omkit 0.2.2 → 0.4.1

package/dist/core/types.d.ts

@@ -5,14 +5,6 @@ import type { Proc } from "../system/proc.ts";
 export type Awaitable<T> = T | Promise<T>;
 /** An action that declares no events. */
 export type NoEvents = Record<never, never>;
-/** An activity's terminal outcome: a value on success, an error on failure/cancel. Never thrown. */
-export type Outcome<T> = {
-    ok: true;
-    value: T;
-} | {
-    ok: false;
-    error: unknown;
-};
 /** A node's lifecycle state, mirrored into `result.json`. */
 export type NodeStatus = "running" | "ok" | "failed" | "cancelled";
 /**
@@ -73,8 +65,12 @@ export interface OmContext {
  */
 export interface Activity<Result = unknown, Events extends object = NoEvents, Handle = void> {
     readonly id: string;
-    /** The terminal outcome; always resolves (never rejects). Reading it observes the failure. */
-    readonly result: Promise<Outcome<Result>>;
+    /**
+     * The terminal outcome: resolves the value on success, **rejects** with the action's error on
+     * failure (or `CancelledError` on cancel). Reading it observes the activity — a handled failure,
+     * so it won't tear the run down. For fire-and-forget handling, `activity.result.catch(fn)`.
+     */
+    readonly result: Promise<Result>;
     /** The attached handle; rejects on failure/cancel. */
     readonly ref: Promise<Handle>;
     /**
@@ -84,19 +80,13 @@ export interface Activity<Result = unknown, Events extends object = NoEvents, Ha
      * after the launching call; calling it once the body has started throws.
      */
     withCache(...paths: string[]): Activity<Result | undefined, Events, Handle>;
-    /**
-     * Handle a fire-and-forget activity's failure: attach a handler so a crash runs it
-     * instead of tearing the run down. Observes the failure; chainable; attach in the
-     * same tick as the launching call. Not called on cancellation.
-     */
-    handleFailure(handler: (error: unknown) => void): this;
     /** Subscribe to every emit of a declared/system event (`done`/`error`/`attached`). */
     on<K extends keyof InstanceEvents<Events, Result>>(key: K, handler: EventHandler<InstanceEvents<Events, Result>[K]>): void;
     /**
-     * Next emit of `key`; resolves `undefined` if the node settles first (never rejects).
-     * Exception — `once("done")` awaits the outcome itself: it resolves the result on
-     * success and **rejects** on failure/cancellation (observing the failure), so
-     * `await activity.once("done")` is a hard step-gate the body cannot sail past.
+     * Await the next emit of `key`. Resolves the event's payload when it fires; if the activity
+     * settles first, resolves `undefined` on success and **rejects** on failure/cancellation — so a
+     * gate on an event surfaces a failure instead of hanging or sailing past it. Observes the
+     * activity. `once("done")` is the outcome itself — identical to `.result`.
      */
     once<K extends keyof InstanceEvents<Events, Result>>(key: K): Promise<InstanceEvents<Events, Result>[K] | undefined>;
     /** Tag this run; chainable. */

package/dist/index.d.ts

@@ -11,4 +11,4 @@ export { om } from "./core/om.ts";
 export { action } from "./core/action.ts";
 export { step } from "./core/step.ts";
 export { CancelledError, isCancelled } from "./foundation/CancelledError.ts";
-export type { Action, Activity, ActionContext, OmContext, Outcome } from "./core/types.ts";
+export type { Action, Activity, ActionContext, OmContext } from "./core/types.ts";

package/dist/output/LiveRenderer.d.ts

@@ -1,28 +1,18 @@
 import type { LogStore } from "./log/LogStore.ts";
-/** The terminal surface the renderer writes to (process.stdout satisfies it). */
+/** The terminal surface the renderer appends to (process.stdout satisfies it). */
 export interface LiveTerminal {
     write(text: string): unknown;
-    readonly isTTY?: boolean;
-    readonly columns?: number;
 }
 /**
- * Renders a **curated** stream of milestones to the terminal, live — action launches,
- * completions, and errors, plus events, asserts, and snapshots. The bulk output (console
- * lines, proc stdout/stderr) is intentionally *not* shown live; it lives in the per-action
- * `.log` files.
- *
- * On a TTY it keeps a **single status line**, rewriting it in place as milestones arrive,
- * so the terminal stays quiet — except lines worth keeping (errors, failures, run
- * milestones), which are *committed* (printed with a newline) so they persist above the
- * live line. Piped/redirected output (no TTY) falls back to appending every line, so logs
- * stay readable. Writes through `process.stdout` directly, which `patch-console` doesn't
- * intercept, so it can't feed back into console capture.
+ * Appends a **curated** stream of milestones — action launches, completions, errors, events,
+ * asserts, snapshots — one line each, as the run goes. The in-place status-line rendering is
+ * retired: the interactive surface is the Ink app (`omkit ui`); this reporter is the plain
+ * output for bare `omkit run`, CI, and pipes. Writes through the given terminal directly (for
+ * `process.stdout`, `patch-console` doesn't intercept it, so it can't feed console capture).
  */
 export declare class LiveRenderer {
     private readonly term;
-    /** True while a transient status line is on screen (needs clearing or a closing newline). */
-    private pending;
-    /** Tags accumulated per node from `tag` entries, so milestones can show them by the name. */
+    /** Tags accumulated per node from `tag` entries, so milestones can show them by name. */
     private readonly tagsByNode;
     constructor(term: LiveTerminal);
     run(store: LogStore): Promise<void>;

package/dist/output/LiveRenderer.js

@@ -1,29 +1,19 @@
-/** Return to column 0 and clear the whole line — the in-place status-line reset. */
-const CLEAR = "\r\x1b[2K";
+import { format } from "./milestones.js";
 /**
- * Renders a **curated** stream of milestones to the terminal, live — action launches,
- * completions, and errors, plus events, asserts, and snapshots. The bulk output (console
- * lines, proc stdout/stderr) is intentionally *not* shown live; it lives in the per-action
- * `.log` files.
- *
- * On a TTY it keeps a **single status line**, rewriting it in place as milestones arrive,
- * so the terminal stays quiet — except lines worth keeping (errors, failures, run
- * milestones), which are *committed* (printed with a newline) so they persist above the
- * live line. Piped/redirected output (no TTY) falls back to appending every line, so logs
- * stay readable. Writes through `process.stdout` directly, which `patch-console` doesn't
- * intercept, so it can't feed back into console capture.
+ * Appends a **curated** stream of milestones — action launches, completions, errors, events,
+ * asserts, snapshots — one line each, as the run goes. The in-place status-line rendering is
+ * retired: the interactive surface is the Ink app (`omkit ui`); this reporter is the plain
+ * output for bare `omkit run`, CI, and pipes. Writes through the given terminal directly (for
+ * `process.stdout`, `patch-console` doesn't intercept it, so it can't feed console capture).
  */
 export class LiveRenderer {
     term;
-    /** True while a transient status line is on screen (needs clearing or a closing newline). */
-    pending = false;
-    /** Tags accumulated per node from `tag` entries, so milestones can show them by the name. */
+    /** Tags accumulated per node from `tag` entries, so milestones can show them by name. */
     tagsByNode = new Map();
     constructor(term) {
         this.term = term;
     }
     async run(store) {
-        const tty = Boolean(this.term.isTTY);
         for await (const entry of store.subscribe({ replay: true })) {
             if (entry.level === "tag" && entry.source === "tag") {
                 const list = this.tagsByNode.get(entry.nodeId) ?? [];
@@ -34,71 +24,7 @@ export class LiveRenderer {
             const rendered = format(entry, this.tagsByNode.get(entry.nodeId));
             if (rendered === null)
                 continue;
-            if (!tty) {
-                this.term.write(`${rendered.text}\n`); // no TTY: append, one line each
-                continue;
-            }
-            if (rendered.persist) {
-                // Commit a line that must survive: finish the transient line, then print permanently.
-                this.term.write(`${this.pending ? CLEAR : ""}${rendered.text}\n`);
-                this.pending = false;
-            }
-            else {
-                // Transient: overwrite the current status line in place, truncated to fit.
-                this.term.write(`${CLEAR}${truncate(rendered.text, this.term.columns)}`);
-                this.pending = true;
-            }
-        }
-        // Keep the last status line on screen for the summary that follows.
-        if (this.pending) {
-            this.term.write("\n");
-            this.pending = false;
+            this.term.write(`${rendered.text}\n`);
         }
     }
 }
-const firstLine = (message) => message.split("\n", 1)[0] ?? message;
-/** ✓ ok · ⊘ cancelled (a clean stop) · ✗ failed. */
-const doneIcon = (status) => status === "ok" ? "✓" : status === "cancelled" ? "⊘" : "✗";
-/** Truncate to the terminal width so an in-place line never wraps and breaks the `\r`. */
-const truncate = (text, columns) => !columns || text.length < columns ? text : `${text.slice(0, Math.max(0, columns - 1))}…`;
-/** The node's path with its accumulated tags appended: `main/probe_9f3c [ready, gate]`. */
-const named = (path, tags) => tags && tags.length ? `${path} [${tags.join(", ")}]` : path;
-/** Map a curated entry to a terminal line (and whether it persists), or `null` to drop it. */
-const format = (e, tags) => {
-    // Action launch — bubbled onto the parent as `→ <childId> · <log>`.
-    if (e.level === "child" && e.source === "launch") {
-        const child = e.message.replace(/^→\s*/, "").split(" · ")[0];
-        return { text: `▶ ${e.path}/${child}`, persist: false };
-    }
-    // Lifecycle events: `launched` is already shown via the launch pointer above, so drop
-    // the duplicate; `done · <status>` renders with the status icon — a failure persists.
-    if (e.level === "event" && e.source === "lifecycle") {
-        if (e.message === "launched")
-            return null;
-        const status = e.message.replace(/^done · /, "");
-        return {
-            text: `${doneIcon(status)} ${named(e.path, tags)} · ${status}`,
-            persist: status === "failed",
-        };
-    }
-    // Run milestones (started / tearing down / finished) — few, and worth keeping.
-    if (e.level === "run")
-        return { text: `· ${e.message}`, persist: true };
-    // An action's *own* failure — not proc stderr, console.error, or a teardown cancellation.
-    if (e.level === "error" && e.source === "error") {
-        return { text: `✗ ${named(e.path, tags)} · ${firstLine(e.message)}`, persist: true };
-    }
-    // A cancellation milestone (⊘) — persist it so it doesn't flash away during teardown.
-    if (e.level === "event" && e.source === "cancel")
-        return { text: `⊘ ${named(e.path, tags)} · ${e.message}`, persist: true };
-    // User-emitted events.
-    if (e.level === "event")
-        return { text: `⚡ ${named(e.path, tags)} · ${e.message}`, persist: false };
-    // Asserts: a failed one (⊭) persists, a pass is transient.
-    if (e.level === "assert")
-        return { text: `  ${named(e.path, tags)} · ${e.message}`, persist: e.message.includes("⊭") };
-    if (e.level === "snapshot")
-        return { text: `📸 ${named(e.path, tags)} · ${e.message}`, persist: false };
-    // Everything else (info / console / proc output / tag / bubbled child events) → files only.
-    return null;
-};

package/dist/output/milestones.d.ts

@@ -0,0 +1,8 @@
+import type { LogEntry } from "../foundation/LogEntry.ts";
+/** A curated milestone line plus whether it must persist (vs. a transient status update). */
+export interface Rendered {
+    text: string;
+    persist: boolean;
+}
+/** Map a curated log entry to a milestone line (and whether it persists), or `null` to drop it. */
+export declare function format(e: LogEntry, tags?: readonly string[]): Rendered | null;

package/dist/output/milestones.js

@@ -0,0 +1,39 @@
+const firstLine = (message) => message.split("\n", 1)[0] ?? message;
+/** ✓ ok · ⊘ cancelled (a clean stop) · ✗ failed. */
+const doneIcon = (status) => status === "ok" ? "✓" : status === "cancelled" ? "⊘" : "✗";
+/** The node's path with its accumulated tags appended: `main/probe_9f3c [ready, gate]`. */
+const named = (path, tags) => tags && tags.length ? `${path} [${tags.join(", ")}]` : path;
+/** Map a curated log entry to a milestone line (and whether it persists), or `null` to drop it. */
+export function format(e, tags) {
+    if (e.level === "child" && e.source === "launch") {
+        const child = e.message.replace(/^→\s*/, "").split(" · ")[0];
+        return { text: `▶ ${e.path}/${child}`, persist: false };
+    }
+    if (e.level === "event" && e.source === "lifecycle") {
+        if (e.message === "launched")
+            return null;
+        const status = e.message.replace(/^done · /, "");
+        return {
+            text: `${doneIcon(status)} ${named(e.path, tags)} · ${status}`,
+            persist: status === "failed",
+        };
+    }
+    if (e.level === "run")
+        return { text: `· ${e.message}`, persist: true };
+    if (e.level === "error" && e.source === "error") {
+        return { text: `✗ ${named(e.path, tags)} · ${firstLine(e.message)}`, persist: true };
+    }
+    if (e.level === "event" && e.source === "cancel") {
+        return { text: `⊘ ${named(e.path, tags)} · ${e.message}`, persist: true };
+    }
+    if (e.level === "event") {
+        return { text: `⚡ ${named(e.path, tags)} · ${e.message}`, persist: false };
+    }
+    if (e.level === "assert") {
+        return { text: `  ${named(e.path, tags)} · ${e.message}`, persist: e.message.includes("⊭") };
+    }
+    if (e.level === "snapshot") {
+        return { text: `📸 ${named(e.path, tags)} · ${e.message}`, persist: false };
+    }
+    return null;
+}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "omkit",
-  "version": "0.2.2",
+  "version": "0.4.1",
   "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",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "omkit": "./dist/cli/index.js"
+  },
   "files": [
     "dist",
     "LICENSE"
@@ -49,12 +52,17 @@
     "developer-tools"
   ],
   "dependencies": {
+    "ink": "^7.1.1",
     "patch-console": "^2.0.0",
     "playwright-core": "^1.49.0",
+    "react": "^19.2.8",
+    "tsx": "4.23.1",
     "zx": "^8.8.5"
   },
   "devDependencies": {
     "@types/node": "^24",
+    "@types/react": "^19.2.17",
+    "ink-testing-library": "^4.0.0",
     "rimraf": "^6.0.1",
     "typescript": "^5.9.3"
   }