@aisystemresources/emdee 0.1.0

package/src/lib/mcp/tools/distill_doc.ts

@@ -0,0 +1,262 @@
+import { createHash } from "node:crypto";
+import { validatePath, loadVaultIndex } from "./vault";
+import type { ToolContext } from "./types";
+import type { DocNode } from "../../../core/indexer";
+import { validateArgs } from "./validate_args";
+
+const ARG_SPEC = { allowed: ["path"], required: ["path"] } as const;
+
+function json(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
+}
+
+const FENCE_RE = /^\s*(?:```|~~~)/;
+const H2_RE = /^##\s+(.+?)\s*$/;
+const H3_RE = /^###\s+(.+?)\s*$/;
+const H1_RE = /^#\s+(.+?)\s*$/;
+
+interface SectionLoc {
+  heading: string;
+  level: 2 | 3;
+  start_line: number;
+  end_line: number;
+  body_verbatim: string;
+  content_hash: string;
+  char_count: number;
+}
+
+/**
+ * Walk the source doc and emit a flat list of H2 + H3 sections — both are
+ * extraction boundaries for distill_doc. The body of each section runs up
+ * to the next heading of equal or shallower depth.
+ */
+function parseSectionsForDistill(content: string): SectionLoc[] {
+  const lines = content.split("\n");
+  const headings: Array<{ heading: string; level: 2 | 3; line: number }> = [];
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (FENCE_RE.test(lines[i])) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    const h2 = lines[i].match(H2_RE);
+    if (h2) { headings.push({ heading: h2[1].trim(), level: 2, line: i }); continue; }
+    const h3 = lines[i].match(H3_RE);
+    if (h3) headings.push({ heading: h3[1].trim(), level: 3, line: i });
+  }
+
+  const out: SectionLoc[] = [];
+  for (let i = 0; i < headings.length; i++) {
+    const h = headings[i];
+    // End the body when we hit the next heading of equal-or-shallower depth.
+    let end = lines.length;
+    for (let j = i + 1; j < headings.length; j++) {
+      if (headings[j].level <= h.level) { end = headings[j].line; break; }
+    }
+    const body_verbatim = lines.slice(h.line + 1, end).join("\n").replace(/^\s*\n+/, "").replace(/\n+\s*$/, "");
+    out.push({
+      heading: h.heading,
+      level: h.level,
+      start_line: h.line,
+      end_line: end,
+      body_verbatim,
+      content_hash: hashBody(body_verbatim),
+      char_count: body_verbatim.length,
+    });
+  }
+  return out;
+}
+
+function hashBody(body: string): string {
+  return createHash("sha256").update(body, "utf8").digest("hex").slice(0, 16);
+}
+
+/**
+ * Pull a named H2 section's body out of a doc. Used to extract the
+ * BRAIN/PATTERN/INFO rubric content from the live docs so the distill
+ * semantics stay in sync with whatever the canonical filters say today.
+ * Returns null when the doc lacks that section.
+ */
+function extractH2Section(content: string, headingLower: string): string | null {
+  const lines = content.split("\n");
+  let inFence = false;
+  let startBody = -1;
+  let endBody = lines.length;
+  for (let i = 0; i < lines.length; i++) {
+    if (FENCE_RE.test(lines[i])) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    const m = lines[i].match(H2_RE);
+    if (!m) continue;
+    const h = m[1].trim().toLowerCase();
+    if (startBody === -1 && h === headingLower) {
+      startBody = i + 1;
+      continue;
+    }
+    if (startBody !== -1) { endBody = i; break; }
+  }
+  if (startBody === -1) return null;
+  return lines.slice(startBody, endBody).join("\n").trim();
+}
+
+/**
+ * Extract a doc's H1 + blockquote summary (preamble region). Used to
+ * convey the BRAIN / PROJECTS — PATTERN charter alongside the CONTEXT
+ * section — together they form the rubric.
+ */
+function extractPreambleSummary(content: string): string {
+  const lines = content.split("\n");
+  let inFence = false;
+  let h1Idx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (FENCE_RE.test(lines[i])) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    if (H1_RE.test(lines[i])) { h1Idx = i; break; }
+  }
+  if (h1Idx === -1) return "";
+
+  let firstH2Idx = lines.length;
+  inFence = false;
+  for (let i = h1Idx + 1; i < lines.length; i++) {
+    if (FENCE_RE.test(lines[i])) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    if (H2_RE.test(lines[i])) { firstH2Idx = i; break; }
+  }
+  return lines.slice(h1Idx, firstH2Idx).join("\n").trim();
+}
+
+function findByTitle(docs: DocNode[], title: string): DocNode | undefined {
+  const target = title.toLowerCase();
+  return docs.find((d) => d.title.toLowerCase() === target);
+}
+
+const PLAN_INSTRUCTIONS = `You are constructing a distillation plan for a notes doc. The plan will be reviewed by a human, then executed via the \`split_doc\` MCP tool which atomically rewrites the source and creates the new extract docs.
+
+STRICT RULES — failure to follow these breaks the trust contract with the user, who exports these notes to other people:
+
+1. **Verbatim body.** Every extract's \`body_verbatim\` field MUST be a copy-paste of the exact bytes from \`source.sections[i].body_verbatim\`. Do NOT reword, paraphrase, polish, summarize, or "improve" the prose. Same em-dashes, same code fences, same tables, same trailing whitespace. If you can't extract a concept without rewriting it to stand alone, DO NOT extract — add it to \`flagged_for_manual_split\` instead.
+
+2. **Title and summary are the only things you author.** The H1 title and the \`> blockquote\` summary on the new doc are the only LLM-authored strings. Mark both clearly in the plan's \`notes\` field as "review: LLM-drafted." Everything else is the user's own words.
+
+3. **Section-level only.** Only propose extractions at H2 or H3 section boundaries (matching exactly one \`source.sections[i].heading\`). If a concept sits mid-paragraph or spans multiple sub-paragraphs without a clean heading, add it to \`flagged_for_manual_split\` with the reason.
+
+4. **Idempotency.** For every extract, check \`vault_context.existing_titles\` (case-insensitive). If the title already exists, set \`already_exists: { path: "<existing-path>" }\` and DO NOT propose body_verbatim for that extract — the source will simply get a wiki-link stub pointing at the existing doc instead.
+
+5. **Branch placement is a hint, not a decision.** The user makes the final call. Provide your best guess in \`suggested_child_of\` and \`suggested_associated_with\` using the rubrics from \`vault_context\`. Explain your reasoning briefly in \`notes\`.
+
+6. **Source rewrite.** Construct \`source_rewrite_summary\` describing what the source doc will look like after extraction — typically the narrative scaffolding stays, the extracted sections become single-line wiki-link bullets. The actual rewritten content will be assembled by the executor (you or the user) when calling \`split_doc\`.
+
+7. **Confidence scoring.** \`high\` = clean section boundary, clear concept, obvious branch fit. \`medium\` = readable but judgment call on title or branch. \`low\` = the section feels extractable but you're unsure — flag your doubt in \`notes\` for the reviewer.
+
+8. **Don't extract everything.** Narrative content, session-specific observations, personal AHAs, and "(to be expanded)" stubs should usually stay in the source — they're not standalone concepts. Surface them in \`keep_in_source_headings\`. The goal is to extract knowledge POINTS that other docs can wiki-link to, not to evacuate the source.
+
+Now: read \`source\` and \`vault_context\`, then produce a plan in the shape of \`plan_template.schema_hint\`.`;
+
+const EXAMPLE_EXTRACT = {
+  title: "PAS Formula",
+  summary: "> Problem → Agitate → Solution. The emotional arc that great copy follows: name the problem, twist the knife, then ride in with the solution. Makes the prospect feel the pain before offering the relief.",
+  suggested_path: "concepts/PAS-FORMULA.md",
+  suggested_child_of: ["[[PROJECTS — PATTERN]]"],
+  suggested_associated_with: ["[[GBI_Day4]]", "[[GBI]]"],
+  source_section_heading: "#3 — How to Write the Body: The PAS Formula",
+  body_verbatim: "<copy-paste of source.sections[i].body_verbatim verbatim — same bytes, do not reword>",
+  confidence: "high",
+  notes: "review: LLM-drafted title + summary. Branch placement: PROJECTS — PATTERN since this is a cross-instance technical pattern for copywriting. Associated with both the day note (GBI_Day4) and the event itself (GBI).",
+};
+
+const SCHEMA_HINT = JSON.stringify(
+  {
+    source_path: "string — same as input path",
+    source_rewrite_summary: "string — one paragraph describing the post-extraction source state",
+    extracts: [
+      {
+        title: "string",
+        summary: "string — must start with `> `",
+        suggested_path: "string — vault-relative, ends in .md",
+        suggested_child_of: ["array of `[[Title]]` wiki-link strings"],
+        suggested_associated_with: ["array of `[[Title]]` wiki-link strings"],
+        source_section_heading: "string — exact match to source.sections[i].heading",
+        body_verbatim: "string — VERBATIM from source.sections[i].body_verbatim",
+        confidence: "high | medium | low",
+        notes: "string — reasoning, flags for review",
+        "already_exists?": { path: "string — set ONLY if title already exists in vault" },
+      },
+    ],
+    keep_in_source_headings: ["array of section headings to leave in the source"],
+    flagged_for_manual_split: [
+      { section_heading: "string", reason: "string" },
+    ],
+  },
+  null,
+  2
+);
+
+/**
+ * Read-only intake helper for splitting a notes doc into knowledge nodes.
+ *
+ * Returns everything the calling LLM needs to construct a defensible
+ * split plan without paying for vault lookups one-tool-call-at-a-time:
+ * the source content with section boundaries marked, the existing vault
+ * title set (collision check), the BRAIN / PROJECTS — PATTERN / LEARNINGS
+ * rubrics quoted from the live canonical docs, and a plan template.
+ *
+ * Does NOT make any LLM calls server-side and does NOT write anything.
+ * The calling agent (Claude Chat, ChatGPT, Doubao — whichever) constructs
+ * the plan in its response. The user reviews. Then split_doc executes.
+ */
+export async function distillDoc(ctx: ToolContext, args: Record<string, unknown>): Promise<unknown> {
+  const argErr = validateArgs(args, ARG_SPEC);
+  if (argErr) return json(argErr);
+  const rel = String(args.path);
+  validatePath(rel);
+
+  const index = await loadVaultIndex(ctx);
+  const source = index.docs.find((d) => d.path === rel);
+  if (!source) return json({ error: "doc_not_found", path: rel });
+
+  const sections = parseSectionsForDistill(source.content);
+  const existing_titles = index.docs.map((d) => d.title);
+
+  // Pull the rubrics from the canonical docs by title (not path) so the
+  // distillation semantics survive any future renames of those docs.
+  const brain = findByTitle(index.docs, "BRAIN");
+  const projectsPattern = findByTitle(index.docs, "PROJECTS — PATTERN");
+
+  const brain_charter = brain
+    ? `${extractPreambleSummary(brain.content)}\n\n${extractH2Section(brain.content, "context") ?? ""}`.trim()
+    : "(BRAIN.md not found — falling back: BRAIN holds cross-domain personal operating principles that pass operating-principle / cross-context / actionable.)";
+
+  const projects_pattern_rules = projectsPattern
+    ? `${extractPreambleSummary(projectsPattern.content)}\n\n${extractH2Section(projectsPattern.content, "context") ?? ""}`.trim()
+    : "(PROJECTS — PATTERN doc not found — falling back: cross-project technical/business patterns observed in ≥2 projects.)";
+
+  const learnings_filter = "(three-test filter: reusable, non-obvious in retrospect, has a directive.)";
+
+  // Branches that currently host a PATTERN.md — informs the calling LLM
+  // about where else extracts could go beyond PROJECTS — PATTERN.
+  const branches_with_pattern = index.docs
+    .filter((d) => /(^|\/)PATTERN\.md$/.test(d.path) && d.path !== "PATTERN.md")
+    .map((d) => ({
+      branch: d.path.replace(/\/PATTERN\.md$/, "") || "(root)",
+      pattern_path: d.path,
+    }));
+
+  return json({
+    source: {
+      path: source.path,
+      title: source.title,
+      h1: source.title,
+      content: source.content,
+      sections,
+    },
+    vault_context: {
+      existing_titles,
+      branches_with_pattern,
+      brain_charter,
+      projects_pattern_rules,
+      learnings_filter,
+    },
+    plan_template: {
+      instructions: PLAN_INSTRUCTIONS,
+      example_extract: EXAMPLE_EXTRACT,
+      schema_hint: SCHEMA_HINT,
+    },
+  });
+}

package/src/lib/mcp/tools/filename.ts

@@ -0,0 +1,63 @@
+// SPRINT-055 (SIG-004): filename casing enforcement helpers.
+//
+// EMDEE's on-disk filenames are all-caps (e.g. CLAUDE.md, SPRINT-029.md). The
+// H1 display title is free-form; wiki-links are case-insensitive so titles
+// don't break links no matter their case. Filenames are the durable identifier
+// — judgment-free to constrain, lintable, prevents typo-driven duplicates
+// (Foo.md vs FOO.md vs foo.md as three different files).
+
+import path from "node:path";
+
+// Allowed in a normalised filename: ASCII uppercase letters, digits, dot,
+// hyphen, underscore. Dot is allowed for sub-extensions like FOO.test.md;
+// the final `.md` is asserted separately.
+const UPPERCASE_BASENAME_RE = /^[A-Z0-9._-]+\.md$/;
+
+export function isUppercaseFilename(filepath: string): boolean {
+  const base = path.basename(filepath);
+  return UPPERCASE_BASENAME_RE.test(base);
+}
+
+/**
+ * Normalise a single filename component (no directory) to the project's
+ * canonical shape: uppercase, spaces → hyphens, ASCII-only, collapse repeated
+ * hyphens. Strips a trailing `.md` if the caller passed one; appends a fresh
+ * `.md` always.
+ *
+ * Used by create_child + image upload code paths where filename derivation
+ * is driven by a title/slug rather than a literal user-provided path.
+ */
+export function normalizeBasename(input: string): string {
+  // Strip optional trailing `.md` (case-insensitive) so it doesn't get
+  // double-uppercased and we re-append exactly one.
+  const stripped = input.replace(/\.md$/i, "");
+  const upper = stripped
+    .toUpperCase()
+    // Whitespace → hyphen
+    .replace(/\s+/g, "-")
+    // Anything not [A-Z0-9._-] → drop
+    .replace(/[^A-Z0-9._-]/g, "")
+    // Collapse runs of hyphens
+    .replace(/-+/g, "-")
+    // Strip leading/trailing hyphens or dots
+    .replace(/^[-.]+|[-.]+$/g, "");
+  // Fall back to "DOC" if the input was all-non-ASCII.
+  const safe = upper || "DOC";
+  return `${safe}.md`;
+}
+
+/**
+ * Apply normalizeBasename to the filename portion of a full vault path,
+ * preserving the directory. Returns the corrected path.
+ *
+ *   normalizeFilenameInPath("images/photo-12-57.md")
+ *     → "images/PHOTO-12-57.md"
+ *   normalizeFilenameInPath("foo bar")
+ *     → "FOO-BAR.md"
+ */
+export function normalizeFilenameInPath(filepath: string): string {
+  const dir = path.dirname(filepath);
+  const base = path.basename(filepath);
+  const normalized = normalizeBasename(base);
+  return dir === "." ? normalized : `${dir}/${normalized}`;
+}

package/src/lib/mcp/tools/get_context.ts

@@ -0,0 +1,227 @@
+// SPRINT-018 Phase 4: multi-hop context loader. Given a focal doc, walk
+// the edge graph up to `hops` away and return the focal + neighbourhood
+// with bodies inlined within a token budget.
+//
+// Why not a SQL recursive CTE: loadVaultIndex already gives us the full
+// edge set in both local and cloud modes (Phase 3 wired cloud's edges
+// from doc_edges). BFS in JS is mode-agnostic — no new SQL migration
+// needed, and the post-Phase-3 cloud path still benefits from the
+// materialized table because the index load itself is cheap.
+
+import { loadVaultIndex } from "./vault";
+import { hashBody } from "./sections";
+import type { ToolContext } from "./types";
+import type { DocNode } from "../../../core/indexer";
+
+function json(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
+}
+
+type ContextKind = "focal" | "parent" | "child" | "assoc";
+
+interface ContextNode {
+  path: string;
+  title: string;
+  summary: string;
+  hop: number;
+  kind: ContextKind;
+  content?: string;
+  truncated?: boolean;
+}
+
+interface ContextResult {
+  focal: ContextNode;
+  neighbors: ContextNode[];
+  doc_content_hash: string;
+  budget: { used: number; limit: number; dropped_paths: string[] };
+}
+
+const DEFAULT_HOPS = 2;
+const MAX_HOPS = 3;
+const DEFAULT_BUDGET = 8000;
+// rough char-to-token ratio used elsewhere in the spec
+const CHARS_PER_TOKEN = 4;
+
+/**
+ * BFS the edge graph from `focalPath` out to `maxHops`. For each visited
+ * doc record its hop depth and the relationship kind that brought us
+ * there (parent / child / assoc) — when multiple paths lead to the same
+ * doc, the first arrival wins (shortest hop, and within a hop the kind
+ * priority parent < child < assoc via the edge iteration order below).
+ */
+function buildNeighborhood(
+  focalPath: string,
+  edges: Array<{ from: string; to: string; kind: "hierarchy" | "assoc" }>,
+  maxHops: number,
+  includeAssociates: boolean,
+): Map<string, { hop: number; kind: ContextKind }> {
+  // For each doc, what edges leave/enter it. We pre-classify directed
+  // hierarchy edges as "child" (focal points away) or "parent" (focal
+  // points back), and assoc edges as undirected pair-mates.
+  interface Neighbor { other: string; kind: "parent" | "child" | "assoc"; }
+  const adj = new Map<string, Neighbor[]>();
+  const push = (from: string, n: Neighbor) => {
+    const arr = adj.get(from) ?? [];
+    arr.push(n);
+    adj.set(from, arr);
+  };
+  for (const e of edges) {
+    if (e.kind === "hierarchy") {
+      // from = parent, to = child.
+      push(e.from, { other: e.to, kind: "child" });
+      push(e.to, { other: e.from, kind: "parent" });
+    } else {
+      if (!includeAssociates) continue;
+      // Assoc in our Edge[] (post-Phase-3 dedup) is single-row lo→hi;
+      // treat as undirected.
+      push(e.from, { other: e.to, kind: "assoc" });
+      push(e.to, { other: e.from, kind: "assoc" });
+    }
+  }
+
+  const visited = new Map<string, { hop: number; kind: ContextKind }>();
+  visited.set(focalPath, { hop: 0, kind: "focal" });
+
+  let frontier: string[] = [focalPath];
+  for (let hop = 1; hop <= maxHops; hop++) {
+    const next: string[] = [];
+    for (const path of frontier) {
+      const neighbors = adj.get(path) ?? [];
+      // Stable order: parents first, then children, then assocs (mirrors
+      // the spec's `(hop ASC, kind ASC, position ASC)`).
+      const sorted = neighbors.slice().sort((a, b) => kindRank(a.kind) - kindRank(b.kind));
+      for (const n of sorted) {
+        if (visited.has(n.other)) continue;
+        visited.set(n.other, { hop, kind: n.kind });
+        next.push(n.other);
+      }
+    }
+    if (next.length === 0) break;
+    frontier = next;
+  }
+  return visited;
+}
+
+function kindRank(k: "parent" | "child" | "assoc"): number {
+  if (k === "parent") return 0;
+  if (k === "child") return 1;
+  return 2;
+}
+
+export async function getContext(ctx: ToolContext, args: Record<string, unknown>): Promise<unknown> {
+  const focalPath = String(args.path);
+  const hops = Math.max(1, Math.min(MAX_HOPS, Number(args.hops ?? DEFAULT_HOPS)));
+  const budget = Math.max(0, Number(args.budget_tokens ?? DEFAULT_BUDGET));
+  const includeFull = args.include_full === undefined ? true : Boolean(args.include_full);
+  const includeAssociates = args.include_associates === undefined ? true : Boolean(args.include_associates);
+
+  const idx = await loadVaultIndex(ctx);
+  const focal = idx.docs.find((d) => d.path === focalPath);
+  if (!focal) throw new Error(`no such doc: ${focalPath}`);
+
+  // SPRINT-024 Phase 1: hash-conditional short-circuit. The hash is over the
+  // FOCAL doc's raw content — neighbourhood changes don't bust the cache,
+  // matching `get_doc`'s scope. Callers chasing a structural change must
+  // refetch unconditionally.
+  const docHash = hashBody(focal.content);
+  const expected = args.expected_content_hash !== undefined ? String(args.expected_content_hash) : "";
+  if (expected && expected === docHash) {
+    return json({ unchanged: true, path: focal.path, doc_content_hash: docHash });
+  }
+
+  const visited = buildNeighborhood(focalPath, idx.edges, hops, includeAssociates);
+  const byPath = new Map<string, DocNode>(idx.docs.map((d) => [d.path, d]));
+
+  // Order: focal, then by (hop ASC, kind ASC, path ASC) for determinism.
+  const sortedEntries = [...visited.entries()]
+    .filter(([p]) => byPath.has(p))
+    .sort((a, b) => {
+      if (a[0] === focalPath) return -1;
+      if (b[0] === focalPath) return 1;
+      const ha = a[1].hop;
+      const hb = b[1].hop;
+      if (ha !== hb) return ha - hb;
+      const ka = kindRank(a[1].kind as "parent" | "child" | "assoc");
+      const kb = kindRank(b[1].kind as "parent" | "child" | "assoc");
+      if (ka !== kb) return ka - kb;
+      return a[0].localeCompare(b[0]);
+    });
+
+  // Budget walk: focal + hop-1 docs get full body when include_full,
+  // hop-2+ get summary-only. As budget exhausts, body is dropped first;
+  // if even the summary-line overflows, the node is dropped entirely
+  // and surfaced in dropped_paths.
+  const limit = budget;
+  let used = 0;
+  const dropped: string[] = [];
+  let focalNode: ContextNode | null = null;
+  const neighbors: ContextNode[] = [];
+
+  for (const [p, meta] of sortedEntries) {
+    const doc = byPath.get(p)!;
+    const wantBody = includeFull && meta.hop <= 1;
+    // Always reserve cost for the summary line so dropped nodes are rare.
+    const summaryCost = Math.ceil((doc.summary.length + doc.title.length + p.length) / CHARS_PER_TOKEN);
+    if (used + summaryCost > limit && p !== focalPath) {
+      dropped.push(p);
+      continue;
+    }
+    const node: ContextNode = {
+      path: doc.path,
+      title: doc.title,
+      summary: doc.summary,
+      hop: meta.hop,
+      kind: meta.kind,
+    };
+    used += summaryCost;
+
+    if (wantBody) {
+      const bodyCost = Math.ceil(doc.content.length / CHARS_PER_TOKEN);
+      if (used + bodyCost <= limit) {
+        node.content = doc.content;
+        used += bodyCost;
+      } else {
+        // Out of budget for the body — flag truncation and leave the
+        // summary-only entry. Focal is the one exception: we always try
+        // to ship its body, truncating if necessary so the caller at
+        // least sees the head of the doc.
+        if (p === focalPath) {
+          const remaining = Math.max(0, limit - used);
+          const charBudget = remaining * CHARS_PER_TOKEN;
+          if (charBudget > 0) {
+            node.content = doc.content.slice(0, charBudget);
+            node.truncated = true;
+            used += Math.ceil(node.content.length / CHARS_PER_TOKEN);
+          } else {
+            node.truncated = true;
+          }
+        } else {
+          node.truncated = true;
+        }
+      }
+    }
+
+    if (p === focalPath) focalNode = node;
+    else neighbors.push(node);
+  }
+
+  // Edge case: the focal somehow got dropped (shouldn't happen — we
+  // skip the drop branch when p === focalPath above — but be defensive).
+  if (!focalNode) {
+    focalNode = {
+      path: focal.path,
+      title: focal.title,
+      summary: focal.summary,
+      hop: 0,
+      kind: "focal",
+    };
+  }
+
+  const result: ContextResult = {
+    focal: focalNode,
+    neighbors,
+    doc_content_hash: docHash,
+    budget: { used, limit, dropped_paths: dropped },
+  };
+  return json(result);
+}

package/src/lib/mcp/tools/get_doc.ts

@@ -0,0 +1,91 @@
+import { validatePath, readVaultFile } from "./vault";
+import { extractPreamble } from "./patch_preamble";
+import { parseSections, extractBody, hashBody, sectionId } from "./sections";
+import { deriveTitle, deriveSummary } from "../../../core/indexer";
+import type { ToolContext } from "./types";
+import { SYSTEM_NODES, SYSTEM_NODE_PATHS, systemNodeContent } from "../../system-nodes";
+
+// Re-export sectionId so historic call sites (`import { sectionId } from "./get_doc"`)
+// keep compiling without an audit-the-world rename.
+export { sectionId } from "./sections";
+
+function json(value: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
+}
+
+function text(value: string) {
+  return { content: [{ type: "text" as const, text: value }] };
+}
+
+/**
+ * Return doc metadata. SPRINT-018 Phase 5: the body is opt-in via
+ * `full=true`. The default response is light — title + summary +
+ * preamble + section headings.
+ *
+ * SPRINT-024 Phase 1: every response now carries `doc_content_hash`
+ * (sha256 first 16 hex of the raw file content). Pass it back via
+ * `expected_content_hash` on the next get_doc; if the doc hasn't
+ * changed we return `{ unchanged: true, path, doc_content_hash }` and
+ * skip the section-parse / preamble work entirely. Cheaper than fetching
+ * the doc just to discover nothing moved.
+ *
+ * SPRINT-038 v1: read the file directly via `readVaultFile` instead of
+ * pulling the full vault index. Title + summary are derived locally with
+ * the same primitives the indexer uses, so the response shape is
+ * byte-identical to the prior `loadVaultIndex` path. The cold-start win
+ * is avoiding the `listWithContent` cascade for a known-path lookup.
+ */
+export async function getDoc(ctx: ToolContext, args: Record<string, unknown>): Promise<unknown> {
+  const rel = String(args.path);
+  validatePath(rel);
+  let content = await readVaultFile(ctx, rel);
+  if (content === null) {
+    // Virtual system nodes are never stored per-user — serve their canonical
+    // content so MCP callers can read EMDEE/VAULT/SHARED/GRAVEYARD/IMAGES.
+    if (SYSTEM_NODE_PATHS.has(rel)) {
+      const node = SYSTEM_NODES.find((n) => n.path === rel)!;
+      content = systemNodeContent(node);
+    } else {
+      throw new Error(`no such doc: ${rel}`);
+    }
+  }
+
+  const docHash = hashBody(content);
+
+  const expected = args.expected_content_hash !== undefined ? String(args.expected_content_hash) : "";
+  if (expected && expected === docHash) {
+    return json({ unchanged: true, path: rel, doc_content_hash: docHash });
+  }
+
+  const full = Boolean(args.full);
+
+  // Plaintext mode short-circuit: bare markdown, no envelope.
+  // full=true → raw file. full=false → H1 + summary + section headings.
+  if (args.format === "text") {
+    if (full) return text(content);
+    const title = deriveTitle(rel, content);
+    const summary = deriveSummary(content);
+    const headings = parseSections(content).map((s) => `## ${s.heading}`);
+    const parts = [`# ${title}`];
+    if (summary) parts.push(`> ${summary}`);
+    if (headings.length) parts.push(headings.join("\n"));
+    return text(parts.join("\n\n"));
+  }
+
+  const sections = parseSections(content).map((s, idx) => ({
+    id: sectionId(s.heading, idx),
+    heading: s.heading,
+    content_hash: hashBody(extractBody(content, s)),
+  }));
+  const preamble = extractPreamble(content);
+  const payload: Record<string, unknown> = {
+    path: rel,
+    title: deriveTitle(rel, content),
+    summary: deriveSummary(content),
+    doc_content_hash: docHash,
+    preamble: preamble ?? undefined,
+    sections,
+  };
+  if (full) payload.content = content;
+  return json(payload);
+}