feat: custom global options (#98)

* feat: add Parser.parseGlobals for custom global option extraction

Permissive argv scanner that extracts known global flags and passes
unknown flags + positionals through to rest. Reuses all existing
Parser internals (createOptionNames, normalizeOptionName, coerce, etc).

* feat: add globals generic to middleware Context and command execution

Adds globals as a third generic on Handler, Context, and middleware()
factory following the existing InferVars/InferEnv pattern. Wires
globals into execute.Options and mwCtx construction.

* feat: render custom global options in help output

Extends globalOptionsLines, formatRoot, and formatCommand to accept an
optional globals schema. Custom globals render as a separate block
above the built-in global options using the existing optionEntries helper.

* feat: add global options to shell completions

Extends complete() to accept an optional globals descriptor. Global
flags are suggested alongside command-specific options with dedup.
Value resolution falls through from command options to globals.

* feat: wire global options into Cli.ts

Adds globals as 4th generic on Cli type, all create() overloads, and
create.Options. Stores globals config in WeakMap. Validates against
builtin flag collisions at create() and command option collisions at
command(). Extracts globals via Parser.parseGlobals after builtin
extraction in serveImpl. Passes globals to middleware context,
Help output, Completions, --llms manifests, and --schema output.

* fix: rename rest to commandRest to avoid redeclaration in serveImpl

* test: add globals integration, type-level, and parser unit tests

13 integration tests (middleware flow, aliases, defaults, routing,
help, --llms, --schema, conflicts, negation, position flexibility),
2 type-level tests (generic flow, alias constraint), and 8 parser
unit tests for parseGlobals.

* fix: globals parsing edge cases and collision detection

- Stop unknown flags from greedily eating the next token as a value
- Add -- separator handling in parseGlobals
- Wrap parseGlobals in try/catch for clean error envelopes
- Validate globalAlias values against reserved short flags (-h)
- Check command alias collisions with global aliases
- Include --no-{config} negation in builtin collision list
- Add globals to fetch gateway middleware context

* chore: remove duplicate tests and use toKebab in completions

- Delete redundant "stripped from argv" and "work with subcommands" tests
- Update validation error test to match new try/catch behavior
- Use toKebab import instead of inline regex in Completions.ts

* refactor: extract GlobalsDescriptor type, deduplicate across files

Define GlobalsDescriptor once in Cli.ts, replace 6 inline repetitions
across Cli.ts, Help.ts, and Completions.ts.

* chore: add changeset for custom global options

* fix: CI type errors — exactOptionalPropertyTypes and ts-expect-error

- Add undefined to GlobalsDescriptor.alias for exactOptionalPropertyTypes
- Restructure globalAlias type test to avoid tsc -b @ts-expect-error quirk

* test: close coverage gaps in completions, parser, cli, and help

- 5 completions tests (global flags, aliases, dedup, enum values, booleans)
- 7 parser tests (-- separator, stacked shorts, count, array, unknown --no-*,
  unknown --flag=value, missing value error)
- 3 cli tests (parseGlobals error envelope, -h alias conflict, command alias conflict)
- 2 help tests (deprecated globals rendering, globals with defaults in formatRoot)

* test: close remaining coverage gaps in parseGlobals and serveImpl

- 6 parser tests (stacked short count/non-boolean/value-taking, short
  missing value, known --no- negation, known --flag=value with array)
- 1 cli test (agent-mode error formatting for globals validation)

* fix: handle global option edge cases

* test: cover global options e2e

* chore: update changeset wording

* test: stabilize lazy import tracking

---------

Co-authored-by: jxom <7336481+jxom@users.noreply.github.com>

Author: franklad

.changeset/custom-global-options.md

@@ -0,0 +1,5 @@
+---
+"incur": minor
+---
+
+Added custom global options support via `globals` and `globalAlias` on `Cli.create()`.

src/Cli.test-d.ts

@@ -422,3 +422,24 @@ test('create() accepts config-file defaults options', () => {
     config: { files: [42] },
   })
 })
+
+test('globals type flows to middleware context', () => {
+  Cli.create('test', {
+    globals: z.object({ apiKey: z.string().optional() }),
+  }).use(async (c, next) => {
+    expectTypeOf(c.globals.apiKey).toEqualTypeOf<string | undefined>()
+    await next()
+  })
+})
+
+test('globalAlias keys are constrained to globals schema keys', () => {
+  Cli.create('test', {
+    globals: z.object({ apiKey: z.string() }),
+    globalAlias: { apiKey: 'k' },
+  })
+
+  const globals = z.object({ apiKey: z.string() })
+  // @ts-expect-error — 'foo' is not a key of the globals schema
+  const badAlias: Partial<Record<keyof z.output<typeof globals>, string>> = { foo: 'f' }
+  void badAlias
+})

src/Cli.test.ts

@@ -4310,7 +4310,7 @@ describe('Command.execute', () => {
   })
 })
 
-async function fetchJson(cli: Cli.Cli<any, any, any>, req: Request) {
+async function fetchJson(cli: Cli.Cli<any, any, any, any>, req: Request) {
   const res = await cli.fetch(req)
   const body = await res.json()
   body.meta.duration = '<stripped>'
@@ -5366,6 +5366,296 @@ describe('displayName', () => {
   })
 })
 
+describe('globals', () => {
+  test('globals are parsed and available in middleware', async () => {
+    const cli = Cli.create('test', {
+      globals: z.object({ rpcUrl: z.string() }),
+      vars: z.object({ rpcUrl: z.string().default('') }),
+    })
+      .use(async (c, next) => {
+        c.set('rpcUrl', c.globals.rpcUrl)
+        await next()
+      })
+      .command('ping', {
+        run(c) {
+          return { url: c.var.rpcUrl }
+        },
+      })
+
+    const { output } = await serve(cli, ['--rpc-url', 'http://example.com', 'ping', '--json'])
+    expect(JSON.parse(output)).toEqual({ url: 'http://example.com' })
+  })
+
+  test('globals aliases work', async () => {
+    const cli = Cli.create('test', {
+      globals: z.object({ rpcUrl: z.string() }),
+      globalAlias: { rpcUrl: 'r' },
+      vars: z.object({ rpcUrl: z.string().default('') }),
+    })
+      .use(async (c, next) => {
+        c.set('rpcUrl', c.globals.rpcUrl)
+        await next()
+      })
+      .command('ping', {
+        run(c) {
+          return { url: c.var.rpcUrl }
+        },
+      })
+
+    const { output } = await serve(cli, ['-r', 'http://example.com', 'ping', '--json'])
+    expect(JSON.parse(output)).toEqual({ url: 'http://example.com' })
+  })
+
+  test('globals with defaults work when not provided', async () => {
+    const cli = Cli.create('test', {
+      globals: z.object({ chain: z.string().default('mainnet') }),
+      vars: z.object({ chain: z.string().default('') }),
+    })
+      .use(async (c, next) => {
+        c.set('chain', c.globals.chain)
+        await next()
+      })
+      .command('ping', {
+        run(c) {
+          return { chain: c.var.chain }
+        },
+      })
+
+    const { output } = await serve(cli, ['ping', '--json'])
+    expect(JSON.parse(output)).toEqual({ chain: 'mainnet' })
+  })
+
+  test('globals appear in --help output', async () => {
+    const cli = Cli.create('test', {
+      globals: z.object({
+        rpcUrl: z.string().optional().describe('RPC endpoint URL'),
+      }),
+      globalAlias: { rpcUrl: 'r' },
+    }).command('ping', { run: () => ({}) })
+
+    const { output } = await serve(cli, ['--help'])
+    expect(output).toContain('Custom Global Options')
+    expect(output).toContain('--rpc-url')
+  })
+
+  test('informational commands do not require globals', async () => {
+    const cli = Cli.create('test', {
+      version: '1.0.0',
+      globals: z.object({
+        rpcUrl: z.string().describe('RPC endpoint URL'),
+      }),
+    }).command('ping', {
+      args: z.object({ target: z.string() }),
+      run: () => ({}),
+    })
+
+    const help = await serve(cli, ['--help'])
+    expect(help.exitCode).toBeUndefined()
+    expect(help.output).toContain('--rpc-url')
+
+    const schema = await serve(cli, ['ping', '--schema', '--format', 'json'])
+    expect(schema.exitCode).toBeUndefined()
+    expect(JSON.parse(schema.output).globals.properties.rpcUrl).toBeDefined()
+
+    const llms = await serve(cli, ['--llms', '--format', 'json'])
+    expect(llms.exitCode).toBeUndefined()
+    expect(JSON.parse(llms.output).globals.properties.rpcUrl).toBeDefined()
+
+    const version = await serve(cli, ['--version'])
+    expect(version.exitCode).toBeUndefined()
+    expect(version.output).toBe('1.0.0\n')
+  })
+
+  test('globals appear in --llms manifest', async () => {
+    const cli = Cli.create('test', {
+      globals: z.object({
+        rpcUrl: z.string().optional().describe('RPC endpoint URL'),
+      }),
+    }).command('ping', { description: 'Health check', run: () => ({}) })
+
+    const { output } = await serve(cli, ['--llms', '--format', 'json'])
+    const manifest = JSON.parse(output)
+    expect(manifest.globals).toBeDefined()
+    expect(manifest.globals.properties.rpcUrl).toBeDefined()
+  })
+
+  test('globals validation error shows message and exits 1', async () => {
+    const cli = Cli.create('test', {
+      globals: z.object({ limit: z.number() }),
+    }).command('ping', { run: () => ({}) })
+
+    const { output, exitCode } = await serve(cli, ['--limit', 'not-a-number', 'ping'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('Invalid input')
+  })
+
+  test('globals position is flexible', async () => {
+    const cli = Cli.create('test', {
+      globals: z.object({ rpcUrl: z.string() }),
+      vars: z.object({ rpcUrl: z.string().default('') }),
+    })
+      .use(async (c, next) => {
+        c.set('rpcUrl', c.globals.rpcUrl)
+        await next()
+      })
+      .command('deploy', {
+        run(c) {
+          return { url: c.var.rpcUrl }
+        },
+      })
+
+    const { output } = await serve(cli, ['deploy', '--rpc-url', 'http://x', '--json'])
+    expect(JSON.parse(output)).toEqual({ url: 'http://x' })
+  })
+
+  test('globals conflict with builtins errors at create() time', () => {
+    expect(() =>
+      Cli.create('test', {
+        globals: z.object({ format: z.string() }),
+      }),
+    ).toThrow(/conflicts with a built-in flag/)
+  })
+
+  test('command option conflicting with global errors at command() time', () => {
+    const cli = Cli.create('test', {
+      globals: z.object({ rpcUrl: z.string() }),
+    })
+    expect(() =>
+      cli.command('deploy', {
+        options: z.object({ rpcUrl: z.string() }),
+        run: () => ({}),
+      }),
+    ).toThrow(/conflicts with a global option/)
+  })
+
+  test('mounted root command option conflicting with global errors at command() time', () => {
+    const cli = Cli.create('test', {
+      globals: z.object({ rpcUrl: z.string() }),
+    })
+    const deploy = Cli.create('deploy', {
+      options: z.object({ rpcUrl: z.string() }),
+      run: () => ({}),
+    })
+
+    expect(() => cli.command(deploy)).toThrow(/conflicts with a global option/)
+  })
+
+  test('mounted subcommand option conflicting with global errors at command() time', () => {
+    const cli = Cli.create('test', {
+      globals: z.object({ rpcUrl: z.string() }),
+    })
+    const admin = Cli.create('admin').command('deploy', {
+      options: z.object({ rpcUrl: z.string() }),
+      run: () => ({}),
+    })
+
+    expect(() => cli.command(admin)).toThrow(/conflicts with a global option/)
+  })
+
+  test('boolean globals handle --no- negation', async () => {
+    const cli = Cli.create('test', {
+      globals: z.object({ dryRun: z.boolean().default(true) }),
+      vars: z.object({ dryRun: z.boolean().default(false) }),
+    })
+      .use(async (c, next) => {
+        c.set('dryRun', c.globals.dryRun)
+        await next()
+      })
+      .command('ping', {
+        run(c) {
+          return { dryRun: c.var.dryRun }
+        },
+      })
+
+    const { output } = await serve(cli, ['--no-dry-run', 'ping', '--json'])
+    expect(JSON.parse(output)).toEqual({ dryRun: false })
+  })
+
+  test('parseGlobals error produces clean error output with exit code 1', async () => {
+    const cli = Cli.create('test', {
+      globals: z.object({ rpcUrl: z.string() }),
+    }).command('ping', { run: () => ({}) })
+
+    const { output, exitCode } = await serve(cli, ['--rpc-url'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('Missing value for flag')
+  })
+
+  test('global alias collision with -h throws at create() time', () => {
+    expect(() =>
+      Cli.create('test', {
+        globals: z.object({ host: z.string().optional() }),
+        globalAlias: { host: 'h' },
+      }),
+    ).toThrow(/conflicts with a built-in short flag/)
+  })
+
+  test('command alias collision with global alias throws at command() time', () => {
+    const cli = Cli.create('test', {
+      globals: z.object({ rpcUrl: z.string().optional() }),
+      globalAlias: { rpcUrl: 'r' },
+    })
+    expect(() =>
+      cli.command('deploy', {
+        options: z.object({ region: z.string().optional() }),
+        alias: { region: 'r' },
+        run: () => ({}),
+      }),
+    ).toThrow(/conflicts with a global alias/)
+  })
+
+  test('globals validation error in agent mode outputs toon format', async () => {
+    ;(process.stdout as any).isTTY = false
+    const cli = Cli.create('test', {
+      globals: z.object({ limit: z.number() }),
+    }).command('ping', { run: () => ({}) })
+
+    const { output, exitCode } = await serve(cli, ['--limit', 'abc', 'ping'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('UNKNOWN')
+    ;(process.stdout as any).isTTY = true
+  })
+
+  test('globals appear in --schema output', async () => {
+    const cli = Cli.create('test', {
+      globals: z.object({
+        rpcUrl: z.string().optional().describe('RPC endpoint URL'),
+      }),
+    }).command('ping', {
+      args: z.object({ target: z.string() }),
+      run: () => ({}),
+    })
+
+    const { output } = await serve(cli, ['ping', '--schema', '--format', 'json'])
+    const parsed = JSON.parse(output)
+    expect(parsed.globals).toBeDefined()
+    expect(parsed.globals.properties.rpcUrl).toBeDefined()
+  })
+
+  test('globals are available in fetch middleware', async () => {
+    const cli = Cli.create('test', {
+      globals: z.object({ rpcUrl: z.string().default('fallback') }),
+      vars: z.object({ rpcUrl: z.string().default('') }),
+    })
+      .use(async (c, next) => {
+        c.set('rpcUrl', c.globals.rpcUrl)
+        await next()
+      })
+      .command('ping', {
+        options: z.object({ limit: z.coerce.number().default(0) }),
+        run(c) {
+          return { limit: c.options.limit, url: c.var.rpcUrl }
+        },
+      })
+
+    const { body } = await fetchJson(
+      cli,
+      new Request('http://localhost/ping?rpcUrl=http://example.com&limit=3'),
+    )
+    expect(body.data).toEqual({ limit: 3, url: 'http://example.com' })
+  })
+})
+
 test('--format rejects invalid format values', async () => {
   const cli = Cli.create('test').command('hello', {
     run: (c) => c.ok({ message: 'hi' }),