@skaile/forge-settings 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,438 @@
+/**
+ * Editing the provider registry's on-disk layers over HTTP: the instance
+ * layer (admins) and a workspace's `<root>/.skaile/providers.yml` (write
+ * access, unless the admin locked providers).
+ *
+ * A layer file holds references, never secrets: a body that carries a key
+ * value is refused before anything else, and `credential.ref` must be one of
+ * the four reference forms. Every write is gated on the registry it would
+ * produce — the scope's layers merged over the catalog presets the entries
+ * name, as the spawned child merges them — so an entry the child would drop is
+ * refused with the upstream diagnostics instead of being written.
+ *
+ * An entry a lower document defines can be **patched** from a higher scope:
+ * a body holding only {@link PATCH_KEYS} is stored under that id in the
+ * scope's own document, where the registry merge applies it field by field
+ * over the inherited entry. Removing it again (`removeProviderEntry`) is the
+ * patch's reset.
+ *
+ * Writes never touch live sessions: a running chat keeps its endpoint until
+ * its model or harness changes.
+ *
+ * Auth stays in the app: it builds the {@link ProviderWriteScope} (paths, env,
+ * lock state), asks {@link providerScopeWritable}, and answers 403 itself.
+ */
+
+import {
+  type AIProviderDiagnostic,
+  type AIProviderRegistryLayer,
+  type AIProviderRegistryPatch,
+  isSafeProviderId,
+  loadProviderRegistryFile,
+  mergeRegistries,
+  parseCredentialRef,
+  validateMergedRegistry,
+  validateRegistry,
+} from "@skaile/workspaces/core";
+import {
+  AI_PROVIDER_PRESETS,
+  type AIProviderPreset,
+  expandPreset,
+} from "@skaile/workspaces/sdk/bridge";
+import type { AIProviderEntry, AIProviderRegistry } from "../shared/provider-registry";
+import { type CredentialPolicy, entryPolicyRefusal } from "./credential-policy";
+import { catalogPreset, readProviderLayer, writeProviderLayer } from "./provider-layers";
+
+/**
+ * A refused provider write. Framework-free: a Nitro / h3 host answers a thrown
+ * error carrying `statusCode`, `statusMessage` and `data` with exactly that
+ * status, message and body, the same as one made by `createError`.
+ */
+export class ProviderWriteError extends Error {
+  readonly statusCode: number;
+  readonly statusMessage: string;
+  readonly data?: unknown;
+  constructor(input: { statusCode: number; statusMessage: string; data?: unknown }) {
+    super(input.statusMessage);
+    this.name = "ProviderWriteError";
+    this.statusCode = input.statusCode;
+    this.statusMessage = input.statusMessage;
+    if (input.data !== undefined) this.data = input.data;
+  }
+}
+
+function createError(input: { statusCode: number; statusMessage: string; data?: unknown }) {
+  return new ProviderWriteError(input);
+}
+
+/** The refusal for a body that carries a secret instead of a reference. */
+export const PROVIDER_SECRET_REFUSAL =
+  "Secrets go into the scope's .env; reference them as env:NAME";
+
+const CREDENTIAL_REF_REFUSAL =
+  "credential.ref must be a reference, not a secret: env:NAME, cmd:<shell>, platform:<configId> or keyring:<service>/<account>";
+
+const PATCH_REFUSAL =
+  "A workspace may only patch credential and enabled of an inherited entry; add it as a workspace entry to change anything else.";
+
+/**
+ * Entry keys a `PUT` body may set, and that an omitting body removes. `kind`
+ * may be set too — an entry without a `preset` (the settings modal's
+ * "Custom") has nothing else to supply it — but, omitted, it keeps its
+ * written value like every other key of a stored entry.
+ */
+const BODY_KEYS: Record<string, true> = {
+  preset: true,
+  label: true,
+  surface: true,
+  base_url: true,
+  headers: true,
+  credential: true,
+  model_map: true,
+  enabled: true,
+};
+
+/** Entry fields a higher scope may set on an entry a lower document defines. */
+export const PATCH_KEYS = ["credential", "enabled"] as const;
+
+/** Keys that only ever hold a secret value. */
+const SECRET_KEYS: Record<string, true> = { apiKey: true, api_key: true, token: true };
+
+/** One registry layer file a write goes to, and the layers merged beneath it. */
+export interface ProviderWriteScope {
+  /** Which registry the caller edits. */
+  name: "instance" | "workspace";
+  /** The scope's own document (its `.yaml` spelling when only that one exists). */
+  file: string;
+  /** Documents merged beneath it, lowest first; empty for the lowest layer. */
+  below: string[];
+  /** The scope's effective environment, as `env:` credential references resolve against it. */
+  env: Record<string, string | undefined>;
+  /** The control plane's provider lock is in force: only an admin may write. */
+  lock: boolean;
+  /**
+   * The host's credential policy. A write whose resulting entry names a
+   * reference or environment variable the policy refuses is a 400 and nothing
+   * is written. Absent: no restriction.
+   */
+  policy?: CredentialPolicy;
+}
+
+/**
+ * Whether the caller may write the scope's document: an admin always; anyone
+ * else only to a workspace document while providers are not locked.
+ */
+export function providerScopeWritable(
+  scope: ProviderWriteScope,
+  caller: { isAdmin: boolean },
+): boolean {
+  if (caller.isAdmin) return true;
+  return scope.name !== "instance" && !scope.lock;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The merge layer a scope's own document feeds. */
+function mergeLayerOf(scope: ProviderWriteScope): "user" | "workspace" {
+  return scope.name === "instance" ? "user" : "workspace";
+}
+
+/** A layer document's entries; a document that is not a registry reads as empty, as the loader skips it. */
+function readLayerLeniently(file: string): Record<string, unknown> {
+  try {
+    return readProviderLayer(file);
+  } catch {
+    return {};
+  }
+}
+
+/** The scope's document for an edit; 409 when it cannot be read back safely. */
+function editableLayer(scope: ProviderWriteScope): Record<string, unknown> {
+  try {
+    return readProviderLayer(scope.file);
+  } catch (err) {
+    throw createError({
+      statusCode: 409,
+      statusMessage: `${(err as Error).message} - fix it by hand first`,
+    });
+  }
+}
+
+/** The entry fields a `PUT` body sets, or the refusal. */
+function readEntryBody(body: unknown): Record<string, unknown> | string {
+  if (!isPlainObject(body)) return "Body must be a provider entry object";
+  const credential = body.credential;
+  const credentialKeys = isPlainObject(credential) ? Object.keys(credential) : [];
+  if (
+    Object.keys(body).some((key) => Object.hasOwn(SECRET_KEYS, key)) ||
+    credentialKeys.some((key) => key === "value" || Object.hasOwn(SECRET_KEYS, key))
+  ) {
+    return PROVIDER_SECRET_REFUSAL;
+  }
+  const unknown = Object.keys(body).find((key) => !Object.hasOwn(BODY_KEYS, key) && key !== "kind");
+  if (unknown) return `'${unknown}' is not a provider entry field`;
+  if (body.preset !== undefined && !catalogPreset(body.preset)) {
+    return `Unknown preset '${String(body.preset)}'`;
+  }
+  if (credential !== undefined) {
+    if (!isPlainObject(credential)) return "credential must be { kind, ref }";
+    const ref = credential.ref;
+    if (ref !== undefined && (typeof ref !== "string" || !parseCredentialRef(ref)))
+      return CREDENTIAL_REF_REFUSAL;
+  }
+  return body;
+}
+
+/**
+ * Error diagnostics for entry `id` in the registry the scope would hold with
+ * `providers` as its own layer: the layer check (types, enums, literal
+ * secrets) plus the merged gate over the lower layers and the catalog presets
+ * the merged entries name. Only the edited entry's errors count — a broken
+ * entry elsewhere is not this write's doing.
+ */
+function entryErrors(
+  scope: ProviderWriteScope,
+  providers: Record<string, unknown>,
+  id: string,
+): AIProviderDiagnostic[] {
+  const layer = mergeLayerOf(scope);
+  const lower = scope.below.map((file) => loadProviderRegistryFile(file, "user"));
+  const own = validateRegistry({ version: 1, providers }, { source: scope.file, layer });
+  const fileLayers: AIProviderRegistryLayer[] = [
+    ...lower.map((file) => ({ layer: file.layer, providers: file.document.providers })),
+    { layer, providers: own.document.providers },
+  ];
+  const catalog: AIProviderRegistryPatch = {};
+  for (const [entryId, patch] of Object.entries(mergeRegistries(fileLayers).providers)) {
+    const preset = catalogPreset(patch.preset);
+    if (preset) catalog[entryId] = expandPreset(preset);
+  }
+  const merged = validateMergedRegistry(
+    mergeRegistries([...fileLayers, { layer: "catalog", providers: catalog }]),
+    {
+      sources: [
+        ...lower.map((file) => ({ label: file.path, providers: file.document.providers })),
+        { label: scope.file, providers: own.document.providers },
+      ],
+    },
+  );
+  const path = `providers.${id}`;
+  return [...own.diagnostics, ...merged.diagnostics].filter(
+    (d) => d.severity === "error" && (d.path === path || d.path.startsWith(`${path}.`)),
+  );
+}
+
+/** Whether a stored entry holds only patch fields (or is absent) — nothing a workspace could not have inherited. */
+function isPatchOrAbsent(entry: unknown): boolean {
+  if (entry === undefined) return true;
+  return (
+    isPlainObject(entry) &&
+    Object.keys(entry).every((key) => (PATCH_KEYS as readonly string[]).includes(key))
+  );
+}
+
+/**
+ * Upsert entry `id` in the scope's document.
+ *
+ * - **Own entry** — the body sets the editable fields (`BODY_KEYS`) — one it
+ *   omits is removed — and optionally `kind`; fields it does not set (`kind`,
+ *   `transport`, `params`, …) keep their written value.
+ * - **Patch** — when a lower document defines `id` and the body holds only
+ *   {@link PATCH_KEYS}, the body is merged into the scope's stored entry for
+ *   `id` (created when absent), leaving every other stored field alone.
+ *
+ * The file and its directory are created when absent; other entries are kept
+ * as written.
+ *
+ * 400: invalid id, secret-bearing or malformed body, a body for an inherited
+ * entry that is neither a patch nor over an own full entry, or any error
+ * diagnostic for the entry (as `data.diagnostics`; nothing is written). 403:
+ * the entry is `locked: true` in some document. 409: the document on disk is
+ * not a registry.
+ */
+export function upsertProviderEntry(
+  scope: ProviderWriteScope,
+  id: string,
+  body: unknown,
+): { id: string; entry: Record<string, unknown> } {
+  if (!isSafeProviderId(id)) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: `'${id}' is not a valid provider id - use [a-z0-9][a-z0-9_-]*`,
+    });
+  }
+  const fields = readEntryBody(body);
+  if (typeof fields === "string") throw createError({ statusCode: 400, statusMessage: fields });
+
+  const providers = editableLayer(scope);
+  const existing = providers[id];
+  const lowerEntries = scope.below.map((file) => readLayerLeniently(file)[id]);
+  const inherited = lowerEntries.some((entry) => entry !== undefined);
+
+  if ([...lowerEntries, existing].some((entry) => isPlainObject(entry) && entry.locked === true)) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: `Provider '${id}' is locked by the control plane`,
+    });
+  }
+
+  const fieldKeys = Object.keys(fields);
+  const isPatch =
+    inherited &&
+    fieldKeys.length > 0 &&
+    fieldKeys.every((key) => (PATCH_KEYS as readonly string[]).includes(key));
+  if (inherited && !isPatch && isPatchOrAbsent(existing)) {
+    throw createError({ statusCode: 400, statusMessage: PATCH_REFUSAL });
+  }
+
+  let entry: Record<string, unknown>;
+  if (isPatch) {
+    entry = { ...(isPlainObject(existing) ? existing : {}), ...fields };
+  } else {
+    const kept = isPlainObject(existing)
+      ? Object.fromEntries(
+          Object.entries(existing).filter(([key]) => !Object.hasOwn(BODY_KEYS, key)),
+        )
+      : {};
+    entry = { ...kept, ...fields };
+  }
+  const next = { ...providers, [id]: entry };
+
+  const refusal = scope.policy
+    ? entryPolicyRefusal(entry as unknown as AIProviderEntry, scope.policy)
+    : undefined;
+  if (refusal) throw createError({ statusCode: 400, statusMessage: refusal });
+
+  const diagnostics = entryErrors(scope, next, id);
+  if (diagnostics.length > 0) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: `Invalid provider entry '${id}': ${diagnostics.map((d) => d.path).join(", ")}`,
+      data: { diagnostics },
+    });
+  }
+  writeProviderLayer(scope.file, next);
+  return { id, entry };
+}
+
+/**
+ * Remove entry `id` from the scope's document; 404 when that document does
+ * not define it. On a patched entry that deletes the patch and the inherited
+ * entry shows through again.
+ */
+export function removeProviderEntry(scope: ProviderWriteScope, id: string): { id: string } {
+  const providers = editableLayer(scope);
+  if (!Object.hasOwn(providers, id)) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: `No provider '${id}' in the ${scope.name} registry`,
+    });
+  }
+  const { [id]: _removed, ...rest } = providers;
+  writeProviderLayer(scope.file, rest);
+  return { id };
+}
+
+/** A catalog preset as the settings modal lists it. */
+export interface ProviderPresetSummary {
+  id: string;
+  label: string;
+  kind: AIProviderPreset["kind"];
+  surface?: AIProviderPreset["surface"];
+  base_url?: string;
+  base_url_env?: string;
+  credential: { kind: AIProviderPreset["credential"]["kind"]; env?: string };
+}
+
+/** Catalog presets (all of them by default), in catalog order. */
+export function providerPresetSummaries(
+  presets: AIProviderPreset[] = Object.values(AI_PROVIDER_PRESETS),
+): ProviderPresetSummary[] {
+  return presets.map((preset) => ({
+    id: preset.id,
+    label: preset.label,
+    kind: preset.kind,
+    surface: preset.surface,
+    base_url: preset.base_url,
+    base_url_env: preset.base_url_env,
+    credential: { kind: preset.credential.kind, env: preset.credential.env },
+  }));
+}
+
+/**
+ * Presets a scope could configure right now: their `credential.env` is set
+ * in `env`, and no entry of `registry` is the preset's id or names it as its
+ * `preset`.
+ *
+ * @param env - The scope's layered environment.
+ * @param registry - The scope's merged registry.
+ */
+export function detectedProviderPresets(
+  env: Record<string, string | undefined>,
+  registry: AIProviderRegistry,
+): ProviderPresetSummary[] {
+  const used = new Set(Object.keys(registry));
+  for (const entry of Object.values(registry)) {
+    if (entry.preset !== undefined) used.add(entry.preset);
+  }
+  return providerPresetSummaries(
+    Object.values(AI_PROVIDER_PRESETS).filter((preset) => {
+      const name = preset.credential.env;
+      return name !== undefined && Boolean(env[name]?.trim()) && !used.has(preset.id);
+    }),
+  );
+}
+
+/** Which registry document holds a provider entry the scope lists. */
+export type ProviderLayerName = ProviderWriteScope["name"];
+
+/**
+ * The defining document's values for the `PUT`-editable fields a settings UI
+ * edit dialog does not show. A `PUT` removes every editable field it omits,
+ * so an edit sends these back unchanged instead of dropping them.
+ */
+export interface ProviderLayerFields {
+  label?: unknown;
+  headers?: unknown;
+  model_map?: unknown;
+  enabled?: unknown;
+}
+
+const LAYER_FIELD_KEYS = ["label", "headers", "model_map", "enabled"] as const;
+
+/**
+ * Tag each provider view of a scope with every registry document that holds
+ * its id — `layers`, lowest first: `"instance"` for each lower document, then
+ * the scope's own name when its own document holds it. An id no document
+ * holds (not expected) is attributed to the lowest layer of the scope.
+ * `layerFields` are the {@link ProviderLayerFields} of the scope's own entry,
+ * or of the lowest document holding the id when the scope has none.
+ */
+export function withProviderLayers<T extends { id: string }>(
+  views: T[],
+  scope: ProviderWriteScope,
+): Array<T & { layers: ProviderLayerName[]; layerFields: ProviderLayerFields }> {
+  const own = readLayerLeniently(scope.file);
+  const lower = scope.below.map((file) => readLayerLeniently(file));
+  return views.map((view) => {
+    const layers = lower
+      .filter((doc) => Object.hasOwn(doc, view.id))
+      .map((): ProviderLayerName => "instance");
+    if (Object.hasOwn(own, view.id)) layers.push(scope.name);
+    const deduped = [...new Set(layers)];
+    if (deduped.length === 0) deduped.push(scope.below.length > 0 ? "instance" : scope.name);
+
+    const entry = Object.hasOwn(own, view.id)
+      ? own[view.id]
+      : lower.find((doc) => Object.hasOwn(doc, view.id))?.[view.id];
+    const layerFields: ProviderLayerFields = {};
+    if (isPlainObject(entry)) {
+      for (const key of LAYER_FIELD_KEYS) {
+        if (entry[key] !== undefined) layerFields[key] = entry[key];
+      }
+    }
+    return { ...view, layers: deduped, layerFields };
+  });
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Settings defaults and the legacy harness-key migration.
+ *
+ * Storage stays with the host: this module reads and writes nothing except the
+ * one `settings.json` {@link migrateLegacyHarnessSettings} is pointed at.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { SETTINGS_DEFAULTS as CORE_DEFAULTS } from "@skaile/workspaces/sdk/core";
+import type { SkaileSettings } from "../shared/settings-types";
+
+/**
+ * App-level defaults merged on top of core defaults.
+ *
+ * No voice defaults live here. `sttProvider`/`ttsProvider` default to the first
+ * enabled entry of that kind in registry order (see `resolveVoiceProvider`),
+ * and the language and voice id default to the chosen entry's `params`.
+ */
+const APP_DEFAULTS: Partial<SkaileSettings> = {
+  domains: {
+    enabled: [
+      "skaileup-conceptualization",
+      "skaileup-implementation",
+      "skaileup-evaluate",
+      "dev-security",
+    ],
+    default: "skaileup-conceptualization",
+  },
+};
+
+/**
+ * Merged default settings for forge apps.
+ *
+ * Combines core defaults with the app-specific domain defaults. Used as the
+ * lowest-priority layer during settings resolution.
+ */
+export const SETTINGS_DEFAULTS: SkaileSettings = { ...CORE_DEFAULTS, ...APP_DEFAULTS };
+
+/**
+ * Harness settings keys renamed, old name → new name. `driver` → `harness` is
+ * the `@skaile/workspaces` 6 rename (read as an alias for one major there too);
+ * the rest were renamed in forge-common 6.0.0.
+ */
+const LEGACY_HARNESS_KEYS: Readonly<Record<string, string>> = {
+  driver: "harness",
+  driverModels: "harnessModels",
+  driverProviders: "harnessProviders",
+  enabledBackends: "enabledHarnesses",
+  lockBackend: "lockHarness",
+};
+
+/**
+ * Rewrite one `settings.json` from the legacy harness keys to the current
+ * ones. Each legacy key is moved to its new name and removed; when the new key
+ * already exists it wins and the legacy value is dropped. A file without legacy
+ * keys (or one that is missing / not a JSON object) is left byte-identical.
+ *
+ * @param settingsPath - Absolute path to a `settings.json`.
+ * @returns The legacy keys that were rewritten (empty when nothing changed).
+ */
+export function migrateLegacyHarnessSettings(settingsPath: string): { mapped: string[] } {
+  const mapped: string[] = [];
+  if (!existsSync(settingsPath)) return { mapped };
+
+  let settings: unknown;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+  } catch {
+    return { mapped };
+  }
+  if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
+    return { mapped };
+  }
+
+  const doc = settings as Record<string, unknown>;
+  for (const [legacy, current] of Object.entries(LEGACY_HARNESS_KEYS)) {
+    if (!(legacy in doc)) continue;
+    if (!(current in doc)) doc[current] = doc[legacy];
+    delete doc[legacy];
+    mapped.push(legacy);
+  }
+
+  if (mapped.length > 0) {
+    writeFileSync(settingsPath, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
+  }
+  return { mapped };
+}

package/src/runtime/shared/env-vars.ts

@@ -0,0 +1,82 @@
+/**
+ * Environment-layer vocabulary shared by the server helpers
+ * (`server/utils/env-layers.ts`) and the settings modal's Providers tab.
+ *
+ * Browser-safe on purpose — no `node:` imports — so the client refuses the
+ * same names the server refuses, from one source.
+ *
+ * Layers, lowest to highest precedence: `process` (boot env), `instance`
+ * (`$FORGE_HOME/.env`), `workspace` (`<workspace root>/.env`). The nearest
+ * layer defining a non-empty value wins.
+ */
+
+/** One source of environment variables. */
+export type EnvLayerId = "process" | "instance" | "workspace";
+
+/** Layer precedence, lowest first. */
+export const ENV_LAYER_ORDER: readonly EnvLayerId[] = ["process", "instance", "workspace"];
+
+/** Names an editable `.env` layer accepts. */
+export const ENV_VAR_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
+
+/** Names no settings UI may write: they steer the process or forge itself. */
+export const ENV_VAR_DENYLIST: readonly string[] = [
+  "PATH",
+  "HOME",
+  "NODE_OPTIONS",
+  "LD_PRELOAD",
+  "DYLD_INSERT_LIBRARIES",
+  "FORGE_HOME",
+  "FORGE_CREDENTIAL_KEY",
+  "FORGE_CREDENTIAL_STORE",
+  "SKAILE_HOME",
+];
+
+/** Refusal text for a name an editable layer must not hold, or `null` when it is fine. */
+export function validateEnvVarName(name: string): string | null {
+  if (!ENV_VAR_NAME_PATTERN.test(name)) {
+    return `Invalid variable name "${name}": use upper-case letters, digits and underscores, not starting with a digit`;
+  }
+  if (ENV_VAR_DENYLIST.includes(name)) {
+    return `"${name}" cannot be set from settings`;
+  }
+  return null;
+}
+
+/** One variable as the browser sees it — never the value. */
+export interface EnvVarView {
+  name: string;
+  /** Last 4 characters when the value has at least 8, else `""`. */
+  hint: string;
+  length: number;
+  /** Layer whose value wins. */
+  source: EnvLayerId;
+  /** Lower layers that also define the name (their value is shadowed). */
+  shadows: EnvLayerId[];
+  /** Registry entry ids whose credential references `env:<name>`. */
+  referencedBy: string[];
+}
+
+/** A registry `env:` reference no layer defines. */
+export interface EnvSettingsMissing {
+  name: string;
+  referencedBy: string[];
+}
+
+/** Response of `GET`/`PUT <environmentUrl>`. */
+export interface EnvSettingsDocument {
+  scope: "instance" | "workspace";
+  /** Whether the caller may `PUT` to this document's layer. */
+  editable: boolean;
+  /** The layer this document edits. */
+  layer: "instance" | "workspace";
+  /** Sorted by name. */
+  vars: EnvVarView[];
+  missing: EnvSettingsMissing[];
+}
+
+/** Request body of `PUT <environmentUrl>`. */
+export interface EnvSettingsUpdate {
+  set: Record<string, string>;
+  unset: string[];
+}