@runa-cmd/core 0.2.0-beta.2 → 0.2.0-beta.3

package/dist/cli.js

@@ -11,8 +11,10 @@
  * - Error handling
  */
 import { parseArgs } from 'node:util';
-import { loadAndMergeConfig } from './config/merge.js';
-import { CommandNotFoundError, describeFailure, failureReason, isDebugEnabled, isUsageError, RunaError, ValidationError, } from './errors.js';
+import { JSON_OPTION, JSON_SCHEMA } from './command.js';
+import { loadConfigFile } from './config/merge.js';
+import { assertConfigNames, assertValidConfig, commandValues, } from './config/scope.js';
+import { CommandNotFoundError, describeFailure, failureReason, isDebugEnabled, isUsageError, ProcessExit, 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';
@@ -22,20 +24,25 @@ import { buildParseArgsConfig } from './parse/parseargs-bridge.js';
 import { distributeRest, resolveToolInput, resolveValues } from './parse/resolve.js';
 import { walkSchema } from './parse/schema-walker.js';
 import { assertKnownOptions, assertOptionValues } from './parse/strict.js';
-import { resolvePlugins, runPluginCleanup, runPluginSetup, STATIC_GLOBAL_OPTION_SOURCE, topologicalSort, validateOptionCollisions, validateOptionNames, } from './plugin.js';
+import { resolvePlugins, runPluginCleanup, runPluginSetup, STATIC_GLOBAL_OPTION_SOURCE, topologicalSort, validateCommandNames, validateOptionCollisions, validateOptionNames, } from './plugin.js';
 import { watchForStop } from './stop.js';
 import { findSuggestion } from './suggest.js';
 import { sendToolReport, takeToolRequest, } from './tool-channel.js';
+import { debugLine, optionEvents } from './trace.js';
 /** Routing stopped before a command: `path` is how far it got. */
 class RouteNotFoundError extends CommandNotFoundError {
     path;
     isIncomplete;
+    flag;
     constructor(name, suggestion, path, 
     /** Nothing was wrong, only unfinished: argv ended before reaching a command */
-    isIncomplete) {
+    isIncomplete, 
+    /** What stopped the route, if it was a flag and not a mistyped command */
+    flag) {
         super(name, suggestion);
         this.path = path;
         this.isIncomplete = isIncomplete;
+        this.flag = flag;
     }
 }
 /**
@@ -77,18 +84,50 @@ function resolveCommand(commands, tokens) {
     if (next === undefined) {
         throw new RouteNotFoundError(path.join(' ') || '(no command specified)', undefined, path, true);
     }
+    // A lone `-` means stdin in many CLIs: it isn't a flag, whatever it is here
+    const flag = next.length > 1 && next.startsWith('-') ? next : undefined;
     const suggestion = findSuggestion(next, Object.keys(current));
-    throw new RouteNotFoundError([...path, next].join(' '), suggestion, path, false);
+    throw new RouteNotFoundError([...path, next].join(' '), suggestion, path, false, flag);
 }
 // ─── 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) {
+/** The key names a command, so that's its name once a run reaches it (ADR-0043). */
+function namedMeta(command, path) {
+    return { ...command.meta, name: path.at(-1) };
+}
+function assertValidOutput(name, 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 });
+    throw new RunaError(`Command '${name}' returned invalid output:\n${issues.join('\n')}`, {
+        code: INVALID_OUTPUT,
+        exitCode: 1,
+    });
+}
+const asJsonText = (value) => JSON.stringify(value, null, 2);
+/** What a person sees of a result (ADR-0042). */
+function resultText(name, command, result, asJson) {
+    if (result === undefined) {
+        if (!command.format)
+            return undefined;
+        throw new RunaError(`Command '${name}' declares format but returned nothing.`, {
+            code: 'MISSING_RESULT',
+            exitCode: 1,
+        });
+    }
+    if (asJson)
+        return asJsonText(result);
+    if (command.format)
+        return command.format(result);
+    return typeof result === 'string' ? result : asJsonText(result);
+}
+function printResult(name, command, result, asJson) {
+    const text = resultText(name, command, result, asJson);
+    if (text === undefined)
+        return;
+    process.stdout.write(text.endsWith('\n') ? text : `${text}\n`);
 }
 function toolFailureReason(error) {
     if (isUsageError(error))
@@ -121,9 +160,6 @@ function composeMiddleware(middlewareList, globalOptions, innerFn) {
     }
     return chain;
 }
-function loadConfigValues(config) {
-    return config.config ? loadAndMergeConfig(config.config) : Promise.resolve(undefined);
-}
 function reportDeprecations(input) {
     for (const warning of deprecationWarnings(input)) {
         console.error(warning);
@@ -140,6 +176,27 @@ function findBuiltInAnswer(config, route, argv) {
         return 'help';
     return route.isIncomplete ? 'usage' : undefined;
 }
+/** Report a flag before any command: same message as one after it, same exit code. */
+function assertKnownFlag(token, { config, globalOptions, globalMeta }) {
+    const rawName = token.split('=')[0];
+    const name = rawName.replace(/^-+/, '');
+    const longAliases = Object.values(globalMeta.options)
+        .flatMap((meta) => meta.alias ?? [])
+        .filter((alias) => alias.startsWith('--'))
+        .map((alias) => alias.slice(2));
+    assertKnownOptions({
+        producedKeys: [name],
+        knownKeys: new Set(),
+        booleanKeys: new Set(),
+        suggestionCandidates: [
+            'help',
+            ...(config.meta.version === undefined ? [] : ['version']),
+            ...Object.keys(globalOptions).map(flagName),
+            ...longAliases,
+        ],
+        tokens: [{ kind: 'option', name, rawName }],
+    });
+}
 /** 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;
@@ -165,11 +222,19 @@ async function selectFromArgv(scope, rest, rootName) {
             scope.exitWith(USAGE_EXIT_CODE);
         return undefined;
     }
+    // Globals were taken out already, so a flag here belongs to nobody
+    if (route.flag)
+        assertKnownFlag(route.flag, scope);
     // ─── Resolve command ──────────────────────────────
-    const { command, remainingArgv } = resolveCommandFromTree(commands, commandArgv, rootName);
-    hookCtx.command = command.meta;
+    const { command, path, remainingArgv } = resolveCommandFromTree(commands, commandArgv, rootName);
+    hookCtx.command = namedMeta(command, path);
     // ─── Parse command args + options ──────────────────
-    const optionMetadata = command.options ? walkSchema(command.options) : [];
+    // --json stays out of command.options: it's for the terminal, not for run()
+    // or a tool.
+    const optionMetadata = [
+        ...walkSchema(command.options ?? {}),
+        ...(command.format ? walkSchema({ [JSON_OPTION]: JSON_SCHEMA }) : []),
+    ];
     const commandOptionMeta = command.meta.options;
     const { parseArgsConfig, longAliasMap, knownKeys, booleanKeys } = buildParseArgsConfig(optionMetadata, commandOptionMeta, true);
     const cmdParseResult = parseArgs({
@@ -216,11 +281,15 @@ async function selectFromArgv(scope, rest, rootName) {
         longAliasMap,
         optionMeta: commandOptionMeta,
     });
-    const configValues = await loadConfigValues(config);
+    const asJson = command.format !== undefined && commandValues[JSON_OPTION] === true;
+    if (command.format)
+        delete commandValues[JSON_OPTION];
+    const { configValues, configSource } = await scope.loadConfig(path);
     const operands = distributeRest(cmdParseResult.positionals, rest, command.args ?? {});
     // Nothing reads what's left unless the command asked for it, so it can't stay
     // silent: as positionals, it gets the same error as any other extra (ADR-0036).
-    const { parsedArgs, parsedOptions } = resolveValues({
+    const { parsedArgs, parsedOptions, optionSources } = resolveValues({
+        env: scope.env,
         parseArgsResult: {
             values: commandValues,
             positionals: command.rest
@@ -234,14 +303,16 @@ async function selectFromArgv(scope, rest, rootName) {
         },
         meta: { options: commandOptionMeta },
         configValues,
+        configSource,
     });
     reportDeprecations({
         provided: Object.keys(commandValues),
         longAliasMap,
         optionMeta: commandOptionMeta,
         configValues,
+        env: scope.env,
     });
-    return { command, parsedArgs, parsedOptions, rest: operands.rest };
+    return { command, path, parsedArgs, parsedOptions, optionSources, rest: operands.rest, asJson };
 }
 function commandAtPath(commands, path) {
     const notFound = new CommandNotFoundError(path.join(' '));
@@ -257,30 +328,41 @@ function commandAtPath(commands, path) {
 }
 /** 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 { commands, hookCtx } = scope;
     const command = commandAtPath(commands, call.path);
-    hookCtx.command = command.meta;
+    hookCtx.command = namedMeta(command, call.path);
     const commandOptionMeta = command.meta.options;
-    const configValues = await loadConfigValues(config);
-    const { parsedArgs, parsedOptions } = resolveToolInput({
+    const { configValues, configSource } = await scope.loadConfig(call.path);
+    const { parsedArgs, parsedOptions, optionSources } = resolveToolInput({
+        env: scope.env,
         input: call.input,
         schemas: { args: command.args, options: command.options },
         meta: { options: commandOptionMeta },
         configValues,
+        configSource,
     });
     reportDeprecations({
         provided: Object.keys(call.input),
         longAliasMap: {},
         optionMeta: commandOptionMeta,
         configValues,
+        env: scope.env,
     });
-    return { command, parsedArgs, parsedOptions, rest: [] };
+    return {
+        command,
+        path: call.path,
+        parsedArgs,
+        parsedOptions,
+        optionSources,
+        rest: [],
+        asJson: false,
+    };
 }
 /**
  * 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, { rootName, toolCall, report } = {}) {
+async function runCLILifecycle(config, argv, { rootName, toolCall, report, harness } = {}) {
     // ─── State ─────────────────────────────────────────
     const hookRegistry = createHookRegistry();
     const mutableCommands = { ...config.commands };
@@ -301,7 +383,15 @@ async function runCLILifecycle(config, argv, { rootName, toolCall, report } = {}
         ...getSchema({ ...config, commands: mutableCommands }, mutableGlobalOptions, mutableGlobalMeta.options),
         root: rootName,
     });
-    const stop = watchForStop(report !== undefined);
+    const stop = watchForStop(report !== undefined, harness === undefined);
+    const env = harness?.env ?? process.env;
+    const debug = isDebugEnabled(env);
+    const trace = (event) => {
+        harness?.trace(event);
+        const line = debug ? debugLine(event) : undefined;
+        if (line)
+            console.error(line);
+    };
     // Hook context that grows as we progress through the lifecycle
     const hookCtx = {
         cli: config.meta,
@@ -312,6 +402,81 @@ async function runCLILifecycle(config, argv, { rootName, toolCall, report } = {}
     let lifecycleError;
     let failureExitCode;
     let commandResult;
+    let leftByExit = false;
+    const finishRun = async () => {
+        // ─── cleanup (ALWAYS runs) ────────────────────────
+        try {
+            await emitHook('cleanup');
+        }
+        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) {
+            const cleanupErrors = await runPluginCleanup(sortedPlugins);
+            if (cleanupErrors.length > 0) {
+                for (const err of cleanupErrors) {
+                    console.error(`Plugin cleanup error: ${err.message}`);
+                }
+            }
+        }
+        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)
+            return;
+        if (harness)
+            harness.onExit(exitCode);
+        else if (hookCtx.handled) {
+            // A plugin that truly recovered keeps control by setting process.exitCode.
+            process.exitCode ??= exitCode;
+        }
+        else {
+            process.exit(exitCode);
+        }
+    };
+    const configTarget = {
+        commands: mutableCommands,
+        globalOptions: mutableGlobalOptions,
+        globalMeta: mutableGlobalMeta,
+        rootName,
+    };
+    /** Read when a run needs it: a broken file must not get in the way of --help. */
+    const readConfigFile = async () => {
+        if (harness) {
+            const values = harness.configValues;
+            return values && { filePath: 'testCLI config', values };
+        }
+        return config.config && loadConfigFile(config.config);
+    };
+    let tracedConfig = false;
+    const loadCheckedConfig = async () => {
+        const file = await readConfigFile();
+        if (!tracedConfig && (config.config || file)) {
+            tracedConfig = true;
+            trace({ step: 'config', file: file?.filePath });
+        }
+        if (file)
+            assertValidConfig(file, configTarget);
+        return file;
+    };
+    const emitHook = async (name) => {
+        if (hookRegistry.getHandlers(name).length === 0)
+            return { shortCircuited: false };
+        const started = performance.now();
+        const result = await hookRegistry.emit(name, hookCtx);
+        trace({ step: 'hook', name, ms: Math.round(performance.now() - started) });
+        return result;
+    };
+    const loadConfig = async (path) => {
+        const file = await loadCheckedConfig();
+        if (!file)
+            return {};
+        const { values, source } = commandValues(file, path, rootName);
+        return { configValues: values, configSource: source };
+    };
     try {
         // ─── Plugin resolution ────────────────────────────
         if (config.plugins && config.plugins.length > 0) {
@@ -325,7 +490,7 @@ async function runCLILifecycle(config, argv, { rootName, toolCall, report } = {}
                 middleware: mutableMiddleware,
                 hookRegister: (name, handler) => hookRegistry.register(name, handler),
                 getSchema: currentSchema,
-                getConfigValues: () => loadConfigValues(config),
+                getConfigValues: async (path) => path ? (await loadConfig(path)).configValues : (await loadCheckedConfig())?.values,
                 help,
                 globalOptionSources,
             };
@@ -335,10 +500,13 @@ async function runCLILifecycle(config, argv, { rootName, toolCall, report } = {}
         // 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.
+        validateCommandNames(mutableCommands, rootName);
         validateOptionNames(mutableCommands, mutableGlobalOptions);
         validateOptionCollisions(mutableCommands, mutableGlobalOptions, mutableGlobalMeta, globalOptionSources);
+        if (config.config || harness?.configValues)
+            assertConfigNames(configTarget);
         // ─── beforeParse ──────────────────────────────────
-        await hookRegistry.emit('beforeParse', hookCtx);
+        await emitHook('beforeParse');
         // Handlers may have mutated hookCtx.rawArgs
         const currentArgv = hookCtx.rawArgs;
         // ─── Rest split (ADR-0012) ────────────────────────
@@ -434,13 +602,21 @@ async function runCLILifecycle(config, argv, { rootName, toolCall, report } = {}
             });
             // Asking how to use a CLI can't require already knowing its options.
             const answer = findBuiltInAnswer(config, findRoute(mutableCommands, commandArgv, rootName), commandArgv);
+            // With a tool call, the command comes from the call, not from argv.
+            const { configValues, configSource } = answer && !toolCall ? {} : await loadConfig([]);
             try {
-                parsedGlobalOptions = resolveValues({
+                const { parsedOptions, optionSources } = resolveValues({
                     parseArgsResult: { values: globalValues, positionals: [] },
                     longAliasMap,
                     schemas: { options: mutableGlobalOptions },
                     meta: { options: mutableGlobalMeta.options },
-                }).parsedOptions;
+                    configValues,
+                    configSource,
+                    env,
+                });
+                parsedGlobalOptions = parsedOptions;
+                const names = Object.keys(mutableGlobalOptions);
+                optionEvents('global', names, parsedOptions, optionSources).forEach(trace);
             }
             catch (err) {
                 const isQuestion = answer === 'help' || answer === 'version';
@@ -451,13 +627,15 @@ async function runCLILifecycle(config, argv, { rootName, toolCall, report } = {}
                 provided: Object.keys(globalValues),
                 longAliasMap,
                 optionMeta: mutableGlobalMeta.options,
+                configValues,
+                env,
             });
             // Pass remaining argv (command tokens only) to command parsing
             hookCtx.rawArgs = commandArgv;
         }
         hookCtx.globalOptions = parsedGlobalOptions;
         // ─── onGlobalFlags ────────────────────────────────
-        const globalFlagsResult = await hookRegistry.emit('onGlobalFlags', hookCtx);
+        const globalFlagsResult = await emitHook('onGlobalFlags');
         if (globalFlagsResult.shortCircuited) {
             // Short-circuit: skip command resolution and execution, go to cleanup
             return;
@@ -474,50 +652,67 @@ async function runCLILifecycle(config, argv, { rootName, toolCall, report } = {}
             exitWith: (code) => {
                 failureExitCode = code;
             },
+            loadConfig,
+            env,
         };
         const selection = toolCall
             ? await selectFromInput(scope, toolCall)
             : await selectFromArgv(scope, rest, rootName);
         if (!selection)
             return;
-        const { command, parsedArgs, parsedOptions } = selection;
+        const { command, path, parsedArgs, parsedOptions, optionSources } = selection;
+        const meta = namedMeta(command, path);
+        const optionNames = Object.keys(command.options ?? {});
+        optionEvents('command', optionNames, parsedOptions, optionSources).forEach(trace);
         hookCtx.args = parsedArgs;
         hookCtx.options = parsedOptions;
         // ─── afterParse ───────────────────────────────────
-        await hookRegistry.emit('afterParse', hookCtx);
+        await emitHook('afterParse');
         // ─── beforeRun ────────────────────────────────────
-        await hookRegistry.emit('beforeRun', hookCtx);
+        await emitHook('beforeRun');
         // ─── Middleware chain + command execution ──────────
         const runContext = {
             args: parsedArgs,
             options: parsedOptions,
             globalOptions: parsedGlobalOptions,
-            command: command.meta,
+            command: meta,
             rawArgs: argv,
             rest: selection.rest,
             signal: stop.signal,
         };
         const innerFn = async () => {
             report?.({ kind: 'running' });
+            const started = performance.now();
             commandResult = await command.run(runContext);
+            trace({ step: 'run', command: path, ms: Math.round(performance.now() - started) });
             report?.({ kind: 'ran' });
             // Validate output schema if present
             if (command.output) {
-                assertValidOutput(command, command.output, commandResult);
+                assertValidOutput(meta.name, command.output, commandResult);
             }
             report?.({ kind: 'result', value: commandResult });
+            harness?.onResult(commandResult);
+            // A tool hands the data to the server, which never runs format()
+            if (!report)
+                printResult(meta.name, command, commandResult, selection.asJson);
         };
         const chain = composeMiddleware(mutableMiddleware, parsedGlobalOptions, innerFn);
         await stop.guard(chain);
         // ─── afterRun ─────────────────────────────────────
-        await hookRegistry.emit('afterRun', hookCtx);
+        await emitHook('afterRun');
     }
     catch (err) {
+        // A real exit ends here: no onError, no cleanup, no message
+        if (err instanceof ProcessExit) {
+            leftByExit = true;
+            throw err;
+        }
         lifecycleError = err instanceof Error ? err : new Error(err == null ? '' : String(err));
+        harness?.onError(lifecycleError);
         // ─── onError ──────────────────────────────────────
         hookCtx.error = lifecycleError;
         try {
-            await hookRegistry.emit('onError', hookCtx);
+            await emitHook('onError');
         }
         catch (hookErr) {
             // ADR-0009: log to stderr, never rethrow — a broken error handler must
@@ -530,7 +725,6 @@ async function runCLILifecycle(config, argv, { rootName, toolCall, report } = {}
         // `handled` means the plugin owns the output, not that the run succeeded.
         if (!hookCtx.handled) {
             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
@@ -540,36 +734,10 @@ async function runCLILifecycle(config, argv, { rootName, toolCall, report } = {}
         report?.({ kind: 'failed', reason: toolFailureReason(lifecycleError) });
     }
     finally {
-        // ─── cleanup (ALWAYS runs) ────────────────────────
-        try {
-            await hookRegistry.emit('cleanup', hookCtx);
-        }
-        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) {
-            const cleanupErrors = await runPluginCleanup(sortedPlugins);
-            if (cleanupErrors.length > 0) {
-                for (const err of cleanupErrors) {
-                    console.error(`Plugin cleanup error: ${err.message}`);
-                }
-            }
-        }
-        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);
-            }
-        }
+        if (leftByExit)
+            stop.finish();
+        else
+            await finishRun();
     }
 }
 /**
@@ -620,7 +788,7 @@ function findRoute(commands, argv, rootName) {
     catch (err) {
         if (!(err instanceof RouteNotFoundError))
             throw err;
-        return { path: err.path, isIncomplete: err.isIncomplete };
+        return { path: err.path, isIncomplete: err.isIncomplete, flag: err.flag };
     }
 }
 // ─── Public API ─────────────────────────────────────────────
@@ -643,8 +811,18 @@ export function defineCLI(config) {
  */
 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);
+    const { name } = command.meta;
+    // A CLI of one command has no key to name it (ADR-0043)
+    if (!name) {
+        console.error('runCLI needs meta.name: it is the name of the CLI.');
+        process.exit(1);
+    }
+    await enter(rootConfig(command, name, config), argv, name);
+}
+/** What a CLI of one command is. Internal, shared with testCLI(). */
+export function rootConfig(command, name, config) {
+    const { version, description } = command.meta;
+    return { ...config, meta: { name, version, description }, commands: { [name]: command } };
 }
 /** Every CLI starts here: as itself, or as a tool if an MCP server launched it. */
 async function enter(config, argv, rootName) {
@@ -668,4 +846,11 @@ async function enter(config, argv, rootName) {
 export async function runToolCall(config, call, options = {}) {
     await runCLILifecycle(config, options.argv ?? [], { rootName: options.rootName, toolCall: call });
 }
+/**
+ * Run a CLI without ending the process.
+ * Internal, for testCLI(): not exported from the package barrel.
+ */
+export async function runWithHarness(config, argv, rootName, harness) {
+    await runCLILifecycle(config, argv, { rootName, harness });
+}
 //# sourceMappingURL=cli.js.map