incur 0.0.0 → 0.0.2

package/src/Help.ts

@@ -0,0 +1,302 @@
+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 lines: string[] = []
+
+  // Header
+  lines.push(description ? `${name} \u2014 ${description}` : name)
+  if (version) lines.push(`v${version}`)
+  lines.push('')
+
+  // Synopsis
+  lines.push(`Usage: ${name} <command>`)
+
+  // Commands
+  if (commands.length > 0) {
+    lines.push('')
+    lines.push('Commands:')
+    const maxLen = Math.max(...commands.map((c) => c.name.length))
+    for (const cmd of commands) {
+      if (cmd.description) {
+        const padding = ' '.repeat(maxLen - cmd.name.length)
+        lines.push(`  ${cmd.name}${padding}  ${cmd.description}`)
+      } else lines.push(`  ${cmd.name}`)
+    }
+  }
+
+  lines.push(...globalOptionsLines(root))
+
+  return lines.join('\n')
+}
+
+export declare namespace formatRoot {
+  type Options = {
+    /** Commands to list. */
+    commands?: { name: string; description?: string | undefined }[] | undefined
+    /** A short description of the CLI or group. */
+    description?: string | undefined
+    /** Show root-level built-in commands and flags. */
+    root?: boolean | undefined
+    /** CLI version string. */
+    version?: string | undefined
+  }
+}
+
+export declare namespace formatCommand {
+  type Options = {
+    /** Map of option names to single-char aliases. */
+    alias?: Record<string, string> | undefined
+    /** Zod schema for positional arguments. */
+    args?: z.ZodObject<any> | undefined
+    /** A short description of what the command does. */
+    description?: string | undefined
+    /** Zod schema for environment variables. */
+    env?: z.ZodObject<any> | undefined
+    /** Formatted usage examples. */
+    examples?: { command: string; description?: string }[] | undefined
+    /** Plain text hint displayed after examples and before global options. */
+    hint?: string | undefined
+    /** Zod schema for named options/flags. */
+    options?: z.ZodObject<any> | undefined
+    /** Show root-level built-in commands and flags. */
+    root?: boolean | undefined
+    /** Alternative usage patterns. */
+    usage?:
+      | {
+          args?: Partial<Record<string, true>> | undefined
+          options?: Partial<Record<string, true>> | undefined
+          prefix?: string | undefined
+          suffix?: string | undefined
+        }[]
+      | undefined
+    /** CLI version string. */
+    version?: string | undefined
+  }
+}
+
+/** Formats help text for a leaf command. */
+export function formatCommand(name: string, options: formatCommand.Options = {}): string {
+  const {
+    alias,
+    description,
+    version,
+    args,
+    env,
+    hint,
+    root = false,
+    options: opts,
+    examples,
+  } = options
+  const lines: string[] = []
+
+  // Header
+  lines.push(description ? `${name} \u2014 ${description}` : name)
+  if (version) lines.push(`v${version}`)
+  lines.push('')
+
+  // Synopsis
+  const { usage } = options
+  if (usage && usage.length > 0) {
+    const usageLines = usage.map((u) => {
+      const parts: string[] = []
+      if (u.prefix) parts.push(u.prefix)
+      parts.push(name)
+      if (u.args) for (const key of Object.keys(u.args)) parts.push(`<${key}>`)
+      if (u.options) for (const key of Object.keys(u.options)) parts.push(`--${key} <${key}>`)
+      if (u.suffix) parts.push(u.suffix)
+      return parts.join(' ')
+    })
+    const pad = ' '.repeat('Usage: '.length)
+    lines.push(`Usage: ${usageLines[0]}`)
+    for (const line of usageLines.slice(1)) lines.push(`${pad}${line}`)
+  } else {
+    const synopsis = buildSynopsis(name, args)
+    lines.push(`Usage: ${synopsis}${opts ? ' [options]' : ''}`)
+  }
+
+  // Arguments
+  if (args) {
+    const entries = argsEntries(args)
+    if (entries.length > 0) {
+      lines.push('')
+      lines.push('Arguments:')
+      const maxLen = Math.max(...entries.map((e) => e.name.length))
+      for (const entry of entries)
+        lines.push(`  ${entry.name}${' '.repeat(maxLen - entry.name.length)}  ${entry.description}`)
+    }
+  }
+
+  // Options
+  if (opts) {
+    const entries = optionEntries(opts, alias)
+    if (entries.length > 0) {
+      lines.push('')
+      lines.push('Options:')
+      const maxLen = Math.max(...entries.map((e) => e.flag.length))
+      for (const entry of entries) {
+        const padding = ' '.repeat(maxLen - entry.flag.length)
+        const desc =
+          entry.defaultValue !== undefined
+            ? `${entry.description} (default: ${entry.defaultValue})`
+            : entry.description
+        lines.push(`  ${entry.flag}${padding}  ${desc}`)
+      }
+    }
+  }
+
+  // Environment Variables
+  if (env) {
+    const entries = envEntries(env)
+    if (entries.length > 0) {
+      lines.push('')
+      lines.push('Environment Variables:')
+      const maxLen = Math.max(...entries.map((e) => e.name.length))
+      for (const entry of entries) {
+        const padding = ' '.repeat(maxLen - entry.name.length)
+        const desc =
+          entry.defaultValue !== undefined
+            ? `${entry.description} (default: ${entry.defaultValue})`
+            : entry.description
+        lines.push(`  ${entry.name}${padding}  ${desc}`)
+      }
+    }
+  }
+
+  // Examples
+  if (examples && examples.length > 0) {
+    lines.push('')
+    lines.push('Examples:')
+    const maxLen = Math.max(
+      ...examples.map((e) => (e.command ? `$ ${name} ${e.command}` : `$ ${name}`).length),
+    )
+    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}`)
+      else lines.push(`  ${cmd}`)
+    }
+  }
+
+  // Hint
+  if (hint) {
+    lines.push('')
+    lines.push(hint)
+  }
+
+  lines.push(...globalOptionsLines(root))
+
+  return lines.join('\n')
+}
+
+/** Builds the synopsis string with `<required>` and `[optional]` placeholders. */
+function buildSynopsis(name: string, args?: z.ZodObject<any>): string {
+  if (!args) return name
+  const parts = [name]
+  for (const [key, schema] of Object.entries(args.shape))
+    parts.push((schema as any).isOptional() ? `[${key}]` : `<${key}>`)
+  return parts.join(' ')
+}
+
+/** Extracts arg entries from a Zod object schema. */
+function argsEntries(schema: z.ZodObject<any>) {
+  const entries: { name: string; description: string }[] = []
+  for (const [key, field] of Object.entries(schema.shape))
+    entries.push({ name: key, description: (field as any).description ?? '' })
+  return entries
+}
+
+/** Extracts env var entries from a Zod object schema. */
+function envEntries(schema: z.ZodObject<any>) {
+  const entries: { name: string; description: string; defaultValue?: unknown }[] = []
+  for (const [key, field] of Object.entries(schema.shape)) {
+    const defaultValue = extractDefault(field)
+    entries.push({ name: key, description: (field as any).description ?? '', defaultValue })
+  }
+  return entries
+}
+
+/** Extracts option entries from a Zod object schema. */
+function optionEntries(schema: z.ZodObject<any>, alias?: Record<string, string> | undefined) {
+  const entries: { flag: string; description: string; defaultValue?: unknown }[] = []
+  for (const [key, field] of Object.entries(schema.shape)) {
+    const type = resolveTypeName(field)
+    const short = alias?.[key]
+    const kebab = toKebab(key)
+    const flag = short ? `--${kebab}, -${short} <${type}>` : `--${kebab} <${type}>`
+    const defaultValue = extractDefault(field)
+    entries.push({ flag, description: (field as any).description ?? '', defaultValue })
+  }
+  return entries
+}
+
+/** Resolves a human-readable type name from a Zod schema. */
+function resolveTypeName(schema: unknown): string {
+  const unwrapped = unwrap(schema)
+  if (unwrapped instanceof z.ZodString) return 'string'
+  if (unwrapped instanceof z.ZodNumber) return 'number'
+  if (unwrapped instanceof z.ZodBoolean) return 'boolean'
+  if (unwrapped instanceof z.ZodArray) return 'array'
+  return 'value'
+}
+
+/** Unwraps optional/default/nullable wrappers to get the inner type. */
+function unwrap(schema: unknown): unknown {
+  if (schema instanceof z.ZodOptional) return unwrap(schema.unwrap())
+  if (schema instanceof z.ZodDefault) return unwrap(schema.removeDefault())
+  if (schema instanceof z.ZodNullable) return unwrap(schema.unwrap())
+  return schema
+}
+
+/** Extracts the default value from a Zod schema, if any. */
+function extractDefault(schema: unknown): unknown {
+  if (schema instanceof z.ZodDefault) {
+    const raw = schema._def.defaultValue
+    const value = typeof raw === 'function' ? raw() : raw
+    if (Array.isArray(value) && value.length === 0) return undefined
+    return value
+  }
+  if (schema instanceof z.ZodOptional) return extractDefault(schema.unwrap())
+  return undefined
+}
+
+/** Converts a camelCase string to kebab-case. */
+function toKebab(str: string): string {
+  return str.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
+}
+
+/** Renders the built-in commands and global options block. Root-only items are hidden for subcommands. */
+function globalOptionsLines(root = false): string[] {
+  const lines: string[] = []
+
+  if (root) {
+    const builtins = [
+      { name: 'mcp add', desc: 'Register as an MCP server' },
+      { name: 'skills add', desc: 'Sync skill files to your agent' },
+    ]
+    const maxCmd = Math.max(...builtins.map((b) => b.name.length))
+    lines.push(
+      '',
+      'Built-in Commands:',
+      ...builtins.map((b) => `  ${b.name}${' '.repeat(maxCmd - b.name.length)}  ${b.desc}`),
+    )
+  }
+
+  const flags = [
+    { 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: '--verbose', desc: 'Show full output envelope' },
+    ...(root ? [{ flag: '--version', desc: 'Show version' }] : []),
+  ]
+  const maxLen = Math.max(...flags.map((f) => f.flag.length))
+  lines.push(
+    '',
+    'Global Options:',
+    ...flags.map((f) => `  ${f.flag}${' '.repeat(maxLen - f.flag.length)}  ${f.desc}`),
+  )
+
+  return lines
+}

package/src/Mcp.test.ts

@@ -0,0 +1,254 @@
+import { Mcp, z } from 'incur'
+import { PassThrough } from 'node:stream'
+
+function createTestCommands() {
+  const commands = new Map<string, any>()
+
+  commands.set('ping', {
+    description: 'Health check',
+    run() {
+      return { pong: true }
+    },
+  })
+
+  commands.set('echo', {
+    description: 'Echo a message',
+    args: z.object({
+      message: z.string().describe('Message to echo'),
+    }),
+    options: z.object({
+      upper: z.boolean().default(false).describe('Uppercase output'),
+    }),
+    run({ args, options }: any) {
+      const msg = options.upper ? args.message.toUpperCase() : args.message
+      return { result: msg }
+    },
+  })
+
+  commands.set('greet', {
+    _group: true,
+    description: 'Greeting commands',
+    commands: new Map([
+      [
+        'hello',
+        {
+          description: 'Say hello',
+          args: z.object({ name: z.string().describe('Name to greet') }),
+          run({ args }: any) {
+            return { greeting: `hello ${args.name}` }
+          },
+        },
+      ],
+    ]),
+  })
+
+  commands.set('fail', {
+    description: 'Always fails',
+    run({ error }: any) {
+      return error({ code: 'BOOM', message: 'it broke' })
+    },
+  })
+
+  commands.set('stream', {
+    description: 'Stream chunks',
+    async *run() {
+      yield { content: 'hello' }
+      yield { content: 'world' }
+    },
+  })
+
+  return commands
+}
+
+/** Standard initialize params for MCP protocol. */
+const initParams = {
+  protocolVersion: '2024-11-05',
+  capabilities: {},
+  clientInfo: { name: 'test-client', version: '1.0.0' },
+}
+
+/** Sends JSON-RPC messages, ends the stream, waits for serve to finish, returns parsed responses. */
+async function mcpSession(
+  commands: Map<string, any>,
+  messages: { method: string; params?: unknown; id?: number }[],
+) {
+  const input = new PassThrough()
+  const output = new PassThrough()
+  const chunks: string[] = []
+  output.on('data', (chunk) => chunks.push(chunk.toString()))
+
+  const done = Mcp.serve('test-cli', '1.0.0', commands, { input, output })
+
+  for (const msg of messages) {
+    const rpc = { jsonrpc: '2.0', ...msg }
+    input.write(`${JSON.stringify(rpc)}\n`)
+  }
+
+  // Give time for async processing then close
+  await new Promise((r) => setTimeout(r, 20))
+  input.end()
+  await done
+
+  return chunks.map((c) => JSON.parse(c.trim()))
+}
+
+describe('Mcp', () => {
+  test('initialize responds with server info', async () => {
+    const [res] = await mcpSession(createTestCommands(), [
+      { id: 1, method: 'initialize', params: initParams },
+    ])
+    expect(res.id).toBe(1)
+    expect(res.result.protocolVersion).toBe('2024-11-05')
+    expect(res.result.serverInfo).toEqual({ name: 'test-cli', version: '1.0.0' })
+    expect(res.result.capabilities.tools).toBeDefined()
+  })
+
+  test('tools/list returns all leaf commands as tools', async () => {
+    const [, res] = await mcpSession(createTestCommands(), [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/list', params: {} },
+    ])
+    const names = res.result.tools.map((t: any) => t.name).sort()
+    expect(names).toEqual(['echo', 'fail', 'greet_hello', 'ping', 'stream'])
+
+    const echoTool = res.result.tools.find((t: any) => t.name === 'echo')
+    expect(echoTool.description).toBe('Echo a message')
+    expect(echoTool.inputSchema.properties.message).toBeDefined()
+    expect(echoTool.inputSchema.properties.upper).toBeDefined()
+    expect(echoTool.inputSchema.required).toContain('message')
+  })
+
+  test('notifications are ignored (no response)', async () => {
+    const responses = await mcpSession(createTestCommands(), [
+      { id: 1, method: 'initialize', params: initParams },
+      { method: 'notifications/initialized' },
+      { id: 2, method: 'ping' },
+    ])
+    expect(responses).toHaveLength(2)
+    expect(responses[0].id).toBe(1)
+    expect(responses[1].id).toBe(2)
+  })
+
+  test('tools/call executes simple command', async () => {
+    const [, res] = await mcpSession(createTestCommands(), [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/call', params: { name: 'ping', arguments: {} } },
+    ])
+    expect(res.result.content).toEqual([{ type: 'text', text: '{"pong":true}' }])
+  })
+
+  test('tools/call with args and options', async () => {
+    const [, res] = await mcpSession(createTestCommands(), [
+      { id: 1, method: 'initialize', params: initParams },
+      {
+        id: 2,
+        method: 'tools/call',
+        params: { name: 'echo', arguments: { message: 'hello', upper: true } },
+      },
+    ])
+    expect(res.result.content).toEqual([{ type: 'text', text: '{"result":"HELLO"}' }])
+  })
+
+  test('tools/call with nested group command', async () => {
+    const [, res] = await mcpSession(createTestCommands(), [
+      { id: 1, method: 'initialize', params: initParams },
+      {
+        id: 2,
+        method: 'tools/call',
+        params: { name: 'greet_hello', arguments: { name: 'world' } },
+      },
+    ])
+    expect(res.result.content).toEqual([{ type: 'text', text: '{"greeting":"hello world"}' }])
+  })
+
+  test('tools/call unknown tool returns error', async () => {
+    const [, res] = await mcpSession(createTestCommands(), [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/call', params: { name: 'nope', arguments: {} } },
+    ])
+    // SDK returns a JSON-RPC error for unknown tools
+    const hasError = res.error?.message?.includes('nope') || res.result?.isError
+    expect(hasError).toBeTruthy()
+  })
+
+  test('tools/call with sentinel error result', async () => {
+    const [, res] = await mcpSession(createTestCommands(), [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/call', params: { name: 'fail', arguments: {} } },
+    ])
+    expect(res.result.isError).toBe(true)
+    expect(res.result.content[0].text).toBe('it broke')
+  })
+
+  test('unknown method returns JSON-RPC error', async () => {
+    const [, res] = await mcpSession(createTestCommands(), [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'bogus/method', params: {} },
+    ])
+    // SDK returns either a JSON-RPC error or ignores unknown methods
+    expect(res.error ?? res.result).toBeDefined()
+  })
+
+  test('ping returns empty object', async () => {
+    const [, res] = await mcpSession(createTestCommands(), [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'ping' },
+    ])
+    expect(res.result).toEqual({})
+  })
+
+  test('options get defaults applied', async () => {
+    const [, res] = await mcpSession(createTestCommands(), [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/call', params: { name: 'echo', arguments: { message: 'hi' } } },
+    ])
+    // upper defaults to false, so message stays lowercase
+    expect(res.result.content).toEqual([{ type: 'text', text: '{"result":"hi"}' }])
+  })
+
+  test('streaming command buffers chunks into array', async () => {
+    const [, res] = await mcpSession(createTestCommands(), [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/call', params: { name: 'stream', arguments: {} } },
+    ])
+    expect(res.result.content).toEqual([
+      { type: 'text', text: '[{"content":"hello"},{"content":"world"}]' },
+    ])
+  })
+
+  test('streaming command sends progress notifications', async () => {
+    const input = new PassThrough()
+    const output = new PassThrough()
+    const chunks: any[] = []
+    output.on('data', (chunk) => chunks.push(JSON.parse(chunk.toString().trim())))
+
+    const done = Mcp.serve('test-cli', '1.0.0', createTestCommands(), { input, output })
+
+    // Initialize
+    input.write(
+      JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: initParams }) + '\n',
+    )
+    await new Promise((r) => setTimeout(r, 10))
+
+    // Call streaming tool with progressToken
+    input.write(
+      JSON.stringify({
+        jsonrpc: '2.0',
+        id: 2,
+        method: 'tools/call',
+        params: { name: 'stream', arguments: {}, _meta: { progressToken: 'tok-1' } },
+      }) + '\n',
+    )
+    await new Promise((r) => setTimeout(r, 50))
+    input.end()
+    await done
+
+    // Filter for progress notifications
+    const progress = chunks.filter((c) => c.method === 'notifications/progress')
+    expect(progress).toHaveLength(2)
+    expect(progress[0].params.message).toBe('{"content":"hello"}')
+    expect(progress[1].params.message).toBe('{"content":"world"}')
+    expect(progress[0].params.progress).toBe(1)
+    expect(progress[1].params.progress).toBe(2)
+  })
+})