@skaile/forge-settings 1.2.1 → 1.3.0

package/dist/runtime/shared/model-roles.js

@@ -0,0 +1,144 @@
+import { ModelResolutionError } from "../model/errors.js";
+import {
+  isEntryEnabled,
+  isMergedRegistry
+} from "./provider-registry.js";
+export const MODEL_ROLE_KINDS = ["chat", "decision", "image", "tts", "stt"];
+export const STANDARD_MODEL_ROLES = [
+  {
+    id: "decision",
+    kind: "decision",
+    label: "Decision model",
+    description: "A small, fast model for classifying and routing: yes/no checks, picking a branch, tagging.",
+    enabled: true
+  },
+  {
+    id: "image",
+    kind: "image",
+    label: "Image model",
+    description: "Generates or edits images.",
+    enabled: true
+  },
+  {
+    id: "tts",
+    kind: "tts",
+    label: "Text to speech",
+    description: "The voice provider that reads text aloud.",
+    enabled: true
+  },
+  {
+    id: "stt",
+    kind: "stt",
+    label: "Speech to text",
+    description: "The voice provider that transcribes spoken input.",
+    enabled: true
+  }
+];
+function isVoiceRoleKind(kind) {
+  return kind === "tts" || kind === "stt";
+}
+function entryOf(registry, id) {
+  const entries = isMergedRegistry(registry) ? registry.providers : registry;
+  return Object.hasOwn(entries, id) ? entries[id] : void 0;
+}
+function parseSelector(selector) {
+  const slash = selector.indexOf("/");
+  if (slash <= 0 || slash === selector.length - 1) return void 0;
+  return { entryId: selector.slice(0, slash), modelId: selector.slice(slash + 1) };
+}
+function findRole(roles, id) {
+  return roles.find((role) => role.id === id);
+}
+function assignmentIssue(role, roleId, value, registry) {
+  const issue = (code, message) => ({
+    role: roleId,
+    code,
+    message
+  });
+  if (!role) return issue("unknown_role", `Model role '${roleId}' does not exist.`);
+  if (!role.enabled) {
+    return issue("disabled_role", `Model role '${role.label}' (${roleId}) is disabled.`);
+  }
+  const voice = isVoiceRoleKind(role.kind);
+  let entryId;
+  if (voice) {
+    if (value.includes("/")) {
+      return issue(
+        "bad_selector",
+        `Model role '${role.label}' (${roleId}) takes a provider id, not '${value}'.`
+      );
+    }
+    entryId = value;
+  } else {
+    const parsed = parseSelector(value);
+    if (!parsed) {
+      return issue(
+        "bad_selector",
+        `Model role '${role.label}' (${roleId}) takes '<provider>/<model>', not '${value}'.`
+      );
+    }
+    entryId = parsed.entryId;
+  }
+  const entry = entryOf(registry, entryId);
+  if (!entry) {
+    return issue(
+      "entry_missing",
+      `Model role '${role.label}' (${roleId}) points at provider '${entryId}', which is not in the registry.`
+    );
+  }
+  if (!isEntryEnabled(entry)) {
+    return issue(
+      "entry_disabled",
+      `Model role '${role.label}' (${roleId}) points at provider '${entryId}', which is disabled.`
+    );
+  }
+  const wanted = voice ? role.kind : "llm";
+  if (entry.kind !== wanted) {
+    return issue(
+      "entry_wrong_kind",
+      `Model role '${role.label}' (${roleId}) needs a '${wanted}' provider, but '${entryId}' is '${entry.kind}'.`
+    );
+  }
+  return void 0;
+}
+export function validateModelRoleAssignments(roles, assignments, registry) {
+  const issues = [];
+  for (const [roleId, value] of Object.entries(assignments)) {
+    if (!value) continue;
+    const issue = assignmentIssue(findRole(roles, roleId), roleId, value, registry);
+    if (issue) issues.push(issue);
+  }
+  return issues;
+}
+export function resolveModelRole(roleId, context) {
+  const role = findRole(context.roles, roleId);
+  if (!role) {
+    throw new ModelResolutionError("unknown_selector", `Model role '${roleId}' does not exist.`);
+  }
+  if (!role.enabled) {
+    throw new ModelResolutionError(
+      "unknown_selector",
+      `Model role '${role.label}' (${roleId}) is disabled.`
+    );
+  }
+  const value = Object.hasOwn(context.assignments, roleId) ? context.assignments[roleId] : void 0;
+  if (!value) return { kind: "unassigned" };
+  const issue = assignmentIssue(role, roleId, value, context.registry);
+  if (issue) {
+    const providerId = isVoiceRoleKind(role.kind) ? value : parseSelector(value)?.entryId;
+    throw new ModelResolutionError("unknown_selector", issue.message, {
+      ...providerId !== void 0 && entryOf(context.registry, providerId) ? { providerId } : {}
+    });
+  }
+  if (isVoiceRoleKind(role.kind)) return { kind: "voice", entryId: value };
+  return { kind: "model", selector: value, entryId: value.slice(0, value.indexOf("/")) };
+}
+export function modelRoleAliases(roles, assignments) {
+  const aliases = {};
+  for (const role of roles) {
+    if (!role.enabled || isVoiceRoleKind(role.kind)) continue;
+    const value = Object.hasOwn(assignments, role.id) ? assignments[role.id] : void 0;
+    if (value) aliases[role.id] = value;
+  }
+  return aliases;
+}

package/dist/runtime/vue/index.d.ts

@@ -9,6 +9,9 @@
 export * from "../shared/env-vars.js";
 export * from "../shared/harness-providers.js";
 export * from "../shared/harnesses.js";
+export * from "../shared/model-roles.js";
 export * from "../shared/provider-registry.js";
+export * from "./model-roles-panel.js";
+export * from "./providers-client.js";
 export * from "./settings-modal-scope.js";
 export * from "./useProvidersPanel.js";

package/dist/runtime/vue/index.js

@@ -1,6 +1,9 @@
 export * from "../shared/env-vars.js";
 export * from "../shared/harness-providers.js";
 export * from "../shared/harnesses.js";
+export * from "../shared/model-roles.js";
 export * from "../shared/provider-registry.js";
+export * from "./model-roles-panel.js";
+export * from "./providers-client.js";
 export * from "./settings-modal-scope.js";
 export * from "./useProvidersPanel.js";

package/dist/runtime/vue/model-roles-panel.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The model-roles panel's logic: which registry entries a role kind offers,
+ * how an assignment splits into provider and model, and what a row shows.
+ * No Vue, no requests, no `node:` imports; `ForgeModelRolesPanel` renders it.
+ */
+import type { ModelRoleAssignments, ModelRoleDefinition, ModelRoleKind } from "../shared/model-roles.js";
+import type { AIProviderKind } from "../shared/provider-registry.js";
+import type { ProvidersPanelEntry } from "./providers-panel-model.js";
+/** What the roles panel needs of a providers client; `ProvidersPanelClient` satisfies it. */
+export interface ModelRolesPanelClient {
+    /** Merged registry view including disabled entries. */
+    list(): Promise<ProvidersPanelEntry[]>;
+    /** The models one entry offers. */
+    models(id: string): Promise<ModelRolesModelsResult>;
+}
+/** The result of `ModelRolesPanelClient.models`. */
+export interface ModelRolesModelsResult {
+    status: "live" | "static" | "unsupported";
+    models: {
+        id: string;
+        name: string;
+    }[];
+    message?: string;
+}
+/** One option of a provider or model select. */
+export interface ModelRoleOption {
+    label: string;
+    value: string;
+}
+/** The registry entry kind a role kind assigns from. */
+export declare function roleEntryKind(kind: ModelRoleKind): AIProviderKind;
+/** Whether the role assigns an entry id (`tts`, `stt`) rather than a model. */
+export declare function isVoiceRole(kind: ModelRoleKind): boolean;
+/** The enabled entries of the kind this role assigns from. */
+export declare function entriesForRole(kind: ModelRoleKind, entries: readonly ProvidersPanelEntry[]): ProvidersPanelEntry[];
+/** `<entryId>/<modelId>`. */
+export declare function buildSelector(entryId: string, modelId: string): string;
+/** Splits on the first slash (model ids may contain slashes); no slash means no model. */
+export declare function splitSelector(selector: string): {
+    entryId: string;
+    modelId: string;
+};
+/** The assignment of a role; inherited keys such as `constructor` are not assignments. */
+export declare function assignmentOf(assignments: ModelRoleAssignments, roleId: string): string | undefined;
+/** The assignments with one role set; an empty value unassigns it. Never mutates. */
+export declare function withAssignment(assignments: ModelRoleAssignments, roleId: string, value: string): ModelRoleAssignments;
+/** What one row shows. */
+export interface ModelRoleRowState {
+    /** The provider the row has: the pending pick, else the assignment's. Empty when none. */
+    entryId: string;
+    /** The assigned model id (model roles only). */
+    modelId: string;
+    /** Whether the role has an assignment stored. */
+    assigned: boolean;
+    /** Enabled entries of the role's kind, plus the current one when it is unavailable. */
+    providerOptions: ModelRoleOption[];
+    /** Set when `entryId` is not an enabled entry of the role's kind. */
+    warning?: string;
+}
+/**
+ * The state of one row. `pendingEntryId` is a provider picked on a model role
+ * before a model exists: an assignment needs both, so the pick lives in the
+ * panel until the model is chosen.
+ */
+export declare function modelRoleRowState(role: ModelRoleDefinition, assignment: string | undefined, entries: readonly ProvidersPanelEntry[], pendingEntryId?: string): ModelRoleRowState;
+/** Options of a model select; the current model stays listed when the provider no longer offers it. */
+export declare function modelOptions(models: readonly {
+    id: string;
+    name: string;
+}[], currentModelId: string): ModelRoleOption[];

package/dist/runtime/vue/model-roles-panel.js

@@ -0,0 +1,54 @@
+export function roleEntryKind(kind) {
+  if (kind === "tts") return "tts";
+  if (kind === "stt") return "stt";
+  return "llm";
+}
+export function isVoiceRole(kind) {
+  return kind === "tts" || kind === "stt";
+}
+export function entriesForRole(kind, entries) {
+  const wanted = roleEntryKind(kind);
+  return entries.filter((entry) => entry.enabled && entry.kind === wanted);
+}
+export function buildSelector(entryId, modelId) {
+  return `${entryId}/${modelId}`;
+}
+export function splitSelector(selector) {
+  const slash = selector.indexOf("/");
+  if (slash < 0) return { entryId: selector, modelId: "" };
+  return { entryId: selector.slice(0, slash), modelId: selector.slice(slash + 1) };
+}
+export function assignmentOf(assignments, roleId) {
+  return Object.hasOwn(assignments, roleId) ? assignments[roleId] : void 0;
+}
+export function withAssignment(assignments, roleId, value) {
+  const next = { ...assignments };
+  if (value === "") delete next[roleId];
+  else next[roleId] = value;
+  return next;
+}
+export function modelRoleRowState(role, assignment, entries, pendingEntryId) {
+  const value = assignment ?? "";
+  const voice = isVoiceRole(role.kind);
+  const parsed = voice ? { entryId: value, modelId: "" } : splitSelector(value);
+  const entryId = pendingEntryId ?? parsed.entryId;
+  const modelId = entryId === parsed.entryId ? parsed.modelId : "";
+  const offered = entriesForRole(role.kind, entries);
+  const providerOptions = offered.map((entry) => ({ label: entry.name, value: entry.id }));
+  let warning;
+  if (entryId !== "" && !offered.some((entry) => entry.id === entryId)) {
+    providerOptions.push({ label: `${entryId} (unavailable)`, value: entryId });
+    warning = `Provider "${entryId}" is not available`;
+  }
+  return { entryId, modelId, assigned: value !== "", providerOptions, warning };
+}
+export function modelOptions(models, currentModelId) {
+  const options = models.map((model) => ({
+    label: model.name && model.name !== model.id ? `${model.name} (${model.id})` : model.id,
+    value: model.id
+  }));
+  if (currentModelId !== "" && !models.some((model) => model.id === currentModelId)) {
+    options.push({ label: `${currentModelId} (not listed)`, value: currentModelId });
+  }
+  return options;
+}

package/dist/runtime/vue/providers-client.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The transport of `ForgeProvidersPanel` (and the models of
+ * `ForgeModelRolesPanel`): one method per call the panels make. The default is
+ * {@link urlProvidersClient}, plain `ofetch` against the routes the panel
+ * always used; a host that backs the same screens with something other than
+ * HTTP routes (server actions, RPC) passes its own client. No Vue, no `node:`.
+ */
+import type { EnvSettingsDocument, EnvSettingsUpdate } from "../shared/env-vars.js";
+import { type ProvidersPanelEntry, type ProvidersPanelPreset } from "./providers-panel-model.js";
+/** The models of one provider entry, as `ProvidersPanelClient.models` answers. */
+export interface ProviderModelsResult {
+    /**
+     * `live`: asked the provider's own endpoint; `static`: a fixed list from the
+     * catalog; `unsupported`: the entry cannot list models (free-text entry).
+     */
+    status: "live" | "static" | "unsupported";
+    models: {
+        id: string;
+        name: string;
+    }[];
+    /** Why the list is empty or not live. Secret-free. */
+    message?: string;
+}
+/** The outcome of one provider credential test. */
+export interface ProvidersPanelTestResult {
+    ok: boolean;
+    /** What the provider answered or why it refused. Secret-free. */
+    message: string;
+}
+/** Every call `ForgeProvidersPanel` and `ForgeModelRolesPanel` make. */
+export interface ProvidersPanelClient {
+    /** The merged view, disabled entries included. */
+    list(): Promise<ProvidersPanelEntry[]>;
+    /** Presets whose key is set in the scope's environment. */
+    detected(): Promise<ProvidersPanelPreset[]>;
+    /** The catalog presets. */
+    presets(): Promise<ProvidersPanelPreset[]>;
+    /** Create or change an entry; the body is the registry entry's editable fields. */
+    upsert(id: string, body: Record<string, unknown>): Promise<void>;
+    /** Delete an entry of the scope's own document. */
+    remove(id: string): Promise<void>;
+    /** The scope's `.env` document. */
+    environment(): Promise<EnvSettingsDocument>;
+    /** Write variables to the scope's `.env`. */
+    updateEnvironment(update: EnvSettingsUpdate): Promise<void>;
+    /** The models of one entry. */
+    models(id: string): Promise<ProviderModelsResult>;
+    /** Check that the entry's credential works. */
+    test(id: string): Promise<ProvidersPanelTestResult>;
+}
+/** The URLs {@link urlProvidersClient} calls. */
+export interface UrlProvidersClientUrls {
+    /** `GET ${providersUrl}?all=1`: the merged view. */
+    providersUrl: string;
+    /** `PUT|DELETE ${providersWriteUrl}/:id`; `GET ${providersWriteUrl}/detected`; `GET .../:id/models`; `POST .../:id/test`. */
+    providersWriteUrl: string;
+    /** Catalog presets. Default `/api/providers/presets`. */
+    presetsUrl?: string;
+    /** The scope's `.env` route. Omitted, `environment` and `updateEnvironment` reject. */
+    environmentUrl?: string;
+}
+/**
+ * The HTTP transport: the requests the panel made before it took a client.
+ * `models` and `test` call routes skaile-forge does not serve; they are for
+ * hosts that do.
+ */
+export declare function urlProvidersClient(urls: UrlProvidersClientUrls): ProvidersPanelClient;

package/dist/runtime/vue/providers-client.js

@@ -0,0 +1,28 @@
+import { $fetch } from "ofetch";
+import {
+  DEFAULT_PRESETS_URL
+} from "./providers-panel-model.js";
+export function urlProvidersClient(urls) {
+  const entryUrl = (id) => `${urls.providersWriteUrl}/${encodeURIComponent(id)}`;
+  const environmentUrl = () => {
+    if (!urls.environmentUrl) throw new Error("This scope has no environment route.");
+    return urls.environmentUrl;
+  };
+  return {
+    list: () => $fetch(urls.providersUrl, { query: { all: "1" } }),
+    detected: () => $fetch(`${urls.providersWriteUrl}/detected`),
+    presets: () => $fetch(urls.presetsUrl ?? DEFAULT_PRESETS_URL),
+    upsert: async (id, body) => {
+      await $fetch(entryUrl(id), { method: "PUT", body });
+    },
+    remove: async (id) => {
+      await $fetch(entryUrl(id), { method: "DELETE" });
+    },
+    environment: async () => await $fetch(environmentUrl()),
+    updateEnvironment: async (update) => {
+      await $fetch(environmentUrl(), { method: "PUT", body: update });
+    },
+    models: (id) => $fetch(`${entryUrl(id)}/models`),
+    test: (id) => $fetch(`${entryUrl(id)}/test`, { method: "POST" })
+  };
+}

package/dist/runtime/vue/providers-panel-model.d.ts

@@ -6,14 +6,21 @@
  */
 import type { EnvLayerId } from "../shared/env-vars.js";
 import type { AIProviderCredentialKind, AIProviderKind, AIProviderSurface } from "../shared/provider-registry.js";
+import type { ProvidersPanelClient } from "./providers-client.js";
 /** Registry document a provider entry is defined in. */
 export type ProvidersPanelLayer = "instance" | "workspace";
 /** Props both `ForgeProvidersPanel` variants declare. */
 export interface ProvidersPanelProps {
-    /** `GET` merged view for this scope (`/api/providers` | `/api/workspaces/:id/providers`). */
-    providersUrl: string;
-    /** `PUT|DELETE ${providersWriteUrl}/:id`; `GET ${providersWriteUrl}/detected`. */
-    providersWriteUrl: string;
+    /**
+     * The panel's transport. Without it the panel talks to the URL props below
+     * through {@link urlProvidersClient}; with it the URL props are ignored. An
+     * explicit client also turns on the per-row Test button.
+     */
+    client?: ProvidersPanelClient;
+    /** `GET` merged view for this scope (`/api/providers` | `/api/workspaces/:id/providers`). Required without `client`. */
+    providersUrl?: string;
+    /** `PUT|DELETE ${providersWriteUrl}/:id`; `GET ${providersWriteUrl}/detected`. Required without `client`. */
+    providersWriteUrl?: string;
     /** Catalog preset summaries. Default `/api/providers/presets`. */
     presetsUrl?: string;
     /**
@@ -21,6 +28,12 @@ export interface ProvidersPanelProps {
      * into the panel write through it. Omitted, no key can be entered.
      */
     environmentUrl?: string;
+    /**
+     * Whether the panel reads and writes the scope's environment (key entry,
+     * the environment document). Default: `Boolean(environmentUrl)` without
+     * `client`, `true` with one.
+     */
+    environmentEnabled?: boolean;
     /** The scope's own registry document. */
     layer: ProvidersPanelLayer;
     /** Disables every write (non-admin at instance scope; provider lock). */

package/dist/runtime/vue/useProvidersPanel.d.ts

@@ -16,9 +16,10 @@
 import { type ComputedRef, type Ref, type WritableComputedRef } from "vue";
 import { type EnvSettingsDocument } from "../shared/env-vars.js";
 import { type AIProviderSurface } from "../shared/provider-registry.js";
-import { type ProvidersPanelEntry, type ProvidersPanelEmit, type ProvidersPanelForm, type ProvidersPanelPreset, type ProvidersPanelProps, type ProvidersPanelRow } from "./providers-panel-model.js";
-export { CREDENTIAL_ENTER_KEY, CREDENTIAL_OTHER_REF, CUSTOM_PRESET } from "./providers-panel-model.js";
+import { type ProvidersPanelTestResult } from "./providers-client.js";
+import { type ProvidersPanelEmit, type ProvidersPanelEntry, type ProvidersPanelForm, type ProvidersPanelPreset, type ProvidersPanelProps, type ProvidersPanelRow } from "./providers-panel-model.js";
 export type { ProvidersPanelCredentialOption, ProvidersPanelEmit, ProvidersPanelEntry, ProvidersPanelForm, ProvidersPanelLayer, ProvidersPanelPreset, ProvidersPanelProps, ProvidersPanelRow, ProvidersPanelRowState, } from "./providers-panel-model.js";
+export { CREDENTIAL_ENTER_KEY, CREDENTIAL_OTHER_REF, CUSTOM_PRESET } from "./providers-panel-model.js";
 /** What both `ForgeProvidersPanel` variants bind to. */
 export interface ProvidersPanelState {
     /** The scope's entries, disabled ones included, in registry order. */
@@ -82,6 +83,13 @@ export interface ProvidersPanelState {
         id: string;
         message: string;
     } | null>;
+    /** The panel was given an explicit client: rows offer a connection test. */
+    canTest: ComputedRef<boolean>;
+    /** Row id with a test in flight. */
+    testBusy: Ref<string | null>;
+    /** The last test result per row id. */
+    testResults: Record<string, ProvidersPanelTestResult>;
+    testProvider: (row: ProvidersPanelEntry) => Promise<void>;
     /** "Enter a key…" is offered: the scope has an editable `.env` route. */
     canEnterKey: ComputedRef<boolean>;
     /** Row id whose key editor is open. */