@progen-labs/spectra 0.6.0 → 0.7.0

package/dist/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Performance Profiler</title>
     <link rel="icon" href="data:," />
-    <script type="module" crossorigin src="/assets/index-mtYxDBW7.js"></script>
+    <script type="module" crossorigin src="/assets/index-BDIjT029.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-z14kjW8r.css">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@progen-labs/spectra",
-  "version": "0.6.0",
+  "version": "0.7.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.",
   "type": "module",
   "bin": {
@@ -24,7 +24,8 @@
     "index.html",
     "vite.config.js",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "spectra": "node bin/spectra.js",
@@ -36,10 +37,12 @@
     "test": "node --test \"server/**/test-*.js\" \"action/test-*.js\"",
     "test:vscode": "npm --prefix vscode test",
     "bench": "node bench/run.mjs",
-    "postinstall": "node server/postinstall.js"
+    "size": "npm run build && node scripts/size-report.mjs",
+    "lint": "eslint .",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-include=\"server/**\" --test-coverage-include=\"shared/**\" --test-coverage-include=\"bin/**\" --test-coverage-exclude=\"**/test-*.js\" --test-coverage-exclude=\"server/probe.browser.js\" --test-coverage-lines=70 --test-coverage-branches=70 --test-coverage-functions=72 \"server/**/test-*.js\" \"action/test-*.js\""
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22.12"
   },
   "keywords": [
     "performance",
@@ -63,7 +66,7 @@
   ],
   "author": "Progen Labs (Sourav Debnath)",
   "license": "MIT",
-  "homepage": "https://github.com/progen-labs/spectra#readme",
+  "homepage": "https://progen-labs.github.io/website/#spectra",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/progen-labs/spectra.git"
@@ -79,12 +82,32 @@
     "puppeteer-core": "^25.13.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.5",
     "@modelcontextprotocol/sdk": "^1.32.1",
+    "@size-limit/file": "^14.2.0",
     "@vitejs/plugin-react": "^6.1.2",
     "d3": "^7.9.0",
+    "eslint": "^9.39.5",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.13.0",
     "highlight.js": "^11.10.0",
+    "publint": "^0.3.25",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "size-limit": "^14.2.0",
     "vite": "^8.3.4"
-  }
+  },
+  "size-limit": [
+    {
+      "name": "Dashboard JavaScript (brotli)",
+      "path": "dist/assets/*.js",
+      "limit": "115 kB"
+    },
+    {
+      "name": "Dashboard CSS (brotli)",
+      "path": "dist/assets/*.css",
+      "limit": "10 kB"
+    }
+  ]
 }

package/schema/config.schema.json

@@ -141,7 +141,7 @@
       }
     },
     "agentDocs": {
-      "description": "Spectra's knowledge doc for AI agents, written after npm install (see `spectra agents`). false: never write it; a list: only for these agents. Left out: AGENTS.md and the agents this project or machine uses.",
+      "description": "Spectra's knowledge doc for AI agents, written the first time Spectra runs in the project (see `spectra agents`). false: never write it; a list: only for these agents. Left out: AGENTS.md and the agents this project or machine uses.",
       "oneOf": [
         {
           "type": "boolean"

package/schema/result.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://unpkg.com/@progen-labs/spectra/schema/result.schema.json",
   "title": "Spectra result",
-  "description": "What `spectra … --json` prints and `--out` writes. A small envelope that points at the full reports on disk. Additive changes keep schemaVersion; breaking changes bump it.",
+  "description": "What `spectra \u2026 --json` prints and `--out` writes. A small envelope that points at the full reports on disk. Additive changes keep schemaVersion; breaking changes bump it.",
   "type": "object",
   "required": [
     "schemaVersion",
@@ -19,7 +19,8 @@
         "profile",
         "evaluation",
         "compare",
-        "reports"
+        "reports",
+        "improve"
       ]
     },
     "spectraVersion": {
@@ -81,6 +82,18 @@
       "then": {
         "$ref": "#/$defs/reports"
       }
+    },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "improve"
+          }
+        }
+      },
+      "then": {
+        "$ref": "#/$defs/improve"
+      }
     }
   ],
   "$defs": {
@@ -258,7 +271,7 @@
             "string",
             "null"
           ],
-          "description": "exact, or located (≈, found by searching the source)."
+          "description": "exact, or located (\u2248, found by searching the source)."
         },
         "abs": {
           "type": [
@@ -744,6 +757,54 @@
           }
         }
       }
+    },
+    "improve": {
+      "type": "object",
+      "description": "One step of a guided `spectra improve` session (next, check, report or stop): the text shown to whoever makes the changes, and the session state.",
+      "required": [
+        "step",
+        "message",
+        "session"
+      ],
+      "properties": {
+        "step": {
+          "enum": [
+            "next",
+            "check",
+            "report",
+            "stop"
+          ]
+        },
+        "message": {
+          "type": "string",
+          "description": "What was printed: the problem to fix, the verdict on a change, or the report."
+        },
+        "task": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "description": "The problem to work on now, if any: title, file, line, severity, impactMs, fix, culprits."
+        },
+        "attempt": {
+          "type": "object",
+          "description": "check only: the change just measured, with outcome (kept, no-gain, slower, mixed, new-problem, unproven, checks-failed) and reason."
+        },
+        "result": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "description": "report and stop: the overall before \u2192 after (verdict, confidence, headlines) when something was kept."
+        },
+        "session": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "description": "The whole session: baseline, current (the result files of the latest kept state), queue, task, attempts, skipped, kept."
+        }
+      }
     }
   }
 }

package/server/agents-cli.js

@@ -10,9 +10,10 @@
  *   spectra agents --print         print the knowledge doc
  *   … --dir <project>  --dry-run
  */
+import fs from 'node:fs';
 import path from 'node:path';
 import { parseArgs } from './args.js';
-import { TARGETS, TARGET_IDS, describe, detectTargets, installAgentDocs, knowledge, removeAgentDocs } from './agents.js';
+import { TARGETS, TARGET_IDS, describe, detectTargets, installAgentDocs, knowledge, removeAgentDocs, writeNote } from './agents.js';
 
 const { opt, flag } = parseArgs(process.argv.slice(2), { values: ['dir', 'only'] });
 const root = path.resolve(opt('dir', process.cwd()));
@@ -25,7 +26,7 @@ Teaches your AI agents about Spectra: what it does, which command answers which
 request, and how to read the results. It writes Spectra's knowledge doc where
 each agent reads its project instructions, so you can ask in plain words
 ("why is checkout slow?", "did my change help?") and the agent runs Spectra.
-It runs by itself after npm install; this does it by hand.
+It happens by itself the first time Spectra runs in a project; this does it by hand.
 
 Agents: ${TARGET_IDS.join(', ')}
 Off for a project: "agentDocs": false in spectra.config.json (or SPECTRA_AGENT_DOCS=0).`);
@@ -46,6 +47,8 @@ if (flag('list')) {
 
 if (flag('remove')) {
   const results = removeAgentDocs({ root, dryRun });
+  // and don't bring them back on the next run
+  if (!dryRun) writeNote(root, { removed: true });
   console.log(results.length ? `${dryRun ? 'Would remove' : 'Removed'} Spectra's knowledge doc:\n${describe(results)}` : 'Nothing to remove.');
   process.exit(0);
 }
@@ -61,6 +64,7 @@ else if (opt('only')) {
   }
 }
 const results = installAgentDocs({ root, targets, dryRun });
+if (!dryRun) writeNote(root, { version: JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version });
 console.log(`${dryRun ? 'Would write' : 'Wrote'} Spectra's knowledge doc for your AI agents:\n${describe(results)}`);
 console.log('\nAsk your agent in plain words, e.g. "why is the checkout page slow?" or "did my last change make it faster?".');
 console.log('Remove it with: npx spectra agents --remove');

package/server/agents.js

@@ -5,8 +5,9 @@
  * instructions, so a user can just ask in plain words ("why is checkout
  * slow?", "did my change help?") and the agent runs the right Spectra command.
  *
- * Runs after `npm install @progen-labs/spectra` (server/postinstall.js) for the
- * agents this machine or project uses, and on demand with `spectra agents`.
+ * Written the first time Spectra runs in a project it is installed in (no
+ * install script, so package managers and supply-chain scanners have nothing
+ * to flag), refreshed when Spectra updates, and on demand with `spectra agents`.
  *
  * Files Spectra owns carry a `spectra:managed` marker and are replaced on
  * update; in shared files (AGENTS.md, CLAUDE.md, GEMINI.md) only the block
@@ -250,33 +251,84 @@ export function removeAgentDocs({ root, dryRun = false } = {}) {
   return out;
 }
 
+// what Spectra did in a project, so it acts once per version and never undoes a removal
+const noteFile = root => path.join(root, '.spectra', 'agent-docs.json');
+const readNote = root => {
+  try {
+    return JSON.parse(fs.readFileSync(noteFile(root), 'utf8'));
+  } catch {
+    return null;
+  }
+};
+export function writeNote(root, note) {
+  try {
+    fs.mkdirSync(path.dirname(noteFile(root)), { recursive: true });
+    fs.writeFileSync(noteFile(root), `${JSON.stringify({ ...note, at: new Date().toISOString() }, null, 2)}\n`);
+  } catch {}
+}
+
 /**
- * Should the install step write the docs? Only for a real project install:
- * not in CI, not a global install, not `npx` running Spectra from its cache,
- * not Spectra's own repository, and not when the user opted out.
+ * Should this run of `spectra` write the docs? Only in a project Spectra is
+ * installed in (its node_modules holds this copy of Spectra, and the command
+ * runs inside it): not under `npx` from its cache, not a global install, not
+ * Spectra's own repository, not in CI, and not when the user opted out or
+ * removed the docs. Once per Spectra version: the first run writes them for
+ * the agents in use; after an update, only what is already there is refreshed.
  */
-export function postinstallPlan({ env = process.env, pkgRoot = PKG_ROOT } = {}) {
-  const root = env.INIT_CWD && path.resolve(env.INIT_CWD);
+export function firstRunPlan({ cwd = process.cwd(), env = process.env, pkgRoot = PKG_ROOT } = {}) {
   if (env.SPECTRA_AGENT_DOCS === '0' || env.SPECTRA_AGENT_DOCS === 'false') return { skip: 'SPECTRA_AGENT_DOCS=0' };
   if (env.CI && env.CI !== 'false' && env.CI !== '0') return { skip: 'CI' };
-  if (env.npm_config_global === 'true') return { skip: 'a global install' };
-  if (!root) return { skip: 'no project directory (INIT_CWD)' };
-  const pkg = path.resolve(pkgRoot);
-  if (pkg === root) return { skip: "Spectra's own repository" };
-  // installed into this project's node_modules (pnpm keeps it under node_modules/.pnpm), not into npx's cache
   const real = (() => {
     try {
-      return fs.realpathSync(pkg);
+      return fs.realpathSync(pkgRoot);
     } catch {
-      return pkg;
+      return path.resolve(pkgRoot);
     }
   })();
-  const modules = path.join(root, 'node_modules') + path.sep;
-  if (!pkg.startsWith(modules) && !real.startsWith(modules)) return { skip: 'not installed into this project (npx or a parent folder)' };
+  const at = real.indexOf(`${path.sep}node_modules${path.sep}`);
+  if (at < 0) return { skip: "not installed from npm (Spectra's own repository)" };
+  const root = real.slice(0, at);
+  const here = (() => {
+    try {
+      return fs.realpathSync(cwd);
+    } catch {
+      return path.resolve(cwd);
+    }
+  })();
+  if (here !== root && !here.startsWith(root + path.sep)) return { skip: 'not run inside the project Spectra is installed in (npx or a global install)' };
   if (!exists(path.join(root, 'package.json'))) return { skip: 'no package.json' };
   const setting = readAgentDocsSetting(root);
   if (setting === false) return { skip: '"agentDocs": false in spectra.config.json' };
-  return { root, targets: Array.isArray(setting) ? setting.filter(id => TARGET_IDS.includes(id)) : undefined };
+  const note = readNote(root);
+  if (note?.removed) return { skip: 'removed with `spectra agents --remove`' };
+  if (note?.version === VERSION) return { skip: 'already done for this version' };
+  return { root, mode: note ? 'refresh' : 'install', targets: Array.isArray(setting) ? setting.filter(id => TARGET_IDS.includes(id)) : undefined };
+}
+
+/** Rewrites only the Spectra content that is already in the project (after an update). */
+export function refreshAgentDocs({ root, dryRun = false } = {}) {
+  const out = [];
+  for (const t of TARGETS) {
+    const files = [{ file: t.file, write: f => (t.block ? writeBlock(f, t.block(), dryRun) : writeOwn(f, t.content(), dryRun)) }];
+    if (t.also) files.push({ file: t.also.file, write: f => writeBlock(f, t.also.block(), dryRun) });
+    for (const { file: rel, write } of files) {
+      const file = path.join(root, rel);
+      if (!exists(file)) continue;
+      const text = fs.readFileSync(file, 'utf8');
+      if (!findBlock(text) && !text.includes(MANAGED)) continue;
+      out.push({ id: t.id, name: t.name, file: rel, result: write(file) });
+    }
+  }
+  return out;
+}
+
+/** The first-run step: does what firstRunPlan says, and remembers it. Returns the files it changed. */
+export function ensureAgentDocs(opts = {}) {
+  const plan = firstRunPlan(opts);
+  if (plan.skip) return { skip: plan.skip, changed: [] };
+  const results = plan.mode === 'install' ? installAgentDocs({ root: plan.root, targets: plan.targets }) : refreshAgentDocs({ root: plan.root });
+  writeNote(plan.root, { version: VERSION });
+  return { root: plan.root, changed: results.filter(r => r.result === 'created' || r.result === 'updated') };
 }
 
 /** One line per file, for people. */

package/server/explore/boot.js

@@ -8,6 +8,8 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
+// terminal colour codes in the dev server's output
+// eslint-disable-next-line no-control-regex
 const ANSI = /\x1b\[[0-9;]*m/g;
 const URL_RE =
   /(https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0)(?::\d+)?[^\s)'"<]*)/i;

package/server/fix/agent.js

@@ -1,18 +1,97 @@
 /**
- * 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.
+ * The coding agent `spectra improve` hands one finding to when it runs
+ * unattended. Spectra knows the common agent CLIs by name (AGENTS below) and
+ * finds one on the machine by itself; Claude Code runs 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';
 
+/**
+ * The agents Spectra can run by name: how each one takes a single prompt,
+ * edits files in the current directory without asking, and exits (the
+ * "print" mode every CLI agent has), and the signs that it is in use.
+ */
+export const AGENTS = {
+  claude: { name: 'Claude Code', bin: 'claude', project: ['CLAUDE.md', '.claude'], home: ['.claude', '.claude.json'], also: ['.local/bin/claude', '.claude/local/claude'] },
+  codex: { name: 'Codex CLI', bin: 'codex', args: p => ['exec', '--full-auto', p], project: ['.codex'], home: ['.codex'] },
+  gemini: { name: 'Gemini CLI', bin: 'gemini', args: p => ['-p', p, '--yolo'], project: ['GEMINI.md', '.gemini'], home: ['.gemini'] },
+  copilot: { name: 'GitHub Copilot CLI', bin: 'copilot', args: p => ['-p', p, '--allow-all-tools'], project: ['.github/copilot-instructions.md', '.github/instructions'], home: ['.copilot'] },
+  cursor: { name: 'Cursor CLI', bin: 'cursor-agent', args: p => ['-p', p, '--force'], project: ['.cursor', '.cursorrules'], home: ['.cursor'] },
+  opencode: { name: 'OpenCode', bin: 'opencode', args: p => ['run', p], project: ['opencode.json', '.opencode'], home: ['.config/opencode'] },
+  amp: { name: 'Amp', bin: 'amp', args: p => ['-x', p], project: [], home: ['.config/amp'] },
+};
+export const AGENT_IDS = Object.keys(AGENTS);
+
+const exists = p => {
+  try {
+    fs.statSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Where an agent's executable is: on PATH, or in the places its installer uses. Null when it is not installed. */
+export function findExecutable(id, { env = process.env, home = os.homedir() } = {}) {
+  const a = AGENTS[id];
+  if (id === 'claude' && env.SPECTRA_CLAUDE) return env.SPECTRA_CLAUDE;
+  const names = process.platform === 'win32' ? [`${a.bin}.cmd`, `${a.bin}.exe`, a.bin] : [a.bin];
+  for (const dir of (env.PATH || '').split(path.delimiter).filter(Boolean))
+    for (const n of names) if (exists(path.join(dir, n))) return path.join(dir, n);
+  for (const rel of a.also || []) if (home && exists(path.join(home, rel))) return path.join(home, rel);
+  return null;
+}
+
+/**
+ * The agent to run unattended, when none was named: first one the project or
+ * the machine shows signs of (so it is the agent the user already works with),
+ * then any that is installed. Null when there is none.
+ */
+export function detectAgent({ root = process.cwd(), home = os.homedir(), env = process.env } = {}) {
+  const installed = AGENT_IDS.filter(id => findExecutable(id, { env, home }));
+  const inUse = id => (AGENTS[id].project || []).some(p => exists(path.join(root, p))) || (AGENTS[id].home || []).some(p => home && exists(path.join(home, p)));
+  const id = installed.find(inUse) || installed[0];
+  return id ? { id, ...AGENTS[id], bin: findExecutable(id, { env, home }) } : null;
+}
+
+/** The agent for --agent: a name from AGENTS, or any shell command. */
+export function agentFromOption(value, opts = {}) {
+  return AGENTS[value] ? namedAgent(value, opts) : commandAgent(String(value), opts);
+}
+
+/** One of AGENTS, ready to run. */
+export function namedAgent(id, { bin, model, budgetUsd, timeoutMs = 10 * 60_000, env, home } = {}) {
+  const a = AGENTS[id];
+  if (!a) throw new Error(`unknown agent "${id}"; the names are ${AGENT_IDS.join(', ')}, or pass a command.`);
+  const executable = bin || findExecutable(id, { env, home }) || a.bin;
+  if (id === 'claude') return claudeAgent({ bin: executable, model, budgetUsd, timeoutMs });
+  return {
+    id,
+    name: a.name,
+    async run(prompt, { cwd, signal }) {
+      let res;
+      try {
+        res = await run(executable, a.args(prompt), { cwd, signal, timeoutMs, env: { CI: '1' } });
+      } catch (err) {
+        throw new Error(`could not start ${a.name} (${err.message}). Install it, or pass --agent "<command>".`);
+      }
+      if (res.code !== 0) throw new Error(`${a.name} exited with code ${res.code}: ${(res.err || res.out).trim().split('\n').slice(-3).join(' ')}`);
+      return { summary: res.out.trim().split('\n').filter(Boolean).pop()?.slice(0, 300) || '', costUsd: null, turns: null, error: null };
+    },
+  };
+}
+
+// `input` goes to the agent's stdin; without it, stdin is closed from the start
+// (the prompt is in the arguments). An agent that exits before reading its
+// stdin makes the write fail with EPIPE, which must not take Spectra down.
 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 });
+    const child = spawn(cmd, args, { cwd, env: { ...process.env, ...env }, stdio: [input == null ? 'ignore' : 'pipe', 'pipe', 'pipe'], shell });
     let out = '';
     let err = '';
     child.stdout.on('data', d => (out += d));
@@ -29,12 +108,16 @@ const run = (cmd, args, { cwd, input, env, signal, timeoutMs, shell = false }) =
       signal?.removeEventListener('abort', abort);
       resolve({ code, out, err });
     });
-    child.stdin.end(input ?? '');
+    if (input != null) {
+      child.stdin.on('error', () => {}); // the agent closed its end first
+      child.stdin.end(input);
+    }
   });
 
 /** Claude Code, headless. */
 export function claudeAgent({ bin = process.env.SPECTRA_CLAUDE || 'claude', model, budgetUsd = 2, timeoutMs = 10 * 60_000 } = {}) {
   return {
+    id: 'claude',
     name: `Claude Code${model ? ` (${model})` : ''}`,
     async run(prompt, { cwd, signal }) {
       const args = [