@checkstack/healthcheck-script-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# @checkstack/healthcheck-script-backend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/backend-api@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/healthcheck-common@0.0.2
+
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+  - @checkstack/backend-api@1.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/healthcheck-common@0.1.1
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [4dd644d]
+- Updated dependencies [71275dd]
+- Updated dependencies [ae19ff6]
+- Updated dependencies [0babb9c]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+- Updated dependencies [81f3f85]
+  - @checkstack/common@0.1.0
+  - @checkstack/backend-api@1.0.0
+  - @checkstack/healthcheck-common@0.1.0

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@checkstack/healthcheck-script-backend",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@checkstack/healthcheck-common": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.0.0",
+    "typescript": "^5.0.0",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+import {
+  createBackendPlugin,
+  coreServices,
+} from "@checkstack/backend-api";
+import { ScriptHealthCheckStrategy } from "./strategy";
+import { pluginMetadata } from "./plugin-metadata";
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+  register(env) {
+    env.registerInit({
+      deps: {
+        healthCheckRegistry: coreServices.healthCheckRegistry,
+        logger: coreServices.logger,
+      },
+      init: async ({ healthCheckRegistry, logger }) => {
+        logger.debug("🔌 Registering Script Health Check Strategy...");
+        const strategy = new ScriptHealthCheckStrategy();
+        healthCheckRegistry.register(strategy);
+      },
+    });
+  },
+});

package/src/plugin-metadata.ts

@@ -0,0 +1,8 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the Script Health Check backend.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "healthcheck-script",
+});

package/src/strategy.test.ts

@@ -0,0 +1,255 @@
+import { describe, expect, it, mock } from "bun:test";
+import { ScriptHealthCheckStrategy, ScriptExecutor } from "./strategy";
+
+describe("ScriptHealthCheckStrategy", () => {
+  // Helper to create mock Script executor
+  const createMockExecutor = (
+    config: {
+      exitCode?: number;
+      stdout?: string;
+      stderr?: string;
+      timedOut?: boolean;
+      error?: Error;
+    } = {}
+  ): ScriptExecutor => ({
+    execute: mock(() =>
+      config.error
+        ? Promise.reject(config.error)
+        : Promise.resolve({
+            exitCode: config.exitCode ?? 0,
+            stdout: config.stdout ?? "",
+            stderr: config.stderr ?? "",
+            timedOut: config.timedOut ?? false,
+          })
+    ),
+  });
+
+  describe("execute", () => {
+    it("should return healthy for successful script execution", async () => {
+      const strategy = new ScriptHealthCheckStrategy(
+        createMockExecutor({ exitCode: 0, stdout: "OK" })
+      );
+
+      const result = await strategy.execute({
+        command: "/usr/bin/true",
+        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);
+    });
+
+    it("should return unhealthy for non-zero exit code", async () => {
+      const strategy = new ScriptHealthCheckStrategy(
+        createMockExecutor({ exitCode: 1, stderr: "Error" })
+      );
+
+      const result = await strategy.execute({
+        command: "/usr/bin/false",
+        timeout: 5000,
+      });
+
+      expect(result.status).toBe("unhealthy");
+      expect(result.metadata?.exitCode).toBe(1);
+      expect(result.metadata?.success).toBe(false);
+    });
+
+    it("should return unhealthy for timeout", async () => {
+      const strategy = new ScriptHealthCheckStrategy(
+        createMockExecutor({ timedOut: true, exitCode: -1 })
+      );
+
+      const result = await strategy.execute({
+        command: "sleep",
+        args: ["60"],
+        timeout: 1000,
+      });
+
+      expect(result.status).toBe("unhealthy");
+      expect(result.message).toContain("timed out");
+      expect(result.metadata?.timedOut).toBe(true);
+    });
+
+    it("should return unhealthy for execution error", async () => {
+      const strategy = new ScriptHealthCheckStrategy(
+        createMockExecutor({ error: new Error("Command not found") })
+      );
+
+      const result = await strategy.execute({
+        command: "nonexistent-command",
+        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 })
+      );
+
+      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");
+    });
+
+    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 () => {
+      const mockExecutor = createMockExecutor({ exitCode: 0 });
+      const strategy = new ScriptHealthCheckStrategy(mockExecutor);
+
+      await strategy.execute({
+        command: "./check.sh",
+        args: ["--verbose", "--env=prod"],
+        cwd: "/opt/scripts",
+        env: { API_KEY: "secret" },
+        timeout: 5000,
+      });
+
+      expect(mockExecutor.execute).toHaveBeenCalledWith(
+        expect.objectContaining({
+          command: "./check.sh",
+          args: ["--verbose", "--env=prod"],
+          cwd: "/opt/scripts",
+          env: { API_KEY: "secret" },
+        })
+      );
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate averages correctly", () => {
+      const strategy = new ScriptHealthCheckStrategy();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            executed: true,
+            executionTimeMs: 50,
+            exitCode: 0,
+            success: true,
+            timedOut: false,
+          },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 150,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            executed: true,
+            executionTimeMs: 100,
+            exitCode: 0,
+            success: true,
+            timedOut: false,
+          },
+        },
+      ];
+
+      const aggregated = strategy.aggregateResult(runs);
+
+      expect(aggregated.avgExecutionTime).toBe(75);
+      expect(aggregated.successRate).toBe(100);
+      expect(aggregated.errorCount).toBe(0);
+      expect(aggregated.timeoutCount).toBe(0);
+    });
+
+    it("should count errors and timeouts", () => {
+      const strategy = new ScriptHealthCheckStrategy();
+      const runs = [
+        {
+          id: "1",
+          status: "unhealthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            executed: false,
+            executionTimeMs: 100,
+            success: false,
+            timedOut: false,
+            error: "Command not found",
+          },
+        },
+        {
+          id: "2",
+          status: "unhealthy" as const,
+          latencyMs: 1000,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            executed: true,
+            executionTimeMs: 1000,
+            exitCode: -1,
+            success: false,
+            timedOut: true,
+          },
+        },
+      ];
+
+      const aggregated = strategy.aggregateResult(runs);
+
+      expect(aggregated.errorCount).toBe(1);
+      expect(aggregated.timeoutCount).toBe(1);
+      expect(aggregated.successRate).toBe(0);
+    });
+  });
+});

package/src/strategy.ts

@@ -0,0 +1,365 @@
+import { spawn, type Subprocess } from "bun";
+import {
+  HealthCheckStrategy,
+  HealthCheckResult,
+  HealthCheckRunForAggregation,
+  Versioned,
+  z,
+  timeThresholdField,
+  numericField,
+  booleanField,
+  stringField,
+  evaluateAssertions,
+} from "@checkstack/backend-api";
+import {
+  healthResultBoolean,
+  healthResultNumber,
+  healthResultString,
+} from "@checkstack/healthcheck-common";
+
+// ============================================================================
+// 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.
+ */
+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"),
+});
+
+export type ScriptConfig = z.infer<typeof scriptConfigSchema>;
+export type ScriptConfigInput = z.input<typeof scriptConfigSchema>;
+
+/**
+ * Per-run result metadata.
+ */
+const scriptResultSchema = z.object({
+  executed: healthResultBoolean({
+    "x-chart-type": "boolean",
+    "x-chart-label": "Executed",
+  }),
+  executionTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Execution Time",
+    "x-chart-unit": "ms",
+  }),
+  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(),
+  success: healthResultBoolean({
+    "x-chart-type": "boolean",
+    "x-chart-label": "Success",
+  }),
+  timedOut: healthResultBoolean({
+    "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>;
+
+/**
+ * Aggregated metadata for buckets.
+ */
+const scriptAggregatedSchema = z.object({
+  avgExecutionTime: 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": "%",
+  }),
+  errorCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Errors",
+  }),
+  timeoutCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Timeouts",
+  }),
+});
+
+export type ScriptAggregatedResult = z.infer<typeof scriptAggregatedSchema>;
+
+// ============================================================================
+// SCRIPT EXECUTOR INTERFACE (for testability)
+// ============================================================================
+
+export interface ScriptExecutionResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+}
+
+export interface ScriptExecutor {
+  execute(config: {
+    command: string;
+    args: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeout: number;
+  }): Promise<ScriptExecutionResult>;
+}
+
+// Default executor using Bun.spawn
+const defaultScriptExecutor: ScriptExecutor = {
+  async execute(config) {
+    let proc: Subprocess | undefined;
+    let timedOut = false;
+
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => {
+        timedOut = true;
+        proc?.kill();
+        reject(new Error("Script execution timed out"));
+      }, config.timeout);
+    });
+
+    const execPromise = (async () => {
+      proc = spawn({
+        cmd: [config.command, ...config.args],
+        cwd: config.cwd,
+        env: { ...process.env, ...config.env },
+        stdout: "pipe",
+        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;
+
+      return {
+        exitCode,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        timedOut: false,
+      };
+    })();
+
+    try {
+      return await Promise.race([execPromise, timeoutPromise]);
+    } catch (error) {
+      if (timedOut) {
+        return {
+          exitCode: -1,
+          stdout: "",
+          stderr: "Script execution timed out",
+          timedOut: true,
+        };
+      }
+      throw error;
+    }
+  },
+};
+
+// ============================================================================
+// STRATEGY
+// ============================================================================
+
+export class ScriptHealthCheckStrategy
+  implements
+    HealthCheckStrategy<ScriptConfig, ScriptResult, ScriptAggregatedResult>
+{
+  id = "script";
+  displayName = "Script Health Check";
+  description = "Execute local scripts or commands for health checking";
+
+  private executor: ScriptExecutor;
+
+  constructor(executor: ScriptExecutor = defaultScriptExecutor) {
+    this.executor = executor;
+  }
+
+  config: Versioned<ScriptConfig> = new Versioned({
+    version: 1,
+    schema: scriptConfigSchema,
+  });
+
+  result: Versioned<ScriptResult> = new Versioned({
+    version: 1,
+    schema: scriptResultSchema,
+  });
+
+  aggregatedResult: Versioned<ScriptAggregatedResult> = new Versioned({
+    version: 1,
+    schema: scriptAggregatedSchema,
+  });
+
+  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++;
+      }
+    }
+
+    return {
+      avgExecutionTime: validRuns > 0 ? totalExecutionTime / validRuns : 0,
+      successRate: runs.length > 0 ? (successCount / runs.length) * 100 : 0,
+      errorCount,
+      timeoutCount,
+    };
+  }
+
+  async execute(
+    config: ScriptConfigInput
+  ): Promise<HealthCheckResult<ScriptResult>> {
+    const validatedConfig = this.config.validate(config);
+    const start = performance.now();
+
+    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 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,
+      };
+
+      // Evaluate assertions using shared utility
+      const failedAssertion = evaluateAssertions(validatedConfig.assertions, {
+        executionTime: executionTimeMs,
+        exitCode: execResult.exitCode,
+        success,
+        stdout: execResult.stdout,
+      });
+
+      if (failedAssertion) {
+        return {
+          status: "unhealthy",
+          latencyMs: executionTimeMs,
+          message: `Assertion failed: ${failedAssertion.field} ${
+            failedAssertion.operator
+          }${"value" in failedAssertion ? ` ${failedAssertion.value}` : ""}`,
+          metadata: { ...result, failedAssertion },
+        };
+      }
+
+      if (execResult.timedOut) {
+        return {
+          status: "unhealthy",
+          latencyMs: executionTimeMs,
+          message: `Script timed out after ${validatedConfig.timeout}ms`,
+          metadata: result,
+        };
+      }
+
+      if (!success) {
+        return {
+          status: "unhealthy",
+          latencyMs: executionTimeMs,
+          message: `Script failed with exit code ${execResult.exitCode}`,
+          metadata: result,
+        };
+      }
+
+      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",
+        },
+      };
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}