@anvpx/motion-cli 0.0.0-stage → 0.1.0

package/dist/catalog/format.js

@@ -0,0 +1,54 @@
+/** Constitution 8.4: the index stays within 3k tokens (estimated as chars / 4). */
+export const INDEX_TOKEN_BUDGET = 3000;
+export const CHARS_PER_TOKEN = 4;
+const required = (doc) => doc.fields.filter((f) => f.required).map((f) => f.name);
+const indexLine = (doc) => `${doc.type} | ${doc.layer} | ${doc.purpose} | ${required(doc).join(",") || "-"}`;
+/** One line per scene: `type | layer | purpose | required fields`. */
+export const formatIndex = (docs) => [
+    "type | layer | purpose | required",
+    ...docs.map(indexLine),
+    "Detail: `mk catalog <type>`. Props are strict; unlisted keys are rejected.",
+    "",
+].join("\n");
+const fieldLine = (field, width) => {
+    const mark = field.required ? "*" : " ";
+    const fallback = "default" in field ? `  = ${JSON.stringify(field.default)}` : "";
+    return `  ${field.name.padEnd(width)}${mark} ${field.type}${fallback}`;
+};
+/** Fields (`*` = required), types, defaults and a minimal example of one scene. */
+export const formatDetail = (doc) => {
+    const width = Math.max(0, ...doc.fields.map((f) => f.name.length));
+    return [
+        `${doc.type} (${doc.layer}): ${doc.purpose}`,
+        ...(doc.fields.length === 0 ? ["  (no props)"] : doc.fields.map((f) => fieldLine(f, width))),
+        ...(doc.fields.some((f) => f.type.includes("icon"))
+            ? ["icons: `mk icon search <query>` | `mk icon list [--tag group]` (names only)"]
+            : []),
+        `props: ${JSON.stringify(doc.example)}`,
+        "",
+    ].join("\n");
+};
+export const indexJson = (docs) => `${JSON.stringify(docs.map((doc) => ({
+    type: doc.type,
+    layer: doc.layer,
+    purpose: doc.purpose,
+    required: required(doc),
+})))}\n`;
+export const detailJson = (doc) => `${JSON.stringify(doc)}\n`;
+/** The committed CATALOG.md: deterministic, generated, index first. */
+export const formatCatalogMarkdown = (docs) => [
+    "# Catalog",
+    "",
+    "Generated by `mk catalog --write` from the scene registry; do not edit. Read the index, then `mk catalog <type>` for one scene. `*` marks a required field.",
+    "",
+    "## Index",
+    "",
+    "```",
+    formatIndex(docs).trimEnd(),
+    "```",
+    "",
+    "## Scenes",
+    "",
+    ...docs.flatMap((doc) => ["```", formatDetail(doc).trimEnd(), "```", ""]),
+].join("\n");
+export const estimateTokens = (text) => Math.ceil(text.length / CHARS_PER_TOKEN);

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+import type { Command, Io } from "./types.ts";
+/** Dispatches argv (without node/script) to a command; resolves to the exit code. */
+export declare function runCli(argv: readonly string[], io: Io, commands?: readonly Command[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,35 @@
+import { COMMANDS } from "./commands.js";
+import { helpSkillFile } from "./doctor/skills.js";
+const SKILLS_NOTE = "(brief -> storyboard -> preview -> render protocol)";
+function helpText(commands) {
+    const width = Math.max(0, ...commands.map((c) => c.name.length));
+    const rows = commands.map((c) => `  ${c.name.padEnd(width)}  ${c.summary}`);
+    return [
+        "mk <command> [flags]",
+        "",
+        "Commands:",
+        ...rows,
+        "",
+        "One command: mk <command> --help",
+        "",
+        `skills: ${helpSkillFile()}  ${SKILLS_NOTE}`,
+        "",
+    ].join("\n");
+}
+function isHelp(arg) {
+    return arg === undefined || arg === "--help" || arg === "-h";
+}
+/** Dispatches argv (without node/script) to a command; resolves to the exit code. */
+export async function runCli(argv, io, commands = COMMANDS) {
+    const [name, ...rest] = argv;
+    if (isHelp(name)) {
+        io.stdout(helpText(commands));
+        return 0;
+    }
+    const command = commands.find((c) => c.name === name);
+    if (!command) {
+        io.stderr(`mk: unknown command "${name}". Run \`mk --help\`.\n`);
+        return 2;
+    }
+    return command.run(rest, io);
+}

package/dist/commands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "./types.ts";
+/** Command registry: a new command is one more entry here. */
+export declare const COMMANDS: readonly Command[];

package/dist/commands.js

@@ -0,0 +1,59 @@
+import { analyzeCommand } from "./analyze/command.js";
+import { approveCommand } from "./approval/command.js";
+import { assetsCommand } from "./assets/command.js";
+import { captionsCommand } from "./captions/command.js";
+import { catalogCommand } from "./catalog/command.js";
+import { compareCommand } from "./compare/command.js";
+import { contactCommand } from "./contact/command.js";
+import { doctorCommand } from "./doctor/command.js";
+import { fitCommand } from "./fit/command.js";
+import { generate3dCommand } from "./generate3d/command.js";
+import { iconCommand } from "./icon/command.js";
+import { optimizeModelCommand } from "./optimize/command.js";
+import { patchCommand } from "./patch/command.js";
+import { pluginCommand } from "./plugin/install.js";
+import { previewCommand } from "./preview/command.js";
+import { publishCommand } from "./publish/command.js";
+import { qcCommand } from "./qc.js";
+import { sceneCommand } from "./scene/command.js";
+import { stateCommand } from "./state/command.js";
+import { templateCommand } from "./template/command.js";
+import { newCommand } from "./template/new.js";
+import { verifyCommand } from "./verify/command.js";
+import { voiceCommand } from "./voice/command.js";
+import { buildCommand } from "./workflow/build.js";
+import { draftCommand } from "./workflow/draft.js";
+import { renderCommand } from "./workflow/render.js";
+import { stillCommand } from "./workflow/still.js";
+import { validateCommand } from "./workflow/validate.js";
+/** Command registry: a new command is one more entry here. */
+export const COMMANDS = [
+    doctorCommand,
+    validateCommand,
+    buildCommand,
+    stillCommand,
+    compareCommand,
+    draftCommand,
+    renderCommand,
+    verifyCommand,
+    stateCommand,
+    analyzeCommand,
+    qcCommand,
+    captionsCommand,
+    catalogCommand,
+    contactCommand,
+    templateCommand,
+    newCommand,
+    previewCommand,
+    publishCommand,
+    approveCommand,
+    patchCommand,
+    sceneCommand,
+    fitCommand,
+    iconCommand,
+    assetsCommand,
+    pluginCommand,
+    voiceCommand,
+    optimizeModelCommand,
+    generate3dCommand,
+];

package/dist/compare/command.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "../types.ts";
+/** Wide enough to judge composition: 2-4 candidates give a 1280-2560 px sheet. */
+export declare const COMPARE_TILE_WIDTH = 640;
+export declare const compareCommand: Command;

package/dist/compare/command.js

@@ -0,0 +1,144 @@
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { parseFlags, textFlag, usageError } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { clearPngs, contactSheet, listPngs } from "../preview/pack.js";
+import { runInProject } from "../tooling/session.js";
+import { PROJECT_FLAGS, prepareProject } from "../workflow/project.js";
+import { STILLS_DIR, stillSnapshotArgs } from "../workflow/still.js";
+const NAME = "compare";
+const USAGE = `mk compare <a.json> <b.json> [<c.json> [<d.json>]] --at <seconds> [--out <dir>] [--assets <dir>] [--ledger <assets.json>] [--json]
+
+Build two to four storyboards and capture one still of each at the same second
+(hyperframes snapshot --at <seconds> --no-end), then tile them into one PNG
+in the order given, so candidates can be compared by eye instead of by text.
+Default <out>: <first storyboard dir>/out/compare. Each storyboard builds into
+<out>/<storyboard name>; the sheet is <out>/compare-<at>.png (one output line).
+--json: one compact line {at, png, items: [{storyboard, still, sha256}]}.
+`;
+const FLAGS = {
+    ...PROJECT_FLAGS,
+    at: { type: "string" },
+    json: { type: "boolean" },
+};
+const MIN_BOARDS = 2;
+const MAX_BOARDS = 4;
+/** One timestamp (no list, unlike `mk still --at`). */
+const ONE_TIME = /^\d+(\.\d+)?$/;
+/** Same per-scene build cache location `parseBuildArgs` uses. */
+const CACHE_DIR = ".mk-cache";
+const LIST_FILE = "compare-stills.txt";
+/** Wide enough to judge composition: 2-4 candidates give a 1280-2560 px sheet. */
+export const COMPARE_TILE_WIDTH = 640;
+/** A copy of `io` whose output is captured, so wrapped builds stay quiet on stdout. */
+const captured = (io) => {
+    const err = [];
+    return { io: { ...io, stdout: () => { }, stderr: (text) => err.push(text) }, err };
+};
+const stemOf = (storyboard) => basename(storyboard, extname(storyboard));
+/** The request `parseBuildArgs` (workflow/project.ts) builds for one storyboard, with compare's out dir. */
+function requestFor(storyboard, outDir, flags) {
+    const assets = textFlag(flags, "assets");
+    const ledger = textFlag(flags, "ledger");
+    const shared = textFlag(flags, "shared-cache-dir");
+    return {
+        storyboard,
+        outDir,
+        ...(assets === undefined ? {} : { assetsDir: resolve(assets) }),
+        ...(ledger === undefined ? {} : { ledger }),
+        ...(shared === undefined ? {} : { sharedCacheDir: resolve(shared) }),
+        incremental: flags.incremental === true,
+        cleanCache: flags["clean-cache"] === true,
+        cacheDir: join(dirname(resolve(storyboard)), CACHE_DIR),
+    };
+}
+function readOptions(args, io) {
+    const parsed = parseFlags(NAME, USAGE, args, FLAGS, io);
+    if (parsed.kind === "exit")
+        return parsed.code;
+    const [first] = parsed.positionals;
+    if (first === undefined || parsed.positionals.length < MIN_BOARDS) {
+        return usageError(NAME, USAGE, "need at least two storyboards to compare", io).code;
+    }
+    if (parsed.positionals.length > MAX_BOARDS) {
+        return usageError(NAME, USAGE, "at most four storyboards", io).code;
+    }
+    const stems = parsed.positionals.map(stemOf);
+    const repeated = stems.find((stem, index) => stems.indexOf(stem) !== index);
+    if (repeated !== undefined) {
+        return usageError(NAME, USAGE, `two storyboards share the name "${repeated}"; each builds into <out>/<name>, so rename one`, io).code;
+    }
+    if (parsed.flags.incremental === true && parsed.flags["no-incremental"] === true) {
+        return usageError(NAME, USAGE, "--incremental and --no-incremental conflict", io).code;
+    }
+    const at = textFlag(parsed.flags, "at");
+    if (at === undefined)
+        return usageError(NAME, USAGE, "missing --at <seconds>", io).code;
+    if (!ONE_TIME.test(at)) {
+        return usageError(NAME, USAGE, "--at needs one timestamp in seconds like 3 or 1.5", io).code;
+    }
+    return {
+        boards: parsed.positionals,
+        at,
+        out: resolve(textFlag(parsed.flags, "out") ?? join(dirname(resolve(first)), "out", "compare")),
+        json: parsed.flags.json === true,
+        flags: parsed.flags,
+    };
+}
+/** Builds one storyboard and captures its single still; a number is the exit code on failure. */
+async function stillOf(io, request, at) {
+    const name = basename(request.storyboard);
+    const build = captured(io);
+    const prepared = await prepareProject(request, build.io);
+    if (!prepared.ok) {
+        io.stderr(`mk ${NAME}: ${name}: build failed\n${build.err.join("")}`);
+        return EXIT.ERROR;
+    }
+    io.stderr(build.err.join(""));
+    const dir = join(prepared.outDir, STILLS_DIR);
+    await clearPngs(io.host, dir);
+    const snap = captured(io);
+    const code = await runInProject(snap.io, prepared.outDir, async (session) => {
+        await session.hf(stillSnapshotArgs(at));
+    });
+    if (code !== EXIT.OK) {
+        io.stderr(`mk ${NAME}: ${name}: snapshot failed\n${snap.err.join("")}`);
+        return EXIT.ERROR;
+    }
+    const stills = await listPngs(io.host, dir);
+    const still = stills[0];
+    if (stills.length !== 1 || still === undefined) {
+        io.stderr(`mk ${NAME}: ${name}: expected one still at ${at}s, hyperframes wrote ${stills.length}\n`);
+        return EXIT.ERROR;
+    }
+    const sha256 = await io.host.sha256File(still);
+    if (sha256 === undefined) {
+        io.stderr(`mk ${NAME}: ${name}: cannot read the still ${still}\n`);
+        return EXIT.ERROR;
+    }
+    return { storyboard: name, still, sha256 };
+}
+export const compareCommand = {
+    name: NAME,
+    summary: "build 2-4 storyboards, one still each at the same --at second, tiled into one PNG",
+    async run(args, io) {
+        const options = readOptions(args, io);
+        if (typeof options === "number")
+            return options;
+        const items = [];
+        for (const storyboard of options.boards) {
+            const outDir = join(options.out, stemOf(storyboard));
+            const item = await stillOf(io, requestFor(storyboard, outDir, options.flags), options.at);
+            if (typeof item === "number")
+                return item;
+            items.push(item);
+        }
+        const png = join(options.out, `compare-${options.at}.png`);
+        const tiled = await contactSheet(io, items.map((item) => item.still), join(options.out, LIST_FILE), png, COMPARE_TILE_WIDTH);
+        if (tiled !== EXIT.OK) {
+            io.stderr(`mk ${NAME}: tiling the stills failed\n`);
+            return EXIT.ERROR;
+        }
+        io.stdout(options.json ? `${JSON.stringify({ at: Number(options.at), png, items })}\n` : `${png}\n`);
+        return EXIT.OK;
+    },
+};

package/dist/contact/argv.d.ts

@@ -0,0 +1,24 @@
+export declare const DEFAULT_COLS = 4;
+export declare const DEFAULT_COUNT = 12;
+export declare const MAX_COUNT = 64;
+/** Width of one tile in px; height follows the aspect ratio (even). */
+export declare const TILE_WIDTH = 320;
+export interface ContactPlan {
+    file: string;
+    out: string;
+    /** Seconds, > 0. */
+    duration: number;
+    count: number;
+    cols: number;
+}
+export declare const rowsFor: (count: number, cols: number) => number;
+/**
+ * ffmpeg argv (no shell): `fps=count/duration` keeps frame i at time i*duration/count, so the
+ * frames are evenly spaced; then scale and tile them into one image.
+ */
+export declare function contactArgs(plan: ContactPlan): string[];
+/**
+ * ffmpeg argv (no shell) tiling the images named by an ffconcat list (`file '<path>'` + `duration 1`
+ * per image) into one contact sheet; same tile layout as `contactArgs`, at `width` px per tile.
+ */
+export declare function contactImagesArgs(list: string, out: string, count: number, cols: number, width?: number): string[];

package/dist/contact/argv.js

@@ -0,0 +1,42 @@
+export const DEFAULT_COLS = 4;
+export const DEFAULT_COUNT = 12;
+export const MAX_COUNT = 64;
+/** Width of one tile in px; height follows the aspect ratio (even). */
+export const TILE_WIDTH = 320;
+export const rowsFor = (count, cols) => Math.ceil(count / cols);
+/**
+ * ffmpeg argv (no shell): `fps=count/duration` keeps frame i at time i*duration/count, so the
+ * frames are evenly spaced; then scale and tile them into one image.
+ */
+export function contactArgs(plan) {
+    const { file, out, duration, count, cols } = plan;
+    const filter = [
+        `fps=${count}/${duration.toFixed(3)}`,
+        `scale=${TILE_WIDTH}:-2:flags=lanczos`,
+        `tile=${cols}x${rowsFor(count, cols)}`,
+    ].join(",");
+    return ["-y", "-v", "error", "-i", file, "-vf", filter, "-frames:v", "1", out];
+}
+/**
+ * ffmpeg argv (no shell) tiling the images named by an ffconcat list (`file '<path>'` + `duration 1`
+ * per image) into one contact sheet; same tile layout as `contactArgs`, at `width` px per tile.
+ */
+export function contactImagesArgs(list, out, count, cols, width = TILE_WIDTH) {
+    const filter = [`scale=${width}:-2:flags=lanczos`, `tile=${cols}x${rowsFor(count, cols)}`];
+    return [
+        "-y",
+        "-v",
+        "error",
+        "-f",
+        "concat",
+        "-safe",
+        "0",
+        "-i",
+        list,
+        "-vf",
+        filter.join(","),
+        "-frames:v",
+        "1",
+        out,
+    ];
+}

package/dist/contact/command.d.ts

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

package/dist/contact/command.js

@@ -0,0 +1,79 @@
+import { basename, dirname, join } from "node:path";
+import { parseFlags, requirePositional, textFlag, usageError } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { probeMedia } from "../verify/probe.js";
+import { contactArgs, DEFAULT_COLS, DEFAULT_COUNT, MAX_COUNT, rowsFor } from "./argv.js";
+const USAGE = `mk contact <file.mp4> [--cols N] [--count N] [--out file.png]
+
+Tile evenly spaced frames of a video into one PNG contact sheet (zero tokens: look at the image).
+  --cols N    tiles per row, 1-${MAX_COUNT} (default ${DEFAULT_COLS})
+  --count N   frames to sample, 1-${MAX_COUNT} (default ${DEFAULT_COUNT})
+  --out f     output PNG (default <file>-contact.png beside the video)
+`;
+const FLAGS = {
+    cols: { type: "string" },
+    count: { type: "string" },
+    out: { type: "string" },
+};
+const RENDER_TIMEOUT_MS = 120_000;
+const intFlag = (flags, name, fallback) => {
+    const raw = textFlag(flags, name);
+    if (raw === undefined)
+        return fallback;
+    const value = Number(raw);
+    return /^\d+$/.test(raw) && value >= 1 && value <= MAX_COUNT ? value : undefined;
+};
+const defaultOut = (file) => join(dirname(file), `${basename(file).replace(/\.[^.]+$/, "")}-contact.png`);
+/** Duration in seconds from an ffprobe JSON document, or undefined. */
+const durationOf = (probe) => {
+    const raw = probe.format?.duration;
+    const seconds = Number(raw);
+    return Number.isFinite(seconds) && seconds > 0 ? seconds : undefined;
+};
+async function sheet(io, file, out, count, cols) {
+    const probed = await probeMedia(io, file);
+    if (!probed.ok && probed.kind === "missing-tool") {
+        io.stderr("mk: ffprobe not found; install ffmpeg and put it on PATH\n");
+        return EXIT.MISSING_TOOL;
+    }
+    const duration = probed.ok ? durationOf(probed.probe) : undefined;
+    if (duration === undefined) {
+        io.stderr(`mk contact: cannot read a duration from ${file}\n`);
+        return EXIT.ERROR;
+    }
+    const args = contactArgs({ file, out, duration, count, cols });
+    const result = await io.run("ffmpeg", args, { timeoutMs: RENDER_TIMEOUT_MS });
+    if (result.code === EXIT.MISSING_TOOL) {
+        io.stderr("mk: ffmpeg not found; install ffmpeg and put it on PATH\n");
+        return EXIT.MISSING_TOOL;
+    }
+    if (result.code !== 0) {
+        io.stderr(`mk contact: ffmpeg failed: ${result.stderr.trim().split(/\r?\n/).pop()}\n`);
+        return EXIT.ERROR;
+    }
+    io.stdout(`${out} ${cols}x${rowsFor(count, cols)} tiles, ${count} frames\n`);
+    return EXIT.OK;
+}
+export const contactCommand = {
+    name: "contact",
+    summary: "tile evenly spaced frames of an mp4 into one PNG contact sheet",
+    async run(args, io) {
+        const parsed = parseFlags("contact", USAGE, args, FLAGS, io);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const file = requirePositional("contact", USAGE, parsed.positionals, "<file.mp4>", io);
+        if (typeof file !== "string")
+            return file.code;
+        const cols = intFlag(parsed.flags, "cols", DEFAULT_COLS);
+        const count = intFlag(parsed.flags, "count", DEFAULT_COUNT);
+        if (cols === undefined || count === undefined) {
+            return usageError("contact", USAGE, `--cols and --count must be integers 1-${MAX_COUNT}`, io)
+                .code;
+        }
+        if (!(await io.host.exists(file))) {
+            io.stderr(`mk contact: cannot read ${file}; check the path.\n`);
+            return EXIT.USAGE;
+        }
+        return sheet(io, file, textFlag(parsed.flags, "out") ?? defaultOut(file), count, cols);
+    },
+};

package/dist/doctor/checks.d.ts

@@ -0,0 +1,25 @@
+import type { Check } from "./types.ts";
+/** DL-01b voice bar: Kokoro is the local primary; failures are manual-hint-only. */
+export declare const VOICE_LOCAL_PRIMARY = "Kokoro local primary";
+export declare const VOICE_WAV_FALLBACK = "pre-rendered WAV fallback in pack";
+export declare const VOICE_MANUAL_SETUP = "manual setup only; no auto-install";
+export declare const VOICE_NO_PAID_BACKEND = "no paid backend";
+export declare const VOICE_ALIGNER = "aligner";
+export declare const checkNode: Check;
+export declare const checkPnpm: Check;
+export declare const checkFfmpeg: Check;
+export declare const checkFfprobe: Check;
+export declare const checkHyperframes: Check;
+export declare const checkChrome: Check;
+export declare const checkGpu: Check;
+export declare const checkPython: Check;
+export declare const checkPythonVenv: Check;
+export declare const checkEspeak: Check;
+export declare const checkKokoro: Check;
+export declare const checkFasterWhisper: Check;
+export declare const checkFonts: Check;
+export declare const checkIcons: Check;
+export declare const checkTemplates: Check;
+export declare const checkBin: Check;
+export declare const checkCatalog: Check;
+export declare const CHECKS: readonly Check[];