@anvpx/motion-cli 0.0.0-stage → 0.1.0

package/dist/patch/apply.js

@@ -0,0 +1,186 @@
+import { canonicalJson, forbiddenKeys } from "@anvpx/motion-schema";
+const OPS = ["add", "replace", "remove", "move", "test"];
+const KEYS = {
+    add: ["op", "path", "value"],
+    replace: ["op", "path", "value"],
+    test: ["op", "path", "value"],
+    remove: ["op", "path"],
+    move: ["op", "path", "from"],
+};
+const INDEX = /^(0|[1-9]\d*)$/;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const pointerProblem = (field, pointer) => {
+    if (typeof pointer !== "string")
+        return `${field} must be a string`;
+    if (pointer === "")
+        return `${field} must not be empty (the document root cannot be patched)`;
+    return pointer.startsWith("/") ? undefined : `${field} must start with "/"`;
+};
+const keysProblem = (raw, op) => {
+    const unknown = Object.keys(raw).find((key) => !KEYS[op].includes(key));
+    return unknown === undefined ? undefined : `unknown key "${unknown}" for ${op}`;
+};
+const pointersProblem = (raw, op) => {
+    if (op === "move" && typeof raw.from !== "string")
+        return "move needs from";
+    const from = op === "move" ? pointerProblem("from", raw.from) : undefined;
+    return from ?? pointerProblem("path", raw.path);
+};
+const opProblem = (raw) => {
+    if (!isRecord(raw))
+        return "must be an object";
+    const known = OPS.find((op) => op === raw.op);
+    if (known === undefined)
+        return `unsupported op ${JSON.stringify(raw.op)}; use ${OPS.join("|")}`;
+    const needsValue = KEYS[known].includes("value") && !Object.hasOwn(raw, "value");
+    return (keysProblem(raw, known) ??
+        pointersProblem(raw, known) ??
+        (needsValue ? `${known} needs a value` : undefined));
+};
+/** Checks the shape of an ops document; every message names the op index. */
+export function parseOps(input) {
+    if (!Array.isArray(input))
+        return { ok: false, message: "ops must be a JSON array of operations" };
+    if (input.length === 0)
+        return { ok: false, message: "ops needs at least one operation" };
+    for (const [index, raw] of input.entries()) {
+        const problem = opProblem(raw);
+        if (problem !== undefined)
+            return { ok: false, message: `op ${index}: ${problem}` };
+    }
+    return { ok: true, ops: input };
+}
+class PatchError extends Error {
+}
+const fail = (message) => {
+    throw new PatchError(message);
+};
+const tokensOf = (pointer) => pointer
+    .slice(1)
+    .split("/")
+    .map((token) => token.replaceAll("~1", "/").replaceAll("~0", "~"));
+const pointerOf = (tokens) => tokens.map((token) => `/${token.replaceAll("~", "~0").replaceAll("/", "~1")}`).join("");
+/** Prototype-polluting and execution-shaped keys are refused in every path segment. */
+const checkSegments = (tokens) => {
+    for (const token of tokens) {
+        const [problem] = forbiddenKeys({ [token]: 0 }, []);
+        if (problem !== undefined)
+            fail(`path segment "${token}": ${problem.message}`);
+    }
+};
+const isContainer = (value) => typeof value === "object" && value !== null;
+const hasChild = (container, token) => Array.isArray(container)
+    ? INDEX.test(token) && Number(token) < container.length
+    : Object.hasOwn(container, token);
+const childOf = (container, token) => Array.isArray(container) ? container[Number(token)] : container[token];
+/** The container holding the last token; fails on the first missing prefix. */
+function parentOf(root, tokens) {
+    let node = root;
+    for (const [depth, token] of tokens.slice(0, -1).entries()) {
+        const prefix = pointerOf(tokens.slice(0, depth + 1));
+        if (!isContainer(node) || !hasChild(node, token))
+            return fail(`parent "${prefix}" does not exist`);
+        node = childOf(node, token);
+        if (!isContainer(node))
+            return fail(`parent "${prefix}" is not an object or array`);
+    }
+    return isContainer(node) ? node : fail("document root is not an object or array");
+}
+const existing = (parent, tokens, pointer) => {
+    const last = tokens.at(-1) ?? "";
+    if (!hasChild(parent, last))
+        fail(`target "${pointer}" does not exist`);
+    return last;
+};
+function insert(parent, token, value) {
+    if (!Array.isArray(parent)) {
+        parent[token] = value;
+        return;
+    }
+    if (token === "-") {
+        parent.push(value);
+        return;
+    }
+    if (!INDEX.test(token))
+        fail(`"${token}" is not an array index`);
+    if (Number(token) > parent.length)
+        fail(`index ${token} is out of range (length ${parent.length})`);
+    parent.splice(Number(token), 0, value);
+}
+function drop(parent, token) {
+    if (Array.isArray(parent))
+        parent.splice(Number(token), 1);
+    else
+        delete parent[token];
+}
+function overwrite(parent, token, value) {
+    if (Array.isArray(parent))
+        parent[Number(token)] = value;
+    else
+        parent[token] = value;
+}
+const sameValue = (a, b) => canonicalJson(a) === canonicalJson(b);
+function valueProblem(value) {
+    const [problem] = forbiddenKeys(value, []);
+    if (problem !== undefined) {
+        fail(`value ${pointerOf(problem.path.map(String)) || "/"}: ${problem.message}`);
+    }
+}
+function applyMove(root, op, changed) {
+    const from = tokensOf(op.from);
+    const tokens = tokensOf(op.path);
+    checkSegments(from);
+    checkSegments(tokens);
+    if (op.path === op.from)
+        return;
+    if (op.path.startsWith(`${op.from}/`))
+        fail("cannot move a value into its own child");
+    const source = parentOf(root, from);
+    const sourceToken = existing(source, from, op.from);
+    const moved = childOf(source, sourceToken);
+    drop(source, sourceToken);
+    insert(parentOf(root, tokens), tokens.at(-1) ?? "", moved);
+    changed.push(op.from, op.path);
+}
+function applyAt(root, op, changed) {
+    const tokens = tokensOf(op.path);
+    checkSegments(tokens);
+    const parent = parentOf(root, tokens);
+    if (op.op === "remove") {
+        drop(parent, existing(parent, tokens, op.path));
+        changed.push(op.path);
+        return;
+    }
+    valueProblem(op.value);
+    if (op.op === "add") {
+        insert(parent, tokens.at(-1) ?? "", op.value);
+        changed.push(op.path);
+    }
+    else if (op.op === "replace") {
+        overwrite(parent, existing(parent, tokens, op.path), op.value);
+        changed.push(op.path);
+    }
+    else if (!sameValue(childOf(parent, existing(parent, tokens, op.path)), op.value)) {
+        fail(`test failed at "${op.path}": value differs`);
+    }
+}
+const applyOne = (root, op, changed) => op.op === "move" ? applyMove(root, op, changed) : applyAt(root, op, changed);
+/**
+ * Applies ops in order to a copy of `doc`; the input is never mutated. Stops at the first op that
+ * cannot apply and names its index. Pure: validation of the result is the caller's job.
+ */
+export function applyPatch(doc, ops) {
+    const root = structuredClone(doc);
+    const changed = [];
+    for (const [index, op] of ops.entries()) {
+        try {
+            applyOne(root, op, changed);
+        }
+        catch (error) {
+            if (error instanceof PatchError)
+                return { ok: false, index, message: error.message };
+            throw error;
+        }
+    }
+    return { ok: true, value: root, changed };
+}

package/dist/patch/command.d.ts

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

package/dist/patch/command.js

@@ -0,0 +1,92 @@
+import { listFlag, parseFlags, requireStoryboard, textFlag, usageError } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { editStoryboard, statusLine } from "../storyboard/edit.js";
+import { readJsonFile } from "../storyboard/load.js";
+import { formatFinding } from "../storyboard/report.js";
+import { applyPatch, parseOps } from "./apply.js";
+const USAGE = `mk patch <storyboard.json> [--ops file.json] [--op <json> ...]
+
+Apply an RFC 6902 JSON Patch (subset: add, replace, remove, move, test) to a storyboard, validate the result
+with the full validator and write it atomically. An invalid result is never written; the pointer errors are printed.
+  --ops f   JSON array of operations: [{"op":"replace","path":"/scenes/0/props/title","value":"New"}]
+  --op j    one operation as JSON (repeatable; applied after --ops)
+Paths follow RFC 6902: "-" appends to an array, ~0 and ~1 escape ~ and /. A path into a missing parent is an error.
+__proto__, constructor, prototype and command-shaped keys are refused. Any edit changes the approval hash.
+Prints <= 3 lines: changed paths; scene count, total seconds, errors and warnings.
+`;
+const FLAGS = { ops: { type: "string" }, op: { type: "string", multiple: true } };
+const MAX_PATHS = 4;
+async function gatherOps(opsFile, inline, io) {
+    const raw = [];
+    if (opsFile !== undefined) {
+        const loaded = await readJsonFile(opsFile, io.host);
+        if (!loaded.ok) {
+            io.stderr(`mk patch: ${loaded.message}\n`);
+            return EXIT.USAGE;
+        }
+        if (!Array.isArray(loaded.value)) {
+            io.stderr(`mk patch: ${opsFile} must hold a JSON array of operations\n`);
+            return EXIT.USAGE;
+        }
+        raw.push(...loaded.value);
+    }
+    for (const text of inline) {
+        try {
+            raw.push(JSON.parse(text));
+        }
+        catch {
+            io.stderr(`mk patch: --op: invalid JSON ${text.slice(0, 40)}\n`);
+            return EXIT.USAGE;
+        }
+    }
+    const parsed = parseOps(raw);
+    if (parsed.ok)
+        return parsed.ops;
+    io.stderr(`mk patch: ${parsed.message}\n`);
+    return EXIT.USAGE;
+}
+const changedLine = (ops, changed) => {
+    const unique = [...new Set(changed)];
+    const shown = unique.slice(0, MAX_PATHS).join(", ");
+    const more = unique.length > MAX_PATHS ? ` (+${unique.length - MAX_PATHS} more)` : "";
+    const label = `${ops} op${ops === 1 ? "" : "s"}`;
+    return `patch ok | ${label} | changed ${shown || "nothing"}${more}`;
+};
+export const patchCommand = {
+    name: "patch",
+    summary: "apply a JSON Patch to a storyboard; validated, atomic, never writes invalid",
+    async run(args, io) {
+        const parsed = parseFlags("patch", USAGE, args, FLAGS, io);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const path = requireStoryboard("patch", USAGE, parsed.positionals, io);
+        if (typeof path !== "string")
+            return path.code;
+        const inline = listFlag(parsed.flags, "op");
+        const opsFile = textFlag(parsed.flags, "ops");
+        if (opsFile === undefined && inline.length === 0) {
+            return usageError("patch", USAGE, "give --ops <file> or --op <json>", io).code;
+        }
+        const ops = await gatherOps(opsFile, inline, io);
+        if (typeof ops === "number")
+            return ops;
+        return editStoryboard("patch", path, io, (doc) => {
+            const result = applyPatch(doc, ops);
+            if (!result.ok) {
+                const failed = ops[result.index];
+                const where = failed === undefined ? "" : ` (${failed.op} ${failed.path})`;
+                return { ok: false, message: `op ${result.index}${where}: ${result.message}` };
+            }
+            const scenes = result.value.scenes?.length ?? 0;
+            return {
+                ok: true,
+                value: result.value,
+                lines: (report) => [
+                    changedLine(ops.length, result.changed),
+                    statusLine(report, scenes),
+                    ...report.warnings.slice(0, 1).map(formatFinding),
+                ],
+            };
+        });
+    },
+};

package/dist/plugin/install.d.ts

@@ -0,0 +1,40 @@
+import type { Command } from "../types.ts";
+/** Pinned publishable core; every command wrapper invokes exactly this, never an unpinned npx.
+ *
+ * Version strategy (MK-080): the pin tracks `@anvpx/motion` manifest
+ * `version` exactly (enforced by `plugin.test.ts` "matches @anvpx/motion
+ * version", which also pins `.claude-plugin/plugin.json`). `0.0.0` is the
+ * pre-publish placeholder: an isolated `npm install` of the packed tarball
+ * rewrites internal `workspace:*` to `0.0.0`, which is private/unpublished,
+ * so `npx -y @anvpx/motion@0.0.0` 404s in isolation (qualify-pack exits 2
+ * BLOCKED with `unpublishedInternals`). Do NOT unpin or float the range to
+ * work around it. Publish path is choiceA (publish internal @anvpx/motion-*
+ * at real versions) or choiceB (bundle into one tarball); either lands with
+ * a version bump of core manifest + this pin + plugin.json together.
+ */
+export declare const PINNED_CORE_VERSION = "0.1.0";
+export declare const PINNED_NPX = "npx -y @anvpx/motion@0.1.0";
+/** Skill file whose sha256 must survive `plugin install` byte for byte. */
+export declare const PLUGIN_SKILL: string;
+export interface PluginEnv {
+    sourceDir: string;
+}
+export declare const defaultPluginEnv: () => PluginEnv;
+/** Resolves a package id (e.g. `@anvpx/motion/package.json`) to a file path. */
+export type CoreResolver = (id: string) => string;
+/** Path existence probe; injectable so tests can model an install layout. */
+export type PathExists = (path: string) => boolean;
+/** The repo checkout copy (`<repo>/plugins/motion-kit`), used for development runs. */
+export declare const repoPluginDir: () => string;
+/**
+ * Resolve the bundled plugin dir, in order: (a) `@anvpx/motion/package.json`
+ * -> `<core>/plugins/motion-kit` (the installed layout), (b) the repo checkout
+ * `<repo>/plugins/motion-kit` for development. Never returns a path that does
+ * not exist: when neither candidate is present it throws naming
+ * `@anvpx/motion` and every attempted path. An injected resolver models a
+ * layout without touching the filesystem; pass `exists` to force the probe.
+ */
+export declare const resolvePluginSourceDir: (resolveCorePkg?: CoreResolver, exists?: PathExists) => string;
+/** `mk plugin install`; `env` is injectable so tests use a fake source tree. */
+export declare const makePluginCommand: (env?: () => PluginEnv) => Command;
+export declare const pluginCommand: Command;

package/dist/plugin/install.js

@@ -0,0 +1,170 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseFlags, textFlag, usageError } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+/** Pinned publishable core; every command wrapper invokes exactly this, never an unpinned npx.
+ *
+ * Version strategy (MK-080): the pin tracks `@anvpx/motion` manifest
+ * `version` exactly (enforced by `plugin.test.ts` "matches @anvpx/motion
+ * version", which also pins `.claude-plugin/plugin.json`). `0.0.0` is the
+ * pre-publish placeholder: an isolated `npm install` of the packed tarball
+ * rewrites internal `workspace:*` to `0.0.0`, which is private/unpublished,
+ * so `npx -y @anvpx/motion@0.0.0` 404s in isolation (qualify-pack exits 2
+ * BLOCKED with `unpublishedInternals`). Do NOT unpin or float the range to
+ * work around it. Publish path is choiceA (publish internal @anvpx/motion-*
+ * at real versions) or choiceB (bundle into one tarball); either lands with
+ * a version bump of core manifest + this pin + plugin.json together.
+ */
+export const PINNED_CORE_VERSION = "0.1.0";
+export const PINNED_NPX = `npx -y @anvpx/motion@${PINNED_CORE_VERSION}`;
+/** Skill file whose sha256 must survive `plugin install` byte for byte. */
+export const PLUGIN_SKILL = join("skills", "motion-kit", "SKILL.md");
+const USAGE = `mk plugin install [--out <dir>]
+
+Copies the bundled Claude Code plugin (plugins/motion-kit) to <dir> (default motion-kit-plugin).
+Verifies skills/motion-kit/SKILL.md copied byte for byte (sha256 match).
+`;
+const FLAGS = { out: { type: "string" } };
+export const defaultPluginEnv = () => ({
+    sourceDir: resolvePluginSourceDir(),
+});
+const defaultResolve = (id) => createRequire(import.meta.url).resolve(id);
+/** `plugins/motion-kit` inside a resolved `@anvpx/motion` package manifest path. */
+const pluginDirIn = (corePkgPath) => join(dirname(corePkgPath), "plugins", "motion-kit");
+/** The repo checkout copy (`<repo>/plugins/motion-kit`), used for development runs. */
+export const repoPluginDir = () => fileURLToPath(new URL("../../../../plugins/motion-kit", import.meta.url));
+const MISSING_SOURCE = "cannot find the bundled plugin; install @anvpx/motion (it ships plugins/motion-kit)";
+/**
+ * Resolve the bundled plugin dir, in order: (a) `@anvpx/motion/package.json`
+ * -> `<core>/plugins/motion-kit` (the installed layout), (b) the repo checkout
+ * `<repo>/plugins/motion-kit` for development. Never returns a path that does
+ * not exist: when neither candidate is present it throws naming
+ * `@anvpx/motion` and every attempted path. An injected resolver models a
+ * layout without touching the filesystem; pass `exists` to force the probe.
+ */
+export const resolvePluginSourceDir = (resolveCorePkg, exists) => {
+    const probe = exists ?? (resolveCorePkg === undefined ? existsSync : () => true);
+    const searched = [];
+    try {
+        const resolve = resolveCorePkg ?? defaultResolve;
+        const installed = pluginDirIn(resolve("@anvpx/motion/package.json"));
+        searched.push(installed);
+        if (probe(installed))
+            return installed;
+    }
+    catch {
+        // Not installed, or an older exports map hides ./package.json.
+    }
+    const repo = repoPluginDir();
+    searched.push(repo);
+    if (probe(repo))
+        return repo;
+    throw new Error(`${MISSING_SOURCE}; searched: ${searched.join(", ")}`);
+};
+function assertSafeEntry(entry) {
+    if (entry === "" || entry.includes("/") || entry.includes("\\") || entry.includes("..")) {
+        throw new Error(`unsafe plugin entry: ${entry}`);
+    }
+}
+async function copyTree(host, from, to) {
+    const entries = await host.listDir(from);
+    let count = 0;
+    for (const entry of entries) {
+        assertSafeEntry(entry);
+        const src = join(from, entry);
+        const dest = join(to, entry);
+        count += (await isDir(host, src))
+            ? await copyTree(host, src, dest)
+            : await copyOne(host, src, dest);
+    }
+    return count;
+}
+async function isDir(host, path) {
+    try {
+        await host.listDir(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function copyOne(host, from, to) {
+    await host.copyFile(from, to);
+    return 1;
+}
+async function readSource(host, sourceDir) {
+    try {
+        await host.listDir(sourceDir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function skillMatches(host, sourceDir, dest) {
+    const before = await host.sha256File(join(sourceDir, PLUGIN_SKILL));
+    const after = await host.sha256File(join(dest, PLUGIN_SKILL));
+    return before !== undefined && before === after;
+}
+function parseInstall(args, io) {
+    const bad = (message) => usageError("plugin", USAGE, message, io).code;
+    const parsed = parseFlags("plugin", USAGE, args, FLAGS, io);
+    if (parsed.kind === "exit")
+        return parsed.code;
+    const [sub, destPos, ...extra] = parsed.positionals;
+    if (sub !== "install")
+        return bad("use one of: install");
+    if (extra.length > 0)
+        return bad(`unexpected argument "${extra[0]}"`);
+    const outFlag = textFlag(parsed.flags, "out");
+    if (outFlag !== undefined && destPos !== undefined)
+        return bad("use --out or <dir>, not both");
+    const dest = outFlag ?? destPos ?? "motion-kit-plugin";
+    if (dest === "")
+        return bad("--out needs a directory");
+    return { dest };
+}
+/** `mk plugin install`; `env` is injectable so tests use a fake source tree. */
+export const makePluginCommand = (env = defaultPluginEnv) => ({
+    name: "plugin",
+    summary: "install the Claude Code plugin (copies plugins/motion-kit)",
+    async run(args, io) {
+        const request = parseInstall(args, io);
+        if (typeof request === "number")
+            return request;
+        let sourceDir;
+        try {
+            sourceDir = env().sourceDir;
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            io.stderr(`mk plugin: ${detail}\n`);
+            return EXIT.ERROR;
+        }
+        return installSource(io, sourceDir, request.dest);
+    },
+});
+async function installSource(io, sourceDir, dest) {
+    if (!(await readSource(io.host, sourceDir))) {
+        io.stderr(`mk plugin: cannot read plugin source at ${sourceDir}\n`);
+        return EXIT.ERROR;
+    }
+    let count;
+    try {
+        count = await copyTree(io.host, sourceDir, dest);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : error;
+        io.stderr(`mk plugin: refusing unsafe entry (${detail})\n`);
+        return EXIT.ERROR;
+    }
+    if (!(await skillMatches(io.host, sourceDir, dest))) {
+        io.stderr("mk plugin: SKILL.md hash mismatch after copy\n");
+        return EXIT.ERROR;
+    }
+    io.stdout(`plugin ${count} files -> ${dest}\n`);
+    return EXIT.OK;
+}
+export const pluginCommand = makePluginCommand();

package/dist/preview/command.d.ts

@@ -0,0 +1,10 @@
+import type { Storyboard } from "@anvpx/motion-schema";
+import { type TemplateEnv } from "../template/env.ts";
+import type { Command, Io } from "../types.ts";
+/**
+ * Copies authored scene directories beside a derived storyboard, so a relative
+ * `props.dir` still resolves after the storyboard is rewritten into a scratch dir.
+ */
+export declare function copyCustomScenes(host: Io["host"], board: Storyboard, origin: string, targetDir: string): Promise<void>;
+export declare const makePreviewCommand: (env?: () => TemplateEnv, clock?: () => number) => Command;
+export declare const previewCommand: Command;