@anvpx/motion-cli 0.0.0-stage → 0.1.0

package/dist/approval/command.js

@@ -0,0 +1,255 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { parseFlags, requireStoryboard, textFlag } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { defaultOut, previewManifestPath } from "../preview/manifest.js";
+import { writeApproval } from "./approval.js";
+import { buildApprovalInputManifest, hashApprovalInput, } from "./hash.js";
+const USAGE = `mk approve <storyboard.json> [--note "<user words>"] [--out <dir>] [--assets <dir>] [--ledger file] [--audio manifest] [--music <bed.wav>] [--music-volume <n>] [--music-license <file>]
+
+Record the user's approval of the CURRENT inputs (visual, audiovisual or audiovisual+music) in <storyboard dir>/.mk/<name>/approval.json.
+Run it only after the user has seen the preview pack and said an explicit yes. Opt-in music is covered by the same gate (no parallel gate).
+Refuses (exit 2) when <out>/<name>.preview/preview.json does not exist for the current inputs: run \`mk preview\` first.
+Every preview input (assets, ledger, audio, music, volume, license) is inferred from the pack; an explicit flag
+must match the pack or the command exits 2 naming the difference.
+Any later edit to the storyboard, its themes, its referenced assets or its ledger, or (for audiovisual) its audio manifest, wavs, mix, bed, volume or license receipt re-arms \`mk render --gated\` (exit 4).
+  --note   the user's words, stored with the approval
+  --out d  the --out used for \`mk preview\` (default <storyboard dir>/out)
+  --assets d  the --assets used for \`mk preview\` (default: none)
+  --ledger f  the --ledger used for preview (default: none)
+  --audio manifest  the --audio used for preview (default: none; mismatch exits 2)
+  --music <bed.wav>  the --music bed used for preview (needs --audio; mismatch exits 2)
+  --music-volume <n>  the --music-volume used for preview (within (0, 1])
+  --music-license <file>  the --music-license used for preview (hash only)
+`;
+const previewed = (text) => {
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed.inputManifest !== undefined && parsed.inputManifestSha256 !== undefined) {
+            return {
+                inputManifest: parsed.inputManifest,
+                inputManifestSha256: parsed.inputManifestSha256,
+                audioMix: parsed.audioMix,
+                clip: parsed.clip,
+                inputs: parsed.inputs,
+            };
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The pack's recorded invocation inputs; absent only when the pack predates A4. */
+const recordedInputs = (value) => {
+    if (!isRecord(value))
+        return undefined;
+    const path = (key) => typeof value[key] === "string" ? value[key] : null;
+    return {
+        assetsDir: path("assetsDir"),
+        ledger: path("ledger"),
+        audioManifest: path("audioManifest"),
+        music: path("music"),
+        musicVolume: typeof value.musicVolume === "number" ? value.musicVolume : null,
+        musicLicense: path("musicLicense"),
+    };
+};
+/**
+ * A4: an explicit flag must agree with what the pack recorded; when omitted, the
+ * recorded input is reused. Returns the value to resolve with (or an exit code).
+ */
+const pickInput = (name, flag, recorded, io) => {
+    if (flag === undefined)
+        return recorded ?? undefined;
+    if (recorded !== null && resolve(flag) !== recorded) {
+        io.stderr(`mk approve: --${name} differs from the preview pack (${recorded}); drop the flag to use the previewed input, or run \`mk preview\` again with this value\n`);
+        return EXIT.USAGE;
+    }
+    return flag;
+};
+const pickVolume = (flag, recorded, io) => {
+    if (flag === undefined)
+        return { ok: true, value: recorded ?? undefined };
+    if (recorded !== null && flag !== recorded) {
+        io.stderr(`mk approve: --music-volume differs from the preview pack (${recorded}); drop the flag to use the previewed level, or run \`mk preview\` again\n`);
+        return { ok: false, code: EXIT.USAGE };
+    }
+    return { ok: true, value: flag };
+};
+const resolveInputs = async (io, storyboard, assetsDir, ledgerPath, audioManifest, musicPath, musicVolume, musicLicensePath) => {
+    try {
+        const manifest = await buildApprovalInputManifest(io.host, storyboard, {
+            ...(assetsDir === undefined ? {} : { assetsDir: resolve(assetsDir) }),
+            ...(ledgerPath === undefined ? {} : { ledgerPath }),
+            ...(audioManifest === undefined ? {} : { audioManifest }),
+            ...(musicPath === undefined ? {} : { music: musicPath }),
+            ...(musicVolume === undefined ? {} : { musicVolume }),
+            ...(musicLicensePath === undefined ? {} : { musicLicense: musicLicensePath }),
+        });
+        return { manifest, hash: hashApprovalInput(manifest) };
+    }
+    catch (error) {
+        io.stderr(`mk approve: cannot resolve approval inputs: ${error.message}\n`);
+        return EXIT.USAGE;
+    }
+};
+const stalePreview = (io, storyboard, reason) => {
+    io.stderr(`mk approve: ${reason}; run \`mk preview ${storyboard}\` again and show it to the user\n`);
+    return EXIT.USAGE;
+};
+/** Verifies a preview binding; returns its sha or an exit code. */
+const verifyBinding = (io, storyboard, inputManifest, inputManifestSha256) => {
+    if (typeof inputManifestSha256 !== "string" || !/^[a-f0-9]{64}$/.test(inputManifestSha256)) {
+        return stalePreview(io, storyboard, "the preview binding is malformed");
+    }
+    try {
+        const recomputed = hashApprovalInput(inputManifest);
+        if (recomputed !== inputManifestSha256) {
+            return stalePreview(io, storyboard, "the preview binding is tampered (sha mismatch)");
+        }
+    }
+    catch {
+        return stalePreview(io, storyboard, "the preview binding is malformed");
+    }
+    return inputManifestSha256;
+};
+const approvePreview = async (io, resolved) => {
+    const preview = previewed(resolved.manifestText);
+    if (preview === undefined) {
+        return stalePreview(io, resolved.storyboard, "the preview is missing the visual input binding");
+    }
+    // RA-02: an audiovisual approval is only valid after the user heard a
+    // playable mixed clip. Silent or skipped clips never authorize audio;
+    // visual-only approvals are unaffected. AU-01: a music receipt is only valid
+    // after an audible clip mixed with the same bed (musicSha/volume/license).
+    if (resolved.inputs.manifest.scope === "audiovisual") {
+        const mix = preview.audioMix;
+        const clip = preview.clip;
+        const previewScope = preview.inputManifest?.scope;
+        const heard = mix?.audible === true && clip?.status === "ok" && previewScope === "audiovisual";
+        if (!heard) {
+            const detail = previewScope !== "audiovisual"
+                ? "the preview is silent (scope visual)"
+                : clip?.status !== "ok"
+                    ? `the preview clip was ${typeof clip?.status === "string" ? clip.status : "missing"}${typeof clip?.reason === "string" ? ` (${clip.reason})` : ""}`
+                    : "the preview is not audible (audible:false, unheard mix)";
+            io.stderr(`mk approve: refusing audiovisual approval: ${detail}; regenerate an audible preview with \`mk preview ${resolved.storyboard} --audio <manifest>\` and show clip.mp4 to the user before approving\n`);
+            return EXIT.USAGE;
+        }
+        const wantMusic = resolved.inputs.manifest.music;
+        if (wantMusic !== undefined) {
+            const heardMusic = mix?.musicSha === wantMusic.sha256 &&
+                mix?.musicVolume === wantMusic.volume &&
+                mix?.musicLicenseSha === wantMusic.licenseEvidenceSha256;
+            if (!heardMusic) {
+                io.stderr(`mk approve: refusing music approval: the preview clip was not mixed with this bed/volume/license; regenerate an audible preview with \`mk preview ${resolved.storyboard} --audio <manifest> --music <bed>\` and show clip.mp4 to the user before approving\n`);
+                return EXIT.USAGE;
+            }
+        }
+        else {
+            const previewMusic = preview.inputManifest?.music;
+            if (previewMusic !== undefined) {
+                return stalePreview(io, resolved.storyboard, "the preview is for an older version of the inputs (music mismatch)");
+            }
+        }
+    }
+    const verified = verifyBinding(io, resolved.storyboard, preview.inputManifest, preview.inputManifestSha256);
+    if (typeof verified === "number")
+        return verified;
+    if (resolved.inputs.hash !== verified) {
+        return stalePreview(io, resolved.storyboard, "the preview is for an older version of the inputs (edited since, or --audio mismatch)");
+    }
+    await writeApproval(io.host, resolved.storyboard, {
+        inputManifest: resolved.inputs.manifest,
+        inputManifestSha256: resolved.inputs.hash,
+        previewManifestSha: resolved.previewManifestSha,
+        approvedAt: new Date().toISOString(),
+        note: resolved.note,
+    });
+    io.stdout(`approved ${resolved.inputs.hash.slice(0, 12)} | mk render ${resolved.storyboard} --gated\n`);
+    return EXIT.OK;
+};
+export const approveCommand = {
+    name: "approve",
+    summary: "record the user's approval of the previewed storyboard",
+    async run(args, io) {
+        const flags = {
+            note: { type: "string" },
+            out: { type: "string" },
+            assets: { type: "string" },
+            ledger: { type: "string" },
+            audio: { type: "string" },
+            music: { type: "string" },
+            "music-volume": { type: "string" },
+            "music-license": { type: "string" },
+        };
+        const parsed = parseFlags("approve", USAGE, args, flags, io);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const storyboard = requireStoryboard("approve", USAGE, parsed.positionals, io);
+        if (typeof storyboard !== "string")
+            return storyboard.code;
+        const musicRaw = textFlag(parsed.flags, "music-volume");
+        let musicVolume;
+        if (musicRaw !== undefined) {
+            musicVolume = Number(musicRaw);
+            if (!Number.isFinite(musicVolume) || musicVolume <= 0 || musicVolume > 1) {
+                io.stderr("mk approve: --music-volume must be within (0, 1]\n");
+                return EXIT.USAGE;
+            }
+        }
+        const out = resolve(textFlag(parsed.flags, "out") ?? defaultOut(storyboard));
+        const manifestFile = previewManifestPath(out, storyboard);
+        let manifestText;
+        try {
+            manifestText = await io.host.readText(manifestFile);
+        }
+        catch {
+            io.stderr(`mk approve: no preview for this storyboard (${manifestFile} is missing); run \`mk preview ${storyboard}\` and show it to the user first\n`);
+            return EXIT.USAGE;
+        }
+        const previewManifestSha = createHash("sha256").update(manifestText).digest("hex");
+        // A4: the pack records the inputs it was made with; omitted flags reuse them.
+        const recorded = recordedInputs(previewed(manifestText)?.inputs);
+        const assetsDir = pickInput("assets", textFlag(parsed.flags, "assets"), recorded?.assetsDir ?? null, io);
+        if (typeof assetsDir === "number")
+            return assetsDir;
+        const ledgerPath = pickInput("ledger", textFlag(parsed.flags, "ledger"), recorded?.ledger ?? null, io);
+        if (typeof ledgerPath === "number")
+            return ledgerPath;
+        const audioFlag = pickInput("audio", textFlag(parsed.flags, "audio"), recorded?.audioManifest ?? null, io);
+        if (typeof audioFlag === "number")
+            return audioFlag;
+        const musicPath = pickInput("music", textFlag(parsed.flags, "music"), recorded?.music ?? null, io);
+        if (typeof musicPath === "number")
+            return musicPath;
+        const mergedVolume = pickVolume(musicVolume, recorded?.musicVolume ?? null, io);
+        if (!mergedVolume.ok)
+            return mergedVolume.code;
+        musicVolume = mergedVolume.value;
+        const musicLicensePath = pickInput("music-license", textFlag(parsed.flags, "music-license"), recorded?.musicLicense ?? null, io);
+        if (typeof musicLicensePath === "number")
+            return musicLicensePath;
+        if (musicPath !== undefined && audioFlag === undefined) {
+            io.stderr("mk approve: --music needs --audio\n");
+            return EXIT.USAGE;
+        }
+        if ((musicVolume !== undefined || musicLicensePath !== undefined) && musicPath === undefined) {
+            io.stderr("mk approve: --music-volume/--music-license need --music\n");
+            return EXIT.USAGE;
+        }
+        const inputs = await resolveInputs(io, storyboard, assetsDir, ledgerPath, audioFlag, musicPath, musicVolume, musicLicensePath);
+        if (typeof inputs === "number")
+            return inputs;
+        const note = textFlag(parsed.flags, "note") ?? "";
+        const resolved = {
+            storyboard,
+            inputs,
+            manifestText,
+            previewManifestSha,
+            note,
+        };
+        return approvePreview(io, resolved);
+    },
+};

package/dist/approval/gate.d.ts

@@ -0,0 +1,7 @@
+import type { Io } from "../types.ts";
+/**
+ * `--gated`: undefined when the current storyboard, themes and authored scenes are approved, else EXIT.AWAITING_APPROVAL
+ * with a message that tells the agent to ask the user (not an error). An unreadable storyboard is
+ * left to the normal build path to report.
+ */
+export declare function approvalGate(io: Io, storyboard: string): Promise<number | undefined>;

package/dist/approval/gate.js

@@ -0,0 +1,23 @@
+import { EXIT } from "../exit-codes.js";
+import { approvalState } from "./approval.js";
+/**
+ * `--gated`: undefined when the current storyboard, themes and authored scenes are approved, else EXIT.AWAITING_APPROVAL
+ * with a message that tells the agent to ask the user (not an error). An unreadable storyboard is
+ * left to the normal build path to report.
+ */
+export async function approvalGate(io, storyboard) {
+    let state;
+    try {
+        state = await approvalState(io.host, storyboard);
+    }
+    catch {
+        return undefined;
+    }
+    if (state.state === "approved")
+        return undefined;
+    const why = state.state === "stale"
+        ? "the storyboard, its themes or its authored scene files changed since it was approved"
+        : "no approval recorded";
+    io.stderr(`mk: AWAITING_APPROVAL (${state.hash.slice(0, 12)}): ${why}. Run \`mk preview ${storyboard}\`, show the user the pack, and only after an explicit yes run \`mk approve ${storyboard}\`.\n`);
+    return EXIT.AWAITING_APPROVAL;
+}

package/dist/approval/hash.d.ts

@@ -0,0 +1,71 @@
+import type { Host } from "../types.ts";
+export declare const MK_DIR = ".mk";
+/** File name without its extension: the namespace of everything a storyboard owns next to itself. */
+export declare const storyboardStem: (storyboard: string) => string;
+/** `<storyboard dir>/.mk/<stem>`: provenance and approval, so two storyboards in one folder never share state. */
+export declare const mkDir: (storyboard: string) => string;
+/**
+ * Reads a sidecar file of `storyboard`. Projects made before the per-storyboard namespace kept it
+ * in `<dir>/.mk/`; that location is still read, and only for a storyboard named `storyboard.json`.
+ */
+export declare function readSidecar(host: Host, storyboard: string, file: string): Promise<string>;
+/**
+ * The approval hash: sha256 over the storyboard bytes, every vendored theme (name + bytes,
+ * sorted by name) and — when the storyboard has authored scenes — every file of those scene
+ * directories. Any edit to any of them changes the hash, which re-arms the gate. Authored
+ * scenes are media-producing input: leaving them out would let `scene.js` change under an
+ * approval and still render.
+ */
+export declare function combineHash(storyboardText: string, themes: readonly (readonly [name: string, text: string])[], scenes?: readonly (readonly [name: string, text: string])[]): string;
+/** Reads the storyboard, `<dir>/themes/*.json` and any authored scene files; rejects when the storyboard is unreadable. */
+export declare function storyboardHash(host: Host, storyboard: string): Promise<string>;
+export interface ManifestRef {
+    readonly path: string;
+    readonly sha256: string;
+}
+export interface MixClipRef {
+    readonly id: string;
+    readonly start: number;
+    readonly wavSha: string;
+}
+export interface MixInfo {
+    readonly mode: "single" | "concat" | "adelay";
+    readonly clips: readonly MixClipRef[];
+}
+export interface MusicInfo {
+    readonly path: string;
+    readonly sha256: string;
+    readonly volume: number;
+    readonly licenseEvidenceSha256: string | null;
+}
+export interface ApprovalInputManifest {
+    readonly scope: "visual" | "audiovisual";
+    readonly storyboard: ManifestRef;
+    readonly themes: readonly ManifestRef[];
+    readonly assets: readonly ManifestRef[];
+    readonly ledgerSha256?: string;
+    readonly audio: readonly ManifestRef[];
+    /** Files of authored (`type: "custom"`) scenes; omitted when the storyboard has none. */
+    readonly scenes?: readonly ManifestRef[];
+    readonly audioManifest?: ManifestRef;
+    readonly mix?: MixInfo;
+    readonly music?: MusicInfo;
+}
+export interface ApprovalBuildOptions {
+    readonly assetsDir?: string;
+    readonly ledgerPath?: string;
+    readonly audioManifest?: string;
+    readonly music?: string;
+    readonly musicVolume?: number;
+    readonly musicLicense?: string;
+}
+export declare function buildApprovalInputManifest(host: Host, storyboard: string, opts?: ApprovalBuildOptions): Promise<ApprovalInputManifest>;
+/**
+ * Canonical hash of the manifest. Sorts themes/assets/audio by UTF-16
+ * code units so enumeration order never changes the digest. No timestamp
+ * or machine path enters the hash. Audiovisual fields (audioManifest + mix)
+ * are covered so wav/manifest/mix changes re-arm the gate. AU-01 music
+ * {path,sha256,volume,licenseEvidenceSha256} is covered so bed/volume/license
+ * changes re-arm the gate.
+ */
+export declare function hashApprovalInput(manifest: ApprovalInputManifest): string;