synapse-mcp 1.0.0 → 1.0.2

package/dist/services/ssh-service.js

@@ -1,4 +1,34 @@
 import { SSHCommandError } from "../utils/errors.js";
+import { escapeShellArg } from "../utils/path-security.js";
+/**
+ * Hardcoded shell script for collecting host resource information.
+ *
+ * Security (S-H4): This multi-command script is SAFE because it is fully hardcoded
+ * with no user input. The script pattern (joining with semicolons) is only safe
+ * for hardcoded commands.
+ *
+ * WARNING: Do NOT copy this pattern for user-influenced commands. User input
+ * must be validated and escaped per command using escapeShellArg().
+ *
+ * @see https://cwe.mitre.org/data/definitions/78.html
+ */
+const HOST_RESOURCES_SCRIPT = `
+hostname
+echo "---"
+uptime -p 2>/dev/null || uptime | sed 's/.*up/up/'
+echo "---"
+cat /proc/loadavg | awk '{print $1,$2,$3}'
+echo "---"
+nproc
+echo "---"
+top -bn1 | grep "Cpu(s)" | awk '{print 100-$8}' 2>/dev/null || echo "0"
+echo "---"
+free -m | awk '/^Mem:/ {print $2,$3,$4}'
+echo "---"
+df -BG --output=source,target,size,used,avail,pcent 2>/dev/null | grep -E '^/dev' || df -h | grep -E '^/dev'
+`
+    .trim()
+    .replace(/\n/g, "; ");
 /**
  * SSH service implementation using connection pool for command execution.
  * Provides secure command execution and resource monitoring via SSH connections.
@@ -25,12 +55,13 @@ export class SSHService {
         const timeoutMs = options.timeoutMs || 30000;
         // Get connection from pool
         const connection = await this.pool.getConnection(host);
-        // Build full command
-        const fullCommand = args.length > 0 ? `${command} ${args.join(" ")}` : command;
+        // Build full command with escaped arguments to prevent shell injection
+        const fullCommand = args.length > 0 ? `${command} ${args.map((a) => escapeShellArg(a)).join(" ")}` : command;
+        let timeoutId = null;
         try {
             // Execute with timeout
             const timeoutPromise = new Promise((_, reject) => {
-                setTimeout(() => {
+                timeoutId = setTimeout(() => {
                     reject(new Error(`SSH command timeout after ${timeoutMs}ms: ${command}`));
                 }, timeoutMs);
             });
@@ -53,6 +84,10 @@ export class SSHService {
             throw new SSHCommandError("SSH command execution failed", host.name, fullCommand, undefined, undefined, undefined, error);
         }
         finally {
+            // Clear timeout to prevent resource leak
+            if (timeoutId !== null) {
+                clearTimeout(timeoutId);
+            }
             // Always release connection back to pool
             await this.pool.releaseConnection(host, connection);
         }
@@ -60,29 +95,16 @@ export class SSHService {
     /**
      * Get host resource usage via SSH using connection pool
      *
+     * Security (S-H4): Uses hardcoded HOST_RESOURCES_SCRIPT constant for safety.
+     * See constant definition for security documentation.
+     *
      * @param host - Host configuration to query
      * @returns Resource information including CPU, memory, disk, and uptime
      */
     async getHostResources(host) {
         // Run all commands in one SSH session for efficiency
-        const script = `
-    hostname
-    echo "---"
-    uptime -p 2>/dev/null || uptime | sed 's/.*up/up/'
-    echo "---"
-    cat /proc/loadavg | awk '{print $1,$2,$3}'
-    echo "---"
-    nproc
-    echo "---"
-    top -bn1 | grep "Cpu(s)" | awk '{print 100-$8}' 2>/dev/null || echo "0"
-    echo "---"
-    free -m | awk '/^Mem:/ {print $2,$3,$4}'
-    echo "---"
-    df -BG --output=source,target,size,used,avail,pcent 2>/dev/null | grep -E '^/dev' || df -h | grep -E '^/dev'
-  `
-            .trim()
-            .replace(/\n/g, "; ");
-        const output = await this.executeSSHCommand(host, script);
+        // SECURITY (S-H4): Script is hardcoded constant - safe for semicolon joining
+        const output = await this.executeSSHCommand(host, HOST_RESOURCES_SCRIPT);
         const sections = output.split("---").map((s) => s.trim());
         // Parse hostname
         const hostname = sections[0] || host.name;
@@ -93,11 +115,11 @@ export class SSHService {
         const loadAverage = [
             loadParts[0] || 0,
             loadParts[1] || 0,
-            loadParts[2] || 0
+            loadParts[2] || 0,
         ];
         // Parse CPU
-        const cores = parseInt(sections[3] || "1", 10);
-        const cpuUsage = parseFloat(sections[4] || "0");
+        const cores = Number.parseInt(sections[3] || "1", 10);
+        const cpuUsage = Number.parseFloat(sections[4] || "0");
         // Parse memory
         const memParts = (sections[5] || "0 0 0").split(" ").map(Number);
         const totalMB = memParts[0] || 0;
@@ -113,10 +135,10 @@ export class SSHService {
                 return {
                     filesystem: parts[0],
                     mount: parts[1],
-                    totalGB: parseFloat(parts[2].replace("G", "")) || 0,
-                    usedGB: parseFloat(parts[3].replace("G", "")) || 0,
-                    availGB: parseFloat(parts[4].replace("G", "")) || 0,
-                    usagePercent: parseFloat(parts[5].replace("%", "")) || 0
+                    totalGB: Number.parseFloat(parts[2].replace("G", "")) || 0,
+                    usedGB: Number.parseFloat(parts[3].replace("G", "")) || 0,
+                    availGB: Number.parseFloat(parts[4].replace("G", "")) || 0,
+                    usagePercent: Number.parseFloat(parts[5].replace("%", "")) || 0,
                 };
             }
             return null;
@@ -128,15 +150,15 @@ export class SSHService {
             loadAverage,
             cpu: {
                 cores,
-                usagePercent: Math.round(cpuUsage * 10) / 10
+                usagePercent: Math.round(cpuUsage * 10) / 10,
             },
             memory: {
                 totalMB,
                 usedMB,
                 freeMB,
-                usagePercent: Math.round(memUsagePercent * 10) / 10
+                usagePercent: Math.round(memUsagePercent * 10) / 10,
             },
-            disk
+            disk,
         };
     }
 }

package/dist/services/ssh-service.js.map

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

package/dist/services/ssh.d.ts

@@ -1,11 +1,7 @@
-import { HostConfig } from "../types.js";
-/**
- * Sanitize string for safe shell usage
- * Rejects any potentially dangerous characters
- */
-export declare function sanitizeForShell(input: string): string;
+import type { HostConfig } from "../types.js";
 /**
  * Validate host configuration for SSH
+ * SECURITY: Validates host before shell interpolation to prevent command injection
  */
 export declare function validateHostForSsh(host: HostConfig): void;
 /**

package/dist/services/ssh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssh.d.ts","sourceRoot":"","sources":["../../src/services/ssh.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA4BzC;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMtD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAezD;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,GAAG,EAAE;QACH,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,IAAI,EAAE,KAAK,CAAC;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;CACJ"}
+{"version":3,"file":"ssh.d.ts","sourceRoot":"","sources":["../../src/services/ssh.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI9C;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAazD;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,GAAG,EAAE;QACH,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,IAAI,EAAE,KAAK,CAAC;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;CACJ"}

package/dist/services/ssh.js

@@ -1,50 +1,19 @@
-import { SSHService } from "./ssh-service.js";
-import { SSHConnectionPoolImpl } from "./ssh-pool.js";
-/**
- * Temporary global SSH service for backward compatibility
- * @deprecated Use ServiceContainer.getSSHService() instead
- */
-let globalSSHService = null;
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-function getGlobalSSHService() {
-    if (!globalSSHService) {
-        const pool = new SSHConnectionPoolImpl({
-            maxConnections: parseInt(process.env.HOMELAB_SSH_MAX_CONNECTIONS || "5", 10),
-            idleTimeoutMs: parseInt(process.env.HOMELAB_SSH_IDLE_TIMEOUT_MS || "60000", 10),
-            connectionTimeoutMs: parseInt(process.env.HOMELAB_SSH_CONNECTION_TIMEOUT_MS || "5000", 10),
-            enableHealthChecks: process.env.HOMELAB_SSH_ENABLE_HEALTH_CHECKS !== "false",
-            healthCheckIntervalMs: parseInt(process.env.HOMELAB_SSH_HEALTH_CHECK_INTERVAL_MS || "30000", 10)
-        });
-        globalSSHService = new SSHService(pool);
-    }
-    return globalSSHService;
-}
-/**
- * Sanitize string for safe shell usage
- * Rejects any potentially dangerous characters
- */
-export function sanitizeForShell(input) {
-    // Only allow alphanumeric, dots, hyphens, underscores, and forward slashes (for paths)
-    if (!/^[a-zA-Z0-9._\-/]+$/.test(input)) {
-        throw new Error(`Invalid characters in input: ${input}`);
-    }
-    return input;
-}
+import { validateHostname } from "../utils/path-security.js";
+import { validateAlphanumeric } from "../utils/validation.js";
 /**
  * Validate host configuration for SSH
+ * SECURITY: Validates host before shell interpolation to prevent command injection
  */
 export function validateHostForSsh(host) {
-    // Validate hostname/IP - allow alphanumeric, dots, hyphens, colons (IPv6), and brackets
-    if (host.host && !/^[a-zA-Z0-9.\-:[\]/]+$/.test(host.host)) {
-        throw new Error(`Invalid host format: ${host.host}`);
-    }
+    // Validate hostname using centralized validation
+    validateHostname(host.host);
     // Validate SSH user if provided
-    if (host.sshUser && !/^[a-zA-Z0-9_-]+$/.test(host.sshUser)) {
-        throw new Error(`Invalid SSH user: ${host.sshUser}`);
+    if (host.sshUser) {
+        validateAlphanumeric(host.sshUser, "SSH user");
     }
     // Validate key path if provided
-    if (host.sshKeyPath && !/^[a-zA-Z0-9._\-/~]+$/.test(host.sshKeyPath)) {
-        throw new Error(`Invalid SSH key path: ${host.sshKeyPath}`);
+    if (host.sshKeyPath) {
+        validateAlphanumeric(host.sshKeyPath, "SSH key path", { allowSlash: true, allowTilde: true });
     }
 }
 //# sourceMappingURL=ssh.js.map

package/dist/services/ssh.js.map

@@ -1 +1 @@
-{"version":3,"file":"ssh.js","sourceRoot":"","sources":["../../src/services/ssh.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD;;;GAGG;AACH,IAAI,gBAAgB,GAAsB,IAAI,CAAC;AAE/C,6DAA6D;AAC7D,SAAS,mBAAmB;IAC1B,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,IAAI,qBAAqB,CAAC;YACrC,cAAc,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,2BAA2B,IAAI,GAAG,EAAE,EAAE,CAAC;YAC5E,aAAa,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,2BAA2B,IAAI,OAAO,EAAE,EAAE,CAAC;YAC/E,mBAAmB,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,iCAAiC,IAAI,MAAM,EAAE,EAAE,CAAC;YAC1F,kBAAkB,EAAE,OAAO,CAAC,GAAG,CAAC,gCAAgC,KAAK,OAAO;YAC5E,qBAAqB,EAAE,QAAQ,CAC7B,OAAO,CAAC,GAAG,CAAC,oCAAoC,IAAI,OAAO,EAC3D,EAAE,CACH;SACF,CAAC,CAAC;QACH,gBAAgB,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,uFAAuF;IACvF,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,gCAAgC,KAAK,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAgB;IACjD,wFAAwF;IACxF,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,gCAAgC;IAChC,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,gCAAgC;IAChC,IAAI,IAAI,CAAC,UAAU,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC"}
+{"version":3,"file":"ssh.js","sourceRoot":"","sources":["../../src/services/ssh.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAgB;IACjD,iDAAiD;IACjD,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE5B,gCAAgC;IAChC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,oBAAoB,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACjD,CAAC;IAED,gCAAgC;IAChC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,oBAAoB,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IAChG,CAAC;AACH,CAAC"}

package/dist/tools/definitions/flux.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Flux tool definition
+ *
+ * Docker infrastructure management tool for containers, compose, images, and hosts.
+ */
+import type { ToolDefinition } from "../registry.js";
+/**
+ * Flux tool - Docker infrastructure management
+ *
+ * Supports: container, compose, docker, and host operations
+ */
+export declare const FluxTool: ToolDefinition;
+//# sourceMappingURL=flux.d.ts.map

package/dist/tools/definitions/flux.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flux.d.ts","sourceRoot":"","sources":["../../../src/tools/definitions/flux.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,cAuFtB,CAAC"}

package/dist/tools/definitions/flux.js

@@ -0,0 +1,101 @@
+/**
+ * Flux tool definition
+ *
+ * Docker infrastructure management tool for containers, compose, images, and hosts.
+ */
+import { FluxSchema } from "../../schemas/flux/index.js";
+import { handleFluxTool } from "../flux.js";
+/**
+ * Flux tool - Docker infrastructure management
+ *
+ * Supports: container, compose, docker, and host operations
+ */
+export const FluxTool = {
+    name: "flux",
+    title: "Flux Tool",
+    description: `Docker infrastructure management - container, compose, docker, and host operations
+
+HOW TO USE:
+{
+  "action": "container",                   // Required: action family
+  "subaction": "list",                     // Required: operation within action
+  "host": "hostname",                      // Optional: target specific host
+  "response_format": "markdown",           // Optional: markdown (default) or json
+  "force": true                            // Required for destructive operations (⚠️)
+}
+
+Examples:
+  • List containers: {"action": "container", "subaction": "list"}
+  • Stop container: {"action": "container", "subaction": "stop", "container_id": "container-id"}
+  • Docker info: {"action": "docker", "subaction": "info", "host": "myhost"}
+  • Help: {"action": "help"}
+
+FLUX OPERATIONS:
+
+Container (14 operations)
+  ●  exec       - Execute command in running container
+  ●  inspect    - Detailed container information
+  ●  list       - List containers across all hosts
+  ●  logs       - Container logs with streaming
+  ●  pause      - Pause container execution
+  ●  pull       - Pull latest image for a container
+  ⚠️  recreate   - Recreate a container
+  ●  restart    - Restart one or more containers
+  ●  resume     - Resume paused container
+  ●  search     - Search containers across hosts
+  ●  start      - Start stopped containers
+  ●  stats      - Container resource usage statistics
+  ●  stop       - Stop running containers
+  ●  top        - Display running processes in container
+
+Compose (10 operations)
+  ●  build      - Build compose project images
+  ⚠️  down       - Stop compose project
+  ●  list       - List compose projects across all hosts
+  ●  logs       - View compose project logs
+  ●  pull       - Pull compose project images
+  ●  refresh    - Refresh compose project discovery cache
+  ⚠️  recreate   - Recreate compose containers
+  ●  restart    - Restart compose services
+  ●  status     - Show compose project status
+  ●  up         - Create and start compose services
+
+Docker (9 operations)
+  ⚠️  build      - Build image from Dockerfile
+  ●  df         - Show docker disk usage
+  ●  images     - List images across all hosts
+  ●  info       - Display system-wide information
+  ●  networks   - List networks across all hosts
+  ●  pull       - Pull a Docker image
+  ⚠️  prune      - Remove unused Docker objects
+  ⚠️  rmi        - Remove one or more images
+  ●  volumes    - List volumes across all hosts
+
+Host (9 operations)
+  ✓  doctor     - Run diagnostic checks
+  ✓  info       - Host system information
+  ●  mounts     - List filesystem mounts
+  ●  network    - Network interface details
+  ●  ports      - List and filter host/container port mappings
+  ●  resources  - CPU, memory, and disk usage
+  ●  services   - List systemd services
+  ✓  status     - Quick host health check
+  ●  uptime     - System uptime and load
+
+Help (1 operation)
+  ●  help       - Show available operations
+
+Legend:
+  ● State-changing operation
+  ⚠️ Destructive operation (requires force: true)
+  ✓ Diagnostic/health check`,
+    inputSchema: FluxSchema,
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true, // Can prune containers, remove images, recreate containers
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    handler: handleFluxTool,
+};
+//# sourceMappingURL=flux.js.map

package/dist/tools/definitions/flux.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flux.js","sourceRoot":"","sources":["../../../src/tools/definitions/flux.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAmB;IACtC,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,WAAW;IAClB,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BA2Ea;IAC1B,WAAW,EAAE,UAAU;IACvB,WAAW,EAAE;QACX,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,IAAI,EAAE,2DAA2D;QAClF,cAAc,EAAE,KAAK;QACrB,aAAa,EAAE,IAAI;KACpB;IACD,OAAO,EAAE,cAAc;CACxB,CAAC"}

package/dist/tools/definitions/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Built-in tool definitions
+ *
+ * Exports all built-in tool definitions for registration with ToolRegistry.
+ */
+export { FluxTool } from "./flux.js";
+export { ScoutTool } from "./scout.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/definitions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/tools/definitions/index.js

@@ -0,0 +1,8 @@
+/**
+ * Built-in tool definitions
+ *
+ * Exports all built-in tool definitions for registration with ToolRegistry.
+ */
+export { FluxTool } from "./flux.js";
+export { ScoutTool } from "./scout.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/definitions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/tools/definitions/scout.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Scout tool definition
+ *
+ * SSH remote operations tool for file, process, and system inspection.
+ */
+import type { ToolDefinition } from "../registry.js";
+/**
+ * Scout tool - SSH remote operations
+ *
+ * Supports: file operations, process inspection, system information
+ */
+export declare const ScoutTool: ToolDefinition;
+//# sourceMappingURL=scout.d.ts.map

package/dist/tools/definitions/scout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scout.d.ts","sourceRoot":"","sources":["../../../src/tools/definitions/scout.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGrD;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,cAgEvB,CAAC"}

package/dist/tools/definitions/scout.js

@@ -0,0 +1,78 @@
+/**
+ * Scout tool definition
+ *
+ * SSH remote operations tool for file, process, and system inspection.
+ */
+import { ScoutSchema } from "../../schemas/scout/index.js";
+import { handleScoutTool } from "../scout.js";
+/**
+ * Scout tool - SSH remote operations
+ *
+ * Supports: file operations, process inspection, system information
+ */
+export const ScoutTool = {
+    name: "scout",
+    title: "Scout Tool",
+    description: `SSH remote operations - file, process, and system inspection
+
+HOW TO USE:
+{
+  "action": "peek",                        // Simple actions
+  "host": "hostname",                      // Required for most operations
+  "path": "/path/to/file"                  // Operation-specific parameters
+}
+{
+  "action": "zfs",                         // ZFS operations
+  "subaction": "pools",                    // Subaction: pools, datasets, snapshots
+  "host": "hostname"
+}
+{
+  "action": "logs",                        // Log operations
+  "subaction": "journal",                  // Subaction: syslog, journal, dmesg, auth
+  "host": "hostname",
+  "lines": 50                              // Optional: number of lines
+}
+
+Examples:
+  • List hosts: {"action": "nodes"}
+  • Read file: {"action": "peek", "host": "myhost", "path": "/etc/hostname"}
+  • ZFS pools: {"action": "zfs", "subaction": "pools", "host": "myhost"}
+  • System logs: {"action": "logs", "subaction": "journal", "host": "myhost"}
+
+SCOUT OPERATIONS:
+
+Simple Actions (9 operations)
+  ●  beam       - File transfer between local and remote hosts
+  ●  delta      - Compare files or content between locations
+  ●  df         - Disk usage information for a remote host
+  ●  emit       - Multi-host operations
+  ●  exec       - Execute command on a remote host
+  ●  find       - Find files by glob pattern on a remote host
+  ●  nodes      - List all configured SSH hosts
+  ●  peek       - Read file or directory contents on a remote host
+  ●  ps         - List and search processes on a remote host
+
+ZFS (3 operations)
+  ●  pools      - List ZFS storage pools
+  ●  datasets   - List ZFS datasets
+  ●  snapshots  - List ZFS snapshots
+
+Logs (4 operations)
+  ●  syslog     - Access system log files (/var/log)
+  ●  journal    - Access systemd journal logs
+  ●  dmesg      - Access kernel ring buffer logs
+  ●  auth       - Access authentication logs
+
+Legend:
+  ● State-changing operation
+  ✓ Diagnostic/health check`,
+    inputSchema: ScoutSchema,
+    annotations: {
+        readOnlyHint: false, // Can write files, execute commands
+        destructiveHint: true, // exec and emit can run arbitrary commands
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    handler: handleScoutTool,
+};
+//# sourceMappingURL=scout.js.map

package/dist/tools/definitions/scout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scout.js","sourceRoot":"","sources":["../../../src/tools/definitions/scout.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAE3D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAmB;IACvC,IAAI,EAAE,OAAO;IACb,KAAK,EAAE,YAAY;IACnB,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAoDa;IAC1B,WAAW,EAAE,WAAW;IACxB,WAAW,EAAE;QACX,YAAY,EAAE,KAAK,EAAE,oCAAoC;QACzD,eAAe,EAAE,IAAI,EAAE,2CAA2C;QAClE,cAAc,EAAE,KAAK;QACrB,aAAa,EAAE,IAAI;KACpB;IACD,OAAO,EAAE,eAAe;CACzB,CAAC"}

package/dist/tools/flux.d.ts

@@ -1,14 +1,22 @@
-import type { ServiceContainer } from '../services/container.js';
+import type { ServiceContainer } from "../services/container.js";
 /**
- * Flux tool handler - Docker infrastructure management
+ * Handle all Flux tool requests - Docker infrastructure management.
  *
- * Handles 4 action categories with 39 total subactions:
- * - container: 14 subactions (list, start, stop, restart, pause, resume, logs, stats, inspect, search, pull, recreate, exec, top)
- * - compose: 9 subactions (list, status, up, down, restart, logs, build, pull, recreate)
- * - docker: 9 subactions (info, df, prune, images, pull, build, rmi, networks, volumes)
- * - host: 7 subactions (status, resources, info, uptime, services, network, mounts)
+ * Routes incoming requests to specialized handlers based on action type.
+ * Validates input against Flux schema before dispatching.
  *
- * Plus 'help' pseudo-action for auto-generated documentation.
+ * @param input - Unvalidated user input to process
+ * @param container - Service container with dependencies
+ * @returns Formatted response string (markdown or JSON)
+ * @throws {Error} When validation fails or action is unknown
+ *
+ * @example
+ * ```typescript
+ * const result = await handleFluxTool(
+ *   { action: 'container', subaction: 'list', state: 'running' },
+ *   container
+ * );
+ * ```
  */
 export declare function handleFluxTool(input: unknown, container: ServiceContainer): Promise<string>;
 //# sourceMappingURL=flux.d.ts.map

package/dist/tools/flux.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flux.d.ts","sourceRoot":"","sources":["../../src/tools/flux.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAQjE;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,gBAAgB,GAC1B,OAAO,CAAC,MAAM,CAAC,CA6BjB"}
+{"version":3,"file":"flux.d.ts","sourceRoot":"","sources":["../../src/tools/flux.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAOjE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoBjG"}