incur 0.1.17 → 0.2.1

package/src/Cli.ts

@@ -1,8 +1,11 @@
 import type { z } from 'zod'
 
 import * as Completions from './Completions.js'
+import * as Filter from './Filter.js'
 import type { FieldError } from './Errors.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'
@@ -56,6 +59,11 @@ export type Cli<
       vars,
       env
     >
+    /** Mounts a fetch handler as a command, optionally with OpenAPI spec for typed subcommands. */
+    <const name extends string>(
+      name: name,
+      definition: { basePath?: string | undefined; description?: string | undefined; fetch: FetchHandler; openapi?: Openapi.OpenAPISpec | undefined; outputPolicy?: OutputPolicy | undefined },
+    ): Cli<commands, vars, env>
   }
   /** A short description of the CLI. */
   description?: string | undefined
@@ -63,6 +71,8 @@ export type Cli<
   env: env
   /** The name of the CLI application. */
   name: string
+  /** Handles an incoming HTTP request, resolves the matching command, and returns a JSON Response. */
+  fetch(req: Request): Promise<Response>
   /** Parses argv, runs the matched command, and writes the output envelope to stdout. */
   serve(argv?: string[], options?: serve.Options): Promise<void>
   /** Registers middleware that runs around every command. */
@@ -174,9 +184,12 @@ export function create(
   const name = typeof nameOrDefinition === 'string' ? nameOrDefinition : nameOrDefinition.name
   const def = typeof nameOrDefinition === 'string' ? (definition ?? {}) : nameOrDefinition
   const rootDef = 'run' in def ? (def as CommandDefinition<any, any, any>) : undefined
+  const rootFetch = 'fetch' in def ? (def.fetch as FetchHandler) : undefined
 
   const commands = new Map<string, CommandEntry>()
   const middlewares: MiddlewareHandler[] = []
+  const pending: Promise<void>[] = []
+  const mcpHandler = createMcpHttpHandler(name, def.version ?? '0.0.0')
 
   const cli: Cli = {
     name,
@@ -186,6 +199,30 @@ export function create(
 
     command(nameOrCli: any, def?: any): any {
       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 as Map<string, CommandEntry>,
+                  ...(def.outputPolicy ? { outputPolicy: def.outputPolicy } : undefined),
+                } as InternalGroup)
+              }),
+            )
+            return cli
+          }
+          commands.set(nameOrCli, {
+            _fetch: true,
+            basePath: def.basePath,
+            description: def.description,
+            fetch: def.fetch,
+            ...(def.outputPolicy ? { outputPolicy: def.outputPolicy } : undefined),
+          } as InternalFetchGateway)
+          return cli
+        }
         commands.set(nameOrCli, def)
         return cli
       }
@@ -208,7 +245,18 @@ export function create(
       return cli
     },
 
+    async fetch(req: Request) {
+      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: serve.Options = {}) {
+      if (pending.length > 0) await Promise.all(pending)
       return serveImpl(name, commands, argv, {
         ...serveOptions,
         aliases: def.aliases,
@@ -219,6 +267,7 @@ export function create(
         middlewares,
         outputPolicy: def.outputPolicy,
         rootCommand: rootDef,
+        rootFetch,
         sync: def.sync,
         vars: def.vars,
         version: def.version,
@@ -261,6 +310,8 @@ export declare namespace create {
     env?: env | undefined
     /** Usage examples for this command. */
     examples?: Example<args, options>[] | undefined
+    /** A fetch handler to use as the root command. All argv tokens are interpreted as path segments and curl-style flags. */
+    fetch?: FetchHandler | undefined
     /** Default output format. Overridden by `--format` or `--json`. */
     format?: Formatter.Format | undefined
     /** Zod schema for named options/flags. */
@@ -287,17 +338,22 @@ export declare namespace create {
           agent: boolean
           /** Positional arguments. */
           args: InferOutput<args>
-          /** The CLI name. */
-          name: string
           /** Parsed environment variables. */
           env: InferOutput<env>
           /** Return an error result with optional CTAs. */
           error: (options: {
             code: string
             cta?: CtaBlock | undefined
+            exitCode?: number | undefined
             message: string
             retryable?: boolean | undefined
           }) => never
+          /** The resolved output format (e.g. `'toon'`, `'json'`, `'jsonl'`). */
+          format: Formatter.Format
+          /** Whether the user explicitly passed `--format` or `--json`. */
+          formatExplicit: boolean
+          /** The CLI name. */
+          name: string
           /** Return a success result with optional metadata (e.g. CTAs). */
           ok: (data: InferReturn<output>, meta?: { cta?: CtaBlock | undefined }) => never
           options: InferOutput<options>
@@ -362,10 +418,12 @@ async function serveImpl(
     verbose,
     format: formatFlag,
     formatExplicit,
+    filterOutput,
     llms,
     mcp: mcpFlag,
     help,
     version,
+    schema,
     rest: filtered,
   } = extractBuiltinFlags(argv)
 
@@ -402,7 +460,7 @@ async function serveImpl(
   }
 
   // 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')
@@ -689,8 +747,8 @@ async function serveImpl(
       )
       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, {
@@ -708,7 +766,16 @@ async function serveImpl(
   const resolved =
     filtered.length === 0 && options.rootCommand
       ? { command: options.rootCommand, path: name, rest: [] as string[] }
-      : resolveCommand(commands, filtered)
+      : filtered.length === 0 && options.rootFetch
+        ? { fetchGateway: { _fetch: true as const, fetch: options.rootFetch, description: options.description }, middlewares: [] as MiddlewareHandler[], path: name, rest: [] as string[] }
+        : 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) {
@@ -749,7 +816,8 @@ async function serveImpl(
           }),
         )
       }
-    } else {
+    } else if ('command' in resolved) {
+      const cmd = resolved.command
       const isRootCmd = resolved.path === name
       const commandName = isRootCmd ? name : `${name} ${resolved.path}`
       const helpSubcommands =
@@ -758,17 +826,17 @@ async function serveImpl(
           : undefined
       writeln(
         Help.formatCommand(commandName, {
-          alias: resolved.command.alias as Record<string, string> | undefined,
+          alias: cmd.alias as Record<string, string> | undefined,
           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,
         }),
@@ -777,6 +845,39 @@ async function serveImpl(
     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: Record<string, unknown> = {}
+    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}`, {
@@ -790,21 +891,27 @@ async function serveImpl(
   const start = performance.now()
 
   // Resolve effective format: explicit --format/--json → command default → CLI default → toon
-  const resolvedFormat = 'command' in resolved && resolved.command.format
+  const resolvedFormat = 'command' in resolved && (resolved as any).command.format
   const format = formatExplicit ? formatFlag : resolvedFormat || options.format || 'toon'
 
-  // Fall back to root command when no subcommand matches
+  // Fall back to root fetch when no subcommand matches
   const effective =
-    'error' in resolved && options.rootCommand && !resolved.path
-      ? { command: options.rootCommand, path: name, rest: filtered }
-      : resolved
+    'error' in resolved && options.rootFetch && !resolved.path
+      ? { fetchGateway: { _fetch: true as const, fetch: options.rootFetch, description: options.description }, middlewares: [] as MiddlewareHandler[], 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: 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)
@@ -852,6 +959,119 @@ async function serveImpl(
     return
   }
 
+  // Fetch gateway execution path
+  if ('fetchGateway' in effective) {
+    const { fetchGateway, path, rest: fetchRest } = effective
+    const fetchMiddleware = [
+      ...(options.middlewares ?? []),
+      ...((effective as any).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 as any).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: Record<string, unknown> = options.vars ? options.vars.parse({}) : {}
+        const errorFn = (opts: { code: string; exitCode?: number | undefined; message: string; retryable?: boolean | undefined; cta?: CtaBlock | undefined }): never =>
+          ({ [sentinel]: 'error', ...opts }) as never
+        const mwCtx: MiddlewareContext = {
+          agent: !human,
+          command: path,
+          env: cliEnv,
+          error: errorFn,
+          format,
+          formatExplicit,
+          name,
+          set(key: string, value: unknown) { varsMap[key] = value },
+          var: varsMap,
+          version: options.version,
+        }
+        const handleMwSentinel = (result: unknown) => {
+          if (!isSentinel(result) || result[sentinel] !== 'error') return
+          const err = result as ErrorResult
+          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: () => Promise<void>, 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
@@ -888,6 +1108,7 @@ async function serveImpl(
     }
     const errorFn = (opts: {
       code: string
+      exitCode?: number | undefined
       message: string
       retryable?: boolean | undefined
       cta?: CtaBlock | undefined
@@ -899,10 +1120,12 @@ async function serveImpl(
       agent: !human,
       args,
       env,
+      error: errorFn,
+      format,
+      formatExplicit,
       name,
-      options: parsedOptions,
       ok: okFn,
-      error: errorFn,
+      options: parsedOptions,
       var: varsMap,
       version: options.version,
     })
@@ -940,12 +1163,13 @@ async function serveImpl(
           },
         })
       } else {
+        const err = awaited as ErrorResult
         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,
@@ -953,7 +1177,7 @@ async function serveImpl(
             ...(cta ? { cta } : undefined),
           },
         })
-        exit(1)
+        exit(err.exitCode ?? 1)
       }
     } else {
       write({
@@ -973,6 +1197,7 @@ async function serveImpl(
     if (allMiddleware.length > 0) {
       const errorFn = (opts: {
         code: string
+        exitCode?: number | undefined
         message: string
         retryable?: boolean | undefined
         cta?: CtaBlock | undefined
@@ -984,6 +1209,8 @@ async function serveImpl(
         command: path,
         env: cliEnv,
         error: errorFn,
+        format,
+        formatExplicit,
         name,
         set(key: string, value: unknown) {
           varsMap[key] = value
@@ -993,13 +1220,14 @@ async function serveImpl(
       }
       const handleMwSentinel = (result: unknown) => {
         if (!isSentinel(result) || result[sentinel] !== 'error') return
-        const cta = formatCtaBlock(name, result.cta)
+        const err = result as ErrorResult
+        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,
@@ -1007,7 +1235,7 @@ async function serveImpl(
             ...(cta ? { cta } : undefined),
           },
         })
-        exit(1)
+        exit(err.exitCode ?? 1)
       }
       const composed = allMiddleware.reduceRight(
         (next: () => Promise<void>, mw) => async () => {
@@ -1046,8 +1274,321 @@ async function serveImpl(
     }
 
     write(errorOutput)
-    exit(1)
+    exit(error instanceof IncurError ? (error.exitCode ?? 1) : 1)
+  }
+}
+
+/** @internal Options for fetchImpl. */
+declare namespace fetchImpl {
+  type Options = {
+    mcpHandler?: ((req: Request, commands: Map<string, CommandEntry>) => Promise<Response>) | undefined
+    middlewares?: MiddlewareHandler[] | undefined
+    rootCommand?: CommandDefinition<any, any, any> | undefined
+    vars?: z.ZodObject<any> | undefined
+  }
+}
+
+/** @internal Creates a lazy MCP HTTP handler scoped to a CLI instance. */
+function createMcpHttpHandler(name: string, version: string) {
+  let transport: any
+
+  return async (req: Request, commands: Map<string, CommandEntry>): Promise<Response> => {
+    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: Record<string, any> = {
+          ...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: any[]) => {
+            const params = hasInput ? (callArgs[0] as Record<string, unknown>) : {}
+            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: string,
+  commands: Map<string, CommandEntry>,
+  req: Request,
+  options: fetchImpl.Options = {},
+): Promise<Response> {
+  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<string, string>()
+    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: Record<string, unknown> = {}
+  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()) as Record<string, unknown>
+    } catch {}
+  }
+
+  function jsonResponse(body: unknown, status: number) {
+    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: string,
+  command: CommandDefinition<any, any, any>,
+  rest: string[],
+  inputOptions: Record<string, unknown>,
+  start: number,
+  options: fetchImpl.Options,
+): Promise<Response> {
+  function jsonResponse(body: unknown, status: number) {
+    return new Response(JSON.stringify(body), {
+      status,
+      headers: { 'content-type': 'application/json' },
+    })
+  }
+
+  const sentinel_ = Symbol.for('incur.sentinel')
+  const varsMap: Record<string, unknown> = options.vars ? options.vars.parse({}) : {}
+  let response: Response | undefined
+
+  const runCommand = async () => {
+    const { args } = Parser.parse(rest, { args: command.args })
+    const parsedOptions = command.options ? command.options.parse(inputOptions) : {}
+
+    const okFn = (data: unknown): never => ({ [sentinel_]: 'ok', data }) as never
+    const errorFn = (opts: { code: string; message: string; exitCode?: number | undefined }): never =>
+      ({ [sentinel_]: 'error', ...opts }) as never
+
+    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: unknown
+            while (true) {
+              const { value, done } = await result.next()
+              if (done) {
+                returnValue = value
+                break
+              }
+              if (isSentinel(value) && (value as any)[sentinel] === 'error') {
+                const tagged = value as any
+                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: Record<string, unknown> = { command: path }
+            if (isSentinel(returnValue) && (returnValue as any)[sentinel] === 'error') {
+              const tagged = returnValue as any
+              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 as any
+      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: { code: string; message: string; exitCode?: number | undefined }): never => {
+        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 as never
+      }
+      const mwCtx: MiddlewareContext = {
+        agent: true,
+        command: path,
+        env: {},
+        error: errorFn,
+        format: 'json',
+        formatExplicit: true,
+        name: path,
+        set(key: string, value: unknown) { varsMap[key] = value },
+        var: varsMap,
+        version: undefined,
+      }
+      const composed = allMiddleware.reduceRight(
+        (next: () => Promise<void>, 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. */
@@ -1090,6 +1631,13 @@ function resolveCommand(
       path: string
       rest: string[]
     }
+  | {
+      fetchGateway: InternalFetchGateway
+      middlewares: MiddlewareHandler[]
+      outputPolicy?: OutputPolicy | undefined
+      path: string
+      rest: string[]
+    }
   | {
       help: true
       path: string
@@ -1107,6 +1655,18 @@ function resolveCommand(
   let inheritedOutputPolicy: OutputPolicy | undefined
   const collectedMiddlewares: MiddlewareHandler[] = []
 
+  // 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
     if (entry.middlewares) collectedMiddlewares.push(...entry.middlewares)
@@ -1127,6 +1687,17 @@ function resolveCommand(
     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
@@ -1161,6 +1732,8 @@ declare namespace serveImpl {
       | undefined
     /** Root command handler, invoked when no subcommand matches. */
     rootCommand?: CommandDefinition<any, any, any> | undefined
+    /** Root fetch handler, invoked when no subcommand matches and no rootCommand is set. */
+    rootFetch?: FetchHandler | undefined
     sync?:
       | {
           cwd?: string | undefined
@@ -1182,8 +1755,10 @@ function extractBuiltinFlags(argv: string[]) {
   let mcp = false
   let help = false
   let version = false
+  let schema = false
   let format: Formatter.Format = 'toon'
   let formatExplicit = false
+  let filterOutput: string | undefined
   const rest: string[] = []
 
   for (let i = 0; i < argv.length; i++) {
@@ -1193,6 +1768,7 @@ function extractBuiltinFlags(argv: string[]) {
     else if (token === '--mcp') mcp = true
     else if (token === '--help' || token === '-h') help = true
     else if (token === '--version') version = true
+    else if (token === '--schema') schema = true
     else if (token === '--json') {
       format = 'json'
       formatExplicit = true
@@ -1200,10 +1776,13 @@ function extractBuiltinFlags(argv: string[]) {
       format = argv[i + 1] as Formatter.Format
       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. */
@@ -1212,24 +1791,45 @@ function collectHelpCommands(
 ): { name: string; description?: string | undefined }[] {
   const result: { name: string; description?: string | undefined }[] = []
   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: string, description?: string): string {
+  const lines: string[] = []
+  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')
+}
+
 /** Shape of the commands map accumulated through `.command()` chains. */
 export type CommandsMap = Record<
   string,
   { args: Record<string, unknown>; options: Record<string, unknown> }
 >
 
-/** @internal Entry stored in a command map — either a leaf definition or a group. */
-type CommandEntry = CommandDefinition<any, any, any> | InternalGroup
+/** @internal Entry stored in a command map — either a leaf definition, a group, or a fetch gateway. */
+type CommandEntry = CommandDefinition<any, any, any> | InternalGroup | InternalFetchGateway
 
 /** Controls when output data is displayed. `'all'` displays to both humans and agents. `'agent-only'` suppresses data output in human/TTY mode. */
 export type OutputPolicy = 'agent-only' | 'all'
 
+/** A standard Fetch API handler. */
+type FetchHandler = (req: Request) => Response | Promise<Response>
+
 /** @internal A command group's internal storage. */
 type InternalGroup = {
   _group: true
@@ -1239,11 +1839,25 @@ type InternalGroup = {
   commands: Map<string, CommandEntry>
 }
 
+/** @internal A fetch gateway entry. */
+type InternalFetchGateway = {
+  _fetch: true
+  basePath?: string | undefined
+  description?: string | undefined
+  fetch: FetchHandler
+  outputPolicy?: OutputPolicy | undefined
+}
+
 /** @internal Type guard for command groups. */
 function isGroup(entry: CommandEntry): entry is InternalGroup {
   return '_group' in entry
 }
 
+/** @internal Type guard for fetch gateways. */
+function isFetchGateway(entry: CommandEntry): entry is InternalFetchGateway {
+  return '_fetch' in entry
+}
+
 /** @internal Maps CLI instances to their command maps. */
 export const toCommands = new WeakMap<Cli, Map<string, CommandEntry>>()
 
@@ -1272,6 +1886,7 @@ type ErrorResult = {
   code: string
   message: string
   retryable?: boolean | undefined
+  exitCode?: number | undefined
   cta?: CtaBlock | undefined
 }
 
@@ -1377,7 +1992,7 @@ async function handleStreaming(
                 }),
               )
             else ctx.writeln(formatHumanError({ code: tagged.code, message: tagged.message }))
-            ctx.exit(1)
+            ctx.exit(tagged.exitCode ?? 1)
             return
           }
         }
@@ -1401,7 +2016,7 @@ async function handleStreaming(
             }),
           )
         else ctx.writeln(formatHumanError({ code: err.code, message: err.message }))
-        ctx.exit(1)
+        ctx.exit(err.exitCode ?? 1)
         return
       }
 
@@ -1442,7 +2057,7 @@ async function handleStreaming(
             message: error instanceof Error ? error.message : String(error),
           }),
         )
-      ctx.exit(1)
+      ctx.exit(error instanceof IncurError ? (error.exitCode ?? 1) : 1)
     }
   } else {
     // Buffered output: collect all chunks, write as single value
@@ -1470,7 +2085,7 @@ async function handleStreaming(
                 duration: `${Math.round(performance.now() - ctx.start)}ms`,
               },
             })
-            ctx.exit(1)
+            ctx.exit(tagged.exitCode ?? 1)
             return
           }
         }
@@ -1491,7 +2106,7 @@ async function handleStreaming(
             duration: `${Math.round(performance.now() - ctx.start)}ms`,
           },
         })
-        ctx.exit(1)
+        ctx.exit(err.exitCode ?? 1)
         return
       }
 
@@ -1521,7 +2136,7 @@ async function handleStreaming(
           duration: `${Math.round(performance.now() - ctx.start)}ms`,
         },
       })
-      ctx.exit(1)
+      ctx.exit(error instanceof IncurError ? (error.exitCode ?? 1) : 1)
     }
   }
 }
@@ -1570,7 +2185,11 @@ function collectCommands(
   const result: ReturnType<typeof collectCommands> = []
   for (const [name, entry] of commands) {
     const path = [...prefix, name]
-    if (isGroup(entry)) {
+    if (isFetchGateway(entry)) {
+      const cmd: (typeof result)[number] = { name: path.join(' ') }
+      if (entry.description) cmd.description = entry.description
+      result.push(cmd)
+    } else if (isGroup(entry)) {
       result.push(...collectCommands(entry.commands, path))
     } else {
       const cmd: (typeof result)[number] = { name: path.join(' ') }
@@ -1609,7 +2228,12 @@ function collectSkillCommands(
   const result: Skill.CommandInfo[] = []
   for (const [name, entry] of commands) {
     const path = [...prefix, name]
-    if (isGroup(entry)) {
+    if (isFetchGateway(entry)) {
+      const cmd: Skill.CommandInfo = { 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))
     } else {
@@ -1809,17 +2433,22 @@ type CommandDefinition<
     agent: boolean
     /** Positional arguments. */
     args: InferOutput<args>
-    /** The CLI name. */
-    name: string
     /** Parsed environment variables. */
     env: InferOutput<env>
     /** Return an error result with optional CTAs. */
     error: (options: {
       code: string
       cta?: CtaBlock | undefined
+      exitCode?: number | undefined
       message: string
       retryable?: boolean | undefined
     }) => never
+    /** The resolved output format (e.g. `'toon'`, `'json'`, `'jsonl'`). */
+    format: Formatter.Format
+    /** Whether the user explicitly passed `--format` or `--json`. */
+    formatExplicit: boolean
+    /** The CLI name. */
+    name: string
     /** Return a success result with optional metadata (e.g. CTAs). */
     ok: (data: InferReturn<output>, meta?: { cta?: CtaBlock | undefined }) => never
     options: InferOutput<options>