omkit 0.4.7 → 0.8.0

package/dist/cli/commands/ls.js

@@ -2,24 +2,44 @@ 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}`);
-    }
+        return renderJson(registry, opts.registrations);
+    const declared = index(opts.registrations);
+    const lines = [
+        `oms (${registry.oms.length})`,
+        ...registry.oms.flatMap((om) => row(`${om.name}  ${path.basename(om.file)}:${om.line}`, [], declared?.get(key(om.name, om.file)))),
+        "",
+        `actions (${registry.actions.length})`,
+        ...registry.actions.flatMap((a) => row(`${a.name}  ${path.basename(a.file)}`, [a.publishesCapability ? "ref" : "", a.events ? "events" : ""], declared?.get(key(a.name, a.file)))),
+    ];
     if (registry.warnings.length) {
-        lines.push("");
-        lines.push(`warnings (${registry.warnings.length})`);
+        lines.push("", `warnings (${registry.warnings.length})`);
         for (const w of registry.warnings)
             lines.push(`  ${w}`);
     }
     return lines.join("\n");
 }
+/** One entry: its head line with any markers, plus an indented summary when one was declared. */
+function row(head, tags, meta) {
+    const all = [...tags, ...mcpTags(meta)].filter(Boolean);
+    const suffix = all.length ? `  [${all.join(", ")}]` : "";
+    return meta?.summary ? [`  ${head}${suffix}`, `    ${meta.summary}`] : [`  ${head}${suffix}`];
+}
+function renderJson(registry, registrations) {
+    return JSON.stringify(registrations ? { ...registry, ...registrations } : registry, null, 2);
+}
+/** Declarations keyed by name-in-file, so a name reused across files cannot cross over. */
+function index(set) {
+    if (!set)
+        return undefined;
+    const byKey = new Map();
+    for (const r of [...set.oms, ...set.actions])
+        byKey.set(key(r.name, r.file), r);
+    return byKey;
+}
+const key = (name, file) => `${name}\0${path.resolve(file)}`;
+/** `[mcp]` / `[mcp, long-lived]` — only meaningful once the fork has told us what is exposed. */
+function mcpTags(meta) {
+    if (!meta?.mcp)
+        return [];
+    return meta.mcp.mode === "long-lived" ? ["mcp", "long-lived"] : ["mcp"];
+}

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

@@ -0,0 +1,10 @@
+import type { OmkitClient } from "../../client/index.ts";
+/**
+ * The `mcp` command: serve this project over MCP on stdio, until the client hangs up.
+ *
+ * Deliberately silent. Every other command prints; this one must not, because its stdout
+ * is the protocol stream — a banner here reaches the client as a JSON parse error.
+ */
+export declare function mcpCommand(client: OmkitClient, opts: {
+    root: string;
+}): Promise<void>;

package/dist/cli/commands/mcp.js

@@ -0,0 +1,13 @@
+import { startMcpServer } from "../../mcp/server.js";
+/**
+ * The `mcp` command: serve this project over MCP on stdio, until the client hangs up.
+ *
+ * Deliberately silent. Every other command prints; this one must not, because its stdout
+ * is the protocol stream — a banner here reaches the client as a JSON parse error.
+ */
+export async function mcpCommand(client, opts) {
+    await startMcpServer({ client, root: opts.root });
+    // `connect` resolves once the transport is bound; the transport keeps the process alive
+    // from here, so hold the command open rather than falling out of `main` and exiting.
+    await new Promise(() => { });
+}

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

@@ -0,0 +1,17 @@
+import type { OmkitClient } from "../../client/index.ts";
+export interface SkillOptions {
+    /** Project root the skill is written relative to — the directory owning the tsconfig. */
+    readonly root: string;
+    /** Override the output path (still resolved against `root` when relative). */
+    readonly out?: string;
+    /** Compare hashes and exit non-zero on drift instead of writing. */
+    readonly check?: boolean;
+}
+/**
+ * The `skill` command: generate `.claude/skills/omkit-runs/SKILL.md` from what this project's
+ * oms and actions declare, so an assistant knows what is runnable before its first tool call.
+ *
+ * Generation runs no workflow. It uses the same `OMKIT_DISCOVER=1` fork the MCP server's
+ * `list_oms` uses, which returns from `launch()` before an execution tree exists.
+ */
+export declare function skillCommand(client: OmkitClient, opts: SkillOptions): Promise<void>;

package/dist/cli/commands/skill.js

@@ -0,0 +1,56 @@
+import path from "node:path";
+import { buildSkillModel, readExisting, renderSkill, writeSkill, DEFAULT_DESCRIPTION, SKILL_RELATIVE_PATH, } from "../../skill/index.js";
+const EMPTY_REGISTRY = { oms: [], actions: [], warnings: [] };
+/**
+ * The `skill` command: generate `.claude/skills/omkit-runs/SKILL.md` from what this project's
+ * oms and actions declare, so an assistant knows what is runnable before its first tool call.
+ *
+ * Generation runs no workflow. It uses the same `OMKIT_DISCOVER=1` fork the MCP server's
+ * `list_oms` uses, which returns from `launch()` before an execution tree exists.
+ */
+export async function skillCommand(client, opts) {
+    const file = path.resolve(opts.root, opts.out ?? SKILL_RELATIVE_PATH);
+    const registrations = await client.discoverRegistrations();
+    const model = buildSkillModel(registrations, registrations.registry ?? EMPTY_REGISTRY, opts.root);
+    const existing = readExisting(file);
+    if (opts.check) {
+        reportCheck(file, existing.hash, model.hash);
+        return;
+    }
+    // The description is the skill's loading trigger and is authored, so an existing one always
+    // wins; the fallback is only ever written into a file that does not exist yet.
+    const content = renderSkill(model, { description: existing.description ?? DEFAULT_DESCRIPTION });
+    writeSkill(file, content);
+    const total = model.oms.length + model.actions.length;
+    console.log(`wrote ${path.relative(opts.root, file) || file}`);
+    console.log(`  ${model.oms.length} om${model.oms.length === 1 ? "" : "s"}, ` +
+        `${model.actions.length} action${model.actions.length === 1 ? "" : "s"}  ` +
+        `[registry-hash: ${model.hash}]`);
+    if (total === 0) {
+        console.log("  nothing is exposed yet — mark an om or action with .mcp() to list it");
+    }
+    reportWarnings(registrations.warnings);
+}
+/**
+ * `--check` is for a hook or a CI step, so it says what changed and sets the exit code rather
+ * than writing. A file with no marker at all counts as drift: it was hand-written or predates
+ * the generator, and either way regenerating is the fix.
+ */
+function reportCheck(file, existing, fresh) {
+    if (existing === fresh) {
+        console.log(`up to date  [registry-hash: ${fresh}]`);
+        return;
+    }
+    const detail = existing === undefined ? "no registry-hash found" : `has ${existing}`;
+    console.error(`${file} is stale — ${detail}, project is ${fresh}`);
+    console.error("run `omkit skill` to regenerate");
+    process.exitCode = 1;
+}
+/** Discovery degrades to warnings rather than failing, so they have to reach the terminal. */
+function reportWarnings(warnings) {
+    if (warnings.length === 0)
+        return;
+    console.error(`\nwarnings (${warnings.length})`);
+    for (const w of warnings)
+        console.error(`  ${w}`);
+}

package/dist/cli/index.d.ts

@@ -7,6 +7,14 @@ export interface Cli {
     tsconfig: string;
     /** Set by `--help`/`-h` (the `help` command is carried on `command` instead). */
     help: boolean;
+    /** `ls --describe`: import the oms to read their summaries, instead of staying AST-only. */
+    describe: boolean;
+    /** `skill --check`: report drift and exit non-zero instead of writing. */
+    check: boolean;
+    /** `skill --out <path>`: write somewhere other than `.claude/skills/omkit-runs/SKILL.md`. */
+    out?: string;
+    /** `skill --root <path>`: the project the skill describes, when the tsconfig sits below it. */
+    root?: string;
     /** The Node inspector, if requested via `--inspect[=port]`. */
     inspect?: InspectOptions;
 }

package/dist/cli/index.js

@@ -33,6 +33,10 @@ export function parseCli(argv) {
             json: { type: "boolean", default: false },
             tsconfig: { type: "string", default: "tsconfig.omkit.json" },
             help: { type: "boolean", short: "h", default: false },
+            describe: { type: "boolean", default: false },
+            check: { type: "boolean", default: false },
+            out: { type: "string" },
+            root: { type: "string" },
         },
         allowPositionals: true,
     });
@@ -42,6 +46,10 @@ export function parseCli(argv) {
         json: Boolean(values.json),
         tsconfig: values.tsconfig,
         help: Boolean(values.help),
+        describe: Boolean(values.describe),
+        check: Boolean(values.check),
+        ...(values.out === undefined ? {} : { out: values.out }),
+        ...(values.root === undefined ? {} : { root: values.root }),
         inspect,
     };
 }
@@ -62,6 +70,62 @@ async function checkCommand(client) {
     await renderDiagnostics({ kind: n === 0 ? "ok" : "error", title, items }, n === 0 ? process.stdout : process.stderr);
     process.exitCode = n === 0 ? 0 : 1;
 }
+/**
+ * The `ls` command: print the discovered oms and actions.
+ *
+ * `--describe` is the only path here that imports user code. Without it `ls` is the AST scan
+ * and nothing else — the property that keeps it instant and safe to run in any repo, including
+ * one whose oms would start servers if they were evaluated.
+ */
+async function lsCommand(client, cli) {
+    const { formatRegistry } = await import("./commands/ls.js");
+    const { withSpinner } = await import("./ui/Report.js");
+    if (!cli.describe) {
+        const registry = await withSpinner("discovering…", () => client.discover());
+        console.log(formatRegistry(registry, { json: cli.json }));
+        return;
+    }
+    const registrations = await withSpinner("reading declarations…", () => client.discoverRegistrations());
+    const registry = registrations.registry ?? (await client.discover());
+    console.log(formatRegistry(registry, { json: cli.json, registrations }));
+}
+/** The `init` command: scaffold a starter project in the current directory. */
+async function initCommand() {
+    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}`);
+}
+/** The `skill` command: generate the runnable-workflow map for an assistant to read. */
+async function generateSkill(client, cli) {
+    const { skillCommand } = await import("./commands/skill.js");
+    // The root decides two things at once — where `.claude/` goes, and what the recorded paths are
+    // relative to — so it is one setting, not two. It defaults to the tsconfig's directory (the
+    // common layout, where they are the same place); `--root` covers the repo that keeps its om
+    // project in a subfolder, where the reader's cwd is the repo and so the paths must be too.
+    const root = cli.root ? path.resolve(cli.root) : path.dirname(path.resolve(cli.tsconfig));
+    await skillCommand(client, { root, check: cli.check, ...(cli.out ? { out: cli.out } : {}) });
+}
+/**
+ * Every command, by name. A table rather than a chain of `if`s: each entry is one lazy import
+ * and one call, so adding a command cannot quietly grow the entry point's branching.
+ */
+const COMMANDS = {
+    init: () => initCommand(),
+    ls: (client, cli) => lsCommand(client, cli),
+    check: (client) => checkCommand(client),
+    mcp: async (client) => {
+        const { mcpCommand } = await import("./commands/mcp.js");
+        await mcpCommand(client, { root: process.cwd() });
+    },
+    skill: (client, cli) => generateSkill(client, cli),
+    run: async (client, cli) => {
+        const { runCommand } = await import("./commands/run.js");
+        await runCommand(client, { target: cli.target, inspect: cli.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));
@@ -71,37 +135,15 @@ async function main() {
         console.log(helpText());
         return;
     }
-    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());
-        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");
-        const { withSpinner } = await import("./ui/Report.js");
-        const registry = await withSpinner("discovering…", () => client.discover());
-        console.log(formatRegistry(registry, { json: cli.json }));
-        return;
-    }
-    if (cli.command === "check") {
-        await checkCommand(client);
-        return;
-    }
-    if (cli.command === "run") {
-        const { runCommand } = await import("./commands/run.js");
-        await runCommand(client, { target: cli.target, inspect: cli.inspect });
+    const handler = COMMANDS[cli.command];
+    if (!handler) {
+        const { helpText } = await import("./commands/help.js");
+        console.error(`unknown command "${cli.command}"\n`);
+        console.error(helpText());
+        process.exitCode = 1;
         return;
     }
-    const { helpText } = await import("./commands/help.js");
-    console.error(`unknown command "${cli.command}"\n`);
-    console.error(helpText());
-    process.exitCode = 1;
+    await handler(createOmkitClient({ tsconfig: cli.tsconfig, inspect: cli.inspect }), cli);
 }
 /**
  * True when this module is the process entry point — not when a test imports `parseCli`.

package/dist/client/discover-child.d.ts

@@ -0,0 +1,12 @@
+import type { ActionRegistration } from "./registry.ts";
+/** The parent's opening message: sent over IPC, so no argv length limit applies. */
+export interface ScanMessage {
+    readonly kind: "scan";
+    readonly files: string[];
+}
+/** The child's closing message. Om registrations arrive separately, as each om is reached. */
+export interface ActionsMessage {
+    readonly kind: "actions";
+    readonly actions: ActionRegistration[];
+    readonly warnings: string[];
+}

package/dist/client/discover-child.js

@@ -0,0 +1,71 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { pathToFileURL } from "node:url";
+function asAction(value) {
+    if (typeof value !== "function")
+        return undefined;
+    const candidate = value;
+    if (typeof candidate.actionName !== "string")
+        return undefined;
+    if (typeof candidate.describeArgs !== "function")
+        return undefined;
+    return candidate;
+}
+/**
+ * The discovery child. Forked with `OMKIT_DISCOVER=1`, so importing a file makes every
+ * `om(...).run(...)` in it post a registration up this same channel instead of launching
+ * (see core/discovery-mode.ts). Actions post nothing — they are plain values — so their
+ * metadata is read off each module's exports here, afterwards.
+ */
+async function scan(files) {
+    const actions = [];
+    const warnings = [];
+    for (const file of files) {
+        let mod;
+        try {
+            mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+        }
+        catch (e) {
+            warnings.push(`${file}: ${e instanceof Error ? e.message : String(e)}`);
+            continue;
+        }
+        for (const [exportName, value] of Object.entries(mod)) {
+            const found = asAction(value);
+            if (!found)
+                continue;
+            const { inputSchema, schemaError } = found.describeArgs();
+            actions.push({
+                name: found.actionName,
+                exportName,
+                file,
+                ...(found.description ? { summary: found.description.summary } : {}),
+                ...(found.mcp ? { mcp: found.mcp } : {}),
+                ...(inputSchema ? { inputSchema } : {}),
+                ...(schemaError ? { unavailable: schemaError } : {}),
+            });
+        }
+    }
+    // Exit only once the message has actually flushed. `process.send` is asynchronous —
+    // exiting on the next line can drop the payload before it reaches the parent, and the
+    // parent would see a `close` with no `actions` message and report an empty project.
+    // A user module may also have started a server or a timer at import; nothing here is
+    // supervised and nothing will tear it down, so leave deliberately rather than linger.
+    const done = () => process.exit(0);
+    if (process.send) {
+        process.send({ kind: "actions", actions, warnings }, done);
+    }
+    else {
+        done();
+    }
+}
+process.on("message", (message) => {
+    if (message?.kind === "scan") {
+        void scan(message.files);
+    }
+});

package/dist/client/discovery.d.ts

@@ -1,4 +1,4 @@
-import type { Registry } from "./registry.ts";
+import type { Registry, RegistrationSet } from "./registry.ts";
 /**
  * Statically scan the project described by `tsconfigPath` for runnable oms and inspectable
  * actions. Type errors in the user's oms/actions degrade to `warnings` (an editor-in-progress
@@ -6,3 +6,23 @@ import type { Registry } from "./registry.ts";
  * tsconfig — throws, so the CLI crashes visibly instead of silently returning an empty project.
  */
 export declare function discover(tsconfigPath: string): Registry;
+/**
+ * Import `files` in a throwaway child with `OMKIT_DISCOVER=1` and collect what they
+ * declare. Exposed separately from {@link discoverRegistrations} so the fork can be driven
+ * with an explicit file list — by tests, and by anything that already knows its candidates.
+ *
+ * Never rejects for user-code problems: an import failure, a crashed child, or a child
+ * that outstays its timeout all come back as warnings on an otherwise usable set.
+ */
+export declare function readRegistrations(files: string[], opts?: {
+    cwd?: string;
+    timeoutMs?: number;
+}): Promise<RegistrationSet>;
+/**
+ * The full pass: the AST scan picks the candidate files — it stays the only cheap,
+ * never-executing phase — then {@link readRegistrations} imports just those. AST warnings
+ * are carried through so nothing is lost between the two phases.
+ */
+export declare function discoverRegistrations(tsconfigPath: string, opts?: {
+    timeoutMs?: number;
+}): Promise<RegistrationSet>;

package/dist/client/discovery.js

@@ -1,5 +1,12 @@
 import ts from "typescript";
 import path from "node:path";
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { omHash } from "../foundation/ids.js";
+import { fsSafe } from "../foundation/fsSafe.js";
+import { canonicalPath } from "../foundation/canonicalPath.js";
+import { tsxLoader } from "./runner.js";
+import { chainRoot, importedNames, outlineBody } from "./outline.js";
 /**
  * Statically scan the project described by `tsconfigPath` for runnable oms and inspectable
  * actions. Type errors in the user's oms/actions degrade to `warnings` (an editor-in-progress
@@ -20,16 +27,28 @@ export function discover(tsconfigPath) {
     for (const sf of program.getSourceFiles()) {
         if (!fileSet.has(canonical(sf.fileName)))
             continue;
+        // TypeScript hands back its own spelling of the path — on Windows it lowercases the drive
+        // letter — and every consumer downstream keys on this string: the discovery fork imports
+        // it, `omHash` hashes it, and Node caches modules by it. Canonicalise once here so the
+        // whole chain agrees with the filesystem, and with the paths a real run reports.
+        const file = canonicalPath(sf.fileName);
         for (const d of program.getSemanticDiagnostics(sf))
             warnings.push(formatDiagnostic(d));
         const names = omkitImports(sf);
+        const outlines = outlinesIn(sf, names.om, importedNames(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) });
+                    const calls = outlines.get(arg.text);
+                    oms.push({
+                        name: arg.text,
+                        file,
+                        line: lineOf(sf, node),
+                        ...(calls?.length ? { calls } : {}),
+                    });
                 }
             }
             ts.forEachChild(node, visit);
@@ -45,7 +64,7 @@ export function discover(tsconfigPath) {
                 if (info) {
                     actions.push({
                         name: info.name,
-                        file: sf.fileName,
+                        file,
                         exportName: decl.name.text,
                         publishesCapability: info.ref,
                         events: info.emits,
@@ -56,6 +75,124 @@ export function discover(tsconfigPath) {
     }
     return { oms, actions, warnings };
 }
+/**
+ * Outline every `om("name")…​.run(body)` chain in a file, keyed by om name.
+ *
+ * Collected in its own pass rather than alongside the `om(...)` match, because a body is only
+ * reachable from the `.run` end of the chain and the om name only from the other — and the
+ * chain is walked downward (see {@link chainRoot}), so one pass cannot have both.
+ */
+function outlinesIn(sf, omName, imported) {
+    const outlines = new Map();
+    if (omName === undefined)
+        return outlines;
+    const visit = (node) => {
+        if (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression) &&
+            node.expression.name.text === "run") {
+            const root = chainRoot(node);
+            const body = node.arguments[0];
+            const name = root?.call.arguments[0];
+            if (root?.name === omName && name && ts.isStringLiteralLike(name) && body) {
+                if (ts.isFunctionLike(body))
+                    outlines.set(name.text, outlineBody(body, imported));
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return outlines;
+}
+/** How long the child gets to import every file before it is killed and reported. */
+const DISCOVER_TIMEOUT_MS = 30_000;
+/**
+ * Absolute path of a sibling module, carrying the extension this build actually uses —
+ * `.ts` under tsx and vitest, `.js` once compiled. `rewriteRelativeImportExtensions`
+ * rewrites import specifiers; this path is data (a fork target), so it does not.
+ */
+function siblingScript(name) {
+    const here = fileURLToPath(import.meta.url);
+    return path.join(path.dirname(here), `${name}${path.extname(here)}`);
+}
+/** Project an om's registration message onto the client-facing shape, folder name and all. */
+function toOmRegistration(m) {
+    return {
+        name: m.name,
+        file: m.file ?? "",
+        folderName: `${fsSafe(m.name)}-${omHash(m.name, m.file)}`,
+        ...(m.description ? { summary: m.description.summary } : {}),
+        ...(m.mcp ? { mcp: m.mcp } : {}),
+        ...(m.inputSchema ? { inputSchema: m.inputSchema } : {}),
+        ...(m.schemaError ? { unavailable: m.schemaError } : {}),
+    };
+}
+/**
+ * Import `files` in a throwaway child with `OMKIT_DISCOVER=1` and collect what they
+ * declare. Exposed separately from {@link discoverRegistrations} so the fork can be driven
+ * with an explicit file list — by tests, and by anything that already knows its candidates.
+ *
+ * Never rejects for user-code problems: an import failure, a crashed child, or a child
+ * that outstays its timeout all come back as warnings on an otherwise usable set.
+ */
+export function readRegistrations(files, opts = {}) {
+    if (files.length === 0)
+        return Promise.resolve({ oms: [], actions: [], warnings: [] });
+    const timeoutMs = opts.timeoutMs ?? DISCOVER_TIMEOUT_MS;
+    return new Promise((resolve) => {
+        const oms = [];
+        const warnings = [];
+        const child = fork(siblingScript("discover-child"), [], {
+            execArgv: ["--import", tsxLoader],
+            cwd: opts.cwd ?? path.dirname(files[0]),
+            env: { ...process.env, OMKIT_DISCOVER: "1" },
+            stdio: ["ignore", "pipe", "pipe", "ipc"],
+        });
+        let settled = false;
+        const finish = (actions) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill();
+            resolve({ oms, actions, warnings });
+        };
+        const timer = setTimeout(() => {
+            warnings.push(`discovery timed out after ${timeoutMs}ms`);
+            finish([]);
+        }, timeoutMs);
+        child.on("message", (message) => {
+            const m = message;
+            if (m.kind === "om-registration")
+                oms.push(toOmRegistration(m));
+            else if (m.kind === "actions") {
+                warnings.push(...m.warnings);
+                finish(m.actions);
+            }
+        });
+        // A child that dies before reporting still yields whatever streamed in before it did.
+        child.on("close", () => finish([]));
+        child.on("error", (e) => {
+            warnings.push(`discovery child failed: ${e.message}`);
+            finish([]);
+        });
+        child.send({ kind: "scan", files });
+    });
+}
+/**
+ * The full pass: the AST scan picks the candidate files — it stays the only cheap,
+ * never-executing phase — then {@link readRegistrations} imports just those. AST warnings
+ * are carried through so nothing is lost between the two phases.
+ */
+export async function discoverRegistrations(tsconfigPath, opts = {}) {
+    const ast = discover(tsconfigPath);
+    const files = [...new Set([...ast.oms.map((o) => o.file), ...ast.actions.map((a) => a.file)])];
+    const set = await readRegistrations(files, {
+        cwd: path.dirname(path.resolve(tsconfigPath)),
+        ...opts,
+    });
+    return { ...set, warnings: [...ast.warnings, ...set.warnings], registry: ast };
+}
 /**
  * Load and validate the tsconfig, throwing on a fatal config problem — a missing/unparseable file,
  * or a config-level error (bad compilerOptions, an unresolvable `extends`). The benign "no inputs

package/dist/client/index.d.ts

@@ -1,6 +1,7 @@
 import type { OmkitClient } from "./types.ts";
+export { readRegistrations, discoverRegistrations } from "./discovery.ts";
 export type { OmkitClient, RunSession, RunOptions, InspectOptions, Verdict, Diagnostic, PromptRequest, RunEvents, } from "./types.ts";
-export type { Registry, DiscoveredOm, DiscoveredAction } from "./registry.ts";
+export type { Registry, DiscoveredOm, DiscoveredAction, Registration, OmRegistration, ActionRegistration, RegistrationSet, } from "./registry.ts";
 import type { InspectOptions } from "./types.ts";
 /** Configuration for a client — the project's `tsconfig.omkit.json` and optional debugging. */
 export interface OmkitConfig {

package/dist/client/index.js

@@ -1,6 +1,7 @@
-import { discover } from "./discovery.js";
+import { discover, discoverRegistrations } from "./discovery.js";
 import { runOm, spawnBare } from "./runner.js";
 import { runCheck } from "./check.js";
+export { readRegistrations, discoverRegistrations } from "./discovery.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.
@@ -11,6 +12,7 @@ export function createOmkitClient(config) {
     return {
         tsconfig: config.tsconfig,
         discover: async () => discover(config.tsconfig),
+        discoverRegistrations: async () => discoverRegistrations(config.tsconfig),
         run: (omFile, opts) => runOm(omFile, withInspect(opts)),
         runBare: (omFile, opts) => spawnBare(omFile, withInspect(opts)),
         check: async () => runCheck(config.tsconfig),

package/dist/client/outline.d.ts

@@ -0,0 +1,35 @@
+import ts from "typescript";
+import type { OmCall } from "./registry.ts";
+/**
+ * Every identifier a file binds through an import — the whole allow-list for the outline.
+ * An action always arrives by import (`omkit/actions`, or a local actions module), so
+ * "was imported" is a cheap stand-in for "is a step" that never needs the type checker.
+ */
+export declare function importedNames(sf: ts.SourceFile): ReadonlySet<string>;
+/** A fluent chain resolved down to the call that starts it: `a(…).b().c()` → the `a(…)`. */
+export interface ChainRoot {
+    /** The identifier the chain is rooted in. */
+    readonly name: string;
+    /** The base call itself, so a caller can read its arguments. */
+    readonly call: ts.CallExpression;
+    /** Every call in the chain, outermost first. */
+    readonly calls: readonly ts.CallExpression[];
+}
+/**
+ * Walk a fluent chain down from any of its calls to the identifier call at its root.
+ *
+ * Descends through `.expression` rather than climbing through `.parent`: a `SourceFile` from
+ * `ts.createProgram` only has parent pointers once its file has been bound, so climbing would
+ * work or not depending on whether the caller happened to ask for diagnostics first.
+ */
+export declare function chainRoot(node: ts.CallExpression): ChainRoot | undefined;
+/**
+ * A static sketch of what an om body calls: imported identifiers invoked directly inside
+ * `.run(body)`, in source order, each paired with the `.tag("…")` from its own fluent chain.
+ *
+ * Deliberately an approximation, and labelled as one wherever it is rendered. A conditional
+ * call appears unconditionally, a loop appears once, an action picked dynamically does not
+ * appear at all, and a call made inside a module-level helper is invisible — the walk does
+ * not follow indirection. It answers "roughly what happens in here" and nothing stronger.
+ */
+export declare function outlineBody(body: ts.Node, imported: ReadonlySet<string>): OmCall[];