capman 0.4.1 → 0.4.3

package/dist/esm/index.js

@@ -1,24 +1,26 @@
 export { setLogLevel } from './logger';
-import { CapmanEngine } from './engine';
 export { generate, loadConfig, writeManifest, readManifest, validate, generateStarterConfig, } from './generator';
 export { match, matchWithLLM, } from './matcher';
 export { resolve } from './resolver';
 // ─── Engine (recommended API) ─────────────────────────────────────────────────
 export { CapmanEngine } from './engine';
 // ─── Cache ────────────────────────────────────────────────────────────────────
-export { MemoryCache, FileCache, ComboCache } from './cache';
+export { MemoryCache, FileCache, ComboCache, buildCacheKey, normalizeQuery } from './cache';
 // ─── Learning ─────────────────────────────────────────────────────────────────
 export { FileLearningStore, MemoryLearningStore } from './learning';
+export { parseOpenAPI } from './parser';
+// ─── Convenience: ask() ───────────────────────────────────────────────────────
+import { CapmanEngine } from './engine';
 /**
  * One-shot convenience: match + resolve in a single call.
  * Delegates to CapmanEngine internally.
  *
+ * @deprecated For full features including trace and caching, use CapmanEngine directly.
+ *
  * @example
  * const result = await ask("show me the dashboard", manifest, {
  *   baseUrl: 'https://api.your-app.com',
  * })
- *
- * @deprecated For full features including trace and caching, use CapmanEngine directly.
  */
 export async function ask(query, manifest, options = {}) {
     const { llm, mode, ...resolveOptions } = options;

package/dist/esm/learning.d.ts

@@ -0,0 +1,55 @@
+export interface LearningEntry {
+    query: string;
+    capabilityId: string | null;
+    confidence: number;
+    intent: string;
+    extractedParams: Record<string, string | null>;
+    resolvedVia: 'keyword' | 'llm' | 'cache';
+    timestamp: string;
+}
+export interface KeywordStats {
+    /** keyword → Map of capabilityId → hit count */
+    index: Record<string, Record<string, number>>;
+    /** Total queries processed */
+    totalQueries: number;
+    /** Queries that went to LLM */
+    llmQueries: number;
+    /** Queries served from cache */
+    cacheHits: number;
+    /** Out of scope queries */
+    outOfScope: number;
+}
+export interface LearningStore {
+    record(entry: LearningEntry): Promise<void>;
+    getStats(): Promise<KeywordStats>;
+    getTopCapabilities(limit?: number): Promise<Array<{
+        id: string;
+        hits: number;
+    }>>;
+    clear(): Promise<void>;
+}
+export declare class FileLearningStore implements LearningStore {
+    private filePath;
+    private entries;
+    private loaded;
+    constructor(filePath?: string);
+    private load;
+    private save;
+    record(entry: LearningEntry): Promise<void>;
+    getStats(): Promise<KeywordStats>;
+    getTopCapabilities(limit?: number): Promise<Array<{
+        id: string;
+        hits: number;
+    }>>;
+    clear(): Promise<void>;
+}
+export declare class MemoryLearningStore implements LearningStore {
+    private entries;
+    record(entry: LearningEntry): Promise<void>;
+    getStats(): Promise<KeywordStats>;
+    getTopCapabilities(limit?: number): Promise<Array<{
+        id: string;
+        hits: number;
+    }>>;
+    clear(): Promise<void>;
+}

package/dist/esm/logger.d.ts

@@ -0,0 +1,21 @@
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+export declare class Logger {
+    private level;
+    constructor(level?: LogLevel);
+    setLevel(level: LogLevel): void;
+    error(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    debug(msg: string, ...args: unknown[]): void;
+}
+export declare const logger: Logger;
+/**
+ * Set the global log level for capman.
+ *
+ * @example
+ * import { setLogLevel } from 'capman'
+ * setLogLevel('debug') // see everything
+ * setLogLevel('info')  // see key steps
+ * setLogLevel('silent') // no output (default)
+ */
+export declare function setLogLevel(level: LogLevel): void;

package/dist/esm/matcher.d.ts

@@ -0,0 +1,6 @@
+import type { Manifest, MatchResult } from './types';
+export declare function match(query: string, manifest: Manifest): MatchResult;
+export interface LLMMatcherOptions {
+    llm: (prompt: string) => Promise<string>;
+}
+export declare function matchWithLLM(query: string, manifest: Manifest, options: LLMMatcherOptions): Promise<MatchResult>;

package/dist/esm/matcher.js

@@ -203,29 +203,23 @@ export async function matchWithLLM(query, manifest, options) {
   "reasoning": "<one sentence>",
   "extracted_params": { "<param_name>": "<value or null>" }
   }`;
-    try {
-        const raw = await options.llm(prompt);
-        const clean = raw.replace(/```json|```/g, '').trim();
-        const parsed = JSON.parse(clean);
-        const isOOS = parsed.matched_capability === 'OUT_OF_SCOPE';
-        const capability = isOOS
-            ? null
-            : manifest.capabilities.find(c => c.id === parsed.matched_capability) ?? null;
-        return {
-            capability,
-            confidence: parsed.confidence,
-            intent: isOOS ? 'out_of_scope' : parsed.intent,
-            extractedParams: parsed.extracted_params ?? {},
-            reasoning: parsed.reasoning,
-            candidates: capability ? [{
-                    capabilityId: capability.id,
-                    score: parsed.confidence,
-                    matched: true,
-                }] : [],
-        };
-    }
-    catch (err) {
-        logger.warn(`LLM match failed, falling back to keyword matcher: ${err}`);
-        return match(query, manifest);
-    }
+    const raw = await options.llm(prompt);
+    const clean = raw.replace(/```json|```/g, '').trim();
+    const parsed = JSON.parse(clean);
+    const isOOS = parsed.matched_capability === 'OUT_OF_SCOPE';
+    const capability = isOOS
+        ? null
+        : manifest.capabilities.find(c => c.id === parsed.matched_capability) ?? null;
+    return {
+        capability,
+        confidence: parsed.confidence,
+        intent: isOOS ? 'out_of_scope' : parsed.intent,
+        extractedParams: parsed.extracted_params ?? {},
+        reasoning: parsed.reasoning,
+        candidates: capability ? [{
+                capabilityId: capability.id,
+                score: parsed.confidence,
+                matched: true,
+            }] : [],
+    };
 }

package/dist/esm/parser.d.ts

@@ -0,0 +1,10 @@
+import type { CapmanConfig } from './types';
+export interface ParseResult {
+    config: CapmanConfig;
+    stats: {
+        total: number;
+        skipped: number;
+        warnings: string[];
+    };
+}
+export declare function parseOpenAPI(specPathOrUrl: string): Promise<ParseResult>;

package/dist/esm/parser.js

@@ -0,0 +1,267 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { logger } from './logger';
+export async function parseOpenAPI(specPathOrUrl) {
+    const spec = await loadSpec(specPathOrUrl);
+    return convertSpec(spec);
+}
+// ─── Load spec from file or URL ───────────────────────────────────────────────
+async function loadSpec(source) {
+    // URL
+    if (source.startsWith('http://') || source.startsWith('https://')) {
+        logger.info(`Fetching OpenAPI spec from: ${source}`);
+        const res = await fetch(source);
+        if (!res.ok)
+            throw new Error(`Failed to fetch spec: ${res.status} ${res.statusText}`);
+        const text = await res.text();
+        return parseSpecText(text, source);
+    }
+    // Local file
+    const resolved = path.resolve(process.cwd(), source);
+    if (!fs.existsSync(resolved)) {
+        throw new Error(`Spec file not found: ${resolved}`);
+    }
+    logger.info(`Reading OpenAPI spec from: ${resolved}`);
+    const text = fs.readFileSync(resolved, 'utf-8');
+    return parseSpecText(text, source);
+}
+function parseSpecText(text, source) {
+    // Try JSON first
+    try {
+        return JSON.parse(text);
+    }
+    catch { }
+    // Try YAML — only if yaml package available
+    try {
+        const yaml = require('js-yaml');
+        return yaml.load(text);
+    }
+    catch {
+        // js-yaml not installed — try basic YAML detection
+        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' +
+                'Or convert your spec to JSON first.');
+        }
+    }
+    throw new Error('Could not parse spec — must be valid JSON or YAML');
+}
+// ─── Convert OpenAPI spec to CapmanConfig ─────────────────────────────────────
+function convertSpec(spec) {
+    const warnings = [];
+    const capabilities = [];
+    let skipped = 0;
+    // Determine base URL
+    const baseUrl = extractBaseUrl(spec);
+    // Detect global security schemes
+    const securitySchemes = spec.components?.securitySchemes
+        ?? spec.securityDefinitions
+        ?? {};
+    const hasGlobalAuth = Object.keys(securitySchemes).some(k => {
+        const s = securitySchemes[k];
+        return s.type === 'http' || s.type === 'apiKey' || s.type === 'oauth2';
+    });
+    // Convert each path + method
+    for (const [urlPath, pathItem] of Object.entries(spec.paths ?? {})) {
+        const methods = [];
+        if (pathItem.get)
+            methods.push(['GET', pathItem.get]);
+        if (pathItem.post)
+            methods.push(['POST', pathItem.post]);
+        if (pathItem.put)
+            methods.push(['PUT', pathItem.put]);
+        if (pathItem.patch)
+            methods.push(['PATCH', pathItem.patch]);
+        if (pathItem.delete)
+            methods.push(['DELETE', pathItem.delete]);
+        for (const [method, op] of methods) {
+            const result = convertOperation(urlPath, method, op, hasGlobalAuth, securitySchemes);
+            if (!result) {
+                skipped++;
+                warnings.push(`Skipped ${method} ${urlPath} — no useful info to generate capability`);
+                continue;
+            }
+            // Check for duplicate IDs
+            const existing = capabilities.find(c => c.id === result.id);
+            if (existing) {
+                result.id = `${result.id}_${method.toLowerCase()}`;
+                warnings.push(`Duplicate ID resolved: ${result.id}`);
+            }
+            capabilities.push(result);
+        }
+    }
+    const config = {
+        app: sanitizeAppName(spec.info.title),
+        baseUrl,
+        capabilities,
+    };
+    return {
+        config,
+        stats: {
+            total: capabilities.length,
+            skipped,
+            warnings,
+        },
+    };
+}
+// ─── Convert single operation ─────────────────────────────────────────────────
+function convertOperation(urlPath, method, op, hasGlobalAuth, securitySchemes) {
+    // Build capability ID
+    const id = op.operationId
+        ? toSnakeCase(op.operationId)
+        : pathToId(method, urlPath);
+    // Name and description
+    const name = op.summary ?? toHumanName(id);
+    const description = op.description ?? op.summary ?? `${method} ${urlPath}`;
+    if (description.length < 5)
+        return null;
+    // Extract params
+    const params = extractParams(op);
+    // Determine privacy scope
+    const privacyLevel = inferPrivacy(op, hasGlobalAuth, securitySchemes);
+    // Build examples from path pattern
+    const examples = generateExamples(name, description, params);
+    // Build returns from response descriptions
+    const returns = inferReturns(op, urlPath);
+    return {
+        id,
+        name,
+        description,
+        examples,
+        params,
+        returns,
+        resolver: {
+            type: 'api',
+            endpoints: [{ method, path: urlPath }],
+        },
+        privacy: { level: privacyLevel },
+    };
+}
+// ─── Extract params from operation ───────────────────────────────────────────
+function extractParams(op) {
+    const params = [];
+    // Path and query params
+    for (const p of op.parameters ?? []) {
+        if (p.in === 'header' || p.in === 'cookie')
+            continue;
+        const source = p.in === 'path' ? 'user_query' :
+            p.in === 'query' ? 'user_query' :
+                'context';
+        params.push({
+            name: toSnakeCase(p.name),
+            description: p.description ?? toHumanName(p.name),
+            required: p.required ?? p.in === 'path',
+            source,
+        });
+    }
+    // Request body fields (POST/PUT/PATCH)
+    const bodyContent = op.requestBody?.content;
+    if (bodyContent) {
+        const schema = (bodyContent['application/json']?.schema ??
+            bodyContent['*/*']?.schema);
+        if (schema?.properties) {
+            const required = schema.required ?? [];
+            for (const [fieldName, field] of Object.entries(schema.properties)) {
+                // Skip if already added as a path param
+                if (params.find(p => p.name === toSnakeCase(fieldName)))
+                    continue;
+                params.push({
+                    name: toSnakeCase(fieldName),
+                    description: field.description ?? toHumanName(fieldName),
+                    required: required.includes(fieldName),
+                    source: 'user_query',
+                });
+            }
+        }
+    }
+    return params;
+}
+// ─── Infer privacy scope ──────────────────────────────────────────────────────
+function inferPrivacy(op, hasGlobalAuth, securitySchemes) {
+    // Explicitly no security on this operation
+    if (op.security !== undefined && op.security.length === 0)
+        return 'public';
+    // Check operation tags for admin hints
+    const tags = (op.tags ?? []).map(t => t.toLowerCase());
+    if (tags.some(t => t.includes('admin') || t.includes('internal')))
+        return 'admin';
+    // Check operation ID / summary for admin hints
+    const hint = `${op.operationId ?? ''} ${op.summary ?? ''}`.toLowerCase();
+    if (hint.includes('admin') || hint.includes('manage') || hint.includes('internal')) {
+        return 'admin';
+    }
+    // If global auth exists or operation has security, it's user_owned
+    if (hasGlobalAuth || (op.security && op.security.length > 0)) {
+        return 'user_owned';
+    }
+    return 'public';
+}
+// ─── Generate examples ────────────────────────────────────────────────────────
+function generateExamples(name, description, params) {
+    const examples = [];
+    // Primary example from name
+    examples.push(name);
+    // Variation from description (first sentence, truncated)
+    const firstSentence = description.split(/[.!?]/)[0].trim();
+    if (firstSentence && firstSentence !== name && firstSentence.length < 80) {
+        examples.push(firstSentence);
+    }
+    // Param-based example
+    const required = params.filter(p => p.required && p.source === 'user_query');
+    if (required.length > 0) {
+        const paramNames = required.map(p => p.name.replace(/_/g, ' ')).join(' and ');
+        examples.push(`${name} by ${paramNames}`);
+    }
+    return examples.slice(0, 3);
+}
+// ─── Infer returns ────────────────────────────────────────────────────────────
+function inferReturns(op, urlPath) {
+    const segments = urlPath.split('/').filter(Boolean);
+    const resource = segments
+        .filter(s => !s.startsWith('{'))
+        .pop() ?? 'data';
+    return [resource.replace(/-/g, '_')];
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function extractBaseUrl(spec) {
+    // OpenAPI 3.x
+    if (spec.servers?.length) {
+        return spec.servers[0].url.replace(/\/$/, '');
+    }
+    // Swagger 2.x
+    if (spec.host) {
+        const scheme = 'https';
+        const base = spec.basePath ?? '';
+        return `${scheme}://${spec.host}${base}`.replace(/\/$/, '');
+    }
+    return 'https://api.your-app.com';
+}
+function sanitizeAppName(title) {
+    return title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+function toSnakeCase(str) {
+    return str
+        .replace(/([A-Z])/g, '_$1')
+        .replace(/[-\s]+/g, '_')
+        .toLowerCase()
+        .replace(/^_/, '')
+        .replace(/__+/g, '_');
+}
+function toHumanName(id) {
+    return id
+        .replace(/_/g, ' ')
+        .replace(/\b\w/g, c => c.toUpperCase());
+}
+function pathToId(method, urlPath) {
+    const segments = urlPath
+        .split('/')
+        .filter(Boolean)
+        .map(s => s.startsWith('{') ? s.slice(1, -1) : s)
+        .join('_');
+    const prefix = method === 'GET' ? 'get' :
+        method === 'POST' ? 'create' :
+            method === 'PUT' ? 'update' :
+                method === 'PATCH' ? 'update' :
+                    method === 'DELETE' ? 'delete' : 'call';
+    return toSnakeCase(`${prefix}_${segments}`);
+}

package/dist/esm/resolver.d.ts

@@ -0,0 +1,21 @@
+import type { MatchResult, ResolveResult } from './types';
+export interface AuthContext {
+    /** Whether the current request is authenticated */
+    isAuthenticated: boolean;
+    /** Current user's role */
+    role?: 'user' | 'admin';
+    /** Current user's ID — injected into session params */
+    userId?: string;
+}
+export interface ResolveOptions {
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    dryRun?: boolean;
+    headers?: Record<string, string>;
+    auth?: AuthContext;
+    /** Number of retries on failure (default: 0) */
+    retries?: number;
+    /** Timeout in milliseconds (default: 5000) */
+    timeoutMs?: number;
+}
+export declare function resolve(matchResult: MatchResult, params?: Record<string, unknown>, options?: ResolveOptions): Promise<ResolveResult>;