incur 0.0.0 → 0.0.2

package/dist/Cli.js

@@ -0,0 +1,900 @@
+import { IncurError, ValidationError } from './Errors.js';
+import * as Formatter from './Formatter.js';
+import * as Help from './Help.js';
+import { detectRunner } from './internal/pm.js';
+import * as Mcp from './Mcp.js';
+import * as Parser from './Parser.js';
+import * as Schema from './Schema.js';
+import * as Skill from './Skill.js';
+import * as SyncMcp from './SyncMcp.js';
+import * as SyncSkills from './SyncSkills.js';
+export function create(nameOrDefinition, definition) {
+    const name = typeof nameOrDefinition === 'string' ? nameOrDefinition : nameOrDefinition.name;
+    const def = typeof nameOrDefinition === 'string' ? (definition ?? {}) : nameOrDefinition;
+    if ('run' in def) {
+        const rootDef = def;
+        const leafCommands = new Map();
+        leafCommands.set(name, rootDef);
+        const leaf = {
+            name,
+            description: def.description,
+            async serve(argv = process.argv.slice(2), options = {}) {
+                return serveImpl(name, leafCommands, [name, ...argv], {
+                    ...options,
+                    description: def.description,
+                    format: def.format,
+                    mcp: def.mcp,
+                    sync: def.sync,
+                    version: def.version,
+                });
+            },
+        };
+        toRootDefinition.set(leaf, rootDef);
+        toCommands.set(leaf, leafCommands);
+        return leaf;
+    }
+    const commands = new Map();
+    const cli = {
+        name,
+        description: def.description,
+        command(nameOrCli, def) {
+            if (typeof nameOrCli === 'string') {
+                commands.set(nameOrCli, def);
+                return cli;
+            }
+            const rootDef = toRootDefinition.get(nameOrCli);
+            if (rootDef) {
+                commands.set(nameOrCli.name, rootDef);
+                return cli;
+            }
+            const sub = nameOrCli;
+            const subCommands = toCommands.get(sub);
+            commands.set(sub.name, { _group: true, description: sub.description, commands: subCommands });
+            return cli;
+        },
+        async serve(argv = process.argv.slice(2), serveOptions = {}) {
+            return serveImpl(name, commands, argv, {
+                ...serveOptions,
+                description: def.description,
+                format: def.format,
+                mcp: def.mcp,
+                sync: def.sync,
+                version: def.version,
+            });
+        },
+    };
+    toCommands.set(cli, commands);
+    return cli;
+}
+/** @internal Shared serve implementation for both router and leaf CLIs. */
+// biome-ignore lint/correctness/noUnusedVariables: _
+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, llms, mcp: mcpFlag, help, version, rest: filtered, } = extractBuiltinFlags(argv);
+    // --mcp: start as MCP stdio server
+    if (mcpFlag) {
+        await Mcp.serve(name, options.version ?? '0.0.0', commands);
+        return;
+    }
+    // Human mode: default unless --verbose or explicit --format/--json override
+    const human = !formatExplicit && !verbose;
+    function writeln(s) {
+        stdout(s.endsWith('\n') ? s : `${s}\n`);
+    }
+    // Skills staleness check (skip for built-in commands)
+    if (!llms && !help && !version) {
+        const isSkillsAdd = filtered[0] === 'skills' || (filtered[0] === name && filtered[1] === 'skills');
+        const isMcpAdd = filtered[0] === 'mcp' || (filtered[0] === name && filtered[1] === 'mcp');
+        if (!isSkillsAdd && !isMcpAdd) {
+            const stored = SyncSkills.readHash(name);
+            if (stored) {
+                const groups = new Map();
+                const entries = collectSkillCommands(commands, [], groups);
+                if (Skill.hash(entries) !== stored) {
+                    const runner = detectRunner();
+                    const spec = SyncMcp.detectPackageSpecifier(name);
+                    process.stderr.write(`⚠ Skills are out of date. Run '${runner} ${spec} skills add' to update.\n\n`);
+                }
+            }
+        }
+    }
+    if (llms) {
+        // Scope to a subtree if command tokens are provided
+        let scopedCommands = commands;
+        const prefix = [];
+        for (const token of filtered) {
+            const entry = scopedCommands.get(token);
+            if (!entry)
+                break;
+            if (isGroup(entry)) {
+                scopedCommands = entry.commands;
+                prefix.push(token);
+            }
+            else {
+                // Leaf command — scope to just this command
+                scopedCommands = new Map([[token, entry]]);
+                break;
+            }
+        }
+        if (!formatExplicit || formatFlag === 'md') {
+            const groups = new Map();
+            const cmds = collectSkillCommands(scopedCommands, prefix, groups);
+            const scopedName = prefix.length > 0 ? `${name} ${prefix.join(' ')}` : name;
+            writeln(Skill.generate(scopedName, cmds, groups));
+            return;
+        }
+        writeln(Formatter.format(buildManifest(scopedCommands, prefix), formatFlag));
+        return;
+    }
+    // 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 (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'));
+            return;
+        }
+        const rest = filtered.slice(skillsIdx + 2);
+        const depthArg = rest.indexOf('--depth');
+        const depth = depthArg !== -1 ? Number(rest[depthArg + 1]) : (options.sync?.depth ?? 1);
+        const global = rest.includes('--no-global') ? false : undefined;
+        try {
+            if (human)
+                stdout('Syncing...');
+            const result = await SyncSkills.sync(name, commands, {
+                cwd: options.sync?.cwd,
+                depth,
+                description: options.description,
+                global,
+                include: options.sync?.include,
+            });
+            if (human) {
+                stdout('\r\x1b[K');
+                const lines = [];
+                const skillLabel = (s) => s.external || s.name === name ? s.name : `${name}-${s.name}`;
+                const maxLen = Math.max(...result.skills.map((s) => skillLabel(s).length));
+                for (const s of result.skills) {
+                    const label = skillLabel(s);
+                    const padding = s.description
+                        ? `${' '.repeat(maxLen - label.length)}  ${s.description}`
+                        : '';
+                    lines.push(`  ✓ ${label}${padding}`);
+                }
+                lines.push('');
+                lines.push(`${result.skills.length} skill${result.skills.length === 1 ? '' : 's'} synced`);
+                const suggestions = options.sync?.suggestions;
+                if (suggestions && suggestions.length > 0) {
+                    lines.push('');
+                    lines.push(`Your agent can now use ${name}. Try asking:`);
+                    for (const s of suggestions)
+                        lines.push(`  "${s}"`);
+                }
+                lines.push('');
+                lines.push(`Run \`${name} --help\` to see the full command reference.`);
+                writeln(lines.join('\n'));
+            }
+            else
+                writeln(Formatter.format({ skills: result.paths }, formatExplicit ? formatFlag : 'toon'));
+        }
+        catch (err) {
+            writeln(Formatter.format({ code: 'SYNC_SKILLS_FAILED', message: err instanceof Error ? err.message : String(err) }, formatExplicit ? formatFlag : 'toon'));
+            exit(1);
+        }
+        return;
+    }
+    // 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 (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'));
+            return;
+        }
+        const rest = filtered.slice(mcpIdx + 2);
+        const global = rest.includes('--no-global') ? false : true;
+        // Parse --command / -c and --agent flags from argv
+        let command = options.mcp?.command;
+        const agents = [...(options.mcp?.agents ?? [])];
+        for (let i = 0; i < rest.length; i++) {
+            if ((rest[i] === '--command' || rest[i] === '-c') && rest[i + 1])
+                command = rest[++i];
+            else if (rest[i] === '--agent' && rest[i + 1])
+                agents.push(rest[++i]);
+        }
+        try {
+            if (human)
+                stdout('Registering MCP server...');
+            const result = await SyncMcp.register(name, {
+                command,
+                global,
+                agents,
+            });
+            if (human) {
+                stdout('\r\x1b[K');
+                const lines = [];
+                lines.push(`✓ Registered ${name} as MCP server`);
+                if (result.agents.length > 0)
+                    lines.push(`  Agents: ${result.agents.join(', ')}`);
+                lines.push('');
+                lines.push(`Agents can now use ${name} tools.`);
+                const suggestions = options.sync?.suggestions;
+                if (suggestions && suggestions.length > 0) {
+                    lines.push('');
+                    lines.push('Try asking:');
+                    for (const s of suggestions)
+                        lines.push(`  "${s}"`);
+                }
+                writeln(lines.join('\n'));
+            }
+            else
+                writeln(Formatter.format({ name, command: result.command, agents: result.agents }, formatExplicit ? formatFlag : 'toon'));
+        }
+        catch (err) {
+            writeln(Formatter.format({ code: 'MCP_ADD_FAILED', message: err instanceof Error ? err.message : String(err) }, formatExplicit ? formatFlag : 'toon'));
+            exit(1);
+        }
+        return;
+    }
+    // --help takes precedence over --version
+    if (version && !help && options.version) {
+        writeln(options.version);
+        return;
+    }
+    if (filtered.length === 0) {
+        writeln(Help.formatRoot(name, {
+            description: options.description,
+            version: options.version,
+            commands: collectHelpCommands(commands),
+            root: true,
+        }));
+        return;
+    }
+    const resolved = resolveCommand(commands, filtered);
+    // --help after a command → show help for that command
+    if (help) {
+        if ('help' in resolved || 'error' in resolved) {
+            // group or unknown → show root help for that path
+            const helpName = 'help' in resolved ? `${name} ${resolved.path}` : name;
+            const helpDesc = 'help' in resolved ? resolved.description : options.description;
+            const helpCmds = 'help' in resolved ? resolved.commands : commands;
+            const isRoot = helpName === name;
+            writeln(Help.formatRoot(helpName, {
+                description: helpDesc,
+                version: isRoot ? options.version : undefined,
+                commands: collectHelpCommands(helpCmds),
+                root: isRoot,
+            }));
+        }
+        else {
+            const isRootCmd = resolved.path === name;
+            const commandName = isRootCmd ? name : `${name} ${resolved.path}`;
+            writeln(Help.formatCommand(commandName, {
+                alias: resolved.command.alias,
+                description: resolved.command.description,
+                version: isRootCmd ? options.version : undefined,
+                args: resolved.command.args,
+                env: resolved.command.env,
+                hint: resolved.command.hint,
+                options: resolved.command.options,
+                examples: formatExamples(resolved.command.examples),
+                usage: resolved.command.usage,
+                root: isRootCmd,
+            }));
+        }
+        return;
+    }
+    if ('help' in resolved) {
+        writeln(Help.formatRoot(`${name} ${resolved.path}`, {
+            description: resolved.description,
+            commands: collectHelpCommands(resolved.commands),
+        }));
+        return;
+    }
+    const start = performance.now();
+    // Resolve effective format: explicit --format/--json → command default → CLI default → toon
+    const resolvedFormat = 'command' in resolved && resolved.command.format;
+    const format = formatExplicit ? formatFlag : resolvedFormat || options.format || 'toon';
+    function write(output) {
+        const cta = output.meta.cta;
+        if (human) {
+            if (output.ok)
+                writeln(Formatter.format(output.data, format));
+            else
+                writeln(formatHumanError(output.error));
+            if (cta)
+                writeln(formatHumanCta(cta));
+            return;
+        }
+        if (verbose)
+            return writeln(Formatter.format(output, format));
+        const base = output.ok ? output.data : output.error;
+        if (!cta)
+            return writeln(Formatter.format(base, format));
+        const payload = typeof base === 'object' && base !== null ? { ...base, cta } : { data: base, cta };
+        writeln(Formatter.format(payload, format));
+    }
+    if ('error' in resolved) {
+        const helpCmd = resolved.path ? `${name} ${resolved.path} --help` : `${name} --help`;
+        const message = `'${resolved.error}' is not a command. See '${helpCmd}' for a list of available commands.`;
+        if (human) {
+            writeln(formatHumanError({ code: 'COMMAND_NOT_FOUND', message }));
+            exit(1);
+            return;
+        }
+        write({
+            ok: false,
+            error: { code: 'COMMAND_NOT_FOUND', message },
+            meta: {
+                command: resolved.error,
+                duration: `${Math.round(performance.now() - start)}ms`,
+            },
+        });
+        exit(1);
+        return;
+    }
+    const { command, path, rest } = resolved;
+    try {
+        const { args, options: parsedOptions } = Parser.parse(rest, {
+            alias: command.alias,
+            args: command.args,
+            options: command.options,
+        });
+        const envSource = options.env ?? process.env;
+        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({
+            args,
+            env,
+            options: parsedOptions,
+            ok: okFn,
+            error: errorFn,
+        });
+        // Streaming path — async generator
+        if (isAsyncGenerator(result)) {
+            await handleStreaming(result, {
+                name,
+                path,
+                start,
+                format,
+                formatExplicit,
+                human,
+                verbose,
+                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 {
+                write({
+                    ok: false,
+                    error: {
+                        code: awaited.code,
+                        message: awaited.message,
+                        ...(awaited.retryable !== undefined ? { retryable: awaited.retryable } : undefined),
+                    },
+                    meta: {
+                        command: path,
+                        duration: `${Math.round(performance.now() - start)}ms`,
+                        ...(cta ? { cta } : undefined),
+                    },
+                });
+                exit(1);
+            }
+        }
+        else {
+            write({
+                ok: true,
+                data: awaited,
+                meta: {
+                    command: path,
+                    duration: `${Math.round(performance.now() - start)}ms`,
+                },
+            });
+        }
+    }
+    catch (error) {
+        const errorOutput = {
+            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),
+            },
+            meta: {
+                command: path,
+                duration: `${Math.round(performance.now() - start)}ms`,
+            },
+        };
+        if (human && error instanceof ValidationError) {
+            writeln(formatHumanValidationError(name, path, command, error));
+            exit(1);
+            return;
+        }
+        write(errorOutput);
+        exit(1);
+    }
+}
+/** @internal Formats a validation error for TTY with usage hint. */
+function formatHumanValidationError(cli, path, command, error) {
+    const lines = [];
+    for (const fe of error.fieldErrors)
+        lines.push(`Error: missing required argument <${fe.path}>`);
+    lines.push('See below for usage.');
+    lines.push('');
+    lines.push(Help.formatCommand(path === cli ? cli : `${cli} ${path}`, {
+        alias: command.alias,
+        description: command.description,
+        args: command.args,
+        env: command.env,
+        hint: command.hint,
+        options: command.options,
+        examples: formatExamples(command.examples),
+        usage: command.usage,
+    }));
+    return lines.join('\n');
+}
+/** @internal Resolves a command from the tree by walking tokens until a leaf is found. */
+function resolveCommand(commands, tokens) {
+    const [first, ...rest] = tokens;
+    if (!first || !commands.has(first))
+        return { error: first ?? '(none)', path: '' };
+    let entry = commands.get(first);
+    const path = [first];
+    let remaining = rest;
+    while (isGroup(entry)) {
+        const next = remaining[0];
+        if (!next)
+            return {
+                help: true,
+                path: path.join(' '),
+                description: entry.description,
+                commands: entry.commands,
+            };
+        const child = entry.commands.get(next);
+        if (!child) {
+            return { error: next, path: path.join(' ') };
+        }
+        path.push(next);
+        remaining = remaining.slice(1);
+        entry = child;
+    }
+    return { command: entry, path: path.join(' '), rest: remaining };
+}
+/** @internal Extracts built-in flags (--verbose, --format, --json, --llms, --help, --version) from argv. */
+function extractBuiltinFlags(argv) {
+    let verbose = false;
+    let llms = false;
+    let mcp = false;
+    let help = false;
+    let version = false;
+    let format = 'toon';
+    let formatExplicit = false;
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--verbose')
+            verbose = true;
+        else if (token === '--llms')
+            llms = true;
+        else if (token === '--mcp')
+            mcp = true;
+        else if (token === '--help' || token === '-h')
+            help = true;
+        else if (token === '--version')
+            version = true;
+        else if (token === '--json') {
+            format = 'json';
+            formatExplicit = true;
+        }
+        else if (token === '--format' && argv[i + 1]) {
+            format = argv[i + 1];
+            formatExplicit = true;
+            i++;
+        }
+        else
+            rest.push(token);
+    }
+    return { verbose, format, formatExplicit, llms, mcp, help, version, rest };
+}
+/** @internal Collects immediate child commands/groups for help output. */
+function collectHelpCommands(commands) {
+    const result = [];
+    for (const [name, entry] of commands) {
+        if (isGroup(entry))
+            result.push({ name, description: entry.description });
+        else
+            result.push({ name, description: entry.description });
+    }
+    return result.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** @internal Type guard for command groups. */
+function isGroup(entry) {
+    return '_group' in entry;
+}
+/** @internal Maps CLI instances to their command maps. */
+export const toCommands = new WeakMap();
+/** @internal Maps root CLI instances to their command definitions. */
+const toRootDefinition = new WeakMap();
+/** @internal Sentinel symbol for `ok()` and `error()` return values. */
+const sentinel = Symbol.for('incur.sentinel');
+/** @internal Formats an error for human-readable TTY output. */
+function formatHumanError(error) {
+    const prefix = error.code === 'UNKNOWN' || error.code === 'COMMAND_NOT_FOUND'
+        ? 'Error'
+        : `Error (${error.code})`;
+    let out = `${prefix}: ${error.message}`;
+    if (error.fieldErrors)
+        for (const fe of error.fieldErrors)
+            out += `\n  ${fe.path}: ${fe.message}`;
+    return out;
+}
+/** @internal Formats a CTA block for human-readable TTY output. */
+function formatHumanCta(cta) {
+    const lines = ['', cta.description];
+    for (const c of cta.commands) {
+        const desc = c.description ? `  ${c.description}` : '';
+        lines.push(`  ${c.command}${desc}`);
+    }
+    return lines.join('\n');
+}
+/** @internal Type guard for sentinel results. */
+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: human, no explicit format (default toon), or explicit jsonl
+    // Buffered: explicit json/yaml/toon/md
+    const useJsonl = !ctx.human && ctx.formatExplicit && ctx.format === 'jsonl';
+    const incremental = ctx.human || useJsonl || !ctx.formatExplicit;
+    if (incremental) {
+        // Incremental output: write each chunk as it arrives
+        try {
+            let returnValue;
+            while (true) {
+                const { value, done } = await generator.next();
+                if (done) {
+                    returnValue = value;
+                    break;
+                }
+                if (isSentinel(value)) {
+                    const tagged = value;
+                    if (tagged[sentinel] === 'error') {
+                        if (useJsonl)
+                            ctx.writeln(JSON.stringify({
+                                type: 'error',
+                                ok: false,
+                                error: {
+                                    code: tagged.code,
+                                    message: tagged.message,
+                                    ...(tagged.retryable !== undefined
+                                        ? { retryable: tagged.retryable }
+                                        : undefined),
+                                },
+                            }));
+                        else
+                            ctx.writeln(formatHumanError({ code: tagged.code, message: tagged.message }));
+                        ctx.exit(1);
+                        return;
+                    }
+                }
+                if (useJsonl)
+                    ctx.writeln(JSON.stringify({ type: 'chunk', data: value }));
+                else
+                    ctx.writeln(Formatter.format(value, 'toon'));
+            }
+            // Handle return value — error() or ok() sentinel
+            if (isSentinel(returnValue) && returnValue[sentinel] === 'error') {
+                const err = returnValue;
+                if (useJsonl)
+                    ctx.writeln(JSON.stringify({
+                        type: 'error',
+                        ok: false,
+                        error: {
+                            code: err.code,
+                            message: err.message,
+                            ...(err.retryable !== undefined ? { retryable: err.retryable } : undefined),
+                        },
+                    }));
+                else
+                    ctx.writeln(formatHumanError({ code: err.code, message: err.message }));
+                ctx.exit(1);
+                return;
+            }
+            const cta = isSentinel(returnValue) && returnValue[sentinel] === 'ok'
+                ? formatCtaBlock(ctx.name, returnValue.cta)
+                : undefined;
+            if (useJsonl)
+                ctx.writeln(JSON.stringify({
+                    type: 'done',
+                    ok: true,
+                    meta: {
+                        command: ctx.path,
+                        duration: `${Math.round(performance.now() - ctx.start)}ms`,
+                        ...(cta ? { cta } : undefined),
+                    },
+                }));
+            else if (cta)
+                ctx.writeln(formatHumanCta(cta));
+        }
+        catch (error) {
+            if (useJsonl)
+                ctx.writeln(JSON.stringify({
+                    type: 'error',
+                    ok: false,
+                    error: {
+                        code: error instanceof IncurError ? error.code : 'UNKNOWN',
+                        message: error instanceof Error ? error.message : String(error),
+                    },
+                }));
+            else
+                ctx.writeln(formatHumanError({
+                    code: 'UNKNOWN',
+                    message: error instanceof Error ? error.message : String(error),
+                }));
+            ctx.exit(1);
+        }
+    }
+    else {
+        // Buffered output: collect all chunks, write as single value
+        const chunks = [];
+        try {
+            let returnValue;
+            while (true) {
+                const { value, done } = await generator.next();
+                if (done) {
+                    returnValue = value;
+                    break;
+                }
+                if (isSentinel(value)) {
+                    const tagged = value;
+                    if (tagged[sentinel] === 'error') {
+                        ctx.write({
+                            ok: false,
+                            error: {
+                                code: tagged.code,
+                                message: tagged.message,
+                                ...(tagged.retryable !== undefined ? { retryable: tagged.retryable } : undefined),
+                            },
+                            meta: {
+                                command: ctx.path,
+                                duration: `${Math.round(performance.now() - ctx.start)}ms`,
+                            },
+                        });
+                        ctx.exit(1);
+                        return;
+                    }
+                }
+                chunks.push(value);
+            }
+            if (isSentinel(returnValue) && returnValue[sentinel] === 'error') {
+                const err = returnValue;
+                ctx.write({
+                    ok: false,
+                    error: {
+                        code: err.code,
+                        message: err.message,
+                        ...(err.retryable !== undefined ? { retryable: err.retryable } : undefined),
+                    },
+                    meta: {
+                        command: ctx.path,
+                        duration: `${Math.round(performance.now() - ctx.start)}ms`,
+                    },
+                });
+                ctx.exit(1);
+                return;
+            }
+            const cta = isSentinel(returnValue) && returnValue[sentinel] === 'ok'
+                ? formatCtaBlock(ctx.name, returnValue.cta)
+                : undefined;
+            ctx.write({
+                ok: true,
+                data: chunks,
+                meta: {
+                    command: ctx.path,
+                    duration: `${Math.round(performance.now() - ctx.start)}ms`,
+                    ...(cta ? { cta } : undefined),
+                },
+            });
+        }
+        catch (error) {
+            ctx.write({
+                ok: false,
+                error: {
+                    code: error instanceof IncurError ? error.code : 'UNKNOWN',
+                    message: error instanceof Error ? error.message : String(error),
+                },
+                meta: {
+                    command: ctx.path,
+                    duration: `${Math.round(performance.now() - ctx.start)}ms`,
+                },
+            });
+            ctx.exit(1);
+        }
+    }
+}
+/** @internal Formats a CTA block into the output envelope shape. */
+function formatCtaBlock(name, block) {
+    if (!block || block.commands.length === 0)
+        return undefined;
+    return {
+        description: block.description ?? 'Suggested commands:',
+        commands: block.commands.map((c) => formatCta(name, c)),
+    };
+}
+/** @internal Formats a CTA by prefixing the CLI name. Handles string and object forms. */
+function formatCta(name, cta) {
+    if (typeof cta === 'string')
+        return { command: `${name} ${cta}` };
+    const prefix = cta.command === name || cta.command.startsWith(`${name} `) ? '' : `${name} `;
+    let cmd = `${prefix}${cta.command}`;
+    if (cta.args)
+        for (const [key, value] of Object.entries(cta.args))
+            cmd += value === true ? ` <${key}>` : ` ${value}`;
+    if (cta.options)
+        for (const [key, value] of Object.entries(cta.options))
+            cmd += value === true ? ` --${key} <${key}>` : ` --${key} ${value}`;
+    return { command: cmd, ...(cta.description ? { description: cta.description } : undefined) };
+}
+/** @internal Builds the `--llms` manifest from the command tree. */
+function buildManifest(commands, prefix = []) {
+    return {
+        version: 'incur.v1',
+        commands: collectCommands(commands, prefix).sort((a, b) => a.name.localeCompare(b.name)),
+    };
+}
+/** @internal Recursively collects leaf commands with their full paths. */
+function collectCommands(commands, prefix) {
+    const result = [];
+    for (const [name, entry] of commands) {
+        const path = [...prefix, name];
+        if (isGroup(entry)) {
+            result.push(...collectCommands(entry.commands, path));
+        }
+        else {
+            const cmd = { name: path.join(' ') };
+            if (entry.description)
+                cmd.description = entry.description;
+            const inputSchema = buildInputSchema(entry.args, entry.env, entry.options);
+            const outputSchema = entry.output ? Schema.toJsonSchema(entry.output) : undefined;
+            if (inputSchema || outputSchema) {
+                cmd.schema = {};
+                if (inputSchema?.args)
+                    cmd.schema.args = inputSchema.args;
+                if (inputSchema?.env)
+                    cmd.schema.env = inputSchema.env;
+                if (inputSchema?.options)
+                    cmd.schema.options = inputSchema.options;
+                if (outputSchema)
+                    cmd.schema.output = outputSchema;
+            }
+            const examples = formatExamples(entry.examples);
+            if (examples) {
+                const cmdName = path.join(' ');
+                cmd.examples = examples.map((e) => ({
+                    ...e,
+                    command: e.command ? `${cmdName} ${e.command}` : cmdName,
+                }));
+            }
+            result.push(cmd);
+        }
+    }
+    return result;
+}
+/** @internal Recursively collects leaf commands as `Skill.CommandInfo` for `--llms --format md`. */
+function collectSkillCommands(commands, prefix, groups) {
+    const result = [];
+    for (const [name, entry] of commands) {
+        const path = [...prefix, name];
+        if (isGroup(entry)) {
+            if (entry.description)
+                groups.set(path.join(' '), entry.description);
+            result.push(...collectSkillCommands(entry.commands, path, groups));
+        }
+        else {
+            const cmd = { name: path.join(' ') };
+            if (entry.description)
+                cmd.description = entry.description;
+            if (entry.args)
+                cmd.args = entry.args;
+            if (entry.env)
+                cmd.env = entry.env;
+            if (entry.hint)
+                cmd.hint = entry.hint;
+            if (entry.options)
+                cmd.options = entry.options;
+            if (entry.output)
+                cmd.output = entry.output;
+            const examples = formatExamples(entry.examples);
+            if (examples) {
+                const cmdName = path.join(' ');
+                cmd.examples = examples.map((e) => ({
+                    ...e,
+                    command: e.command ? `${cmdName} ${e.command}` : cmdName,
+                }));
+            }
+            result.push(cmd);
+        }
+    }
+    return result.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** @internal Formats examples into `{ command, description }` objects. `command` is the args/options suffix only. */
+export function formatExamples(examples) {
+    if (!examples || examples.length === 0)
+        return undefined;
+    return examples.map((ex) => {
+        const parts = [];
+        if (ex.args)
+            for (const value of Object.values(ex.args))
+                parts.push(String(value));
+        if (ex.options)
+            for (const [key, value] of Object.entries(ex.options))
+                parts.push(`--${key} ${value}`);
+        const result = { command: parts.join(' ') };
+        if (ex.description)
+            result.description = ex.description;
+        return result;
+    });
+}
+/** @internal Builds separate args, env, and options JSON Schemas. */
+function buildInputSchema(args, env, options) {
+    if (!args && !env && !options)
+        return undefined;
+    const result = {};
+    if (args)
+        result.args = Schema.toJsonSchema(args);
+    if (env)
+        result.env = Schema.toJsonSchema(env);
+    if (options)
+        result.options = Schema.toJsonSchema(options);
+    return result;
+}
+//# sourceMappingURL=Cli.js.map