@checkstack/healthcheck-ssh-backend 0.0.2 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @checkstack/healthcheck-ssh-backend
 
+## 0.1.0
+
+### Minor Changes
+
+- f5b1f49: Refactored health check strategies to use `createClient()` pattern with built-in collectors.
+
+  **Strategy Changes:**
+
+  - Replaced `execute()` with `createClient()` that returns a transport client
+  - Strategy configs now only contain connection parameters
+  - Collector configs handle what to do with the connection
+
+  **Built-in Collectors Added:**
+
+  - DNS: `LookupCollector` for hostname resolution
+  - gRPC: `HealthCollector` for gRPC health protocol
+  - HTTP: `RequestCollector` for HTTP requests
+  - MySQL: `QueryCollector` for database queries
+  - Ping: `PingCollector` for ICMP ping
+  - Postgres: `QueryCollector` for database queries
+  - Redis: `CommandCollector` for Redis commands
+  - Script: `ExecuteCollector` for script execution
+  - SSH: `CommandCollector` for SSH commands
+  - TCP: `BannerCollector` for TCP banner grabbing
+  - TLS: `CertificateCollector` for certificate inspection
+
+### Patch Changes
+
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+  - @checkstack/backend-api@0.1.0
+  - @checkstack/healthcheck-common@0.1.0
+  - @checkstack/healthcheck-ssh-common@0.1.0
+  - @checkstack/common@0.0.3
+
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies [cb82e4d]
+  - @checkstack/healthcheck-common@0.0.3
+
 ## 0.0.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-ssh-backend",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {
@@ -12,6 +12,7 @@
     "@checkstack/backend-api": "workspace:*",
     "@checkstack/common": "workspace:*",
     "@checkstack/healthcheck-common": "workspace:*",
+    "@checkstack/healthcheck-ssh-common": "workspace:*",
     "ssh2": "^1.15.0"
   },
   "devDependencies": {

package/src/command-collector.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it, mock } from "bun:test";
+import { CommandCollector, type CommandConfig } from "./command-collector";
+import type { SshTransportClient } from "@checkstack/healthcheck-ssh-common";
+
+describe("CommandCollector", () => {
+  const createMockClient = (
+    response: {
+      exitCode?: number;
+      stdout?: string;
+      stderr?: string;
+    } = {}
+  ): SshTransportClient => ({
+    exec: mock(() =>
+      Promise.resolve({
+        exitCode: response.exitCode ?? 0,
+        stdout: response.stdout ?? "",
+        stderr: response.stderr ?? "",
+      })
+    ),
+  });
+
+  describe("execute", () => {
+    it("should execute command successfully", async () => {
+      const collector = new CommandCollector();
+      const client = createMockClient({
+        exitCode: 0,
+        stdout: "Hello World",
+      });
+
+      const result = await collector.execute({
+        config: { command: "echo 'Hello World'" },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.exitCode).toBe(0);
+      expect(result.result.stdout).toBe("Hello World");
+      expect(result.result.executionTimeMs).toBeGreaterThanOrEqual(0);
+    });
+
+    it("should return non-zero exit code for failed command", async () => {
+      const collector = new CommandCollector();
+      const client = createMockClient({
+        exitCode: 1,
+        stderr: "Command not found",
+      });
+
+      const result = await collector.execute({
+        config: { command: "nonexistent-command" },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.exitCode).toBe(1);
+      expect(result.result.stderr).toBe("Command not found");
+    });
+
+    it("should pass command to client", async () => {
+      const collector = new CommandCollector();
+      const client = createMockClient();
+
+      await collector.execute({
+        config: { command: "ls -la /tmp" },
+        client,
+        pluginId: "test",
+      });
+
+      expect(client.exec).toHaveBeenCalledWith("ls -la /tmp");
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate average execution time and success rate", () => {
+      const collector = new CommandCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            exitCode: 0,
+            stdout: "",
+            stderr: "",
+            executionTimeMs: 50,
+          },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 150,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            exitCode: 0,
+            stdout: "",
+            stderr: "",
+            executionTimeMs: 100,
+          },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.avgExecutionTimeMs).toBe(75);
+      expect(aggregated.successRate).toBe(100);
+    });
+
+    it("should calculate success rate based on exit codes", () => {
+      const collector = new CommandCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            exitCode: 0,
+            stdout: "",
+            stderr: "",
+            executionTimeMs: 50,
+          },
+        },
+        {
+          id: "2",
+          status: "unhealthy" as const,
+          latencyMs: 150,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            exitCode: 1,
+            stdout: "",
+            stderr: "",
+            executionTimeMs: 100,
+          },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.successRate).toBe(50);
+    });
+  });
+
+  describe("metadata", () => {
+    it("should have correct static properties", () => {
+      const collector = new CommandCollector();
+
+      expect(collector.id).toBe("command");
+      expect(collector.displayName).toBe("Shell Command");
+      expect(collector.allowMultiple).toBe(true);
+      expect(collector.supportedPlugins).toHaveLength(1);
+    });
+  });
+});

package/src/command-collector.ts

@@ -0,0 +1,151 @@
+import {
+  Versioned,
+  z,
+  type HealthCheckRunForAggregation,
+  type CollectorResult,
+  type CollectorStrategy,
+} from "@checkstack/backend-api";
+import {
+  healthResultNumber,
+  healthResultString,
+} from "@checkstack/healthcheck-common";
+import { pluginMetadata as sshPluginMetadata } from "./plugin-metadata";
+import type { SshTransportClient } from "@checkstack/healthcheck-ssh-common";
+
+// ============================================================================
+// CONFIGURATION SCHEMA
+// ============================================================================
+
+const commandConfigSchema = z.object({
+  command: z.string().min(1).describe("Shell command to execute"),
+});
+
+export type CommandConfig = z.infer<typeof commandConfigSchema>;
+
+// ============================================================================
+// RESULT SCHEMAS
+// ============================================================================
+
+const commandResultSchema = z.object({
+  exitCode: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Exit Code",
+  }),
+  stdout: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Standard Output",
+  }),
+  stderr: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Standard Error",
+  }),
+  executionTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Execution Time",
+    "x-chart-unit": "ms",
+  }),
+});
+
+export type CommandResult = z.infer<typeof commandResultSchema>;
+
+const commandAggregatedSchema = z.object({
+  avgExecutionTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Execution Time",
+    "x-chart-unit": "ms",
+  }),
+  successRate: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Success Rate",
+    "x-chart-unit": "%",
+  }),
+});
+
+export type CommandAggregatedResult = z.infer<typeof commandAggregatedSchema>;
+
+// ============================================================================
+// COMMAND COLLECTOR (PSEUDO-COLLECTOR)
+// ============================================================================
+
+/**
+ * Built-in command collector for SSH strategy.
+ * Allows users to run arbitrary shell commands as check items.
+ * This is the "basic mode" functionality exposed as a collector.
+ */
+export class CommandCollector
+  implements
+    CollectorStrategy<
+      SshTransportClient,
+      CommandConfig,
+      CommandResult,
+      CommandAggregatedResult
+    >
+{
+  /**
+   * ID for this collector.
+   * Built-in collectors are identified by ownerPlugin matching the strategy's plugin.
+   * Fully-qualified: healthcheck-ssh.command
+   */
+  id = "command";
+  displayName = "Shell Command";
+  description = "Execute a shell command and check the result";
+
+  supportedPlugins = [sshPluginMetadata];
+
+  /** Allow multiple command instances per config */
+  allowMultiple = true;
+
+  config = new Versioned({ version: 1, schema: commandConfigSchema });
+  result = new Versioned({ version: 1, schema: commandResultSchema });
+  aggregatedResult = new Versioned({
+    version: 1,
+    schema: commandAggregatedSchema,
+  });
+
+  async execute({
+    config,
+    client,
+  }: {
+    config: CommandConfig;
+    client: SshTransportClient;
+    pluginId: string;
+  }): Promise<CollectorResult<CommandResult>> {
+    const startTime = Date.now();
+    const result = await client.exec(config.command);
+    const executionTimeMs = Date.now() - startTime;
+
+    return {
+      result: {
+        exitCode: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        executionTimeMs,
+      },
+    };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<CommandResult>[]
+  ): CommandAggregatedResult {
+    const times = runs
+      .map((r) => r.metadata?.executionTimeMs)
+      .filter((v): v is number => typeof v === "number");
+
+    const exitCodes = runs
+      .map((r) => r.metadata?.exitCode)
+      .filter((v): v is number => typeof v === "number");
+
+    const successCount = exitCodes.filter((code) => code === 0).length;
+
+    return {
+      avgExecutionTimeMs:
+        times.length > 0
+          ? Math.round(times.reduce((a, b) => a + b, 0) / times.length)
+          : 0,
+      successRate:
+        exitCodes.length > 0
+          ? Math.round((successCount / exitCodes.length) * 100)
+          : 0,
+    };
+  }
+}

package/src/index.ts

@@ -1,8 +1,6 @@
-import {
-  createBackendPlugin,
-  coreServices,
-} from "@checkstack/backend-api";
+import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
 import { SshHealthCheckStrategy } from "./strategy";
+import { CommandCollector } from "./command-collector";
 import { pluginMetadata } from "./plugin-metadata";
 
 export default createBackendPlugin({
@@ -11,12 +9,17 @@ export default createBackendPlugin({
     env.registerInit({
       deps: {
         healthCheckRegistry: coreServices.healthCheckRegistry,
+        collectorRegistry: coreServices.collectorRegistry,
         logger: coreServices.logger,
       },
-      init: async ({ healthCheckRegistry, logger }) => {
+      init: async ({ healthCheckRegistry, collectorRegistry, logger }) => {
         logger.debug("🔌 Registering SSH Health Check Strategy...");
         const strategy = new SshHealthCheckStrategy();
         healthCheckRegistry.register(strategy);
+
+        // Register the built-in command collector (allows "basic mode" via collector UI)
+        collectorRegistry.register(new CommandCollector());
+        logger.debug("   -> Registered __command__ collector");
       },
     });
   },

package/src/strategy.test.ts

@@ -30,11 +30,11 @@ describe("SshHealthCheckStrategy", () => {
     ),
   });
 
-  describe("execute", () => {
-    it("should return healthy for successful connection", async () => {
+  describe("createClient", () => {
+    it("should return a connected client for successful connection", async () => {
       const strategy = new SshHealthCheckStrategy(createMockClient());
 
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "localhost",
         port: 22,
         username: "user",
@@ -42,137 +42,70 @@ describe("SshHealthCheckStrategy", () => {
         timeout: 5000,
       });
 
-      expect(result.status).toBe("healthy");
-      expect(result.metadata?.connected).toBe(true);
-    });
-
-    it("should return healthy for successful command execution", async () => {
-      const strategy = new SshHealthCheckStrategy(
-        createMockClient({ exitCode: 0, stdout: "OK" })
-      );
-
-      const result = await strategy.execute({
-        host: "localhost",
-        port: 22,
-        username: "user",
-        password: "secret",
-        timeout: 5000,
-        command: "echo OK",
-      });
+      expect(connectedClient.client).toBeDefined();
+      expect(connectedClient.client.exec).toBeDefined();
+      expect(connectedClient.close).toBeDefined();
 
-      expect(result.status).toBe("healthy");
-      expect(result.metadata?.commandSuccess).toBe(true);
-      expect(result.metadata?.stdout).toBe("OK");
-      expect(result.metadata?.exitCode).toBe(0);
+      connectedClient.close();
     });
 
-    it("should return unhealthy for connection error", async () => {
+    it("should throw for connection error", async () => {
       const strategy = new SshHealthCheckStrategy(
         createMockClient({ connectError: new Error("Connection refused") })
       );
 
-      const result = await strategy.execute({
-        host: "localhost",
-        port: 22,
-        username: "user",
-        password: "secret",
-        timeout: 5000,
-      });
-
-      expect(result.status).toBe("unhealthy");
-      expect(result.message).toContain("Connection refused");
-      expect(result.metadata?.connected).toBe(false);
+      await expect(
+        strategy.createClient({
+          host: "localhost",
+          port: 22,
+          username: "user",
+          password: "secret",
+          timeout: 5000,
+        })
+      ).rejects.toThrow("Connection refused");
     });
+  });
 
-    it("should return unhealthy for non-zero exit code", async () => {
+  describe("client.exec", () => {
+    it("should execute command successfully", async () => {
       const strategy = new SshHealthCheckStrategy(
-        createMockClient({ exitCode: 1, stderr: "Error" })
+        createMockClient({ exitCode: 0, stdout: "OK" })
       );
-
-      const result = await strategy.execute({
-        host: "localhost",
-        port: 22,
-        username: "user",
-        password: "secret",
-        timeout: 5000,
-        command: "exit 1",
-      });
-
-      expect(result.status).toBe("unhealthy");
-      expect(result.metadata?.exitCode).toBe(1);
-      expect(result.metadata?.commandSuccess).toBe(false);
-    });
-
-    it("should pass connectionTime assertion when below threshold", async () => {
-      const strategy = new SshHealthCheckStrategy(createMockClient());
-
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "localhost",
         port: 22,
         username: "user",
         password: "secret",
         timeout: 5000,
-        assertions: [
-          { field: "connectionTime", operator: "lessThan", value: 5000 },
-        ],
       });
 
-      expect(result.status).toBe("healthy");
-    });
-
-    it("should pass exitCode assertion", async () => {
-      const strategy = new SshHealthCheckStrategy(
-        createMockClient({ exitCode: 0 })
-      );
+      // SSH transport client takes a string command
+      const result = await connectedClient.client.exec("echo OK");
 
-      const result = await strategy.execute({
-        host: "localhost",
-        port: 22,
-        username: "user",
-        password: "secret",
-        timeout: 5000,
-        command: "true",
-        assertions: [{ field: "exitCode", operator: "equals", value: 0 }],
-      });
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toBe("OK");
 
-      expect(result.status).toBe("healthy");
+      connectedClient.close();
     });
 
-    it("should fail exitCode assertion when non-zero", async () => {
+    it("should return non-zero exit code for failed command", async () => {
       const strategy = new SshHealthCheckStrategy(
-        createMockClient({ exitCode: 1 })
+        createMockClient({ exitCode: 1, stderr: "Error" })
       );
-
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "localhost",
         port: 22,
         username: "user",
         password: "secret",
         timeout: 5000,
-        command: "false",
-        assertions: [{ field: "exitCode", operator: "equals", value: 0 }],
       });
 
-      expect(result.status).toBe("unhealthy");
-      expect(result.message).toContain("Assertion failed");
-    });
-
-    it("should pass stdout assertion", async () => {
-      const strategy = new SshHealthCheckStrategy(
-        createMockClient({ stdout: "OK: Service running" })
-      );
+      const result = await connectedClient.client.exec("exit 1");
 
-      const result = await strategy.execute({
-        host: "localhost",
-        port: 22,
-        username: "user",
-        password: "secret",
-        timeout: 5000,
-        command: "systemctl status myservice",
-        assertions: [{ field: "stdout", operator: "contains", value: "OK" }],
-      });
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toBe("Error");
 
-      expect(result.status).toBe("healthy");
+      connectedClient.close();
     });
   });
 
@@ -189,9 +122,7 @@ describe("SshHealthCheckStrategy", () => {
           metadata: {
             connected: true,
             connectionTimeMs: 50,
-            commandTimeMs: 10,
             exitCode: 0,
-            commandSuccess: true,
           },
         },
         {
@@ -203,9 +134,7 @@ describe("SshHealthCheckStrategy", () => {
           metadata: {
             connected: true,
             connectionTimeMs: 100,
-            commandTimeMs: 20,
             exitCode: 0,
-            commandSuccess: true,
           },
         },
       ];
@@ -213,7 +142,6 @@ describe("SshHealthCheckStrategy", () => {
       const aggregated = strategy.aggregateResult(runs);
 
       expect(aggregated.avgConnectionTime).toBe(75);
-      expect(aggregated.avgCommandTime).toBe(15);
       expect(aggregated.successRate).toBe(100);
       expect(aggregated.errorCount).toBe(0);
     });
@@ -230,7 +158,6 @@ describe("SshHealthCheckStrategy", () => {
           metadata: {
             connected: false,
             connectionTimeMs: 100,
-            commandSuccess: false,
             error: "Connection refused",
           },
         },

package/src/strategy.ts

@@ -1,41 +1,24 @@
 import { Client } from "ssh2";
 import {
   HealthCheckStrategy,
-  HealthCheckResult,
   HealthCheckRunForAggregation,
   Versioned,
   z,
-  timeThresholdField,
-  numericField,
-  booleanField,
-  stringField,
-  evaluateAssertions,
   configString,
   configNumber,
+  type ConnectedClient,
 } from "@checkstack/backend-api";
 import {
   healthResultBoolean,
   healthResultNumber,
   healthResultString,
 } from "@checkstack/healthcheck-common";
+import type { SshTransportClient, SshCommandResult } from "./transport-client";
 
 // ============================================================================
 // SCHEMAS
 // ============================================================================
 
-/**
- * Assertion schema for SSH health checks using shared factories.
- */
-const sshAssertionSchema = z.discriminatedUnion("field", [
-  timeThresholdField("connectionTime"),
-  timeThresholdField("commandTime"),
-  numericField("exitCode", { min: 0 }),
-  booleanField("commandSuccess"),
-  stringField("stdout"),
-]);
-
-export type SshAssertion = z.infer<typeof sshAssertionSchema>;
-
 /**
  * Configuration schema for SSH health checks.
  */
@@ -56,13 +39,6 @@ export const sshConfigSchema = z.object({
     .min(100)
     .default(10_000)
     .describe("Connection timeout in milliseconds"),
-  command: configString({})
-    .optional()
-    .describe("Command to execute for health check (optional)"),
-  assertions: z
-    .array(sshAssertionSchema)
-    .optional()
-    .describe("Validation conditions"),
 });
 
 export type SshConfig = z.infer<typeof sshConfigSchema>;
@@ -81,35 +57,13 @@ const sshResultSchema = z.object({
     "x-chart-label": "Connection Time",
     "x-chart-unit": "ms",
   }),
-  commandTimeMs: healthResultNumber({
-    "x-chart-type": "line",
-    "x-chart-label": "Command Time",
-    "x-chart-unit": "ms",
-  }).optional(),
-  exitCode: healthResultNumber({
-    "x-chart-type": "counter",
-    "x-chart-label": "Exit Code",
-  }).optional(),
-  stdout: healthResultString({
-    "x-chart-type": "text",
-    "x-chart-label": "Stdout",
-  }).optional(),
-  stderr: healthResultString({
-    "x-chart-type": "text",
-    "x-chart-label": "Stderr",
-  }).optional(),
-  commandSuccess: healthResultBoolean({
-    "x-chart-type": "boolean",
-    "x-chart-label": "Command Success",
-  }),
-  failedAssertion: sshAssertionSchema.optional(),
   error: healthResultString({
     "x-chart-type": "status",
     "x-chart-label": "Error",
   }).optional(),
 });
 
-export type SshResult = z.infer<typeof sshResultSchema>;
+type SshResult = z.infer<typeof sshResultSchema>;
 
 /**
  * Aggregated metadata for buckets.
@@ -120,9 +74,9 @@ const sshAggregatedSchema = z.object({
     "x-chart-label": "Avg Connection Time",
     "x-chart-unit": "ms",
   }),
-  avgCommandTime: healthResultNumber({
+  maxConnectionTime: healthResultNumber({
     "x-chart-type": "line",
-    "x-chart-label": "Avg Command Time",
+    "x-chart-label": "Max Connection Time",
     "x-chart-unit": "ms",
   }),
   successRate: healthResultNumber({
@@ -136,18 +90,12 @@ const sshAggregatedSchema = z.object({
   }),
 });
 
-export type SshAggregatedResult = z.infer<typeof sshAggregatedSchema>;
+type SshAggregatedResult = z.infer<typeof sshAggregatedSchema>;
 
 // ============================================================================
 // SSH CLIENT INTERFACE (for testability)
 // ============================================================================
 
-export interface SshCommandResult {
-  exitCode: number;
-  stdout: string;
-  stderr: string;
-}
-
 export interface SshConnection {
   exec(command: string): Promise<SshCommandResult>;
   end(): void;
@@ -230,7 +178,13 @@ const defaultSshClient: SshClient = {
 // ============================================================================
 
 export class SshHealthCheckStrategy
-  implements HealthCheckStrategy<SshConfig, SshResult, SshAggregatedResult>
+  implements
+    HealthCheckStrategy<
+      SshConfig,
+      SshTransportClient,
+      SshResult,
+      SshAggregatedResult
+    >
 {
   id = "ssh";
   displayName = "SSH Health Check";
@@ -260,144 +214,71 @@ export class SshHealthCheckStrategy
   aggregateResult(
     runs: HealthCheckRunForAggregation<SshResult>[]
   ): SshAggregatedResult {
-    let totalConnectionTime = 0;
-    let totalCommandTime = 0;
-    let successCount = 0;
-    let errorCount = 0;
-    let validRuns = 0;
-    let commandRuns = 0;
-
-    for (const run of runs) {
-      if (run.metadata?.error) {
-        errorCount++;
-        continue;
-      }
-      if (run.status === "healthy") {
-        successCount++;
-      }
-      if (run.metadata) {
-        totalConnectionTime += run.metadata.connectionTimeMs;
-        if (run.metadata.commandTimeMs !== undefined) {
-          totalCommandTime += run.metadata.commandTimeMs;
-          commandRuns++;
-        }
-        validRuns++;
-      }
+    const validRuns = runs.filter((r) => r.metadata);
+
+    if (validRuns.length === 0) {
+      return {
+        avgConnectionTime: 0,
+        maxConnectionTime: 0,
+        successRate: 0,
+        errorCount: 0,
+      };
     }
 
+    const connectionTimes = validRuns
+      .map((r) => r.metadata?.connectionTimeMs)
+      .filter((t): t is number => typeof t === "number");
+
+    const avgConnectionTime =
+      connectionTimes.length > 0
+        ? Math.round(
+            connectionTimes.reduce((a, b) => a + b, 0) / connectionTimes.length
+          )
+        : 0;
+
+    const maxConnectionTime =
+      connectionTimes.length > 0 ? Math.max(...connectionTimes) : 0;
+
+    const successCount = validRuns.filter(
+      (r) => r.metadata?.connected === true
+    ).length;
+    const successRate = Math.round((successCount / validRuns.length) * 100);
+
+    const errorCount = validRuns.filter(
+      (r) => r.metadata?.error !== undefined
+    ).length;
+
     return {
-      avgConnectionTime: validRuns > 0 ? totalConnectionTime / validRuns : 0,
-      avgCommandTime: commandRuns > 0 ? totalCommandTime / commandRuns : 0,
-      successRate: runs.length > 0 ? (successCount / runs.length) * 100 : 0,
+      avgConnectionTime,
+      maxConnectionTime,
+      successRate,
       errorCount,
     };
   }
 
-  async execute(config: SshConfigInput): Promise<HealthCheckResult<SshResult>> {
+  /**
+   * Create a connected SSH transport client.
+   */
+  async createClient(
+    config: SshConfigInput
+  ): Promise<ConnectedClient<SshTransportClient>> {
     const validatedConfig = this.config.validate(config);
-    const start = performance.now();
-
-    try {
-      // Connect to SSH server
-      const connection = await this.sshClient.connect({
-        host: validatedConfig.host,
-        port: validatedConfig.port,
-        username: validatedConfig.username,
-        password: validatedConfig.password,
-        privateKey: validatedConfig.privateKey,
-        passphrase: validatedConfig.passphrase,
-        readyTimeout: validatedConfig.timeout,
-      });
-
-      const connectionTimeMs = Math.round(performance.now() - start);
-
-      let commandTimeMs: number | undefined;
-      let exitCode: number | undefined;
-      let stdout: string | undefined;
-      let stderr: string | undefined;
-      let commandSuccess = true;
-
-      // Execute command if provided
-      if (validatedConfig.command) {
-        const commandStart = performance.now();
-        try {
-          const result = await connection.exec(validatedConfig.command);
-          exitCode = result.exitCode;
-          stdout = result.stdout;
-          stderr = result.stderr;
-          commandSuccess = result.exitCode === 0;
-          commandTimeMs = Math.round(performance.now() - commandStart);
-        } catch {
-          commandSuccess = false;
-          commandTimeMs = Math.round(performance.now() - commandStart);
-        }
-      }
-
-      connection.end();
-
-      const result: Omit<SshResult, "failedAssertion" | "error"> = {
-        connected: true,
-        connectionTimeMs,
-        commandTimeMs,
-        exitCode,
-        stdout,
-        stderr,
-        commandSuccess,
-      };
-
-      // Evaluate assertions using shared utility
-      const failedAssertion = evaluateAssertions(validatedConfig.assertions, {
-        connectionTime: connectionTimeMs,
-        commandTime: commandTimeMs ?? 0,
-        exitCode: exitCode ?? 0,
-        commandSuccess,
-        stdout: stdout ?? "",
-      });
 
-      if (failedAssertion) {
-        return {
-          status: "unhealthy",
-          latencyMs: connectionTimeMs + (commandTimeMs ?? 0),
-          message: `Assertion failed: ${failedAssertion.field} ${
-            failedAssertion.operator
-          }${"value" in failedAssertion ? ` ${failedAssertion.value}` : ""}`,
-          metadata: { ...result, failedAssertion },
-        };
-      }
-
-      if (!commandSuccess && validatedConfig.command) {
-        return {
-          status: "unhealthy",
-          latencyMs: connectionTimeMs + (commandTimeMs ?? 0),
-          message: `Command failed with exit code ${exitCode}`,
-          metadata: result,
-        };
-      }
-
-      const message = validatedConfig.command
-        ? `SSH connected, command executed (exit ${exitCode}) in ${commandTimeMs}ms`
-        : `SSH connected in ${connectionTimeMs}ms`;
+    const connection = await this.sshClient.connect({
+      host: validatedConfig.host,
+      port: validatedConfig.port,
+      username: validatedConfig.username,
+      password: validatedConfig.password,
+      privateKey: validatedConfig.privateKey,
+      passphrase: validatedConfig.passphrase,
+      readyTimeout: validatedConfig.timeout,
+    });
 
-      return {
-        status: "healthy",
-        latencyMs: connectionTimeMs + (commandTimeMs ?? 0),
-        message,
-        metadata: result,
-      };
-    } catch (error: unknown) {
-      const end = performance.now();
-      const isError = error instanceof Error;
-      return {
-        status: "unhealthy",
-        latencyMs: Math.round(end - start),
-        message: isError ? error.message : "SSH connection failed",
-        metadata: {
-          connected: false,
-          connectionTimeMs: Math.round(end - start),
-          commandSuccess: false,
-          error: isError ? error.name : "UnknownError",
-        },
-      };
-    }
+    return {
+      client: {
+        exec: (command: string) => connection.exec(command),
+      },
+      close: () => connection.end(),
+    };
   }
 }

package/src/transport-client.ts

@@ -0,0 +1,19 @@
+import type { TransportClient } from "@checkstack/common";
+
+/**
+ * SSH command result from remote execution.
+ */
+export interface SshCommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * SSH transport client for collector execution.
+ * Implements the generic TransportClient interface with SSH command execution.
+ */
+export type SshTransportClient = TransportClient<string, SshCommandResult>;
+
+// Re-export for convenience
+export type { TransportClient } from "@checkstack/common";