@skaile/forge-settings 0.0.0-stage → 1.0.0

package/src/runtime/server/harness-settings.ts

@@ -0,0 +1,373 @@
+/**
+ * Harness settings — the one implementation both forge hosts share.
+ *
+ * A harness is a coding-agent product; `@skaile/workspaces` 6 names the adapter
+ * that runs it the same way (`listHarnesses()`), and the selecting settings key
+ * is `harness`.
+ *
+ * What lives here, so hosts only read and write their own storage:
+ *
+ * - {@link validateHarnessSettingsPatch} — the rule set for a harness settings
+ *   write (`harness`, `harnessModels`, `harnessProviders`, `enabledHarnesses`,
+ *   `lock*`), as a pure function over the request body and the stored state.
+ * - {@link resolveLockFlags} — the admin lock flags in force. Locks are
+ *   `settings.json` fields only; there is no environment override.
+ * - {@link applyHarnessLayers} — which harness, model and provider pick a
+ *   session starts with, given the settings layers the host read.
+ * - {@link enabledHarnessIds} / {@link buildHarnessRows} — the harness catalog
+ *   `GET /api/agents` serves.
+ *
+ * Pure functions over plain values: no Node built-ins, no environment, no file access.
+ */
+
+import type { HarnessInfo } from "@skaile/workspaces/types";
+import {
+  DEFAULT_ENABLED_HARNESSES,
+  HARNESS_LABELS,
+  isExperimentalHarness,
+} from "../shared/harnesses";
+import type { SkaileSettings } from "../shared/settings-types";
+
+/** The slice of {@link SkaileSettings} that selects, configures and locks harnesses. */
+export type HarnessSettings = Pick<
+  SkaileSettings,
+  | "harness"
+  | "harnessModels"
+  | "harnessProviders"
+  | "enabledHarnesses"
+  | "lockHarness"
+  | "lockProvider"
+  | "lockModel"
+  | "lockAudio"
+>;
+
+/** One lock flag and where its value comes from. */
+export type LockFlagStatus = { value: boolean; source: "settings" | "default" };
+
+/** The admin lock flags in force on an instance. */
+export type LockFlags = {
+  harness: LockFlagStatus;
+  provider: LockFlagStatus;
+  model: LockFlagStatus;
+  audio: LockFlagStatus;
+};
+
+/** Stored `lock*` setting → the {@link LockFlags} member it controls. */
+const LOCK_FIELDS = [
+  ["lockHarness", "harness"],
+  ["lockProvider", "provider"],
+  ["lockModel", "model"],
+  ["lockAudio", "audio"],
+] as const satisfies ReadonlyArray<readonly [keyof HarnessSettings, keyof LockFlags]>;
+
+/**
+ * The lock flags a stored settings document carries: a boolean `lock*` field is
+ * `{ value, source: "settings" }`, anything else `{ value: false, source:
+ * "default" }`. Pass the instance settings (locks describe the instance, not a
+ * workspace or a user).
+ */
+export function resolveLockFlags(stored: Partial<HarnessSettings> | null | undefined): LockFlags {
+  const flag = (value: unknown): LockFlagStatus =>
+    typeof value === "boolean"
+      ? { value, source: "settings" }
+      : { value: false, source: "default" };
+  return {
+    harness: flag(stored?.lockHarness),
+    provider: flag(stored?.lockProvider),
+    model: flag(stored?.lockModel),
+    audio: flag(stored?.lockAudio),
+  };
+}
+
+/**
+ * The harness ids this instance offers: its `enabledHarnesses`, else
+ * {@link DEFAULT_ENABLED_HARNESSES}. A missing or empty list means the default
+ * set.
+ */
+export function enabledHarnessIds(s: Pick<HarnessSettings, "enabledHarnesses">): string[] {
+  return s.enabledHarnesses?.length ? s.enabledHarnesses : [...DEFAULT_ENABLED_HARNESSES];
+}
+
+/** A `GET /api/agents` row: the harness's own info plus how this instance presents it. */
+export type HarnessRow = HarnessInfo & {
+  /** Display label ({@link HARNESS_LABELS}, else the harness's own `name`). */
+  label: string;
+  /** Outside {@link DEFAULT_ENABLED_HARNESSES}: opt-in only. */
+  experimental: boolean;
+  /** Whether the instance's `enabledHarnesses` offers it. */
+  enabled: boolean;
+};
+
+/**
+ * The rows of `GET /api/agents`: one per harness, in `harnesses` order. Hosts
+ * filter to `enabled` unless the request asked for all (`?all=1`).
+ * `surfaces` and `providerPlurality` ride along from {@link HarnessInfo} so the
+ * Harness tab can offer each harness only the providers it can use.
+ */
+export function buildHarnessRows(
+  harnesses: HarnessInfo[],
+  s: Pick<HarnessSettings, "enabledHarnesses">,
+): HarnessRow[] {
+  const enabled = new Set(enabledHarnessIds(s));
+  return harnesses.map((info) => ({
+    ...info,
+    label: HARNESS_LABELS[info.id] ?? info.name,
+    experimental: isExperimentalHarness(info.id),
+    enabled: enabled.has(info.id),
+  }));
+}
+
+// ── validateHarnessSettingsPatch ────────────────────────────────────────────
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** A non-empty string, else undefined. */
+const nonEmpty = (value: unknown): string | undefined =>
+  typeof value === "string" && value ? value : undefined;
+
+/** `"providerId/modelId"` with both halves non-empty. */
+function isModelSelector(value: string): boolean {
+  const slash = value.indexOf("/");
+  return slash > 0 && slash < value.length - 1;
+}
+
+/** The non-empty string entries of an object value. */
+function stringEntries(value: unknown): Record<string, string> {
+  const entries: Record<string, string> = {};
+  if (!isObject(value)) return entries;
+  for (const [id, entry] of Object.entries(value))
+    if (typeof entry === "string" && entry) entries[id] = entry;
+  return entries;
+}
+
+function sameEntries(a: Record<string, string>, b: Record<string, string>): boolean {
+  const keys = Object.keys(a);
+  return keys.length === Object.keys(b).length && keys.every((key) => a[key] === b[key]);
+}
+
+/** The non-empty, deduplicated id lists of an object value (the provider pick per harness). */
+function idLists(value: unknown): Record<string, string[]> {
+  const lists: Record<string, string[]> = {};
+  if (!isObject(value)) return lists;
+  for (const [harnessId, ids] of Object.entries(value)) {
+    if (!Array.isArray(ids)) continue;
+    const kept = [
+      ...new Set(ids.filter((id): id is string => typeof id === "string" && id !== "")),
+    ];
+    if (kept.length) lists[harnessId] = kept;
+  }
+  return lists;
+}
+
+function sameIdLists(a: Record<string, string[]>, b: Record<string, string[]>): boolean {
+  const keys = Object.keys(a);
+  return (
+    keys.length === Object.keys(b).length &&
+    keys.every(
+      (key) =>
+        b[key] !== undefined &&
+        a[key]!.length === b[key].length &&
+        a[key]!.every((id, i) => id === b[key]![i]),
+    )
+  );
+}
+
+/** What {@link validateHarnessSettingsPatch} hands back for a valid body. */
+export type HarnessSettingsPatch = {
+  /**
+   * The fields to write; a key whose value is `undefined` is removed from the
+   * stored document. Only fields that carry something to write appear.
+   */
+  patch: Partial<HarnessSettings>;
+  /**
+   * Whether the effective `harness`, `harnessModels`, `harnessProviders` or
+   * `enabledHarnesses` changed, i.e. whether running sessions now run on stale
+   * defaults and the host should stop them.
+   */
+  sessionAffecting: boolean;
+};
+
+/**
+ * Validate the harness part of a settings write and compute what to store.
+ * Keys outside the harness set are ignored — the host validates its own.
+ *
+ * - `model`: refused — the model is set per harness (`harnessModels`).
+ * - `harness`: a catalog harness id that is enabled; empty/null removes it
+ *   (→ `"omp"`). The body key `driver` (the pre-6.0 spelling) is an alias for
+ *   one major: it is validated the same way and stored as `harness`. When both
+ *   keys are present `harness` wins.
+ * - `harnessModels`: patched per harness id (catalog ids only); a value is a
+ *   `providerId/modelId` selector, an empty string removes that harness's entry.
+ * - `harnessProviders`: the registry entry ids picked per harness id. The modal
+ *   sends the whole map, so it replaces the stored one: each value must be an
+ *   array of strings (empty strings are dropped, duplicates collapse, order is
+ *   kept), a harness whose array ends up empty is removed from the map, and the
+ *   key appears in `patch` only when the map changed. Ids are not checked
+ *   against the registry — a pick that is no longer eligible is shown as stale
+ *   in the modal.
+ * - `enabledHarnesses`: catalog ids, always including the resulting `harness`.
+ * - `lockHarness` / `lockProvider` / `lockModel` / `lockAudio`: booleans,
+ *   written only when they differ from `ctx.locks`.
+ *
+ * `ctx.locks` is used only to skip no-op lock writes; it is **not** enforced
+ * here. Whether the caller may write at all (admin, instance scope) and
+ * whether a locked field may be overridden is the host's decision, made before
+ * this runs.
+ *
+ * @param body the request body, untrusted.
+ * @param ctx.catalog valid harness ids (`listHarnesses().map(d => d.id)`).
+ * @param ctx.current the stored settings the patch applies to (the instance file).
+ * @param ctx.locks the lock flags in force ({@link resolveLockFlags} of `current`).
+ * @returns the patch, or the error message of the first violated rule (a
+ * string, mirroring `validateEnvSettingsUpdate`; hosts answer 400 with it).
+ */
+export function validateHarnessSettingsPatch(
+  body: unknown,
+  ctx: { catalog: Iterable<string>; current: HarnessSettings; locks: LockFlags },
+): HarnessSettingsPatch | string {
+  if (!isObject(body)) return "body must be an object";
+  if ("model" in body) return "model is set per harness - use harnessModels";
+
+  const { current, locks } = ctx;
+  const catalog = new Set(ctx.catalog);
+  const patch: Partial<HarnessSettings> = {};
+  let sessionAffecting = false;
+
+  const currentHarness = nonEmpty(current.harness) ?? "omp";
+  let nextHarness = currentHarness;
+  const harnessKey = "harness" in body ? "harness" : "driver" in body ? "driver" : undefined;
+  if (harnessKey) {
+    const raw = body[harnessKey];
+    if (raw !== null && raw !== undefined && typeof raw !== "string")
+      return `${harnessKey} must be a string`;
+    const value = typeof raw === "string" ? raw.trim() : "";
+    if (value && !catalog.has(value)) return `Unknown harness "${value}"`;
+    patch.harness = value || undefined;
+    nextHarness = value || "omp";
+    if (nextHarness !== currentHarness) sessionAffecting = true;
+  }
+
+  if ("harnessModels" in body) {
+    const raw = body.harnessModels;
+    if (!isObject(raw)) return "harnessModels must be an object";
+    const currentModels = stringEntries(current.harnessModels);
+    const nextModels = { ...currentModels };
+    for (const [id, entry] of Object.entries(raw)) {
+      if (!catalog.has(id)) return `harnessModels: unknown harness "${id}"`;
+      if (typeof entry !== "string") return `harnessModels.${id} must be a string`;
+      const value = entry.trim();
+      if (!value) {
+        delete nextModels[id];
+        continue;
+      }
+      if (!isModelSelector(value))
+        return `harnessModels.${id} must be a "providerId/modelId" selector`;
+      nextModels[id] = value;
+    }
+    patch.harnessModels = Object.keys(nextModels).length ? nextModels : undefined;
+    if (!sameEntries(currentModels, nextModels)) sessionAffecting = true;
+  }
+
+  if ("harnessProviders" in body) {
+    const raw = body.harnessProviders;
+    if (!isObject(raw)) return "harnessProviders must be an object";
+    for (const [id, ids] of Object.entries(raw)) {
+      if (!Array.isArray(ids) || !ids.every((entry) => typeof entry === "string")) {
+        return `harnessProviders.${id} must be an array of provider ids`;
+      }
+    }
+    const next = idLists(raw);
+    if (!sameIdLists(idLists(current.harnessProviders), next)) {
+      patch.harnessProviders = Object.keys(next).length ? next : undefined;
+      sessionAffecting = true;
+    }
+  }
+
+  if ("enabledHarnesses" in body) {
+    const raw = body.enabledHarnesses;
+    if (!Array.isArray(raw) || !raw.every((id) => typeof id === "string")) {
+      return "enabledHarnesses must be an array of harness ids";
+    }
+    const unknownId = raw.find((id) => !catalog.has(id));
+    if (unknownId !== undefined) return `enabledHarnesses: unknown harness "${unknownId}"`;
+    const enabled = [...new Set(raw as string[])];
+    if (!enabled.includes(nextHarness))
+      return `enabledHarnesses must include the active harness "${nextHarness}"`;
+    patch.enabledHarnesses = enabled;
+    const before = enabledHarnessIds(current);
+    if (enabled.length !== before.length || enabled.some((id) => !before.includes(id)))
+      sessionAffecting = true;
+  } else if (harnessKey && !enabledHarnessIds(current).includes(nextHarness)) {
+    return `Harness "${nextHarness}" is not enabled`;
+  }
+
+  for (const [field, lock] of LOCK_FIELDS) {
+    const wanted = body[field];
+    if (wanted === undefined) continue;
+    if (typeof wanted !== "boolean") return `${field} must be a boolean`;
+    if (wanted !== locks[lock].value) patch[field] = wanted;
+  }
+
+  return { patch, sessionAffecting };
+}
+
+// ── applyHarnessLayers ──────────────────────────────────────────────────────
+
+/** One settings layer's say in which harness, model and provider pick a session gets. */
+export type HarnessLayer = {
+  /** The harness id (the workspaces settings key `harness`). */
+  harness?: string;
+  /** An explicit model selector; wins over this layer's `harnessModels` entry. */
+  model?: string;
+  harnessModels?: Record<string, string>;
+  harnessProviders?: Record<string, string[]>;
+};
+
+/**
+ * Resolve the harness, model and provider pick a session starts with.
+ *
+ * `layers[0]` is the instance layer; later layers (workspace file, workspace
+ * overrides, chat, …) are more specific and override it per field — the last
+ * layer that sets a field wins. A locked field (`locks.harness` → `harness`,
+ * `locks.model` → `model`, `locks.provider` → `providers`) ignores every later
+ * layer: layer 0's value is the answer, even when it is unset.
+ *
+ * "Sets" means a non-empty `harness`/`model` string or a non-empty provider
+ * array; `""` and `[]` inherit. A layer's model is `layer.model`, else
+ * `layer.harnessModels[harness]`; its providers are
+ * `layer.harnessProviders[harness]` — both keyed by the *resolved* harness, so
+ * a pick stored for another harness never applies.
+ *
+ * Fields no layer sets come back `undefined`; the host supplies its defaults.
+ */
+export function applyHarnessLayers(
+  layers: HarnessLayer[],
+  locks: LockFlags,
+): { harness: string | undefined; model: string | undefined; providers: string[] | undefined } {
+  /** The layer-0 value when `locked`, else the last layer's non-undefined value. */
+  const pick = <T>(
+    locked: boolean,
+    read: (layer: HarnessLayer) => T | undefined,
+  ): T | undefined => {
+    if (locked) return layers[0] ? read(layers[0]) : undefined;
+    for (let i = layers.length - 1; i >= 0; i--) {
+      const value = read(layers[i]!);
+      if (value !== undefined) return value;
+    }
+    return undefined;
+  };
+
+  const harness = pick(locks.harness.value, (layer) => nonEmpty(layer.harness));
+  const model = pick(
+    locks.model.value,
+    (layer) =>
+      nonEmpty(layer.model) ??
+      (harness === undefined ? undefined : nonEmpty(layer.harnessModels?.[harness])),
+  );
+  const providers = pick(locks.provider.value, (layer) => {
+    const ids = harness === undefined ? undefined : layer.harnessProviders?.[harness];
+    return ids?.length ? ids : undefined;
+  });
+  return { harness, model, providers };
+}

package/src/runtime/server/index.ts

@@ -0,0 +1,24 @@
+/**
+ * `@skaile/forge-settings/server` — provider and settings operations for a
+ * host server: the registry vocabulary and layer editing, the credential
+ * store, env layers, harness settings, model discovery.
+ *
+ * Imports no Vue, no editor, no AI SDK and no agent session code. Storage,
+ * authentication and workspace permissions stay with the host.
+ */
+
+export * from "../shared/harness-providers";
+export * from "../shared/harnesses";
+export * from "../shared/provider-registry";
+export type { DomainConfig, SkaileSettings } from "../shared/settings-types";
+export * from "./credential-policy";
+export * from "./credential-store";
+export * from "./env";
+export * from "./env-layers";
+export * from "./harness-settings";
+export * from "./provider-discovery";
+export * from "./provider-layers";
+export * from "./provider-service";
+export * from "./provider-settings";
+export * from "./provider-write";
+export * from "./settings-defaults";

package/src/runtime/server/provider-discovery.ts

@@ -0,0 +1,164 @@
+/**
+ * Live model discovery for one registry entry.
+ *
+ * `listAIProviderModels` (provider-service) answers from the registry's own
+ * `model_map`; this module asks the provider's REST API. The two are different
+ * facts and the result says which one it is:
+ *
+ * - `live` — the provider answered; `models` is its list.
+ * - `static` — the live request failed or the entry has no key, and `models` is
+ *   the offline catalog of its preset. It is a fallback, never a live answer.
+ * - `unsupported` — the entry has no catalog preset, so there is nothing to ask;
+ *   a host lets the admin type a model id.
+ * - `error` — nothing usable. The message is scrubbed.
+ *
+ * The error text is built here, never forwarded: a remote response body is
+ * never part of it, and every secret this call resolved (or the host names in
+ * `redact`) is removed from whatever text remains before it leaves the module.
+ *
+ * The credential policy (see `credential-policy.ts`) is applied to the entry
+ * before its credential is resolved, and `env:` references read from the
+ * explicit `env` only.
+ */
+
+import { resolveEntryBaseUrl } from "@skaile/workspaces/core";
+import { fetchProviderModels, getStaticModels } from "@skaile/workspaces/sdk/bridge";
+import type { AIProviderRegistryView } from "../shared/provider-registry";
+import { isEntryEnabled, registryEntries } from "../shared/provider-registry";
+import { type CredentialPolicy, entryPolicyRefusal } from "./credential-policy";
+import { resolveEntryCredential } from "./credential-store";
+
+/** One model a provider offers. */
+export interface DiscoveredModel {
+  id: string;
+  name: string;
+}
+
+/** Outcome of {@link discoverProviderModels}. */
+export type ModelDiscoveryResult =
+  | { status: "live"; providerId: string; models: DiscoveredModel[] }
+  | {
+      status: "static";
+      providerId: string;
+      models: DiscoveredModel[];
+      /** Why the live request did not produce the list. Scrubbed. */
+      reason: string;
+    }
+  | { status: "unsupported"; providerId: string; reason: string }
+  | { status: "error"; providerId: string; error: string };
+
+/** Options for {@link discoverProviderModels}. */
+export interface DiscoverProviderModelsOptions {
+  /** Environment `env:` references and base-URL variables are read from. Required: no ambient process. */
+  env: Record<string, string | undefined>;
+  /** Which credential references may be resolved. Absent: no restriction. */
+  policy?: CredentialPolicy;
+  /** Extra strings to remove from error text, besides the secrets this call resolves. */
+  redact?: readonly string[];
+  /** Local encrypted store for `keyring:` references. */
+  key?: string;
+  path?: string;
+}
+
+/** Longest error message returned. */
+const MAX_ERROR_LENGTH = 200;
+/** Shortest secret worth masking; shorter strings would mangle ordinary words. */
+const MIN_SECRET_LENGTH = 4;
+
+/**
+ * Remove every occurrence of each secret (verbatim, URL-encoded and
+ * base64-encoded) from `text`, then cap its length.
+ */
+export function scrubSecrets(text: string, secrets: readonly (string | undefined)[]): string {
+  let out = text;
+  for (const secret of secrets) {
+    if (!secret || secret.length < MIN_SECRET_LENGTH) continue;
+    const forms = new Set([
+      secret,
+      encodeURIComponent(secret),
+      Buffer.from(secret, "utf8").toString("base64"),
+    ]);
+    for (const form of forms) out = out.split(form).join("***");
+  }
+  return out.length > MAX_ERROR_LENGTH ? `${out.slice(0, MAX_ERROR_LENGTH)}…` : out;
+}
+
+/**
+ * Ask one registry entry's provider for its models.
+ *
+ * Never throws for a provider-side failure: that is the `error` / `static`
+ * result. A host maps `error` to its own status.
+ */
+export async function discoverProviderModels(
+  providerId: string,
+  registry: AIProviderRegistryView,
+  options: DiscoverProviderModelsOptions,
+): Promise<ModelDiscoveryResult> {
+  const match = registryEntries(registry).find(([id]) => id === providerId);
+  if (!match)
+    return { status: "error", providerId, error: `'${providerId}' is not in this registry` };
+  const entry = match[1];
+  if (entry.kind !== "llm") {
+    return { status: "unsupported", providerId, reason: "only llm entries list models" };
+  }
+  if (!isEntryEnabled(entry)) return { status: "error", providerId, error: "entry is disabled" };
+
+  // The policy decides before anything is resolved or requested.
+  const refusal = options.policy ? entryPolicyRefusal(entry, options.policy) : undefined;
+  if (refusal) return { status: "error", providerId, error: refusal };
+
+  const credential = resolveEntryCredential(entry, {
+    env: options.env,
+    ...(options.policy ? { policy: options.policy } : {}),
+    ...(options.key ? { key: options.key } : {}),
+    ...(options.path ? { path: options.path } : {}),
+  });
+  const secrets = [credential.value, ...(options.redact ?? [])];
+  const scrub = (text: string) => scrubSecrets(text, secrets);
+
+  if (!entry.preset) {
+    return {
+      status: "unsupported",
+      providerId,
+      reason:
+        "this entry names no catalog preset, so its models cannot be listed; enter a model id",
+    };
+  }
+  if (credential.error && !credential.value) {
+    return { status: "error", providerId, error: scrub(credential.error) };
+  }
+
+  const staticList = getStaticModels(entry.preset).map(({ id, name }) => ({ id, name }));
+  if (!credential.value) {
+    // Without a key there is nothing to ask with.
+    return staticList.length > 0
+      ? {
+          status: "static",
+          providerId,
+          models: staticList,
+          reason: "no credential to query the provider with",
+        }
+      : {
+          status: "unsupported",
+          providerId,
+          reason: "no credential, and no offline catalog for this preset",
+        };
+  }
+
+  const baseUrl = resolveEntryBaseUrl(entry);
+  const live = await fetchProviderModels(entry.preset, credential.value, {
+    ...(baseUrl ? { baseUrl } : {}),
+    env: options.env,
+  });
+  if (live.ok && live.models.length > 0) {
+    return {
+      status: "live",
+      providerId,
+      models: live.models.map(({ id, name }) => ({ id, name })),
+    };
+  }
+  const reason = scrub(live.error ?? "the provider returned no models");
+  return staticList.length > 0
+    ? { status: "static", providerId, models: staticList, reason }
+    : { status: "error", providerId, error: reason };
+}

package/src/runtime/server/provider-layers.ts

@@ -0,0 +1,70 @@
+/**
+ * Reading and writing one provider-registry layer document
+ * (`providers.yml` / `providers.yaml`) as written on disk.
+ *
+ * The upstream loader validates and drops entries it dislikes; an editor must
+ * not, or rewriting a file would delete a hand-written entry. These helpers
+ * therefore read the raw `providers` map and write it back unchanged apart
+ * from the entry being edited.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import {
+  type AIProviderRegistryPatch,
+  PROVIDERS_FILENAME,
+  saveProviderRegistryFile,
+} from "@skaile/workspaces/core";
+import { AI_PROVIDER_PRESETS, type AIProviderPreset } from "@skaile/workspaces/sdk/bridge";
+import { parse as parseYaml } from "yaml";
+
+/** The `.yaml` spelling of {@link PROVIDERS_FILENAME}. */
+const PROVIDERS_FILENAME_ALIAS = "providers.yaml";
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * The file a write to the layer at `path` goes to: the `.yaml` spelling when
+ * only that one exists, so an edit never shadows a hand-written document.
+ */
+export function providerLayerDocument(path: string): string {
+  if (existsSync(path)) return path;
+  const alias = `${path.slice(0, -PROVIDERS_FILENAME.length)}${PROVIDERS_FILENAME_ALIAS}`;
+  return existsSync(alias) ? alias : path;
+}
+
+/** The catalog preset `id` names, if the catalog has one. */
+export function catalogPreset(id: unknown): AIProviderPreset | undefined {
+  return typeof id === "string" && Object.hasOwn(AI_PROVIDER_PRESETS, id)
+    ? AI_PROVIDER_PRESETS[id]
+    : undefined;
+}
+
+/**
+ * A layer document's `providers` map exactly as written — entries the
+ * validator would reject included, so rewriting the file never drops a
+ * hand-written entry. A missing or empty file is an empty layer.
+ *
+ * @throws When the file is not YAML or not a registry document.
+ */
+export function readProviderLayer(file: string): Record<string, unknown> {
+  if (!existsSync(file)) return {};
+  let document: unknown;
+  try {
+    document = parseYaml(readFileSync(file, "utf8"));
+  } catch (err) {
+    throw new Error(`${file} is not valid YAML (${(err as Error).message})`);
+  }
+  if (document === null || document === undefined) return {};
+  if (!isPlainObject(document)) throw new Error(`${file} does not contain a registry document`);
+  const providers = document.providers;
+  if (providers === undefined || providers === null) return {};
+  if (!isPlainObject(providers)) throw new Error(`${file}: 'providers' is not a map of entries`);
+  return providers;
+}
+
+/** Write a layer's `providers` map back in the shape the upstream CLI writes. */
+export function writeProviderLayer(file: string, providers: Record<string, unknown>): void {
+  saveProviderRegistryFile(file, { version: 1, providers: providers as AIProviderRegistryPatch });
+}