incur 0.2.0 → 0.2.2

package/src/Cli.test.ts

@@ -580,6 +580,121 @@ describe('--llms', () => {
   })
 })
 
+describe('--schema', () => {
+  test('returns command schema in toon format', async () => {
+    const cli = Cli.create('test')
+    cli.command('greet', {
+      args: z.object({ name: z.string().describe('Name to greet') }),
+      options: z.object({ loud: z.boolean().default(false).describe('Shout') }),
+      output: z.object({ message: z.string() }),
+      run(c) {
+        return { message: `hello ${c.args.name}` }
+      },
+    })
+    const { output } = await serve(cli, ['greet', '--schema'])
+    expect(output).toContain('args')
+    expect(output).toContain('options')
+    expect(output).toContain('output')
+  })
+
+  test('returns command schema as JSON', async () => {
+    const cli = Cli.create('test')
+    cli.command('greet', {
+      args: z.object({ name: z.string().describe('Name to greet') }),
+      options: z.object({ loud: z.boolean().default(false).describe('Shout') }),
+      output: z.object({ message: z.string() }),
+      run(c) {
+        return { message: `hello ${c.args.name}` }
+      },
+    })
+    const { output } = await serve(cli, ['greet', '--schema', '--format', 'json'])
+    expect(JSON.parse(output)).toMatchInlineSnapshot(`
+      {
+        "args": {
+          "additionalProperties": false,
+          "properties": {
+            "name": {
+              "description": "Name to greet",
+              "type": "string",
+            },
+          },
+          "required": [
+            "name",
+          ],
+          "type": "object",
+        },
+        "options": {
+          "additionalProperties": false,
+          "properties": {
+            "loud": {
+              "default": false,
+              "description": "Shout",
+              "type": "boolean",
+            },
+          },
+          "required": [
+            "loud",
+          ],
+          "type": "object",
+        },
+        "output": {
+          "additionalProperties": false,
+          "properties": {
+            "message": {
+              "type": "string",
+            },
+          },
+          "required": [
+            "message",
+          ],
+          "type": "object",
+        },
+      }
+    `)
+  })
+
+  test('on root command', async () => {
+    const cli = Cli.create('test', {
+      args: z.object({ name: z.string() }),
+      output: z.object({ greeting: z.string() }),
+      run(c) {
+        return { greeting: `hi ${c.args.name}` }
+      },
+    })
+    const { output } = await serve(cli, ['--schema', '--format', 'json'])
+    const parsed = JSON.parse(output)
+    expect(parsed.args).toBeDefined()
+    expect(parsed.output).toBeDefined()
+  })
+
+  test('on unknown command shows error', async () => {
+    const cli = Cli.create('test')
+    cli.command('greet', { run: () => ({}) })
+    const { output, exitCode } = await serve(cli, ['nope', '--schema'])
+    expect(output).toContain("'nope' is not a command")
+    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', {
+      description: 'List PRs',
+      run: () => ({ items: [] }),
+    })
+    cli.command(pr)
+    const { output } = await serve(cli, ['pr', '--schema'])
+    expect(output).toContain('pr')
+    expect(output).toContain('list')
+  })
+
+  test('omits empty schema sections', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['ping', '--schema', '--format', 'json'])
+    expect(JSON.parse(output)).toMatchInlineSnapshot('{}')
+  })
+})
+
 describe('subcommands', () => {
   test('creates a command group with name and description', () => {
     const pr = Cli.create('pr', { description: 'PR management' })
@@ -739,9 +854,14 @@ describe('subcommands', () => {
         list
 
       Global Options:
+        --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                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a 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
       "
     `)
@@ -1173,10 +1293,15 @@ describe('help', () => {
         skills add   Sync skill files to your agent
 
       Global Options:
+        --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                              Print LLM-readable manifest
         --mcp                               Start as MCP stdio server
+        --schema                            Show JSON Schema for a 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
       "
@@ -1206,10 +1331,15 @@ describe('help', () => {
         skills add   Sync skill files to your agent
 
       Global Options:
+        --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                              Print LLM-readable manifest
         --mcp                               Start as MCP stdio server
+        --schema                            Show JSON Schema for a 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
       "
@@ -1235,9 +1365,14 @@ describe('help', () => {
         name  Name
 
       Global Options:
+        --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                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a 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
       "
     `)
@@ -1264,9 +1399,14 @@ describe('help', () => {
         list  List PRs
 
       Global Options:
+        --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                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a 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
       "
     `)
@@ -1354,10 +1494,15 @@ describe('help', () => {
         skills add   Sync skill files to your agent
 
       Global Options:
+        --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                              Print LLM-readable manifest
         --mcp                               Start as MCP stdio server
+        --schema                            Show JSON Schema for a 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
       "
@@ -1381,9 +1526,14 @@ describe('help', () => {
       Run "tool status" to check deployment progress.
 
       Global Options:
+        --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                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a 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
       "
     `)
@@ -1471,9 +1621,14 @@ describe('env', () => {
       Usage: test deploy
 
       Global Options:
+        --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                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a 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
 
       Environment Variables:
@@ -1504,9 +1659,14 @@ describe('env', () => {
         Usage: test deploy
 
         Global Options:
+          --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                              Print LLM-readable manifest
+          --schema                            Show JSON Schema for a 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
 
         Environment Variables:
@@ -2104,6 +2264,43 @@ describe('outputPolicy', () => {
     expect(captured).toEqual({ agent: false, command: 'deploy' })
   })
 
+  test('e2e: middleware and run context expose format metadata', async () => {
+    let mwCaptured:
+      | {
+          format: string
+          formatExplicit: boolean
+        }
+      | undefined
+    let runCaptured:
+      | {
+          format: string
+          formatExplicit: boolean
+        }
+      | undefined
+
+    const cli = Cli.create('test')
+      .use(async (c, next) => {
+        mwCaptured = {
+          format: c.format,
+          formatExplicit: c.formatExplicit,
+        }
+        await next()
+      })
+      .command('deploy', {
+        run(c) {
+          runCaptured = {
+            format: c.format,
+            formatExplicit: c.formatExplicit,
+          }
+          return { ok: true }
+        },
+      })
+
+    await serve(cli, ['deploy', '--format', 'json'])
+    expect(mwCaptured).toEqual({ format: 'json', formatExplicit: true })
+    expect(runCaptured).toEqual({ format: 'json', formatExplicit: true })
+  })
+
   test('e2e: middleware works with streaming handlers', async () => {
     const order: string[] = []
     const cli = Cli.create('test')
@@ -2404,6 +2601,88 @@ test('streaming: generator returns error in buffered mode', async () => {
   expect(output).toContain('RET_ERR')
 })
 
+test('c.error({ exitCode }) uses custom exit code', async () => {
+  const cli = Cli.create('test')
+  cli.command('fail', {
+    run(c) {
+      return c.error({ code: 'AUTH', message: 'not authed', exitCode: 10 })
+    },
+  })
+
+  const { output, exitCode } = await serve(cli, ['fail'])
+  expect(exitCode).toBe(10)
+  expect(output).toMatchInlineSnapshot(`
+    "code: AUTH
+    message: not authed
+    "
+  `)
+})
+
+test('c.error() without exitCode defaults to 1', async () => {
+  const cli = Cli.create('test')
+  cli.command('fail', {
+    run(c) {
+      return c.error({ code: 'BAD', message: 'fail' })
+    },
+  })
+
+  const { output, exitCode } = await serve(cli, ['fail'])
+  expect(exitCode).toBe(1)
+  expect(output).toMatchInlineSnapshot(`
+    "code: BAD
+    message: fail
+    "
+  `)
+})
+
+test('middleware c.error({ exitCode }) uses custom exit code', async () => {
+  const cli = Cli.create('test')
+  cli.use((c) => {
+    return c.error({ code: 'MW_ERR', message: 'blocked', exitCode: 42 })
+  })
+  cli.command('anything', { run: () => ({}) })
+
+  const { output, exitCode } = await serve(cli, ['anything'])
+  expect(exitCode).toBe(42)
+  expect(output).toMatchInlineSnapshot(`
+    "code: MW_ERR
+    message: blocked
+    "
+  `)
+})
+
+test('thrown IncurError with exitCode uses custom exit code', async () => {
+  const cli = Cli.create('test')
+  cli.command('fail', {
+    run() {
+      throw new Errors.IncurError({ code: 'RATE_LIMITED', message: 'too fast', exitCode: 99 })
+    },
+  })
+
+  const { output, exitCode } = await serve(cli, ['fail'])
+  expect(exitCode).toBe(99)
+  expect(output).toMatchInlineSnapshot(`
+    "code: RATE_LIMITED
+    message: too fast
+    retryable: false
+    "
+  `)
+})
+
+test('streaming: c.error({ exitCode }) in yield uses custom exit code', async () => {
+  const cli = Cli.create('test')
+  cli.command('fail', {
+    async *run(c) {
+      yield { step: 1 }
+      yield c.error({ code: 'STREAM_ERR', message: 'mid-stream', exitCode: 77 })
+    },
+  })
+
+  const { output, exitCode } = await serve(cli, ['fail', '--format', 'jsonl'])
+  expect(exitCode).toBe(77)
+  expect(output).toContain('STREAM_ERR')
+})
+
 test('deprecated short flag emits warning', async () => {
   const cli = Cli.create('app').command('deploy', {
     options: z.object({
@@ -2640,3 +2919,553 @@ describe('fetch', async () => {
     expect(output).toContain('Proxy to API')
   })
 })
+
+describe('--filter-output', () => {
+  test('selects specific keys', async () => {
+    const cli = Cli.create('test')
+    cli.command('user', {
+      run() {
+        return { name: 'alice', age: 30, email: 'alice@example.com' }
+      },
+    })
+    const { output } = await serve(cli, ['user', '--filter-output', 'name,age'])
+    expect(output).toMatchInlineSnapshot(`
+      "name: alice
+      age: 30
+      "
+    `)
+  })
+
+  test('returns scalar for single key', async () => {
+    const cli = Cli.create('test')
+    cli.command('greet', {
+      args: z.object({ name: z.string() }),
+      run(c) {
+        return { message: `hello ${c.args.name}` }
+      },
+    })
+    const { output } = await serve(cli, ['greet', 'world', '--filter-output', 'message'])
+    expect(output).toMatchInlineSnapshot(`
+      "hello world
+      "
+    `)
+  })
+
+  test('dot notation filters nested keys', async () => {
+    const cli = Cli.create('test')
+    cli.command('profile', {
+      run() {
+        return { user: { name: 'alice', email: 'a@b.com' }, status: 'active' }
+      },
+    })
+    const { output } = await serve(cli, ['profile', '--filter-output', 'user.name'])
+    expect(output).toMatchInlineSnapshot(`
+      "user:
+        name: alice
+      "
+    `)
+  })
+
+  test('array slice', async () => {
+    const cli = Cli.create('test')
+    cli.command('list', {
+      run() {
+        return { items: [1, 2, 3, 4, 5] }
+      },
+    })
+    const { output } = await serve(cli, ['list', '--filter-output', 'items[0,3]'])
+    expect(output).toMatchInlineSnapshot(`
+      "items[3]: 1,2,3
+      "
+    `)
+  })
+
+  test('works with --format json', async () => {
+    const cli = Cli.create('test')
+    cli.command('user', {
+      run() {
+        return { name: 'alice', age: 30, email: 'alice@example.com' }
+      },
+    })
+    const { output } = await serve(cli, ['user', '--filter-output', 'name,age', '--format', 'json'])
+    const parsed = JSON.parse(output)
+    expect(parsed).toEqual({ name: 'alice', age: 30 })
+  })
+})
+
+async function fetchJson(cli: Cli.Cli<any, any, any>, req: Request) {
+  const res = await cli.fetch(req)
+  const body = await res.json()
+  body.meta.duration = '<stripped>'
+  return { status: res.status, body }
+}
+
+describe('fetch', () => {
+  test('GET /health → 200', async () => {
+    const cli = Cli.create('test')
+    cli.command('health', { run: () => ({ ok: true }) })
+    expect(await fetchJson(cli, new Request('http://localhost/health'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "data": {
+            "ok": true,
+          },
+          "meta": {
+            "command": "health",
+            "duration": "<stripped>",
+          },
+          "ok": true,
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('GET /unknown → 404', async () => {
+    const cli = Cli.create('test')
+    cli.command('health', { run: () => ({}) })
+    expect(await fetchJson(cli, new Request('http://localhost/unknown'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "error": {
+            "code": "COMMAND_NOT_FOUND",
+            "message": "'unknown' is not a command for 'test'.",
+          },
+          "meta": {
+            "command": "unknown",
+            "duration": "<stripped>",
+          },
+          "ok": false,
+        },
+        "status": 404,
+      }
+    `)
+  })
+
+  test('GET / with root command → 200', async () => {
+    const cli = Cli.create('test', { run: () => ({ root: true }) })
+    expect(await fetchJson(cli, new Request('http://localhost/'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "data": {
+            "root": true,
+          },
+          "meta": {
+            "command": "test",
+            "duration": "<stripped>",
+          },
+          "ok": true,
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('GET / without root command → 404', async () => {
+    const cli = Cli.create('test')
+    cli.command('health', { run: () => ({}) })
+    expect(await fetchJson(cli, new Request('http://localhost/'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "error": {
+            "code": "COMMAND_NOT_FOUND",
+            "message": "No root command defined.",
+          },
+          "meta": {
+            "command": "/",
+            "duration": "<stripped>",
+          },
+          "ok": false,
+        },
+        "status": 404,
+      }
+    `)
+  })
+
+  test('GET search params → options', async () => {
+    const cli = Cli.create('test')
+    cli.command('users', {
+      options: z.object({ limit: z.coerce.number().default(10) }),
+      run: (c) => ({ limit: c.options.limit }),
+    })
+    expect(await fetchJson(cli, new Request('http://localhost/users?limit=5'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "data": {
+            "limit": 5,
+          },
+          "meta": {
+            "command": "users",
+            "duration": "<stripped>",
+          },
+          "ok": true,
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('POST body → options', async () => {
+    const cli = Cli.create('test')
+    cli.command('users', {
+      options: z.object({ name: z.string() }),
+      run: (c) => ({ created: true, name: c.options.name }),
+    })
+    const req = new Request('http://localhost/users', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ name: 'Bob' }),
+    })
+    expect(await fetchJson(cli, req)).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "data": {
+            "created": true,
+            "name": "Bob",
+          },
+          "meta": {
+            "command": "users",
+            "duration": "<stripped>",
+          },
+          "ok": true,
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('trailing path segments → positional args', async () => {
+    const cli = Cli.create('test')
+    cli.command('users', {
+      args: z.object({ id: z.coerce.number() }),
+      run: (c) => ({ id: c.args.id }),
+    })
+    expect(await fetchJson(cli, new Request('http://localhost/users/42'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "data": {
+            "id": 42,
+          },
+          "meta": {
+            "command": "users",
+            "duration": "<stripped>",
+          },
+          "ok": true,
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('nested command resolution', async () => {
+    const sub = Cli.create('users')
+    sub.command('list', { run: () => ({ users: [] }) })
+    const cli = Cli.create('test')
+    cli.command(sub)
+    expect(await fetchJson(cli, new Request('http://localhost/users/list'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "data": {
+            "users": [],
+          },
+          "meta": {
+            "command": "users list",
+            "duration": "<stripped>",
+          },
+          "ok": true,
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('validation error → 400', async () => {
+    const cli = Cli.create('test')
+    cli.command('users', {
+      args: z.object({ id: z.coerce.number() }),
+      run: (c) => ({ id: c.args.id }),
+    })
+    const { status, body } = await fetchJson(cli, new Request('http://localhost/users'))
+    expect(status).toBe(400)
+    expect(body.ok).toBe(false)
+    expect(body.error.code).toBe('VALIDATION_ERROR')
+  })
+
+  test('thrown error → 500', async () => {
+    const cli = Cli.create('test')
+    cli.command('fail', {
+      run() {
+        throw new Error('boom')
+      },
+    })
+    expect(await fetchJson(cli, new Request('http://localhost/fail'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "error": {
+            "code": "UNKNOWN",
+            "message": "boom",
+          },
+          "meta": {
+            "command": "fail",
+            "duration": "<stripped>",
+          },
+          "ok": false,
+        },
+        "status": 500,
+      }
+    `)
+  })
+
+  test('async generator → NDJSON streaming response', async () => {
+    const cli = Cli.create('test')
+    cli.command('stream', {
+      async *run() {
+        yield { progress: 1 }
+        yield { progress: 2 }
+        return { done: true }
+      },
+    })
+    const res = await cli.fetch(new Request('http://localhost/stream'))
+    expect(res.status).toBe(200)
+    expect(res.headers.get('content-type')).toBe('application/x-ndjson')
+    const text = await res.text()
+    const lines = text.trim().split('\n').map((l) => JSON.parse(l))
+    expect(lines).toMatchInlineSnapshot(`
+      [
+        {
+          "data": {
+            "progress": 1,
+          },
+          "type": "chunk",
+        },
+        {
+          "data": {
+            "progress": 2,
+          },
+          "type": "chunk",
+        },
+        {
+          "meta": {
+            "command": "stream",
+          },
+          "ok": true,
+          "type": "done",
+        },
+      ]
+    `)
+  })
+
+  test('middleware sets var → command sees it', async () => {
+    const cli = Cli.create('test', {
+      vars: z.object({ user: z.string().default('anonymous') }),
+    })
+    cli.use(async (c, next) => {
+      c.set('user', 'alice')
+      await next()
+    })
+    cli.command('whoami', {
+      run: (c) => ({ user: c.var.user }),
+    })
+    expect(await fetchJson(cli, new Request('http://localhost/whoami'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "data": {
+            "user": "alice",
+          },
+          "meta": {
+            "command": "whoami",
+            "duration": "<stripped>",
+          },
+          "ok": true,
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('middleware error → error response', async () => {
+    const cli = Cli.create('test')
+    cli.use((c) => {
+      c.error({ code: 'UNAUTHORIZED', message: 'not allowed' })
+    })
+    cli.command('secret', { run: () => ({ secret: true }) })
+    expect(await fetchJson(cli, new Request('http://localhost/secret'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "error": {
+            "code": "UNAUTHORIZED",
+            "message": "not allowed",
+          },
+          "meta": {
+            "command": "secret",
+            "duration": "<stripped>",
+          },
+          "ok": false,
+        },
+        "status": 500,
+      }
+    `)
+  })
+
+  test('fetch gateway → forwards request', async () => {
+    const handler = (req: Request) => {
+      const url = new URL(req.url)
+      return new Response(JSON.stringify({ path: url.pathname }), {
+        headers: { 'content-type': 'application/json' },
+      })
+    }
+    const cli = Cli.create('test')
+    cli.command('api', { fetch: handler })
+    const res = await cli.fetch(new Request('http://localhost/api/users/list'))
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body).toMatchInlineSnapshot(`
+      {
+        "path": "/api/users/list",
+      }
+    `)
+  })
+
+  describe('mcp over http', () => {
+    function mcpCli() {
+      const cli = Cli.create('test', { version: '1.0.0' })
+      cli.command('greet', {
+        description: 'Greet someone',
+        args: z.object({ name: z.string() }),
+        run: (c) => ({ message: `hello ${c.args.name}` }),
+      })
+      cli.command('ping', {
+        description: 'Ping',
+        run: () => ({ pong: true }),
+      })
+      return cli
+    }
+
+    async function mcpRequest(cli: Cli.Cli<any, any, any>, body: unknown, sessionId?: string) {
+      const headers: Record<string, string> = { 'content-type': 'application/json', accept: 'application/json, text/event-stream' }
+      if (sessionId) headers['mcp-session-id'] = sessionId
+      return cli.fetch(
+        new Request('http://localhost/mcp', {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(body),
+        }),
+      )
+    }
+
+    async function initSession(cli: Cli.Cli<any, any, any>) {
+      const res = await mcpRequest(cli, {
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2025-03-26',
+          capabilities: {},
+          clientInfo: { name: 'test-client', version: '1.0.0' },
+        },
+      })
+      const sessionId = res.headers.get('mcp-session-id')
+      const body = await res.json()
+      // Send initialized notification
+      await mcpRequest(cli, { jsonrpc: '2.0', method: 'notifications/initialized' }, sessionId!)
+      return { sessionId: sessionId!, body }
+    }
+
+    test('POST /mcp with initialize → valid MCP response', async () => {
+      const cli = mcpCli()
+      const res = await mcpRequest(cli, {
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2025-03-26',
+          capabilities: {},
+          clientInfo: { name: 'test-client', version: '1.0.0' },
+        },
+      })
+      expect(res.status).toBe(200)
+      const body = await res.json()
+      expect({
+        serverInfo: body.result.serverInfo,
+        hasTools: 'tools' in (body.result.capabilities ?? {}),
+      }).toMatchInlineSnapshot(`
+        {
+          "hasTools": true,
+          "serverInfo": {
+            "name": "test",
+            "version": "1.0.0",
+          },
+        }
+      `)
+    })
+
+    test('POST /mcp with tools/list → returns registered tools', async () => {
+      const cli = mcpCli()
+      const { sessionId } = await initSession(cli)
+      const res = await mcpRequest(
+        cli,
+        { jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} },
+        sessionId,
+      )
+      expect(res.status).toBe(200)
+      const body = await res.json()
+      const tools = body.result.tools.map((t: any) => ({
+        name: t.name,
+        description: t.description,
+        hasInputSchema: Object.keys(t.inputSchema?.properties ?? {}).length > 0,
+      }))
+      expect(tools).toMatchInlineSnapshot(`
+        [
+          {
+            "description": "Greet someone",
+            "hasInputSchema": true,
+            "name": "greet",
+          },
+          {
+            "description": "Ping",
+            "hasInputSchema": false,
+            "name": "ping",
+          },
+        ]
+      `)
+    })
+
+    test('POST /mcp with tools/call → executes command', async () => {
+      const cli = mcpCli()
+      const { sessionId } = await initSession(cli)
+      const res = await mcpRequest(
+        cli,
+        {
+          jsonrpc: '2.0',
+          id: 3,
+          method: 'tools/call',
+          params: { name: 'greet', arguments: { name: 'world' } },
+        },
+        sessionId,
+      )
+      expect(res.status).toBe(200)
+      const body = await res.json()
+      expect({
+        isError: body.result.isError,
+        content: JSON.parse(body.result.content[0].text),
+      }).toMatchInlineSnapshot(`
+        {
+          "content": {
+            "message": "hello world",
+          },
+          "isError": undefined,
+        }
+      `)
+    })
+
+    test('non-/mcp paths still route to command API', async () => {
+      const cli = mcpCli()
+      const { body } = await fetchJson(cli, new Request('http://localhost/ping'))
+      expect(body.data).toMatchInlineSnapshot(`
+        {
+          "pong": true,
+        }
+      `)
+    })
+  })
+})