@webjsdev/cli 0.10.57 → 0.10.59

package/templates/.agents/skills/webjs/SKILL.md

@@ -264,6 +264,7 @@ Success is a 303 (PRG); failure re-renders the page at 422 with the result on `a
 
 ## Testing Defaults
 
+- `npm run ci` before every push: it runs the `webjs.ci` step list in `package.json` (correctness, project health, types, a dependency audit, then the server, browser, and e2e test layers) with a result line per step, and CI runs the same list, so a green local run predicts the pipeline. `npm run ci -- --only Tests` runs one layer while iterating. See `references/testing.md` and `references/built-ins.md`.
 - Prefer server/handler tests first: drive the app with `handle()` from `@webjsdev/server/testing` and assert on the `Response`.
 - Add a browser test (`npm run test:browser`) for anything touching hydration, the client router, slots, or custom-element upgrade. A unit test is necessary but NOT sufficient for a browser-facing change.
 - Render the app and LOOK for any UI change: `npm run check` and `npm run typecheck` pass even when a layout collapses. Static tools give no signal for a visual defect.

package/templates/.agents/skills/webjs/references/auth-and-sessions.md

@@ -113,6 +113,17 @@ export const POST = handlers.POST;
 <form method="POST" action="/api/auth/signout"><button>Log out</button></form>
 ```
 
+**OAuth sign-in returns the user where they started, with the same one form.** POST to `/api/auth/signin/github` (or `google`) with a hidden `redirectTo`, or link to `GET /api/auth/signin/github?redirectTo=/dashboard/x`; `signIn('github', undefined, { redirectTo })` does the same from an action. The target rides through the provider round trip in a short-lived signed cookie and the callback lands on it, so no wrapper around the auth route is needed:
+
+```html
+<form method="POST" action="/api/auth/signin/github">
+  <input type="hidden" name="redirectTo" value="/dashboard/x">
+  <button>Sign in with GitHub</button>
+</form>
+```
+
+A `redirectTo` that arrives from a request (a form field or a query param, for OAuth or credentials) must be a same-origin local path: one leading `/`, not followed by `/` or `\`. An absolute URL, a protocol-relative `//host`, or a backslash variant is dropped (not repaired) and the sign-in lands on `/`, so the field is never an open redirect. A denied sign-in still goes to `pages.error`.
+
 For a programmatic sign-in (the auto-login-after-signup pattern), `signIn('credentials', creds, { redirectTo })` returns a `302` `Response` that a form-bound action can return directly (the framework honors a returned `Response` verbatim).
 
 Sessions are JWT by default (stateless, scales horizontally). OAuth

package/templates/.agents/skills/webjs/references/built-ins.md

@@ -22,6 +22,24 @@ Read this when wiring caching or rate limiting, storing uploads, hardening heade
 | `REDIS_URL` | When set, sessions, rate limit, and cache use Redis instead of memory |
 | `SESSION_SECRET` / `AUTH_SECRET` | Session and auth signing (see `auth-and-sessions.md`) |
 | `PORT` | Listen port. Precedence `--port` flag, then `PORT` (real env or `.env`), then `8080` |
+| `WEBJS_SOURCE_LOCATIONS` | `webjs dev` only. `1` stamps `data-webjs-src="<app-relative-file>:<line>"` on the elements of the app's `html` templates (see below). Ignored by `webjs start` |
+| `WEBJS_EMBED_ORIGINS` | `webjs dev` only. Comma-separated parent origins (`https://builder.dev,http://localhost:8080`) allowed to frame the dev server and receive the embed bridge's messages (see below). Ignored by `webjs start` |
+
+**Source locations for tooling (`WEBJS_SOURCE_LOCATIONS=1`, dev only).** A tool that hosts the app (an inspector, click-to-edit in an embedding builder) can map a clicked element back to the line that wrote it. With the variable set, `webjs dev` adds `data-webjs-src="components/todo-list.ts:12"` to every element opening tag written in an `html` template inside the app, both in the SSR markup and in client renders (one source transform applied to the served module and to the module the server imports, so the two agree and hydration is unaffected). Read it with `el.closest('[data-webjs-src]')`. Not annotated: `*.server.*` modules, `node_modules`, `css` / `svg` tagged templates, `html` / `head` / `body` / head-only and raw-text elements, and the descendants of `svg` / `math`. Lines are exact; nothing reaches production. The importmap `<script>` in `<head>` carries an unrelated `data-webjs-src` (the app-source deploy id), so match the `file:line` value shape when querying the whole document.
+
+**Embed bridge for iframe previews (`WEBJS_EMBED_ORIGINS`, dev only).** A tool that previews the app inside an iframe (an app builder, a docs playground) sets `WEBJS_EMBED_ORIGINS` to its own origin(s). `webjs dev` then (1) drops `X-Frame-Options` and adds those origins to a CSP `frame-ancestors`, so the frame loads without the app stripping headers in `webjs.headers`, and (2) inlines a small nonce-signed script into every document that, when framed by a listed origin, posts to `window.parent` (with that exact target origin, never `*`):
+
+```js
+{ source: 'webjs-embed', type: 'ready', path, title }            // document parsed
+{ source: 'webjs-embed', type: 'navigate', path, title }         // every client-router navigation + popstate
+{ source: 'webjs-embed', type: 'console', level: 'error' | 'warn', message, dropped? } // max 20/s
+{ source: 'webjs-embed', type: 'error', message, stack, file, line, column }          // window error + unhandledrejection
+{ source: 'webjs-embed', type: 'network', method, url, status, error? }               // fetch/XHR status >= 500, or status 0 on failure
+{ source: 'webjs-embed', type: 'server-error', kind, message, file, line, path }      // the dev error overlay went up
+{ source: 'webjs-embed', type: 'select', src, tag, text, rect: { x, y, width, height } } // a click in inspect mode
+```
+
+and accepts, only from `window.parent` on a listed origin: `{ source: 'webjs-embed-host', type: 'navigate', path }` (a local path; a soft navigation when the client router is on), `{ source: 'webjs-embed-host', type: 'reload' }`, and `{ source: 'webjs-embed-host', type: 'inspect', enabled: true | false }` (hover highlight plus click capture that posts `select`; `src` is the nearest `data-webjs-src`, so pair it with `WEBJS_SOURCE_LOCATIONS=1` for click-to-edit). Paths are app paths (`/api/x`, `/components/x.ts`). Unset adds zero bytes; `webjs start` never injects it nor relaxes a header.
 
 Defaults are single-instance memory stores. To scale horizontally, switch the store once at startup: `setStore(redisStore({ url: process.env.REDIS_URL }))`.
 
@@ -216,6 +234,48 @@ An over-limit body responds `413` without buffering the whole payload.
 
 `before` runs to completion first (a non-zero exit aborts the boot). `parallel` (dev only) runs long-lived watchers alongside the server and tears them down on exit. `watch` (dev only) adds extra live-reload directories outside the app tree.
 
+### Local CI (`webjs.ci`)
+
+`webjs ci` runs the step list the block declares, the Rails 8.1 `bin/ci` posture: your machine is the first CI runner, and a cloud pipeline runs the SAME list by calling `npm run ci`, so the two cannot drift. Each step prints a heading, then `✅ <title> passed in 2.11s` or `❌ <title> failed in 0.01s`; the run ends with every failure listed and one total line, and exits 1 on any failure.
+
+```jsonc
+{ "webjs": { "ci": { "steps": [
+  { "title": "Setup", "run": "webjs db migrate" },
+  { "title": "Checks", "parallel": 2, "steps": [        // two at a time
+    "webjs check",                                       // a string is a command titled by itself
+    { "title": "Types", "run": "webjs typecheck" },
+    { "title": "Tests", "steps": [                       // a nested group takes ONE slot, runs in order
+      { "title": "Tests: server", "run": "webjs test --server" },
+      { "title": "Tests: e2e", "run": "webjs test --server", "env": { "WEBJS_E2E": "1" } }
+    ] }
+  ] }
+] } } }
+```
+
+A step is a string, a `{ title, run, env? }` command, or a `{ title, steps, parallel? }` group. `parallel` is a slot count (default 1); a parallel group captures each step's output and replays it whole when the step finishes, so two steps never interleave, and a group nested inside it takes one slot and runs sequentially (it cannot declare `parallel`, which the reader reports rather than honours). `env` is per-step, so the e2e opt-in does not depend on a shell prefix. Every child runs with `CI=true`, `node_modules/.bin` on PATH, and `.env` loaded first (a real env var wins), so a `webjs db migrate` step sees `DATABASE_URL`.
+
+Flags: `-f` / `--fail-fast` stops after the first failure (the default runs everything and lists every failure), `--only <title>` runs one step or group by title (repeatable, an unknown title is an error rather than an empty green run), `--json` emits one document on stdout (`{ ok, seconds, steps: [{ title, run, group, ok, code, seconds, output? }] }`, failed steps carrying their captured output, the human report on stderr) for an agent loop, and `--signoff` runs `gh signoff` after a green run. To hold a merge until a LOCAL run is green, install `basecamp/gh-signoff`, run `gh signoff install` once (a branch-protection rule requiring the `signoff` status), and run `npm run ci -- --signoff`; a red run posts nothing.
+
+Under GitHub Actions each step is a `::group::` in the log, a failed step is an `::error::` annotation, and a step table is appended to the job summary, so a single job running the whole list still names the layer that broke. The scaffold's workflow is exactly that one job; `webjs create --skip-ci` omits it and the local list always ships. A malformed block (a group with no title, a nested `parallel`, an unknown key) refuses to run and names every problem by JSON path, because a silently dropped step is a check that never ran. Nothing declared is exit 1 too, naming any workspace member that declares one, since "ran zero steps" would read as green.
+
+### Bring your own ORM (`webjs.db`)
+
+Drizzle is the scaffold DEFAULT, not lock-in. The runtime never imports it, `db/connection.server.ts` is the app's own file, and `webjs db` is adapter-driven: a `db` block maps each verb to the shell command `webjs db <verb>` runs instead of the drizzle-kit default (node_modules/.bin on PATH like a `before` step, extra CLI args appended).
+
+```jsonc
+{ "webjs": {
+  "db": {
+    "generate": "prisma migrate dev --create-only",
+    "migrate":  "prisma migrate deploy",
+    "push":     "prisma db push",
+    "studio":   "prisma studio",
+    "reset":    "prisma migrate reset --force"
+  }
+} }
+```
+
+Any key is a verb (`reset` above adds `webjs db reset`). A verb the block does not name keeps its default (drizzle-kit for `generate` / `migrate` / `push` / `studio`, `db/seed.server.ts` for `seed`), so an app with no block is unchanged and the scaffold emits none. The payoff is that `webjs db migrate` stays one spelling across ORMs, so the scaffolded `dev.before` / `start.before`, the Dockerfile, CI, and the deploy docs all keep working after a swap. Write the bare binary (`prisma migrate deploy`), not `npx prisma ...`, since a pure Bun image has no `npx`. The swap itself is the app's own files: replace `db/connection.server.ts` with the new client, drop `drizzle.config.ts` / `db/columns.server.ts`, and keep server-only imports behind `.server.ts` as before.
+
 ### Doctor severity gate
 
 `webjs doctor` reports project health, and by default only a broken toolchain fails the exit. `--strict` makes EVERY warning fatal, which is unusable in CI, because four checks are environment-shaped: `GIT_HOOK` wants a local pre-commit hook a runner has no reason to have, `ENV_DRIFT` compares against a `.env` CI does not carry, `VENDOR_PIN` fetches the network, and `FRAMEWORK_RESOLVE` plus `FRAMEWORK_LINKS` depend on the environment. So per-check severity is CONFIG, keyed by the stable code every result carries.
@@ -233,6 +293,25 @@ Three levels, the same scale ESLint uses: `error` fails the exit, `warn` reports
 
 Two guarantees worth knowing. A result that could not check (a network or toolchain outage) is capped at `warn` and can never be escalated, so a jspm or npm outage cannot red your CI. And a malformed gate exits 1 naming the offender rather than being ignored, so a typo cannot silently un-gate the build. That covers an unknown code, a bad severity, a wrong shape (a non-object `doctor` or `gate`), and a misspelled sibling of `gate` such as `gates`, since every one of those would otherwise leave the build un-gated while the `package.json` looks gated. Under `--json` the offenders come back as a `configErrors` array alongside an empty `results`, each entry a `{ kind }` of `malformed` / `unknown-key` / `unknown-code` / `bad-severity`. Wire it up with one workflow step, `npm run doctor`, and change what is fatal in `package.json` rather than in the workflow.
 
+### Dependency audit allowlist
+
+`webjs audit` runs `npm audit` or `bun audit` (by the nearest lockfile, so a workspace member uses the root's) and fails on any advisory at or above `webjs.audit.level` (default `high`) that `webjs.audit.ignore` does not list. The scaffold's `Security: dependency audit` CI step runs it.
+
+```jsonc
+{ "webjs": {
+  "audit": {
+    "level": "high",
+    "ignore": [
+      { "id": "GHSA-vfj7-8cjw-p6xm", "reason": "braces has no patched release; reached only through dev tooling" }
+    ]
+  }
+} }
+```
+
+The allowlist is the ONE place an accepted advisory lives, each with its reason. Accept only an advisory with no patched release that the app's users cannot reach; upgrade anything that has a fix. Never "fix" a red audit with `npm audit fix --force`, which proposes breaking majors that often keep the same vulnerable chain. A malformed block (unknown key, bad level, an entry without an id or a reason) exits 1, and an id the audit stops reporting prints as stale, so remove it then.
+
+Overrides apply only at a WORKSPACE ROOT. The scaffold's `overrides` block (the `puppeteer-core` and `basic-ftp` security floors) is ignored once the app is a member of an npm or bun workspace, so move it into the root `package.json`; `webjs doctor` warns with `WORKSPACE_OVERRIDES` until you do.
+
 ## Observability
 
 Wired at the single response funnel, covering pages, routes, actions, and assets uniformly.

package/templates/.agents/skills/webjs/references/styling.md

@@ -115,7 +115,7 @@ So near an island the fragment is the smaller and more predictable choice, not a
 
 ### A design system for repeated PRIMITIVES: class helpers built on `@webjsdev/ui`
 
-An `html`-fragment helper is right for a repeated CHUNK of markup (the rubric above). For a repeated UI PRIMITIVE (button, input, card, badge) that needs variants and sizes, use a class helper instead: a function that returns a Tailwind class STRING you spread onto a native element. That is exactly what `@webjsdev/ui` ships (`buttonClass({ variant, size })`, `cardClass()`, `inputClass()`, `badgeClass({ variant })`), and it is what the scaffold gallery uses in `components/ui/`. To style a ONE-OFF that a variant does not cover (a circular icon button, a pill), compose the helper and override the bespoke bits with `cn()`: `cn(buttonClass({ variant: 'secondary', size: 'none' }), 'w-9 h-9 rounded-full')`. `cn` resolves Tailwind conflicts so a later class wins, including a shorthand over the axis it subsumes (`p-0` beats an earlier `px-4 py-2`), so an override just works. Conflicts are keyed on the CSS PROPERTY wherever `cn` can tell the properties apart, rather than on the shared class prefix, so the common prefix collisions do NOT evict: `cn('border-2', 'border-primary')` keeps both (a width and a colour), `cn('flex', 'flex-1')` keeps both (a `display` and a `flex-grow`, the shape an element that is both a flex container and a flex child needs), `cn('shadow-lg', 'shadow-red-500')` keeps both (a box-shadow and its colour), `cn('bg-clip-text', 'bg-primary')` keeps both (a clip and a colour, so the gradient-text idiom survives a later background), and an arbitrary value carrying a type hint is read as the property the hint names (`cn('shadow-lg', 'shadow-[color:red]')` keeps both). It is a small hand-rolled merger, not `tailwind-merge`, so it is still coarse in two ways. A prefix outside the families it knows is not grouped at all, so both classes are emitted and the winner is left to compiled stylesheet order (`inset-shadow-sm` against `inset-shadow-red-500`, `ring-2` against `ring-red-500`). And where one prefix carries two properties it reads the value against Tailwind's DEFAULT scales, so a `@theme`-extended name it cannot know about can still be misread and evict the wrong class: a custom `--shadow-card` makes `shadow-card` a box-shadow, but `cn` sees an unfamiliar name under a prefix whose bare names are usually colours and treats it as one. When an override has to win and you are unsure, pass the one class rather than layering, or install `clsx` + `tailwind-merge` and replace the helper (its header comment shows the swap). For an icon button prefer `size: 'none'` (it states "I supply my own box" by dropping the helper's padding + radius) over layering a `p-0` on top of the default size.
+An `html`-fragment helper is right for a repeated CHUNK of markup (the rubric above). For a repeated UI PRIMITIVE (button, input, card, badge) that needs variants and sizes, use a class helper instead: a function that returns a Tailwind class STRING you spread onto a native element. That is exactly what `@webjsdev/ui` ships (`buttonClass({ variant, size })`, `cardClass()`, `inputClass()`, `badgeClass({ variant })`), and it is what the scaffold gallery uses in `components/ui/`. To style a ONE-OFF that a variant does not cover (a circular icon button, a pill), compose the helper and override the bespoke bits with `cn()`: `cn(buttonClass({ variant: 'secondary', size: 'none' }), 'w-9 h-9 rounded-full')`. `cn` resolves Tailwind conflicts so a later class wins, including a shorthand over the axis it subsumes (`p-0` beats an earlier `px-4 py-2`), so an override just works. Conflicts are keyed on the CSS PROPERTY wherever `cn` can tell the properties apart, rather than on the shared class prefix, so the common prefix collisions do NOT evict: `cn('border-2', 'border-primary')` keeps both (a width and a colour), `cn('flex', 'flex-1')` keeps both (a `display` and a `flex-grow`, the shape an element that is both a flex container and a flex child needs), `cn('shadow-lg', 'shadow-red-500')` keeps both (a box-shadow and its colour), `cn('bg-clip-text', 'bg-primary')` keeps both (a clip and a colour, so the gradient-text idiom survives a later background), and an arbitrary value carrying a type hint is read as the property the hint names (`cn('shadow-lg', 'shadow-[color:red]')` keeps both). It is a small hand-rolled merger, not `tailwind-merge`, so it is still coarse in two ways. A prefix outside the families it knows is not grouped at all, so both classes are emitted and the winner is left to compiled stylesheet order (`inset-shadow-sm` against `inset-shadow-red-500`, `ring-2` against `ring-red-500`). And where one prefix carries two properties it reads the value against Tailwind's DEFAULT scales, so a `@theme`-extended name it cannot know about can still be misread and evict the wrong class: a custom `--shadow-card` makes `shadow-card` a box-shadow, but `cn` sees an unfamiliar name under a prefix whose bare names are usually colours and treats it as one. When an override has to win and you are unsure, pass the one class rather than layering, or install `clsx` + `tailwind-merge` and replace the helper (its header comment shows the swap). For an icon button prefer `size: 'none'` (it states "I supply my own box" by dropping the helper's padding + radius) over layering a `p-0` on top of the default size. Under the opt-in `webjsui lint` (configured by a `lint` block in `components.json`, see `references/ui-kit.md`), `w-9 h-9` is layout and `rounded-full` is shape in the shadcn category taxonomy, so an app running it sets `no-restyle` to `allow: ["layout", "rounded"]` for this idiom to pass: the plain radius group is granted by name without opening the whole `shape` category, and `border-2` beside a helper still fires.
 
 ```ts
 // components/ui/button.ts  (npx webjsdev ui add button, themed to your app)

package/templates/.agents/skills/webjs/references/testing.md

@@ -63,6 +63,8 @@ WEBJS_E2E=1 npm run test  # adds the e2e layer
 
 `npm run test` dispatches on the runtime (`node --test` on Node, `bun test` on Bun). The scaffold's `web-test-runner.config.js` globs `test/**/browser/**/*.test.js` and is already wired, so you do not set it up.
 
+An app with no browser tests yet (for example right after `npm run gallery:clear`) is not a failure: `webjs test --browser` sees that no file matches the config's `files` globs, prints `no browser tests yet`, and exits 0, the same way the server layer passes with zero files. So `npm run ci` stays green until you write the first browser test, and from then on the browser layer runs as normal.
+
 A scaffolded app has one root `test/` directory shaped the same way (feature first, kind second):
 
 ```
@@ -189,6 +191,17 @@ WEBJS_ELIDE=0 npm run test:e2e
 
 A test that passes under one and fails under the other is a wrong verdict, and `webjs elision` tells you which module and on what evidence. If the component's interactivity is genuinely invisible to static analysis, the fix is `static interactive = true` on it; see `components.md` for what that override does and does not rescue.
 
+## One command for every layer (`webjs ci`)
+
+```sh
+npm run ci                     # the webjs.ci list: check, doctor, typecheck, audit, then every test layer
+npm run ci -- --only Tests     # one step or group by title
+npm run ci -- --fail-fast      # stop at the first failure
+npm run ci -- --json           # one JSON document for an agent loop
+```
+
+The scaffold declares its gate once, in `package.json` under `webjs.ci`, and `npm run ci` runs it with a timed result line per step (the Rails `bin/ci` model). The generated GitHub workflow runs the same list, so a green local run predicts CI. Run it before every push; the pre-commit hook deliberately runs none of it so a commit stays fast. Browser and e2e steps need a Chromium on the machine (`npx playwright install chromium`, plus `puppeteer-core` for the e2e layer), which the workflow installs for itself. The list, the flags, the `--signoff` merge gate, and the JSON shape are in `references/built-ins.md` under "Local CI".
+
 ## Type-checking your tests (`webjs typecheck`)
 
 Your tests are inside the tsconfig `include`, so `npm run typecheck` reads them (#1299). Treat a type error in a test as a failed gate, not a review catch: the checker sees a wrong argument shape or an unannotated parameter in a test the same way it sees one in `app/`.

package/templates/.agents/skills/webjs/references/ui-kit.md

@@ -52,6 +52,31 @@ So the loop is: `add` the component, then query `ui <name>` (MCP) or
   that ships inside the installed `@webjsdev/ui`, with no network. This pins you
   to the installed version; run `npx webjsdev ui diff` to see where your local copies
   drift from the upstream (that command alone compares against the live registry).
+- `npx webjsdev ui lint` is an OPT-IN design-system linter over the app's own
+  source. It reads the Tailwind classes in `html` templates, `cn()` calls and
+  `class=${...}` holes and reports, at the line, a raw palette colour where the
+  theme declares a role token (`no-raw-colors`, with a message naming only the
+  `--color-*` tokens the configured `tailwind.css` actually declares), an
+  arbitrary value such as `p-[13px]` (`no-arbitrary-values`; an arbitrary
+  VARIANT like `[&_svg]:size-4` never fires), and a class composed over a kit
+  helper (`no-restyle`, naming the helper's real variants and sizes read from
+  the app's copied `components/ui/*.ts`). It is off until `components.json`
+  carries a `lint` block, and with no block it reports nothing and exits 0.
+  `components/ui/**` is skipped by default (a copied primitive owns structural
+  values no variant expresses), and `allow` uses shadcn's category taxonomy
+  (`layout`, `color`, `typography`, `spacing`, `shape`, `effects`, `motion`) or
+  a class-group id such as `rounded`. `--json` emits `{ violations, summary }`
+  for an agent loop; `--max-warnings <n>` pins a count.
+
+  ```json
+  "lint": {
+    "rules": {
+      "no-raw-colors": "warn",
+      "no-arbitrary-values": { "severity": "warn", "allow": ["layout"] },
+      "no-restyle": { "severity": "error", "allow": ["layout", "rounded"] }
+    }
+  }
+  ```
 
 ## Inventory (run `npx webjsdev ui list` or the MCP `ui` tool for the authoritative, current set)
 

package/templates/.dockerignore

@@ -18,7 +18,7 @@ build
 out
 .cache
 
-# Local env files. The container gets its env from compose / uncloud, not a
+# Local env files. The container gets its env from compose or the host, not a
 # committed file. Keep the example for reference.
 .env
 !.env.example

package/templates/.github/pull_request_template.md

@@ -4,10 +4,9 @@
 
 ## Test plan
 
-- [ ] Unit tests added/updated (`webjs test` passes)
-- [ ] E2E tests added/updated for user-facing changes (`webjs test --e2e` passes)
-- [ ] `webjs check` passes (no convention violations)
-- [ ] `webjs doctor` passes (project health; it fails on whatever `webjs.doctor.gate` marks `error`, plus the hard `NODE_VERSION` / `TSCONFIG_ERASABLE` checks)
+- [ ] `webjs ci` passes locally (the `webjs.ci` step list in package.json: `webjs check`, `webjs doctor`, `webjs typecheck`, the dependency audit, and the server / browser / e2e test layers; CI runs the same list)
+- [ ] Unit tests added/updated
+- [ ] E2E tests added/updated for user-facing changes (`WEBJS_E2E=1 webjs test`)
 
 ## Definition of done
 

package/templates/.github/workflows/ci.yml

@@ -1,15 +1,25 @@
 name: CI
 
-# The test gate for {{APP_NAME}}. Runs the full test pyramid on every PR
-# into main and on every push to main. This is the gate the local
-# pre-commit hook deliberately leaves out, so `git commit` stays fast and
-# the test gate runs in one authoritative place a local --no-verify cannot
-# skip. Same posture as the webjs framework's own CI.
+# The cloud half of CI for {{APP_NAME}}. The step list itself lives in
+# package.json under "webjs": { "ci": { "steps": [...] } }, and `npm run ci`
+# runs it: on a developer machine before a push, and here on every PR into
+# main and every push to main, so the two can never drift. This job only
+# prepares the runner (Node, dependencies, a browser, the database) and then
+# runs that one command.
 #
-# The four layers run as separate jobs so a failure names the layer that
-# broke. Mark all four as required status checks in the branch-protection
-# rule for main so a PR can only merge when every layer is green. Free on
-# public repos (ubuntu-latest has unlimited Actions minutes).
+# One job on purpose. Each step is still a collapsible log group with its own
+# result line, a failing step is annotated, and the run's step table lands in
+# the job summary, so a failure names the layer that broke. Mark this job as a
+# required status check in the branch-protection rule for main. A team that
+# wants one required check PER LAYER can add a matrix job that runs
+# `npx webjs ci --only "<group title>"` per entry.
+#
+# The local pre-commit hook deliberately runs none of this, so a commit stays
+# fast; `npm run ci` before pushing is the local gate. To hold a merge until a
+# LOCAL run is green, `npm run ci -- --signoff` posts a green commit status
+# through basecamp/gh-signoff, which branch protection can require (`gh signoff
+# install`), the Rails posture. Free on public repos (ubuntu-latest has
+# unlimited Actions minutes).
 
 on:
   pull_request:
@@ -17,40 +27,21 @@ on:
   push:
     branches: [main]
 
+permissions:
+  contents: read
+
 # A newer push to the same branch cancels the older in-flight run.
 concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
-  conventions:
-    name: Conventions (webjs check)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: '24'
-          cache: npm
-      - run: npm ci
-      - run: npm run check
-      # Project health, on top of the correctness checks. WHICH findings are
-      # fatal is your call, declared in package.json under
-      # "webjs": { "doctor": { "gate": { "<CODE>": "off" | "warn" | "error" } } },
-      # so this step and a local `npm run doctor` always agree. The scaffold
-      # starts with UNMARKED_ASSET_LINKS at error (an un-versioned /public url
-      # is a real deploy-staleness bug). Two checks fail with no gate entry at
-      # all, NODE_VERSION and TSCONFIG_ERASABLE, because either would 500 the
-      # app at runtime; everything else stays a warn and cannot fail this job.
-      # Widen or narrow the gate in package.json, not
-      # here. Deliberately not --strict: the git-hook, env-drift, vendor-pin,
-      # and framework-resolve checks are environment-shaped and would fail a
-      # perfectly healthy runner.
-      - run: npm run doctor
-
-  unit:
-    name: Unit + integration (node --test)
+  ci:
+    name: CI (npm run ci)
     runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      DATABASE_URL: file:./ci.db
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6
@@ -58,58 +49,17 @@ jobs:
           node-version: '24'
           cache: npm
       - run: npm ci
-      - name: Set up the database (generate + apply migrations)
-        run: npm run db:generate && npm run db:migrate
-        env:
-          DATABASE_URL: file:./ci.db
-      # --server keeps this job to node:test (the browser layer is its own
-      # job below). Without WEBJS_E2E the e2e folders are skipped too.
-      - run: npm run test:server
-        env:
-          DATABASE_URL: file:./ci.db
-
-  browser:
-    name: Browser (web-test-runner / Playwright)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: '24'
-          cache: npm
-      - run: npm ci
-      - name: Install Playwright Chromium
+      - name: Install Playwright Chromium (browser + e2e layers)
         run: npx playwright install --with-deps chromium
-      - run: npm run test:browser
-
-  e2e:
-    name: E2E (full app boot)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
-        with:
-          node-version: '24'
-          cache: npm
-      - run: npm ci
-      - name: Set up the database (generate + apply migrations)
-        run: npm run db:generate && npm run db:migrate
-        env:
-          DATABASE_URL: file:./ci.db
-      # The scaffold's e2e test (test/hello/e2e/) drives a real browser
-      # via puppeteer-core, which is not a default dependency (the test
-      # skips when it is absent). Install it and Chromium so the e2e
-      # layer actually runs in CI rather than skipping silently.
-      - name: Install puppeteer-core + Chromium
-        run: |
-          npm install --no-save puppeteer-core
-          npx playwright install --with-deps chromium
+      # The scaffold's e2e test (test/hello/e2e/) drives a real browser via
+      # puppeteer-core, which is not a default dependency (the test skips when
+      # it is absent). Install it so the e2e layer runs here rather than
+      # skipping silently.
+      - name: Install puppeteer-core
+        run: npm install --no-save puppeteer-core
       - name: Resolve the Chromium binary path
         run: echo "CHROMIUM_PATH=$(node -e "console.log(require('playwright-core').chromium.executablePath())")" >> "$GITHUB_ENV"
-      # --server with WEBJS_E2E=1 runs node:test including the e2e folders
-      # (the runner gates them on that env var) and skips the browser layer.
-      - name: Run e2e
-        env:
-          WEBJS_E2E: '1'
-          DATABASE_URL: file:./ci.db
-        run: npm run test:server
+      - name: Set up the database (generate + apply migrations)
+        run: npm run db:generate && npm run db:migrate
+      # Everything above prepares the runner. This is the whole gate.
+      - run: npm run ci

package/templates/.hooks/pre-commit

@@ -7,10 +7,11 @@
 #
 # To bypass in emergencies: git commit --no-verify
 #
-# Tests and convention checks run in CI (.github/workflows/ci.yml), not
-# here, so a commit stays fast and the test gate cannot be skipped by a
-# local --no-verify. The CI workflow runs `webjs check` + `webjs test`
-# on every push and pull request.
+# Tests and convention checks do not run here, so a commit stays fast. The
+# step list lives in package.json under "webjs": { "ci" }. Run it locally
+# with `npm run ci` before pushing (the local gate), and the CI workflow
+# (.github/workflows/ci.yml) runs the same list on every push and pull
+# request, where a local --no-verify cannot skip it.
 #
 # Running more than one AI agent on this repo at once? Give each task its own
 # git worktree, not a shared checkout. Two agents in one working directory

package/templates/Dockerfile

@@ -1,7 +1,7 @@
 # Production image for the {{APP_NAME}} webjs app.
 #
-# Works with a plain `docker build` / `docker compose up`, and is the same
-# artifact the webdeploy hosting tool (ubicloud + uncloud) builds and ships.
+# Works with a plain `docker build` / `docker compose up`, and with any host
+# that builds from a Dockerfile.
 #
 # webjs serves .ts directly by stripping types at the runtime layer, so there is
 # NO JavaScript build step (webjs is buildless end to end; there is no bundler or
@@ -41,7 +41,7 @@ COPY . .
 # step runs `webjs db migrate`). See the CMD note below.
 
 ENV NODE_ENV=production
-# webjs start reads $PORT (default 8080). compose / uncloud / Railway set it.
+# webjs start reads $PORT (default 8080). compose and most hosts set it.
 ENV PORT=8080
 EXPOSE 8080
 

package/templates/compose.yaml

@@ -2,9 +2,9 @@
 #
 #   docker compose up --build   →   http://localhost:8080
 #
-# In production the webdeploy tool (ubicloud + uncloud) provisions a managed
-# Postgres and injects DATABASE_URL + AUTH_SECRET for you. Locally this uses
-# the scaffold's SQLite file on a named volume so data survives `compose down`.
+# In production your host provides DATABASE_URL + AUTH_SECRET. Locally this
+# uses the scaffold's SQLite file on a named volume so data survives
+# `compose down`.
 services:
   app:
     build: .

package/templates/partials/agents-playbook-api.md

@@ -44,15 +44,20 @@ cross-origin access use the `cors()` middleware from `@webjsdev/server`; with
 
 ### 5. Verify before you call it done
 
-Run each of these and fix what it reports, in order:
+Run `npm run ci` and fix what it reports. It is one command for every gate,
+the step list declared in `package.json` under `webjs.ci`, with a result line
+per step:
 
-- `npm run check` (correctness: no browser-import or boundary violation).
-- `npm run doctor` (project health; CI runs it too). It fails on whatever
-  `package.json` `webjs.doctor.gate` marks `error`, plus the two hard toolchain
-  checks that are fatal with no gate entry, `NODE_VERSION` and
-  `TSCONFIG_ERASABLE`.
-- `npm run typecheck` (zero type errors).
-- `npm test` (unit tests for the endpoints and modules you built).
+- `webjs check` (correctness: no browser-import or boundary violation).
+- `webjs doctor` (project health). It fails on whatever `package.json`
+  `webjs.doctor.gate` marks `error`, plus the two hard toolchain checks that
+  are fatal with no gate entry, `NODE_VERSION` and `TSCONFIG_ERASABLE`.
+- `webjs typecheck` (zero type errors).
+- A dependency audit.
+- The test layers for the endpoints and modules you built.
+
+The GitHub workflow runs the same list, so a green local run predicts CI.
+While iterating, `npm run ci -- --only Tests` runs one layer.
 
 Then boot `npm run dev` and probe each endpoint for the expected status and JSON
 shape.
@@ -66,6 +71,7 @@ npm run dev             # dev server at http://localhost:8080
 npm run start           # production server
 npm test                # unit + browser tests
 npm run typecheck
+npm run ci              # every gate, one command (the webjs.ci steps in package.json)
 npm run check           # correctness checks
 npm run doctor          # project health (severity per check: webjs.doctor.gate)
 npm run db:generate && npm run db:migrate

package/templates/partials/agents-playbook-fullstack.md

@@ -95,16 +95,21 @@ accessor). Use the shorthand for primitives
 
 ### 7. Verify before you call it done
 
-Run each of these and fix what it reports, in order:
-
-- `npm run check` (correctness: no browser-import or boundary violation).
-- `npm run doctor` (project health; CI runs it too). It fails on whatever
-  `package.json` `webjs.doctor.gate` marks `error`, plus the two hard toolchain
-  checks that are fatal with no gate entry, `NODE_VERSION` and
-  `TSCONFIG_ERASABLE`.
-- `npm run typecheck` (zero type errors).
-- `npm test` (unit and browser tests for the features you built).
-- `npm run css:build` (compile Tailwind).
+Run `npm run ci` and fix what it reports. It is one command for every gate,
+the step list declared in `package.json` under `webjs.ci`, with a result line
+per step:
+
+- `webjs check` (correctness: no browser-import or boundary violation).
+- `webjs doctor` (project health). It fails on whatever `package.json`
+  `webjs.doctor.gate` marks `error`, plus the two hard toolchain checks that
+  are fatal with no gate entry, `NODE_VERSION` and `TSCONFIG_ERASABLE`.
+- `webjs typecheck` (zero type errors).
+- A dependency audit.
+- The server, browser, and e2e test layers for the features you built.
+
+The GitHub workflow runs the same list, so a green local run predicts CI.
+While iterating, `npm run ci -- --only Tests` runs one layer. Then
+`npm run css:build` (compile Tailwind).
 
 Then boot `npm run dev`, confirm every page route returns HTTP 200, and open
 every route you changed in a real browser and play through its states: `check`
@@ -121,6 +126,7 @@ npm run start                # production server
 npm test                     # unit + browser tests
 npm run typecheck
 npm run css:build            # compile Tailwind
+npm run ci                   # every gate, one command (the webjs.ci steps in package.json)
 npm run check                # correctness checks
 npm run doctor               # project health (severity per check: webjs.doctor.gate)
 npx webjsdev ui add <name>   # copy a ui primitive into components/ui/