incur 0.4.0 → 0.4.2

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
@@ -264,7 +315,7 @@ function coerce(value: unknown, name: string, schema: z.ZodObject<any>): unknown
 }
 
 /** Returns the best available env source for the current runtime. */
-function defaultEnvSource(): Record<string, string | undefined> {
+export function defaultEnvSource(): Record<string, string | undefined> {
   if (typeof globalThis !== 'undefined') {
     const g = globalThis as any
     if (g.process?.env) return g.process.env

package/src/Schema.test.ts

@@ -97,6 +97,35 @@ describe('toJsonSchema', () => {
     })
   })
 
+  test('converts z.bigint() as string', () => {
+    expect(Schema.toJsonSchema(z.bigint())).toEqual({ type: 'string' })
+  })
+
+  test('converts z.coerce.bigint() as string', () => {
+    expect(Schema.toJsonSchema(z.coerce.bigint())).toEqual({ type: 'string' })
+  })
+
+  test('converts z.object() with bigint field', () => {
+    expect(
+      Schema.toJsonSchema(z.object({ amount: z.coerce.bigint().describe('Token amount') })),
+    ).toEqual({
+      type: 'object',
+      properties: {
+        amount: { type: 'string', description: 'Token amount' },
+      },
+      required: ['amount'],
+      additionalProperties: false,
+    })
+  })
+
+  test('converts z.date() as string', () => {
+    expect(Schema.toJsonSchema(z.date())).toEqual({ type: 'string' })
+  })
+
+  test('converts z.coerce.date() as string', () => {
+    expect(Schema.toJsonSchema(z.coerce.date())).toEqual({ type: 'string' })
+  })
+
   test('full object with optional, default, and describe', () => {
     const result = Schema.toJsonSchema(
       z.object({

package/src/Schema.ts

@@ -1,8 +1,18 @@
 import { z } from 'zod'
 
-/** Converts a Zod schema to a JSON Schema object. Strips the `$schema` meta-property. */
+/**
+ * Converts a Zod schema to a JSON Schema object. Strips the `$schema`
+ * meta-property. Represents bigints and dates as `{ type: "string" }`
+ * since JSON lacks native types for them.
+ */
 export function toJsonSchema(schema: z.ZodType): Record<string, unknown> {
-  const result = z.toJSONSchema(schema) as Record<string, unknown>
+  const result = z.toJSONSchema(schema, {
+    unrepresentable: 'any',
+    override: (ctx) => {
+      const type = ctx.zodSchema._zod?.def?.type
+      if (type === 'bigint' || type === 'date') ctx.jsonSchema.type = 'string'
+    },
+  }) as Record<string, unknown>
   delete result.$schema
   return result
 }

package/src/Skill.test.ts

@@ -216,6 +216,40 @@ describe('hash', () => {
   })
 })
 
+describe('root command (no name)', () => {
+  test('generate renders root command without trailing space', () => {
+    const result = Skill.generate('my-cli', [
+      {
+        description: 'Fetch a URL',
+        args: z.object({ url: z.string().describe('URL to fetch') }),
+      },
+      { name: 'auth', description: 'Auth commands' },
+    ])
+    expect(result).toContain('# my-cli\n\nFetch a URL')
+    expect(result).not.toContain('# my-cli \n')
+    expect(result).toContain('| `url` | `string` | yes | URL to fetch |')
+    expect(result).toContain('# my-cli auth')
+  })
+
+  test('index renders root command signature without trailing space', () => {
+    const result = Skill.index('my-cli', [
+      { description: 'Fetch a URL', args: z.object({ url: z.string() }) },
+      { name: 'auth', description: 'Auth commands' },
+    ])
+    expect(result).toContain('| `my-cli <url>` | Fetch a URL |')
+    expect(result).toContain('| `my-cli auth` | Auth commands |')
+  })
+
+  test('hash changes when root command is added', () => {
+    const a = Skill.hash([{ name: 'ping', description: 'Health check' }])
+    const b = Skill.hash([
+      { description: 'Root command' },
+      { name: 'ping', description: 'Health check' },
+    ])
+    expect(a).not.toBe(b)
+  })
+})
+
 describe('split', () => {
   const commands: Skill.CommandInfo[] = [
     { name: 'auth login', description: 'Log in' },
@@ -252,7 +286,7 @@ describe('split', () => {
     expect(files[0]!.content).toMatchInlineSnapshot(`
       "---
       name: gh-auth
-      description: Authenticate with GitHub. Log in, Check status. Run \`gh auth --help\` for usage details.
+      description: Authenticate with GitHub. Run \`gh auth --help\` for usage details.
       requires_bin: gh
       command: gh auth
       ---
@@ -270,7 +304,7 @@ describe('split', () => {
     expect(files[1]!.content).toMatchInlineSnapshot(`
       "---
       name: gh-pr
-      description: Manage pull requests. List PRs, Create PR. Run \`gh pr --help\` for usage details.
+      description: Manage pull requests. Run \`gh pr --help\` for usage details.
       requires_bin: gh
       command: gh pr
       ---
@@ -287,11 +321,9 @@ describe('split', () => {
     `)
   })
 
-  test('depth 1 without group descriptions uses child descriptions', () => {
+  test('depth 1 without group descriptions uses fallback hint', () => {
     const files = Skill.split('gh', commands, 1)
-    expect(files[0]!.content).toContain(
-      'description: Log in, Check status. Run `gh auth --help` for usage details.',
-    )
+    expect(files[0]!.content).toContain('description: Run `gh auth --help` for usage details.')
   })
 
   test('depth 2 groups by first two segments', () => {
@@ -349,4 +381,53 @@ describe('split', () => {
     expect(afterFrontmatter).not.toMatch(/^title:/m)
     expect(afterFrontmatter).not.toMatch(/^command:/m)
   })
+
+  test('root command uses command description in frontmatter', () => {
+    const cmds: Skill.CommandInfo[] = [
+      { description: 'Fetch a URL' },
+      { name: 'auth login', description: 'Log in' },
+    ]
+    const files = Skill.split('my-cli', cmds, 1)
+    const rootFile = files.find((f) => f.dir === 'my-cli')!
+    expect(rootFile.content).toContain(
+      'description: Fetch a URL. Run `my-cli --help` for usage details.',
+    )
+  })
+
+  test('single-command group uses command description in frontmatter', () => {
+    const files = Skill.split('test', [{ name: 'ping', description: 'Health check' }], 1)
+    expect(files[0]!.content).toContain(
+      'description: Health check. Run `test ping --help` for usage details.',
+    )
+  })
+
+  test('depth 1 creates separate file for root command', () => {
+    const cmds: Skill.CommandInfo[] = [
+      {
+        description: 'Fetch a URL',
+        args: z.object({ url: z.string().describe('URL to fetch') }),
+      },
+      { name: 'auth login', description: 'Log in' },
+      { name: 'auth status', description: 'Check status' },
+    ]
+    const files = Skill.split('my-cli', cmds, 1)
+    expect(files.map((f) => f.dir)).toEqual(['auth', 'my-cli'])
+    const rootFile = files.find((f) => f.dir === 'my-cli')!
+    expect(rootFile.content).toContain('name: my-cli')
+    expect(rootFile.content).toContain('command: my-cli')
+    expect(rootFile.content).toContain('# my-cli')
+    expect(rootFile.content).toContain('| `url` | `string` | yes | URL to fetch |')
+    expect(rootFile.content).not.toContain('# my-cli ')
+  })
+
+  test('depth 0 includes root command in single file', () => {
+    const cmds: Skill.CommandInfo[] = [
+      { description: 'Fetch a URL' },
+      { name: 'ping', description: 'Health check' },
+    ]
+    const files = Skill.split('test', cmds, 0)
+    expect(files).toHaveLength(1)
+    expect(files[0]!.content).toContain('# test\n\nFetch a URL')
+    expect(files[0]!.content).toContain('# test ping')
+  })
 })

package/src/Skill.ts

@@ -5,7 +5,8 @@ import * as Schema from './Schema.js'
 
 /** Information about a single command, passed to `generate()`. */
 export type CommandInfo = {
-  name: string
+  /** Command name (subcommand path). Omit for root commands. */
+  name?: string | undefined
   description?: string | undefined
   args?: z.ZodObject<any> | undefined
   env?: z.ZodObject<any> | undefined
@@ -48,7 +49,7 @@ export function index(
 
 /** @internal Builds a command signature with arg placeholders. */
 function buildSignature(cli: string, cmd: CommandInfo): string {
-  const base = `${cli} ${cmd.name}`
+  const base = !cmd.name ? cli : `${cli} ${cmd.name}`
   if (!cmd.args) return base
   const shape = cmd.args.shape as Record<string, z.ZodType>
   const json = Schema.toJsonSchema(cmd.args)
@@ -70,14 +71,16 @@ export function generate(
   let lastGroup: string | undefined
 
   for (const cmd of commands) {
-    const segment = cmd.name.split(' ')[0]!
+    const segment = !cmd.name ? '' : cmd.name.split(' ')[0]!
     if (segment !== lastGroup) {
       lastGroup = segment
-      const desc = groups.get(segment)
-      const heading = desc ? `## ${name} ${segment}\n\n${desc}` : `## ${name} ${segment}`
-      sections.push(heading)
+      if (segment) {
+        const desc = groups.get(segment)
+        const heading = desc ? `## ${name} ${segment}\n\n${desc}` : `## ${name} ${segment}`
+        sections.push(heading)
+      }
     }
-    sections.push(renderCommandBody(name, cmd, 3))
+    sections.push(renderCommandBody(name, cmd, segment ? 3 : 2))
   }
 
   return sections.join('\n\n')
@@ -94,6 +97,13 @@ export function split(
 
   const buckets = new Map<string, CommandInfo[]>()
   for (const cmd of commands) {
+    if (!cmd.name) {
+      const key = slugify(name)
+      const bucket = buckets.get(key) ?? []
+      bucket.push(cmd)
+      buckets.set(key, bucket)
+      continue
+    }
     const segments = cmd.name.split(' ')
     const key = segments.slice(0, depth).join('-')
     const bucket = buckets.get(key) ?? []
@@ -104,8 +114,10 @@ export function split(
   return [...buckets.entries()]
     .sort(([a], [b]) => a.localeCompare(b))
     .map(([dir, cmds]) => {
-      const prefix = cmds[0]!.name.split(' ').slice(0, depth).join(' ')
-      return { dir, content: renderGroup(name, `${name} ${prefix}`, cmds, groups, prefix) }
+      const first = cmds[0]!
+      const prefix = !first.name ? '' : first.name.split(' ').slice(0, depth).join(' ')
+      const title = prefix ? `${name} ${prefix}` : name
+      return { dir, content: renderGroup(name, title, cmds, groups, prefix || undefined) }
     })
 }
 
@@ -118,17 +130,13 @@ function renderGroup(
   prefix?: string | undefined,
 ): string {
   const groupDesc = prefix ? groups.get(prefix) : undefined
-  const childDescs = cmds.map((c) => c.description).filter(Boolean) as string[]
-  const descParts: string[] = []
-  if (groupDesc) descParts.push(groupDesc.replace(/\.$/, ''))
-  if (childDescs.length > 0) descParts.push(childDescs.join(', '))
-  const description =
-    descParts.length > 0
-      ? `${descParts.join('. ')}. Run \`${title} --help\` for usage details.`
-      : `Run \`${title} --help\` for usage details.`
-
-  const slug = title.replace(/\s+/g, '-')
-  const fm = ['---', `name: ${slug}`]
+  const fallbackDesc = cmds.length === 1 && cmds[0]!.description ? cmds[0]!.description : undefined
+  const desc = groupDesc ?? fallbackDesc
+  const description = desc
+    ? `${desc.replace(/\.$/, '')}. Run \`${title} --help\` for usage details.`
+    : `Run \`${title} --help\` for usage details.`
+
+  const fm = ['---', `name: ${slugify(title)}`]
   fm.push(`description: ${description}`)
   fm.push(`requires_bin: ${cli}`)
   fm.push(`command: ${title}`, '---')
@@ -139,7 +147,7 @@ function renderGroup(
 
 /** @internal Renders a command's heading and sections without frontmatter. */
 function renderCommandBody(cli: string, cmd: CommandInfo, level = 1): string {
-  const fullName = `${cli} ${cmd.name}`
+  const fullName = !cmd.name ? cli : `${cli} ${cmd.name}`
   const sections: string[] = []
   const h = (n: number) => '#'.repeat(n)
 
@@ -283,6 +291,15 @@ function schemaToTable(schema: Record<string, unknown>, prefix = ''): string | u
   return `| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n${rows.join('\n')}`
 }
 
+/** @internal Converts a string to a lowercase slug (e.g. `"my-cli"` → `"my-cli"`, `"My Tool"` → `"my-tool"`). */
+function slugify(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-|-$/g, '')
+}
+
 /** @internal Resolves a simple type name from a JSON Schema property. */
 function resolveTypeName(prop: Record<string, unknown> | undefined): string {
   if (!prop) return 'unknown'

package/src/Skillgen.ts

@@ -62,5 +62,5 @@ function collectEntries(
       result.push(cmd)
     }
   }
-  return result.sort((a, b) => a.name.localeCompare(b.name))
+  return result.sort((a, b) => (a.name ?? '').localeCompare(b.name ?? ''))
 }

package/src/SyncMcp.test.ts

@@ -19,21 +19,19 @@ vi.mock('node:os', async (importOriginal) => {
   }
 })
 
-let savedArgv1: string | undefined
 let tmp: string
 
 beforeEach(() => {
-  savedArgv1 = process.argv[1]
+  const savedArgv1 = process.argv[1]
   tmp = join(tmpdir(), `clac-test-${Date.now()}`)
   mkdirSync(join(tmp, 'node_modules', '.bin'), { recursive: true })
   fakeHome = join(tmp, 'home')
   mkdirSync(fakeHome, { recursive: true })
-})
-
-afterEach(() => {
-  process.argv[1] = savedArgv1!
-  fakeHome = undefined
-  rmSync(tmp, { recursive: true, force: true })
+  return () => {
+    process.argv[1] = savedArgv1!
+    fakeHome = undefined
+    rmSync(tmp, { recursive: true, force: true })
+  }
 })
 
 function setupPkg(deps: Record<string, string>) {