@checkstack/automation-backend 0.2.0 → 0.3.0

package/src/entity/with-entity-write.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared driven-write/remove guard for PLUGIN-BACKED (Model B) entities.
+ *
+ * Every plugin-backed domain (incident, catalog, dependency, maintenance, slo,
+ * satellite) drives its reactive-state writes through the same tiny guard:
+ *
+ *   - no handle wired (tests construct the router without one, or before the
+ *     entity is defined) → run the plugin write (`apply`) directly; reactivity
+ *     is layered on top and is never required for the underlying write to
+ *     succeed, and
+ *   - handle wired → route through `handle.mutate` / `handle.remove` so the
+ *     framework snapshots `prev`, appends the transition log, and emits
+ *     `ENTITY_CHANGED`.
+ *
+ * The only thing that varied between the per-domain copies was the id-key name
+ * (`incidentId`, `dependencyId`, …); the guard itself is identical. Domains
+ * keep their thin, well-named wrappers (`writeIncidentEntity`, …) but delegate
+ * the guard here so the branch lives in exactly one place.
+ *
+ * NOTE: `writeHealthEntity` (healthcheck-backend) is deliberately NOT built on
+ * this helper — it is genuinely bespoke (closure-captured durable state,
+ * distinct rethrow-vs-fail-soft branches, a per-system serializer, and it
+ * returns the computed state). Do not force-fit it here.
+ */
+import type { EntityHandle, EntityMutationOpts } from "./define-entity";
+
+/**
+ * Drive a reactive-state write through `handle.mutate`, falling back to a plain
+ * `apply()` when no handle is wired. `apply` performs the plugin's REAL write
+ * (its own db/tx) and returns the new reactive state; the framework snapshots
+ * `prev`, appends the transition log, and emits `ENTITY_CHANGED`.
+ */
+export async function withEntityWrite<
+  TState extends Record<string, unknown>,
+>(args: {
+  handle: EntityHandle<TState> | undefined;
+  id: string;
+  opts?: EntityMutationOpts;
+  apply: () => Promise<TState>;
+}): Promise<void> {
+  const { handle, id, opts, apply } = args;
+  if (!handle) {
+    await apply();
+    return;
+  }
+  await handle.mutate({ id, opts, apply });
+}
+
+/**
+ * Drive a tombstone through `handle.remove`, falling back to a plain `apply()`
+ * when no handle is wired. `apply` performs the plugin's REAL delete (its own
+ * db/tx); the framework records the tombstone transition and emits a tombstone
+ * `ENTITY_CHANGED`.
+ */
+export async function withEntityRemove<
+  TState extends Record<string, unknown>,
+>(args: {
+  handle: EntityHandle<TState> | undefined;
+  id: string;
+  opts?: EntityMutationOpts;
+  apply: () => Promise<void>;
+}): Promise<void> {
+  const { handle, id, opts, apply } = args;
+  if (!handle) {
+    await apply();
+    return;
+  }
+  await handle.remove({ id, opts, apply });
+}

package/src/entity-driven-trigger.ts

@@ -0,0 +1,46 @@
+/**
+ * Helper for ENTITY-DRIVEN triggers (reactive automation engine Phase 4).
+ *
+ * A domain that migrated its state to a `defineEntity` no longer emits a
+ * cross-plugin lifecycle hook — the entity's change event drives dispatch
+ * through Stage-1 routing (the registered `registerChangeDeriver` maps a
+ * change to the qualified trigger event id). The trigger is therefore fired
+ * neither by a `hook` subscription nor by a `setup` listener; it is fired by
+ * the deriver matching the automation definition's `trigger.event` string
+ * (via `findEnabledByTriggerEvent`).
+ *
+ * The trigger still needs to REGISTER (for the editor's trigger catalog +
+ * payload introspection), and the trigger registry requires exactly one of
+ * `hook` / `setup`. This provides a no-op `setup` so an entity-driven
+ * trigger registers cleanly without re-introducing a hook. The setup
+ * subscribes to nothing and tears down nothing — the deriver does the work.
+ */
+import type { TriggerSetupFn, TriggerTeardown } from "./action-types";
+
+/** No-op teardown — an entity-driven trigger has no listener to remove. */
+const noopTeardown: TriggerTeardown = async () => {
+  // Fired by the entity change deriver; nothing to tear down.
+};
+
+/**
+ * The single, payload-agnostic entity-driven `setup`: subscribes to nothing
+ * and returns the no-op teardown. The trigger actually fires via its
+ * registered change deriver (Stage-1 routing), not this setup.
+ */
+async function entityDrivenSetup(): Promise<TriggerTeardown> {
+  return noopTeardown;
+}
+
+/**
+ * Return the entity-driven no-op `setup`, typed for the specific trigger
+ * payload/config it is assigned to. `setup` is contravariant in its payload,
+ * so a single shared `unknown`-typed value won't assign to a concrete
+ * `TriggerDefinition<TPayload>.setup`; this factory re-types the one shared
+ * implementation for each call site without per-trigger allocation churn.
+ */
+export function makeEntityDrivenTriggerSetup<
+  TPayload,
+  TConfig = void,
+>(): TriggerSetupFn<TPayload, TConfig> {
+  return entityDrivenSetup;
+}

package/src/extension-points.ts

@@ -3,6 +3,7 @@ import {
   createServiceRef,
 } from "@checkstack/backend-api";
 import type { PluginMetadata } from "@checkstack/common";
+import type { Filter } from "@checkstack/template-engine";
 import type {
   ActionDefinition,
   ArtifactTypeDefinition,
@@ -61,6 +62,40 @@ export const automationArtifactTypeExtensionPoint =
     "automation.artifactTypeExtensionPoint",
   );
 
+/**
+ * A plugin-contributed template filter. Filters MUST be pure and
+ * synchronous (no I/O, no async, no DB) — the template engine evaluates
+ * them inline during condition/value rendering. `description` and
+ * `signature` feed the editor's autocomplete catalogue.
+ */
+export interface FilterDefinition {
+  /** Pipe name, e.g. `older_than`. Used as `{{ value | older_than(...) }}`. */
+  name: string;
+  /** The pure transform. First arg is the piped value. */
+  filter: Filter;
+  /** One-line description for the autocomplete catalogue. */
+  description?: string;
+  /** Human-readable call signature, e.g. `older_than(thresholdMs)`. */
+  signature?: string;
+}
+
+/**
+ * Extension point for registering pure template filters. Lets plugins
+ * contribute domain-specific transforms (e.g. a duration or unit helper)
+ * without forking the template engine's default registry.
+ */
+export interface AutomationFilterExtensionPoint {
+  registerFilter(
+    definition: FilterDefinition,
+    pluginMetadata: PluginMetadata,
+  ): void;
+}
+
+export const automationFilterExtensionPoint =
+  createExtensionPoint<AutomationFilterExtensionPoint>(
+    "automation.filterExtensionPoint",
+  );
+
 // ─── Service refs ─────────────────────────────────────────────────────────
 
 /**

package/src/gitops-docs.test.ts

@@ -0,0 +1,215 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { z } from "zod";
+import { createHook, Versioned } from "@checkstack/backend-api";
+import { CHECKSTACK_API_VERSION } from "@checkstack/gitops-common";
+import type { SpecSchemaDocumentationProvider } from "@checkstack/gitops-common";
+import { createTriggerRegistry } from "./trigger-registry";
+import { createActionRegistry } from "./action-registry";
+import {
+  buildAutomationSpecSchemaDocumentation,
+  registerAutomationGitOpsDocumentation,
+} from "./gitops-docs";
+
+const testPlugin = { pluginId: "test-plugin" } as const;
+
+/**
+ * Stub kind registry capturing the registered doc PROVIDER. The eager
+ * registration methods throw if hit, proving the docs path only registers a
+ * lazy provider.
+ */
+function createCapturingKindRegistry() {
+  const providers: SpecSchemaDocumentationProvider[] = [];
+  return {
+    providers,
+    registry: {
+      registerKind: () => {
+        throw new Error("registerKind should not be called by docs");
+      },
+      registerKindExtension: () => {
+        throw new Error("registerKindExtension should not be called by docs");
+      },
+      registerSpecSchemaDocumentation: () => {
+        throw new Error(
+          "registerSpecSchemaDocumentation (eager) should not be called by docs",
+        );
+      },
+      registerSpecSchemaDocumentationProvider: (
+        provider: SpecSchemaDocumentationProvider,
+      ) => {
+        providers.push(provider);
+      },
+    },
+  };
+}
+
+describe("buildAutomationSpecSchemaDocumentation", () => {
+  let triggerRegistry: ReturnType<typeof createTriggerRegistry>;
+  let actionRegistry: ReturnType<typeof createActionRegistry>;
+
+  beforeEach(() => {
+    triggerRegistry = createTriggerRegistry();
+    actionRegistry = createActionRegistry();
+  });
+
+  it("emits triggers[].config docs only for triggers with a configSchema", () => {
+    // Setup-backed trigger WITH config schema.
+    triggerRegistry.register(
+      {
+        id: "time.cron",
+        displayName: "Cron",
+        description: "Runs on a cron schedule.",
+        payloadSchema: z.object({ scheduledAt: z.string() }),
+        configSchema: z.object({ pattern: z.string() }),
+        setup: async () => async () => {},
+      },
+      testPlugin,
+    );
+    // Hook-backed trigger WITHOUT config schema — should be skipped.
+    triggerRegistry.register(
+      {
+        id: "incident.created",
+        displayName: "Incident Created",
+        payloadSchema: z.object({ incidentId: z.string() }),
+        hook: createHook<{ incidentId: string }>("incident.created"),
+      },
+      testPlugin,
+    );
+
+    const docs = buildAutomationSpecSchemaDocumentation({
+      triggerRegistry,
+      actionRegistry,
+    });
+
+    const triggerDocs = docs.filter((c) => c.fieldPath === "triggers[].config");
+    expect(triggerDocs.length).toBe(1);
+
+    const cron = triggerDocs[0];
+    expect(cron?.kind).toBe("Automation");
+    expect(cron?.apiVersion).toBe(CHECKSTACK_API_VERSION);
+    expect(cron?.variantId).toBe("test-plugin.time.cron");
+    expect(cron?.label).toBe("Cron");
+    expect(cron?.description).toContain("ID: test-plugin.time.cron");
+    expect(cron?.description).toContain("Runs on a cron schedule.");
+    expect(cron?.schema).toBe(
+      triggerRegistry.getTrigger("test-plugin.time.cron")!.configSchema!,
+    );
+    // No conditions: the trigger config is a standalone variant the kind
+    // browser surfaces directly (mirrors Healthcheck's primary `config`).
+    expect(cron?.conditions).toBeUndefined();
+  });
+
+  it("emits actions[].config docs for each registered provider action", () => {
+    const jiraConfig = z.object({ projectKey: z.string() });
+    actionRegistry.register(
+      {
+        id: "jira.create_issue",
+        displayName: "Create Jira issue",
+        description: "Creates a Jira issue.",
+        config: new Versioned({ version: 1, schema: jiraConfig }),
+        execute: async () => ({ success: true }),
+      },
+      testPlugin,
+    );
+
+    const docs = buildAutomationSpecSchemaDocumentation({
+      triggerRegistry,
+      actionRegistry,
+    });
+
+    const actionDocs = docs.filter((c) => c.fieldPath === "actions[].config");
+    expect(actionDocs.length).toBe(1);
+
+    const jira = actionDocs[0];
+    expect(jira?.kind).toBe("Automation");
+    expect(jira?.apiVersion).toBe(CHECKSTACK_API_VERSION);
+    expect(jira?.variantId).toBe("test-plugin.jira.create_issue");
+    expect(jira?.label).toBe("Create Jira issue");
+    expect(jira?.description).toContain("ID: test-plugin.jira.create_issue");
+    expect(jira?.description).toContain("Creates a Jira issue.");
+    expect(jira?.schema).toBe(jiraConfig);
+    // No conditions: each provider action is a standalone variant in the
+    // kind browser's single `actions[].config` dropdown.
+    expect(jira?.conditions).toBeUndefined();
+  });
+
+  it("falls back to just the ID when a registration has no description", () => {
+    actionRegistry.register(
+      {
+        id: "noop",
+        displayName: "No-op",
+        config: new Versioned({ version: 1, schema: z.object({}) }),
+        execute: async () => ({ success: true }),
+      },
+      testPlugin,
+    );
+
+    const docs = buildAutomationSpecSchemaDocumentation({
+      triggerRegistry,
+      actionRegistry,
+    });
+
+    const doc = docs.find((c) => c.variantId === "test-plugin.noop");
+    expect(doc?.description).toBe("ID: test-plugin.noop");
+  });
+
+  it("emits nothing when both registries are empty", () => {
+    const docs = buildAutomationSpecSchemaDocumentation({
+      triggerRegistry,
+      actionRegistry,
+    });
+    expect(docs.length).toBe(0);
+  });
+});
+
+describe("registerAutomationGitOpsDocumentation", () => {
+  let triggerRegistry: ReturnType<typeof createTriggerRegistry>;
+  let actionRegistry: ReturnType<typeof createActionRegistry>;
+
+  beforeEach(() => {
+    triggerRegistry = createTriggerRegistry();
+    actionRegistry = createActionRegistry();
+  });
+
+  it("registers a LAZY provider (not eager entries)", () => {
+    const { providers, registry } = createCapturingKindRegistry();
+    registerAutomationGitOpsDocumentation({
+      kindRegistry: registry,
+      triggerRegistry,
+      actionRegistry,
+    });
+    expect(providers.length).toBe(1);
+  });
+
+  it("provider reflects actions registered AFTER it was registered (order-independent)", () => {
+    const { providers, registry } = createCapturingKindRegistry();
+
+    // Register the provider while the registries are still empty — this is
+    // the real-world race: automation registers docs before other plugins
+    // contribute their provider actions.
+    registerAutomationGitOpsDocumentation({
+      kindRegistry: registry,
+      triggerRegistry,
+      actionRegistry,
+    });
+
+    // Provider invoked now (empty) returns nothing.
+    expect(providers[0]!().length).toBe(0);
+
+    // A later plugin registers its action.
+    actionRegistry.register(
+      {
+        id: "late.action",
+        displayName: "Late Action",
+        config: new Versioned({ version: 1, schema: z.object({}) }),
+        execute: async () => ({ success: true }),
+      },
+      testPlugin,
+    );
+
+    // Re-invoking the SAME provider now surfaces the late action.
+    const later = providers[0]!();
+    expect(later.length).toBe(1);
+    expect(later[0]?.variantId).toBe("test-plugin.late.action");
+    expect(later[0]?.fieldPath).toBe("actions[].config");
+  });
+});

package/src/gitops-docs.ts

@@ -0,0 +1,151 @@
+/**
+ * GitOps spec-schema documentation for the `Automation` kind.
+ *
+ * Mirrors `registerHealthcheckGitOpsDocumentation` in healthcheck-backend:
+ * the `Automation` spec (`AutomationDefinitionSchema`) has two polymorphic,
+ * user-facing field paths whose concrete shape depends on a sibling
+ * discriminator value:
+ *
+ *   - `triggers[].config` is polymorphic on `triggers[].event` — each
+ *     registered trigger declares its own `configSchema`.
+ *   - `actions[].config` is polymorphic on `actions[].action` — each
+ *     registered provider action declares its own config schema.
+ *
+ * For every registered trigger/action we emit one standalone documentation
+ * entry (a variant keyed by the trigger/action id, with NO `conditions`), so
+ * the kind browser renders one variant dropdown per field - exactly the way
+ * Healthcheck surfaces its primary `config` (strategy) field. We deliberately
+ * do NOT condition these on `triggers[].event` / `actions[].action`: those
+ * discriminators have no variant-selector group of their own in the kind
+ * browser, so a condition referencing them would never be satisfied and the
+ * whole "Additional Schemas" section would render empty.
+ *
+ * IMPORTANT — why this uses a LAZY provider, not eager registration:
+ * unlike Healthcheck (whose strategy/collector registries are CORE SERVICES
+ * fully populated before any plugin's `afterPluginsReady`), the automation
+ * trigger/action registries are filled by OTHER plugins across their
+ * `init` / `afterPluginsReady` phases, which have NO guaranteed ordering
+ * relative to automation's `afterPluginsReady`. Several plugins
+ * (catalog/maintenance/notification) register their provider actions in
+ * THEIR `afterPluginsReady`, so a one-shot eager registration at automation's
+ * `afterPluginsReady` would snapshot a half-populated (often empty) registry.
+ * Registering a provider thunk instead means the kind registry re-reads the
+ * registries when the kind-browser RPC is queried, so the docs always reflect
+ * the fully-populated registries regardless of registration order.
+ */
+import type {
+  EntityKindRegistry,
+  SpecSchemaDocumentation,
+} from "@checkstack/gitops-common";
+import { CHECKSTACK_API_VERSION } from "@checkstack/gitops-common";
+import type { TriggerRegistry } from "./trigger-registry";
+import type { ActionRegistry } from "./action-registry";
+
+/** A documentation entry as accepted by the kind registry. */
+type AutomationDoc = {
+  apiVersion: string;
+  kind: string;
+} & SpecSchemaDocumentation;
+
+/**
+ * Compose a doc description for a registered variant: the fully-qualified id
+ * (so operators can copy the exact `event` / `action` value into YAML)
+ * followed by the registration's own description, when present.
+ */
+function buildDescription({
+  qualifiedId,
+  description,
+}: {
+  qualifiedId: string;
+  description?: string;
+}): string {
+  return description
+    ? `ID: ${qualifiedId}\n\n${description}`
+    : `ID: ${qualifiedId}`;
+}
+
+/**
+ * Build the `Automation` spec-schema documentation entries from the CURRENT
+ * contents of the trigger/action registries. Pure: it only reads the
+ * registries it is handed and returns the entries — no side effects. The
+ * provider registered below calls this at describe time.
+ */
+export function buildAutomationSpecSchemaDocumentation({
+  triggerRegistry,
+  actionRegistry,
+}: {
+  triggerRegistry: TriggerRegistry;
+  actionRegistry: ActionRegistry;
+}): AutomationDoc[] {
+  const docs: AutomationDoc[] = [];
+
+  // 1. Trigger config docs (fieldPath: "triggers[].config").
+  //    A trigger's `config` block is only meaningful when the trigger
+  //    declares a `configSchema` — config-less triggers (most hook-backed
+  //    ones) have no documentable shape, so we skip them. Each entry is a
+  //    standalone variant keyed by the trigger id (no `conditions`): the
+  //    kind browser surfaces one dropdown of triggers, exactly like
+  //    Healthcheck's primary `config` (strategy) field.
+  for (const trigger of triggerRegistry.getTriggers()) {
+    if (!trigger.configSchema) continue;
+
+    docs.push({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "Automation",
+      fieldPath: "triggers[].config",
+      variantId: trigger.qualifiedId,
+      label: trigger.displayName,
+      description: buildDescription({
+        qualifiedId: trigger.qualifiedId,
+        description: trigger.description,
+      }),
+      schema: trigger.configSchema,
+    });
+  }
+
+  // 2. Provider-action config docs (fieldPath: "actions[].config").
+  //    Every registered provider action carries a config schema
+  //    (`action.config.schema`). Block kinds (choose/parallel/repeat/…)
+  //    are structural and documented by the base spec schema, not here.
+  //    Each entry is a standalone variant keyed by the action id (no
+  //    `conditions`) - one dropdown of provider actions in the kind browser.
+  for (const action of actionRegistry.getActions()) {
+    docs.push({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "Automation",
+      fieldPath: "actions[].config",
+      variantId: action.qualifiedId,
+      label: action.displayName,
+      description: buildDescription({
+        qualifiedId: action.qualifiedId,
+        description: action.description,
+      }),
+      schema: action.config.schema,
+    });
+  }
+
+  return docs;
+}
+
+/**
+ * Register a lazy spec-schema documentation provider for the `Automation`
+ * kind. The provider re-reads the trigger/action registries each time the
+ * kind registry is described, so the docs reflect the fully-populated
+ * registries regardless of cross-plugin registration ordering.
+ */
+export function registerAutomationGitOpsDocumentation({
+  kindRegistry,
+  triggerRegistry,
+  actionRegistry,
+}: {
+  kindRegistry: EntityKindRegistry;
+  triggerRegistry: TriggerRegistry;
+  actionRegistry: ActionRegistry;
+}): void {
+  kindRegistry.registerSpecSchemaDocumentationProvider(() =>
+    buildAutomationSpecSchemaDocumentation({
+      triggerRegistry,
+      actionRegistry,
+    }),
+  );
+}