@anvpx/motion-cli 0.0.0-stage → 0.1.0

package/dist/approval/hash.js

@@ -0,0 +1,451 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { AUDIO_DIR_NAME, normaliseRef as buildNormaliseRef, clipsFromManifest, isContiguous, parseAudioManifest, readRelativeClosure, resolveSceneDir, } from "@anvpx/motion-build";
+import { parseMusicBed } from "@anvpx/motion-schema";
+import { sceneContainment } from "../storyboard/containment.js";
+export const MK_DIR = ".mk";
+const THEMES_DIR = "themes";
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+/** sha256 of zero bytes: a silent/empty wav can never qualify as audible proof. */
+const EMPTY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+/** File name without its extension: the namespace of everything a storyboard owns next to itself. */
+export const storyboardStem = (storyboard) => basename(storyboard, extname(storyboard));
+/** `<storyboard dir>/.mk/<stem>`: provenance and approval, so two storyboards in one folder never share state. */
+export const mkDir = (storyboard) => join(dirname(resolve(storyboard)), MK_DIR, storyboardStem(storyboard));
+/**
+ * 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 async function readSidecar(host, storyboard, file) {
+    try {
+        return await host.readText(join(mkDir(storyboard), file));
+    }
+    catch (error) {
+        if (storyboardStem(storyboard) !== "storyboard")
+            throw error;
+        return host.readText(join(dirname(resolve(storyboard)), MK_DIR, file));
+    }
+}
+/**
+ * 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 function combineHash(storyboardText, themes, scenes = []) {
+    const rows = [...themes].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const sceneRows = [...scenes].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return sha256(JSON.stringify({
+        storyboard: sha256(storyboardText),
+        themes: rows.map(([name, text]) => [name, sha256(text)]),
+        ...(sceneRows.length === 0
+            ? {}
+            : { scenes: sceneRows.map(([name, text]) => [name, sha256(text)]) }),
+    }));
+}
+const SCENE_FILES = ["scene.js", "fragment.html", "style.css"];
+/** Every file of every authored scene directory, as `<props.dir>/<file>` + bytes. */
+async function authoredSceneFiles(host, storyboard, text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    const scenes = parsed.scenes;
+    if (!Array.isArray(scenes))
+        return [];
+    const base = dirname(resolve(storyboard));
+    const files = [];
+    for (const entry of scenes) {
+        const scene = entry;
+        if (scene.type !== "custom")
+            continue;
+        const requested = scene.props?.dir;
+        if (typeof requested !== "string")
+            continue;
+        const resolved = resolveSceneDir(base, requested);
+        if (!resolved.ok)
+            continue;
+        const dirName = requested.replaceAll("\\", "/");
+        // A symlink or junction can point outside while looking project-local; the
+        // loader refuses it, and the approval manifest must not record outside bytes
+        // as local inputs either.
+        const containment = sceneContainment(base, resolved.dir, SCENE_FILES);
+        if (!containment.dirInside) {
+            throw new Error(`custom scene "${requested}" resolves outside the storyboard directory (symlink/junction)`);
+        }
+        if (containment.escapedFiles.length > 0) {
+            throw new Error(`custom scene file "${containment.escapedFiles[0] ?? ""}" resolves outside the scene directory (symlink/junction)`);
+        }
+        for (const file of SCENE_FILES) {
+            const path = join(resolved.dir, file);
+            if (!(await host.exists(path)))
+                continue;
+            files.push([`${dirName}/${file}`, await host.readText(path)]);
+        }
+        // Relative helpers are emitted into the project, so they are approval inputs
+        // too: a helper-only edit must rebuild and re-arm the gate.
+        const jsPath = join(resolved.dir, "scene.js");
+        if (await host.exists(jsPath)) {
+            const closure = await readRelativeClosure(await host.readText(jsPath), async (helper) => {
+                const check = sceneContainment(base, resolved.dir, [helper]);
+                if (!check.dirInside || check.escapedFiles.length > 0) {
+                    throw new Error(`custom scene helper "${helper}" resolves outside the scene (symlink)`);
+                }
+                const full = join(resolved.dir, helper);
+                return (await host.exists(full)) ? host.readText(full) : undefined;
+            });
+            for (const helper of closure.files) {
+                files.push([`${dirName}/${helper.path}`, helper.text]);
+            }
+        }
+    }
+    return files;
+}
+/** Reads the storyboard, `<dir>/themes/*.json` and any authored scene files; rejects when the storyboard is unreadable. */
+export async function storyboardHash(host, storyboard) {
+    const text = await host.readText(storyboard);
+    const dir = join(dirname(resolve(storyboard)), THEMES_DIR);
+    const names = (await host.listDir(dir).catch(() => []))
+        .filter((name) => name.endsWith(".json"))
+        .sort();
+    const themes = await Promise.all(names.map(async (name) => [name, await host.readText(join(dir, name))]));
+    const scenes = await authoredSceneFiles(host, storyboard, text);
+    return combineHash(text, themes, scenes);
+}
+/**
+ * RA-01: the build resolver is the single path authority; the CLI keeps its
+ * own escape taxonomy on top so existing fail-closed messages are unchanged.
+ * The trailing clean check preserves the historical rejection of ".".
+ */
+const normaliseRef = (ref) => {
+    let clean;
+    try {
+        clean = buildNormaliseRef(ref);
+    }
+    catch (error) {
+        throw new Error(`${error.message} (escape)`);
+    }
+    if (clean === "" || clean === "." || clean.startsWith("../") || clean === "..") {
+        throw new Error(`asset "${ref}" escapes the project (escape)`);
+    }
+    return clean;
+};
+const toForwardSlash = (p) => p.split(sep).join("/");
+/** Every storyboard string key that resolves through the asset ledger.
+ * Census of the build surface today: only `image` is emitted by scenes
+ * (bug, media-frame, quote via assetResolver); video/poster/font/lut/src
+ * (+ aliases) are hashed too so a future scene cannot bypass the gate by
+ * renaming the key. Timing/platforms/cache need no extra file hash: timing
+ * and meta.platform are inside the hashed storyboard bytes, platforms ship
+ * pinned with @anvpx/motion-schema, and .mk-cache output is never an input.
+ */
+const ASSET_REF_KEYS = new Set(["image", "video", "poster", "font", "lut"]);
+/** Collects every asset-ref string in the storyboard JSON (see ASSET_REF_KEYS). */
+const collectFromObject = (record, out) => {
+    for (const [key, entry] of Object.entries(record)) {
+        if (typeof entry === "string") {
+            if (ASSET_REF_KEYS.has(key))
+                out.push(entry);
+        }
+        else
+            collectAssetRefs(entry, out);
+    }
+};
+const collectAssetRefs = (value, out) => {
+    if (typeof value === "string")
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectAssetRefs(item, out);
+        return;
+    }
+    if (typeof value === "object" && value !== null) {
+        collectFromObject(value, out);
+    }
+};
+const codeUnitSort = (a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+const insideDir = (root, target) => {
+    const rel = relative(root, target);
+    return rel !== "" && rel.split(sep)[0] !== ".." && !isAbsolute(rel);
+};
+/** Rejects symlinks (or any realpath) escaping the assets dir; skips when off-disk (fake hosts). */
+const assertInsideAssetsDir = (assetsDir, full, ref) => {
+    let realAssets;
+    let realTarget;
+    try {
+        realAssets = realpathSync(resolve(assetsDir));
+        realTarget = realpathSync(full);
+    }
+    catch {
+        return;
+    }
+    if (!insideDir(realAssets, realTarget)) {
+        throw new Error(`asset "${ref}" resolves outside the assets dir (symlink escape)`);
+    }
+};
+/** Rejects symlinks (or any realpath) escaping the project dir; skips when off-disk (fake hosts). */
+const assertInsideProjectDir = (projectDir, full, label) => {
+    let realRoot;
+    let realTarget;
+    try {
+        realRoot = realpathSync(resolve(projectDir));
+        realTarget = realpathSync(full);
+    }
+    catch {
+        return;
+    }
+    if (realTarget !== realRoot && !insideDir(realRoot, realTarget)) {
+        throw new Error(`theme "${label}" resolves outside the project (symlink escape)`);
+    }
+};
+/**
+ * Builds the visual-only input manifest: storyboard + vendored themes +
+ * exact referenced assets + ledger bytes. Project-relative forward-slash
+ * paths, code-unit sorted. Fails closed on missing assets, escapes,
+ * symlinks, duplicate normalized paths and unreadable ledgers.
+ */
+const readThemeRefs = async (host, projectDir) => {
+    const themesDir = join(projectDir, THEMES_DIR);
+    const themeNames = (await host.listDir(themesDir).catch(() => []))
+        .filter((name) => name.endsWith(".json"))
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const themes = [];
+    for (const name of themeNames) {
+        const full = join(themesDir, name);
+        assertInsideProjectDir(projectDir, full, name);
+        const text = await host.readText(full);
+        const rel = toForwardSlash(relative(projectDir, resolve(full)));
+        if (rel === "" || rel.startsWith("../") || isAbsolute(rel)) {
+            throw new Error(`theme "${name}" escapes the project (escape)`);
+        }
+        themes.push({ path: rel, sha256: sha256(text) });
+    }
+    themes.sort(codeUnitSort);
+    return themes;
+};
+const dedupeAssetRefs = (rawRefs) => {
+    const seen = new Map();
+    for (const raw of rawRefs) {
+        const clean = normaliseRef(raw);
+        const first = seen.get(clean);
+        if (first !== undefined && first !== raw) {
+            throw new Error(`asset "${raw}" duplicates normalized path "${clean}" (duplicate)`);
+        }
+        seen.set(clean, raw);
+    }
+    return [...seen.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+};
+const readAssetRefs = async (host, projectDir, assetsDir, cleans) => {
+    const assets = [];
+    for (const clean of cleans) {
+        const full = resolve(assetsDir, clean);
+        const rel = toForwardSlash(relative(projectDir, full));
+        if (rel === "" || rel.startsWith("../") || isAbsolute(rel)) {
+            throw new Error(`asset "${clean}" escapes the project (escape)`);
+        }
+        assertInsideAssetsDir(assetsDir, full, clean);
+        const digest = await host.sha256File(full);
+        if (digest === undefined) {
+            throw new Error(`asset "${clean}" not found under the assets dir`);
+        }
+        assets.push({ path: rel, sha256: digest });
+    }
+    assets.sort(codeUnitSort);
+    return assets;
+};
+const readLedgerSha = async (host, ledgerPath) => {
+    try {
+        return sha256(await host.readText(ledgerPath));
+    }
+    catch (error) {
+        throw new Error(`cannot read asset ledger ${ledgerPath}: ${error.message}`);
+    }
+};
+/** Resolves --audio TimingManifest plus every sibling wav into refs + mix. Fails closed. */
+const readAudioRefs = async (host, projectDir, audioManifestPath) => {
+    let text;
+    try {
+        text = await host.readText(audioManifestPath);
+    }
+    catch (error) {
+        throw new Error(`cannot read --audio manifest ${audioManifestPath}: ${error.message}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`invalid --audio manifest ${audioManifestPath}: ${error.message}`);
+    }
+    const parsed = parseAudioManifest(raw);
+    if (!parsed.ok) {
+        throw new Error(`invalid --audio manifest ${audioManifestPath}: ${parsed.problems.join("; ")}`);
+    }
+    const audioDir = join(dirname(resolve(audioManifestPath)), AUDIO_DIR_NAME);
+    const clips = clipsFromManifest(parsed.manifest, audioDir);
+    if (clips.length === 0) {
+        throw new Error(`--audio manifest ${audioManifestPath} has no scenes; nothing to mix`);
+    }
+    const audio = [];
+    const mixClips = [];
+    for (const clip of clips) {
+        const digest = await host.sha256File(clip.wav);
+        if (digest === undefined) {
+            throw new Error(`audio wav for scene "${clip.id}" not found: ${clip.wav}`);
+        }
+        if (digest === EMPTY_SHA256) {
+            throw new Error(`audio wav for scene "${clip.id}" is silent/empty: ${clip.wav}`);
+        }
+        const rel = toForwardSlash(relative(projectDir, resolve(clip.wav)));
+        if (rel === "" || rel.startsWith("../") || isAbsolute(rel)) {
+            throw new Error(`audio wav for scene "${clip.id}" escapes the project (escape)`);
+        }
+        audio.push({ path: rel, sha256: digest });
+        mixClips.push({ id: clip.id, start: clip.start, wavSha: digest });
+    }
+    audio.sort(codeUnitSort);
+    const manifestRel = toForwardSlash(relative(projectDir, resolve(audioManifestPath)));
+    if (manifestRel === "" || manifestRel.startsWith("../") || isAbsolute(manifestRel)) {
+        throw new Error(`--audio manifest ${audioManifestPath} escapes the project (escape)`);
+    }
+    const audioManifest = { path: manifestRel, sha256: sha256(text) };
+    const mode = clips.length === 1 ? "single" : isContiguous(parsed.manifest.scenes) ? "concat" : "adelay";
+    return { audio, audioManifest, mix: { mode, clips: mixClips } };
+};
+/** Resolves --music bed wav plus volume and license-evidence receipt. Fails closed. */
+const readMusicRefs = async (host, projectDir, musicPath, musicVolume, musicLicensePath) => {
+    const parsedBed = parseMusicBed(musicVolume === undefined ? { wav: musicPath } : { wav: musicPath, volume: musicVolume });
+    if (!parsedBed.ok) {
+        throw new Error(`invalid --music bed: ${parsedBed.hint}`);
+    }
+    const full = resolve(musicPath);
+    const digest = await host.sha256File(full);
+    if (digest === undefined) {
+        throw new Error(`music bed wav not found: ${musicPath}`);
+    }
+    if (digest === EMPTY_SHA256) {
+        throw new Error(`music bed wav is silent/empty: ${musicPath}`);
+    }
+    if (digest.length !== 64) {
+        throw new Error(`music bed wav unreadable: ${musicPath}`);
+    }
+    const rel = toForwardSlash(relative(projectDir, full));
+    if (rel === "" || rel.startsWith("../") || isAbsolute(rel)) {
+        throw new Error(`music bed "${musicPath}" escapes the project (escape)`);
+    }
+    assertInsideProjectDir(projectDir, full, `music bed "${musicPath}"`);
+    let licenseEvidenceSha256 = null;
+    if (musicLicensePath !== undefined) {
+        const licenseFull = resolve(musicLicensePath);
+        const licenseDigest = await host.sha256File(licenseFull);
+        if (licenseDigest === undefined) {
+            throw new Error(`cannot read --music-license ${musicLicensePath}: not found`);
+        }
+        licenseEvidenceSha256 = licenseDigest;
+    }
+    return { path: rel, sha256: digest, volume: parsedBed.bed.volume, licenseEvidenceSha256 };
+};
+export async function buildApprovalInputManifest(host, storyboard, opts = {}) {
+    const projectDir = dirname(resolve(storyboard));
+    const storyboardText = await host.readText(storyboard);
+    const storyboardRel = toForwardSlash(relative(projectDir, resolve(storyboard)));
+    const storyboardRef = { path: storyboardRel, sha256: sha256(storyboardText) };
+    const themes = await readThemeRefs(host, projectDir);
+    const sceneFiles = await authoredSceneFiles(host, storyboard, storyboardText);
+    const scenes = sceneFiles.map(([path, text]) => ({
+        path,
+        sha256: sha256(text),
+    }));
+    let parsed = null;
+    try {
+        parsed = JSON.parse(storyboardText);
+    }
+    catch {
+        parsed = null;
+    }
+    const rawRefs = [];
+    if (parsed !== null)
+        collectAssetRefs(parsed, rawRefs);
+    const cleans = dedupeAssetRefs(rawRefs);
+    const assetsDir = opts.assetsDir === undefined ? undefined : resolve(opts.assetsDir);
+    if (rawRefs.length > 0 && assetsDir === undefined) {
+        throw new Error(`asset "${rawRefs[0] ?? ""}" requested but no assetsDir was given`);
+    }
+    const assets = assetsDir === undefined ? [] : await readAssetRefs(host, projectDir, assetsDir, cleans);
+    const ledgerSha256 = opts.ledgerPath === undefined ? undefined : await readLedgerSha(host, opts.ledgerPath);
+    if (opts.audioManifest === undefined) {
+        if (opts.music !== undefined) {
+            throw new Error(`--music needs --audio: pass the same --audio manifest used for preview`);
+        }
+        return {
+            scope: "visual",
+            storyboard: storyboardRef,
+            themes,
+            assets,
+            ...(ledgerSha256 === undefined ? {} : { ledgerSha256 }),
+            ...(scenes.length === 0 ? {} : { scenes }),
+            audio: [],
+        };
+    }
+    const { audio, audioManifest, mix } = await readAudioRefs(host, projectDir, opts.audioManifest);
+    const music = opts.music === undefined
+        ? undefined
+        : await readMusicRefs(host, projectDir, opts.music, opts.musicVolume, opts.musicLicense);
+    return {
+        scope: "audiovisual",
+        storyboard: storyboardRef,
+        themes,
+        assets,
+        ...(ledgerSha256 === undefined ? {} : { ledgerSha256 }),
+        ...(scenes.length === 0 ? {} : { scenes }),
+        audio,
+        audioManifest,
+        mix,
+        ...(music === undefined ? {} : { music }),
+    };
+}
+/**
+ * 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 function hashApprovalInput(manifest) {
+    const themes = [...manifest.themes].sort(codeUnitSort);
+    const assets = [...manifest.assets].sort(codeUnitSort);
+    const audio = [...(manifest.audio ?? [])].sort(codeUnitSort);
+    const scenes = [...(manifest.scenes ?? [])].sort(codeUnitSort);
+    return sha256(JSON.stringify({
+        scope: manifest.scope,
+        storyboard: { path: manifest.storyboard.path, sha256: manifest.storyboard.sha256 },
+        themes: themes.map((t) => [t.path, t.sha256]),
+        assets: assets.map((a) => [a.path, a.sha256]),
+        ledgerSha256: manifest.ledgerSha256 ?? null,
+        audio: audio.map((a) => [a.path, a.sha256]),
+        ...(scenes.length === 0 ? {} : { scenes: scenes.map((s) => [s.path, s.sha256]) }),
+        audioManifest: manifest.audioManifest === undefined
+            ? null
+            : { path: manifest.audioManifest.path, sha256: manifest.audioManifest.sha256 },
+        mix: manifest.mix === undefined
+            ? null
+            : {
+                mode: manifest.mix.mode,
+                clips: manifest.mix.clips.map((c) => [c.id, c.start, c.wavSha]),
+            },
+        music: manifest.music === undefined
+            ? null
+            : {
+                path: manifest.music.path,
+                sha256: manifest.music.sha256,
+                volume: manifest.music.volume,
+                licenseEvidenceSha256: manifest.music.licenseEvidenceSha256,
+            },
+    }));
+}

package/dist/args.d.ts

@@ -0,0 +1,30 @@
+import type { Io } from "./types.ts";
+export type FlagSpec = Readonly<Record<string, {
+    type: "boolean" | "string";
+    short?: string;
+    multiple?: boolean;
+}>>;
+export type Flags = Readonly<Record<string, string | boolean | string[] | undefined>>;
+export interface Exit {
+    kind: "exit";
+    code: number;
+}
+export interface Parsed {
+    kind: "run";
+    flags: Flags;
+    positionals: string[];
+}
+/** Reports a usage problem on stderr with the one-line usage; always EXIT.USAGE. */
+export declare function usageError(name: string, usage: string, message: string, io: Io): Exit;
+/** Strict flag parsing plus `--help`; unknown flags and missing values exit 2. */
+export declare function parseFlags(name: string, usage: string, args: readonly string[], spec: FlagSpec, io: Io): Parsed | Exit;
+/** A path: exactly one positional argument; `label` names it in the error. */
+export declare function requirePositional(name: string, usage: string, positionals: readonly string[], label: string, io: Io): string | Exit;
+/** A string flag's value, or undefined when absent. */
+export declare function textFlag(flags: Flags, name: string): string | undefined;
+/** Every value of a repeatable string flag (`multiple: true`), in order. */
+export declare function listFlag(flags: Flags, name: string): string[];
+/** The storyboard path: exactly one positional argument. */
+export declare const requireStoryboard: (name: string, usage: string, positionals: readonly string[], io: Io) => string | Exit;
+/** Node's argument errors append long advice; keep only the first sentence. */
+export declare const firstSentence: (message: string) => string;

package/dist/args.js

@@ -0,0 +1,53 @@
+import { parseArgs } from "node:util";
+import { EXIT } from "./exit-codes.js";
+const usageLine = (usage) => usage.split("\n")[0] ?? "";
+/** Reports a usage problem on stderr with the one-line usage; always EXIT.USAGE. */
+export function usageError(name, usage, message, io) {
+    io.stderr(`mk ${name}: ${message}\nusage: ${usageLine(usage)}\n`);
+    return { kind: "exit", code: EXIT.USAGE };
+}
+/** Strict flag parsing plus `--help`; unknown flags and missing values exit 2. */
+export function parseFlags(name, usage, args, spec, io) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: [...args],
+            options: { ...spec, help: { type: "boolean", short: "h" } },
+            allowPositionals: true,
+        });
+        const { help, ...flags } = values;
+        if (!help)
+            return { kind: "run", flags, positionals };
+        io.stdout(usage);
+        return { kind: "exit", code: EXIT.OK };
+    }
+    catch (error) {
+        return usageError(name, usage, firstSentence(error.message), io);
+    }
+}
+/** A path: exactly one positional argument; `label` names it in the error. */
+export function requirePositional(name, usage, positionals, label, io) {
+    const [path, ...extra] = positionals;
+    if (path === undefined)
+        return usageError(name, usage, `missing ${label}`, io);
+    if (extra.length > 0) {
+        return usageError(name, usage, `unexpected argument "${extra[0]}"`, io);
+    }
+    return path;
+}
+/** A string flag's value, or undefined when absent. */
+export function textFlag(flags, name) {
+    const value = flags[name];
+    return typeof value === "string" ? value : undefined;
+}
+/** Every value of a repeatable string flag (`multiple: true`), in order. */
+export function listFlag(flags, name) {
+    const value = flags[name];
+    return Array.isArray(value) ? value : [];
+}
+/** The storyboard path: exactly one positional argument. */
+export const requireStoryboard = (name, usage, positionals, io) => requirePositional(name, usage, positionals, "<storyboard.json>", io);
+/** Node's argument errors append long advice; keep only the first sentence. */
+export const firstSentence = (message) => {
+    const end = message.search(/\.\s/);
+    return end === -1 ? message : message.slice(0, end + 1);
+};

package/dist/assets/command.d.ts

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