@skaile/forge-settings 1.3.3 → 2.0.0

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,
-  };
-}