@skaile/forge-settings 1.0.0 → 1.1.0

package/dist/runtime/vue/useProvidersPanel.js

@@ -13,43 +13,21 @@ import {
   AI_PROVIDER_SURFACES,
   validateCredentialRef
 } from "../shared/provider-registry.js";
-export const CUSTOM_PRESET = "__custom__";
-export const CREDENTIAL_ENTER_KEY = "__enter_key__";
-export const CREDENTIAL_OTHER_REF = "__other_ref__";
-const PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
-const DEFAULT_PRESETS_URL = "/api/providers/presets";
-const ENV_REF_PATTERN = /^env:(.+)$/;
-const FALLBACK_CREDENTIAL_KIND = "api_key_header";
-const ENV_SOURCE_LABEL = {
-  instance: "instance .env",
-  workspace: "workspace .env",
-  process: "boot environment"
-};
-const OVERRIDES_INSTANCE_NOTICE = "Entering a key here stores it in this workspace's .env and overrides that value for this workspace.";
-function requestErrorMessage(err, fallback) {
-  const e = err;
-  const details = (e?.data?.data?.diagnostics ?? []).map((d) => d.message).filter((m) => typeof m === "string" && m !== "");
-  if (details.length > 0) return details.join("; ");
-  const message = e?.data?.statusMessage ?? e?.statusMessage;
-  return typeof message === "string" && message ? message : fallback;
-}
-function envNameOfRef(ref2) {
-  return ref2 ? ENV_REF_PATTERN.exec(ref2)?.[1] : void 0;
-}
-function nonEnvSourceLabel(ref2) {
-  if (ref2.startsWith("keyring:")) return "keyring";
-  if (ref2.startsWith("cmd:")) return "runtime-owned (cmd)";
-  if (ref2.startsWith("platform:")) return "control-plane-owned (platform)";
-  return void 0;
-}
-const EMPTY_FORM = {
-  preset: "",
-  id: "",
-  surface: "",
-  baseUrl: "",
-  envName: "",
-  secret: ""
-};
+import {
+  CREDENTIAL_ENTER_KEY,
+  CREDENTIAL_OTHER_REF,
+  CUSTOM_PRESET,
+  DEFAULT_PRESETS_URL,
+  EMPTY_FORM,
+  ENV_SOURCE_LABEL,
+  envNameOfRef,
+  FALLBACK_CREDENTIAL_KIND,
+  nonEnvSourceLabel,
+  OVERRIDES_INSTANCE_NOTICE,
+  PROVIDER_ID_PATTERN,
+  requestErrorMessage
+} from "./providers-panel-model.js";
+export { CREDENTIAL_ENTER_KEY, CREDENTIAL_OTHER_REF, CUSTOM_PRESET } from "./providers-panel-model.js";
 export function useProvidersPanel(props, emit) {
   const providers = ref([]);
   const presets = ref([]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skaile/forge-settings",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Provider and settings operations for Skaile forge apps: provider registry layers, credential store, env layers, model discovery, the providers panel, and editor / AI SDK model adapters.",
   "type": "module",
   "packageManager": "bun@1.3.9",
@@ -55,7 +55,7 @@
   },
   "dependencies": {
     "@nuxt/kit": "^4.0.0",
-    "@skaile/workspaces": "^6.10.0",
+    "@skaile/workspaces": "^6.14.0",
     "ofetch": "^1.4.0",
     "yaml": "^2.9.0"
   },

package/src/runtime/ai-sdk/index.ts

@@ -17,8 +17,8 @@
 import { parseModelRef } from "@skaile/workspaces/core";
 import { type ResolvedLanguageModel, resolveLanguageModel } from "@skaile/workspaces/ai-sdk";
 import { loadMergedProviderRegistry } from "@skaile/workspaces/sdk/bridge";
-import { type CredentialPolicy, entryPolicyRefusal } from "../server/credential-policy";
-import { ModelResolutionError } from "../model/errors";
+import type { CredentialPolicy } from "../server/credential-policy";
+import { ModelResolutionError, assertEntryAllowed } from "../model/errors";
 
 export { ModelResolutionError } from "../model/errors";
 export type { ModelResolutionCode } from "../model/errors";
@@ -47,7 +47,8 @@ export interface ResolveRegistryLanguageModelOptions {
  * `@role`), resolved by Workspaces against the registry on disk.
  *
  * @throws {ModelResolutionError} `registry_invalid` · `unknown_selector` ·
- *   `policy_refused` · `unresolved` (credential, endpoint or provider SDK).
+ *   `policy_refused` · `unresolved` (credential, endpoint or provider SDK; the
+ *   message is fixed and never carries Workspaces' text, which stays on `cause`).
  */
 export async function resolveRegistryLanguageModel(
   selector: string,
@@ -66,14 +67,7 @@ export async function resolveRegistryLanguageModel(
     throw new ModelResolutionError("unknown_selector", `no provider serves '${selector}'`);
   }
   const entry = merged.providers[ref.providerId];
-  if (entry && options.policy) {
-    const refusal = entryPolicyRefusal(entry, options.policy);
-    if (refusal) {
-      throw new ModelResolutionError("policy_refused", `provider '${ref.providerId}': ${refusal}`, {
-        providerId: ref.providerId,
-      });
-    }
-  }
+  if (entry) assertEntryAllowed(entry, ref.providerId, options.policy);
 
   try {
     return await resolveLanguageModel(selector, {
@@ -82,9 +76,12 @@ export async function resolveRegistryLanguageModel(
       ...(options.roles ? { roles: options.roles } : {}),
     });
   } catch (cause) {
+    // Workspaces' message is not ours to vouch for: it can echo a resolved
+    // credential or an endpoint with a key in its query. The message is fixed;
+    // the original error stays on `cause` for a host that logs it server-side.
     throw new ModelResolutionError(
       "unresolved",
-      cause instanceof Error ? cause.message : String(cause),
+      `provider '${ref.providerId}': credential, endpoint or provider SDK could not be resolved`,
       { providerId: ref.providerId, cause },
     );
   }

package/src/runtime/editor/index.ts

@@ -22,7 +22,7 @@
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import type { ModelProfile, ModelRef } from "@skaile/forge-editor/ai";
 import type { ModelProvider } from "@skaile/forge-editor/server";
-import { ModelResolutionError } from "../model/errors";
+import { ModelResolutionError, assertEntryAllowed } from "../model/errors";
 import { type CredentialPolicy, entryPolicyRefusal } from "../server/credential-policy";
 import { resolveEntryCredential } from "../server/credential-store";
 import { listAIProviderModels } from "../server/provider-service";
@@ -64,7 +64,7 @@ export function editorModelProfiles(
   const entries = editorEntries(registry);
   const allowed = (providerId: string) => {
     const entry = entries.get(providerId);
-    return entry !== undefined && !(options.policy && entryPolicyRefusal(entry, options.policy));
+    return entry !== undefined && !entryPolicyRefusal(entry, options.policy);
   };
   return listAIProviderModels(registry)
     .filter((model) => allowed(model.providerId))
@@ -96,18 +96,7 @@ export function editorLanguageModel(
   const model = listAIProviderModels(registry).find((candidate) => candidate.id === ref.preset);
   const entry = model && editorEntries(registry).get(model.providerId);
   if (!model || !entry) return null;
-  if (options.policy) {
-    const refusal = entryPolicyRefusal(entry, options.policy);
-    if (refusal) {
-      throw new ModelResolutionError(
-        "policy_refused",
-        `AI provider "${model.providerId}": ${refusal}`,
-        {
-          providerId: model.providerId,
-        },
-      );
-    }
-  }
+  assertEntryAllowed(entry, model.providerId, options.policy);
   const credential = resolveEntryCredential(entry, {
     env,
     ...(options.policy ? { policy: options.policy } : {}),
@@ -115,7 +104,7 @@ export function editorLanguageModel(
   if (credential.error && !credential.value) {
     throw new ModelResolutionError(
       "unresolved",
-      `AI provider "${model.providerId}": ${credential.error}`,
+      `provider '${model.providerId}': ${credential.error}`,
       { providerId: model.providerId },
     );
   }

package/src/runtime/model/errors.ts

@@ -1,3 +1,6 @@
+import { type CredentialPolicy, entryPolicyRefusal } from "../server/credential-policy";
+import type { AIProviderEntry } from "../shared/provider-registry";
+
 /**
  * A model could not be resolved. Framework-free: the host decides which HTTP
  * status (or tool error) each `code` becomes.
@@ -29,3 +32,21 @@ export class ModelResolutionError extends Error {
     if (options.providerId !== undefined) this.providerId = options.providerId;
   }
 }
+
+/**
+ * Throw `policy_refused` when `policy` refuses `entry`; no policy refuses
+ * nothing. The one place a model adapter turns a policy refusal into an error,
+ * so every adapter words it the same way. Nothing is resolved.
+ */
+export function assertEntryAllowed(
+  entry: AIProviderEntry,
+  providerId: string,
+  policy?: CredentialPolicy,
+): void {
+  const refusal = entryPolicyRefusal(entry, policy);
+  if (refusal) {
+    throw new ModelResolutionError("policy_refused", `provider '${providerId}': ${refusal}`, {
+      providerId,
+    });
+  }
+}

package/src/runtime/server/credential-policy.ts

@@ -90,11 +90,13 @@ function interpolationRefusal(
 /**
  * The reason an entry is refused, or `undefined`: its credential reference and
  * every environment name it interpolates are checked, nothing is resolved.
+ * Without a policy nothing is refused.
  */
 export function entryPolicyRefusal(
   entry: AIProviderEntry,
-  policy: CredentialPolicy,
+  policy?: CredentialPolicy,
 ): string | undefined {
+  if (!policy) return undefined;
   const ref = entry.credential?.ref;
   if (ref !== undefined) {
     const refusal = credentialRefRefusal(ref, policy);

package/src/runtime/server/credential-store.ts

@@ -366,7 +366,7 @@ export function resolveEntryCredential(
   entry: AIProviderEntry,
   options: CredentialStoreOptions = {},
 ): ResolvedCredential {
-  const refusal = options.policy ? entryPolicyRefusal(entry, options.policy) : undefined;
+  const refusal = entryPolicyRefusal(entry, options.policy);
   if (refusal) return { source: "none", error: refusal };
   const credential = entry.credential;
   if (!credential || credential.kind === "none") return { source: "none" };

package/src/runtime/server/env-layers.ts

@@ -17,6 +17,7 @@
 import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { AI_PROVIDER_PRESETS } from "@skaile/workspaces/sdk/bridge";
+import { isPlainObject } from "../shared/guards";
 import type { AIProviderRegistryView } from "../shared/provider-registry";
 import { parseCredentialRef, registryEntries } from "../shared/provider-registry";
 import {
@@ -250,10 +251,6 @@ export function buildEnvSettingsDocument(input: EnvSettingsDocumentInput): EnvSe
 
 // ── Update validation ──────────────────────────────────────────────────────
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * Validate a `PUT <environmentUrl>` body. Returns the normalized update, or a
  * refusal string suitable as an HTTP 400 status message.

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

@@ -20,6 +20,7 @@
  * Pure functions over plain values: no Node built-ins, no environment, no file access.
  */
 
+import type { HarnessDetection } from "@skaile/workspaces/sdk/bridge";
 import type { HarnessInfo } from "@skaile/workspaces/types";
 import {
   DEFAULT_ENABLED_HARNESSES,
@@ -96,6 +97,8 @@ export type HarnessRow = HarnessInfo & {
   experimental: boolean;
   /** Whether the instance's `enabledHarnesses` offers it. */
   enabled: boolean;
+  /** What `detectHarnesses()` found on this host: installed, version, login. */
+  detection: HarnessDetection;
 };
 
 /**
@@ -103,10 +106,13 @@ export type HarnessRow = HarnessInfo & {
  * filter to `enabled` unless the request asked for all (`?all=1`).
  * `surfaces` and `providerPlurality` ride along from {@link HarnessInfo} so the
  * Harness tab can offer each harness only the providers it can use.
+ * `detections` is the host's `detectHarnesses()` answer; a harness it does not
+ * mention (or every harness, when it is omitted) reports `{ status: "unknown" }`.
  */
 export function buildHarnessRows(
   harnesses: HarnessInfo[],
   s: Pick<HarnessSettings, "enabledHarnesses">,
+  detections: readonly HarnessDetection[] = [],
 ): HarnessRow[] {
   const enabled = new Set(enabledHarnessIds(s));
   return harnesses.map((info) => ({
@@ -114,6 +120,7 @@ export function buildHarnessRows(
     label: HARNESS_LABELS[info.id] ?? info.name,
     experimental: isExperimentalHarness(info.id),
     enabled: enabled.has(info.id),
+    detection: detections.find((d) => d.id === info.id) ?? { id: info.id, status: "unknown" },
   }));
 }
 

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

@@ -104,7 +104,7 @@ export async function discoverProviderModels(
   if (!isEntryEnabled(entry)) return { status: "error", providerId, error: "entry is disabled" };
 
   // The policy decides before anything is resolved or requested.
-  const refusal = options.policy ? entryPolicyRefusal(entry, options.policy) : undefined;
+  const refusal = entryPolicyRefusal(entry, options.policy);
   if (refusal) return { status: "error", providerId, error: refusal };
 
   const credential = resolveEntryCredential(entry, {

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

@@ -16,14 +16,11 @@ import {
 } from "@skaile/workspaces/core";
 import { AI_PROVIDER_PRESETS, type AIProviderPreset } from "@skaile/workspaces/sdk/bridge";
 import { parse as parseYaml } from "yaml";
+import { isPlainObject } from "../shared/guards";
 
 /** The `.yaml` spelling of {@link PROVIDERS_FILENAME}. */
 const PROVIDERS_FILENAME_ALIAS = "providers.yaml";
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * The file a write to the layer at `path` goes to: the `.yaml` spelling when
  * only that one exists, so an edit never shadows a hand-written document.

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

@@ -39,6 +39,7 @@ import {
   type AIProviderPreset,
   expandPreset,
 } from "@skaile/workspaces/sdk/bridge";
+import { isPlainObject } from "../shared/guards";
 import type { AIProviderEntry, AIProviderRegistry } from "../shared/provider-registry";
 import { type CredentialPolicy, entryPolicyRefusal } from "./credential-policy";
 import { catalogPreset, readProviderLayer, writeProviderLayer } from "./provider-layers";
@@ -130,10 +131,6 @@ export function providerScopeWritable(
   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";
@@ -300,9 +297,7 @@ export function upsertProviderEntry(
   }
   const next = { ...providers, [id]: entry };
 
-  const refusal = scope.policy
-    ? entryPolicyRefusal(entry as unknown as AIProviderEntry, scope.policy)
-    : undefined;
+  const refusal = entryPolicyRefusal(entry as unknown as AIProviderEntry, scope.policy);
   if (refusal) throw createError({ statusCode: 400, statusMessage: refusal });
 
   const diagnostics = entryErrors(scope, next, id);

package/src/runtime/shared/guards.ts

@@ -0,0 +1,4 @@
+/** A non-null, non-array object. */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/runtime/vue/providers-panel-model.ts

@@ -0,0 +1,203 @@
+/**
+ * The providers panel's vocabulary: the types the panel and its composable
+ * share, the constants of its form, and the pure reference / error helpers.
+ * No Vue, no requests — testable on their own. The public types and constants
+ * are re-exported by `useProvidersPanel`; the rest is internal to the package.
+ */
+
+import type { EnvLayerId } from "../shared/env-vars";
+import type {
+  AIProviderCredentialKind,
+  AIProviderKind,
+  AIProviderSurface,
+} from "../shared/provider-registry";
+
+/** 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;
+  /** Catalog preset summaries. Default `/api/providers/presets`. */
+  presetsUrl?: string;
+  /**
+   * The scope's `.env` route. `GET` on load and after every write; keys typed
+   * into the panel write through it. Omitted, no key can be entered.
+   */
+  environmentUrl?: string;
+  /** The scope's own registry document. */
+  layer: ProvidersPanelLayer;
+  /** Disables every write (non-admin at instance scope; provider lock). */
+  readOnly?: boolean;
+}
+
+/** Emits both variants declare. */
+export type ProvidersPanelEmit = (event: "changed") => void;
+
+/** One entry of `GET ${providersUrl}?all=1`. */
+export interface ProvidersPanelEntry {
+  id: string;
+  /** The entry's label, else its id. */
+  name: string;
+  kind: AIProviderKind;
+  /** Whether the credential reference resolved on the server. */
+  configured: boolean;
+  /** Why it did not resolve. Secret-free. */
+  error?: string;
+  credentialRef?: string;
+  credentialKind?: AIProviderCredentialKind;
+  hasEnvKey: boolean;
+  envKeyName?: string;
+  baseUrl?: string;
+  preset?: string;
+  surface?: AIProviderSurface;
+  enabled: boolean;
+  locked: boolean;
+  /** Registry documents holding the id, lowest first: `["instance"]`, `["workspace"]` or both. */
+  layers: ProvidersPanelLayer[];
+  /** The scope's own document's values for the editable fields the dialog does not show. */
+  layerFields?: Record<string, unknown>;
+}
+
+/** One catalog preset, as `GET /api/providers/presets` and `.../detected` list it. */
+export interface ProvidersPanelPreset {
+  id: string;
+  label: string;
+  kind: AIProviderKind;
+  surface?: AIProviderSurface;
+  base_url?: string;
+  base_url_env?: string;
+  credential: { kind: AIProviderCredentialKind; env?: string };
+}
+
+/** Where a row's entry lives relative to the scope's own document. */
+export type ProvidersPanelRowState = "own" | "inherited" | "patched";
+
+/** One entry of a row's credential select. */
+export interface ProvidersPanelCredentialOption {
+  /** An env var NAME, a literal non-env ref, {@link CREDENTIAL_ENTER_KEY} or {@link CREDENTIAL_OTHER_REF}. */
+  value: string;
+  /** `NAME ••••hint` | `NAME (not set)` | the literal ref | `Enter a key…` | `Other reference…`. */
+  label: string;
+  defined?: boolean;
+  hint?: string;
+  source?: EnvLayerId;
+  action?: "enter-key" | "other-ref";
+}
+
+/** A table row: the entry plus what the panel derives for it. */
+export interface ProvidersPanelRow extends ProvidersPanelEntry {
+  /** Own entry, an inherited one, or an inherited one this scope patched. */
+  state: ProvidersPanelRowState;
+  /** `instance` | `workspace` | `instance · overridden here`. */
+  badge: string;
+  /** Set on inherited rows. */
+  inheritedNote?: string;
+  /** Edit/Delete offered: the scope's document defines it and the panel is writable. */
+  editable: boolean;
+  /** Reset offered: a patched row of a writable panel. */
+  canReset: boolean;
+  /** The enabled switch is live. */
+  canToggle: boolean;
+  /** The entry takes a credential (its kind is not `none`). */
+  needsCredential: boolean;
+  /** The credential picker is live. */
+  canEditCredential: boolean;
+  /** The select's model: the env var NAME of an `env:` ref, else the literal ref, else `""`. */
+  credentialValue: string;
+  credentialOptions: ProvidersPanelCredentialOption[];
+  /** The preset it inherits, else its surface, else its kind. */
+  origin: string;
+  /** `configured · <source>`, `missing <VAR>`, the resolver's reason, or `No credential needed.`. */
+  status: string;
+  /** Which other layer defines or overrides the credential; see the panel contract. */
+  overrideNotices: string[];
+}
+
+/** The add/edit dialog's fields. */
+export interface ProvidersPanelForm {
+  /** A preset id, or {@link CUSTOM_PRESET}. */
+  preset: string;
+  id: string;
+  /** Custom entries only. */
+  surface: string;
+  /** Empty: the preset's endpoint. */
+  baseUrl: string;
+  /** Adding only: the `env:` variable the credential references. */
+  envName: string;
+  /** Adding only, "Set value now": written to the scope's `.env`, never to the provider route. */
+  secret: string;
+}
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+/** The preset select's value for an entry that names no preset. */
+export const CUSTOM_PRESET = "__custom__";
+
+/** Credential select value: open the inline key editor. */
+export const CREDENTIAL_ENTER_KEY = "__enter_key__";
+
+/** Credential select value: open the inline reference editor. */
+export const CREDENTIAL_OTHER_REF = "__other_ref__";
+
+/** Registry ids the write routes accept (`isSafeProviderId` upstream). */
+export const PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
+
+export const DEFAULT_PRESETS_URL = "/api/providers/presets";
+
+/** An `env:NAME` credential reference; group 1 is the variable name. */
+export const ENV_REF_PATTERN = /^env:(.+)$/;
+
+/** The credential kind a written reference gets when the row states none. */
+export const FALLBACK_CREDENTIAL_KIND: AIProviderCredentialKind = "api_key_header";
+
+export const ENV_SOURCE_LABEL: Record<EnvLayerId, string> = {
+  instance: "instance .env",
+  workspace: "workspace .env",
+  process: "boot environment",
+};
+
+export const OVERRIDES_INSTANCE_NOTICE =
+  "Entering a key here stores it in this workspace's .env and overrides that value for this workspace.";
+
+/**
+ * The server's refusal for a failed request, else `fallback`. A registry
+ * rejection (`400` with `data.diagnostics`) reads as its diagnostics' messages.
+ */
+export function requestErrorMessage(err: unknown, fallback: string): string {
+  const e = err as {
+    data?: { statusMessage?: unknown; data?: { diagnostics?: Array<{ message?: unknown }> } };
+    statusMessage?: unknown;
+  } | null;
+  const details = (e?.data?.data?.diagnostics ?? [])
+    .map((d) => d.message)
+    .filter((m): m is string => typeof m === "string" && m !== "");
+  if (details.length > 0) return details.join("; ");
+  const message = e?.data?.statusMessage ?? e?.statusMessage;
+  return typeof message === "string" && message ? message : fallback;
+}
+
+/** The variable name of an `env:NAME` reference. */
+export function envNameOfRef(ref: string | undefined): string | undefined {
+  return ref ? ENV_REF_PATTERN.exec(ref)?.[1] : undefined;
+}
+
+/** `configured · …` for a reference that is not an env var. */
+export function nonEnvSourceLabel(ref: string): string | undefined {
+  if (ref.startsWith("keyring:")) return "keyring";
+  if (ref.startsWith("cmd:")) return "runtime-owned (cmd)";
+  if (ref.startsWith("platform:")) return "control-plane-owned (platform)";
+  return undefined;
+}
+
+export const EMPTY_FORM: Readonly<ProvidersPanelForm> = {
+  preset: "",
+  id: "",
+  surface: "",
+  baseUrl: "",
+  envName: "",
+  secret: "",
+};