Skip to content

[codex] Add toolchain guardrails and docs#95

Merged
cschubiner merged 2 commits intomainfrom
codex/toolchain-guardrails
Apr 4, 2026
Merged

[codex] Add toolchain guardrails and docs#95
cschubiner merged 2 commits intomainfrom
codex/toolchain-guardrails

Conversation

@cschubiner
Copy link
Copy Markdown
Owner

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 typecheck were being launched from a shell that still had Node 20 active, even though the repo already declares Node 24.13.1 in .mise.toml and package.json. In practice that meant debugging would often start with a downstream Astro error inside apps/marketing instead 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 recommended mise workflow plus the explicit mise exec fallback, and an .nvmrc file was added as a breadcrumb for developers using nvm or 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 typecheck and bun run start:desktop:main-state now fail immediately with a direct version mismatch message and concrete remediation steps. Under Node 24.13.1, the toolchain check passes and the repo validations complete successfully.

Checks run:

  • bun fmt
  • bun lint
  • bun typecheck
  • node -v && bun run typecheck under Node 20.20.1 to verify fail-fast behavior
  • node -v && bun run start:desktop:main-state under Node 20.20.1 to verify fail-fast behavior
  • source ~/.nvm/nvm.sh && nvm use 24.13.1 >/dev/null && node -v && bun run typecheck

@github-actions github-actions Bot added size:L vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. labels Apr 4, 2026
@cschubiner cschubiner marked this pull request as ready for review April 4, 2026 06:18
@cschubiner cschubiner force-pushed the codex/toolchain-guardrails branch from d6aecab to be35bff Compare April 4, 2026 06:20
@cschubiner cschubiner merged commit 3d35be2 into main Apr 4, 2026
7 checks passed
@cschubiner cschubiner deleted the codex/toolchain-guardrails branch April 4, 2026 09:08
cschubiner added a commit that referenced this pull request Apr 16, 2026
* add toolchain guardrails

* stabilize snippet picker browser test
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:L vouch:trusted PR author is trusted by repo permissions or the VOUCHED list.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant