mppx 0.8.6 → 0.8.8

package/src/cli/validate/discovery.test.ts

@@ -0,0 +1,307 @@
+import { describe, expect, test } from 'vp/test'
+
+import {
+  buildUrl,
+  extractEndpointsFromDiscovery,
+  extractRequestBodyFromDiscovery,
+} from './discovery.js'
+
+describe('buildUrl', () => {
+  describe('path parameters', () => {
+    test('substitutes param with example from parameter', () => {
+      const endpoint = {
+        method: 'GET',
+        path: '/users/{userId}/posts',
+        parameters: [{ name: 'userId', in: 'path' as const, example: 'abc-123' }],
+      }
+      expect(buildUrl('http://localhost', endpoint)).toBe('http://localhost/users/abc-123/posts')
+    })
+
+    test('substitutes param with example from schema', () => {
+      const endpoint = {
+        method: 'GET',
+        path: '/orders/{orderId}',
+        parameters: [{ name: 'orderId', in: 'path' as const, schema: { example: 'ORD-001' } }],
+      }
+      expect(buildUrl('http://localhost', endpoint)).toBe('http://localhost/orders/ORD-001')
+    })
+
+    test('substitutes param with default from schema', () => {
+      const endpoint = {
+        method: 'GET',
+        path: '/items/{itemId}',
+        parameters: [{ name: 'itemId', in: 'path' as const, schema: { default: '42' } }],
+      }
+      expect(buildUrl('http://localhost', endpoint)).toBe('http://localhost/items/42')
+    })
+
+    test('leaves placeholder when no example available', () => {
+      const endpoint = {
+        method: 'GET',
+        path: '/users/{userId}',
+        parameters: [{ name: 'userId', in: 'path' as const, schema: { type: 'string' } }],
+      }
+      expect(buildUrl('http://localhost', endpoint)).toBe('http://localhost/users/%7BuserId%7D')
+    })
+
+    test('handles multiple path params', () => {
+      const endpoint = {
+        method: 'GET',
+        path: '/orgs/{orgId}/repos/{repoId}',
+        parameters: [
+          { name: 'orgId', in: 'path' as const, example: 'stripe' },
+          { name: 'repoId', in: 'path' as const, example: 'mppx' },
+        ],
+      }
+      expect(buildUrl('http://localhost', endpoint)).toBe('http://localhost/orgs/stripe/repos/mppx')
+    })
+
+    test('encodes special characters', () => {
+      const endpoint = {
+        method: 'GET',
+        path: '/search/{query}',
+        parameters: [{ name: 'query', in: 'path' as const, example: 'hello world' }],
+      }
+      expect(buildUrl('http://localhost', endpoint)).toBe('http://localhost/search/hello%20world')
+    })
+
+    test('no parameters field leaves path as-is', () => {
+      const endpoint = { method: 'GET', path: '/simple' }
+      expect(buildUrl('http://localhost', endpoint)).toBe('http://localhost/simple')
+    })
+  })
+
+  describe('subpath base URL', () => {
+    test('preserves base URL subpath', () => {
+      const endpoint = { method: 'POST', path: '/plan' }
+      expect(buildUrl('http://localhost/mpp', endpoint)).toBe('http://localhost/mpp/plan')
+    })
+
+    test('preserves nested subpath', () => {
+      const endpoint = { method: 'GET', path: '/users/123' }
+      expect(buildUrl('http://localhost/api/v1', endpoint)).toBe(
+        'http://localhost/api/v1/users/123',
+      )
+    })
+
+    test('works with trailing slash on base', () => {
+      const endpoint = { method: 'POST', path: '/plan' }
+      expect(buildUrl('http://localhost/mpp/', endpoint)).toBe('http://localhost/mpp/plan')
+    })
+  })
+})
+
+describe('extractEndpointsFromDiscovery', () => {
+  describe('path parameters', () => {
+    test('extracts parameters from OpenAPI doc', () => {
+      const doc = {
+        openapi: '3.1.0',
+        paths: {
+          '/users/{userId}': {
+            parameters: [
+              { name: 'userId', in: 'path', schema: { type: 'string', example: 'u-1' } },
+            ],
+            get: {
+              'x-payment-info': { amount: '100' },
+              responses: { '402': {} },
+            },
+          },
+        },
+      }
+      const endpoints = extractEndpointsFromDiscovery(doc as Record<string, unknown>)
+      expect(endpoints).toHaveLength(1)
+      expect(endpoints[0]!.parameters).toHaveLength(1)
+      expect(endpoints[0]!.parameters![0]!.name).toBe('userId')
+      expect(buildUrl('http://localhost', endpoints[0]!)).toBe('http://localhost/users/u-1')
+    })
+
+    test('operation params override path-level params', () => {
+      const doc = {
+        openapi: '3.1.0',
+        paths: {
+          '/items/{id}': {
+            parameters: [{ name: 'id', in: 'path', example: 'path-level' }],
+            post: {
+              'x-payment-info': { amount: '100' },
+              parameters: [{ name: 'id', in: 'path', example: 'op-level' }],
+            },
+          },
+        },
+      }
+      const endpoints = extractEndpointsFromDiscovery(doc as Record<string, unknown>)
+      expect(buildUrl('http://localhost', endpoints[0]!)).toBe('http://localhost/items/op-level')
+    })
+  })
+
+  describe('endpoint selection', () => {
+    test('prefers x-payment-info endpoints over 402 heuristic', () => {
+      const doc = {
+        paths: {
+          '/paid': { post: { 'x-payment-info': { amount: '100' }, responses: { '402': {} } } },
+          '/maybe': { get: { responses: { '402': {} } } },
+        },
+      }
+      const endpoints = extractEndpointsFromDiscovery(doc as Record<string, unknown>)
+      expect(endpoints).toHaveLength(1)
+      expect(endpoints[0]!.path).toBe('/paid')
+    })
+
+    test('falls back to 402 heuristic when no x-payment-info', () => {
+      const doc = {
+        paths: {
+          '/a': { get: { responses: { '402': {} } } },
+          '/b': { post: { responses: { '402': {} } } },
+        },
+      }
+      const endpoints = extractEndpointsFromDiscovery(doc as Record<string, unknown>)
+      expect(endpoints).toHaveLength(2)
+    })
+
+    test('returns empty for no paths', () => {
+      expect(extractEndpointsFromDiscovery({} as Record<string, unknown>)).toEqual([])
+    })
+
+    test('captures amount from x-payment-info', () => {
+      const doc = {
+        paths: {
+          '/api/generate': {
+            post: { 'x-payment-info': { amount: '50000' }, responses: { '402': {} } },
+          },
+        },
+      }
+      const endpoints = extractEndpointsFromDiscovery(doc as Record<string, unknown>)
+      expect(endpoints[0]!.amount).toBe('50000')
+    })
+  })
+})
+
+describe('extractRequestBodyFromDiscovery', () => {
+  test('returns explicit example from content', () => {
+    const doc = {
+      paths: {
+        '/api/test': {
+          post: {
+            requestBody: {
+              content: {
+                'application/json': { example: { prompt: 'hello' } },
+              },
+            },
+          },
+        },
+      },
+    }
+    const body = extractRequestBodyFromDiscovery(doc as Record<string, unknown>, {
+      method: 'POST',
+      path: '/api/test',
+    })
+    expect(body).toBe('{"prompt":"hello"}')
+  })
+
+  test('generates body from schema with required fields', () => {
+    const doc = {
+      paths: {
+        '/api/test': {
+          post: {
+            requestBody: {
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    required: ['query', 'count'],
+                    properties: {
+                      query: { type: 'string', example: 'test query' },
+                      count: { type: 'integer', default: 10 },
+                      optional: { type: 'string' },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    }
+    const body = extractRequestBodyFromDiscovery(doc as Record<string, unknown>, {
+      method: 'POST',
+      path: '/api/test',
+    })
+    expect(JSON.parse(body!)).toEqual({ query: 'test query', count: 10 })
+  })
+
+  test('uses schema defaults for scalar types', () => {
+    const doc = {
+      paths: {
+        '/api/test': {
+          post: {
+            requestBody: {
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    required: ['email', 'active'],
+                    properties: {
+                      email: { type: 'string', format: 'email' },
+                      active: { type: 'boolean' },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    }
+    const body = extractRequestBodyFromDiscovery(doc as Record<string, unknown>, {
+      method: 'POST',
+      path: '/api/test',
+    })
+    expect(JSON.parse(body!)).toEqual({ email: 'test@example.com', active: true })
+  })
+
+  test('returns undefined when no requestBody', () => {
+    const doc = { paths: { '/api/test': { post: {} } } }
+    const body = extractRequestBodyFromDiscovery(doc as Record<string, unknown>, {
+      method: 'POST',
+      path: '/api/test',
+    })
+    expect(body).toBeUndefined()
+  })
+
+  test('returns undefined when path not found', () => {
+    const doc = { paths: { '/other': { get: {} } } }
+    const body = extractRequestBodyFromDiscovery(doc as Record<string, unknown>, {
+      method: 'POST',
+      path: '/api/test',
+    })
+    expect(body).toBeUndefined()
+  })
+
+  test('handles enum in schema', () => {
+    const doc = {
+      paths: {
+        '/api/test': {
+          post: {
+            requestBody: {
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    required: ['model'],
+                    properties: {
+                      model: { type: 'string', enum: ['gpt-4', 'gpt-3.5'] },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    }
+    const body = extractRequestBodyFromDiscovery(doc as Record<string, unknown>, {
+      method: 'POST',
+      path: '/api/test',
+    })
+    expect(JSON.parse(body!)).toEqual({ model: 'gpt-4' })
+  })
+})

package/src/cli/validate/discovery.ts

@@ -1,10 +1,11 @@
-import type { EndpointSpec } from './helpers.js'
+import type { EndpointSpec, PathParameter } from './helpers.js'
 import { fetchWithTimeout, HTTP_METHODS } from './helpers.js'
 
 export async function fetchDiscoveryDoc(
   baseUrl: string,
 ): Promise<{ doc: unknown; raw: string } | { error: string }> {
-  const url = new URL('/openapi.json', baseUrl).href
+  // Trailing slash makes URL treat baseUrl as a directory, so relative resolution appends rather than replaces the last segment.
+  const url = new URL('openapi.json', baseUrl.replace(/\/?$/, '/')).href
   try {
     const response = await fetchWithTimeout(url, {})
     if (!response.ok) return { error: `HTTP ${response.status}` }
@@ -28,21 +29,29 @@ export function extractEndpointsFromDiscovery(doc: Record<string, unknown>): End
   const paths = doc.paths as Record<string, Record<string, unknown>> | undefined
   if (!paths) return []
   for (const [pathKey, pathItem] of Object.entries(paths)) {
+    const pathLevelParams = extractPathParameters(pathItem.parameters)
+
     for (const [method, operation] of Object.entries(pathItem)) {
       if (!HTTP_METHODS.has(method)) continue
       if (!operation || typeof operation !== 'object' || Array.isArray(operation)) continue
       const op = operation as Record<string, unknown>
+
+      const opParams = extractPathParameters(op.parameters)
+      const merged = mergeParameters(pathLevelParams, opParams)
+      const params = merged.length > 0 ? merged : undefined
+
       if (op['x-payment-info']) {
         const payInfo = op['x-payment-info'] as Record<string, unknown>
         withPaymentInfo.push({
           method: method.toUpperCase(),
           path: pathKey,
           amount: payInfo.amount as string | undefined,
+          parameters: params,
         })
       } else {
         const responses = op.responses as Record<string, unknown> | undefined
         if (responses && '402' in responses) {
-          with402Response.push({ method: method.toUpperCase(), path: pathKey })
+          with402Response.push({ method: method.toUpperCase(), path: pathKey, parameters: params })
         }
       }
     }
@@ -50,8 +59,96 @@ export function extractEndpointsFromDiscovery(doc: Record<string, unknown>): End
   return withPaymentInfo.length > 0 ? withPaymentInfo : with402Response
 }
 
-// Recursively generates a minimal valid value from a JSON Schema definition.
-// Fills only required fields, preferring const > example > default > synthetic.
+export function extractRequestBodyFromDiscovery(
+  doc: Record<string, unknown>,
+  endpoint: EndpointSpec,
+): string | undefined {
+  const paths = doc.paths as Record<string, Record<string, unknown>> | undefined
+  if (!paths) return undefined
+  const pathItem = paths[endpoint.path]
+  if (!pathItem) return undefined
+  const op = pathItem[endpoint.method.toLowerCase()] as Record<string, unknown> | undefined
+  if (!op?.requestBody) return undefined
+
+  const rb = op.requestBody as Record<string, unknown>
+  const content = rb.content as Record<string, unknown> | undefined
+  const jsonContent = content?.['application/json'] as Record<string, unknown> | undefined
+  if (!jsonContent) return undefined
+
+  if (jsonContent.example) return JSON.stringify(jsonContent.example)
+
+  const schema = jsonContent.schema as Record<string, unknown> | undefined
+  if (!schema || schema.type !== 'object') return undefined
+
+  const result = generateValueFromSchema(schema)
+  if (result && typeof result === 'object' && Object.keys(result as object).length > 0) {
+    return JSON.stringify(result)
+  }
+  return undefined
+}
+
+export function buildUrl(baseUrl: string, endpoint: EndpointSpec, query?: string[]): string {
+  let path = endpoint.path
+  if (endpoint.parameters) {
+    path = substitutePathParams(path, endpoint.parameters)
+  }
+  // Strip leading slash so URL resolves relative to baseUrl's path, not root.
+  const relativePath = path.startsWith('/') ? path.slice(1) : path
+  let url = new URL(relativePath, baseUrl.replace(/\/?$/, '/')).href
+  if (query) {
+    const u = new URL(url)
+    for (const q of query) {
+      const [key, ...rest] = q.split('=')
+      if (key) u.searchParams.set(key, rest.join('='))
+    }
+    url = u.href
+  }
+  return url
+}
+
+// ── Internal helpers ─────────────────────────────────────────────────────────
+
+function extractPathParameters(raw: unknown): PathParameter[] {
+  if (!Array.isArray(raw)) return []
+  const results: PathParameter[] = []
+  for (const p of raw) {
+    if (!p || typeof p !== 'object') continue
+    const param = p as Record<string, unknown>
+    if (param.in !== 'path' || typeof param.name !== 'string') continue
+    results.push(
+      param.schema && typeof param.schema === 'object'
+        ? {
+            name: param.name,
+            in: 'path' as const,
+            schema: param.schema as NonNullable<PathParameter['schema']>,
+            example: param.example,
+          }
+        : { name: param.name, in: 'path' as const, example: param.example },
+    )
+  }
+  return results
+}
+
+function mergeParameters(base: PathParameter[], override: PathParameter[]): PathParameter[] {
+  const merged = [...base]
+  for (const p of override) {
+    const idx = merged.findIndex((m) => m.name === p.name)
+    if (idx >= 0) merged[idx] = p
+    else merged.push(p)
+  }
+  return merged
+}
+
+function substitutePathParams(path: string, params: PathParameter[]): string {
+  return path.replace(/\{([^}]+)\}/g, (match, name) => {
+    const param = params.find((p) => p.name === name && p.in === 'path')
+    if (!param) return match
+    const value = param.example ?? param.schema?.example ?? param.schema?.default
+    if (value === undefined) return match
+    return encodeURIComponent(String(value))
+  })
+}
+
 function generateValueFromSchema(schema: Record<string, unknown>): unknown {
   if (schema.const !== undefined) return schema.const
   if (schema.example !== undefined) return schema.example
@@ -59,15 +156,15 @@ function generateValueFromSchema(schema: Record<string, unknown>): unknown {
 
   switch (schema.type) {
     case 'string': {
+      if (schema.enum && Array.isArray(schema.enum)) return schema.enum[0]
       if (schema.format === 'email') return 'test@example.com'
       if (schema.format === 'uuid') return '00000000-0000-0000-0000-000000000000'
       if (schema.format === 'uri' || schema.format === 'url') return 'https://example.com'
-      if (schema.enum && Array.isArray(schema.enum)) return schema.enum[0]
       return 'test'
     }
     case 'number':
     case 'integer':
-      return schema.minimum ?? 1
+      return (schema.minimum as number) ?? 1
     case 'boolean':
       return true
     case 'array':
@@ -87,34 +184,3 @@ function generateValueFromSchema(schema: Record<string, unknown>): unknown {
       return null
   }
 }
-
-// Looks up the requestBody schema for an endpoint in the OpenAPI doc and
-// returns a JSON string suitable for the request. Uses the doc's example
-// if one exists, otherwise generates a minimal body from the schema.
-export function extractRequestBodyFromDiscovery(
-  doc: Record<string, unknown>,
-  endpoint: EndpointSpec,
-): string | undefined {
-  const paths = doc.paths as Record<string, Record<string, unknown>> | undefined
-  if (!paths) return undefined
-  const pathItem = paths[endpoint.path]
-  if (!pathItem) return undefined
-  const op = pathItem[endpoint.method.toLowerCase()] as Record<string, unknown> | undefined
-  if (!op?.requestBody) return undefined
-
-  const rb = op.requestBody as Record<string, unknown>
-  const content = rb.content as Record<string, unknown> | undefined
-  const jsonContent = content?.['application/json'] as Record<string, unknown> | undefined
-  if (!jsonContent) return undefined
-
-  if (jsonContent.example) return JSON.stringify(jsonContent.example)
-
-  const schema = jsonContent.schema as Record<string, unknown> | undefined
-  if (!schema || schema.type !== 'object') return undefined
-
-  const result = generateValueFromSchema(schema)
-  if (result && typeof result === 'object' && Object.keys(result as object).length > 0) {
-    return JSON.stringify(result)
-  }
-  return undefined
-}

package/src/cli/validate/helpers.ts

@@ -11,6 +11,21 @@ export type EndpointSpec = {
   method: string
   path: string
   amount?: string | undefined
+  parameters?: PathParameter[] | undefined
+}
+
+export type PathParameter = {
+  name: string
+  in: 'path' | 'query' | 'header' | 'cookie'
+  schema?: {
+    type?: string
+    format?: string
+    pattern?: string
+    enum?: unknown[]
+    example?: unknown
+    default?: unknown
+  }
+  example?: unknown
 }
 
 export function check(label: string, detail?: string): CheckResult {
@@ -83,19 +98,6 @@ export async function fetchWithTimeout(
   }
 }
 
-export function buildUrl(baseUrl: string, endpoint: EndpointSpec, query?: string[]): string {
-  let url = new URL(endpoint.path, baseUrl).href
-  if (query) {
-    const u = new URL(url)
-    for (const q of query) {
-      const [key, ...rest] = q.split('=')
-      if (key) u.searchParams.set(key, rest.join('='))
-    }
-    url = u.href
-  }
-  return url
-}
-
 export function formatBytes(bytes: number): string {
   if (bytes < 1024) return `${bytes}B`
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`