@checkstack/healthcheck-backend 1.4.0 → 1.6.0

package/src/collector-script-test.ts

@@ -29,10 +29,17 @@ import {
 
 export type CollectorScriptTestKind = "typescript" | "shell";
 
-/** Curated check/system metadata a collector script can read. */
+/** Curated check/system/environment metadata a collector script can read. */
 export interface CollectorTestRunContext {
   check?: { id: string; name: string; intervalSeconds: number };
   system?: { id: string; name: string };
+  /**
+   * The resolved environment for the previewed run. `fields` is the
+   * environment's free-form custom metadata. Mirrors the runtime
+   * `CollectorRunContext.environment` so the test panel previews exactly the
+   * `CHECKSTACK_ENV_*` / `context.environment` surface the real run exposes.
+   */
+  environment?: { id: string; name: string; fields: Record<string, unknown> };
 }
 
 export interface CollectorScriptTestInput {
@@ -77,11 +84,42 @@ export interface CollectorScriptTestDeps {
   resolutionRoot?: string;
 }
 
+const CHECKSTACK_ENV_PREFIX = "CHECKSTACK_ENV_";
+
+/**
+ * Derive the `CHECKSTACK_ENV_<KEY>` shell var name for a custom field key.
+ * Mirrors `toEnvFieldShellKey` in `@checkstack/healthcheck-script-backend`
+ * (kept local - we don't import across plugins) so the test panel and the
+ * real run produce identical var names. Splits camelCase, uppercases,
+ * collapses non-alphanumeric runs to `_`, trims leading/trailing `_` using a
+ * ReDoS-safe negative look-behind.
+ */
+function toEnvFieldShellKey(key: string): string {
+  const normalized = key
+    .replaceAll(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .toUpperCase()
+    .replaceAll(/[^A-Z0-9]+/g, "_")
+    .replaceAll(/^_+|(?<!_)_+$/g, "");
+  return `${CHECKSTACK_ENV_PREFIX}${normalized}`;
+}
+
+/** Stringify a custom-field value for a shell env var. */
+function stringifyFieldValue(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+
 /**
  * Map curated run-context metadata to the reserved `CHECKSTACK_*` env vars
- * the shell collector exposes. Mirrors `runContextEnv` in
- * `@checkstack/healthcheck-script-backend` (kept local - we don't import
- * across plugins). Only emits vars for the parts of the context provided.
+ * the shell collector exposes. Mirrors `runContextEnv` /
+ * `buildEnvironmentShellEnv` in `@checkstack/healthcheck-script-backend`
+ * (kept local - we don't import across plugins). Only emits vars for the
+ * parts of the context provided. Custom-field key collisions keep the first
+ * and skip later ones (first-wins, never last-write-wins).
  */
 export function buildShellRunContextEnv(
   runContext: CollectorTestRunContext | undefined,
@@ -98,13 +136,24 @@ export function buildShellRunContextEnv(
     env.CHECKSTACK_SYSTEM_ID = runContext.system.id;
     env.CHECKSTACK_SYSTEM_NAME = runContext.system.name;
   }
+  if (runContext?.environment) {
+    env.CHECKSTACK_ENV_ID = runContext.environment.id;
+    env.CHECKSTACK_ENV_NAME = runContext.environment.name;
+    const claimed = new Set<string>();
+    for (const [key, value] of Object.entries(runContext.environment.fields)) {
+      const shellKey = toEnvFieldShellKey(key);
+      if (shellKey === CHECKSTACK_ENV_PREFIX || claimed.has(shellKey)) continue;
+      env[shellKey] = stringifyFieldValue(value);
+      claimed.add(shellKey);
+    }
+  }
   return env;
 }
 
 /**
  * Build the `globalThis.context` object the inline-script (TS) collector
- * sees: `{ config, check?, system? }`. Matches the runtime collector so a
- * test mirrors production.
+ * sees: `{ config, check?, system?, environment? }`. Matches the runtime
+ * collector so a test mirrors production.
  */
 export function buildCollectorContext(
   input: Pick<CollectorScriptTestInput, "config" | "runContext">,
@@ -113,6 +162,9 @@ export function buildCollectorContext(
     config: input.config ?? {},
     ...(input.runContext?.check ? { check: input.runContext.check } : {}),
     ...(input.runContext?.system ? { system: input.runContext.system } : {}),
+    ...(input.runContext?.environment
+      ? { environment: input.runContext.environment }
+      : {}),
   };
 }
 
@@ -193,7 +245,7 @@ export async function runCollectorScriptTest({
       script: input.script,
       context: buildCollectorContext(input),
       timeoutMs: input.timeoutMs,
-      helperModuleName: "@checkstack/healthcheck",
+      helperModuleName: "@checkstack/sdk/healthcheck",
       helperFunctionName: "defineHealthCheck",
       ...(Object.keys(secretTest.env).length > 0
         ? { env: secretTest.env }

package/src/effective-environments.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from "bun:test";
+import { resolveEffectiveEnvironments } from "./effective-environments";
+import type { Environment } from "@checkstack/catalog-common";
+
+const env = (
+  id: string,
+  name: string,
+  metadata: Record<string, unknown> | null = {},
+): Environment => ({
+  id,
+  name,
+  description: null,
+  systemIds: [],
+  metadata,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+});
+
+describe("resolveEffectiveEnvironments", () => {
+  const membership = [
+    env("prod", "Production", { baseUrl: "https://prod" }),
+    env("staging", "Staging", { baseUrl: "https://staging" }),
+  ];
+
+  it("null selector returns ALL current environments", () => {
+    const result = resolveEffectiveEnvironments({
+      environmentIds: null,
+      membership,
+    });
+    expect(result.map((e) => e.id)).toEqual(["prod", "staging"]);
+    expect(result[0]).toEqual({
+      id: "prod",
+      name: "Production",
+      fields: { baseUrl: "https://prod" },
+    });
+  });
+
+  it("undefined selector behaves like null (all environments)", () => {
+    const result = resolveEffectiveEnvironments({
+      environmentIds: undefined,
+      membership,
+    });
+    expect(result.map((e) => e.id)).toEqual(["prod", "staging"]);
+  });
+
+  it("empty array selector opts out (env-less single run)", () => {
+    const result = resolveEffectiveEnvironments({
+      environmentIds: [],
+      membership,
+    });
+    expect(result).toEqual([]);
+  });
+
+  it("explicit subset returns exactly those, intersected with membership", () => {
+    const result = resolveEffectiveEnvironments({
+      environmentIds: ["staging"],
+      membership,
+    });
+    expect(result.map((e) => e.id)).toEqual(["staging"]);
+  });
+
+  it("preserves membership order regardless of selector order", () => {
+    const result = resolveEffectiveEnvironments({
+      environmentIds: ["staging", "prod"],
+      membership,
+    });
+    expect(result.map((e) => e.id)).toEqual(["prod", "staging"]);
+  });
+
+  it("silently drops explicit ids no longer in membership (stale-ref prune)", () => {
+    const result = resolveEffectiveEnvironments({
+      environmentIds: ["prod", "deleted-env"],
+      membership,
+    });
+    expect(result.map((e) => e.id)).toEqual(["prod"]);
+  });
+
+  it("null metadata becomes empty fields", () => {
+    const result = resolveEffectiveEnvironments({
+      environmentIds: null,
+      membership: [env("e1", "E1", null)],
+    });
+    expect(result[0]?.fields).toEqual({});
+  });
+
+  it("empty membership under null selector yields env-less (empty result)", () => {
+    const result = resolveEffectiveEnvironments({
+      environmentIds: null,
+      membership: [],
+    });
+    expect(result).toEqual([]);
+  });
+});

package/src/effective-environments.ts

@@ -0,0 +1,64 @@
+import type { Environment } from "@checkstack/catalog-common";
+
+/**
+ * The resolved environment a single fanned-out run executes for. A subset of
+ * the catalog `Environment` carrying only the run-relevant fields. `fields`
+ * is the environment's free-form custom metadata (verbatim values) - it is
+ * surfaced to collectors via `CollectorRunContext.environment.fields`
+ * (metadata only, never secrets).
+ */
+export interface EffectiveEnvironment {
+  id: string;
+  name: string;
+  fields: Record<string, unknown>;
+}
+
+/**
+ * Resolve the effective set of environments a (config, system) assignment
+ * fans out into for one tick.
+ *
+ * Semantics (locked, §2/§7.1 of the environments plan):
+ * - `environmentIds === null` => ALL environments the system currently
+ *   belongs to (the `membership` set).
+ * - `environmentIds === []`   => OPT OUT: an empty result, meaning the check
+ *   runs exactly ONCE with no environment in context (env-less run).
+ * - non-empty `environmentIds` => exactly those ids, INTERSECTED with the
+ *   current membership. An explicit id no longer in membership silently
+ *   drops (consistent with stale-ref pruning in the GitOps groups reconcile).
+ *
+ * The caller turns an empty result into a single env-less run (so a fanned
+ * check with no effective environments behaves exactly like the pre-feature
+ * single run). A non-empty result drives one run per environment.
+ *
+ * Membership order is preserved so fan-out order is deterministic.
+ */
+export function resolveEffectiveEnvironments({
+  environmentIds,
+  membership,
+}: {
+  environmentIds: string[] | null | undefined;
+  membership: Environment[];
+}): EffectiveEnvironment[] {
+  const toEffective = (env: Environment): EffectiveEnvironment => ({
+    id: env.id,
+    name: env.name,
+    fields: env.metadata ?? {},
+  });
+
+  // null / undefined => all current environments.
+  if (environmentIds === null || environmentIds === undefined) {
+    return membership.map((env) => toEffective(env));
+  }
+
+  // [] => opt out (env-less single run).
+  if (environmentIds.length === 0) {
+    return [];
+  }
+
+  // Non-empty => explicit subset intersected with current membership,
+  // preserving membership order; stale ids silently drop.
+  const wanted = new Set(environmentIds);
+  return membership
+    .filter((env) => wanted.has(env.id))
+    .map((env) => toEffective(env));
+}

package/src/health-entity-id.ts

@@ -0,0 +1,57 @@
+/**
+ * The `health` reactive entity id-shape (§7.4.1, Phase 3b).
+ *
+ * The reactive engine keys entities by a single opaque string id. The `health`
+ * kind encodes TWO views into that one id space:
+ *
+ *  - **System rollup** — the BARE `"<systemId>"`. Unchanged from the pre-3b
+ *    contract: it is the worst-status rollup across the system's environments
+ *    (and env-less runs). Dashboards, badges, and existing system-level
+ *    automations reference this id and keep working WITHOUT re-authoring.
+ *  - **Per-environment** — `"<systemId>::<environmentId>"` (double-colon
+ *    separator). Catalog `text` ids never contain `::`, so the separator is
+ *    unambiguous. State shape is identical; only the id distinguishes them.
+ *
+ * This module is the SINGLE source of truth for encoding / decoding that id so
+ * the read accessor, the write helper, the change deriver, the payload mapper,
+ * and (read-only) the automation scope enrichment all agree on the shape.
+ */
+
+/** The separator between systemId and environmentId in a per-env entity id. */
+export const HEALTH_ENTITY_ID_SEPARATOR = "::";
+
+/** A decoded `health` entity id. `environmentId === null` ⇒ the system rollup. */
+export interface ParsedHealthEntityId {
+  systemId: string;
+  /** null for the bare system rollup id; the env id for a per-env id. */
+  environmentId: string | null;
+}
+
+/**
+ * Encode a `health` entity id from its parts. A `null`/`undefined`
+ * environmentId yields the bare rollup id `"<systemId>"`; a concrete
+ * environmentId yields `"<systemId>::<environmentId>"`.
+ */
+export function encodeHealthEntityId(args: {
+  systemId: string;
+  environmentId?: string | null;
+}): string {
+  const { systemId, environmentId } = args;
+  if (environmentId === null || environmentId === undefined) return systemId;
+  return `${systemId}${HEALTH_ENTITY_ID_SEPARATOR}${environmentId}`;
+}
+
+/**
+ * Decode a `health` entity id into `(systemId, environmentId)`. An id with no
+ * separator is the system rollup (`environmentId: null`). Splits on the FIRST
+ * separator so a (hypothetical) env id containing `::` still resolves a stable
+ * systemId; catalog ids don't contain `::`, so this is defensive only.
+ */
+export function parseHealthEntityId(id: string): ParsedHealthEntityId {
+  const idx = id.indexOf(HEALTH_ENTITY_ID_SEPARATOR);
+  if (idx === -1) return { systemId: id, environmentId: null };
+  return {
+    systemId: id.slice(0, idx),
+    environmentId: id.slice(idx + HEALTH_ENTITY_ID_SEPARATOR.length),
+  };
+}