omkit 0.1.6 → 0.1.8

package/dist/core/ExecutionTree.d.ts

@@ -70,7 +70,13 @@ export declare class ExecutionTree {
     private drive;
     private finalize;
     private finalizeOnce;
-    /** The end-of-run links + assert summary, to the terminal (files are already written). */
+    /**
+     * The end-of-run recap: the run folder, sibling log paths, and the assert tally.
+     * Shared verbatim between the terminal (via {@link printSummary}) and the tail of
+     * `main.log` (as the footer passed to `writeNodeLogs`), so both close the same way.
+     */
+    private summaryLines;
+    /** The recap to the terminal (files are already written). */
     private printSummary;
     private verdictOk;
     private nodeView;

package/dist/core/ExecutionTree.js

@@ -243,7 +243,8 @@ export class ExecutionTree {
         const entries = this.store.entries();
         const at = (name) => path.join(this.folder.path(), name);
         const assertSummary = `⊨ ${this.assertionsPassed} passed · ⊭ ${this.assertionsFailed} failed`;
-        await writeNodeLogs(flat, entries);
+        const summary = this.summaryLines(at, assertSummary);
+        await writeNodeLogs(flat, entries, summary);
         await writeRollup(at("events.log"), flat, entries, (e) => e.level === "event");
         await writeRollup(at("asserts.log"), flat, entries, (e) => e.level === "assert", assertSummary);
         await writeRollup(at("snapshots.log"), flat, entries, (e) => e.level === "snapshot");
@@ -255,19 +256,30 @@ export class ExecutionTree {
         process.off("unhandledRejection", this.onUnhandled);
         this.consoleCapture.uninstall();
         ExecutionTree.current = null;
-        this.printSummary(at, assertSummary);
+        this.printSummary(summary);
         if (!this.verdictOk())
             process.exitCode = 1;
     }
-    /** The end-of-run links + assert summary, to the terminal (files are already written). */
-    printSummary(at, assertSummary) {
+    /**
+     * The end-of-run recap: the run folder, sibling log paths, and the assert tally.
+     * Shared verbatim between the terminal (via {@link printSummary}) and the tail of
+     * `main.log` (as the footer passed to `writeNodeLogs`), so both close the same way.
+     */
+    summaryLines(at, assertSummary) {
+        return [
+            `om → ${this.folder.path()}`,
+            `  main log  → ${at("main.log")}`,
+            `  events    → ${at("events.log")}`,
+            `  asserts   → ${at("asserts.log")}   ${assertSummary}`,
+            `  snapshots → ${at("snapshots.log")}`,
+        ];
+    }
+    /** The recap to the terminal (files are already written). */
+    printSummary(lines) {
         const term = this.originalLog;
         term("");
-        term(`om → ${this.folder.path()}`);
-        term(`  main log  → ${at("main.log")}`);
-        term(`  events    → ${at("events.log")}`);
-        term(`  asserts   → ${at("asserts.log")}   ${assertSummary}`);
-        term(`  snapshots → ${at("snapshots.log")}`);
+        for (const line of lines)
+            term(line);
     }
     verdictOk() {
         return this.faults.length === 0;

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

@@ -3,6 +3,8 @@ import type { NodeView } from "./views.ts";
 /**
  * Writes each node's own human `.log`: a one-time `ActionRef` header, then that
  * node's entries (by `nodeId`) prefixed `[seq iso-ts path]`. Rows never repeat
- * name/tags — the header carries them.
+ * name/tags — the header carries them. The optional `footer` (the run's end-of-run
+ * recap — assert tally + sibling log paths) is appended to the **root** log only,
+ * so `main.log` closes with the same snippet shown live on the terminal.
  */
-export declare function writeNodeLogs(nodes: readonly NodeView[], entries: readonly LogEntry[]): Promise<void>;
+export declare function writeNodeLogs(nodes: readonly NodeView[], entries: readonly LogEntry[], footer?: readonly string[]): Promise<void>;

package/dist/output/writers/NodeLogWriter.js

@@ -5,19 +5,24 @@ import { entryLine, groupByNode } from "./entryLine.js";
 /**
  * Writes each node's own human `.log`: a one-time `ActionRef` header, then that
  * node's entries (by `nodeId`) prefixed `[seq iso-ts path]`. Rows never repeat
- * name/tags — the header carries them.
+ * name/tags — the header carries them. The optional `footer` (the run's end-of-run
+ * recap — assert tally + sibling log paths) is appended to the **root** log only,
+ * so `main.log` closes with the same snippet shown live on the terminal.
  */
-export async function writeNodeLogs(nodes, entries) {
+export async function writeNodeLogs(nodes, entries, footer = []) {
     const byNode = groupByNode(entries, () => true);
     const refByNode = new Map(nodes.map((n) => [n.id, n]));
     const refOf = (id) => refByNode.get(id);
     await Promise.all(nodes.map(async (node) => {
         const lines = (byNode.get(node.id) ?? []).map((e) => entryLine(e, refOf));
-        const body = [...header(node), "", ...lines, ""].join("\n");
+        const foot = node.parentId === null && footer.length ? ["", summaryRule, ...footer] : [];
+        const body = [...header(node), "", ...lines, ...foot, ""].join("\n");
         await mkdir(path.dirname(node.logFile), { recursive: true });
         await writeFile(node.logFile, body, "utf8");
     }));
 }
+/** The divider that opens the root log's end-of-run recap (mirrors the header's `── legend ──`). */
+const summaryRule = "── summary ──────────────────────────────────────────────────────────";
 /** The per-file metadata header: ref, defining script, args, start/finish times, status. */
 const header = (node) => [
     `# ${renderRef(node)}`,
@@ -27,7 +32,18 @@ const header = (node) => [
     `#   started:  ${stamp(node.startedAt)}`,
     `#   finished: ${stamp(node.endedAt)} (${node.duration}ms)`,
     `#   status:   ${node.status}`,
+    ...(node.parentId === null ? legend : []), // the run's root log (main.log) only
 ].filter((line) => line !== null);
+/** A compact reading guide, printed once on the root log so an agent can follow the run. */
+const legend = [
+    "#",
+    "# ── legend ──────────────────────────────────────────────────────────",
+    "#   [n]              global sequence — the merge/order key across every .log",
+    "#   indented rows    a child action's milestones, bubbled up here",
+    "#   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() : "-");
 const renderArgs = (args) => {
     try {

package/dist/output/writers/entryLine.js

@@ -6,7 +6,11 @@ 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) => `[${e.sequence}] ${bodyOf(e, refOf)}`;
+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)}`;
+};
 const bodyOf = (e, refOf) => {
     switch (e.level) {
         case "event":
@@ -24,9 +28,9 @@ 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 milestone carries the child's id as `source`: name it with its
-            // tags (`name [tags]`) so the parent timeline always shows them. The launch
-            // pointer (`source === "launch"`) keeps its `→ id · logfile` message as-is.
+            // 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`.
             if (e.source === "launch")
                 return `${e.source} · ${e.message}`;
             const ref = refOf?.(e.source);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "A tiny runtime for developer workflows: typed actions that pass runtime capabilities and emit typed events, under one run and one shared log. The operational/runtime layer to tskb's knowledge layer.",
   "type": "module",
   "main": "./dist/index.js",