@checkstack/maintenance-backend 1.1.5 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,153 @@
 # @checkstack/maintenance-backend
 
+## 1.2.0
+
+### Minor Changes
+
+- 41c77f4: feat(automation): type enum-able trigger/artifact fields as enums for editor value autocompletion
+
+  The automation editor's staged completion offers concrete values after a
+  comparator (`{{ trigger.payload.severity == "high" }}`) only when the
+  field's JSON Schema carries an `enum`. Several trigger payload + artifact
+  schemas declared closed-set fields as loose `z.string()`, so no values
+  were suggested. Tightened them to the canonical enums that already
+  existed in each plugin's `-common` package (and matched the hook payload
+  types in lockstep so the trigger's `payloadSchema` and `hook` keep the
+  same `TPayload`):
+
+  - **incident** — trigger payloads: `severity` → `IncidentSeverityEnum`,
+    `status` / `statusChange` → `IncidentStatusEnum`.
+  - **healthcheck** — trigger payloads: `previousStatus` / `newStatus` /
+    `status` → `HealthCheckStatusSchema` (across systemDegraded,
+    systemHealthy, systemHealthChanged, checkFailed; plus checkCompleted's
+    hook type).
+  - **dependency** — trigger + artifact: `impactType` → `ImpactTypeSchema`;
+    impactPropagated `previousState` / `newState` → `DerivedStateSchema`.
+    Also deduped the inline `impactTypeSchema` action-config enum to reuse
+    the canonical `ImpactTypeSchema`.
+  - **maintenance** — trigger + artifact: `status` →
+    `MaintenanceStatusEnum`; deduped the inline `maintenanceStatusEnum`
+    (used by `add_update.statusChange`) to the canonical one.
+  - **slo** — `achievement.unlocked` trigger + hook: `achievement` →
+    `AchievementTypeSchema`.
+
+  Runtime behaviour is unchanged — these fields always carried valid enum
+  values (the underlying records are enum-constrained); only the schema
+  types were loose. The hook payload generics are now precise too, which
+  caught one stale test fixture asserting an invalid `impactType: "soft"`.
+
+  Fields that look enum-ish but are genuinely free-form were intentionally
+  left as `z.string()`: satellite `region` (user-entered), Jira issue
+  `status` (per-instance workflow name), notification `strategyQualifiedId`
+  / `errorMessage`, healthcheck collector `result`, and script
+  `stdout` / `stderr`.
+
+- 41c77f4: feat(maintenance): Phase 9 — actions + system-shaped helpers
+
+  - Triggers `maintenance.created`, `maintenance.updated` are unchanged;
+    they're now lifted out of the inline `register()` block into
+    `automations.ts` alongside the new actions.
+  - Actions `maintenance.create`, `maintenance.update`,
+    `maintenance.add_update` wrapping `MaintenanceService`. Each emits
+    the appropriate `maintenanceHooks.*` so downstream automations and
+    caches react identically to RPC-driven changes; `add_update`
+    re-fetches the window before emitting so the hook payload reflects
+    the new status.
+  - The two deferred catalog actions land here as
+    `maintenance.set_system` (schedule a `now → now+durationMinutes`
+    window covering a single system — the "park this system" operation)
+    and `maintenance.clear_system` (close every active or scheduled
+    window covering a given system — the "let it back into rotation"
+    operation).
+  - Artifact type `maintenance.window` for downstream steps to consume.
+
+### Patch Changes
+
+- 41c77f4: feat(automation): one-time migration of webhook subscriptions + remove legacy integration backend
+
+  **BREAKING CHANGES** (platform is in BETA — no major bump):
+
+  - `IntegrationProvider` no longer carries `config` (subscription
+    config) or `deliver`. The interface now models a connection provider
+    only: connection schema + `getConnectionOptions` + `testConnection`.
+  - The legacy subscription / delivery-log / event endpoints
+    (`listSubscriptions`, `createSubscription`, `getDeliveryLogs`,
+    `listEventTypes`, …) are removed from `integrationContract`.
+  - `delivery-coordinator`, `hook-subscriber`, `event-registry`, and the
+    `integrationEventExtensionPoint` are deleted. Plugins that
+    previously called `integrationEvents.registerEvent(...)` now
+    register their hooks as automation triggers via
+    `automationTriggerExtensionPoint.registerTrigger(...)`.
+  - Frontend pages `IntegrationsPage` and `DeliveryLogsPage` are gone;
+    the integration plugin's only remaining UI is connection
+    management. Subscription management lives under `/automation/...`.
+  - `webhook_subscriptions` and `delivery_logs` tables stay in the
+    database for one release as a safety net (no code reads or writes
+    them), and will be dropped in a follow-up migration.
+
+  **New**:
+
+  - `jira.create_issue`, `teams.post_message`, `webex.post_message`,
+    `webhook.send`, `integration-script.run_shell`, and
+    `integration-script.run_script` actions registered against the
+    Automation Platform with matching `*.message`, `*.delivery`,
+    `shell.result`, and `script.result` artifact types. The script
+    plugin exposes **two** actions — `run_shell` runs bash via the
+    shared `ShellScriptRunner` (Monaco `shell` editor), `run_script`
+    runs an ESM module in a Bun subprocess via `EsmScriptRunner`
+    (Monaco `typescript` editor + `defineIntegration` helper) — to
+    preserve the legacy provider split. `jira.create_issue` keeps the
+    dynamic field-mapping dropdown (driven by
+    `JIRA_RESOLVERS.FIELD_OPTIONS`).
+  - One-time data migration runs on boot in
+    `automation-backend.afterPluginsReady`. It reads
+    `webhook_subscriptions` via a new service RPC
+    `IntegrationApi.listLegacySubscriptions`, translates each row into
+    a single-trigger / single-action automation (marked with
+    `managed_by = "migrated-subscription:<id>"`), and is idempotent
+    across restarts.
+  - Failed translations are recorded in a new
+    `automation_migration_failures` table and surfaced via
+    `AutomationApi.listMigrationFailures` /
+    `acknowledgeMigrationFailure` so admins can review and re-create
+    failed entries by hand.
+
+- Updated dependencies [e2d6f25]
+- Updated dependencies [41c77f4]
+- Updated dependencies [e1a2077]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [6d52276]
+- Updated dependencies [6d52276]
+- Updated dependencies [35bc682]
+  - @checkstack/automation-backend@0.2.0
+  - @checkstack/catalog-backend@1.2.0
+  - @checkstack/common@0.12.0
+  - @checkstack/backend-api@0.18.0
+  - @checkstack/catalog-common@2.2.3
+  - @checkstack/maintenance-common@1.2.3
+  - @checkstack/auth-common@0.7.2
+  - @checkstack/command-backend@0.1.31
+  - @checkstack/notification-common@1.2.1
+  - @checkstack/signal-common@0.2.5
+  - @checkstack/cache-api@0.3.6
+  - @checkstack/cache-utils@0.2.11
+
+## 1.1.6
+
+### Patch Changes
+
+- @checkstack/backend-api@0.17.1
+- @checkstack/cache-api@0.3.5
+- @checkstack/catalog-backend@1.1.6
+- @checkstack/command-backend@0.1.30
+- @checkstack/integration-backend@0.1.30
+- @checkstack/cache-utils@0.2.10
+
 ## 1.1.5
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/maintenance-backend",
-  "version": "1.1.5",
+  "version": "1.2.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -11,30 +11,30 @@
     "typecheck": "tsgo -b",
     "generate": "drizzle-kit generate",
     "lint": "bun run lint:code",
-    "lint:code": "eslint . --max-warnings 0"
+    "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.16.0",
-    "@checkstack/cache-api": "0.3.3",
-    "@checkstack/cache-utils": "0.2.8",
-    "@checkstack/maintenance-common": "1.2.1",
-    "@checkstack/notification-common": "1.1.1",
-    "@checkstack/catalog-common": "2.2.1",
-    "@checkstack/catalog-backend": "1.1.4",
-    "@checkstack/auth-common": "0.7.0",
-    "@checkstack/command-backend": "0.1.28",
-    "@checkstack/signal-common": "0.2.3",
-    "@checkstack/integration-backend": "0.1.28",
-    "@checkstack/integration-common": "0.4.0",
+    "@checkstack/backend-api": "0.17.1",
+    "@checkstack/cache-api": "0.3.5",
+    "@checkstack/cache-utils": "0.2.10",
+    "@checkstack/maintenance-common": "1.2.2",
+    "@checkstack/notification-common": "1.2.0",
+    "@checkstack/catalog-common": "2.2.2",
+    "@checkstack/catalog-backend": "1.1.6",
+    "@checkstack/auth-common": "0.7.1",
+    "@checkstack/command-backend": "0.1.30",
+    "@checkstack/signal-common": "0.2.4",
+    "@checkstack/automation-backend": "0.1.0",
     "drizzle-orm": "^0.45.0",
     "zod": "^4.2.1",
-    "@checkstack/common": "0.10.0",
+    "@checkstack/common": "0.11.0",
     "@orpc/server": "^1.13.2"
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/scripts": "0.3.2",
-    "@checkstack/test-utils-backend": "0.1.28",
+    "@checkstack/scripts": "0.3.3",
+    "@checkstack/test-utils-backend": "0.1.30",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
     "drizzle-kit": "^0.31.10",

package/src/automations.test.ts

@@ -0,0 +1,368 @@
+/**
+ * Behaviour tests for the maintenance automation triggers + actions.
+ */
+import { describe, expect, it, mock } from "bun:test";
+import type { Logger } from "@checkstack/backend-api";
+import { createMockLogger } from "@checkstack/test-utils-backend";
+
+import {
+  createMaintenanceActions,
+  maintenanceArtifactType,
+  maintenanceCreatedTrigger,
+  maintenanceTriggers,
+  maintenanceUpdatedTrigger,
+} from "./automations";
+import { maintenanceHooks } from "./hooks";
+import type { MaintenanceService } from "./service";
+
+const logger = createMockLogger() as Logger;
+
+const ctxBase = {
+  runId: "run-1",
+  automationId: "auto-1",
+  contextKey: null,
+  logger,
+  getService: async <T,>(): Promise<T> => {
+    throw new Error("not used");
+  },
+};
+
+// ─── Triggers ──────────────────────────────────────────────────────────
+
+describe("maintenance triggers", () => {
+  it("exposes two triggers in a stable order", () => {
+    expect(maintenanceTriggers).toHaveLength(2);
+    expect(maintenanceTriggers[0]).toBe(
+      maintenanceCreatedTrigger as (typeof maintenanceTriggers)[number],
+    );
+    expect(maintenanceTriggers[1]).toBe(
+      maintenanceUpdatedTrigger as (typeof maintenanceTriggers)[number],
+    );
+  });
+
+  it("extracts maintenanceId as the contextKey on both triggers", () => {
+    const payload = {
+      maintenanceId: "m-1",
+      systemIds: ["sys-1"],
+      title: "Deploy",
+      status: "scheduled" as const,
+      startAt: "2026-05-29T11:00:00Z",
+      endAt: "2026-05-29T12:00:00Z",
+    };
+    expect(maintenanceCreatedTrigger.contextKey?.(payload)).toBe("m-1");
+    expect(
+      maintenanceUpdatedTrigger.contextKey?.({ ...payload, action: "updated" }),
+    ).toBe("m-1");
+  });
+
+  it("requires action enum on updated payload", () => {
+    const ok = maintenanceUpdatedTrigger.payloadSchema.safeParse({
+      maintenanceId: "m-1",
+      systemIds: [],
+      title: "Deploy",
+      status: "completed",
+      startAt: "2026-05-29T11:00:00Z",
+      endAt: "2026-05-29T12:00:00Z",
+      action: "closed",
+    });
+    const bad = maintenanceUpdatedTrigger.payloadSchema.safeParse({
+      maintenanceId: "m-1",
+      systemIds: [],
+      title: "Deploy",
+      status: "completed",
+      startAt: "2026-05-29T11:00:00Z",
+      endAt: "2026-05-29T12:00:00Z",
+    });
+    expect(ok.success).toBe(true);
+    expect(bad.success).toBe(false);
+  });
+});
+
+describe("maintenanceArtifactType", () => {
+  it("validates the canonical artifact shape", () => {
+    const ok = maintenanceArtifactType.schema.safeParse({
+      maintenanceId: "m-1",
+      status: "scheduled",
+      systemIds: ["sys-1"],
+      startAt: "2026-05-29T11:00:00Z",
+      endAt: "2026-05-29T12:00:00Z",
+    });
+    expect(ok.success).toBe(true);
+  });
+});
+
+// ─── Actions ───────────────────────────────────────────────────────────
+
+interface FakeMaintenance {
+  id: string;
+  title: string;
+  description?: string;
+  status: string;
+  systemIds: string[];
+  startAt: Date;
+  endAt: Date;
+}
+
+function makeService(args: {
+  rowToReturn?: FakeMaintenance;
+  updateReturn?: FakeMaintenance | undefined;
+  getMaintenanceReturn?: FakeMaintenance | undefined;
+  activeForSystem?: FakeMaintenance[];
+  closeReturn?: FakeMaintenance | undefined;
+}): MaintenanceService & {
+  createMock: ReturnType<typeof mock>;
+  updateMock: ReturnType<typeof mock>;
+  addUpdateMock: ReturnType<typeof mock>;
+  getMock: ReturnType<typeof mock>;
+  activeMock: ReturnType<typeof mock>;
+  closeMock: ReturnType<typeof mock>;
+} {
+  const createMock = mock(async (_input: unknown) => args.rowToReturn);
+  const updateMock = mock(async (_input: unknown) => args.updateReturn);
+  const addUpdateMock = mock(async (_input: unknown) => ({
+    id: "upd-1",
+    maintenanceId: "m-1",
+    message: "x",
+    statusChange: undefined,
+    createdBy: undefined,
+    createdAt: new Date(),
+  }));
+  const getMock = mock(async (_id: string) => args.getMaintenanceReturn);
+  const activeMock = mock(async (_id: string) => args.activeForSystem ?? []);
+  const closeMock = mock(async (_id: string, _msg?: string) => args.closeReturn);
+  return {
+    createMaintenance: createMock,
+    updateMaintenance: updateMock,
+    addUpdate: addUpdateMock,
+    getMaintenance: getMock,
+    getMaintenancesForSystem: activeMock,
+    closeMaintenance: closeMock,
+    createMock,
+    updateMock,
+    addUpdateMock,
+    getMock,
+    activeMock,
+    closeMock,
+  } as unknown as MaintenanceService & {
+    createMock: ReturnType<typeof mock>;
+    updateMock: ReturnType<typeof mock>;
+    addUpdateMock: ReturnType<typeof mock>;
+    getMock: ReturnType<typeof mock>;
+    activeMock: ReturnType<typeof mock>;
+    closeMock: ReturnType<typeof mock>;
+  };
+}
+
+const sampleRow: FakeMaintenance = {
+  id: "m-1",
+  title: "Deploy",
+  status: "scheduled",
+  systemIds: ["sys-1"],
+  startAt: new Date("2026-05-29T11:00:00Z"),
+  endAt: new Date("2026-05-29T12:00:00Z"),
+};
+
+describe("maintenance.create", () => {
+  it("creates a maintenance, fires maintenanceCreated, and emits a maintenance.window artifact", async () => {
+    const service = makeService({ rowToReturn: sampleRow });
+    const emitHook = mock(async (_hook: unknown, _payload: unknown) => {});
+    const [create] = createMaintenanceActions({
+      service,
+      emitHook: emitHook as never,
+    });
+
+    const result = await create!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        title: "Deploy",
+        systemIds: ["sys-1"],
+        startAt: "2026-05-29T11:00:00Z",
+        endAt: "2026-05-29T12:00:00Z",
+      } as never,
+    });
+
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.externalId).toBe("m-1");
+    expect(emitHook).toHaveBeenCalledTimes(1);
+    expect(emitHook.mock.calls[0]![0]).toBe(maintenanceHooks.maintenanceCreated);
+  });
+});
+
+describe("maintenance.update", () => {
+  it("returns failure when the maintenance doesn't exist", async () => {
+    const service = makeService({ updateReturn: undefined });
+    const emitHook = mock(async (_hook: unknown, _payload: unknown) => {});
+    const [, update] = createMaintenanceActions({
+      service,
+      emitHook: emitHook as never,
+    });
+
+    const result = await update!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { maintenanceId: "missing", title: "x" } as never,
+    });
+
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.error).toMatch(/not found/i);
+    expect(emitHook).not.toHaveBeenCalled();
+  });
+
+  it("emits maintenanceUpdated with action='updated' on success", async () => {
+    const service = makeService({ updateReturn: sampleRow });
+    const emitHook = mock(async (_hook: unknown, _payload: unknown) => {});
+    const [, update] = createMaintenanceActions({
+      service,
+      emitHook: emitHook as never,
+    });
+
+    const result = await update!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { maintenanceId: "m-1", title: "Deploy v2" } as never,
+    });
+
+    expect(result.success).toBe(true);
+    const emitCall = emitHook.mock.calls[0]!;
+    expect(emitCall[0]).toBe(maintenanceHooks.maintenanceUpdated);
+    expect((emitCall[1] as { action: string }).action).toBe("updated");
+  });
+});
+
+describe("maintenance.add_update", () => {
+  it("uses action='closed' when statusChange is 'completed'", async () => {
+    const service = makeService({
+      getMaintenanceReturn: { ...sampleRow, status: "completed" },
+    });
+    const emitHook = mock(async (_hook: unknown, _payload: unknown) => {});
+    const [, , addUpdate] = createMaintenanceActions({
+      service,
+      emitHook: emitHook as never,
+    });
+
+    const result = await addUpdate!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        maintenanceId: "m-1",
+        message: "done",
+        statusChange: "completed",
+      } as never,
+    });
+
+    expect(result.success).toBe(true);
+    expect((emitHook.mock.calls[0]![1] as { action: string }).action).toBe(
+      "closed",
+    );
+  });
+
+  it("returns failure when the maintenance vanishes between addUpdate and getMaintenance", async () => {
+    const service = makeService({ getMaintenanceReturn: undefined });
+    const emitHook = mock(async (_hook: unknown, _payload: unknown) => {});
+    const [, , addUpdate] = createMaintenanceActions({
+      service,
+      emitHook: emitHook as never,
+    });
+
+    const result = await addUpdate!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { maintenanceId: "m-1", message: "x" } as never,
+    });
+
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.error).toMatch(/not found/i);
+    expect(emitHook).not.toHaveBeenCalled();
+  });
+});
+
+describe("maintenance.set_system", () => {
+  it("schedules a now+durationMinutes window covering one system", async () => {
+    const service = makeService({ rowToReturn: sampleRow });
+    const emitHook = mock(async (_hook: unknown, _payload: unknown) => {});
+    const fixedNow = new Date("2026-05-29T11:00:00Z");
+    const [, , , setSystem] = createMaintenanceActions({
+      service,
+      emitHook: emitHook as never,
+      now: () => fixedNow,
+    });
+
+    await setSystem!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        systemId: "sys-1",
+        durationMinutes: 60,
+      } as never,
+    });
+
+    expect(service.createMock).toHaveBeenCalledTimes(1);
+    const call = service.createMock.mock.calls[0]![0] as {
+      systemIds: string[];
+      startAt: Date;
+      endAt: Date;
+    };
+    expect(call.systemIds).toEqual(["sys-1"]);
+    expect(call.startAt.toISOString()).toBe("2026-05-29T11:00:00.000Z");
+    expect(call.endAt.toISOString()).toBe("2026-05-29T12:00:00.000Z");
+  });
+});
+
+describe("maintenance.clear_system", () => {
+  it("closes every active window for the system + emits one updated hook per close", async () => {
+    const window1 = { ...sampleRow, id: "m-1" };
+    const window2 = { ...sampleRow, id: "m-2" };
+    const service = makeService({
+      activeForSystem: [window1, window2],
+      closeReturn: window1,
+    });
+    // closeMaintenance returns the same row both times in the fixture
+    // — that's fine for this test; we only assert the count + ids.
+    const emitHook = mock(async (_hook: unknown, _payload: unknown) => {});
+    const actions = createMaintenanceActions({
+      service,
+      emitHook: emitHook as never,
+    });
+    const clearSystem = actions[4]!;
+
+    const result = await clearSystem.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { systemId: "sys-1" } as never,
+    });
+
+    expect(result.success).toBe(true);
+    expect(service.closeMock).toHaveBeenCalledTimes(2);
+    expect(emitHook).toHaveBeenCalledTimes(2);
+    for (const call of emitHook.mock.calls) {
+      expect(call[0]).toBe(maintenanceHooks.maintenanceUpdated);
+      expect((call[1] as { action: string }).action).toBe("closed");
+    }
+  });
+
+  it("succeeds and emits an empty artifact when no windows are active for the system", async () => {
+    const service = makeService({ activeForSystem: [] });
+    const emitHook = mock(async (_hook: unknown, _payload: unknown) => {});
+    const actions = createMaintenanceActions({
+      service,
+      emitHook: emitHook as never,
+    });
+    const clearSystem = actions[4]!;
+
+    const result = await clearSystem.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: { systemId: "sys-1" } as never,
+    });
+
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    const artifact = result.artifact as { closedMaintenanceIds: string[] };
+    expect(artifact.closedMaintenanceIds).toEqual([]);
+    expect(emitHook).not.toHaveBeenCalled();
+  });
+});

package/src/automations.ts

@@ -0,0 +1,422 @@
+/**
+ * Maintenance triggers + actions registered with the Automation Platform.
+ *
+ * Triggers re-expose `maintenanceHooks` as automation entry points
+ * (`maintenance.created`, `maintenance.updated`). The existing index
+ * registered these inline; this module owns them now alongside the
+ * actions so the plugin's automation surface lives in one place.
+ *
+ * Actions wrap `MaintenanceService` for `create`, `update`, and
+ * `add_update`. The catalog Phase-9 chunk deferred two additional
+ * "system-shaped" actions to this chunk:
+ *
+ *   - `set_system`: schedule a maintenance window that starts now and
+ *     covers a single system, for a given duration. The convenient
+ *     "park this system for an hour" operation.
+ *   - `clear_system`: close every active/scheduled maintenance that
+ *     covers a given system. The convenient "let it back into rotation
+ *     even if maintenance was over-scheduled" operation.
+ *
+ * Mutation actions emit the matching hooks themselves (via the
+ * `emitHook` factory dep) so downstream automations + caches react
+ * the same way they do when the mutation comes in via RPC.
+ */
+import { z } from "zod";
+import { Versioned, type Hook } from "@checkstack/backend-api";
+import type {
+  ActionDefinition,
+  TriggerDefinition,
+} from "@checkstack/automation-backend";
+import {
+  MaintenanceStatusEnum,
+  type MaintenanceStatus,
+} from "@checkstack/maintenance-common";
+
+import { maintenanceHooks } from "./hooks";
+import type { MaintenanceService } from "./service";
+
+// ─── Payload schemas ───────────────────────────────────────────────────
+
+const maintenanceCreatedPayloadSchema = z.object({
+  maintenanceId: z.string(),
+  systemIds: z.array(z.string()),
+  title: z.string(),
+  description: z.string().optional(),
+  status: MaintenanceStatusEnum,
+  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: MaintenanceStatusEnum,
+  startAt: z.string(),
+  endAt: z.string(),
+  action: z.enum(["updated", "closed"]),
+});
+
+// ─── Triggers ──────────────────────────────────────────────────────────
+
+export const maintenanceCreatedTrigger: TriggerDefinition<
+  z.infer<typeof maintenanceCreatedPayloadSchema>
+> = {
+  id: "created",
+  displayName: "Maintenance Created",
+  description: "Fired when a new maintenance is scheduled",
+  category: "Maintenance",
+  icon: "Wrench",
+  payloadSchema: maintenanceCreatedPayloadSchema,
+  hook: maintenanceHooks.maintenanceCreated,
+  contextKey: (p) => p.maintenanceId,
+};
+
+export const maintenanceUpdatedTrigger: TriggerDefinition<
+  z.infer<typeof maintenanceUpdatedPayloadSchema>
+> = {
+  id: "updated",
+  displayName: "Maintenance Updated",
+  description: "Fired when a maintenance is updated or closed",
+  category: "Maintenance",
+  icon: "Wrench",
+  payloadSchema: maintenanceUpdatedPayloadSchema,
+  hook: maintenanceHooks.maintenanceUpdated,
+  contextKey: (p) => p.maintenanceId,
+};
+
+export const maintenanceTriggers: TriggerDefinition<unknown>[] = [
+  maintenanceCreatedTrigger as TriggerDefinition<unknown>,
+  maintenanceUpdatedTrigger as TriggerDefinition<unknown>,
+];
+
+// ─── Action configs ────────────────────────────────────────────────────
+
+const createConfigSchema = z.object({
+  title: z.string().min(1),
+  description: z.string().optional(),
+  systemIds: z.array(z.string()).min(1),
+  startAt: z
+    .string()
+    .describe("ISO timestamp when the window starts"),
+  endAt: z.string().describe("ISO timestamp when the window ends"),
+  suppressNotifications: z.boolean().optional().default(false),
+});
+
+const updateConfigSchema = z.object({
+  maintenanceId: z.string().min(1),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  systemIds: z.array(z.string()).optional(),
+  startAt: z.string().optional(),
+  endAt: z.string().optional(),
+  suppressNotifications: z.boolean().optional(),
+});
+
+const addUpdateConfigSchema = z.object({
+  maintenanceId: z.string().min(1),
+  message: z.string().min(1),
+  statusChange: MaintenanceStatusEnum.optional(),
+});
+
+const setSystemConfigSchema = z.object({
+  systemId: z.string().min(1),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  durationMinutes: z
+    .number()
+    .int()
+    .min(1)
+    .max(30 * 24 * 60)
+    .describe("Window length in minutes (1 min – 30 days)"),
+  suppressNotifications: z.boolean().optional().default(false),
+});
+
+const clearSystemConfigSchema = z.object({
+  systemId: z.string().min(1),
+  message: z
+    .string()
+    .optional()
+    .describe(
+      "Note appended to the maintenance update log; defaults to a generic 'cleared by automation' message",
+    ),
+});
+
+// ─── Artifact ──────────────────────────────────────────────────────────
+
+const maintenanceArtifactSchema = z.object({
+  maintenanceId: z.string(),
+  status: MaintenanceStatusEnum,
+  systemIds: z.array(z.string()),
+  startAt: z.string(),
+  endAt: z.string(),
+});
+
+export type MaintenanceArtifact = z.infer<typeof maintenanceArtifactSchema>;
+
+export const maintenanceArtifactType = {
+  id: "window",
+  displayName: "Maintenance Window",
+  description: "Maintenance row touched (created/updated/closed) by an automation",
+  schema: maintenanceArtifactSchema,
+} as const;
+
+// ─── Action factory ────────────────────────────────────────────────────
+
+export interface MaintenanceActionDeps {
+  service: MaintenanceService;
+  emitHook: <T>(hook: Hook<T>, payload: T) => Promise<void>;
+  /**
+   * Override for `Date.now()`. Only used by `set_system` to compute
+   * `endAt = now + durationMinutes`. Tests inject a fixed clock; the
+   * default uses the real wall clock.
+   */
+  now?: () => Date;
+}
+
+function toArtifact(maint: {
+  id: string;
+  status: MaintenanceStatus;
+  systemIds: string[];
+  startAt: Date | string;
+  endAt: Date | string;
+}): MaintenanceArtifact {
+  return {
+    maintenanceId: maint.id,
+    status: maint.status,
+    systemIds: maint.systemIds,
+    startAt:
+      maint.startAt instanceof Date ? maint.startAt.toISOString() : maint.startAt,
+    endAt: maint.endAt instanceof Date ? maint.endAt.toISOString() : maint.endAt,
+  };
+}
+
+export function createMaintenanceActions(
+  deps: MaintenanceActionDeps,
+): ActionDefinition<unknown, unknown>[] {
+  const now = deps.now ?? (() => new Date());
+
+  const createAction: ActionDefinition<
+    z.infer<typeof createConfigSchema>,
+    MaintenanceArtifact
+  > = {
+    id: "create",
+    displayName: "Schedule Maintenance",
+    description: "Schedule a new maintenance window",
+    category: "Maintenance",
+    icon: "Wrench",
+    config: new Versioned({ version: 1, schema: createConfigSchema }),
+    produces: "maintenance.window",
+    execute: async ({ config, logger }) => {
+      const created = await deps.service.createMaintenance({
+        title: config.title,
+        description: config.description,
+        systemIds: config.systemIds,
+        startAt: new Date(config.startAt),
+        endAt: new Date(config.endAt),
+        suppressNotifications: config.suppressNotifications,
+      });
+      const artifact = toArtifact(created);
+      await deps.emitHook(maintenanceHooks.maintenanceCreated, {
+        maintenanceId: created.id,
+        systemIds: created.systemIds,
+        title: created.title,
+        description: created.description,
+        status: created.status,
+        startAt: artifact.startAt,
+        endAt: artifact.endAt,
+      });
+      logger.info(`Automation scheduled maintenance ${created.id}`);
+      return {
+        success: true,
+        externalId: created.id,
+        artifact,
+      };
+    },
+  };
+
+  const updateAction: ActionDefinition<
+    z.infer<typeof updateConfigSchema>,
+    MaintenanceArtifact
+  > = {
+    id: "update",
+    displayName: "Update Maintenance",
+    description: "Update an existing maintenance window's metadata or schedule",
+    category: "Maintenance",
+    icon: "Wrench",
+    config: new Versioned({ version: 1, schema: updateConfigSchema }),
+    produces: "maintenance.window",
+    execute: async ({ config, logger }) => {
+      const updated = await deps.service.updateMaintenance({
+        id: config.maintenanceId,
+        title: config.title,
+        description: config.description,
+        systemIds: config.systemIds,
+        startAt: config.startAt ? new Date(config.startAt) : undefined,
+        endAt: config.endAt ? new Date(config.endAt) : undefined,
+        suppressNotifications: config.suppressNotifications,
+      });
+      if (!updated) {
+        return {
+          success: false,
+          error: `Maintenance not found: ${config.maintenanceId}`,
+        };
+      }
+      const artifact = toArtifact(updated);
+      await deps.emitHook(maintenanceHooks.maintenanceUpdated, {
+        maintenanceId: updated.id,
+        systemIds: updated.systemIds,
+        title: updated.title,
+        description: updated.description,
+        status: updated.status,
+        startAt: artifact.startAt,
+        endAt: artifact.endAt,
+        action: "updated",
+      });
+      logger.info(`Automation updated maintenance ${updated.id}`);
+      return { success: true, externalId: updated.id, artifact };
+    },
+  };
+
+  const addUpdateAction: ActionDefinition<
+    z.infer<typeof addUpdateConfigSchema>,
+    MaintenanceArtifact
+  > = {
+    id: "add_update",
+    displayName: "Add Maintenance Update",
+    description: "Append a status-update note to a maintenance window",
+    category: "Maintenance",
+    icon: "MessageSquarePlus",
+    config: new Versioned({ version: 1, schema: addUpdateConfigSchema }),
+    produces: "maintenance.window",
+    execute: async ({ config, logger }) => {
+      await deps.service.addUpdate({
+        maintenanceId: config.maintenanceId,
+        message: config.message,
+        statusChange: config.statusChange,
+      });
+      // Re-fetch so we surface the latest window state to the next
+      // step + so the emitted hook payload matches the (now-updated)
+      // row.
+      const refreshed = await deps.service.getMaintenance(config.maintenanceId);
+      if (!refreshed) {
+        return {
+          success: false,
+          error: `Maintenance ${config.maintenanceId} not found after update`,
+        };
+      }
+      const artifact = toArtifact(refreshed);
+      await deps.emitHook(maintenanceHooks.maintenanceUpdated, {
+        maintenanceId: refreshed.id,
+        systemIds: refreshed.systemIds,
+        title: refreshed.title,
+        description: refreshed.description,
+        status: refreshed.status,
+        startAt: artifact.startAt,
+        endAt: artifact.endAt,
+        action: config.statusChange === "completed" ? "closed" : "updated",
+      });
+      logger.info(`Automation added update to maintenance ${refreshed.id}`);
+      return { success: true, externalId: refreshed.id, artifact };
+    },
+  };
+
+  const setSystemAction: ActionDefinition<
+    z.infer<typeof setSystemConfigSchema>,
+    MaintenanceArtifact
+  > = {
+    id: "set_system",
+    displayName: "Set System Maintenance",
+    description:
+      "Schedule a maintenance window covering a single system, starting now and lasting `durationMinutes` minutes.",
+    category: "Maintenance",
+    icon: "Wrench",
+    config: new Versioned({ version: 1, schema: setSystemConfigSchema }),
+    produces: "maintenance.window",
+    execute: async ({ config, logger }) => {
+      const startAt = now();
+      const endAt = new Date(
+        startAt.getTime() + config.durationMinutes * 60_000,
+      );
+      const created = await deps.service.createMaintenance({
+        title: config.title ?? `Automation maintenance (${config.systemId})`,
+        description: config.description,
+        systemIds: [config.systemId],
+        startAt,
+        endAt,
+        suppressNotifications: config.suppressNotifications,
+      });
+      const artifact = toArtifact(created);
+      await deps.emitHook(maintenanceHooks.maintenanceCreated, {
+        maintenanceId: created.id,
+        systemIds: created.systemIds,
+        title: created.title,
+        description: created.description,
+        status: created.status,
+        startAt: artifact.startAt,
+        endAt: artifact.endAt,
+      });
+      logger.info(
+        `Automation parked system ${config.systemId} via maintenance ${created.id}`,
+      );
+      return { success: true, externalId: created.id, artifact };
+    },
+  };
+
+  interface ClearSystemArtifact {
+    systemId: string;
+    closedMaintenanceIds: string[];
+  }
+
+  const clearSystemAction: ActionDefinition<
+    z.infer<typeof clearSystemConfigSchema>,
+    ClearSystemArtifact
+  > = {
+    id: "clear_system",
+    displayName: "Clear System Maintenance",
+    description:
+      "Close every active or scheduled maintenance window that covers this system.",
+    category: "Maintenance",
+    icon: "Wrench",
+    config: new Versioned({ version: 1, schema: clearSystemConfigSchema }),
+    produces: "maintenance.window",
+    execute: async ({ config, logger }) => {
+      const active = await deps.service.getMaintenancesForSystem(config.systemId);
+      const closedIds: string[] = [];
+      const message = config.message ?? "Cleared by automation";
+      for (const window of active) {
+        const closed = await deps.service.closeMaintenance(window.id, message);
+        if (!closed) continue;
+        closedIds.push(closed.id);
+        const artifact = toArtifact(closed);
+        await deps.emitHook(maintenanceHooks.maintenanceUpdated, {
+          maintenanceId: closed.id,
+          systemIds: closed.systemIds,
+          title: closed.title,
+          description: closed.description,
+          status: closed.status,
+          startAt: artifact.startAt,
+          endAt: artifact.endAt,
+          action: "closed",
+        });
+      }
+      logger.info(
+        `Automation cleared maintenance for system ${config.systemId} (${closedIds.length} window(s))`,
+      );
+      return {
+        success: true,
+        externalId: config.systemId,
+        artifact: { systemId: config.systemId, closedMaintenanceIds: closedIds },
+      };
+    },
+  };
+
+  return [
+    createAction as ActionDefinition<unknown, unknown>,
+    updateAction as ActionDefinition<unknown, unknown>,
+    addUpdateAction as ActionDefinition<unknown, unknown>,
+    setSystemAction as ActionDefinition<unknown, unknown>,
+    clearSystemAction as ActionDefinition<unknown, unknown>,
+  ];
+}

package/src/hooks.ts

@@ -1,9 +1,14 @@
 import { createHook } from "@checkstack/backend-api";
+import type { MaintenanceStatus } from "@checkstack/maintenance-common";
 
 /**
  * Maintenance hooks for cross-plugin communication.
  * Other plugins can subscribe to these hooks to react to maintenance lifecycle events.
  * These hooks are registered as integration events for webhook subscriptions.
+ *
+ * `status` carries the canonical `MaintenanceStatus` enum value, so
+ * automation triggers built on these hooks can offer the known values
+ * for `==` comparisons in the editor.
  */
 export const maintenanceHooks = {
   /**
@@ -15,7 +20,7 @@ export const maintenanceHooks = {
     systemIds: string[];
     title: string;
     description?: string;
-    status: string;
+    status: MaintenanceStatus;
     startAt: string;
     endAt: string;
   }>("maintenance.created"),
@@ -29,7 +34,7 @@ export const maintenanceHooks = {
     systemIds: string[];
     title: string;
     description?: string;
-    status: string;
+    status: MaintenanceStatus;
     startAt: string;
     endAt: string;
     action: "updated" | "closed";

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,11 @@ import {
 } from "@checkstack/maintenance-common";
 
 import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
-import { integrationEventExtensionPoint } from "@checkstack/integration-backend";
+import {
+  automationActionExtensionPoint,
+  automationArtifactTypeExtensionPoint,
+  automationTriggerExtensionPoint,
+} from "@checkstack/automation-backend";
 import {
   NotificationApi,
   specToRegistration,
@@ -24,33 +27,12 @@ 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";
 
 // Queue and job constants
 const STATUS_TRANSITION_QUEUE = "maintenance-status-transitions";
@@ -70,32 +52,19 @@ export default createBackendPlugin({
       maintenanceGroupSubscription,
     ]);
 
-    // Register hooks as integration events
-    const integrationEvents = env.getExtensionPoint(
-      integrationEventExtensionPoint,
-    );
-
-    integrationEvents.registerEvent(
-      {
-        hook: maintenanceHooks.maintenanceCreated,
-        displayName: "Maintenance Created",
-        description: "Fired when a new maintenance is scheduled",
-        category: "Maintenance",
-        payloadSchema: maintenanceCreatedPayloadSchema,
-      },
-      pluginMetadata,
-    );
-
-    integrationEvents.registerEvent(
-      {
-        hook: maintenanceHooks.maintenanceUpdated,
-        displayName: "Maintenance Updated",
-        description: "Fired when a maintenance is updated or closed",
-        category: "Maintenance",
-        payloadSchema: maintenanceUpdatedPayloadSchema,
-      },
-      pluginMetadata,
+    // ─── Automation Platform: triggers + artifact type ─────────────────
+    // Buffered behind the extension point until automation-backend's
+    // register() runs. Actions are wired in afterPluginsReady so
+    // `emitHook` is available — see below.
+    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;
@@ -172,7 +141,18 @@ export default createBackendPlugin({
 
         logger.debug("✅ Maintenance Backend initialized.");
       },
-      afterPluginsReady: async ({ queueManager, logger }) => {
+      afterPluginsReady: async ({ queueManager, logger, emitHook }) => {
+        // Register automation actions now that `emitHook` is available.
+        const automationActions = env.getExtensionPoint(
+          automationActionExtensionPoint,
+        );
+        for (const action of createMaintenanceActions({
+          service: maintenanceService,
+          emitHook,
+        })) {
+          automationActions.registerAction(action, pluginMetadata);
+        }
+
         // Notification subscription specs. Per-resource group lifecycle
         // is platform-managed by notification-backend — maintenance just
         // declares the specs.

package/tsconfig.json

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