cli-jaw 0.1.0

package/skills_ref/whatsapp/scripts/openapi-explore.mjs

@@ -0,0 +1,1273 @@
+#!/usr/bin/env node
+
+import { readFileSync, readdirSync, statSync } from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { parse as parseYaml } from 'yaml'
+
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head']
+const DEFAULT_PUBLISHED_WHATSAPP_OPENAPI = 'https://docs.kapso.ai/api/meta/whatsapp/openapi-whatsapp.yaml'
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url))
+
+function printHelp(exitCode = 0) {
+  const msg = `
+Explore OpenAPI specs (YAML)
+
+Usage:
+  node openapi-explore.mjs [openapi.yaml ...] <command> [args]
+  node openapi-explore.mjs [--file <path> ...] <command> [args]
+  node openapi-explore.mjs --all <command> [args]
+
+Default (no files passed):
+  Loads the published OpenAPI files from docs.kapso.ai:
+  - ${DEFAULT_PUBLISHED_WHATSAPP_OPENAPI}
+  - (plus platform + workflows, deduced from that URL)
+
+Fallback:
+  If it can't fetch the published specs (offline, etc.), it falls back to local repo files:
+  api/**/openapi-*.yaml
+
+Use --all to force local auto-discovery.
+
+Commands:
+  specs
+  tags [--spec <id>]
+  ops [--spec <id>] [--tag <tag>] [--q <query>]
+  search <query> [--spec <id>]
+  op <operationId | specId:operationId | "METHOD /path"> [--spec <id>]
+  schema <SchemaName | specId:SchemaName> [--spec <id>]
+  where <SchemaName | specId:SchemaName> [--spec <id>]
+
+Flags:
+  --file, -f <path>     Load a spec file (repeatable)
+  --all                 Load all api/**/openapi-*.yaml files
+  --spec <id>           Filter by spec id (platform, workflows, whatsapp, ...)
+  --json                Output JSON (search/ops/where)
+  --limit <n>           Limit results (default 30)
+`
+  console.log(msg.trim())
+  process.exit(exitCode)
+}
+
+function die(msg, exitCode = 1) {
+  console.error(msg)
+  process.exit(exitCode)
+}
+
+function parseArgs(argv) {
+  const args = [...argv]
+  const opts = { files: [], all: false, spec: null, json: false, limit: 30, tag: null, q: null }
+  let command = null
+  const rest = []
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--help' || a === '-h') printHelp(0)
+
+    if (a === '--all') {
+      opts.all = true
+      continue
+    }
+    if (a === '--json') {
+      opts.json = true
+      continue
+    }
+    if (a === '--file' || a === '-f') {
+      const p = args[++i]
+      if (!p) die('Missing value for --file')
+      opts.files.push(p)
+      continue
+    }
+    if (a === '--spec') {
+      opts.spec = args[++i] || null
+      if (!opts.spec) die('Missing value for --spec')
+      continue
+    }
+    if (a === '--limit') {
+      const raw = args[++i]
+      const n = Number(raw)
+      if (!Number.isFinite(n) || n <= 0) die(`Invalid --limit: ${raw}`)
+      opts.limit = n
+      continue
+    }
+    if (a === '--tag') {
+      opts.tag = args[++i] || null
+      if (!opts.tag) die('Missing value for --tag')
+      continue
+    }
+    if (a === '--q') {
+      opts.q = args[++i] || null
+      if (!opts.q) die('Missing value for --q')
+      continue
+    }
+
+    if (!command && (a.endsWith('.yaml') || a.endsWith('.yml'))) {
+      opts.files.push(a)
+      continue
+    }
+
+    if (!command) command = a
+    else rest.push(a)
+  }
+
+  return { opts, command, rest }
+}
+
+function walk(dir, { filePattern, maxDepth = 10 } = {}, depth = 0, out = []) {
+  if (depth > maxDepth) return out
+  let entries
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return out
+  }
+
+  for (const entry of entries) {
+    const full = path.join(dir, entry)
+    let st
+    try {
+      st = statSync(full)
+    } catch {
+      continue
+    }
+
+    if (st.isDirectory()) {
+      walk(full, { filePattern, maxDepth }, depth + 1, out)
+    } else if (!filePattern || filePattern.test(entry)) {
+      out.push(full)
+    }
+  }
+
+  return out
+}
+
+function findUpDir(startDir, targetDirName, { maxDepth = 12 } = {}) {
+  let current = path.resolve(startDir)
+  for (let i = 0; i <= maxDepth; i++) {
+    const candidate = path.join(current, targetDirName)
+    try {
+      const st = statSync(candidate)
+      if (st.isDirectory()) return candidate
+    } catch {
+      // ignore
+    }
+
+    const parent = path.dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return null
+}
+
+function findLocalApiDir() {
+  return findUpDir(process.cwd(), 'api') || findUpDir(SCRIPT_DIR, 'api')
+}
+
+function isUrl(s) {
+  return /^https?:\/\//i.test(String(s))
+}
+
+function deducePublishedOpenApiUrls(whatsappUrl = DEFAULT_PUBLISHED_WHATSAPP_OPENAPI) {
+  const u = new URL(whatsappUrl)
+  const origin = u.origin
+  return [
+    whatsappUrl,
+    new URL('/api/platform/v1/openapi-platform.yaml', origin).toString(),
+    new URL('/api/platform/v1/openapi-workflows.yaml', origin).toString(),
+  ]
+}
+
+function inferSpecId(filePath, spec) {
+  const base = (isUrl(filePath) ? path.basename(new URL(filePath).pathname) : path.basename(filePath)).toLowerCase()
+  if (base.includes('whatsapp')) return 'whatsapp'
+  if (base.includes('workflows')) return 'workflows'
+  if (base.includes('platform')) return 'platform'
+
+  const title = (spec?.info?.title || '').toLowerCase()
+  if (title.includes('whatsapp')) return 'whatsapp'
+  if (title.includes('workflow')) return 'workflows'
+  if (title.includes('platform')) return 'platform'
+
+  return base.replace(/^openapi-/, '').replace(/\.(ya?ml)$/, '') || 'spec'
+}
+
+function decodeJsonPointerToken(token) {
+  return token.replaceAll('~1', '/').replaceAll('~0', '~')
+}
+
+function getByJsonPointer(doc, pointer) {
+  if (!pointer || !pointer.startsWith('#/')) return null
+  const parts = pointer.slice(2).split('/').map(decodeJsonPointerToken)
+  let cur = doc
+  for (const part of parts) {
+    if (cur == null) return null
+    cur = cur[part]
+  }
+  return cur ?? null
+}
+
+function refName(ref) {
+  if (!ref) return null
+  const parts = String(ref).split('/')
+  return parts[parts.length - 1] || null
+}
+
+function derefObject(obj, doc, stack = new Set()) {
+  if (!obj?.$ref) return obj
+  const ref = String(obj.$ref)
+  if (stack.has(ref)) return obj
+  stack.add(ref)
+  const resolved = getByJsonPointer(doc, ref)
+  if (!resolved) return obj
+  return derefObject(resolved, doc, stack)
+}
+
+function schemaTypeString(schema) {
+  if (!schema) return 'any'
+  if (schema.$ref) return refName(schema.$ref) || 'ref'
+  if (schema.const !== undefined) return `const ${JSON.stringify(schema.const)}`
+  if (schema.enum?.length) {
+    const vals = schema.enum.slice(0, 6).map((v) => JSON.stringify(v)).join(' | ')
+    return schema.enum.length > 6 ? `enum(${vals} | ...)` : `enum(${vals})`
+  }
+  if (schema.type) {
+    if (Array.isArray(schema.type)) return schema.type.join('|')
+    return schema.type
+  }
+  if (schema.oneOf) return 'oneOf'
+  if (schema.anyOf) return 'anyOf'
+  if (schema.allOf) return 'allOf'
+  if (schema.properties) return 'object'
+  if (schema.items) return 'array'
+  return 'any'
+}
+
+function normalizeType(schema) {
+  if (!schema) return null
+  const t = schema.type
+  if (!t) return null
+  if (Array.isArray(t)) {
+    const nonNull = t.find((x) => x !== 'null')
+    return nonNull || t[0] || null
+  }
+  return t
+}
+
+function mergeAllOf(schema, doc, seen = new Set()) {
+  if (!schema?.allOf?.length) return schema
+
+  const out = { ...schema }
+  delete out.allOf
+
+  let merged = { type: 'object', properties: {}, required: [] }
+
+  for (const part of schema.allOf) {
+    let s = part
+    if (s?.$ref) {
+      const name = refName(s.$ref)
+      if (name) {
+        if (seen.has(name)) continue
+        seen.add(name)
+      }
+      s = getByJsonPointer(doc, s.$ref) || s
+    }
+    if (s?.allOf) s = mergeAllOf(s, doc, seen)
+
+    if (s?.type && normalizeType(s) !== 'object' && s.properties) {
+      // some specs omit type: object but still have properties
+    } else if (normalizeType(s) && normalizeType(s) !== 'object' && !s.properties) {
+      return schema
+    }
+
+    if (s?.properties) Object.assign(merged.properties, s.properties)
+    if (Array.isArray(s?.required)) merged.required.push(...s.required)
+    if (s?.description && !merged.description) merged.description = s.description
+  }
+
+  merged.required = [...new Set(merged.required)]
+  return { ...merged, ...out }
+}
+
+function formatSchemaPreview(schema, doc, { depth = 2, maxProps = 12 } = {}, indent = '', refStack = new Set()) {
+  if (!schema) return [`${indent}any`]
+
+  if (schema.$ref) {
+    const name = refName(schema.$ref) || schema.$ref
+    const resolved = getByJsonPointer(doc, schema.$ref)
+    const lines = [`${indent}${name}`]
+    const refKey = String(schema.$ref)
+    if (refStack.has(refKey)) return lines
+    refStack.add(refKey)
+    if (resolved && depth > 0) {
+      const next = resolved?.allOf ? mergeAllOf(resolved, doc) : resolved
+      const childLines = formatSchemaPreview(next, doc, { depth, maxProps }, indent + '  ', refStack)
+      // Avoid printing a single redundant "object" line for refs
+      if (!(childLines.length === 1 && childLines[0].trim() === 'object')) lines.push(...childLines)
+    }
+    refStack.delete(refKey)
+    return lines
+  }
+
+  const normalized = schema.allOf ? mergeAllOf(schema, doc) : schema
+
+  const t = normalizeType(normalized) || schemaTypeString(normalized)
+  if (t === 'object' || normalized.properties) {
+    const props = normalized.properties || {}
+    const required = new Set(normalized.required || [])
+    const keys = Object.keys(props)
+    if (!keys.length) return [`${indent}object`]
+
+    const lines = []
+    for (const key of keys.slice(0, maxProps)) {
+      const s = props[key]
+      const typeStr = schemaTypeString(s)
+      const req = required.has(key) ? ' (required)' : ''
+      const desc = s?.description ? ` - ${String(s.description).replaceAll('\n', ' ').slice(0, 80)}` : ''
+      lines.push(`${indent}- ${key}: ${typeStr}${req}${desc}`)
+      if (depth > 0) {
+        const child = s?.$ref ? getByJsonPointer(doc, s.$ref) : s
+        const childNorm = child?.allOf ? mergeAllOf(child, doc) : child
+        const childType = normalizeType(childNorm)
+        if (childType === 'object' || childNorm?.properties || childNorm?.items) {
+          const nested = formatSchemaPreview(childNorm, doc, { depth: depth - 1, maxProps }, indent + '  ', refStack)
+          // Only include nested if it adds something beyond "object"/"array"
+          if (!(nested.length === 1 && ['object', 'array'].includes(nested[0].trim()))) lines.push(...nested)
+        }
+      }
+    }
+    if (keys.length > maxProps) lines.push(`${indent}- ... (${keys.length - maxProps} more)`)
+    return lines
+  }
+
+  if (t === 'array' || normalized.items) {
+    const itemType = schemaTypeString(normalized.items)
+    const lines = [`${indent}array<${itemType}>`]
+    if (normalized.items && depth > 0) {
+      const next = normalized.items?.$ref ? getByJsonPointer(doc, normalized.items.$ref) : normalized.items
+      const nextNorm = next?.allOf ? mergeAllOf(next, doc) : next
+      const nested = formatSchemaPreview(nextNorm, doc, { depth: depth - 1, maxProps }, indent + '  ', refStack)
+      const nestedTrim = nested.length === 1 ? nested[0].trim() : null
+      const redundant =
+        nestedTrim === null ? false : ['object', 'array'].includes(nestedTrim) || nestedTrim === itemType
+      if (!redundant) lines.push(...nested)
+    }
+    return lines
+  }
+
+  if (normalized.oneOf?.length) {
+    const opts = normalized.oneOf.slice(0, 5).map((s) => schemaTypeString(s)).join(' | ')
+    return [`${indent}oneOf(${opts}${normalized.oneOf.length > 5 ? ' | ...' : ''})`]
+  }
+  if (normalized.anyOf?.length) {
+    const opts = normalized.anyOf.slice(0, 5).map((s) => schemaTypeString(s)).join(' | ')
+    return [`${indent}anyOf(${opts}${normalized.anyOf.length > 5 ? ' | ...' : ''})`]
+  }
+
+  return [`${indent}${schemaTypeString(normalized)}`]
+}
+
+function placeholderForString(schema) {
+  if (schema?.enum?.length) return schema.enum[0]
+  if (schema?.const !== undefined) return schema.const
+  if (schema?.format === 'uuid') return '00000000-0000-0000-0000-000000000000'
+  if (schema?.format === 'date-time') return '2025-01-01T00:00:00Z'
+  if (schema?.format === 'date') return '2025-01-01'
+  if (schema?.format === 'email') return 'user@example.com'
+  if (schema?.format === 'uri' || schema?.format === 'url') return 'https://example.com'
+  return 'string'
+}
+
+function exampleFromSchema(schema, doc, { depth = 3, includeOptional = false } = {}, stack = new Set()) {
+  if (!schema) return null
+
+  if (schema.$ref) {
+    const name = refName(schema.$ref)
+    if (name) {
+      if (stack.has(name)) return `<circular:${name}>`
+      stack.add(name)
+    }
+    const resolved = getByJsonPointer(doc, schema.$ref)
+    const out = exampleFromSchema(resolved || {}, doc, { depth, includeOptional }, stack)
+    if (name) stack.delete(name)
+    return out
+  }
+
+  const normalized = schema.allOf ? mergeAllOf(schema, doc) : schema
+
+  if (normalized.const !== undefined) return normalized.const
+  if (normalized.enum?.length) return normalized.enum[0]
+
+  const t = normalizeType(normalized)
+  if (t === 'string') return placeholderForString(normalized)
+  if (t === 'integer') return 0
+  if (t === 'number') return 0
+  if (t === 'boolean') return true
+  if (t === 'null') return null
+
+  if ((t === 'array' || normalized.items) && depth > 0) {
+    return [exampleFromSchema(normalized.items || {}, doc, { depth: depth - 1, includeOptional }, stack)]
+  }
+
+  if ((t === 'object' || normalized.properties || normalized.additionalProperties) && depth > 0) {
+    const props = normalized.properties || {}
+    const required = new Set(normalized.required || [])
+    const out = {}
+
+    const keys = Object.keys(props)
+    for (const key of keys) {
+      if (!includeOptional && !required.has(key)) continue
+      out[key] = exampleFromSchema(props[key], doc, { depth: depth - 1, includeOptional }, stack)
+    }
+
+    // If it is a free-form map, add a placeholder entry.
+    if (!keys.length && normalized.additionalProperties) {
+      out.key = exampleFromSchema(
+        normalized.additionalProperties === true ? {} : normalized.additionalProperties,
+        doc,
+        { depth: depth - 1, includeOptional },
+        stack,
+      )
+    }
+
+    return out
+  }
+
+  if (normalized.oneOf?.length) return exampleFromSchema(normalized.oneOf[0], doc, { depth, includeOptional }, stack)
+  if (normalized.anyOf?.length) return exampleFromSchema(normalized.anyOf[0], doc, { depth, includeOptional }, stack)
+
+  return null
+}
+
+function collectSchemaRefs(schema, doc, out = new Set(), stack = new Set()) {
+  if (!schema) return out
+
+  if (schema.$ref) {
+    const name = refName(schema.$ref)
+    if (name) out.add(name)
+    if (name) {
+      if (stack.has(name)) return out
+      stack.add(name)
+    }
+    const resolved = getByJsonPointer(doc, schema.$ref)
+    if (resolved) collectSchemaRefs(resolved, doc, out, stack)
+    if (name) stack.delete(name)
+    return out
+  }
+
+  const normalized = schema.allOf ? mergeAllOf(schema, doc) : schema
+
+  for (const key of ['oneOf', 'anyOf', 'allOf']) {
+    if (Array.isArray(normalized[key])) {
+      for (const s of normalized[key]) collectSchemaRefs(s, doc, out, stack)
+    }
+  }
+
+  if (normalized.properties) {
+    for (const s of Object.values(normalized.properties)) collectSchemaRefs(s, doc, out, stack)
+  }
+  if (normalized.items) collectSchemaRefs(normalized.items, doc, out, stack)
+  if (normalized.additionalProperties && normalized.additionalProperties !== true) {
+    collectSchemaRefs(normalized.additionalProperties, doc, out, stack)
+  }
+
+  return out
+}
+
+function collectSchemaFieldNames(schema, doc, out = new Set(), stack = new Set(), depth = 3) {
+  if (!schema || depth < 0) return out
+
+  if (schema.$ref) {
+    const ref = String(schema.$ref)
+    if (stack.has(ref)) return out
+    stack.add(ref)
+    const resolved = getByJsonPointer(doc, ref)
+    if (resolved) collectSchemaFieldNames(resolved, doc, out, stack, depth)
+    stack.delete(ref)
+    return out
+  }
+
+  const normalized = schema.allOf ? mergeAllOf(schema, doc) : schema
+
+  for (const key of ['oneOf', 'anyOf', 'allOf']) {
+    if (Array.isArray(normalized[key])) {
+      for (const s of normalized[key]) collectSchemaFieldNames(s, doc, out, stack, depth)
+    }
+  }
+
+  if (normalized.properties) {
+    for (const [k, s] of Object.entries(normalized.properties)) {
+      out.add(k)
+      collectSchemaFieldNames(s, doc, out, stack, depth - 1)
+    }
+  }
+
+  if (normalized.items) collectSchemaFieldNames(normalized.items, doc, out, stack, depth - 1)
+  if (normalized.additionalProperties && normalized.additionalProperties !== true) {
+    collectSchemaFieldNames(normalized.additionalProperties, doc, out, stack, depth - 1)
+  }
+
+  return out
+}
+
+function normalizeOperationSecurity(op, spec) {
+  if (Object.prototype.hasOwnProperty.call(op, 'security')) return op.security
+  return spec.security
+}
+
+function securityLabel(opSecurity, spec) {
+  if (!opSecurity) return null
+  if (Array.isArray(opSecurity) && opSecurity.length === 0) return 'none'
+
+  const schemes = spec?.components?.securitySchemes || {}
+
+  function schemeLabel(name) {
+    const s = schemes[name]
+    if (!s) return name
+    if (s.type === 'apiKey' && s.in === 'header' && s.name) return `${name} (${s.name} header)`
+    if (s.type === 'apiKey' && s.in) return `${name} (apiKey in ${s.in})`
+    if (s.type === 'http' && s.scheme === 'bearer') return `${name} (Authorization: Bearer ...)`
+    if (s.type === 'http') return `${name} (http ${s.scheme || ''})`.trim()
+    return `${name} (${s.type})`
+  }
+
+  const requirementSets = []
+  for (const req of opSecurity || []) {
+    const keys = Object.keys(req || {})
+    if (!keys.length) continue
+    requirementSets.push(keys.map(schemeLabel).join(' + '))
+  }
+
+  if (!requirementSets.length) return null
+  return requirementSets.join(' OR ')
+}
+
+function toShortSpec(s) {
+  return {
+    id: s.id,
+    title: s.title,
+    version: s.version,
+    file: s.filePath,
+    servers: s.servers,
+    operations: s.operations.length,
+    schemas: Object.keys(s.schemas).length,
+  }
+}
+
+async function readSpecSource(source) {
+  if (isUrl(source)) {
+    const res = await fetch(source, {
+      // Some CDNs / WAFs behave better with a UA.
+      headers: { 'User-Agent': 'kapso-openapi-explore/1.0 (+https://docs.kapso.ai)' },
+    })
+    if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`)
+    return await res.text()
+  }
+  return readFileSync(source, 'utf-8')
+}
+
+async function loadSpecsAsync({ sources, sourceMode, specFilter }) {
+  if (!sources.length) die('No OpenAPI sources provided')
+
+  const seenIds = new Map()
+  const specs = []
+  const errors = []
+
+  for (const filePath of sources) {
+    let raw = null
+    try {
+      raw = await readSpecSource(filePath)
+    } catch (e) {
+      errors.push({ source: filePath, error: e })
+      if (sourceMode === 'explicit') console.error(`Skipping ${filePath}: ${e.message}`)
+      continue
+    }
+
+    let doc
+    try {
+      doc = parseYaml(raw)
+    } catch (e) {
+      errors.push({ source: filePath, error: e })
+      console.error(`Skipping ${filePath}: YAML parse error: ${e.message}`)
+      continue
+    }
+
+    const idBase = inferSpecId(filePath, doc)
+    const n = (seenIds.get(idBase) || 0) + 1
+    seenIds.set(idBase, n)
+    const id = n === 1 ? idBase : `${idBase}${n}`
+
+    if (specFilter && id !== specFilter) continue
+
+    const title = doc?.info?.title || id
+    const version = doc?.info?.version || '?'
+    const servers = (doc?.servers || []).map((s) => s?.url).filter(Boolean)
+    const tags = doc?.tags || []
+    const schemas = doc?.components?.schemas || {}
+    const schemaFieldCache = new Map()
+
+    const getSchemaFields = (schemaName) => {
+      if (schemaFieldCache.has(schemaName)) return schemaFieldCache.get(schemaName)
+      const schema = schemas?.[schemaName]
+      const fields = schema ? [...collectSchemaFieldNames(schema, doc)] : []
+      schemaFieldCache.set(schemaName, fields)
+      return fields
+    }
+
+    const operations = []
+    const paths = doc?.paths || {}
+    for (const [p, pathItemRaw] of Object.entries(paths)) {
+      const pathItem = pathItemRaw || {}
+      const pathParams = Array.isArray(pathItem.parameters) ? pathItem.parameters.map((x) => derefObject(x, doc)) : []
+
+      for (const method of HTTP_METHODS) {
+        const op = pathItem[method]
+        if (!op) continue
+
+        const mergedParams = [...pathParams, ...((op.parameters || []).filter(Boolean))]
+          .map((x) => derefObject(x, doc))
+          .filter(Boolean)
+        const opSecurity = normalizeOperationSecurity(op, doc)
+        const opRequestBody = derefObject(op.requestBody || null, doc)
+
+        const refs = new Set()
+        // params
+        for (const param of mergedParams) {
+          if (param?.schema) collectSchemaRefs(param.schema, doc, refs)
+          if (param?.content) {
+            for (const media of Object.values(param.content)) {
+              if (media?.schema) collectSchemaRefs(media.schema, doc, refs)
+            }
+          }
+        }
+        // body
+        if (opRequestBody?.content) {
+          for (const media of Object.values(opRequestBody.content)) {
+            if (media?.schema) collectSchemaRefs(media.schema, doc, refs)
+          }
+        }
+        // responses
+        if (op?.responses) {
+          for (const resp of Object.values(op.responses)) {
+            const r = derefObject(resp, doc)
+            if (r?.content) {
+              for (const media of Object.values(r.content)) {
+                if (media?.schema) collectSchemaRefs(media.schema, doc, refs)
+              }
+            }
+          }
+        }
+
+        const fieldsUsed = new Set()
+        for (const schemaName of refs) {
+          for (const f of getSchemaFields(schemaName)) fieldsUsed.add(f)
+        }
+
+        operations.push({
+          specId: id,
+          specTitle: title,
+          specFile: filePath,
+          method,
+          path: p,
+          operationId: op.operationId || null,
+          summary: op.summary || null,
+          description: op.description || null,
+          tags: op.tags || [],
+          deprecated: Boolean(op.deprecated),
+          security: opSecurity,
+          securityLabel: securityLabel(opSecurity, doc),
+          parameters: mergedParams,
+          requestBody: opRequestBody,
+          responses: op.responses || {},
+          refsUsed: refs,
+          fieldsUsed,
+        })
+      }
+    }
+
+    specs.push({
+      id,
+      filePath,
+      title,
+      version,
+      servers,
+      doc,
+      tags,
+      schemas,
+      operations,
+    })
+  }
+
+  if (!specs.length) {
+    if (sourceMode === 'default_remote' && errors.length) {
+      const apiDir = findLocalApiDir()
+      const local = apiDir ? walk(apiDir, { filePattern: /^openapi-.*\.ya?ml$/ }) : []
+      if (local.length) {
+        console.error(`Could not fetch published OpenAPI specs. Falling back to local repo specs (api/**/openapi-*.yaml).`)
+        return await loadSpecsAsync({ sources: local, sourceMode: 'explicit', specFilter })
+      }
+    }
+    if (specFilter) die(`No specs matched --spec ${specFilter}`)
+    die('No specs loaded')
+  }
+
+  if (sourceMode === 'default_remote' && errors.length) {
+    console.error(`Some published OpenAPI specs could not be fetched:`)
+    for (const e of errors) console.error(`- ${e.source}: ${e.error?.message || String(e.error)}`)
+  }
+
+  return specs
+}
+
+function findOperation(specs, query, { specHint } = {}) {
+  const raw = query.trim()
+  const direct = raw.includes(':') ? raw.split(':') : null
+  const qSpec = direct?.[0] || specHint
+  const qId = direct?.[1] || raw
+
+  // METHOD /path
+  const m = raw.match(/^(get|post|put|patch|delete|options|head)\\s+(.+)$/i)
+  if (m) {
+    const method = m[1].toLowerCase()
+    const p = m[2].trim()
+    const matches = []
+    for (const s of specs) {
+      if (qSpec && s.id !== qSpec) continue
+      for (const op of s.operations) {
+        if (op.method === method && op.path === p) matches.push(op)
+      }
+    }
+    return matches
+  }
+
+  // operationId
+  const matches = []
+  for (const s of specs) {
+    if (qSpec && s.id !== qSpec) continue
+    for (const op of s.operations) {
+      if (op.operationId === qId) matches.push(op)
+    }
+  }
+  return matches
+}
+
+function findSchema(specs, query, { specHint } = {}) {
+  const raw = query.trim()
+  const direct = raw.includes(':') ? raw.split(':') : null
+  const qSpec = direct?.[0] || specHint
+  const qName = direct?.[1] || raw
+
+  const matches = []
+  for (const s of specs) {
+    if (qSpec && s.id !== qSpec) continue
+    if (Object.prototype.hasOwnProperty.call(s.schemas, qName)) {
+      matches.push({ spec: s, name: qName, schema: s.schemas[qName] })
+    }
+  }
+  return matches
+}
+
+function scoreText(hay, q) {
+  if (!hay) return 0
+  const h = hay.toLowerCase()
+  if (h === q) return 100
+  if (h.startsWith(q)) return 60
+  if (h.includes(q)) return 30
+  return 0
+}
+
+function search(specs, query, { specHint, limit = 30 } = {}) {
+  const q = query.toLowerCase().trim()
+  if (!q) return { ops: [], schemas: [] }
+
+  const ops = []
+  const schemas = []
+
+  for (const s of specs) {
+    if (specHint && s.id !== specHint) continue
+
+    for (const op of s.operations) {
+      let score = 0
+      score += scoreText(op.operationId, q) * 3
+      score += scoreText(`${op.method} ${op.path}`, q) * 2
+      score += scoreText(op.summary, q) * 2
+      score += scoreText(op.description, q)
+      for (const t of op.tags || []) score += scoreText(t, q) * 2
+      score += scoreText((op.parameters || []).map((p) => p?.name).filter(Boolean).join(' '), q) * 2
+      score += scoreText([...op.refsUsed].join(' '), q) * 2
+      score += scoreText([...op.fieldsUsed].join(' '), q)
+      if (score > 0) ops.push({ score, op })
+    }
+
+    for (const [name, schema] of Object.entries(s.schemas)) {
+      let score = 0
+      score += scoreText(name, q) * 3
+      score += scoreText(schema?.description, q)
+      score += scoreText([...collectSchemaFieldNames(schema, s.doc)].join(' '), q) * 2
+      if (score > 0) schemas.push({ score, spec: s, name, schema })
+    }
+  }
+
+  ops.sort((a, b) => b.score - a.score)
+  schemas.sort((a, b) => b.score - a.score)
+
+  return {
+    ops: ops.slice(0, limit).map((x) => x.op),
+    schemas: schemas.slice(0, limit).map((x) => ({ specId: x.spec.id, name: x.name })),
+  }
+}
+
+function printTable(rows, { sep = '  ' } = {}) {
+  if (!rows.length) return
+  const widths = []
+  for (const row of rows) {
+    row.forEach((cell, i) => {
+      widths[i] = Math.max(widths[i] || 0, String(cell).length)
+    })
+  }
+  for (const row of rows) {
+    const line = row
+      .map((cell, i) => String(cell).padEnd(widths[i], ' '))
+      .join(sep)
+      .trimEnd()
+    console.log(line)
+  }
+}
+
+function printSpecs(specs, { json } = {}) {
+  if (json) {
+    console.log(JSON.stringify(specs.map(toShortSpec), null, 2))
+    return
+  }
+
+  const rows = [['id', 'version', 'operations', 'schemas', 'file']]
+  for (const s of specs) rows.push([s.id, s.version, String(s.operations.length), String(Object.keys(s.schemas).length), s.filePath])
+  printTable(rows)
+}
+
+function printTags(specs, { specHint } = {}) {
+  const rows = [['spec', 'tag', 'description']]
+  for (const s of specs) {
+    if (specHint && s.id !== specHint) continue
+    for (const t of s.tags || []) rows.push([s.id, t.name, (t.description || '').replaceAll('\n', ' ').slice(0, 80)])
+  }
+  if (rows.length === 1) die('No tags found')
+  printTable(rows)
+}
+
+function printOps(specs, { specHint, tag, q, json, limit = 30 } = {}) {
+  let ops = []
+  for (const s of specs) {
+    if (specHint && s.id !== specHint) continue
+    ops.push(...s.operations)
+  }
+
+  if (tag) ops = ops.filter((o) => (o.tags || []).includes(tag))
+
+  if (q) {
+    const res = search(specs, q, { specHint, limit: Math.max(limit, 200) })
+    const opSet = new Set(res.ops.map((o) => `${o.specId}:${o.operationId || o.method + ' ' + o.path}`))
+    ops = ops.filter((o) => opSet.has(`${o.specId}:${o.operationId || o.method + ' ' + o.path}`))
+  }
+
+  ops = ops.slice(0, limit)
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        ops.map((o) => ({
+          spec: o.specId,
+          operationId: o.operationId,
+          method: o.method,
+          path: o.path,
+          summary: o.summary,
+        })),
+        null,
+        2,
+      ),
+    )
+    return
+  }
+
+  const rows = [['spec', 'operationId', 'method', 'path', 'summary']]
+  for (const o of ops) rows.push([o.specId, o.operationId || '-', o.method.toUpperCase(), o.path, (o.summary || '').slice(0, 80)])
+  printTable(rows)
+}
+
+function splitParams(params) {
+  const out = { path: [], query: [], header: [], cookie: [], other: [] }
+  for (const p of params || []) {
+    const loc = p?.in
+    if (loc === 'path') out.path.push(p)
+    else if (loc === 'query') out.query.push(p)
+    else if (loc === 'header') out.header.push(p)
+    else if (loc === 'cookie') out.cookie.push(p)
+    else out.other.push(p)
+  }
+  return out
+}
+
+function paramType(param) {
+  const s = param?.schema
+  if (s) return schemaTypeString(s)
+  if (param?.content) {
+    const media = Object.values(param.content)[0]
+    if (media?.schema) return schemaTypeString(media.schema)
+  }
+  return 'any'
+}
+
+function printParamsBlock(title, params) {
+  if (!params.length) return
+  console.log(`\n${title}`)
+  const rows = [['name', 'in', 'required', 'type', 'description']]
+  for (const p of params) {
+    rows.push([
+      p.name || '-',
+      p.in || '-',
+      p.required ? 'yes' : 'no',
+      paramType(p),
+      (p.description || '').replaceAll('\n', ' ').slice(0, 80),
+    ])
+  }
+  printTable(rows)
+}
+
+function printOperation(op, spec) {
+  const baseUrl = spec.servers?.[0] || ''
+  const full = baseUrl ? `${baseUrl}${op.path}` : op.path
+
+  const id = op.operationId ? `${op.specId}:${op.operationId}` : `${op.specId}:${op.method.toUpperCase()} ${op.path}`
+
+  console.log(id)
+  console.log(`${op.method.toUpperCase()} ${full}`)
+
+  if (op.summary) console.log(`\n${op.summary}`)
+  if (op.deprecated) console.log(`\nDeprecated: yes`)
+
+  const auth = op.securityLabel
+  if (auth) console.log(`\nAuth: ${auth}`)
+
+  if (op.tags?.length) console.log(`Tags: ${op.tags.join(', ')}`)
+
+  if (op.description) {
+    const desc = String(op.description).trim().replace(/\n{3,}/g, '\n\n')
+    const short = desc.length > 800 ? `${desc.slice(0, 800)}\n...` : desc
+    console.log(`\n${short}`)
+  }
+
+  const params = splitParams(op.parameters || [])
+  printParamsBlock('Path params', params.path)
+  printParamsBlock('Query params', params.query)
+  printParamsBlock('Header params', params.header)
+
+  if (op.requestBody?.content) {
+    console.log('\nBody')
+    const required = op.requestBody.required ? 'required' : 'optional'
+    console.log(`required: ${required}`)
+
+    const contentTypes = Object.keys(op.requestBody.content)
+    for (const ct of contentTypes) {
+      const schema = op.requestBody.content?.[ct]?.schema
+      if (!schema) continue
+      console.log(`\n${ct}`)
+      const lines = formatSchemaPreview(schema, spec.doc, { depth: 3, maxProps: 12 })
+      for (const l of lines) console.log(l)
+
+      if (ct === 'application/json') {
+        const ex = exampleFromSchema(schema, spec.doc, { depth: 3, includeOptional: false })
+        if (ex && typeof ex === 'object') {
+          console.log('\nexample (required fields)')
+          console.log(JSON.stringify(ex, null, 2))
+        }
+      }
+    }
+  }
+
+  if (op.responses && Object.keys(op.responses).length) {
+    console.log('\nResponses')
+    const codes = Object.keys(op.responses).sort((a, b) => {
+      const na = Number(a)
+      const nb = Number(b)
+      if (Number.isFinite(na) && Number.isFinite(nb)) return na - nb
+      if (a === 'default') return 1
+      if (b === 'default') return -1
+      return a.localeCompare(b)
+    })
+
+    for (const code of codes) {
+      const resp = derefObject(op.responses[code], spec.doc)
+      const desc = resp?.description ? ` - ${String(resp.description).replaceAll('\n', ' ').slice(0, 80)}` : ''
+      console.log(`\n${code}${desc}`)
+
+      const content = resp?.content || {}
+      for (const [ct, media] of Object.entries(content)) {
+        if (!media?.schema) continue
+        console.log(`${ct}`)
+        const lines = formatSchemaPreview(media.schema, spec.doc, { depth: 3, maxProps: 12 })
+        for (const l of lines) console.log(l)
+      }
+    }
+  }
+
+  console.log('\ncurl')
+  console.log(formatCurl(op, spec))
+}
+
+function replacePathParams(p) {
+  return p.replaceAll(/\{([^}]+)\}/g, '<$1>')
+}
+
+function formatCurl(op, spec) {
+  const baseUrl = spec.servers?.[0] || ''
+  let url = baseUrl ? `${baseUrl}${replacePathParams(op.path)}` : replacePathParams(op.path)
+
+  const requiredQuery = (op.parameters || [])
+    .filter((p) => p?.in === 'query' && p?.required && p?.name)
+    .map((p) => `${encodeURIComponent(p.name)}=<${p.name}>`)
+  if (requiredQuery.length) url += `?${requiredQuery.join('&')}`
+
+  const lines = []
+  lines.push(`curl -X ${op.method.toUpperCase()} '${url}' \\`)
+
+  // auth header if we can infer it
+  const schemes = spec?.doc?.components?.securitySchemes || {}
+  const sec = Array.isArray(op.security) ? op.security : null
+  const candidates = (sec || []).filter((x) => x && typeof x === 'object')
+  const preferred =
+    candidates.find((req) =>
+      Object.keys(req).some((name) => schemes[name]?.type === 'apiKey' && schemes[name]?.in === 'header'),
+    ) || candidates[0]
+
+  for (const name of Object.keys(preferred || {})) {
+    const s = schemes[name]
+    if (s?.type === 'apiKey' && s.in === 'header' && s.name) {
+      lines.push(`  -H '${s.name}: $KAPSO_API_KEY' \\`)
+    } else if (s?.type === 'http' && s.scheme === 'bearer') {
+      lines.push(`  -H 'Authorization: Bearer $ACCESS_TOKEN' \\`)
+    }
+  }
+
+  // content-type + body for JSON
+  const jsonSchema = op.requestBody?.content?.['application/json']?.schema
+  if (jsonSchema) {
+    const ex = exampleFromSchema(jsonSchema, spec.doc, { depth: 4, includeOptional: false })
+    lines.push(`  -H 'Content-Type: application/json' \\`)
+    lines.push(`  -d '${JSON.stringify(ex ?? {}, null, 0)}'`)
+    return lines.join('\n')
+  }
+
+  // trim trailing backslash
+  lines[lines.length - 1] = lines[lines.length - 1].replace(/ \\\\$/, '')
+  return lines.join('\n')
+}
+
+function printSchemaDetails(match, specs, { includeUsedBy = true } = {}) {
+  const { spec, name, schema } = match
+  console.log(`${spec.id}:${name}`)
+
+  const normalized = schema?.allOf ? mergeAllOf(schema, spec.doc) : schema
+  const typeStr = schemaTypeString(normalized)
+  console.log(typeStr)
+
+  if (normalized?.description) console.log(`\n${String(normalized.description).trim()}`)
+
+  const required = normalized?.required || []
+  if (required.length) console.log(`\nrequired: ${required.join(', ')}`)
+
+  if (normalized?.properties || normalized?.items) {
+    console.log('\nshape')
+    const lines = formatSchemaPreview(normalized, spec.doc, { depth: 3, maxProps: 25 })
+    for (const l of lines) console.log(l)
+  }
+
+  const ex = exampleFromSchema(normalized, spec.doc, { depth: 4, includeOptional: false })
+  if (ex && typeof ex === 'object') {
+    console.log('\nexample (required fields)')
+    console.log(JSON.stringify(ex, null, 2))
+  }
+
+  if (includeUsedBy) {
+    const usedBy = []
+    for (const s of specs) {
+      for (const op of s.operations) {
+        if (op.refsUsed?.has(name)) usedBy.push(op)
+      }
+    }
+
+    if (usedBy.length) {
+      console.log('\nused by')
+      const rows = [['spec', 'operationId', 'method', 'path']]
+      for (const op of usedBy.slice(0, 30)) rows.push([op.specId, op.operationId || '-', op.method.toUpperCase(), op.path])
+      printTable(rows)
+      if (usedBy.length > 30) console.log(`... (${usedBy.length - 30} more)`)
+    }
+  }
+}
+
+function printWhere(specs, schemaQuery, { specHint, json, limit = 30 } = {}) {
+  const matches = findSchema(specs, schemaQuery, { specHint })
+  if (!matches.length) die(`Schema not found: ${schemaQuery}`)
+  if (matches.length > 1 && !schemaQuery.includes(':')) {
+    die(`Schema exists in multiple specs. Use specId:SchemaName\n${matches.map((m) => `- ${m.spec.id}:${m.name}`).join('\n')}`)
+  }
+
+  const { name } = matches[0]
+  const usedBy = []
+  for (const s of specs) {
+    if (specHint && s.id !== specHint) continue
+    for (const op of s.operations) {
+      if (op.refsUsed?.has(name)) usedBy.push(op)
+    }
+  }
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        usedBy.slice(0, limit).map((o) => ({
+          spec: o.specId,
+          operationId: o.operationId,
+          method: o.method,
+          path: o.path,
+          summary: o.summary,
+        })),
+        null,
+        2,
+      ),
+    )
+    return
+  }
+
+  if (!usedBy.length) {
+    console.log('No operations reference this schema (via $ref).')
+    return
+  }
+
+  const rows = [['spec', 'operationId', 'method', 'path', 'summary']]
+  for (const o of usedBy.slice(0, limit)) rows.push([o.specId, o.operationId || '-', o.method.toUpperCase(), o.path, (o.summary || '').slice(0, 80)])
+  printTable(rows)
+  if (usedBy.length > limit) console.log(`... (${usedBy.length - limit} more)`)
+}
+
+async function main() {
+  const { opts, command, rest } = parseArgs(process.argv.slice(2))
+  if (!command) printHelp(1)
+
+  let sources = []
+  let sourceMode = 'explicit'
+
+  if (opts.files.length) {
+    sources = opts.files
+    sourceMode = 'explicit'
+  } else if (opts.all) {
+    const apiDir = findLocalApiDir()
+    sources = apiDir ? walk(apiDir, { filePattern: /^openapi-.*\.ya?ml$/ }) : []
+    sourceMode = 'explicit'
+  } else {
+    sources = deducePublishedOpenApiUrls(DEFAULT_PUBLISHED_WHATSAPP_OPENAPI)
+    sourceMode = 'default_remote'
+  }
+
+  const specs = await loadSpecsAsync({ sources, sourceMode, specFilter: opts.spec })
+
+  if (command === 'specs') return printSpecs(specs, { json: opts.json })
+  if (command === 'tags') return printTags(specs, { specHint: opts.spec })
+  if (command === 'ops') return printOps(specs, { specHint: opts.spec, tag: opts.tag, q: opts.q, json: opts.json, limit: opts.limit })
+  if (command === 'search') {
+    const q = rest.join(' ').trim()
+    if (!q) die('Usage: search <query>')
+    const res = search(specs, q, { specHint: opts.spec, limit: opts.limit })
+    if (opts.json) {
+      return console.log(
+        JSON.stringify(
+          {
+            ops: res.ops.map((o) => ({
+              spec: o.specId,
+              operationId: o.operationId,
+              method: o.method,
+              path: o.path,
+              summary: o.summary,
+            })),
+            schemas: res.schemas,
+          },
+          null,
+          2,
+        ),
+      )
+    }
+
+    if (!res.ops.length && !res.schemas.length) {
+      console.log('No matches.')
+      return
+    }
+
+    if (res.ops.length) {
+      console.log('ops')
+      const rows = [['spec', 'operationId', 'method', 'path', 'summary']]
+      for (const o of res.ops) rows.push([o.specId, o.operationId || '-', o.method.toUpperCase(), o.path, (o.summary || '').slice(0, 80)])
+      printTable(rows)
+    }
+    if (res.schemas.length) {
+      console.log('\nschemas')
+      const rows = [['spec', 'name']]
+      for (const s of res.schemas) rows.push([s.specId, s.name])
+      printTable(rows)
+    }
+    return
+  }
+  if (command === 'op') {
+    const q = rest.join(' ').trim()
+    if (!q) die('Usage: op <operationId | specId:operationId | "METHOD /path">')
+    const matches = findOperation(specs, q, { specHint: opts.spec })
+    if (!matches.length) {
+      const res = search(specs, q, { specHint: opts.spec, limit: 10 })
+      if (res.ops.length) {
+        console.log(`Operation not found: ${q}\n`)
+        console.log('closest ops')
+        const rows = [['spec', 'operationId', 'method', 'path', 'summary']]
+        for (const o of res.ops) rows.push([o.specId, o.operationId || '-', o.method.toUpperCase(), o.path, (o.summary || '').slice(0, 80)])
+        printTable(rows)
+        process.exit(1)
+      }
+      die(`Operation not found: ${q}`)
+    }
+    if (matches.length > 1 && !q.includes(':') && !q.match(/^(get|post|put|patch|delete|options|head)\\s+/i)) {
+      die(`OperationId exists in multiple specs. Use specId:operationId\n${matches.map((m) => `- ${m.specId}:${m.operationId}`).join('\n')}`)
+    }
+    const op = matches[0]
+    const spec = specs.find((s) => s.id === op.specId)
+    if (!spec) die(`Internal error: missing spec ${op.specId}`)
+    printOperation(op, spec)
+    return
+  }
+  if (command === 'schema') {
+    const q = rest.join(' ').trim()
+    if (!q) die('Usage: schema <SchemaName | specId:SchemaName>')
+    const matches = findSchema(specs, q, { specHint: opts.spec })
+    if (!matches.length) {
+      const res = search(specs, q, { specHint: opts.spec, limit: 10 })
+      if (res.schemas.length) {
+        console.log(`Schema not found: ${q}\n`)
+        console.log('closest schemas')
+        const rows = [['spec', 'name']]
+        for (const s of res.schemas) rows.push([s.specId, s.name])
+        printTable(rows)
+        process.exit(1)
+      }
+      die(`Schema not found: ${q}`)
+    }
+    if (matches.length > 1 && !q.includes(':')) {
+      die(`Schema exists in multiple specs. Use specId:SchemaName\n${matches.map((m) => `- ${m.spec.id}:${m.name}`).join('\n')}`)
+    }
+    printSchemaDetails(matches[0], specs, { includeUsedBy: true })
+    return
+  }
+  if (command === 'where') {
+    const q = rest.join(' ').trim()
+    if (!q) die('Usage: where <SchemaName | specId:SchemaName>')
+    return printWhere(specs, q, { specHint: opts.spec, json: opts.json, limit: opts.limit })
+  }
+
+  die(`Unknown command: ${command}`)
+}
+
+main().catch((e) => die(e?.stack || e?.message || String(e)))