@webjsdev/cli 0.10.2 → 0.10.4

package/bin/webjs.js

@@ -15,7 +15,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
@@ -212,22 +212,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 +229,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

@@ -536,7 +536,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 +820,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/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-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "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.
@@ -318,12 +318,17 @@ Fully warm means the deterministic analysis AND the first vendor attempt have
 both completed, so the importmap and its build id are settled. Point your
 platform's readiness check at `/__webjs/ready` so it holds traffic off a
 not-yet-warmed instance instead of routing the first user request into the cold
-analysis or the brief window where the importmap is still resolving. On
-Railway, set `"healthcheckPath": "/__webjs/ready"` under `deploy` in
-`railway.json`. For dependency-aware
-readiness (gate on a live DB ping), add an optional `readiness.{js,ts}` at the
-app root that default-exports an async check; `/__webjs/ready` runs it once warm
-and reports 503 if it returns `false` or throws.
+analysis or the brief window where the importmap is still resolving. The
+scaffolded `Dockerfile` and `compose.yaml` already wire this up with a
+`HEALTHCHECK` that probes `/__webjs/ready`, so any Docker-based deploy gets the
+gate with no extra config. On a platform that reads its own config instead,
+point its equivalent knob at the same path: Railway `"healthcheckPath":
+"/__webjs/ready"`, Render `healthCheckPath: /__webjs/ready`, Fly a
+`[[http_service.checks]]` on `/__webjs/ready`, or a Kubernetes `readinessProbe`
+with `httpGet.path: /__webjs/ready`. For dependency-aware readiness (gate on a
+live DB ping), add an optional `readiness.{js,ts}` at the app root that
+default-exports an async check; `/__webjs/ready` runs it once warm and reports
+503 if it returns `false` or throws.
 
 Scripts:
 
@@ -583,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
@@ -938,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

@@ -33,6 +33,17 @@ ENV NODE_ENV=production
 ENV PORT=8080
 EXPOSE 8080
 
+# Platform-neutral readiness gate. webjs answers /__webjs/ready with 503 until
+# the instance is fully warm (analysis + first vendor attempt), then 200. This
+# HEALTHCHECK is honoured by Docker, compose, and most Docker-based platforms,
+# so the gate works the same everywhere instead of needing a per-platform file.
+# The probe is dependency-free (Node 24's built-in fetch, no curl/wget). For
+# platforms that read their own config, point the equivalent knob at the same
+# path (Railway healthcheckPath, Render healthCheckPath, Fly [checks], k8s
+# readinessProbe); see AGENTS.md "Health and readiness probes".
+HEALTHCHECK --interval=15s --timeout=3s --start-period=40s --retries=5 \
+  CMD ["node", "-e", "fetch('http://127.0.0.1:'+(process.env.PORT||8080)+'/__webjs/ready').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
+
 # `npm start` runs `prestart: prisma migrate deploy` (idempotent, a no-op when
 # there are no migrations yet) and then `webjs start`, which serves on $PORT.
 CMD ["npm", "start"]

package/templates/compose.yaml

@@ -23,6 +23,14 @@ services:
       # REDIS_URL: redis://redis:6379
     volumes:
       - app-data:/data
+    # Readiness gate: hold the service "starting" until /__webjs/ready returns
+    # 200 (fully warm). Same probe as the Dockerfile HEALTHCHECK; dependency-free.
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:'+(process.env.PORT||8080)+'/__webjs/ready').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
+      interval: 15s
+      timeout: 3s
+      start_period: 40s
+      retries: 5
 
 volumes:
   app-data: