omkit 0.0.10 → 0.0.12

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,11 +64,11 @@ 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()}` });
+        logs.append({ source: label, level: "info", message: `console: ${msg.text()}` });
         emit("console", msg.text());
     });
     page.on("pageerror", (err) => {
-        logs.append({ source: "Chrome Page", level: "error", message: err.message });
+        logs.append({ source: label, level: "error", message: err.message });
         emit("pageerror", err.message);
     });
     page.on("framenavigated", (frame) => {
@@ -73,10 +77,10 @@ export const chromePage = action("Chrome Page")
     });
     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/index.d.ts

@@ -17,7 +17,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/orchestration/action/action.js

@@ -66,6 +66,7 @@ class ActionRun {
             attach: (value) => this.attach(value),
             proc: createProc(system.logs, system.signal, system.output.snapshots),
             artifactsFolder: system.output.folder.artifacts(),
+            snapshot: (name, value) => system.output.snapshots.snapshot(name, value),
         }, ...this.args))
             .then((result) => {
             const outcome = { ok: true, value: result };

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

@@ -86,6 +86,13 @@ export interface ActionContext<Events extends object, Handle = void> extends Sys
      * beside `run.log`; the same folder is on the `spin` context.
      */
     readonly artifactsFolder: string;
+    /**
+     * Capture a JSON snapshot into this run's output folder and drop a `[snapshot]`
+     * line on the timeline (under this action's path). The ergonomic shortcut for
+     * `ctx.output.snapshots.snapshot(…)`; the same convenience is on the `spin`
+     * context. Resolves with the snapshot's relative path.
+     */
+    readonly snapshot: (name: string, value: unknown) => Promise<string>;
 }
 /** A constructed-but-not-yet-run action: what calling an `Action` produces. */
 export interface ActionInstance<Result = unknown, Events extends object = NoEvents, Handle = void> {
@@ -106,7 +113,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/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,6 +2,7 @@ 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";
 /** The entry script, relative to where node was invoked (so the log says what produced it). */
 const scriptPath = () => {
@@ -58,6 +59,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 +94,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 +161,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 +217,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) {
@@ -247,8 +258,8 @@ 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 }))
             .then((outcome) => {
             if (!outcome.ok)
                 record(outcome.error);
@@ -282,6 +293,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 +303,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;

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.10",
+  "version": "0.0.12",
   "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",