@skaile/forge-settings 0.0.0-stage → 1.0.1

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: "",
+};

package/src/runtime/vue/settings-modal-scope.ts

@@ -0,0 +1,66 @@
+/**
+ * The tier a settings modal edits, and the URLs of its routes.
+ *
+ * The URL protocol is the host's: every field names a route the host serves,
+ * and no component builds a URL from an id or a slug. `ForgeProvidersPanel`
+ * takes the `providers*` / `environmentUrl` / `providersLayer` fields of this
+ * record as its props; the rest belong to the host's own modal tabs (harness,
+ * voice, workspace), which stay in the host.
+ */
+
+/** Which settings tier a modal edits. */
+export type SettingsModalSettingsScope = "instance" | "workspace";
+
+/**
+ * The tier the modal edits: the instance (app-wide defaults) or one
+ * workspace. The caller owns every route: the modal never builds a URL from an
+ * id or slug.
+ */
+export interface SettingsModalScope {
+  /** Dialog header text, e.g. the workspace name. */
+  label: string;
+  /**
+   * `"instance"`: the Harness tab edits the instance defaults
+   * (`PUT /api/settings?scope=instance`); `"workspace"`: it edits this
+   * workspace's overrides through {@link settingsUrl}.
+   */
+  settingsScope: SettingsModalSettingsScope;
+  /**
+   * `GET`/`PUT` endpoint of this scope's settings: `/api/settings` for the
+   * instance, the workspace's override row (`{ harness, model }`) otherwise.
+   */
+  settingsUrl: string;
+  /** Base URL for the Workspace + Connectors tabs' config API calls. */
+  workspaceApiBaseUrl: string;
+  /** `GET` model catalog of this scope's registry, queried with `?harness=<id>`. */
+  modelsUrl: string;
+  /** Provider registry write base: `PUT|DELETE <url>/:id`, `GET <url>/detected`. */
+  providersWriteUrl: string;
+  /**
+   * `GET` endpoint of this scope's `.env` layer, which the Providers tab reads and
+   * writes. Defaults to the instance layer, `/api/settings/env`.
+   */
+  environmentUrl?: string;
+  /**
+   * `GET` endpoint listing registry entries with their credential status
+   * resolved against this scope's environment. Defaults to `/api/providers`.
+   */
+  providersUrl?: string;
+  /**
+   * The registry document the Providers tab edits, when it differs from
+   * {@link settingsScope}. A single-workspace app keeps instance settings but
+   * writes the workspace registry over a user-level one: `"workspace"` there
+   * makes the lower document's entries inherited and patchable.
+   */
+  providersLayer?: SettingsModalSettingsScope;
+  /** Workspace name for workspace-scope copy (the harness-change confirm); defaults to {@link label}. */
+  workspaceName?: string;
+  /** The caller may read but not write this scope (e.g. a `readonly` user, another owner's workspace). */
+  readOnly?: boolean;
+}
+
+/** Default `GET` route of the merged provider list. */
+export const DEFAULT_PROVIDERS_URL = "/api/providers";
+
+/** Default `GET`/`PUT` route of the instance `.env` layer. */
+export const DEFAULT_ENVIRONMENT_URL = "/api/settings/env";