@skaile/forge-settings 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 1.0.1
+
+- `@skaile/forge-settings/ai-sdk`: an `unresolved` `ModelResolutionError` no longer copies Workspaces' error text into `message` (it could echo a resolved credential or a key in an endpoint query). The message is now fixed (`provider '<id>': credential, endpoint or provider SDK could not be resolved`); the original error stays on `cause`.
+- Refusal wording is one format across adapters: `provider '<id>': <reason>`. `./editor` previously said `AI provider "<id>": <reason>`, for both `policy_refused` and `unresolved`.
+- `entryPolicyRefusal(entry, policy?)` accepts an absent policy (refuses nothing), so call sites no longer branch on it.
+- Internal: one `isPlainObject`, one `assertEntryAllowed`, and the providers panel's types and pure reference helpers moved to `vue/providers-panel-model.ts`. No public export changes.
+
+## 1.0.0
+
+First release. Extracted from `@skaile/forge-common` (provider/settings half) and skaile-forge's editor model adapter; `@skaile/forge-common` is unchanged and stays installable for consumers that have not migrated.
+
+- `@skaile/forge-settings/server`: provider registry vocabulary, layer read/write (`readProviderLayer`, `writeProviderLayer`, `upsertProviderEntry`, `removeProviderEntry`, `withProviderLayers`, `catalogPreset`), the credential store (AES-256-GCM, 64-hex `FORGE_CREDENTIAL_KEY`, reference as per-record AAD), `.env` layer helpers, provider inventory (`listAIProviders`, `listAIProviderModels`, `testAIProviderCredential`), harness settings rules, voice provider selection and legacy-settings migration. Imports no Vue, editor, AI SDK or agent session code.
+- `@skaile/forge-settings/vue`: `useProvidersPanel`, `SettingsModalScope` (and its URL fields), and the browser-safe env/harness/registry vocabulary.
+- `@skaile/forge-settings/nuxt`: registers `<ForgeProvidersPanel>` (needs `@nuxt/ui` registered first). No route, auto-import or authorization.
+- `@skaile/forge-settings/ai-sdk`: `resolveRegistryLanguageModel(selector, { projectDir, env, roles?, policy? })` over `@skaile/workspaces/ai-sdk`'s `resolveLanguageModel`.
+- `@skaile/forge-settings/editor`: `createEditorModelProvider({ registry, env, policy?, onFailure? })`, an implementation of `@skaile/forge-editor`'s `ModelProvider`, plus `editorModelProfiles` and `editorLanguageModel`.
+
+Added over the extracted code:
+
+- `CredentialPolicy` (`forms`, `envNames`): a host states which references may be resolved. `entryPolicyRefusal` checks an entry's `credential.ref` and every `${NAME}` interpolation in `base_url`, `headers` and `query_params` before anything is read; `applyCredentialPolicy` filters a registry. `CredentialStoreOptions.policy` and `.env`: a policy-bound call reads only the explicit `env` (an empty one when omitted), never `process.env`. `ProviderWriteScope.policy` refuses writes that name a refused reference.
+- `CredentialKeyError` (`statusCode: 503`): only operations that need the encrypted store raise it; `env:` references resolve without a key. `CredentialDecryptError` for a replayed or altered blob.
+- `ProviderWriteError` replaces h3's `createError` in the provider write helpers; it carries `statusCode`, `statusMessage` and `data`, which an H3 host answers unchanged. The package has no h3 dependency.
+- `discoverProviderModels`: live model discovery with an explicit `status` (`live` | `static` | `unsupported` | `error`), so an offline catalog is never presented as live. Error text is built here, carries no remote response body, and has resolved secrets (and any `redact` strings) removed.
+- `ModelResolutionError` (`registry_invalid` | `unknown_selector` | `policy_refused` | `unresolved`): framework-free, mapped to HTTP by the host.
+
+Not included (host-owned): storage (`getUserSettings`/`saveUserSettings`), workspace ACLs and lock flags, agent sessions, a settings action catalogue.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthias Ortegro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# @skaile/forge-settings
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Provider and settings operations for Skaile forge apps, without the app's database, authentication or agent runtime.
+
+| Entry | Contents | Peers it needs |
+|---|---|---|
+| `/server` | registry layers and writes, credential store, `.env` layers, provider inventory and discovery, harness settings rules, credential policy | none |
+| `/vue` | `useProvidersPanel`, `SettingsModalScope`, browser-safe registry/env/harness vocabulary | `vue` |
+| `/nuxt` | Nuxt module registering `<ForgeProvidersPanel>` | `nuxt`, `@nuxt/ui` |
+| `/ai-sdk` | AI SDK `LanguageModel` of a registry selector | `ai` + the `@ai-sdk/*` provider the surface needs |
+| `/editor` | the editor's `ModelProvider` over a registry | `@skaile/forge-editor`, `@ai-sdk/openai-compatible` |
+
+Importing `/server` loads no Vue, editor, AI SDK or agent session code. Every peer is optional and used by one entry only.
+
+## What stays with the host
+
+Where settings are stored, who may write which scope, workspace ACLs, lock flags, and what a failure becomes over HTTP. The package supplies the operations (`upsertProviderEntry`, `removeProviderEntry`, `buildEnvSettingsDocument`, …) and the rules they enforce on a document; the host builds a `ProviderWriteScope` (file paths, effective env, lock state, optional `policy`) after its own authentication and permission check.
+
+## Credential policy
+
+A host that runs next to its own secrets (a database token, an encryption key) states up front which references may be resolved:
+
+```ts
+import { type CredentialPolicy } from '@skaile/forge-settings/server'
+
+const policy: CredentialPolicy = {
+  forms: ['env'],                                   // no cmd:, keyring:, platform:
+  envNames: [/ASSISTENT_PROVIDER_[A-Z0-9_]+/, 'NUXT_AI_API_KEY'], // whole-name match
+}
+```
+
+The policy is checked against `credential.ref` and every `${NAME}` token in `base_url`, `headers` and `query_params` **before** anything is read; a refused reference is never resolved, looked up or requested. A policy-bound call reads only the `env` you pass (an empty one when omitted), never `process.env`. Without a policy, behaviour is the unrestricted forge-common behaviour.
+
+```ts
+const scope: ProviderWriteScope = { name: 'instance', file, below: [], env, lock, policy } // refuses writes naming a refused ref
+discoverProviderModels('main', registry, { env, policy })
+resolveRegistryLanguageModel('main/gpt-x', { projectDir, env, policy })
+```
+
+## Credential store
+
+`keyring:<service>/<account>` references are stored AES-256-GCM encrypted in a JSON file; the reference is the additional authenticated data, so a blob cannot be replayed under another reference. The key is `FORGE_CREDENTIAL_KEY` (64 hex characters) or `options.key`. Without it only operations that need the store fail, with `CredentialKeyError` (`statusCode: 503`); `env:` references keep working. A blob that does not authenticate raises `CredentialDecryptError`.
+
+## Model discovery
+
+`discoverProviderModels(id, registry, { env, policy?, redact? })` returns `live`, `static` (the offline catalog, with the scrubbed reason the live request failed), `unsupported` (no catalog preset: let the admin type a model id) or `error`. Error text never contains a remote response body, and every secret the call resolved (plus `redact`) is removed from it, also in URL-encoded and base64 form.
+
+## Models for the editor and the AI SDK
+
+```ts
+// server/utils/editor-models.ts: ModelProvider for @skaile/forge-editor
+import { createEditorModelProvider, ModelResolutionError } from '@skaile/forge-settings/editor'
+
+export const models = createEditorModelProvider({
+  registry: () => getProviderRegistry(home()),
+  env: () => effectiveEnv(),
+  policy,                                            // refused entries are neither listed nor resolved
+  onFailure: (e) => createError({ statusCode: e.code === 'policy_refused' ? 403 : 400, statusMessage: e.message }),
+})
+```
+
+```ts
+import { resolveRegistryLanguageModel } from '@skaile/forge-settings/ai-sdk'
+const { model } = await resolveRegistryLanguageModel('assistant-default/some-model', { projectDir, env, policy })
+```
+
+Role-to-selector mapping belongs to the host's settings document; there is no global model locator. Failures are `ModelResolutionError` with a `code`; messages never carry a secret.
+
+## Providers panel
+
+```ts
+// nuxt.config.ts: '@nuxt/ui' BEFORE this module
+modules: ['@nuxt/ui', '@skaile/forge-settings/nuxt']
+```
+
+```vue
+<ForgeProvidersPanel
+  providers-url="/api/providers" providers-write-url="/api/providers"
+  environment-url="/api/settings/env" layer="instance" :read-only="!canAdmin"
+  @changed="reload" />
+```
+
+The panel (`PUT|DELETE <writeUrl>/:id`, `GET <writeUrl>/detected`, `GET <providersUrl>`, `GET|PUT <environmentUrl>`) reads and writes only the routes you give it. The host serves them with the `/server` operations and decides who may call them. `SettingsModalScope` documents the same URL fields for hosts that compose a larger modal.
+
+## Development
+
+```
+bun install
+bun run prepare     # generate module types
+bun run typecheck
+bun run test
+bun run build
+```
+
+Releases: push a `v*` tag equal to the `package.json` version; `publish.yml` publishes with npm trusted publishing.

package/dist/module.d.mts

@@ -0,0 +1,17 @@
+import { NuxtModule } from '@nuxt/schema';
+
+/** `@skaile/forge-settings/nuxt` has no options: it registers one component. */
+type ForgeSettingsOptions = Record<string, never>;
+/**
+ * Nuxt module registering `<ForgeProvidersPanel>`, the narrow provider
+ * settings surface (registry editor, detected-in-environment adds, key entry).
+ *
+ * It installs no server route, no auto-import and no authorization: the host
+ * serves the panel's routes with `@skaile/forge-settings/server` and decides who
+ * may call them. Requires `@nuxt/ui` (^4.11) registered BEFORE this module in
+ * `modules`; the panel renders Nuxt UI primitives.
+ */
+declare const forgeSettingsModule: NuxtModule<ForgeSettingsOptions>;
+
+export { forgeSettingsModule as default };
+export type { ForgeSettingsOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@skaile/forge-settings",
+  "configKey": "forgeSettings",
+  "version": "1.0.1",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,23 @@
+import { defineNuxtModule, createResolver, hasNuxtModule, addComponent } from '@nuxt/kit';
+
+const forgeSettingsModule = defineNuxtModule({
+  meta: {
+    name: "@skaile/forge-settings",
+    configKey: "forgeSettings"
+  },
+  setup(_options, nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+    if (!nuxt.options._prepare && !hasNuxtModule("@nuxt/ui", nuxt)) {
+      throw new Error(
+        "[@skaile/forge-settings] requires the '@nuxt/ui' module, but it was not registered before '@skaile/forge-settings/nuxt'. Add '@nuxt/ui' to the `modules` array in your nuxt.config *before* '@skaile/forge-settings/nuxt' (and install it as a dependency): <ForgeProvidersPanel> renders Nuxt UI primitives (<UModal>, <UButton>, <UInput>, \u2026)."
+      );
+    }
+    addComponent({
+      name: "ForgeProvidersPanel",
+      filePath: resolve("./runtime/components/ForgeProvidersPanel.vue"),
+      global: false
+    });
+  }
+});
+
+export { forgeSettingsModule as default };

package/dist/runtime/ai-sdk/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `@skaile/forge-settings/ai-sdk` — the AI SDK language model of a registry
+ * selector, resolved by `@skaile/workspaces/ai-sdk` and gated by the host's
+ * credential policy.
+ *
+ * Workspaces owns endpoint, header and credential wiring for every surface;
+ * this module only decides *whether* an entry may be resolved and against
+ * *which* environment. It is not a service locator: the caller passes the
+ * selector (role-to-selector mapping belongs to the host's settings document)
+ * and the environment explicitly.
+ *
+ * Provider SDKs (`@ai-sdk/anthropic`, `@ai-sdk/openai`,
+ * `@ai-sdk/openai-compatible`) are optional peers of Workspaces: install the
+ * one the selected surface needs.
+ */
+import { type ResolvedLanguageModel } from "@skaile/workspaces/ai-sdk";
+import type { CredentialPolicy } from "../server/credential-policy.js";
+export { ModelResolutionError } from "../model/errors.js";
+export type { ModelResolutionCode } from "../model/errors.js";
+export type { ResolvedLanguageModel };
+/** Options for {@link resolveRegistryLanguageModel}. */
+export interface ResolveRegistryLanguageModelOptions {
+    /** Workspace whose `.skaile/providers.yml` is the workspace layer. */
+    projectDir: string;
+    /**
+     * The environment `env:` credential references are read from. Required, so a
+     * host never reads the ambient process by accident.
+     */
+    env: Record<string, string | undefined>;
+    /** Role → model-ref map `@role` selectors resolve against. */
+    roles?: Record<string, string>;
+    /**
+     * Which credential references may be resolved. The selected entry is checked
+     * before anything is read; a refused one is a `policy_refused` failure.
+     */
+    policy?: CredentialPolicy;
+}
+/**
+ * The AI SDK model for `selector` (`<providerId>/<modelId>`, a bare model id or
+ * `@role`), resolved by Workspaces against the registry on disk.
+ *
+ * @throws {ModelResolutionError} `registry_invalid` · `unknown_selector` ·
+ *   `policy_refused` · `unresolved` (credential, endpoint or provider SDK; the
+ *   message is fixed and never carries Workspaces' text, which stays on `cause`).
+ */
+export declare function resolveRegistryLanguageModel(selector: string, options: ResolveRegistryLanguageModelOptions): Promise<ResolvedLanguageModel>;

package/dist/runtime/ai-sdk/index.js

@@ -0,0 +1,31 @@
+import { parseModelRef } from "@skaile/workspaces/core";
+import { resolveLanguageModel } from "@skaile/workspaces/ai-sdk";
+import { loadMergedProviderRegistry } from "@skaile/workspaces/sdk/bridge";
+import { ModelResolutionError, assertEntryAllowed } from "../model/errors.js";
+export { ModelResolutionError } from "../model/errors.js";
+export async function resolveRegistryLanguageModel(selector, options) {
+  const { merged, diagnostics } = loadMergedProviderRegistry({ projectDir: options.projectDir });
+  const errors = diagnostics.filter((d) => d.severity === "error").map((d) => d.path ? `${d.path}: ${d.message}` : d.message);
+  if (errors.length > 0) {
+    throw new ModelResolutionError("registry_invalid", `providers registry: ${errors.join("; ")}`);
+  }
+  const ref = parseModelRef(selector, merged, options.roles);
+  if (!ref) {
+    throw new ModelResolutionError("unknown_selector", `no provider serves '${selector}'`);
+  }
+  const entry = merged.providers[ref.providerId];
+  if (entry) assertEntryAllowed(entry, ref.providerId, options.policy);
+  try {
+    return await resolveLanguageModel(selector, {
+      projectDir: options.projectDir,
+      env: options.env,
+      ...options.roles ? { roles: options.roles } : {}
+    });
+  } catch (cause) {
+    throw new ModelResolutionError(
+      "unresolved",
+      `provider '${ref.providerId}': credential, endpoint or provider SDK could not be resolved`,
+      { providerId: ref.providerId, cause }
+    );
+  }
+}

package/dist/runtime/components/ForgeProvidersPanel.d.vue.ts

@@ -0,0 +1,21 @@
+import { type ProvidersPanelLayer } from "../vue/useProvidersPanel.js";
+type __VLS_Props = {
+    /** `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: hand-entered keys. Omitted, key entry is hidden. */
+    environmentUrl?: string;
+    /** Edit/Delete are offered only for entries this layer defines. */
+    layer: ProvidersPanelLayer;
+    /** Disables add, edit and delete. */
+    readOnly?: boolean;
+};
+declare const _default: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    changed: () => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onChanged?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;