tinywebui 0.1.4 → 0.1.5

package/src/config/data_dir.js

@@ -0,0 +1,24 @@
+/*
+ * Where an installed TinyWebUI (npx, or npm install -g) keeps its files when
+ * nothing says otherwise: one folder per user, the platform's usual place for
+ * application data, rather than whichever folder the command ran in. Config,
+ * keys, database and embedding models all sit there, beside the config, so
+ * one person has one of each and knows where to back it up or delete it.
+ * A clone and the Docker image keep using the working directory and their
+ * explicit paths.
+ */
+import { homedir } from 'node:os';
+import { isAbsolute, join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The per-user data folder on `platform`. */
+export function userDataDir(env = process.env, platform = process.platform, home = homedir()) {
+    if (platform === 'darwin')
+        return join(home, 'Library', 'Application Support', 'TinyWebUI');
+    if (platform === 'win32')
+        return join(env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'TinyWebUI');
+    // XDG: a relative value is invalid and must be ignored.
+    const xdg = env.XDG_DATA_HOME && isAbsolute(env.XDG_DATA_HOME) ? env.XDG_DATA_HOME : join(home, '.local', 'share');
+    return join(xdg, 'tinywebui');
+}
+/** Whether `moduleUrl` runs from an installed package rather than a checkout. */
+export const isInstalled = (moduleUrl) => fileURLToPath(moduleUrl).split(sep).includes('node_modules');

package/src/config/models.js

@@ -1,153 +1,229 @@
-/**
- * The model catalog: which models people may pick, what they are called, and
- * how each one is prompted and sampled. Declared in the config file:
- *
- *   models: [
- *     { id: 'fast', label: 'Quick', model: 'deepseek/deepseek-v4.1-flash',
- *       description: 'Everyday questions', temperature: 0.3 },
- *     { id: 'deep', label: 'Thorough', model: 'anthropic/claude-sonnet-5',
- *       systemPrompt: '...', maxToolRounds: 20 }
- *   ]
- *
- * An empty catalog (the default) changes nothing: any model id goes. A
- * non-empty one is closed: only its entries can be picked, the configured
- * `model` and every role's `models` list name entries by `id`, and people see
- * `label`, never the provider's id. `enabled: false` parks an entry: it keeps
- * its settings but cannot be picked or run until switched back on. Pure, like
- * policy.js.
- */
-
 /** Per-model settings that replace the global value for that model's turns. */
 export const MODEL_OVERRIDES = ['systemPrompt', 'temperature', 'maxTokens', 'maxToolRounds', 'cacheMode', 'cacheTtl', 'extraBody', 'reasoningReplay'];
-
 /** Values of `reasoningReplay`; see reasoningReplay in harness/provider.js. */
 export const REASONING_REPLAY = ['auto', 'omit', 'reasoning_content', 'reasoning_details'];
-
 /** What a model can do; the page uses these (e.g. `vision` gates image upload). */
 export const MODEL_TAGS = ['vision', 'reasoning', 'tools'];
-
 const ENTRY_KEYS = new Set(['id', 'model', 'label', 'description', 'enabled', 'connector', 'tags', ...MODEL_OVERRIDES]);
-
-/** Named endpoints: { id, label?, baseUrl, apiKey? }. The top-level baseUrl/apiKey stay the implicit default. */
+/**
+ * The file keeps each model with the endpoint that serves it: top-level
+ * `models` run on the default baseUrl/apiKey, `connectors[i].models` on that
+ * connector, and every entry carries its own prompt, sampling and caching.
+ * At runtime the catalog is one flat list whose entries name their connector,
+ * so nothing past loading knows about the nesting. The older flat file shape
+ * (entries with `connector: <id>`) loads unchanged.
+ */
+// Raw input: the file's contents, before validation.
+export function flattenCatalog(cfg) {
+    if (!Array.isArray(cfg.connectors) || !Array.isArray(cfg.models ?? []))
+        return {};
+    const nested = [];
+    const connectors = cfg.connectors.map((c) => {
+        if (!c || typeof c !== 'object' || !Array.isArray(c.models))
+            return c;
+        const { models, ...rest } = c;
+        for (const m of models)
+            nested.push(m && typeof m === 'object' && !Array.isArray(m) ? { ...m, connector: c.id } : m);
+        return rest;
+    });
+    return { connectors, models: [...(cfg.models ?? []), ...nested] };
+}
+/** The flat runtime catalog back in the file's nested shape. */
+export function nestCatalog(cfg) {
+    const out = {};
+    const connectors = Array.isArray(cfg.connectors) ? cfg.connectors : [];
+    const models = Array.isArray(cfg.models) ? cfg.models : [];
+    const ids = new Set(connectors.map((c) => c?.id));
+    // An entry naming a connector that is not listed stays flat, so validation
+    // still reports it instead of the entry silently moving endpoints.
+    if (cfg.models !== undefined)
+        out.models = models.filter((m) => !m?.connector || !ids.has(m.connector));
+    if (cfg.connectors !== undefined) {
+        out.connectors = connectors.map((c) => {
+            const mine = models.filter((m) => m?.connector && m.connector === c?.id).map(({ connector, ...m }) => m);
+            return mine.length ? { ...c, models: mine } : c;
+        });
+    }
+    return out;
+}
+/**
+ * Whether turns on `key` have somewhere to go: an entry's connector, else the
+ * top-level endpoint if it has a URL. A key is optional either way: a local
+ * server may need none.
+ */
+export function hasEndpoint(cfg, key) {
+    const e = findEntry(cfg, key ?? cfg.model);
+    return e?.connector && findConnector(cfg, e.connector) ? true : Boolean(cfg.baseUrl);
+}
+/**
+ * Named endpoints: { id, label?, baseUrl, apiKey? }. The top-level
+ * baseUrl/apiKey are the endpoint of a model that names none, for a
+ * deployment set up in code or the environment; unset by default.
+ */
 export const connectors = (cfg) => (Array.isArray(cfg.connectors) ? cfg.connectors : []);
 export const findConnector = (cfg, id) => connectors(cfg).find((c) => c.id === id) || null;
-
 export const catalog = (cfg) => (Array.isArray(cfg.models) ? cfg.models : []);
 // Closed whenever entries are listed, even if all are disabled: parking every
 // model must not reopen the picker to the provider's whole list.
 export const isClosed = (cfg) => catalog(cfg).length > 0;
 export const enabledEntries = (cfg) => catalog(cfg).filter((e) => e.enabled !== false);
-
+/** The default model: `model` as set, or unset with a catalog, its first enabled entry. */
+export const defaultModel = (cfg) => cfg.model || enabledEntries(cfg)[0]?.id || '';
 /** The enabled entry `key` names: by id, or by its provider model id (the default `model` may be either). */
 export function findEntry(cfg, key) {
-  const list = enabledEntries(cfg);
-  return list.find((e) => e.id === key) || list.find((e) => (e.model || e.id) === key) || null;
+    const list = enabledEntries(cfg);
+    return list.find((e) => e.id === key) || list.find((e) => (e.model || e.id) === key) || null;
 }
-
 /** What people call a model: its label in the catalog, else the id itself. */
 export function labelFor(cfg, key) {
-  const e = findEntry(cfg, key);
-  return e ? e.label || e.id : key;
+    const e = findEntry(cfg, key);
+    return e ? e.label || e.id : key;
 }
-
 /** What the picker lists for one entry. Prompts and knobs stay server-side. */
 export const publicEntry = (e) => ({ id: e.id, name: e.label || e.id, description: e.description || null, tags: e.tags || [] });
-
 /**
  * The config one turn runs with: the entry's overrides over the global
  * settings and its provider id as `model`. extraBody merges, so an entry can
  * add a reasoning knob without restating the gateway's routing.
  */
 export function effectiveConfig(cfg, key) {
-  const e = findEntry(cfg, key ?? cfg.model);
-  if (!e) return key && key !== cfg.model ? { ...cfg, model: key } : cfg;
-  const out = { ...cfg };
-  for (const k of MODEL_OVERRIDES) if (e[k] !== undefined) out[k] = e[k];
-  out.extraBody = { ...(cfg.extraBody || {}), ...(e.extraBody || {}) };
-  // `provider` merges one level deeper: a global data policy (zdr,
-  // data_collection) must survive an entry that only pins its routing.
-  if (cfg.extraBody?.provider || e.extraBody?.provider) {
-    out.extraBody.provider = { ...(cfg.extraBody?.provider || {}), ...(e.extraBody?.provider || {}) };
-  }
-  out.model = e.model || e.id;
-  // The entry's endpoint replaces the global one; provider.js only ever reads
-  // cfg.baseUrl and cfg.apiKey, so nothing downstream knows about connectors.
-  const conn = e.connector ? findConnector(cfg, e.connector) : null;
-  if (conn) {
-    out.baseUrl = String(conn.baseUrl).replace(/\/+$/, '');
-    out.apiKey = conn.apiKey || '';
-  }
-  return out;
+    const e = findEntry(cfg, key ?? cfg.model);
+    if (!e)
+        return key && key !== cfg.model ? { ...cfg, model: key } : cfg;
+    const out = { ...cfg };
+    for (const k of MODEL_OVERRIDES)
+        if (e[k] !== undefined)
+            out[k] = e[k];
+    out.extraBody = { ...(cfg.extraBody || {}), ...(e.extraBody || {}) };
+    // `provider` merges one level deeper: a global data policy (zdr,
+    // data_collection) must survive an entry that only pins its routing.
+    if (cfg.extraBody?.provider || e.extraBody?.provider) {
+        out.extraBody.provider = { ...(cfg.extraBody?.provider || {}), ...(e.extraBody?.provider || {}) };
+    }
+    out.model = e.model || e.id;
+    // The entry's endpoint replaces the global one; provider.js only ever reads
+    // cfg.baseUrl and cfg.apiKey, so nothing downstream knows about connectors.
+    const conn = e.connector ? findConnector(cfg, e.connector) : null;
+    if (conn) {
+        out.baseUrl = String(conn.baseUrl).replace(/\/+$/, '');
+        out.apiKey = conn.apiKey || '';
+    }
+    return out;
 }
-
 /** Every problem with the connector list. */
 export function connectorProblems(cfg) {
-  const list = cfg.connectors;
-  if (list === undefined) return [];
-  if (!Array.isArray(list)) return ['connectors must be a list of { id, baseUrl, apiKey?, label? } entries'];
-  const out = [];
-  const ids = new Set();
-  list.forEach((c, i) => {
-    const at = `connectors[${i}]`;
-    if (!c || typeof c !== 'object' || Array.isArray(c)) { out.push(`${at} must be an object`); return; }
-    if (typeof c.id !== 'string' || !c.id.trim()) { out.push(`${at}.id must be a non-empty string`); return; }
-    if (ids.has(c.id)) out.push(`${at}.id "${c.id}" is listed twice`);
-    ids.add(c.id);
-    for (const k of Object.keys(c)) if (!['id', 'label', 'baseUrl', 'apiKey'].includes(k)) out.push(`${at}.${k} is not a known setting (known: id, label, baseUrl, apiKey)`);
-    for (const k of ['label', 'apiKey']) if (c[k] !== undefined && typeof c[k] !== 'string') out.push(`${at}.${k} must be a string`);
-    try {
-      if (!/^https?:$/.test(new URL(c.baseUrl).protocol)) throw new Error('scheme');
-    } catch { out.push(`${at}.baseUrl must be an http(s) URL`); }
-  });
-  for (const [i, e] of (Array.isArray(cfg.models) ? cfg.models : []).entries()) {
-    if (e?.connector !== undefined && !ids.has(e.connector)) out.push(`models[${i}].connector "${e.connector}" is not in connectors`);
-  }
-  return out;
+    const list = cfg.connectors;
+    if (list === undefined)
+        return [];
+    if (!Array.isArray(list))
+        return ['connectors must be a list of { id, baseUrl, apiKey?, label?, models? } entries'];
+    const out = [];
+    const ids = new Set();
+    list.forEach((c, i) => {
+        const at = `connectors[${i}]`;
+        if (!c || typeof c !== 'object' || Array.isArray(c)) {
+            out.push(`${at} must be an object`);
+            return;
+        }
+        if (typeof c.id !== 'string' || !c.id.trim()) {
+            out.push(`${at}.id must be a non-empty string`);
+            return;
+        }
+        if (ids.has(c.id))
+            out.push(`${at}.id "${c.id}" is listed twice`);
+        ids.add(c.id);
+        // A nested `models` that is a list was already lifted out by flattenCatalog.
+        if (c.models !== undefined)
+            out.push(`${at}.models must be a list of model entries`);
+        for (const k of Object.keys(c))
+            if (!['id', 'label', 'baseUrl', 'apiKey', 'models'].includes(k))
+                out.push(`${at}.${k} is not a known setting (known: id, label, baseUrl, apiKey, models)`);
+        for (const k of ['label', 'apiKey'])
+            if (c[k] !== undefined && typeof c[k] !== 'string')
+                out.push(`${at}.${k} must be a string`);
+        try {
+            if (!/^https?:$/.test(new URL(c.baseUrl).protocol))
+                throw new Error('scheme');
+        }
+        catch {
+            out.push(`${at}.baseUrl must be an http(s) URL`);
+        }
+    });
+    for (const [i, e] of (Array.isArray(cfg.models) ? cfg.models : []).entries()) {
+        if (e?.connector !== undefined && !ids.has(e.connector))
+            out.push(`models[${i}].connector "${e.connector}" is not in connectors`);
+    }
+    return out;
 }
-
 const NUMERIC = { temperature: 'a number or null', maxTokens: 'a number or null' };
-
 /** Every problem with the catalog and what refers into it. */
 export function modelProblems(cfg) {
-  const list = cfg.models;
-  if (list === undefined) return [];
-  if (!Array.isArray(list)) return ['models must be a list of { id, model?, label?, ... } entries'];
-  const out = [];
-  const ids = new Set();
-  list.forEach((e, i) => {
-    const at = `models[${i}]`;
-    if (!e || typeof e !== 'object' || Array.isArray(e)) { out.push(`${at} must be an object`); return; }
-    if (typeof e.id !== 'string' || !e.id.trim()) { out.push(`${at}.id must be a non-empty string`); return; }
-    if (ids.has(e.id)) out.push(`${at}.id "${e.id}" is listed twice`);
-    ids.add(e.id);
-    for (const k of Object.keys(e)) if (!ENTRY_KEYS.has(k)) out.push(`${at}.${k} is not a known setting (known: ${[...ENTRY_KEYS].join(', ')})`);
-    for (const k of ['model', 'label', 'description', 'systemPrompt']) {
-      if (e[k] !== undefined && typeof e[k] !== 'string') out.push(`${at}.${k} must be a string`);
+    const list = cfg.models;
+    if (list === undefined)
+        return [];
+    if (!Array.isArray(list))
+        return ['models must be a list of { id, model?, label?, ... } entries'];
+    const out = [];
+    const ids = new Set();
+    list.forEach((e, i) => {
+        const at = `models[${i}]`;
+        if (!e || typeof e !== 'object' || Array.isArray(e)) {
+            out.push(`${at} must be an object`);
+            return;
+        }
+        if (typeof e.id !== 'string' || !e.id.trim()) {
+            out.push(`${at}.id must be a non-empty string`);
+            return;
+        }
+        if (ids.has(e.id))
+            out.push(`${at}.id "${e.id}" is listed twice`);
+        ids.add(e.id);
+        for (const k of Object.keys(e))
+            if (!ENTRY_KEYS.has(k))
+                out.push(`${at}.${k} is not a known setting (known: ${[...ENTRY_KEYS].join(', ')})`);
+        for (const k of ['model', 'label', 'description', 'systemPrompt']) {
+            if (e[k] !== undefined && typeof e[k] !== 'string')
+                out.push(`${at}.${k} must be a string`);
+        }
+        for (const k of Object.keys(NUMERIC)) {
+            if (e[k] !== undefined && e[k] !== null && !(typeof e[k] === 'number' && Number.isFinite(e[k])))
+                out.push(`${at}.${k} must be ${NUMERIC[k]}`);
+        }
+        if (e.maxToolRounds !== undefined && !(Number.isInteger(e.maxToolRounds) && e.maxToolRounds >= 0))
+            out.push(`${at}.maxToolRounds must be a whole number >= 0`);
+        if (e.cacheMode !== undefined && !['auto', 'implicit', 'explicit', 'rolling', 'off'].includes(e.cacheMode))
+            out.push(`${at}.cacheMode must be one of auto, implicit, explicit, rolling, off`);
+        if (e.reasoningReplay !== undefined && !REASONING_REPLAY.includes(e.reasoningReplay))
+            out.push(`${at}.reasoningReplay must be one of ${REASONING_REPLAY.join(', ')}`);
+        if (e.cacheTtl !== undefined && !['5m', '1h'].includes(e.cacheTtl))
+            out.push(`${at}.cacheTtl must be 5m or 1h`);
+        if (e.enabled !== undefined && typeof e.enabled !== 'boolean')
+            out.push(`${at}.enabled must be true or false`);
+        if (e.connector !== undefined && typeof e.connector !== 'string')
+            out.push(`${at}.connector must be a connector id`);
+        if (e.tags !== undefined && !(Array.isArray(e.tags) && e.tags.every((t) => MODEL_TAGS.includes(t))))
+            out.push(`${at}.tags must be a list from ${MODEL_TAGS.join(', ')}`);
+        if (e.extraBody !== undefined && !(e.extraBody && typeof e.extraBody === 'object' && !Array.isArray(e.extraBody)))
+            out.push(`${at}.extraBody must be an object`);
+    });
+    if (!list.length || out.length)
+        return out;
+    // A closed catalog: everything that names a model has to name an entry.
+    // Role lists may name disabled entries (they just drop out); the default may not.
+    // An unset `model` is the first enabled entry (see defaultModel).
+    const on = enabledEntries(cfg).map((e) => e.id);
+    if (!on.length)
+        out.push('every entry in models is disabled: enable at least one');
+    else if (cfg.model && !findEntry(cfg, cfg.model)) {
+        const off = list.some((e) => e.id === cfg.model || e.model === cfg.model);
+        out.push(`model "${cfg.model}" ${off ? 'is disabled' : 'is not in the models catalog'}; enabled ids: ${on.join(', ')}`);
     }
-    for (const k of Object.keys(NUMERIC)) {
-      if (e[k] !== undefined && e[k] !== null && !(typeof e[k] === 'number' && Number.isFinite(e[k]))) out.push(`${at}.${k} must be ${NUMERIC[k]}`);
+    for (const [role, spec] of Object.entries(cfg.access?.roles || {})) {
+        if (!Array.isArray(spec?.models))
+            continue;
+        for (const m of spec.models)
+            if (!ids.has(m))
+                out.push(`access.roles.${role}.models: "${m}" is not a models catalog id`);
     }
-    if (e.maxToolRounds !== undefined && !(Number.isInteger(e.maxToolRounds) && e.maxToolRounds >= 0)) out.push(`${at}.maxToolRounds must be a whole number >= 0`);
-    if (e.cacheMode !== undefined && !['auto', 'implicit', 'explicit', 'rolling', 'off'].includes(e.cacheMode)) out.push(`${at}.cacheMode must be one of auto, implicit, explicit, rolling, off`);
-    if (e.reasoningReplay !== undefined && !REASONING_REPLAY.includes(e.reasoningReplay)) out.push(`${at}.reasoningReplay must be one of ${REASONING_REPLAY.join(', ')}`);
-    if (e.cacheTtl !== undefined && !['5m', '1h'].includes(e.cacheTtl)) out.push(`${at}.cacheTtl must be 5m or 1h`);
-    if (e.enabled !== undefined && typeof e.enabled !== 'boolean') out.push(`${at}.enabled must be true or false`);
-    if (e.connector !== undefined && typeof e.connector !== 'string') out.push(`${at}.connector must be a connector id`);
-    if (e.tags !== undefined && !(Array.isArray(e.tags) && e.tags.every((t) => MODEL_TAGS.includes(t)))) out.push(`${at}.tags must be a list from ${MODEL_TAGS.join(', ')}`);
-    if (e.extraBody !== undefined && !(e.extraBody && typeof e.extraBody === 'object' && !Array.isArray(e.extraBody))) out.push(`${at}.extraBody must be an object`);
-  });
-  if (!list.length || out.length) return out;
-  // A closed catalog: everything that names a model has to name an entry.
-  // Role lists may name disabled entries (they just drop out); the default may not.
-  const on = enabledEntries(cfg).map((e) => e.id);
-  if (!on.length) out.push('every entry in models is disabled: enable at least one');
-  else if (!findEntry(cfg, cfg.model)) {
-    const off = list.some((e) => e.id === cfg.model || e.model === cfg.model);
-    out.push(`model "${cfg.model}" ${off ? 'is disabled' : 'is not in the models catalog'}; enabled ids: ${on.join(', ')}`);
-  }
-  for (const [role, spec] of Object.entries(cfg.access?.roles || {})) {
-    if (!Array.isArray(spec?.models)) continue;
-    for (const m of spec.models) if (!ids.has(m)) out.push(`access.roles.${role}.models: "${m}" is not a models catalog id`);
-  }
-  return out;
+    return out;
 }

package/src/config/refs.js

@@ -0,0 +1,32 @@
+/*
+ * `${NAME}` references to the environment, so a file can say where a secret
+ * comes from without holding it: mcp.json headers and env, and the keys in
+ * tinywebui.config.json.
+ */
+const REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/** True when a value names at least one environment variable. */
+export const hasRef = (value) => typeof value === 'string' && /\$\{[A-Za-z_][A-Za-z0-9_]*\}/.test(value);
+/** The names a value refers to that the environment does not set. */
+export function missingRefs(value, env = process.env) {
+    if (typeof value !== 'string')
+        return [];
+    return [...value.matchAll(REF)].map((m) => m[1]).filter((name) => env[name] === undefined);
+}
+/**
+ * Fills `${NAME}` from the environment. A name that is not set is left as
+ * written, so validation can say which one; it never becomes an empty
+ * string, which reads as "unauthorised" and sends people looking in the
+ * wrong place.
+ */
+export function fillRefs(value, env = process.env) {
+    if (typeof value !== 'string')
+        return value;
+    return value.replace(REF, (ref, name) => env[name] ?? ref);
+}
+/** fillRefs, but a name that is not set is an error naming it and `where` it was written. */
+export function expandRefs(value, env = process.env, where = 'mcp.json') {
+    const [missing] = missingRefs(value, env);
+    if (missing)
+        throw new Error(`${where} refers to \${${missing}}, which is not set in TinyWebUI's environment`);
+    return fillRefs(value, env);
+}

package/src/config/secrets.js

@@ -0,0 +1,153 @@
+/*
+ * Secrets kept out of tinywebui.config.json. The config file says what the
+ * deployment is -- endpoints, connectors, models, policy -- and is safe to
+ * read, diff and share. A key is not part of that shape, so it lives in one
+ * of two places instead:
+ *
+ *   "${NAME}" in the config   filled in from the environment (see refs.ts)
+ *   tinywebui.secrets.json    beside the config, owner-only: what the settings
+ *                             page saves, and the generated session secret
+ *
+ * A literal key still found in the config file is honoured, and moved into
+ * the secrets file the next time the server starts. Pure functions only; the
+ * files are read and written by createConfigSource().
+ */
+import { SECRET_KEYS } from '../access/policy.js';
+import { fillRefs, hasRef, missingRefs } from './refs.js';
+const TOP = [...SECRET_KEYS];
+/** A value that is a secret itself, rather than empty or a pointer to one. */
+const literal = (v) => typeof v === 'string' && v !== '' && !hasRef(v);
+/** The literal secrets a file-shaped config holds, and the config without them. */
+export function extractSecrets(file) {
+    const shape = { ...file };
+    const found = {};
+    const names = [];
+    for (const k of TOP) {
+        if (!literal(shape[k]))
+            continue;
+        found[k] = shape[k];
+        names.push(k);
+        delete shape[k];
+    }
+    if (Array.isArray(shape.connectors)) {
+        shape.connectors = shape.connectors.map((c) => {
+            if (!c || typeof c !== 'object' || !literal(c.apiKey))
+                return c;
+            (found.connectors ??= {})[c.id] = { apiKey: c.apiKey };
+            names.push(`connectors.${c.id}.apiKey`);
+            const { apiKey, ...rest } = c;
+            return rest;
+        });
+    }
+    return { shape, found, names };
+}
+/** Folds newly found secrets into the stored ones; the found ones win. */
+export function mergeSecrets(stored, found) {
+    const out = { ...stored, ...found, connectors: { ...(stored.connectors || {}), ...(found.connectors || {}) } };
+    if (!Object.keys(out.connectors).length)
+        delete out.connectors;
+    return out;
+}
+/**
+ * A file-shaped config with its secrets filled in: a reference from the
+ * environment, a literal as written, anything absent from the secrets file.
+ */
+export function applySecrets(file, secrets, env = process.env) {
+    const out = { ...file };
+    for (const k of TOP) {
+        if (hasRef(out[k]))
+            out[k] = fillRefs(out[k], env);
+        else if (!literal(out[k]) && secrets[k])
+            out[k] = secrets[k];
+    }
+    if (Array.isArray(out.connectors)) {
+        out.connectors = out.connectors.map((c) => {
+            if (!c || typeof c !== 'object')
+                return c;
+            if (hasRef(c.apiKey))
+                return { ...c, apiKey: fillRefs(c.apiKey, env) };
+            const stored = secrets.connectors?.[c.id]?.apiKey;
+            return !literal(c.apiKey) && stored ? { ...c, apiKey: stored } : c;
+        });
+    }
+    return out;
+}
+/** References in the config file the environment does not satisfy, as problems. */
+export function refProblems(file, env = process.env) {
+    const out = [];
+    const check = (where, v) => {
+        for (const name of missingRefs(v, env))
+            out.push(`${where} refers to \${${name}}, which is not set in TinyWebUI's environment`);
+    };
+    for (const k of TOP)
+        check(k, file[k]);
+    for (const c of Array.isArray(file.connectors) ? file.connectors : []) {
+        if (c && typeof c === 'object')
+            check(`connectors.${c.id}.apiKey`, c.apiKey);
+    }
+    return out;
+}
+/**
+ * Splits a settings save. Keys typed into the page go to the secrets file and
+ * leave the patch (an `apiKey: undefined` left in it drops any literal from
+ * the config file); a "${NAME}" typed there is shape and stays in it. Sent
+ * empty or left out, a key is unchanged; null clears it. A key the config
+ * file takes from the environment cannot be overwritten from the page:
+ * `refused` names those.
+ *
+ * `current` is the config file as it stands (catalog flattened).
+ */
+export function takeSecrets(patch, current, stored) {
+    const out = { ...patch };
+    const secrets = { ...stored, connectors: { ...(stored.connectors || {}) } };
+    const refused = [];
+    if ('apiKey' in out) {
+        const v = out.apiKey;
+        delete out.apiKey;
+        if (v === undefined || v === '') { /* unchanged */ }
+        else if (hasRef(current.apiKey) && !hasRef(v))
+            refused.push(`apiKey (comes from ${current.apiKey})`);
+        else if (v === null) {
+            delete secrets.apiKey;
+            out.apiKey = undefined;
+        }
+        else if (hasRef(v)) {
+            delete secrets.apiKey;
+            out.apiKey = v;
+        }
+        else {
+            secrets.apiKey = String(v);
+            out.apiKey = undefined;
+        }
+    }
+    if (Array.isArray(out.connectors)) {
+        const old = new Map((Array.isArray(current.connectors) ? current.connectors : []).map((c) => [c?.id, c]));
+        const kept = {};
+        out.connectors = out.connectors.map((c) => {
+            if (!c || typeof c !== 'object')
+                return c;
+            const { apiKey, ...rest } = c;
+            const prev = old.get(c.id);
+            if (hasRef(prev?.apiKey) && !hasRef(apiKey)) {
+                if (apiKey !== undefined && apiKey !== '' && apiKey !== null)
+                    refused.push(`connectors.${c.id}.apiKey (comes from ${prev.apiKey})`);
+                return { ...rest, apiKey: prev.apiKey };
+            }
+            if (hasRef(apiKey))
+                return { ...rest, apiKey };
+            if (apiKey === null)
+                return rest;
+            const key = apiKey === undefined || apiKey === ''
+                ? secrets.connectors[c.id]?.apiKey ?? (literal(prev?.apiKey) ? prev.apiKey : undefined)
+                : String(apiKey);
+            if (key)
+                kept[c.id] = { apiKey: key };
+            return rest;
+        });
+        // A connector that is gone takes its key with it.
+        secrets.connectors = kept;
+    }
+    if (!Object.keys(secrets.connectors).length)
+        delete secrets.connectors;
+    return { patch: out, secrets, refused };
+}