@checkstack/ui 1.11.0 → 1.13.0

package/src/components/DynamicForm/validation.logic.ts

@@ -0,0 +1,210 @@
+import { z } from "zod";
+
+import type { JsonSchema, JsonSchemaProperty } from "./types";
+import { isValueEmpty, isFieldHiddenByCondition } from "./utils";
+
+/**
+ * A map from a field path to a human-readable validation message. The path
+ * is dot-joined (e.g. `spendCap.tokenBudget`) so it lines up with the keys
+ * DynamicForm renders for nested object fields. The top-level segment is
+ * always the form field DynamicForm shows; nested segments identify the
+ * offending sub-field for the message text.
+ */
+export type FieldErrorMap = Record<string, string>;
+
+/**
+ * Zod schema for a single zod issue as it crosses the oRPC boundary. The
+ * backend attaches the original `ZodError.issues` array to the
+ * `ORPCError.data` payload; oRPC serializes it to JSON and the client
+ * deserializes it, so we re-parse it here rather than trusting its shape.
+ * Only the fields we actually consume are required.
+ */
+const serverZodIssueSchema = z.object({
+  path: z.array(z.union([z.string(), z.number()])),
+  message: z.string(),
+});
+
+/**
+ * Zod schema for the structured validation payload the backend places on
+ * `ORPCError.data` for connection-config validation failures. `code`
+ * discriminates this payload from any other structured error data so we
+ * never mis-map an unrelated error onto form fields.
+ */
+export const serverValidationDataSchema = z.object({
+  code: z.literal("CONFIG_VALIDATION"),
+  issues: z.array(serverZodIssueSchema),
+});
+
+export type ServerValidationData = z.infer<typeof serverValidationDataSchema>;
+
+/**
+ * Parse an unknown error payload (typically `error.data` from an oRPC
+ * `ORPCError`) into the structured connection-config validation shape.
+ * Returns `undefined` when the payload is not structured config-validation
+ * data, signalling the caller to fall back to a toast/banner.
+ */
+export function parseServerValidationData(
+  data: unknown,
+): ServerValidationData | undefined {
+  const result = serverValidationDataSchema.safeParse(data);
+  return result.success ? result.data : undefined;
+}
+
+/**
+ * Map a structured server validation payload onto DynamicForm field paths.
+ *
+ * Each zod issue's `path` is joined with dots to form a field path. Only
+ * issues whose first path segment names a property that actually exists in
+ * the rendered schema are considered "mappable"; everything else (empty
+ * paths, unknown roots) is reported back as `unmapped` so the caller can
+ * surface it via the existing toast/banner instead of silently dropping it.
+ *
+ * When multiple issues target the same path, the first one wins (zod emits
+ * the most specific issue first for a given location).
+ */
+export function deriveServerFieldErrors({
+  issues,
+  schema,
+}: {
+  issues: ServerValidationData["issues"];
+  schema: JsonSchema;
+}): { mapped: FieldErrorMap; unmapped: string[] } {
+  const mapped: FieldErrorMap = {};
+  const unmapped: string[] = [];
+  const properties = schema.properties ?? {};
+
+  for (const issue of issues) {
+    const root = issue.path[0];
+    const rootKey = typeof root === "string" ? root : undefined;
+
+    if (rootKey === undefined || !(rootKey in properties)) {
+      unmapped.push(issue.message);
+      continue;
+    }
+
+    const fieldPath = issue.path.map(String).join(".");
+
+    if (mapped[fieldPath] === undefined) {
+      mapped[fieldPath] = issue.message;
+    }
+  }
+
+  return { mapped, unmapped };
+}
+
+/**
+ * Compute client-side validation problems from the JSON schema and the
+ * current form values. Mirrors the validity computation DynamicForm already
+ * does for `onValidChange`, but returns a per-field message map instead of a
+ * single boolean so the offending fields can be flagged inline. The form is
+ * considered valid exactly when this map is empty, so the same call drives
+ * both the inline errors and the `onValidChange` boolean.
+ *
+ * At minimum this flags empty REQUIRED fields (reusing {@link isValueEmpty}
+ * so the notion of "empty" stays in lock-step). Hidden and
+ * conditionally-hidden required fields are skipped because the user cannot
+ * fill them. Optional empty fields never produce an error.
+ *
+ * `keepExistingSecretFields` lists `x-secret` field keys whose value is
+ * already stored server-side (edit mode). A blank input on such a field
+ * means "keep the existing secret" - the redacted preview never returns the
+ * value, so an empty input is expected and MUST count as valid rather than a
+ * missing-required error. A blank `x-secret` field NOT in this set (create
+ * mode, or a secret that was never set) is still treated as missing-required.
+ */
+export function deriveClientFieldErrors({
+  schema,
+  value,
+  keepExistingSecretFields = [],
+}: {
+  schema: JsonSchema;
+  value: Record<string, unknown>;
+  keepExistingSecretFields?: string[];
+}): FieldErrorMap {
+  const errors: FieldErrorMap = {};
+  const properties = schema.properties;
+  if (!properties) return errors;
+
+  const keepExisting = new Set(keepExistingSecretFields);
+  const requiredKeys = schema.required ?? [];
+
+  for (const key of requiredKeys) {
+    const propSchema: JsonSchemaProperty | undefined = properties[key];
+    if (!propSchema) continue;
+
+    // Hidden fields are auto-populated; the user cannot act on them.
+    if (propSchema["x-hidden"]) continue;
+
+    const hiddenWhen = propSchema["x-hidden-when"];
+    if (hiddenWhen && isFieldHiddenByCondition(hiddenWhen, value)) continue;
+
+    if (!isValueEmpty(value[key], propSchema)) continue;
+
+    // A blank secret that already has a stored value is "keep existing",
+    // not missing-required.
+    if (propSchema["x-secret"] === true && keepExisting.has(key)) continue;
+
+    errors[key] = `${labelForKey(key)} is required.`;
+  }
+
+  return errors;
+}
+
+/**
+ * Strip blank `x-secret` fields that are flagged keep-existing from a config
+ * object before submit, so an empty input does not overwrite (clear) the
+ * stored secret. The update path treats an absent secret key as "leave the
+ * stored value untouched"; sending `""` would clear it. CREATE mode passes an
+ * empty `keepExistingSecretFields`, so nothing is stripped there.
+ */
+export function omitKeepExistingSecrets({
+  schema,
+  value,
+  keepExistingSecretFields,
+}: {
+  schema: JsonSchema;
+  value: Record<string, unknown>;
+  keepExistingSecretFields: string[];
+}): Record<string, unknown> {
+  const properties = schema.properties;
+  if (!properties || keepExistingSecretFields.length === 0) return value;
+
+  const keepExisting = new Set(keepExistingSecretFields);
+  const result: Record<string, unknown> = {};
+
+  for (const [key, fieldValue] of Object.entries(value)) {
+    const propSchema = properties[key];
+    const isBlankKeepExistingSecret =
+      propSchema?.["x-secret"] === true &&
+      keepExisting.has(key) &&
+      isValueEmpty(fieldValue, propSchema);
+    if (isBlankKeepExistingSecret) continue;
+    result[key] = fieldValue;
+  }
+
+  return result;
+}
+
+/**
+ * List the top-level `x-secret` field keys declared in a schema. The owning
+ * page uses this in EDIT mode to mark every secret field as keep-existing
+ * (their stored values are redacted out of the loaded preview, so a blank
+ * input must mean "keep existing" rather than "clear"). CREATE mode passes
+ * an empty list so blank secrets stay genuinely required.
+ */
+export function listSecretFieldKeys(schema: JsonSchema): string[] {
+  const properties = schema.properties;
+  if (!properties) return [];
+  return Object.entries(properties)
+    .filter(([, propSchema]) => propSchema["x-secret"] === true)
+    .map(([key]) => key);
+}
+
+/**
+ * Derive the human-readable label DynamicForm renders for a field key
+ * (capitalized first letter), kept in sync with the label logic in
+ * `DynamicForm.tsx` so inline messages read naturally.
+ */
+function labelForKey(key: string): string {
+  return key.charAt(0).toUpperCase() + key.slice(1);
+}

package/src/components/DynamicIcon.tsx

@@ -1,29 +1,46 @@
-import { icons, type LucideIcon } from "lucide-react";
-import { Settings } from "lucide-react";
-import type { LucideIconName } from "@checkstack/common";
+import { lazy, Suspense } from "react";
+import { Settings, type LucideIcon } from "lucide-react";
+import type { IconName, BrandIconName } from "@checkstack/common";
+import { brandIcons } from "./BrandIcon";
 
-// Re-export the type for convenience
-export type { LucideIconName } from "@checkstack/common";
+// Re-export the icon-name types for convenience.
+export type { IconName, LucideIconName } from "@checkstack/common";
 
 /**
  * Props for the DynamicIcon component
  */
 export interface DynamicIconProps {
-  /** Lucide icon name in PascalCase (e.g., 'AlertCircle', 'HeartPulse') */
-  name?: LucideIconName;
+  /**
+   * Icon name. Lucide names are PascalCase (e.g. 'CircleAlert', 'HeartPulse');
+   * the few brand names lucide v1 dropped ('Github', 'Gitlab') resolve to
+   * vendored marks.
+   */
+  name?: IconName;
   /** CSS class name to apply to the icon */
   className?: string;
   /** Fallback icon if name is not provided */
   fallback?: LucideIcon;
 }
 
+// The lucide icon set is loaded lazily through `iconRegistry` (see that file):
+// importing lucide's `icons` map eagerly would ship the entire ~1600-icon set
+// in the initial bundle. `RegistryIcon` is the only importer of that map, and
+// it's behind React.lazy, so the icon set is fetched on demand the first time a
+// data-driven icon renders - never in the initial load.
+const RegistryIcon = lazy(() => import("./iconRegistry"));
+
+function isBrandIcon(name: string): name is BrandIconName {
+  return Object.prototype.hasOwnProperty.call(brandIcons, name);
+}
+
 /**
- * Dynamically renders a Lucide icon by name.
- * Falls back to Settings icon if the icon name is not provided.
+ * Dynamically renders an icon by name. Lucide icons are code-split into a single
+ * on-demand chunk; vendored brand icons render synchronously. Falls back to the
+ * Settings icon if no name is provided.
  *
  * @example
- * <DynamicIcon name="AlertCircle" />
- * <DynamicIcon name="HeartPulse" className="h-6 w-6" />
+ * <DynamicIcon name="CircleAlert" />
+ * <DynamicIcon name="Github" className="h-6 w-6" />
  */
 export function DynamicIcon({
   name,
@@ -34,12 +51,17 @@ export function DynamicIcon({
     return <FallbackIcon className={className} />;
   }
 
-  const Icon = icons[name];
-
-  // Fallback if icon name doesn't exist in lucide-react
-  if (!Icon) {
-    return <FallbackIcon className={className} />;
+  // Brand marks lucide v1 removed - render the vendored component synchronously.
+  if (isBrandIcon(name)) {
+    const Brand = brandIcons[name];
+    return <Brand className={className} />;
   }
 
-  return <Icon className={className} />;
+  return (
+    // Invisible, correctly-sized placeholder while the icon chunk loads, so
+    // there's no layout shift and no flash of a wrong (fallback) icon.
+    <Suspense fallback={<span aria-hidden className={className} />}>
+      <RegistryIcon name={name} className={className} />
+    </Suspense>
+  );
 }

package/src/components/Markdown.tsx

@@ -1,7 +1,36 @@
 import ReactMarkdown from "react-markdown";
 import type { Components } from "react-markdown";
+import remarkGfm from "remark-gfm";
+import rehypeRaw from "rehype-raw";
+import rehypeSanitize from "rehype-sanitize";
 import { cn } from "../utils";
 
+/**
+ * Allow a SAFE subset of raw HTML in rendered markdown so model output that uses
+ * native disclosure widgets (`<details>` / `<summary>` for a foldable diff) and
+ * other plain formatting renders as intended instead of leaking the literal
+ * tags as text. `rehype-raw` parses the embedded HTML; `rehype-sanitize` then
+ * strips anything unsafe (scripts, event handlers, `javascript:` URLs, ...) - its
+ * default schema already allow-lists `details`/`summary` plus the usual markdown
+ * elements, so the XSS surface stays closed even though chat content is
+ * model-generated. Order matters: raw MUST run before sanitize.
+ */
+const rehypePlugins = [rehypeRaw, rehypeSanitize];
+
+/** Shared `<details>`/`<summary>` renderers: a styled, click-to-expand fold. */
+const disclosureComponents: Pick<Components, "details" | "summary"> = {
+  details: ({ children }) => (
+    <details className="my-2 rounded-md border border-border bg-muted/40 px-3 py-2 [&[open]>summary]:mb-2">
+      {children}
+    </details>
+  ),
+  summary: ({ children }) => (
+    <summary className="cursor-pointer select-none font-medium text-foreground marker:text-muted-foreground">
+      {children}
+    </summary>
+  ),
+};
+
 export interface MarkdownProps {
   /** The markdown content to render */
   children: string;
@@ -69,11 +98,20 @@ export function Markdown({
     del: ({ children }) => (
       <del className="line-through text-muted-foreground">{children}</del>
     ),
+
+    // Collapsible disclosure (e.g. a model-emitted "view diff" fold)
+    ...disclosureComponents,
   };
 
   return (
     <span className={cn(sizeClasses[size], className)}>
-      <ReactMarkdown components={components}>{children}</ReactMarkdown>
+      <ReactMarkdown
+        remarkPlugins={[remarkGfm]}
+        rehypePlugins={rehypePlugins}
+        components={components}
+      >
+        {children}
+      </ReactMarkdown>
     </span>
   );
 }
@@ -190,6 +228,28 @@ export function MarkdownBlock({
     del: ({ children }) => (
       <del className="line-through text-muted-foreground">{children}</del>
     ),
+
+    // GFM tables (enabled via remark-gfm). Styled to the design tokens; the
+    // wrapper scrolls horizontally so a wide table never overflows its bubble.
+    table: ({ children }) => (
+      <div className="mb-4 overflow-x-auto">
+        <table className="w-full border-collapse text-sm">{children}</table>
+      </div>
+    ),
+    thead: ({ children }) => <thead className="bg-muted">{children}</thead>,
+    tbody: ({ children }) => <tbody>{children}</tbody>,
+    tr: ({ children }) => <tr className="border-b border-border">{children}</tr>,
+    th: ({ children }) => (
+      <th className="border border-border px-2 py-1 text-left font-semibold text-foreground">
+        {children}
+      </th>
+    ),
+    td: ({ children }) => (
+      <td className="border border-border px-2 py-1 align-top">{children}</td>
+    ),
+
+    // Collapsible disclosure (e.g. a model-emitted "view diff" fold)
+    ...disclosureComponents,
   };
 
   return (
@@ -200,7 +260,13 @@ export function MarkdownBlock({
         className
       )}
     >
-      <ReactMarkdown components={components}>{children}</ReactMarkdown>
+      <ReactMarkdown
+        remarkPlugins={[remarkGfm]}
+        rehypePlugins={rehypePlugins}
+        components={components}
+      >
+        {children}
+      </ReactMarkdown>
     </div>
   );
 }

package/src/components/Popover.tsx

@@ -2,6 +2,7 @@ import * as React from "react";
 import * as PopoverPrimitive from "@radix-ui/react-popover";
 import { cn } from "../utils";
 import { usePerformance } from "./PerformanceProvider";
+import { usePortalContainer } from "./portalContainer";
 
 const Popover = PopoverPrimitive.Root;
 const PopoverTrigger = PopoverPrimitive.Trigger;
@@ -17,8 +18,12 @@ const PopoverContent = React.forwardRef<
   PopoverContentProps
 >(({ className, align = "end", sideOffset = 8, ...props }, ref) => {
   const { isLowPower } = usePerformance();
+  // When inside a modal Sheet/Dialog, portal into its content so the dialog's
+  // scroll-lock doesn't block this popover's internal scroll. Outside a
+  // Sheet/Dialog the container is null and Radix portals to `body` as usual.
+  const portalContainer = usePortalContainer();
   return (
-    <PopoverPrimitive.Portal>
+    <PopoverPrimitive.Portal container={portalContainer ?? undefined}>
       <PopoverPrimitive.Content
         ref={ref}
         align={align}

package/src/components/ScriptTestPanel.logic.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, test } from "bun:test";
+import {
+  buildSecretOverrides,
+  distinctSecretNames,
+  formatReturnValue,
+  hasNoOutput,
+  isFailedResult,
+  rejectionResult,
+  validateSampleContextJson,
+  type ScriptTestPanelResult,
+} from "./ScriptTestPanel.logic";
+
+const base: ScriptTestPanelResult = {
+  stdout: "",
+  stderr: "",
+  durationMs: 10,
+  timedOut: false,
+};
+
+describe("isFailedResult", () => {
+  test("a clean result is not a failure", () => {
+    expect(isFailedResult({ ...base, result: { ok: true } })).toBe(false);
+  });
+  test("an error result is a failure", () => {
+    expect(isFailedResult({ ...base, error: "boom" })).toBe(true);
+  });
+  test("a timed-out result is a failure", () => {
+    expect(isFailedResult({ ...base, timedOut: true })).toBe(true);
+  });
+});
+
+describe("formatReturnValue", () => {
+  test("pretty-prints an object", () => {
+    expect(formatReturnValue({ a: 1 })).toBe('{\n  "a": 1\n}');
+  });
+  test("renders undefined explicitly", () => {
+    expect(formatReturnValue(undefined)).toBe("undefined");
+  });
+  test("falls back to String() for non-serialisable values", () => {
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+    expect(formatReturnValue(circular)).toBe("[object Object]");
+  });
+});
+
+describe("hasNoOutput", () => {
+  test("true when nothing was produced", () => {
+    expect(hasNoOutput(base)).toBe(true);
+  });
+  test("false when there is a return value", () => {
+    expect(hasNoOutput({ ...base, result: null })).toBe(false);
+  });
+  test("false when there is stdout", () => {
+    expect(hasNoOutput({ ...base, stdout: "hi" })).toBe(false);
+  });
+  test("false when there is an error", () => {
+    expect(hasNoOutput({ ...base, error: "x" })).toBe(false);
+  });
+});
+
+describe("validateSampleContextJson", () => {
+  test("empty value is valid (null)", () => {
+    expect(validateSampleContextJson("   ")).toBeNull();
+  });
+  test("valid JSON is valid (null)", () => {
+    expect(validateSampleContextJson('{"a":1}')).toBeNull();
+  });
+  test("malformed JSON returns a message", () => {
+    expect(validateSampleContextJson("{ not json")).not.toBeNull();
+  });
+});
+
+describe("rejectionResult", () => {
+  test("wraps a thrown Error into a failure result", () => {
+    const r = rejectionResult(new Error("network down"));
+    expect(r.error).toBe("network down");
+    expect(isFailedResult(r)).toBe(true);
+    expect(r.timedOut).toBe(false);
+  });
+});
+
+describe("distinctSecretNames", () => {
+  test("returns [] for an absent or empty mapping", () => {
+    expect(distinctSecretNames(undefined)).toEqual([]);
+    expect(distinctSecretNames({})).toEqual([]);
+  });
+
+  test("extracts distinct secret names from templates, first-seen order", () => {
+    expect(
+      distinctSecretNames({
+        API_TOKEN: "${{ secrets.jira_token }}",
+        DB: "${{ secrets.db_pass }}",
+        ALSO: "${{ secrets.jira_token }}",
+      }),
+    ).toEqual(["jira_token", "db_pass"]);
+  });
+
+  test("tolerates a legacy bare secret name as a value", () => {
+    expect(distinctSecretNames({ secret: "SECRET" })).toEqual(["SECRET"]);
+  });
+
+  test("ignores values that are neither a template nor a bare name", () => {
+    expect(distinctSecretNames({ X: "not a name" })).toEqual([]);
+  });
+});
+
+describe("buildSecretOverrides", () => {
+  const secretEnv = {
+    API_TOKEN: "${{ secrets.jira_token }}",
+    DB: "${{ secrets.db_pass }}",
+  };
+
+  test("returns undefined when no draft is filled", () => {
+    expect(
+      buildSecretOverrides({ secretEnv, drafts: {} }),
+    ).toBeUndefined();
+    expect(
+      buildSecretOverrides({ secretEnv, drafts: { jira_token: "" } }),
+    ).toBeUndefined();
+  });
+
+  test("keeps only filled drafts for referenced names", () => {
+    expect(
+      buildSecretOverrides({
+        secretEnv,
+        drafts: { jira_token: "abc", db_pass: "" },
+      }),
+    ).toEqual({ jira_token: "abc" });
+  });
+
+  test("drops drafts for names not referenced by the mapping", () => {
+    expect(
+      buildSecretOverrides({
+        secretEnv,
+        drafts: { jira_token: "abc", stale: "leak" },
+      }),
+    ).toEqual({ jira_token: "abc" });
+  });
+});

package/src/components/ScriptTestPanel.logic.ts

@@ -0,0 +1,137 @@
+import { extractErrorMessage } from "@checkstack/common";
+
+/**
+ * Pure logic for the script-test panel, extracted so it can be unit-tested
+ * without rendering Monaco. The React component in `ScriptTestPanel.tsx`
+ * consumes these.
+ */
+
+/** Result of a single in-UI script test run (UI-side shape). */
+export interface ScriptTestPanelResult {
+  result?: unknown;
+  stdout: string;
+  stderr: string;
+  exitCode?: number;
+  durationMs: number;
+  timedOut: boolean;
+  error?: string;
+}
+
+/** A run is a failure if it errored or timed out. */
+export function isFailedResult(result: ScriptTestPanelResult): boolean {
+  return result.error !== undefined || result.timedOut;
+}
+
+/** Pretty-print a script's return value for display. */
+export function formatReturnValue(value: unknown): string {
+  if (value === undefined) return "undefined";
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * True when a result has nothing to show in the detail body (no error,
+ * no return value, no stdout/stderr) - the panel shows "No output." then.
+ */
+export function hasNoOutput(result: ScriptTestPanelResult): boolean {
+  return (
+    result.error === undefined &&
+    result.result === undefined &&
+    result.stdout.length === 0 &&
+    result.stderr.length === 0
+  );
+}
+
+/**
+ * Validate the editable sample-context JSON. Returns the parse error
+ * message, or `null` when the value is empty or valid JSON.
+ */
+export function validateSampleContextJson(value: string): string | null {
+  if (value.trim().length === 0) return null;
+  try {
+    JSON.parse(value);
+    return null;
+  } catch (error) {
+    return extractErrorMessage(error, "Invalid JSON");
+  }
+}
+
+/** Build the failure result the panel shows when `onRun` rejects. */
+export function rejectionResult(error: unknown): ScriptTestPanelResult {
+  return {
+    stdout: "",
+    stderr: "",
+    durationMs: 0,
+    timedOut: false,
+    error: extractErrorMessage(error),
+  };
+}
+
+// ─── Secret-env test overrides ──────────────────────────────────────────────
+
+const SECRET_TEMPLATE_RE = /\$\{\{\s*secrets\.([a-zA-Z0-9_-]+)\s*\}\}/g;
+// A mapping value may legacy-carry a bare secret name instead of a template.
+const BARE_SECRET_NAME_RE = /^\s*([a-zA-Z][a-zA-Z0-9_-]*)\s*$/;
+
+/**
+ * Derive the set of distinct secret NAMES referenced by a `secretEnv`
+ * mapping (`{ ENV_NAME: "${{ secrets.NAME }}" }`). Tolerates a legacy bare
+ * secret name as a value too. Order-stable (first-seen) so the override UI
+ * renders deterministically. Returns `[]` when the mapping is absent/empty.
+ */
+export function distinctSecretNames(
+  secretEnv: Record<string, string> | undefined,
+): string[] {
+  if (!secretEnv) return [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  const add = (name: string) => {
+    if (!seen.has(name)) {
+      seen.add(name);
+      out.push(name);
+    }
+  };
+  for (const value of Object.values(secretEnv)) {
+    SECRET_TEMPLATE_RE.lastIndex = 0;
+    let matched = false;
+    let match: RegExpExecArray | null;
+    while ((match = SECRET_TEMPLATE_RE.exec(value)) !== null) {
+      matched = true;
+      add(match[1]);
+    }
+    if (!matched) {
+      const bare = BARE_SECRET_NAME_RE.exec(value);
+      if (bare) add(bare[1]);
+    }
+  }
+  return out;
+}
+
+/**
+ * Build the `secretOverrides` payload sent to the test endpoint from the
+ * user's per-secret-NAME draft inputs. Drops blank entries (an empty
+ * override means "use the placeholder") and keeps only names actually
+ * referenced by the mapping, so a stale draft can't inject an unreferenced
+ * value. Returns `undefined` when nothing is overridden so the wire stays
+ * clean.
+ */
+export function buildSecretOverrides({
+  secretEnv,
+  drafts,
+}: {
+  secretEnv: Record<string, string> | undefined;
+  drafts: Record<string, string>;
+}): Record<string, string> | undefined {
+  const names = distinctSecretNames(secretEnv);
+  const out: Record<string, string> = {};
+  for (const name of names) {
+    const value = drafts[name];
+    if (value !== undefined && value.length > 0) {
+      out[name] = value;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}