omkit 0.0.15 → 0.1.0

package/dist/output/log/LogStore.js

@@ -0,0 +1,56 @@
+import { AsyncQueue } from "../../foundation/AsyncQueue.js";
+/**
+ * The run's single append-only timeline. Owns the run-global `sequence`, keeps the
+ * full history (for replay + finalize projections), and fans live entries out to
+ * subscribers. It holds no presentation — headers/prefixes are applied by writers
+ * at read time. Actions receive it only as {@link ReadableLog}.
+ */
+export class LogStore {
+    seq = 0;
+    history = [];
+    subscribers = new Set();
+    ended = false;
+    /** Append one entry; stamps `sequence`/`ts`, retains it, fans it out. */
+    append(input) {
+        const entry = { ...input, sequence: ++this.seq, ts: Date.now() };
+        this.history.push(entry);
+        for (const subscriber of this.subscribers)
+            subscriber.push(entry);
+        return entry;
+    }
+    subscribe({ replay = false } = {}) {
+        const queue = new AsyncQueue();
+        if (replay)
+            for (const entry of this.history)
+                queue.push(entry);
+        if (this.ended)
+            queue.close();
+        else
+            this.subscribers.add(queue);
+        const subscribers = this.subscribers;
+        const inner = queue[Symbol.asyncIterator]();
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    next: () => inner.next(),
+                    return: () => {
+                        subscribers.delete(queue);
+                        queue.close();
+                        return Promise.resolve({ done: true, value: undefined });
+                    },
+                };
+            },
+        };
+    }
+    /** EOF for readers: end every live subscription and refuse new ones. Called once at finalize. */
+    close() {
+        this.ended = true;
+        for (const queue of this.subscribers)
+            queue.close();
+        this.subscribers.clear();
+    }
+    /** The complete history — the source for finalize-time projections (per-node logs, rollups). */
+    entries() {
+        return this.history;
+    }
+}

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

@@ -0,0 +1,11 @@
+import type { LogStore } from "./LogStore.ts";
+/**
+ * Streams every entry to `raw.jsonl` as one JSON object per line, live, for the
+ * whole run — the crash-insurance / machine-merge record. `run(store)` subscribes
+ * (replay + live) and resolves once the store closes and the file is flushed.
+ */
+export declare class RawStream {
+    private readonly file;
+    constructor(absPath: string);
+    run(store: LogStore): Promise<void>;
+}

package/dist/output/log/RawStream.js

@@ -0,0 +1,18 @@
+import { createWriteStream } from "node:fs";
+/**
+ * Streams every entry to `raw.jsonl` as one JSON object per line, live, for the
+ * whole run — the crash-insurance / machine-merge record. `run(store)` subscribes
+ * (replay + live) and resolves once the store closes and the file is flushed.
+ */
+export class RawStream {
+    file;
+    constructor(absPath) {
+        this.file = createWriteStream(absPath, { flags: "w" });
+    }
+    async run(store) {
+        for await (const entry of store.subscribe({ replay: true })) {
+            this.file.write(`${JSON.stringify(entry)}\n`);
+        }
+        await new Promise((resolve) => this.file.end(resolve));
+    }
+}

package/dist/output/snapshot/SnapshotStore.d.ts

@@ -1,49 +1,12 @@
-import type { Logger } from "../log/LogsCollector.ts";
 import type { RunFolder } from "../folder/RunFolder.ts";
-/** A written (or in-flight) snapshot file and where to find it. */
-export interface SnapshotRef {
-    /** Absolute path to the snapshot file. */
-    readonly file: string;
-    /** Path relative to cwd — what a log line references. */
-    readonly rel: string;
-    /** Resolves once the file is flushed to disk. */
-    readonly written: Promise<void>;
-}
 /**
- * Writes sequenced snapshot files into the run folder and (for {@link snapshot})
- * drops a `[snapshot]` pointer line into the timeline.
- *
- * Sequence numbers make repeated snapshots of the same name a history rather than an
- * overwrite. Paths are computed synchronously so a caller can reference the file in
- * the same tick while the write proceeds in the background. Depends on a
- * {@link RunFolder} (where the files land) and a {@link Logger} (only `snapshot`
- * writes a timeline line).
+ * Writes JSON snapshot payloads under the run folder's `snapshots/` dir and returns
+ * each file's **absolute** path (for an absolute link in the log). Sequenced so
+ * names are unique and ordered; attribution (the timeline line) is the caller's job.
  */
 export declare class SnapshotStore {
-    private seq;
     private readonly folder;
-    private readonly log;
-    constructor(folder: RunFolder, log: Logger);
-    /**
-     * Writes `value` as a sequenced JSON snapshot file (`<name>-NN.json`) and returns its
-     * path — **without** logging a pointer line. The path is computed synchronously while
-     * the write proceeds in the background. Use {@link snapshot} when you also want a
-     * `[snapshot]` line in the timeline; the event bus uses this directly to link a
-     * non-string payload from its own line.
-     */
-    captureJson(name: string, value: unknown): SnapshotRef;
-    /**
-     * Writes raw text `lines` as a sequenced `.log` snapshot file — the text sibling of
-     * {@link captureJson}. {@link RunLog.write} uses it to off-load a collapsed output run
-     * from `run.log`, keeping the burst's full text one click away.
-     */
-    captureText(name: string, lines: readonly string[]): SnapshotRef;
-    /**
-     * Captures a value as a JSON snapshot (via {@link captureJson}) and records a
-     * `[snapshot] <name>: <path>` line in the timeline at the point it's taken. Callable
-     * any time, anywhere in the run; resolves with the file path once written.
-     */
-    snapshot(name: string, value: unknown): Promise<string>;
-    /** Shared writer: sequence + sanitize the name, write in the background, return its refs. */
-    private capture;
+    private seq;
+    constructor(folder: RunFolder);
+    write(name: string, value: unknown, nodeId: string): Promise<string>;
 }

package/dist/output/snapshot/SnapshotStore.js

@@ -1,61 +1,21 @@
-import { writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { pad } from "../../utils/format.js";
-import { serialize } from "../../utils/serialize.js";
+import { fsSafe } from "../../foundation/fsSafe.js";
 /**
- * Writes sequenced snapshot files into the run folder and (for {@link snapshot})
- * drops a `[snapshot]` pointer line into the timeline.
- *
- * Sequence numbers make repeated snapshots of the same name a history rather than an
- * overwrite. Paths are computed synchronously so a caller can reference the file in
- * the same tick while the write proceeds in the background. Depends on a
- * {@link RunFolder} (where the files land) and a {@link Logger} (only `snapshot`
- * writes a timeline line).
+ * Writes JSON snapshot payloads under the run folder's `snapshots/` dir and returns
+ * each file's **absolute** path (for an absolute link in the log). Sequenced so
+ * names are unique and ordered; attribution (the timeline line) is the caller's job.
  */
 export class SnapshotStore {
-    seq = 0;
     folder;
-    log;
-    constructor(folder, log) {
+    seq = 0;
+    constructor(folder) {
         this.folder = folder;
-        this.log = log;
-    }
-    /**
-     * Writes `value` as a sequenced JSON snapshot file (`<name>-NN.json`) and returns its
-     * path — **without** logging a pointer line. The path is computed synchronously while
-     * the write proceeds in the background. Use {@link snapshot} when you also want a
-     * `[snapshot]` line in the timeline; the event bus uses this directly to link a
-     * non-string payload from its own line.
-     */
-    captureJson(name, value) {
-        return this.capture(name, "json", `${serialize(value)}\n`);
-    }
-    /**
-     * Writes raw text `lines` as a sequenced `.log` snapshot file — the text sibling of
-     * {@link captureJson}. {@link RunLog.write} uses it to off-load a collapsed output run
-     * from `run.log`, keeping the burst's full text one click away.
-     */
-    captureText(name, lines) {
-        return this.capture(name, "log", lines.length ? `${lines.join("\n")}\n` : "");
-    }
-    /**
-     * Captures a value as a JSON snapshot (via {@link captureJson}) and records a
-     * `[snapshot] <name>: <path>` line in the timeline at the point it's taken. Callable
-     * any time, anywhere in the run; resolves with the file path once written.
-     */
-    snapshot(name, value) {
-        const { file, rel, written } = this.captureJson(name, value);
-        // Record the pointer synchronously, so it sits at the right spot in the timeline.
-        this.log.append({ source: "snapshot", level: "snapshot", message: `${name}: ${rel}` });
-        return written.then(() => file);
     }
-    /** Shared writer: sequence + sanitize the name, write in the background, return its refs. */
-    capture(name, ext, body) {
-        const safe = name.replace(/[^\w.-]+/g, "-");
-        const file = this.folder.resolve(`${safe}-${pad(++this.seq)}.${ext}`);
-        const written = this.folder.ensure().then(() => writeFile(file, body, "utf8"));
-        // Normalize to forward slashes so the reference is portable in the log artifact.
-        const rel = path.relative(process.cwd(), file).replaceAll("\\", "/");
-        return { file, rel, written };
+    async write(name, value, nodeId) {
+        const file = this.folder.file(path.join("snapshots", `${++this.seq}-${fsSafe(nodeId)}-${fsSafe(name)}.json`));
+        await mkdir(path.dirname(file), { recursive: true });
+        await writeFile(file, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+        return file;
     }
 }

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

@@ -0,0 +1,8 @@
+import type { LogEntry } from "../../foundation/LogEntry.ts";
+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.
+ */
+export declare function writeNodeLogs(nodes: readonly NodeView[], entries: readonly LogEntry[]): Promise<void>;

package/dist/output/writers/NodeLogWriter.js

@@ -0,0 +1,36 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { renderRef } from "../../foundation/ActionRef.js";
+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.
+ */
+export async function writeNodeLogs(nodes, entries) {
+    const byNode = groupByNode(entries, () => true);
+    await Promise.all(nodes.map(async (node) => {
+        const lines = (byNode.get(node.id) ?? []).map(entryLine);
+        const body = [...header(node), "", ...lines, ""].join("\n");
+        await mkdir(path.dirname(node.logFile), { recursive: true });
+        await writeFile(node.logFile, body, "utf8");
+    }));
+}
+/** The per-file metadata header: ref, args, start/finish times, duration, status. */
+const header = (node) => [
+    `# ${renderRef(node)}`,
+    `#   log:      ${node.logFile}`,
+    `#   args:     ${renderArgs(node.args)}`,
+    `#   started:  ${stamp(node.startedAt)}`,
+    `#   finished: ${stamp(node.endedAt)} (${node.duration}ms)`,
+    `#   status:   ${node.status}`,
+];
+const stamp = (ms) => (ms ? new Date(ms).toISOString() : "-");
+const renderArgs = (args) => {
+    try {
+        return JSON.stringify(args);
+    }
+    catch {
+        return String(args);
+    }
+};

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

@@ -0,0 +1,3 @@
+import type { RunView } from "./views.ts";
+/** Serializes the whole run tree + verdict to `result.json`. */
+export declare function writeResult(file: string, run: RunView): Promise<void>;

package/dist/output/writers/ResultWriter.js

@@ -0,0 +1,5 @@
+import { writeFile } from "node:fs/promises";
+/** Serializes the whole run tree + verdict to `result.json`. */
+export async function writeResult(file, run) {
+    await writeFile(file, `${JSON.stringify(run, null, 2)}\n`, "utf8");
+}

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

@@ -0,0 +1,9 @@
+import type { LogEntry } from "../../foundation/LogEntry.ts";
+import type { NodeView } from "./views.ts";
+/**
+ * A cross-cutting rollup: entries matching one facet (e.g. `level === "event"`), in
+ * **global sequence order**. A little action header is inserted whenever the
+ * emitting action changes, so the file reads as a chronological timeline of that
+ * facet across the run — not grouped per action. `footer`, if given, is appended.
+ */
+export declare function writeRollup(file: string, nodes: readonly NodeView[], entries: readonly LogEntry[], match: (e: LogEntry) => boolean, footer?: string): Promise<void>;

package/dist/output/writers/RollupWriter.js

@@ -0,0 +1,29 @@
+import { writeFile } from "node:fs/promises";
+import { renderRef } from "../../foundation/ActionRef.js";
+import { entryLine } from "./entryLine.js";
+/**
+ * A cross-cutting rollup: entries matching one facet (e.g. `level === "event"`), in
+ * **global sequence order**. A little action header is inserted whenever the
+ * emitting action changes, so the file reads as a chronological timeline of that
+ * facet across the run — not grouped per action. `footer`, if given, is appended.
+ */
+export async function writeRollup(file, nodes, entries, match, footer) {
+    const refByNode = new Map(nodes.map((n) => [n.id, n]));
+    const chunks = [];
+    let lastNode = null;
+    for (const e of entries) {
+        if (!match(e))
+            continue;
+        if (e.nodeId !== lastNode) {
+            if (chunks.length)
+                chunks.push(""); // blank line before the next action's header
+            const ref = refByNode.get(e.nodeId);
+            chunks.push(`# ${ref ? renderRef(ref) : e.path}`);
+            lastNode = e.nodeId;
+        }
+        chunks.push(entryLine(e));
+    }
+    if (footer)
+        chunks.push("", footer);
+    await writeFile(file, `${chunks.join("\n")}\n`, "utf8");
+}

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

@@ -0,0 +1,10 @@
+import type { LogEntry } from "../../foundation/LogEntry.ts";
+/**
+ * The shared human-readable row: `[<seq>] <body>`. Only the run-global sequence
+ * prefixes the line (date/path live in the file header + `raw.jsonl`). Event,
+ * snapshot, and assert lines carry a leading icon; everything else keeps its
+ * `source` (proc name, child id, `console`, …).
+ */
+export declare const entryLine: (e: LogEntry) => string;
+/** Group entries by `nodeId` (preserving order), keeping only those that `match`. */
+export declare const groupByNode: (entries: readonly LogEntry[], match: (e: LogEntry) => boolean) => Map<string, LogEntry[]>;

package/dist/output/writers/entryLine.js

@@ -0,0 +1,39 @@
+/**
+ * The shared human-readable row: `[<seq>] <body>`. Only the run-global sequence
+ * prefixes the line (date/path live in the file header + `raw.jsonl`). Event,
+ * snapshot, and assert lines carry a leading icon; everything else keeps its
+ * `source` (proc name, child id, `console`, …).
+ */
+export const entryLine = (e) => `[${e.sequence}] ${bodyOf(e)}`;
+const bodyOf = (e) => {
+    switch (e.level) {
+        case "event":
+            return `⚡ ${e.message}`;
+        case "snapshot":
+            return `📸 ${e.message}`;
+        case "assert":
+            return e.message; // already ⊨/⊭-prefixed
+        // Plain output (console.log, proc stdout) — no action-name prefix, just a quiet marker.
+        case "info":
+            return `▪ ${e.message}`;
+        case "error":
+            // An action's *own* failure keeps a ✗; proc stderr / console.error is plain
+            // output. (Cancellation no longer logs at this level — it's a clean stop.)
+            return e.source === "error" ? `✗ ${e.message}` : `▪ ${e.message}`;
+        // run/done milestones, tags, and bubbled child lines keep their `source` label.
+        default:
+            return `${e.source} · ${e.message}`;
+    }
+};
+/** Group entries by `nodeId` (preserving order), keeping only those that `match`. */
+export const groupByNode = (entries, match) => {
+    const byNode = new Map();
+    for (const e of entries) {
+        if (!match(e))
+            continue;
+        const list = byNode.get(e.nodeId) ?? [];
+        list.push(e);
+        byNode.set(e.nodeId, list);
+    }
+    return byNode;
+};

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

@@ -0,0 +1,38 @@
+/**
+ * Plain, serializable projections the `core` layer builds from the tree and hands
+ * to the writers. Kept here (output) as data-only shapes so the writers never
+ * import `core`.
+ */
+export interface NodeView {
+    readonly id: string;
+    readonly uuid: string;
+    readonly name: string;
+    readonly path: string;
+    readonly parentId: string | null;
+    readonly tags: readonly string[];
+    readonly args: readonly unknown[];
+    readonly status: string;
+    readonly startedAt: number;
+    readonly endedAt: number;
+    readonly duration: number;
+    /** Absolute path to this node's own `.log`. */
+    readonly logFile: string;
+    readonly children: readonly NodeView[];
+}
+export interface RunView {
+    readonly ok: boolean;
+    readonly failures: ReadonlyArray<{
+        action: string;
+        error: string;
+    }>;
+    readonly assertions: {
+        readonly passed: number;
+        readonly failed: number;
+    };
+    readonly startedAt: number;
+    readonly endedAt: number;
+    readonly duration: number;
+    /** Absolute path to `raw.jsonl`. */
+    readonly rawStream: string;
+    readonly root: NodeView;
+}

package/dist/output/writers/views.js

@@ -0,0 +1,6 @@
+/**
+ * Plain, serializable projections the `core` layer builds from the tree and hands
+ * to the writers. Kept here (output) as data-only shapes so the writers never
+ * import `core`.
+ */
+export {};

package/dist/system/fs/FolderCache.d.ts

@@ -2,46 +2,18 @@
  * An input-fingerprint cache: hash the mtime+size of one or more **input**
  * targets (the files/folders an action reads — *not* what it produces), so an
  * expensive action can be skipped when its inputs are unchanged since its last
- * successful run. Backs the `.withCache(...)` method on action instances.
- *
- * Entries live under `node_modules/.cache/omkit/` (conventional, gitignored) —
- * one JSON file per set of inputs, named by a hash of their absolute paths.
- *
- * Stateless — the cache is the filesystem, so the methods are `static`. Internal
- * cross-references go through the class name (not `this`), so a caller may pull a
- * method off the class (`const fp = FolderCache.fingerprint`) without losing it.
+ * successful run. Backs `.withCache(...)` on action instances. Entries live under
+ * `node_modules/.cache/omkit/`. Stateless — the cache is the filesystem.
  */
 export declare class FolderCache {
-    /** Where cache entries are written — `node_modules/.cache/omkit/` under the cwd. */
     static readonly dir: string;
-    /**
-     * Require every path to be **absolute** (a relative path is a developer error —
-     * throws, naming it) and return them canonicalized with `resolve`, so different
-     * spellings of the same target (`.`/`..`/trailing slash) collapse to one stable
-     * fingerprint prefix and cache key. `resolve` on an already-absolute path only
-     * normalizes — it never falls back to the cwd. Each target may be a file or a
-     * folder (see {@link FolderCache.fingerprint}).
-     */
+    /** Require absolute paths (throws otherwise) and canonicalize them for a stable key. */
     static resolvePaths(paths: string[]): string[];
-    /**
-     * Fingerprints one or more **input** targets by mtime+size. Each target may be
-     * a **file** (fingerprinted directly) or a **folder** (walked recursively, its
-     * files fingerprinted). Every path must be absolute (throws otherwise). A
-     * missing target contributes nothing — so an input that doesn't exist yet is
-     * naturally a miss, not an error. The entry list is sorted for determinism
-     * before hashing.
-     */
+    /** Fingerprint input targets by mtime+size (files directly, folders walked). Missing = no entries. */
     static fingerprint(paths: string[]): Promise<string>;
-    /**
-     * Reads the fingerprint stored for these targets, or `undefined` when there's
-     * no cache (absent, unreadable, or malformed — all treated as a miss).
-     */
+    /** The stored fingerprint for these targets, or `undefined` on any miss. */
     static read(paths: string[]): Promise<string | undefined>;
-    /**
-     * Records the fingerprint for these targets after a successful run. Writes
-     * atomically (temp file + rename) so a concurrent read never sees a half-file.
-     */
+    /** Record the fingerprint after a successful run (atomic temp+rename). */
     static write(paths: string[], fp: string): Promise<void>;
-    /** The on-disk filename for a set of targets — a hash of their absolute paths. */
     private static entryPath;
 }

package/dist/system/fs/FolderCache.js

@@ -5,42 +5,20 @@ import { isAbsolute, join, resolve } from "node:path";
  * An input-fingerprint cache: hash the mtime+size of one or more **input**
  * targets (the files/folders an action reads — *not* what it produces), so an
  * expensive action can be skipped when its inputs are unchanged since its last
- * successful run. Backs the `.withCache(...)` method on action instances.
- *
- * Entries live under `node_modules/.cache/omkit/` (conventional, gitignored) —
- * one JSON file per set of inputs, named by a hash of their absolute paths.
- *
- * Stateless — the cache is the filesystem, so the methods are `static`. Internal
- * cross-references go through the class name (not `this`), so a caller may pull a
- * method off the class (`const fp = FolderCache.fingerprint`) without losing it.
+ * successful run. Backs `.withCache(...)` on action instances. Entries live under
+ * `node_modules/.cache/omkit/`. Stateless — the cache is the filesystem.
  */
 export class FolderCache {
-    /** Where cache entries are written — `node_modules/.cache/omkit/` under the cwd. */
     static dir = join(process.cwd(), "node_modules", ".cache", "omkit");
-    /**
-     * Require every path to be **absolute** (a relative path is a developer error —
-     * throws, naming it) and return them canonicalized with `resolve`, so different
-     * spellings of the same target (`.`/`..`/trailing slash) collapse to one stable
-     * fingerprint prefix and cache key. `resolve` on an already-absolute path only
-     * normalizes — it never falls back to the cwd. Each target may be a file or a
-     * folder (see {@link FolderCache.fingerprint}).
-     */
+    /** Require absolute paths (throws otherwise) and canonicalize them for a stable key. */
     static resolvePaths(paths) {
         return paths.map((p) => {
-            if (!isAbsolute(p)) {
+            if (!isAbsolute(p))
                 throw new Error(`withCache: path must be absolute, got "${p}"`);
-            }
             return resolve(p);
         });
     }
-    /**
-     * Fingerprints one or more **input** targets by mtime+size. Each target may be
-     * a **file** (fingerprinted directly) or a **folder** (walked recursively, its
-     * files fingerprinted). Every path must be absolute (throws otherwise). A
-     * missing target contributes nothing — so an input that doesn't exist yet is
-     * naturally a miss, not an error. The entry list is sorted for determinism
-     * before hashing.
-     */
+    /** Fingerprint input targets by mtime+size (files directly, folders walked). Missing = no entries. */
     static async fingerprint(paths) {
         const targets = FolderCache.resolvePaths(paths);
         const entries = [];
@@ -55,12 +33,10 @@ export class FolderCache {
             catch {
                 continue; // missing/unreadable — contributes no entries
             }
-            // A file target fingerprints itself (empty rel — there's no walk).
             if (root.isFile()) {
                 record(target, "", root.mtimeMs, root.size);
                 continue;
             }
-            // A folder target: walk it and fingerprint every file inside.
             let rels;
             try {
                 rels = await readdir(target, { recursive: true });
@@ -83,10 +59,7 @@ export class FolderCache {
         entries.sort();
         return createHash("sha1").update(entries.join("\n")).digest("hex");
     }
-    /**
-     * Reads the fingerprint stored for these targets, or `undefined` when there's
-     * no cache (absent, unreadable, or malformed — all treated as a miss).
-     */
+    /** The stored fingerprint for these targets, or `undefined` on any miss. */
     static async read(paths) {
         try {
             const raw = await readFile(FolderCache.entryPath(paths), "utf8");
@@ -97,10 +70,7 @@ export class FolderCache {
             return undefined;
         }
     }
-    /**
-     * Records the fingerprint for these targets after a successful run. Writes
-     * atomically (temp file + rename) so a concurrent read never sees a half-file.
-     */
+    /** Record the fingerprint after a successful run (atomic temp+rename). */
     static async write(paths, fp) {
         await mkdir(FolderCache.dir, { recursive: true });
         const target = FolderCache.entryPath(paths);
@@ -109,7 +79,6 @@ export class FolderCache {
         await writeFile(tmp, JSON.stringify(entry, null, 2));
         await rename(tmp, target);
     }
-    /** 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"))

package/dist/system/proc.d.ts

@@ -0,0 +1,51 @@
+import { type Options, type ProcessPromise } from "zx";
+import { ProcRegistry } from "./procRegistry.ts";
+/**
+ * Force-kill a process **and its whole tree, synchronously**.
+ *
+ * On POSIX the child is spawned as its own process-group leader (see createProc), so
+ * `kill(-pid)` reaps the whole group in one call — every descendant, re-parented or not.
+ *
+ * On Windows there are no process groups and we can't detach (a console-less child breaks
+ * npm/vite — see createProc), so a mashed Ctrl+C sent to the shared console can make an
+ * intermediate shell (powershell/npm/npx) exit and orphan its real leaf (vite,
+ * chromedriver.exe) before teardown reaps it. `taskkill /F /T` force-kills the live tree
+ * by PID, but a leaf whose intermediate already exited can't be reached via `/T` — that
+ * mash-Ctrl+C orphan is a known Windows edge, mitigated by a port/PID sweep on teardown
+ * rather than by detaching. Best-effort: an already-dead PID is ignored.
+ */
+export declare const killTree: (pid: number) => void;
+/**
+ * A copy of `env` with the orchestrator's debugger stripped, so a spawned child runs
+ * clean instead of inheriting our inspector. Removes `--inspect*` flags from
+ * `NODE_OPTIONS`, drops VS Code auto-attach's injected bootloader `--require` and its
+ * `VSCODE_INSPECTOR_OPTIONS` handshake, and deletes `NODE_OPTIONS` entirely if nothing
+ * else remains. A legitimate non-debug `--require` and any other options are preserved.
+ * Does not mutate the input.
+ */
+export declare const debuggerFreeEnv: (env: NodeJS.ProcessEnv) => NodeJS.ProcessEnv;
+/** Where a proc writes its lines — bound by the framework to the owning node's log. */
+export type ProcSink = (source: string, level: string, message: string) => void;
+/** zx spawn options plus omkit's own knobs. */
+export type ProcOptions = Partial<Options> & {
+    /**
+     * Let this child inherit the orchestrator's debugger instead of running clean
+     * (default false). Also enabled for every child by the `OMKIT_INHERIT_DEBUGGER`
+     * env var. See {@link debuggerFreeEnv}.
+     */
+    inheritDebugger?: boolean;
+};
+/** Spawn a shell command (zx tagged-template), streaming its output into the log. */
+export type Proc = (name: string, opts?: ProcOptions) => (pieces: TemplateStringsArray, ...args: unknown[]) => ProcessPromise;
+/**
+ * The run-wide orphan reaper. `createProc` registers each shell it spawns (Windows only);
+ * the ExecutionTree calls `procRegistry.sweep()` at teardown to reap any that a mashed
+ * Ctrl+C orphaned. A no-op in practice off Windows (nothing is tracked there).
+ */
+export declare const procRegistry: ProcRegistry;
+/**
+ * Build a {@link Proc} bound to a log sink and abort signal. The framework injects
+ * one per action as `ctx.proc`, wired to that action's log and the run's signal, so
+ * actions just describe the command — output streams in, the child dies on teardown.
+ */
+export declare const createProc: (sink: ProcSink, signal: AbortSignal) => Proc;