@checkstack/healthcheck-jenkins-backend 0.2.0

package/src/collectors/queue-info.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "bun:test";
+import { QueueInfoCollector } from "./queue-info";
+import type {
+  JenkinsTransportClient,
+  JenkinsResponse,
+} from "../transport-client";
+
+describe("QueueInfoCollector", () => {
+  const collector = new QueueInfoCollector();
+
+  const createMockClient = (
+    response: JenkinsResponse
+  ): JenkinsTransportClient => ({
+    exec: async () => response,
+  });
+
+  it("should collect queue info successfully", async () => {
+    const now = Date.now();
+    const mockClient = createMockClient({
+      statusCode: 200,
+      data: {
+        items: [
+          {
+            id: 1,
+            blocked: false,
+            buildable: true,
+            stuck: false,
+            inQueueSince: now - 5000,
+          },
+          {
+            id: 2,
+            blocked: true,
+            buildable: false,
+            stuck: false,
+            inQueueSince: now - 10000,
+          },
+          {
+            id: 3,
+            blocked: false,
+            buildable: true,
+            stuck: true,
+            inQueueSince: now - 30000,
+          },
+        ],
+      },
+    });
+
+    const result = await collector.execute({
+      config: {},
+      client: mockClient,
+      pluginId: "healthcheck-jenkins",
+    });
+
+    expect(result.result.queueLength).toBe(3);
+    expect(result.result.blockedCount).toBe(1);
+    expect(result.result.buildableCount).toBe(2);
+    expect(result.result.stuckCount).toBe(1);
+    expect(result.result.oldestWaitingMs).toBeGreaterThanOrEqual(30000);
+    // Error should be set because stuck > 0
+    expect(result.error).toContain("stuck");
+  });
+
+  it("should report no error for empty queue", async () => {
+    const mockClient = createMockClient({
+      statusCode: 200,
+      data: { items: [] },
+    });
+
+    const result = await collector.execute({
+      config: {},
+      client: mockClient,
+      pluginId: "healthcheck-jenkins",
+    });
+
+    expect(result.error).toBeUndefined();
+    expect(result.result.queueLength).toBe(0);
+  });
+
+  it("should aggregate correctly", () => {
+    const runs: Parameters<typeof collector.aggregateResult>[0] = [
+      {
+        status: "healthy" as const,
+        latencyMs: 100,
+        metadata: {
+          queueLength: 5,
+          blockedCount: 1,
+          buildableCount: 4,
+          stuckCount: 0,
+          oldestWaitingMs: 15000,
+          avgWaitingMs: 10000,
+        },
+      },
+      {
+        status: "healthy" as const,
+        latencyMs: 100,
+        metadata: {
+          queueLength: 3,
+          blockedCount: 0,
+          buildableCount: 3,
+          stuckCount: 0,
+          oldestWaitingMs: 25000,
+          avgWaitingMs: 20000,
+        },
+      },
+    ];
+
+    const aggregated = collector.aggregateResult(runs);
+
+    expect(aggregated.avgQueueLength).toBe(4);
+    expect(aggregated.maxQueueLength).toBe(5);
+    expect(aggregated.avgWaitTime).toBe(15000);
+  });
+});

package/src/collectors/queue-info.ts

@@ -0,0 +1,215 @@
+import {
+  Versioned,
+  z,
+  type HealthCheckRunForAggregation,
+  type CollectorResult,
+  type CollectorStrategy,
+} from "@checkstack/backend-api";
+import { healthResultNumber } from "@checkstack/healthcheck-common";
+import { pluginMetadata } from "../plugin-metadata";
+import type { JenkinsTransportClient } from "../transport-client";
+
+// ============================================================================
+// CONFIGURATION SCHEMA
+// ============================================================================
+
+const queueInfoConfigSchema = z.object({});
+
+export type QueueInfoConfig = z.infer<typeof queueInfoConfigSchema>;
+
+// ============================================================================
+// RESULT SCHEMAS
+// ============================================================================
+
+const queueInfoResultSchema = z.object({
+  queueLength: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Queue Length",
+  }),
+  blockedCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Blocked Items",
+  }),
+  buildableCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Buildable Items",
+  }),
+  stuckCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Stuck Items",
+  }),
+  oldestWaitingMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Oldest Wait Time",
+    "x-chart-unit": "ms",
+  }),
+  avgWaitingMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Wait Time",
+    "x-chart-unit": "ms",
+  }),
+});
+
+export type QueueInfoResult = z.infer<typeof queueInfoResultSchema>;
+
+const queueInfoAggregatedSchema = z.object({
+  avgQueueLength: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Queue Length",
+  }),
+  maxQueueLength: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Max Queue Length",
+  }),
+  avgWaitTime: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Wait Time",
+    "x-chart-unit": "ms",
+  }),
+});
+
+export type QueueInfoAggregatedResult = z.infer<
+  typeof queueInfoAggregatedSchema
+>;
+
+// ============================================================================
+// QUEUE INFO COLLECTOR
+// ============================================================================
+
+/**
+ * Collector for Jenkins build queue.
+ * Monitors queue length and wait times.
+ */
+export class QueueInfoCollector
+  implements
+    CollectorStrategy<
+      JenkinsTransportClient,
+      QueueInfoConfig,
+      QueueInfoResult,
+      QueueInfoAggregatedResult
+    >
+{
+  id = "queue-info";
+  displayName = "Queue Info";
+  description = "Monitor Jenkins build queue length and wait times";
+
+  supportedPlugins = [pluginMetadata];
+
+  config = new Versioned({ version: 1, schema: queueInfoConfigSchema });
+  result = new Versioned({ version: 1, schema: queueInfoResultSchema });
+  aggregatedResult = new Versioned({
+    version: 1,
+    schema: queueInfoAggregatedSchema,
+  });
+
+  async execute({
+    client,
+  }: {
+    config: QueueInfoConfig;
+    client: JenkinsTransportClient;
+    pluginId: string;
+  }): Promise<CollectorResult<QueueInfoResult>> {
+    const response = await client.exec({
+      path: "/queue/api/json",
+      query: {
+        tree: "items[id,why,stuck,blocked,buildable,inQueueSince]",
+      },
+    });
+
+    if (response.error) {
+      return {
+        result: {
+          queueLength: 0,
+          blockedCount: 0,
+          buildableCount: 0,
+          stuckCount: 0,
+          oldestWaitingMs: 0,
+          avgWaitingMs: 0,
+        },
+        error: response.error,
+      };
+    }
+
+    const data = response.data as {
+      items?: Array<{
+        id?: number;
+        why?: string;
+        stuck?: boolean;
+        blocked?: boolean;
+        buildable?: boolean;
+        inQueueSince?: number;
+      }>;
+    };
+
+    const items = data.items || [];
+    const now = Date.now();
+
+    let blockedCount = 0;
+    let buildableCount = 0;
+    let stuckCount = 0;
+    const waitTimes: number[] = [];
+
+    for (const item of items) {
+      if (item.blocked) blockedCount++;
+      if (item.buildable) buildableCount++;
+      if (item.stuck) stuckCount++;
+
+      if (item.inQueueSince) {
+        waitTimes.push(now - item.inQueueSince);
+      }
+    }
+
+    const oldestWaitingMs = waitTimes.length > 0 ? Math.max(...waitTimes) : 0;
+    const avgWaitingMs =
+      waitTimes.length > 0
+        ? Math.round(waitTimes.reduce((a, b) => a + b, 0) / waitTimes.length)
+        : 0;
+
+    const result: QueueInfoResult = {
+      queueLength: items.length,
+      blockedCount,
+      buildableCount,
+      stuckCount,
+      oldestWaitingMs,
+      avgWaitingMs,
+    };
+
+    // Warn if queue is backing up
+    const hasIssue = stuckCount > 0 || items.length > 10;
+
+    return {
+      result,
+      error: hasIssue
+        ? `Queue has ${items.length} items${
+            stuckCount > 0 ? `, ${stuckCount} stuck` : ""
+          }`
+        : undefined,
+    };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<QueueInfoResult>[]
+  ): QueueInfoAggregatedResult {
+    const queueLengths = runs
+      .map((r) => r.metadata?.queueLength)
+      .filter((v): v is number => typeof v === "number");
+
+    const waitTimes = runs
+      .map((r) => r.metadata?.avgWaitingMs)
+      .filter((v): v is number => typeof v === "number");
+
+    return {
+      avgQueueLength:
+        queueLengths.length > 0
+          ? Math.round(
+              queueLengths.reduce((a, b) => a + b, 0) / queueLengths.length
+            )
+          : 0,
+      maxQueueLength: queueLengths.length > 0 ? Math.max(...queueLengths) : 0,
+      avgWaitTime:
+        waitTimes.length > 0
+          ? Math.round(waitTimes.reduce((a, b) => a + b, 0) / waitTimes.length)
+          : 0,
+    };
+  }
+}

package/src/collectors/server-info.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "bun:test";
+import { ServerInfoCollector } from "./server-info";
+import type {
+  JenkinsTransportClient,
+  JenkinsResponse,
+} from "../transport-client";
+
+describe("ServerInfoCollector", () => {
+  const collector = new ServerInfoCollector();
+
+  const createMockClient = (
+    response: JenkinsResponse
+  ): JenkinsTransportClient => ({
+    exec: async () => response,
+  });
+
+  it("should collect server info successfully", async () => {
+    const mockClient = createMockClient({
+      statusCode: 200,
+      jenkinsVersion: "2.426.1",
+      data: {
+        mode: "NORMAL",
+        numExecutors: 4,
+        usableWorkers: 3,
+        jobs: [{ name: "job1" }, { name: "job2" }, { name: "job3" }],
+      },
+    });
+
+    const result = await collector.execute({
+      config: {},
+      client: mockClient,
+      pluginId: "healthcheck-jenkins",
+    });
+
+    expect(result.error).toBeUndefined();
+    expect(result.result.jenkinsVersion).toBe("2.426.1");
+    expect(result.result.mode).toBe("NORMAL");
+    expect(result.result.numExecutors).toBe(4);
+    expect(result.result.usableWorkers).toBe(3);
+    expect(result.result.totalJobs).toBe(3);
+  });
+
+  it("should handle API error", async () => {
+    const mockClient = createMockClient({
+      statusCode: 401,
+      data: null,
+      error: "HTTP 401: Unauthorized",
+    });
+
+    const result = await collector.execute({
+      config: {},
+      client: mockClient,
+      pluginId: "healthcheck-jenkins",
+    });
+
+    expect(result.error).toBe("HTTP 401: Unauthorized");
+  });
+
+  it("should aggregate results correctly", () => {
+    const runs: Parameters<typeof collector.aggregateResult>[0] = [
+      {
+        status: "healthy" as const,
+        latencyMs: 100,
+        metadata: {
+          jenkinsVersion: "2.426.1",
+          mode: "NORMAL",
+          numExecutors: 4,
+          usableWorkers: 3,
+          totalJobs: 10,
+        },
+      },
+      {
+        status: "healthy" as const,
+        latencyMs: 100,
+        metadata: {
+          jenkinsVersion: "2.426.1",
+          mode: "NORMAL",
+          numExecutors: 6,
+          usableWorkers: 5,
+          totalJobs: 12,
+        },
+      },
+    ];
+
+    const aggregated = collector.aggregateResult(runs);
+
+    expect(aggregated.avgExecutors).toBe(5);
+    expect(aggregated.avgTotalJobs).toBe(11);
+  });
+});

package/src/collectors/server-info.ts

@@ -0,0 +1,169 @@
+import {
+  Versioned,
+  z,
+  type HealthCheckRunForAggregation,
+  type CollectorResult,
+  type CollectorStrategy,
+} from "@checkstack/backend-api";
+import {
+  healthResultNumber,
+  healthResultString,
+} from "@checkstack/healthcheck-common";
+import { pluginMetadata } from "../plugin-metadata";
+import type { JenkinsTransportClient } from "../transport-client";
+
+// ============================================================================
+// CONFIGURATION SCHEMA
+// ============================================================================
+
+const serverInfoConfigSchema = z.object({});
+
+export type ServerInfoConfig = z.infer<typeof serverInfoConfigSchema>;
+
+// ============================================================================
+// RESULT SCHEMAS
+// ============================================================================
+
+const serverInfoResultSchema = z.object({
+  jenkinsVersion: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Jenkins Version",
+  }),
+  mode: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Server Mode",
+  }),
+  numExecutors: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Executors",
+  }),
+  usableWorkers: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Usable Workers",
+  }),
+  totalJobs: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Total Jobs",
+  }),
+  uptime: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Uptime",
+    "x-chart-unit": "hours",
+  }).optional(),
+});
+
+export type ServerInfoResult = z.infer<typeof serverInfoResultSchema>;
+
+const serverInfoAggregatedSchema = z.object({
+  avgExecutors: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Executors",
+  }),
+  avgTotalJobs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Jobs",
+  }),
+});
+
+export type ServerInfoAggregatedResult = z.infer<
+  typeof serverInfoAggregatedSchema
+>;
+
+// ============================================================================
+// SERVER INFO COLLECTOR
+// ============================================================================
+
+/**
+ * Built-in collector for Jenkins server information.
+ * Fetches basic server health metrics via /api/json.
+ */
+export class ServerInfoCollector
+  implements
+    CollectorStrategy<
+      JenkinsTransportClient,
+      ServerInfoConfig,
+      ServerInfoResult,
+      ServerInfoAggregatedResult
+    >
+{
+  id = "server-info";
+  displayName = "Server Info";
+  description = "Collects Jenkins server information and health metrics";
+
+  supportedPlugins = [pluginMetadata];
+
+  config = new Versioned({ version: 1, schema: serverInfoConfigSchema });
+  result = new Versioned({ version: 1, schema: serverInfoResultSchema });
+  aggregatedResult = new Versioned({
+    version: 1,
+    schema: serverInfoAggregatedSchema,
+  });
+
+  async execute({
+    client,
+  }: {
+    config: ServerInfoConfig;
+    client: JenkinsTransportClient;
+    pluginId: string;
+  }): Promise<CollectorResult<ServerInfoResult>> {
+    const response = await client.exec({
+      path: "/api/json",
+      query: {
+        tree: "mode,numExecutors,usableWorkers,jobs[name]",
+      },
+    });
+
+    if (response.error) {
+      return {
+        result: {
+          jenkinsVersion: "",
+          mode: "",
+          numExecutors: 0,
+          usableWorkers: 0,
+          totalJobs: 0,
+        },
+        error: response.error,
+      };
+    }
+
+    const data = response.data as {
+      mode?: string;
+      numExecutors?: number;
+      usableWorkers?: number;
+      jobs?: Array<{ name: string }>;
+    };
+
+    return {
+      result: {
+        jenkinsVersion: response.jenkinsVersion || "unknown",
+        mode: data.mode || "NORMAL",
+        numExecutors: data.numExecutors || 0,
+        usableWorkers: data.usableWorkers || 0,
+        totalJobs: data.jobs?.length || 0,
+      },
+    };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<ServerInfoResult>[]
+  ): ServerInfoAggregatedResult {
+    const executors = runs
+      .map((r) => r.metadata?.numExecutors)
+      .filter((v): v is number => typeof v === "number");
+
+    const jobs = runs
+      .map((r) => r.metadata?.totalJobs)
+      .filter((v): v is number => typeof v === "number");
+
+    return {
+      avgExecutors:
+        executors.length > 0
+          ? Math.round(executors.reduce((a, b) => a + b, 0) / executors.length)
+          : 0,
+      avgTotalJobs:
+        jobs.length > 0
+          ? Math.round(jobs.reduce((a, b) => a + b, 0) / jobs.length)
+          : 0,
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
+import { JenkinsHealthCheckStrategy } from "./strategy";
+import { pluginMetadata } from "./plugin-metadata";
+import {
+  ServerInfoCollector,
+  JobStatusCollector,
+  BuildHistoryCollector,
+  QueueInfoCollector,
+  NodeHealthCollector,
+} from "./collectors";
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+  register(env) {
+    env.registerInit({
+      deps: {
+        healthCheckRegistry: coreServices.healthCheckRegistry,
+        collectorRegistry: coreServices.collectorRegistry,
+        logger: coreServices.logger,
+      },
+      init: async ({ healthCheckRegistry, collectorRegistry, logger }) => {
+        logger.debug("🔌 Registering Jenkins Health Check Strategy...");
+
+        // Register the transport strategy
+        const strategy = new JenkinsHealthCheckStrategy();
+        healthCheckRegistry.register(strategy);
+
+        // Register all collectors
+        collectorRegistry.register(new ServerInfoCollector());
+        collectorRegistry.register(new JobStatusCollector());
+        collectorRegistry.register(new BuildHistoryCollector());
+        collectorRegistry.register(new QueueInfoCollector());
+        collectorRegistry.register(new NodeHealthCollector());
+
+        logger.info(
+          "✅ Jenkins health check registered (strategy + 5 collectors)"
+        );
+      },
+    });
+  },
+});
+
+export { pluginMetadata } from "./plugin-metadata";

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the Jenkins Health Check backend.
+ * This is the single source of truth for the plugin ID.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "healthcheck-jenkins",
+});