@runa-cmd/core 0.1.0 → 0.2.0-beta.1

package/dist/cli.js

@@ -12,66 +12,38 @@
  */
 import { parseArgs } from 'node:util';
 import { loadAndMergeConfig } from './config/merge.js';
-import { CommandNotFoundError, RunaError } from './errors.js';
+import { CommandNotFoundError, describeFailure, failureReason, isDebugEnabled, isUsageError, RunaError, ValidationError, } from './errors.js';
+import { flagName } from './flag-name.js';
+import { commandClaims, findHelpTarget, HELP_TOKENS, renderHelp } from './help.js';
 import { getSchema } from './introspect.js';
 import { createHookRegistry } from './lifecycle.js';
+import { deprecationWarnings } from './parse/deprecated.js';
 import { buildParseArgsConfig } from './parse/parseargs-bridge.js';
-import { resolveValues } from './parse/resolve.js';
+import { distributeRest, resolveToolInput, resolveValues } from './parse/resolve.js';
 import { walkSchema } from './parse/schema-walker.js';
-import { resolvePlugins, runPluginCleanup, runPluginSetup, topologicalSort } from './plugin.js';
+import { assertKnownOptions, assertOptionValues } from './parse/strict.js';
+import { resolvePlugins, runPluginCleanup, runPluginSetup, STATIC_GLOBAL_OPTION_SOURCE, topologicalSort, validateOptionCollisions, validateOptionNames, } from './plugin.js';
+import { watchForStop } from './stop.js';
+import { findSuggestion } from './suggest.js';
+import { sendToolReport, takeToolRequest, } from './tool-channel.js';
+/** Routing stopped before a command: `path` is how far it got. */
+class RouteNotFoundError extends CommandNotFoundError {
+    path;
+    isIncomplete;
+    constructor(name, suggestion, path, 
+    /** Nothing was wrong, only unfinished: argv ended before reaching a command */
+    isIncomplete) {
+        super(name, suggestion);
+        this.path = path;
+        this.isIncomplete = isIncomplete;
+    }
+}
 /**
  * Check if a value is a Command (branded object).
  */
 function isCommand(value) {
     return '_type' in value && value._type === 'runa:command';
 }
-/**
- * Levenshtein distance for "did you mean" suggestions.
- */
-function levenshtein(a, b) {
-    const rows = b.length + 1;
-    const cols = a.length + 1;
-    // Use a flat array for guaranteed index access without non-null assertions
-    const matrix = new Array(rows * cols).fill(0);
-    const at = (i, j) => matrix[i * cols + j] ?? 0;
-    const set = (i, j, v) => {
-        matrix[i * cols + j] = v;
-    };
-    for (let i = 0; i < rows; i++)
-        set(i, 0, i);
-    for (let j = 0; j < cols; j++)
-        set(0, j, j);
-    for (let i = 1; i < rows; i++) {
-        for (let j = 1; j < cols; j++) {
-            if (b[i - 1] === a[j - 1]) {
-                set(i, j, at(i - 1, j - 1));
-            }
-            else {
-                set(i, j, Math.min(at(i - 1, j - 1) + 1, // substitution
-                at(i, j - 1) + 1, // insertion
-                at(i - 1, j) + 1));
-            }
-        }
-    }
-    return at(b.length, a.length);
-}
-/**
- * Find the best suggestion for a misspelled command name.
- * Returns undefined if no close match exists (distance > 3).
- */
-function findSuggestion(input, candidates) {
-    let best;
-    let bestDist = Infinity;
-    for (const candidate of candidates) {
-        const dist = levenshtein(input, candidate);
-        if (dist < bestDist) {
-            bestDist = dist;
-            best = candidate;
-        }
-    }
-    // Only suggest if reasonably close
-    return bestDist <= 3 ? best : undefined;
-}
 /**
  * Resolve a command from the command tree by walking argv tokens.
  * Supports nested subcommands.
@@ -93,21 +65,35 @@ function resolveCommand(commands, tokens) {
         if (isCommand(entry)) {
             return {
                 command: entry,
+                path: tokens.slice(0, consumed),
                 remainingArgv: tokens.slice(consumed),
             };
         }
         // It's a subtree — continue walking
         current = entry;
     }
-    // If we're in a subtree and haven't found a command, check for a default/index command
-    // For now, throw CommandNotFoundError
-    const commandName = tokens[consumed] ?? tokens[consumed - 1] ?? '';
-    const candidates = Object.keys(current);
-    const suggestion = commandName ? findSuggestion(commandName, candidates) : undefined;
-    if (!commandName && consumed === 0) {
-        throw new CommandNotFoundError('(no command specified)', undefined);
+    const path = tokens.slice(0, consumed);
+    const next = tokens[consumed];
+    if (next === undefined) {
+        throw new RouteNotFoundError(path.join(' ') || '(no command specified)', undefined, path, true);
     }
-    throw new CommandNotFoundError(tokens.slice(0, consumed + 1).join(' '), suggestion);
+    const suggestion = findSuggestion(next, Object.keys(current));
+    throw new RouteNotFoundError([...path, next].join(' '), suggestion, path, false);
+}
+// ─── Output Validation ──────────────────────────────────────
+/** A command returning the wrong shape is an author defect, reported by field. */
+const INVALID_OUTPUT = 'INVALID_OUTPUT';
+function assertValidOutput(command, output, result) {
+    const parsed = output.safeParse(result);
+    if (parsed.success)
+        return;
+    const issues = parsed.error.issues.map((issue) => `  ${issue.path.join('.') || '(root)'}: ${issue.message}`);
+    throw new RunaError(`Command '${command.meta.name}' returned invalid output:\n${issues.join('\n')}`, { code: INVALID_OUTPUT, exitCode: 1 });
+}
+function toolFailureReason(error) {
+    if (isUsageError(error))
+        return 'input';
+    return error instanceof RunaError && error.code === INVALID_OUTPUT ? 'output' : 'other';
 }
 // ─── Middleware Composition ─────────────────────────────────
 /**
@@ -135,11 +121,157 @@ function composeMiddleware(middlewareList, globalOptions, innerFn) {
     }
     return chain;
 }
-// ─── CLI Execution Engine ───────────────────────────────────
+function loadConfigValues(config) {
+    return config.config ? loadAndMergeConfig(config.config) : Promise.resolve(undefined);
+}
+function reportDeprecations(input) {
+    for (const warning of deprecationWarnings(input)) {
+        console.error(warning);
+    }
+}
+/** The exit code of a usage error (ADR-0009). */
+const USAGE_EXIT_CODE = 2;
+/** What core answers by itself, instead of running a command. */
+function findBuiltInAnswer(config, route, argv) {
+    const isFree = (token) => argv.includes(token) && !(route.command && commandClaims(route.command, token));
+    if (config.meta.version !== undefined && isFree('--version'))
+        return 'version';
+    if (HELP_TOKENS.some(isFree))
+        return 'help';
+    return route.isIncomplete ? 'usage' : undefined;
+}
+/** Select from argv. Undefined means the run ended here, as with --version. */
+async function selectFromArgv(scope, rest, rootName) {
+    const { config, commands, globalOptions, globalMeta, hookCtx, help } = scope;
+    const commandArgv = hookCtx.rawArgs;
+    // ─── Built-in --version and --help (ADR-0021) ─────
+    // Globals were extracted above, so an option of the CLI never gets here.
+    const route = findRoute(commands, commandArgv, rootName);
+    const answer = findBuiltInAnswer(config, route, commandArgv);
+    if (answer === 'version') {
+        console.log(config.meta.version);
+        return undefined;
+    }
+    if (answer) {
+        // Asking for help is a success. Reaching it with nothing to run is a usage
+        // error: stdout stays clean, and a script with an empty command fails.
+        const output = answer === 'help' ? process.stdout : process.stderr;
+        const target = findHelpTarget(scope.schema(), route.path);
+        if (help.show)
+            await help.show(target, output);
+        else
+            output.write(`${renderHelp(target)}\n`);
+        if (answer === 'usage')
+            scope.exitWith(USAGE_EXIT_CODE);
+        return undefined;
+    }
+    // ─── Resolve command ──────────────────────────────
+    const { command, remainingArgv } = resolveCommandFromTree(commands, commandArgv, rootName);
+    hookCtx.command = command.meta;
+    // ─── Parse command args + options ──────────────────
+    const optionMetadata = command.options ? walkSchema(command.options) : [];
+    const commandOptionMeta = command.meta.options;
+    const { parseArgsConfig, longAliasMap, knownKeys, booleanKeys } = buildParseArgsConfig(optionMetadata, commandOptionMeta, true);
+    const cmdParseResult = parseArgs({
+        ...parseArgsConfig,
+        args: remainingArgv,
+        tokens: true,
+    });
+    const commandValues = cmdParseResult.values;
+    // ─── Strict options check ─────────────────────────
+    if (config.strictOptions !== false) {
+        // Command canonical names + long aliases (= keys of the parseArgs config)
+        const suggestionCandidates = Object.keys(parseArgsConfig.options ?? {});
+        // Globals are extracted before command parsing, but their names must
+        // still be known here: parseArgs maps a stray global short flag to its
+        // bare character, and typo'd globals should suggest the global name.
+        for (const name of Object.keys(globalOptions)) {
+            knownKeys.add(flagName(name));
+            suggestionCandidates.push(flagName(name));
+            for (const alias of globalMeta.options[name]?.alias ?? []) {
+                if (alias.startsWith('--')) {
+                    knownKeys.add(alias.slice(2));
+                    suggestionCandidates.push(alias.slice(2));
+                }
+                else if (alias.startsWith('-') && alias.length === 2) {
+                    knownKeys.add(alias.slice(1));
+                }
+            }
+        }
+        assertKnownOptions({
+            producedKeys: Object.keys(commandValues),
+            knownKeys,
+            booleanKeys,
+            suggestionCandidates,
+        });
+    }
+    assertOptionValues({
+        tokens: cmdParseResult.tokens,
+        options: parseArgsConfig.options ?? {},
+        longAliasMap,
+        optionMeta: commandOptionMeta,
+    });
+    const configValues = await loadConfigValues(config);
+    const operands = distributeRest(cmdParseResult.positionals, rest, command.args ?? {});
+    const { parsedArgs, parsedOptions } = resolveValues({
+        parseArgsResult: {
+            values: commandValues,
+            positionals: operands.positionals,
+        },
+        longAliasMap,
+        schemas: {
+            args: command.args,
+            options: command.options,
+        },
+        meta: { options: commandOptionMeta },
+        configValues,
+    });
+    reportDeprecations({
+        provided: Object.keys(commandValues),
+        longAliasMap,
+        optionMeta: commandOptionMeta,
+        configValues,
+    });
+    return { command, parsedArgs, parsedOptions, rest: operands.rest };
+}
+function commandAtPath(commands, path) {
+    const notFound = new CommandNotFoundError(path.join(' '));
+    let current = commands;
+    for (const segment of path) {
+        if (isCommand(current) || !Object.hasOwn(current, segment))
+            throw notFound;
+        current = current[segment];
+    }
+    if (!isCommand(current))
+        throw notFound;
+    return current;
+}
+/** Select from a tool call: the path names the command, the input carries its values. */
+async function selectFromInput(scope, call) {
+    const { config, commands, hookCtx } = scope;
+    const command = commandAtPath(commands, call.path);
+    hookCtx.command = command.meta;
+    const commandOptionMeta = command.meta.options;
+    const configValues = await loadConfigValues(config);
+    const { parsedArgs, parsedOptions } = resolveToolInput({
+        input: call.input,
+        schemas: { args: command.args, options: command.options },
+        meta: { options: commandOptionMeta },
+        configValues,
+    });
+    reportDeprecations({
+        provided: Object.keys(call.input),
+        longAliasMap: {},
+        optionMeta: commandOptionMeta,
+        configValues,
+    });
+    return { command, parsedArgs, parsedOptions, rest: [] };
+}
 /**
- * Run the full CLI lifecycle.
+ * Run the full CLI lifecycle. Only selecting the command and its values depends
+ * on the entry point: everything else is what any run goes through.
  */
-async function runCLILifecycle(config, argv) {
+async function runCLILifecycle(config, argv, { rootName, toolCall, report } = {}) {
     // ─── State ─────────────────────────────────────────
     const hookRegistry = createHookRegistry();
     const mutableCommands = { ...config.commands };
@@ -149,12 +281,27 @@ async function runCLILifecycle(config, argv) {
     };
     const mutableMiddleware = [...(config.middleware ?? [])];
     let sortedPlugins = [];
+    // Registrant per global option name (ADR-0014): statically-declared
+    // globals are seeded here; plugin registrations append via addGlobalOption.
+    const globalOptionSources = new Map();
+    for (const name of Object.keys(mutableGlobalOptions)) {
+        globalOptionSources.set(name, [STATIC_GLOBAL_OPTION_SOURCE]);
+    }
+    const help = {};
+    const currentSchema = () => ({
+        ...getSchema({ ...config, commands: mutableCommands }, mutableGlobalOptions, mutableGlobalMeta.options),
+        root: rootName,
+    });
+    const stop = watchForStop(report !== undefined);
     // Hook context that grows as we progress through the lifecycle
     const hookCtx = {
         cli: config.meta,
+        invocation: toolCall ? { surface: 'tool', tool: toolCall.path.join('_') } : { surface: 'cli' },
         rawArgs: argv,
+        signal: stop.signal,
     };
     let lifecycleError;
+    let failureExitCode;
     let commandResult;
     try {
         // ─── Plugin resolution ────────────────────────────
@@ -168,14 +315,34 @@ async function runCLILifecycle(config, argv) {
                 globalMeta: mutableGlobalMeta,
                 middleware: mutableMiddleware,
                 hookRegister: (name, handler) => hookRegistry.register(name, handler),
-                getSchema: () => getSchema({ ...config, commands: mutableCommands }, mutableGlobalOptions, mutableGlobalMeta.options),
+                getSchema: currentSchema,
+                getConfigValues: () => loadConfigValues(config),
+                help,
+                globalOptionSources,
             };
             await runPluginSetup(sortedPlugins, pluginRefs);
         }
+        // ─── Option collision validation (ADR-0014) ─────
+        // Post-plugin-setup is the earliest point where the full option
+        // surface (plugin globals + plugin commands) exists. Runs before
+        // any parsing on every invocation; throws RunaError OPTION_COLLISION.
+        validateOptionNames(mutableCommands, mutableGlobalOptions);
+        validateOptionCollisions(mutableCommands, mutableGlobalOptions, mutableGlobalMeta, globalOptionSources);
         // ─── beforeParse ──────────────────────────────────
         await hookRegistry.emit('beforeParse', hookCtx);
         // Handlers may have mutated hookCtx.rawArgs
         const currentArgv = hookCtx.rawArgs;
+        // ─── Rest split (ADR-0012) ────────────────────────
+        // Split at the FIRST `--`: `head` flows through the entire pipeline
+        // (global extraction → resolution → parseArgs → strict check), `rest`
+        // bypasses everything and lands verbatim on the run context. Because
+        // the global extractor below only ever sees `head`, a token like
+        // `--help` after `--` can never be stolen as a global flag.
+        // Only the first `--` splits; later `--` tokens are ordinary rest content.
+        const sepIdx = currentArgv.indexOf('--');
+        const head = sepIdx === -1 ? currentArgv : currentArgv.slice(0, sepIdx);
+        const rest = sepIdx === -1 ? [] : currentArgv.slice(sepIdx + 1);
+        hookCtx.rawArgs = head;
         // ─── Parse global options ─────────────────────────
         let parsedGlobalOptions = {};
         if (Object.keys(mutableGlobalOptions).length > 0) {
@@ -205,12 +372,13 @@ async function runCLILifecycle(config, argv) {
             for (const [alias, canonical] of Object.entries(longAliasMap)) {
                 longNames.set(`--${alias}`, canonical);
             }
-            // Manual argv split: extract global option tokens, leave the rest
+            // Manual argv split: extract global option tokens, leave the rest.
+            // Operates on `head` only — post-`--` tokens are never candidates.
             const globalArgv = [];
             const commandArgv = [];
             let i = 0;
-            while (i < currentArgv.length) {
-                const token = currentArgv[i] ?? '';
+            while (i < head.length) {
+                const token = head[i] ?? '';
                 // Handle --opt=val form
                 const eqIdx = token.indexOf('=');
                 const tokenKey = eqIdx > 0 ? token.slice(0, eqIdx) : token;
@@ -231,8 +399,8 @@ async function runCLILifecycle(config, argv) {
                         // --opt val — string option, extract both tokens
                         globalArgv.push(token);
                         i++;
-                        if (i < currentArgv.length) {
-                            globalArgv.push(currentArgv[i] ?? '');
+                        if (i < head.length) {
+                            globalArgv.push(head[i] ?? '');
                             i++;
                         }
                     }
@@ -246,17 +414,35 @@ async function runCLILifecycle(config, argv) {
             const globalParseResult = parseArgs({
                 ...parseArgsConfig,
                 args: globalArgv,
+                tokens: true,
             });
-            const { parsedOptions } = resolveValues({
-                parseArgsResult: {
-                    values: globalParseResult.values,
-                    positionals: [],
-                },
+            const globalValues = globalParseResult.values;
+            assertOptionValues({
+                tokens: globalParseResult.tokens,
+                options: registeredOptions,
                 longAliasMap,
-                schemas: { options: mutableGlobalOptions },
-                meta: { options: mutableGlobalMeta.options },
+                optionMeta: mutableGlobalMeta.options,
+            });
+            // Asking how to use a CLI can't require already knowing its options.
+            const answer = findBuiltInAnswer(config, findRoute(mutableCommands, commandArgv, rootName), commandArgv);
+            try {
+                parsedGlobalOptions = resolveValues({
+                    parseArgsResult: { values: globalValues, positionals: [] },
+                    longAliasMap,
+                    schemas: { options: mutableGlobalOptions },
+                    meta: { options: mutableGlobalMeta.options },
+                }).parsedOptions;
+            }
+            catch (err) {
+                const isQuestion = answer === 'help' || answer === 'version';
+                if (!isQuestion || !(err instanceof ValidationError))
+                    throw err;
+            }
+            reportDeprecations({
+                provided: Object.keys(globalValues),
+                longAliasMap,
+                optionMeta: mutableGlobalMeta.options,
             });
-            parsedGlobalOptions = parsedOptions;
             // Pass remaining argv (command tokens only) to command parsing
             hookCtx.rawArgs = commandArgv;
         }
@@ -267,35 +453,25 @@ async function runCLILifecycle(config, argv) {
             // Short-circuit: skip command resolution and execution, go to cleanup
             return;
         }
-        // ─── Resolve command ──────────────────────────────
-        const commandArgv = hookCtx.rawArgs;
-        const { command, remainingArgv } = resolveCommandFromTree(mutableCommands, commandArgv, config);
-        hookCtx.command = command.meta;
-        // ─── Parse command args + options ──────────────────
-        const optionMetadata = command.options ? walkSchema(command.options) : [];
-        const { parseArgsConfig, longAliasMap } = buildParseArgsConfig(optionMetadata, command.meta.options, !!command.args);
-        const cmdParseResult = parseArgs({
-            ...parseArgsConfig,
-            args: remainingArgv,
-        });
-        // Load config values if configured
-        let configValues;
-        if (config.config) {
-            configValues = await loadAndMergeConfig(config.config);
-        }
-        const { parsedArgs, parsedOptions } = resolveValues({
-            parseArgsResult: {
-                values: cmdParseResult.values,
-                positionals: cmdParseResult.positionals,
+        // ─── Select the command and its values ────────────
+        const scope = {
+            config,
+            commands: mutableCommands,
+            globalOptions: mutableGlobalOptions,
+            globalMeta: mutableGlobalMeta,
+            hookCtx,
+            help,
+            schema: currentSchema,
+            exitWith: (code) => {
+                failureExitCode = code;
             },
-            longAliasMap,
-            schemas: {
-                args: command.args,
-                options: command.options,
-            },
-            meta: { options: command.meta.options },
-            configValues,
-        });
+        };
+        const selection = toolCall
+            ? await selectFromInput(scope, toolCall)
+            : await selectFromArgv(scope, rest, rootName);
+        if (!selection)
+            return;
+        const { command, parsedArgs, parsedOptions } = selection;
         hookCtx.args = parsedArgs;
         hookCtx.options = parsedOptions;
         // ─── afterParse ───────────────────────────────────
@@ -309,43 +485,59 @@ async function runCLILifecycle(config, argv) {
             globalOptions: parsedGlobalOptions,
             command: command.meta,
             rawArgs: argv,
+            rest: selection.rest,
+            signal: stop.signal,
         };
         const innerFn = async () => {
+            report?.({ kind: 'running' });
             commandResult = await command.run(runContext);
+            report?.({ kind: 'ran' });
             // Validate output schema if present
             if (command.output) {
-                command.output.parse(commandResult);
+                assertValidOutput(command, command.output, commandResult);
             }
+            report?.({ kind: 'result', value: commandResult });
         };
         const chain = composeMiddleware(mutableMiddleware, parsedGlobalOptions, innerFn);
-        await chain();
+        await stop.guard(chain);
         // ─── afterRun ─────────────────────────────────────
         await hookRegistry.emit('afterRun', hookCtx);
     }
     catch (err) {
-        lifecycleError = err instanceof Error ? err : new Error(String(err));
+        lifecycleError = err instanceof Error ? err : new Error(err == null ? '' : String(err));
         // ─── onError ──────────────────────────────────────
         hookCtx.error = lifecycleError;
         try {
             await hookRegistry.emit('onError', hookCtx);
         }
-        catch {
-            // onError handler threw — swallow it, cleanup still needs to run
+        catch (hookErr) {
+            // ADR-0009: log to stderr, never rethrow — a broken error handler must
+            // not prevent cleanup, but its own defect must not vanish either.
+            // The ORIGINAL error still drives exit behavior below.
+            console.error('runa: onError handler threw:', hookErr);
         }
-        // If error was not handled, fall back to default behavior
+        failureExitCode = lifecycleError instanceof RunaError ? lifecycleError.exitCode : 1;
+        // Report BEFORE cleanup: the reason stays visible even if cleanup hangs.
+        // `handled` means the plugin owns the output, not that the run succeeded.
         if (!hookCtx.handled) {
-            const exitCode = lifecycleError instanceof RunaError ? lifecycleError.exitCode : 1;
-            console.error(lifecycleError.message);
-            process.exit(exitCode);
+            const subject = hookCtx.command?.name ?? config.meta.name;
+            const debug = isDebugEnabled();
+            // An agent cannot use a hint for people, unless the operator asked for details.
+            const helpCommand = report ? undefined : config.meta.name;
+            console.error(report && !debug
+                ? failureReason(lifecycleError, subject)
+                : describeFailure(lifecycleError, subject, debug, helpCommand));
         }
+        report?.({ kind: 'failed', reason: toolFailureReason(lifecycleError) });
     }
     finally {
         // ─── cleanup (ALWAYS runs) ────────────────────────
         try {
             await hookRegistry.emit('cleanup', hookCtx);
         }
-        catch {
-            // Cleanup hook errors are swallowed
+        catch (hookErr) {
+            // ADR-0009: same treatment as onError — log the defect, keep cleaning up.
+            console.error('runa: cleanup hook threw:', hookErr);
         }
         // Plugin cleanup in reverse topological order
         if (sortedPlugins.length > 0) {
@@ -356,34 +548,72 @@ async function runCLILifecycle(config, argv) {
                 }
             }
         }
+        stop.finish();
+        // Exit only after cleanup: process.exit inside catch would skip the rest of
+        // this block. It can't go after it either: a return in the try never gets there.
+        const exitCode = stop.exitCode ?? failureExitCode;
+        if (exitCode !== undefined) {
+            if (hookCtx.handled) {
+                // A plugin that truly recovered keeps control by setting process.exitCode.
+                process.exitCode ??= exitCode;
+            }
+            else {
+                process.exit(exitCode);
+            }
+        }
     }
 }
 /**
- * Resolve command with single-command mode support.
- * If there's exactly one command, route directly without requiring
- * the command name in argv.
+ * Route argv to a command.
+ *
+ * Root mode (runCLI): the root command takes everything and consumes nothing,
+ * so a value equal to its name is data. Only another command's name routes
+ * away from it, and `--` passes even that as data (ADR-0023).
  */
-function resolveCommandFromTree(commands, argv, _config) {
-    const commandEntries = Object.entries(commands);
-    // Single-command mode: if exactly one command and first token doesn't match it,
-    // route directly to that command
-    if (commandEntries.length === 1) {
-        const firstEntry = commandEntries[0];
-        if (firstEntry) {
-            const [name, entry] = firstEntry;
-            if (isCommand(entry)) {
-                // If argv is empty or first token doesn't match the command name
-                if (argv.length === 0 || argv[0] !== name) {
-                    return { command: entry, remainingArgv: argv };
-                }
-                // First token matches — consume it
-                return { command: entry, remainingArgv: argv.slice(1) };
-            }
+function resolveCommandFromTree(commands, argv, rootName) {
+    if (rootName !== undefined) {
+        const root = commands[rootName];
+        const first = argv[0] ?? '';
+        const isSubcommand = first !== rootName && Object.hasOwn(commands, first);
+        if (root && isCommand(root) && !isSubcommand) {
+            return { command: root, path: [rootName], remainingArgv: argv };
         }
+        return resolveCommand(commands, argv);
+    }
+    // Implicit single-command mode, retired before 1.0: it depends on counting
+    // commands, so a plugin that adds one silently turns it off.
+    const entries = Object.entries(commands);
+    const [name, entry] = entries[0] ?? [];
+    if (entries.length === 1 && entry && isCommand(entry)) {
+        const path = [name];
+        if (argv[0] === name)
+            return { command: entry, path, remainingArgv: argv.slice(1) };
+        warnImplicitMode();
+        return { command: entry, path, remainingArgv: argv };
     }
-    // Multi-command mode: resolve from tree
     return resolveCommand(commands, argv);
 }
+let warnedImplicitMode = false;
+function warnImplicitMode() {
+    if (warnedImplicitMode)
+        return;
+    warnedImplicitMode = true;
+    process.emitWarning('defineCLI() with a single command is deprecated. Use runCLI().', {
+        type: 'DeprecationWarning',
+        code: 'RUNA_IMPLICIT_SINGLE_COMMAND',
+    });
+}
+function findRoute(commands, argv, rootName) {
+    try {
+        const { command, path } = resolveCommandFromTree(commands, argv, rootName);
+        return { command, path, isIncomplete: false };
+    }
+    catch (err) {
+        if (!(err instanceof RouteNotFoundError))
+            throw err;
+        return { path: err.path, isIncomplete: err.isIncomplete };
+    }
+}
 // ─── Public API ─────────────────────────────────────────────
 /**
  * Create a CLI from a configuration.
@@ -394,20 +624,39 @@ export function defineCLI(config) {
         _type: 'runa:cli',
         config,
         async run(argv) {
-            const effectiveArgv = argv ?? process.argv.slice(2);
-            await runCLILifecycle(config, effectiveArgv);
+            await enter(config, argv ?? process.argv.slice(2));
         },
     };
 }
 /**
- * Single-command shorthand.
- * Wraps a command in defineCLI() and runs it.
+ * Run a CLI made of one command. Accepts everything defineCLI() does except
+ * meta and commands, which come from the command: plugins, middleware, config.
  */
-export async function runCLI(command, argv) {
-    const cli = defineCLI({
-        meta: { name: command.meta.name, description: command.meta.description },
-        commands: { [command.meta.name]: command },
+export async function runCLI(command, options = {}) {
+    const { argv = process.argv.slice(2), ...config } = options;
+    const { name, version, description } = command.meta;
+    await enter({ ...config, meta: { name, version, description }, commands: { [name]: command } }, argv, name);
+}
+/** Every CLI starts here: as itself, or as a tool if an MCP server launched it. */
+async function enter(config, argv, rootName) {
+    const request = takeToolRequest();
+    if (request?.kind === 'ping') {
+        sendToolReport({ kind: 'pong' });
+        return;
+    }
+    await runCLILifecycle(config, argv, {
+        rootName,
+        toolCall: request,
+        report: request && ((report) => sendToolReport(report, request.maxResultBytes)),
     });
-    await cli.run(argv);
+}
+/**
+ * Run a command from an object, through the same lifecycle as a CLI run.
+ * Internal, for @runa-cmd/mcp: not exported from the package barrel.
+ *
+ * @param options.argv - Startup arguments, read for global options only
+ */
+export async function runToolCall(config, call, options = {}) {
+    await runCLILifecycle(config, options.argv ?? [], { rootName: options.rootName, toolCall: call });
 }
 //# sourceMappingURL=cli.js.map