[codex] Add toolchain guardrails and docs#95
Merged
cschubiner merged 2 commits intomainfrom Apr 4, 2026
Merged
Conversation
d6aecab to
be35bff
Compare
cschubiner
added a commit
that referenced
this pull request
Apr 16, 2026
* add toolchain guardrails * stabilize snippet picker browser test
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds clearer toolchain guardrails for local development in this clone. We hit a confusing failure mode where repo-level commands like
bun run typecheckwere being launched from a shell that still had Node 20 active, even though the repo already declares Node 24.13.1 in.mise.tomlandpackage.json. In practice that meant debugging would often start with a downstream Astro error insideapps/marketinginstead of a clear explanation that the shell itself was on the wrong runtime.User impact
Before this change, a developer could enter the repo, run a normal root command, and get blocked by a late failure that looked like an app problem rather than an environment problem. That wastes time during debugging and makes the repo feel less predictable, especially when trying to launch the desktop app against real local state or when running repo-wide validation.
Root cause
The repository already had a source of truth for the expected toolchain, but that expectation was not enforced at the command entrypoints and it was barely documented in the README. As a result, the local shell could drift onto an older Node version and the first visible failure would happen much later inside Turbo or Astro.
Fix
This change adds a small fail-fast toolchain check script that reads the expected versions from
.mise.toml, verifies the active Node and Bun versions, and exits with actionable guidance when the shell is wrong. Root-level scripts that commonly trigger confusing failures now call that check first, the README now documents the recommendedmiseworkflow plus the explicitmise execfallback, and an.nvmrcfile was added as a breadcrumb for developers usingnvmor editor integrations that look for it.Validation
I validated both the failure and success paths locally. Under the wrong Node version (
20.20.1),bun run typecheckandbun run start:desktop:main-statenow fail immediately with a direct version mismatch message and concrete remediation steps. Under Node24.13.1, the toolchain check passes and the repo validations complete successfully.Checks run:
bun fmtbun lintbun typechecknode -v && bun run typecheckunder Node20.20.1to verify fail-fast behaviornode -v && bun run start:desktop:main-stateunder Node20.20.1to verify fail-fast behaviorsource ~/.nvm/nvm.sh && nvm use 24.13.1 >/dev/null && node -v && bun run typecheck