@checkstack/backend-api 0.17.1 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,103 @@
 # @checkstack/backend-api
 
+## 0.18.0
+
+### Minor Changes
+
+- 6d52276: feat(automation): expose `trigger.actor` so automations can filter on who/what caused an event
+
+  Every platform event now carries an **actor** - the user, application (API
+  client), service (backend-to-backend), or `system` (background /
+  unauthenticated) that caused it - and the automation engine surfaces it to
+  automations as `trigger.actor`. This lets a trigger filter gate on the
+  origin of the event it reacts to:
+
+  ```text
+  {{ trigger.actor.type == "system" }}      # auto-created by the platform
+  {{ trigger.actor.type == "user" }}         # a human
+  {{ trigger.actor.id == "app-deploybot" }}  # a specific application
+  ```
+
+  `trigger.actor` is available on **every** trigger - it is injected by the
+  platform, not declared per trigger - and editor autocomplete + Run Script
+  context types include `trigger.actor.{type,id,name}`.
+
+  How it works:
+
+  - **`@checkstack/common`** adds the canonical `Actor` type / `ActorSchema`
+    and `SYSTEM_ACTOR`.
+  - **`@checkstack/backend-api`** adds `resolveActor(user)` and a
+    `HookEventMeta` envelope. The hook listener / `onHook` signature gains an
+    optional second `meta` argument (additive, backward compatible).
+  - **`@checkstack/backend`** wraps emitted hooks in an envelope so the actor
+    travels with the payload through the distributed queue, unwrapping it
+    before delivery. The RPC emit path captures the authenticated caller;
+    background emits default to the system actor. Raw/legacy queue data is
+    treated as a system-actor payload, so delivery stays backward compatible.
+  - **`@checkstack/automation-backend`** threads the actor into the dispatch
+    scope (`trigger.actor`), available to trigger filters, top-level
+    conditions, and all run templates, and persisted in the run's scope
+    snapshot. Manual runs are attributed to the invoking user.
+  - **`@checkstack/automation-common`** / **`@checkstack/automation-frontend`**
+    expose `trigger.actor` in the editor variable scope and the generated
+    Run Script `context.trigger.actor` types.
+
+  No database migration and no per-trigger schema changes: the actor rides as
+  event-envelope metadata and in the run scope snapshot.
+
+- 35bc682: feat(healthcheck): expose check + system run-context to script collectors
+
+  Script health checks can now read which check and system a run is for.
+  Previously shell scripts got only a curated env whitelist and inline
+  scripts only `context.config`, so a script had no built-in way to know
+  its own check name or the system it was checking.
+
+  - `@checkstack/backend-api`: new `CollectorRunContext` type
+    (`{ check: { id, name, intervalSeconds }, system: { id, name } }`) and
+    an optional `runContext` param on `CollectorStrategy.execute`. Optional,
+    so existing collector implementations are unaffected.
+  - Shell-script collector: injects reserved `CHECKSTACK_CHECK_ID`,
+    `CHECKSTACK_CHECK_NAME`, `CHECKSTACK_CHECK_INTERVAL_SECONDS`,
+    `CHECKSTACK_SYSTEM_ID`, `CHECKSTACK_SYSTEM_NAME` env vars (user-supplied
+    `env` still wins on collision).
+  - Inline-script collector: exposes `context.check` and `context.system`
+    alongside `context.config`; the inline-script editor now types them for
+    autocomplete.
+  - Shell editors (health-check collectors and automation shell actions) now
+    also suggest the user's own `env` (JSON) keys as `$NAME` completions, via
+    the new exported `customShellEnvVars` helper. Keys that aren't valid shell
+    identifiers are omitted.
+  - Fix: the Typefox `CodeEditor` captured a stale `onChange` at editor start,
+    so editing one `DynamicForm` field reverted sibling fields changed since
+    mount (e.g. typing in a shell `script` field wiped an unsaved `env` value,
+    or deleted a sibling automation action added after mount). The change
+    handler now routes through a ref to the current `onChange`.
+  - Fix: focusing a JSON editor threw "LanguageStatusService.addStatus is not
+    supported" because the standalone service set omitted `ILanguageStatusService`.
+    That one service is now registered via `serviceOverrides`.
+  - Fix: the automation trigger card nested a `<Badge>` (a `<div>`) inside a
+    `<p>`, producing a `validateDOMNesting` warning. Switched the wrapper to a
+    `<div>`.
+  - Local runs (`queue-executor`) and satellite runs both populate the
+    context. `SatelliteAssignment` (and the `getAssignmentsForSatellite`
+    RPC output) gained optional `configName` / `systemName` so the metadata
+    reaches satellite-side execution; `HealthCheckService` resolves the
+    system name via the catalog client.
+
+  BREAKING CHANGE: `createHealthCheckRouter` now requires a `catalogClient`
+  option (used to resolve system names for satellite assignments). Update
+  call sites to pass the catalog RPC client.
+
+### Patch Changes
+
+- Updated dependencies [6d52276]
+- Updated dependencies [35bc682]
+  - @checkstack/common@0.12.0
+  - @checkstack/healthcheck-common@1.3.0
+  - @checkstack/signal-common@0.2.5
+  - @checkstack/cache-api@0.3.6
+  - @checkstack/queue-api@0.3.6
+
 ## 0.17.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend-api",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "./src/index.ts",
@@ -11,9 +11,9 @@
   },
   "dependencies": {
     "@checkstack/common": "0.11.0",
-    "@checkstack/healthcheck-common": "1.1.2",
-    "@checkstack/cache-api": "0.3.4",
-    "@checkstack/queue-api": "0.3.4",
+    "@checkstack/healthcheck-common": "1.2.0",
+    "@checkstack/cache-api": "0.3.5",
+    "@checkstack/queue-api": "0.3.5",
     "@checkstack/signal-common": "0.2.4",
     "@orpc/client": "^1.13.14",
     "@orpc/contract": "^1.13.14",

package/src/actor.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from "bun:test";
+import { SYSTEM_ACTOR } from "@checkstack/common";
+import { resolveActor } from "./actor";
+
+describe("resolveActor", () => {
+  it("falls back to the system actor when there is no caller", () => {
+    expect(resolveActor(undefined)).toEqual(SYSTEM_ACTOR);
+  });
+
+  it("maps a real (human) user", () => {
+    expect(
+      resolveActor({ type: "user", id: "user-1", name: "Nico" }),
+    ).toEqual({ type: "user", id: "user-1", name: "Nico" });
+  });
+
+  it("maps an application (API client)", () => {
+    expect(
+      resolveActor({ type: "application", id: "app-deploybot", name: "Deploy Bot" }),
+    ).toEqual({ type: "application", id: "app-deploybot", name: "Deploy Bot" });
+  });
+
+  it("maps a service to its originating plugin id", () => {
+    expect(resolveActor({ type: "service", pluginId: "healthcheck" })).toEqual({
+      type: "service",
+      id: "healthcheck",
+      name: "healthcheck",
+    });
+  });
+});

package/src/actor.ts

@@ -0,0 +1,27 @@
+import { SYSTEM_ACTOR, type Actor } from "@checkstack/common";
+import type { AuthUser } from "./types";
+
+/**
+ * Resolve the canonical platform {@link Actor} for an event from the
+ * authenticated caller. Background / unauthenticated emits (no `user`)
+ * resolve to the system actor, so every emitted event carries an actor.
+ *
+ * - {@link RealUser}        -> `{ type: "user" }`
+ * - {@link ApplicationUser} -> `{ type: "application" }`
+ * - {@link ServiceUser}     -> `{ type: "service", id: pluginId }`
+ * - `undefined`             -> {@link SYSTEM_ACTOR}
+ */
+export function resolveActor(user?: AuthUser): Actor {
+  if (!user) return SYSTEM_ACTOR;
+  switch (user.type) {
+    case "user": {
+      return { type: "user", id: user.id, name: user.name };
+    }
+    case "application": {
+      return { type: "application", id: user.id, name: user.name };
+    }
+    case "service": {
+      return { type: "service", id: user.pluginId, name: user.pluginId };
+    }
+  }
+}

package/src/collector-strategy.ts

@@ -17,6 +17,15 @@ export interface CollectorResult<TResult> {
   error?: string;
 }
 
+/**
+ * Curated, read-only metadata about the health check + system a collector
+ * run is for. Metadata only - never secrets/config.
+ */
+export interface CollectorRunContext {
+  check: { id: string; name: string; intervalSeconds: number };
+  system: { id: string; name: string };
+}
+
 /**
  * Generic collector strategy interface.
  *
@@ -71,12 +80,15 @@ export interface CollectorStrategy<
    * @param params.config - Validated collector configuration
    * @param params.client - Connected transport client
    * @param params.pluginId - ID of the transport strategy invoking this collector
+   * @param params.runContext - Curated, read-only metadata about the health
+   *   check + system this run is for (metadata only, never secrets/config)
    * @returns Collector result with typed metadata
    */
   execute(params: {
     config: TConfig;
     client: TClient;
     pluginId: string;
+    runContext?: CollectorRunContext;
   }): Promise<CollectorResult<TResult>>;
 
   /**

package/src/event-bus-types.ts

@@ -1,4 +1,9 @@
-import type { Hook, HookSubscribeOptions, HookUnsubscribe } from "./hooks";
+import type {
+  Hook,
+  HookEventMeta,
+  HookSubscribeOptions,
+  HookUnsubscribe,
+} from "./hooks";
 
 /**
  * EventBus interface for dependency injection
@@ -7,22 +12,26 @@ export interface EventBus {
   subscribe<T>(
     pluginId: string,
     hook: Hook<T>,
-    listener: (payload: T) => Promise<void>,
+    listener: (payload: T, meta?: HookEventMeta) => Promise<void>,
     options?: HookSubscribeOptions
   ): Promise<HookUnsubscribe>;
 
   /**
    * Emit a hook through the distributed queue system.
    * All instances receive broadcast hooks; one instance handles work-queue hooks.
+   *
+   * `meta` carries event-envelope metadata (the acting `actor`). When omitted,
+   * the bus defaults to the system actor, so every emitted hook carries an
+   * actor even when emitted from a background/unauthenticated context.
    */
-  emit<T>(hook: Hook<T>, payload: T): Promise<void>;
+  emit<T>(hook: Hook<T>, payload: T, meta?: HookEventMeta): Promise<void>;
 
   /**
    * Emit a hook locally only (not distributed).
    * Use for instance-local hooks that should only run on THIS instance.
    * Uses Promise.allSettled to ensure one listener error doesn't block others.
    */
-  emitLocal<T>(hook: Hook<T>, payload: T): Promise<void>;
+  emitLocal<T>(hook: Hook<T>, payload: T, meta?: HookEventMeta): Promise<void>;
 
   shutdown(): Promise<void>;
 }

package/src/hooks.ts

@@ -1,4 +1,4 @@
-import type { AccessRule } from "@checkstack/common";
+import type { AccessRule, Actor } from "@checkstack/common";
 
 /**
  * Hook definition for type-safe event emission and subscription
@@ -8,6 +8,19 @@ export interface Hook<T = unknown> {
   _type?: T; // Phantom type for TypeScript inference
 }
 
+/**
+ * Envelope metadata that travels alongside every emitted hook payload,
+ * independent of the hook's typed payload. Injected centrally at emit time
+ * (from the request context, defaulting to the system actor) and delivered to
+ * subscribers as the optional second listener argument.
+ *
+ * The automation engine reads `actor` and exposes it to automations as
+ * `trigger.actor`, so a trigger filter can gate on who/what caused the event.
+ */
+export interface HookEventMeta {
+  actor: Actor;
+}
+
 /**
  * Create a typed hook
  */

package/src/index.ts

@@ -17,6 +17,7 @@ export * from "./rpc";
 export * from "./test-utils";
 export * from "./hooks";
 export * from "./event-bus-types";
+export * from "./actor";
 export * from "./plugin-source";
 export * from "./plugin-artifact-store";
 export * from "./notification-strategy";

package/src/plugin-system.ts

@@ -2,7 +2,12 @@ import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { ServiceRef } from "./service-ref";
 import { ExtensionPoint } from "./extension-point";
 import type { AccessRule, PluginMetadata } from "@checkstack/common";
-import type { Hook, HookSubscribeOptions, HookUnsubscribe } from "./hooks";
+import type {
+  Hook,
+  HookEventMeta,
+  HookSubscribeOptions,
+  HookUnsubscribe,
+} from "./hooks";
 import { Router } from "@orpc/server";
 import { RpcContext } from "./rpc";
 import { AnyContractRouter } from "@orpc/contract";
@@ -48,7 +53,7 @@ export type AfterPluginsReadyContext = {
    */
   onHook: <T>(
     hook: Hook<T>,
-    listener: (payload: T) => Promise<void>,
+    listener: (payload: T, meta?: HookEventMeta) => Promise<void>,
     options?: HookSubscribeOptions,
   ) => HookUnsubscribe;
   /**