synapse-mcp 1.0.0 → 1.0.2

package/dist/services/cache-layer.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Cache statistics tracking cache performance and resource usage.
+ * Used by ICacheLayer implementations to report operational metrics.
+ */
+export interface CacheStats {
+    /**
+     * Number of successful cache lookups (key found).
+     */
+    hits: number;
+    /**
+     * Number of failed cache lookups (key not found).
+     */
+    misses: number;
+    /**
+     * Current number of entries stored in the cache.
+     */
+    size: number;
+    /**
+     * Maximum number of entries the cache can hold before eviction occurs.
+     */
+    maxSize: number;
+    /**
+     * Total number of entries that have been evicted due to capacity limits.
+     */
+    evictions: number;
+}
+/**
+ * Generic cache layer interface providing key-value storage with eviction policies.
+ * Implementations should handle storage, retrieval, and automatic eviction when capacity is reached.
+ *
+ * @template K - Type of cache keys (must be comparable for lookups)
+ * @template V - Type of cached values
+ *
+ * @example
+ * ```typescript
+ * // Create a cache for host configurations
+ * const cache: ICacheLayer<string, HostConfig> = new LRUCacheLayer(100);
+ *
+ * // Store a value
+ * cache.set('prod-host', hostConfig);
+ *
+ * // Retrieve a value
+ * const config = cache.get('prod-host');
+ *
+ * // Check cache performance
+ * const stats = cache.getStats();
+ * console.log(`Hit rate: ${stats.hits / (stats.hits + stats.misses)}`);
+ * ```
+ */
+export interface ICacheLayer<K, V> {
+    /**
+     * Retrieve a value from the cache by its key.
+     * Updates access tracking for eviction policy (e.g., LRU tracking).
+     *
+     * @param key - The cache key to lookup
+     * @returns The cached value if found, undefined if not in cache
+     */
+    get(key: K): V | undefined;
+    /**
+     * Store a value in the cache with the specified key.
+     * If the cache is at capacity, evicts entries according to the eviction policy.
+     * If the key already exists, updates the value and resets access tracking.
+     *
+     * @param key - The cache key to store under
+     * @param value - The value to cache
+     */
+    set(key: K, value: V): void;
+    /**
+     * Remove a specific entry from the cache by its key.
+     * Does nothing if the key is not in the cache.
+     *
+     * @param key - The cache key to remove
+     */
+    delete(key: K): void;
+    /**
+     * Remove all entries from the cache and reset statistics.
+     * Resets the cache to its initial empty state.
+     */
+    clear(): void;
+    /**
+     * Get current cache statistics for monitoring and debugging.
+     * Statistics should reflect the current state of the cache accurately.
+     *
+     * @returns Cache statistics including hits, misses, size, capacity, and evictions
+     */
+    getStats(): CacheStats;
+}
+/**
+ * Least Recently Used (LRU) cache implementation with TTL support.
+ * Evicts the least recently accessed item when cache reaches max capacity.
+ * Uses Map for O(1) lookups and leverages insertion order for LRU tracking.
+ *
+ * @template K - Type of cache keys (must be comparable for Map lookups)
+ * @template V - Type of cached values
+ *
+ * @example
+ * ```typescript
+ * // Create cache with 100 max entries and 1 hour TTL
+ * const cache = new LRUCacheLayer<string, UserData>(100, 3600000);
+ *
+ * // Store and retrieve
+ * cache.set('user-123', userData);
+ * const data = cache.get('user-123');
+ *
+ * // Monitor performance
+ * const stats = cache.getStats();
+ * console.log(`Hit rate: ${stats.hits / (stats.hits + stats.misses)}`);
+ * ```
+ */
+export declare class LRUCacheLayer<K, V> implements ICacheLayer<K, V> {
+    private readonly cache;
+    private readonly maxSize;
+    private readonly ttlMs;
+    private stats;
+    /**
+     * Create a new LRU cache layer.
+     *
+     * @param maxSize - Maximum number of entries (default: 50)
+     * @param ttlMs - Time-to-live in milliseconds (default: 24 hours)
+     */
+    constructor(maxSize?: number, ttlMs?: number);
+    /**
+     * Retrieve a value from the cache by its key.
+     * Moves the accessed entry to the end of the Map (marks as most recently used).
+     * Returns undefined if key doesn't exist or entry has expired.
+     *
+     * @param key - The cache key to lookup
+     * @returns The cached value if found and not expired, undefined otherwise
+     */
+    get(key: K): V | undefined;
+    /**
+     * Store a value in the cache with the specified key.
+     * If key exists, updates value and moves to end (most recently used).
+     * If cache is full, evicts the least recently used entry first.
+     *
+     * @param key - The cache key to store under
+     * @param value - The value to cache
+     */
+    set(key: K, value: V): void;
+    /**
+     * Remove a specific entry from the cache by its key.
+     * Does nothing if the key is not in the cache.
+     *
+     * @param key - The cache key to remove
+     */
+    delete(key: K): void;
+    /**
+     * Remove all entries from the cache and reset statistics.
+     * Resets the cache to its initial empty state.
+     */
+    clear(): void;
+    /**
+     * Get current cache statistics for monitoring and debugging.
+     * Statistics reflect the current state including all tracked metrics.
+     *
+     * @returns Cache statistics including hits, misses, size, capacity, and evictions
+     */
+    getStats(): CacheStats;
+}
+//# sourceMappingURL=cache-layer.d.ts.map

package/dist/services/cache-layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-layer.d.ts","sourceRoot":"","sources":["../../src/services/cache-layer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,EAAE,CAAC;IAC/B;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAE3B;;;;;;;OAOG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAE5B;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IAErB;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;;;;OAKG;IACH,QAAQ,IAAI,UAAU,CAAC;CACxB;AAaD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,aAAa,CAAC,CAAC,EAAE,CAAC,CAAE,YAAW,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC;IAC3D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,KAAK,CAIX;IAEF;;;;;OAKG;gBACS,OAAO,SAAK,EAAE,KAAK,GAAE,MAA4B;IAW7D;;;;;;;OAOG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IA6B1B;;;;;;;OAOG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAmB3B;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;IAIpB;;;OAGG;IACH,KAAK,IAAI,IAAI;IASb;;;;;OAKG;IACH,QAAQ,IAAI,UAAU;CASvB"}

package/dist/services/cache-layer.js

@@ -0,0 +1,138 @@
+/**
+ * Least Recently Used (LRU) cache implementation with TTL support.
+ * Evicts the least recently accessed item when cache reaches max capacity.
+ * Uses Map for O(1) lookups and leverages insertion order for LRU tracking.
+ *
+ * @template K - Type of cache keys (must be comparable for Map lookups)
+ * @template V - Type of cached values
+ *
+ * @example
+ * ```typescript
+ * // Create cache with 100 max entries and 1 hour TTL
+ * const cache = new LRUCacheLayer<string, UserData>(100, 3600000);
+ *
+ * // Store and retrieve
+ * cache.set('user-123', userData);
+ * const data = cache.get('user-123');
+ *
+ * // Monitor performance
+ * const stats = cache.getStats();
+ * console.log(`Hit rate: ${stats.hits / (stats.hits + stats.misses)}`);
+ * ```
+ */
+export class LRUCacheLayer {
+    cache;
+    maxSize;
+    ttlMs;
+    stats;
+    /**
+     * Create a new LRU cache layer.
+     *
+     * @param maxSize - Maximum number of entries (default: 50)
+     * @param ttlMs - Time-to-live in milliseconds (default: 24 hours)
+     */
+    constructor(maxSize = 50, ttlMs = 24 * 60 * 60 * 1000) {
+        this.cache = new Map();
+        this.maxSize = maxSize;
+        this.ttlMs = ttlMs;
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            evictions: 0,
+        };
+    }
+    /**
+     * Retrieve a value from the cache by its key.
+     * Moves the accessed entry to the end of the Map (marks as most recently used).
+     * Returns undefined if key doesn't exist or entry has expired.
+     *
+     * @param key - The cache key to lookup
+     * @returns The cached value if found and not expired, undefined otherwise
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.stats.misses++;
+            return undefined;
+        }
+        // Check if entry has expired
+        const now = Date.now();
+        if (now - entry.timestamp > this.ttlMs) {
+            // Entry expired - remove it and count as miss
+            this.cache.delete(key);
+            this.stats.misses++;
+            return undefined;
+        }
+        // Entry is valid - move to end (most recently used)
+        // Note: delete-and-reinsert is O(1) but performs 2 Map operations per hit.
+        // For higher throughput (>10k ops/sec), consider doubly-linked-list + Map
+        // approach (e.g., lru-cache npm package) for O(1) single-operation reordering.
+        // Current implementation is sufficient for typical workloads (<1k ops/sec).
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        this.stats.hits++;
+        return entry.value;
+    }
+    /**
+     * Store a value in the cache with the specified key.
+     * If key exists, updates value and moves to end (most recently used).
+     * If cache is full, evicts the least recently used entry first.
+     *
+     * @param key - The cache key to store under
+     * @param value - The value to cache
+     */
+    set(key, value) {
+        const now = Date.now();
+        // If key already exists, delete it first (we'll re-add at end)
+        if (this.cache.has(key)) {
+            this.cache.delete(key);
+        }
+        else if (this.cache.size >= this.maxSize) {
+            // Cache is full and this is a new key - evict LRU (first entry)
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined) {
+                this.cache.delete(firstKey);
+                this.stats.evictions++;
+            }
+        }
+        // Add entry at end (most recently used position)
+        this.cache.set(key, { value, timestamp: now });
+    }
+    /**
+     * Remove a specific entry from the cache by its key.
+     * Does nothing if the key is not in the cache.
+     *
+     * @param key - The cache key to remove
+     */
+    delete(key) {
+        this.cache.delete(key);
+    }
+    /**
+     * Remove all entries from the cache and reset statistics.
+     * Resets the cache to its initial empty state.
+     */
+    clear() {
+        this.cache.clear();
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            evictions: 0,
+        };
+    }
+    /**
+     * Get current cache statistics for monitoring and debugging.
+     * Statistics reflect the current state including all tracked metrics.
+     *
+     * @returns Cache statistics including hits, misses, size, capacity, and evictions
+     */
+    getStats() {
+        return {
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            evictions: this.stats.evictions,
+        };
+    }
+}
+//# sourceMappingURL=cache-layer.js.map

package/dist/services/cache-layer.js.map

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

package/dist/services/compose-cache.d.ts

@@ -0,0 +1,75 @@
+import { type CacheStats } from "./cache-layer.js";
+export interface CachedProject {
+    path: string;
+    name: string;
+    discoveredFrom: "docker-ls" | "scan" | "user-provided";
+    lastSeen: string;
+}
+export interface CacheData {
+    lastScan: string;
+    searchPaths: string[];
+    projects: Record<string, CachedProject>;
+}
+/**
+ * Two-tier cache for Docker Compose project metadata.
+ * Uses an in-memory LRU cache (L1) backed by file-based storage (L2).
+ *
+ * @example
+ * ```typescript
+ * const cache = new ComposeProjectCache('.cache/compose-projects', 24*60*60*1000, 50);
+ * await cache.updateProject('host', 'plex', projectData);
+ * const project = await cache.getProject('host', 'plex'); // Fast memory lookup
+ * ```
+ */
+export declare class ComposeProjectCache {
+    private cacheDir;
+    private cacheTtlMs;
+    private memoryCache;
+    /**
+     * Create a new ComposeProjectCache with two-tier caching.
+     *
+     * @param cacheDir - Directory for file-based cache storage
+     * @param cacheTtlMs - Time-to-live for cache entries in milliseconds (default: 24 hours)
+     * @param memoryCacheSize - Maximum number of entries in memory cache (default: 50)
+     */
+    constructor(cacheDir?: string, cacheTtlMs?: number, memoryCacheSize?: number);
+    load(host: string): Promise<CacheData>;
+    save(host: string, data: CacheData): Promise<void>;
+    /**
+     * Retrieve a project from cache (memory first, then file).
+     * Returns undefined if project doesn't exist or is stale.
+     *
+     * @param host - The host identifier
+     * @param projectName - The project name
+     * @returns The cached project or undefined if not found/stale
+     */
+    getProject(host: string, projectName: string): Promise<CachedProject | undefined>;
+    /**
+     * Check if a cache entry is stale based on TTL
+     */
+    private isStale;
+    /**
+     * Update or add a project in both memory and file cache.
+     *
+     * @param host - The host identifier
+     * @param projectName - The project name
+     * @param project - The project data to cache
+     */
+    updateProject(host: string, projectName: string, project: CachedProject): Promise<void>;
+    /**
+     * Remove a project from both memory and file cache.
+     *
+     * @param host - The host identifier
+     * @param projectName - The project name to remove
+     */
+    removeProject(host: string, projectName: string): Promise<void>;
+    /**
+     * Get memory cache statistics for monitoring and debugging.
+     * Provides metrics on cache performance and resource usage.
+     *
+     * @returns Cache statistics including hits, misses, size, and evictions
+     */
+    getCacheStats(): CacheStats;
+    private emptyCache;
+}
+//# sourceMappingURL=compose-cache.d.ts.map

package/dist/services/compose-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-cache.d.ts","sourceRoot":"","sources":["../../src/services/compose-cache.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,UAAU,EAAmC,MAAM,kBAAkB,CAAC;AAEpF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,WAAW,GAAG,MAAM,GAAG,eAAe,CAAC;IACvD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACzC;AAkBD;;;;;;;;;;GAUG;AACH,qBAAa,mBAAmB;IAW5B,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,UAAU;IAXpB,OAAO,CAAC,WAAW,CAAqC;IAExD;;;;;;OAMG;gBAEO,QAAQ,SAA4B,EACpC,UAAU,SAAuB,EACzC,eAAe,SAAK;IAKhB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAwBtC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxD;;;;;;;OAOG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;IAkCvF;;OAEG;IACH,OAAO,CAAC,OAAO;IAMf;;;;;;OAMG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB7F;;;;;OAKG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBrE;;;;;OAKG;IACH,aAAa,IAAI,UAAU;IAI3B,OAAO,CAAC,UAAU;CAOnB"}

package/dist/services/compose-cache.js

@@ -0,0 +1,178 @@
+// src/services/compose-cache.ts
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { validateHostname } from "../utils/path-security.js";
+import { getCurrentTimestamp } from "../utils/time.js";
+import { LRUCacheLayer } from "./cache-layer.js";
+const DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+// Zod schemas for runtime validation of JSON cache files
+const CachedProjectSchema = z.object({
+    path: z.string(),
+    name: z.string(),
+    discoveredFrom: z.enum(["docker-ls", "scan", "user-provided"]),
+    lastSeen: z.string(),
+});
+const CacheDataSchema = z.object({
+    lastScan: z.string(),
+    searchPaths: z.array(z.string()),
+    projects: z.record(z.string(), CachedProjectSchema),
+});
+/**
+ * Two-tier cache for Docker Compose project metadata.
+ * Uses an in-memory LRU cache (L1) backed by file-based storage (L2).
+ *
+ * @example
+ * ```typescript
+ * const cache = new ComposeProjectCache('.cache/compose-projects', 24*60*60*1000, 50);
+ * await cache.updateProject('host', 'plex', projectData);
+ * const project = await cache.getProject('host', 'plex'); // Fast memory lookup
+ * ```
+ */
+export class ComposeProjectCache {
+    cacheDir;
+    cacheTtlMs;
+    memoryCache;
+    /**
+     * Create a new ComposeProjectCache with two-tier caching.
+     *
+     * @param cacheDir - Directory for file-based cache storage
+     * @param cacheTtlMs - Time-to-live for cache entries in milliseconds (default: 24 hours)
+     * @param memoryCacheSize - Maximum number of entries in memory cache (default: 50)
+     */
+    constructor(cacheDir = ".cache/compose-projects", cacheTtlMs = DEFAULT_CACHE_TTL_MS, memoryCacheSize = 50) {
+        this.cacheDir = cacheDir;
+        this.cacheTtlMs = cacheTtlMs;
+        this.memoryCache = new LRUCacheLayer(memoryCacheSize, cacheTtlMs);
+    }
+    async load(host) {
+        // SECURITY: Validate host to prevent path traversal attacks (CWE-22)
+        validateHostname(host);
+        const file = join(this.cacheDir, `${host}.json`);
+        try {
+            const data = await readFile(file, "utf-8");
+            const parsed = JSON.parse(data);
+            // Runtime validation: protect against corrupted cache files
+            return CacheDataSchema.parse(parsed);
+        }
+        catch (error) {
+            // Only return empty cache if file doesn't exist
+            // Re-throw validation errors to catch corrupted cache files
+            if (error instanceof z.ZodError) {
+                throw new Error(`Cache file validation failed for ${host}: ${error.message}`, {
+                    cause: error,
+                });
+            }
+            // File not found or JSON parse error - return empty cache
+            return this.emptyCache();
+        }
+    }
+    async save(host, data) {
+        // SECURITY: Validate host to prevent path traversal attacks (CWE-22)
+        validateHostname(host);
+        await mkdir(this.cacheDir, { recursive: true });
+        const file = join(this.cacheDir, `${host}.json`);
+        const tempFile = join(this.cacheDir, `${host}.json.tmp`);
+        // Atomic write: write to temp file in same directory, then rename
+        // Using same directory ensures rename works across all filesystems
+        await writeFile(tempFile, JSON.stringify(data, null, 2));
+        await rename(tempFile, file);
+    }
+    /**
+     * Retrieve a project from cache (memory first, then file).
+     * Returns undefined if project doesn't exist or is stale.
+     *
+     * @param host - The host identifier
+     * @param projectName - The project name
+     * @returns The cached project or undefined if not found/stale
+     */
+    async getProject(host, projectName) {
+        // SECURITY: Validate host to prevent path traversal attacks (CWE-22)
+        validateHostname(host);
+        const cacheKey = `${host}:${projectName}`;
+        // L1 Cache: Check memory cache first (fast path)
+        const memoryHit = this.memoryCache.get(cacheKey);
+        if (memoryHit) {
+            // Check TTL - return undefined if stale
+            if (this.isStale(memoryHit.lastSeen)) {
+                this.memoryCache.delete(cacheKey);
+                return undefined;
+            }
+            return memoryHit;
+        }
+        // L2 Cache: Fall back to file cache
+        const data = await this.load(host);
+        const project = data.projects[projectName];
+        // Check TTL - return undefined if stale
+        if (project && this.isStale(project.lastSeen)) {
+            return undefined;
+        }
+        // If found in file cache, populate memory cache (cache warming)
+        if (project) {
+            this.memoryCache.set(cacheKey, project);
+        }
+        return project;
+    }
+    /**
+     * Check if a cache entry is stale based on TTL
+     */
+    isStale(lastSeenIso) {
+        const lastSeen = new Date(lastSeenIso).getTime();
+        const now = Date.now();
+        return now - lastSeen > this.cacheTtlMs;
+    }
+    /**
+     * Update or add a project in both memory and file cache.
+     *
+     * @param host - The host identifier
+     * @param projectName - The project name
+     * @param project - The project data to cache
+     */
+    async updateProject(host, projectName, project) {
+        // SECURITY: Validate host to prevent path traversal attacks (CWE-22)
+        validateHostname(host);
+        const cacheKey = `${host}:${projectName}`;
+        // Update file cache (L2) - persistence layer
+        const data = await this.load(host);
+        data.projects[projectName] = project;
+        data.lastScan = getCurrentTimestamp();
+        await this.save(host, data);
+        // Update memory cache (L1) - fast access layer
+        this.memoryCache.set(cacheKey, project);
+    }
+    /**
+     * Remove a project from both memory and file cache.
+     *
+     * @param host - The host identifier
+     * @param projectName - The project name to remove
+     */
+    async removeProject(host, projectName) {
+        // SECURITY: Validate host to prevent path traversal attacks (CWE-22)
+        validateHostname(host);
+        const cacheKey = `${host}:${projectName}`;
+        // Remove from memory cache (L1)
+        this.memoryCache.delete(cacheKey);
+        // Remove from file cache (L2)
+        const data = await this.load(host);
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        delete data.projects[projectName];
+        await this.save(host, data);
+    }
+    /**
+     * Get memory cache statistics for monitoring and debugging.
+     * Provides metrics on cache performance and resource usage.
+     *
+     * @returns Cache statistics including hits, misses, size, and evictions
+     */
+    getCacheStats() {
+        return this.memoryCache.getStats();
+    }
+    emptyCache() {
+        return {
+            lastScan: getCurrentTimestamp(),
+            searchPaths: [],
+            projects: {},
+        };
+    }
+}
+//# sourceMappingURL=compose-cache.js.map

package/dist/services/compose-cache.js.map

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

package/dist/services/compose-discovery.d.ts

@@ -0,0 +1,46 @@
+import type { HostConfig } from "../types.js";
+import type { ComposeProjectCache } from "./compose-cache.js";
+import type { ComposeScanner } from "./compose-scanner.js";
+import type { IComposeProjectLister } from "./interfaces.js";
+export declare class ComposeDiscovery {
+    private projectLister;
+    cache: ComposeProjectCache;
+    private scanner;
+    /**
+     * In-flight filesystem scan promises keyed by host name.
+     * Coalesces concurrent scan requests for the same host into a single scan,
+     * preventing redundant filesystem operations (200-1000ms each).
+     */
+    private inflightScans;
+    constructor(projectLister: IComposeProjectLister, cache: ComposeProjectCache, // Public for cache invalidation in handlers
+    scanner: ComposeScanner);
+    private getSearchPaths;
+    private discoverFromDockerLs;
+    /**
+     * Scan a host's filesystem for compose projects, coalescing concurrent requests.
+     * If a scan is already in flight for this host, returns the existing promise.
+     *
+     * @param host - Host to scan
+     * @returns Array of discovered projects with name and path
+     */
+    private scanHostFilesystem;
+    private discoverFromFilesystem;
+    /**
+     * Resolve compose file path for a project
+     * Strategy:
+     * 1. Check cache (trust it - lazy invalidation at handler level)
+     * 2. Check docker compose ls (running projects) - FAST
+     * 3. Scan filesystem if not found - SLOWER
+     * 4. Error if not found
+     */
+    resolveProjectPath(host: HostConfig, projectName: string): Promise<string>;
+    /**
+     * Warm cache by discovering all projects on a host in the background.
+     * This mitigates cold-start penalty (200-1000ms) on first compose operation.
+     * Call this on server startup or after cache invalidation.
+     *
+     * @param host - Host to warm cache for
+     */
+    warmCache(host: HostConfig): Promise<void>;
+}
+//# sourceMappingURL=compose-discovery.d.ts.map

package/dist/services/compose-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-discovery.d.ts","sourceRoot":"","sources":["../../src/services/compose-discovery.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,KAAK,EAAiB,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAI7D,qBAAa,gBAAgB;IASzB,OAAO,CAAC,aAAa;IACd,KAAK,EAAE,mBAAmB;IACjC,OAAO,CAAC,OAAO;IAVjB;;;;OAIG;IACH,OAAO,CAAC,aAAa,CAAqE;gBAGhF,aAAa,EAAE,qBAAqB,EACrC,KAAK,EAAE,mBAAmB,EAAE,4CAA4C;IACvE,OAAO,EAAE,cAAc;IAGjC,OAAO,CAAC,cAAc;YAuBR,oBAAoB;IA0BlC;;;;;;OAMG;YACW,kBAAkB;YAyClB,sBAAsB;IAoCpC;;;;;;;OAOG;IACG,kBAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA+BhF;;;;;;OAMG;IACG,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CA4DjD"}