@checkstack/healthcheck-backend 1.8.0 → 1.9.0

package/src/router.ts

@@ -199,20 +199,20 @@ export const createHealthCheckRouter = (opts: {
     }),
 
     deleteConfiguration: os.deleteConfiguration.handler(async ({ input }) => {
-      await enforceNotGitOpsLocked("Healthcheck", input);
-      await service.deleteConfiguration(input);
+      await enforceNotGitOpsLocked("Healthcheck", input.id);
+      await service.deleteConfiguration(input.id);
       await cache.invalidateAllSystems();
     }),
 
     pauseConfiguration: os.pauseConfiguration.handler(async ({ input }) => {
-      await enforceNotGitOpsLocked("Healthcheck", input);
-      await service.pauseConfiguration(input);
+      await enforceNotGitOpsLocked("Healthcheck", input.id);
+      await service.pauseConfiguration(input.id);
       await cache.invalidateAllSystems();
     }),
 
     resumeConfiguration: os.resumeConfiguration.handler(async ({ input }) => {
-      await enforceNotGitOpsLocked("Healthcheck", input);
-      await service.resumeConfiguration(input);
+      await enforceNotGitOpsLocked("Healthcheck", input.id);
+      await service.resumeConfiguration(input.id);
       await cache.invalidateAllSystems();
     }),
 
@@ -313,6 +313,10 @@ export const createHealthCheckRouter = (opts: {
       return service.getHistory(input);
     }),
 
+    getRunStats: os.getRunStats.handler(async ({ input }) => {
+      return service.getRunStats(input);
+    }),
+
     getDetailedHistory: os.getDetailedHistory.handler(async ({ input }) => {
       return service.getDetailedHistory(input);
     }),

package/src/run-stats.logic.test.ts

@@ -0,0 +1,73 @@
+import { describe, test, expect } from "bun:test";
+import { summarizeRuns, type StatRun } from "./run-stats.logic";
+
+const start = new Date("2026-06-10T00:00:00.000Z");
+const end = new Date("2026-06-10T04:00:00.000Z"); // 4h window
+
+function at(hoursFromStart: number, status: string, latencyMs?: number): StatRun {
+  return {
+    timestamp: new Date(start.getTime() + hoursFromStart * 3_600_000),
+    status,
+    latencyMs,
+  };
+}
+
+describe("summarizeRuns", () => {
+  test("computes window totals with exact uptime and latency stats", () => {
+    const runs: StatRun[] = [
+      at(0, "healthy", 100),
+      at(0.5, "unhealthy", 300),
+      at(1, "healthy", 200),
+      at(2, "degraded", 400),
+    ];
+    const stats = summarizeRuns({ runs, startDate: start, endDate: end, maxBuckets: 4 });
+    expect(stats.total.runCount).toBe(4);
+    expect(stats.total.healthy).toBe(2);
+    expect(stats.total.degraded).toBe(1);
+    expect(stats.total.unhealthy).toBe(1);
+    expect(stats.total.uptimePct).toBe(50);
+    expect(stats.total.minLatencyMs).toBe(100);
+    expect(stats.total.maxLatencyMs).toBe(400);
+    expect(stats.total.avgLatencyMs).toBe(250);
+    expect(stats.window.start).toBe("2026-06-10T00:00:00.000Z");
+    expect(stats.window.end).toBe("2026-06-10T04:00:00.000Z");
+  });
+
+  test("buckets runs over the window and caps the count", () => {
+    const runs: StatRun[] = [
+      at(0, "healthy"),
+      at(0.5, "unhealthy"),
+      at(1, "healthy"),
+      at(2, "healthy"),
+    ];
+    const stats = summarizeRuns({ runs, startDate: start, endDate: end, maxBuckets: 4 });
+    // 4h / 4 buckets = 1h interval.
+    expect(stats.bucketIntervalSeconds).toBe(3600);
+    // Buckets 0 (2 runs), 1 (1 run), 2 (1 run); bucket 3 empty -> omitted.
+    expect(stats.buckets).toHaveLength(3);
+    expect(stats.buckets[0].runCount).toBe(2);
+    expect(stats.buckets[0].healthy).toBe(1);
+    expect(stats.buckets[0].unhealthy).toBe(1);
+    expect(stats.buckets[0].uptimePct).toBe(50);
+    expect(stats.buckets[0].start).toBe("2026-06-10T00:00:00.000Z");
+    expect(stats.buckets[0].end).toBe("2026-06-10T01:00:00.000Z");
+    // Empty buckets are omitted, not padded.
+    expect(stats.buckets.map((b) => b.runCount)).toEqual([2, 1, 1]);
+  });
+
+  test("never emits more buckets than maxBuckets", () => {
+    const runs: StatRun[] = Array.from({ length: 200 }, (_, i) =>
+      at((i / 200) * 4, "healthy"),
+    );
+    const stats = summarizeRuns({ runs, startDate: start, endDate: end, maxBuckets: 6 });
+    expect(stats.buckets.length).toBeLessThanOrEqual(6);
+  });
+
+  test("empty window yields zeroed totals and no buckets", () => {
+    const stats = summarizeRuns({ runs: [], startDate: start, endDate: end, maxBuckets: 4 });
+    expect(stats.total.runCount).toBe(0);
+    expect(stats.total.uptimePct).toBe(0);
+    expect(stats.total.avgLatencyMs).toBeUndefined();
+    expect(stats.buckets).toHaveLength(0);
+  });
+});

package/src/run-stats.logic.ts

@@ -0,0 +1,148 @@
+import {
+  countStatuses,
+  calculateLatencyStats,
+  extractLatencies,
+} from "./aggregation-utils";
+
+/**
+ * Pure summarizer behind the `healthcheck.runStats` AI tool. Turns raw runs in a
+ * window into a COMPACT report — window totals + a small, capped time series of
+ * buckets — so the assistant can answer "how often / how much downtime / uptime
+ * over the last N days" without pulling thousands of rows into its context.
+ *
+ * Bucketing is uniform over [startDate, endDate): the window is split into at
+ * most `maxBuckets` equal intervals; each run lands in `floor((t - start) /
+ * interval)`. Buckets with no runs are omitted (the model reads the bucket's
+ * own `start`/`end`, so gaps are unambiguous and we don't pad the context with
+ * empty rows). Deterministic and DB-free, so it is unit-tested directly.
+ */
+
+/** One input run (only the fields stats need). */
+export interface StatRun {
+  timestamp: Date;
+  status: string;
+  latencyMs?: number;
+}
+
+export interface RunStatsBucket {
+  start: string;
+  end: string;
+  runCount: number;
+  healthy: number;
+  degraded: number;
+  unhealthy: number;
+  /** Percent of runs that were healthy, 0-100, rounded to 1 decimal. */
+  uptimePct: number;
+  avgLatencyMs?: number;
+  p95LatencyMs?: number;
+}
+
+export interface RunStatsTotal {
+  runCount: number;
+  healthy: number;
+  degraded: number;
+  unhealthy: number;
+  uptimePct: number;
+  avgLatencyMs?: number;
+  minLatencyMs?: number;
+  maxLatencyMs?: number;
+  p95LatencyMs?: number;
+}
+
+export interface RunStats {
+  window: { start: string; end: string };
+  bucketIntervalSeconds: number;
+  total: RunStatsTotal;
+  buckets: RunStatsBucket[];
+}
+
+/** Healthy / (total) as a 0-100 percentage, 1 decimal. 0 runs -> 0. */
+function uptimePct({
+  healthy,
+  runCount,
+}: {
+  healthy: number;
+  runCount: number;
+}): number {
+  if (runCount === 0) return 0;
+  return Math.round((healthy / runCount) * 1000) / 10;
+}
+
+export function summarizeRuns({
+  runs,
+  startDate,
+  endDate,
+  maxBuckets,
+}: {
+  runs: StatRun[];
+  startDate: Date;
+  endDate: Date;
+  maxBuckets: number;
+}): RunStats {
+  const startMs = startDate.getTime();
+  const endMs = endDate.getTime();
+  const rangeMs = Math.max(1, endMs - startMs);
+  const buckets = Math.max(1, Math.min(maxBuckets, Math.ceil(maxBuckets)));
+  // At least 1s per bucket; never more buckets than the range allows.
+  const intervalMs = Math.max(1000, Math.ceil(rangeMs / buckets));
+
+  // Window totals (over ALL runs, so p95 is exact, not derived from buckets).
+  const totalCounts = countStatuses(runs);
+  const totalLatency = calculateLatencyStats(extractLatencies(runs));
+  const total: RunStatsTotal = {
+    runCount: runs.length,
+    healthy: totalCounts.healthyCount,
+    degraded: totalCounts.degradedCount,
+    unhealthy: totalCounts.unhealthyCount,
+    uptimePct: uptimePct({ healthy: totalCounts.healthyCount, runCount: runs.length }),
+    avgLatencyMs: totalLatency.avgLatencyMs,
+    minLatencyMs: totalLatency.minLatencyMs,
+    maxLatencyMs: totalLatency.maxLatencyMs,
+    p95LatencyMs: totalLatency.p95LatencyMs,
+  };
+
+  // Group runs into bucket indices.
+  const byBucket = new Map<number, StatRun[]>();
+  for (const run of runs) {
+    const offset = run.timestamp.getTime() - startMs;
+    if (offset < 0 || offset > rangeMs) continue; // outside the window
+    const idx = Math.min(buckets - 1, Math.floor(offset / intervalMs));
+    const list = byBucket.get(idx) ?? [];
+    list.push(run);
+    byBucket.set(idx, list);
+  }
+
+  const bucketRows: RunStatsBucket[] = [...byBucket.entries()]
+    .toSorted(([a], [b]) => a - b)
+    .map(([idx, bucketRuns]) => {
+      const counts = countStatuses(bucketRuns);
+      const latency = calculateLatencyStats(extractLatencies(bucketRuns));
+      const bStartMs = startMs + idx * intervalMs;
+      const bEndMs = Math.min(endMs, bStartMs + intervalMs);
+      return {
+        start: new Date(bStartMs).toISOString(),
+        end: new Date(bEndMs).toISOString(),
+        runCount: bucketRuns.length,
+        healthy: counts.healthyCount,
+        degraded: counts.degradedCount,
+        unhealthy: counts.unhealthyCount,
+        uptimePct: uptimePct({
+          healthy: counts.healthyCount,
+          runCount: bucketRuns.length,
+        }),
+        ...(latency.avgLatencyMs === undefined
+          ? {}
+          : { avgLatencyMs: latency.avgLatencyMs }),
+        ...(latency.p95LatencyMs === undefined
+          ? {}
+          : { p95LatencyMs: latency.p95LatencyMs }),
+      };
+    });
+
+  return {
+    window: { start: startDate.toISOString(), end: endDate.toISOString() },
+    bucketIntervalSeconds: Math.round(intervalMs / 1000),
+    total,
+    buckets: bucketRows,
+  };
+}

package/src/service.ts

@@ -11,7 +11,9 @@ import {
   DEFAULT_NOTIFICATION_POLICY,
   type CollectorConfigEntry,
   type HealthcheckSignalStatuses,
+  type RunStats,
 } from "@checkstack/healthcheck-common";
+import { summarizeRuns, type StatRun } from "./run-stats.logic";
 import type { ConfigService } from "@checkstack/backend-api";
 import type { InferClient } from "@checkstack/common";
 import type { CatalogApi } from "@checkstack/catalog-common";
@@ -921,6 +923,67 @@ export class HealthCheckService {
     };
   }
 
+  /**
+   * Compact run statistics over a window: totals + a small, capped bucket series.
+   * Backs the `healthcheck.runStats` AI tool so the assistant can answer
+   * "how often / how much downtime / uptime over the last N days" WITHOUT pulling
+   * thousands of raw rows into its context. Selects only the three columns the
+   * stats need and aggregates with the pure `summarizeRuns` helper. Same public
+   * gate as `getHistory` (no `result` payload is read).
+   */
+  async getRunStats(props: {
+    systemId?: string;
+    configurationId?: string;
+    startDate: Date;
+    endDate: Date;
+    sourceFilter?: string;
+    statusFilter?: HealthCheckStatus[];
+    maxBuckets?: number;
+  }): Promise<RunStats> {
+    const {
+      systemId,
+      configurationId,
+      startDate,
+      endDate,
+      sourceFilter,
+      statusFilter,
+      maxBuckets = 24,
+    } = props;
+
+    const conditions = [
+      gte(healthCheckRuns.timestamp, startDate),
+      lte(healthCheckRuns.timestamp, endDate),
+    ];
+    if (systemId) conditions.push(eq(healthCheckRuns.systemId, systemId));
+    if (configurationId)
+      conditions.push(eq(healthCheckRuns.configurationId, configurationId));
+    if (sourceFilter === "local") {
+      conditions.push(isNull(healthCheckRuns.sourceId));
+    } else if (sourceFilter) {
+      conditions.push(eq(healthCheckRuns.sourceId, sourceFilter));
+    }
+    if (statusFilter && statusFilter.length > 0) {
+      conditions.push(inArray(healthCheckRuns.status, statusFilter));
+    }
+
+    const rows = await this.db
+      .select({
+        timestamp: healthCheckRuns.timestamp,
+        status: healthCheckRuns.status,
+        latencyMs: healthCheckRuns.latencyMs,
+      })
+      .from(healthCheckRuns)
+      .where(and(...conditions));
+
+    const runs: StatRun[] = rows.map((r) => ({
+      timestamp: r.timestamp,
+      status: r.status,
+      latencyMs: r.latencyMs ?? undefined,
+    }));
+
+    return summarizeRuns({ runs, startDate, endDate, maxBuckets });
+  }
+
   /**
    * Get detailed health check run history with full result data.
    * Restricted to users with manage access.

package/src/status-page/rollup.test.ts

@@ -0,0 +1,53 @@
+import { describe, test, expect } from "bun:test";
+import {
+  mapHealthStatus,
+  rollupStatus,
+  overallBannerStatus,
+  statusBannerTitle,
+} from "./rollup";
+
+describe("mapHealthStatus", () => {
+  test("maps the internal health enum to the public vocabulary", () => {
+    expect(mapHealthStatus("healthy")).toBe("operational");
+    expect(mapHealthStatus("degraded")).toBe("degraded");
+    expect(mapHealthStatus("unhealthy")).toBe("major_outage");
+    expect(mapHealthStatus("weird")).toBe("unknown");
+  });
+});
+
+describe("rollupStatus", () => {
+  test("empty -> unknown; all operational -> operational", () => {
+    expect(rollupStatus([])).toBe("unknown");
+    expect(rollupStatus(["operational", "operational"])).toBe("operational");
+  });
+  test("a major outage dominates; maintenance ranks above degraded", () => {
+    expect(rollupStatus(["operational", "major_outage"])).toBe("major_outage");
+    expect(rollupStatus(["degraded", "maintenance"])).toBe("maintenance");
+  });
+});
+
+describe("overallBannerStatus", () => {
+  test("SOME down -> partial_outage; ALL down -> major_outage", () => {
+    expect(overallBannerStatus(["operational", "major_outage"])).toBe(
+      "partial_outage",
+    );
+    expect(overallBannerStatus(["major_outage", "major_outage"])).toBe(
+      "major_outage",
+    );
+    expect(overallBannerStatus(["major_outage", "unknown"])).toBe(
+      "major_outage",
+    );
+  });
+  test("no hard outages -> worst of the rest; empty/unknown -> unknown", () => {
+    expect(overallBannerStatus(["degraded", "operational"])).toBe("degraded");
+    expect(overallBannerStatus([])).toBe("unknown");
+    expect(overallBannerStatus(["unknown"])).toBe("unknown");
+  });
+});
+
+describe("statusBannerTitle", () => {
+  test("renders a human title", () => {
+    expect(statusBannerTitle("operational")).toBe("All systems operational");
+    expect(statusBannerTitle("partial_outage")).toBe("Partial system outage");
+  });
+});

package/src/status-page/rollup.ts

@@ -0,0 +1,82 @@
+import type { PublicStatus } from "@checkstack/status-page-common";
+
+/**
+ * Pure status mapping + rollup for the status-page health widgets. The INTERNAL
+ * health enum is never exposed; it is mapped onto the public vocabulary here.
+ * (Moved here from status-page-backend: the rollup is health-domain logic, so it
+ * lives with the plugin that owns health.)
+ */
+
+export function mapHealthStatus(
+  internal: "healthy" | "degraded" | "unhealthy" | string,
+): PublicStatus {
+  switch (internal) {
+    case "healthy": {
+      return "operational";
+    }
+    case "degraded": {
+      return "degraded";
+    }
+    case "unhealthy": {
+      return "major_outage";
+    }
+    default: {
+      return "unknown";
+    }
+  }
+}
+
+const PRECEDENCE: PublicStatus[] = [
+  "major_outage",
+  "partial_outage",
+  "maintenance",
+  "degraded",
+  "operational",
+  "unknown",
+];
+
+export function rollupStatus(statuses: PublicStatus[]): PublicStatus {
+  if (statuses.length === 0) return "unknown";
+  for (const candidate of PRECEDENCE) {
+    if (statuses.includes(candidate)) return candidate;
+  }
+  return "unknown";
+}
+
+/**
+ * Overall BANNER status: distinguishes a PARTIAL outage (some, not all, known
+ * systems down) from a MAJOR one (all known systems down). `unknown` is ignored
+ * unless everything is unknown.
+ */
+export function overallBannerStatus(statuses: PublicStatus[]): PublicStatus {
+  const known = statuses.filter((s) => s !== "unknown");
+  if (known.length === 0) return "unknown";
+  const majors = known.filter((s) => s === "major_outage").length;
+  if (majors > 0) {
+    return majors === known.length ? "major_outage" : "partial_outage";
+  }
+  return rollupStatus(known);
+}
+
+export function statusBannerTitle(status: PublicStatus): string {
+  switch (status) {
+    case "operational": {
+      return "All systems operational";
+    }
+    case "degraded": {
+      return "Degraded performance";
+    }
+    case "partial_outage": {
+      return "Partial system outage";
+    }
+    case "major_outage": {
+      return "Major system outage";
+    }
+    case "maintenance": {
+      return "Under maintenance";
+    }
+    case "unknown": {
+      return "Status unknown";
+    }
+  }
+}