@webjsdev/cli 0.10.19 → 0.10.21

package/bin/webjs.js

@@ -2,6 +2,7 @@
 import { resolve, join, dirname } from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+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';
@@ -49,8 +50,10 @@ const USAGE = `webjs commands:
   webjs doctor                                    Verify project health (Node, tsconfig, env, vendor pins, importmap coherence, @webjsdev versions, git hook)
   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] [--no-install]  Scaffold a new webjs app
-                                                  (only 3 templates exist. default: full-stack, Drizzle, --db sqlite)
+  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".
                                                   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)
@@ -216,7 +219,22 @@ async function main() {
       const map = { generate: ['generate'], migrate: ['migrate'], push: ['push'], studio: ['studio'] };
       const kitArgs = map[sub];
       if (!kitArgs) { console.error('Unknown db subcommand.\n' + USAGE); process.exit(1); }
-      const child = spawn('npx', ['drizzle-kit', ...kitArgs, ...args], { stdio: 'inherit', cwd: process.cwd() });
+      // Resolve the app's own drizzle-kit bin and spawn it with the CURRENT
+      // runtime (process.execPath). This drops the hard `npx` dependency (#570):
+      // `npx` is absent in a pure oven/bun image, which broke `webjs db migrate`
+      // at boot. On Node this is `node drizzle-kit`, on Bun `bun drizzle-kit`
+      // (drizzle-kit runs under both).
+      let dkPath;
+      try {
+        dkPath = resolveBin(process.cwd(), 'drizzle-kit', 'drizzle-kit');
+      } catch {
+        console.error(
+          'webjs db: drizzle-kit is not installed in this project.\n' +
+          'Install it with `npm install -D drizzle-kit`, then re-run `webjs db ' + sub + '`.',
+        );
+        process.exit(1);
+      }
+      const child = spawn(process.execPath, [dkPath, ...kitArgs, ...args], { stdio: 'inherit', cwd: process.cwd() });
       child.on('exit', (code) => process.exit(code ?? 0));
       break;
     }
@@ -296,7 +314,14 @@ async function main() {
 
         if (testFiles.length > 0) {
           console.log(`webjs test: running ${testFiles.length} server test file(s)…\n`);
-          const child = spawn(process.execPath, ['--test', ...testFiles], {
+          // Dispatch to the current runtime's test runner (#570). Node uses
+          // `node --test <files>`; Bun's runner is the `bun test <files>`
+          // subcommand (`bun --test` is invalid). process.execPath is the
+          // active runtime, so the args differ but the runner is native to it.
+          const testArgs = process.versions.bun
+            ? ['test', ...testFiles]
+            : ['--test', ...testFiles];
+          const child = spawn(process.execPath, testArgs, {
             stdio: 'inherit', cwd, env: { ...process.env },
           });
           const code = await new Promise(r => child.on('exit', r));
@@ -306,25 +331,32 @@ async function main() {
 
       // --- Browser tests (WTR + Playwright) ---
       if (runBrowser) {
-        const wtrConfig = join(cwd, 'web-test-runner.config.js');
-        if (existsSync(wtrConfig) || existsSync(join(cwd, 'web-test-runner.config.mjs'))) {
+        const hasConfig = existsSync(join(cwd, 'web-test-runner.config.js'))
+          || existsSync(join(cwd, 'web-test-runner.config.mjs'));
+        // Fall back to the test/browser dir only when there is no explicit config.
+        const useBrowserDir = !hasConfig && !serverOnly && existsSync(join(cwd, 'test', 'browser'));
+        // Only resolve + run when there is actually something to run, so a
+        // `webjs test` with no browser tests stays a no-op (not a hard error).
+        if (hasConfig || useBrowserDir) {
+          // Resolve the app's @web/test-runner bin and spawn it with the current
+          // runtime, dropping `npx` (#570; absent in a pure oven/bun image).
+          let wtrPath;
+          try {
+            wtrPath = resolveBin(cwd, '@web/test-runner', 'wtr');
+          } catch {
+            console.error(
+              '\nwebjs test --browser: @web/test-runner is not installed in this project.\n' +
+              'Install it with `npm install -D @web/test-runner @web/test-runner-playwright`.',
+            );
+            process.exit(1);
+          }
           console.log(`\nwebjs test: running browser tests (WTR + Playwright)…\n`);
-          const child = spawn('npx', ['wtr'], {
+          const wtrArgs = hasConfig ? [wtrPath] : [wtrPath, '--files', 'test/browser/**/*.test.js'];
+          const child = spawn(process.execPath, wtrArgs, {
             stdio: 'inherit', cwd, env: { ...process.env },
           });
           const code = await new Promise(r => child.on('exit', r));
           if (code !== 0) process.exit(code ?? 1);
-        } else if (!serverOnly) {
-          // No WTR config, check for test/browser directory
-          const browserDir = join(cwd, 'test', 'browser');
-          if (existsSync(browserDir)) {
-            console.log(`\nwebjs test: running browser tests (WTR + Playwright)…\n`);
-            const child = spawn('npx', ['wtr', '--files', 'test/browser/**/*.test.js'], {
-              stdio: 'inherit', cwd, env: { ...process.env },
-            });
-            const code = await new Promise(r => child.on('exit', r));
-            if (code !== 0) process.exit(code ?? 1);
-          }
         }
       }
 
@@ -492,8 +524,16 @@ Full docs: https://docs.webjs.com`);
       const noInstall = rest.includes('--no-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
+      // to --template (#541). When omitted, scaffoldApp auto-detects bun from
+      // the invoking PM (so `bun create webjs` implies bun).
+      const runtime = flag(rest, '--runtime');
+      if (runtime && !['node', 'bun'].includes(runtime)) {
+        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, install: !noInstall });
+      await scaffoldApp(name, process.cwd(), { template, db, runtime, install: !noInstall });
       break;
     }
     case 'vendor': {

package/lib/create.js

@@ -17,6 +17,7 @@ import { fileURLToPath } from 'node:url';
 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';
 
 /**
  * Detect which package manager invoked us. Reads `npm_config_user_agent`,
@@ -259,6 +260,19 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   if (!VALID_DIALECTS.includes(dialect)) {
     throw new Error(`Unknown --db '${dialect}'. Only ${VALID_DIALECTS.join(' / ')} are supported.`);
   }
+
+  // Runtime axis (#541), ORTHOGONAL to --template (the exactly-3-templates
+  // invariant is untouched). Default node; bun opt-in via `--runtime bun` OR
+  // auto-detected when the scaffold is invoked through bun (`bun create webjs`),
+  // with the explicit flag winning over detection. A bun-flavored app SERVES on
+  // Bun (its dev/start scripts force `--bun`), commits `bun.lock`, sets
+  // `trustedDependencies`, and ships a bun Dockerfile / CI / agent docs.
+  const runtime = opts.runtime || (detectPackageManager() === 'bun' ? 'bun' : 'node');
+  const VALID_RUNTIMES = ['node', 'bun'];
+  if (!VALID_RUNTIMES.includes(runtime)) {
+    throw new Error(`Unknown --runtime '${runtime}'. Only ${VALID_RUNTIMES.join(' / ')} are supported.`);
+  }
+  const isBun = runtime === 'bun';
   const appDir = join(cwd, name);
   if (existsSync(appDir)) {
     console.error(`Error: directory '${name}' already exists.`);
@@ -303,8 +317,19 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // 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.
-      dev: 'webjs dev',
-      start: 'webjs start',
+      //
+      // 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).
+      // 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`,
+      // 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',
@@ -371,6 +396,14 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // applies pending migrations at boot via `webjs db migrate` (drizzle-kit).
       start: { before: ['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');
 
   await writeFile(join(appDir, 'tsconfig.json'), JSON.stringify({
@@ -484,12 +517,39 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     'compose.yaml',
     '.dockerignore',
   ];
+  // Bun runtime (#541): the agent-config markdown shows bun commands, and the
+  // deploy files (Dockerfile / compose / CI) run on Bun. Each is DERIVED from
+  // the canonical node template by a pure transform (see runtime-rewrite.js), so
+  // there is no parallel bun template to drift. Prose files get the command
+  // rewrites; the three infra files get their file-specific transform. On Node,
+  // every file is copied byte-identical (the map is empty).
+  const PROSE_REWRITE = new Set([
+    'AGENTS.md', 'CONVENTIONS.md', '.cursorrules',
+    '.agents/rules/workflow.md', '.github/copilot-instructions.md',
+    // The starter tests carry header comments with run commands (`npx wtr`,
+    // `npm i -D puppeteer-core`); bun-ify those too so a bun app's test files
+    // do not tell the user to run npm/npx (#541 review). The transform only
+    // touches npm/npx command tokens, so the test code itself is unaffected.
+    'test/hello/browser/hello.test.js', 'test/hello/e2e/hello.test.ts',
+  ]);
+  // compose.yaml builds from the (pure oven/bun) Dockerfile and inherits its
+  // `bun --bun run start` CMD; only its healthcheck needs switching off node
+  // (the pure Bun image has no node), which bunifyCompose does.
+  const FILE_REWRITE = {
+    'Dockerfile': bunifyDockerfile,
+    'compose.yaml': bunifyCompose,
+    '.github/workflows/ci.yml': bunifyCi,
+  };
   for (const f of templateFiles) {
     const src = join(TEMPLATES, f);
     if (existsSync(src)) {
       await mkdir(dirname(join(appDir, f)), { recursive: true });
       let content = await readFile(src, 'utf8');
       content = content.replace(/\{\{APP_NAME\}\}/g, name);
+      if (isBun) {
+        if (PROSE_REWRITE.has(f)) content = bunifyProse(content);
+        else if (FILE_REWRITE[f]) content = FILE_REWRITE[f](content);
+      }
       await writeFile(join(appDir, f), content);
     }
   }
@@ -717,6 +777,15 @@ export default cors({
 
     await writeFile(join(appDir, 'modules', 'users', 'queries', 'list-users.server.ts'), `'use server';
 
+// A GET server action (#488): a read declares its HTTP semantics via reserved
+// sibling exports the framework reads statically. 'method' makes the call ride
+// the URL (cacheable, ETag/304-aware, SSR-seeded on first paint); 'cache' is the
+// max-age in seconds (private by default, do NOT add { public: true } unless the
+// data is identical for EVERY visitor); 'tags' label the cached entry so a
+// mutation can evict it. One function per file.
+export const method = 'GET';
+export const cache = 30;
+export const tags = () => ['users'];
 export async function listUsers() {
   // TODO: replace with real data source
   return [
@@ -727,6 +796,11 @@ export async function listUsers() {
 `);
     await writeFile(join(appDir, 'modules', 'users', 'actions', 'create-user.server.ts'), `'use server';
 
+// A mutation server action (#488). With no 'method' export it defaults to POST
+// (CSRF-protected, rich request body). 'invalidates' lists the cache tags to
+// evict on success, so the next listUsers() read refetches fresh instead of
+// serving a stale browser-cached value. One function per file.
+export const invalidates = () => ['users'];
 export async function createUser(input: { name: string; email: string }) {
   // TODO: validate input, persist to database
   return { success: true, data: { id: Date.now().toString(), ...input } };
@@ -1173,7 +1247,7 @@ ThemeToggle.register('theme-toggle');
   // --- SaaS template extras: auth, dashboard, drizzle User model ---
   if (isSaas) {
     const { writeSaasFiles } = await import('./saas-template.js');
-    await writeSaasFiles(appDir);
+    await writeSaasFiles(appDir, { runtime });
   }
 
   // AGENTS.md is already in place via the shared `templateFiles` loop
@@ -1264,7 +1338,10 @@ For AI agents, read this before editing scaffolded files:
   // pnpm / yarn / bun users get their own. Pass `--no-install` (or
   // `{ install: false }` to scaffoldApp) to opt out, e.g. for CI tests
   // that exercise the scaffold without paying the install cost.
-  const pm = detectPackageManager();
+  // In bun mode, install with bun regardless of the invoking PM, so the app
+  // commits `bun.lock` (text JSONC, git-diffable) instead of `package-lock.json`
+  // (#541). Otherwise honour the invoking PM (npm / pnpm / yarn / bun).
+  const pm = isBun ? 'bun' : detectPackageManager();
   let installed = false;
   if (shouldInstall) {
     console.log(`Running '${pm} install' in ${name}/ ...\n`);

package/lib/resolve-bin.js

@@ -0,0 +1,42 @@
+/**
+ * Resolve a dependency's executable from an app's node_modules (#570).
+ *
+ * `webjs db` / `webjs test --browser` used to shell `npx drizzle-kit` / `npx
+ * wtr`, but `npx` is absent in a pure `oven/bun` image (and the whole point of
+ * runtime-native commands is to run under whatever the current runtime is). So
+ * instead resolve the tool's bin from the APP's node_modules and let the caller
+ * spawn it with `process.execPath` (Node or Bun), the same pattern `webjs
+ * typecheck` uses for the app's `tsc`.
+ *
+ * The wrinkle: CLIs like drizzle-kit and @web/test-runner do NOT expose
+ * `./package.json` or their bin subpath in `exports`, so `require.resolve(
+ * 'drizzle-kit/bin.cjs')` throws `ERR_PACKAGE_PATH_NOT_EXPORTED`. The `.` main
+ * entry DOES resolve, so resolve that, walk up to the package root (the nearest
+ * dir with a package.json), and read the `bin` field, which is version-robust.
+ */
+import { createRequire } from 'node:module';
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+
+/**
+ * @param {string} cwd  the app root (a dir containing the app's package.json)
+ * @param {string} pkgName  the dependency package name (e.g. 'drizzle-kit')
+ * @param {string} binName  the key in the package's `bin` map (e.g. 'wtr');
+ *   ignored when `bin` is a plain string
+ * @returns {string} absolute path to the bin's JS entry
+ * @throws if the package is not installed or has no matching bin
+ */
+export function resolveBin(cwd, pkgName, binName) {
+  const req = createRequire(join(cwd, 'package.json'));
+  // `.` (the main entry) is exported even when subpaths are not.
+  let pkgDir = dirname(req.resolve(pkgName));
+  while (!existsSync(join(pkgDir, 'package.json'))) {
+    const parent = dirname(pkgDir);
+    if (parent === pkgDir) throw new Error(`package.json not found for ${pkgName}`);
+    pkgDir = parent;
+  }
+  const pkg = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8'));
+  const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.[binName];
+  if (!binRel) throw new Error(`bin '${binName}' not found in ${pkgName}`);
+  return resolve(pkgDir, binRel);
+}

package/lib/runtime-rewrite.js

@@ -0,0 +1,189 @@
+/**
+ * Bun-first scaffold rewrites (#541).
+ *
+ * The scaffold authors every template in its node/npm form (ONE source of
+ * truth, no drift) and DERIVES the bun-mode variant by transform when the app
+ * is scaffolded with `--runtime bun` (or through `bun create webjs`). These are
+ * pure string transforms so they unit-test without touching the filesystem.
+ *
+ * Why a transform and not a second set of template files: the agent-config
+ * markdown (AGENTS.md / CONVENTIONS.md / .cursorrules / ...) plus the deploy
+ * files (Dockerfile / ci.yml) are long and change often; a parallel bun copy
+ * would silently drift from the node original. A transform keeps the node
+ * template canonical and the bun output a deterministic function of it.
+ *
+ * The runtime axis is ORTHOGONAL to `--template` (the exactly-3-templates
+ * invariant is untouched, this is a separate dimension).
+ *
+ * WHAT RUNS ON BUN, AND WHAT DOES NOT (the load-bearing design decision):
+ * the SERVER (the `dev` / `start` scripts) runs on Bun, because that is the
+ * app. The dev/build TOOLING (`webjs test` / `db:*` / `check` / `typecheck`)
+ * stays on Node, because `webjs test` spawns `node --test` (Bun has no
+ * `--test` flag; its runner is `bun test`). So:
+ *   - the `dev` / `start` scripts force `bun --bun` (the server is Bun),
+ *   - every other command stays `bun run` / `webjs ...` (runs on Node via the
+ *     `webjs` bin's `#!/usr/bin/env node` shebang),
+ *   - the Dockerfile is a pure `oven/bun:1` base (#595). This is safe as of
+ *     `@webjsdev/cli@0.10.20` (#570): `webjs db migrate` resolves drizzle-kit
+ *     and runs it under Bun (no `npx`), so a Node-less image works. (Before
+ *     #570 shipped as `latest`, this stayed on `node:24-alpine` + a copied Bun
+ *     binary, since the installed CLI could still shell `npx`.)
+ */
+
+/**
+ * Rewrite command-shaped npm/npx invocations in prose (markdown / agent config /
+ * the starter-test header comments) to their bun equivalents.
+ *
+ * `npm run dev` / `start` become `bun --bun run` (the `--bun` overrides the
+ * `webjs` bin's Node shebang so the SERVER runs on Bun). Every OTHER script
+ * becomes a plain `bun run` (Node tooling: forcing `--bun` on `webjs test`
+ * would spawn the invalid `bun --test`). Bare "npm" as a word (e.g. "a
+ * third-party npm package", "the npm registry") is left alone: packages still
+ * come from npm, only the COMMAND changes.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function bunifyProse(s) {
+  return s
+    // Prose claim about the Dockerfile CMD (AGENTS.md dev-start parity section);
+    // the bun Dockerfile's CMD becomes `bun --bun run start`.
+    .replaceAll('`CMD ["npm", "start"]`', '`CMD ["bun", "--bun", "run", "start"]`')
+    // The "Containerized deploy" prose describes the node template's
+    // node:24-alpine base; the bun Dockerfile is a pure oven/bun:1 image (#595),
+    // so rewrite the base claim to match what the bun app actually ships. (The
+    // trailing `npm start` is rewritten to `bun --bun run start` by the generic
+    // rule below.)
+    .replaceAll(
+      '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.
+    .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')
+    .replaceAll('npm create webjs', 'bun create webjs')
+    // dev-dep installs (`npm install -D` and the `npm i -D` shorthand)
+    .replace(/npm install -D /g, 'bun add -d ')
+    .replace(/npm install --save-dev /g, 'bun add -d ')
+    .replace(/npm i -D /g, 'bun add -d ')
+    // a package install (followed by a package name) -> `bun add <pkg>`
+    .replace(/npm install (?=[A-Za-z@])/g, 'bun add ')
+    .replace(/npm i (?=[A-Za-z@])/g, 'bun add ')
+    // bare install / ci -> `bun install`
+    .replace(/npm install\b/g, 'bun install')
+    .replace(/npm ci\b/g, 'bun install')
+    // The SERVER scripts run on Bun (force --bun, overriding the Node shebang).
+    .replace(/npm run dev\b/g, 'bun --bun run dev')
+    .replace(/npm run start\b/g, 'bun --bun run start')
+    .replace(/npm start\b/g, 'bun --bun run start')
+    // Every other script is Node tooling (webjs test -> node --test, db -> npx
+    // drizzle-kit): a plain `bun run` lets the shebang pick Node. NEVER --bun
+    // here (it would make `webjs test` spawn the invalid `bun --test`).
+    .replace(/npm run /g, 'bun run ')
+    .replace(/npm test\b/g, 'bun run test')
+    // one-off executors
+    .replace(/npx /g, 'bunx ');
+}
+
+/**
+ * Rewrite the scaffolded Dockerfile for Bun.
+ *
+ * Base decision (acceptance criterion): a pure `oven/bun:1` image (no Node).
+ * Safe as of `@webjsdev/cli@0.10.20` (#570): `webjs db` / `webjs test` resolve
+ * their tools (drizzle-kit, wtr) and spawn them with the current runtime instead
+ * of `npx`, so the boot-time `webjs db migrate` runs under Bun with no Node
+ * toolchain. (Before #570 was the published `latest`, this stayed on a
+ * `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.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function bunifyDockerfile(s) {
+  return s
+    // Top comment: explain the pure oven/bun base.
+    .replace(
+      /# webjs serves \.ts directly[\s\S]*?since the built-in stripper and recursive fs\.watch need it\.\n/,
+      '# webjs serves .ts directly by stripping types at the runtime layer, so there is\n' +
+      '# NO JavaScript build step (webjs is buildless end to end; there is no bundler or\n' +
+      '# esbuild fallback). This image runs the app on **Bun**: the type-strip comes from\n' +
+      '# `amaro`, the server serves via Bun.serve, and `webjs db migrate` runs under Bun\n' +
+      '# (the CLI resolves drizzle-kit without npx, #570), so no Node is needed. webjs also\n' +
+      '# runs on Node 24+; for a Node base instead, swap to `node:24-alpine` and start with\n' +
+      '# `npm start`.\n',
+    )
+    .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',
+    )
+    // 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',
+    )
+    // Healthcheck: the pure Bun image has no node; use `bun -e`. Keep the
+    // dependency-free-probe comment accurate (the probe runs under Bun now).
+    .replace("(Node 24's built-in fetch, no curl/wget)", "(the runtime's built-in fetch, no curl/wget)")
+    .replace('CMD ["node", "-e", "fetch(', 'CMD ["bun", "-e", "fetch(')
+    // Entrypoint: serve on Bun.
+    .replace(
+      /# `npm start` is a thin alias[\s\S]*?the migrate no longer depends on an npm `prestart` hook\.\nCMD \["npm", "start"\]/,
+      '# `bun --bun run start` runs the `start` script on Bun (the server serves via\n' +
+      '# Bun.serve). `webjs start` runs the `webjs.start.before` step (`webjs db migrate`,\n' +
+      '# which resolves drizzle-kit and runs it under Bun, no npx, #570), idempotent / a\n' +
+      '# no-op with no pending migrations, then serves on $PORT.\n' +
+      'CMD ["bun", "--bun", "run", "start"]',
+    );
+}
+
+/**
+ * Rewrite compose.yaml for the pure-Bun image (#595): its healthcheck runs in
+ * the `oven/bun:1` container (compose's healthcheck overrides the Dockerfile's),
+ * which has no `node`, so switch `node -e` to `bun -e`. compose otherwise builds
+ * from the Dockerfile and inherits its `bun --bun run start` CMD, so nothing
+ * else changes.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function bunifyCompose(s) {
+  return s.replace('test: ["CMD", "node", "-e", "fetch(', 'test: ["CMD", "bun", "-e", "fetch(');
+}
+
+/**
+ * Rewrite the GitHub Actions CI workflow for Bun: ADD `oven-sh/setup-bun`
+ * alongside `actions/setup-node` (kept, because the `webjs` test/db/check
+ * tooling runs on Node), install with `bun install` (uses bun.lock), and run
+ * scripts with a plain `bun run` (the script bodies' `webjs ...` resolve to Node
+ * via the shebang, and dev/start are not run in CI). The `node -e` Chromium-path
+ * step stays (Node is present from setup-node).
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function bunifyCi(s) {
+  return s
+    // Keep the Node setup (the tooling needs it), add Bun for `bun install`.
+    // Drop `cache: npm` (the cache is bun's now; setup-bun caches by default).
+    .replaceAll(
+      "- uses: actions/setup-node@v6\n        with:\n          node-version: '24'\n          cache: npm",
+      "- uses: actions/setup-node@v6\n        with:\n          node-version: '24'\n      - uses: oven-sh/setup-bun@v2\n        with:\n          bun-version: latest",
+    )
+    .replaceAll('- run: npm ci', '- run: bun install')
+    .replaceAll('npm install --no-save ', 'bun add --no-save ')
+    .replaceAll('npm run ', 'bun run ')
+    .replaceAll('npx ', 'bunx ');
+}

package/lib/saas-template.js

@@ -4,6 +4,7 @@
  */
 
 import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { bunifyProse } from './runtime-rewrite.js';
 import { existsSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -42,8 +43,10 @@ async function copyUiComponents(appDir, names) {
 
 /**
  * @param {string} appDir
+ * @param {{ runtime?: 'node'|'bun' }} [opts]
  */
-export async function writeSaasFiles(appDir) {
+export async function writeSaasFiles(appDir, opts = {}) {
+  const isBun = opts.runtime === 'bun';
   // SaaS pages use auth forms, so copy the extra ui-* components on top of
   // the standard set the full-stack scaffold already wrote. Pre-importing
   // them in login/signup/dashboard pages below means the dev server will
@@ -145,6 +148,12 @@ export async function writeSaasFiles(appDir) {
     "",
     "import { auth } from '#lib/auth.server.ts';",
     "",
+    "// This read deliberately stays POST-default (no 'method' export). A GET",
+    "// server action (#488) is cacheable and SSR-seeded, which is wrong for a",
+    "// per-session read: the result differs per user and changes on sign-in /",
+    "// sign-out, so it must never be browser-cached or shared. Reserve GET +",
+    "// cache + tags for data identical for every visitor (see",
+    "// modules/users/queries/list-users.server.ts in the full-stack template).",
     "export async function currentUser() {",
     "  const session = await auth();",
     "  return session?.user ?? null;",
@@ -181,7 +190,10 @@ export async function writeSaasFiles(appDir) {
   //   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.
   await mkdir(join(appDir, 'test', 'auth'), { recursive: true });
-  await writeFile(join(appDir, 'test', 'auth', 'auth.test.ts'), [
+  // 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
+  // plain `bun run`, not the --bun server form). The transform is a no-op on Node.
+  const authTest = [
     "import { test } from 'node:test';",
     "import assert from 'node:assert/strict';",
     "import { fileURLToPath } from 'node:url';",
@@ -260,7 +272,11 @@ export async function writeSaasFiles(appDir) {
     "  assert.match(body, /Dashboard/, 'the dashboard content rendered');",
     "});",
     "",
-  ].join('\n'));
+  ].join('\n');
+  await writeFile(
+    join(appDir, 'test', 'auth', 'auth.test.ts'),
+    isBun ? bunifyProse(authTest) : authTest,
+  );
 
   // app/api/auth/[...path]/route.ts
   await mkdir(join(appDir, 'app', 'api', 'auth', '[...path]'), { recursive: true });

package/package.json

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

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

@@ -34,6 +34,13 @@ FIRST, before writing any code:
    - If on main/master: create a feature branch before editing.
    - If on a feature branch: verify it matches the current task.
 2. Sync: `git fetch origin && git rebase origin/main` if behind.
+3. If more than one agent may work this repo at once, use a DEDICATED git
+   worktree per task (`git worktree add -b <branch> ../<repo>-<slug> origin/main`,
+   `cd` in, work there, `git worktree remove` after merge), never a shared
+   checkout. Two agents in one directory collide: a `git checkout` in one moves
+   HEAD under the other, so commits land on the wrong branch. Git enforces
+   one-branch-per-worktree, so worktrees prevent it. A lone agent in a clean
+   checkout may use a plain branch.
 
 ## Autonomous mode (sandbox / no-prompt)
 

package/templates/.cursorrules

@@ -7,10 +7,10 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**.
 
 ## Persistence + scaffold rules (non-negotiable)
 
-- **Use Prisma + SQLite for data, never JSON files.** It's already wired up
-  (`prisma/schema.prisma`, `lib/prisma.server.ts`, `npm run db:migrate`). For ANY
+- **Use Drizzle + SQLite for data, never JSON files.** It's already wired up
+  (`db/schema.server.ts`, `db/connection.server.ts`, `npm run db:generate` + `npm run db:migrate`). For ANY
   data the app stores (todos, posts, messages, products, comments…),
-  define a Prisma model. NEVER create `data/*.json`, `db.json`, or any
+  define a Drizzle table. NEVER create `data/*.json`, `db.json`, or any
   JSON file as a fake database. NEVER use module-scope arrays / Maps as
   a substitute. NEVER use localStorage for app data. These are project conventions in CONVENTIONS.md (a JSON file used as a
   database resets on reload and cannot scale).
@@ -35,6 +35,12 @@ FIRST, before writing any code:
 2. Sync with parent: `git fetch origin && git log HEAD..origin/main --oneline`
    - If upstream has new commits: `git rebase origin/main` before starting.
    - Resolve any conflicts before proceeding with the task.
+3. If more than one agent may work this repo at once, use a DEDICATED git
+   worktree per task, not a shared checkout: `git worktree add -b <branch>
+   ../<repo>-<slug> origin/main`, `cd` in, work there, `git worktree remove`
+   after merge. Two agents in one directory collide (a `git checkout` in one
+   moves HEAD under the other, so commits land on the wrong branch). A lone
+   agent in a clean checkout may use a plain branch.
 
 ## Autonomous mode (sandbox / no-prompt)
 
@@ -107,7 +113,7 @@ self-review loop.
 - Shadow-DOM components opt in with `static shadow = true` and use `static styles = css` for scoped CSS, not inline styles. That is the right home for scoped CSS.
 - One function per server action file (*.server.ts)
 - Components must call customElements.define('tag', Class)
-- Server-only code (@prisma/client, 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. lib/ holds both server-only infra (lib/prisma.server.ts) 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 `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.
 - Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat` ship. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported. 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/.dockerignore

@@ -23,11 +23,12 @@ out
 .env
 !.env.example
 
-# Prisma local SQLite. Schema + migrations ship; the runtime volume owns the db.
-dev.db
-dev.db-journal
-prisma/dev.db
-prisma/dev.db-journal
+# Local SQLite database (Drizzle, sqlite dialect). Schema + migrations ship;
+# the runtime volume owns the db file. Matches the `db/dev.db*` rule the
+# scaffold appends to `.gitignore` for the sqlite dialect (no-op for postgres).
+db/dev.db
+db/dev.db-journal
+db/dev.db-*
 
 # logs
 *.log

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

@@ -32,6 +32,12 @@ FIRST, before writing any code:
    - If on main/master: create a feature branch before editing.
    - If on a feature branch: verify it matches the task at hand.
 2. Sync: `git fetch origin && git rebase origin/main` if behind.
+3. If more than one agent may work this repo at once, use a DEDICATED git
+   worktree per task (`git worktree add -b <branch> ../<repo>-<slug> origin/main`,
+   `cd` in, work there, `git worktree remove` after merge), never a shared
+   checkout. Two agents in one directory collide: a `git checkout` in one moves
+   HEAD under the other, so commits land on the wrong branch. A lone agent in a
+   clean checkout may use a plain branch.
 
 ## Autonomous mode (sandbox / no-prompt)
 
@@ -101,7 +107,7 @@ 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 WebComponent, declare `static properties` (and `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.
+- 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`).
 - 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.
@@ -109,5 +115,5 @@ each change must include.
 - Context: import { createContext, ContextProvider, ContextConsumer } from '@webjsdev/core/context'
 - Task: import { Task, TaskStatus } from '@webjsdev/core/task'
 - Routing: file-based under app/ (page.ts, layout.ts, route.ts, middleware.ts).
-- Component state lives in signals from @webjsdev/core. Module-scope signals share state across components; instance signals (created in the constructor) carry component-local state. Reactive properties (static properties + declare) are for HTML attributes and .prop=${...} hydration.
+- Component state lives in signals from @webjsdev/core. Module-scope signals share state across components; instance signals (created in the constructor) carry component-local state. Reactive properties (declared via the `WebComponent({ ... })` factory) are for HTML attributes and .prop=${...} hydration.
 - Don't skip tests or documentation updates.

package/templates/.hooks/pre-commit

@@ -11,9 +11,20 @@
 # here, so a commit stays fast and the test gate cannot be skipped by a
 # local --no-verify. The CI workflow runs `webjs check` + `webjs test`
 # on every push and pull request.
+#
+# Running more than one AI agent on this repo at once? Give each task its own
+# git worktree, not a shared checkout. Two agents in one working directory
+# collide: a `git checkout` in one moves HEAD under the other, so the next
+# commit lands on the wrong branch. Before committing, confirm the branch below
+# is the one you intended; if it moved, you are sharing a checkout. Isolate:
+#   git worktree add -b <branch> ../<app>-<task> origin/main && cd ../<app>-<task>
 
 BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null)
 
+# Surface the branch so a wrong-branch commit (a concurrent-agent HEAD move) is
+# visible in the commit output rather than silent.
+echo "[pre-commit] committing on branch: ${BRANCH:-<detached>}"
+
 if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
   echo ""
   echo "ERROR: Cannot commit directly to '$BRANCH'."

package/templates/AGENTS.md

@@ -163,8 +163,9 @@ entry, its own template parser. Inside `` html`…` `` templates you get:
 - Binding-aware completions: reachable tag names after `<`, and
   prefix-keyed attributes (`.prop` property names, `?bool` / plain
   hyphenated attribute names).
-- Diagnostics: value type-checks against `declare propName: T`, unquoted
-  `@`/`.`/`?` bindings, and expressionless `.prop` bindings.
+- Diagnostics: value type-checks against the reactive props declared in
+  `WebComponent({ ... })`, unquoted `@`/`.`/`?` bindings, and
+  expressionless `.prop` bindings.
 - Hover showing the component class / declared member type.
 
 In VS Code / Cursor / Windsurf, the **`webjs` extension** bundles this
@@ -597,12 +598,13 @@ const secret = process.env.AUTH_SECRET;             // undefined (fail-closed)
 ```ts
 import { WebComponent, html, css } from '@webjsdev/core';
 
-export class Counter extends WebComponent {
-  static properties = { count: { type: Number } };
+// Recommended declare-free base-class factory style
+export class Counter extends WebComponent({
+  count: Number
+}) {
   static styles = css`button { padding: 8px 12px; }`;   // shadow-DOM only
   // static shadow = true;          // opt into shadow DOM (default: light DOM)
   // static lazy = true;             // download JS only when scrolled into view
-  declare count: number;             // TypeScript-only typed accessor
 
   constructor() {
     super();
@@ -629,8 +631,9 @@ the click handler is inert). Two consequences for how you write code:
 1. **Defaults for the first paint go in `constructor()`** (after
    `super()`), never as class-field initializers (which break
    reactivity) and never in `connectedCallback` (which the server
-   doesn't run). For Web Component properties with `declare`, set the
-   default in the constructor.
+   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 })`).
 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
@@ -659,7 +662,8 @@ See [Progressive Enhancement](https://docs.webjs.dev/docs/progressive-enhancemen
 ## Lit muscle-memory gotchas (read if you have written lit before)
 
 Webjs's runtime API matches lit. The `WebComponent` base class,
-`static properties`, the lifecycle hooks, ReactiveControllers, the
+reactive properties (declared via the `WebComponent({ ... })` factory),
+the lifecycle hooks, ReactiveControllers, the
 directive set, `html` / `css` tagged templates. The **rendering
 model**, however, is different. Pure-lit patterns that work fine in a
 client-only lit app break in webjs's SSR pipeline or its reactivity
@@ -714,11 +718,12 @@ Practical consequences for agents writing webjs code.
 | Assuming an `async render()` always ships its module | A bare one (no other client signal) is ELIDED, so it costs zero JS and skips the on-hydration re-fetch, first paint unchanged | Rely on it for a fetch-and-display leaf. `static refresh = true` keeps the on-load refresh, `static shadow = true` always ships |
 | `window.X` / `document.X` in constructor or `render()` | SSR crash | Move to `connectedCallback` |
 | Top-level `import` of a browser-only library | SSR crash | Dynamic `import()` inside `connectedCallback` |
-| Class-field initializer for a reactive property (`student: Student = {...}`) | Silently breaks reactivity (overwrites the framework accessor) | `declare student: Student` plus constructor default |
-| `@property()` decorator | Banned by invariant 10 (erasable TS) | `static properties = { ... }` plus `declare` |
+| Class-field initializer for a reactive property (`student: Student = {...}`) | Silently breaks reactivity (overwrites the framework accessor) | Pass the shape to the base-class factory `WebComponent({ student: Object })` and set the default in the constructor (flagged by `reactive-props-no-class-field`) |
+| `@property()` decorator | Banned by invariant 10 (erasable TS) | Pass the shape to the base-class factory `WebComponent({ ... })` (the only supported form) |
+| Hand-written `static properties = { ... }` | Throws at construction (the factory owns property setup) | Pass the same shape to the base-class factory `WebComponent({ ... })` (flagged by `no-static-properties`) |
 | Scoped `static styles = css` or an inline `<style>` with semantic class names (`.hero`, `.card`) in a light-DOM component | Scoped block does nothing without `static shadow = true`; inline `<style>` class names leak globally | Tailwind utilities (the light-DOM default); or `static shadow = true` for genuinely scoped CSS |
 | `willUpdate` computing SSR-visible derived state | Works (runs at SSR), but overriding it opts the component out of elision | Fine for interactive components; for display-only, derive inline in `render()` |
-| `this.hasAttribute` / `getAttribute` in `render()` | Works (server attribute shim backs the attribute methods at SSR) | Read attributes directly, or via a `static properties` + `declare` reactive prop |
+| `this.hasAttribute` / `getAttribute` in `render()` | Works (server attribute shim backs the attribute methods at SSR) | Read attributes directly, or declare a reactive prop via the base-class factory `WebComponent({ ... })` |
 | `ContextProvider` for server-known data | Default value during SSR, content shift on hydration | Pass via props from the page function |
 
 The full annotated catalog with code examples lives in the framework
@@ -767,6 +772,19 @@ export async function createPost(input: { title: string; body: string }) {
 Import it from a client component. The framework rewrites it into a
 type-safe RPC stub automatically.
 
+A server action is a POST by default, but reserved sibling exports change its
+HTTP semantics without changing the call site (`await getUser(7)` stays the
+same): `export const method = 'GET'` (a read; rides args in the URL, CSRF-exempt,
+cacheable), `export const cache = 60` + `export const tags` (GET response
+caching), `export const invalidates` (a mutation's tags to evict), `export const
+middleware` (a per-action chain, `actionContext()`), and `export const validate`
+(the boundary validator). One callable function per configured file. An action
+that RETURNS a `ReadableStream` / async generator streams its chunks (consume
+with `for await`); read the request `AbortSignal` via `actionSignal()` to cancel
+on disconnect. **SAFETY:** a `cache` with `public: true` shares one response
+across all users, so use it only for data identical for every visitor. Full
+reference: https://docs.webjs.com/docs/server-actions
+
 ## Client navigation patterns (auto-magic)
 
 The client router enables itself when the scaffolded root layout imports
@@ -1205,7 +1223,14 @@ composition, so a nested shell ends up dropped by the HTML parser.
 
 ## Workflow expectations for AI agents
 
-1. Branch before editing. Never push to `main` directly.
+1. Branch before editing. Never push to `main` directly. **If more than one
+   agent may work this repo at once, give each task its own git worktree, not a
+   shared checkout** (`git worktree add -b <branch> ../<repo>-<slug> origin/main`,
+   `cd` in, work there, `git worktree remove` after merge). Two agents in one
+   working directory collide: a `git checkout` in one moves `HEAD` under the
+   other, so the next commit lands on the wrong branch. Git enforces
+   one-branch-per-worktree, so worktrees prevent it; a lone agent in a clean
+   checkout may use a plain branch.
 2. Every code change comes with a test, AGENTS.md / docs updates if the
    feature surface changed, `webjs check` passing. A unit test is not
    always enough: a component, hydration, the client router, or a server

package/templates/CONVENTIONS.md

@@ -60,6 +60,14 @@ even if the user doesn't explicitly ask.**
 3. If on a feature branch → verify it matches the current task
 4. Sync with parent: `git fetch origin && git rebase origin/main` if behind
 5. Don't mix unrelated work on the wrong branch
+6. **If more than one agent may work this repo at once, use a dedicated git
+   worktree per task, never a shared checkout.** Two agents in one working
+   directory collide: a `git checkout` in one moves `HEAD` under the other, so
+   the next commit lands on the wrong branch. Isolate each task:
+   `git worktree add -b <branch> ../<repo>-<slug> origin/main`, `cd` in, work
+   there, and `git worktree remove` after the PR merges. Git enforces
+   one-branch-per-worktree, so this makes the collision impossible. A lone agent
+   in a clean checkout may use a plain branch.
 
 ### After cloning: verify the toolchain
 
@@ -635,10 +643,11 @@ Any stateful behavior with a Tier-2 element uses the element.
 ```ts
 import { WebComponent, html } from '@webjsdev/core';
 
-export class MyWidget extends WebComponent {
-  static properties = { label: { type: String }, count: { type: Number } };
-  declare label: string;
-  declare count: number;
+// Recommended declare-free base-class factory style
+export class MyWidget extends WebComponent({
+  label: String,
+  count: Number
+}) {
   // Light DOM is the default; Tailwind utility classes apply directly.
 
   constructor() {
@@ -660,16 +669,7 @@ export class MyWidget extends WebComponent {
 MyWidget.register('my-widget');
 ```
 
-`static properties` is the runtime declaration (reactive accessor,
-attribute coercion, reflection). `declare` types the field for
-TypeScript without emitting a class-field initializer that would
-clobber the reactive accessor at construction time. The two
-declarations together give 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 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.
 
 **Rules:**
 - One component per file
@@ -680,15 +680,8 @@ value/binding diagnostics, hover); in VS Code / Cursor / Windsurf the
   - `my-widget .body`, `my-widget .title` (descendant selector)
 - Tag name must contain a hyphen (HTML spec)
 - Always call `Class.register('tag')`. That's the standard DOM API.
-- **Reactive props use `declare propName: Type` (no value) plus a default in `constructor()` after `super()`.** Never write `propName = value` or `propName: Type = value` as a class-field initializer. It compiles to `Object.defineProperty(this, …)` after `super()` and clobbers the framework's reactive accessor, silently breaking re-renders. `webjs check` flags this via the `reactive-props-use-declare` rule.
-- 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 (`static properties =
-  { foo: { type: ... } }` with a sibling `declare foo: T`) wrap HTML
-  attributes, attribute reflection, and `.prop=${value}` SSR
-  hydration.
+- **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.
+- 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
 
 ---
@@ -997,7 +990,8 @@ component, applies its attributes, runs `willUpdate` and controllers'
 `firstUpdated`, `updated`, or any other browser-only lifecycle hook.
 Whatever state should appear on first paint MUST be set in the
 constructor (after `super()`), derived in `willUpdate`, or derivable
-from `static properties` + attributes on the rendered tag. Reading
+from the factory-declared reactive props + attributes on the rendered
+tag. Reading
 `this.getAttribute` / `hasAttribute` in `render()` works server-side (a
 server attribute shim backs the attribute methods), but a `Task`'s
 fetch still runs only on the client.