buildanything 1.8.0 → 2.1.1

package/bin/buildanything-runtime.ts

@@ -0,0 +1,241 @@
+#!/usr/bin/env tsx
+/*
+ * buildanything runtime — entrypoint loaded by Claude Code plugin
+ * when SDK mode is enabled.
+ *
+ * Responsibilities:
+ *   - schema_version forward-compat check on docs/plans/.build-state.json
+ *   - --resume stale-edge recovery (Task 4.3.4)
+ *   - SDK/host compat probe (sdkActive = state file + CLAUDE_CODE_VERSION ok)
+ *   - logging
+ *
+ * Orchestrator MCP tools (state_save, write_lease, cycle_counter, scribe) are
+ * served over stdio by bin/mcp-servers/orchestrator-mcp.ts — registered via
+ * .claude-plugin/plugin.json's mcpServers block and auto-started by Claude
+ * Code. This runtime no longer registers them in-process.
+ */
+
+import process from "node:process";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import semver from "semver";
+
+interface PluginConfig {
+  config?: {
+    sdkStateFile?: string;
+    claudeCodeHostRange?: string;
+    sdkVersion?: string;
+    maxSupportedSchemaVersion?: number;
+  };
+}
+
+const RUNTIME_VERSION = "0.1.0";
+// Hardcoded fallback if plugin.json lacks maxSupportedSchemaVersion. Keep this
+// in sync with the `schema_version` table in protocols/state-schema.md.
+const MAX_SUPPORTED_SCHEMA_VERSION_FALLBACK = 2;
+// EX_CONFIG — configuration/state mismatch.
+const EXIT_SCHEMA_VERSION_REJECT = 78;
+const BUILD_STATE_PATH_REL = "docs/plans/.build-state.json";
+
+export interface SchemaVersionCheck {
+  accepted: boolean;
+  reason?: "too_new";
+  detected?: number;
+  max?: number;
+  message?: string;
+}
+
+// Pure: evaluate whether a parsed state file's schema_version is forward-
+// compatible with this runtime. Missing / non-numeric / ≤ max → accepted.
+// Only `> max` triggers a reject. Upgrade/migration for LOWER versions is
+// explicitly out of scope here (task 4.5.2 scope note).
+export function checkSchemaVersion(
+  state: unknown,
+  maxSupported: number,
+  stateFilePath: string,
+): SchemaVersionCheck {
+  if (!state || typeof state !== "object") return { accepted: true };
+  const raw = (state as Record<string, unknown>).schema_version;
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return { accepted: true };
+  if (raw <= maxSupported) return { accepted: true };
+  return {
+    accepted: false,
+    reason: "too_new",
+    detected: raw,
+    max: maxSupported,
+    message:
+      `buildanything: state file schema_version=${raw} exceeds supported maximum ${maxSupported} ` +
+      `(${stateFilePath}). Upgrade plugin to >=v${raw} or delete the state file. ` +
+      `See docs/migration/sdk-host-compat.md.`,
+  };
+}
+
+async function loadPluginConfig(): Promise<PluginConfig> {
+  const scriptPath = process.argv[1] ?? "";
+  const here = scriptPath ? dirname(scriptPath) : process.cwd();
+  const pluginJsonPath = resolve(here, "..", ".claude-plugin", "plugin.json");
+  const raw = await readFile(pluginJsonPath, "utf8");
+  return JSON.parse(raw) as PluginConfig;
+}
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+  const resumeRequested = argv.includes("--resume");
+
+  let pinned = "unknown";
+  let hostRange = "unknown";
+  let sdkStateFile = ".buildanything/sdk-state";
+  let maxSupportedSchemaVersion = MAX_SUPPORTED_SCHEMA_VERSION_FALLBACK;
+  try {
+    const plugin = await loadPluginConfig();
+    if (plugin.config?.sdkVersion) pinned = plugin.config.sdkVersion;
+    if (plugin.config?.claudeCodeHostRange) hostRange = plugin.config.claudeCodeHostRange;
+    if (plugin.config?.sdkStateFile) sdkStateFile = plugin.config.sdkStateFile;
+    if (
+      typeof plugin.config?.maxSupportedSchemaVersion === "number" &&
+      Number.isFinite(plugin.config.maxSupportedSchemaVersion)
+    ) {
+      maxSupportedSchemaVersion = plugin.config.maxSupportedSchemaVersion;
+    }
+    if (!plugin.config) {
+      console.warn("[buildanything-runtime] warning: plugin.json has no 'config' block; using unknown defaults");
+    }
+  } catch (err) {
+    console.warn(`[buildanything-runtime] warning: could not load plugin.json config (${(err as Error).message}); using unknown defaults`);
+  }
+
+  // [Task 4.5.2] Forward-reject state files with schema_version > max.
+  // Runs before any SDK/MCP wiring so an incompatible state file halts the
+  // whole session instead of silently stripping fields on next write.
+  const buildStatePath = resolve(process.cwd(), BUILD_STATE_PATH_REL);
+  try {
+    const raw = await readFile(buildStatePath, "utf8");
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      // Malformed JSON is NOT our concern here — other handlers surface it.
+      // Log for visibility and continue.
+      console.warn(
+        `[buildanything-runtime] warning: could not parse ${buildStatePath} for schema check (${(err as Error).message}); continuing`,
+      );
+      parsed = null;
+    }
+    const check = checkSchemaVersion(parsed, maxSupportedSchemaVersion, buildStatePath);
+    if (!check.accepted) {
+      process.stderr.write(`${check.message}\n`);
+      process.exit(EXIT_SCHEMA_VERSION_REJECT);
+    }
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") {
+      console.warn(
+        `[buildanything-runtime] warning: could not read ${buildStatePath} for schema check (${(err as Error).message}); continuing`,
+      );
+    }
+    // ENOENT → no state file yet (fresh project); nothing to reject.
+  }
+
+  console.log(`buildanything-runtime v${RUNTIME_VERSION} starting (sdk=${pinned}, hostRange=${hostRange})`);
+
+  if (resumeRequested) {
+    console.log("[buildanything-runtime] resume requested");
+    // [Task 4.3.4] --resume staleness decrement — clears a crashed
+    // backward edge (>60s old) by decrementing counters, so the retry
+    // isn't double-counted toward the escalate-to-user cap.
+    try {
+      const cycleCounter = await import("../src/orchestrator/mcp/cycle-counter.js");
+      const stateSaveModule = await import("../src/orchestrator/mcp/state-save.js");
+      let parsed: Record<string, unknown> | null = null;
+      try {
+        const raw = await readFile(buildStatePath, "utf8");
+        parsed = JSON.parse(raw) as Record<string, unknown>;
+      } catch (err) {
+        const code = (err as NodeJS.ErrnoException).code;
+        if (code === "ENOENT") {
+          process.stderr.write("buildanything: no active backward edge; --resume is a no-op.\n");
+        } else {
+          console.warn(
+            `[buildanything-runtime] warning: could not read ${buildStatePath} for --resume stale-edge check (${(err as Error).message}); continuing`,
+          );
+        }
+      }
+      if (parsed) {
+        if (!parsed.in_flight_backward_edge) {
+          process.stderr.write("buildanything: no active backward edge; --resume is a no-op.\n");
+        } else {
+          const cleared = cycleCounter.handleStaleEdge(parsed as unknown as import("../src/orchestrator/mcp/cycle-counter.js").CounterState);
+          if (cleared) {
+            stateSaveModule.stateSave(buildStatePath, parsed);
+            process.stderr.write(
+              "buildanything: cleared stale in_flight_backward_edge (>60s old); counters decremented. Resuming from last known good phase.\n",
+            );
+          } else {
+            process.stderr.write(
+              "buildanything: --resume requested but no stale edge detected; proceeding normally.\n",
+            );
+          }
+        }
+      }
+    } catch (err) {
+      console.warn(
+        `[buildanything-runtime] warning: --resume stale-edge check failed (${(err as Error).message}); continuing`,
+      );
+    }
+  }
+
+  const hostVersion = process.env.CLAUDE_CODE_VERSION;
+  let hostCompat = true;
+  if (!hostVersion) {
+    console.log("[buildanything-runtime] host version unavailable (CLAUDE_CODE_VERSION not set); skipping compat check");
+  } else if (semver.satisfies(hostVersion, hostRange)) {
+    console.log(`[buildanything-runtime] host version ${hostVersion} satisfies compat range ${hostRange}`);
+  } else {
+    hostCompat = false;
+  }
+
+  if (!hostCompat) {
+    console.warn(`[buildanything-runtime] host version ${hostVersion} outside compat range ${hostRange} — falling back to markdown mode.`);
+  }
+
+  const stateFilePath = resolve(process.cwd(), sdkStateFile);
+  let stateFileActive = false;
+  try {
+    const contents = (await readFile(stateFilePath, "utf8")).trim();
+    stateFileActive = contents === "on";
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") {
+      console.log(`[buildanything-runtime] debug: sdk state file missing at ${stateFilePath}; treating as off`);
+    } else {
+      console.warn(`[buildanything-runtime] warning: could not read sdk state file (${(err as Error).message}); treating as off`);
+    }
+  }
+  const sdkActive = stateFileActive && hostCompat;
+  console.log(`[buildanything-runtime] sdkActive=${sdkActive} (stateFile=${stateFileActive}, hostCompat=${hostCompat})`);
+
+  // Orchestrator MCP tools (scribe_decision [Task 1.2.4], acquire/release/list
+  // write-lease [Task 2.3.4], state_save/state_read/verify_integrity [Task
+  // 3.2.4], cycle_counter_check/clear_in_flight_edge/handle_stale_edge [Task
+  // 4.2.4]) are served over stdio by bin/mcp-servers/orchestrator-mcp.ts,
+  // registered through .claude-plugin/plugin.json's mcpServers block. The
+  // Agent SDK path no longer owns these tools — stdio is the single source.
+  // The adapters in bin/adapters/*.ts remain for any future in-process SDK
+  // path that wants to share the zod shapes.
+  void sdkActive;
+}
+
+function isCliEntry(): boolean {
+  // Run main() only when invoked as the CLI, not when imported by tests.
+  const entry = process.argv[1] ?? "";
+  return entry.endsWith("buildanything-runtime.ts") || entry.endsWith("buildanything-runtime.js");
+}
+
+if (isCliEntry()) {
+  main()
+    .then(() => process.exit(0))
+    .catch((err) => {
+      console.error("[buildanything-runtime] fatal:", err instanceof Error ? err.stack ?? err.message : err);
+      process.exit(1);
+    });
+}

package/bin/graph-index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+'use strict';
+
+// Thin shim: delegates to the graph indexer TypeScript entry via tsx.
+const { spawn } = require('child_process');
+const path = require('path');
+
+const tsEntry = path.join(__dirname, 'graph-index.ts');
+const child = spawn('npx', ['--no-install', 'tsx', tsEntry, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});
+
+child.on('error', (err) => {
+  process.stderr.write(`[graph-index shim] failed to spawn tsx: ${err.message}\n`);
+  process.exit(1);
+});

package/bin/graph-index.ts

@@ -0,0 +1,340 @@
+#!/usr/bin/env tsx
+
+import { readFileSync, statSync, readdirSync, existsSync, unlinkSync } from "node:fs";
+import { basename, resolve, join, relative, extname } from "node:path";
+import { createHash } from "node:crypto";
+import process from "node:process";
+import { extractProductSpec, extractDesignMd, extractDesignMdTokens, extractComponentManifest, extractPageSpec, extractArchitecture, extractSprintTasks, extractDecisionsJsonl, extractScreenshot, saveGraph } from "../src/graph/index.js";
+import type { GraphFragment } from "../src/graph/types.js";
+
+type ImageClass = "reference" | "brand_drift" | "dogfood";
+
+const VALID_IMAGE_CLASSES: ReadonlySet<string> = new Set(["reference", "brand_drift", "dogfood"]);
+const IMAGE_EXTENSIONS: ReadonlySet<string> = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif"]);
+
+function parseArgs(argv: string[]): { positional: string[]; imageClass: string | undefined } {
+  const positional: string[] = [];
+  let imageClass: string | undefined;
+  for (const arg of argv) {
+    if (arg.startsWith("--image-class=")) {
+      imageClass = arg.slice("--image-class=".length);
+    } else if (arg === "--image-class") {
+      // peek-ahead style not supported; require =VALUE form
+      process.stderr.write("[graph-index] error: --image-class requires =VALUE form (e.g. --image-class=reference)\n");
+      process.exit(64);
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { positional, imageClass };
+}
+
+function inferImageClassFromPath(absPath: string): ImageClass | null {
+  // Normalize trailing slash + lower-case scan against known suffixes.
+  const normalized = absPath.replace(/\/+$/, "");
+  if (normalized.endsWith("/design-references") || normalized.includes("/design-references/")) {
+    return "reference";
+  }
+  if (normalized.endsWith("/evidence/brand-drift") || normalized.includes("/evidence/brand-drift/")) {
+    return "brand_drift";
+  }
+  if (normalized.endsWith("/evidence/dogfood") || normalized.includes("/evidence/dogfood/")) {
+    return "dogfood";
+  }
+  return null;
+}
+
+function targetFileForClass(c: ImageClass): string {
+  switch (c) {
+    case "reference": return "slice-5-references.json";
+    case "brand_drift": return "slice-5-brand-drift.json";
+    case "dogfood": return "slice-5-dogfood.json";
+  }
+}
+
+function collectImageFiles(dir: string): string[] {
+  const files: string[] = [];
+  // Recurse one level — competitors/, inspiration/, screenshots/ subdirs are common.
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      try {
+        for (const sub of readdirSync(full, { withFileTypes: true })) {
+          if (sub.isFile() && IMAGE_EXTENSIONS.has(extname(sub.name).toLowerCase())) {
+            files.push(join(full, sub.name));
+          }
+        }
+      } catch { /* unreadable subdir */ }
+    } else if (entry.isFile() && IMAGE_EXTENSIONS.has(extname(entry.name).toLowerCase())) {
+      files.push(full);
+    }
+  }
+  return files.sort();
+}
+
+function indexImageDirectory(absPath: string, imageClass: ImageClass): void {
+  // TODO Slice 5 production: when imageClass === 'dogfood', read evidence/dogfood/findings.json side-channel to populate linked_finding_id per screenshot.
+  const imageFiles = collectImageFiles(absPath);
+
+  if (imageFiles.length === 0) {
+    // Per Slice 5 schema §11 scenario 1: empty directory writes empty fragment, does NOT fail.
+    process.stdout.write(`[graph-index] info — no images in ${absPath}, writing empty fragment\n`);
+  }
+
+  const allNodes: GraphFragment["nodes"] = [];
+  const allEdges: GraphFragment["edges"] = [];
+  const hashChunks: Buffer[] = [];
+  const warnings: string[] = [];
+  let successCount = 0;
+
+  for (const filePath of imageFiles) {
+    let bytes: Buffer;
+    try {
+      bytes = readFileSync(filePath);
+    } catch (err) {
+      const msg = `failed to read ${filePath}: ${err instanceof Error ? err.message : String(err)}`;
+      process.stderr.write(`[graph-index] warning: ${msg}\n`);
+      warnings.push(msg);
+      continue;
+    }
+    hashChunks.push(bytes);
+
+    try {
+      const result = extractScreenshot({
+        imagePath: relative(process.cwd(), filePath),
+        imageClass,
+        imageBytes: new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength),
+      });
+
+      if (!result.ok) {
+        const msg = `${filePath}: ${result.errors.map((e) => e.message).join("; ")}`;
+        warnings.push(msg);
+        continue;
+      }
+      allNodes.push(...result.nodes);
+      allEdges.push(...result.edges);
+      successCount++;
+    } catch (err) {
+      const msg = `${filePath}: ${err instanceof Error ? err.message : String(err)}`;
+      warnings.push(msg);
+      continue;
+    }
+  }
+
+  if (imageFiles.length > 0 && successCount === 0) {
+    for (const w of warnings) {
+      process.stderr.write(`[graph-index] warning: ${w}\n`);
+    }
+    process.exit(1);
+  }
+
+  const combined = Buffer.concat(hashChunks);
+  const combinedHash = combined.length > 0
+    ? createHash("sha256").update(combined).digest("hex")
+    : "0".repeat(64);
+
+  const relDir = relative(process.cwd(), absPath) + "/";
+
+  const fragment: GraphFragment = {
+    source_file: relDir,
+    source_sha: combinedHash,
+    produced_at: new Date().toISOString(),
+    version: 1,
+    schema: "buildanything-slice-5",
+    nodes: allNodes,
+    edges: allEdges,
+  };
+
+  const targetFile = targetFileForClass(imageClass);
+  saveGraph(process.cwd(), fragment, targetFile);
+  process.stdout.write(
+    `[graph-index] ok — ${fragment.nodes.length} nodes, ${fragment.edges.length} edges → .buildanything/graph/${targetFile}\n`,
+  );
+
+  if (imageFiles.length > 0) {
+    for (const w of warnings) {
+      process.stdout.write(`[graph-index] warning: ${w}\n`);
+    }
+    process.stdout.write(`[graph-index] indexed ${successCount}/${imageFiles.length} images; ${warnings.length} warnings\n`);
+  }
+}
+
+const { positional, imageClass: explicitImageClass } = parseArgs(process.argv.slice(2));
+const target = positional[0];
+
+if (!target) {
+  process.stderr.write(
+    "Usage: graph-index <path> [--image-class=reference|brand_drift|dogfood]\n" +
+    "  Recognized basenames: product-spec.md, DESIGN.md, component-manifest.md, architecture.md, sprint-tasks.md, decisions.jsonl\n" +
+    "  Directory mode: page-specs/ → indexes all *.md files inside\n" +
+    "  Image directory mode: design-references/ | evidence/brand-drift/ | evidence/dogfood/ → indexes all images\n" +
+    "  DESIGN.md produces both slice-2-dna.json (Pass 1) and slice-3-tokens.json (Pass 2, if tokens found)\n",
+  );
+  process.exit(64);
+}
+
+if (explicitImageClass !== undefined && !VALID_IMAGE_CLASSES.has(explicitImageClass)) {
+  process.stderr.write(`[graph-index] error: --image-class must be one of: reference, brand_drift, dogfood (got: ${explicitImageClass})\n`);
+  process.exit(64);
+}
+
+try {
+  const absPath = resolve(target);
+
+  // ── Directory mode ──────────────────────────────────────────────────
+  let isDir = false;
+  try { isDir = statSync(absPath).isDirectory(); } catch { /* not a dir */ }
+
+  if (isDir) {
+    // page-specs/ — Slice 3 markdown directory mode
+    if (basename(absPath) === "page-specs") {
+      const mdFiles = readdirSync(absPath)
+        .filter((f) => f.endsWith(".md"))
+        .sort();
+
+      if (mdFiles.length === 0) {
+        process.stderr.write(`[graph-index] error: no .md files found in directory: ${absPath}\n`);
+        process.exit(1);
+      }
+
+      const allNodes: GraphFragment["nodes"] = [];
+      const allEdges: GraphFragment["edges"] = [];
+      const contents: string[] = [];
+
+      for (const file of mdFiles) {
+        const filePath = join(absPath, file);
+        const content = readFileSync(filePath, "utf-8");
+        contents.push(content);
+        const result = extractPageSpec({ mdPath: filePath, mdContent: content });
+        if (!result.ok) {
+          for (const err of result.errors) {
+            process.stderr.write(`[graph-index] ${file} L${err.line}: ${err.message}\n`);
+          }
+          process.stderr.write(`[graph-index] fatal: page-spec parse failed for ${file}\n`);
+          process.exit(1);
+        }
+        allNodes.push(...result.fragment!.nodes);
+        allEdges.push(...result.fragment!.edges);
+      }
+
+      const combinedHash = createHash("sha256").update(contents.join("")).digest("hex");
+      const relDir = relative(process.cwd(), absPath) + "/";
+
+      const fragment: GraphFragment = {
+        source_file: relDir,
+        source_sha: combinedHash,
+        produced_at: new Date().toISOString(),
+        version: 1,
+        schema: "buildanything-slice-3",
+        nodes: allNodes,
+        edges: allEdges,
+      };
+
+      saveGraph(process.cwd(), fragment, "slice-3-pages.json");
+      process.stdout.write(
+        `[graph-index] ok — ${fragment.nodes.length} nodes, ${fragment.edges.length} edges → .buildanything/graph/slice-3-pages.json\n`,
+      );
+      process.exit(0);
+    }
+
+    // Slice 5 image-directory mode — explicit override OR path inference
+    const inferred = inferImageClassFromPath(absPath);
+    const resolvedClass = (explicitImageClass ?? inferred) as ImageClass | null;
+
+    if (resolvedClass !== null) {
+      indexImageDirectory(absPath, resolvedClass);
+      process.exit(0);
+    }
+
+    process.stderr.write(
+      `[graph-index] error: directory ${absPath} is not a recognized indexer target.\n` +
+      `  Markdown directory: page-specs/\n` +
+      `  Image directories (auto-detected): design-references/, evidence/brand-drift/, evidence/dogfood/\n` +
+      `  Or pass --image-class=reference|brand_drift|dogfood to force.\n`,
+    );
+    process.exit(64);
+  }
+
+  // ── File mode ───────────────────────────────────────────────────────
+  if (!(() => { try { readFileSync(absPath); return true; } catch { return false; } })()) {
+    process.stderr.write(
+      "Usage: graph-index <path>\n" +
+      "  Recognized basenames: product-spec.md, DESIGN.md, component-manifest.md, architecture.md, sprint-tasks.md, decisions.jsonl\n" +
+      "  Directory mode: pass a page-specs/ directory to index all *.md files inside\n",
+    );
+    process.exit(64);
+  }
+
+  const mdContent = readFileSync(absPath, "utf-8");
+  const base = basename(absPath);
+
+  let result;
+  let targetFile: string;
+  if (base === "product-spec.md") {
+    result = extractProductSpec({ mdPath: absPath, mdContent });
+    targetFile = "slice-1.json";
+  } else if (base === "DESIGN.md") {
+    result = extractDesignMd({ mdPath: absPath, mdContent });
+    targetFile = "slice-2-dna.json";
+  } else if (base === "component-manifest.md") {
+    result = extractComponentManifest({ mdPath: absPath, mdContent });
+    targetFile = "slice-2-manifest.json";
+  } else if (base === "architecture.md") {
+    result = extractArchitecture({ mdPath: absPath, mdContent });
+    targetFile = "slice-4-architecture.json";
+  } else if (base === "sprint-tasks.md") {
+    result = extractSprintTasks({ mdPath: absPath, mdContent });
+    targetFile = "slice-4-tasks.json";
+  } else if (base === "decisions.jsonl") {
+    result = extractDecisionsJsonl({ mdPath: absPath, mdContent });
+    targetFile = "slice-4-decisions.json";
+  } else {
+    process.stderr.write(
+      `Usage: graph-index <path>\n  Recognized basenames: product-spec.md, DESIGN.md, component-manifest.md, architecture.md, sprint-tasks.md, decisions.jsonl\n  Directory mode: pass a page-specs/ directory to index all *.md files inside\n  Got: ${base}\n`,
+    );
+    process.exit(64);
+  }
+
+  if (result.ok) {
+    const fragment = result.fragment!;
+    saveGraph(process.cwd(), fragment, targetFile);
+    process.stdout.write(
+      `[graph-index] ok — ${fragment.nodes.length} nodes, ${fragment.edges.length} edges → .buildanything/graph/${targetFile}\n`,
+    );
+  } else {
+    for (const err of result.errors) {
+      process.stderr.write(`[graph-index] L${err.line}: ${err.message}\n`);
+    }
+    process.exit(1);
+  }
+
+  // ── DESIGN.md Pass 2: tokens ────────────────────────────────────────
+  if (base === "DESIGN.md") {
+    const pass2 = extractDesignMdTokens({ mdPath: absPath, mdContent });
+    if (pass2.ok && pass2.fragment!.nodes.length > 0) {
+      saveGraph(process.cwd(), pass2.fragment!, "slice-3-tokens.json");
+      process.stdout.write(
+        `[graph-index] ok — ${pass2.fragment!.nodes.length} nodes, ${pass2.fragment!.edges.length} edges → .buildanything/graph/slice-3-tokens.json\n`,
+      );
+    } else if (!pass2.ok) {
+      for (const err of pass2.errors) {
+        process.stderr.write(`[graph-index] warning (Pass 2): L${err.line}: ${err.message}\n`);
+      }
+    }
+
+    if ((pass2.ok && pass2.fragment!.nodes.length === 0) || !pass2.ok) {
+      const stalePath = join(process.cwd(), ".buildanything", "graph", "slice-3-tokens.json");
+      try {
+        if (existsSync(stalePath)) {
+          unlinkSync(stalePath);
+          process.stdout.write("[graph-index] Pass 2 empty — removed stale slice-3-tokens.json\n");
+        }
+      } catch { /* best-effort */ }
+    }
+  }
+} catch (e: unknown) {
+  const msg = e instanceof Error ? e.message : String(e);
+  process.stderr.write(`[graph-index] fatal: ${msg}\n`);
+  process.exit(2);
+}

package/bin/mcp-servers/graph-mcp.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+'use strict';
+
+// Thin shim: delegates to the TypeScript entry via tsx.
+// Mirrors bin/buildanything-runtime.js and the hooks pattern so Claude Code
+// can launch this stdio MCP server without tsx installed globally.
+const { spawn } = require('child_process');
+const path = require('path');
+
+const tsEntry = path.join(__dirname, 'graph-mcp.ts');
+const child = spawn('npx', ['--no-install', 'tsx', tsEntry, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});
+
+child.on('error', (err) => {
+  process.stderr.write(`[graph-mcp shim] failed to spawn tsx: ${err.message}\n`);
+  process.exit(1);
+});