@webjsdev/cli 0.9.1 → 0.10.1

package/README.md

@@ -66,7 +66,7 @@ the CLI gives you `webjs ui` automatically. See
 The scaffold seeds opinionated defaults so AI agents produce consistent code:
 
 - `AGENTS.md` + `CONVENTIONS.md` (the machine-readable contract)
-- `.claude/`, `.cursorrules`, `.windsurfrules`, `.github/copilot-instructions.md`
+- `.claude/`, `.cursorrules`, `.agents/rules/workflow.md` (Antigravity), `.github/copilot-instructions.md`
 - `test/<feature>/` (with optional `browser/` / `e2e/` subfolders per kind) with example tests
 - Tailwind CSS via CLI (no browser runtime at build time)
 - TypeScript, `.editorconfig`, `.gitignore`

package/bin/webjs.js

@@ -8,7 +8,7 @@ const [cmd, ...rest] = process.argv.slice(2);
 
 // Exactly three scaffolds exist. Keep this list as the single source of
 // truth. AI-agent docs in README.md / AGENTS.md / .cursorrules /
-// .windsurfrules / .github/copilot-instructions.md mirror it.
+// .agents/rules/workflow.md / .github/copilot-instructions.md mirror it.
 const TEMPLATES = ['full-stack', 'api', 'saas'];
 
 const USAGE = `webjs commands:
@@ -26,6 +26,11 @@ const USAGE = `webjs commands:
   webjs ui <subcmd>                               AI-first component library CLI
                                                   (init / add / list / view / diff / info)
                                                   Requires @webjsdev/ui installed in the project
+  webjs vendor pin [--download]                   Pin client-side npm packages to .webjs/vendor/importmap.json
+                                                  Default: writes jspm.io URLs (browser fetches from CDN)
+                                                  --download: also downloads bundles for offline production
+  webjs vendor unpin <pkg>                        Remove a specific package from the pin file
+  webjs vendor list                               Show pinned packages with versions and URLs
   webjs help                                      Show this help`;
 
 /** @param {string[]} args */
@@ -266,6 +271,241 @@ Full docs: https://docs.webjs.com`);
       await scaffoldApp(name, process.cwd(), { template, install: !noInstall });
       break;
     }
+    case 'vendor': {
+      const sub = rest[0];
+      const args = rest.slice(1);
+      const appDir = process.cwd();
+      const { pinAll, unpinPackage, listPinned, auditPinned, findOutdated, updatePinned, readPinFile, SUPPORTED_PROVIDERS } = await import('@webjsdev/server');
+
+      // Parse `--from <provider>` once at the top so subcommands share it.
+      // Mirrors importmap-rails's `bin/importmap pin foo --from jsdelivr`.
+      let from = 'jspm';
+      const fromIdx = args.indexOf('--from');
+      if (fromIdx !== -1) {
+        from = args[fromIdx + 1];
+        if (!from || !SUPPORTED_PROVIDERS.has(from)) {
+          console.error(
+            `Unknown --from provider '${from || ''}'. Supported: ${[...SUPPORTED_PROVIDERS].join(', ')}.`,
+          );
+          process.exit(1);
+        }
+        // Strip --from + its argument so downstream flag checks like
+        // `args.includes('--download')` aren't confused.
+        args.splice(fromIdx, 2);
+      }
+
+      if (sub === 'pin') {
+        const download = args.includes('--download');
+        // Same precedence rule as `vendor update`: explicit --from
+        // wins; otherwise pinAll reads the pin file's persisted
+        // provider so a user who pinned via jsdelivr stays on it.
+        // Pass undefined (not the parsed 'jspm' default) when no
+        // --from to engage the pin-file fallback. Peek at the pin
+        // file here to compute the log line before pinAll runs.
+        const explicitFrom = fromIdx !== -1 ? from : undefined;
+        const existing = await readPinFile(appDir);
+        const usedFrom = explicitFrom || existing?.provider || 'jspm';
+        console.log(
+          `Pinning vendor packages from ${appDir}` +
+          (usedFrom !== 'jspm' ? ` via ${usedFrom}` : '') +
+          (download ? ' (downloading bundles)' : '') + '...',
+        );
+        const result = await pinAll(appDir, { download, from: explicitFrom });
+        if (result.noBareImports) {
+          // Scanner found zero bare-specifier imports in client-
+          // reachable source. Without this branch pinAll would write
+          // `{ imports: {} }`, which readPinFile then rejects as empty,
+          // leaving a useless file behind in whatever cwd.
+          console.error(
+            `Pin: no bare-specifier npm imports found in client code under ${appDir}. ` +
+            `Nothing to pin (no pin file written). Add a bare import like ` +
+            `\`import x from 'pkg-name'\` to a page or component, then rerun.`,
+          );
+          process.exit(1);
+        }
+        if (result.failed) {
+          // pinAll refused to write the pin file because every install
+          // failed to resolve via the chosen resolver (jspm.io's
+          // Generator API powers all providers; the failure mode is
+          // typically a brand-new published version not yet on the
+          // CDN, a network outage, or a provider-side 5xx). Surface
+          // the failure with the actual provider in the message so
+          // the user can fix the cause before shipping.
+          const provider = result.provider || 'jspm.io';
+          console.error(
+            `Pin FAILED: every package failed to resolve via ${provider}. No pin file written ` +
+            `(would shadow the live-API fallback with an empty importmap and break the browser).`,
+          );
+          console.error(`Attempted installs:`);
+          for (const i of result.attemptedInstalls) console.error(`  ${i}`);
+          console.error(
+            `Possible causes: the package version is too new for ${provider}'s CDN to have indexed yet; ` +
+            `network outage; ${provider} is down. Try again in a few minutes, or pin an older version.`,
+          );
+          process.exit(1);
+        }
+        const { pins, pruned, downloaded } = result;
+        for (const p of pins) {
+          const sizeStr = p.bytes != null ? ` ${(p.bytes / 1024).toFixed(1)} KB` : '';
+          console.log(`  ${(p.pkg + '@' + p.version).padEnd(40)}${sizeStr}`);
+        }
+        for (const f of pruned) {
+          console.log(`  ${f.padEnd(40)} REMOVED (orphan)`);
+        }
+        const pinMsg = `Pinned ${pins.length} package${pins.length === 1 ? '' : 's'}, wrote .webjs/vendor/importmap.json` +
+          (downloaded ? ` + ${downloaded} bundle${downloaded === 1 ? '' : 's'}` : '') + '.';
+        const pruneMsg = pruned.length ? ` Pruned ${pruned.length} orphan${pruned.length === 1 ? '' : 's'}.` : '';
+        console.log(pinMsg + pruneMsg);
+        break;
+      }
+
+      if (sub === 'unpin') {
+        if (args.length === 0) {
+          console.error('Usage: webjs vendor unpin <pkg>');
+          process.exit(1);
+        }
+        let unpinFailed = false;
+        for (const pkg of args) {
+          const r = await unpinPackage(appDir, pkg);
+          if (!r.removed) {
+            console.error(`  ${pkg.padEnd(40)} not in pin file`);
+            unpinFailed = true;
+            continue;
+          }
+          const extra = r.deletedFile ? ` (also deleted ${r.deletedFile})` : '';
+          console.log(`  ${pkg.padEnd(40)} unpinned${extra}`);
+        }
+        // Exit non-zero if ANY of the requested packages weren't in
+        // the pin file. Scripts wrapping the CLI rely on the exit
+        // code to detect "nothing was removed"; printing the message
+        // alone wasn't enough.
+        if (unpinFailed) process.exit(1);
+        break;
+      }
+
+      if (sub === 'list') {
+        const entries = await listPinned(appDir);
+        if (entries.length === 0) {
+          console.log('No pin file. Run "webjs vendor pin" to create .webjs/vendor/importmap.json.');
+          break;
+        }
+        console.log(`Pinned packages from ${appDir}/.webjs/vendor/importmap.json:`);
+        for (const e of entries) {
+          const sizeStr = e.bytes != null ? ` ${(e.bytes / 1024).toFixed(1)} KB` : '';
+          console.log(`  ${(e.pkg + '@' + e.version).padEnd(40)}${sizeStr}`);
+          console.log(`    ${e.url}`);
+        }
+        console.log(`${entries.length} package${entries.length === 1 ? '' : 's'} pinned.`);
+        break;
+      }
+
+      if (sub === 'audit') {
+        // npm bulk-advisories check against pinned versions. Mirrors
+        // bin/importmap audit. Exits non-zero when any vulnerability
+        // is found so CI can gate on it.
+        const { vulnerable, totalChecked, errored } = await auditPinned(appDir);
+        if (totalChecked === 0) {
+          console.log('No pinned packages to audit. Run "webjs vendor pin" first.');
+          break;
+        }
+        if (errored) {
+          console.error(
+            `Could not reach registry.npmjs.org for security advisories ` +
+            `(network failure, timeout, or 5xx). Retry when connectivity is back.`,
+          );
+          process.exit(1);
+        }
+        if (vulnerable.length === 0) {
+          console.log(`No vulnerable packages found (${totalChecked} checked).`);
+          break;
+        }
+        console.log(`Package                                  Severity   Vulnerable versions       Title`);
+        for (const v of vulnerable) {
+          console.log(
+            `  ${v.name.padEnd(38)} ${v.severity.padEnd(10)} ${v.vulnerableVersions.padEnd(25)} ${v.title}`,
+          );
+        }
+        const bySeverity = vulnerable.reduce((acc, v) => {
+          acc[v.severity] = (acc[v.severity] || 0) + 1;
+          return acc;
+        }, /** @type {Record<string,number>} */ ({}));
+        const summary = Object.entries(bySeverity)
+          .sort((a, b) => b[1] - a[1])
+          .map(([sev, n]) => `${n} ${sev}`).join(', ');
+        console.error(
+          `  ${vulnerable.length} vulnerabilit${vulnerable.length === 1 ? 'y' : 'ies'} found: ${summary}`,
+        );
+        process.exit(1);
+      }
+
+      if (sub === 'outdated') {
+        // npm registry latest-version check against pinned versions.
+        // Mirrors bin/importmap outdated. Exits non-zero when any
+        // package is outdated so CI / Renovate-style automation can
+        // detect it.
+        const outdated = await findOutdated(appDir);
+        if (outdated.length === 0) {
+          console.log('No outdated packages found.');
+          break;
+        }
+        console.log(`Package                                  Current               Latest`);
+        for (const o of outdated) {
+          console.log(`  ${o.pkg.padEnd(38)} ${o.current.padEnd(21)} ${o.latest}`);
+        }
+        console.error(
+          `  ${outdated.length} outdated package${outdated.length === 1 ? '' : 's'} found.`,
+        );
+        process.exit(1);
+      }
+
+      if (sub === 'update') {
+        // Re-pin outdated packages to latest. Mirrors bin/importmap
+        // update. Does NOT modify package.json or node_modules; the
+        // user should run `npm install <pkg>@<latest>` afterward to
+        // keep the local install in sync.
+        //
+        // Provider precedence: explicit --from CLI flag wins. Without
+        // it, updatePinned reads the pin file's persisted provider so
+        // a user who pinned via jsdelivr stays on jsdelivr after
+        // update. Pass `undefined` (not the parsed `from = 'jspm'`
+        // default) when no --from was given so updatePinned's
+        // pin-file fallback engages.
+        const explicitFrom = fromIdx !== -1 ? from : undefined;
+        const existing = await readPinFile(appDir);
+        const usedFrom = explicitFrom || existing?.provider || 'jspm';
+        console.log(`Updating outdated vendor pins in ${appDir}${usedFrom !== 'jspm' ? ` via ${usedFrom}` : ''}...`);
+        const result = await updatePinned(appDir, { from: explicitFrom });
+        if (result.noOutdated) {
+          console.log('No outdated packages found.');
+          break;
+        }
+        if (result.updated.length === 0) {
+          console.error('No packages were updated (jspm.io may have failed to resolve any of the new versions).');
+          process.exit(1);
+        }
+        for (const u of result.updated) {
+          console.log(`  ${u.pkg.padEnd(38)} ${u.from} → ${u.to}`);
+        }
+        console.log(
+          `Updated ${result.updated.length} package${result.updated.length === 1 ? '' : 's'}. ` +
+          `Run \`npm install ${result.updated.map(u => `${u.pkg}@${u.to}`).join(' ')}\` to ` +
+          `sync your node_modules.`,
+        );
+        break;
+      }
+
+      console.error(`Unknown vendor subcommand: ${sub || '(none)'}\n` +
+        `Usage:\n` +
+        `  webjs vendor pin [--from PROVIDER] [--download]   Pin packages to .webjs/vendor/importmap.json\n` +
+        `  webjs vendor unpin <pkg>                          Remove a package from the pin file\n` +
+        `  webjs vendor list                                 Show pinned packages with versions and URLs\n` +
+        `  webjs vendor audit                                Run a security audit against pinned versions\n` +
+        `  webjs vendor outdated                             Check pinned packages for newer versions\n` +
+        `  webjs vendor update [--from PROVIDER]             Re-pin outdated packages to latest\n` +
+        `\n` +
+        `  --from PROVIDER     CDN to resolve through. One of: ${[...SUPPORTED_PROVIDERS].join(', ')}. Default: jspm.`);
+      process.exit(1);
+    }
     case 'help':
     case undefined:
       console.log(USAGE);

package/lib/create.js

@@ -373,6 +373,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     '.claude/hooks/block-prose-punctuation.sh',
     '.claude/hooks/guard-branch-context.sh',
     '.claude/hooks/nudge-uncommitted.sh',
+    '.claude/hooks/require-tests-with-src.sh',
     // Gemini CLI config + hooks
     '.gemini/settings.json',
     '.gemini/hooks/nudge-uncommitted.sh',
@@ -381,9 +382,14 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     '.cursor/hooks/nudge-uncommitted.sh',
     // OpenCode plugins (loaded as TS by Bun at runtime)
     '.opencode/plugins/nudge-uncommitted.ts',
+    // Antigravity workspace rules (Google's documented convention is
+    // `.agents/rules/*.md`, lowercase, per the Codelab
+    // "Build Autonomous Developer Pipelines using agents.md and skills.md
+    // in Antigravity"). Replaced the legacy `.windsurfrules` ship when
+    // Windsurf was acquired by Google.
+    '.agents/rules/workflow.md',
     // Cross-agent config files
     '.cursorrules',
-    '.windsurfrules',
     '.github/copilot-instructions.md',
     '.github/pull_request_template.md',
     '.editorconfig',
@@ -400,7 +406,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
 
   // Make hook scripts executable
   const { chmod } = await import('node:fs/promises');
-  for (const hook of ['block-prose-punctuation.sh', 'guard-branch-context.sh', 'nudge-uncommitted.sh']) {
+  for (const hook of ['block-prose-punctuation.sh', 'guard-branch-context.sh', 'nudge-uncommitted.sh', 'require-tests-with-src.sh']) {
     const hookPath = join(appDir, '.claude', 'hooks', hook);
     if (existsSync(hookPath)) await chmod(hookPath, 0o755);
   }
@@ -606,7 +612,7 @@ export type ActionResult<T> =
       .replace(/`/g, '\\`')
       .replace(/\$\{/g, '\\${');
 
-  await writeFile(join(appDir, 'app', 'layout.ts'), `import { html } from '@webjsdev/core';
+  await writeFile(join(appDir, 'app', 'layout.ts'), `import { html, cspNonce } from '@webjsdev/core';
 import '@webjsdev/core/client-router';
 import '../components/theme-toggle.ts';
 // Webjs UI components are tiered:
@@ -638,8 +644,13 @@ const navLink = (href: string, label: string) => html\`
 \`;
 
 export default function RootLayout({ children }: { children: unknown }) {
+  // Read the in-flight request's CSP nonce so the theme-detection
+  // inline script below passes strict CSP (script-src 'nonce-...').
+  // Returns '' when no CSP nonce is set, in which case the attribute
+  // is empty and the browser ignores it.
+  const nonce = cspNonce();
   return html\`
-    <script>
+    <script nonce="\${nonce}">
       (function(){
         try {
           var mq = window.matchMedia('(prefers-color-scheme: light)');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {
@@ -13,7 +13,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@webjsdev/server": "^0.7.2",
+    "@webjsdev/server": "^0.8.0",
     "@webjsdev/ui": "^0.3.1"
   },
   "publishConfig": {

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

@@ -0,0 +1,149 @@
+# Antigravity Workspace Rules: webjs app
+
+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**.
+
+## Persistence + scaffold rules (non-negotiable)
+
+- **Use Prisma + SQLite for data, never JSON files.** It is already wired up
+  (`prisma/schema.prisma`, `lib/prisma.server.ts`, `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 JSON file as a
+  fake database. NEVER use module-scope arrays / Maps as a substitute. NEVER
+  use localStorage for app data. `webjs check`'s `no-json-data-files` rule
+  will fail the build if you do.
+- **The scaffold is reference, not the final product.** Replace `app/page.ts`,
+  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.
+- **Only three templates exist:** `webjs create <name>` (default full-stack),
+  `--template api`, `--template saas`. The CLI rejects any other `--template`
+  value. Pick:
+  - Any product UI (todo, blog, dashboard, marketplace, social) goes through
+    the default template.
+  - HTTP/JSON API only, no UI, uses `--template api`.
+  - Auth / login / signup / SaaS uses `--template saas`.
+
+## Before starting ANY work
+
+FIRST, before writing any code:
+1. Check `git branch --show-current`.
+   - 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.
+
+## Autonomous mode (sandbox / no-prompt)
+
+If running without interactive approval, auto-decide:
+- On main? Auto-create feature/<task-slug> branch.
+- Parent behind? Auto-rebase. Merge? Auto-merge + delete feature branches.
+- Auto-generate commit messages. Fix failing tests and violations.
+Quality bar stays the same, no blocking on questions.
+
+## Mandatory workflow (never skip)
+
+Every code change must include:
+1. Server tests in `test/<feature>/*.test.ts` (node:test).
+2. Browser tests in `test/<feature>/browser/*.test.js` (WTR + Playwright, real Chromium).
+3. Documentation updates. Walk every surface in the **Definition of done**
+   section of CONVENTIONS.md (AGENTS.md, CONVENTIONS.md, README.md, docs/,
+   website/, scaffold scripts) and either update it or write
+   "N/A because <reason>" in the PR body. Docs land on the same PR as the
+   code, never as a follow-up.
+4. Convention check: `webjs check` must pass.
+5. Pre-merge self-review loop. Before saying the PR is ready for merge, run
+   fresh-context review rounds until one round finds zero issues. Antigravity
+   primitive: open a new Cascade thread or a fresh side-panel session for
+   each round so the reviewer has no prior context on the implementation
+   decisions. Minimum two rounds; rotate focus each round. Skip the loop
+   only for one-line trivial changes; skipping on a change that touches
+   logic, public surface, build, security, or multiple files is the exact
+   failure mode the loop exists to prevent. The full rule, prompt template,
+   and reporting contract live in the **Pre-merge self-review loop** section
+   of CONVENTIONS.md.
+
+The user should never have to ask for tests, documentation, or the
+self-review loop.
+
+## Git rules
+
+- COMMIT AND PUSH PER LOGICAL UNIT, NOT AT THE END. One feature, one fix, one
+  rename, one doc rewrite per commit. Always `git push` after committing.
+  The user should never have to ask for a commit.
+- HARD LIMIT: if you have 5+ unstaged files spanning different concerns,
+  commit before continuing. The Claude Code hook at
+  `.claude/hooks/nudge-uncommitted.sh` fires at threshold 4. Antigravity
+  users should self-enforce the same rule. Batching multiple logical units
+  into one commit is the failure mode this rule exists to prevent.
+- Meaningful commit messages: what changed and why.
+- NEVER add Co-Authored-By or AI attribution trailers to commits.
+- NEVER use em-dashes (U+2014), a hyphen-as-pause (` - `), or a
+  semicolon-as-pause (` ; `) in commit messages or anywhere else. Rewrite the
+  sentence so no pause-punctuation crutch is needed. Use a period, comma,
+  colon, parentheses, or a restructured phrasing. Plain hyphens stay fine in
+  compound words, CLI flags, filenames, and ranges. Semicolons stay fine
+  inside code.
+- Work on feature branches, never push directly to main.
+- Create pull requests for review.
+- NEVER merge any branch without explicit user permission. Always ask:
+  "Ready to merge <branch> into <target>? Delete or keep <branch> after?"
+  Wait for approval AND the delete/keep preference. Applies to ALL merges.
+- Run `webjs test` before every commit.
+
+## Framework rules
+
+- No build step: ES modules served directly.
+- **Erasable TypeScript only.** Node 24+ strips types via
+  `module.stripTypeScriptTypes` (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.
+- Web components render into light DOM by default (so Tailwind / global CSS
+  apply directly). Opt in to shadow DOM per component with
+  `static shadow = true` when you need scoped styles (via
+  `static styles = css\`...\``) or third-party-embed isolation. `<slot>`
+  projection works identically in both modes (named slots, fallback content,
+  `assignedNodes` / `slotchange`, first-wins resolution).
+- Custom-element tag names are passed to `.register('tag-name')`. They are NOT
+  a static field on the class.
+- One function per server action file (`*.server.ts`).
+- 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.
+- Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat`
+  ship. Use plain template-literal expressions
+  (`class=${active ? 'btn active' : 'btn'}`, `style=${'color:' + color}`,
+  `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in
+  `firstUpdated`) instead of Lit's `classMap` / `styleMap` / `ref` / `when` /
+  `choose` / `guard`.
+- Use Context for cross-component data, Task for async data in components.
+- **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), 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.
+- **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.
+- Full API reference in AGENTS.md.

package/templates/.claude/hooks/require-tests-with-src.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+#
+# PreToolUse hook (scaffolded by `webjs create`): block a `git commit`
+# that adds or changes application code without any accompanying test.
+#
+# webjs is AI-first: most apps are built with an AI agent, and the
+# easiest corner to cut is shipping a feature with no test. This gate
+# makes "every change ships with a test" a hard floor, not a suggestion.
+#
+# What a hook CANNOT do: judge WHICH test layer a change needs (a unit
+# test vs a browser/e2e test is a judgement call). So it enforces the
+# floor (some real test must accompany app code) and reminds you to add
+# browser/e2e coverage for interactive surfaces. `webjs test` runs the
+# actual suite in the commit hook.
+#
+# Scope: fires only on `git commit`. Inspects the STAGED diff.
+#
+# Blocks (exit 2) when the staged diff changes app code (app/, modules/,
+# components/, lib/) but stages no test (test/** or *.test.* / *.spec.*).
+# Allowed: commits with no app-code change, commits that stage a test
+# alongside, and WEBJS_NO_TEST_GATE=1 for a genuine non-code commit.
+#
+# Bypass (humans, emergencies): git commit --no-verify.
+
+set -euo pipefail
+
+if [ "${WEBJS_NO_TEST_GATE:-}" = "1" ]; then
+  exit 0
+fi
+
+payload=$(cat)
+cmd=$(printf '%s' "$payload" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+if [ -z "$cmd" ]; then exit 0; fi
+# Match `git commit` as a whole word so sibling subcommands
+# (git commit-graph, git commit-tree) and string mentions do not trip it.
+if ! printf '%s' "$cmd" | grep -Eq '(^|[^[:alnum:]-])git commit([^[:alnum:]-]|$)'; then
+  exit 0
+fi
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then exit 0; fi
+
+staged=$(git diff --cached --name-only 2>/dev/null || true)
+if [ -z "$staged" ]; then exit 0; fi
+
+# App code lives under app/, modules/, components/, lib/. A `.server.*`
+# file is still app code. Match source extensions only (skip .css, .md).
+app_code=$(printf '%s\n' "$staged" \
+  | grep -E '^(app|modules|components|lib)/.*\.([mc]?[jt]sx?)$' || true)
+if [ -z "$app_code" ]; then exit 0; fi
+
+test_staged=$(printf '%s\n' "$staged" \
+  | grep -E '(^|/)test/|\.test\.[mc]?[jt]sx?$|\.spec\.[mc]?[jt]sx?$' || true)
+
+if [ -z "$test_staged" ]; then
+  cat >&2 <<'EOF'
+BLOCKED: this commit changes app code but stages no test.
+
+You staged application code (app/, modules/, components/, lib/) with no
+accompanying test. Every change ships with a test. Add or update the test
+that proves the new behaviour, then `git add` it.
+
+Pick the layer the change needs (a unit test is not always enough):
+  - logic / actions / queries / utils  -> a unit test
+  - a component, hydration, a server action called from the client, the
+    router, anything interactive -> a browser or e2e test that asserts the
+    real behaviour in a browser, not just the function in isolation.
+
+See `webjs test` and the testing guide. Genuine non-code commit (docs,
+config) that needs no test? Re-run with WEBJS_NO_TEST_GATE=1.
+
+Hook: .claude/hooks/require-tests-with-src.sh
+EOF
+  exit 2
+fi
+
+# Reminder for interactive surfaces: a unit test alone rarely covers them.
+interactive=$(printf '%s\n' "$app_code" | grep -E '^components/|/components/' || true)
+if [ -n "$interactive" ]; then
+  jq -n --arg ctx "Reminder: this commit changes component code. A unit test alone usually is not enough for an interactive component; add a browser test (webjs test --browser) that asserts the rendered/hydrated behaviour." '{
+    hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: $ctx }
+  }'
+fi
+exit 0

package/templates/.claude/settings.json

@@ -18,6 +18,15 @@
             "command": ".claude/hooks/guard-branch-context.sh"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/require-tests-with-src.sh"
+          }
+        ]
       }
     ],
     "PostToolUse": [