@anvpx/motion-cli 0.0.0-stage → 0.1.0

package/dist/scene/command.js

@@ -0,0 +1,110 @@
+import { listFlag, parseFlags, textFlag, usageError } from "../args.js";
+import { editStoryboard } from "../storyboard/edit.js";
+import { sceneLint, sceneNew, scenePromote } from "./author.js";
+import { addScene, moveScene, removeScene } from "./ops.js";
+const USAGE = `mk scene new <id> [--dir <path>] [--force]
+mk scene lint <dir>
+mk scene promote <dir> --as <type>
+mk scene add <storyboard.json> <type> [--id x] [--after id] [--set k=v ...] [--duration s] [--over id] [--offset s]
+mk scene remove <storyboard.json> <id>
+mk scene move <storyboard.json> <id> (--after <id> | --first)
+
+Edit the scene list of a storyboard; the result is validated and written atomically (never written invalid).
+  add     insert a scene of <type> built from its minimal catalog example (see \`mk catalog <type>\`)
+          --id x       scene id (default <type>-<n>)         --after id   insert after that scene (default: at the end)
+          --set k=v    top-level prop; v is JSON when it parses (3, true, ["a","b"]), else text; repeatable
+          --duration s seconds (default: auto from the text)
+          --over id    overlay types only: the base scene it covers (required), --offset s seconds into it (default 0)
+  remove  delete a scene (an overlay still pointing at it makes the result invalid)
+  move    reorder: land after another scene, or first
+Nested prop edits: \`mk patch\`. Prints one line.
+`;
+const FLAGS = {
+    id: { type: "string" },
+    after: { type: "string" },
+    first: { type: "boolean" },
+    set: { type: "string", multiple: true },
+    duration: { type: "string" },
+    over: { type: "string" },
+    offset: { type: "string" },
+};
+const SUBCOMMANDS = ["add", "remove", "move"];
+const isSub = (value) => SUBCOMMANDS.some((sub) => sub === value);
+/** Flags each subcommand accepts; anything else is a usage error rather than silently ignored. */
+const ALLOWED = {
+    add: ["id", "after", "set", "duration", "over", "offset"],
+    remove: [],
+    move: ["after", "first"],
+};
+const seconds = (flags, name) => {
+    const text = textFlag(flags, name);
+    if (text === undefined)
+        return undefined;
+    const value = Number(text);
+    return Number.isFinite(value) && value >= 0 ? value : "bad";
+};
+/** Subcommand, storyboard path, target and flags checked together; an exit code on bad usage. */
+function parseTarget(args, io) {
+    const parsed = parseFlags("scene", USAGE, args, FLAGS, io);
+    if (parsed.kind === "exit")
+        return parsed.code;
+    const [sub, path, target, ...extra] = parsed.positionals;
+    const usage = (message) => usageError("scene", USAGE, message, io).code;
+    if (!isSub(sub))
+        return usage(`use one of: ${SUBCOMMANDS.join("|")}`);
+    const stray = Object.keys(parsed.flags).find((flag) => !ALLOWED[sub].includes(flag));
+    if (stray !== undefined)
+        return usage(`--${stray} does not apply to ${sub}`);
+    if (path === undefined)
+        return usage("missing <storyboard.json>");
+    if (target === undefined)
+        return usage(sub === "add" ? "missing <type>" : "missing <id>");
+    if (extra.length > 0)
+        return usage(`unexpected argument "${extra[0]}"`);
+    return { sub, path, target, flags: parsed.flags };
+}
+function runMove(request, io) {
+    const after = textFlag(request.flags, "after");
+    if ((after === undefined) === (request.flags.first !== true)) {
+        return usageError("scene", USAGE, "move needs exactly one of --after <id> or --first", io).code;
+    }
+    return editStoryboard("scene", request.path, io, (doc) => moveScene(doc, { id: request.target, after }));
+}
+function runAdd(request, io) {
+    const { flags } = request;
+    const duration = seconds(flags, "duration");
+    const offset = seconds(flags, "offset");
+    if (duration === "bad" || offset === "bad" || duration === 0) {
+        return usageError("scene", USAGE, "--duration and --offset need positive seconds", io).code;
+    }
+    return editStoryboard("scene", request.path, io, (doc) => addScene(doc, {
+        type: request.target,
+        id: textFlag(flags, "id"),
+        after: textFlag(flags, "after"),
+        sets: listFlag(flags, "set"),
+        duration,
+        over: textFlag(flags, "over"),
+        offset,
+    }));
+}
+export const sceneCommand = {
+    name: "scene",
+    summary: "add, remove, move, scaffold or lint scenes",
+    async run(args, io) {
+        const head = args[0];
+        if (head === "new")
+            return sceneNew(args.slice(1), io);
+        if (head === "lint")
+            return sceneLint(args.slice(1), io);
+        if (head === "promote")
+            return scenePromote(args.slice(1), io);
+        const request = parseTarget(args, io);
+        if (typeof request === "number")
+            return request;
+        if (request.sub === "move")
+            return runMove(request, io);
+        if (request.sub === "add")
+            return runAdd(request, io);
+        return editStoryboard("scene", request.path, io, (doc) => removeScene(doc, request.target));
+    },
+};

package/dist/scene/ops.d.ts

@@ -0,0 +1,23 @@
+import { type Edit } from "../storyboard/edit.ts";
+export interface AddRequest {
+    type: string;
+    id?: string | undefined;
+    after?: string | undefined;
+    /** `k=v` pairs; v is JSON when it parses (numbers, true, [..]), else a string. */
+    sets: readonly string[];
+    duration?: number | undefined;
+    /** Overlay scenes only. */
+    over?: string | undefined;
+    offset?: number | undefined;
+}
+/** Inserts a scene built from the catalog's minimal example for `type`. */
+export declare function addScene(doc: unknown, request: AddRequest): Edit;
+/** Removes a scene by id; an overlay still pointing at it makes the validator refuse the result. */
+export declare function removeScene(doc: unknown, id: string): Edit;
+export interface MoveRequest {
+    id: string;
+    /** Scene id to land after; `undefined` moves to the start. */
+    after: string | undefined;
+}
+/** Moves a scene to follow another one (or to the start). */
+export declare function moveScene(doc: unknown, request: MoveRequest): Edit;

package/dist/scene/ops.js

@@ -0,0 +1,151 @@
+import { sceneDocs } from "@anvpx/motion-build";
+import { forbiddenKeys } from "@anvpx/motion-schema";
+import { round1 } from "../storyboard/edit.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const sceneList = (doc) => {
+    const scenes = isRecord(doc) ? doc.scenes : undefined;
+    return Array.isArray(scenes) ? scenes : undefined;
+};
+const indexOfId = (scenes, id) => scenes.findIndex((scene) => scene.id === id);
+const knownIds = (scenes) => scenes.map((s) => String(s.id)).join(", ");
+const NO_SCENES = { ok: false, message: "the storyboard has no scenes array" };
+const OVERLAY_SECONDS = 3;
+const jsonOrText = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+};
+/** `k=v` pairs onto the props; keys are top-level prop names (use `mk patch` for nested edits). */
+function applySets(props, sets) {
+    for (const pair of sets) {
+        const cut = pair.indexOf("=");
+        const key = cut > 0 ? pair.slice(0, cut) : "";
+        if (key === "")
+            return `--set "${pair}" needs k=v`;
+        const [problem] = forbiddenKeys({ [key]: 0 }, []);
+        if (problem !== undefined)
+            return `--set ${key}: ${problem.message}`;
+        props[key] = jsonOrText(pair.slice(cut + 1));
+    }
+    return undefined;
+}
+const freeId = (type, scenes) => {
+    const taken = new Set(scenes.map((scene) => scene.id));
+    for (let n = 1;; n++)
+        if (!taken.has(`${type}-${n}`))
+            return `${type}-${n}`;
+};
+/** The entry's timing fields: `duration`, and `layer`/`over`/`offset` for overlays. */
+function timingOf(overlay, request) {
+    const duration = request.duration ?? (overlay ? OVERLAY_SECONDS : undefined);
+    return {
+        ...(duration === undefined ? {} : { duration }),
+        ...(overlay ? { layer: "overlay", over: request.over, offset: request.offset ?? 0 } : {}),
+    };
+}
+/** The scene entry for `type`, or the reason it cannot be built. */
+function buildEntry(scenes, request) {
+    const docs = sceneDocs();
+    const found = docs.find((entry) => entry.type === request.type);
+    if (found === undefined) {
+        const known = docs.map((d) => d.type).join("|");
+        return { ok: false, message: `unknown scene type "${request.type}"; use one of: ${known}` };
+    }
+    const id = request.id ?? freeId(request.type, scenes);
+    if (indexOfId(scenes, id) !== -1)
+        return { ok: false, message: `scene id "${id}" already exists` };
+    const props = structuredClone(found.example);
+    const problem = applySets(props, request.sets);
+    if (problem !== undefined)
+        return { ok: false, message: problem };
+    const overlay = found.layer === "overlay";
+    if (overlay && (request.over === undefined || indexOfId(scenes, request.over) === -1)) {
+        const known = knownIds(scenes);
+        return {
+            ok: false,
+            message: `${request.type} is an overlay: give --over <base scene id> (one of: ${known})`,
+        };
+    }
+    return { ok: true, entry: { id, type: request.type, props, ...timingOf(overlay, request) } };
+}
+/** Index to insert at: after `--after`, else the end; undefined when that scene does not exist. */
+function insertionIndex(scenes, after) {
+    if (after === undefined)
+        return scenes.length;
+    const at = indexOfId(scenes, after);
+    return at === -1 ? undefined : at + 1;
+}
+/** Inserts a scene built from the catalog's minimal example for `type`. */
+export function addScene(doc, request) {
+    const scenes = sceneList(doc);
+    if (scenes === undefined)
+        return NO_SCENES;
+    const built = buildEntry(scenes, request);
+    if (!built.ok)
+        return built;
+    const at = insertionIndex(scenes, request.after);
+    if (at === undefined) {
+        return {
+            ok: false,
+            message: `--after "${request.after}": no such scene (have: ${knownIds(scenes)})`,
+        };
+    }
+    const next = structuredClone(doc);
+    next.scenes.splice(at, 0, built.entry);
+    return {
+        ok: true,
+        value: next,
+        lines: (report) => [
+            `scene add ok | ${built.entry.id} (${request.type}) at ${at + 1}/${next.scenes.length} | total ${round1(report.total ?? 0)}s | ${report.errors.length} errors, ${report.warnings.length} warnings`,
+        ],
+    };
+}
+/** Removes a scene by id; an overlay still pointing at it makes the validator refuse the result. */
+export function removeScene(doc, id) {
+    const scenes = sceneList(doc);
+    if (scenes === undefined)
+        return NO_SCENES;
+    const at = indexOfId(scenes, id);
+    if (at === -1)
+        return { ok: false, message: `no scene "${id}" (have: ${knownIds(scenes)})` };
+    const next = structuredClone(doc);
+    next.scenes.splice(at, 1);
+    return {
+        ok: true,
+        value: next,
+        lines: (report) => [
+            `scene remove ok | ${id} | scenes ${next.scenes.length} | total ${round1(report.total ?? 0)}s | ${report.errors.length} errors, ${report.warnings.length} warnings`,
+        ],
+    };
+}
+/** Moves a scene to follow another one (or to the start). */
+export function moveScene(doc, request) {
+    const scenes = sceneList(doc);
+    if (scenes === undefined)
+        return NO_SCENES;
+    const from = indexOfId(scenes, request.id);
+    if (from === -1)
+        return { ok: false, message: `no scene "${request.id}" (have: ${knownIds(scenes)})` };
+    if (request.after === request.id)
+        return { ok: false, message: "cannot move a scene after itself" };
+    const next = structuredClone(doc);
+    const [moved] = next.scenes.splice(from, 1);
+    const anchor = request.after === undefined ? -1 : indexOfId(next.scenes, request.after);
+    if (request.after !== undefined && anchor === -1) {
+        return {
+            ok: false,
+            message: `--after "${request.after}": no such scene (have: ${knownIds(scenes)})`,
+        };
+    }
+    next.scenes.splice(anchor + 1, 0, moved);
+    return {
+        ok: true,
+        value: next,
+        lines: (report) => [
+            `scene move ok | ${request.id} now at ${anchor + 2}/${next.scenes.length} | total ${round1(report.total ?? 0)}s | ${report.errors.length} errors, ${report.warnings.length} warnings`,
+        ],
+    };
+}

package/dist/state/command.d.ts

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

package/dist/state/command.js

@@ -0,0 +1,128 @@
+import { resolve } from "node:path";
+import { parseFlags, requireStoryboard, textFlag, usageError, } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { deriveState, gatherEvidence } from "./evidence.js";
+const USAGE = `mk state <storyboard.json> [--out <dir>] [--render <dir>] [--assets <dir>] [--ledger <assets.json>] [--audio <manifest>] [--music <bed.wav>] [--music-volume <n>] [--music-license <file>] [--json]
+
+Report the highest project state the artifacts prove; read-only, never writes.
+  --out <dir>       preview pack base (default <storyboard dir>/out)
+  --render <dir>  render output dir (default <storyboard dir>/out/project); one manifest per dir
+  --assets <dir>    the --assets used with \`mk preview\`/\`mk approve\`
+  --ledger <file>   the --ledger used with \`mk preview\`/\`mk approve\`
+  --audio <manifest>  the --audio used with \`mk preview\`/\`mk approve\`
+  --music <bed.wav>   the --music used with \`mk preview\`/\`mk approve\`
+  --music-volume <n>  the --music-volume used with \`mk preview\`/\`mk approve\`
+  --music-license <file>  the --music-license used with \`mk preview\`/\`mk approve\`
+  --json            one compact line {state, next, missing, problems, evidence}
+Exit 0 consistent; 1 an artifact claims more than the evidence; 2 usage, invalid storyboard or unreadable inputs.
+`;
+const FLAGS = {
+    out: { type: "string" },
+    render: { type: "string" },
+    assets: { type: "string" },
+    ledger: { type: "string" },
+    audio: { type: "string" },
+    music: { type: "string" },
+    "music-volume": { type: "string" },
+    "music-license": { type: "string" },
+    json: { type: "boolean" },
+};
+const MAX_PROBLEM_LINES = 3;
+/** The state word, the one missing artifact, then at most three problem lines. */
+function formatText(report) {
+    const lines = [report.state];
+    if (report.next !== null)
+        lines.push(`missing: ${report.next}`);
+    for (const problem of report.problems.slice(0, MAX_PROBLEM_LINES)) {
+        lines.push(`problem: ${problem.code} ${problem.message}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function isExit(value) {
+    return typeof value === "object" && value !== null && value.kind === "exit";
+}
+/** `--music-volume` as a number in (0, 1], or the usage exit. */
+function musicVolumeOf(flags, io) {
+    const raw = textFlag(flags, "music-volume");
+    if (raw === undefined)
+        return {};
+    const volume = Number(raw);
+    if (!Number.isFinite(volume) || volume <= 0 || volume > 1) {
+        return usageError("state", USAGE, "--music-volume must be within (0, 1]", io);
+    }
+    return { volume };
+}
+/** `--music` needs `--audio`; its volume/license need `--music`. */
+function musicDependency(flags, io) {
+    const music = textFlag(flags, "music");
+    if (music === undefined) {
+        return textFlag(flags, "music-volume") === undefined &&
+            textFlag(flags, "music-license") === undefined
+            ? undefined
+            : usageError("state", USAGE, "--music-volume/--music-license need --music", io);
+    }
+    return textFlag(flags, "audio") === undefined
+        ? usageError("state", USAGE, "--music needs --audio", io)
+        : undefined;
+}
+/** The same approval input scope `mk approve` used; without it vendored assets cannot resolve. */
+function approvalOptions(flags, io) {
+    const volume = musicVolumeOf(flags, io);
+    if (isExit(volume))
+        return volume;
+    const dependency = musicDependency(flags, io);
+    if (dependency !== undefined)
+        return dependency;
+    const assets = textFlag(flags, "assets");
+    const ledger = textFlag(flags, "ledger");
+    const audio = textFlag(flags, "audio");
+    const music = textFlag(flags, "music");
+    const license = textFlag(flags, "music-license");
+    const options = {};
+    if (assets !== undefined)
+        options.assetsDir = resolve(assets);
+    if (ledger !== undefined)
+        options.ledgerPath = ledger;
+    if (audio !== undefined)
+        options.audioManifest = audio;
+    if (music !== undefined)
+        options.music = music;
+    if (volume.volume !== undefined)
+        options.musicVolume = volume.volume;
+    if (license !== undefined)
+        options.musicLicense = license;
+    return options;
+}
+/** Unreadable inputs are undecidable (exit 2); a render overclaim is a contradiction (exit 1). */
+function exitFor(report) {
+    if (report.problems.some((problem) => problem.code === "inputs-unreadable"))
+        return EXIT.USAGE;
+    return report.problems.length > 0 ? EXIT.ERROR : EXIT.OK;
+}
+export const stateCommand = {
+    name: "state",
+    summary: "report the highest project state the artifacts prove; flags overclaims",
+    async run(args, io) {
+        const parsed = parseFlags("state", USAGE, args, FLAGS, io);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const storyboard = requireStoryboard("state", USAGE, parsed.positionals, io);
+        if (isExit(storyboard))
+            return storyboard.code;
+        const approval = approvalOptions(parsed.flags, io);
+        if (isExit(approval))
+            return approval.code;
+        const gathered = await gatherEvidence(io, storyboard, {
+            out: textFlag(parsed.flags, "out"),
+            render: textFlag(parsed.flags, "render"),
+            approval,
+        });
+        if (!gathered.ok) {
+            io.stderr(`mk state: ${gathered.message.trimEnd()}\n`);
+            return EXIT.USAGE;
+        }
+        const report = deriveState(gathered.facts);
+        io.stdout(parsed.flags.json === true ? `${JSON.stringify(report)}\n` : formatText(report));
+        return exitFor(report);
+    },
+};

package/dist/state/evidence.d.ts

@@ -0,0 +1,71 @@
+import { type ApprovalState } from "../approval/approval.ts";
+import type { ApprovalBuildOptions } from "../approval/hash.ts";
+import type { Io } from "../types.ts";
+/** The highest state a project has current evidence for. */
+export type ProjectState = "storyboard" | "previewed" | "approved" | "rendered" | "verified";
+/** The next missing artifact, one word. */
+export type NextState = "preview" | "approval" | "render" | "verify";
+export type Presence = "missing" | "stale" | "current";
+export type ApprovalEvidence = ApprovalState["state"];
+export type VerifyEvidence = "PASS" | "not-run" | "unknown";
+export type ProblemCode = "render-output-missing" | "render-output-mismatch" | "render-unapproved" | "verify-claim-unsupported" | "inputs-unreadable";
+export interface Problem {
+    readonly code: ProblemCode;
+    readonly message: string;
+}
+export interface Evidence {
+    readonly storyboard: string;
+    readonly preview: Presence;
+    readonly approval: ApprovalEvidence;
+    readonly render: Presence;
+    readonly verify: VerifyEvidence;
+}
+export interface StateReport {
+    readonly state: ProjectState;
+    readonly next: NextState | null;
+    readonly missing: readonly NextState[];
+    readonly problems: readonly Problem[];
+    readonly evidence: Evidence;
+}
+/** A render manifest we understand: recorded output plus what is actually on disk. */
+export interface RenderFacts {
+    readonly file: string;
+    readonly recordedSha256: string;
+    readonly diskSha256?: string;
+    /** `storyboardSha256` of the build manifest; absent when it is missing or unparsable. */
+    readonly buildStoryboardSha256?: string;
+    readonly verify: string;
+}
+/** Already-read facts; `deriveState` is pure so every combination is testable without files. */
+export interface EvidenceFacts {
+    readonly storyboardSha256: string;
+    /** The hash a build would record: `sha256(JSON.stringify(board))`, so whitespace is not identity. */
+    readonly storyboardCanonicalSha256: string;
+    /** The approval hash the current inputs resolve to; absent when they cannot be read. */
+    readonly currentHash?: string;
+    /** `inputManifestSha256` recorded by the preview pack. */
+    readonly previewSha256?: string;
+    readonly approval: ApprovalEvidence;
+    readonly render?: RenderFacts;
+    /** Short, path-free reason the approval inputs could not be resolved. */
+    readonly unreadable?: string;
+}
+/** Derives the state, the next missing artifact and every overclaim from already-read facts. */
+export declare function deriveState(facts: EvidenceFacts): StateReport;
+export interface StateOptions {
+    /** Preview pack base; default `<storyboard dir>/out`. */
+    readonly out?: string;
+    /** Render output dir; default `<out>/project`. */
+    readonly render?: string;
+    /** The same approval input scope `mk approve` used (`--assets`, `--ledger`, audio, music). */
+    readonly approval?: ApprovalBuildOptions;
+}
+export type GatherResult = {
+    readonly ok: true;
+    readonly facts: EvidenceFacts;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** Reads every artifact once; validation failures and unreadable inputs are exit-2 values. */
+export declare function gatherEvidence(io: Io, storyboard: string, options?: StateOptions): Promise<GatherResult>;