incur 0.3.5 → 0.3.6

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
   },
 })
 

package/src/e2e.test.ts

@@ -2204,7 +2204,7 @@ describe('fetch gateway', () => {
   })
 
   test('query params from --key value', async () => {
-    const { output } = await serve(createApp(), ['api', 'users', '--limit', '5'])
+    await serve(createApp(), ['api', 'users', '--limit', '5'])
     const { output: jsonOut } = await serve(createApp(), [
       'api',
       'users',

package/src/internal/command.ts

@@ -71,6 +71,7 @@ export async function execute(command: any, options: execute.Options): Promise<e
       const parsed = Parser.parse(argv, {
         alias: command.alias as Record<string, string> | undefined,
         args: command.args,
+        defaults: options.defaults,
         options: command.options,
       })
       args = parsed.args
@@ -269,6 +270,8 @@ export declare namespace execute {
     agent: boolean
     /** Raw positional tokens (already separated from flags). For HTTP/MCP, pass `[]`. */
     argv: string[]
+    /** Default option values from config file. */
+    defaults?: Record<string, unknown> | undefined
     /** CLI-level env schema. */
     env?: z.ZodObject<any> | undefined
     /** Source for environment variables. Defaults to `process.env`. */

package/src/internal/configSchema.test.ts

@@ -0,0 +1,193 @@
+import { Cli, z } from 'incur'
+
+import * as ConfigSchema from './configSchema.js'
+
+describe('fromCli', () => {
+  test('generates schema for root options and leaf commands', () => {
+    const cli = Cli.create('test', {
+      options: z.object({
+        verbose: z.boolean().default(false),
+      }),
+    })
+    cli.command('echo', {
+      options: z.object({
+        prefix: z.string().default(''),
+        upper: z.boolean().default(false),
+      }),
+      run: (c) => c.options,
+    })
+
+    const schema = ConfigSchema.fromCli(cli)
+    expect(schema).toMatchInlineSnapshot(`
+      {
+        "additionalProperties": false,
+        "properties": {
+          "$schema": {
+            "type": "string",
+          },
+          "commands": {
+            "additionalProperties": false,
+            "properties": {
+              "echo": {
+                "additionalProperties": false,
+                "properties": {
+                  "options": {
+                    "additionalProperties": false,
+                    "properties": {
+                      "prefix": {
+                        "default": "",
+                        "type": "string",
+                      },
+                      "upper": {
+                        "default": false,
+                        "type": "boolean",
+                      },
+                    },
+                    "type": "object",
+                  },
+                },
+                "type": "object",
+              },
+            },
+            "type": "object",
+          },
+          "options": {
+            "additionalProperties": false,
+            "properties": {
+              "verbose": {
+                "default": false,
+                "type": "boolean",
+              },
+            },
+            "type": "object",
+          },
+        },
+        "type": "object",
+      }
+    `)
+  })
+
+  test('generates schema for nested command groups', () => {
+    const project = Cli.create('project')
+    project.command('list', {
+      options: z.object({
+        limit: z.number().default(10),
+        label: z.array(z.string()).default([]),
+      }),
+      run: (c) => c.options,
+    })
+
+    const cli = Cli.create('test')
+    cli.command(project)
+
+    const schema = ConfigSchema.fromCli(cli)
+    expect(schema).toMatchInlineSnapshot(`
+      {
+        "additionalProperties": false,
+        "properties": {
+          "$schema": {
+            "type": "string",
+          },
+          "commands": {
+            "additionalProperties": false,
+            "properties": {
+              "project": {
+                "additionalProperties": false,
+                "properties": {
+                  "commands": {
+                    "additionalProperties": false,
+                    "properties": {
+                      "list": {
+                        "additionalProperties": false,
+                        "properties": {
+                          "options": {
+                            "additionalProperties": false,
+                            "properties": {
+                              "label": {
+                                "default": [],
+                                "items": {
+                                  "type": "string",
+                                },
+                                "type": "array",
+                              },
+                              "limit": {
+                                "default": 10,
+                                "type": "number",
+                              },
+                            },
+                            "type": "object",
+                          },
+                        },
+                        "type": "object",
+                      },
+                    },
+                    "type": "object",
+                  },
+                },
+                "type": "object",
+              },
+            },
+            "type": "object",
+          },
+        },
+        "type": "object",
+      }
+    `)
+  })
+
+  test('returns schema with only $schema for cli with no commands', () => {
+    const cli = Cli.create('test')
+    const schema = ConfigSchema.fromCli(cli)
+    expect(schema).toEqual({
+      type: 'object',
+      additionalProperties: false,
+      properties: { $schema: { type: 'string' } },
+    })
+  })
+
+  test('skips fetch gateway commands', () => {
+    const cli = Cli.create('test')
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+    cli.command('api', {
+      description: 'API gateway',
+      fetch: () => new Response('ok'),
+    })
+
+    const schema = ConfigSchema.fromCli(cli)
+    const commandKeys = Object.keys((schema as any).properties.commands.properties)
+    expect(commandKeys).toEqual(['echo'])
+  })
+
+  test('includes commands without options as empty objects', () => {
+    const cli = Cli.create('test')
+    cli.command('ping', {
+      run: () => 'pong',
+    })
+
+    const schema = ConfigSchema.fromCli(cli)
+    expect(schema).toMatchInlineSnapshot(`
+      {
+        "additionalProperties": false,
+        "properties": {
+          "$schema": {
+            "type": "string",
+          },
+          "commands": {
+            "additionalProperties": false,
+            "properties": {
+              "ping": {
+                "additionalProperties": false,
+                "type": "object",
+              },
+            },
+            "type": "object",
+          },
+        },
+        "type": "object",
+      }
+    `)
+  })
+})

package/src/internal/configSchema.ts

@@ -0,0 +1,66 @@
+import fs from 'node:fs/promises'
+import type { z } from 'zod'
+
+import * as Cli from '../Cli.js'
+import * as Schema from '../Schema.js'
+import { importCli } from './utils.js'
+
+/** Returns `true` if the CLI has `config` enabled on `Cli.create()`. */
+export function hasConfig(cli: Cli.Cli): boolean {
+  return Cli.toConfigEnabled.get(cli) === true
+}
+
+/** Imports a CLI from `input` (must `export default` a `Cli`), generates the JSON Schema, and writes it to `output`. */
+export async function generate(input: string, output: string): Promise<void> {
+  const cli = await importCli(input)
+  await fs.writeFile(output, JSON.stringify(fromCli(cli), null, 2) + '\n')
+}
+
+/** Generates a JSON Schema describing the config file structure for a CLI. */
+export function fromCli(cli: Cli.Cli): Record<string, unknown> {
+  const commands = Cli.toCommands.get(cli)
+  if (!commands) return { type: 'object' }
+
+  const rootOptions = Cli.toRootOptions.get(cli)
+  const node = buildNode(commands, rootOptions)
+  const properties = (node.properties ?? {}) as Record<string, unknown>
+  properties.$schema = { type: 'string' }
+  node.properties = properties
+  return node
+}
+
+/** Builds a JSON Schema node for a command level. */
+function buildNode(
+  commands: Map<string, any>,
+  options?: z.ZodObject<any>,
+): Record<string, unknown> {
+  const properties: Record<string, unknown> = {}
+
+  // Add `options` property from the options schema
+  if (options) {
+    const optSchema = Schema.toJsonSchema(options)
+    const props = optSchema.properties as Record<string, unknown> | undefined
+    if (props && Object.keys(props).length > 0)
+      properties.options = { type: 'object', additionalProperties: false, properties: props }
+  }
+
+  // Add `commands` property with subcommand namespaces
+  const commandProps: Record<string, unknown> = {}
+  for (const [name, entry] of commands) {
+    if ('_group' in entry && entry._group) {
+      commandProps[name] = buildNode(entry.commands, undefined)
+    } else if (!('_fetch' in entry)) {
+      const cmd = entry as { options?: z.ZodObject<any> }
+      commandProps[name] = buildNode(new Map(), cmd.options)
+    }
+  }
+  if (Object.keys(commandProps).length > 0)
+    properties.commands = { type: 'object', additionalProperties: false, properties: commandProps }
+
+  const node: Record<string, unknown> = {
+    type: 'object',
+    additionalProperties: false,
+  }
+  if (Object.keys(properties).length > 0) node.properties = properties
+  return node
+}

package/src/internal/helpers.ts

@@ -0,0 +1,9 @@
+/** Checks whether a value is a plain object record. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Converts a camelCase string to kebab-case. */
+export function toKebab(value: string): string {
+  return value.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
+}