@anvpx/motion-cli 0.0.0-stage → 0.1.1

package/dist/storyboard/custom.js

@@ -0,0 +1,133 @@
+import { dirname, join, resolve } from "node:path";
+import { CUSTOM_SCENE_TYPE, HELPER_LIMITS, lintCustomSource, readRelativeClosure, resolveSceneDir, scanVendorImports, } from "@anvpx/motion-build";
+import { sceneContainment } from "./containment.js";
+/** Files an authored scene must ship; `style.css` is optional. */
+const REQUIRED = ["scene.js", "fragment.html"];
+const OPTIONAL_CSS = "style.css";
+const customEntries = (board) => {
+    const scenes = board.scenes;
+    if (!Array.isArray(scenes))
+        return [];
+    const entries = [];
+    scenes.forEach((scene, index) => {
+        const entry = scene;
+        if (entry.type !== CUSTOM_SCENE_TYPE)
+            return;
+        entries.push({
+            index,
+            id: typeof entry.id === "string" ? entry.id : `#${index}`,
+            dir: typeof entry.props?.dir === "string" ? entry.props.dir : "",
+        });
+    });
+    return entries;
+};
+/** True when the storyboard references an authored scene; cheap, no disk access. */
+export const hasCustomScenes = (board) => customEntries(board).length > 0;
+const error = (path, message, suggestion) => ({
+    severity: "error",
+    path,
+    message,
+    ...(suggestion === undefined ? {} : { suggestion }),
+});
+/** Runs the determinism probes on one helper, under its own scene-relative path. */
+const lintHelper = (text, dirName, path) => lintCustomSource({ js: text }, dirName).map((finding) => ({
+    ...finding,
+    path: finding.path.replace(/scene\.js:/, `${path}:`),
+}));
+/**
+ * Reads every authored scene beside the storyboard, refuses directories that escape it
+ * (textually or through a symlink/junction), and runs the determinism lint. The build
+ * stays pure: this is the only place that touches disk.
+ */
+export async function readCustomScenes(board, storyboardPath, host) {
+    const entries = customEntries(board);
+    const sources = {};
+    const findings = [];
+    const baseDir = dirname(resolve(storyboardPath));
+    for (const entry of entries) {
+        const where = `/scenes/${entry.index}/props/dir`;
+        const resolved = resolveSceneDir(baseDir, entry.dir);
+        if (!resolved.ok) {
+            findings.push(error(where, resolved.message));
+            continue;
+        }
+        const dirName = `scenes/${entry.id}`;
+        const missing = [];
+        for (const file of REQUIRED) {
+            if (!(await host.exists(join(resolved.dir, file))))
+                missing.push(file);
+        }
+        if (missing.length > 0) {
+            findings.push(error(where, `missing ${missing.join(", ")}`, `add them under ${entry.dir}`));
+            continue;
+        }
+        // Textual containment is not enough: a symlink or junction can leave the project.
+        const containment = sceneContainment(baseDir, resolved.dir, [...REQUIRED, OPTIONAL_CSS]);
+        if (!containment.dirInside) {
+            findings.push(error(where, "scene directory resolves outside the storyboard directory (symlink/junction)", "replace the link with a real directory inside the project"));
+            continue;
+        }
+        const escaped = new Set(containment.escapedFiles);
+        for (const file of escaped) {
+            findings.push(error(`${dirName}/${file}`, "scene file resolves outside the scene directory (symlink/junction)", "replace the link with a real file inside the scene directory"));
+        }
+        if (escaped.size > 0)
+            continue;
+        try {
+            const js = await host.readText(join(resolved.dir, "scene.js"));
+            const html = await host.readText(join(resolved.dir, "fragment.html"));
+            const cssPath = join(resolved.dir, OPTIONAL_CSS);
+            const css = (await host.exists(cssPath)) ? await host.readText(cssPath) : undefined;
+            // A bare import only resolves if the build wrote an import map entry for it.
+            const vendor = scanVendorImports(js);
+            for (const name of vendor.unknown) {
+                findings.push(error(`${dirName}/scene.js`, `cannot import "${name}": the emitted page vendors no such library`, "import three or postprocessing, or use a relative path (./, ../) inside the scene"));
+            }
+            // Relative helpers are part of the scene: package the closure and lint it too.
+            // Each helper is containment-checked before its bytes are read.
+            const helperEscapes = [];
+            const closure = await readRelativeClosure(js, async (path) => {
+                const check = sceneContainment(baseDir, resolved.dir, [path]);
+                if (!check.dirInside || check.escapedFiles.length > 0) {
+                    helperEscapes.push(path);
+                    return undefined;
+                }
+                const full = join(resolved.dir, path);
+                return (await host.exists(full)) ? host.readText(full) : undefined;
+            });
+            for (const path of helperEscapes) {
+                findings.push(error(`${dirName}/${path}`, "helper resolves outside the scene directory (symlink/junction)", "keep the real file inside the scene directory"));
+            }
+            for (const specifier of closure.escaping) {
+                findings.push(error(`${dirName}/scene.js`, `relative import "${specifier}" escapes the scene directory`, "keep helpers inside the scene directory (./lib/format.js)"));
+            }
+            for (const path of closure.missing) {
+                if (helperEscapes.includes(path))
+                    continue;
+                findings.push(error(`${dirName}/scene.js`, `cannot import "./${path}": no such file beside the scene`, "add the file, or inline the code"));
+            }
+            if (closure.overflow) {
+                findings.push(error(`${dirName}/scene.js`, `scene helper closure exceeds ${HELPER_LIMITS.files} files or ${HELPER_LIMITS.chars} characters`, "keep the scene to a few small helpers"));
+            }
+            for (const file of closure.files) {
+                findings.push(...lintHelper(file.text, dirName, file.path));
+            }
+            // A scene whose helper cannot be read safely is not emitted at all.
+            if (helperEscapes.length > 0)
+                continue;
+            const source = {
+                js,
+                html,
+                ...(css === undefined ? {} : { css }),
+                ...(vendor.libs.length === 0 ? {} : { vendor: vendor.libs }),
+                ...(closure.files.length === 0 ? {} : { files: closure.files }),
+            };
+            findings.push(...lintCustomSource(source, dirName));
+            sources[entry.id] = source;
+        }
+        catch (cause) {
+            findings.push(error(where, `cannot read scene files: ${cause.message}`));
+        }
+    }
+    return { sources, findings };
+}

package/dist/storyboard/edit.d.ts

@@ -0,0 +1,19 @@
+import type { Io } from "../types.ts";
+import { type CheckReport } from "./check.ts";
+/** What an edit produced: the new document and how to describe it once it is written. */
+export type Edit = {
+    ok: true;
+    value: unknown;
+    lines(report: CheckReport): string[];
+} | {
+    ok: false;
+    message: string;
+};
+/** `scenes 5 | total 25s | 0 errors, 1 warnings`: the second line every edit prints. */
+export declare const statusLine: (report: CheckReport, scenes: number) => string;
+export declare const round1: (value: number) => number;
+/**
+ * The shared edit pipeline: load, transform, validate the result with the full validator, write
+ * atomically. An invalid result is never written: the pointer errors are printed and the exit is 2.
+ */
+export declare function editStoryboard(name: string, path: string, io: Io, transform: (doc: unknown) => Edit): Promise<number>;

package/dist/storyboard/edit.js

@@ -0,0 +1,39 @@
+import { EXIT } from "../exit-codes.js";
+import { checkStoryboard } from "./check.js";
+import { readJsonFile } from "./load.js";
+import { formatFinding } from "./report.js";
+const MAX_ERROR_LINES = 2;
+const refusal = (name, report) => {
+    const shown = report.errors.slice(0, MAX_ERROR_LINES).map(formatFinding);
+    const more = report.errors.length - shown.length;
+    const head = `${name} refused, nothing written: ${report.errors.length} errors`;
+    const tail = more > 0 ? ` (+${more} more; run mk validate)` : "";
+    return `${[head, ...shown].join("\n")}${tail}\n`;
+};
+/** `scenes 5 | total 25s | 0 errors, 1 warnings`: the second line every edit prints. */
+export const statusLine = (report, scenes) => `scenes ${scenes} | total ${round1(report.total ?? 0)}s | ${report.errors.length} errors, ${report.warnings.length} warnings`;
+export const round1 = (value) => Math.round(value * 10) / 10;
+/**
+ * The shared edit pipeline: load, transform, validate the result with the full validator, write
+ * atomically. An invalid result is never written: the pointer errors are printed and the exit is 2.
+ */
+export async function editStoryboard(name, path, io, transform) {
+    const loaded = await readJsonFile(path, io.host);
+    if (!loaded.ok) {
+        io.stderr(`mk ${name}: ${loaded.message}\n`);
+        return EXIT.USAGE;
+    }
+    const edit = transform(loaded.value);
+    if (!edit.ok) {
+        io.stderr(`mk ${name}: ${edit.message}\n`);
+        return EXIT.USAGE;
+    }
+    const report = checkStoryboard(edit.value);
+    if (report.errors.length > 0) {
+        io.stderr(refusal(name, report));
+        return EXIT.USAGE;
+    }
+    await io.host.writeTextAtomic(path, `${JSON.stringify(edit.value, null, 2)}\n`);
+    io.stdout(`${edit.lines(report).join("\n")}\n`);
+    return EXIT.OK;
+}

package/dist/storyboard/load.d.ts

@@ -0,0 +1,11 @@
+import type { Host } from "../types.ts";
+export type LoadResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    kind: "io" | "syntax";
+    message: string;
+};
+/** Reads and parses a JSON file; I/O and syntax failures are reported as values. */
+export declare function readJsonFile(path: string, host: Host): Promise<LoadResult>;

package/dist/storyboard/load.js

@@ -0,0 +1,52 @@
+const POSITION = /at position (\d+)/;
+const POSITION_SUFFIX = /\s+in JSON at position \d+(?: \(line \d+ column \d+\))?/;
+/** True while `text[0, length)` is still the start of some valid document. */
+function isLivePrefix(text, length) {
+    try {
+        JSON.parse(text.slice(0, length));
+        return true;
+    }
+    catch (error) {
+        const message = error.message;
+        if (message.includes("end of JSON input"))
+            return true;
+        const position = POSITION.exec(message)?.[1];
+        return position !== undefined && Number(position) >= length;
+    }
+}
+/** Offset of the first character that makes the text invalid (binary search over prefixes). */
+function errorOffset(text) {
+    let live = 0;
+    let dead = text.length;
+    while (dead - live > 1) {
+        const middle = Math.floor((live + dead) / 2);
+        if (isLivePrefix(text, middle))
+            live = middle;
+        else
+            dead = middle;
+    }
+    return live;
+}
+function syntaxMessage(text, error) {
+    const reason = error.message.replace(POSITION_SUFFIX, "");
+    const before = text.slice(0, errorOffset(text)).split("\n");
+    const line = before.length;
+    const col = (before.at(-1)?.length ?? 0) + 1;
+    return `invalid JSON at line ${line}, col ${col}: ${reason}`;
+}
+/** Reads and parses a JSON file; I/O and syntax failures are reported as values. */
+export async function readJsonFile(path, host) {
+    let text;
+    try {
+        text = await host.readText(path);
+    }
+    catch (error) {
+        return { ok: false, kind: "io", message: `cannot read ${path}: ${error.message}` };
+    }
+    try {
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch (error) {
+        return { ok: false, kind: "syntax", message: syntaxMessage(text, error) };
+    }
+}

package/dist/storyboard/report.d.ts

@@ -0,0 +1,5 @@
+import type { Finding } from "./check.ts";
+/** `E /scenes/1/props/items/0: message -> suggestion`; the JSON root prints as `/`. */
+export declare function formatFinding(finding: Finding): string;
+export declare const formatFindings: (findings: readonly Finding[]) => string;
+export declare const summaryLine: (errors: number, warnings: number) => string;

package/dist/storyboard/report.js

@@ -0,0 +1,8 @@
+/** `E /scenes/1/props/items/0: message -> suggestion`; the JSON root prints as `/`. */
+export function formatFinding(finding) {
+    const level = finding.severity === "error" ? "E" : "W";
+    const suggestion = finding.suggestion === undefined ? "" : ` -> ${finding.suggestion}`;
+    return `${level} ${finding.path || "/"}: ${finding.message}${suggestion}`;
+}
+export const formatFindings = (findings) => findings.map((finding) => `${formatFinding(finding)}\n`).join("");
+export const summaryLine = (errors, warnings) => `${errors} errors, ${warnings} warnings\n`;

package/dist/template/coerce.d.ts

@@ -0,0 +1,6 @@
+import type { Result, SlotDef } from "@anvpx/motion-schema";
+/**
+ * `--set k=v` values to slot values by slot type: text/enum as is, `text[]` as `a|b|c` (backslash-pipe is a literal pipe),
+ * number as a finite number. Objects (and lists of objects) need `--slots file.json`.
+ */
+export declare function coerceSets(slots: Readonly<Record<string, SlotDef>>, sets: readonly string[]): Result<Record<string, unknown>>;

package/dist/template/coerce.js

@@ -0,0 +1,44 @@
+const fail = (path, message, suggestion) => ({
+    ok: false,
+    errors: [suggestion === undefined ? { path, message } : { path, message, suggestion }],
+});
+/** One `--set` value by slot type. */
+function coerceOne(name, def, text) {
+    const path = `/set/${name}`;
+    if (def.type === "object") {
+        return fail(path, `slot "${name}" is an object; --set cannot express it`, "put it in --slots file.json");
+    }
+    if (def.type === "number") {
+        const number = Number(text);
+        return text.trim() === "" || !Number.isFinite(number)
+            ? fail(path, `"${text}" is not a number`)
+            : { ok: true, value: number };
+    }
+    if (def.type === "text[]") {
+        const items = text.split(/(?<!\\)\|/).map((item) => item.replaceAll("\\|", "|").trim());
+        return { ok: true, value: text === "" ? [] : items };
+    }
+    return { ok: true, value: text };
+}
+/**
+ * `--set k=v` values to slot values by slot type: text/enum as is, `text[]` as `a|b|c` (backslash-pipe is a literal pipe),
+ * number as a finite number. Objects (and lists of objects) need `--slots file.json`.
+ */
+export function coerceSets(slots, sets) {
+    const value = {};
+    for (const set of sets) {
+        const eq = set.indexOf("=");
+        if (eq === -1)
+            return fail(`/set/${set}`, `--set needs name=value, got "${set}"`);
+        const name = set.slice(0, eq);
+        const def = slots[name];
+        if (def === undefined) {
+            return fail(`/set/${name}`, `unknown slot "${name}"`, `use one of: ${Object.keys(slots).join("|")}`);
+        }
+        const one = coerceOne(name, def, set.slice(eq + 1));
+        if (!one.ok)
+            return one;
+        value[name] = one.value;
+    }
+    return { ok: true, value };
+}

package/dist/template/command.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "../types.ts";
+import { type TemplateEnv } from "./env.ts";
+/** `mk template list|show|validate|fork`; `env` is injectable for tests. */
+export declare const makeTemplateCommand: (env?: () => TemplateEnv) => Command;
+export declare const templateCommand: Command;

package/dist/template/command.js

@@ -0,0 +1,163 @@
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { loadTemplate, validateTemplate } from "@anvpx/motion-build";
+import { parseFlags, requirePositional, usageError } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { defaultEnv, findTemplate, formatErrors, loadOptions, platformsFor, } from "./env.js";
+import { runFork } from "./fork.js";
+import { formatBlueprint, formatTemplate } from "./format.js";
+import { list } from "./list.js";
+const USAGE = `mk template list [--for "<brief>"] [--tag a,b] [--aspect 9:16] [--sec 45] [--domain <d>] [--json]
+mk template show <template>[/<blueprint>] [--json]
+mk template validate <dir|id> [--json]
+mk template fork <template>/<blueprint> --as <name> [--out <storyboard.json>] [--json]
+
+Templates are data folders (themes, styles, blueprints, pacing, copy); a blueprint is a parameterised storyboard.
+  list      one line per template: id@version | summary | tags | aspects | blueprints | source (<= 15 lines; shadowed flagged)
+            --for "<brief>" ranks blueprints (top 8, with matched words; NOT-FOR sinks); --tag a,b is an exact AND;
+            --aspect and --sec are hard filters. It filters and explains; you choose.
+  show      template: use cases, good/not for, styles, themes, blueprints with slot signatures (<= 60 lines);
+            template/blueprint: slots, scenes, example and a ready mk new line (<= 40 lines)
+  validate  contracts, themes (AA contrast), styles, blueprint examples; exit 0 clean, 2 on errors
+Roots, highest precedence first: ./templates, $MK_TEMPLATES_PATH, ~/.motion-kit/templates, built-in.
+`;
+const FLAGS = {
+    domain: { type: "string" },
+    for: { type: "string" },
+    tag: { type: "string" },
+    aspect: { type: "string" },
+    sec: { type: "string" },
+    json: { type: "boolean" },
+};
+const SUBCOMMANDS = ["list", "show", "validate", "fork"];
+async function show(target, json, env, io) {
+    const [id = "", blueprintId, ...extra] = target.split("/");
+    if (extra.length > 0)
+        return usageError("template", USAGE, `bad target "${target}"`, io).code;
+    const found = findTemplate(env, io, id);
+    if (!found.ok) {
+        io.stderr(`mk template: ${found.message}\n`);
+        return EXIT.USAGE;
+    }
+    const { template, source } = found;
+    if (blueprintId === undefined) {
+        io.stdout(json
+            ? `${JSON.stringify({ ...template.manifest, source })}\n`
+            : formatTemplate(template, source));
+        return EXIT.OK;
+    }
+    const blueprint = template.blueprints.get(blueprintId);
+    if (blueprint === undefined) {
+        const known = [...template.blueprints.keys()].join("|");
+        io.stderr(`mk template: unknown blueprint "${blueprintId}"; use one of: ${known}\n`);
+        return EXIT.USAGE;
+    }
+    const previewFile = join(template.dir, "previews", `${blueprint.id}.png`);
+    const preview = (await io.host.exists(previewFile)) ? previewFile : undefined;
+    io.stdout(json ? `${JSON.stringify(blueprint)}\n` : formatBlueprint(template, blueprint, preview));
+    return EXIT.OK;
+}
+async function validate(target, json, env, io) {
+    const dir = resolve(target);
+    if (await io.host.exists(join(dir, "template.json"))) {
+        const loaded = loadTemplate(dir, loadOptions(env));
+        if (!loaded.ok)
+            return print(target, loaded.errors, [], json, io);
+        return validateLoaded(loaded.value, json, io, isBuiltIn(dir, env));
+    }
+    const byId = findTemplate(env, io, target);
+    if (!byId.ok) {
+        io.stderr(`mk template: ${byId.message}
+`);
+        return EXIT.USAGE;
+    }
+    return validateLoaded(byId.template, json, io, byId.source === "built-in");
+}
+const isBuiltIn = (dir, env) => {
+    const inside = relative(resolve(env.builtInDir), dir);
+    return inside !== "" && !inside.startsWith("..") && !isAbsolute(inside);
+};
+async function validateLoaded(template, json, io, builtIn) {
+    const report = validateTemplate(template, { platforms: await platformsFor(io), builtIn });
+    const label = `${template.manifest.id}@${template.manifest.version}`;
+    return print(label, report.errors, report.warnings, json, io);
+}
+function print(label, errors, warnings, json, io) {
+    if (json) {
+        io.stdout(`${JSON.stringify({ ok: errors.length === 0, errors, warnings })}\n`);
+    }
+    else {
+        const warn = warnings.map((w) => `W ${w.path}: ${w.message}${w.suggestion === undefined ? "" : ` -> ${w.suggestion}`}`);
+        const lines = [...(errors.length > 0 ? [formatErrors(errors)] : []), ...warn];
+        io.stdout(`${lines.map((l) => `${l}\n`).join("")}template ${label}: ${errors.length} errors, ${warnings.length} warnings\n`);
+    }
+    return errors.length === 0 ? EXIT.OK : EXIT.USAGE;
+}
+const isSub = (value) => SUBCOMMANDS.some((sub) => sub === value);
+const ASPECT = /^\d+:\d+$/;
+const bad = (message, io) => usageError("template", USAGE, message, io).code;
+/** The `list` flags as a request, or an exit code after a usage error. */
+function listRequest(flags, io) {
+    const text = (name) => {
+        const value = flags[name];
+        return typeof value === "string" ? value : undefined;
+    };
+    const aspect = text("aspect");
+    if (aspect !== undefined && !ASPECT.test(aspect))
+        return bad(`--aspect ${aspect} must look like 16:9`, io);
+    const secText = text("sec");
+    const sec = secText === undefined ? undefined : Number(secText);
+    if (sec !== undefined && !(Number.isInteger(sec) && sec > 0)) {
+        return bad(`--sec ${secText} must be a positive whole number of seconds`, io);
+    }
+    const tags = (text("tag") ?? "")
+        .split(",")
+        .map((tag) => tag.trim().toLowerCase())
+        .filter((tag) => tag !== "");
+    return {
+        domain: text("domain"),
+        query: text("for"),
+        filters: {
+            ...(tags.length === 0 ? {} : { tags }),
+            ...(aspect === undefined ? {} : { aspect }),
+            ...(sec === undefined ? {} : { sec }),
+        },
+        json: flags.json === true,
+    };
+}
+function parseRequest(args, io) {
+    const parsed = parseFlags("template", USAGE, args, FLAGS, io);
+    if (parsed.kind === "exit")
+        return parsed.code;
+    const [sub, ...rest] = parsed.positionals;
+    if (!isSub(sub))
+        return bad(`use one of: ${SUBCOMMANDS.join("|")}`, io);
+    const request = listRequest(parsed.flags, io);
+    if (typeof request === "number")
+        return request;
+    if (sub === "list") {
+        const extra = rest[0];
+        return extra === undefined
+            ? { sub, target: undefined, list: request }
+            : bad(`unexpected argument "${extra}"`, io);
+    }
+    const target = requirePositional("template", USAGE, rest, "<template>", io);
+    return typeof target === "string" ? { sub, target, list: request } : target.code;
+}
+/** `mk template list|show|validate|fork`; `env` is injectable for tests. */
+export const makeTemplateCommand = (env = defaultEnv) => ({
+    name: "template",
+    summary: "list, show, validate or fork templates (themes + styles + blueprints)",
+    async run(args, io) {
+        if (args[0] === "fork")
+            return runFork(args.slice(1), env(), io);
+        const request = parseRequest(args, io);
+        if (typeof request === "number")
+            return request;
+        const { sub, target = "", list: listing } = request;
+        if (sub === "list")
+            return list(listing, env(), io);
+        const json = listing.json;
+        return sub === "show" ? show(target, json, env(), io) : validate(target, json, env(), io);
+    },
+});
+export const templateCommand = makeTemplateCommand();

package/dist/template/env.d.ts

@@ -0,0 +1,34 @@
+import { type LoadedTemplate, type PlatformLookup } from "@anvpx/motion-build";
+import type { ValidationError } from "@anvpx/motion-schema";
+import type { Io } from "../types.ts";
+/** Where templates come from; injectable so tests use fixtures instead of the real built-ins. */
+export interface TemplateEnv {
+    /** The built-in templates directory (from `@anvpx/motion-templates`; `build` never imports it). */
+    builtInDir: string;
+    /** Folder behind `@shared/<name>.json` theme refs; unset means such templates fail to load. */
+    sharedThemesDir?: string | undefined;
+    /** Search stopwords; unset means the build default list. */
+    stopwords?: readonly string[] | undefined;
+    /** `MK_TEMPLATES_PATH`. */
+    envPath?: string | undefined;
+    /** Project directory whose `templates/` has top precedence. */
+    projectDir: string;
+}
+export declare const defaultEnv: () => TemplateEnv;
+export declare const loadOptions: (env: TemplateEnv) => {
+    sharedThemesDir: string | undefined;
+};
+export declare const rootsOf: (env: TemplateEnv, io: Io) => import("@anvpx/motion-build").TemplateRoot[];
+export declare const discover: (env: TemplateEnv, io: Io) => import("@anvpx/motion-build").Discovery;
+export type Found = {
+    ok: true;
+    template: LoadedTemplate;
+    source: string;
+} | {
+    ok: false;
+    message: string;
+};
+/** Loads a template by id from the discovery roots; a miss lists the known ids. */
+export declare function findTemplate(env: TemplateEnv, io: Io, id: string): Found;
+export declare const formatErrors: (errors: readonly ValidationError[]) => string;
+export declare const platformsFor: (io: Io) => Promise<PlatformLookup>;

package/dist/template/env.js

@@ -0,0 +1,38 @@
+import { discoverTemplates, loadTemplate, templateRoots, } from "@anvpx/motion-build";
+import { listNpmTemplateRoots, SHARED_THEMES_DIR, STOPWORDS, TEMPLATES_DIR, } from "@anvpx/motion-templates";
+import { platformLookup } from "../verify/platform.js";
+export const defaultEnv = () => ({
+    builtInDir: TEMPLATES_DIR,
+    sharedThemesDir: SHARED_THEMES_DIR,
+    stopwords: STOPWORDS,
+    envPath: process.env.MK_TEMPLATES_PATH,
+    projectDir: process.cwd(),
+});
+export const loadOptions = (env) => ({ sharedThemesDir: env.sharedThemesDir });
+export const rootsOf = (env, io) => templateRoots({
+    projectDir: env.projectDir,
+    envPath: env.envPath,
+    homeDir: io.host.homeDir,
+    builtInDir: env.builtInDir,
+});
+export const discover = (env, io) => discoverTemplates([...rootsOf(env, io), ...listNpmTemplateRoots(env.projectDir)]);
+/** Loads a template by id from the discovery roots; a miss lists the known ids. */
+export function findTemplate(env, io, id) {
+    const { templates } = discover(env, io);
+    const candidate = templates.find((t) => t.id === id);
+    if (candidate === undefined) {
+        const known = templates.map((t) => t.id).join("|");
+        return {
+            ok: false,
+            message: `unknown template "${id}"; use one of: ${known || "(none found)"}`,
+        };
+    }
+    const loaded = loadTemplate(candidate.dir, loadOptions(env));
+    if (!loaded.ok)
+        return { ok: false, message: formatErrors(loaded.errors) };
+    return { ok: true, template: loaded.value, source: candidate.source };
+}
+export const formatErrors = (errors) => errors
+    .map((e) => `E ${e.path}: ${e.message}${e.suggestion === undefined ? "" : ` -> ${e.suggestion}`}`)
+    .join("\n");
+export const platformsFor = (io) => platformLookup(io.host);

package/dist/template/fork.d.ts

@@ -0,0 +1,8 @@
+import type { Command, Io } from "../types.ts";
+import { type TemplateEnv } from "./env.ts";
+export declare const FORK_USAGE = "mk template fork <template>/<blueprint> --as <name> [--out <storyboard.json>] [--json]\n\nForks a blueprint example into a user-owned storyboard you can reshape with mk scene/patch.\nWrites the storyboard, vendors the theme(s) it uses into <out dir>/themes/ and records\nprovenance (including forkedFrom <template>@<version>) in <out dir>/.mk/<name>/template.json.\nBuilt-ins are never modified; the fork is yours.\n  --as <name>   fork folder/name (required): letters, numbers, - and _; no slashes\n  --out f       storyboard path (default <as>/storyboard.json)\nSee `mk template show <template>/<blueprint>` for slots and limits.\n";
+/** `mk template fork <template>/<blueprint> --as <name>`; `env` is injectable for tests. */
+export declare function runFork(args: readonly string[], env: TemplateEnv, io: Io): Promise<number>;
+/** `mk template fork` as a standalone command (wired as a `mk template` subcommand too). */
+export declare const makeForkCommand: (env?: () => TemplateEnv) => Command;
+export declare const forkCommand: Command;