@webjsdev/cli 0.10.23 → 0.10.25

package/README.md

@@ -33,7 +33,7 @@ npx @webjsdev/cli create my-app
 cd my-app && npm run dev
 ```
 
-Both `webjs create` and `create-webjs-app` auto-install dependencies in the new directory using your detected package manager (npm / pnpm / yarn / bun). Pass `--no-install` to opt out.
+`webjs create` installs dependencies in the new directory by default on **Node** (it needs `node_modules` to run). On **Bun** it **skips** the install (zero-install: `bun run dev` resolves deps on the fly). Pass `--install` to force the install, or `--no-install` to skip it, on either runtime.
 
 ## Commands
 

package/bin/webjs.js

@@ -50,12 +50,12 @@ const USAGE = `webjs commands:
   webjs doctor                                    Verify project health (Node, tsconfig, env, vendor pins, importmap coherence, @webjsdev versions, git hook, page/layout elision)
   webjs types                                     Generate .webjs/routes.d.ts (typed Route union + per-route params)
   webjs typecheck [tsc args...]                   Type-check the app with the project's tsc --noEmit (non-zero on errors)
-  webjs create <name> [--template full-stack|api|saas] [--db sqlite|postgres] [--runtime node|bun] [--no-install]  Scaffold a new webjs app
+  webjs create <name> [--template full-stack|api|saas] [--db sqlite|postgres] [--runtime node|bun] [--install|--no-install]  Scaffold a new webjs app
                                                   (only 3 templates exist. default: full-stack, Drizzle, --db sqlite, --runtime node)
                                                   --runtime bun emits a Bun-flavored app (bun.lock, bun Dockerfile/CI, bun docs);
                                                   also auto-detected when run via "bun create webjs".
-                                                  Auto-runs the detected package manager's install in the new dir
-                                                  unless --no-install is passed.
+                                                  Install default is per runtime: Node installs; Bun skips (zero-install,
+                                                  "bun run dev" resolves deps on the fly). --install / --no-install override.
   webjs db generate                               Generate a SQL migration from the schema (drizzle-kit generate)
   webjs db migrate                                Apply pending migrations (drizzle-kit migrate)
   webjs db push                                   Push the schema straight to the dev DB (drizzle-kit push)
@@ -521,7 +521,11 @@ files.
 Full docs: https://docs.webjs.com`);
         process.exit(1);
       }
+      // Install policy (#682). Default per runtime: Node installs (needs
+      // node_modules to run); Bun skips (zero-install, `bun run dev` resolves
+      // on the fly). `--install` / `--no-install` override either way.
       const noInstall = rest.includes('--no-install');
+      const explicitInstall = rest.includes('--install');
       // --db picks the database dialect: sqlite (default) or postgres.
       const db = flag(rest, '--db', 'sqlite');
       // --runtime picks the target runtime: node (default) or bun. Orthogonal
@@ -532,8 +536,9 @@ Full docs: https://docs.webjs.com`);
         console.error(`Error: unknown --runtime '${runtime}'. Only node / bun are supported.`);
         process.exit(1);
       }
-      const { scaffoldApp } = await import('../lib/create.js');
-      await scaffoldApp(name, process.cwd(), { template, db, runtime, install: !noInstall });
+      const { scaffoldApp, resolveCreateInstall } = await import('../lib/create.js');
+      const install = resolveCreateInstall({ runtime, explicitInstall, noInstall });
+      await scaffoldApp(name, process.cwd(), { template, db, runtime, install });
       break;
     }
     case 'vendor': {

package/lib/create.js

@@ -14,7 +14,7 @@
 import { mkdir, writeFile, readFile, cp } from 'node:fs/promises';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import { bunifyProse, bunifyDockerfile, bunifyCompose, bunifyCi } from './runtime-rewrite.js';
@@ -35,6 +35,68 @@ function detectPackageManager() {
   return 'npm';
 }
 
+/**
+ * Decide whether `webjs create` runs the post-scaffold install, per target
+ * runtime (#682). Node installs by default (it needs `node_modules` to run);
+ * Bun SKIPS by default (zero-install: `bun run dev` resolves deps on the fly,
+ * #675). Under Bun zero-install deps resolve to their LATEST version (ranges
+ * and any lockfile are ignored at runtime, #690), so `bun install` is the path
+ * to pinned, reproducible versions. Explicit flags win: `--install` forces it
+ * on, `--no-install` forces it off. The CLI entry points call this and pass an
+ * explicit boolean to `scaffoldApp`, so the library default (no install unless
+ * `install: true`) is unchanged for programmatic callers.
+ *
+ * @param {{ runtime?: string, explicitInstall?: boolean, noInstall?: boolean }} [o]
+ * @returns {boolean}
+ */
+export function resolveCreateInstall({ runtime, explicitInstall, noInstall } = {}) {
+  if (explicitInstall) return true;
+  if (noInstall) return false;
+  const isBun = runtime === 'bun' || (!runtime && detectPackageManager() === 'bun');
+  return !isBun;
+}
+
+/**
+ * Read the EXACT version of `@webjsdev/<pkg>` the scaffolding CLI ships with, so
+ * the generated `package.json` pins it precisely and BOTH npm and bun resolve
+ * the same version (#692). Walks the `require.resolve` node_modules search paths
+ * and fs-reads `<pkg>/package.json` directly: `@webjsdev/server` (and `ui`) hide
+ * `./package.json` behind `exports`, so a bare `require('<pkg>/package.json')`
+ * fails (same constraint #687 hit). Falls back to `'latest'` when the package is
+ * not resolvable (defensive; the CLI's own dependency closure is normally
+ * present), which keeps the scaffold working rather than emitting a bad pin.
+ * @param {string} pkg  e.g. 'cli', 'core', 'server'
+ * @returns {string}  an exact version, or 'latest'
+ */
+function webjsdevVersion(pkg) {
+  const req = createRequire(import.meta.url);
+  for (const base of (req.resolve.paths(`@webjsdev/${pkg}`) || [])) {
+    const pj = join(base, '@webjsdev', pkg, 'package.json');
+    if (existsSync(pj)) {
+      try {
+        const v = JSON.parse(readFileSync(pj, 'utf8')).version;
+        if (v) return v;
+      } catch { /* unreadable; keep looking, then fall back */ }
+    }
+  }
+  return 'latest';
+}
+
+/**
+ * Exact third-party dep versions the scaffold pins (#692). These are template
+ * deps the CLI does NOT itself depend on, so they cannot be read from the CLI's
+ * closure (unlike `@webjsdev/*`). Pinned EXACT so npm and bun resolve identically
+ * (a `^` range diverges: npm takes latest-in-range, bun zero-install takes
+ * absolute latest, #690). Drizzle is the 1.0 relations-v2 RC the scaffold's db
+ * code targets (its npm `latest` tag is a 0.x line, so a range would resolve the
+ * wrong major under bun). Refresh on a deliberate bump, same as the old ranges.
+ */
+const SCAFFOLD_DEP_VERSIONS = {
+  'drizzle-orm': '1.0.0-rc.3',
+  'drizzle-kit': '1.0.0-rc.3',
+  pg: '8.22.0',
+};
+
 /**
  * Run `<pm> install` inside the scaffolded app. Returns true on success.
  * Inherits stdio so the user sees the install progress live. Caller decides
@@ -273,6 +335,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     throw new Error(`Unknown --runtime '${runtime}'. Only ${VALID_RUNTIMES.join(' / ')} are supported.`);
   }
   const isBun = runtime === 'bun';
+  // Zero-install Bun entry (#675): the app-local `webjs-bun.mjs` bootstrap, run
+  // under `bun --bun`, so the server resolves the CLI + deps via Bun auto-install
+  // (no `bun install` required). App-local so it is resolvable with no node_modules.
+  const bunBoot = 'bun --bun webjs-bun.mjs';
   const appDir = join(cwd, name);
   if (existsSync(appDir)) {
     console.error(`Error: directory '${name}' already exists.`);
@@ -318,18 +384,19 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // so `npm run start` (a thin alias) behaves identically. Drizzle has no
       // codegen, so there is no dev `before` step.
       //
-      // Bun runtime (#541): the long-running server scripts (`dev` / `start`)
-      // are prefixed `bun --bun` so the app SERVES on Bun. The `--bun` overrides
-      // the `webjs` bin's `#!/usr/bin/env node` shebang (without it `bun run dev`
+      // Bun runtime (#541, zero-install #675): the server + DB scripts run via
+      // the `webjs-bun.mjs` bootstrap under `bun --bun`. `--bun` overrides the
+      // `webjs` bin's `#!/usr/bin/env node` shebang (without it `bun run dev`
       // would exec webjs under Node, silently running the "bun" app on Node).
-      // Baking it into the script body means a plain `bun run dev` (or even
-      // `npm run dev`) starts on Bun, so a user never has to remember the flag.
-      // The runtime-neutral tooling scripts below (test / db / check / typecheck
+      // Routing through the bootstrap file (which imports the CLI by bare
+      // specifier) instead of the `webjs` bin means Bun's auto-install resolves
+      // `@webjsdev/*` and your deps ON DEMAND, so `bun run dev` / `start` work
+      // with NO `bun install` (install becomes optional, for editor types /
+      // offline). The runtime-neutral tooling scripts (test / check / typecheck
       // / doctor) stay plain `webjs ...`: they spawn node tooling (`node --test`,
-      // drizzle-kit, tsc) and forcing `--bun` there buys nothing (and `webjs
-      // test` shells `node --test`, which a `bun --test` would not be).
-      dev: isBun ? 'bun --bun webjs dev' : 'webjs dev',
-      start: isBun ? 'bun --bun webjs start' : 'webjs start',
+      // tsc), which needs an install, so they are not part of the zero-install path.
+      dev: isBun ? `${bunBoot} dev` : 'webjs dev',
+      start: isBun ? `${bunBoot} start` : 'webjs start',
       test: 'webjs test',
       'test:server': 'webjs test --server',
       'test:browser': 'webjs test --browser',
@@ -340,23 +407,33 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // vendor pins, @webjsdev versions, git hook). Local tool, NOT a CI gate
       // (its env-drift + network pin-freshness checks would make CI flaky).
       doctor: 'webjs doctor',
-      'db:generate': 'webjs db generate',
-      'db:migrate': 'webjs db migrate',
-      'db:push': 'webjs db push',
-      'db:studio': 'webjs db studio',
-      'db:seed': 'webjs db seed',
+      'db:generate': isBun ? `${bunBoot} db generate` : 'webjs db generate',
+      'db:migrate': isBun ? `${bunBoot} db migrate` : 'webjs db migrate',
+      'db:push': isBun ? `${bunBoot} db push` : 'webjs db push',
+      'db:studio': isBun ? `${bunBoot} db studio` : 'webjs db studio',
+      'db:seed': isBun ? `${bunBoot} db seed` : 'webjs db seed',
     },
     dependencies: {
       // Drizzle ORM (no codegen, no engine binary). Pinned to the 1.0 line
-      // for relations v2. The SQLite/Postgres driver below is dialect-picked.
-      'drizzle-orm': '^1.0.0-rc.3',
-      ...(dialect === 'postgres' ? { pg: '^8.13.0' } : { 'better-sqlite3': '^12.11.1' }),
-      '@webjsdev/cli': 'latest',
-      '@webjsdev/core': 'latest',
-      '@webjsdev/server': 'latest',
+      // for relations v2. SQLite needs NO driver dependency: the connection
+      // uses the built-in node:sqlite (Node) / bun:sqlite (Bun) via Drizzle's
+      // node-sqlite / bun-sqlite adapters. Postgres still needs the pg driver.
+      // Exact pins (#692): npm and bun must resolve identical versions. A `^`
+      // range diverges (npm = latest-in-range; bun zero-install = absolute
+      // latest, #690), and drizzle's npm `latest` tag is a 0.x line, so a range
+      // would pull the wrong major under bun. @webjsdev/* are pinned to the
+      // versions the scaffolding CLI itself ships with.
+      'drizzle-orm': SCAFFOLD_DEP_VERSIONS['drizzle-orm'],
+      ...(dialect === 'postgres' ? { pg: SCAFFOLD_DEP_VERSIONS.pg } : {}),
+      '@webjsdev/cli': webjsdevVersion('cli'),
+      '@webjsdev/core': webjsdevVersion('core'),
+      '@webjsdev/server': webjsdevVersion('server'),
     },
     devDependencies: {
-      'drizzle-kit': '^1.0.0-rc.3',
+      // Exact pin (#692): drizzle-kit is resolved under bun zero-install via
+      // `bun run db:generate` / `db:migrate`, so it must match drizzle-orm's
+      // exact version across runtimes (a range would diverge, #690).
+      'drizzle-kit': SCAFFOLD_DEP_VERSIONS['drizzle-kit'],
       ...(dialect === 'postgres' ? { '@types/pg': '^8.11.0' } : {}),
       // The TypeScript compiler, for `npm run typecheck` (webjs typecheck runs
       // tsc --noEmit). Not needed at runtime (Node strips types in place), only
@@ -394,18 +471,28 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     webjs: {
       // Drizzle has no codegen, so there is no dev `before` step. Production
       // applies pending migrations at boot via `webjs db migrate` (drizzle-kit).
-      start: { before: ['webjs db migrate'] },
+      // On Bun this runs through the same zero-install bootstrap as `start`, so
+      // the boot-time migrate needs no `webjs` bin in node_modules (#675).
+      start: { before: [isBun ? `${bunBoot} db migrate` : 'webjs db migrate'] },
     },
-    // Bun runtime (#541): Bun does NOT run a dependency's postinstall by default
-    // (a security default); a package must be listed here for its install script
-    // to run on `bun install`. The sqlite driver `better-sqlite3` fetches its
-    // native prebuild in a postinstall, so without this the native binding is
-    // missing and the app crashes at first DB access. Postgres `pg` is pure JS
-    // (no postinstall), so the list is sqlite-only. Omitted entirely on Node
-    // (npm runs postinstalls), keeping the node-mode package.json byte-identical.
-    ...(isBun && dialect !== 'postgres' ? { trustedDependencies: ['better-sqlite3'] } : {}),
   }, null, 2) + '\n');
 
+  // The zero-install Bun entry (#675). `bun run dev` / `start` invoke this via
+  // `bun --bun` (see the scripts above). Importing the webjs CLI by bare
+  // specifier lets Bun auto-install resolve `@webjsdev/*` and your deps on
+  // demand, so a fresh app serves with NO `bun install`. The CLI reads its
+  // command (dev / start / db ...) and flags straight from argv. Node apps do
+  // not get this file; they run the `webjs` bin directly.
+  if (isBun) {
+    await writeFile(join(appDir, 'webjs-bun.mjs'),
+      '// Zero-install Bun entry (webjs #675). Run via `bun --bun webjs-bun.mjs <cmd>`\n' +
+      '// (the dev / start / db npm scripts do this). Importing the CLI by bare\n' +
+      '// specifier lets Bun auto-install resolve @webjsdev/* and your deps on\n' +
+      '// demand, so the app serves with no `bun install` (install stays optional,\n' +
+      '// for editor types and offline runs). Args pass through to the CLI.\n' +
+      "await import('@webjsdev/cli/bin/webjs.js');\n");
+  }
+
   await writeFile(join(appDir, 'tsconfig.json'), JSON.stringify({
     compilerOptions: {
       target: 'ES2022',
@@ -650,8 +737,9 @@ export type User = typeof users.$inferSelect;
 import { fileURLToPath } from 'node:url';
 import * as schema from './schema.server.ts';
 
-// The only file that opens the driver. Runtime-neutral: native bun:sqlite on
-// Bun, better-sqlite3 on Node. Cached on globalThis across dev reloads.
+// The only file that opens the driver. Runtime-neutral and ZERO native deps:
+// built-in bun:sqlite on Bun, built-in node:sqlite on Node. Cached on
+// globalThis across dev reloads.
 // A relative SQLite path resolves against the app root (the parent of db/), not
 // process.cwd(), so the connection works under \`webjs dev\` AND when the app is
 // embedded via createRequestHandler from a different working directory.
@@ -660,15 +748,25 @@ const raw = process.env.DATABASE_URL?.replace(/^file:/, '') ?? 'db/dev.db';
 const url = raw === ':memory:' || isAbsolute(raw) ? raw : resolve(appRoot, raw);
 const g = globalThis as unknown as { __webjs_db?: unknown };
 
+// Both node:sqlite and bun:sqlite default \`busy_timeout\` to 0, so a concurrent
+// writer throws \`database is locked\` immediately. Restore a 5s wait (the old
+// better-sqlite3 default) so contended access waits, and WAL so readers proceed
+// alongside one writer.
+function tune<T extends { exec(sql: string): unknown }>(client: T): T {
+  client.exec('PRAGMA busy_timeout = 5000');
+  client.exec('PRAGMA journal_mode = WAL');
+  return client;
+}
+
 async function open() {
   if ((globalThis as { Bun?: unknown }).Bun) {
     const { Database } = await import('bun:sqlite');
     const { drizzle } = await import('drizzle-orm/bun-sqlite');
-    return drizzle({ client: new Database(url), relations: schema.relations });
+    return drizzle({ client: tune(new Database(url)), relations: schema.relations });
   }
-  const { default: Database } = await import('better-sqlite3');
-  const { drizzle } = await import('drizzle-orm/better-sqlite3');
-  return drizzle({ client: new Database(url), relations: schema.relations });
+  const { DatabaseSync } = await import('node:sqlite');
+  const { drizzle } = await import('drizzle-orm/node-sqlite');
+  return drizzle({ client: tune(new DatabaseSync(url)), relations: schema.relations });
 }
 
 export const db = (g.__webjs_db ??= await open()) as Awaited<ReturnType<typeof open>>;
@@ -701,6 +799,12 @@ export default defineConfig({
 `
     : `import { defineConfig } from 'drizzle-kit';
 
+// No 'driver' is set: drizzle-kit auto-selects the SQLite driver for
+// migrate/push/studio from the runtime, picking the built-in node:sqlite on
+// Node and bun:sqlite on Bun (it only reaches for better-sqlite3 when that
+// package is present, which this app does not install). That auto-selection is
+// what keeps \`webjs db migrate\` free of a native driver, matching the runtime
+// connection in db/connection.server.ts.
 export default defineConfig({
   dialect: 'sqlite',
   schema: './db/schema.server.ts',
@@ -1370,6 +1474,12 @@ For AI agents, read this before editing scaffolded files:
     if (!installed) {
       console.log(`\n[warn] ${pm} install failed. Run '${pm} install' manually in ${name}/ to finish setup.\n`);
     }
+  } else if (isBun) {
+    // Bun zero-install (#675): no install needed; `bun run dev` resolves deps on
+    // the fly. They resolve to LATEST (ranges + lockfile ignored at runtime,
+    // #690), so point at `bun install` for pinned, reproducible versions.
+    console.log(`Skipped install. Bun resolves dependencies on the fly, so 'bun run dev' and 'bun run start' work as-is (no node_modules).`);
+    console.log(`These resolve to each dependency's LATEST version. Run 'bun install' in ${name}/ when you want pinned, reproducible versions (and editor type intelligence).\n`);
   }
 
   // Next-steps banner prints LAST so the actionable command is the
@@ -1381,7 +1491,10 @@ For AI agents, read this before editing scaffolded files:
   // generate + migrate before the first run (the example User model wants
   // its table to exist). Drizzle splits Prisma's `migrate dev` into
   // `db:generate` (schema to SQL) then `db:migrate` (apply).
-  const installSegment = installed ? '' : `${pm} install && `;
+  // Omit the install step from the next-steps line for a deliberate Bun
+  // zero-install (#682): `bun run dev` resolves deps on the fly, so it works
+  // without an install. Otherwise (Node, or an install that did not run) keep it.
+  const installSegment = (installed || (isBun && !shouldInstall)) ? '' : `${pm} install && `;
   const dbSegment = isSaas ? `${pm} run db:generate && ${pm} run db:migrate && ` : '';
   const runCommand = `cd ${name} && ${installSegment}${dbSegment}${pm} run dev`;
   // Use `npx webjsdev ui ...` here, not `npx webjs ui ...`. The bare

package/lib/runtime-rewrite.js

@@ -58,14 +58,10 @@ export function bunifyProse(s) {
       'Dockerfile pins `node:24-alpine` (the same Node major CI uses), installs\ndeps (no build step, since Drizzle has no codegen), and starts via',
       'Dockerfile is a pure `oven/bun:1` image (no Node, since `webjs db migrate`\nresolves drizzle-kit and runs under Bun with no `npx`, #570), installs deps\nwith `bun install` (no build step, since Drizzle has no codegen), and starts via',
     )
-    // The "Running on Bun" section frames Bun as opt-in ("force it with --bun").
-    // In a bun-flavored app the dev/start scripts ALREADY embed --bun, so reframe
-    // it as the configured default.
+    // The "Running on Bun" section heading is reframed for a bun-flavored app.
+    // Its body already describes the webjs-bun.mjs bootstrap + zero-install in the
+    // template (#675), so only the heading needs the runtime reframe.
     .replaceAll('### Running on Bun instead of Node', '### Runtime: this app runs on Bun')
-    .replaceAll(
-      'The same `package.json` scripts work on\neither; to run under Bun, force it with `--bun` so the server executes on Bun\nrather than the `webjs` bin\'s Node shebang:',
-      'This app is configured for Bun. Its `dev` / `start` scripts already force\n`--bun` (which overrides the `webjs` bin\'s Node shebang), so a plain `bun run dev`\nserves on Bun. The other scripts (test / db / check) run on Node, the runtime\nthe `webjs` tooling targets:',
-    )
     // Invocation styles first, so "npm create webjs@latest" does not get
     // mangled by the generic "npm <x>" rules below.
     .replaceAll('npm create webjs@latest', 'bun create webjs')
@@ -104,8 +100,8 @@ export function bunifyProse(s) {
  * `node:24-alpine` base with a copied Bun binary, since the installed CLI could
  * still shell `npx`, which a pure Bun image lacks. #595 flipped it once the
  * npx-free CLI shipped.) `oven/bun:1` is Debian-based: `ca-certificates` ship in
- * the image and better-sqlite3 fetches its glibc prebuild on `bun install`
- * (gated by `trustedDependencies`), so no build toolchain is needed.
+ * the image, and SQLite uses the built-in bun:sqlite (no native module), so no
+ * build toolchain is needed.
  *
  * @param {string} s
  * @returns {string}
@@ -126,13 +122,13 @@ export function bunifyDockerfile(s) {
     .replace('FROM node:24-alpine', 'FROM oven/bun:1')
     // Debian base: ca-certificates already present, no `apk`. Drop the alpine line.
     .replace(
-      /# ca-certificates for outbound TLS \(e\.g\. a managed Postgres\)\. better-sqlite3\n# is a prebuilt native module, so no build toolchain is needed here\.\nRUN apk add --no-cache ca-certificates\n\n/,
-      '# The Debian-based oven/bun image ships ca-certificates for outbound TLS (e.g. a\n# managed Postgres). better-sqlite3 fetches its glibc prebuild on `bun install`\n# (gated by trustedDependencies), so no build toolchain is needed.\n\n',
+      /# ca-certificates for outbound TLS \(e\.g\. a managed Postgres\)\. SQLite uses the\n# built-in node:sqlite \(no native module, no build toolchain needed\)\.\nRUN apk add --no-cache ca-certificates\n\n/,
+      '# The Debian-based oven/bun image ships ca-certificates for outbound TLS (e.g. a\n# managed Postgres). SQLite uses the built-in bun:sqlite (no native module), so no\n# build toolchain is needed.\n\n',
     )
     // Lockfile + install (bun.lock, bun install).
     .replace(
       '# package-lock.json is optional (it\'s absent when the app was scaffolded with\n# --no-install); the glob keeps the COPY working with or without it.\nCOPY package.json package-lock.json* ./\nRUN npm install --no-audit --no-fund',
-      '# bun.lock is optional (absent when scaffolded with --no-install); the glob keeps\n# the COPY working with or without it. trustedDependencies in package.json lets\n# better-sqlite3\'s native-prebuild postinstall run (bun skips postinstalls).\nCOPY package.json bun.lock* ./\nRUN bun install',
+      '# bun.lock is optional (absent when scaffolded with --no-install); the glob keeps\n# the COPY working with or without it. SQLite uses the built-in bun:sqlite, so no\n# native dependency or postinstall is involved.\nCOPY package.json bun.lock* ./\nRUN bun install',
     )
     // Healthcheck: the pure Bun image has no node; use `bun -e`. Keep the
     // dependency-free-probe comment accurate (the probe runs under Bun now).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.23",
+  "version": "0.10.25",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/.agents/rules/workflow.md

@@ -139,7 +139,7 @@ self-review loop.
   a static field on the class.
 - **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
 - One function per server action file (`*.server.ts`).
-- Server-only code (a DB driver like `better-sqlite3`/`pg`, `node:*`, anything that needs Node APIs)
+- Server-only code (a DB driver like `pg`, `node:*`, anything that needs Node APIs)
   goes only in `.server.{js,ts}` files, `route.ts` handlers, or
   `middleware.ts`. Never in pages, layouts, or components. Wrap the access in
   a `.server.{js,ts}` file; the framework rewrites that import into an RPC

package/templates/.cursorrules

@@ -114,7 +114,7 @@ self-review loop.
 - One function per server action file (*.server.ts)
 - Components must call customElements.define('tag', Class)
 - **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
-- Server-only code (the DB driver `better-sqlite3` / `pg`, node:*, anything that needs Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap the access in a .server.{js,ts} file; the framework rewrites that import into an RPC stub for the browser. The DB lives in db/*.server.ts (db/connection.server.ts); lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); follow the same rule per file: if a lib/ file needs Node APIs, only import it from server-only files.
+- Server-only code (the DB driver `pg`, node:*, anything that needs Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap the access in a .server.{js,ts} file; the framework rewrites that import into an RPC stub for the browser. The DB lives in db/*.server.ts (db/connection.server.ts); lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); follow the same rule per file: if a lib/ file needs Node APIs, only import it from server-only files.
 - Directives: webjs exports the lit directives with no clean native equivalent (`repeat`, `unsafeHTML`, `live`, `keyed`, `guard`, `cache`, `until`, `ref` / `createRef`, `templateContent`, `asyncAppend` / `asyncReplace`, `watch`). Lit's `classMap` / `styleMap` / `ifDefined` / `when` / `choose` are NOT exported. For those, use plain template-literal expressions (`class=${cond ? 'a' : 'b'}`, `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in `firstUpdated`) instead.
 - **Progressive enhancement is the default.** Pages AND every web component are SSR'd to real HTML. Write components so the first paint is the right content. Read SSR-meaningful defaults in `constructor()`. `connectedCallback` is never called on the server, so anything there only runs after hydration. Initial data for components comes from the page function (server-side fetch plus pass as attribute/property) OR from an `async render()` in the component itself (`const u = await getUser(this.uid)`, which SSR awaits so the data is in the first paint), NOT from `fetch` calls in `connectedCallback`. Prefer the co-located `async render()` over prop-drilling; `renderFallback()` is the optional re-fetch loading state (never first paint), and a `Task` is for genuinely client-only data. For write-paths, prefer `<form action=...>` plus server action over `fetch` plus click handler. The framework upgrades plain forms to partial-swap submissions automatically.
 - **Client navigation is auto-magic.** Real `<a href>` and `<form action>` get partial-swap behavior with no opt-in. Because layouts persist across navigation, put shared chrome (sidenav, header) in `layout.ts` and page-specific content in `page.ts`. For validation errors, return 4xx HTML from a `route.ts` POST handler; the router renders it in place preserving the user's input. For non-layout swap regions, wrap in `<webjs-frame id="...">`. See "Client navigation patterns" in AGENTS.md.

package/templates/.github/copilot-instructions.md

@@ -107,10 +107,10 @@ each change must include.
 - **Erasable TypeScript only.** The runtime strips types via `module.stripTypeScriptTypes` (Node's built-in, or `amaro` on Bun) (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server fails at strip time and returns a 500 pointing at the `no-non-erasable-typescript` lint rule. webjs is buildless end-to-end and has no bundler fallback.
 - Tagged template: html`<div>${value}</div>` with css`...` for styles.
 - **Tailwind-first styling.** Tailwind utilities are the strong default for pages AND light-DOM components (the default DOM mode): layout, spacing, color (via `@theme` tokens), typography, borders, radius, shadows, interaction states. Light DOM does not scope, so utilities apply directly. The lit reflex to scope CSS (`static styles = css\`...\``) or write an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component is wrong: the scoped block needs `static shadow = true`, and inline class names leak globally. When a utility bundle repeats, extract a `lib/utils/ui.ts` helper returning an `html` fragment, not a CSS class. Reserve raw CSS for the allowlist (design tokens / `@theme`, `@property` + `@keyframes`, `::-webkit-scrollbar`, `prefers-reduced-motion`, complex `color-mix()` / gradients); when unavoidable in a light-DOM component, prefix every class selector with the component tag. Shadow-DOM components (`static shadow = true`) legitimately author `static styles = css\`...\`` for scoped CSS; don't use inline `style="..."` there.
-- Components: extend the `WebComponent({ ... })` factory to declare reactive properties (e.g. `extends WebComponent({ count: Number })`; per-prop options via `prop(Number, { reflect: true })`), add `static styles` for shadow-DOM components, call `Class.register('tag-name')` at the bottom of the file. The tag name is the argument to `.register()`, not a static field. A hand-written `static properties` throws at construction (`no-static-properties`); set defaults via the `default` option or the constructor, never a class-field initializer (`reactive-props-no-class-field`). Declare an array-typed prop with the `Array` constructor, not `Object` (`items: prop<Tag[]>(Array)`), flagged by `array-prop-uses-array-type`. **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
+- Components: extend the `WebComponent({ ... })` factory to declare reactive properties (e.g. `extends WebComponent({ count: Number })`; per-prop options via `prop(Number, { reflect: true })`), add `static styles` for shadow-DOM components, call `Class.register('tag-name')` at the bottom of the file. The tag name is the argument to `.register()`, not a static field. A hand-written `static properties` throws at construction (`no-static-properties`); set defaults in the constructor, never a class-field initializer (`reactive-props-no-class-field`). Declare an array-typed prop with the `Array` constructor, not `Object` (`items: prop<Tag[]>(Array)`), flagged by `array-prop-uses-array-type`. **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
 - Async data in a component: prefer an `async render()` (`const u = await getUser(this.uid)`), which SSR awaits so the data is in the first paint, over prop-drilling from the page or fetching in `connectedCallback`. `renderFallback()` is the optional re-fetch loading state (never first paint); error isolation is automatic (`renderError()` customizes it); a `Task` is for genuinely client-only data.
 - Server actions: *.server.ts files with one exported async function each.
-- Server-only code (a DB driver like better-sqlite3/pg, node:*, anything needing Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap in a .server.{js,ts} file; the framework rewrites that import to an RPC stub for the browser. The DB lives in db/*.server.ts; lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file.
+- Server-only code (a DB driver like pg, node:*, anything needing Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap in a .server.{js,ts} file; the framework rewrites that import to an RPC stub for the browser. The DB lives in db/*.server.ts; lib/ holds other server-only infra and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file.
 - Directives: webjs exports the lit directives with no clean native equivalent (`repeat`, `unsafeHTML`, `live`, `keyed`, `guard`, `cache`, `until`, `ref` / `createRef`, `templateContent`, `asyncAppend` / `asyncReplace`, `watch`). Lit's `classMap` / `styleMap` / `ifDefined` / `when` / `choose` are NOT exported; use plain template-literal expressions instead.
 - Context: import { createContext, ContextProvider, ContextConsumer } from '@webjsdev/core/context'
 - Task: import { Task, TaskStatus } from '@webjsdev/core/task'

package/templates/AGENTS.md

@@ -404,15 +404,24 @@ an npm `prestart` hook.
 
 ### Running on Bun instead of Node
 
-webjs runs on **Node 24+ or Bun**. The same `package.json` scripts work on
-either; to run under Bun, force it with `--bun` so the server executes on Bun
-rather than the `webjs` bin's Node shebang:
+webjs runs on **Node 24+ or Bun**. A `--runtime bun` app routes its `dev` /
+`start` / `db` scripts through a `webjs-bun.mjs` bootstrap under `bun --bun`
+(which overrides the `webjs` bin's Node shebang so the server runs on Bun). The
+bootstrap imports the CLI by bare specifier, so Bun auto-install resolves deps on
+demand and **no `bun install` is needed**:
 
 ```sh
-bun install
-bun --bun run dev      # or: bun --bun run start
+bun run dev            # or: bun run start  (no install step required)
 ```
 
+`bun create` does not run an install on Bun, so a fresh app serves immediately.
+Under zero-install, deps resolve to their LATEST version: ranges and any
+`bun.lock` are ignored by the runtime auto-install (only an exact `package.json`
+pin is honored, via an `onLoad` rewrite). Run `bun install` when you want pinned,
+reproducible versions (it materializes `node_modules` from the lockfile) or
+editor type intelligence. (To run a Node-flavored app on Bun instead, force `bun --bun run
+dev`, which still expects an install.)
+
 On Node the `.ts` type-stripping is the built-in `module.stripTypeScriptTypes`;
 on Bun (which has no built-in) it comes from `amaro` automatically, so the same
 source serves identically. SSR action-result seeding (an internal hydration
@@ -632,7 +641,7 @@ the click handler is inert). Two consequences for how you write code:
    reactivity) and never in `connectedCallback` (which the server
    doesn't run). For reactive properties declared via the
    `WebComponent({ ... })` factory, set the default in the constructor
-   or pass the `default` option (e.g. `prop(Number, { default: 0 })`).
+   after `super()`.
 2. **`connectedCallback` is browser-only.** Use it for
    `localStorage`, viewport size, online status, or anything that
    genuinely can't be known on the server. Read the value, then
@@ -1153,7 +1162,7 @@ composition, so a nested shell ends up dropped by the HTML parser.
 1. Custom element tags must contain a hyphen. Pass the tag to `.register('tag-name')` at the bottom of the file. The tag is not a static field.
 2. **Server-only code goes in `.server.{js,ts}` files, `route.ts`
    handlers, or `middleware.ts`. Never in pages, layouts, or
-   components.** Direct imports of a DB driver (`better-sqlite3` / `pg`),
+   components.** Direct imports of a DB driver (`pg`),
    `node:*`, or any server-only dependency from a page, layout, loading.ts,
    error.ts, not-found.ts, or component will crash the browser at module load.
    Wrap the access in a `.server.{js,ts}` file; the framework

package/templates/CONVENTIONS.md

@@ -400,7 +400,7 @@ modules/
 - One exported function per server action/query file
 - Server actions need BOTH the `.server.{js,ts}` extension AND a `'use server'` directive at the top. Extension alone marks a server-only utility (source-protected, not RPC-callable). Directive alone is a lint violation (`use-server-needs-extension`).
 - Components must call `Class.register('tag')`
-- **Server-only code goes in `.server.{js,ts}` files, `route.ts` handlers, or `middleware.ts`. Never in pages, layouts, or components.** Direct imports of a DB driver (`better-sqlite3` / `pg`) or `node:*` from pages, layouts, or components crash the browser at module load. Wrap in a `.server.{js,ts}` file; the framework rewrites that import to an RPC stub on the browser side. The DB lives in `db/*.server.ts`; `lib/` holds other server-only infra and browser-safe utilities (`lib/utils/cn.ts` with `cn`); the convention is "if a `lib/` file needs Node APIs, only import it from server-only files."
+- **Server-only code goes in `.server.{js,ts}` files, `route.ts` handlers, or `middleware.ts`. Never in pages, layouts, or components.** Direct imports of a DB driver (`pg`) or `node:*` from pages, layouts, or components crash the browser at module load. Wrap in a `.server.{js,ts}` file; the framework rewrites that import to an RPC stub on the browser side. The DB lives in `db/*.server.ts`; `lib/` holds other server-only infra and browser-safe utilities (`lib/utils/cn.ts` with `cn`); the convention is "if a `lib/` file needs Node APIs, only import it from server-only files."
 - Routes (`app/**/page.ts`, `app/**/route.ts`) must be thin: import logic from modules
 - **Fetch server data in the component that needs it, with an `async render()`, not by prop-drilling.** A leaf component can write `const u = await getUser(this.uid)` directly in `render()`; SSR awaits it so the data is in the first paint, and the client uses stale-while-revalidate on a re-fetch. Reach for `renderFallback()` only to show a re-fetch loading state, and `Task` / signals only for genuinely client-only data (a `Task` shows its pending state at SSR, losing first-paint data). Do not put `await getData()` in a page / layout when a leaf component can own it (page fetches run sequentially, a route-level waterfall).
 - **Keep pages and layouts as pure carriers, so their modules stay out of the network tab.** A page/layout never hydrates; the framework drops its module from the browser as long as its only browser-relevant job is registering the components it imports. It starts shipping its own module (invisible in tests) the moment its closure does any OTHER client work. So do not give a page/layout module-scope client work (a top-level call, a `window` / `document` / `customElements` access, a bare side-effect import, or a `@webjsdev/core/client-router` import: routing is automatic), and do not import a client-global-touching non-component util into it. Put client behaviour in a component, server-only code in `.server.{js,ts}`. Self-check: `page.ts` / `layout.ts` should not appear in the browser's network tab.
@@ -671,7 +671,7 @@ export class MyWidget extends WebComponent({
 MyWidget.register('my-widget');
 ```
 
-Reactive properties are declared one way: pass the properties shape directly to the base-class factory `WebComponent({ ... })` (e.g. `label: String`). The property types flow to `this.<prop>` with no `declare` lines needed, and the factory installs the reactive accessors so a class-field initializer can never clobber them. For per-property options use the `prop()` helper inside the shape (`count: prop(Number, { reflect: true })`, `mode: prop({ state: true })`); narrow a type with `prop<Student>(Object)`. Set defaults via the `default` option (`prop(Number, { default: 0 })`) or by assigning in the constructor after `super()`. A hand-written `static properties = { ... }` THROWS at construction (`no-static-properties`). The factory gives you full intelligence in any tsserver-backed editor. See the Editor Setup docs for the standalone `@webjsdev/intellisense` (no Lit dependency) that extends this to tag / attribute intelligence inside `html\`…\`` templates (go-to-definition, binding-aware completions, value/binding diagnostics, hover); in VS Code / Cursor / Windsurf the `webjs` extension bundles it automatically.
+Reactive properties are declared one way: pass the properties shape directly to the base-class factory `WebComponent({ ... })` (e.g. `label: String`). The property types flow to `this.<prop>` with no `declare` lines needed, and the factory installs the reactive accessors so a class-field initializer can never clobber them. For per-property options use the `prop()` helper inside the shape (`count: prop(Number, { reflect: true })`, `mode: prop({ state: true })`); narrow a type with `prop<Student>(Object)`. Set defaults by assigning in the constructor after `super()`. A hand-written `static properties = { ... }` THROWS at construction (`no-static-properties`). The factory gives you full intelligence in any tsserver-backed editor. See the Editor Setup docs for the standalone `@webjsdev/intellisense` (no Lit dependency) that extends this to tag / attribute intelligence inside `html\`…\`` templates (go-to-definition, binding-aware completions, value/binding diagnostics, hover); in VS Code / Cursor / Windsurf the `webjs` extension bundles it automatically.
 
 **Rules:**
 - One component per file
@@ -683,7 +683,7 @@ Reactive properties are declared one way: pass the properties shape directly to
 - **Never extend raw HTMLElement directly for app components.** Always subclass `WebComponent` (or the factory form `WebComponent({...})`) to hook into SSR, lifecycle, elision, and the reactive property system. Extend raw HTMLElement only for rare native-API edge cases (like form-associated `ElementInternals` or customized built-in elements), and add a `webjs-allow-htmlelement: <reason>` comment to acknowledge the exception.
 - Tag name must contain a hyphen (HTML spec)
 - Always call `Class.register('tag')`. That's the standard DOM API.
-- **Reactive props are declared via the base-class factory `WebComponent({ ... })`.** A hand-written `static properties = { ... }` throws at construction (`webjs check` flags it via `no-static-properties`). Never write `propName = value` or `propName: Type = value` as a class-field initializer on a reactive prop. It compiles to `Object.defineProperty(this, …)` after `super()` and clobbers the framework's reactive accessor, silently breaking re-renders (`webjs check` flags this via `reactive-props-no-class-field`). Set defaults via the `default` option or in the constructor. Declare an array-typed prop with the `Array` constructor, not `Object` (`items: prop<Tag[]>(Array)`): the two share one JSON converter so neither crashes, but `Array` states the shape and `webjs check` flags the `Object` form via `array-prop-uses-array-type`.
+- **Reactive props are declared via the base-class factory `WebComponent({ ... })`.** A hand-written `static properties = { ... }` throws at construction (`webjs check` flags it via `no-static-properties`). Never write `propName = value` or `propName: Type = value` as a class-field initializer on a reactive prop. It compiles to `Object.defineProperty(this, …)` after `super()` and clobbers the framework's reactive accessor, silently breaking re-renders (`webjs check` flags this via `reactive-props-no-class-field`). Set defaults in the constructor. Declare an array-typed prop with the `Array` constructor, not `Object` (`items: prop<Tag[]>(Array)`): the two share one JSON converter so neither crashes, but `Array` states the shape and `webjs check` flags the `Object` form via `array-prop-uses-array-type`.
 - Component state lives in signals. Import `signal` from `@webjsdev/core`, read via `signal.get()` inside `render()`, write via `signal.set(value)`. Module-scope signals share state across components; instance signals (created in the constructor) carry component-local state. Reactive properties (declared via the factory) wrap HTML attributes, attribute reflection, and `.prop=${value}` SSR hydration.
 - Use lifecycle hooks (`firstUpdated`, `updated`) only when needed
 

package/templates/Dockerfile

@@ -21,8 +21,8 @@
 # framework AGENTS.md "Secure response headers" section.
 FROM node:24-alpine
 
-# ca-certificates for outbound TLS (e.g. a managed Postgres). better-sqlite3
-# is a prebuilt native module, so no build toolchain is needed here.
+# ca-certificates for outbound TLS (e.g. a managed Postgres). SQLite uses the
+# built-in node:sqlite (no native module, no build toolchain needed).
 RUN apk add --no-cache ca-certificates
 
 WORKDIR /app