@webjsdev/cli 0.10.3 → 0.10.5

package/bin/webjs.js

@@ -2,10 +2,36 @@
 import { resolve, join, dirname } from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { checkNodeInline, nodeInlineMessage } from '../lib/node-preflight.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const [cmd, ...rest] = process.argv.slice(2);
 
+// Node-version preflight (issue #238), INLINE and dependency-free.
+// This MUST run before any `import @webjsdev/server`: importing the server
+// package links `src/dev.js`, which references Node 24+ builtins, so on an old
+// Node that import would LINK-fail before any preflight inside the server
+// package could run. The primary guard is therefore `checkNodeInline` (from
+// `../lib/node-preflight.js`, which imports nothing), depending only on
+// `process.versions.node`. The richer `assertNodeVersion` import inside main()
+// stays as belt-and-suspenders for the link-ok (>= 22.13) cases.
+// `help` / no-arg is exempt so a user on an old Node can still read usage.
+if (cmd !== 'help' && cmd !== undefined) {
+  let engines = '>=24.0.0';
+  try {
+    const { readFileSync } = await import('node:fs');
+    const pkg = JSON.parse(
+      readFileSync(join(__dirname, '..', 'package.json'), 'utf8'),
+    );
+    engines = pkg?.engines?.node || engines;
+  } catch {}
+  const r = checkNodeInline(process.versions.node, engines);
+  if (!r.ok) {
+    console.error(nodeInlineMessage(r));
+    process.exit(1);
+  }
+}
+
 // Exactly three scaffolds exist. Keep this list as the single source of
 // truth. AI-agent docs in README.md / AGENTS.md / .cursorrules /
 // .agents/rules/workflow.md / .github/copilot-instructions.md mirror it.
@@ -15,7 +41,7 @@ const USAGE = `webjs commands:
   webjs dev   [--port 8080]                       Start dev server with live reload
   webjs start [--port 8080]                       Start production server (serves source directly, no build step)
   webjs test  [--server|--browser]                 Run server + browser tests
-  webjs check                                     Validate app against conventions
+  webjs check                                     Run correctness checks on the app
   webjs create <name> [--template full-stack|api|saas] [--no-install]  Scaffold a new webjs app
                                                   (only 3 templates exist. default: full-stack with Prisma+SQLite)
                                                   Auto-runs the detected package manager's install in the new dir
@@ -41,6 +67,15 @@ function flag(args, name, def) {
 }
 
 async function main() {
+  // Preflight: webjs needs Node 24+ (built-in TS strip + recursive fs.watch).
+  // Run before any subcommand so an older Node fails fast with a clear,
+  // actionable message naming the found + required version, exiting non-zero
+  // instead of crashing cryptically later. `help` is exempt so a user on an
+  // old Node can still read usage.
+  if (cmd !== 'help' && cmd !== undefined) {
+    const { assertNodeVersion } = await import('@webjsdev/server');
+    assertNodeVersion({ onFail: 'exit' });
+  }
   switch (cmd) {
     case 'dev': {
       // If we're already inside the --watch child, start the server directly.
@@ -212,22 +247,16 @@ async function main() {
       break;
     }
     case 'check': {
-      const { checkConventions, RULES, loadConventionOverrides } = await import('@webjsdev/server/check');
+      const { checkConventions, RULES } = await import('@webjsdev/server/check');
 
       if (rest.includes('--rules')) {
-        const overrides = await loadConventionOverrides(process.cwd());
-        const anyOverride = Object.keys(overrides).length > 0;
-        console.log('webjs check, available rules:');
-        console.log('  All rules are ENABLED by default. A rule is only off when');
-        console.log('  package.json "webjs": { "conventions": { ... } } sets it');
-        console.log('  to false.\n');
+        console.log('webjs check, correctness rules:');
+        console.log('  Every rule catches objectively broken code (a crash, a');
+        console.log('  security leak, or a build/type-strip failure) and always');
+        console.log('  runs. Project conventions (layout, style, process) are');
+        console.log('  guidance in CONVENTIONS.md, not rules here.\n');
         for (const r of RULES) {
-          const off = overrides[r.name] === false;
-          const status = off ? '[disabled by override]' : '[enabled]';
-          console.log(`  ${r.name.padEnd(30)} ${status.padEnd(24)} ${r.description}`);
-        }
-        if (!anyOverride) {
-          console.log('\n  (no overrides found; every rule above is active in this project)');
+          console.log(`  ${r.name.padEnd(30)} ${r.description}`);
         }
         break;
       }
@@ -235,7 +264,7 @@ async function main() {
       const violations = await checkConventions(process.cwd());
 
       if (violations.length === 0) {
-        console.log('webjs check: all conventions pass ✓');
+        console.log('webjs check: all checks pass ✓');
       } else {
         console.log(`webjs check: ${violations.length} violation(s) found\n`);
         for (const v of violations) {

package/lib/create.js

@@ -494,6 +494,27 @@ if (process.env.NODE_ENV !== 'production') g.__prisma = prisma;
   if (isApi) {
     // API-only template: no layout, no page, no components.
     // Just a health route and an example module with route wrapper.
+
+    // Root middleware applying CORS to every route. An API consumed by a
+    // browser from another origin needs this; the `cors()` primitive
+    // handles origin reflection, the OPTIONS preflight, Vary: Origin, and
+    // the credentials rule, so route handlers stay focused on data.
+    await writeFile(join(appDir, 'middleware.ts'), `import { cors } from '@webjsdev/server';
+
+/**
+ * App-wide CORS policy. Replace the allow-list with your real frontend
+ * origins. With \`credentials: true\` a wildcard origin is invalid per the
+ * CORS spec, so list explicit origins (never \`'*'\` + credentials).
+ */
+export default cors({
+  origin: ['http://localhost:3000', 'https://app.example.com'],
+  credentials: true,
+  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+  allowedHeaders: ['content-type', 'authorization'],
+  maxAge: 86400,
+});
+`);
+
     await mkdir(join(appDir, 'app', 'api', 'health'), { recursive: true });
     await mkdir(join(appDir, 'app', 'api', 'users'), { recursive: true });
     await writeFile(join(appDir, 'app', 'api', 'health', 'route.ts'), `export async function GET() {
@@ -536,7 +557,7 @@ export async function POST(req: Request) {
   return Response.json(await createUser(body));
 }
 `);
-    // Minimal test stub so the scaffold passes `webjs check` (tests-exist)
+    // Minimal starter test so a freshly scaffolded app ships with a test
     // and `webjs test` runs cleanly. Replace these with real assertions
     // once you wire the action/query to a real data source.
     await writeFile(join(appDir, 'test', 'unit', 'users.test.ts'), `import { test } from 'node:test';
@@ -820,7 +841,7 @@ export default function Home() {
       <p class="text-lede leading-[1.5] text-fg-muted max-w-[56ch] m-0 mb-6">
         Edit <code class="font-mono text-[0.9em]">app/page.ts</code> to get started.
         Run \${accentLink('#', 'webjs test')} to run tests and
-        \${accentLink('#', 'webjs check')} to validate conventions.
+        \${accentLink('#', 'webjs check')} to catch correctness issues.
       </p>
       <div class="flex gap-3 items-center">
         <button class=\${buttonClass()}>Get started</button>

package/lib/node-preflight.js

@@ -0,0 +1,46 @@
+/**
+ * Inline, dependency-free Node-version preflight for the CLI (issue #238).
+ *
+ * This is deliberately SEPARATE from `@webjsdev/server`'s `node-version.js`:
+ * importing the server package links `src/dev.js`, which references Node 24+
+ * builtins, so on an old Node that import LINK-fails before any preflight could
+ * run. The CLI's primary guard must therefore depend on nothing but
+ * `process.versions.node`. `bin/webjs.js` imports `checkNodeInline` from here
+ * and runs it before any `import @webjsdev/server`. This module imports nothing.
+ */
+
+/**
+ * Pure Node-major check. Reads the minimum from the passed `engines` range
+ * (the CLI's own `engines.node`, so the requirement lives in one place) and
+ * compares the running major. Fails open (`ok: true`) on an unparseable running
+ * version so an unusual runtime is not blocked; falls back to 24 when the
+ * engines range carries no integer.
+ * @param {string} current  running Node version (e.g. `process.versions.node`)
+ * @param {string} engines  the CLI package's `engines.node` range
+ * @returns {{ ok: boolean, current: string, currentMajor: number, requiredMajor: number }}
+ */
+export function checkNodeInline(current, engines) {
+  const cm = String(current).match(/^v?(\d+)/);
+  const rm = String(engines).match(/(\d+)/);
+  const currentMajor = cm ? Number(cm[1]) : NaN;
+  const requiredMajor = rm ? Number(rm[1]) : 24;
+  const ok = Number.isNaN(currentMajor) || currentMajor >= requiredMajor;
+  return { ok, current, currentMajor, requiredMajor };
+}
+
+/**
+ * Compose the actionable stderr message for an unsupported Node. Names the found
+ * and required version and the reason (the built-in TS strip + recursive
+ * fs.watch need Node 24+).
+ * @param {{ current: string, currentMajor: number, requiredMajor: number }} r
+ * @returns {string}
+ */
+export function nodeInlineMessage(r) {
+  return (
+    `webjs requires Node ${r.requiredMajor}+ but found Node ${r.current}. ` +
+    `webjs is buildless and relies on Node ${r.requiredMajor}'s built-in ` +
+    `TypeScript strip (module.stripTypeScriptTypes) and recursive fs.watch, ` +
+    `neither of which exists on Node ${r.currentMajor}. ` +
+    `Upgrade to Node ${r.requiredMajor} or newer (see https://nodejs.org).`
+  );
+}

package/lib/saas-template.js

@@ -174,7 +174,7 @@ export async function writeSaasFiles(appDir) {
   ].join('\n'));
 
   // test/unit/auth.test.ts: minimal stub so the scaffold passes
-  // `webjs check` (tests-exist) and `webjs test` runs cleanly out of the
+  // `webjs test` runs cleanly out of the
   // box. The signup/current-user functions import from lib/prisma.server.ts
   // and lib/auth.server.ts, both of which need `prisma generate` to have run before
   // they can be imported, so we deliberately test only the runtime-
@@ -276,6 +276,7 @@ export async function writeSaasFiles(appDir) {
   await mkdir(join(appDir, 'app', 'signup'), { recursive: true });
   await writeFile(join(appDir, 'app', 'signup', 'page.ts'), [
     "import { html } from '@webjsdev/core';",
+    "import { signup } from '../../modules/auth/actions/signup.server.ts';",
     "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass, cardFooterClass } from '../../components/ui/card.ts';",
     "import { buttonClass } from '../../components/ui/button.ts';",
     "import { inputClass } from '../../components/ui/input.ts';",
@@ -283,7 +284,30 @@ export async function writeSaasFiles(appDir) {
     "",
     "export const metadata = { title: 'Sign up' };",
     "",
-    "export default function SignupPage() {",
+    "// Page server action: handles the POST from the form below. With JS",
+    "// disabled this is a plain <form> round-trip; with JS the client router",
+    "// swaps the 422 re-render (errors) or follows the 303 (success) in place.",
+    "// A validation failure returns fieldErrors + values so the page re-renders",
+    "// with messages and the user's typed input preserved (#244).",
+    "export async function action({ formData }: { formData: FormData }) {",
+    "  const name = String(formData.get('name') || '').trim();",
+    "  const email = String(formData.get('email') || '').trim();",
+    "  const password = String(formData.get('password') || '');",
+    "  const values = { name, email };",
+    "  const fieldErrors: Record<string, string> = {};",
+    "  if (!name) fieldErrors.name = 'Name is required';",
+    "  if (!email.includes('@')) fieldErrors.email = 'Enter a valid email';",
+    "  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' };",
+    "}",
+    "",
+    "export default function SignupPage({ actionData }: { actionData?: { fieldErrors?: Record<string, string>; values?: Record<string, string> } }) {",
+    "  const errors = actionData?.fieldErrors || {};",
+    "  const values = actionData?.values || {};",
     "  return html`",
     "    <div class=\"max-w-sm mx-auto mt-12\">",
     "      <div class=${cardClass()}>",
@@ -292,18 +316,21 @@ export async function writeSaasFiles(appDir) {
     "          <p class=${cardDescriptionClass()}>Get started with your new workspace.</p>",
     "        </div>",
     "        <div class=${cardContentClass()}>",
-    "          <form id=\"signup-form\" class=\"flex flex-col gap-4\">",
+    "          <form method=\"POST\" class=\"flex flex-col gap-4\">",
     "            <div class=\"flex flex-col gap-1.5\">",
     "              <label class=${labelClass()} for=\"name\">Name</label>",
-    "              <input class=${inputClass()} id=\"name\" name=\"name\" type=\"text\" required>",
+    "              <input class=${inputClass()} id=\"name\" name=\"name\" type=\"text\" value=${values.name || ''} required>",
+    "              ${errors.name ? html`<p class=\"text-sm text-destructive\">${errors.name}</p>` : ''}",
     "            </div>",
     "            <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>",
+    "              <input class=${inputClass()} id=\"email\" name=\"email\" type=\"email\" value=${values.email || ''} required>",
+    "              ${errors.email ? html`<p class=\"text-sm text-destructive\">${errors.email}</p>` : ''}",
     "            </div>",
     "            <div class=\"flex flex-col gap-1.5\">",
     "              <label class=${labelClass()} for=\"password\">Password</label>",
-    "              <input class=${inputClass()} id=\"password\" name=\"password\" type=\"password\" required>",
+    "              <input class=${inputClass()} id=\"password\" name=\"password\" type=\"password\" minlength=\"8\" required>",
+    "              ${errors.password ? html`<p class=\"text-sm text-destructive\">${errors.password}</p>` : ''}",
     "            </div>",
     "            <button class=${buttonClass()} type=\"submit\">Create account</button>",
     "          </form>",

package/package.json

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

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

@@ -12,8 +12,9 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**.
   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.
+  use localStorage for app data. These are project conventions in
+  CONVENTIONS.md (a JSON file used as a database resets on reload and
+  cannot scale).
 - **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

package/templates/.cursorrules

@@ -12,8 +12,8 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**.
   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.
+  a substitute. NEVER use localStorage for app data. These are project conventions in CONVENTIONS.md (a JSON file used as a
+  database resets on reload and cannot scale).
 - **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. Don't ship "Hello from

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

@@ -12,8 +12,8 @@ the full hosted docs are at **https://docs.webjs.com**.
   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.
+  a substitute. NEVER use localStorage for app data. It resets on reload and cannot scale. This is a project convention
+  (CONVENTIONS.md).
 - **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. Don't ship "Hello from

package/templates/AGENTS.md

@@ -24,8 +24,8 @@ the app the user actually asked for.
    stores (todos, posts, messages, products, comments, anything),
    define a Prisma model and persist there.
    - **NEVER** store app data in JSON files (`data/todos.json`,
-     `db.json`, …). The convention check `no-json-data-files` flags
-     this and the user's prompt explicitly forbids it.
+     `db.json`, …). It resets on reload and cannot scale. This is a project convention,
+     and the user's prompt explicitly forbids it.
    - **NEVER** use in-memory arrays or `Map`s as a substitute for the
      database. They vanish on every dev-server reload and aren't
      shared across processes.
@@ -440,7 +440,7 @@ import { createContext } from '@webjsdev/core/context';
 import { Task } from '@webjsdev/core/task';
 import { fixture, waitForUpdate } from '@webjsdev/core/testing';
 
-import { rateLimit, cache, createAuth, Credentials, Session } from '@webjsdev/server';
+import { rateLimit, cors, cache, createAuth, Credentials, Session } from '@webjsdev/server';
 ```
 
 ## Environment variables (server vs browser)
@@ -588,7 +588,8 @@ Practical consequences for agents writing webjs code.
 | Class-field initializer for a reactive property (`student: Student = {...}`) | Silently breaks reactivity (overwrites the framework accessor) | `declare student: Student` plus constructor default |
 | `@property()` decorator | Banned by invariant 10 (erasable TS) | `static properties = { ... }` plus `declare` |
 | `static styles = css` block without `static shadow = true` | Styles leak globally; the framework warns at runtime | Add `static shadow = true`, or use Tailwind utilities |
-| `willUpdate` computing SSR-visible derived state | Field is `undefined` in SSR HTML (hook is client-only) | Compute inline in `render()` |
+| `willUpdate` computing SSR-visible derived state | Works (runs at SSR), but overriding it opts the component out of elision | Fine for interactive components; for display-only, derive inline in `render()` |
+| `this.hasAttribute` / `getAttribute` in `render()` | Works (server attribute shim backs the attribute methods at SSR) | Read attributes directly, or via a `static properties` + `declare` reactive prop |
 | `ContextProvider` for server-known data | Default value during SSR, content shift on hydration | Pass via props from the page function |
 
 The full annotated catalog with code examples lives in the framework
@@ -943,5 +944,6 @@ composition, so a nested shell ends up dropped by the HTML parser.
 5. When unsure how a framework feature works, `grep` or `cat` the
    relevant `node_modules/@webjsdev/*/src/` file before asking the user.
 
-Project-specific conventions and overrides live in
-[CONVENTIONS.md](./CONVENTIONS.md).
+Project conventions live in [CONVENTIONS.md](./CONVENTIONS.md) (guidance
+you follow by judgment). `webjs check` is separate: correctness checks
+only, always on, no per-project disabling.

package/templates/CONVENTIONS.md

@@ -9,59 +9,41 @@ Edit the content below the marker to change the convention for your project.
 
 ---
 
-## How `CONVENTIONS.md` relates to `webjs check`
-
-This markdown file holds **architectural conventions** (modules layout,
-styling, testing, git workflow) that the linter can't enforce
-programmatically. The `<!-- OVERRIDE -->` markers let you customize
-those for this project, and AI agents read them when writing code.
-
-The **lint rules** are a separate, narrower thing: the boolean checks
-that `webjs check` runs (one function per action, components register
-themselves, tag names have hyphens, etc.). They are NOT documented in
-this file. Their **single source of truth** is the
-`"webjs": { "conventions": { … } }` key in `package.json`.
-
-If that key is absent, **every default rule is enabled** and AI agents
-must follow all of them.
-
-### Discovering the active rules
-
-```sh
-webjs check --rules
-```
-
-prints every available rule with its description and shows which ones
-are currently disabled by this project's overrides. That command is the
-**authoritative** list. Do not maintain a copy elsewhere; it will drift.
-
-### Disabling a rule
-
-Add the rule name to `package.json` with a value of `false`:
-
-```jsonc
-{
-  "webjs": {
-    "conventions": {
-      "tests-exist": false,
-      "actions-in-modules": false
-    }
-  }
-}
-```
-
-Only `false` is meaningful. There's no way to tweak rule *behaviour*
-via config. A rule is either on or off.
-
-### Rule for AI agents
-
-1. Run `webjs check --rules` to learn the active rule set for this
-   project.
-2. Treat every rule not explicitly disabled as binding when writing
-   code.
-3. To change which rules are active, edit the `webjs.conventions`
-   block in `package.json`. Never inline a rule list into prose, since
-   it will drift.
+## `CONVENTIONS.md` vs `webjs check`: two different things
+
+This file is the source of truth for **project conventions**: how code
+is organized, named, and tested. They are preferences a reasonable
+project could do differently, so they are guidance (for humans and AI
+agents), not a hard gate. Customize any of them; sections marked
+`<!-- OVERRIDE -->` are explicit customization points.
+
+`webjs check` is a separate, narrower tool: **correctness checks** that
+catch objectively broken code (a crash, a security leak, a build or
+type-strip failure). Those always run, there is no per-project
+disabling, and they are not listed here (run `webjs check --rules` to
+see them). The line between the two: *could a sensible app legitimately
+want this to pass?* If yes, it is a convention (this file); if no, it is
+a check (the tool).
+
+### Project conventions (follow these)
+
+These are the architectural conventions for this app. They are not
+enforced by `webjs check`; follow them by judgment.
+
+- **Server actions and queries live in `modules/<feature>/actions/` and
+  `modules/<feature>/queries/`** (`*.server.{js,ts}`), not loose in the
+  app root. Cross-cutting server infrastructure (the Prisma singleton,
+  session helpers, auth config) lives in `lib/`.
+- **One exported function per action/query file.** Name the file after
+  the function (`create-post.server.ts` exports `createPost`). It keeps
+  the action surface greppable.
+- **Every feature has tests.** A `modules/<feature>/` directory should
+  have matching test files under `test/<feature>/`. A unit test for
+  logic, a browser/e2e test for user-facing behaviour.
+- **Persist data with Prisma + SQLite, never JSON files.** The scaffold
+  wires up `prisma/schema.prisma` and `lib/prisma.server.ts`. A
+  `data/todos.json` or `db.json` used as a database resets on reload and
+  cannot scale; define a Prisma model instead.
 
 ---
 
@@ -125,9 +107,9 @@ checklist mirrors this list.
    If yes, update it on this PR. Common surfaces (non-exhaustive):
    - `AGENTS.md` (root and every nested one) for API surface, invariants,
      file-routing rules, project-wide agent workflow.
-   - `CONVENTIONS.md` (this file) for architectural conventions. Do NOT
-     enumerate lint rules in prose; those live in `package.json` under
-     `"webjs": { "conventions": { … } }`.
+   - `CONVENTIONS.md` (this file) for project conventions (layout,
+     naming, testing). The `webjs check` correctness rules are a separate
+     tool surface, not documented here (run `webjs check --rules`).
    - `README.md` (root and any nested ones) for install / use / public
      surface descriptions.
    - `CHANGELOG.md` for any user-visible change, including the SHA / PR
@@ -267,8 +249,8 @@ deploy`, and `npm run db:migrate` / `db:generate` / `db:studio` scripts.
    comments, users…), define a Prisma model in `prisma/schema.prisma`
    and persist there.
 2. **NEVER** create JSON files under `data/`, `db.json`, `posts.json`,
-   `todos.json`, etc. as a fake database. The `no-json-data-files`
-   convention check flags this and `webjs check` will fail.
+   `todos.json`, etc. as a fake database. It resets on reload and cannot
+   scale; this is a project convention (see the conventions section above).
 3. **NEVER** use module-scope arrays or `Map`s as a "store". They
    reset on every dev-server reload and can't scale beyond one process.
 4. **NEVER** use `localStorage` / `sessionStorage` to persist app data -
@@ -878,11 +860,15 @@ toggle, the tab switch) requires JS.
   JS will fill it in. The first paint must be the right content.
 
 **SSR-meaningful component state.** The SSR pipeline constructs the
-component, applies its attributes, and calls `render()`. It does NOT
-call `connectedCallback`, `firstUpdated`, or any other browser-only
-lifecycle hook. Whatever state should appear on first paint MUST be
-set in the constructor (after `super()`) or be derivable from
-`static properties` + attributes on the rendered tag.
+component, applies its attributes, runs `willUpdate` and controllers'
+`hostUpdate`, and calls `render()`. It does NOT call `connectedCallback`,
+`firstUpdated`, `updated`, or any other browser-only lifecycle hook.
+Whatever state should appear on first paint MUST be set in the
+constructor (after `super()`), derived in `willUpdate`, or derivable
+from `static properties` + attributes on the rendered tag. Reading
+`this.getAttribute` / `hasAttribute` in `render()` works server-side (a
+server attribute shim backs the attribute methods), but a `Task`'s
+fetch still runs only on the client.
 
 ```ts
 import { WebComponent, html, signal } from '@webjsdev/core';
@@ -1019,15 +1005,17 @@ This project enforces a git workflow via agent-specific config files
 
 ---
 
-## Overriding conventions
+## Customizing conventions
 
-See the **"How `CONVENTIONS.md` relates to `webjs check`"** section at
-the top of this file. Short version: set a rule to `false` in
-`package.json` under `"webjs": { "conventions": { … } }`. With no
-override, every default rule is on.
+The conventions in this file are guidance, so customize them directly:
+edit the prose under any `<!-- OVERRIDE -->` marker. There is no
+`package.json` switch and nothing to toggle, because conventions are not
+enforced by a tool.
 
-Run `webjs check` to validate. Run `webjs check --rules` to list every
-rule with its description and current enabled state.
+`webjs check` is separate: it runs only correctness checks (a crash, a
+security leak, a build/type-strip failure), always, with no per-project
+disabling. Run `webjs check` to validate, and `webjs check --rules` to
+list those checks.
 
 ---
 

package/templates/Dockerfile

@@ -8,6 +8,14 @@
 # falls back to esbuild, whose class-declaration transform breaks webjs's SSR
 # walker for multi-class component files. Do not lower this base image
 # below 24 (the same version the CI workflow and the framework pin).
+#
+# Security headers are set by the framework, not the proxy. webjs emits
+# X-Content-Type-Options, X-Frame-Options, Referrer-Policy, and
+# Permissions-Policy on every response, plus Strict-Transport-Security in
+# production over HTTPS (detected from X-Forwarded-Proto on the trusted
+# edge). So the baseline needs no reverse-proxy config. Override or extend
+# per path with package.json "webjs": { "headers": [...] }. See the
+# framework AGENTS.md "Secure response headers" section.
 FROM node:24-alpine
 
 # openssl + ca-certificates are required by Prisma's query engine at runtime.