feat: add OpenAPI-first discovery tooling

.changeset/discovery-openapi-consolidation.md

@@ -0,0 +1,11 @@
+---
+'mppx': minor
+---
+
+Add OpenAPI-first discovery tooling via `mppx/discovery`, framework `discovery()` helpers, and `mppx discover validate`.
+
+This also changes `mppx/proxy` discovery routes:
+
+- `GET /openapi.json` is now the canonical machine-readable discovery document.
+- `GET /llms.txt` remains available as the text-friendly discovery view.
+- Legacy `/discover*` routes now return `410 Gone`.

AGENTS.md

@@ -115,7 +115,7 @@ Canonical specs live at [tempoxyz/payment-auth-spec](https://github.com/tempoxyz
 | **Intent**    | [draft-payment-intent-session-00](https://github.com/tempoxyz/payment-auth-spec/blob/main/specs/intents/draft-payment-intent-session-00.md) | Pay-as-you-go streaming payments                                        |
 | **Method**    | [draft-tempo-charge-00](https://github.com/tempoxyz/payment-auth-spec/blob/main/specs/methods/tempo/draft-tempo-charge-00.md)               | TIP-20 token transfers on Tempo                                         |
 | **Method**    | [draft-tempo-session-00](https://github.com/tempoxyz/payment-auth-spec/blob/main/specs/methods/tempo/draft-tempo-session-00.md)             | Tempo payment channels for streaming                                    |
-| **Extension** | [draft-payment-discovery-00](https://github.com/tempoxyz/payment-auth-spec/blob/main/specs/extensions/draft-payment-discovery-00.md)        | `/.well-known/payment` discovery                                        |
+| **Extension** | [draft-payment-discovery-00](https://paymentauth.org/draft-payment-discovery-00.html)                                                       | OpenAPI-first discovery via `/openapi.json`                             |
 
 ### Key Protocol Details
 

package.json

@@ -82,6 +82,11 @@
       "src": "./src/client/index.ts",
       "default": "./dist/client/index.js"
     },
+    "./discovery": {
+      "types": "./dist/discovery/index.d.ts",
+      "src": "./src/discovery/index.ts",
+      "default": "./dist/discovery/index.js"
+    },
     "./mcp-sdk/client": {
       "types": "./dist/mcp-sdk/client/index.d.ts",
       "src": "./src/mcp-sdk/client/index.ts",

src/cli/cli.test.ts

@@ -76,6 +76,217 @@ async function serve(argv: string[], options?: { env?: Record<string, string | u
   return { output, stderr, exitCode }
 }
 
+describe('discover validate', () => {
+  test('validates a local discovery document', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mppx-discovery-'))
+    const file = path.join(dir, 'openapi.json')
+    fs.writeFileSync(
+      file,
+      JSON.stringify({
+        info: { title: 'Test', version: '1.0.0' },
+        openapi: '3.1.0',
+        paths: {
+          '/search': {
+            post: {
+              'x-payment-info': {
+                amount: '100',
+                intent: 'charge',
+                method: 'tempo',
+              },
+              requestBody: {
+                content: { 'application/json': { schema: { type: 'object' } } },
+              },
+              responses: {
+                '200': { description: 'OK' },
+                '402': { description: 'Payment Required' },
+              },
+            },
+          },
+        },
+      }),
+    )
+
+    const { output, exitCode } = await serve(['discover', 'validate', file])
+    expect(exitCode).toBeUndefined()
+    expect(output).toContain('Discovery document is valid.')
+  })
+
+  test('returns non-zero for invalid discovery documents', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mppx-discovery-'))
+    const file = path.join(dir, 'openapi.json')
+    fs.writeFileSync(
+      file,
+      JSON.stringify({
+        info: { title: 'Test', version: '1.0.0' },
+        openapi: '3.1.0',
+        paths: {
+          '/search': {
+            post: {
+              'x-payment-info': {
+                amount: '100',
+                intent: 'charge',
+                method: 'tempo',
+              },
+              responses: {
+                '200': { description: 'OK' },
+              },
+            },
+          },
+        },
+      }),
+    )
+
+    const { output, exitCode } = await serve(['discover', 'validate', file])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('[error]')
+    expect(output).toContain('402')
+  })
+
+  test(
+    'validates remote discovery documents and reports warnings',
+    { timeout: 20_000 },
+    async () => {
+      const body = JSON.stringify({
+        info: { title: 'Test', version: '1.0.0' },
+        openapi: '3.1.0',
+        paths: {
+          '/search': {
+            post: {
+              'x-payment-info': {
+                amount: '100',
+                intent: 'charge',
+                method: 'tempo',
+              },
+              responses: {
+                '200': { description: 'OK' },
+                '402': { description: 'Payment Required' },
+              },
+            },
+          },
+        },
+      })
+      const server = await Http.createServer((_req, res) => {
+        res.setHeader('Content-Type', 'application/json')
+        res.end(body)
+      })
+
+      try {
+        const { output, exitCode } = await serve(['discover', 'validate', server.url])
+        expect(exitCode).toBeUndefined()
+        expect(output).toContain('[warning]')
+        expect(output).toContain('requestBody')
+        expect(output).toContain('valid with 1 warning')
+      } finally {
+        server.close()
+      }
+    },
+  )
+
+  test(
+    'rejects oversized discovery documents via content-length',
+    { timeout: 20_000 },
+    async () => {
+      const server = await Http.createServer((_req, res) => {
+        res.setHeader('Content-Type', 'application/json')
+        res.setHeader('Content-Length', String(11 * 1024 * 1024))
+        res.end('{}')
+      })
+
+      try {
+        const { exitCode, output } = await serve(['discover', 'validate', server.url])
+        expect(exitCode).toBe(1)
+        expect(output).toContain('10 MB')
+      } finally {
+        server.close()
+      }
+    },
+  )
+})
+
+describe('discover generate', () => {
+  test('generates from a pre-built OpenAPI document module', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mppx-generate-'))
+    const mod = path.join(dir, 'doc.mjs')
+    fs.writeFileSync(
+      mod,
+      `export default ${JSON.stringify({
+        openapi: '3.1.0',
+        info: { title: 'Test', version: '1.0.0' },
+        paths: {
+          '/pay': {
+            post: {
+              'x-payment-info': { amount: '100', intent: 'charge', method: 'tempo' },
+              responses: {
+                '200': { description: 'OK' },
+                '402': { description: 'Payment Required' },
+              },
+            },
+          },
+        },
+      })}`,
+    )
+
+    const { output, exitCode } = await serve(['discover', 'generate', mod])
+    expect(exitCode).toBeUndefined()
+    const doc = JSON.parse(output)
+    expect(doc.openapi).toBe('3.1.0')
+    expect(doc.paths['/pay'].post['x-payment-info'].amount).toBe('100')
+
+    fs.rmSync(dir, { recursive: true, force: true })
+  })
+
+  test('writes to file with --output', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mppx-generate-'))
+    const mod = path.join(dir, 'doc.mjs')
+    const outFile = path.join(dir, 'openapi.json')
+    fs.writeFileSync(
+      mod,
+      `export default ${JSON.stringify({
+        openapi: '3.1.0',
+        info: { title: 'Test', version: '1.0.0' },
+        paths: {},
+      })}`,
+    )
+
+    const { output, stderr, exitCode } = await serve([
+      'discover',
+      'generate',
+      mod,
+      '--output',
+      outFile,
+    ])
+    expect(exitCode).toBeUndefined()
+    expect(output).toBe('')
+    expect(stderr).toContain(outFile)
+    const written = JSON.parse(fs.readFileSync(outFile, 'utf-8'))
+    expect(written.openapi).toBe('3.1.0')
+
+    fs.rmSync(dir, { recursive: true, force: true })
+  })
+
+  test('errors when module not found', async () => {
+    const { output, exitCode } = await serve([
+      'discover',
+      'generate',
+      '/tmp/nonexistent-mppx-module.mjs',
+    ])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('MODULE_NOT_FOUND')
+  })
+
+  test('errors when module has no mppx or openapi export', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mppx-generate-'))
+    const mod = path.join(dir, 'bad.mjs')
+    fs.writeFileSync(mod, 'export default { foo: "bar" }')
+
+    const { output, exitCode } = await serve(['discover', 'generate', mod])
+    expect(exitCode).toBe(1)
+    expect(output).toContain('INVALID_MODULE')
+
+    fs.rmSync(dir, { recursive: true, force: true })
+  })
+})
+
 describe('basic charge (examples/basic)', () => {
   test('happy path: makes payment and receives response', { timeout: 120_000 }, async () => {
     const { Actions } = await import('viem/tempo')