@anvpx/motion-cli 0.0.0-stage → 0.1.1

package/dist/assets/command.js

@@ -0,0 +1,165 @@
+import { basename, join, resolve } from "node:path";
+import { AssetLedgerSchema } from "@anvpx/motion-schema";
+import { parseFlags, textFlag, usageError } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+const USAGE = `mk assets import <file...> --dir <assets dir> --licence <spdx> --source-url <url> [--attribution <text>] [--ledger <file>] [--json]
+
+Copy local files into <assets dir>, hash the copied bytes and append one ledger row per file
+(path, sourceUrl, licence, attribution, sha256). Re-running the same call is a no-op when the
+bytes match; a different hash at an existing path exits 2 naming the file. Remote URLs are refused.
+  --dir <d>          destination directory (created when missing)
+  --licence <id>     SPDX identifier for every file in this call (required)
+  --source-url <u>   provenance URL for every file in this call (required; the ledger schema needs it)
+  --attribution <t>  optional attribution text for every file in this call
+  --ledger <f>       ledger path (default <dir>/assets.json)
+  --json             print one JSON summary line
+`;
+const FLAGS = {
+    dir: { type: "string" },
+    licence: { type: "string" },
+    "source-url": { type: "string" },
+    attribution: { type: "string" },
+    ledger: { type: "string" },
+    json: { type: "boolean" },
+};
+const REMOTE = /^[a-z][a-z0-9+.-]*:\/\//i;
+/** One `import` file: refused when remote, unreadable or nameless. */
+async function inspectFile(file, io) {
+    if (REMOTE.test(file)) {
+        io.stderr(`mk assets import: refusing remote path "${file}"; download it first\n`);
+        return EXIT.USAGE;
+    }
+    const name = basename(file);
+    if (name === "" || name === "." || name === "..") {
+        io.stderr(`mk assets import: cannot import "${file}": it has no file name\n`);
+        return EXIT.USAGE;
+    }
+    if (!(await io.host.exists(file))) {
+        io.stderr(`mk assets import: no such file "${file}"\n`);
+        return EXIT.USAGE;
+    }
+    const sha256 = await io.host.sha256File(file);
+    if (sha256 === undefined) {
+        io.stderr(`mk assets import: cannot hash "${file}"\n`);
+        return EXIT.USAGE;
+    }
+    return { name, sha256 };
+}
+/** Reads and validates the ledger; a missing file starts an empty ledger. */
+async function readLedger(path, io) {
+    if (!(await io.host.exists(path)))
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(await io.host.readText(path));
+    }
+    catch (error) {
+        io.stderr(`mk assets import: cannot read ledger ${path}: ${error.message}\n`);
+        return EXIT.USAGE;
+    }
+    const valid = AssetLedgerSchema.safeParse(parsed);
+    if (!valid.success) {
+        const problems = valid.error.issues
+            .map((issue) => `${issue.path.join("/") || "/"}: ${issue.message}`)
+            .join("; ");
+        io.stderr(`mk assets import: ledger ${path} is invalid: ${problems}\n`);
+        return EXIT.USAGE;
+    }
+    return [...valid.data];
+}
+/** Copies one file and returns the ledger row; exits 2 when the existing path has other bytes. */
+async function importOne(file, inspected, dir, rows, shared, io) {
+    const existing = rows.find((row) => row.path === inspected.name);
+    if (existing !== undefined && existing.sha256 !== inspected.sha256) {
+        io.stderr(`mk assets import: "${inspected.name}" already has different bytes in the ledger (${existing.sha256.slice(0, 12)} != ${inspected.sha256.slice(0, 12)}); remove the row or rename the file\n`);
+        return EXIT.USAGE;
+    }
+    if (existing !== undefined) {
+        return {
+            row: { file, path: inspected.name, sha256: inspected.sha256 },
+            skipped: true,
+        };
+    }
+    const destination = join(dir, inspected.name);
+    try {
+        await io.host.copyFile(file, destination);
+    }
+    catch (error) {
+        io.stderr(`mk assets import: cannot copy "${file}" to ${destination}: ${error.message}\n`);
+        return EXIT.USAGE;
+    }
+    const copied = await io.host.sha256File(destination);
+    if (copied !== inspected.sha256) {
+        io.stderr(`mk assets import: "${file}" changed while copying; nothing written\n`);
+        return EXIT.ERROR;
+    }
+    rows.push({
+        path: inspected.name,
+        sourceUrl: shared.sourceUrl,
+        licence: shared.licence,
+        ...(shared.attribution === undefined ? {} : { attribution: shared.attribution }),
+        sha256: inspected.sha256,
+    });
+    return { row: { file, path: inspected.name, sha256: inspected.sha256 }, skipped: false };
+}
+const byPath = (a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+export const assetsCommand = {
+    name: "assets",
+    summary: "import local asset files into a directory with validated ledger rows",
+    async run(args, io) {
+        const [subcommand, ...files] = args;
+        if (subcommand !== "import") {
+            return usageError("assets", USAGE, 'expected "import"', io).code;
+        }
+        const parsed = parseFlags("assets", USAGE, files, FLAGS, io);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const sources = parsed.positionals;
+        if (sources.length === 0) {
+            return usageError("assets", USAGE, "missing <file...>", io).code;
+        }
+        const dirFlag = textFlag(parsed.flags, "dir");
+        if (dirFlag === undefined) {
+            return usageError("assets", USAGE, "--dir <assets dir> is required", io).code;
+        }
+        const licence = textFlag(parsed.flags, "licence");
+        if (licence === undefined || licence.trim() === "") {
+            return usageError("assets", USAGE, "--licence <spdx> is required", io).code;
+        }
+        const sourceUrl = textFlag(parsed.flags, "source-url");
+        if (sourceUrl === undefined || sourceUrl.trim() === "") {
+            return usageError("assets", USAGE, "--source-url <url> is required (the ledger row needs provenance)", io).code;
+        }
+        const attribution = textFlag(parsed.flags, "attribution");
+        const dir = resolve(dirFlag);
+        const ledgerPath = resolve(textFlag(parsed.flags, "ledger") ?? join(dir, "assets.json"));
+        const rows = await readLedger(ledgerPath, io);
+        if (typeof rows === "number")
+            return rows;
+        const summary = { imported: [], skipped: [] };
+        for (const file of sources) {
+            const inspected = await inspectFile(file, io);
+            if (typeof inspected === "number")
+                return inspected;
+            const result = await importOne(file, inspected, dir, rows, {
+                sourceUrl,
+                licence,
+                ...(attribution === undefined ? {} : { attribution }),
+            }, io);
+            if (typeof result === "number")
+                return result;
+            (result.skipped ? summary.skipped : summary.imported).push(result.row);
+        }
+        if (summary.imported.length > 0) {
+            const text = `${JSON.stringify([...rows].sort(byPath), null, 2)}\n`;
+            await io.host.writeTextAtomic(ledgerPath, text);
+        }
+        if (parsed.flags.json === true) {
+            io.stdout(`${JSON.stringify({ ok: true, ledger: ledgerPath, ...summary })}\n`);
+        }
+        else {
+            io.stdout(`assets import ok | ${summary.imported.length} imported, ${summary.skipped.length} unchanged -> ${ledgerPath}\n`);
+        }
+        return EXIT.OK;
+    },
+};

package/dist/captions/command.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "../types.ts";
+export declare const captionsCommand: Command;

package/dist/captions/command.js

@@ -0,0 +1,341 @@
+import { resolveTimeline, validateStoryboardFull } from "@anvpx/motion-build";
+import { TimingManifestSchema } from "@anvpx/motion-schema";
+import { parseFlags, textFlag, usageError } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { readJsonFile } from "../storyboard/load.js";
+import { formatErrors } from "../template/env.js";
+import { formatSrt, formatVtt, parseCues } from "./cues.js";
+const USAGE = `mk captions [<voice-manifest.json>] [--storyboard <board.json>] [--out ops.json] [--srt <file>] [--vtt <file>] [--from-srt <file> | --from-vtt <file>] [--json]
+
+Turn voice word timings into one karaoke caption overlay per narrated scene, written as RFC 6902
+\`add\` operations for \`mk patch --ops\`. Words are shifted to scene-relative time; words past the
+scene's authored/auto duration are omitted and reported per scene, never silently kept.
+  --storyboard b   the storyboard the manifest belongs to (required to emit ops)
+  --out f          write the ops JSON array here (default: print it on stdout)
+  --srt f          also export the manifest as SRT
+  --vtt f          also export the manifest as WebVTT
+  --from-srt f     instead of a manifest: convert SRT cues into caption overlays (needs --storyboard)
+  --from-vtt f     instead of a manifest: convert WebVTT cues into caption overlays (needs --storyboard)
+`;
+const FLAGS = {
+    storyboard: { type: "string" },
+    out: { type: "string" },
+    srt: { type: "string" },
+    vtt: { type: "string" },
+    "from-srt": { type: "string" },
+    "from-vtt": { type: "string" },
+    json: { type: "boolean" },
+};
+const round = (value) => Math.round(value * 1000) / 1000;
+const CAPTION_MAX_WORDS = 40;
+const CAPTION_MAX_TEXT = 140;
+const baseTimeline = (board) => {
+    const timeline = resolveTimeline(board);
+    if (!timeline.ok)
+        return EXIT.USAGE;
+    return timeline.value.scenes.map((scene) => ({
+        id: scene.id,
+        start: scene.start,
+        duration: scene.duration,
+    }));
+};
+/** A4/A1: words on the scene clock, clamped to the authored/auto bound; never overlaps. */
+const sceneWords = (row, bound, fallback) => {
+    const source = row.words && row.words.length > 0 ? row.words : fallback;
+    const words = [];
+    let omitted = 0;
+    let cursor = 0;
+    for (const word of source) {
+        const start = round(Math.max(0, word.start - row.start));
+        const end = round(Math.min(bound, word.end - row.start));
+        if (start >= bound - 1e-6 || end <= start || start < cursor) {
+            omitted += 1;
+            continue;
+        }
+        if (words.length >= CAPTION_MAX_WORDS) {
+            omitted += 1;
+            continue;
+        }
+        words.push({ w: word.w, start, end });
+        cursor = end;
+    }
+    return { words, omitted };
+};
+/** One `add /scenes/-` op per narrated scene, with a per-scene captioned/omitted report. */
+const planFromManifest = (board, manifest) => {
+    const timed = baseTimeline(board);
+    if (typeof timed === "number")
+        return timed;
+    const byId = new Map(timed.map((scene) => [scene.id, scene]));
+    const ops = [];
+    const report = [];
+    let words = 0;
+    let omitted = 0;
+    let scenes = 0;
+    for (const row of manifest.scenes) {
+        const scene = byId.get(row.id);
+        if (scene === undefined) {
+            report.push(`scene "${row.id}": not in the storyboard; skipped`);
+            continue;
+        }
+        const bound = round(scene.duration);
+        const fallback = manifest.audio?.words.filter((word) => word.start >= row.start - 1e-6 && word.start < row.start + bound) ?? [];
+        const built = sceneWords(row, bound, fallback);
+        words += built.words.length;
+        omitted += built.omitted;
+        if (built.words.length === 0) {
+            report.push(`scene "${row.id}": no words inside ${bound}s (${built.omitted} omitted); no caption`);
+            continue;
+        }
+        scenes += 1;
+        ops.push({
+            op: "add",
+            path: "/scenes/-",
+            value: {
+                id: `cap-${row.id}`,
+                type: "caption",
+                layer: "overlay",
+                over: row.id,
+                duration: bound,
+                props: { words: built.words },
+            },
+        });
+        report.push(`scene "${row.id}": ${built.words.length} words captioned` +
+            (built.omitted > 0 ? `, ${built.omitted} omitted past ${bound}s` : ""));
+    }
+    if (scenes === 0 || words === 0) {
+        return EXIT.USAGE;
+    }
+    return { ops, report, words, omitted };
+};
+/** SRT/VTT cues -> overlays placed by scene + offset; text-only captions (no word timings). */
+const planFromCues = (board, cues, io) => {
+    const valid = validateStoryboardFull(board);
+    if (!valid.ok) {
+        io.stderr(`mk captions: storyboard is invalid: ${formatErrors(valid.errors)}\n`);
+        return EXIT.USAGE;
+    }
+    const timed = baseTimeline(valid.value);
+    if (typeof timed === "number") {
+        io.stderr("mk captions: cannot resolve the storyboard timeline\n");
+        return EXIT.USAGE;
+    }
+    const ops = [];
+    const report = [];
+    let words = 0;
+    let omitted = 0;
+    let index = 0;
+    for (const cue of cues) {
+        const scene = timed.find((candidate) => cue.start >= candidate.start - 1e-6 &&
+            cue.start < candidate.start + candidate.duration - 1e-6);
+        if (scene === undefined) {
+            omitted += 1;
+            report.push(`cue "${cue.text.slice(0, 24)}": outside every base scene; omitted`);
+            continue;
+        }
+        const start = round(Math.max(0, cue.start - scene.start));
+        const end = round(Math.min(cue.end, scene.start + scene.duration) - cue.start);
+        if (end <= 0) {
+            omitted += 1;
+            continue;
+        }
+        if (cue.text.length > CAPTION_MAX_TEXT) {
+            omitted += 1;
+            report.push(`cue "${cue.text.slice(0, 24)}": ${cue.text.length} chars (max ${CAPTION_MAX_TEXT}); omitted`);
+            continue;
+        }
+        index += 1;
+        words += cue.text.split(/\s+/).filter(Boolean).length;
+        ops.push({
+            op: "add",
+            path: "/scenes/-",
+            value: {
+                id: `cap-cue-${index}`,
+                type: "caption",
+                layer: "overlay",
+                over: scene.id,
+                offset: start,
+                duration: end,
+                props: { text: cue.text },
+            },
+        });
+        report.push(`cue ${index} over "${scene.id}" at ${start}s for ${round(end)}s`);
+    }
+    if (ops.length === 0)
+        return EXIT.USAGE;
+    return { ops, report, words, omitted };
+};
+/** Applies the ops in memory and validates, so `mk patch --ops` cannot fail on our output. */
+const validateOps = (board, plan, io) => {
+    const validBoard = validateStoryboardFull(board);
+    if (!validBoard.ok) {
+        io.stderr(`mk captions: storyboard is invalid: ${formatErrors(validBoard.errors)}\n`);
+        return EXIT.USAGE;
+    }
+    const next = {
+        ...validBoard.value,
+        scenes: [...validBoard.value.scenes, ...plan.ops.map((op) => op.value)],
+    };
+    const valid = validateStoryboardFull(next);
+    if (valid.ok)
+        return undefined;
+    io.stderr(`mk captions: the caption overlays would not validate: ${formatErrors(valid.errors)}\n`);
+    return EXIT.USAGE;
+};
+const writeFile = async (path, text, io) => {
+    try {
+        await io.host.writeText(path, text);
+        return undefined;
+    }
+    catch (error) {
+        io.stderr(`mk captions: cannot write ${path}: ${error.message}\n`);
+        return EXIT.ERROR;
+    }
+};
+export const captionsCommand = {
+    name: "captions",
+    summary: "turn voice word timings (or SRT/VTT) into caption overlay ops; export SRT/VTT",
+    async run(args, io) {
+        const parsed = parseFlags("captions", USAGE, args, FLAGS, io);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const [manifestPath, ...extra] = parsed.positionals;
+        if (extra.length > 0) {
+            return usageError("captions", USAGE, `unexpected argument "${extra[0]}"`, io).code;
+        }
+        const storyboard = textFlag(parsed.flags, "storyboard");
+        const fromSrt = textFlag(parsed.flags, "from-srt");
+        const fromVtt = textFlag(parsed.flags, "from-vtt");
+        if (fromSrt !== undefined && fromVtt !== undefined) {
+            return usageError("captions", USAGE, "--from-srt and --from-vtt conflict", io).code;
+        }
+        if ((fromSrt !== undefined || fromVtt !== undefined) && manifestPath !== undefined) {
+            return usageError("captions", USAGE, "give a manifest or --from-*, not both", io).code;
+        }
+        const importPath = fromSrt ?? fromVtt;
+        if (manifestPath === undefined && importPath === undefined) {
+            return usageError("captions", USAGE, "missing <voice-manifest.json> or --from-srt/--from-vtt", io).code;
+        }
+        const wantsOps = textFlag(parsed.flags, "out") !== undefined || storyboard !== undefined;
+        const wantsExport = textFlag(parsed.flags, "srt") !== undefined || textFlag(parsed.flags, "vtt") !== undefined;
+        if (wantsOps && storyboard === undefined) {
+            return usageError("captions", USAGE, "--storyboard is required to emit caption ops", io).code;
+        }
+        if (!wantsOps && !wantsExport) {
+            return usageError("captions", USAGE, "nothing to do: give --out, --storyboard, --srt or --vtt", io).code;
+        }
+        let board;
+        if (wantsOps) {
+            const loaded = await readJsonFile(storyboard, io.host);
+            if (!loaded.ok) {
+                io.stderr(`mk captions: ${loaded.message}\n`);
+                return EXIT.USAGE;
+            }
+            board = loaded.value;
+        }
+        let plan;
+        let manifest;
+        if (importPath !== undefined) {
+            let text;
+            try {
+                text = await io.host.readText(importPath);
+            }
+            catch {
+                io.stderr(`mk captions: cannot read ${importPath}\n`);
+                return EXIT.USAGE;
+            }
+            const cues = parseCues(text, fromSrt !== undefined ? "srt" : "vtt");
+            if (cues.length === 0) {
+                io.stderr(`mk captions: ${importPath} has no readable cues\n`);
+                return EXIT.USAGE;
+            }
+            const planned = planFromCues(board, cues, io);
+            if (typeof planned === "number")
+                return planned;
+            plan = planned;
+        }
+        else {
+            const loaded = await readJsonFile(manifestPath, io.host);
+            if (!loaded.ok) {
+                io.stderr(`mk captions: ${loaded.message}\n`);
+                return EXIT.USAGE;
+            }
+            const parsedManifest = TimingManifestSchema.safeParse(loaded.value);
+            if (!parsedManifest.success) {
+                const problems = parsedManifest.error.issues
+                    .map((issue) => `${issue.path.join("/") || "/"}: ${issue.message}`)
+                    .join("; ");
+                io.stderr(`mk captions: invalid voice manifest: ${problems}\n`);
+                return EXIT.USAGE;
+            }
+            manifest = parsedManifest.data;
+            const hasWords = manifest.scenes.some((scene) => (scene.words?.length ?? 0) > 0) ||
+                (manifest.audio?.words.length ?? 0) > 0;
+            if (!hasWords) {
+                io.stderr("mk captions: the manifest has no words\n");
+                return EXIT.USAGE;
+            }
+            if (wantsOps) {
+                const valid = validateStoryboardFull(board);
+                if (!valid.ok) {
+                    io.stderr(`mk captions: storyboard is invalid: ${formatErrors(valid.errors)}\n`);
+                    return EXIT.USAGE;
+                }
+                const planned = planFromManifest(valid.value, manifest);
+                if (typeof planned === "number") {
+                    io.stderr("mk captions: no scene of the storyboard has words inside its bound\n");
+                    return EXIT.USAGE;
+                }
+                plan = planned;
+            }
+        }
+        if (plan !== undefined) {
+            const invalid = validateOps(board, plan, io);
+            if (invalid !== undefined)
+                return invalid;
+            for (const line of plan.report)
+                io.stderr(`${line}\n`);
+            const text = `${JSON.stringify(plan.ops, null, 2)}\n`;
+            const out = textFlag(parsed.flags, "out");
+            if (out === undefined) {
+                io.stdout(text);
+            }
+            else {
+                const written = await writeFile(out, text, io);
+                if (written !== undefined)
+                    return written;
+                const summary = `captions ok | ${plan.ops.length} overlays, ${plan.words} words, ${plan.omitted} omitted -> ${out}`;
+                if (parsed.flags.json === true) {
+                    io.stdout(`${JSON.stringify({ ok: true, out, overlays: plan.ops.length, words: plan.words, omitted: plan.omitted })}\n`);
+                }
+                else {
+                    io.stdout(`${summary}\n`);
+                }
+            }
+        }
+        if (manifest !== undefined) {
+            const exportCues = manifest.scenes
+                .filter((scene) => (scene.words?.length ?? 0) > 0)
+                .map((scene) => ({
+                start: scene.start,
+                end: round(scene.start + scene.duration),
+                text: (scene.words ?? []).map((word) => word.w).join(" "),
+            }));
+            const srt = textFlag(parsed.flags, "srt");
+            if (srt !== undefined) {
+                const written = await writeFile(srt, formatSrt(exportCues), io);
+                if (written !== undefined)
+                    return written;
+                io.stdout(`captions srt | ${exportCues.length} cues -> ${srt}\n`);
+            }
+            const vtt = textFlag(parsed.flags, "vtt");
+            if (vtt !== undefined) {
+                const written = await writeFile(vtt, formatVtt(exportCues), io);
+                if (written !== undefined)
+                    return written;
+                io.stdout(`captions vtt | ${exportCues.length} cues -> ${vtt}\n`);
+            }
+        }
+        return EXIT.OK;
+    },
+};

package/dist/captions/cues.d.ts

@@ -0,0 +1,10 @@
+/** Cue parsing/formatting for SRT and WebVTT (the caption interchange formats). */
+export interface Cue {
+    readonly start: number;
+    readonly end: number;
+    readonly text: string;
+}
+/** Parses cue blocks; an index line and the WEBVTT header are ignored, malformed cues are skipped. */
+export declare function parseCues(text: string, kind: "srt" | "vtt"): Cue[];
+export declare function formatSrt(cues: readonly Cue[]): string;
+export declare function formatVtt(cues: readonly Cue[]): string;

package/dist/captions/cues.js

@@ -0,0 +1,61 @@
+/** Cue parsing/formatting for SRT and WebVTT (the caption interchange formats). */
+const TIMING = /^(\d{1,2}:)?(\d{2}):(\d{2})[.,](\d{1,3})$/;
+const seconds = (hh, mm, ss, ms) => Number(hh?.slice(0, -1) ?? 0) * 3600 +
+    Number(mm) * 60 +
+    Number(ss) +
+    Number(ms.padEnd(3, "0")) / 1000;
+const parseStamp = (text) => {
+    const match = TIMING.exec(text.trim());
+    if (match === null)
+        return undefined;
+    return seconds(match[1], match[2] ?? "0", match[3] ?? "0", match[4] ?? "0");
+};
+const clean = (text) => text
+    .replace(/<[^>]+>/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+/** Parses cue blocks; an index line and the WEBVTT header are ignored, malformed cues are skipped. */
+export function parseCues(text, kind) {
+    const blocks = text.replaceAll("\r\n", "\n").split(/\n{2,}/);
+    const cues = [];
+    for (const block of blocks) {
+        const lines = block.split("\n").map((line) => line.trim());
+        if (lines.length === 0)
+            continue;
+        const timingIndex = lines.findIndex((line) => line.includes("-->"));
+        if (timingIndex === -1)
+            continue;
+        const [from = "", to = ""] = (lines[timingIndex] ?? "").split("-->");
+        const start = parseStamp(from);
+        const end = parseStamp(to.trim().split(/\s+/)[0] ?? "");
+        if (start === undefined || end === undefined || end <= start)
+            continue;
+        const body = clean(lines.slice(timingIndex + 1).join(" "));
+        if (body === "")
+            continue;
+        cues.push({ start, end, text: body });
+    }
+    if (kind === "vtt")
+        cues.sort((a, b) => a.start - b.start);
+    return cues;
+}
+const stamp = (value, separator) => {
+    const total = Math.max(0, Math.round(value * 1000));
+    const ms = total % 1000;
+    const sec = Math.floor(total / 1000) % 60;
+    const min = Math.floor(total / 60_000) % 60;
+    const hour = Math.floor(total / 3_600_000);
+    const two = (n) => String(n).padStart(2, "0");
+    return `${two(hour)}:${two(min)}:${two(sec)}${separator}${String(ms).padStart(3, "0")}`;
+};
+export function formatSrt(cues) {
+    return `${cues
+        .map((cue, index) => `${index + 1}\n${stamp(cue.start, ",")} --> ${stamp(cue.end, ",")}\n${cue.text}`)
+        .join("\n\n")}\n`;
+}
+export function formatVtt(cues) {
+    const body = cues
+        .map((cue) => `${stamp(cue.start, ".")} --> ${stamp(cue.end, ".")}\n${cue.text}`)
+        .join("\n\n");
+    return `WEBVTT\n\n${body}\n`;
+}

package/dist/catalog/command.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "../types.ts";
+export declare const catalogCommand: Command;

package/dist/catalog/command.js

@@ -0,0 +1,60 @@
+import { join } from "node:path";
+import { sceneDocs } from "@anvpx/motion-build";
+import { parseFlags, requirePositional, textFlag, usageError } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { detailJson, formatCatalogMarkdown, formatDetail, formatIndex, indexJson, } from "./format.js";
+const USAGE = `mk catalog [<scene>] [--json] [--write [--out <file>]]
+
+No argument: one line per scene (type, layer, purpose, required fields).
+With <scene>: its fields, types, defaults and a minimal example.
+  --json        one compact JSON line instead of text
+  --write       write CATALOG.md in the current directory (or --out <file>) from the registry
+`;
+const FLAGS = {
+    json: { type: "boolean" },
+    write: { type: "boolean" },
+    out: { type: "string" },
+};
+/** Default `--write` destination: the invoking directory, never the repo root. */
+const defaultCatalogFile = () => join(process.cwd(), "CATALOG.md");
+const pick = (docs, type) => docs.find((doc) => doc.type === type);
+async function writeCatalog(docs, flags, positionals, io) {
+    if (positionals.length > 0)
+        return usageError("catalog", USAGE, "--write takes no scene", io).code;
+    const file = textFlag(flags, "out") ?? defaultCatalogFile();
+    const text = formatCatalogMarkdown(docs);
+    await io.host.writeText(file, text);
+    io.stdout(`wrote ${file} (${text.length} chars, ${docs.length} scenes)
+`);
+    return EXIT.OK;
+}
+function showScene(docs, positionals, json, io) {
+    const type = requirePositional("catalog", USAGE, positionals, "<scene>", io);
+    if (typeof type !== "string")
+        return type.code;
+    const doc = pick(docs, type);
+    if (!doc) {
+        const known = docs.map((d) => d.type).join("|");
+        return usageError("catalog", USAGE, `unknown scene "${type}"; use one of: ${known}`, io).code;
+    }
+    io.stdout(json ? detailJson(doc) : formatDetail(doc));
+    return EXIT.OK;
+}
+export const catalogCommand = {
+    name: "catalog",
+    summary: "list scene types, or show one scene's fields and example; --write refreshes CATALOG.md",
+    async run(args, io) {
+        const parsed = parseFlags("catalog", USAGE, args, FLAGS, io);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const { flags, positionals } = parsed;
+        const docs = sceneDocs();
+        if (flags.write === true)
+            return writeCatalog(docs, flags, positionals, io);
+        const json = flags.json === true;
+        if (positionals.length > 0)
+            return showScene(docs, positionals, json, io);
+        io.stdout(json ? indexJson(docs) : formatIndex(docs));
+        return EXIT.OK;
+    },
+};

package/dist/catalog/format.d.ts

@@ -0,0 +1,13 @@
+import type { SceneDoc } from "@anvpx/motion-build";
+/** Constitution 8.4: the index stays within 3k tokens (estimated as chars / 4). */
+export declare const INDEX_TOKEN_BUDGET = 3000;
+export declare const CHARS_PER_TOKEN = 4;
+/** One line per scene: `type | layer | purpose | required fields`. */
+export declare const formatIndex: (docs: readonly SceneDoc[]) => string;
+/** Fields (`*` = required), types, defaults and a minimal example of one scene. */
+export declare const formatDetail: (doc: SceneDoc) => string;
+export declare const indexJson: (docs: readonly SceneDoc[]) => string;
+export declare const detailJson: (doc: SceneDoc) => string;
+/** The committed CATALOG.md: deterministic, generated, index first. */
+export declare const formatCatalogMarkdown: (docs: readonly SceneDoc[]) => string;
+export declare const estimateTokens: (text: string) => number;