@anvpx/motion-cli 0.0.0-stage → 0.1.0

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;

package/dist/template/fork.js

@@ -0,0 +1,156 @@
+import { createHash } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { instantiate } from "@anvpx/motion-build";
+import { MK_DIR, mkDir, storyboardStem } from "../approval/hash.js";
+import { parseFlags, requirePositional, textFlag, usageError } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { defaultEnv, findTemplate, formatErrors, platformsFor } from "./env.js";
+import { TEMPLATE_PROVENANCE } from "./new.js";
+export const FORK_USAGE = `mk template fork <template>/<blueprint> --as <name> [--out <storyboard.json>] [--json]
+
+Forks a blueprint example into a user-owned storyboard you can reshape with mk scene/patch.
+Writes the storyboard, vendors the theme(s) it uses into <out dir>/themes/ and records
+provenance (including forkedFrom <template>@<version>) in <out dir>/.mk/<name>/template.json.
+Built-ins are never modified; the fork is yours.
+  --as <name>   fork folder/name (required): letters, numbers, - and _; no slashes
+  --out f       storyboard path (default <as>/storyboard.json)
+See \`mk template show <template>/<blueprint>\` for slots and limits.
+`;
+const FLAGS = {
+    as: { type: "string" },
+    out: { type: "string" },
+    json: { type: "boolean" },
+};
+const AS_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const MAX_WARNING_LINES = 5;
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+/** Resolves `<template>/<blueprint>`; a miss prints the known ids and yields an exit code. */
+function resolveTarget(target, env, io) {
+    const [templateId = "", blueprintId = "", ...extra] = target.split("/");
+    if (blueprintId === "" || extra.length > 0) {
+        return usageError("template fork", FORK_USAGE, "target must be <template>/<blueprint>", io)
+            .code;
+    }
+    const found = findTemplate(env, io, templateId);
+    if (!found.ok) {
+        io.stderr(`mk template fork: ${found.message}\n`);
+        return EXIT.USAGE;
+    }
+    const blueprint = found.template.blueprints.get(blueprintId);
+    if (blueprint === undefined) {
+        const known = [...found.template.blueprints.keys()].join("|");
+        io.stderr(`mk template fork: unknown blueprint "${blueprintId}"; use one of: ${known}\n`);
+        return EXIT.USAGE;
+    }
+    return { template: found.template, blueprintId, blueprint };
+}
+const asNameOf = (flags, io) => {
+    const name = textFlag(flags, "as");
+    if (name === undefined) {
+        return usageError("template fork", FORK_USAGE, "missing --as <name>", io).code;
+    }
+    if (!AS_RE.test(name)) {
+        return usageError("template fork", FORK_USAGE, `--as "${name}" must match [A-Za-z0-9_-]+ with no slashes`, io).code;
+    }
+    return name;
+};
+/** Writes the storyboard, the vendored theme(s) and the fork provenance; returns the storyboard path. */
+async function writeFork(made, asName, outFlag, io) {
+    const out = resolve(outFlag ?? join(asName, "storyboard.json"));
+    const dir = dirname(out);
+    const text = `${made.text}\n`;
+    await io.host.writeText(out, text);
+    for (const theme of made.themes)
+        await io.host.writeText(join(dir, theme.file), theme.text);
+    const record = {
+        ...made.provenance,
+        storyboardSha256: sha256(text),
+        forkedFrom: made.provenance.template,
+        forkName: asName,
+    };
+    await io.host.writeText(join(mkDir(out), TEMPLATE_PROVENANCE), `${JSON.stringify(record, null, 2)}\n`);
+    return out;
+}
+function report(made, asName, out, json, io) {
+    const { meta } = made.storyboard;
+    const overlays = made.storyboard.scenes.filter((s) => s.layer === "overlay").length;
+    const scenes = made.sceneCount - overlays;
+    const frame = { width: meta.width, height: meta.height, fps: meta.fps };
+    const files = made.themes.map((t) => t.file);
+    if (json) {
+        const { provenance, totalSec } = made;
+        io.stdout(`${JSON.stringify({
+            ok: true,
+            fork: asName,
+            storyboard: out,
+            forkedFrom: provenance.template,
+            ...provenance,
+            scenes,
+            overlays,
+            totalSec,
+            frame,
+            themes: files,
+            warnings: made.warnings.length,
+        })}\n`);
+        return;
+    }
+    const { provenance } = made;
+    const label = `${provenance.template.split("@")[0]}/${provenance.blueprint}`;
+    io.stdout(`fork ok | ${label} -> ${asName} | ${scenes} scenes + ${overlays} overlays ${made.totalSec}s ${frame.width}x${frame.height}@${frame.fps}\n` +
+        `wrote ${out} (+ ${files.join(", ")}, ${MK_DIR}/${storyboardStem(out)}/${TEMPLATE_PROVENANCE})\n` +
+        `next: mk validate ${out} && mk preview ${out}\n`);
+}
+/** Everything `instantiate` needs, from flags and the template example; an exit code on bad input. */
+async function plan(args, env, io) {
+    const parsed = parseFlags("template fork", FORK_USAGE, args, FLAGS, io);
+    if (parsed.kind === "exit")
+        return parsed.code;
+    const name = requirePositional("template fork", FORK_USAGE, parsed.positionals, "<template>/<blueprint>", io);
+    if (typeof name !== "string")
+        return name.code;
+    const asName = asNameOf(parsed.flags, io);
+    if (typeof asName === "number")
+        return asName;
+    const target = resolveTarget(name, env, io);
+    if (typeof target === "number")
+        return target;
+    return {
+        target,
+        asName,
+        out: textFlag(parsed.flags, "out"),
+        json: parsed.flags.json === true,
+    };
+}
+const formatWarnings = (made) => {
+    const rows = made.warnings.slice(0, MAX_WARNING_LINES);
+    return rows.map((w) => `W ${w.path}: ${w.message}\n`).join("");
+};
+/** `mk template fork <template>/<blueprint> --as <name>`; `env` is injectable for tests. */
+export async function runFork(args, env, io) {
+    const planned = await plan(args, env, io);
+    if (typeof planned === "number")
+        return planned;
+    const slots = { ...planned.target.blueprint.example };
+    const result = instantiate(planned.target.template, planned.target.blueprintId, slots, {
+        platforms: await platformsFor(io),
+    });
+    if (!result.ok) {
+        io.stderr(`mk template fork: ${formatErrors(result.errors)}\n`);
+        return EXIT.USAGE;
+    }
+    const out = await writeFork(result.value, planned.asName, planned.out, io);
+    report(result.value, planned.asName, out, planned.json, io);
+    const warnings = formatWarnings(result.value);
+    if (warnings !== "")
+        io.stderr(warnings);
+    return EXIT.OK;
+}
+/** `mk template fork` as a standalone command (wired as a `mk template` subcommand too). */
+export const makeForkCommand = (env = defaultEnv) => ({
+    name: "fork",
+    summary: "fork a template blueprint example into a user-owned storyboard",
+    async run(args, io) {
+        return runFork(args, env(), io);
+    },
+});
+export const forkCommand = makeForkCommand();

package/dist/template/format.d.ts

@@ -0,0 +1,21 @@
+import { type LoadedTemplate } from "@anvpx/motion-build";
+import type { BlueprintDoc, SlotDef } from "@anvpx/motion-schema";
+/** One-line slot signature: `points* text[][3..5]<=70`; `*` required, `?` optional. */
+export declare const slotSignature: (name: string, def: SlotDef) => string;
+/** One line cut to `max` characters with an ellipsis. */
+export declare const clip: (text: string, max: number) => string;
+/** Approximate tokens of a text (4 characters each, as in the copy-guide limit). */
+export declare const tokensOf: (text: string) => number;
+/** Lengths as `30-60s`; `-` when unknown. */
+export declare const lengthLabel: (lengths: {
+    min: number;
+    max: number;
+} | undefined) => string;
+/** The 3D honesty line, repeated wherever a storyboard may contain `scene3d`. */
+export declare const SCENE3D_NOTE = "scene3d requires WebGL and falls back to a flat 2D canvas without it.";
+/** `mk template show <template>`; at most 60 lines and about 600 tokens. */
+export declare function formatTemplate(template: LoadedTemplate, source: string): string;
+/** A ready `mk new` line built from the blueprint `example`; object slots need `--slots`. */
+export declare const useLine: (id: string, blueprint: BlueprintDoc) => string;
+/** `mk template show <template>/<blueprint>`; at most 40 lines and about 450 tokens (the example is the first to go, the ready `mk new` line stays). */
+export declare function formatBlueprint(template: LoadedTemplate, blueprint: BlueprintDoc, preview?: string): string;

package/dist/template/format.js

@@ -0,0 +1,161 @@
+import { templateLengths } from "@anvpx/motion-build";
+const flagOf = (def) => def.required ? "*" : def.optional ? "?" : "";
+const range = (min, max) => min === undefined && max === undefined ? "" : `[${min ?? 0}..${max ?? "n"}]`;
+const upTo = (max) => (max === undefined ? "" : `<=${max}`);
+const fieldsOf = (fields) => Object.entries(fields)
+    .map(([key, type]) => `${key}:${type}`)
+    .join(",");
+const SIGNATURES = {
+    text: (name, def) => `${name}${flagOf(def)} text${upTo(def.max)}`,
+    "text[]": (name, def) => `${name}${flagOf(def)} text${range(def.min, def.max) || "[]"}${upTo(def.itemMax)}`,
+    number: (name, def) => `${name}${flagOf(def)} number${range(def.min, def.max)}`,
+    enum: (name, def) => `${name} ${def.values.join("|")}${def.default === undefined ? "" : ` (default ${def.default})`}`,
+    object: (name, def) => `${name}${flagOf(def)} ${def.list ? `{${fieldsOf(def.fields)}}[]${range(def.min, def.max)}` : `{${fieldsOf(def.fields)}}`}`,
+};
+/** One-line slot signature: `points* text[][3..5]<=70`; `*` required, `?` optional. */
+export const slotSignature = (name, def) => SIGNATURES[def.type](name, def);
+const frameOf = (template, styleId) => {
+    const frame = template.styles.get(styleId)?.frame;
+    if (frame === undefined)
+        return "";
+    return "platform" in frame
+        ? `, ${frame.platform}`
+        : `, ${frame.width}x${frame.height}@${frame.fps}`;
+};
+const CHARS_PER_TOKEN = 4;
+/** Keeps the first `maxLines` lines; the rest collapses into one `(+N more lines)` line. */
+const cap = (lines, max) => lines.length <= max
+    ? lines
+    : [...lines.slice(0, max - 1), `(+${lines.length - max + 1} more lines)`];
+/** One line cut to `max` characters with an ellipsis. */
+export const clip = (text, max) => text.length <= max ? text : `${text.slice(0, max - 1).trimEnd()}…`;
+/** Approximate tokens of a text (4 characters each, as in the copy-guide limit). */
+export const tokensOf = (text) => Math.ceil(text.length / CHARS_PER_TOKEN);
+/** Lengths as `30-60s`; `-` when unknown. */
+export const lengthLabel = (lengths) => lengths === undefined ? "-" : `${lengths.min}-${lengths.max}s`;
+/** Slot signature without the `length`/`style` enums every blueprint repeats. */
+const signatureLine = (blueprint) => {
+    const own = Object.entries(blueprint.slots).filter(([name]) => name !== "length" && name !== "style");
+    return own.map(([name, def]) => slotSignature(name, def)).join("; ");
+};
+const copyLinesWithin = (copy, budgetChars) => {
+    const lines = [];
+    let used = 0;
+    for (const line of copy
+        .split(/\r?\n/)
+        .filter((l) => l.trim() !== "")
+        .slice(0, 14)) {
+        used += line.length + 3;
+        if (used > budgetChars)
+            break;
+        lines.push(`  ${line}`);
+    }
+    return lines;
+};
+const TEMPLATE_MAX_LINES = 60;
+const TEMPLATE_MAX_TOKENS = 600;
+const BLUEPRINT_MAX_LINES = 40;
+const BLUEPRINT_MAX_TOKENS = 450;
+/** The 3D honesty line, repeated wherever a storyboard may contain `scene3d`. */
+export const SCENE3D_NOTE = "scene3d requires WebGL and falls back to a flat 2D canvas without it.";
+/** Drops trailing lines until the text fits the token budget; always keeps the first. */
+const withinTokens = (lines, maxTokens) => {
+    const out = [...lines];
+    while (out.length > 1 && tokensOf(out.join("\n")) > maxTokens)
+        out.pop();
+    return out;
+};
+const discoverLines = (discover, lengths) => {
+    if (discover === undefined)
+        return [];
+    const facts = [
+        `tags: ${discover.tags.join(", ")}`,
+        ...(discover.audience === undefined ? [] : [`audience: ${discover.audience.join(", ")}`]),
+        ...(discover.tone === undefined ? [] : [`tone: ${discover.tone.join(", ")}`]),
+        ...(discover.aspects === undefined ? [] : [`aspects: ${discover.aspects.join(", ")}`]),
+        ...(lengths === undefined ? [] : [`length: ${lengthLabel(lengths)}`]),
+    ];
+    return [
+        `good for: ${discover.goodFor}`,
+        ...(discover.notFor === undefined ? [] : [`not for: ${discover.notFor}`]),
+        "use cases:",
+        ...discover.useCases.map((useCase) => `  - ${useCase}`),
+        facts.join("; "),
+    ];
+};
+/** `mk template show <template>`; at most 60 lines and about 600 tokens. */
+export function formatTemplate(template, source) {
+    const { manifest } = template;
+    const lines = [
+        `${manifest.id}@${manifest.version} (${source}): ${manifest.title}`,
+        manifest.summary,
+        ...discoverLines(manifest.discover, templateLengths(template)),
+        `domains: ${manifest.domains.join(", ")}`,
+        `styles: ${[...template.styles.values()].map((s) => `${s.id} (theme ${s.theme}${frameOf(template, s.id)})`).join("; ")}`,
+        `themes: ${manifest.themes.map((t) => `${t.id} (${t.mode}${t.pair === undefined ? "" : `, pair ${t.pair}`})`).join("; ")}`,
+        "blueprints (mk template show <template>/<blueprint> for slots; every one also takes length, style):",
+    ];
+    for (const blueprint of template.blueprints.values()) {
+        const pick = clip(blueprint.discover?.goodFor ?? blueprint.purpose, 70);
+        lines.push(`  ${blueprint.id}: ${signatureLine(blueprint)} | ${lengthLabel(blueprint.discover?.lengths)} | ${pick}`);
+    }
+    if (uses3d(template))
+        lines.push(`note: ${SCENE3D_NOTE}`);
+    const { pacing } = template;
+    const ranges = Object.entries(pacing.lengths)
+        .map(([name, r]) => `${name} ${r.scenes[0]}-${r.scenes[1]} scenes, ${r.totalSec[0]}-${r.totalSec[1]}s`)
+        .join("; ");
+    lines.push(`pacing: ${pacing.wordsPerSecond} words/s; ${ranges}`);
+    const spent = tokensOf(lines.join("\n")) * CHARS_PER_TOKEN;
+    const room = TEMPLATE_MAX_TOKENS * CHARS_PER_TOKEN - spent - 16;
+    const copy = copyLinesWithin(template.copy, room);
+    const all = copy.length === 0 ? lines : [...lines, "copy guide:", ...copy];
+    return `${cap(withinTokens(all, TEMPLATE_MAX_TOKENS), TEMPLATE_MAX_LINES).join("\n")}
+`;
+}
+const shellQuote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+const setOf = (name, def, value) => {
+    if (def.type === "object" || value === undefined)
+        return undefined;
+    const text = Array.isArray(value)
+        ? value.map((item) => String(item).replaceAll("|", "\\|")).join("|")
+        : String(value);
+    return `--set ${shellQuote(`${name}=${text}`)}`;
+};
+/** A ready `mk new` line built from the blueprint `example`; object slots need `--slots`. */
+export const useLine = (id, blueprint) => {
+    const example = blueprint.example;
+    const sets = Object.entries(blueprint.slots).flatMap(([name, def]) => {
+        const set = setOf(name, def, example[name]);
+        return set === undefined ? [] : [set];
+    });
+    const objects = Object.values(blueprint.slots).some((def) => def.type === "object");
+    const tail = objects ? "  (object slots: --slots file.json)" : "";
+    return `use: mk new ${id} ${sets.join(" ")} --out storyboard.json${tail}`;
+};
+const sceneTypes = (blueprint) => [
+    ...new Set(blueprint.scenes.map((entry) => ("$repeat" in entry ? entry.scene.type : entry.type))),
+];
+/** True when any blueprint can emit `scene3d` (the template view then repeats the honesty line). */
+const uses3d = (template) => [...template.blueprints.values()].some((blueprint) => sceneTypes(blueprint).includes("scene3d"));
+/** `mk template show <template>/<blueprint>`; at most 40 lines and about 450 tokens (the example is the first to go, the ready `mk new` line stays). */
+export function formatBlueprint(template, blueprint, preview) {
+    const id = `${template.manifest.id}/${blueprint.id}`;
+    const types = sceneTypes(blueprint);
+    const lines = [
+        `${id}: ${blueprint.purpose}`,
+        ...(preview === undefined ? [] : [`preview: ${preview}`]),
+        ...discoverLines(blueprint.discover, blueprint.discover?.lengths),
+        "slots (* required, ? optional):",
+    ];
+    for (const [name, def] of Object.entries(blueprint.slots))
+        lines.push(`  ${slotSignature(name, def)}`);
+    lines.push(`styles: ${[...template.styles.keys()].join("|")}; lengths: short|standard|long`);
+    lines.push(`scenes: ${types.join(", ")}`);
+    if (types.includes("scene3d"))
+        lines.push(`note: ${SCENE3D_NOTE}`);
+    lines.push(useLine(id, blueprint));
+    lines.push(`example: ${JSON.stringify(blueprint.example)}`);
+    return `${cap(withinTokens(lines, BLUEPRINT_MAX_TOKENS), BLUEPRINT_MAX_LINES).join("\n")}
+`;
+}

package/dist/template/list.d.ts

@@ -0,0 +1,15 @@
+import { type SearchFilters } from "@anvpx/motion-build";
+import type { Io } from "../types.ts";
+import { type TemplateEnv } from "./env.ts";
+export declare const LIST_MAX_LINES = 15;
+/** Ranked or filtered blueprints shown (one header line on top: 9 lines in all). */
+export declare const BLUEPRINT_ROWS = 8;
+export interface ListRequest {
+    readonly domain: string | undefined;
+    /** `--for` free text. */
+    readonly query: string | undefined;
+    readonly filters: SearchFilters;
+    readonly json: boolean;
+}
+/** `mk template list`: templates, or (with `--for/--tag/--aspect/--sec`) ranked or filtered blueprints. */
+export declare function list(request: ListRequest, env: TemplateEnv, io: Io): Promise<number>;