incur 0.1.17 → 0.2.0

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 })
+  })
+})

package/src/Openapi.ts

@@ -0,0 +1,196 @@
+import { dereference } from '@readme/openapi-parser'
+import { z } from 'zod'
+
+import * as Fetch from './Fetch.js'
+
+/** A minimal OpenAPI 3.x spec shape. Accepts both hand-written specs and generated ones (e.g. from `@hono/zod-openapi`). */
+export type OpenAPISpec = { paths?: {} | undefined }
+
+/** Internal operation shape after casting. */
+type Operation = {
+  description?: string | undefined
+  operationId?: string | undefined
+  parameters?: readonly Parameter[] | undefined
+  requestBody?: RequestBody | undefined
+  responses?: Record<string, unknown> | undefined
+  summary?: string | undefined
+}
+
+type Parameter = {
+  description?: string | undefined
+  in: 'cookie' | 'header' | 'path' | 'query'
+  name: string
+  required?: boolean | undefined
+  schema?: Record<string, unknown> | undefined
+}
+
+type RequestBody = {
+  content?: Record<string, { schema?: Record<string, unknown> | undefined }> | undefined
+  required?: boolean | undefined
+}
+
+/** A fetch handler. */
+type FetchHandler = (req: Request) => Response | Promise<Response>
+
+/** A generated command entry compatible with incur's internal CommandEntry. */
+type GeneratedCommand = {
+  args?: z.ZodObject<any> | undefined
+  description?: string | undefined
+  options?: z.ZodObject<any> | undefined
+  run: (context: any) => any
+}
+
+/** Generates incur command entries from an OpenAPI spec. Resolves all `$ref` pointers. */
+export async function generateCommands(
+  spec: OpenAPISpec,
+  fetch: FetchHandler,
+  options: { basePath?: string | undefined } = {},
+): Promise<Map<string, GeneratedCommand>> {
+  const resolved = await dereference(structuredClone(spec) as any) as unknown as OpenAPISpec
+  const commands = new Map<string, GeneratedCommand>()
+  const paths = (resolved.paths ?? {}) as Record<string, Record<string, unknown>>
+
+  for (const [path, methods] of Object.entries(paths)) {
+    for (const [method, operation] of Object.entries(methods)) {
+      if (method.startsWith('x-')) continue
+      const op = operation as Operation
+      const name = op.operationId ?? `${method}_${path.replace(/[/{}]/g, '_')}`
+      const httpMethod = method.toUpperCase()
+
+      const pathParams = (op.parameters ?? []).filter((p) => p.in === 'path')
+      const queryParams = (op.parameters ?? []).filter((p) => p.in === 'query')
+
+      const bodySchema = op.requestBody?.content?.['application/json']?.schema
+      const bodyProps = (bodySchema?.properties ?? {}) as Record<string, Record<string, unknown>>
+      const bodyRequired = new Set((bodySchema?.required as string[]) ?? [])
+
+      // Build args Zod schema from path params
+      let argsSchema: z.ZodObject<any> | undefined
+      if (pathParams.length > 0) {
+        const shape: Record<string, z.ZodType> = {}
+        for (const p of pathParams) {
+          let zodType = p.schema ? toZod(p.schema) : z.string()
+          if (p.description) zodType = zodType.describe(p.description)
+          // Path params need coercion from string argv
+          shape[p.name] = coerceIfNeeded(zodType)
+        }
+        argsSchema = z.object(shape)
+      }
+
+      // Build options Zod schema from query params + body properties
+      const optShape: Record<string, z.ZodType> = {}
+      for (const p of queryParams) {
+        let zodType = p.schema ? toZod(p.schema) : z.string()
+        if (!p.required) zodType = zodType.optional()
+        if (p.description) zodType = zodType.describe(p.description)
+        optShape[p.name] = coerceIfNeeded(zodType)
+      }
+      for (const [key, schema] of Object.entries(bodyProps)) {
+        let zodType = toZod(schema)
+        if (!bodyRequired.has(key)) zodType = zodType.optional()
+        optShape[key] = zodType
+      }
+      const optionsSchema = Object.keys(optShape).length > 0 ? z.object(optShape) : undefined
+
+      commands.set(name, {
+        description: op.summary ?? op.description,
+        args: argsSchema,
+        options: optionsSchema,
+        run: createHandler({ basePath: options.basePath, fetch, httpMethod, path, pathParams, queryParams, bodyProps }),
+      })
+    }
+  }
+
+  return commands
+}
+
+function createHandler(config: {
+  basePath?: string | undefined
+  bodyProps: Record<string, Record<string, unknown>>
+  fetch: FetchHandler
+  httpMethod: string
+  path: string
+  pathParams: Parameter[]
+  queryParams: Parameter[]
+}) {
+  return async (context: any) => {
+    const { args = {}, options = {} } = context
+
+    // Build URL path with interpolated path params
+    let urlPath = (config.basePath ?? '') + config.path
+    for (const p of config.pathParams) {
+      const value = args[p.name]
+      if (value !== undefined) urlPath = urlPath.replace(`{${p.name}}`, String(value))
+    }
+
+    // Build query string from query params
+    const query = new URLSearchParams()
+    for (const p of config.queryParams) {
+      const value = options[p.name]
+      if (value !== undefined) query.set(p.name, String(value))
+    }
+
+    // Build body from body properties
+    let body: string | undefined
+    const bodyKeys = Object.keys(config.bodyProps)
+    if (bodyKeys.length > 0) {
+      const bodyObj: Record<string, unknown> = {}
+      for (const key of bodyKeys)
+        if (options[key] !== undefined) bodyObj[key] = options[key]
+      if (Object.keys(bodyObj).length > 0) body = JSON.stringify(bodyObj)
+    }
+
+    const input: Fetch.FetchInput = {
+      path: urlPath,
+      method: config.httpMethod,
+      headers: new Headers(),
+      body,
+      query,
+    }
+
+    if (body) input.headers.set('content-type', 'application/json')
+
+    const request = Fetch.buildRequest(input)
+    const response = await config.fetch(request)
+    const output = await Fetch.parseResponse(response)
+
+    if (!output.ok)
+      return context.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}`,
+      })
+
+    return output.data
+  }
+}
+
+/** Converts a JSON Schema object to a Zod schema. */
+function toZod(schema: Record<string, unknown>): z.ZodType {
+  return z.fromJSONSchema(schema)
+}
+
+/** Wraps a Zod schema with coercion if the base type is number or boolean (argv is always strings). */
+function coerceIfNeeded(schema: z.ZodType): z.ZodType {
+  const isOptional = schema instanceof z.ZodOptional
+  const inner = isOptional ? schema.unwrap() : schema
+
+  // Direct number/boolean
+  if (inner instanceof z.ZodNumber) return isOptional ? z.coerce.number().optional() : z.coerce.number()
+  if (inner instanceof z.ZodBoolean) return isOptional ? z.coerce.boolean().optional() : z.coerce.boolean()
+
+  // Union containing number (e.g. type: ["number", "null"] from OpenAPI 3.1)
+  if (inner instanceof z.ZodUnion) {
+    const options = (inner as any)._zod?.def?.options as z.ZodType[] | undefined
+    if (options?.some((o: z.ZodType) => o instanceof z.ZodNumber))
+      return isOptional ? z.coerce.number().optional() : z.coerce.number()
+    if (options?.some((o: z.ZodType) => o instanceof z.ZodBoolean))
+      return isOptional ? z.coerce.boolean().optional() : z.coerce.boolean()
+  }
+
+  return schema
+}