@webjsdev/cli 0.10.57 → 0.10.58

package/README.md

@@ -48,8 +48,12 @@ webjs start                    # production server (no build step, serves source
 webjs check                    # validate source-code conventions (CI gate)
 webjs doctor                   # verify the project/toolchain setup (per-check severity via webjs.doctor.gate, so CI can gate a subset)
 webjs test                     # run server + browser tests
+webjs ci                       # local CI: run the webjs.ci step list in package.json (check, doctor,
+                               # typecheck, audit, every test layer), one result line per step;
+                               # --only <title>, --fail-fast, --json, --signoff (gh signoff after a green run)
+webjs create <name> --skip-ci  # omit the GitHub workflow (the local ci list always ships)
 webjs vendor pin [--download]  # pin client deps to a committable importmap (offline/reproducible)
-webjs db <generate|migrate|push|studio|seed>   # drizzle-kit passthrough (+ seed)
+webjs db <generate|migrate|push|studio|seed>   # drizzle-kit passthrough (+ seed) by default; a package.json webjs.db block maps any verb to your own ORM's command
 
 webjs ui init                  # initialise @webjsdev/ui in this project
 webjs ui add <names...>        # copy components from the registry (https://webjs.dev/ui/registry/<name>.json)
@@ -70,6 +74,7 @@ The scaffold seeds opinionated defaults so AI agents produce consistent code:
 
 - `AGENTS.md` + `CONVENTIONS.md` + `.agents/skills/webjs/` (single cross-agent source of truth)
 - `.agents/rules/workflow.md` & `.claude/` protective hooks
+- A `webjs.ci` step list in `package.json` (`npm run ci`, local CI) and a one-job GitHub workflow that runs the same list
 - `test/<feature>/` (with optional `browser/` / `e2e/` subfolders per kind) with example tests
 - Tailwind CSS via CLI (no browser runtime at build time)
 - TypeScript, `.editorconfig`, `.gitignore`

package/bin/webjs.js

@@ -90,6 +90,11 @@ const USAGE = `webjs commands:
   webjs start [--port 8080]                       Start production server (serves source directly, no build step)
   webjs test  [--server|--browser]                 Run server + browser tests
   webjs check [--json]                            Run correctness checks (--json emits structured violations)
+  webjs ci [-f|--fail-fast] [--only <title>] [--json] [--signoff]
+                                                  Run the local CI steps declared under "webjs": { "ci": { "steps": [...] } }
+                                                  in package.json (timed, one result line per step, parallel groups replayed whole,
+                                                  exit 1 on any failure). The same list a cloud pipeline runs via "npm run ci".
+                                                  --only runs one step or group by title; --signoff runs "gh signoff" after a green run
   webjs routes [--json|--table] [--no-headers]    Print the route table (path / owner file / methods). Default tree; --json matches the MCP list_routes shape; --no-headers drops the --table header
   webjs elision [--json] [--verify]               Report which component modules are elided and why each shipped one ships;
                                                   --verify diffs SSR output with elision on vs off (exits non-zero on a divergence)
@@ -100,7 +105,7 @@ const USAGE = `webjs commands:
                                                   in package.json, so CI gates on a chosen subset without every warning becoming fatal
   webjs types                                     Generate .webjs/routes.d.ts (typed Route union + per-route params)
   webjs typecheck [tsc args...]                   Type-check the app with the project's tsc --noEmit (non-zero on errors)
-  webjs create <name> [--template full-stack|api] [--db sqlite|postgres] [--runtime node|bun] [--no-install]  Scaffold a new webjs app
+  webjs create <name> [--template full-stack|api] [--db sqlite|postgres] [--runtime node|bun] [--no-install] [--skip-ci]  Scaffold a new webjs app
                                                   <name> must be a valid package name (letters, digits, - . _, starts with a letter or digit)
                                                   (only 2 templates exist. default: full-stack, Drizzle, --db sqlite, --runtime node)
                                                   --runtime bun emits a Bun-flavored app (bun.lock, bun Dockerfile/CI, bun docs);
@@ -112,6 +117,9 @@ const USAGE = `webjs commands:
   webjs db push                                   Push the schema straight to the dev DB (drizzle-kit push)
   webjs db studio                                 Open the database browser (drizzle-kit studio)
   webjs db seed                                   Run the app's db/seed.server.ts
+  webjs db <verb>                                 Any verb "webjs": { "db": { "<verb>": "<command>" } } maps in
+                                                  package.json runs that command instead (bring your own ORM);
+                                                  an unmapped verb keeps the drizzle-kit default above
   webjs ui <subcmd>                               AI-first component library CLI
                                                   (init / add / list / view / diff / info)
                                                   Requires @webjsdev/ui installed in the project
@@ -171,6 +179,25 @@ const HELP = {
     ],
     examples: ['webjs check', 'webjs check --json', 'webjs check --rules'],
   },
+  ci: {
+    usage: 'webjs ci [-f|--fail-fast] [--only <title>]... [--json] [--signoff]',
+    summary:
+      'Run the local CI steps declared in package.json under "webjs": { "ci": { "steps": [...] } }: ' +
+      'each step is timed and reported, a parallel group replays each step\'s output whole, and the exit is 1 on any failure. ' +
+      'A cloud pipeline runs the same list through `npm run ci`, so the two cannot drift.',
+    options: [
+      { flag: '-f, --fail-fast', description: 'Stop after the first failing step instead of running every step and listing every failure.' },
+      { flag: '--only <title>', description: 'Run only the step or group with this title (repeatable, case-insensitive; a matched group runs whole).' },
+      { flag: '--json', description: 'Emit one JSON document on stdout ({ ok, seconds, steps[] }, failed steps carry their output); the human output goes to stderr.' },
+      { flag: '--signoff', description: 'After a green run, run `gh signoff` (basecamp/gh-signoff) to post a green commit status; a red run prints the do-not-merge heading instead.' },
+    ],
+    notesTitle: 'Environment:',
+    notes: [
+      'Every step runs with CI=true and node_modules/.bin on PATH, plus the step\'s own `env`.',
+      'Under GitHub Actions each step is a log group and a failure is annotated; a $GITHUB_STEP_SUMMARY table is appended.',
+    ],
+    examples: ['webjs ci', 'webjs ci --fail-fast', 'webjs ci --only Tests', 'webjs ci --json', 'webjs ci --signoff'],
+  },
   routes: {
     usage: 'webjs routes [--json | --table] [--no-headers]',
     summary: 'Print the route table: each page/route path, its owner file, and (for route handlers) its HTTP methods.',
@@ -228,7 +255,7 @@ const HELP = {
     examples: ['webjs typecheck', 'webjs typecheck --watch'],
   },
   create: {
-    usage: 'webjs create <name> [--template full-stack|api] [--db sqlite|postgres] [--runtime node|bun] [--no-install]',
+    usage: 'webjs create <name> [--template full-stack|api] [--db sqlite|postgres] [--runtime node|bun] [--no-install] [--skip-ci]',
     summary: 'Scaffold a new app. Defaults: full-stack template, Drizzle + SQLite, Node runtime.',
     options: [
       // Kept to one terminal line like every other row: printHelp does not
@@ -241,6 +268,7 @@ const HELP = {
       { flag: '--db <d>', description: 'sqlite (default) or postgres.' },
       { flag: '--runtime <r>', description: 'node (default) or bun.' },
       { flag: '--no-install', description: 'Skip the package-manager install step.' },
+      { flag: '--skip-ci', description: 'Omit the GitHub workflow (.github/workflows/ci.yml); the local `npm run ci` list is always emitted.' },
     ],
     examples: [
       'webjs create my-app',
@@ -250,12 +278,19 @@ const HELP = {
     ],
   },
   db: {
-    usage: 'webjs db <generate|migrate|push|studio|seed>',
-    summary: 'Database tasks (wraps drizzle-kit); seed runs db/seed.server.ts.',
+    usage: 'webjs db <generate|migrate|push|studio|seed|verb> [args...]',
+    summary: 'Database tasks (wraps drizzle-kit by default); seed runs db/seed.server.ts.',
+    notes: [
+      'A "webjs": { "db": { "<verb>": "<command>" } } block in package.json maps a verb to',
+      'a shell command (run with node_modules/.bin on PATH, extra args appended), so',
+      'another ORM keeps the same spelling: { "migrate": "prisma migrate deploy" }.',
+      'Any key is a verb ("reset" adds `webjs db reset`); an unmapped one keeps its',
+      'drizzle-kit / seed default, so an app with no block is unchanged.',
+    ],
     examples: ['webjs db generate', 'webjs db migrate', 'webjs db studio', 'webjs db seed'],
   },
   ui: {
-    usage: 'webjs ui <init|add|list|view|diff|info> [names...]',
+    usage: 'webjs ui <init|add|list|view|diff|info|lint> [names...]',
     summary: 'AI-first component library CLI. Requires @webjsdev/ui installed in the project.',
     examples: ['webjs ui init', 'webjs ui add button card', 'webjs ui list'],
   },
@@ -516,6 +551,31 @@ async function main() {
     case 'db': {
       const sub = rest[0];
       const args = rest.slice(1);
+      // A verb the app's `webjs.db` block maps (#1468) runs that command
+      // through the shell, the way a `before` step does (node_modules/.bin on
+      // PATH, so a bare `prisma migrate deploy` resolves), with the extra args
+      // appended. This is what makes Drizzle a default rather than lock-in:
+      // `webjs db migrate` stays the one spelling the scaffolded start.before,
+      // the Dockerfile, and the deploy docs use, whatever ORM is behind it.
+      // Checked FIRST so a mapped `seed` overrides the seed-file runner too.
+      if (!sub) {
+        console.error('webjs db: missing subcommand.\n' + USAGE);
+        process.exit(1);
+      }
+      const { readDbCommands } = await import('../lib/app-tasks.js');
+      const dbCommands = readDbCommands(process.cwd());
+      // Own-property lookup: the map is a plain object, so a bare index would
+      // answer `webjs db constructor` with an inherited function.
+      const mapped = Object.hasOwn(dbCommands, sub) ? dbCommands[sub] : undefined;
+      if (mapped) {
+        const { runBeforeSteps, shellQuote } = await import('../lib/run-tasks.js');
+        // Each arg is quoted so it reaches the ORM as one word, unexpanded,
+        // the way the drizzle-kit default's real argv already does.
+        const full = [mapped, ...args.map(shellQuote)].join(' ');
+        console.log(`webjs db ${sub}: running \`${full}\` (from package.json webjs.db)`);
+        const r = await runBeforeSteps([full], process.cwd());
+        process.exit(r.ok ? 0 : r.code);
+      }
       // `webjs db seed` runs the app's own seed script directly (not a
       // drizzle-kit command); Drizzle has no codegen, so there is no
       // `generate`-the-client step, only schema-to-SQL `generate`.
@@ -535,8 +595,14 @@ async function main() {
       // schema sync), studio. All wrap drizzle-kit; the verbose name stays
       // hidden behind `webjs db`.
       const map = { generate: ['generate'], migrate: ['migrate'], push: ['push'], studio: ['studio'] };
-      const kitArgs = map[sub];
-      if (!kitArgs) { console.error('Unknown db subcommand.\n' + USAGE); process.exit(1); }
+      const kitArgs = Object.hasOwn(map, sub) ? map[sub] : undefined;
+      if (!kitArgs) {
+        console.error(
+          `Unknown db subcommand "${sub}". Map it in package.json to add it: ` +
+          `"webjs": { "db": { "${sub}": "<command>" } }\n` + USAGE,
+        );
+        process.exit(1);
+      }
       // Resolve the app's own drizzle-kit bin and spawn it with the CURRENT
       // runtime (process.execPath). This drops the hard `npx` dependency (#570):
       // `npx` is absent in a pure oven/bun image, which broke `webjs db migrate`
@@ -548,7 +614,9 @@ async function main() {
       } catch {
         console.error(
           'webjs db: drizzle-kit is not installed in this project.\n' +
-          'Install it with `npm install -D drizzle-kit`, then re-run `webjs db ' + sub + '`.',
+          'Install it with `npm install -D drizzle-kit`, then re-run `webjs db ' + sub + '`.\n' +
+          'Using another ORM? Map the verb in package.json and the same command runs it:\n' +
+          '  "webjs": { "db": { "' + sub + '": "<your ORM\'s ' + sub + ' command>" } }',
         );
         process.exit(1);
       }
@@ -707,6 +775,146 @@ async function main() {
       console.log('\nwebjs test: done ✓');
       break;
     }
+    case 'ci': {
+      // Local CI (#1471): run the step list `webjs.ci` declares, the Rails
+      // `bin/ci` posture. The predicate is the CONFIG, not an `app/` dir (unlike
+      // `webjs check`), because a workspace root is a legitimate target: this
+      // monorepo declares its own list. Nothing declared is exit 1, not 0, since
+      // "ran zero steps" would read as green.
+      const cwd = process.cwd();
+      const json = rest.includes('--json');
+      const failFast = rest.includes('--fail-fast') || rest.includes('-f');
+      const signoff = rest.includes('--signoff');
+      const only = [];
+      let onlyMissing = false;
+      for (let i = 0; i < rest.length; i++) {
+        if (rest[i] !== '--only') continue;
+        const value = rest[i + 1];
+        // A bare `--only` (or one followed by another flag) must NOT fall
+        // through to the whole list: that inverts the flag. Refuse it below.
+        if (value === undefined || value.startsWith('--')) onlyMissing = true;
+        else only.push(rest[++i]);
+      }
+      const { readCiConfig, selectSteps, noCiConfigMessage } = await import('../lib/ci-config.js');
+      const { runCi, formatSummary, stepSummaryMarkdown, colorize } = await import('../lib/ci-runner.js');
+      // Under --json stdout carries exactly one document, so the human output
+      // moves to stderr; every step is captured so its output can ride the
+      // document (failed steps only) instead of the terminal.
+      const out = json ? (s) => { process.stderr.write(s); } : (s) => { process.stdout.write(s); };
+      const isTTY = !json && !!process.stdout.isTTY;
+      // Colour on a TTY unless NO_COLOR is set; the runner passes the same
+      // decision down as FORCE_COLOR for captured children.
+      const color = isTTY && !process.env.NO_COLOR;
+      const refuse = (message, code, extra) => {
+        if (json) console.log(JSON.stringify({ error: { code, message, cwd, ...extra } }));
+        else console.error(message);
+        process.exitCode = 1;
+      };
+      if (onlyMissing) {
+        refuse('webjs ci: --only needs a step or group title (webjs ci --only "Tests")', 'INVALID_ONLY', {});
+        break;
+      }
+
+      const cfg = readCiConfig(cwd);
+      if (!cfg.declared) {
+        const { workspaceApps } = await import('../lib/check-target.js');
+        const members = (await workspaceApps(cwd)).filter((app) => readCiConfig(join(cwd, app)).declared);
+        refuse(noCiConfigMessage(cwd, members), 'NO_CI_CONFIG', { apps: members });
+        break;
+      }
+      if (cfg.problems.length > 0) {
+        refuse(
+          `webjs ci: package.json has ${cfg.problems.length} problem(s) in the "webjs": { "ci" } block, so nothing ran:\n` +
+            cfg.problems.map((p) => `  - ${p}`).join('\n'),
+          'INVALID_CI_CONFIG',
+          { problems: cfg.problems },
+        );
+        break;
+      }
+      const selected = selectSteps(cfg.steps, only);
+      if (selected.problems.length > 0) {
+        refuse(`webjs ci: ${selected.problems.join('; ')}`, 'UNKNOWN_ONLY', { problems: selected.problems });
+        break;
+      }
+
+      // `.env` first, like dev / start (#447), so a local `webjs db migrate`
+      // step reads DATABASE_URL from it. A real env var still wins (loadEnvFile
+      // never overrides), so a CI runner's explicit env is untouched.
+      loadAppEnv(cwd);
+      const title = 'Continuous Integration';
+      out(`${colorize(title, 'banner', color)}\n${colorize('Running the steps declared in package.json under webjs.ci', 'subtitle', color)}\n`);
+      const run = runCi(selected.steps, cwd, {
+        write: out,
+        isTTY,
+        color,
+        failFast,
+        captureAll: json,
+        actions: !!process.env.GITHUB_ACTIONS,
+      });
+      // The first signal winds the run down (children killed, results kept).
+      // A SECOND one exits outright, the way Rails' bin/ci lets a repeated
+      // interrupt through: a captured child that ignores SIGTERM (a hung
+      // browser under web-test-runner) would otherwise leave no way out.
+      let interrupting = false;
+      const onSignal = () => {
+        if (interrupting) process.exit(130);
+        interrupting = true;
+        run.interrupt();
+      };
+      process.on('SIGINT', onSignal);
+      process.on('SIGTERM', onSignal);
+      const result = await run.done;
+      process.off('SIGINT', onSignal);
+      process.off('SIGTERM', onSignal);
+      out(formatSummary(result, title, color));
+
+      if (process.env.GITHUB_STEP_SUMMARY) {
+        const { appendFileSync } = await import('node:fs');
+        try { appendFileSync(process.env.GITHUB_STEP_SUMMARY, stepSummaryMarkdown(result)); } catch {}
+      }
+
+      // The Rails signoff step, opt-in. A green run posts a green commit status
+      // (`gh signoff`, which branch protection can require); a red run says so
+      // and posts nothing. It goes through the same runner so it reads as one
+      // more step, and a missing `gh` is a failed step, never a silent skip.
+      let signoffOk = true;
+      if (signoff) {
+        if (result.ok) {
+          const so = runCi(
+            [{ kind: 'step', title: 'Signoff: All systems go. Ready for merge and deploy.', run: 'gh signoff', env: {} }],
+            cwd,
+            { write: out, isTTY, color, captureAll: json },
+          );
+          signoffOk = (await so.done).ok;
+        } else {
+          out(`\n\n${colorize('Signoff: CI failed. Do not merge or deploy.', 'error', color)}\n${colorize('Fix the issues and try again.', 'subtitle', color)}\n`);
+        }
+      }
+
+      if (json) {
+        console.log(JSON.stringify({
+          ok: result.ok && signoffOk,
+          seconds: result.seconds,
+          interrupted: result.interrupted,
+          steps: result.steps.map((s) => ({
+            title: s.title,
+            run: s.run,
+            group: s.group,
+            ok: s.ok,
+            code: s.code,
+            signal: s.signal,
+            interrupted: s.interrupted,
+            seconds: s.seconds,
+            ...(s.ok ? {} : { output: s.output ?? '' }),
+          })),
+        }));
+      }
+      // exitCode rather than a process.exit() call, because a run writes far
+      // more than `check` does and exit() truncates pending pipe writes when
+      // stdout is not a TTY.
+      process.exitCode = result.interrupted ? 130 : result.ok && signoffOk ? 0 : 1;
+      break;
+    }
     case 'check': {
       const { checkConventions, RULES } = await import('@webjsdev/server/check');
 
@@ -1301,6 +1509,8 @@ Full docs: https://webjs.dev/docs`);
         process.exit(1);
       }
       const noInstall = rest.includes('--no-install');
+      // --skip-ci omits the GitHub workflow (#1471); the local ci list stays.
+      const skipCi = rest.includes('--skip-ci');
       // --db picks the database dialect: sqlite (default) or postgres.
       const db = flag(rest, '--db', 'sqlite');
       // --runtime picks the target runtime: node (default) or bun. Orthogonal
@@ -1312,7 +1522,7 @@ Full docs: https://webjs.dev/docs`);
         process.exit(1);
       }
       const { scaffoldApp } = await import('../lib/create.js');
-      await scaffoldApp(name, process.cwd(), { template, db, runtime, install: !noInstall });
+      await scaffoldApp(name, process.cwd(), { template, db, runtime, install: !noInstall, skipCi });
       break;
     }
     case 'vendor': {

package/lib/app-tasks.js

@@ -38,16 +38,9 @@ import { join } from 'node:path';
  * @returns {{ dev: { before: string[], parallel: string[] }, start: { before: string[] } }}
  */
 export function readAppTasks(appDir, readFile) {
-  const read = readFile || ((p) => readFileSync(p, 'utf8'));
-  let pkg = {};
-  try {
-    pkg = JSON.parse(read(join(appDir, 'package.json')));
-  } catch {
-    // No package.json, or unparseable: a plain run with no orchestration.
-    return emptyTasks();
-  }
-  const webjs = pkg && typeof pkg === 'object' ? pkg.webjs : null;
-  if (!webjs || typeof webjs !== 'object') return emptyTasks();
+  const webjs = readWebjsBlock(appDir, readFile);
+  // No package.json, unparseable, or no block: a plain run with no orchestration.
+  if (!webjs) return emptyTasks();
 
   /** Keep only non-empty string entries; drop anything else defensively. */
   const cmds = (v) =>
@@ -62,7 +55,74 @@ export function readAppTasks(appDir, readFile) {
   };
 }
 
+/**
+ * The app's `package.json` `"webjs"` block, or `null` when there is no
+ * package.json, it does not parse, or the block is absent / not an object.
+ * Shared by every CLI-side reader here so the file is read one way.
+ *
+ * @param {string} appDir
+ * @param {(p: string) => string} [readFile] injectable reader for tests
+ * @returns {Record<string, unknown> | null}
+ */
+function readWebjsBlock(appDir, readFile) {
+  const read = readFile || ((p) => readFileSync(p, 'utf8'));
+  let pkg;
+  try {
+    pkg = JSON.parse(read(join(appDir, 'package.json')));
+  } catch {
+    return null;
+  }
+  const webjs = pkg && typeof pkg === 'object' ? pkg.webjs : null;
+  return webjs && typeof webjs === 'object' ? webjs : null;
+}
+
 /** @returns {{ dev: { before: string[], parallel: string[] }, start: { before: string[] } }} */
 function emptyTasks() {
   return { dev: { before: [], parallel: [] }, start: { before: [] } };
 }
+
+/**
+ * Read the `webjs db` verb map from an app's `package.json` `"webjs"` block
+ * (#1468). Drizzle is the scaffold DEFAULT, never lock-in: the runtime never
+ * imports it and `db/connection.server.ts` is the app's own file. But without
+ * this map the `webjs db` verbs contradicted that, since `generate` / `migrate`
+ * / `push` / `studio` resolved the app's drizzle-kit binary and exited 1 with
+ * any other ORM installed, while `webjs db migrate` is the spelling baked into
+ * the scaffolded `dev.before` / `start.before` tasks, the Dockerfile, and the
+ * deployment docs. Mapping a verb here keeps that spelling stable across ORMs,
+ * so an ORM swap is one config block plus the app's own `db/` files.
+ *
+ * Shape:
+ *   "webjs": {
+ *     "db": {
+ *       "migrate": "prisma migrate deploy",
+ *       "studio":  "prisma studio",
+ *       "reset":   "prisma migrate reset --force"
+ *     }
+ *   }
+ *
+ * Any key is a verb: a mapped verb runs its command through the shell (the
+ * same way a `before` step does, so a local-only binary resolves), with the
+ * extra CLI args appended. A verb the map does not name keeps its default (the
+ * drizzle-kit passthrough for the four kit verbs, `db/seed.server.ts` for
+ * `seed`), so an app with no block is unchanged. Non-string / blank values are
+ * dropped defensively, the same posture as `readAppTasks`.
+ *
+ * Pure (reads one file, never spawns / prints / exits) so it is unit-testable
+ * without a process.
+ *
+ * @param {string} appDir
+ * @param {(p: string) => string} [readFile] injectable reader for tests
+ * @returns {Record<string, string>} verb -> shell command (empty when unset)
+ */
+export function readDbCommands(appDir, readFile) {
+  const webjs = readWebjsBlock(appDir, readFile);
+  const db = webjs ? webjs.db : null;
+  if (!db || typeof db !== 'object' || Array.isArray(db)) return {};
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const [verb, cmd] of Object.entries(db)) {
+    if (typeof cmd === 'string' && cmd.trim().length > 0 && verb.trim().length > 0) out[verb] = cmd;
+  }
+  return out;
+}

package/lib/check-target.js

@@ -69,7 +69,7 @@ export async function findCheckTarget(cwd) {
  * @param {string} cwd
  * @returns {Promise<string[]>}
  */
-async function workspaceApps(cwd) {
+export async function workspaceApps(cwd) {
   let patterns;
   try {
     const pkg = JSON.parse(await readFile(join(cwd, 'package.json'), 'utf8'));