@checkstack/slo-backend 0.3.5 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # @checkstack/slo-backend
 
+## 0.4.1
+
+### Patch Changes
+
+- Updated dependencies [7c97b43]
+- Updated dependencies [9016526]
+  - @checkstack/healthcheck-backend@1.1.0
+  - @checkstack/common@0.10.0
+  - @checkstack/catalog-common@2.2.0
+  - @checkstack/healthcheck-common@1.1.0
+  - @checkstack/dependency-common@1.1.0
+  - @checkstack/slo-common@0.4.0
+  - @checkstack/gitops-common@0.4.0
+  - @checkstack/integration-common@0.4.0
+  - @checkstack/backend-api@0.15.2
+  - @checkstack/catalog-backend@1.1.1
+  - @checkstack/command-backend@0.1.26
+  - @checkstack/gitops-backend@0.3.1
+  - @checkstack/integration-backend@0.1.26
+  - @checkstack/signal-common@0.2.3
+  - @checkstack/cache-api@0.3.1
+  - @checkstack/queue-api@0.3.1
+  - @checkstack/cache-utils@0.2.6
+
+## 0.4.0
+
+### Minor Changes
+
+- f6f9a5c: Add a GitOps `SLO` kind so reliability targets can be declared in YAML.
+
+  The kind references its target system via `systemRef` and may optionally
+  narrow to a single healthcheck via `healthcheckRef`. Excluded
+  dependencies are referenced by ref and resolved to system IDs at
+  reconcile time.
+
+  ```yaml
+  apiVersion: checkstack.io/v1alpha1
+  kind: SLO
+  metadata:
+    name: payments-availability
+  spec:
+    systemRef: { kind: System, name: payments-api }
+    target: 99.9
+    windowDays: 30
+  ```
+
+  Reconcile maps to `SloService.createObjective` /
+  `updateObjective` / `deleteObjective`; the entity ID stored in
+  provenance is the SLO objective UUID, so renames in YAML preserve
+  identity.
+
+### Patch Changes
+
+- Updated dependencies [42abfff]
+- Updated dependencies [f6f9a5c]
+- Updated dependencies [1ef2e79]
+- Updated dependencies [aa89bc5]
+  - @checkstack/common@0.9.0
+  - @checkstack/gitops-common@0.3.0
+  - @checkstack/gitops-backend@0.3.0
+  - @checkstack/catalog-common@2.1.0
+  - @checkstack/catalog-backend@1.1.0
+  - @checkstack/queue-api@0.3.0
+  - @checkstack/cache-api@0.3.0
+  - @checkstack/backend-api@0.15.1
+  - @checkstack/command-backend@0.1.25
+  - @checkstack/dependency-common@1.0.2
+  - @checkstack/healthcheck-backend@1.0.4
+  - @checkstack/healthcheck-common@1.0.2
+  - @checkstack/integration-backend@0.1.25
+  - @checkstack/integration-common@0.3.2
+  - @checkstack/signal-common@0.2.2
+  - @checkstack/slo-common@0.3.3
+  - @checkstack/cache-utils@0.2.5
+
 ## 0.3.5
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/slo-backend",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -14,30 +14,32 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.14.1",
-    "@checkstack/cache-api": "0.2.3",
-    "@checkstack/cache-utils": "0.2.3",
-    "@checkstack/slo-common": "0.3.1",
-    "@checkstack/healthcheck-common": "1.0.0",
-    "@checkstack/healthcheck-backend": "1.0.2",
-    "@checkstack/dependency-common": "1.0.0",
-    "@checkstack/catalog-common": "2.0.0",
-    "@checkstack/catalog-backend": "1.0.1",
-    "@checkstack/command-backend": "0.1.23",
-    "@checkstack/signal-common": "0.2.0",
-    "@checkstack/integration-backend": "0.1.23",
-    "@checkstack/integration-common": "0.3.0",
-    "@checkstack/common": "0.7.0",
-    "@checkstack/queue-api": "0.2.17",
+    "@checkstack/backend-api": "0.15.1",
+    "@checkstack/cache-api": "0.3.0",
+    "@checkstack/cache-utils": "0.2.5",
+    "@checkstack/slo-common": "0.3.3",
+    "@checkstack/healthcheck-common": "1.0.2",
+    "@checkstack/healthcheck-backend": "1.0.4",
+    "@checkstack/dependency-common": "1.0.2",
+    "@checkstack/catalog-common": "2.1.0",
+    "@checkstack/catalog-backend": "1.1.0",
+    "@checkstack/command-backend": "0.1.25",
+    "@checkstack/signal-common": "0.2.2",
+    "@checkstack/integration-backend": "0.1.25",
+    "@checkstack/integration-common": "0.3.2",
+    "@checkstack/gitops-backend": "0.3.0",
+    "@checkstack/gitops-common": "0.3.0",
+    "@checkstack/common": "0.9.0",
+    "@checkstack/queue-api": "0.3.0",
     "drizzle-orm": "^0.45.0",
     "zod": "^4.2.1",
     "@orpc/server": "^1.13.2"
   },
   "devDependencies": {
-    "@checkstack/drizzle-helper": "0.0.4",
-    "@checkstack/scripts": "0.1.2",
-    "@checkstack/test-utils-backend": "0.1.23",
-    "@checkstack/tsconfig": "0.0.6",
+    "@checkstack/drizzle-helper": "0.0.5",
+    "@checkstack/scripts": "0.3.1",
+    "@checkstack/test-utils-backend": "0.1.25",
+    "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
     "drizzle-kit": "^0.31.10",
     "typescript": "^5.0.0"

package/src/index.ts

@@ -24,6 +24,8 @@ import { sloHooks } from "./hooks";
 import { setupDailySnapshotJob } from "./streak-calculator";
 import { setupWeeklyDigestJob } from "./weekly-digest";
 import { evaluateAchievements } from "./achievement-evaluator";
+import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
+import { registerSloGitOpsKinds } from "./slo-gitops-kinds";
 
 // =============================================================================
 // Integration Event Payload Schemas
@@ -168,6 +170,17 @@ export default createBackendPlugin({
 
     // Shared references across init/afterPluginsReady (maintenance-backend pattern)
     let sharedEngine: SloEngine;
+    let gitopsService: SloService | undefined;
+
+    // ─── GitOps Entity Kind Registration ─────────────────────────────
+    const kindRegistry = env.getExtensionPoint(entityKindExtensionPoint);
+    registerSloGitOpsKinds({
+      kindRegistry,
+      getService: () => {
+        if (!gitopsService) throw new Error("SloService not initialized");
+        return gitopsService;
+      },
+    });
 
     env.registerInit({
       schema,
@@ -190,6 +203,7 @@ export default createBackendPlugin({
         logger.debug("🔧 Initializing SLO Backend...");
 
         const service = new SloService(database as SafeDatabase<typeof schema>);
+        gitopsService = service;
         const engine = new SloEngine({
           service,
           signalService,

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

@@ -0,0 +1,238 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import {
+  CHECKSTACK_API_VERSION,
+  type ReconcileContext,
+} from "@checkstack/gitops-common";
+import type { SloService } from "./service";
+import type { SloObjective } from "@checkstack/slo-common";
+import { buildSloKind } from "./slo-gitops-kinds";
+
+const noopLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};
+
+const buildContext = (
+  overrides: Partial<ReconcileContext> = {},
+): ReconcileContext =>
+  ({
+    logger: noopLogger,
+    resolveEntityRef: async () => undefined,
+    resolveSecretsBySchema: async ({ value }) => ({
+      resolved: value,
+      warnings: [],
+    }),
+    ...overrides,
+  }) as ReconcileContext;
+
+const stubService = () => {
+  const created: SloObjective = {
+    id: "slo-1",
+    systemId: "sys-1",
+    healthCheckConfigurationId: null,
+    target: 99.9,
+    windowDays: 30,
+    dependencyExclusion: "strict",
+    excludedDependencyIds: [],
+    burnRateThresholds: {
+      warningPercent: 50,
+      criticalPercent: 80,
+      fastBurnMultiplier: 5,
+    },
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+  const createObjective = mock(async () => created);
+  const updateObjective = mock(async () => created);
+  const deleteObjective = mock(async () => true);
+  return {
+    created,
+    createObjective,
+    updateObjective,
+    deleteObjective,
+    service: {
+      createObjective,
+      updateObjective,
+      deleteObjective,
+    } as unknown as SloService,
+  };
+};
+
+const refResolver =
+  (table: Record<string, string>) =>
+  async ({ entityName }: { kind: string; entityName: string }) =>
+    table[entityName];
+
+const mkEntity = <TSpec>(name: string, spec: TSpec) => ({
+  apiVersion: CHECKSTACK_API_VERSION,
+  kind: "SLO",
+  metadata: { name },
+  spec,
+});
+
+describe("buildSloKind", () => {
+  let stub: ReturnType<typeof stubService>;
+  let kind: ReturnType<typeof buildSloKind>;
+
+  beforeEach(() => {
+    stub = stubService();
+    kind = buildSloKind({ getService: () => stub.service });
+  });
+
+  it("registers under SLO kind", () => {
+    expect(kind.kind).toBe("SLO");
+  });
+
+  it("creates an objective when no existing entity id is supplied", async () => {
+    const result = await kind.reconcile({
+      entity: mkEntity("payments-availability", {
+        systemRef: { kind: "System", name: "payments-api" },
+        target: 99.9,
+        windowDays: 30,
+      }),
+      context: buildContext({
+        resolveEntityRef: refResolver({ "payments-api": "sys-1" }),
+      }),
+    });
+
+    expect(result.entityId).toBe("slo-1");
+    expect(stub.createObjective).toHaveBeenCalledTimes(1);
+    expect(stub.createObjective).toHaveBeenCalledWith({
+      input: {
+        systemId: "sys-1",
+        healthCheckConfigurationId: undefined,
+        target: 99.9,
+        windowDays: 30,
+        dependencyExclusion: "strict",
+        excludedDependencyIds: [],
+        burnRateThresholds: {
+          warningPercent: 50,
+          criticalPercent: 80,
+          fastBurnMultiplier: 5,
+        },
+      },
+    });
+  });
+
+  it("resolves an optional healthcheck ref into healthCheckConfigurationId", async () => {
+    await kind.reconcile({
+      entity: mkEntity("payments-http-availability", {
+        systemRef: { kind: "System", name: "payments-api" },
+        healthcheckRef: { kind: "Healthcheck", name: "payments-http" },
+        target: 99.95,
+        windowDays: 7,
+      }),
+      context: buildContext({
+        resolveEntityRef: refResolver({
+          "payments-api": "sys-1",
+          "payments-http": "hc-1",
+        }),
+      }),
+    });
+
+    expect(stub.createObjective).toHaveBeenCalledWith({
+      input: expect.objectContaining({
+        systemId: "sys-1",
+        healthCheckConfigurationId: "hc-1",
+      }),
+    });
+  });
+
+  it("resolves excluded dependency refs to system ids", async () => {
+    await kind.reconcile({
+      entity: mkEntity("core", {
+        systemRef: { kind: "System", name: "core" },
+        target: 99.9,
+        windowDays: 30,
+        dependencyExclusion: "self-only",
+        excludedDependencyRefs: [
+          { kind: "System", name: "third-party-payments" },
+          { kind: "System", name: "third-party-email" },
+        ],
+      }),
+      context: buildContext({
+        resolveEntityRef: refResolver({
+          core: "sys-core",
+          "third-party-payments": "sys-pay",
+          "third-party-email": "sys-mail",
+        }),
+      }),
+    });
+
+    expect(stub.createObjective).toHaveBeenCalledWith({
+      input: expect.objectContaining({
+        excludedDependencyIds: ["sys-pay", "sys-mail"],
+        dependencyExclusion: "self-only",
+      }),
+    });
+  });
+
+  it("updates an existing objective when existingEntityId is supplied", async () => {
+    await kind.reconcile({
+      entity: mkEntity("payments", {
+        systemRef: { kind: "System", name: "payments-api" },
+        target: 99.95,
+        windowDays: 30,
+      }),
+      existingEntityId: "slo-existing",
+      context: buildContext({
+        resolveEntityRef: refResolver({ "payments-api": "sys-1" }),
+      }),
+    });
+
+    expect(stub.createObjective).not.toHaveBeenCalled();
+    expect(stub.updateObjective).toHaveBeenCalledWith({
+      input: expect.objectContaining({
+        id: "slo-existing",
+        target: 99.95,
+        windowDays: 30,
+      }),
+    });
+  });
+
+  it("treats pending-* entityIds as fresh creates", async () => {
+    await kind.reconcile({
+      entity: mkEntity("payments", {
+        systemRef: { kind: "System", name: "payments-api" },
+        target: 99.9,
+        windowDays: 30,
+      }),
+      existingEntityId: "pending-abc",
+      context: buildContext({
+        resolveEntityRef: refResolver({ "payments-api": "sys-1" }),
+      }),
+    });
+
+    expect(stub.createObjective).toHaveBeenCalledTimes(1);
+    expect(stub.updateObjective).not.toHaveBeenCalled();
+  });
+
+  it("throws when systemRef cannot be resolved", async () => {
+    await expect(
+      kind.reconcile({
+        entity: mkEntity("broken", {
+          systemRef: { kind: "System", name: "nope" },
+          target: 99.9,
+          windowDays: 30,
+        }),
+        context: buildContext({ resolveEntityRef: async () => undefined }),
+      }),
+    ).rejects.toThrow(/Cannot resolve system ref "nope"/);
+  });
+
+  it("delegates delete to the service", async () => {
+    await kind.delete!({
+      entityName: "payments",
+      entityId: "slo-1",
+      context: buildContext(),
+    });
+    expect(stub.deleteObjective).toHaveBeenCalledWith({ id: "slo-1" });
+  });
+
+  it("delete is a no-op when entityId is missing", async () => {
+    await kind.delete!({ entityName: "x", context: buildContext() });
+    expect(stub.deleteObjective).not.toHaveBeenCalled();
+  });
+});

package/src/slo-gitops-kinds.ts

@@ -0,0 +1,174 @@
+import { z } from "zod";
+import {
+  CHECKSTACK_API_VERSION,
+  entityRefSchema,
+  type EntityKindDefinition,
+  type EntityKindRegistry,
+  type ReconcileContext,
+} from "@checkstack/gitops-common";
+import {
+  DependencyExclusionModeSchema,
+  BurnRateThresholdsSchema,
+} from "@checkstack/slo-common";
+import type { SloService } from "./service";
+
+interface SloGitOpsKindsDeps {
+  /** Lazy accessor — populated during init(), invoked at reconcile time. */
+  getService: () => SloService;
+}
+
+// ─── SLO Spec Schema ───────────────────────────────────────────────────────
+
+/**
+ * GitOps spec for `kind: SLO`.
+ *
+ * An SLO targets a specific system (required) and may optionally narrow to a
+ * single healthcheck on that system. When `healthcheckRef` is omitted the SLO
+ * covers the system's aggregate availability across all of its healthchecks.
+ */
+const sloSpecSchema = z.object({
+  systemRef: entityRefSchema,
+  healthcheckRef: entityRefSchema.optional(),
+  target: z.number().min(0).max(100),
+  windowDays: z.number().int().positive(),
+  dependencyExclusion: DependencyExclusionModeSchema.optional(),
+  excludedDependencyRefs: z.array(entityRefSchema).optional(),
+  burnRateThresholds: BurnRateThresholdsSchema.optional(),
+});
+
+type SloSpec = z.infer<typeof sloSpecSchema>;
+
+// ─── Kind builder ───────────────────────────────────────────────────────────
+
+const resolveRequiredRef = async ({
+  context,
+  ref,
+  refKindLabel,
+}: {
+  context: ReconcileContext;
+  ref: { kind: string; name: string };
+  refKindLabel: string;
+}): Promise<string> => {
+  const id = await context.resolveEntityRef({
+    kind: ref.kind,
+    entityName: ref.name,
+  });
+  if (!id) {
+    throw new Error(
+      `Cannot resolve ${refKindLabel} ref "${ref.name}" (kind: ${ref.kind}) — ensure the entity exists`,
+    );
+  }
+  return id;
+};
+
+export function buildSloKind(
+  deps: SloGitOpsKindsDeps,
+): EntityKindDefinition<SloSpec> {
+  return {
+    apiVersion: CHECKSTACK_API_VERSION,
+    kind: "SLO",
+    specSchema: sloSpecSchema,
+
+    reconcile: async ({
+      entity,
+      existingEntityId,
+      context,
+    }: {
+      entity: {
+        metadata: { name: string; title?: string; description?: string };
+        spec: SloSpec;
+      };
+      existingEntityId?: string;
+      context: ReconcileContext;
+    }) => {
+      const { spec } = entity;
+      const service = deps.getService();
+
+      const systemId = await resolveRequiredRef({
+        context,
+        ref: spec.systemRef,
+        refKindLabel: "system",
+      });
+
+      let healthCheckConfigurationId: string | undefined;
+      if (spec.healthcheckRef) {
+        healthCheckConfigurationId = await resolveRequiredRef({
+          context,
+          ref: spec.healthcheckRef,
+          refKindLabel: "healthcheck",
+        });
+      }
+
+      const excludedDependencyIds = spec.excludedDependencyRefs
+        ? await Promise.all(
+            spec.excludedDependencyRefs.map((ref) =>
+              resolveRequiredRef({
+                context,
+                ref,
+                refKindLabel: "excluded dependency",
+              }),
+            ),
+          )
+        : [];
+
+      if (existingEntityId && !existingEntityId.startsWith("pending-")) {
+        await service.updateObjective({
+          input: {
+            id: existingEntityId,
+            target: spec.target,
+            windowDays: spec.windowDays,
+            dependencyExclusion: spec.dependencyExclusion,
+            excludedDependencyIds,
+            burnRateThresholds: spec.burnRateThresholds,
+          },
+        });
+        context.logger.info(
+          `GitOps: updated SLO "${entity.metadata.name}" (id: ${existingEntityId})`,
+        );
+        return { entityId: existingEntityId };
+      }
+
+      const created = await service.createObjective({
+        input: {
+          systemId,
+          healthCheckConfigurationId,
+          target: spec.target,
+          windowDays: spec.windowDays,
+          dependencyExclusion: spec.dependencyExclusion ?? "strict",
+          excludedDependencyIds,
+          burnRateThresholds: spec.burnRateThresholds ?? {
+            warningPercent: 50,
+            criticalPercent: 80,
+            fastBurnMultiplier: 5,
+          },
+        },
+      });
+      context.logger.info(
+        `GitOps: created SLO "${entity.metadata.name}" (id: ${created.id})`,
+      );
+      return { entityId: created.id };
+    },
+
+    delete: async ({
+      entityId,
+      context,
+    }: {
+      entityName: string;
+      entityId?: string;
+      context: ReconcileContext;
+    }) => {
+      if (!entityId) return;
+      await deps.getService().deleteObjective({ id: entityId });
+      context.logger.info(`GitOps: deleted SLO (id: ${entityId})`);
+    },
+  };
+}
+
+export function registerSloGitOpsKinds({
+  kindRegistry,
+  ...deps
+}: SloGitOpsKindsDeps & {
+  kindRegistry: EntityKindRegistry;
+}): void {
+  kindRegistry.registerKind(buildSloKind(deps));
+}

package/tsconfig.json

@@ -31,6 +31,12 @@
     {
       "path": "../drizzle-helper"
     },
+    {
+      "path": "../gitops-backend"
+    },
+    {
+      "path": "../gitops-common"
+    },
     {
       "path": "../healthcheck-backend"
     },