omkit 0.8.9 → 0.8.11

package/dist/core/ActionRun.d.ts

@@ -3,7 +3,7 @@ import type { ActionRef } from "../foundation/ActionRef.ts";
 import type { LogStore } from "../output/log/LogStore.ts";
 import type { SnapshotStore } from "../output/snapshot/SnapshotStore.ts";
 import type { ArtifactStore } from "../output/artifact/ArtifactStore.ts";
-import type { Activity, Exec, InstanceEvents, NodeStatus } from "./types.ts";
+import type { ActionMeta, Activity, Exec, InstanceEvents, NodeStatus } from "./types.ts";
 /** Everything a node needs to exist, minus its behavior. */
 export interface NodeInit {
     readonly store: LogStore;
@@ -45,6 +45,8 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     readonly path: string;
     readonly parentId: string | null;
     readonly tags: string[];
+    /** What the definition said about itself (`.describe()`, `.mcp()`, `.args()`); for the record. */
+    meta: ActionMeta | undefined;
     /** The captured args this node ran with (for the log header); set at run start. */
     args: readonly unknown[];
     readonly children: ActionRun[];

package/dist/core/ActionRun.js

@@ -18,6 +18,8 @@ export class ActionRun {
     path;
     parentId;
     tags = [];
+    /** What the definition said about itself (`.describe()`, `.mcp()`, `.args()`); for the record. */
+    meta;
     /** The captured args this node ran with (for the log header); set at run start. */
     args = [];
     children = [];

package/dist/core/ExecutionTree.d.ts

@@ -22,6 +22,8 @@ export declare class ExecutionTree {
     readonly store: LogStore;
     readonly folder: RunFolder;
     readonly root: ActionRun;
+    /** The om's name, as given to `om(name)`. */
+    readonly name: string;
     /**
      * The om's `.describe(…)` summary, carried here from the builder so it survives the
      * terminal `.run(...)` call. Stored so it is retrievable; nothing reads it yet.
@@ -39,6 +41,7 @@ export declare class ExecutionTree {
     private readonly snapshotStore;
     private readonly artifactStore;
     private readonly registry;
+    private readonly schemaCache;
     private readonly unsettled;
     private readonly originalLog;
     private streaming;
@@ -99,6 +102,12 @@ export declare class ExecutionTree {
     private printSummary;
     private verdictOk;
     private nodeView;
+    /**
+     * The node's self-description, projected for the record. The root's comes from the om
+     * builder; a child's from its action definition. The args schema is converted here, once per
+     * definition, so a step launched a thousand times converts its schema once.
+     */
+    private metaView;
     /** Test seam: the projected run view (same object written to result.json). */
     runViewForTest(): RunView;
     /** Test seam: the run's curated artifacts. */
@@ -122,6 +131,8 @@ export declare class ExecutionTree {
      * artifact name is free-form, so any printable separator can be forged inside a key.
      */
     private curatedArtifacts;
+    /** {@link curatedArtifacts}, each still carrying the node that registered it (for the report). */
+    private curatedArtifactsWithNode;
     /**
      * Absolute `.log` path for a node — root is `main.log`, children drop the `main/`
      * prefix. One directory level per ancestor, mirroring the tree.

package/dist/core/ExecutionTree.js

@@ -13,6 +13,7 @@ import { LiveRenderer } from "../output/LiveRenderer.js";
 import { writeNodeLogs } from "../output/writers/NodeLogWriter.js";
 import { writeRollup } from "../output/writers/RollupWriter.js";
 import { writeResult } from "../output/writers/ResultWriter.js";
+import { writeReport } from "../output/writers/ReportWriter.js";
 import { ActionRun } from "./ActionRun.js";
 import { procRegistry } from "../system/proc.js";
 import { currentNode } from "./context.js";
@@ -41,6 +42,8 @@ export class ExecutionTree {
     store = new LogStore();
     folder;
     root;
+    /** The om's name, as given to `om(name)`. */
+    name;
     /**
      * The om's `.describe(…)` summary, carried here from the builder so it survives the
      * terminal `.run(...)` call. Stored so it is retrievable; nothing reads it yet.
@@ -58,6 +61,7 @@ export class ExecutionTree {
     snapshotStore;
     artifactStore = new ArtifactStore();
     registry = [];
+    schemaCache = new Map();
     unsettled = new Set();
     originalLog = console.log.bind(console);
     streaming;
@@ -84,6 +88,7 @@ export class ExecutionTree {
     onUncaught = (e) => this.onFatal("uncaughtException", e);
     onUnhandled = (e) => this.onFatal("unhandledRejection", e);
     constructor(name, definedAt, description, mcp) {
+        this.name = name;
         this.description = description;
         this.mcp = mcp;
         // The run's identity: its name + where om() is written (not how it was launched),
@@ -133,6 +138,7 @@ export class ExecutionTree {
             // into the parent's log, attributed to this child's id.
             bubble: (message) => this.append(parent, "child", id, message),
         });
+        node.meta = spec.meta;
         parent.children.push(node);
         this.registry.push(node);
         // Launch reference — the parent's pointer to the child's own (absolute) log, plus where
@@ -307,7 +313,22 @@ export class ExecutionTree {
         await writeRollup(at("asserts.log"), flat, entries, (e) => e.level === "assert", assertSummary);
         await writeRollup(at("snapshots.log"), flat, entries, (e) => e.level === "snapshot");
         await writeRollup(at("artifacts.log"), flat, entries, (e) => e.level === "artifact");
-        await writeResult(at("result.json"), this.runView());
+        const run = this.runView();
+        await writeResult(at("result.json"), run);
+        // The page is a convenience over the record above — a failure to build it must not
+        // cost the run its verdict, its exit code, or its other files.
+        try {
+            await writeReport(at("report.html"), {
+                name: this.name,
+                folder: this.folder.path(),
+                run,
+                entries,
+                artifacts: this.curatedArtifactsWithNode(),
+            });
+        }
+        catch (e) {
+            this.originalLog(`omkit: report.html not written — ${e instanceof Error ? e.message : String(e)}`);
+        }
         // Only now let go of the process hooks — a Ctrl+C during the writes must still be
         // caught (as a no-op) so it can't fall through to Node's kill-without-log default.
         process.off("SIGINT", this.onSigint);
@@ -338,6 +359,7 @@ export class ExecutionTree {
             `  asserts   → ${at("asserts.log")}   ${assertSummary}`,
             `  snapshots → ${at("snapshots.log")}`,
             `  artifacts → ${at("artifacts.log")}`,
+            `  report    → ${at("report.html")}`,
         ];
     }
     /** The recap to the terminal (files are already written). */
@@ -366,9 +388,34 @@ export class ExecutionTree {
             endedAt: node.endedAt,
             duration: node.duration,
             logFile: this.logFile(node.path),
+            ...this.metaView(node),
             children: node.children.map((child) => this.nodeView(child)),
         };
     }
+    /**
+     * The node's self-description, projected for the record. The root's comes from the om
+     * builder; a child's from its action definition. The args schema is converted here, once per
+     * definition, so a step launched a thousand times converts its schema once.
+     */
+    metaView(node) {
+        const meta = node.parentId === null
+            ? { description: this.description, mcp: this.mcp, describeArgs: node.meta?.describeArgs }
+            : node.meta;
+        if (!meta)
+            return {};
+        let inputSchema;
+        if (meta.describeArgs) {
+            if (!this.schemaCache.has(meta.describeArgs)) {
+                this.schemaCache.set(meta.describeArgs, meta.describeArgs().inputSchema);
+            }
+            inputSchema = this.schemaCache.get(meta.describeArgs);
+        }
+        return {
+            ...(meta.description === undefined ? {} : { description: { ...meta.description } }),
+            ...(meta.mcp === undefined ? {} : { mcp: { ...meta.mcp } }),
+            ...(inputSchema === undefined ? {} : { inputSchema }),
+        };
+    }
     /** Test seam: the projected run view (same object written to result.json). */
     runViewForTest() {
         return this.runView();
@@ -412,6 +459,10 @@ export class ExecutionTree {
      * artifact name is free-form, so any printable separator can be forged inside a key.
      */
     curatedArtifacts() {
+        return this.curatedArtifactsWithNode().map(({ nodeId: _nodeId, ...view }) => view);
+    }
+    /** {@link curatedArtifacts}, each still carrying the node that registered it (for the report). */
+    curatedArtifactsWithNode() {
         const byKey = new Map();
         for (const { name, file, description, mime, nodeId } of this.artifactStore.all()) {
             byKey.set(`${nodeId}\0${name}`, {
@@ -419,6 +470,7 @@ export class ExecutionTree {
                 file,
                 mime,
                 ...(description === undefined ? {} : { description }),
+                nodeId,
             });
         }
         return [...byKey.values()];

package/dist/core/action.js

@@ -49,9 +49,13 @@ class Builder {
         // No `.args()` on this path, so there is nothing to describe — or to resolve against.
         const describeArgs = () => describeSchema(undefined);
         const parseArgs = (supplied) => supplied;
+        const meta = {
+            ...(description === undefined ? {} : { description }),
+            ...(mcp === undefined ? {} : { mcp }),
+        };
         const exec = body;
         const create = (...args) => {
-            const spec = { name, args, tags: [], body: exec, definedAt };
+            const spec = { name, args, tags: [], body: exec, definedAt, meta };
             return ExecutionTree.require().launch(spec);
         };
         return Object.assign(create, {
@@ -102,6 +106,11 @@ class ArgsBuilder {
         // that built it — rather than in whichever copy the discovery child is running.
         const schema = this.schema;
         const describeArgs = () => describeSchema(schema);
+        const meta = {
+            ...(description === undefined ? {} : { description }),
+            ...(mcp === undefined ? {} : { mcp }),
+            describeArgs,
+        };
         // `safeParse` is what applies `.default()`s, so this is where an advertised default
         // becomes the effective one. A refusal names the action and every failing field.
         const parseArgs = (supplied) => {
@@ -112,7 +121,7 @@ class ArgsBuilder {
         };
         const exec = body;
         const create = (...args) => {
-            const spec = { name, args, tags: [], body: exec, definedAt };
+            const spec = { name, args, tags: [], body: exec, definedAt, meta };
             return ExecutionTree.require().launch(spec);
         };
         return Object.assign(create, {

package/dist/core/om.js

@@ -37,6 +37,9 @@ function launch(name, site, description, exposure, body, schema) {
     }
     const tree = new ExecutionTree(name, site, description, exposure);
     ExecutionTree.current = tree;
+    // The root's description and exposure live on the tree; its schema rides on the node.
+    if (schema !== undefined)
+        tree.root.meta = { describeArgs: () => describeSchema(schema) };
     const rootBody = (ctx) => body({
         signal: ctx.signal,
         logs: ctx.logs,

package/dist/core/types.d.ts

@@ -239,4 +239,17 @@ export interface LaunchSpec {
     readonly body: Exec<object, unknown, unknown>;
     /** `file:line` where the action was defined; carried onto the node for its log header. */
     readonly definedAt: string | undefined;
+    /** What the definition declared about itself — carried onto the node for the run record. */
+    readonly meta?: ActionMeta;
+}
+/**
+ * A definition's self-description, as it travels onto each node it launches: what
+ * `.describe()` and `.mcp()` said, and the `.args()` schema as JSON Schema. Read only by the
+ * run record (`result.json`, `report.html`) — the runtime never branches on it.
+ */
+export interface ActionMeta {
+    readonly description?: OmDescription;
+    readonly mcp?: ResolvedMcpExposure;
+    /** Converts the declared args schema; called once, at finalize. */
+    readonly describeArgs?: () => DescribedArgs;
 }

package/dist/output/writers/ReportWriter.d.ts

@@ -0,0 +1,16 @@
+import type { LogEntry } from "../../foundation/LogEntry.ts";
+import type { ArtifactView, RunView } from "./views.ts";
+export interface ReportInput {
+    /** The om's name, as given to `om(name)`. */
+    readonly name: string;
+    /** The run folder (absolute). */
+    readonly folder: string;
+    readonly run: RunView;
+    readonly entries: readonly LogEntry[];
+    /** The curated artifacts, as in `run.artifacts`, with the node that registered each. */
+    readonly artifacts: ReadonlyArray<ArtifactView & {
+        readonly nodeId: string;
+    }>;
+}
+/** Writes `report.html` for a finished run. */
+export declare function writeReport(file: string, input: ReportInput): Promise<void>;

package/dist/output/writers/ReportWriter.js

@@ -0,0 +1,275 @@
+import { readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * `report.html` — the run as one self-contained page: the run view, every log entry, the
+ * snapshot payloads, the run's images (as base64), d3, and the viewer itself, all inlined so
+ * the file opens straight from disk, survives being zipped or attached, and needs no server.
+ *
+ * Heavy by design. Images are kept out of the main JSON — each sits in its own inert
+ * `<script type="text/plain">` block the viewer decodes only when it shows that image — so the
+ * page's one `JSON.parse` stays proportional to the log, not to the screenshots. The viewer
+ * paints a loader first and swaps it out once the data is parsed.
+ */
+/** Snapshot payloads larger than this are embedded as truncated text, not parsed JSON. */
+const SNAPSHOT_CAP = 2 * 1024 * 1024;
+/** A single image larger than this is listed but not embedded. */
+const IMAGE_CAP = 25 * 1024 * 1024;
+/** Images stop being embedded once this many bytes are in the page. */
+const IMAGES_TOTAL_CAP = 200 * 1024 * 1024;
+/** Text artifacts (logs, json, md, …) are embedded up to this size. */
+const TEXT_CAP = 1024 * 1024;
+const IMAGE_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+};
+/** Writes `report.html` for a finished run. */
+export async function writeReport(file, input) {
+    const assets = [];
+    const files = await collectFiles(input, assets);
+    const snapshots = await collectSnapshots(input);
+    const root = await projectRoot(input.folder);
+    const payload = {
+        version: 1,
+        name: input.name,
+        folder: input.folder,
+        projectRoot: root,
+        sources: definitionSources(input.run.root, root),
+        generatedAt: Date.now(),
+        run: input.run,
+        entries: input.entries,
+        snapshots,
+        files,
+    };
+    const [d3, css, client] = await Promise.all([
+        readFile(d3Path(), "utf8"),
+        readFile(assetPath("report.css"), "utf8"),
+        readFile(assetPath("report.js"), "utf8"),
+    ]);
+    await writeFile(file, renderPage(input, payload, assets, { d3, css, client }), "utf8");
+}
+function renderPage(input, payload, assets, code) {
+    const title = `Run: ${input.name}`;
+    const blobs = assets
+        .map((a) => `<script type="text/plain" id="${a.id}" data-mime="${a.mime}">${a.data}</script>`)
+        .join("\n");
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>${code.css}</style>
+</head>
+<body>
+<div id="loader" role="status" aria-live="polite">
+  <div class="loader-card">
+    <div class="loader-spin"></div>
+    <div class="loader-title">${escapeHtml(title)}</div>
+    <div class="loader-step" id="loader-step">Loading the run record…</div>
+  </div>
+</div>
+<div id="app" hidden></div>
+<script id="omkit-data" type="application/json">${inertJson(payload)}</script>
+${blobs}
+<script>${inertScript(code.d3)}</script>
+<script>${inertScript(code.client)}</script>
+</body>
+</html>
+`;
+}
+async function collectFiles(input, assets) {
+    const out = [];
+    const seen = new Set();
+    let budget = IMAGES_TOTAL_CAP;
+    const artifactTs = artifactTimes(input.entries);
+    const add = async (abs, meta) => {
+        const key = path.resolve(abs).toLowerCase();
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        const base = { ...meta, file: abs, rel: relTo(input.folder, abs) };
+        let size;
+        try {
+            size = (await stat(abs)).size;
+        }
+        catch {
+            out.push({ ...base, size: 0, omitted: "file not found" });
+            return;
+        }
+        if (meta.mime.startsWith("image/")) {
+            if (size > IMAGE_CAP) {
+                out.push({ ...base, size, omitted: `larger than ${mb(IMAGE_CAP)}` });
+            }
+            else if (size > budget) {
+                out.push({ ...base, size, omitted: `page image budget (${mb(IMAGES_TOTAL_CAP)}) spent` });
+            }
+            else {
+                budget -= size;
+                const id = `asset-${assets.length + 1}`;
+                assets.push({ id, mime: meta.mime, data: (await readFile(abs)).toString("base64") });
+                out.push({ ...base, size, asset: id });
+            }
+        }
+        else if (isText(meta.mime) && size <= TEXT_CAP) {
+            out.push({ ...base, size, text: await readFile(abs, "utf8") });
+        }
+        else {
+            out.push({ ...base, size, omitted: isText(meta.mime) ? `larger than ${mb(TEXT_CAP)}` : "binary" });
+        }
+    };
+    for (const a of input.artifacts) {
+        const ts = artifactTs.get(`${a.nodeId}\0${path.resolve(a.file)}`);
+        await add(a.file, {
+            name: a.name,
+            mime: a.mime,
+            curated: true,
+            nodeId: a.nodeId,
+            ...(ts === undefined ? {} : { ts }),
+            ...(a.description === undefined ? {} : { description: a.description }),
+        });
+    }
+    // Images the run left in its folder without labelling them still belong in the picture.
+    for (const abs of await walk(input.folder)) {
+        const mime = IMAGE_MIME[path.extname(abs).toLowerCase()];
+        if (mime)
+            await add(abs, { name: path.basename(abs), mime, curated: false });
+    }
+    return out;
+}
+async function collectSnapshots(input) {
+    const out = [];
+    let seq = 0;
+    for (const e of input.entries) {
+        if (e.level !== "snapshot")
+            continue;
+        const split = e.message.lastIndexOf(" → ");
+        if (split < 0)
+            continue;
+        const name = e.message.slice(0, split);
+        const abs = e.message.slice(split + 3);
+        const base = { seq: ++seq, name, nodeId: e.nodeId, ts: e.ts, file: abs, rel: relTo(input.folder, abs) };
+        try {
+            const raw = await readFile(abs, "utf8");
+            if (raw.length > SNAPSHOT_CAP) {
+                out.push({ ...base, text: raw.slice(0, SNAPSHOT_CAP), truncated: true });
+            }
+            else {
+                try {
+                    out.push({ ...base, value: JSON.parse(raw) });
+                }
+                catch {
+                    out.push({ ...base, text: raw });
+                }
+            }
+        }
+        catch {
+            out.push({ ...base, text: "(snapshot file not found)" });
+        }
+    }
+    return out;
+}
+/** `ts` of each `artifact` timeline line, keyed by `(nodeId, file)` — the latest wins. */
+function artifactTimes(entries) {
+    const out = new Map();
+    for (const e of entries) {
+        if (e.level !== "artifact")
+            continue;
+        const split = e.message.lastIndexOf(" → ");
+        if (split >= 0)
+            out.set(`${e.nodeId}\0${path.resolve(e.message.slice(split + 3))}`, e.ts);
+    }
+    return out;
+}
+/**
+ * The project the run belongs to, for project-relative paths: the nearest ancestor of the run
+ * folder holding `.git`, else the folder `logs/` sits in (the root omkit was given), else cwd.
+ */
+async function projectRoot(folder) {
+    let dir = path.resolve(folder);
+    for (;;) {
+        try {
+            await stat(path.join(dir, ".git"));
+            return dir;
+        }
+        catch {
+            /* keep climbing */
+        }
+        const up = path.dirname(dir);
+        if (up === dir)
+            break;
+        dir = up;
+    }
+    return process.env.OMKIT_ROOT ? path.resolve(process.env.OMKIT_ROOT) : process.cwd();
+}
+/** Each distinct `definedAt` site → its file, relative to the project root, forward-slashed, no line. */
+function definitionSources(root, projectDir) {
+    const out = {};
+    const visit = (n) => {
+        if (n.definedAt && !(n.definedAt in out)) {
+            const file = n.definedAt.replace(/:\d+(:\d+)?$/, "");
+            out[n.definedAt] = path.relative(projectDir, file).split(path.sep).join("/") || file;
+        }
+        n.children.forEach(visit);
+    };
+    visit(root);
+    return out;
+}
+async function walk(dir, depth = 0) {
+    if (depth > 4)
+        return [];
+    let names;
+    try {
+        names = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const d of names) {
+        const abs = path.join(dir, d.name);
+        if (d.isDirectory())
+            out.push(...(await walk(abs, depth + 1)));
+        else if (d.isFile())
+            out.push(abs);
+    }
+    return out.sort();
+}
+function relTo(folder, abs) {
+    const rel = path.relative(folder, abs);
+    return rel.startsWith("..") || path.isAbsolute(rel) ? abs : rel.split(path.sep).join("/");
+}
+function isText(mime) {
+    return (mime.startsWith("text/") ||
+        mime === "application/json" ||
+        mime === "application/x-ndjson" ||
+        mime === "image/svg+xml");
+}
+function mb(bytes) {
+    return `${Math.round(bytes / 1024 / 1024)} MB`;
+}
+/** JSON safe to sit inside a `<script>` block: no `</script>`, no `<!--`. */
+function inertJson(value) {
+    return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+/** JS safe to sit inside a `<script>` block. */
+function inertScript(code) {
+    return code.replace(/<\/script/gi, "<\\/script");
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+}
+/** The viewer's own files, next to this module (`report/`) in both `src` and `dist`. */
+function assetPath(name) {
+    return fileURLToPath(new URL(`./report/${name}`, import.meta.url));
+}
+/** d3's UMD bundle — the package's `exports` hide `dist/`, so go via its resolved entry. */
+function d3Path() {
+    const entry = createRequire(import.meta.url).resolve("d3");
+    return path.join(path.dirname(entry), "..", "dist", "d3.min.js");
+}