incur 0.1.16 → 0.2.0

package/src/Cli.ts

@@ -3,6 +3,8 @@ import type { z } from 'zod'
 import * as Completions from './Completions.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 +58,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
@@ -174,9 +181,11 @@ 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 cli: Cli = {
     name,
@@ -186,6 +195,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
       }
@@ -209,8 +242,10 @@ export function create(
     },
 
     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,
         description: def.description,
         envSchema: def.env,
         format: def.format,
@@ -218,6 +253,7 @@ export function create(
         middlewares,
         outputPolicy: def.outputPolicy,
         rootCommand: rootDef,
+        rootFetch,
         sync: def.sync,
         vars: def.vars,
         version: def.version,
@@ -250,6 +286,8 @@ export declare namespace create {
     alias?: options extends z.ZodObject<any>
       ? Partial<Record<keyof z.output<options>, string>>
       : Record<string, string> | undefined
+    /** Alternative binary names for this CLI (e.g. shorter aliases in package.json `bin`). Shell completions are registered for all names. */
+    aliases?: string[] | undefined
     /** Zod schema for positional arguments. */
     args?: args | undefined
     /** A short description of what the CLI does. */
@@ -258,6 +296,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. */
@@ -379,8 +419,9 @@ async function serveImpl(
     const sepIdx = argv.indexOf('--')
     const words = sepIdx !== -1 ? argv.slice(sepIdx + 1) : argv
     if (words.length === 0) {
-      // Registration mode: print shell hook script
-      stdout(Completions.register(completeShell, name))
+      // Registration mode: print shell hook script for primary name + aliases
+      const names = [name, ...(options.aliases ?? [])]
+      stdout(names.map((n) => Completions.register(completeShell, n)).join('\n'))
     } else {
       const index = Number(process.env._COMPLETE_INDEX ?? words.length - 1)
       const candidates = Completions.complete(commands, options.rootCommand, words, index)
@@ -501,7 +542,8 @@ async function serveImpl(
       exit(1)
       return
     }
-    writeln(Completions.register(shell as Completions.Shell, name))
+    const names = [name, ...(options.aliases ?? [])]
+    writeln(names.map((n) => Completions.register(shell as Completions.Shell, n)).join('\n'))
     return
   }
 
@@ -668,6 +710,7 @@ async function serveImpl(
       writeln(
         Help.formatCommand(name, {
           alias: cmd.alias as Record<string, string> | undefined,
+          aliases: options.aliases,
           description: cmd.description ?? options.description,
           version: options.version,
           args: cmd.args,
@@ -683,11 +726,12 @@ 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, {
+          aliases: options.aliases,
           description: options.description,
           version: options.version,
           commands: collectHelpCommands(commands),
@@ -701,7 +745,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) {
@@ -717,6 +770,7 @@ async function serveImpl(
         writeln(
           Help.formatCommand(name, {
             alias: cmd.alias as Record<string, string> | undefined,
+            aliases: options.aliases,
             description: cmd.description ?? options.description,
             version: options.version,
             args: cmd.args,
@@ -733,6 +787,7 @@ async function serveImpl(
       } else {
         writeln(
           Help.formatRoot(helpName, {
+            aliases: isRoot ? options.aliases : undefined,
             description: helpDesc,
             version: isRoot ? options.version : undefined,
             commands: collectHelpCommands(helpCmds),
@@ -740,7 +795,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 =
@@ -749,16 +805,17 @@ async function serveImpl(
           : undefined
       writeln(
         Help.formatCommand(commandName, {
-          alias: resolved.command.alias as Record<string, string> | undefined,
-          description: resolved.command.description,
+          alias: cmd.alias as Record<string, string> | undefined,
+          aliases: isRootCmd ? options.aliases : undefined,
+          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,
         }),
@@ -780,14 +837,16 @@ 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 =
@@ -842,6 +901,116 @@ 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; 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,
+          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 cta = formatCtaBlock(name, result.cta)
+          write({
+            ok: false,
+            error: { code: result.code, message: result.message, ...(result.retryable !== undefined ? { retryable: result.retryable } : undefined) },
+            meta: { command: path, duration: `${Math.round(performance.now() - start)}ms`, ...(cta ? { cta } : undefined) },
+          })
+          exit(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(1)
+    }
+    return
+  }
+
   const { command, path, rest } = effective
 
   // Collect middleware: root CLI + groups traversed + per-command
@@ -1080,6 +1249,13 @@ function resolveCommand(
       path: string
       rest: string[]
     }
+  | {
+      fetchGateway: InternalFetchGateway
+      middlewares: MiddlewareHandler[]
+      outputPolicy?: OutputPolicy | undefined
+      path: string
+      rest: string[]
+    }
   | {
       help: true
       path: string
@@ -1097,6 +1273,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)
@@ -1117,6 +1305,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
@@ -1132,6 +1331,8 @@ function resolveCommand(
 /** @internal Options for serveImpl, extending public serve.Options with internal metadata. */
 declare namespace serveImpl {
   type Options = serve.Options & {
+    /** Alternative binary names for this CLI. */
+    aliases?: string[] | undefined
     description?: string | undefined
     /** CLI-level env schema. Parsed before middleware runs. */
     envSchema?: z.ZodObject<any> | undefined
@@ -1149,6 +1350,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
@@ -1200,24 +1403,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
@@ -1227,11 +1451,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>>()
 
@@ -1558,7 +1796,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(' ') }
@@ -1597,7 +1839,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 {

package/src/Completions.test.ts

@@ -324,6 +324,55 @@ describe('completions built-in command', () => {
   })
 })
 
+describe('aliases', () => {
+  function makeAliasedCli() {
+    const cli = Cli.create('my-tool', {
+      version: '1.0.0',
+      description: 'A test CLI',
+      aliases: ['mt', 'myt'],
+    })
+    cli.command('fetch', {
+      description: 'Fetch a URL',
+      run() {
+        return { ok: true }
+      },
+    })
+    return cli
+  }
+
+  test('completions fish outputs registration for all names', async () => {
+    const cli = makeAliasedCli()
+    const output = await serve(cli, ['completions', 'fish'])
+    expect(output).toContain('--command my-tool')
+    expect(output).toContain('--command mt')
+    expect(output).toContain('--command myt')
+  })
+
+  test('completions bash outputs registration for all names', async () => {
+    const cli = makeAliasedCli()
+    const output = await serve(cli, ['completions', 'bash'])
+    expect(output).toContain('_incur_complete_my_tool()')
+    expect(output).toContain('_incur_complete_mt()')
+    expect(output).toContain('_incur_complete_myt()')
+  })
+
+  test('completions zsh outputs registration for all names', async () => {
+    const cli = makeAliasedCli()
+    const output = await serve(cli, ['completions', 'zsh'])
+    expect(output).toContain('#compdef my-tool')
+    expect(output).toContain('compdef _incur_complete_mt mt')
+    expect(output).toContain('compdef _incur_complete_myt myt')
+  })
+
+  test('COMPLETE env var registers all names', async () => {
+    const cli = makeAliasedCli()
+    const output = await serve(cli, [], { COMPLETE: 'fish' })
+    expect(output).toContain('--command my-tool')
+    expect(output).toContain('--command mt')
+    expect(output).toContain('--command myt')
+  })
+})
+
 describe('serve integration', () => {
   test('COMPLETE=bash with no words outputs registration script', async () => {
     const cli = makeCli()