@1agh/maude 0.42.0 → 0.43.0

package/apps/studio/bin/_ingest-footage.mjs

@@ -0,0 +1,386 @@
+#!/usr/bin/env node
+// _ingest-footage.mjs — ingest a DIRECTORY of raw footage into the design root's
+// content-addressed asset store, behind `maude design ingest-footage` (DDR-062
+// dispatch). The folder-scale counterpart to `_fetch-asset.mjs` (single URL).
+//
+// feature-footage-analysis-director, Task 3. WHY THIS EXISTS: the `/design:reel`
+// director pipeline wants to start from a folder of client clips
+// (`/…/podklady/video`). This verb copies each recognised video (and any image/
+// audio) into `<designRoot>/assets/<sha8>.<ext>` — the SAME content-addressed
+// convention `/_api/asset` + `_fetch-asset.mjs` use, so a clip references
+// uniformly as `assets/<sha8>.mp4` on both the main and the canvas origin.
+//
+// SECURITY / DISCIPLINE (mirrors _fetch-asset.mjs):
+//   • magic-byte sniff decides the category + extension — the source name /
+//     extension is NEVER trusted (a `.mp4` that is really an HTML polyglot →
+//     skipped). Mirrors api.ts sniffAssetType (mp4/mov/m4v/webm video · mp3/wav/
+//     m4a audio · png/jpg/gif/webp image); SVG/script → null → skipped.
+//   • content-addressed `<sha8>.<ext>` name, `[a-z0-9._-]` only, written FLAT
+//     under assets/ with a realpath containment assertion.
+//   • per-file size cap (default 100 MB — the DDR-148 video ceiling); oversized
+//     files are SKIPPED LOUDLY (listed in the manifest), never silently dropped.
+//   • the source directory is READ-ONLY — this never writes back into it.
+//   • no network, no shell interpolation, no container parsing (magic bytes only).
+//
+// Reached via `maude design ingest-footage <dir> --root <repo>`, never a raw path.
+// stdout (default) = a JSON manifest { clips:[{asset,src,bytes,category}],
+// skipped:[{src,why}], assetsDir }. Exit: 0 ok (even with skips) · 2 usage ·
+// 6 write/containment error · 1 other.
+
+import { createHash } from 'node:crypto';
+import {
+  closeSync,
+  copyFileSync,
+  createReadStream,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readSync,
+  statSync,
+} from 'node:fs';
+import { extname, join, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// The DDR-148 video ceiling (100 MB). Images/audio also ride this generous cap
+// here — the reel pipeline's inputs are dominated by video. Override per-file
+// via --max-bytes.
+const DEFAULT_MAX_BYTES = 100 * 1024 * 1024;
+
+class IngestError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+// ── magic-byte sniff (mirrors apps/studio/api.ts sniffAssetType) ──────────────
+
+/** Sniff → { ext, category } or null. Bytes decide; name/extension untrusted. */
+export function sniffAsset(b) {
+  // Images (mirrors sniffImageType).
+  if (
+    b.length >= 8 &&
+    b[0] === 0x89 &&
+    b[1] === 0x50 &&
+    b[2] === 0x4e &&
+    b[3] === 0x47 &&
+    b[4] === 0x0d &&
+    b[5] === 0x0a &&
+    b[6] === 0x1a &&
+    b[7] === 0x0a
+  )
+    return { ext: 'png', category: 'image' };
+  if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff)
+    return { ext: 'jpg', category: 'image' };
+  if (
+    b.length >= 6 &&
+    b[0] === 0x47 &&
+    b[1] === 0x49 &&
+    b[2] === 0x46 &&
+    b[3] === 0x38 &&
+    (b[4] === 0x37 || b[4] === 0x39) &&
+    b[5] === 0x61
+  )
+    return { ext: 'gif', category: 'image' };
+  if (
+    b.length >= 12 &&
+    b[0] === 0x52 &&
+    b[1] === 0x49 &&
+    b[2] === 0x46 &&
+    b[3] === 0x46 &&
+    b[8] === 0x57 &&
+    b[9] === 0x45 &&
+    b[10] === 0x42 &&
+    b[11] === 0x50
+  )
+    return { ext: 'webp', category: 'image' };
+  // ISO-BMFF (mp4 / mov / m4a / m4v): "ftyp" at offset 4, brand at 8.
+  if (b.length >= 12 && b[4] === 0x66 && b[5] === 0x74 && b[6] === 0x79 && b[7] === 0x70) {
+    const brand = String.fromCharCode(b[8] ?? 0, b[9] ?? 0, b[10] ?? 0, b[11] ?? 0);
+    if (brand === 'qt  ') return { ext: 'mov', category: 'video' };
+    if (brand.startsWith('M4A')) return { ext: 'm4a', category: 'audio' };
+    if (brand.startsWith('M4V')) return { ext: 'm4v', category: 'video' };
+    return { ext: 'mp4', category: 'video' };
+  }
+  // Matroska / WebM — EBML header.
+  if (b.length >= 4 && b[0] === 0x1a && b[1] === 0x45 && b[2] === 0xdf && b[3] === 0xa3)
+    return { ext: 'webm', category: 'video' };
+  // MP3 — "ID3" or frame-sync.
+  if (b.length >= 3 && b[0] === 0x49 && b[1] === 0x44 && b[2] === 0x33)
+    return { ext: 'mp3', category: 'audio' };
+  if (b.length >= 2 && b[0] === 0xff && ((b[1] ?? 0) & 0xe0) === 0xe0)
+    return { ext: 'mp3', category: 'audio' };
+  // WAV.
+  if (
+    b.length >= 12 &&
+    b[0] === 0x52 &&
+    b[1] === 0x49 &&
+    b[2] === 0x46 &&
+    b[3] === 0x46 &&
+    b[8] === 0x57 &&
+    b[9] === 0x41 &&
+    b[10] === 0x56 &&
+    b[11] === 0x45
+  )
+    return { ext: 'wav', category: 'audio' };
+  return null;
+}
+
+// ── path helpers (mirror _fetch-asset.mjs containment) ───────────────────────
+
+/** Resolve `<root>/<designRootRel>/assets` with a containment assertion. */
+export function assetsDirFor(root, designRootRel) {
+  const rootAbs = resolve(root);
+  const assetsDir = resolve(rootAbs, designRootRel, 'assets');
+  if (assetsDir !== rootAbs && !assetsDir.startsWith(rootAbs + sep))
+    throw new IngestError(6, `assets dir escapes root: ${assetsDir}`);
+  return assetsDir;
+}
+
+/** Assert a content-addressed name and resolve it inside assets/ (no traversal). */
+export function containedName(assetsDir, name) {
+  if (!/^[a-z0-9]{8}\.(png|jpg|gif|webp|mp4|mov|m4v|webm|mp3|wav|m4a)$/.test(name))
+    throw new IngestError(6, `generated name failed the charset contract: ${name}`);
+  const fileAbs = resolve(assetsDir, name);
+  if (fileAbs !== join(assetsDir, name) || !fileAbs.startsWith(assetsDir + sep))
+    throw new IngestError(6, `resolved asset path escapes assets dir: ${fileAbs}`);
+  return fileAbs;
+}
+
+// ── sniff head + full-file hash (streamed — clips can be 100 MB) ─────────────
+
+/** Read the first `n` bytes of a file for the magic-byte sniff. */
+function readHead(file, n = 16) {
+  const fd = openSync(file, 'r');
+  try {
+    const buf = Buffer.alloc(n);
+    const bytesRead = readSync(fd, buf, 0, n, 0);
+    return buf.subarray(0, bytesRead);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** Full-file sha256 (streamed) → first 8 hex chars. */
+function hashFile(file) {
+  return new Promise((res, rej) => {
+    const h = createHash('sha256');
+    createReadStream(file)
+      .on('error', rej)
+      .on('data', (d) => h.update(d))
+      .on('end', () => res(h.digest('hex').slice(0, 8)));
+  });
+}
+
+// ── directory walk + ingest ──────────────────────────────────────────────────
+
+function listFiles(dir, recursive) {
+  const out = [];
+  const walk = (d) => {
+    let entries;
+    try {
+      entries = readdirSync(d, { withFileTypes: true });
+    } catch (e) {
+      throw new IngestError(2, `cannot read directory ${d}: ${e?.message ?? e}`);
+    }
+    for (const ent of entries) {
+      if (ent.name.startsWith('.')) continue; // skip dotfiles / .DS_Store
+      const abs = join(d, ent.name);
+      if (ent.isDirectory()) {
+        if (recursive) walk(abs);
+      } else if (ent.isFile()) {
+        out.push(abs);
+      }
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+/**
+ * Ingest every recognised media file under `dir` into assets/. Returns
+ * { clips, skipped, assetsDir }. Never throws on a per-file problem (that file
+ * is skipped with a reason); throws IngestError only for whole-run failures
+ * (unreadable dir, containment breach).
+ */
+export async function ingestFootage({
+  dir,
+  root,
+  designRootRel = '.design',
+  maxBytes = DEFAULT_MAX_BYTES,
+  recursive = false,
+}) {
+  const srcDir = resolve(dir);
+  if (!existsSync(srcDir) || !statSync(srcDir).isDirectory())
+    throw new IngestError(2, `not a directory: ${srcDir}`);
+
+  const assetsDir = assetsDirFor(root, designRootRel);
+  mkdirSync(assetsDir, { recursive: true });
+
+  const clips = [];
+  const skipped = [];
+  const seen = new Set(); // sha8 dedupe within this run
+
+  for (const file of listFiles(srcDir, recursive)) {
+    let size;
+    try {
+      size = statSync(file).size;
+    } catch (e) {
+      skipped.push({ src: file, why: `stat failed: ${e?.message ?? e}` });
+      continue;
+    }
+    if (size === 0) {
+      skipped.push({ src: file, why: 'empty file' });
+      continue;
+    }
+    if (size > maxBytes) {
+      skipped.push({
+        src: file,
+        why: `exceeds the ${Math.round(maxBytes / (1024 * 1024))} MB per-file cap (${Math.round(size / (1024 * 1024))} MB)`,
+      });
+      continue;
+    }
+    let info;
+    try {
+      info = sniffAsset(readHead(file));
+    } catch (e) {
+      skipped.push({ src: file, why: `read failed: ${e?.message ?? e}` });
+      continue;
+    }
+    if (!info) {
+      skipped.push({
+        src: file,
+        why: `unrecognised media (not video/image/audio); ext ${extname(file) || '(none)'}`,
+      });
+      continue;
+    }
+    let sha8;
+    try {
+      sha8 = await hashFile(file);
+    } catch (e) {
+      skipped.push({ src: file, why: `hash failed: ${e?.message ?? e}` });
+      continue;
+    }
+    const name = `${sha8}.${info.ext}`;
+    let fileAbs;
+    try {
+      fileAbs = containedName(assetsDir, name);
+    } catch (e) {
+      skipped.push({ src: file, why: e?.message ?? 'containment error' });
+      continue;
+    }
+    // Content-addressed dedupe: identical bytes → identical name → copy once.
+    if (!existsSync(fileAbs)) {
+      try {
+        copyFileSync(file, fileAbs);
+      } catch (e) {
+        skipped.push({ src: file, why: `copy failed: ${e?.message ?? e}` });
+        continue;
+      }
+    }
+    if (!seen.has(sha8)) {
+      seen.add(sha8);
+      clips.push({ asset: `assets/${name}`, src: file, bytes: size, category: info.category });
+    }
+  }
+
+  return { clips, skipped, assetsDir };
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+function parseArgv(argv) {
+  const out = {
+    dir: null,
+    root: null,
+    designRoot: '.design',
+    maxBytes: DEFAULT_MAX_BYTES,
+    recursive: false,
+    json: true,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    switch (a) {
+      case '--root':
+        out.root = argv[++i];
+        break;
+      case '--design-root':
+        out.designRoot = argv[++i];
+        break;
+      case '--max-bytes':
+        out.maxBytes = Number(argv[++i]);
+        break;
+      case '--recursive':
+        out.recursive = true;
+        break;
+      case '--json':
+        out.json = true;
+        break;
+      case '--help':
+      case '-h':
+        out.help = true;
+        break;
+      default:
+        if (a.startsWith('-')) throw new IngestError(2, `unknown flag ${a}`);
+        if (out.dir === null) out.dir = a;
+        else throw new IngestError(2, `unexpected extra arg ${a}`);
+    }
+  }
+  return out;
+}
+
+const HELP = `ingest-footage — copy a folder of raw footage into the design asset store
+(reached via \`maude design ingest-footage\`)
+
+Usage:
+  maude design ingest-footage <dir> --root <repo> [--design-root .design]
+                              [--recursive] [--max-bytes N]
+
+Walks <dir>, magic-byte-sniffs each file (mp4/mov/m4v/webm video · mp3/wav/m4a
+audio · png/jpg/gif/webp image; SVG/script/unrecognised skipped), content-
+addresses each to <designRoot>/assets/<sha8>.<ext>, and prints a JSON manifest.
+Oversized / unrecognised files are SKIPPED and listed under "skipped" — never
+silently dropped. The source directory is read-only.
+
+Exit: 0 ok (even with skips) · 2 usage · 6 write/containment error · 1 other.`;
+
+async function main() {
+  let opts;
+  try {
+    opts = parseArgv(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`ingest-footage: ${err.message}\n`);
+    process.exit(err instanceof IngestError ? err.code : 2);
+  }
+  if (opts.help) {
+    process.stdout.write(`${HELP}\n`);
+    return;
+  }
+  if (!opts.dir) {
+    process.stderr.write('ingest-footage: <dir> required\n');
+    process.exit(2);
+  }
+  if (!Number.isFinite(opts.maxBytes) || opts.maxBytes <= 0) {
+    process.stderr.write('ingest-footage: --max-bytes must be a positive number\n');
+    process.exit(2);
+  }
+  const root = opts.root || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  try {
+    const r = await ingestFootage({
+      dir: opts.dir,
+      root,
+      designRootRel: opts.designRoot,
+      maxBytes: opts.maxBytes,
+      recursive: opts.recursive,
+    });
+    process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+  } catch (err) {
+    process.stderr.write(`ingest-footage: ${err.message}\n`);
+    process.exit(err instanceof IngestError ? err.code : 1);
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

package/apps/studio/bin/_probe-footage-playwright.mjs

@@ -0,0 +1,269 @@
+// _probe-footage-playwright.mjs — keyframe extraction for the footage director
+// (feature-footage-analysis-director, Task 4). The READ counterpart to
+// _ingest-footage.mjs: given ONE content-addressed clip, decode it in headless
+// Chromium and dump N evenly-spaced keyframe PNGs the `footage-analyst` agent
+// then WATCHES (vision) to characterize the clip.
+//
+// WHY A BROWSER, NOT ffmpeg: DDR-148's posture is "no native renderer binaries".
+// Chromium already decodes video (it's the capture spine's engine). We don't even
+// need Remotion here — a plain HTML5 <video>, seeked frame-by-frame and
+// screenshotted, is the whole mechanism. No dev server is required either: the
+// page is navigated as file:// and the clip is a file:// subresource (same
+// scheme; `--allow-file-access-from-files` permits the load), so probing works
+// offline / pre-server, unlike the export capture (which drives the live Player).
+//
+// Determinism note (DDR-094 — freeze-frames lie): the frames are evenly spaced
+// midpoints across the clip, so a downstream reader gets genuine motion samples,
+// not one repeated frame.
+//
+// OUTPUT: keyframe PNGs are THROWAWAY SCRATCH → written under --out-dir (a /tmp
+// scratch path, DDR-115: capture scratch never gets a new `_*` dir, never lands
+// in the VERSIONED assets/). stdout = a JSON manifest
+//   { asset, durationSec, width, height, frames:[{index,t,png}] }
+//
+// Reached via `maude design probe-footage`, never a raw path.
+// Exit: 0 ok · 2 usage · 3 no browser (via _pw-launch) · 4 decode/probe error · 1 other.
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { launchChromium } from './_pw-launch.mjs';
+
+const DEFAULT_FRAMES = 12;
+// Cap the longest side of a keyframe PNG — vision only needs legible frames, and
+// small PNGs keep the analyst's context lean. 960px is ample.
+const MAX_FRAME_EDGE = 960;
+
+function parseArgv(argv) {
+  const out = {
+    asset: null,
+    root: null,
+    designRoot: '.design',
+    frames: DEFAULT_FRAMES,
+    outDir: null,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    switch (a) {
+      case '--asset':
+        out.asset = argv[++i];
+        break;
+      case '--root':
+        out.root = argv[++i];
+        break;
+      case '--design-root':
+        out.designRoot = argv[++i];
+        break;
+      case '--frames':
+        out.frames = Number(argv[++i]);
+        break;
+      case '--out-dir':
+        out.outDir = argv[++i];
+        break;
+      case '--help':
+      case '-h':
+        out.help = true;
+        break;
+      default:
+        if (a.startsWith('-')) throw usage(`unknown flag ${a}`);
+        if (out.asset === null) out.asset = a;
+        else throw usage(`unexpected extra arg ${a}`);
+    }
+  }
+  return out;
+}
+
+function usage(msg) {
+  const e = new Error(msg);
+  e.code = 2;
+  return e;
+}
+function probeError(msg) {
+  const e = new Error(msg);
+  e.code = 4;
+  return e;
+}
+
+const HELP = `probe-footage — extract keyframe PNGs from one clip for vision analysis
+(reached via \`maude design probe-footage\`)
+
+Usage:
+  maude design probe-footage <assets/<sha8>.<ext>> --root <repo>
+                             [--design-root .design] [--frames N] [--out-dir DIR]
+
+Decodes the clip in headless Chromium, seeks to N evenly-spaced frames, writes a
+PNG per frame to --out-dir (a /tmp scratch dir — NOT assets/), and prints a JSON
+manifest { asset, durationSec, width, height, frames }.
+
+Exit: 0 ok · 2 usage · 3 no browser · 4 decode/probe error · 1 other.`;
+
+/** Resolve the clip to an absolute path inside <designRoot>/assets and assert containment. */
+function resolveAsset(root, designRootRel, asset) {
+  const rel = String(asset).replace(/^\/+/, ''); // tolerate a leading slash
+  if (isAbsolute(rel) || rel.includes('..'))
+    throw usage(`asset must be a relative assets/ path: ${asset}`);
+  const assetsDir = resolve(root, designRootRel, 'assets');
+  // Accept both `assets/<name>` and a bare `<name>`.
+  const name = rel.startsWith('assets/') ? rel.slice('assets/'.length) : rel;
+  if (!/^[a-z0-9]{8}\.[a-z0-9]{2,4}$/.test(name))
+    throw usage(`asset name must be content-addressed <sha8>.<ext>: ${name}`);
+  const abs = resolve(assetsDir, name);
+  if (abs !== join(assetsDir, name) || !abs.startsWith(assetsDir + sep))
+    throw usage(`asset path escapes assets dir: ${abs}`);
+  return { abs, name, rel: `assets/${name}` };
+}
+
+async function probe({ asset, root, designRootRel, frames, outDir }) {
+  const { abs, name, rel } = resolveAsset(root, designRootRel, asset);
+  const nFrames = Number.isInteger(frames) && frames > 0 ? Math.min(frames, 64) : DEFAULT_FRAMES;
+  const dir =
+    outDir || join(process.env.TMPDIR || '/tmp', `maude-footage-${name.replace(/\./g, '_')}`);
+  mkdirSync(dir, { recursive: true });
+
+  const browser = await launchChromium({
+    headless: true,
+    // file:// page loading a file:// video subresource needs this flag.
+    args: ['--allow-file-access-from-files', '--autoplay-policy=no-user-gesture-required'],
+  });
+  try {
+    const page = await browser.newPage();
+    // A real file:// host page (NOT about:blank — its opaque origin can't load a
+    // file:// subresource even with --allow-file-access-from-files). With a
+    // file:// page + the flag, the clip loads as a same-scheme cross-dir resource.
+    const hostHtml = join(dir, '_probe.html');
+    writeFileSync(hostHtml, '<!doctype html><meta charset="utf-8"><body style="margin:0"></body>');
+    await page.goto(pathToFileURL(hostHtml).href);
+
+    // Load metadata: duration + intrinsic dimensions.
+    const fileUrl = pathToFileURL(abs).href;
+    const meta = await page.evaluate(async (url) => {
+      const v = document.createElement('video');
+      v.id = 'probe-v';
+      v.muted = true;
+      v.playsInline = true;
+      v.preload = 'auto';
+      v.style.position = 'fixed';
+      v.style.left = '0';
+      v.style.top = '0';
+      v.style.margin = '0';
+      document.body.style.margin = '0';
+      document.body.appendChild(v);
+      const done = new Promise((res, rej) => {
+        v.addEventListener('loadedmetadata', () => res(true), { once: true });
+        v.addEventListener('error', () => rej(new Error('video error while loading metadata')), {
+          once: true,
+        });
+        setTimeout(() => rej(new Error('timed out loading metadata (15s)')), 15000);
+      });
+      v.src = url;
+      await done;
+      return { duration: v.duration, width: v.videoWidth, height: v.videoHeight };
+    }, fileUrl);
+
+    if (!Number.isFinite(meta.duration) || meta.duration <= 0 || !meta.width || !meta.height) {
+      throw probeError(
+        `clip has no seekable video track (duration=${meta.duration}, ${meta.width}x${meta.height})`
+      );
+    }
+
+    // Size the <video> element to its intrinsic size, capped, and set the viewport
+    // to match so an element screenshot captures the whole frame at 1:1-ish.
+    const scale = Math.min(1, MAX_FRAME_EDGE / Math.max(meta.width, meta.height));
+    const drawW = Math.max(1, Math.round(meta.width * scale));
+    const drawH = Math.max(1, Math.round(meta.height * scale));
+    await page.setViewportSize({ width: drawW, height: drawH });
+    await page.evaluate(
+      ({ w, h }) => {
+        const v = document.getElementById('probe-v');
+        v.style.width = `${w}px`;
+        v.style.height = `${h}px`;
+        // Expose a promise-returning seek helper for the frame loop.
+        window.__seekTo = (t) =>
+          new Promise((res, rej) => {
+            const onSeeked = () => {
+              v.removeEventListener('seeked', onSeeked);
+              res(true);
+            };
+            v.addEventListener('seeked', onSeeked);
+            setTimeout(() => {
+              v.removeEventListener('seeked', onSeeked);
+              rej(new Error(`seek to ${t}s timed out`));
+            }, 8000);
+            v.currentTime = t;
+          });
+      },
+      { w: drawW, h: drawH }
+    );
+
+    const video = page.locator('#probe-v');
+    const outFrames = [];
+    for (let i = 0; i < nFrames; i += 1) {
+      // Even midpoints across (0, duration) — avoids the exact-0 / exact-end
+      // frames some codecs won't decode cleanly.
+      const t = (meta.duration * (i + 0.5)) / nFrames;
+      try {
+        await page.evaluate((tt) => window.__seekTo(tt), t);
+      } catch (e) {
+        // A single flaky seek shouldn't abort the whole probe — skip this frame.
+        outFrames.push({
+          index: i,
+          t: Number(t.toFixed(3)),
+          png: null,
+          error: String(e?.message ?? e),
+        });
+        continue;
+      }
+      const png = join(dir, `frame-${String(i).padStart(2, '0')}.png`);
+      await video.screenshot({ path: png });
+      outFrames.push({ index: i, t: Number(t.toFixed(3)), png });
+    }
+
+    return {
+      asset: rel,
+      durationSec: Number(meta.duration.toFixed(3)),
+      width: meta.width,
+      height: meta.height,
+      outDir: dir,
+      frames: outFrames,
+    };
+  } finally {
+    await browser.close();
+  }
+}
+
+async function main() {
+  let opts;
+  try {
+    opts = parseArgv(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`probe-footage: ${err.message}\n`);
+    process.exit(err.code ?? 2);
+  }
+  if (opts.help) {
+    process.stdout.write(`${HELP}\n`);
+    return;
+  }
+  if (!opts.asset) {
+    process.stderr.write('probe-footage: <assets/<sha8>.<ext>> required\n');
+    process.exit(2);
+  }
+  const root = opts.root || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  try {
+    const r = await probe({
+      asset: opts.asset,
+      root,
+      designRootRel: opts.designRoot,
+      frames: opts.frames,
+      outDir: opts.outDir,
+    });
+    process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+  } catch (err) {
+    process.stderr.write(`probe-footage: ${err.message}\n`);
+    process.exit(err.code ?? 1);
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}