chainlesschain 0.162.161 → 0.162.162

package/src/lib/lsp/__tests__/diagnostics-scheduler.test.js

@@ -0,0 +1,93 @@
+/**
+ * Edit-triggered auto-diagnostics scheduler (P2) — debounce, throttle, and
+ * token-cap. Pure + clock-injected.
+ */
+import { describe, it, expect } from "vitest";
+import {
+  DiagnosticsScheduler,
+  capDiagnostics,
+} from "../diagnostics-scheduler.js";
+
+describe("DiagnosticsScheduler — debounce", () => {
+  it("coalesces a burst of edits into one run after the quiet period", () => {
+    const s = new DiagnosticsScheduler({ debounceMs: 300, throttleMs: 1000 });
+    s.noteEdit("f.js", 0).noteEdit("f.js", 100).noteEdit("f.js", 200);
+    expect(s.due(400)).toEqual([]); // last edit at 200, only 200ms quiet
+    expect(s.due(500)).toEqual(["f.js"]); // 300ms after the last edit
+    expect(s.pendingCount()).toBe(0);
+  });
+});
+
+describe("DiagnosticsScheduler — throttle", () => {
+  it("won't run the same file again within the throttle window", () => {
+    const s = new DiagnosticsScheduler({ debounceMs: 100, throttleMs: 1000 });
+    s.noteEdit("f.js", 0);
+    expect(s.due(200)).toEqual(["f.js"]); // first run at 200
+    s.noteEdit("f.js", 300);
+    expect(s.due(500)).toEqual([]); // throttled (only 300ms since last run)
+    expect(s.pendingCount()).toBe(1); // stays pending
+    expect(s.due(1300)).toEqual(["f.js"]); // window passed → runs
+  });
+});
+
+describe("DiagnosticsScheduler — msUntilNextDue", () => {
+  it("reports the earliest time a pending file can run", () => {
+    const s = new DiagnosticsScheduler({ debounceMs: 300, throttleMs: 1000 });
+    s.noteEdit("f.js", 100);
+    expect(s.msUntilNextDue(200)).toBe(200); // ready at 400, now 200
+    expect(s.msUntilNextDue(500)).toBe(0); // already due
+    s.reset();
+    expect(s.msUntilNextDue(0)).toBeNull();
+  });
+
+  it("independent files debounce independently", () => {
+    const s = new DiagnosticsScheduler({ debounceMs: 300, throttleMs: 1000 });
+    s.noteEdit("a.js", 0).noteEdit("b.js", 200);
+    expect(s.due(350).sort()).toEqual(["a.js"]); // b still settling
+    expect(s.due(600)).toEqual(["b.js"]);
+  });
+});
+
+describe("capDiagnostics — token cap, least-severe dropped first", () => {
+  const mk = (severity, message) => ({ severity, message });
+
+  it("keeps within the token budget and drops the tail", () => {
+    const long = "x".repeat(400); // ~106 tokens each
+    const diags = [
+      mk("error", long),
+      mk("error", long),
+      mk("warning", long),
+      mk("hint", long),
+    ];
+    const r = capDiagnostics(diags, { maxTokens: 220 });
+    expect(r.kept.length).toBe(2);
+    expect(r.truncated).toBe(true);
+    expect(r.dropped).toBe(2);
+  });
+
+  it("prioritizes by severity — errors kept, hints dropped", () => {
+    const long = "y".repeat(400);
+    const diags = [mk("hint", long), mk("error", long), mk("warning", long)];
+    const r = capDiagnostics(diags, { maxTokens: 120 });
+    expect(r.kept).toHaveLength(1);
+    expect(r.kept[0].severity).toBe("error"); // most severe survived
+  });
+
+  it("accepts numeric LSP severities (1=error … 4=hint)", () => {
+    const long = "z".repeat(400);
+    const r = capDiagnostics([mk(4, long), mk(1, long)], { maxTokens: 120 });
+    expect(r.kept[0].severity).toBe(1);
+  });
+
+  it("keeps at least one item and is a no-op under budget", () => {
+    const small = [mk("error", "short")];
+    expect(capDiagnostics(small, { maxTokens: 10000 })).toMatchObject({
+      dropped: 0,
+      truncated: false,
+    });
+    // a single huge item is still kept (never emit empty)
+    expect(
+      capDiagnostics([mk("error", "q".repeat(9999))], { maxTokens: 5 }).kept,
+    ).toHaveLength(1);
+  });
+});

package/src/lib/lsp/diagnostics-scheduler.js

@@ -0,0 +1,127 @@
+/**
+ * Edit-triggered auto-diagnostics scheduler (P2 "LSP 自动诊断").
+ *
+ * `CodeIntelligence.refreshFile` already re-diagnoses one file on demand, and
+ * `LSPManager` already quarantines a crash-looping server (sliding-window
+ * backoff) — those pieces exist. What's missing is the layer that turns a stream
+ * of EDITS into well-paced diagnostics runs and bounds their volume:
+ *
+ *   - DEBOUNCE  — coalesce a burst of rapid edits to one file into a single run
+ *                 once edits settle, so typing doesn't spawn a run per keystroke.
+ *   - THROTTLE  — a minimum interval between runs for the same file, so a file
+ *                 edited continuously still can't run more than once per window.
+ *   - TOKEN CAP — bound the diagnostics handed to the model, dropping the least
+ *                 severe first, with a truncation marker.
+ *
+ * Pure + clock-injected (no timers): the caller feeds edit events and a `now`,
+ * and asks which files are due. Deterministic and unit-testable.
+ */
+
+/** LSP-ish severity → order (lower = more severe). Accepts numbers or labels. */
+function severityOrder(sev) {
+  if (typeof sev === "number" && Number.isFinite(sev)) return sev; // LSP 1..4
+  const m = { error: 1, warning: 2, information: 3, info: 3, hint: 4 };
+  return m[String(sev || "").toLowerCase()] ?? 5;
+}
+
+export class DiagnosticsScheduler {
+  /**
+   * @param {object} [opts]
+   *   debounceMs — quiet period after the last edit before a run (default 300)
+   *   throttleMs — minimum spacing between runs for one file (default 1000)
+   */
+  constructor({ debounceMs = 300, throttleMs = 1000 } = {}) {
+    this.debounceMs =
+      Number.isFinite(debounceMs) && debounceMs >= 0 ? debounceMs : 300;
+    this.throttleMs =
+      Number.isFinite(throttleMs) && throttleMs >= 0 ? throttleMs : 1000;
+    this._pending = new Map(); // uri → last edit time
+    this._lastRun = new Map(); // uri → last run time
+  }
+
+  /** Record an edit to `uri` at `at`. A later edit resets the debounce window. */
+  noteEdit(uri, at) {
+    if (uri == null) return this;
+    this._pending.set(String(uri), Number(at));
+    return this;
+  }
+
+  /**
+   * The URIs whose debounce window has elapsed AND whose throttle interval has
+   * passed at `now`. Due URIs are marked run (cleared from pending, `_lastRun`
+   * stamped); a throttled URI STAYS pending so it fires once the window passes.
+   */
+  due(now) {
+    const t = Number(now);
+    const out = [];
+    for (const [uri, editAt] of this._pending) {
+      if (t - editAt < this.debounceMs) continue; // still settling
+      const last = this._lastRun.get(uri);
+      if (last != null && t - last < this.throttleMs) continue; // throttled
+      out.push(uri);
+    }
+    for (const uri of out) {
+      this._pending.delete(uri);
+      this._lastRun.set(uri, t);
+    }
+    return out;
+  }
+
+  /** ms until the earliest pending URI could next run, or null if none pending. */
+  msUntilNextDue(now) {
+    const t = Number(now);
+    let min = null;
+    for (const [uri, editAt] of this._pending) {
+      const debounceReady = editAt + this.debounceMs;
+      const last = this._lastRun.get(uri);
+      const throttleReady = last != null ? last + this.throttleMs : -Infinity;
+      const readyAt = Math.max(debounceReady, throttleReady);
+      const ms = Math.max(0, readyAt - t);
+      if (min == null || ms < min) min = ms;
+    }
+    return min;
+  }
+
+  pendingCount() {
+    return this._pending.size;
+  }
+
+  reset() {
+    this._pending.clear();
+    this._lastRun.clear();
+  }
+}
+
+/**
+ * Bound a diagnostics array to a token budget, dropping the LEAST severe first.
+ * The estimate is chars/token over each message (plus a small per-item overhead).
+ * Always keeps at least one item when the list is non-empty.
+ *
+ * @returns {{kept:Array, dropped:number, tokens:number, truncated:boolean}}
+ */
+export function capDiagnostics(
+  diagnostics,
+  { maxTokens = 2000, charsPerToken = 4, prioritize = true } = {},
+) {
+  const list = Array.isArray(diagnostics) ? [...diagnostics] : [];
+  if (prioritize) {
+    list.sort(
+      (a, b) => severityOrder(a?.severity) - severityOrder(b?.severity),
+    );
+  }
+  const kept = [];
+  let tokens = 0;
+  for (const d of list) {
+    const cost = Math.max(
+      1,
+      Math.ceil(
+        (String(d?.message || "").length + 24) / Math.max(1, charsPerToken),
+      ),
+    );
+    if (kept.length > 0 && tokens + cost > maxTokens) break;
+    kept.push(d);
+    tokens += cost;
+  }
+  const dropped = list.length - kept.length;
+  return { kept, dropped, tokens, truncated: dropped > 0 };
+}

package/src/lib/operation-fingerprint.js

@@ -0,0 +1,95 @@
+/**
+ * Operation fingerprint — binds an approval to the specific operation it
+ * authorizes (IDE gap P0#2 "每个副作用关联唯一 approvalId；approvalId 绑定操作
+ * 指纹（工具名+参数哈希）").
+ *
+ * A remote permission ask is matched to its resolve by a random `requestId`.
+ * That alone answers "which ask" but not "which OPERATION" — a stale approval
+ * card, a replayed resolve, or a request body swapped in flight could settle a
+ * gate for an operation the human never actually saw. A fingerprint over the
+ * operation's identity (tool + canonicalized arguments) lets the host verify
+ * that the decision coming back approves the SAME operation it published, and
+ * reject a mismatch (confused-deputy defense) while still failing closed.
+ *
+ * Pure + deterministic (no clock / RNG): the same operation always yields the
+ * same fingerprint, so both ends compute it independently and compare.
+ */
+
+import { createHash, timingSafeEqual } from "node:crypto";
+
+/**
+ * Recursively canonical JSON: object keys sorted so argument ORDER never
+ * changes the fingerprint ({a:1,b:2} === {b:2,a:1}); arrays keep their order
+ * (order is semantic for a list). Cycles are impossible here (inputs are the
+ * plain ask payload), but a depth guard keeps it total.
+ */
+function canonicalize(value, depth = 0) {
+  if (value === null || value === undefined) return "null";
+  if (depth > 32) return '"[maxdepth]"';
+  const t = typeof value;
+  if (t === "number")
+    return Number.isFinite(value) ? JSON.stringify(value) : "null";
+  if (t === "boolean" || t === "string") return JSON.stringify(value);
+  if (t !== "object") return JSON.stringify(String(value)); // bigint/function/symbol → string
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => canonicalize(v, depth + 1)).join(",")}]`;
+  }
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(value[k], depth + 1)}`).join(",")}}`;
+}
+
+/**
+ * Stable 32-hex fingerprint of an operation. `args` (structured) is preferred;
+ * a `detail` string (e.g. a shell command) is the fallback identity. tool +
+ * action + the argument payload together identify the side effect.
+ *
+ * @param {object} op
+ * @param {string} [op.tool]    the tool / capability name
+ * @param {string} [op.action]  a sub-action within the tool
+ * @param {*}      [op.args]    structured arguments (preferred)
+ * @param {string} [op.detail]  a human/string form used when args is absent
+ * @returns {string} 32-char lowercase hex
+ */
+export function operationFingerprint(op = {}) {
+  const canonical = canonicalize({
+    tool: op.tool ?? null,
+    action: op.action ?? null,
+    args: op.args !== undefined ? op.args : (op.detail ?? null),
+  });
+  return createHash("sha256")
+    .update(canonical, "utf8")
+    .digest("hex")
+    .slice(0, 32);
+}
+
+/**
+ * Constant-time equality of two fingerprints. Both must be non-empty strings
+ * of equal length; anything else (null / mismatched length / non-string) →
+ * false. Constant-time so a mismatch position is not observable.
+ */
+export function fingerprintsMatch(a, b) {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  if (a.length === 0 || a.length !== b.length) return false;
+  try {
+    return timingSafeEqual(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Verdict for a resolve carrying (or omitting) a fingerprint against the
+ * pending ask's fingerprint. Backward compatible: a resolve with NO fingerprint
+ * is accepted (old devices predate the field) — absence is tolerated, presence
+ * is verified. A PRESENT-but-mismatched fingerprint is rejected.
+ *
+ * @param {string|null|undefined} pending  the pending ask's fingerprint
+ * @param {string|null|undefined} resolved the fingerprint the resolve carries
+ * @returns {boolean} true = settle the gate; false = reject (keep fail-closed)
+ */
+export function approvalFingerprintOk(pending, resolved) {
+  if (resolved === null || resolved === undefined || resolved === "")
+    return true;
+  if (!pending) return true; // nothing to bind against (legacy pending ask)
+  return fingerprintsMatch(pending, resolved);
+}

package/src/lib/plugin-runtime/capabilities.js

@@ -0,0 +1,371 @@
+/**
+ * Plugin capability declaration + typed options schema — the manifest's
+ * declarative SECURITY CONTRACT (P1 "Plugin 能力声明和配置 Schema").
+ *
+ * Two concerns, both pure (no I/O), both parsed from `plugin.json`:
+ *
+ * 1. **Declared capabilities** (`manifest.permissions`) — what a plugin is
+ *    allowed to touch: process spawning, network domains, filesystem roots,
+ *    MCP, monitors, credentials. On install/upgrade a `diffCapabilities`
+ *    surfaces what CHANGED; any WIDENING (a new capability, a new domain/root)
+ *    forces a fresh consent (`consentRequiredForUpgrade`). `auditDeclaredCapabilities`
+ *    catches the "declares no network but ships an MCP server" mismatch — a
+ *    plugin whose COMPONENTS need a capability it did not DECLARE.
+ *
+ * 2. **Typed options schema** (`manifest.optionsSchema`) — each config key's
+ *    type/default/required/enum/scope/sensitivity. `validateOptions` enforces
+ *    it AND the invariant that a `sensitive` option can NEVER be supplied from
+ *    project config (it must come from the user scope / OS keychain), so a
+ *    checked-in project file can't smuggle a secret. `redactSensitiveOptions`
+ *    masks secrets for logs/audit.
+ *
+ * Trust today is exact-version (see [[trust.js]]); this module is what an
+ * install/upgrade flow consults to decide whether that trust must be re-taken.
+ */
+
+// ─── capabilities ───────────────────────────────────────────────────────────
+
+export const CAPABILITY_KINDS = Object.freeze([
+  "process",
+  "network",
+  "filesystem",
+  "mcp",
+  "monitor",
+  "credential",
+]);
+
+function toBool(v) {
+  if (v === true) return true;
+  if (typeof v === "number") return v === 1;
+  if (typeof v === "string") {
+    const s = v.trim().toLowerCase();
+    return s === "true" || s === "1" || s === "yes";
+  }
+  return false;
+}
+
+/** Normalize a string list (array | comma-string | null) → deduped string[]. */
+function toList(v) {
+  if (v == null) return [];
+  const list = Array.isArray(v) ? v : String(v).split(/[,\s]+/);
+  const out = [];
+  const seen = new Set();
+  for (const item of list) {
+    const s = String(item).trim();
+    if (!s || seen.has(s)) continue;
+    seen.add(s);
+    out.push(s);
+  }
+  return out;
+}
+
+/** A `network` declaration → `{ any, domains }`. `true`/`"*"` = any host. */
+function normalizeNetwork(v) {
+  if (v === true || v === "*") return { any: true, domains: [] };
+  if (Array.isArray(v) || typeof v === "string") {
+    const domains = toList(v);
+    return {
+      any: domains.includes("*"),
+      domains: domains.filter((d) => d !== "*"),
+    };
+  }
+  if (v && typeof v === "object") {
+    const domains = toList(v.domains);
+    return {
+      any: toBool(v.any) || domains.includes("*"),
+      domains: domains.filter((d) => d !== "*"),
+    };
+  }
+  return { any: false, domains: [] };
+}
+
+/**
+ * Normalize a manifest `permissions` block into the canonical capability set.
+ * Everything defaults to DENY (false / empty) — a capability must be declared.
+ */
+export function normalizeCapabilities(raw) {
+  const r = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+  return {
+    process: toBool(r.process),
+    network: normalizeNetwork(r.network),
+    filesystem: { roots: toList(r.filesystem ?? r.filesystemRoots) },
+    mcp: toBool(r.mcp),
+    monitor: toBool(r.monitor ?? r.monitors),
+    credential: { names: toList(r.credential ?? r.credentials) },
+  };
+}
+
+const EMPTY_CAPS = normalizeCapabilities(null);
+
+/**
+ * What `next` grants that `prev` did not (and vice-versa). Each entry is a
+ * stable string token (e.g. "process", "network:*", "network:api.x.com",
+ * "filesystem:/tmp", "credential:GH_TOKEN"). `widened` = any new grant.
+ */
+export function diffCapabilities(prev, next) {
+  const a = prev || EMPTY_CAPS;
+  const b = next || EMPTY_CAPS;
+  const added = [];
+  const removed = [];
+
+  const boolCap = (key) => {
+    if (b[key] && !a[key]) added.push(key);
+    else if (!b[key] && a[key]) removed.push(key);
+  };
+  boolCap("process");
+  boolCap("mcp");
+  boolCap("monitor");
+
+  // network
+  if (b.network.any && !a.network.any) added.push("network:*");
+  if (!b.network.any && a.network.any) removed.push("network:*");
+  if (!a.network.any) {
+    for (const d of b.network.domains) {
+      if (!a.network.domains.includes(d)) added.push(`network:${d}`);
+    }
+  }
+  for (const d of a.network.domains) {
+    if (!b.network.any && !b.network.domains.includes(d))
+      removed.push(`network:${d}`);
+  }
+
+  const listCap = (key, prefix, pick) => {
+    const av = pick(a);
+    const bv = pick(b);
+    for (const x of bv) if (!av.includes(x)) added.push(`${prefix}:${x}`);
+    for (const x of av) if (!bv.includes(x)) removed.push(`${prefix}:${x}`);
+  };
+  listCap("filesystem", "filesystem", (c) => c.filesystem.roots);
+  listCap("credential", "credential", (c) => c.credential.names);
+
+  return { added, removed, widened: added.length > 0 };
+}
+
+/**
+ * Consent must be re-taken on upgrade when the capability set WIDENS (a new
+ * grant appears). A pure re-install from empty (first install) therefore always
+ * requires consent for whatever it declares.
+ */
+export function consentRequiredForUpgrade({
+  prevCaps = null,
+  nextCaps = null,
+} = {}) {
+  return diffCapabilities(prevCaps, nextCaps).widened;
+}
+
+/** Human-readable lines for an install/upgrade capability prompt. */
+export function describeCapabilities(caps) {
+  const c = caps || EMPTY_CAPS;
+  const lines = [];
+  if (c.process)
+    lines.push("process: may spawn processes / run bundled binaries & hooks");
+  if (c.network.any) lines.push("network: ANY host");
+  else if (c.network.domains.length)
+    lines.push(`network: ${c.network.domains.join(", ")}`);
+  if (c.filesystem.roots.length)
+    lines.push(`filesystem: ${c.filesystem.roots.join(", ")}`);
+  if (c.mcp) lines.push("mcp: may run MCP servers");
+  if (c.monitor) lines.push("monitor: may run background monitors");
+  if (c.credential.names.length)
+    lines.push(`credential: ${c.credential.names.join(", ")}`);
+  return lines;
+}
+
+/**
+ * Catch a manifest whose COMPONENTS need a capability it did not DECLARE — e.g.
+ * ships an MCP server but declared no `mcp`/`network`, or ships bin/hooks/lsp
+ * (which spawn processes) without `process`. Best-effort static check; returns
+ * `[{capability, reason}]`. Callers run it only when a `permissions` block is
+ * present (an undeclared legacy plugin is unrestricted by design).
+ */
+export function auditDeclaredCapabilities(manifest) {
+  const caps = manifest?.capabilities || EMPTY_CAPS;
+  const comp = manifest?.components || {};
+  const findings = [];
+  const has = (v) =>
+    Array.isArray(v)
+      ? v.length > 0
+      : Boolean(v && (v.count || v.file || v.inline));
+
+  const spawns =
+    has(comp.bin) ||
+    has(comp.hooks) ||
+    (Array.isArray(comp.lsp) && comp.lsp.length > 0);
+  if (spawns && !caps.process) {
+    findings.push({
+      capability: "process",
+      reason:
+        "ships bin/hooks/lsp that spawn processes but did not declare the 'process' capability",
+    });
+  }
+  if (has(comp.mcp) && !caps.mcp) {
+    findings.push({
+      capability: "mcp",
+      reason: "ships an MCP server but did not declare the 'mcp' capability",
+    });
+  }
+  if (has(comp.mcp) && !caps.network.any && caps.network.domains.length === 0) {
+    findings.push({
+      capability: "network",
+      reason:
+        "ships an MCP server (which typically needs network) but declared no network domains",
+    });
+  }
+  if (has(comp.monitors) && !caps.monitor) {
+    findings.push({
+      capability: "monitor",
+      reason: "ships monitors but did not declare the 'monitor' capability",
+    });
+  }
+  return findings;
+}
+
+// ─── options schema ─────────────────────────────────────────────────────────
+
+export const OPTION_TYPES = Object.freeze([
+  "string",
+  "number",
+  "boolean",
+  "enum",
+  "string[]",
+]);
+export const OPTION_SCOPES = Object.freeze(["user", "project", "both"]);
+
+/**
+ * Normalize a manifest `optionsSchema` (key → descriptor) into a canonical map.
+ * Unknown types default to "string"; `scope` defaults to "both"; `sensitive`
+ * defaults false. A sensitive option is never allowed at project scope, so its
+ * effective scope is narrowed to "user" here (validateOptions also enforces it).
+ */
+export function normalizeOptionsSchema(raw) {
+  const r = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+  const out = {};
+  for (const [key, descRaw] of Object.entries(r)) {
+    const d = descRaw && typeof descRaw === "object" ? descRaw : {};
+    const type = OPTION_TYPES.includes(d.type) ? d.type : "string";
+    const sensitive = toBool(d.sensitive);
+    let scope = OPTION_SCOPES.includes(d.scope) ? d.scope : "both";
+    if (sensitive && scope !== "user") scope = "user"; // secrets: user scope only
+    out[key] = {
+      type,
+      default: d.default === undefined ? null : d.default,
+      required: toBool(d.required),
+      enum:
+        type === "enum" && Array.isArray(d.enum) ? d.enum.map(String) : null,
+      scope,
+      sensitive,
+      description: typeof d.description === "string" ? d.description : "",
+    };
+  }
+  return out;
+}
+
+/** The default value object for a schema (keys with a non-null default). */
+export function optionDefaults(schema) {
+  const out = {};
+  for (const [key, d] of Object.entries(schema || {})) {
+    if (d.default !== null && d.default !== undefined) out[key] = d.default;
+  }
+  return out;
+}
+
+function coerce(type, value, enumVals) {
+  switch (type) {
+    case "number": {
+      const n = Number(value);
+      return Number.isFinite(n) ? { ok: true, value: n } : { ok: false };
+    }
+    case "boolean": {
+      if (typeof value === "boolean") return { ok: true, value };
+      const s = String(value).trim().toLowerCase();
+      if (["true", "1", "yes"].includes(s)) return { ok: true, value: true };
+      if (["false", "0", "no"].includes(s)) return { ok: true, value: false };
+      return { ok: false };
+    }
+    case "enum":
+      return enumVals && enumVals.includes(String(value))
+        ? { ok: true, value: String(value) }
+        : { ok: false };
+    case "string[]": {
+      if (Array.isArray(value)) return { ok: true, value: value.map(String) };
+      if (typeof value === "string") return { ok: true, value: toList(value) };
+      return { ok: false };
+    }
+    default:
+      return { ok: true, value: String(value) };
+  }
+}
+
+/**
+ * Validate a values object against an options schema at a given scope. Enforces
+ * types, `required`, `enum`, per-option `scope`, and the SENSITIVE-not-from-
+ * project invariant. Returns the merged/coerced values plus errors/warnings —
+ * never throws.
+ *
+ * @param {object} schema   from normalizeOptionsSchema
+ * @param {object} values   the config values to check
+ * @param {object} [opts]   { scope: 'user'|'project' }
+ * @returns {{ok:boolean, errors:string[], warnings:string[], normalized:object}}
+ */
+export function validateOptions(schema, values, { scope = "user" } = {}) {
+  const s = schema || {};
+  const v = values && typeof values === "object" ? values : {};
+  const errors = [];
+  const warnings = [];
+  const normalized = optionDefaults(s);
+
+  for (const [key, d] of Object.entries(s)) {
+    const provided = Object.prototype.hasOwnProperty.call(v, key);
+    if (!provided) {
+      if (d.required && normalized[key] === undefined) {
+        errors.push(`missing required option "${key}"`);
+      }
+      continue;
+    }
+    // sensitive secrets can never come from a project-scoped config file.
+    if (d.sensitive && scope === "project") {
+      errors.push(
+        `option "${key}" is sensitive and cannot be set from project config — use user scope / OS keychain`,
+      );
+      continue;
+    }
+    // a user-only option may not be set at project scope.
+    if (d.scope === "user" && scope === "project") {
+      errors.push(
+        `option "${key}" is user-scoped and cannot be set from project config`,
+      );
+      continue;
+    }
+    if (d.scope === "project" && scope === "user") {
+      warnings.push(
+        `option "${key}" is project-scoped; a user value may be ignored`,
+      );
+    }
+    const c = coerce(d.type, v[key], d.enum);
+    if (!c.ok) {
+      errors.push(
+        `option "${key}" must be ${d.type}${d.enum ? ` (${d.enum.join("|")})` : ""}`,
+      );
+      continue;
+    }
+    normalized[key] = c.value;
+  }
+
+  for (const key of Object.keys(v)) {
+    if (!Object.prototype.hasOwnProperty.call(s, key)) {
+      warnings.push(`unknown option "${key}" (not in optionsSchema)`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings, normalized };
+}
+
+/** Clone `values` with every schema-declared sensitive key masked. */
+export function redactSensitiveOptions(schema, values) {
+  const s = schema || {};
+  const out = {};
+  for (const [key, val] of Object.entries(values || {})) {
+    out[key] = s[key]?.sensitive ? "***" : val;
+  }
+  return out;
+}