@anvpx/motion-cli 0.0.0-stage → 0.1.1

package/dist/fit/solve.js

@@ -0,0 +1,80 @@
+/** Durations are whole tenths of a second internally, so the sum is exact. */
+const TENTHS = 10;
+const EPS = 1e-9;
+const ITERATIONS = 200;
+const MAX_FACTOR = 1e9;
+const clamp = (value, lo, hi) => Math.min(hi, Math.max(lo, value));
+const total = (values) => values.reduce((a, b) => a + b, 0);
+const inTenths = (rows) => {
+    const lo = rows.map((row) => Math.ceil(row.lo * TENTHS - EPS));
+    return {
+        cur: rows.map((row) => row.cur * TENTHS),
+        lo,
+        hi: rows.map((row, i) => Math.max(lo[i] ?? 0, Math.floor(row.hi * TENTHS + EPS))),
+    };
+};
+/** Every scene times one factor, held inside its own range. */
+const scaled = (t, factor) => t.cur.map((cur, i) => clamp(cur * factor, t.lo[i] ?? 0, t.hi[i] ?? 0));
+/** The smallest factor whose scaled total reaches `goal` (the total never decreases with it). */
+function factorFor(t, goal) {
+    let low = 0;
+    let high = 1;
+    while (total(scaled(t, high)) < goal && high < MAX_FACTOR)
+        high *= 2;
+    for (let step = 0; step < ITERATIONS; step++) {
+        const middle = (low + high) / 2;
+        if (total(scaled(t, middle)) < goal)
+            low = middle;
+        else
+            high = middle;
+    }
+    return high;
+}
+/** The scene's duration moved by `step` tenths, or undefined when that leaves its range. */
+const shifted = (t, whole, i, step) => {
+    const next = (whole[i] ?? 0) + step;
+    return next >= (t.lo[i] ?? 0) && next <= (t.hi[i] ?? 0) ? next : undefined;
+};
+/** One pass over `order`, moving scenes one tenth towards the goal; returns what is still missing. */
+function handOut(t, whole, order, missing) {
+    let left = missing;
+    for (const i of order) {
+        const next = left === 0 ? undefined : shifted(t, whole, i, Math.sign(left));
+        if (next === undefined)
+            continue;
+        whole[i] = next;
+        left -= Math.sign(left);
+    }
+    return left;
+}
+/**
+ * Rounds down to whole tenths, then hands the remainder out one tenth at a time: to the scenes
+ * with the largest fractional part first (ties: first scene), or taken back from the smallest.
+ */
+function distribute(t, real, goal) {
+    const whole = real.map((value, i) => clamp(Math.floor(value + EPS), t.lo[i] ?? 0, t.hi[i] ?? 0));
+    const fraction = real.map((value, i) => value - (whole[i] ?? 0));
+    const byFraction = [...whole.keys()].sort((a, b) => (fraction[b] ?? 0) - (fraction[a] ?? 0) || a - b);
+    let missing = goal - total(whole);
+    const order = missing > 0 ? byFraction : [...byFraction].reverse();
+    for (let pass = 0; missing !== 0 && pass < real.length * 2; pass++) {
+        missing = handOut(t, whole, order, missing);
+    }
+    return whole;
+}
+/**
+ * Scales every scene by one common factor, clamped to each scene's [lo, hi], so the durations
+ * add up to `targetSum` seconds (to 0.1 s). Deterministic: bisection on the factor, then the
+ * rounding remainder is distributed by largest fractional part.
+ */
+export function fitDurations(rows, targetSum) {
+    const t = inTenths(rows);
+    const goal = Math.round(targetSum * TENTHS);
+    const range = { min: total(t.lo) / TENTHS, max: total(t.hi) / TENTHS };
+    if (goal < total(t.lo))
+        return { ok: false, reason: "below", ...range };
+    if (goal > total(t.hi))
+        return { ok: false, reason: "above", ...range };
+    const whole = distribute(t, scaled(t, factorFor(t, goal)), goal);
+    return { ok: true, seconds: whole.map((value) => value / TENTHS) };
+}

package/dist/fit/target.d.ts

@@ -0,0 +1,18 @@
+export type FitTarget = {
+    readonly ok: true;
+    readonly target: number;
+    readonly from: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * The fit target in seconds: either `--seconds`, or a bar count at a tempo
+ * (`bars * 4 * 60 / bpm`, i.e. 4/4). Tempo is a first-class authoring unit in the
+ * reference corpus, so the CLI can take bars instead of doing the arithmetic by hand.
+ */
+export declare const fitTarget: (flags: {
+    readonly seconds?: string;
+    readonly bpm?: string;
+    readonly bars?: string;
+}) => FitTarget;

package/dist/fit/target.js

@@ -0,0 +1,47 @@
+/** Beats in a bar at 4/4; the only time signature the engine assumes. */
+const BEATS_PER_BAR = 4;
+const SECONDS_PER_MINUTE = 60;
+const positive = (text) => {
+    const value = Number(text);
+    return text !== undefined && Number.isFinite(value) && value > 0 ? value : undefined;
+};
+const round1 = (value) => Math.round(value * 10) / 10;
+/**
+ * The fit target in seconds: either `--seconds`, or a bar count at a tempo
+ * (`bars * 4 * 60 / bpm`, i.e. 4/4). Tempo is a first-class authoring unit in the
+ * reference corpus, so the CLI can take bars instead of doing the arithmetic by hand.
+ */
+export const fitTarget = (flags) => {
+    const seconds = positive(flags.seconds);
+    const bpm = positive(flags.bpm);
+    const bars = positive(flags.bars);
+    if (seconds !== undefined && (bpm !== undefined || bars !== undefined)) {
+        return { ok: false, message: "use --seconds or --bpm/--bars, not both" };
+    }
+    if (flags.seconds !== undefined && seconds === undefined) {
+        return { ok: false, message: "--seconds needs a positive number" };
+    }
+    if (seconds !== undefined)
+        return { ok: true, target: seconds, from: "seconds" };
+    if (flags.bpm !== undefined && bpm === undefined) {
+        return { ok: false, message: "--bpm needs a positive number" };
+    }
+    if (flags.bars !== undefined && bars === undefined) {
+        return { ok: false, message: "--bars needs a positive number" };
+    }
+    if (bpm === undefined && bars === undefined) {
+        return { ok: false, message: "--seconds needs a positive number" };
+    }
+    if (bpm === undefined || bars === undefined) {
+        return { ok: false, message: "--bpm and --bars go together" };
+    }
+    if (bpm < 30 || bpm > 300)
+        return { ok: false, message: "--bpm must be between 30 and 300" };
+    if (bars < 1 || bars > 400)
+        return { ok: false, message: "--bars must be between 1 and 400" };
+    return {
+        ok: true,
+        target: round1((bars * BEATS_PER_BAR * SECONDS_PER_MINUTE) / bpm),
+        from: `${bars} bars at ${bpm} BPM`,
+    };
+};

package/dist/generate3d/command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "../types.ts";
+export declare const generate3dCommand: Command;
+export declare const makeGenerate3dCommand: () => Command;

package/dist/generate3d/command.js

@@ -0,0 +1,38 @@
+import { parseFlags, requirePositional, textFlag, usageError } from "../args.js";
+import { runGenerate3d } from "./run.js";
+const USAGE = `mk generate-3d <image> --out <model.glb> [--python <bin>]
+
+Generate a 3D model from a single image via the triposr backend and validate it.
+Calls the audio triposr adapter, checks the GLB with the optimize-model validator,
+then writes the model plus licences-style generate-3d-provenance.json next to it.
+No venv/model: fails closed with a doctor hint, never a silent fallback.
+  --out <model.glb>   output model path (required)
+  --python <bin>      explicit venv python (skips the probe)
+`;
+const FLAGS = {
+    out: { type: "string" },
+    python: { type: "string" },
+};
+const NAME = "generate-3d";
+export const generate3dCommand = {
+    name: NAME,
+    summary: "generate a validated GLB model from an image via the triposr backend",
+    async run(args, io) {
+        const parsed = parseFlags(NAME, USAGE, args, FLAGS, io);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const image = requirePositional(NAME, USAGE, parsed.positionals, "<image>", io);
+        if (typeof image !== "string")
+            return image.code;
+        const out = textFlag(parsed.flags, "out");
+        if (out === undefined || out.trim() === "") {
+            return usageError(NAME, USAGE, "--out <model.glb> is required", io).code;
+        }
+        const python = textFlag(parsed.flags, "python");
+        return runGenerate3d(image, {
+            outPath: out,
+            ...(python === undefined ? {} : { python }),
+        }, io);
+    },
+};
+export const makeGenerate3dCommand = () => generate3dCommand;

package/dist/generate3d/run.d.ts

@@ -0,0 +1,39 @@
+import type { Io, Runner } from "../types.ts";
+/**
+ * Triposr port (adapter-agnostic).
+ *
+ * Real adapter lives in the audio package and is re-exported
+ * from `@anvpx/motion-audio`. This file keeps the CLI-side port types against
+ * the agreed spec:
+ * `generate3d(image, outGlb) -> { status: ok|missing|unknown, hint?, glbPath? }`.
+ * The default wires the real adapter with a shape-preserving mapping
+ * (adapter owns model pins; the CLI never hardcodes model ids).
+ */
+export type Generate3dStatus = "ok" | "missing" | "unknown";
+export type Generate3dResult = {
+    status: "ok";
+    glbPath: string;
+} | {
+    status: "missing" | "unknown";
+    hint: string;
+};
+export interface Generate3dRequest {
+    image: string;
+    outGlb: string;
+    python?: string;
+}
+export type Generate3dFn = (run: Runner, req: Generate3dRequest) => Promise<Generate3dResult>;
+export interface Generate3dOptions {
+    outPath: string;
+    python?: string;
+}
+export interface Generate3dDeps {
+    generate3d?: Generate3dFn;
+}
+export declare const provenancePathFor: (outGlb: string) => string;
+/**
+ * Run the triposr adapter, validate the GLB via the optimize-model validator,
+ * and write licences-style provenance next to the output. Resolves to the
+ * process exit code; fails closed (127 missing, 1 unknown/invalid).
+ */
+export declare function runGenerate3d(image: string, options: Generate3dOptions, io: Io, deps?: Generate3dDeps): Promise<number>;

package/dist/generate3d/run.js

@@ -0,0 +1,77 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { generate3d as generate3dAdapter } from "@anvpx/motion-audio";
+import { EXIT } from "../exit-codes.js";
+import { validateGlb } from "../optimize/command.js";
+const doctorHint = "Run `mk doctor` for the generate-3d setup steps.";
+/** Default: real TripoSR adapter with a shape-preserving result mapping. */
+const defaultGenerate3d = async (run, req) => {
+    const result = await generate3dAdapter(run, req);
+    if (result.ok)
+        return { status: "ok", glbPath: result.outGlb };
+    return { status: result.status, hint: result.hint };
+};
+export const provenancePathFor = (outGlb) => join(dirname(outGlb), "generate-3d-provenance.json");
+const readGlbBytes = async (host, path) => {
+    try {
+        const buf = await readFile(path);
+        return { bytes: new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength) };
+    }
+    catch {
+        // In-memory fakes (tests) fall through to Host.
+    }
+    try {
+        const text = await host.readText(path);
+        return { bytes: Uint8Array.from(Buffer.from(text, "binary")) };
+    }
+    catch {
+        return { message: `cannot read "${path}"` };
+    }
+};
+/**
+ * Run the triposr adapter, validate the GLB via the optimize-model validator,
+ * and write licences-style provenance next to the output. Resolves to the
+ * process exit code; fails closed (127 missing, 1 unknown/invalid).
+ */
+export async function runGenerate3d(image, options, io, deps = {}) {
+    const exists = await io.host.exists(image).catch(() => false);
+    if (!exists) {
+        io.stderr(`mk generate-3d: cannot read "${image}"\n`);
+        return EXIT.USAGE;
+    }
+    const generate3d = deps.generate3d ?? defaultGenerate3d;
+    const outGlb = options.outPath;
+    const result = await generate3d(io.run, {
+        image,
+        outGlb,
+        ...(options.python === undefined ? {} : { python: options.python }),
+    });
+    if (result.status === "missing") {
+        io.stderr(`mk generate-3d: ${result.hint}\n${doctorHint}\n`);
+        return EXIT.MISSING_TOOL;
+    }
+    if (result.status !== "ok") {
+        io.stderr(`mk generate-3d: ${result.hint}\n`);
+        return EXIT.ERROR;
+    }
+    const read = await readGlbBytes(io.host, outGlb);
+    if ("message" in read) {
+        io.stderr(`mk generate-3d: ${read.message}\n`);
+        return EXIT.ERROR;
+    }
+    const checked = validateGlb(read.bytes);
+    if (!checked.ok) {
+        io.stderr(`mk generate-3d: refusing invalid model: ${checked.message}\n`);
+        return EXIT.ERROR;
+    }
+    const provenance = {
+        tool: "generate-3d",
+        backend: "triposr",
+        image,
+        out: outGlb,
+        bytes: checked.bytes,
+    };
+    await io.host.writeTextAtomic(provenancePathFor(outGlb), `${JSON.stringify(provenance, null, 2)}\n`);
+    io.stdout(`generate-3d ok | ${checked.bytes} bytes | ${outGlb}\n`);
+    return EXIT.OK;
+}

package/dist/icon/command.d.ts

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

package/dist/icon/command.js

@@ -0,0 +1,113 @@
+import { iconGroups, listIcons, searchIconNames } from "@anvpx/motion-build";
+import { parseFlags, textFlag, usageError } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+const USAGE = `mk icon search <query> | list [--tag <group|keyword>] [--json]
+
+Icon names for the \`icon\` props of icon-grid, bullets, steps, ... (names only; unknown names fail \`mk validate\`).
+  search q       icons whose name, keyword or group contains every word of q, ranked exact > prefix > word-part > substring, then A-Z
+  list           the groups with their icon counts
+  list --tag t   the names in group or keyword t (case-insensitive, trimmed)
+  --json         one JSON line (array of names; list without --tag gives group names)
+`;
+const FLAGS = { tag: { type: "string" }, json: { type: "boolean" } };
+const MAX_NAMES = 60;
+const WIDTH = 100;
+/** Tier for one query token against a lowercased icon name (lower is better). */
+function tier(nameLower, token) {
+    if (nameLower === token)
+        return 0;
+    if (nameLower.startsWith(token))
+        return 1;
+    if (nameLower.includes(`-${token}`))
+        return 2;
+    if (nameLower.includes(token))
+        return 3;
+    return 4;
+}
+/** Relevance score for one icon name (lower is better). */
+function relevanceScore(dashed, tokens, nameLower) {
+    const exact = nameLower === dashed ? 0 : 1;
+    const parts = tokens.reduce((sum, t) => sum + tier(nameLower, t), 0);
+    return exact * 100 + parts;
+}
+/** Re-rank library hits (alphabetical) by relevance; ties stay alphabetical. */
+function rankNames(query, names) {
+    const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const dashed = tokens.join("-");
+    const scored = names.map((name) => ({
+        name,
+        lower: name.toLowerCase(),
+        score: relevanceScore(dashed, tokens, name.toLowerCase()),
+    }));
+    scored.sort((a, b) => (a.score !== b.score ? a.score - b.score : a.lower < b.lower ? -1 : 1));
+    return scored.map((s) => s.name);
+}
+/** Names joined by spaces, wrapped at WIDTH columns, at most MAX_NAMES of them. */
+function wrap(names) {
+    const rows = [];
+    let row = "";
+    for (const name of names.slice(0, MAX_NAMES)) {
+        if (row !== "" && row.length + 1 + name.length > WIDTH) {
+            rows.push(row);
+            row = name;
+        }
+        else {
+            row = row === "" ? name : `${row} ${name}`;
+        }
+    }
+    if (row !== "")
+        rows.push(row);
+    if (names.length > MAX_NAMES)
+        rows.push(`(+${names.length - MAX_NAMES} more; narrow the query)`);
+    return `${rows.join("\n")}\n`;
+}
+const emit = (io, names, json, header) => {
+    io.stdout(json ? `${JSON.stringify(names)}\n` : `${header}\n${wrap(names)}`);
+    return EXIT.OK;
+};
+function search(positionals, json, io) {
+    const query = positionals.join(" ").trim();
+    if (query === "")
+        return usageError("icon", USAGE, "search needs a query", io).code;
+    const names = rankNames(query, searchIconNames(query));
+    if (names.length === 0 && !json) {
+        io.stdout(`no icon matches "${query}"; try one word, or \`mk icon list\` for the groups\n`);
+        return EXIT.OK;
+    }
+    return emit(io, names, json, `${names.length} icons for "${query}":`);
+}
+function list(tag, json, io) {
+    const groups = iconGroups();
+    const clean = tag === undefined ? undefined : tag.trim();
+    if (clean === undefined) {
+        if (json) {
+            io.stdout(`${JSON.stringify(groups.map((g) => g.group))}\n`);
+            return EXIT.OK;
+        }
+        const row = groups.map((g) => `${g.group} (${g.count})`).join(", ");
+        io.stdout(`groups: ${row}\nnext: mk icon list --tag <group> | mk icon search <query>\n`);
+        return EXIT.OK;
+    }
+    const names = listIcons(clean);
+    if (names.length === 0) {
+        const known = groups.map((g) => g.group).join("|");
+        return usageError("icon", USAGE, `unknown tag "${clean}"; groups: ${known}`, io).code;
+    }
+    return emit(io, names, json, `${names.length} icons tagged "${clean}":`);
+}
+export const iconCommand = {
+    name: "icon",
+    summary: "find icon names for scene props: search <query> | list [--tag group|keyword] [--json]",
+    async run(args, io) {
+        const parsed = parseFlags("icon", USAGE, args, FLAGS, io);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const [action, ...rest] = parsed.positionals;
+        const json = parsed.flags.json === true;
+        if (action === "search")
+            return search(rest, json, io);
+        if (action === "list")
+            return list(textFlag(parsed.flags, "tag"), json, io);
+        return usageError("icon", USAGE, "action must be search|list", io).code;
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { approveCommand } from "./approval/command.ts";
+export { catalogCommand } from "./catalog/command.ts";
+export { runCli } from "./cli.ts";
+export { COMMANDS } from "./commands.ts";
+export { contactCommand } from "./contact/command.ts";
+export { CHECKS } from "./doctor/checks.ts";
+export { doctorCommand } from "./doctor/command.ts";
+export { PIN_KEYS, readPins } from "./doctor/pins.ts";
+export type { Check, CheckResult, CheckStatus, Pins } from "./doctor/types.ts";
+export { previewCommand } from "./preview/command.ts";
+export { templateCommand } from "./template/command.ts";
+export { newCommand } from "./template/new.ts";
+export type { Command, CommandResult, Host, Io, Runner, RunOptions } from "./types.ts";
+export { buildCommand } from "./workflow/build.ts";
+export { draftCommand } from "./workflow/draft.ts";
+export { renderCommand } from "./workflow/render.ts";
+export { stillCommand } from "./workflow/still.ts";
+export { validateCommand } from "./workflow/validate.ts";

package/dist/index.js

@@ -0,0 +1,16 @@
+export { approveCommand } from "./approval/command.js";
+export { catalogCommand } from "./catalog/command.js";
+export { runCli } from "./cli.js";
+export { COMMANDS } from "./commands.js";
+export { contactCommand } from "./contact/command.js";
+export { CHECKS } from "./doctor/checks.js";
+export { doctorCommand } from "./doctor/command.js";
+export { PIN_KEYS, readPins } from "./doctor/pins.js";
+export { previewCommand } from "./preview/command.js";
+export { templateCommand } from "./template/command.js";
+export { newCommand } from "./template/new.js";
+export { buildCommand } from "./workflow/build.js";
+export { draftCommand } from "./workflow/draft.js";
+export { renderCommand } from "./workflow/render.js";
+export { stillCommand } from "./workflow/still.js";
+export { validateCommand } from "./workflow/validate.js";

package/dist/install-mk.d.ts

@@ -0,0 +1,31 @@
+import type { Command } from "./types.ts";
+/** Default install directory for the empty-consumer proof (no workspace fallback). */
+export declare const INSTALL_MK_DEFAULT_OUT = "motion-kit-pack";
+/** Manifest written beside the copied pack so consumers can verify bytes. */
+export declare const INSTALL_MK_MANIFEST = "install.json";
+export type InstallMkSource = {
+    kind: "file-path";
+    path: string;
+} | {
+    kind: "registry";
+    name: "current";
+};
+export interface InstallMkFailure {
+    error: string;
+}
+/** File-path first, registry fallback stub. Only the unversioned current name is accepted. */
+export declare function resolveInstallMkSource(opts: {
+    from?: string;
+    name?: string;
+}): InstallMkSource | InstallMkFailure;
+/**
+ * Normalize-and-constrain traversal guard: reject NUL bytes and any `..`
+ * path segment before touching the host, so `../evil` can never escape the
+ * install directory. Both the source path and the destination directory are
+ * constrained; the copied file name is always the source basename joined
+ * under the normalized out dir.
+ */
+export declare function isTraversalPath(value: string): boolean;
+/** File-path installs copy + manifest + SHA-verify; registry name stubs fail closed with a hint. */
+export declare const makeInstallMkCommand: () => Command;
+export declare const installMkCommand: Command;

package/dist/install-mk.js

@@ -0,0 +1,168 @@
+import { createHash } from "node:crypto";
+import { join, normalize } from "node:path";
+import { parseFlags, textFlag, usageError } from "./args.js";
+import { EXIT } from "./exit-codes.js";
+const USAGE = `mk install-mk [--from <path>] [--out <dir>] [current]
+
+Install the smallest single-scene current pack.
+  --from <path>   file path to a pack storyboard (takes priority)
+  --out <dir>     install directory (default motion-kit-pack)
+  current         registry stub name (unavailable in skeleton; use --from <path>)
+Alias: mk install [--from <path>] [--out <dir>] behaves the same as mk install-mk.
+`;
+const FLAGS = { from: { type: "string" }, out: { type: "string" } };
+/** Default install directory for the empty-consumer proof (no workspace fallback). */
+export const INSTALL_MK_DEFAULT_OUT = "motion-kit-pack";
+/** Manifest written beside the copied pack so consumers can verify bytes. */
+export const INSTALL_MK_MANIFEST = "install.json";
+/** File-path first, registry fallback stub. Only the unversioned current name is accepted. */
+export function resolveInstallMkSource(opts) {
+    if (opts.from !== undefined && opts.from !== "") {
+        if (opts.from.includes("@"))
+            return { error: "versioned names not supported (current only)" };
+        return { kind: "file-path", path: opts.from };
+    }
+    const name = opts.name;
+    if (name === undefined || name === "" || name === "current")
+        return { kind: "registry", name: "current" };
+    if (name.includes("@"))
+        return { error: "versioned names not supported (current only)" };
+    return {
+        error: `unknown pack "${name}" (only "current" supported; use --from <path> for file paths)`,
+    };
+}
+function isSingleScenePack(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const scenes = value.scenes;
+    return Array.isArray(scenes) && scenes.length === 1;
+}
+/**
+ * Normalize-and-constrain traversal guard: reject NUL bytes and any `..`
+ * path segment before touching the host, so `../evil` can never escape the
+ * install directory. Both the source path and the destination directory are
+ * constrained; the copied file name is always the source basename joined
+ * under the normalized out dir.
+ */
+export function isTraversalPath(value) {
+    if (value.includes("\0"))
+        return true;
+    return value.split(/[\\/]/).some((segment) => segment === "..");
+}
+function safeBasename(path) {
+    const base = path
+        .split(/[\\/]/)
+        .filter((part) => part !== "")
+        .pop();
+    if (base === undefined || base === "" || base === "." || base === "..")
+        return undefined;
+    if (base.includes("\0"))
+        return undefined;
+    return base;
+}
+async function installFromPath(io, path, outDir) {
+    if (isTraversalPath(path)) {
+        io.stderr(`mk install-mk: refusing traversal path at ${path}\n`);
+        return EXIT.ERROR;
+    }
+    if (isTraversalPath(outDir)) {
+        io.stderr(`mk install-mk: refusing traversal output directory at ${outDir}\n`);
+        return EXIT.ERROR;
+    }
+    const base = safeBasename(path);
+    if (base === undefined) {
+        io.stderr(`mk install-mk: refusing traversal path at ${path}\n`);
+        return EXIT.ERROR;
+    }
+    if (!(await io.host.exists(path))) {
+        io.stderr(`mk install-mk: cannot read pack file at ${path}\n`);
+        return EXIT.ERROR;
+    }
+    let text;
+    try {
+        text = await io.host.readText(path);
+    }
+    catch {
+        io.stderr(`mk install-mk: cannot read pack file at ${path}\n`);
+        return EXIT.ERROR;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        io.stderr("mk install-mk: pack file is not valid JSON\n");
+        return EXIT.ERROR;
+    }
+    if (!isSingleScenePack(parsed)) {
+        io.stderr("mk install-mk: expected the smallest single-scene current pack\n");
+        return EXIT.ERROR;
+    }
+    const sha256 = createHash("sha256").update(text, "utf8").digest("hex");
+    const destDir = normalize(outDir);
+    const destFile = join(destDir, base);
+    const manifestPath = join(destDir, INSTALL_MK_MANIFEST);
+    try {
+        await io.host.copyFile(path, destFile);
+    }
+    catch {
+        io.stderr(`mk install-mk: cannot copy pack file to ${destFile}\n`);
+        return EXIT.ERROR;
+    }
+    const manifest = `${JSON.stringify({
+        command: "install-mk",
+        alias: "mk install",
+        source: path,
+        file: destFile,
+        sha256,
+        scenes: 1,
+        name: "current",
+    }, null, 2)}\n`;
+    try {
+        await io.host.writeTextAtomic(manifestPath, manifest);
+    }
+    catch {
+        io.stderr(`mk install-mk: cannot write manifest at ${manifestPath}\n`);
+        return EXIT.ERROR;
+    }
+    const copiedSha = await io.host.sha256File(destFile);
+    if (copiedSha !== sha256) {
+        io.stderr(`mk install-mk: SHA mismatch after copy to ${destFile}\n`);
+        return EXIT.ERROR;
+    }
+    io.stdout(`install-mk 1 scene -> ${destFile} (sha256 ${sha256.slice(0, 12)})\n`);
+    return EXIT.OK;
+}
+function toInstallTarget(positionals, flags, io) {
+    const [name, ...extra] = positionals;
+    if (extra.length > 0)
+        return { exit: usageError("install-mk", USAGE, `unexpected argument "${extra[0]}"`, io).code };
+    const resolved = resolveInstallMkSource({ from: textFlag(flags, "from"), name });
+    if ("error" in resolved)
+        return { exit: usageError("install-mk", USAGE, resolved.error, io).code };
+    if (resolved.kind === "registry")
+        return { registry: true };
+    const outFlag = textFlag(flags, "out");
+    if (outFlag !== undefined && outFlag === "")
+        return { exit: usageError("install-mk", USAGE, "--out needs a directory", io).code };
+    return { path: resolved.path, outDir: outFlag ?? INSTALL_MK_DEFAULT_OUT };
+}
+/** File-path installs copy + manifest + SHA-verify; registry name stubs fail closed with a hint. */
+export const makeInstallMkCommand = () => ({
+    name: "install-mk",
+    summary: "install the smallest single-scene current pack from a file path (alias: mk install)",
+    async run(args, io) {
+        const parsed = parseFlags("install-mk", USAGE, args, FLAGS, io);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const target = toInstallTarget(parsed.positionals, parsed.flags, io);
+        if ("exit" in target)
+            return target.exit;
+        if ("registry" in target) {
+            io.stderr('mk install-mk: registry "current" unavailable in skeleton; provide --from <path>\n');
+            return EXIT.ERROR;
+        }
+        return installFromPath(io, target.path, target.outDir);
+    },
+});
+export const installMkCommand = makeInstallMkCommand();

package/dist/integration/preview.integration.d.ts

@@ -0,0 +1 @@
+export {};