@webjsdev/cli 0.10.30 → 0.10.32

package/lib/saas-template.js

@@ -106,7 +106,7 @@ export async function writeSaasFiles(appDir, opts = {}) {
   // add passwordHash (the column auth needs). Drizzle, dialect-agnostic.
   await writeFile(join(appDir, 'db', 'schema.server.ts'), [
     "import { defineRelations } from 'drizzle-orm';",
-    "import { table, pk, text, createdAt } from './columns.server.ts';",
+    "import { table, pk, uuidPk, text, bool, createdAt } from './columns.server.ts';",
     "",
     "export const users = table('users', {",
     "  id: pk(),",
@@ -116,7 +116,16 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "  createdAt: createdAt(),",
     "});",
     "",
-    "export const relations = defineRelations({ users }, () => ({}));",
+    "// Backs the example-gallery /examples/todo route (modules/todo). Delete it",
+    "// with the gallery when you prune the examples you do not use.",
+    "export const todos = table('todos', {",
+    "  id: uuidPk(),",
+    "  title: text().notNull(),",
+    "  completed: bool().notNull().default(false),",
+    "  createdAt: createdAt(),",
+    "});",
+    "",
+    "export const relations = defineRelations({ users, todos }, () => ({}));",
     "",
     "export type User = typeof users.$inferSelect;",
     "",
@@ -132,12 +141,19 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "import { db } from '#db/connection.server.ts';",
     "import { users } from '#db/schema.server.ts';",
     "import { hash } from '#lib/password.server.ts';",
-    "",
+    "import { signIn } from '#lib/auth.server.ts';",
+    "",
+    "// Creates the account, then signs the new user in and lands on the",
+    "// dashboard. signIn returns a 302 Response carrying the session cookie; the",
+    "// signup page action returns that Response as-is (a page action may return a",
+    "// Response). signIn lives in the server-only auth module, imported here",
+    "// server-to-server, so it never reaches the browser (the signup page only",
+    "// imports this action's RPC stub).",
     "export async function signup(input: { name: string; email: string; password: string }) {",
     "  const exists = await db.query.users.findFirst({ where: { email: input.email }, columns: { id: true } });",
     "  if (exists) return { success: false as const, error: 'Email already registered', status: 409 };",
-    "  const [user] = await db.insert(users).values({ name: input.name, email: input.email, passwordHash: await hash(input.password) }).returning();",
-    "  return { success: true as const, data: { id: user.id, name: user.name, email: user.email } };",
+    "  await db.insert(users).values({ name: input.name, email: input.email, passwordHash: await hash(input.password) });",
+    "  return signIn('credentials', { email: input.email, password: input.password }, { redirectTo: '/dashboard' });",
     "}",
     "",
   ].join('\n'));
@@ -252,10 +268,11 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "      headers: { 'content-type': 'application/x-www-form-urlencoded' },",
     "      body: new URLSearchParams({ name: 'Harness', email, password }).toString(),",
     "    });",
-    "    // Success is a 303 PRG to /login; a 422 means validation failed (still a",
-    "    // real response, just not the happy path). Either way the action ran.",
-    "    assert.ok([303, 422].includes(signupRes.status), 'signup action ran');",
-    "    if (signupRes.status !== 303) canSignup = false;",
+    "    // Success auto-logs-in and 302s to /dashboard (carrying the session",
+    "    // cookie); a 422 means validation failed. Either way the action ran.",
+    "    assert.ok([302, 422].includes(signupRes.status), 'signup action ran');",
+    "    if (signupRes.status === 302) assert.equal(signupRes.headers.get('location'), '/dashboard', 'signup lands on the dashboard');",
+    "    if (signupRes.status !== 302) canSignup = false;",
     "  } catch {",
     "    // No migrated DB table -> the action throws. Skip the DB-backed assertions.",
     "    canSignup = false;",
@@ -270,6 +287,10 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "  assert.equal(dash.status, 200, 'the session cookie unlocks the dashboard');",
     "  const body = await dash.text();",
     "  assert.match(body, /Dashboard/, 'the dashboard content rendered');",
+    "  // The greeting interpolates the real user, so the name renders and the",
+    "  // literal template source never leaks (a counterfactual for the escaping bug).",
+    "  assert.match(body, /Harness/, 'the dashboard greets the signed-in user by name');",
+    "  assert.ok(!body.includes('${user'), 'the greeting interpolation is not a literal string');",
     "});",
     "",
   ].join('\n');
@@ -308,6 +329,8 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "        </div>",
     "        <div class=${cardContentClass()}>",
     "          <form method=\"POST\" action=\"/api/auth/signin/credentials\" class=\"flex flex-col gap-4\">",
+    "            <!-- createAuth reads redirectTo from the posted form and 302s there after a successful signin. -->",
+    "            <input type=\"hidden\" name=\"redirectTo\" value=\"/dashboard\">",
     "            <div class=\"flex flex-col gap-1.5\">",
     "              <label class=${labelClass()} for=\"email\">Email</label>",
     "              <input class=${inputClass()} id=\"email\" name=\"email\" type=\"email\" required>",
@@ -357,9 +380,10 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "  if (password.length < 8) fieldErrors.password = 'At least 8 characters';",
     "  if (Object.keys(fieldErrors).length) return { success: false, fieldErrors, values, status: 422 };",
     "  const result = await signup({ name, email, password });",
-    "  if (!result.success) return { success: false, fieldErrors: { email: result.error }, values, status: result.status };",
-    "  // Account created. Redirect to login via PRG so a reload will not resubmit.",
-    "  return { success: true, redirect: '/login' };",
+    "  // On success signup returns signIn's 302 Response (auto-login -> /dashboard);",
+    "  // a page action may return a Response, so pass it straight through.",
+    "  if (result instanceof Response) return result;",
+    "  return { success: false, fieldErrors: { email: result.error }, values, status: result.status };",
     "}",
     "",
     "export default function SignupPage({ actionData }: { actionData?: { fieldErrors?: Record<string, string>; values?: Record<string, string> } }) {",
@@ -436,7 +460,7 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "    </div>",
     "    <div class=${cardClass()}>",
     "      <div class=${cardHeaderClass()}>",
-    "        <h3 class=${cardTitleClass()}>Welcome, ${`\\$\\{user?.name || user?.email\\}`}!</h3>",
+    "        <h3 class=${cardTitleClass()}>Welcome, ${user?.name || user?.email}!</h3>",
     "        <p class=${cardDescriptionClass()}>You're authenticated. Replace this scaffold with your real app.</p>",
     "      </div>",
     "      <div class=${cardContentClass()}>",
@@ -468,9 +492,9 @@ export async function writeSaasFiles(appDir, opts = {}) {
     "      <div class=${cardContentClass()}>",
     "        <dl class=\"grid grid-cols-[max-content_1fr] gap-x-6 gap-y-2 text-sm\">",
     "          <dt class=\"text-muted-foreground\">Email</dt>",
-    "          <dd>${`\\$\\{user?.email\\}`}</dd>",
+    "          <dd>${user?.email}</dd>",
     "          <dt class=\"text-muted-foreground\">Name</dt>",
-    "          <dd>${`\\$\\{user?.name || 'Not set'\\}`}</dd>",
+    "          <dd>${user?.name || 'Not set'}</dd>",
     "        </dl>",
     "      </div>",
     "    </div>",

package/package.json

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

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

@@ -3,7 +3,7 @@
 You are working on a webjs app, an AI-first, no-build, web-components-first
 framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
 project-specific conventions before writing any code. When AGENTS.md does not
-cover what you need, the full hosted docs are at **https://docs.webjs.com**.
+cover what you need, the full hosted docs are at **https://docs.webjs.dev**.
 
 ## Persistence + scaffold rules (non-negotiable)
 
@@ -19,6 +19,50 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**.
   the example `User` model, the example users module, etc. with the app the
   user actually asked for. Do not ship "Hello from <app-name>" as the
   deliverable.
+- **Study the gallery first, prune it second.** The full-stack and saas scaffolds
+  ship single-feature demos under `app/features/` plus one whole example app under
+  `app/examples/` (logic in `modules/`). It is your PRIMARY webjs reference: read
+  every demo end to end (code AND comments) to learn the idioms BEFORE you write
+  or delete anything. Only after internalising the patterns should you prune,
+  keeping and adapting what you need and deleting the rest (the
+  `app/features/<name>` or `app/examples/<name>` route AND its `modules/<name>`;
+  for the todo app, also the `todos` table). Never delete blindly up front. Each
+  route page has a `webjs-scaffold-placeholder` marker so `webjs check` fails
+  until you resolve it. Delete now-empty directories after pruning. The `api`
+  template ships a BACKEND-features showcase instead (endpoints under
+  `app/api/features/`: the `route()` adapter + validation, rate limiting,
+  streaming, file storage, WebSockets + broadcast, plus `env.ts` validation),
+  listed in the root `app/route.ts` index; prune it the same way.
+- **Prune what the app does not use.** Keep the infrastructure the app USES
+  and delete the rest (files AND folders). No persistence means delete `db/`,
+  `drizzle.config.ts`, and the `db:*` scripts. No UI kit used means delete
+  `components/ui/`, `components.json`, and `lib/utils/cn.ts`. No PWA means
+  delete `public/sw.js` and `offline.html`. Always KEEP the durable knowledge
+  (`AGENTS.md`, `CONVENTIONS.md`, the rule files, the MCP), never prune it, so
+  removing example code never removes your context. Prune AFTER using the
+  features and examples as reference, never blindly up front. A no-op for the `api` template
+  (no UI kit, no PWA files).
+- **`app/` is routing-only.** Only routing files live in `app/` (page, layout,
+  route, middleware, metadata routes). CSS, helpers, and constants do NOT:
+  `globals.css` is at `styles/`, browser-safe helpers at `lib/utils/`, feature
+  logic in `modules/`.
+- **Use a unique design, and redesign means more than recolor (UI apps).** Give
+  the app a design of its own (palette, typography, LAYOUT, and chrome) chosen
+  from what the app IS. Recoloring the scaffold and swapping the logo while
+  keeping its skeleton (a fixed top header with a Home link and a theme toggle,
+  the centered ~760px reading column, the "Built with webjs" footer) is NOT a
+  unique design. Decide from scratch whether this app even needs a header or
+  footer, what nav (if any), and what layout fits (a centered board, a full-bleed
+  dashboard, a split, a single card). The scaffold ships a
+  `webjs-scaffold-placeholder` marker on its footer, so `webjs check` fails until
+  you remove or replace the "Built with webjs" branding. Self-audit before
+  finishing: nothing should read as the scaffold example (no "Built with webjs"
+  footer, no leftover example nav, no default reading column unless it truly
+  fits). Keep only the design TOKENS and theme wiring in `app/layout.ts`
+  (infrastructure the ui kit reads) and restyle on top. Style with Tailwind
+  utilities wherever they reach, and use custom CSS only for what utilities
+  cannot express (@theme tokens, @keyframes, scrollbar, complex color-mix or
+  gradients). The `api` template has no UI, so this does not apply there.
 - **Only three templates exist:** `webjs create <name>` (default full-stack),
   `--template api`, `--template saas`. The CLI rejects any other `--template`
   value. Pick:
@@ -135,10 +179,37 @@ self-review loop.
   gradients); when unavoidable in a light-DOM component, prefix every class
   selector with the component tag. Shadow-DOM components legitimately use
   `static styles = css\`...\`` for scoped CSS.
+- **One theme, canonical tokens.** The app has a SINGLE theme, defined once in
+  `app/layout.ts` using the standard `@webjsdev/ui` (shadcn-compatible)
+  semantic tokens set to the brand palette. Use the canonical utility names
+  everywhere, in the page chrome AND inside components: `bg-background`,
+  `text-foreground`, `bg-card`, `bg-muted`, `text-muted-foreground`,
+  `bg-primary`, `text-primary-foreground`, `bg-accent`, `text-accent-foreground`,
+  `border-border`, `ring-ring`. These are exactly the tokens a component copied
+  in by `webjs ui add <name>` reads, so a scaffolded page and a later-added ui
+  component share one theme with no wiring. NEVER invent a parallel token
+  vocabulary (`--fg`, `--bg`, `text-fg`, `bg-elev`, a separate `--brand`): it
+  collides with the ui tokens (the accent once flipped to neutral on navigation
+  for exactly this reason) and diverges from the shadcn conventions the kit and
+  AI agents expect. Reach for opacity modifiers (`bg-primary/10`,
+  `hover:bg-primary/90`) before adding a token; add one the canonical way (a
+  `--x` var plus a `--color-x: var(--x)` line in `@theme inline`).
 - Custom-element tag names are passed to `.register('tag-name')`. They are NOT
   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.ts` vs `'use server'`, the decision.** Will the client call it?
+  Add `'use server'` and the file becomes an RPC action (browser import
+  rewritten to a typed stub). Is it server-only infra instead (a DB driver,
+  secrets, `node:*`)? Use NO directive, and NEVER import it into a
+  page/layout/component. Reach it from a `'use server'` action, `route.ts`, or
+  `middleware.ts`. A `.server.ts` WITHOUT the directive is a server-only utility
+  whose browser import throws at module load.
+- **Label every interactive control.** Give each control an accessible name, and
+  make clickable text a `<label for="control-id">` (or the control itself) so a
+  text click activates the control on BOTH the JS path and the no-JS
+  form-submit path. Use `aria-label` and `aria-pressed` on icon-only controls.
+  `assertNoA11yViolations(el)` in a browser test catches missing labels.
 - 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
@@ -182,6 +253,12 @@ self-review loop.
   paint), NOT from `fetch` calls in `connectedCallback`. For write-paths, prefer `<form action=...>` plus
   server action over `fetch` plus click handler. The framework upgrades plain
   forms to partial-swap submissions automatically.
+- **Default to optimistic UI for feasible mutations.** Use `optimistic()` from
+  `@webjsdev/core` for create/toggle/like/reorder so the UI updates instantly
+  and rolls back on failure (no hand-written try-catch or temp-id bookkeeping).
+  Do NOT use it where it hurts: unpredictable or server-computed results,
+  side-effectful or OAuth/payment mutations, and destructive irreversible
+  actions (confirm-first instead).
 - **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

package/templates/.claude/hooks/check-server-imports.mjs

@@ -0,0 +1,86 @@
+// Node walker for check-server-imports.sh (#804). Reads the PreToolUse JSON
+// payload (arg or stdin), extracts the file being edited and its proposed
+// content, and warns when a browser-facing app module adds an import of a
+// server-only `.server.*` utility (no `'use server'`). WARN by default; a
+// clean edit prints nothing and exits 0.
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, resolve, join } from 'node:path';
+
+function readPayload() {
+  const arg = process.argv[2];
+  if (arg && arg.trim().startsWith('{')) return arg;
+  try { return readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+let data;
+try { data = JSON.parse(readPayload() || '{}'); } catch { process.exit(0); }
+const input = data.tool_input || {};
+const filePath = input.file_path || input.filePath || '';
+if (!filePath) process.exit(0);
+
+// Only browser-facing app modules matter. A `.server.*` file (the boundary) or a
+// route.ts / middleware.ts (never shipped) is allowed to import server code.
+const rel = filePath.replace(/\\/g, '/');
+const isAppModule = /\/(app|components|modules|lib)\/.*\.(ts|js|mts|mjs)$/.test('/' + rel) || /(^|\/)(app|components|modules|lib)\//.test(rel);
+if (!isAppModule) process.exit(0);
+if (/\.server\.(ts|js|mts|mjs)$/.test(rel)) process.exit(0);
+if (/(^|\/)(route|middleware)\.(ts|js|mts|mjs)$/.test(rel)) process.exit(0);
+
+// Proposed content: Write has `content`; Edit has `new_string`; else read disk.
+let content = input.content ?? input.new_string ?? '';
+if (!content && existsSync(filePath)) { try { content = readFileSync(filePath, 'utf8'); } catch { /* ignore */ } }
+if (!content) process.exit(0);
+
+// Find the app root (walks up for a package.json with a `#*` imports map or a db/ dir).
+function findAppRoot(start) {
+  let dir = dirname(resolve(start));
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, 'package.json')) && (existsSync(join(dir, 'app')) || existsSync(join(dir, 'db')))) return dir;
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return dirname(resolve(start));
+}
+const appRoot = findAppRoot(filePath);
+
+// Collect import specifiers, skipping `import type` (erased by the stripper).
+const specs = [];
+const re = /(?:^|\n)\s*import\s+(type\s+)?[^;'"]*?from\s*['"]([^'"]+)['"]/g;
+let m;
+while ((m = re.exec(content))) { if (!m[1]) specs.push(m[2]); }
+
+function resolveSpec(spec) {
+  if (spec.startsWith('#')) return join(appRoot, spec.slice(1).replace(/^\//, ''));
+  if (spec.startsWith('.')) return resolve(dirname(filePath), spec);
+  return null; // bare npm specifier
+}
+
+const offenders = [];
+for (const spec of specs) {
+  if (!/\.server\.(ts|js|mts|mjs)$/.test(spec)) continue;
+  const abs = resolveSpec(spec);
+  if (!abs || !existsSync(abs)) continue;
+  let src = '';
+  try { src = readFileSync(abs, 'utf8'); } catch { continue; }
+  const head = src.split('\n').slice(0, 5).join('\n');
+  const hasUseServer = /^\s*(['"])use server\1\s*;?\s*$/m.test(head);
+  if (!hasUseServer) offenders.push(spec);
+}
+
+if (offenders.length === 0) process.exit(0);
+
+const msg =
+  `A browser-facing module (${rel}) imports a server-only utility: ${offenders.join(', ')}. ` +
+  `A .server.{ts,js} file with NO 'use server' directive throws at load in the browser, ` +
+  `so this would crash the page (webjs check flags it as no-server-import-in-browser-module). ` +
+  `Fix: add 'use server' to make it an RPC action, or reach it from a 'use server' action / route.ts / ` +
+  `middleware.ts, or share only a type via 'import type'. See agent-docs/types-and-mutations.md.`;
+
+if (process.env.WEBJS_SERVER_IMPORT_GATE === 'block') {
+  process.stderr.write(`BLOCKED: ${msg}\n`);
+  process.exit(2);
+}
+// WARN: surface as additionalContext, allow the edit.
+process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: msg } }) + '\n');
+process.exit(0);

package/templates/.claude/hooks/check-server-imports.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+#
+# PreToolUse hook (scaffolded by `webjs create`): WARN, at write time, when an
+# Edit/Write to a browser-facing app module (a page / layout / component under
+# app/ or components/ or modules/, NOT a `.server.*` file) adds an import of a
+# server-only `.server.{ts,js}` utility (a `.server.*` file with NO `'use server'`
+# directive). In the browser that import resolves to a throw-at-load stub, so the
+# module crashes the moment it loads. This is the #804 first-pass iteration loop:
+# `webjs check`'s `no-server-import-in-browser-module` catches it AFTER the file
+# lands; this hook surfaces it BEFORE, so the agent never writes the wrong shape.
+#
+# WARN, not block (the convention-vs-check principle in this app's AGENTS.md):
+# `webjs check` is the authoritative gate, and a pre-edit static peek cannot see
+# the full elision verdict, so a hard block could false-positive on a display-only
+# page the framework would elide. So this emits a loud reminder and allows the
+# edit. Set WEBJS_SERVER_IMPORT_GATE=block to hard-block instead; set
+# WEBJS_NO_SERVER_IMPORT_GATE=1 to skip.
+#
+# A `'use server'` action import is fine (it becomes a working RPC stub), and a
+# `import type { ... } from './x.server.ts'` is fine (the stripper erases it), so
+# both are ignored.
+
+[ "$WEBJS_NO_SERVER_IMPORT_GATE" = "1" ] && exit 0
+
+payload="$(cat)"
+node "$(dirname "$0")/check-server-imports.mjs" "$payload"

package/templates/.claude/hooks/cleanup-merged-worktree.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+#
+# Claude Code PostToolUse hook (matcher: Bash).
+#
+# After a `gh pr merge`, sweep the repo's git worktrees and REMOVE the ones
+# whose work has already landed, so a merged branch's worktree does not leak.
+# Accumulated stale worktrees (a session that merged but never cleaned up, or
+# crashed mid-task) are exactly what this closes: the webjs-start-work skill
+# already says "after the PR merges, git worktree remove", but as guidance it
+# gets skipped, so this makes the cleanup deterministic.
+#
+# CONSERVATIVE BY DESIGN. A worktree is removed ONLY when ALL hold:
+#   * it is a LINKED worktree, not the primary checkout;
+#   * it is NOT the current directory (you cannot remove the one you are in);
+#   * its branch is not main/master;
+#   * its branch is MERGED (an ancestor of the base ref, OR a merged GitHub PR
+#     for that head branch, which is how squash-merges are detected);
+#   * its working tree is CLEAN apart from untracked node_modules / .webjs.
+# Anything with uncommitted or unpushed-looking work is KEPT and reported, so
+# the hook can never destroy in-flight work.
+#
+# It never blocks the tool (always exits 0) and reports what it did back to the
+# model via hookSpecificOutput.additionalContext. Disable with
+# WEBJS_NO_WORKTREE_CLEANUP=1.
+#
+# Rule: AGENTS.md "One task per git worktree" + the webjs-start-work skill.
+
+set -uo pipefail
+
+# Read the whole payload first so we always honour the hook contract.
+payload=$(cat 2>/dev/null || true)
+
+if [ "${WEBJS_NO_WORKTREE_CLEANUP:-}" = "1" ]; then exit 0; fi
+
+cmd=$(printf '%s' "$payload" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+if [ -z "$cmd" ]; then exit 0; fi
+
+# Only act after a `gh pr merge` (whole word, not `gh pr merge-queue` typos etc.).
+if ! printf '%s' "$cmd" | grep -Eq '(^|[^[:alnum:]-])gh pr merge([^[:alnum:]-]|$)'; then
+  exit 0
+fi
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then exit 0; fi
+
+# The base ref merged branches land on. Prefer origin/main; fall back to a
+# local main/master (the test harness has no remote).
+base=""
+for ref in origin/main origin/master main master; do
+  if git rev-parse --verify --quiet "$ref" >/dev/null 2>&1; then base="$ref"; break; fi
+done
+[ -z "$base" ] && exit 0
+
+here=$(git rev-parse --show-toplevel 2>/dev/null || printf '%s' "$PWD")
+# The primary worktree is the first entry of `git worktree list`.
+primary=$(git worktree list --porcelain 2>/dev/null | awk '/^worktree /{print $2; exit}')
+
+is_merged() {
+  local br="$1"
+  # Ancestor of the base ref (fast-forward / rebase merges, and the real
+  # merges the test harness makes).
+  if git merge-base --is-ancestor "refs/heads/$br" "$base" 2>/dev/null; then return 0; fi
+  # A merged GitHub PR for this head branch (squash merges, which are NOT an
+  # ancestor of base). Network; skipped when gh is absent or unauthenticated.
+  if command -v gh >/dev/null 2>&1; then
+    local n
+    n=$(gh pr list --state merged --head "$br" --json number --jq '.[0].number' 2>/dev/null || true)
+    [ -n "$n" ] && return 0
+  fi
+  return 1
+}
+
+# Clean = nothing in `git status` except untracked node_modules / .webjs caches.
+is_clean() {
+  local wt="$1" dirty
+  dirty=$(git -C "$wt" status --porcelain 2>/dev/null \
+    | grep -vE '(^|/)(node_modules|\.webjs)(/|$)' || true)
+  [ -z "$dirty" ]
+}
+
+removed=()
+kept=()
+
+# Parse worktree path + branch pairs.
+wt=""
+while IFS= read -r line; do
+  case "$line" in
+    worktree\ *) wt="${line#worktree }" ;;
+    branch\ *)
+      br="${line#branch refs/heads/}"
+      # Skip the primary checkout and main/master lines.
+      if [ "$wt" = "$primary" ] || [ "$br" = "main" ] || [ "$br" = "master" ]; then wt=""; continue; fi
+      # Never remove the worktree we are currently in.
+      if [ "$wt" = "$here" ]; then
+        kept+=("$wt (current directory; cd out then \`git worktree remove\`)")
+        wt=""; continue
+      fi
+      if ! is_clean "$wt"; then
+        kept+=("$wt (uncommitted changes)"); wt=""; continue
+      fi
+      if ! is_merged "$br"; then
+        kept+=("$wt (branch $br not merged yet)"); wt=""; continue
+      fi
+      if git worktree remove --force "$wt" >/dev/null 2>&1; then
+        removed+=("$wt ($br)")
+      else
+        kept+=("$wt (git worktree remove failed)")
+      fi
+      wt="" ;;
+    "") wt="" ;;
+  esac
+done < <(git worktree list --porcelain 2>/dev/null)
+
+git worktree prune >/dev/null 2>&1 || true
+
+# Report nothing if there was nothing to do.
+if [ "${#removed[@]}" -eq 0 ] && [ "${#kept[@]}" -eq 0 ]; then exit 0; fi
+
+msg="Worktree cleanup after \`gh pr merge\`:"
+for r in "${removed[@]:-}"; do [ -n "$r" ] && msg="$msg"$'\n'"  removed $r (merged, clean)"; done
+for k in "${kept[@]:-}"; do [ -n "$k" ] && msg="$msg"$'\n'"  kept $k"; done
+
+jq -n --arg ctx "$msg" '{
+  hookSpecificOutput: {
+    hookEventName: "PostToolUse",
+    additionalContext: $ctx
+  }
+}' 2>/dev/null || true
+
+exit 0

package/templates/.claude/hooks/commit-before-stop.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+#
+# Claude Code Stop hook.
+#
+# The commit-per-logical-unit rule (CLAUDE.md + AGENTS.md "Git workflow") is
+# easy for an agent to defer to "the end", and then the end arrives with the
+# whole feature done and ZERO commits, which is the worst outcome: git history,
+# the user's revert and cherry-pick safety net, is empty. The PostToolUse
+# `nudge-uncommitted.sh` reminds DURING work but is only a soft context nudge an
+# agent can ignore. This Stop hook is the backstop at the END of a turn: if you
+# try to finish with a pile of uncommitted work on a feature branch, it blocks
+# the stop once and tells you to commit the completed unit first.
+#
+# Loop-safe: when `stop_hook_active` is already true (this hook fired and the
+# agent is continuing because of it), it does NOT block again, so it nags at
+# most once per stop and can never trap the agent in a loop.
+#
+# Skipped on main/master (you must not commit there anyway) and outside a git
+# work tree. Threshold via WEBJS_COMMIT_STOP_THRESHOLD (default 2). Disable
+# entirely with WEBJS_NO_COMMIT_STOP=1.
+
+set -uo pipefail
+
+payload=$(cat 2>/dev/null || true)
+
+if [ "${WEBJS_NO_COMMIT_STOP:-}" = "1" ]; then exit 0; fi
+
+# Loop guard: if we already blocked once this stop-cycle, let the agent stop.
+active=$(printf '%s' "$payload" | jq -r '.stop_hook_active // false' 2>/dev/null || echo false)
+if [ "$active" = "true" ]; then exit 0; fi
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then exit 0; fi
+
+branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+if [ -z "$branch" ] || [ "$branch" = "main" ] || [ "$branch" = "master" ]; then exit 0; fi
+
+threshold="${WEBJS_COMMIT_STOP_THRESHOLD:-2}"
+
+# Count real changes: tracked modifications + staged + untracked, minus the
+# noise the agent should never commit (node_modules, the sqlite db, caches).
+changed=$(git status --porcelain 2>/dev/null \
+  | grep -vE '(^|/)(node_modules|\.webjs)(/|$)|dev\.db($|-journal)' \
+  | grep -c . || true)
+
+if [ -z "$changed" ] || [ "$changed" -lt "$threshold" ]; then exit 0; fi
+
+reason="You are ending the turn with ${changed} uncommitted changes on '${branch}'. This project OVERRIDES Claude Code's never-commit default: commit per logical unit (see CLAUDE.md and AGENTS.md \"Git workflow\"). Before you stop, group the completed work into a meaningful commit ('git add' the related files, 'git commit' with an imperative subject under 72 chars) and push. If the work is genuinely mid-change and not yet a coherent unit, commit what IS complete, or explain in your final message why it cannot be committed yet. To relax this backstop set WEBJS_COMMIT_STOP_THRESHOLD, or disable it with WEBJS_NO_COMMIT_STOP=1."
+
+jq -n --arg r "$reason" '{decision: "block", reason: $r}' 2>/dev/null \
+  || printf '{"decision":"block","reason":%s}\n' "$(printf '%s' "$reason" | jq -Rs . 2>/dev/null || echo '""')"
+
+exit 0

package/templates/.claude/settings.json

@@ -10,6 +10,15 @@
           }
         ]
       },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/check-server-imports.sh"
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
         "hooks": [
@@ -47,6 +56,25 @@
             "command": ".claude/hooks/nudge-uncommitted.sh"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/cleanup-merged-worktree.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/commit-before-stop.sh"
+          }
+        ]
       }
     ]
   }