@checkstack/healthcheck-jenkins-backend 0.2.0

package/src/collectors/job-status.ts

@@ -0,0 +1,241 @@
+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 { JenkinsTransportClient } from "../transport-client";
+
+// ============================================================================
+// CONFIGURATION SCHEMA
+// ============================================================================
+
+const jobStatusConfigSchema = z.object({
+  jobName: z
+    .string()
+    .min(1)
+    .describe("Full job path (e.g., 'folder/job-name' or 'my-job')"),
+  checkLastBuild: z
+    .boolean()
+    .default(true)
+    .describe("Check the last build status"),
+});
+
+export type JobStatusConfig = z.infer<typeof jobStatusConfigSchema>;
+
+// ============================================================================
+// RESULT SCHEMAS
+// ============================================================================
+
+const jobStatusResultSchema = z.object({
+  jobName: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Job Name",
+  }),
+  buildable: healthResultBoolean({
+    "x-chart-type": "boolean",
+    "x-chart-label": "Buildable",
+  }),
+  lastBuildNumber: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Last Build #",
+  }).optional(),
+  lastBuildResult: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Last Build Result",
+  }).optional(),
+  lastBuildDurationMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Build Duration",
+    "x-chart-unit": "ms",
+  }).optional(),
+  lastBuildTimestamp: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Last Build Time",
+  }).optional(),
+  timeSinceLastBuildMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Time Since Last Build",
+    "x-chart-unit": "ms",
+  }).optional(),
+  inQueue: healthResultBoolean({
+    "x-chart-type": "boolean",
+    "x-chart-label": "In Queue",
+  }),
+  color: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Status Color",
+  }),
+});
+
+export type JobStatusResult = z.infer<typeof jobStatusResultSchema>;
+
+const jobStatusAggregatedSchema = z.object({
+  avgBuildDurationMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Build Duration",
+    "x-chart-unit": "ms",
+  }),
+  successRate: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Success Rate",
+    "x-chart-unit": "%",
+  }),
+  buildableRate: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Enabled Rate",
+    "x-chart-unit": "%",
+  }),
+});
+
+export type JobStatusAggregatedResult = z.infer<
+  typeof jobStatusAggregatedSchema
+>;
+
+// ============================================================================
+// JOB STATUS COLLECTOR
+// ============================================================================
+
+/**
+ * Collector for Jenkins job status.
+ * Monitors individual job health and last build information.
+ */
+export class JobStatusCollector
+  implements
+    CollectorStrategy<
+      JenkinsTransportClient,
+      JobStatusConfig,
+      JobStatusResult,
+      JobStatusAggregatedResult
+    >
+{
+  id = "job-status";
+  displayName = "Job Status";
+  description = "Monitor Jenkins job status and last build information";
+
+  supportedPlugins = [pluginMetadata];
+  allowMultiple = true;
+
+  config = new Versioned({ version: 1, schema: jobStatusConfigSchema });
+  result = new Versioned({ version: 1, schema: jobStatusResultSchema });
+  aggregatedResult = new Versioned({
+    version: 1,
+    schema: jobStatusAggregatedSchema,
+  });
+
+  async execute({
+    config,
+    client,
+  }: {
+    config: JobStatusConfig;
+    client: JenkinsTransportClient;
+    pluginId: string;
+  }): Promise<CollectorResult<JobStatusResult>> {
+    // Encode job path for URL (handle folders)
+    const jobPath = config.jobName
+      .split("/")
+      .map((part) => `job/${encodeURIComponent(part)}`)
+      .join("/");
+
+    const response = await client.exec({
+      path: `/${jobPath}/api/json`,
+      query: {
+        tree: "name,buildable,color,inQueue,lastBuild[number,result,duration,timestamp]",
+      },
+    });
+
+    if (response.error) {
+      return {
+        result: {
+          jobName: config.jobName,
+          buildable: false,
+          inQueue: false,
+          color: "notbuilt",
+        },
+        error: response.error,
+      };
+    }
+
+    const data = response.data as {
+      name?: string;
+      buildable?: boolean;
+      color?: string;
+      inQueue?: boolean;
+      lastBuild?: {
+        number?: number;
+        result?: string;
+        duration?: number;
+        timestamp?: number;
+      };
+    };
+
+    const result: JobStatusResult = {
+      jobName: data.name || config.jobName,
+      buildable: data.buildable ?? true,
+      color: data.color || "notbuilt",
+      inQueue: data.inQueue ?? false,
+    };
+
+    if (config.checkLastBuild && data.lastBuild) {
+      result.lastBuildNumber = data.lastBuild.number;
+      result.lastBuildResult = data.lastBuild.result || "UNKNOWN";
+      result.lastBuildDurationMs = data.lastBuild.duration;
+      result.lastBuildTimestamp = data.lastBuild.timestamp;
+
+      if (data.lastBuild.timestamp) {
+        result.timeSinceLastBuildMs = Date.now() - data.lastBuild.timestamp;
+      }
+    }
+
+    // Determine if there's an error based on build result
+    const isFailure =
+      result.lastBuildResult === "FAILURE" ||
+      result.lastBuildResult === "ABORTED";
+
+    return {
+      result,
+      error: isFailure ? `Last build: ${result.lastBuildResult}` : undefined,
+    };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<JobStatusResult>[]
+  ): JobStatusAggregatedResult {
+    const durations = runs
+      .map((r) => r.metadata?.lastBuildDurationMs)
+      .filter((v): v is number => typeof v === "number");
+
+    const results = runs
+      .map((r) => r.metadata?.lastBuildResult)
+      .filter((v): v is string => typeof v === "string");
+
+    const buildables = runs
+      .map((r) => r.metadata?.buildable)
+      .filter((v): v is boolean => typeof v === "boolean");
+
+    const successCount = results.filter((r) => r === "SUCCESS").length;
+    const buildableCount = buildables.filter(Boolean).length;
+
+    return {
+      avgBuildDurationMs:
+        durations.length > 0
+          ? Math.round(durations.reduce((a, b) => a + b, 0) / durations.length)
+          : 0,
+      successRate:
+        results.length > 0
+          ? Math.round((successCount / results.length) * 100)
+          : 0,
+      buildableRate:
+        buildables.length > 0
+          ? Math.round((buildableCount / buildables.length) * 100)
+          : 0,
+    };
+  }
+}

package/src/collectors/node-health.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from "bun:test";
+import { NodeHealthCollector } from "./node-health";
+import type {
+  JenkinsTransportClient,
+  JenkinsRequest,
+  JenkinsResponse,
+} from "../transport-client";
+
+describe("NodeHealthCollector", () => {
+  const collector = new NodeHealthCollector();
+
+  it("should collect all nodes info", async () => {
+    const mockClient: JenkinsTransportClient = {
+      exec: async () => ({
+        statusCode: 200,
+        data: {
+          busyExecutors: 3,
+          totalExecutors: 10,
+          computer: [
+            {
+              displayName: "master",
+              offline: false,
+              numExecutors: 2,
+              idle: true,
+            },
+            {
+              displayName: "agent-1",
+              offline: false,
+              numExecutors: 4,
+              idle: false,
+            },
+            {
+              displayName: "agent-2",
+              offline: true,
+              numExecutors: 4,
+              idle: true,
+            },
+          ],
+        },
+      }),
+    };
+
+    const result = await collector.execute({
+      config: {},
+      client: mockClient,
+      pluginId: "healthcheck-jenkins",
+    });
+
+    expect(result.result.totalNodes).toBe(3);
+    expect(result.result.onlineNodes).toBe(2);
+    expect(result.result.offlineNodes).toBe(1);
+    expect(result.result.busyExecutors).toBe(3);
+    expect(result.result.totalExecutors).toBe(10);
+    expect(result.result.executorUtilization).toBe(30);
+    // Error for offline nodes
+    expect(result.error).toContain("1 of 3 nodes offline");
+  });
+
+  it("should collect single node info", async () => {
+    let capturedPath = "";
+    const mockClient: JenkinsTransportClient = {
+      exec: async (req: JenkinsRequest) => {
+        capturedPath = req.path;
+        return {
+          statusCode: 200,
+          data: {
+            displayName: "agent-1",
+            offline: false,
+            numExecutors: 4,
+            idle: false,
+          },
+        };
+      },
+    };
+
+    const result = await collector.execute({
+      config: { nodeName: "agent-1" },
+      client: mockClient,
+      pluginId: "healthcheck-jenkins",
+    });
+
+    expect(capturedPath).toContain("/computer/agent-1/api/json");
+    expect(result.result.totalNodes).toBe(1);
+    expect(result.result.onlineNodes).toBe(1);
+    expect(result.result.nodeDisplayName).toBe("agent-1");
+    expect(result.error).toBeUndefined();
+  });
+
+  it("should report error for offline single node", async () => {
+    const mockClient: JenkinsTransportClient = {
+      exec: async () => ({
+        statusCode: 200,
+        data: {
+          displayName: "agent-1",
+          offline: true,
+          offlineCauseReason: "Connection lost",
+          numExecutors: 4,
+        },
+      }),
+    };
+
+    const result = await collector.execute({
+      config: { nodeName: "agent-1" },
+      client: mockClient,
+      pluginId: "healthcheck-jenkins",
+    });
+
+    expect(result.result.offlineNodes).toBe(1);
+    expect(result.result.nodeOffline).toBe(true);
+    expect(result.error).toContain("Connection lost");
+  });
+
+  it("should aggregate correctly", () => {
+    const runs: Parameters<typeof collector.aggregateResult>[0] = [
+      {
+        status: "healthy" as const,
+        latencyMs: 100,
+        metadata: {
+          totalNodes: 6,
+          onlineNodes: 5,
+          offlineNodes: 1,
+          busyExecutors: 10,
+          idleExecutors: 10,
+          totalExecutors: 20,
+          executorUtilization: 50,
+        },
+      },
+      {
+        status: "healthy" as const,
+        latencyMs: 100,
+        metadata: {
+          totalNodes: 5,
+          onlineNodes: 3,
+          offlineNodes: 2,
+          busyExecutors: 14,
+          idleExecutors: 6,
+          totalExecutors: 20,
+          executorUtilization: 70,
+        },
+      },
+    ];
+
+    const aggregated = collector.aggregateResult(runs);
+
+    expect(aggregated.avgOnlineNodes).toBe(4);
+    expect(aggregated.avgUtilization).toBe(60);
+    expect(aggregated.minOnlineNodes).toBe(3);
+  });
+});

package/src/collectors/node-health.ts

@@ -0,0 +1,305 @@
+import {
+  Versioned,
+  z,
+  type HealthCheckRunForAggregation,
+  type CollectorResult,
+  type CollectorStrategy,
+} from "@checkstack/backend-api";
+import {
+  healthResultBoolean,
+  healthResultNumber,
+  healthResultString,
+} from "@checkstack/healthcheck-common";
+import { pluginMetadata } from "../plugin-metadata";
+import type { JenkinsTransportClient } from "../transport-client";
+
+// ============================================================================
+// CONFIGURATION SCHEMA
+// ============================================================================
+
+const nodeHealthConfigSchema = z.object({
+  nodeName: z
+    .string()
+    .optional()
+    .describe("Specific node name to check (leave empty for all nodes)"),
+});
+
+export type NodeHealthConfig = z.infer<typeof nodeHealthConfigSchema>;
+
+// ============================================================================
+// RESULT SCHEMAS
+// ============================================================================
+
+const nodeHealthResultSchema = z.object({
+  totalNodes: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Total Nodes",
+  }),
+  onlineNodes: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Online Nodes",
+  }),
+  offlineNodes: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Offline Nodes",
+  }),
+  busyExecutors: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Busy Executors",
+  }),
+  idleExecutors: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Idle Executors",
+  }),
+  totalExecutors: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Total Executors",
+  }),
+  executorUtilization: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Executor Utilization",
+    "x-chart-unit": "%",
+  }),
+  // For single node mode
+  nodeDisplayName: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Node Name",
+  }).optional(),
+  nodeOffline: healthResultBoolean({
+    "x-chart-type": "boolean",
+    "x-chart-label": "Node Offline",
+  }).optional(),
+  nodeOfflineReason: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Offline Reason",
+  }).optional(),
+});
+
+export type NodeHealthResult = z.infer<typeof nodeHealthResultSchema>;
+
+const nodeHealthAggregatedSchema = z.object({
+  avgOnlineNodes: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Online Nodes",
+  }),
+  avgUtilization: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Avg Utilization",
+    "x-chart-unit": "%",
+  }),
+  minOnlineNodes: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Min Online Nodes",
+  }),
+});
+
+export type NodeHealthAggregatedResult = z.infer<
+  typeof nodeHealthAggregatedSchema
+>;
+
+// ============================================================================
+// NODE HEALTH COLLECTOR
+// ============================================================================
+
+/**
+ * Collector for Jenkins node/agent health.
+ * Monitors node availability and executor utilization.
+ */
+export class NodeHealthCollector
+  implements
+    CollectorStrategy<
+      JenkinsTransportClient,
+      NodeHealthConfig,
+      NodeHealthResult,
+      NodeHealthAggregatedResult
+    >
+{
+  id = "node-health";
+  displayName = "Node Health";
+  description = "Monitor Jenkins agent/node availability and executor usage";
+
+  supportedPlugins = [pluginMetadata];
+  allowMultiple = true;
+
+  config = new Versioned({ version: 1, schema: nodeHealthConfigSchema });
+  result = new Versioned({ version: 1, schema: nodeHealthResultSchema });
+  aggregatedResult = new Versioned({
+    version: 1,
+    schema: nodeHealthAggregatedSchema,
+  });
+
+  async execute({
+    config,
+    client,
+  }: {
+    config: NodeHealthConfig;
+    client: JenkinsTransportClient;
+    pluginId: string;
+  }): Promise<CollectorResult<NodeHealthResult>> {
+    // If checking a specific node
+    if (config.nodeName) {
+      return this.executeForSingleNode(config.nodeName, client);
+    }
+
+    // Otherwise, get all nodes
+    return this.executeForAllNodes(client);
+  }
+
+  private async executeForSingleNode(
+    nodeName: string,
+    client: JenkinsTransportClient
+  ): Promise<CollectorResult<NodeHealthResult>> {
+    const encodedName = encodeURIComponent(nodeName);
+    const response = await client.exec({
+      path: `/computer/${encodedName}/api/json`,
+      query: {
+        tree: "displayName,offline,offlineCauseReason,numExecutors,idle,temporarilyOffline",
+      },
+    });
+
+    if (response.error) {
+      return {
+        result: {
+          totalNodes: 0,
+          onlineNodes: 0,
+          offlineNodes: 0,
+          busyExecutors: 0,
+          idleExecutors: 0,
+          totalExecutors: 0,
+          executorUtilization: 0,
+        },
+        error: response.error,
+      };
+    }
+
+    const data = response.data as {
+      displayName?: string;
+      offline?: boolean;
+      offlineCauseReason?: string;
+      numExecutors?: number;
+      idle?: boolean;
+      temporarilyOffline?: boolean;
+    };
+
+    const isOffline = data.offline ?? false;
+    const numExecutors = data.numExecutors ?? 0;
+    const busyExecutors = isOffline ? 0 : data.idle ? 0 : numExecutors;
+    const idleExecutors = numExecutors - busyExecutors;
+
+    const result: NodeHealthResult = {
+      totalNodes: 1,
+      onlineNodes: isOffline ? 0 : 1,
+      offlineNodes: isOffline ? 1 : 0,
+      busyExecutors,
+      idleExecutors,
+      totalExecutors: numExecutors,
+      executorUtilization:
+        numExecutors > 0 ? Math.round((busyExecutors / numExecutors) * 100) : 0,
+      nodeDisplayName: data.displayName,
+      nodeOffline: isOffline,
+      nodeOfflineReason: data.offlineCauseReason,
+    };
+
+    return {
+      result,
+      error: isOffline
+        ? `Node offline: ${data.offlineCauseReason || "Unknown reason"}`
+        : undefined,
+    };
+  }
+
+  private async executeForAllNodes(
+    client: JenkinsTransportClient
+  ): Promise<CollectorResult<NodeHealthResult>> {
+    const response = await client.exec({
+      path: "/computer/api/json",
+      query: {
+        tree: "busyExecutors,computer[displayName,offline,numExecutors,idle],totalExecutors",
+      },
+    });
+
+    if (response.error) {
+      return {
+        result: {
+          totalNodes: 0,
+          onlineNodes: 0,
+          offlineNodes: 0,
+          busyExecutors: 0,
+          idleExecutors: 0,
+          totalExecutors: 0,
+          executorUtilization: 0,
+        },
+        error: response.error,
+      };
+    }
+
+    const data = response.data as {
+      busyExecutors?: number;
+      totalExecutors?: number;
+      computer?: Array<{
+        displayName?: string;
+        offline?: boolean;
+        numExecutors?: number;
+        idle?: boolean;
+      }>;
+    };
+
+    const nodes = data.computer || [];
+    const onlineNodes = nodes.filter((n) => !n.offline).length;
+    const offlineNodes = nodes.filter((n) => n.offline).length;
+    const totalExecutors = data.totalExecutors ?? 0;
+    const busyExecutors = data.busyExecutors ?? 0;
+    const idleExecutors = totalExecutors - busyExecutors;
+
+    const result: NodeHealthResult = {
+      totalNodes: nodes.length,
+      onlineNodes,
+      offlineNodes,
+      busyExecutors,
+      idleExecutors,
+      totalExecutors,
+      executorUtilization:
+        totalExecutors > 0
+          ? Math.round((busyExecutors / totalExecutors) * 100)
+          : 0,
+    };
+
+    // Warn if nodes are offline
+    const hasIssue = offlineNodes > 0;
+
+    return {
+      result,
+      error: hasIssue
+        ? `${offlineNodes} of ${nodes.length} nodes offline`
+        : undefined,
+    };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<NodeHealthResult>[]
+  ): NodeHealthAggregatedResult {
+    const onlineNodes = runs
+      .map((r) => r.metadata?.onlineNodes)
+      .filter((v): v is number => typeof v === "number");
+
+    const utilizations = runs
+      .map((r) => r.metadata?.executorUtilization)
+      .filter((v): v is number => typeof v === "number");
+
+    return {
+      avgOnlineNodes:
+        onlineNodes.length > 0
+          ? Math.round(
+              onlineNodes.reduce((a, b) => a + b, 0) / onlineNodes.length
+            )
+          : 0,
+      avgUtilization:
+        utilizations.length > 0
+          ? Math.round(
+              utilizations.reduce((a, b) => a + b, 0) / utilizations.length
+            )
+          : 0,
+      minOnlineNodes: onlineNodes.length > 0 ? Math.min(...onlineNodes) : 0,
+    };
+  }
+}