@checkstack/healthcheck-frontend 0.21.0 → 0.23.0

package/src/components/assignments/environment-selector.logic.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "bun:test";
+import {
+  modeFromEnvironmentIds,
+  environmentIdsForMode,
+  toggleEnvironmentId,
+} from "./environment-selector.logic";
+
+describe("modeFromEnvironmentIds", () => {
+  it("null => all", () => {
+    expect(modeFromEnvironmentIds(null)).toBe("all");
+  });
+  it("undefined => all", () => {
+    expect(modeFromEnvironmentIds(undefined)).toBe("all");
+  });
+  it("[] => none", () => {
+    expect(modeFromEnvironmentIds([])).toBe("none");
+  });
+  it("non-empty => specific", () => {
+    expect(modeFromEnvironmentIds(["prod"])).toBe("specific");
+  });
+});
+
+describe("environmentIdsForMode", () => {
+  it("all => null", () => {
+    expect(environmentIdsForMode({ mode: "all", selectedIds: ["x"] })).toBeNull();
+  });
+  it("none => []", () => {
+    expect(environmentIdsForMode({ mode: "none", selectedIds: ["x"] })).toEqual(
+      [],
+    );
+  });
+  it("specific => the selected ids verbatim", () => {
+    expect(
+      environmentIdsForMode({ mode: "specific", selectedIds: ["prod", "qa"] }),
+    ).toEqual(["prod", "qa"]);
+  });
+
+  it("round-trips through modeFromEnvironmentIds for all three modes", () => {
+    expect(
+      modeFromEnvironmentIds(
+        environmentIdsForMode({ mode: "all", selectedIds: [] }),
+      ),
+    ).toBe("all");
+    expect(
+      modeFromEnvironmentIds(
+        environmentIdsForMode({ mode: "none", selectedIds: [] }),
+      ),
+    ).toBe("none");
+    expect(
+      modeFromEnvironmentIds(
+        environmentIdsForMode({ mode: "specific", selectedIds: ["e1"] }),
+      ),
+    ).toBe("specific");
+  });
+});
+
+describe("toggleEnvironmentId", () => {
+  it("adds an id not present, preserving order", () => {
+    expect(
+      toggleEnvironmentId({ selectedIds: ["a"], environmentId: "b" }),
+    ).toEqual(["a", "b"]);
+  });
+  it("removes an id already present", () => {
+    expect(
+      toggleEnvironmentId({ selectedIds: ["a", "b"], environmentId: "a" }),
+    ).toEqual(["b"]);
+  });
+});

package/src/components/assignments/environment-selector.logic.ts

@@ -0,0 +1,69 @@
+/**
+ * Pure, DOM-free logic for the per-assignment environment selector. Kept
+ * separate from the React component so it can be unit-tested in the repo-root
+ * `bun test` run (which has no happy-dom).
+ *
+ * The selector has three modes that map to the `environmentIds` wire value
+ * (semantics locked in the environments plan, §2/§7.1):
+ * - "all"      => `null`  : run for ALL environments the system belongs to.
+ * - "specific" => `string[]` (non-empty): run for exactly those env ids.
+ * - "none"     => `[]`    : opt out, run ONCE with no environment.
+ */
+export type EnvironmentSelectorMode = "all" | "specific" | "none";
+
+/**
+ * Derive the UI mode from the stored `environmentIds` wire value.
+ * `null`/`undefined` = all; `[]` = none; non-empty = specific.
+ */
+export function modeFromEnvironmentIds(
+  environmentIds: string[] | null | undefined,
+): EnvironmentSelectorMode {
+  if (environmentIds === null || environmentIds === undefined) return "all";
+  if (environmentIds.length === 0) return "none";
+  return "specific";
+}
+
+/**
+ * Compute the `environmentIds` wire value to persist for a chosen mode.
+ *
+ * For "specific", `selectedIds` is used verbatim (empty selection under
+ * "specific" is NOT auto-coerced to "none" here — the component keeps the
+ * mode explicit and `selectedIds` empty; callers/UI should require at least
+ * one selection before this is treated as a meaningful "specific" set).
+ */
+export function environmentIdsForMode({
+  mode,
+  selectedIds,
+}: {
+  mode: EnvironmentSelectorMode;
+  selectedIds: string[];
+}): string[] | null {
+  switch (mode) {
+    case "all": {
+      return null;
+    }
+    case "none": {
+      return [];
+    }
+    case "specific": {
+      return selectedIds;
+    }
+  }
+}
+
+/**
+ * Toggle one environment id in a "specific" selection, returning the new
+ * sorted-stable list (membership order is the caller's concern; this just
+ * adds/removes preserving existing order).
+ */
+export function toggleEnvironmentId({
+  selectedIds,
+  environmentId,
+}: {
+  selectedIds: string[];
+  environmentId: string;
+}): string[] {
+  return selectedIds.includes(environmentId)
+    ? selectedIds.filter((id) => id !== environmentId)
+    : [...selectedIds, environmentId];
+}

package/src/components/editor/CollectorScriptTestRenderer.tsx

@@ -0,0 +1,115 @@
+import React from "react";
+import { usePluginClient } from "@checkstack/frontend-api";
+import {
+  ScriptTestPanel,
+  ContextSampleEditor,
+  type ScriptTestRenderer,
+  type ScriptTestPanelResult,
+} from "@checkstack/ui";
+import { HealthCheckApi } from "@checkstack/healthcheck-common";
+import { extractErrorMessage } from "@checkstack/common";
+
+const TIMEOUT_MS = 30_000;
+
+/**
+ * Placeholder check/system metadata for the auto-seeded sample. A test run
+ * has no real check assignment, so we surface stable example values for
+ * `context.check` / `context.system` (and the `$CHECKSTACK_*` shell vars).
+ */
+const SAMPLE_RUN_CONTEXT = {
+  check: { id: "test-check", name: "Test Check", intervalSeconds: 60 },
+  system: { id: "test-system", name: "Test System" },
+};
+
+/**
+ * Build the auto-seeded sample context JSON for a collector script. There
+ * is no healthcheck replay (executions don't persist the script/config),
+ * so the seed is the collector's live config plus placeholder check/system.
+ */
+function seedSample(config: Record<string, unknown>): string {
+  return JSON.stringify(
+    { config, ...SAMPLE_RUN_CONTEXT },
+    null,
+    2,
+  );
+}
+
+interface CollectorScriptTestPanelProps {
+  kind: "typescript" | "shell";
+  script: string;
+  /** Live collector config, used to auto-seed `context.config`. */
+  config: Record<string, unknown>;
+}
+
+const CollectorScriptTestPanel: React.FC<CollectorScriptTestPanelProps> = ({
+  kind,
+  script,
+  config,
+}) => {
+  const client = usePluginClient(HealthCheckApi);
+  const testMutation = client.testCollectorScript.useMutation();
+  const [sampleContext, setSampleContext] = React.useState(() =>
+    seedSample(config),
+  );
+
+  const handleRun = React.useCallback(async (): Promise<ScriptTestPanelResult> => {
+    // Collector config has no `x-secret-env` field, so there are no secret
+    // overrides to forward; the panel passes none.
+    let parsed: {
+      config?: Record<string, unknown>;
+      check?: { id: string; name: string; intervalSeconds: number };
+      system?: { id: string; name: string };
+    } = {};
+    if (sampleContext.trim().length > 0) {
+      try {
+        parsed = JSON.parse(sampleContext) as typeof parsed;
+      } catch (error) {
+        return {
+          stdout: "",
+          stderr: "",
+          durationMs: 0,
+          timedOut: false,
+          error: `Sample context is not valid JSON: ${extractErrorMessage(error)}`,
+        };
+      }
+    }
+    return testMutation.mutateAsync({
+      kind,
+      script,
+      config: parsed.config,
+      runContext: {
+        ...(parsed.check ? { check: parsed.check } : {}),
+        ...(parsed.system ? { system: parsed.system } : {}),
+      },
+      timeoutMs: TIMEOUT_MS,
+    });
+  }, [testMutation, kind, script, sampleContext]);
+
+  return (
+    <ScriptTestPanel
+      onRun={handleRun}
+      disabled={script.trim().length === 0}
+      contextEditor={
+        <ContextSampleEditor value={sampleContext} onChange={setSampleContext} />
+      }
+    />
+  );
+};
+
+/**
+ * Build the {@link ScriptTestRenderer} for the health-check collector
+ * editor. Captures the live collector `config` so the auto-seeded sample
+ * matches what the operator is editing.
+ */
+export function createCollectorScriptTestRenderer(
+  config: Record<string, unknown>,
+): ScriptTestRenderer {
+  return ({ fieldId, kind, script }) => (
+    <CollectorScriptTestPanel
+      key={`${fieldId}-test`}
+      kind={kind}
+      script={script}
+      config={config}
+    />
+  );
+}

package/src/components/editor/CollectorSection.tsx

@@ -10,7 +10,18 @@ import {
   healthcheckScriptContext,
 } from "@checkstack/ui";
 import { Trash2 } from "lucide-react";
+import {
+  useScriptPackageTypeAcquisition,
+  useSdkTypeInjection,
+} from "@checkstack/script-packages-frontend";
+import { useSecretNames } from "@checkstack/secrets-frontend";
+import {
+  EnvironmentPreviewPicker,
+  type Environment,
+} from "@checkstack/catalog-frontend";
 import { AssertionBuilder, type Assertion } from "../AssertionBuilder";
+import { createCollectorScriptTestRenderer } from "./CollectorScriptTestRenderer";
+import { schemaHasTemplatableFields } from "./collector-preview-context.logic";
 
 interface CollectorSectionProps {
   entry: CollectorConfigEntry;
@@ -19,6 +30,21 @@ interface CollectorSectionProps {
   onAssertionsChange: (assertions: CollectorConfigEntry["assertions"]) => void;
   onValidChange: (isValid: boolean) => void;
   onRemove: () => void;
+  /**
+   * Environments offered in the "Preview as" picker (the system's when one is
+   * in context, else all). Empty disables the picker.
+   */
+  previewEnvironments: ReadonlyArray<Environment>;
+  /** Currently selected preview environment id (shared across collectors). */
+  previewEnvironmentId: string | null;
+  /** Called when the author picks (or clears) a preview environment. */
+  onPreviewEnvironmentChange: (environmentId: string | null) => void;
+  /**
+   * Sample context for previewing `x-templatable` fields, built from the
+   * selected environment's custom fields plus curated check/system metadata.
+   * `undefined` when no environment is selected (preview line stays hidden).
+   */
+  templatePreviewContext?: Record<string, unknown>;
 }
 
 export const CollectorSection: React.FC<CollectorSectionProps> = ({
@@ -28,7 +54,25 @@ export const CollectorSection: React.FC<CollectorSectionProps> = ({
   onAssertionsChange,
   onValidChange,
   onRemove,
+  previewEnvironments,
+  previewEnvironmentId,
+  onPreviewEnvironmentChange,
+  templatePreviewContext,
 }) => {
+  const scriptTestRenderer = React.useMemo(
+    () => createCollectorScriptTestRenderer(entry.config),
+    [entry.config],
+  );
+  // Lazy ATA: collector scripts get package IntelliSense (incl. `@types/*`)
+  // on demand for whatever npm packages they import. `importablePackages`
+  // drives import-specifier name completion before any module is registered.
+  const { acquireTypes, acquireResetKey, importablePackages } =
+    useScriptPackageTypeAcquisition();
+  // SDK editor types so `@checkstack/sdk/healthcheck` imports resolve.
+  const { sdkTypes, sdkTypesResetKey } = useSdkTypeInjection();
+  // Secret names (never values) for the secret -> env mapping editor.
+  const { secretNames } = useSecretNames();
+
   return (
     <div className="space-y-6">
       {/* Header */}
@@ -57,23 +101,46 @@ export const CollectorSection: React.FC<CollectorSectionProps> = ({
       {/* Configuration */}
       {collectorDef?.configSchema && (
         <div className="space-y-3">
-          <div>
-            <Label className="text-sm font-semibold">Configuration</Label>
-            <p className="text-xs text-muted-foreground">
-              Configure how this check item behaves.
-            </p>
+          <div className="flex items-start justify-between gap-4">
+            <div>
+              <Label className="text-sm font-semibold">Configuration</Label>
+              <p className="text-xs text-muted-foreground">
+                Configure how this check item behaves.
+              </p>
+            </div>
+            {/* Only offer the preview picker when a templatable field exists. */}
+            {schemaHasTemplatableFields(collectorDef.configSchema) && (
+              <EnvironmentPreviewPicker
+                environments={previewEnvironments}
+                selectedId={previewEnvironmentId}
+                onSelect={onPreviewEnvironmentChange}
+              />
+            )}
           </div>
-          <DynamicForm
-            schema={collectorDef.configSchema}
-            value={entry.config}
-            onChange={onConfigChange}
-            onValidChange={onValidChange}
-            {...healthcheckScriptContext({
+          {(() => {
+            const ctx = healthcheckScriptContext({
               collectorConfigSchema: collectorDef.configSchema,
               // Surface the user's own `env` keys as `$`-completions.
               customEnv: entry.config.env,
-            })}
-          />
+            });
+            return (
+              <DynamicForm
+                schema={collectorDef.configSchema}
+                value={entry.config}
+                onChange={onConfigChange}
+                onValidChange={onValidChange}
+                templatePreviewContext={templatePreviewContext}
+                {...ctx}
+                scriptTestRenderer={scriptTestRenderer}
+                secretNames={secretNames}
+                acquireTypes={acquireTypes}
+                acquireResetKey={acquireResetKey}
+                sdkTypes={sdkTypes}
+                sdkTypesResetKey={sdkTypesResetKey}
+                importablePackages={importablePackages}
+              />
+            );
+          })()}
         </div>
       )}
 

package/src/components/editor/EditorPanel.tsx

@@ -10,6 +10,7 @@ import { CollectorSection } from "./CollectorSection";
 import { CollectorPicker } from "./CollectorPicker";
 import { SystemsSection } from "./SystemsSection";
 import { TeamAccessEditor } from "@checkstack/auth-frontend";
+import type { Environment } from "@checkstack/catalog-frontend";
 
 // =============================================================================
 // TYPES
@@ -49,6 +50,21 @@ interface EditorPanelProps {
   systemsLoading?: boolean;
   selectedSystemIds?: string[];
   onSystemsChange?: (systemIds: string[]) => void;
+  /**
+   * Environments offered in the collector "Preview as" picker (the system's
+   * environments when a single system is in context, else all). Empty hides
+   * the picker.
+   */
+  previewEnvironments?: ReadonlyArray<Environment>;
+  /** Selected preview environment id (shared across collectors). */
+  previewEnvironmentId?: string | null;
+  /** Called when the author picks (or clears) a preview environment. */
+  onPreviewEnvironmentChange?: (environmentId: string | null) => void;
+  /**
+   * Sample context for previewing the selected collector's `x-templatable`
+   * fields, built from the chosen environment. `undefined` when none chosen.
+   */
+  templatePreviewContext?: Record<string, unknown>;
 }
 
 // =============================================================================
@@ -78,6 +94,10 @@ export const EditorPanel: React.FC<EditorPanelProps> = ({
   systemsLoading = false,
   selectedSystemIds = [],
   onSystemsChange,
+  previewEnvironments = [],
+  previewEnvironmentId = null,
+  onPreviewEnvironmentChange,
+  templatePreviewContext,
 }) => {
   // --- General Section ---
   if (selectedNode === "general") {
@@ -180,6 +200,12 @@ export const EditorPanel: React.FC<EditorPanelProps> = ({
           }
           onValidChange={(isValid) => onCollectorValidChange(entryId, isValid)}
           onRemove={() => onCollectorRemove(entryId)}
+          previewEnvironments={previewEnvironments}
+          previewEnvironmentId={previewEnvironmentId}
+          onPreviewEnvironmentChange={(id) =>
+            onPreviewEnvironmentChange?.(id)
+          }
+          templatePreviewContext={templatePreviewContext}
         />
       </div>
     );

package/src/components/editor/collector-preview-context.logic.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from "bun:test";
+import {
+  schemaHasTemplatableFields,
+  buildTemplatePreviewContext,
+} from "./collector-preview-context.logic";
+import type { JsonSchema } from "@checkstack/ui";
+
+describe("schemaHasTemplatableFields", () => {
+  it("returns false for empty/missing schema", () => {
+    expect(schemaHasTemplatableFields(undefined)).toBe(false);
+    expect(schemaHasTemplatableFields(null)).toBe(false);
+    expect(schemaHasTemplatableFields({ type: "object" })).toBe(false);
+    expect(
+      schemaHasTemplatableFields({ type: "object", properties: {} }),
+    ).toBe(false);
+  });
+
+  it("detects a top-level templatable field", () => {
+    const schema: JsonSchema = {
+      type: "object",
+      properties: {
+        url: { type: "string", "x-templatable": true },
+        method: { type: "string" },
+      },
+    };
+    expect(schemaHasTemplatableFields(schema)).toBe(true);
+  });
+
+  it("returns false when no field is templatable", () => {
+    const schema: JsonSchema = {
+      type: "object",
+      properties: {
+        url: { type: "string" },
+        timeout: { type: "number" },
+      },
+    };
+    expect(schemaHasTemplatableFields(schema)).toBe(false);
+  });
+
+  it("detects a nested templatable field in an object property", () => {
+    const schema: JsonSchema = {
+      type: "object",
+      properties: {
+        auth: {
+          type: "object",
+          properties: {
+            token: { type: "string", "x-templatable": true },
+          },
+        },
+      },
+    };
+    expect(schemaHasTemplatableFields(schema)).toBe(true);
+  });
+
+  it("detects a templatable field inside array items", () => {
+    const schema: JsonSchema = {
+      type: "object",
+      properties: {
+        headers: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              value: { type: "string", "x-templatable": true },
+            },
+          },
+        },
+      },
+    };
+    expect(schemaHasTemplatableFields(schema)).toBe(true);
+  });
+});
+
+describe("buildTemplatePreviewContext", () => {
+  it("places environment fields under `environment`", () => {
+    const ctx = buildTemplatePreviewContext({
+      environmentFields: { baseUrl: "https://staging.example.com" },
+    });
+    expect(ctx.environment).toEqual({
+      baseUrl: "https://staging.example.com",
+    });
+  });
+
+  it("defaults check/system to empty objects when absent", () => {
+    const ctx = buildTemplatePreviewContext({ environmentFields: {} });
+    expect(ctx).toEqual({ environment: {}, check: {}, system: {} });
+  });
+
+  it("includes curated check/system metadata when provided", () => {
+    const ctx = buildTemplatePreviewContext({
+      environmentFields: { baseUrl: "https://x" },
+      check: { id: "c1", name: "API health", intervalSeconds: 60 },
+      system: { id: "s1", name: "Payments" },
+    });
+    expect(ctx).toEqual({
+      environment: { baseUrl: "https://x" },
+      check: { id: "c1", name: "API health", intervalSeconds: 60 },
+      system: { id: "s1", name: "Payments" },
+    });
+  });
+});

package/src/components/editor/collector-preview-context.logic.ts

@@ -0,0 +1,88 @@
+/**
+ * DOM-free helpers backing the collector config "preview-as-environment" UX.
+ *
+ * Two concerns, both kept pure so they run in the repo-root `bun test` (no
+ * happy-dom):
+ *
+ * 1. Detect whether a collector's config schema has any `x-templatable` field
+ *    (recursively), so the editor only shows the environment picker when a
+ *    preview would actually be meaningful.
+ * 2. Build the `templatePreviewContext` fed to `DynamicForm` from a chosen
+ *    environment's custom fields plus curated check/system metadata. The shape
+ *    `{ environment, check, system }` mirrors the backend's run-time render
+ *    context exactly (see `queue-executor.ts`), so the preview never diverges
+ *    from what runs.
+ */
+
+import type { JsonSchema, JsonSchemaProperty } from "@checkstack/ui";
+
+/**
+ * True when `schema` (or any nested object/array property) declares at least
+ * one `x-templatable` field. Used to gate the preview picker: no templatable
+ * field means no `{{ … }}` to resolve, so the picker stays hidden.
+ */
+export function schemaHasTemplatableFields(
+  schema: JsonSchema | undefined | null,
+): boolean {
+  if (!schema?.properties) return false;
+  return Object.values(schema.properties).some((property) =>
+    propertyHasTemplatable(property),
+  );
+}
+
+function propertyHasTemplatable(property: JsonSchemaProperty): boolean {
+  if (property["x-templatable"]) return true;
+  if (
+    property.properties &&
+    Object.values(property.properties).some((nested) =>
+      propertyHasTemplatable(nested),
+    )
+  ) {
+    return true;
+  }
+  if (property.items && propertyHasTemplatable(property.items)) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Curated check/system metadata exposed to the preview, matching the run-time
+ * `CollectorRunContext` subset that templating sees. Optional because the
+ * editor may not have a concrete system in context (the author writes a config
+ * that several systems may later use).
+ */
+export interface PreviewCheckMeta {
+  id: string;
+  name: string;
+  intervalSeconds: number;
+}
+
+export interface PreviewSystemMeta {
+  id: string;
+  name: string;
+}
+
+/**
+ * Build the sample `templatePreviewContext` for `DynamicForm`. `environment`
+ * carries the chosen environment's verbatim custom fields (its catalog
+ * `metadata`); `check`/`system` carry curated metadata when available. The
+ * resulting shape `{ environment, check, system }` matches the backend
+ * `templateContext` so `{{ environment.baseUrl }}` previews exactly as it
+ * renders at run time.
+ */
+export function buildTemplatePreviewContext({
+  environmentFields,
+  check,
+  system,
+}: {
+  environmentFields: Record<string, unknown>;
+  check?: PreviewCheckMeta;
+  system?: PreviewSystemMeta;
+}): Record<string, unknown> {
+  return {
+    environment: environmentFields,
+    check: check ?? {},
+    system: system ?? {},
+  };
+}