@checkstack/ui 1.8.2 → 1.9.0

package/src/components/CodeEditor/index.ts

@@ -3,9 +3,16 @@ export {
   type CodeEditorProps,
   type CodeEditorLanguage,
   type TemplateProperty,
+  type ShellEnvVar,
 } from "./CodeEditor";
 
 export {
   generateTypeDefinitions,
   type GenerateTypesOptions,
 } from "./generateTypeDefinitions";
+
+export {
+  healthcheckScriptContext,
+  integrationScriptContext,
+  type ScriptEditorContext,
+} from "./scriptContext";

package/src/components/CodeEditor/monacoStdlib.ts

@@ -0,0 +1,62 @@
+import type { Monaco } from "@monaco-editor/react";
+
+/**
+ * Lazy-load the bundled `@types/node` + `bun-types` declarations and mount
+ * them into a Monaco TypeScript service.
+ *
+ * The bundle lives at [generated/stdlib-types.json](./generated/stdlib-types.json)
+ * and is produced by `bun run generate:monaco-types`. It's ~3 MB of upstream
+ * `.d.ts` content, which is why we **dynamically import** it: bundlers
+ * (Vite, Rspack, …) split the JSON into its own chunk so it never blocks the
+ * initial frontend load. The chunk is fetched the first time the user opens
+ * an inline-script editor and cached for the rest of the session.
+ *
+ * Each file is registered at its real `node_modules/...` virtual path, so
+ * Monaco resolves cross-file `/// <reference>` directives just like the
+ * canonical TypeScript service would on disk.
+ */
+
+type StdlibBundle = Record<string, string>;
+
+let bundlePromise: Promise<StdlibBundle> | undefined;
+
+function loadBundle(): Promise<StdlibBundle> {
+  if (!bundlePromise) {
+    bundlePromise = import("./generated/stdlib-types.json").then(
+      (mod) => mod.default as StdlibBundle,
+    );
+  }
+  return bundlePromise;
+}
+
+const installedFor = new WeakSet<object>();
+
+/**
+ * Register the bundled stdlib types with the given Monaco instance.
+ *
+ * Safe to call multiple times — the work is gated on a per-Monaco
+ * `WeakSet` so we only `addExtraLib` once per instance, even across many
+ * editor mounts.
+ *
+ * @returns true once the stdlib is installed (or was already).
+ */
+export async function ensureMonacoStdlib(monaco: Monaco): Promise<boolean> {
+  if (installedFor.has(monaco)) return true;
+
+  const bundle = await loadBundle();
+
+  // TypeScript and JavaScript share a single TS service in Monaco, but each
+  // service tracks its own extra-libs. Register against both so the same
+  // bundle covers either language mode.
+  for (const defaults of [
+    monaco.languages.typescript.typescriptDefaults,
+    monaco.languages.typescript.javascriptDefaults,
+  ]) {
+    for (const [path, content] of Object.entries(bundle)) {
+      defaults.addExtraLib(content, `file:///${path}`);
+    }
+  }
+
+  installedFor.add(monaco);
+  return true;
+}

package/src/components/CodeEditor/monacoWorkers.ts

@@ -0,0 +1,118 @@
+/// <reference types="vite/client" />
+/**
+ * Eager, module-load-time Monaco bootstrap. Three things happen here,
+ * in this exact order, before any `<CodeEditor>` instance can mount:
+ *
+ *   1. Bundle the per-language web workers via Vite's `?worker` import
+ *      suffix and install them via `MonacoEnvironment.getWorker`.
+ *      Without locally-bundled workers, the loader's default CDN path
+ *      sometimes fails silently (CORS on the worker scripts) and the
+ *      TS service falls back to no-language-service mode.
+ *
+ *   2. Configure the TypeScript language service — compiler options,
+ *      diagnostics options, eager-model-sync. The TS service in
+ *      monaco-editor is a singleton that initialises lazily the FIRST
+ *      time it sees a TS/JS model. Doing this config inside a
+ *      per-mount `onMount` (the previous shape) meant a shell editor
+ *      mounted first would start the service with defaults, and the
+ *      later TS editor's config arrived too late.
+ *
+ *   3. Tell `@monaco-editor/react`'s loader to use our locally-bundled
+ *      Monaco instance via `loader.config({ monaco })`. Without this
+ *      the loader pulls Monaco from a CDN at runtime — which defeats
+ *      the worker setup above.
+ *
+ * This file is imported as a SIDE EFFECT from MonacoEditor.tsx, so the
+ * setup runs on the first import of CodeEditor regardless of which
+ * language ends up being mounted first.
+ */
+import * as monaco from "monaco-editor";
+import editorWorker from "monaco-editor/esm/vs/editor/editor.worker?worker";
+import jsonWorker from "monaco-editor/esm/vs/language/json/json.worker?worker";
+import cssWorker from "monaco-editor/esm/vs/language/css/css.worker?worker";
+import htmlWorker from "monaco-editor/esm/vs/language/html/html.worker?worker";
+import tsWorker from "monaco-editor/esm/vs/language/typescript/ts.worker?worker";
+import { loader } from "@monaco-editor/react";
+
+// ─── 1. Workers ──────────────────────────────────────────────────────────
+
+interface MonacoEnvironmentLike {
+  getWorker(workerId: string, label: string): Worker;
+}
+
+(
+  globalThis as unknown as { MonacoEnvironment: MonacoEnvironmentLike }
+).MonacoEnvironment = {
+  getWorker(_workerId: string, label: string): Worker {
+    switch (label) {
+      case "json": {
+        return new jsonWorker();
+      }
+      case "css":
+      case "scss":
+      case "less": {
+        return new cssWorker();
+      }
+      case "html":
+      case "handlebars":
+      case "razor": {
+        return new htmlWorker();
+      }
+      case "typescript":
+      case "javascript": {
+        return new tsWorker();
+      }
+      default: {
+        return new editorWorker();
+      }
+    }
+  },
+};
+
+// ─── 2. TypeScript language service ──────────────────────────────────────
+//
+// In monaco-editor 0.55 the canonical access path is `monaco.typescript`
+// (the older `monaco.languages.typescript` is marked
+// `{ deprecated: true }` in the type defs and emits a tombstone object).
+// Both still resolve to the same singleton at runtime; we use the new
+// path for type-safety.
+
+const tsDefaults = monaco.typescript.typescriptDefaults;
+const jsDefaults = monaco.typescript.javascriptDefaults;
+
+for (const defaults of [tsDefaults, jsDefaults]) {
+  defaults.setCompilerOptions({
+    target: monaco.typescript.ScriptTarget.ESNext,
+    module: monaco.typescript.ModuleKind.ESNext,
+    moduleResolution: monaco.typescript.ModuleResolutionKind.NodeJs,
+    lib: ["esnext"],
+    // Pulls the bundled @types/node + bun-types declarations into the
+    // ambient scope, so `process`, `Buffer`, the `Bun` global, etc. are
+    // typed without the user needing any `/// <reference>`.
+    types: ["node", "bun-types"],
+    allowNonTsExtensions: false,
+    noEmit: true,
+    strict: true,
+    esModuleInterop: true,
+  });
+
+  // Suppress diagnostics that don't apply to our script context:
+  //   - 1108: "A 'return' statement can only be used within a function body"
+  //           The runtime wraps legacy scripts in an async IIFE, so a
+  //           top-level `return X;` is valid in the user's source.
+  defaults.setDiagnosticsOptions({
+    diagnosticCodesToIgnore: [1108],
+  });
+
+  // Eagerly push models to the TS worker the moment they're created so
+  // diagnostics + completions are available on the first keystroke.
+  defaults.setEagerModelSync(true);
+}
+
+// ─── 3. Loader ───────────────────────────────────────────────────────────
+//
+// Must be the LAST step: once a `<Editor>` mounts, `loader.init()` is
+// called and config is locked. Pointing at our local `monaco` import
+// bypasses the loader's default AMD/CDN path entirely.
+
+loader.config({ monaco });

package/src/components/CodeEditor/scriptContext.test.ts

@@ -0,0 +1,280 @@
+import { describe, expect, it } from "bun:test";
+import {
+  healthcheckScriptContext,
+  integrationScriptContext,
+  _internals,
+} from "./scriptContext";
+import type { JsonSchemaProperty } from "../DynamicForm/types";
+
+describe("healthcheckScriptContext", () => {
+  it("emits both the global and module-export declarations of defineHealthCheck", () => {
+    const ctx = healthcheckScriptContext({});
+    // Module declaration is what `import { defineHealthCheck } from
+    // "@checkstack/healthcheck"` resolves to.
+    expect(ctx.typeDefinitions).toContain('declare module "@checkstack/healthcheck"');
+    expect(ctx.typeDefinitions).toContain("HealthCheckScriptResult");
+    // Global declaration is what makes Monaco autocomplete `defineHea…`
+    // _without_ requiring the user to type the import first (Monaco 0.55
+    // doesn't expose `includeCompletionsForModuleExports`).
+    expect(ctx.typeDefinitions).toMatch(/declare function defineHealthCheck/);
+  });
+
+  it("typed `context.config` reflects the supplied collector schema", () => {
+    const ctx = healthcheckScriptContext({
+      collectorConfigSchema: {
+        type: "object",
+        properties: {
+          host: { type: "string", description: "Target hostname" },
+          port: { type: "integer" },
+          enabled: { type: "boolean" },
+        },
+        required: ["host", "port"],
+      },
+    });
+
+    // Property names + descriptions should land in the generated context block.
+    expect(ctx.typeDefinitions).toContain("declare const context");
+    expect(ctx.typeDefinitions).toContain("readonly host: string");
+    expect(ctx.typeDefinitions).toContain("readonly port: number");
+    expect(ctx.typeDefinitions).toContain("readonly enabled?: boolean");
+    expect(ctx.typeDefinitions).toContain("Target hostname");
+  });
+
+  it("falls back to a generic `Record<string, unknown>` config when no schema is given", () => {
+    const ctx = healthcheckScriptContext({});
+    // We ALWAYS declare `context` so the function-arg form
+    // `defineHealthCheck(ctx => …)` is properly typed too — without a
+    // schema, both the global and the function param fall back to a
+    // generic config shape.
+    expect(ctx.typeDefinitions).toContain("declare const context");
+    expect(ctx.typeDefinitions).toContain("Record<string, unknown>");
+    expect(ctx.typeDefinitions).toContain("HealthCheckScriptResult");
+    expect(ctx.typeDefinitions).toContain("HealthCheckScriptContext");
+  });
+
+  it("types the `defineHealthCheck` callback parameter from the schema (not `unknown`)", () => {
+    // Regression guard: the previous version had `(ctx: unknown) => …`,
+    // so `ctx.config.host` produced "'ctx' is of type 'unknown'". The
+    // callback param must reference the shared HealthCheckScriptContext
+    // type that's also used for the global `context`.
+    const ctx = healthcheckScriptContext({
+      collectorConfigSchema: {
+        type: "object",
+        properties: { host: { type: "string" } },
+        required: ["host"],
+      },
+    });
+    expect(ctx.typeDefinitions).toMatch(
+      /\(ctx:\s*HealthCheckScriptContext\)/,
+    );
+    // The shared context type carries the schema-derived field.
+    expect(ctx.typeDefinitions).toContain("readonly host: string");
+  });
+
+  it("exposes inline TS + shell starters", () => {
+    const ctx = healthcheckScriptContext({});
+    expect(ctx.starterTemplates.typescript).toBeDefined();
+    expect(ctx.starterTemplates.javascript).toBeDefined();
+    expect(ctx.starterTemplates.shell).toBeDefined();
+    expect(ctx.starterTemplates.typescript).toContain('import { loadavg } from "node:os"');
+    expect(ctx.starterTemplates.typescript).toContain("defineHealthCheck");
+    // Portable load-average read via `uptime` (works on Linux + macOS).
+    expect(ctx.starterTemplates.shell).toContain("uptime");
+    expect(ctx.starterTemplates.shell).toContain("load average");
+    expect(ctx.starterTemplates.shell).toContain("awk");
+    // Guard against a Linux-only regression: /proc/loadavg doesn't
+    // exist on macOS, so the starter must not depend on it.
+    expect(ctx.starterTemplates.shell).not.toContain("/proc/loadavg");
+  });
+
+  it("exposes the safe-env-vars whitelist for shell completion", () => {
+    const ctx = healthcheckScriptContext({});
+    const names = ctx.shellEnvVars.map((v) => v.name);
+    // Sanity-check a few entries from the whitelist that scripts will
+    // most often actually reference.
+    expect(names).toContain("PATH");
+    expect(names).toContain("HOME");
+    expect(names).toContain("TZ");
+    // Integration-only vars must NOT leak into the healthcheck context.
+    expect(names).not.toContain("EVENT_ID");
+    expect(names).not.toContain("PAYLOAD_TITLE");
+  });
+});
+
+describe("integrationScriptContext", () => {
+  it("emits both the global and module-export declarations of defineIntegration", () => {
+    const ctx = integrationScriptContext({});
+    expect(ctx.typeDefinitions).toContain('declare module "@checkstack/integration"');
+    expect(ctx.typeDefinitions).toContain("IntegrationScriptResult");
+    // Global form — analogous to defineHealthCheck.
+    expect(ctx.typeDefinitions).toMatch(/declare function defineIntegration/);
+  });
+
+  it("typed `context.event.payload` reflects the supplied payload schema", () => {
+    const ctx = integrationScriptContext({
+      eventPayloadSchema: {
+        type: "object",
+        properties: {
+          title: { type: "string" },
+          severity: { type: "string", enum: ["low", "high"] },
+        },
+        required: ["title"],
+      },
+    });
+
+    expect(ctx.typeDefinitions).toContain("readonly title: string");
+    // Enum should narrow to the literal union.
+    expect(ctx.typeDefinitions).toContain('"low" | "high"');
+    expect(ctx.typeDefinitions).toContain("declare const context");
+    expect(ctx.typeDefinitions).toContain("eventId");
+  });
+
+  it("types the `defineIntegration` callback parameter from the schema (not `unknown`)", () => {
+    // Regression guard for the screenshot the user sent: typing
+    // `context.event.eventId` inside `defineIntegration(async (context)
+    // => …)` produced "'context' is of type 'unknown'" because the
+    // virtual module declared the param as `unknown`. Must reference
+    // the shared `IntegrationScriptContext` type instead.
+    const ctx = integrationScriptContext({
+      eventPayloadSchema: {
+        type: "object",
+        properties: { title: { type: "string" } },
+        required: ["title"],
+      },
+    });
+    expect(ctx.typeDefinitions).toMatch(
+      /\(ctx:\s*IntegrationScriptContext\)/,
+    );
+    // The shared context type carries the schema-derived payload field.
+    expect(ctx.typeDefinitions).toContain("readonly title: string");
+    // And the always-present event metadata.
+    expect(ctx.typeDefinitions).toContain("readonly eventId: string");
+    expect(ctx.typeDefinitions).toContain("readonly deliveryId: string");
+  });
+
+  it("falls back to `Record<string, unknown>` payload when no schema is given", () => {
+    const ctx = integrationScriptContext({});
+    expect(ctx.typeDefinitions).toContain("declare const context");
+    expect(ctx.typeDefinitions).toContain("IntegrationScriptContext");
+    expect(ctx.typeDefinitions).toContain("Record<string, unknown>");
+  });
+
+  it("flattens nested payload schemas into PAYLOAD_* shell env-var hints", () => {
+    const ctx = integrationScriptContext({
+      eventPayloadSchema: {
+        type: "object",
+        properties: {
+          title: { type: "string", description: "Incident title" },
+          severity: { type: "string" },
+          metadata: {
+            type: "object",
+            properties: {
+              region: { type: "string" },
+              host: { type: "string" },
+            },
+          },
+        },
+      },
+    });
+
+    const names = ctx.shellEnvVars.map((v) => v.name);
+    // Top-level scalars are flattened with the PAYLOAD_ prefix.
+    expect(names).toContain("PAYLOAD_TITLE");
+    expect(names).toContain("PAYLOAD_SEVERITY");
+    // Nested objects are recursively flattened with underscore-joined keys.
+    expect(names).toContain("PAYLOAD_METADATA_REGION");
+    expect(names).toContain("PAYLOAD_METADATA_HOST");
+    // The intermediate object key itself is NOT emitted (only its leaves).
+    expect(names).not.toContain("PAYLOAD_METADATA");
+
+    const title = ctx.shellEnvVars.find((v) => v.name === "PAYLOAD_TITLE");
+    expect(title?.description).toBe("Incident title");
+  });
+
+  it("always includes the platform-injected core integration env vars", () => {
+    const ctx = integrationScriptContext({});
+    const names = ctx.shellEnvVars.map((v) => v.name);
+    expect(names).toContain("EVENT_ID");
+    expect(names).toContain("EVENT_TIMESTAMP");
+    expect(names).toContain("DELIVERY_ID");
+    expect(names).toContain("SUBSCRIPTION_ID");
+    expect(names).toContain("SUBSCRIPTION_NAME");
+    // Safe-vars are also still present.
+    expect(names).toContain("PATH");
+  });
+
+  it("exposes inline TS + shell starters that reference the right variables", () => {
+    const ctx = integrationScriptContext({});
+    expect(ctx.starterTemplates.typescript).toContain("defineIntegration");
+    expect(ctx.starterTemplates.typescript).toContain("context.event.eventId");
+    expect(ctx.starterTemplates.shell).toContain("$EVENT_ID");
+    expect(ctx.starterTemplates.shell).toContain("$PAYLOAD_TITLE");
+  });
+
+  it("falls back gracefully when the payload schema isn't available", () => {
+    const ctx = integrationScriptContext({});
+    // No `PAYLOAD_*` hints yet, but the core vars and starters are usable.
+    const payloadVars = ctx.shellEnvVars.filter((v) =>
+      v.name.startsWith("PAYLOAD_"),
+    );
+    expect(payloadVars).toHaveLength(0);
+    expect(ctx.starterTemplates.typescript).toBeDefined();
+    expect(ctx.starterTemplates.shell).toBeDefined();
+  });
+});
+
+describe("flattenSchemaToEnvVars (internal)", () => {
+  const { flattenSchemaToEnvVars } = _internals;
+
+  it("returns an empty list for non-object schemas", () => {
+    expect(flattenSchemaToEnvVars({ type: "string" })).toEqual([]);
+    expect(flattenSchemaToEnvVars({ type: "number" })).toEqual([]);
+  });
+
+  it("normalises field names: uppercases and replaces dots/dashes", () => {
+    const schema: JsonSchemaProperty = {
+      type: "object",
+      properties: {
+        "user.email": { type: "string" },
+        "first-name": { type: "string" },
+        "field!with$weird?chars": { type: "string" },
+      },
+    };
+
+    const names = flattenSchemaToEnvVars(schema).map((v) => v.name);
+    expect(names).toContain("PAYLOAD_USER_EMAIL");
+    expect(names).toContain("PAYLOAD_FIRST_NAME");
+    // Special characters are stripped, not preserved.
+    expect(names).toContain("PAYLOAD_FIELDWITHWEIRDCHARS");
+  });
+
+  it("respects a custom prefix for nested flattening", () => {
+    const schema: JsonSchemaProperty = {
+      type: "object",
+      properties: {
+        title: { type: "string" },
+      },
+    };
+
+    const result = flattenSchemaToEnvVars(schema, "EVENT");
+    expect(result[0]?.name).toBe("EVENT_TITLE");
+  });
+
+  it("includes example placeholders sized to the property type", () => {
+    const schema: JsonSchemaProperty = {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        count: { type: "number" },
+        on: { type: "boolean" },
+      },
+    };
+
+    const byName = Object.fromEntries(
+      flattenSchemaToEnvVars(schema).map((v) => [v.name, v]),
+    );
+    expect(byName.PAYLOAD_NAME?.example).toBe("<string>");
+    expect(byName.PAYLOAD_COUNT?.example).toBe("<number>");
+    expect(byName.PAYLOAD_ON?.example).toBe("<true|false>");
+  });
+});