@objectstack/service-settings 9.2.0 → 9.3.0

package/dist/index.cjs

@@ -38,14 +38,18 @@ __export(index_exports, {
   SettingsLockedError: () => SettingsLockedError,
   SettingsService: () => SettingsService,
   SettingsServicePlugin: () => SettingsServicePlugin,
+  SettingsValidationError: () => SettingsValidationError,
   UnknownKeyError: () => UnknownKeyError,
   UnknownNamespaceError: () => UnknownNamespaceError,
+  VisibilityParseError: () => VisibilityParseError,
   brandingSettingsManifest: () => brandingSettingsManifest,
   builtinSettingsManifests: () => builtinSettingsManifests,
   envKeyOf: () => envKeyOf,
+  evaluateVisibility: () => evaluateVisibility,
   featureFlagsSettingsManifest: () => featureFlagsSettingsManifest,
   mailSettingsManifest: () => mailSettingsManifest,
   mailTestActionHandler: () => mailTestActionHandler,
+  referencedKeys: () => referencedKeys,
   registerSettingsRoutes: () => registerSettingsRoutes,
   settingsBuiltinTranslations: () => settingsBuiltinTranslations,
   settingsObjects: () => settingsObjects,
@@ -108,6 +112,178 @@ var UnknownKeyError = class extends Error {
     this.code = "SETTINGS_UNKNOWN_KEY";
   }
 };
+var SettingsValidationError = class extends Error {
+  constructor(namespace, fields) {
+    super(
+      `Settings for '${namespace}' are incomplete: ` + Object.entries(fields).map(([k, msg]) => `${k} \u2014 ${msg}`).join("; ")
+    );
+    this.namespace = namespace;
+    this.fields = fields;
+    this.code = "SETTINGS_VALIDATION";
+  }
+};
+
+// src/visibility-eval.ts
+var VisibilityParseError = class extends Error {
+  constructor(expr, detail) {
+    super(`Cannot parse visibility expression "${expr}": ${detail}`);
+    this.name = "VisibilityParseError";
+  }
+};
+function visibilitySource(visible) {
+  let src;
+  if (typeof visible === "string") src = visible;
+  else if (visible && typeof visible === "object" && typeof visible.source === "string") {
+    src = visible.source;
+  }
+  if (src === void 0) return void 0;
+  const trimmed = src.trim();
+  if (trimmed.startsWith("${") && trimmed.endsWith("}")) return trimmed.slice(2, -1).trim();
+  return trimmed;
+}
+function referencedKeys(visible) {
+  const src = visibilitySource(visible);
+  if (!src) return [];
+  return [...src.matchAll(/data\.([A-Za-z_][A-Za-z0-9_]*)/g)].map((m) => m[1]);
+}
+function tokenize(expr) {
+  const tokens = [];
+  let i = 0;
+  while (i < expr.length) {
+    const ch = expr[i];
+    if (/\s/.test(ch)) {
+      i++;
+      continue;
+    }
+    if (ch === "(" || ch === ")") {
+      tokens.push({ kind: "punct", value: ch });
+      i++;
+      continue;
+    }
+    let matchedOp = false;
+    for (const op of ["===", "!==", "==", "!=", "&&", "||"]) {
+      if (expr.startsWith(op, i)) {
+        tokens.push({ kind: "punct", value: op });
+        i += op.length;
+        matchedOp = true;
+        break;
+      }
+    }
+    if (matchedOp) continue;
+    if (ch === "!") {
+      tokens.push({ kind: "punct", value: "!" });
+      i++;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      const quote = ch;
+      let j = i + 1;
+      let out = "";
+      while (j < expr.length && expr[j] !== quote) {
+        if (expr[j] === "\\" && j + 1 < expr.length) {
+          out += expr[j + 1];
+          j += 2;
+        } else {
+          out += expr[j];
+          j++;
+        }
+      }
+      if (j >= expr.length) throw new VisibilityParseError(expr, "unterminated string");
+      tokens.push({ kind: "string", value: out });
+      i = j + 1;
+      continue;
+    }
+    if (/[0-9]/.test(ch)) {
+      const m = /^[0-9]+(\.[0-9]+)?/.exec(expr.slice(i));
+      tokens.push({ kind: "number", value: Number(m[0]) });
+      i += m[0].length;
+      continue;
+    }
+    if (/[A-Za-z_]/.test(ch)) {
+      const m = /^[A-Za-z_][A-Za-z0-9_.]*/.exec(expr.slice(i));
+      const word = m[0];
+      if (word === "true") tokens.push({ kind: "keyword", value: true });
+      else if (word === "false") tokens.push({ kind: "keyword", value: false });
+      else if (word === "null") tokens.push({ kind: "keyword", value: null });
+      else if (word.startsWith("data.")) {
+        const key = word.slice("data.".length);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new VisibilityParseError(expr, `unsupported reference "${word}"`);
+        tokens.push({ kind: "ref", value: key });
+      } else throw new VisibilityParseError(expr, `unsupported identifier "${word}"`);
+      i += word.length;
+      continue;
+    }
+    throw new VisibilityParseError(expr, `unexpected character "${ch}"`);
+  }
+  return tokens;
+}
+function evaluateVisibility(visible, data) {
+  const src = visibilitySource(visible);
+  if (!src) return true;
+  const tokens = tokenize(src);
+  let pos = 0;
+  const peek = () => tokens[pos];
+  const eat = (value) => {
+    const t = tokens[pos];
+    if (t?.kind === "punct" && t.value === value) {
+      pos++;
+      return true;
+    }
+    return false;
+  };
+  function primary() {
+    const t = peek();
+    if (!t) throw new VisibilityParseError(src, "unexpected end of expression");
+    if (t.kind === "punct" && t.value === "(") {
+      pos++;
+      const v = orExpr();
+      if (!eat(")")) throw new VisibilityParseError(src, "missing closing parenthesis");
+      return v;
+    }
+    if (t.kind === "string" || t.kind === "number" || t.kind === "keyword") {
+      pos++;
+      return t.value;
+    }
+    if (t.kind === "ref") {
+      pos++;
+      return data[t.value];
+    }
+    throw new VisibilityParseError(src, `unexpected token`);
+  }
+  function comparison() {
+    const left = primary();
+    const t = peek();
+    if (t?.kind === "punct" && ["===", "!==", "==", "!="].includes(t.value)) {
+      pos++;
+      const right = primary();
+      return t.value === "===" || t.value === "==" ? left === right : left !== right;
+    }
+    return left;
+  }
+  function unary() {
+    if (eat("!")) return !unary();
+    return comparison();
+  }
+  function andExpr() {
+    let v = unary();
+    while (eat("&&")) {
+      const r = unary();
+      v = v && r;
+    }
+    return v;
+  }
+  function orExpr() {
+    let v = andExpr();
+    while (eat("||")) {
+      const r = andExpr();
+      v = v || r;
+    }
+    return v;
+  }
+  const result = orExpr();
+  if (pos !== tokens.length) throw new VisibilityParseError(src, "trailing tokens");
+  return Boolean(result);
+}
 
 // src/settings-service.ts
 var DEFAULT_OBJECT = "sys_setting";
@@ -393,6 +569,7 @@ var SettingsService = class {
         throw new SettingsLockedError(namespace, key, `locked-by-${upper.scope}`);
       }
     }
+    await this.validatePatch(namespace, patch, ctx);
     for (const [key, rawValue] of Object.entries(patch)) {
       const scope = reg.scopes.get(key);
       const userId = scope === "user" ? ctx.userId ?? null : null;
@@ -484,12 +661,111 @@ var SettingsService = class {
     }
     return out;
   }
+  /**
+   * Save-time validation for `setMany`, fulfilling the spec promise that
+   * `required` is enforced server-side and hidden specifiers are not
+   * validated. Semantics, tuned to reject broken configs without
+   * breaking unrelated single-key writes:
+   *
+   * - The post-write value map is computed (current values overlaid
+   *   with the patch; `null` patch entries fall back to the default).
+   * - A specifier is checked only when the patch TOUCHES it — its own
+   *   key is in the patch, or a key its `visible` expression references
+   *   is (switching provider must validate that provider's fields).
+   * - `required` + visible + empty → rejected.
+   * - `pattern` (text fields) + non-empty value that mismatches → rejected.
+   * - All-null patches (namespace reset) and unparseable visibility
+   *   expressions skip validation rather than block the write.
+   */
+  async validatePatch(namespace, patch, ctx) {
+    const reg = this.registry.get(namespace);
+    if (!reg) return;
+    const entries = Object.entries(patch);
+    if (entries.length === 0) return;
+    if (entries.every(([, v]) => v === null || typeof v === "undefined")) return;
+    const data = {};
+    for (const [key] of reg.scopes) {
+      data[key] = (await this.get(namespace, key, ctx)).value;
+    }
+    for (const [key, value] of entries) {
+      data[key] = value === null || typeof value === "undefined" ? reg.defaults.get(key) ?? null : value;
+    }
+    const patchKeys = new Set(Object.keys(patch));
+    const errors = {};
+    for (const spec of reg.manifest.specifiers ?? []) {
+      const key = spec.key;
+      const type = String(spec.type ?? "");
+      if (!key || LAYOUT_ONLY_TYPES.has(type)) continue;
+      let visible = true;
+      let deps = [];
+      if (typeof spec.visible !== "undefined") {
+        try {
+          visible = evaluateVisibility(spec.visible, data);
+          deps = referencedKeys(spec.visible);
+        } catch {
+          continue;
+        }
+      }
+      if (!visible) continue;
+      if (!patchKeys.has(key) && !deps.some((d) => patchKeys.has(d))) continue;
+      const value = data[key];
+      const label = typeof spec.label === "string" ? spec.label : key;
+      const empty = value === null || typeof value === "undefined" || typeof value === "string" && value.trim() === "";
+      if (spec.required === true && empty) {
+        errors[key] = `${label} is required for this configuration.`;
+        continue;
+      }
+      if (!empty && typeof spec.pattern === "string" && typeof value === "string") {
+        let re;
+        try {
+          re = new RegExp(spec.pattern);
+        } catch {
+          re = void 0;
+        }
+        if (re && !re.test(value)) {
+          const hint = typeof spec.description === "string" ? ` ${spec.description}` : "";
+          errors[key] = `${label} does not match the expected format.${hint}`;
+        }
+      }
+    }
+    if (Object.keys(errors).length > 0) {
+      throw new SettingsValidationError(namespace, errors);
+    }
+  }
+  /**
+   * Clear every persisted row in a namespace so values fall back to
+   * env/defaults. Env-locked keys are untouched (env wins over rows
+   * anyway and refuses writes). Persisted rows are nulled rather than
+   * deleted so the audit trail records the reset per key.
+   *
+   * Returns the number of cleared keys.
+   */
+  async resetNamespace(namespace, ctx = {}) {
+    const payload = await this.getNamespace(namespace, ctx);
+    const patch = {};
+    for (const [key, v] of Object.entries(payload.values)) {
+      if (v.source === "global" || v.source === "tenant" || v.source === "user") {
+        patch[key] = null;
+      }
+    }
+    const keys = Object.keys(patch);
+    if (keys.length > 0) await this.setMany(namespace, patch, ctx);
+    return keys.length;
+  }
   /** Invoke a declared action (test connection, rotate, …). */
   async runAction(namespace, actionId, payload, ctx = {}) {
     const reg = this.registry.get(namespace);
     if (!reg) throw new UnknownNamespaceError(namespace);
     const handler = reg.actions.get(actionId);
     if (!handler) {
+      if (actionId === "reset") {
+        const cleared = await this.resetNamespace(namespace, ctx);
+        return {
+          ok: true,
+          severity: "info",
+          message: cleared > 0 ? `Cleared ${cleared} saved value(s); environment/default configuration is back in effect.` : "No saved values to clear \u2014 already using environment/default configuration."
+        };
+      }
       return {
         ok: false,
         severity: "error",
@@ -916,6 +1192,11 @@ function registerSettingsRoutes(http, service, opts = {}) {
         sendError(res, 404, "UNKNOWN_NAMESPACE", err.message);
       } else if (err instanceof UnknownKeyError) {
         sendError(res, 400, "UNKNOWN_KEY", err.message, { namespace: err.namespace, key: err.key });
+      } else if (err instanceof SettingsValidationError) {
+        sendError(res, 400, "SETTINGS_VALIDATION", err.message, {
+          namespace: err.namespace,
+          fields: err.fields
+        });
       } else {
         sendError(res, 500, "INTERNAL", err?.message ?? "Failed to write namespace");
       }
@@ -1477,7 +1758,8 @@ var manifest4 = {
       key: "gateway_model",
       label: "Gateway model",
       required: true,
-      description: "Forwarded as AI_GATEWAY_MODEL. Example: openai/gpt-4o",
+      description: "Forwarded as AI_GATEWAY_MODEL. Format: provider/model, e.g. openai/gpt-4o or anthropic/claude-sonnet-4.6.",
+      pattern: "^[A-Za-z0-9_-]+\\/[A-Za-z0-9._:-]+$",
       visible: "${data.provider === 'gateway'}"
     },
     {
@@ -1673,6 +1955,7 @@ var manifest4 = {
       label: "Model",
       required: false,
       default: "openai/gpt-4o-mini",
+      pattern: "^[A-Za-z0-9_-]+\\/[A-Za-z0-9._:@-]+$",
       description: "Format: provider/model. Allowed providers (per Cloudflare /compat): anthropic, openai, groq, mistral, cohere, perplexity, workers-ai, google-ai-studio, vertex, grok, deepseek, cerebras, baseten, parallel.",
       visible: "${data.provider === 'cloudflare'}"
     },
@@ -1829,6 +2112,18 @@ var manifest4 = {
       icon: "Plug",
       handler: { kind: "http", method: "POST", url: "/api/settings/ai/test" }
     },
+    // Escape hatch: clears every saved row in this namespace so the
+    // runtime falls back to env auto-detection (AI_GATEWAY_MODEL /
+    // OPENAI_API_KEY / …). Without it, a broken saved config can only
+    // be removed by editing sys_setting by hand.
+    {
+      type: "action_button",
+      id: "reset",
+      label: "Reset to environment defaults",
+      required: false,
+      icon: "RotateCcw",
+      handler: { kind: "http", method: "POST", url: "/api/settings/ai/reset" }
+    },
     // ════════════════════════════════════════════════════════════════
     // Embedder — text → vector provider used by knowledge / RAG.
     // Decoupled from the chat provider above so an organisation can
@@ -3671,14 +3966,18 @@ function wrapEngineAsSettingsEngine(engine) {
   SettingsLockedError,
   SettingsService,
   SettingsServicePlugin,
+  SettingsValidationError,
   UnknownKeyError,
   UnknownNamespaceError,
+  VisibilityParseError,
   brandingSettingsManifest,
   builtinSettingsManifests,
   envKeyOf,
+  evaluateVisibility,
   featureFlagsSettingsManifest,
   mailSettingsManifest,
   mailTestActionHandler,
+  referencedKeys,
   registerSettingsRoutes,
   settingsBuiltinTranslations,
   settingsObjects,