heyspex 0.2.0 → 0.2.1

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

@@ -65,6 +65,7 @@
  * behavior, so nothing regresses when no registry exists.
  */
 
+import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -85,7 +86,7 @@ export const UNREGISTERED_VAULT_ID = 'unregistered';
  * @returns {string}
  */
 function vaultRegistryDir(opts = {}) {
-  return opts.registryDir ?? join(homedir(), '.heyspex');
+  return opts.registryDir ?? join(heyspexHome(), '.heyspex');
 }
 
 /**
@@ -175,6 +176,33 @@ export function registryPointerVaultId(json) {
   return legacy && isNonEmptyString(legacy.active_vault_id) ? legacy.active_vault_id : null;
 }
 
+/**
+ * The account the MACHINE-LOCAL registry row for `repoRootAbs` was registered
+ * under (`vaults[].account_id`), or null (no row, or the pre-account `legacy`
+ * bucket). The repo-to-account binding lives here - per machine, per user -
+ * and NEVER in the committed heyspex.yaml: a second developer with another
+ * account must not inherit the first one's account (owner ruling 2026-10-16).
+ *
+ * @param {string} repoRootAbs
+ * @param {{ registryDir?: string }} [opts]
+ * @returns {string|null}
+ */
+export function registryAccountIdForRoot(repoRootAbs, opts = {}) {
+  if (!isNonEmptyString(repoRootAbs)) return null;
+  const file = vaultRegistryFilePath(opts);
+  let json;
+  try {
+    json = JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+  const target = normalizeRoot(repoRootAbs);
+  const rows = Array.isArray(json?.vaults) ? json.vaults : [];
+  const row = rows.find((v) => v && isNonEmptyString(v.repo_root_abs) && normalizeRoot(v.repo_root_abs) === target);
+  const id = row?.account_id;
+  return isNonEmptyString(id) && id !== LEGACY_REGISTRY_ACCOUNT_ID ? id.trim() : null;
+}
+
 /** Find a vault row by id. Returns null when absent. */
 function findVaultById(registry, vaultId) {
   if (!registry || !isNonEmptyString(vaultId)) return null;
@@ -260,6 +288,46 @@ function isAbsolutePin(p) {
  * @returns {string|null} the attached vault's absolute repo root
  */
 export function readSatellitePin(dir) {
+  const d = inspectSatellitePin(dir);
+  return d && d.kind === 'pin' ? d.root : null;
+}
+
+/**
+ * Expand the client placeholders a PORTABLE pin may carry against the
+ * manifest's own directory: ${CLAUDE_PROJECT_DIR[:-default]} (Claude Code) and
+ * ${workspaceFolder} (Cursor). Anything else left as ${...} is unresolvable.
+ */
+function expandPinPlaceholders(value, dir) {
+  return value.replace(/\$\{(?:CLAUDE_PROJECT_DIR|workspaceFolder)(?::-[^}]*)?\}/g, dir);
+}
+
+/**
+ * Classify the heyspex server's HEYSPEX_VAULT_ROOT in `dir`'s MCP manifests.
+ * Returns null when no manifest names a pin at all, else one of:
+ *   { kind: 'pin', root, raw, source }       an attachment to a vault OUTSIDE dir
+ *   { kind: 'self' }                         ordinary install (pin is dir or under it)
+ *   { kind: 'broken', raw, source, reason }  a pin that cannot be resolved
+ *       (unknown ${...} placeholder). A broken pin must REFUSE, never fall
+ *       through to the account-wide pointer (owner principle P1).
+ *
+ * PORTABLE pins (owner principle P3, 2026-10-16): a pin may be RELATIVE
+ * ('../mlc-specs') or built on the project-dir placeholder
+ * ('${CLAUDE_PROJECT_DIR:-.}/../mlc-specs'); both resolve against the
+ * MANIFEST'S OWN directory, never the process cwd, so the committed manifest
+ * carries no machine-specific absolute path.
+ *
+ * @param {string} dir
+ */
+export function inspectSatellitePin(dir) {
+  // ONE precedence rule, identical in the TS twin (satellite.ts
+  // readPinnedVaultRoot + the resolver walk): at each directory a committed
+  // satellite MARKER (heyspex.yaml with vault_path) beats any manifest pin; of
+  // the manifests, the first VALID outside pin in read order (.mcp.json, then
+  // .cursor/mcp.json) wins no matter what the other manifest says; a broken
+  // pin refuses only when no manifest carries a valid one; 'self' (an ordinary
+  // install) is the weakest signal. Shared table: satellite-precedence-fixtures.json.
+  let broken = null;
+  let self = false;
   for (const rel of SATELLITE_MANIFESTS) {
     let raw;
     try {
@@ -274,13 +342,58 @@ export function readSatellitePin(dir) {
       continue;
     }
     if (!isNonEmptyString(value)) continue;
+    const source = rel.join('/');
     const trimmed = value.trim();
-    if (trimmed.includes('${')) continue;
-    if (!isAbsolutePin(trimmed)) continue;
-    const pinned = normalizeRoot(trimmed);
+    const expanded = expandPinPlaceholders(trimmed, dir);
+    if (expanded.includes('${')) {
+      broken ??= { kind: 'broken', raw: trimmed, source, reason: 'it contains a placeholder other than ${CLAUDE_PROJECT_DIR} / ${workspaceFolder}' };
+      continue;
+    }
+    if (/^[a-zA-Z]:(?![\\/])/.test(expanded)) {
+      broken ??= { kind: 'broken', raw: trimmed, source, reason: 'a drive-relative path (C:dir) names no single directory' };
+      continue;
+    }
+    const abs = isAbsolutePin(expanded) ? resolve(expanded) : resolve(dir, expanded);
+    const pinned = normalizeRoot(abs);
     const here = normalizeRoot(dir);
-    if (pinned === here || pinned.startsWith(`${here}/`)) continue; // ordinary install
-    return resolve(trimmed);
+    if (pinned === here || pinned.startsWith(`${here}/`)) {
+      self = true;
+      continue;
+    }
+    return { kind: 'pin', root: abs, raw: trimmed, source };
+  }
+  if (broken) return broken;
+  return self ? { kind: 'self' } : null;
+}
+
+/**
+ * Walk up from `startDir` looking for the NEAREST manifest pin that cannot be
+ * honoured: unresolvable placeholder, or a pin whose target is not a vault
+ * root on this machine. Returns null when the nearest pin (or marker) is fine
+ * or there is none. `hs` uses it to REFUSE instead of falling back to the
+ * account-wide pointer ([[HS-O40H]], owner principle P1).
+ *
+ * @param {string} startDir
+ * @param {string} [stopAt]
+ * @returns {{ dir: string, raw: string, source: string, reason: string }|null}
+ */
+export function findBrokenSatellitePin(startDir, stopAt) {
+  let dir = resolve(startDir);
+  const boundary = isNonEmptyString(stopAt) ? resolve(stopAt) : null;
+  for (let i = 0; i < 256; i += 1) {
+    if (readMarkerSatellite(dir)) return null; // marker outranks any pin
+    const d = inspectSatellitePin(dir);
+    if (d?.kind === 'broken') return { dir, raw: d.raw, source: d.source, reason: d.reason };
+    if (d?.kind === 'pin') {
+      if (isVaultRoot(d.root)) return null;
+      return { dir, raw: d.raw, source: d.source, reason: `${d.root} is not a vault on this machine (no heyspex.yaml or specs/ there; clone the vault repo there or fix the pin)` };
+    }
+    if (d?.kind === 'self') return null;
+    if (readMarkerSatellite(dir) || isVaultRoot(dir)) return null;
+    if (boundary && dir === boundary) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
   }
   return null;
 }
@@ -342,6 +455,59 @@ function readMarkerVaultId(dir) {
   }
 }
 
+/**
+ * Extract `vault_path: <value>` from raw heyspex.yaml text, or `null`.
+ * The PORTABLE satellite declaration (owner principles P1/P3, 2026-10-16): a
+ * code repo (e.g. mlc-app) commits a `heyspex.yaml` carrying its `vault_id`
+ * plus a RELATIVE `vault_path` (e.g. `../mlc-specs`) to where the attached
+ * vault is usually cloned. No absolute path is ever committed. An absolute,
+ * empty or unexpanded `${...}` value is not a declaration (returns null).
+ *
+ * @param {string} content
+ * @returns {string|null}
+ */
+export function parseMarkerVaultPath(content) {
+  const m = String(content ?? '').match(/^vault_path:[ \t]*(.+?)[ \t]*$/m);
+  if (!m) return null;
+  const v = m[1].trim().replace(/\s+#.*$/, '').replace(/^"(.*)"$/, '$1').replace(/^'(.*)'$/, '$1').trim();
+  if (!v || v.includes('${') || isAbsolutePin(v)) return null;
+  return v;
+}
+
+/**
+ * Is `<dir>/heyspex.yaml` a committed SATELLITE marker (it carries a relative
+ * `vault_path`)? Returns the attachment it declares, or `null`.
+ *
+ *   - `vaultId`: the marker's `vault_id` (the vault this repo is bound to; the
+ *     ONLY thing a fresh machine without the vault clone needs, because
+ *     cloud-routed writes name the vault by id).
+ *   - `vaultRootAbs`: `resolve(dir, vault_path)` when that directory exists on
+ *     THIS machine and is a vault root whose own marker does not name a
+ *     DIFFERENT vault id; otherwise `null` (not cloned here, or a different
+ *     vault sits at that path - never read the wrong vault's disk).
+ *
+ * @param {string} dir
+ * @returns {{ vaultId: string|null, vaultPath: string, vaultRootAbs: string|null }|null}
+ */
+export function readMarkerSatellite(dir) {
+  let raw;
+  try {
+    raw = readFileSync(join(dir, 'heyspex.yaml'), 'utf8');
+  } catch {
+    return null;
+  }
+  const vaultPath = parseMarkerVaultPath(raw);
+  if (!vaultPath) return null;
+  const vaultId = parseMarkerVaultId(raw);
+  const candidate = resolve(dir, vaultPath);
+  let vaultRootAbs = null;
+  if (normalizeRoot(candidate) !== normalizeRoot(dir) && isVaultRoot(candidate)) {
+    const theirs = readMarkerVaultId(candidate);
+    if (!vaultId || !theirs || theirs === vaultId) vaultRootAbs = candidate;
+  }
+  return { vaultId, vaultPath, vaultRootAbs };
+}
+
 /**
  * The marker id and the registry row for the same root disagree. The marker
  * wins (it is the repo's own on-disk declaration, written by `hs init` /
@@ -371,12 +537,18 @@ function logMarkerRegistryMismatch(repoRootAbs, markerVaultId, registryVaultId)
  *   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 cannot produce a false match.
- * @returns {{ repoRootAbs: string, satellite: boolean }|null}
+ * @returns {{ repoRootAbs: string, satellite: boolean, markerSatellite?: ReturnType<typeof readMarkerSatellite> }|null}
  */
 function findCwdVaultOrAttachment(startDir, stopAt) {
   let dir = startDir;
   const boundary = isNonEmptyString(stopAt) ? resolve(stopAt) : null;
   for (let i = 0; i < 256; i += 1) {
+    // Precedence (see inspectSatellitePin): committed satellite marker, then
+    // any valid manifest pin, then the generic vault-root test.
+    const marked = readMarkerSatellite(dir);
+    if (marked) {
+      return { repoRootAbs: marked.vaultRootAbs ?? dir, satellite: true, markerSatellite: marked };
+    }
     const pinned = readSatellitePin(dir);
     if (pinned) return { repoRootAbs: pinned, satellite: true };
     if (isVaultRoot(dir)) return { repoRootAbs: dir, satellite: false };
@@ -501,11 +673,21 @@ export function resolveActiveVault(options = {}) {
       // for the gate sites that consume this (all of them reject only
       // `'cwd-heuristic'`, so both labels are accepted identically).
       const pinnedRecord = findVaultByRoot(registry, cwdMatch.repoRootAbs);
-      return finalize(
-        pinnedRecord?.id ?? UNREGISTERED_VAULT_ID,
+      // A committed satellite marker names the vault by id: that id IS the
+      // binding (works on a fresh machine with no registry row and no clone).
+      const markerId = cwdMatch.markerSatellite?.vaultId ?? null;
+      const bound = finalize(
+        markerId ?? pinnedRecord?.id ?? UNREGISTERED_VAULT_ID,
         cwdMatch.repoRootAbs,
         'satellite-pin',
       );
+      // The marker names a vault that is NOT cloned on this machine: the
+      // binding is cloud-only. Disk readers must not report an empty vault -
+      // they answer from the cloud and say so (read-path.mjs).
+      if (cwdMatch.markerSatellite && !cwdMatch.markerSatellite.vaultRootAbs) {
+        return { ...bound, vaultCloned: false, vaultPath: cwdMatch.markerSatellite.vaultPath };
+      }
+      return bound;
     }
     // A heyspex.yaml `vault_id` IS the vault's id ([[HS-VVNQ]]): `hs init` /
     // `hs connect` wrote it there. Before this, the id came ONLY from a
@@ -561,6 +743,12 @@ export function resolveActiveVault(options = {}) {
   // anywhere up the tree) and no env var names one. 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.
+  // The ORDER is pinned (decision memory `vault-resolver-precedence`); what a
+  // consumer does with `source: 'account-pointer'` is its own call — the
+  // console transport (console-fetch.mjs `vaultIdHeaderFor`) REFUSES
+  // vault-scoped requests on it (`VAULT_NOT_PINNED`) unless
+  // HEYSPEX_ALLOW_POINTER_VAULT=1, because the pointer mirrors whatever the
+  // owner last clicked in the console, not anything this repo declared.
   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');

package/vendor/heyspex-mcp/whoami.mjs

@@ -9,6 +9,7 @@
 // TypeScript, same as folder-trust-store.mjs). Never prints, logs or returns
 // token material: callers only ever see an identity verdict.
 
+import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
 import { homedir } from 'node:os';
 
 import { readBearer } from './credentials.mjs';
@@ -29,7 +30,7 @@ export const SESSION_PATH = '/api/mcp/session';
  * @param {{ env?: NodeJS.ProcessEnv | Record<string, string | undefined>, homeDir?: string, readFile?: (p: string) => string }} [opts]
  * @returns {string | null}
  */
-export function readStoredBearer({ env = process.env, homeDir = homedir(), readFile } = {}) {
+export function readStoredBearer({ env = process.env, homeDir = heyspexHome(), readFile } = {}) {
   return readBearer({ env, homeDir, readFile }).token;
 }