@webjsdev/cli 0.10.27 → 0.10.29

package/README.md

@@ -33,7 +33,7 @@ npx @webjsdev/cli create my-app
 cd my-app && npm run dev
 ```
 
-`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.
+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.
 
 ## Commands
 

package/bin/webjs.js

@@ -6,7 +6,6 @@ import { resolveBin } from '../lib/resolve-bin.js';
 import { checkNodeInline, nodeInlineMessage } from '../lib/node-preflight.js';
 import { loadAppEnv, resolvePort } from '../lib/port.js';
 import { planDevSupervisor } from '../lib/dev-supervisor.js';
-import { importWebjsdev } from '../lib/import-webjsdev.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const [cmd, ...rest] = process.argv.slice(2);
@@ -51,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] [--install|--no-install]  Scaffold a new webjs app
+  webjs create <name> [--template full-stack|api|saas] [--db sqlite|postgres] [--runtime node|bun] [--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".
-                                                  Install default is per runtime: Node installs; Bun skips (zero-install,
-                                                  "bun run dev" resolves deps on the fly). --install / --no-install override.
+                                                  Auto-runs the detected package manager's install in the new dir
+                                                  unless --no-install is passed.
   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)
@@ -122,7 +121,7 @@ async function main() {
   // instead of crashing cryptically later. `help` is exempt so a user on an
   // old Node can still read usage.
   if (cmd !== 'help' && cmd !== undefined) {
-    const { assertNodeVersion } = await importWebjsdev('@webjsdev/server');
+    const { assertNodeVersion } = await import('@webjsdev/server');
     assertNodeVersion({ onFail: 'exit' });
   }
   switch (cmd) {
@@ -130,7 +129,7 @@ async function main() {
       // If we're already inside the reload child (node --watch or bun --hot),
       // start the server directly.
       if (process.env.__WEBJS_DEV_CHILD === '1') {
-        const { startServer } = await importWebjsdev('@webjsdev/server');
+        const { startServer } = await import('@webjsdev/server');
         // Load `.env` BEFORE resolving the port so a `PORT` set there is in
         // process.env at resolution time (#447). The server loads `.env`
         // too, but that runs too late to affect the port the CLI computes.
@@ -148,6 +147,12 @@ async function main() {
       // down on exit so a watcher cannot outlive the server.
       const { readAppTasks } = await import('../lib/app-tasks.js');
       const devTasks = readAppTasks(process.cwd());
+      // Load `.env` BEFORE the before-steps (same as `start`, L188), so a
+      // `dev.before` `webjs db migrate` sees DATABASE_URL from `.env`. Without
+      // this a Postgres dev migrate runs with no connection string and fails
+      // (sqlite survives via its `?? 'db/dev.db'` config fallback). The watch
+      // child / inline server load `.env` again later (idempotent).
+      loadAppEnv(process.cwd());
       await runPhaseBeforeSteps('dev', devTasks.dev.before, process.cwd());
       const killTasks = await startDevParallelTasks(devTasks.dev.parallel, process.cwd());
       process.on('SIGINT', () => { killTasks(); process.exit(0); });
@@ -166,7 +171,7 @@ async function main() {
       });
 
       if (plan.mode === 'inline') {
-        const { startServer } = await importWebjsdev('@webjsdev/server');
+        const { startServer } = await import('@webjsdev/server');
         loadAppEnv(process.cwd());
         const port = resolvePort(flag(rest, '--port'));
         await startServer({ appDir: process.cwd(), port, dev: true });
@@ -183,7 +188,7 @@ async function main() {
       break;
     }
     case 'start': {
-      const { startServer } = await importWebjsdev('@webjsdev/server');
+      const { startServer } = await import('@webjsdev/server');
       // Load `.env` BEFORE resolving the port so a `PORT` set there wins over
       // the 8080 default (#447), same as for `dev`.
       loadAppEnv(process.cwd());
@@ -365,7 +370,7 @@ async function main() {
       break;
     }
     case 'check': {
-      const { checkConventions, RULES } = await importWebjsdev('@webjsdev/server/check');
+      const { checkConventions, RULES } = await import('@webjsdev/server/check');
 
       if (rest.includes('--rules')) {
         console.log('webjs check, correctness rules:');
@@ -391,7 +396,7 @@ async function main() {
       if (rest.includes('--json')) {
         // The projector lives in @webjsdev/mcp (the MCP `check` tool's home),
         // so `check --json` and the MCP tool stay byte-identical (#415).
-        const { projectCheck } = await importWebjsdev('@webjsdev/mcp/check-report');
+        const { projectCheck } = await import('@webjsdev/mcp/check-report');
         console.log(JSON.stringify(projectCheck(violations)));
         if (violations.length > 0) process.exit(1);
         break;
@@ -448,7 +453,7 @@ async function main() {
       // narrowing the @webjsdev/core `Route` href union + per-route `params`.
       // Opt-in codegen: the static types in @webjsdev/core work without it
       // (un-generated apps see `Route = string`).
-      const { generateRouteTypes } = await importWebjsdev('@webjsdev/server');
+      const { generateRouteTypes } = await import('@webjsdev/server');
       const { mkdir, writeFile } = await import('node:fs/promises');
       const appDir = process.cwd();
       const text = await generateRouteTypes(appDir);
@@ -522,11 +527,7 @@ 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
@@ -537,16 +538,15 @@ Full docs: https://docs.webjs.com`);
         console.error(`Error: unknown --runtime '${runtime}'. Only node / bun are supported.`);
         process.exit(1);
       }
-      const { scaffoldApp, resolveCreateInstall } = await import('../lib/create.js');
-      const install = resolveCreateInstall({ runtime, explicitInstall, noInstall });
-      await scaffoldApp(name, process.cwd(), { template, db, runtime, install });
+      const { scaffoldApp } = await import('../lib/create.js');
+      await scaffoldApp(name, process.cwd(), { template, db, runtime, install: !noInstall });
       break;
     }
     case 'vendor': {
       const sub = rest[0];
       const args = rest.slice(1);
       const appDir = process.cwd();
-      const { pinAll, unpinPackage, listPinned, auditPinned, findOutdated, updatePinned, readPinFile, ensureVendorCommittable, SUPPORTED_PROVIDERS } = await importWebjsdev('@webjsdev/server');
+      const { pinAll, unpinPackage, listPinned, auditPinned, findOutdated, updatePinned, readPinFile, ensureVendorCommittable, SUPPORTED_PROVIDERS } = await import('@webjsdev/server');
 
       // Parse `--from <provider>` once at the top so subcommands share it.
       // Mirrors importmap-rails's `bin/importmap pin foo --from jsdelivr`.
@@ -809,7 +809,7 @@ Full docs: https://docs.webjs.com`);
       // runnable directly as `npx @webjsdev/mcp`); `webjs mcp` delegates to it
       // for back-compat. The version advertised in the initialize handshake is
       // @webjsdev/mcp's own, resolved by its bin, so this passes none.
-      const { runMcpServer } = await importWebjsdev('@webjsdev/mcp');
+      const { runMcpServer } = await import('@webjsdev/mcp');
       const { createRequire } = await import('node:module');
       const require = createRequire(import.meta.url);
       let version = '0.0.0';

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, readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import { bunifyProse, bunifyDockerfile, bunifyCompose, bunifyCi } from './runtime-rewrite.js';
@@ -35,86 +35,6 @@ 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 webjs pins a declared dep to its package.json
- * version via the #685/#698 onLoad rewrite (a caret range now resolves the
- * highest match, not absolute latest), so `bun install` is the path to a frozen
- * lockfile, not a correctness fix. 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.
- * `webjsdevRange` carets over this for the generated `package.json` (#700), so a
- * fresh app tracks the line the CLI shipped. 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';
-}
-
-/**
- * The `@webjsdev/<pkg>` specifier for the generated `package.json` (#700): a
- * caret range over the version the scaffolding CLI ships with, so a fresh app
- * picks up patch updates the way an npm user expects (a `^0.x` caret stays
- * within the minor). Bun zero-install resolves a normal caret range correctly
- * since #698, so this no longer diverges from npm. Falls back to `'latest'` when
- * the version is not resolvable (keeps `^latest` from ever being emitted).
- * @param {string} pkg  e.g. 'cli', 'core', 'server'
- * @returns {string}
- */
-function webjsdevRange(pkg) {
-  const v = webjsdevVersion(pkg);
-  return v === 'latest' ? 'latest' : '^' + v;
-}
-
-/**
- * Third-party dep specifiers the scaffold ships (#700). These are template deps
- * the CLI does NOT itself depend on, so they cannot be read from the CLI's
- * closure (unlike `@webjsdev/*`). Since #698, Bun zero-install resolves a normal
- * caret range correctly (highest match, not absolute latest), so `pg` is an
- * idiomatic `^` range. Drizzle is PINNED to an exact RC: its 1.0 line is a
- * PRERELEASE (`1.0.0-rc.3`), and Bun zero-install ENOENTs on a caret-prerelease
- * inline specifier (`drizzle-orm@^1.0.0-rc.3`, verified on Bun 1.3.14) while the
- * exact prerelease resolves, so drizzle must stay exact until the 1.0 stable
- * ships. Refresh on a deliberate bump.
- */
-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
@@ -353,10 +273,6 @@ 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.`);
@@ -398,23 +314,22 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     },
     scripts: {
       // No `predev` / `prestart` hooks (#550): the `webjs` block below holds
-      // the start orchestration (`webjs db migrate`), run INSIDE `webjs start`,
-      // so `npm run start` (a thin alias) behaves identically. Drizzle has no
-      // codegen, so there is no dev `before` step.
+      // the dev + start orchestration (`webjs db migrate`), run INSIDE `webjs
+      // dev` / `webjs start`, so `npm run dev` / `start` (thin aliases) behave
+      // identically. Both apply pending migrations before serving (#725).
       //
-      // 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`
+      // 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`
       // would exec webjs under Node, silently running the "bun" app on Node).
-      // 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
+      // 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
       // / doctor) stay plain `webjs ...`: they spawn node tooling (`node --test`,
-      // 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',
+      // 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',
       test: 'webjs test',
       'test:server': 'webjs test --server',
       'test:browser': 'webjs test --browser',
@@ -425,31 +340,25 @@ 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': 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',
+      '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',
     },
     dependencies: {
       // Drizzle ORM (no codegen, no engine binary). Pinned to the 1.0 line
       // 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.
-      // Since #698 a normal caret range resolves correctly under bun
-      // zero-install, so @webjsdev/* and pg are idiomatic `^` ranges (#700).
-      // Drizzle stays EXACT: its 1.0 line is a prerelease RC, and bun ENOENTs
-      // on a caret-prerelease inline specifier, so a range would break it.
-      'drizzle-orm': SCAFFOLD_DEP_VERSIONS['drizzle-orm'],
-      ...(dialect === 'postgres' ? { pg: SCAFFOLD_DEP_VERSIONS.pg } : {}),
-      '@webjsdev/cli': webjsdevRange('cli'),
-      '@webjsdev/core': webjsdevRange('core'),
-      '@webjsdev/server': webjsdevRange('server'),
+      'drizzle-orm': '^1.0.0-rc.3',
+      ...(dialect === 'postgres' ? { pg: '^8.13.0' } : {}),
+      '@webjsdev/cli': 'latest',
+      '@webjsdev/core': 'latest',
+      '@webjsdev/server': 'latest',
     },
     devDependencies: {
-      // Exact pin: drizzle-kit shares drizzle-orm's prerelease 1.0 RC, which bun
-      // cannot resolve as a caret-prerelease range, so it stays exact (#700).
-      'drizzle-kit': SCAFFOLD_DEP_VERSIONS['drizzle-kit'],
+      'drizzle-kit': '^1.0.0-rc.3',
       ...(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
@@ -477,38 +386,20 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // into components/ui/ (they import @webjsdev/core, not the kit), and the
       // CLI resolves @webjsdev/ui from its own install.
     },
-    // Start task orchestration (#550). `webjs start` reads `start.before` and
-    // runs it in-process, so `npm run start` (a thin alias above) behaves
-    // identically. Drizzle has no codegen, so there is no dev `before` step;
-    // production applies pending migrations via `webjs db migrate`. The scaffold
+    // Dev + start task orchestration (#550). `webjs dev` / `webjs start` read
+    // `before` and run it in-process, so `npm run dev` / `start` (thin aliases
+    // above) behave identically. Both apply pending migrations via `webjs db
+    // migrate` (idempotent, a no-op when the db is current), so a freshly
+    // generated migration is applied without a manual step (#725). The scaffold
     // uses the Tailwind browser runtime (no CSS build step), so there is no dev
     // `parallel` watcher here; an app that adds the Tailwind CLI puts its
     // `--watch` command under `webjs.dev.parallel`.
     webjs: {
-      // Drizzle has no codegen, so there is no dev `before` step. Production
-      // applies pending migrations at boot via `webjs db migrate` (drizzle-kit).
-      // 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'] },
+      dev: { before: ['webjs db migrate'] },
+      start: { before: ['webjs db migrate'] },
     },
   }, 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',
@@ -1490,13 +1381,6 @@ 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. Since #698 they resolve to their package.json versions (a caret
-    // range to its highest match), so point at `bun install` for a frozen
-    // lockfile and editor type intelligence, not a correctness fix.
-    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 the versions in package.json. Run 'bun install' in ${name}/ to freeze a lockfile and get editor type intelligence.\n`);
   }
 
   // Next-steps banner prints LAST so the actionable command is the
@@ -1504,16 +1388,22 @@ For AI agents, read this before editing scaffolded files:
   // Single copy-paste line so the user can move from "scaffold done"
   // to "dev server up" in one command. The full-stack and saas
   // templates ship with @webjsdev/ui already initialised; the api
-  // template has no UI but may add one later. Saas needs a one-time
-  // 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).
-  // 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 && ` : '';
+  // template has no UI but may add one later.
+  const installSegment = installed ? '' : `${pm} install && `;
+  // The saas example queries the users table on its first request (auth), so it
+  // needs a migration authored first: `db:generate` writes it and the
+  // `webjs.dev.before` migrate applies it on `run dev` (Drizzle splits Prisma's
+  // `migrate dev` into generate-then-migrate). The full-stack / api examples do
+  // not query the db on first paint, so they boot with just `run dev`; once you
+  // add a db route, `db:generate` then `run dev` is the loop (dev auto-migrates).
+  const dbSegment = isSaas ? `${pm} run db:generate && ` : '';
   const runCommand = `cd ${name} && ${installSegment}${dbSegment}${pm} run dev`;
+  // Postgres needs a reachable DATABASE_URL before any migrate (sqlite uses a
+  // local file with no .env). Point it at a running database; `dev` / `start`
+  // then apply pending migrations via webjs.*.before.
+  const pgNote = dialect === 'postgres'
+    ? `\nPostgres: copy .env.example to .env and set DATABASE_URL to a running database before \`${pm} run dev\`.\n`
+    : '';
   // Use `npx webjsdev ui ...` here, not `npx webjs ui ...`. The bare
   // `webjs` npm name is owned by an unrelated package; `npx webjs
   // <cmd>` would fetch THAT package instead of ours when run outside
@@ -1529,7 +1419,7 @@ For AI agents, read this before editing scaffolded files:
 Next steps:
   ${runCommand}
   # → http://localhost:8080
-
+${pgNote}
 Optional:
   ${uiNote}
 `);

package/lib/runtime-rewrite.js

@@ -58,10 +58,14 @@ 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 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.
+    // 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.
     .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')

package/lib/saas-template.js

@@ -186,9 +186,10 @@ export async function writeSaasFiles(appDir, opts = {}) {
   //     ALWAYS once the app modules import: auth() only reads a cookie, no DB
   //     query. This is the headline security assertion and it is REAL.
   //   The signup, login, and protected-route flow writes + reads a user, so it
-  //   needs the DB migrated (`npm run db:generate` then `npm run db:migrate`).
-  //   Until the users table exists those flows error, so the suite skips with a
-  //   clear message instead of crashing. After DB setup it runs for real.
+  //   needs the migrated users table (`npm run db:generate`, then `npm run dev`
+  //   applies it via webjs.dev.before). Until then those flows error, so the
+  //   suite probes readiness and skips with a clear message instead of crashing,
+  //   then runs for real once the db is set up.
   await mkdir(join(appDir, 'test', 'auth'), { recursive: true });
   // The generated comments reference `npm run db:*` setup; bun-ify them so a
   // bun-flavored saas app reads `bun run db:*` (#541; db is Node tooling, so a
@@ -205,12 +206,11 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "const appDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');",
     "",
     "// The auth pages + dashboard middleware query the users table via Drizzle.",
-    "// Until `npm run db:generate` + `npm run db:migrate` have created it, a",
-    "// request hitting those modules 500s. We detect that at the RESPONSE level",
+    "// Until `npm run db:generate` has authored the migration (then `npm run dev`",
+    "// applies it via webjs.dev.before, or `npm run db:migrate` directly), a",
+    "// request hitting those modules 500s; we detect that at the RESPONSE level",
     "// (a 5xx on the dashboard) and SKIP with a clear message rather than report",
-    "// a misleading failure. After you run",
-    "//   npm install && npm run db:generate && npm run db:migrate",
-    "// every assertion below runs for real.",
+    "// a misleading failure. After the db is set up every assertion runs for real.",
     "process.env.DATABASE_URL ||= 'file:./dev.db';",
     "process.env.AUTH_SECRET ||= 'test-secret-at-least-32-characters-long!!';",
     "",

package/package.json

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

package/templates/AGENTS.md

@@ -329,7 +329,7 @@ db/
   columns.server.ts      column helpers (dialect-specific; the only file to swap for Postgres)
   connection.server.ts   opens the driver, exports the \`db\` singleton (import \`db\` from here)
   seed.server.ts         optional seed (run via \`webjs db seed\`)
-  dev.db                 SQLite file (gitignored); run \`npm run db:migrate\` to create
+  dev.db                 SQLite file (gitignored); created when migrations apply (\`dev\`/\`start\` run \`webjs db migrate\`)
   migrations/            generated migration SQL (committed)
 drizzle.config.ts        drizzle-kit config (root; SQLite by default, --db postgres to switch)
 public/                  static assets, served at /public/*
@@ -387,13 +387,16 @@ lives in the `webjs` block of `package.json` and runs INSIDE
 
 ```jsonc
 "webjs": {
+  "dev": { "before": ["webjs db migrate"] },
   "start": { "before": ["webjs db migrate"] }
 }
 ```
 
-Drizzle has no codegen, so there is no dev `before` step. An app that
-adds the Tailwind CLI puts its `--watch` command under
-`webjs.dev.parallel` and it runs alongside the server, torn down on exit.
+Both `dev` and `start` apply pending migrations via `webjs db migrate`
+(idempotent, a no-op when the db is current), so a freshly generated
+migration is applied without a manual step. An app that adds the Tailwind
+CLI puts its `--watch` command under `webjs.dev.parallel` and it runs
+alongside the server, torn down on exit.
 `before` steps run to completion first; a failed `webjs db migrate`
 aborts the boot with a clear message rather than serving a stale schema.
 
@@ -404,29 +407,15 @@ an npm `prestart` hook.
 
 ### Running on Bun instead of Node
 
-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**:
+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:
 
 ```sh
-bun run dev            # or: bun run start  (no install step required)
+bun install
+bun --bun run dev      # or: bun --bun run start
 ```
 
-`bun create` does not run an install on Bun, so a fresh app serves immediately.
-Under zero-install, Bun's runtime auto-install resolves a BARE import to LATEST
-(it ignores `package.json` and `bun.lock`), so webjs rewrites each declared dep's
-specifier to an inline-versioned one via an `onLoad` transform. The version is the
-`bun.lock` exact when present, else the `package.json` value when it is an
-inline-safe semver (an exact pin, or a caret / tilde / comparator range, which
-Bun resolves to the highest match). A protocol range (`workspace:`, `file:`), a
-wildcard (`*`), and a dist-tag (`latest`) stay at latest. Run `bun install` when
-you want versions frozen identically across machines (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
@@ -471,7 +460,7 @@ Scripts (all wrap `drizzle-kit`):
 - `npm run db:push`: `webjs db push` (push the schema straight to the dev DB)
 - `npm run db:studio`: `webjs db studio` (visual DB browser)
 - `npm run db:seed`: `webjs db seed` (run `db/seed.server.ts`)
-- `webjs.start.before` runs `webjs db migrate` inside `webjs start` (idempotent; replaces the old `prestart` hook). No dev `before` step (no codegen).
+- `webjs.dev.before` and `webjs.start.before` both run `webjs db migrate` inside `webjs dev` / `webjs start` (idempotent; replaces the old `prestart` hook), so after you `db:generate` a migration it is applied on the next boot with no manual `db:migrate` step.
 
 Always import `db` from `db/connection.server.ts` (the globalThis-cached
 singleton avoids opening a new connection on every dev-server reload), and

package/templates/CONVENTIONS.md

@@ -268,11 +268,12 @@ docs". That is the agent's default behavior in a webjs project.
 
 Every webjs app uses **Drizzle + SQLite** for persistence by default. The
 scaffold ships the `db/` folder (`schema.server.ts`, `columns.server.ts`,
-`connection.server.ts`), the `webjs.start.before` step that runs
-`webjs db migrate` inside `webjs start` (#550), and the
+`connection.server.ts`), the `webjs.dev.before` + `webjs.start.before` steps
+that run `webjs db migrate` inside `webjs dev` / `webjs start` (#550), and the
 `npm run db:generate` / `db:migrate` / `db:push` / `db:studio` / `db:seed`
-scripts (which route through `webjs db` to drizzle-kit). Drizzle has no
-codegen, so there is no dev `before` step.
+scripts (which route through `webjs db` to drizzle-kit). The loop after a
+schema change is `db:generate` (authors the migration) then `webjs dev` (the
+`dev.before` step applies it); `db:generate` is never auto-run on boot.
 
 **AI agents: these rules are absolute.**
 

package/lib/import-webjsdev.js

@@ -1,99 +0,0 @@
-// Pin `@webjsdev/*` imports under Bun zero-install (#709).
-//
-// Under Bun zero-install a bare `import('@webjsdev/server')` from the cli (run
-// out of the global cache) ENOENTs: Bun's runtime auto-install ignores the cli's
-// declared range and flakily fetches latest, which fails. An INLINE-versioned
-// specifier (`@webjsdev/server@^0.8.0`) resolves reliably. So we read the version
-// the APP declares (the scaffold adds `@webjsdev/*` to its deps) and retry inline
-// only when the bare import fails, so Node and installed apps are unaffected.
-
-import { readFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-// The cli's OWN package.json (one level up from this lib), used as the fallback
-// pin source for `@webjsdev/*` packages the app does not declare (mcp, ui).
-const CLI_PKG = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
-
-/**
- * Whether a declared version is a Bun inline-safe specifier: an exact version or
- * a single caret / tilde / comparator range, but NOT a range over a prerelease
- * (`^1.0.0-rc.3`, which Bun ENOENTs on, #703), a wildcard, a multi-token range,
- * or a protocol range (`workspace:` / `file:`).
- * @param {unknown} v
- * @returns {boolean}
- */
-export function inlineSafeVersion(v) {
-  if (typeof v !== 'string') return false;
-  const m = /^(>=|<=|>|<|=|\^|~)?(\d+(?:\.\d+){0,2})([-+][0-9A-Za-z.-]+)?$/.exec(v);
-  return !!m && !(m[1] && m[3]);
-}
-
-/**
- * The version a `package.json` at `pkgPath` declares for `name`, when it is
- * inline-safe; else null.
- * @param {string} name
- * @param {string} pkgPath  absolute path to a package.json
- * @returns {string | null}
- */
-function declaredIn(name, pkgPath) {
-  try {
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
-    const v = { ...pkg.dependencies, ...pkg.devDependencies }[name];
-    if (inlineSafeVersion(v)) return v;
-  } catch { /* no readable package.json */ }
-  return null;
-}
-
-/**
- * The inline-safe version to pin `name` to: the app's `package.json` (in `cwd`)
- * first (it declares `@webjsdev/server` etc.), else the cli's OWN package.json
- * (for `@webjsdev/*` the app does not declare, like `mcp` / `ui`). Null if
- * neither has an inline-safe declaration.
- * @param {string} name
- * @param {string} [cwd]
- * @returns {string | null}
- */
-export function appDeclaredVersion(name, cwd = process.cwd()) {
-  return declaredIn(name, join(cwd, 'package.json')) || declaredIn(name, CLI_PKG);
-}
-
-/**
- * Whether an import error is a resolution / not-found failure (so a version
- * retry is warranted), vs a genuine load-time throw from the module's own code
- * (which we must NOT retry, to avoid masking it and re-running side effects).
- * @param {unknown} err
- * @returns {boolean}
- */
-function isResolutionError(err) {
-  if (err && /** @type {any} */ (err).code === 'ERR_MODULE_NOT_FOUND') return true;
-  const msg = err && String(/** @type {any} */ (err).message || err);
-  // Narrow on purpose: Node sets the code above; Bun's auto-install miss is
-  // `ENOENT while resolving package '...'`. A broad "cannot find" would match
-  // ordinary runtime errors ("Cannot find user") and wrongly trigger a retry.
-  return !!msg && /ENOENT|resolving package|module not found/i.test(msg);
-}
-
-/**
- * Import an `@webjsdev/*` module, pinning the version under Bun zero-install. On
- * Node or an installed app the bare specifier resolves from `node_modules` (no
- * retry). On a RESOLUTION failure (Bun zero-install), retry with the app's (else
- * the cli's own) declared version inline. A real load-time throw is rethrown,
- * not retried. A subpath (`/check`) is preserved across the rewrite.
- * @param {string} spec  e.g. `@webjsdev/server` or `@webjsdev/server/check`
- * @param {(s: string) => Promise<any>} [importer]  injectable for tests
- * @returns {Promise<any>}
- */
-export async function importWebjsdev(spec, importer = (s) => import(s)) {
-  try {
-    return await importer(spec);
-  } catch (err) {
-    if (!isResolutionError(err)) throw err;
-    const m = /^(@webjsdev\/[^/]+)(\/.*)?$/.exec(spec);
-    const pkg = m && m[1];
-    const sub = (m && m[2]) || '';
-    const v = pkg && appDeclaredVersion(pkg);
-    if (v) return await importer(pkg + '@' + v + sub);
-    throw err;
-  }
-}