omkit 0.4.6 → 0.4.8

package/README.md

@@ -33,7 +33,7 @@ om("dev", async () => {
 
   // …then launch a real browser and hand its live page downstream — typed, not scraped.
   const chrome = browser({ headless: false }); // a visible Chromium, closed on teardown
-  const page = chromePage("app", chrome.ref, { url: "http://localhost:3000" });
+  const page = chromePage("app", await chrome.ref, { url: "http://localhost:3000" });
   console.log(`opened ${(await page.ref).url()}`);
 
   console.log("stack is up — press Ctrl+C to stop");
@@ -223,6 +223,7 @@ Reusable actions built on the core engine. For anything beyond these, drop down
 - **`untilLog`** — gate on the first log entry matching a predicate.
 - **`tailLog`** — tail a file another process writes, folding its lines into the combined log.
 - **`healthcheck`** — poll a URL/port until the status (and optionally body) matches.
+- **`portFree`** — the mirror of `healthcheck`: poll a TCP port until nothing is listening, so a restart can rebind without racing the old process.
 - **`prompt`** — ask the terminal for input or a choice, with a timeout that falls back to a default; the answer is its handle.
 - **`browser`** — launch a Chromium browser with Playwright and expose the live `Browser` as a handle (defaults to the installed Chrome); closed on teardown. Feed its `.ref` to `chromePage`.
 - **`chromePage`** — attach to Chrome over CDP, or to an existing Playwright `Page`/`Browser`/`Context` (including a `browser` handle or an Electron window), and expose the live `Page` as a handle.
@@ -236,8 +237,9 @@ Point the `omkit` bin at a project — a `tsconfig.omkit.json` that lists your `
 - **`omkit run <om>`** — run one om directly by name or file path, inheriting the terminal.
 - **`omkit ls`** — list the discovered oms and actions.
 - **`omkit check`** — typecheck the project (`tsc --noEmit`) and report diagnostics.
+- **`omkit help`** — print the command overview (also `--help` / `-h`).
 
-Each run is supervised in its own child process and narrated to a run folder (see above), whether you launch it from the picker or with `run <om>`.
+Both paths run the om in its own child process and narrate it to a run folder (see above). The picker **supervises** the child — piping its output into the live view and answering prompts for it — while `omkit run <om>` runs it **bare**, handing the om your terminal directly.
 
 ## Install
 

package/dist/actions/browser.d.ts

@@ -17,7 +17,7 @@ export interface BrowserOptions {
 }
 /**
  * Launches a Chromium browser with Playwright and publishes the live {@link Browser}
- * as this action's handle, so a driver — e.g. `chromePage("Explorer", browser.ref,
+ * as this action's handle, so a driver — e.g. `chromePage("Explorer", await browser.ref,
  * { url })` — can await `instance.ref` and open pages in it. This owns the browser it
  * launches (unlike a CDP endpoint handed to `chromePage`, which belongs to its opener),
  * so teardown closes it. Replaces the external chromedriver/WebDriver dance.

package/dist/actions/browser.js

@@ -3,7 +3,7 @@ import { action } from "../core/action.js";
 const delay = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * Launches a Chromium browser with Playwright and publishes the live {@link Browser}
- * as this action's handle, so a driver — e.g. `chromePage("Explorer", browser.ref,
+ * as this action's handle, so a driver — e.g. `chromePage("Explorer", await browser.ref,
  * { url })` — can await `instance.ref` and open pages in it. This owns the browser it
  * launches (unlike a CDP endpoint handed to `chromePage`, which belongs to its opener),
  * so teardown closes it. Replaces the external chromedriver/WebDriver dance.

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

@@ -22,10 +22,11 @@ export interface ChromePageOptions {
 }
 /**
  * Publishes a Chrome/Chromium {@link Page} as this action's handle, so downstream
- * actions can await `instance.ref` and drive the same live page. The source may be
- * a promise, so it wires straight from another action's `.ref` (e.g.
- * `chromePage("Explorer", chromedriver.ref)`). `label` tags this run so several
+ * actions can await `instance.ref` and drive the same live page. The source is a
+ * resolved handle, not a promise — chain it from another action by awaiting that
+ * action's `.ref` at the call site (e.g.
+ * `chromePage("Explorer", await chromedriver.ref)`). `label` tags this run so several
  * pages in one run stay distinguishable. Daemon: acquire + attach, stay alive
  * until teardown, then close the CDP connection only when it opened one.
  */
-export declare const chromePage: import("../index.ts").Action<[label: string, source: ChromePageSource | Promise<ChromePageSource>, opts?: ChromePageOptions | undefined], void, ChromePageEvents, Page>;
+export declare const chromePage: import("../index.ts").Action<[label: string, source: ChromePageSource, opts?: ChromePageOptions | undefined], void, ChromePageEvents, Page>;

package/dist/actions/chrome-page.js

@@ -7,9 +7,10 @@ const isBrowser = (x) => typeof x.contexts === "function";
 const pageOf = (context, fresh) => fresh ? context.newPage() : (context.pages()[0] ?? context.newPage());
 /**
  * Publishes a Chrome/Chromium {@link Page} as this action's handle, so downstream
- * actions can await `instance.ref` and drive the same live page. The source may be
- * a promise, so it wires straight from another action's `.ref` (e.g.
- * `chromePage("Explorer", chromedriver.ref)`). `label` tags this run so several
+ * actions can await `instance.ref` and drive the same live page. The source is a
+ * resolved handle, not a promise — chain it from another action by awaiting that
+ * action's `.ref` at the call site (e.g.
+ * `chromePage("Explorer", await chromedriver.ref)`). `label` tags this run so several
  * pages in one run stay distinguishable. Daemon: acquire + attach, stay alive
  * until teardown, then close the CDP connection only when it opened one.
  */
@@ -19,13 +20,12 @@ export const chromePage = action("chromePage")
     .run(async ({ signal, emit, attach, tag }, label, source, opts = {}) => {
     tag(label);
     const { url } = opts;
-    const resolved = await source;
     // Only a CDP connection we open here is ours to close; handles belong to callers.
     let owned;
     let page;
     let from;
-    if (typeof resolved === "string") {
-        const cdpUrl = resolved.includes("://") ? resolved : `http://${resolved}`;
+    if (typeof source === "string") {
+        const cdpUrl = source.includes("://") ? source : `http://${source}`;
         from = cdpUrl;
         try {
             owned = await chromium.connectOverCDP(cdpUrl);
@@ -36,18 +36,18 @@ export const chromePage = action("chromePage")
         const context = owned.contexts()[0] ?? (await owned.newContext());
         page = await pageOf(context, url !== undefined);
     }
-    else if (isPage(resolved)) {
+    else if (isPage(source)) {
         from = "page handle";
-        page = resolved;
+        page = source;
     }
-    else if (isBrowser(resolved)) {
+    else if (isBrowser(source)) {
         from = "browser handle";
-        const context = resolved.contexts()[0] ?? (await resolved.newContext());
+        const context = source.contexts()[0] ?? (await source.newContext());
         page = await pageOf(context, url !== undefined);
     }
     else {
         from = "context handle";
-        page = await pageOf(resolved, url !== undefined);
+        page = await pageOf(source, url !== undefined);
     }
     page.on("console", (msg) => {
         console.log(`console: ${msg.text()}`);

package/dist/actions/index.d.ts

@@ -8,6 +8,8 @@ export { untilLog } from "./until-log.ts";
 export type { LogMatcher, UntilLogOptions, UntilLogEvents } from "./until-log.ts";
 export { healthcheck } from "./healthcheck.ts";
 export type { HealthcheckOptions, HealthcheckResult, HealthcheckEvents, StatusMatcher, BodyMatcher, } from "./healthcheck.ts";
+export { portFree } from "./port-free.ts";
+export type { PortFreeOptions, PortFreeResult, PortFreeEvents } from "./port-free.ts";
 export { watch } from "./watch.ts";
 export type { FileEvent, FileListener, WatchOptions } from "./watch.ts";
 export { watchDir } from "./watch-dir.ts";

package/dist/actions/index.js

@@ -5,6 +5,7 @@
 export { command } from "./command.js";
 export { untilLog } from "./until-log.js";
 export { healthcheck } from "./healthcheck.js";
+export { portFree } from "./port-free.js";
 export { watch } from "./watch.js";
 export { watchDir } from "./watch-dir.js";
 export { tailLog } from "./tail-log.js";

package/dist/actions/port-free.d.ts

@@ -0,0 +1,29 @@
+export interface PortFreeOptions {
+    /** Host to probe. Default "127.0.0.1". */
+    host?: string;
+    /** Delay between probes. Default 500ms. */
+    intervalMs?: number;
+    /** Abort a single connect attempt that hasn't answered within this long. Default 1000ms. */
+    connectTimeoutMs?: number;
+    /** Reject after this long overall. Default 30000ms; pass `undefined` to wait until teardown. */
+    timeoutMs?: number;
+}
+/** The probe that found the port free — this action's result and `free` event payload. */
+export interface PortFreeResult {
+    port: number;
+    host: string;
+    attempts: number;
+}
+/** Events emitted by {@link portFree}. */
+export interface PortFreeEvents {
+    /** Nothing is listening any more; payload is the passing probe. */
+    free: PortFreeResult;
+}
+/**
+ * Gate: polls a TCP port until nothing is listening on it, then resolves with that
+ * probe and emits `free`. The mirror of `healthcheck` — where that one waits
+ * for a service to come up, this waits for one to let go, so a restart can rebind
+ * without racing the previous process's socket. Bounded by the run's abort signal
+ * and `timeoutMs`, so teardown unblocks a pending probe instead of hanging.
+ */
+export declare const portFree: import("../index.ts").Action<[port: number, opts?: PortFreeOptions | undefined], PortFreeResult, PortFreeEvents, void>;

package/dist/actions/port-free.js

@@ -0,0 +1,78 @@
+import net from "node:net";
+import { action } from "../core/action.js";
+/**
+ * One TCP connect attempt. A refusal is the only answer that proves nobody is
+ * listening: a successful connect means the port is taken, and a hang or any other
+ * error (filtered, unreachable) is inconclusive, so both count as still busy rather
+ * than letting a firewall read as "free".
+ */
+const probe = (port, host, connectTimeoutMs, signal) => new Promise((resolve) => {
+    const socket = new net.Socket();
+    let settled = false;
+    const finish = (free) => {
+        if (settled)
+            return;
+        settled = true;
+        signal.removeEventListener("abort", onAbort);
+        socket.destroy();
+        resolve(free);
+    };
+    // Teardown mid-connect: drop the socket and report "busy" — the loop's own abort
+    // check turns that into a clean stop on the next pass.
+    function onAbort() {
+        finish(false);
+    }
+    socket.setTimeout(connectTimeoutMs);
+    socket.once("connect", () => finish(false));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", (error) => finish(error.code === "ECONNREFUSED"));
+    signal.addEventListener("abort", onAbort, { once: true });
+    socket.connect(port, host);
+});
+/**
+ * Gate: polls a TCP port until nothing is listening on it, then resolves with that
+ * probe and emits `free`. The mirror of `healthcheck` — where that one waits
+ * for a service to come up, this waits for one to let go, so a restart can rebind
+ * without racing the previous process's socket. Bounded by the run's abort signal
+ * and `timeoutMs`, so teardown unblocks a pending probe instead of hanging.
+ */
+export const portFree = action("portFree")
+    .emits()
+    .run(async ({ signal, emit }, port, opts = {}) => {
+    const { host = "127.0.0.1", intervalMs = 500, connectTimeoutMs = 1000, timeoutMs = 30_000, } = opts;
+    // Abortable inter-probe delay: resolves after `ms`, or rejects on teardown.
+    const sleep = (ms) => new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new Error("portFree: aborted"));
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener("abort", onAbort, { once: true });
+    });
+    const deadline = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
+    const target = `${host}:${port}`;
+    console.log(`waiting for ${target} to free up`);
+    let attempts = 0;
+    for (;;) {
+        if (signal.aborted)
+            throw new Error("portFree: aborted");
+        attempts++;
+        if (await probe(port, host, connectTimeoutMs, signal)) {
+            const result = { port, host, attempts };
+            const probes = `${attempts} ${attempts === 1 ? "probe" : "probes"}`;
+            console.log(`free ${target} (${probes})`);
+            emit("free", result);
+            return result;
+        }
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new Error(`portFree: ${target} still in use after ${timeoutMs}ms (${attempts} probes)`);
+        }
+        await sleep(intervalMs);
+    }
+});

package/dist/cli/commands/help.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The flat `omkit help` overview — one usage line, every command, and the global flags.
+ * A pure string builder so it's trivially testable and reusable: `main` prints it for an
+ * explicit `help`/`--help`, and again (to stderr) when an unknown command is given.
+ */
+export declare function helpText(): string;

package/dist/cli/commands/help.js

@@ -0,0 +1,27 @@
+/**
+ * The flat `omkit help` overview — one usage line, every command, and the global flags.
+ * A pure string builder so it's trivially testable and reusable: `main` prints it for an
+ * explicit `help`/`--help`, and again (to stderr) when an unknown command is given.
+ */
+export function helpText() {
+    return [
+        "omkit — run the workflows around your code",
+        "",
+        "Usage: omkit [command] [target] [flags]",
+        "",
+        "Commands:",
+        "  run [om]     run an om — interactive picker if no om is given, else by name or file path",
+        "  ls           list the discovered oms and actions",
+        "  check        typecheck the project (tsc --noEmit)",
+        "  init         scaffold a starter project (tsconfig.omkit.json + sample oms/ and actions/)",
+        "  help         show this help",
+        "",
+        "Flags:",
+        "  --tsconfig <path>   project config to scan (default: tsconfig.omkit.json)",
+        "  --json              machine-readable output (ls)",
+        "  --inspect[=port]    run the om in a forked child with the Node inspector open (default port 9229)",
+        "  -h, --help          show this help",
+        "",
+        "A bare `omkit` opens the interactive picker (run is the default command).",
+    ].join("\n");
+}

package/dist/cli/commands/ls.d.ts

@@ -1,4 +1,4 @@
-import type { Registry } from "../client/registry.ts";
+import type { Registry } from "../../client/registry.ts";
 /** Render a {@link Registry} for the terminal (plain text) or as JSON. */
 export declare function formatRegistry(registry: Registry, opts?: {
     json?: boolean;

package/dist/cli/commands/run.d.ts

@@ -1,4 +1,5 @@
-import type { Registry } from "../client/registry.ts";
+import type { Registry } from "../../client/registry.ts";
+import type { OmkitClient, InspectOptions } from "../../client/index.ts";
 /**
  * Report an actionable "nothing to run" panel when discovery finds no oms. Names the config file
  * omkit actually read (absolute, so the tsconfig.omkit.json-vs-tsconfig.json confusion goes away),
@@ -16,3 +17,13 @@ export declare function resolveOm(arg: string, registry: {
         file: string;
     }[];
 }, cwd: string): string | undefined;
+/**
+ * The `run` command. With no target, open the interactive picker (a bare `omkit` lands here too,
+ * since `run` is the default command); otherwise resolve the target om and run it bare, inheriting
+ * the terminal. Reaches the engine only through the {@link OmkitClient} interface. Sets
+ * `process.exitCode` on failure or from the child's exit code.
+ */
+export declare function runCommand(client: OmkitClient, opts: {
+    target?: string;
+    inspect?: InspectOptions;
+}): Promise<void>;

package/dist/cli/commands/run.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { renderDiagnostics } from "../ui/Report.js";
+import { renderDiagnostics, withSpinner } from "../ui/Report.js";
 /**
  * Report an actionable "nothing to run" panel when discovery finds no oms. Names the config file
  * omkit actually read (absolute, so the tsconfig.omkit.json-vs-tsconfig.json confusion goes away),
@@ -27,3 +27,49 @@ export function resolveOm(arg, registry, cwd) {
         return asPath;
     return registry.oms.find((o) => o.name === arg)?.file;
 }
+/**
+ * Tell the user where the inspector will be. The om runs in a forked child, so the inspector is on
+ * that child — never on the omkit process. In the interactive picker the child (and the port) only
+ * exists once an om is chosen; a bare run forks it immediately.
+ */
+function announceInspect(inspect, interactive) {
+    const p = inspect.port;
+    const run = interactive ? "the om you pick runs" : "the om runs";
+    console.log(`omkit: ${run} in a forked child with the inspector on :${p} — attach a debugger to that child, not to omkit itself (--inspect).`);
+}
+/**
+ * The `run` command. With no target, open the interactive picker (a bare `omkit` lands here too,
+ * since `run` is the default command); otherwise resolve the target om and run it bare, inheriting
+ * the terminal. Reaches the engine only through the {@link OmkitClient} interface. Sets
+ * `process.exitCode` on failure or from the child's exit code.
+ */
+export async function runCommand(client, opts) {
+    const { target, inspect } = opts;
+    if (!target) {
+        // Announce before Ink takes the terminal, so the notice isn't swallowed by the live UI —
+        // the supervised child's own inspector banner goes to a piped stream nobody sees. launchUi is
+        // lazy-loaded to keep the run.ts↔ui.tsx dependency out of module init (ui.tsx imports reportNoOms).
+        if (inspect)
+            announceInspect(inspect, true);
+        const { launchUi } = await import("./ui.js");
+        await launchUi(client);
+        return;
+    }
+    const registry = await withSpinner("discovering…", () => client.discover());
+    if (registry.oms.length === 0) {
+        await reportNoOms(client.tsconfig, registry);
+        process.exitCode = 1;
+        return;
+    }
+    const omFile = resolveOm(target, registry, process.cwd());
+    if (!omFile) {
+        const known = registry.oms.map((o) => o.name).join(", ");
+        console.error(`no om matches "${target}". Known oms: ${known}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (inspect)
+        announceInspect(inspect, false);
+    process.on("SIGINT", () => { }); // let the child tear down; don't die first
+    process.exitCode = await client.runBare(omFile, { cwd: path.dirname(omFile) });
+}

package/dist/cli/commands/ui.d.ts

@@ -1,4 +1,4 @@
-import type { OmkitClient } from "../client/index.ts";
+import type { OmkitClient } from "../../client/index.ts";
 /**
  * Render the interactive Ink app. Ink's own Ctrl+C handling is disabled so the app can tear the
  * run down gracefully first; the final verdict + run-folder path are printed here, after Ink
@@ -9,4 +9,4 @@ import type { OmkitClient } from "../client/index.ts";
  * it reports why (config + warnings) instead of dropping into a blank picker. Non-fatal warnings
  * are printed so they aren't lost behind the UI.
  */
-export declare function launchUi(client: OmkitClient, tsconfig: string): Promise<void>;
+export declare function launchUi(client: OmkitClient): Promise<void>;

package/dist/cli/commands/ui.js

@@ -13,10 +13,10 @@ import { reportNoOms } from "./run.js";
  * it reports why (config + warnings) instead of dropping into a blank picker. Non-fatal warnings
  * are printed so they aren't lost behind the UI.
  */
-export async function launchUi(client, tsconfig) {
+export async function launchUi(client) {
     const registry = await withSpinner("discovering…", () => client.discover());
     if (registry.oms.length === 0) {
-        await reportNoOms(tsconfig, registry);
+        await reportNoOms(client.tsconfig, registry);
         return;
     }
     if (registry.warnings.length > 0) {

package/dist/cli/index.d.ts

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
-import { type InspectOptions } from "./client/index.ts";
+import { type InspectOptions } from "../client/index.ts";
 export interface Cli {
     command: string;
     target?: string;
     json: boolean;
     tsconfig: string;
+    /** Set by `--help`/`-h` (the `help` command is carried on `command` instead). */
+    help: boolean;
     /** The Node inspector, if requested via `--inspect[=port]`. */
     inspect?: InspectOptions;
 }

package/dist/cli/index.js

@@ -3,7 +3,7 @@ import { parseArgs } from "node:util";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { realpathSync } from "node:fs";
-import { createOmkitClient } from "./client/index.js";
+import { createOmkitClient } from "../client/index.js";
 /**
  * Pull the Node-style inspector flag out of argv, returning the options plus the remaining args.
  * Matches Node's own syntax: `--inspect`, `--inspect=PORT` (default port 9229); an explicit port
@@ -32,6 +32,7 @@ export function parseCli(argv) {
         options: {
             json: { type: "boolean", default: false },
             tsconfig: { type: "string", default: "tsconfig.omkit.json" },
+            help: { type: "boolean", short: "h", default: false },
         },
         allowPositionals: true,
     });
@@ -40,22 +41,36 @@ export function parseCli(argv) {
         target: positionals[1],
         json: Boolean(values.json),
         tsconfig: values.tsconfig,
+        help: Boolean(values.help),
         inspect,
     };
 }
 /**
- * Tell the user where the inspector will be. The om runs in a forked child, so the inspector is on
- * that child — never on this omkit process. In the interactive picker the child (and the port) only
- * exists once an om is chosen; a bare run forks it immediately.
+ * The `check` command: typecheck the project and render the diagnostics. The mapping is trivial
+ * (one item per diagnostic) and the policy is local — **any diagnostic fails the command** (exit 1),
+ * a clean project reports ok and exits 0.
  */
-function announceInspect(inspect, interactive) {
-    const p = inspect.port;
-    const run = interactive ? "the om you pick runs" : "the om runs";
-    console.log(`omkit: ${run} in a forked child with the inspector on :${p} — attach a debugger to that child, not to omkit itself (--inspect).`);
+async function checkCommand(client) {
+    const { renderDiagnostics, withSpinner } = await import("./ui/Report.js");
+    const diagnostics = await withSpinner("type-checking…", () => client.check());
+    const n = diagnostics.length;
+    const items = diagnostics.map((d) => ({
+        head: `${path.basename(d.file)}:${d.line}`,
+        detail: d.message,
+    }));
+    const title = n === 0 ? "no type errors" : `${n} type error${n === 1 ? "" : "s"}`;
+    await renderDiagnostics({ kind: n === 0 ? "ok" : "error", title, items }, n === 0 ? process.stdout : process.stderr);
+    process.exitCode = n === 0 ? 0 : 1;
 }
 /** The bin entry: route to a lazily-imported command; owns stdout and the exit code. */
 async function main() {
     const cli = parseCli(process.argv.slice(2));
+    // `--help`/`-h` or the `help` command short-circuits everything — no config or client needed.
+    if (cli.help || cli.command === "help") {
+        const { helpText } = await import("./commands/help.js");
+        console.log(helpText());
+        return;
+    }
     const inspect = cli.inspect;
     const client = createOmkitClient({ tsconfig: cli.tsconfig, inspect });
     if (cli.command === "init") {
@@ -75,50 +90,17 @@ async function main() {
         return;
     }
     if (cli.command === "check") {
-        const { checkReport } = await import("./commands/check.js");
-        const { renderDiagnostics, withSpinner } = await import("./ui/Report.js");
-        const diagnostics = await withSpinner("type-checking…", () => client.check());
-        const { title, items, code } = checkReport(diagnostics);
-        // Type errors fail the command (exit 1); a clean project reports ok and exits 0.
-        await renderDiagnostics({ kind: code === 0 ? "ok" : "error", title, items }, code === 0 ? process.stdout : process.stderr);
-        process.exitCode = code;
+        await checkCommand(client);
         return;
     }
     if (cli.command === "run") {
-        // No target → open the interactive picker (browse/search oms, run one with live output).
-        // A bare `omkit` lands here too, since `run` is the default command.
-        if (!cli.target) {
-            // Announce before Ink takes the terminal, so the notice isn't swallowed by the live UI —
-            // the supervised child's own inspector banner goes to a piped stream nobody sees.
-            if (inspect)
-                announceInspect(inspect, true);
-            const { launchUi } = await import("./commands/ui.js");
-            await launchUi(client, cli.tsconfig);
-            return;
-        }
-        const { resolveOm, reportNoOms } = await import("./commands/run.js");
-        const { spawnBare } = await import("./client/runner.js");
-        const { withSpinner } = await import("./ui/Report.js");
-        const registry = await withSpinner("discovering…", () => client.discover());
-        if (registry.oms.length === 0) {
-            await reportNoOms(cli.tsconfig, registry);
-            process.exitCode = 1;
-            return;
-        }
-        const omFile = resolveOm(cli.target, registry, process.cwd());
-        if (!omFile) {
-            const known = registry.oms.map((o) => o.name).join(", ");
-            console.error(`no om matches "${cli.target}". Known oms: ${known}`);
-            process.exitCode = 1;
-            return;
-        }
-        if (inspect)
-            announceInspect(inspect, false);
-        process.on("SIGINT", () => { }); // let the child tear down; don't die first
-        process.exitCode = await spawnBare(omFile, { cwd: path.dirname(omFile), inspect });
+        const { runCommand } = await import("./commands/run.js");
+        await runCommand(client, { target: cli.target, inspect: cli.inspect });
         return;
     }
-    console.error(`unknown command "${cli.command}"`);
+    const { helpText } = await import("./commands/help.js");
+    console.error(`unknown command "${cli.command}"\n`);
+    console.error(helpText());
     process.exitCode = 1;
 }
 /**

package/dist/cli/ui/app.d.ts

@@ -1,6 +1,6 @@
 import { type ReactElement } from "react";
-import type { OmkitClient, Verdict } from "../client/types.ts";
-import type { DiscoveredOm } from "../client/registry.ts";
+import type { OmkitClient, Verdict } from "../../client/types.ts";
+import type { DiscoveredOm } from "../../client/registry.ts";
 /** The interactive app: discover → list/search → run → live milestones + prompts. */
 export declare function App({ client, onExit, oms: initialOms, }: {
     client: OmkitClient;

package/dist/cli/ui/app.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from "react";
 import { useApp, useInput } from "ink";
-import { format } from "../../output/milestones.js";
+import { RunModel } from "../../output/RunModel.js";
 import { OmList } from "./views/OmList.js";
 import { RunView } from "./views/RunView.js";
 import { Spinner } from "./Spinner.js";
@@ -10,7 +10,10 @@ export function App({ client, onExit, oms: initialOms, }) {
     const { exit } = useApp();
     const [oms, setOms] = useState(initialOms ?? []);
     const [session, setSession] = useState(null);
+    // A per-run RunModel folds the log stream into a capped milestone tail plus a live node summary;
+    // these snapshots are what the view renders. The cap is what keeps a long run from growing forever.
     const [lines, setLines] = useState([]);
+    const [status, setStatus] = useState();
     const [prompt, setPrompt] = useState();
     const [verdict, setVerdict] = useState();
     const [tearing, setTearing] = useState(false);
@@ -31,12 +34,13 @@ export function App({ client, onExit, oms: initialOms, }) {
         };
     }, [client, initialOms]);
     const run = (om) => {
+        const model = new RunModel();
         const s = client.run(om.file);
         sessionRef.current = s;
         s.on("log", (entry) => {
-            const rendered = format(entry);
-            if (rendered)
-                setLines((prev) => [...prev, rendered.text]);
+            model.apply(entry);
+            setLines(model.milestones());
+            setStatus(model.summary());
         });
         s.on("prompt", (req) => setPrompt(req));
         // The child gave up on the prompt (timed out or torn down). Withdraw its box so a stale,
@@ -95,5 +99,5 @@ export function App({ client, onExit, oms: initialOms, }) {
     });
     if (!session)
         return _jsx(OmList, { oms: oms, onSelect: run });
-    return (_jsxs(_Fragment, { children: [_jsx(RunView, { lines: lines, prompt: prompt, verdict: verdict, onAnswer: answer }), !verdict && tearing ? _jsx(Spinner, { label: "tearing down\u2026 (stopping the run cleanly)" }) : null, !verdict && !tearing && !prompt ? _jsx(Spinner, { label: "running\u2026" }) : null] }));
+    return (_jsxs(_Fragment, { children: [_jsx(RunView, { lines: lines, status: status, prompt: prompt, verdict: verdict, onAnswer: answer }), !verdict && tearing ? _jsx(Spinner, { label: "tearing down\u2026 (stopping the run cleanly)" }) : null, !verdict && !tearing && !prompt ? _jsx(Spinner, { label: "running\u2026" }) : null] }));
 }

package/dist/cli/ui/views/OmList.d.ts

@@ -1,5 +1,5 @@
 import { type ReactElement } from "react";
-import type { DiscoveredOm } from "../../client/registry.ts";
+import type { DiscoveredOm } from "../../../client/registry.ts";
 /** A searchable, arrow-navigable list of oms; Enter selects the highlighted one. */
 export declare function OmList({ oms, onSelect, }: {
     oms: DiscoveredOm[];

package/dist/cli/ui/views/RunView.d.ts

@@ -1,13 +1,15 @@
 import { type ReactElement } from "react";
-import type { PromptRequest, Verdict } from "../../client/types.ts";
+import type { RunSummary } from "../../../output/RunModel.ts";
+import type { PromptRequest, Verdict } from "../../../client/types.ts";
 /** Answer one pending prompt — free-text input, or searchable choices. */
 export declare function PromptView({ request, onAnswer, }: {
     request: PromptRequest;
     onAnswer: (value: string) => void;
 }): ReactElement;
-/** The live run surface: milestone lines, a pending prompt, and the final verdict. */
-export declare function RunView({ lines, prompt, verdict, onAnswer, }: {
-    lines: string[];
+/** The live run surface: milestone lines, a compact status strip, a pending prompt, and the verdict. */
+export declare function RunView({ lines, status, prompt, verdict, onAnswer, }: {
+    lines: readonly string[];
+    status?: RunSummary;
     prompt?: PromptRequest;
     verdict?: Verdict;
     onAnswer: (value: string) => void;

package/dist/cli/ui/views/RunView.js

@@ -35,7 +35,28 @@ function InputPrompt({ request, onAnswer, }) {
 export function PromptView({ request, onAnswer, }) {
     return request.spec.kind === "choice" ? (_jsx(ChoicePrompt, { request: request, onAnswer: onAnswer })) : (_jsx(InputPrompt, { request: request, onAnswer: onAnswer }));
 }
-/** The live run surface: milestone lines, a pending prompt, and the final verdict. */
-export function RunView({ lines, prompt, verdict, onAnswer, }) {
-    return (_jsxs(Box, { flexDirection: "column", children: [lines.map((line, i) => (_jsx(Text, { children: line }, i))), prompt ? _jsx(PromptView, { request: prompt, onAnswer: onAnswer }) : null, verdict ? (_jsxs(Text, { color: verdict.ok ? "green" : "red", children: [verdict.ok ? "✓ ok" : "✗ failed", " \u00B7 ", verdict.folder] })) : null] }));
+/** One-line roll-up of the live tree: what's still running and the finished tally. Empty until
+ *  something is happening, so it renders nothing at the very start of a run. */
+function statusStrip(s) {
+    const parts = [];
+    if (s.running.length) {
+        const shown = s.running.slice(0, 3).join(", ");
+        const more = s.running.length > 3 ? ` +${s.running.length - 3}` : "";
+        parts.push(`● running: ${shown}${more}`);
+    }
+    const tally = [];
+    if (s.ok)
+        tally.push(`${s.ok} ok`);
+    if (s.failed)
+        tally.push(`${s.failed} failed`);
+    if (s.cancelled)
+        tally.push(`${s.cancelled} cancelled`);
+    if (tally.length)
+        parts.push(tally.join(" · "));
+    return parts.join("  ·  ");
+}
+/** The live run surface: milestone lines, a compact status strip, a pending prompt, and the verdict. */
+export function RunView({ lines, status, prompt, verdict, onAnswer, }) {
+    const strip = status && !verdict ? statusStrip(status) : "";
+    return (_jsxs(Box, { flexDirection: "column", children: [lines.map((line, i) => (_jsx(Text, { children: line }, i))), strip ? _jsx(Text, { dimColor: true, children: strip }) : null, prompt ? _jsx(PromptView, { request: prompt, onAnswer: onAnswer }) : null, verdict ? (_jsxs(Text, { color: verdict.ok ? "green" : "red", children: [verdict.ok ? "✓ ok" : "✗ failed", " \u00B7 ", verdict.folder] })) : null] }));
 }

package/dist/{cli/client → client}/channel.d.ts

@@ -1,4 +1,4 @@
-import type { ChildMessage, SupervisorMessage } from "../../core/interaction.ts";
+import type { ChildMessage, SupervisorMessage } from "../core/interaction.ts";
 import type { RunSession } from "./types.ts";
 /** The minimal duplex the channel needs — satisfied by a real ChildProcess or a fake. */
 export interface Transport {

package/dist/{cli/client → client}/index.d.ts

@@ -8,5 +8,5 @@ export interface OmkitConfig {
     /** When set, every run this client launches forks with the Node inspector open. */
     inspect?: InspectOptions;
 }
-/** Build the headless engine: discovery + supervised run + typecheck over one config. */
+/** Build the headless engine: discovery + supervised/bare run + typecheck over one config. */
 export declare function createOmkitClient(config: OmkitConfig): OmkitClient;

package/dist/client/index.js

@@ -0,0 +1,18 @@
+import { discover } from "./discovery.js";
+import { runOm, spawnBare } from "./runner.js";
+import { runCheck } from "./check.js";
+/** Build the headless engine: discovery + supervised/bare run + typecheck over one config. */
+export function createOmkitClient(config) {
+    // A per-call inspect wins; the client's construction-time inspect is the fallback.
+    const withInspect = (opts) => ({
+        ...opts,
+        inspect: opts?.inspect ?? config.inspect,
+    });
+    return {
+        tsconfig: config.tsconfig,
+        discover: async () => discover(config.tsconfig),
+        run: (omFile, opts) => runOm(omFile, withInspect(opts)),
+        runBare: (omFile, opts) => spawnBare(omFile, withInspect(opts)),
+        check: async () => runCheck(config.tsconfig),
+    };
+}

package/dist/{cli/client → client}/types.d.ts

@@ -1,5 +1,5 @@
-import type { LogEntry } from "../../foundation/LogEntry.ts";
-import type { PromptSpec } from "../../core/interaction.ts";
+import type { LogEntry } from "../foundation/LogEntry.ts";
+import type { PromptSpec } from "../core/interaction.ts";
 import type { Registry } from "./registry.ts";
 /** A run's terminal verdict, resolved when the child settles. */
 export interface Verdict {
@@ -53,10 +53,14 @@ export interface RunSession {
 }
 /** The headless engine behind every omkit frontend. */
 export interface OmkitClient {
+    /** The `tsconfig.omkit.json` path this client scans and runs against — the single source of it. */
+    readonly tsconfig: string;
     /** Statically scan the project's `tsconfig.omkit.json` for oms and actions. */
     discover(): Promise<Registry>;
-    /** Spawn an om file as a supervised child and return its live session. */
+    /** Spawn an om file as a supervised child and return its live session (the Ink UI drives this). */
     run(omFile: string, opts?: RunOptions): RunSession;
+    /** Spawn an om file bare — inherited stdio, no supervision — and resolve its exit code. */
+    runBare(omFile: string, opts?: RunOptions): Promise<number>;
     /** Typecheck the project (`tsc --noEmit`) and return diagnostics. */
     check(): Promise<Diagnostic[]>;
 }

package/dist/output/LiveRenderer.d.ts

@@ -9,11 +9,13 @@ export interface LiveTerminal {
  * 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).
+ *
+ * Folds the stream through a {@link RunModel} — the same reducer the interactive app uses — so the
+ * bare and supervised surfaces render a run identically (tags and all) rather than drifting apart.
  */
 export declare class LiveRenderer {
     private readonly term;
-    /** Tags accumulated per node from `tag` entries, so milestones can show them by name. */
-    private readonly tagsByNode;
+    private readonly model;
     constructor(term: LiveTerminal);
     run(store: LogStore): Promise<void>;
 }

package/dist/output/LiveRenderer.js

@@ -1,30 +1,25 @@
-import { format } from "./milestones.js";
+import { RunModel } from "./RunModel.js";
 /**
  * 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).
+ *
+ * Folds the stream through a {@link RunModel} — the same reducer the interactive app uses — so the
+ * bare and supervised surfaces render a run identically (tags and all) rather than drifting apart.
  */
 export class LiveRenderer {
     term;
-    /** Tags accumulated per node from `tag` entries, so milestones can show them by name. */
-    tagsByNode = new Map();
+    model = new RunModel();
     constructor(term) {
         this.term = term;
     }
     async run(store) {
         for await (const entry of store.subscribe({ replay: true })) {
-            if (entry.level === "tag" && entry.source === "tag") {
-                const list = this.tagsByNode.get(entry.nodeId) ?? [];
-                list.push(entry.message);
-                this.tagsByNode.set(entry.nodeId, list);
-                continue; // tags aren't their own line — they decorate the node's milestones
-            }
-            const rendered = format(entry, this.tagsByNode.get(entry.nodeId));
-            if (rendered === null)
-                continue;
-            this.term.write(`${rendered.text}\n`);
+            const rendered = this.model.apply(entry);
+            if (rendered)
+                this.term.write(`${rendered.text}\n`);
         }
     }
 }

package/dist/output/RunModel.d.ts

@@ -0,0 +1,41 @@
+import type { LogEntry } from "../foundation/LogEntry.ts";
+import { type Rendered } from "./milestones.ts";
+export type RunNodeStatus = "running" | "ok" | "failed" | "cancelled";
+/** One node of the live tree: where it is, how it's doing, and the tags it has picked up. */
+export interface RunNode {
+    /** The node's execution path, e.g. `main/dev`. */
+    readonly path: string;
+    readonly status: RunNodeStatus;
+    readonly tags: readonly string[];
+}
+/** A compact roll-up of the live tree, for a one-line status strip. */
+export interface RunSummary {
+    /** Paths of nodes still running, most-recently-active first. */
+    readonly running: readonly string[];
+    readonly ok: number;
+    readonly failed: number;
+    readonly cancelled: number;
+}
+/** How many milestone lines to keep. Older lines fall off the top so a long run can't grow without bound. */
+export declare const MILESTONE_CAP = 500;
+/**
+ * Folds a run's {@link LogEntry} stream into live, bounded state: a per-node status map (the tree)
+ * and a capped tail of milestone lines. One reducer shared by every frontend — the bare
+ * `LiveRenderer` and the interactive app both drive it — so "how a run looks" has one definition.
+ */
+export declare class RunModel {
+    private readonly _nodes;
+    private readonly _milestones;
+    private seq;
+    /** Apply one entry: update node/tag state, append its milestone line (if any), and return it. */
+    apply(entry: LogEntry): Rendered | null;
+    /** The live tree: every node touched so far, with its current status and tags. */
+    nodes(): readonly RunNode[];
+    /** The capped tail of milestone lines, oldest first. */
+    milestones(): readonly string[];
+    /** A compact roll-up for a status strip: who's still running, and how many finished each way. */
+    summary(): RunSummary;
+    private touch;
+    private transition;
+    private push;
+}

package/dist/output/RunModel.js

@@ -0,0 +1,86 @@
+import { format } from "./milestones.js";
+/** How many milestone lines to keep. Older lines fall off the top so a long run can't grow without bound. */
+export const MILESTONE_CAP = 500;
+/**
+ * Folds a run's {@link LogEntry} stream into live, bounded state: a per-node status map (the tree)
+ * and a capped tail of milestone lines. One reducer shared by every frontend — the bare
+ * `LiveRenderer` and the interactive app both drive it — so "how a run looks" has one definition.
+ */
+export class RunModel {
+    _nodes = new Map();
+    _milestones = [];
+    seq = 0;
+    /** Apply one entry: update node/tag state, append its milestone line (if any), and return it. */
+    apply(entry) {
+        const node = this.touch(entry);
+        if (entry.level === "tag" && entry.source === "tag") {
+            node.tags.push(entry.message);
+            return null; // tags decorate a node's lines; they aren't a line of their own
+        }
+        this.transition(node, entry);
+        const rendered = format(entry, node.tags);
+        if (rendered)
+            this.push(rendered.text);
+        return rendered;
+    }
+    /** The live tree: every node touched so far, with its current status and tags. */
+    nodes() {
+        return [...this._nodes.values()].map((n) => ({
+            path: n.path,
+            status: n.status,
+            tags: [...n.tags],
+        }));
+    }
+    /** The capped tail of milestone lines, oldest first. */
+    milestones() {
+        return [...this._milestones];
+    }
+    /** A compact roll-up for a status strip: who's still running, and how many finished each way. */
+    summary() {
+        let ok = 0;
+        let failed = 0;
+        let cancelled = 0;
+        const running = [];
+        for (const n of this._nodes.values()) {
+            if (n.status === "ok")
+                ok++;
+            else if (n.status === "failed")
+                failed++;
+            else if (n.status === "cancelled")
+                cancelled++;
+            else
+                running.push(n);
+        }
+        running.sort((a, b) => b.order - a.order); // most-recently-active first
+        return { running: running.map((n) => n.path), ok, failed, cancelled };
+    }
+    touch(entry) {
+        const existing = this._nodes.get(entry.nodeId);
+        if (existing) {
+            existing.order = this.seq++; // most-recent activity wins the ordering
+            return existing;
+        }
+        const node = { path: entry.path, status: "running", tags: [], order: this.seq++ };
+        this._nodes.set(entry.nodeId, node);
+        return node;
+    }
+    transition(node, entry) {
+        if (entry.level === "event" && entry.source === "lifecycle") {
+            // A node reports `done · <status>` when it settles; "launched" leaves it running.
+            if (entry.message.startsWith("done · ")) {
+                node.status = statusOf(entry.message.slice("done · ".length));
+            }
+        }
+        else if (entry.level === "event" && entry.source === "cancel") {
+            node.status = "cancelled";
+        }
+    }
+    push(text) {
+        this._milestones.push(text);
+        if (this._milestones.length > MILESTONE_CAP)
+            this._milestones.shift();
+    }
+}
+function statusOf(s) {
+    return s === "ok" ? "ok" : s === "cancelled" ? "cancelled" : "failed";
+}

package/package.json

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

package/dist/cli/client/index.js

@@ -1,11 +0,0 @@
-import { discover } from "./discovery.js";
-import { runOm } from "./runner.js";
-import { runCheck } from "./check.js";
-/** Build the headless engine: discovery + supervised run + typecheck over one config. */
-export function createOmkitClient(config) {
-    return {
-        discover: async () => discover(config.tsconfig),
-        run: (omFile, opts) => runOm(omFile, { ...opts, inspect: config.inspect }),
-        check: async () => runCheck(config.tsconfig),
-    };
-}

package/dist/cli/commands/check.d.ts

@@ -1,11 +0,0 @@
-import type { Diagnostic } from "../client/types.ts";
-import type { ReportItem } from "../ui/Report.tsx";
-/**
- * Turn typecheck diagnostics into a report: a headline, one item per diagnostic (location + message),
- * and the process exit code — **1 when there are any errors**, 0 when the project is clean.
- */
-export declare function checkReport(diagnostics: Diagnostic[]): {
-    title: string;
-    items: ReportItem[];
-    code: number;
-};

package/dist/cli/commands/check.js

@@ -1,14 +0,0 @@
-import path from "node:path";
-/**
- * Turn typecheck diagnostics into a report: a headline, one item per diagnostic (location + message),
- * and the process exit code — **1 when there are any errors**, 0 when the project is clean.
- */
-export function checkReport(diagnostics) {
-    const n = diagnostics.length;
-    const items = diagnostics.map((d) => ({
-        head: `${path.basename(d.file)}:${d.line}`,
-        detail: d.message,
-    }));
-    const title = n === 0 ? "no type errors" : `${n} type error${n === 1 ? "" : "s"}`;
-    return { title, items, code: n === 0 ? 0 : 1 };
-}