@progen-labs/spectra 0.2.0 → 0.4.0

package/README.md

@@ -14,6 +14,8 @@ and per-component render/change-detection time; source files too, where the fram
 functions. A [Progen Labs](https://github.com/progen-labs) project — open source, non-profit, no
 telemetry, no account required.
 
+**Watch the two-minute demo:** [progen-labs.github.io/website/#spectra/demo](https://progen-labs.github.io/website/#spectra/demo).
+
 **Documentation:** the full guide, with annotated screenshots of every screen, is at
 [progen-labs.github.io/website](https://progen-labs.github.io/website/#spectra/docs/introduction).
 
@@ -70,6 +72,7 @@ spectra performance [options]            Golden-path evaluation (default)
 spectra performance --quick              One page-load profile (about 15 s)
 spectra compare <before> <after>         Did it get faster? Noise-aware before/after
 spectra reports                          List saved reports
+spectra mcp [--project <dir>]            MCP server for AI tools (stdio)
 spectra dashboard [--port N] [--open]    Open the dashboard UI
 spectra --help                           Full option list
 spectra --version
@@ -141,6 +144,37 @@ Exit codes make it a CI gate:
 | `1` | Could not run (no Chrome, server down, bad config) |
 | `2` | Ran, but a budget was exceeded, or `compare --fail-on-regression` found a regression |
 
+### GitHub Action
+
+The repository is also a GitHub Action. On every pull request it profiles the change and its base commit on the
+same runner, compares them beyond run-to-run noise, enforces your budgets, and writes the result to the job summary
+and (optionally) a PR comment:
+
+```yaml
+name: Performance
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write   # only for comment: true
+jobs:
+  spectra:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npm ci
+      - uses: progen-labs/spectra@v1
+        with:
+          compare-to-base: true
+          fail-on-regression: true
+          comment: true
+```
+
+Inputs include `url`, `command`, `mode` (`quick` or `golden-paths`), `runs`, `config`, `fail-on-budget` and
+`working-directory`; outputs are `result-file`, `verdict`, `over-budget` and `summary-file`. Full reports are
+uploaded as an artifact. See the [Action guide](https://progen-labs.github.io/website/#spectra/docs/github-action).
+
 ## Machine-readable output
 
 `--json` prints a small, versioned result on stdout and sends every human-readable line to stderr, so it can
@@ -150,6 +184,84 @@ Findings carry the file, line, cost in ms and a suggested fix. The format is des
 shipped with the package (`schema/result.schema.json`); additive changes keep `schemaVersion`, breaking
 changes bump it. Saved reports carry their own `schemaVersion` too.
 
+## Use it from your AI assistant
+
+Spectra is an [MCP](https://modelcontextprotocol.io) server too, so an AI coding assistant can profile a page,
+fix what it finds, and prove each fix with before/after measurements.
+
+**Claude Code**, with the plugin (adds an *improve-performance* skill and `/spectra:audit`):
+
+```
+/plugin marketplace add progen-labs/spectra
+/plugin install spectra@progen-labs
+```
+
+**Any MCP client** (Claude Code without the plugin, Claude Desktop, Cursor, VS Code, Windsurf…): run
+`npx -y @progen-labs/spectra mcp` as a stdio server (Spectra 0.3.0 or later). For example:
+
+```bash
+claude mcp add spectra -- npx -y @progen-labs/spectra mcp
+```
+
+```json
+{ "mcpServers": { "spectra": { "command": "npx", "args": ["-y", "@progen-labs/spectra", "mcp", "--project", "/path/to/your/app"] } } }
+```
+
+Tools: `profile_page`, `verify_change` (re-profile and compare against a baseline), `compare_profiles`,
+`run_golden_paths`, `list_reports` and `get_report`. The server profiles pages on this machine only (start it with
+`--allow-remote` to lift that), runs one browser at a time, and stops Chrome and any dev server it started when a
+call is cancelled. See the [MCP guide](https://progen-labs.github.io/website/#spectra/docs/mcp-server).
+
+## The AI fix harness
+
+`spectra fix` hands the costliest findings in your own code to a coding agent, one at a time, and keeps a change only
+when your checks still pass and Spectra measures the page faster beyond run-to-run noise. Kept changes arrive as
+commits on a new branch, `spectra/fix-<time>`, for you to review; everything else is undone.
+
+```bash
+npx spectra fix                       # Claude Code (signed in) fixes up to 3 findings
+npx spectra fix --check "npm run e2e" --max-fixes 5
+npx spectra fix --agent "./my-agent.sh"   # any agent: instructions on stdin
+```
+
+The harness, not the agent, makes every decision:
+
+- **Isolation.** It works in a git worktree of your last commit, with its own dev server. Your working tree is never
+  touched, and nothing is pushed or merged.
+- **Your checks first.** Your test, type-check and build scripts (or `--check`, which can test the running app at
+  `$SPECTRA_FIX_URL`) must pass before any change and after each one. A faster page that breaks is undone.
+- **Scope rules.** A change may not touch `package.json`, lockfiles, configuration, tests or CI, delete files, or
+  exceed 150 lines.
+- **Proof.** The change is kept only if `spectra compare` says *improved* with medium or high confidence and no new
+  critical finding; with low confidence it measures again.
+- **A record.** Each kept commit carries its evidence; `.spectra/fix/<time>/report.md` summarises the session, and a
+  history skips findings that failed before.
+
+By default the agent is Claude Code in headless mode, allowed only to read and edit files (no shell, no web, no MCP),
+with a spending cap per finding. A test bench (`npm run bench`) checks the harness's decisions in CI: a real fix is
+kept, a "faster" change that breaks the page is caught, a cosmetic change doesn't count, and an edit to
+`package.json` is refused. See [the AI fix harness](https://progen-labs.github.io/website/#spectra/docs/harness).
+
+## In VS Code
+
+The Spectra extension (`vscode/`) puts results where you work: every finding in the **Problems panel** at the file
+and line responsible, **CodeLens** above the costliest components and functions
+(`⚡ Spectra: Row · 7,200 renders · 1.44 s rendering`), headline numbers in the **status bar**, **Verify against
+baseline** after a change, golden paths, and the dashboard inside the editor. Results that the CLI or an AI
+assistant writes to `.spectra/results` appear automatically, and on VS Code 1.101+ it offers Spectra's MCP server to
+agent mode. It runs your project's Spectra (0.2.0 or later) or `npx`.
+
+Install **Spectra — frontend performance** from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=progen-labs.spectra-performance), or from a terminal:
+
+```bash
+code --install-extension progen-labs.spectra-performance
+```
+
+For Cursor, Windsurf or VSCodium (Open VSX), until it is listed there: `cd vscode && npx @vscode/vsce package
+--no-dependencies`, then install `spectra-performance-0.1.0.vsix` with **Extensions: Install from VSIX…**.
+
+See the [VS Code guide](https://progen-labs.github.io/website/#spectra/docs/vscode).
+
 ## Safe by default
 
 Auto-exploration never triggers destructive actions. Spectra detects controls that would mutate state —
@@ -178,7 +290,8 @@ and report generation work.
   [Quick start](https://progen-labs.github.io/website/#spectra/docs/quick-start),
   [Compare before and after](https://progen-labs.github.io/website/#spectra/docs/compare),
   [Budgets and CI](https://progen-labs.github.io/website/#spectra/docs/budgets),
-  [JSON output](https://progen-labs.github.io/website/#spectra/docs/json-output), the
+  [JSON output](https://progen-labs.github.io/website/#spectra/docs/json-output),
+  [Claude Code](https://progen-labs.github.io/website/#spectra/docs/claude-code), the
   [Findings reference](https://progen-labs.github.io/website/#spectra/docs/findings) and
   [Troubleshooting](https://progen-labs.github.io/website/#spectra/docs/troubleshooting).
 - **[DOCS.md](DOCS.md)**: the in-repo manual, the technical deep dive, and how to contribute.

package/bin/spectra.js

@@ -5,6 +5,8 @@
  *   spectra performance [--url <page>] [profiler options]   profile a frontend
  *   spectra compare <before> <after>                         before vs after, noise-aware
  *   spectra reports                                          list saved reports
+ *   spectra mcp [--project <dir>]                            MCP server for AI tools (stdio)
+ *   spectra fix [options]                                    the AI fix harness: fix, check, verify
  *   spectra dashboard                                        open the dashboard UI
  *   spectra --help                                           show this help
  *   spectra --version                                        print the version
@@ -39,6 +41,13 @@ Usage:
                                   Compare two profiles; a change counts only when
                                   it is bigger than the noise between runs
   spectra reports [--json]        List saved reports (ids for compare / dashboard)
+  spectra mcp [--project <dir>] [--allow-remote]
+                                  Run as an MCP server (stdio) for Claude Code,
+                                  Cursor, VS Code and other AI tools
+  spectra fix [options]           The AI fix harness: an agent fixes the costliest
+                                  findings in a copy of your code; a change is kept
+                                  only if your checks pass and it measures faster
+                                  (spectra fix --help for its options)
   spectra dashboard               Open the Spectra dashboard UI
   spectra --help, -h              Show this help
   spectra --version, -v           Print the version
@@ -91,9 +100,26 @@ Examples:
   spectra performance --quick --runs 5 --out before.json
   spectra performance --quick --runs 5 --out after.json
   spectra compare before.json after.json           # did the change help?
+  spectra fix --max-fixes 3                        # let an agent fix them, verified
   spectra performance --json | jq .summary         # pipe it anywhere
 `;
 
+// What a terminate signal must clean up: the running script and a dev server
+// Spectra started. Without this, stopping Spectra from outside (an editor or
+// an AI client cancelling a run) would leave the dev server running.
+const active = { child: null, server: null };
+let stopping = false;
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => {
+    if (stopping) return;
+    stopping = true;
+    active.child?.kill(signal);
+    Promise.resolve(active.server?.stop())
+      .catch(() => {})
+      .finally(() => process.exit(signal === 'SIGINT' ? 130 : 143));
+  });
+}
+
 function runNodeAsync(scriptRelPath, args, extraEnv = {}) {
   return new Promise((resolve, reject) => {
     const child = spawn(
@@ -105,7 +131,11 @@ function runNodeAsync(scriptRelPath, args, extraEnv = {}) {
         env: { ...process.env, ...extraEnv },
       },
     );
-    child.on('exit', code => resolve(code ?? 0));
+    active.child = child;
+    child.on('exit', code => {
+      if (active.child === child) active.child = null;
+      resolve(code ?? 0);
+    });
     child.on('error', reject);
   });
 }
@@ -189,11 +219,10 @@ async function runProfile() {
   const { value: command, rest: afterCmd } = takeOption(args, 'command');
   const { value: bootTimeout, rest: profileArgs } = takeOption(afterCmd, 'boot-timeout');
   const fw = detectFramework(cwd);
-  const label =
-    fw.framework !== 'unknown' ? `${fw.framework}/${fw.bundler}` : fw.bundler;
+  const label = [fw.framework, fw.bundler].filter(x => x && x !== 'unknown').join('/');
   // Status goes to stderr so it never mixes with the report on stdout.
   console.error(
-    `spectra: no --url given — starting the ${label} dev server in ${cwd} …`,
+    `spectra: no --url given — starting the ${label ? `${label} ` : ''}dev server in ${cwd} …`,
   );
 
   let server;
@@ -207,6 +236,7 @@ async function runProfile() {
     console.error(`spectra: ${err.message}`);
     return 1;
   }
+  active.server = server;
   console.error(`spectra: dev server ready at ${server.url} — profiling …\n`);
 
   let code = 1;
@@ -217,6 +247,7 @@ async function runProfile() {
       env,
     );
   } finally {
+    active.server = null;
     await server.stop();
     console.error('\nspectra: stopped the dev server.');
   }
@@ -246,6 +277,7 @@ function runDashboard() {
       env: { ...process.env, ...projectEnv() },
     },
   );
+  active.child = child;
   child.on('exit', code => process.exit(code ?? 0));
   child.on('error', err => {
     console.error(`spectra: failed to start the dashboard — ${err.message}`);
@@ -274,6 +306,23 @@ switch (command) {
       });
     break;
   }
+  case 'fix':
+    // In-process, in the user's project: the harness manages its own copy,
+    // dev server and child processes (server/fix/cli.js).
+    import('../server/fix/cli.js').catch(err => {
+      console.error(`spectra: ${err.message}`);
+      process.exit(1);
+    });
+    break;
+  case 'mcp':
+    // In-process: stdin/stdout are the protocol channel, and the working
+    // directory stays the user's (the project, unless --project or the
+    // client's roots say otherwise).
+    import('../server/mcp.js').catch(err => {
+      console.error(`spectra: ${err.message}`);
+      process.exit(1);
+    });
+    break;
   case 'dashboard':
   case 'ui':
     runDashboard();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@progen-labs/spectra",
-  "version": "0.2.0",
-  "description": "Spectra — a Chrome DevTools Protocol profiler that identifies the files, functions and components causing frontend slowness, across React, Vue, Svelte, Angular and Next.js builds.",
+  "version": "0.4.0",
+  "description": "Spectra \u2014 a Chrome DevTools Protocol profiler that identifies the files, functions and components causing frontend slowness, across React, Vue, Svelte, Angular and Next.js builds.",
   "type": "module",
   "bin": {
     "spectra": "bin/spectra.js"
@@ -32,7 +32,9 @@
     "prepack": "npm run build",
     "demo": "vite --config fixtures/demo-app/vite.config.js",
     "profile": "node server/cli.js",
-    "test": "node --test \"server/**/test-*.js\""
+    "test": "node --test \"server/**/test-*.js\" \"action/test-*.js\"",
+    "test:vscode": "npm --prefix vscode test",
+    "bench": "node bench/run.mjs"
   },
   "engines": {
     "node": ">=18"
@@ -51,7 +53,11 @@
     "angular",
     "nextjs",
     "spectra",
-    "progen-labs"
+    "progen-labs",
+    "mcp",
+    "mcp-server",
+    "claude-code",
+    "ai"
   ],
   "author": "Progen Labs (Sourav Debnath)",
   "license": "MIT",
@@ -71,6 +77,7 @@
     "puppeteer-core": "^25.13.0"
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@vitejs/plugin-react": "^6.1.2",
     "d3": "^7.9.0",
     "highlight.js": "^11.10.0",

package/server/fix/agent.js

@@ -0,0 +1,96 @@
+/**
+ * The coding agent `spectra fix` hands one finding to. By default it is Claude
+ * Code in headless mode, allowed only to read and edit files: no shell, no
+ * web, no MCP servers. Any other agent works through --agent "<command>": it
+ * gets the instructions on stdin (and in $SPECTRA_FIX_PROMPT_FILE) and runs in
+ * the copy of the project.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const run = (cmd, args, { cwd, input, env, signal, timeoutMs, shell = false }) =>
+  new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd, env: { ...process.env, ...env }, stdio: ['pipe', 'pipe', 'pipe'], shell });
+    let out = '';
+    let err = '';
+    child.stdout.on('data', d => (out += d));
+    child.stderr.on('data', d => (err += d));
+    const timer = setTimeout(() => child.kill('SIGTERM'), timeoutMs);
+    const abort = () => child.kill('SIGTERM');
+    signal?.addEventListener('abort', abort, { once: true });
+    child.on('error', e => {
+      clearTimeout(timer);
+      reject(e.code === 'ENOENT' ? new Error(`${cmd} was not found`) : e);
+    });
+    child.on('close', code => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', abort);
+      resolve({ code, out, err });
+    });
+    child.stdin.end(input ?? '');
+  });
+
+/** Claude Code, headless. */
+export function claudeAgent({ bin = process.env.SPECTRA_CLAUDE || 'claude', model, budgetUsd = 2, timeoutMs = 10 * 60_000 } = {}) {
+  return {
+    name: `Claude Code${model ? ` (${model})` : ''}`,
+    async run(prompt, { cwd, signal }) {
+      const args = [
+        '-p',
+        prompt,
+        '--output-format',
+        'json',
+        '--permission-mode',
+        'acceptEdits',
+        '--allowedTools',
+        'Read Edit Write Glob Grep',
+        '--disallowedTools',
+        'Bash WebFetch WebSearch',
+        '--strict-mcp-config',
+        '--no-session-persistence',
+        '--max-budget-usd',
+        String(budgetUsd),
+        ...(model ? ['--model', model] : []),
+      ];
+      let res;
+      try {
+        res = await run(bin, args, { cwd, signal, timeoutMs });
+      } catch (err) {
+        throw new Error(`could not start Claude Code (${err.message}). Install it (https://claude.com/claude-code), set SPECTRA_CLAUDE to its path, or pass --agent "<command>".`);
+      }
+      let parsed = null;
+      try {
+        parsed = JSON.parse(res.out.trim().split('\n').pop());
+      } catch {
+        /* not JSON */
+      }
+      if (res.code !== 0 && !parsed) throw new Error(`Claude Code exited with code ${res.code}: ${(res.err || res.out).trim().split('\n').slice(-3).join(' ')}`);
+      return {
+        summary: String(parsed?.result ?? res.out).trim().split('\n').filter(Boolean).pop()?.slice(0, 300) || '',
+        costUsd: parsed?.total_cost_usd ?? null,
+        turns: parsed?.num_turns ?? null,
+        error: parsed?.is_error ? String(parsed.result || 'agent error') : null,
+      };
+    },
+  };
+}
+
+/** Any agent, as a shell command run in the copy of the project. */
+export function commandAgent(command, { timeoutMs = 10 * 60_000 } = {}) {
+  return {
+    name: command,
+    async run(prompt, { cwd, signal, finding }) {
+      const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'spectra-fix-')), 'prompt.md');
+      fs.writeFileSync(file, prompt);
+      try {
+        const res = await run(command, [], { cwd, input: prompt, signal, timeoutMs, shell: true, env: { SPECTRA_FIX_PROMPT_FILE: file, SPECTRA_FIX_FINDING: JSON.stringify(finding) } });
+        if (res.code !== 0) throw new Error(`the agent exited with code ${res.code}: ${(res.err || res.out).trim().split('\n').slice(-2).join(' ')}`);
+        return { summary: res.out.trim().split('\n').filter(Boolean).pop()?.slice(0, 300) || '', costUsd: null, turns: null, error: null };
+      } finally {
+        fs.rmSync(path.dirname(file), { recursive: true, force: true });
+      }
+    },
+  };
+}

package/server/fix/checks.js

@@ -0,0 +1,53 @@
+/**
+ * The project's own checks: the tests, type check and build that must pass
+ * after every change, so a "faster" page is never a broken one. A check can
+ * test the live app at $SPECTRA_FIX_URL.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PLACEHOLDER = /no test specified/;
+
+/** Checks from package.json scripts: test, typecheck and build. */
+export function detectChecks(projectDir) {
+  let scripts = {};
+  try {
+    scripts = JSON.parse(fs.readFileSync(path.join(projectDir, 'package.json'), 'utf8')).scripts || {};
+  } catch {
+    /* no package.json */
+  }
+  const checks = [];
+  if (scripts.test && !PLACEHOLDER.test(scripts.test)) checks.push({ name: 'npm test', cmd: 'npm test' });
+  const typecheck = ['typecheck', 'type-check', 'check-types', 'tsc'].find(s => scripts[s]);
+  if (typecheck) checks.push({ name: `npm run ${typecheck}`, cmd: `npm run ${typecheck}` });
+  if (scripts.build) checks.push({ name: 'npm run build', cmd: 'npm run build' });
+  return checks;
+}
+
+/** Run checks in order, stopping at the first failure. */
+export async function runChecks(checks, { cwd, env = {}, signal, timeoutMs = 10 * 60_000 }) {
+  const results = [];
+  for (const check of checks) {
+    const t0 = Date.now();
+    const res = await new Promise(resolve => {
+      const child = spawn(check.cmd, { cwd, shell: true, env: { ...process.env, CI: '1', FORCE_COLOR: '0', ...env }, stdio: ['ignore', 'pipe', 'pipe'] });
+      let out = '';
+      child.stdout.on('data', d => (out = (out + d).slice(-4000)));
+      child.stderr.on('data', d => (out = (out + d).slice(-4000)));
+      const timer = setTimeout(() => child.kill('SIGTERM'), timeoutMs);
+      const abort = () => child.kill('SIGTERM');
+      signal?.addEventListener('abort', abort, { once: true });
+      child.on('error', e => resolve({ code: 127, out: e.message }));
+      child.on('close', code => {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', abort);
+        resolve({ code, out });
+      });
+    });
+    const result = { name: check.name, ok: res.code === 0, ms: Date.now() - t0, tail: res.out.trim().split('\n').slice(-12).join('\n') };
+    results.push(result);
+    if (!result.ok) break;
+  }
+  return results;
+}