@webjsdev/cli 0.10.1 → 0.10.3

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

@@ -392,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);

package/package.json

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

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,53 +26,4 @@ if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
   exit 1
 fi
 
-# Require a test to accompany app-code changes. Tool-agnostic floor: a
-# commit that stages app code (app/, modules/, components/, lib/) with no
-# test (test/** or *.test.* / *.spec.*) is blocked. The full suite below
-# proves tests PASS; this proves a test was WRITTEN. Bypass for a genuine
-# non-code commit with WEBJS_NO_TEST_GATE=1, or --no-verify in emergencies.
-if [ "${WEBJS_NO_TEST_GATE:-}" != "1" ]; then
-  STAGED=$(git diff --cached --name-only 2>/dev/null)
-  APP_CODE=$(printf '%s\n' "$STAGED" | grep -E '^(app|modules|components|lib)/.*\.([mc]?[jt]sx?)$' || true)
-  if [ -n "$APP_CODE" ]; then
-    TESTS=$(printf '%s\n' "$STAGED" | grep -E '(^|/)test/|\.test\.[mc]?[jt]sx?$|\.spec\.[mc]?[jt]sx?$' || true)
-    if [ -z "$TESTS" ]; then
-      echo ""
-      echo "ERROR: app code changed but no test is staged."
-      echo "Every change ships with a test. Add or update the test that"
-      echo "proves the new behaviour (a browser/e2e test for interactive"
-      echo "or component code), then git add it."
-      echo ""
-      echo "Genuine non-code commit? WEBJS_NO_TEST_GATE=1 git commit ..."
-      echo "Emergency bypass: git commit --no-verify"
-      echo ""
-      exit 1
-    fi
-  fi
-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).
@@ -308,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:
 
@@ -889,9 +904,11 @@ composition, so a nested shell ends up dropped by the HTML parser.
    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 by `.claude/hooks/require-tests-with-src.sh`
-   and the `.hooks/pre-commit` floor (bypass a genuine non-code commit
-   with `WEBJS_NO_TEST_GATE=1`).
+   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.
@@ -907,9 +924,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,14 +451,14 @@ 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, enforced at commit time.** A commit
-that stages app code (`app/`, `modules/`, `components/`, `lib/`) without
-staging a test is blocked by `.claude/hooks/require-tests-with-src.sh`
-(Claude Code) and the universal `.hooks/pre-commit` (any agent or human).
+**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. Bypass a
-genuine non-code commit with `WEBJS_NO_TEST_GATE=1`, or `--no-verify` in
-an emergency.
+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
 
@@ -1003,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,49 @@
+# 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
+
+# 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

@@ -0,0 +1,36 @@
+# {{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
+    # 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: