fix: bun zero-install breaks every spawned-subprocess command (db/test/seed/typecheck); pin at the spawn layer

[vivek7405]

Problem

A fresh Bun zero-install scaffold cannot set up its database. Reproduced cleanly (fresh bun pm cache rm, shipped cli@0.10.25):

npm create webjs@latest fs -- --runtime bun   # skips install (#691)
cd fs && bun run db:generate
# SyntaxError: Export named 'defineRelations' not found in
#   .../cache/drizzle-orm@0.45.2@@@1/index.js

Bun fetched drizzle-orm@0.45.2 and drizzle-kit@0.31.10 (both the wrong 0.x major), despite the package.json pinning 1.0.0-rc.3. All three templates use Drizzle, so this breaks db setup for every bun zero-install app. The npm/node path works (npm honors the exact pin).

Root cause (see #690 for the full cross-version research)

1. Bun RUNTIME auto-install ignores the package.json version for a bare import. An empty cache resolves to the absolute latest major. Verified across Bun 1.0.0 through 1.4.0-canary. Only an inline EXACT specifier (drizzle-orm@1.0.0-rc.3) is honored; inline ranges and tags ENOENT.
2. feat: pin Bun zero-install deps via an onLoad specifier-rewrite from package.json #685 compensates by rewriting a bare import to inline-exact, but the Bun.plugin runs ONLY in the webjs server process.
3. webjs db <generate|migrate|push|studio> (packages/cli/bin/webjs.js, case 'db') resolves the drizzle-kit bin (resolveBin(cwd, 'drizzle-kit')) and SPAWNS it as a separate bun drizzle-kit subprocess. That subprocess has no feat: pin Bun zero-install deps via an onLoad specifier-rewrite from package.json #685 plugin, so its bare import 'drizzle-orm' (from the schema) hits raw auto-install against an empty cache and gets the wrong major.

The trigger is #691 (skip-install default for bun). Before it, bun create ran bun install, which DOES honor pins, so the db worked. The cli AGENTS.md still says "since webjs create auto-installs", now stale for bun.

Design / approach

Recommended: A. do not default to skip-install for db templates (revert the #691 default, at least when Drizzle is present, which is all three templates). Bun zero-install fundamentally cannot pin a spawned tool's deps, so the skip-install default is unsafe for any app with db tooling. The npm path is unaffected.

Alternatives considered:

• B. Spawn the db tool as bun --preload <pin-registrar> drizzle-kit ... so the feat: pin Bun zero-install deps via an onLoad specifier-rewrite from package.json #685 plugin loads in that process. Incomplete on its own: resolveBin still resolves the WRONG drizzle-kit bin (0.31.10) under an empty cache, which --preload does not fix.
• C. webjs db runs a targeted bun install when node_modules is absent on bun. Works, but it is a per-command install that surprises the user mid-command.

Implementation notes (for the implementing agent)

• Where: resolveCreateInstall() in packages/cli/lib/create.js (the per-runtime install default, bun create defaults to no install (zero-install onboarding); node unchanged #682/feat(cli): bun create skips install by default (zero-install dev); node unchanged #691) and the case 'db' block in packages/cli/bin/webjs.js.
• For option A: make resolveCreateInstall (or the create path) install on bun when the template carries Drizzle, or revert the bun default to install outright. Update the next-steps banner and the "Skipped install" note accordingly.
• Landmine: do NOT rely on the package.json exact pin saving bun zero-install for the db tooling. It does not (raw auto-install ignores package.json, research: respect full package.json (ranges + tree) under Bun zero-install (default auto-install) #690). The pin only helps the server via feat: pin Bun zero-install deps via an onLoad specifier-rewrite from package.json #685.
• Docs to resync: agent-docs/runtime.md (the zero-install section), docs/app/docs/runtime/page.ts, AGENTS.md scaffolding line, the scaffold templates/AGENTS.md, and packages/cli/AGENTS.md (the stale "webjs create auto-installs" note).
• Tests: a scaffold test that a fresh bun db app can run db:generate (or that bun create installs for a db template). Counterfactual: it fails if skip-install is restored for a db template.

Acceptance criteria

• A fresh bun create webjs (full-stack / api / saas) can run db:generate + db:migrate and boot with a working DB.
• The npm/node path is unchanged.
• A test proves the db-tooling path works on bun (with the counterfactual).
• Docs resynced; the stale "auto-installs" note fixed.
• Cross-references research: respect full package.json (ranges + tree) under Bun zero-install (default auto-install) #690 (research), feat: pin Bun zero-install deps via an onLoad specifier-rewrite from package.json #685 (pin rewrite), feat(cli): bun create skips install by default (zero-install dev); node unchanged #691 (skip-install default), feat(cli): exact-pin scaffold deps so npm and bun resolve identical versions #693 (exact pins), bun create defaults to no install (zero-install onboarding); node unchanged #682.
• Decide whether cli needs a 0.10.26 hotfix (the released 0.10.25 ships the broken bun default).

[vivek7405]

Upstream root cause is a confirmed open Bun bug: oven-sh/bun#21832 (confirmed bug, runtime; Linear ENG-20057) "auto-install does not respect version resolution order and always resolve to latest", plus oven-sh/bun#21030 and #11037. The Bun-prescribed workaround in #21832 (inline pkg@version specifier) is exactly what #685 does in the server process; the gap here is the spawned drizzle-kit subprocess not getting that rewrite. Full cross-version research + upstream links in #690.

[vivek7405]

Preferred fix is option B (verified feasible): reuse #685 in the db subprocess

Confirmed empirically: bun --preload <registrar> that registers the #685 Bun.plugin onLoad DOES rewrite a spawned process's bare imports to inline-exact. Test: a preload rewriting import 'zod' to zod@3.22.4 made the spawned bun app.ts fetch zod@3.22.4 (the pin), not zod@4.4.3 (latest). Cache confirmed.

So webjs db <generate|migrate|push|studio> on Bun should spawn drizzle-kit as bun --preload <pin-registrar> <drizzle-kit-bin> <cmd>, where the registrar registers the same pin transform (registerSeedHooks with pinEnabled, or a thin module that installs installBunSeedPlugin with buildBunPinTransform(appDir)). drizzle-kit's bare import 'drizzle-orm' from the schema then resolves the pinned 1.0.0-rc.3.

This keeps the #691 zero-install default (no revert) and makes db tooling consistent with the server. Preferred over option A.

Remaining sub-detail

resolveBin(cwd, 'drizzle-kit') (packages/cli/lib/resolve-bin.js) resolves the drizzle-kit BIN itself to the wrong major (0.31.10) under an empty cache, because that bare resolution happens in the PARENT process before the spawn (the preload only affects the spawned process's onLoad). So the fix must also pin the bin version: resolve drizzle-kit@<package.json pin> explicitly (construct the cache path or seed it), not a bare drizzle-kit. Both drizzle-orm (via preload) and drizzle-kit (via bin pin) must land on 1.0.0-rc.3.

Where

• packages/cli/bin/webjs.js case 'db': branch on Bun, add --preload + the pinned bin.
• packages/cli/lib/resolve-bin.js: pin the bin version on Bun zero-install.
• A small registrar module (in @webjsdev/server or cli) that installs the pin plugin, suitable for bun --preload.
• Cross-runtime test: a fresh bun zero-install scaffold runs db:generate + db:migrate and resolves drizzle at 1.0.0-rc.3.

Source-of-truth root cause and the cross-version proof are in #690.

[vivek7405]

Scope broadened: this is a spawn-layer issue, not just webjs db

Audited every subprocess spawn in the cli (packages/cli/bin/webjs.js + lib/). Each spawns process.execPath (bun under a bun app) with a tool or file that loads app code/deps, so each hits the same bare-import-resolves-latest bug under zero-install:

Command	Spawns	Affected
webjs db generate/migrate/push/studio	drizzle-kit (schema -> drizzle-orm)	Yes
webjs db seed (webjs.js:212)	bun seed.server.ts -> drizzle	Yes
webjs test --server (:324)	bun test <files> -> app + deps	Yes
webjs test --browser (:355)	wtr -> app + deps + axe	Yes (+ wrong wtr bin)
webjs typecheck (:485)	tsc -> @types	Likely
webjs.dev.before/.parallel (run-tasks.js)	user tasks	Yes if bun-loaded
webjs dev/start (:176)	the server	No (server self-registers #685)

Fix at the spawn layer (future-proof)

Add ONE shared bun-aware spawn helper that, on bun + no node_modules, prepends --preload <pin-registrar> (verified #685 mechanism) and pins any resolveBin'd tool to its package.json-exact version. Route db / db seed / test / typecheck / run-tasks through it. Every current AND future bun-loaded subprocess command is then covered by construction, with no per-command work as the CLI grows.

Caveats

• run-tasks uses shell: true; the preload only applies to bun-launched tools, not an arbitrary PATH binary. Doc + a bun-aware task form covers user tasks.
• tsc resolves types not runtime deps (lower risk) but uses the same helper.
• The resolveBin bin-version pin is required regardless (the parent resolves the bin before the spawn; the preload only affects the child's onLoad).

Where

• New: a shared spawn helper (e.g. packages/cli/lib/spawn-tool.js) + a preload registrar module that installs the feat: pin Bun zero-install deps via an onLoad specifier-rewrite from package.json #685 pin plugin.
• Edit: the spawn sites in packages/cli/bin/webjs.js (db, db seed, test, typecheck) and packages/cli/lib/run-tasks.js; resolve-bin.js for the bin-version pin.
• Test: a fresh bun zero-install scaffold runs db:generate, db:migrate, AND test:server resolving drizzle/deps at the pinned versions.

[vivek7405]

Sync with #698 (range pinning + zero-install gate): one root-cause claim is now stale, the core problem stands

#698 (the in-process pin now forwards inline-safe ranges, and is gated on true zero-install) changes two things this issue assumed, so updating rather than re-filing:

1. STALE: root cause point 1 says "Only an inline EXACT specifier is honored; inline ranges and tags ENOENT." That is wrong for ranges. Verified on Bun 1.3.14, an inline range resolves the standard way (zod@^3.20.0 picks the highest 3.x; lodash.camelcase@^4.0.0 fresh-fetches 4.3.0). Only dist-tags (name@next) are flaky inline. So #685 now forwards ranges too, not just exact.

2. UNCHANGED, and this is the point: none of that helps a SPAWNED subprocess. The #685 onLoad plugin runs only in the webjs server process. webjs db / seed spawn drizzle-kit / the seed script as separate Bun processes with no plugin, so their bare import 'drizzle-orm' still hits raw auto-install. The range-vs-exact detail is irrelevant there because the rewrite never runs in that process at all. So the core break (and option A, install for db templates) is exactly as filed.

3. New interaction to fold into the fix: feat: forward inline-safe ranges in the bun zero-install pin rewrite #698 added a node_modules gate to the in-process pin (buildBunPinTransform returns null when node_modules exists). That is consistent with option A here: if a db template stops skipping install, node_modules exists, the in-process pin correctly no-ops, and Bun resolves everything (server AND spawned tools) from the installed tree. So option A fixes both layers at once.

Scope check on the title's command list, under bun zero-install (no node_modules):

• db (generate/migrate/push) and seed: BREAK (spawn a tool that imports drizzle, wrong major). The concrete repro here.
• test / check / typecheck: per the runtime docs these run on NODE even for a Bun app, and Node has NO auto-install, so they fail to resolve @webjsdev/* without an install regardless. Same conclusion (zero-install + spawned/Node tooling needs an install), so option A (install for templates with tooling) covers them too.

Net: keep this open as the tracking issue. The fix is still option A (do not skip-install for templates that carry db/test tooling), now also justified by the #698 gate. No re-file needed; I corrected the one stale claim here.

[vivek7405]

Closing as superseded by the documented zero-install limitation

After #698 (range pinning) and #700 (scaffold ranges, drizzle kept exact), the spawn-layer story is clearer, and I am closing this in favor of the documented resolution rather than an in-process spawn-pin.

The fact this rests on is real and unchanged: the #685 onLoad pin runs only in the webjs server process, so a SPAWNED tool (drizzle-kit under webjs db, the test runner, tsc) never gets it and resolves its own bare imports raw. But neither proposed fix is clean: option A (force-install for db templates) undoes the #682 zero-install onboarding, and option B (preload + spawn) still resolves the wrong tool bin under an empty cache (this issue's own analysis).

So the accepted resolution is the simpler one: bun zero-install cannot pin a spawned tool's deps in-process, so the db / test / typecheck tooling needs a real install. That is already the documented guidance (the scaffold next-steps banner and the runtime docs point at bun install for tooling, and the prod Dockerfile runs it). The zero-install path stays for bun run dev / start (the server, which IS pinned via the onLoad rewrite).

If the fresh-app bun run db:generate failure proves to be a real onboarding pain, the right follow-up is a friendly error in webjs db (detect no node_modules on bun and tell the user to bun install), not a spawn-layer version pin. Re-file if that surfaces.