@triscope/cli 0.4.0

package/src/gltf-scaffold.mjs

@@ -0,0 +1,189 @@
+// `triscope new-gltf <file.glb>` — generate a wired triscope Element from a
+// glTF/GLB asset. Reads the asset's bounds + animation names WITHOUT a renderer
+// or a heavy dep (GLB is a binary container whose first chunk is the glTF JSON),
+// then emits a ready-to-edit Element that GLTFLoads the model, auto-fits cameras
+// to the bounds, and plays the first animation clip.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, extname, join } from 'node:path';
+
+const GLB_MAGIC = 0x46546c67; // 'glTF'
+const JSON_CHUNK = 0x4e4f534a; // 'JSON'
+
+/** Extract { animations, bounds, meshCount } from a .glb or .gltf buffer. */
+export function readGltfMeta(buf) {
+  let json;
+  if (buf.length >= 20 && buf.readUInt32LE(0) === GLB_MAGIC) {
+    const chunkLen = buf.readUInt32LE(12);
+    const chunkType = buf.readUInt32LE(16);
+    if (chunkType !== JSON_CHUNK) throw new Error('first GLB chunk is not JSON');
+    json = JSON.parse(buf.subarray(20, 20 + chunkLen).toString('utf8'));
+  } else {
+    json = JSON.parse(buf.toString('utf8'));
+  }
+  const animations = (json.animations ?? []).map((a, i) => a.name || `clip${i}`);
+  const accessors = json.accessors ?? [];
+  const min = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
+  const max = [Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY];
+  let found = false;
+  for (const mesh of json.meshes ?? []) {
+    for (const prim of mesh.primitives ?? []) {
+      const ai = prim.attributes?.POSITION;
+      if (ai == null) continue;
+      const acc = accessors[ai];
+      if (Array.isArray(acc?.min) && Array.isArray(acc?.max) && acc.min.length === 3) {
+        found = true;
+        for (let k = 0; k < 3; k++) {
+          if (acc.min[k] < min[k]) min[k] = acc.min[k];
+          if (acc.max[k] > max[k]) max[k] = acc.max[k];
+        }
+      }
+    }
+  }
+  return { animations, bounds: found ? { min, max } : null, meshCount: (json.meshes ?? []).length };
+}
+
+function camerasFor(bounds) {
+  // Fitted presets around the asset's bounds (or a unit box fallback).
+  const b = bounds ?? { min: [-1, -1, -1], max: [1, 1, 1] };
+  const c = [0, 1, 2].map((k) => (b.min[k] + b.max[k]) / 2);
+  const size = Math.max(...[0, 1, 2].map((k) => b.max[k] - b.min[k]), 1);
+  const d = size * 1.8;
+  const t = `[${c[0].toFixed(2)}, ${c[1].toFixed(2)}, ${c[2].toFixed(2)}]`;
+  return `  cameras: {
+    front: { position: [${c[0].toFixed(2)}, ${c[1].toFixed(2)}, ${(c[2] + d).toFixed(2)}], target: ${t}, fit: true },
+    side: { position: [${(c[0] + d).toFixed(2)}, ${c[1].toFixed(2)}, ${c[2].toFixed(2)}], target: ${t}, fit: true },
+    top: { position: [${c[0].toFixed(2)}, ${(c[1] + d).toFixed(2)}, ${c[2].toFixed(2)}], target: ${t}, fit: true },
+    'three-quarter': { position: [${(c[0] + d * 0.7).toFixed(2)}, ${(c[1] + d * 0.5).toFixed(2)}, ${(c[2] + d * 0.7).toFixed(2)}], target: ${t}, fit: true },
+  },`;
+}
+
+export function gltfElementSource({ name, assetPath, meta }) {
+  const bounds = meta.bounds
+    ? `  bounds: { min: [${meta.bounds.min.join(', ')}], max: [${meta.bounds.max.join(', ')}] },`
+    : '  // bounds: set me — the asset declared no POSITION accessor min/max';
+  const hasAnim = meta.animations.length > 0;
+  return `// Generated by \`triscope new-gltf\`. Edit freely.
+import type { Element } from '@triscope/core';
+import * as THREE from 'three/webgpu';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+
+// Served from /public (vite serves it at the site root).
+const ASSET_URL = ${JSON.stringify(assetPath)};
+
+interface ${cap(name)}Data {
+  root: THREE.Group;
+  mixer: THREE.AnimationMixer | null;
+  scale: number;
+  clips: THREE.AnimationClip[];
+}
+
+export const ${name}: Element = {
+  name: '${name}',
+${bounds}
+
+  mount: ({ parent }) => {
+    const root = new THREE.Group();
+    parent.add(root);
+    const u: ${cap(name)}Data = { root, mixer: null, scale: 1, clips: [] };
+
+    new GLTFLoader().load(
+      ASSET_URL,
+      (gltf) => {
+        root.add(gltf.scene);
+        u.clips = gltf.animations ?? [];
+        ${hasAnim ? `if (u.clips.length) { u.mixer = new THREE.AnimationMixer(gltf.scene); u.mixer.clipAction(u.clips[0]).play(); }` : '// no animations in this asset'}
+      },
+      undefined,
+      (err) => console.error('GLTF load failed:', err),
+    );
+
+    // Advance the animation mixer each frame (CPU-integrated → use capture_motion mode:'real').
+    let last = performance.now();
+    const tick = () => {
+      const now = performance.now();
+      if (u.mixer) u.mixer.update((now - last) / 1000);
+      last = now;
+      requestAnimationFrame(tick);
+    };
+    requestAnimationFrame(tick);
+
+    return {
+      root,
+      userData: u as unknown as Record<string, unknown>,
+      dispose: () => {
+        parent.remove(root);
+        root.traverse((o) => {
+          const m = o as THREE.Mesh;
+          m.geometry?.dispose?.();
+          const mat = m.material as THREE.Material | THREE.Material[] | undefined;
+          if (Array.isArray(mat)) mat.forEach((x) => x.dispose?.());
+          else mat?.dispose?.();
+        });
+      },
+    };
+  },
+
+${camerasFor(meta.bounds)}
+
+  knobs: {
+    scale: { type: 'number', min: 0.1, max: 5, step: 0.1, default: 1, label: 'scale' },${
+      hasAnim
+        ? `\n    // clips: ${JSON.stringify(meta.animations)} — wire a picker if you want`
+        : ''
+    }
+  },
+
+  onKnob: (handle, key, value) => {
+    const u = handle.userData as unknown as ${cap(name)}Data;
+    if (key === 'scale') u.root.scale.setScalar(Number(value));
+  },
+
+  telemetry: (handle) => {
+    const u = handle.userData as unknown as ${cap(name)}Data;
+    return { scale: u.scale, hasModel: u.root.children.length > 0, clips: u.clips.length };
+  },
+};
+`;
+}
+
+function cap(s) {
+  return s.replace(/[^A-Za-z0-9]/g, '_').replace(/^./, (c) => c.toUpperCase());
+}
+
+export async function runGltfScaffold({ file, name: nameOverride, cwd = process.cwd() }) {
+  if (!file) {
+    console.error('Usage: triscope new-gltf <file.glb> [--name <n>]');
+    process.exit(2);
+  }
+  if (!existsSync(file)) {
+    console.error(`asset not found: ${file}`);
+    process.exit(2);
+  }
+  const meta = readGltfMeta(readFileSync(file));
+  // Whitelist the extension — never let a crafted filename's "extension" flow
+  // into the copied filename or the generated source.
+  const rawExt = extname(file).toLowerCase();
+  const ext = rawExt === '.gltf' ? '.gltf' : '.glb';
+  const name = (nameOverride ?? basename(file, extname(file))).replace(/[^A-Za-z0-9_-]/g, '-');
+
+  // Copy the asset into /public so vite serves it at /<name><ext>.
+  const publicDir = join(cwd, 'public');
+  mkdirSync(publicDir, { recursive: true });
+  const assetFile = `${name}${ext}`;
+  copyFileSync(file, join(publicDir, assetFile));
+  const assetPath = `/${assetFile}`;
+
+  const elPath = join(cwd, 'src', 'elements', `${name}.ts`);
+  mkdirSync(dirname(elPath), { recursive: true });
+  writeFileSync(elPath, gltfElementSource({ name, assetPath, meta }));
+
+  console.log(`generated element "${name}" from ${file}`);
+  console.log(`  + ${elPath}`);
+  console.log(`  + ${join(publicDir, assetFile)}`);
+  console.log(`  bounds: ${meta.bounds ? JSON.stringify(meta.bounds) : '(none — set manually)'}`);
+  console.log(`  animations: ${meta.animations.length ? meta.animations.join(', ') : '(none)'}`);
+  console.log(
+    `  next: triscope import is for packages; add a lab — copy labs/cube.html → labs/${name}.html`,
+  );
+  return { name, elPath, meta };
+}

package/src/import-element.mjs

@@ -0,0 +1,193 @@
+// `triscope import <pkg|github>` — install a published element package and wire
+// it into the current project (lab page + vite input + package.json#triscope.labs).
+// The naming convention is `triscope-element-<name>`; the package default-exports
+// an Element. The pure helpers are unit-tested; runImport spawns `npm install`.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+const GH_SHORTHAND = /^[\w-]+\/[\w.-]+(#[\w./-]+)?$/;
+// Strict allowlists for what we'll hand to `npm install`. No leading dash (flag
+// smuggling), no shell metacharacters, no glob `*`.
+const NPM_SPEC = /^(@[\w.-]+\/)?[\w.-]+(@[\w.^~-]+)?$/;
+const GH_SPEC = /^github:[\w.-]+\/[\w.-]+(#[\w./-]+)?$/;
+
+/** Reject anything that isn't a plain npm/github install spec (no flags, no shell chars). */
+export function assertSafeInstallSpec(spec) {
+  if (
+    typeof spec !== 'string' ||
+    spec.startsWith('-') ||
+    !(NPM_SPEC.test(spec) || GH_SPEC.test(spec))
+  ) {
+    throw new Error(
+      `refusing unsafe install spec ${JSON.stringify(spec)} — expected a plain package name, name@version, or github:user/repo[#ref]`,
+    );
+  }
+}
+
+export function parseElementSource(source, nameOverride) {
+  let kind = 'npm';
+  let installSpec = source;
+  let pkgName = source;
+  if (source.startsWith('github:') || GH_SHORTHAND.test(source)) {
+    kind = 'github';
+    installSpec = source.startsWith('github:') ? source : `github:${source}`;
+    pkgName = installSpec.replace(/^github:/, '').split('#')[0];
+  } else {
+    // strip a trailing version range (pkg@1.2.3) but keep an @scope
+    pkgName = source.replace(/(?<!^)@[\^~]?\d[\w.-]*$/, '');
+  }
+  const base = pkgName.split('/').pop();
+  const name = nameOverride ?? base.replace(/^triscope-element-/, '');
+  return { kind, installSpec, pkgName, name };
+}
+
+export function labEntry(name, pkgName) {
+  return `import { runLab } from '@triscope/core';
+import element from ${JSON.stringify(pkgName)};
+
+const canvas = document.getElementById('canvas');
+runLab({
+  element,
+  canvas,
+  hud: document.getElementById('hud'),
+  labelContainer: document.getElementById('app'),
+  editorContainer: document.getElementById('lab-controls'),
+  bootOverlay: document.getElementById('boot'),
+}).catch((e) => {
+  const b = document.getElementById('boot');
+  if (b) b.textContent = 'Init failed: ' + (e?.message ?? e);
+  console.error(e);
+});
+`;
+}
+
+export function labHtml(name) {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>${name} lab</title>
+    <style>
+      html, body { margin: 0; padding: 0; overflow: hidden; background: #000; color: #cfd6db; font-family: ui-monospace, monospace; }
+      #app { position: fixed; inset: 0; }
+      canvas { display: block; width: 100%; height: 100%; }
+      .triscope-label { position: absolute; background: rgba(0,0,0,.55); color: #cfd6db; padding: 4px 8px; font-size: 11px; pointer-events: none; border-radius: 3px; z-index: 5; }
+      #hud { position: fixed; bottom: 8px; left: 8px; z-index: 10; font-size: 11px; padding: 4px 8px; background: rgba(0,0,0,.55); border-radius: 3px; }
+      #boot { position: fixed; inset: 0; display: flex; align-items: center; justify-content: center; background: #0a1a20; z-index: 50; }
+      #lab-controls { position: fixed; right: 8px; bottom: 8px; z-index: 20; width: min(320px, calc(100vw - 24px)); padding: 10px 12px; background: rgba(5,12,16,.78); border: 1px solid rgba(210,230,240,.16); border-radius: 6px; box-sizing: border-box; }
+      .triscope-editor__row { display: grid; grid-template-columns: 110px 1fr 56px; align-items: center; gap: 6px; font-size: 11px; margin: 4px 0; }
+      .triscope-editor__row input { width: 100%; accent-color: #8fc7d9; }
+      .triscope-editor__row output { text-align: right; color: #f0f5f7; }
+    </style>
+  </head>
+  <body>
+    <div id="boot">Initialising Triscope · WebGPU...</div>
+    <div id="app"><canvas id="canvas"></canvas></div>
+    <div id="hud">- fps · WebGPU</div>
+    <div id="lab-controls"></div>
+    <script type="module" src="/src/labs/${name}.ts"></script>
+  </body>
+</html>
+`;
+}
+
+export function injectLabInput(viteText, name) {
+  if (viteText.includes(`labs/${name}.html`)) return viteText;
+  const line = `        ${name}: 'labs/${name}.html',`;
+  return viteText.replace(/(\n[ \t]*index: 'index\.html',)/, `$1\n${line}`);
+}
+
+/**
+ * Idempotently add `triscopeTelemetryPlugin()` to an existing vite.config's
+ * `plugins: [...]` (the one piece `triscope adopt` can't get for free). Returns
+ * { text, injected, already?, manual? }: if there's no `plugins:` array we don't
+ * touch the file and hand back a `manual` patch string instead of guessing.
+ */
+export function injectTelemetryPlugin(viteText) {
+  if (/triscopeTelemetryPlugin/.test(viteText)) {
+    return { text: viteText, injected: false, already: true };
+  }
+  const importLine = "import { triscopeTelemetryPlugin } from '@triscope/core/vite';\n";
+  const manual = {
+    text: viteText,
+    injected: false,
+    manual: `${importLine}…and add triscopeTelemetryPlugin() to your Vite \`plugins: []\` array.`,
+  };
+  // Find the FIRST `plugins: [` on a non-comment line (so we don't inject into a
+  // commented-out array, which would be a silent no-op). If none, hand back a
+  // manual patch instead of guessing/corrupting.
+  const m = /^(?![ \t]*(?:\/\/|\*)).*?\bplugins\s*:\s*\[/m.exec(viteText);
+  if (!m) return manual;
+  const at = m.index + m[0].length; // just past the opening `[`
+  const withPlugin = `${viteText.slice(0, at)}triscopeTelemetryPlugin(), ${viteText.slice(at)}`;
+  // Add the import after the first existing import (or prepend).
+  const text = /^[ \t]*import\s/m.test(withPlugin)
+    ? withPlugin.replace(/^([ \t]*import\s.*\n)/m, `$1${importLine}`)
+    : importLine + withPlugin;
+  return { text, injected: true };
+}
+
+export function wireProjectLabs(cwd, name) {
+  const p = join(cwd, 'package.json');
+  if (!existsSync(p)) return;
+  const pkg = JSON.parse(readFileSync(p, 'utf8'));
+  pkg.triscope ??= {};
+  pkg.triscope.labs ??= {};
+  pkg.triscope.labs[name] = `/labs/${name}.html`;
+  writeFileSync(p, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+export async function runImport({
+  source,
+  name: nameOverride,
+  install = true,
+  cwd = process.cwd(),
+}) {
+  if (!source) {
+    console.error('Usage: triscope import <pkg|github:user/repo> [--name <n>] [--no-install]');
+    process.exit(2);
+  }
+  const { installSpec, pkgName, name } = parseElementSource(source, nameOverride);
+  // Always validate — installSpec/pkgName also flow into the generated lab
+  // import, so a malicious value must be rejected even with --no-install.
+  assertSafeInstallSpec(installSpec);
+
+  if (install) {
+    // Harden against argv flag smuggling / shell injection: pass `--` so npm
+    // can't read it as a flag, and spawn npm WITHOUT a shell (explicit npm.cmd
+    // on Windows) so there's no shell to inject into.
+    console.log(`installing ${installSpec}…`);
+    const npmBin = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const r = spawnSync(npmBin, ['install', '--', installSpec], { cwd, stdio: 'inherit' });
+    if (r.status !== 0) {
+      console.error(`npm install ${installSpec} failed (${r.status}).`);
+      process.exit(1);
+    }
+  }
+
+  const created = [];
+  const htmlPath = join(cwd, 'labs', `${name}.html`);
+  mkdirSync(dirname(htmlPath), { recursive: true });
+  writeFileSync(htmlPath, labHtml(name));
+  created.push(htmlPath);
+
+  const entryPath = join(cwd, 'src', 'labs', `${name}.ts`);
+  mkdirSync(dirname(entryPath), { recursive: true });
+  writeFileSync(entryPath, labEntry(name, pkgName));
+  created.push(entryPath);
+
+  const vitePath = ['vite.config.js', 'vite.config.ts', 'vite.config.mjs']
+    .map((f) => join(cwd, f))
+    .find((f) => existsSync(f));
+  if (vitePath) {
+    writeFileSync(vitePath, injectLabInput(readFileSync(vitePath, 'utf8'), name));
+    created.push(`${vitePath} (lab input)`);
+  }
+  wireProjectLabs(cwd, name);
+
+  console.log(`imported "${name}" from ${pkgName}.`);
+  for (const c of created) console.log(`  + ${c}`);
+  console.log(`  open /labs/${name}.html (or: triscope smoke ${name})`);
+  return { name, pkgName, created };
+}

package/src/init.mjs

@@ -0,0 +1,78 @@
+// `triscope init <dir>` — thin wrapper around create-triscope so users
+// don't have to remember `npm init triscope` vs `npx create-triscope`.
+import { spawn } from 'node:child_process';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveQuickMode, runQuickSetup } from './wizard.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+// In a hoisted monorepo install, create-triscope sits next to cli inside
+// the same node_modules root. In a published install, it lives at
+// `<consumer>/node_modules/create-triscope`. We try both.
+export function locateScaffolderBin() {
+  const candidates = [
+    // monorepo / workspace layout (cli/src/init.mjs → ../../create-triscope)
+    resolve(HERE, '../../create-triscope/bin/create.mjs'),
+    // hoisted into the consumer's node_modules
+    resolve(process.cwd(), 'node_modules/create-triscope/bin/create.mjs'),
+  ];
+  for (const p of candidates) {
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+export async function runInit({ dir, install, quick, yes, preset }) {
+  if (!dir) {
+    console.error('Usage: triscope init <project-dir> [--install]');
+    process.exit(2);
+  }
+  const target = resolve(process.cwd(), dir);
+  // create-triscope itself rejects non-empty dirs; we warn early so the
+  // user sees the failure before we spawn the scaffolder. Only the
+  // readdirSync call can plausibly fail (permission errors) — handle
+  // *that* narrowly instead of wrapping process.exit, which earlier
+  // wrapping was silently swallowing.
+  if (existsSync(target) && statSync(target).isDirectory()) {
+    let entries;
+    try {
+      entries = readdirSync(target);
+    } catch {
+      entries = null;
+    }
+    if (entries && entries.length > 0) {
+      console.error(`refusing: ${target} exists and is not empty`);
+      process.exit(2);
+    }
+  }
+
+  const presetArgs = preset ? ['--preset', preset] : [];
+  const bin = locateScaffolderBin();
+  if (bin) {
+    await spawnAndWait(process.execPath, [bin, dir, ...presetArgs]);
+  } else {
+    // Fall back to `npm init triscope` so users without the workspace can
+    // still bootstrap (npm will fetch create-triscope from the registry).
+    await spawnAndWait('npm', ['init', 'triscope', dir, ...presetArgs]);
+  }
+
+  // --quick runs the post-scaffold setup wizard (interactive on a TTY, safe
+  // non-interactive defaults with --yes, and a never-hang "skip" otherwise).
+  const mode = resolveQuickMode({ quick: !!quick, yes: !!yes, isTTY: !!process.stdin.isTTY });
+  if (mode !== 'off') {
+    await runQuickSetup({ target, mode });
+  } else if (install) {
+    console.log('');
+    console.log(`running \`npm install\` in ${dir}…`);
+    await spawnAndWait('npm', ['install'], { cwd: target });
+  }
+}
+
+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);
+  });
+}

package/src/list.mjs

@@ -0,0 +1,21 @@
+// `triscope list` — print the live element manifest from the running dev server.
+export async function runList({ url = 'http://localhost:5173' } = {}) {
+  const endpoint = `${url.replace(/\/$/, '')}/__manifest`;
+  let res;
+  try {
+    res = await fetch(endpoint);
+  } catch (err) {
+    console.error(`Could not reach ${endpoint}. Is \`triscope dev\` running?`);
+    process.exit(1);
+  }
+  if (!res.ok) {
+    console.error(`${endpoint} returned ${res.status}`);
+    process.exit(1);
+  }
+  const manifest = await res.json();
+  if (manifest == null) {
+    console.error('Dev server is up but no manifest has been posted yet. Load a lab page first.');
+    process.exit(2);
+  }
+  console.log(JSON.stringify(manifest, null, 2));
+}