omkit 0.4.8 → 0.8.1

package/dist/cli/index.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { realpathSync } from "node:fs";
 import { createOmkitClient } from "../client/index.js";
+import { DEFAULT_TSCONFIG } from "../client/types.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
@@ -31,8 +32,12 @@ export function parseCli(argv) {
         args: rest,
         options: {
             json: { type: "boolean", default: false },
-            tsconfig: { type: "string", default: "tsconfig.omkit.json" },
+            tsconfig: { type: "string", default: DEFAULT_TSCONFIG },
             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 +47,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 +71,67 @@ 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, skillRoot } = 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 enclosing repository, which
+    // is both where `.claude/` belongs and where the file's reader will be standing; `--root`
+    // remains for the project that is deliberately not at the top of its checkout.
+    const root = cli.root
+        ? path.resolve(cli.root)
+        : skillRoot(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, cli) => {
+        const { mcpCommand } = await import("./commands/mcp.js");
+        // The project owning the config, not the directory the server was launched from: run
+        // folders are written under it, so reading them back has to use the same answer. An
+        // assistant that starts the server from anywhere still sees the project's own runs.
+        await mcpCommand(client, { root: path.dirname(path.resolve(cli.tsconfig)) });
+    },
+    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 +141,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,18 +1,28 @@
-import { discover } from "./discovery.js";
+import path from "node:path";
+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.
-    const withInspect = (opts) => ({
+    // The project every run of this client belongs to: the directory owning the config it was
+    // built from. Injected here rather than at each frontend because "which project is this?" has
+    // one answer per client, and three call sites remembering it separately is how the terminal
+    // and the MCP server ended up writing their run folders to two different trees.
+    const root = path.dirname(path.resolve(config.tsconfig));
+    // A per-call inspect wins; the client's construction-time inspect is the fallback. Likewise
+    // a caller may name its own root — the injected one is a default, not an override.
+    const withDefaults = (opts) => ({
         ...opts,
         inspect: opts?.inspect ?? config.inspect,
+        env: { OMKIT_ROOT: root, ...opts?.env },
     });
     return {
         tsconfig: config.tsconfig,
         discover: async () => discover(config.tsconfig),
-        run: (omFile, opts) => runOm(omFile, withInspect(opts)),
-        runBare: (omFile, opts) => spawnBare(omFile, withInspect(opts)),
+        discoverRegistrations: async () => discoverRegistrations(config.tsconfig),
+        run: (omFile, opts) => runOm(omFile, withDefaults(opts)),
+        runBare: (omFile, opts) => spawnBare(omFile, withDefaults(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[];

package/dist/client/outline.js

@@ -0,0 +1,100 @@
+import ts from "typescript";
+/**
+ * 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 function importedNames(sf) {
+    const names = new Set();
+    for (const stmt of sf.statements) {
+        if (!ts.isImportDeclaration(stmt) || !stmt.importClause)
+            continue;
+        const clause = stmt.importClause;
+        if (clause.name)
+            names.add(clause.name.text);
+        const bindings = clause.namedBindings;
+        if (!bindings)
+            continue;
+        if (ts.isNamespaceImport(bindings))
+            names.add(bindings.name.text);
+        else
+            for (const el of bindings.elements)
+                names.add(el.name.text);
+    }
+    return names;
+}
+/**
+ * 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 function chainRoot(node) {
+    const calls = [];
+    let current = node;
+    while (ts.isCallExpression(current)) {
+        calls.push(current);
+        const callee = current.expression;
+        if (ts.isPropertyAccessExpression(callee)) {
+            current = callee.expression;
+            continue;
+        }
+        if (ts.isIdentifier(callee))
+            return { name: callee.text, call: current, calls };
+        return undefined;
+    }
+    return 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 function outlineBody(body, imported) {
+    const calls = [];
+    const seen = new Set();
+    const visit = (node) => {
+        const chain = ts.isCallExpression(node) ? chainRoot(node) : undefined;
+        if (chain && imported.has(chain.name)) {
+            const tag = tagOf(chain);
+            // Name and tag together are the identity: three `command` calls with distinct tags are
+            // three steps, while the same call written twice is one.
+            const key = `${chain.name} ${tag ?? ""}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                calls.push(tag === undefined ? { name: chain.name } : { name: chain.name, tag });
+            }
+            // The chain's own spine is now accounted for; only its arguments can hold further steps.
+            // Walking it again would re-enter each inner call and record the same step repeatedly.
+            for (const call of chain.calls)
+                for (const arg of call.arguments)
+                    visit(arg);
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(body);
+    return calls;
+}
+/**
+ * The `.tag("…")` on a chain, taken nearest its root. `calls` is outermost-first, so the last
+ * match is the innermost — the tag attached directly to the action rather than to something
+ * further along the chain.
+ */
+function tagOf(chain) {
+    let tag;
+    for (const call of chain.calls) {
+        const callee = call.expression;
+        if (!ts.isPropertyAccessExpression(callee) || callee.name.text !== "tag")
+            continue;
+        const arg = call.arguments[0];
+        if (arg && ts.isStringLiteralLike(arg))
+            tag = arg.text;
+    }
+    return tag;
+}