incur 0.1.16 → 0.2.0

package/src/Fetch.test.ts

@@ -0,0 +1,274 @@
+import { describe, expect, test } from 'vitest'
+
+import { app } from '../test/fixtures/hono-api.js'
+import * as Fetch from './Fetch.js'
+
+describe('parseArgv', () => {
+  test('bare tokens → path segments', () => {
+    const input = Fetch.parseArgv(['users', 'list'])
+    expect(input.path).toBe('/users/list')
+  })
+
+  test('empty argv → root path', () => {
+    const input = Fetch.parseArgv([])
+    expect(input.path).toBe('/')
+  })
+
+  test('single token', () => {
+    const input = Fetch.parseArgv(['health'])
+    expect(input.path).toBe('/health')
+  })
+
+  test('default method is GET', () => {
+    const input = Fetch.parseArgv(['users'])
+    expect(input.method).toBe('GET')
+  })
+
+  test('-X sets method', () => {
+    const input = Fetch.parseArgv(['users', '-X', 'POST'])
+    expect(input.method).toBe('POST')
+  })
+
+  test('--method sets method', () => {
+    const input = Fetch.parseArgv(['users', '--method', 'DELETE'])
+    expect(input.method).toBe('DELETE')
+  })
+
+  test('default POST when body present', () => {
+    const input = Fetch.parseArgv(['users', '--body', '{"name":"Eve"}'])
+    expect(input.method).toBe('POST')
+  })
+
+  test('-d sets body', () => {
+    const input = Fetch.parseArgv(['users', '-d', '{"name":"Bob"}'])
+    expect(input.body).toBe('{"name":"Bob"}')
+    expect(input.method).toBe('POST')
+  })
+
+  test('--data sets body', () => {
+    const input = Fetch.parseArgv(['users', '--data', '{"x":1}'])
+    expect(input.body).toBe('{"x":1}')
+  })
+
+  test('explicit method overrides body default', () => {
+    const input = Fetch.parseArgv(['users', '-X', 'PUT', '-d', '{"name":"Bob"}'])
+    expect(input.method).toBe('PUT')
+  })
+
+  test('-H sets header', () => {
+    const input = Fetch.parseArgv(['users', '-H', 'X-Api-Key: secret'])
+    expect(input.headers.get('X-Api-Key')).toBe('secret')
+  })
+
+  test('--header sets header', () => {
+    const input = Fetch.parseArgv(['users', '--header', 'Authorization: Bearer tok'])
+    expect(input.headers.get('Authorization')).toBe('Bearer tok')
+  })
+
+  test('multiple headers', () => {
+    const input = Fetch.parseArgv([
+      'users',
+      '-H',
+      'X-A: 1',
+      '-H',
+      'X-B: 2',
+    ])
+    expect(input.headers.get('X-A')).toBe('1')
+    expect(input.headers.get('X-B')).toBe('2')
+  })
+
+  test('unknown --key value → query params', () => {
+    const input = Fetch.parseArgv(['users', '--limit', '5', '--sort', 'name'])
+    expect(input.query.get('limit')).toBe('5')
+    expect(input.query.get('sort')).toBe('name')
+  })
+
+  test('--key=value → query params', () => {
+    const input = Fetch.parseArgv(['users', '--limit=5'])
+    expect(input.query.get('limit')).toBe('5')
+  })
+
+  test('mixed tokens, flags, and query params', () => {
+    const input = Fetch.parseArgv([
+      'users',
+      '42',
+      '--limit',
+      '5',
+      '-X',
+      'POST',
+      '-d',
+      '{"x":1}',
+      '-H',
+      'Auth: tok',
+    ])
+    expect(input.path).toBe('/users/42')
+    expect(input.method).toBe('POST')
+    expect(input.body).toBe('{"x":1}')
+    expect(input.query.get('limit')).toBe('5')
+    expect(input.headers.get('Auth')).toBe('tok')
+  })
+})
+
+describe('buildRequest', () => {
+  test('builds GET request with path', () => {
+    const req = Fetch.buildRequest(Fetch.parseArgv(['users']))
+    expect(req.method).toBe('GET')
+    expect(new URL(req.url).pathname).toBe('/users')
+  })
+
+  test('builds request with query params', () => {
+    const req = Fetch.buildRequest(Fetch.parseArgv(['users', '--limit', '5']))
+    const url = new URL(req.url)
+    expect(url.searchParams.get('limit')).toBe('5')
+  })
+
+  test('builds POST request with body', () => {
+    const req = Fetch.buildRequest(
+      Fetch.parseArgv(['users', '-X', 'POST', '-d', '{"name":"Bob"}']),
+    )
+    expect(req.method).toBe('POST')
+  })
+
+  test('builds request with headers', () => {
+    const req = Fetch.buildRequest(
+      Fetch.parseArgv(['users', '-H', 'X-Api-Key: secret']),
+    )
+    expect(req.headers.get('X-Api-Key')).toBe('secret')
+  })
+})
+
+describe('parseResponse', () => {
+  test('parses JSON response', async () => {
+    const res = new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    })
+    const output = await Fetch.parseResponse(res)
+    expect(output.ok).toBe(true)
+    expect(output.status).toBe(200)
+    expect(output.data).toEqual({ ok: true })
+  })
+
+  test('parses text response', async () => {
+    const res = new Response('hello world', { status: 200 })
+    const output = await Fetch.parseResponse(res)
+    expect(output.data).toBe('hello world')
+  })
+
+  test('error status → ok: false', async () => {
+    const res = new Response(JSON.stringify({ message: 'not found' }), {
+      status: 404,
+      headers: { 'content-type': 'application/json' },
+    })
+    const output = await Fetch.parseResponse(res)
+    expect(output.ok).toBe(false)
+    expect(output.status).toBe(404)
+    expect(output.data).toEqual({ message: 'not found' })
+  })
+})
+
+describe('round-trip with Hono', () => {
+  test('GET /users', async () => {
+    const input = Fetch.parseArgv(['users'])
+    const req = Fetch.buildRequest(input)
+    const res = await app.fetch(req)
+    const output = await Fetch.parseResponse(res)
+    expect(output.ok).toBe(true)
+    expect(output.data).toEqual({ users: [{ id: 1, name: 'Alice' }], limit: 10 })
+  })
+
+  test('GET /users?limit=5', async () => {
+    const input = Fetch.parseArgv(['users', '--limit', '5'])
+    const req = Fetch.buildRequest(input)
+    const res = await app.fetch(req)
+    const output = await Fetch.parseResponse(res)
+    expect(output.ok).toBe(true)
+    expect(output.data).toEqual({ users: [{ id: 1, name: 'Alice' }], limit: 5 })
+  })
+
+  test('GET /users/:id', async () => {
+    const input = Fetch.parseArgv(['users', '42'])
+    const req = Fetch.buildRequest(input)
+    const res = await app.fetch(req)
+    const output = await Fetch.parseResponse(res)
+    expect(output.ok).toBe(true)
+    expect(output.data).toEqual({ id: 42, name: 'Alice' })
+  })
+
+  test('POST /users with body', async () => {
+    const input = Fetch.parseArgv(['users', '-X', 'POST', '-d', '{"name":"Bob"}'])
+    const req = Fetch.buildRequest(input)
+    const res = await app.fetch(req)
+    const output = await Fetch.parseResponse(res)
+    expect(output.ok).toBe(true)
+    expect(output.status).toBe(201)
+    expect(output.data).toEqual({ created: true, name: 'Bob' })
+  })
+
+  test('POST /users with implicit method', async () => {
+    const input = Fetch.parseArgv(['users', '--body', '{"name":"Eve"}'])
+    const req = Fetch.buildRequest(input)
+    const res = await app.fetch(req)
+    const output = await Fetch.parseResponse(res)
+    expect(output.ok).toBe(true)
+    expect(output.data).toEqual({ created: true, name: 'Eve' })
+  })
+
+  test('DELETE /users/:id', async () => {
+    const input = Fetch.parseArgv(['users', '1', '--method', 'DELETE'])
+    const req = Fetch.buildRequest(input)
+    const res = await app.fetch(req)
+    const output = await Fetch.parseResponse(res)
+    expect(output.ok).toBe(true)
+    expect(output.data).toEqual({ deleted: true, id: 1 })
+  })
+
+  test('GET /health', async () => {
+    const input = Fetch.parseArgv(['health'])
+    const req = Fetch.buildRequest(input)
+    const res = await app.fetch(req)
+    const output = await Fetch.parseResponse(res)
+    expect(output.ok).toBe(true)
+    expect(output.data).toEqual({ ok: true })
+  })
+
+  test('GET /error → 404', async () => {
+    const input = Fetch.parseArgv(['error'])
+    const req = Fetch.buildRequest(input)
+    const res = await app.fetch(req)
+    const output = await Fetch.parseResponse(res)
+    expect(output.ok).toBe(false)
+    expect(output.status).toBe(404)
+    expect(output.data).toEqual({ message: 'not found' })
+  })
+
+  test('GET /text → plain text', async () => {
+    const input = Fetch.parseArgv(['text'])
+    const req = Fetch.buildRequest(input)
+    const res = await app.fetch(req)
+    const output = await Fetch.parseResponse(res)
+    expect(output.ok).toBe(true)
+    expect(output.data).toBe('hello world')
+  })
+
+  test('custom headers pass through', async () => {
+    const input = Fetch.parseArgv(['users', '-H', 'X-Custom: hello'])
+    const req = Fetch.buildRequest(input)
+    expect(req.headers.get('X-Custom')).toBe('hello')
+    const res = await app.fetch(req)
+    const output = await Fetch.parseResponse(res)
+    expect(output.ok).toBe(true)
+  })
+
+  test('streaming NDJSON response', async () => {
+    const input = Fetch.parseArgv(['stream'])
+    const req = Fetch.buildRequest(input)
+    const res = await app.fetch(req)
+    expect(Fetch.isStreamingResponse(res)).toBe(true)
+    const chunks: unknown[] = []
+    for await (const chunk of Fetch.parseStreamingResponse(res)) {
+      chunks.push(chunk)
+    }
+    expect(chunks).toEqual([{ progress: 1 }, { progress: 2 }])
+  })
+})

package/src/Fetch.ts

@@ -0,0 +1,170 @@
+/** Structured input parsed from curl-style argv. */
+export type FetchInput = {
+  body: string | undefined
+  headers: Headers
+  method: string
+  path: string
+  query: URLSearchParams
+}
+
+/** Structured output from a fetch Response. */
+export type FetchOutput = {
+  data: unknown
+  headers: Headers
+  ok: boolean
+  status: number
+}
+
+/** Reserved flags consumed by the fetch gateway (not forwarded as query params). */
+const reservedFlags = new Set(['method', 'body', 'data', 'header'])
+const reservedShort: Record<string, string> = { X: 'method', d: 'data', H: 'header' }
+
+/** Parses curl-style argv into a structured fetch input. */
+export function parseArgv(argv: string[]): FetchInput {
+  const segments: string[] = []
+  const headers = new Headers()
+  const query = new URLSearchParams()
+  let method: string | undefined
+  let body: string | undefined
+
+  let i = 0
+  while (i < argv.length) {
+    const token = argv[i]!
+
+    if (token.startsWith('--')) {
+      const eqIdx = token.indexOf('=')
+      if (eqIdx !== -1) {
+        // --key=value
+        const key = token.slice(2, eqIdx)
+        const value = token.slice(eqIdx + 1)
+        if (reservedFlags.has(key)) handleReserved(key, value)
+        else query.set(key, value)
+        i++
+      } else {
+        const key = token.slice(2)
+        const value = argv[i + 1]
+        if (reservedFlags.has(key)) {
+          handleReserved(key, value!)
+          i += 2
+        } else {
+          query.set(key, value!)
+          i += 2
+        }
+      }
+    } else if (token.startsWith('-') && token.length === 2) {
+      const short = token[1]!
+      const mapped = reservedShort[short]
+      const value = argv[i + 1]!
+      if (mapped) {
+        handleReserved(mapped, value)
+        i += 2
+      } else {
+        // Unknown short flag — skip (shouldn't happen in fetch context)
+        i += 2
+      }
+    } else {
+      segments.push(token)
+      i++
+    }
+  }
+
+  function handleReserved(key: string, value: string) {
+    if (key === 'method') method = value.toUpperCase()
+    else if (key === 'body' || key === 'data') body = value
+    else if (key === 'header') {
+      const colonIdx = value.indexOf(':')
+      if (colonIdx !== -1) {
+        const name = value.slice(0, colonIdx).trim()
+        const val = value.slice(colonIdx + 1).trim()
+        headers.set(name, val)
+      }
+    }
+  }
+
+  return {
+    path: segments.length > 0 ? `/${segments.join('/')}` : '/',
+    method: method ?? (body !== undefined ? 'POST' : 'GET'),
+    headers,
+    body,
+    query,
+  }
+}
+
+/** Constructs a standard Request from a FetchInput. */
+export function buildRequest(input: FetchInput): Request {
+  const url = new URL(input.path, 'http://localhost')
+  input.query.forEach((value, key) => url.searchParams.set(key, value))
+
+  const init: RequestInit = {
+    method: input.method,
+    headers: input.headers,
+  }
+
+  if (input.body !== undefined) {
+    init.body = input.body
+    if (!input.headers.has('content-type'))
+      input.headers.set('content-type', 'application/json')
+  }
+
+  return new Request(url.toString(), init)
+}
+
+/** Returns true if the response body is a stream that should be consumed incrementally. */
+export function isStreamingResponse(response: Response): boolean {
+  return response.body !== null && response.headers.get('content-type') === 'application/x-ndjson'
+}
+
+/** Parses a streaming response body as an async generator of parsed NDJSON chunks. */
+export async function* parseStreamingResponse(
+  response: Response,
+): AsyncGenerator<unknown, void, unknown> {
+  const reader = response.body!.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+
+  while (true) {
+    const { value, done } = await reader.read()
+    if (done) break
+    buffer += decoder.decode(value, { stream: true })
+
+    let newlineIdx: number
+    while ((newlineIdx = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, newlineIdx).trim()
+      buffer = buffer.slice(newlineIdx + 1)
+      if (line.length === 0) continue
+      try {
+        yield JSON.parse(line)
+      } catch {
+        yield line
+      }
+    }
+  }
+
+  // flush remaining buffer
+  const remaining = buffer.trim()
+  if (remaining.length > 0) {
+    try {
+      yield JSON.parse(remaining)
+    } catch {
+      yield remaining
+    }
+  }
+}
+
+/** Parses a fetch Response into structured output. */
+export async function parseResponse(response: Response): Promise<FetchOutput> {
+  const text = await response.text()
+  let data: unknown
+  try {
+    data = JSON.parse(text)
+  } catch {
+    data = text
+  }
+
+  return {
+    ok: response.ok,
+    status: response.status,
+    data,
+    headers: response.headers,
+  }
+}

package/src/Help.test.ts

@@ -133,4 +133,52 @@ describe('formatRoot', () => {
         --verbose                           Show full output envelope"
     `)
   })
+
+  test('formatRoot shows aliases', () => {
+    const result = Help.formatRoot('my-tool', {
+      description: 'A test CLI',
+      version: '1.0.0',
+      aliases: ['mt', 'myt'],
+      commands: [{ name: 'fetch', description: 'Fetch a URL' }],
+    })
+    expect(result).toMatchInlineSnapshot(`
+      "my-tool@1.0.0 — A test CLI
+      Aliases: mt, myt
+
+      Usage: my-tool <command>
+
+      Commands:
+        fetch  Fetch a URL
+
+      Global Options:
+        --format <toon|json|yaml|md|jsonl>  Output format
+        --help                              Show help
+        --llms                              Print LLM-readable manifest
+        --verbose                           Show full output envelope"
+    `)
+  })
+
+  test('formatCommand shows aliases', () => {
+    const result = Help.formatCommand('my-tool', {
+      description: 'A test CLI',
+      version: '1.0.0',
+      aliases: ['mt', 'myt'],
+      args: z.object({ url: z.string().describe('URL to fetch') }),
+    })
+    expect(result).toMatchInlineSnapshot(`
+      "my-tool@1.0.0 — A test CLI
+      Aliases: mt, myt
+
+      Usage: my-tool <url>
+
+      Arguments:
+        url  URL to fetch
+
+      Global Options:
+        --format <toon|json|yaml|md|jsonl>  Output format
+        --help                              Show help
+        --llms                              Print LLM-readable manifest
+        --verbose                           Show full output envelope"
+    `)
+  })
 })

package/src/Help.ts

@@ -2,12 +2,13 @@ import { z } from 'zod'
 
 /** Formats help text for a router CLI or command group. */
 export function formatRoot(name: string, options: formatRoot.Options = {}): string {
-  const { description, version, commands = [], root = false } = options
+  const { aliases, description, version, commands = [], root = false } = options
   const lines: string[] = []
 
   // Header
-  lines.push(description ? `${name} \u2014 ${description}` : name)
-  if (version) lines.push(`v${version}`)
+  const title = version ? `${name}@${version}` : name
+  lines.push(description ? `${title} \u2014 ${description}` : title)
+  if (aliases?.length) lines.push(`Aliases: ${aliases.join(', ')}`)
   lines.push('')
 
   // Synopsis
@@ -33,6 +34,8 @@ export function formatRoot(name: string, options: formatRoot.Options = {}): stri
 
 export declare namespace formatRoot {
   type Options = {
+    /** Alternative binary names for this CLI. */
+    aliases?: string[] | undefined
     /** Commands to list. */
     commands?: { name: string; description?: string | undefined }[] | undefined
     /** A short description of the CLI or group. */
@@ -48,6 +51,8 @@ export declare namespace formatCommand {
   type Options = {
     /** Map of option names to single-char aliases. */
     alias?: Record<string, string> | undefined
+    /** Alternative binary names for this CLI. */
+    aliases?: string[] | undefined
     /** Zod schema for positional arguments. */
     args?: z.ZodObject<any> | undefined
     /** Subcommands to list (for CLIs with both a root handler and subcommands). */
@@ -84,6 +89,7 @@ export declare namespace formatCommand {
 export function formatCommand(name: string, options: formatCommand.Options = {}): string {
   const {
     alias,
+    aliases,
     description,
     version,
     args,
@@ -97,8 +103,9 @@ export function formatCommand(name: string, options: formatCommand.Options = {})
   const lines: string[] = []
 
   // Header
-  lines.push(description ? `${name} \u2014 ${description}` : name)
-  if (version) lines.push(`v${version}`)
+  const title = version ? `${name}@${version}` : name
+  lines.push(description ? `${title} \u2014 ${description}` : title)
+  if (aliases?.length) lines.push(`Aliases: ${aliases.join(', ')}`)
   lines.push('')
 
   // Synopsis
@@ -163,7 +170,7 @@ export function formatCommand(name: string, options: formatCommand.Options = {})
     for (const ex of examples) {
       const cmd = ex.command ? `$ ${name} ${ex.command}` : `$ ${name}`
       if (ex.description)
-        lines.push(`  ${cmd}${' '.repeat(maxLen - cmd.length)}  ${ex.description}`)
+        lines.push(`  ${cmd}${' '.repeat(maxLen - cmd.length)}  # ${ex.description}`)
       else lines.push(`  ${cmd}`)
     }
   }