@cleocode/mcp-server 0.86.0

package/dist/lib/audit.js

@@ -0,0 +1,311 @@
+/**
+ * Audit Trail for MCP Server Mutations
+ *
+ * Logs all write operations to .cleo/audit-log.json for compliance
+ * and debugging purposes.
+ *
+ * @task T2920
+ * @task T2929
+ */
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import { getConfig } from './config.js';
+/**
+ * Maximum audit log size in bytes before rotation (default: 10MB)
+ */
+const MAX_AUDIT_LOG_SIZE = 10 * 1024 * 1024;
+/**
+ * Get audit log file path
+ */
+function getAuditLogPath() {
+    const config = getConfig();
+    // Default to .cleo/audit-log.json in project root
+    return join(process.cwd(), '.cleo', 'audit-log.json');
+}
+/**
+ * Get current session ID from environment or config
+ */
+function getCurrentSessionId() {
+    // TODO: Integrate with session system when available
+    return process.env.CLEO_SESSION_ID || null;
+}
+/**
+ * Ensure .cleo directory exists
+ */
+async function ensureCleoDir() {
+    const cleoDir = join(process.cwd(), '.cleo');
+    try {
+        await fs.mkdir(cleoDir, { recursive: true });
+    }
+    catch (error) {
+        // Ignore if already exists
+        if (error.code !== 'EEXIST') {
+            throw error;
+        }
+    }
+}
+/**
+ * Log mutation to audit trail
+ *
+ * Appends a single-line JSON entry to .cleo/audit-log.json
+ * Non-blocking - errors are logged but not thrown
+ * Automatically rotates log if size exceeds limit
+ *
+ * @param entry Audit entry to log
+ */
+export async function logMutation(entry) {
+    try {
+        // Check if audit logging is enabled
+        const config = getConfig();
+        if (!config.auditLog) {
+            return; // Audit logging disabled
+        }
+        // Ensure .cleo directory exists
+        await ensureCleoDir();
+        // Get audit log path
+        const logPath = getAuditLogPath();
+        // Check if rotation is needed
+        await checkAndRotateLog(logPath);
+        // Serialize entry as single-line JSON
+        const line = JSON.stringify(entry) + '\n';
+        // Append to log file
+        await fs.appendFile(logPath, line, 'utf8');
+    }
+    catch (error) {
+        // Log error but don't throw - audit logging should not block operations
+        console.error('Failed to write audit log entry:', error);
+    }
+}
+/**
+ * Log error to audit trail
+ *
+ * Convenience function for logging errors with full context
+ *
+ * @param domain Domain where error occurred
+ * @param operation Operation that failed
+ * @param error Error object or message
+ * @param params Operation parameters
+ * @param exitCode Exit code (default: 1)
+ */
+export async function logError(domain, operation, error, params = {}, exitCode = 1) {
+    // Check if audit logging is enabled
+    const config = getConfig();
+    if (!config.auditLog) {
+        return; // Audit logging disabled
+    }
+    const errorMessage = error instanceof Error ? error.message : error;
+    const taskId = typeof params.taskId === 'string' ? params.taskId : undefined;
+    const entry = {
+        timestamp: new Date().toISOString(),
+        sessionId: getCurrentSessionId(),
+        domain,
+        operation,
+        params,
+        result: {
+            success: false,
+            exitCode,
+            duration: 0,
+        },
+        metadata: {
+            taskId,
+            source: 'mcp',
+        },
+        error: errorMessage,
+    };
+    await logMutation(entry);
+}
+/**
+ * Read audit log entries
+ *
+ * @param options Filter options
+ * @returns Array of audit entries
+ */
+export async function readAuditLog(options) {
+    try {
+        const logPath = getAuditLogPath();
+        // Read log file
+        const content = await fs.readFile(logPath, 'utf8');
+        // Parse JSONL
+        const entries = content
+            .split('\n')
+            .filter((line) => line.trim())
+            .map((line) => JSON.parse(line));
+        // Apply filters
+        let filtered = entries;
+        if (options?.since) {
+            filtered = filtered.filter((e) => e.timestamp >= options.since);
+        }
+        if (options?.domain) {
+            filtered = filtered.filter((e) => e.domain === options.domain);
+        }
+        if (options?.operation) {
+            filtered = filtered.filter((e) => e.operation === options.operation);
+        }
+        if (options?.success !== undefined) {
+            filtered = filtered.filter((e) => e.result.success === options.success);
+        }
+        // Apply limit
+        if (options?.limit) {
+            filtered = filtered.slice(-options.limit);
+        }
+        return filtered;
+    }
+    catch (error) {
+        // If file doesn't exist, return empty array
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+/**
+ * Get audit statistics
+ *
+ * @returns Audit statistics
+ */
+export async function getAuditStats() {
+    const entries = await readAuditLog();
+    const stats = {
+        totalEntries: entries.length,
+        successCount: entries.filter((e) => e.result.success).length,
+        failureCount: entries.filter((e) => !e.result.success).length,
+        byDomain: {},
+        byOperation: {},
+        avgDuration: 0,
+    };
+    // Count by domain
+    for (const entry of entries) {
+        stats.byDomain[entry.domain] = (stats.byDomain[entry.domain] || 0) + 1;
+        const opKey = `${entry.domain}.${entry.operation}`;
+        stats.byOperation[opKey] = (stats.byOperation[opKey] || 0) + 1;
+    }
+    // Calculate average duration
+    const durations = entries.filter((e) => e.result.duration).map((e) => e.result.duration);
+    if (durations.length > 0) {
+        stats.avgDuration = durations.reduce((a, b) => a + b, 0) / durations.length;
+    }
+    return stats;
+}
+/**
+ * Clear audit log (use with caution)
+ *
+ * @returns Number of entries cleared
+ */
+export async function clearAuditLog() {
+    try {
+        const entries = await readAuditLog();
+        const count = entries.length;
+        const logPath = getAuditLogPath();
+        await fs.unlink(logPath);
+        return count;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return 0;
+        }
+        throw error;
+    }
+}
+/**
+ * Check and rotate audit log if size exceeds limit
+ *
+ * Rotates log to timestamped archive file when size exceeds MAX_AUDIT_LOG_SIZE
+ *
+ * @param logPath Path to audit log file
+ */
+async function checkAndRotateLog(logPath) {
+    try {
+        const stats = await fs.stat(logPath);
+        if (stats.size >= MAX_AUDIT_LOG_SIZE) {
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+            const archivePath = join(process.cwd(), '.cleo', `audit-log-${timestamp}.json`);
+            // Move current log to archive
+            await fs.rename(logPath, archivePath);
+            console.log(`Rotated audit log: ${archivePath} (${stats.size} bytes)`);
+        }
+    }
+    catch (error) {
+        // If file doesn't exist, no rotation needed
+        if (error.code !== 'ENOENT') {
+            console.error('Failed to check/rotate audit log:', error);
+        }
+    }
+}
+/**
+ * Manually rotate audit log
+ *
+ * Forces rotation regardless of size
+ *
+ * @returns Path to rotated log file
+ */
+export async function rotateLog() {
+    try {
+        const logPath = getAuditLogPath();
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const archivePath = join(process.cwd(), '.cleo', `audit-log-${timestamp}.json`);
+        // Check if log exists
+        try {
+            await fs.access(logPath);
+        }
+        catch {
+            return null; // No log to rotate
+        }
+        // Move current log to archive
+        await fs.rename(logPath, archivePath);
+        return archivePath;
+    }
+    catch (error) {
+        console.error('Failed to rotate audit log:', error);
+        return null;
+    }
+}
+/**
+ * Archive old audit entries
+ *
+ * Moves entries older than specified date to archive file
+ *
+ * @param beforeDate ISO date string
+ * @returns Number of entries archived
+ */
+export async function archiveAuditLog(beforeDate) {
+    try {
+        const entries = await readAuditLog();
+        const toArchive = entries.filter((e) => e.timestamp < beforeDate);
+        const toKeep = entries.filter((e) => e.timestamp >= beforeDate);
+        if (toArchive.length === 0) {
+            return 0;
+        }
+        // Write archive file
+        const archivePath = join(process.cwd(), '.cleo', `audit-log-archive-${beforeDate}.json`);
+        const archiveContent = toArchive.map((e) => JSON.stringify(e)).join('\n') + '\n';
+        await fs.writeFile(archivePath, archiveContent, 'utf8');
+        // Write remaining entries back to log
+        const logPath = getAuditLogPath();
+        const logContent = toKeep.map((e) => JSON.stringify(e)).join('\n') + '\n';
+        await fs.writeFile(logPath, logContent, 'utf8');
+        return toArchive.length;
+    }
+    catch (error) {
+        console.error('Failed to archive audit log:', error);
+        return 0;
+    }
+}
+/**
+ * Query audit log entries with filters
+ *
+ * @param options Query options
+ * @returns Filtered audit entries
+ */
+export async function queryAudit(options) {
+    const entries = await readAuditLog(options);
+    // Additional filters for new fields
+    let filtered = entries;
+    if (options?.taskId) {
+        filtered = filtered.filter((e) => e.metadata?.taskId === options.taskId);
+    }
+    if (options?.sessionId) {
+        filtered = filtered.filter((e) => e.sessionId === options.sessionId);
+    }
+    return filtered;
+}
+//# sourceMappingURL=audit.js.map

package/dist/lib/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/lib/audit.ts"],"names":[],"mappings":"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"}

package/dist/lib/background-jobs.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Background Job Manager for Long-Running Operations
+ *
+ * Per MCP-SERVER-SPECIFICATION.md Section 10, operations that may take >30s
+ * should support async execution. This module provides a job manager that
+ * tracks background operations with status, progress, and auto-cleanup.
+ *
+ * @task T3080
+ */
+/**
+ * Background job status
+ */
+export type JobStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Background job representation
+ */
+export interface BackgroundJob {
+    id: string;
+    operation: string;
+    status: JobStatus;
+    startedAt: string;
+    completedAt?: string;
+    result?: unknown;
+    error?: string;
+    progress?: number;
+}
+/**
+ * Configuration for BackgroundJobManager
+ */
+export interface BackgroundJobManagerConfig {
+    maxJobs?: number;
+    retentionMs?: number;
+}
+/**
+ * Manages background jobs for long-running operations
+ */
+export declare class BackgroundJobManager {
+    private jobs;
+    private abortControllers;
+    private maxJobs;
+    private retentionMs;
+    private cleanupTimer;
+    constructor(config?: BackgroundJobManagerConfig);
+    /**
+     * Start a new background job
+     *
+     * @param operation - The operation identifier (e.g. "validate.test.run")
+     * @param executor - Async function to execute in the background
+     * @returns The job ID
+     * @throws Error if max concurrent jobs reached
+     */
+    startJob(operation: string, executor: () => Promise<unknown>): Promise<string>;
+    /**
+     * Get a specific job by ID
+     */
+    getJob(jobId: string): BackgroundJob | undefined;
+    /**
+     * List all jobs, optionally filtered by status
+     */
+    listJobs(status?: string): BackgroundJob[];
+    /**
+     * Cancel a running job
+     *
+     * @returns true if the job was cancelled, false if not found or not running
+     */
+    cancelJob(jobId: string): boolean;
+    /**
+     * Update job progress (0-100)
+     */
+    updateProgress(jobId: string, progress: number): boolean;
+    /**
+     * Cleanup old completed/failed/cancelled jobs past retention period
+     *
+     * @returns Number of jobs cleaned up
+     */
+    cleanup(): number;
+    /**
+     * Destroy the manager: cancel all running jobs and clear state
+     */
+    destroy(): void;
+    /**
+     * Execute a job's executor function and update status on completion/failure
+     */
+    private executeJob;
+}
+//# sourceMappingURL=background-jobs.d.ts.map

package/dist/lib/background-jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-jobs.d.ts","sourceRoot":"","sources":["../../src/lib/background-jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,gBAAgB,CAA+B;IACvD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAAwC;gBAEhD,MAAM,CAAC,EAAE,0BAA0B;IAe/C;;;;;;;OAOG;IACG,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BpF;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIhD;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE;IAQ1C;;;;OAIG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAkBjC;;OAEG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IASxD;;;;OAIG;IACH,OAAO,IAAI,MAAM;IAqBjB;;OAEG;IACH,OAAO,IAAI,IAAI;IAoBf;;OAEG;YACW,UAAU;CAmCzB"}

package/dist/lib/background-jobs.js

@@ -0,0 +1,183 @@
+/**
+ * Background Job Manager for Long-Running Operations
+ *
+ * Per MCP-SERVER-SPECIFICATION.md Section 10, operations that may take >30s
+ * should support async execution. This module provides a job manager that
+ * tracks background operations with status, progress, and auto-cleanup.
+ *
+ * @task T3080
+ */
+import { randomUUID } from 'crypto';
+/**
+ * Manages background jobs for long-running operations
+ */
+export class BackgroundJobManager {
+    jobs;
+    abortControllers;
+    maxJobs;
+    retentionMs;
+    cleanupTimer;
+    constructor(config) {
+        this.jobs = new Map();
+        this.abortControllers = new Map();
+        this.maxJobs = config?.maxJobs ?? 10;
+        this.retentionMs = config?.retentionMs ?? 3600000; // 1 hour default
+        this.cleanupTimer = null;
+        // Start periodic cleanup every 5 minutes
+        this.cleanupTimer = setInterval(() => this.cleanup(), 300000);
+        // Don't prevent process exit
+        if (this.cleanupTimer.unref) {
+            this.cleanupTimer.unref();
+        }
+    }
+    /**
+     * Start a new background job
+     *
+     * @param operation - The operation identifier (e.g. "validate.test.run")
+     * @param executor - Async function to execute in the background
+     * @returns The job ID
+     * @throws Error if max concurrent jobs reached
+     */
+    async startJob(operation, executor) {
+        // Check concurrent job limit (only count running jobs)
+        const runningCount = this.listJobs('running').length;
+        if (runningCount >= this.maxJobs) {
+            throw new Error(`Maximum concurrent jobs reached (${this.maxJobs}). Cancel or wait for existing jobs to complete.`);
+        }
+        const jobId = randomUUID();
+        const abortController = new AbortController();
+        const job = {
+            id: jobId,
+            operation,
+            status: 'running',
+            startedAt: new Date().toISOString(),
+        };
+        this.jobs.set(jobId, job);
+        this.abortControllers.set(jobId, abortController);
+        // Execute async - don't await
+        this.executeJob(jobId, executor, abortController.signal);
+        return jobId;
+    }
+    /**
+     * Get a specific job by ID
+     */
+    getJob(jobId) {
+        return this.jobs.get(jobId);
+    }
+    /**
+     * List all jobs, optionally filtered by status
+     */
+    listJobs(status) {
+        const all = Array.from(this.jobs.values());
+        if (!status) {
+            return all;
+        }
+        return all.filter((job) => job.status === status);
+    }
+    /**
+     * Cancel a running job
+     *
+     * @returns true if the job was cancelled, false if not found or not running
+     */
+    cancelJob(jobId) {
+        const job = this.jobs.get(jobId);
+        if (!job || job.status !== 'running') {
+            return false;
+        }
+        const controller = this.abortControllers.get(jobId);
+        if (controller) {
+            controller.abort();
+            this.abortControllers.delete(jobId);
+        }
+        job.status = 'cancelled';
+        job.completedAt = new Date().toISOString();
+        return true;
+    }
+    /**
+     * Update job progress (0-100)
+     */
+    updateProgress(jobId, progress) {
+        const job = this.jobs.get(jobId);
+        if (!job || job.status !== 'running') {
+            return false;
+        }
+        job.progress = Math.max(0, Math.min(100, progress));
+        return true;
+    }
+    /**
+     * Cleanup old completed/failed/cancelled jobs past retention period
+     *
+     * @returns Number of jobs cleaned up
+     */
+    cleanup() {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [id, job] of this.jobs.entries()) {
+            if (job.status === 'running') {
+                continue;
+            }
+            if (job.completedAt) {
+                const completedTime = new Date(job.completedAt).getTime();
+                if (now - completedTime > this.retentionMs) {
+                    this.jobs.delete(id);
+                    this.abortControllers.delete(id);
+                    cleaned++;
+                }
+            }
+        }
+        return cleaned;
+    }
+    /**
+     * Destroy the manager: cancel all running jobs and clear state
+     */
+    destroy() {
+        // Cancel all running jobs
+        for (const [id, job] of this.jobs.entries()) {
+            if (job.status === 'running') {
+                const controller = this.abortControllers.get(id);
+                if (controller) {
+                    controller.abort();
+                }
+            }
+        }
+        this.jobs.clear();
+        this.abortControllers.clear();
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+    }
+    /**
+     * Execute a job's executor function and update status on completion/failure
+     */
+    async executeJob(jobId, executor, signal) {
+        const job = this.jobs.get(jobId);
+        if (!job) {
+            return;
+        }
+        try {
+            const result = await executor();
+            // Check if cancelled during execution
+            if (signal.aborted) {
+                return;
+            }
+            job.status = 'completed';
+            job.completedAt = new Date().toISOString();
+            job.result = result;
+            job.progress = 100;
+        }
+        catch (error) {
+            // Check if this was a cancellation
+            if (signal.aborted) {
+                return;
+            }
+            job.status = 'failed';
+            job.completedAt = new Date().toISOString();
+            job.error = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            this.abortControllers.delete(jobId);
+        }
+    }
+}
+//# sourceMappingURL=background-jobs.js.map

package/dist/lib/background-jobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-jobs.js","sourceRoot":"","sources":["../../src/lib/background-jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AA6BpC;;GAEG;AACH,MAAM,OAAO,oBAAoB;IACvB,IAAI,CAA6B;IACjC,gBAAgB,CAA+B;IAC/C,OAAO,CAAS;IAChB,WAAW,CAAS;IACpB,YAAY,CAAwC;IAE5D,YAAY,MAAmC;QAC7C,IAAI,CAAC,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC;QACtB,IAAI,CAAC,gBAAgB,GAAG,IAAI,GAAG,EAAE,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,MAAM,EAAE,OAAO,IAAI,EAAE,CAAC;QACrC,IAAI,CAAC,WAAW,GAAG,MAAM,EAAE,WAAW,IAAI,OAAO,CAAC,CAAC,iBAAiB;QACpE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAEzB,yCAAyC;QACzC,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;QAC9D,6BAA6B;QAC7B,IAAI,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;YAC5B,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAC5B,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,CAAC,SAAiB,EAAE,QAAgC;QAChE,uDAAuD;QACvD,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC;QACrD,IAAI,YAAY,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CACb,oCAAoC,IAAI,CAAC,OAAO,kDAAkD,CACnG,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;QAC3B,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;QAE9C,MAAM,GAAG,GAAkB;YACzB,EAAE,EAAE,KAAK;YACT,SAAS;YACT,MAAM,EAAE,SAAS;YACjB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC;QAEF,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;QAElD,8BAA8B;QAC9B,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;QAEzD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAa;QAClB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,MAAe;QACtB,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,GAAG,CAAC;QACb,CAAC;QACD,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;IACpD,CAAC;IAED;;;;OAIG;IACH,SAAS,CAAC,KAAa;QACrB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACrC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpD,IAAI,UAAU,EAAE,CAAC;YACf,UAAU,CAAC,KAAK,EAAE,CAAC;YACnB,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC;QAED,GAAG,CAAC,MAAM,GAAG,WAAW,CAAC;QACzB,GAAG,CAAC,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAE3C,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,KAAa,EAAE,QAAgB;QAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACrC,OAAO,KAAK,CAAC;QACf,CAAC;QACD,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,OAAO;QACL,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,OAAO,GAAG,CAAC,CAAC;QAEhB,KAAK,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;YAC5C,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC7B,SAAS;YACX,CAAC;YACD,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;gBACpB,MAAM,aAAa,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE,CAAC;gBAC1D,IAAI,GAAG,GAAG,aAAa,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;oBAC3C,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;oBACrB,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;oBACjC,OAAO,EAAE,CAAC;gBACZ,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,OAAO;QACL,0BAA0B;QAC1B,KAAK,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;YAC5C,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,UAAU,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACjD,IAAI,UAAU,EAAE,CAAC;oBACf,UAAU,CAAC,KAAK,EAAE,CAAC;gBACrB,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAClB,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC;QAE9B,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACjC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,UAAU,CACtB,KAAa,EACb,QAAgC,EAChC,MAAmB;QAEnB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,QAAQ,EAAE,CAAC;YAEhC,sCAAsC;YACtC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBACnB,OAAO;YACT,CAAC;YAED,GAAG,CAAC,MAAM,GAAG,WAAW,CAAC;YACzB,GAAG,CAAC,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAC3C,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC;YACpB,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC;QACrB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,mCAAmC;YACnC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBACnB,OAAO;YACT,CAAC;YAED,GAAG,CAAC,MAAM,GAAG,QAAQ,CAAC;YACtB,GAAG,CAAC,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAC3C,GAAG,CAAC,KAAK,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrE,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;CACF"}

package/dist/lib/cache.d.ts

@@ -0,0 +1,78 @@
+/**
+ * In-memory query cache for CLEO MCP Server
+ *
+ * Caches cleo_query responses with configurable TTL.
+ * Cache key = domain + operation + hash(params).
+ * Invalidated on any cleo_mutate operation for the relevant domain.
+ *
+ * @task T3145
+ */
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    evictions: number;
+    size: number;
+    domains: Record<string, number>;
+}
+/**
+ * Query cache with per-domain invalidation
+ */
+export declare class QueryCache {
+    private store;
+    private domainKeys;
+    private stats;
+    private ttl;
+    private enabled;
+    private cleanupTimer;
+    constructor(ttlMs?: number, enabled?: boolean);
+    /**
+     * Build cache key from domain, operation, and params
+     */
+    buildKey(domain: string, operation: string, params?: Record<string, unknown>): string;
+    /**
+     * Get cached value, or undefined if not found/expired
+     */
+    get<T = unknown>(domain: string, operation: string, params?: Record<string, unknown>): T | undefined;
+    /**
+     * Store a value in the cache
+     */
+    set<T = unknown>(domain: string, operation: string, params: Record<string, unknown> | undefined, value: T): void;
+    /**
+     * Invalidate all cached entries for a domain
+     *
+     * Called on any cleo_mutate operation to ensure consistency.
+     */
+    invalidateDomain(domain: string): number;
+    /**
+     * Clear entire cache
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset statistics counters
+     */
+    resetStats(): void;
+    /**
+     * Evict all expired entries
+     */
+    evictExpired(): number;
+    /**
+     * Stop the cleanup timer (call on shutdown)
+     */
+    destroy(): void;
+    /**
+     * Check if cache is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Delete a single key and update domain tracking
+     */
+    private delete;
+}
+//# sourceMappingURL=cache.d.ts.map