incur 0.3.5 → 0.3.7

package/src/e2e.test.ts

@@ -70,9 +70,9 @@ describe('routing', () => {
       "code: COMMAND_NOT_FOUND
       message: 'nonexistent' is not a command for 'app'.
       cta:
-        description: "See available commands:"
-        commands[1]{command}:
-          app --help
+        description: "Next steps:"
+        commands[1]{command,description}:
+          app --help,see all available commands
       "
     `)
   })
@@ -85,8 +85,8 @@ describe('routing', () => {
     expect(output).toMatchInlineSnapshot(`
       "Error: 'nonexistent' is not a command for 'app'.
 
-      See available commands:
-        app --help
+      Next steps:
+        app --help  # see all available commands
       "
     `)
   })
@@ -98,9 +98,9 @@ describe('routing', () => {
       "code: COMMAND_NOT_FOUND
       message: 'whoami' is not a command for 'app auth'.
       cta:
-        description: "See available commands:"
-        commands[1]{command}:
-          app auth --help
+        description: "Next steps:"
+        commands[1]{command,description}:
+          app auth --help,see all available commands
       "
     `)
   })
@@ -112,9 +112,9 @@ describe('routing', () => {
       "code: COMMAND_NOT_FOUND
       message: 'nope' is not a command for 'app project deploy'.
       cta:
-        description: "See available commands:"
-        commands[1]{command}:
-          app project deploy --help
+        description: "Next steps:"
+        commands[1]{command,description}:
+          app project deploy --help,see all available commands
       "
     `)
   })
@@ -650,9 +650,10 @@ describe('error handling', () => {
             "commands": [
               {
                 "command": "app --help",
+                "description": "see all available commands",
               },
             ],
-            "description": "See available commands:",
+            "description": "Next steps:",
           },
           "duration": "<stripped>",
         },
@@ -1974,13 +1975,15 @@ describe('skills staleness', () => {
 
   afterEach(() => {
     stderrSpy.mockRestore()
+    __mockSkillsHash = undefined
   })
 
-  test('warns when running a command with stale skills', async () => {
+  test('includes skills CTA when stale', async () => {
     __mockSkillsHash = '0000000000000000'
     const { output } = await serve(createApp(), ['ping'])
     expect(output).toContain('pong: true')
-    expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('Skills are out of date.'))
+    expect(output).toContain('Skills are out of date:')
+    expect(output).toContain('skills add')
   })
 
   test('no warning when skills hash matches', async () => {
@@ -1991,20 +1994,20 @@ describe('skills staleness', () => {
 
     const { output } = await serve(cli, ['ping'])
     expect(output).toContain('pong: true')
-    expect(stderrSpy).not.toHaveBeenCalled()
+    expect(output).not.toContain('Skills are out of date')
   })
 
   test('no warning on first use (no hash stored)', async () => {
     __mockSkillsHash = undefined
     const { output } = await serve(createApp(), ['ping'])
     expect(output).toContain('pong: true')
-    expect(stderrSpy).not.toHaveBeenCalled()
+    expect(output).not.toContain('Skills are out of date')
   })
 
   test('no warning for --llms', async () => {
     __mockSkillsHash = '0000000000000000'
-    await serve(createApp(), ['--llms'])
-    expect(stderrSpy).not.toHaveBeenCalled()
+    const { output } = await serve(createApp(), ['--llms'])
+    expect(output).not.toContain('Skills are out of date')
   })
 
   test('no warning for --mcp', async () => {
@@ -2204,7 +2207,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.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from 'vitest'
+import { levenshtein, suggest } from './helpers.js'
+
+describe('levenshtein', () => {
+  test('identical strings', () => {
+    expect(levenshtein('abc', 'abc')).toBe(0)
+  })
+
+  test('single insertion', () => {
+    expect(levenshtein('abc', 'abcd')).toBe(1)
+  })
+
+  test('single deletion', () => {
+    expect(levenshtein('abcd', 'abc')).toBe(1)
+  })
+
+  test('single substitution', () => {
+    expect(levenshtein('abc', 'axc')).toBe(1)
+  })
+
+  test('transposition counts as 2', () => {
+    expect(levenshtein('mpc', 'mcp')).toBe(2)
+  })
+
+  test('empty strings', () => {
+    expect(levenshtein('', '')).toBe(0)
+    expect(levenshtein('abc', '')).toBe(3)
+    expect(levenshtein('', 'abc')).toBe(3)
+  })
+})
+
+describe('suggest', () => {
+  const commands = ['deploy', 'status', 'list', 'create']
+
+  test('returns closest match within threshold', () => {
+    expect(suggest('deplyo', commands)).toBe('deploy')
+  })
+
+  test('returns match for transposition', () => {
+    expect(suggest('mpc', ['mcp', 'skills', 'completions'])).toBe('mcp')
+  })
+
+  test('returns undefined when no match is close enough', () => {
+    expect(suggest('xyz', commands)).toBeUndefined()
+  })
+
+  test('returns undefined for empty candidates', () => {
+    expect(suggest('deploy', [])).toBeUndefined()
+  })
+
+  test('picks the closest among multiple candidates', () => {
+    expect(suggest('craete', ['list', 'create', 'delete'])).toBe('create')
+  })
+})

package/src/internal/helpers.ts

@@ -0,0 +1,41 @@
+/** 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()}`)
+}
+
+/** Computes the Levenshtein edit distance between two strings. */
+export function levenshtein(a: string, b: string): number {
+  const m = a.length
+  const n = b.length
+  const dp: number[] = Array.from({ length: n + 1 }, (_, i) => i)
+  for (let i = 1; i <= m; i++) {
+    let prev = dp[0]!
+    dp[0] = i
+    for (let j = 1; j <= n; j++) {
+      const tmp = dp[j]!
+      dp[j] = a[i - 1] === b[j - 1] ? prev : 1 + Math.min(prev, dp[j]!, dp[j - 1]!)
+      prev = tmp
+    }
+  }
+  return dp[n]!
+}
+
+/** Suggests the closest command name from a set, returning it if within a reasonable edit distance. */
+export function suggest(input: string, candidates: Iterable<string>): string | undefined {
+  const threshold = input.length <= 4 ? 2 : Math.floor(input.length / 2)
+  let best: string | undefined
+  let bestDist = threshold + 1
+  for (const c of candidates) {
+    const d = levenshtein(input, c)
+    if (d < bestDist) {
+      bestDist = d
+      best = c
+    }
+  }
+  return best
+}