@checkstack/maintenance-backend 1.1.6 → 1.3.0

package/src/index.ts

@@ -1,6 +1,5 @@
 import * as schema from "./schema";
 import type { SafeDatabase } from "@checkstack/backend-api";
-import { z } from "zod";
 import {
   maintenanceAccessRules,
   maintenanceAccess,
@@ -13,7 +12,13 @@ import {
 } from "@checkstack/maintenance-common";
 
 import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
-import { integrationEventExtensionPoint } from "@checkstack/integration-backend";
+import {
+  automationActionExtensionPoint,
+  automationArtifactTypeExtensionPoint,
+  automationTriggerExtensionPoint,
+  entityExtensionPoint,
+  type EntityHandle,
+} from "@checkstack/automation-backend";
 import {
   NotificationApi,
   specToRegistration,
@@ -24,33 +29,20 @@ import { CatalogApi } from "@checkstack/catalog-common";
 import { AuthApi } from "@checkstack/auth-common";
 import { registerSearchProvider } from "@checkstack/command-backend";
 import { resolveRoute, type InferClient } from "@checkstack/common";
-import { maintenanceHooks } from "./hooks";
 import { createMaintenanceCache } from "./cache";
-
-// =============================================================================
-// Integration Event Payload Schemas
-// =============================================================================
-
-const maintenanceCreatedPayloadSchema = z.object({
-  maintenanceId: z.string(),
-  systemIds: z.array(z.string()),
-  title: z.string(),
-  description: z.string().optional(),
-  status: z.string(),
-  startAt: z.string(),
-  endAt: z.string(),
-});
-
-const maintenanceUpdatedPayloadSchema = z.object({
-  maintenanceId: z.string(),
-  systemIds: z.array(z.string()),
-  title: z.string(),
-  description: z.string().optional(),
-  status: z.string(),
-  startAt: z.string(),
-  endAt: z.string(),
-  action: z.enum(["updated", "closed"]),
-});
+import {
+  createMaintenanceActions,
+  maintenanceArtifactType,
+  maintenanceTriggers,
+} from "./automations";
+import {
+  MAINTENANCE_ENTITY_KIND,
+  createMaintenanceEntityRead,
+  deriveMaintenanceEvents,
+  maintenanceChangeToPayload,
+  maintenanceEntityStateSchema,
+  type MaintenanceEntityState,
+} from "./entity";
 
 // Queue and job constants
 const STATUS_TRANSITION_QUEUE = "maintenance-status-transitions";
@@ -70,32 +62,62 @@ export default createBackendPlugin({
       maintenanceGroupSubscription,
     ]);
 
-    // Register hooks as integration events
-    const integrationEvents = env.getExtensionPoint(
-      integrationEventExtensionPoint,
-    );
+    // ─── Automation Platform: entity + artifact type ───────────────────
+    // Buffered behind the extension point until automation-backend's
+    // register() runs. Actions are wired in afterPluginsReady so the entity
+    // handle is available on the service — see below.
+    //
+    // Reactive entity (reactive automation engine §10.2): the
+    // `maintenance.created` / `maintenance.updated` trigger events are now
+    // DERIVED from `maintenance` entity changes. The triggers stay registered
+    // (ENTITY-DRIVEN, no hook) so they remain in the editor's trigger catalog +
+    // payload-introspectable; a `toPayload` mapper makes the runtime
+    // `trigger.payload` match their `payloadSchema` (mirroring incident /
+    // catalog / dependency / healthcheck).
+    //
+    // PLUGIN-BACKED (Model B): the `maintenances` + `maintenance_systems`
+    // tables ARE the current-state storage. `read` routes straight to the
+    // service's batched authoritative read — no framework `entity_state` row,
+    // so no `indexes` (those only apply to store-backed kinds). The `read`
+    // closure resolves the service set by init() (mutations only happen from
+    // init onward).
+    const entity = env.getExtensionPoint(entityExtensionPoint);
 
-    integrationEvents.registerEvent(
-      {
-        hook: maintenanceHooks.maintenanceCreated,
-        displayName: "Maintenance Created",
-        description: "Fired when a new maintenance is scheduled",
-        category: "Maintenance",
-        payloadSchema: maintenanceCreatedPayloadSchema,
-      },
-      pluginMetadata,
-    );
+    // The maintenance service is created in init() (it needs the resolved
+    // database), but the PLUGIN-BACKED entity `read` accessor must be supplied
+    // at `defineEntity` time in register(). This holder bridges the two: the
+    // `read` closure resolves the service lazily, and init() sets it before
+    // any mutation runs (the registry only mutates from init() onward).
+    let maintenanceServiceRef: MaintenanceService | undefined;
 
-    integrationEvents.registerEvent(
-      {
-        hook: maintenanceHooks.maintenanceUpdated,
-        displayName: "Maintenance Updated",
-        description: "Fired when a maintenance is updated or closed",
-        category: "Maintenance",
-        payloadSchema: maintenanceUpdatedPayloadSchema,
-      },
-      pluginMetadata,
+    const maintenanceEntityHandle: EntityHandle<MaintenanceEntityState> =
+      entity.defineEntity<MaintenanceEntityState>({
+        kind: MAINTENANCE_ENTITY_KIND,
+        state: maintenanceEntityStateSchema,
+        read: (ids) => {
+          const svc = maintenanceServiceRef;
+          if (!svc) {
+            throw new Error(
+              "maintenance entity read before init: service not yet resolved",
+            );
+          }
+          return createMaintenanceEntityRead(svc)(ids);
+        },
+      });
+    entity.registerChangeDeriver({
+      kind: MAINTENANCE_ENTITY_KIND,
+      derive: deriveMaintenanceEvents,
+      toPayload: maintenanceChangeToPayload,
+    });
+    const automationTriggers = env.getExtensionPoint(
+      automationTriggerExtensionPoint,
     );
+    for (const trigger of maintenanceTriggers) {
+      automationTriggers.registerTrigger(trigger, pluginMetadata);
+    }
+    env
+      .getExtensionPoint(automationArtifactTypeExtensionPoint)
+      .registerArtifactType(maintenanceArtifactType, pluginMetadata);
 
     // Store service reference for afterPluginsReady
     let maintenanceService: MaintenanceService;
@@ -132,6 +154,9 @@ export default createBackendPlugin({
         maintenanceService = new MaintenanceService(
           database as SafeDatabase<typeof schema>,
         );
+        // Publish the service for the PLUGIN-BACKED entity `read` accessor
+        // (defined in register()). Mutations only run from here onward.
+        maintenanceServiceRef = maintenanceService;
         const cache = createMaintenanceCache({ cacheManager, logger });
         const router = createRouter(
           maintenanceService,
@@ -141,6 +166,7 @@ export default createBackendPlugin({
           authClient,
           logger,
           cache,
+          maintenanceEntityHandle,
         );
         rpc.registerRouter(router, maintenanceContract);
 
@@ -173,6 +199,19 @@ export default createBackendPlugin({
         logger.debug("✅ Maintenance Backend initialized.");
       },
       afterPluginsReady: async ({ queueManager, logger }) => {
+        // Register automation actions. Mutation actions mirror window state
+        // through the `maintenance` entity handle (created in init) rather
+        // than emitting the removed hooks.
+        const automationActions = env.getExtensionPoint(
+          automationActionExtensionPoint,
+        );
+        for (const action of createMaintenanceActions({
+          service: maintenanceService,
+          entityHandle: maintenanceEntityHandle,
+        })) {
+          automationActions.registerAction(action, pluginMetadata);
+        }
+
         // Notification subscription specs. Per-resource group lifecycle
         // is platform-managed by notification-backend — maintenance just
         // declares the specs.
@@ -264,6 +303,3 @@ export default createBackendPlugin({
     });
   },
 });
-
-// Re-export hooks for other plugins to use
-export { maintenanceHooks } from "./hooks";

package/src/router.ts

@@ -7,17 +7,24 @@ import {
   autoAuthMiddleware,
   correlationMiddleware,
   Logger,
+  resolveActor,
   type RpcContext,
 } from "@checkstack/backend-api";
+import type { EntityHandle } from "@checkstack/automation-backend";
 import type { SignalService } from "@checkstack/signal-common";
 import type { MaintenanceService } from "./service";
 import { CatalogApi } from "@checkstack/catalog-common";
 import { AuthApi } from "@checkstack/auth-common";
 import type { InferClient } from "@checkstack/common";
-import { maintenanceHooks } from "./hooks";
 import { notifyAffectedSystems } from "./notifications";
 import type { MaintenanceUpdate } from "@checkstack/maintenance-common";
 import type { MaintenanceCache } from "./cache";
+import {
+  removeMaintenanceEntity,
+  toMaintenanceEntityState,
+  writeMaintenanceEntity,
+  type MaintenanceEntityState,
+} from "./entity";
 
 export function createRouter(
   service: MaintenanceService,
@@ -29,6 +36,15 @@ export function createRouter(
   authClient: InferClient<typeof AuthApi>,
   logger: Logger,
   cache: MaintenanceCache,
+  /**
+   * Reactive `maintenance` entity handle (reactive automation engine §10.2).
+   * PLUGIN-BACKED (Model B): the `maintenances` + `maintenance_systems` tables
+   * ARE the current-state storage. Mutation sites drive the REAL write through
+   * `handle.mutate` / `handle.remove` (the write runs inside `apply`); the
+   * change-deriver re-emits the `maintenance.created` / `maintenance.updated`
+   * trigger events that automations match.
+   */
+  entityHandle: EntityHandle<MaintenanceEntityState>,
 ) {
   /**
    * Resolve user IDs to profile names for a list of updates.
@@ -144,7 +160,23 @@ export function createRouter(
 
     createMaintenance: os.createMaintenance.handler(
       async ({ input, context }) => {
-        const result = await service.createMaintenance(input);
+        // Drive the create through the reactive `maintenance` entity (§10.2):
+        // `apply` performs the REAL `maintenances`/junction write (the plugin's
+        // own db/tx) and returns the new reactive state; the deriver fires
+        // `maintenance.created` from the resulting change. The id is generated
+        // up front so the handle is keyed on it and the create's `prev`
+        // snapshot correctly reads the not-yet-existing row as absent.
+        const maintenanceId = crypto.randomUUID();
+        let result!: Awaited<ReturnType<typeof service.createMaintenance>>;
+        await writeMaintenanceEntity({
+          handle: entityHandle,
+          maintenanceId,
+          opts: { actor: resolveActor(context.user) },
+          apply: async () => {
+            result = await service.createMaintenance(input, maintenanceId);
+            return toMaintenanceEntityState(result);
+          },
+        });
 
         // Invalidate before signal so any frontend that refetches in
         // response sees fresh data. Mutation invariant in this file:
@@ -161,17 +193,6 @@ export function createRouter(
           action: "created",
         });
 
-        // Emit hook for cross-plugin coordination and integrations
-        await context.emitHook(maintenanceHooks.maintenanceCreated, {
-          maintenanceId: result.id,
-          systemIds: result.systemIds,
-          title: result.title,
-          description: result.description,
-          status: result.status,
-          startAt: result.startAt.toISOString(),
-          endAt: result.endAt.toISOString(),
-        });
-
         // Send notifications to system subscribers
         const systemNames = await resolveSystemNames(result.systemIds);
         await notifyAffectedSystems({
@@ -191,13 +212,38 @@ export function createRouter(
 
     updateMaintenance: os.updateMaintenance.handler(
       async ({ input, context }) => {
-        const result = await service.updateMaintenance(input);
-        if (!result) {
+        // Probe existence first so a missing maintenance still surfaces as
+        // NOT_FOUND without driving an entity write.
+        const exists = await service.getMaintenance(input.id);
+        if (!exists) {
           throw new ORPCError("NOT_FOUND", {
             message: "Maintenance not found",
           });
         }
 
+        // Drive the update through the reactive `maintenance` entity (§10.2);
+        // `apply` performs the REAL update (the plugin's own db/tx) and returns
+        // the new reactive state. The deriver fires `maintenance.updated` from
+        // the resulting change.
+        let result!: NonNullable<
+          Awaited<ReturnType<typeof service.updateMaintenance>>
+        >;
+        await writeMaintenanceEntity({
+          handle: entityHandle,
+          maintenanceId: input.id,
+          opts: { actor: resolveActor(context.user) },
+          apply: async () => {
+            const updated = await service.updateMaintenance(input);
+            if (!updated) {
+              throw new ORPCError("NOT_FOUND", {
+                message: "Maintenance not found",
+              });
+            }
+            result = updated;
+            return toMaintenanceEntityState(result);
+          },
+        });
+
         await cache.invalidateForMutation({
           maintenanceId: result.id,
           systemIds: result.systemIds,
@@ -210,18 +256,6 @@ export function createRouter(
           action: "updated",
         });
 
-        // Emit hook for cross-plugin coordination and integrations
-        await context.emitHook(maintenanceHooks.maintenanceUpdated, {
-          maintenanceId: result.id,
-          systemIds: result.systemIds,
-          title: result.title,
-          description: result.description,
-          status: result.status,
-          startAt: result.startAt.toISOString(),
-          endAt: result.endAt.toISOString(),
-          action: "updated",
-        });
-
         return result;
       },
     ),
@@ -236,10 +270,31 @@ export function createRouter(
         : undefined;
       const previousStatus = previousMaintenance?.status;
 
-      const result = await service.addUpdate(input, userId);
-      // Read post-write state directly from the service so the broadcast
-      // payload is fresh; the cache is invalidated below before the signal.
-      const maintenance = await service.getMaintenance(input.maintenanceId);
+      // Drive the update through the reactive `maintenance` entity (§10.2).
+      // `apply` posts the update row + (optionally) flips status in the
+      // plugin's own db/tx, then re-reads the post-write reactive state. The
+      // deriver fires `maintenance.updated` purely from the entity diff; when
+      // the status/window is unchanged, the diff is empty and no event fires.
+      let result!: Awaited<ReturnType<typeof service.addUpdate>>;
+      let maintenance: Awaited<ReturnType<typeof service.getMaintenance>>;
+      await writeMaintenanceEntity({
+        handle: entityHandle,
+        maintenanceId: input.maintenanceId,
+        opts: { actor: resolveActor(context.user) },
+        apply: async () => {
+          result = await service.addUpdate(input, userId);
+          maintenance = await service.getMaintenance(input.maintenanceId);
+          // The maintenance must exist (the update FK-references it); guard for
+          // the type and to fail loudly if it vanished mid-write.
+          if (!maintenance) {
+            throw new ORPCError("NOT_FOUND", {
+              message: "Maintenance not found",
+            });
+          }
+          return toMaintenanceEntityState(maintenance);
+        },
+      });
+
       if (maintenance) {
         await cache.invalidateForMutation({
           maintenanceId: input.maintenanceId,
@@ -256,18 +311,6 @@ export function createRouter(
           action,
         });
 
-        // Emit hook for cross-plugin coordination and integrations
-        await context.emitHook(maintenanceHooks.maintenanceUpdated, {
-          maintenanceId: input.maintenanceId,
-          systemIds: maintenance.systemIds,
-          title: maintenance.title,
-          description: maintenance.description,
-          status: maintenance.status,
-          startAt: maintenance.startAt.toISOString(),
-          endAt: maintenance.endAt.toISOString(),
-          action,
-        });
-
         // Send notifications when status actually changes
         if (input.statusChange && previousStatus !== input.statusChange) {
           // Determine notification action based on the actual status transition
@@ -303,16 +346,43 @@ export function createRouter(
       async ({ input, context }) => {
         const userId =
           context.user && "id" in context.user ? context.user.id : undefined;
-        const result = await service.closeMaintenance(
-          input.id,
-          input.message,
-          userId,
-        );
-        if (!result) {
+
+        // Probe existence first so a missing maintenance still surfaces as
+        // NOT_FOUND without driving an entity write.
+        const exists = await service.getMaintenance(input.id);
+        if (!exists) {
           throw new ORPCError("NOT_FOUND", {
             message: "Maintenance not found",
           });
         }
+
+        // Drive the close through the reactive `maintenance` entity (§10.2);
+        // `apply` performs the REAL close (status → completed, the plugin's own
+        // db/tx) and returns the new reactive state. The deriver fires
+        // `maintenance.updated` from the status transition.
+        let result!: NonNullable<
+          Awaited<ReturnType<typeof service.closeMaintenance>>
+        >;
+        await writeMaintenanceEntity({
+          handle: entityHandle,
+          maintenanceId: input.id,
+          opts: { actor: resolveActor(context.user) },
+          apply: async () => {
+            const closed = await service.closeMaintenance(
+              input.id,
+              input.message,
+              userId,
+            );
+            if (!closed) {
+              throw new ORPCError("NOT_FOUND", {
+                message: "Maintenance not found",
+              });
+            }
+            result = closed;
+            return toMaintenanceEntityState(result);
+          },
+        });
+
         await cache.invalidateForMutation({
           maintenanceId: result.id,
           systemIds: result.systemIds,
@@ -324,18 +394,6 @@ export function createRouter(
           action: "closed",
         });
 
-        // Emit hook for cross-plugin coordination and integrations
-        await context.emitHook(maintenanceHooks.maintenanceUpdated, {
-          maintenanceId: result.id,
-          systemIds: result.systemIds,
-          title: result.title,
-          description: result.description,
-          status: result.status,
-          startAt: result.startAt.toISOString(),
-          endAt: result.endAt.toISOString(),
-          action: "closed",
-        });
-
         // Send notifications to system subscribers
         const systemNames = await resolveSystemNames(result.systemIds);
         await notifyAffectedSystems({
@@ -353,10 +411,25 @@ export function createRouter(
       },
     ),
 
-    deleteMaintenance: os.deleteMaintenance.handler(async ({ input }) => {
+    deleteMaintenance: os.deleteMaintenance.handler(async ({ input, context }) => {
       // Get maintenance before deleting to get systemIds
       const maintenance = await service.getMaintenance(input.id);
-      const success = await service.deleteMaintenance(input.id);
+
+      // Drive the delete through the reactive `maintenance` entity tombstone
+      // (§10.2). `apply` performs the REAL delete (the plugin's own db/tx);
+      // the framework records the tombstone transition and emits a tombstone
+      // change. The deriver fires nothing, matching the historical behaviour
+      // where delete emitted no maintenance hook.
+      let success = false;
+      await removeMaintenanceEntity({
+        handle: entityHandle,
+        maintenanceId: input.id,
+        opts: { actor: resolveActor(context.user) },
+        apply: async () => {
+          success = await service.deleteMaintenance(input.id);
+        },
+      });
+
       if (success && maintenance) {
         await cache.invalidateForMutation({
           maintenanceId: input.id,
@@ -380,6 +453,11 @@ export function createRouter(
         return { suppressed };
       }),
 
+    hasActiveMaintenance: os.hasActiveMaintenance.handler(async ({ input }) => {
+      const active = await service.hasActiveMaintenance(input.systemId);
+      return { active };
+    }),
+
     addLink: os.addLink.handler(async ({ input }) => {
       const maintenance = await service.getMaintenance(input.maintenanceId);
       if (!maintenance) {

package/src/service.ts

@@ -174,13 +174,89 @@ export class MaintenanceService {
   }
 
   /**
-   * Create a new maintenance
+   * Batched reactive-state read for the `maintenance` entity (Model B
+   * plugin-backed `read` accessor). Given maintenance ids, return the
+   * reactive subset `{ status, systemIds, startAt, endAt }` for each that
+   * exists (missing ids omitted). Reads the AUTHORITATIVE `maintenances` +
+   * `maintenance_systems` tables — no framework `entity_state` storage. This
+   * is the single source of truth `handle.mutate` snapshots `prev` from and
+   * `get`/`getMany`/scope enrichment route through. `startAt`/`endAt` are
+   * serialized to ISO strings to match the entity state schema.
+   */
+  async getManyEntityStates(
+    ids: ReadonlyArray<string>,
+  ): Promise<
+    Record<
+      string,
+      {
+        status: MaintenanceStatus;
+        systemIds: string[];
+        startAt: string;
+        endAt: string;
+      }
+    >
+  > {
+    if (ids.length === 0) return {};
+
+    const rows = await this.db
+      .select({
+        id: maintenances.id,
+        status: maintenances.status,
+        startAt: maintenances.startAt,
+        endAt: maintenances.endAt,
+      })
+      .from(maintenances)
+      .where(inArray(maintenances.id, [...ids]));
+    if (rows.length === 0) return {};
+
+    const presentIds = rows.map((r) => r.id);
+    const systemRows = await this.db
+      .select({
+        maintenanceId: maintenanceSystems.maintenanceId,
+        systemId: maintenanceSystems.systemId,
+      })
+      .from(maintenanceSystems)
+      .where(inArray(maintenanceSystems.maintenanceId, presentIds));
+
+    const systemsByMaintenance = new Map<string, string[]>();
+    for (const r of systemRows) {
+      const list = systemsByMaintenance.get(r.maintenanceId);
+      if (list) list.push(r.systemId);
+      else systemsByMaintenance.set(r.maintenanceId, [r.systemId]);
+    }
+
+    const out: Record<
+      string,
+      {
+        status: MaintenanceStatus;
+        systemIds: string[];
+        startAt: string;
+        endAt: string;
+      }
+    > = {};
+    for (const row of rows) {
+      out[row.id] = {
+        status: row.status,
+        systemIds: systemsByMaintenance.get(row.id) ?? [],
+        startAt: row.startAt.toISOString(),
+        endAt: row.endAt.toISOString(),
+      };
+    }
+    return out;
+  }
+
+  /**
+   * Create a new maintenance.
+   *
+   * `id` may be supplied by the caller so the reactive `maintenance` entity
+   * can be keyed on a known id BEFORE the insert runs (the create's `prev`
+   * snapshot must read the not-yet-existing row as absent — see §10.2). When
+   * omitted, a fresh id is generated. The id is server-owned either way.
    */
   async createMaintenance(
     input: CreateMaintenanceInput,
+    id: string = generateId(),
   ): Promise<MaintenanceWithSystems> {
-    const id = generateId();
-
     await this.db.insert(maintenances).values({
       id,
       title: input.title,
@@ -409,6 +485,39 @@ export class MaintenanceService {
     return !!match;
   }
 
+  /**
+   * Check if a system currently has an active maintenance window,
+   * regardless of whether notification suppression is enabled. A
+   * maintenance is "active" when its status is "in_progress".
+   *
+   * Unlike {@link hasActiveMaintenanceWithSuppression}, this is
+   * suppression-agnostic: it answers "is this system in a maintenance
+   * window right now?" so automations can gate on maintenance state
+   * without being coupled to the notification-suppression flag.
+   */
+  async hasActiveMaintenance(systemId: string): Promise<boolean> {
+    const systemMaintenances = await this.db
+      .select({ maintenanceId: maintenanceSystems.maintenanceId })
+      .from(maintenanceSystems)
+      .where(eq(maintenanceSystems.systemId, systemId));
+
+    const ids = systemMaintenances.map((r) => r.maintenanceId);
+    if (ids.length === 0) return false;
+
+    const [match] = await this.db
+      .select({ id: maintenances.id })
+      .from(maintenances)
+      .where(
+        and(
+          inArray(maintenances.id, ids),
+          eq(maintenances.status, "in_progress"),
+        ),
+      )
+      .limit(1);
+
+    return !!match;
+  }
+
   /**
    * Get maintenances that should transition from 'scheduled' to 'in_progress'.
    * These are maintenances where status = 'scheduled' AND startAt <= now.

package/tsconfig.json

@@ -7,6 +7,12 @@
     {
       "path": "../auth-common"
     },
+    {
+      "path": "../automation-backend"
+    },
+    {
+      "path": "../automation-common"
+    },
     {
       "path": "../backend-api"
     },
@@ -31,12 +37,6 @@
     {
       "path": "../drizzle-helper"
     },
-    {
-      "path": "../integration-backend"
-    },
-    {
-      "path": "../integration-common"
-    },
     {
       "path": "../maintenance-common"
     },