@webjsdev/cli 0.10.23 → 0.10.24

package/lib/create.js

@@ -273,6 +273,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     throw new Error(`Unknown --runtime '${runtime}'. Only ${VALID_RUNTIMES.join(' / ')} are supported.`);
   }
   const isBun = runtime === 'bun';
+  // Zero-install Bun entry (#675): the app-local `webjs-bun.mjs` bootstrap, run
+  // under `bun --bun`, so the server resolves the CLI + deps via Bun auto-install
+  // (no `bun install` required). App-local so it is resolvable with no node_modules.
+  const bunBoot = 'bun --bun webjs-bun.mjs';
   const appDir = join(cwd, name);
   if (existsSync(appDir)) {
     console.error(`Error: directory '${name}' already exists.`);
@@ -318,18 +322,19 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // so `npm run start` (a thin alias) behaves identically. Drizzle has no
       // codegen, so there is no dev `before` step.
       //
-      // Bun runtime (#541): the long-running server scripts (`dev` / `start`)
-      // are prefixed `bun --bun` so the app SERVES on Bun. The `--bun` overrides
-      // the `webjs` bin's `#!/usr/bin/env node` shebang (without it `bun run dev`
+      // Bun runtime (#541, zero-install #675): the server + DB scripts run via
+      // the `webjs-bun.mjs` bootstrap under `bun --bun`. `--bun` overrides the
+      // `webjs` bin's `#!/usr/bin/env node` shebang (without it `bun run dev`
       // would exec webjs under Node, silently running the "bun" app on Node).
-      // Baking it into the script body means a plain `bun run dev` (or even
-      // `npm run dev`) starts on Bun, so a user never has to remember the flag.
-      // The runtime-neutral tooling scripts below (test / db / check / typecheck
+      // Routing through the bootstrap file (which imports the CLI by bare
+      // specifier) instead of the `webjs` bin means Bun's auto-install resolves
+      // `@webjsdev/*` and your deps ON DEMAND, so `bun run dev` / `start` work
+      // with NO `bun install` (install becomes optional, for editor types /
+      // offline). The runtime-neutral tooling scripts (test / check / typecheck
       // / doctor) stay plain `webjs ...`: they spawn node tooling (`node --test`,
-      // drizzle-kit, tsc) and forcing `--bun` there buys nothing (and `webjs
-      // test` shells `node --test`, which a `bun --test` would not be).
-      dev: isBun ? 'bun --bun webjs dev' : 'webjs dev',
-      start: isBun ? 'bun --bun webjs start' : 'webjs start',
+      // tsc), which needs an install, so they are not part of the zero-install path.
+      dev: isBun ? `${bunBoot} dev` : 'webjs dev',
+      start: isBun ? `${bunBoot} start` : 'webjs start',
       test: 'webjs test',
       'test:server': 'webjs test --server',
       'test:browser': 'webjs test --browser',
@@ -340,17 +345,19 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       // vendor pins, @webjsdev versions, git hook). Local tool, NOT a CI gate
       // (its env-drift + network pin-freshness checks would make CI flaky).
       doctor: 'webjs doctor',
-      'db:generate': 'webjs db generate',
-      'db:migrate': 'webjs db migrate',
-      'db:push': 'webjs db push',
-      'db:studio': 'webjs db studio',
-      'db:seed': 'webjs db seed',
+      'db:generate': isBun ? `${bunBoot} db generate` : 'webjs db generate',
+      'db:migrate': isBun ? `${bunBoot} db migrate` : 'webjs db migrate',
+      'db:push': isBun ? `${bunBoot} db push` : 'webjs db push',
+      'db:studio': isBun ? `${bunBoot} db studio` : 'webjs db studio',
+      'db:seed': isBun ? `${bunBoot} db seed` : 'webjs db seed',
     },
     dependencies: {
       // Drizzle ORM (no codegen, no engine binary). Pinned to the 1.0 line
-      // for relations v2. The SQLite/Postgres driver below is dialect-picked.
+      // 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.
       'drizzle-orm': '^1.0.0-rc.3',
-      ...(dialect === 'postgres' ? { pg: '^8.13.0' } : { 'better-sqlite3': '^12.11.1' }),
+      ...(dialect === 'postgres' ? { pg: '^8.13.0' } : {}),
       '@webjsdev/cli': 'latest',
       '@webjsdev/core': 'latest',
       '@webjsdev/server': 'latest',
@@ -394,18 +401,28 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     webjs: {
       // Drizzle has no codegen, so there is no dev `before` step. Production
       // applies pending migrations at boot via `webjs db migrate` (drizzle-kit).
-      start: { before: ['webjs db migrate'] },
+      // On Bun this runs through the same zero-install bootstrap as `start`, so
+      // the boot-time migrate needs no `webjs` bin in node_modules (#675).
+      start: { before: [isBun ? `${bunBoot} db migrate` : 'webjs db migrate'] },
     },
-    // Bun runtime (#541): Bun does NOT run a dependency's postinstall by default
-    // (a security default); a package must be listed here for its install script
-    // to run on `bun install`. The sqlite driver `better-sqlite3` fetches its
-    // native prebuild in a postinstall, so without this the native binding is
-    // missing and the app crashes at first DB access. Postgres `pg` is pure JS
-    // (no postinstall), so the list is sqlite-only. Omitted entirely on Node
-    // (npm runs postinstalls), keeping the node-mode package.json byte-identical.
-    ...(isBun && dialect !== 'postgres' ? { trustedDependencies: ['better-sqlite3'] } : {}),
   }, null, 2) + '\n');
 
+  // The zero-install Bun entry (#675). `bun run dev` / `start` invoke this via
+  // `bun --bun` (see the scripts above). Importing the webjs CLI by bare
+  // specifier lets Bun auto-install resolve `@webjsdev/*` and your deps on
+  // demand, so a fresh app serves with NO `bun install`. The CLI reads its
+  // command (dev / start / db ...) and flags straight from argv. Node apps do
+  // not get this file; they run the `webjs` bin directly.
+  if (isBun) {
+    await writeFile(join(appDir, 'webjs-bun.mjs'),
+      '// Zero-install Bun entry (webjs #675). Run via `bun --bun webjs-bun.mjs <cmd>`\n' +
+      '// (the dev / start / db npm scripts do this). Importing the CLI by bare\n' +
+      '// specifier lets Bun auto-install resolve @webjsdev/* and your deps on\n' +
+      '// demand, so the app serves with no `bun install` (install stays optional,\n' +
+      '// for editor types and offline runs). Args pass through to the CLI.\n' +
+      "await import('@webjsdev/cli/bin/webjs.js');\n");
+  }
+
   await writeFile(join(appDir, 'tsconfig.json'), JSON.stringify({
     compilerOptions: {
       target: 'ES2022',
@@ -650,8 +667,9 @@ export type User = typeof users.$inferSelect;
 import { fileURLToPath } from 'node:url';
 import * as schema from './schema.server.ts';
 
-// The only file that opens the driver. Runtime-neutral: native bun:sqlite on
-// Bun, better-sqlite3 on Node. Cached on globalThis across dev reloads.
+// The only file that opens the driver. Runtime-neutral and ZERO native deps:
+// built-in bun:sqlite on Bun, built-in node:sqlite on Node. Cached on
+// globalThis across dev reloads.
 // A relative SQLite path resolves against the app root (the parent of db/), not
 // process.cwd(), so the connection works under \`webjs dev\` AND when the app is
 // embedded via createRequestHandler from a different working directory.
@@ -660,15 +678,25 @@ const raw = process.env.DATABASE_URL?.replace(/^file:/, '') ?? 'db/dev.db';
 const url = raw === ':memory:' || isAbsolute(raw) ? raw : resolve(appRoot, raw);
 const g = globalThis as unknown as { __webjs_db?: unknown };
 
+// Both node:sqlite and bun:sqlite default \`busy_timeout\` to 0, so a concurrent
+// writer throws \`database is locked\` immediately. Restore a 5s wait (the old
+// better-sqlite3 default) so contended access waits, and WAL so readers proceed
+// alongside one writer.
+function tune<T extends { exec(sql: string): unknown }>(client: T): T {
+  client.exec('PRAGMA busy_timeout = 5000');
+  client.exec('PRAGMA journal_mode = WAL');
+  return client;
+}
+
 async function open() {
   if ((globalThis as { Bun?: unknown }).Bun) {
     const { Database } = await import('bun:sqlite');
     const { drizzle } = await import('drizzle-orm/bun-sqlite');
-    return drizzle({ client: new Database(url), relations: schema.relations });
+    return drizzle({ client: tune(new Database(url)), relations: schema.relations });
   }
-  const { default: Database } = await import('better-sqlite3');
-  const { drizzle } = await import('drizzle-orm/better-sqlite3');
-  return drizzle({ client: new Database(url), relations: schema.relations });
+  const { DatabaseSync } = await import('node:sqlite');
+  const { drizzle } = await import('drizzle-orm/node-sqlite');
+  return drizzle({ client: tune(new DatabaseSync(url)), relations: schema.relations });
 }
 
 export const db = (g.__webjs_db ??= await open()) as Awaited<ReturnType<typeof open>>;
@@ -701,6 +729,12 @@ export default defineConfig({
 `
     : `import { defineConfig } from 'drizzle-kit';
 
+// No 'driver' is set: drizzle-kit auto-selects the SQLite driver for
+// migrate/push/studio from the runtime, picking the built-in node:sqlite on
+// Node and bun:sqlite on Bun (it only reaches for better-sqlite3 when that
+// package is present, which this app does not install). That auto-selection is
+// what keeps \`webjs db migrate\` free of a native driver, matching the runtime
+// connection in db/connection.server.ts.
 export default defineConfig({
   dialect: 'sqlite',
   schema: './db/schema.server.ts',

package/lib/runtime-rewrite.js

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

package/package.json

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

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

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

package/templates/.cursorrules

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

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

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

package/templates/AGENTS.md

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

package/templates/CONVENTIONS.md

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

package/templates/Dockerfile

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