@horizon36596/zenith-cli 0.1.1

package/dist/commands/sim.js

@@ -0,0 +1,213 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { estimate as coreEstimate, ledger as coreLedger, render as coreRender } from "@horizon36596/zenith-core";
+import { resolveSeason } from "@horizon36596/zenith-seasons";
+import { loadAutoAndPlan, resolveAutoPath } from "../autoLoad.js";
+import { tryCore } from "../coreGate.js";
+import { formatFindingsTable } from "../findings.js";
+import { hostPlatform, resolveLauncher } from "../launcher.js";
+import { confinePath, loadProject, ProjectError } from "../project.js";
+import { buildSimReport, parseTrace, TraceParseError } from "../traceReport.js";
+/**
+ * Splits a command line into argv words the way a POSIX shell would, without ever handing the
+ * string to a shell: single quotes are fully literal, double quotes allow `\"`, `\\`, `` \` `` and
+ * `\$` to escape, and an unquoted backslash escapes the next character. `sim.command` in
+ * `zenith.json` is the team's own string (not attacker input), so this only needs to parse it the
+ * way a person reading it would, not defend against a hostile one; the actual security boundary is
+ * that `{auto}` is substituted in only after `auto.name` has already been validated against
+ * `AUTO_NAME_PATTERN`, so no token it lands in can ever contain a quote, space or shell
+ * metacharacter, and the whole argv array is then spawned with `shell: false`.
+ */
+export function splitShellWords(command) {
+    const words = [];
+    let current = "";
+    let has = false;
+    let i = 0;
+    const push = () => {
+        if (has)
+            words.push(current);
+        current = "";
+        has = false;
+    };
+    while (i < command.length) {
+        const ch = command[i];
+        if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
+            push();
+            i += 1;
+            continue;
+        }
+        if (ch === "'") {
+            has = true;
+            i += 1;
+            while (i < command.length && command[i] !== "'") {
+                current += command[i];
+                i += 1;
+            }
+            i += 1;
+            continue;
+        }
+        if (ch === '"') {
+            has = true;
+            i += 1;
+            while (i < command.length && command[i] !== '"') {
+                const next = command[i];
+                if (next === "\\" && i + 1 < command.length && '"\\$`'.includes(command[i + 1])) {
+                    current += command[i + 1];
+                    i += 2;
+                }
+                else {
+                    current += next;
+                    i += 1;
+                }
+            }
+            i += 1;
+            continue;
+        }
+        if (ch === "\\" && i + 1 < command.length) {
+            current += command[i + 1];
+            i += 2;
+            has = true;
+            continue;
+        }
+        current += ch;
+        has = true;
+        i += 1;
+    }
+    push();
+    return words;
+}
+const pad = (text, width) => (text.length >= width ? text : text + " ".repeat(width - text.length));
+function formatReport(report) {
+    const lines = [];
+    const idWidth = Math.max(2, ...report.steps.map((step) => step.id.length));
+    lines.push(`${pad("step", idWidth)}  nominal s  actual s  delta s  max cross-track in`);
+    for (const step of report.steps) {
+        const nominal = step.estimateNominalS === null ? "–" : step.estimateNominalS.toFixed(2);
+        const delta = step.deltaS === null ? "–" : (step.deltaS >= 0 ? "+" : "") + step.deltaS.toFixed(2);
+        const cross = step.maxCrossTrackIn === null ? "–" : step.maxCrossTrackIn.toFixed(2);
+        const interrupted = step.interrupted ? " (interrupted)" : "";
+        lines.push(`${pad(step.id, idWidth)}  ${pad(nominal, 9)}  ${pad(step.actualS.toFixed(2), 8)}  ${pad(delta, 7)}  ${cross}${interrupted}`);
+    }
+    lines.push("");
+    lines.push(`total: estimate ${report.totalEstimateS === null ? "unknown" : report.totalEstimateS.toFixed(2)} s, actual ${report.totalActualS.toFixed(2)} s`);
+    lines.push(`structure contacts: ${String(report.structureContacts)}, launches: ${String(report.launches)}, held at end: ${report.heldAtEnd === null ? "unknown" : String(report.heldAtEnd)}`);
+    if (Object.keys(report.tips).length > 0) {
+        lines.push(`tips: ${Object.entries(report.tips).map(([alliance, count]) => `${alliance} ${String(count)}`).join(", ")}`);
+    }
+    if (report.inert.length > 0) {
+        lines.push(`not measured by this sim build: ${report.inert.join(", ")} (https://libraries.horizon36596.org/zenith/simulation/)`);
+    }
+    return lines.join("\n");
+}
+/** Runs the sim command and resolves with its exit code and the interleaved output it printed. */
+function runCommand(spawnImpl, launch, cwd, timeoutS) {
+    return new Promise((resolvePromise, reject) => {
+        // No shell: the argv array is spawned directly, so nothing in `command` (or in `{auto}`, which
+        // is substituted in only after auto.name has already been validated) is ever interpreted for
+        // metacharacters, quoting or redirection (finding 1). `resolveLauncher` has already turned a
+        // Gradle wrapper or a Windows batch file into something that starts without one.
+        const child = spawnImpl(launch.file, launch.args, { cwd, shell: false, windowsHide: true });
+        const chunks = [];
+        let timedOut = false;
+        const timer = timeoutS === undefined
+            ? undefined
+            : setTimeout(() => {
+                timedOut = true;
+                child.kill();
+            }, timeoutS * 1000);
+        child.stdout?.on("data", (chunk) => {
+            process.stdout.write(chunk);
+            chunks.push(chunk.toString());
+        });
+        child.stderr?.on("data", (chunk) => {
+            process.stderr.write(chunk);
+            chunks.push(chunk.toString());
+        });
+        child.on("error", (error) => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            reject(error);
+        });
+        child.on("close", (code) => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            resolvePromise({ code: code ?? 1, output: chunks.join(""), timedOut });
+        });
+    });
+}
+/**
+ * `zenith sim <auto> [--open] [--timeout <s>]`: runs `zenith.json.sim.command`, reads the trace it
+ * writes, and prints estimate vs actual per step (site/docs/simulation.md).
+ */
+export async function runSim(autoArg, options) {
+    const cwd = options.cwd ?? process.cwd();
+    const project = loadProject(cwd, options.project, autoArg);
+    const path = resolveAutoPath(cwd, project, autoArg);
+    const result = loadAutoAndPlan(path, project);
+    if (!result.ok) {
+        const files = [{ path: autoArg, findings: result.findings }];
+        process.stdout.write(options.json === true ? `${JSON.stringify({ files }, null, 2)}\n` : `${formatFindingsTable(files)}\n`);
+        return 1;
+    }
+    // loadAutoAndPlan (result.ok) already validated auto.name against AUTO_NAME_PATTERN, so every
+    // {auto} substitution below is guaranteed to contain only [A-Za-z0-9._-] — no path separator, no
+    // ".." segment, and (for the sim command) no shell metacharacter of any kind.
+    const { auto, plan, robot, field, seasonWarnings } = result.loaded;
+    const simConfig = project.link.sim;
+    if (simConfig === undefined) {
+        throw new ProjectError('zenith.json has no "sim" section (command and trace); add one before running zenith sim.');
+    }
+    const argv = splitShellWords(simConfig.command).map((word) => word.split("{auto}").join(auto.name));
+    const tracePath = confinePath(project.root, simConfig.trace.replaceAll("{auto}", auto.name));
+    const launch = resolveLauncher(argv, project.root, options.host ?? hostPlatform());
+    const { code, output, timedOut } = await runCommand(options.spawnFn ?? spawn, launch, project.root, options.timeout);
+    if (code !== 0) {
+        const tail = output.split("\n").slice(-40).join("\n");
+        const reason = timedOut ? `timed out after ${String(options.timeout)} s` : `exit code ${String(code)}`;
+        process.stderr.write(`sim command failed (${reason}):\n${tail}\n`);
+        return 2;
+    }
+    if (!existsSync(tracePath)) {
+        process.stderr.write(`the sim command exited 0 but did not write a trace at ${tracePath}\n`);
+        return 2;
+    }
+    let trace;
+    try {
+        trace = parseTrace(JSON.parse(readFileSync(tracePath, "utf8")));
+    }
+    catch (error) {
+        const message = error instanceof TraceParseError || error instanceof Error ? error.message : String(error);
+        process.stderr.write(`could not read the trace at ${tracePath}: ${message}\n`);
+        return 2;
+    }
+    const estimateOutcome = tryCore(() => coreEstimate(plan, robot));
+    const report = buildSimReport(trace, plan, estimateOutcome.ok ? estimateOutcome.value : null);
+    let renderedPath = null;
+    if (options.open === true) {
+        const ledgerOutcome = tryCore(() => coreLedger(plan, field, resolveSeason(field).rules));
+        const renderOutcome = tryCore(() => coreRender(plan, estimateOutcome.ok ? estimateOutcome.value : null, result.loaded.findings, ledgerOutcome.ok ? ledgerOutcome.value : [], {}));
+        if (renderOutcome.ok) {
+            const relative = `${project.link.autosDir}/.renders/${auto.name}.sim.svg`;
+            const full = confinePath(project.root, relative);
+            mkdirSync(dirname(full), { recursive: true });
+            writeFileSync(full, renderOutcome.value, "utf8");
+            renderedPath = relative;
+        }
+    }
+    if (options.json === true) {
+        process.stdout.write(`${JSON.stringify({ report, estimateAvailable: estimateOutcome.ok, render: renderedPath, seasonWarnings }, null, 2)}\n`);
+    }
+    else {
+        for (const warning of seasonWarnings)
+            process.stderr.write(`warning: ${autoArg}: ${warning}\n`);
+        process.stdout.write(`${formatReport(report)}\n`);
+        if (!estimateOutcome.ok)
+            process.stdout.write(`\n${estimateOutcome.message}\n`);
+        if (options.open === true) {
+            process.stdout.write(renderedPath === null ? "\n--open: render is not available yet (core M1 not landed).\n" : `\nopen: ${renderedPath}\n`);
+        }
+    }
+    return 0;
+}
+//# sourceMappingURL=sim.js.map

package/dist/commands/sim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sim.js","sourceRoot":"","sources":["../../src/commands/sim.ts"],"names":[],"mappings":"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"}

package/dist/commands/validate.d.ts

@@ -0,0 +1,19 @@
+import { type Finding } from "@horizon36596/zenith-core";
+import { type Project } from "../project.js";
+export interface ValidateOptions {
+    json?: boolean;
+    /** Say what each finding code means and how to fix it (`FINDING_HELP`). */
+    explain?: boolean;
+    project?: string;
+    cwd?: string;
+}
+export interface ValidateResult {
+    findings: Finding[];
+    /** Full sentences from `@horizon36596/zenith-seasons` when the field names no plugin this build carries. */
+    seasonWarnings: string[];
+}
+/** One auto's findings, including the schema errors that stop it from being planned at all. */
+export declare function validateAuto(path: string, project: Project): ValidateResult;
+/** `zenith validate <auto...>`: schema plus checks, exit 1 on any error. */
+export declare function runValidate(autos: readonly string[], options: ValidateOptions): number;
+//# sourceMappingURL=validate.d.ts.map

package/dist/commands/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAQL,KAAK,OAAO,EACb,MAAM,2BAA2B,CAAC;AAWnC,OAAO,EAA6B,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAExE,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAgCD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,4GAA4G;IAC5G,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,+FAA+F;AAC/F,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,cAAc,CAmC3E;AAID,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CA+BtF"}

package/dist/commands/validate.js

@@ -0,0 +1,97 @@
+import { isAbsolute, join, relative } from "node:path";
+import { check, estimate, loadAuto, loadField, loadRobot, plan, resolve, } from "@horizon36596/zenith-core";
+import { resolveSeason } from "@horizon36596/zenith-seasons";
+import { SchemaError } from "@horizon36596/zenith-schema";
+import { assertValidAutoName, nearestStepId, resolveAutoPath } from "../autoLoad.js";
+import { countErrors, formatExplanations, formatFindingsTable, helpFor, } from "../findings.js";
+import { loadProject, readJsonFile } from "../project.js";
+const schemaFinding = (stepId, message) => ({
+    severity: "error",
+    stepId,
+    code: "SCHEMA",
+    message,
+});
+/**
+ * An auto may name its own robot or field file; when it does, that file wins over the link file's,
+ * and a broken override is a finding rather than a crash.
+ */
+function override(project, path, load, fallback, findings) {
+    if (path === undefined)
+        return fallback;
+    const full = isAbsolute(path) ? path : join(project.root, path);
+    try {
+        return load(readJsonFile(full));
+    }
+    catch (error) {
+        findings.push(schemaFinding("(file)", `Cannot use ${path}: ${error.message.split("\n")[0] ?? ""}`));
+        return fallback;
+    }
+}
+/** One auto's findings, including the schema errors that stop it from being planned at all. */
+export function validateAuto(path, project) {
+    let json;
+    try {
+        json = readJsonFile(path);
+    }
+    catch (error) {
+        return { findings: [schemaFinding("(file)", error.message)], seasonWarnings: [] };
+    }
+    try {
+        const auto = loadAuto(json);
+        assertValidAutoName(auto.name);
+        const findings = [];
+        const robot = override(project, auto.robot, loadRobot, project.robot, findings);
+        const field = override(project, auto.field, loadField, project.field, findings);
+        const planned = plan(resolve(auto, project.waypoints), robot, field);
+        const season = resolveSeason(field);
+        findings.push(...check(planned, estimate(planned, robot), robot, field, season.rules));
+        return { findings, seasonWarnings: [...season.warnings] };
+    }
+    catch (error) {
+        if (error instanceof SchemaError) {
+            return {
+                findings: error.issues.map((issue) => schemaFinding(issue.path.length === 0 ? "(file)" : nearestStepId(json, issue.path), `${issue.path.join(".")}: ${issue.message}`)),
+                seasonWarnings: [],
+            };
+        }
+        return {
+            findings: [schemaFinding("(file)", error instanceof Error ? error.message : String(error))],
+            seasonWarnings: [],
+        };
+    }
+}
+const slash = (path) => path.split("\\").join("/");
+/** `zenith validate <auto...>`: schema plus checks, exit 1 on any error. */
+export function runValidate(autos, options) {
+    const cwd = options.cwd ?? process.cwd();
+    // `loadProject` itself now walks up from the first auto argument when there is no zenith.json
+    // above the working directory (finding 27) — every verb gets that fallback, not just this one.
+    const project = loadProject(cwd, options.project, autos[0]);
+    const files = autos.map((autoArg) => {
+        const full = resolveAutoPath(cwd, project, autoArg);
+        const result = validateAuto(full, project);
+        return { path: slash(relative(cwd, full)), findings: result.findings, seasonWarnings: result.seasonWarnings };
+    });
+    const errors = countErrors(files);
+    if (options.json === true) {
+        const body = options.explain === true
+            ? { project: slash(project.root), files, errors, help: helpFor(files) }
+            : { project: slash(project.root), files, errors };
+        process.stdout.write(`${JSON.stringify(body, null, 2)}\n`);
+    }
+    else {
+        for (const file of files) {
+            for (const warning of file.seasonWarnings ?? []) {
+                process.stderr.write(`warning: ${file.path}: ${warning}\n`);
+            }
+        }
+        process.stdout.write(`${formatFindingsTable(files)}\n`);
+        if (options.explain === true) {
+            const explained = formatExplanations(files);
+            if (explained.length > 0)
+                process.stdout.write(`${explained}\n`);
+        }
+    }
+    return errors === 0 ? 0 : 1;
+}
+//# sourceMappingURL=validate.js.map

package/dist/commands/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"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"}

package/dist/coreGate.d.ts

@@ -0,0 +1,19 @@
+import { NotImplementedError } from "@horizon36596/zenith-core";
+/**
+ * `core.estimate`, `core.ledger`, `core.render` and `core.diff` throw `NotImplementedError` until
+ * M1 lands. Every verb that calls one of them runs the call through
+ * here so the CLI prints a clear message and exits 2 (usage/IO, since the file itself is fine; the
+ * tool just cannot finish the job yet) instead of a stack trace.
+ */
+export declare const CORE_NOT_LANDED_EXIT_CODE = 2;
+export declare function coreNotLandedMessage(error: NotImplementedError): string;
+export type CoreResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    message: string;
+};
+/** Calls `fn`; catches only `NotImplementedError` and turns it into a `CoreResult`. */
+export declare function tryCore<T>(fn: () => T): CoreResult<T>;
+//# sourceMappingURL=coreGate.d.ts.map

package/dist/coreGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coreGate.d.ts","sourceRoot":"","sources":["../src/coreGate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAEvE;AAED,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpF,uFAAuF;AACvF,wBAAgB,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAOrD"}

package/dist/coreGate.js

@@ -0,0 +1,23 @@
+import { NotImplementedError } from "@horizon36596/zenith-core";
+/**
+ * `core.estimate`, `core.ledger`, `core.render` and `core.diff` throw `NotImplementedError` until
+ * M1 lands. Every verb that calls one of them runs the call through
+ * here so the CLI prints a clear message and exits 2 (usage/IO, since the file itself is fine; the
+ * tool just cannot finish the job yet) instead of a stack trace.
+ */
+export const CORE_NOT_LANDED_EXIT_CODE = 2;
+export function coreNotLandedMessage(error) {
+    return `core M1 not landed yet: ${error.message}`;
+}
+/** Calls `fn`; catches only `NotImplementedError` and turns it into a `CoreResult`. */
+export function tryCore(fn) {
+    try {
+        return { ok: true, value: fn() };
+    }
+    catch (error) {
+        if (error instanceof NotImplementedError)
+            return { ok: false, message: coreNotLandedMessage(error) };
+        throw error;
+    }
+}
+//# sourceMappingURL=coreGate.js.map

package/dist/coreGate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coreGate.js","sourceRoot":"","sources":["../src/coreGate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAE3C,MAAM,UAAU,oBAAoB,CAAC,KAA0B;IAC7D,OAAO,2BAA2B,KAAK,CAAC,OAAO,EAAE,CAAC;AACpD,CAAC;AAID,uFAAuF;AACvF,MAAM,UAAU,OAAO,CAAI,EAAW;IACpC,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC;IACnC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,mBAAmB;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;QACrG,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/fieldImage.d.ts

@@ -0,0 +1,19 @@
+import type { RenderOptions } from "@horizon36596/zenith-core";
+import type { Field } from "@horizon36596/zenith-schema";
+import { type Project } from "./project.js";
+/**
+ * The stored size of a PNG or WebP image in pixels, read from its header, or null for any other
+ * format or a header this does not recognise. Only a `pxBoundsIn` crop needs it.
+ */
+export declare function imageSizePx(bytes: Uint8Array): {
+    widthPx: number;
+    heightPx: number;
+} | null;
+/**
+ * The picture `field.image` names, read for `core.render`, when it is a file inside the project:
+ * `src` relative to the field file. An `app:` image ships with the editor rather than the robot
+ * repository, and a missing file is not an error, so both give `undefined` and the render falls
+ * back to vector (site/docs/editor.md).
+ */
+export declare function fieldImageFor(project: Project, field: Field, fieldPath: string): RenderOptions["fieldImage"] | undefined;
+//# sourceMappingURL=fieldImage.d.ts.map

package/dist/fieldImage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldImage.d.ts","sourceRoot":"","sources":["../src/fieldImage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAe,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAUzD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAqB3F;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,MAAM,GAChB,aAAa,CAAC,YAAY,CAAC,GAAG,SAAS,CAiBzC"}

package/dist/fieldImage.js

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
+import { confinePath } from "./project.js";
+const MIME = {
+    ".png": "image/png",
+    ".webp": "image/webp",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".svg": "image/svg+xml",
+};
+/**
+ * The stored size of a PNG or WebP image in pixels, read from its header, or null for any other
+ * format or a header this does not recognise. Only a `pxBoundsIn` crop needs it.
+ */
+export function imageSizePx(bytes) {
+    const ascii = (from, length) => String.fromCharCode(...bytes.subarray(from, from + length));
+    const u16le = (at) => (bytes[at] ?? 0) | ((bytes[at + 1] ?? 0) << 8);
+    const u24le = (at) => u16le(at) | ((bytes[at + 2] ?? 0) << 16);
+    const u32be = (at) => (((bytes[at] ?? 0) << 24) | ((bytes[at + 1] ?? 0) << 16) | ((bytes[at + 2] ?? 0) << 8) | (bytes[at + 3] ?? 0)) >>> 0;
+    if (ascii(1, 3) === "PNG" && ascii(12, 4) === "IHDR") {
+        return { widthPx: u32be(16), heightPx: u32be(20) };
+    }
+    if (ascii(0, 4) === "RIFF" && ascii(8, 4) === "WEBP") {
+        const chunk = ascii(12, 4);
+        if (chunk === "VP8X")
+            return { widthPx: u24le(24) + 1, heightPx: u24le(27) + 1 };
+        if (chunk === "VP8 ")
+            return { widthPx: u16le(26) & 0x3fff, heightPx: u16le(28) & 0x3fff };
+        if (chunk === "VP8L") {
+            const bits = (bytes[21] ?? 0) | ((bytes[22] ?? 0) << 8) | ((bytes[23] ?? 0) << 16) | ((bytes[24] ?? 0) << 24);
+            return { widthPx: (bits & 0x3fff) + 1, heightPx: ((bits >>> 14) & 0x3fff) + 1 };
+        }
+    }
+    return null;
+}
+/**
+ * The picture `field.image` names, read for `core.render`, when it is a file inside the project:
+ * `src` relative to the field file. An `app:` image ships with the editor rather than the robot
+ * repository, and a missing file is not an error, so both give `undefined` and the render falls
+ * back to vector (site/docs/editor.md).
+ */
+export function fieldImageFor(project, field, fieldPath) {
+    const src = field.image?.src;
+    if (src === undefined || src.startsWith("app:"))
+        return undefined;
+    let full;
+    try {
+        full = confinePath(project.root, join(dirname(fieldPath), src));
+    }
+    catch {
+        return undefined;
+    }
+    const mime = MIME[extname(full).toLowerCase()];
+    if (mime === undefined || !existsSync(full))
+        return undefined;
+    const bytes = readFileSync(full);
+    const size = imageSizePx(bytes);
+    return {
+        href: `data:${mime};base64,${bytes.toString("base64")}`,
+        ...(size === null ? {} : size),
+    };
+}
+//# sourceMappingURL=fieldImage.js.map

package/dist/fieldImage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldImage.js","sourceRoot":"","sources":["../src/fieldImage.ts"],"names":[],"mappings":"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"}

package/dist/findings.d.ts

@@ -0,0 +1,20 @@
+import { type Finding, type FindingCode, type FindingHelp } from "@horizon36596/zenith-core";
+export interface FileFindings {
+    path: string;
+    findings: Finding[];
+    /** Full sentences from `@horizon36596/zenith-seasons` when the file's season plugin is missing or unknown. */
+    seasonWarnings?: readonly string[];
+}
+/** A table a person reads. Every verb also has --json, so an agent never parses this. */
+export declare function formatFindingsTable(files: readonly FileFindings[]): string;
+/** The distinct codes these files raise, in the order they first appear. */
+export declare function codesIn(files: readonly FileFindings[]): FindingCode[];
+/** `FINDING_HELP` for just the codes these files raise, for `validate --explain --json`. */
+export declare const helpFor: (files: readonly FileFindings[]) => Partial<Record<FindingCode, FindingHelp>>;
+/**
+ * `validate --explain`: what each code in the table means and how to fix it, once per code, in
+ * the words the editor shows behind the code chip.
+ */
+export declare function formatExplanations(files: readonly FileFindings[]): string;
+export declare const countErrors: (files: readonly FileFindings[]) => number;
+//# sourceMappingURL=findings.d.ts.map

package/dist/findings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings.d.ts","sourceRoot":"","sources":["../src/findings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE3G,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,8GAA8G;IAC9G,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAKD,yFAAyF;AACzF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CA6B1E;AAED,4EAA4E;AAC5E,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,WAAW,EAAE,CAQrE;AAED,4FAA4F;AAC5F,eAAO,MAAM,OAAO,GAAI,OAAO,SAAS,YAAY,EAAE,KAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC,CACnB,CAAC;AAE/E;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAWzE;AAED,eAAO,MAAM,WAAW,GAAI,OAAO,SAAS,YAAY,EAAE,KAAG,MAI1D,CAAC"}

package/dist/findings.js

@@ -0,0 +1,57 @@
+import { FINDING_HELP } from "@horizon36596/zenith-core";
+const pad = (text, width) => text.length >= width ? text : text + " ".repeat(width - text.length);
+/** A table a person reads. Every verb also has --json, so an agent never parses this. */
+export function formatFindingsTable(files) {
+    const lines = [];
+    for (const file of files) {
+        lines.push(file.path);
+        if (file.findings.length === 0) {
+            lines.push("  no findings");
+        }
+        else {
+            const severityWidth = Math.max(...file.findings.map((finding) => finding.severity.length));
+            const codeWidth = Math.max(...file.findings.map((finding) => finding.code.length));
+            const stepWidth = Math.max(...file.findings.map((finding) => finding.stepId.length));
+            for (const finding of file.findings) {
+                lines.push(`  ${pad(finding.severity, severityWidth)}  ${pad(finding.code, codeWidth)}  ${pad(finding.stepId, stepWidth)}  ${finding.message}`);
+            }
+        }
+    }
+    const errors = files.reduce((sum, file) => sum + file.findings.filter((finding) => finding.severity === "error").length, 0);
+    const warnings = files.reduce((sum, file) => sum + file.findings.filter((finding) => finding.severity === "warning").length, 0);
+    const plural = (count, word) => `${String(count)} ${word}${count === 1 ? "" : "s"}`;
+    lines.push(`${plural(errors, "error")}, ${plural(warnings, "warning")}`);
+    return lines.join("\n");
+}
+/** The distinct codes these files raise, in the order they first appear. */
+export function codesIn(files) {
+    const codes = [];
+    for (const file of files) {
+        for (const finding of file.findings) {
+            if (!codes.includes(finding.code))
+                codes.push(finding.code);
+        }
+    }
+    return codes;
+}
+/** `FINDING_HELP` for just the codes these files raise, for `validate --explain --json`. */
+export const helpFor = (files) => Object.fromEntries(codesIn(files).map((code) => [code, FINDING_HELP[code]]));
+/**
+ * `validate --explain`: what each code in the table means and how to fix it, once per code, in
+ * the words the editor shows behind the code chip.
+ */
+export function formatExplanations(files) {
+    const codes = codesIn(files);
+    if (codes.length === 0)
+        return "";
+    const lines = ["", "What these findings mean"];
+    for (const code of codes) {
+        const help = FINDING_HELP[code];
+        lines.push(`  ${code}: ${help.title}`);
+        lines.push(`    ${help.means}`);
+        lines.push(`    To fix it: ${help.fix}`);
+    }
+    return lines.join("\n");
+}
+export const countErrors = (files) => files.reduce((sum, file) => sum + file.findings.filter((finding) => finding.severity === "error").length, 0);
+//# sourceMappingURL=findings.js.map

package/dist/findings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings.js","sourceRoot":"","sources":["../src/findings.ts"],"names":[],"mappings":"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"}