incur 0.3.3 → 0.3.5

package/dist/Cli.js

@@ -5,6 +5,8 @@ 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 { detectRunner } from './internal/pm.js';
 import * as Mcp from './Mcp.js';
 import * as Openapi from './Openapi.js';
@@ -76,10 +78,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 = {}) {
@@ -122,7 +127,12 @@ async function serveImpl(name, commands, argv, options = {}) {
     const { verbose, format: formatFlag, formatExplicit, filterOutput, tokenLimit, tokenOffset, tokenCount, llms, llmsFull, mcp: mcpFlag, help, version, schema, rest: filtered, } = extractBuiltinFlags(argv);
     // --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,6 +149,27 @@ 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);
@@ -219,41 +250,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 +277,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 your agent`,
-                '',
-                `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 +344,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 an 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);
@@ -807,178 +815,86 @@ 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,
+    if (human)
+        emitDeprecationWarnings(rest, command.options, command.alias);
+    const result = await Command.execute(command, {
+        agent: !human,
+        argv: rest,
+        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,
-            name,
-            ok: okFn,
-            options: parsedOptions,
-            var: varsMap,
-            version: options.version,
+            human,
+            renderOutput,
+            verbose,
+            truncate,
+            write,
+            writeln,
+            exit,
         });
-        // Streaming path — async generator
-        if (isAsyncGenerator(result)) {
-            await handleStreaming(result, {
-                name,
-                path,
-                start,
-                format,
-                formatExplicit,
-                human,
-                renderOutput,
-                verbose,
-                truncate,
-                write,
-                writeln,
-                exit,
-            });
-            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 {
-            write({
-                ok: true,
-                data: awaited,
-                meta: {
-                    command: path,
-                    duration: `${Math.round(performance.now() - start)}ms`,
-                },
-            });
-        }
-    };
-    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,
+        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));
+            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 +910,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 +935,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 +1029,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,153 +1043,87 @@ 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 },
-        }, 500);
+            meta: {
+                command: path,
+                duration,
+                ...(cta ? { cta } : undefined),
+            },
+        }, 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) {
@@ -1425,6 +1289,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 = [];
@@ -1477,8 +1358,9 @@ function formatHumanError(error) {
 /** @internal Formats a CTA block for human-readable TTY output. */
 function formatHumanCta(cta) {
     const lines = ['', cta.description];
+    const maxLen = Math.max(...cta.commands.map((c) => c.command.length));
     for (const c of cta.commands) {
-        const desc = c.description ? `  # ${c.description}` : '';
+        const desc = c.description ? `  ${''.padEnd(maxLen - c.command.length)}# ${c.description}` : '';
         lines.push(`  ${c.command}${desc}`);
     }
     return lines.join('\n');
@@ -1490,13 +1372,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