omkit 0.0.11 → 0.0.13

package/dist/actions/chrome-page.d.ts

@@ -33,12 +33,16 @@ export interface ChromePageOptions {
  * from whatever {@link ChromePageSource} is given — a CDP endpoint to connect to,
  * or an already-owned Playwright handle (an Electron `BrowserWindow` page, a
  * `BrowserContext`, or a `Browser`). The source may be a promise, so it wires
- * straight from another action's `.ref` (e.g. `chromePage(chromedriver.ref)` or
- * `chromePage(electronApp.ref)`).
+ * straight from another action's `.ref` (e.g. `chromePage("Explorer",
+ * chromedriver.ref)` or `chromePage("App", electronApp.ref)`).
  *
  * Daemon-shaped like the watch actions: acquire the page, attach it, then stay
  * alive on a promise that only resolves when the run's `signal` aborts. On
  * teardown it closes the CDP connection *only* when it opened one — a handed-in
  * browser or window is left untouched for its owner to close.
+ *
+ * `label` names this page in the log (its `source`), so several `chromePage`
+ * instances in one run stay distinguishable — e.g. `chromePage("Explorer",
+ * chrome.ref)` logs its lines under `Explorer` rather than a shared default.
  */
-export declare const chromePage: import("../index.ts").Action<[source: ChromePageSource | Promise<ChromePageSource>, opts?: ChromePageOptions | undefined], void, ChromePageEvents, Page>;
+export declare const chromePage: import("../index.ts").Action<[label: string, source: ChromePageSource | Promise<ChromePageSource>, opts?: ChromePageOptions | undefined], void, ChromePageEvents, Page>;

package/dist/actions/chrome-page.js

@@ -13,18 +13,22 @@ const pageOf = (context, fresh) => fresh ? context.newPage() : (context.pages()[
  * from whatever {@link ChromePageSource} is given — a CDP endpoint to connect to,
  * or an already-owned Playwright handle (an Electron `BrowserWindow` page, a
  * `BrowserContext`, or a `Browser`). The source may be a promise, so it wires
- * straight from another action's `.ref` (e.g. `chromePage(chromedriver.ref)` or
- * `chromePage(electronApp.ref)`).
+ * straight from another action's `.ref` (e.g. `chromePage("Explorer",
+ * chromedriver.ref)` or `chromePage("App", electronApp.ref)`).
  *
  * Daemon-shaped like the watch actions: acquire the page, attach it, then stay
  * alive on a promise that only resolves when the run's `signal` aborts. On
  * teardown it closes the CDP connection *only* when it opened one — a handed-in
  * browser or window is left untouched for its owner to close.
+ *
+ * `label` names this page in the log (its `source`), so several `chromePage`
+ * instances in one run stay distinguishable — e.g. `chromePage("Explorer",
+ * chrome.ref)` logs its lines under `Explorer` rather than a shared default.
  */
 export const chromePage = action("Chrome Page")
     .emits()
     .ref()
-    .run(async ({ logs, signal, emit, attach }, source, opts = {}) => {
+    .run(async ({ logs, signal, emit, attach }, label, source, opts = {}) => {
     const { url } = opts;
     const resolved = await source;
     // Resolve the source to a Page, recording what (if anything) we own. Only a
@@ -60,23 +64,23 @@ export const chromePage = action("Chrome Page")
         page = await pageOf(resolved, url !== undefined);
     }
     page.on("console", (msg) => {
-        logs.append({ source: "Chrome Page", level: "info", message: `console: ${msg.text()}` });
-        emit("console", msg.text());
+        logs.append({ source: label, level: "info", message: `console: ${msg.text()}` });
+        emit("console", `from: ${label}:  ${msg.text()}`);
     });
     page.on("pageerror", (err) => {
-        logs.append({ source: "Chrome Page", level: "error", message: err.message });
-        emit("pageerror", err.message);
+        logs.append({ source: label, level: "error", message: err.message });
+        emit("pageerror", `from: ${label}:  ${err.message}`);
     });
     page.on("framenavigated", (frame) => {
         if (frame === page.mainFrame())
-            emit("navigated", frame.url());
+            emit("navigated", `${label}: ${frame.url()}`);
     });
     if (url) {
         await page.goto(url);
-        logs.append({ source: "Chrome Page", level: "info", message: `navigated ${url}` });
+        logs.append({ source: label, level: "info", message: `navigated ${url}` });
     }
     attach(page); // resolves instance.ref for every downstream action
-    logs.append({ source: "Chrome Page", level: "info", message: `attached ${from}` });
+    logs.append({ source: label, level: "info", message: `attached ${from}` });
     // Daemon: hold the page open until teardown, then drop the CDP session if it
     // was ours; never close a handed-in browser/window.
     return new Promise((resolveRun) => {

package/dist/actions/command.d.ts

@@ -6,8 +6,6 @@ export interface CommandOptions {
      * node was executed from (process.cwd()). Default ".".
      */
     cwd?: string;
-    /** Label the child's output is logged under. Defaults to the action's name. */
-    label?: string;
     /**
      * Environment for the child. Pass the full set you want (e.g.
      * `{ ...process.env, NODE_ENV: "development" }`) — it's handed to the child

package/dist/actions/command.js

@@ -21,7 +21,7 @@ export function command(name, cmdOrFile, argsOrOptions, maybeOptions) {
         // against process.cwd() — exactly the "absolute from where node runs" rule.
         const cwd = path.resolve(options.cwd ?? ".");
         // proc sources the LogsCollector from async context and streams output into it.
-        return proc(options.label ?? name, {
+        return proc(name, {
             cwd,
             ...(options.env ? { env: options.env } : {}),
         })(verbatim(cmdOrFile));
@@ -36,7 +36,7 @@ export function command(name, cmdOrFile, argsOrOptions, maybeOptions) {
  */
 const spawnDirect = (snapshots, logs, signal, name, file, args, options) => {
     const cwd = path.resolve(options.cwd ?? ".");
-    const source = options.label ?? name;
+    const source = name;
     // windowsHide keeps a stray console window from flashing for the child.
     // env omitted -> spawn inherits the parent's process.env (Node's default).
     const child = spawn(file, args, { cwd, windowsHide: true, env: options.env });

package/dist/index.d.ts

@@ -10,6 +10,8 @@
  */
 export { action } from "./orchestration/action/action.ts";
 export type { Action, ActionBuilder, ActionInstance, AnyActionInstance, ActionContext, SystemGlobal, SystemEvents, InstanceEvents, NoEvents, Awaitable, Outcome, } from "./orchestration/action/types.ts";
+export { AssertionError } from "./orchestration/assert.ts";
+export type { Assert } from "./orchestration/assert.ts";
 export { spin } from "./orchestration/spin/spin.ts";
 export type { Nod, SpinContext, SpinBody } from "./orchestration/spin/types.ts";
 export { events } from "./orchestration/events/events.ts";
@@ -17,7 +19,7 @@ export type { Emitter, EventHandler, EventMeta } from "./orchestration/events/ev
 export { createProc } from "./system/process/process.ts";
 export type { Proc } from "./system/process/process.ts";
 export { LogsCollector } from "./output/log/LogsCollector.ts";
-export type { Logger, LogEntry, LogInput, SubscribeOptions, } from "./output/log/LogsCollector.ts";
+export type { Logger, LogEntry, LogInput, SubscribeOptions } from "./output/log/LogsCollector.ts";
 export { Output } from "./output/index.ts";
 export type { SnapshotRef } from "./output/index.ts";
 export { FolderCache } from "./system/fs/FolderCache.ts";

package/dist/index.js

@@ -10,6 +10,7 @@
  */
 // ── Actions ────────────────────────────────────────────────────────────────
 export { action } from "./orchestration/action/action.js";
+export { AssertionError } from "./orchestration/assert.js";
 // ── Spin (linear orchestration) ──────────────────────────────────────────────
 export { spin } from "./orchestration/spin/spin.js";
 // ── Events ─────────────────────────────────────────────────────────────────

package/dist/orchestration/action/action.js

@@ -123,6 +123,7 @@ class ActionRun {
                 signal: ctx.signal,
                 nod: ctx.nod,
                 output: ctx.output,
+                assert: ctx.assert,
             });
             // Re-throw the inner failure so the wrapper fails too (the framework re-wraps
             // it into this wrapper's own Outcome); only record on success.

package/dist/orchestration/action/types.d.ts

@@ -2,6 +2,7 @@ import type { Logger } from "../../output/log/LogsCollector.ts";
 import type { Output } from "../../output/Output.ts";
 import type { Emitter, EventHandler } from "../events/events.ts";
 import type { Proc } from "../../system/process/process.ts";
+import type { Assert } from "../assert.ts";
 /** An action that declares no events. */
 export type NoEvents = Record<never, never>;
 /** A value an action's `exec` may return: a result, or a promise of one. */
@@ -67,6 +68,12 @@ export interface SystemGlobal {
      * capture their own artifacts.
      */
     readonly output: Output;
+    /**
+     * Assert a boolean invariant for this action. Logs a `⊨` line every call; a
+     * mismatch is recorded into the run's verdict (never throws, never stops the
+     * run). Bound to this action's path for attribution.
+     */
+    readonly assert: Assert;
 }
 /** What an action's implementation receives: the system bag, plus `emit`, `attach`, and `proc`. */
 export interface ActionContext<Events extends object, Handle = void> extends SystemGlobal {
@@ -113,7 +120,7 @@ export interface ActionInstance<Result = unknown, Events extends object = NoEven
     readonly done: Promise<Outcome<Result>>;
     /**
      * Resolves with the handle the action attached via `ctx.attach` (set once).
-     * Used to thread a handle into another action (`chromePage(driver.ref)`). If
+     * Used to thread a handle into another action (`chromePage("Explorer", driver.ref)`). If
      * the action settles *without* attaching, this resolves (`undefined` for the
      * default `void` handle) on success and **rejects on failure** — so, unlike
      * `done`, awaiting `ref` in a body can throw. It's meant to be consumed as a

package/dist/orchestration/assert.d.ts

@@ -0,0 +1,22 @@
+import type { Logger } from "../output/log/LogsCollector.ts";
+/**
+ * An inline check injected into every action's `ctx` and the `spin` body. Passes
+ * when `value` is `true`. Every call is logged; a failure is recorded into the
+ * run's verdict — as data, not a throw — so the run keeps going and later
+ * assertions still fire. Returns the pass boolean so a body can branch on it.
+ *
+ *   assert(page.isVisible(), "page loaded")
+ */
+export type Assert = (value: boolean, what: string) => boolean;
+/** Marks a failed assertion in the spin's verdict, distinct from an action's own error. */
+export declare class AssertionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Build an {@link Assert} bound to one action (or the spin body): `name` is its
+ * launch path (used for attribution in the log line and the error), `logs` is the
+ * logger to append to, and `onFail` records a genuine failure into the verdict. The
+ * factory is file-agnostic — it only appends `level: "assert"` entries; the
+ * dedicated `assertions.log` is a downstream projection of that stream.
+ */
+export declare function createAssert(name: string, logs: Logger, onFail: (error: AssertionError) => void): Assert;

package/dist/orchestration/assert.js

@@ -0,0 +1,26 @@
+/** Marks a failed assertion in the spin's verdict, distinct from an action's own error. */
+export class AssertionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AssertionError";
+    }
+}
+/**
+ * Build an {@link Assert} bound to one action (or the spin body): `name` is its
+ * launch path (used for attribution in the log line and the error), `logs` is the
+ * logger to append to, and `onFail` records a genuine failure into the verdict. The
+ * factory is file-agnostic — it only appends `level: "assert"` entries; the
+ * dedicated `assertions.log` is a downstream projection of that stream.
+ */
+export function createAssert(name, logs, onFail) {
+    return (value, what) => {
+        const pass = value;
+        const glyph = pass ? "✓" : "✗";
+        const message = `${name} · ${glyph} ${what}`;
+        logs.append({ source: "assert", level: "assert", message });
+        if (!pass) {
+            onFail(new AssertionError(`${name}: ${what}`));
+        }
+        return pass;
+    };
+}

package/dist/orchestration/spin/SpinHost.d.ts

@@ -32,6 +32,10 @@ export declare class SpinHost {
     readonly signal: AbortSignal;
     /** Settles once the spin reaches `closed`, carrying the terminal verdict. Never rejects. */
     readonly done: Promise<SpinResult>;
+    /** The original `console.log`, captured before patching — the run's terminal writer. */
+    private readonly term;
+    /** Reinstalls the pre-run console methods; called once at finalize. */
+    private readonly restoreConsole;
     private readonly controller;
     private phase;
     /** The current lifecycle state — see {@link SpinState}. */

package/dist/orchestration/spin/SpinHost.js

@@ -2,7 +2,9 @@ import { relative } from "node:path";
 import { producerOfRef } from "../action/action.js";
 import { LogsCollector, ScopedLogger } from "../../output/log/LogsCollector.js";
 import { LogRenderer } from "../../output/log/LogRenderer.js";
+import { actionScope, captureConsole } from "../../output/log/console-capture.js";
 import { Output } from "../../output/Output.js";
+import { createAssert } from "../assert.js";
 /** The entry script, relative to where node was invoked (so the log says what produced it). */
 const scriptPath = () => {
     const entry = process.argv[1];
@@ -58,6 +60,10 @@ export class SpinHost {
     signal;
     /** Settles once the spin reaches `closed`, carrying the terminal verdict. Never rejects. */
     done;
+    /** The original `console.log`, captured before patching — the run's terminal writer. */
+    term;
+    /** Reinstalls the pre-run console methods; called once at finalize. */
+    restoreConsole;
     controller = new AbortController();
     // ── Lifecycle state ──────────────────────────────────────────────────────
     // The single source of truth for "where in its life is this run". Only
@@ -89,6 +95,12 @@ export class SpinHost {
         for (const instance of actions)
             assertInstance(instance);
         this.signal = this.controller.signal;
+        // Capture the ORIGINAL console.log as this run's terminal writer BEFORE patching,
+        // or `drain`/finalize would re-enter the patched method and feedback-loop. Then
+        // patch console so every console.* during the run folds into this run's log,
+        // attributed via `actionScope` (see `launch`).
+        this.term = console.log.bind(console);
+        this.restoreConsole = captureConsole(this.logs);
         process.once("SIGINT", this.onSigint);
         process.on("uncaughtException", this.onUncaught);
         process.on("unhandledRejection", this.onUnhandled);
@@ -150,7 +162,7 @@ export class SpinHost {
         void (async () => {
             const renderer = new LogRenderer();
             for await (const entry of this.logs.subscribe({ replay: true }))
-                console.log(renderer.render(entry));
+                this.term(renderer.render(entry));
         })().catch(() => { });
     }
     /** Narrate a run-lifecycle milestone into this run's log (renders as a `[run]` line). */
@@ -206,7 +218,7 @@ export class SpinHost {
         };
     }
     launch(instance, parentPath) {
-        // A consumer built with another action's `.ref` (e.g. `chromePage(driver.ref)`)
+        // A consumer built with another action's `.ref` (e.g. `chromePage("Explorer", driver.ref)`)
         // must be launched *after* that producer — otherwise it awaits a handle that
         // never arrives and the spin hangs silently. Catch it and say how to fix it.
         for (const arg of instance.args) {
@@ -228,6 +240,16 @@ export class SpinHost {
             this.nodInto(child, path);
             return child;
         };
+        // A boolean check bound to this action's path: it logs a `⊨` milestone, and a
+        // mismatch records a verdict failure the same way an action's own failure does
+        // — skipped during teardown (cascade, not a fault). Uses `this.logs` (not
+        // `scoped`) the same way `record` below does: the path is already embedded in
+        // the message via `name`, so routing through `scoped` would double-prefix the
+        // `source` field for a nodded child.
+        const assert = createAssert(path, this.logs, (error) => {
+            if (!this.controller.signal.aborted)
+                this.recordFailure(path, error);
+        });
         this.narrate(`launch ${path}`);
         // The action logs into this run's shared store (entries carry their `source`;
         // grouping is applied at render time) and gets the spin's signal directly; the
@@ -247,8 +269,14 @@ export class SpinHost {
             if (!this.controller.signal.aborted)
                 this.recordFailure(path, error);
         };
-        const promise = instance
-            .start({ logs: scoped, signal: this.controller.signal, nod, output: this.output })
+        const promise = actionScope
+            .run(path, () => instance.start({
+            logs: scoped,
+            signal: this.controller.signal,
+            nod,
+            output: this.output,
+            assert,
+        }))
             .then((outcome) => {
             if (!outcome.ok)
                 record(outcome.error);
@@ -282,6 +310,7 @@ export class SpinHost {
         process.off("SIGINT", this.onSigint);
         process.off("uncaughtException", this.onUncaught);
         process.off("unhandledRejection", this.onUnhandled);
+        this.restoreConsole();
         this.narrate("finished");
         // Close the log now (after the last entry) so `streamLog` drains and finishes
         // writing the complete run.jsonl, then wait for it to fully close its files —
@@ -291,7 +320,7 @@ export class SpinHost {
         await this.streaming;
         const file = await this.output.runLog.write();
         // Direct to the terminal — the file's already written, so this line isn't in it.
-        console.log(LogRenderer.marker("run", `log → ${file}`));
+        this.term(LogRenderer.marker("run", `log → ${file}`));
         const result = { ok: this.failures.length === 0, failures: this.failures };
         // One process = one run = one verdict; reflect pass/fail in the exit code so
         // shells and CI see it without parsing the log. Only set it on failure, so a

package/dist/orchestration/spin/spin.d.ts

@@ -16,7 +16,7 @@ import type { SpinBody } from "./types.ts";
  *     if (ans.ok && ans.value === "yes") await nod(test).done;
  *     nod(devServer);                                   // fire-and-forget daemon
  *     const chrome = nod(chromedriver({ … }));
- *     nod(chromePage(chrome.ref));                      // data deps via .ref
+ *     nod(chromePage("Explorer", chrome.ref));          // data deps via .ref
  *   });
  *
  * Auto-drains by default;

package/dist/orchestration/spin/spin.js

@@ -17,7 +17,7 @@ import { SpinHost } from "./SpinHost.js";
  *     if (ans.ok && ans.value === "yes") await nod(test).done;
  *     nod(devServer);                                   // fire-and-forget daemon
  *     const chrome = nod(chromedriver({ … }));
- *     nod(chromePage(chrome.ref));                      // data deps via .ref
+ *     nod(chromePage("Explorer", chrome.ref));          // data deps via .ref
  *   });
  *
  * Auto-drains by default;
@@ -41,6 +41,7 @@ export function spin(body) {
             // the body from there rather than reaching for a module singleton.
             artifactsFolder: ctx.artifactsFolder,
             snapshot: (name, value) => ctx.output.snapshots.snapshot(name, value),
+            assert: ctx.assert,
         });
     });
     const mainSpinAction = hostAction();

package/dist/orchestration/spin/types.d.ts

@@ -1,5 +1,6 @@
 export type { Nod } from "../action/types.ts";
 import type { Nod } from "../action/types.ts";
+import type { Assert } from "../assert.ts";
 /** What a {@link spin} body receives. */
 export interface SpinContext {
     /** Launch an action into the spin; returns the instance for awaiting/chaining. */
@@ -25,6 +26,12 @@ export interface SpinContext {
      * run-scoped counterpart to the action `ctx.output.snapshots`.
      */
     readonly snapshot: (name: string, value: unknown) => Promise<string>;
+    /**
+     * Assert a boolean invariant from the spin body. Same semantics as the action
+     * `ctx.assert`; body assertions are attributed to the host action path
+     * (`omkit:Spin`).
+     */
+    readonly assert: Assert;
 }
 /** The body of a {@link spin}: any (async) function — it isn't named or wrapped by you. */
 export type SpinBody = (ctx: SpinContext) => void | Promise<void>;

package/dist/output/log/LogRenderer.d.ts

@@ -1,6 +1,6 @@
 import type { LogEntry } from "./LogsCollector.ts";
 /** The special "title" log lines that get a distinguishing prefix. */
-export type MarkerKind = "event" | "action" | "run" | "snapshot";
+export type MarkerKind = "event" | "action" | "run" | "snapshot" | "assert";
 /** A run set aside for collapsing: its source and every output line, in order. */
 export interface CollapsedRun {
     readonly source: string;

package/dist/output/log/LogRenderer.js

@@ -3,6 +3,7 @@ const PREFIX = {
     action: "▸",
     run: "●",
     snapshot: "📎",
+    assert: "⊨",
 };
 /**
  * Levels that render as their own top-level milestone line — marker-prefixed and
@@ -13,6 +14,7 @@ const MILESTONE = {
     run: "run",
     event: "event",
     snapshot: "snapshot",
+    assert: "assert",
 };
 /** Only runs *longer than* this collapse, so a trigger always hides a meaningful amount. */
 const COLLAPSE_THRESHOLD = 15;

package/dist/output/log/RunLog.js

@@ -37,10 +37,18 @@ export class RunLog {
         const pretty = createWriteStream(this.folder.resolve("run.log"));
         const renderer = new LogRenderer();
         pretty.write(this.header() + "\n");
+        // The dedicated assertions file is a filtered projection of the same stream:
+        // opened lazily on the first `assert` entry (so runs with none produce no file),
+        // one `⊨ …` line each. Assertions still ride the main run.jsonl / run.log too.
+        let assertions;
         try {
             for await (const entry of entries) {
                 jsonl.write(JSON.stringify(entry) + "\n");
                 pretty.write(renderer.render(entry) + "\n");
+                if (entry.level === "assert") {
+                    assertions ??= createWriteStream(this.folder.resolve("assertions.log"));
+                    assertions.write(LogRenderer.marker("assert", entry.message) + "\n");
+                }
             }
         }
         finally {
@@ -49,7 +57,11 @@ export class RunLog {
             // this stream landed *after* write() truncated run.log, the OS would zero-fill the
             // gap — a multi-MB run of NUL bytes. `run` awaits this promise before calling
             // write(), so this writer is guaranteed done first (and run.jsonl is complete).
-            await Promise.all([closeStream(jsonl), closeStream(pretty)]);
+            await Promise.all([
+                closeStream(jsonl),
+                closeStream(pretty),
+                ...(assertions ? [closeStream(assertions)] : []),
+            ]);
         }
     }
     /**
@@ -112,7 +124,7 @@ export class RunLog {
         const now = new Date();
         return [
             `─── ${this.folder.name()} · ${ymd(now)} ${hms(now)} ───`,
-            `● run  ⚡ event  ▸ action  📎 snapshot  ⇥ output`,
+            `● run  ⚡ event  ▸ action  📎 snapshot  ⇥ output  ⊨ assert`,
             "",
         ].join("\n");
     }

package/dist/output/log/console-capture.d.ts

@@ -0,0 +1,24 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Logger } from "./LogsCollector.ts";
+/**
+ * The path of the action whose async context is currently executing (e.g.
+ * "Build", "Dev › Server"). `SpinHost.launch` wraps each action's `start` in
+ * `actionScope.run(path, …)`, so any `console.*` call inside that action's
+ * (a)synchronous body reads its path here. No store → the call ran outside any
+ * action (the spin body, top-level, a third-party module init).
+ */
+export declare const actionScope: AsyncLocalStorage<string>;
+/**
+ * Patch `console.log/info/debug/warn/error` so each call appends into `logs`
+ * instead of writing to the terminal, attributing every line to the current
+ * action via {@link actionScope}. Returns a `restore()` that reinstalls the
+ * methods that were installed when this ran — so sequential runs nest cleanly
+ * (save-current / restore-saved).
+ *
+ * The patched methods do **not** echo to the terminal: their output reaches it
+ * through the run's log renderer (the caller keeps the original `console.log`
+ * for the renderer's own writes). Args are rendered with `util.format` (exact
+ * console semantics), split on newlines, and appended line-by-line; an empty
+ * render is skipped.
+ */
+export declare function captureConsole(logs: Logger): () => void;

package/dist/output/log/console-capture.js

@@ -0,0 +1,53 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { format } from "node:util";
+/**
+ * The path of the action whose async context is currently executing (e.g.
+ * "Build", "Dev › Server"). `SpinHost.launch` wraps each action's `start` in
+ * `actionScope.run(path, …)`, so any `console.*` call inside that action's
+ * (a)synchronous body reads its path here. No store → the call ran outside any
+ * action (the spin body, top-level, a third-party module init).
+ */
+export const actionScope = new AsyncLocalStorage();
+/** The console methods we fold into the log, each mapped to its log level. */
+const LEVELS = {
+    log: "info",
+    info: "info",
+    debug: "debug",
+    warn: "warn",
+    error: "error",
+};
+/**
+ * Patch `console.log/info/debug/warn/error` so each call appends into `logs`
+ * instead of writing to the terminal, attributing every line to the current
+ * action via {@link actionScope}. Returns a `restore()` that reinstalls the
+ * methods that were installed when this ran — so sequential runs nest cleanly
+ * (save-current / restore-saved).
+ *
+ * The patched methods do **not** echo to the terminal: their output reaches it
+ * through the run's log renderer (the caller keeps the original `console.log`
+ * for the renderer's own writes). Args are rendered with `util.format` (exact
+ * console semantics), split on newlines, and appended line-by-line; an empty
+ * render is skipped.
+ */
+export function captureConsole(logs) {
+    const c = console;
+    const saved = {};
+    const methods = Object.keys(LEVELS);
+    for (const method of methods) {
+        saved[method] = c[method];
+        const level = LEVELS[method];
+        c[method] = (...args) => {
+            const path = actionScope.getStore();
+            const source = path ? `${path} › console` : "console";
+            const text = format(...args);
+            for (const line of text.split("\n")) {
+                if (line)
+                    logs.append({ source, level, message: line });
+            }
+        };
+    }
+    return () => {
+        for (const method of methods)
+            c[method] = saved[method];
+    };
+}

package/dist/system/fs/FolderCache.js

@@ -111,7 +111,9 @@ export class FolderCache {
     }
     /** The on-disk filename for a set of targets — a hash of their absolute paths. */
     static entryPath(paths) {
-        const key = createHash("sha1").update(FolderCache.resolvePaths(paths).sort().join("\0")).digest("hex");
+        const key = createHash("sha1")
+            .update(FolderCache.resolvePaths(paths).sort().join("\0"))
+            .digest("hex");
         return join(FolderCache.dir, `${key}.json`);
     }
 }

package/dist/system/process/process.js

@@ -63,7 +63,11 @@ export const createProc = (logs, signal, snapshots) => (name, opts) => {
         // spread sits before `cwd` so this resolved value wins even when opts omits
         // it). This is the "where" that makes a launch line reproducible.
         const cwd = opts?.cwd ?? process.cwd();
-        const snap = snapshots.captureJson(`proc-${name}-start`, { cmd: child.cmd, ...safeOpts, cwd });
+        const snap = snapshots.captureJson(`proc-${name}-start`, {
+            cmd: child.cmd,
+            ...safeOpts,
+            cwd,
+        });
         logs.append({
             source: name,
             level: "event",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "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",