@progen-labs/spectra 0.1.2 → 0.2.0

package/server/analysis/findings.js

@@ -241,13 +241,17 @@ export function buildFindings(report) {
   const slowFix =
     fw === 'vue'
       ? 'Move expensive work into a computed property, use v-memo/v-once for static subtrees, and virtualise long lists.'
-      : fw === 'react' || fw === 'next'
-        ? 'Move expensive calculations into useMemo, virtualise long lists, and avoid deriving large data structures inside render.'
-        : 'Memoize expensive work, virtualise long lists, and avoid building large data structures during render.';
+      : fw === 'angular'
+        ? 'Avoid heavy work in template expressions and getters — move it to a memoized value or pure pipe — and use ChangeDetectionStrategy.OnPush.'
+        : fw === 'react' || fw === 'next'
+          ? 'Move expensive calculations into useMemo, virtualise long lists, and avoid deriving large data structures inside render.'
+          : 'Memoize expensive work, virtualise long lists, and avoid building large data structures during render.';
   const frequentFix =
     fw === 'vue'
       ? 'Find the reactive dependency that changes this often (a ref/store/timer), narrow it, and use v-memo to skip unchanged subtrees.'
-      : 'Find what updates this often (a timer, a store subscription, a scroll handler) and throttle it or narrow the selector/subscription.';
+      : fw === 'angular'
+        ? 'Reduce change-detection triggers: use OnPush, run timers/listeners with NgZone.runOutsideAngular, and avoid method/getter calls in templates.'
+        : 'Find what updates this often (a timer, a store subscription, a scroll handler) and throttle it or narrow the selector/subscription.';
   if (react.detected && react.hasTimings) {
     react.components
       .filter(c => c.wasted >= 5 && c.wasted / c.renders >= 0.3)

package/server/args.js

@@ -0,0 +1,29 @@
+/**
+ * Tiny argv parser shared by the CLI scripts: `--name value` options, bare
+ * `--flag`s, and positionals. `values` lists the options that take a value, so
+ * their value is never mistaken for a positional.
+ */
+export function parseArgs(argv, { values = [] } = {}) {
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      if (values.includes(a.slice(2))) i++;
+    } else positionals.push(a);
+  }
+  const opt = (name, fallback) => {
+    const i = argv.indexOf(`--${name}`);
+    return i === -1 ? fallback : (argv[i + 1] ?? true);
+  };
+  const flag = name => argv.includes(`--${name}`);
+  return { opt, flag, positionals };
+}
+
+/** A positive integer option, or an Error naming the option. */
+export function intOption(raw, name, { min = 1, max = Infinity, fallback } = {}) {
+  if (raw === undefined) return fallback;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < min || n > max)
+    throw new Error(`--${name} must be a whole number from ${min} to ${max} (got ${raw === true ? 'nothing' : raw}).`);
+  return n;
+}

package/server/cli.js

@@ -1,94 +1,170 @@
 /**
- * Headless / scripted profiling:
+ * Single-page profiling: one or more recordings of one page.
  *
+ *   spectra performance --quick                       # one page-load profile
+ *   spectra performance --quick --runs 5 --json       # median of 5, as JSON
  *   npm run profile -- --url http://localhost:3000/ --mode load
  *   npm run profile -- --url http://localhost:5188/ --duration 8 --throttle 4
  *   npm run profile -- --url ... --scenario ./scenario.mjs   # export default async page => {…}
  *
- * The report is saved in reports/ and can be opened in the UI (npm run dev).
+ * Every run is saved in reports/ and can be opened in the UI (npm run dev).
+ * Several runs are reduced to their median, so one noisy recording can't
+ * decide a number. Budgets from spectra.config.json are checked against it.
  */
-import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import path from 'node:path';
 import { PerfSession, readReport } from './recorder.js';
-import { REPORTS_DIR } from './config.js';
+import { REPORTS_DIR, TARGET_NAME } from './config.js';
+import { intOption, parseArgs } from './args.js';
+import { loadProjectConfig } from './project-config.js';
+import { EXIT, SPECTRA_VERSION, exitAfterFlush, fmt, printBudgets, reportFile, writeResult } from './output.js';
+import { buildProfileResult } from '../shared/result.js';
 
-const args = process.argv.slice(2);
-const opt = (name, fallback) => {
-  const i = args.indexOf(`--${name}`);
-  return i === -1 ? fallback : (args[i + 1] ?? true);
-};
-const flag = name => args.includes(`--${name}`);
+const { opt, flag } = parseArgs(process.argv.slice(2));
 
 const url = opt('url');
 if (!url || flag('help')) {
-  console.log(
-    'usage: npm run profile -- --url <page> [--mode live|load] [--duration seconds] [--throttle 4] [--scenario file.mjs] [--headed] [--save-trace] [--sign-in "http://host/login/?redirect={url}"]',
+  console.error(
+    'usage: npm run profile -- --url <page> [--mode live|load] [--runs n] [--duration seconds] [--throttle 4] [--scenario file.mjs] [--json] [--out file.json] [--config spectra.config.json] [--headed] [--save-trace] [--sign-in "http://host/login/?redirect={url}"]',
   );
-  process.exit(url ? 0 : 1);
+  process.exit(url ? EXIT.OK : EXIT.ERROR);
 }
-const mode = opt('mode', 'live');
-const duration = Number(opt('duration', 8)) * 1000;
+
+const json = flag('json');
+const out = opt('out');
+// In --json mode stdout carries only the result; people still see progress.
+const log = json ? console.error : console.log;
 const sleep = ms => new Promise(r => setTimeout(r, ms));
 
-const session = new PerfSession();
+let mode, runs, duration, cpuThrottle, config, scenario;
 try {
-  await session.connect({
-    mode: 'launch',
-    url,
-    headless: !flag('headed'),
-    signIn: opt('sign-in'),
-  });
-  await sleep(1500);
-  await session.reload(); // make sure the probe was installed before the app loaded
-  await sleep(1000);
-  await session.start({
-    mode,
-    cpuThrottle: Number(opt('throttle', 1)),
-    saveTrace: flag('save-trace'),
+  mode = opt('mode', 'live');
+  if (!['live', 'load'].includes(mode)) throw new Error(`--mode must be live or load (got ${mode}).`);
+  runs = intOption(opt('runs'), 'runs', { max: 25, fallback: 1 });
+  duration = Number(opt('duration', 8)) * 1000;
+  cpuThrottle = Number(opt('throttle', 1));
+  config = loadProjectConfig(opt('config'));
+  const scenarioFile = opt('scenario');
+  if (scenarioFile) scenario = (await import(pathToFileURL(path.resolve(scenarioFile)).href)).default;
+} catch (err) {
+  console.error(`spectra: ${err.message}`);
+  process.exit(EXIT.ERROR);
+}
+
+/** A page-load recording stops itself shortly after the load event. */
+function recordLoad(session, startOpts) {
+  return new Promise((resolve, reject) => {
+    const onReport = r => {
+      cleanup();
+      resolve(readReport(r.id));
+    };
+    const onState = s => {
+      if (s.error) {
+        cleanup();
+        reject(new Error(s.error));
+      }
+    };
+    const cleanup = () => {
+      session.off('report', onReport);
+      session.off('state', onState);
+    };
+    session.on('report', onReport);
+    session.on('state', onState);
+    session.start(startOpts).catch(err => {
+      cleanup();
+      reject(err);
+    });
   });
-  let report;
-  if (mode === 'live') {
-    const scenario = opt('scenario');
-    if (scenario) {
-      const mod = await import(pathToFileURL(path.resolve(scenario)).href);
-      await mod.default(session.page);
-    } else await sleep(duration);
-    report = await session.stop();
+}
+
+async function recordOnce(session, index) {
+  const startOpts = { mode, cpuThrottle, saveTrace: flag('save-trace') };
+  if (mode === 'load') return recordLoad(session, startOpts);
+  // live: every run starts from the same freshly loaded page
+  if (index > 0) {
+    await session.navigate(url, opt('sign-in'));
+    await sleep(800);
+  }
+  await session.start(startOpts);
+  if (scenario) await scenario(session.page);
+  else await sleep(duration);
+  return session.stop();
+}
+
+const lineRef = c => (c.line ? `:${c.lineKind === 'located' ? '≈' : ''}${c.line}` : '');
+
+function printProfile(result, reports) {
+  const rep = reports.find(r => r.id === result.representativeRunId) || reports[0];
+  const s = result.summary;
+  if (reports.length === 1) {
+    log(`\nReport ${rep.id} (${rep.meta.attribution}, ${rep.meta.sampleCount} samples)`);
+    log(
+      `TBT ${fmt('ms', s.tbtMs)} · long tasks ${s.longTaskCount ?? '—'} · CLS ${s.cls ?? '—'} · FCP ${fmt('ms', s.fcpMs)} · LCP ${fmt('ms', s.lcpMs)} · forced layouts ${s.forcedLayoutCount ?? '—'}`,
+    );
   } else {
-    // Page-load recordings stop themselves shortly after the load event.
-    const id = await new Promise((resolve, reject) => {
-      session.once('report', r => resolve(r.id));
-      session.on('state', s => s.error && reject(new Error(s.error)));
-    });
-    report = readReport(id);
+    const range = (key, unit) => {
+      const sp = result.spread[key];
+      return sp && sp.min !== sp.max ? ` (${fmt(unit, sp.min)}–${fmt(unit, sp.max)})` : '';
+    };
+    log(`\n${reports.length} runs — medians:`);
+    log(
+      `TBT ${fmt('ms', s.tbtMs)}${range('tbtMs', 'ms')} · LCP ${fmt('ms', s.lcpMs)}${range('lcpMs', 'ms')} · FCP ${fmt('ms', s.fcpMs)}${range('fcpMs', 'ms')} · CLS ${s.cls ?? '—'} · long tasks ${s.longTaskCount ?? '—'} · forced layouts ${s.forcedLayoutCount ?? '—'}`,
+    );
+    result.runs.forEach((r, i) =>
+      log(`  run ${i + 1}  ${r.id}  TBT ${fmt('ms', r.summary.tbtMs)} · LCP ${fmt('ms', r.summary.lcpMs)} · scripting ${fmt('ms', r.summary.scriptingMs)}`),
+    );
   }
-  console.log(
-    `\nReport ${report.id} (${report.meta.attribution}, ${report.meta.sampleCount} samples)`,
+  log(
+    reports.length > 1
+      ? `\nCulprits (from ${rep.id}, the most typical run):`
+      : '\nCulprits:',
   );
-  console.log(
-    `TBT ${report.vitals.tbtMs}ms · long tasks ${report.vitals.longTaskCount} · CLS ${report.vitals.cls} · FCP ${report.vitals.fcpMs}ms · LCP ${report.vitals.lcpMs}ms · forced layouts ${report.totals.forcedLayoutCount}`,
-  );
-  console.log('\nCulprits:');
-  for (const f of report.findings.slice(0, 15)) {
-    console.log(` [${f.severity}] (${f.category}) ${f.title}`);
-    for (const c of f.culprits) {
-      const line = c.line
-        ? `:${c.lineKind === 'located' ? '≈' : ''}${c.line}`
-        : '';
-      console.log(
-        `      ↳ ${c.fn}()  ${c.file || 'unknown'}${line}${c.ms ? `  ${c.ms}ms` : ''}${c.note ? `  (${c.note})` : ''}`,
-      );
-    }
+  for (const f of result.findings.slice(0, 15)) {
+    const seen = f.seenIn != null ? `  [seen in ${f.seenIn}/${reports.length} runs]` : '';
+    log(` [${f.severity}] (${f.category}) ${f.title}${seen}`);
+    for (const c of f.culprits)
+      log(`      ↳ ${c.fn}()  ${c.file || 'unknown'}${lineRef(c)}${c.ms ? `  ${c.ms}ms` : ''}${c.note ? `  (${c.note})` : ''}`);
+  }
+}
+
+const session = new PerfSession();
+const reports = [];
+let code = EXIT.OK;
+try {
+  await session.connect({ mode: 'launch', url, headless: !flag('headed'), signIn: opt('sign-in') });
+  await sleep(1500);
+  await session.reload(); // make sure the probe was installed before the app loaded
+  await sleep(1000);
+  for (let i = 0; i < runs; i++) {
+    if (runs > 1) console.error(`spectra: run ${i + 1}/${runs} …`);
+    reports.push(await recordOnce(session, i));
+    if (i < runs - 1) await sleep(500);
   }
+} catch (err) {
+  console.error(`spectra: ${err.message}`);
+  code = EXIT.ERROR;
+} finally {
+  await session.disconnect();
+}
+
+if (code === EXIT.OK) {
+  const result = buildProfileResult({
+    reports,
+    fileOf: reportFile,
+    target: TARGET_NAME,
+    spectraVersion: SPECTRA_VERSION,
+    budgets: config.budgets,
+  });
+  printProfile(result, reports);
+  printBudgets(result.budgets, log);
+  if (result.budgets && !result.budgets.ok) code = EXIT.CHECKS_FAILED;
+  writeResult(result, { json, out });
+
   // When launched by the installed CLI the bin sets PERF_REPORTS_DIR; in a dev
   // checkout it is unset. Tailor the "how to view it" hint to each.
   const installed = !!process.env.PERF_REPORTS_DIR;
-  console.log(
-    `\nSaved ${path.join(REPORTS_DIR, report.id)}.json — view it with: ${
-      installed ? 'spectra dashboard' : 'npm run dev'
-    }`,
-  );
-} finally {
-  await session.disconnect();
+  const saved = reports.length === 1 ? `${reportFile(reports[0].id)}` : `${reports.length} reports in ${REPORTS_DIR}`;
+  log(`\nSaved ${saved} — view with: ${installed ? 'spectra dashboard' : 'npm run dev'}`);
+  if (out) log(`Result written to ${path.resolve(out)}`);
 }
-process.exit(0);
+exitAfterFlush(code);

package/server/compare-cli.js

@@ -0,0 +1,126 @@
+/**
+ * spectra compare <before> <after> [--json] [--out file.json] [--fail-on-regression]
+ *
+ * Each side is any of:
+ *   - a report id from .spectra/reports        20261017T101500-load
+ *   - a report file                            ./perf_3fa516c_load.json
+ *   - a result file from `spectra performance --out` (all of its runs)
+ *   - several of the above joined by commas    id1,id2,id3
+ *
+ * Several runs per side are reduced to their median and a change only counts
+ * when it is bigger than the noise between runs (shared/compare.js).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readReport } from './recorder.js';
+import { REPORTS_DIR } from './config.js';
+import { parseArgs } from './args.js';
+import { EXIT, SPECTRA_VERSION, exitAfterFlush, writeResult } from './output.js';
+import { buildCompareResult, isRegression } from '../shared/result.js';
+import { validateReport } from '../shared/snapshot.js';
+import { formatPct, formatValue } from '../shared/compare.js';
+
+const { opt, flag, positionals } = parseArgs(process.argv.slice(2), { values: ['out'] });
+const json = flag('json');
+const out = opt('out');
+const log = json ? console.error : console.log;
+
+if (flag('help') || positionals.length !== 2) {
+  console.error('usage: spectra compare <before> <after> [--json] [--out file.json] [--fail-on-regression]');
+  console.error('  each side: a report id, a report file, a `spectra performance --out` result file, or id1,id2,…');
+  process.exit(flag('help') ? EXIT.OK : EXIT.ERROR);
+}
+
+const readJson = file => {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    throw new Error(`${file} is not valid JSON (${err.message}).`);
+  }
+};
+
+/** The runs a result file points at: its recorded path, the reports dir, or next to the result. */
+function loadRun(run, dir) {
+  const candidates = [run.file, path.join(REPORTS_DIR, `${run.id}.json`), path.join(dir, `${run.id}.json`)];
+  const found = candidates.find(f => f && fs.existsSync(f));
+  if (!found) throw new Error(`report ${run.id} (listed in the result file) was not found; it was saved to ${run.file}.`);
+  return readJson(found);
+}
+
+function loadToken(token) {
+  const file = path.resolve(token);
+  if (fs.existsSync(file) || token.endsWith('.json')) {
+    if (!fs.existsSync(file)) throw new Error(`no such file: ${file}`);
+    const obj = readJson(file);
+    if (obj?.schemaVersion && obj.kind === 'profile') return obj.runs.map(run => loadRun(run, path.dirname(file)));
+    if (obj?.kind === 'evaluation')
+      throw new Error(
+        `${token} is a golden-path evaluation. Compare single-page profiles instead: run "spectra performance --quick --runs 5 --out before.json" (and again for after), or compare two journey reports by id.`,
+      );
+    if (obj?.kind) throw new Error(`${token} is a "${obj.kind}" result, not a profile.`);
+    const valid = validateReport(obj);
+    if (!valid.ok) throw new Error(`${token}: ${valid.reason}`);
+    return [obj];
+  }
+  const report = readReport(token);
+  if (!report) throw new Error(`no report "${token}" in ${REPORTS_DIR}. List them with: spectra reports`);
+  return [report];
+}
+
+const loadSide = arg =>
+  arg
+    .split(',')
+    .map(t => t.trim())
+    .filter(Boolean)
+    .flatMap(loadToken);
+
+let result;
+try {
+  const before = loadSide(positionals[0]);
+  const after = loadSide(positionals[1]);
+  result = buildCompareResult({ before, after, spectraVersion: SPECTRA_VERSION });
+  if (!result) throw new Error('nothing to compare.');
+} catch (err) {
+  console.error(`spectra: ${err.message}`);
+  process.exit(EXIT.ERROR);
+}
+
+const VERDICT = {
+  improved: 'IMPROVED',
+  regressed: 'REGRESSED',
+  mixed: 'MIXED (some better, some worse)',
+  neutral: 'NO SIGNIFICANT CHANGE',
+};
+const sideLine = side => {
+  const commit = side.git?.shortHash || side.runs.find(r => r.commit)?.commit;
+  return `${side.runs.length} run${side.runs.length === 1 ? '' : 's'}${commit ? ` · commit ${commit}` : ''}${side.label ? ` · ${side.label}` : ''}`;
+};
+
+const c = result.comparison;
+log(`\nSpectra compare — ${VERDICT[c.verdict] || c.verdict} (confidence: ${c.confidence})`);
+log(`Before: ${sideLine(c.before)}`);
+log(`After:  ${sideLine(c.after)}`);
+if (c.headlines.length) {
+  log('');
+  for (const h of c.headlines) log(`  ${h.kind === 'improved' ? '✓' : '✗'} ${h.text}`);
+}
+log(`\n${'Key metric'.padEnd(28)}${'Before'.padStart(11)}${'After'.padStart(11)}${'Change'.padStart(9)}  Verdict`);
+for (const m of c.metrics.filter(x => x.key)) {
+  log(
+    `${m.label.padEnd(28)}${formatValue(m.unit, m.before.value).padStart(11)}${formatValue(m.unit, m.after.value).padStart(11)}${(m.verdict === 'n/a' ? '' : formatPct(m.pct)).padStart(9)}  ${m.verdict}`,
+  );
+}
+log(`(${c.counts.improved} improved · ${c.counts.degraded} worse · ${c.counts.same} within noise across all ${c.metrics.length} metrics)`);
+const { added, resolved, persisting } = c.findings;
+log(`\nFindings: ${resolved.length} resolved · ${added.length} new · ${persisting.length} still present`);
+for (const f of resolved.slice(0, 8)) log(`  resolved  [${f.severity}] ${f.title}`);
+for (const f of added.slice(0, 8)) log(`  new       [${f.severity}] ${f.title}`);
+const concerns = c.checks.filter(x => x.level === 'warn' || x.level === 'bad');
+if (concerns.length) {
+  log('\nComparability:');
+  for (const x of concerns) log(`  ! ${x.title}${x.detail ? ` — ${x.detail}` : ''}`);
+}
+
+writeResult(result, { json, out });
+if (out) log(`\nResult written to ${path.resolve(out)}`);
+exitAfterFlush(flag('fail-on-regression') && isRegression(result) ? EXIT.CHECKS_FAILED : EXIT.OK);

package/server/explore/evaluate-cli.js

@@ -2,59 +2,73 @@
  * CLI wrapper for the evaluation orchestrator — the default action of
  * `spectra performance`. Runs the golden-path suite against --url, prints the
  * performance matrix, and saves an aggregate report alongside the per-path
- * reports (all openable in the dashboard).
+ * reports (all openable in the dashboard). With --json / --out it also emits
+ * the machine-readable result, and budgets from spectra.config.json are
+ * checked against every journey.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { runEvaluation } from './evaluate.js';
+import { readReport } from '../recorder.js';
 import { REPORTS_DIR, TARGET_NAME } from '../config.js';
+import { parseArgs } from '../args.js';
+import { loadProjectConfig } from '../project-config.js';
+import { EXIT, SPECTRA_VERSION, exitAfterFlush, printBudgets, reportFile, writeResult } from '../output.js';
+import { buildEvaluationResult } from '../../shared/result.js';
 
-const args = process.argv.slice(2);
-const opt = (name, fallback) => {
-  const i = args.indexOf(`--${name}`);
-  return i === -1 ? fallback : args[i + 1] ?? true;
-};
-const flag = name => args.includes(`--${name}`);
+const { opt, flag } = parseArgs(process.argv.slice(2));
 
 const url = opt('url');
 if (!url) {
   console.error('spectra: evaluate requires --url');
-  process.exit(1);
+  process.exit(EXIT.ERROR);
+}
+const json = flag('json');
+const out = opt('out');
+// In --json mode stdout carries only the result; people still see the matrix.
+const log = json ? console.error : console.log;
+
+let config;
+try {
+  config = loadProjectConfig(opt('config'));
+} catch (err) {
+  console.error(`spectra: ${err.message}`);
+  process.exit(EXIT.ERROR);
 }
 
 const pad = (s, n) => String(s ?? '').padEnd(n).slice(0, n);
 const padL = (s, n) => String(s ?? '').padStart(n);
-const ms = v => (v == null ? '—' : `${v}ms`);
+const ms = v => (v == null ? '—' : `${Math.round(v)}ms`);
 
 function printMatrix(result) {
   const rows = [result.baseline, ...result.paths];
-  console.log(`\n${'═'.repeat(78)}`);
-  console.log(`Spectra performance evaluation — ${result.target}`);
-  console.log(`${result.url}`);
-  console.log(
+  log(`\n${'═'.repeat(78)}`);
+  log(`Spectra performance evaluation — ${result.target}`);
+  log(`${result.url}`);
+  log(
     `${result.discovered} actionable elements · ${result.paths.length} golden paths · ` +
       `${result.skippedDestructive.length} destructive skipped (safe mode)`,
   );
-  console.log('═'.repeat(78));
-  console.log(
+  log('═'.repeat(78));
+  log(
     `${pad('#', 3)}${pad('Golden path', 34)}${pad('Result', 8)}${padL('TBT', 7)}${padL('LCP', 8)}${padL('LongT', 7)}  Top finding`,
   );
-  console.log('─'.repeat(78));
+  log('─'.repeat(78));
   rows.forEach((r, i) => {
     const num = i === 0 ? '·' : String(i);
     const status = r.ok ? 'PASS' : 'FAIL';
     const s = r.summary || {};
     const top = s.topFinding ? `[${s.topFinding.severity}] ${s.topFinding.title}` : '—';
-    console.log(
+    log(
       `${pad(num, 3)}${pad(r.title, 34)}${pad(status, 8)}${padL(ms(s.tbtMs), 7)}${padL(ms(s.lcpMs), 8)}${padL(s.longTaskCount ?? '—', 7)}  ${top.slice(0, 40)}`,
     );
-    if (!r.ok && r.error) console.log(`      ↳ ${r.error}`);
+    if (!r.ok && r.error) log(`      ↳ ${r.error}`);
   });
-  console.log('─'.repeat(78));
+  log('─'.repeat(78));
   const passed = result.paths.filter(p => p.ok).length;
-  console.log(`Automation: ${passed}/${result.paths.length} golden paths passed.`);
+  log(`Automation: ${passed}/${result.paths.length} golden paths passed.`);
   if (result.skippedDestructive.length) {
-    console.log(
+    log(
       `Skipped (safe mode): ${result.skippedDestructive.map(s => s.name).join(', ')}`,
     );
   }
@@ -66,22 +80,28 @@ function stamp() {
   return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}T${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
 }
 
-const result = await runEvaluation({
-  url,
-  headless: !flag('headed'),
-  limit: Number(opt('paths', 12)),
-  signIn: opt('sign-in'),
-  onProgress: ev => {
-    if (ev.phase === 'baseline') console.error('spectra: recording baseline page load …');
-    else if (ev.phase === 'discover') console.error('spectra: discovering actionable elements …');
-    else if (ev.phase === 'synthesized')
-      console.error(
-        `spectra: ${ev.discovered} actionable elements (${ev.skipped} destructive skipped) → ${ev.paths} golden paths`,
-      );
-    else if (ev.phase === 'path')
-      console.error(`spectra: [${ev.index}/${ev.total}] ${ev.title}`);
-  },
-});
+let result;
+try {
+  result = await runEvaluation({
+    url,
+    headless: !flag('headed'),
+    limit: Number(opt('paths', 12)),
+    signIn: opt('sign-in'),
+    onProgress: ev => {
+      if (ev.phase === 'baseline') console.error('spectra: recording baseline page load …');
+      else if (ev.phase === 'discover') console.error('spectra: discovering actionable elements …');
+      else if (ev.phase === 'synthesized')
+        console.error(
+          `spectra: ${ev.discovered} actionable elements (${ev.skipped} destructive skipped) → ${ev.paths} golden paths`,
+        );
+      else if (ev.phase === 'path')
+        console.error(`spectra: [${ev.index}/${ev.total}] ${ev.title}`);
+    },
+  });
+} catch (err) {
+  console.error(`spectra: ${err.message}`);
+  process.exit(EXIT.ERROR);
+}
 
 printMatrix(result);
 
@@ -93,9 +113,21 @@ fs.writeFileSync(
   JSON.stringify({ id, kind: 'evaluation', createdAt: Date.now(), target: TARGET_NAME, ...result }, null, 2),
 );
 
+const evaluation = buildEvaluationResult({
+  evaluation: result,
+  readReport,
+  fileOf: reportFile,
+  file,
+  spectraVersion: SPECTRA_VERSION,
+  budgets: config.budgets,
+});
+printBudgets(evaluation.budgets, log);
+writeResult(evaluation, { json, out });
+
 const installed = !!process.env.PERF_REPORTS_DIR;
-console.log(`\nSaved ${file}`);
-console.log(
+log(`\nSaved ${file}`);
+log(
   `Per-path reports are in ${REPORTS_DIR} — view them with: ${installed ? 'spectra dashboard' : 'npm run dev'}`,
 );
-process.exit(0);
+if (out) log(`Result written to ${path.resolve(out)}`);
+exitAfterFlush(evaluation.budgets && !evaluation.budgets.ok ? EXIT.CHECKS_FAILED : EXIT.OK);

package/server/output.js

@@ -0,0 +1,50 @@
+/**
+ * Shared output plumbing for the CLI scripts. In --json mode stdout carries
+ * nothing but the result document, so it can be piped (`| jq`, an editor, an
+ * agent); every human-readable line goes to stderr instead.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { REPORTS_DIR, TOOL_ROOT } from './config.js';
+import { formatValue } from '../shared/compare.js';
+
+export const SPECTRA_VERSION = JSON.parse(
+  fs.readFileSync(path.join(TOOL_ROOT, 'package.json'), 'utf8'),
+).version;
+
+/** 0 = done, 1 = could not run, 2 = ran, but a budget or a compare failed. */
+export const EXIT = { OK: 0, ERROR: 1, CHECKS_FAILED: 2 };
+
+export const reportFile = id => path.join(REPORTS_DIR, `${id}.json`);
+
+/** Writes the result to --out and/or stdout (--json). */
+export function writeResult(result, { json, out }) {
+  if (out) {
+    fs.mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
+    fs.writeFileSync(out, `${JSON.stringify(result, null, 2)}\n`);
+  }
+  if (json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+/**
+ * process.exit() can cut a piped stdout short (pipes are asynchronous on
+ * macOS), so exit only once everything written so far has been flushed.
+ */
+export function exitAfterFlush(code) {
+  process.stdout.write('', () => process.exit(code));
+}
+
+const unitOf = unit => (unit === 'KB' ? 'bytes' : unit === 'count' ? 'count' : unit);
+export const fmt = (unit, v) =>
+  v == null ? '—' : formatValue(unitOf(unit), unit === 'KB' ? v * 1024 : v);
+
+export function printBudgets(budgets, log) {
+  if (!budgets) return;
+  log(`\nBudgets: ${budgets.ok ? 'all within budget' : `${budgets.failed} over budget`}`);
+  for (const c of budgets.checks) {
+    const mark = c.status === 'pass' ? '✓' : c.status === 'fail' ? '✗' : '–';
+    const where = c.where && c.where !== 'median' ? `  (${c.where})` : '';
+    const value = c.status === 'skipped' ? 'not measured' : fmt(c.unit, c.value);
+    log(`  ${mark} ${c.label.padEnd(26)} ${value.padStart(12)}  limit ${fmt(c.unit, c.limit)}${where}`);
+  }
+}