@checkstack/healthcheck-script-backend 0.0.3 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @checkstack/healthcheck-script-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]
+  - @checkstack/backend-api@0.1.0
+  - @checkstack/healthcheck-common@0.1.0
+  - @checkstack/common@0.0.3
+
 ## 0.0.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-script-backend",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {

package/src/execute-collector.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, it, mock } from "bun:test";
+import { ExecuteCollector, type ExecuteConfig } from "./execute-collector";
+import type { ScriptTransportClient } from "./transport-client";
+
+describe("ExecuteCollector", () => {
+  const createMockClient = (
+    response: {
+      exitCode?: number;
+      stdout?: string;
+      stderr?: string;
+      timedOut?: boolean;
+      error?: string;
+    } = {}
+  ): ScriptTransportClient => ({
+    exec: mock(() =>
+      Promise.resolve({
+        exitCode: response.exitCode ?? 0,
+        stdout: response.stdout ?? "",
+        stderr: response.stderr ?? "",
+        timedOut: response.timedOut ?? false,
+        error: response.error,
+      })
+    ),
+  });
+
+  describe("execute", () => {
+    it("should execute script successfully", async () => {
+      const collector = new ExecuteCollector();
+      const client = createMockClient({ exitCode: 0, stdout: "Hello World" });
+
+      const result = await collector.execute({
+        config: { command: "echo", args: ["Hello", "World"], timeout: 5000 },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.exitCode).toBe(0);
+      expect(result.result.stdout).toBe("Hello World");
+      expect(result.result.success).toBe(true);
+      expect(result.result.timedOut).toBe(false);
+      expect(result.result.executionTimeMs).toBeGreaterThanOrEqual(0);
+      expect(result.error).toBeUndefined();
+    });
+
+    it("should return error for failed script", async () => {
+      const collector = new ExecuteCollector();
+      const client = createMockClient({
+        exitCode: 1,
+        stderr: "Command not found",
+      });
+
+      const result = await collector.execute({
+        config: { command: "nonexistent", args: [], timeout: 5000 },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.exitCode).toBe(1);
+      expect(result.result.success).toBe(false);
+      expect(result.error).toContain("Exit code: 1");
+    });
+
+    it("should handle timeout", async () => {
+      const collector = new ExecuteCollector();
+      const client = createMockClient({ timedOut: true, exitCode: -1 });
+
+      const result = await collector.execute({
+        config: { command: "sleep", args: ["999"], timeout: 100 },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.timedOut).toBe(true);
+      expect(result.result.success).toBe(false);
+    });
+
+    it("should pass correct parameters to client", async () => {
+      const collector = new ExecuteCollector();
+      const client = createMockClient();
+
+      await collector.execute({
+        config: {
+          command: "/usr/bin/check",
+          args: ["--verbose"],
+          cwd: "/tmp",
+          env: { MY_VAR: "value" },
+          timeout: 3000,
+        },
+        client,
+        pluginId: "test",
+      });
+
+      expect(client.exec).toHaveBeenCalledWith({
+        command: "/usr/bin/check",
+        args: ["--verbose"],
+        cwd: "/tmp",
+        env: { MY_VAR: "value" },
+        timeout: 3000,
+      });
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate average execution time and success rate", () => {
+      const collector = new ExecuteCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            exitCode: 0,
+            stdout: "",
+            stderr: "",
+            executionTimeMs: 50,
+            success: true,
+            timedOut: false,
+          },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 150,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            exitCode: 0,
+            stdout: "",
+            stderr: "",
+            executionTimeMs: 100,
+            success: true,
+            timedOut: false,
+          },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.avgExecutionTimeMs).toBe(75);
+      expect(aggregated.successRate).toBe(100);
+    });
+
+    it("should calculate success rate correctly", () => {
+      const collector = new ExecuteCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            exitCode: 0,
+            stdout: "",
+            stderr: "",
+            executionTimeMs: 50,
+            success: true,
+            timedOut: false,
+          },
+        },
+        {
+          id: "2",
+          status: "unhealthy" as const,
+          latencyMs: 150,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            exitCode: 1,
+            stdout: "",
+            stderr: "",
+            executionTimeMs: 100,
+            success: false,
+            timedOut: false,
+          },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.successRate).toBe(50);
+    });
+  });
+
+  describe("metadata", () => {
+    it("should have correct static properties", () => {
+      const collector = new ExecuteCollector();
+
+      expect(collector.id).toBe("execute");
+      expect(collector.displayName).toBe("Execute Script");
+      expect(collector.allowMultiple).toBe(true);
+      expect(collector.supportedPlugins).toHaveLength(1);
+    });
+  });
+});

package/src/execute-collector.ts

@@ -0,0 +1,178 @@
+import {
+  Versioned,
+  z,
+  type HealthCheckRunForAggregation,
+  type CollectorResult,
+  type CollectorStrategy,
+} from "@checkstack/backend-api";
+import {
+  healthResultNumber,
+  healthResultString,
+  healthResultBoolean,
+} from "@checkstack/healthcheck-common";
+import { pluginMetadata } from "./plugin-metadata";
+import type { ScriptTransportClient } from "./transport-client";
+
+// ============================================================================
+// CONFIGURATION SCHEMA
+// ============================================================================
+
+const executeConfigSchema = z.object({
+  command: z.string().min(1).describe("Command or script path to execute"),
+  args: z.array(z.string()).default([]).describe("Command arguments"),
+  cwd: z.string().optional().describe("Working directory"),
+  env: z
+    .record(z.string(), z.string())
+    .optional()
+    .describe("Environment variables"),
+  timeout: z
+    .number()
+    .min(100)
+    .default(30_000)
+    .describe("Timeout in milliseconds"),
+});
+
+export type ExecuteConfig = z.infer<typeof executeConfigSchema>;
+
+// ============================================================================
+// RESULT SCHEMAS
+// ============================================================================
+
+const executeResultSchema = 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",
+  }),
+  success: healthResultBoolean({
+    "x-chart-type": "boolean",
+    "x-chart-label": "Success",
+  }),
+  timedOut: healthResultBoolean({
+    "x-chart-type": "boolean",
+    "x-chart-label": "Timed Out",
+  }),
+});
+
+export type ExecuteResult = z.infer<typeof executeResultSchema>;
+
+const executeAggregatedSchema = 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 ExecuteAggregatedResult = z.infer<typeof executeAggregatedSchema>;
+
+// ============================================================================
+// EXECUTE COLLECTOR
+// ============================================================================
+
+/**
+ * Built-in Script execute collector.
+ * Runs commands and checks results.
+ */
+export class ExecuteCollector
+  implements
+    CollectorStrategy<
+      ScriptTransportClient,
+      ExecuteConfig,
+      ExecuteResult,
+      ExecuteAggregatedResult
+    >
+{
+  id = "execute";
+  displayName = "Execute Script";
+  description = "Execute a command or script and check the result";
+
+  supportedPlugins = [pluginMetadata];
+
+  allowMultiple = true;
+
+  config = new Versioned({ version: 1, schema: executeConfigSchema });
+  result = new Versioned({ version: 1, schema: executeResultSchema });
+  aggregatedResult = new Versioned({
+    version: 1,
+    schema: executeAggregatedSchema,
+  });
+
+  async execute({
+    config,
+    client,
+  }: {
+    config: ExecuteConfig;
+    client: ScriptTransportClient;
+    pluginId: string;
+  }): Promise<CollectorResult<ExecuteResult>> {
+    const startTime = Date.now();
+
+    const response = await client.exec({
+      command: config.command,
+      args: config.args,
+      cwd: config.cwd,
+      env: config.env,
+      timeout: config.timeout,
+    });
+
+    const executionTimeMs = Date.now() - startTime;
+    const success = response.exitCode === 0 && !response.timedOut;
+
+    return {
+      result: {
+        exitCode: response.exitCode,
+        stdout: response.stdout,
+        stderr: response.stderr,
+        executionTimeMs,
+        success,
+        timedOut: response.timedOut,
+      },
+      error:
+        response.error ??
+        (success ? undefined : `Exit code: ${response.exitCode}`),
+    };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<ExecuteResult>[]
+  ): ExecuteAggregatedResult {
+    const times = runs
+      .map((r) => r.metadata?.executionTimeMs)
+      .filter((v): v is number => typeof v === "number");
+
+    const successes = runs
+      .map((r) => r.metadata?.success)
+      .filter((v): v is boolean => typeof v === "boolean");
+
+    const successCount = successes.filter(Boolean).length;
+
+    return {
+      avgExecutionTimeMs:
+        times.length > 0
+          ? Math.round(times.reduce((a, b) => a + b, 0) / times.length)
+          : 0,
+      successRate:
+        successes.length > 0
+          ? Math.round((successCount / successes.length) * 100)
+          : 0,
+    };
+  }
+}

package/src/index.ts

@@ -1,9 +1,7 @@
-import {
-  createBackendPlugin,
-  coreServices,
-} from "@checkstack/backend-api";
+import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
 import { ScriptHealthCheckStrategy } from "./strategy";
 import { pluginMetadata } from "./plugin-metadata";
+import { ExecuteCollector } from "./execute-collector";
 
 export default createBackendPlugin({
   metadata: pluginMetadata,
@@ -11,13 +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 Script Health Check Strategy...");
         const strategy = new ScriptHealthCheckStrategy();
         healthCheckRegistry.register(strategy);
+        collectorRegistry.register(new ExecuteCollector());
       },
     });
   },
 });
+
+export { pluginMetadata } from "./plugin-metadata";

package/src/strategy.test.ts

@@ -24,134 +24,100 @@ describe("ScriptHealthCheckStrategy", () => {
     ),
   });
 
-  describe("execute", () => {
-    it("should return healthy for successful script execution", async () => {
+  describe("createClient", () => {
+    it("should return a connected client", async () => {
+      const strategy = new ScriptHealthCheckStrategy(createMockExecutor());
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
+
+      expect(connectedClient.client).toBeDefined();
+      expect(connectedClient.client.exec).toBeDefined();
+      expect(connectedClient.close).toBeDefined();
+    });
+
+    it("should allow closing the client", async () => {
+      const strategy = new ScriptHealthCheckStrategy(createMockExecutor());
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
+
+      expect(() => connectedClient.close()).not.toThrow();
+    });
+  });
+
+  describe("client.exec", () => {
+    it("should return successful result for successful script execution", async () => {
       const strategy = new ScriptHealthCheckStrategy(
         createMockExecutor({ exitCode: 0, stdout: "OK" })
       );
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
 
-      const result = await strategy.execute({
+      const result = await connectedClient.client.exec({
         command: "/usr/bin/true",
+        args: [],
         timeout: 5000,
       });
 
-      expect(result.status).toBe("healthy");
-      expect(result.metadata?.executed).toBe(true);
-      expect(result.metadata?.success).toBe(true);
-      expect(result.metadata?.exitCode).toBe(0);
+      expect(result.exitCode).toBe(0);
+      expect(result.timedOut).toBe(false);
+
+      connectedClient.close();
     });
 
-    it("should return unhealthy for non-zero exit code", async () => {
+    it("should return non-zero exit code for failed script", async () => {
       const strategy = new ScriptHealthCheckStrategy(
         createMockExecutor({ exitCode: 1, stderr: "Error" })
       );
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
 
-      const result = await strategy.execute({
+      const result = await connectedClient.client.exec({
         command: "/usr/bin/false",
+        args: [],
         timeout: 5000,
       });
 
-      expect(result.status).toBe("unhealthy");
-      expect(result.metadata?.exitCode).toBe(1);
-      expect(result.metadata?.success).toBe(false);
+      expect(result.exitCode).toBe(1);
+
+      connectedClient.close();
     });
 
-    it("should return unhealthy for timeout", async () => {
+    it("should indicate timeout for timed out script", async () => {
       const strategy = new ScriptHealthCheckStrategy(
         createMockExecutor({ timedOut: true, exitCode: -1 })
       );
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
 
-      const result = await strategy.execute({
+      const result = await connectedClient.client.exec({
         command: "sleep",
         args: ["60"],
         timeout: 1000,
       });
 
-      expect(result.status).toBe("unhealthy");
-      expect(result.message).toContain("timed out");
-      expect(result.metadata?.timedOut).toBe(true);
+      expect(result.timedOut).toBe(true);
+
+      connectedClient.close();
     });
 
-    it("should return unhealthy for execution error", async () => {
+    it("should return error for execution error", async () => {
       const strategy = new ScriptHealthCheckStrategy(
         createMockExecutor({ error: new Error("Command not found") })
       );
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
 
-      const result = await strategy.execute({
+      const result = await connectedClient.client.exec({
         command: "nonexistent-command",
+        args: [],
         timeout: 5000,
       });
 
-      expect(result.status).toBe("unhealthy");
-      expect(result.message).toContain("Command not found");
-      expect(result.metadata?.executed).toBe(false);
-    });
-
-    it("should pass executionTime assertion when below threshold", async () => {
-      const strategy = new ScriptHealthCheckStrategy(createMockExecutor());
-
-      const result = await strategy.execute({
-        command: "/usr/bin/true",
-        timeout: 5000,
-        assertions: [
-          { field: "executionTime", operator: "lessThan", value: 5000 },
-        ],
-      });
-
-      expect(result.status).toBe("healthy");
-    });
-
-    it("should pass exitCode assertion", async () => {
-      const strategy = new ScriptHealthCheckStrategy(
-        createMockExecutor({ exitCode: 0 })
-      );
-
-      const result = await strategy.execute({
-        command: "/usr/bin/true",
-        timeout: 5000,
-        assertions: [{ field: "exitCode", operator: "equals", value: 0 }],
-      });
-
-      expect(result.status).toBe("healthy");
-    });
-
-    it("should fail exitCode assertion when non-zero", async () => {
-      const strategy = new ScriptHealthCheckStrategy(
-        createMockExecutor({ exitCode: 2 })
-      );
+      expect(result.error).toContain("Command not found");
 
-      const result = await strategy.execute({
-        command: "/usr/bin/false",
-        timeout: 5000,
-        assertions: [{ field: "exitCode", operator: "equals", value: 0 }],
-      });
-
-      expect(result.status).toBe("unhealthy");
-      expect(result.message).toContain("Assertion failed");
+      connectedClient.close();
     });
 
-    it("should pass stdout assertion", async () => {
-      const strategy = new ScriptHealthCheckStrategy(
-        createMockExecutor({ stdout: "Service is running" })
-      );
-
-      const result = await strategy.execute({
-        command: "/usr/bin/echo",
-        args: ["Service is running"],
-        timeout: 5000,
-        assertions: [
-          { field: "stdout", operator: "contains", value: "running" },
-        ],
-      });
-
-      expect(result.status).toBe("healthy");
-    });
-
-    it("should pass with arguments and env vars", async () => {
+    it("should pass arguments, cwd, and env to executor", async () => {
       const mockExecutor = createMockExecutor({ exitCode: 0 });
       const strategy = new ScriptHealthCheckStrategy(mockExecutor);
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
 
-      await strategy.execute({
+      await connectedClient.client.exec({
         command: "./check.sh",
         args: ["--verbose", "--env=prod"],
         cwd: "/opt/scripts",
@@ -167,6 +133,8 @@ describe("ScriptHealthCheckStrategy", () => {
           env: { API_KEY: "secret" },
         })
       );
+
+      connectedClient.close();
     });
   });
 

package/src/strategy.ts

@@ -1,66 +1,50 @@
 import { spawn, type Subprocess } from "bun";
 import {
   HealthCheckStrategy,
-  HealthCheckResult,
   HealthCheckRunForAggregation,
   Versioned,
   z,
-  timeThresholdField,
-  numericField,
-  booleanField,
-  stringField,
-  evaluateAssertions,
+  type ConnectedClient,
 } from "@checkstack/backend-api";
 import {
   healthResultBoolean,
   healthResultNumber,
   healthResultString,
 } from "@checkstack/healthcheck-common";
+import type {
+  ScriptTransportClient,
+  ScriptRequest,
+  ScriptResult as ScriptResultType,
+} from "./transport-client";
 
 // ============================================================================
 // SCHEMAS
 // ============================================================================
 
-/**
- * Assertion schema for Script health checks using shared factories.
- */
-const scriptAssertionSchema = z.discriminatedUnion("field", [
-  timeThresholdField("executionTime"),
-  numericField("exitCode", { min: 0 }),
-  booleanField("success"),
-  stringField("stdout"),
-]);
-
-export type ScriptAssertion = z.infer<typeof scriptAssertionSchema>;
-
 /**
  * Configuration schema for Script health checks.
+ * Global defaults only - action params moved to ExecuteCollector.
  */
 export const scriptConfigSchema = z.object({
-  command: z.string().describe("Command or script path to execute"),
-  args: z
-    .array(z.string())
-    .default([])
-    .describe("Arguments to pass to the command"),
-  cwd: z.string().optional().describe("Working directory for script execution"),
-  env: z
-    .record(z.string(), z.string())
-    .optional()
-    .describe("Environment variables to set"),
   timeout: z
     .number()
     .min(100)
     .default(30_000)
-    .describe("Execution timeout in milliseconds"),
-  assertions: z
-    .array(scriptAssertionSchema)
-    .optional()
-    .describe("Validation conditions"),
+    .describe("Default execution timeout in milliseconds"),
 });
 
 export type ScriptConfig = z.infer<typeof scriptConfigSchema>;
 export type ScriptConfigInput = z.input<typeof scriptConfigSchema>;
 
+// Legacy config type for migrations
+interface ScriptConfigV1 {
+  command: string;
+  args: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  timeout: number;
+}
+
 /**
  * Per-run result metadata.
  */
@@ -78,14 +62,6 @@ const scriptResultSchema = z.object({
     "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(),
   success: healthResultBoolean({
     "x-chart-type": "boolean",
     "x-chart-label": "Success",
@@ -94,14 +70,13 @@ const scriptResultSchema = z.object({
     "x-chart-type": "boolean",
     "x-chart-label": "Timed Out",
   }),
-  failedAssertion: scriptAssertionSchema.optional(),
   error: healthResultString({
     "x-chart-type": "status",
     "x-chart-label": "Error",
   }).optional(),
 });
 
-export type ScriptResult = z.infer<typeof scriptResultSchema>;
+type ScriptResult = z.infer<typeof scriptResultSchema>;
 
 /**
  * Aggregated metadata for buckets.
@@ -127,13 +102,13 @@ const scriptAggregatedSchema = z.object({
   }),
 });
 
-export type ScriptAggregatedResult = z.infer<typeof scriptAggregatedSchema>;
+type ScriptAggregatedResult = z.infer<typeof scriptAggregatedSchema>;
 
 // ============================================================================
 // SCRIPT EXECUTOR INTERFACE (for testability)
 // ============================================================================
 
-export interface ScriptExecutionResult {
+interface ScriptExecutionResult {
   exitCode: number;
   stdout: string;
   stderr: string;
@@ -164,7 +139,7 @@ const defaultScriptExecutor: ScriptExecutor = {
       }, config.timeout);
     });
 
-    const execPromise = (async () => {
+    try {
       proc = spawn({
         cmd: [config.command, ...config.args],
         cwd: config.cwd,
@@ -173,15 +148,14 @@ const defaultScriptExecutor: ScriptExecutor = {
         stderr: "pipe",
       });
 
-      const stdoutStream = proc.stdout;
-      const stderrStream = proc.stderr;
-      const stdout = stdoutStream
-        ? await new Response(stdoutStream as unknown as ReadableStream).text()
-        : "";
-      const stderr = stderrStream
-        ? await new Response(stderrStream as unknown as ReadableStream).text()
-        : "";
-      const exitCode = await proc.exited;
+      const [stdout, stderr, exitCode] = await Promise.race([
+        Promise.all([
+          new Response(proc.stdout as ReadableStream).text(),
+          new Response(proc.stderr as ReadableStream).text(),
+          proc.exited,
+        ]),
+        timeoutPromise,
+      ]);
 
       return {
         exitCode,
@@ -189,10 +163,6 @@ const defaultScriptExecutor: ScriptExecutor = {
         stderr: stderr.trim(),
         timedOut: false,
       };
-    })();
-
-    try {
-      return await Promise.race([execPromise, timeoutPromise]);
     } catch (error) {
       if (timedOut) {
         return {
@@ -213,7 +183,12 @@ const defaultScriptExecutor: ScriptExecutor = {
 
 export class ScriptHealthCheckStrategy
   implements
-    HealthCheckStrategy<ScriptConfig, ScriptResult, ScriptAggregatedResult>
+    HealthCheckStrategy<
+      ScriptConfig,
+      ScriptTransportClient,
+      ScriptResult,
+      ScriptAggregatedResult
+    >
 {
   id = "script";
   displayName = "Script Health Check";
@@ -226,13 +201,31 @@ export class ScriptHealthCheckStrategy
   }
 
   config: Versioned<ScriptConfig> = new Versioned({
-    version: 1,
+    version: 2,
     schema: scriptConfigSchema,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        description: "Remove command/args/cwd/env (moved to ExecuteCollector)",
+        migrate: (data: ScriptConfigV1): ScriptConfig => ({
+          timeout: data.timeout,
+        }),
+      },
+    ],
   });
 
   result: Versioned<ScriptResult> = new Versioned({
-    version: 1,
+    version: 2,
     schema: scriptResultSchema,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        description: "Migrate to createClient pattern (no result changes)",
+        migrate: (data: unknown) => data,
+      },
+    ],
   });
 
   aggregatedResult: Versioned<ScriptAggregatedResult> = new Versioned({
@@ -243,123 +236,86 @@ export class ScriptHealthCheckStrategy
   aggregateResult(
     runs: HealthCheckRunForAggregation<ScriptResult>[]
   ): ScriptAggregatedResult {
-    let totalExecutionTime = 0;
-    let successCount = 0;
-    let errorCount = 0;
-    let timeoutCount = 0;
-    let validRuns = 0;
-
-    for (const run of runs) {
-      if (run.metadata?.error) {
-        errorCount++;
-        continue;
-      }
-      if (run.metadata?.timedOut) {
-        timeoutCount++;
-      }
-      if (run.status === "healthy") {
-        successCount++;
-      }
-      if (run.metadata) {
-        totalExecutionTime += run.metadata.executionTimeMs;
-        validRuns++;
-      }
-    }
+    const validRuns = runs.filter((r) => r.metadata);
 
-    return {
-      avgExecutionTime: validRuns > 0 ? totalExecutionTime / validRuns : 0,
-      successRate: runs.length > 0 ? (successCount / runs.length) * 100 : 0,
-      errorCount,
-      timeoutCount,
-    };
-  }
+    if (validRuns.length === 0) {
+      return {
+        avgExecutionTime: 0,
+        successRate: 0,
+        errorCount: 0,
+        timeoutCount: 0,
+      };
+    }
 
-  async execute(
-    config: ScriptConfigInput
-  ): Promise<HealthCheckResult<ScriptResult>> {
-    const validatedConfig = this.config.validate(config);
-    const start = performance.now();
+    const executionTimes = validRuns
+      .map((r) => r.metadata?.executionTimeMs)
+      .filter((t): t is number => typeof t === "number");
 
-    try {
-      const execResult = await this.executor.execute({
-        command: validatedConfig.command,
-        args: validatedConfig.args,
-        cwd: validatedConfig.cwd,
-        env: validatedConfig.env as Record<string, string> | undefined,
-        timeout: validatedConfig.timeout,
-      });
+    const avgExecutionTime =
+      executionTimes.length > 0
+        ? Math.round(
+            executionTimes.reduce((a, b) => a + b, 0) / executionTimes.length
+          )
+        : 0;
 
-      const executionTimeMs = Math.round(performance.now() - start);
-      const success = execResult.exitCode === 0 && !execResult.timedOut;
-
-      const result: Omit<ScriptResult, "failedAssertion" | "error"> = {
-        executed: true,
-        executionTimeMs,
-        exitCode: execResult.exitCode,
-        stdout: execResult.stdout,
-        stderr: execResult.stderr,
-        success,
-        timedOut: execResult.timedOut,
-      };
+    const successCount = validRuns.filter(
+      (r) => r.metadata?.success === true
+    ).length;
+    const successRate = Math.round((successCount / validRuns.length) * 100);
 
-      // Evaluate assertions using shared utility
-      const failedAssertion = evaluateAssertions(validatedConfig.assertions, {
-        executionTime: executionTimeMs,
-        exitCode: execResult.exitCode,
-        success,
-        stdout: execResult.stdout,
-      });
+    const errorCount = validRuns.filter(
+      (r) => r.metadata?.error !== undefined
+    ).length;
 
-      if (failedAssertion) {
-        return {
-          status: "unhealthy",
-          latencyMs: executionTimeMs,
-          message: `Assertion failed: ${failedAssertion.field} ${
-            failedAssertion.operator
-          }${"value" in failedAssertion ? ` ${failedAssertion.value}` : ""}`,
-          metadata: { ...result, failedAssertion },
-        };
-      }
+    const timeoutCount = validRuns.filter(
+      (r) => r.metadata?.timedOut === true
+    ).length;
 
-      if (execResult.timedOut) {
-        return {
-          status: "unhealthy",
-          latencyMs: executionTimeMs,
-          message: `Script timed out after ${validatedConfig.timeout}ms`,
-          metadata: result,
-        };
-      }
+    return {
+      avgExecutionTime,
+      successRate,
+      errorCount,
+      timeoutCount,
+    };
+  }
 
-      if (!success) {
-        return {
-          status: "unhealthy",
-          latencyMs: executionTimeMs,
-          message: `Script failed with exit code ${execResult.exitCode}`,
-          metadata: result,
-        };
-      }
+  async createClient(
+    _config: ScriptConfigInput
+  ): Promise<ConnectedClient<ScriptTransportClient>> {
+    const client: ScriptTransportClient = {
+      exec: async (request: ScriptRequest): Promise<ScriptResultType> => {
+        try {
+          const result = await this.executor.execute({
+            command: request.command,
+            args: request.args,
+            cwd: request.cwd,
+            env: request.env,
+            timeout: request.timeout,
+          });
+
+          return {
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            timedOut: result.timedOut,
+          };
+        } catch (error) {
+          return {
+            exitCode: -1,
+            stdout: "",
+            stderr: "",
+            timedOut: false,
+            error: error instanceof Error ? error.message : String(error),
+          };
+        }
+      },
+    };
 
-      return {
-        status: "healthy",
-        latencyMs: executionTimeMs,
-        message: `Script executed successfully (exit 0) in ${executionTimeMs}ms`,
-        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 : "Script execution failed",
-        metadata: {
-          executed: false,
-          executionTimeMs: Math.round(end - start),
-          success: false,
-          timedOut: false,
-          error: isError ? error.name : "UnknownError",
-        },
-      };
-    }
+    return {
+      client,
+      close: () => {
+        // Script executor is stateless, nothing to close
+      },
+    };
   }
 }

package/src/transport-client.ts

@@ -0,0 +1,31 @@
+import type { TransportClient } from "@checkstack/common";
+
+/**
+ * Script execution request.
+ */
+export interface ScriptRequest {
+  command: string;
+  args: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  timeout: number;
+}
+
+/**
+ * Script execution result.
+ */
+export interface ScriptResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  error?: string;
+}
+
+/**
+ * Script transport client for command execution.
+ */
+export type ScriptTransportClient = TransportClient<
+  ScriptRequest,
+  ScriptResult
+>;