incur 0.3.5 → 0.3.7

package/src/Help.test.ts

@@ -141,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', () => {
@@ -258,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,10 +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
@@ -29,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')
 }
@@ -38,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. */
@@ -57,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. */
@@ -94,6 +99,7 @@ export function formatCommand(name: string, options: formatCommand.Options = {})
   const {
     alias,
     aliases,
+    configFlag,
     description,
     version,
     args,
@@ -199,7 +205,7 @@ export function formatCommand(name: string, options: formatCommand.Options = {})
     }
   }
 
-  if (!options.hideGlobalOptions) lines.push(...globalOptionsLines(root))
+  if (!options.hideGlobalOptions) lines.push(...globalOptionsLines(root, configFlag))
 
   // Environment Variables
   if (env) {
@@ -327,13 +333,8 @@ 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) {
@@ -355,6 +356,9 @@ function globalOptionsLines(root = false): string[] {
   }
 
   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])',
@@ -363,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(
     '',
@@ -380,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/Openapi.test.ts

@@ -1,4 +1,9 @@
-import { describe, expect, test } from 'vitest'
+import { describe, expect, test, vi } from 'vitest'
+
+vi.mock('./SyncSkills.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('./SyncSkills.js')>()
+  return { ...actual, readHash: () => undefined }
+})
 
 import { app as prefixedApp } from '../test/fixtures/hono-api-prefixed.js'
 import { app } from '../test/fixtures/hono-api.js'

package/src/Parser.test-d.ts

@@ -43,3 +43,25 @@ test('narrows both args and options together', () => {
   expectTypeOf(result.args).toEqualTypeOf<{ repo: string }>()
   expectTypeOf(result.options).toEqualTypeOf<{ limit: number }>()
 })
+
+test('defaults are typed from z.input of the options schema', () => {
+  const result = Parser.parse([], {
+    defaults: { limit: '5' },
+    options: z.object({ limit: z.coerce.number().default(30) }),
+  })
+  expectTypeOf(result.options).toEqualTypeOf<{ limit: number }>()
+})
+
+test('defaults do not leak any', () => {
+  type Options = z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>
+    saveDev: z.ZodOptional<z.ZodBoolean>
+  }>
+
+  expectTypeOf<Parser.parse.Options<undefined, Options>>().toEqualTypeOf<{
+    args?: undefined
+    alias?: Record<string, string> | undefined
+    defaults?: Partial<z.input<Options>> | undefined
+    options?: Options
+  }>()
+})

package/src/Parser.test.ts

@@ -252,4 +252,93 @@ describe('parse', () => {
     expect(result.args).toEqual({ repo: 'myrepo' })
     expect(result.options).toEqual({ limit: 5 })
   })
+
+  test('applies config defaults when argv omits an option', () => {
+    const result = Parser.parse([], {
+      defaults: { limit: 10 },
+      options: z.object({ limit: z.number().default(30) }),
+    })
+    expect(result.options).toEqual({ limit: 10 })
+  })
+
+  test('argv overrides config defaults', () => {
+    const result = Parser.parse(['--limit', '5'], {
+      defaults: { limit: 10 },
+      options: z.object({ limit: z.number().default(30) }),
+    })
+    expect(result.options).toEqual({ limit: 5 })
+  })
+
+  test('argv arrays replace config arrays', () => {
+    const result = Parser.parse(['--label', 'bug', '--label', 'feature'], {
+      defaults: { label: ['ops'] },
+      options: z.object({ label: z.array(z.string()).default([]) }),
+    })
+    expect(result.options).toEqual({ label: ['bug', 'feature'] })
+  })
+
+  test('kebab-case config keys map to camelCase schema names', () => {
+    const result = Parser.parse([], {
+      defaults: { 'save-dev': true } as any,
+      options: z.object({ saveDev: z.boolean().default(false) }),
+    })
+    expect(result.options).toEqual({ saveDev: true })
+  })
+
+  test('throws ParseError on unknown config option keys', () => {
+    expect(() =>
+      Parser.parse([], {
+        defaults: { missing: true } as any,
+        options: z.object({ saveDev: z.boolean().default(false) }),
+      }),
+    ).toThrow(expect.objectContaining({ name: 'Incur.ParseError' }))
+  })
+
+  test('throws ValidationError for invalid config defaults when argv does not override them', () => {
+    expect(() =>
+      Parser.parse([], {
+        defaults: { limit: 'oops' } as any,
+        options: z.object({ limit: z.number() }),
+      }),
+    ).toThrow(expect.objectContaining({ name: 'Incur.ValidationError' }))
+  })
+
+  test('argv overrides invalid config defaults', () => {
+    const result = Parser.parse(['--limit', '5'], {
+      defaults: { limit: 'oops' } as any,
+      options: z.object({ limit: z.number() }),
+    })
+    expect(result.options).toEqual({ limit: 5 })
+  })
+
+  test('defaults with no options schema throws on non-empty defaults', () => {
+    expect(() =>
+      Parser.parse([], {
+        defaults: { limit: 10 } as any,
+      }),
+    ).toThrow(expect.objectContaining({ name: 'Incur.ParseError' }))
+  })
+
+  test('defaults with no options schema and empty defaults is a no-op', () => {
+    const result = Parser.parse([], { defaults: {} as any })
+    expect(result.options).toEqual({})
+  })
+
+  test('config array defaults are used when argv omits the option', () => {
+    const result = Parser.parse([], {
+      defaults: { label: ['bug', 'feature'] },
+      options: z.object({ label: z.array(z.string()).default([]) }),
+    })
+    expect(result.options).toEqual({ label: ['bug', 'feature'] })
+  })
+
+  test('refined option schemas validate only the merged winning values', () => {
+    const result = Parser.parse(['--min', '1', '--max', '3'], {
+      defaults: { min: 'oops' } as any,
+      options: z
+        .object({ min: z.number(), max: z.number() })
+        .refine((value) => value.min < value.max, { message: 'min must be less than max' }),
+    })
+    expect(result.options).toEqual({ min: 1, max: 3 })
+  })
 })

package/src/Parser.ts

@@ -2,29 +2,20 @@ import type { z } from 'zod'
 
 import type { FieldError } from './Errors.js'
 import { ParseError, ValidationError } from './Errors.js'
+import { isRecord, toKebab } from './internal/helpers.js'
 
 /** Parses raw argv tokens against Zod schemas for args and options. */
 export function parse<
   const args extends z.ZodObject<any> | undefined = undefined,
   const options extends z.ZodObject<any> | undefined = undefined,
 >(argv: string[], options: parse.Options<args, options> = {}): parse.ReturnType<args, options> {
-  const { args: argsSchema, options: optionsSchema, alias } = options
+  const { args: argsSchema, options: optionsSchema, alias, defaults } = options
 
-  // Build reverse alias map: short char → long name
-  const aliasToName = new Map<string, string>()
-  if (alias) for (const [name, short] of Object.entries(alias)) aliasToName.set(short, name)
-
-  // Known option names from schema, plus kebab-case → camelCase map
-  const knownOptions = new Set(optionsSchema ? Object.keys(optionsSchema.shape) : [])
-  const kebabToCamel = new Map<string, string>()
-  for (const name of knownOptions) {
-    const kebab = name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
-    if (kebab !== name) kebabToCamel.set(kebab, name)
-  }
+  const optionNames = createOptionNames(optionsSchema, alias)
 
   // First pass: split argv into positional tokens and raw option values
   const positionals: string[] = []
-  const rawOptions: Record<string, unknown> = {}
+  const rawArgvOptions: Record<string, unknown> = {}
 
   let i = 0
   while (i < argv.length) {
@@ -32,36 +23,34 @@ export function parse<
 
     if (token.startsWith('--no-') && token.length > 5) {
       // --no-flag negation
-      const raw = token.slice(5)
-      const name = kebabToCamel.get(raw) ?? raw
-      if (!knownOptions.has(name)) throw new ParseError({ message: `Unknown flag: ${token}` })
-      rawOptions[name] = false
+      const name = normalizeOptionName(token.slice(5), optionNames)
+      if (!name) throw new ParseError({ message: `Unknown flag: ${token}` })
+      rawArgvOptions[name] = false
       i++
     } else if (token.startsWith('--')) {
       const eqIdx = token.indexOf('=')
       if (eqIdx !== -1) {
         // --flag=value
         const raw = token.slice(2, eqIdx)
-        const name = kebabToCamel.get(raw) ?? raw
-        if (!knownOptions.has(name)) throw new ParseError({ message: `Unknown flag: --${raw}` })
-        setOption(rawOptions, name, token.slice(eqIdx + 1), optionsSchema)
+        const name = normalizeOptionName(raw, optionNames)
+        if (!name) throw new ParseError({ message: `Unknown flag: --${raw}` })
+        setOption(rawArgvOptions, name, token.slice(eqIdx + 1), optionsSchema)
         i++
       } else {
         // --flag [value]
-        const raw = token.slice(2)
-        const name = kebabToCamel.get(raw) ?? raw
-        if (!knownOptions.has(name)) throw new ParseError({ message: `Unknown flag: ${token}` })
+        const name = normalizeOptionName(token.slice(2), optionNames)
+        if (!name) throw new ParseError({ message: `Unknown flag: ${token}` })
         if (isCountOption(name, optionsSchema)) {
-          rawOptions[name] = ((rawOptions[name] as number) ?? 0) + 1
+          rawArgvOptions[name] = ((rawArgvOptions[name] as number) ?? 0) + 1
           i++
         } else if (isBooleanOption(name, optionsSchema)) {
-          rawOptions[name] = true
+          rawArgvOptions[name] = true
           i++
         } else {
           const value = argv[i + 1]
           if (value === undefined)
             throw new ParseError({ message: `Missing value for flag: ${token}` })
-          setOption(rawOptions, name, value, optionsSchema)
+          setOption(rawArgvOptions, name, value, optionsSchema)
           i += 2
         }
       }
@@ -70,28 +59,28 @@ export function parse<
       const chars = token.slice(1)
       for (let j = 0; j < chars.length; j++) {
         const short = chars[j]!
-        const name = aliasToName.get(short)
+        const name = optionNames.aliasToName.get(short)
         if (!name) throw new ParseError({ message: `Unknown flag: -${short}` })
         const isLast = j === chars.length - 1
         if (!isLast) {
           if (isCountOption(name, optionsSchema)) {
-            rawOptions[name] = ((rawOptions[name] as number) ?? 0) + 1
+            rawArgvOptions[name] = ((rawArgvOptions[name] as number) ?? 0) + 1
           } else if (isBooleanOption(name, optionsSchema)) {
-            rawOptions[name] = true
+            rawArgvOptions[name] = true
           } else {
             throw new ParseError({
               message: `Non-boolean flag -${short} must be last in a stacked alias`,
             })
           }
         } else if (isCountOption(name, optionsSchema)) {
-          rawOptions[name] = ((rawOptions[name] as number) ?? 0) + 1
+          rawArgvOptions[name] = ((rawArgvOptions[name] as number) ?? 0) + 1
         } else if (isBooleanOption(name, optionsSchema)) {
-          rawOptions[name] = true
+          rawArgvOptions[name] = true
         } else {
           const value = argv[i + 1]
           if (value === undefined)
             throw new ParseError({ message: `Missing value for flag: -${short}` })
-          setOption(rawOptions, name, value, optionsSchema)
+          setOption(rawArgvOptions, name, value, optionsSchema)
           i++
         }
       }
@@ -117,15 +106,19 @@ export function parse<
   // Validate args through zod
   const args = argsSchema ? zodParse(argsSchema, rawArgs) : {}
 
+  const rawDefaults = normalizeOptionDefaults(defaults, optionsSchema, optionNames)
+
   // Coerce raw option values before zod validation
   if (optionsSchema) {
-    for (const [name, value] of Object.entries(rawOptions)) {
-      rawOptions[name] = coerce(value, name, optionsSchema)
+    for (const [name, value] of Object.entries(rawArgvOptions)) {
+      rawArgvOptions[name] = coerce(value, name, optionsSchema)
     }
   }
 
+  const mergedOptions = { ...rawDefaults, ...rawArgvOptions }
+
   // Validate options through zod
-  const parsedOptions = optionsSchema ? zodParse(optionsSchema, rawOptions) : {}
+  const parsedOptions = optionsSchema ? zodParse(optionsSchema, mergedOptions) : {}
 
   return { args, options: parsedOptions } as parse.ReturnType<args, options>
 }
@@ -138,6 +131,8 @@ export declare namespace parse {
   > = {
     /** Zod schema for positional arguments. Keys define order. */
     args?: args
+    /** Config-backed option defaults merged before argv parsing. */
+    defaults?: options extends z.ZodObject<any> ? Partial<z.input<options>> | undefined : undefined
     /** Zod schema for named options/flags. */
     options?: options
     /** Map of option names to single-char aliases. */
@@ -155,6 +150,62 @@ export declare namespace parse {
   }
 }
 
+type OptionNames = {
+  aliasToName: Map<string, string>
+  kebabToCamel: Map<string, string>
+  knownOptions: Set<string>
+}
+
+/** Builds lookup tables for option names and short aliases. */
+function createOptionNames(
+  schema: z.ZodObject<any> | undefined,
+  alias: Record<string, string> | undefined,
+): OptionNames {
+  const aliasToName = new Map<string, string>()
+  if (alias) for (const [name, short] of Object.entries(alias)) aliasToName.set(short, name)
+
+  const knownOptions = new Set(schema ? Object.keys(schema.shape) : [])
+  const kebabToCamel = new Map<string, string>()
+  for (const name of knownOptions) {
+    const kebab = toKebab(name)
+    if (kebab !== name) kebabToCamel.set(kebab, name)
+  }
+
+  return { aliasToName, kebabToCamel, knownOptions }
+}
+
+/** Normalizes a long option name, accepting kebab-case aliases for camelCase schema keys. */
+function normalizeOptionName(raw: string, options: OptionNames): string | undefined {
+  const name = options.kebabToCamel.get(raw) ?? raw
+  return options.knownOptions.has(name) ? name : undefined
+}
+
+/** Normalizes config-backed defaults and validates config structure/key names. */
+function normalizeOptionDefaults(
+  defaults: unknown,
+  schema: z.ZodObject<any> | undefined,
+  optionNames: OptionNames,
+): Record<string, unknown> {
+  if (defaults === undefined) return {}
+  if (!isRecord(defaults))
+    throw new ParseError({
+      message: 'Invalid config section: expected an object of option defaults',
+    })
+  if (!schema) {
+    const [first] = Object.keys(defaults)
+    if (first) throw new ParseError({ message: `Unknown config option: ${first}` })
+    return {}
+  }
+
+  const normalized: Record<string, unknown> = {}
+  for (const [rawName, value] of Object.entries(defaults)) {
+    const name = normalizeOptionName(rawName, optionNames)
+    if (!name) throw new ParseError({ message: `Unknown config option: ${rawName}` })
+    normalized[name] = value
+  }
+  return normalized
+}
+
 /** Unwraps ZodDefault/ZodOptional to get the inner type. */
 function unwrap(schema: z.ZodType): z.ZodType {
   let s = schema as any

package/src/bin.ts

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
+import fs from 'node:fs/promises'
 import path from 'node:path'
 import { z } from 'zod'
 
 import * as Cli from './Cli.js'
+import * as ConfigSchema from './internal/configSchema.js'
+import { importCli } from './internal/utils.js'
 import * as Typegen from './Typegen.js'
 
 const cli = Cli.create('incur', {
@@ -15,6 +18,10 @@ const cli = Cli.create('incur', {
 }).command('gen', {
   description: 'Generate type definitions for development.',
   options: z.object({
+    configSchema: z
+      .boolean()
+      .optional()
+      .describe('Generate config JSON Schema (auto-detected by default)'),
     dir: z.string().optional().describe('Project root directory'),
     entry: z.string().optional().describe('Entrypoint path (absolute)'),
     output: z.string().optional().describe('Output path (absolute)'),
@@ -23,8 +30,20 @@ const cli = Cli.create('incur', {
     const dir = c.options.dir ?? '.'
     const entry = c.options.entry ?? dir
     const output = c.options.output ?? path.join(dir, 'incur.generated.ts')
-    await Typegen.generate(entry, output)
-    return { dir, entry, output }
+
+    const cli = await importCli(entry)
+    await fs.writeFile(output, Typegen.fromCli(cli))
+
+    const result: Record<string, unknown> = { dir, entry, output }
+
+    const configSchema = c.options.configSchema ?? ConfigSchema.hasConfig(cli)
+    if (configSchema) {
+      const schemaOutput = path.join(path.dirname(output), 'config.schema.json')
+      await fs.writeFile(schemaOutput, JSON.stringify(ConfigSchema.fromCli(cli), null, 2) + '\n')
+      result.configSchema = schemaOutput
+    }
+
+    return result
   },
 })