@archastro/movie-harness 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# `@archastro/movie-harness`
+
+Universal **movie** capture harness for Astroshots. One session API, many
+sources, one `.astroshot/` sink (poster PNG + video + manifest).
+
+Also exposed as **`astroshot movie`** from `@archastro/astroshot` (same binary
+agents already install for stills).
+
+| Source | Status | Notes |
+|--------|--------|-------|
+| `frames` | **ready** | Push any PNG/JPEG sequence (multi-process CLI) |
+| `browser` | **ready** | Playwright `recordVideo` (headless OK) |
+| `pty` | **ready** | Truecolor SGR → xterm → Chromium samples |
+| `pty-demo` | **ready** | Truecolor smoke without a real program |
+| `desktop.window` | **ready** (macOS) | OS `screencapture -l` + shipped Swift window list |
+| `desktop.display` | stub | Use `desktop.window` or `frames` for now |
+
+## Which source? (for agents)
+
+```bash
+astroshot movie which-source "record a ratatui TUI with truecolor"
+astroshot movie which-source "SwiftUI onboarding window"
+astroshot movie help-sources
+astroshot movie --help          # full decision table
+```
+
+Hard rules:
+
+1. **TUI/CLI color** → `pty` (never `desktop.window` on Terminal/iTerm/Ghostty)
+2. **Web** → `browser` (not a desktop grab of Chrome)
+3. **Native Mac app** → `desktop.window` (`--bundle-id` / `--window-id`)
+4. **Custom pixels** → `frames`
+
+## Why
+
+Stills already stream through `.astroshot/`. Journeys need movies. Browser and
+PTY are off-screen (headless Chromium). Native desktop is a separate adapter
+behind the same session contract.
+
+**PTY color is sacred:** `TERM=xterm-256color`, `COLORTERM=truecolor`, cell paint
+via xterm (RGB / 256 / 16). Never screenshot Terminal.app.
+
+## CLI
+
+```bash
+# From monorepo after build:
+node packages/movie-harness/bin/astroshot-movie.mjs --help
+
+# Synthetic frames demo → .astroshot/demo-journey/
+astroshot-movie run --source frames --feature demo-journey --slug flow
+
+# Browser journey
+astroshot-movie run --source browser --feature web --slug home \
+  --url https://example.com --settle-ms 500
+
+# Truecolor terminal smoke (no fixture program)
+astroshot movie run --source pty-demo --feature tui --slug brand
+
+# Real PTY fixture
+astroshot movie run --source pty --feature tui --slug flow \
+  --fixture ./fixtures/demo.pty.yaml
+
+# Native macOS window (uses /usr/sbin/screencapture — already on the Mac)
+astroshot movie list-windows
+astroshot movie run --source desktop.window --feature app --slug onboard \
+  --bundle-id com.example.App --duration-ms 4000 --fps 10
+
+# Multi-process frames
+astroshot movie start --feature custom --slug walk
+astroshot movie push-frame --feature custom --file ./frame.png
+astroshot movie mark --feature custom --slug step-2
+astroshot movie stop --feature custom --status pass
+```
+
+`desktop.window` needs **Screen Recording** permission for your terminal/IDE
+(System Settings → Privacy & Security). Window listing uses Swift
+(`native/macos/WindowTools.swift`) shipped in the package — no extra download.
+
+## Library
+
+```ts
+import { MovieSession, encodeSolidPng, recordBrowserMovie } from "@archastro/movie-harness";
+
+const session = MovieSession.create({
+  feature: "install-wizard",
+  slug: "journey",
+  source: "frames",
+  size: { width: 1280, height: 720 },
+  fps: 15,
+});
+session.pushFrame(encodeSolidPng(1280, 720, [124, 92, 255]));
+session.mark("purple");
+const artifact = await session.stop({ status: "pass" });
+// artifact.posterPath, artifact.videoPath under .astroshot/
+```
+
+## Write contract
+
+```text
+.astroshot/<feature>/
+  manifest.json
+  0001-journey.png     # poster (tray / overlay today)
+  0001-journey.webm    # movie
+```
+
+Manifest shot fields (extension):
+
+```json
+{
+  "kind": "movie",
+  "file": "0001-journey.png",
+  "video": "0001-journey.webm",
+  "duration_ms": 1200,
+  "source": "browser",
+  "chapters": [{ "slug": "mid", "t_ms": 400 }]
+}
+```
+
+Phase 0: Astroshots app needs no changes (poster is a normal image).  
+Phase 1: open `video` from detail when present.
+
+## Encode
+
+1. **ffmpeg** if on `PATH` (WebM VP9 or MP4 H.264)
+2. Else **Playwright** slideshow → `recordVideo` WebM (no extra native deps)
+
+## Desktop window (macOS)
+
+Uses tooling already on the machine:
+
+1. **Window list** — shipped `WindowTools.swift` via `swift` (Xcode CLT)
+2. **Frames** — `/usr/sbin/screencapture -l <windowId>`
+3. **Encode** — same Playwright/ffmpeg path as other sources
+
+```bash
+astroshot movie run --source desktop.window --feature app --slug flow \
+  --bundle-id ai.archastro.Astroshots --duration-ms 3000
+```

package/bin/astroshot-movie.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runCli } from "../dist/cli.js";
+
+const code = await runCli(process.argv.slice(2));
+process.exit(code);

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function runCli(argv: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,388 @@
+import fs from "node:fs";
+import path from "node:path";
+import { encodeSolidPng } from "./png.js";
+import { resolveRoot } from "./paths.js";
+import { finalizeManifest } from "./sink.js";
+import { formatSourceCatalog, recommendSource, SOURCE_DECISION_TABLE, sourceHintForError, } from "./source-help.js";
+import { recordBrowserMovie } from "./sources/browser.js";
+import { assertDesktopToolchain, checkScreenRecordingAccess, desktopMatchFromFlags, listDesktopWindows, openScreenRecordingSettings, recordDesktopWindowMovie, } from "./sources/desktop-macos.js";
+import { loadFrameSession, markFrameSession, pushFrameToSession, startFrameSession, stopFrameSession, } from "./sources/frames-store.js";
+import { recordPtyMovie, recordTruecolorDemoMovie, } from "./sources/pty.js";
+function usage() {
+    return `astroshot movie — universal movie harness → .astroshot/ poster + video
+
+${SOURCE_DECISION_TABLE}
+
+Commands
+--------
+  which-source [intent…]     Recommend a --source for an agent/human intent
+  list-windows               List macOS windows (id, bundle, title) for desktop.window
+  check-screen-access        Detect Screen Recording TCC (optional --request prompt)
+  open-screen-settings       Open System Settings → Screen Recording
+  start / push-frame / mark / stop
+                             Multi-process frames session
+  run                        One-shot recorder (browser | pty | desktop.window | frames | …)
+  finalize                   Set manifest status pass|fail|idle
+
+run --source …
+--------------
+  browser         --url URL | --script path.mjs [--headed] [--settle-ms N]
+  pty             --fixture path.yaml|json   # truecolor TUI — preferred for terminals
+  pty-demo        [--color 7c5cff]           # truecolor smoke, no program
+  desktop.window  --bundle-id ID | --window-id N | --title-regex RE | --owner NAME | --pid N
+                  [--duration-ms 3000] [--fps 10] [--cursor]
+  frames          [--demo-frames N]          # or use start/push-frame/stop
+
+Common options
+--------------
+  --feature NAME   kebab-case feature dir under .astroshot/ (required for capture)
+  --slug SLUG      kebab-case movie slug (required for capture)
+  --root DIR       worktree root (default: git root or cwd)
+  --run-id ID      stable run identity (share across movies in one journey)
+  --title TEXT     human title
+  --description T  what the movie proves
+  --size WxH       encode size (desktop defaults to window pixels)
+  --fps N          default 15 (desktop default 10)
+  --format webm|mp4
+  --status running|pass|fail|idle
+  --session ID     frames session id (default: latest)
+  -h, --help
+
+Agent notes
+-----------
+  • Prefer the decision table over improvising OS screen recording for web/TUI.
+  • Always land poster+video under .astroshot/ so Astroshots streams posters.
+  • desktop.window uses macOS screencapture (already on the system) + Swift window list
+    shipped in this package — no extra binary download. Needs Screen Recording TCC.
+  • For full catalog: astroshot movie help-sources
+
+Examples
+--------
+  astroshot movie which-source "record a ratatui TUI with truecolor"
+  astroshot movie run --source browser --feature web --slug home --url https://example.com
+  astroshot movie run --source pty --feature tui --slug flow --fixture ./flow.pty.yaml
+  astroshot movie run --source desktop.window --feature app --slug onboard \\
+    --bundle-id com.example.App --duration-ms 4000
+  astroshot movie list-windows
+`;
+}
+function parseArgs(argv) {
+    if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
+        return { command: "help", args: {}, rest: [] };
+    }
+    const command = argv[0];
+    const args = {};
+    const rest = [];
+    for (let i = 1; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "-h" || token === "--help") {
+            args.help = true;
+            continue;
+        }
+        if (!token.startsWith("--")) {
+            rest.push(token);
+            continue;
+        }
+        const key = token.slice(2);
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith("--")) {
+            args[key] = true;
+        }
+        else {
+            args[key] = next;
+            i += 1;
+        }
+    }
+    return { command, args, rest };
+}
+function req(args, key) {
+    const value = args[key];
+    if (typeof value !== "string" || !value) {
+        throw new Error(`--${key} is required`);
+    }
+    return value;
+}
+function opt(args, key) {
+    const value = args[key];
+    return typeof value === "string" ? value : undefined;
+}
+function parseSize(value) {
+    if (!value)
+        return undefined;
+    const match = /^(\d+)x(\d+)$/.exec(value);
+    if (!match)
+        throw new Error(`--size must be WxH, got ${value}`);
+    return { width: Number(match[1]), height: Number(match[2]) };
+}
+function parseFormat(value) {
+    if (!value)
+        return undefined;
+    if (value !== "webm" && value !== "mp4") {
+        throw new Error(`--format must be webm|mp4`);
+    }
+    return value;
+}
+function parseFps(value) {
+    if (!value)
+        return undefined;
+    const n = Number(value);
+    if (!(n > 0 && n <= 60))
+        throw new Error(`--fps must be in (0, 60]`);
+    return n;
+}
+export async function runCli(argv) {
+    try {
+        const { command, args, rest } = parseArgs(argv);
+        if (command === "help" || args.help) {
+            process.stdout.write(`${usage()}\n`);
+            return 0;
+        }
+        switch (command) {
+            case "which-source":
+                return cmdWhichSource(rest, args);
+            case "help-sources":
+                process.stdout.write(`${formatSourceCatalog()}\n`);
+                return 0;
+            case "list-windows":
+                return cmdListWindows();
+            case "check-screen-access":
+                return cmdCheckScreenAccess(args);
+            case "open-screen-settings":
+                return cmdOpenScreenSettings();
+            case "start":
+                return cmdStart(args);
+            case "push-frame":
+                return cmdPushFrame(args);
+            case "mark":
+                return cmdMark(args);
+            case "stop":
+                return await cmdStop(args);
+            case "run":
+                return await cmdRun(args);
+            case "finalize":
+                return cmdFinalize(args);
+            default:
+                throw new Error(`unknown command: ${command}\n\n${usage()}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`error: ${message}\n`);
+        if (!/which-source|decision table|list-windows/i.test(message)) {
+            process.stderr.write(`hint: ${sourceHintForError()}\n`);
+        }
+        return 1;
+    }
+}
+function cmdWhichSource(rest, args) {
+    const intent = rest.join(" ") ||
+        opt(args, "intent") ||
+        opt(args, "for") ||
+        "";
+    if (!intent) {
+        process.stdout.write(`${SOURCE_DECISION_TABLE}\n\n` +
+            `Pass free text, e.g.:\n` +
+            `  astroshot movie which-source "native SwiftUI onboarding window"\n` +
+            `  astroshot movie which-source "ratatui truecolor dashboard"\n`);
+        return 0;
+    }
+    const advice = recommendSource(intent);
+    process.stdout.write(`${JSON.stringify({ intent, recommended: advice.source, reason: advice.reason }, null, 2)}\n`);
+    return 0;
+}
+function cmdListWindows() {
+    assertDesktopToolchain();
+    const windows = listDesktopWindows();
+    process.stdout.write(`${JSON.stringify(windows, null, 2)}\n`);
+    process.stderr.write(`# ${windows.length} windows — match with --window-id / --bundle-id / --title-regex / --owner / --pid\n`);
+    return 0;
+}
+function cmdCheckScreenAccess(args) {
+    assertDesktopToolchain();
+    const request = Boolean(args.request);
+    const report = checkScreenRecordingAccess({ request });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.granted) {
+        process.stderr.write(`\nScreen Recording: DENIED (enable "${report.enableApp}")\n` +
+            `  → ${report.settingsHint}\n` +
+            `  → or: astroshot movie open-screen-settings\n` +
+            `  → then quit & reopen ${report.enableApp}, re-run check-screen-access\n`);
+        if (args["open-settings"] || args.open) {
+            openScreenRecordingSettings();
+        }
+        return 2;
+    }
+    process.stderr.write(`# Screen Recording preflight: OK — still enable "${report.enableApp}" in Settings if captures fail\n`);
+    return 0;
+}
+function cmdOpenScreenSettings() {
+    assertDesktopToolchain();
+    const ok = openScreenRecordingSettings();
+    if (!ok) {
+        process.stderr.write("error: could not open System Settings; open Privacy & Security → Screen Recording manually\n");
+        return 1;
+    }
+    process.stderr.write("Opened System Settings (Screen Recording). Enable the app that launched this command, quit it fully, reopen, then:\n" +
+        "  astroshot movie check-screen-access\n");
+    return 0;
+}
+function cmdStart(args) {
+    const state = startFrameSession({
+        feature: req(args, "feature"),
+        slug: req(args, "slug"),
+        root: opt(args, "root"),
+        runId: opt(args, "run-id"),
+        title: opt(args, "title"),
+        description: opt(args, "description"),
+        size: parseSize(opt(args, "size")),
+        fps: parseFps(opt(args, "fps")),
+        format: parseFormat(opt(args, "format")),
+    });
+    process.stdout.write(`${JSON.stringify({
+        id: state.id,
+        feature: state.feature,
+        slug: state.slug,
+        runId: state.runId,
+        frameDir: state.frameDir,
+    }, null, 2)}\n`);
+    return 0;
+}
+function cmdPushFrame(args) {
+    const state = loadFrameSession(opt(args, "root") ?? resolveRoot(), req(args, "feature"), opt(args, "session"));
+    const file = req(args, "file");
+    const next = pushFrameToSession(state, path.resolve(file));
+    process.stdout.write(`${JSON.stringify({ id: next.id, frameCount: next.frameCount }, null, 2)}\n`);
+    return 0;
+}
+function cmdMark(args) {
+    const state = loadFrameSession(opt(args, "root") ?? resolveRoot(), req(args, "feature"), opt(args, "session"));
+    const next = markFrameSession(state, req(args, "slug"), opt(args, "note"));
+    process.stdout.write(`${JSON.stringify({ id: next.id, chapters: next.chapters }, null, 2)}\n`);
+    return 0;
+}
+async function cmdStop(args) {
+    const state = loadFrameSession(opt(args, "root") ?? resolveRoot(), req(args, "feature"), opt(args, "session"));
+    const status = (opt(args, "status") ?? "running");
+    const artifact = await stopFrameSession(state, { status });
+    process.stdout.write(`${JSON.stringify(artifact, null, 2)}\n`);
+    return 0;
+}
+async function cmdRun(args) {
+    const source = req(args, "source");
+    const feature = req(args, "feature");
+    const slug = req(args, "slug");
+    const common = {
+        feature,
+        slug,
+        root: opt(args, "root"),
+        runId: opt(args, "run-id"),
+        title: opt(args, "title"),
+        description: opt(args, "description"),
+        size: parseSize(opt(args, "size")),
+        fps: parseFps(opt(args, "fps")),
+        format: parseFormat(opt(args, "format")),
+        status: (opt(args, "status") ?? "running"),
+    };
+    if (source === "frames") {
+        const count = Number(opt(args, "demo-frames") ?? "8");
+        const size = common.size ?? { width: 320, height: 180 };
+        let state = startFrameSession({ ...common, size });
+        const tmpDir = path.join(state.frameDir, "..", "demo-src");
+        fs.mkdirSync(tmpDir, { recursive: true });
+        const colors = [
+            [124, 92, 255],
+            [90, 200, 250],
+            [80, 220, 160],
+            [240, 180, 110],
+            [240, 114, 122],
+            [232, 232, 242],
+            [90, 90, 122],
+            [9, 10, 18],
+        ];
+        for (let i = 0; i < count; i++) {
+            const rgb = colors[i % colors.length];
+            const png = encodeSolidPng(size.width, size.height, rgb);
+            const file = path.join(tmpDir, `f-${i}.png`);
+            fs.writeFileSync(file, png);
+            state = pushFrameToSession(state, file);
+            if (i === Math.floor(count / 2)) {
+                state = markFrameSession(state, "midpoint");
+            }
+        }
+        const artifact = await stopFrameSession(state, {
+            status: common.status,
+        });
+        process.stdout.write(`${JSON.stringify(artifact, null, 2)}\n`);
+        return 0;
+    }
+    if (source === "browser") {
+        const artifact = await recordBrowserMovie({
+            ...common,
+            url: opt(args, "url"),
+            scriptPath: opt(args, "script"),
+            headed: Boolean(args.headed),
+            settleMs: opt(args, "settle-ms")
+                ? Number(opt(args, "settle-ms"))
+                : undefined,
+        });
+        process.stdout.write(`${JSON.stringify(artifact, null, 2)}\n`);
+        return 0;
+    }
+    if (source === "pty") {
+        const artifact = await recordPtyMovie({
+            ...common,
+            fixturePath: req(args, "fixture"),
+        });
+        process.stdout.write(`${JSON.stringify(artifact, null, 2)}\n`);
+        return 0;
+    }
+    if (source === "pty-demo") {
+        const artifact = await recordTruecolorDemoMovie({
+            ...common,
+            color: opt(args, "color"),
+        });
+        process.stdout.write(`${JSON.stringify(artifact, null, 2)}\n`);
+        return 0;
+    }
+    if (source === "desktop.window") {
+        assertDesktopToolchain();
+        const match = desktopMatchFromFlags({
+            "window-id": opt(args, "window-id"),
+            "bundle-id": opt(args, "bundle-id"),
+            "title-regex": opt(args, "title-regex"),
+            owner: opt(args, "owner"),
+            pid: opt(args, "pid"),
+            pick: opt(args, "pick"),
+        });
+        const durationMs = opt(args, "duration-ms")
+            ? Number(opt(args, "duration-ms"))
+            : 3_000;
+        const artifact = await recordDesktopWindowMovie({
+            ...common,
+            match,
+            durationMs,
+            cursor: Boolean(args.cursor),
+            fps: common.fps ?? 10,
+        });
+        process.stdout.write(`${JSON.stringify(artifact, null, 2)}\n`);
+        return 0;
+    }
+    if (source === "desktop.display" || source === "desktop.region") {
+        throw new Error(`${source} is not implemented yet.\n` +
+            `Use --source desktop.window for a single app, or --source frames.\n` +
+            sourceHintForError("desktop.window"));
+    }
+    throw new Error(`unknown --source ${JSON.stringify(source)}\n${SOURCE_DECISION_TABLE}`);
+}
+function cmdFinalize(args) {
+    const root = resolveRoot(opt(args, "root"));
+    const feature = req(args, "feature");
+    const runId = req(args, "run-id");
+    const status = req(args, "status");
+    if (!["pass", "fail", "idle", "running"].includes(status)) {
+        throw new Error("--status must be pass|fail|idle|running");
+    }
+    finalizeManifest(root, feature, runId, status);
+    process.stdout.write(`${JSON.stringify({ feature, runId, status }, null, 2)}\n`);
+    return 0;
+}

package/dist/encode.d.ts

@@ -0,0 +1,14 @@
+import type { EncodeFramesRequest } from "./types.js";
+/**
+ * Encode a PNG sequence to WebM/MP4.
+ *
+ * Prefer ffmpeg when present (fast, high quality). Otherwise replay frames in
+ * headless Chromium with Playwright recordVideo — no native deps beyond the
+ * Chromium we already ship for stills.
+ */
+export declare function encodeFrames(request: EncodeFramesRequest): Promise<{
+    videoPath: string;
+    durationMs: number;
+}>;
+/** Copy the last frame as the poster PNG. */
+export declare function posterFromFrames(framePaths: string[], outPath: string): string;