@anvpx/motion-cli 0.0.0-stage → 0.1.0

package/dist/template/list.js

@@ -0,0 +1,116 @@
+import { entriesOf, filterEntries, loadTemplate, rankEntries, } from "@anvpx/motion-build";
+import { EXIT } from "../exit-codes.js";
+import { discover, loadOptions } from "./env.js";
+import { clip, lengthLabel } from "./format.js";
+export const LIST_MAX_LINES = 15;
+/** Ranked or filtered blueprints shown (one header line on top: 9 lines in all). */
+export const BLUEPRINT_ROWS = 8;
+const SUMMARY_MAX = 70;
+const GOOD_FOR_MAX = 70;
+const TOP_TAGS = 4;
+/** `--for`, `--tag`, `--aspect` or `--sec` switch the listing from templates to blueprints. */
+const wantsBlueprints = (request) => request.query !== undefined ||
+    (request.filters.tags?.length ?? 0) > 0 ||
+    request.filters.aspect !== undefined ||
+    request.filters.sec !== undefined;
+const capLines = (lines) => lines.length <= LIST_MAX_LINES
+    ? lines
+    : [...lines.slice(0, LIST_MAX_LINES - 1), `(+${lines.length - LIST_MAX_LINES + 1} more)`];
+const loadAll = (env, io) => {
+    const found = discover(env, io);
+    const loaded = found.templates.flatMap((candidate) => {
+        const result = loadTemplate(candidate.dir, loadOptions(env));
+        return result.ok ? [{ template: result.value, source: candidate.source }] : [];
+    });
+    return { found, loaded };
+};
+const templateRow = (template, source) => {
+    const { manifest } = template;
+    const tags = manifest.discover?.tags.slice(0, TOP_TAGS) ?? [];
+    return {
+        id: `${manifest.id}@${manifest.version}`,
+        summary: manifest.summary,
+        domains: manifest.domains,
+        tags,
+        aspects: manifest.discover?.aspects ?? [],
+        blueprints: manifest.blueprints.map((b) => b.id),
+        source,
+    };
+};
+const dash = (items) => (items.length === 0 ? "-" : items.join(","));
+function listTemplates(request, env, io) {
+    const { found, loaded } = loadAll(env, io);
+    const wanted = request.domain?.toLowerCase();
+    const rows = loaded
+        .filter(({ template }) => wanted === undefined || template.manifest.domains.some((d) => d.toLowerCase() === wanted))
+        .map(({ template, source }) => templateRow(template, source));
+    const shadowed = found.shadowed.map((s) => `! ${s.id}@${s.version} (${s.source}) shadowed by ${s.reason === "root" ? "higher-precedence root" : "newer version"}: ${s.by}`);
+    const problems = found.problems.map((p) => `! ${p.path}: ${p.message}`);
+    if (request.json) {
+        io.stdout(`${JSON.stringify({ templates: rows, shadowed, problems })}\n`);
+        return EXIT.OK;
+    }
+    const lines = [
+        ...rows.map((r) => `${r.id} | ${clip(r.summary, SUMMARY_MAX)} | ${dash(r.tags)} | ${dash(r.aspects)} | ${r.blueprints.join(",")} | ${r.source}`),
+        ...shadowed,
+        ...problems,
+    ];
+    if (lines.length === 0) {
+        lines.push(wanted === undefined ? "no templates found" : `no template for domain "${request.domain}"`);
+    }
+    io.stdout(`${capLines(lines).join("\n")}\n`);
+    return EXIT.OK;
+}
+const idOf = (entry) => `${entry.template}/${entry.blueprint}`;
+const pickText = (entry) => clip(entry.goodFor === "" ? entry.purpose : entry.goodFor, GOOD_FOR_MAX);
+const criteria = (request) => {
+    const { tags = [], aspect, sec } = request.filters;
+    return [
+        request.query === undefined ? "" : `for "${request.query}"`,
+        tags.length === 0 ? "" : `tag ${tags.join(",")}`,
+        aspect === undefined ? "" : `aspect ${aspect}`,
+        sec === undefined ? "" : `sec ${sec}`,
+    ]
+        .filter((part) => part !== "")
+        .join(" ");
+};
+const rowOf = (entry, hit) => {
+    const tail = `${pickText(entry)} | ${lengthLabel(entry.lengths)} | ${dash(entry.aspects)}`;
+    if (hit === undefined)
+        return `${idOf(entry)} | ${tail}`;
+    const mark = hit.notFor ? `${hit.score} NOT-FOR` : String(hit.score);
+    return `${idOf(entry)} | ${mark} | ${tail} | why: ${hit.why.join(",")}`;
+};
+function listBlueprints(request, env, io) {
+    const { loaded } = loadAll(env, io);
+    const filtered = filterEntries(entriesOf(loaded.map((item) => item.template)), request.filters);
+    const hits = request.query === undefined ? undefined : rankEntries(filtered, request.query, env.stopwords);
+    const shown = hits === undefined
+        ? filtered.map((entry) => ({ entry, hit: undefined }))
+        : hits.map((hit) => ({ entry: hit.entry, hit }));
+    const top = shown.slice(0, BLUEPRINT_ROWS);
+    if (request.json) {
+        const blueprints = top.map(({ entry, hit }) => ({
+            id: idOf(entry),
+            goodFor: entry.goodFor,
+            aspects: entry.aspects,
+            lengths: entry.lengths ?? null,
+            ...(hit === undefined ? {} : { score: hit.score, notFor: hit.notFor, why: hit.why }),
+        }));
+        io.stdout(`${JSON.stringify({ total: shown.length, blueprints })}\n`);
+        return EXIT.OK;
+    }
+    const count = shown.length > top.length ? `top ${top.length} of ${shown.length}` : `${shown.length}`;
+    const header = `blueprints ${criteria(request)}: ${count}`;
+    const lines = top.length === 0
+        ? [header, "no blueprint matches; relax a filter or reword --for"]
+        : [header, ...top.map(({ entry, hit }) => rowOf(entry, hit))];
+    io.stdout(`${lines.join("\n")}\n`);
+    return EXIT.OK;
+}
+/** `mk template list`: templates, or (with `--for/--tag/--aspect/--sec`) ranked or filtered blueprints. */
+export async function list(request, env, io) {
+    return wantsBlueprints(request)
+        ? listBlueprints(request, env, io)
+        : listTemplates(request, env, io);
+}

package/dist/template/new.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "../types.ts";
+import { type TemplateEnv } from "./env.ts";
+export declare const TEMPLATE_PROVENANCE = "template.json";
+/** `mk new`; `env` is injectable for tests. */
+export declare const makeNewCommand: (env?: () => TemplateEnv) => Command;
+export declare const newCommand: Command;

package/dist/template/new.js

@@ -0,0 +1,302 @@
+import { createHash } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { instantiate, resolveTimeline, sceneDocs, validateStoryboardFull, } from "@anvpx/motion-build";
+import { canonicalJson, LENGTH_CLASSES, } from "@anvpx/motion-schema";
+import { MK_DIR, mkDir, storyboardStem } from "../approval/hash.js";
+import { listFlag, parseFlags, textFlag, usageError } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { readJsonFile } from "../storyboard/load.js";
+import { formatFindings } from "../storyboard/report.js";
+import { coerceSets } from "./coerce.js";
+import { defaultEnv, findTemplate, formatErrors, platformsFor } from "./env.js";
+export const TEMPLATE_PROVENANCE = "template.json";
+/** Bare `mk new --demo` target: the most familiar blueprint. */
+const DEFAULT_DEMO = "explain/architecture";
+const USAGE = `mk new [<template>/<blueprint>] [--demo] [--with scene[,scene] ...] [--set k=v ...] [--slots file.json] [--style s] [--length l] [--out storyboard.json] [--json]
+
+Instantiate a blueprint into a plain, validated storyboard. Writes the storyboard, vendors the theme(s) it uses
+into <out dir>/themes/ (the project builds without the template installed) and records provenance in <out dir>/.mk/<name>/template.json.
+  --demo         start from the blueprint's own example; --slots/--set still win. Without a target, demo uses ${DEFAULT_DEMO}.
+  --with t[,t]   append one base scene per type after the blueprint; props come from the catalog example
+                 merged with slots["$with"]["<type>"] (same --slots file), then the whole storyboard validates.
+  --set k=v      one slot; lists as k=a|b|c, backslash-pipe for a literal pipe (repeatable; wins over --slots)
+  --slots f      JSON object of slots (needed for object slots); may carry a "$with" object for --with props
+  --style s      style id (default: the blueprint's default)
+  --length l     short|standard|long (default: the blueprint's default)
+  --out f        storyboard path (default storyboard.json)
+See \`mk template show <template>/<blueprint>\` for slots and limits.
+`;
+const FLAGS = {
+    demo: { type: "boolean" },
+    with: { type: "string", multiple: true },
+    set: { type: "string", multiple: true },
+    slots: { type: "string" },
+    style: { type: "string" },
+    length: { type: "string" },
+    out: { type: "string" },
+    json: { type: "boolean" },
+};
+/** Reserved slots key holding per-scene props for `--with`; stripped before slot resolution. */
+const WITH_KEY = "$with";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const MAX_WARNING_LINES = 5;
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+async function slotsFile(path, io) {
+    if (path === undefined)
+        return { slots: {}, withProps: {} };
+    const loaded = await readJsonFile(path, io.host);
+    if (!loaded.ok) {
+        io.stderr(`mk new: ${loaded.message}\n`);
+        return EXIT.USAGE;
+    }
+    const value = loaded.value;
+    if (!isRecord(value)) {
+        io.stderr(`mk new: ${path} must hold a JSON object of slots\n`);
+        return EXIT.USAGE;
+    }
+    const { [WITH_KEY]: withRaw, ...slots } = value;
+    if (withRaw !== undefined && !isRecord(withRaw)) {
+        io.stderr(`mk new: ${path} "${WITH_KEY}" must be an object keyed by scene type\n`);
+        return EXIT.USAGE;
+    }
+    return { slots, withProps: isRecord(withRaw) ? withRaw : {} };
+}
+/** Resolves `<template>/<blueprint>`; a miss prints the known ids and yields an exit code. */
+function resolveTarget(target, env, io) {
+    const [templateId = "", blueprintId = "", ...extra] = target.split("/");
+    if (blueprintId === "" || extra.length > 0) {
+        return usageError("new", USAGE, "target must be <template>/<blueprint>", io).code;
+    }
+    const found = findTemplate(env, io, templateId);
+    if (!found.ok) {
+        io.stderr(`mk new: ${found.message}
+`);
+        return EXIT.USAGE;
+    }
+    const blueprint = found.template.blueprints.get(blueprintId);
+    if (blueprint === undefined) {
+        const known = [...found.template.blueprints.keys()].join("|");
+        io.stderr(`mk new: unknown blueprint "${blueprintId}"; use one of: ${known}
+`);
+        return EXIT.USAGE;
+    }
+    return { template: found.template, blueprintId, blueprint };
+}
+/** `--demo`: the blueprint's own example values, or an exit code when it has none (never invented). */
+function demoSlots(target, io) {
+    if (Object.keys(target.blueprint.example).length > 0)
+        return target.blueprint.example;
+    io.stderr(`mk new: ${target.template.manifest.id}/${target.blueprintId} has no example slots; pass --slots or --set
+`);
+    return EXIT.USAGE;
+}
+/** `--demo` example first, then `--slots`, then `--set` (which wins); an exit code on bad input. */
+async function gatherSlots(flags, target, io) {
+    const base = flags.demo === true ? demoSlots(target, io) : {};
+    if (typeof base === "number")
+        return base;
+    const fromFile = await slotsFile(textFlag(flags, "slots"), io);
+    if (typeof fromFile === "number")
+        return fromFile;
+    const sets = coerceSets(target.blueprint.slots, listFlag(flags, "set"));
+    if (sets.ok) {
+        return {
+            slots: { ...base, ...fromFile.slots, ...sets.value },
+            withProps: fromFile.withProps,
+        };
+    }
+    io.stderr(`mk new: ${formatErrors(sets.errors)}
+`);
+    return EXIT.USAGE;
+}
+/** Writes the storyboard, the vendored theme(s) and the provenance record; returns the storyboard path. */
+async function writeProject(made, outFlag, io) {
+    const out = resolve(outFlag ?? "storyboard.json");
+    const dir = dirname(out);
+    const text = `${made.text}
+`;
+    await io.host.writeText(out, text);
+    for (const theme of made.themes)
+        await io.host.writeText(join(dir, theme.file), theme.text);
+    const record = { ...made.provenance, storyboardSha256: sha256(text) };
+    await io.host.writeText(join(mkDir(out), TEMPLATE_PROVENANCE), `${JSON.stringify(record, null, 2)}
+`);
+    return out;
+}
+function report(made, out, json, io) {
+    const { meta } = made.storyboard;
+    const overlays = made.storyboard.scenes.filter((s) => s.layer === "overlay").length;
+    const scenes = made.sceneCount - overlays;
+    const frame = { width: meta.width, height: meta.height, fps: meta.fps };
+    const files = made.themes.map((t) => t.file);
+    if (json) {
+        const { provenance, totalSec } = made;
+        const doc = {
+            ok: true,
+            storyboard: out,
+            ...provenance,
+            scenes,
+            overlays,
+            totalSec,
+            frame,
+            themes: files,
+            warnings: made.warnings.length,
+        };
+        io.stdout(`${JSON.stringify(doc)}
+`);
+        return;
+    }
+    const { provenance } = made;
+    const label = `${provenance.template.split("@")[0]}/${provenance.blueprint}`;
+    io.stdout(`new ok | ${label} style ${provenance.style} length ${provenance.length} | ${scenes} scenes + ${overlays} overlays ${made.totalSec}s ${frame.width}x${frame.height}@${frame.fps} | ${made.warnings.length} warnings
+` +
+        `wrote ${out} (+ ${files.join(", ")}, ${MK_DIR}/${storyboardStem(out)}/${TEMPLATE_PROVENANCE})
+` +
+        `next: mk validate ${out} && mk preview ${out}
+`);
+}
+const lengthOf = (flags, io) => {
+    const length = textFlag(flags, "length");
+    if (length === undefined)
+        return undefined;
+    if (LENGTH_CLASSES.includes(length))
+        return length;
+    return usageError("new", USAGE, `--length must be ${LENGTH_CLASSES.join("|")}`, io).code;
+};
+const appendScenes = (made, types, withProps) => {
+    if (types.length === 0)
+        return { ok: true, value: made };
+    const docs = new Map(sceneDocs().map((doc) => [doc.type, doc]));
+    const ids = new Set(made.storyboard.scenes.map((scene) => scene.id));
+    const appended = [];
+    for (const type of types) {
+        const doc = docs.get(type);
+        if (doc === undefined) {
+            return { ok: false, message: `unknown scene type "${type}"; run mk catalog` };
+        }
+        if (doc.layer === "overlay") {
+            return {
+                ok: false,
+                message: `"${type}" is an overlay; --with appends base scenes (use mk scene add for overlays)`,
+            };
+        }
+        const override = withProps[type];
+        if (override !== undefined && !isRecord(override)) {
+            return { ok: false, message: `"${WITH_KEY}.${type}" must be an object of props` };
+        }
+        const provided = isRecord(override) ? override : {};
+        const missing = doc.fields
+            .filter((field) => field.required && provided[field.name] === undefined)
+            .map((field) => field.name);
+        if (missing.length > 0) {
+            return {
+                ok: false,
+                message: `${type} needs ${missing.join(", ")}; add them under "${WITH_KEY}"."${type}" in --slots`,
+            };
+        }
+        // The slot object is the complete props value: no example defaults leak in
+        // (the kinetic example pins emphasis to a word index that the new words may not have).
+        const props = provided;
+        let id = type;
+        let suffix = 2;
+        while (ids.has(id)) {
+            id = `${type}-${suffix}`;
+            suffix += 1;
+        }
+        ids.add(id);
+        appended.push({ id, type, props });
+    }
+    const storyboard = {
+        ...made.storyboard,
+        scenes: [...made.storyboard.scenes, ...appended],
+    };
+    const valid = validateStoryboardFull(storyboard);
+    if (!valid.ok)
+        return { ok: false, message: formatErrors(valid.errors) };
+    const timeline = resolveTimeline(valid.value);
+    if (!timeline.ok)
+        return { ok: false, message: formatErrors(timeline.errors) };
+    return {
+        ok: true,
+        value: {
+            ...made,
+            storyboard: valid.value,
+            text: canonicalJson(valid.value),
+            sceneCount: valid.value.scenes.length,
+            totalSec: timeline.value.total,
+        },
+    };
+};
+/** `--with t[,t]` entries, trimmed and de-duplicated by scene type. */
+const withTypesOf = (flags) => [
+    ...new Set(listFlag(flags, "with")
+        .flatMap((value) => value.split(","))
+        .map((value) => value.trim())
+        .filter((value) => value !== "")),
+];
+/** Everything `instantiate` needs, from flags and the template; an exit code on bad input. */
+async function plan(args, env, io) {
+    const parsed = parseFlags("new", USAGE, args, FLAGS, io);
+    if (parsed.kind === "exit")
+        return parsed.code;
+    const [positional, ...extra] = parsed.positionals;
+    if (extra.length > 0) {
+        return usageError("new", USAGE, `unexpected argument "${extra[0]}"`, io).code;
+    }
+    const demo = parsed.flags.demo === true;
+    if (positional === undefined && !demo) {
+        return usageError("new", USAGE, "missing <template>/<blueprint> (or pass --demo for the default demo)", io).code;
+    }
+    const name = positional ?? DEFAULT_DEMO;
+    const length = lengthOf(parsed.flags, io);
+    const target = typeof length === "number" ? length : resolveTarget(name, env, io);
+    if (typeof target === "number")
+        return target;
+    const gathered = await gatherSlots(parsed.flags, target, io);
+    if (typeof gathered === "number")
+        return gathered;
+    const style = textFlag(parsed.flags, "style");
+    const options = {
+        ...(style === undefined ? {} : { style }),
+        ...(length === undefined ? {} : { length: length }),
+        platforms: await platformsFor(io),
+    };
+    return {
+        target,
+        slots: gathered.slots,
+        withTypes: withTypesOf(parsed.flags),
+        withProps: gathered.withProps,
+        options,
+        out: textFlag(parsed.flags, "out"),
+        json: parsed.flags.json === true,
+    };
+}
+/** `mk new`; `env` is injectable for tests. */
+export const makeNewCommand = (env = defaultEnv) => ({
+    name: "new",
+    summary: "instantiate a template blueprint into a validated storyboard",
+    async run(args, io) {
+        const planned = await plan(args, env(), io);
+        if (typeof planned === "number")
+            return planned;
+        const { target, slots, options } = planned;
+        const result = instantiate(target.template, target.blueprintId, slots, options);
+        if (!result.ok) {
+            const label = `${target.template.manifest.id}/${target.blueprintId}`;
+            io.stderr(`mk new: ${formatErrors(result.errors)}
+run mk template show ${label} for the required slots (the use line is copy-pasteable)
+`);
+            return EXIT.USAGE;
+        }
+        const appended = appendScenes(result.value, planned.withTypes, planned.withProps);
+        if (!appended.ok) {
+            io.stderr(`mk new: ${appended.message}\n`);
+            return EXIT.USAGE;
+        }
+        const out = await writeProject(appended.value, planned.out, io);
+        report(appended.value, out, planned.json, io);
+        io.stderr(formatFindings(appended.value.warnings.slice(0, MAX_WARNING_LINES)));
+        return EXIT.OK;
+    },
+});
+export const newCommand = makeNewCommand();

package/dist/testing/env.d.ts

@@ -0,0 +1,8 @@
+import { type TemplateEnv } from "../template/env.ts";
+/**
+ * The environment the real CLI passes (`defaultEnv`: built-ins, shared themes, stopwords) pinned to a
+ * project directory and with `MK_TEMPLATES_PATH` cleared, so tests cannot drift from production.
+ */
+export declare const testEnv: (projectDir: string, overrides?: Partial<TemplateEnv>) => TemplateEnv;
+/** `<id>@<version>` of a built-in template, read from its manifest (never hard-coded in tests). */
+export declare const builtInRef: (id: string) => string;

package/dist/testing/env.js

@@ -0,0 +1,19 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { TEMPLATES_DIR } from "@anvpx/motion-templates";
+import { defaultEnv } from "../template/env.js";
+/**
+ * The environment the real CLI passes (`defaultEnv`: built-ins, shared themes, stopwords) pinned to a
+ * project directory and with `MK_TEMPLATES_PATH` cleared, so tests cannot drift from production.
+ */
+export const testEnv = (projectDir, overrides = {}) => ({
+    ...defaultEnv(),
+    envPath: undefined,
+    projectDir,
+    ...overrides,
+});
+/** `<id>@<version>` of a built-in template, read from its manifest (never hard-coded in tests). */
+export const builtInRef = (id) => {
+    const manifest = JSON.parse(readFileSync(join(TEMPLATES_DIR, id, "template.json"), "utf8"));
+    return `${id}@${manifest.version}`;
+};

package/dist/testing/fakes.d.ts

@@ -0,0 +1,33 @@
+import type { CommandResult, Host, Io, Runner, RunOptions } from "../types.ts";
+export declare const NOT_FOUND: CommandResult;
+export declare function ok(stdout?: string): CommandResult;
+export declare function failed(code: number, stderr: string, stdout?: string): CommandResult;
+/** A canned result, or a function that may also act (e.g. create the files a tool would). */
+export type Response = CommandResult | ((options: RunOptions | undefined) => CommandResult | Promise<CommandResult>);
+/**
+ * Runner answering by exact "cmd arg arg" key; anything else is command-not-found.
+ * `calls` records each key, `options` the RunOptions of the same call.
+ */
+export declare function fakeRunner(responses: Record<string, Response>, calls?: string[], options?: (RunOptions | undefined)[]): Runner;
+export interface HostOptions {
+    platform?: NodeJS.Platform;
+    nodeVersion?: string;
+    homeDir?: string;
+    env?: Readonly<Record<string, string | undefined>>;
+    dirs?: Record<string, string[]>;
+    packageJson?: unknown;
+    /** Readable files by exact path. */
+    files?: Record<string, string>;
+}
+export interface FakeHost extends Host {
+    written: Record<string, string>;
+    removed: string[];
+}
+export declare function fakeHost(options?: HostOptions): FakeHost;
+/** The real filesystem (real build into a temp dir) with a stubbed root package.json. */
+export declare function diskHost(packageJson: unknown): Host;
+export interface FakeIo extends Io {
+    out: string[];
+    err: string[];
+}
+export declare function fakeIo(run: Runner, host?: Host): FakeIo;

package/dist/testing/fakes.js

@@ -0,0 +1,95 @@
+import { createHash } from "node:crypto";
+import { nodeHost } from "../node-io.js";
+export const NOT_FOUND = { code: 127, stdout: "", stderr: "not found" };
+export function ok(stdout = "") {
+    return { code: 0, stdout, stderr: "" };
+}
+export function failed(code, stderr, stdout = "") {
+    return { code, stdout, stderr };
+}
+/**
+ * Runner answering by exact "cmd arg arg" key; anything else is command-not-found.
+ * `calls` records each key, `options` the RunOptions of the same call.
+ */
+export function fakeRunner(responses, calls = [], options = []) {
+    return async (cmd, args, runOptions) => {
+        const key = [cmd, ...args].join(" ");
+        calls.push(key);
+        options.push(runOptions);
+        const response = responses[key];
+        if (response === undefined)
+            return NOT_FOUND;
+        return typeof response === "function" ? response(runOptions) : response;
+    };
+}
+export function fakeHost(options = {}) {
+    const dirs = options.dirs ?? {};
+    const files = options.files ?? {};
+    const written = {};
+    const removed = [];
+    return {
+        platform: options.platform ?? "win32",
+        nodeVersion: options.nodeVersion ?? "24.12.0",
+        homeDir: options.homeDir ?? "/home/u",
+        env: options.env ?? {},
+        async listDir(path) {
+            const entries = dirs[path];
+            if (!entries)
+                throw new Error(`ENOENT: ${path}`);
+            return entries;
+        },
+        async mkdir(path) {
+            dirs[path] = dirs[path] ?? [];
+        },
+        async readRootPackageJson() {
+            return options.packageJson;
+        },
+        async readText(path) {
+            const text = files[path] ?? written[path];
+            if (text === undefined)
+                throw new Error(`ENOENT: ${path}`);
+            return text;
+        },
+        async writeText(path, text) {
+            written[path] = text;
+        },
+        async writeTextAtomic(path, text) {
+            written[path] = text;
+        },
+        async exists(path) {
+            return (files[path] ?? written[path]) !== undefined || path in dirs;
+        },
+        async copyFile(from, to) {
+            const text = files[from] ?? written[from];
+            if (text === undefined)
+                throw new Error(`ENOENT: ${from}`);
+            written[to] = text;
+        },
+        async renameFile(from, to) {
+            const text = files[from] ?? written[from];
+            if (text === undefined)
+                throw new Error(`ENOENT: ${from}`);
+            written[to] = text;
+            // Mirrors node:rename: the source is gone after the move.
+            delete written[from];
+        },
+        async sha256File(path) {
+            const text = files[path] ?? written[path];
+            return text === undefined ? undefined : createHash("sha256").update(text).digest("hex");
+        },
+        async remove(path) {
+            removed.push(path);
+        },
+        written,
+        removed,
+    };
+}
+/** The real filesystem (real build into a temp dir) with a stubbed root package.json. */
+export function diskHost(packageJson) {
+    return { ...nodeHost(), readRootPackageJson: async () => packageJson };
+}
+export function fakeIo(run, host = fakeHost()) {
+    const out = [];
+    const err = [];
+    return { stdout: (t) => out.push(t), stderr: (t) => err.push(t), run, host, out, err };
+}

package/dist/testing/fixtures.d.ts

@@ -0,0 +1,8 @@
+/** The 5-scene demo storyboard, as raw text. */
+export declare const demoText: () => string;
+export interface LooseBoard {
+    scenes: Record<string, unknown>[];
+    [key: string]: unknown;
+}
+/** A fresh deep copy of the demo storyboard for mutation in tests. */
+export declare const demoBoard: () => LooseBoard;

package/dist/testing/fixtures.js

@@ -0,0 +1,6 @@
+import { readFileSync } from "node:fs";
+const DEMO = new URL("../../../build/fixtures/demo.storyboard.json", import.meta.url);
+/** The 5-scene demo storyboard, as raw text. */
+export const demoText = () => readFileSync(DEMO, "utf8");
+/** A fresh deep copy of the demo storyboard for mutation in tests. */
+export const demoBoard = () => JSON.parse(demoText());

package/dist/testing/probe.d.ts

@@ -0,0 +1,15 @@
+export declare const probeKey: (file: string) => string;
+export interface ProbeInit {
+    width?: number;
+    height?: number;
+    rate?: string;
+    frames?: number;
+    duration?: number;
+    codec?: string;
+    pixFmt?: string;
+    audio?: string;
+}
+/** ffprobe JSON for the demo storyboard's final render: 1920x1080, 30 fps, 32.5 s, 975 frames. */
+export declare function probeJson(init?: ProbeInit): string;
+/** The same render as a draft: 960x540 at 15 fps (488 frames). */
+export declare const draftProbeJson: (init?: ProbeInit) => string;

package/dist/testing/probe.js

@@ -0,0 +1,20 @@
+export const probeKey = (file) => `ffprobe -v error -show_streams -show_format -of json ${file}`;
+/** ffprobe JSON for the demo storyboard's final render: 1920x1080, 30 fps, 32.5 s, 975 frames. */
+export function probeJson(init = {}) {
+    const streams = [
+        {
+            codec_type: "video",
+            codec_name: init.codec ?? "h264",
+            pix_fmt: init.pixFmt ?? "yuv420p",
+            width: init.width ?? 1920,
+            height: init.height ?? 1080,
+            r_frame_rate: init.rate ?? "30/1",
+            nb_frames: String(init.frames ?? 975),
+        },
+    ];
+    if (init.audio)
+        streams.push({ codec_type: "audio", codec_name: init.audio });
+    return JSON.stringify({ streams, format: { duration: String(init.duration ?? 32.5) } });
+}
+/** The same render as a draft: 960x540 at 15 fps (488 frames). */
+export const draftProbeJson = (init = {}) => probeJson({ width: 960, height: 540, rate: "15/1", frames: 488, ...init });

package/dist/testing/project.d.ts

@@ -0,0 +1,22 @@
+export declare const PIN = "0.8.212";
+export declare const PINNED_PACKAGE: {
+    motionKit: {
+        pins: {
+            hyperframes: string;
+        };
+    };
+};
+/** Fake-runner key for `node <resolved hyperframes CLI> <args>` (mirrors runInProject). */
+export declare const hfKey: (...args: readonly string[]) => string;
+/** Fake-runner key for the hyperframes pin check. */
+export declare const VERSION_KEY: string;
+export interface TempProject {
+    dir: string;
+    storyboard: string;
+    /** Default build output: `<dir>/out/project`. */
+    out: string;
+}
+/** A temp directory holding the demo storyboard; removed when the test finishes. */
+export declare function tempProject(storyboardText?: string): TempProject;
+/** Creates empty files, as a stand-in for what an external tool would produce. */
+export declare function touch(dir: string, ...names: string[]): void;