@anvpx/motion-cli 0.0.0-stage → 0.1.0

package/dist/state/evidence.js

@@ -0,0 +1,243 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { validateStoryboardFull } from "@anvpx/motion-build";
+import { approvalState } from "../approval/approval.js";
+import { defaultOut, previewManifestPath } from "../preview/manifest.js";
+import { checkStoryboard } from "../storyboard/check.js";
+import { readJsonFile } from "../storyboard/load.js";
+import { formatFindings } from "../storyboard/report.js";
+import { RENDER_MANIFEST } from "../workflow/provenance.js";
+/** `<render>/manifest.json`: the build manifest, the only artifact that names its storyboard. */
+const BUILD_MANIFEST = "manifest.json";
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+const NEXT = {
+    storyboard: "preview",
+    previewed: "approval",
+    approved: "render",
+    rendered: "verify",
+    verified: null,
+};
+const previewEvidence = (facts) => {
+    if (facts.previewSha256 === undefined || facts.currentHash === undefined)
+        return "missing";
+    return facts.previewSha256 === facts.currentHash ? "current" : "stale";
+};
+/** Current only when the output holds AND the build manifest attributes it to this storyboard. */
+const renderEvidence = (render, canonical) => {
+    if (render === undefined)
+        return "missing";
+    if (render.diskSha256 !== render.recordedSha256)
+        return "stale";
+    return render.buildStoryboardSha256 === canonical ? "current" : "stale";
+};
+const verifyEvidence = (render, supported) => {
+    if (render === undefined)
+        return "unknown";
+    if (render.verify === "PASS")
+        return supported ? "PASS" : "unknown";
+    return render.verify === "not-run" ? "not-run" : "unknown";
+};
+const renderProblems = (facts, supported) => {
+    const render = facts.render;
+    if (render === undefined)
+        return [];
+    const problems = [];
+    if (render.diskSha256 === undefined) {
+        problems.push({
+            code: "render-output-missing",
+            message: `${render.file} is recorded but not in the render dir`,
+        });
+    }
+    else if (render.diskSha256 !== render.recordedSha256) {
+        problems.push({
+            code: "render-output-mismatch",
+            message: `${render.file} sha256 differs from the render manifest`,
+        });
+    }
+    // Unreadable approval inputs leave the approval state unknown, not "not approved".
+    if (facts.unreadable !== undefined)
+        return problems;
+    if (facts.approval !== "approved") {
+        problems.push({
+            code: "render-unapproved",
+            message: "a render manifest exists without a current approval",
+        });
+    }
+    if (render.verify === "PASS" && !supported) {
+        problems.push({
+            code: "verify-claim-unsupported",
+            message: "verify PASS is recorded but the render evidence does not hold",
+        });
+    }
+    return problems;
+};
+const stateOf = (facts, preview, render, verify) => {
+    const approved = facts.approval === "approved";
+    if (approved && render === "current")
+        return verify === "PASS" ? "verified" : "rendered";
+    if (approved)
+        return "approved";
+    return preview === "current" ? "previewed" : "storyboard";
+};
+/** Derives the state, the next missing artifact and every overclaim from already-read facts. */
+export function deriveState(facts) {
+    const preview = previewEvidence(facts);
+    const render = renderEvidence(facts.render, facts.storyboardCanonicalSha256);
+    const supported = render === "current" && facts.approval === "approved";
+    const verify = verifyEvidence(facts.render, supported);
+    const problems = renderProblems(facts, supported);
+    if (facts.unreadable !== undefined) {
+        problems.push({ code: "inputs-unreadable", message: facts.unreadable });
+    }
+    const state = stateOf(facts, preview, render, verify);
+    const next = NEXT[state];
+    return {
+        state,
+        next,
+        missing: next === null ? [] : [next],
+        problems,
+        evidence: {
+            storyboard: facts.storyboardSha256,
+            preview,
+            approval: facts.approval,
+            render,
+            verify,
+        },
+    };
+}
+const HEX64 = /^[a-f0-9]{64}$/;
+const BASENAME = /^[^\\/]+$/;
+const ABSOLUTE = /(?:[A-Za-z]:)?[\\/][^\s:;,"']+/g;
+/** Keeps an error reason short and machine-independent: no absolute paths. */
+const sanitize = (text) => {
+    const line = text.split("\n")[0] ?? "";
+    return line.replace(ABSOLUTE, "<path>").slice(0, 120);
+};
+const recordedPreviewSha = (value) => {
+    const row = value;
+    if (typeof row !== "object" || row === null)
+        return undefined;
+    const sha = row.inputManifestSha256;
+    return typeof sha === "string" && HEX64.test(sha) ? sha : undefined;
+};
+/** The storyboard a build manifest compiled. Unknown or older shapes are "cannot attribute". */
+const recordedBuildSha = (value) => {
+    const row = value;
+    if (typeof row !== "object" || row === null)
+        return undefined;
+    const sha = row.storyboardSha256;
+    return typeof sha === "string" && HEX64.test(sha) ? sha : undefined;
+};
+/** Present and parsed, absent, or present but unreadable (which exits 2, never "missing"). */
+async function readEvidenceJson(host, path, label) {
+    const loaded = await readJsonFile(path, host);
+    if (loaded.ok)
+        return { kind: "value", value: loaded.value };
+    if (loaded.kind === "syntax" || !(await host.exists(path)))
+        return { kind: "missing" };
+    return { kind: "unreadable", message: `${label} is unreadable` };
+}
+/** A render manifest shape we understand; unknown or older shapes are simply not evidence. */
+async function parseRender(host, dir, value, buildStoryboardSha256) {
+    const row = value;
+    if (typeof row !== "object" || row === null || row.schema !== 1)
+        return undefined;
+    const output = row.output;
+    if (typeof output !== "object" || output === null)
+        return undefined;
+    const file = output.file;
+    const sha = output.sha256;
+    if (typeof file !== "string" || !BASENAME.test(file) || file === "." || file === "..") {
+        return undefined;
+    }
+    if (typeof sha !== "string" || !HEX64.test(sha))
+        return undefined;
+    return {
+        file,
+        recordedSha256: sha,
+        diskSha256: await host.sha256File(join(dir, file)),
+        ...(buildStoryboardSha256 === undefined ? {} : { buildStoryboardSha256 }),
+        verify: typeof row.verify === "string" ? row.verify : "unknown",
+    };
+}
+/** Tolerant by design: an absent or unparsable build manifest means "cannot attribute", not an error. */
+async function readBuildStoryboardSha(host, dir) {
+    const loaded = await readJsonFile(join(dir, BUILD_MANIFEST), host);
+    return loaded.ok ? recordedBuildSha(loaded.value) : undefined;
+}
+const SAME_APPROVAL_FLAGS = "pass the same --assets/--ledger/--audio/--music flags used with `mk approve`";
+async function readApproval(io, storyboard, options) {
+    try {
+        const state = await approvalState(io.host, storyboard, options);
+        return { approval: state.state, currentHash: state.hash };
+    }
+    catch (error) {
+        return {
+            approval: "missing",
+            unreadable: `approval inputs cannot be read: ${sanitize(error.message)}; ${SAME_APPROVAL_FLAGS}`,
+        };
+    }
+}
+async function loadStoryboard(io, storyboard) {
+    const loaded = await readJsonFile(storyboard, io.host);
+    if (!loaded.ok)
+        return { ok: false, message: loaded.message };
+    const report = checkStoryboard(loaded.value);
+    if (report.errors.length > 0) {
+        const findings = formatFindings(report.errors.slice(0, 3));
+        return { ok: false, message: `storyboard is invalid; run \`mk validate\`.\n${findings}` };
+    }
+    const board = validateStoryboardFull(loaded.value);
+    // checkStoryboard ran the same validator; this turns the impossible into a typed refusal.
+    if (!board.ok)
+        return { ok: false, message: "storyboard is invalid; run `mk validate`." };
+    const fileSha256 = await io.host.sha256File(storyboard);
+    if (fileSha256 === undefined)
+        return { ok: false, message: `cannot read ${storyboard}` };
+    // A build hashes `JSON.stringify(board)`: canonical, so whitespace and key order are not identity.
+    return { ok: true, sha256: fileSha256, canonicalSha256: sha256(JSON.stringify(board.value)) };
+}
+async function readPreview(io, storyboard, options) {
+    const out = options.out ?? defaultOut(storyboard);
+    const preview = await readEvidenceJson(io.host, previewManifestPath(out, storyboard), "preview manifest");
+    if (preview.kind === "unreadable")
+        return { ok: false, message: preview.message };
+    const sha256 = preview.kind === "value" ? recordedPreviewSha(preview.value) : undefined;
+    return sha256 === undefined ? { ok: true } : { ok: true, sha256 };
+}
+async function readRender(io, storyboard, options) {
+    const dir = options.render ?? join(defaultOut(storyboard), "project");
+    const json = await readEvidenceJson(io.host, join(dir, RENDER_MANIFEST), "render manifest");
+    if (json.kind === "unreadable")
+        return { ok: false, message: json.message };
+    if (json.kind !== "value")
+        return { ok: true };
+    const buildSha = await readBuildStoryboardSha(io.host, dir);
+    const facts = await parseRender(io.host, dir, json.value, buildSha);
+    return facts === undefined ? { ok: true } : { ok: true, facts };
+}
+/** Reads every artifact once; validation failures and unreadable inputs are exit-2 values. */
+export async function gatherEvidence(io, storyboard, options = {}) {
+    const board = await loadStoryboard(io, storyboard);
+    if (!board.ok)
+        return board;
+    const approval = await readApproval(io, storyboard, options.approval ?? {});
+    const preview = await readPreview(io, storyboard, options);
+    if (!preview.ok)
+        return preview;
+    const render = await readRender(io, storyboard, options);
+    if (!render.ok)
+        return render;
+    return {
+        ok: true,
+        facts: {
+            storyboardSha256: board.sha256,
+            storyboardCanonicalSha256: board.canonicalSha256,
+            approval: approval.approval,
+            ...(approval.currentHash === undefined ? {} : { currentHash: approval.currentHash }),
+            ...(approval.unreadable === undefined ? {} : { unreadable: approval.unreadable }),
+            ...(preview.sha256 === undefined ? {} : { previewSha256: preview.sha256 }),
+            ...(render.facts === undefined ? {} : { render: render.facts }),
+        },
+    };
+}

package/dist/storyboard/check.d.ts

@@ -0,0 +1,21 @@
+import { type LintFinding, type PlatformMarginLookup } from "@anvpx/motion-build";
+export type Finding = LintFinding;
+export interface CheckReport {
+    errors: Finding[];
+    warnings: Finding[];
+    /** Total duration in seconds; present once the storyboard validates. */
+    total?: number;
+    /** Frame size and rate; present once the storyboard validates. */
+    meta?: {
+        width: number;
+        height: number;
+        fps: number;
+    };
+}
+/** A finding about the document itself (path "" is the JSON root). */
+export declare const rootError: (message: string) => Finding;
+/** Schema + per-scene validation, timing resolution and lint (unless `lint: false`), with no side effects. */
+export declare function checkStoryboard(value: unknown, options?: {
+    lint?: boolean;
+    platforms?: PlatformMarginLookup;
+}): CheckReport;

package/dist/storyboard/check.js

@@ -0,0 +1,39 @@
+import { bundledThemeDocs, lintStoryboard, resolveTimeline, sceneWords, tryResolveTheme, validateStoryboardFull, } from "@anvpx/motion-build";
+const asFinding = (error) => ({ severity: "error", ...error });
+/** A finding about the document itself (path "" is the JSON root). */
+export const rootError = (message) => ({ severity: "error", path: "", message });
+const failure = (errors) => ({
+    errors: errors.map(asFinding),
+    warnings: [],
+});
+const themeInput = (name) => {
+    const theme = tryResolveTheme(name, bundledThemeDocs());
+    return theme === undefined ? {} : { theme };
+};
+/** Schema + per-scene validation, timing resolution and lint (unless `lint: false`), with no side effects. */
+export function checkStoryboard(value, options = {}) {
+    const valid = validateStoryboardFull(value);
+    if (!valid.ok)
+        return failure(valid.errors);
+    const board = valid.value;
+    const timeline = resolveTimeline(board);
+    if (!timeline.ok)
+        return failure(timeline.errors);
+    const words = board.scenes.map((scene) => sceneWords(scene.props, scene.type));
+    const lint = options.lint === false
+        ? { errors: [], warnings: [] }
+        : lintStoryboard({
+            storyboard: board,
+            timeline: timeline.value,
+            words,
+            ...themeInput(board.meta.theme),
+            ...(options.platforms === undefined ? {} : { platforms: options.platforms }),
+        });
+    const { width, height, fps } = board.meta;
+    return {
+        errors: [...lint.errors],
+        warnings: [...lint.warnings],
+        total: timeline.value.total,
+        meta: { width, height, fps },
+    };
+}

package/dist/storyboard/containment.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Real-path containment for authored scenes.
+ *
+ * `props.dir` is checked textually by `resolveSceneDir`, but a symlink or NTFS
+ * junction points outside the project while still looking local. Loading such a
+ * scene would read outside files, and hashing it would record them as local
+ * approval inputs. Every path that reaches an authored scene therefore gets a
+ * real-path check; the check fails closed when a real path exists and leaves the
+ * allowed root.
+ *
+ * Fake/off-disk hosts have no realpath: an unresolvable path is treated as "not
+ * escaped" and left to the existing existence checks, because there is nothing
+ * for the real filesystem to resolve.
+ */
+/** True when `target` is strictly inside `root` (not equal, not a sibling prefix). */
+export declare const insideReal: (root: string, target: string) => boolean;
+export interface SceneContainment {
+    /** False when the scene directory itself resolves outside the storyboard directory. */
+    readonly dirInside: boolean;
+    /** Scene-relative files whose real path leaves the scene directory. */
+    readonly escapedFiles: readonly string[];
+}
+/** Real-path containment for a scene directory plus the files it is about to read. */
+export declare const sceneContainment: (storyboardDir: string, sceneDir: string, files: readonly string[]) => SceneContainment;

package/dist/storyboard/containment.js

@@ -0,0 +1,43 @@
+import { realpathSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+/**
+ * Real-path containment for authored scenes.
+ *
+ * `props.dir` is checked textually by `resolveSceneDir`, but a symlink or NTFS
+ * junction points outside the project while still looking local. Loading such a
+ * scene would read outside files, and hashing it would record them as local
+ * approval inputs. Every path that reaches an authored scene therefore gets a
+ * real-path check; the check fails closed when a real path exists and leaves the
+ * allowed root.
+ *
+ * Fake/off-disk hosts have no realpath: an unresolvable path is treated as "not
+ * escaped" and left to the existing existence checks, because there is nothing
+ * for the real filesystem to resolve.
+ */
+/** True when `target` is strictly inside `root` (not equal, not a sibling prefix). */
+export const insideReal = (root, target) => {
+    const rel = relative(root, target);
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+};
+const realPath = (path) => {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Real-path containment for a scene directory plus the files it is about to read. */
+export const sceneContainment = (storyboardDir, sceneDir, files) => {
+    const rootReal = realPath(storyboardDir);
+    const dirReal = realPath(sceneDir);
+    if (rootReal === undefined || dirReal === undefined) {
+        return { dirInside: true, escapedFiles: [] };
+    }
+    const dirInside = insideReal(rootReal, dirReal);
+    const escapedFiles = files.filter((file) => {
+        const fileReal = realPath(join(sceneDir, file));
+        return fileReal !== undefined && !insideReal(dirReal, fileReal);
+    });
+    return { dirInside, escapedFiles };
+};

package/dist/storyboard/custom.d.ts

@@ -0,0 +1,15 @@
+import { type CustomSceneSource, type LintFinding } from "@anvpx/motion-build";
+import type { Host } from "../types.ts";
+/** True when the storyboard references an authored scene; cheap, no disk access. */
+export declare const hasCustomScenes: (board: unknown) => boolean;
+export interface CustomReadResult {
+    /** Authored scene sources by scene id; only the entries that read cleanly. */
+    readonly sources: Readonly<Record<string, CustomSceneSource>>;
+    readonly findings: readonly LintFinding[];
+}
+/**
+ * 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 declare function readCustomScenes(board: unknown, storyboardPath: string, host: Host): Promise<CustomReadResult>;

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`;