@everystack/cli 0.3.0 → 0.3.4

package/src/cli/bundle-weight.ts

@@ -0,0 +1,356 @@
+/**
+ * Bundle weight/size audit — pure scanners for `everystack bundle:audit`.
+ *
+ * The leak scanner (bundle-audit.ts) answers "did a secret get into the bundle?"
+ * This answers "is the bundle bloated, and is data shipping that belongs in the
+ * database?" — the class of mistake test-case-zero is made of: an agent that
+ * defaults to training-consensus and bundles a 180MB JSON into an Expo app.
+ *
+ * Config-free by construction. The only inputs are universal truths:
+ *   - a file's byte size (the budget gate),
+ *   - its extension (data vs image vs js vs source-map vs other),
+ *   - and, when a source map is present, the per-package source-byte breakdown
+ *     already computed by bundle.ts (the dependency-weight gate).
+ *
+ * Everything here is pure: it takes a list of {path, size} and returns findings.
+ * The command layer walks the export directory (and the app source tree) and
+ * feeds those lists in, so the governance MCP can import these scanners directly
+ * without touching the filesystem.
+ */
+
+import type { AuditFinding } from './bundle-audit.js';
+import type { Composition } from './bundle.js';
+
+/** One file's relative path and byte size — the only input the gates need. */
+export interface AssetFile {
+  path: string;
+  size: number;
+}
+
+export type AssetKind = 'data' | 'image' | 'js' | 'sourcemap' | 'other';
+
+/** Per-file and total byte budgets. All sizes are bytes. */
+export interface WeightBudget {
+  /** Generic single-file warn/fail (non-data, non-image, non-js). */
+  perFileWarn: number;
+  perFileFail: number;
+  /** An image past this is almost certainly unoptimized. */
+  imageWarn: number;
+  /** Sum of every file in the export. */
+  totalWarn: number;
+  totalFail: number;
+  /** Sum of served client JS chunks. */
+  jsWarn: number;
+  jsFail: number;
+  /** A data file (.json/.csv/…) shipped in the bundle. Categorically suspect:
+   *  data belongs in the DB/Model/API, so the thresholds are tighter. */
+  dataWarn: number;
+  dataFail: number;
+  /** A single dependency's source-byte contribution (from the source map). */
+  depWarn: number;
+  /** …or its share of the largest chunk, whichever trips first. */
+  depShareWarn: number;
+}
+
+const MB = 1024 * 1024;
+
+/**
+ * Defaults chosen against real Expo/mobile norms, not arbitrary round numbers:
+ *  - Optimized images sit well under 1MB; a 2MB+ non-image asset is unusual and
+ *    a 10MB single file is almost always a mistake.
+ *  - Data files belong in the DB, so they fail tighter (5MB) with a redirect
+ *    message — a 180MB JSON trips this loudly.
+ *  - A typical Expo web client bundle is a few MB raw; 15MB+ is bloat.
+ *  - A single dependency over ~512KB of source, or dominating >25% of the
+ *    largest chunk, is worth a second look.
+ * All overridable via flags (resolveWeightBudget).
+ */
+export const DEFAULT_WEIGHT_BUDGET: WeightBudget = {
+  perFileWarn: 2 * MB,
+  perFileFail: 10 * MB,
+  imageWarn: 1 * MB,
+  totalWarn: 25 * MB,
+  totalFail: 100 * MB,
+  jsWarn: 5 * MB,
+  jsFail: 15 * MB,
+  dataWarn: 1 * MB,
+  dataFail: 5 * MB,
+  depWarn: 512 * 1024,
+  depShareWarn: 0.25,
+};
+
+const DATA_EXTS = new Set([
+  '.json', '.csv', '.tsv', '.geojson', '.ndjson', '.jsonl',
+  '.xml', '.yaml', '.yml', '.parquet', '.sqlite', '.db',
+]);
+const IMAGE_EXTS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.tiff', '.tif', '.avif',
+]);
+
+function ext(p: string): string {
+  const dot = p.lastIndexOf('.');
+  return dot < 0 ? '' : p.slice(dot).toLowerCase();
+}
+
+/** Classify a file by extension — the basis of every weight gate. */
+export function classifyAsset(p: string): AssetKind {
+  const e = ext(p);
+  if (e === '.map') return 'sourcemap';
+  if (e === '.js' || e === '.mjs' || e === '.cjs') return 'js';
+  if (DATA_EXTS.has(e)) return 'data';
+  if (IMAGE_EXTS.has(e)) return 'image';
+  return 'other';
+}
+
+/** Human-readable byte size: "180.00 MB", "512.00 KB", "40 B". */
+export function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  if (n < MB) return `${(n / 1024).toFixed(2)} KB`;
+  if (n < 1024 * MB) return `${(n / MB).toFixed(2)} MB`;
+  return `${(n / (1024 * MB)).toFixed(2)} GB`;
+}
+
+/**
+ * Per-file weight gate over data / image / other assets. JS and source maps are
+ * skipped here (scanJsWeight / scanSourceMapsPresent own those). A data file
+ * over budget is reported as `data-in-bundle` with the "belongs in the DB"
+ * redirect; an oversized image is called out as unoptimized.
+ */
+export function scanAssetWeights(
+  files: AssetFile[],
+  budget: WeightBudget = DEFAULT_WEIGHT_BUDGET,
+): AuditFinding[] {
+  const findings: AuditFinding[] = [];
+  for (const f of files) {
+    const kind = classifyAsset(f.path);
+    if (kind === 'js' || kind === 'sourcemap') continue;
+
+    if (kind === 'data') {
+      if (f.size >= budget.dataFail) {
+        findings.push({
+          severity: 'fail',
+          check: 'data-in-bundle',
+          source: f.path,
+          detail: `${f.path} is ${formatBytes(f.size)} of data shipped in the bundle — this belongs in the database (a Model/migration) and should be served over the API, not bundled`,
+        });
+      } else if (f.size >= budget.dataWarn) {
+        findings.push({
+          severity: 'warn',
+          check: 'data-in-bundle',
+          source: f.path,
+          detail: `${f.path} is ${formatBytes(f.size)} of data in the bundle — consider moving it to the database/API`,
+        });
+      }
+      continue;
+    }
+
+    const warnAt = kind === 'image' ? budget.imageWarn : budget.perFileWarn;
+    if (f.size >= budget.perFileFail) {
+      findings.push({
+        severity: 'fail',
+        check: 'asset-weight',
+        source: f.path,
+        detail:
+          kind === 'image'
+            ? `${f.path} is ${formatBytes(f.size)} — an unoptimized image this large should be compressed or served from a CDN`
+            : `${f.path} is ${formatBytes(f.size)}, over the ${formatBytes(budget.perFileFail)} per-file budget`,
+      });
+    } else if (f.size >= warnAt) {
+      findings.push({
+        severity: 'warn',
+        check: 'asset-weight',
+        source: f.path,
+        detail:
+          kind === 'image'
+            ? `${f.path} is ${formatBytes(f.size)} — large for an image, consider optimizing (WebP/AVIF) or a CDN`
+            : `${f.path} is ${formatBytes(f.size)}, over the ${formatBytes(budget.perFileWarn)} per-file warning budget`,
+      });
+    }
+  }
+  return findings;
+}
+
+/** Total-export-size gate over every file. */
+export function scanTotalWeight(
+  files: AssetFile[],
+  budget: WeightBudget = DEFAULT_WEIGHT_BUDGET,
+): AuditFinding[] {
+  const total = files.reduce((sum, f) => sum + f.size, 0);
+  if (total >= budget.totalFail) {
+    return [
+      {
+        severity: 'fail',
+        check: 'total-weight',
+        source: 'export',
+        detail: `total export is ${formatBytes(total)} across ${files.length} file(s), over the ${formatBytes(budget.totalFail)} budget`,
+      },
+    ];
+  }
+  if (total >= budget.totalWarn) {
+    return [
+      {
+        severity: 'warn',
+        check: 'total-weight',
+        source: 'export',
+        detail: `total export is ${formatBytes(total)} across ${files.length} file(s), over the ${formatBytes(budget.totalWarn)} warning budget`,
+      },
+    ];
+  }
+  return [];
+}
+
+/** Served-client-JS weight gate (sum of all .js chunks). */
+export function scanJsWeight(
+  files: AssetFile[],
+  budget: WeightBudget = DEFAULT_WEIGHT_BUDGET,
+): AuditFinding[] {
+  const js = files.filter((f) => classifyAsset(f.path) === 'js');
+  if (js.length === 0) return [];
+  const total = js.reduce((sum, f) => sum + f.size, 0);
+  if (total >= budget.jsFail) {
+    return [
+      {
+        severity: 'fail',
+        check: 'js-weight',
+        source: 'client-js',
+        detail: `client JS is ${formatBytes(total)} raw across ${js.length} chunk(s), over the ${formatBytes(budget.jsFail)} budget — see the data-in-bundle findings for inlined datasets, or \`everystack bundle:analyze\` for the per-package breakdown`,
+      },
+    ];
+  }
+  if (total >= budget.jsWarn) {
+    return [
+      {
+        severity: 'warn',
+        check: 'js-weight',
+        source: 'client-js',
+        detail: `client JS is ${formatBytes(total)} raw across ${js.length} chunk(s), over the ${formatBytes(budget.jsWarn)} warning budget`,
+      },
+    ];
+  }
+  return [];
+}
+
+/**
+ * Flag source maps present in the export — they will be served to prod and
+ * expose original source. Distinct from the network leak check, which catches a
+ * map already served at a URL; this catches it before deploy.
+ */
+export function scanSourceMapsPresent(files: AssetFile[]): AuditFinding[] {
+  return files
+    .filter((f) => classifyAsset(f.path) === 'sourcemap')
+    .map((f) => ({
+      severity: 'warn' as const,
+      check: 'source-map' as const,
+      source: f.path,
+      detail: `source map (${formatBytes(f.size)}) is in the export and will be served to prod — exclude it from the deployed artifacts`,
+    }));
+}
+
+/**
+ * Best-effort dependency-weight gate from the largest chunk's source-map
+ * composition (bundle.ts → composeSourceMap). A single dependency over the byte
+ * budget, or dominating the chunk by share, is flagged. App workspace buckets
+ * (APP:*) are skipped — they are the app's own code, not a dependency.
+ */
+export function scanDependencyWeight(
+  composition: Composition,
+  budget: WeightBudget = DEFAULT_WEIGHT_BUDGET,
+): AuditFinding[] {
+  const findings: AuditFinding[] = [];
+  for (const p of composition.top) {
+    if (p.pkg.startsWith('APP:')) continue;
+    const overBytes = p.bytes >= budget.depWarn;
+    const overShare = p.share >= budget.depShareWarn;
+    if (overBytes || overShare) {
+      findings.push({
+        severity: 'warn',
+        check: 'dep-weight',
+        source: p.pkg,
+        detail: `${p.pkg} contributes ${formatBytes(p.bytes)} (${(p.share * 100).toFixed(1)}%) to the largest chunk — consider a lighter alternative or lazy-loading`,
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * Pinpoint *data inlined into a JS chunk* — the most useful diagnosis, because
+ * a dataset imported into app code (`import data from './big.json'`) is bundled
+ * as a Metro module and shows up only as "JS is big". This splits the chunk on
+ * Metro module boundaries (`__d(`), finds the heavy ones whose body is an
+ * `exports = {…}`/`[…]` literal with high data density (digits/quotes/colons),
+ * and names each with its size and a key hint, redirecting it to the DB/API.
+ *
+ * Pure: takes the chunk text, returns findings. Top offenders only (capped), so
+ * a chunk full of data produces a readable list, not hundreds of lines.
+ */
+export function analyzeChunkBloat(
+  text: string,
+  source: string,
+  budget: WeightBudget = DEFAULT_WEIGHT_BUDGET,
+  topN = 8,
+): AuditFinding[] {
+  const starts: number[] = [];
+  const re = /__d\(/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text)) !== null) starts.push(m.index);
+  if (starts.length === 0) return [];
+
+  const found: AuditFinding[] = [];
+  for (let i = 0; i < starts.length; i++) {
+    const s = starts[i];
+    const e = i + 1 < starts.length ? starts[i + 1] : text.length;
+    const size = e - s;
+    if (size < budget.dataWarn) continue;
+
+    const head = text.slice(s, s + 220);
+    if (!/\.exports\s*=\s*[{[]/.test(head)) continue; // not an export literal
+
+    // Data density on a sample: data files are mostly quotes/digits/punctuation.
+    const sample = text.slice(s, s + 4096);
+    const dataChars = (sample.match(/["{}:,[\]0-9.]/g) || []).length;
+    if (!sample.length || dataChars / sample.length < 0.22) continue; // looks like code
+
+    const hint = (head.match(/exports\s*=\s*[{[]\s*"?([A-Za-z0-9_:.-]{2,40})"?\s*[:,]/) || [])[1];
+    found.push({
+      severity: size >= budget.dataFail ? 'fail' : 'warn',
+      check: 'data-in-bundle',
+      source,
+      detail: `${formatBytes(size)} of data is inlined into ${source}${hint ? ` (a module whose first key is "${hint}")` : ''} — this is a dataset imported into app code; move it to the database (a Model/migration) and serve it over the API instead of bundling it`,
+    });
+  }
+  return found.sort((a, b) => byteHint(b.detail) - byteHint(a.detail)).slice(0, topN);
+}
+
+/** Pull the leading byte count back out of a formatted detail, for sorting. */
+function byteHint(detail: string): number {
+  const m = detail.match(/^([\d.]+)\s*(B|KB|MB|GB)/);
+  if (!m) return 0;
+  const units: Record<string, number> = { B: 1, KB: 1024, MB: MB, GB: 1024 * MB };
+  return parseFloat(m[1]) * (units[m[2]] || 1);
+}
+
+/** The N biggest files, largest first — for an always-on "largest files" list. */
+export function largestFiles(files: AssetFile[], n = 10): AssetFile[] {
+  return [...files].sort((a, b) => b.size - a.size).slice(0, n);
+}
+
+/** Resolve a budget from CLI flags (MB), falling back to the defaults. */
+export function resolveWeightBudget(
+  flags: Record<string, string>,
+  base: WeightBudget = DEFAULT_WEIGHT_BUDGET,
+): WeightBudget {
+  const mb = (key: string): number | undefined => {
+    const raw = flags[key];
+    if (raw == null) return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n * MB : undefined;
+  };
+  return {
+    ...base,
+    perFileFail: mb('max-file-mb') ?? base.perFileFail,
+    totalFail: mb('max-total-mb') ?? base.totalFail,
+    jsFail: mb('max-js-mb') ?? base.jsFail,
+    dataFail: mb('max-data-mb') ?? base.dataFail,
+  };
+}

package/src/cli/bundle.ts

@@ -0,0 +1,146 @@
+/**
+ * Bundle analysis — pure, filesystem-free logic for `everystack bundle:analyze`.
+ *
+ * Measures the served client JS (raw / gzip / brotli — brotli is the real
+ * CloudFront-transfer number) and, from the largest chunk's source map, ranks
+ * the source-byte contributors per npm package / app workspace.
+ *
+ * Config-free by construction: the bundle layout is an Expo convention (located
+ * by the command), and the workspace bucketing is derived from the source paths
+ * themselves — nothing is hand-declared.
+ */
+
+import zlib from 'node:zlib';
+
+export interface ChunkInput {
+  name: string;
+  buf: Buffer;
+}
+
+export interface ChunkSize {
+  name: string;
+  raw: number;
+  gz: number;
+  br: number;
+}
+
+export interface SizeTotals {
+  raw: number;
+  gz: number;
+  br: number;
+}
+
+export interface SourceMap {
+  sources?: (string | null)[];
+  sourcesContent?: (string | null)[];
+}
+
+export interface PkgComposition {
+  pkg: string;
+  bytes: number;
+  share: number; // 0..1
+}
+
+export interface Composition {
+  total: number;
+  modules: number;
+  top: PkgComposition[];
+}
+
+/** Raw / gzip(9) / brotli byte sizes of a single chunk buffer. Deterministic. */
+export function measureChunk(buf: Buffer): SizeTotals {
+  return {
+    raw: buf.length,
+    gz: zlib.gzipSync(buf, { level: 9 }).length,
+    br: zlib.brotliCompressSync(buf).length,
+  };
+}
+
+/** Measure every chunk, sorted largest-raw first. */
+export function measureChunks(chunks: ChunkInput[]): ChunkSize[] {
+  return chunks
+    .map((c) => ({ name: c.name, ...measureChunk(c.buf) }))
+    .sort((a, b) => b.raw - a.raw);
+}
+
+export function totalSizes(chunks: ChunkSize[]): SizeTotals {
+  return chunks.reduce<SizeTotals>(
+    (acc, c) => ({ raw: acc.raw + c.raw, gz: acc.gz + c.gz, br: acc.br + c.br }),
+    { raw: 0, gz: 0, br: 0 },
+  );
+}
+
+/**
+ * Map a source-map `sources` path to its owning bucket. Generic — no hardcoded
+ * app or package names. node_modules → the package (scope-aware); a monorepo
+ * `/packages/<name>/` or `/apps/<name>/` segment → that workspace; else `other`.
+ */
+export function bucketSource(src: string): string {
+  const nm = src.lastIndexOf('node_modules/');
+  if (nm >= 0) {
+    const parts = src.slice(nm + 'node_modules/'.length).split('/');
+    return parts[0].startsWith('@') ? `${parts[0]}/${parts[1]}` : parts[0];
+  }
+  const pkg = src.match(/\/packages\/([^/]+)/);
+  if (pkg) return `APP:packages/${pkg[1]}`;
+  const app = src.match(/\/apps\/([^/]+)/);
+  if (app) return `APP:apps/${app[1]}`;
+  return 'APP:other';
+}
+
+/** Bucket the largest chunk's source bytes by owning package, top N by size. */
+export function composeSourceMap(map: SourceMap, topN = 30): Composition {
+  const sources = map.sources || [];
+  const content = map.sourcesContent || [];
+  const byPkg: Record<string, number> = {};
+  let total = 0;
+  for (let i = 0; i < sources.length; i++) {
+    const src = sources[i] || '';
+    const len = (content[i] || '').length;
+    total += len;
+    const key = bucketSource(src);
+    byPkg[key] = (byPkg[key] || 0) + len;
+  }
+  const top = Object.entries(byPkg)
+    .map(([pkg, bytes]) => ({ pkg, bytes, share: total ? bytes / total : 0 }))
+    .sort((a, b) => b.bytes - a.bytes)
+    .slice(0, topN);
+  return { total, modules: sources.length, top };
+}
+
+const mb = (n: number): string => (n / 1048576).toFixed(2);
+const kb = (n: number): string => (n / 1024).toFixed(0);
+
+/** Render the size + composition report as lines (testable, IO-free). */
+export function formatBundleReport(chunks: ChunkSize[], composition: Composition | null): string[] {
+  const totals = totalSizes(chunks);
+  const lines: string[] = [];
+  lines.push(`CLIENT JS: ${chunks.length} chunk(s)`);
+  lines.push(`  raw    ${mb(totals.raw)} MB`);
+  lines.push(`  gzip   ${mb(totals.gz)} MB`);
+  lines.push(`  brotli ${mb(totals.br)} MB  (CloudFront transfer)`);
+  lines.push('');
+  for (const c of chunks) {
+    lines.push(`  ${kb(c.raw).padStart(7)} KB raw  ${kb(c.gz).padStart(6)} KB gz  ${c.name}`);
+  }
+
+  if (!composition) {
+    lines.push('');
+    lines.push('(no source map for composition — re-export with --source-maps)');
+    return lines;
+  }
+
+  lines.push('');
+  lines.push(
+    `largest chunk: ${mb(composition.total)} MB source / ${composition.modules} modules`,
+  );
+  lines.push('  rank  src-KB   share  package');
+  composition.top.forEach((p, i) => {
+    lines.push(
+      `  ${String(i + 1).padStart(3)}  ${kb(p.bytes).padStart(7)}  ${(p.share * 100)
+        .toFixed(1)
+        .padStart(5)}%  ${p.pkg}`,
+    );
+  });
+  return lines;
+}

package/src/cli/commands/audit.ts

@@ -0,0 +1,118 @@
+/**
+ * `everystack audit --stage <name>` — the capstone. Runs the live deploy-checks
+ * against one stage and emits a combined report + a single exit code (non-zero
+ * if anything failed), so it works as a one-shot CI gate.
+ *
+ * Composes the shared result-producing cores (runBundleAudit, runSecurityProbe)
+ * so there's no orchestration duplication. The white-box `security:audit` and
+ * the heavier `audit:lighthouse` stay separate commands (run them explicitly).
+ */
+
+import { resolveConfig, opsFunction } from '../config.js';
+import { runBundleAudit, runBundleWeightAudit, reportBundleAudit } from './bundle.js';
+import { resolveWeightBudget } from '../bundle-weight.js';
+import { runSecurityProbe, reportProbeResults } from './security-probe.js';
+import { auditDeployedSql, printReport, loadWaivers } from './security.js';
+import { collectLighthouseRuns } from './lighthouse.js';
+import { aggregate, formatLighthouseReport } from '../lighthouse.js';
+import { step, info, fail, success, warn } from '../output.js';
+
+export async function auditCommand(flags: Record<string, string>): Promise<void> {
+  step('Resolving deployed config...');
+  let config;
+  try {
+    config = await resolveConfig(flags.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  const base = (flags.host || config.baseUrl || '').replace(/\/+$/, '');
+  if (!base) {
+    fail('No router URL to audit. Pass --host or ensure the stage has a deployed URL.');
+    process.exit(1);
+  }
+  info(`Region: ${config.region}, URL: ${base}`);
+
+  let failures = 0;
+  const ran: string[] = [];
+
+  // --- security:audit (white-box: SECDEF / exposing-view SQL surface) -------
+  console.log('');
+  info('── security:audit ───────────────────────────────────────────');
+  try {
+    const waivers = await loadWaivers(flags.config);
+    const report = await auditDeployedSql(config.region, opsFunction(config), waivers);
+    console.log('');
+    printReport(report, 'catalog');
+    failures += report.red;
+    ran.push('security:audit');
+  } catch (err: any) {
+    warn(`security:audit skipped: ${err.message}`);
+  }
+
+  // --- security:probe (live RLS/grants introspection + surface probing) ----
+  console.log('');
+  info('── security:probe ───────────────────────────────────────────');
+  try {
+    const results = await runSecurityProbe({
+      region: config.region,
+      opsFn: opsFunction(config),
+      base,
+    });
+    console.log('');
+    failures += reportProbeResults(results);
+    ran.push('security:probe');
+  } catch (err: any) {
+    warn(`security:probe skipped: ${err.message}`);
+  }
+
+  // --- bundle:audit (leak + weight) ----------------------------------------
+  // --dir scans a local export for leaks AND weight (the 180MB gate); without
+  // it, the deployed bundle is scanned for leaks only (weight needs the export).
+  console.log('');
+  info('── bundle:audit ─────────────────────────────────────────────');
+  try {
+    const result = flags.dir
+      ? await runBundleWeightAudit(flags.dir, {
+          budget: resolveWeightBudget(flags),
+          valuesFrom: flags['values-from'],
+        })
+      : await runBundleAudit(base, {
+          valuesFrom: flags['values-from'],
+          weight: !flags['leak-only'],
+          budget: resolveWeightBudget(flags),
+        });
+    console.log('');
+    failures += reportBundleAudit(result);
+    ran.push('bundle:audit (leak + weight)');
+  } catch (err: any) {
+    warn(`bundle:audit skipped: ${err.message}`);
+  }
+
+  // --- audit:lighthouse (perf/SEO) — opt-in; heavy and informational -------
+  if (flags.lighthouse) {
+    console.log('');
+    info('── audit:lighthouse ─────────────────────────────────────────');
+    try {
+      const runs = flags.runs ? parseInt(flags.runs, 10) : 3;
+      const extracts = await collectLighthouseRuns(base + '/', runs);
+      if (extracts.length) {
+        console.log('');
+        console.log(formatLighthouseReport(base + '/', extracts.length, aggregate(extracts)).join('\n'));
+        ran.push('audit:lighthouse (informational)');
+      }
+    } catch (err: any) {
+      warn(`audit:lighthouse skipped: ${err.message}`);
+    }
+  }
+
+  console.log('');
+  const summary = `audit — ${failures} failing check(s) across ${ran.join(' + ') || 'no checks'}`;
+  if (failures > 0) {
+    fail(summary);
+    process.exit(1);
+  }
+  success(summary);
+  if (!flags.lighthouse) info('Add --lighthouse for perf/SEO (slower; informational, does not gate).');
+  process.exit(0);
+}