heyspex 0.1.0 → 0.2.0

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

@@ -29,10 +29,72 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
 
 import { yamlScalar } from './yaml-scalar.mjs';
+import { getSettingEntry, SETTINGS_REGISTRY } from './settings-registry.mjs';
+import { listTrustedFolders, readTrustStore, trustStorePath } from './folder-trust-store.mjs';
 
 export const CONFIG_REL = path.join('.heyspex', 'config.yaml');
+
+/**
+ * The seed template a vault's `.heyspex/config.yaml` is created from when it is
+ * missing ([[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]] fix 3).
+ * Ships in the npm package next to this module (`package.json` `files`), so a
+ * published install seeds the same defaults a source checkout does. `hs init`
+ * seeds from the same file; the settings core seeds on the FIRST WRITE only —
+ * reads (`listConfigLeaves` / `getConfigLeaf`) never create files.
+ */
+export const CONFIG_SEED_PATH = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  'config-seed.yaml',
+);
+
+/** The seed template's text. Throws only if the package itself is broken. */
+export function readConfigSeed() {
+  return fs.readFileSync(CONFIG_SEED_PATH, 'utf8');
+}
+
+/**
+ * The one non-scalar, non-`.heyspex/config.yaml` COMPUTED key the settings capability exposes
+ * ([[HS-25AJ-8CMW-TASK-folder-trust-revoke-through-the]], agent-settings-protocol.md): the list
+ * of `hs chat`/`spexcode` folder-trust decisions, sourced live from the machine-local
+ * `~/.heyspex/trusted-folders.json` store (`folder-trust-store.mjs` — the SAME read primitive
+ * `spex-console/src/lib/cli/folder-trust.ts` re-exports for `hs trust list`). READ-ONLY: writes
+ * are refused in both `requestSettingsWrite` (MCP two-step) and `setConfigLeaf` (the CLI's
+ * direct-write path) — see each function below. Never reads or writes config.yaml for this key.
+ *
+ * Why the core hosts a computed key rather than distorting itself around one: this module's
+ * entire model — `listConfigLeaves`/`getConfigLeaf`/`setConfigLeaf` — is a scalar-leaf scan and
+ * surgical single-line rewrite of ONE git-tracked YAML file. `trusted_folders` is a LIST of
+ * records (path/trusted/decidedAt) sourced from a DIFFERENT, machine-local, never-git-tracked
+ * JSON file — hosting a `…trusted_folders.revoke = <path>` WRITE through the two-step confirm
+ * store would mean that store's pending-write record and audit row both lie about writing to
+ * config.yaml (they don't — a revoke deletes an entry from trusted-folders.json). So the read
+ * is computed here (small, honest addition), but the write stays CLI-only (`hs trust revoke
+ * <path>`), documented as the task's AC2 explicitly allows.
+ */
+export const TRUSTED_FOLDERS_KEY = 'agent_behaviors.spexcode.trusted_folders';
+
+function isTrustedFoldersKey(key) {
+  return key === TRUSTED_FOLDERS_KEY || key.startsWith(TRUSTED_FOLDERS_KEY + '.');
+}
+
+/** Shared refusal for both write entry points (`setConfigLeaf`'s direct/CLI path and
+ *  `requestSettingsWrite`'s MCP two-step path) — `null` when `key` isn't governed by this
+ *  computed key, so callers can `return refusal ?? ...normal flow`. */
+function refuseTrustedFoldersWrite(key) {
+  if (!isTrustedFoldersKey(key)) return null;
+  return {
+    ok: false,
+    error: 'read_only_computed_key',
+    message:
+      `"${key}" is a read-only computed key — it is sourced live from the machine-local hs ` +
+      `trust store (${trustStorePath()}), never from .heyspex/config.yaml, and settings writes ` +
+      'are not supported here. Run "hs trust revoke <path>" instead — it clears one folder; ' +
+      'omit <path> to clear the current folder.',
+  };
+}
 export const SETTINGS_AUDIT_REL = path.join('.heyspex', 'settings-history.jsonl');
 export const PENDING_WRITE_REL = path.join('.heyspex', 'settings-write-pending.json');
 
@@ -60,6 +122,82 @@ export function validateSettingKey(key) {
   return { ok: true };
 }
 
+// ── registry-backed write validation (HS-WH06, HS-JXT9) ─────────────────────
+//
+// The registry (`vendor/heyspex-mcp/settings-registry.mjs`) currently declares
+// only the `close_out.*` namespace. Validation below applies ONLY to a key whose
+// top-level segment the registry governs — a key in an ungoverned namespace
+// (`mvp_mode.*`, `agent_behaviors.*`, …) keeps its pre-registry freeform write
+// behavior unchanged. This keeps the epic's scope to "close-out settings" without
+// silently locking down every other setting the registry has not been taught yet
+// ([[HS-KW38-15XI-EPIC-settings-registry-core]] scope).
+
+/** Top-level key segments the registry declares at least one entry for. */
+const REGISTRY_GOVERNED_PREFIXES = new Set(
+  SETTINGS_REGISTRY.map((entry) => entry.key.split('.')[0]),
+);
+
+function isRegistryGoverned(key) {
+  return REGISTRY_GOVERNED_PREFIXES.has(key.split('.')[0]);
+}
+
+/** Human-readable description of what `entry` accepts, for a refusal message. */
+function describeExpectedSettingValue(entry) {
+  if (entry.type === 'enum') return `one of: ${entry.values.join(', ')}`;
+  if (entry.type === 'boolean') return 'a boolean (true or false)';
+  return 'a string';
+}
+
+/** True when `value` matches the type/allowed-values `entry` declares. */
+function settingValueMatchesEntry(entry, value) {
+  if (entry.type === 'boolean') return typeof value === 'boolean';
+  if (entry.type === 'enum') return typeof value === 'string' && entry.values.includes(value);
+  if (entry.type === 'string') return typeof value === 'string';
+  return true;
+}
+
+/**
+ * Validate a proposed write against the settings registry, ahead of any file or
+ * audit-log write. Only applies within a registry-governed namespace (see above);
+ * a key outside it always passes through with `{ ok: true }`.
+ *
+ * Refuses, in order:
+ *   1. a key the registry does not declare (`unknown_setting`);
+ *   2. any change to an entry marked `enforced`, regardless of who the caller is —
+ *      there is no admin bypass (`enforced_setting`);
+ *   3. a value whose type doesn't match the entry, or that falls outside the
+ *      entry's declared `values` list (`invalid_setting_value`) — names the
+ *      setting, the value given, and what was expected.
+ *
+ * Returns `{ ok: true }` or `{ ok: false, error, message }`. Never touches disk.
+ */
+export function validateSettingWrite(key, value) {
+  if (typeof key !== 'string' || !isRegistryGoverned(key)) return { ok: true };
+  const entry = getSettingEntry(key);
+  if (!entry) {
+    return {
+      ok: false,
+      error: 'unknown_setting',
+      message: `"${key}" is not a setting declared in the settings registry — refusing to write an unknown key.`,
+    };
+  }
+  if (entry.enforced) {
+    return {
+      ok: false,
+      error: 'enforced_setting',
+      message: `"${key}" is a hard rule and cannot be changed by anyone, including an administrator (${entry.description})`,
+    };
+  }
+  if (!settingValueMatchesEntry(entry, value)) {
+    return {
+      ok: false,
+      error: 'invalid_setting_value',
+      message: `"${key}" was given ${JSON.stringify(value)}, but expected ${describeExpectedSettingValue(entry)}.`,
+    };
+  }
+  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.
@@ -92,6 +230,72 @@ function readRaw(repoRoot, options = {}) {
   }
 }
 
+function isExistingDirectory(dir) {
+  try {
+    return typeof dir === 'string' && dir.length > 0 && fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Make sure `<repoRoot>/.heyspex/` exists ahead of a write into it. Only ever
+ * creates the `.heyspex/` directory INSIDE an existing vault root — never the
+ * vault root itself (a typo'd `HS_VAULT_ROOT` must not grow a `.heyspex/` tree
+ * in a path that does not exist). Returns false when `repoRoot` is not an
+ * existing directory or the mkdir fails.
+ */
+function ensureHeyspexDir(repoRoot) {
+  if (!isExistingDirectory(repoRoot)) return false;
+  try {
+    fs.mkdirSync(path.join(repoRoot, '.heyspex'), { recursive: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Seed a MISSING config file from the template ([[HS-4C76-9W86-DIAG]] fix 3).
+ * Returns `{ ok: true, raw }` with the seeded text, or `{ ok: false, error,
+ * message }` when seeding is not allowed / fails. Refuses (keeps the historic
+ * `config_unreadable` contract) when:
+ *   - `repoRoot` is not an existing directory — never mkdir a vault into a
+ *     path that does not exist;
+ *   - the file EXISTS but could not be read (permissions, a directory at that
+ *     path…) — seeding over it would silently destroy the user's settings.
+ */
+function seedMissingConfig(repoRoot, file) {
+  if (fs.existsSync(file)) {
+    return { ok: false, error: 'config_unreadable', message: `${file} exists but is unreadable` };
+  }
+  if (!isExistingDirectory(repoRoot)) {
+    return {
+      ok: false,
+      error: 'config_unreadable',
+      message: `${file} not found and its vault root ${repoRoot} does not exist — refusing to create a vault there. Run \`hs init\` in the directory that should become the vault.`,
+    };
+  }
+  let seed;
+  try {
+    seed = readConfigSeed();
+  } catch (err) {
+    return { ok: false, error: 'seed_unreadable', message: `config seed template ${CONFIG_SEED_PATH} could not be read: ${String(err?.message ?? err)}` };
+  }
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    // 'wx' — create only; if a concurrent writer beat us to it, read theirs.
+    fs.writeFileSync(file, seed, { encoding: 'utf8', flag: 'wx' });
+  } catch (err) {
+    if (err?.code === 'EEXIST') {
+      const raced = readRaw(repoRoot, { configPath: file });
+      if (raced !== null) return { ok: true, raw: raced, seeded: false };
+    }
+    return { ok: false, error: 'write_failed', message: `could not seed ${file}: ${String(err?.message ?? err)}` };
+  }
+  return { ok: true, raw: seed, seeded: true };
+}
+
 /**
  * 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
@@ -177,6 +381,50 @@ export function getConfigLeaf(repoRoot, key, options = {}) {
   return { key, found: true, raw: hit, value: parseScalar(hit) };
 }
 
+/**
+ * Resolve the effective value of one setting through the registry-aware read
+ * chain ([[HS-FCF5-15XI-RES-user-editable-close-out-settings-with]] §"One-time
+ * bypass resolve order"):
+ *   1. (future) a one-time command-line flag override — NOT implemented here; a
+ *      later epic (the `hs close` one-time flag layer) adds it above the file
+ *      value. This function's `source` field leaves room for a `'flag'` value
+ *      without changing its shape.
+ *   2. the file's value in `.heyspex/config.yaml`, when the key is present.
+ *   3. the registry's shipped default (`vendor/heyspex-mcp/settings-registry.mjs`),
+ *      when the key is a declared registry entry and the file has no value.
+ * A key that is neither present in the file nor declared in the registry resolves
+ * to `source: 'absent'` with a null value — unchanged from the pre-registry
+ * behavior of `getConfigLeaf`.
+ *
+ * `found` keeps `getConfigLeaf`'s existing meaning (present in the file) so
+ * existing callers of that lower-level function are unaffected; this function is
+ * the one the CLI/MCP/console faces are meant to resolve reads through instead of
+ * each rolling their own fallback (a later task in
+ * [[HS-KW38-15XI-EPIC-settings-registry-core]] wires them up).
+ *
+ * @returns {{ key: string, value: *, found: boolean, source: 'file'|'registry_default'|'absent' }}
+ */
+export function getEffectiveSetting(repoRoot, key, options = {}) {
+  // Computed key — answered from the machine-local trust store, NEVER from config.yaml (see
+  // TRUSTED_FOLDERS_KEY's doc comment above). Only the exact key resolves; a deeper child (e.g.
+  // "…trusted_folders.revoke") falls through to the normal absent handling below.
+  // `options.trustStorePath` is a test-only override (mirrors `options.configPath` elsewhere in
+  // this module) — every real caller omits it and reads the real `~/.heyspex/trusted-folders.json`.
+  if (key === TRUSTED_FOLDERS_KEY) {
+    const value = listTrustedFolders(readTrustStore(options.trustStorePath));
+    return { key, value, found: true, source: 'computed' };
+  }
+  const fileLeaf = getConfigLeaf(repoRoot, key, options);
+  if (fileLeaf.found) {
+    return { key, value: fileLeaf.value, found: true, source: 'file' };
+  }
+  const entry = getSettingEntry(key);
+  if (entry) {
+    return { key, value: entry.default, found: false, source: 'registry_default' };
+  }
+  return { key, value: null, found: false, source: 'absent' };
+}
+
 /** Append one row to the settings audit log. Fail-safe: never throws. */
 export function appendSettingsAudit(repoRoot, row) {
   try {
@@ -200,21 +448,41 @@ export function appendSettingsAudit(repoRoot, row) {
  * 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 }.
+ * Returns { ok, key, previous, value, created, audited } or { ok:false, error }.
  * Appends a `settings.write` audit row on success (meta: { actor, face }).
+ * `audited` is the MEASURED result of that append — false means the config write
+ * landed but the audit trail did not, which callers must report as a partial.
+ *
+ * SELF-HEALS a missing file ([[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]
+ * fix 3): when `.heyspex/config.yaml` does not exist under an EXISTING vault root,
+ * it is created from `config-seed.yaml` first and the write lands on that seeded
+ * text; the result and the audit row then carry `seeded: true`. A vault root that
+ * does not exist, or a file that exists but is unreadable, still refuses with
+ * `config_unreadable` — seeding never creates a vault and never overwrites.
  */
 export function setConfigLeaf(repoRoot, key, value, meta = {}, options = {}) {
   const check = validateSettingKey(key);
   if (!check.ok) return { ok: false, error: 'invalid_key', message: check.reason };
+  const trustedFoldersRefusal = refuseTrustedFoldersWrite(key);
+  if (trustedFoldersRefusal) return trustedFoldersRefusal;
+  const registryCheck = validateSettingWrite(key, value);
+  if (!registryCheck.ok) return registryCheck;
   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);
+  let raw = readRaw(repoRoot, options);
+  let seeded = false;
   if (raw === null) {
-    return { ok: false, error: 'config_unreadable', message: `${file} not found or unreadable` };
+    const seedResult = seedMissingConfig(repoRoot, file);
+    if (!seedResult.ok) return seedResult;
+    raw = seedResult.raw;
+    seeded = seedResult.seeded === true;
   }
+  // Only present on the row/result when a seed actually happened — an existing
+  // file's write result and audit row keep their exact pre-existing shape.
+  const seededFields = seeded ? { seeded: true } : {};
 
   const eol = raw.includes('\r\n') ? '\r\n' : '\n';
   const lines = raw.split(/\r?\n/);
@@ -277,14 +545,19 @@ export function setConfigLeaf(repoRoot, key, value, meta = {}, options = {}) {
     } catch (err) {
       return { ok: false, error: 'write_failed', message: String(err?.message ?? err) };
     }
-    appendSettingsAudit(repoRoot, {
+    // `appendSettingsAudit` is fail-safe and returns FALSE on an append that did
+    // not land; that boolean used to be discarded, so every face reported the
+    // write as "applied and audited" over a missing audit row
+    // ([[HS-IOJW-5YDH-DIAG]] sweep: report the result, not the request).
+    const audited = appendSettingsAudit(repoRoot, {
       key,
       previous,
       value,
       actor: meta.actor ?? 'unknown',
       face: meta.face ?? 'unknown',
+      ...seededFields,
     });
-    return { ok: true, key, previous, value, created: false };
+    return { ok: true, key, previous, value, created: false, audited, ...seededFields };
   }
 
   // Insert. Build the missing chain below the deepest existing ancestor.
@@ -318,14 +591,15 @@ export function setConfigLeaf(repoRoot, key, value, meta = {}, options = {}) {
   } catch (err) {
     return { ok: false, error: 'write_failed', message: String(err?.message ?? err) };
   }
-  appendSettingsAudit(repoRoot, {
+  const audited = appendSettingsAudit(repoRoot, {
     key,
     previous: null,
     value,
     actor: meta.actor ?? 'unknown',
     face: meta.face ?? 'unknown',
+    ...seededFields,
   });
-  return { ok: true, key, previous: null, value, created: true };
+  return { ok: true, key, previous: null, value, created: true, audited, ...seededFields };
 }
 
 // ── two-step confirm store (the MCP write-permission handshake) ─────────────
@@ -357,10 +631,19 @@ export function peekPendingWrite(repoRoot) {
 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 };
+  const trustedFoldersRefusal = refuseTrustedFoldersWrite(key);
+  if (trustedFoldersRefusal) return trustedFoldersRefusal;
+  const registryCheck = validateSettingWrite(key, value);
+  if (!registryCheck.ok) return registryCheck;
   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);
+  // A fresh vault may have no `.heyspex/` directory yet (HS-4C76): the pending
+  // record and the request audit row both live there, so create the directory
+  // now — inside an EXISTING vault root only (see ensureHeyspexDir). The config
+  // file itself is NOT created here; that happens on confirm, via setConfigLeaf.
+  ensureHeyspexDir(repoRoot);
   const token = crypto.randomBytes(6).toString('hex');
   const record = {
     token,