@triscope/cli 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 triscope contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @triscope/cli
+
+The `triscope` command-line tool for [triscope](https://github.com/tedin7/triscope)
+projects.
+
+```sh
+npx triscope <command>
+```
+
+## Commands
+
+- **`dev`** — start the Vite dev server with the telemetry plugin wired in
+  (`dev --check` runs a preflight first).
+- **`list`** — print the element manifest of the running lab.
+- **`state [<jq-path>]`** — read the live telemetry snapshot (or one path of it).
+- **`import <spec>`** — pull in a published/GitHub element package and wire a lab page.
+- **`adopt`** — retrofit an existing Vite + Three project: inject the telemetry
+  plugin and scaffold a `runSceneView` lab.
+- **`smoke`** — headless boot + capture sanity check.
+
+Pairs with [`@triscope/core`](https://www.npmjs.com/package/@triscope/core) (the
+lab runtime) and [`@triscope/mcp`](https://www.npmjs.com/package/@triscope/mcp)
+(the AI tool surface). MIT.

package/bin/triscope.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+import { runAdopt } from '../src/adopt.mjs';
+import { runAutoCapture } from '../src/auto-capture.mjs';
+// Triscope CLI entry. Pure ESM JS — no build step.
+import { runDev } from '../src/dev.mjs';
+import { runFigma } from '../src/figma.mjs';
+import { runGltfScaffold } from '../src/gltf-scaffold.mjs';
+import { runImport } from '../src/import-element.mjs';
+import { runInit } from '../src/init.mjs';
+import { runList } from '../src/list.mjs';
+import { runMcp } from '../src/mcp.mjs';
+import { parseFlags } from '../src/parse-flags.mjs';
+import { runSmoke } from '../src/smoke.mjs';
+import { runState } from '../src/state.mjs';
+
+const [, , subcommand, ...rest] = process.argv;
+
+const HELP = `triscope — multi-angle 3D iteration framework
+
+USAGE
+  triscope <command> [options]
+
+COMMANDS
+  init <dir> [--install]    Scaffold a new triscope project in <dir>. Wraps
+                            create-triscope. With --install, also runs
+                            \`npm install\`. With --quick, run a setup wizard
+                            (deps + MCP + hook); add --yes for non-interactive.
+  dev [--check]             Start the Vite dev server (in the current project).
+                            With --check, run the preflight checklist (Node,
+                            deps, chromium, MCP, port) and exit instead.
+  adopt [--name <n>]        Retrofit triscope onto an EXISTING Vite + Three
+                            project: inject the telemetry plugin + scaffold a
+                            runSceneView lab. Then point it at your scene.
+  import <pkg|github>       Install a published element package
+                            (triscope-element-<name> or github:user/repo) and
+                            wire its lab + vite input. [--name <n>] [--no-install]
+  new-gltf <file.glb>       Generate a wired Element from a glTF/GLB asset
+                            (bounds + animations auto-detected). [--name <n>]
+  new-figma <key> <node>    Export a Figma node (needs FIGMA_TOKEN) as a PNG and
+                            scaffold a textured-plane Element. [--name <n>]
+  state [<jq.path>]         Read /tmp/<project>-state.json. With a path
+                            (e.g. ".elements.ship.triangles"), prints just
+                            that slice.
+  list                      Print the current scene manifest (elements,
+                            cameras, knobs) from the running dev server.
+  smoke [<element>]         Run the headed-Chromium smoke harness against a
+                            lab page. Defaults to the scene lab. Element
+                            argument picks /labs/<element>.html.
+  mcp install [--project]   Register the triscope MCP server with Claude Code
+                            (user scope by default; --project writes .mcp.json
+                            in the cwd).
+  mcp uninstall             Remove the triscope MCP registration.
+  auto-capture [--file <p>] Print one-line motion summary from telemetry.
+                            Designed to wire as a Claude Code PostToolUse hook.
+
+OPTIONS
+  --url <url>               Override the dev server URL (default http://localhost:5173).
+  --port <n>                Override the Vite port for \`triscope dev\`.
+  --help, -h                Print this message.
+
+EXAMPLES
+  triscope dev
+  triscope state .perf.fps
+  triscope state .elements.ship
+  triscope list
+  triscope smoke ship
+  triscope smoke --url http://localhost:5174/labs/scene.html
+`;
+
+async function main() {
+  if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+    console.log(HELP);
+    return;
+  }
+  const { flags, positional } = parseFlags(rest);
+  if (flags.help) {
+    console.log(HELP);
+    return;
+  }
+  try {
+    switch (subcommand) {
+      case 'init':
+        await runInit({
+          dir: positional[0],
+          install: flags.install,
+          quick: flags.quick,
+          yes: flags.yes,
+          preset: flags.preset,
+        });
+        break;
+      case 'dev':
+        await runDev({ port: flags.port, check: flags.check });
+        break;
+      case 'adopt':
+        await runAdopt({ name: flags.name ?? 'scene' });
+        break;
+      case 'import':
+        await runImport({
+          source: positional[0],
+          name: flags.name,
+          install: flags['no-install'] !== true,
+        });
+        break;
+      case 'new-gltf':
+        await runGltfScaffold({ file: positional[0], name: flags.name });
+        break;
+      case 'new-figma':
+        await runFigma({ fileKey: positional[0], nodeId: positional[1], name: flags.name });
+        break;
+      case 'state':
+        await runState({ path: positional[0] });
+        break;
+      case 'list':
+        await runList({ url: flags.url });
+        break;
+      case 'smoke':
+        await runSmoke({ element: positional[0], url: flags.url, screenshot: flags.screenshot });
+        break;
+      case 'mcp':
+        await runMcp({
+          action: positional[0],
+          scope: flags.project ? 'project' : 'user',
+          url: flags.url,
+          withHook: flags['no-hook'] !== true,
+        });
+        break;
+      case 'auto-capture':
+        await runAutoCapture({ file: flags.file });
+        break;
+      default:
+        console.error(`Unknown command: ${subcommand}\n`);
+        console.log(HELP);
+        process.exit(2);
+    }
+  } catch (err) {
+    console.error(`triscope ${subcommand} failed:`, err?.message || err);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@triscope/cli",
+  "version": "0.4.0",
+  "description": "Triscope CLI: dev, state, list, smoke. Headed-Chromium WebGPU smoke harness for AI iteration.",
+  "type": "module",
+  "bin": {
+    "triscope": "./bin/triscope.mjs"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "pngjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.9",
+    "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "build": "echo \"cli: no build\" && exit 0",
+    "typecheck": "echo \"cli: pure ESM JS, no typecheck\" && exit 0",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text --coverage.reporter=html"
+  },
+  "keywords": [
+    "triscope",
+    "cli",
+    "three.js",
+    "webgpu",
+    "claude-code"
+  ]
+}

package/src/adopt.mjs

@@ -0,0 +1,127 @@
+// `triscope adopt` — retrofit triscope onto an EXISTING Vite + Three.js project
+// in one command: inject the telemetry plugin into vite.config (the one piece
+// you can't get for free), scaffold a `runSceneView`-based lab page + entry, and
+// wire it into rollupOptions.input + package.json#triscope.labs. After this the
+// MCP tools work; the generated entry renders a placeholder until you point
+// runSceneView at your own scene (see the `// TODO` in src/labs/<name>.ts).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import {
+  injectLabInput,
+  injectTelemetryPlugin,
+  labHtml,
+  wireProjectLabs,
+} from './import-element.mjs';
+
+const VITE_CONFIGS = ['vite.config.js', 'vite.config.ts', 'vite.config.mjs'];
+
+/** Lab entry that wraps a scene via runSceneView — placeholder until the user
+ *  swaps in their own object/builder. Renders a box+light so the lab is alive
+ *  (and MCP-pilotable) immediately, proving the adoption worked. */
+export function adoptLabEntry(name) {
+  return `// triscope lab generated by \`triscope adopt\`.
+// runSceneView wraps ANY THREE.Object3D (or a () => Object3D) into the lab —
+// no Element boilerplate. Replace getRoot() below with YOUR scene/group.
+import { runSceneView } from '@triscope/core';
+
+async function getRoot() {
+  // TODO: return your existing content here, e.g.:
+  //   import { buildScene } from '../scene.js';  return buildScene();
+  const THREE = await import('three/webgpu');
+  const g = new THREE.Group();
+  const mesh = new THREE.Mesh(
+    new THREE.BoxGeometry(1, 1, 1),
+    new THREE.MeshStandardMaterial({ color: 0xff8844, roughness: 0.5 }),
+  );
+  mesh.name = 'placeholder';
+  const key = new THREE.DirectionalLight(0xffffff, 2.2);
+  key.name = 'key';
+  key.position.set(2, 3, 4);
+  g.add(mesh, key, new THREE.AmbientLight(0x8899aa, 0.4));
+  return g;
+}
+
+runSceneView(await getRoot(), { name: ${JSON.stringify(name)}, autoKnobs: true }).catch((e) => {
+  const b = document.getElementById('boot');
+  if (b) b.textContent = 'Init failed: ' + (e?.message ?? e);
+  console.error(e);
+});
+`;
+}
+
+export async function runAdopt({ cwd = process.cwd(), name = 'scene' } = {}) {
+  if (!/^[a-z][\w-]*$/i.test(name)) {
+    console.error(`adopt: lab name must be [A-Za-z][\\w-]* (got ${JSON.stringify(name)})`);
+    process.exit(2);
+  }
+  const created = [];
+  const notes = [];
+
+  // 1. Telemetry plugin — the one piece adopt can't infer.
+  const vitePath = VITE_CONFIGS.map((f) => join(cwd, f)).find((f) => existsSync(f));
+  if (!vitePath) {
+    console.error(
+      'adopt: no vite.config.{js,ts,mjs} found. `triscope adopt` retrofits a Vite + Three project; for a fresh project use `npm create triscope`.',
+    );
+    process.exit(2);
+  }
+  const inj = injectTelemetryPlugin(readFileSync(vitePath, 'utf8'));
+  if (inj.injected) {
+    writeFileSync(vitePath, inj.text);
+    created.push(`${vitePath} (triscopeTelemetryPlugin)`);
+  } else if (inj.already) {
+    notes.push('vite.config already registers triscopeTelemetryPlugin ✓');
+  } else {
+    notes.push(`MANUAL vite.config patch needed — ${inj.manual}`);
+  }
+
+  // 2. Dependency check (don't auto-install; just tell the user).
+  const pkgPath = join(cwd, 'package.json');
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (!deps['@triscope/core']) notes.push('MISSING dependency — run: npm i @triscope/core three');
+  }
+
+  // 3. Scaffold lab page + runSceneView entry, wire vite input + labs (idempotent).
+  const htmlPath = join(cwd, 'labs', `${name}.html`);
+  if (existsSync(htmlPath)) {
+    notes.push(`${htmlPath} exists — left as-is`);
+  } else {
+    mkdirSync(dirname(htmlPath), { recursive: true });
+    writeFileSync(htmlPath, labHtml(name));
+    created.push(htmlPath);
+  }
+  const entryPath = join(cwd, 'src', 'labs', `${name}.ts`);
+  if (existsSync(entryPath)) {
+    notes.push(`${entryPath} exists — left as-is`);
+  } else {
+    mkdirSync(dirname(entryPath), { recursive: true });
+    writeFileSync(entryPath, adoptLabEntry(name));
+    created.push(entryPath);
+  }
+  if (vitePath) {
+    const v = injectLabInput(readFileSync(vitePath, 'utf8'), name);
+    writeFileSync(vitePath, v);
+    // injectLabInput is a no-op if it can't find `index: 'index.html'` to anchor
+    // to (e.g. a config with no rollupOptions.input). Dev + MCP work regardless
+    // (they resolve via triscope.labs); only the production `vite build` needs it.
+    if (!v.includes(`labs/${name}.html`)) {
+      notes.push(
+        `couldn't auto-add to rollupOptions.input — for \`vite build\`, add \`${name}: 'labs/${name}.html'\` to it manually (dev + MCP work without it)`,
+      );
+    }
+  }
+  wireProjectLabs(cwd, name);
+
+  console.log(`triscope adopt: wired lab "${name}".`);
+  for (const c of created) console.log(`  + ${c}`);
+  for (const n of notes) console.log(`  • ${n}`);
+  console.log('\nNext:');
+  console.log(`  1. point runSceneView at your scene in src/labs/${name}.ts (the // TODO)`);
+  console.log('  2. triscope dev --check   (verify Node/deps/chromium/MCP/port)');
+  console.log(
+    `  3. npm run dev  →  open /labs/${name}.html  →  drive it with the triscope MCP tools`,
+  );
+  return { name, created, notes };
+}

package/src/auto-capture.mjs

@@ -0,0 +1,74 @@
+// `triscope auto-capture` — minimal hook-friendly status print.
+//
+// Designed to be wired as a Claude Code PostToolUse hook that runs after
+// every Edit. Reads /tmp/<project>-state.json (already maintained by the
+// dev server) and prints a one-line motion summary per element that has
+// motionProbes declared. Cheap: no Chromium spawn, just a file read.
+//
+// Hook config example (settings.json or .claude/settings.local.json):
+//   {
+//     "hooks": {
+//       "PostToolUse": [{
+//         "matcher": "Edit|Write",
+//         "hooks": [{ "type": "command", "command": "triscope auto-capture" }]
+//       }]
+//     }
+//   }
+//
+// Optional `--file <path>` arg: filter so the hook only prints when an
+// edited file likely affects 3D state. Falls back to printing always.
+
+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 const RELEVANT = /\b(triscope|lab|scene|element|shader|mesh)/i;
+
+export function fmt(n) {
+  if (!Number.isFinite(n)) return '?';
+  return Number(n).toFixed(2);
+}
+
+export async function runAutoCapture({ file } = {}) {
+  // If a file path was passed and it doesn't look like 3D code, exit silently.
+  if (file && !RELEVANT.test(file)) return;
+
+  const project = readProjectName(process.cwd());
+  const statePath = join(tmpdir(), `${project}-state.json`);
+  if (!existsSync(statePath)) {
+    // No dev server running — the hook just stays quiet.
+    return;
+  }
+  let state;
+  try {
+    state = JSON.parse(readFileSync(statePath, 'utf8'));
+  } catch {
+    return;
+  }
+  const elements = state?.elements;
+  if (!elements || typeof elements !== 'object') return;
+
+  const lines = [];
+  for (const [name, payload] of Object.entries(elements)) {
+    const motion = payload?.motion;
+    if (!motion || typeof motion !== 'object') continue;
+    const probes = Object.entries(motion)
+      .filter(([, s]) => s && typeof s === 'object')
+      .map(([k, s]) => `${k} p2p=${fmt(s.peakToPeak)} freq=${fmt(s.dominantFreqHz)}Hz`)
+      .join(', ');
+    if (probes) lines.push(`[triscope] ${name} motion: ${probes}`);
+  }
+  if (state?.perf?.fps != null) lines.unshift(`[triscope] fps=${fmt(state.perf.fps)}`);
+  if (lines.length > 0) console.log(lines.join('\n'));
+}

package/src/dev.mjs

@@ -0,0 +1,23 @@
+// `triscope dev` — proxy to `vite` in the current project.
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { formatPreflight, runPreflight } from './preflight.mjs';
+
+export async function runDev({ port, check } = {}) {
+  const cwd = process.cwd();
+  // `triscope dev --check`: print the preflight checklist and exit (non-zero on
+  // any FAIL) without booting Vite — turns mid-session surprises into a gate.
+  if (check) {
+    const report = await runPreflight({ cwd, port: port ? Number(port) : 5173 });
+    console.log(formatPreflight(report));
+    process.exit(report.ok ? 0 : 1);
+  }
+  // Prefer locally-installed vite binary, fall back to PATH.
+  const localVite = resolve(cwd, 'node_modules/.bin/vite');
+  const vite = existsSync(localVite) ? localVite : 'vite';
+  const args = [];
+  if (port) args.push('--port', String(port));
+  const child = spawn(vite, args, { stdio: 'inherit' });
+  child.on('exit', (code) => process.exit(code ?? 0));
+}

package/src/figma.mjs

@@ -0,0 +1,124 @@
+// `triscope new-figma <fileKey> <nodeId>` — export a Figma node as a PNG (REST
+// images API, needs FIGMA_TOKEN) and scaffold an Element that shows it as a flat
+// TEXTURED PLANE (reference image / UI-in-3D). This is deliberately NOT
+// "2D design → 3D geometry" (impossible to infer); it brings the rendered node
+// into the scene as a plane you can frame, fade, and place. CLI-only by design
+// (no MCP tool) — keeps the tool surface lean and the token out of the agent.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export function figmaImageUrl(fileKey, nodeId, { scale = 2, format = 'png' } = {}) {
+  const q = new URLSearchParams({ ids: nodeId, format, scale: String(scale) });
+  return `https://api.figma.com/v1/images/${encodeURIComponent(fileKey)}?${q.toString()}`;
+}
+
+export function texturedPlaneSource({ name, assetPath }) {
+  return `// Generated by \`triscope new-figma\`. A Figma node exported as a flat
+// textured plane (reference image / UI-in-3D) — NOT geometry inferred from a
+// 2D design. Edit freely.
+import type { Element } from '@triscope/core';
+import * as THREE from 'three/webgpu';
+
+const ASSET_URL = ${JSON.stringify(assetPath)};
+
+interface ${cap(name)}Data {
+  mesh: THREE.Mesh;
+  material: THREE.MeshBasicMaterial;
+}
+
+export const ${name}: Element = {
+  name: '${name}',
+  bounds: { min: [-1, -0.6, -0.05], max: [1, 0.6, 0.05] },
+
+  mount: ({ parent }) => {
+    const geo = new THREE.PlaneGeometry(2, 1.2);
+    const material = new THREE.MeshBasicMaterial({ side: THREE.DoubleSide, transparent: true });
+    const mesh = new THREE.Mesh(geo, material);
+    parent.add(mesh);
+    new THREE.TextureLoader().load(ASSET_URL, (tex) => {
+      tex.colorSpace = THREE.SRGBColorSpace;
+      material.map = tex;
+      material.needsUpdate = true;
+      const img = tex.image as { width?: number; height?: number } | undefined;
+      if (img?.width && img?.height) mesh.scale.set(img.width / img.height, 1, 1);
+    });
+    return {
+      root: mesh,
+      userData: { mesh, material } as unknown as Record<string, unknown>,
+      dispose: () => {
+        parent.remove(mesh);
+        geo.dispose();
+        material.dispose();
+      },
+    };
+  },
+
+  cameras: {
+    front: { position: [0, 0, 3], target: [0, 0, 0] },
+    angle: { position: [2, 1, 3], target: [0, 0, 0] },
+  },
+
+  knobs: {
+    opacity: { type: 'number', min: 0, max: 1, step: 0.05, default: 1, label: 'opacity' },
+  },
+
+  onKnob: (handle, key, value) => {
+    const u = handle.userData as unknown as ${cap(name)}Data;
+    if (key === 'opacity') u.material.opacity = Number(value);
+  },
+};
+`;
+}
+
+function cap(s) {
+  return s.replace(/[^A-Za-z0-9]/g, '_').replace(/^./, (c) => c.toUpperCase());
+}
+
+export async function runFigma({
+  fileKey,
+  nodeId,
+  name: nameOverride,
+  scale = 2,
+  cwd = process.cwd(),
+}) {
+  const token = process.env.FIGMA_TOKEN;
+  if (!fileKey || !nodeId) {
+    console.error(
+      'Usage: triscope new-figma <fileKey> <nodeId> [--name <n>]   (needs FIGMA_TOKEN)',
+    );
+    process.exit(2);
+  }
+  if (!token) {
+    console.error('FIGMA_TOKEN env var is required (a Figma personal access token).');
+    process.exit(2);
+  }
+  const name = (nameOverride ?? `figma-${nodeId}`).replace(/[^A-Za-z0-9_-]/g, '-');
+
+  // 1. Ask Figma for a rendered image URL for the node.
+  const meta = await fetch(figmaImageUrl(fileKey, nodeId, { scale }), {
+    headers: { 'X-Figma-Token': token },
+  }).then((r) => r.json());
+  const imageUrl = meta?.images?.[nodeId];
+  if (meta?.err || !imageUrl) {
+    console.error(`Figma did not return an image for node ${nodeId}: ${meta?.err ?? 'no url'}`);
+    process.exit(1);
+  }
+
+  // 2. Download the rendered PNG into /public.
+  const bytes = Buffer.from(await (await fetch(imageUrl)).arrayBuffer());
+  const publicDir = join(cwd, 'public');
+  mkdirSync(publicDir, { recursive: true });
+  const assetFile = `${name}.png`;
+  writeFileSync(join(publicDir, assetFile), bytes);
+
+  // 3. Scaffold the textured-plane element.
+  const elPath = join(cwd, 'src', 'elements', `${name}.ts`);
+  mkdirSync(dirname(elPath), { recursive: true });
+  writeFileSync(elPath, texturedPlaneSource({ name, assetPath: `/${assetFile}` }));
+
+  console.log(`exported Figma node ${nodeId} → element "${name}"`);
+  console.log(`  + ${join(publicDir, assetFile)} (${(bytes.length / 1024).toFixed(0)} KB)`);
+  console.log(`  + ${elPath}`);
+  console.log('  note: this is a flat textured plane (reference/UI-in-3D), not inferred geometry.');
+  return { name, elPath };
+}