heyspex 0.1.0

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

@@ -0,0 +1,417 @@
+/**
+ * register-spec.mjs — the core of `heyspex_register_spec`.
+ *
+ * The fix counterpart to `heyspex_validate_linkage` ([[HS-TASK-5K13]] under
+ * [[HS-EPIC-0037-spec-linkage-validation-system]]). Where validate-linkage
+ * *detects* a spec that is unreachable from the roadmap, this *links it in* —
+ * editing the vault files on both sides so the orphan (or one-sided
+ * parent/child mismatch) is resolved.
+ *
+ * Reachability is the manifest-v3 hierarchy
+ * ([[HS-TASK-JN9H-manifest-schema-v3-and-horizon-retirement]]), so what
+ * "register" means depends on the spec's kind:
+ *
+ *   - milestone → add its basename to a roadmap's `roadmap_manifest.milestones`.
+ *   - epic      → set the epic's `milestone:` field AND add the epic to that
+ *                 milestone's `epics:` list (both sides).
+ *   - task      → set the task's `parent:` field AND add the task to that
+ *                 epic's `children:` list (both sides).
+ *
+ * The original 2026-05-18 task body described a `phase_id` / `section` API over
+ * the retired `phases[].tasks[]` manifest shape. That shape no longer exists;
+ * this implementation targets the live v3 manifest, the same hierarchy the
+ * validation core was re-grounded on. Inferring the parent from the spec's own
+ * `milestone:`/`parent:` field (when the back-reference is the only thing
+ * missing) lets the tool also repair the `parent_child_mismatches` class, not
+ * just full orphans.
+ *
+ * Self-contained (no import from spex-console/) so the vendored MCP server
+ * stays portable. Frontmatter is read with the same regex-over-raw approach the
+ * rest of the vendored server uses; writes go through the shared yaml-scalar
+ * quoter ([[HS-RES-COOA-deterministic-frontmatter-integrity]]).
+ *
+ * Faces ([[capability-three-faces-no-per-capability-slash]]): this core feeds
+ *   - the `heyspex_register_spec` MCP tool (cli.mjs), and
+ *   - the `register` CLI verb (cli.mjs) for terminal / disaster-recovery use.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { collectVaultSpecs, validateLinkage } from './validate-linkage.mjs';
+import { yamlScalar } from './yaml-scalar.mjs';
+import { toCanonicalFamilyFirstId } from './spec-id-lib.mjs';
+
+const SUBJECT_TYPES = new Set(['milestone', 'epic', 'task']);
+
+// ---------------------------------------------------------------------------
+// Small id/link helpers (kept local so the module stays self-contained — they
+// mirror the ones in validate-linkage.mjs).
+// ---------------------------------------------------------------------------
+
+// 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.
+function idCore(value) {
+  const canonical = toCanonicalFamilyFirstId(value);
+  if (canonical) return canonical.toUpperCase();
+  const m = String(value || '').match(/^(HS-[A-Z]+-[A-Za-z0-9]{2,})/i);
+  return m ? m[1].toUpperCase() : null;
+}
+
+function stripWikilink(value) {
+  if (typeof value !== 'string') return null;
+  const inner = value.match(/\[\[([^\]]+)\]\]/);
+  let t = (inner ? inner[1] : value).trim();
+  t = t.split('|')[0].split('#')[0].trim();
+  return t || null;
+}
+
+function err(error, message, suggestions) {
+  const out = { success: false, error, message };
+  if (suggestions && suggestions.length) out.suggestions = suggestions;
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Frontmatter text edits (raw-string surgery — no YAML parse, CRLF-tolerant)
+// ---------------------------------------------------------------------------
+
+function detectEol(raw) {
+  return /\r\n/.test(raw) ? '\r\n' : '\n';
+}
+
+function getFrontmatter(raw) {
+  const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  return m ? m[1] : null;
+}
+
+function replaceFrontmatter(raw, newBlock) {
+  const m = raw.match(/^(---\r?\n)([\s\S]*?)(\r?\n---)/);
+  if (!m) return null;
+  return raw.slice(0, m.index) + m[1] + newBlock + m[3] + raw.slice(m.index + m[0].length);
+}
+
+// Set (replace or append) a scalar `field:` in the frontmatter block. `value`
+// is an already-serialized YAML scalar (e.g. the output of yamlScalar()).
+function setScalar(block, field, value, eol) {
+  const re = new RegExp(`^([ \\t]*${field}:)[ \\t]*.*$`, 'm');
+  if (re.test(block)) return block.replace(re, `$1 ${value}`);
+  return `${block}${eol}${field}: ${value}`;
+}
+
+// Does a raw list line (e.g. "  - '[[HS-TASK-CCCC-foo]]'") refer to `ref`?
+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);
+}
+
+/**
+ * Insert `itemValue` (already-formatted item content, without the `- ` prefix)
+ * into the YAML block list under `field:`. Handles nested keys (e.g. the
+ * `milestones:` list under `roadmap_manifest:`), an inline-empty `field: []`,
+ * and an absent field. Item indentation and the leading-`-` style are copied
+ * from existing items so the file's formatting is preserved.
+ *
+ * @returns {{ block: string } | { error: string, ref?: string }}
+ */
+function insertListItem(block, field, itemValue, position, eol) {
+  const lines = block.split(/\r?\n/);
+  let keyIdx = -1;
+  let keyIndent = '';
+  let inlineVal = '';
+  const keyRe = new RegExp(`^([ \\t]*)${field}:[ \\t]*(.*)$`);
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(keyRe);
+    if (m) {
+      keyIdx = i;
+      keyIndent = m[1];
+      inlineVal = m[2];
+      break;
+    }
+  }
+
+  // Field absent → append a fresh top-level block list at the end.
+  if (keyIdx === -1) {
+    return { block: `${block}${eol}${field}:${eol}  - ${itemValue}` };
+  }
+
+  // `field: []` → expand into a block list with the single item.
+  if (/^\[\s*\]$/.test(inlineVal.trim())) {
+    lines[keyIdx] = `${keyIndent}${field}:`;
+    lines.splice(keyIdx + 1, 0, `${keyIndent}  - ${itemValue}`);
+    return { block: lines.join(eol) };
+  }
+
+  // Walk the existing items (deeper-indented `- …` lines following the key).
+  let firstItem = -1;
+  let lastItem = -1;
+  let itemIndent = `${keyIndent}  `;
+  for (let i = keyIdx + 1; i < lines.length; i++) {
+    const im = lines[i].match(/^([ \t]+)-[ \t]?(.*)$/);
+    if (im && im[1].length > keyIndent.length) {
+      if (firstItem === -1) {
+        firstItem = i;
+        itemIndent = im[1];
+      }
+      lastItem = i;
+    } else {
+      break;
+    }
+  }
+
+  const newLine = `${itemIndent}- ${itemValue}`;
+  let insertAt;
+  if (firstItem === -1) {
+    insertAt = keyIdx + 1; // key present but no items yet
+  } else if (position === 'first') {
+    insertAt = firstItem;
+  } else if (!position || position === 'last') {
+    insertAt = lastItem + 1;
+  } else if (position.startsWith('after:') || position.startsWith('before:')) {
+    const ref = position.slice(position.indexOf(':') + 1);
+    let matchIdx = -1;
+    for (let i = firstItem; i <= lastItem; i++) {
+      if (lineRefMatches(lines[i], ref)) {
+        matchIdx = i;
+        break;
+      }
+    }
+    if (matchIdx === -1) return { error: 'POSITION_REF_NOT_FOUND', ref };
+    insertAt = position.startsWith('after:') ? matchIdx + 1 : matchIdx;
+  } else {
+    return { error: 'BAD_POSITION', ref: position };
+  }
+
+  lines.splice(insertAt, 0, newLine);
+  return { block: lines.join(eol) };
+}
+
+// ---------------------------------------------------------------------------
+// Per-file mutation accumulator — collects edits then writes once.
+// ---------------------------------------------------------------------------
+
+function loadFile(vaultRoot, relFile) {
+  const abs = join(vaultRoot, ...relFile.split('/'));
+  return { abs, raw: readFileSync(abs, 'utf-8') };
+}
+
+// ---------------------------------------------------------------------------
+// Core
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string} vaultRoot
+ * @param {object} opts
+ * @param {string}  opts.spec_id              Spec to register (id or basename).
+ * @param {string}  [opts.parent_id]          Target parent: the milestone for an
+ *        epic, the epic for a task, or the roadmap for a milestone. When omitted
+ *        for an epic/task, the spec's own `milestone:`/`parent:` field is used
+ *        (repairs a one-sided back-reference); for a milestone it defaults to
+ *        `roadmap_id`.
+ * @param {string}  [opts.roadmap_id='HS-ROADMAP-PRODUCT']  Roadmap for milestones.
+ * @param {string}  [opts.position='last']    'first' | 'last' | 'after:<ref>' | 'before:<ref>'.
+ * @param {boolean} [opts.dryRun=false]       Plan the edits without writing or re-validating.
+ * @param {string}  [opts.now]                ISO timestamp for `updated:` (injectable for tests).
+ * @param {boolean} [opts.updateTimestamps=true]
+ */
+export function registerSpec(vaultRoot, opts = {}) {
+  const {
+    spec_id,
+    parent_id = null,
+    roadmap_id = 'HS-ROADMAP-PRODUCT',
+    position = 'last',
+    dryRun = false,
+    updateTimestamps = true,
+  } = opts;
+  const now = opts.now || new Date().toISOString();
+
+  if (!spec_id || !String(spec_id).trim()) {
+    return err('SPEC_ID_REQUIRED', 'spec_id is required.');
+  }
+
+  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;
+  };
+  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 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);
+  }
+  if (!SUBJECT_TYPES.has(spec.type)) {
+    return err(
+      'UNSUPPORTED_TYPE',
+      `register_spec only links milestones, epics, and tasks into the roadmap; ${spec.id} is type "${spec.type}".`,
+    );
+  }
+
+  // Stage edits per file, then commit in one pass so a mid-write failure can't
+  // leave one side linked and the other not.
+  const edits = new Map(); // relFile -> { abs, block, eol, raw, actions: [] }
+  const stage = (record) => {
+    if (edits.has(record.file)) return edits.get(record.file);
+    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 };
+    edits.set(record.file, e);
+    return e;
+  };
+
+  const changes = [];
+
+  if (spec.type === 'milestone') {
+    // Target roadmap: explicit parent_id wins, else roadmap_id default.
+    const roadmapRef = parent_id || roadmap_id;
+    const roadmap = resolveRef(roadmapRef);
+    if (!roadmap || !roadmap.manifest) {
+      return err('ROADMAP_NOT_FOUND', `Roadmap ${roadmapRef} not found (or it has no roadmap_manifest).`);
+    }
+    const already = listHasSpec(roadmap.manifest.milestones, spec);
+    if (!already) {
+      const e = stage(roadmap);
+      const res = insertListItem(e.block, 'milestones', spec.basename, position, e.eol);
+      if (res.error) return err(res.error, positionErrorMessage(res), undefined);
+      e.block = res.block;
+      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,
+    });
+  }
+
+  // epic → milestone (milestone:/epics:) or task → epic (parent:/children:)
+  const childField = spec.type === 'epic' ? 'milestone' : 'parent';
+  const parentListField = spec.type === 'epic' ? 'epics' : 'children';
+  const parentType = spec.type === 'epic' ? 'milestone' : 'epic';
+  const existingParentRef = spec.type === 'epic' ? spec.milestone : spec.parent;
+
+  const targetRef = parent_id || existingParentRef;
+  if (!targetRef) {
+    return err(
+      'MISSING_PARENT',
+      `${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 parent = resolveRef(targetRef);
+  if (!parent) {
+    return err('PARENT_NOT_FOUND', `Parent ${targetRef} not found in the vault.`);
+  }
+  if (parent.type !== parentType) {
+    return err(
+      'PARENT_TYPE_MISMATCH',
+      `A ${spec.type} must be parented to a ${parentType}, but ${parent.id} is type "${parent.type}".`,
+    );
+  }
+
+  // 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));
+  if (!fieldPointsAtParent) {
+    const e = stage(spec);
+    e.block = setScalar(e.block, childField, yamlScalar(`[[${parent.basename}]]`), e.eol);
+    e.touched = true;
+    changes.push({ file: spec.file, action: `Set ${childField}: [[${parent.basename}]]` });
+  }
+
+  // Side 2: the parent's back-reference list.
+  const parentLists = parentListField === 'epics' ? parent.epics : parent.children;
+  const listAlready = listHasSpec(parentLists, spec);
+  if (!listAlready) {
+    const e = stage(parent);
+    const res = insertListItem(e.block, parentListField, `'[[${spec.basename}]]'`, position, e.eol);
+    if (res.error) return err(res.error, positionErrorMessage(res), undefined);
+    e.block = res.block;
+    e.touched = true;
+    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,
+  });
+}
+
+function positionErrorMessage(res) {
+  if (res.error === 'POSITION_REF_NOT_FOUND') {
+    return `position ref "${res.ref}" was not found in the target list.`;
+  }
+  return `invalid position "${res.ref}". Use 'first', 'last', 'after:<ref>', or 'before:<ref>'.`;
+}
+
+// Commit staged edits to disk (unless dryRun) and re-validate the subject.
+function finalize({ spec, parent, roadmap_id, already, edits, changes, vaultRoot, dryRun, updateTimestamps, now }) {
+  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}`);
+      writeFileSync(e.abs, next, 'utf-8');
+    }
+  }
+
+  const result = {
+    success: true,
+    spec_id: spec.id,
+    type: spec.type,
+    parent,
+    already_registered: !!already && changes.length === 0,
+    changes,
+    dry_run: !!dryRun,
+  };
+  if (roadmap_id) result.roadmap_id = roadmap_id;
+
+  if (!dryRun) {
+    const v = validateLinkage(vaultRoot, { spec_id: spec.id, includeWarnings: false });
+    result.validation = {
+      valid: v.valid,
+      orphan_specs: v.orphan_specs,
+      parent_child_mismatches: v.parent_child_mismatches,
+    };
+  }
+  return result;
+}