@webjsdev/cli 0.10.57 → 0.10.59

package/lib/audit.js

@@ -0,0 +1,218 @@
+/**
+ * `webjs audit`: the dependency audit with a reviewable allowlist (#1492).
+ *
+ * A freshly generated app used to fail its own `Security: dependency audit`
+ * CI step on the day it was created, because the dev toolchain reaches an
+ * advisory with NO patched release (braces, GHSA-vfj7-8cjw-p6xm, through the
+ * Tailwind watcher and the test runner's globber). Nothing can be upgraded,
+ * so the step was red until someone deleted it, which also throws away the
+ * signal for every advisory that DOES have a fix.
+ *
+ * So the app declares the advisories it accepts, in ONE place, each with the
+ * reason it is safe, under `webjs.audit` in package.json:
+ *
+ *   "audit": {
+ *     "level": "high",
+ *     "ignore": [{ "id": "GHSA-...", "reason": "why this cannot reach users" }]
+ *   }
+ *
+ * and `webjs audit` runs the package manager's own audit (`npm audit --json`
+ * or `bun audit --json`) and filters that report here, the same way for both,
+ * since npm has no ignore flag at all. Every other advisory at or above
+ * `level` still fails.
+ *
+ * The config fails CLOSED, like the doctor gate: an entry without an id or a
+ * reason, an unknown key, or a bad level exits 1 naming the problem, because
+ * an allowlist that silently stopped applying (or silently applied to
+ * everything) would be worse than none. An ignored id that no longer appears in
+ * the report is printed as stale, so the list shrinks when upstream ships a fix.
+ *
+ * @module audit
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const AUDIT_LEVELS = ['low', 'moderate', 'high', 'critical'];
+
+/**
+ * @typedef {{ id: string, reason: string }} AuditIgnore
+ * @typedef {{ level: string, ignore: AuditIgnore[] }} AuditConfig
+ * @typedef {{ id: string, url: string, severity: string, title: string, packages: string[] }} Advisory
+ */
+
+/**
+ * Read and validate `webjs.audit` from a parsed package.json.
+ *
+ * @param {Record<string, any>} pkg
+ * @returns {{ config: AuditConfig, errors: string[] }}
+ */
+export function readAuditConfig(pkg) {
+  /** @type {AuditConfig} */
+  const config = { level: 'high', ignore: [] };
+  /** @type {string[]} */
+  const errors = [];
+  const raw = pkg?.webjs?.audit;
+  if (raw === undefined) return { config, errors };
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { config, errors: ['webjs.audit must be an object'] };
+  }
+  for (const key of Object.keys(raw)) {
+    if (key !== 'level' && key !== 'ignore') errors.push(`webjs.audit: unknown key "${key}" (expected "level" or "ignore")`);
+  }
+  if (raw.level !== undefined) {
+    if (!AUDIT_LEVELS.includes(raw.level)) errors.push(`webjs.audit.level must be one of ${AUDIT_LEVELS.join(', ')}`);
+    else config.level = raw.level;
+  }
+  if (raw.ignore !== undefined) {
+    if (!Array.isArray(raw.ignore)) {
+      errors.push('webjs.audit.ignore must be an array of { id, reason }');
+    } else {
+      raw.ignore.forEach((entry, i) => {
+        const at = `webjs.audit.ignore[${i}]`;
+        if (!entry || typeof entry !== 'object') { errors.push(`${at} must be an object { id, reason }`); return; }
+        const extra = Object.keys(entry).filter((k) => k !== 'id' && k !== 'reason');
+        if (extra.length) errors.push(`${at}: unknown key "${extra[0]}" (expected "id" and "reason")`);
+        if (typeof entry.id !== 'string' || !/^(GHSA(-[0-9a-z]{4}){3}|CVE-\d{4}-\d+)$/i.test(entry.id)) {
+          errors.push(`${at}.id must be an advisory id such as GHSA-xxxx-xxxx-xxxx or CVE-2024-12345`);
+          return;
+        }
+        if (typeof entry.reason !== 'string' || entry.reason.trim() === '') {
+          errors.push(`${at} (${entry.id}) needs a non-empty "reason" saying why it is safe to accept`);
+          return;
+        }
+        config.ignore.push({ id: entry.id, reason: entry.reason });
+      });
+    }
+  }
+  return { config, errors };
+}
+
+/**
+ * Which package manager's audit to run. Walks up from `cwd` to the first
+ * lockfile, since an app inside a workspace has its lockfile at the root.
+ * Only bun and npm have an audit this command drives; anything else is
+ * reported as unsupported by the caller.
+ *
+ * @param {string} cwd
+ * @returns {'bun' | 'npm' | 'pnpm' | 'yarn'}
+ */
+export function detectAuditManager(cwd) {
+  let dir = cwd;
+  for (;;) {
+    if (existsSync(join(dir, 'bun.lock')) || existsSync(join(dir, 'bun.lockb'))) return 'bun';
+    if (existsSync(join(dir, 'package-lock.json')) || existsSync(join(dir, 'npm-shrinkwrap.json'))) return 'npm';
+    if (existsSync(join(dir, 'pnpm-lock.yaml'))) return 'pnpm';
+    if (existsSync(join(dir, 'yarn.lock'))) return 'yarn';
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.versions.bun ? 'bun' : 'npm';
+}
+
+/** The advisory id at the end of a GitHub advisory url. */
+function idFromUrl(url) {
+  const m = /(GHSA(?:-[0-9a-z]{4}){3})/i.exec(url || '');
+  return m ? m[1] : '';
+}
+
+/**
+ * The source advisories in an `npm audit --json` (v2 report format) report,
+ * deduplicated by id. A vulnerability entry whose `via` holds only package
+ * NAMES is a dependent of one of these, not an advisory of its own, so it is
+ * covered by filtering the advisories it inherits from.
+ *
+ * @param {any} report
+ * @returns {Advisory[]}
+ */
+export function npmAdvisories(report) {
+  /** @type {Map<string, Advisory>} */
+  const byId = new Map();
+  for (const [name, vuln] of Object.entries(report?.vulnerabilities || {})) {
+    for (const via of /** @type {any} */ (vuln).via || []) {
+      if (!via || typeof via !== 'object') continue;
+      const id = idFromUrl(via.url) || String(via.source ?? via.url);
+      const cur = byId.get(id);
+      if (cur) { if (!cur.packages.includes(name)) cur.packages.push(name); continue; }
+      byId.set(id, { id, url: via.url || '', severity: via.severity || 'low', title: via.title || '', packages: [name] });
+    }
+  }
+  return [...byId.values()];
+}
+
+/**
+ * Split advisories into the ones that still fail and the ones the allowlist
+ * accepted, keeping only those at or above `level`.
+ *
+ * @param {Advisory[]} advisories
+ * @param {AuditConfig} config
+ * @returns {{ failing: Advisory[], ignored: Advisory[], stale: AuditIgnore[] }}
+ */
+export function applyAuditConfig(advisories, config) {
+  const floor = AUDIT_LEVELS.indexOf(config.level);
+  const atLevel = advisories.filter((a) => AUDIT_LEVELS.indexOf(a.severity) >= floor);
+  const ids = new Set(config.ignore.map((i) => i.id.toUpperCase()));
+  const failing = atLevel.filter((a) => !ids.has(a.id.toUpperCase()));
+  const ignored = atLevel.filter((a) => ids.has(a.id.toUpperCase()));
+  const seen = new Set(advisories.map((a) => a.id.toUpperCase()));
+  const stale = config.ignore.filter((i) => !seen.has(i.id.toUpperCase()));
+  return { failing, ignored, stale };
+}
+
+/**
+ * The source advisories in a `bun audit --json` report, which is keyed by
+ * package name with a list of advisories each.
+ *
+ * @param {any} report
+ * @returns {Advisory[]}
+ */
+export function bunAdvisories(report) {
+  /** @type {Map<string, Advisory>} */
+  const byId = new Map();
+  for (const [name, list] of Object.entries(report || {})) {
+    if (!Array.isArray(list)) continue;
+    for (const adv of list) {
+      const id = idFromUrl(adv?.url) || String(adv?.id ?? adv?.url);
+      const cur = byId.get(id);
+      if (cur) { if (!cur.packages.includes(name)) cur.packages.push(name); continue; }
+      byId.set(id, { id, url: adv?.url || '', severity: adv?.severity || 'low', title: adv?.title || '', packages: [name] });
+    }
+  }
+  return [...byId.values()];
+}
+
+/**
+ * Parse a package manager's `audit --json` stdout into advisories. Both
+ * managers exit non-zero when they find anything, so the exit code says
+ * nothing; an unparseable stdout (a registry outage, an old manager) returns
+ * `null` and the caller fails closed.
+ *
+ * @param {'bun' | 'npm'} pm
+ * @param {string} stdout
+ * @returns {Advisory[] | null}
+ */
+export function parseAuditReport(pm, stdout) {
+  let report;
+  try { report = JSON.parse(stdout); } catch { return null; }
+  if (!report || typeof report !== 'object') return null;
+  if (pm === 'npm') {
+    if (report.error) return null;
+    return npmAdvisories(report);
+  }
+  return bunAdvisories(report);
+}
+
+/**
+ * Read `webjs.audit` from the package.json in `cwd`.
+ *
+ * @param {string} cwd
+ */
+export function readAuditConfigFrom(cwd) {
+  const p = join(cwd, 'package.json');
+  if (!existsSync(p)) return { config: { level: 'high', ignore: [] }, errors: ['no package.json in this directory'] };
+  try {
+    return readAuditConfig(JSON.parse(readFileSync(p, 'utf8')));
+  } catch (e) {
+    return { config: { level: 'high', ignore: [] }, errors: [`package.json is not valid JSON: ${/** @type {Error} */ (e).message}`] };
+  }
+}

package/lib/browser-test-files.js

@@ -0,0 +1,125 @@
+/**
+ * Decide whether `webjs test --browser` has anything to run (#1491).
+ *
+ * web-test-runner throws `Could not find any test files with pattern(s)` when
+ * its `files` globs match nothing, so an app with no browser tests yet (the
+ * state `npm run gallery:clear` leaves behind) fails its own CI on the browser
+ * layer. A missing layer is not a failing layer: the server layer already
+ * passes with zero files, and the browser layer should too. WTR raises the
+ * error while building its session groups, after it has started, so the check
+ * has to happen here, before it is spawned.
+ *
+ * The globs are read from the config's SOURCE rather than by importing it,
+ * because the scaffold's config top-level-awaits a warmed webjs handler (the
+ * whole app boots) just to answer a question a file walk can answer. When the
+ * `files` value is not a plain literal (computed, imported, spread), the
+ * patterns come back `null` and the caller runs WTR exactly as before, so a
+ * config this reader does not understand never turns into a silent skip.
+ *
+ * @module browser-test-files
+ */
+import { readdir } from 'node:fs/promises';
+import { join, relative, sep, matchesGlob } from 'node:path';
+
+/**
+ * Pull the `files` globs out of a web-test-runner config's source text.
+ * Accepts `files: 'one/glob'` and `files: ['a', "b", ...]` with only string
+ * literals inside the array. Anything else returns `null` (unknown).
+ *
+ * @param {string} source
+ * @returns {string[] | null}
+ */
+export function readWtrFilePatterns(source) {
+  // Strip line + block comments first, so a commented-out `files:` cannot
+  // match and a comment inside the array does not read as a non-literal.
+  const code = stripComments(source);
+  const single = code.match(/\bfiles\s*:\s*(['"])([^'"]+)\1\s*[,}\n]/);
+  if (single) return [single[2]];
+  const arr = code.match(/\bfiles\s*:\s*\[([\s\S]*?)\]/);
+  if (!arr) return null;
+  const body = arr[1].trim();
+  if (body === '') return [];
+  const out = [];
+  // Every comma-separated element must be a quoted string literal.
+  for (const raw of body.split(',')) {
+    const el = raw.trim();
+    if (el === '') continue; // trailing comma
+    const m = el.match(/^(['"])([^'"]*)\1$/);
+    if (!m) return null;
+    out.push(m[2]);
+  }
+  return out;
+}
+
+/**
+ * Walk `cwd` and return the app-relative paths (forward slashes) matching
+ * the include globs and none of the `!`-prefixed exclude globs. Skips
+ * `node_modules` and dot directories, which WTR's globber skips too.
+ *
+ * @param {string} cwd
+ * @param {string[]} patterns
+ * @returns {Promise<string[]>}
+ */
+export async function findBrowserTestFiles(cwd, patterns) {
+  const include = patterns.filter((p) => !p.startsWith('!')).map(normalize);
+  const exclude = patterns.filter((p) => p.startsWith('!')).map((p) => normalize(p.slice(1)));
+  if (include.length === 0) return [];
+  const found = [];
+  const walk = async (dir) => {
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); }
+    catch { return; }
+    for (const ent of entries) {
+      if (ent.name === 'node_modules' || ent.name.startsWith('.')) continue;
+      const full = join(dir, ent.name);
+      if (ent.isDirectory()) { await walk(full); continue; }
+      if (!ent.isFile()) continue;
+      const rel = relative(cwd, full).split(sep).join('/');
+      if (include.some((g) => matchesGlob(rel, g)) && !exclude.some((g) => matchesGlob(rel, g))) {
+        found.push(rel);
+      }
+    }
+  };
+  await walk(cwd);
+  return found;
+}
+
+/**
+ * Remove `//` and `/* *\/` comments while leaving string literals intact. A
+ * regex strip is not enough: a glob such as `test/**\/browser` contains the
+ * very `/*` that opens a block comment.
+ *
+ * @param {string} src
+ * @returns {string}
+ */
+function stripComments(src) {
+  let out = '';
+  let quote = '';
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i];
+    if (quote) {
+      out += c;
+      if (c === '\\') { out += src[++i] ?? ''; continue; }
+      if (c === quote) quote = '';
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; out += c; continue; }
+    if (c === '/' && src[i + 1] === '/') {
+      while (i < src.length && src[i] !== '\n') i++;
+      out += '\n';
+      continue;
+    }
+    if (c === '/' && src[i + 1] === '*') {
+      const end = src.indexOf('*/', i + 2);
+      i = end === -1 ? src.length : end + 1;
+      continue;
+    }
+    out += c;
+  }
+  return out;
+}
+
+/** @param {string} p */
+function normalize(p) {
+  return p.replace(/^\.\//, '');
+}

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'));

package/lib/ci-config.js

@@ -0,0 +1,250 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Read the local-CI step list from an app's `package.json` `"webjs": { "ci" }`
+ * block (#1471), the list `webjs ci` runs. Modeled on Rails 8.1's `config/ci.rb`
+ * and shaped like the #550 `dev` / `start` orchestration: data in the `webjs`
+ * block, read by the CLI, never by the server, so every tool (the JSON Schema,
+ * `webjs doctor`, a cloud workflow that calls `npm run ci`) learns the list
+ * without importing app code.
+ *
+ * Shape:
+ *   "webjs": { "ci": { "steps": [
+ *     "webjs check",                                     // shorthand: title = command
+ *     { "title": "Types", "run": "webjs typecheck" },
+ *     { "title": "Checks", "parallel": 2, "steps": [
+ *       { "title": "Tests", "steps": [                   // a nested group takes ONE slot
+ *         { "title": "e2e", "run": "webjs test --server", "env": { "WEBJS_E2E": "1" } }
+ *       ] }
+ *     ] }
+ *   ] } }
+ *
+ * The boot validator (`@webjsdev/server` webjs-config-validate.js) checks only
+ * top-level key membership and never follows the schema's `$ref`, so this
+ * reader validates the step shapes itself and reports every problem with its
+ * JSON path, rather than silently skipping a malformed entry: a step that is
+ * dropped is a check that never ran, which is the exact false green local CI
+ * exists to prevent. The bin refuses to run on any problem.
+ *
+ * Pure (reads one file, never spawns / prints / exits), with the reader
+ * injectable, matching `app-tasks.js`.
+ *
+ * @typedef {{ kind: 'step', title: string, run: string, env: Record<string, string> }} CiStep
+ * @typedef {{ kind: 'group', title: string, parallel: number, steps: CiNode[] }} CiGroup
+ * @typedef {CiStep | CiGroup} CiNode
+ */
+
+/**
+ * @param {string} appDir
+ * @param {(p: string) => string} [readFile] injectable reader for tests
+ * @returns {{ declared: boolean, steps: CiNode[], problems: string[] }}
+ *   `declared` is false when there is no `webjs.ci` block at all (the bin
+ *   turns that into a "nothing declared" error naming where to declare one),
+ *   as opposed to a block that is present but malformed (`problems`).
+ */
+export function readCiConfig(appDir, readFile) {
+  const read = readFile || ((p) => readFileSync(p, 'utf8'));
+  let pkg;
+  try {
+    pkg = JSON.parse(read(join(appDir, 'package.json')));
+  } catch {
+    return { declared: false, steps: [], problems: [] };
+  }
+  const webjs = pkg && typeof pkg === 'object' ? pkg.webjs : null;
+  const ci = webjs && typeof webjs === 'object' ? webjs.ci : undefined;
+  if (ci === undefined) return { declared: false, steps: [], problems: [] };
+  if (!isPlainObject(ci)) {
+    return { declared: true, steps: [], problems: ['webjs.ci must be an object holding a `steps` array'] };
+  }
+  const problems = [];
+  for (const key of Object.keys(ci)) {
+    if (key !== 'steps') problems.push(`webjs.ci has an unknown key "${key}" (only \`steps\` is read)`);
+  }
+  if (ci.steps === undefined) {
+    problems.push('webjs.ci.steps is missing');
+    return { declared: true, steps: [], problems };
+  }
+  const r = normalizeSteps(ci.steps, 'webjs.ci.steps', false);
+  problems.push(...r.problems);
+  return { declared: true, steps: r.steps, problems };
+}
+
+/**
+ * Normalize a raw step array into `CiNode`s, collecting every shape problem
+ * with its JSON path. A string is shorthand for a command titled by itself; an
+ * object with `steps` is a group; an object with `run` is a command. Only a
+ * TOP-LEVEL group may declare `parallel`: a nested group takes one slot of
+ * its parent and runs its steps in order, so `parallel` on it is reported
+ * rather than honoured (the Rails rule: sub-groups cannot be parallelized),
+ * which is exactly what the JSON Schema's `ciNestedStep` and the
+ * `WebjsCiNestedGroup` type say.
+ *
+ * @param {unknown} raw
+ * @param {string} path JSON path used in problem messages
+ * @param {boolean} nested whether these steps sit inside a group
+ * @returns {{ steps: CiNode[], problems: string[] }}
+ */
+export function normalizeSteps(raw, path = 'webjs.ci.steps', nested = false) {
+  /** @type {CiNode[]} */
+  const steps = [];
+  /** @type {string[]} */
+  const problems = [];
+  if (!Array.isArray(raw)) {
+    return { steps, problems: [`${path} must be an array of steps`] };
+  }
+  raw.forEach((item, i) => {
+    const at = `${path}[${i}]`;
+    if (typeof item === 'string') {
+      const run = item.trim();
+      if (!run) problems.push(`${at} is an empty command`);
+      else steps.push({ kind: 'step', title: run, run, env: {} });
+      return;
+    }
+    if (!isPlainObject(item)) {
+      problems.push(`${at} must be a command string, a { title, run } object, or a { title, steps } group`);
+      return;
+    }
+    const title = typeof item.title === 'string' ? item.title.trim() : '';
+    if (Object.prototype.hasOwnProperty.call(item, 'steps')) {
+      for (const key of Object.keys(item)) {
+        if (!['title', 'steps', 'parallel'].includes(key)) {
+          problems.push(`${at} has an unknown key "${key}" (a group takes title, steps, parallel)`);
+        }
+      }
+      if (!title) problems.push(`${at} (a group) needs a non-empty title`);
+      let parallel = 1;
+      if (item.parallel !== undefined) {
+        if (nested) {
+          // One rule on every surface (the schema's ciNestedStep, the
+          // WebjsCiNestedGroup type, the docs): a nested group never declares
+          // parallel, whatever its parent is. It takes one slot and runs in order.
+          problems.push(
+            `${at}.parallel is not allowed on a nested group (it takes one slot of its parent and runs its steps in order)`,
+          );
+        } else if (!Number.isInteger(item.parallel) || item.parallel < 1) {
+          problems.push(`${at}.parallel must be an integer of at least 1`);
+        } else {
+          parallel = item.parallel;
+        }
+      }
+      const inner = normalizeSteps(item.steps, `${at}.steps`, true);
+      problems.push(...inner.problems);
+      if (Array.isArray(item.steps) && item.steps.length === 0) problems.push(`${at}.steps is empty`);
+      steps.push({ kind: 'group', title: title || `group ${i}`, parallel, steps: inner.steps });
+      return;
+    }
+    for (const key of Object.keys(item)) {
+      if (!['title', 'run', 'env'].includes(key)) {
+        problems.push(`${at} has an unknown key "${key}" (a command takes title, run, env)`);
+      }
+    }
+    const run = typeof item.run === 'string' ? item.run.trim() : '';
+    if (!run) problems.push(`${at}.run must be a non-empty command string`);
+    if (!title) problems.push(`${at}.title must be a non-empty string`);
+    /** @type {Record<string, string>} */
+    const env = {};
+    if (item.env !== undefined) {
+      if (!isPlainObject(item.env)) {
+        problems.push(`${at}.env must be an object of string values`);
+      } else {
+        for (const [k, v] of Object.entries(item.env)) {
+          if (typeof v === 'string') env[k] = v;
+          else problems.push(`${at}.env.${k} must be a string`);
+        }
+      }
+    }
+    if (run && title) steps.push({ kind: 'step', title, run, env });
+  });
+  return { steps, problems };
+}
+
+/**
+ * Select the steps `--only <title>` names. A matched group is taken WHOLE (its
+ * children are not searched further); matching is case-insensitive on the
+ * trimmed title. A title that matches nothing is a problem rather than a
+ * silent empty run, since "ran zero steps" reads as green.
+ *
+ * @param {CiNode[]} steps
+ * @param {string[]} only
+ * @returns {{ steps: CiNode[], problems: string[] }}
+ */
+export function selectSteps(steps, only) {
+  if (!only || only.length === 0) return { steps, problems: [] };
+  const wanted = only.map((t) => t.trim().toLowerCase());
+  const hit = new Set();
+  /** @type {CiNode[]} */
+  const picked = [];
+  const walk = (nodes) => {
+    for (const node of nodes) {
+      const key = node.title.trim().toLowerCase();
+      const idx = wanted.indexOf(key);
+      if (idx !== -1) {
+        hit.add(idx);
+        picked.push(node);
+        continue;
+      }
+      if (node.kind === 'group') walk(node.steps);
+    }
+  };
+  walk(steps);
+  const problems = only
+    .filter((_, i) => !hit.has(i))
+    .map((t) => `--only "${t}" matches no step or group title`);
+  return { steps: picked, problems };
+}
+
+/**
+ * Every command step in tree order (groups flattened), for counting and for
+ * the JSON report.
+ *
+ * @param {CiNode[]} steps
+ * @returns {CiStep[]}
+ */
+export function flattenSteps(steps) {
+  /** @type {CiStep[]} */
+  const out = [];
+  for (const node of steps) {
+    if (node.kind === 'group') out.push(...flattenSteps(node.steps));
+    else out.push(node);
+  }
+  return out;
+}
+
+/**
+ * The refusal `webjs ci` prints when the directory declares no `webjs.ci`
+ * block: what is missing, where it goes, and (at a workspace root) which
+ * member apps already declare one. Mirrors `notAnAppMessage` in
+ * check-target.js. A run with nothing declared exits 1 rather than 0, because
+ * "ran zero steps" would read as green.
+ *
+ * @param {string} cwd
+ * @param {string[]} apps workspace members that DO declare a `webjs.ci` block
+ */
+export function noCiConfigMessage(cwd, apps) {
+  const lines = [
+    'webjs ci: nothing to run, this package.json declares no "webjs": { "ci" } block.',
+    '',
+    `  ${cwd}`,
+    '',
+    'Declare the steps once and every tool reads the same list:',
+    '',
+    '  "webjs": { "ci": { "steps": [',
+    '    "webjs check",',
+    '    { "title": "Tests", "run": "webjs test" }',
+    '  ] } }',
+    '',
+  ];
+  if (apps.length > 0) {
+    lines.push('These workspace members declare one. Run it inside each:', '');
+    for (const app of apps) lines.push(`  ( cd ${app} && npx webjs ci )`);
+    lines.push('');
+  }
+  lines.push('`webjs help ci` shows the flags.');
+  return lines.join('\n');
+}
+
+/** @param {unknown} v */
+function isPlainObject(v) {
+  return !!v && typeof v === 'object' && !Array.isArray(v);
+}