@checkstack/healthcheck-backend 1.5.0 → 1.6.0

package/src/health-state.ts

@@ -1,4 +1,4 @@
-import { and, desc, eq, gte } from "drizzle-orm";
+import { and, desc, eq, gte, isNull } from "drizzle-orm";
 import type { HealthCheckStatus } from "@checkstack/healthcheck-common";
 import type { Logger, SafeDatabase } from "@checkstack/backend-api";
 import type { InferClient } from "@checkstack/common";
@@ -122,15 +122,28 @@ export async function findLatestRun({
   db,
   systemId,
   configurationId,
+  environmentId,
 }: {
   db: Db;
   systemId: string;
   configurationId?: string;
+  /**
+   * Environment to scope the run lookup to (Phase 3b). `undefined` = any
+   * environment (rollup). `null` = env-less runs only. A string = that env.
+   */
+  environmentId?: string | null;
 }): Promise<{ latencyMs?: number; lastRunAt?: Date }> {
   const conditions = [eq(healthCheckRuns.systemId, systemId)];
   if (configurationId) {
     conditions.push(eq(healthCheckRuns.configurationId, configurationId));
   }
+  if (environmentId !== undefined) {
+    conditions.push(
+      environmentId === null
+        ? isNull(healthCheckRuns.environmentId)
+        : eq(healthCheckRuns.environmentId, environmentId),
+    );
+  }
 
   const [row] = await db
     .select({
@@ -161,12 +174,19 @@ export async function computeWindowedMetrics({
   db,
   systemId,
   configurationId,
+  environmentId,
   now = new Date(),
   windowHours = DEFAULT_METRICS_WINDOW_HOURS,
 }: {
   db: Db;
   systemId: string;
   configurationId?: string;
+  /**
+   * Environment to scope the windowed metrics to (Phase 3b). `undefined` =
+   * any environment (rollup). `null` = env-less aggregates only. A string =
+   * that environment's aggregate buckets only.
+   */
+  environmentId?: string | null;
   now?: Date;
   windowHours?: number;
 }): Promise<{
@@ -185,6 +205,13 @@ export async function computeWindowedMetrics({
       eq(healthCheckAggregates.configurationId, configurationId),
     );
   }
+  if (environmentId !== undefined) {
+    conditions.push(
+      environmentId === null
+        ? isNull(healthCheckAggregates.environmentId)
+        : eq(healthCheckAggregates.environmentId, environmentId),
+    );
+  }
 
   const buckets = await db
     .select({
@@ -284,6 +311,7 @@ export async function computeHealthState({
   db,
   systemId,
   configurationId,
+  environmentId,
   resolveStatus,
   maintenanceClient,
   logger,
@@ -293,6 +321,14 @@ export async function computeHealthState({
   db: Db;
   systemId: string;
   configurationId?: string;
+  /**
+   * Environment to scope EVERY durable read to (Phase 3b). `undefined` = the
+   * system rollup (all environments + env-less). `null` = the env-less slice.
+   * A string = that environment. `inStatusSince`, latest run, windowed
+   * metrics, and the transition count all narrow to this env so a per-env
+   * health snapshot reflects only that environment's runs/transitions.
+   */
+  environmentId?: string | null;
   /** Returns the aggregate status for the system (per-check when scoped). */
   resolveStatus: () => Promise<HealthCheckStatus>;
   maintenanceClient?: MaintenanceClient;
@@ -305,14 +341,15 @@ export async function computeHealthState({
 
   const [inStatusSince, latest, windowed, inMaintenance, transitionsInWindow] =
     await Promise.all([
-      findInStatusSince({ db, systemId, status }),
-      findLatestRun({ db, systemId, configurationId }),
-      computeWindowedMetrics({ db, systemId, configurationId, now }),
+      findInStatusSince({ db, systemId, status, environmentId }),
+      findLatestRun({ db, systemId, configurationId, environmentId }),
+      computeWindowedMetrics({ db, systemId, configurationId, environmentId, now }),
       resolveInMaintenance({ maintenanceClient, systemId, logger }),
       countStateTransitionsInWindow({
         db,
         systemId,
         windowMinutes: transitionWindowMinutes,
+        environmentId,
         now,
       }),
     ]);

package/src/healthcheck-gitops-kinds.test.ts

@@ -415,6 +415,101 @@ describe("Healthcheck GitOps Kind: Healthcheck", () => {
     ).rejects.toThrow(/config validation failed/);
   });
 
+  it("migrates an OLD-shape authored config forward and stores the migrated value", async () => {
+    // A strategy at version 2 whose v1->v2 migration drops a removed
+    // `legacyMode` key. Authored gitops YAML still in the v1 shape (carrying
+    // `legacyMode`) must be migrated forward and applied, not rejected.
+    const v2Schema = z.object({ host: z.string() });
+    const versionedStrategy = {
+      id: "postgres",
+      displayName: "PostgreSQL",
+      description: "test",
+      config: new Versioned({
+        version: 2,
+        schema: v2Schema,
+        migrations: [
+          {
+            fromVersion: 1,
+            toVersion: 2,
+            description: "Drop removed legacyMode key",
+            migrate: ({ legacyMode: _legacyMode, ...rest }: Record<string, unknown>) =>
+              rest,
+          },
+        ],
+      }),
+    };
+    mockHCRegistry.getStrategiesWithMeta = () =>
+      [
+        { strategy: versionedStrategy, ownerPluginId: "mock", qualifiedId: "postgres" },
+      ] as any;
+
+    const kind = buildKind();
+
+    const result = await kind.reconcile({
+      entity: {
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Healthcheck",
+        metadata: { name: "legacy-check" },
+        spec: {
+          strategy: "postgres",
+          intervalSeconds: 30,
+          // Old v1 shape: carries the now-removed `legacyMode`.
+          config: { host: "db.legacy", legacyMode: true },
+        },
+      },
+      context: mockContext,
+    });
+
+    expect(result.entityId).toBe("hc-1");
+    // The MIGRATED config (legacyMode dropped) is what gets stored.
+    expect(mockService.configs[0].config).toEqual({ host: "db.legacy" });
+  });
+
+  it("rejects a genuine typo the migration does not account for (strict)", async () => {
+    const v2Schema = z.object({ host: z.string() });
+    const versionedStrategy = {
+      id: "postgres",
+      displayName: "PostgreSQL",
+      description: "test",
+      config: new Versioned({
+        version: 2,
+        schema: v2Schema,
+        migrations: [
+          {
+            fromVersion: 1,
+            toVersion: 2,
+            description: "Drop removed legacyMode key",
+            migrate: ({ legacyMode: _legacyMode, ...rest }: Record<string, unknown>) =>
+              rest,
+          },
+        ],
+      }),
+    };
+    mockHCRegistry.getStrategiesWithMeta = () =>
+      [
+        { strategy: versionedStrategy, ownerPluginId: "mock", qualifiedId: "postgres" },
+      ] as any;
+
+    const kind = buildKind();
+
+    await expect(
+      kind.reconcile({
+        entity: {
+          apiVersion: CHECKSTACK_API_VERSION,
+          kind: "Healthcheck",
+          metadata: { name: "typo-check" },
+          spec: {
+            strategy: "postgres",
+            intervalSeconds: 30,
+            // `hsot` is a genuine typo no migration accounts for.
+            config: { host: "db.local", hsot: "oops" },
+          },
+        },
+        context: mockContext,
+      }),
+    ).rejects.toThrow(/config validation failed/);
+  });
+
   it("validates collector configs against collector registry schemas", async () => {
     const kind = buildKind();
 

package/src/healthcheck-gitops-kinds.ts

@@ -15,6 +15,7 @@ import type {
 } from "@checkstack/backend-api";
 import { NotificationPolicySchema } from "@checkstack/healthcheck-common";
 import { HealthCheckService } from "./service";
+import { validateVersionedConfigStrict } from "./validate-configuration";
 import {
   DynamicOperators,
   numericField,
@@ -154,13 +155,25 @@ export function buildHealthcheckKind(
         },
       );
 
-      // Validate resolved config against strategy's Zod schema
-      const configValidation = strategy.config.schema.safeParse(resolvedConfig);
-      if (!configValidation.success) {
+      // Migrate-then-validate-strict: authored gitops YAML may be in an OLD
+      // config shape, so run the migration chain (assume-v1-on-read) before
+      // strict validation. Old-shape YAML still applies; genuine typos
+      // (unknown keys no migration accounts for) are still rejected. Shares the
+      // exact strict-validate path the `validateConfiguration` RPC uses, so the
+      // two agree on what counts as valid. A strategy config is always a plain
+      // object validated by the strategy's own schema, so narrowing the
+      // `unknown` result to the stored `Record` shape is safe.
+      const strategyResult = await validateVersionedConfigStrict({
+        config: strategy.config,
+        value: resolvedConfig,
+        basePath: ["config"],
+      });
+      if (!strategyResult.ok) {
         throw new Error(
-          `Strategy "${spec.strategy}" config validation failed: ${configValidation.error.message}`,
+          `Strategy "${spec.strategy}" config validation failed: ${formatIssues(strategyResult.issues)}`,
         );
       }
+      const migratedConfig = strategyResult.value as Record<string, unknown>;
 
       // Resolve and validate collector configs using their registry schemas
       const resolvedCollectors = spec.collectors
@@ -190,17 +203,30 @@ export function buildHealthcheckKind(
                   schema: registered.collector.config.schema,
                 });
 
-              const collectorConfigValidation =
-                registered.collector.config.schema.safeParse(
-                  resolvedCollectorConfig,
-                );
-              if (!collectorConfigValidation.success) {
+              // Migrate-then-validate-strict: authored gitops YAML may use an
+              // OLD collector config shape. Run the migration chain before
+              // strict validation so old-shape YAML still applies while
+              // genuine typos are still rejected. Shares the exact strict-
+              // validate path the `validateConfiguration` RPC uses. A collector
+              // config is always a plain object validated by the collector's
+              // schema, so narrowing the `unknown` result to the stored
+              // `Record` shape is safe.
+              const collectorResult = await validateVersionedConfigStrict({
+                config: registered.collector.config,
+                value: resolvedCollectorConfig,
+                basePath: ["config"],
+              });
+              if (!collectorResult.ok) {
                 throw new Error(
-                  `Collector "${c.collectorId}" config validation failed: ${collectorConfigValidation.error.message}`,
+                  `Collector "${c.collectorId}" config validation failed: ${formatIssues(collectorResult.issues)}`,
                 );
               }
+              const migratedCollectorConfig = collectorResult.value as Record<
+                string,
+                unknown
+              >;
 
-              return { ...c, config: resolvedCollectorConfig };
+              return { ...c, config: migratedCollectorConfig };
             }),
           )
         : undefined;
@@ -212,7 +238,7 @@ export function buildHealthcheckKind(
         await service.updateConfiguration(existingEntityId, {
           name: displayName,
           strategyId: spec.strategy,
-          config: resolvedConfig,
+          config: migratedConfig,
           intervalSeconds: spec.intervalSeconds,
           collectors: resolvedCollectors?.map((c) => ({
             id: c.collectorId,
@@ -230,7 +256,7 @@ export function buildHealthcheckKind(
       const config = await service.createConfiguration({
         name: displayName,
         strategyId: spec.strategy,
-        config: resolvedConfig,
+        config: migratedConfig,
         intervalSeconds: spec.intervalSeconds,
         collectors: resolvedCollectors?.map((c) => ({
           id: c.collectorId,
@@ -517,6 +543,23 @@ export function registerHealthcheckGitOpsDocumentation({
   }
 }
 
+/**
+ * Render the structured issues from {@link validateVersionedConfigStrict} into
+ * a single human-readable message for the thrown GitOps reconcile error,
+ * preserving the per-field path (e.g. `config.url: Invalid url`).
+ */
+function formatIssues(
+  issues: Array<{ path: Array<string | number>; message: string }>,
+): string {
+  return issues
+    .map((issue) =>
+      issue.path.length > 0
+        ? `${issue.path.join(".")}: ${issue.message}`
+        : issue.message,
+    )
+    .join("; ");
+}
+
 function unwrapZodType(type: z.ZodTypeAny): z.ZodTypeAny {
   let current = type;
   while (current) {

package/src/index.ts

@@ -17,6 +17,12 @@ import {
   NotificationApi,
   specToRegistration,
 } from "@checkstack/notification-common";
+import {
+  aiToolExtensionPoint,
+  aiToolProjectionExtensionPoint,
+  deferredProjectionExecute,
+} from "@checkstack/ai-backend";
+import { buildHealthcheckAiTools } from "./ai/register-ai-tools";
 import {
   createBackendPlugin,
   coreServices,
@@ -234,6 +240,30 @@ export default createBackendPlugin({
           collectorRegistry,
         );
 
+        // Register this plugin's AI tools (propose/update/delete) into the AI
+        // registry via the extension point - owned here, not in ai-backend.
+        const aiToolExt = env.getExtensionPoint(aiToolExtensionPoint);
+        for (const tool of buildHealthcheckAiTools()) {
+          aiToolExt.registerTool(tool, pluginMetadata);
+        }
+
+        // Expose this plugin's OWN read-only AI projection of the existing
+        // `getConfigurations` query via aiToolProjectionExtensionPoint - owned
+        // here, not in ai-backend. The projected read tool is routed by the
+        // transport (MCP / chat) AS the principal, so `getConfigurations`'
+        // own contract access rules gate it; `deferredProjectionExecute` is
+        // the fail-closed net if a transport ever forgot to route.
+        env.getExtensionPoint(aiToolProjectionExtensionPoint).expose({
+          procedure: healthCheckContract.getConfigurations,
+          sourcePluginMetadata: pluginMetadata,
+          procedureKey: "getConfigurations",
+          name: "healthcheck.status",
+          description:
+            "List health-check configurations and their current status. Read-only.",
+          effect: "read",
+          execute: deferredProjectionExecute,
+        });
+
         // Create catalog client for notification delegation
         const catalogClient = rpcClient.forPlugin(CatalogApi);
 

package/src/migration-chain-contract.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Contract test: every healthcheck-backend-owned Versioned config that is
+ * stored and read back via the migration chain MUST have a COMPLETE,
+ * contiguous chain from version 1 to its current `version`. Pure STRUCTURAL
+ * check (`validateMigrationChainFromV1` — no `migrate()` is run), so it carries
+ * zero per-config upkeep: the day someone bumps a config's `version` without
+ * shipping a covering migration, the read path would silently fail at runtime
+ * on a genuinely-v1 stored blob — this test turns that into a CI failure
+ * instead. See the HTTP plugin's equivalent test for the full rationale.
+ *
+ * Covers the configs this CORE package owns: the per-assignment state
+ * thresholds wrapper and every built-in automation action config. The
+ * strategy / collector `config` / `result` / `aggregatedResult` Versioned
+ * schemas are registered by the healthcheck strategy plugins (e.g.
+ * healthcheck-http-backend) and are guarded by an equivalent contract test in
+ * each plugin package.
+ */
+import { describe, expect, it } from "bun:test";
+import type { QueueManager } from "@checkstack/queue-api";
+import type { Hook } from "@checkstack/backend-api";
+import { stateThresholds } from "./state-thresholds-migrations";
+import { createHealthCheckActions } from "./automations";
+import type { HealthCheckService } from "./service";
+
+// `createHealthCheckActions` only constructs the action definitions; the deps
+// are touched lazily inside `execute()`, which the contract check never calls.
+// Stubs are sufficient.
+const stubService = {} as unknown as HealthCheckService;
+const stubQueueManager = {} as unknown as QueueManager;
+const stubEmitHook = async <T>(_hook: Hook<T>, _payload: T): Promise<void> => {};
+
+describe("healthcheck config migration-chain contract", () => {
+  it("the state-thresholds config has a complete v1->version chain", () => {
+    const problem = stateThresholds.validateMigrationChainFromV1();
+    expect(
+      problem,
+      `state thresholds config (version ${stateThresholds.version}) has a broken migration chain: ${problem}`,
+    ).toBeUndefined();
+  });
+
+  it("every built-in action config has a complete v1->version chain", () => {
+    const actions = createHealthCheckActions({
+      service: stubService,
+      queueManager: stubQueueManager,
+      emitHook: stubEmitHook,
+    });
+    expect(actions.length).toBeGreaterThan(0);
+
+    for (const action of actions) {
+      const problem = action.config.validateMigrationChainFromV1();
+      expect(
+        problem,
+        `Action "${action.id}" config (version ${action.config.version}) has a broken migration chain: ${problem}`,
+      ).toBeUndefined();
+    }
+  });
+});