omkit 0.4.4 → 0.4.6

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

@@ -7,8 +7,8 @@ export interface Transport {
     onClose(handler: (code: number | null) => void): void;
 }
 /**
- * Turn a child transport into a {@link RunSession}: fan `log`/`prompt` child messages out to
- * handlers, resolve `result` on `settled`, and map `answer`/`cancel` back down the wire. A
- * close before `settled` resolves a failed verdict so `result` never hangs.
+ * Turn a child transport into a {@link RunSession}: fan `log`/`prompt`/`prompt-done` child
+ * messages out to handlers, resolve `result` on `settled`, and map `answer`/`cancel` back down
+ * the wire. A close before `settled` resolves a failed verdict so `result` never hangs.
  */
 export declare function createChannel(transport: Transport): RunSession;

package/dist/cli/client/channel.js

@@ -1,12 +1,13 @@
 /**
- * Turn a child transport into a {@link RunSession}: fan `log`/`prompt` child messages out to
- * handlers, resolve `result` on `settled`, and map `answer`/`cancel` back down the wire. A
- * close before `settled` resolves a failed verdict so `result` never hangs.
+ * Turn a child transport into a {@link RunSession}: fan `log`/`prompt`/`prompt-done` child
+ * messages out to handlers, resolve `result` on `settled`, and map `answer`/`cancel` back down
+ * the wire. A close before `settled` resolves a failed verdict so `result` never hangs.
  */
 export function createChannel(transport) {
     const handlers = {
         log: [],
         prompt: [],
+        promptDone: [],
         settled: [],
     };
     let settled = false;
@@ -21,6 +22,10 @@ export function createChannel(transport) {
             for (const h of handlers.prompt)
                 h({ id: message.id, spec: message.spec });
         }
+        else if (message.kind === "prompt-done") {
+            for (const h of handlers.promptDone)
+                h(message.id);
+        }
         else if (message.kind === "settled") {
             settled = true;
             const verdict = { ok: message.ok, folder: message.folder, summary: message.summary };

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

@@ -1,9 +1,12 @@
 import type { OmkitClient } from "./types.ts";
-export type { OmkitClient, RunSession, RunOptions, Verdict, Diagnostic, PromptRequest, RunEvents, } from "./types.ts";
+export type { OmkitClient, RunSession, RunOptions, InspectOptions, 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`. */
+import type { InspectOptions } from "./types.ts";
+/** Configuration for a client — the project's `tsconfig.omkit.json` and optional debugging. */
 export interface OmkitConfig {
     tsconfig: string;
+    /** 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. */
 export declare function createOmkitClient(config: OmkitConfig): OmkitClient;

package/dist/cli/client/index.js

@@ -5,7 +5,7 @@ import { runCheck } from "./check.js";
 export function createOmkitClient(config) {
     return {
         discover: async () => discover(config.tsconfig),
-        run: (omFile, opts) => runOm(omFile, opts),
+        run: (omFile, opts) => runOm(omFile, { ...opts, inspect: config.inspect }),
         check: async () => runCheck(config.tsconfig),
     };
 }

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

@@ -1,4 +1,10 @@
-import type { RunSession, RunOptions } from "./types.ts";
+import type { RunSession, RunOptions, InspectOptions } from "./types.ts";
+/**
+ * The inspector flag to prepend to a child's `execArgv` — empty when no inspector is requested.
+ * Plain `--inspect` opens the port without stopping, so the child still installs its teardown
+ * handlers and settles normally.
+ */
+export declare function inspectArgs(inspect: InspectOptions | undefined): string[];
 /**
  * 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
@@ -10,6 +16,4 @@ 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>;
+export declare function spawnBare(omFile: string, opts?: RunOptions): Promise<number>;

package/dist/cli/client/runner.js

@@ -7,6 +7,16 @@ import { createChannel } from "./channel.js";
  * a run in any directory still finds the loader shipped with omkit.
  */
 const tsxLoader = import.meta.resolve("tsx");
+/**
+ * The inspector flag to prepend to a child's `execArgv` — empty when no inspector is requested.
+ * Plain `--inspect` opens the port without stopping, so the child still installs its teardown
+ * handlers and settles normally.
+ */
+export function inspectArgs(inspect) {
+    if (!inspect)
+        return [];
+    return [`--inspect=${inspect.port}`];
+}
 /**
  * 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
@@ -15,7 +25,7 @@ const tsxLoader = import.meta.resolve("tsx");
  */
 export function runOm(omFile, opts = {}) {
     const child = fork(omFile, [], {
-        execArgv: ["--import", tsxLoader],
+        execArgv: [...inspectArgs(opts.inspect), "--import", tsxLoader],
         cwd: opts.cwd ?? path.dirname(omFile),
         env: { ...process.env, OMKIT_SUPERVISED: "1" },
         stdio: ["ignore", "pipe", "pipe", "ipc"],
@@ -50,7 +60,7 @@ export function spawnBare(omFile, opts = {}) {
     const env = { ...process.env };
     delete env.OMKIT_SUPERVISED;
     const child = fork(omFile, [], {
-        execArgv: ["--import", tsxLoader],
+        execArgv: [...inspectArgs(opts.inspect), "--import", tsxLoader],
         cwd: opts.cwd ?? path.dirname(omFile),
         stdio: "inherit",
         env,

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

@@ -16,10 +16,17 @@ export interface Diagnostic {
     readonly line: number;
     readonly message: string;
 }
+/** Node inspector wiring for a run's forked child, so a debugger can attach to the om. */
+export interface InspectOptions {
+    /** Inspector port the child listens on. */
+    readonly port: number;
+}
 /** Options for launching a run. */
 export interface RunOptions {
     /** Working directory for the child process (defaults to the om file's directory). */
     readonly cwd?: string;
+    /** When set, fork the child with the Node inspector open so a debugger can attach. */
+    readonly inspect?: InspectOptions;
 }
 /** A prompt the running om is waiting on — surfaced to the frontend, answered via `answer`. */
 export interface PromptRequest {
@@ -30,6 +37,8 @@ export interface PromptRequest {
 export interface RunEvents {
     log: (entry: LogEntry) => void;
     prompt: (request: PromptRequest) => void;
+    /** A pending prompt was withdrawn by the child (timed out or torn down) — clear it from the UI. */
+    promptDone: (id: string) => void;
     settled: (verdict: Verdict) => void;
 }
 /** A live handle to one supervised run. */

package/dist/cli/index.d.ts

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
+import { type InspectOptions } from "./client/index.ts";
 export interface Cli {
     command: string;
     target?: string;
     json: boolean;
     tsconfig: string;
+    /** The Node inspector, if requested via `--inspect[=port]`. */
+    inspect?: InspectOptions;
 }
 /** 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

@@ -4,10 +4,31 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { realpathSync } from "node:fs";
 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
+ * always wins.
+ */
+function extractInspect(argv) {
+    let inspect;
+    const rest = [];
+    for (const arg of argv) {
+        const m = /^--inspect(?:=(\d+))?$/.exec(arg);
+        if (!m) {
+            rest.push(arg);
+            continue;
+        }
+        const port = m[1] ? Number(m[1]) : (inspect?.port ?? 9229);
+        inspect = { port };
+    }
+    return { inspect, rest };
+}
 /** Parse argv (without node/script) into a command, an optional target, and flags. */
 export function parseCli(argv) {
+    // Inspector flags take an optional `=PORT`, which `parseArgs` can't express — pull them first.
+    const { inspect, rest } = extractInspect(argv);
     const { values, positionals } = parseArgs({
-        args: argv,
+        args: rest,
         options: {
             json: { type: "boolean", default: false },
             tsconfig: { type: "string", default: "tsconfig.omkit.json" },
@@ -19,12 +40,24 @@ export function parseCli(argv) {
         target: positionals[1],
         json: Boolean(values.json),
         tsconfig: values.tsconfig,
+        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.
+ */
+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 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 });
+    const inspect = cli.inspect;
+    const client = createOmkitClient({ tsconfig: cli.tsconfig, inspect });
     if (cli.command === "init") {
         const { scaffold } = await import("./commands/init.js");
         const { created, skipped } = scaffold(process.cwd());
@@ -55,6 +88,10 @@ async function main() {
         // 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;
@@ -75,8 +112,10 @@ async function main() {
             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) });
+        process.exitCode = await spawnBare(omFile, { cwd: path.dirname(omFile), inspect });
         return;
     }
     console.error(`unknown command "${cli.command}"`);

package/dist/cli/ui/app.js

@@ -39,6 +39,10 @@ export function App({ client, onExit, oms: initialOms, }) {
                 setLines((prev) => [...prev, rendered.text]);
         });
         s.on("prompt", (req) => setPrompt(req));
+        // The child gave up on the prompt (timed out or torn down). Withdraw its box so a stale,
+        // unanswerable prompt doesn't linger — but only if it's still the one on screen, so a late
+        // withdrawal can't clobber a fresh prompt.
+        s.on("promptDone", (id) => setPrompt((p) => (p?.id === id ? undefined : p)));
         s.on("settled", (v) => {
             setVerdict(v);
             setPrompt(undefined);

package/dist/core/interaction.d.ts

@@ -17,6 +17,9 @@ export type ChildMessage = {
     kind: "prompt";
     id: string;
     spec: PromptSpec;
+} | {
+    kind: "prompt-done";
+    id: string;
 } | {
     kind: "log";
     entry: LogEntry;

package/dist/core/interaction.js

@@ -29,6 +29,10 @@ export class Supervisor {
         return new Promise((resolve, reject) => {
             const onAbort = () => {
                 this.pending.delete(id);
+                // The child is giving up on this prompt (timeout or teardown) and moving on. Tell the
+                // supervisor so it withdraws the prompt from its UI — otherwise a stale, unanswerable
+                // prompt box lingers on screen for the rest of the run.
+                this.send({ kind: "prompt-done", id });
                 reject(new Error("prompt aborted"));
             };
             if (signal.aborted)

package/dist/core/types.d.ts

@@ -58,10 +58,11 @@ export interface OmContext {
 }
 /**
  * A launched action: the live node's awaitable/observable surface, returned by
- * **invoking an {@link Action}**. `.result` always resolves an {@link Outcome} (never
- * throws); `.ref` rejects on failure/cancel. The body is committed one microtask after
- * the launching call, so pre-body config (`withCache`) chained before the first `await`
- * still applies.
+ * **invoking an {@link Action}**. `.result` (like `.ref` and `once`) resolves the value on
+ * success and **rejects** with the action's error on failure (or `CancelledError` on cancel);
+ * reading it observes the activity, so a handled failure won't tear the run down. The body is
+ * committed one microtask after the launching call, so pre-body config (`withCache`) chained
+ * before the first `await` still applies.
  */
 export interface Activity<Result = unknown, Events extends object = NoEvents, Handle = void> {
     readonly id: string;

package/package.json

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