@checkstack/maintenance-backend 1.3.1 → 1.4.1

package/src/ai/maintenance-remove-link.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  MaintenanceApi,
+  maintenanceAccess,
+  pluginMetadata,
+} from "@checkstack/maintenance-common";
+import type { AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+
+/** Input for `maintenance.removeLink`: the link id to remove. */
+export const MaintenanceRemoveLinkInputSchema = z.object({
+  id: z.string(),
+});
+export type MaintenanceRemoveLinkInput = z.infer<
+  typeof MaintenanceRemoveLinkInputSchema
+>;
+
+/** Output returned once a human applies the removal. */
+export interface MaintenanceRemoveLinkApplyResult {
+  id: string;
+  removed: true;
+}
+
+/**
+ * `maintenance.removeLink` - remove a hotlink from a maintenance window by link
+ * id.
+ *
+ * `effect: "destructive"` - removal is irreversible, so it ALWAYS routes through
+ * the propose/apply confirm card in BOTH permission modes (it can never
+ * auto-apply). `execute` (reached only via `apply`) performs the removal through
+ * the USER-SCOPED client, so handler-side authorization is enforced exactly as a
+ * direct UI/RPC call.
+ */
+export function createMaintenanceRemoveLinkTool(): RegisteredAiTool<
+  MaintenanceRemoveLinkInput,
+  MaintenanceRemoveLinkApplyResult
+> {
+  const dryRun = async ({
+    input,
+  }: {
+    input: MaintenanceRemoveLinkInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<MaintenanceRemoveLinkInput>> => {
+    return {
+      summary: `Remove link "${input.id}" from its maintenance window. This is permanent.`,
+      payload: { id: input.id },
+    };
+  };
+
+  return {
+    name: "maintenance.removeLink",
+    description:
+      "Remove a hotlink from a maintenance window by link id. DESTRUCTIVE and irreversible. Never removes directly; a person must approve the confirmation. Find the link id with the maintenance read tools first.",
+    effect: "destructive",
+    input: MaintenanceRemoveLinkInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(pluginMetadata, maintenanceAccess.maintenance.manage),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const maintenanceClient = rpcClient.forPlugin(MaintenanceApi);
+      await maintenanceClient.removeLink({ id: input.id });
+      return { id: input.id, removed: true };
+    },
+  };
+}

package/src/ai/maintenance-update.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import { createMaintenanceUpdateTool } from "./maintenance-update";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["maintenance.maintenance.manage"],
+};
+
+const existing = {
+  id: "m1",
+  title: "DB upgrade",
+  description: "Planned upgrade",
+  suppressNotifications: false,
+  status: "scheduled" as const,
+  startAt: new Date("2026-07-01T10:00:00.000Z"),
+  endAt: new Date("2026-07-01T12:00:00.000Z"),
+  createdAt: new Date(),
+  updatedAt: new Date(),
+  systemIds: ["s1"],
+  updates: [],
+  links: [],
+};
+
+function fakeRpcClient({
+  getMaintenance,
+  updateMaintenance,
+}: {
+  getMaintenance: ReturnType<typeof mock>;
+  updateMaintenance: ReturnType<typeof mock>;
+}): RpcClient {
+  return {
+    forPlugin: () => ({ getMaintenance, updateMaintenance }),
+  } as unknown as RpcClient;
+}
+
+describe("maintenance.update tool", () => {
+  test("declares mutate effect + the manage rule", () => {
+    const tool = createMaintenanceUpdateTool();
+    expect(tool.name).toBe("maintenance.update");
+    expect(tool.effect).toBe("mutate");
+    expect(tool.requiredAccessRules).toEqual([
+      "maintenance.maintenance.manage",
+    ]);
+    expect(typeof tool.dryRun).toBe("function");
+  });
+
+  test("dryRun fetches the maintenance and returns a diff", async () => {
+    const getMaintenance = mock(() => Promise.resolve(existing));
+    const updateMaintenance = mock(() => Promise.resolve());
+    const rpcClient = fakeRpcClient({ getMaintenance, updateMaintenance });
+    const tool = createMaintenanceUpdateTool();
+    const preview = await tool.dryRun!({
+      input: { id: "m1", title: "DB upgrade v2" },
+      principal,
+      rpcClient,
+    });
+    expect(getMaintenance).toHaveBeenCalledWith({ id: "m1" });
+    expect(updateMaintenance).not.toHaveBeenCalled();
+    expect(preview.diff).toBeDefined();
+    expect(preview.summary).toContain("DB upgrade");
+  });
+
+  test("dryRun throws a clear error when the id is unknown", async () => {
+    const rpcClient = fakeRpcClient({
+      getMaintenance: mock(() => Promise.resolve(null)),
+      updateMaintenance: mock(),
+    });
+    const tool = createMaintenanceUpdateTool();
+    await expect(
+      tool.dryRun!({ input: { id: "nope" }, principal, rpcClient }),
+    ).rejects.toThrow(/No maintenance found/);
+  });
+
+  test("coerces ISO string dates to Date instances before the RPC", async () => {
+    let received: { startAt: unknown; endAt: unknown } | undefined;
+    const getMaintenance = mock(() => Promise.resolve(existing));
+    const updateMaintenance = mock(
+      (arg: { startAt: unknown; endAt: unknown }) => {
+        received = arg;
+        return Promise.resolve({ ...existing });
+      },
+    );
+    const rpcClient = fakeRpcClient({ getMaintenance, updateMaintenance });
+    const tool = createMaintenanceUpdateTool();
+    const parsed = tool.input.parse({
+      id: "m1",
+      startAt: "2026-07-02T10:00:00.000Z",
+      endAt: "2026-07-02T12:00:00.000Z",
+    });
+    await tool.execute({ input: parsed, principal, rpcClient });
+    expect(received?.startAt instanceof Date).toBe(true);
+    expect(received?.endAt instanceof Date).toBe(true);
+  });
+});

package/src/ai/maintenance-update.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  MaintenanceApi,
+  UpdateMaintenanceInputSchema,
+  maintenanceAccess,
+  pluginMetadata,
+  type MaintenanceWithSystems,
+} from "@checkstack/maintenance-common";
+import { computeFieldDiff, type AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+
+/**
+ * Tool-local update schema. The exported `UpdateMaintenanceInputSchema` types
+ * `startAt` / `endAt` as `z.date()`, but the model sends ISO strings, so we
+ * `.extend` it to coerce just those two fields to `Date` while leaving every
+ * other (already-correct) field as published. The exported schema is NOT mutated.
+ */
+export const MaintenanceUpdateInputSchema = UpdateMaintenanceInputSchema.extend({
+  startAt: z.coerce.date().optional(),
+  endAt: z.coerce.date().optional(),
+});
+export type MaintenanceUpdateInput = z.infer<typeof MaintenanceUpdateInputSchema>;
+
+/** Output returned once a human applies the update (the updated maintenance). */
+export interface MaintenanceUpdateApplyResult {
+  maintenance: MaintenanceWithSystems;
+}
+
+/** Fields a `maintenance.update` can change - used to build the before/after diff. */
+const UPDATABLE_FIELDS = [
+  "title",
+  "description",
+  "suppressNotifications",
+  "startAt",
+  "endAt",
+  "systemIds",
+] as const;
+
+/**
+ * `maintenance.update` - change an existing maintenance window by id with a
+ * partial body (only provided fields change).
+ *
+ * `effect: "mutate"` - a non-destructive change, so it auto-applies in AUTO mode
+ * and is confirm-gated in APPROVE mode. `dryRun` fetches the live maintenance,
+ * throws a clear error if it does not exist, and renders a before/after field
+ * diff over the updatable subset so the confirm card shows exactly what changes.
+ */
+export function createMaintenanceUpdateTool(): RegisteredAiTool<
+  MaintenanceUpdateInput,
+  MaintenanceUpdateApplyResult
+> {
+  const dryRun = async ({
+    input,
+    rpcClient,
+  }: {
+    input: MaintenanceUpdateInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<MaintenanceUpdateInput>> => {
+    const maintenanceClient = rpcClient.forPlugin(MaintenanceApi);
+    const existing = await maintenanceClient.getMaintenance({ id: input.id });
+    if (!existing) {
+      throw new Error(
+        `No maintenance found with id "${input.id}". List maintenances first to get a valid id.`,
+      );
+    }
+
+    // before -> after diff over the updatable subset only (the fetched detail
+    // also carries id/status/timestamps/updates/links that are not updatable).
+    const before: Record<string, unknown> = {};
+    const after: Record<string, unknown> = {};
+    for (const field of UPDATABLE_FIELDS) {
+      before[field] = existing[field];
+      after[field] = field in input ? input[field] : existing[field];
+    }
+    const diff = computeFieldDiff({ before, after });
+
+    return {
+      summary: `Update maintenance "${existing.title}".`,
+      payload: input,
+      diff,
+    };
+  };
+
+  return {
+    name: "maintenance.update",
+    description:
+      "Update an existing maintenance window by id with a partial body (only provided fields change). Provide startAt/endAt as ISO 8601 timestamps if changing them. Never updates directly; a person must approve unless the conversation is in auto mode. Find the id with the maintenance read tools first.",
+    effect: "mutate",
+    input: MaintenanceUpdateInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(pluginMetadata, maintenanceAccess.maintenance.manage),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const maintenanceClient = rpcClient.forPlugin(MaintenanceApi);
+      const maintenance = await maintenanceClient.updateMaintenance(input);
+      return { maintenance };
+    },
+  };
+}

package/src/ai/maintenance.projection.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import {
+  buildProjectedTool,
+  deferredProjectionExecute,
+} from "@checkstack/ai-backend";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import {
+  maintenanceContract,
+  maintenanceAccess,
+  pluginMetadata,
+} from "@checkstack/maintenance-common";
+
+// Build the projected tools with the SAME inputs the plugin exposes via
+// aiToolProjectionExtensionPoint in `index.ts`, and assert each carries the
+// source procedure's OWN contract access rules - NOT the chat transport's
+// `ai.chat.read` gate.
+describe("maintenance AI projections", () => {
+  const expectedRule = qualifyAccessRuleId(
+    pluginMetadata,
+    maintenanceAccess.maintenance.read,
+  );
+
+  test("maintenance.list is a read-only tool with the read rule", () => {
+    const tool = buildProjectedTool({
+      procedure: maintenanceContract.listMaintenances,
+      sourcePluginMetadata: pluginMetadata,
+      procedureKey: "listMaintenances",
+      name: "maintenance.list",
+      description:
+        "List planned maintenance windows with optional status/system filters. Read-only.",
+      effect: "read",
+      execute: deferredProjectionExecute,
+    });
+    expect(tool.name).toBe("maintenance.list");
+    expect(tool.effect).toBe("read");
+    expect(tool.requiredAccessRules).toEqual([expectedRule]);
+    expect(tool.requiredAccessRules).not.toEqual(["ai.chat.read"]);
+  });
+
+  test("maintenance.get is a read-only tool with the read rule", () => {
+    const tool = buildProjectedTool({
+      procedure: maintenanceContract.getMaintenance,
+      sourcePluginMetadata: pluginMetadata,
+      procedureKey: "getMaintenance",
+      name: "maintenance.get",
+      description:
+        "Get one maintenance window with its updates and links. Read-only.",
+      effect: "read",
+      execute: deferredProjectionExecute,
+    });
+    expect(tool.name).toBe("maintenance.get");
+    expect(tool.effect).toBe("read");
+    expect(tool.requiredAccessRules).toEqual([expectedRule]);
+    expect(tool.requiredAccessRules).not.toEqual(["ai.chat.read"]);
+  });
+});

package/src/ai/register-ai-tools.ts

@@ -0,0 +1,33 @@
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+import { createMaintenanceCreateTool } from "./maintenance-create";
+import { createMaintenanceUpdateTool } from "./maintenance-update";
+import { createMaintenanceDeleteTool } from "./maintenance-delete";
+import { createMaintenanceAddUpdateTool } from "./maintenance-add-update";
+import { createMaintenanceCloseTool } from "./maintenance-close";
+import { createMaintenanceAddLinkTool } from "./maintenance-add-link";
+import { createMaintenanceRemoveLinkTool } from "./maintenance-remove-link";
+
+/**
+ * The maintenance plugin's AI tools, registered into the AI registry via
+ * `aiToolExtensionPoint` from this plugin's own init - NOT centralized in
+ * ai-backend. This is the canonical pattern any plugin (first- or third-party)
+ * uses to contribute AI tools without ai-backend depending on it.
+ *
+ * create/update/addUpdate/close/addLink are `mutate` (auto-applies in AUTO mode,
+ * confirm-gated in APPROVE mode); delete/removeLink are `destructive` (always
+ * confirm-gated). They all go through the USER-SCOPED client passed at call time,
+ * so handler-side authorization (access rules AND per-resource/team scoping) is
+ * enforced exactly as a direct UI/RPC call; the resolver gate + the
+ * propose/apply re-check are the additional authorization authority.
+ */
+export function buildMaintenanceAiTools(): RegisteredAiTool[] {
+  return [
+    createMaintenanceCreateTool(),
+    createMaintenanceUpdateTool(),
+    createMaintenanceDeleteTool(),
+    createMaintenanceAddUpdateTool(),
+    createMaintenanceCloseTool(),
+    createMaintenanceAddLinkTool(),
+    createMaintenanceRemoveLinkTool(),
+  ];
+}

package/src/automations.test.ts

@@ -8,7 +8,7 @@
  * maintenance id and `apply` returns the §10.2 entity shape.
  */
 import { describe, expect, it, mock } from "bun:test";
-import type { Logger } from "@checkstack/backend-api";
+import type { Logger, RpcClient } from "@checkstack/backend-api";
 import type {
   EntityHandle,
   EntityMutationOpts,
@@ -32,6 +32,7 @@ const ctxBase = {
   getService: async <T,>(): Promise<T> => {
     throw new Error("not used");
   },
+  rpcClient: { forPlugin: () => ({}) } as unknown as RpcClient,
 };
 
 interface RecordedMutate {

package/src/index.ts

@@ -12,6 +12,12 @@ import {
 } from "@checkstack/maintenance-common";
 
 import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
+import {
+  aiToolExtensionPoint,
+  aiToolProjectionExtensionPoint,
+  deferredProjectionExecute,
+} from "@checkstack/ai-backend";
+import { buildMaintenanceAiTools } from "./ai/register-ai-tools";
 import {
   automationActionExtensionPoint,
   automationArtifactTypeExtensionPoint,
@@ -170,6 +176,44 @@ export default createBackendPlugin({
         );
         rpc.registerRouter(router, maintenanceContract);
 
+        // Register this plugin's AI tools (create/update/delete/addUpdate/
+        // close/addLink/removeLink) into the AI registry via the extension
+        // point - owned here, not in ai-backend.
+        const aiToolExt = env.getExtensionPoint(aiToolExtensionPoint);
+        for (const tool of buildMaintenanceAiTools()) {
+          aiToolExt.registerTool(tool, pluginMetadata);
+        }
+
+        // Expose this plugin's OWN read-only AI projections of the existing
+        // list/get queries via aiToolProjectionExtensionPoint - owned here,
+        // not in ai-backend. The projected read tools are routed by the
+        // transport (MCP / chat) AS the principal, so each procedure's own
+        // contract access rules gate it; `deferredProjectionExecute` is the
+        // fail-closed net if a transport ever forgot to route.
+        const aiProjectionExt = env.getExtensionPoint(
+          aiToolProjectionExtensionPoint,
+        );
+        aiProjectionExt.expose({
+          procedure: maintenanceContract.listMaintenances,
+          sourcePluginMetadata: pluginMetadata,
+          procedureKey: "listMaintenances",
+          name: "maintenance.list",
+          description:
+            "List planned maintenance windows with optional status/system filters. Read-only.",
+          effect: "read",
+          execute: deferredProjectionExecute,
+        });
+        aiProjectionExt.expose({
+          procedure: maintenanceContract.getMaintenance,
+          sourcePluginMetadata: pluginMetadata,
+          procedureKey: "getMaintenance",
+          name: "maintenance.get",
+          description:
+            "Get one maintenance window with its updates and links. Read-only.",
+          effect: "read",
+          execute: deferredProjectionExecute,
+        });
+
         // Register "Create Maintenance" command in the command palette
         registerSearchProvider({
           pluginMetadata,

package/src/schema.ts

@@ -5,6 +5,7 @@ import {
   timestamp,
   primaryKey,
   boolean,
+  uniqueIndex,
 } from "drizzle-orm/pg-core";
 
 /**
@@ -68,12 +69,21 @@ export const maintenanceUpdates = pgTable("maintenance_updates", {
  * Hotlinks attached to a maintenance — e.g. a change ticket, runbook, or
  * chat thread. Free-form URL + optional human label.
  */
-export const maintenanceLinks = pgTable("maintenance_links", {
-  id: text("id").primaryKey(),
-  maintenanceId: text("maintenance_id")
-    .notNull()
-    .references(() => maintenances.id, { onDelete: "cascade" }),
-  label: text("label"),
-  url: text("url").notNull(),
-  createdAt: timestamp("created_at").defaultNow().notNull(),
-});
+export const maintenanceLinks = pgTable(
+  "maintenance_links",
+  {
+    id: text("id").primaryKey(),
+    maintenanceId: text("maintenance_id")
+      .notNull()
+      .references(() => maintenances.id, { onDelete: "cascade" }),
+    label: text("label"),
+    url: text("url").notNull(),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    // The same URL may be attached to a maintenance only once.
+    maintenanceUrlUnique: uniqueIndex(
+      "maintenance_links_maintenance_url_unique",
+    ).on(t.maintenanceId, t.url),
+  }),
+);

package/src/service.ts

@@ -257,23 +257,28 @@ export class MaintenanceService {
     input: CreateMaintenanceInput,
     id: string = generateId(),
   ): Promise<MaintenanceWithSystems> {
-    await this.db.insert(maintenances).values({
-      id,
-      title: input.title,
-      description: input.description,
-      suppressNotifications: input.suppressNotifications ?? false,
-      status: "scheduled",
-      startAt: input.startAt,
-      endAt: input.endAt,
-    });
-
-    // Insert system associations
-    for (const systemId of input.systemIds) {
-      await this.db.insert(maintenanceSystems).values({
-        maintenanceId: id,
-        systemId,
+    // Atomic: the maintenance row and its system associations must commit
+    // together. Without the transaction a failure mid-loop left a committed
+    // maintenance with only some (or none) of its system links.
+    await this.db.transaction(async (tx) => {
+      await tx.insert(maintenances).values({
+        id,
+        title: input.title,
+        description: input.description,
+        suppressNotifications: input.suppressNotifications ?? false,
+        status: "scheduled",
+        startAt: input.startAt,
+        endAt: input.endAt,
       });
-    }
+
+      // Insert system associations
+      for (const systemId of input.systemIds) {
+        await tx.insert(maintenanceSystems).values({
+          maintenanceId: id,
+          systemId,
+        });
+      }
+    });
 
     return (await this.getMaintenance(id))!;
   }
@@ -303,24 +308,29 @@ export class MaintenanceService {
     if (input.startAt !== undefined) updateData.startAt = input.startAt;
     if (input.endAt !== undefined) updateData.endAt = input.endAt;
 
-    await this.db
-      .update(maintenances)
-      .set(updateData)
-      .where(eq(maintenances.id, input.id));
-
-    // Update system associations if provided
-    if (input.systemIds !== undefined) {
-      await this.db
-        .delete(maintenanceSystems)
-        .where(eq(maintenanceSystems.maintenanceId, input.id));
-
-      for (const systemId of input.systemIds) {
-        await this.db.insert(maintenanceSystems).values({
-          maintenanceId: input.id,
-          systemId,
-        });
+    // Atomic: the field update and the delete-then-reinsert of system links must
+    // commit together. Without the transaction a failure after the delete left
+    // the maintenance with ALL system associations wiped.
+    await this.db.transaction(async (tx) => {
+      await tx
+        .update(maintenances)
+        .set(updateData)
+        .where(eq(maintenances.id, input.id));
+
+      // Update system associations if provided
+      if (input.systemIds !== undefined) {
+        await tx
+          .delete(maintenanceSystems)
+          .where(eq(maintenanceSystems.maintenanceId, input.id));
+
+        for (const systemId of input.systemIds) {
+          await tx.insert(maintenanceSystems).values({
+            maintenanceId: input.id,
+            systemId,
+          });
+        }
       }
-    }
+    });
 
     return (await this.getMaintenance(input.id))!;
   }
@@ -334,20 +344,24 @@ export class MaintenanceService {
   ): Promise<MaintenanceUpdate> {
     const id = generateId();
 
-    // If status change is provided, update the maintenance status
-    if (input.statusChange) {
-      await this.db
-        .update(maintenances)
-        .set({ status: input.statusChange, updatedAt: new Date() })
-        .where(eq(maintenances.id, input.maintenanceId));
-    }
+    // Atomic: the status flip and the timeline entry that records it must commit
+    // together (status/timeline divergence otherwise).
+    await this.db.transaction(async (tx) => {
+      // If status change is provided, update the maintenance status
+      if (input.statusChange) {
+        await tx
+          .update(maintenances)
+          .set({ status: input.statusChange, updatedAt: new Date() })
+          .where(eq(maintenances.id, input.maintenanceId));
+      }
 
-    await this.db.insert(maintenanceUpdates).values({
-      id,
-      maintenanceId: input.maintenanceId,
-      message: input.message,
-      statusChange: input.statusChange,
-      createdBy: userId,
+      await tx.insert(maintenanceUpdates).values({
+        id,
+        maintenanceId: input.maintenanceId,
+        message: input.message,
+        statusChange: input.statusChange,
+        createdBy: userId,
+      });
     });
 
     const [update] = await this.db
@@ -377,18 +391,21 @@ export class MaintenanceService {
 
     if (!existing) return undefined;
 
-    await this.db
-      .update(maintenances)
-      .set({ status: "completed", updatedAt: new Date() })
-      .where(eq(maintenances.id, id));
+    // Atomic: mark completed + write the closing timeline entry together.
+    await this.db.transaction(async (tx) => {
+      await tx
+        .update(maintenances)
+        .set({ status: "completed", updatedAt: new Date() })
+        .where(eq(maintenances.id, id));
 
-    // Add update entry
-    await this.db.insert(maintenanceUpdates).values({
-      id: generateId(),
-      maintenanceId: id,
-      message: message ?? "Maintenance completed early",
-      statusChange: "completed",
-      createdBy: userId,
+      // Add update entry
+      await tx.insert(maintenanceUpdates).values({
+        id: generateId(),
+        maintenanceId: id,
+        message: message ?? "Maintenance completed early",
+        statusChange: "completed",
+        createdBy: userId,
+      });
     });
 
     return (await this.getMaintenance(id))!;

package/tsconfig.json

@@ -4,6 +4,12 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../ai-backend"
+    },
+    {
+      "path": "../ai-common"
+    },
     {
       "path": "../auth-common"
     },