synapse-mcp 1.0.0 → 1.0.2

package/dist/services/compose-discovery.js

@@ -0,0 +1,219 @@
+import { DEFAULT_COMPOSE_SCAN_CONCURRENCY } from "../constants.js";
+import { logError } from "../utils/errors.js";
+import { getCurrentTimestamp } from "../utils/time.js";
+const DEFAULT_SEARCH_PATHS = ["/compose", "/mnt/cache/compose", "/mnt/cache/code"];
+export class ComposeDiscovery {
+    projectLister;
+    cache;
+    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).
+     */
+    inflightScans = new Map();
+    constructor(projectLister, cache, // Public for cache invalidation in handlers
+    scanner) {
+        this.projectLister = projectLister;
+        this.cache = cache;
+        this.scanner = scanner;
+    }
+    getSearchPaths(host, cachedPaths) {
+        const paths = new Set();
+        // Add default paths
+        for (const p of DEFAULT_SEARCH_PATHS) {
+            paths.add(p);
+        }
+        // Add cached paths
+        for (const p of cachedPaths) {
+            paths.add(p);
+        }
+        // Add user-configured paths
+        if (host.composeSearchPaths) {
+            for (const p of host.composeSearchPaths) {
+                paths.add(p);
+            }
+        }
+        return Array.from(paths);
+    }
+    async discoverFromDockerLs(host, projectName) {
+        try {
+            const projects = await this.projectLister.listComposeProjects(host);
+            const found = projects.find((p) => p.name === projectName);
+            if (found && found.configFiles.length > 0) {
+                return {
+                    path: found.configFiles[0],
+                    name: projectName,
+                    discoveredFrom: "docker-ls",
+                    lastSeen: getCurrentTimestamp(),
+                };
+            }
+        }
+        catch (error) {
+            logError(error, {
+                operation: "discoverFromDockerLs",
+                metadata: { host: host.name, project: projectName },
+            });
+        }
+        return null;
+    }
+    /**
+     * 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
+     */
+    async scanHostFilesystem(host) {
+        const existing = this.inflightScans.get(host.name);
+        if (existing) {
+            return existing;
+        }
+        const scanPromise = (async () => {
+            try {
+                const cacheData = await this.cache.load(host.name);
+                const searchPaths = this.getSearchPaths(host, cacheData.searchPaths);
+                const hostWithSearchPaths = {
+                    ...host,
+                    composeSearchPaths: searchPaths,
+                };
+                const files = await this.scanner.findComposeFiles(hostWithSearchPaths);
+                const nameMap = await this.scanner.batchParseComposeNames(host, files, DEFAULT_COMPOSE_SCAN_CONCURRENCY);
+                return files.map((file) => {
+                    const dirName = this.scanner.extractProjectName(file);
+                    const explicitName = nameMap.get(file);
+                    const name = explicitName ?? dirName;
+                    return { name, path: file };
+                });
+            }
+            finally {
+                this.inflightScans.delete(host.name);
+            }
+        })();
+        this.inflightScans.set(host.name, scanPromise);
+        return scanPromise;
+    }
+    async discoverFromFilesystem(host, projectName) {
+        try {
+            const projects = await this.scanHostFilesystem(host);
+            // Cache all discovered projects to avoid future scans
+            for (const project of projects) {
+                await this.cache.updateProject(host.name, project.name, {
+                    path: project.path,
+                    name: project.name,
+                    discoveredFrom: "scan",
+                    lastSeen: getCurrentTimestamp(),
+                });
+            }
+            const found = projects.find((p) => p.name === projectName);
+            if (found) {
+                return {
+                    path: found.path,
+                    name: found.name,
+                    discoveredFrom: "scan",
+                    lastSeen: getCurrentTimestamp(),
+                };
+            }
+        }
+        catch (error) {
+            logError(error, {
+                operation: "discoverFromFilesystem",
+                metadata: { host: host.name, project: projectName },
+            });
+        }
+        return null;
+    }
+    /**
+     * 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
+     */
+    async resolveProjectPath(host, projectName) {
+        // Step 1: Check cache (no validation - lazy invalidation)
+        const cached = await this.cache.getProject(host.name, projectName);
+        if (cached) {
+            return cached.path;
+        }
+        // Step 2: Try docker ls first (fast, authoritative for running projects)
+        const dockerLsResult = await this.discoverFromDockerLs(host, projectName);
+        if (dockerLsResult) {
+            await this.cache.updateProject(host.name, projectName, dockerLsResult);
+            return dockerLsResult.path;
+        }
+        // Step 3: Fallback to filesystem scan (slower, but finds stopped projects)
+        const scanResult = await this.discoverFromFilesystem(host, projectName);
+        if (scanResult) {
+            await this.cache.updateProject(host.name, projectName, scanResult);
+            return scanResult.path;
+        }
+        // Step 4: Not found
+        const cacheData = await this.cache.load(host.name);
+        const searchPaths = cacheData.searchPaths.length > 0 ? cacheData.searchPaths : DEFAULT_SEARCH_PATHS;
+        throw new Error(`Project '${projectName}' not found on host '${host.name}'\nSearched locations: ${searchPaths.join(", ")}\nTip: Provide compose_file parameter if project is in a different location`);
+    }
+    /**
+     * 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
+     */
+    async warmCache(host) {
+        // Phase 1: Discover from docker ls (fast, finds running projects)
+        try {
+            const runningProjects = await this.projectLister.listComposeProjects(host);
+            // Cache all running projects
+            for (const project of runningProjects) {
+                if (project.configFiles.length > 0) {
+                    await this.cache.updateProject(host.name, project.name, {
+                        path: project.configFiles[0],
+                        name: project.name,
+                        discoveredFrom: "docker-ls",
+                        lastSeen: getCurrentTimestamp(),
+                    });
+                }
+            }
+        }
+        catch (error) {
+            // Non-fatal: docker-ls failure should not prevent filesystem scan
+            logError(error, {
+                operation: "warmCache:docker-ls",
+                metadata: { host: host.name },
+            });
+        }
+        // Phase 2: Discover from filesystem (slower, finds stopped projects)
+        try {
+            const cacheData = await this.cache.load(host.name);
+            const searchPaths = this.getSearchPaths(host, cacheData.searchPaths);
+            const hostWithSearchPaths = { ...host, composeSearchPaths: searchPaths };
+            const files = await this.scanner.findComposeFiles(hostWithSearchPaths);
+            const nameMap = await this.scanner.batchParseComposeNames(host, files, DEFAULT_COMPOSE_SCAN_CONCURRENCY);
+            const projects = files.map((file) => {
+                const dirName = this.scanner.extractProjectName(file);
+                const explicitName = nameMap.get(file);
+                const name = explicitName ?? dirName;
+                return { name, path: file };
+            });
+            // Cache all discovered projects
+            for (const project of projects) {
+                await this.cache.updateProject(host.name, project.name, {
+                    path: project.path,
+                    name: project.name,
+                    discoveredFrom: "scan",
+                    lastSeen: getCurrentTimestamp(),
+                });
+            }
+        }
+        catch (error) {
+            // Non-fatal: filesystem scan failure is best-effort
+            logError(error, {
+                operation: "warmCache:filesystem-scan",
+                metadata: { host: host.name },
+            });
+        }
+    }
+}
+//# sourceMappingURL=compose-discovery.js.map

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

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

package/dist/services/compose-project-lister.d.ts

@@ -0,0 +1,27 @@
+import type { ComposeProject, HostConfig } from "../types.js";
+import type { IComposeProjectLister, ILocalExecutorService, ISSHService } from "./interfaces.js";
+/**
+ * Standalone service for listing Docker Compose projects on hosts.
+ *
+ * Extracted from ComposeService to break the circular dependency:
+ *   ComposeService <-> ComposeDiscovery
+ *
+ * Before: ComposeService implemented both IComposeService and IComposeProjectLister,
+ * requiring setter injection to wire ComposeDiscovery as its path resolver.
+ *
+ * After: ComposeProjectLister implements IComposeProjectLister independently,
+ * allowing a clean dependency chain:
+ *   ComposeProjectLister -> ComposeDiscovery -> ComposeService
+ *   (no cycle, no setter injection)
+ */
+export declare class ComposeProjectLister implements IComposeProjectLister {
+    private sshService;
+    private localExecutor;
+    constructor(sshService: ISSHService, localExecutor: ILocalExecutorService);
+    /**
+     * List all compose projects on a host (local or remote)
+     * via `docker compose ls --format json`.
+     */
+    listComposeProjects(host: HostConfig): Promise<ComposeProject[]>;
+}
+//# sourceMappingURL=compose-project-lister.d.ts.map

package/dist/services/compose-project-lister.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-project-lister.d.ts","sourceRoot":"","sources":["../../src/services/compose-project-lister.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI9D,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGjG;;;;;;;;;;;;;GAaG;AACH,qBAAa,oBAAqB,YAAW,qBAAqB;IAE9D,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,aAAa;gBADb,UAAU,EAAE,WAAW,EACvB,aAAa,EAAE,qBAAqB;IAG9C;;;OAGG;IACG,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;CA0DvE"}

package/dist/services/compose-project-lister.js

@@ -0,0 +1,71 @@
+import { ComposeOperationError } from "../utils/errors.js";
+import { isLocalHost } from "../utils/host-utils.js";
+import { parseComposeStatus } from "./compose.js";
+import { validateHostForSsh } from "./ssh.js";
+/**
+ * Standalone service for listing Docker Compose projects on hosts.
+ *
+ * Extracted from ComposeService to break the circular dependency:
+ *   ComposeService <-> ComposeDiscovery
+ *
+ * Before: ComposeService implemented both IComposeService and IComposeProjectLister,
+ * requiring setter injection to wire ComposeDiscovery as its path resolver.
+ *
+ * After: ComposeProjectLister implements IComposeProjectLister independently,
+ * allowing a clean dependency chain:
+ *   ComposeProjectLister -> ComposeDiscovery -> ComposeService
+ *   (no cycle, no setter injection)
+ */
+export class ComposeProjectLister {
+    sshService;
+    localExecutor;
+    constructor(sshService, localExecutor) {
+        this.sshService = sshService;
+        this.localExecutor = localExecutor;
+    }
+    /**
+     * List all compose projects on a host (local or remote)
+     * via `docker compose ls --format json`.
+     */
+    async listComposeProjects(host) {
+        const args = ["--format", "json"];
+        try {
+            let stdout;
+            if (isLocalHost(host)) {
+                stdout = await this.localExecutor.executeLocalCommand("docker", ["compose", "ls", ...args], { timeoutMs: 15000 });
+            }
+            else {
+                validateHostForSsh(host);
+                const command = `docker compose ls ${args.join(" ")}`;
+                stdout = await this.sshService.executeSSHCommand(host, command, [], {
+                    timeoutMs: 15000,
+                });
+            }
+            if (!stdout.trim()) {
+                return [];
+            }
+            const projects = JSON.parse(stdout);
+            return projects.map((p) => {
+                if (!p.ConfigFiles) {
+                    return {
+                        name: p.Name,
+                        status: parseComposeStatus(p.Status),
+                        configFiles: [],
+                        services: [],
+                    };
+                }
+                return {
+                    name: p.Name,
+                    status: parseComposeStatus(p.Status),
+                    configFiles: p.ConfigFiles.split(",").map((f) => f.trim()),
+                    services: [],
+                };
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : "Unknown error";
+            throw new ComposeOperationError(`Failed to list compose projects: ${detail}`, host.name, "*", "ls", error);
+        }
+    }
+}
+//# sourceMappingURL=compose-project-lister.js.map

package/dist/services/compose-project-lister.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-project-lister.js","sourceRoot":"","sources":["../../src/services/compose-project-lister.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE9C;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,oBAAoB;IAErB;IACA;IAFV,YACU,UAAuB,EACvB,aAAoC;QADpC,eAAU,GAAV,UAAU,CAAa;QACvB,kBAAa,GAAb,aAAa,CAAuB;IAC3C,CAAC;IAEJ;;;OAGG;IACH,KAAK,CAAC,mBAAmB,CAAC,IAAgB;QACxC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAElC,IAAI,CAAC;YACH,IAAI,MAAc,CAAC;YAEnB,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;gBACtB,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,mBAAmB,CACnD,QAAQ,EACR,CAAC,SAAS,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,EAC1B,EAAE,SAAS,EAAE,KAAK,EAAE,CACrB,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,kBAAkB,CAAC,IAAI,CAAC,CAAC;gBACzB,MAAM,OAAO,GAAG,qBAAqB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBACtD,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;oBAClE,SAAS,EAAE,KAAK;iBACjB,CAAC,CAAC;YACL,CAAC;YAED,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;gBACnB,OAAO,EAAE,CAAC;YACZ,CAAC;YAED,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAIhC,CAAC;YAEH,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBACxB,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;oBACnB,OAAO;wBACL,IAAI,EAAE,CAAC,CAAC,IAAI;wBACZ,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,MAAM,CAAC;wBACpC,WAAW,EAAE,EAAE;wBACf,QAAQ,EAAE,EAAE;qBACb,CAAC;gBACJ,CAAC;gBAED,OAAO;oBACL,IAAI,EAAE,CAAC,CAAC,IAAI;oBACZ,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,MAAM,CAAC;oBACpC,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;oBAC1D,QAAQ,EAAE,EAAE;iBACb,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;YACxE,MAAM,IAAI,qBAAqB,CAC7B,oCAAoC,MAAM,EAAE,EAC5C,IAAI,CAAC,IAAI,EACT,GAAG,EACH,IAAI,EACJ,KAAK,CACN,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

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

@@ -0,0 +1,63 @@
+import type { HostConfig } from "../types.js";
+import type { ILocalExecutorService, ISSHService } from "./interfaces.js";
+/**
+ * Service for scanning filesystems to find Docker Compose files.
+ * Supports both remote (SSH) and local execution.
+ */
+export declare class ComposeScanner {
+    private readonly sshService;
+    private readonly localExecutor;
+    constructor(sshService: ISSHService, localExecutor: ILocalExecutorService);
+    /**
+     * Find all compose files in configured search paths.
+     * Uses SSH for remote hosts, local execution for localhost.
+     *
+     * @param host - Host configuration with optional composeSearchPaths
+     * @returns Array of absolute paths to compose files
+     */
+    findComposeFiles(host: HostConfig): Promise<string[]>;
+    /**
+     * Extract project name from compose file path (parent directory name).
+     *
+     * @param filePath - Absolute path to compose file
+     * @returns Parent directory name, or empty string if at root
+     */
+    extractProjectName(filePath: string): string;
+    /**
+     * Parse compose file to extract explicit 'name:' field.
+     * Returns null if parsing fails or no name field exists.
+     *
+     * SECURITY: Uses args array to prevent shell injection when reading files.
+     *
+     * @param host - Host configuration
+     * @param filePath - Absolute path to compose file
+     * @returns Explicit project name from 'name:' field, or null
+     */
+    parseComposeName(host: HostConfig, filePath: string): Promise<string | null>;
+    /**
+     * Parse multiple compose files in chunks and read each chunk in parallel.
+     * Avoids shell string concatenation by issuing one cat command per file.
+     *
+     * @param host - Host configuration where files are located
+     * @param filePaths - Array of absolute paths to compose files
+     * @param concurrency - Maximum concurrent SSH connections (default from constants)
+     * @returns Map of file path to project name (null if parse failed)
+     */
+    batchParseComposeNames(host: HostConfig, filePaths: string[], concurrency?: number): Promise<Map<string, string | null>>;
+    /**
+     * Read and parse a batch of compose files using parallel cat commands.
+     *
+     * @param host - Host configuration
+     * @param filePaths - Batch of file paths to read
+     * @returns Map of file path to parsed project name (null if parse failed)
+     */
+    private batchReadAndParse;
+    /**
+     * Check if host is localhost (avoids SSH overhead for local operations).
+     *
+     * @param host - Host configuration
+     * @returns true if host is localhost/127.0.0.1
+     */
+    private isLocalHost;
+}
+//# sourceMappingURL=compose-scanner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compose-scanner.d.ts","sourceRoot":"","sources":["../../src/services/compose-scanner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAsC1E;;;GAGG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,aAAa;gBADb,UAAU,EAAE,WAAW,EACvB,aAAa,EAAE,qBAAqB;IAGvD;;;;;;OAMG;IACG,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAwC3D;;;;;OAKG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAS5C;;;;;;;;;OASG;IACG,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA8BlF;;;;;;;;OAQG;IACG,sBAAsB,CAC1B,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,EAAE,EACnB,WAAW,GAAE,MAAyC,GACrD,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IAyCtC;;;;;;OAMG;YACW,iBAAiB;IAwE/B;;;;;OAKG;IACH,OAAO,CAAC,WAAW;CAIpB"}

package/dist/services/compose-scanner.js

@@ -0,0 +1,253 @@
+import pLimit from "p-limit";
+import YAML from "yaml";
+import { DEFAULT_COMPOSE_SCAN_CONCURRENCY } from "../constants.js";
+/**
+ * Default search paths for compose files if not specified in host config
+ */
+const DEFAULT_SEARCH_PATHS = ["/compose", "/mnt/cache/compose", "/mnt/cache/code"];
+/**
+ * Maximum depth to search for compose files
+ */
+const MAX_SCAN_DEPTH = 3;
+/**
+ * Timeout for remote find operations (ms)
+ */
+const FIND_TIMEOUT_MS = 60_000;
+/**
+ * Timeout for reading individual compose files (ms)
+ */
+const CAT_TIMEOUT_MS = 10_000;
+/**
+ * Maximum number of files to read in a single batched cat command.
+ * Keeps argument lists and output size manageable.
+ */
+const BATCH_CAT_CHUNK_SIZE = 20;
+/**
+ * Compose file patterns to search for
+ */
+const COMPOSE_FILE_PATTERNS = [
+    "docker-compose.yml",
+    "docker-compose.yaml",
+    "compose.yml",
+    "compose.yaml",
+];
+/**
+ * Service for scanning filesystems to find Docker Compose files.
+ * Supports both remote (SSH) and local execution.
+ */
+export class ComposeScanner {
+    sshService;
+    localExecutor;
+    constructor(sshService, localExecutor) {
+        this.sshService = sshService;
+        this.localExecutor = localExecutor;
+    }
+    /**
+     * Find all compose files in configured search paths.
+     * Uses SSH for remote hosts, local execution for localhost.
+     *
+     * @param host - Host configuration with optional composeSearchPaths
+     * @returns Array of absolute paths to compose files
+     */
+    async findComposeFiles(host) {
+        const searchPaths = host.composeSearchPaths ?? DEFAULT_SEARCH_PATHS;
+        const isLocal = this.isLocalHost(host);
+        // Build find command args to avoid shell injection
+        // find /path1 /path2 -maxdepth 3 -type f \( -name "docker-compose.yml" -o -name "compose.yaml" ... \) -print
+        const args = [...searchPaths, "-maxdepth", MAX_SCAN_DEPTH.toString(), "-type", "f", "("];
+        // Add each pattern with -o (OR) between them
+        for (let i = 0; i < COMPOSE_FILE_PATTERNS.length; i++) {
+            if (i > 0) {
+                args.push("-o");
+            }
+            const pattern = COMPOSE_FILE_PATTERNS[i];
+            if (pattern) {
+                args.push("-name", pattern);
+            }
+        }
+        args.push(")", "-print");
+        try {
+            const output = isLocal
+                ? await this.localExecutor.executeLocalCommand("find", args, { timeoutMs: FIND_TIMEOUT_MS })
+                : await this.sshService.executeSSHCommand(host, "find", args, {
+                    timeoutMs: FIND_TIMEOUT_MS,
+                });
+            // Split output by newlines, filter empty lines, and deduplicate
+            const allFiles = output
+                .split("\n")
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0);
+            return Array.from(new Set(allFiles));
+        }
+        catch (_error) {
+            return [];
+        }
+    }
+    /**
+     * Extract project name from compose file path (parent directory name).
+     *
+     * @param filePath - Absolute path to compose file
+     * @returns Parent directory name, or empty string if at root
+     */
+    extractProjectName(filePath) {
+        const parts = filePath.split("/").filter((p) => p.length > 0);
+        // Return parent directory name (last directory before filename)
+        if (parts.length < 2) {
+            return "";
+        }
+        return parts[parts.length - 2] ?? "";
+    }
+    /**
+     * Parse compose file to extract explicit 'name:' field.
+     * Returns null if parsing fails or no name field exists.
+     *
+     * SECURITY: Uses args array to prevent shell injection when reading files.
+     *
+     * @param host - Host configuration
+     * @param filePath - Absolute path to compose file
+     * @returns Explicit project name from 'name:' field, or null
+     */
+    async parseComposeName(host, filePath) {
+        const isLocal = this.isLocalHost(host);
+        try {
+            // Read file contents using cat command with args array
+            const content = isLocal
+                ? await this.localExecutor.executeLocalCommand("cat", [filePath], {
+                    timeoutMs: CAT_TIMEOUT_MS,
+                })
+                : await this.sshService.executeSSHCommand(host, "cat", [filePath], {
+                    timeoutMs: CAT_TIMEOUT_MS,
+                });
+            // Parse YAML and extract name field
+            const parsed = YAML.parse(content);
+            if (parsed && typeof parsed === "object" && "name" in parsed) {
+                const name = parsed.name;
+                if (typeof name === "string" && name.length > 0) {
+                    return name;
+                }
+            }
+            return null;
+        }
+        catch (_error) {
+            // Alternative: Log errors for debugging while still returning null.
+            return null;
+        }
+    }
+    /**
+     * Parse multiple compose files in chunks and read each chunk in parallel.
+     * Avoids shell string concatenation by issuing one cat command per file.
+     *
+     * @param host - Host configuration where files are located
+     * @param filePaths - Array of absolute paths to compose files
+     * @param concurrency - Maximum concurrent SSH connections (default from constants)
+     * @returns Map of file path to project name (null if parse failed)
+     */
+    async batchParseComposeNames(host, filePaths, concurrency = DEFAULT_COMPOSE_SCAN_CONCURRENCY) {
+        const results = new Map();
+        if (filePaths.length === 0) {
+            return results;
+        }
+        // Split file paths into chunks for batched reading
+        const chunks = [];
+        for (let i = 0; i < filePaths.length; i += BATCH_CAT_CHUNK_SIZE) {
+            chunks.push(filePaths.slice(i, i + BATCH_CAT_CHUNK_SIZE));
+        }
+        // Process chunks in parallel with concurrency control
+        const limit = pLimit(concurrency);
+        const chunkPromises = chunks.map((chunk) => limit(async () => this.batchReadAndParse(host, chunk)));
+        const chunkResults = await Promise.allSettled(chunkPromises);
+        // Merge results from all chunks
+        for (const settled of chunkResults) {
+            if (settled.status === "fulfilled") {
+                for (const [path, name] of settled.value) {
+                    results.set(path, name);
+                }
+            }
+        }
+        // Ensure every requested path has an entry
+        for (const filePath of filePaths) {
+            if (!results.has(filePath)) {
+                results.set(filePath, null);
+            }
+        }
+        return results;
+    }
+    /**
+     * Read and parse a batch of compose files using parallel cat commands.
+     *
+     * @param host - Host configuration
+     * @param filePaths - Batch of file paths to read
+     * @returns Map of file path to parsed project name (null if parse failed)
+     */
+    async batchReadAndParse(host, filePaths) {
+        const results = new Map();
+        const isLocal = this.isLocalHost(host);
+        if (filePaths.length === 1) {
+            // Single file — use simple cat (no delimiter overhead)
+            const name = await this.parseComposeName(host, filePaths[0]);
+            results.set(filePaths[0], name);
+            return results;
+        }
+        try {
+            const contents = await Promise.all(filePaths.map((filePath) => isLocal
+                ? this.localExecutor.executeLocalCommand("cat", [filePath], {
+                    timeoutMs: CAT_TIMEOUT_MS,
+                })
+                : this.sshService.executeSSHCommand(host, "cat", [filePath], {
+                    timeoutMs: CAT_TIMEOUT_MS,
+                })));
+            for (let i = 0; i < filePaths.length; i++) {
+                const content = contents[i]?.trim();
+                const filePath = filePaths[i];
+                if (!content) {
+                    results.set(filePath, null);
+                    continue;
+                }
+                try {
+                    const parsed = YAML.parse(content);
+                    if (parsed && typeof parsed === "object" && "name" in parsed) {
+                        const name = parsed.name;
+                        if (typeof name === "string" && name.length > 0) {
+                            results.set(filePath, name);
+                            continue;
+                        }
+                    }
+                    results.set(filePath, null);
+                }
+                catch {
+                    results.set(filePath, null);
+                }
+            }
+        }
+        catch {
+            // Batch read failed — fall back to individual reads
+            const individualPromises = filePaths.map(async (filePath) => {
+                try {
+                    const name = await this.parseComposeName(host, filePath);
+                    return { path: filePath, name };
+                }
+                catch {
+                    return { path: filePath, name: null };
+                }
+            });
+            const settled = await Promise.allSettled(individualPromises);
+            for (const result of settled) {
+                if (result.status === "fulfilled") {
+                    results.set(result.value.path, result.value.name);
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Check if host is localhost (avoids SSH overhead for local operations).
+     *
+     * @param host - Host configuration
+     * @returns true if host is localhost/127.0.0.1
+     */
+    isLocalHost(host) {
+        const hostname = host.host.toLowerCase();
+        return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+    }
+}
+//# sourceMappingURL=compose-scanner.js.map