@skaile/forge-settings 1.4.0 → 2.0.0

package/src/runtime/workspaces/model-endpoint.ts

@@ -0,0 +1,100 @@
+/**
+ * Where a running `skaile serve --model-endpoint` can be reached: the
+ * OpenAI-compatible URL and its bearer token.
+ *
+ * Read-only: the runner writes, owns and removes `.skaile/model-endpoint.json`;
+ * this module only reads what the host points it at. No directory climbing, no
+ * working-directory lookup, and the token never appears in an error.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isPlainObject } from "../shared/guards";
+
+/** Env var names the runner hands its endpoint URL and token through. */
+export const WORKSPACE_MODEL_ENDPOINT_URL_ENV = "SKAILE_MODEL_ENDPOINT_URL";
+export const WORKSPACE_MODEL_ENDPOINT_TOKEN_ENV = "SKAILE_MODEL_ENDPOINT_TOKEN";
+
+/** Address of a Workspaces model endpoint. `token` is a secret. */
+export interface WorkspaceModelEndpoint {
+  /** `http(s)://<host>:<port>/v1`. */
+  url: string;
+  /** Bearer token; never log it. */
+  token: string;
+}
+
+/** Options for {@link readWorkspaceModelEndpoint}. */
+export interface ReadWorkspaceModelEndpointOptions {
+  /** Environment snapshot the URL/token pair is read from. */
+  env: Record<string, string | undefined>;
+  /** Project whose `.skaile/model-endpoint.json` is read when the env pair is absent. */
+  projectDir?: string;
+}
+
+const PREFIX = "Skaile model endpoint configuration";
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const { protocol } = new URL(value);
+    return protocol === "http:" || protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The endpoint address, or `null` when none is configured.
+ *
+ * 1. `SKAILE_MODEL_ENDPOINT_URL` + `SKAILE_MODEL_ENDPOINT_TOKEN` in `env` win.
+ *    Both must be set and the URL must be HTTP(S); one without the other is a
+ *    configuration error, not an absence.
+ * 2. Otherwise, only when `projectDir` is given, `<projectDir>/.skaile/model-endpoint.json`
+ *    (`{ url, token, pid }`). A missing file is `null`.
+ *
+ * @throws Error a malformed or incomplete configuration; the message names the
+ *   source and the problem, never the token.
+ */
+export async function readWorkspaceModelEndpoint(
+  options: ReadWorkspaceModelEndpointOptions,
+): Promise<WorkspaceModelEndpoint | null> {
+  const envUrl = options.env[WORKSPACE_MODEL_ENDPOINT_URL_ENV]?.trim() ?? "";
+  const envToken = options.env[WORKSPACE_MODEL_ENDPOINT_TOKEN_ENV]?.trim() ?? "";
+  if (envUrl || envToken) {
+    if (!envUrl || !envToken) {
+      throw new Error(
+        `${PREFIX}: ${WORKSPACE_MODEL_ENDPOINT_URL_ENV} and ${WORKSPACE_MODEL_ENDPOINT_TOKEN_ENV} must be set together`,
+      );
+    }
+    if (!isHttpUrl(envUrl)) {
+      throw new Error(`${PREFIX}: ${WORKSPACE_MODEL_ENDPOINT_URL_ENV} is not an http(s) URL`);
+    }
+    return { url: envUrl, token: envToken };
+  }
+
+  if (options.projectDir === undefined) return null;
+  const file = join(options.projectDir, ".skaile", "model-endpoint.json");
+  let text: string;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw new Error(`${PREFIX}: ${file} could not be read`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    // The parser's message can quote the file's content, i.e. the token.
+    throw new Error(`${PREFIX}: ${file} is not valid JSON`);
+  }
+  const record = isPlainObject(parsed) ? parsed : {};
+  const url = typeof record.url === "string" ? record.url.trim() : "";
+  const token = typeof record.token === "string" ? record.token.trim() : "";
+  if (!url || !token) {
+    throw new Error(`${PREFIX}: ${file} needs a non-empty "url" and "token"`);
+  }
+  if (!isHttpUrl(url)) {
+    throw new Error(`${PREFIX}: ${file} "url" is not an http(s) URL`);
+  }
+  return { url, token };
+}

package/src/runtime/workspaces/provider-settings.ts

@@ -0,0 +1,96 @@
+/**
+ * The legacy `settings.json` migration of a Workspaces host.
+ *
+ * A `settings.json` written before the 5.0.0 registry migration holds
+ * `provider` + a free-text `model`, and an `apiKeys` map of secrets. On first
+ * load the pair collapses into one `"<providerId>/<modelId>"` selector, and the
+ * `apiKeys` map is dropped with a warning — a plaintext key is never
+ * auto-written anywhere; the user moves it into `.env`.
+ *
+ * Voice selection over the same settings fields is generic:
+ * `resolveVoiceProvider` in `@skaile/forge-settings/server`.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+/** What {@link migrateLegacyProviderSettings} did to one settings file. */
+export interface LegacySettingsMigration {
+  /** The file that was inspected. */
+  path: string;
+  /** Whether the file was rewritten. */
+  changed: boolean;
+  /** The selector `provider` + `model` collapsed into, when that happened. */
+  model?: string;
+  /** Everything dropped or left untouched, and why. Secret-free. */
+  warnings: string[];
+}
+
+/**
+ * Migrate one legacy `settings.json` in place. Idempotent: a file with no
+ * legacy `provider` and no `apiKeys` is left byte-identical.
+ *
+ * An `apiKeys` map is removed from the file and never stored anywhere else:
+ * the registry holds references only, and a plaintext key has no safe
+ * automatic destination. Each non-empty entry is reported through `warnings`
+ * (without the key) so the user can move it into `.env`.
+ *
+ * @param settingsPath - Absolute path to a `settings.json`.
+ */
+export function migrateLegacyProviderSettings(settingsPath: string): LegacySettingsMigration {
+  const result: LegacySettingsMigration = {
+    path: settingsPath,
+    changed: false,
+    warnings: [],
+  };
+  if (!existsSync(settingsPath)) return result;
+
+  let settings: Record<string, unknown>;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, "utf8")) as Record<string, unknown>;
+  } catch (err) {
+    result.warnings.push(`${settingsPath} is not valid JSON (${(err as Error).message})`);
+    return result;
+  }
+  if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
+    result.warnings.push(`${settingsPath} does not contain a settings object`);
+    return result;
+  }
+
+  // ── provider + free-text model → one selector ───────────────────────────
+  const legacyProvider = typeof settings.provider === "string" ? settings.provider.trim() : "";
+  if (legacyProvider) {
+    const model = typeof settings.model === "string" ? settings.model.trim() : "";
+    if (model && !model.includes("/")) {
+      settings.model = `${legacyProvider}/${model}`;
+      result.model = settings.model as string;
+    } else if (!model) {
+      result.warnings.push(
+        `provider '${legacyProvider}' had no model to namespace — the session now resolves ` +
+          "its model through the registry's own order",
+      );
+    }
+    delete settings.provider;
+    result.changed = true;
+  }
+
+  // ── apiKeys map → dropped, never stored ─────────────────────────────────
+  if ("apiKeys" in settings) {
+    const apiKeys = settings.apiKeys;
+    const hasSecret =
+      typeof apiKeys === "object" &&
+      apiKeys !== null &&
+      Object.values(apiKeys).some((value) => typeof value === "string" && value !== "");
+    if (hasSecret) {
+      result.warnings.push(
+        "apiKeys found in settings: move each key into .env and reference it from providers.yml (skaile providers add)",
+      );
+    }
+    delete settings.apiKeys;
+    result.changed = true;
+  }
+
+  if (result.changed) {
+    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+  }
+  return result;
+}

package/src/runtime/{server → workspaces}/settings-defaults.ts

@@ -7,7 +7,7 @@
 
 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";
+import type { SkaileSettings } from "./settings-types";
 
 /**
  * App-level defaults merged on top of core defaults.

package/src/runtime/{shared → workspaces}/settings-types.ts

@@ -1,9 +1,9 @@
 /**
- * The settings document type forge apps share.
+ * The settings document type forge apps on Skaile Workspaces share.
  *
- * A leaf module: it imports types only, so the harness and provider settings
- * modules read `SkaileSettings` from here instead of from the broad server
- * entry. Browser-safe.
+ * It extends the Workspaces `settings.json` type, so it lives in the explicit
+ * `@skaile/forge-settings/workspaces` entry: the generic entries never see it.
+ * A leaf module: it imports types only.
  */
 
 import type { SkaileSettings as CoreSettings } from "@skaile/workspaces/sdk/core";

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

@@ -1,78 +0,0 @@
-/**
- * Where a forge app's settings meet the AI provider registry.
- *
- * Two jobs:
- *
- *   1. **Migration.** A `settings.json` written before the 5.0.0 registry migration holds
- *      `provider` + a free-text `model`, and an `apiKeys` map of secrets. On
- *      first load the pair collapses into one `"<providerId>/<modelId>"`
- *      selector, and the `apiKeys` map is dropped with a warning — a plaintext
- *      key is never auto-written anywhere; the user moves it into `.env`.
- *   2. **Voice selection.** `sttProvider`/`ttsProvider` are registry ids of
- *      `kind: stt|tts` entries; the endpoint and the voice parameters live on
- *      the entry, and `sttLanguage`/`ttsVoice` are per-request overrides of two
- *      of those parameters. Resolving all of that used to be three apps'
- *      worth of hardcoded endpoints and voice ids.
- */
-import type { AIProviderVoiceEntry, AIProviderVoiceKind, AIProviderVoiceParams, AIProviderRegistryView } from "../shared/provider-registry.js";
-import type { SkaileSettings } from "../shared/settings-types.js";
-/** What {@link migrateLegacyProviderSettings} did to one settings file. */
-export interface LegacySettingsMigration {
-    /** The file that was inspected. */
-    path: string;
-    /** Whether the file was rewritten. */
-    changed: boolean;
-    /** The selector `provider` + `model` collapsed into, when that happened. */
-    model?: string;
-    /** Everything dropped or left untouched, and why. Secret-free. */
-    warnings: string[];
-}
-/**
- * Migrate one legacy `settings.json` in place. Idempotent: a file with no
- * legacy `provider` and no `apiKeys` is left byte-identical.
- *
- * An `apiKeys` map is removed from the file and never stored anywhere else:
- * the registry holds references only, and a plaintext key has no safe
- * automatic destination. Each non-empty entry is reported through `warnings`
- * (without the key) so the user can move it into `.env`.
- *
- * @param settingsPath - Absolute path to a `settings.json`.
- */
-export declare function migrateLegacyProviderSettings(settingsPath: string): LegacySettingsMigration;
-/** Settings fields that name a voice entry and override its parameters. */
-export type VoiceSettings = Pick<SkaileSettings, "sttProvider" | "ttsProvider" | "sttLanguage" | "ttsVoice">;
-/** The `kind: stt|tts` entry a request runs against, with its parameters resolved. */
-export interface VoiceProviderSelection {
-    /** Registry id of the entry. */
-    providerId: string;
-    entry: AIProviderVoiceEntry;
-    /** Endpoint from the entry; absent when the entry inherits its preset's default. */
-    baseUrl?: string;
-    /**
-     * The entry's `params` with overrides applied — Deepgram `{model, language}`,
-     * ElevenLabs `{voice_id, output_format}`. This is the only place a forge app
-     * should read voice defaults from.
-     */
-    params: AIProviderVoiceParams;
-    /** True when settings named no usable entry and registry order decided. */
-    fallback: boolean;
-    /** Non-fatal notes, e.g. settings naming an entry the registry does not have. */
-    warnings: string[];
-}
-/**
- * Resolve which registry entry serves speech-to-text or text-to-speech.
- *
- * Selection is `settings.sttProvider`/`settings.ttsProvider`, falling back to
- * the first enabled entry of that kind in registry order when the setting is
- * absent or names an entry that is gone — a missing setting must not silence an
- * app that has a perfectly good entry configured.
- *
- * Parameter precedence, lowest first: the entry's `params`, then the settings
- * overrides (`sttLanguage` → `language`, `ttsVoice` → `voice_id`), then
- * `overrides` from the request. The per-request override is the contract
- * forge-concept already honoured and the other apps silently dropped.
- *
- * @returns The selection, or `undefined` when the registry has no enabled entry
- *          of that kind.
- */
-export declare function resolveVoiceProvider(registry: AIProviderRegistryView, kind: AIProviderVoiceKind, settings?: VoiceSettings, overrides?: AIProviderVoiceParams): VoiceProviderSelection | undefined;

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

@@ -1,192 +0,0 @@
-/**
- * Where a forge app's settings meet the AI provider registry.
- *
- * Two jobs:
- *
- *   1. **Migration.** A `settings.json` written before the 5.0.0 registry migration holds
- *      `provider` + a free-text `model`, and an `apiKeys` map of secrets. On
- *      first load the pair collapses into one `"<providerId>/<modelId>"`
- *      selector, and the `apiKeys` map is dropped with a warning — a plaintext
- *      key is never auto-written anywhere; the user moves it into `.env`.
- *   2. **Voice selection.** `sttProvider`/`ttsProvider` are registry ids of
- *      `kind: stt|tts` entries; the endpoint and the voice parameters live on
- *      the entry, and `sttLanguage`/`ttsVoice` are per-request overrides of two
- *      of those parameters. Resolving all of that used to be three apps'
- *      worth of hardcoded endpoints and voice ids.
- */
-
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import type {
-  AIProviderVoiceEntry,
-  AIProviderVoiceKind,
-  AIProviderVoiceParams,
-  AIProviderRegistryView,
-} from "../shared/provider-registry";
-import {
-  entriesOfKind,
-  selectVoiceEntryId,
-  VOICE_OVERRIDE_PARAM,
-} from "../shared/provider-registry";
-import type { SkaileSettings } from "../shared/settings-types";
-
-/** What {@link migrateLegacyProviderSettings} did to one settings file. */
-export interface LegacySettingsMigration {
-  /** The file that was inspected. */
-  path: string;
-  /** Whether the file was rewritten. */
-  changed: boolean;
-  /** The selector `provider` + `model` collapsed into, when that happened. */
-  model?: string;
-  /** Everything dropped or left untouched, and why. Secret-free. */
-  warnings: string[];
-}
-
-/**
- * Migrate one legacy `settings.json` in place. Idempotent: a file with no
- * legacy `provider` and no `apiKeys` is left byte-identical.
- *
- * An `apiKeys` map is removed from the file and never stored anywhere else:
- * the registry holds references only, and a plaintext key has no safe
- * automatic destination. Each non-empty entry is reported through `warnings`
- * (without the key) so the user can move it into `.env`.
- *
- * @param settingsPath - Absolute path to a `settings.json`.
- */
-export function migrateLegacyProviderSettings(settingsPath: string): LegacySettingsMigration {
-  const result: LegacySettingsMigration = {
-    path: settingsPath,
-    changed: false,
-    warnings: [],
-  };
-  if (!existsSync(settingsPath)) return result;
-
-  let settings: Record<string, unknown>;
-  try {
-    settings = JSON.parse(readFileSync(settingsPath, "utf8")) as Record<string, unknown>;
-  } catch (err) {
-    result.warnings.push(`${settingsPath} is not valid JSON (${(err as Error).message})`);
-    return result;
-  }
-  if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
-    result.warnings.push(`${settingsPath} does not contain a settings object`);
-    return result;
-  }
-
-  // ── provider + free-text model → one selector ───────────────────────────
-  const legacyProvider = typeof settings.provider === "string" ? settings.provider.trim() : "";
-  if (legacyProvider) {
-    const model = typeof settings.model === "string" ? settings.model.trim() : "";
-    if (model && !model.includes("/")) {
-      settings.model = `${legacyProvider}/${model}`;
-      result.model = settings.model as string;
-    } else if (!model) {
-      result.warnings.push(
-        `provider '${legacyProvider}' had no model to namespace — the session now resolves ` +
-          "its model through the registry's own order",
-      );
-    }
-    delete settings.provider;
-    result.changed = true;
-  }
-
-  // ── apiKeys map → dropped, never stored ─────────────────────────────────
-  if ("apiKeys" in settings) {
-    const apiKeys = settings.apiKeys;
-    const hasSecret =
-      typeof apiKeys === "object" &&
-      apiKeys !== null &&
-      Object.values(apiKeys).some((value) => typeof value === "string" && value !== "");
-    if (hasSecret) {
-      result.warnings.push(
-        "apiKeys found in settings: move each key into .env and reference it from providers.yml (skaile providers add)",
-      );
-    }
-    delete settings.apiKeys;
-    result.changed = true;
-  }
-
-  if (result.changed) {
-    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
-  }
-  return result;
-}
-
-// ── Voice selection ────────────────────────────────────────────────────────
-
-/** Settings fields that name a voice entry and override its parameters. */
-export type VoiceSettings = Pick<
-  SkaileSettings,
-  "sttProvider" | "ttsProvider" | "sttLanguage" | "ttsVoice"
->;
-
-/** The `kind: stt|tts` entry a request runs against, with its parameters resolved. */
-export interface VoiceProviderSelection {
-  /** Registry id of the entry. */
-  providerId: string;
-  entry: AIProviderVoiceEntry;
-  /** Endpoint from the entry; absent when the entry inherits its preset's default. */
-  baseUrl?: string;
-  /**
-   * The entry's `params` with overrides applied — Deepgram `{model, language}`,
-   * ElevenLabs `{voice_id, output_format}`. This is the only place a forge app
-   * should read voice defaults from.
-   */
-  params: AIProviderVoiceParams;
-  /** True when settings named no usable entry and registry order decided. */
-  fallback: boolean;
-  /** Non-fatal notes, e.g. settings naming an entry the registry does not have. */
-  warnings: string[];
-}
-
-/**
- * Resolve which registry entry serves speech-to-text or text-to-speech.
- *
- * Selection is `settings.sttProvider`/`settings.ttsProvider`, falling back to
- * the first enabled entry of that kind in registry order when the setting is
- * absent or names an entry that is gone — a missing setting must not silence an
- * app that has a perfectly good entry configured.
- *
- * Parameter precedence, lowest first: the entry's `params`, then the settings
- * overrides (`sttLanguage` → `language`, `ttsVoice` → `voice_id`), then
- * `overrides` from the request. The per-request override is the contract
- * forge-concept already honoured and the other apps silently dropped.
- *
- * @returns The selection, or `undefined` when the registry has no enabled entry
- *          of that kind.
- */
-export function resolveVoiceProvider(
-  registry: AIProviderRegistryView,
-  kind: AIProviderVoiceKind,
-  settings: VoiceSettings = {},
-  overrides: AIProviderVoiceParams = {},
-): VoiceProviderSelection | undefined {
-  const candidates = entriesOfKind(registry, kind);
-  if (candidates.length === 0) return undefined;
-
-  const warnings: string[] = [];
-  const wanted = (kind === "stt" ? settings.sttProvider : settings.ttsProvider)?.trim();
-  const ids = candidates.map(([id]) => id);
-  // `candidates` is non-empty, so the shared rule always names one of these ids.
-  const providerId = selectVoiceEntryId(ids, wanted) as string;
-  const entry = candidates[ids.indexOf(providerId)][1];
-  if (wanted && wanted !== providerId) {
-    warnings.push(
-      `settings name '${wanted}' for ${kind}, which is not an enabled ${kind} entry — ` +
-        `using '${providerId}' instead`,
-    );
-  }
-  const fallback = wanted !== providerId;
-
-  const settingsOverride: AIProviderVoiceParams = {};
-  const override = (kind === "stt" ? settings.sttLanguage : settings.ttsVoice)?.trim();
-  if (override) settingsOverride[VOICE_OVERRIDE_PARAM[kind]] = override;
-
-  return {
-    providerId,
-    entry,
-    ...(entry.base_url ? { baseUrl: entry.base_url } : {}),
-    params: { ...entry.params, ...settingsOverride, ...overrides },
-    fallback,
-    warnings,
-  };
-}