@checkstack/ui 1.8.2 → 1.9.0

package/src/components/DynamicForm/FormField.tsx

@@ -33,6 +33,9 @@ export const FormField: React.FC<FormFieldProps> = ({
   formValues,
   optionsResolvers,
   templateProperties,
+  typeDefinitions,
+  shellEnvVars,
+  starterTemplates,
   onChange,
 }) => {
   const description = propSchema.description || "";
@@ -129,6 +132,9 @@ export const FormField: React.FC<FormFieldProps> = ({
           isRequired={isRequired}
           editorTypes={editorTypes}
           templateProperties={templateProperties}
+          typeDefinitions={typeDefinitions}
+          shellEnvVars={shellEnvVars}
+          starterTemplates={starterTemplates}
           onChange={onChange as (val: string | undefined) => void}
         />
       );
@@ -346,6 +352,9 @@ export const FormField: React.FC<FormFieldProps> = ({
             formValues={formValues}
             optionsResolvers={optionsResolvers}
             templateProperties={templateProperties}
+            typeDefinitions={typeDefinitions}
+            shellEnvVars={shellEnvVars}
+            starterTemplates={starterTemplates}
             onChange={(val) =>
               onChange({ ...(value as Record<string, unknown>), [key]: val })
             }
@@ -454,6 +463,9 @@ export const FormField: React.FC<FormFieldProps> = ({
                   formValues={formValues}
                   optionsResolvers={optionsResolvers}
                   templateProperties={templateProperties}
+                  typeDefinitions={typeDefinitions}
+                  shellEnvVars={shellEnvVars}
+                  starterTemplates={starterTemplates}
                   onChange={(val) => {
                     const next = [...(items as unknown[])];
                     next[index] = val;
@@ -582,6 +594,9 @@ export const FormField: React.FC<FormFieldProps> = ({
                 formValues={formValues}
                 optionsResolvers={optionsResolvers}
                 templateProperties={templateProperties}
+                typeDefinitions={typeDefinitions}
+                shellEnvVars={shellEnvVars}
+                starterTemplates={starterTemplates}
                 onChange={(val) => onChange({ ...currentValue, [key]: val })}
               />
             ))}

package/src/components/DynamicForm/MultiTypeEditorField.tsx

@@ -17,6 +17,8 @@ import {
   parseFormData,
   EDITOR_TYPE_LABELS,
 } from "./utils";
+import type { EditorStarterTemplates, ShellEnvVar } from "./types";
+import { pickStarterForEmptyField } from "./starterTemplateSelector";
 
 export interface MultiTypeEditorFieldProps {
   /** Unique identifier for the field */
@@ -33,6 +35,25 @@ export interface MultiTypeEditorFieldProps {
   editorTypes: EditorType[];
   /** Optional template properties for autocomplete */
   templateProperties?: TemplateProperty[];
+  /**
+   * Optional TypeScript declarations injected into Monaco for TS/JS modes —
+   * powers IntelliSense + return-shape error reporting against the runtime
+   * context the user will see (`context.config`, `context.event`, ...).
+   */
+  typeDefinitions?: string;
+  /**
+   * Optional shell env-var hints surfaced as completion items after `$`
+   * (and `${`) in shell mode. Typically populated by the platform with
+   * names like `EVENT_ID` / `PAYLOAD_*` so users don't have to memorise.
+   */
+  shellEnvVars?: ShellEnvVar[];
+  /**
+   * Optional starter templates per editor language. When the field is
+   * empty (and the user hasn't typed yet), switching to an editor with a
+   * starter for that language pre-populates the editor so users see a
+   * working example instead of a blank canvas.
+   */
+  starterTemplates?: EditorStarterTemplates;
   /** Callback when value changes */
   onChange: (value: string | undefined) => void;
 }
@@ -50,6 +71,9 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
   isRequired,
   editorTypes,
   templateProperties,
+  typeDefinitions,
+  shellEnvVars,
+  starterTemplates,
   onChange,
 }) => {
   // Detect initial editor type from value
@@ -57,16 +81,81 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
     detectEditorType(value, editorTypes),
   );
 
-  // Track if this is the initial mount to avoid re-detecting on every value change
-  const isInitialMount = React.useRef(true);
+  // Latched once the field has had non-empty content at least once for
+  // this mount. Used by the seed effects below to decide whether to
+  // (re-)install the starter template.
+  const hasSeededRef = React.useRef(false);
+
+  // React reuses this `MultiTypeEditorField` instance across collector
+  // switches when its parent `FormField` keeps the same key (e.g. both
+  // collectors have a property called `script`). The `useState`
+  // initializer above only runs on the first mount, so without this
+  // effect a switch from a shell-only collector to a typescript-only
+  // collector leaves `selectedType` stuck on "shell" — Monaco then
+  // tokenises the new collector's TS content as shell (no
+  // highlighting), and the reverse direction tokenises shell content as
+  // TS (nonsense "Cannot find name" errors).
+  //
+  // Whenever `editorTypes` changes and the current selection is no
+  // longer offered, re-detect from the new value. We deliberately do
+  // NOT reset on every `value` change — that would clobber the user's
+  // manual dropdown choice mid-edit.
   React.useEffect(() => {
-    if (isInitialMount.current) {
-      isInitialMount.current = false;
-      return;
+    if (!editorTypes.includes(selectedType)) {
+      const next = detectEditorType(value, editorTypes);
+      setSelectedType(next);
+      // Reset the seed latch too — this is effectively a fresh field
+      // for a different collector, and the new language's starter
+      // template should be eligible again.
+      hasSeededRef.current = false;
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- intentional: only re-derive when the offered types change
+  }, [editorTypes]);
+
+  // Seed an empty field with the starter template for its detected
+  // language so users see a working example instead of a blank canvas.
+  //
+  // Why this isn't just `useEffect(..., [])`:
+  // React fires CHILD effects before PARENT effects. `DynamicForm`'s
+  // own init effect (which applies schema defaults) runs AFTER this one
+  // and, on initial mount, calls `onChange(defaults)` — which clobbers
+  // a freshly-seeded `script: starter` back to `script: ""` because the
+  // defaults effect's closure-captured `value` was the original `{}`.
+  // A naive `[]`-dep seed would therefore appear to do nothing.
+  //
+  // Two-effect design fixes this without depending on cross-component
+  // effect ordering:
+  //   1. The "observed" effect (declared FIRST) flips `hasSeededRef` to
+  //      true the moment we see non-empty content in `value` — whether
+  //      that came from our seed surviving, a parent default landing
+  //      with content, or the user typing.
+  //   2. The "seed" effect re-runs on every value/starter change and
+  //      installs the starter while `hasSeededRef` is still false. If
+  //      the parent clobbers us back to "", we just re-seed on the
+  //      next pass — until the value sticks and effect (1) latches.
+  //
+  // The latch also means we DON'T re-seed if the user deliberately
+  // deletes their content later, or on any subsequent refetch / parent
+  // re-render: once non-empty has been observed at least once, the
+  // field is the user's territory.
+  React.useEffect(() => {
+    if (!hasSeededRef.current && (value ?? "").trim().length > 0) {
+      hasSeededRef.current = true;
     }
-    // Don't re-detect type when value changes after initial mount
   }, [value]);
 
+  React.useEffect(() => {
+    if (hasSeededRef.current) return;
+    const starter = pickStarterForEmptyField({
+      value,
+      selectedType,
+      starterTemplates,
+    });
+    if (starter !== undefined) {
+      onChange(starter);
+    }
+  }, [value, selectedType, starterTemplates, onChange]);
+
   const handleTypeChange = (newType: EditorType) => {
     setSelectedType(newType);
 
@@ -76,6 +165,19 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
       return;
     }
 
+    // If the field is empty after the switch and we have a starter template
+    // for the new language, seed it. (Switching languages on a non-empty
+    // field preserves the existing content, just like before.)
+    const starter = pickStarterForEmptyField({
+      value,
+      selectedType: newType,
+      starterTemplates,
+    });
+    if (starter !== undefined) {
+      onChange(starter);
+      return;
+    }
+
     // When switching to formdata
     if (newType === "formdata") {
       if (!value || value.trim() === "") {
@@ -242,6 +344,7 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
           language="javascript"
           minHeight="150px"
           templateProperties={templateProperties}
+          typeDefinitions={typeDefinitions}
         />
       )}
 
@@ -253,6 +356,7 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
           language="typescript"
           minHeight="150px"
           templateProperties={templateProperties}
+          typeDefinitions={typeDefinitions}
         />
       )}
 
@@ -264,6 +368,7 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
           language="shell"
           minHeight="150px"
           templateProperties={templateProperties}
+          shellEnvVars={shellEnvVars}
         />
       )}
     </div>

package/src/components/DynamicForm/index.ts

@@ -13,6 +13,8 @@ export type {
   OptionsResolver,
   ResolverOption,
   EditorType,
+  ShellEnvVar,
+  EditorStarterTemplates,
 } from "./types";
 
 // Utility functions

package/src/components/DynamicForm/starterTemplateSelector.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "bun:test";
+import { pickStarterForEmptyField } from "./starterTemplateSelector";
+import type { EditorStarterTemplates } from "./types";
+
+/**
+ * Regression suite for the starter-template seeding behaviour in
+ * `MultiTypeEditorField`.
+ *
+ * The previous implementation gated seeding behind an `isInitialMount`
+ * ref that a sibling effect with `[value]` deps flipped to false BEFORE
+ * the seed effect ran — so seeding silently no-op'd on every mount and
+ * users always saw a blank canvas. The refactored seed effect delegates
+ * to this pure function; testing it here proves the decision is correct
+ * regardless of the React effect ordering trap.
+ */
+
+const STARTERS: EditorStarterTemplates = {
+  typescript: "// starter for TypeScript",
+  shell: "#!/bin/sh\necho starter for shell",
+};
+
+describe("pickStarterForEmptyField", () => {
+  it("returns the starter for the selected language when the field is empty", () => {
+    expect(
+      pickStarterForEmptyField({
+        value: "",
+        selectedType: "typescript",
+        starterTemplates: STARTERS,
+      }),
+    ).toBe(STARTERS.typescript);
+  });
+
+  it("returns the starter when the value is whitespace-only", () => {
+    // The original bug let trailing whitespace block the seed; explicit
+    // coverage so we don't regress.
+    expect(
+      pickStarterForEmptyField({
+        value: "   \n\t  ",
+        selectedType: "typescript",
+        starterTemplates: STARTERS,
+      }),
+    ).toBe(STARTERS.typescript);
+  });
+
+  it("returns undefined when the field already has content (don't clobber)", () => {
+    expect(
+      pickStarterForEmptyField({
+        value: "// user's existing code",
+        selectedType: "typescript",
+        starterTemplates: STARTERS,
+      }),
+    ).toBeUndefined();
+  });
+
+  it("returns undefined when value is undefined and no starter is defined for the selected language", () => {
+    expect(
+      pickStarterForEmptyField({
+        value: undefined,
+        selectedType: "json",
+        starterTemplates: STARTERS,
+      }),
+    ).toBeUndefined();
+  });
+
+  it("returns undefined when no `starterTemplates` are provided at all", () => {
+    expect(
+      pickStarterForEmptyField({
+        value: "",
+        selectedType: "typescript",
+      }),
+    ).toBeUndefined();
+  });
+
+  it("returns the shell starter when shell is selected", () => {
+    expect(
+      pickStarterForEmptyField({
+        value: undefined,
+        selectedType: "shell",
+        starterTemplates: STARTERS,
+      }),
+    ).toBe(STARTERS.shell);
+  });
+
+  it("treats an empty-string starter as 'no starter available'", () => {
+    // We never want to install a literal empty string on top of an
+    // already-empty field; that would just look like the seed silently
+    // did nothing.
+    expect(
+      pickStarterForEmptyField({
+        value: "",
+        selectedType: "typescript",
+        starterTemplates: { typescript: "" },
+      }),
+    ).toBeUndefined();
+  });
+});

package/src/components/DynamicForm/starterTemplateSelector.ts

@@ -0,0 +1,32 @@
+import type { EditorStarterTemplates, EditorType } from "./types";
+
+/**
+ * Pure decision function powering the "seed empty editor with a starter
+ * template" behaviour in `MultiTypeEditorField`. Returns the starter
+ * content to install, or `undefined` if the field shouldn't be touched.
+ *
+ * Used both on first mount and when the user switches editor language on
+ * a still-empty field, so a single source of truth governs both paths
+ * (and a single test suite covers them).
+ *
+ * Returns `undefined` when:
+ *  - the field already has non-whitespace content (don't clobber user input)
+ *  - no `starterTemplates` were provided
+ *  - no starter exists for the currently-selected language
+ *  - the matching starter is the empty string
+ */
+export function pickStarterForEmptyField({
+  value,
+  selectedType,
+  starterTemplates,
+}: {
+  value: string | undefined;
+  selectedType: EditorType;
+  starterTemplates?: EditorStarterTemplates;
+}): string | undefined {
+  const trimmed = (value ?? "").trim();
+  if (trimmed.length > 0) return undefined;
+  const starter = starterTemplates?.[selectedType];
+  if (!starter || starter.length === 0) return undefined;
+  return starter;
+}

package/src/components/DynamicForm/types.ts

@@ -1,8 +1,11 @@
-import type { TemplateProperty } from "../CodeEditor";
+import type { TemplateProperty, ShellEnvVar } from "../CodeEditor";
 import type { EditorType } from "@checkstack/common";
 
 // Re-export types used by multi-type editor
 export type { EditorType } from "./utils";
+// Re-export `ShellEnvVar` so DynamicForm consumers don't have to import
+// from two paths. The canonical definition lives in `../CodeEditor`.
+export type { ShellEnvVar } from "../CodeEditor";
 import type {
   JsonSchemaPropertyCore,
   JsonSchemaBase,
@@ -40,6 +43,13 @@ export type OptionsResolver = (
  */
 export type JsonSchema = JsonSchemaBase<JsonSchemaProperty>;
 
+/**
+ * Default starter templates per editor language. Used to populate empty
+ * multi-type editor fields so users see a working example instead of a
+ * blank canvas. Keyed by `EditorType` (e.g. "typescript", "shell").
+ */
+export type EditorStarterTemplates = Partial<Record<EditorType, string>>;
+
 export interface DynamicFormProps {
   schema: JsonSchema;
   value: Record<string, unknown>;
@@ -59,6 +69,25 @@ export interface DynamicFormProps {
    * When provided, fields with x-editor-types get {{ autocomplete suggestions.
    */
   templateProperties?: TemplateProperty[];
+  /**
+   * Optional TypeScript declarations to inject into Monaco for `typescript`
+   * or `javascript` editor-type fields. Typically built from a schema via
+   * `generateTypeDefinitions()` so users get autocomplete + type errors
+   * against the runtime context they'll see.
+   */
+  typeDefinitions?: string;
+  /**
+   * Optional list of environment-variable names that are available to
+   * `shell` editor-type fields. When provided, Monaco autocompletes them
+   * after `$` and `${`. Use this to surface platform-injected vars like
+   * `EVENT_ID`, `PAYLOAD_*` etc. so users don't have to remember the names.
+   */
+  shellEnvVars?: ShellEnvVar[];
+  /**
+   * Optional initial content per editor language, used to populate empty
+   * fields with a working example. Keyed by `EditorType`.
+   */
+  starterTemplates?: EditorStarterTemplates;
 }
 
 /** Props for the FormField component */
@@ -71,10 +100,14 @@ export interface FormFieldProps {
   formValues: Record<string, unknown>;
   optionsResolvers?: Record<string, OptionsResolver>;
   templateProperties?: TemplateProperty[];
+  typeDefinitions?: string;
+  shellEnvVars?: ShellEnvVar[];
+  starterTemplates?: EditorStarterTemplates;
   /** Callback when value changes. Omit val to clear the field. */
   onChange: (val?: unknown) => void;
 }
 
+
 /** Props for the DynamicOptionsField component */
 export interface DynamicOptionsFieldProps {
   id: string;

package/src/components/LinksEditor.tsx

@@ -10,6 +10,24 @@ export interface HotLink {
   url: string;
 }
 
+// Parse a user-supplied URL and return its canonicalized form ONLY when the
+// scheme is `http:` / `https:`. Returns `undefined` for any other scheme
+// (`javascript:`, `data:`, `vbscript:`, etc.) so callers can refuse to
+// render an anchor at all. The returned string is `URL.toString()` — i.e.
+// a re-serialized URL — so taint analysis sees a fresh, sanitized value
+// rather than the raw input flowing through. CodeQL js/xss-through-dom.
+function safeHref(raw: string): string | undefined {
+  try {
+    const parsed = new URL(raw);
+    if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+      return parsed.toString();
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export interface LinksEditorProps<T extends HotLink> {
   /** Currently attached links. */
   links: T[];
@@ -60,6 +78,11 @@ export function LinksEditor<T extends HotLink>({
       setError("Must be a valid URL (include http:// or https://)");
       return;
     }
+    const parsed = new URL(trimmedUrl);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      setError("Only http:// and https:// URLs are allowed");
+      return;
+    }
     setError(undefined);
     await onAdd({ label: label.trim() || undefined, url: trimmedUrl });
     setLabel("");
@@ -77,42 +100,54 @@ export function LinksEditor<T extends HotLink>({
 
       {links.length > 0 ? (
         <div className="border rounded-lg divide-y">
-          {links.map((link) => (
-            <div
-              key={link.id}
-              className="flex items-center justify-between p-3 gap-2"
-            >
-              <div className="flex items-center gap-2 min-w-0 flex-1">
-                <ExternalLink className="h-4 w-4 text-muted-foreground shrink-0" />
-                <div className="min-w-0">
-                  <a
-                    href={link.url}
-                    target="_blank"
-                    rel="noopener noreferrer"
-                    className="text-sm text-primary hover:underline truncate block"
-                  >
-                    {link.label ?? link.url}
-                  </a>
-                  {link.label && (
-                    <span className="text-xs text-muted-foreground truncate block">
-                      {link.url}
-                    </span>
-                  )}
+          {links.map((link) => {
+            const href = safeHref(link.url);
+            return (
+              <div
+                key={link.id}
+                className="flex items-center justify-between p-3 gap-2"
+              >
+                <div className="flex items-center gap-2 min-w-0 flex-1">
+                  <ExternalLink className="h-4 w-4 text-muted-foreground shrink-0" />
+                  <div className="min-w-0">
+                    {href ? (
+                      <a
+                        href={href}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        className="text-sm text-primary hover:underline truncate block"
+                      >
+                        {link.label ?? link.url}
+                      </a>
+                    ) : (
+                      <span
+                        className="text-sm text-muted-foreground truncate block"
+                        title="Unsafe URL scheme — link disabled"
+                      >
+                        {link.label ?? link.url}
+                      </span>
+                    )}
+                    {link.label && (
+                      <span className="text-xs text-muted-foreground truncate block">
+                        {link.url}
+                      </span>
+                    )}
+                  </div>
                 </div>
+                {canManage && (
+                  <Button
+                    variant="ghost"
+                    size="sm"
+                    onClick={() => void onRemove(link)}
+                    disabled={busy}
+                    aria-label="Remove link"
+                  >
+                    <Trash2 className="h-4 w-4" />
+                  </Button>
+                )}
               </div>
-              {canManage && (
-                <Button
-                  variant="ghost"
-                  size="sm"
-                  onClick={() => void onRemove(link)}
-                  disabled={busy}
-                  aria-label="Remove link"
-                >
-                  <Trash2 className="h-4 w-4" />
-                </Button>
-              )}
-            </div>
-          ))}
+            );
+          })}
         </div>
       ) : (
         <p className="text-sm text-muted-foreground">No links attached</p>

package/src/hooks/useInitOnceForKey.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "bun:test";
+import { shouldInitForKey } from "./useInitOnceForKey";
+
+/**
+ * Regression suite for the form-preservation bug in the healthcheck editor.
+ *
+ * Before this hook existed, the page had:
+ *
+ *   useEffect(() => {
+ *     if (existingConfig) setFormState({ … });
+ *   }, [existingConfig]);
+ *
+ * That fires on every refetch — including the refetches triggered by the
+ * realtime `HEALTH_CHECK_RUN_COMPLETED` signal — so the user's in-progress
+ * edits got wiped every time a healthcheck run completed anywhere on the
+ * platform.
+ *
+ * The hook delegates its decision to the pure `shouldInitForKey` function
+ * tested below. The hook is a thin React wrapper around two refs and a
+ * `useEffect` — testing the decision function gives full coverage of the
+ * logic without needing a DOM.
+ */
+
+describe("shouldInitForKey", () => {
+  it("returns true the first time value+key are defined and no key has been initialised", () => {
+    expect(
+      shouldInitForKey({
+        value: { name: "A" },
+        key: "id-1",
+        initialisedKey: undefined,
+      }),
+    ).toBe(true);
+  });
+
+  it("returns false when value is undefined (query still loading)", () => {
+    expect(
+      shouldInitForKey({
+        value: undefined,
+        key: "id-1",
+        initialisedKey: undefined,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns false when value is null", () => {
+    expect(
+      shouldInitForKey({
+        value: null,
+        key: "id-1",
+        initialisedKey: undefined,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns false when key is undefined (no discriminator yet)", () => {
+    expect(
+      shouldInitForKey({
+        value: { name: "A" },
+        key: undefined,
+        initialisedKey: undefined,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns false when key is null (record-not-found path)", () => {
+    expect(
+      shouldInitForKey({
+        value: { name: "A" },
+        key: null,
+        initialisedKey: undefined,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns false on a background refetch (same key already initialised)", () => {
+    // THE regression case: react-query refetched the same record after an
+    // invalidation, handing us a new `value` object reference. The
+    // `initialisedKey` already matches the new key, so we must not re-fire.
+    expect(
+      shouldInitForKey({
+        value: { name: "A (refetched)" },
+        key: "id-1",
+        initialisedKey: "id-1",
+      }),
+    ).toBe(false);
+  });
+
+  it("returns true when the key changes (user navigated to a different record)", () => {
+    expect(
+      shouldInitForKey({
+        value: { name: "B" },
+        key: "id-2",
+        initialisedKey: "id-1",
+      }),
+    ).toBe(true);
+  });
+
+  it("returns true when we're returning to a previously-seen key from a different one", () => {
+    // The hook only stores the LAST initialised key, so flipping between
+    // two records re-initialises each time. That's the correct behaviour:
+    // each visit shows fresh server data.
+    expect(
+      shouldInitForKey({
+        value: { name: "A" },
+        key: "id-1",
+        initialisedKey: "id-2",
+      }),
+    ).toBe(true);
+  });
+
+  it("treats numeric keys correctly (different number → re-init)", () => {
+    expect(
+      shouldInitForKey({ value: "any", key: 1, initialisedKey: 1 }),
+    ).toBe(false);
+    expect(
+      shouldInitForKey({ value: "any", key: 2, initialisedKey: 1 }),
+    ).toBe(true);
+  });
+
+  it("treats string vs number keys as different (no implicit coercion)", () => {
+    // If a caller starts passing IDs as numbers after passing strings (or
+    // vice versa) we'd rather re-init than miss an update; strict !== handles it.
+    expect(
+      shouldInitForKey({ value: "any", key: "1", initialisedKey: 1 }),
+    ).toBe(true);
+  });
+});