incur 0.3.5 → 0.3.7

package/src/Cli.test.ts

@@ -1,4 +1,7 @@
 import { Cli, Errors, z } from 'incur'
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
 
 const originalIsTTY = process.stdout.isTTY
 beforeAll(() => {
@@ -37,6 +40,42 @@ async function serve(
   }
 }
 
+function createConfigCli(flag?: string) {
+  const project = Cli.create('project').command('list', {
+    options: z.object({
+      label: z.array(z.string()).default([]),
+      limit: z.number().default(10),
+    }),
+    run(c) {
+      return c.options
+    },
+  })
+
+  const cli = Cli.create('test', {
+    config: flag !== undefined ? { flag } : {},
+    options: z.object({
+      rootValue: z.string().default('root-default'),
+    }),
+    run(c) {
+      return c.options
+    },
+  })
+
+  cli.command('echo', {
+    options: z.object({
+      prefix: z.string().default(''),
+      upper: z.boolean().default(false),
+    }),
+    run(c) {
+      return c.options
+    },
+  })
+
+  cli.command(project)
+
+  return cli
+}
+
 describe('create', () => {
   test('returns cli instance with name', () => {
     const cli = Cli.create('test')
@@ -62,6 +101,518 @@ describe('command', () => {
   })
 })
 
+describe('config defaults', () => {
+  let cwd: string
+  let dir: string
+
+  beforeEach(async () => {
+    cwd = process.cwd()
+    dir = await mkdtemp(join(tmpdir(), 'incur-config-'))
+    process.chdir(dir)
+  })
+
+  afterEach(async () => {
+    process.chdir(cwd)
+    await rm(dir, { force: true, recursive: true })
+  })
+
+  test('auto-loads <cli>.json for leaf commands', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({
+        commands: {
+          echo: {
+            options: {
+              prefix: 'cfg',
+              upper: true,
+            },
+          },
+        },
+      }),
+    )
+
+    const { output } = await serve(createConfigCli(), ['echo', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: 'cfg', upper: true })
+  })
+
+  test('ignores a missing auto config file', async () => {
+    const { output } = await serve(createConfigCli(), ['echo', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: '', upper: false })
+  })
+
+  test('root options coexist with subcommand keys', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({
+        options: { rootValue: 'cfg-root' },
+        commands: {
+          echo: { options: { prefix: 'cfg' } },
+        },
+      }),
+    )
+
+    const rootResult = await serve(createConfigCli(), ['--json'])
+    expect(JSON.parse(rootResult.output)).toEqual({ rootValue: 'cfg-root' })
+
+    const echoResult = await serve(createConfigCli(), ['echo', '--json'])
+    expect(JSON.parse(echoResult.output)).toEqual({ prefix: 'cfg', upper: false })
+  })
+
+  test('walks nested command sections in config tree', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({
+        commands: {
+          project: {
+            commands: {
+              list: {
+                options: {
+                  label: ['cfg'],
+                  limit: 25,
+                },
+              },
+            },
+          },
+        },
+      }),
+    )
+
+    const { output } = await serve(createConfigCli(), ['project', 'list', '--json'])
+    expect(JSON.parse(output)).toEqual({ label: ['cfg'], limit: 25 })
+  })
+
+  test('uses an explicit --config path instead of the auto file', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({
+        commands: { echo: { options: { prefix: 'auto' } } },
+      }),
+    )
+    await writeFile(
+      join(dir, 'custom.json'),
+      JSON.stringify({
+        commands: { echo: { options: { prefix: 'custom', upper: true } } },
+      }),
+    )
+
+    const { output } = await serve(createConfigCli('config'), [
+      'echo',
+      '--config',
+      'custom.json',
+      '--json',
+    ])
+    expect(JSON.parse(output)).toEqual({ prefix: 'custom', upper: true })
+  })
+
+  test('--no-config disables earlier config flags, and a later --config wins again', async () => {
+    await writeFile(
+      join(dir, 'one.json'),
+      JSON.stringify({
+        commands: { echo: { options: { prefix: 'one' } } },
+      }),
+    )
+    await writeFile(
+      join(dir, 'two.json'),
+      JSON.stringify({
+        commands: { echo: { options: { prefix: 'two' } } },
+      }),
+    )
+
+    const first = await serve(createConfigCli('config'), [
+      'echo',
+      '--config',
+      'one.json',
+      '--no-config',
+      '--json',
+    ])
+    expect(JSON.parse(first.output)).toEqual({ prefix: '', upper: false })
+
+    const second = await serve(createConfigCli('config'), [
+      'echo',
+      '--config',
+      'one.json',
+      '--no-config',
+      '--config=two.json',
+      '--json',
+    ])
+    expect(JSON.parse(second.output)).toEqual({ prefix: 'two', upper: false })
+  })
+
+  test('fails when an explicit config file is missing', async () => {
+    const { exitCode, output } = await serve(createConfigCli('config'), [
+      'echo',
+      '--config',
+      'missing.json',
+    ])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('Config file not found')
+  })
+
+  test('fails on invalid JSON config files', async () => {
+    await writeFile(join(dir, 'test.json'), '{ invalid')
+
+    const { exitCode, output } = await serve(createConfigCli(), ['echo'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('Invalid JSON config file')
+  })
+
+  test('fails when the config file top level is not an object', async () => {
+    await writeFile(join(dir, 'test.json'), JSON.stringify(['bad']))
+
+    const { exitCode, output } = await serve(createConfigCli(), ['echo'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('expected a top-level object')
+  })
+
+  test('fails when the selected config section is not an object', async () => {
+    await writeFile(join(dir, 'test.json'), JSON.stringify({ commands: { echo: true } }))
+
+    const { exitCode, output } = await serve(createConfigCli(), ['echo'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain("Invalid config section for 'echo'")
+  })
+
+  test('fails validation when config option values are invalid', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({
+        commands: { echo: { options: { upper: 'nope' } } },
+      }),
+    )
+
+    const { exitCode, output } = await serve(createConfigCli(), ['echo'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('VALIDATION_ERROR')
+  })
+
+  test('argv overrides invalid config values at the CLI layer', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({
+        commands: { echo: { options: { prefix: 123 } } },
+      }),
+    )
+
+    const { output } = await serve(createConfigCli(), ['echo', '--prefix', 'cli', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: 'cli', upper: false })
+  })
+
+  test('built-in commands ignore config loading', async () => {
+    await writeFile(join(dir, 'test.json'), '{ invalid')
+
+    const { output, exitCode } = await serve(createConfigCli(), ['--help'])
+    expect(exitCode).toBeUndefined()
+    expect(output).toContain('Global Options:')
+  })
+
+  test('config without flag does not reserve --config', async () => {
+    const cli = Cli.create('test', { config: {} })
+    cli.command('echo', {
+      options: z.object({ config: z.string().default('') }),
+      run(c) {
+        return c.options
+      },
+    })
+
+    const { output } = await serve(cli, ['echo', '--config', 'my-value', '--json'])
+    expect(JSON.parse(output)).toEqual({ config: 'my-value' })
+  })
+
+  test('--help shows config flags only when flag name is set', async () => {
+    const { output } = await serve(createConfigCli('config'), ['--help'])
+    expect(output).toContain('--config <path>')
+    expect(output).toContain('--no-config')
+
+    const { output: noFlagOutput } = await serve(createConfigCli(), ['--help'])
+    expect(noFlagOutput).not.toContain('--config')
+  })
+
+  test('custom flag name is used for config path override', async () => {
+    await writeFile(
+      join(dir, 'custom.json'),
+      JSON.stringify({
+        commands: { echo: { options: { prefix: 'custom' } } },
+      }),
+    )
+
+    const { output } = await serve(createConfigCli('settings'), [
+      'echo',
+      '--settings',
+      'custom.json',
+      '--json',
+    ])
+    expect(JSON.parse(output)).toEqual({ prefix: 'custom', upper: false })
+  })
+
+  test('searches files list in order, first match wins', async () => {
+    await writeFile(
+      join(dir, '.testrc.json'),
+      JSON.stringify({ commands: { echo: { options: { prefix: 'rc' } } } }),
+    )
+
+    const cli = Cli.create('test', {
+      config: { files: ['test.json', '.testrc.json'] },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { output } = await serve(cli, ['echo', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: 'rc' })
+  })
+
+  test('files: [] disables auto-discovery', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({ commands: { echo: { options: { prefix: 'should-not-load' } } } }),
+    )
+
+    const cli = Cli.create('test', {
+      config: { files: [] },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { output } = await serve(cli, ['echo', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: '' })
+  })
+
+  test('files supports ~ for home directory', async () => {
+    const configDir = join(homedir(), '.config', 'test-incur-files-tilde')
+    await mkdir(configDir, { recursive: true })
+    try {
+      await writeFile(
+        join(configDir, 'config.json'),
+        JSON.stringify({ commands: { echo: { options: { prefix: 'home' } } } }),
+      )
+
+      const cli = Cli.create('test', {
+        config: { files: ['test.json', '~/.config/test-incur-files-tilde/config.json'] },
+      })
+      cli.command('echo', {
+        options: z.object({ prefix: z.string().default('') }),
+        run: (c) => c.options,
+      })
+
+      const { output } = await serve(cli, ['echo', '--json'])
+      expect(JSON.parse(output)).toEqual({ prefix: 'home' })
+    } finally {
+      await rm(configDir, { recursive: true, force: true })
+    }
+  })
+
+  test('explicit --flag overrides files list', async () => {
+    await writeFile(
+      join(dir, '.testrc.json'),
+      JSON.stringify({ commands: { echo: { options: { prefix: 'rc' } } } }),
+    )
+    await writeFile(
+      join(dir, 'override.json'),
+      JSON.stringify({ commands: { echo: { options: { prefix: 'override' } } } }),
+    )
+
+    const cli = Cli.create('test', {
+      config: { flag: 'config', files: ['.testrc.json'] },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { output } = await serve(cli, ['echo', '--config', 'override.json', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: 'override' })
+  })
+
+  test('custom loader replaces JSON parsing', async () => {
+    await writeFile(join(dir, 'test.ini'), 'prefix=ini-value')
+
+    const cli = Cli.create('test', {
+      config: {
+        files: ['test.ini'],
+        async loader(path) {
+          if (!path) return undefined
+          const raw = await readFile(path, 'utf8')
+          const obj: Record<string, unknown> = {}
+          for (const line of raw.split('\n')) {
+            const eq = line.indexOf('=')
+            if (eq !== -1) obj[line.slice(0, eq).trim()] = line.slice(eq + 1).trim()
+          }
+          return { commands: { echo: { options: obj } } }
+        },
+      },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { output } = await serve(cli, ['echo', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: 'ini-value' })
+  })
+
+  test('loader with files: [] receives undefined path', async () => {
+    const cli = Cli.create('test', {
+      config: {
+        files: [],
+        loader: async (path) => {
+          expect(path).toBeUndefined()
+          return { commands: { echo: { options: { prefix: 'from-loader' } } } }
+        },
+      },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { output } = await serve(cli, ['echo', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: 'from-loader' })
+  })
+
+  test('loader returning undefined applies no defaults', async () => {
+    const cli = Cli.create('test', {
+      config: { files: [], loader: async () => undefined },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { output } = await serve(cli, ['echo', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: '' })
+  })
+
+  test('--no-flag skips loader entirely', async () => {
+    let loaderCalled = false
+    const cli = Cli.create('test', {
+      config: {
+        flag: 'config',
+        files: [],
+        loader: async () => {
+          loaderCalled = true
+          return { commands: { echo: { options: { prefix: 'should-not-load' } } } }
+        },
+      },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { output } = await serve(cli, ['echo', '--no-config', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: '' })
+    expect(loaderCalled).toBe(false)
+  })
+
+  test('loader errors propagate', async () => {
+    const cli = Cli.create('test', {
+      config: {
+        files: [],
+        loader: async () => {
+          throw new Error('Remote config server unreachable')
+        },
+      },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { exitCode, output } = await serve(cli, ['echo'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('Remote config server unreachable')
+  })
+
+  test('--no-flag disables auto-discovery without prior --flag', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({ commands: { echo: { options: { prefix: 'auto-loaded' } } } }),
+    )
+
+    const { output } = await serve(createConfigCli('config'), ['echo', '--no-config', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: '', upper: false })
+  })
+
+  test('--config without a value produces an error', async () => {
+    const { exitCode, output } = await serve(createConfigCli('config'), ['echo', '--config'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('Missing value for flag')
+  })
+
+  test('--config= (empty value) produces an error', async () => {
+    const { exitCode, output } = await serve(createConfigCli('config'), ['echo', '--config='])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('Missing value for flag')
+  })
+
+  test('--no-settings works with custom flag name', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({ commands: { echo: { options: { prefix: 'auto' } } } }),
+    )
+
+    const { output } = await serve(createConfigCli('settings'), ['echo', '--no-settings', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: '', upper: false })
+  })
+
+  test('camelCase config keys are accepted at cli level', async () => {
+    const cli = Cli.create('test', { config: {} })
+    cli.command('echo', {
+      options: z.object({ saveDev: z.boolean().default(false) }),
+      run: (c) => c.options,
+    })
+
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({ commands: { echo: { options: { 'save-dev': true } } } }),
+    )
+
+    const { output } = await serve(cli, ['echo', '--json'])
+    expect(JSON.parse(output)).toEqual({ saveDev: true })
+  })
+
+  test('config defaults with only subcommand namespaces yields no option defaults', async () => {
+    await writeFile(
+      join(dir, 'test.json'),
+      JSON.stringify({
+        commands: {
+          echo: { options: { prefix: 'child' } },
+          project: { commands: { list: { options: { limit: 50 } } } },
+        },
+      }),
+    )
+
+    const rootResult = await serve(createConfigCli(), ['--json'])
+    expect(JSON.parse(rootResult.output)).toEqual({ rootValue: 'root-default' })
+  })
+
+  test('explicit --flag path is forwarded to custom loader', async () => {
+    await writeFile(join(dir, 'custom.dat'), 'prefix=custom-loader')
+
+    const cli = Cli.create('test', {
+      config: {
+        flag: 'config',
+        async loader(path) {
+          if (!path) return undefined
+          const raw = await readFile(path, 'utf8')
+          const [, value] = raw.split('=')
+          return { commands: { echo: { options: { prefix: value!.trim() } } } }
+        },
+      },
+    })
+    cli.command('echo', {
+      options: z.object({ prefix: z.string().default('') }),
+      run: (c) => c.options,
+    })
+
+    const { output } = await serve(cli, ['echo', '--config', 'custom.dat', '--json'])
+    expect(JSON.parse(output)).toEqual({ prefix: 'custom-loader' })
+  })
+})
+
 describe('serve', () => {
   test('outputs data only by default', async () => {
     const cli = Cli.create('test')
@@ -140,9 +691,9 @@ describe('serve', () => {
       "code: COMMAND_NOT_FOUND
       message: 'nonexistent' is not a command for 'test'.
       cta:
-        description: "See available commands:"
-        commands[1]{command}:
-          test --help
+        description: "Next steps:"
+        commands[1]{command,description}:
+          test --help,see all available commands
       "
     `)
   })
@@ -157,8 +708,8 @@ describe('serve', () => {
     expect(output).toMatchInlineSnapshot(`
       "Error: 'nonexistent' is not a command for 'test'.
 
-      See available commands:
-        test --help
+      Next steps:
+        test --help  # see all available commands
       "
     `)
   })
@@ -176,14 +727,100 @@ describe('serve', () => {
       meta:
         command: nonexistent
         cta:
-          description: "See available commands:"
-          commands[1]{command}:
-            test --help
+          description: "Next steps:"
+          commands[1]{command,description}:
+            test --help,see all available commands
         duration: <stripped>
       "
     `)
   })
 
+  test('suggests similar command for typos', async () => {
+    const cli = Cli.create('test')
+    cli.command('deploy', { run: () => ({}) })
+    cli.command('status', { run: () => ({}) })
+
+    const { output, exitCode } = await serve(cli, ['deplyo'])
+    expect(exitCode).toBe(1)
+    expect(output).toMatchInlineSnapshot(`
+      "code: COMMAND_NOT_FOUND
+      message: 'deplyo' is not a command for 'test'. Did you mean 'deploy'?
+      cta:
+        description: "Next steps:"
+        commands[2]:
+          - command: test deploy
+          - command: test --help
+            description: see all available commands
+      "
+    `)
+  })
+
+  test('suggests similar command for typos in TTY', async () => {
+    ;(process.stdout as any).isTTY = true
+    const cli = Cli.create('test')
+    cli.command('deploy', { run: () => ({}) })
+
+    const { output, exitCode } = await serve(cli, ['deplyo'])
+    ;(process.stdout as any).isTTY = false
+    expect(exitCode).toBe(1)
+    expect(output).toMatchInlineSnapshot(`
+      "Error: 'deplyo' is not a command for 'test'. Did you mean 'deploy'?
+
+      Next steps:
+        test deploy
+        test --help  # see all available commands
+      "
+    `)
+  })
+
+  test('suggests builtin commands for typos', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({}) })
+
+    const { output, exitCode } = await serve(cli, ['mpc'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain("Did you mean 'mcp'?")
+    expect(output).toContain('test mcp')
+  })
+
+  test('preserves flags in suggestion CTA', async () => {
+    const cli = Cli.create('test')
+    cli.command('deploy', { run: () => ({}) })
+
+    const { output } = await serve(cli, ['deplyo', '--verbose'])
+    expect(output).toContain('test deploy --verbose')
+  })
+
+  test('no suggestion when input is too far from any command', async () => {
+    const cli = Cli.create('test')
+    cli.command('deploy', { run: () => ({}) })
+
+    const { output } = await serve(cli, ['xyz'])
+    expect(output).not.toContain('Did you mean')
+  })
+
+  test('suggests similar subcommand for typos', async () => {
+    const cli = Cli.create('test')
+    const pr = Cli.create('pr')
+      .command('list', { run: () => ({}) })
+      .command('create', { run: () => ({}) })
+    cli.command(pr)
+
+    const { output, exitCode } = await serve(cli, ['pr', 'craete'])
+    expect(exitCode).toBe(1)
+    expect(output).toMatchInlineSnapshot(`
+      "code: COMMAND_NOT_FOUND
+      message: 'craete' is not a command for 'test pr'. Did you mean 'create'?
+      cta:
+        description: "Next steps:"
+        commands[2]:
+          - command: test pr create
+          - command: test pr --help
+            description: see all available commands
+      "
+    `)
+  })
+
   test('wraps handler errors in error output', async () => {
     const cli = Cli.create('test')
     cli.command('fail', {
@@ -738,6 +1375,14 @@ describe('--schema', () => {
     expect(exitCode).toBe(1)
   })
 
+  test('on unknown command suggests similar', async () => {
+    const cli = Cli.create('test')
+    cli.command('greet', { run: () => ({}) })
+    const { output, exitCode } = await serve(cli, ['grete', '--schema'])
+    expect(output).toContain("Did you mean 'greet'?")
+    expect(exitCode).toBe(1)
+  })
+
   test('on group shows available commands', async () => {
     const cli = Cli.create('test')
     const pr = Cli.create('pr', { description: 'PR management' }).command('list', {
@@ -871,9 +1516,9 @@ describe('subcommands', () => {
       "code: COMMAND_NOT_FOUND
       message: 'unknown' is not a command for 'test pr'.
       cta:
-        description: "See available commands:"
-        commands[1]{command}:
-          test pr --help
+        description: "Next steps:"
+        commands[1]{command,description}:
+          test pr --help,see all available commands
       "
     `)
   })
@@ -892,8 +1537,8 @@ describe('subcommands', () => {
     expect(output).toMatchInlineSnapshot(`
       "Error: 'unknown' is not a command for 'test pr'.
 
-      See available commands:
-        test pr --help
+      Next steps:
+        test pr --help  # see all available commands
       "
     `)
   })
@@ -1733,7 +2378,7 @@ describe('env', () => {
           --verbose                           Show full output envelope
 
         Environment Variables:
-          API_TOKEN  Auth token (set: ••••ret)
+          API_TOKEN  Auth token (set: ****cret)
           API_URL    API URL (default: https://api.example.com)
         "
       `)
@@ -1742,7 +2387,7 @@ describe('env', () => {
       process.env.API_URL = 'https://custom.example.com'
       const { output: output2 } = await serve(cli, ['deploy', '--help'])
       expect(output2).toContain(
-        'API_URL    API URL (set: ••••com, default: https://api.example.com)',
+        'API_URL    API URL (set: ****.com, default: https://api.example.com)',
       )
     } finally {
       delete process.env.API_TOKEN
@@ -1770,7 +2415,7 @@ describe('env', () => {
     const { output: output2 } = await serve(cli, ['deploy', '--help'], {
       env: { API_TOKEN: 'secret' },
     })
-    expect(output2).toContain('set: ••••ret')
+    expect(output2).toContain('set: ****cret')
   })
 
   test('--llms json includes schema.env', async () => {
@@ -1898,6 +2543,25 @@ describe('built-in commands', () => {
     expect(output).toContain('add')
   })
 
+  test('skills typo suggests add', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({}) })
+    const { output, exitCode } = await serve(cli, ['skills', 'addd'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain("Did you mean 'add'?")
+    expect(output).toContain('test skills add')
+    expect(output).toContain('test skills --help')
+  })
+
+  test('mcp typo suggests add', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({}) })
+    const { output, exitCode } = await serve(cli, ['mcp', 'addd'])
+    expect(exitCode).toBe(1)
+    expect(output).toContain("Did you mean 'add'?")
+    expect(output).toContain('test mcp add')
+  })
+
   test('skills add --help shows options', async () => {
     const cli = Cli.create('test')
     cli.command('ping', { run: () => ({ pong: true }) })
@@ -1918,15 +2582,32 @@ describe('skills staleness', () => {
 
   afterEach(() => {
     stderrSpy.mockRestore()
+    __mockSkillsHash = undefined
   })
 
-  test('warns on stderr when skills are stale', async () => {
+  test('includes skills CTA when stale', async () => {
     __mockSkillsHash = '0000000000000000'
     const cli = Cli.create('test')
     cli.command('ping', { description: 'Health check', run: () => ({ pong: true }) })
 
-    await serve(cli, ['ping'])
-    expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining("Skills are out of date. Run '"))
+    const { output } = await serve(cli, ['ping'])
+    expect(output).toContain('Skills are out of date:')
+    expect(output).toContain('skills add')
+  })
+
+  test('merges skills CTA with command CTA', async () => {
+    __mockSkillsHash = '0000000000000000'
+    ;(process.stdout as any).isTTY = true
+    const cli = Cli.create('test')
+    cli.command('ping', {
+      description: 'Health check',
+      run: (c) => c.ok({ pong: true }, { cta: { commands: ['status'] } }),
+    })
+
+    const { output } = await serve(cli, ['ping'])
+    ;(process.stdout as any).isTTY = false
+    expect(output).toContain('status')
+    expect(output).toContain('skills add')
   })
 
   test('does not warn when hash matches', async () => {
@@ -1935,8 +2616,8 @@ describe('skills staleness', () => {
     const cli = Cli.create('test')
     cli.command('ping', { description: 'Health check', run: () => ({ pong: true }) })
 
-    await serve(cli, ['ping'])
-    expect(stderrSpy).not.toHaveBeenCalled()
+    const { output } = await serve(cli, ['ping'])
+    expect(output).not.toContain('Skills are out of date')
   })
 
   test('does not warn when no hash stored', async () => {
@@ -1944,8 +2625,8 @@ describe('skills staleness', () => {
     const cli = Cli.create('test')
     cli.command('ping', { run: () => ({ pong: true }) })
 
-    await serve(cli, ['ping'])
-    expect(stderrSpy).not.toHaveBeenCalled()
+    const { output } = await serve(cli, ['ping'])
+    expect(output).not.toContain('Skills are out of date')
   })
 
   test('does not warn for skills add', async () => {
@@ -1962,8 +2643,8 @@ describe('skills staleness', () => {
     const cli = Cli.create('test')
     cli.command('ping', { run: () => ({ pong: true }) })
 
-    await serve(cli, ['--help'])
-    expect(stderrSpy).not.toHaveBeenCalled()
+    const { output } = await serve(cli, ['--help'])
+    expect(output).not.toContain('Skills are out of date')
   })
 })
 
@@ -3157,6 +3838,14 @@ describe('fetch', () => {
     `)
   })
 
+  test('GET /helath → 404 with suggestion', async () => {
+    const cli = Cli.create('test')
+    cli.command('health', { run: () => ({}) })
+    const res = await fetchJson(cli, new Request('http://localhost/helath'))
+    expect(res.status).toBe(404)
+    expect(res.body.error.message).toContain("Did you mean 'health'?")
+  })
+
   test('GET / with root command → 200', async () => {
     const cli = Cli.create('test', { run: () => ({ root: true }) })
     expect(await fetchJson(cli, new Request('http://localhost/'))).toMatchInlineSnapshot(`