incur 0.1.17 → 0.2.1

package/dist/Cli.js

@@ -1,5 +1,8 @@
 import * as Completions from './Completions.js';
+import * as Filter from './Filter.js';
 import { IncurError, ValidationError } from './Errors.js';
+import * as Fetch from './Fetch.js';
+import * as Openapi from './Openapi.js';
 import * as Formatter from './Formatter.js';
 import * as Help from './Help.js';
 import { detectRunner } from './internal/pm.js';
@@ -13,8 +16,11 @@ export function create(nameOrDefinition, definition) {
     const name = typeof nameOrDefinition === 'string' ? nameOrDefinition : nameOrDefinition.name;
     const def = typeof nameOrDefinition === 'string' ? (definition ?? {}) : nameOrDefinition;
     const rootDef = 'run' in def ? def : undefined;
+    const rootFetch = 'fetch' in def ? def.fetch : undefined;
     const commands = new Map();
     const middlewares = [];
+    const pending = [];
+    const mcpHandler = createMcpHttpHandler(name, def.version ?? '0.0.0');
     const cli = {
         name,
         description: def.description,
@@ -22,6 +28,28 @@ export function create(nameOrDefinition, definition) {
         vars: def.vars,
         command(nameOrCli, def) {
             if (typeof nameOrCli === 'string') {
+                if (def && 'fetch' in def && typeof def.fetch === 'function') {
+                    // OpenAPI + fetch → generate typed command group (async, resolved before serve)
+                    if (def.openapi) {
+                        pending.push(Openapi.generateCommands(def.openapi, def.fetch, { basePath: def.basePath }).then((generated) => {
+                            commands.set(nameOrCli, {
+                                _group: true,
+                                description: def.description,
+                                commands: generated,
+                                ...(def.outputPolicy ? { outputPolicy: def.outputPolicy } : undefined),
+                            });
+                        }));
+                        return cli;
+                    }
+                    commands.set(nameOrCli, {
+                        _fetch: true,
+                        basePath: def.basePath,
+                        description: def.description,
+                        fetch: def.fetch,
+                        ...(def.outputPolicy ? { outputPolicy: def.outputPolicy } : undefined),
+                    });
+                    return cli;
+                }
                 commands.set(nameOrCli, def);
                 return cli;
             }
@@ -43,7 +71,19 @@ export function create(nameOrDefinition, definition) {
             });
             return cli;
         },
+        async fetch(req) {
+            if (pending.length > 0)
+                await Promise.all(pending);
+            return fetchImpl(name, commands, req, {
+                mcpHandler,
+                middlewares,
+                rootCommand: rootDef,
+                vars: def.vars,
+            });
+        },
         async serve(argv = process.argv.slice(2), serveOptions = {}) {
+            if (pending.length > 0)
+                await Promise.all(pending);
             return serveImpl(name, commands, argv, {
                 ...serveOptions,
                 aliases: def.aliases,
@@ -54,6 +94,7 @@ export function create(nameOrDefinition, definition) {
                 middlewares,
                 outputPolicy: def.outputPolicy,
                 rootCommand: rootDef,
+                rootFetch,
                 sync: def.sync,
                 vars: def.vars,
                 version: def.version,
@@ -77,7 +118,7 @@ export function create(nameOrDefinition, definition) {
 async function serveImpl(name, commands, argv, options = {}) {
     const stdout = options.stdout ?? ((s) => process.stdout.write(s));
     const exit = options.exit ?? ((code) => process.exit(code));
-    const { verbose, format: formatFlag, formatExplicit, llms, mcp: mcpFlag, help, version, rest: filtered, } = extractBuiltinFlags(argv);
+    const { verbose, format: formatFlag, formatExplicit, filterOutput, llms, 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);
@@ -109,7 +150,7 @@ async function serveImpl(name, commands, argv, options = {}) {
         stdout(s.endsWith('\n') ? s : `${s}\n`);
     }
     // Skills staleness check (skip for built-in commands)
-    if (!llms && !help && !version) {
+    if (!llms && !schema && !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) {
@@ -363,8 +404,8 @@ async function serveImpl(name, commands, argv, options = {}) {
             }));
             return;
         }
-        if (options.rootCommand) {
-            // Root command with no args — treat as root invocation
+        if (options.rootCommand || options.rootFetch) {
+            // Root command/fetch with no args — treat as root invocation
         }
         else {
             writeln(Help.formatRoot(name, {
@@ -379,7 +420,15 @@ async function serveImpl(name, commands, argv, options = {}) {
     }
     const resolved = filtered.length === 0 && options.rootCommand
         ? { command: options.rootCommand, path: name, rest: [] }
-        : resolveCommand(commands, filtered);
+        : filtered.length === 0 && options.rootFetch
+            ? { fetchGateway: { _fetch: true, fetch: options.rootFetch, description: options.description }, middlewares: [], path: name, rest: [] }
+            : resolveCommand(commands, filtered);
+    // --help on a fetch gateway → show fetch-specific help
+    if (help && 'fetchGateway' in resolved) {
+        const commandName = resolved.path === name ? name : `${name} ${resolved.path}`;
+        writeln(formatFetchHelp(commandName, resolved.fetchGateway.description));
+        return;
+    }
     // --help after a command → show help for that command
     if (help) {
         if ('help' in resolved || 'error' in resolved) {
@@ -417,30 +466,65 @@ async function serveImpl(name, commands, argv, options = {}) {
                 }));
             }
         }
-        else {
+        else if ('command' in resolved) {
+            const cmd = resolved.command;
             const isRootCmd = resolved.path === name;
             const commandName = isRootCmd ? name : `${name} ${resolved.path}`;
             const helpSubcommands = isRootCmd && options.rootCommand && commands.size > 0
                 ? collectHelpCommands(commands)
                 : undefined;
             writeln(Help.formatCommand(commandName, {
-                alias: resolved.command.alias,
+                alias: cmd.alias,
                 aliases: isRootCmd ? options.aliases : undefined,
-                description: resolved.command.description,
+                description: cmd.description,
                 version: isRootCmd ? options.version : undefined,
-                args: resolved.command.args,
-                env: resolved.command.env,
+                args: cmd.args,
+                env: cmd.env,
                 envSource: options.env,
-                hint: resolved.command.hint,
-                options: resolved.command.options,
-                examples: formatExamples(resolved.command.examples),
-                usage: resolved.command.usage,
+                hint: cmd.hint,
+                options: cmd.options,
+                examples: formatExamples(cmd.examples),
+                usage: cmd.usage,
                 commands: helpSubcommands,
                 root: isRootCmd,
             }));
         }
         return;
     }
+    // --schema: output JSON Schema for a command's args, env, options, output
+    if (schema) {
+        if ('help' in resolved) {
+            writeln(Help.formatRoot(`${name} ${resolved.path}`, {
+                description: resolved.description,
+                commands: collectHelpCommands(resolved.commands),
+            }));
+            return;
+        }
+        if ('error' in resolved) {
+            const parent = resolved.path ? `${name} ${resolved.path}` : name;
+            writeln(`Error: '${resolved.error}' is not a command for '${parent}'.`);
+            exit(1);
+            return;
+        }
+        if ('fetchGateway' in resolved) {
+            writeln('--schema is not supported for fetch commands.');
+            exit(1);
+            return;
+        }
+        const cmd = resolved.command;
+        const format = formatExplicit ? formatFlag : 'toon';
+        const result = {};
+        if (cmd.args)
+            result.args = Schema.toJsonSchema(cmd.args);
+        if (cmd.env)
+            result.env = Schema.toJsonSchema(cmd.env);
+        if (cmd.options)
+            result.options = Schema.toJsonSchema(cmd.options);
+        if (cmd.output)
+            result.output = Schema.toJsonSchema(cmd.output);
+        writeln(Formatter.format(result, format));
+        return;
+    }
     if ('help' in resolved) {
         writeln(Help.formatRoot(`${name} ${resolved.path}`, {
             description: resolved.description,
@@ -452,14 +536,19 @@ 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';
-    // Fall back to root command when no subcommand matches
-    const effective = 'error' in resolved && options.rootCommand && !resolved.path
-        ? { command: options.rootCommand, path: name, rest: filtered }
-        : resolved;
+    // Fall back to root fetch when no subcommand matches
+    const effective = 'error' in resolved && options.rootFetch && !resolved.path
+        ? { fetchGateway: { _fetch: true, fetch: options.rootFetch, description: options.description }, middlewares: [], path: name, rest: filtered }
+        : 'error' in resolved && options.rootCommand && !resolved.path
+            ? { command: options.rootCommand, path: name, rest: filtered }
+            : resolved;
     // Resolve outputPolicy: command/group → CLI-level → default ('all')
     const effectiveOutputPolicy = ('outputPolicy' in resolved && resolved.outputPolicy) || options.outputPolicy;
     const renderOutput = !(human && !formatExplicit && effectiveOutputPolicy === 'agent-only');
+    const filterPaths = filterOutput ? Filter.parse(filterOutput) : undefined;
     function write(output) {
+        if (filterPaths && output.ok && output.data != null)
+            output = { ...output, data: Filter.apply(output.data, filterPaths) };
         const cta = output.meta.cta;
         if (human && !verbose) {
             if (output.ok && output.data != null && renderOutput)
@@ -508,6 +597,114 @@ async function serveImpl(name, commands, argv, options = {}) {
         exit(1);
         return;
     }
+    // Fetch gateway execution path
+    if ('fetchGateway' in effective) {
+        const { fetchGateway, path, rest: fetchRest } = effective;
+        const fetchMiddleware = [
+            ...(options.middlewares ?? []),
+            ...(effective.middlewares ?? []),
+        ];
+        const runFetch = async () => {
+            const input = Fetch.parseArgv(fetchRest);
+            if (fetchGateway.basePath)
+                input.path = fetchGateway.basePath + input.path;
+            const request = Fetch.buildRequest(input);
+            const response = await fetchGateway.fetch(request);
+            // Streaming path — NDJSON responses pipe through handleStreaming
+            if (Fetch.isStreamingResponse(response)) {
+                const generator = Fetch.parseStreamingResponse(response);
+                await handleStreaming(generator, {
+                    name,
+                    path,
+                    start,
+                    format,
+                    formatExplicit,
+                    human,
+                    renderOutput,
+                    verbose,
+                    write,
+                    writeln,
+                    exit,
+                });
+                return;
+            }
+            const output = await Fetch.parseResponse(response);
+            if (output.ok) {
+                write({
+                    ok: true,
+                    data: output.data,
+                    meta: {
+                        command: path,
+                        duration: `${Math.round(performance.now() - start)}ms`,
+                    },
+                });
+            }
+            else {
+                write({
+                    ok: false,
+                    error: {
+                        code: `HTTP_${output.status}`,
+                        message: typeof output.data === 'object' && output.data !== null && 'message' in output.data
+                            ? String(output.data.message)
+                            : typeof output.data === 'string' ? output.data : `HTTP ${output.status}`,
+                    },
+                    meta: {
+                        command: path,
+                        duration: `${Math.round(performance.now() - start)}ms`,
+                    },
+                });
+                exit(1);
+            }
+        };
+        try {
+            const cliEnv = options.envSchema ? Parser.parseEnv(options.envSchema, options.env ?? process.env) : {};
+            if (fetchMiddleware.length > 0) {
+                const varsMap = options.vars ? options.vars.parse({}) : {};
+                const errorFn = (opts) => ({ [sentinel]: 'error', ...opts });
+                const mwCtx = {
+                    agent: !human,
+                    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 = fetchMiddleware.reduceRight((next, mw) => async () => { handleMwSentinel(await mw(mwCtx, next)); }, runFetch);
+                await composed();
+            }
+            else {
+                await runFetch();
+            }
+        }
+        catch (error) {
+            write({
+                ok: false,
+                error: {
+                    code: error instanceof IncurError ? error.code : 'UNKNOWN',
+                    message: error instanceof Error ? error.message : String(error),
+                },
+                meta: { command: path, duration: `${Math.round(performance.now() - start)}ms` },
+            });
+            exit(error instanceof IncurError ? (error.exitCode ?? 1) : 1);
+        }
+        return;
+    }
     const { command, path, rest } = effective;
     // Collect middleware: root CLI + groups traversed + per-command
     const allMiddleware = [
@@ -539,10 +736,12 @@ async function serveImpl(name, commands, argv, options = {}) {
             agent: !human,
             args,
             env,
+            error: errorFn,
+            format,
+            formatExplicit,
             name,
-            options: parsedOptions,
             ok: okFn,
-            error: errorFn,
+            options: parsedOptions,
             var: varsMap,
             version: options.version,
         });
@@ -578,12 +777,13 @@ async function serveImpl(name, commands, argv, options = {}) {
                 });
             }
             else {
+                const err = awaited;
                 write({
                     ok: false,
                     error: {
-                        code: awaited.code,
-                        message: awaited.message,
-                        ...(awaited.retryable !== undefined ? { retryable: awaited.retryable } : undefined),
+                        code: err.code,
+                        message: err.message,
+                        ...(err.retryable !== undefined ? { retryable: err.retryable } : undefined),
                     },
                     meta: {
                         command: path,
@@ -591,7 +791,7 @@ async function serveImpl(name, commands, argv, options = {}) {
                         ...(cta ? { cta } : undefined),
                     },
                 });
-                exit(1);
+                exit(err.exitCode ?? 1);
             }
         }
         else {
@@ -616,6 +816,8 @@ async function serveImpl(name, commands, argv, options = {}) {
                 command: path,
                 env: cliEnv,
                 error: errorFn,
+                format,
+                formatExplicit,
                 name,
                 set(key, value) {
                     varsMap[key] = value;
@@ -626,13 +828,14 @@ async function serveImpl(name, commands, argv, options = {}) {
             const handleMwSentinel = (result) => {
                 if (!isSentinel(result) || result[sentinel] !== 'error')
                     return;
-                const cta = formatCtaBlock(name, result.cta);
+                const err = result;
+                const cta = formatCtaBlock(name, err.cta);
                 write({
                     ok: false,
                     error: {
-                        code: result.code,
-                        message: result.message,
-                        ...(result.retryable !== undefined ? { retryable: result.retryable } : undefined),
+                        code: err.code,
+                        message: err.message,
+                        ...(err.retryable !== undefined ? { retryable: err.retryable } : undefined),
                     },
                     meta: {
                         command: path,
@@ -640,7 +843,7 @@ async function serveImpl(name, commands, argv, options = {}) {
                         ...(cta ? { cta } : undefined),
                     },
                 });
-                exit(1);
+                exit(err.exitCode ?? 1);
             };
             const composed = allMiddleware.reduceRight((next, mw) => async () => {
                 handleMwSentinel(await mw(mwCtx, next));
@@ -675,9 +878,236 @@ async function serveImpl(name, commands, argv, options = {}) {
             return;
         }
         write(errorOutput);
-        exit(1);
+        exit(error instanceof IncurError ? (error.exitCode ?? 1) : 1);
     }
 }
+/** @internal Creates a lazy MCP HTTP handler scoped to a CLI instance. */
+function createMcpHttpHandler(name, version) {
+    let transport;
+    return async (req, commands) => {
+        if (!transport) {
+            const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
+            const { WebStandardStreamableHTTPServerTransport } = await import('@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js');
+            const server = new McpServer({ name, version });
+            for (const tool of Mcp.collectTools(commands, [])) {
+                const mergedShape = {
+                    ...tool.command.args?.shape,
+                    ...tool.command.options?.shape,
+                };
+                const hasInput = Object.keys(mergedShape).length > 0;
+                server.registerTool(tool.name, {
+                    ...(tool.description ? { description: tool.description } : undefined),
+                    ...(hasInput ? { inputSchema: mergedShape } : undefined),
+                }, async (...callArgs) => {
+                    const params = hasInput ? callArgs[0] : {};
+                    return Mcp.callTool(tool, params);
+                });
+            }
+            transport = new WebStandardStreamableHTTPServerTransport({
+                sessionIdGenerator: () => crypto.randomUUID(),
+                enableJsonResponse: true,
+            });
+            await server.connect(transport);
+        }
+        return transport.handleRequest(req);
+    };
+}
+/** @internal Handles an HTTP request by resolving a command and returning a JSON Response. */
+async function fetchImpl(name, commands, req, options = {}) {
+    const start = performance.now();
+    const url = new URL(req.url);
+    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);
+    // .well-known/skills/ — Agent Skills Discovery (RFC)
+    if (segments[0] === '.well-known' &&
+        segments[1] === 'skills' &&
+        segments.length >= 3 &&
+        req.method === 'GET') {
+        const groups = new Map();
+        const cmds = collectSkillCommands(commands, [], groups);
+        // GET /.well-known/skills/index.json
+        if (segments[2] === 'index.json' && segments.length === 3) {
+            const files = Skill.split(name, cmds, 1, groups);
+            const skills = files.map((f) => {
+                const descMatch = f.content.match(/^description:\s*(.+)$/m);
+                return {
+                    name: f.dir || name,
+                    description: descMatch?.[1] ?? '',
+                    files: ['SKILL.md'],
+                };
+            });
+            return new Response(JSON.stringify({ skills }), {
+                status: 200,
+                headers: { 'content-type': 'application/json', 'cache-control': 'public, max-age=300' },
+            });
+        }
+        // GET /.well-known/skills/{skill-name}/SKILL.md
+        if (segments.length === 4 && segments[3] === 'SKILL.md') {
+            const skillName = segments[2];
+            const files = Skill.split(name, cmds, 1, groups);
+            const file = files.find((f) => (f.dir || name) === skillName);
+            if (file)
+                return new Response(file.content, {
+                    status: 200,
+                    headers: { 'content-type': 'text/markdown', 'cache-control': 'public, max-age=300' },
+                });
+            return new Response('Not Found', { status: 404 });
+        }
+        return new Response('Not Found', { status: 404 });
+    }
+    // Parse options from search params (GET) or body (non-GET)
+    let inputOptions = {};
+    if (req.method === 'GET')
+        for (const [key, value] of url.searchParams)
+            inputOptions[key] = value;
+    else {
+        try {
+            const contentType = req.headers.get('content-type') ?? '';
+            if (contentType.includes('application/json'))
+                inputOptions = (await req.json());
+        }
+        catch { }
+    }
+    function jsonResponse(body, status) {
+        return new Response(JSON.stringify(body), {
+            status,
+            headers: { 'content-type': 'application/json' },
+        });
+    }
+    // Resolve command from path segments
+    if (segments.length === 0) {
+        // Root path
+        if (options.rootCommand)
+            return executeCommand(name, options.rootCommand, [], inputOptions, start, options);
+        return jsonResponse({ ok: false, error: { code: 'COMMAND_NOT_FOUND', message: 'No root command defined.' }, meta: { command: '/', duration: `${Math.round(performance.now() - start)}ms` } }, 404);
+    }
+    const resolved = resolveCommand(commands, segments);
+    if ('error' in resolved)
+        return jsonResponse({ ok: false, error: { code: 'COMMAND_NOT_FOUND', message: `'${resolved.error}' is not a command for '${resolved.path ? `${name} ${resolved.path}` : name}'.` }, meta: { command: resolved.error, duration: `${Math.round(performance.now() - start)}ms` } }, 404);
+    if ('help' in resolved)
+        return jsonResponse({ ok: false, error: { code: 'COMMAND_NOT_FOUND', message: `'${resolved.path}' is a command group. Specify a subcommand.` }, meta: { command: resolved.path, duration: `${Math.round(performance.now() - start)}ms` } }, 404);
+    if ('fetchGateway' in resolved)
+        return resolved.fetchGateway.fetch(req);
+    const { command, path, rest } = resolved;
+    return executeCommand(path, command, rest, inputOptions, start, 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), {
+            status,
+            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'));
+                    }
+                    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();
+        }
+    }
+    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);
+        return jsonResponse({ ok: false, error: { code: error instanceof IncurError ? error.code : 'UNKNOWN', message: error instanceof Error ? error.message : String(error) }, meta: { command: path, duration } }, 500);
+    }
+    return response;
+}
 /** @internal Formats a validation error for TTY with usage hint. */
 function formatHumanValidationError(cli, path, command, error, envSource) {
     const lines = [];
@@ -708,6 +1138,17 @@ function resolveCommand(commands, tokens) {
     let remaining = rest;
     let inheritedOutputPolicy;
     const collectedMiddlewares = [];
+    // Fetch gateway — all remaining tokens go to the fetch handler
+    if (isFetchGateway(entry)) {
+        const outputPolicy = entry.outputPolicy ?? inheritedOutputPolicy;
+        return {
+            fetchGateway: entry,
+            middlewares: collectedMiddlewares,
+            path: path.join(' '),
+            rest: remaining,
+            ...(outputPolicy ? { outputPolicy } : undefined),
+        };
+    }
     while (isGroup(entry)) {
         if (entry.outputPolicy)
             inheritedOutputPolicy = entry.outputPolicy;
@@ -728,6 +1169,16 @@ function resolveCommand(commands, tokens) {
         path.push(next);
         remaining = remaining.slice(1);
         entry = child;
+        if (isFetchGateway(entry)) {
+            const outputPolicy = entry.outputPolicy ?? inheritedOutputPolicy;
+            return {
+                fetchGateway: entry,
+                middlewares: collectedMiddlewares,
+                path: path.join(' '),
+                rest: remaining,
+                ...(outputPolicy ? { outputPolicy } : undefined),
+            };
+        }
     }
     const outputPolicy = entry.outputPolicy ?? inheritedOutputPolicy;
     return {
@@ -745,8 +1196,10 @@ function extractBuiltinFlags(argv) {
     let mcp = false;
     let help = false;
     let version = false;
+    let schema = false;
     let format = 'toon';
     let formatExplicit = false;
+    let filterOutput;
     const rest = [];
     for (let i = 0; i < argv.length; i++) {
         const token = argv[i];
@@ -760,6 +1213,8 @@ function extractBuiltinFlags(argv) {
             help = true;
         else if (token === '--version')
             version = true;
+        else if (token === '--schema')
+            schema = true;
         else if (token === '--json') {
             format = 'json';
             formatExplicit = true;
@@ -769,26 +1224,51 @@ function extractBuiltinFlags(argv) {
             formatExplicit = true;
             i++;
         }
+        else if (token === '--filter-output' && argv[i + 1]) {
+            filterOutput = argv[i + 1];
+            i++;
+        }
         else
             rest.push(token);
     }
-    return { verbose, format, formatExplicit, llms, mcp, help, version, rest };
+    return { verbose, format, formatExplicit, filterOutput, llms, mcp, help, version, schema, 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 });
+        result.push({ name, description: entry.description });
     }
     return result.sort((a, b) => a.name.localeCompare(b.name));
 }
+/** @internal Formats help text for a fetch gateway command. */
+function formatFetchHelp(name, description) {
+    const lines = [];
+    if (description)
+        lines.push(`${name} — ${description}`);
+    else
+        lines.push(name);
+    lines.push('');
+    lines.push(`Usage: ${name} <path> [options]`);
+    lines.push('');
+    lines.push('Path segments are joined into the request URL path.');
+    lines.push('');
+    lines.push('Options:');
+    lines.push('  -X, --method <METHOD>     HTTP method (default: GET, POST if body present)');
+    lines.push('  -H, --header "Key: Val"   Set a request header (repeatable)');
+    lines.push('  -d, --data <json>          Request body (implies POST)');
+    lines.push('      --body <json>          Request body (implies POST)');
+    lines.push('  --<key> <value>            Query string parameter');
+    return lines.join('\n');
+}
 /** @internal Type guard for command groups. */
 function isGroup(entry) {
     return '_group' in entry;
 }
+/** @internal Type guard for fetch gateways. */
+function isFetchGateway(entry) {
+    return '_fetch' in entry;
+}
 /** @internal Maps CLI instances to their command maps. */
 export const toCommands = new WeakMap();
 /** @internal Maps CLI instances to their middleware arrays. */
@@ -866,7 +1346,7 @@ async function handleStreaming(generator, ctx) {
                             }));
                         else
                             ctx.writeln(formatHumanError({ code: tagged.code, message: tagged.message }));
-                        ctx.exit(1);
+                        ctx.exit(tagged.exitCode ?? 1);
                         return;
                     }
                 }
@@ -890,7 +1370,7 @@ async function handleStreaming(generator, ctx) {
                     }));
                 else
                     ctx.writeln(formatHumanError({ code: err.code, message: err.message }));
-                ctx.exit(1);
+                ctx.exit(err.exitCode ?? 1);
                 return;
             }
             const cta = isSentinel(returnValue) && returnValue[sentinel] === 'ok'
@@ -924,7 +1404,7 @@ async function handleStreaming(generator, ctx) {
                     code: 'UNKNOWN',
                     message: error instanceof Error ? error.message : String(error),
                 }));
-            ctx.exit(1);
+            ctx.exit(error instanceof IncurError ? (error.exitCode ?? 1) : 1);
         }
     }
     else {
@@ -953,7 +1433,7 @@ async function handleStreaming(generator, ctx) {
                                 duration: `${Math.round(performance.now() - ctx.start)}ms`,
                             },
                         });
-                        ctx.exit(1);
+                        ctx.exit(tagged.exitCode ?? 1);
                         return;
                     }
                 }
@@ -973,7 +1453,7 @@ async function handleStreaming(generator, ctx) {
                         duration: `${Math.round(performance.now() - ctx.start)}ms`,
                     },
                 });
-                ctx.exit(1);
+                ctx.exit(err.exitCode ?? 1);
                 return;
             }
             const cta = isSentinel(returnValue) && returnValue[sentinel] === 'ok'
@@ -1001,7 +1481,7 @@ async function handleStreaming(generator, ctx) {
                     duration: `${Math.round(performance.now() - ctx.start)}ms`,
                 },
             });
-            ctx.exit(1);
+            ctx.exit(error instanceof IncurError ? (error.exitCode ?? 1) : 1);
         }
     }
 }
@@ -1040,7 +1520,13 @@ function collectCommands(commands, prefix) {
     const result = [];
     for (const [name, entry] of commands) {
         const path = [...prefix, name];
-        if (isGroup(entry)) {
+        if (isFetchGateway(entry)) {
+            const cmd = { name: path.join(' ') };
+            if (entry.description)
+                cmd.description = entry.description;
+            result.push(cmd);
+        }
+        else if (isGroup(entry)) {
             result.push(...collectCommands(entry.commands, path));
         }
         else {
@@ -1078,7 +1564,14 @@ function collectSkillCommands(commands, prefix, groups) {
     const result = [];
     for (const [name, entry] of commands) {
         const path = [...prefix, name];
-        if (isGroup(entry)) {
+        if (isFetchGateway(entry)) {
+            const cmd = { name: path.join(' ') };
+            if (entry.description)
+                cmd.description = entry.description;
+            cmd.hint = 'Fetch gateway. Pass path segments and curl-style flags (-X, -H, -d, --key value).';
+            result.push(cmd);
+        }
+        else if (isGroup(entry)) {
             if (entry.description)
                 groups.set(path.join(' '), entry.description);
             result.push(...collectSkillCommands(entry.commands, path, groups));