capman 0.4.2 → 0.4.3

package/bin/capman.js

@@ -1,737 +1,24 @@
 #!/usr/bin/env node
 'use strict'
 
-const path = require('path')
-const fs   = require('fs')
+const { command, header, log, c } = require('./lib/shared')
 
-const args    = process.argv.slice(2)
-const command = args[0]
-const flags   = args.slice(1)
-
-const getFlag = (name) => {
-  const i = flags.indexOf(name)
-  return i !== -1 ? flags[i + 1] : undefined
-}
-
-const c = {
-  reset:  '\x1b[0m',
-  bold:   '\x1b[1m',
-  teal:   '\x1b[36m',
-  yellow: '\x1b[33m',
-  red:    '\x1b[31m',
-  green:  '\x1b[32m',
-  gray:   '\x1b[90m',
-}
-
-const log = {
-  info:    (...a) => console.log(`${c.teal}i${c.reset}`, ...a),
-  success: (...a) => console.log(`${c.green}✓${c.reset}`, ...a),
-  warn:    (...a) => console.log(`${c.yellow}⚠${c.reset}`, ...a),
-  error:   (...a) => console.error(`${c.red}✗${c.reset}`, ...a),
-  blank:   ()     => console.log(),
-}
-
-function header() {
-  const pkg = require(path.join(__dirname, '..', 'package.json'))
-  console.log()
-  console.log(`${c.bold}${c.teal}  capman${c.reset} ${c.gray}v${pkg.version} — Capability Manifest Engine${c.reset}`)
-  console.log(`${c.gray}  ─────────────────────────────────────────${c.reset}`)
-  console.log()
-}
-
-function requireSrc() {
-  const distPath = path.join(__dirname, '..', 'dist', 'cjs', 'index.js')
-  if (fs.existsSync(distPath)) return require(distPath)
-
-  // dist not built — try to build automatically
-  log.info('dist/cjs not found — running build...')
-  try {
-    require('child_process').execSync('npm run build', {
-      cwd: path.join(__dirname, '..'),
-      stdio: 'inherit'
-    })
-    if (fs.existsSync(distPath)) return require(distPath)
-  } catch {
-    // build failed
-  }
-
-  log.error('Cannot find dist/cjs/. Run: pnpm run build')
-  process.exit(1)
-}
-
-function cmdHelp() {
-  header()
-  console.log(`${c.bold}  Usage:${c.reset}  node bin/capman.js <command>`)
-  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 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`)
-  console.log(`    ${c.teal}run${c.reset}       Run a query against your manifest`)
-  console.log()
-  console.log(`${c.bold}  Options:${c.reset}`)
-  console.log(`    ${c.gray}--config    Path to config file  (default: capman.config.js)${c.reset}`)
-  console.log(`    ${c.gray}--out       Output path          (default: manifest.json)${c.reset}`)
-  console.log(`    ${c.gray}--manifest  Manifest to read     (default: manifest.json)${c.reset}`)
-  console.log(`    ${c.gray}Options: --debug (show all candidates)${c.reset}`)
-  console.log()
-}
-
-function cmdInit() {
-  header()
-  const outPath = path.resolve(process.cwd(), 'capman.config.js')
-  if (fs.existsSync(outPath)) {
-    log.warn('capman.config.js already exists — not overwriting.')
-    process.exit(0)
-  }
-  const { generateStarterConfig } = requireSrc()
-  fs.writeFileSync(outPath, generateStarterConfig())
-  log.success(`Created ${c.bold}capman.config.js${c.reset}`)
-  log.info(`Edit it with your app's capabilities, then run:`)
-  console.log(`\n    node bin/capman.js generate\n`)
-}
-
-async function cmdGenerate() {
-  header()
-  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 { 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 {
-    config = loadConfig(configPath)
-  } catch (e) {
-    log.error(e.message)
-    process.exit(1)
-  }
-
-  const outManifestPath = getFlag('--out') ?? 'manifest.json'
-  log.info(`Generating manifest for ${config.app}...`)
-
-  let manifest
-  try {
-    manifest = generate(config)
-  } catch (e) {
-    log.error(`Generation failed: ${e.message}`)
-    process.exit(1)
-  }
-
-  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))
-  }
-
-  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()
-
-  const manifestPath = getFlag('--manifest') ?? 'manifest.json'
-  let manifest
-  try {
-    manifest = readManifest(manifestPath)
-  } catch (e) {
-    log.error(e.message)
-    process.exit(1)
-  }
-
-  log.info(`Validating ${c.bold}${manifestPath}${c.reset}...`)
-  const result = validate(manifest)
-  log.blank()
-
-  for (const w of result.warnings) log.warn(w)
-  for (const e of result.errors)   log.error(e)
-
-  if (result.valid) {
-    log.success(`${manifest.capabilities.length} capabilities — all valid`)
-  } else {
-    log.error(`${result.errors.length} error(s) found.`)
-    process.exit(1)
-  }
-  console.log()
-}
-
-function cmdInspect() {
-  header()
-  const { readManifest } = requireSrc()
-
-  const manifestPath = getFlag('--manifest') ?? 'manifest.json'
-  let manifest
-  try {
-    manifest = readManifest(manifestPath)
-  } catch (e) {
-    log.error(e.message)
-    process.exit(1)
-  }
-
-  console.log(`${c.bold}  App:${c.reset}          ${manifest.app}`)
-  console.log(`${c.bold}  Generated:${c.reset}    ${manifest.generatedAt}`)
-  console.log(`${c.bold}  Capabilities:${c.reset} ${manifest.capabilities.length}`)
-  console.log()
-
-  for (const cap of manifest.capabilities) {
-    const col = cap.resolver.type === 'api' ? c.teal : cap.resolver.type === 'nav' ? c.teal : c.yellow
-    console.log(`  ${c.bold}${cap.name}${c.reset}  ${col}[${cap.resolver.type}]${c.reset}  ${c.gray}${cap.privacy.level}${c.reset}`)
-    console.log(`  ${c.gray}id: ${cap.id}${c.reset}`)
-    console.log(`  ${cap.description}`)
-    if (cap.examples?.length) {
-      console.log(`  ${c.gray}e.g. "${cap.examples[0]}"${c.reset}`)
-    }
-    console.log()
-  }
-}
-
-function cmdDemo() {
-  header()
-  const { generate, match } = requireSrc()
-
-  // ── Title ──────────────────────────────────────────────────────────────────
-  console.log(`${c.bold}  Turn natural language into reliable, explainable backend actions.${c.reset}`)
-  console.log(`${c.gray}  ─────────────────────────────────────────${c.reset}\n`)
-
-  // ── Manifest ───────────────────────────────────────────────────────────────
-  const config = {
-    app: 'demo-store',
-    baseUrl: 'https://api.demo-store.com',
-    capabilities: [
-      {
-        id: 'check_product_availability',
-        name: 'Check product availability',
-        description: 'Check stock and pricing for a product by name or ID.',
-        examples: [
-          'Is the blue jacket in stock?',
-          'Check stock for blue jacket',
-          'Check availability for blue jacket',
-          'Product availability for jacket',
-        ],
-        params: [
-          { name: 'product', description: 'Product name or ID', required: true, source: 'user_query' }
-        ],
-        returns: ['stock', 'price', 'variants'],
-        resolver: { type: 'api', endpoints: [{ method: 'GET', path: '/products/{product}/availability' }] },
-        privacy: { level: 'public' },
-      },
-      {
-        id: 'get_order_status',
-        name: 'Get order status',
-        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 purchase?',
-        ],
-        params: [
-          { name: 'order_id', description: 'Order ID', required: true, source: 'user_query' }
-        ],
-        returns: ['status', 'tracking', 'estimated_delivery'],
-        resolver: { type: 'api', endpoints: [{ method: 'GET', path: '/orders/{order_id}' }] },
-        privacy: { level: 'user_owned' },
-      },
-      {
-        id: 'navigate_to_screen',
-        name: 'Navigate to screen',
-        description: 'Route the user to a specific page in the store.',
-        examples: [
-          'Take me to cart',
-          'Open cart',
-          'Go to checkout',
-          'Navigate to account',
-        ],
-        params: [
-          { name: 'destination', description: 'Target screen', required: true, source: 'user_query' }
-        ],
-        returns: ['deep_link'],
-        resolver: { type: 'nav', destination: '/{destination}' },
-        privacy: { level: 'public' },
-      },
-    ],
-  }
-
-  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 = [
-    { 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 },
-  ]
-
-  let passed = 0
-  let outOfScope = 0
-
-  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
-    }
-
-    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}`
-    }
-
-    // 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()
-  }
-
-  // ── 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() {
-  header()
-  const query = args[1]
-  const debug = flags.includes('--debug')
-  const manifestPath = getFlag('--manifest') ?? 'manifest.json'
-
-  if (!query) {
-    log.error('Please provide a query. Example: node bin/capman.js run "show me articles"')
-    process.exit(1)
-  }
-
-  const { readManifest, match } = requireSrc()
-
-  let manifest
-  try {
-    manifest = readManifest(manifestPath)
-  } catch (e) {
-    log.error(e.message)
-    process.exit(1)
-  }
-
-  log.info(`Query: "${query}"`)
-  log.blank()
-
-  const result = match(query, manifest)
-
-  if (result.capability) {
-    console.log(`  ${c.green}✓${c.reset}  Matched: ${c.bold}${result.capability.id}${c.reset}`)
-    console.log(`     Intent:     ${result.intent}`)
-    console.log(`     Confidence: ${result.confidence}%`)
-    console.log(`     Resolver:   ${result.capability.resolver.type}`)
-
-    if (Object.keys(result.extractedParams).length > 0) {
-      const params = Object.entries(result.extractedParams)
-        .map(([k, v]) => `${k}=${v}`)
-        .join(', ')
-      console.log(`     Params:     ${params}`)
-    }
-
-    if (debug && result.candidates?.length) {
-      log.blank()
-      console.log(`  ${c.gray}── All candidates:${c.reset}`)
-      result.candidates
-        .sort((a, b) => b.score - a.score)
-        .forEach(c2 => {
-          const marker = c2.matched ? c.green + '✓' : c.gray + '○'
-          console.log(`     ${marker}${c.reset}  ${c2.capabilityId}: ${c2.score}%`)
-        })
-    }
-  } else {
-    console.log(`  ${c.yellow}○${c.reset}  OUT_OF_SCOPE — no capability matched`)
-    console.log(`     ${c.gray}${result.reasoning}${c.reset}`)
-
-    if (debug && result.candidates?.length) {
-      log.blank()
-      console.log(`  ${c.gray}── All candidates:${c.reset}`)
-      result.candidates
-        .sort((a, b) => b.score - a.score)
-        .slice(0, 5)
-        .forEach(c2 => {
-          console.log(`     ${c.gray}○  ${c2.capabilityId}: ${c2.score}%${c.reset}`)
-        })
-    }
-  }
-  console.log()
-}
-
-(async () => {
+;(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 'init':     require('./lib/cmd-init')();          break
+    case 'generate': await require('./lib/cmd-generate')(); break
+    case 'validate': require('./lib/cmd-validate')();       break
+    case 'inspect':  require('./lib/cmd-inspect')();        break
+    case 'demo':     require('./lib/cmd-demo')();           break
+    case 'run':      require('./lib/cmd-run')();            break
+    case 'explain':  await require('./lib/cmd-explain')();  break
     case undefined:
     case '--help':
-    case '-h':       cmdHelp();          break
+    case '-h':       require('./lib/cmd-help')();           break
     default:
       header()
       log.error(`Unknown command: ${command}`)
-      console.log(`  Run: node bin/capman.js --help\n`)
+      console.log(`  Run: ${c.teal}capman --help${c.reset}\n`)
       process.exit(1)
   }
 })()
-