Zero-install dev/start on Bun via native auto-install (carve from #669)

[vivek7405]

Problem

Bun resolves bare npm specifiers on the fly when no node_modules is present (auto-install, the Bun analog of Deno 2's npm: resolution but with no prefix). Verified on Bun 1.3.14: bun --bun running a script that does import { html } from '@webjsdev/core' (and a second importing drizzle-orm) auto-installs both from npm and runs, with no node_modules. Built-in SQLite (#670) needs no install. So webjs's pure-JS packages are auto-install-compatible, and a zero-install dev/start on Bun should be reachable.

It does NOT work end to end today because the CLI runs the SERVER on Node, so the app's imports hit Node resolution (which has no auto-install) and fail. Reproduced: bunx @webjsdev/cli@latest start on a no-node_modules app booted the server, but the page render threw ERR_MODULE_NOT_FOUND: @webjsdev/core with a node:internal/modules/esm stack. The CLI spawned the server child via spawn(process.execPath, ...) (the hot-reload supervisor), which is Node. The scaffold's bun --bun webjs start does force Bun, but relies on the webjs bin already being in node_modules/.bin, so it is not zero-install either.

This is the Bun half of #669, carved out because it is reachable with a small launcher change rather than the full resolve-hook (Node still needs that hook, so it stays in #669).

Design / approach

When invoked under Bun (process.versions.bun set), run the SERVER genuinely on Bun so the app's imports (and @webjsdev/*) flow through Bun auto-install, instead of spawning a Node child via process.execPath. The hot-reload supervisor already branches node --watch vs bun --hot (#514), so the seam exists; the gap is the zero-install bootstrap (bunx @webjsdev/cli ... must end up running the server on Bun, not Node, and must not require the webjs bin to pre-exist in node_modules).

Scope to BUN ONLY. Node has no native auto-install (only npx for bin tools and experimental URL-only network imports), so #669's module.register resolve-hook remains the Node mechanism and stays in #669. jspm/client behavior is unchanged (owner constraint).

Implementation notes (for the implementing agent)

• Where to edit: packages/cli/bin/webjs.js (the launch path, the hot-reload supervisor that spawns process.execPath around L156-176, and the dev/start command handling). The scaffold scripts in packages/cli/lib/create.js (~L331-332, bun --bun webjs dev / bun --bun webjs start) may also need a zero-install variant or doc.
• The fix is making the server RUN on Bun under a bunx @webjsdev/cli invocation: re-exec / run in-process under Bun rather than spawning Node. Confirm the in-process (--no-hot) path already runs on the current runtime (it should), and that the supervised (bun --hot) path keeps the child on Bun.
• Landmines: keep the Node path EXACTLY as-is (Bun-only change). The .server.{js,ts} boundary + the import-graph auth gate must stay intact (zero-install must not change what is servable). Auto-installed deps live in Bun's global cache, NOT node_modules, so anything that reads node_modules for versions degrades: locatePackageDir (packages/server/src/dev.js ~L2436) and getPackageVersion (packages/server/src/vendor.js ~L253) already return null gracefully on a miss, so the importmap falls back to a latest jspm pin rather than crashing. That is the Zero-install dev: no install command, transparent resolution (Node+Bun) #669 reproducibility tradeoff (the anchor shifts from a per-app lockfile to bun.lock plus the pin file); document it.
• Prove on a REAL scaffolded app that pins published @webjsdev/*, NOT the monorepo workspace (the workspace resolves @webjsdev/* to local packages and bypasses auto-install, so it cannot test this).
• Invariants: no-build model (Support both Bun and Node runtimes (first-class create + run) #508); the server-only boundary + auth gate; runtime parity (the Node path is untouched).

Acceptance criteria

• A freshly scaffolded app with NO node_modules, served via bunx @webjsdev/cli dev and start on Bun, renders its pages (the @webjsdev/core import resolves via auto-install, no ERR_MODULE_NOT_FOUND).
• webjs db migrate works under auto-install on Bun (drizzle-kit auto-installs; confirm the migrate run path).
• The client importmap / jspm path still works without node_modules (falls back to a latest pin gracefully); jspm behavior is otherwise unchanged.
• The Node path is unchanged (no regression to webjs dev / start on Node).
• A test proves a no-node_modules app serves on Bun (a test/bun or scaffold test that removes node_modules then boots), with a counterfactual where applicable.
• Docs updated (a "zero-install on Bun" note in the deployment / getting-started docs-site pages + the scaffold Bun docs + agent-docs), including the reproducibility tradeoff.

[vivek7405]

Hard requirement: demand-driven (lazy) resolution, NOT an eager bulk install at startup

The point of this is TRUE on-the-fly resolution (fetch a dependency the first time its import is actually reached, cached after), not moving a bulk bun install from build time to server-startup time. Verified that Bun's auto-install is genuinely demand-driven, so this is achievable, but ONLY via the right entry mechanism:

• Proof: a package.json listing lodash plus a BOGUS unimported dep (this-pkg-does-not-exist-zzz-9999), with a script importing ONLY lodash, run via bun --bun script.ts (no node_modules): it ran fine and never tried to fetch the bogus dep. An eager full install would have failed on it. So bun --bun <entry> auto-install fetches only what is actually imported, when imported.

• TRAP to avoid: bunx @webjsdev/cli is EAGER. In the earlier boot test it printed "Resolved, downloaded and extracted [48]", i.e. bunx installs the CLI's entire declared dependency tree up front before running. Bootstrapping the server through bunx @webjsdev/cli would therefore reintroduce exactly the eager-bulk-install this issue exists to avoid. The implementation MUST run the server through Bun's demand-driven auto-install path (bun --bun <server-entry>), not bunx-the-cli.

Realistic shape on webjs (all cached once per machine):

• Framework set (@webjsdev/server, core, and their runtime deps) is fetched at server BOOT, because the server imports them to run. That is a fixed set, not the whole dependency universe.
• App/route-specific deps are fetched when that route's module FIRST loads. webjs walks/loads route modules lazily on first request, so a dep used only by /reports is fetched when /reports is first hit, not at boot.
• Unimported deps are never fetched.
• Granularity caveat: it is per-PACKAGE lazy (a package plus its transitive subtree on first import), not per-individual-module-file streaming.

Add to acceptance criteria:

• A dep imported by only ONE route is NOT fetched at server boot; it is fetched on the first request to that route (prove with a route-specific dep and a cache/probe check).
• An unimported dep present in package.json is never fetched.
• The server is NOT bootstrapped via bunx @webjsdev/cli (eager full-tree install); it runs through bun --bun demand-driven auto-install.

[vivek7405]

UX target: the three commands stay identical; bun install is demoted from required to optional

The user-facing flow must NOT change. After this lands:

bun create webjs@latest my-app
cd my-app
# no `bun install` step needed
bun run dev      # dev server on Bun, deps resolved on demand
bun run start    # prod server on Bun, deps resolved on demand

• bun run dev and bun run start are the SAME commands as today. What changes is the package.json dev/start SCRIPTS behind them: they move from bun --bun webjs dev (which needs the webjs bin in node_modules/.bin) to a zero-install-capable form that runs the server on Bun via demand-driven auto-install. A tiny shipped bootstrap that bun --bun runs and imports the framework by bare specifier is the likely shape; do NOT use bunx @webjsdev/cli (eager full-tree install).
• bun install becomes OPTIONAL, not forbidden: with it, auto-install finds deps locally; without it, they are fetched on demand. Same runtime behavior. Reasons a user would still run it: editor IntelliSense/types (no node_modules means the editor has no local type files), and a pinned/offline-reproducible install.
• --bun exists because webjs is a Node-shebang bin and Bun respects shebangs by default (so a plain webjs dev runs on Node). --bun overrides the shebang to run on Bun. It stays internal to the scripts; the user never types it.
• Accept a one-time first-request latency: a route's unique deps are fetched the first time that route is hit (cached after).

Add to acceptance criteria:

• bun create then bun run dev / bun run start with NO bun install serves the app (the three commands are unchanged from today).
• Running bun install first still works identically (install is optional, not required or forbidden).
• The generated package.json dev/start scripts do not depend on the webjs bin pre-existing in node_modules.

[vivek7405]

Progress: core mechanism de-risked; dev-hot supervisor is the remaining risk

Workspace: branch feat/zero-install-bun (worktree), card In progress. Empirically validated on Bun 1.3.14 with NO node_modules (a minimal app pinning published @webjsdev/*):

• bun --bun <boot>.mjs start (boot = await import('@webjsdev/cli/bin/webjs.js')): server ready ON Bun, page renders (the app's @webjsdev/core import resolves via demand-driven auto-install), and NO local node_modules is created (pure global cache). So start works zero-install.
• bun --bun <boot>.mjs dev --no-hot: also serves zero-install on Bun.
• bun --bun <boot>.mjs dev (default, hot supervisor): did NOT come up in the test (empty log). The webjs dev path spawns spawn(process.execPath, plan.args) with bun --hot (Dev hot-reload of server-side modules is stale on Bun (query cache-bust ignored) #514); re-execing that under the bootstrap needs work. This is the riskiest remaining piece (and it is the DEFAULT bun run dev).

Why the CLI-on-Bun framing is the whole fix: webjs start runs the server IN-PROCESS, and webjs dev re-execs via process.execPath (which is bun when the CLI runs on Bun), so the server stays on Bun automatically AS LONG AS the CLI itself runs on Bun. The only gap is getting the CLI onto Bun without node_modules. bunx @webjsdev/cli runs it on Node (the bin shebang) AND eager-installs; the app-local bootstrap avoids both.

Design decisions:

• An APP-LOCAL bootstrap file is required (not an inline bun -e): with -e, a trailing start/dev lands in the script-name argv slot, so the CLI's process.argv.slice(2) misses it. A bootstrap file (bun --bun boot.mjs start) passes args through cleanly. The bootstrap must be app-local so it is resolvable with no node_modules (its import('@webjsdev/cli/...') is what auto-installs the CLI).
• The CLI has no exports field, so @webjsdev/cli/bin/webjs.js is importable by path, and it auto-runs main() on import.

Remaining to finish #675:

1. dev-hot supervisor: make bun --hot re-exec work under the bootstrap (or run dev in-process on Bun by default when zero-install). The default bun run dev must work.
2. webjs db migrate under auto-install on Bun (drizzle-kit auto-install).
3. Finalize the scaffold: emit the bootstrap file + point the Bun dev/start scripts at it; keep bun install optional and the Node path unchanged.
4. Tests on a REAL published-deps scaffold (network), plus the no-node_modules serve proof.
5. Docs (deployment / getting-started + scaffold Bun docs + agent-docs), including the reproducibility tradeoff.