omkit 0.0.15 → 0.1.0

package/dist/actions/watch.js

@@ -1,18 +1,14 @@
 import { watch as fsWatch } from "node:fs";
 import { stat } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
-import { action } from "../orchestration/action/action.js";
+import { action } from "../core/action.js";
 /**
  * Watches a single file that may not exist yet, firing callbacks on its
- * transitions. Since `fs.watch` can't watch a missing path, it watches the
- * parent directory and filters by name; on each event it re-`stat`s and diffs
- * against the last known state rather than trusting the raw event type. Runs
- * until the run's signal aborts, then closes the watcher.
- *
- * Assumes the parent directory exists; watching when an ancestor is missing is
- * a later case.
+ * transitions. Watches the parent directory and filters by name (so a missing
+ * file can be awaited), re-`stat`ing on each event to diff against last state.
+ * Daemon: runs until the run's signal aborts, then closes the watcher.
  */
-export const watch = action("Watch").run(({ logs, signal }, target, opts = {}) => {
+export const watch = action("watch").run(({ signal }, target, opts = {}) => {
     const { onMissing, onCreate, onUpdate, onDelete, debounceMs = 50 } = opts;
     const file = resolve(target);
     const dir = dirname(file);
@@ -31,23 +27,23 @@ export const watch = action("Watch").run(({ logs, signal }, target, opts = {}) =
             if (!present) {
                 present = true;
                 mtimeMs = stats.mtimeMs;
-                logs.append({ source: name, level: "info", message: `created ${file}` });
+                console.log(`created ${file}`);
                 onCreate?.({ path: file, isInitial, stats });
             }
             else if (stats.mtimeMs !== mtimeMs) {
                 mtimeMs = stats.mtimeMs;
-                logs.append({ source: name, level: "info", message: `updated ${file}` });
+                console.log(`updated ${file}`);
                 onUpdate?.({ path: file, isInitial, stats });
             }
         }
         else if (present) {
             present = false;
             mtimeMs = 0;
-            logs.append({ source: name, level: "info", message: `deleted ${file}` });
+            console.log(`deleted ${file}`);
             onDelete?.({ path: file, isInitial });
         }
         else if (isInitial) {
-            logs.append({ source: name, level: "info", message: `missing ${file}` });
+            console.log(`missing ${file}`);
             onMissing?.({ path: file, isInitial });
         }
     };
@@ -57,14 +53,11 @@ export const watch = action("Watch").run(({ logs, signal }, target, opts = {}) =
             clearTimeout(timer);
         timer = setTimeout(() => void recheck(false), debounceMs);
     };
-    // Watch the parent dir (the file may not exist yet) and filter by name.
-    // Some platforms pass a null filename — recheck anyway, it's a cheap stat.
     const watcher = fsWatch(dir, (_event, filename) => {
         if (filename === null || filename === name)
             schedule();
     });
     void recheck(true); // report the initial state
-    // Daemon: stay alive until torn down, then close the watcher.
     return new Promise((resolveRun) => {
         const stop = () => {
             if (timer)

package/dist/core/ActionRun.d.ts

@@ -0,0 +1,97 @@
+import { type EventHandler } from "../foundation/events.ts";
+import type { ActionRef } from "../foundation/ActionRef.ts";
+import type { LogStore } from "../output/log/LogStore.ts";
+import type { SnapshotStore } from "../output/snapshot/SnapshotStore.ts";
+import type { Exec, InstanceEvents, NodeStatus, Outcome, RunHandle } from "./types.ts";
+/** Everything a node needs to exist, minus its behavior. */
+export interface NodeInit {
+    readonly store: LogStore;
+    readonly name: string;
+    readonly uuid: string;
+    /** `${name}_${shortId}`, or `main` for the root. */
+    readonly id: string;
+    /** Ancestry of ids joined by `/`. */
+    readonly path: string;
+    readonly parentId: string | null;
+    /** The parent's signal — this node's controller chains off it. */
+    readonly parentSignal: AbortSignal | null;
+    /** The run's snapshot store — backs `ctx.snapshot`. */
+    readonly snapshots: SnapshotStore;
+    /** Absolute path to the run's output folder — backs `ctx.artifactsFolder`. */
+    readonly artifactsFolder: string;
+    /** Report an assertion outcome to the run verdict. */
+    readonly onAssert: (pass: boolean, path: string, message: string) => void;
+    /** Called when this node fails while unobserved — the tree tears down + records a fault. */
+    readonly onUnhandledFailure: (path: string, error: unknown) => void;
+    /** Bubble a milestone line into this node's parent log (no-op for the root). */
+    readonly bubble: (message: string) => void;
+}
+/**
+ * One node in the {@link ExecutionTree}: its identity, tags, timing, and terminal
+ * state, plus the run handle (`result`/`ref`/`once`/`tag`/`cancel`). Self-contained —
+ * `run(exec, args)` executes the body inside the error boundary and settles the
+ * node; it never throws (the failure is delivered through `.result`).
+ */
+export declare class ActionRun<Result = unknown, Events extends object = object, Handle = unknown> implements RunHandle<Result, Events, Handle> {
+    readonly id: string;
+    readonly uuid: string;
+    readonly name: string;
+    readonly path: string;
+    readonly parentId: string | null;
+    readonly tags: string[];
+    /** The captured args this node ran with (for the log header); set at run start. */
+    args: readonly unknown[];
+    readonly children: ActionRun[];
+    readonly controller: AbortController;
+    status: NodeStatus;
+    value: Result | undefined;
+    error: unknown;
+    startedAt: number;
+    endedAt: number;
+    duration: number;
+    private readonly store;
+    private readonly snapshots;
+    private readonly artifactsFolder;
+    private readonly onAssert;
+    private readonly onUnhandledFailure;
+    private readonly bubble;
+    private readonly emitter;
+    private readonly settled;
+    private readonly handle;
+    private failureHandler;
+    private attached;
+    private observed;
+    private refObserved;
+    private cascadeCancelled;
+    constructor(init: NodeInit);
+    /** A stable reference for headers/attribution (tags are the accumulated set now). */
+    toRef(): ActionRef;
+    /** This node's abort signal — handed to the exec as `ctx.signal`. */
+    get signal(): AbortSignal;
+    get result(): Promise<Outcome<Result>>;
+    /** The attached handle; rejects on failure/cancel. */
+    get ref(): Promise<Handle>;
+    on<K extends keyof InstanceEvents<Events, Result>>(key: K, handler: EventHandler<InstanceEvents<Events, Result>[K]>): void;
+    once<K extends keyof InstanceEvents<Events, Result>>(key: K): Promise<InstanceEvents<Events, Result>[K] | undefined>;
+    tag(name: string): this;
+    handleFailure(handler: (error: unknown) => void): this;
+    cancel(): void;
+    /** Run the body inside the error boundary, settling the node. Never rejects. */
+    run(exec: Exec<Events, Handle, Result>, args: readonly unknown[]): Promise<void>;
+    private context;
+    private assertInvariant;
+    private captureSnapshot;
+    private attach;
+    private succeed;
+    private fail;
+    /** The framework's own emits (loosely typed — sidesteps EmitArgs for void payloads). */
+    private sysEmit;
+    private finishTiming;
+    /**
+     * A lifecycle transition (`launched`, `done · ok|failed|cancelled`) — logged as an
+     * `event` on this node so it joins the unified event stream (`events.log`) and the
+     * node's own log, distinct from user emits by its `lifecycle` source.
+     */
+    private lifecycle;
+    private log;
+}

package/dist/core/ActionRun.js

@@ -0,0 +1,266 @@
+import { defer } from "../foundation/Deferred.js";
+import { events } from "../foundation/events.js";
+import { CancelledError } from "../foundation/CancelledError.js";
+import { renderValue } from "../foundation/format.js";
+import { createProc } from "../system/proc.js";
+/**
+ * One node in the {@link ExecutionTree}: its identity, tags, timing, and terminal
+ * state, plus the run handle (`result`/`ref`/`once`/`tag`/`cancel`). Self-contained —
+ * `run(exec, args)` executes the body inside the error boundary and settles the
+ * node; it never throws (the failure is delivered through `.result`).
+ */
+export class ActionRun {
+    id;
+    uuid;
+    name;
+    path;
+    parentId;
+    tags = [];
+    /** The captured args this node ran with (for the log header); set at run start. */
+    args = [];
+    children = [];
+    controller = new AbortController();
+    status = "running";
+    value;
+    error;
+    startedAt = 0;
+    endedAt = 0;
+    duration = 0;
+    store;
+    snapshots;
+    artifactsFolder;
+    onAssert;
+    onUnhandledFailure;
+    bubble;
+    emitter = events();
+    settled = defer();
+    handle = defer();
+    failureHandler;
+    attached = false;
+    observed = false;
+    refObserved = false;
+    // Set only by the parent-signal abort listener (an ANCESTOR cancelling this node).
+    // Distinguishes a run/ancestor teardown from this node's own subtree-abort on failure,
+    // so the unobserved-failure check below isn't fooled by our own controller.abort().
+    cascadeCancelled = false;
+    constructor(init) {
+        this.id = init.id;
+        this.uuid = init.uuid;
+        this.name = init.name;
+        this.path = init.path;
+        this.parentId = init.parentId;
+        this.store = init.store;
+        this.snapshots = init.snapshots;
+        this.artifactsFolder = init.artifactsFolder;
+        this.onAssert = init.onAssert;
+        this.onUnhandledFailure = init.onUnhandledFailure;
+        this.bubble = init.bubble;
+        // Chain cancellation: an ancestor's abort ⇒ this subtree aborts (and is flagged as a
+        // cascade, so a concurrent own-failure isn't misread as a fresh unhandled fault).
+        const parent = init.parentSignal;
+        const onAncestorAbort = () => {
+            this.cascadeCancelled = true;
+            this.controller.abort();
+        };
+        if (parent) {
+            if (parent.aborted)
+                onAncestorAbort();
+            else
+                parent.addEventListener("abort", onAncestorAbort, { once: true });
+        }
+        // A void-handle awaiter shouldn't surface an unhandled rejection at settle.
+        void this.handle.promise.catch(() => { });
+        // An unobserved failure is routed to teardown explicitly; swallow the raw rejection
+        // here (via the field, not the `done` getter) so it isn't also an unhandledRejection.
+        void this.settled.promise.catch(() => { });
+    }
+    /** A stable reference for headers/attribution (tags are the accumulated set now). */
+    toRef() {
+        return { id: this.id, name: this.name, path: this.path, tags: [...this.tags] };
+    }
+    /** This node's abort signal — handed to the exec as `ctx.signal`. */
+    get signal() {
+        return this.controller.signal;
+    }
+    // ── Run handle surface ─────────────────────────────────────────────────────
+    get result() {
+        this.observed = true;
+        return this.settled.promise.then((value) => ({ ok: true, value }), (error) => ({ ok: false, error }));
+    }
+    /** The attached handle; rejects on failure/cancel. */
+    get ref() {
+        this.refObserved = true;
+        return this.handle.promise;
+    }
+    on(key, handler) {
+        // A late `on("error")` (e.g. attached after a synchronously-throwing body already
+        // failed inline during `.exec()`) still receives the failure: the emitter snapshots
+        // the last "error" payload and replays it to a new listener.
+        if (key === "error")
+            this.observed = true;
+        this.emitter.listen(key, handler);
+    }
+    once(key) {
+        if (key === "error")
+            this.observed = true;
+        if (key === "done") {
+            return this.settled.promise.then((v) => v, () => undefined);
+        }
+        return new Promise((resolve) => {
+            let done = false;
+            const settle = (v) => {
+                if (!done) {
+                    done = true;
+                    resolve(v);
+                }
+            };
+            const doneKey = "done";
+            this.emitter.listenOnce(key, (p) => settle(p));
+            this.emitter.listenOnce(doneKey, () => settle(undefined));
+        });
+    }
+    tag(name) {
+        this.tags.push(name);
+        this.log("tag", "tag", name);
+        return this;
+    }
+    handleFailure(handler) {
+        this.failureHandler = handler;
+        this.observed = true;
+        // A synchronously-throwing body fails inline during `.exec()`, before this attaches:
+        // deliver the already-recorded failure now (it won't fail again). Cancellation is
+        // status "cancelled", not "failed", so a cancelled node never runs the handler.
+        if (this.status === "failed")
+            handler(this.error);
+        return this;
+    }
+    cancel() {
+        this.controller.abort();
+    }
+    // ── Execution ──────────────────────────────────────────────────────────────
+    /** Run the body inside the error boundary, settling the node. Never rejects. */
+    async run(exec, args) {
+        this.args = args;
+        this.startedAt = Date.now();
+        this.lifecycle("launched");
+        try {
+            const result = await exec(this.context(), ...args);
+            this.succeed(result);
+        }
+        catch (error) {
+            this.fail(error);
+        }
+    }
+    context() {
+        return {
+            signal: this.signal,
+            logs: this.store,
+            emit: ((key, payload) => {
+                this.emitter.emit(key, payload);
+                const rendered = payload === undefined ? "" : ` · ${renderValue(payload)}`;
+                this.log("event", "event", `${String(key)}${rendered}`);
+                this.bubble(`⚡ ${String(key)}${rendered}`);
+            }),
+            attach: (handle) => this.attach(handle),
+            tag: (name) => void this.tag(name),
+            assert: (condition, message) => this.assertInvariant(condition, message),
+            snapshot: (name, value) => this.captureSnapshot(name, value),
+            artifactsFolder: this.artifactsFolder,
+            proc: createProc((source, level, message) => this.store.append({ nodeId: this.id, path: this.path, level, source, message }), this.signal),
+        };
+    }
+    assertInvariant(condition, message) {
+        const line = `${condition ? "⊨ pass" : "⊭ FAIL"} · ${message}`;
+        this.log("assert", "assert", line);
+        this.bubble(line);
+        this.onAssert(condition, this.path, message);
+    }
+    async captureSnapshot(name, value) {
+        const file = await this.snapshots.write(name, value, this.id);
+        this.log("snapshot", "snapshot", `${name} → ${file}`);
+        this.bubble(`📸 ${name} → ${file}`);
+        return file;
+    }
+    attach(handle) {
+        if (this.attached)
+            return;
+        this.attached = true;
+        this.handle.resolve(handle);
+        this.sysEmit("attached");
+        this.bubble("attached");
+    }
+    succeed(result) {
+        this.finishTiming();
+        this.status = "ok";
+        this.value = result;
+        this.lifecycle("done · ok");
+        this.bubble("✓ done · ok");
+        this.settled.resolve(result);
+        this.sysEmit("done", result);
+        // Settle a never-attached void handle so `.ref` awaiters resolve instead of hang.
+        this.handle.resolve(undefined);
+    }
+    fail(error) {
+        this.finishTiming();
+        // Classify: an aborted signal ⇒ intentional teardown, not a fault. The thrown
+        // error is then just the killed-child artifact (often blank), so we drop it and
+        // record a clean stop; a genuine failure keeps its error and the ✗ styling.
+        if (this.signal.aborted) {
+            this.status = "cancelled";
+            this.error = error;
+            this.lifecycle("done · cancelled");
+            this.bubble("⊘ done · cancelled");
+            this.sysEmit("done", undefined);
+            this.settled.reject(new CancelledError());
+            this.handle.reject(new CancelledError());
+            return;
+        }
+        this.status = "failed";
+        this.error = error;
+        this.log("error", "error", messageOf(error));
+        this.bubble(`✗ ${firstLine(messageOf(error))}`);
+        this.sysEmit("error", error);
+        this.lifecycle("done · failed");
+        this.bubble("✗ done · failed");
+        this.sysEmit("done", undefined);
+        this.settled.reject(error);
+        this.handle.reject(error);
+        // A failed action's work is over: abort its OWN subtree (children → CancelledError,
+        // procs killed). This is local cleanup, independent of the run verdict. It sets our
+        // signal.aborted, which is why the check below uses `cascadeCancelled`, not
+        // `signal.aborted`, to tell an unhandled fault from a run/ancestor teardown.
+        this.controller.abort();
+        // A registered handler owns a fire-and-forget failure (side effect only; not on cancel).
+        this.failureHandler?.(error);
+        // If, one microtask on, no one is positioned to receive this error (no `.result`/`.ref`
+        // read, no `on("error")`) and we weren't caught in an ancestor's teardown, it's
+        // unhandled — tell the tree to tear the run down and record the fault.
+        // `sysEmit("error")` above already ran, so a live error handler has set `observed`.
+        queueMicrotask(() => {
+            const observed = this.observed || (this.refObserved && !this.attached);
+            if (!observed && !this.cascadeCancelled)
+                this.onUnhandledFailure(this.path, error);
+        });
+    }
+    /** The framework's own emits (loosely typed — sidesteps EmitArgs for void payloads). */
+    sysEmit(key, payload) {
+        this.emitter.emit(key, payload);
+    }
+    finishTiming() {
+        this.endedAt = Date.now();
+        this.duration = this.endedAt - this.startedAt;
+    }
+    /**
+     * A lifecycle transition (`launched`, `done · ok|failed|cancelled`) — logged as an
+     * `event` on this node so it joins the unified event stream (`events.log`) and the
+     * node's own log, distinct from user emits by its `lifecycle` source.
+     */
+    lifecycle(message) {
+        this.log("event", "lifecycle", message);
+    }
+    log(level, source, message) {
+        this.store.append({ nodeId: this.id, path: this.path, level, source, message });
+    }
+}
+const messageOf = (error) => error instanceof Error ? (error.stack ?? error.message) : String(error);
+const firstLine = (message) => message.split("\n", 1)[0] ?? message;

package/dist/core/ExecutionTree.d.ts

@@ -0,0 +1,88 @@
+import { LogStore } from "../output/log/LogStore.ts";
+import { RunFolder } from "../output/folder/RunFolder.ts";
+import type { RunView } from "../output/writers/views.ts";
+import { ActionRun } from "./ActionRun.ts";
+import type { Exec, LaunchSpec } from "./types.ts";
+/**
+ * The run: a module singleton that owns the log store, the run folder, the node
+ * registry, and the process-wide teardown. `launch` creates a child node under the
+ * ambient current action and runs it; `runRoot` runs the `om` body as the root and
+ * drives the whole thing to `finalize`, which always produces the artifacts.
+ */
+export declare class ExecutionTree {
+    static current: ExecutionTree | null;
+    /** The most recent run — kept for test/debug introspection (not nulled at finalize). */
+    static last: ExecutionTree | null;
+    /** The ambient-run guard: an action can only run inside a root `om(...)`. */
+    static require(): ExecutionTree;
+    /** For tests: drop the singleton so the next `om(...)` starts clean. */
+    static reset(): void;
+    readonly store: LogStore;
+    readonly folder: RunFolder;
+    readonly root: ActionRun;
+    private readonly rawStream;
+    private readonly consoleCapture;
+    private readonly snapshotStore;
+    private readonly registry;
+    private readonly unsettled;
+    private readonly originalLog;
+    private streaming;
+    private liveRendering;
+    private assertionsPassed;
+    private assertionsFailed;
+    private readonly faults;
+    static graceMs: number;
+    private phase;
+    private finalizing;
+    private graceTimer;
+    private readonly teardownGrace;
+    private readonly onSigint;
+    private readonly onUncaught;
+    private readonly onUnhandled;
+    constructor();
+    /** Launch an instance under the ambient current node (or the root). */
+    launch(spec: LaunchSpec): ActionRun;
+    private append;
+    /** The shared services every node is built with (log store, snapshots, assert tally). */
+    private nodeDeps;
+    private recordFault;
+    private recordAssert;
+    /** Tear the whole run down (aborts the root, cascading to every node). Idempotent. */
+    cancel(): void;
+    /**
+     * The sole teardown path: `open → closing`, narrate the reason once, abort the root
+     * (cascading to every node — procs killed, waits unblocked, daemons stopped). Later
+     * calls are no-ops. A single grace timer guarantees finalize even if a node's cleanup
+     * wedges after its proc is already dead, so the run always writes its log.
+     */
+    teardown(reason: string): void;
+    /** An escaped throw/rejection: log it, record it (unless already tearing down), tear down. */
+    private onFatal;
+    /** Run the `om` body as the root node, then drive to finalize. */
+    runRoot(body: Exec<object, unknown, unknown>): Promise<void>;
+    /**
+     * Track a launched node's `run()` promise until it settles (drives `drive()`'s
+     * wait). `run()` itself never rejects — the node's own constructor already
+     * swallows its settled rejection (via the private field, not the `.result` getter,
+     * so it doesn't mark the node observed and defeat the unobserved-failure check).
+     */
+    private trackNode;
+    private drive;
+    private finalize;
+    private finalizeOnce;
+    /** The end-of-run links + assert summary, to the terminal (files are already written). */
+    private printSummary;
+    private verdictOk;
+    private nodeView;
+    /** Test seam: the projected run view (same object written to result.json). */
+    runViewForTest(): RunView;
+    private runView;
+    /**
+     * Absolute `.log` path for a node — root is `main.log`, children drop the `main/`
+     * prefix. Each id segment is sanitized so names with filesystem-illegal characters
+     * (e.g. `TSKB:root:watch:docs`) still produce a valid path.
+     */
+    private logFile;
+    private rawStreamPath;
+    private narrate;
+}