incur 0.4.7 → 0.4.9

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>,
@@ -189,6 +228,8 @@ export function collectTools(
         ...(entry.output
           ? { outputSchema: Schema.toJsonSchema(entry.output) as Record<string, unknown> }
           : 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),
       })

package/src/Openapi.test.ts

@@ -203,6 +203,69 @@ describe('cli integration', () => {
     })
   }
 
+  function createSecurityHeaderCli() {
+    return Cli.create('test', { description: 'test' }).command('api', {
+      fetch(request) {
+        return Response.json({ apiKey: request.headers.get('x-api-key') })
+      },
+      openapi: {
+        openapi: '3.0.0',
+        info: { title: 'Test API', version: '1.0.0' },
+        components: {
+          securitySchemes: {
+            tokenAuth: {
+              type: 'apiKey',
+              in: 'header',
+              name: 'x-api-key',
+              description: 'Access token',
+            },
+          },
+        },
+        security: [{ tokenAuth: [] }],
+        paths: {
+          '/secret': {
+            get: {
+              operationId: 'getSecret',
+              summary: 'Get secret',
+              responses: { '200': { description: 'OK' } },
+            },
+          },
+        },
+      },
+    })
+  }
+
+  function createBearerAuthCli() {
+    return Cli.create('test', { description: 'test' }).command('api', {
+      fetch(request) {
+        return Response.json({ authorization: request.headers.get('authorization') })
+      },
+      openapi: {
+        openapi: '3.0.0',
+        info: { title: 'Test API', version: '1.0.0' },
+        components: {
+          securitySchemes: {
+            bearerAuth: {
+              type: 'http',
+              scheme: 'bearer',
+              description: 'Bearer credential',
+            },
+          },
+        },
+        security: [{ bearerAuth: [] }],
+        paths: {
+          '/secret': {
+            get: {
+              operationId: 'getSecret',
+              summary: 'Get secret',
+              responses: { '200': { description: 'OK' } },
+            },
+          },
+        },
+      },
+    })
+  }
+
   test('GET /users via operationId', async () => {
     const { output } = await serve(createCli(), ['api', 'listUsers'])
     expect(output).toContain('Alice')
@@ -230,6 +293,122 @@ describe('cli integration', () => {
     expect(json(output).limit).toBe(5)
   })
 
+  test('security headers become generated command options', async () => {
+    const cli = createSecurityHeaderCli()
+    const { output } = await serve(cli, [
+      'api',
+      'getSecret',
+      '--x-api-key',
+      'secret',
+      '--format',
+      'json',
+    ])
+
+    expect(json(output).apiKey).toMatchInlineSnapshot(`"secret"`)
+  })
+
+  test('security header options appear in generated command help', async () => {
+    const { output } = await serve(createSecurityHeaderCli(), ['api', 'getSecret', '--help'])
+
+    expect(output).toMatchInlineSnapshot(`
+      "test api getSecret — Get secret
+
+      Usage: test api getSecret [options]
+
+      Options:
+        --x-api-key <string>  Access token
+
+      Global Options:
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
+        --format <toon|json|yaml|md|jsonl>  Output format
+        --full-output                       Show full output envelope
+        --help                              Show help
+        --llms, --llms-full                 Print LLM-readable manifest
+        --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
+      "
+    `)
+  })
+
+  test('bearer auth becomes an authorization option', async () => {
+    const { output } = await serve(createBearerAuthCli(), [
+      'api',
+      'getSecret',
+      '--authorization',
+      'Bearer secret',
+      '--format',
+      'json',
+    ])
+
+    expect(json(output).authorization).toMatchInlineSnapshot(`"Bearer secret"`)
+  })
+
+  test('bearer auth option appears in generated command help', async () => {
+    const { output } = await serve(createBearerAuthCli(), ['api', 'getSecret', '--help'])
+
+    expect(output).toMatchInlineSnapshot(`
+      "test api getSecret — Get secret
+
+      Usage: test api getSecret [options]
+
+      Options:
+        --authorization <string>  Bearer credential
+
+      Global Options:
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
+        --format <toon|json|yaml|md|jsonl>  Output format
+        --full-output                       Show full output envelope
+        --help                              Show help
+        --llms, --llms-full                 Print LLM-readable manifest
+        --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
+      "
+    `)
+  })
+
+  test('header parameters become generated command options', async () => {
+    const cli = Cli.create('test', { description: 'test' }).command('api', {
+      fetch(request) {
+        return Response.json({ requestId: request.headers.get('x-request-id') })
+      },
+      openapi: {
+        openapi: '3.0.0',
+        info: { title: 'Test API', version: '1.0.0' },
+        paths: {
+          '/secret': {
+            get: {
+              operationId: 'getSecret',
+              summary: 'Get secret',
+              parameters: [
+                {
+                  name: 'x-request-id',
+                  in: 'header',
+                  schema: { type: 'string' },
+                  description: 'Request ID',
+                },
+              ],
+              responses: { '200': { description: 'OK' } },
+            },
+          },
+        },
+      },
+    })
+    const { output } = await serve(cli, [
+      'api',
+      'getSecret',
+      '--x-request-id',
+      'request_test',
+      '--format',
+      'json',
+    ])
+
+    expect(json(output).requestId).toMatchInlineSnapshot(`"request_test"`)
+  })
+
   test('loads OpenAPI commands from a spec URL string', async () => {
     const cli = Cli.create('test', { description: 'test' }).command('api', {
       fetch: app.fetch,

package/src/Openapi.ts

@@ -12,7 +12,17 @@ import { dereference } from './internal/dereference.js'
 import * as Schema from './Schema.js'
 
 /** A minimal OpenAPI 3.x spec shape. Accepts both hand-written specs and generated ones (e.g. from `@hono/zod-openapi`). */
-export type OpenAPISpec = { paths?: {} | undefined }
+export type OpenAPISpec = {
+  components?:
+    | {
+        securitySchemes?: Record<string, SecurityScheme> | undefined
+      }
+    | undefined
+  info?: Record<string, unknown> | undefined
+  openapi?: string | undefined
+  paths?: {} | undefined
+  security?: readonly SecurityRequirement[] | undefined
+}
 
 /** OpenAPI document source accepted by fetch-backed CLI commands. */
 export type OpenAPISource = OpenAPISpec | string | URL
@@ -72,6 +82,7 @@ type Operation = {
   parameters?: readonly Parameter[] | undefined
   requestBody?: RequestBody | undefined
   responses?: Record<string, unknown> | undefined
+  security?: readonly SecurityRequirement[] | undefined
   summary?: string | undefined
 }
 
@@ -88,6 +99,20 @@ type RequestBody = {
   required?: boolean | undefined
 }
 
+type SecurityRequirement = Record<string, readonly string[]>
+
+type SecurityScheme = {
+  description?: string | undefined
+  in?: 'cookie' | 'header' | 'query' | undefined
+  name?: string | undefined
+  scheme?: string | undefined
+  type?: string | undefined
+}
+
+type HeaderParameter = Parameter & {
+  optionName: string
+}
+
 /** A fetch handler. */
 type FetchHandler = (req: Request) => Response | Promise<Response>
 
@@ -356,6 +381,10 @@ export async function generateCommands(
 
     const pathParams = (op.parameters ?? []).filter((p) => p.in === 'path')
     const queryParams = (op.parameters ?? []).filter((p) => p.in === 'query')
+    const headerParams = headerOptions([
+      ...(op.parameters ?? []).filter((p) => p.in === 'header'),
+      ...securityHeaderParams(resolved, op),
+    ])
 
     const bodySchema = op.requestBody?.content?.['application/json']?.schema
     const bodyProps = (bodySchema?.properties ?? {}) as Record<string, Record<string, unknown>>
@@ -376,16 +405,28 @@ export async function generateCommands(
 
     // Build options Zod schema from query params + body properties
     const optShape: Record<string, z.ZodType> = {}
+    const usedOptionNames = new Set<string>()
     for (const p of queryParams) {
       let zodType = p.schema ? toZod(p.schema) : z.string()
       if (!p.required) zodType = zodType.optional()
       if (p.description) zodType = zodType.describe(p.description)
       optShape[p.name] = coerceIfNeeded(zodType)
+      usedOptionNames.add(p.name)
     }
     for (const [key, schema] of Object.entries(bodyProps)) {
       let zodType = toZod(schema)
       if (!bodyRequired.has(key)) zodType = zodType.optional()
       optShape[key] = zodType
+      usedOptionNames.add(key)
+    }
+    for (const p of headerParams) {
+      const optionName = resolveHeaderOptionName(p.optionName, usedOptionNames)
+      p.optionName = optionName
+      let zodType = p.schema ? toZod(p.schema) : z.string()
+      if (!p.required) zodType = zodType.optional()
+      zodType = zodType.describe(p.description ?? `${p.name} header`)
+      optShape[optionName] = coerceIfNeeded(zodType)
+      usedOptionNames.add(optionName)
     }
     const optionsSchema = Object.keys(optShape).length > 0 ? z.object(optShape) : undefined
 
@@ -398,6 +439,7 @@ export async function generateCommands(
         fetch,
         httpMethod,
         path,
+        headerParams,
         pathParams,
         queryParams,
         bodyProps,
@@ -438,6 +480,77 @@ function openapiOperations(paths: Record<string, Record<string, unknown>>) {
   return operations
 }
 
+function securityHeaderParams(spec: OpenAPISpec, operation: Operation): Parameter[] {
+  const schemes = spec.components?.securitySchemes ?? {}
+  const requirements = operation.security ?? spec.security ?? []
+  const headers: Parameter[] = []
+
+  for (const requirement of requirements)
+    for (const name of Object.keys(requirement)) {
+      const scheme = schemes[name]
+      const parameter = securityHeaderParam(name, scheme)
+      if (parameter) headers.push(parameter)
+    }
+
+  return headers
+}
+
+function securityHeaderParam(
+  name: string,
+  scheme: SecurityScheme | undefined,
+): Parameter | undefined {
+  if (!scheme) return undefined
+  // `apiKey` is OpenAPI's generic name for a credential carried in a
+  // header/query/cookie, not an incur- or Cadent-specific API key concept.
+  if (scheme.type === 'apiKey' && scheme.in === 'header' && scheme.name)
+    return {
+      description: scheme.description ?? `${scheme.name} header`,
+      in: 'header',
+      name: scheme.name,
+      required: false,
+      schema: { type: 'string' },
+    }
+
+  if (scheme.type === 'http' && authorizationSchemes.has(scheme.scheme?.toLowerCase() ?? ''))
+    return {
+      description: scheme.description ?? `${name} authorization header`,
+      in: 'header',
+      name: 'authorization',
+      required: false,
+      schema: { type: 'string' },
+    }
+
+  return undefined
+}
+
+const authorizationSchemes = new Set(['basic', 'bearer'])
+
+function headerOptions(parameters: Parameter[]): HeaderParameter[] {
+  const seen = new Set<string>()
+  const headers: HeaderParameter[] = []
+
+  for (const parameter of parameters) {
+    const normalized = parameter.name.toLowerCase()
+    if (seen.has(normalized)) continue
+    seen.add(normalized)
+    headers.push({ ...parameter, optionName: normalized })
+  }
+
+  return headers
+}
+
+function resolveHeaderOptionName(optionName: string, used: Set<string>) {
+  if (!used.has(optionName)) return optionName
+
+  const prefix = `header-${optionName}`
+  if (!used.has(prefix)) return prefix
+
+  for (let index = 2; ; index++) {
+    const candidate = `${prefix}-${index}`
+    if (!used.has(candidate)) return candidate
+  }
+}
+
 function getNamespaceInfo(operations: OperationEntry[]) {
   const pathOperations = new Map<string, number>()
   const parentPaths = new Set<string>()
@@ -565,6 +678,7 @@ function createHandler(config: {
   basePath?: string | undefined
   bodyProps: Record<string, Record<string, unknown>>
   fetch: FetchHandler
+  headerParams: HeaderParameter[]
   httpMethod: string
   path: string
   pathParams: Parameter[]
@@ -604,7 +718,13 @@ function createHandler(config: {
       query,
     }
 
-    if (body) input.headers.set('content-type', 'application/json')
+    for (const p of config.headerParams) {
+      const value = options[p.optionName]
+      if (value !== undefined) input.headers.set(p.name, String(value))
+    }
+
+    if (body && !input.headers.has('content-type'))
+      input.headers.set('content-type', 'application/json')
 
     const request = Fetch.buildRequest(input)
     const response = await config.fetch(request)

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'] })
+  })
+})