@triscope/cli 0.4.0

package/src/mcp.mjs

@@ -0,0 +1,257 @@
+// `triscope mcp install|uninstall` — wraps `claude mcp add/remove`.
+//
+// Resolves the absolute path of the @triscope/mcp bin via Node's resolver, so
+// it works whether triscope is installed as a dep, linked, or run from this
+// monorepo. Falls back to a sibling `packages/mcp/bin/triscope-mcp.mjs` for
+// the monorepo case where the bin isn't on PATH.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SERVER_NAME = 'triscope';
+const DEFAULT_URL = 'http://localhost:5173';
+
+export function resolveServerBin() {
+  // Try the workspace sibling first (monorepo dev case).
+  const here = dirname(fileURLToPath(import.meta.url));
+  const sibling = resolve(here, '../../mcp/bin/triscope-mcp.mjs');
+  if (existsSync(sibling)) return sibling;
+
+  // Fall back to Node resolution from the consumer project's cwd.
+  try {
+    const req = createRequire(join(process.cwd(), 'package.json'));
+    const pkgJson = req.resolve('@triscope/mcp/package.json');
+    return resolve(dirname(pkgJson), 'bin/triscope-mcp.mjs');
+  } catch {
+    return null;
+  }
+}
+
+export function resolveCliBin() {
+  // This module lives in packages/cli/src/mcp.mjs; the bin is at ../bin/triscope.mjs.
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, '../bin/triscope.mjs');
+}
+
+function triscopeOnPath() {
+  const r = spawnSync('triscope', ['--help'], { stdio: 'ignore' });
+  return r.status === 0;
+}
+
+export function autoCaptureCommand() {
+  // Use bare `triscope` if it's on PATH (npm i -g'd), otherwise the
+  // absolute path to this CLI bin (monorepo / file-dep installs).
+  const cmd = triscopeOnPath() ? 'triscope' : `node ${resolveCliBin()}`;
+  return `${cmd} auto-capture --file "\${TOOL_INPUT_file_path:-}"`;
+}
+
+function hasClaudeCli() {
+  const r = spawnSync('claude', ['--version'], { stdio: 'ignore' });
+  return r.status === 0;
+}
+
+function runClaude(args) {
+  const r = spawnSync('claude', args, { stdio: 'inherit' });
+  if (r.status !== 0) throw new Error(`claude ${args.join(' ')} exited ${r.status}`);
+}
+
+function isTriscopeRegistered() {
+  const r = spawnSync('claude', ['mcp', 'list'], { stdio: ['ignore', 'pipe', 'pipe'] });
+  if (r.status !== 0) return false;
+  return /^triscope:/m.test(r.stdout?.toString?.() ?? '');
+}
+
+export function writeProjectMcpJson(bin, url) {
+  const path = join(process.cwd(), '.mcp.json');
+  let existing = {};
+  if (existsSync(path)) {
+    try {
+      existing = JSON.parse(readFileSync(path, 'utf8'));
+    } catch {}
+  }
+  existing.mcpServers ??= {};
+  existing.mcpServers[SERVER_NAME] = {
+    command: 'node',
+    args: [bin],
+    env: { TRISCOPE_URL: url },
+  };
+  writeFileSync(path, JSON.stringify(existing, null, 2) + '\n');
+  return path;
+}
+
+export function removeFromProjectMcpJson() {
+  const path = join(process.cwd(), '.mcp.json');
+  if (!existsSync(path)) return null;
+  const data = JSON.parse(readFileSync(path, 'utf8'));
+  if (!data?.mcpServers?.[SERVER_NAME]) return null;
+  delete data.mcpServers[SERVER_NAME];
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+  return path;
+}
+
+// Hook config — same shape across user/project scope. The "_triscope" tag
+// lets uninstall find and remove our entry without touching unrelated hooks.
+export function triscopeHookSpec() {
+  return {
+    matcher: 'Edit|Write',
+    _triscope: true,
+    hooks: [{ type: 'command', command: autoCaptureCommand() }],
+  };
+}
+
+export function settingsPathForScope(scope) {
+  if (scope === 'project') {
+    return join(process.cwd(), '.claude', 'settings.local.json');
+  }
+  return join(homedir(), '.claude', 'settings.json');
+}
+
+export function mergeHook(scope) {
+  const path = settingsPathForScope(scope);
+  mkdirSync(dirname(path), { recursive: true });
+  let data = {};
+  if (existsSync(path)) {
+    try {
+      data = JSON.parse(readFileSync(path, 'utf8'));
+    } catch {
+      // Settings file is malformed — refuse rather than silently overwrite.
+      throw new Error(`refusing to overwrite malformed JSON at ${path}`);
+    }
+  }
+  data.hooks ??= {};
+  data.hooks.PostToolUse ??= [];
+  // Skip if our entry is already present (idempotent install).
+  const already = data.hooks.PostToolUse.some(
+    (e) =>
+      e?._triscope === true ||
+      e?.hooks?.some?.(
+        (h) => typeof h?.command === 'string' && h.command.includes('triscope auto-capture'),
+      ),
+  );
+  if (!already) data.hooks.PostToolUse.push(triscopeHookSpec());
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+  return { path, added: !already };
+}
+
+export function unmergeHook(scope) {
+  const path = settingsPathForScope(scope);
+  if (!existsSync(path)) return { path, removed: false };
+  let data;
+  try {
+    data = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return { path, removed: false };
+  }
+  const arr = data?.hooks?.PostToolUse;
+  if (!Array.isArray(arr)) return { path, removed: false };
+  const before = arr.length;
+  data.hooks.PostToolUse = arr.filter(
+    (e) =>
+      !(
+        e?._triscope === true ||
+        e?.hooks?.some?.(
+          (h) => typeof h?.command === 'string' && h.command.includes('triscope auto-capture'),
+        )
+      ),
+  );
+  if (data.hooks.PostToolUse.length === before) return { path, removed: false };
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+  return { path, removed: true };
+}
+
+export async function runMcp({ action, scope = 'user', url = DEFAULT_URL, withHook = true }) {
+  if (!action || action === 'help') {
+    console.log(`triscope mcp <install|uninstall> [--project] [--no-hook] [--url <url>]
+
+  install              Register the triscope MCP server with Claude Code AND
+                       wire the PostToolUse auto-capture hook into settings
+                       (default: user scope, so it's available in every chat).
+  install --project    Write/merge .mcp.json + .claude/settings.local.json
+                       in the current directory instead.
+  uninstall            Remove the triscope MCP registration and the hook.
+
+OPTIONS
+  --project            Use project scope (cwd-local files) instead of user.
+  --no-hook            Skip the PostToolUse hook (MCP-only install).
+  --url <url>          Override TRISCOPE_URL env (default ${DEFAULT_URL}).
+`);
+    return;
+  }
+
+  const bin = resolveServerBin();
+  if (!bin) {
+    throw new Error(
+      'Could not locate @triscope/mcp. Install triscope (e.g. `npm i @triscope/mcp`) or run from the monorepo.',
+    );
+  }
+  try {
+    statSync(bin);
+  } catch {
+    throw new Error(`@triscope/mcp bin not found at ${bin}`);
+  }
+
+  if (action === 'install') {
+    if (scope === 'project') {
+      const path = writeProjectMcpJson(bin, url);
+      console.log(`wrote project-scoped registration to ${path}`);
+      if (withHook) {
+        const r = mergeHook('project');
+        console.log(
+          r.added ? `added PostToolUse hook to ${r.path}` : `hook already present in ${r.path}`,
+        );
+      }
+      console.log('restart Claude Code in this directory to pick it up.');
+      return;
+    }
+    if (!hasClaudeCli()) {
+      throw new Error(
+        'claude CLI not on PATH. Install Claude Code, or run `triscope mcp install --project`.',
+      );
+    }
+    if (isTriscopeRegistered()) {
+      console.log('triscope MCP already registered (user scope), skipping mcp add.');
+    } else {
+      runClaude([
+        'mcp',
+        'add',
+        SERVER_NAME,
+        '--scope',
+        'user',
+        '--env',
+        `TRISCOPE_URL=${url}`,
+        '--',
+        'node',
+        bin,
+      ]);
+      console.log(`\ntriscope registered (user scope). bin: ${bin}`);
+    }
+    if (withHook) {
+      const r = mergeHook('user');
+      console.log(
+        r.added ? `added PostToolUse hook to ${r.path}` : `hook already present in ${r.path}`,
+      );
+    }
+    return;
+  }
+
+  if (action === 'uninstall') {
+    if (scope === 'project') {
+      const path = removeFromProjectMcpJson();
+      if (path) console.log(`removed triscope from ${path}`);
+      else console.log('no project-scoped triscope entry found.');
+      const h = unmergeHook('project');
+      if (h.removed) console.log(`removed PostToolUse hook from ${h.path}`);
+      return;
+    }
+    if (!hasClaudeCli()) throw new Error('claude CLI not on PATH.');
+    runClaude(['mcp', 'remove', SERVER_NAME, '--scope', 'user']);
+    const h = unmergeHook('user');
+    if (h.removed) console.log(`removed PostToolUse hook from ${h.path}`);
+    return;
+  }
+
+  throw new Error(`Unknown mcp action: ${action}`);
+}

package/src/parse-flags.mjs

@@ -0,0 +1,25 @@
+// Argv parser shared between the bin entry and its tests. Keeps the bin
+// file small enough that the only thing left to cover via subprocess is
+// the subcommand-dispatch table itself.
+export function parseFlags(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') flags.help = true;
+    else if (a === '--project') flags.project = true;
+    else if (a === '--check') flags.check = true;
+    else if (a === '--quick') flags.quick = true;
+    else if (a === '--yes' || a === '-y') flags.yes = true;
+    else if (a === '--no-hook') flags['no-hook'] = true;
+    else if (a === '--no-install') flags['no-install'] = true;
+    else if (a === '--url') flags.url = argv[++i];
+    else if (a === '--file') flags.file = argv[++i];
+    else if (a === '--port') flags.port = argv[++i];
+    else if (a === '--screenshot') flags.screenshot = argv[++i];
+    else if (a === '--install') flags.install = true;
+    else if (a.startsWith('--')) flags[a.slice(2)] = argv[++i];
+    else positional.push(a);
+  }
+  return { flags, positional };
+}

package/src/preflight.mjs

@@ -0,0 +1,110 @@
+// `triscope dev --check` — preflight diagnostics. Turns the cryptic mid-session
+// failures (no WebGPU, wrong Node, MCP not registered, port busy) into an
+// up-front PASS/WARN/FAIL checklist. The pure predicates are unit-tested; the
+// side-effecty ones (chromium spawn, port bind, claude CLI) are composed here.
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { join } from 'node:path';
+
+export function checkNode(version = process.versions.node) {
+  const major = Number.parseInt(String(version), 10);
+  return major >= 20
+    ? { name: 'node', status: 'PASS', detail: `v${version}` }
+    : { name: 'node', status: 'FAIL', detail: `v${version} — triscope needs Node >= 20` };
+}
+
+export function checkProjectDeps(cwd = process.cwd()) {
+  const vite = existsSync(join(cwd, 'node_modules', '.bin', 'vite'));
+  const core = existsSync(join(cwd, 'node_modules', '@triscope', 'core', 'package.json'));
+  return [
+    vite
+      ? { name: 'vite', status: 'PASS', detail: 'installed' }
+      : { name: 'vite', status: 'FAIL', detail: 'not installed — run `npm install`' },
+    core
+      ? { name: '@triscope/core', status: 'PASS', detail: 'installed' }
+      : { name: '@triscope/core', status: 'FAIL', detail: 'not installed — run `npm install`' },
+  ];
+}
+
+export function checkChromium(bin = process.env.CHROME_BIN ?? 'chromium') {
+  const r = spawnSync(bin, ['--version'], { stdio: ['ignore', 'pipe', 'ignore'] });
+  if (r.status === 0) {
+    return {
+      name: 'chromium',
+      status: 'PASS',
+      detail: (r.stdout?.toString?.() ?? '').trim() || bin,
+    };
+  }
+  return {
+    name: 'chromium',
+    status: 'WARN',
+    detail: `"${bin}" not runnable — capture_views/smoke need Chrome/Chromium with WebGPU (set CHROME_BIN)`,
+  };
+}
+
+export function checkClaudeMcp() {
+  const has = spawnSync('claude', ['--version'], { stdio: 'ignore' }).status === 0;
+  if (!has) {
+    return {
+      name: 'mcp',
+      status: 'WARN',
+      detail: 'claude CLI not on PATH — MCP tools unavailable (optional)',
+    };
+  }
+  const list = spawnSync('claude', ['mcp', 'list'], { stdio: ['ignore', 'pipe', 'ignore'] });
+  const registered = list.status === 0 && /^triscope:/m.test(list.stdout?.toString?.() ?? '');
+  return registered
+    ? { name: 'mcp', status: 'PASS', detail: 'triscope registered' }
+    : {
+        name: 'mcp',
+        status: 'WARN',
+        detail: 'triscope not registered — run `triscope mcp install`',
+      };
+}
+
+export function checkPortFree(port = 5173) {
+  return new Promise((resolve) => {
+    const srv = createServer();
+    srv.once('error', () => {
+      resolve({
+        name: `port ${port}`,
+        status: 'WARN',
+        detail: 'in use — `triscope dev` will pick another or fail',
+      });
+    });
+    srv.once('listening', () => {
+      srv.close(() => resolve({ name: `port ${port}`, status: 'PASS', detail: 'free' }));
+    });
+    srv.listen(port, '127.0.0.1');
+  });
+}
+
+export function aggregatePreflight(results) {
+  const fails = results.filter((r) => r.status === 'FAIL').length;
+  const warns = results.filter((r) => r.status === 'WARN').length;
+  return { ok: fails === 0, fails, warns };
+}
+
+export async function runPreflight({ cwd = process.cwd(), port = 5173, chromeBin } = {}) {
+  const results = [
+    checkNode(),
+    ...checkProjectDeps(cwd),
+    checkChromium(chromeBin),
+    checkClaudeMcp(),
+    await checkPortFree(port),
+  ];
+  return { results, ...aggregatePreflight(results) };
+}
+
+const ICON = { PASS: '✓', WARN: '!', FAIL: '✗' };
+
+export function formatPreflight({ results, ok, fails, warns }) {
+  const lines = results.map(
+    (r) => `  ${ICON[r.status] ?? '?'} ${r.status.padEnd(4)} ${r.name} — ${r.detail}`,
+  );
+  const summary = ok
+    ? `\npreflight OK${warns ? ` (${warns} warning${warns > 1 ? 's' : ''})` : ''}.`
+    : `\npreflight FAILED: ${fails} blocking issue${fails > 1 ? 's' : ''} (see ✗ above).`;
+  return ['triscope preflight:', ...lines, summary].join('\n');
+}

package/src/smoke-lib.mjs

@@ -0,0 +1,230 @@
+// Shared smoke primitives: boot Vite, drive Chromium over CDP, read back via
+// the harness's captureViews() (the only reliable WebGPU path), and an SSIM
+// helper for visual-regression gating. Used by `triscope smoke` and reusable
+// by project/example smokes.
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PNG } from 'pngjs';
+
+export const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export function readProjectName(cwd) {
+  try {
+    const p = join(cwd, 'package.json');
+    if (!existsSync(p)) return 'triscope-project';
+    const pkg = JSON.parse(readFileSync(p, 'utf8'));
+    return String(pkg.name ?? 'triscope-project').replace(/[^A-Za-z0-9._-]/g, '-');
+  } catch {
+    return 'triscope-project';
+  }
+}
+
+export async function canFetch(url) {
+  try {
+    return (await fetch(url)).ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function waitForHttp(url, timeoutMs = 15000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await canFetch(url)) return true;
+    await wait(250);
+  }
+  return false;
+}
+
+export async function waitForDevtools(port, baseUrl, timeoutMs = 15000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const pages = await fetch(`http://127.0.0.1:${port}/json`).then((r) => r.json());
+      const page = Array.isArray(pages)
+        ? (pages.find((p) => p.type === 'page' && p.url?.startsWith(baseUrl)) ?? pages[0])
+        : null;
+      if (page?.webSocketDebuggerUrl) return page;
+    } catch {}
+    await wait(250);
+  }
+  throw new Error(`DevTools endpoint not ready on 127.0.0.1:${port}`);
+}
+
+/** CDP client + console/exception error collection. */
+export function cdpFactory() {
+  let nextId = 0;
+  const pending = new Map();
+  const errors = [];
+  return {
+    errors,
+    bind(ws) {
+      ws.onmessage = (event) => {
+        const msg = JSON.parse(event.data);
+        if (msg.id && pending.has(msg.id)) {
+          pending.get(msg.id)(msg);
+          pending.delete(msg.id);
+          return;
+        }
+        if (msg.method === 'Runtime.exceptionThrown') {
+          errors.push(
+            msg.params?.exceptionDetails?.exception?.description ??
+              msg.params?.exceptionDetails?.text ??
+              'exception',
+          );
+        } else if (msg.method === 'Runtime.consoleAPICalled' && msg.params?.type === 'error') {
+          errors.push((msg.params.args ?? []).map((a) => a.value ?? a.description ?? '').join(' '));
+        }
+      };
+    },
+    call(ws, method, params = {}) {
+      const id = ++nextId;
+      ws.send(JSON.stringify({ id, method, params }));
+      return new Promise((res, rej) => {
+        const t = setTimeout(() => {
+          pending.delete(id);
+          rej(new Error(`CDP timeout: ${method}`));
+        }, 20000);
+        pending.set(id, (msg) => {
+          clearTimeout(t);
+          if (msg.error) rej(new Error(`${method}: ${msg.error.message}`));
+          else res(msg);
+        });
+      });
+    },
+  };
+}
+
+export async function resolveSmokeLabUrl(baseUrl, element, cwd) {
+  if (!element) return baseUrl;
+  try {
+    const r = await fetch(`${baseUrl}/__manifest`);
+    if (r.ok) {
+      const entry = (await r.json())?.elements?.[element];
+      if (entry?.labUrl) return abs(baseUrl, entry.labUrl);
+    }
+  } catch {}
+  try {
+    const p = join(cwd, 'package.json');
+    if (existsSync(p)) {
+      const m = JSON.parse(readFileSync(p, 'utf8'))?.triscope?.labs;
+      if (m?.[element]) return abs(baseUrl, m[element]);
+    }
+  } catch {}
+  return `${baseUrl}/labs/${element}.html`;
+}
+const abs = (base, v) =>
+  /^https?:\/\//.test(v) ? v : `${base}${v.startsWith('/') ? '' : '/'}${v}`;
+
+export function chromeLaunchArgs({ port, url, profileDir, headless }) {
+  const head = headless
+    ? ['--headless=new', '--use-angle=vulkan', '--enable-features=Vulkan']
+    : ['--ozone-platform=x11'];
+  return [
+    ...head,
+    '--enable-unsafe-webgpu',
+    '--ignore-gpu-blocklist',
+    `--user-data-dir=${profileDir}`,
+    `--remote-debugging-port=${port}`,
+    '--window-size=1600,900',
+    url,
+  ];
+}
+
+export function spawnVite(cwd, port) {
+  // --host 127.0.0.1: bind the IPv4 address the smoke polls/attaches on (Vite 5
+  // otherwise binds localhost/::1 and a 127.0.0.1 fetch can be refused).
+  return spawn(
+    'npx',
+    ['--no-install', 'vite', '--port', String(port), '--strictPort', '--host', '127.0.0.1'],
+    {
+      cwd,
+      env: { ...process.env, BROWSER: 'none' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: true,
+    },
+  );
+}
+
+export function decodePng(buf) {
+  return PNG.sync.read(buf);
+}
+
+/** Mean SSIM over Rec.709 luminance, 256×256 downsample, 8×8 windows.
+ *  Self-contained mirror of @triscope/core's ssim() for the regression gate. */
+export function ssim(aBuf, bBuf) {
+  const A = resize256(decodePng(aBuf));
+  const B = resize256(decodePng(bBuf));
+  const W = 256;
+  const H = 256;
+  const lA = luma(A);
+  const lB = luma(B);
+  const L = 255;
+  const C1 = (0.01 * L) ** 2;
+  const C2 = (0.03 * L) ** 2;
+  const WIN = 8;
+  let total = 0;
+  let count = 0;
+  for (let wy = 0; wy < H; wy += WIN) {
+    for (let wx = 0; wx < W; wx += WIN) {
+      let muA = 0;
+      let muB = 0;
+      for (let dy = 0; dy < WIN; dy++)
+        for (let dx = 0; dx < WIN; dx++) {
+          const i = (wy + dy) * W + (wx + dx);
+          muA += lA[i];
+          muB += lB[i];
+        }
+      muA /= WIN * WIN;
+      muB /= WIN * WIN;
+      let vA = 0;
+      let vB = 0;
+      let cov = 0;
+      for (let dy = 0; dy < WIN; dy++)
+        for (let dx = 0; dx < WIN; dx++) {
+          const i = (wy + dy) * W + (wx + dx);
+          const da = lA[i] - muA;
+          const db = lB[i] - muB;
+          vA += da * da;
+          vB += db * db;
+          cov += da * db;
+        }
+      vA /= WIN * WIN - 1;
+      vB /= WIN * WIN - 1;
+      cov /= WIN * WIN - 1;
+      total +=
+        ((2 * muA * muB + C1) * (2 * cov + C2)) / ((muA * muA + muB * muB + C1) * (vA + vB + C2));
+      count++;
+    }
+  }
+  return +(total / count).toFixed(4);
+}
+
+function resize256(src) {
+  const W = 256;
+  const H = 256;
+  if (src.width === W && src.height === H) return src;
+  const dst = new PNG({ width: W, height: H });
+  for (let y = 0; y < H; y++) {
+    const sy = Math.min(src.height - 1, Math.floor((y * src.height) / H));
+    for (let x = 0; x < W; x++) {
+      const sx = Math.min(src.width - 1, Math.floor((x * src.width) / W));
+      const si = (sy * src.width + sx) * 4;
+      const di = (y * W + x) * 4;
+      dst.data[di] = src.data[si];
+      dst.data[di + 1] = src.data[si + 1];
+      dst.data[di + 2] = src.data[si + 2];
+      dst.data[di + 3] = 255;
+    }
+  }
+  return dst;
+}
+function luma(png) {
+  const out = new Float32Array(png.width * png.height);
+  for (let i = 0; i < out.length; i++) {
+    const j = i * 4;
+    out[i] = 0.2126 * png.data[j] + 0.7152 * png.data[j + 1] + 0.0722 * png.data[j + 2];
+  }
+  return out;
+}