capman 0.4.0 → 0.4.2

package/bin/capman.js

@@ -65,7 +65,9 @@ function cmdHelp() {
   console.log()
   console.log(`${c.bold}  Commands:${c.reset}`)
   console.log(`    ${c.teal}init${c.reset}      Create a starter capman.config.js`)
-  console.log(`    ${c.teal}generate${c.reset}  Generate manifest.json from config`)
+  console.log(`    ${c.teal}generate${c.reset}                   Generate manifest from capman.config.js`)
+  console.log(`    ${c.teal}generate --from <path|url>${c.reset}  Generate from OpenAPI/Swagger spec`)
+  console.log(`    ${c.teal}generate --ai${c.reset}              Generate manifest using AI (needs API key)`)
   console.log(`    ${c.teal}validate${c.reset}  Validate an existing manifest.json`)
   console.log(`    ${c.teal}inspect${c.reset}   Print all capabilities in manifest`)
   console.log(`    ${c.teal}demo${c.reset}      Run a live demo with sample queries`)
@@ -93,13 +95,153 @@ function cmdInit() {
   console.log(`\n    node bin/capman.js generate\n`)
 }
 
-function cmdGenerate() {
+async function cmdGenerate() {
   header()
-  const { loadConfig, generate, writeManifest, validate } = requireSrc()
+  const { generate, loadConfig, writeManifest, validate, generateStarterConfig, parseOpenAPI } = requireSrc()
+
+  const fromFlag  = getFlag('--from')
+  const aiFlag    = flags.includes('--ai')
+  const outPath   = getFlag('--out') ?? 'manifest.json'
+  const configOut = getFlag('--config-out') ?? 'capman.config.js'
+
+  // ── Path 1: OpenAPI parser ─────────────────────────────────────────────────
+  if (fromFlag) {
+    log.info(`Parsing OpenAPI spec: ${fromFlag}`)
+    let result
+    try {
+      result = await parseOpenAPI(fromFlag)
+    } catch (e) {
+      log.error(e.message)
+      process.exit(1)
+    }
 
-  const configPath = getFlag('--config')
-  const outPath    = getFlag('--out') ?? 'manifest.json'
+    const { config, stats } = result
+
+    log.success(`Parsed ${stats.total} capabilities from spec`)
+    if (stats.skipped > 0) {
+      log.info(`Skipped ${stats.skipped} operations (insufficient info)`)
+    }
+    if (stats.warnings.length) {
+      stats.warnings.forEach(w => log.warn(w))
+    }
+
+    // Write capman.config.js
+    const configContent = `// Auto-generated by capman from OpenAPI spec
+// Review and adjust before committing
+
+module.exports = ${JSON.stringify(config, null, 2)
+  .replace(/"([^"]+)":/g, '$1:')
+  .replace(/"/g, "'")
+}
+`
+    const fs = require('fs')
+    fs.writeFileSync(configOut, configContent)
+    log.success(`Config written to ${configOut}`)
+
+    // Also generate manifest.json
+    try {
+      const manifest = generate(config)
+      writeManifest(manifest, outPath)
+      log.success(`Manifest written to ${outPath}`)
+      log.info(`${manifest.capabilities.length} capabilities registered`)
+    } catch (e) {
+      log.warn(`Could not generate manifest: ${e.message}`)
+    }
+
+    console.log()
+    console.log(`  ${c.gray}Next steps:${c.reset}`)
+    console.log(`  1. Review ${c.teal}${configOut}${c.reset} — adjust descriptions and examples`)
+    console.log(`  2. Run ${c.teal}npx capman validate${c.reset} to check your manifest`)
+    console.log(`  3. Run ${c.teal}npx capman demo${c.reset} to see it in action`)
+    console.log()
+    return
+  }
 
+  // ── Path 2: LLM-assisted ───────────────────────────────────────────────────
+  if (aiFlag) {
+    log.info('LLM-assisted manifest generation')
+    console.log()
+
+    const readline = require('readline')
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+
+    const ask = (q) => new Promise(resolve => rl.question(q, resolve))
+
+    console.log(`  ${c.gray}Describe your app and its main capabilities.${c.reset}`)
+    console.log(`  ${c.gray}Example: "A CRM app. Users can create contacts, log calls,`)
+    console.log(`  view pipeline stages. Admins can manage teams and billing."${c.reset}\n`)
+
+    const description = await ask(`  ${c.teal}>${c.reset} `)
+    rl.close()
+
+    if (!description.trim()) {
+      log.error('No description provided.')
+      process.exit(1)
+    }
+
+    // Detect LLM provider from env
+    const apiKey = process.env.ANTHROPIC_API_KEY ?? process.env.OPENAI_API_KEY ?? process.env.OPENROUTER_API_KEY
+    const provider =
+      process.env.ANTHROPIC_API_KEY  ? 'anthropic' :
+      process.env.OPENAI_API_KEY     ? 'openai' :
+      process.env.OPENROUTER_API_KEY ? 'openrouter' : null
+
+    if (!apiKey || !provider) {
+      log.error('No LLM API key found.')
+      console.log(`  Set one of: ${c.teal}ANTHROPIC_API_KEY${c.reset}, ${c.teal}OPENAI_API_KEY${c.reset}, or ${c.teal}OPENROUTER_API_KEY${c.reset}`)
+      process.exit(1)
+    }
+
+    log.info(`Using ${provider} to generate manifest...`)
+
+    const prompt = buildAIPrompt(description)
+    let raw
+    try {
+      raw = await callLLM(provider, apiKey, prompt)
+    } catch (e) {
+      log.error(`LLM call failed: ${e.message}`)
+      process.exit(1)
+    }
+
+    // Parse response
+    let config
+    try {
+      const clean = raw.replace(/```json|```javascript|```js|```/g, '').trim()
+      const match = clean.match(/module\.exports\s*=\s*(\{[\s\S]+\})/)
+      const jsonStr = match ? match[1] : clean
+      config = JSON.parse(jsonStr)
+    } catch (e) {
+      log.error('Could not parse LLM response. Try again or use --from with an OpenAPI spec.')
+      console.log(`\n  Raw response:\n${raw.slice(0, 500)}`)
+      process.exit(1)
+    }
+
+    // Write config
+    const fs = require('fs')
+    const configContent = `// Auto-generated by capman AI\n// Review before committing\n\nmodule.exports = ${JSON.stringify(config, null, 2)}\n`
+    fs.writeFileSync(configOut, configContent)
+    log.success(`Config written to ${configOut}`)
+
+    // Generate manifest
+    try {
+      const manifest = generate(config)
+      writeManifest(manifest, outPath)
+      log.success(`Manifest written to ${outPath}`)
+      log.info(`${manifest.capabilities.length} capabilities generated`)
+    } catch (e) {
+      log.warn(`Manifest generation failed — review your config: ${e.message}`)
+    }
+
+    console.log()
+    console.log(`  ${c.gray}Review ${configOut} — the AI may have missed things.${c.reset}`)
+    console.log(`  ${c.teal}npx capman validate${c.reset}   ${c.gray}→ check for errors${c.reset}`)
+    console.log(`  ${c.teal}npx capman inspect${c.reset}    ${c.gray}→ see all capabilities${c.reset}`)
+    console.log()
+    return
+  }
+
+  // ── Path 3: Manual (existing behaviour) ───────────────────────────────────
+  const configPath = getFlag('--config')
   log.info('Loading config...')
   let config
   try {
@@ -109,25 +251,143 @@ function cmdGenerate() {
     process.exit(1)
   }
 
-  log.info(`Generating manifest for ${c.bold}${config.app}${c.reset}...`)
-  const manifest = generate(config)
-  const result   = validate(manifest)
+  const outManifestPath = getFlag('--out') ?? 'manifest.json'
+  log.info(`Generating manifest for ${config.app}...`)
 
-  for (const w of result.warnings) log.warn(w)
-  for (const e of result.errors)   log.error(e)
+  let manifest
+  try {
+    manifest = generate(config)
+  } catch (e) {
+    log.error(`Generation failed: ${e.message}`)
+    process.exit(1)
+  }
 
-  if (!result.valid) {
-    log.error('Manifest has errors — fix them before writing.')
+  const validation = validate(manifest)
+  if (!validation.valid) {
+    validation.errors.forEach(e => log.error(e))
     process.exit(1)
   }
+  if (validation.warnings.length) {
+    validation.warnings.forEach(w => log.warn(w))
+  }
 
-  const written = writeManifest(manifest, outPath)
-  log.blank()
-  log.success(`Manifest written to ${c.bold}${written}${c.reset}`)
+  writeManifest(manifest, outManifestPath)
+  log.success(`Manifest written to ${outManifestPath}`)
   log.info(`${manifest.capabilities.length} capabilities registered`)
   console.log()
 }
 
+// ─── AI prompt builder ─────────────────────────────────────────────────────────
+
+function buildAIPrompt(description) {
+  return `You are helping generate a capman capability manifest config.
+
+The user's app description:
+${JSON.stringify({ app_description: description })}
+
+Generate a valid capman config as a JSON object (not module.exports, just the raw JSON object).
+
+The config must follow this exact structure:
+{
+  "app": "app-name-in-kebab-case",
+  "baseUrl": "https://api.your-app.com",
+  "capabilities": [
+    {
+      "id": "snake_case_id",
+      "name": "Human readable name",
+      "description": "What this capability does (min 10 chars)",
+      "examples": ["Example query 1", "Example query 2", "Example query 3"],
+      "params": [
+        {
+          "name": "param_name",
+          "description": "What this param is",
+          "required": true,
+          "source": "user_query"
+        }
+      ],
+      "returns": ["resource_name"],
+      "resolver": {
+        "type": "api",
+        "endpoints": [{ "method": "GET", "path": "/resource/{param_name}" }]
+      },
+      "privacy": { "level": "public" }
+    }
+  ]
+}
+
+Rules:
+- privacy.level must be "public", "user_owned", or "admin"
+- resolver.type must be "api", "nav", or "hybrid"
+- method must be "GET", "POST", "PUT", "PATCH", or "DELETE"
+- source must be "user_query", "session", "context", or "static"
+- Generate 3-8 capabilities based on the description
+- Each capability needs at least 2 examples
+- Respond ONLY with the raw JSON object — no markdown, no explanation`
+}
+
+// ─── LLM caller ───────────────────────────────────────────────────────────────
+
+async function callLLM(provider, apiKey, prompt) {
+  if (provider === 'anthropic') {
+    const res = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+      },
+      body: JSON.stringify({
+        model: 'claude-sonnet-4-20250514',
+        max_tokens: 4000,
+        messages: [{ role: 'user', content: prompt }],
+      }),
+    })
+    const data = await res.json()
+    if (!res.ok) throw new Error(data.error?.message ?? res.statusText)
+    return data.content[0].text
+  }
+
+  if (provider === 'openai') {
+    const res = await fetch('https://api.openai.com/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        model: 'gpt-4o-mini',
+        max_tokens: 4000,
+        messages: [{ role: 'user', content: prompt }],
+      }),
+    })
+    const data = await res.json()
+    if (!res.ok) throw new Error(data.error?.message ?? res.statusText)
+    return data.choices[0].message.content
+  }
+
+  if (provider === 'openrouter') {
+    const res = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+        'HTTP-Referer': 'https://github.com/Hobbydefiningdoctory/capman',
+      },
+      body: JSON.stringify({
+        model: 'openai/gpt-oss-120b:free',
+        max_tokens: 4000,
+        messages: [{ role: 'user', content: prompt }],
+        provider: { order: ['open-inference'], allow_fallbacks: true },
+      }),
+    })
+    const data = await res.json()
+    if (!res.ok) throw new Error(data.error?.message ?? res.statusText)
+    return data.choices[0].message.content
+  }
+
+  throw new Error(`Unknown provider: ${provider}`)
+}
+
 function cmdValidate() {
   header()
   const { readManifest, validate } = requireSrc()
@@ -189,12 +449,13 @@ function cmdInspect() {
 
 function cmdDemo() {
   header()
-  const { generate, match, resolve } = requireSrc()
+  const { generate, match } = requireSrc()
 
-  console.log(`${c.bold}  Live demo — see capman in action${c.reset}`)
+  // ── Title ──────────────────────────────────────────────────────────────────
+  console.log(`${c.bold}  Turn natural language into reliable, explainable backend actions.${c.reset}`)
   console.log(`${c.gray}  ─────────────────────────────────────────${c.reset}\n`)
 
-  // Demo manifest — generic e-commerce app
+  // ── Manifest ───────────────────────────────────────────────────────────────
   const config = {
     app: 'demo-store',
     baseUrl: 'https://api.demo-store.com',
@@ -206,9 +467,8 @@ function cmdDemo() {
         examples: [
           'Is the blue jacket in stock?',
           'Check stock for blue jacket',
-          'Do you have size M available?',
+          'Check availability for blue jacket',
           'Product availability for jacket',
-          'Is jacket available?',
         ],
         params: [
           { name: 'product', description: 'Product name or ID', required: true, source: 'user_query' }
@@ -220,11 +480,11 @@ function cmdDemo() {
       {
         id: 'get_order_status',
         name: 'Get order status',
-        description: 'Retrieve the current status and tracking info for an order.',
+        description: 'Retrieve the current status and tracking info for an order by order ID.',
         examples: [
           'Where is my order?',
           'Track order 1234',
-          'What is the status of my recent purchase?',
+          'What is the status of my purchase?',
         ],
         params: [
           { name: 'order_id', description: 'Order ID', required: true, source: 'user_query' }
@@ -242,7 +502,6 @@ function cmdDemo() {
           'Open cart',
           'Go to checkout',
           'Navigate to account',
-          'Show homepage',
         ],
         params: [
           { name: 'destination', description: 'Target screen', required: true, source: 'user_query' }
@@ -256,71 +515,138 @@ function cmdDemo() {
 
   const manifest = generate(config)
 
+  console.log(`${c.gray}  app:${c.reset}          ${c.bold}${config.app}${c.reset}`)
+  console.log(`${c.gray}  capabilities:${c.reset} ${manifest.capabilities.length}`)
+  console.log(`${c.gray}  matcher:${c.reset}      keyword (no LLM, no API key needed)\n`)
+
+  // ── Queries ────────────────────────────────────────────────────────────────
   const queries = [
-    'Check availability for blue jacket',
-    'Track order 1234',
-    'Go to cart',
-    'Is the website down?',
+    { text: 'Check availability for blue jacket', expectMatch: true  },
+    { text: 'Track order 1234',                   expectMatch: true  },
+    { text: 'Go to cart',                         expectMatch: true  },
+    { text: 'Is the website down?',               expectMatch: false },
   ]
 
-  console.log(`${c.gray}  App: ${c.reset}${c.bold}${config.app}${c.reset}`)
-  console.log(`${c.gray}  Capabilities: ${c.reset}${manifest.capabilities.length}`)
-  console.log(`${c.gray}  Mode: keyword matcher (no LLM required)\n${c.reset}`)
-
   let passed = 0
   let outOfScope = 0
 
-  for (const query of queries) {
-    const start = Date.now()
-    const result = match(query, manifest)
-    const duration = Date.now() - start
-
-    if (result.capability) {
-      passed++
-      const resolverColor = result.capability.resolver.type === 'api' ? c.teal :
-                            result.capability.resolver.type === 'nav' ? c.teal : c.yellow
-
-      console.log(`  ${c.green}✓${c.reset}  ${c.bold}"${query}"${c.reset}`)
-      console.log(`     ${c.gray}→ matched:${c.reset}    ${resolverColor}${result.capability.id}${c.reset}`)
-      console.log(`     ${c.gray}→ intent:${c.reset}     ${result.intent}`)
-      console.log(`     ${c.gray}→ confidence:${c.reset} ${result.confidence}%`)
-
-      if (Object.keys(result.extractedParams).length > 0) {
-        const params = Object.entries(result.extractedParams)
-          .map(([k, v]) => `${k}=${v}`)
-          .join(', ')
-        console.log(`     ${c.gray}→ params:${c.reset}     ${params}`)
+  for (const q of queries) {
+    const t0     = Date.now()
+    const result = match(q.text, manifest)
+    const ms     = Date.now() - t0
+
+    console.log(`${c.gray}  ────────────────────────────────────────${c.reset}`)
+    console.log()
+
+    // ── 1. QUERY ──────────────────────────────────────────────────────────
+    console.log(`  ${c.bold}QUERY${c.reset}`)
+    console.log(`  "${c.bold}${q.text}${c.reset}"\n`)
+
+    if (!result.capability) {
+      outOfScope++
+
+      // ── MATCH (out of scope) ─────────────────────────────────────────
+      console.log(`  ${c.bold}MATCH${c.reset}`)
+      console.log(`  ${c.yellow}○  OUT_OF_SCOPE${c.reset} — no capability handles this query\n`)
+
+      // ── EXECUTION ────────────────────────────────────────────────────
+      console.log(`  ${c.bold}EXECUTION${c.reset}`)
+      console.log(`  ${c.gray}[1] keyword_match  no match  ${ms}ms${c.reset}\n`)
+
+      // ── RESULT ───────────────────────────────────────────────────────
+      console.log(`  ${c.bold}RESULT${c.reset}`)
+      console.log(`  ${c.yellow}No action taken — query is outside manifest scope${c.reset}\n`)
+
+      // ── EXPLANATION ──────────────────────────────────────────────────
+      console.log(`  ${c.bold}EXPLANATION${c.reset}`)
+      if (result.candidates.length) {
+        const best = result.candidates.sort((a, b) => b.score - a.score)[0]
+        console.log(`  ${c.gray}Closest capability was "${best.capabilityId}" (${best.score}%) —`)
+        console.log(`  below the 50% confidence threshold. Correctly rejected.${c.reset}`)
       }
+      console.log()
+      continue
+    }
 
-      // Show what API call would be made
-      if (result.capability.resolver.type === 'api') {
-        const endpoint = result.capability.resolver.endpoints[0]
-        let path = endpoint.path
-        for (const [k, v] of Object.entries(result.extractedParams)) {
-          if (v) path = path.replace(`{${k}}`, v)
-        }
-        console.log(`     ${c.gray}→ api call:${c.reset}   ${endpoint.method} ${config.baseUrl}${path}`)
-      } else if (result.capability.resolver.type === 'nav') {
-        let dest = result.capability.resolver.destination
-        for (const [k, v] of Object.entries(result.extractedParams)) {
-          if (v) dest = dest.replace(`{${k}}`, v)
-        }
-        console.log(`     ${c.gray}→ nav target:${c.reset}  ${dest}`)
+    passed++
+
+    // Build API call or nav target
+    let actionLine = ''
+    if (result.capability.resolver.type === 'api') {
+      const endpoint = result.capability.resolver.endpoints[0]
+      let path = endpoint.path
+      for (const [k, v] of Object.entries(result.extractedParams)) {
+        if (v) path = path.replace(`{${k}}`, String(v))
       }
+      actionLine = `${endpoint.method} ${config.baseUrl}${path}`
+    } else if (result.capability.resolver.type === 'nav') {
+      let dest = result.capability.resolver.destination
+      for (const [k, v] of Object.entries(result.extractedParams)) {
+        if (v) dest = dest.replace(`{${k}}`, String(v))
+      }
+      actionLine = `navigate → ${dest}`
+    }
 
-      console.log(`     ${c.gray}→ time:${c.reset}       ${duration}ms\n`)
-    } else {
-      outOfScope++
-      console.log(`  ${c.yellow}○${c.reset}  ${c.bold}"${query}"${c.reset}`)
-      console.log(`     ${c.gray}→ out of scope — no capability handles this\n${c.reset}`)
+    // Candidates
+    const sorted   = [...result.candidates].sort((a, b) => b.score - a.score)
+    const winner   = sorted[0]
+    const runners  = sorted.slice(1).filter(r => r.score > 0)
+
+    // Extracted params
+    const paramEntries = Object.entries(result.extractedParams).filter(([, v]) => v !== null)
+
+    // ── 2. MATCH ──────────────────────────────────────────────────────────
+    console.log(`  ${c.bold}MATCH${c.reset}`)
+    console.log(`  ${c.green}✓  ${result.capability.id}${c.reset}`)
+    console.log(`  ${c.gray}intent:     ${c.reset}${result.intent}`)
+    console.log(`  ${c.gray}confidence: ${c.reset}${c.bold}${result.confidence}%${c.reset}`)
+    console.log(`  ${c.gray}privacy:    ${c.reset}${result.capability.privacy.level}`)
+    if (paramEntries.length) {
+      const pStr = paramEntries.map(([k, v]) => `${k}=${v}`).join(', ')
+      console.log(`  ${c.gray}params:     ${c.reset}${pStr}`)
     }
+    console.log()
+
+    // ── 3. EXECUTION ──────────────────────────────────────────────────────
+    console.log(`  ${c.bold}EXECUTION${c.reset}`)
+    console.log(`  ${c.gray}[1] cache_check    miss    0ms${c.reset}`)
+    console.log(`  ${c.gray}[2]${c.reset} keyword_match  ${c.green}pass${c.reset}    ${ms}ms   confidence: ${result.confidence}%`)
+    console.log(`  ${c.gray}[3] privacy_check  pass    0ms   level: ${result.capability.privacy.level}${c.reset}`)
+    console.log(`  ${c.gray}[4] resolve        pass    ${ms}ms   via ${result.capability.resolver.type}${c.reset}`)
+    console.log()
+
+    // ── 4. RESULT ─────────────────────────────────────────────────────────
+    console.log(`  ${c.bold}RESULT${c.reset}`)
+    console.log(`  ${c.green}${actionLine}${c.reset}`)
+    console.log()
+
+    // ── 5. EXPLANATION ────────────────────────────────────────────────────
+    console.log(`  ${c.bold}EXPLANATION${c.reset}`)
+    console.log(`  ${c.gray}Why "${winner.capabilityId}"?${c.reset}`)
+    console.log(`  ${c.gray}  scored ${winner.score}% — highest match against examples and description${c.reset}`)
+    if (runners.length) {
+      const rStr = runners.map(r => `${r.capabilityId} (${r.score}%)`).join(', ')
+      console.log(`  ${c.gray}  rejected: ${rStr}${c.reset}`)
+    }
+    if (paramEntries.length) {
+      const pStr = paramEntries.map(([k, v]) => `${k}="${v}"`).join(', ')
+      console.log(`  ${c.gray}  extracted from query: ${pStr}${c.reset}`)
+    }
+    console.log()
   }
 
-  console.log(`${c.gray}  ─────────────────────────────────────────${c.reset}`)
-  console.log(`  ${c.green}${passed} matched${c.reset}  ${c.gray}·${c.reset}  ${c.yellow}${outOfScope} out of scope${c.reset}  ${c.gray}·${c.reset}  ${manifest.capabilities.length} capabilities\n`)
-  console.log(`  ${c.gray}Try it on your own app:${c.reset}`)
-  console.log(`  ${c.teal}npx capman init${c.reset}  ${c.gray}→ create your manifest${c.reset}`)
-  console.log(`  ${c.teal}npx capman generate${c.reset}  ${c.gray}→ generate manifest.json${c.reset}\n`)
+  // ── Summary ────────────────────────────────────────────────────────────────
+  console.log(`${c.gray}  ────────────────────────────────────────${c.reset}\n`)
+  console.log(`  ${c.green}${passed} matched${c.reset}  ${c.gray}·${c.reset}  ${c.yellow}${outOfScope} out of scope${c.reset}  ${c.gray}·${c.reset}  ${manifest.capabilities.length} capabilities  ${c.gray}·${c.reset}  no LLM required\n`)
+  console.log(`  ${c.bold}Every query above is fully traced.${c.reset}`)
+  console.log(`  ${c.gray}You saw what matched, why it matched, how it executed, what it called,`)
+  console.log(`  and which alternatives were considered and rejected.${c.reset}`)
+  console.log(`  ${c.gray}No black box. No guessing. Full control.\n${c.reset}`)
+  console.log(`  ${c.gray}Next steps:${c.reset}`)
+  console.log(`  ${c.teal}npx capman init${c.reset}                          ${c.gray}→ define your app's capabilities${c.reset}`)
+  console.log(`  ${c.teal}npx capman generate${c.reset}                      ${c.gray}→ generate manifest.json${c.reset}`)
+  console.log(`  ${c.teal}npx capman run "your query" --debug${c.reset}      ${c.gray}→ trace any query live${c.reset}`)
+  console.log(`  ${c.teal}npm install capman${c.reset}                       ${c.gray}→ use in your AI agent${c.reset}\n`)
 }
 
 function cmdRun() {
@@ -390,19 +716,22 @@ function cmdRun() {
   console.log()
 }
 
-switch (command) {
-  case 'init':     cmdInit();     break
-  case 'generate': cmdGenerate(); break
-  case 'validate': cmdValidate(); break
-  case 'inspect':  cmdInspect();  break
-  case 'demo':     cmdDemo();     break
-  case 'run':      cmdRun();      break
-  case undefined:
-  case '--help':
-  case '-h':       cmdHelp();     break
-  default:
-    header()
-    log.error(`Unknown command: ${command}`)
-    console.log(`  Run: node bin/capman.js --help\n`)
-    process.exit(1)
-}
+(async () => {
+  switch (command) {
+    case 'init':     cmdInit();          break
+    case 'generate': await cmdGenerate(); break
+    case 'validate': cmdValidate();      break
+    case 'inspect':  cmdInspect();       break
+    case 'demo':     cmdDemo();          break
+    case 'run':      cmdRun();           break
+    case undefined:
+    case '--help':
+    case '-h':       cmdHelp();          break
+    default:
+      header()
+      log.error(`Unknown command: ${command}`)
+      console.log(`  Run: node bin/capman.js --help\n`)
+      process.exit(1)
+  }
+})()
+    

package/dist/cjs/cache.d.ts

@@ -6,15 +6,23 @@ export interface CacheEntry {
     hits: number;
 }
 export interface CacheStore {
-    get(query: string): Promise<CacheEntry | null>;
-    set(query: string, result: MatchResult): Promise<void>;
+    get(key: string): Promise<CacheEntry | null>;
+    set(key: string, result: MatchResult): Promise<void>;
     clear(): Promise<void>;
     size(): Promise<number>;
 }
+export declare function normalizeQuery(query: string): string;
+/**
+ * Build a smarter cache key based on matched capability + extracted params.
+ * Two different queries that resolve to the same capability with the same params
+ * will share a cache entry — dramatically improving hit rate.
+ * Falls back to normalized query if no capability matched.
+ */
+export declare function buildCacheKey(query: string, capabilityId: string | null, extractedParams: Record<string, string | null>): string;
 export declare class MemoryCache implements CacheStore {
     private store;
-    get(query: string): Promise<CacheEntry | null>;
-    set(query: string, result: MatchResult): Promise<void>;
+    get(key: string): Promise<CacheEntry | null>;
+    set(key: string, result: MatchResult): Promise<void>;
     clear(): Promise<void>;
     size(): Promise<number>;
 }
@@ -25,8 +33,8 @@ export declare class FileCache implements CacheStore {
     constructor(filePath?: string);
     private load;
     private save;
-    get(query: string): Promise<CacheEntry | null>;
-    set(query: string, result: MatchResult): Promise<void>;
+    get(key: string): Promise<CacheEntry | null>;
+    set(key: string, result: MatchResult): Promise<void>;
     clear(): Promise<void>;
     size(): Promise<number>;
 }
@@ -34,8 +42,8 @@ export declare class ComboCache implements CacheStore {
     private memory;
     private file;
     constructor(filePath?: string);
-    get(query: string): Promise<CacheEntry | null>;
-    set(query: string, result: MatchResult): Promise<void>;
+    get(key: string): Promise<CacheEntry | null>;
+    set(key: string, result: MatchResult): Promise<void>;
     clear(): Promise<void>;
     size(): Promise<number>;
 }

package/dist/cjs/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAK1C,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,WAAW,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAID,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;IAC9C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CACxB;AAUD,qBAAa,WAAY,YAAW,UAAU;IAC5C,OAAO,CAAC,KAAK,CAAgC;IAEvC,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAW9C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAWtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAG9B;AAID,qBAAa,SAAU,YAAW,UAAU;IAC1C,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,MAAM,CAAQ;gBAEV,QAAQ,SAAuB;YAK7B,IAAI;YAYJ,IAAI;IAaZ,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAY9C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAatD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAI9B;AAID,qBAAa,UAAW,YAAW,UAAU;IAC3C,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,IAAI,CAAW;gBAEX,QAAQ,SAAuB;IAKrC,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAiB9C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAG9B"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAK1C,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,WAAW,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAID,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;IAC5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CACxB;AAID,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AAEH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAC7C,MAAM,CAQR;AAMD,qBAAa,WAAY,YAAW,UAAU;IAC5C,OAAO,CAAC,KAAK,CAAgC;IAEvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAU5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAepD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IACtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAC9B;AAID,qBAAa,SAAU,YAAW,UAAU;IAC1C,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,MAAM,CAAQ;gBAEV,QAAQ,SAAuB;YAK7B,IAAI;YAYJ,IAAI;IAaZ,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAW5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAYpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAI9B;AAID,qBAAa,UAAW,YAAW,UAAU;IAC3C,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,IAAI,CAAW;gBAEX,QAAQ,SAAuB;IAKrC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAY5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAG9B"}