@fonoster/common 0.27.0 → 0.30.0

package/dist/registry/Registry.d.ts

@@ -0,0 +1,79 @@
+import { Capability, CatalogEntry, ItemKind, ModelEntry, ProviderEntry, RegistryStore, Usage, UsageSource, VoiceEntry } from "./types";
+/** Adapters that ship with this version (add-provider-registry, P2). */
+export declare const BUILT_IN_ADAPTERS: string[];
+export declare class RegistryError extends Error {
+}
+export type ImpactLine = {
+    mark: "✓" | "✗" | "~";
+    text: string;
+    count: number;
+};
+export type Impact = {
+    lines: ImpactLine[];
+    mappable: Usage[];
+    unmappable: Usage[];
+};
+export type RegistryOptions = {
+    store: RegistryStore;
+    usages?: UsageSource;
+    actor?: string;
+    /** Allows the fake adapter (test deployments only; conformance "Implementations ship fake adapters"). */
+    testMode?: boolean;
+    now?: () => Date;
+    /** The command line that made the change, stored in every audit entry (spec "Every write is audited"). */
+    commandLine?: string;
+};
+/** The registry operations behind the `fonoster-registry` utility. */
+export declare class Registry {
+    private readonly options;
+    private readonly usages;
+    constructor(options: RegistryOptions);
+    private get store();
+    private audit;
+    /** Rejects anything that looks like a credential (the catalog never holds a secret). */
+    private assertNoSecrets;
+    private assertNew;
+    private require;
+    addProvider(input: {
+        id: string;
+        adapter: string;
+        capabilities: Capability[];
+        credentialRef: string;
+    } & Record<string, unknown>): ProviderEntry;
+    addModel(input: {
+        id: string;
+        type: Capability;
+        features?: string[];
+        languages?: string[];
+        settings?: string[];
+    } & Record<string, unknown>): ModelEntry;
+    addVoice(input: {
+        id: string;
+        models: string[];
+        language?: string;
+        gender?: string;
+        ownerWorkspace?: string;
+    } & Record<string, unknown>): VoiceEntry;
+    private requireProviderFor;
+    /** What moving the usages of `id` to `replacement` would do (shared by deprecate and retire). */
+    impact(id: string, replacement: string, voiceMap?: Record<string, string>): Impact;
+    deprecate(kind: ItemKind, id: string, replacement: string, retireOn: string): Impact;
+    retire(kind: ItemKind, id: string, voiceMap?: Record<string, string>): Impact;
+    /** What the gateway does with an id at session start: retired ids resolve to their replacement. */
+    resolve(id: string): {
+        id: string;
+        event?: "provider.deprecated_used" | "provider.retired_used";
+        replacement?: string;
+    };
+    show(id: string): CatalogEntry;
+    list(kind?: ItemKind): CatalogEntry[];
+    /** Voices the dashboard offers for a model: active or deprecated voices that work on it. */
+    voicesFor(modelId: string): VoiceEntry[];
+    usage(id: string): Usage[];
+    history(id?: string): import("./types").AuditEntry[];
+    /** The whole catalog, sorted and without secrets, as YAML. Byte-identical for equal catalogs. */
+    export(): string;
+    plan(file: string): string[];
+    apply(file: string): string[];
+    private diff;
+}

package/dist/registry/Registry.js

@@ -0,0 +1,418 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Registry = exports.RegistryError = exports.BUILT_IN_ADAPTERS = void 0;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const yaml_1 = require("yaml");
+const features_1 = require("./features");
+/** Adapters that ship with this version (add-provider-registry, P2). */
+exports.BUILT_IN_ADAPTERS = [
+    "deepgram",
+    "elevenlabs",
+    "google",
+    "azure",
+    "openai",
+    "anthropic",
+    "groq",
+    "ollama",
+    "fake"
+];
+// provider/name; the name may have its own slashes, as hosted models do (groq/openai/gpt-oss-120b).
+const CATALOG_ID = /^[a-z0-9-]+(\/[A-Za-z0-9._-]+)+$/;
+const REF = /^[a-z0-9][a-z0-9-]*$/;
+const SECRET_KEY = /(api[-_]?key|secret|token|password|private[-_]?key)/i;
+const SECRET_VALUE = /^(sk-|sk_|xox[abp]-|AKIA|AIza|-----BEGIN)/;
+class RegistryError extends Error {
+}
+exports.RegistryError = RegistryError;
+const noUsages = {
+    find: () => [],
+    rewrite: () => true,
+    notify: () => undefined
+};
+/** The registry operations behind the `fonoster-registry` utility. */
+class Registry {
+    constructor(options) {
+        var _a;
+        this.options = options;
+        this.usages = (_a = options.usages) !== null && _a !== void 0 ? _a : noUsages;
+    }
+    get store() {
+        return this.options.store;
+    }
+    audit(action, target, details) {
+        var _a, _b, _c, _d, _e;
+        this.store.audit({
+            at: ((_c = (_b = (_a = this.options).now) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : new Date()).toISOString(),
+            actor: (_e = (_d = this.options.actor) !== null && _d !== void 0 ? _d : process.env.USER) !== null && _e !== void 0 ? _e : "operator",
+            action,
+            target,
+            details: this.options.commandLine
+                ? Object.assign({ command: this.options.commandLine }, details) : details
+        });
+    }
+    /** Rejects anything that looks like a credential (the catalog never holds a secret). */
+    assertNoSecrets(input) {
+        for (const [k, v] of Object.entries(input)) {
+            if (SECRET_KEY.test(k) ||
+                (typeof v === "string" && SECRET_VALUE.test(v))) {
+                throw new RegistryError(`secrets cannot be stored in the catalog (${k}); store keys as workspace Secrets or platform credentials and pass --credential-ref`);
+            }
+        }
+    }
+    assertNew(id) {
+        if (!CATALOG_ID.test(id) && !REF.test(id))
+            throw new RegistryError(`invalid catalog id ${id}`);
+        const existing = this.store.get(id);
+        if (existing)
+            throw new RegistryError(`catalog id ${id} already exists (state: ${existing.state})`);
+    }
+    require(id, kind) {
+        const e = this.store.get(id);
+        if (!e || e.kind !== kind)
+            throw new RegistryError(`no ${kind} ${id}`);
+        return e;
+    }
+    // ---- add --------------------------------------------------------------------------
+    addProvider(input) {
+        this.assertNoSecrets(input);
+        this.assertNew(input.id);
+        if (!exports.BUILT_IN_ADAPTERS.includes(input.adapter))
+            throw new RegistryError(`unknown adapter: ${input.adapter}`);
+        if (input.adapter === "fake" && !this.options.testMode) {
+            throw new RegistryError("the fake adapter is only available in test mode");
+        }
+        if (!REF.test(input.credentialRef))
+            throw new RegistryError("credentialRef must be a name such as deepgram-default");
+        const entry = {
+            kind: "provider",
+            id: input.id,
+            adapter: input.adapter,
+            capabilities: input.capabilities,
+            credentialRef: input.credentialRef,
+            state: "active"
+        };
+        this.store.put(entry);
+        this.audit("add-provider", entry.id, { entry, before: null, after: entry });
+        return entry;
+    }
+    addModel(input) {
+        var _a, _b, _c, _d;
+        this.assertNoSecrets(input);
+        this.assertNew(input.id);
+        this.requireProviderFor(input.id, input.type);
+        const unknown = (0, features_1.unknownFeatures)(input.type, (_a = input.features) !== null && _a !== void 0 ? _a : []);
+        if (unknown.length)
+            throw new RegistryError(`unknown ${input.type} features: ${unknown.join(", ")}`);
+        const entry = {
+            kind: "model",
+            id: input.id,
+            type: input.type,
+            features: (_b = input.features) !== null && _b !== void 0 ? _b : [],
+            languages: (_c = input.languages) !== null && _c !== void 0 ? _c : [],
+            settings: (_d = input.settings) !== null && _d !== void 0 ? _d : [],
+            state: "active"
+        };
+        this.store.put(entry);
+        this.audit("add-model", entry.id, { entry, before: null, after: entry });
+        return entry;
+    }
+    addVoice(input) {
+        this.assertNoSecrets(input);
+        this.assertNew(input.id);
+        for (const m of input.models) {
+            const model = this.require(m, "model");
+            if (model.type !== "tts")
+                throw new RegistryError(`${m} is not a tts model`);
+        }
+        const entry = {
+            kind: "voice",
+            id: input.id,
+            models: input.models,
+            language: input.language,
+            gender: input.gender,
+            ownerWorkspace: input.ownerWorkspace,
+            state: "active"
+        };
+        this.store.put(entry);
+        this.audit("add-voice", entry.id, { entry, before: null, after: entry });
+        return entry;
+    }
+    requireProviderFor(id, type) {
+        const provider = this.store.get(id.split("/")[0]);
+        if (!provider || provider.kind !== "provider")
+            throw new RegistryError(`no provider ${id.split("/")[0]}`);
+        if (!provider.capabilities.includes(type))
+            throw new RegistryError(`provider ${provider.id} has no ${type} capability`);
+    }
+    // ---- impact, deprecate, retire ----------------------------------------------------
+    /** What moving the usages of `id` to `replacement` would do (shared by deprecate and retire). */
+    impact(id, replacement, voiceMap = {}) {
+        var _a;
+        const item = this.store.get(id);
+        const repl = this.store.get(replacement);
+        if (!item || !repl)
+            throw new RegistryError(`unknown ${!item ? id : replacement}`);
+        const usages = this.usages.find(id);
+        const mappable = [];
+        const unmappable = [];
+        const counts = new Map();
+        const bump = (key, line) => {
+            var _a;
+            const l = (_a = counts.get(key)) !== null && _a !== void 0 ? _a : Object.assign(Object.assign({}, line), { count: 0 });
+            l.count++;
+            counts.set(key, l);
+        };
+        for (const u of usages) {
+            let ok = true;
+            if (item.kind === "model" && repl.kind === "model") {
+                const missing = u.requires.filter((f) => features_1.FEATURES[repl.type][f] === "hard" && !repl.features.includes(f));
+                if (missing.length) {
+                    ok = false;
+                    bump(`req:${missing}`, {
+                        mark: "✗",
+                        text: `requires ${missing.join(", ")}, which ${replacement} lacks`
+                    });
+                }
+                if (u.voice) {
+                    const voice = this.store.get(u.voice);
+                    const name = (_a = u.voice.split("/")[1]) !== null && _a !== void 0 ? _a : u.voice;
+                    if (voice === null || voice === void 0 ? void 0 : voice.models.includes(replacement))
+                        bump(`v:${u.voice}`, {
+                            mark: "✓",
+                            text: `voice ${name} works on replacement`
+                        });
+                    else if (voiceMap[name])
+                        bump(`vm:${u.voice}`, {
+                            mark: "✓",
+                            text: `voice ${name} → ${voiceMap[name]}`
+                        });
+                    else {
+                        ok = false;
+                        const owned = (voice === null || voice === void 0 ? void 0 : voice.ownerWorkspace)
+                            ? ` (workspace ${voice.ownerWorkspace}'s own voice)`
+                            : "";
+                        bump(`vx:${u.voice}`, {
+                            mark: "✗",
+                            text: `voice ${name}${owned} only exists on ${id.split("/")[1]} → needs --voice-map ${name}=<voice>`
+                        });
+                    }
+                }
+                for (const s of u.settings.filter((s) => !repl.settings.includes(s))) {
+                    bump(`s:${s}`, {
+                        mark: "~",
+                        text: `setting "${s}" not supported, will be dropped (soft)`
+                    });
+                }
+            }
+            else if (item.kind === "voice" && repl.kind === "voice") {
+                if (u.model && !repl.models.includes(u.model)) {
+                    ok = false;
+                    bump(`m:${u.model}`, {
+                        mark: "✗",
+                        text: `${replacement} does not work on ${u.model}`
+                    });
+                }
+                else
+                    bump("ok", { mark: "✓", text: `works on the same model` });
+            }
+            else
+                bump("ok", { mark: "✓", text: "config moves to the replacement" });
+            (ok ? mappable : unmappable).push(u);
+        }
+        return { lines: [...counts.values()], mappable, unmappable };
+    }
+    deprecate(kind, id, replacement, retireOn) {
+        const item = this.require(id, kind);
+        const repl = this.store.get(replacement);
+        if (!repl ||
+            repl.kind !== kind ||
+            repl.state !== "active" ||
+            (kind === "model" &&
+                repl.type !== item.type)) {
+            throw new RegistryError(`replacement must be an active ${kind}`);
+        }
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(retireOn))
+            throw new RegistryError("--retire-on must be a date (YYYY-MM-DD)");
+        const report = this.impact(id, replacement);
+        const after = Object.assign(Object.assign({}, item), { state: "deprecated", replacement,
+            retireOn });
+        this.store.put(after);
+        this.audit(`deprecate-${kind}`, id, {
+            replacement,
+            retireOn,
+            before: item,
+            after
+        });
+        const workspaces = new Set(this.usages.find(id).map((u) => u.workspace));
+        // One provider.deprecated notice per workspace (sent as a workspace webhook by the apiserver).
+        for (const w of workspaces)
+            this.usages.notify(w, {
+                type: "provider.deprecated",
+                id,
+                replacement,
+                retireOn
+            });
+        return report;
+    }
+    retire(kind, id, voiceMap = {}) {
+        var _a;
+        const item = this.require(id, kind);
+        if (!item.replacement)
+            throw new RegistryError(`${id} must be deprecated with a replacement before it is retired`);
+        const report = this.impact(id, item.replacement, voiceMap);
+        const repl = this.store.get(item.replacement);
+        for (const u of report.mappable) {
+            const name = (_a = u.voice) === null || _a === void 0 ? void 0 : _a.split("/")[1];
+            const voice = kind === "voice"
+                ? item.replacement
+                : name && voiceMap[name]
+                    ? `${u.voice.split("/")[0]}/${voiceMap[name]}`
+                    : undefined;
+            const dropSettings = repl.kind === "model"
+                ? u.settings.filter((s) => !repl.settings.includes(s))
+                : [];
+            const change = {
+                model: kind === "model" ? item.replacement : undefined,
+                voice,
+                dropSettings
+            };
+            if (this.usages.rewrite(u, change))
+                this.audit("rewrite-config", id, {
+                    workspace: u.workspace,
+                    config: u.config,
+                    change
+                });
+        }
+        for (const w of new Set([...report.mappable, ...report.unmappable].map((u) => u.workspace))) {
+            this.usages.notify(w, {
+                type: "provider.retired",
+                id,
+                replacement: item.replacement
+            });
+        }
+        const after = Object.assign(Object.assign({}, item), { state: "retired" });
+        this.store.put(after);
+        this.audit(`retire-${kind}`, id, {
+            before: item,
+            after,
+            replacement: item.replacement,
+            unmappable: report.unmappable.length
+        });
+        return report;
+    }
+    /** What the gateway does with an id at session start: retired ids resolve to their replacement. */
+    resolve(id) {
+        const e = this.store.get(id);
+        if (!e)
+            return { id };
+        if (e.state === "retired" && e.replacement)
+            return Object.assign(Object.assign({}, this.resolve(e.replacement)), { event: "provider.retired_used", replacement: e.replacement });
+        if (e.state === "deprecated")
+            return {
+                id,
+                event: "provider.deprecated_used",
+                replacement: e.replacement
+            };
+        return { id };
+    }
+    // ---- read ---------------------------------------------------------------------------
+    show(id) {
+        const e = this.store.get(id);
+        if (!e)
+            throw new RegistryError(`no catalog entry ${id}`);
+        return e;
+    }
+    list(kind) {
+        return this.store.all().filter((e) => !kind || e.kind === kind);
+    }
+    /** Voices the dashboard offers for a model: active or deprecated voices that work on it. */
+    voicesFor(modelId) {
+        return this.store
+            .all()
+            .filter((e) => e.kind === "voice" &&
+            e.state !== "retired" &&
+            e.models.includes(modelId));
+    }
+    usage(id) {
+        return this.usages.find(id);
+    }
+    history(id) {
+        return this.store.history(id);
+    }
+    // ---- export, plan, apply ----------------------------------------------------------
+    /** The whole catalog, sorted and without secrets, as YAML. Byte-identical for equal catalogs. */
+    export() {
+        return (0, yaml_1.stringify)({
+            format: "fonoster.catalog.v1",
+            entries: this.store.all().map(canonical)
+        });
+    }
+    plan(file) {
+        return this.diff(file).map((d) => d.line);
+    }
+    apply(file) {
+        var _a;
+        const changes = this.diff(file);
+        for (const c of changes) {
+            const before = (_a = this.store.get(c.entry.id)) !== null && _a !== void 0 ? _a : null;
+            this.store.put(c.entry);
+            this.audit("apply", c.entry.id, {
+                change: c.line,
+                before,
+                after: c.entry
+            });
+        }
+        return changes.length ? changes.map((c) => c.line) : ["no changes"];
+    }
+    diff(file) {
+        const target = (0, yaml_1.parse)(file).entries;
+        const out = [];
+        for (const want of target) {
+            this.assertNoSecrets(want);
+            const have = this.store.get(want.id);
+            if (!have)
+                out.push({ line: `+ add ${want.kind} ${want.id}`, entry: want });
+            else if (JSON.stringify(canonical(have)) !== JSON.stringify(canonical(want))) {
+                const verb = have.state !== want.state
+                    ? want.state === "deprecated"
+                        ? "deprecate"
+                        : want.state === "retired"
+                            ? "retire"
+                            : "update"
+                    : "update";
+                const to = want.replacement && have.state !== want.state
+                    ? ` → ${want.replacement}`
+                    : "";
+                out.push({
+                    line: `~ ${verb} ${want.kind} ${want.id}${to}`,
+                    entry: want
+                });
+            }
+        }
+        return out;
+    }
+}
+exports.Registry = Registry;
+/** Keys in a fixed order and no undefined values, so exports compare byte for byte. */
+function canonical(e) {
+    return Object.fromEntries(Object.entries(e)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => a.localeCompare(b)));
+}

package/dist/registry/cli.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { PrismaLike } from "./prisma";
+/** Runs one command against the JSON file store (synchronous; the default store). */
+export declare function run(argv: string[], out?: (s: string) => void): number;
+export declare const usesDatabase: (argv: string[]) => boolean;
+/**
+ * Runs one command against the control-plane database: loads the catalog and usages, runs the
+ * command, then waits for every write, records skipped rewrites in the audit log and sends due
+ * `provider.deprecated` webhooks once (retries are adopted by a running dispatcher).
+ */
+export declare function runWithDatabase(argv: string[], out?: (s: string) => void, deps?: {
+    prisma?: PrismaLike;
+    actor?: string;
+}): Promise<number>;
+/**
+ * Runs one command with telemetry (add-platform 2.5): a `registry.command` span and a
+ * `fonoster.registry.commands` count by command and outcome, flushed before returning. Off unless
+ * an OTLP endpoint is set.
+ */
+export declare function runTraced(argv: string[], env?: Record<string, string | undefined>): Promise<number>;