@checkstack/healthcheck-backend 1.4.0 → 1.6.0

package/src/ai/healthcheck-delete.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import { createHealthcheckDeleteTool } from "./healthcheck-delete";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["healthcheck.healthcheck.manage"],
+};
+
+const config = {
+  id: "hc1",
+  name: "google-com-http",
+  strategyId: "healthcheck-http.http",
+  config: {},
+  intervalSeconds: 60,
+  paused: false,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+function fakeRpcClient({
+  getConfiguration,
+  deleteConfiguration,
+}: {
+  getConfiguration: ReturnType<typeof mock>;
+  deleteConfiguration: ReturnType<typeof mock>;
+}): RpcClient {
+  return {
+    forPlugin: () => ({ getConfiguration, deleteConfiguration }),
+  } as unknown as RpcClient;
+}
+
+describe("healthcheck.delete tool", () => {
+  test("declares destructive effect + the manage rule", () => {
+    const tool = createHealthcheckDeleteTool();
+    expect(tool.name).toBe("healthcheck.delete");
+    expect(tool.effect).toBe("destructive");
+    expect(tool.requiredAccessRules).toEqual(["healthcheck.healthcheck.manage"]);
+    expect(typeof tool.dryRun).toBe("function");
+  });
+
+  test("dryRun resolves the target and NEVER deletes", async () => {
+    const getConfiguration = mock(() => Promise.resolve(config));
+    const deleteConfiguration = mock(() => Promise.resolve());
+    const rpcClient = fakeRpcClient({ getConfiguration, deleteConfiguration });
+    const tool = createHealthcheckDeleteTool();
+    const preview = await tool.dryRun!({
+      input: { id: "hc1" },
+      principal,
+      rpcClient,
+    });
+    expect(deleteConfiguration).not.toHaveBeenCalled();
+    expect(preview.summary).toContain("google-com-http");
+    expect(preview.summary).toContain("permanent");
+    expect(preview.payload).toEqual({ id: "hc1" });
+  });
+
+  test("dryRun throws a clear error when the id is unknown", async () => {
+    const rpcClient = fakeRpcClient({
+      getConfiguration: mock(() => Promise.resolve(undefined)),
+      deleteConfiguration: mock(),
+    });
+    const tool = createHealthcheckDeleteTool();
+    await expect(
+      tool.dryRun!({ input: { id: "nope" }, principal, rpcClient }),
+    ).rejects.toThrow(/No health check found/);
+  });
+
+  test("execute (apply) deletes via deleteConfiguration", async () => {
+    const deleteConfiguration = mock(() => Promise.resolve());
+    const rpcClient = fakeRpcClient({
+      getConfiguration: mock(() => Promise.resolve(config)),
+      deleteConfiguration,
+    });
+    const tool = createHealthcheckDeleteTool();
+    const result = await tool.execute({ input: { id: "hc1" }, principal, rpcClient });
+    expect(deleteConfiguration).toHaveBeenCalledWith("hc1");
+    expect(result).toEqual({ id: "hc1", deleted: true });
+  });
+});

package/src/ai/healthcheck-delete.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { RpcClient, AuthUser } from "@checkstack/backend-api";
+import {
+  HealthCheckApi,
+  healthCheckAccess,
+  pluginMetadata as healthcheckPluginMetadata,
+} from "@checkstack/healthcheck-common";
+import type { AiProposalPreview } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "@checkstack/ai-backend";
+
+/** Input for `healthcheck.delete`: the configuration id to remove. */
+export const HealthcheckDeleteInputSchema = z.object({
+  id: z.string().min(1),
+});
+export type HealthcheckDeleteInput = z.infer<typeof HealthcheckDeleteInputSchema>;
+
+/** Output returned once a human applies the deletion. */
+export interface HealthcheckDeleteApplyResult {
+  id: string;
+  deleted: true;
+}
+
+/**
+ * `healthcheck.delete` - delete a health-check configuration by id.
+ *
+ * `effect: "destructive"` - deletion is irreversible, so it ALWAYS routes
+ * through the propose/apply confirm card in BOTH permission modes (it can never
+ * auto-apply). `dryRun` resolves the target config so the confirm card names
+ * exactly what will be removed; `execute` (reached only via `apply`) performs
+ * the delete. Authorization is the same `configuration.manage` rule the UI
+ * delete requires, re-checked at propose AND apply time by the propose/apply
+ * service. The underlying RPC calls use 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.
+ */
+export function createHealthcheckDeleteTool(): RegisteredAiTool<
+  HealthcheckDeleteInput,
+  HealthcheckDeleteApplyResult
+> {
+  const dryRun = async ({
+    input,
+    rpcClient,
+  }: {
+    input: HealthcheckDeleteInput;
+    principal: AuthUser;
+    rpcClient: RpcClient;
+  }): Promise<AiProposalPreview<HealthcheckDeleteInput>> => {
+    const healthcheckClient = rpcClient.forPlugin(HealthCheckApi);
+    const config = await healthcheckClient.getConfiguration({ id: input.id });
+    if (!config) {
+      throw new Error(
+        `No health check found with id "${input.id}". List health checks first to get a valid id.`,
+      );
+    }
+    return {
+      summary: `Delete health check "${config.name}" (strategy ${config.strategyId}). This is permanent and also removes its system assignments.`,
+      payload: { id: input.id },
+    };
+  };
+
+  return {
+    name: "healthcheck.delete",
+    description:
+      "Delete a health-check configuration by id. DESTRUCTIVE and irreversible - it also removes the check's system assignments. Never deletes directly; a person must approve the confirmation. Find the id with the health-check read tools first.",
+    effect: "destructive",
+    input: HealthcheckDeleteInputSchema,
+    requiredAccessRules: [
+      qualifyAccessRuleId(
+        healthcheckPluginMetadata,
+        healthCheckAccess.configuration.manage,
+      ),
+    ],
+    dryRun,
+    async execute({ input, rpcClient }) {
+      const healthcheckClient = rpcClient.forPlugin(HealthCheckApi);
+      await healthcheckClient.deleteConfiguration(input.id);
+      return { id: input.id, deleted: true };
+    },
+  };
+}

package/src/ai/healthcheck-projection.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import {
+  buildProjectedTool,
+  deferredProjectionExecute,
+} from "@checkstack/ai-backend";
+import { healthCheckContract, pluginMetadata } from "@checkstack/healthcheck-common";
+
+// Build the projected tool with the SAME inputs the plugin exposes via
+// aiToolProjectionExtensionPoint in `index.ts`, and assert the resulting tool
+// carries the source procedure's contract access rules - NOT the chat
+// transport's `ai.chat.read` gate.
+describe("healthcheck.status projection", () => {
+  const tool = buildProjectedTool({
+    procedure: healthCheckContract.getConfigurations,
+    sourcePluginMetadata: pluginMetadata,
+    procedureKey: "getConfigurations",
+    name: "healthcheck.status",
+    description:
+      "List health-check configurations and their current status. Read-only.",
+    effect: "read",
+    execute: deferredProjectionExecute,
+  });
+
+  test("uses the overridden tool name", () => {
+    expect(tool.name).toBe("healthcheck.status");
+  });
+
+  test("is classified as a read-only effect", () => {
+    expect(tool.effect).toBe("read");
+  });
+
+  test("inherits the source procedure's access rules, not the chat gate", () => {
+    expect(tool.requiredAccessRules.length).toBeGreaterThan(0);
+    expect(tool.requiredAccessRules).not.toEqual(["ai.chat.read"]);
+  });
+});

package/src/ai/healthcheck-propose.test.ts

@@ -0,0 +1,268 @@
+import { describe, expect, test, mock } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import {
+  createHealthcheckProposeTool,
+  extractCollectorScriptSource,
+} from "./healthcheck-propose";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["healthcheck.healthcheck.manage"],
+};
+
+const httpStrategy = {
+  id: "healthcheck-http.http",
+  displayName: "HTTP",
+  description: "HTTP probe",
+  category: "network",
+  configSchema: {
+    type: "object",
+    properties: { url: { type: "string" }, method: { type: "string" } },
+    required: ["url"],
+  },
+};
+
+const scriptCollector = {
+  id: "script.inline",
+  displayName: "Inline script",
+  description: "Inline TS collector",
+  configSchema: {
+    type: "object",
+    properties: { script: { type: "string" } },
+    required: ["script"],
+  },
+  resultSchema: {},
+  allowMultiple: true,
+};
+
+/** Default fake `validateConfiguration` that reports the draft as valid. */
+const okValidate = () => mock(() => Promise.resolve({ valid: true, errors: [] }));
+
+function fakeRpcClient({
+  getStrategies,
+  getCollectors,
+  createConfiguration,
+  validateConfiguration,
+}: {
+  getStrategies: ReturnType<typeof mock>;
+  getCollectors: ReturnType<typeof mock>;
+  createConfiguration: ReturnType<typeof mock>;
+  validateConfiguration?: ReturnType<typeof mock>;
+}): RpcClient {
+  return {
+    forPlugin: () => ({
+      getStrategies,
+      getCollectors,
+      createConfiguration,
+      validateConfiguration: validateConfiguration ?? okValidate(),
+    }),
+  } as unknown as RpcClient;
+}
+
+const validInput = {
+  name: "Probe foo status",
+  strategyId: "healthcheck-http.http",
+  config: { url: "https://foo.bar/status" },
+  intervalSeconds: 60,
+};
+
+describe("extractCollectorScriptSource", () => {
+  test("reads script or source string", () => {
+    expect(extractCollectorScriptSource({ script: "code" })).toBe("code");
+    expect(extractCollectorScriptSource({ source: "code2" })).toBe("code2");
+    expect(extractCollectorScriptSource({ other: 1 })).toBeUndefined();
+  });
+});
+
+describe("healthcheck.propose composite tool", () => {
+  test("declares mutate effect + a SINGLE healthcheck manage rule", () => {
+    const tool = createHealthcheckProposeTool();
+    expect(tool.name).toBe("healthcheck.propose");
+    expect(tool.effect).toBe("mutate");
+    expect(tool.requiredAccessRules).toEqual([
+      "healthcheck.healthcheck.manage",
+    ]);
+    // A single rule keeps the framework's AND-gate correct.
+    expect(tool.requiredAccessRules).toHaveLength(1);
+    expect(typeof tool.dryRun).toBe("function");
+  });
+
+  test("dryRun deep-validates via validateConfiguration and NEVER creates", async () => {
+    const validateConfiguration = okValidate();
+    const getStrategies = mock(() => Promise.resolve([httpStrategy]));
+    const getCollectors = mock(() => Promise.resolve([]));
+    const createConfiguration = mock(() => Promise.resolve({}));
+    const rpcClient = fakeRpcClient({
+      getStrategies,
+      getCollectors,
+      createConfiguration,
+      validateConfiguration,
+    });
+    const tool = createHealthcheckProposeTool();
+
+    const preview = await tool.dryRun!({
+      input: validInput,
+      principal,
+      rpcClient,
+    });
+
+    // Deep validation runs against the live registry path, not a hand-rolled
+    // presence check.
+    expect(validateConfiguration).toHaveBeenCalledTimes(1);
+    // The AI never silently creates a health check: create is NOT called at propose.
+    expect(createConfiguration).not.toHaveBeenCalled();
+    expect(preview.summary).toContain("Probe foo status");
+    expect(preview.summary).toContain("HTTP");
+    expect(preview.summary).toContain("60s");
+    const payload = preview.payload as { name: string; yaml: string };
+    expect(payload.name).toBe("Probe foo status");
+    expect(payload.yaml).toContain("strategyId:");
+  });
+
+  test("dryRun describes a script collector on the confirm card", async () => {
+    const getStrategies = mock(() => Promise.resolve([httpStrategy]));
+    const getCollectors = mock(() => Promise.resolve([scriptCollector]));
+    const rpcClient = fakeRpcClient({
+      getStrategies,
+      getCollectors,
+      createConfiguration: mock(),
+    });
+    const tool = createHealthcheckProposeTool();
+
+    const preview = await tool.dryRun!({
+      input: {
+        ...validInput,
+        collectors: [
+          {
+            id: "c1",
+            collectorId: "script.inline",
+            config: { script: "export default defineHealthCheck(() => ({}))" },
+          },
+        ],
+      },
+      principal,
+      rpcClient,
+    });
+
+    expect(getCollectors).toHaveBeenCalledTimes(1);
+    expect(preview.summary).toContain("script collector");
+    expect(preview.summary).toContain("1 collector");
+  });
+
+  test("dryRun surfaces an unknown-strategy error from validateConfiguration", async () => {
+    const validateConfiguration = mock(() =>
+      Promise.resolve({
+        valid: false,
+        errors: [
+          {
+            path: ["strategyId"],
+            message: 'Unknown health-check strategy "nope.nope".',
+          },
+        ],
+      }),
+    );
+    const rpcClient = fakeRpcClient({
+      getStrategies: mock(() => Promise.resolve([httpStrategy])),
+      getCollectors: mock(() => Promise.resolve([])),
+      createConfiguration: mock(),
+      validateConfiguration,
+    });
+    const tool = createHealthcheckProposeTool();
+
+    await expect(
+      tool.dryRun!({
+        input: { ...validInput, strategyId: "nope.nope" },
+        principal,
+        rpcClient,
+      }),
+    ).rejects.toThrow(/invalid/i);
+  });
+
+  // The deep-vs-lightweight proof at the propose layer: `url` IS present
+  // (the old presence check would pass), but it holds the WRONG TYPE. The deep
+  // validateConfiguration path rejects it, so dryRun surfaces the error.
+  test("dryRun surfaces a deep type error the old presence check would miss", async () => {
+    const validateConfiguration = mock(() =>
+      Promise.resolve({
+        valid: false,
+        errors: [{ path: ["config", "url"], message: "Expected string" }],
+      }),
+    );
+    const rpcClient = fakeRpcClient({
+      getStrategies: mock(() => Promise.resolve([httpStrategy])),
+      getCollectors: mock(() => Promise.resolve([])),
+      createConfiguration: mock(),
+      validateConfiguration,
+    });
+    const tool = createHealthcheckProposeTool();
+
+    await expect(
+      tool.dryRun!({
+        // `url` present but a number, not a string.
+        input: { ...validInput, config: { url: 12345 } },
+        principal,
+        rpcClient,
+      }),
+    ).rejects.toThrow(/invalid/i);
+    expect(validateConfiguration).toHaveBeenCalledTimes(1);
+  });
+
+  test("dryRun surfaces an unknown-collector error from validateConfiguration", async () => {
+    const validateConfiguration = mock(() =>
+      Promise.resolve({
+        valid: false,
+        errors: [
+          {
+            path: ["collectors", 0, "collectorId"],
+            message: 'Unknown collector "does.not-exist".',
+          },
+        ],
+      }),
+    );
+    const rpcClient = fakeRpcClient({
+      getStrategies: mock(() => Promise.resolve([httpStrategy])),
+      getCollectors: mock(() => Promise.resolve([scriptCollector])),
+      createConfiguration: mock(),
+      validateConfiguration,
+    });
+    const tool = createHealthcheckProposeTool();
+
+    await expect(
+      tool.dryRun!({
+        input: {
+          ...validInput,
+          collectors: [
+            { id: "c1", collectorId: "does.not-exist", config: {} },
+          ],
+        },
+        principal,
+        rpcClient,
+      }),
+    ).rejects.toThrow(/invalid/i);
+  });
+
+  test("execute (apply) creates the configuration via createConfiguration", async () => {
+    const created = {
+      id: "hc1",
+      name: "Probe foo status",
+      strategyId: "healthcheck-http.http",
+      config: { url: "https://foo.bar/status" },
+      intervalSeconds: 60,
+      paused: false,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+    const createConfiguration = mock(() => Promise.resolve(created));
+    const rpcClient = fakeRpcClient({
+      getStrategies: mock(() => Promise.resolve([httpStrategy])),
+      getCollectors: mock(() => Promise.resolve([])),
+      createConfiguration,
+    });
+    const tool = createHealthcheckProposeTool();
+
+    const result = await tool.execute({ input: validInput, principal, rpcClient });
+    expect(createConfiguration).toHaveBeenCalledTimes(1);
+    expect(result.configuration.id).toBe("hc1");
+  });
+});