incur 0.0.0 → 0.0.2

package/src/Typegen.test.ts

@@ -0,0 +1,150 @@
+import { Cli, Typegen, z } from 'incur'
+
+describe('fromCli', () => {
+  test('simple commands with args and options', () => {
+    const cli = Cli.create('test')
+      .command('get', {
+        args: z.object({ id: z.number() }),
+        run: () => ({}),
+      })
+      .command('list', {
+        options: z.object({ limit: z.number() }),
+        run: () => ({}),
+      })
+
+    expect(Typegen.fromCli(cli)).toMatchInlineSnapshot(`
+      "declare module 'incur' {
+        interface Register {
+          commands: {
+            'get': { args: { id: number }; options: {} }
+            'list': { args: {}; options: { limit: number } }
+          }
+        }
+      }
+      "
+    `)
+  })
+
+  test('command with no args or options', () => {
+    const cli = Cli.create('test').command('ping', { run: () => ({}) })
+
+    expect(Typegen.fromCli(cli)).toMatchInlineSnapshot(`
+      "declare module 'incur' {
+        interface Register {
+          commands: {
+            'ping': { args: {}; options: {} }
+          }
+        }
+      }
+      "
+    `)
+  })
+
+  test('sub-commands use full path', () => {
+    const cli = Cli.create('test')
+    const pr = Cli.create('pr')
+      .command('list', {
+        options: z.object({ state: z.string() }),
+        run: () => ({}),
+      })
+      .command('create', {
+        args: z.object({ title: z.string() }),
+        run: () => ({}),
+      })
+    cli.command(pr)
+
+    expect(Typegen.fromCli(cli)).toMatchInlineSnapshot(`
+      "declare module 'incur' {
+        interface Register {
+          commands: {
+            'pr create': { args: { title: string }; options: {} }
+            'pr list': { args: {}; options: { state: string } }
+          }
+        }
+      }
+      "
+    `)
+  })
+
+  test('deeply nested sub-commands', () => {
+    const cli = Cli.create('test')
+    const review = Cli.create('review').command('approve', {
+      args: z.object({ id: z.number() }),
+      run: () => ({}),
+    })
+    const pr = Cli.create('pr')
+    pr.command(review)
+    cli.command(pr)
+
+    expect(Typegen.fromCli(cli)).toMatchInlineSnapshot(`
+      "declare module 'incur' {
+        interface Register {
+          commands: {
+            'pr review approve': { args: { id: number }; options: {} }
+          }
+        }
+      }
+      "
+    `)
+  })
+
+  test('enum types fromCli union of literals', () => {
+    const cli = Cli.create('test').command('list', {
+      options: z.object({ state: z.enum(['open', 'closed', 'merged']) }),
+      run: () => ({}),
+    })
+
+    const output = Typegen.fromCli(cli)
+    expect(output).toContain('"open" | "closed" | "merged"')
+  })
+
+  test('boolean types', () => {
+    const cli = Cli.create('test').command('list', {
+      options: z.object({ verbose: z.boolean() }),
+      run: () => ({}),
+    })
+
+    const output = Typegen.fromCli(cli)
+    expect(output).toContain('verbose: boolean')
+  })
+
+  test('array types', () => {
+    const cli = Cli.create('test').command('list', {
+      options: z.object({ tags: z.array(z.string()) }),
+      run: () => ({}),
+    })
+
+    const output = Typegen.fromCli(cli)
+    expect(output).toContain('tags: string[]')
+  })
+
+  test('commands are sorted alphabetically', () => {
+    const cli = Cli.create('test')
+      .command('zebra', { run: () => ({}) })
+      .command('alpha', { run: () => ({}) })
+      .command('middle', { run: () => ({}) })
+
+    const output = Typegen.fromCli(cli)
+    const commandOrder = [...output.matchAll(/^ {6}'(\w+)':/gm)].map((m) => m[1])
+    expect(commandOrder).toEqual(['alpha', 'middle', 'zebra'])
+  })
+
+  test('mixed top-level and grouped commands', () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({}) })
+    const pr = Cli.create('pr').command('list', { run: () => ({}) })
+    cli.command(pr)
+
+    expect(Typegen.fromCli(cli)).toMatchInlineSnapshot(`
+      "declare module 'incur' {
+        interface Register {
+          commands: {
+            'ping': { args: {}; options: {} }
+            'pr list': { args: {}; options: {} }
+          }
+        }
+      }
+      "
+    `)
+  })
+})

package/src/Typegen.ts

@@ -0,0 +1,107 @@
+import fs from 'node:fs/promises'
+import { z } from 'zod'
+
+import * as Cli from './Cli.js'
+import { importCli } from './internal/utils.js'
+
+/** Imports a CLI from `input` (must `export default` a `Cli`), generates the `.d.ts`, and writes it to `output`. */
+export async function generate(input: string, output: string): Promise<void> {
+  const cli = await importCli(input)
+  await fs.writeFile(output, fromCli(cli))
+}
+
+/** Generates a `.d.ts` declaration string for the `incur` module augmentation. */
+export function fromCli(cli: Cli.Cli): string {
+  const commands = Cli.toCommands.get(cli)
+  if (!commands) throw new Error('No commands registered on this CLI instance')
+
+  const entries = collectEntries(commands, [])
+
+  const lines: string[] = ["declare module 'incur' {", '  interface Register {', '    commands: {']
+
+  for (const { name, args, options } of entries)
+    lines.push(
+      `      '${name}': { args: ${schemaToType(args)}; options: ${schemaToType(options)} }`,
+    )
+
+  lines.push('    }', '  }', '}', '')
+  return lines.join('\n')
+}
+
+/** Recursively collects leaf commands with their full paths and schemas. */
+function collectEntries(
+  commands: Map<string, any>,
+  prefix: string[],
+): { name: string; args?: z.ZodObject<any>; options?: z.ZodObject<any> }[] {
+  const result: ReturnType<typeof collectEntries> = []
+  for (const [name, entry] of commands) {
+    const path = [...prefix, name]
+    if ('_group' in entry && entry._group) result.push(...collectEntries(entry.commands, path))
+    else result.push({ name: path.join(' '), args: entry.args, options: entry.options })
+  }
+  return result.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+/** Converts a Zod object schema to a TypeScript type string. Returns `{}` for undefined schemas. */
+function schemaToType(schema: z.ZodObject<any> | undefined): string {
+  if (!schema) return '{}'
+  const json = z.toJSONSchema(schema) as Record<string, unknown>
+  const defs = (json.$defs ?? {}) as Record<string, Record<string, unknown>>
+  const properties = json.properties as Record<string, Record<string, unknown>> | undefined
+  if (!properties || Object.keys(properties).length === 0) return '{}'
+  const entries = Object.entries(properties).map(
+    ([key, value]) => `${key}: ${resolveType(value, defs)}`,
+  )
+  return `{ ${entries.join('; ')} }`
+}
+
+/** Recursively resolves a JSON Schema node to a TypeScript type string. */
+function resolveType(
+  schema: Record<string, unknown>,
+  defs: Record<string, Record<string, unknown>>,
+): string {
+  if (schema.$ref) {
+    const ref = (schema.$ref as string).replace('#/$defs/', '')
+    const resolved = defs[ref]
+    if (resolved) return resolveType(resolved, defs)
+    return 'unknown'
+  }
+
+  if ('const' in schema) return JSON.stringify(schema.const)
+  if (schema.enum) return (schema.enum as unknown[]).map((v) => JSON.stringify(v)).join(' | ')
+  if (schema.anyOf)
+    return (schema.anyOf as Record<string, unknown>[]).map((s) => resolveType(s, defs)).join(' | ')
+
+  const type = schema.type as string | string[] | undefined
+  if (Array.isArray(type))
+    return type
+      .map((t) => (t === 'null' ? 'null' : resolveType({ ...schema, type: t }, defs)))
+      .join(' | ')
+
+  switch (type) {
+    case 'string':
+      return 'string'
+    case 'number':
+    case 'integer':
+      return 'number'
+    case 'boolean':
+      return 'boolean'
+    case 'null':
+      return 'null'
+    case 'array': {
+      const items = schema.items as Record<string, unknown> | undefined
+      const itemType = items ? resolveType(items, defs) : 'unknown'
+      return itemType.includes(' | ') ? `(${itemType})[]` : `${itemType}[]`
+    }
+    case 'object': {
+      const properties = schema.properties as Record<string, Record<string, unknown>> | undefined
+      if (!properties || Object.keys(properties).length === 0) return '{}'
+      const entries = Object.entries(properties).map(
+        ([key, value]) => `${key}: ${resolveType(value, defs)}`,
+      )
+      return `{ ${entries.join('; ')} }`
+    }
+    default:
+      return 'unknown'
+  }
+}

package/src/bin.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import { z } from 'zod'
+
+import * as Cli from './Cli.js'
+import * as Typegen from './Typegen.js'
+
+const cli = Cli.create('incur', {
+  description: 'CLI for incur',
+  sync: {
+    depth: 1,
+    include: ['_root'],
+    suggestions: ['build a cli with incur', 'generate incur types'],
+  },
+}).command('gen', {
+  description: 'Generate type definitions for development.',
+  options: z.object({
+    dir: z.string().optional().describe('Project root directory'),
+    entry: z.string().optional().describe('Entrypoint path (absolute)'),
+    output: z.string().optional().describe('Output path (absolute)'),
+  }),
+  async run({ options }) {
+    const dir = options.dir ?? '.'
+    const entry = options.entry ?? dir
+    const output = options.output ?? path.join(dir, 'incur.generated.ts')
+    await Typegen.generate(entry, output)
+    return { dir, entry, output }
+  },
+})
+
+cli.serve()
+
+export default cli