incur 0.4.8 → 0.4.10

package/dist/Cli.js

@@ -1,8 +1,8 @@
 import * as fs from 'node:fs/promises';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { PassThrough } from 'node:stream';
 import { estimateTokenCount, sliceByTokens } from 'tokenx';
-import { parse as yamlParse, stringify as yamlStringify } from 'yaml';
 import { z } from 'zod';
 import * as Completions from './Completions.js';
 import { IncurError, ParseError, ValidationError } from './Errors.js';
@@ -12,8 +12,11 @@ import * as Formatter from './Formatter.js';
 import * as Help from './Help.js';
 import { builtinCommands, findBuiltin, findBuiltinSubcommand, shells, } from './internal/command.js';
 import * as Command from './internal/command.js';
+import { formatCtaBlock } from './internal/cta.js';
 import { isRecord, suggest, toKebab } from './internal/helpers.js';
+import * as Json from './internal/json.js';
 import { detectRunner } from './internal/pm.js';
+import * as Yaml from './internal/yaml.js';
 import * as Mcp from './Mcp.js';
 import * as Openapi from './Openapi.js';
 import * as Parser from './Parser.js';
@@ -21,6 +24,7 @@ import * as Schema from './Schema.js';
 import * as Skill from './Skill.js';
 import * as SyncMcp from './SyncMcp.js';
 import * as SyncSkills from './SyncSkills.js';
+const destructiveCommandHint = 'Confirm with the user before executing this destructive command.';
 export function create(nameOrDefinition, definition) {
     const name = typeof nameOrDefinition === 'string' ? nameOrDefinition : nameOrDefinition.name;
     const def = typeof nameOrDefinition === 'string' ? (definition ?? {}) : nameOrDefinition;
@@ -31,7 +35,9 @@ export function create(nameOrDefinition, definition) {
     const commands = new Map();
     const middlewares = [];
     const pending = [];
-    const mcpHandler = createMcpHttpHandler(name, def.version ?? '0.0.0');
+    const mcpHandler = createMcpHttpHandler(name, def.version ?? '0.0.0', {
+        stateless: def.mcp?.stateless,
+    });
     if (def.openapi && rootFetch) {
         pending.push((async () => {
             const spec = await Openapi.resolve(def.openapi, { baseUrl: rootFetchBaseUrl });
@@ -61,12 +67,14 @@ export function create(nameOrDefinition, definition) {
                                 basePath: def.basePath,
                                 config: def.openapiConfig,
                             });
-                            commands.set(nameOrCli, {
+                            const entry = {
                                 _group: true,
                                 description: def.description,
                                 commands: generated,
                                 ...(def.outputPolicy ? { outputPolicy: def.outputPolicy } : undefined),
-                            });
+                            };
+                            assertNoGlobalOptionConflicts(nameOrCli, entry, toGlobals.get(cli));
+                            commands.set(nameOrCli, entry);
                         })());
                         return cli;
                     }
@@ -79,6 +87,7 @@ export function create(nameOrDefinition, definition) {
                     });
                     return cli;
                 }
+                assertNoGlobalOptionConflicts(nameOrCli, def, toGlobals.get(cli));
                 commands.set(nameOrCli, def);
                 if (def.aliases)
                     for (const a of def.aliases)
@@ -87,6 +96,7 @@ export function create(nameOrDefinition, definition) {
             }
             const mountedRootDef = toRootDefinition.get(nameOrCli);
             if (mountedRootDef) {
+                assertNoGlobalOptionConflicts(nameOrCli.name, mountedRootDef, toGlobals.get(cli));
                 commands.set(nameOrCli.name, mountedRootDef);
                 const rootAliases = toRootAliases.get(nameOrCli);
                 if (rootAliases)
@@ -98,21 +108,25 @@ export function create(nameOrDefinition, definition) {
             const subCommands = toCommands.get(sub);
             const subOutputPolicy = toOutputPolicy.get(sub);
             const subMiddlewares = toMiddlewares.get(sub);
-            commands.set(sub.name, {
+            const entry = {
                 _group: true,
                 description: sub.description,
                 commands: subCommands,
                 ...(subOutputPolicy ? { outputPolicy: subOutputPolicy } : undefined),
                 ...(subMiddlewares?.length ? { middlewares: subMiddlewares } : undefined),
-            });
+            };
+            assertNoGlobalOptionConflicts(sub.name, entry, toGlobals.get(cli));
+            commands.set(sub.name, entry);
             return cli;
         },
         async fetch(req) {
             if (pending.length > 0)
                 await Promise.all(pending);
+            const globalsDesc = toGlobals.get(cli);
             return fetchImpl(name, commands, req, {
                 description: def.description,
                 envSchema: def.env,
+                globals: globalsDesc,
                 mcpHandler,
                 middlewares,
                 name,
@@ -124,13 +138,16 @@ export function create(nameOrDefinition, definition) {
         async serve(argv = process.argv.slice(2), serveOptions = {}) {
             if (pending.length > 0)
                 await Promise.all(pending);
+            const globalsDesc = toGlobals.get(cli);
             return serveImpl(name, commands, argv, {
                 ...serveOptions,
                 aliases: def.aliases,
+                banner: def.banner,
                 config: def.config,
                 description: def.description,
                 envSchema: def.env,
                 format: def.format,
+                globals: globalsDesc,
                 mcp: def.mcp,
                 middlewares,
                 outputPolicy: def.outputPolicy,
@@ -156,6 +173,40 @@ export function create(nameOrDefinition, definition) {
         toConfigEnabled.set(cli, true);
     if (def.outputPolicy)
         toOutputPolicy.set(cli, def.outputPolicy);
+    if (def.globals) {
+        toGlobals.set(cli, { schema: def.globals, alias: def.globalAlias });
+        const builtinNames = [
+            'verbose',
+            'format',
+            'json',
+            'llms',
+            'llmsFull',
+            'mcp',
+            'help',
+            'version',
+            'schema',
+            'filterOutput',
+            'tokenLimit',
+            'tokenOffset',
+            'tokenCount',
+            ...(def.config?.flag
+                ? [def.config.flag, `no${def.config.flag[0].toUpperCase()}${def.config.flag.slice(1)}`]
+                : []),
+        ];
+        const globalKeys = Object.keys(def.globals.shape);
+        for (const key of globalKeys) {
+            if (builtinNames.includes(key))
+                throw new Error(`Global option '${key}' conflicts with a built-in flag. Choose a different name.`);
+        }
+        // Check globalAlias values against reserved short aliases
+        const reservedShorts = new Set(['h']);
+        if (def.globalAlias) {
+            for (const [name, short] of Object.entries(def.globalAlias)) {
+                if (reservedShorts.has(short))
+                    throw new Error(`Global alias '-${short}' for '${name}' conflicts with a built-in short flag. Choose a different alias.`);
+            }
+        }
+    }
     toMiddlewares.set(cli, middlewares);
     toCommands.set(cli, commands);
     return cli;
@@ -172,6 +223,22 @@ async function serveImpl(name, commands, argv, options = {}) {
     function writeln(s) {
         stdout(s.endsWith('\n') ? s : `${s}\n`);
     }
+    async function writeBanner() {
+        if (!options.banner || help)
+            return;
+        const banner = typeof options.banner === 'function'
+            ? { render: options.banner, mode: 'all' }
+            : options.banner;
+        const mode = banner.mode ?? 'all';
+        if (mode !== 'all' && mode !== (human ? 'human' : 'agent'))
+            return;
+        try {
+            const text = await banner.render();
+            if (text)
+                writeln(text);
+        }
+        catch { }
+    }
     let builtinFlags;
     try {
         builtinFlags = extractBuiltinFlags(argv, { configFlag });
@@ -185,7 +252,36 @@ async function serveImpl(name, commands, argv, options = {}) {
         exit(1);
         return;
     }
-    const { fullOutput, format: formatFlag, formatExplicit, filterOutput, tokenLimit, tokenOffset, tokenCount, llms, llmsFull, mcp: mcpFlag, help, version, schema, configPath, configDisabled, rest: filtered, } = builtinFlags;
+    const { fullOutput, format: formatFlag, formatExplicit, filterOutput, tokenLimit, tokenOffset, tokenCount, llms, llmsFull, mcp: mcpFlag, help, version, schema, configPath, configDisabled, rest, } = builtinFlags;
+    let globals = {};
+    let filtered = rest;
+    function parseGlobalOptions(validate) {
+        if (!options.globals)
+            return true;
+        try {
+            const result = Parser.parseGlobals(rest, options.globals.schema, options.globals.alias, {
+                validate,
+            });
+            if (validate)
+                globals = result.parsed;
+            filtered = result.rest;
+            return true;
+        }
+        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 false;
+        }
+    }
+    if (!parseGlobalOptions(false))
+        return;
+    // Pre-load yaml for the sync formatting paths below (yaml is loaded lazily -- see internal/yaml.ts).
+    if (formatFlag === 'yaml')
+        await Yaml.load();
     // --mcp: start as MCP stdio server
     if (mcpFlag) {
         await Mcp.serve(name, options.version ?? '0.0.0', commands, {
@@ -193,6 +289,7 @@ async function serveImpl(name, commands, argv, options = {}) {
             env: options.envSchema,
             vars: options.vars,
             version: options.version,
+            ...(options.mcp?.instructions ? { instructions: options.mcp.instructions } : undefined),
         });
         return;
     }
@@ -209,7 +306,9 @@ 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);
+            const candidates = Completions.complete(commands, options.rootCommand, words, index, options.globals
+                ? { schema: options.globals.schema, alias: options.globals.alias }
+                : undefined);
             // Add built-in commands (completions, mcp, skills) to completions
             const current = words[index] ?? '';
             const nonFlags = words.slice(0, index).filter((w) => !w.startsWith('-'));
@@ -282,25 +381,29 @@ async function serveImpl(name, commands, argv, options = {}) {
             }
         }
         const scopedRoot = prefix.length === 0 ? options.rootCommand : undefined;
+        // Markdown skill output renders scopedName separately. Passing prefix again
+        // to those collect helpers would double the group segment in command names
+        // (e.g. "cli auth auth login" instead of "cli auth login").
+        const collectPrefix = prefix.length > 0 ? [] : prefix;
         if (llmsFull) {
             if (!formatExplicit || formatFlag === 'md') {
                 const groups = new Map();
-                const cmds = collectSkillCommands(scopedCommands, prefix, groups, scopedRoot);
+                const cmds = collectSkillCommands(scopedCommands, collectPrefix, groups, scopedRoot);
                 const scopedName = prefix.length > 0 ? `${name} ${prefix.join(' ')}` : name;
                 writeln(Skill.generate(scopedName, cmds, groups));
                 return;
             }
-            writeln(Formatter.format(buildManifest(scopedCommands, prefix), formatFlag));
+            writeln(Formatter.format(buildManifest(scopedCommands, prefix, options.globals?.schema), formatFlag));
             return;
         }
         if (!formatExplicit || formatFlag === 'md') {
             const groups = new Map();
-            const cmds = collectSkillCommands(scopedCommands, prefix, groups, scopedRoot);
+            const cmds = collectSkillCommands(scopedCommands, collectPrefix, groups, scopedRoot);
             const scopedName = prefix.length > 0 ? `${name} ${prefix.join(' ')}` : name;
             writeln(Skill.index(scopedName, cmds, scopedDescription));
             return;
         }
-        writeln(Formatter.format(buildIndexManifest(scopedCommands, prefix), formatFlag));
+        writeln(Formatter.format(buildIndexManifest(scopedCommands, prefix, options.globals?.schema), formatFlag));
         return;
     }
     // completions <shell>: print shell hook script to stdout
@@ -465,12 +568,15 @@ async function serveImpl(name, commands, argv, options = {}) {
         }
         return;
     }
-    // mcp add: register CLI as MCP server via `npx add-mcp`
+    // mcp add/doctor: register or smoke-test CLI MCP server integration.
     const mcpIdx = builtinIdx(filtered, name, 'mcp');
     if (mcpIdx !== -1) {
+        const builtin = findBuiltin('mcp');
         const mcpSub = filtered[mcpIdx + 1];
-        if (mcpSub && mcpSub !== 'add') {
-            const suggestion = suggest(mcpSub, ['add']);
+        const sub = mcpSub ? findBuiltinSubcommand(builtin, mcpSub) : undefined;
+        if (mcpSub && !sub) {
+            const candidates = builtin.subcommands?.flatMap((sub) => [sub.name, ...(sub.aliases ?? [])]) ?? [];
+            const suggestion = suggest(mcpSub, candidates);
             const didYouMean = suggestion ? ` Did you mean '${suggestion}'?` : '';
             const message = `'${mcpSub}' is not a command for '${name} mcp'.${didYouMean}`;
             const ctaCommands = [];
@@ -493,13 +599,18 @@ async function serveImpl(name, commands, argv, options = {}) {
             return;
         }
         if (!mcpSub) {
-            const b = findBuiltin('mcp');
-            writeln(formatBuiltinHelp(name, b));
+            writeln(formatBuiltinHelp(name, builtin));
             return;
         }
         if (help) {
-            const b = findBuiltin('mcp');
-            writeln(formatBuiltinSubcommandHelp(name, b, 'add'));
+            writeln(formatBuiltinSubcommandHelp(name, builtin, sub.name));
+            return;
+        }
+        if (sub.name === 'doctor') {
+            const result = await runMcpDoctor(name, commands, options);
+            writeln(Formatter.format(result, formatExplicit ? formatFlag : 'toon'));
+            if (!result.ok)
+                exit(1);
             return;
         }
         const rest = filtered.slice(mcpIdx + 2);
@@ -556,11 +667,13 @@ async function serveImpl(name, commands, argv, options = {}) {
             hasRequiredArgs(options.rootCommand.args)) {
             // Root command with args but none provided (human mode) — show help
             const cmd = options.rootCommand;
+            await writeBanner();
             writeln(Help.formatCommand(name, {
                 alias: cmd.alias,
                 aliases: options.aliases,
                 configFlag,
                 description: cmd.description ?? options.description,
+                globals: options.globals,
                 version: options.version,
                 args: cmd.args,
                 env: cmd.env,
@@ -578,10 +691,12 @@ async function serveImpl(name, commands, argv, options = {}) {
             // Root command/fetch with no args — treat as root invocation
         }
         else {
+            await writeBanner();
             writeln(Help.formatRoot(name, {
                 aliases: options.aliases,
                 configFlag,
                 description: options.description,
+                globals: options.globals,
                 version: options.version,
                 commands: collectHelpCommands(commands),
                 root: true,
@@ -635,6 +750,7 @@ async function serveImpl(name, commands, argv, options = {}) {
                     aliases: options.aliases,
                     configFlag,
                     description: cmd.description ?? options.description,
+                    globals: options.globals,
                     version: options.version,
                     args: cmd.args,
                     env: cmd.env,
@@ -652,6 +768,7 @@ async function serveImpl(name, commands, argv, options = {}) {
                     aliases: isRoot ? options.aliases : undefined,
                     configFlag,
                     description: helpDesc,
+                    globals: options.globals,
                     version: isRoot ? options.version : undefined,
                     commands: collectHelpCommands(helpCmds),
                     root: isRoot,
@@ -670,6 +787,7 @@ async function serveImpl(name, commands, argv, options = {}) {
                 aliases: isRootCmd ? options.aliases : cmd.aliases,
                 configFlag,
                 description: cmd.description,
+                globals: options.globals,
                 version: isRootCmd ? options.version : undefined,
                 args: cmd.args,
                 env: cmd.env,
@@ -690,6 +808,7 @@ async function serveImpl(name, commands, argv, options = {}) {
             writeln(Help.formatRoot(`${name} ${resolved.path}`, {
                 configFlag,
                 description: resolved.description,
+                globals: options.globals,
                 commands: collectHelpCommands(resolved.commands),
             }));
             return;
@@ -718,6 +837,8 @@ async function serveImpl(name, commands, argv, options = {}) {
             result.options = Schema.toJsonSchema(cmd.options);
         if (cmd.output)
             result.output = Schema.toJsonSchema(cmd.output);
+        if (options.globals?.schema)
+            result.globals = Schema.toJsonSchema(options.globals.schema);
         writeln(Formatter.format(result, format));
         return;
     }
@@ -725,6 +846,7 @@ async function serveImpl(name, commands, argv, options = {}) {
         writeln(Help.formatRoot(`${name} ${resolved.path}`, {
             configFlag,
             description: resolved.description,
+            globals: options.globals,
             commands: collectHelpCommands(resolved.commands),
         }));
         return;
@@ -733,6 +855,8 @@ async function serveImpl(name, commands, argv, options = {}) {
     // 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';
+    if (format === 'yaml')
+        await Yaml.load();
     // Fall back to root fetch/command when no subcommand matches,
     // but only if the token doesn't look like a typo of a known command.
     const rootFallbackBlocked = 'error' in resolved &&
@@ -888,6 +1012,8 @@ async function serveImpl(name, commands, argv, options = {}) {
     }
     // Fetch gateway execution path
     if ('fetchGateway' in effective) {
+        if (!parseGlobalOptions(true))
+            return;
         const { fetchGateway, path, rest: fetchRest } = effective;
         const fetchMiddleware = [
             ...(options.middlewares ?? []),
@@ -963,6 +1089,7 @@ async function serveImpl(name, commands, argv, options = {}) {
                     error: errorFn,
                     format,
                     formatExplicit,
+                    globals,
                     name,
                     set(key, value) {
                         varsMap[key] = value;
@@ -1012,7 +1139,9 @@ async function serveImpl(name, commands, argv, options = {}) {
         }
         return;
     }
-    const { command, path, rest } = effective;
+    const { command, path, rest: commandRest } = effective;
+    if (!parseGlobalOptions(true))
+        return;
     // Collect middleware: root CLI + groups traversed + per-command
     const allMiddleware = [
         ...(options.middlewares ?? []),
@@ -1022,7 +1151,7 @@ async function serveImpl(name, commands, argv, options = {}) {
         ...(command.middleware ?? []),
     ];
     if (human)
-        emitDeprecationWarnings(rest, command.options, command.alias);
+        emitDeprecationWarnings(commandRest, command.options, command.alias);
     let defaults;
     if (configEnabled) {
         try {
@@ -1048,13 +1177,14 @@ async function serveImpl(name, commands, argv, options = {}) {
     }
     const result = await Command.execute(command, {
         agent: !human,
-        argv: rest,
+        argv: commandRest,
         defaults,
         displayName,
         env: options.envSchema,
         envSource: options.env,
         format,
         formatExplicit,
+        globals,
         inputOptions: {},
         middlewares: allMiddleware,
         name,
@@ -1123,11 +1253,14 @@ async function serveImpl(name, commands, argv, options = {}) {
     }
 }
 /** @internal Creates a lazy MCP HTTP handler scoped to a CLI instance. */
-function createMcpHttpHandler(name, version) {
+function createMcpHttpHandler(name, version, options = {}) {
     let transport;
     return async (req, commands, mcpOptions) => {
+        const stateless = options.stateless ?? true;
+        if (stateless && req.method !== 'POST')
+            return new Response(null, { status: 405, headers: { Allow: 'POST' } });
         if (!transport) {
-            const { McpServer, WebStandardStreamableHTTPServerTransport } = await import('@modelcontextprotocol/server');
+            const { fromJsonSchema, McpServer, WebStandardStreamableHTTPServerTransport } = await import('@modelcontextprotocol/server');
             const server = new McpServer({ name, version });
             for (const tool of Mcp.collectTools(commands, [])) {
                 const mergedShape = {
@@ -1138,6 +1271,9 @@ function createMcpHttpHandler(name, version) {
                 server.registerTool(tool.name, {
                     ...(tool.description ? { description: tool.description } : undefined),
                     ...(hasInput ? { inputSchema: z.object(mergedShape) } : undefined),
+                    ...(tool.outputSchema
+                        ? { outputSchema: fromJsonSchema(tool.outputSchema) }
+                        : undefined),
                 }, async (...callArgs) => {
                     const params = hasInput ? callArgs[0] : {};
                     return Mcp.callTool(tool, params, {
@@ -1149,10 +1285,13 @@ function createMcpHttpHandler(name, version) {
                     });
                 });
             }
-            transport = new WebStandardStreamableHTTPServerTransport({
-                sessionIdGenerator: () => crypto.randomUUID(),
-                enableJsonResponse: true,
-            });
+            const transportOptions = stateless
+                ? { enableJsonResponse: true }
+                : {
+                    sessionIdGenerator: () => crypto.randomUUID(),
+                    enableJsonResponse: true,
+                };
+            transport = new WebStandardStreamableHTTPServerTransport(transportOptions);
             await server.connect(transport);
         }
         return transport.handleRequest(req);
@@ -1185,7 +1324,7 @@ async function fetchImpl(name, commands, req, options = {}) {
     if (req.method === 'GET' && isOpenapiRoute(segments)) {
         const spec = generatedOpenapi(name, commands, options);
         const yaml = segments[0] === 'openapi.yml' || segments[0] === 'openapi.yaml';
-        return new Response(yaml ? yamlStringify(spec) : JSON.stringify(spec), {
+        return new Response(yaml ? (await Yaml.load()).stringify(spec) : JSON.stringify(spec), {
             status: 200,
             headers: {
                 'content-type': yaml ? 'application/yaml' : 'application/json',
@@ -1205,6 +1344,8 @@ async function fetchImpl(name, commands, req, options = {}) {
         segments[1] === 'skills' &&
         segments.length >= 3 &&
         req.method === 'GET') {
+        // Pre-load yaml for the sync call paths below (`Skill.split`, frontmatter parsing).
+        await Yaml.load();
         const groups = new Map();
         const cmds = collectSkillCommands(commands, [], groups, options.rootCommand);
         // GET /.well-known/skills/index.json
@@ -1212,7 +1353,7 @@ async function fetchImpl(name, commands, req, options = {}) {
             const files = Skill.split(name, cmds, 1, groups);
             const skills = files.map((f) => {
                 const fmMatch = f.content.match(/^---\n([\s\S]*?)\n---/);
-                const meta = fmMatch ? yamlParse(fmMatch[1]) : {};
+                const meta = fmMatch ? Yaml.loadSync().parse(fmMatch[1]) : {};
                 return {
                     name: f.dir || name,
                     description: meta.description ?? '',
@@ -1252,7 +1393,7 @@ async function fetchImpl(name, commands, req, options = {}) {
         catch { }
     }
     function jsonResponse(body, status) {
-        return new Response(JSON.stringify(body), {
+        return new Response(Json.stringify(body), {
             status,
             headers: { 'content-type': 'application/json' },
         });
@@ -1303,7 +1444,7 @@ async function fetchImpl(name, commands, req, options = {}) {
 /** @internal Executes a resolved command for the fetch handler and returns a JSON Response. */
 async function executeCommand(path, command, rest, inputOptions, start, options) {
     function jsonResponse(body, status) {
-        return new Response(JSON.stringify(body), {
+        return new Response(Json.stringify(body), {
             status,
             headers: { 'content-type': 'application/json' },
         });
@@ -1313,13 +1454,39 @@ async function executeCommand(path, command, rest, inputOptions, start, options)
         ...(options.groupMiddlewares ?? []),
         ...(command.middleware ?? []),
     ];
+    let globals = {};
+    let commandInputOptions = inputOptions;
+    if (options.globals) {
+        const globalKeys = new Set(Object.keys(options.globals.schema.shape));
+        const rawGlobals = {};
+        commandInputOptions = {};
+        for (const [key, value] of Object.entries(inputOptions)) {
+            if (globalKeys.has(key))
+                rawGlobals[key] = value;
+            else
+                commandInputOptions[key] = value;
+        }
+        try {
+            globals = options.globals.schema.parse(rawGlobals);
+        }
+        catch (error) {
+            const issues = error?.issues ?? error?.error?.issues ?? [];
+            const message = issues.map((i) => i.message).join('; ') || 'Validation failed';
+            return jsonResponse({
+                ok: false,
+                error: { code: 'VALIDATION_ERROR', message },
+                meta: { command: path, duration: `${Math.round(performance.now() - start)}ms` },
+            }, 400);
+        }
+    }
     const result = await Command.execute(command, {
         agent: true,
         argv: rest,
         env: options.envSchema,
         format: 'json',
         formatExplicit: true,
-        inputOptions,
+        globals,
+        inputOptions: commandInputOptions,
         middlewares: allMiddleware,
         name: options.name ?? path,
         parseMode: 'split',
@@ -1330,30 +1497,68 @@ async function executeCommand(path, command, rest, inputOptions, start, options)
     const duration = `${Math.round(performance.now() - start)}ms`;
     // Streaming path — async generator → NDJSON response
     if ('stream' in result) {
+        const iterator = result.stream;
+        const encoder = new TextEncoder();
+        const meta = (cta) => ({
+            command: path,
+            duration: `${Math.round(performance.now() - start)}ms`,
+            ...(cta ? { cta } : undefined),
+        });
+        const errorRecord = (err) => ({
+            type: 'error',
+            ok: false,
+            error: {
+                code: err.code,
+                message: err.message,
+                ...(err.retryable !== undefined ? { retryable: err.retryable } : undefined),
+            },
+            meta: meta(formatCtaBlock(options.name ?? path, err.cta)),
+        });
         const stream = new ReadableStream({
-            async start(controller) {
-                const encoder = new TextEncoder();
+            async cancel() {
+                await iterator.return(undefined);
+            },
+            async pull(controller) {
                 try {
-                    for await (const value of result.stream) {
-                        controller.enqueue(encoder.encode(JSON.stringify({ type: 'chunk', data: value }) + '\n'));
+                    const { value, done } = await iterator.next();
+                    if (done) {
+                        if (isSentinel(value) && value[sentinel] === 'error') {
+                            controller.enqueue(encoder.encode(Json.stringify(errorRecord(value)) + '\n'));
+                            controller.close();
+                            return;
+                        }
+                        const cta = isSentinel(value) && value[sentinel] === 'ok'
+                            ? formatCtaBlock(options.name ?? path, value.cta)
+                            : undefined;
+                        controller.enqueue(encoder.encode(Json.stringify({
+                            type: 'done',
+                            ok: true,
+                            meta: meta(cta),
+                        }) + '\n'));
+                        controller.close();
+                        return;
                     }
-                    controller.enqueue(encoder.encode(JSON.stringify({
-                        type: 'done',
-                        ok: true,
-                        meta: { command: path },
-                    }) + '\n'));
+                    if (isSentinel(value) && value[sentinel] === 'error') {
+                        controller.enqueue(encoder.encode(Json.stringify(errorRecord(value)) + '\n'));
+                        await iterator.return(undefined);
+                        controller.close();
+                        return;
+                    }
+                    controller.enqueue(encoder.encode(Json.stringify({ type: 'chunk', data: value }) + '\n'));
                 }
                 catch (error) {
-                    controller.enqueue(encoder.encode(JSON.stringify({
+                    controller.enqueue(encoder.encode(Json.stringify({
                         type: 'error',
                         ok: false,
                         error: {
-                            code: 'UNKNOWN',
+                            code: error instanceof IncurError ? error.code : 'UNKNOWN',
                             message: error instanceof Error ? error.message : String(error),
+                            ...(error instanceof IncurError ? { retryable: error.retryable } : undefined),
                         },
+                        meta: meta(),
                     }) + '\n'));
+                    controller.close();
                 }
-                controller.close();
             },
         });
         return new Response(stream, {
@@ -1371,6 +1576,7 @@ async function executeCommand(path, command, rest, inputOptions, start, options)
                 ...(result.error.retryable !== undefined
                     ? { retryable: result.error.retryable }
                     : undefined),
+                ...(result.error.fieldErrors ? { fieldErrors: result.error.fieldErrors } : undefined),
             },
             meta: {
                 command: path,
@@ -1765,6 +1971,115 @@ function formatBuiltinSubcommandHelp(cli, builtin, subName) {
         options: sub?.options,
     });
 }
+async function runMcpDoctor(name, commands, options) {
+    const warnings = [];
+    const errors = [];
+    const input = new PassThrough();
+    const output = new PassThrough();
+    const chunks = [];
+    output.on('data', (chunk) => chunks.push(chunk.toString()));
+    let serveError;
+    const done = Mcp.serve(name, options.version ?? '0.0.0', commands, {
+        input,
+        output,
+        middlewares: options.middlewares,
+        env: options.envSchema,
+        vars: options.vars,
+        version: options.version,
+        ...(options.mcp?.instructions ? { instructions: options.mcp.instructions } : undefined),
+    }).catch((error) => {
+        serveError = error;
+    });
+    input.write(`${Json.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+            protocolVersion: '2024-11-05',
+            capabilities: {},
+            clientInfo: { name: 'incur-doctor', version: '1.0.0' },
+        },
+    })}\n`);
+    input.write(`${Json.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} })}\n`);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    input.end();
+    await done;
+    if (serveError)
+        return {
+            ok: false,
+            toolCount: 0,
+            tools: [],
+            warnings,
+            errors: [{ code: 'MCP_SERVER_FAILED', message: errorMessage(serveError) }],
+        };
+    let responses;
+    try {
+        responses = parseMcpDoctorResponses(chunks);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            toolCount: 0,
+            tools: [],
+            warnings,
+            errors: [{ code: 'MCP_RESPONSE_PARSE_FAILED', message: errorMessage(error) }],
+        };
+    }
+    const initialize = responses.find((response) => response.id === 1);
+    if (!initialize)
+        errors.push({ code: 'MCP_INITIALIZE_MISSING', message: 'Missing initialize response.' });
+    else if (initialize.error)
+        errors.push({ code: 'MCP_INITIALIZE_FAILED', message: mcpErrorMessage(initialize.error) });
+    const toolsList = responses.find((response) => response.id === 2);
+    let tools = [];
+    if (!toolsList)
+        errors.push({ code: 'MCP_TOOLS_LIST_MISSING', message: 'Missing tools/list response.' });
+    else if (toolsList.error)
+        errors.push({ code: 'MCP_TOOLS_LIST_FAILED', message: mcpErrorMessage(toolsList.error) });
+    else if (!isRecord(toolsList.result) || !Array.isArray(toolsList.result.tools))
+        errors.push({
+            code: 'MCP_TOOLS_LIST_INVALID',
+            message: 'tools/list did not return a tools array.',
+        });
+    else
+        tools = toolsList.result.tools
+            .filter(isRecord)
+            .map((tool) => ({
+            name: typeof tool.name === 'string' ? tool.name : '',
+            ...(typeof tool.description === 'string' ? { description: tool.description } : undefined),
+        }))
+            .filter((tool) => tool.name);
+    if (errors.length === 0 && tools.length === 0)
+        warnings.push('No MCP tools exposed.');
+    return {
+        ok: errors.length === 0,
+        toolCount: tools.length,
+        tools,
+        warnings,
+        errors,
+    };
+}
+function parseMcpDoctorResponses(chunks) {
+    const responses = [];
+    for (const line of chunks.join('').split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const parsed = JSON.parse(trimmed);
+        if (!isRecord(parsed))
+            throw new Error('Expected JSON-RPC response object.');
+        responses.push(parsed);
+    }
+    return responses;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function mcpErrorMessage(error) {
+    if (isRecord(error) && typeof error.message === 'string')
+        return error.message;
+    return Json.stringify(error);
+}
 /** @internal Formats help text for a fetch gateway command. */
 function formatFetchHelp(name, description) {
     const lines = [];
@@ -1819,6 +2134,31 @@ function resolveAlias(commands, entry) {
         return commands.get(entry.target);
     return entry;
 }
+/** @internal Validates command options against CLI-level global options. */
+function assertNoGlobalOptionConflicts(path, entry, globals) {
+    if (!globals || isFetchGateway(entry) || isAlias(entry))
+        return;
+    if (isGroup(entry)) {
+        for (const [name, child] of entry.commands)
+            assertNoGlobalOptionConflicts(`${path} ${name}`, child, globals);
+        return;
+    }
+    if (entry.options) {
+        const globalKeys = Object.keys(globals.schema.shape);
+        const optionKeys = Object.keys(entry.options.shape);
+        for (const key of optionKeys) {
+            if (globalKeys.includes(key))
+                throw new Error(`Command '${path}' option '${key}' conflicts with a global option. Choose a different name.`);
+        }
+    }
+    if (globals.alias && entry.alias) {
+        const globalAliasValues = new Set(Object.values(globals.alias));
+        for (const [name, short] of Object.entries(entry.alias)) {
+            if (short && globalAliasValues.has(short))
+                throw new Error(`Command '${path}' alias '-${short}' for '${name}' conflicts with a global alias. Choose a different alias.`);
+        }
+    }
+}
 /** @internal Maps CLI instances to their command maps. */
 export const toCommands = new WeakMap();
 /** @internal Maps CLI instances to their middleware arrays. */
@@ -1831,6 +2171,8 @@ export const toRootOptions = new WeakMap();
 export const toConfigEnabled = new WeakMap();
 /** @internal Maps CLI instances to their output policy. */
 const toOutputPolicy = new WeakMap();
+/** @internal Maps CLI instances to their globals schema and alias map. */
+const toGlobals = new WeakMap();
 /** @internal Maps root CLI instances to their command aliases. */
 const toRootAliases = new WeakMap();
 /** @internal Sentinel symbol for `ok()` and `error()` return values. */
@@ -1901,7 +2243,7 @@ async function handleStreaming(generator, ctx) {
                     }
                 }
                 if (useJsonl)
-                    ctx.writeln(JSON.stringify({ type: 'chunk', data: value }));
+                    ctx.writeln(Json.stringify({ type: 'chunk', data: value }));
                 else if (ctx.renderOutput)
                     ctx.writeln(ctx.truncate(Formatter.format(value, ctx.format)).text);
             }
@@ -1947,6 +2289,7 @@ async function handleStreaming(generator, ctx) {
                     error: {
                         code: error instanceof IncurError ? error.code : 'UNKNOWN',
                         message: error instanceof Error ? error.message : String(error),
+                        ...(error instanceof IncurError ? { retryable: error.retryable } : undefined),
                     },
                 }));
             else
@@ -2025,6 +2368,7 @@ async function handleStreaming(generator, ctx) {
                 error: {
                     code: error instanceof IncurError ? error.code : 'UNKNOWN',
                     message: error instanceof Error ? error.message : String(error),
+                    ...(error instanceof IncurError ? { retryable: error.retryable } : undefined),
                 },
                 meta: {
                     command: ctx.path,
@@ -2035,35 +2379,12 @@ async function handleStreaming(generator, ctx) {
         }
     }
 }
-/** @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 ??
-            (block.commands.length === 1 ? 'Suggested command:' : '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` index manifest (name + description only) from the command tree. */
-function buildIndexManifest(commands, prefix = []) {
+function buildIndexManifest(commands, prefix = [], globalsSchema) {
     return {
         version: 'incur.v1',
         commands: collectIndexCommands(commands, prefix).sort((a, b) => a.name.localeCompare(b.name)),
+        ...(globalsSchema ? { globals: Schema.toJsonSchema(globalsSchema) } : undefined),
     };
 }
 /** @internal Recursively collects leaf commands with name + description only. */
@@ -2090,10 +2411,11 @@ function collectIndexCommands(commands, prefix) {
     return result;
 }
 /** @internal Builds the `--llms` manifest from the command tree. */
-function buildManifest(commands, prefix = []) {
+function buildManifest(commands, prefix = [], globalsSchema) {
     return {
         version: 'incur.v1',
         commands: collectCommands(commands, prefix).sort((a, b) => a.name.localeCompare(b.name)),
+        ...(globalsSchema ? { globals: Schema.toJsonSchema(globalsSchema) } : undefined),
     };
 }
 /** @internal Recursively collects leaf commands with their full paths. */
@@ -2143,7 +2465,7 @@ function collectCommands(commands, prefix) {
     return result;
 }
 /** @internal Recursively collects leaf commands as `Skill.CommandInfo` for `--llms --format md`. */
-function collectSkillCommands(commands, prefix, groups, rootCommand) {
+export function collectSkillCommands(commands, prefix, groups, rootCommand) {
     const result = [];
     if (rootCommand) {
         const cmd = {};
@@ -2155,6 +2477,8 @@ function collectSkillCommands(commands, prefix, groups, rootCommand) {
             cmd.env = rootCommand.env;
         if (rootCommand.hint)
             cmd.hint = rootCommand.hint;
+        if (isDestructive(rootCommand))
+            cmd.hint = appendDestructiveHint(cmd.hint);
         if (rootCommand.options)
             cmd.options = rootCommand.options;
         if (rootCommand.output)
@@ -2190,6 +2514,8 @@ function collectSkillCommands(commands, prefix, groups, rootCommand) {
                 cmd.env = entry.env;
             if (entry.hint)
                 cmd.hint = entry.hint;
+            if (isDestructive(entry))
+                cmd.hint = appendDestructiveHint(cmd.hint);
             if (entry.options)
                 cmd.options = entry.options;
             if (entry.output)
@@ -2207,6 +2533,16 @@ function collectSkillCommands(commands, prefix, groups, rootCommand) {
     }
     return result.sort((a, b) => (a.name ?? '').localeCompare(b.name ?? ''));
 }
+function isDestructive(command) {
+    return command.destructive === true || command.mcp?.annotations?.destructiveHint === true;
+}
+function appendDestructiveHint(hint) {
+    if (!hint)
+        return destructiveCommandHint;
+    if (hint.includes(destructiveCommandHint))
+        return hint;
+    return `${hint} ${destructiveCommandHint}`;
+}
 /** @internal Formats examples into `{ command, description }` objects. `command` is the args/options suffix only. */
 export function formatExamples(examples) {
     if (!examples || examples.length === 0)
@@ -2225,6 +2561,16 @@ export function formatExamples(examples) {
         return result;
     });
 }
+/** @internal Parses YAML frontmatter from generated skill Markdown. */
+export function parseSkillFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return {};
+    const meta = Yaml.loadSync().parse(match[1]);
+    if (!meta || typeof meta !== 'object')
+        return {};
+    return meta;
+}
 /** @internal Builds separate args, env, and options JSON Schemas. */
 function buildInputSchema(args, env, options) {
     if (!args && !env && !options)