feat(config): add "auto" devbox_version policy to switch versions

[mikeland73]

Summary

Stacked on #2990, which adds devbox_version. Merge that first.

Adds an auto policy that switches to the pinned devbox version:

"devbox_version": {"version": "0.18.4", "on_mismatch": "auto"}

• How switching works: when the running devbox doesn't match, it re-runs the same command through the devbox launcher ($LAUNCHER_PATH) with DEVBOX_USE_VERSION set to the pinned version.
• The existing launcher already downloads, checksum-verifies and runs any release named by DEVBOX_USE_VERSION, so the launcher needs no changes.
• Download progress goes to stderr, so shellenv and direnv output stays clean.
• Exact versions only: auto requires an exact version; a range with auto is a config error. DEVBOX_VERSION_POLICY=auto with a range fails like error.
• A DEVBOX_USE_VERSION set by the user wins: devbox warns instead of switching.
• Loop guard: __DEVBOX_AUTO_VERSION marks a version that auto chose. That lets a nested shell switch again for a different project, and makes devbox fail instead of looping if the launcher doesn't switch.
• Without a launcher (for example Nix or Homebrew installs), auto fails with install instructions.
• Inheritance: DEVBOX_USE_VERSION carries into devbox shell, so nested devbox commands stay on the pinned version.

How was it tested?

• Unit tests with a mocked exec cover: switching, replacing existing env values, switching again for a different project, no launcher, the loop guard, a user-set version winning, and the env override with a range.
• testscripts/version/devbox_version_auto.test.txt uses a fake launcher script to check that the same command is re-run with DEVBOX_USE_VERSION set. It also covers the no-launcher error, a user-set version winning, and rejecting ranges.
• Manual end-to-end run with the real launcher (v0.2.2): a binary built as 0.17.1, run in a project pinned to 0.18.4 with auto, ran devbox run under 0.18.4. Inside the script, devbox version printed 0.18.4 and DEVBOX_USE_VERSION=0.18.4.
• go test ./internal/... and devbox run lint pass.

Community Contribution License

All community contributions in this pull request are licensed to the project
maintainers under the terms of the
Apache 2 License.

By creating this pull request, I represent that I have the right to license the
contributions to the project maintainers under the Apache 2 License as stated in
the
Community Contribution License.

🤖 Generated with Claude Code

[mikeland73]

@claude ptal

[claude]

Claude finished @mikeland73's task in 2m 14s —— View job

---

Reviewing PR #2991

• Gather context (read CLAUDE.md, diff, changed files)
• Understand the request (code review requested via "ptal")
• Review internal/vercheck/project.go changes
• Review internal/devconfig/configfile/devbox_version.go changes
• Review test coverage
• Post review feedback

Review

I read through internal/vercheck/project.go, internal/devconfig/configfile/devbox_version.go, both test files, the testscript, and the schema diff (against origin/mikeland73/devbox-version-constraint). This is a clean, well-scoped implementation — I didn't find any bugs. Notes below are mostly confirmations of things I checked, plus a couple of minor observations.

Correctness checks I traced through and confirm are right:

• internal/vercheck/project.go:96-103 — the "user-set version wins" check correctly distinguishes a user-set DEVBOX_USE_VERSION from one auto itself set, by comparing against __DEVBOX_AUTO_VERSION. Covered by the user_set_version_wins test.
• internal/vercheck/project.go:105-110 — the loop guard (autoVersion == target → error) correctly fires only when we previously tried switching to exactly this target and are still mismatched after re-exec, rather than on every switch. The "different project" case (nested shell re-switching to a different pinned version) is correctly allowed through, per the switches_again_for_a_different_project test.
• internal/devconfig/configfile/devbox_version.go:126-133 — auto + range is rejected at config-validation time, and switchVersion (project.go:86-94) independently re-checks ExactVersion() to cover the DEVBOX_VERSION_POLICY=auto env-override path, which bypasses static validation. Both are tested (env_override_with_range, plus the config validation table).
• args := append([]string{launcher}, os.Args[1:]...) (project.go:126) — no backing-array aliasing issue since the literal slice's cap forces a new allocation.
• syscall.Exec (project.go:12,34) — devbox only ships linux/darwin builds per .goreleaser.yaml, so this is safe; not an issue for a Windows target that doesn't exist.
• Test coverage is thorough: unit tests mock execFunc and cover switching, env replacement (not duplication), re-switching for a different project, no-launcher, the loop guard, user-override, and the range env-override error. The testscript exercises the same behaviors end-to-end through a fake launcher script, consistent with the existing devbox_version.test.txt style.

Minor observations (non-blocking):

• internal/vercheck/project.go:127 — on execFunc failure the function returns a wrapped usererr; worth double-checking in practice that syscall.Exec failures (e.g. launcher not executable, ENOENT) produce a readable message via usererr.WithUserMessage, but I didn't find anything wrong with the wrapping itself.
• I wasn't able to run go build/go test/git fetch in this sandboxed environment (those commands required approval that wasn't available here), so I verified everything by reading the diff and tests rather than executing them. The PR description states go test ./internal/... and devbox run lint already pass, and the tests I read look correct and would need to pass to compile as written.

No changes requested — this looks ready to merge from a correctness standpoint.
· Branch: mikeland73/devbox-version-auto