omkit 0.8.8 → 0.8.10

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.
@@ -122,6 +124,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.
@@ -84,6 +87,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),
@@ -307,7 +311,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 +357,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). */
@@ -412,6 +432,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 +443,7 @@ export class ExecutionTree {
                 file,
                 mime,
                 ...(description === undefined ? {} : { description }),
+                nodeId,
             });
         }
         return [...byKey.values()];

package/dist/output/writers/NodeLogWriter.js

@@ -39,9 +39,9 @@ const legend = [
     "#",
     "# ── legend ──────────────────────────────────────────────────────────",
     "#   [n]              global sequence — the merge/order key across every .log",
-    "#   indented rows    a child action's milestones, bubbled up here",
+    "#   launch ACTION_RUN(id) · → · ….log   a child started — open that file for its full output",
+    "#   indented rows    a child action's milestones, bubbled up here (one level under launches)",
     "#   name [tags]      the action and its tags   ·   defined …  where its code lives",
-    "#   launch · → ….log a child started — open that file for its full output",
     "#   ⚡ event   ✓ done ok   ⊘ cancelled   ✗ failed   ⊨/⊭ assert pass/fail   📸 snapshot   ▪ output",
 ];
 const stamp = (ms) => (ms ? new Date(ms).toISOString() : "-");

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,238 @@
+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 payload = {
+        version: 1,
+        name: input.name,
+        folder: input.folder,
+        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;
+}
+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");
+}

package/dist/output/writers/entryLine.js

@@ -6,10 +6,20 @@ import { label } from "../../foundation/ActionRef.js";
  * the child by its {@link label} (name + tags) via `refOf`; everything else keeps its
  * `source` (proc name, `console`, …).
  */
-export const entryLine = (e, refOf) => {
-    // Bubbled child rows are nested a level in — the whole row, `[seq]` included.
-    const indent = e.level === "child" ? "    " : "";
-    return `${indent}[${e.sequence}] ${bodyOf(e, refOf)}`;
+export const entryLine = (e, refOf) => `${indentOf(e)}[${e.sequence}] ${bodyOf(e, refOf)}`;
+/**
+ * Bubbled child rows are nested in — the whole row, `[seq]` included. The launch pointer
+ * sits one level in; the child's own milestones sit one level deeper, under their launch.
+ */
+const indentOf = (e) => {
+    if (e.level !== "child")
+        return "";
+    return e.source === "launch" ? "    " : "        ";
+};
+/** `→ <id> · <logfile> · …` → `ACTION_RUN(<id>) · → · <logfile> · …`, so a launch stands out. */
+const launchBody = (message) => {
+    const [head = "", ...rest] = message.replace(/^→\s*/, "").split(" · ");
+    return [`ACTION_RUN(${head})`, "→", ...rest].join(" · ");
 };
 const bodyOf = (e, refOf) => {
     switch (e.level) {
@@ -28,11 +38,11 @@ const bodyOf = (e, refOf) => {
             // output. (Cancellation no longer logs at this level — it's a clean stop.)
             return e.source === "error" ? `✗ ${e.message}` : `▪ ${e.message}`;
         case "child": {
-            // A bubbled child line (indented at the row level by `entryLine`). The launch pointer
-            // (`source === "launch"`) keeps its `→ id · logfile` message; a milestone names the
-            // child by its label (name + tags) via `refOf`.
+            // A bubbled child line (indented at the row level by `indentOf`). The launch pointer
+            // (`source === "launch"`) reads `launch ACTION_RUN(id) · → · logfile`; a milestone
+            // names the child by its label (name + tags) via `refOf`.
             if (e.source === "launch")
-                return `${e.source} · ${e.message}`;
+                return `${e.source} ${launchBody(e.message)}`;
             const ref = refOf?.(e.source);
             return `${ref ? label(ref) : e.source} · ${e.message}`;
         }