incur 0.4.8 → 0.4.10

package/src/Mcp.test.ts

@@ -134,6 +134,54 @@ describe('Mcp', () => {
     expect(echoTool.inputSchema.required).toContain('message')
   })
 
+  test('tools/list uses command MCP name and description overrides', async () => {
+    const commands = new Map<string, any>()
+    commands.set('whoami', {
+      description: 'Show wallet identity',
+      mcp: {
+        name: 'get_balance',
+        description: 'Get wallet balance',
+      },
+      run() {
+        return { balance: '1.00' }
+      },
+    })
+
+    const [, listRes] = await mcpSession(commands, [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/list', params: {} },
+    ])
+    const names = listRes.result.tools.map((tool: any) => tool.name)
+    expect(names).toEqual(['get_balance'])
+    expect(listRes.result.tools[0].description).toBe('Get wallet balance')
+
+    const [, callRes] = await mcpSession(commands, [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/call', params: { name: 'get_balance', arguments: {} } },
+    ])
+    expect(callRes.result.content).toEqual([{ type: 'text', text: '{"balance":"1.00"}' }])
+  })
+
+  test('collectTools rejects duplicate MCP tool names', () => {
+    const commands = new Map<string, any>()
+    commands.set('whoami', {
+      mcp: { name: 'get_balance' },
+      run() {
+        return { balance: '1.00' }
+      },
+    })
+    commands.set('balance', {
+      mcp: { name: 'get_balance' },
+      run() {
+        return { balance: '1.00' }
+      },
+    })
+
+    expect(() => Mcp.collectTools(commands, [])).toThrowError(
+      'Duplicate MCP tool name: get_balance',
+    )
+  })
+
   test('notifications are ignored (no response)', async () => {
     const responses = await mcpSession(createTestCommands(), [
       { id: 1, method: 'initialize', params: initParams },
@@ -165,6 +213,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 +237,154 @@ 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/list tolerates non-object output schemas', async () => {
+    const commands = new Map<string, any>()
+    commands.set('list', {
+      description: 'List records',
+      output: z.array(z.object({ id: z.string() })),
+      run() {
+        return [{ id: 'foo' }]
+      },
+    })
+    commands.set('count', {
+      description: 'Count records',
+      output: z.number(),
+      run() {
+        return 1
+      },
+    })
+    commands.set('show', {
+      description: 'Show record',
+      output: z.object({ id: z.string() }),
+      run() {
+        return { id: 'foo' }
+      },
+    })
+
+    const tools = Mcp.collectTools(commands, [])
+    expect(tools.find((tool) => tool.name === 'list')?.outputSchema).toBeUndefined()
+    expect(tools.find((tool) => tool.name === 'count')?.outputSchema).toBeUndefined()
+    expect(tools.find((tool) => tool.name === 'show')?.outputSchema?.type).toBe('object')
+
+    const [, listRes] = await mcpSession(commands, [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/list', params: {} },
+    ])
+    expect(listRes.error).toBeUndefined()
+    expect(listRes.result.tools.map((tool: any) => tool.name).sort()).toEqual([
+      'count',
+      'list',
+      'show',
+    ])
+
+    const [, callRes] = await mcpSession(commands, [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/call', params: { name: 'list', arguments: {} } },
+    ])
+    expect(callRes.result.content).toEqual([{ type: 'text', text: '[{"id":"foo"}]' }])
+    expect(callRes.result.structuredContent).toBeUndefined()
+  })
+
+  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 +618,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()
+  })
 })

package/src/Mcp.ts

@@ -1,8 +1,9 @@
-import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server'
 import type { Readable, Writable } from 'node:stream'
 import { z } from 'zod'
 
 import * as Command from './internal/command.js'
+import { formatCtaBlock, type FormattedCtaBlock } from './internal/cta.js'
+import * as Json from './internal/json.js'
 import type { Handler as MiddlewareHandler } from './middleware.js'
 import * as Schema from './Schema.js'
 
@@ -13,7 +14,14 @@ export async function serve(
   commands: Map<string, any>,
   options: serve.Options = {},
 ): Promise<void> {
-  const server = new McpServer({ name, version })
+  // Lazy: only runs when actually serving MCP, so plain command runs don't pay for the SDK import.
+  const { fromJsonSchema, McpServer, StdioServerTransport } =
+    await import('@modelcontextprotocol/server')
+
+  const server = new McpServer(
+    { name, version },
+    options.instructions ? { instructions: options.instructions } : undefined,
+  )
 
   for (const tool of collectTools(commands, [])) {
     const mergedShape: Record<string, any> = {
@@ -27,7 +35,9 @@ export async function serve(
       {
         ...(tool.description ? { description: tool.description } : undefined),
         ...(hasInput ? { inputSchema: z.object(mergedShape) } : undefined),
-        ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : undefined),
+        ...(tool.outputSchema ? { outputSchema: fromJsonSchema(tool.outputSchema) } : undefined),
+        ...(tool.annotations ? { annotations: tool.annotations } : undefined),
+        ...(tool.instructions ? { _meta: { instructions: tool.instructions } } : undefined),
       } as never,
       async (...callArgs: any[]) => {
         // registerTool passes (args, extra) when inputSchema is set, (extra) when not
@@ -67,6 +77,8 @@ export declare namespace serve {
     vars?: z.ZodObject<any> | undefined
     /** CLI version string. */
     version?: string | undefined
+    /** Instructions describing how to use the server and its features. */
+    instructions?: string | undefined
   }
 }
 
@@ -88,6 +100,7 @@ export async function callTool(
 ): Promise<{
   content: { type: 'text'; text: string }[]
   structuredContent?: Record<string, unknown>
+  _meta?: { cta: FormattedCtaBlock } | undefined
   isError?: boolean
 }> {
   const allMiddleware = [
@@ -122,7 +135,7 @@ export async function callTool(
         if (progressToken !== undefined && options.sendNotification)
           await options.sendNotification({
             method: 'notifications/progress' as const,
-            params: { progressToken, progress: ++i, message: JSON.stringify(chunk) },
+            params: { progressToken, progress: ++i, message: Json.stringify(chunk) },
           })
       }
     } catch (err) {
@@ -131,21 +144,31 @@ export async function callTool(
         isError: true,
       }
     }
-    return { content: [{ type: 'text', text: JSON.stringify(chunks) }] }
+    return { content: [{ type: 'text', text: Json.stringify(chunks) }] }
   }
 
   if (!result.ok)
     return {
-      content: [{ type: 'text', text: result.error.message ?? 'Command failed' }],
+      content: [
+        {
+          type: 'text',
+          text: result.error.fieldErrors
+            ? JSON.stringify(result.error)
+            : (result.error.message ?? 'Command failed'),
+        },
+      ],
       isError: true,
     }
 
   const data = result.data ?? null
+  const jsonData = Json.normalize(data)
+  const cta = formatCtaBlock(options.name ?? tool.name, result.cta as Command.CtaBlock | undefined)
   return {
-    content: [{ type: 'text', text: JSON.stringify(data) }],
+    content: [{ type: 'text', text: Json.stringify(jsonData) }],
     ...(data !== null && tool.outputSchema
-      ? { structuredContent: data as Record<string, unknown> }
+      ? { structuredContent: jsonData as Record<string, unknown> }
       : undefined),
+    ...(cta ? { _meta: { cta } } : undefined),
   }
 }
 
@@ -161,10 +184,26 @@ export type ToolEntry = {
   description?: string | undefined
   inputSchema: { type: 'object'; properties: Record<string, unknown>; required?: string[] }
   outputSchema?: Record<string, unknown> | undefined
+  annotations?: ToolAnnotations | undefined
+  instructions?: string | undefined
   command: any
   middlewares?: MiddlewareHandler[] | undefined
 }
 
+/** MCP tool annotations that describe tool behavior to clients. */
+export type ToolAnnotations = {
+  /** A human-readable title for the tool. */
+  title?: string | undefined
+  /** If true, the tool does not modify its environment. Default: false. */
+  readOnlyHint?: boolean | undefined
+  /** If true, the tool may perform destructive updates to its environment. Meaningful only when readOnlyHint is false. Default: true. */
+  destructiveHint?: boolean | undefined
+  /** If true, calling the tool repeatedly with the same arguments has no additional effect. Meaningful only when readOnlyHint is false. Default: false. */
+  idempotentHint?: boolean | undefined
+  /** If true, the tool may interact with an open world of external entities. Default: true. */
+  openWorldHint?: boolean | undefined
+}
+
 /** @internal Recursively collects leaf commands as tool entries. */
 export function collectTools(
   commands: Map<string, any>,
@@ -182,21 +221,37 @@ export function collectTools(
       ]
       result.push(...collectTools(entry.commands, path, groupMw))
     } else {
+      const outputSchema = entry.output ? mcpOutputSchema(entry.output) : undefined
       result.push({
-        name: path.join('_'),
-        description: entry.description,
+        name: entry.mcp?.name ?? path.join('_'),
+        description: entry.mcp?.description ?? entry.description,
         inputSchema: buildToolSchema(entry.args, entry.options),
-        ...(entry.output
-          ? { outputSchema: Schema.toJsonSchema(entry.output) as Record<string, unknown> }
-          : undefined),
+        ...(outputSchema ? { outputSchema } : undefined),
+        ...(entry.mcp?.annotations ? { annotations: entry.mcp.annotations } : undefined),
+        ...(entry.mcp?.instructions ? { instructions: entry.mcp.instructions } : undefined),
         command: entry,
         ...(parentMiddlewares.length > 0 ? { middlewares: parentMiddlewares } : undefined),
       })
     }
   }
+  assertUniqueToolNames(result)
   return result.sort((a, b) => a.name.localeCompare(b.name))
 }
 
+function assertUniqueToolNames(tools: ToolEntry[]) {
+  const seen = new Set<string>()
+  for (const tool of tools) {
+    if (seen.has(tool.name)) throw new Error(`Duplicate MCP tool name: ${tool.name}`)
+    seen.add(tool.name)
+  }
+}
+
+function mcpOutputSchema(output: any): Record<string, unknown> | undefined {
+  const schema = Schema.toJsonSchema(output) as Record<string, unknown>
+  if (schema.type === 'object') return schema
+  return undefined
+}
+
 /** @internal Builds a merged JSON Schema from args and options Zod schemas. */
 function buildToolSchema(
   args: any | undefined,

package/src/Parser.test.ts

@@ -376,3 +376,176 @@ describe('parse', () => {
     expect(result.options).toEqual({ min: 1, max: 3 })
   })
 })
+
+describe('parseGlobals', () => {
+  test('extracts known globals and returns rest', () => {
+    const schema = z.object({ rpcUrl: z.string() })
+    const result = Parser.parseGlobals(['--rpc-url', 'http://example.com', 'deploy'], schema)
+    expect(result.parsed).toEqual({ rpcUrl: 'http://example.com' })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('unknown flags pass through to rest', () => {
+    const schema = z.object({ rpcUrl: z.string() })
+    const result = Parser.parseGlobals(
+      ['--rpc-url', 'http://example.com', '--unknown', 'val', 'deploy'],
+      schema,
+    )
+    expect(result.parsed).toEqual({ rpcUrl: 'http://example.com' })
+    expect(result.rest).toEqual(['--unknown', 'val', 'deploy'])
+  })
+
+  test('handles --flag=value syntax', () => {
+    const schema = z.object({ rpcUrl: z.string() })
+    const result = Parser.parseGlobals(['--rpc-url=http://example.com', 'deploy'], schema)
+    expect(result.parsed).toEqual({ rpcUrl: 'http://example.com' })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('handles short aliases', () => {
+    const schema = z.object({ rpcUrl: z.string() })
+    const result = Parser.parseGlobals(
+      ['-r', 'http://example.com', 'deploy'],
+      schema,
+      { rpcUrl: 'r' },
+    )
+    expect(result.parsed).toEqual({ rpcUrl: 'http://example.com' })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('handles boolean globals', () => {
+    const schema = z.object({ verbose: z.boolean().default(false) })
+    const result = Parser.parseGlobals(['--verbose', 'deploy'], schema)
+    expect(result.parsed).toEqual({ verbose: true })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('validates against schema', () => {
+    const schema = z.object({ count: z.number() })
+    expect(() => Parser.parseGlobals(['--count', 'not-a-number'], schema)).toThrow()
+  })
+
+  test('coerces string to number', () => {
+    const schema = z.object({ limit: z.number() })
+    const result = Parser.parseGlobals(['--limit', '42', 'deploy'], schema)
+    expect(result.parsed).toEqual({ limit: 42 })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('positionals pass through to rest', () => {
+    const schema = z.object({ verbose: z.boolean().default(false) })
+    const result = Parser.parseGlobals(['deploy', 'contract', '--verbose'], schema)
+    expect(result.parsed).toEqual({ verbose: true })
+    expect(result.rest).toEqual(['deploy', 'contract'])
+  })
+
+  test('-- separator: everything after -- passes through to rest including the --', () => {
+    const schema = z.object({ verbose: z.boolean().default(false) })
+    const result = Parser.parseGlobals(
+      ['--verbose', '--', '--unknown', 'positional', '--also-unknown'],
+      schema,
+    )
+    expect(result.parsed).toEqual({ verbose: true })
+    expect(result.rest).toEqual(['--', '--unknown', 'positional', '--also-unknown'])
+  })
+
+  test('stacked short aliases: -rv where both are known boolean globals', () => {
+    const schema = z.object({
+      recursive: z.boolean().default(false),
+      verbose: z.boolean().default(false),
+    })
+    const result = Parser.parseGlobals(['-rv', 'deploy'], schema, {
+      recursive: 'r',
+      verbose: 'v',
+    })
+    expect(result.parsed).toEqual({ recursive: true, verbose: true })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('count options: --verbose --verbose accumulates', () => {
+    const schema = z.object({ verbose: z.number().default(0).meta({ count: true }) })
+    const result = Parser.parseGlobals(['--verbose', '--verbose', 'deploy'], schema)
+    expect(result.parsed).toEqual({ verbose: 2 })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('array options: --tag foo --tag bar collects into array', () => {
+    const schema = z.object({ tag: z.array(z.string()).default([]) })
+    const result = Parser.parseGlobals(['--tag', 'foo', '--tag', 'bar', 'deploy'], schema)
+    expect(result.parsed).toEqual({ tag: ['foo', 'bar'] })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('unknown --no-* flags pass through to rest', () => {
+    const schema = z.object({ verbose: z.boolean().default(false) })
+    const result = Parser.parseGlobals(['--no-color', '--verbose'], schema)
+    expect(result.parsed).toEqual({ verbose: true })
+    expect(result.rest).toEqual(['--no-color'])
+  })
+
+  test('unknown --flag=value passes through as single token', () => {
+    const schema = z.object({ verbose: z.boolean().default(false) })
+    const result = Parser.parseGlobals(['--output=json', '--verbose'], schema)
+    expect(result.parsed).toEqual({ verbose: true })
+    expect(result.rest).toEqual(['--output=json'])
+  })
+
+  test('missing value for known flag throws ParseError', () => {
+    const schema = z.object({ rpcUrl: z.string() })
+    expect(() => Parser.parseGlobals(['--rpc-url'], schema)).toThrow(
+      expect.objectContaining({ name: 'Incur.ParseError' }),
+    )
+  })
+
+  test('stacked short: count in non-last position', () => {
+    const schema = z.object({
+      verbose: z.number().default(0).meta({ count: true }),
+      recursive: z.boolean().default(false),
+    })
+    const result = Parser.parseGlobals(['-vr'], schema, { verbose: 'v', recursive: 'r' })
+    expect(result.parsed).toEqual({ verbose: 1, recursive: true })
+  })
+
+  test('stacked short: non-boolean in non-last position throws', () => {
+    const schema = z.object({
+      output: z.string(),
+      verbose: z.boolean().default(false),
+    })
+    expect(() => Parser.parseGlobals(['-ov', 'file'], schema, { output: 'o', verbose: 'v' })).toThrow(
+      /must be last/,
+    )
+  })
+
+  test('short flag value-taking as last in stacked alias', () => {
+    const schema = z.object({
+      verbose: z.boolean().default(false),
+      output: z.string(),
+    })
+    const result = Parser.parseGlobals(['-vo', 'file', 'deploy'], schema, {
+      verbose: 'v',
+      output: 'o',
+    })
+    expect(result.parsed).toEqual({ verbose: true, output: 'file' })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('short flag missing value throws ParseError', () => {
+    const schema = z.object({ output: z.string() })
+    expect(() => Parser.parseGlobals(['-o'], schema, { output: 'o' })).toThrow(
+      expect.objectContaining({ name: 'Incur.ParseError' }),
+    )
+  })
+
+  test('known --no- negation for boolean global', () => {
+    const schema = z.object({ verbose: z.boolean().default(true) })
+    const result = Parser.parseGlobals(['--no-verbose', 'deploy'], schema)
+    expect(result.parsed).toEqual({ verbose: false })
+    expect(result.rest).toEqual(['deploy'])
+  })
+
+  test('known --flag=value with setOption', () => {
+    const schema = z.object({ tag: z.array(z.string()).default([]) })
+    const result = Parser.parseGlobals(['--tag=foo', '--tag=bar'], schema)
+    expect(result.parsed).toEqual({ tag: ['foo', 'bar'] })
+  })
+})