@checkstack/maintenance-backend 1.1.6 → 1.3.0

package/src/entity.test.ts

@@ -0,0 +1,280 @@
+/**
+ * Unit tests for the maintenance reactive-entity mapping (reactive
+ * automation engine §10.2). Proves the deriver returns the EXACT qualified
+ * trigger event ids existing automations match, the state builder produces
+ * the §10.2 entity shape, and the PLUGIN-BACKED `read`/`mutate`/`remove`
+ * helpers route to the service (no framework `entity_state`).
+ */
+import { describe, expect, it } from "bun:test";
+import { SYSTEM_ACTOR } from "@checkstack/common";
+import type {
+  EntityChanged,
+  EntityHandle,
+} from "@checkstack/automation-backend";
+
+import {
+  MAINTENANCE_CREATED_EVENT,
+  MAINTENANCE_ENTITY_KIND,
+  MAINTENANCE_UPDATED_EVENT,
+  createMaintenanceEntityRead,
+  deriveMaintenanceEvents,
+  maintenanceChangeToPayload,
+  maintenanceEntityStateSchema,
+  removeMaintenanceEntity,
+  toMaintenanceEntityState,
+  writeMaintenanceEntity,
+  type MaintenanceEntityState,
+} from "./entity";
+import {
+  maintenanceCreatedTrigger,
+  maintenanceUpdatedTrigger,
+} from "./automations";
+import type { MaintenanceService } from "./service";
+
+function makeChange(over: Partial<EntityChanged>): EntityChanged {
+  return {
+    kind: "maintenance",
+    id: "m-1",
+    prev: null,
+    next: { status: "scheduled", systemIds: [], startAt: "a", endAt: "b" },
+    delta: {},
+    changedFields: [],
+    actor: SYSTEM_ACTOR,
+    occurredAt: "2026-05-31T00:00:00.000Z",
+    ...over,
+  };
+}
+
+describe("maintenanceChangeToPayload — payloadSchema parity", () => {
+  it("a create payload validates against the created trigger's payloadSchema", () => {
+    const parsed = maintenanceCreatedTrigger.payloadSchema.parse(
+      maintenanceChangeToPayload(
+        makeChange({
+          prev: null,
+          next: {
+            status: "scheduled",
+            systemIds: ["sys-1"],
+            startAt: "2026-05-31T00:00:00.000Z",
+            endAt: "2026-05-31T01:00:00.000Z",
+          },
+        }),
+      ),
+    );
+    expect(parsed.maintenanceId).toBe("m-1");
+    expect(parsed.status).toBe("scheduled");
+    expect(parsed.systemIds).toEqual(["sys-1"]);
+    expect(parsed.startAt).toBe("2026-05-31T00:00:00.000Z");
+    expect(parsed.endAt).toBe("2026-05-31T01:00:00.000Z");
+  });
+
+  it("an update payload validates against the updated trigger's payloadSchema", () => {
+    const parsed = maintenanceUpdatedTrigger.payloadSchema.parse(
+      maintenanceChangeToPayload(
+        makeChange({
+          prev: {
+            status: "scheduled",
+            systemIds: ["sys-1"],
+            startAt: "2026-05-31T00:00:00.000Z",
+            endAt: "2026-05-31T01:00:00.000Z",
+          },
+          next: {
+            status: "in_progress",
+            systemIds: ["sys-1"],
+            startAt: "2026-05-31T00:00:00.000Z",
+            endAt: "2026-05-31T01:00:00.000Z",
+          },
+        }),
+      ),
+    );
+    expect(parsed.maintenanceId).toBe("m-1");
+    expect(parsed.status).toBe("in_progress");
+  });
+});
+
+describe("deriveMaintenanceEvents", () => {
+  it("maps a create (prev === null) to maintenance.created", () => {
+    const events = deriveMaintenanceEvents(makeChange({ prev: null }));
+    expect(events).toEqual([MAINTENANCE_CREATED_EVENT]);
+  });
+
+  it("maps an update (prev present, next present) to maintenance.updated", () => {
+    const events = deriveMaintenanceEvents(
+      makeChange({
+        prev: { status: "scheduled", systemIds: [], startAt: "a", endAt: "b" },
+        next: { status: "in_progress", systemIds: [], startAt: "a", endAt: "b" },
+      }),
+    );
+    expect(events).toEqual([MAINTENANCE_UPDATED_EVENT]);
+  });
+
+  it("maps a tombstone (next === null) to no event", () => {
+    const events = deriveMaintenanceEvents(
+      makeChange({
+        prev: { status: "scheduled", systemIds: [], startAt: "a", endAt: "b" },
+        next: null,
+      }),
+    );
+    expect(events).toEqual([]);
+  });
+
+  it("returns event ids that exactly equal the qualified trigger ids", () => {
+    // The created/updated trigger ids are namespaced to `${pluginId}.${id}`
+    // → `maintenance.created` / `maintenance.updated`. Lock the constants.
+    expect(MAINTENANCE_CREATED_EVENT).toBe("maintenance.created");
+    expect(MAINTENANCE_UPDATED_EVENT).toBe("maintenance.updated");
+  });
+});
+
+describe("toMaintenanceEntityState", () => {
+  it("serializes Date columns to ISO strings and validates against the schema", () => {
+    const state = toMaintenanceEntityState({
+      status: "scheduled",
+      systemIds: ["sys-1", "sys-2"],
+      startAt: new Date("2026-05-29T11:00:00Z"),
+      endAt: new Date("2026-05-29T12:00:00Z"),
+    });
+    expect(state).toEqual({
+      status: "scheduled",
+      systemIds: ["sys-1", "sys-2"],
+      startAt: "2026-05-29T11:00:00.000Z",
+      endAt: "2026-05-29T12:00:00.000Z",
+    });
+    expect(() => maintenanceEntityStateSchema.parse(state)).not.toThrow();
+  });
+
+  it("passes through already-ISO strings unchanged", () => {
+    const state = toMaintenanceEntityState({
+      status: "completed",
+      systemIds: [],
+      startAt: "2026-05-29T11:00:00.000Z",
+      endAt: "2026-05-29T12:00:00.000Z",
+    });
+    expect(state.startAt).toBe("2026-05-29T11:00:00.000Z");
+    expect(state.endAt).toBe("2026-05-29T12:00:00.000Z");
+  });
+});
+
+describe("createMaintenanceEntityRead", () => {
+  it("routes the batched read straight to the service (plugin-backed)", async () => {
+    const seen: ReadonlyArray<string>[] = [];
+    const service = {
+      async getManyEntityStates(ids: ReadonlyArray<string>) {
+        seen.push(ids);
+        return {
+          "m-1": {
+            status: "scheduled" as const,
+            systemIds: ["sys-1"],
+            startAt: "2026-05-29T11:00:00.000Z",
+            endAt: "2026-05-29T12:00:00.000Z",
+          },
+        };
+      },
+    } as unknown as MaintenanceService;
+    const read = createMaintenanceEntityRead(service);
+    const out = await read(["m-1", "m-2"]);
+    expect(seen).toEqual([["m-1", "m-2"]]);
+    expect(out["m-1"]).toEqual({
+      status: "scheduled",
+      systemIds: ["sys-1"],
+      startAt: "2026-05-29T11:00:00.000Z",
+      endAt: "2026-05-29T12:00:00.000Z",
+    });
+  });
+});
+
+describe("writeMaintenanceEntity", () => {
+  it("drives the write through handle.mutate keyed by maintenance id", async () => {
+    const calls: Array<{ id: string; next: MaintenanceEntityState }> = [];
+    const handle = {
+      kind: MAINTENANCE_ENTITY_KIND,
+      async mutate(input: {
+        id: string;
+        apply: () => Promise<MaintenanceEntityState>;
+      }) {
+        const next = await input.apply();
+        calls.push({ id: input.id, next });
+        return next;
+      },
+    } as unknown as EntityHandle<MaintenanceEntityState>;
+
+    let applied = false;
+    await writeMaintenanceEntity({
+      handle,
+      maintenanceId: "m-9",
+      apply: async () => {
+        applied = true;
+        return {
+          status: "in_progress",
+          systemIds: ["sys-1"],
+          startAt: "2026-05-29T11:00:00.000Z",
+          endAt: "2026-05-29T12:00:00.000Z",
+        };
+      },
+    });
+    expect(applied).toBe(true);
+    expect(calls).toEqual([
+      {
+        id: "m-9",
+        next: {
+          status: "in_progress",
+          systemIds: ["sys-1"],
+          startAt: "2026-05-29T11:00:00.000Z",
+          endAt: "2026-05-29T12:00:00.000Z",
+        },
+      },
+    ]);
+  });
+
+  it("still runs the plugin write when no handle is wired", async () => {
+    let applied = false;
+    await writeMaintenanceEntity({
+      handle: undefined,
+      maintenanceId: "m-9",
+      apply: async () => {
+        applied = true;
+        return {
+          status: "scheduled",
+          systemIds: [],
+          startAt: "a",
+          endAt: "b",
+        };
+      },
+    });
+    expect(applied).toBe(true);
+  });
+});
+
+describe("removeMaintenanceEntity", () => {
+  it("tombstones via handle.remove({ apply })", async () => {
+    const removed: string[] = [];
+    let deleted = false;
+    const handle = {
+      kind: MAINTENANCE_ENTITY_KIND,
+      async remove(input: { id: string; apply: () => Promise<void> }) {
+        await input.apply();
+        removed.push(input.id);
+      },
+    } as unknown as EntityHandle<MaintenanceEntityState>;
+    await removeMaintenanceEntity({
+      handle,
+      maintenanceId: "m-9",
+      apply: async () => {
+        deleted = true;
+      },
+    });
+    expect(deleted).toBe(true);
+    expect(removed).toEqual(["m-9"]);
+  });
+
+  it("still runs the delete when no handle is wired", async () => {
+    let deleted = false;
+    await removeMaintenanceEntity({
+      handle: undefined,
+      maintenanceId: "m-9",
+      apply: async () => {
+        deleted = true;
+      },
+    });
+    expect(deleted).toBe(true);
+  });
+});

package/src/entity.ts

@@ -0,0 +1,187 @@
+/**
+ * The reactive `maintenance` entity (reactive automation engine §10.2).
+ *
+ * Model B PLUGIN-BACKED entity: the `maintenances` + `maintenance_systems`
+ * tables are authoritative AND ARE the entity's current-state storage — there
+ * is NO framework `entity_state` row for a maintenance window.
+ * `defineEntity({ read })` makes that plugin state reactive: every
+ * reactive-state write goes through `handle.mutate`, whose `apply()` performs
+ * the REAL `maintenances`/junction write via the maintenance service (the
+ * plugin's own db/tx) and returns the resulting `{ status, systemIds, startAt,
+ * endAt }`. The framework snapshots `prev` via `read`, appends the transition
+ * log (its own db), and emits `ENTITY_CHANGED`. The change → trigger-event
+ * deriver reproduces `maintenance.created` / `.updated` so automations keep
+ * firing.
+ */
+import { z } from "zod";
+import {
+  MaintenanceStatusEnum,
+  type MaintenanceStatus,
+} from "@checkstack/maintenance-common";
+import type {
+  EntityChanged,
+  EntityChangePayloadMapper,
+  EntityHandle,
+  EntityMutationOpts,
+  EntityRead,
+} from "@checkstack/automation-backend";
+import {
+  withEntityRemove,
+  withEntityWrite,
+} from "@checkstack/automation-backend";
+
+import type { MaintenanceService } from "./service";
+
+/** Globally-unique entity kind for a maintenance window. */
+export const MAINTENANCE_ENTITY_KIND = "maintenance";
+
+/**
+ * Qualified trigger event ids the deriver maps to — `${pluginId}.${triggerId}`
+ * for the (now-removed) `created` / `updated` triggers. Automations reference
+ * these strings in `definition.triggers[].event`, so the deriver MUST return
+ * them verbatim for Stage-1 routing to match.
+ */
+export const MAINTENANCE_CREATED_EVENT = "maintenance.created";
+export const MAINTENANCE_UPDATED_EVENT = "maintenance.updated";
+
+/**
+ * Reactive state of a maintenance window (reactive automation engine §10.2).
+ * `startAt` / `endAt` are ISO strings (the `read` accessor serializes the
+ * service's `Date` columns; the `apply()` return uses {@link
+ * toMaintenanceEntityState} to do the same).
+ */
+export const maintenanceEntityStateSchema = z.object({
+  status: MaintenanceStatusEnum,
+  systemIds: z.array(z.string()),
+  startAt: z.string(),
+  endAt: z.string(),
+});
+
+export type MaintenanceEntityState = z.infer<
+  typeof maintenanceEntityStateSchema
+>;
+
+/**
+ * Project a freshly-written maintenance row onto the reactive `{ status,
+ * systemIds, startAt, endAt }` subset. Accepts either `Date` (service return
+ * shape) or already-ISO strings. This is the `apply()` return for
+ * `handle.mutate`.
+ */
+export function toMaintenanceEntityState(row: {
+  status: MaintenanceStatus;
+  systemIds: string[];
+  startAt: Date | string;
+  endAt: Date | string;
+}): MaintenanceEntityState {
+  return {
+    status: row.status,
+    systemIds: row.systemIds,
+    startAt:
+      row.startAt instanceof Date ? row.startAt.toISOString() : row.startAt,
+    endAt: row.endAt instanceof Date ? row.endAt.toISOString() : row.endAt,
+  };
+}
+
+/**
+ * Map a `maintenance` entity change to the qualified trigger event id(s) it
+ * should fire (reactive automation engine §7, Stage-1 routing):
+ *
+ *   - create (`prev === null`)            → `maintenance.created`
+ *   - update (a real diff, prev present)  → `maintenance.updated`
+ *   - remove (tombstone, `next === null`) → nothing (the old domain never
+ *     emitted a hook on delete)
+ *
+ * The deriver never sees no-op writes — the handle only emits a change event
+ * on a real diff — so a plain non-tombstone change is always a meaningful
+ * `created`/`updated`.
+ */
+export function deriveMaintenanceEvents(
+  changed: EntityChanged,
+): ReadonlyArray<string> {
+  if (changed.next === null) {
+    // Tombstone — delete fired no maintenance hook historically.
+    return [];
+  }
+  if (changed.prev === null) {
+    return [MAINTENANCE_CREATED_EVENT];
+  }
+  return [MAINTENANCE_UPDATED_EVENT];
+}
+
+/**
+ * Map a `maintenance` entity change to the domain-named `trigger.payload` the
+ * maintenance triggers declare via `payloadSchema` (`maintenanceId`, `status`,
+ * `systemIds`, `startAt`, `endAt`). Restores the keys operators read
+ * (`trigger.payload.maintenanceId`, `.status`, …) that the generic change shape
+ * omits, so an entity-driven maintenance trigger sees the same documented
+ * payload the four migrated lifecycle domains do.
+ *
+ * `maintenanceId` is the entity id; the remaining fields read off `next` (a
+ * tombstone fires no event, so `next` is always present when a trigger fires).
+ * The reactive subset is `{ status, systemIds, startAt, endAt }`, so the
+ * descriptive fields the old hook carried (`title`, `description`) are NOT
+ * derivable from a change and are declared OPTIONAL on the payload schemas.
+ */
+export const maintenanceChangeToPayload: EntityChangePayloadMapper = (
+  changed,
+) => {
+  const next = changed.next;
+  const systemIds = next === null ? undefined : next["systemIds"];
+  const readString = (field: string): unknown =>
+    next === null ? undefined : next[field];
+  return {
+    maintenanceId: changed.id,
+    status: readString("status"),
+    systemIds: Array.isArray(systemIds) ? systemIds : [],
+    startAt: readString("startAt"),
+    endAt: readString("endAt"),
+  };
+};
+
+/**
+ * Build the PLUGIN-BACKED `read` accessor for the `maintenance` entity. Routes
+ * straight to the service's batched authoritative read — no framework storage.
+ */
+export function createMaintenanceEntityRead(
+  service: MaintenanceService,
+): EntityRead<MaintenanceEntityState> {
+  return (ids) => service.getManyEntityStates(ids);
+}
+
+/**
+ * Drive a reactive-state maintenance write through `handle.mutate` (§10.2).
+ * `apply` performs the REAL `maintenances`/junction write via the service (the
+ * plugin's own db/tx) and returns the new reactive state. The framework
+ * snapshots `prev`, appends the transition log, and emits `ENTITY_CHANGED`
+ * (the deriver turns that into `maintenance.created/.updated`).
+ *
+ * When no handle is available (tests construct the router without one), the
+ * write still runs — the entity reactivity is layered on top, never required
+ * for the underlying write to succeed.
+ */
+export async function writeMaintenanceEntity(args: {
+  handle: EntityHandle<MaintenanceEntityState> | undefined;
+  maintenanceId: string;
+  opts?: EntityMutationOpts;
+  apply: () => Promise<MaintenanceEntityState>;
+}): Promise<void> {
+  const { handle, maintenanceId, opts, apply } = args;
+  await withEntityWrite({ handle, id: maintenanceId, opts, apply });
+}
+
+/**
+ * Drive a maintenance tombstone through `handle.remove` (§10.2). `apply`
+ * performs the REAL delete via the service; the framework records the
+ * tombstone transition and emits a tombstone change (the deriver fires
+ * nothing — the old domain never emitted a hook on delete). Without a handle,
+ * the delete still runs.
+ */
+export async function removeMaintenanceEntity(args: {
+  handle: EntityHandle<MaintenanceEntityState> | undefined;
+  maintenanceId: string;
+  opts?: EntityMutationOpts;
+  apply: () => Promise<void>;
+}): Promise<void> {
+  const { handle, maintenanceId, opts, apply } = args;
+  await withEntityRemove({ handle, id: maintenanceId, opts, apply });
+}

package/src/has-active-maintenance.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, mock } from "bun:test";
+import { MaintenanceService } from "./service";
+
+/**
+ * Mock db for hasActiveMaintenance. The method issues two select shapes
+ * in order:
+ *  1. .select({maintenanceId}).from(maintenanceSystems).where(...) -> ids
+ *  2. .select({id}).from(maintenances).where(...).limit(1)         -> match
+ * We disambiguate by call order.
+ */
+function createMockDb(opts: {
+  systemMaintenanceIds: string[];
+  activeMatch: boolean;
+}) {
+  let firstSelect = true;
+  return {
+    select: mock(() => {
+      if (firstSelect) {
+        firstSelect = false;
+        return {
+          from: mock(() => ({
+            where: mock(() =>
+              Promise.resolve(
+                opts.systemMaintenanceIds.map((maintenanceId) => ({
+                  maintenanceId,
+                })),
+              ),
+            ),
+          })),
+        };
+      }
+      return {
+        from: mock(() => ({
+          where: mock(() => ({
+            limit: mock(() =>
+              Promise.resolve(opts.activeMatch ? [{ id: "m-1" }] : []),
+            ),
+          })),
+        })),
+      };
+    }),
+  };
+}
+
+describe("MaintenanceService.hasActiveMaintenance", () => {
+  it("returns false when the system has no maintenance memberships", async () => {
+    const db = createMockDb({ systemMaintenanceIds: [], activeMatch: false });
+    const service = new MaintenanceService(db as never);
+    expect(await service.hasActiveMaintenance("system-1")).toBe(false);
+  });
+
+  it("returns true when an in_progress maintenance covers the system", async () => {
+    const db = createMockDb({
+      systemMaintenanceIds: ["m-1"],
+      activeMatch: true,
+    });
+    const service = new MaintenanceService(db as never);
+    expect(await service.hasActiveMaintenance("system-1")).toBe(true);
+  });
+
+  it("returns false when memberships exist but none are in_progress", async () => {
+    const db = createMockDb({
+      systemMaintenanceIds: ["m-1", "m-2"],
+      activeMatch: false,
+    });
+    const service = new MaintenanceService(db as never);
+    expect(await service.hasActiveMaintenance("system-1")).toBe(false);
+  });
+});