incur 0.4.8 → 0.4.10

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' },
@@ -515,6 +599,7 @@ describe('serve integration', () => {
       _COMPLETE_INDEX: '2',
     })
     expect(output).toContain('add')
+    expect(output).toContain('doctor')
   })
 
   test('COMPLETE=zsh with words outputs candidates in zsh format', async () => {

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

@@ -392,7 +392,7 @@ describe('formatRoot', () => {
 
       Integrations:
         completions  Generate shell completion script
-        mcp add      Register as MCP server
+        mcp          Register as MCP server (add, doctor)
         skills       Sync skill files to agents (add, list)
 
       Global Options:
@@ -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' }]