capman 0.5.2 → 0.5.4

package/dist/esm/learning.js

@@ -3,35 +3,16 @@ import * as path from 'path';
 import { logger } from './logger';
 const MAX_LEARNING_ENTRIES = 10_000;
 import { STOPWORDS } from './matcher';
-// ─── Shared computation helpers ───────────────────────────────────────────────
-function computeStats(entries) {
-    const index = {};
-    let totalQueries = 0;
-    let llmQueries = 0;
-    let cacheHits = 0;
-    let outOfScope = 0;
-    for (const entry of entries) {
-        totalQueries++;
-        if (entry.resolvedVia === 'llm')
-            llmQueries++;
-        if (entry.resolvedVia === 'cache')
-            cacheHits++;
-        if (!entry.capabilityId)
-            outOfScope++;
-        if (entry.capabilityId) {
-            const words = entry.query.toLowerCase()
-                .split(/\W+/)
-                .filter(w => w.length > 2 && !STOPWORDS.has(w));
-            for (const word of words) {
-                if (!index[word])
-                    index[word] = {};
-                index[word][entry.capabilityId] =
-                    (index[word][entry.capabilityId] ?? 0) + 1;
-            }
-        }
+// Module-level registry — tracks all active FileLearningStore instances
+// for process exit flushing. Handlers registered once to avoid accumulation.
+const activeStores = new Set();
+let exitHandlersRegistered = false;
+function flushAllStores() {
+    for (const store of activeStores) {
+        store.flushSync();
     }
-    return { index, totalQueries, llmQueries, cacheHits, outOfScope };
 }
+// ─── Shared computation helpers ───────────────────────────────────────────────
 function computeTopCapabilities(entries, limit) {
     const counts = {};
     for (const entry of entries) {
@@ -44,28 +25,18 @@ function computeTopCapabilities(entries, limit) {
         .slice(0, limit)
         .map(([id, hits]) => ({ id, hits }));
 }
-// ─── File Learning Store ──────────────────────────────────────────────────────
-export class FileLearningStore {
-    constructor(filePath = '.capman/learning.json') {
-        this.entries = [];
-        this.loaded = false;
-        this.saveQueue = Promise.resolve();
-        // ── Incremental index — updated in record(), not rebuilt in getStats() ────
+// ─── Shared Learning Index ────────────────────────────────────────────────────
+// Encapsulates keyword index and stats counters.
+// Both FileLearningStore and MemoryLearningStore compose this instead of
+// duplicating the same ~80 lines of index management logic.
+class LearningIndex {
+    constructor() {
         this.index = {};
         this.statsCounter = {
             totalQueries: 0, llmQueries: 0, cacheHits: 0, outOfScope: 0,
         };
-        const cwd = process.cwd();
-        const resolved = path.resolve(cwd, filePath);
-        const allowedPrefix = cwd === '/' ? '/' : cwd + path.sep;
-        if (!resolved.startsWith(allowedPrefix)) {
-            throw new Error(`FileCache path "${filePath}" resolves outside the working directory.\n` +
-                `Resolved: ${resolved}\nAllowed:  ${cwd}`);
-        }
-        this.filePath = resolved;
-        logger.info(`FileLearningStore initialized — writing to: ${this.filePath}`);
     }
-    updateIndex(entry) {
+    update(entry) {
         this.statsCounter.totalQueries++;
         if (entry.resolvedVia === 'llm')
             this.statsCounter.llmQueries++;
@@ -84,21 +55,18 @@ export class FileLearningStore {
             }
         }
     }
-    subtractFromIndex(entry) {
-        if (!entry.capabilityId) {
-            this.statsCounter.outOfScope = Math.max(0, this.statsCounter.outOfScope - 1);
-            this.statsCounter.totalQueries = Math.max(0, this.statsCounter.totalQueries - 1);
-            if (entry.resolvedVia === 'llm')
-                this.statsCounter.llmQueries = Math.max(0, this.statsCounter.llmQueries - 1);
-            if (entry.resolvedVia === 'cache')
-                this.statsCounter.cacheHits = Math.max(0, this.statsCounter.cacheHits - 1);
-            return;
-        }
+    subtract(entry) {
+        // Shared counter decrements regardless of capabilityId
         this.statsCounter.totalQueries = Math.max(0, this.statsCounter.totalQueries - 1);
         if (entry.resolvedVia === 'llm')
             this.statsCounter.llmQueries = Math.max(0, this.statsCounter.llmQueries - 1);
         if (entry.resolvedVia === 'cache')
             this.statsCounter.cacheHits = Math.max(0, this.statsCounter.cacheHits - 1);
+        if (!entry.capabilityId) {
+            this.statsCounter.outOfScope = Math.max(0, this.statsCounter.outOfScope - 1);
+            return;
+        }
+        // Keyword index cleanup
         const words = entry.query.toLowerCase()
             .split(/\W+/)
             .filter(w => w.length > 2 && !STOPWORDS.has(w));
@@ -115,22 +83,102 @@ export class FileLearningStore {
             }
         }
     }
-    rebuildIndex() {
+    rebuild(entries) {
+        this.index = {};
+        this.statsCounter = { totalQueries: 0, llmQueries: 0, cacheHits: 0, outOfScope: 0 };
+        for (const entry of entries) {
+            this.update(entry);
+        }
+    }
+    reset() {
         this.index = {};
         this.statsCounter = { totalQueries: 0, llmQueries: 0, cacheHits: 0, outOfScope: 0 };
-        for (const entry of this.entries) {
-            this.updateIndex(entry);
+    }
+    getStats() {
+        return { ...this.statsCounter, index: structuredClone(this.index) };
+    }
+    getIndex() {
+        return structuredClone(this.index);
+    }
+}
+// ─── File Learning Store ──────────────────────────────────────────────────────
+export class FileLearningStore {
+    constructor(filePath = '.capman/learning.json') {
+        this.entries = [];
+        this.loadPromise = null;
+        this.saveQueue = Promise.resolve();
+        this.learningIndex = new LearningIndex();
+        this.dirty = false;
+        this.saveTimer = null;
+        const cwd = process.cwd();
+        const resolved = path.resolve(cwd, filePath);
+        const allowedPrefix = cwd === '/' ? '/' : cwd + path.sep;
+        if (!resolved.startsWith(allowedPrefix)) {
+            throw new Error(`FileLearningStore path "${filePath}" resolves outside the working directory.\n` +
+                `Resolved: ${resolved}\nAllowed:  ${cwd}`);
+        }
+        this.filePath = resolved;
+        logger.info(`FileLearningStore initialized — writing to: ${this.filePath}`);
+        activeStores.add(this);
+        if (!exitHandlersRegistered) {
+            exitHandlersRegistered = true;
+            process.on('exit', flushAllStores);
+            process.on('SIGTERM', () => { flushAllStores(); process.exit(0); });
+            process.on('SIGINT', () => { flushAllStores(); process.exit(0); });
         }
     }
-    async load() {
-        if (this.loaded)
+    flushSync() {
+        // Cancel pending timer — prevents scheduleSave firing after sync write
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+            this.saveTimer = null;
+        }
+        if (!this.dirty)
             return;
+        this.dirty = false;
+        try {
+            const dir = path.dirname(this.filePath);
+            fs.mkdirSync(dir, { recursive: true });
+            const tmp = `${this.filePath}.tmp`;
+            const payload = JSON.stringify({ entries: this.entries, updatedAt: new Date().toISOString() }, null, 2);
+            // Write to .tmp then rename — matches _doSave() pattern so they can't interleave
+            fs.writeFileSync(tmp, payload);
+            fs.renameSync(tmp, this.filePath);
+        }
+        catch {
+            // Best-effort in exit handler
+        }
+    }
+    /**
+     * Removes this store from the exit flush registry and cancels any pending save timer.
+     * Call when the store is no longer needed to prevent memory leaks in long-running servers.
+     */
+    async destroy() {
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+            this.saveTimer = null;
+        }
+        if (this.dirty) {
+            this.dirty = false;
+            // Await final flush before removing from registry —
+            // ensures data is written before the store becomes unreachable
+            await this.save();
+        }
+        activeStores.delete(this);
+    }
+    load() {
+        if (!this.loadPromise) {
+            this.loadPromise = this._doLoad();
+        }
+        return this.loadPromise;
+    }
+    async _doLoad() {
         try {
             const raw = await fs.promises.readFile(this.filePath, 'utf-8');
             const parsed = JSON.parse(raw);
             if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && Array.isArray(parsed.entries)) {
                 this.entries = parsed.entries;
-                this.rebuildIndex();
+                this.learningIndex.rebuild(this.entries);
                 logger.debug(`Learning store loaded: ${this.entries.length} entries`);
             }
             else {
@@ -140,7 +188,19 @@ export class FileLearningStore {
         catch {
             // File doesn't exist yet — start fresh
         }
-        this.loaded = true;
+    }
+    scheduleSave(urgencyMs = 5_000) {
+        this.dirty = true;
+        if (!this.saveTimer) {
+            this.saveTimer = setTimeout(() => {
+                this.saveTimer = null;
+                if (this.dirty) {
+                    this.dirty = false;
+                    // Route through saveQueue — serializes with all other saves
+                    this.save();
+                }
+            }, urgencyMs);
+        }
     }
     save() {
         this.saveQueue = this.saveQueue.then(() => this._doSave());
@@ -150,10 +210,12 @@ export class FileLearningStore {
         try {
             const dir = path.dirname(this.filePath);
             await fs.promises.mkdir(dir, { recursive: true });
-            await fs.promises.writeFile(this.filePath, JSON.stringify({
+            const tmp = `${this.filePath}.tmp`;
+            await fs.promises.writeFile(tmp, JSON.stringify({
                 entries: this.entries,
                 updatedAt: new Date().toISOString(),
             }, null, 2));
+            await fs.promises.rename(tmp, this.filePath);
         }
         catch (err) {
             logger.warn(`Failed to save learning store to ${this.filePath}: ${err instanceof Error ? err.message : String(err)}`);
@@ -173,34 +235,40 @@ export class FileLearningStore {
                 .join(' '),
         };
         this.entries.push(sanitized);
-        this.updateIndex(sanitized);
+        this.learningIndex.update(sanitized);
         if (this.entries.length > MAX_LEARNING_ENTRIES) {
             const excess = this.entries.length - MAX_LEARNING_ENTRIES;
             const pruned = this.entries.splice(0, excess);
             // Subtract pruned entries from index — O(pruned × w) instead of O(n × w) full rebuild
             for (const entry of pruned) {
-                this.subtractFromIndex(entry);
+                this.learningIndex.subtract(entry);
             }
             logger.debug(`Learning store pruned ${excess} oldest entries (cap: ${MAX_LEARNING_ENTRIES})`);
         }
-        await this.save();
+        this.scheduleSave();
     }
     async getStats() {
         await this.load();
-        return { ...this.statsCounter, index: structuredClone(this.index) };
+        return this.learningIndex.getStats();
     }
     async getIndex() {
         await this.load();
-        return structuredClone(this.index);
+        return this.learningIndex.getIndex();
     }
     async getTopCapabilities(limit = 5) {
         await this.load();
         return computeTopCapabilities(this.entries, limit);
     }
     async clear() {
+        // Cancel any pending debounced save — prevents stale data being written
+        // after clear() resets state
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+            this.saveTimer = null;
+        }
+        this.dirty = false;
         this.entries = [];
-        this.index = {};
-        this.statsCounter = { totalQueries: 0, llmQueries: 0, cacheHits: 0, outOfScope: 0 };
+        this.learningIndex.reset();
         await this.save();
     }
 }
@@ -208,10 +276,7 @@ export class FileLearningStore {
 export class MemoryLearningStore {
     constructor() {
         this.entries = [];
-        this.index = {};
-        this.statsCounter = {
-            totalQueries: 0, llmQueries: 0, cacheHits: 0, outOfScope: 0,
-        };
+        this.learningIndex = new LearningIndex();
     }
     async record(entry) {
         const sanitized = {
@@ -223,77 +288,29 @@ export class MemoryLearningStore {
                 .join(' '),
         };
         this.entries.push(sanitized);
-        this.updateIndex(sanitized);
+        this.learningIndex.update(sanitized);
         if (this.entries.length > MAX_LEARNING_ENTRIES) {
             const excess = this.entries.length - MAX_LEARNING_ENTRIES;
             const pruned = this.entries.splice(0, excess);
             for (const entry of pruned) {
-                this.subtractFromIndex(entry);
+                this.learningIndex.subtract(entry);
             }
         }
     }
     async getStats() {
-        return { ...this.statsCounter, index: structuredClone(this.index) };
+        return this.learningIndex.getStats();
     }
     async getIndex() {
-        return structuredClone(this.index);
-    }
-    updateIndex(entry) {
-        this.statsCounter.totalQueries++;
-        if (entry.resolvedVia === 'llm')
-            this.statsCounter.llmQueries++;
-        if (entry.resolvedVia === 'cache')
-            this.statsCounter.cacheHits++;
-        if (!entry.capabilityId)
-            this.statsCounter.outOfScope++;
-        if (entry.capabilityId) {
-            const words = entry.query.toLowerCase()
-                .split(/\W+/)
-                .filter(w => w.length > 2 && !STOPWORDS.has(w));
-            for (const word of words) {
-                this.index[word] ??= {};
-                this.index[word][entry.capabilityId] =
-                    (this.index[word][entry.capabilityId] ?? 0) + 1;
-            }
-        }
-    }
-    subtractFromIndex(entry) {
-        if (!entry.capabilityId) {
-            this.statsCounter.outOfScope = Math.max(0, this.statsCounter.outOfScope - 1);
-            this.statsCounter.totalQueries = Math.max(0, this.statsCounter.totalQueries - 1);
-            if (entry.resolvedVia === 'llm')
-                this.statsCounter.llmQueries = Math.max(0, this.statsCounter.llmQueries - 1);
-            if (entry.resolvedVia === 'cache')
-                this.statsCounter.cacheHits = Math.max(0, this.statsCounter.cacheHits - 1);
-            return;
-        }
-        this.statsCounter.totalQueries = Math.max(0, this.statsCounter.totalQueries - 1);
-        if (entry.resolvedVia === 'llm')
-            this.statsCounter.llmQueries = Math.max(0, this.statsCounter.llmQueries - 1);
-        if (entry.resolvedVia === 'cache')
-            this.statsCounter.cacheHits = Math.max(0, this.statsCounter.cacheHits - 1);
-        const words = entry.query.toLowerCase()
-            .split(/\W+/)
-            .filter(w => w.length > 2 && !STOPWORDS.has(w));
-        for (const word of words) {
-            if (!this.index[word])
-                continue;
-            this.index[word][entry.capabilityId] =
-                (this.index[word][entry.capabilityId] ?? 1) - 1;
-            if (this.index[word][entry.capabilityId] <= 0) {
-                delete this.index[word][entry.capabilityId];
-            }
-            if (Object.keys(this.index[word]).length === 0) {
-                delete this.index[word];
-            }
-        }
+        return this.learningIndex.getIndex();
     }
     async getTopCapabilities(limit = 5) {
         return computeTopCapabilities(this.entries, limit);
     }
     async clear() {
         this.entries = [];
-        this.index = {};
-        this.statsCounter = { totalQueries: 0, llmQueries: 0, cacheHits: 0, outOfScope: 0 };
+        this.learningIndex.reset();
+    }
+    async destroy() {
+        // No-op for memory store — nothing to flush or deregister
     }
 }

package/dist/esm/matcher.d.ts

@@ -6,7 +6,6 @@ export declare const STOPWORDS: Set<string>;
 export declare function resolverToIntent(cap: Capability): MatchResult['intent'];
 /**
  * Extracts parameter values from a user query using keyword heuristics.
- *
  * Known limits:
  * - Extracts single tokens only — "jane smith" would extract "jane"
  * - Keyword matching is positional — "articles from authors I follow"
@@ -15,7 +14,11 @@ export declare function resolverToIntent(cap: Capability): MatchResult['intent']
  *   param extraction more accurately via the LLM prompt
  */
 export declare function extractParams(query: string, cap: Capability): Record<string, string | null>;
-export declare function match(query: string, manifest: Manifest): MatchResult;
+export interface MatchOptions {
+    fuzzyMatch?: boolean;
+    fuzzyThreshold?: number;
+}
+export declare function match(query: string, manifest: Manifest, options?: MatchOptions): MatchResult;
 export interface LLMMatcherOptions {
     llm: (prompt: string) => Promise<string>;
 }

package/dist/esm/matcher.js

@@ -1,4 +1,5 @@
 import { logger } from './logger';
+import Fuse from 'fuse.js';
 // ─── Typed error for LLM parse failures ──────────────────────────────────────
 export class LLMParseError extends Error {
     constructor(message) {
@@ -24,14 +25,20 @@ function scoreCapability(query, cap) {
     const q = query.toLowerCase();
     let score = 0;
     const qWords = filterStopwords(q.split(/\W+/).filter(Boolean));
-    // Check examples — exact substring match is a strong signal
+    // Check examples — take the best single example match, not the sum.
+    // Accumulating across examples rewards bloated example lists over precise ones:
+    // 10 examples at 50% overlap = 300 points (clamped to 60) beats 1 perfect example at 60.
+    // Taking Math.max means quality of examples matters, not quantity.
+    let bestExampleScore = 0;
     for (const example of cap.examples ?? []) {
         const exWords = filterStopwords(example.toLowerCase().split(/\s+/));
         if (exWords.length === 0)
             continue;
         const overlap = exWords.filter(w => qWords.includes(w)).length;
-        score += (overlap / exWords.length) * 60;
+        const contribution = (overlap / exWords.length) * 60;
+        bestExampleScore = Math.max(bestExampleScore, contribution);
     }
+    score += bestExampleScore;
     // Check description words
     const descWords = filterStopwords(cap.description.toLowerCase().split(/\W+/).filter(Boolean));
     if (descWords.length > 0) {
@@ -58,7 +65,6 @@ export function resolverToIntent(cap) {
 }
 /**
  * Extracts parameter values from a user query using keyword heuristics.
- *
  * Known limits:
  * - Extracts single tokens only — "jane smith" would extract "jane"
  * - Keyword matching is positional — "articles from authors I follow"
@@ -136,7 +142,7 @@ export function extractParams(query, cap) {
     }
     return result;
 }
-export function match(query, manifest) {
+export function match(query, manifest, options = {}) {
     if (!query?.trim()) {
         logger.warn('Empty query received');
         return {
@@ -148,15 +154,65 @@ export function match(query, manifest) {
             candidates: [],
         };
     }
-    logger.info(`Matching query: "${query}"`);
+    logger.info(`Matching query (${query.length} chars)`);
+    logger.debug(`Full query: "${query}"`);
     logger.debug(`Manifest has ${manifest.capabilities.length} capabilities`);
     let best = null;
     let bestScore = 0;
+    // ── Build Fuse index once per match() call ────────────────────────────────
+    // Flat corpus — each example/description/name is its own searchable record,
+    // tagged with the owning capability id. This avoids two pitfalls of using
+    // Fuse's multi-key mode here:
+    //   (1) joining examples into one string dilutes single-example matches,
+    //   (2) multi-key weighted aggregation mixes good and bad field matches
+    //       when we actually want the best single match across all fields.
+    // After searching, we group hits by capability and take the BEST score.
+    // Field prioritization (examples > description > name) is already applied
+    // by the keyword scorer (60/30/10 weights in scoreCapability), so fuzzy
+    // here is a pure similarity signal.
+    const fuzzyScoreMap = new Map();
+    if (options.fuzzyMatch) {
+        const corpus = [];
+        for (const cap of manifest.capabilities) {
+            for (const ex of cap.examples ?? []) {
+                if (ex?.trim())
+                    corpus.push({ capabilityId: cap.id, text: ex });
+            }
+            if (cap.description?.trim())
+                corpus.push({ capabilityId: cap.id, text: cap.description });
+            if (cap.name?.trim())
+                corpus.push({ capabilityId: cap.id, text: cap.name });
+        }
+        if (corpus.length > 0) {
+            const fuse = new Fuse(corpus, {
+                keys: ['text'],
+                threshold: options.fuzzyThreshold ?? 0.4,
+                includeScore: true,
+                ignoreLocation: true,
+                minMatchCharLength: 3,
+            });
+            // Group hits by capability, keeping the best (lowest fuse score = highest similarity).
+            // Convert to 0-100 contribution: fuseScore 0.0 = 100%, fuseScore 1.0 = 0%.
+            // Multiplier 100 (not 60) lets a strong fuzzy match alone reach the standard
+            // 50% confidence cutoff for typo-only queries that have no keyword overlap.
+            for (const hit of fuse.search(query)) {
+                const capId = hit.item.capabilityId;
+                const contribution = (1 - (hit.score ?? 1)) * 100;
+                const existing = fuzzyScoreMap.get(capId) ?? 0;
+                if (contribution > existing)
+                    fuzzyScoreMap.set(capId, contribution);
+            }
+        }
+    }
+    // ── Score all capabilities ────────────────────────────────────────────────
     const allScores = [];
     for (const cap of manifest.capabilities) {
-        const score = scoreCapability(query, cap);
-        logger.debug(`  scored "${cap.id}": ${score}%`);
-        allScores.push({ cap, score });
+        const keywordScore = scoreCapability(query, cap);
+        const fuzzyScore = fuzzyScoreMap.get(cap.id) ?? 0;
+        const via = fuzzyScore > keywordScore ? 'fuzzy' : 'keyword';
+        const score = Math.min(100, Math.round(Math.max(keywordScore, fuzzyScore)));
+        logger.debug(`  scored "${cap.id}": ${score}% (keyword: ${keywordScore}%, fuzzy: ${Math.round(fuzzyScore)}%)`);
+        allScores.push({ cap, score, via });
         if (score > bestScore) {
             bestScore = score;
             best = cap;
@@ -168,7 +224,8 @@ export function match(query, manifest) {
         matched: cap.id === best?.id,
     }));
     if (!best || bestScore < 50) {
-        logger.info(`No match above threshold (best: ${bestScore}% for "${best?.id ?? 'none'}")`);
+        const bestId = best ? best.id : 'none';
+        logger.info(`No match above threshold (best: ${bestScore}% for "${bestId}")`);
         // Out of scope return:
         return {
             capability: null,
@@ -182,13 +239,16 @@ export function match(query, manifest) {
     const params = extractParams(query, best);
     logger.info(`Matched "${best.id}" at ${bestScore}% confidence`);
     logger.debug(`Extracted params: ${JSON.stringify(Object.fromEntries(Object.entries(params).map(([k, v]) => [k, v != null ? '[REDACTED]' : 'null'])))}`);
+    // Use the via tag tracked during scoring — avoids redundant scoreCapability call.
+    const bestEntry = allScores.find(s => s.cap.id === best.id);
+    const winner = bestEntry?.via === 'fuzzy' ? 'fuzzy match' : 'keyword scoring';
     // Matched return:
     return {
         capability: best,
         confidence: bestScore,
         intent: resolverToIntent(best),
         extractedParams: params,
-        reasoning: `Matched "${best.id}" via keyword scoring (score: ${bestScore})`,
+        reasoning: `Matched "${best.id}" via ${winner} (score: ${bestScore})`,
         candidates,
     };
 }

package/dist/esm/parser.js

@@ -50,8 +50,14 @@ function parseSpecText(text, source) {
         const yaml = require('js-yaml');
         return yaml.load(text);
     }
-    catch {
-        // js-yaml not installed — try basic YAML detection
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Distinguish "module not found" from actual YAML parse errors
+        const code = err.code;
+        if (code !== 'MODULE_NOT_FOUND') {
+            throw new Error(`YAML parse error in "${source}": ${msg}`);
+        }
+        // js-yaml not installed — fall through to extension check
         if (source.endsWith('.yaml') || source.endsWith('.yml')) {
             throw new Error('YAML spec detected but js-yaml is not installed.\n' +
                 'Install it: npm install js-yaml\n' +

package/dist/esm/resolver.d.ts

@@ -17,5 +17,12 @@ export interface ResolveOptions {
     retries?: number;
     /** Timeout in milliseconds (default: 5000) */
     timeoutMs?: number;
+    /**
+     * When true, retries all HTTP methods including POST/PUT/PATCH/DELETE.
+     * Use only for idempotent write operations — retrying non-idempotent
+     * methods can cause duplicate side effects (duplicate orders, double charges).
+     * @default false
+     */
+    retryAllMethods?: boolean;
 }
 export declare function resolve(matchResult: MatchResult, params?: Record<string, unknown>, options?: ResolveOptions): Promise<ResolveResult>;