@mrclrchtr/supi-consulting 0.0.0-stage → 9.0.0

package/node_modules/@mrclrchtr/supi-core/src/config/config.ts

@@ -0,0 +1,342 @@
+// Shared config system for SuPi extensions.
+//
+// Global config: ~/.pi/agent/supi/config.json
+// Project config: .pi/supi/config.json (relative to cwd)
+// Resolution: hardcoded defaults ← global ← project
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+
+const GLOBAL_CONFIG_DIR = `${CONFIG_DIR_NAME}/agent/supi`;
+const PROJECT_CONFIG_DIR = `${CONFIG_DIR_NAME}/supi`;
+const CONFIG_FILE = "config.json";
+
+function getGlobalConfigPath(homeDir?: string): string {
+  return path.join(homeDir ?? os.homedir(), GLOBAL_CONFIG_DIR, CONFIG_FILE);
+}
+
+function getProjectConfigPath(cwd: string): string {
+  return path.join(cwd, PROJECT_CONFIG_DIR, CONFIG_FILE);
+}
+
+/** Return the SuPi config file path for one scope. */
+export function getSupiConfigPath(
+  scope: "global" | "project",
+  cwd: string,
+  options?: SupiConfigOptions,
+): string {
+  return scope === "global" ? getGlobalConfigPath(options?.homeDir) : getProjectConfigPath(cwd);
+}
+
+export function readJsonFile(filePath: string): Record<string, unknown> | null {
+  let content: string;
+  try {
+    content = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    // ENOENT or permission error — silent, file may not exist
+    return null;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    // biome-ignore lint/suspicious/noConsole: deliberate config parse warning
+    console.warn(`[supi-core] Failed to parse config file, ignoring: ${filePath}`);
+    return null;
+  }
+
+  if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+    return parsed as Record<string, unknown>;
+  }
+
+  // biome-ignore lint/suspicious/noConsole: deliberate config parse warning
+  console.warn(`[supi-core] Config file root is not an object, ignoring: ${filePath}`);
+  return null;
+}
+
+function shallowMerge<T>(base: T, ...overrides: Array<Record<string, unknown> | null>): T {
+  let result = { ...base };
+  for (const override of overrides) {
+    if (!override) continue;
+    result = { ...result, ...override };
+  }
+  return result;
+}
+
+export interface SupiConfigOptions {
+  homeDir?: string;
+}
+
+/** Options for loading automatic code-intelligence exclusions. */
+export interface AutomaticExclusionOptions extends SupiConfigOptions {
+  /** Whether the project config is trusted and can apply. Defaults to true. */
+  projectTrusted?: boolean;
+}
+
+/**
+ * Load the one configured exclusion list shared by automatic LSP work and
+ * broad AST searches.
+ *
+ * Project values replace global values. An explicit empty project list clears
+ * the global list. The old `lsp.exclude` key is rejected in every applicable
+ * scope so automatic work cannot start without its former protection.
+ */
+export function loadAutomaticExclusionPatterns(
+  cwd: string,
+  options: AutomaticExclusionOptions = {},
+): readonly string[] {
+  const projectTrusted = options.projectTrusted !== false;
+  const globalCodeIntelligence = loadSupiConfigSectionForScope("code-intelligence", cwd, {
+    scope: "global",
+    homeDir: options.homeDir,
+  });
+  const projectCodeIntelligence = projectTrusted
+    ? loadSupiConfigSectionForScope("code-intelligence", cwd, { scope: "project" })
+    : null;
+  const globalLsp = loadSupiConfigSectionForScope("lsp", cwd, {
+    scope: "global",
+    homeDir: options.homeDir,
+  });
+  const projectLsp = projectTrusted
+    ? loadSupiConfigSectionForScope("lsp", cwd, { scope: "project" })
+    : null;
+
+  const legacyPath = findLegacyExclusionPath(cwd, options, globalLsp, projectLsp);
+  if (legacyPath) {
+    throw new Error(
+      `Unsupported ${legacyPath.scope} configuration at ${legacyPath.path}: "lsp.exclude" was removed. Move its value to "code-intelligence.exclude". Automatic LSP and broad AST work did not start; reload after migration.`,
+    );
+  }
+
+  const source = findExclusionSource(cwd, options, {
+    projectTrusted,
+    globalCodeIntelligence,
+    projectCodeIntelligence,
+  });
+  return validateExclusionSource(source);
+}
+
+interface ExclusionSource {
+  value: unknown;
+  path: string;
+}
+
+interface LegacyExclusionPath {
+  scope: "global" | "project";
+  path: string;
+}
+
+function findLegacyExclusionPath(
+  cwd: string,
+  options: AutomaticExclusionOptions,
+  globalLsp: Record<string, unknown> | null,
+  projectLsp: Record<string, unknown> | null,
+): LegacyExclusionPath | null {
+  if (globalLsp && Object.hasOwn(globalLsp, "exclude")) {
+    return { scope: "global", path: getSupiConfigPath("global", cwd, options) };
+  }
+  if (projectLsp && Object.hasOwn(projectLsp, "exclude")) {
+    return { scope: "project", path: getSupiConfigPath("project", cwd) };
+  }
+  return null;
+}
+
+function findExclusionSource(
+  cwd: string,
+  options: AutomaticExclusionOptions,
+  sections: {
+    projectTrusted: boolean;
+    globalCodeIntelligence: Record<string, unknown> | null;
+    projectCodeIntelligence: Record<string, unknown> | null;
+  },
+): ExclusionSource | null {
+  const { projectTrusted, globalCodeIntelligence, projectCodeIntelligence } = sections;
+  if (
+    projectTrusted &&
+    projectCodeIntelligence &&
+    Object.hasOwn(projectCodeIntelligence, "exclude")
+  ) {
+    return { value: projectCodeIntelligence.exclude, path: getSupiConfigPath("project", cwd) };
+  }
+  if (globalCodeIntelligence && Object.hasOwn(globalCodeIntelligence, "exclude")) {
+    return {
+      value: globalCodeIntelligence.exclude,
+      path: getSupiConfigPath("global", cwd, options),
+    };
+  }
+  return null;
+}
+
+function validateExclusionSource(source: ExclusionSource | null): readonly string[] {
+  if (!source) return Object.freeze([]);
+  if (!Array.isArray(source.value) || !source.value.every((entry) => typeof entry === "string")) {
+    throw new Error(
+      `Invalid "code-intelligence.exclude" in ${source.path}: expected an array of gitignore-style strings. Automatic LSP and broad AST work did not start.`,
+    );
+  }
+  return Object.freeze([...source.value]);
+}
+
+/**
+ * Load and merge config for a given extension section.
+ *
+ * Resolution order: defaults ← global ← project
+ */
+export function loadSupiConfig<T>(
+  section: string,
+  cwd: string,
+  defaults: T,
+  options?: SupiConfigOptions,
+): T {
+  const globalConfig = readJsonFile(getGlobalConfigPath(options?.homeDir));
+  const projectConfig = readJsonFile(getProjectConfigPath(cwd));
+
+  const globalSection = extractSection(globalConfig, section);
+  const projectSection = extractSection(projectConfig, section);
+
+  return shallowMerge(defaults, globalSection, projectSection);
+}
+
+/**
+ * Load config for a single scope only.
+ *
+ * Resolution order: defaults ← selected scope
+ *
+ * This is useful for settings UIs that need to show the raw values stored in
+ * one scope, rather than the effective merged config.
+ */
+export function loadSupiConfigForScope<T>(
+  section: string,
+  cwd: string,
+  defaults: T,
+  options: { scope: "global" | "project" } & SupiConfigOptions,
+): T {
+  const config = readJsonFile(getSupiConfigPath(options.scope, cwd, { homeDir: options.homeDir }));
+
+  const scopedSection = extractSection(config, section);
+  return shallowMerge(defaults, scopedSection);
+}
+
+/** Load the raw object for one config section and one scope. */
+export function loadSupiConfigSectionForScope(
+  section: string,
+  cwd: string,
+  options: { scope: "global" | "project" } & SupiConfigOptions,
+): Record<string, unknown> | null {
+  const config = readJsonFile(getSupiConfigPath(options.scope, cwd, { homeDir: options.homeDir }));
+  return extractSection(config, section);
+}
+
+export interface SupiConfigLocation {
+  section: string;
+  scope: "global" | "project";
+  cwd: string;
+}
+
+/**
+ * Write config values for a given extension section.
+ */
+export function writeSupiConfig(
+  loc: SupiConfigLocation,
+  value: Record<string, unknown>,
+  options?: SupiConfigOptions,
+): void {
+  const configPath = getSupiConfigPath(loc.scope, loc.cwd, options);
+
+  const dir = path.dirname(configPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const existing = readJsonFile(configPath) ?? {};
+  existing[loc.section] = {
+    ...((existing[loc.section] as Record<string, unknown>) ?? {}),
+    ...value,
+  };
+
+  fs.writeFileSync(configPath, `${JSON.stringify(existing, null, 2)}\n`, "utf-8");
+}
+
+/**
+ * Replace one complete config section while preserving other sections.
+ *
+ * This is useful for nested settings that must remove stale keys as part of
+ * one update. An empty section is removed from the config file.
+ */
+export function replaceSupiConfigSection(
+  loc: SupiConfigLocation,
+  value: Record<string, unknown>,
+  options?: SupiConfigOptions,
+): void {
+  const configPath = getSupiConfigPath(loc.scope, loc.cwd, options);
+  const existing = readJsonFile(configPath) ?? {};
+
+  if (Object.keys(value).length > 0) existing[loc.section] = value;
+  else delete existing[loc.section];
+
+  const content = Object.keys(existing).length > 0 ? `${JSON.stringify(existing, null, 2)}\n` : "";
+  if (content) {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, content, "utf-8");
+    return;
+  }
+
+  try {
+    fs.unlinkSync(configPath);
+  } catch {
+    // File may not exist.
+  }
+}
+
+/**
+ * Remove a key from a config section.
+ * Used by `interval default` to remove the project override.
+ */
+export function removeSupiConfigKey(
+  loc: SupiConfigLocation,
+  key: string,
+  options?: SupiConfigOptions,
+): void {
+  const configPath = getSupiConfigPath(loc.scope, loc.cwd, options);
+
+  const existing = readJsonFile(configPath);
+  if (!existing) return;
+
+  const sectionData = existing[loc.section] as Record<string, unknown> | undefined;
+  if (!sectionData) return;
+
+  delete sectionData[key];
+
+  if (Object.keys(sectionData).length === 0) {
+    delete existing[loc.section];
+  }
+
+  const dir = path.dirname(configPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const content = Object.keys(existing).length > 0 ? `${JSON.stringify(existing, null, 2)}\n` : "";
+
+  if (content) {
+    // Directory guaranteed to exist since we just read from it
+    fs.writeFileSync(configPath, content, "utf-8");
+  } else {
+    try {
+      fs.unlinkSync(configPath);
+    } catch {
+      // File may not exist
+    }
+  }
+}
+
+function extractSection(
+  config: Record<string, unknown> | null,
+  section: string,
+): Record<string, unknown> | null {
+  if (!config) return null;
+  const data = config[section];
+  if (typeof data === "object" && data !== null && !Array.isArray(data)) {
+    return data as Record<string, unknown>;
+  }
+  return null;
+}

package/node_modules/@mrclrchtr/supi-core/src/config/prompt-surface.ts

@@ -0,0 +1,363 @@
+// Configurable tool prompt-surface overrides.
+//
+// Resolution order: package defaults ← global SuPi config ← trusted project SuPi config.
+// Project overrides are trust-gated; they require PI project trust and a PI-recognized
+// trust-requiring resource (e.g. .pi/settings.json).
+
+import {
+  type ExtensionContext,
+  hasTrustRequiringProjectResources,
+} from "@earendil-works/pi-coding-agent";
+import { loadSupiConfigSectionForScope, type SupiConfigOptions } from "./config.ts";
+
+// ── Public types ───────────────────────────────────────────────────────────
+
+/** Model-facing text that PI adds to one registered tool's prompt surface. */
+export interface SuiPiToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
+
+export type ToolPromptSurfaceDiagnosticCode =
+  | "invalidPromptSurfaceConfig"
+  | "invalidPromptSurfaceField"
+  | "projectPromptSurfaceIgnored";
+
+export interface ToolPromptSurfaceDiagnostic {
+  code: ToolPromptSurfaceDiagnosticCode;
+  scope: "global" | "project";
+  section: string;
+  toolName: string;
+  message: string;
+}
+
+export interface ResolveToolPromptSurfaceOptions extends SupiConfigOptions {
+  section: string;
+  toolName: string;
+  defaults: SuiPiToolPromptSurface;
+  ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">;
+}
+
+export interface ResolveToolPromptSurfaceResult {
+  surface: SuiPiToolPromptSurface;
+  diagnostics: ToolPromptSurfaceDiagnostic[];
+}
+
+// ── Private types ──────────────────────────────────────────────────────────
+
+type PromptSurfaceField = keyof SuiPiToolPromptSurface;
+type PromptSurfaceScope = ToolPromptSurfaceDiagnostic["scope"];
+
+const PROMPT_SURFACE_FIELDS = new Set<string>(["description", "promptSnippet", "promptGuidelines"]);
+
+const PROMPT_SURFACE_DIAGNOSTICS_KEY = Symbol.for(
+  "@mrclrchtr/supi-core/tool-prompt-surface/notified-diagnostics",
+);
+
+// ── Resolution ─────────────────────────────────────────────────────────────
+
+/** Resolve a tool's model-facing prompt surface from defaults + SuPi config overrides. */
+export function resolveToolPromptSurface(
+  options: ResolveToolPromptSurfaceOptions,
+): ResolveToolPromptSurfaceResult {
+  const diagnostics: ToolPromptSurfaceDiagnostic[] = [];
+  let surface = clonePromptSurface(options.defaults);
+
+  const globalSection = loadSupiConfigSectionForScope(options.section, options.ctx.cwd, {
+    scope: "global",
+    homeDir: options.homeDir,
+  });
+  surface = applyPromptSurfaceScope(surface, options, "global", globalSection, diagnostics);
+
+  const projectSection = loadSupiConfigSectionForScope(options.section, options.ctx.cwd, {
+    scope: "project",
+    homeDir: options.homeDir,
+  });
+  const projectPromptSurface = getPromptSurfaceConfig(projectSection, options.toolName, {
+    diagnostics,
+    options,
+    scope: "project",
+  });
+
+  if (projectPromptSurface) {
+    const hasTrustMarker = hasTrustRequiringProjectResources(options.ctx.cwd);
+    const projectTrusted = options.ctx.isProjectTrusted();
+    if (hasTrustMarker && projectTrusted) {
+      surface = applyPromptSurfaceConfig(
+        surface,
+        options.defaults,
+        projectPromptSurface,
+        options,
+        "project",
+        diagnostics,
+      );
+    } else {
+      diagnostics.push({
+        code: "projectPromptSurfaceIgnored",
+        scope: "project",
+        section: options.section,
+        toolName: options.toolName,
+        message: hasTrustMarker
+          ? `Project prompt-surface overrides for ${options.toolName} were ignored because the project is not trusted in PI.`
+          : `Project prompt-surface overrides for ${options.toolName} were ignored because ${options.ctx.cwd}/.pi/supi/config.json is not PI trust-gated. Add .pi/settings.json and trust the project to enable them.`,
+      });
+    }
+  }
+
+  return { surface, diagnostics };
+}
+
+/** Notify prompt-surface diagnostics once per session/tool/diagnostic code. */
+export function notifyToolPromptSurfaceDiagnostics(
+  ctx: Pick<ExtensionContext, "sessionManager" | "ui">,
+  diagnostics: readonly ToolPromptSurfaceDiagnostic[],
+): void {
+  const globalRecord = globalThis as Record<symbol, Set<string> | undefined>;
+  const notified = globalRecord[PROMPT_SURFACE_DIAGNOSTICS_KEY] ?? new Set<string>();
+  globalRecord[PROMPT_SURFACE_DIAGNOSTICS_KEY] = notified;
+  const sessionId = ctx.sessionManager.getSessionId();
+
+  for (const diagnostic of diagnostics) {
+    const key = `${sessionId}:${diagnostic.section}:${diagnostic.toolName}:${diagnostic.code}`;
+    if (notified.has(key)) continue;
+    notified.add(key);
+    ctx.ui.notify(diagnostic.message, "warning");
+  }
+}
+
+// ── Scope helpers ──────────────────────────────────────────────────────────
+
+// biome-ignore lint/complexity/useMaxParams: resolver dispatch with diagnostics
+function applyPromptSurfaceScope(
+  current: SuiPiToolPromptSurface,
+  options: ResolveToolPromptSurfaceOptions,
+  scope: PromptSurfaceScope,
+  sectionConfig: Record<string, unknown> | null,
+  diagnostics: ToolPromptSurfaceDiagnostic[],
+): SuiPiToolPromptSurface {
+  const promptSurface = getPromptSurfaceConfig(sectionConfig, options.toolName, {
+    diagnostics,
+    options,
+    scope,
+  });
+  if (!promptSurface) return current;
+  return applyPromptSurfaceConfig(
+    current,
+    options.defaults,
+    promptSurface,
+    options,
+    scope,
+    diagnostics,
+  );
+}
+
+// biome-ignore lint/complexity/useMaxParams: per-scope config merger with diagnostics
+function applyPromptSurfaceConfig(
+  current: SuiPiToolPromptSurface,
+  defaults: SuiPiToolPromptSurface,
+  config: Record<string, unknown>,
+  options: ResolveToolPromptSurfaceOptions,
+  scope: PromptSurfaceScope,
+  diagnostics: ToolPromptSurfaceDiagnostic[],
+): SuiPiToolPromptSurface {
+  let next = clonePromptSurface(current);
+
+  for (const field of getResetFields(config.$reset, options, scope, diagnostics)) {
+    next = { ...next, [field]: clonePromptSurfaceField(defaults[field]) };
+  }
+
+  const description = getOptionalNonEmptyString(
+    config.description,
+    "description",
+    options,
+    scope,
+    diagnostics,
+  );
+  if (description !== undefined) next.description = description;
+
+  const promptSnippet = getOptionalNonEmptyString(
+    config.promptSnippet,
+    "promptSnippet",
+    options,
+    scope,
+    diagnostics,
+  );
+  if (promptSnippet !== undefined) next.promptSnippet = promptSnippet;
+
+  const promptGuidelines = getOptionalStringArray(
+    config.promptGuidelines,
+    "promptGuidelines",
+    options,
+    scope,
+    diagnostics,
+  );
+  if (promptGuidelines !== undefined) next.promptGuidelines = promptGuidelines;
+
+  const prepend = getOptionalStringArray(
+    config.prependPromptGuidelines,
+    "prependPromptGuidelines",
+    options,
+    scope,
+    diagnostics,
+  );
+  if (prepend !== undefined) next.promptGuidelines = [...prepend, ...next.promptGuidelines];
+
+  const append = getOptionalStringArray(
+    config.appendPromptGuidelines,
+    "appendPromptGuidelines",
+    options,
+    scope,
+    diagnostics,
+  );
+  if (append !== undefined) next.promptGuidelines = [...next.promptGuidelines, ...append];
+
+  return next;
+}
+
+// ── Config extraction ──────────────────────────────────────────────────────
+
+function getPromptSurfaceConfig(
+  sectionConfig: Record<string, unknown> | null,
+  toolName: string,
+  deps: {
+    diagnostics: ToolPromptSurfaceDiagnostic[];
+    options: ResolveToolPromptSurfaceOptions;
+    scope: PromptSurfaceScope;
+  },
+): Record<string, unknown> | null {
+  if (!sectionConfig) return null;
+  if (sectionConfig.tools === undefined) return null;
+  if (!isRecord(sectionConfig.tools)) {
+    pushInvalidConfig(deps, "tools must be an object.");
+    return null;
+  }
+  const toolConfig = sectionConfig.tools[toolName];
+  if (toolConfig === undefined) return null;
+  if (!isRecord(toolConfig)) {
+    pushInvalidConfig(deps, `tools.${toolName} must be an object.`);
+    return null;
+  }
+  if (toolConfig.promptSurface === undefined) return null;
+  if (!isRecord(toolConfig.promptSurface)) {
+    pushInvalidConfig(deps, `tools.${toolName}.promptSurface must be an object.`);
+    return null;
+  }
+  return toolConfig.promptSurface;
+}
+
+// ── Field validation ───────────────────────────────────────────────────────
+
+function getResetFields(
+  value: unknown,
+  options: ResolveToolPromptSurfaceOptions,
+  scope: PromptSurfaceScope,
+  diagnostics: ToolPromptSurfaceDiagnostic[],
+): PromptSurfaceField[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    pushInvalidField(options, scope, diagnostics, "$reset", "must be an array.");
+    return [];
+  }
+  const fields: PromptSurfaceField[] = [];
+  for (const item of value) {
+    if (typeof item === "string" && PROMPT_SURFACE_FIELDS.has(item)) {
+      fields.push(item as PromptSurfaceField);
+    } else {
+      pushInvalidField(
+        options,
+        scope,
+        diagnostics,
+        "$reset",
+        `contains unsupported field ${JSON.stringify(item)}.`,
+      );
+    }
+  }
+  return fields;
+}
+
+// biome-ignore lint/complexity/useMaxParams: validation helper with diagnostics
+function getOptionalNonEmptyString(
+  value: unknown,
+  field: string,
+  options: ResolveToolPromptSurfaceOptions,
+  scope: PromptSurfaceScope,
+  diagnostics: ToolPromptSurfaceDiagnostic[],
+): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === "string" && value.length > 0) return value;
+  pushInvalidField(options, scope, diagnostics, field, "must be a non-empty string.");
+  return undefined;
+}
+
+// biome-ignore lint/complexity/useMaxParams: validation helper with diagnostics
+function getOptionalStringArray(
+  value: unknown,
+  field: string,
+  options: ResolveToolPromptSurfaceOptions,
+  scope: PromptSurfaceScope,
+  diagnostics: ToolPromptSurfaceDiagnostic[],
+): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+    return [...value];
+  }
+  pushInvalidField(options, scope, diagnostics, field, "must be an array of strings.");
+  return undefined;
+}
+
+// ── Diagnostics ────────────────────────────────────────────────────────────
+
+function pushInvalidConfig(
+  deps: {
+    diagnostics: ToolPromptSurfaceDiagnostic[];
+    options: ResolveToolPromptSurfaceOptions;
+    scope: PromptSurfaceScope;
+  },
+  detail: string,
+): void {
+  deps.diagnostics.push({
+    // biome-ignore lint/security/noSecrets: false positive on string constant
+    code: "invalidPromptSurfaceConfig",
+    scope: deps.scope,
+    section: deps.options.section,
+    toolName: deps.options.toolName,
+    message: `Invalid prompt-surface config for ${deps.options.section}.${deps.options.toolName}: ${detail}`,
+  });
+}
+
+// biome-ignore lint/complexity/useMaxParams: diagnostics utility with many fields
+function pushInvalidField(
+  options: ResolveToolPromptSurfaceOptions,
+  scope: PromptSurfaceScope,
+  diagnostics: ToolPromptSurfaceDiagnostic[],
+  field: string,
+  detail: string,
+): void {
+  diagnostics.push({
+    // biome-ignore lint/security/noSecrets: false positive on string constant
+    code: "invalidPromptSurfaceField",
+    scope,
+    section: options.section,
+    toolName: options.toolName,
+    message: `Invalid prompt-surface field ${field} for ${options.section}.${options.toolName}: ${detail}`,
+  });
+}
+
+// ── Cloning ────────────────────────────────────────────────────────────────
+
+function clonePromptSurface(surface: SuiPiToolPromptSurface): SuiPiToolPromptSurface {
+  return {
+    description: surface.description,
+    promptSnippet: surface.promptSnippet,
+    promptGuidelines: [...surface.promptGuidelines],
+  };
+}
+
+function clonePromptSurfaceField<T extends string | string[]>(value: T): T {
+  return (Array.isArray(value) ? [...value] : value) as T;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}