heyspex 0.1.0

package/vendor/heyspex-mcp/vault-resolve.mjs

@@ -0,0 +1,297 @@
+/**
+ * vault-resolve.mjs — the MCP-side port of the console's active-vault resolver.
+ *
+ * Mirrors `spex-console/src/lib/vault-resolve/index.ts` (`resolveActiveVaultRoot`)
+ * so that, given the same registry/env state, the MCP face and the console face
+ * agree on which vault is active (same repo root; specs dir = repoRoot/specs).
+ * Replaces the divergent one-line resolution that used to live in `cli.mjs`
+ * `getConfig()` (`HEYSPEX_VAULT_ROOT || CLAUDE_PROJECT_DIR || cwd`) and the
+ * `hooks-engine.mjs` fallback (`HEYSPEX_VAULT_ROOT || cwd`). Convergence tracked
+ * under [[HS-ICDI-TASK]] / [[HS-PNH2-RES]].
+ *
+ * Pure Node ESM — only node:fs / node:path / node:os. NO import from
+ * spex-console, no TypeScript. The MCP process is standalone (Neon /
+ * DATABASE_URL may be absent), so this port does NOT make a network/account
+ * lookup. Instead it reads the offline registry file
+ * (`~/.heyspex/registry.json`, same shape as
+ * `spex-console/src/lib/vault-registry/registry-file.ts`) for tier-1
+ * (explicit vaultId) and tier-4 (the offline active-vault pointer). That
+ * offline pointer is how an MCP restart picks up a CLI `hs vault use` switch
+ * without Neon.
+ *
+ * Precedence stack (highest wins) — REORDERED by [[HS-C87T-0JNK-TASK]]: a
+ * packaged server started with cwd inside an empty target vault used to
+ * resolve to whatever vault another terminal/console last marked active on
+ * the machine (old tier order put the registry pointer above cwd), silently
+ * writing its bookkeeping into the WRONG repo. Now the folder the process was
+ * actually started in/under wins over the registry's stale-by-comparison
+ * pointer:
+ *   1. explicit vaultId            -> registry lookup (vaults[].id)
+ *   2. HEYSPEX_VAULT_ROOT env      -> repo root (legacy escape hatch)
+ *   2. HEYSPEX_VAULT_DIR env       -> the specs/ dir itself (repo root = parent)
+ *   3. cwd-contained vault         -> walk UP from cwd through every ancestor
+ *                                     looking for a heyspex.yaml marker or a
+ *                                     specs/ dir; the nearest match wins. Logs
+ *                                     one stderr notice iff this differs from
+ *                                     the registry's active vault (tier 4) —
+ *                                     silent when they agree (the common case:
+ *                                     the owner's own sessions start inside the
+ *                                     platform repo, which is also the
+ *                                     registry's active vault).
+ *   4. registry active_vault_id    -> the offline active pointer (vaults[].id)
+ *                                     — reached only when cwd sits inside no
+ *                                     vault at all (tier 3 found nothing)
+ *   5. cwd fallback                -> cwd itself (no marker found anywhere;
+ *                                     preserves the pre-existing default)
+ *
+ * Resolution is SYNCHRONOUS (all inputs are fs/env) and, via getActiveConfig(),
+ * memoized once per process. If the registry can't be read, tier 4 simply
+ * finds nothing and resolution falls through to tier 5 — i.e. today's
+ * behavior, so nothing regresses when no registry exists.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+/**
+ * Placeholder vaultId for tiers 3-5, which resolve a filesystem path but have
+ * no registry row to source a real id from. Mirrors UNREGISTERED_VAULT_ID in
+ * the TS resolver.
+ */
+export const UNREGISTERED_VAULT_ID = 'unregistered';
+
+/**
+ * Registry directory. Mirrors `registry-file.ts` `vaultRegistryDir`: default
+ * `~/.heyspex`, overridable via `opts.registryDir` (tests only — registry-file.ts
+ * uses an opts override, not an env var, so we do the same).
+ *
+ * @param {{ registryDir?: string }} [opts]
+ * @returns {string}
+ */
+function vaultRegistryDir(opts = {}) {
+  return opts.registryDir ?? join(homedir(), '.heyspex');
+}
+
+/**
+ * Full path to `registry.json` under the resolved registry directory.
+ * @param {{ registryDir?: string }} [opts]
+ * @returns {string}
+ */
+function vaultRegistryFilePath(opts = {}) {
+  return join(vaultRegistryDir(opts), 'registry.json');
+}
+
+function isNonEmptyString(v) {
+  return typeof v === 'string' && v.trim().length > 0;
+}
+
+/**
+ * Read + defensively parse `~/.heyspex/registry.json`. A missing or malformed
+ * file returns `null` (never throws) so callers fall through to env/cwd tiers —
+ * mirroring registry-file.ts `loadVaultRegistry`'s fail-closed contract.
+ *
+ * @param {{ registryDir?: string }} [opts]
+ * @returns {{ vaults: Array<{ id: string, repo_root_abs: string }>, active_vault_id: string|null }|null}
+ */
+function loadRegistry(opts = {}) {
+  const filePath = vaultRegistryFilePath(opts);
+  if (!existsSync(filePath)) return null;
+  let json;
+  try {
+    json = JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!json || typeof json !== 'object') return null;
+
+  const vaultsRaw = Array.isArray(json.vaults) ? json.vaults : [];
+  const vaults = [];
+  for (const raw of vaultsRaw) {
+    if (!raw || typeof raw !== 'object') continue;
+    if (!isNonEmptyString(raw.id)) continue;
+    if (!isNonEmptyString(raw.repo_root_abs)) continue;
+    vaults.push({ id: raw.id, repo_root_abs: raw.repo_root_abs });
+  }
+  const active_vault_id = isNonEmptyString(json.active_vault_id) ? json.active_vault_id : null;
+  return { vaults, active_vault_id };
+}
+
+/** Find a vault row by id. Returns null when absent. */
+function findVaultById(registry, vaultId) {
+  if (!registry || !isNonEmptyString(vaultId)) return null;
+  return registry.vaults.find((v) => v.id === vaultId) ?? null;
+}
+
+/**
+ * Walk UP from `startDir` through every ancestor directory looking for a
+ * `heyspex.yaml` marker file or a `specs/` dir — the two on-disk signals that
+ * a folder IS a vault root (mirrors `hs init`'s marker + the entity-model's
+ * folder layout). Returns the nearest matching ancestor (closest to
+ * `startDir` wins), or `null` if the walk reaches the filesystem root (or
+ * `stopAt`, inclusive) with no match. Bounded to guard against any path
+ * pathology; real filesystems never nest this deep.
+ *
+ * @param {string} startDir
+ * @param {string|undefined} stopAt - test-only walk boundary (checked, then
+ *   the walk stops — never climbs past it). Unset in production, so the walk
+ *   always reaches the real filesystem root; tests use it to fence the walk
+ *   inside a disposable tmp fixture so ambient/unrelated directories higher up
+ *   the real tree (e.g. a stray `specs` folder under the OS temp dir) can't
+ *   produce a false match.
+ * @returns {string|null}
+ */
+function findCwdVaultRoot(startDir, stopAt) {
+  let dir = startDir;
+  const boundary = isNonEmptyString(stopAt) ? resolve(stopAt) : null;
+  for (let i = 0; i < 256; i += 1) {
+    if (existsSync(join(dir, 'heyspex.yaml')) || existsSync(join(dir, 'specs'))) {
+      return dir;
+    }
+    if (boundary && dir === boundary) break; // hit the test-only fence
+    const parent = dirname(dir);
+    if (parent === dir) break; // reached filesystem root
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * When the cwd-contained vault (tier 3) wins, tell the operator if that
+ * silently overrode the registry's active vault — the customer-visible
+ * failure this task fixes (packaged server writing bookkeeping into the
+ * WRONG repo with no warning). Prints nothing when there is no registry
+ * pointer, the pointer is stale/unresolvable, or the two vaults are the same
+ * repo (the owner's own sessions: cwd = the platform repo = the registry's
+ * active vault too — must stay silent and unaffected).
+ *
+ * @param {string} cwdVaultRoot
+ * @param {{ vaults: Array<{id:string, repo_root_abs:string}>, active_vault_id: string|null }|null} registry
+ */
+function maybeLogCwdOverrideNotice(cwdVaultRoot, registry) {
+  if (!registry || !isNonEmptyString(registry.active_vault_id)) return;
+  const activeRecord = findVaultById(registry, registry.active_vault_id);
+  if (!activeRecord) return;
+  const registryRoot = resolve(activeRecord.repo_root_abs);
+  const resolvedCwdRoot = resolve(cwdVaultRoot);
+  if (registryRoot === resolvedCwdRoot) return; // same vault — no notice
+  process.stderr.write(
+    `[heyspex-mcp] vault resolution: started inside ${resolvedCwdRoot} — overriding the registry's active vault ${registryRoot}, using the cwd vault.\n`,
+  );
+}
+
+/**
+ * Build the resolved shape from a repo root. specsDirAbs is ALWAYS repoRoot/specs
+ * regardless of which tier resolved the root — matching the TS resolver.
+ *
+ * @param {string} vaultId
+ * @param {string} repoRootAbs
+ * @param {'explicit'|'account-pointer'|'env-vault-root'|'env-vault-dir'|'cwd-heuristic'} source
+ */
+function finalize(vaultId, repoRootAbs, source) {
+  const resolvedRoot = resolve(repoRootAbs);
+  return {
+    vaultId,
+    repoRootAbs: resolvedRoot,
+    specsDirAbs: join(resolvedRoot, 'specs'),
+    source,
+  };
+}
+
+/**
+ * Resolve the active vault synchronously via the 5-tier precedence stack.
+ *
+ * @param {{ vaultId?: string, cwd?: string, registryDir?: string, cwdWalkRoot?: string }} [options]
+ *   - `vaultId`: explicit override (tier 1).
+ *   - `cwd`: working dir for the cwd-contained-vault walk-up (tier 3; defaults
+ *     to `CLAUDE_PROJECT_DIR` then `process.cwd()`).
+ *   - `registryDir`: registry dir override (tests only; defaults to ~/.heyspex).
+ *   - `cwdWalkRoot`: test-only fence for the tier-3 walk-up (see
+ *     {@link findCwdVaultRoot}); production code never sets this.
+ * @returns {{ vaultId: string, repoRootAbs: string, specsDirAbs: string, source: string }}
+ */
+export function resolveActiveVault(options = {}) {
+  const registry = loadRegistry(options);
+
+  // Tier 1 — explicit vaultId (CLI --vault / caller override). Unchanged:
+  // an explicit ask always wins over everything else.
+  if (isNonEmptyString(options.vaultId)) {
+    const record = findVaultById(registry, options.vaultId);
+    if (record) return finalize(record.id, record.repo_root_abs, 'explicit');
+    // Unknown explicit id: cascade rather than fail closed (matches TS resolver).
+  }
+
+  // Tier 2 — HEYSPEX_VAULT_ROOT / HEYSPEX_VAULT_DIR env (legacy escape hatch).
+  // [[HS-C87T-0JNK-TASK]]: moved ABOVE both the cwd-contained vault and the
+  // registry pointer — an explicit env override must win "regardless" of
+  // where the process was started or what the registry says is active.
+  const envRoot = process.env.HEYSPEX_VAULT_ROOT;
+  if (isNonEmptyString(envRoot)) {
+    return finalize(UNREGISTERED_VAULT_ID, resolve(envRoot), 'env-vault-root');
+  }
+  const envDir = process.env.HEYSPEX_VAULT_DIR;
+  if (isNonEmptyString(envDir)) {
+    // Historically points AT the specs/ dir itself, so repo root = its parent
+    // (specsDirAbs then round-trips back).
+    const specsDirFromEnv = resolve(envDir);
+    return finalize(UNREGISTERED_VAULT_ID, dirname(specsDirFromEnv), 'env-vault-dir');
+  }
+
+  // Tier 3 — cwd-contained vault (HS-C87T). Backward-compat note: the OLD
+  // getConfig() fell back to CLAUDE_PROJECT_DIR then process.cwd() as a bare
+  // repo root. We keep honoring CLAUDE_PROJECT_DIR as the cwd base (an
+  // explicit `options.cwd` caller/test override still takes precedence over
+  // it), but now WALK UP from that base looking for a heyspex.yaml marker or
+  // a specs/ dir at any ancestor level — not just the base and its immediate
+  // parent — so the vault the process was actually started inside/under wins
+  // over a stale registry pointer from a different terminal/console tab.
+  const cwdBase = resolve(
+    isNonEmptyString(options.cwd)
+      ? options.cwd
+      : (isNonEmptyString(process.env.CLAUDE_PROJECT_DIR)
+        ? process.env.CLAUDE_PROJECT_DIR
+        : process.cwd()),
+  );
+  const cwdVaultRoot = findCwdVaultRoot(cwdBase, options.cwdWalkRoot);
+  if (cwdVaultRoot) {
+    maybeLogCwdOverrideNotice(cwdVaultRoot, registry);
+    return finalize(UNREGISTERED_VAULT_ID, cwdVaultRoot, 'cwd-heuristic');
+  }
+
+  // Tier 4 — registry active_vault_id (the OFFLINE active pointer). Reached
+  // only when cwd sits inside no vault at all (tier 3 found neither marker
+  // anywhere up the tree) — e.g. an ad-hoc script dir. This is how an MCP
+  // restart picks up a CLI `hs vault use` switch without Neon. Mirrors the TS
+  // resolver's account-pointer tier, sourced from the registry file here.
+  if (registry && isNonEmptyString(registry.active_vault_id)) {
+    const record = findVaultById(registry, registry.active_vault_id);
+    if (record) return finalize(record.id, record.repo_root_abs, 'account-pointer');
+    // Stale/corrupt pointer (no matching row): cascade rather than throw.
+  }
+
+  // Tier 5 — last-resort cwd fallback: no marker found anywhere up the tree,
+  // no registry pointer either. Preserves the pre-existing default value old
+  // getConfig() would have produced.
+  return finalize(UNREGISTERED_VAULT_ID, cwdBase, 'cwd-heuristic');
+}
+
+let _cached = null;
+
+/**
+ * Cached, process-lifetime resolution. Resolves once (default options) and
+ * memoizes — the MCP process is spawned once at session start, so re-resolving
+ * per call buys nothing. Use {@link resolveActiveVault} directly for per-call
+ * overrides (e.g. an explicit --vault), or {@link resetActiveConfigCache} in
+ * tests.
+ *
+ * @returns {{ vaultId: string, repoRootAbs: string, specsDirAbs: string, source: string }}
+ */
+export function getActiveConfig() {
+  if (_cached === null) _cached = resolveActiveVault();
+  return _cached;
+}
+
+/** Test-only: clear the getActiveConfig() memo so a controlled env re-resolves. */
+export function resetActiveConfigCache() {
+  _cached = null;
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Headless vault knob resolution for MCP — mirrors spex-console resolvers
+ * ([[HS-TASK-9PJV]]). Reads `spex-console/settings.json` first, then env, then
+ * shipped defaults. Repo root is the directory containing `spex-console/`.
+ *
+ * Headless mirror seam ([[HS-TASK-UEBN]]): optional `.heyspex/` JSON files are
+ * read-only fallbacks when the primary store is absent (free-tier headless MCP).
+ * Nothing in the codebase writes the mirror — the console persists only to
+ * `spex-console/settings.json` via PUT /api/settings. To sync manually:
+ * `cp spex-console/settings.json .heyspex/spex-console-settings.json`.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const DEFAULT_USE_INDEXER = true;
+export const DEFAULT_VAULT_FRONTMATTER_AUTO_REPAIR = true;
+
+/** Repo-relative primary settings store (gitignored). */
+export const SPEX_CONSOLE_SETTINGS_REL = join('spex-console', 'settings.json');
+
+/** Canonical headless mirror filename under `.heyspex/`. */
+export const SPEX_CONSOLE_SETTINGS_MIRROR_REL = join(
+  '.heyspex',
+  'spex-console-settings.json',
+);
+
+/** Pre-rename mirror — read during transition only; do not write. */
+export const SPEX_CONSOLE_SETTINGS_MIRROR_LEGACY_REL = join(
+  '.heyspex',
+  'console-settings.json',
+);
+
+function readJsonSafe(filePath) {
+  try {
+    if (!existsSync(filePath)) return null;
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Candidate settings paths in precedence order: primary store, canonical mirror,
+ * legacy mirror (back-compat). First existing readable JSON wins.
+ */
+export function spexConsoleSettingsCandidates(repoRoot) {
+  if (!repoRoot) return [];
+  return [
+    join(repoRoot, SPEX_CONSOLE_SETTINGS_REL),
+    join(repoRoot, SPEX_CONSOLE_SETTINGS_MIRROR_REL),
+    join(repoRoot, SPEX_CONSOLE_SETTINGS_MIRROR_LEGACY_REL),
+  ];
+}
+
+export function readSpexConsoleSettingsRaw(repoRoot) {
+  for (const p of spexConsoleSettingsCandidates(repoRoot)) {
+    const raw = readJsonSafe(p);
+    if (raw && typeof raw === 'object') return raw;
+  }
+  return null;
+}
+
+function parseEnvTriState(raw) {
+  if (typeof raw !== 'string') return undefined;
+  const v = raw.trim().toLowerCase();
+  if (v === 'false' || v === '0' || v === 'off') return false;
+  if (v === 'true' || v === '1' || v === 'on') return true;
+  return undefined;
+}
+
+export function resolveUseIndexerEnabled(repoRoot) {
+  const raw = readSpexConsoleSettingsRaw(repoRoot);
+  if (raw && typeof raw.useIndexer === 'boolean') return raw.useIndexer;
+  const env = parseEnvTriState(process.env.HEYSPEX_USE_INDEX);
+  if (env !== undefined) return env;
+  return DEFAULT_USE_INDEXER;
+}
+
+export function resolveVaultFrontmatterAutoRepairEnabled(repoRoot) {
+  const raw = readSpexConsoleSettingsRaw(repoRoot);
+  if (raw && typeof raw.vaultFrontmatterAutoRepair === 'boolean') {
+    return raw.vaultFrontmatterAutoRepair;
+  }
+  const env = parseEnvTriState(process.env.HEYSPEX_VAULT_AUTO_REPAIR);
+  if (env !== undefined) return env;
+  return DEFAULT_VAULT_FRONTMATTER_AUTO_REPAIR;
+}