heyspex 0.1.0

package/vendor/heyspex-mcp/config-settings.mjs

@@ -0,0 +1,419 @@
+/**
+ * HeySpex settings core — the ONE module that reads and writes scalar values in
+ * `.heyspex/config.yaml` by dotted key (e.g. `agent_behaviors.capture_on_idea.enabled`).
+ *
+ * Three-faces principle ([[capability-three-faces-no-per-capability-slash]]): this is
+ * the core; the faces delegate to it —
+ *   - `hs settings list|get|set`            (CLI face, scripts/hs-settings.mjs)
+ *   - `heyspex_settings_list|get|set`       (MCP face, settings-tools.mjs → cli.mjs)
+ *   - `GET/PUT /api/agent-behaviors`        (console face, spex-console lib delegates here)
+ * The read-only hook loader (`scripts/claude-hooks/_guardrail-loader.mjs`) keeps its
+ * own tiny reader on purpose — hooks predate this module and must stay standalone —
+ * but both use the identical indent-scoped scan so the semantics match.
+ *
+ * WRITE-PERMISSION GUARDRAIL (owner directive 2026-07-11): settings WRITES are a
+ * protected class. Reads are open; no agent or MCP/agentic process may change a
+ * setting without EXPLICIT user permission — regardless of the global
+ * `ask_forgiveness_not_permission` switch (that switch governs behaviors, not its
+ * own controls). This module supplies the two-step confirm store
+ * (`requestSettingsWrite` → `confirmSettingsWrite`) that the MCP face uses, and the
+ * audit trail (`.heyspex/settings-history.jsonl`) every face appends to. The
+ * PreToolUse gate (`scripts/claude-hooks/settings-write-gate.mjs`) enforces the same
+ * rule on direct file edits. Documented in specs/protocols/agent-settings-protocol.md.
+ *
+ * DEPENDENCY-FREE: Node stdlib only (no js-yaml — same rationale as yaml-scalar.mjs).
+ * Comment lines and unrelated content in config.yaml are preserved byte-for-byte;
+ * writes are surgical single-line rewrites/inserts.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+import { yamlScalar } from './yaml-scalar.mjs';
+
+export const CONFIG_REL = path.join('.heyspex', 'config.yaml');
+export const SETTINGS_AUDIT_REL = path.join('.heyspex', 'settings-history.jsonl');
+export const PENDING_WRITE_REL = path.join('.heyspex', 'settings-write-pending.json');
+
+/** How long a requested-but-unconfirmed write stays valid. */
+export const PENDING_WRITE_TTL_MS = 10 * 60 * 1000;
+
+const KEY_RE = /^[A-Za-z0-9_]+(\.[A-Za-z0-9_]+){0,5}$/;
+
+export function configPath(repoRoot, options = {}) {
+  return options.configPath || path.join(repoRoot, CONFIG_REL);
+}
+
+/** Validate a dotted settings key. Returns { ok } or { ok:false, reason }. */
+export function validateSettingKey(key) {
+  if (typeof key !== 'string' || !key.trim()) {
+    return { ok: false, reason: 'key must be a non-empty string' };
+  }
+  if (!KEY_RE.test(key.trim())) {
+    return {
+      ok: false,
+      reason:
+        'key must be dotted segments of letters/digits/underscores, at most 6 levels (e.g. agent_behaviors.capture_on_idea.enabled)',
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Parse a raw YAML scalar string into a JS value (boolean/number/null/string).
+ * Quoted strings are unquoted; anything else stays a string.
+ */
+export function parseScalar(raw) {
+  if (raw === undefined || raw === null) return null;
+  const v = String(raw).trim();
+  if (v === '' || v === 'null' || v === '~') return null;
+  const low = v.toLowerCase();
+  if (low === 'true' || low === 'yes') return true;
+  if (low === 'false' || low === 'no') return false;
+  if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v);
+  const m = v.match(/^"(.*)"$/) || v.match(/^'(.*)'$/);
+  if (m) return m[1];
+  return v;
+}
+
+/** Serialize a JS scalar for a YAML `key: value` line. */
+export function serializeScalar(value) {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'boolean' || typeof value === 'number') return String(value);
+  return yamlScalar(value);
+}
+
+function readRaw(repoRoot, options = {}) {
+  try {
+    return fs.readFileSync(configPath(repoRoot, options), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Walk config.yaml lines maintaining an indent-scoped key path (the same scan the
+ * hook loader uses). Calls `visit({ pathHere, key, indent, rawValue, lineIdx })` for
+ * every `key:` line. Never throws.
+ */
+function scanLines(lines, visit) {
+  const stack = []; // { key, indent }
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const m = trimmed.match(/^([A-Za-z0-9_]+)\s*:(.*)$/);
+    if (!m) continue;
+    const indent = line.length - line.trimStart().length;
+    while (stack.length && stack[stack.length - 1].indent >= indent) stack.pop();
+    stack.push({ key: m[1], indent });
+    const stop = visit({
+      pathHere: stack.map((f) => f.key),
+      key: m[1],
+      indent,
+      rawValue: stripTrailingComment(m[2]),
+      lineIdx: i,
+    });
+    if (stop === true) return;
+  }
+}
+
+/** Drop a trailing ` # comment` from a scalar value (quote-aware enough for our file). */
+function stripTrailingComment(raw) {
+  const v = String(raw ?? '').trim();
+  if (!v) return v;
+  if (v.startsWith('"') || v.startsWith("'")) return v; // keep quoted values intact
+  const hash = v.indexOf(' #');
+  return hash === -1 ? v : v.slice(0, hash).trim();
+}
+
+/**
+ * All scalar leaves as [{ key, value, raw }], dotted-key sorted by file order.
+ * A `key:` line with an empty value followed by deeper lines is a block, not a leaf.
+ */
+export function listConfigLeaves(repoRoot, options = {}) {
+  const raw = readRaw(repoRoot, options);
+  if (raw === null) return [];
+  const lines = raw.split(/\r?\n/);
+  const entries = [];
+  scanLines(lines, ({ pathHere, rawValue, lineIdx, indent }) => {
+    if (rawValue !== '') {
+      entries.push({ key: pathHere.join('.'), raw: rawValue, value: parseScalar(rawValue) });
+      return;
+    }
+    // Empty value: block header unless nothing deeper follows (then it's a null leaf).
+    for (let j = lineIdx + 1; j < lines.length; j++) {
+      const t = lines[j].trim();
+      if (!t || t.startsWith('#')) continue;
+      const childIndent = lines[j].length - lines[j].trimStart().length;
+      if (childIndent > indent) return; // block header — skip
+      break;
+    }
+    entries.push({ key: pathHere.join('.'), raw: '', value: null });
+  });
+  return entries;
+}
+
+/**
+ * Read one scalar leaf. Returns { key, found, raw, value }.
+ * `found:false` when the path is absent or the config file is unreadable.
+ */
+export function getConfigLeaf(repoRoot, key, options = {}) {
+  const check = validateSettingKey(key);
+  if (!check.ok) return { key, found: false, raw: null, value: null, error: check.reason };
+  const raw = readRaw(repoRoot, options);
+  if (raw === null) return { key, found: false, raw: null, value: null };
+  const segments = key.trim().split('.');
+  let hit = null;
+  scanLines(raw.split(/\r?\n/), ({ pathHere, rawValue }) => {
+    if (pathHere.length === segments.length && pathHere.every((k, i) => k === segments[i])) {
+      hit = rawValue;
+      return true;
+    }
+    return false;
+  });
+  if (hit === null) return { key, found: false, raw: null, value: null };
+  return { key, found: true, raw: hit, value: parseScalar(hit) };
+}
+
+/** Append one row to the settings audit log. Fail-safe: never throws. */
+export function appendSettingsAudit(repoRoot, row) {
+  try {
+    const full = {
+      timestamp: new Date().toISOString(),
+      event_kind: 'settings.write',
+      actor: 'unknown',
+      face: 'unknown',
+      ...row,
+    };
+    fs.appendFileSync(path.join(repoRoot, SETTINGS_AUDIT_REL), JSON.stringify(full) + '\n');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Surgically set one scalar leaf. Rewrites the existing `key:` line in place, or
+ * inserts the missing key (and any missing intermediate blocks) at the correct
+ * indent, after the last line of the deepest existing ancestor's block. Preserves
+ * every other line (comments included) byte-for-byte.
+ *
+ * Returns { ok, key, previous, value, created } or { ok:false, error }.
+ * Appends a `settings.write` audit row on success (meta: { actor, face }).
+ */
+export function setConfigLeaf(repoRoot, key, value, meta = {}, options = {}) {
+  const check = validateSettingKey(key);
+  if (!check.ok) return { ok: false, error: 'invalid_key', message: check.reason };
+  if (value !== null && !['string', 'number', 'boolean'].includes(typeof value)) {
+    return { ok: false, error: 'invalid_value', message: 'value must be a scalar (string, number, boolean, or null)' };
+  }
+
+  const file = configPath(repoRoot, options);
+  const raw = readRaw(repoRoot, options);
+  if (raw === null) {
+    return { ok: false, error: 'config_unreadable', message: `${file} not found or unreadable` };
+  }
+
+  const eol = raw.includes('\r\n') ? '\r\n' : '\n';
+  const lines = raw.split(/\r?\n/);
+  const segments = key.trim().split('.');
+
+  // Locate the target line, the deepest existing ancestor, and (for insertion) the
+  // end of that ancestor's block.
+  let targetLineIdx = -1;
+  let targetRaw = null;
+  let ancestorDepth = 0; // how many leading segments already exist as a chain
+  let ancestorLineIdx = -1;
+  let ancestorIndent = -1;
+  scanLines(lines, ({ pathHere, rawValue, lineIdx, indent }) => {
+    const depth = pathHere.length;
+    if (depth <= segments.length && pathHere.every((k, i) => k === segments[i])) {
+      if (depth === segments.length) {
+        targetLineIdx = lineIdx;
+        targetRaw = rawValue;
+        return true;
+      }
+      if (depth > ancestorDepth) {
+        ancestorDepth = depth;
+        ancestorLineIdx = lineIdx;
+        ancestorIndent = indent;
+      }
+    }
+    return false;
+  });
+
+  const serialized = serializeScalar(value);
+
+  if (targetLineIdx >= 0) {
+    // The target exists. Refuse to overwrite a block header (a key with children).
+    if (targetRaw === '') {
+      for (let j = targetLineIdx + 1; j < lines.length; j++) {
+        const t = lines[j].trim();
+        if (!t || t.startsWith('#')) continue;
+        const childIndent = lines[j].length - lines[j].trimStart().length;
+        const targetIndent = lines[targetLineIdx].length - lines[targetLineIdx].trimStart().length;
+        if (childIndent > targetIndent) {
+          return {
+            ok: false,
+            error: 'not_scalar',
+            message: `"${key}" is a block with nested keys, not a scalar setting — set one of its leaves instead`,
+          };
+        }
+        break;
+      }
+    }
+    const line = lines[targetLineIdx];
+    const colonIdx = line.indexOf(':');
+    // Preserve any trailing comment on the same line.
+    const after = line.slice(colonIdx + 1);
+    const commentMatch = after.match(/\s#\s.*$/);
+    const trailingComment = commentMatch && !stripTrailingComment(after).startsWith('"') ? commentMatch[0] : '';
+    lines[targetLineIdx] = `${line.slice(0, colonIdx + 1)} ${serialized}${trailingComment}`;
+    const previous = parseScalar(targetRaw);
+    try {
+      fs.writeFileSync(file, lines.join(eol), 'utf8');
+    } catch (err) {
+      return { ok: false, error: 'write_failed', message: String(err?.message ?? err) };
+    }
+    appendSettingsAudit(repoRoot, {
+      key,
+      previous,
+      value,
+      actor: meta.actor ?? 'unknown',
+      face: meta.face ?? 'unknown',
+    });
+    return { ok: true, key, previous, value, created: false };
+  }
+
+  // Insert. Build the missing chain below the deepest existing ancestor.
+  // Indent convention in this file: 2 spaces per nesting level.
+  let insertAfter;
+  if (ancestorLineIdx >= 0) {
+    // Find the last line inside the ancestor's block (skip trailing blank/comment runs).
+    insertAfter = ancestorLineIdx;
+    for (let j = ancestorLineIdx + 1; j < lines.length; j++) {
+      const t = lines[j].trim();
+      if (!t || t.startsWith('#')) continue;
+      const lineIndent = lines[j].length - lines[j].trimStart().length;
+      if (lineIndent <= ancestorIndent) break;
+      insertAfter = j;
+    }
+  } else {
+    // No ancestor at all — append at end of file (after trimming trailing blanks).
+    insertAfter = lines.length - 1;
+    while (insertAfter > 0 && lines[insertAfter].trim() === '') insertAfter--;
+  }
+
+  const newLines = [];
+  for (let depth = ancestorDepth; depth < segments.length; depth++) {
+    const indent = ' '.repeat(2 * depth);
+    const isLeaf = depth === segments.length - 1;
+    newLines.push(`${indent}${segments[depth]}:${isLeaf ? ` ${serialized}` : ''}`);
+  }
+  lines.splice(insertAfter + 1, 0, ...newLines);
+  try {
+    fs.writeFileSync(file, lines.join(eol), 'utf8');
+  } catch (err) {
+    return { ok: false, error: 'write_failed', message: String(err?.message ?? err) };
+  }
+  appendSettingsAudit(repoRoot, {
+    key,
+    previous: null,
+    value,
+    actor: meta.actor ?? 'unknown',
+    face: meta.face ?? 'unknown',
+  });
+  return { ok: true, key, previous: null, value, created: true };
+}
+
+// ── two-step confirm store (the MCP write-permission handshake) ─────────────
+//
+// An agentic settings write is a two-call flow:
+//   1. requestSettingsWrite → records the proposed change and returns a token; the
+//      caller MUST show the user the exact change and get explicit approval.
+//   2. confirmSettingsWrite(token) → applies the change only while the token is
+//      valid (10-minute expiry, single pending slot — a new request replaces it).
+// The token proves call-two refers to the exact reviewed change; the PreToolUse
+// gate additionally routes the confirm call through the harness permission prompt.
+
+function pendingPath(repoRoot) {
+  return path.join(repoRoot, PENDING_WRITE_REL);
+}
+
+export function peekPendingWrite(repoRoot) {
+  try {
+    const raw = fs.readFileSync(pendingPath(repoRoot), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || !parsed.token) return null;
+    if (Date.parse(parsed.expires_at) < Date.now()) return null; // expired
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function requestSettingsWrite(repoRoot, { key, value, actor, face } = {}, options = {}) {
+  const check = validateSettingKey(key);
+  if (!check.ok) return { ok: false, error: 'invalid_key', message: check.reason };
+  if (value !== null && !['string', 'number', 'boolean'].includes(typeof value)) {
+    return { ok: false, error: 'invalid_value', message: 'value must be a scalar (string, number, boolean, or null)' };
+  }
+  const current = getConfigLeaf(repoRoot, key, options);
+  const token = crypto.randomBytes(6).toString('hex');
+  const record = {
+    token,
+    key,
+    value,
+    current_value: current.found ? current.value : null,
+    current_found: current.found,
+    requested_by: actor ?? 'unknown',
+    face: face ?? 'unknown',
+    requested_at: new Date().toISOString(),
+    expires_at: new Date(Date.now() + PENDING_WRITE_TTL_MS).toISOString(),
+  };
+  try {
+    fs.writeFileSync(pendingPath(repoRoot), JSON.stringify(record, null, 2) + '\n', 'utf8');
+  } catch (err) {
+    return { ok: false, error: 'pending_write_failed', message: String(err?.message ?? err) };
+  }
+  appendSettingsAudit(repoRoot, {
+    event_kind: 'settings.write_requested',
+    key,
+    previous: record.current_value,
+    value,
+    actor: actor ?? 'unknown',
+    face: face ?? 'unknown',
+  });
+  return { ok: true, ...record };
+}
+
+export function confirmSettingsWrite(repoRoot, { token, actor, face } = {}, options = {}) {
+  if (typeof token !== 'string' || !token.trim()) {
+    return { ok: false, error: 'missing_token', message: 'confirm_token is required to apply a settings write' };
+  }
+  const pending = peekPendingWrite(repoRoot);
+  if (!pending) {
+    return {
+      ok: false,
+      error: 'no_pending_write',
+      message: 'No valid pending settings write (never requested, already applied, or expired after 10 minutes). Request again.',
+    };
+  }
+  if (pending.token !== token.trim()) {
+    return { ok: false, error: 'token_mismatch', message: 'confirm_token does not match the pending settings write' };
+  }
+  const result = setConfigLeaf(repoRoot, pending.key, pending.value, {
+    actor: actor ?? pending.requested_by,
+    face: face ?? pending.face,
+  }, options);
+  if (result.ok) {
+    try {
+      fs.unlinkSync(pendingPath(repoRoot));
+    } catch {
+      /* already gone — fine */
+    }
+  }
+  return result;
+}