@webjsdev/cli 0.10.0 → 0.10.2

package/bin/webjs.js

@@ -148,17 +148,31 @@ async function main() {
         const { readdir } = await import('node:fs/promises');
         const testFiles = [];
 
-        for (const dir of ['test/server', 'test/unit', 'test']) {
-          const fullDir = join(cwd, dir);
-          if (!existsSync(fullDir)) continue;
-          const files = await readdir(fullDir);
-          for (const f of files) {
-            if (/\.test\.(js|ts|mjs|mts)$/.test(f)) {
-              const full = join(fullDir, f);
+        // Walk test/ recursively so the documented feature-folder layout
+        // (test/<feature>/<name>.test.ts) is discovered, not just files
+        // sitting directly in test/. Two kinds are NOT run here:
+        //   - **/browser/**  → real-browser tests, owned by WTR below.
+        //   - **/e2e/**      → full-app boot, opt-in via WEBJS_E2E=1 (the
+        //                      documented "WEBJS_E2E=1 webjs test adds the
+        //                      e2e tests" semantics).
+        const runE2E = !!process.env.WEBJS_E2E;
+        const walk = async (dir, segments) => {
+          let entries;
+          try { entries = await readdir(dir, { withFileTypes: true }); }
+          catch { return; }
+          for (const ent of entries) {
+            if (ent.name === 'node_modules') continue;
+            const full = join(dir, ent.name);
+            if (ent.isDirectory()) {
+              if (ent.name === 'browser') continue;
+              if (ent.name === 'e2e' && !runE2E) continue;
+              await walk(full, [...segments, ent.name]);
+            } else if (/\.test\.(js|ts|mjs|mts)$/.test(ent.name)) {
               if (!testFiles.includes(full)) testFiles.push(full);
             }
           }
-        }
+        };
+        await walk(join(cwd, 'test'), []);
 
         if (testFiles.length > 0) {
           console.log(`webjs test: running ${testFiles.length} server test file(s)…\n`);

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',
@@ -391,7 +392,16 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     '.cursorrules',
     '.github/copilot-instructions.md',
     '.github/pull_request_template.md',
+    // CI is the test gate (the pre-commit hook only blocks main). Runs
+    // webjs check + the unit / browser / e2e layers on every PR and push
+    // to main, mirroring the webjs framework's own CI.
+    '.github/workflows/ci.yml',
     '.editorconfig',
+    // Production / deploy scaffolding. `docker compose up --build` runs
+    // the app locally with the same Dockerfile production builds from.
+    'Dockerfile',
+    'compose.yaml',
+    '.dockerignore',
   ];
   for (const f of templateFiles) {
     const src = join(TEMPLATES, f);
@@ -405,7 +415,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);
   }

package/package.json

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

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": [

package/templates/.dockerignore

@@ -0,0 +1,43 @@
+.git
+.github
+node_modules
+**/node_modules
+
+# `.webjs/` is ignored EXCEPT for `.webjs/vendor/`, which holds the committed
+# importmap manifest (and optionally downloaded bundle bytes) the server needs
+# at boot without reaching api.jspm.io. DO NOT collapse to `**/.webjs`: parent
+# exclusion blocks child negations and the vendor files would never ship.
+.webjs/*
+!.webjs/vendor/
+!.webjs/vendor/**
+
+dist
+build
+out
+.cache
+
+# Local env files. The container gets its env from compose / uncloud, not a
+# committed file. Keep the example for reference.
+.env
+!.env.example
+
+# Prisma local SQLite. Schema + migrations ship; the runtime volume owns the db.
+dev.db
+dev.db-journal
+prisma/dev.db
+prisma/dev.db-journal
+
+# logs
+*.log
+npm-debug.log*
+
+# editors / OS
+.vscode
+.idea
+.DS_Store
+Thumbs.db
+
+# tests aren't needed in the production image
+coverage/
+test/
+**/test/

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

@@ -0,0 +1,105 @@
+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 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).
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+# 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
+
+  unit:
+    name: Unit + integration (node --test)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: npm
+      - run: npm ci
+      - run: npx prisma generate
+      - name: Apply migrations to the test database
+        run: npx prisma migrate deploy
+        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
+      - run: npx prisma generate
+      - name: Install Playwright Chromium
+        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
+      - run: npx prisma generate
+      - name: Apply migrations to the test database
+        run: npx prisma migrate deploy
+        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
+      - 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

package/templates/.hooks/pre-commit

@@ -1,11 +1,16 @@
 #!/bin/bash
 #
-# pre-commit hook - blocks commits on main/master.
+# pre-commit hook. Blocks commits on main/master.
 #
 # No AI agent, no editor, no human can commit to main directly.
 # Create a feature branch first. This is git-level enforcement.
 #
 # 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.
 
 BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null)
 
@@ -21,28 +26,4 @@ if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
   exit 1
 fi
 
-# webjs test + webjs check on every commit. Tool-agnostic enforcement:
-# fires regardless of which agent (Claude, Cursor, Antigravity, Copilot,
-# human) is making the commit. Skipped if the CLI is not yet installed
-# (fresh clone before npm install).
-if command -v webjs >/dev/null 2>&1 || [ -x "node_modules/.bin/webjs" ]; then
-  echo "Running webjs test..."
-  if ! npx --no-install webjs test; then
-    echo ""
-    echo "ERROR: webjs test failed. Fix tests before committing."
-    echo "To bypass (emergencies only): git commit --no-verify"
-    echo ""
-    exit 1
-  fi
-
-  echo "Running webjs check..."
-  if ! npx --no-install webjs check; then
-    echo ""
-    echo "ERROR: webjs check failed. Fix convention violations before committing."
-    echo "To bypass (emergencies only): git commit --no-verify"
-    echo ""
-    exit 1
-  fi
-fi
-
 exit 0

package/templates/AGENTS.md

@@ -301,6 +301,16 @@ In Docker / Railway, prefer `npm start` (or `node node_modules/.bin/npm
 start`) as the CMD over `node ... webjs.js start ...`. The npm form
 fires `prestart`; the direct binary form skips it.
 
+**Containerized deploy ships with the scaffold.** `Dockerfile`,
+`compose.yaml`, and `.dockerignore` are scaffolded at the app root. The
+Dockerfile pins `node:24-alpine` (the same Node major CI uses), installs
+deps, runs `prisma generate`, and starts via `npm start` so `prestart`
+applies migrations. Run it locally with `docker compose up --build` (the
+app comes up on http://localhost:8080 against a SQLite file on a named
+volume). For production, point `DATABASE_URL` at managed Postgres and set
+`AUTH_SECRET`. The `.dockerignore` keeps the `.webjs/vendor/` importmap in
+the image while excluding `node_modules`, tests, and local state.
+
 **Health and readiness probes.** Every webjs server answers two endpoints:
 `/__webjs/health` (liveness, 200 once the process is listening) and
 `/__webjs/ready` (readiness, 503 until the instance is fully warm, then 200).
@@ -883,8 +893,17 @@ composition, so a nested shell ends up dropped by the HTML parser.
 ## Workflow expectations for AI agents
 
 1. Branch before editing. Never push to `main` directly.
-2. Every code change comes with: unit test(s), AGENTS.md / docs updates if
-   the feature surface changed, `webjs check` passing.
+2. Every code change comes with a test, AGENTS.md / docs updates if the
+   feature surface changed, `webjs check` passing. A unit test is not
+   always enough: a component, hydration, the client router, or a server
+   action called from the client needs a browser test
+   (`webjs test --browser`) asserting the behaviour in a real browser. A
+   commit that stages app code (`app/`, `modules/`, `components/`, `lib/`)
+   with no test is blocked for Claude Code by
+   `.claude/hooks/require-tests-with-src.sh`. The test suite itself runs in
+   CI (`.github/workflows/ci.yml`), not in the pre-commit hook, so `git
+   commit` stays fast and the gate cannot be skipped with a local
+   `--no-verify`.
 3. Commit and push **per logical unit**, not at the end. A logical unit is one
    feature, one fix, one rename, one doc rewrite. If you have 5+ unstaged files
    spanning different concerns, commit the current group before continuing.
@@ -900,9 +919,10 @@ composition, so a nested shell ends up dropped by the HTML parser.
    | Antigravity (Google) | text rule only (post-write hooks not yet exposed) | `.agents/rules/workflow.md` |
    | GitHub Copilot | text rule only (no hooks API) | `.github/copilot-instructions.md` |
 
-   Tool-agnostic fallback: `.hooks/pre-commit` runs `webjs test` + `webjs check`
-   on every commit, regardless of which agent (or human) made it. No AI
-   attribution trailers in commit messages.
+   The `.hooks/pre-commit` hook blocks commits to main and nothing else;
+   `webjs test` + `webjs check` run in CI (`.github/workflows/ci.yml`) on
+   every PR and push to main, regardless of which agent (or human) made
+   the commit. No AI attribution trailers in commit messages.
 4. Run the **pre-merge self-review loop** before signaling the PR is
    ready. After committing the work, trigger a fresh-context review
    pass (a new chat / composer tab / subagent / Cascade thread

package/templates/CONVENTIONS.md

@@ -451,6 +451,15 @@ test/
 - `webjs test --browser` (or `npx wtr`) runs the browser tests.
 - `WEBJS_E2E=1 webjs test` adds the e2e tests.
 
+**Every change ships with a test.** For Claude Code, a commit that
+stages app code (`app/`, `modules/`, `components/`, `lib/`) without
+staging a test is blocked by `.claude/hooks/require-tests-with-src.sh`.
+A unit test alone is not enough for interactive or component code: add
+the browser test that asserts the rendered/hydrated behaviour. The test
+suite itself runs in CI (`.github/workflows/ci.yml`) on every PR and
+push to main, not in the local pre-commit hook, so `git commit` stays
+fast and the gate cannot be skipped with a local `--no-verify`.
+
 ### Choosing a feature folder
 
 Use the same name as the matching module folder when one exists:
@@ -994,10 +1003,19 @@ This project enforces a git workflow via agent-specific config files
   Other agents enforce this via `.cursorrules`, `.agents/rules/workflow.md`,
   `.github/copilot-instructions.md`.
 
-**Pre-commit checks:**
-- `webjs test` must pass
-- `webjs check` must pass
-- No unrelated files in the commit
+**Pre-commit hook (`.hooks/pre-commit`):**
+- Blocks commits to `main` / `master`. Nothing else runs locally, so
+  `git commit` stays fast. Keeping commits to one logical unit (no
+  unrelated files) is your discipline plus the `nudge-uncommitted`
+  hooks, not something this hook enforces.
+
+**CI gate (`.github/workflows/ci.yml`), on every PR and push to main:**
+- `webjs check` (conventions) must pass
+- `webjs test` (unit + integration), the browser layer, and the e2e
+  layer must pass
+- Mark these as required status checks in the branch-protection rule for
+  main so a PR can only merge when the gate is green. The gate lives in
+  CI, where a local `--no-verify` cannot skip it.
 
 ---
 

package/templates/Dockerfile

@@ -0,0 +1,38 @@
+# 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.
+#
+# webjs serves .ts directly via Node's built-in type-stripping, so there is
+# NO JavaScript build step. **Node 24+ is REQUIRED**: on older Node the runtime
+# 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).
+FROM node:24-alpine
+
+# openssl + ca-certificates are required by Prisma's query engine at runtime.
+RUN apk add --no-cache openssl ca-certificates
+
+WORKDIR /app
+
+# Install deps first so this layer is cached unless the manifests change.
+# package-lock.json is optional (it's absent when the app was scaffolded with
+# --no-install); the glob keeps the COPY working with or without it.
+COPY package.json package-lock.json* ./
+RUN npm install --no-audit --no-fund
+
+# App source. node_modules and local state are excluded via .dockerignore.
+COPY . .
+
+# Generate the Prisma client at build time (every scaffold ships a
+# prisma/schema.prisma). If you remove Prisma from the app, delete this line.
+RUN npx prisma generate
+
+ENV NODE_ENV=production
+# webjs start reads $PORT (default 8080). compose / uncloud / Railway set it.
+ENV PORT=8080
+EXPOSE 8080
+
+# `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

@@ -0,0 +1,28 @@
+# {{APP_NAME}} local parity with production, using the same Dockerfile, one service.
+#
+#   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`.
+services:
+  app:
+    build: .
+    ports:
+      - "8080:8080"
+    environment:
+      PORT: 8080
+      # SQLite on a volume for local dev. For production, point DATABASE_URL at
+      # your managed Postgres and switch prisma/schema.prisma's provider to
+      # "postgresql".
+      DATABASE_URL: file:/data/dev.db
+      # Generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+      AUTH_SECRET: ${AUTH_SECRET:-change-me-please-at-least-32-characters!}
+      # Uncomment to back cache / sessions / rate-limiting / pub-sub with Redis
+      # instead of the in-memory defaults.
+      # REDIS_URL: redis://redis:6379
+    volumes:
+      - app-data:/data
+
+volumes:
+  app-data: