@checkstack/maintenance-backend 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @checkstack/maintenance-backend
 
+## 0.5.0
+
+### Minor Changes
+
+- 2c0822d: ### Queue System
+
+  - Added cron pattern support to `scheduleRecurring()` - accepts either `intervalSeconds` or `cronPattern`
+  - BullMQ backend uses native cron scheduling via `pattern` option
+  - InMemoryQueue implements wall-clock cron scheduling with `cron-parser`
+
+  ### Maintenance Backend
+
+  - Auto status transitions now use cron pattern `* * * * *` for precise second-0 scheduling
+  - User notifications are now sent for auto-started and auto-completed maintenances
+  - Refactored to call `addUpdate` RPC for status changes, centralizing hook/signal/notification logic
+
+  ### UI
+
+  - DateTimePicker now resets seconds and milliseconds to 0 when time is changed
+
+### Patch Changes
+
+- 66a3963: Update database types to use SafeDatabase
+
+  - Updated all database type declarations from `NodePgDatabase` to `SafeDatabase` for compile-time safety
+
+- Updated dependencies [66a3963]
+- Updated dependencies [66a3963]
+  - @checkstack/integration-backend@0.1.6
+  - @checkstack/backend-api@0.5.0
+  - @checkstack/command-backend@0.1.6
+
+## 0.4.0
+
+### Minor Changes
+
+- 65aa47e: Add automatic maintenance status transitions
+
+  Maintenances now automatically transition from `scheduled` to `in_progress` when their `startAt` time is reached, and from `in_progress` to `completed` when their `endAt` time is reached. A recurring queue job runs every minute to check and transition statuses. Integration hooks and real-time signals are emitted upon each transition.
+
+### Patch Changes
+
+- Updated dependencies [8a87cd4]
+- Updated dependencies [8a87cd4]
+- Updated dependencies [8a87cd4]
+- Updated dependencies [8a87cd4]
+  - @checkstack/backend-api@0.4.1
+  - @checkstack/catalog-common@1.2.3
+  - @checkstack/common@0.5.0
+  - @checkstack/maintenance-common@0.4.1
+  - @checkstack/command-backend@0.1.5
+  - @checkstack/integration-backend@0.1.5
+  - @checkstack/integration-common@0.2.2
+  - @checkstack/notification-common@0.2.2
+  - @checkstack/signal-common@0.1.3
+
 ## 0.3.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/maintenance-backend",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {

package/src/index.ts

@@ -1,5 +1,5 @@
 import * as schema from "./schema";
-import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { SafeDatabase } from "@checkstack/backend-api";
 import { z } from "zod";
 import {
   maintenanceAccessRules,
@@ -7,14 +7,16 @@ import {
   pluginMetadata,
   maintenanceContract,
   maintenanceRoutes,
+  MaintenanceApi,
 } from "@checkstack/maintenance-common";
+
 import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
 import { integrationEventExtensionPoint } from "@checkstack/integration-backend";
 import { MaintenanceService } from "./service";
 import { createRouter } from "./router";
 import { CatalogApi } from "@checkstack/catalog-common";
 import { registerSearchProvider } from "@checkstack/command-backend";
-import { resolveRoute } from "@checkstack/common";
+import { resolveRoute, type InferClient } from "@checkstack/common";
 import { maintenanceHooks } from "./hooks";
 
 // =============================================================================
@@ -42,6 +44,11 @@ const maintenanceUpdatedPayloadSchema = z.object({
   action: z.enum(["updated", "closed"]),
 });
 
+// Queue and job constants
+const STATUS_TRANSITION_QUEUE = "maintenance-status-transitions";
+const STATUS_TRANSITION_JOB_ID = "maintenance-status-transition-check";
+const WORKER_GROUP = "maintenance-status-worker";
+
 // =============================================================================
 // Plugin Definition
 // =============================================================================
@@ -53,7 +60,7 @@ export default createBackendPlugin({
 
     // Register hooks as integration events
     const integrationEvents = env.getExtensionPoint(
-      integrationEventExtensionPoint
+      integrationEventExtensionPoint,
     );
 
     integrationEvents.registerEvent(
@@ -64,7 +71,7 @@ export default createBackendPlugin({
         category: "Maintenance",
         payloadSchema: maintenanceCreatedPayloadSchema,
       },
-      pluginMetadata
+      pluginMetadata,
     );
 
     integrationEvents.registerEvent(
@@ -75,9 +82,15 @@ export default createBackendPlugin({
         category: "Maintenance",
         payloadSchema: maintenanceUpdatedPayloadSchema,
       },
-      pluginMetadata
+      pluginMetadata,
     );
 
+    // Store service reference for afterPluginsReady
+    let maintenanceService: MaintenanceService;
+    // Store clients for afterPluginsReady
+    let catalogClient: InferClient<typeof CatalogApi>;
+    let maintenanceClient: InferClient<typeof MaintenanceApi>;
+
     env.registerInit({
       schema,
       deps: {
@@ -85,20 +98,22 @@ export default createBackendPlugin({
         rpc: coreServices.rpc,
         rpcClient: coreServices.rpcClient,
         signalService: coreServices.signalService,
+        queueManager: coreServices.queueManager,
       },
       init: async ({ logger, database, rpc, rpcClient, signalService }) => {
         logger.debug("🔧 Initializing Maintenance Backend...");
 
-        const catalogClient = rpcClient.forPlugin(CatalogApi);
+        catalogClient = rpcClient.forPlugin(CatalogApi);
+        maintenanceClient = rpcClient.forPlugin(MaintenanceApi);
 
-        const service = new MaintenanceService(
-          database as NodePgDatabase<typeof schema>
+        maintenanceService = new MaintenanceService(
+          database as SafeDatabase<typeof schema>,
         );
         const router = createRouter(
-          service,
+          maintenanceService,
           signalService,
           catalogClient,
-          logger
+          logger,
         );
         rpc.registerRouter(router, maintenanceContract);
 
@@ -130,6 +145,83 @@ export default createBackendPlugin({
 
         logger.debug("✅ Maintenance Backend initialized.");
       },
+      afterPluginsReady: async ({ queueManager, logger }) => {
+        // Schedule the recurring status transition check job
+        const queue = queueManager.getQueue<Record<string, never>>(
+          STATUS_TRANSITION_QUEUE,
+        );
+
+        // Subscribe to process status transition check jobs
+        await queue.consume(
+          async () => {
+            logger.debug("⏰ Checking maintenance status transitions...");
+
+            // Get maintenances that need to start
+            const toStart = await maintenanceService.getMaintenancesToStart();
+            for (const maintenance of toStart) {
+              try {
+                // Call addUpdate via RPC - this handles hooks, signals, and notifications
+                await maintenanceClient.addUpdate({
+                  maintenanceId: maintenance.id,
+                  message: "Maintenance started automatically",
+                  statusChange: "in_progress",
+                });
+                logger.info(
+                  `Maintenance "${maintenance.title}" transitioned to in_progress`,
+                );
+              } catch (error) {
+                logger.error(
+                  `Failed to transition maintenance ${maintenance.id}:`,
+                  error,
+                );
+              }
+            }
+
+            // Get maintenances that need to complete
+            const toComplete =
+              await maintenanceService.getMaintenancesToComplete();
+            for (const maintenance of toComplete) {
+              try {
+                // Call addUpdate via RPC - this handles hooks, signals, and notifications
+                await maintenanceClient.addUpdate({
+                  maintenanceId: maintenance.id,
+                  message: "Maintenance completed automatically",
+                  statusChange: "completed",
+                });
+                logger.info(
+                  `Maintenance "${maintenance.title}" transitioned to completed`,
+                );
+              } catch (error) {
+                logger.error(
+                  `Failed to transition maintenance ${maintenance.id}:`,
+                  error,
+                );
+              }
+            }
+
+            if (toStart.length > 0 || toComplete.length > 0) {
+              logger.debug(
+                `Status transitions: ${toStart.length} started, ${toComplete.length} completed`,
+              );
+            }
+          },
+          {
+            consumerGroup: WORKER_GROUP,
+            maxRetries: 0, // Status checks should not retry
+          },
+        );
+
+        // Schedule to run every minute at second 0 (cron-based for precise timing)
+        await queue.scheduleRecurring(
+          {}, // Empty payload - the job just triggers a check
+          {
+            jobId: STATUS_TRANSITION_JOB_ID,
+            cronPattern: "* * * * *", // Every minute at :00 seconds
+          },
+        );
+
+        logger.debug("✅ Maintenance status transition job scheduled.");
+      },
     });
   },
 });

package/src/notifications.ts

@@ -0,0 +1,58 @@
+import { CatalogApi } from "@checkstack/catalog-common";
+import type { Logger } from "@checkstack/backend-api";
+import type { InferClient } from "@checkstack/common";
+import { resolveRoute } from "@checkstack/common";
+import { maintenanceRoutes } from "@checkstack/maintenance-common";
+
+/**
+ * Helper to notify subscribers of affected systems about a maintenance event.
+ * Each system triggers a separate notification call, but within each call
+ * the subscribers are deduplicated (system + its groups).
+ */
+export async function notifyAffectedSystems(props: {
+  catalogClient: InferClient<typeof CatalogApi>;
+  logger: Logger;
+  maintenanceId: string;
+  maintenanceTitle: string;
+  systemIds: string[];
+  action: "created" | "updated" | "started" | "completed";
+}): Promise<void> {
+  const {
+    catalogClient,
+    logger,
+    maintenanceId,
+    maintenanceTitle,
+    systemIds,
+    action,
+  } = props;
+
+  const actionText = {
+    created: "scheduled",
+    updated: "updated",
+    started: "started",
+    completed: "completed",
+  }[action];
+
+  const maintenanceDetailPath = resolveRoute(maintenanceRoutes.routes.detail, {
+    maintenanceId,
+  });
+
+  for (const systemId of systemIds) {
+    try {
+      await catalogClient.notifySystemSubscribers({
+        systemId,
+        title: `Maintenance ${actionText}`,
+        body: `A maintenance **"${maintenanceTitle}"** has been ${actionText} for a system you're subscribed to.`,
+        importance: "info",
+        action: { label: "View Maintenance", url: maintenanceDetailPath },
+        includeGroupSubscribers: true,
+      });
+    } catch (error) {
+      // Log but don't fail the operation - notifications are best-effort
+      logger.warn(
+        `Failed to notify subscribers for system ${systemId}:`,
+        error,
+      );
+    }
+  }
+}

package/src/router.ts

@@ -2,7 +2,6 @@ import { implement, ORPCError } from "@orpc/server";
 import {
   maintenanceContract,
   MAINTENANCE_UPDATED,
-  maintenanceRoutes,
 } from "@checkstack/maintenance-common";
 import {
   autoAuthMiddleware,
@@ -13,8 +12,8 @@ import type { SignalService } from "@checkstack/signal-common";
 import type { MaintenanceService } from "./service";
 import { CatalogApi } from "@checkstack/catalog-common";
 import type { InferClient } from "@checkstack/common";
-import { resolveRoute } from "@checkstack/common";
 import { maintenanceHooks } from "./hooks";
+import { notifyAffectedSystems } from "./notifications";
 
 export function createRouter(
   service: MaintenanceService,
@@ -26,47 +25,6 @@ export function createRouter(
     .$context<RpcContext>()
     .use(autoAuthMiddleware);
 
-  /**
-   * Helper to notify subscribers of affected systems about a maintenance event.
-   * Each system triggers a separate notification call, but within each call
-   * the subscribers are deduplicated (system + its groups).
-   */
-  const notifyAffectedSystems = async (props: {
-    maintenanceId: string;
-    maintenanceTitle: string;
-    systemIds: string[];
-    action: "created" | "updated";
-  }) => {
-    const { maintenanceId, maintenanceTitle, systemIds, action } = props;
-
-    const actionText = action === "created" ? "scheduled" : "updated";
-    const maintenanceDetailPath = resolveRoute(
-      maintenanceRoutes.routes.detail,
-      {
-        maintenanceId,
-      },
-    );
-
-    for (const systemId of systemIds) {
-      try {
-        await catalogClient.notifySystemSubscribers({
-          systemId,
-          title: `Maintenance ${actionText}`,
-          body: `A maintenance **"${maintenanceTitle}"** has been ${actionText} for a system you're subscribed to.`,
-          importance: "info",
-          action: { label: "View Maintenance", url: maintenanceDetailPath },
-          includeGroupSubscribers: true,
-        });
-      } catch (error) {
-        // Log but don't fail the operation - notifications are best-effort
-        logger.warn(
-          `Failed to notify subscribers for system ${systemId}:`,
-          error,
-        );
-      }
-    }
-  };
-
   return os.router({
     listMaintenances: os.listMaintenances.handler(async ({ input }) => {
       return { maintenances: await service.listMaintenances(input ?? {}) };
@@ -127,6 +85,8 @@ export function createRouter(
 
         // Send notifications to system subscribers
         await notifyAffectedSystems({
+          catalogClient,
+          logger,
           maintenanceId: result.id,
           maintenanceTitle: result.title,
           systemIds: result.systemIds,
@@ -165,14 +125,6 @@ export function createRouter(
           action: "updated",
         });
 
-        // Send notifications to system subscribers
-        await notifyAffectedSystems({
-          maintenanceId: result.id,
-          maintenanceTitle: result.title,
-          systemIds: result.systemIds,
-          action: "updated",
-        });
-
         return result;
       },
     ),
@@ -180,14 +132,25 @@ export function createRouter(
     addUpdate: os.addUpdate.handler(async ({ input, context }) => {
       const userId =
         context.user && "id" in context.user ? context.user.id : undefined;
+
+      // Get previous status before update for comparison
+      const previousMaintenance = input.statusChange
+        ? await service.getMaintenance(input.maintenanceId)
+        : undefined;
+      const previousStatus = previousMaintenance?.status;
+
       const result = await service.addUpdate(input, userId);
       // Get maintenance to broadcast with correct systemIds
       const maintenance = await service.getMaintenance(input.maintenanceId);
       if (maintenance) {
+        // Determine action based on status change
+        const action =
+          input.statusChange === "completed" ? "closed" : "updated";
+
         await signalService.broadcast(MAINTENANCE_UPDATED, {
           maintenanceId: input.maintenanceId,
           systemIds: maintenance.systemIds,
-          action: "updated",
+          action,
         });
 
         // Emit hook for cross-plugin coordination and integrations
@@ -199,8 +162,33 @@ export function createRouter(
           status: maintenance.status,
           startAt: maintenance.startAt.toISOString(),
           endAt: maintenance.endAt.toISOString(),
-          action: "updated",
+          action,
         });
+
+        // Send notifications when status actually changes
+        if (input.statusChange && previousStatus !== input.statusChange) {
+          // Determine notification action based on the actual status transition
+          let notificationAction: "started" | "completed" | "updated";
+          if (
+            input.statusChange === "in_progress" &&
+            previousStatus !== "in_progress"
+          ) {
+            notificationAction = "started";
+          } else if (input.statusChange === "completed") {
+            notificationAction = "completed";
+          } else {
+            notificationAction = "updated";
+          }
+
+          await notifyAffectedSystems({
+            catalogClient,
+            logger,
+            maintenanceId: input.maintenanceId,
+            maintenanceTitle: maintenance.title,
+            systemIds: maintenance.systemIds,
+            action: notificationAction,
+          });
+        }
       }
       return result;
     }),

package/src/service.ts

@@ -1,5 +1,5 @@
 import { eq, and, or, inArray } from "drizzle-orm";
-import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { SafeDatabase } from "@checkstack/backend-api";
 import * as schema from "./schema";
 import { maintenances, maintenanceSystems, maintenanceUpdates } from "./schema";
 import type {
@@ -12,7 +12,7 @@ import type {
   MaintenanceStatus,
 } from "@checkstack/maintenance-common";
 
-type Db = NodePgDatabase<typeof schema>;
+type Db = SafeDatabase<typeof schema>;
 
 function generateId(): string {
   return crypto.randomUUID();
@@ -362,4 +362,110 @@ export class MaintenanceService {
 
     return !!match;
   }
+
+  /**
+   * Get maintenances that should transition from 'scheduled' to 'in_progress'.
+   * These are maintenances where status = 'scheduled' AND startAt <= now.
+   */
+  async getMaintenancesToStart(): Promise<MaintenanceWithSystems[]> {
+    const now = new Date();
+
+    const rows = await this.db
+      .select()
+      .from(maintenances)
+      .where(
+        and(
+          eq(maintenances.status, "scheduled"),
+          // startAt is in the past or now
+          // Using SQL comparison - startAt <= now
+        ),
+      );
+
+    // Filter in JS since Drizzle SQL comparison can be tricky with dates
+    const startable = rows.filter((m) => m.startAt <= now);
+
+    // Fetch system IDs for each
+    const result: MaintenanceWithSystems[] = [];
+    for (const m of startable) {
+      const systems = await this.db
+        .select({ systemId: maintenanceSystems.systemId })
+        .from(maintenanceSystems)
+        .where(eq(maintenanceSystems.maintenanceId, m.id));
+
+      result.push({
+        ...m,
+        description: m.description ?? undefined,
+        systemIds: systems.map((s) => s.systemId),
+      });
+    }
+
+    return result;
+  }
+
+  /**
+   * Get maintenances that should transition from 'in_progress' to 'completed'.
+   * These are maintenances where status = 'in_progress' AND endAt <= now.
+   */
+  async getMaintenancesToComplete(): Promise<MaintenanceWithSystems[]> {
+    const now = new Date();
+
+    const rows = await this.db
+      .select()
+      .from(maintenances)
+      .where(eq(maintenances.status, "in_progress"));
+
+    // Filter in JS for those that have ended
+    const completable = rows.filter((m) => m.endAt <= now);
+
+    // Fetch system IDs for each
+    const result: MaintenanceWithSystems[] = [];
+    for (const m of completable) {
+      const systems = await this.db
+        .select({ systemId: maintenanceSystems.systemId })
+        .from(maintenanceSystems)
+        .where(eq(maintenanceSystems.maintenanceId, m.id));
+
+      result.push({
+        ...m,
+        description: m.description ?? undefined,
+        systemIds: systems.map((s) => s.systemId),
+      });
+    }
+
+    return result;
+  }
+
+  /**
+   * Transition a maintenance to a new status with an automatic update entry.
+   * Used by the scheduled job for automatic status transitions.
+   */
+  async transitionStatus(
+    id: string,
+    newStatus: MaintenanceStatus,
+    message: string,
+  ): Promise<MaintenanceWithSystems | undefined> {
+    const [existing] = await this.db
+      .select()
+      .from(maintenances)
+      .where(eq(maintenances.id, id));
+
+    if (!existing) return undefined;
+
+    // Update the maintenance status
+    await this.db
+      .update(maintenances)
+      .set({ status: newStatus, updatedAt: new Date() })
+      .where(eq(maintenances.id, id));
+
+    // Add update entry (no user - system-generated)
+    await this.db.insert(maintenanceUpdates).values({
+      id: generateId(),
+      maintenanceId: id,
+      message,
+      statusChange: newStatus,
+      createdBy: undefined, // System-generated, no user
+    });
+
+    return (await this.getMaintenance(id))!;
+  }
 }