heyspex 0.1.0

package/vendor/heyspex-mcp/plan-ingest.mjs

@@ -0,0 +1,476 @@
+/**
+ * Ingest external / proprietary plan documents into HeySpex vault specs.
+ * Cursor plans live under ~/.cursor/plans/ (or repo .cursor/plans/) and are not
+ * portable to Claude Code — vault specs must own canonical plan content.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, basename, isAbsolute, normalize } from 'node:path';
+
+const CANONICAL_SECTION_HEADING = '## Canonical implementation plan (HeySpex)';
+const CANONICAL_SECTION_RE =
+  /## Canonical implementation plan \(HeySpex\)[\s\S]*?(?=\n## Change log|\n## NEXT STEP:|\n## NEXT STEP\s|$)/i;
+
+/** @typedef {{ ref: string, resolvedPath: string | null, label: string }} PlanRef */
+
+/**
+ * Detect external plan path references in markdown.
+ * @param {string} markdown
+ * @returns {PlanRef[]}
+ */
+export function extractExternalPlanRefs(markdown) {
+  if (!markdown?.trim()) return [];
+
+  const refs = [];
+  const seen = new Set();
+
+  const add = (ref, label = basename(ref)) => {
+    const normalized = ref.replace(/\\/g, '/').trim();
+    if (!normalized || seen.has(normalized)) return;
+    if (normalized.includes('*')) return; // prose globs like .cursor/plans/*.plan.md
+    if (!/\.plan\.md$/i.test(normalized) && !/\.cursor\/plans\//i.test(normalized)) return;
+    seen.add(normalized);
+    refs.push({ ref: normalized, resolvedPath: null, label });
+  };
+
+  // Backtick paths
+  for (const m of markdown.matchAll(/`([^`\n]+\.plan\.md)`/gi)) {
+    add(m[1]);
+  }
+
+  // Bold labels: **Plan:** `path`
+  for (const m of markdown.matchAll(
+    /\*\*(?:Full plan|Plan|Layout plan|Implementation plan[^*]*)\*\*:?\s*`([^`]+)`/gi,
+  )) {
+    add(m[1]);
+  }
+
+  // Implementation plan line with middle dot separators
+  for (const m of markdown.matchAll(
+    /\*\*Implementation plan \(Cursor\):\*\*\s*`([^`]+)`/gi,
+  )) {
+    add(m[1]);
+  }
+
+  return refs;
+}
+
+/**
+ * Resolve a plan reference to an absolute file path.
+ * @param {string} vaultRoot
+ * @param {string} ref
+ * @returns {string | null}
+ */
+export function resolvePlanPath(vaultRoot, ref) {
+  const cleaned = ref.replace(/\\/g, '/').trim();
+  const candidates = [];
+
+  if (isAbsolute(cleaned)) {
+    candidates.push(normalize(cleaned));
+  } else {
+    candidates.push(normalize(join(vaultRoot, cleaned)));
+
+    const planBasename = basename(cleaned);
+    if (cleaned.includes('.cursor/plans/') || cleaned.startsWith('.cursor/plans/')) {
+      candidates.push(normalize(join(homedir(), '.cursor', 'plans', planBasename)));
+      candidates.push(normalize(join(vaultRoot, '.cursor', 'plans', planBasename)));
+    }
+  }
+
+  for (const p of candidates) {
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Strip Cursor plan YAML frontmatter (--- name/overview/todos ---).
+ * @param {string} raw
+ * @returns {string}
+ */
+export function stripPlanFrontmatter(raw) {
+  if (!raw.startsWith('---')) return raw.trim();
+  const end = raw.indexOf('\n---', 3);
+  if (end === -1) return raw.trim();
+  return raw.slice(end + 4).trim();
+}
+
+/**
+ * @param {string} resolvedPath
+ * @param {string} ref
+ * @returns {{ content: string, sourceLabel: string }}
+ */
+function readPlanFile(resolvedPath, ref) {
+  const raw = readFileSync(resolvedPath, 'utf8');
+  return {
+    content: stripPlanFrontmatter(raw),
+    sourceLabel: basename(ref) || basename(resolvedPath),
+  };
+}
+
+/**
+ * Build the canonical ingested section for vault specs.
+ * @param {Array<{ sourceLabel: string, content: string, resolvedPath: string }>} plans
+ * @param {string} [ingestedAt]
+ */
+export function buildCanonicalPlanSection(plans, ingestedAt = new Date().toISOString().slice(0, 10)) {
+  if (!plans.length) return '';
+
+  const lines = [
+    CANONICAL_SECTION_HEADING,
+    '',
+    `> **Ingested:** ${ingestedAt}. Treat **this section** as the portable source of truth.`,
+    `> External paths (e.g. \`.cursor/plans/*.plan.md\`) are provenance only — Claude Code and other agents may not read them.`,
+    '',
+  ];
+
+  for (const plan of plans) {
+    lines.push(`### Source: ${plan.sourceLabel}`, '');
+    if (plan.resolvedPath) {
+      lines.push(`_Provenance: \`${plan.resolvedPath.replace(/\\/g, '/')}\`_`, '');
+    }
+    lines.push(plan.content.trim(), '', '---', '');
+  }
+
+  return lines.join('\n').trimEnd();
+}
+
+/**
+ * Remove dangling external-only plan pointer lines (replaced by canonical section).
+ * @param {string} markdown
+ */
+export function stripExternalPlanPointers(markdown) {
+  let out = markdown;
+  const patterns = [
+    /^\*\*(?:Full plan|Plan|Layout plan)\*\*:?\s*`[^`\n]+\.plan\.md`.*\n/gm,
+    /^\*\*Implementation plan \(Cursor\):\*\*[^\n]*\n/gm,
+    /^> \*\*Layout plan:\*\*[^\n]*\n/gm,
+  ];
+  for (const re of patterns) {
+    out = out.replace(re, '');
+  }
+  return out.replace(/\n{3,}/g, '\n\n').trim();
+}
+
+/**
+ * Replace external plan refs in text with vault-local pointer.
+ * @param {string} markdown
+ */
+export function rewritePlanRefsToCanonical(markdown) {
+  let out = markdown;
+  out = out.replace(
+    /`([^`\n]*\.cursor\/plans\/[^`]+\.plan\.md)`/gi,
+    '[[#canonical-implementation-plan-heyspex]] (in this spec)',
+  );
+  out = out.replace(
+    /\*\*(?:Full plan|Plan)\*\*:?\s*`[^`]+`/gi,
+    '**Canonical plan:** see ## Canonical implementation plan (HeySpex) in this spec',
+  );
+  return out;
+}
+
+/**
+ * @param {string} vaultRoot
+ * @param {string} markdown
+ * @param {{ extraPaths?: string[] }} [options]
+ */
+export function resolveAndReadPlans(vaultRoot, markdown, options = {}) {
+  const refs = extractExternalPlanRefs(markdown);
+  const extraPaths = options.extraPaths || [];
+  const byRef = new Map();
+
+  for (const r of refs) {
+    const resolved = resolvePlanPath(vaultRoot, r.ref);
+    byRef.set(r.ref, { ...r, resolvedPath: resolved });
+  }
+
+  for (const p of extraPaths) {
+    const ref = p.replace(/\\/g, '/');
+    if (!byRef.has(ref)) {
+      byRef.set(ref, {
+        ref,
+        resolvedPath: resolvePlanPath(vaultRoot, ref),
+        label: basename(ref),
+      });
+    }
+  }
+
+  /** @type {Array<{ sourceLabel: string, content: string, resolvedPath: string, ref: string }>} */
+  const ingested = [];
+  /** @type {Array<{ ref: string, resolvedPath: string | null }>} */
+  const missing = [];
+
+  for (const entry of byRef.values()) {
+    if (!entry.resolvedPath) {
+      missing.push({ ref: entry.ref, resolvedPath: null });
+      continue;
+    }
+    try {
+      const { content, sourceLabel } = readPlanFile(entry.resolvedPath, entry.ref);
+      ingested.push({
+        sourceLabel,
+        content,
+        resolvedPath: entry.resolvedPath,
+        ref: entry.ref,
+      });
+    } catch {
+      missing.push({ ref: entry.ref, resolvedPath: entry.resolvedPath });
+    }
+  }
+
+  return { ingested, missing, refs: [...byRef.values()] };
+}
+
+/**
+ * Insert canonical plan before change log / NEXT STEP tail sections.
+ * @param {string} body
+ * @param {string} section
+ */
+function insertCanonicalBeforeTailSections(body, section) {
+  const markers = ['\n## Change log', '\n## NEXT STEP'];
+  for (const marker of markers) {
+    const idx = body.indexOf(marker);
+    if (idx !== -1) {
+      return `${body.slice(0, idx).trim()}\n\n${section}\n${body.slice(idx)}`;
+    }
+  }
+  return `${body.trim()}\n\n${section}\n`;
+}
+
+/**
+ * Merge external plans into vault markdown (epic body, task body, or prompt).
+ * @param {string} vaultRoot
+ * @param {string} markdown
+ * @param {{ extraPaths?: string[], force?: boolean }} [options]
+ */
+export function ingestPlansIntoMarkdown(vaultRoot, markdown, options = {}) {
+  const hasCanonical = CANONICAL_SECTION_RE.test(markdown);
+  if (hasCanonical && !options.force) {
+    return {
+      markdown,
+      ingested: [],
+      missing: [],
+      already_canonical: true,
+      changed: false,
+    };
+  }
+
+  const { ingested, missing } = resolveAndReadPlans(vaultRoot, markdown, {
+    extraPaths: options.extraPaths,
+  });
+
+  if (ingested.length === 0) {
+    return { markdown, ingested, missing, already_canonical: false, changed: false };
+  }
+
+  let body = stripExternalPlanPointers(markdown);
+  body = rewritePlanRefsToCanonical(body);
+
+  if (hasCanonical && options.force) {
+    body = body.replace(CANONICAL_SECTION_RE, '').trim();
+  }
+
+  const section = buildCanonicalPlanSection(ingested);
+  const markdownOut = insertCanonicalBeforeTailSections(body, section);
+
+  return {
+    markdown: markdownOut,
+    ingested,
+    missing,
+    already_canonical: false,
+    changed: true,
+  };
+}
+
+/**
+ * Prepare epic + implementation prompt for vault write (hs-push / hs-push-next).
+ * @param {string} vaultRoot
+ * @param {{ plan_markdown?: string, implementation_prompt?: string, source_plan_paths?: string[] }} args
+ */
+export function prepareVaultPlanContent(vaultRoot, args) {
+  const extraPaths = args.source_plan_paths || [];
+
+  const planResult = ingestPlansIntoMarkdown(vaultRoot, args.plan_markdown || '', { extraPaths });
+  const promptSource = args.implementation_prompt || '';
+  const promptIngest = ingestPlansIntoMarkdown(vaultRoot, promptSource, { extraPaths });
+
+  /** @type {typeof planResult.ingested} */
+  const allIngested = [];
+  const seenPaths = new Set();
+  for (const item of [...planResult.ingested, ...promptIngest.ingested]) {
+    if (seenPaths.has(item.resolvedPath)) continue;
+    seenPaths.add(item.resolvedPath);
+    allIngested.push(item);
+  }
+
+  const missing = [...planResult.missing, ...promptIngest.missing].filter(
+    (m, i, arr) => arr.findIndex((x) => x.ref === m.ref) === i,
+  );
+
+  let planMarkdown = planResult.markdown;
+  let implementationPrompt = promptIngest.markdown;
+
+  // If plans only appeared in prompt, append canonical section to epic body
+  if (allIngested.length > 0 && !CANONICAL_SECTION_RE.test(planMarkdown)) {
+    const section = buildCanonicalPlanSection(allIngested);
+    planMarkdown = insertCanonicalBeforeTailSections(planMarkdown, section);
+  }
+
+  if (allIngested.length > 0) {
+    implementationPrompt = rewritePlanRefsToCanonical(
+      stripExternalPlanPointers(implementationPrompt),
+    );
+    if (!/canonical implementation plan/i.test(implementationPrompt)) {
+      implementationPrompt = `${implementationPrompt.trim()}\n\n**Canonical plan:** Full detail is in the epic spec under ## Canonical implementation plan (HeySpex).\n`;
+    }
+  }
+
+  return {
+    plan_markdown: planMarkdown,
+    implementation_prompt: implementationPrompt,
+    ingested_plans: allIngested.map((p) => ({
+      source: p.sourceLabel,
+      path: p.resolvedPath.replace(/\\/g, '/'),
+    })),
+    missing_plans: missing,
+    plans_ingested: allIngested.length > 0,
+  };
+}
+
+/**
+ * Extract canonical plan section from spec body for hs-next prompts.
+ * @param {string} body
+ * @returns {string | null}
+ */
+export function extractCanonicalPlanSection(body) {
+  const m = body.match(CANONICAL_SECTION_RE);
+  return m ? m[0].trim() : null;
+}
+
+/**
+ * Enrich agent prompt with canonical + resolvable external plan content.
+ * @param {string} vaultRoot
+ * @param {string} specRelPath
+ * @param {string} specBody
+ * @param {string} promptMarkdown
+ * @param {{ persist?: boolean }} [options]
+ */
+export function hydratePromptWithPlans(vaultRoot, specRelPath, specBody, promptMarkdown, options = {}) {
+  const canonical = extractCanonicalPlanSection(specBody);
+  const { ingested, missing } = resolveAndReadPlans(
+    vaultRoot,
+    `${specBody}\n\n${promptMarkdown}`,
+  );
+
+  const parts = [promptMarkdown.trim()];
+
+  if (canonical) {
+    parts.push('', '---', '', canonical);
+  } else if (ingested.length > 0) {
+    parts.push(
+      '',
+      '---',
+      '',
+      '> **Plan ingest (runtime):** External plan file(s) were resolved for this session. Re-run **hs-push-next** or persist with `persist_plan_ingest: true` on `heyspex_next_on_deck` to write into the vault spec.',
+      '',
+      buildCanonicalPlanSection(ingested),
+    );
+  }
+
+  if (missing.length > 0) {
+    parts.push(
+      '',
+      '---',
+      '',
+      '### ⚠️ Unresolved plan sources',
+      '',
+      ...missing.map(
+        (m) => `- \`${m.ref}\` — not found (checked vault root and ~/.cursor/plans/)`,
+      ),
+    );
+  }
+
+  let persistResult = null;
+  if (options.persist && ingested.length > 0 && !canonical) {
+    const merged = ingestPlansIntoMarkdown(vaultRoot, specBody, { force: false });
+    if (merged.changed) {
+      const fullPath = join(vaultRoot, specRelPath);
+      writeFileSync(fullPath, patchSpecBody(fullPath, merged.markdown), 'utf8');
+      persistResult = { spec_path: specRelPath, written: true };
+    }
+  }
+
+  return {
+    prompt_markdown: parts.filter(Boolean).join('\n'),
+    plans_in_prompt: ingested.map((p) => p.sourceLabel),
+    missing_plans: missing,
+    had_canonical_in_spec: Boolean(canonical),
+    persist_result: persistResult,
+  };
+}
+
+/**
+ * Replace spec body while preserving frontmatter.
+ * @param {string} filePath
+ * @param {string} newBody
+ */
+function patchSpecBody(filePath, newBody) {
+  const raw = readFileSync(filePath, 'utf8');
+  const fmEnd = raw.indexOf('\n---', 3);
+  if (!raw.startsWith('---') || fmEnd === -1) {
+    return newBody;
+  }
+  const frontmatter = raw.slice(0, fmEnd + 4);
+  return `${frontmatter}\n\n${newBody.trim()}\n`;
+}
+
+/**
+ * Ingest plans into an on-disk spec file (repair / hs-next persist).
+ * @param {string} vaultRoot
+ * @param {string} specRelPath
+ */
+export function ingestPlansIntoSpecFile(vaultRoot, specRelPath) {
+  const fullPath = join(vaultRoot, specRelPath);
+  if (!existsSync(fullPath)) {
+    return { error: 'SPEC_NOT_FOUND', message: specRelPath };
+  }
+  const raw = readFileSync(fullPath, 'utf8');
+  const fmEnd = raw.indexOf('\n---', 3);
+  const body = fmEnd === -1 ? raw : raw.slice(fmEnd + 4);
+  const result = ingestPlansIntoMarkdown(vaultRoot, body, { force: false });
+  if (!result.changed) {
+    return {
+      spec_path: specRelPath,
+      changed: false,
+      ingested_plans: result.ingested,
+      missing_plans: result.missing,
+      already_canonical: result.already_canonical,
+    };
+  }
+  writeFileSync(fullPath, patchSpecBody(fullPath, result.markdown), 'utf8');
+  return {
+    spec_path: specRelPath,
+    changed: true,
+    ingested_plans: result.ingested.map((p) => ({
+      source: p.sourceLabel,
+      path: p.resolvedPath.replace(/\\/g, '/'),
+    })),
+    missing_plans: result.missing,
+  };
+}
+
+// ── Minimal self-test: node vendor/heyspex-mcp/plan-ingest.mjs
+function runSelfTest() {
+  const refs = extractExternalPlanRefs(
+    '**Plan:** `.cursor/plans/foo.plan.md` and `C:\\Users\\x\\.cursor\\plans\\bar.plan.md`',
+  );
+  console.assert(refs.length >= 1, 'extract refs');
+  const stripped = stripPlanFrontmatter('---\nname: x\n---\n\n# Body\n');
+  console.assert(stripped.startsWith('# Body'), 'strip frontmatter');
+  console.log('plan-ingest.mjs: ok');
+}
+
+if (process.argv[1]?.endsWith('plan-ingest.mjs')) {
+  runSelfTest();
+}