dogfood: bun zero-install bun run dev fails, cli can't resolve @webjsdev/server

[vivek7405]

Problem

A fresh Bun zero-install scaffold cannot start the dev server. Reproduced live with the just-released cli@0.10.26:

bun add -g webjsdev          # webjsdev@0.10.26
bun create webjs my-app      # scaffolds fine, skips install (zero-install)
cd my-app && bun run dev
# $ bun --bun webjs-bun.mjs dev
# error: ENOENT while resolving package '@webjsdev/server' from
#   '/home/vivek/.bun/install/cache/@webjsdev/cli@0.10.26@@@1/bin/webjs.js'
# error: script "dev" exited with code 1

So bun run dev (the most basic command) is broken for a fresh bun zero-install app. bun create worked; the dev server does not.

Root cause (grounded)

• bun run dev runs bun --bun webjs-bun.mjs dev, which loads the CLI from the global cache (~/.bun/install/cache/@webjsdev/cli@0.10.26/bin/webjs.js).
• webjs.js does a BARE await import('@webjsdev/server') (around L124, L132); the cli's package.json declares @webjsdev/server: ^0.8.0 (a caret RANGE; also @webjsdev/mcp: ^0.1.0, @webjsdev/ui: ^0.3.1).
• Under Bun zero-install, a BARE import does NOT honor package.json (the feat: forward inline-safe ranges in the bun zero-install pin rewrite #698 finding), so the ^0.8.0 range is ignored. The global cache even holds @webjsdev/server@0.8.36 (which satisfies ^0.8.0), but bun does not use it for the cli's bare import and does not fetch @webjsdev/server (0.8.37 is published), so it ENOENTs.
• This is the BOOTSTRAP-layer cousin of Make webjs db/test/typecheck work under bun zero-install (auto-install, no bun install) #704 (spawn layer) and fix: bun zero-install breaks every spawned-subprocess command (db/test/seed/typecheck); pin at the spawn layer #695: the CLI's own bare @webjsdev/* imports cannot be pinned by the feat: pin Bun zero-install deps via an onLoad specifier-rewrite from package.json #685 onLoad rewrite, because that onLoad lives INSIDE @webjsdev/server (chicken-and-egg: you cannot pin the import of the very package that hosts the pinner). Likely pre-existing (the cli's dep ranges are unchanged by the recent releases), not a regression from feat: forward inline-safe ranges in the bun zero-install pin rewrite #698/Revert scaffold @webjsdev/* + drizzle exact pins to semver ranges (after #698) #700.

Design / approach (candidates, verify empirically)

The bootstrap must resolve the CLI + its @webjsdev/* deps to concrete versions before any in-process onLoad can help.

1. Pin the bootstrap chain at generation time. The generated webjs-bun.mjs imports the CLI (and the cli reaches the server) via INLINE-versioned specifiers, so bun auto-install fetches the pinned versions. The cli's bare import('@webjsdev/server') is the hard part: have the cli read its own pinned server version and import('@webjsdev/server@<v>'), or rewrite it as a published-artifact transform.
2. A bunfig.toml preload (see Make webjs db/test/typecheck work under bun zero-install (auto-install, no bun install) #704's verified bun-pin-preload.js) shipped by the scaffold that rewrites the cli's + bootstrap's bare @webjsdev/* imports to pinned inline specifiers. Verify it loads early enough to catch the cli's import.
3. Make the cli resolve @webjsdev/server via import.meta.resolve against a version it pins internally.

First task: reproduce reliably and determine whether the bare @webjsdev/server auto-install ENOENTs because of (a) the range-ignored-then-latest path, (b) a nested-cache auto-install limitation (a cached package's bare import not triggering project-relative auto-install), or (c) transient fetch flakiness. The fix differs per cause.

Implementation notes (for the implementing agent)

• Where: packages/cli/lib/create.js (the generated webjs-bun.mjs bootstrap + scaffold bunfig), packages/cli/bin/webjs.js (the bare await import('@webjsdev/server')), and reuse packages/server/src/bun-pin-preload.js / bun-pin-rewrite.js (Make webjs db/test/typecheck work under bun zero-install (auto-install, no bun install) #704).
• Landmine: the onLoad pin (feat: pin Bun zero-install deps via an onLoad specifier-rewrite from package.json #685) cannot fix the import of @webjsdev/server itself; the fix has to live in the bootstrap, before the server module loads.
• Tests: a real fresh bun create ... && bun run dev boot (no install) that reaches a 200, plus a counterfactual. Bun-only path.
• Docs: agent-docs/runtime.md, docs site, packages/cli/AGENTS.md.

Acceptance criteria

• A fresh bun create ... && bun run dev serves a 200 with NO bun install.
• The cli + server resolve to the intended versions (not absolute latest, not ENOENT).
• Counterfactual test + docs synced.

Relates to #704, #695, #698, #669. Likely should be prioritized above #704 (it breaks the basic dev path).

[vivek7405]

Root cause confirmed + a proven fix direction (verification-first)

Reproduced and narrowed it down. It is NOT a nested-cache limitation and NOT a range-resolution bug. It is the fetch:

• With @webjsdev/server already in the cache, both the bare import('@webjsdev/server') from a project declaring ^0.8.0 AND the inline-exact import('@webjsdev/server@0.8.37') resolve and load fine (126 exports).
• The failure happens only when the server is NOT cached: the cli's bare import('@webjsdev/server') ignores the cli's ^0.8.0 range (the feat: forward inline-safe ranges in the bun zero-install pin rewrite #698 bare-import-ignores-package.json behaviour), goes for latest, and bun's runtime auto-install fetch of that latest flakes/fails -> ENOENT. The cached satisfying 0.8.36 is never considered (range ignored), and 0.8.37 (just published) was not yet fetched.
• @webjsdev/server is small (2 deps: @webjsdev/core, ws); bun add @webjsdev/server@0.8.37 fetches it reliably. So it is the runtime-auto-install fetch path that is unreliable, the same gap as nanoid/zod earlier in this work.

Proven fix: make the cli import @webjsdev/server (and its other @webjsdev/*) via an INLINE-EXACT specifier, not bare. import('@webjsdev/server@0.8.37') resolved cleanly in the repro. Two parts:

1. EXACT-pin the cli's own @webjsdev/* deps in packages/cli/package.json at release time (the cli is the bootstrap, so it must pin, the opposite of Revert scaffold @webjsdev/* + drizzle exact pins to semver ranges (after #698) #700's idiomatic ranges for an app). The cli then knows the exact version it shipped with.
2. In packages/cli/bin/webjs.js, a small serverSpecifier() helper: return bare @webjsdev/server when node_modules resolves it (Node, installed apps), else @webjsdev/server@<exact-from-own-package.json> under Bun zero-install. Replace the bare await import('@webjsdev/server') sites (L124 assertNodeVersion, L132 startServer, and the others).

This is simpler than the bunfig-preload candidate in the issue body: the cli pins its OWN imports, no preload needed for the bootstrap. The app's own vendor deps are still handled by #698/#704. The remaining open item is the same fetch-reliability caveat (a fresh exact fetch is far more reliable than the bare-latest fetch, but still bun's auto-install path).