incur 0.3.4 → 0.3.6

package/src/Completions.test.ts

@@ -294,27 +294,24 @@ describe('completions built-in command', () => {
     expect(output).toMatchInlineSnapshot(`
       "mycli completions — Generate shell completion script
 
-      Usage: mycli completions <shell>
+      Usage: mycli completions <bash|fish|nushell|zsh>
 
-      Shells:
-        bash
-        fish
-        nushell
-        zsh
+      Arguments:
+        shell  Shell to generate completions for
 
       Setup:
         bash     eval "$(mycli completions bash)"  # add to ~/.bashrc
-        zsh      eval "$(mycli completions zsh)"   # add to ~/.zshrc
         fish     mycli completions fish | source   # add to ~/.config/fish/config.fish
         nushell  see \`mycli completions nushell\`   # add to config.nu
+        zsh      eval "$(mycli completions zsh)"   # add to ~/.zshrc
       "
     `)
   })
 
-  test('errors on missing shell argument', async () => {
+  test('shows help on missing shell argument', async () => {
     const cli = makeCli()
     const output = await serve(cli, ['completions'])
-    expect(output).toContain('Missing shell argument')
+    expect(output).toContain('Generate shell completion script')
   })
 
   test('errors on unknown shell', async () => {
@@ -391,6 +388,35 @@ describe('serve integration', () => {
     expect(output).toContain('db')
   })
 
+  test('COMPLETE=bash includes built-in commands at root', async () => {
+    const cli = makeCli()
+    const output = await serve(cli, ['--', 'mycli', ''], {
+      COMPLETE: 'bash',
+      _COMPLETE_INDEX: '1',
+    })
+    expect(output).toContain('completions')
+    expect(output).toContain('mcp')
+    expect(output).toContain('skills')
+  })
+
+  test('COMPLETE=bash suggests add for skills subcommand', async () => {
+    const cli = makeCli()
+    const output = await serve(cli, ['--', 'mycli', 'skills', ''], {
+      COMPLETE: 'bash',
+      _COMPLETE_INDEX: '2',
+    })
+    expect(output).toContain('add')
+  })
+
+  test('COMPLETE=bash suggests add for mcp subcommand', async () => {
+    const cli = makeCli()
+    const output = await serve(cli, ['--', 'mycli', 'mcp', ''], {
+      COMPLETE: 'bash',
+      _COMPLETE_INDEX: '2',
+    })
+    expect(output).toContain('add')
+  })
+
   test('COMPLETE=zsh with words outputs candidates in zsh format', async () => {
     const cli = makeCli()
     const output = await serve(cli, ['--', 'mycli', '--'], {

package/src/Completions.ts

@@ -1,7 +1,6 @@
 import type { z } from 'zod'
 
-/** Supported shells for completion generation. */
-export type Shell = 'bash' | 'fish' | 'nushell' | 'zsh'
+import type { Shell } from './internal/command.js'
 
 /** A completion candidate with an optional description. */
 export type Candidate = {

package/src/Filter.ts

@@ -80,23 +80,6 @@ export function apply(data: unknown, paths: FilterPath[]): unknown {
   return result
 }
 
-function resolve(data: unknown, segments: Segment[], index: number): unknown {
-  if (index >= segments.length) return data
-  const segment = segments[index]!
-
-  if ('key' in segment) {
-    if (typeof data !== 'object' || data === null) return undefined
-    const val = (data as Record<string, unknown>)[segment.key]
-    return resolve(val, segments, index + 1)
-  }
-
-  // slice segment
-  if (!Array.isArray(data)) return undefined
-  const sliced = data.slice(segment.start, segment.end)
-  if (index + 1 >= segments.length) return sliced
-  return sliced.map((item) => resolve(item, segments, index + 1))
-}
-
 function merge(
   target: Record<string, unknown>,
   data: unknown,

package/src/Help.test.ts

@@ -88,6 +88,17 @@ describe('formatCommand', () => {
     `)
   })
 
+  test('synopsis uses key name for non-union args and expanded values for enums', () => {
+    const result = Help.formatCommand('tool run', {
+      args: z.object({
+        port: z.number().describe('Port number'),
+        verbose: z.boolean().optional().describe('Verbose'),
+        mode: z.enum(['fast', 'slow']).describe('Mode'),
+      }),
+    })
+    expect(result).toContain('Usage: tool run <port> [verbose] <fast|slow>')
+  })
+
   test('shows count type in help for meta count', () => {
     const result = Help.formatCommand('tool run', {
       options: z.object({
@@ -130,6 +141,36 @@ describe('formatCommand', () => {
     expect(result).toContain('[deprecated] Availability zone')
     expect(result).not.toContain('[deprecated] Target region')
   })
+
+  test('shows config global options when flag name is set', () => {
+    const result = Help.formatCommand('tool deploy', {
+      configFlag: 'config',
+      options: z.object({
+        env: z.enum(['staging', 'production']).describe('Target environment'),
+      }),
+    })
+    expect(result).toMatchInlineSnapshot(`
+      "tool deploy
+
+      Usage: tool deploy [options]
+
+      Options:
+        --env <staging|production>  Target environment
+
+      Global Options:
+        --config <path>                     Load JSON option defaults from a file
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
+        --format <toon|json|yaml|md|jsonl>  Output format
+        --help                              Show help
+        --llms, --llms-full                 Print LLM-readable manifest
+        --no-config                         Disable JSON option defaults for this run
+        --schema                            Show JSON Schema for command
+        --token-count                       Print token count of output (instead of output)
+        --token-limit <n>                   Limit output to n tokens
+        --token-offset <n>                  Skip first n tokens of output
+        --verbose                           Show full output envelope"
+    `)
+  })
 })
 
 describe('formatRoot', () => {
@@ -247,4 +288,40 @@ describe('formatRoot', () => {
         --verbose                           Show full output envelope"
     `)
   })
+
+  test('formatRoot shows config global options when flag name is set', () => {
+    const result = Help.formatRoot('tool', {
+      configFlag: 'config',
+      root: true,
+      commands: [{ name: 'ping', description: 'Health check' }],
+    })
+    expect(result).toMatchInlineSnapshot(`
+      "tool
+
+      Usage: tool <command>
+
+      Commands:
+        ping  Health check
+
+      Integrations:
+        completions  Generate shell completion script
+        mcp add      Register as MCP server
+        skills add   Sync skill files to agents
+
+      Global Options:
+        --config <path>                     Load JSON option defaults from a file
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
+        --format <toon|json|yaml|md|jsonl>  Output format
+        --help                              Show help
+        --llms, --llms-full                 Print LLM-readable manifest
+        --mcp                               Start as MCP stdio server
+        --no-config                         Disable JSON option defaults for this run
+        --schema                            Show JSON Schema for command
+        --token-count                       Print token count of output (instead of output)
+        --token-limit <n>                   Limit output to n tokens
+        --token-offset <n>                  Skip first n tokens of output
+        --verbose                           Show full output envelope
+        --version                           Show version"
+    `)
+  })
 })

package/src/Help.ts

@@ -1,8 +1,11 @@
 import { z } from 'zod'
 
+import { builtinCommands } from './internal/command.js'
+import { toKebab } from './internal/helpers.js'
+
 /** Formats help text for a router CLI or command group. */
 export function formatRoot(name: string, options: formatRoot.Options = {}): string {
-  const { aliases, description, version, commands = [], root = false } = options
+  const { aliases, configFlag, description, version, commands = [], root = false } = options
   const lines: string[] = []
 
   // Header
@@ -27,7 +30,7 @@ export function formatRoot(name: string, options: formatRoot.Options = {}): stri
     }
   }
 
-  lines.push(...globalOptionsLines(root))
+  lines.push(...globalOptionsLines(root, configFlag))
 
   return lines.join('\n')
 }
@@ -36,6 +39,8 @@ export declare namespace formatRoot {
   type Options = {
     /** Alternative binary names for this CLI. */
     aliases?: string[] | undefined
+    /** Flag name for config file path (e.g. `'config'` renders `--config <path>`). */
+    configFlag?: string | undefined
     /** Commands to list. */
     commands?: { name: string; description?: string | undefined }[] | undefined
     /** A short description of the CLI or group. */
@@ -55,6 +60,8 @@ export declare namespace formatCommand {
     aliases?: string[] | undefined
     /** Zod schema for positional arguments. */
     args?: z.ZodObject<any> | undefined
+    /** Flag name for config file path (e.g. `'config'` renders `--config <path>`). */
+    configFlag?: string | undefined
     /** Subcommands to list (for CLIs with both a root handler and subcommands). */
     commands?: { name: string; description?: string | undefined }[] | undefined
     /** A short description of what the command does. */
@@ -67,6 +74,8 @@ export declare namespace formatCommand {
     examples?: { command: string; description?: string }[] | undefined
     /** Plain text hint displayed after examples and before global options. */
     hint?: string | undefined
+    /** Hide global options section. */
+    hideGlobalOptions?: boolean | undefined
     /** Zod schema for named options/flags. */
     options?: z.ZodObject<any> | undefined
     /** Show root-level built-in commands and flags. */
@@ -90,6 +99,7 @@ export function formatCommand(name: string, options: formatCommand.Options = {})
   const {
     alias,
     aliases,
+    configFlag,
     description,
     version,
     args,
@@ -195,7 +205,7 @@ export function formatCommand(name: string, options: formatCommand.Options = {})
     }
   }
 
-  lines.push(...globalOptionsLines(root))
+  if (!options.hideGlobalOptions) lines.push(...globalOptionsLines(root, configFlag))
 
   // Environment Variables
   if (env) {
@@ -223,8 +233,11 @@ export function formatCommand(name: string, options: formatCommand.Options = {})
 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 z.ZodType)._zod.optout === 'optional' ? `[${key}]` : `<${key}>`)
+  for (const [key, schema] of Object.entries(args.shape)) {
+    const type = resolveTypeName(schema)
+    const label = type.includes('|') ? type : key
+    parts.push((schema as z.ZodType)._zod.optout === 'optional' ? `[${label}]` : `<${label}>`)
+  }
   return parts.join(' ')
 }
 
@@ -320,30 +333,32 @@ function extractDeprecated(schema: unknown): boolean | undefined {
   return meta?.deprecated === true ? true : 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[] {
+function globalOptionsLines(root = false, configFlag?: string): string[] {
   const lines: string[] = []
 
   if (root) {
-    const builtins = [
-      { name: 'completions', desc: 'Generate shell completion script' },
-      { name: 'mcp add', desc: 'Register as MCP server' },
-      { name: 'skills add', desc: 'Sync skill files to agents' },
-    ]
+    const builtins = builtinCommands.flatMap((b) => {
+      if (!b.subcommands) return [{ name: b.name, desc: b.description }]
+      if (b.subcommands.length === 1)
+        return [
+          { name: `${b.name} ${b.subcommands[0]!.name}`, desc: b.subcommands[0]!.description },
+        ]
+      const names = b.subcommands.map((s) => s.name).join(', ')
+      return [{ name: b.name, desc: `${b.description} (${names})` }]
+    })
     const maxCmd = Math.max(...builtins.map((b) => b.name.length))
     lines.push(
       '',
-      'Built-in Commands:',
+      'Integrations:',
       ...builtins.map((b) => `  ${b.name}${' '.repeat(maxCmd - b.name.length)}  ${b.desc}`),
     )
   }
 
   const flags = [
+    ...(configFlag
+      ? [{ flag: `--${configFlag} <path>`, desc: 'Load JSON option defaults from a file' }]
+      : []),
     {
       flag: '--filter-output <keys>',
       desc: 'Filter output by key paths (e.g. foo,bar.baz,a[0,3])',
@@ -352,13 +367,16 @@ function globalOptionsLines(root = false): string[] {
     { flag: '--help', desc: 'Show help' },
     { flag: '--llms, --llms-full', desc: 'Print LLM-readable manifest' },
     ...(root ? [{ flag: '--mcp', desc: 'Start as MCP stdio server' }] : []),
+    ...(configFlag
+      ? [{ flag: `--no-${configFlag}`, desc: 'Disable JSON option defaults for this run' }]
+      : []),
     { flag: '--schema', desc: 'Show JSON Schema for command' },
     { flag: '--token-count', desc: 'Print token count of output (instead of output)' },
     { flag: '--token-limit <n>', desc: 'Limit output to n tokens' },
     { flag: '--token-offset <n>', desc: 'Skip first n tokens of output' },
     { flag: '--verbose', desc: 'Show full output envelope' },
     ...(root ? [{ flag: '--version', desc: 'Show version' }] : []),
-  ]
+  ].sort((a, b) => a.flag.localeCompare(b.flag))
   const maxLen = Math.max(...flags.map((f) => f.flag.length))
   lines.push(
     '',
@@ -369,8 +387,8 @@ function globalOptionsLines(root = false): string[] {
   return lines
 }
 
-/** Redacts a value, showing only the last 3 characters. */
+/** Redacts a value, showing only the last 4 characters. */
 function redact(value: string): string {
-  if (value.length <= 3) return '••••'
-  return `••••${value.slice(-3)}`
+  if (value.length <= 4) return '****'
+  return `****${value.slice(-4)}`
 }

package/src/Mcp.test.ts

@@ -216,6 +216,149 @@ describe('Mcp', () => {
     ])
   })
 
+  test('middleware runs for tool calls', async () => {
+    const commands = new Map<string, any>()
+    commands.set('secret', {
+      description: 'Protected command',
+      run: () => ({ secret: 'data' }),
+    })
+    const middlewares = [
+      async (_c: any, next: () => Promise<void>) => {
+        _c.set('ran', true)
+        await next()
+      },
+    ]
+    const input = new PassThrough()
+    const output = new PassThrough()
+    const chunks: string[] = []
+    output.on('data', (chunk: Buffer) => chunks.push(chunk.toString()))
+
+    const done = Mcp.serve('test-cli', '1.0.0', commands, {
+      input,
+      output,
+      middlewares,
+      vars: z.object({ ran: z.boolean().default(false) }),
+    })
+
+    input.write(
+      `${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: initParams })}\n`,
+    )
+    await new Promise((r) => setTimeout(r, 10))
+    input.write(
+      `${JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'secret', arguments: {} } })}\n`,
+    )
+    await new Promise((r) => setTimeout(r, 20))
+    input.end()
+    await done
+
+    const responses = chunks.map((c) => JSON.parse(c.trim()))
+    const callRes = responses.find((r: any) => r.id === 2)
+    expect(callRes.result.content).toEqual([{ type: 'text', text: '{"secret":"data"}' }])
+  })
+
+  test('middleware error blocks tool call', async () => {
+    const commands = new Map<string, any>()
+    commands.set('secret', {
+      description: 'Protected',
+      run: () => ({ secret: true }),
+    })
+    const middlewares = [
+      (c: any) => {
+        c.error({ code: 'FORBIDDEN', message: 'not allowed' })
+      },
+    ]
+    const input = new PassThrough()
+    const output = new PassThrough()
+    const chunks: string[] = []
+    output.on('data', (chunk: Buffer) => chunks.push(chunk.toString()))
+
+    const done = Mcp.serve('test-cli', '1.0.0', commands, {
+      input,
+      output,
+      middlewares,
+    })
+
+    input.write(
+      `${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: initParams })}\n`,
+    )
+    await new Promise((r) => setTimeout(r, 10))
+    input.write(
+      `${JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'secret', arguments: {} } })}\n`,
+    )
+    await new Promise((r) => setTimeout(r, 20))
+    input.end()
+    await done
+
+    const responses = chunks.map((c) => JSON.parse(c.trim()))
+    const callRes = responses.find((r: any) => r.id === 2)
+    expect(callRes.result.isError).toBe(true)
+    expect(callRes.result.content[0].text).toBe('not allowed')
+  })
+
+  test('group middleware runs for nested tool calls', async () => {
+    const commands = new Map<string, any>()
+    const groupMiddleware = async (c: any, next: () => Promise<void>) => {
+      c.set('group', 'admin')
+      await next()
+    }
+    commands.set('admin', {
+      _group: true,
+      description: 'Admin commands',
+      middlewares: [groupMiddleware],
+      commands: new Map([
+        [
+          'status',
+          {
+            description: 'Admin status',
+            run: (c: any) => ({ group: c.var.group }),
+          },
+        ],
+      ]),
+    })
+
+    const input = new PassThrough()
+    const output = new PassThrough()
+    const chunks: string[] = []
+    output.on('data', (chunk: Buffer) => chunks.push(chunk.toString()))
+
+    const done = Mcp.serve('test-cli', '1.0.0', commands, {
+      input,
+      output,
+      vars: z.object({ group: z.string().default('none') }),
+    })
+
+    input.write(
+      `${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: initParams })}\n`,
+    )
+    await new Promise((r) => setTimeout(r, 10))
+    input.write(
+      `${JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'admin_status', arguments: {} } })}\n`,
+    )
+    await new Promise((r) => setTimeout(r, 20))
+    input.end()
+    await done
+
+    const responses = chunks.map((c) => JSON.parse(c.trim()))
+    const callRes = responses.find((r: any) => r.id === 2)
+    expect(callRes.result.content).toEqual([{ type: 'text', text: '{"group":"admin"}' }])
+  })
+
+  test('env schema is parsed for tool calls', async () => {
+    const commands = new Map<string, any>()
+    commands.set('check-env', {
+      description: 'Check env',
+      env: z.object({ MY_VAR: z.string().default('default-val') }),
+      run: (c: any) => ({ val: c.env.MY_VAR }),
+    })
+
+    const [, res] = await mcpSession(commands, [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/call', params: { name: 'check-env', arguments: {} } },
+    ])
+    const data = JSON.parse(res.result.content[0].text)
+    expect(data.val).toBe('default-val')
+  })
+
   test('streaming command sends progress notifications', async () => {
     const input = new PassThrough()
     const output = new PassThrough()