incur 0.4.8 → 0.4.9

package/src/Completions.test.ts

@@ -226,6 +226,90 @@ describe('complete', () => {
   })
 })
 
+describe('complete with globals', () => {
+  const globalSchema = z.object({
+    rpcUrl: z.string().optional().describe('RPC endpoint URL'),
+    chain: z.enum(['mainnet', 'sepolia', 'goerli']).default('mainnet').describe('Target chain'),
+    dryRun: z.boolean().default(false).describe('Dry run mode'),
+  })
+  const globalAlias = { rpcUrl: 'r', dryRun: 'd' }
+  const globals = { schema: globalSchema, alias: globalAlias }
+
+  test('global flags appear as completion candidates when typing --', () => {
+    const cli = makeCli()
+    const commands = Cli.toCommands.get(cli)!
+    const candidates = Completions.complete(commands, undefined, ['mycli', 'build', '--'], 2, globals)
+    const values = candidates.map((c) => c.value)
+    expect(values).toContain('--rpc-url')
+    expect(values).toContain('--chain')
+    expect(values).toContain('--dry-run')
+  })
+
+  test('global short aliases appear as candidates when typing -', () => {
+    const cli = makeCli()
+    const commands = Cli.toCommands.get(cli)!
+    const candidates = Completions.complete(commands, undefined, ['mycli', 'build', '-'], 2, globals)
+    const values = candidates.map((c) => c.value)
+    expect(values).toContain('-r')
+    expect(values).toContain('-d')
+  })
+
+  test('global flags do not duplicate command-specific flags', () => {
+    // Create a CLI where a command has --chain already
+    const cli = Cli.create('mycli', { version: '1.0.0' })
+    cli.command('deploy', {
+      description: 'Deploy',
+      options: z.object({
+        chain: z.string().optional().describe('Chain override'),
+      }),
+      run: () => ({}),
+    })
+    const commands = Cli.toCommands.get(cli)!
+    const rootCmd = { options: z.object({ chain: z.string().optional() }) }
+    const dupeGlobals = { schema: z.object({ chain: z.string().optional().describe('Global chain') }) }
+    const candidates = Completions.complete(
+      commands,
+      rootCmd,
+      ['mycli', 'deploy', '--'],
+      2,
+      dupeGlobals,
+    )
+    const chainCount = candidates.filter((c) => c.value === '--chain').length
+    expect(chainCount).toBe(1)
+  })
+
+  test('global option value completion for enum', () => {
+    const cli = makeCli()
+    const commands = Cli.toCommands.get(cli)!
+    const candidates = Completions.complete(
+      commands,
+      undefined,
+      ['mycli', 'build', '--chain', ''],
+      3,
+      globals,
+    )
+    const values = candidates.map((c) => c.value)
+    expect(values).toEqual(['mainnet', 'sepolia', 'goerli'])
+  })
+
+  test('global boolean flag does not consume next token as value in completions', () => {
+    const cli = makeCli()
+    const commands = Cli.toCommands.get(cli)!
+    // After --dry-run (boolean), the next token should suggest subcommands, not be consumed as value
+    const candidates = Completions.complete(
+      commands,
+      undefined,
+      ['mycli', '--dry-run', ''],
+      2,
+      globals,
+    )
+    const values = candidates.map((c) => c.value)
+    // Should suggest subcommands since --dry-run is boolean and doesn't consume next token
+    expect(values).toContain('build')
+    expect(values).toContain('test')
+  })
+})
+
 describe('format', () => {
   const candidates: Completions.Candidate[] = [
     { value: '--target', description: 'Build target' },

package/src/Completions.ts

@@ -1,6 +1,8 @@
 import type { z } from 'zod'
 
+import type { GlobalsDescriptor } from './Cli.js'
 import type { Shell } from './internal/command.js'
+import { toKebab } from './internal/helpers.js'
 
 /** A completion candidate with an optional description. */
 export type Candidate = {
@@ -41,6 +43,7 @@ export function register(shell: Shell, name: string): string {
   }
 }
 
+
 /**
  * Computes completion candidates for the given argv words and cursor index.
  * Walks the command tree to resolve the active command, then suggests
@@ -51,6 +54,7 @@ export function complete(
   rootCommand: CommandEntry | undefined,
   argv: string[],
   index: number,
+  globals?: GlobalsDescriptor | undefined,
 ): Candidate[] {
   const current = argv[index] ?? ''
 
@@ -84,7 +88,7 @@ export function complete(
     if (leaf?.options) {
       const shape = leaf.options.shape as Record<string, any>
       for (const key of Object.keys(shape)) {
-        const kebab = key.replace(/[A-Z]/g, (c: string) => `-${c.toLowerCase()}`)
+        const kebab = toKebab(key)
         const flag = `--${kebab}`
         if (flag.startsWith(current))
           candidates.push({ value: flag, description: descriptionOf(shape[key]) })
@@ -99,6 +103,25 @@ export function complete(
           }
         }
     }
+    // Global options
+    if (globals) {
+      const globalShape = globals.schema.shape as Record<string, any>
+      for (const key of Object.keys(globalShape)) {
+        const kebab = toKebab(key)
+        const flag = `--${kebab}`
+        if (flag.startsWith(current) && !candidates.some((c) => c.value === flag))
+          candidates.push({ value: flag, description: descriptionOf(globalShape[key]) })
+      }
+      // Global short aliases
+      if (globals.alias)
+        for (const [name, short] of Object.entries(globals.alias)) {
+          const flag = `-${short}`
+          if (flag.startsWith(current) && !candidates.some((c) => c.value === flag)) {
+            const desc = descriptionOf(globalShape[name])
+            candidates.push({ value: flag, description: desc })
+          }
+        }
+    }
     return candidates
   }
 
@@ -106,15 +129,31 @@ export function complete(
   if (index > 0) {
     const prev = argv[index - 1]!
     const leaf = scope.leaf
-    if (leaf?.options && prev.startsWith('-')) {
-      const name = resolveOptionName(prev, leaf)
-      if (name) {
-        const values = possibleValues(name, leaf.options)
-        if (values) {
-          for (const v of values) if (v.startsWith(current)) candidates.push({ value: v })
-          return candidates
+    if (prev.startsWith('-')) {
+      // Try command-specific options first
+      if (leaf?.options) {
+        const name = resolveOptionName(prev, leaf)
+        if (name) {
+          const values = possibleValues(name, leaf.options)
+          if (values) {
+            for (const v of values) if (v.startsWith(current)) candidates.push({ value: v })
+            return candidates
+          }
+          if (!isBooleanOption(name, leaf.options)) return candidates
+        }
+      }
+      // Try global options
+      if (globals) {
+        const globalEntry: CommandEntry = { options: globals.schema, alias: globals.alias }
+        const name = resolveOptionName(prev, globalEntry)
+        if (name) {
+          const values = possibleValues(name, globals.schema)
+          if (values) {
+            for (const v of values) if (v.startsWith(current)) candidates.push({ value: v })
+            return candidates
+          }
+          if (!isBooleanOption(name, globals.schema)) return candidates
         }
-        if (!isBooleanOption(name, leaf.options)) return candidates
       }
     }
   }

package/src/Formatter.test.ts

@@ -62,6 +62,15 @@ describe('format', () => {
     `)
   })
 
+  test('formats bigint values as strings in JSON', () => {
+    const result = Formatter.format({ expiry: 2461152330n }, 'json')
+    expect(result).toMatchInlineSnapshot(`
+      "{
+        "expiry": "2461152330"
+      }"
+    `)
+  })
+
   test('formats as YAML', () => {
     const result = Formatter.format({ message: 'hello' }, 'yaml')
     expect(result).toMatchInlineSnapshot(`
@@ -319,6 +328,14 @@ describe('format jsonl', () => {
     `)
   })
 
+  test('array outputs bigint values as strings', () => {
+    const result = Formatter.format([{ expiry: 2461152330n }, { expiry: 2461152331n }], 'jsonl')
+    expect(result).toMatchInlineSnapshot(`
+      "{"expiry":"2461152330"}
+      {"expiry":"2461152331"}"
+    `)
+  })
+
   test('scalar value outputs JSON', () => {
     expect(Formatter.format(42, 'jsonl')).toMatchInlineSnapshot(`"42"`)
     expect(Formatter.format('hi', 'jsonl')).toMatchInlineSnapshot(`""hi""`)

package/src/Formatter.ts

@@ -1,5 +1,7 @@
 import { encode } from '@toon-format/toon'
-import { stringify as yamlStringify } from 'yaml'
+
+import * as Json from './internal/json.js'
+import * as Yaml from './internal/yaml.js'
 
 /** Supported output formats. */
 export type Format = 'toon' | 'json' | 'yaml' | 'md' | 'jsonl'
@@ -16,13 +18,13 @@ export function format(value: unknown, fmt: Format = 'toon'): string {
         } catch {}
       }
     }
-    return JSON.stringify(value, null, 2)
+    return Json.stringify(value, 2)
   }
-  if (fmt === 'yaml') return yamlStringify(value)
+  if (fmt === 'yaml') return Yaml.loadSync().stringify(value)
   if (fmt === 'md') return formatMarkdown(value)
   if (fmt === 'jsonl') {
-    if (Array.isArray(value)) return value.map((v) => JSON.stringify(v)).join('\n')
-    return JSON.stringify(value)
+    if (Array.isArray(value)) return value.map((v) => Json.stringify(v)).join('\n')
+    return Json.stringify(value)
   }
   // toon (default)
   if (isScalar(value)) return String(value)

package/src/Help.test.ts

@@ -411,4 +411,35 @@ describe('formatRoot', () => {
         --version                           Show version"
     `)
   })
+
+  test('formatCommand shows custom global options with deprecated flag', () => {
+    const result = Help.formatCommand('tool deploy', {
+      description: 'Deploy app',
+      globals: {
+        schema: z.object({
+          rpcUrl: z.string().optional().describe('RPC endpoint URL'),
+          oldRpc: z.string().optional().describe('Old RPC endpoint').meta({ deprecated: true }),
+        }),
+        alias: { rpcUrl: 'r' },
+      },
+    })
+    expect(result).toContain('Custom Global Options:')
+    expect(result).toContain('--rpc-url, -r <string>')
+    expect(result).toContain('RPC endpoint URL')
+    expect(result).toContain('[deprecated] Old RPC endpoint')
+  })
+
+  test('formatRoot shows custom global options', () => {
+    const result = Help.formatRoot('tool', {
+      globals: {
+        schema: z.object({
+          chain: z.string().default('mainnet').describe('Target chain'),
+        }),
+      },
+      commands: [{ name: 'deploy', description: 'Deploy' }],
+    })
+    expect(result).toContain('Custom Global Options:')
+    expect(result).toContain('--chain <string>')
+    expect(result).toContain('Target chain (default: mainnet)')
+  })
 })

package/src/Help.ts

@@ -1,12 +1,21 @@
 import { z } from 'zod'
 
+import type { GlobalsDescriptor } from './Cli.js'
 import { builtinCommands } from './internal/command.js'
 import { toKebab } from './internal/helpers.js'
 import { defaultEnvSource } from './Parser.js'
 
 /** Formats help text for a router CLI or command group. */
 export function formatRoot(name: string, options: formatRoot.Options = {}): string {
-  const { aliases, configFlag, description, version, commands = [], root = false } = options
+  const {
+    aliases,
+    configFlag,
+    description,
+    globals,
+    version,
+    commands = [],
+    root = false,
+  } = options
   const lines: string[] = []
 
   // Header
@@ -31,7 +40,7 @@ export function formatRoot(name: string, options: formatRoot.Options = {}): stri
     }
   }
 
-  lines.push(...globalOptionsLines(root, configFlag))
+  lines.push(...globalOptionsLines(root, configFlag, globals))
 
   return lines.join('\n')
 }
@@ -46,6 +55,8 @@ export declare namespace formatRoot {
     commands?: { name: string; description?: string | undefined }[] | undefined
     /** A short description of the CLI or group. */
     description?: string | undefined
+    /** Custom global options schema and alias map. */
+    globals?: GlobalsDescriptor | undefined
     /** Show root-level built-in commands and flags. */
     root?: boolean | undefined
     /** CLI version string. */
@@ -71,6 +82,8 @@ export declare namespace formatCommand {
     env?: z.ZodObject<any> | undefined
     /** Override environment variable source for "set:" display. Defaults to `process.env`. */
     envSource?: Record<string, string | undefined> | undefined
+    /** Custom global options schema and alias map. */
+    globals?: GlobalsDescriptor | undefined
     /** Formatted usage examples. */
     examples?: { command: string; description?: string }[] | undefined
     /** Plain text hint displayed after examples and before global options. */
@@ -102,6 +115,7 @@ export function formatCommand(name: string, options: formatCommand.Options = {})
     aliases,
     configFlag,
     description,
+    globals,
     version,
     args,
     env,
@@ -206,7 +220,7 @@ export function formatCommand(name: string, options: formatCommand.Options = {})
     }
   }
 
-  if (!options.hideGlobalOptions) lines.push(...globalOptionsLines(root, configFlag))
+  if (!options.hideGlobalOptions) lines.push(...globalOptionsLines(root, configFlag, globals))
 
   // Environment Variables
   if (env) {
@@ -340,7 +354,11 @@ function extractDeprecated(schema: unknown): boolean | undefined {
 }
 
 /** Renders the built-in commands and global options block. Root-only items are hidden for subcommands. */
-function globalOptionsLines(root = false, configFlag?: string): string[] {
+function globalOptionsLines(
+  root = false,
+  configFlag?: string,
+  globals?: GlobalsDescriptor,
+): string[] {
   const lines: string[] = []
 
   if (root) {
@@ -361,6 +379,26 @@ function globalOptionsLines(root = false, configFlag?: string): string[] {
     )
   }
 
+  if (globals) {
+    const entries = optionEntries(globals.schema, globals.alias)
+    if (entries.length > 0) {
+      const maxLen = Math.max(...entries.map((e) => e.flag.length))
+      lines.push(
+        '',
+        'Custom Global Options:',
+        ...entries.map((entry) => {
+          const padding = ' '.repeat(maxLen - entry.flag.length)
+          const prefix = entry.deprecated ? '[deprecated] ' : ''
+          const desc =
+            entry.defaultValue !== undefined
+              ? `${prefix}${entry.description} (default: ${entry.defaultValue})`
+              : `${prefix}${entry.description}`
+          return `  ${entry.flag}${padding}  ${desc}`
+        }),
+      )
+    }
+  }
+
   const flags = [
     ...(configFlag
       ? [{ flag: `--${configFlag} <path>`, desc: 'Load JSON option defaults from a file' }]

package/src/Mcp.test.ts

@@ -165,6 +165,18 @@ describe('Mcp', () => {
     expect(res.result.content).toEqual([{ type: 'text', text: '{"result":"HELLO"}' }])
   })
 
+  test('tools/call validation error includes fieldErrors', async () => {
+    const tool = Mcp.collectTools(createTestCommands(), []).find((tool) => tool.name === 'echo')!
+    const result = await Mcp.callTool(tool, { message: 123 })
+    expect(result.isError).toBe(true)
+    const [content] = result.content
+    expect(content).toBeDefined()
+    expect(JSON.parse(content!.text)).toMatchObject({
+      code: 'VALIDATION_ERROR',
+      fieldErrors: [{ code: 'invalid_type', missing: false, path: 'message' }],
+    })
+  })
+
   test('tools/call with nested group command', async () => {
     const [, res] = await mcpSession(createTestCommands(), [
       { id: 1, method: 'initialize', params: initParams },
@@ -177,6 +189,106 @@ describe('Mcp', () => {
     expect(res.result.content).toEqual([{ type: 'text', text: '{"greeting":"hello world"}' }])
   })
 
+  test('tools/call serializes bigint values as strings', async () => {
+    const commands = new Map<string, any>()
+    commands.set('whois', {
+      description: 'Return ENS data',
+      output: z.object({ expiry: z.bigint() }),
+      run() {
+        return { expiry: 2461152330n }
+      },
+    })
+
+    const [, res] = await mcpSession(commands, [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/call', params: { name: 'whois', arguments: {} } },
+    ])
+    expect(res.result.isError).toBeUndefined()
+    expect(res.result.content).toEqual([{ type: 'text', text: '{"expiry":"2461152330"}' }])
+    expect(res.result.structuredContent).toEqual({ expiry: '2461152330' })
+  })
+
+  test('tools/call surfaces cta metadata without changing structured content', async () => {
+    const commands = new Map<string, any>()
+    commands.set('show', {
+      description: 'Show a record',
+      output: z.object({ id: z.string() }),
+      run(c: any) {
+        return c.ok(
+          { id: 'foo' },
+          {
+            cta: {
+              description: 'Next:',
+              commands: [{ command: 'list', description: 'List all' }],
+            },
+          },
+        )
+      },
+    })
+
+    const [, res] = await mcpSession(commands, [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/call', params: { name: 'show', arguments: {} } },
+    ])
+
+    expect(res.result.content).toEqual([{ type: 'text', text: '{"id":"foo"}' }])
+    expect(res.result.structuredContent).toEqual({ id: 'foo' })
+    expect(res.result._meta?.cta).toEqual({
+      description: 'Next:',
+      commands: [{ command: 'test-cli list', description: 'List all' }],
+    })
+  })
+
+  test('callTool serializes bigint values as strings', async () => {
+    const result = await Mcp.callTool(
+      {
+        name: 'whois',
+        inputSchema: { type: 'object', properties: {} },
+        outputSchema: {
+          type: 'object',
+          properties: { expiry: { type: 'string' } },
+          required: ['expiry'],
+        },
+        command: {
+          run() {
+            return { expiry: 2461152330n }
+          },
+        },
+      },
+      {},
+    )
+
+    expect(result.isError).toBeUndefined()
+    expect(result.content).toEqual([{ type: 'text', text: '{"expiry":"2461152330"}' }])
+    expect(result.structuredContent).toEqual({ expiry: '2461152330' })
+  })
+
+  test('callTool serializes streamed bigint chunks as strings', async () => {
+    const notifications: any[] = []
+    const result = await Mcp.callTool(
+      {
+        name: 'whois',
+        inputSchema: { type: 'object', properties: {} },
+        command: {
+          async *run() {
+            yield { expiry: 2461152330n }
+          },
+        },
+      },
+      {},
+      {
+        extra: { mcpReq: { _meta: { progressToken: 'tok-1' } } },
+        sendNotification: async (notification) => {
+          notifications.push(notification)
+        },
+      },
+    )
+
+    expect(result.isError).toBeUndefined()
+    expect(result.content).toEqual([{ type: 'text', text: '[{"expiry":"2461152330"}]' }])
+    expect(notifications[0].params.message).toBe('{"expiry":"2461152330"}')
+  })
+
   test('tools/call unknown tool returns error', async () => {
     const [, res] = await mcpSession(createTestCommands(), [
       { id: 1, method: 'initialize', params: initParams },
@@ -410,4 +522,85 @@ describe('Mcp', () => {
     expect(progress[0].params.progress).toBe(1)
     expect(progress[1].params.progress).toBe(2)
   })
+
+  test('serve options.instructions appears in initialize response', async () => {
+    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', createTestCommands(), {
+      input,
+      output,
+      instructions: 'Use this CLI to run test commands.',
+    })
+
+    input.write(
+      `${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: initParams })}\n`,
+    )
+    await new Promise((r) => setTimeout(r, 20))
+    input.end()
+    await done
+
+    const [res] = chunks.map((c) => JSON.parse(c.trim()))
+    expect(res.result.instructions).toBe('Use this CLI to run test commands.')
+  })
+
+  test('command mcp.annotations appear in tools/list', async () => {
+    const commands = new Map<string, any>()
+    commands.set('read-data', {
+      description: 'Read some data',
+      mcp: { annotations: { readOnlyHint: true, idempotentHint: true } },
+      run: () => ({ data: 42 }),
+    })
+
+    const [, res] = await mcpSession(commands, [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/list', params: {} },
+    ])
+    const tool = res.result.tools.find((t: any) => t.name === 'read-data')
+    expect(tool.annotations).toEqual({ readOnlyHint: true, idempotentHint: true })
+  })
+
+  test('command mcp.instructions appear in tools/list as _meta.instructions', async () => {
+    const commands = new Map<string, any>()
+    commands.set('guided', {
+      description: 'A guided command',
+      mcp: { instructions: 'Pass a valid JSON payload.' },
+      run: () => ({ ok: true }),
+    })
+
+    const [, res] = await mcpSession(commands, [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/list', params: {} },
+    ])
+    const tool = res.result.tools.find((t: any) => t.name === 'guided')
+    expect(tool._meta?.instructions).toBe('Pass a valid JSON payload.')
+  })
+
+  test('collectTools extracts annotations and instructions from entry.mcp', () => {
+    const commands = new Map<string, any>()
+    commands.set('destroy', {
+      description: 'Destructive op',
+      mcp: {
+        annotations: { destructiveHint: true, openWorldHint: false },
+        instructions: 'Only call this in dry-run mode.',
+      },
+      run: () => null,
+    })
+
+    const tools = Mcp.collectTools(commands, [])
+    expect(tools).toHaveLength(1)
+    expect(tools[0]?.annotations).toEqual({ destructiveHint: true, openWorldHint: false })
+    expect(tools[0]?.instructions).toBe('Only call this in dry-run mode.')
+  })
+
+  test('collectTools omits annotations/instructions when not set', () => {
+    const commands = new Map<string, any>()
+    commands.set('plain', { description: 'No mcp opts', run: () => null })
+
+    const tools = Mcp.collectTools(commands, [])
+    expect(tools[0]?.annotations).toBeUndefined()
+    expect(tools[0]?.instructions).toBeUndefined()
+  })
 })