incur 0.3.4 → 0.3.6

package/dist/Cli.js

@@ -1,10 +1,16 @@
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import { estimateTokenCount, sliceByTokens } from 'tokenx';
 import * as Completions from './Completions.js';
-import { IncurError, ValidationError } from './Errors.js';
+import { IncurError, ParseError, ValidationError } from './Errors.js';
 import * as Fetch from './Fetch.js';
 import * as Filter from './Filter.js';
 import * as Formatter from './Formatter.js';
 import * as Help from './Help.js';
+import { builtinCommands, shells } from './internal/command.js';
+import * as Command from './internal/command.js';
+import { isRecord } from './internal/helpers.js';
 import { detectRunner } from './internal/pm.js';
 import * as Mcp from './Mcp.js';
 import * as Openapi from './Openapi.js';
@@ -76,10 +82,13 @@ export function create(nameOrDefinition, definition) {
             if (pending.length > 0)
                 await Promise.all(pending);
             return fetchImpl(name, commands, req, {
+                envSchema: def.env,
                 mcpHandler,
                 middlewares,
+                name,
                 rootCommand: rootDef,
                 vars: def.vars,
+                version: def.version,
             });
         },
         async serve(argv = process.argv.slice(2), serveOptions = {}) {
@@ -88,6 +97,7 @@ export function create(nameOrDefinition, definition) {
             return serveImpl(name, commands, argv, {
                 ...serveOptions,
                 aliases: def.aliases,
+                config: def.config,
                 description: def.description,
                 envSchema: def.env,
                 format: def.format,
@@ -108,6 +118,10 @@ export function create(nameOrDefinition, definition) {
     };
     if (rootDef)
         toRootDefinition.set(cli, rootDef);
+    if (def.options)
+        toRootOptions.set(cli, def.options);
+    if (def.config !== undefined)
+        toConfigEnabled.set(cli, true);
     if (def.outputPolicy)
         toOutputPolicy.set(cli, def.outputPolicy);
     toMiddlewares.set(cli, middlewares);
@@ -119,10 +133,34 @@ export function create(nameOrDefinition, definition) {
 async function serveImpl(name, commands, argv, options = {}) {
     const stdout = options.stdout ?? ((s) => process.stdout.write(s));
     const exit = options.exit ?? ((code) => process.exit(code));
-    const { verbose, format: formatFlag, formatExplicit, filterOutput, tokenLimit, tokenOffset, tokenCount, llms, llmsFull, mcp: mcpFlag, help, version, schema, rest: filtered, } = extractBuiltinFlags(argv);
+    const human = process.stdout.isTTY === true;
+    const configEnabled = options.config !== undefined;
+    const configFlag = options.config?.flag;
+    function writeln(s) {
+        stdout(s.endsWith('\n') ? s : `${s}\n`);
+    }
+    let builtinFlags;
+    try {
+        builtinFlags = extractBuiltinFlags(argv, { configFlag });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (human)
+            writeln(formatHumanError({ code: 'UNKNOWN', message }));
+        else
+            writeln(Formatter.format({ code: 'UNKNOWN', message }, 'toon'));
+        exit(1);
+        return;
+    }
+    const { verbose, format: formatFlag, formatExplicit, filterOutput, tokenLimit, tokenOffset, tokenCount, llms, llmsFull, mcp: mcpFlag, help, version, schema, configPath, configDisabled, rest: filtered, } = builtinFlags;
     // --mcp: start as MCP stdio server
     if (mcpFlag) {
-        await Mcp.serve(name, options.version ?? '0.0.0', commands);
+        await Mcp.serve(name, options.version ?? '0.0.0', commands, {
+            middlewares: options.middlewares,
+            env: options.envSchema,
+            vars: options.vars,
+            version: options.version,
+        });
         return;
     }
     // COMPLETE: dynamic shell completions (called by shell hook at tab-press)
@@ -139,17 +177,33 @@ async function serveImpl(name, commands, argv, options = {}) {
         else {
             const index = Number(process.env._COMPLETE_INDEX ?? words.length - 1);
             const candidates = Completions.complete(commands, options.rootCommand, words, index);
+            // Add built-in commands (completions, mcp, skills) to completions
+            const current = words[index] ?? '';
+            const nonFlags = words.slice(0, index).filter((w) => !w.startsWith('-'));
+            if (nonFlags.length <= 1) {
+                for (const b of builtinCommands) {
+                    if (b.name.startsWith(current) && !candidates.some((c) => c.value === b.name))
+                        candidates.push({
+                            value: b.name,
+                            description: b.description,
+                            ...(b.subcommands ? { noSpace: true } : undefined),
+                        });
+                }
+            }
+            else if (nonFlags.length === 2) {
+                const parent = nonFlags[nonFlags.length - 1];
+                const builtin = builtinCommands.find((b) => b.name === parent && b.subcommands);
+                if (builtin?.subcommands)
+                    for (const sub of builtin.subcommands)
+                        if (sub.name.startsWith(current))
+                            candidates.push({ value: sub.name, description: sub.description });
+            }
             const out = Completions.format(completeShell, candidates);
             if (out)
                 stdout(out);
         }
         return;
     }
-    // Human mode: stdout is a TTY.
-    const human = process.stdout.isTTY === true;
-    function writeln(s) {
-        stdout(s.endsWith('\n') ? s : `${s}\n`);
-    }
     // Skills staleness check (skip for built-in commands)
     if (!llms && !llmsFull && !schema && !help && !version) {
         const isSkillsAdd = filtered[0] === 'skills' || (filtered[0] === name && filtered[1] === 'skills');
@@ -219,41 +273,23 @@ async function serveImpl(name, commands, argv, options = {}) {
         // not a completions invocation
         return -1;
     })();
+    // TODO: refactor built-in command handlers (completions, skills, mcp) into a generic dispatch loop on `builtinCommands`
     if (completionsIdx !== -1 && filtered[completionsIdx] === 'completions') {
-        if (help) {
-            writeln([
-                `${name} completions — Generate shell completion script`,
-                '',
-                `Usage: ${name} completions <shell>`,
-                '',
-                'Shells:',
-                '  bash',
-                '  fish',
-                '  nushell',
-                '  zsh',
-                '',
-                'Setup:',
-                ...(() => {
-                    const rows = [
-                        ['bash', `eval "$(${name} completions bash)"`, '# add to ~/.bashrc'],
-                        ['zsh', `eval "$(${name} completions zsh)"`, '# add to ~/.zshrc'],
-                        ['fish', `${name} completions fish | source`, '# add to ~/.config/fish/config.fish'],
-                        ['nushell', `see \`${name} completions nushell\``, '# add to config.nu'],
-                    ];
-                    const shellW = Math.max(...rows.map((r) => r[0].length));
-                    const cmdW = Math.max(...rows.map((r) => r[1].length));
-                    return rows.map(([shell, cmd, comment]) => `  ${shell.padEnd(shellW)}  ${cmd.padEnd(cmdW)}  ${comment}`);
-                })(),
-            ].join('\n'));
+        const shell = filtered[completionsIdx + 1];
+        if (help || !shell) {
+            const b = builtinCommands.find((c) => c.name === 'completions');
+            writeln(Help.formatCommand(`${name} completions`, {
+                args: b.args,
+                description: b.description,
+                hideGlobalOptions: true,
+                hint: b.hint?.(name),
+            }));
             return;
         }
-        const shell = filtered[completionsIdx + 1];
-        if (!shell || !['bash', 'fish', 'nushell', 'zsh'].includes(shell)) {
+        if (!shells.includes(shell)) {
             writeln(formatHumanError({
                 code: 'INVALID_SHELL',
-                message: shell
-                    ? `Unknown shell '${shell}'. Supported: bash, fish, nushell, zsh`
-                    : `Missing shell argument. Usage: ${name} completions <bash|fish|nushell|zsh>`,
+                message: `Unknown shell '${shell}'. Supported: ${shells.join(', ')}`,
             }));
             exit(1);
             return;
@@ -264,17 +300,15 @@ async function serveImpl(name, commands, argv, options = {}) {
     }
     // skills add: generate skill files and install via `<pm>x skills add` (only when sync is configured)
     const skillsIdx = filtered[0] === 'skills' ? 0 : filtered[0] === name && filtered[1] === 'skills' ? 1 : -1;
-    if (skillsIdx !== -1 && filtered[skillsIdx] === 'skills' && filtered[skillsIdx + 1] === 'add') {
+    if (skillsIdx !== -1 && filtered[skillsIdx] === 'skills') {
+        if (filtered[skillsIdx + 1] !== 'add') {
+            const b = builtinCommands.find((c) => c.name === 'skills');
+            writeln(formatBuiltinHelp(name, b));
+            return;
+        }
         if (help) {
-            writeln([
-                `${name} skills add — Sync skill files to agents`,
-                '',
-                `Usage: ${name} skills add [options]`,
-                '',
-                'Options:',
-                '  --depth <number>  Grouping depth for skill files (default: 1)',
-                '  --no-global       Install to project instead of globally',
-            ].join('\n'));
+            const b = builtinCommands.find((c) => c.name === 'skills');
+            writeln(formatBuiltinSubcommandHelp(name, b, 'add'));
             return;
         }
         const rest = filtered.slice(skillsIdx + 2);
@@ -333,18 +367,15 @@ async function serveImpl(name, commands, argv, options = {}) {
     }
     // mcp add: register CLI as MCP server via `npx add-mcp`
     const mcpIdx = filtered[0] === 'mcp' ? 0 : filtered[0] === name && filtered[1] === 'mcp' ? 1 : -1;
-    if (mcpIdx !== -1 && filtered[mcpIdx] === 'mcp' && filtered[mcpIdx + 1] === 'add') {
+    if (mcpIdx !== -1 && filtered[mcpIdx] === 'mcp') {
+        if (filtered[mcpIdx + 1] !== 'add') {
+            const b = builtinCommands.find((c) => c.name === 'mcp');
+            writeln(formatBuiltinHelp(name, b));
+            return;
+        }
         if (help) {
-            writeln([
-                `${name} mcp add — Register as MCP server for your agent`,
-                '',
-                `Usage: ${name} mcp add [options]`,
-                '',
-                'Options:',
-                '  -c, --command <cmd>  Override the command agents will run (e.g. "pnpm my-cli --mcp")',
-                '  --no-global          Install to project instead of globally',
-                '  --agent <agent>      Target a specific agent (e.g. claude-code, cursor)',
-            ].join('\n'));
+            const b = builtinCommands.find((c) => c.name === 'mcp');
+            writeln(formatBuiltinSubcommandHelp(name, b, 'add'));
             return;
         }
         const rest = filtered.slice(mcpIdx + 2);
@@ -404,6 +435,7 @@ async function serveImpl(name, commands, argv, options = {}) {
             writeln(Help.formatCommand(name, {
                 alias: cmd.alias,
                 aliases: options.aliases,
+                configFlag,
                 description: cmd.description ?? options.description,
                 version: options.version,
                 args: cmd.args,
@@ -424,6 +456,7 @@ async function serveImpl(name, commands, argv, options = {}) {
         else {
             writeln(Help.formatRoot(name, {
                 aliases: options.aliases,
+                configFlag,
                 description: options.description,
                 version: options.version,
                 commands: collectHelpCommands(commands),
@@ -466,6 +499,7 @@ async function serveImpl(name, commands, argv, options = {}) {
                 writeln(Help.formatCommand(name, {
                     alias: cmd.alias,
                     aliases: options.aliases,
+                    configFlag,
                     description: cmd.description ?? options.description,
                     version: options.version,
                     args: cmd.args,
@@ -482,6 +516,7 @@ async function serveImpl(name, commands, argv, options = {}) {
             else {
                 writeln(Help.formatRoot(helpName, {
                     aliases: isRoot ? options.aliases : undefined,
+                    configFlag,
                     description: helpDesc,
                     version: isRoot ? options.version : undefined,
                     commands: collectHelpCommands(helpCmds),
@@ -499,6 +534,7 @@ async function serveImpl(name, commands, argv, options = {}) {
             writeln(Help.formatCommand(commandName, {
                 alias: cmd.alias,
                 aliases: isRootCmd ? options.aliases : undefined,
+                configFlag,
                 description: cmd.description,
                 version: isRootCmd ? options.version : undefined,
                 args: cmd.args,
@@ -518,6 +554,7 @@ async function serveImpl(name, commands, argv, options = {}) {
     if (schema) {
         if ('help' in resolved) {
             writeln(Help.formatRoot(`${name} ${resolved.path}`, {
+                configFlag,
                 description: resolved.description,
                 commands: collectHelpCommands(resolved.commands),
             }));
@@ -550,6 +587,7 @@ async function serveImpl(name, commands, argv, options = {}) {
     }
     if ('help' in resolved) {
         writeln(Help.formatRoot(`${name} ${resolved.path}`, {
+            configFlag,
             description: resolved.description,
             commands: collectHelpCommands(resolved.commands),
         }));
@@ -807,178 +845,110 @@ async function serveImpl(name, commands, argv, options = {}) {
             : []),
         ...(command.middleware ?? []),
     ];
-    // Initialize vars from schema defaults
-    const varsMap = options.vars ? options.vars.parse({}) : {};
-    const envSource = options.env ?? process.env;
-    const runCommand = async () => {
-        const { args, options: parsedOptions } = Parser.parse(rest, {
-            alias: command.alias,
-            args: command.args,
-            options: command.options,
-        });
-        if (human)
-            emitDeprecationWarnings(rest, command.options, command.alias);
-        const env = command.env ? Parser.parseEnv(command.env, envSource) : {};
-        const okFn = (data, meta = {}) => {
-            return { [sentinel]: 'ok', data, cta: meta.cta };
-        };
-        const errorFn = (opts) => {
-            return { [sentinel]: 'error', ...opts };
-        };
-        const result = command.run({
-            agent: !human,
-            args,
-            env,
-            error: errorFn,
-            format,
-            formatExplicit,
-            name,
-            ok: okFn,
-            options: parsedOptions,
-            var: varsMap,
-            version: options.version,
-        });
-        // Streaming path — async generator
-        if (isAsyncGenerator(result)) {
-            await handleStreaming(result, {
-                name,
-                path,
-                start,
-                format,
-                formatExplicit,
-                human,
-                renderOutput,
-                verbose,
-                truncate,
-                write,
-                writeln,
-                exit,
+    if (human)
+        emitDeprecationWarnings(rest, command.options, command.alias);
+    let defaults;
+    if (configEnabled) {
+        try {
+            defaults = await loadCommandOptionDefaults(name, path, {
+                configDisabled,
+                configPath,
+                files: options.config?.files,
+                loader: options.config?.loader,
             });
-            return;
-        }
-        const awaited = await result;
-        if (isSentinel(awaited)) {
-            const cta = formatCtaBlock(name, awaited.cta);
-            if (awaited[sentinel] === 'ok') {
-                write({
-                    ok: true,
-                    data: awaited.data,
-                    meta: {
-                        command: path,
-                        duration: `${Math.round(performance.now() - start)}ms`,
-                        ...(cta ? { cta } : undefined),
-                    },
-                });
-            }
-            else {
-                const err = awaited;
-                write({
-                    ok: false,
-                    error: {
-                        code: err.code,
-                        message: err.message,
-                        ...(err.retryable !== undefined ? { retryable: err.retryable } : undefined),
-                    },
-                    meta: {
-                        command: path,
-                        duration: `${Math.round(performance.now() - start)}ms`,
-                        ...(cta ? { cta } : undefined),
-                    },
-                });
-                exit(err.exitCode ?? 1);
-            }
         }
-        else {
+        catch (error) {
             write({
-                ok: true,
-                data: awaited,
-                meta: {
-                    command: path,
-                    duration: `${Math.round(performance.now() - start)}ms`,
+                ok: false,
+                error: {
+                    code: error instanceof IncurError ? error.code : 'UNKNOWN',
+                    message: error instanceof Error ? error.message : String(error),
                 },
+                meta: { command: path, duration: `${Math.round(performance.now() - start)}ms` },
             });
+            exit(error instanceof IncurError ? (error.exitCode ?? 1) : 1);
+            return;
         }
-    };
-    try {
-        const cliEnv = options.envSchema ? Parser.parseEnv(options.envSchema, envSource) : {};
-        if (allMiddleware.length > 0) {
-            const errorFn = (opts) => {
-                return { [sentinel]: 'error', ...opts };
-            };
-            const mwCtx = {
-                agent: !human,
+    }
+    const result = await Command.execute(command, {
+        agent: !human,
+        argv: rest,
+        defaults,
+        env: options.envSchema,
+        envSource: options.env,
+        format,
+        formatExplicit,
+        inputOptions: {},
+        middlewares: allMiddleware,
+        name,
+        path,
+        vars: options.vars,
+        version: options.version,
+    });
+    const duration = `${Math.round(performance.now() - start)}ms`;
+    // Streaming path — async generator
+    if ('stream' in result) {
+        await handleStreaming(result.stream, {
+            name,
+            path,
+            start,
+            format,
+            formatExplicit,
+            human,
+            renderOutput,
+            verbose,
+            truncate,
+            write,
+            writeln,
+            exit,
+        });
+        return;
+    }
+    if (result.ok) {
+        const cta = formatCtaBlock(name, result.cta);
+        write({
+            ok: true,
+            data: result.data,
+            meta: {
                 command: path,
-                env: cliEnv,
-                error: errorFn,
-                format,
-                formatExplicit,
-                name,
-                set(key, value) {
-                    varsMap[key] = value;
-                },
-                var: varsMap,
-                version: options.version,
-            };
-            const handleMwSentinel = (result) => {
-                if (!isSentinel(result) || result[sentinel] !== 'error')
-                    return;
-                const err = result;
-                const cta = formatCtaBlock(name, err.cta);
-                write({
-                    ok: false,
-                    error: {
-                        code: err.code,
-                        message: err.message,
-                        ...(err.retryable !== undefined ? { retryable: err.retryable } : undefined),
-                    },
-                    meta: {
-                        command: path,
-                        duration: `${Math.round(performance.now() - start)}ms`,
-                        ...(cta ? { cta } : undefined),
-                    },
-                });
-                exit(err.exitCode ?? 1);
-            };
-            const composed = allMiddleware.reduceRight((next, mw) => async () => {
-                handleMwSentinel(await mw(mwCtx, next));
-            }, runCommand);
-            await composed();
-        }
-        else {
-            await runCommand();
-        }
+                duration,
+                ...(cta ? { cta } : undefined),
+            },
+        });
     }
-    catch (error) {
-        const errorOutput = {
+    else {
+        const cta = formatCtaBlock(name, result.cta);
+        if (human && !formatExplicit && result.error.fieldErrors) {
+            writeln(formatHumanValidationError(name, path, command, new ValidationError({
+                message: result.error.message,
+                fieldErrors: result.error.fieldErrors,
+            }), options.env, configFlag));
+            exit(1);
+            return;
+        }
+        write({
             ok: false,
             error: {
-                code: error instanceof IncurError
-                    ? error.code
-                    : error instanceof ValidationError
-                        ? 'VALIDATION_ERROR'
-                        : 'UNKNOWN',
-                message: error instanceof Error ? error.message : String(error),
-                ...(error instanceof IncurError ? { retryable: error.retryable } : undefined),
-                ...(error instanceof ValidationError ? { fieldErrors: error.fieldErrors } : undefined),
+                code: result.error.code,
+                message: result.error.message,
+                ...(result.error.retryable !== undefined
+                    ? { retryable: result.error.retryable }
+                    : undefined),
+                ...(result.error.fieldErrors ? { fieldErrors: result.error.fieldErrors } : undefined),
             },
             meta: {
                 command: path,
-                duration: `${Math.round(performance.now() - start)}ms`,
+                duration,
+                ...(cta ? { cta } : undefined),
             },
-        };
-        if (human && !formatExplicit && error instanceof ValidationError) {
-            writeln(formatHumanValidationError(name, path, command, error, options.env));
-            exit(1);
-            return;
-        }
-        write(errorOutput);
-        exit(error instanceof IncurError ? (error.exitCode ?? 1) : 1);
+        });
+        exit(result.exitCode ?? 1);
     }
 }
 /** @internal Creates a lazy MCP HTTP handler scoped to a CLI instance. */
 function createMcpHttpHandler(name, version) {
     let transport;
-    return async (req, commands) => {
+    return async (req, commands, mcpOptions) => {
         if (!transport) {
             const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
             const { WebStandardStreamableHTTPServerTransport } = await import('@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js');
@@ -994,7 +964,13 @@ function createMcpHttpHandler(name, version) {
                     ...(hasInput ? { inputSchema: mergedShape } : undefined),
                 }, async (...callArgs) => {
                     const params = hasInput ? callArgs[0] : {};
-                    return Mcp.callTool(tool, params);
+                    return Mcp.callTool(tool, params, {
+                        name,
+                        version,
+                        middlewares: mcpOptions?.middlewares,
+                        env: mcpOptions?.env,
+                        vars: mcpOptions?.vars,
+                    });
                 });
             }
             transport = new WebStandardStreamableHTTPServerTransport({
@@ -1013,7 +989,11 @@ async function fetchImpl(name, commands, req, options = {}) {
     const segments = url.pathname.split('/').filter(Boolean);
     // MCP over HTTP: route /mcp to the MCP transport
     if (segments[0] === 'mcp' && segments.length === 1 && options.mcpHandler)
-        return options.mcpHandler(req, commands);
+        return options.mcpHandler(req, commands, {
+            middlewares: options.middlewares,
+            env: options.envSchema,
+            vars: options.vars,
+        });
     // .well-known/skills/ — Agent Skills Discovery (RFC)
     if (segments[0] === '.well-known' &&
         segments[1] === 'skills' &&
@@ -1103,7 +1083,11 @@ async function fetchImpl(name, commands, req, options = {}) {
     if ('fetchGateway' in resolved)
         return resolved.fetchGateway.fetch(req);
     const { command, path, rest } = resolved;
-    return executeCommand(path, command, rest, inputOptions, start, options);
+    const groupMiddlewares = 'middlewares' in resolved ? resolved.middlewares : [];
+    return executeCommand(path, command, rest, inputOptions, start, {
+        ...options,
+        groupMiddlewares,
+    });
 }
 /** @internal Executes a resolved command for the fetch handler and returns a JSON Response. */
 async function executeCommand(path, command, rest, inputOptions, start, options) {
@@ -1113,156 +1097,90 @@ async function executeCommand(path, command, rest, inputOptions, start, options)
             headers: { 'content-type': 'application/json' },
         });
     }
-    const sentinel_ = Symbol.for('incur.sentinel');
-    const varsMap = options.vars ? options.vars.parse({}) : {};
-    let response;
-    const runCommand = async () => {
-        const { args } = Parser.parse(rest, { args: command.args });
-        const parsedOptions = command.options ? command.options.parse(inputOptions) : {};
-        const okFn = (data) => ({ [sentinel_]: 'ok', data });
-        const errorFn = (opts) => ({ [sentinel_]: 'error', ...opts });
-        const result = command.run({
-            agent: true,
-            args,
-            env: {},
-            error: errorFn,
-            format: 'json',
-            formatExplicit: true,
-            name: path,
-            ok: okFn,
-            options: parsedOptions,
-            var: varsMap,
-            version: undefined,
-        });
-        // Streaming path — async generator → NDJSON response
-        if (isAsyncGenerator(result)) {
-            const stream = new ReadableStream({
-                async start(controller) {
-                    const encoder = new TextEncoder();
-                    try {
-                        let returnValue;
-                        while (true) {
-                            const { value, done } = await result.next();
-                            if (done) {
-                                returnValue = value;
-                                break;
-                            }
-                            if (isSentinel(value) && value[sentinel] === 'error') {
-                                const tagged = value;
-                                controller.enqueue(encoder.encode(JSON.stringify({
-                                    type: 'error',
-                                    ok: false,
-                                    error: { code: tagged.code, message: tagged.message },
-                                }) + '\n'));
-                                controller.close();
-                                return;
-                            }
-                            controller.enqueue(encoder.encode(JSON.stringify({ type: 'chunk', data: value }) + '\n'));
-                        }
-                        const meta = { command: path };
-                        if (isSentinel(returnValue) && returnValue[sentinel] === 'error') {
-                            const tagged = returnValue;
-                            controller.enqueue(encoder.encode(JSON.stringify({
-                                type: 'error',
-                                ok: false,
-                                error: { code: tagged.code, message: tagged.message },
-                            }) + '\n'));
-                        }
-                        else {
-                            controller.enqueue(encoder.encode(JSON.stringify({ type: 'done', ok: true, meta }) + '\n'));
-                        }
-                    }
-                    catch (error) {
-                        controller.enqueue(encoder.encode(JSON.stringify({
-                            type: 'error',
-                            ok: false,
-                            error: {
-                                code: 'UNKNOWN',
-                                message: error instanceof Error ? error.message : String(error),
-                            },
-                        }) + '\n'));
+    const allMiddleware = [
+        ...(options.middlewares ?? []),
+        ...(options.groupMiddlewares ?? []),
+        ...(command.middleware ?? []),
+    ];
+    const result = await Command.execute(command, {
+        agent: true,
+        argv: rest,
+        env: options.envSchema,
+        format: 'json',
+        formatExplicit: true,
+        inputOptions,
+        middlewares: allMiddleware,
+        name: options.name ?? path,
+        parseMode: 'split',
+        path,
+        vars: options.vars,
+        version: options.version,
+    });
+    const duration = `${Math.round(performance.now() - start)}ms`;
+    // Streaming path — async generator → NDJSON response
+    if ('stream' in result) {
+        const stream = new ReadableStream({
+            async start(controller) {
+                const encoder = new TextEncoder();
+                try {
+                    for await (const value of result.stream) {
+                        controller.enqueue(encoder.encode(JSON.stringify({ type: 'chunk', data: value }) + '\n'));
                     }
-                    controller.close();
-                },
-            });
-            response = new Response(stream, {
-                status: 200,
-                headers: { 'content-type': 'application/x-ndjson' },
-            });
-            return;
-        }
-        const awaited = await result;
-        const duration = `${Math.round(performance.now() - start)}ms`;
-        if (typeof awaited === 'object' && awaited !== null && sentinel_ in awaited) {
-            const tagged = awaited;
-            if (tagged[sentinel_] === 'error')
-                response = jsonResponse({
-                    ok: false,
-                    error: { code: tagged.code, message: tagged.message },
-                    meta: { command: path, duration },
-                }, 500);
-            else
-                response = jsonResponse({ ok: true, data: tagged.data, meta: { command: path, duration } }, 200);
-            return;
-        }
-        response = jsonResponse({ ok: true, data: awaited, meta: { command: path, duration } }, 200);
-    };
-    try {
-        const allMiddleware = options.middlewares ?? [];
-        if (allMiddleware.length > 0) {
-            const errorFn = (opts) => {
-                const duration = `${Math.round(performance.now() - start)}ms`;
-                response = jsonResponse({
-                    ok: false,
-                    error: { code: opts.code, message: opts.message },
-                    meta: { command: path, duration },
-                }, 500);
-                return undefined;
-            };
-            const mwCtx = {
-                agent: true,
-                command: path,
-                env: {},
-                error: errorFn,
-                format: 'json',
-                formatExplicit: true,
-                name: path,
-                set(key, value) {
-                    varsMap[key] = value;
-                },
-                var: varsMap,
-                version: undefined,
-            };
-            const composed = allMiddleware.reduceRight((next, mw) => async () => {
-                await mw(mwCtx, next);
-            }, runCommand);
-            await composed();
-        }
-        else {
-            await runCommand();
-        }
+                    controller.enqueue(encoder.encode(JSON.stringify({
+                        type: 'done',
+                        ok: true,
+                        meta: { command: path },
+                    }) + '\n'));
+                }
+                catch (error) {
+                    controller.enqueue(encoder.encode(JSON.stringify({
+                        type: 'error',
+                        ok: false,
+                        error: {
+                            code: 'UNKNOWN',
+                            message: error instanceof Error ? error.message : String(error),
+                        },
+                    }) + '\n'));
+                }
+                controller.close();
+            },
+        });
+        return new Response(stream, {
+            status: 200,
+            headers: { 'content-type': 'application/x-ndjson' },
+        });
     }
-    catch (error) {
-        const duration = `${Math.round(performance.now() - start)}ms`;
-        if (error instanceof ValidationError)
-            return jsonResponse({
-                ok: false,
-                error: { code: 'VALIDATION_ERROR', message: error.message },
-                meta: { command: path, duration },
-            }, 400);
+    if (!result.ok) {
+        const cta = formatCtaBlock(options.name ?? path, result.cta);
         return jsonResponse({
             ok: false,
             error: {
-                code: error instanceof IncurError ? error.code : 'UNKNOWN',
-                message: error instanceof Error ? error.message : String(error),
+                code: result.error.code,
+                message: result.error.message,
+                ...(result.error.retryable !== undefined
+                    ? { retryable: result.error.retryable }
+                    : undefined),
+            },
+            meta: {
+                command: path,
+                duration,
+                ...(cta ? { cta } : undefined),
             },
-            meta: { command: path, duration },
-        }, 500);
+        }, result.error.code === 'VALIDATION_ERROR' ? 400 : 500);
     }
-    return response;
+    const cta = formatCtaBlock(options.name ?? path, result.cta);
+    return jsonResponse({
+        ok: true,
+        data: result.data,
+        meta: {
+            command: path,
+            duration,
+            ...(cta ? { cta } : undefined),
+        },
+    }, 200);
 }
 /** @internal Formats a validation error for TTY with usage hint. */
-function formatHumanValidationError(cli, path, command, error, envSource) {
+function formatHumanValidationError(cli, path, command, error, envSource, configFlag) {
     const lines = [];
     for (const fe of error.fieldErrors)
         lines.push(`Error: missing required argument <${fe.path}>`);
@@ -1270,6 +1188,7 @@ function formatHumanValidationError(cli, path, command, error, envSource) {
     lines.push('');
     lines.push(Help.formatCommand(path === cli ? cli : `${cli} ${path}`, {
         alias: command.alias,
+        configFlag,
         description: command.description,
         args: command.args,
         env: command.env,
@@ -1343,7 +1262,7 @@ function resolveCommand(commands, tokens) {
     };
 }
 /** @internal Extracts built-in flags (--verbose, --format, --json, --llms, --help, --version) from argv. */
-function extractBuiltinFlags(argv) {
+function extractBuiltinFlags(argv, options = {}) {
     let verbose = false;
     let llms = false;
     let llmsFull = false;
@@ -1353,11 +1272,16 @@ function extractBuiltinFlags(argv) {
     let schema = false;
     let format = 'toon';
     let formatExplicit = false;
+    let configPath;
+    let configDisabled = false;
     let filterOutput;
     let tokenLimit;
     let tokenOffset;
     let tokenCount = false;
     const rest = [];
+    const cfgFlag = options.configFlag ? `--${options.configFlag}` : undefined;
+    const cfgFlagEq = options.configFlag ? `--${options.configFlag}=` : undefined;
+    const noCfgFlag = options.configFlag ? `--no-${options.configFlag}` : undefined;
     for (let i = 0; i < argv.length; i++) {
         const token = argv[i];
         if (token === '--verbose')
@@ -1383,6 +1307,25 @@ function extractBuiltinFlags(argv) {
             formatExplicit = true;
             i++;
         }
+        else if (cfgFlag && token === cfgFlag) {
+            const value = argv[i + 1];
+            if (value === undefined)
+                throw new ParseError({ message: `Missing value for flag: ${cfgFlag}` });
+            configPath = value;
+            configDisabled = false;
+            i++;
+        }
+        else if (cfgFlagEq && token.startsWith(cfgFlagEq)) {
+            const value = token.slice(cfgFlagEq.length);
+            if (value.length === 0)
+                throw new ParseError({ message: `Missing value for flag: ${cfgFlag}` });
+            configPath = value;
+            configDisabled = false;
+        }
+        else if (noCfgFlag && token === noCfgFlag) {
+            configPath = undefined;
+            configDisabled = true;
+        }
         else if (token === '--filter-output' && argv[i + 1]) {
             filterOutput = argv[i + 1];
             i++;
@@ -1404,6 +1347,8 @@ function extractBuiltinFlags(argv) {
         verbose,
         format,
         formatExplicit,
+        configPath,
+        configDisabled,
         filterOutput,
         tokenLimit,
         tokenOffset,
@@ -1417,6 +1362,117 @@ function extractBuiltinFlags(argv) {
         rest,
     };
 }
+/** @internal Loads config-backed option defaults for the active command. */
+async function loadCommandOptionDefaults(cli, path, options = {}) {
+    if (options.configDisabled)
+        return undefined;
+    const { loader } = options;
+    // Resolve the target file path
+    let targetPath;
+    if (options.configPath) {
+        targetPath = resolveConfigPath(options.configPath);
+    }
+    else {
+        const searchPaths = options.files ?? [`${cli}.json`];
+        targetPath = await findFirstExisting(searchPaths);
+    }
+    // Load and parse the config
+    let parsed;
+    if (loader) {
+        const result = await loader(targetPath);
+        if (result === undefined)
+            return undefined;
+        if (!isRecord(result))
+            throw new ParseError({ message: 'Config loader must return a plain object or undefined' });
+        parsed = result;
+    }
+    else {
+        if (!targetPath)
+            return undefined;
+        const result = await readJsonConfig(targetPath, !!options.configPath);
+        if (!result)
+            return undefined;
+        parsed = result;
+    }
+    // Extract the command section from the config tree
+    return extractCommandSection(parsed, cli, path);
+}
+/** @internal Resolves a config file path, expanding `~` to home dir. */
+function resolveConfigPath(filePath) {
+    if (filePath.startsWith('~/') || filePath === '~') {
+        return path.join(os.homedir(), filePath.slice(1));
+    }
+    return path.resolve(process.cwd(), filePath);
+}
+/** @internal Returns the first readable file from a list of paths, or `undefined`. */
+async function findFirstExisting(paths) {
+    for (const p of paths) {
+        const resolved = resolveConfigPath(p);
+        try {
+            await fs.access(resolved, fs.constants.R_OK);
+            return resolved;
+        }
+        catch { }
+    }
+    return undefined;
+}
+/** @internal Reads and parses a JSON config file. */
+async function readJsonConfig(targetPath, explicit) {
+    let raw;
+    try {
+        raw = await fs.readFile(targetPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            if (explicit)
+                throw new ParseError({ message: `Config file not found: ${targetPath}` });
+            return undefined;
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new ParseError({
+            message: `Invalid JSON config file: ${targetPath}`,
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+    if (!isRecord(parsed))
+        throw new ParseError({
+            message: `Invalid config file: expected a top-level object in ${targetPath}`,
+        });
+    return parsed;
+}
+/** @internal Walks the nested config tree to extract option defaults for a command path. */
+function extractCommandSection(parsed, cli, path) {
+    const segments = path === cli ? [] : path.split(' ');
+    let node = parsed;
+    for (const seg of segments) {
+        if (!isRecord(node))
+            return undefined;
+        const commands = node.commands;
+        if (!isRecord(commands))
+            return undefined;
+        node = commands[seg];
+        if (node === undefined)
+            return undefined;
+    }
+    if (!isRecord(node))
+        throw new ParseError({
+            message: `Invalid config section for '${path}': expected an object`,
+        });
+    const options = node.options;
+    if (options === undefined)
+        return undefined;
+    if (!isRecord(options))
+        throw new ParseError({
+            message: `Invalid config 'options' for '${path}': expected an object`,
+        });
+    return Object.keys(options).length > 0 ? options : undefined;
+}
 /** @internal Collects immediate child commands/groups for help output. */
 function collectHelpCommands(commands) {
     const result = [];
@@ -1425,6 +1481,23 @@ function collectHelpCommands(commands) {
     }
     return result.sort((a, b) => a.name.localeCompare(b.name));
 }
+/** @internal Formats group-level help for a built-in command (e.g. `cli skills`). */
+function formatBuiltinHelp(cli, builtin) {
+    return Help.formatRoot(`${cli} ${builtin.name}`, {
+        description: builtin.description,
+        commands: builtin.subcommands?.map((s) => ({ name: s.name, description: s.description })),
+    });
+}
+/** @internal Formats subcommand-level help for a built-in command (e.g. `cli skills add --help`). */
+function formatBuiltinSubcommandHelp(cli, builtin, subName) {
+    const sub = builtin.subcommands?.find((s) => s.name === subName);
+    return Help.formatCommand(`${cli} ${builtin.name} ${subName}`, {
+        alias: sub?.alias,
+        description: sub?.description,
+        hideGlobalOptions: true,
+        options: sub?.options,
+    });
+}
 /** @internal Formats help text for a fetch gateway command. */
 function formatFetchHelp(name, description) {
     const lines = [];
@@ -1458,7 +1531,11 @@ export const toCommands = new WeakMap();
 /** @internal Maps CLI instances to their middleware arrays. */
 const toMiddlewares = new WeakMap();
 /** @internal Maps root CLI instances to their command definitions. */
-const toRootDefinition = new WeakMap();
+export const toRootDefinition = new WeakMap();
+/** @internal Maps CLI instances to their root options schema. */
+export const toRootOptions = new WeakMap();
+/** @internal Maps CLI instances to whether config file loading is enabled. */
+export const toConfigEnabled = new WeakMap();
 /** @internal Maps CLI instances to their output policy. */
 const toOutputPolicy = new WeakMap();
 /** @internal Sentinel symbol for `ok()` and `error()` return values. */
@@ -1491,13 +1568,6 @@ function hasRequiredArgs(args) {
 function isSentinel(value) {
     return typeof value === 'object' && value !== null && sentinel in value;
 }
-/** @internal Type guard for async generators returned by streaming `run` handlers. */
-function isAsyncGenerator(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        Symbol.asyncIterator in value &&
-        typeof value.next === 'function');
-}
 /** @internal Handles streaming output from an async generator `run` handler. */
 async function handleStreaming(generator, ctx) {
     // Incremental: no explicit format (default toon), or explicit jsonl