@checkstack/healthcheck-script-backend 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @checkstack/healthcheck-script-backend
 
+## 0.5.0
+
+### Minor Changes
+
+- 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/backend-api@0.18.0
+  - @checkstack/healthcheck-common@1.3.0
+
+## 0.4.2
+
+### Patch Changes
+
+- Updated dependencies [ba07ae2]
+  - @checkstack/healthcheck-common@1.2.0
+  - @checkstack/backend-api@0.17.1
+
 ## 0.4.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-script-backend",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -14,15 +14,15 @@
     "pack": "bunx @checkstack/scripts plugin-pack"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.16.0",
-    "@checkstack/common": "0.10.0",
-    "@checkstack/healthcheck-common": "1.1.1"
+    "@checkstack/backend-api": "0.17.1",
+    "@checkstack/common": "0.11.0",
+    "@checkstack/healthcheck-common": "1.2.0"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",
     "typescript": "^5.0.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.2"
+    "@checkstack/scripts": "0.3.3"
   },
   "description": "Checkstack healthcheck-script-backend plugin",
   "author": {

package/src/execute-collector.test.ts

@@ -101,6 +101,66 @@ describe("ExecuteCollector", () => {
         timeout: 3000,
       });
     });
+
+    it("injects run-context metadata into the script env", async () => {
+      const collector = new ExecuteCollector();
+      const client = createMockClient();
+
+      await collector.execute({
+        config: { script: "echo hi", timeout: 3000 },
+        client,
+        pluginId: "test",
+        runContext: {
+          check: { id: "check-1", name: "CPU load", intervalSeconds: 60 },
+          system: { id: "system-9", name: "web-01" },
+        },
+      });
+
+      const call = (client.exec as ReturnType<typeof mock>).mock.calls[0][0];
+      expect(call.env.CHECKSTACK_CHECK_ID).toBe("check-1");
+      expect(call.env.CHECKSTACK_CHECK_NAME).toBe("CPU load");
+      expect(call.env.CHECKSTACK_CHECK_INTERVAL_SECONDS).toBe("60");
+      expect(call.env.CHECKSTACK_SYSTEM_ID).toBe("system-9");
+      expect(call.env.CHECKSTACK_SYSTEM_NAME).toBe("web-01");
+    });
+
+    it("lets a user config.env key win over a metadata key on collision", async () => {
+      const collector = new ExecuteCollector();
+      const client = createMockClient();
+
+      await collector.execute({
+        config: {
+          script: "echo hi",
+          env: { CHECKSTACK_CHECK_NAME: "user override" },
+          timeout: 3000,
+        },
+        client,
+        pluginId: "test",
+        runContext: {
+          check: { id: "check-1", name: "metadata name", intervalSeconds: 60 },
+          system: { id: "system-9", name: "web-01" },
+        },
+      });
+
+      const call = (client.exec as ReturnType<typeof mock>).mock.calls[0][0];
+      expect(call.env.CHECKSTACK_CHECK_NAME).toBe("user override");
+      // Non-colliding metadata keys are still present.
+      expect(call.env.CHECKSTACK_SYSTEM_ID).toBe("system-9");
+    });
+
+    it("leaves env unchanged when no runContext is supplied (back-compat)", async () => {
+      const collector = new ExecuteCollector();
+      const client = createMockClient();
+
+      await collector.execute({
+        config: { script: "echo hi", env: { MY_VAR: "value" }, timeout: 3000 },
+        client,
+        pluginId: "test",
+      });
+
+      const call = (client.exec as ReturnType<typeof mock>).mock.calls[0][0];
+      expect(call.env).toEqual({ MY_VAR: "value" });
+    });
   });
 
   describe("migration", () => {

package/src/execute-collector.ts

@@ -11,6 +11,7 @@ import {
   aggregatedAverage,
   aggregatedRate,
   type InferAggregatedResult,
+  type CollectorRunContext,
 } from "@checkstack/backend-api";
 import {
   healthResultNumber,
@@ -21,6 +22,35 @@ import {
 import { pluginMetadata } from "./plugin-metadata";
 import type { ScriptTransportClient } from "./transport-client";
 
+// ============================================================================
+// RUN-CONTEXT ENV INJECTION
+// ============================================================================
+//
+// Reserved env var names exposing curated run-context metadata to the
+// shell script. These mirror the automation `CHECKSTACK_` shell
+// convention; intentionally NOT imported from automation-common to keep
+// this plugin's dependency surface minimal.
+
+const CHECKSTACK_CHECK_ID = "CHECKSTACK_CHECK_ID";
+const CHECKSTACK_CHECK_NAME = "CHECKSTACK_CHECK_NAME";
+const CHECKSTACK_CHECK_INTERVAL_SECONDS = "CHECKSTACK_CHECK_INTERVAL_SECONDS";
+const CHECKSTACK_SYSTEM_ID = "CHECKSTACK_SYSTEM_ID";
+const CHECKSTACK_SYSTEM_NAME = "CHECKSTACK_SYSTEM_NAME";
+
+/**
+ * Map curated run-context metadata to the reserved `CHECKSTACK_*` env
+ * vars exposed to the shell script.
+ */
+function runContextEnv(ctx: CollectorRunContext): Record<string, string> {
+  return {
+    [CHECKSTACK_CHECK_ID]: ctx.check.id,
+    [CHECKSTACK_CHECK_NAME]: ctx.check.name,
+    [CHECKSTACK_CHECK_INTERVAL_SECONDS]: String(ctx.check.intervalSeconds),
+    [CHECKSTACK_SYSTEM_ID]: ctx.system.id,
+    [CHECKSTACK_SYSTEM_NAME]: ctx.system.name,
+  };
+}
+
 // ============================================================================
 // LEGACY CONFIG (v1) — kept for migration
 // ============================================================================
@@ -212,17 +242,26 @@ export class ExecuteCollector implements CollectorStrategy<
   async execute({
     config,
     client,
+    runContext,
   }: {
     config: ExecuteConfig;
     client: ScriptTransportClient;
     pluginId: string;
+    runContext?: CollectorRunContext;
   }): Promise<CollectorResult<ExecuteResult>> {
     const startTime = Date.now();
 
+    // Merge run-context metadata under the user-supplied env so a user
+    // `config.env` key always wins on collision (matches the runner's
+    // existing merge order against the safe-vars whitelist).
+    const env = runContext
+      ? { ...runContextEnv(runContext), ...config.env }
+      : config.env;
+
     const response = await client.exec({
       script: config.script,
       cwd: config.cwd,
-      env: config.env,
+      env,
       timeout: config.timeout,
     });
 

package/src/inline-script-collector.test.ts

@@ -340,6 +340,49 @@ describe("InlineScriptCollector", () => {
     });
   });
 
+  describe("context.runContext", () => {
+    it("exposes run-context metadata as `context.check` / `context.system`", async () => {
+      const config = createConfig({
+        script: `
+          // @ts-ignore — context is injected by the runner
+          export default { success: true, message: \`\${context.system.name}:\${context.check.id}\` };
+        `,
+      });
+
+      const result = await collector.execute({
+        config,
+        client: mockClient,
+        pluginId: "script",
+        runContext: {
+          check: { id: "check-7", name: "CPU load", intervalSeconds: 30 },
+          system: { id: "system-3", name: "web-02" },
+        },
+      });
+
+      expect(result.result.success).toBe(true);
+      expect(result.result.message).toBe("web-02:check-7");
+    });
+
+    it("still exposes `context.config` and does not crash when runContext is absent (back-compat)", async () => {
+      const config = createConfig({
+        script: `
+          // @ts-ignore — context is injected by the runner
+          export default { success: true, value: context.config.timeout, message: typeof context.system };
+        `,
+      });
+
+      const result = await collector.execute({
+        config,
+        client: mockClient,
+        pluginId: "script",
+      });
+
+      expect(result.result.success).toBe(true);
+      expect(result.result.value).toBe(10_000);
+      expect(result.result.message).toBe("undefined");
+    });
+  });
+
   describe("mergeResult", () => {
     it("aggregates execution time and success rate", () => {
       const run1 = {

package/src/inline-script-collector.ts

@@ -14,6 +14,7 @@ import {
   aggregatedAverage,
   aggregatedRate,
   type InferAggregatedResult,
+  type CollectorRunContext,
 } from "@checkstack/backend-api";
 import {
   healthResultNumber,
@@ -56,20 +57,26 @@ export interface InlineScriptExecutor {
     script: string;
     config: Record<string, unknown>;
     timeoutMs: number;
+    runContext?: CollectorRunContext;
   }): Promise<InlineScriptExecutionResult>;
 }
 
 /**
  * Default executor — delegates to the shared `EsmScriptRunner`. Wires
- * `globalThis.context = { config }` (the inline-health-check runtime
- * surface) and the virtual `@checkstack/healthcheck` module / global
- * `defineHealthCheck` helper.
+ * `globalThis.context = { config, check?, system? }` (the inline
+ * health-check runtime surface) and the virtual `@checkstack/healthcheck`
+ * module / global `defineHealthCheck` helper.
  */
 const defaultInlineScriptExecutor: InlineScriptExecutor = {
-  async execute({ script, config, timeoutMs }) {
+  async execute({ script, config, timeoutMs, runContext }) {
     const res: EsmScriptRunResult = await defaultEsmScriptRunner.run({
       script,
-      context: { config },
+      context: {
+        config,
+        ...(runContext
+          ? { check: runContext.check, system: runContext.system }
+          : {}),
+      },
       timeoutMs,
       helperModuleName: "@checkstack/healthcheck",
       helperFunctionName: "defineHealthCheck",
@@ -254,10 +261,12 @@ export class InlineScriptCollector implements CollectorStrategy<
 
   async execute({
     config,
+    runContext,
   }: {
     config: InlineScriptConfig;
     client: ScriptTransportClient;
     pluginId: string;
+    runContext?: CollectorRunContext;
   }): Promise<CollectorResult<InlineScriptResult>> {
     const startTime = Date.now();
 
@@ -267,6 +276,7 @@ export class InlineScriptCollector implements CollectorStrategy<
         script: config.script,
         config: config as unknown as Record<string, unknown>,
         timeoutMs: config.timeout,
+        runContext,
       });
     } catch (error) {
       const executionTimeMs = Date.now() - startTime;