capman 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+All notable changes to capman are documented here.
+
+---
+
+## [Unreleased] — v0.4.3
+### Added
+- `CapmanEngine.explain(query)` — explains what would match without executing
+  - Returns all candidates with per-candidate human-readable explanations
+  - Shows `wouldExecute.action` — what API call or nav would happen
+  - Shows `wouldExecute.blocked` — if privacy would prevent execution
+  - Fully respects rate limiting and circuit breaker (mirrors `ask()` logic)
+- `ExplainResult` and `ExplainCandidate` types exported from public API
+- `capman explain "query"` CLI command — shows full explanation in terminal
+- LLM rate limiting and circuit breaker in `CapmanEngine`
+  - `maxLLMCallsPerMinute` — hard rate limit (default: 60)
+  - `llmCooldownMs` — minimum ms between consecutive LLM calls (default: 0)
+  - `llmCircuitBreakerThreshold` — failures before circuit opens (default: 3)
+  - `llmCircuitBreakerResetMs` — ms before circuit resets (default: 60000)
+  - `balanced` and `accurate` modes both respect all limits
+  - `explain()` shares the same rate limit state as `ask()`
+
+### Fixed
+- `explain()` now mirrors `ask()` matching logic exactly — balanced mode escalates to LLM when confidence < threshold
+- `matchWithLLM` internal try-catch removed — errors propagate to engine for proper circuit breaker tracking
+- Removed `?? []` on required `candidates` field in trace building
+- Removed `?.` on `candidates` in CLI `--debug` block
+- Fixed mixed indentation in `ask()` switch statement
+
+---
+
+## [0.4.2] — 2026-02-01
+### Added
+- `parseOpenAPI(specPathOrUrl)` — parses OpenAPI 3.x and Swagger 2.x specs into capman configs
+  - Reads local files or fetches from URL
+  - Extracts path params, query params, and request body fields
+  - Infers privacy scope from security schemes — bearer → `user_owned`, admin tags → `admin`
+  - Generates natural language examples from operation summaries
+  - Supports JSON specs; YAML requires `js-yaml` installed
+- `capman generate --from <path|url>` — generate manifest from OpenAPI/Swagger spec
+- `capman generate --ai` — AI-assisted manifest generation from plain English description
+  - Detects `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY` automatically
+  - Validates generated config with Zod before writing
+- `ParseResult` type exported from public API
+- 9 new parser tests covering all extraction and inference paths
+
+### Fixed
+- `bin/capman.js` `generate` command wrapped in async IIFE for proper async support
+- OpenAPI duplicate capability IDs resolved automatically with method suffix
+
+---
+
+## [0.4.1] — 2026-03-28
+### Fixed
+- Prompt injection sanitization in `matchWithLLM` — query now passed as JSON field
+- `ask()` now delegates to `CapmanEngine` internally — eliminates logic duplication
+- `FileLearningStore` and `MemoryLearningStore` now cap at 10,000 entries with oldest-first pruning
+- Post-match cache key now uses `capabilityId + params` instead of raw query — higher hit rate
+- Removed duplicate `AskOptions` interface declaration in `index.ts`
+- Removed dead imports (`_match`, `_matchWithLLM`, `_resolve`) from `index.ts`
+---
+
+## [0.4.0] — 2026-03-xx
+### Added
+- `CapmanEngine` class — unified entry point with caching, learning, and tracing
+- `ExecutionTrace` — structured trace returned with every `engine.ask()` result
+- `MatchCandidate[]` — all scored candidates returned, not just the winner
+- `capman run "query" --debug` CLI command — shows all candidate scores
+- `capman demo` CLI command — live demo with zero config
+- Configurable retries and timeout on API resolver
+- `MemoryCache`, `FileCache`, `ComboCache` — pluggable cache backends
+- `FileLearningStore`, `MemoryLearningStore` — usage analytics and keyword index
+- `MatchMode` — `cheap | balanced | accurate` matching modes
+
+### Fixed
+- Optional params no longer get garbage fallback values
+- `candidates` field made required (was optional `?`)
+- Empty query and LLM paths now correctly set `candidates: []`
+- `generate()` now deep-copies capabilities — prevents config mutation
+- `MemoryCache` now has 512-entry cap with oldest-first eviction
+- `fetchWithRetry` converted from recursive to iterative — no stack overflow risk
+
+---
+
+## [0.3.0] — 2026-03-xx
+### Added
+- `CapmanEngine` initial design with cache and learning stores
+- `FileLearningStore` — persists query history and keyword index
+- `ComboCache` — memory-first with file fallback
+- `scripts/version.js` — prebuild script keeps `src/version.ts` in sync
+- Dual ESM/CJS build verification in CI
+
+### Fixed
+- Default stores changed to memory-only — no silent filesystem writes
+- `FileCache` and `FileLearningStore` converted to async `fs.promises`
+- Shared `computeStats()` helper — eliminates code duplication
+
+---
+
+## [0.2.0] — 2026-03-xx
+### Added
+- Dual CJS + ESM build (`dist/cjs/` and `dist/esm/`)
+- `MatchMode` — `cheap | balanced | accurate`
+- `AuthContext` — privacy enforcement per capability
+- `ApiCallResult` with `status` and `data` fields
+- Configurable `retries` and `timeoutMs` on resolver
+- `setLogLevel()` exported from public API
+
+### Fixed
+- POST/PUT/DELETE requests no longer silently dropped
+- `extractParams` now extracts real values from queries
+- Stopword filtering in scorer
+- Zod runtime validation on config and manifest load
+- `files` field in `package.json` — clean npm publish
+
+---
+
+## [0.1.0] — 2026-03-xx
+### Added
+- Initial release
+- CLI: `init`, `generate`, `validate`, `inspect`
+- SDK: `match()`, `matchWithLLM()`, `resolve()`, `ask()`
+- Two-tier matching: keyword-first, LLM fallback
+- Privacy scopes: `public`, `user_owned`, `admin`
+- Zod schema validation
+- GitHub Actions CI

package/CODEBASE.md

@@ -0,0 +1,391 @@
+# Codebase Map
+
+A guide to every file in capman — what it does, what it exports, and how it connects to everything else.
+
+---
+
+## Overview
+
+```
+capman/
+├── src/              ← TypeScript source — compiled to dist/
+├── dist/
+│   ├── cjs/          ← CommonJS build (Node require)
+│   └── esm/          ← ES Module build (bundlers, import)
+├── bin/              ← CLI entry point and command modules
+│   └── lib/          ← one file per CLI command
+├── tests/            ← Vitest test suites
+├── scripts/          ← build-time utilities
+└── test/             ← live integration tests (not in CI)
+```
+
+---
+
+## src/
+
+### `src/types.ts`
+All TypeScript types and interfaces. No logic — pure declarations.
+
+Key exports:
+- `Capability`, `CapabilityParam`, `Manifest`, `CapmanConfig` — core data shapes
+- `MatchResult` — what `match()` returns, including `candidates: MatchCandidate[]`
+- `MatchCandidate` — `{ capabilityId, score, matched }` — all scored candidates
+- `ResolveResult`, `ApiCallResult` — what `resolve()` returns, with `status` and `data`
+- `ExecutionTrace`, `TraceStep` — full step-by-step trace returned by `engine.ask()`
+- `ExplainResult`, `ExplainCandidate` — what `engine.explain()` returns
+- `ValidationResult` — `{ valid, errors, warnings }`
+- `Resolver`, `ApiResolver`, `NavResolver`, `HybridResolver` — discriminated union
+- `PrivacyScope`, `ResolverType`, `HttpMethod` — enums/literals
+
+---
+
+### `src/schema.ts`
+Zod runtime validation schemas. Mirrors `types.ts` but adds validation rules.
+
+Key exports:
+- `validateConfig(config)` — validates a `CapmanConfig` at load time
+- `validateManifest(manifest)` — validates a `Manifest` at read time
+
+Notable rules:
+- `id` must match `/^[a-z][a-z0-9_]*$/` — snake_case only
+- `description` minimum 10 characters
+- Capability IDs must be unique within a manifest
+
+---
+
+### `src/generator.ts`
+Manifest lifecycle — create, read, write, validate.
+
+Key exports:
+- `generate(config)` → `Manifest` — converts config to manifest, deep-copies capabilities
+- `loadConfig(path?)` → `CapmanConfig` — loads `capman.config.js` via `require()`
+- `writeManifest(manifest, path?)` — writes `manifest.json`
+- `readManifest(path?)` → `Manifest` — reads and Zod-validates `manifest.json`
+- `validate(manifest)` → `ValidationResult` — runs Zod + warns on missing examples
+- `generateStarterConfig()` → `string` — returns starter `capman.config.js` content
+- `VERSION` — current version string, auto-generated by `scripts/version.js`
+
+---
+
+### `src/matcher.ts`
+Intent matching — keyword scoring and LLM-based matching.
+
+Key exports:
+- `match(query, manifest)` → `MatchResult`
+  - Scores every capability against the query
+  - Returns winner + all candidates with scores
+  - Extracts params from the query using keyword heuristics
+  - Returns `out_of_scope` if best score < 50%
+- `matchWithLLM(query, manifest, { llm })` → `MatchResult`
+  - Sends structured prompt to LLM with query as JSON field (prompt injection safe)
+  - Returns matched capability, confidence, intent, extracted params
+  - Errors propagate to caller — no internal try/catch
+
+Scoring algorithm (weights):
+- Examples match: up to 60 points
+- Description match: up to 30 points
+- Name match: up to 10 points
+
+Param extraction:
+- `isIdParam` — single token (e.g. `order_id=1234`)
+- `isNavParam` — single token after nav keywords (`to`, `open`, `show`)
+- Everything else — multi-word joined with `-` (e.g. `product=blue-jacket`)
+- Optional params stay `null` if no keyword match found
+
+---
+
+### `src/resolver.ts`
+Capability execution — API calls, navigation, hybrid.
+
+Key exports:
+- `resolve(matchResult, params, options)` → `ResolveResult`
+  - Enforces privacy before executing
+  - Injects `auth.userId` into session params automatically
+  - Supports `dryRun: true` — returns call plan without executing
+  - Retries with `AbortController` timeout on failure
+  - Returns `status` and parsed `data` from API response
+
+`ResolveOptions`:
+- `baseUrl` — prepended to all API paths
+- `auth` — `{ isAuthenticated, role, userId }`
+- `dryRun` — skip actual fetch
+- `retries` — retry count on failure (default: 0)
+- `timeoutMs` — abort timeout (default: 5000)
+- `headers` — custom request headers
+- `fetch` — injectable fetch function (used in tests)
+
+Privacy enforcement:
+- `public` — always allowed
+- `user_owned` — requires `auth.isAuthenticated === true`
+- `admin` — requires `auth.role === 'admin'`
+
+---
+
+### `src/cache.ts`
+Pluggable cache backends.
+
+Key exports:
+- `CacheStore` interface — `get(key)`, `set(key, result)`, `clear()`, `size()`
+- `MemoryCache` — in-memory Map, 512-entry cap with oldest-first eviction
+- `FileCache` — async `fs.promises` read/write, lazy-loaded on first access
+- `ComboCache` — memory-first with file fallback, promotes file hits to memory
+- `normalizeQuery(query)` — lowercase + trim + collapse whitespace → cache key
+- `buildCacheKey(query, capabilityId, params)` — smarter key using capability + params (exported for future post-match cache layer — not currently used by engine)
+
+Notes:
+- `FileCache` and `ComboCache` are single-instance only — concurrent writers will corrupt
+- For multi-instance deployments, use a Redis adapter (planned v0.5)
+
+---
+
+### `src/learning.ts`
+Usage analytics and keyword index.
+
+Key exports:
+- `LearningStore` interface — `record(entry)`, `getStats()`, `getTopCapabilities(limit)`
+- `FileLearningStore` — persists to `.capman/learning.json`, caps at 10,000 entries
+- `MemoryLearningStore` — in-memory only, used in tests
+
+`LearningEntry`:
+- `query`, `capabilityId`, `confidence`, `intent`, `extractedParams`
+- `resolvedVia: 'keyword' | 'llm' | 'cache'`
+- `timestamp`
+
+`KeywordStats` (from `getStats()`):
+- `index` — `{ word → { capabilityId → hitCount } }` — foundation for adaptive matching
+- `totalQueries`, `llmQueries`, `cacheHits`, `outOfScope`
+
+---
+
+### `src/engine.ts`
+The recommended API — orchestrates matching, caching, learning, and tracing.
+
+Key exports:
+- `CapmanEngine` class
+- `EngineOptions` — all constructor options
+- `EngineResult` — `{ match, resolution, resolvedVia, durationMs, trace }`
+
+`CapmanEngine` methods:
+- `ask(query, overrides?)` → `EngineResult` — full pipeline: cache → match → resolve → learn
+- `explain(query)` → `ExplainResult` — match only, no execution, with candidate explanations
+- `getStats()` → `KeywordStats | null`
+- `getTopCapabilities(limit?)` → `Array<{ id, hits }>`
+- `clearCache()`
+
+Matching pipeline in `ask()`:
+1. Cache check — return immediately on hit
+2. Match — `cheap` / `balanced` / `accurate` mode
+3. Privacy check — recorded in trace
+4. Cache set — stores under normalized query key
+5. Resolve — actual API call or nav
+6. Reasoning build — human-readable array
+7. Learning record
+
+LLM rate limiting (all modes respect these):
+- `maxLLMCallsPerMinute` — sliding window (default: 60)
+- `llmCooldownMs` — minimum gap between calls (default: 0)
+- `llmCircuitBreakerThreshold` — failures before circuit opens (default: 3)
+- `llmCircuitBreakerResetMs` — circuit reset time (default: 60,000ms)
+
+---
+
+### `src/parser.ts`
+OpenAPI/Swagger → capman config converter.
+
+Key exports:
+- `parseOpenAPI(specPathOrUrl)` → `ParseResult`
+  - Accepts local file path or HTTP URL
+  - Parses JSON natively; YAML requires `js-yaml` installed
+  - Converts every path+method into a `Capability`
+  - Infers privacy from security schemes and tags
+  - Extracts path/query/body params
+  - Generates examples from operation summaries
+
+`ParseResult`:
+- `config` — ready-to-use `CapmanConfig`
+- `stats` — `{ total, skipped, warnings }`
+
+Supported: OpenAPI 3.x, Swagger 2.x (JSON or YAML)
+
+---
+
+### `src/logger.ts`
+Minimal logger. Silent by default.
+
+Key exports:
+- `logger` — singleton with `debug()`, `info()`, `warn()`, `error()`
+- `setLogLevel(level)` — `'silent' | 'error' | 'warn' | 'info' | 'debug'`
+- `LogLevel` type
+
+---
+
+### `src/index.ts`
+Public API surface. Re-exports everything the library exposes.
+
+Notable:
+- `ask(query, manifest, options?)` — convenience function, delegates to `CapmanEngine` internally
+  - Marked `@deprecated` — use `CapmanEngine` directly for full features
+- `MatchMode` type — `'cheap' | 'balanced' | 'accurate'`
+- All types, classes, and functions from all modules above
+
+---
+
+## bin/
+
+### `bin/capman.js`
+Entry point only. Reads `command` from `process.argv` and routes to the correct module.
+~20 lines. No logic here.
+
+### `bin/lib/shared.js`
+Shared utilities used by all command modules.
+
+Exports:
+- `args`, `command`, `flags` — parsed from `process.argv`
+- `getFlag(name)` — returns value of `--name value` flag
+- `c` — ANSI color codes (`reset`, `bold`, `teal`, `yellow`, `red`, `green`, `gray`)
+- `log` — `{ info, success, warn, error, blank }`
+- `header()` — prints capman version header
+- `requireSrc()` — loads `dist/cjs/index.js`, auto-builds if missing
+
+### `bin/lib/cmd-init.js`
+Creates `capman.config.js` starter file in current directory.
+
+### `bin/lib/cmd-generate.js`
+Three generation paths:
+- `--from <path|url>` → OpenAPI parser → `capman.config.js` + `manifest.json`
+- `--ai` → LLM-assisted generation from plain English description
+- _(no flags)_ → load `capman.config.js` manually → `manifest.json`
+
+Contains `buildAIPrompt(description)` and `callLLM(provider, apiKey, prompt)`.
+Supports `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`.
+
+### `bin/lib/cmd-validate.js`
+Reads `manifest.json`, runs Zod validation, prints errors and warnings.
+Exits with code 1 if invalid.
+
+### `bin/lib/cmd-inspect.js`
+Prints all capabilities in `manifest.json` — name, ID, resolver type, privacy, description, first example.
+
+### `bin/lib/cmd-demo.js`
+Live demo using a hardcoded e-commerce manifest.
+Shows the full **QUERY → MATCH → EXECUTION → RESULT → EXPLANATION** blueprint for 4 sample queries.
+No config or API key required.
+
+### `bin/lib/cmd-run.js`
+Runs a single query against the current `manifest.json`.
+`--debug` flag shows all candidate scores.
+
+### `bin/lib/cmd-explain.js`
+Runs `engine.explain(query)` and prints the full explanation:
+- What matched and why
+- All candidates with per-candidate explanations
+- What would execute (without executing)
+- Whether privacy would block it
+
+---
+
+## tests/
+
+### `tests/matcher.test.ts`
+14 tests covering:
+- Keyword scoring accuracy
+- Out-of-scope detection
+- Param extraction (single token, multi-word, ID params, nav params)
+- `ask()` matching modes (cheap, balanced, accurate, default)
+
+### `tests/resolver.test.ts`
+18 tests covering:
+- API resolver — dry run, path substitution, query string params
+- Nav resolver — destination building
+- Hybrid resolver — both API and nav
+- No match — graceful failure
+- Privacy enforcement — public, user_owned, admin, session injection
+- Fetch error handling — network error, non-ok status, ok + data
+- Retry behaviour — succeeds after N failures, exhausts retries
+
+### `tests/engine.test.ts`
+26 tests covering:
+- Basic `ask()` — match and resolve
+- Caching — cache hit, cache cleared, ComboCache promotion
+- Learning — records queries, top capabilities, resolvedVia tracking
+- Matching modes — cheap never calls LLM, accurate calls LLM
+- Execution trace — candidates, reasoning, steps, cache hit trace
+- `explain()` — matched, out of scope, candidates with explanations, wouldExecute, blocked, no side effects
+- LLM rate limiting — rate limit, cooldown, circuit breaker, fallback on failure
+
+### `tests/parser.test.ts`
+9 tests covering:
+- Capability extraction from spec
+- Correct IDs from `operationId`
+- Privacy inference from tags and security
+- Path and query param extraction
+- Request body field extraction
+- Base URL extraction
+- Skipping operations with insufficient info
+- Error on missing file
+
+---
+
+## scripts/
+
+### `scripts/version.js`
+Prebuild script. Reads `version` from `package.json` and writes:
+```typescript
+// Auto-generated by scripts/version.js — do not edit manually
+export const VERSION = '0.4.2'
+```
+to `src/version.ts`. Runs automatically before every `pnpm run build`.
+
+`src/version.ts` is gitignored.
+
+---
+
+## test/ (integration, not in CI)
+
+### `test/conduit.config.js`
+capman config for the RealWorld Conduit app (`conduit.productionready.io`).
+8 capabilities covering all resolver types.
+
+### `test/test-conduit.ts`
+Tests keyword matcher against live Conduit API.
+
+### `test/test-llm-live.ts`
+Tests `matchWithLLM` and `CapmanEngine` accurate mode against live API using OpenRouter free models.
+
+---
+
+## Config files
+
+| File | Purpose |
+|---|---|
+| `tsconfig.json` | CJS build → `dist/cjs/` |
+| `tsconfig.esm.json` | ESM build → `dist/esm/` |
+| `package.json` | Version, exports map, scripts, dependencies |
+| `.github/workflows/ci.yml` | Build + test + verify dist on every push |
+| `.gitignore` | Ignores `dist/`, `node_modules/`, `src/version.ts`, `.capman/` |
+| `CHANGELOG.md` | All notable changes per version |
+| `CODEBASE.md` | This file |
+
+---
+
+## Data flow
+
+```
+Developer writes capman.config.js
+         ↓
+  capman generate
+         ↓
+  generator.ts → manifest.json
+         ↓
+  CapmanEngine.ask("user query")
+         ↓
+  cache.ts     → cache hit? return immediately
+         ↓
+  matcher.ts   → score all capabilities → pick winner
+         ↓
+  resolver.ts  → enforce privacy → call API or navigate
+         ↓
+  learning.ts  → record query + result
+         ↓
+  EngineResult → { match, resolution, trace, resolvedVia }
+```

package/README.md

@@ -321,4 +321,4 @@ const result = await engine.ask('show my orders', {
 
 ## License
 
-MIT — [github.com/Hobbydefiningdoctory/capman]
+MIT — [(github.com/Hobbydefiningdoctory/capman)](https://github.com/Hobbydefiningdoctory/capman.git)