@triscope/cli 0.4.0

package/src/smoke.mjs

@@ -0,0 +1,182 @@
+// `triscope smoke [<element>]` — headed-Chromium smoke test against a lab page.
+//
+// Boots Vite (if not already up), drives Chromium with WebGPU via CDP, and reads
+// back through the harness's captureViews() — the ONLY reliable WebGPU readback
+// path (Page.captureScreenshot misses the swap-chain surface, gpuweb#1781).
+// Asserts: harness mounts, every camera renders, none black, fps stepping, no
+// console/runtime errors. Headed by default; SMOKE_HEADLESS=1 for CI/xvfb.
+import { spawn } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import {
+  canFetch,
+  cdpFactory,
+  chromeLaunchArgs,
+  readProjectName,
+  resolveSmokeLabUrl,
+  spawnVite,
+  wait,
+  waitForDevtools,
+  waitForHttp,
+} from './smoke-lib.mjs';
+
+const BLACK = 0.004;
+
+export async function runSmoke({ element, url, screenshot } = {}) {
+  const cwd = process.cwd();
+  const project = readProjectName(cwd);
+  const baseUrl = (url ?? 'http://localhost:5173/').replace(/\/$/, '');
+  const targetUrl = url ? url : await resolveSmokeLabUrl(baseUrl, element, cwd);
+  const OUT = screenshot ?? join(tmpdir(), `${project}-smoke-${element ?? 'default'}.png`);
+  const PORT = Number(process.env.TRISCOPE_DEBUG_PORT ?? 9230);
+  const CHROME = process.env.CHROME_BIN ?? process.env.PUPPETEER_EXECUTABLE_PATH ?? 'chromium';
+  const headless = !!process.env.SMOKE_HEADLESS;
+
+  let vite = null;
+  let chrome = null;
+  let ws = null;
+  let exitCode = 0;
+  const cdp = cdpFactory();
+
+  try {
+    if (!(await canFetch(baseUrl))) {
+      vite = spawnVite(cwd, new URL(baseUrl).port || 5173);
+      if (!(await waitForHttp(baseUrl, 15000)))
+        throw new Error(`Vite did not respond at ${baseUrl}`);
+    }
+
+    const profileDir = join(tmpdir(), `triscope-smoke-${Date.now()}`);
+    chrome = spawn(CHROME, chromeLaunchArgs({ port: PORT, url: targetUrl, profileDir, headless }), {
+      stdio: 'ignore',
+    });
+
+    const page = await waitForDevtools(PORT, baseUrl, 15000);
+    const WSCtor = globalThis.WebSocket ?? (await import('ws')).WebSocket;
+    ws = new WSCtor(page.webSocketDebuggerUrl);
+    await new Promise((res, rej) => {
+      ws.onopen = res;
+      ws.onerror = (e) => rej(new Error(`ws open failed: ${e?.message ?? e}`));
+    });
+    cdp.bind(ws);
+    await cdp.call(ws, 'Runtime.enable');
+
+    let mounted = false;
+    for (let i = 0; i < 60; i++) {
+      const p = await cdp.call(ws, 'Runtime.evaluate', {
+        expression: '!!(window.__TRISCOPE__ && window.__TRISCOPE__.captureViews)',
+        returnByValue: true,
+      });
+      if (p.result.result.value) {
+        mounted = true;
+        break;
+      }
+      await wait(500);
+    }
+    if (!mounted) {
+      const boot = await cdp.call(ws, 'Runtime.evaluate', {
+        expression: 'document.getElementById("boot")?.textContent ?? ""',
+        returnByValue: true,
+      });
+      throw new Error(
+        `window.__TRISCOPE__ did not mount. boot="${boot.result.result.value}" errors=${JSON.stringify(cdp.errors.slice(0, 3))}`,
+      );
+    }
+
+    // Warm up: let the RAF loop ramp before measuring fps / capturing (a fresh
+    // page reads ~1 fps until the WebGPU pipeline settles). Poll up to 6s.
+    let fps = 0;
+    {
+      const t0 = Date.now();
+      while (Date.now() - t0 < 6000) {
+        const r = await cdp.call(ws, 'Runtime.evaluate', {
+          expression: '(window.__TRISCOPE__.sampleTelemetry().perf||{}).fps || 0',
+          returnByValue: true,
+        });
+        fps = Math.max(fps, Number(r.result.result.value ?? 0));
+        if (fps >= 5) break;
+        await wait(300);
+      }
+    }
+
+    const capR = await cdp.call(ws, 'Runtime.evaluate', {
+      expression: 'window.__TRISCOPE__.captureViews()',
+      awaitPromise: true,
+      returnByValue: true,
+    });
+    const views = capR.result.result.value ?? {};
+    const cams = Object.keys(views);
+    if (cams.length === 0) throw new Error('captureViews returned no cameras');
+    mkdirSync(dirname(OUT), { recursive: true });
+    let wroteShot = false;
+    let fullSize = 0;
+    for (const c of cams) {
+      const du = views[c];
+      if (typeof du !== 'string' || !du.startsWith('data:image/png;base64,')) continue;
+      const buf = Buffer.from(du.slice('data:image/png;base64,'.length), 'base64');
+      if (!wroteShot) {
+        writeFileSync(OUT, buf);
+        wroteShot = true;
+      }
+      if (buf.readUInt32BE(16) >= 200 && buf.readUInt32BE(20) >= 100) fullSize++;
+    }
+
+    const probesR = await cdp.call(ws, 'Runtime.evaluate', {
+      expression: 'JSON.stringify(window.__TRISCOPE__.lastGpuProbes ?? {})',
+      returnByValue: true,
+    });
+    const gpuProbes = JSON.parse(probesR.result.result.value || '{}');
+    const black = Object.entries(gpuProbes)
+      .filter(([, s]) => s?.blackFrame || s?.luminance < BLACK)
+      .map(([c]) => c);
+
+    // The teardown "WebGPU Device Lost: ... destroyed" is cosmetic (documented
+    // in the README) and favicon 404s are noise — never fail on those.
+    const COSMETIC = /Device Lost|Device was destroyed|favicon\.ico/i;
+    const realErrors = cdp.errors.filter((e) => !COSMETIC.test(e));
+
+    console.log(
+      JSON.stringify(
+        {
+          url: targetUrl,
+          screenshot: OUT,
+          cameras: cams.length,
+          fullSize,
+          fps: +fps.toFixed(1),
+          blackFrames: black,
+          errors: realErrors.slice(0, 5),
+          headless,
+        },
+        null,
+        2,
+      ),
+    );
+
+    // Always: the harness mounted, declared cameras, and captureViews returned
+    // (asserted above) with no REAL console/runtime errors. Render-quality
+    // (non-black) is hard-gated only when HEADED — headless WebGPU readback is
+    // unreliable on Linux (black frames), per the project's own caveat.
+    if (realErrors.length > 0)
+      throw new Error(`console/runtime errors: ${realErrors.join(' | ').slice(0, 300)}`);
+    if (!headless && black.length > 0)
+      throw new Error(`camera(s) rendered black: ${black.join(', ')}`);
+    if (fps !== 0 && fps < 5) throw new Error(`fps ${fps} < 5 — renderer not stepping`);
+
+    await cdp.call(ws, 'Browser.close').catch(() => {});
+  } catch (err) {
+    console.error('smoke failed:', err.message);
+    exitCode = 1;
+  } finally {
+    try {
+      ws?.close();
+    } catch {}
+    if (chrome && !chrome.killed) chrome.kill();
+    if (vite && !vite.killed) {
+      try {
+        process.kill(-vite.pid, 'SIGTERM');
+      } catch {}
+      vite.kill('SIGTERM');
+    }
+  }
+  process.exit(exitCode);
+}

package/src/state.mjs

@@ -0,0 +1,46 @@
+// `triscope state [<jq-style path>]` — read /tmp/<project>-state.json.
+import { existsSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export function readProjectName(cwd) {
+  try {
+    const pkgPath = join(cwd, 'package.json');
+    if (!existsSync(pkgPath)) return 'triscope-project';
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return String(pkg.name ?? 'triscope-project').replace(/[^A-Za-z0-9._-]/g, '-');
+  } catch {
+    return 'triscope-project';
+  }
+}
+
+export function applyPath(data, path) {
+  if (!path) return data;
+  const segs = path.replace(/^\./, '').split('.').filter(Boolean);
+  let cur = data;
+  for (const s of segs) {
+    if (cur == null) return undefined;
+    cur = cur[s];
+  }
+  return cur;
+}
+
+export async function runState({ path }) {
+  const project = readProjectName(process.cwd());
+  const statePath = join(tmpdir(), `${project}-state.json`);
+  if (!existsSync(statePath)) {
+    console.error(`No telemetry found at ${statePath}. Is the dev server running?`);
+    process.exit(1);
+  }
+  const data = JSON.parse(readFileSync(statePath, 'utf8'));
+  const slice = applyPath(data, path);
+  if (slice === undefined) {
+    console.error(`Path "${path}" not found in telemetry.`);
+    process.exit(2);
+  }
+  if (slice === null || typeof slice !== 'object') {
+    console.log(slice);
+  } else {
+    console.log(JSON.stringify(slice, null, 2));
+  }
+}

package/src/wizard.mjs

@@ -0,0 +1,101 @@
+// `triscope init --quick` post-scaffold setup wizard.
+//
+// The cardinal rule: NEVER block on stdin in a non-interactive context. A
+// readline prompt in CI / a piped invocation would hang forever, so we resolve
+// the mode up front and only prompt on a real TTY.
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+
+/** off | interactive | auto | skip — decided before any prompt is shown. */
+export function resolveQuickMode({ quick, yes, isTTY }) {
+  if (!quick) return 'off';
+  if (yes) return 'auto';
+  if (isTTY) return 'interactive';
+  return 'skip'; // non-TTY without --yes: do not prompt, do not hang
+}
+
+/** Safe, non-browser setup steps. (smoke/open need a browser → left to the user.) */
+export function quickSteps() {
+  return [
+    { id: 'install', label: 'Install dependencies (npm install)', default: true },
+    {
+      id: 'mcp',
+      label: 'Register the triscope MCP server + auto-capture hook (project scope)',
+      default: true,
+    },
+  ];
+}
+
+function ask(rl, question, defaultYes) {
+  const suffix = defaultYes ? '[Y/n]' : '[y/N]';
+  return new Promise((res) => {
+    rl.question(`  ${question} ${suffix} `, (answer) => {
+      const a = answer.trim().toLowerCase();
+      if (a === '') res(defaultYes);
+      else res(a === 'y' || a === 'yes');
+    });
+  });
+}
+
+function spawnAndWait(cmd, args, opts = {}) {
+  return new Promise((res, rej) => {
+    const p = spawn(cmd, args, { stdio: 'inherit', ...opts });
+    p.on('exit', (code) => (code === 0 ? res() : rej(new Error(`${cmd} exited ${code}`))));
+    p.on('error', rej);
+  });
+}
+
+function nextStepsMessage() {
+  // The base scaffolder already printed the cd/install/dev steps; add only the
+  // quick-setup-specific pointer so we don't duplicate the whole block.
+  return [
+    '',
+    'Tip: run setup non-interactively with:  triscope init <dir> --quick --yes',
+    '     (installs deps + registers the MCP server + auto-capture hook)',
+    '     then `triscope dev --check` to verify.',
+  ].join('\n');
+}
+
+/**
+ * Run the quick-setup steps. `mode` comes from resolveQuickMode(); in 'skip'
+ * we only print guidance. The cli bin path is resolved so we can invoke
+ * `triscope mcp install` even when triscope isn't on PATH.
+ */
+export async function runQuickSetup({ target, mode }) {
+  if (mode === 'skip' || mode === 'off') {
+    console.log(nextStepsMessage());
+    return;
+  }
+  const steps = quickSteps();
+  let decisions;
+  if (mode === 'auto') {
+    decisions = Object.fromEntries(steps.map((s) => [s.id, s.default]));
+  } else {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    decisions = {};
+    try {
+      for (const s of steps) decisions[s.id] = await ask(rl, `${s.label}?`, s.default);
+    } finally {
+      rl.close();
+    }
+  }
+
+  if (decisions.install) {
+    console.log('\n→ npm install…');
+    await spawnAndWait('npm', ['install'], { cwd: target });
+  }
+  if (decisions.mcp) {
+    const cliBin = resolve(fileURLToPath(import.meta.url), '../../bin/triscope.mjs');
+    console.log('\n→ triscope mcp install --project…');
+    try {
+      await spawnAndWait(process.execPath, [cliBin, 'mcp', 'install', '--project'], {
+        cwd: target,
+      });
+    } catch (e) {
+      console.warn(`  (mcp install skipped: ${e?.message ?? e})`);
+    }
+  }
+  console.log(`\n✓ ${target} ready. Run \`npm run dev\` then \`triscope dev --check\`.`);
+}