omkit 0.4.5 → 0.4.6

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 {

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/package.json

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