@checkstack/ui 1.10.0 → 1.12.0

package/src/components/CodeEditor/importSpecifiers.ts

@@ -0,0 +1,267 @@
+// Pure helpers for the editor's lazy Automatic Type Acquisition (ATA) loop.
+//
+// `parseBareImportSpecifiers` extracts the BARE package specifiers a script
+// buffer imports/requires, so the editor can fetch + register only those
+// packages' `.d.ts` on demand. `planAcquisitions` diffs that set against the
+// already-acquired set so re-parsing on every keystroke never refetches.
+//
+// Both are pure + unit-tested (no monaco/DOM), per the no-DOM-tests rule.
+
+/** Bare specifiers we never try to acquire (already typed or runtime built-ins). */
+const IGNORED_SPECIFIERS = new Set<string>(["context"]);
+
+/**
+ * True for specifiers the editor must NOT try to acquire:
+ *  - relative paths (`./x`, `../x`) — not packages.
+ *  - `node:`-prefixed built-ins — already covered by the bundled @types/node.
+ *  - `bun` / `bun:*` — covered by the bundled bun-types.
+ *  - the injected `context` ambient global.
+ */
+function isIgnoredSpecifier(specifier: string): boolean {
+  if (specifier.length === 0) return true;
+  if (specifier.startsWith("./") || specifier.startsWith("../")) return true;
+  if (specifier === "." || specifier === "..") return true;
+  if (specifier.startsWith("node:")) return true;
+  if (specifier === "bun" || specifier.startsWith("bun:")) return true;
+  return IGNORED_SPECIFIERS.has(specifier);
+}
+
+/**
+ * Reduce a possibly-subpath specifier to the package name to acquire:
+ *  - `lodash/fp`        -> `lodash`
+ *  - `@scope/pkg/sub`   -> `@scope/pkg`
+ *  - `lodash`           -> `lodash`
+ *  - `@scope/pkg`       -> `@scope/pkg`
+ */
+export function packageNameFromSpecifier(specifier: string): string {
+  if (specifier.startsWith("@")) {
+    const parts = specifier.split("/");
+    return parts.slice(0, 2).join("/");
+  }
+  return specifier.split("/")[0];
+}
+
+/**
+ * Parse the unique BARE package names imported/required by a script buffer.
+ * Handles every import/require form:
+ *   import x from "p"; import {a} from "p"; import * as p from "p";
+ *   import "p"; import type {T} from "p"; export {a} from "p";
+ *   export * from "p"; const x = require("p"); await import("p")
+ * Ignores relative paths, `node:`/`bun` built-ins, and the `context` global.
+ * Subpath imports are reduced to their package name.
+ */
+export function parseBareImportSpecifiers(source: string): string[] {
+  const found = new Set<string>();
+
+  const patterns: RegExp[] = [
+    // import ... from "p"  /  export ... from "p"  (incl. import type)
+    /\b(?:import|export)\b[^;\n]*?\bfrom\s*["']([^"']+)["']/g,
+    // bare side-effect import:  import "p"
+    /\bimport\s*["']([^"']+)["']/g,
+    // dynamic import:  import("p")
+    /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g,
+    // require:  require("p")
+    /\brequire\s*\(\s*["']([^"']+)["']\s*\)/g,
+  ];
+
+  for (const pattern of patterns) {
+    let match: RegExpExecArray | null = pattern.exec(source);
+    while (match !== null) {
+      const specifier = match[1];
+      if (!isIgnoredSpecifier(specifier)) {
+        found.add(packageNameFromSpecifier(specifier));
+      }
+      match = pattern.exec(source);
+    }
+  }
+
+  return [...found];
+}
+
+/**
+ * Given the specifiers currently in the buffer and the set already acquired,
+ * return only the NEW ones to fetch (order-stable). Pure planning step so the
+ * ATA loop never refetches an already-registered package.
+ */
+export function planAcquisitions({
+  specifiers,
+  acquired,
+}: {
+  specifiers: string[];
+  acquired: ReadonlySet<string>;
+}): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const specifier of specifiers) {
+    if (acquired.has(specifier) || seen.has(specifier)) continue;
+    seen.add(specifier);
+    out.push(specifier);
+  }
+  return out;
+}
+
+/**
+ * The cursor's position inside an import-string literal, as detected from the
+ * text on the current line up to (but not including) the cursor.
+ *
+ * `partial` is the specifier text already typed between the opening quote and
+ * the cursor; `replaceFromColumn` is the 1-based editor column of the FIRST
+ * specifier character (i.e. just after the opening quote), so a completion can
+ * replace the whole partial specifier without touching the quotes.
+ */
+export interface ImportSpecifierCompletionContext {
+  partial: string;
+  /** 1-based column where the specifier text starts (just after the quote). */
+  replaceFromColumn: number;
+}
+
+// The import/require lead-ins that put a following string literal in
+// module-specifier position. Each is matched at the END of the line-up-to-
+// cursor, immediately followed by an OPEN (unclosed) quote + the partial text.
+//
+//   ... from "      ->  from-clause (import/export)
+//   import "        ->  bare side-effect import
+//   import(" / require("  ->  dynamic import / require call
+//
+// We deliberately match only an UNCLOSED string (no closing quote between the
+// opening quote and the cursor) so completions never fire once the specifier
+// string is already closed.
+const IMPORT_STRING_LEAD_INS: RegExp[] = [
+  // `from "partial`  (import ... from / export ... from)
+  /\bfrom\s*(["'])([^"']*)$/,
+  // `import "partial`  (bare side-effect import) — `import` not followed by `(`
+  /\bimport\s*(["'])([^"']*)$/,
+  // `import("partial`  (dynamic import)
+  /\bimport\s*\(\s*(["'])([^"']*)$/,
+  // `require("partial`  (CJS require)
+  /\brequire\s*\(\s*(["'])([^"']*)$/,
+];
+
+/**
+ * Detect whether the cursor sits inside an import/require module-specifier
+ * STRING, and if so return the partial specifier + where it starts. Returns
+ * null otherwise (so a completion provider can bail and not pollute normal
+ * positions).
+ *
+ * `lineUpToCursor` is the current line's text from column 1 up to the cursor
+ * (exclusive). Pure + unit-tested; no editor/DOM dependency.
+ */
+export function importSpecifierCompletionContext(
+  lineUpToCursor: string,
+): ImportSpecifierCompletionContext | null {
+  for (const pattern of IMPORT_STRING_LEAD_INS) {
+    const match = pattern.exec(lineUpToCursor);
+    if (!match) continue;
+    const partial = match[2];
+    // The partial starts right after the opening quote. The quote's index is
+    // (matchEnd - partial.length - 1); the partial's first char is one past
+    // that. Editor columns are 1-based, so add 1 to the 0-based index.
+    const partialStartIndex = lineUpToCursor.length - partial.length;
+    return { partial, replaceFromColumn: partialStartIndex + 1 };
+  }
+  return null;
+}
+
+/**
+ * Filter a raw manifest package-name list down to the names a user can
+ * actually `import`: drop `@types/*` companions (you import `lodash`, never
+ * `@types/lodash`), dedupe, and sort. Pure + unit-tested.
+ */
+export function importablePackageNames(names: readonly string[]): string[] {
+  const out = new Set<string>();
+  for (const name of names) {
+    if (name.startsWith("@types/")) continue;
+    out.add(name);
+  }
+  return [...out].toSorted((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Extract the importable built-in module specifiers from bundled stdlib
+ * declaration text (`@types/node` + `bun-types`). Every importable built-in is
+ * declared as a top-level `declare module "<spec>"` (e.g. `node:fs`, bare `fs`,
+ * `bun`, `bun:test`), so the authoritative name set is exactly those names.
+ *
+ * Filter rules (documented):
+ *  - Keep any `declare module "<spec>"` name that is a real specifier.
+ *  - DROP names containing a star character — those are wildcard / asset-glob
+ *    ambient shims (e.g. text/css asset globs or a "bun.lock" path glob), not
+ *    importable runtime modules.
+ *
+ * Pure + unit-tested. Used at BUILD time by the stdlib-types generator to emit
+ * the static name list the editor ships.
+ */
+export function extractBuiltinModuleSpecifiers(
+  declarationText: string,
+): string[] {
+  const out = new Set<string>();
+  // Top-level `declare module "<spec>"` (single or double quotes), anchored to
+  // a statement start (per line, via the `m` flag) so we don't match
+  // augmentation blocks nested deeper — though stdlib's importable modules are
+  // all declared at top level anyway.
+  const pattern = /^\s*declare\s+module\s+["']([^"']+)["']/gm;
+  let match: RegExpExecArray | null = pattern.exec(declarationText);
+  while (match !== null) {
+    const spec = match[1];
+    // Drop wildcard / asset-glob ambient shims (any name containing a star,
+    // e.g. an asset-glob like a ".txt" shim or a "bun.lock" path glob): those
+    // are ambient module shims, not importable runtime modules.
+    if (!spec.includes("*")) {
+      out.add(spec);
+    }
+    match = pattern.exec(declarationText);
+  }
+  return [...out].toSorted((a, b) => a.localeCompare(b));
+}
+
+/** A built-in import specifier plus how it should read in the completion list. */
+export interface BuiltinModuleSpecifier {
+  name: string;
+  /** Completion `detail`, e.g. "Node.js" or "Bun built-in". */
+  detail: string;
+}
+
+/**
+ * Classify a built-in specifier for completion display: `bun` and any
+ * `bun:`-prefixed specifier are Bun built-ins; everything else (the
+ * `node:`-prefixed and bare node builtins) is Node.js. Pure.
+ */
+export function classifyBuiltinModule(name: string): BuiltinModuleSpecifier {
+  const isBun = name === "bun" || name.startsWith("bun:");
+  return { name, detail: isBun ? "Bun built-in" : "Node.js" };
+}
+
+/** One entry in the merged import-name completion list. */
+export interface ImportCompletionEntry {
+  name: string;
+  /** Completion `detail`, e.g. "installed package" / "Node.js" / "Bun built-in". */
+  detail: string;
+}
+
+/**
+ * Merge the always-available runtime built-ins with the injected installed
+ * package names into the final import-name completion list. Built-ins are
+ * always present (importable in the sandbox regardless of the allowlist);
+ * installed packages augment them. Deduped (installed names win their own
+ * `detail`) and sorted. Pure + unit-tested.
+ */
+export function mergeImportCompletionEntries({
+  builtins,
+  installedPackages,
+}: {
+  builtins: readonly string[];
+  installedPackages: readonly string[];
+}): ImportCompletionEntry[] {
+  const byName = new Map<string, ImportCompletionEntry>();
+  for (const name of builtins) {
+    const { detail } = classifyBuiltinModule(name);
+    byName.set(name, { name, detail });
+  }
+  // Installed packages are already `@types/*`-free + deduped by the caller, but
+  // be defensive. An installed package name that collides with a built-in is
+  // re-labelled as an installed package (unlikely, but deterministic).
+  for (const name of installedPackages) {
+    byName.set(name, { name, detail: "installed package" });
+  }
+  return [...byName.values()].toSorted((a, b) => a.name.localeCompare(b.name));
+}

package/src/components/CodeEditor/index.ts

@@ -4,6 +4,9 @@ export {
   type CodeEditorLanguage,
   type TemplateProperty,
   type ShellEnvVar,
+  type EditorMarker,
+  type AcquireTypes,
+  type AcquiredTypeFile,
 } from "./CodeEditor";
 
 export {
@@ -12,7 +15,30 @@ export {
 } from "./generateTypeDefinitions";
 
 export {
+  customShellEnvVars,
   healthcheckScriptContext,
   integrationScriptContext,
   type ScriptEditorContext,
 } from "./scriptContext";
+
+// Pure helper used by consumers (e.g. script-packages-frontend) to derive the
+// importable package-name list for the editor's import-specifier completions.
+export { importablePackageNames } from "./importSpecifiers";
+
+// Headless script validator: type-check scripts against their generated
+// `context` types without a mounted editor (drives the same standalone TS
+// worker). Used by the automation editor to surface type errors on collapsed
+// script-action cards.
+export {
+  validateTypeScriptSources,
+  type ScriptValidationInput,
+  type ScriptDiagnostic,
+} from "./validateScripts";
+
+// Subscribe to / query the monaco-vscode "services ready" transition so a
+// consumer (the automation editor's script validator + its hidden services
+// booter) can react the moment the first editor initializes the services.
+export {
+  onVscodeServicesReady,
+  areVscodeServicesReady,
+} from "./monacoTsService";

package/src/components/CodeEditor/monacoTsService.ts

@@ -0,0 +1,217 @@
+// Shared standalone TypeScript / JavaScript language-service setup.
+//
+// Extracted from `TypefoxEditor` so it can be imported by BOTH the editor and
+// the headless `validateScripts` validator. Both need the same singletons
+// configured (compiler options, ambient stdlib types, the TS worker), and the
+// validator must work even when NO editor is mounted (every script action card
+// collapsed) - so the setup cannot live inside the editor component module's
+// render path.
+//
+// The TS/JS language-service `defaults` are singletons, so the configuration
+// here runs ONCE at module load. The worker factory is registered lazily (and
+// idempotently) via `ensureStandaloneWorkerFactory()` because the editor also
+// registers it during its own init - the guard makes a double-call a no-op.
+
+// Side-effect import: registers the standalone language grammars. Imported here
+// too (not only in TypefoxEditor) so the validator gets a fully-registered TS
+// language environment regardless of import order.
+import "@codingame/monaco-vscode-standalone-languages";
+// The named imports below ALSO trigger this package's side-effect registration
+// of the standalone TypeScript language features (defaults + ts.worker).
+import {
+  typescriptDefaults,
+  javascriptDefaults,
+  ScriptTarget,
+  ModuleKind,
+  ModuleResolutionKind,
+} from "@codingame/monaco-vscode-standalone-typescript-language-features";
+// Worker entry URLs, bundled and resolved by Vite via the `?worker&url` suffix.
+// Imported as URL STRINGS (not Worker constructors) because
+// monaco-languageclient's worker factory consumes `loader().url.toString()`.
+import editorWorkerUrl from "@codingame/monaco-vscode-editor-api/esm/vs/editor/editor.worker.js?worker&url";
+import tsWorkerUrl from "@codingame/monaco-vscode-standalone-typescript-language-features/worker?worker&url";
+import jsonWorkerUrl from "@codingame/monaco-vscode-standalone-json-language-features/worker?worker&url";
+import {
+  // `useWorkerFactory` is a plain library registration function, not a React
+  // hook. We alias away the `use` prefix so the `react-hooks/rules-of-hooks`
+  // lint rule (which keys purely off the identifier name) does not misfire.
+  useWorkerFactory as registerWorkerFactory,
+  Worker,
+  type WorkerFactoryConfig,
+  type WorkerLoader,
+} from "monaco-languageclient/workerFactory";
+
+// Re-exported so consumers keep a single import surface for the TS services.
+export {
+  typescriptDefaults,
+  javascriptDefaults,
+  ScriptTarget,
+  ModuleKind,
+  ModuleResolutionKind,
+} from "@codingame/monaco-vscode-standalone-typescript-language-features";
+
+// The logger type originates from `@codingame/monaco-vscode-log-service-override`,
+// which is not a direct dependency of this package. We derive it from the
+// `WorkerFactoryConfig` we already import so we never reach for a transitive
+// specifier (and never need an `any`).
+type WorkerFactoryLogger = WorkerFactoryConfig["logger"];
+
+const editorWorkerLoader: WorkerLoader = () =>
+  new Worker(editorWorkerUrl, { type: "module" });
+
+const tsWorkerLoader: WorkerLoader = () =>
+  new Worker(tsWorkerUrl, { type: "module" });
+
+const jsonWorkerLoader: WorkerLoader = () =>
+  new Worker(jsonWorkerUrl, { type: "module" });
+
+// The monaco-vscode API initializes globally exactly ONCE, and that init is
+// owned by the editor wrapper (`MonacoEditorReactComp`) - it throws "Services
+// are already initialized" if anything else inits first. So the headless
+// validator must NOT touch the worker / models until an editor has brought the
+// services up. The editor flips this flag from its `onEditorStartDone`; the
+// validator checks it and otherwise no-ops. Net effect: scripts validate once
+// any script editor has been opened this session (covering collapsed cards
+// from then on); a never-opened, all-collapsed automation is left to the
+// deferred backend typecheck.
+let vscodeServicesReady = false;
+const servicesReadyListeners = new Set<() => void>();
+
+/** Called by the editor once the monaco-vscode services have initialized. */
+export const markVscodeServicesReady = (): void => {
+  if (vscodeServicesReady) return;
+  vscodeServicesReady = true;
+  for (const listener of servicesReadyListeners) listener();
+  servicesReadyListeners.clear();
+};
+
+/** True once an editor has initialized the monaco-vscode services. */
+export const areVscodeServicesReady = (): boolean => vscodeServicesReady;
+
+/**
+ * Subscribe to the one-time "services ready" transition. Fires immediately if
+ * already ready. Returns an unsubscribe. Lets the headless validator re-run the
+ * moment the first editor brings the services up (otherwise a never-edited
+ * definition would not re-validate just because a card was opened).
+ */
+export const onVscodeServicesReady = (listener: () => void): (() => void) => {
+  if (vscodeServicesReady) {
+    listener();
+    return () => {};
+  }
+  servicesReadyListeners.add(listener);
+  return () => servicesReadyListeners.delete(listener);
+};
+
+let workerFactoryRegistered = false;
+
+/**
+ * Register the worker loaders for the standalone (classic) Monaco setup. We
+ * only need the generic editor worker plus the TypeScript worker (which also
+ * serves JavaScript) and the JSON worker. Mirrors the upstream
+ * `defineClassicWorkers` helper.
+ *
+ * Idempotent: the first caller registers, subsequent calls no-op. Both the
+ * editor (via its `monacoWorkerFactory` app-config hook) AND the headless
+ * validator call this, so the guard prevents a double registration. The
+ * editor's call may pass a `logger`; the first registration wins, so when the
+ * validator registers first the editor simply reuses it (logging is optional).
+ */
+export const ensureStandaloneWorkerFactory = (
+  logger?: WorkerFactoryLogger,
+): void => {
+  if (workerFactoryRegistered) {
+    return;
+  }
+  workerFactoryRegistered = true;
+  registerWorkerFactory({
+    workerLoaders: {
+      editorWorkerService: editorWorkerLoader,
+      // Both must be defined or the worker factory errors (see upstream
+      // helper-classic.ts).
+      javascript: tsWorkerLoader,
+      typescript: tsWorkerLoader,
+      json: jsonWorkerLoader,
+    },
+    logger,
+  });
+};
+
+// Base compiler options for the standalone TS + JS services. `types` (node +
+// bun-types) is added only once the stdlib bundle has loaded (see
+// ensureStandaloneStdlib), so the service doesn't transiently error on a
+// missing `node` type while the ~3 MB bundle is still fetching.
+//
+// `baseUrl: "file:///"` anchors NodeJs bare-import resolution at the virtual
+// root so an `import "lodash"` walks `file:///node_modules/...` - the same
+// virtual layout the stdlib bundle AND the lazy-ATA extra-libs are registered
+// under. `typeRoots` lists BOTH the `@types` root (so a package with no own
+// types, e.g. lodash, falls back to `@types/lodash`) and the bare
+// `node_modules` root (so the bundled `bun-types`, which is NOT under
+// `@types`, still resolves as an ambient `types` entry).
+export const BASE_COMPILER_OPTIONS = {
+  target: ScriptTarget.ESNext,
+  module: ModuleKind.ESNext,
+  moduleResolution: ModuleResolutionKind.NodeJs,
+  lib: ["esnext"],
+  allowNonTsExtensions: false,
+  noEmit: true,
+  strict: true,
+  esModuleInterop: true,
+  baseUrl: "file:///",
+  typeRoots: ["file:///node_modules/@types", "file:///node_modules"],
+};
+
+/**
+ * Configure the standalone TS + JS language services ONCE at module load.
+ * `typescriptDefaults` / `javascriptDefaults` are singletons, so doing this at
+ * module scope (not per-mount) guarantees the first editor to mount cannot
+ * start the service with stale defaults - the timing race the legacy monaco
+ * editor hit.
+ */
+const configureTypeScriptDefaults = (): void => {
+  for (const defaults of [typescriptDefaults, javascriptDefaults]) {
+    defaults.setCompilerOptions({ ...BASE_COMPILER_OPTIONS });
+    // 1108: a top-level `return` is valid because the runtime wraps scripts in
+    // an async IIFE (same suppression as the legacy editor).
+    defaults.setDiagnosticsOptions({ diagnosticCodesToIgnore: [1108] });
+    // Push models to the worker eagerly so diagnostics/completions are ready on
+    // the first keystroke.
+    defaults.setEagerModelSync(true);
+  }
+};
+
+configureTypeScriptDefaults();
+
+/**
+ * Lazy-load the bundled `@types/node` + `bun-types` declarations into the
+ * standalone TS service so script editors have `console`, `fetch`, `process`,
+ * `Bun`, etc. typed. The ~3 MB bundle is code-split into its own chunk and
+ * fetched once. Runs at module load; this file is browser-only so the dynamic
+ * import is safe here. Returns the in-flight promise so callers (the headless
+ * validator) can await stdlib readiness before requesting diagnostics.
+ */
+let stdlibLoad: Promise<void> | undefined;
+export const ensureStandaloneStdlib = (): Promise<void> => {
+  if (stdlibLoad) {
+    return stdlibLoad;
+  }
+  stdlibLoad = (async () => {
+    const stdlibModule = await import("./generated/stdlib-types.json");
+    const bundle = stdlibModule.default;
+    for (const defaults of [typescriptDefaults, javascriptDefaults]) {
+      for (const [path, content] of Object.entries(bundle)) {
+        defaults.addExtraLib(content, `file:///${path}`);
+      }
+      // The @types/node + bun-types declarations now exist at their node_modules
+      // virtual paths, so include them ambiently.
+      defaults.setCompilerOptions({
+        ...BASE_COMPILER_OPTIONS,
+        types: ["node", "bun-types"],
+      });
+    }
+  })();
+  return stdlibLoad;
+};
+
+void ensureStandaloneStdlib();

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

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "bun:test";
+import { popoutTitle } from "./popoutTitle";
+import type { CodeEditorLanguage } from "./types";
+
+describe("popoutTitle", () => {
+  it("derives a script title for TypeScript", () => {
+    expect(popoutTitle({ language: "typescript" })).toBe(
+      "Edit script - TypeScript",
+    );
+  });
+
+  it("derives a script title for JavaScript", () => {
+    expect(popoutTitle({ language: "javascript" })).toBe(
+      "Edit script - JavaScript",
+    );
+  });
+
+  it("derives a script title for Shell", () => {
+    expect(popoutTitle({ language: "shell" })).toBe("Edit script - Shell");
+  });
+
+  it("falls back to a generic title for markup/text languages", () => {
+    const markupLanguages: CodeEditorLanguage[] = [
+      "json",
+      "yaml",
+      "xml",
+      "markdown",
+    ];
+    for (const language of markupLanguages) {
+      expect(popoutTitle({ language })).toBe("Edit");
+    }
+  });
+
+  it("uses a normal hyphen, never an em-dash", () => {
+    expect(popoutTitle({ language: "typescript" })).not.toContain("—");
+  });
+});

package/src/components/CodeEditor/popoutTitle.ts

@@ -0,0 +1,31 @@
+// Pure helper deriving the popout-dialog title from the editor language.
+// Kept separate (and unit-tested) so the title logic isn't buried in UI glue.
+import type { CodeEditorLanguage } from "./types";
+
+// Human-readable display name for the languages that get a script-flavoured
+// title. Markup/text languages fall through to the generic "Edit" title since
+// "script" wouldn't read correctly for them.
+const SCRIPT_LANGUAGE_LABELS: Partial<Record<CodeEditorLanguage, string>> = {
+  typescript: "TypeScript",
+  javascript: "JavaScript",
+  shell: "Shell",
+};
+
+/**
+ * Derive the overlay dialog title from the editor language.
+ *
+ * - Script languages (`typescript` / `javascript` / `shell`) read as
+ *   `Edit script - <Language>`.
+ * - Everything else (markup/text: json / yaml / xml / markdown) falls back to
+ *   the generic `Edit`.
+ *
+ * Uses a normal hyphen (not an em-dash) per the project content style.
+ */
+export const popoutTitle = ({
+  language,
+}: {
+  language: CodeEditorLanguage;
+}): string => {
+  const scriptLabel = SCRIPT_LANGUAGE_LABELS[language];
+  return scriptLabel ? `Edit script - ${scriptLabel}` : "Edit";
+};

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

@@ -52,6 +52,15 @@ describe("healthcheckScriptContext", () => {
     expect(ctx.typeDefinitions).toContain("HealthCheckScriptContext");
   });
 
+  it("exposes `context.check` and `context.system` run-context metadata", () => {
+    // The runner injects check/system metadata alongside config, so the
+    // editor must type them or `context.system.name` would error.
+    const ctx = healthcheckScriptContext({});
+    expect(ctx.typeDefinitions).toContain("readonly check: {");
+    expect(ctx.typeDefinitions).toContain("readonly system: {");
+    expect(ctx.typeDefinitions).toContain("readonly intervalSeconds: number");
+  });
+
   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
@@ -95,10 +104,42 @@ describe("healthcheckScriptContext", () => {
     expect(names).toContain("PATH");
     expect(names).toContain("HOME");
     expect(names).toContain("TZ");
+    // Run-context vars the shell collector injects are suggested too.
+    expect(names).toContain("CHECKSTACK_CHECK_NAME");
+    expect(names).toContain("CHECKSTACK_SYSTEM_NAME");
+    expect(names).toContain("CHECKSTACK_CHECK_INTERVAL_SECONDS");
     // Integration-only vars must NOT leak into the healthcheck context.
     expect(names).not.toContain("EVENT_ID");
     expect(names).not.toContain("PAYLOAD_TITLE");
   });
+
+  it("surfaces the user's custom Env (JSON) keys as shell completions", () => {
+    const ctx = healthcheckScriptContext({
+      customEnv: { API_TOKEN: "secret", "not-an-ident": "x" },
+    });
+    const names = ctx.shellEnvVars.map((v) => v.name);
+    // Valid shell identifier from the user's env is suggested...
+    expect(names).toContain("API_TOKEN");
+    // ...alongside the whitelist + reserved run-context vars.
+    expect(names).toContain("PATH");
+    expect(names).toContain("CHECKSTACK_SYSTEM_NAME");
+    // Keys that aren't valid `$NAME` identifiers are dropped.
+    expect(names).not.toContain("not-an-ident");
+    // The user's own var must be ordered ahead of the whitelist + run-context
+    // vars so it's not buried at the bottom of the suggest list.
+    expect(names.indexOf("API_TOKEN")).toBeLessThan(names.indexOf("PATH"));
+    expect(names.indexOf("API_TOKEN")).toBeLessThan(
+      names.indexOf("CHECKSTACK_SYSTEM_NAME"),
+    );
+  });
+
+  it("ignores a non-object customEnv without throwing", () => {
+    const names = healthcheckScriptContext({
+      customEnv: "not an object",
+    }).shellEnvVars.map((v) => v.name);
+    expect(names).toContain("PATH");
+    expect(names).toContain("CHECKSTACK_CHECK_ID");
+  });
 });
 
 describe("integrationScriptContext", () => {