heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/register-spec.mjs

@@ -36,9 +36,20 @@
  */
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { collectVaultSpecs, validateLinkage } from './validate-linkage.mjs';
+import {
+  collectVaultSpecs,
+  validateLinkage,
+  buildSpecIndex,
+  resolveSpecRef,
+  refNamesSpec,
+  refsNameSameSpec,
+} from './validate-linkage.mjs';
 import { yamlScalar } from './yaml-scalar.mjs';
-import { toCanonicalFamilyFirstId } from './spec-id-lib.mjs';
+import { toCanonicalFamilyFirstId, lookupFileKeyOf, fileKeyFromBasename } from './spec-id-lib.mjs';
+import { consoleFetch as realConsoleFetch } from './console-transport.mjs';
+import { getConsoleUrl } from './mcp-config.mjs';
+import { resolveVaultWriteMode } from './read-path.mjs';
+import { splitRawSpec, updateSpecViaConsole } from './cloud-vault-writes.mjs';
 
 const SUBJECT_TYPES = new Set(['milestone', 'epic', 'task']);
 
@@ -48,9 +59,15 @@ const SUBJECT_TYPES = new Set(['milestone', 'epic', 'task']);
 // ---------------------------------------------------------------------------
 
 // Canonical, ordering-independent core of a spec id (dual-read: a type-first id
-// and its family-first form resolve to the SAME core, so byIdCore / listHasSpec
-// match across orderings). [[HS-EPIC-DLE3]] / [[HS-EPIC-6SNQ]]. Falls back to the
-// legacy anchored regex for unknown-type / hyphenated ids parseSpecId can't read.
+// and its family-first form resolve to the SAME core). [[HS-EPIC-DLE3]] /
+// [[HS-EPIC-6SNQ]]. Falls back to the legacy anchored regex for unknown-type /
+// hyphenated ids parseSpecId can't read.
+//
+// NOT an identity ([[HS-J6IE-K2EL-DIAG-heyspex-register-spec-resolves-a-task]]):
+// under Naming V3 the core is family+TYPE, which every task in one family
+// shares. It is used here ONLY for the SPEC_NOT_FOUND suggestion list; all
+// resolution and list-membership goes through the shared file-key-first
+// resolver in validate-linkage.mjs (resolveSpecRef / refNamesSpec).
 function idCore(value) {
   const canonical = toCanonicalFamilyFirstId(value);
   if (canonical) return canonical.toUpperCase();
@@ -58,6 +75,14 @@ function idCore(value) {
   return m ? m[1].toUpperCase() : null;
 }
 
+// File key a caller's ref carries (bare `HS-OCL4`, display `HS-OCL4-NYPR`, full
+// era-3 basename, or an era-1/2 basename whose slug leads with the key).
+function refFileKey(ref) {
+  if (typeof ref !== 'string' || !ref.trim()) return null;
+  const t = ref.trim().replace(/^hs-/i, 'HS-');
+  return lookupFileKeyOf(t) ?? fileKeyFromBasename(t) ?? null;
+}
+
 function stripWikilink(value) {
   if (typeof value !== 'string') return null;
   const inner = value.match(/\[\[([^\]]+)\]\]/);
@@ -104,8 +129,7 @@ function lineRefMatches(line, ref) {
   const im = line.match(/^[ \t]+-[ \t]*(.+?)[ \t]*$/);
   if (!im) return false;
   const target = stripWikilink(im[1].replace(/^['"]|['"]$/g, '')) ?? '';
-  const refCore = idCore(ref);
-  return target === stripWikilink(ref) || (!!refCore && idCore(target) === refCore);
+  return refsNameSameSpec(target, ref);
 }
 
 /**
@@ -218,6 +242,53 @@ function loadFile(vaultRoot, relFile) {
  * @param {boolean} [opts.updateTimestamps=true]
  */
 export function registerSpec(vaultRoot, opts = {}) {
+  const planned = planRegisterSpec(vaultRoot, opts);
+  if (!planned.__plan) return planned;
+  return finalize(planned.__plan);
+}
+
+/**
+ * Mode-aware entry point — the one a handler should call
+ * ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]).
+ *
+ * {@link registerSpec} stays SYNCHRONOUS and local-only on purpose: it is
+ * called from sync call sites in filing-tools.mjs, cli-verbs.mjs and
+ * promote-research.mjs, and async-ifying it cascades through all three (the
+ * same bounded deferral
+ * [[HS-M0MK-CPFP-TASK-migrate-capture-focus-yaml-to-neon-capture-focus-pin]]
+ * took for the vendor capture writers). This wrapper resolves the vault write
+ * mode ONCE and dispatches:
+ *
+ *   - `local` — delegates straight to {@link registerSpec}; byte-identical.
+ *   - `cloud` — plans exactly the same frontmatter surgery, then sends each
+ *     touched file through `PUT /api/specs/:id` ({@link updateSpecViaConsole})
+ *     instead of `writeFileSync`. Nothing is written to this machine's disk.
+ *
+ * `registerSpec` only ever EDITS existing vault files (it links an already-filed
+ * spec into its parent's back-reference list), so there is no create branch here
+ * — `createSpecViaConsole` belongs to the filing tools, not to this one.
+ *
+ * @param {object} [deps] Injection seam for tests: `consoleFetch`, `consoleUrl`,
+ *   `resolveWriteMode`.
+ */
+export async function registerSpecViaMode(vaultRoot, opts = {}, deps = {}) {
+  const writeMode =
+    opts.writeMode ?? (await (deps.resolveWriteMode ?? resolveVaultWriteMode)()) ?? 'local';
+  if (writeMode !== 'cloud') return registerSpec(vaultRoot, opts);
+  const planned = planRegisterSpec(vaultRoot, opts);
+  if (!planned.__plan) return planned;
+  return finalizeViaConsole(planned.__plan, {
+    consoleFetch: deps.consoleFetch ?? realConsoleFetch,
+    consoleUrl: deps.consoleUrl ?? getConsoleUrl(),
+  });
+}
+
+/**
+ * Resolve + stage every edit without committing any of them. Returns either a
+ * failure result (the `err(...)` shape callers already read) or `{ __plan }` —
+ * everything {@link finalize} / {@link finalizeViaConsole} need.
+ */
+function planRegisterSpec(vaultRoot, opts = {}) {
   const {
     spec_id,
     parent_id = null,
@@ -233,32 +304,45 @@ export function registerSpec(vaultRoot, opts = {}) {
   }
 
   const specs = collectVaultSpecs(vaultRoot);
-  const byBasename = new Map();
-  const byId = new Map();
-  const byIdCore = new Map();
-  for (const s of specs) {
-    byBasename.set(s.basename, s);
-    if (s.id) byId.set(s.id, s);
-    if (s.idCore && !byIdCore.has(s.idCore)) byIdCore.set(s.idCore, s);
-  }
-  const resolveRef = (ref) => {
-    if (!ref) return null;
-    const t = stripWikilink(ref) ?? ref;
-    return byBasename.get(t) || byId.get(t) || byIdCore.get(idCore(t)) || null;
+  // Shared Naming V3 resolver ([[HS-J6IE-K2EL-DIAG-heyspex-register-spec-resolves-a-task]]):
+  // exact basename → exact id → UNIQUE file key → idCore soft match only for a
+  // key-less (era-1/2) ref and only when exactly one spec matches. A ref that
+  // names two specs is refused with AMBIGUOUS_SPEC_ID naming the candidates;
+  // the old first-wins family-core map re-parented an unrelated sibling.
+  const index = buildSpecIndex(specs);
+  const resolveRef = (ref) => resolveSpecRef(index, ref).spec;
+  const ambiguous = (ref, role) => {
+    const r = resolveSpecRef(index, ref);
+    if (!r.ambiguous) return null;
+    const names = r.candidates.map((c) => c.basename).join(', ');
+    return {
+      ...err(
+        'AMBIGUOUS_SPEC_ID',
+        `${role} "${stripWikilink(ref) ?? ref}" names ${r.candidates.length} specs (${names}). ` +
+          'Under Naming V3 the file key (the token right after HS-) is the only unique key; a family key or ' +
+          'family+TYPE core is shared by every spec in the family. Pass the full basename or the bare file key ' +
+          '(HS-<fileKey>). NOTHING WAS WRITTEN.',
+      ),
+      candidates: r.candidates,
+      matched_by: r.matched_by,
+    };
   };
-  const listHasSpec = (list, target) =>
-    list.some((ref) => {
-      const t = stripWikilink(ref) ?? ref;
-      return t === target.basename || t === target.id || (!!target.idCore && idCore(t) === target.idCore);
-    });
+  const listHasSpec = (list, target) => list.some((ref) => refNamesSpec(ref, target));
 
+  const specAmbiguity = ambiguous(spec_id, 'spec_id');
+  if (specAmbiguity) return specAmbiguity;
   const spec = resolveRef(spec_id);
   if (!spec) {
     const want = idCore(spec_id);
     const suggestions = want
       ? specs.filter((s) => s.idCore && s.idCore.startsWith(want.slice(0, 7))).map((s) => s.id).slice(0, 3)
       : [];
-    return err('SPEC_NOT_FOUND', `Spec ${spec_id} does not exist in the vault.`, suggestions);
+    const key = refFileKey(String(spec_id));
+    const hint = key
+      ? ` It carries file key ${key}, which no file under specs/ is stored under — a cloud-only spec with no local ` +
+        'copy? Pull the vault (or run in cloud write mode) before registering; the resolver never falls through to a sibling.'
+      : '';
+    return err('SPEC_NOT_FOUND', `Spec ${spec_id} does not exist in the vault.${hint}`, suggestions);
   }
   if (!SUBJECT_TYPES.has(spec.type)) {
     return err(
@@ -275,7 +359,20 @@ export function registerSpec(vaultRoot, opts = {}) {
     const { abs, raw } = loadFile(vaultRoot, record.file);
     const block = getFrontmatter(raw);
     if (block == null) throw new Error(`No frontmatter in ${record.file}`);
-    const e = { abs, raw, block, eol: detectEol(raw), actions: [], touched: false };
+    // `specId`/`type`/`file` ride along so the cloud commit can address this
+    // file by the id `PUT /api/specs/:id` takes, and can refuse the one
+    // document shape that cannot survive that route (see finalizeViaConsole).
+    const e = {
+      abs,
+      raw,
+      block,
+      eol: detectEol(raw),
+      actions: [],
+      touched: false,
+      specId: record.id ?? null,
+      type: record.type ?? null,
+      file: record.file,
+    };
     edits.set(record.file, e);
     return e;
   };
@@ -285,6 +382,8 @@ export function registerSpec(vaultRoot, opts = {}) {
   if (spec.type === 'milestone') {
     // Target roadmap: explicit parent_id wins, else roadmap_id default.
     const roadmapRef = parent_id || roadmap_id;
+    const roadmapAmbiguity = ambiguous(roadmapRef, 'roadmap');
+    if (roadmapAmbiguity) return roadmapAmbiguity;
     const roadmap = resolveRef(roadmapRef);
     if (!roadmap || !roadmap.manifest) {
       return err('ROADMAP_NOT_FOUND', `Roadmap ${roadmapRef} not found (or it has no roadmap_manifest).`);
@@ -298,18 +397,20 @@ export function registerSpec(vaultRoot, opts = {}) {
       e.touched = true;
       changes.push({ file: roadmap.file, action: `Added ${spec.basename} to roadmap_manifest.milestones` });
     }
-    return finalize({
-      spec,
-      parent: { id: roadmap.id, type: 'roadmap' },
-      roadmap_id: roadmap.id,
-      already,
-      edits,
-      changes,
-      vaultRoot,
-      dryRun,
-      updateTimestamps,
-      now,
-    });
+    return {
+      __plan: {
+        spec,
+        parent: { id: roadmap.id, type: 'roadmap' },
+        roadmap_id: roadmap.id,
+        already,
+        edits,
+        changes,
+        vaultRoot,
+        dryRun,
+        updateTimestamps,
+        now,
+      },
+    };
   }
 
   // epic → milestone (milestone:/epics:) or task → epic (parent:/children:)
@@ -325,6 +426,8 @@ export function registerSpec(vaultRoot, opts = {}) {
       `${spec.id} is a ${spec.type} with no ${parentType} parent. Pass parent_id (an existing HS-${parentType === 'milestone' ? 'MIL' : 'EPIC'}-* id) to register it.`,
     );
   }
+  const parentAmbiguity = ambiguous(targetRef, 'parent_id');
+  if (parentAmbiguity) return parentAmbiguity;
   const parent = resolveRef(targetRef);
   if (!parent) {
     return err('PARENT_NOT_FOUND', `Parent ${targetRef} not found in the vault.`);
@@ -337,11 +440,7 @@ export function registerSpec(vaultRoot, opts = {}) {
   }
 
   // Side 1: the child's own pointer field.
-  const fieldPointsAtParent =
-    existingParentRef &&
-    (stripWikilink(existingParentRef) === parent.basename ||
-      stripWikilink(existingParentRef) === parent.id ||
-      (!!parent.idCore && idCore(existingParentRef) === parent.idCore));
+  const fieldPointsAtParent = !!existingParentRef && refNamesSpec(existingParentRef, parent);
   if (!fieldPointsAtParent) {
     const e = stage(spec);
     e.block = setScalar(e.block, childField, yamlScalar(`[[${parent.basename}]]`), e.eol);
@@ -361,17 +460,19 @@ export function registerSpec(vaultRoot, opts = {}) {
     changes.push({ file: parent.file, action: `Added [[${spec.basename}]] to ${parent.id} ${parentListField}[]` });
   }
 
-  return finalize({
-    spec,
-    parent: { id: parent.id, type: parent.type },
-    already: fieldPointsAtParent && listAlready,
-    edits,
-    changes,
-    vaultRoot,
-    dryRun,
-    updateTimestamps,
-    now,
-  });
+  return {
+    __plan: {
+      spec,
+      parent: { id: parent.id, type: parent.type },
+      already: fieldPointsAtParent && listAlready,
+      edits,
+      changes,
+      vaultRoot,
+      dryRun,
+      updateTimestamps,
+      now,
+    },
+  };
 }
 
 function positionErrorMessage(res) {
@@ -415,3 +516,114 @@ function finalize({ spec, parent, roadmap_id, already, edits, changes, vaultRoot
   }
   return result;
 }
+
+/**
+ * Cloud-write-mode twin of {@link finalize}: the SAME staged frontmatter
+ * surgery, committed through `PUT /api/specs/:id` instead of `writeFileSync`.
+ *
+ * Each touched file's spliced markdown is split back into the
+ * `{ frontmatter, body }` pair the route takes ({@link splitRawSpec}), and
+ * addressed by the spec id the planner already resolved for that file (falling
+ * back to the document's own `id:`). A file with no cloud route degrades
+ * explicitly as `CLOUD_MODE_UNSUPPORTED_WRITE` rather than quietly landing on a
+ * disk the mode forbade.
+ *
+ * Writes run IN ORDER and stop at the FIRST failure, and nothing is rolled back
+ * — the console has no un-write. The failure result therefore names the step
+ * that failed AND the steps that already landed, so a caller reports the real
+ * half-linked state instead of implying a clean abort (the
+ * `commitWritesViaConsole` contract).
+ *
+ * `validation` is deliberately ABSENT: `validateLinkage` re-reads the vault from
+ * local disk, which in cloud mode still holds the PRE-edit bytes (or no clone at
+ * all), so running it would report a confidently wrong verdict. The reason rides
+ * in `validation_skipped`.
+ */
+async function finalizeViaConsole(
+  { spec, parent, roadmap_id, already, edits, changes, dryRun, updateTimestamps, now },
+  { consoleFetch, consoleUrl },
+) {
+  const written = [];
+  if (!dryRun) {
+    for (const e of edits.values()) {
+      if (!e.touched) continue;
+      let block = e.block;
+      if (updateTimestamps) block = setScalar(block, 'updated', yamlScalar(now), e.eol);
+      const next = replaceFrontmatter(e.raw, block);
+      if (next == null) throw new Error(`Failed to splice frontmatter for ${e.abs}`);
+      // A ROADMAP has no safe cloud route today, and the failure would be
+      // silent DATA LOSS rather than an error: `PUT /api/specs/:id` takes a
+      // PARSED frontmatter object, and the parser that builds it
+      // (`parseFrontmatter` → `parseRoadmapManifest`, vault-io.mjs) still reads
+      // the retired v2 manifest shape — it returns `{ phases, initiatives,
+      // horizon }` and drops `milestones[]` entirely. Sending that object back
+      // would erase the roadmap's whole milestone list. The disk write this
+      // mode forbade is NOT used as a fallback; the caller is told which file
+      // and why.
+      if (e.type === 'roadmap' || /^[ \t]*roadmap_manifest:/m.test(block)) {
+        return {
+          ...err(
+            'CLOUD_MODE_UNSUPPORTED_WRITE',
+            `register_spec cannot write ${e.file ?? e.abs} in cloud vault-write mode: it carries a `
+              + '`roadmap_manifest:`, and the client-side frontmatter parser behind PUT /api/specs/:id still reads '
+              + 'the retired v2 manifest shape (phases/initiatives/horizon) — round-tripping it would DROP the v3 '
+              + '`milestones[]` list. NOTHING WAS WRITTEN. File the milestone through the console (which owns the '
+              + 'manifest), or run this registration in local write mode.',
+          ),
+          write_mode: 'cloud',
+          console_url: consoleUrl ?? null,
+          on_disk: false,
+          completed_writes: written,
+        };
+      }
+      const { frontmatter, body } = splitRawSpec(next);
+      const specId = e.specId || (typeof frontmatter?.id === 'string' ? frontmatter.id.trim() : '');
+      if (!specId) {
+        return {
+          ...err(
+            'CLOUD_MODE_UNSUPPORTED_WRITE',
+            `register_spec cannot write ${e.file ?? e.abs} in cloud vault-write mode: neither the staged spec `
+              + "record nor the document's own frontmatter carries an `id:`, and PUT /api/specs/:id needs one. "
+              + 'NOTHING WAS WRITTEN — the local disk write is deliberately NOT used as a fallback.',
+          ),
+          write_mode: 'cloud',
+          console_url: consoleUrl ?? null,
+          on_disk: false,
+          completed_writes: written,
+        };
+      }
+      try {
+        const res = await updateSpecViaConsole({ consoleFetch, consoleUrl, specId, frontmatter, body });
+        written.push({ file: e.file ?? null, spec_id: res.specId, rel_path: res.relPath });
+      } catch (cause) {
+        return {
+          ...err('CONSOLE_UNREACHABLE_CLOUD_MODE', String(cause?.message ?? cause)),
+          write_mode: 'cloud',
+          console_url: consoleUrl ?? null,
+          on_disk: false,
+          failed_write: { file: e.file ?? null, spec_id: specId },
+          completed_writes: written,
+          ...(cause?.notFound ? { not_found: true } : {}),
+        };
+      }
+    }
+  }
+
+  const result = {
+    success: true,
+    spec_id: spec.id,
+    type: spec.type,
+    parent,
+    already_registered: !!already && changes.length === 0,
+    changes,
+    dry_run: !!dryRun,
+    write_mode: 'cloud',
+    on_disk: false,
+    console_url: consoleUrl ?? null,
+    console_writes: written,
+    validation_skipped:
+      'cloud write mode — the local vault copy was not updated, so validateLinkage would re-read pre-edit bytes',
+  };
+  if (roadmap_id) result.roadmap_id = roadmap_id;
+  return result;
+}

package/vendor/heyspex-mcp/request-context.mjs

@@ -0,0 +1,83 @@
+/**
+ * request-context.mjs — per-call overrides for the console transport.
+ *
+ * WHY: the stdio MCP server is one process per user, so the console URL and
+ * the outbound bearer are process-wide (`HEYSPEX_MCP_TOKEN` env, the
+ * credentials file, the shared console-url resolver). The remote endpoint
+ * (`POST /api/mcp` on the console, WP6) runs the SAME dispatch in-process on a
+ * shared serverless runtime, where one request's caller must never leak into
+ * another's — so `process.env` is off limits and the override has to travel
+ * with the async call chain instead.
+ *
+ * An `AsyncLocalStorage` store carries `{ consoleUrl, authHeader }` for the
+ * duration of one `runWithRequestContext(ctx, fn)` call, including every
+ * `await` beneath it. `console-transport.mjs` consults the two accessors when
+ * it binds `makeConsoleFetch`; with no active store they return `undefined`
+ * and the transport falls through to today's process-wide resolution, so the
+ * stdio server's behavior is unchanged byte-for-byte.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/** @typedef {{ consoleUrl?: string, authHeader?: Record<string, string>, vaultId?: string }} RequestContext */
+
+const storage = new AsyncLocalStorage();
+
+/**
+ * Run `fn` with `ctx` as the active request context. Returns whatever `fn`
+ * returns (a Promise stays a Promise; the store follows its continuations).
+ *
+ * @template T
+ * @param {RequestContext} ctx
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function runWithRequestContext(ctx, fn) {
+  return storage.run(ctx ?? {}, fn);
+}
+
+/** The active request context, or `undefined` outside any `runWithRequestContext`. */
+export function getRequestContext() {
+  return storage.getStore();
+}
+
+/** Console origin override for the active request, or `undefined` (use the shared resolver). */
+export function contextConsoleUrl() {
+  const url = storage.getStore()?.consoleUrl;
+  return typeof url === 'string' && url.trim() ? url.replace(/\/+$/, '') : undefined;
+}
+
+/**
+ * Outbound auth header(s) for the active request, or `undefined` (use the
+ * process-wide `getAuthHeader`). An explicit empty object is honored — it
+ * means "this caller presented no credential; do not fall back to the
+ * server's own token", which is the correct fail-closed shape on a shared
+ * runtime.
+ */
+export function contextAuthHeader() {
+  const header = storage.getStore()?.authHeader;
+  return header && typeof header === 'object' ? header : undefined;
+}
+
+/**
+ * Outbound `x-heyspex-vault-id` for the active request, or `undefined` outside
+ * any request context (the stdio server then resolves the repo-bound vault
+ * from its cwd). INSIDE a context the answer is ALWAYS an object: the caller's
+ * own vault header, or `{}` when it sent none. It is never the server
+ * process's own vault (a shared serverless runtime has none), and never the
+ * account-wide active pointer: a bearer call that names no vault is refused by
+ * the console (`vault-scope-required`). Owner principles P1/P2/P3, 2026-10-16.
+ */
+export function contextVaultIdHeader() {
+  const store = storage.getStore();
+  if (!store) return undefined;
+  const id = typeof store.vaultId === 'string' ? store.vaultId.trim() : '';
+  return id ? { 'x-heyspex-vault-id': id } : {};
+}
+
+/**
+ * Outbound `x-heyspex-account-id` for the active request: always `{}` inside a
+ * context (the forwarded credential IS the account), `undefined` outside.
+ */
+export function contextAccountIdHeader() {
+  return storage.getStore() ? {} : undefined;
+}