@skaile/forge-settings 0.0.0-stage → 1.0.1

package/dist/runtime/server/provider-write.js

@@ -0,0 +1,221 @@
+import {
+  isSafeProviderId,
+  loadProviderRegistryFile,
+  mergeRegistries,
+  parseCredentialRef,
+  validateMergedRegistry,
+  validateRegistry
+} from "@skaile/workspaces/core";
+import {
+  AI_PROVIDER_PRESETS,
+  expandPreset
+} from "@skaile/workspaces/sdk/bridge";
+import { isPlainObject } from "../shared/guards.js";
+import { entryPolicyRefusal } from "./credential-policy.js";
+import { catalogPreset, readProviderLayer, writeProviderLayer } from "./provider-layers.js";
+export class ProviderWriteError extends Error {
+  statusCode;
+  statusMessage;
+  data;
+  constructor(input) {
+    super(input.statusMessage);
+    this.name = "ProviderWriteError";
+    this.statusCode = input.statusCode;
+    this.statusMessage = input.statusMessage;
+    if (input.data !== void 0) this.data = input.data;
+  }
+}
+function createError(input) {
+  return new ProviderWriteError(input);
+}
+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.";
+const BODY_KEYS = {
+  preset: true,
+  label: true,
+  surface: true,
+  base_url: true,
+  headers: true,
+  credential: true,
+  model_map: true,
+  enabled: true
+};
+export const PATCH_KEYS = ["credential", "enabled"];
+const SECRET_KEYS = { apiKey: true, api_key: true, token: true };
+export function providerScopeWritable(scope, caller) {
+  if (caller.isAdmin) return true;
+  return scope.name !== "instance" && !scope.lock;
+}
+function mergeLayerOf(scope) {
+  return scope.name === "instance" ? "user" : "workspace";
+}
+function readLayerLeniently(file) {
+  try {
+    return readProviderLayer(file);
+  } catch {
+    return {};
+  }
+}
+function editableLayer(scope) {
+  try {
+    return readProviderLayer(scope.file);
+  } catch (err) {
+    throw createError({
+      statusCode: 409,
+      statusMessage: `${err.message} - fix it by hand first`
+    });
+  }
+}
+function readEntryBody(body) {
+  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 !== void 0 && !catalogPreset(body.preset)) {
+    return `Unknown preset '${String(body.preset)}'`;
+  }
+  if (credential !== void 0) {
+    if (!isPlainObject(credential)) return "credential must be { kind, ref }";
+    const ref = credential.ref;
+    if (ref !== void 0 && (typeof ref !== "string" || !parseCredentialRef(ref)))
+      return CREDENTIAL_REF_REFUSAL;
+  }
+  return body;
+}
+function entryErrors(scope, providers, id) {
+  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 = [
+    ...lower.map((file) => ({ layer: file.layer, providers: file.document.providers })),
+    { layer, providers: own.document.providers }
+  ];
+  const catalog = {};
+  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}.`))
+  );
+}
+function isPatchOrAbsent(entry) {
+  if (entry === void 0) return true;
+  return isPlainObject(entry) && Object.keys(entry).every((key) => PATCH_KEYS.includes(key));
+}
+export function upsertProviderEntry(scope, id, body) {
+  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((entry2) => entry2 !== void 0);
+  if ([...lowerEntries, existing].some((entry2) => isPlainObject(entry2) && entry2.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.includes(key));
+  if (inherited && !isPatch && isPatchOrAbsent(existing)) {
+    throw createError({ statusCode: 400, statusMessage: PATCH_REFUSAL });
+  }
+  let entry;
+  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 = entryPolicyRefusal(entry, scope.policy);
+  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 };
+}
+export function removeProviderEntry(scope, id) {
+  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 };
+}
+export function providerPresetSummaries(presets = Object.values(AI_PROVIDER_PRESETS)) {
+  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 }
+  }));
+}
+export function detectedProviderPresets(env, registry) {
+  const used = new Set(Object.keys(registry));
+  for (const entry of Object.values(registry)) {
+    if (entry.preset !== void 0) used.add(entry.preset);
+  }
+  return providerPresetSummaries(
+    Object.values(AI_PROVIDER_PRESETS).filter((preset) => {
+      const name = preset.credential.env;
+      return name !== void 0 && Boolean(env[name]?.trim()) && !used.has(preset.id);
+    })
+  );
+}
+const LAYER_FIELD_KEYS = ["label", "headers", "model_map", "enabled"];
+export function withProviderLayers(views, scope) {
+  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(() => "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 = {};
+    if (isPlainObject(entry)) {
+      for (const key of LAYER_FIELD_KEYS) {
+        if (entry[key] !== void 0) layerFields[key] = entry[key];
+      }
+    }
+    return { ...view, layers: deduped, layerFields };
+  });
+}

package/dist/runtime/server/settings-defaults.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 type { SkaileSettings } from "../shared/settings-types.js";
+/**
+ * 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 declare const SETTINGS_DEFAULTS: SkaileSettings;
+/**
+ * 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 declare function migrateLegacyHarnessSettings(settingsPath: string): {
+    mapped: string[];
+};

package/dist/runtime/server/settings-defaults.js

@@ -0,0 +1,46 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { SETTINGS_DEFAULTS as CORE_DEFAULTS } from "@skaile/workspaces/sdk/core";
+const APP_DEFAULTS = {
+  domains: {
+    enabled: [
+      "skaileup-conceptualization",
+      "skaileup-implementation",
+      "skaileup-evaluate",
+      "dev-security"
+    ],
+    default: "skaileup-conceptualization"
+  }
+};
+export const SETTINGS_DEFAULTS = { ...CORE_DEFAULTS, ...APP_DEFAULTS };
+const LEGACY_HARNESS_KEYS = {
+  driver: "harness",
+  driverModels: "harnessModels",
+  driverProviders: "harnessProviders",
+  enabledBackends: "enabledHarnesses",
+  lockBackend: "lockHarness"
+};
+export function migrateLegacyHarnessSettings(settingsPath) {
+  const mapped = [];
+  if (!existsSync(settingsPath)) return { mapped };
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+  } catch {
+    return { mapped };
+  }
+  if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
+    return { mapped };
+  }
+  const doc = settings;
+  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)}
+`, "utf8");
+  }
+  return { mapped };
+}

package/dist/runtime/shared/env-vars.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 declare const ENV_LAYER_ORDER: readonly EnvLayerId[];
+/** Names an editable `.env` layer accepts. */
+export declare const ENV_VAR_NAME_PATTERN: RegExp;
+/** Names no settings UI may write: they steer the process or forge itself. */
+export declare const ENV_VAR_DENYLIST: readonly string[];
+/** Refusal text for a name an editable layer must not hold, or `null` when it is fine. */
+export declare function validateEnvVarName(name: string): string | 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[];
+}

package/dist/runtime/shared/env-vars.js

@@ -0,0 +1,22 @@
+export const ENV_LAYER_ORDER = ["process", "instance", "workspace"];
+export const ENV_VAR_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
+export const ENV_VAR_DENYLIST = [
+  "PATH",
+  "HOME",
+  "NODE_OPTIONS",
+  "LD_PRELOAD",
+  "DYLD_INSERT_LIBRARIES",
+  "FORGE_HOME",
+  "FORGE_CREDENTIAL_KEY",
+  "FORGE_CREDENTIAL_STORE",
+  "SKAILE_HOME"
+];
+export function validateEnvVarName(name) {
+  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;
+}

package/dist/runtime/shared/guards.d.ts

@@ -0,0 +1,2 @@
+/** A non-null, non-array object. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;

package/dist/runtime/shared/guards.js

@@ -0,0 +1,3 @@
+export function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/runtime/shared/harness-providers.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Which registry providers a harness can run against, and which of
+ * them a session on it will use.
+ *
+ * One rule, applied identically by the settings dialog and the spawner, so the
+ * dialog never promises a provider the spawner will not deliver.
+ *
+ * Eligibility is by wire surface, never by vendor name: an entry is eligible
+ * for a harness when it is an enabled `llm` entry whose `surface` the harness
+ * declares. A harness that declares no surfaces accepts every `llm` entry.
+ *
+ * Browser-safe on purpose — no `node:` imports.
+ */
+/** How many registry entries a harness can run at once (`@skaile/workspaces` `HarnessInfo.providerPlurality`). */
+export type HarnessProviderPlurality = "registry" | "credentials-n" | "single";
+/** The slice of a harness the rule reads. `GET /api/agents` rows satisfy it. */
+export interface HarnessProviderInfo {
+    id: string;
+    /** Wire surfaces the harness speaks. Absent: every `llm` entry is eligible. */
+    surfaces?: readonly string[];
+    /** Absent means `"single"`. */
+    providerPlurality?: HarnessProviderPlurality;
+}
+/** The slice of a registry entry the rule reads. `GET /api/providers` rows satisfy it. */
+export interface HarnessProviderCandidate {
+    id: string;
+    /** Absent means `llm`. */
+    kind?: string;
+    /** Wire protocol of an `llm` entry. */
+    surface?: string;
+    /** Absent means enabled. */
+    enabled?: boolean;
+}
+/**
+ * - `chosen`: the stored pick, narrowed to what is still eligible, is used.
+ * - `auto`: nothing usable picked; the only eligible entry — or, for a multi
+ *   harness, every eligible entry — is used.
+ * - `none-eligible`: no entry fits; the harness runs on its native login.
+ * - `needs-choice`: a single-provider harness with several eligible entries and
+ *   no usable pick — the harness is not usable until one is chosen.
+ */
+export type HarnessProviderState = "chosen" | "auto" | "none-eligible" | "needs-choice";
+export interface HarnessProviderResolution<C extends HarnessProviderCandidate = HarnessProviderCandidate> {
+    /** Eligible candidates, in candidate (registry) order. */
+    eligible: C[];
+    /** Ids the session uses, in registry order; empty for `none-eligible` and `needs-choice`. */
+    selected: string[];
+    state: HarnessProviderState;
+    /** The harness can run several providers at once. */
+    multiple: boolean;
+    /** Stored pick ids that are no longer eligible, deduplicated, in stored order. */
+    stale: string[];
+}
+/** Whether `candidate` is an enabled `llm` entry on a surface `harness` speaks. */
+export declare function isProviderEligibleForHarness(harness: HarnessProviderInfo, candidate: HarnessProviderCandidate): boolean;
+/**
+ * Resolve the providers a harness runs against.
+ *
+ * @param candidates Registry entries in registry order.
+ * @param selection The stored per-harness pick (`SkaileSettings.harnessProviders[harness.id]`).
+ */
+export declare function resolveHarnessProviders<C extends HarnessProviderCandidate>(harness: HarnessProviderInfo, candidates: readonly C[], selection: readonly string[] | undefined): HarnessProviderResolution<C>;

package/dist/runtime/shared/harness-providers.js

@@ -0,0 +1,38 @@
+export function isProviderEligibleForHarness(harness, candidate) {
+  if ((candidate.kind ?? "llm") !== "llm") return false;
+  if (candidate.enabled === false) return false;
+  if (!harness.surfaces) return true;
+  return candidate.surface !== void 0 && harness.surfaces.includes(candidate.surface);
+}
+export function resolveHarnessProviders(harness, candidates, selection) {
+  const multiple = harness.providerPlurality === "registry" || harness.providerPlurality === "credentials-n";
+  const eligible = candidates.filter(
+    (candidate) => isProviderEligibleForHarness(harness, candidate)
+  );
+  const eligibleIds = new Set(eligible.map((candidate) => candidate.id));
+  const picked = new Set(selection ?? []);
+  const stale = [...picked].filter((id) => !eligibleIds.has(id));
+  const usable = eligible.filter((candidate) => picked.has(candidate.id)).map((candidate) => candidate.id);
+  if (usable.length > 0) {
+    return {
+      eligible,
+      selected: multiple ? usable : usable.slice(0, 1),
+      state: "chosen",
+      multiple,
+      stale
+    };
+  }
+  if (eligible.length === 0) {
+    return { eligible, selected: [], state: "none-eligible", multiple, stale };
+  }
+  if (eligible.length === 1 || multiple) {
+    return {
+      eligible,
+      selected: eligible.map((candidate) => candidate.id),
+      state: "auto",
+      multiple,
+      stale
+    };
+  }
+  return { eligible, selected: [], state: "needs-choice", multiple, stale };
+}

package/dist/runtime/shared/harnesses.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Harness catalog vocabulary shared by the server and the settings UI.
+ *
+ * A harness is a coding-agent product; `@skaile/workspaces` 6 names the adapter
+ * that runs it the same way, so these ids are the ids `listHarnesses()` reports
+ * (`--harness <id>`).
+ *
+ * {@link DEFAULT_ENABLED_HARNESSES} are the harnesses an instance offers when
+ * its settings name no `enabledHarnesses`; every other harness is experimental
+ * and must be enabled explicitly.
+ *
+ * Browser-safe on purpose — no `node:` imports.
+ */
+/** Display labels keyed by harness id. Unknown ids fall back to the harness's own name. */
+export declare const HARNESS_LABELS: Record<string, string>;
+/** Harness ids an instance enables when its settings carry no `enabledHarnesses`. */
+export declare const DEFAULT_ENABLED_HARNESSES: readonly ["omp", "claude-sdk", "codex"];
+/** Whether `id` is outside {@link DEFAULT_ENABLED_HARNESSES}, i.e. opt-in only. */
+export declare function isExperimentalHarness(id: string): boolean;

package/dist/runtime/shared/harnesses.js

@@ -0,0 +1,15 @@
+export const HARNESS_LABELS = {
+  omp: "oh-my-pi",
+  "claude-sdk": "Claude Code",
+  codex: "Codex",
+  gemini: "Gemini CLI",
+  qwen: "Qwen Code",
+  opencode: "OpenCode",
+  goose: "Goose",
+  continue: "Continue",
+  echo: "Echo (E2E mock)"
+};
+export const DEFAULT_ENABLED_HARNESSES = ["omp", "claude-sdk", "codex"];
+export function isExperimentalHarness(id) {
+  return !DEFAULT_ENABLED_HARNESSES.includes(id);
+}