incur 0.1.17 → 0.2.1

package/src/e2e.test.ts

@@ -1,4 +1,5 @@
 import { Cli, Errors, Skill, Typegen, z } from 'incur'
+import { app as honoApp } from '../test/fixtures/hono-api.js'
 
 let __mockSkillsHash: string | undefined
 
@@ -821,6 +822,7 @@ describe('help', () => {
       Usage: app <command>
 
       Commands:
+        api            Proxy to HTTP API
         auth           Authentication commands
         config         Show current configuration
         echo           Echo back arguments
@@ -843,10 +845,12 @@ 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
         --verbose                           Show full output envelope
         --version                           Show version
       "
@@ -872,9 +876,11 @@ describe('help', () => {
         status  Show authentication status
 
       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
         --verbose                           Show full output envelope
       "
     `)
@@ -894,9 +900,11 @@ describe('help', () => {
         status    Check deployment status
 
       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
         --verbose                           Show full output envelope
       "
     `)
@@ -915,9 +923,11 @@ describe('help', () => {
         --archived <boolean>  Include archived (default: false)
 
       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
         --verbose                           Show full output envelope
       "
     `)
@@ -942,9 +952,11 @@ describe('help', () => {
         $ app project deploy create production --branch release --dryRun true  # Dry run a production 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
         --verbose                           Show full output envelope
       "
     `)
@@ -980,6 +992,7 @@ describe('--llms', () => {
     const names = manifest.commands.map((c: any) => c.name)
     expect(names).toMatchInlineSnapshot(`
       [
+        "api",
         "auth login",
         "auth logout",
         "auth status",
@@ -1180,6 +1193,7 @@ describe('typegen', () => {
       "declare module 'incur' {
         interface Register {
           commands: {
+            'api': { args: {}; options: {} }
             'auth login': { args: {}; options: { hostname: string; web: boolean; scopes: string[] } }
             'auth logout': { args: {}; options: {} }
             'auth status': { args: {}; options: {} }
@@ -1338,10 +1352,12 @@ describe('root command with subcommands', () => {
         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
         --verbose                           Show full output envelope
         --version                           Show version
       "
@@ -1510,9 +1526,11 @@ describe('env', () => {
         --scopes <array>         OAuth scopes
 
       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
         --verbose                           Show full output envelope
 
       Environment Variables:
@@ -1764,6 +1782,765 @@ describe('deprecated flags', () => {
   })
 })
 
+describe('fetch gateway', () => {
+  test('routes to fetch handler', async () => {
+    const { output } = await serve(createApp(), ['api', 'health'])
+    expect(output).toMatchInlineSnapshot(`
+      "ok: true
+      "
+    `)
+  })
+
+  test('path segments map to URL path', async () => {
+    const { output } = await serve(createApp(), ['api', 'users'])
+    expect(output).toContain('Alice')
+  })
+
+  test('path segments with dynamic params', async () => {
+    const { output } = await serve(createApp(), ['api', 'users', '42'])
+    expect(output).toMatchInlineSnapshot(`
+      "id: 42
+      name: Alice
+      "
+    `)
+  })
+
+  test('query params from --key value', async () => {
+    const { output } = await serve(createApp(), ['api', 'users', '--limit', '5'])
+    const { output: jsonOut } = await serve(createApp(), [
+      'api',
+      'users',
+      '--limit',
+      '5',
+      '--format',
+      'json',
+    ])
+    expect(json(jsonOut).limit).toBe(5)
+  })
+
+  test('POST with -X and -d', async () => {
+    const { output } = await serve(createApp(), [
+      'api',
+      'users',
+      '-X',
+      'POST',
+      '-d',
+      '{"name":"Bob"}',
+    ])
+    expect(output).toMatchInlineSnapshot(`
+      "created: true
+      name: Bob
+      "
+    `)
+  })
+
+  test('implicit POST with --body', async () => {
+    const { output } = await serve(createApp(), [
+      'api',
+      'users',
+      '--body',
+      '{"name":"Eve"}',
+    ])
+    expect(output).toMatchInlineSnapshot(`
+      "created: true
+      name: Eve
+      "
+    `)
+  })
+
+  test('DELETE with --method', async () => {
+    const { output } = await serve(createApp(), [
+      'api',
+      'users',
+      '1',
+      '--method',
+      'DELETE',
+    ])
+    expect(output).toMatchInlineSnapshot(`
+      "deleted: true
+      id: 1
+      "
+    `)
+  })
+
+  test('error response produces error envelope', async () => {
+    const { output, exitCode } = await serve(createApp(), ['api', 'error'])
+    expect(exitCode).toBe(1)
+    expect(output).toMatchInlineSnapshot(`
+      "code: HTTP_404
+      message: not found
+      "
+    `)
+  })
+
+  test('text response', async () => {
+    const { output } = await serve(createApp(), ['api', 'text'])
+    expect(output).toMatchInlineSnapshot(`
+      "hello world
+      "
+    `)
+  })
+
+  test('--format json', async () => {
+    const { output } = await serve(createApp(), ['api', 'health', '--format', 'json'])
+    expect(json(output)).toEqual({ ok: true })
+  })
+
+  test('--verbose wraps in envelope', async () => {
+    const { output } = await serve(createApp(), [
+      'api',
+      'health',
+      '--verbose',
+      '--format',
+      'json',
+    ])
+    const parsed = json(output)
+    expect(parsed.ok).toBe(true)
+    expect(parsed.data).toEqual({ ok: true })
+    expect(parsed.meta.command).toBe('api')
+    expect(parsed.meta.duration).toBeDefined()
+  })
+
+  test('--help shows curl-style flags', async () => {
+    const { output } = await serve(createApp(), ['api', '--help'])
+    expect(output).toContain('Proxy to HTTP API')
+    expect(output).toContain('--method')
+    expect(output).toContain('--header')
+    expect(output).toContain('--body')
+    expect(output).toContain('--data')
+  })
+
+  test('appears in root --help', async () => {
+    const { output } = await serve(createApp(), ['--help'])
+    expect(output).toContain('api')
+    expect(output).toContain('Proxy to HTTP API')
+  })
+
+  test('appears in --llms', async () => {
+    const { output } = await serve(createApp(), ['--llms'])
+    expect(output).toContain('api')
+    expect(output).toContain('Proxy to HTTP API')
+  })
+
+  test('coexists with native commands', async () => {
+    const { output: fetchOut } = await serve(createApp(), ['api', 'health'])
+    expect(fetchOut).toContain('ok: true')
+    const { output: nativeOut } = await serve(createApp(), ['ping'])
+    expect(nativeOut).toContain('pong: true')
+  })
+
+  test('streaming NDJSON response', async () => {
+    const { output } = await serve(createApp(), ['api', 'stream'])
+    expect(output).toMatchInlineSnapshot(`
+      "progress: 1
+      progress: 2
+      "
+    `)
+  })
+
+  test('streaming NDJSON --format json buffers all chunks', async () => {
+    const { output } = await serve(createApp(), ['api', 'stream', '--format', 'json'])
+    expect(json(output)).toEqual([{ progress: 1 }, { progress: 2 }])
+  })
+
+  test('streaming NDJSON --format jsonl', async () => {
+    const { output } = await serve(createApp(), ['api', 'stream', '--format', 'jsonl'])
+    const lines = output.trim().split('\n').map((l) => JSON.parse(l))
+    expect(lines[0]).toEqual({ type: 'chunk', data: { progress: 1 } })
+    expect(lines[1]).toEqual({ type: 'chunk', data: { progress: 2 } })
+    expect(lines[2].type).toBe('done')
+  })
+})
+
+async function fetchJson(cli: Cli.Cli<any, any, any>, req: Request) {
+  const res = await cli.fetch(req)
+  const body = await res.json()
+  if (body.meta?.duration) body.meta.duration = '<stripped>'
+  return { status: res.status, body }
+}
+
+describe('fetch api', () => {
+  test('GET /ping → 200 with data', async () => {
+    const cli = createApp()
+    expect(await fetchJson(cli, new Request('http://localhost/ping'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "data": {
+            "pong": true,
+          },
+          "meta": {
+            "command": "ping",
+            "duration": "<stripped>",
+          },
+          "ok": true,
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('GET /unknown → 404', async () => {
+    const cli = createApp()
+    expect(await fetchJson(cli, new Request('http://localhost/unknown'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "error": {
+            "code": "COMMAND_NOT_FOUND",
+            "message": "'unknown' is not a command for 'app'.",
+          },
+          "meta": {
+            "command": "unknown",
+            "duration": "<stripped>",
+          },
+          "ok": false,
+        },
+        "status": 404,
+      }
+    `)
+  })
+
+  test('GET / without root command → 404', async () => {
+    const cli = createApp()
+    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 with query params → options', async () => {
+    const cli = createApp()
+    expect(await fetchJson(cli, new Request('http://localhost/echo/hi?prefix=yo'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "data": {
+            "result": [
+              "yo hi",
+            ],
+          },
+          "meta": {
+            "command": "echo",
+            "duration": "<stripped>",
+          },
+          "ok": true,
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('POST with JSON body → options', async () => {
+    const cli = createApp()
+    const req = new Request('http://localhost/project/create/MyProject', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ description: 'A test project' }),
+    })
+    expect(await fetchJson(cli, req)).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "data": {
+            "id": "p-new",
+            "url": "https://example.com/projects/p-new",
+          },
+          "meta": {
+            "command": "project create",
+            "duration": "<stripped>",
+          },
+          "ok": true,
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('trailing path segments → positional args', async () => {
+    const cli = createApp()
+    expect(await fetchJson(cli, new Request('http://localhost/project/get/p1'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "data": {
+            "description": "Main project",
+            "id": "p1",
+            "members": [
+              {
+                "role": "admin",
+                "userId": "u1",
+              },
+            ],
+            "name": "Alpha",
+          },
+          "meta": {
+            "command": "project get",
+            "duration": "<stripped>",
+          },
+          "ok": true,
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('nested command (3 levels deep)', async () => {
+    const cli = createApp()
+    expect(await fetchJson(cli, new Request('http://localhost/project/deploy/status/d-456'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "data": {
+            "deployId": "d-456",
+            "progress": 75,
+            "status": "running",
+          },
+          "meta": {
+            "command": "project deploy status",
+            "duration": "<stripped>",
+          },
+          "ok": true,
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('thrown error → 500', async () => {
+    const cli = createApp()
+    expect(await fetchJson(cli, new Request('http://localhost/explode'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "error": {
+            "code": "UNKNOWN",
+            "message": "kaboom",
+          },
+          "meta": {
+            "command": "explode",
+            "duration": "<stripped>",
+          },
+          "ok": false,
+        },
+        "status": 500,
+      }
+    `)
+  })
+
+  test('IncurError → 500 with code', async () => {
+    const cli = createApp()
+    expect(await fetchJson(cli, new Request('http://localhost/explode-clac'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "error": {
+            "code": "QUOTA_EXCEEDED",
+            "message": "Rate limit exceeded",
+          },
+          "meta": {
+            "command": "explode-clac",
+            "duration": "<stripped>",
+          },
+          "ok": false,
+        },
+        "status": 500,
+      }
+    `)
+  })
+
+  test('validation error → 400', async () => {
+    const cli = createApp()
+    const { status, body } = await fetchJson(cli, new Request('http://localhost/validate-fail'))
+    expect(status).toBe(400)
+    expect(body.ok).toBe(false)
+    expect(body.error.code).toBe('VALIDATION_ERROR')
+  })
+
+  test('async generator → NDJSON streaming', async () => {
+    const cli = createApp()
+    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 lines = (await res.text()).trim().split('\n').map((l) => JSON.parse(l))
+    expect(lines).toMatchInlineSnapshot(`
+      [
+        {
+          "data": {
+            "content": "hello",
+          },
+          "type": "chunk",
+        },
+        {
+          "data": {
+            "content": "world",
+          },
+          "type": "chunk",
+        },
+        {
+          "meta": {
+            "command": "stream",
+          },
+          "ok": true,
+          "type": "done",
+        },
+      ]
+    `)
+  })
+
+  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'))
+    expect(res.status).toBe(200)
+    expect(await res.json()).toMatchInlineSnapshot(`
+      {
+        "path": "/api/users",
+      }
+    `)
+  })
+
+  test('middleware sets var → command sees it', async () => {
+    const { cli } = createMiddlewareApp()
+    expect(await fetchJson(cli, new Request('http://localhost/whoami'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "data": {
+            "requestId": "req-default",
+            "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: 'FORBIDDEN', message: 'nope' }) })
+    cli.command('secret', { run: () => ({ secret: true }) })
+    expect(await fetchJson(cli, new Request('http://localhost/secret'))).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "error": {
+            "code": "FORBIDDEN",
+            "message": "nope",
+          },
+          "meta": {
+            "command": "secret",
+            "duration": "<stripped>",
+          },
+          "ok": false,
+        },
+        "status": 500,
+      }
+    `)
+  })
+
+  describe('mcp over http', () => {
+    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')!
+      await mcpRequest(cli, { jsonrpc: '2.0', method: 'notifications/initialized' }, sessionId)
+      return sessionId
+    }
+
+    test('initialize → returns server info and capabilities', async () => {
+      const cli = createApp()
+      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": "app",
+            "version": "3.5.0",
+          },
+        }
+      `)
+    })
+
+    test('tools/list → lists all registered tools', async () => {
+      const cli = createApp()
+      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 names = body.result.tools.map((t: any) => t.name).sort()
+      expect(names).toMatchInlineSnapshot(`
+        [
+          "api",
+          "auth_login",
+          "auth_logout",
+          "auth_status",
+          "config",
+          "echo",
+          "explode",
+          "explode-clac",
+          "noop",
+          "ping",
+          "project_create",
+          "project_delete",
+          "project_deploy_create",
+          "project_deploy_rollback",
+          "project_deploy_status",
+          "project_get",
+          "project_list",
+          "slow",
+          "stream",
+          "stream-error",
+          "stream-ok",
+          "stream-text",
+          "stream-throw",
+          "validate-fail",
+        ]
+      `)
+    })
+
+    test('tools/call → executes command and returns result', async () => {
+      const cli = createApp()
+      const sessionId = await initSession(cli)
+      const res = await mcpRequest(
+        cli,
+        {
+          jsonrpc: '2.0',
+          id: 3,
+          method: 'tools/call',
+          params: { name: 'echo', arguments: { message: 'hello' } },
+        },
+        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": {
+            "result": [
+              "hello",
+            ],
+          },
+          "isError": undefined,
+        }
+      `)
+    })
+
+    test('tools/call with nested command', async () => {
+      const cli = createApp()
+      const sessionId = await initSession(cli)
+      const res = await mcpRequest(
+        cli,
+        {
+          jsonrpc: '2.0',
+          id: 4,
+          method: 'tools/call',
+          params: { name: 'project_get', arguments: { id: 'p1' } },
+        },
+        sessionId,
+      )
+      expect(res.status).toBe(200)
+      const body = await res.json()
+      expect(JSON.parse(body.result.content[0].text)).toMatchInlineSnapshot(`
+        {
+          "description": "Main project",
+          "id": "p1",
+          "members": [
+            {
+              "role": "admin",
+              "userId": "u1",
+            },
+          ],
+          "name": "Alpha",
+        }
+      `)
+    })
+
+    test('tools/call with error → isError true', async () => {
+      const cli = createApp()
+      const sessionId = await initSession(cli)
+      const res = await mcpRequest(
+        cli,
+        {
+          jsonrpc: '2.0',
+          id: 5,
+          method: 'tools/call',
+          params: { name: 'explode', arguments: {} },
+        },
+        sessionId,
+      )
+      expect(res.status).toBe(200)
+      const body = await res.json()
+      expect({
+        isError: body.result.isError,
+        text: body.result.content[0].text,
+      }).toMatchInlineSnapshot(`
+        {
+          "isError": true,
+          "text": "kaboom",
+        }
+      `)
+    })
+
+    test('non-/mcp paths still work alongside MCP', async () => {
+      const cli = createApp()
+      // Initialize MCP first
+      await initSession(cli)
+      // Regular fetch still works
+      expect(await fetchJson(cli, new Request('http://localhost/ping'))).toMatchInlineSnapshot(`
+        {
+          "body": {
+            "data": {
+              "pong": true,
+            },
+            "meta": {
+              "command": "ping",
+              "duration": "<stripped>",
+            },
+            "ok": true,
+          },
+          "status": 200,
+        }
+      `)
+    })
+  })
+})
+
+describe('.well-known/skills', () => {
+  async function fetchSkills(cli: Cli.Cli<any, any, any>, path: string) {
+    const res = await cli.fetch(new Request(`http://localhost${path}`))
+    const contentType = res.headers.get('content-type')
+    const body = contentType?.includes('json') ? await res.json() : await res.text()
+    return { status: res.status, contentType, cacheControl: res.headers.get('cache-control'), body }
+  }
+
+  test('GET /.well-known/skills/index.json returns skill index', async () => {
+    const cli = createApp()
+    const result = await fetchSkills(cli, '/.well-known/skills/index.json')
+    expect(result.status).toBe(200)
+    expect(result.contentType).toBe('application/json')
+    expect(result.cacheControl).toBe('public, max-age=300')
+    const names = result.body.skills.map((s: any) => s.name)
+    expect(names).toMatchInlineSnapshot(`
+      [
+        "api",
+        "auth",
+        "config",
+        "echo",
+        "explode",
+        "explode-clac",
+        "noop",
+        "ping",
+        "project",
+        "slow",
+        "stream",
+        "stream-error",
+        "stream-ok",
+        "stream-text",
+        "stream-throw",
+        "validate-fail",
+      ]
+    `)
+    expect(result.body.skills[0]).toMatchInlineSnapshot(`
+      {
+        "description": "Proxy to HTTP API. Run \`app api --help\` for usage details.",
+        "files": [
+          "SKILL.md",
+        ],
+        "name": "api",
+      }
+    `)
+  })
+
+  test('GET /.well-known/skills/{name}/SKILL.md returns skill markdown', async () => {
+    const cli = createApp()
+    const result = await fetchSkills(cli, '/.well-known/skills/ping/SKILL.md')
+    expect(result.status).toBe(200)
+    expect(result.contentType).toBe('text/markdown')
+    expect(result.cacheControl).toBe('public, max-age=300')
+    expect(result.body).toMatchInlineSnapshot(`
+      "---
+      name: app-ping
+      description: Health check. Run \`app ping --help\` for usage details.
+      command: app ping
+      ---
+
+      # app ping
+
+      Health check"
+    `)
+  })
+
+  test('GET /.well-known/skills/unknown/SKILL.md → 404', async () => {
+    const cli = createApp()
+    const result = await fetchSkills(cli, '/.well-known/skills/nonexistent/SKILL.md')
+    expect(result.status).toBe(404)
+  })
+
+  test('GET /.well-known/skills/unknown-path → 404', async () => {
+    const cli = createApp()
+    const result = await fetchSkills(cli, '/.well-known/skills/bad-path')
+    expect(result.status).toBe(404)
+  })
+})
+
 async function serve(
   cli: { serve: Cli.Cli['serve'] },
   argv: string[],
@@ -2174,6 +2951,7 @@ function createApp() {
   cli.command(auth)
   cli.command(project)
   cli.command(config)
+  cli.command('api', { description: 'Proxy to HTTP API', fetch: honoApp.fetch })
 
   return cli
 }