capman 0.5.2 → 0.5.3

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.js

@@ -148,7 +148,8 @@ 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;

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>;

package/dist/esm/resolver.js

@@ -1,4 +1,6 @@
 import { logger } from './logger';
+// ─── Constants ────────────────────────────────────────────────────────────────
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
 function redactParams(params) {
     return Object.fromEntries(Object.entries(params).map(([k, v]) => [k, v != null ? '[REDACTED]' : 'null']));
 }
@@ -49,12 +51,8 @@ export async function resolve(matchResult, params = {}, options = {}) {
     // they must never leak into the query string as ?user_id=xyz
     const enrichedParams = { ...params };
     if (options.auth?.userId !== undefined && options.auth.userId !== '') {
-        const resolver = capability.resolver;
-        const pathTemplate = resolver.type === 'api' ? resolver.endpoints.map(e => e.path).join('') :
-            resolver.type === 'hybrid' ? resolver.api.endpoints.map(e => e.path).join('') :
-                resolver.type === 'nav' ? resolver.destination : '';
         for (const param of capability.params) {
-            if (param.source === 'session' && pathTemplate.includes(`{${param.name}}`)) {
+            if (param.source === 'session') {
                 enrichedParams[param.name] = options.auth.userId;
                 logger.debug(`Injected session param "${param.name}" (value redacted)`);
             }
@@ -65,15 +63,18 @@ export async function resolve(matchResult, params = {}, options = {}) {
     logger.debug(`Params: ${JSON.stringify(redactParams(params))}`);
     logger.debug(`Options: baseUrl=${options.baseUrl} dryRun=${options.dryRun}`);
     try {
+        const sessionParamNames = new Set(capability.params
+            .filter(p => p.source === 'session')
+            .map(p => p.name));
         switch (resolver.type) {
             case 'api':
-                return await resolveApi(resolver, enrichedParams, options);
+                return await resolveApi(resolver, enrichedParams, options, sessionParamNames);
             case 'nav':
                 return resolveNav(resolver, enrichedParams);
             case 'hybrid': {
                 logger.debug('Hybrid resolver — running API and nav in parallel');
                 const [apiResult, navResult] = await Promise.all([
-                    resolveApi(resolver.api, enrichedParams, options),
+                    resolveApi(resolver.api, enrichedParams, options, sessionParamNames),
                     Promise.resolve(resolveNav(resolver.nav, enrichedParams)),
                 ]);
                 return {
@@ -109,15 +110,26 @@ export async function resolve(matchResult, params = {}, options = {}) {
  * For capabilities where ordering or rollback matters, define separate capabilities
  * with single endpoints and orchestrate them at the application layer.
  */
-async function resolveApi(resolver, params, options) {
+async function resolveApi(resolver, params, options, sessionParamNames = new Set()) {
     const startTime = Date.now();
     const retries = options.retries ?? 0;
     const timeoutMs = options.timeoutMs ?? 5000;
-    const apiCalls = resolver.endpoints.map(endpoint => ({
-        method: endpoint.method,
-        url: buildUrl(options.baseUrl ?? '', endpoint.path, params),
-        params: Object.fromEntries(Object.entries(params).filter(([, v]) => v !== null && v !== undefined)),
-    }));
+    const apiCalls = resolver.endpoints.map(endpoint => {
+        // Build per-endpoint params — only inject session params if this
+        // specific endpoint has the placeholder. Prevents userId leaking
+        // as ?user_id=xyz on endpoints that don't use it in their path.
+        const endpointParams = { ...params };
+        for (const name of sessionParamNames) {
+            if (!endpoint.path.includes(`{${name}}`)) {
+                delete endpointParams[name]; // strip session param — not in this endpoint's path
+            }
+        }
+        return {
+            method: endpoint.method,
+            url: buildUrl(options.baseUrl ?? '', endpoint.path, endpointParams),
+            params: Object.fromEntries(Object.entries(endpointParams).filter(([, v]) => v !== null && v !== undefined)),
+        };
+    });
     if (options.dryRun) {
         return { success: true, resolverType: 'api', apiCalls, durationMs: Date.now() - startTime };
     }
@@ -130,9 +142,14 @@ async function resolveApi(resolver, params, options) {
         };
     }
     // ── Fetch with retry + timeout (iterative — no recursion) ────────────────
+    // Only retry safe/idempotent methods — retrying POST/PUT/PATCH/DELETE
+    // can cause duplicate side effects (e.g. duplicate orders, double charges).
     async function fetchWithRetry(call) {
+        const effectiveRetries = (options.retryAllMethods || SAFE_METHODS.has(call.method))
+            ? retries
+            : 0;
         let lastErr;
-        for (let attempt = 0; attempt <= retries; attempt++) {
+        for (let attempt = 0; attempt <= effectiveRetries; attempt++) {
             const controller = new AbortController();
             const timer = setTimeout(() => controller.abort(), timeoutMs);
             try {
@@ -151,8 +168,8 @@ async function resolveApi(resolver, params, options) {
                 clearTimeout(timer);
                 lastErr = err;
                 const isTimeout = err instanceof Error && err.name === 'AbortError';
-                if (attempt < retries) {
-                    logger.warn(`Request failed (attempt ${attempt + 1}/${retries + 1}) — retrying: ${isTimeout ? 'timeout' : err}`);
+                if (attempt < effectiveRetries) {
+                    logger.warn(`Request failed (attempt ${attempt + 1}/${effectiveRetries + 1}) — retrying: ${isTimeout ? 'timeout' : err}`);
                 }
                 else {
                     throw isTimeout ? new Error(`Request timed out after ${timeoutMs}ms`) : err;
@@ -209,12 +226,17 @@ function resolveNav(resolver, params) {
     }
     return { success: true, resolverType: 'nav', navTarget: destination };
 }
-// Note: buildUrl does not validate param values against an allowlist.
-// resolveNav() does validate via validateNavParam() because nav destinations
-// are used as deep links where path traversal is a real risk.
-// For API URLs, extractParams() strips most dangerous characters upstream,
-// so the practical risk is low — but any future caller bypassing extractParams
-// should add validation here too.
+function validateApiPathParam(key, value) {
+    // Prevent path traversal via unencoded slashes — encodeURIComponent does not
+    // encode '/' so a value like '../../admin' would traverse the path hierarchy.
+    // This mirrors the allowlist validation already applied in resolveNav().
+    if (!/^[a-zA-Z0-9_\-.:@]+$/.test(value)) {
+        throw new Error(`API path param "${key}" contains invalid characters: "${value}". ` +
+            `Only alphanumeric, hyphens, underscores, dots, colons, and @ are allowed.`);
+    }
+}
+// Both buildUrl (API) and resolveNav (nav) validate path param values against
+// an allowlist before substitution — prevents path traversal via unencoded slashes.
 function buildUrl(baseUrl, urlPath, params) {
     let resolved = urlPath;
     const unused = {};
@@ -222,7 +244,9 @@ function buildUrl(baseUrl, urlPath, params) {
         if (value === null || value === undefined)
             continue; // never write null into URLs
         if (resolved.includes(`{${key}}`)) {
-            resolved = resolved.replaceAll(`{${key}}`, encodeURIComponent(String(value)));
+            const str = String(value);
+            validateApiPathParam(key, str);
+            resolved = resolved.replaceAll(`{${key}}`, encodeURIComponent(str));
         }
         else {
             unused[key] = value;