incur 0.1.17 → 0.2.1

package/src/Filter.ts

@@ -0,0 +1,139 @@
+/** A single segment in a filter path: either a string key or an array slice. */
+export type Segment = { key: string } | { start: number; end: number }
+
+/** A filter path is an ordered list of segments to traverse. */
+export type FilterPath = Segment[]
+
+/** Parses a filter expression string into structured filter paths. */
+export function parse(expression: string): FilterPath[] {
+  const paths: FilterPath[] = []
+  const tokens: string[] = []
+  let current = ''
+  let depth = 0
+
+  // Split on commas, but commas inside [...] are part of a slice
+  for (let i = 0; i < expression.length; i++) {
+    const ch = expression[i]!
+    if (ch === '[') depth++
+    else if (ch === ']') depth--
+
+    if (ch === ',' && depth === 0) {
+      tokens.push(current)
+      current = ''
+    } else current += ch
+  }
+  if (current) tokens.push(current)
+
+  for (const token of tokens) {
+    const path: FilterPath = []
+    let remaining = token
+
+    while (remaining.length > 0) {
+      const bracketIdx = remaining.indexOf('[')
+
+      if (bracketIdx === -1) {
+        // No more slices — split remaining by dots
+        for (const part of remaining.split('.')) if (part) path.push({ key: part })
+        break
+      }
+
+      // Parse dot-separated keys before the bracket
+      const before = remaining.slice(0, bracketIdx)
+      for (const part of before.split('.')) if (part) path.push({ key: part })
+
+      // Parse the slice [start,end]
+      const closeBracket = remaining.indexOf(']', bracketIdx)
+      const inner = remaining.slice(bracketIdx + 1, closeBracket)
+      const [startStr, endStr] = inner.split(',')
+      path.push({ start: Number(startStr), end: Number(endStr) })
+
+      remaining = remaining.slice(closeBracket + 1)
+      if (remaining.startsWith('.')) remaining = remaining.slice(1)
+    }
+
+    paths.push(path)
+  }
+
+  return paths
+}
+
+/** Applies parsed filter paths to a data value, returning a filtered copy. */
+export function apply(data: unknown, paths: FilterPath[]): unknown {
+  if (paths.length === 0) return data
+
+  // Single key selecting a scalar → return the scalar directly
+  if (paths.length === 1 && paths[0]!.length === 1 && 'key' in paths[0]![0]!) {
+    const key = paths[0]![0]!.key
+    if (Array.isArray(data)) return data.map((item) => apply(item, paths))
+    if (typeof data === 'object' && data !== null) {
+      const val = (data as Record<string, unknown>)[key]
+      if (typeof val !== 'object' || val === null) return val
+      return { [key]: val }
+    }
+    return undefined
+  }
+
+  if (Array.isArray(data)) return data.map((item) => apply(item, paths))
+
+  const result: Record<string, unknown> = {}
+  for (const path of paths) merge(result, data, path, 0)
+  return result
+}
+
+function resolve(data: unknown, segments: Segment[], index: number): unknown {
+  if (index >= segments.length) return data
+  const segment = segments[index]!
+
+  if ('key' in segment) {
+    if (typeof data !== 'object' || data === null) return undefined
+    const val = (data as Record<string, unknown>)[segment.key]
+    return resolve(val, segments, index + 1)
+  }
+
+  // slice segment
+  if (!Array.isArray(data)) return undefined
+  const sliced = data.slice(segment.start, segment.end)
+  if (index + 1 >= segments.length) return sliced
+  return sliced.map((item) => resolve(item, segments, index + 1))
+}
+
+function merge(target: Record<string, unknown>, data: unknown, segments: Segment[], index: number): void {
+  if (index >= segments.length || typeof data !== 'object' || data === null) return
+  const segment = segments[index]!
+
+  if ('key' in segment) {
+    const val = (data as Record<string, unknown>)[segment.key]
+    if (val === undefined) return
+
+    if (index + 1 >= segments.length) {
+      target[segment.key] = val
+      return
+    }
+
+    const next = segments[index + 1]!
+    if ('start' in next) {
+      // Next segment is a slice
+      if (!Array.isArray(val)) return
+      const sliced = val.slice(next.start, next.end)
+      if (index + 2 >= segments.length) {
+        target[segment.key] = sliced
+        return
+      }
+      target[segment.key] = sliced.map((item) => {
+        const sub: Record<string, unknown> = {}
+        merge(sub, item, segments, index + 2)
+        return sub
+      })
+      return
+    }
+
+    // Next segment is a key — recurse into nested object
+    if (typeof val !== 'object' || val === null) return
+    if (!target[segment.key] || typeof target[segment.key] !== 'object')
+      target[segment.key] = {}
+    merge(target[segment.key] as Record<string, unknown>, val, segments, index + 1)
+    return
+  }
+
+  // slice at root level — shouldn't happen in merge (merge starts from object keys)
+}

package/src/Help.test.ts

@@ -25,9 +25,11 @@ describe('formatCommand', () => {
         --limit <number>  Max PRs to return (default: 30)
 
       Global Options:
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a command
         --verbose                           Show full output envelope"
     `)
   })
@@ -42,9 +44,11 @@ describe('formatCommand', () => {
       Usage: tool ping
 
       Global Options:
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a command
         --verbose                           Show full output envelope"
     `)
   })
@@ -66,9 +70,11 @@ describe('formatCommand', () => {
         title  Title
 
       Global Options:
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a command
         --verbose                           Show full output envelope"
     `)
   })
@@ -107,9 +113,11 @@ describe('formatRoot', () => {
         issue list  List issues
 
       Global Options:
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a command
         --verbose                           Show full output envelope"
     `)
   })
@@ -127,9 +135,11 @@ describe('formatRoot', () => {
         ping  Health check
 
       Global Options:
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a command
         --verbose                           Show full output envelope"
     `)
   })
@@ -151,9 +161,11 @@ describe('formatRoot', () => {
         fetch  Fetch a URL
 
       Global Options:
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a command
         --verbose                           Show full output envelope"
     `)
   })
@@ -175,9 +187,11 @@ describe('formatRoot', () => {
         url  URL to fetch
 
       Global Options:
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a command
         --verbose                           Show full output envelope"
     `)
   })

package/src/Help.ts

@@ -326,10 +326,12 @@ function globalOptionsLines(root = false): string[] {
   }
 
   const flags = [
+    { flag: '--filter-output <keys>', desc: 'Filter output by key paths (e.g. foo,bar.baz,a[0,3])' },
     { flag: '--format <toon|json|yaml|md|jsonl>', desc: 'Output format' },
     { flag: '--help', desc: 'Show help' },
     { flag: '--llms', desc: 'Print LLM-readable manifest' },
     ...(root ? [{ flag: '--mcp', desc: 'Start as MCP stdio server' }] : []),
+    { flag: '--schema', desc: 'Show JSON Schema for a command' },
     { flag: '--verbose', desc: 'Show full output envelope' },
     ...(root ? [{ flag: '--version', desc: 'Show version' }] : []),
   ]

package/src/Mcp.ts

@@ -52,7 +52,7 @@ export declare namespace serve {
 }
 
 /** @internal Executes a tool call and returns a CallToolResult. */
-async function callTool(
+export async function callTool(
   tool: ToolEntry,
   params: Record<string, unknown>,
   extra?: {
@@ -135,7 +135,7 @@ function isAsyncGenerator(value: unknown): value is AsyncGenerator<unknown, unkn
 }
 
 /** @internal A resolved tool entry from the command tree. */
-type ToolEntry = {
+export type ToolEntry = {
   name: string
   description?: string | undefined
   inputSchema: { type: 'object'; properties: Record<string, unknown>; required?: string[] }
@@ -143,7 +143,7 @@ type ToolEntry = {
 }
 
 /** @internal Recursively collects leaf commands as tool entries. */
-function collectTools(commands: Map<string, any>, prefix: string[]): ToolEntry[] {
+export function collectTools(commands: Map<string, any>, prefix: string[]): ToolEntry[] {
   const result: ToolEntry[] = []
   for (const [name, entry] of commands) {
     const path = [...prefix, name]

package/src/Openapi.test.ts

@@ -0,0 +1,320 @@
+import { describe, expect, test } from 'vitest'
+
+import * as Cli from './Cli.js'
+import * as Openapi from './Openapi.js'
+import { app } from '../test/fixtures/hono-api.js'
+import { app as prefixedApp } from '../test/fixtures/hono-api-prefixed.js'
+import { spec } from '../test/fixtures/openapi-spec.js'
+import { app as openapiApp, spec as openapiSpec } from '../test/fixtures/hono-openapi-app.js'
+
+function serve(cli: { serve: Cli.Cli['serve'] }, argv: string[]) {
+  let output = ''
+  let exitCode: number | undefined
+  return cli
+    .serve(argv, {
+      stdout: (s) => (output += s),
+      exit: (c) => { exitCode = c },
+    })
+    .then(() => ({
+      output,
+      exitCode,
+    }))
+}
+
+function json(output: string) {
+  return JSON.parse(
+    output.replace(/"duration": "[^"]+"/g, '"duration": "<stripped>"'),
+  )
+}
+
+describe('generateCommands', () => {
+  test('generates command entries from spec', async () => {
+    const commands = await Openapi.generateCommands(spec, app.fetch)
+    expect(commands.has('listUsers')).toBe(true)
+    expect(commands.has('createUser')).toBe(true)
+    expect(commands.has('getUser')).toBe(true)
+    expect(commands.has('deleteUser')).toBe(true)
+    expect(commands.has('healthCheck')).toBe(true)
+  })
+
+  test('command has description from summary', async () => {
+    const commands = await Openapi.generateCommands(spec, app.fetch)
+    const cmd = commands.get('listUsers')!
+    expect(cmd.description).toBe('List users')
+  })
+})
+
+describe('cli integration', () => {
+  function createCli() {
+    return Cli.create('test', { description: 'test' })
+      .command('api', { fetch: app.fetch, openapi: spec })
+  }
+
+  test('GET /users via operationId', async () => {
+    const { output } = await serve(createCli(), ['api', 'listUsers'])
+    expect(output).toContain('Alice')
+  })
+
+  test('GET /users?limit=5 via options', async () => {
+    const { output } = await serve(createCli(), [
+      'api', 'listUsers', '--limit', '5', '--format', 'json',
+    ])
+    expect(json(output).limit).toBe(5)
+  })
+
+  test('GET /users/:id via positional arg', async () => {
+    const { output } = await serve(createCli(), ['api', 'getUser', '42'])
+    expect(output).toMatchInlineSnapshot(`
+      "id: 42
+      name: Alice
+      "
+    `)
+  })
+
+  test('POST /users via createUser with body options', async () => {
+    const { output } = await serve(createCli(), ['api', 'createUser', '--name', 'Bob'])
+    expect(output).toMatchInlineSnapshot(`
+      "created: true
+      name: Bob
+      "
+    `)
+  })
+
+  test('DELETE /users/:id via deleteUser', async () => {
+    const { output } = await serve(createCli(), ['api', 'deleteUser', '1'])
+    expect(output).toMatchInlineSnapshot(`
+      "deleted: true
+      id: 1
+      "
+    `)
+  })
+
+  test('GET /health via healthCheck', async () => {
+    const { output } = await serve(createCli(), ['api', 'healthCheck'])
+    expect(output).toMatchInlineSnapshot(`
+      "ok: true
+      "
+    `)
+  })
+
+  test('--help on api shows subcommands', async () => {
+    const { output } = await serve(createCli(), ['api', '--help'])
+    expect(output).toContain('listUsers')
+    expect(output).toContain('createUser')
+    expect(output).toContain('getUser')
+    expect(output).toContain('deleteUser')
+    expect(output).toContain('healthCheck')
+  })
+
+  test('--help on specific command shows typed args/options', async () => {
+    const { output } = await serve(createCli(), ['api', 'getUser', '--help'])
+    expect(output).toContain('id')
+    expect(output).toContain('Get a user by ID')
+  })
+
+  test('--help on createUser shows body options', async () => {
+    const { output } = await serve(createCli(), ['api', 'createUser', '--help'])
+    expect(output).toContain('name')
+    expect(output).toContain('Create a user')
+  })
+
+  test('--format json', async () => {
+    const { output } = await serve(createCli(), ['api', 'healthCheck', '--format', 'json'])
+    expect(json(output)).toEqual({ ok: true })
+  })
+
+  test('--verbose wraps in envelope', async () => {
+    const { output } = await serve(createCli(), [
+      'api', 'healthCheck', '--verbose', '--format', 'json',
+    ])
+    const parsed = json(output)
+    expect(parsed.ok).toBe(true)
+    expect(parsed.data).toEqual({ ok: true })
+    expect(parsed.meta.command).toContain('api')
+  })
+
+  test('missing required path param shows validation error', async () => {
+    const { exitCode } = await serve(createCli(), ['api', 'getUser'])
+    expect(exitCode).toBe(1)
+  })
+})
+
+describe('@hono/zod-openapi integration', () => {
+  function createCli() {
+    return Cli.create('test', { description: 'test' })
+      .command('api', { fetch: openapiApp.fetch, openapi: openapiSpec })
+  }
+
+  test('GET /users via listUsers', async () => {
+    const { output } = await serve(createCli(), ['api', 'listUsers'])
+    expect(output).toContain('Alice')
+  })
+
+  test('GET /users?limit=5', async () => {
+    const { output } = await serve(createCli(), ['api', 'listUsers', '--limit', '5', '--format', 'json'])
+    expect(json(output).limit).toBe(5)
+  })
+
+  test('GET /users/:id via getUser', async () => {
+    const { output } = await serve(createCli(), ['api', 'getUser', '42'])
+    expect(output).toMatchInlineSnapshot(`
+      "id: 42
+      name: Alice
+      "
+    `)
+  })
+
+  test('POST /users via createUser', async () => {
+    const { output } = await serve(createCli(), ['api', 'createUser', '--name', 'Bob'])
+    expect(output).toMatchInlineSnapshot(`
+      "created: true
+      name: Bob
+      "
+    `)
+  })
+
+  test('DELETE /users/:id via deleteUser', async () => {
+    const { output } = await serve(createCli(), ['api', 'deleteUser', '1'])
+    expect(output).toMatchInlineSnapshot(`
+      "deleted: true
+      id: 1
+      "
+    `)
+  })
+
+  test('GET /health via healthCheck', async () => {
+    const { output } = await serve(createCli(), ['api', 'healthCheck'])
+    expect(output).toMatchInlineSnapshot(`
+      "ok: true
+      "
+    `)
+  })
+
+  test('--help shows operationId commands', async () => {
+    const { output } = await serve(createCli(), ['api', '--help'])
+    expect(output).toContain('listUsers')
+    expect(output).toContain('getUser')
+    expect(output).toContain('createUser')
+    expect(output).toContain('deleteUser')
+    expect(output).toContain('healthCheck')
+    expect(output).toContain('updateUser')
+  })
+
+  test('--help on getUser shows path param', async () => {
+    const { output } = await serve(createCli(), ['api', 'getUser', '--help'])
+    expect(output).toContain('id')
+  })
+
+  test('--help on createUser shows body options', async () => {
+    const { output } = await serve(createCli(), ['api', 'createUser', '--help'])
+    expect(output).toContain('name')
+  })
+
+  test('--help on updateUser shows path param and body options', async () => {
+    const { output } = await serve(createCli(), ['api', 'updateUser', '--help'])
+    expect(output).toContain('id')
+    expect(output).toContain('name')
+    expect(output).toContain('Update a user')
+  })
+
+  test('--format json', async () => {
+    const { output } = await serve(createCli(), ['api', 'healthCheck', '--format', 'json'])
+    expect(json(output)).toEqual({ ok: true })
+  })
+
+  test('--verbose wraps in envelope', async () => {
+    const { output } = await serve(createCli(), [
+      'api', 'healthCheck', '--verbose', '--format', 'json',
+    ])
+    const parsed = json(output)
+    expect(parsed.ok).toBe(true)
+    expect(parsed.data).toEqual({ ok: true })
+    expect(parsed.meta.command).toContain('api')
+  })
+
+  test('missing required path param shows validation error', async () => {
+    const { exitCode } = await serve(createCli(), ['api', 'getUser'])
+    expect(exitCode).toBe(1)
+  })
+
+  test('PUT /users/:id with path param + body options', async () => {
+    const { output } = await serve(createCli(), ['api', 'updateUser', '1', '--name', 'Updated'])
+    expect(output).toMatchInlineSnapshot(`
+      "id: 1
+      name: Updated
+      "
+    `)
+  })
+
+  test('PUT /users/:id with optional boolean body option', async () => {
+    const { output } = await serve(createCli(), [
+      'api', 'updateUser', '1', '--name', 'Updated', '--active', 'true', '--format', 'json',
+    ])
+    const parsed = json(output)
+    expect(parsed.id).toBe(1)
+    expect(parsed.name).toBe('Updated')
+    expect(parsed.active).toBe(true)
+  })
+
+  test('query param coercion with zod-openapi generated spec', async () => {
+    const { output } = await serve(createCli(), ['api', 'listUsers', '--limit', '3', '--format', 'json'])
+    expect(json(output).limit).toBe(3)
+  })
+})
+
+describe('basePath', () => {
+  test('fetch gateway prepends basePath to request path', async () => {
+    const cli = Cli.create('test', { description: 'test' })
+      .command('api', { fetch: prefixedApp.fetch, basePath: '/api' })
+    const { output } = await serve(cli, ['api', 'users'])
+    expect(output).toContain('Alice')
+  })
+
+  test('fetch gateway basePath with query params', async () => {
+    const cli = Cli.create('test', { description: 'test' })
+      .command('api', { fetch: prefixedApp.fetch, basePath: '/api' })
+    const { output } = await serve(cli, ['api', 'users', '--limit', '5', '--format', 'json'])
+    expect(json(output).limit).toBe(5)
+  })
+
+  test('fetch gateway basePath with POST', async () => {
+    const cli = Cli.create('test', { description: 'test' })
+      .command('api', { fetch: prefixedApp.fetch, basePath: '/api' })
+    const { output } = await serve(cli, ['api', 'users', '-X', 'POST', '-d', '{"name":"Bob"}'])
+    expect(output).toContain('Bob')
+    expect(output).toContain('created')
+  })
+
+  test('openapi with basePath prepends to spec paths', async () => {
+    const cli = Cli.create('test', { description: 'test' })
+      .command('api', { fetch: prefixedApp.fetch, openapi: spec, basePath: '/api' })
+    const { output } = await serve(cli, ['api', 'listUsers'])
+    expect(output).toContain('Alice')
+  })
+
+  test('openapi basePath with path params', async () => {
+    const cli = Cli.create('test', { description: 'test' })
+      .command('api', { fetch: prefixedApp.fetch, openapi: spec, basePath: '/api' })
+    const { output } = await serve(cli, ['api', 'getUser', '42'])
+    expect(output).toMatchInlineSnapshot(`
+      "id: 42
+      name: Alice
+      "
+    `)
+  })
+
+  test('openapi basePath with body options', async () => {
+    const cli = Cli.create('test', { description: 'test' })
+      .command('api', { fetch: prefixedApp.fetch, openapi: spec, basePath: '/api' })
+    const { output } = await serve(cli, ['api', 'createUser', '--name', 'Bob'])
+    expect(output).toContain('created')
+    expect(output).toContain('Bob')
+  })
+
+  test('openapi basePath with health check', async () => {
+    const cli = Cli.create('test', { description: 'test' })
+      .command('api', { fetch: prefixedApp.fetch, openapi: spec, basePath: '/api' })
+    const { output } = await serve(cli, ['api', 'healthCheck', '--format', 'json'])
+    expect(json(output)).toEqual({ ok: true })
+  })
+})