synapse-mcp 1.0.0 → 1.0.2

package/dist/utils/errors.js

@@ -1,3 +1,4 @@
+import { getCurrentTimestamp } from "./time.js";
 /**
  * Error classes for preserving context in error chains
  *
@@ -13,13 +14,11 @@
 export class HostOperationError extends Error {
     hostName;
     operation;
-    cause;
     constructor(message, hostName, operation, cause) {
         const fullMessage = `[Host: ${hostName}] [Op: ${operation}] ${message}`;
-        super(fullMessage);
+        super(fullMessage, { cause });
         this.hostName = hostName;
         this.operation = operation;
-        this.cause = cause;
         this.name = "HostOperationError";
         // Preserve original error cause for debugging
         if (cause instanceof Error) {
@@ -36,23 +35,21 @@ export class SSHCommandError extends Error {
     exitCode;
     stderr;
     stdout;
-    cause;
     constructor(message, hostName, command, exitCode, stderr, stdout, cause) {
         const fullMessage = [
             `[SSH] [Host: ${hostName}] ${message}`,
             `Command: ${command}`,
             exitCode !== undefined ? `Exit code: ${exitCode}` : null,
-            stderr ? `Stderr: ${stderr}` : null
+            stderr ? `Stderr: ${stderr}` : null,
         ]
             .filter(Boolean)
             .join("\n");
-        super(fullMessage);
+        super(fullMessage, { cause });
         this.hostName = hostName;
         this.command = command;
         this.exitCode = exitCode;
         this.stderr = stderr;
         this.stdout = stdout;
-        this.cause = cause;
         this.name = "SSHCommandError";
         if (cause instanceof Error) {
             this.stack = `${this.stack}\nCaused by: ${cause.stack}`;
@@ -66,20 +63,102 @@ export class ComposeOperationError extends Error {
     hostName;
     project;
     action;
-    cause;
     constructor(message, hostName, project, action, cause) {
         const fullMessage = `[Compose] [Host: ${hostName}] [Project: ${project}] [Action: ${action}] ${message}`;
-        super(fullMessage);
+        super(fullMessage, { cause });
         this.hostName = hostName;
         this.project = project;
         this.action = action;
-        this.cause = cause;
         this.name = "ComposeOperationError";
         if (cause instanceof Error) {
             this.stack = `${this.stack}\nCaused by: ${cause.stack}`;
         }
     }
 }
+/**
+ * Validation error for input schema failures
+ */
+export class ValidationError extends Error {
+    handlerName;
+    issues;
+    constructor(message, handlerName, issues, cause) {
+        const fullMessage = `[Validation] [Handler: ${handlerName}] ${message}\nIssues: ${issues.join(", ")}`;
+        super(fullMessage, { cause });
+        this.handlerName = handlerName;
+        this.issues = issues;
+        this.name = "ValidationError";
+        if (cause instanceof Error) {
+            this.stack = `${this.stack}\nCaused by: ${cause.stack}`;
+        }
+    }
+}
+/**
+ * Fields that may contain sensitive operational details and should be redacted in logs
+ *
+ * SECURITY (CWE-532): Redact fields that could contain credentials or secrets.
+ * Operational identifiers (host, container_id, project) are intentionally NOT redacted
+ * because they are needed for debugging and do not contain secrets.
+ */
+const SENSITIVE_PARAM_FIELDS = new Set([
+    // Command execution
+    "command", // Shell commands may contain credentials or secrets
+    "args", // Command arguments
+    // File system paths
+    "path", // File paths may reveal system structure
+    "target", // File/directory targets
+    "source", // Source paths
+    "destination", // Destination paths
+    "compose_file", // Compose file paths reveal infrastructure layout
+    // Search/filter patterns
+    "grep", // Search patterns may contain sensitive data
+    "label_filter", // Docker labels may contain internal info
+    "name_filter", // Container/image names may be sensitive
+    // Environment
+    "env", // Environment variables (if we add this feature)
+]);
+/**
+ * Sanitize params for safe logging by redacting potentially sensitive fields
+ *
+ * Preserves safe operational fields (action, subaction, host, response_format, etc.)
+ * while redacting fields that may contain sensitive data (paths, commands, filters).
+ *
+ * @param params - Parameters to sanitize
+ * @returns Sanitized copy of params with sensitive fields redacted
+ *
+ * @example
+ * sanitizeParams({
+ *   action: 'scout',
+ *   command: 'cat /etc/passwd',
+ *   host: 'web-01',
+ *   path: '/etc/secrets'
+ * })
+ * // Returns: { action: 'scout', command: '[REDACTED]', host: 'web-01', path: '[REDACTED]' }
+ */
+export function sanitizeParams(params) {
+    // Handle non-object types
+    if (typeof params !== "object" || params === null) {
+        return params;
+    }
+    // Handle arrays (unlikely but defensive)
+    if (Array.isArray(params)) {
+        return "[REDACTED]";
+    }
+    // Sanitize object fields
+    const sanitized = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (SENSITIVE_PARAM_FIELDS.has(key)) {
+            sanitized[key] = "[REDACTED]";
+        }
+        else if (typeof value === "object" && value !== null) {
+            // Nested objects are redacted entirely (avoiding deep traversal)
+            sanitized[key] = "[REDACTED]";
+        }
+        else {
+            sanitized[key] = value;
+        }
+    }
+    return sanitized;
+}
 /**
  * Log error with structured context
  *
@@ -90,7 +169,7 @@ export class ComposeOperationError extends Error {
  * @param context - Additional context information
  */
 export function logError(error, context) {
-    const timestamp = new Date().toISOString();
+    const timestamp = getCurrentTimestamp();
     const parts = [`[${timestamp}]`];
     if (context?.requestId) {
         parts.push(`[Request: ${context.requestId}]`);
@@ -120,7 +199,7 @@ export function logError(error, context) {
             console.error(error.stack);
         }
         if (context?.metadata) {
-            console.error("Metadata:", JSON.stringify(context.metadata, null, 2));
+            console.error("Metadata:", JSON.stringify(context.metadata));
         }
     }
     else {

package/dist/utils/errors.js.map

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

package/dist/utils/help-handler.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared help handling for flux and scout tools
+ * Extracts 100% duplicated help logic from flux.ts and scout.ts
+ */
+import type { ZodType } from "zod";
+/**
+ * Help action input shape
+ */
+export interface HelpInput {
+    action: "help";
+    topic?: string;
+    format?: "markdown" | "json";
+}
+/**
+ * Handle help action for any schema
+ * Consolidates identical logic from flux.ts:29-37 and scout.ts:32-40
+ *
+ * @param input - Help input with optional topic and format
+ * @param schema - Zod schema to generate help from
+ * @returns Formatted help string (markdown or JSON)
+ */
+export declare function handleHelpAction(input: HelpInput, schema: ZodType): string;
+//# sourceMappingURL=help-handler.d.ts.map

package/dist/utils/help-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-handler.d.ts","sourceRoot":"","sources":["../../src/utils/help-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAGnC;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAM1E"}

package/dist/utils/help-handler.js

@@ -0,0 +1,21 @@
+/**
+ * Shared help handling for flux and scout tools
+ * Extracts 100% duplicated help logic from flux.ts and scout.ts
+ */
+import { formatHelpJson, formatHelpMarkdown, generateHelp } from "./help.js";
+/**
+ * Handle help action for any schema
+ * Consolidates identical logic from flux.ts:29-37 and scout.ts:32-40
+ *
+ * @param input - Help input with optional topic and format
+ * @param schema - Zod schema to generate help from
+ * @returns Formatted help string (markdown or JSON)
+ */
+export function handleHelpAction(input, schema) {
+    const entries = generateHelp(schema, input.topic);
+    if (input.format === "json") {
+        return formatHelpJson(entries);
+    }
+    return formatHelpMarkdown(entries);
+}
+//# sourceMappingURL=help-handler.js.map

package/dist/utils/help-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-handler.js","sourceRoot":"","sources":["../../src/utils/help-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAW7E;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAgB,EAAE,MAAe;IAChE,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAClD,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC5B,OAAO,cAAc,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC"}

package/dist/utils/help.d.ts

@@ -11,7 +11,7 @@
  * 2. Check Zod changelog for changes to internal structure
  * 3. Update this module if internal structure changes
  */
-import { z } from "zod";
+import type { z } from "zod";
 export interface HelpEntry {
     discriminator: string;
     description: string;

package/dist/utils/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/utils/help.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,WAAW,SAAS;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,OAAO,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,OAAO,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC,CAAC;CACJ;AAyLD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,CAwC9E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,CA8B/D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,CAQ3D"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/utils/help.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,MAAM,WAAW,SAAS;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,OAAO,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,KAAK,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,OAAO,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC,CAAC;CACJ;AAkOD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,CA0C9E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,CA8B/D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,CAQ3D"}

package/dist/utils/help.js

@@ -12,17 +12,28 @@
  * 3. Update this module if internal structure changes
  */
 /**
- * Safely access _def from a Zod schema
+ * Safely accesses the internal _def property from a Zod schema.
+ *
+ * NOTE: Uses Zod internal API (_def) which is not part of the public interface.
+ * This may break on Zod version upgrades.
+ *
+ * @param schema - Zod schema to extract internal definition from
+ * @returns Internal definition object with type, options, values, etc.
  */
 function getDef(schema) {
     return schema._def ?? {};
 }
 /**
- * Unwrap z.preprocess wrapper to access inner discriminated union schema
+ * Unwraps z.preprocess wrapper to access inner discriminated union schema.
  *
  * In Zod 4.x, z.preprocess() creates a pipe with:
  * - _def.type === 'pipe'
  * - _def.out containing the inner schema
+ *
+ * In Zod 3.x, preprocessed schemas have _def.innerType instead.
+ *
+ * @param schema - Potentially wrapped Zod schema
+ * @returns Unwrapped inner schema or original schema if not wrapped
  */
 function unwrapSchema(schema) {
     const def = getDef(schema);
@@ -37,9 +48,14 @@ function unwrapSchema(schema) {
     return schema;
 }
 /**
- * Get the base type name from a potentially wrapped Zod schema
+ * Gets the base type name from a potentially wrapped Zod schema.
  *
- * Handles default(), optional(), nullable() wrapping to get the underlying type.
+ * Handles default(), optional(), nullable() wrapping to extract the underlying type.
+ * For union types, returns a pipe-delimited string of all type options.
+ * For enum types, returns quoted values joined by pipes.
+ *
+ * @param schema - Zod schema to extract type name from
+ * @returns Type name string (e.g., "string", "number", "string | number", '"active" | "inactive"')
  */
 function getBaseTypeName(schema) {
     const def = getDef(schema);
@@ -64,7 +80,12 @@ function getBaseTypeName(schema) {
     return def.type ?? "unknown";
 }
 /**
- * Get default value from a schema if present
+ * Extracts the default value from a Zod schema if present.
+ *
+ * Handles both Zod 3.x (defaultValue as value) and Zod 4.x (defaultValue as getter function).
+ *
+ * @param schema - Zod schema to extract default value from
+ * @returns Default value if schema is wrapped with .default(), undefined otherwise
  */
 function getDefaultValue(schema) {
     const def = getDef(schema);
@@ -73,14 +94,19 @@ function getDefaultValue(schema) {
             // defaultValue is a getter function in Zod 4.x
             return typeof def.defaultValue === "function" ? def.defaultValue() : def.defaultValue;
         }
-        catch {
+        catch (_error) {
             return undefined;
         }
     }
     return undefined;
 }
 /**
- * Get options from a discriminated union schema
+ * Extracts options array from a discriminated union or union schema.
+ *
+ * Tries direct property access first (Zod 4.x), then falls back to _def.options.
+ *
+ * @param schema - Zod discriminated union or union schema
+ * @returns Array of schema options, or undefined if not a union type
  */
 function getOptions(schema) {
     // Try direct access (Zod 4.x)
@@ -93,16 +119,31 @@ function getOptions(schema) {
     return def.options;
 }
 /**
- * Check if a schema is a nested discriminated union (has options but no shape)
+ * Checks if a schema is a nested discriminated union (has options but no shape).
+ *
+ * Used to detect nested union structures like zfs or logs actions in Scout schema,
+ * where the union contains another discriminated union rather than object schemas.
+ *
+ * @param schema - Zod schema to check for nested union structure
+ * @returns true if schema has options array but no shape property
  */
 function isNestedDiscriminatedUnion(schema) {
     const def = getDef(schema);
     const hasOptions = !!getOptions(schema);
     const hasShape = !!schema.shape;
-    return hasOptions && !hasShape && (def.type === 'discriminatedUnion' || def.type === 'union');
+    return hasOptions && !hasShape && (def.type === "discriminatedUnion" || def.type === "union");
 }
 /**
- * Extract help entries from a single ZodObject schema
+ * Extracts help entry from a single ZodObject schema.
+ *
+ * Parses the schema's shape to identify:
+ * - Discriminator values (literal fields like 'action' or 'subaction')
+ * - Parameters (all non-discriminator fields with types, descriptions, defaults)
+ * - Schema description
+ *
+ * @param option - ZodObject schema representing one union option
+ * @param prefix - Optional prefix for nested discriminators (e.g., "zfs" for "zfs:pools")
+ * @returns HelpEntry with discriminator, description, and parameters, or null if invalid
  */
 function extractObjectHelpEntry(option, prefix) {
     // Access shape from ZodObject
@@ -125,8 +166,8 @@ function extractObjectHelpEntry(option, prefix) {
     }
     // Build discriminator value: action or action:subaction
     let discriminatorValue;
-    const actionLiteral = literals.find(l => l.key === 'action');
-    const subactionLiteral = literals.find(l => l.key === 'subaction');
+    const actionLiteral = literals.find((l) => l.key === "action");
+    const subactionLiteral = literals.find((l) => l.key === "subaction");
     if (subactionLiteral && actionLiteral) {
         // Nested pattern: action:subaction (e.g., "zfs:pools")
         discriminatorValue = `${actionLiteral.value}:${subactionLiteral.value}`;
@@ -151,13 +192,13 @@ function extractObjectHelpEntry(option, prefix) {
             type: getBaseTypeName(fieldSchema),
             description: fieldSchema.description,
             required: !fieldSchema.isOptional(),
-            default: getDefaultValue(fieldSchema)
+            default: getDefaultValue(fieldSchema),
         };
     });
     return {
         discriminator: discriminatorValue,
         description: option.description ?? "",
-        parameters
+        parameters,
     };
 }
 /**
@@ -204,7 +245,7 @@ export function generateHelp(schema, topic) {
     }
     // Filter by topic if provided
     if (topic) {
-        return entries.filter((e) => e.discriminator === topic || e.discriminator.startsWith(topic + ':'));
+        return entries.filter((e) => e.discriminator === topic || e.discriminator.startsWith(`${topic}:`));
     }
     return entries;
 }
@@ -252,7 +293,7 @@ export function formatHelpJson(entries) {
     const jsonEntries = entries.map((entry) => ({
         action: entry.discriminator,
         description: entry.description,
-        parameters: entry.parameters
+        parameters: entry.parameters,
     }));
     return JSON.stringify(jsonEntries, null, 2);
 }

package/dist/utils/help.js.map

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

package/dist/utils/host-utils.d.ts

@@ -0,0 +1,31 @@
+import type { HostConfig } from "../types.js";
+/**
+ * Determine if a host should use local command execution instead of SSH.
+ *
+ * A host is considered local if:
+ * - Host is localhost/127.x.x.x/::1/0.0.0.0 AND no SSH user is specified
+ * - Protocol is SSH (http/https are Docker API only, not for command execution)
+ *
+ * Note: Even localhost with sshUser means we need to SSH as that user,
+ * so it's treated as remote for command execution purposes.
+ *
+ * @param host - Host configuration to check
+ * @returns True if commands should run locally, false if SSH is required
+ */
+export declare function isLocalHost(host: HostConfig): boolean;
+/**
+ * Narrow a multi-host array to a single default host when no explicit host was requested.
+ *
+ * Prevents unbounded fan-out across all configured hosts on read operations.
+ * Resolution order:
+ *   1. SYNAPSE_DEFAULT_HOST env var
+ *   2. First host with a local Docker socket path
+ *   3. Fall through to original array (no narrowing possible)
+ *
+ * When hosts.length <= 1, returns the array unchanged (already targeted).
+ *
+ * @param hosts - Array of host configurations
+ * @returns Narrowed array (single host) or original array if no default found
+ */
+export declare function narrowToDefaultHost(hosts: HostConfig[]): HostConfig[];
+//# sourceMappingURL=host-utils.d.ts.map

package/dist/utils/host-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-utils.d.ts","sourceRoot":"","sources":["../../src/utils/host-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAmCrD;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAkBrE"}

package/dist/utils/host-utils.js

@@ -0,0 +1,80 @@
+/**
+ * Determine if a host should use local command execution instead of SSH.
+ *
+ * A host is considered local if:
+ * - Host is localhost/127.x.x.x/::1/0.0.0.0 AND no SSH user is specified
+ * - Protocol is SSH (http/https are Docker API only, not for command execution)
+ *
+ * Note: Even localhost with sshUser means we need to SSH as that user,
+ * so it's treated as remote for command execution purposes.
+ *
+ * @param host - Host configuration to check
+ * @returns True if commands should run locally, false if SSH is required
+ */
+export function isLocalHost(host) {
+    // Docker API protocols (http/https) don't support local command execution
+    if (host.protocol === "http" || host.protocol === "https") {
+        return false;
+    }
+    // If SSH user is specified, we need SSH even for localhost
+    if (host.sshUser) {
+        return false;
+    }
+    // Check if hostname is a loopback address
+    const hostname = host.host.toLowerCase();
+    // Check for localhost
+    if (hostname === "localhost") {
+        return true;
+    }
+    // Check for IPv4 loopback (127.0.0.0/8)
+    if (hostname.startsWith("127.")) {
+        return true;
+    }
+    // Check for IPv6 loopback
+    if (hostname === "::1") {
+        return true;
+    }
+    // Check for 0.0.0.0 (all interfaces - treated as local)
+    if (hostname === "0.0.0.0") {
+        return true;
+    }
+    return false;
+}
+/**
+ * Find a host with a local Docker socket path.
+ * Used as a fallback when no specific host is requested.
+ */
+function findLocalSocketHost(hosts) {
+    return hosts.find((host) => Boolean(host.dockerSocketPath) || host.host.startsWith("/"));
+}
+/**
+ * Narrow a multi-host array to a single default host when no explicit host was requested.
+ *
+ * Prevents unbounded fan-out across all configured hosts on read operations.
+ * Resolution order:
+ *   1. SYNAPSE_DEFAULT_HOST env var
+ *   2. First host with a local Docker socket path
+ *   3. Fall through to original array (no narrowing possible)
+ *
+ * When hosts.length <= 1, returns the array unchanged (already targeted).
+ *
+ * @param hosts - Array of host configurations
+ * @returns Narrowed array (single host) or original array if no default found
+ */
+export function narrowToDefaultHost(hosts) {
+    if (hosts.length <= 1)
+        return hosts;
+    const rawDefaultHost = process.env.SYNAPSE_DEFAULT_HOST?.trim();
+    const defaultHost = rawDefaultHost && rawDefaultHost !== "undefined" && rawDefaultHost !== "null"
+        ? rawDefaultHost
+        : undefined;
+    const localSocketHost = findLocalSocketHost(hosts);
+    const targetName = defaultHost ?? localSocketHost?.name;
+    if (!targetName)
+        return hosts;
+    const matched = hosts.find((h) => h.name === targetName);
+    if (!matched)
+        return hosts;
+    return [matched];
+}
+//# sourceMappingURL=host-utils.js.map

package/dist/utils/host-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-utils.js","sourceRoot":"","sources":["../../src/utils/host-utils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,IAAgB;IAC1C,0EAA0E;IAC1E,IAAI,IAAI,CAAC,QAAQ,KAAK,MAAM,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC1D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,2DAA2D;IAC3D,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,0CAA0C;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IAEzC,sBAAsB;IACtB,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wCAAwC;IACxC,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,0BAA0B;IAC1B,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wDAAwD;IACxD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,SAAS,mBAAmB,CAAC,KAAmB;IAC9C,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAmB;IACrD,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAEpC,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,IAAI,EAAE,CAAC;IAChE,MAAM,WAAW,GACf,cAAc,IAAI,cAAc,KAAK,WAAW,IAAI,cAAc,KAAK,MAAM;QAC3E,CAAC,CAAC,cAAc;QAChB,CAAC,CAAC,SAAS,CAAC;IAEhB,MAAM,eAAe,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACnD,MAAM,UAAU,GAAG,WAAW,IAAI,eAAe,EAAE,IAAI,CAAC;IAExD,IAAI,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC;IAE9B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;IACzD,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAE3B,OAAO,CAAC,OAAO,CAAC,CAAC;AACnB,CAAC"}

package/dist/utils/index.d.ts

@@ -1,4 +1,10 @@
-export { validateSecurePath, HostSecurityError, validateHostFormat, escapeShellArg, isSystemPath } from "./path-security.js";
-export { generateHelp, formatHelpMarkdown, formatHelpJson } from "./help.js";
 export type { HelpEntry, HelpJsonEntry } from "./help.js";
+export { formatHelpJson, formatHelpMarkdown, generateHelp } from "./help.js";
+export { type HelpInput, handleHelpAction } from "./help-handler.js";
+export { isLocalHost } from "./host-utils.js";
+export { applyPagination } from "./pagination.js";
+export { escapeShellArg, HostSecurityError, isSystemPath, SSHArgSecurityError, SYSTEMD_SERVICE_NAME_PATTERN, validateHostname, validateSecurePath, validateSSHArg, validateSystemdServiceName, } from "./path-security.js";
+export { COMPOSE_PROJECT_SEVERITY, COMPOSE_SERVICE_SEVERITY, CONTAINER_SEVERITY, sortBySeverity, } from "./sorting.js";
+export { getCurrentTimestamp } from "./time.js";
+export { validateAlphanumeric, validateServiceName } from "./validation.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,YAAY,EACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC7E,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EAAE,KAAK,SAAS,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,4BAA4B,EAC5B,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,kBAAkB,EAClB,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/utils/index.js

@@ -1,4 +1,10 @@
 // Explicit named exports for better IDE support and tree-shaking
-export { validateSecurePath, HostSecurityError, validateHostFormat, escapeShellArg, isSystemPath } from "./path-security.js";
-export { generateHelp, formatHelpMarkdown, formatHelpJson } from "./help.js";
+export { formatHelpJson, formatHelpMarkdown, generateHelp } from "./help.js";
+export { handleHelpAction } from "./help-handler.js";
+export { isLocalHost } from "./host-utils.js";
+export { applyPagination } from "./pagination.js";
+export { escapeShellArg, HostSecurityError, isSystemPath, SSHArgSecurityError, SYSTEMD_SERVICE_NAME_PATTERN, validateHostname, validateSecurePath, validateSSHArg, validateSystemdServiceName, } from "./path-security.js";
+export { COMPOSE_PROJECT_SEVERITY, COMPOSE_SERVICE_SEVERITY, CONTAINER_SEVERITY, sortBySeverity, } from "./sorting.js";
+export { getCurrentTimestamp } from "./time.js";
+export { validateAlphanumeric, validateServiceName } from "./validation.js";
 //# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,YAAY,EACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,iEAAiE;AAGjE,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EAAkB,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,4BAA4B,EAC5B,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,kBAAkB,EAClB,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}