omkit 0.2.1 → 0.4.0

package/dist/cli/client/discovery.js

@@ -0,0 +1,147 @@
+import ts from "typescript";
+import path from "node:path";
+/**
+ * Statically scan the project described by `tsconfigPath` for runnable oms and inspectable
+ * actions. Never throws for user-code problems — type errors become `warnings`, and whatever
+ * parsed is still returned (so an editor-in-progress project stays useful).
+ */
+export function discover(tsconfigPath) {
+    const oms = [];
+    const actions = [];
+    const warnings = [];
+    const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+    if (configFile.error) {
+        warnings.push(ts.flattenDiagnosticMessageText(configFile.error.messageText, "\n"));
+        return { oms, actions, warnings };
+    }
+    // Resolve to an absolute base so `parsed.fileNames` are absolute. Otherwise root files stay
+    // relative while imported files (e.g. an action pulled in by an om) resolve to absolute paths,
+    // and the two never match in `fileSet`.
+    const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path.resolve(path.dirname(tsconfigPath)));
+    const program = ts.createProgram({
+        rootNames: parsed.fileNames,
+        options: { ...parsed.options, noEmit: true },
+    });
+    const fileSet = new Set(parsed.fileNames.map((f) => canonical(f)));
+    for (const sf of program.getSourceFiles()) {
+        if (!fileSet.has(canonical(sf.fileName)))
+            continue;
+        for (const d of program.getSemanticDiagnostics(sf))
+            warnings.push(formatDiagnostic(d));
+        const names = omkitImports(sf);
+        const visit = (node) => {
+            if (ts.isCallExpression(node) &&
+                ts.isIdentifier(node.expression) &&
+                (node.expression.text === names.om || node.expression.text === names.step)) {
+                const arg = node.arguments[0];
+                if (arg && ts.isStringLiteralLike(arg)) {
+                    oms.push({ name: arg.text, file: sf.fileName, line: lineOf(sf, node) });
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sf);
+        for (const stmt of sf.statements) {
+            if (!ts.isVariableStatement(stmt) || !isExported(stmt))
+                continue;
+            for (const decl of stmt.declarationList.declarations) {
+                if (!decl.initializer || !ts.isIdentifier(decl.name))
+                    continue;
+                const info = actionChain(decl.initializer, names.action);
+                if (info) {
+                    actions.push({
+                        name: info.name,
+                        file: sf.fileName,
+                        exportName: decl.name.text,
+                        publishesCapability: info.ref,
+                        events: info.emits,
+                    });
+                }
+            }
+        }
+    }
+    return { oms, actions, warnings };
+}
+/** Collect the local names bound to om/step/action from `import … from "omkit"`. */
+function omkitImports(sf) {
+    const names = {};
+    for (const stmt of sf.statements) {
+        if (!isOmkitImport(stmt))
+            continue;
+        const bindings = stmt.importClause?.namedBindings;
+        if (!bindings || !ts.isNamedImports(bindings))
+            continue;
+        for (const el of bindings.elements)
+            bindName(names, el);
+    }
+    return names;
+}
+/** True for `import … from "omkit"`. */
+function isOmkitImport(stmt) {
+    return (ts.isImportDeclaration(stmt) &&
+        ts.isStringLiteral(stmt.moduleSpecifier) &&
+        stmt.moduleSpecifier.text === "omkit");
+}
+/** Record the local binding for an imported `om` / `step` / `action` specifier. */
+function bindName(names, el) {
+    const imported = (el.propertyName ?? el.name).text;
+    if (imported === "om")
+        names.om = el.name.text;
+    else if (imported === "step")
+        names.step = el.name.text;
+    else if (imported === "action")
+        names.action = el.name.text;
+}
+/**
+ * Walk a builder chain (`action("x").emits<…>().ref<…>().run(fn)`) from the outer call down to
+ * the base `action("name")` call, noting whether `.ref` / `.emits` appear. Returns undefined
+ * when the chain is not rooted in the local `action` binding with a string-literal name.
+ */
+function actionChain(expr, actionName) {
+    if (actionName === undefined)
+        return undefined;
+    let ref = false;
+    let emits = false;
+    let node = expr;
+    while (ts.isCallExpression(node)) {
+        if (ts.isPropertyAccessExpression(node.expression)) {
+            const method = node.expression.name.text;
+            if (method === "ref")
+                ref = true;
+            if (method === "emits")
+                emits = true;
+            node = node.expression.expression;
+            continue;
+        }
+        if (ts.isIdentifier(node.expression) && node.expression.text === actionName) {
+            const arg = node.arguments[0];
+            if (arg && ts.isStringLiteralLike(arg))
+                return { name: arg.text, ref, emits };
+        }
+        return undefined;
+    }
+    return undefined;
+}
+function isExported(stmt) {
+    return Boolean(stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword));
+}
+/**
+ * A canonical key for a file path. TypeScript resolves relative imports with a different
+ * drive-letter case than the tsconfig `include` glob does on Windows, so a plain
+ * `path.normalize` comparison misses files reached both ways. Fold case where the OS does.
+ */
+function canonical(file) {
+    const normalized = path.normalize(file);
+    return ts.sys.useCaseSensitiveFileNames ? normalized : normalized.toLowerCase();
+}
+function lineOf(sf, node) {
+    return sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+}
+function formatDiagnostic(d) {
+    const message = ts.flattenDiagnosticMessageText(d.messageText, "\n");
+    if (d.file && d.start !== undefined) {
+        const { line } = d.file.getLineAndCharacterOfPosition(d.start);
+        return `${path.basename(d.file.fileName)}:${line + 1} ${message}`;
+    }
+    return message;
+}

package/dist/cli/client/index.d.ts

@@ -0,0 +1,9 @@
+import type { OmkitClient } from "./types.ts";
+export type { OmkitClient, RunSession, RunOptions, Verdict, Diagnostic, PromptRequest, RunEvents, } from "./types.ts";
+export type { Registry, DiscoveredOm, DiscoveredAction } from "./registry.ts";
+/** Configuration for a client — the path to the project's `tsconfig.omkit.json`. */
+export interface OmkitConfig {
+    tsconfig: string;
+}
+/** Build the headless engine: discovery + supervised run + typecheck over one config. */
+export declare function createOmkitClient(config: OmkitConfig): OmkitClient;

package/dist/cli/client/index.js

@@ -0,0 +1,11 @@
+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),
+        check: async () => runCheck(config.tsconfig),
+    };
+}

package/dist/cli/client/registry.d.ts

@@ -0,0 +1,29 @@
+/** A runnable om discovered from a top-level `om("name", …)` call. */
+export interface DiscoveredOm {
+    /** The om's name — its first string argument. */
+    readonly name: string;
+    /** Absolute path of the file that defines it. */
+    readonly file: string;
+    /** 1-based line of the `om(...)` call (informational). */
+    readonly line: number;
+}
+/** An inspectable action discovered from an exported `action("name")…` builder. */
+export interface DiscoveredAction {
+    /** The action's name — the first string argument to `action(...)`. */
+    readonly name: string;
+    /** Absolute path of the file that defines it. */
+    readonly file: string;
+    /** The exported binding name (`export const <exportName> = action(...)`). */
+    readonly exportName: string;
+    /** True when the builder chain includes `.ref<…>()` (publishes a capability). */
+    readonly publishesCapability: boolean;
+    /** True when the builder chain includes `.emits<…>()`. */
+    readonly events: boolean;
+}
+/** The result of scanning a project: runnable oms, inspectable actions, and soft warnings. */
+export interface Registry {
+    readonly oms: DiscoveredOm[];
+    readonly actions: DiscoveredAction[];
+    /** Non-fatal diagnostics (type errors, unresolved config) — discovery never throws for these. */
+    readonly warnings: string[];
+}

package/dist/cli/client/registry.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/client/runner.d.ts

@@ -0,0 +1,15 @@
+import type { RunSession, RunOptions } from "./types.ts";
+/**
+ * Fork `omFile` as a supervised child: the `tsx` loader runs the TypeScript directly,
+ * `OMKIT_SUPERVISED=1` flips the child into channel mode (see core/interaction.ts), and its
+ * IPC channel is wrapped into a {@link RunSession}. stdout/stderr are piped (not inherited)
+ * so the child never writes to the supervisor's terminal.
+ */
+export declare function runOm(omFile: string, opts?: RunOptions): RunSession;
+/**
+ * Spawn `omFile` **bare** — inherited stdio, no supervision. The child owns the terminal, so
+ * its LiveRenderer, summary, and native `readline` prompts all work. Resolves the exit code.
+ */
+export declare function spawnBare(omFile: string, opts?: {
+    cwd?: string;
+}): Promise<number>;

package/dist/cli/client/runner.js

@@ -0,0 +1,61 @@
+import { fork } from "node:child_process";
+import path from "node:path";
+import { createChannel } from "./channel.js";
+/**
+ * The `tsx` loader, resolved to an absolute URL from omkit's own location. Resolving it here
+ * (not as the bare specifier `--import tsx`) keeps the child's `tsx` independent of its cwd —
+ * a run in any directory still finds the loader shipped with omkit.
+ */
+const tsxLoader = import.meta.resolve("tsx");
+/**
+ * Fork `omFile` as a supervised child: the `tsx` loader runs the TypeScript directly,
+ * `OMKIT_SUPERVISED=1` flips the child into channel mode (see core/interaction.ts), and its
+ * IPC channel is wrapped into a {@link RunSession}. stdout/stderr are piped (not inherited)
+ * so the child never writes to the supervisor's terminal.
+ */
+export function runOm(omFile, opts = {}) {
+    const child = fork(omFile, [], {
+        execArgv: ["--import", tsxLoader],
+        cwd: opts.cwd ?? path.dirname(omFile),
+        env: { ...process.env, OMKIT_SUPERVISED: "1" },
+        stdio: ["ignore", "pipe", "pipe", "ipc"],
+    });
+    const transport = {
+        send: (message) => void child.send(message),
+        onMessage: (handler) => void child.on("message", (m) => handler(m)),
+        onClose: (handler) => void child.on("close", (code) => handler(code)),
+    };
+    const session = createChannel(transport);
+    // When the run settles, the child has already written its logs and reaped its process tree —
+    // but the live IPC channel (and the unread stdout/stderr pipes) keep both this process and the
+    // child alive, so the frontend would hang after teardown. Release it: disconnect so the child
+    // can drain and exit, and force-kill if it lingers past a short grace.
+    void session.result.then(() => {
+        if (child.exitCode !== null || child.signalCode !== null)
+            return; // already gone
+        if (child.connected)
+            child.disconnect();
+        const kill = setTimeout(() => child.kill(), 1500);
+        child.once("close", () => clearTimeout(kill));
+    });
+    return session;
+}
+/**
+ * Spawn `omFile` **bare** — inherited stdio, no supervision. The child owns the terminal, so
+ * its LiveRenderer, summary, and native `readline` prompts all work. Resolves the exit code.
+ */
+export function spawnBare(omFile, opts = {}) {
+    // A bare run is unsupervised even if the parent process happens to carry the flag (e.g. a
+    // test runner spawned from inside a supervised run) — clear it so the child stays bare.
+    const env = { ...process.env };
+    delete env.OMKIT_SUPERVISED;
+    const child = fork(omFile, [], {
+        execArgv: ["--import", tsxLoader],
+        cwd: opts.cwd ?? path.dirname(omFile),
+        stdio: "inherit",
+        env,
+    });
+    return new Promise((resolve) => {
+        child.on("close", (code) => resolve(code ?? 0));
+    });
+}

package/dist/cli/client/types.d.ts

@@ -0,0 +1,53 @@
+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 {
+    readonly ok: boolean;
+    /** The absolute run-folder path the child reported. */
+    readonly folder: string;
+    /** The end-of-run recap lines (run folder + sibling log paths + assert tally), the same
+     *  block a bare run prints to its terminal. Empty if the child closed without settling. */
+    readonly summary: readonly string[];
+}
+/** A typecheck diagnostic from `check()`. */
+export interface Diagnostic {
+    readonly file: string;
+    readonly line: number;
+    readonly message: string;
+}
+/** Options for launching a run. */
+export interface RunOptions {
+    /** Working directory for the child process (defaults to the om file's directory). */
+    readonly cwd?: string;
+}
+/** A prompt the running om is waiting on — surfaced to the frontend, answered via `answer`. */
+export interface PromptRequest {
+    readonly id: string;
+    readonly spec: PromptSpec;
+}
+/** Handler map for {@link RunSession.on}. */
+export interface RunEvents {
+    log: (entry: LogEntry) => void;
+    prompt: (request: PromptRequest) => void;
+    settled: (verdict: Verdict) => void;
+}
+/** A live handle to one supervised run. */
+export interface RunSession {
+    on<K extends keyof RunEvents>(event: K, handler: RunEvents[K]): void;
+    /** Answer a pending prompt (`via` defaults to "input"). */
+    answer(id: string, value: string, via?: string): void;
+    /** Request graceful teardown of the run. */
+    cancel(): void;
+    /** Resolves when the run settles (or the child exits without settling → ok:false). */
+    readonly result: Promise<Verdict>;
+}
+/** The headless engine behind every omkit frontend. */
+export interface OmkitClient {
+    /** 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. */
+    run(omFile: string, opts?: RunOptions): RunSession;
+    /** Typecheck the project (`tsc --noEmit`) and return diagnostics. */
+    check(): Promise<Diagnostic[]>;
+}

package/dist/cli/client/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,6 @@
+import type { Diagnostic } from "../client/types.ts";
+/** Format typecheck diagnostics into terminal text plus a process exit code. */
+export declare function formatDiagnostics(diagnostics: Diagnostic[]): {
+    text: string;
+    code: number;
+};

package/dist/cli/commands/check.js

@@ -0,0 +1,11 @@
+import path from "node:path";
+/** Format typecheck diagnostics into terminal text plus a process exit code. */
+export function formatDiagnostics(diagnostics) {
+    if (diagnostics.length === 0) {
+        return { text: "no type errors", code: 0 };
+    }
+    const lines = diagnostics.map((d) => `${path.basename(d.file)}:${d.line}  ${d.message}`);
+    lines.push("");
+    lines.push(`${diagnostics.length} error${diagnostics.length === 1 ? "" : "s"}`);
+    return { text: lines.join("\n"), code: 1 };
+}

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

@@ -0,0 +1,5 @@
+/** Write the starter project into `dir`, never overwriting existing files. */
+export declare function scaffold(dir: string): {
+    created: string[];
+    skipped: string[];
+};

package/dist/cli/commands/init.js

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+const TSCONFIG = `{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": ["oms/**/*.ts", "actions/**/*.ts"]
+}
+`;
+const DEV_OM = `import { om } from "omkit";
+import { command, healthcheck } from "omkit/actions";
+
+om("dev", async () => {
+  command("npm run dev", { cwd: "api" }).tag("api");
+  const up = await healthcheck({ url: "http://localhost:3000" }).result;
+  if (!up.ok) return;
+  console.log("stack is up — press Ctrl+C to stop");
+});
+`;
+const HELLO_ACTION = `import { action } from "omkit";
+
+export const hello = action("hello")
+  .ref<string>()
+  .run(async ({ attach }) => {
+    attach("world");
+  });
+`;
+const FILES = [
+    { rel: "tsconfig.omkit.json", body: TSCONFIG },
+    { rel: "oms/dev.ts", body: DEV_OM },
+    { rel: "actions/hello.ts", body: HELLO_ACTION },
+];
+/** Write the starter project into `dir`, never overwriting existing files. */
+export function scaffold(dir) {
+    const created = [];
+    const skipped = [];
+    for (const { rel, body } of FILES) {
+        const target = path.join(dir, rel);
+        if (fs.existsSync(target)) {
+            skipped.push(rel);
+            continue;
+        }
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, body);
+        created.push(rel);
+    }
+    return { created, skipped };
+}

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

@@ -0,0 +1,5 @@
+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;
+}): string;

package/dist/cli/commands/ls.js

@@ -0,0 +1,25 @@
+import path from "node:path";
+/** Render a {@link Registry} for the terminal (plain text) or as JSON. */
+export function formatRegistry(registry, opts = {}) {
+    if (opts.json)
+        return JSON.stringify(registry, null, 2);
+    const lines = [];
+    lines.push(`oms (${registry.oms.length})`);
+    for (const om of registry.oms) {
+        lines.push(`  ${om.name}  ${path.basename(om.file)}:${om.line}`);
+    }
+    lines.push("");
+    lines.push(`actions (${registry.actions.length})`);
+    for (const a of registry.actions) {
+        const tags = [a.publishesCapability ? "ref" : "", a.events ? "events" : ""].filter(Boolean);
+        const suffix = tags.length ? `  [${tags.join(", ")}]` : "";
+        lines.push(`  ${a.name}  ${path.basename(a.file)}${suffix}`);
+    }
+    if (registry.warnings.length) {
+        lines.push("");
+        lines.push(`warnings (${registry.warnings.length})`);
+        for (const w of registry.warnings)
+            lines.push(`  ${w}`);
+    }
+    return lines.join("\n");
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Resolve a `run` argument to an absolute om file: an existing file path (relative to `cwd`)
+ * wins; otherwise match a discovered om by name. Returns undefined when nothing matches.
+ */
+export declare function resolveOm(arg: string, registry: {
+    oms: {
+        name: string;
+        file: string;
+    }[];
+}, cwd: string): string | undefined;

package/dist/cli/commands/run.js

@@ -0,0 +1,12 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Resolve a `run` argument to an absolute om file: an existing file path (relative to `cwd`)
+ * wins; otherwise match a discovered om by name. Returns undefined when nothing matches.
+ */
+export function resolveOm(arg, registry, cwd) {
+    const asPath = path.resolve(cwd, arg);
+    if (fs.existsSync(asPath) && fs.statSync(asPath).isFile())
+        return asPath;
+    return registry.oms.find((o) => o.name === arg)?.file;
+}

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

@@ -0,0 +1,7 @@
+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
+ * unmounts (it erases its own frame), so the pointer to the on-disk record survives on screen.
+ */
+export declare function launchUi(client: OmkitClient): void;

package/dist/cli/commands/ui.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from "ink";
+import { App } from "../ui/app.js";
+/**
+ * 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
+ * unmounts (it erases its own frame), so the pointer to the on-disk record survives on screen.
+ */
+export function launchUi(client) {
+    let finalVerdict;
+    const app = render(_jsx(App, { client: client, onExit: (v) => (finalVerdict = v) }), {
+        exitOnCtrlC: false,
+    });
+    void app.waitUntilExit().then(() => {
+        if (finalVerdict) {
+            // Ink erased its frame on unmount; reprint the verdict marker plus the run's recap block
+            // (the same summary a bare run prints) so the pointers to the on-disk record survive.
+            console.log("");
+            console.log(finalVerdict.ok ? "✓ ok" : "✗ failed");
+            for (const line of finalVerdict.summary)
+                console.log(line);
+            process.exitCode = finalVerdict.ok ? 0 : 1;
+        }
+        // Backstop: the runner disconnects the supervised child so both processes can exit, but if
+        // anything (a wedged pipe, a lingering handle) keeps the event loop alive past the grace,
+        // force the exit. Unref'd, so it only fires when the process is genuinely stuck — a clean
+        // exit beats it to the punch and this never runs.
+        setTimeout(() => process.exit(process.exitCode ?? 0), 2000).unref();
+    });
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+export interface Cli {
+    command: string;
+    target?: string;
+    json: boolean;
+    tsconfig: string;
+}
+/** Parse argv (without node/script) into a command, an optional target, and flags. */
+export declare function parseCli(argv: string[]): Cli;

package/dist/cli/index.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+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";
+/** Parse argv (without node/script) into a command, an optional target, and flags. */
+export function parseCli(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            json: { type: "boolean", default: false },
+            tsconfig: { type: "string", default: "tsconfig.omkit.json" },
+        },
+        allowPositionals: true,
+    });
+    return {
+        command: positionals[0] ?? "run",
+        target: positionals[1],
+        json: Boolean(values.json),
+        tsconfig: values.tsconfig,
+    };
+}
+/** 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));
+    const client = createOmkitClient({ tsconfig: cli.tsconfig });
+    if (cli.command === "init") {
+        const { scaffold } = await import("./commands/init.js");
+        const { created, skipped } = scaffold(process.cwd());
+        for (const f of created)
+            console.log(`created ${f}`);
+        for (const f of skipped)
+            console.log(`exists, skipped ${f}`);
+        return;
+    }
+    if (cli.command === "ls") {
+        const { formatRegistry } = await import("./commands/ls.js");
+        console.log(formatRegistry(await client.discover(), { json: cli.json }));
+        return;
+    }
+    if (cli.command === "check") {
+        const { formatDiagnostics } = await import("./commands/check.js");
+        const { text, code } = formatDiagnostics(await client.check());
+        console.log(text);
+        process.exitCode = code;
+        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) {
+            const { launchUi } = await import("./commands/ui.js");
+            launchUi(client);
+            return;
+        }
+        const { resolveOm } = await import("./commands/run.js");
+        const { spawnBare } = await import("./client/runner.js");
+        const registry = await client.discover();
+        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;
+        }
+        process.on("SIGINT", () => { }); // let the child tear down; don't die first
+        process.exitCode = await spawnBare(omFile, { cwd: path.dirname(omFile) });
+        return;
+    }
+    console.error(`unknown command "${cli.command}"`);
+    process.exitCode = 1;
+}
+/**
+ * True when this module is the process entry point — not when a test imports `parseCli`.
+ * Compares real paths so it holds even when invoked through the `.bin` symlink (where
+ * `process.argv[1]` is the link, not the resolved file).
+ */
+function isEntryPoint() {
+    const argv1 = process.argv[1];
+    if (!argv1)
+        return false;
+    try {
+        return realpathSync(argv1) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntryPoint())
+    void main();

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

@@ -0,0 +1,10 @@
+import { type ReactElement } from "react";
+/**
+ * A tiny animated spinner — cycles braille frames on a timer. Self-contained (no `ink-spinner`
+ * dependency). The interval is unref'd so it never keeps the process alive on its own: it animates
+ * only while something else (the live run's IPC channel) holds the event loop open, and stops the
+ * instant the run is disposed — so it can't block the app's exit.
+ */
+export declare function Spinner({ label }: {
+    label?: string;
+}): ReactElement;

package/dist/cli/ui/Spinner.js

@@ -0,0 +1,20 @@
+import { jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { Text } from "ink";
+// Braille dots — a smooth ten-frame cycle that reads as motion in a terminal.
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/**
+ * A tiny animated spinner — cycles braille frames on a timer. Self-contained (no `ink-spinner`
+ * dependency). The interval is unref'd so it never keeps the process alive on its own: it animates
+ * only while something else (the live run's IPC channel) holds the event loop open, and stops the
+ * instant the run is disposed — so it can't block the app's exit.
+ */
+export function Spinner({ label }) {
+    const [frame, setFrame] = useState(0);
+    useEffect(() => {
+        const id = setInterval(() => setFrame((f) => (f + 1) % FRAMES.length), 80);
+        id.unref?.();
+        return () => clearInterval(id);
+    }, []);
+    return (_jsxs(Text, { dimColor: true, children: [FRAMES[frame], label ? ` ${label}` : ""] }));
+}