@anvpx/motion-cli 0.0.0-stage → 0.1.1

package/dist/workflow/project.js

@@ -0,0 +1,198 @@
+import { createHash } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { buildProject, clearCache, resolveTimeline, validateStoryboardFull, } from "@anvpx/motion-build";
+import { AssetLedgerSchema, toJsonPointer, } from "@anvpx/motion-schema";
+import { parseFlags, requireStoryboard, textFlag, usageError, } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { checkStoryboard, rootError } from "../storyboard/check.js";
+import { hasCustomScenes, readCustomScenes } from "../storyboard/custom.js";
+import { readJsonFile } from "../storyboard/load.js";
+import { formatFindings } from "../storyboard/report.js";
+import { platformLookup } from "../verify/platform.js";
+/** Per-scene build cache, next to the storyboard. */
+const CACHE_DIR = ".mk-cache";
+export const PROJECT_FLAGS = {
+    out: { type: "string" },
+    assets: { type: "string" },
+    ledger: { type: "string" },
+    incremental: { type: "boolean" },
+    "no-incremental": { type: "boolean" },
+    "clean-cache": { type: "boolean" },
+    "shared-cache-dir": { type: "string" },
+    "no-custom": { type: "boolean" },
+};
+/** Parses `<storyboard.json>` plus the shared build flags and whatever `extra` flags a command adds. */
+export function parseBuildArgs(name, usage, args, extra, io) {
+    const parsed = parseFlags(name, usage, args, { ...PROJECT_FLAGS, ...extra }, io);
+    if (parsed.kind === "exit")
+        return parsed;
+    const storyboard = requireStoryboard(name, usage, parsed.positionals, io);
+    if (typeof storyboard !== "string")
+        return storyboard;
+    if (parsed.flags.incremental === true && parsed.flags["no-incremental"] === true) {
+        return usageError(name, usage, "--incremental and --no-incremental conflict", io);
+    }
+    const assetsDir = textFlag(parsed.flags, "assets");
+    const ledger = textFlag(parsed.flags, "ledger");
+    const sharedCacheDir = textFlag(parsed.flags, "shared-cache-dir");
+    const outDir = resolve(textFlag(parsed.flags, "out") ?? join(dirname(resolve(storyboard)), "out", "project"));
+    return {
+        kind: "run",
+        flags: parsed.flags,
+        request: {
+            storyboard,
+            outDir,
+            ...(assetsDir === undefined ? {} : { assetsDir: resolve(assetsDir) }),
+            ...(ledger === undefined ? {} : { ledger }),
+            ...(sharedCacheDir === undefined ? {} : { sharedCacheDir: resolve(sharedCacheDir) }),
+            incremental: parsed.flags.incremental === true,
+            cleanCache: parsed.flags["clean-cache"] === true,
+            cacheDir: join(dirname(resolve(storyboard)), CACHE_DIR),
+            ...(parsed.flags["no-custom"] === true ? { noCustom: true } : {}),
+        },
+    };
+}
+const fail = (io, findings) => {
+    io.stderr(formatFindings(findings));
+    return { ok: false, code: EXIT.USAGE };
+};
+async function loadLedger(path, io) {
+    const loaded = await readJsonFile(path, io.host);
+    if (!loaded.ok && loaded.kind === "io") {
+        io.stderr(`mk: ${loaded.message}\n`);
+        return { ok: false, code: EXIT.USAGE };
+    }
+    if (!loaded.ok)
+        return fail(io, [rootError(`${path}: ${loaded.message}`)]);
+    const parsed = AssetLedgerSchema.safeParse(loaded.value);
+    if (parsed.success)
+        return { ok: true, value: parsed.data };
+    return fail(io, parsed.error.issues.map((issue) => ({
+        severity: "error",
+        path: toJsonPointer(issue.path),
+        message: `${path}: ${issue.message}`,
+    })));
+}
+async function loadStoryboard(path, io, lint) {
+    const loaded = await readJsonFile(path, io.host);
+    if (!loaded.ok && loaded.kind === "io") {
+        io.stderr(`mk: ${loaded.message}\n`);
+        return { ok: false, code: EXIT.USAGE };
+    }
+    if (!loaded.ok)
+        return fail(io, [rootError(loaded.message)]);
+    const report = checkStoryboard(loaded.value, { lint });
+    if (report.errors.length > 0 || report.total === undefined || report.meta === undefined) {
+        return fail(io, report.errors);
+    }
+    return { ok: true, value: { json: loaded.value, total: report.total, meta: report.meta } };
+}
+/** Project themes: every `themes/<name>.json` next to the storyboard, keyed by file name. */
+async function loadProjectThemes(storyboard, io) {
+    const dir = join(dirname(resolve(storyboard)), "themes");
+    const names = (await io.host.listDir(dir).catch(() => [])).filter((name) => name.endsWith(".json"));
+    const docs = {};
+    for (const name of names.sort()) {
+        const loaded = await readJsonFile(join(dir, name), io.host);
+        if (!loaded.ok && loaded.kind === "io") {
+            io.stderr(`mk: ${loaded.message}\n`);
+            return { ok: false, code: EXIT.USAGE };
+        }
+        if (!loaded.ok)
+            return fail(io, [rootError(`${join(dir, name)}: ${loaded.message}`)]);
+        docs[name.slice(0, -".json".length)] = loaded.value;
+    }
+    return { ok: true, value: docs };
+}
+/** `sha256` of the manifest.json that the build just wrote. */
+async function manifestHash(outDir, io) {
+    const text = await io.host.readText(join(outDir, "manifest.json"));
+    return createHash("sha256").update(text).digest("hex");
+}
+const cacheNote = (cache) => cache ? `, cache: ${cache.hits} hit / ${cache.misses} miss` : "";
+/** Everything a build reads from disk: storyboard, optional ledger, project themes. */
+async function loadInputs(request, io) {
+    const board = await loadStoryboard(request.storyboard, io, request.lint !== false);
+    if (!board.ok)
+        return board;
+    const ledger = request.ledger === undefined ? undefined : await loadLedger(request.ledger, io);
+    if (ledger && !ledger.ok)
+        return ledger;
+    const themes = await loadProjectThemes(request.storyboard, io);
+    if (!themes.ok)
+        return themes;
+    const inputs = { board: board.value, themes: themes.value };
+    return { ok: true, value: ledger ? { ...inputs, ledger: ledger.value } : inputs };
+}
+/** Voice total for the board, or a Failure when the timing override cannot resolve. */
+async function resolveVoiceTotal(boardJson, timing, io) {
+    const valid = validateStoryboardFull(boardJson);
+    if (!valid.ok)
+        return fail(io, valid.errors.map((e) => ({ severity: "error", ...e })));
+    const timeline = resolveTimeline(valid.value, timing);
+    if (!timeline.ok)
+        return fail(io, timeline.errors.map((e) => ({ severity: "error", ...e })));
+    return { total: timeline.value.total };
+}
+/** Validates, builds the HyperFrames project and prints one summary line. */
+export async function prepareProject(request, io) {
+    const inputs = await loadInputs(request, io);
+    if (!inputs.ok)
+        return inputs;
+    const { board, ledger, themes } = inputs.value;
+    // Voice override: resolve the narration total now so the printed line,
+    // the returned total (verify expectation), and the build all agree.
+    // Without timing this block is skipped: byte-identical to today.
+    let total = board.total;
+    if (request.timing !== undefined) {
+        const voice = await resolveVoiceTotal(board.json, request.timing, io);
+        if (!("total" in voice))
+            return voice;
+        total = voice.total;
+    }
+    try {
+        if (request.cleanCache)
+            clearCache(request.cacheDir);
+        if (request.noCustom === true && hasCustomScenes(board.json)) {
+            return fail(io, [
+                {
+                    severity: "error",
+                    path: "",
+                    message: "storyboard uses authored scenes and --no-custom was given",
+                    suggestion: "drop --no-custom, or replace the custom scenes with catalog types",
+                },
+            ]);
+        }
+        const custom = await readCustomScenes(board.json, request.storyboard, io.host);
+        const customErrors = custom.findings.filter((finding) => finding.severity === "error");
+        if (customErrors.length > 0)
+            return fail(io, customErrors);
+        const built = buildProject({
+            storyboard: board.json,
+            outDir: request.outDir,
+            ...(request.lint === false ? { lint: false } : {}),
+            themes,
+            platforms: await platformLookup(io.host),
+            ...(request.incremental ? { cacheDir: request.cacheDir } : {}),
+            ...(request.incremental && request.sharedCacheDir !== undefined
+                ? { sharedCacheDir: request.sharedCacheDir }
+                : {}),
+            ...(request.assetsDir === undefined ? {} : { assetsDir: request.assetsDir }),
+            ...(ledger ? { ledger } : {}),
+            ...(request.timing === undefined ? {} : { timing: request.timing }),
+            ...(Object.keys(custom.sources).length === 0 ? {} : { customScenes: custom.sources }),
+        });
+        if (!built.ok)
+            return fail(io, built.errors.map((e) => ({ severity: "error", ...e })));
+        io.stderr(formatFindings(built.warnings));
+        const hash = await manifestHash(built.outDir, io);
+        const cache = cacheNote(built.cache);
+        io.stdout(`built ${built.files.length} files, ${total}s total, manifest sha256 ${hash}${cache} -> ${built.outDir}\n`);
+        const { meta } = board;
+        return { ok: true, outDir: built.outDir, total, meta };
+    }
+    catch (error) {
+        io.stderr(`mk: build failed: ${error.message}\n`);
+        return { ok: false, code: EXIT.ERROR };
+    }
+}

package/dist/workflow/provenance.d.ts

@@ -0,0 +1,18 @@
+import { type RenderManifestInput } from "@anvpx/motion-build";
+import type { Io } from "../types.ts";
+export declare const RENDER_MANIFEST = "render-manifest.json";
+export interface RenderRecord {
+    kind: RenderManifestInput["kind"];
+    /** The project directory that holds `manifest.json`. */
+    outDir: string;
+    /** Absolute path of the rendered mp4. */
+    file: string;
+    params: RenderManifestInput["params"];
+    verify: RenderManifestInput["verify"];
+}
+/**
+ * Writes `<outDir>/render-manifest.json`: the build manifest hash, render params, output hash,
+ * tool versions and verify status. Machine independent (basename only, no timestamps); the
+ * latest render overwrites it, `output.file` and `kind` say which one it describes.
+ */
+export declare function writeRenderManifest(io: Io, record: RenderRecord): Promise<string>;

package/dist/workflow/provenance.js

@@ -0,0 +1,36 @@
+import { join } from "node:path";
+import { createRenderManifest, renderRenderManifest, } from "@anvpx/motion-build";
+import { readPins } from "../doctor/pins.js";
+import { formatVersion, parseVersion } from "../doctor/version.js";
+export const RENDER_MANIFEST = "render-manifest.json";
+const BUILD_MANIFEST = "manifest.json";
+const UNKNOWN = "unknown";
+const UNAVAILABLE = "unavailable";
+const FFMPEG_VERSION = /version\s+n?(\d+)\.(\d+)(?:\.(\d+))?/;
+async function ffmpegVersion(io) {
+    const result = await io.run("ffmpeg", ["-version"]);
+    const version = result.code === 0 ? parseVersion(result.stdout, FFMPEG_VERSION) : undefined;
+    return version ? formatVersion(version) : UNKNOWN;
+}
+/**
+ * Writes `<outDir>/render-manifest.json`: the build manifest hash, render params, output hash,
+ * tool versions and verify status. Machine independent (basename only, no timestamps); the
+ * latest render overwrites it, `output.file` and `kind` say which one it describes.
+ */
+export async function writeRenderManifest(io, record) {
+    const hyperframes = readPins(await io.host.readRootPackageJson()).hyperframes ?? UNKNOWN;
+    const manifest = createRenderManifest({
+        kind: record.kind,
+        manifestSha256: (await io.host.sha256File(join(record.outDir, BUILD_MANIFEST))) ?? UNAVAILABLE,
+        output: {
+            file: record.file.split(/[\\/]/).pop() ?? record.file,
+            sha256: (await io.host.sha256File(record.file)) ?? UNAVAILABLE,
+        },
+        params: record.params,
+        tools: { ffmpeg: await ffmpegVersion(io), hyperframes, node: io.host.nodeVersion },
+        verify: record.verify,
+    });
+    const path = join(record.outDir, RENDER_MANIFEST);
+    await io.host.writeText(path, renderRenderManifest(manifest));
+    return path;
+}

package/dist/workflow/render.d.ts

@@ -0,0 +1,31 @@
+import type { Command, Io } from "../types.ts";
+/** Delivery containers the command can write (the master is always final.mp4). */
+export declare const DELIVERY_FORMATS: readonly ["mp4", "webm", "mov", "gif", "png-sequence"];
+export type DeliveryFormat = (typeof DELIVERY_FORMATS)[number];
+export declare const RESOLUTIONS: readonly ["1080p", "4k"];
+export type Resolution = (typeof RESOLUTIONS)[number];
+/** `4k` maps to the hyperframes preset that matches the storyboard's aspect. */
+export declare const resolutionPreset: (width: number, height: number) => string;
+/** Output of a non-mp4 format: `final.<ext>`, or the `final.frames` directory for a PNG sequence. */
+export declare const exportFile: (outDir: string, format: Exclude<DeliveryFormat, "mp4">) => string;
+/** ffmpeg argv for the delivery conversion; the master mp4 is the source of truth. */
+export declare const exportArgs: (master: string, format: Exclude<DeliveryFormat, "mp4">, outDir: string) => {
+    args: string[];
+    file: string;
+};
+/** Converts the published master into the requested delivery format. */
+export declare function exportArtifact(io: Io, outDir: string, format: Exclude<DeliveryFormat, "mp4">): Promise<{
+    readonly ok: true;
+    readonly file: string;
+} | {
+    readonly ok: false;
+    readonly code: number;
+}>;
+/**
+ * ADR-0008 D3: the problems to report for a typed failed delivery. A failure
+ * with an empty list is still a failure, never a silent success.
+ */
+export declare const deliveryFailureProblems: (delivery: {
+    problems: readonly string[];
+}) => string[];
+export declare const renderCommand: Command;