ralph-hero-mcp-server 2.5.42 → 2.5.51

package/dist/index.js

@@ -23,6 +23,7 @@ import { registerHygieneTools } from "./tools/hygiene-tools.js";
 import { registerDebugTools } from "./tools/debug-tools.js";
 import { registerDecomposeTools } from "./tools/decompose-tools.js";
 import { registerViewTools } from "./tools/view-tools.js";
+import { registerPlanGraphTools } from "./tools/plan-graph-tools.js";
 /**
  * Initialize the GitHub client from environment variables.
  */
@@ -304,6 +305,8 @@ async function main() {
     registerDecomposeTools(server, client, fieldCache);
     // View management tools (REST API view creation)
     registerViewTools(server, client, fieldCache);
+    // Plan graph sync tool (sync plan dependency edges to GitHub)
+    registerPlanGraphTools(server, client);
     // Debug tools (only when RALPH_DEBUG=true)
     if (process.env.RALPH_DEBUG === 'true') {
         registerDebugTools(server, client);

package/dist/lib/helpers.js

@@ -319,7 +319,8 @@ export function resolveConfig(client, args) {
     const owner = args.owner || client.config.owner;
     const repo = args.repo || client.config.repo;
     if (!owner)
-        throw new Error("owner is required (set RALPH_GH_OWNER env var or pass explicitly)");
+        throw new Error("owner is required. Set RALPH_GH_OWNER in ~/.claude/settings.json (user-scoped) " +
+            "or .claude/settings.local.json (project-scoped), or pass owner explicitly.");
     if (!repo)
         throw new Error("repo is required. Set RALPH_GH_REPO env var, pass repo explicitly, or link exactly one repo to your project.");
     return { owner, repo };
@@ -334,7 +335,8 @@ export function resolveConfig(client, args) {
 export function resolveConfigOptionalRepo(client, args) {
     const owner = args.owner || client.config.owner;
     if (!owner)
-        throw new Error("owner is required (set RALPH_GH_OWNER env var or pass explicitly)");
+        throw new Error("owner is required. Set RALPH_GH_OWNER in ~/.claude/settings.json (user-scoped) " +
+            "or .claude/settings.local.json (project-scoped), or pass owner explicitly.");
     const repo = args.repo || client.config.repo;
     return { owner, repo };
 }

package/dist/lib/plan-graph.js

@@ -0,0 +1,152 @@
+/**
+ * Plan dependency graph parser.
+ *
+ * Extracts issue-level dependency edges from plan markdown documents.
+ * Pure function — no I/O, no GitHub calls.
+ */
+/**
+ * Parse frontmatter from `---` fenced block at the start of content.
+ * Returns key-value pairs as raw strings.
+ */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return {};
+    const result = {};
+    for (const line of match[1].split("\n")) {
+        const colonIdx = line.indexOf(":");
+        if (colonIdx === -1)
+            continue;
+        const key = line.slice(0, colonIdx).trim();
+        const value = line.slice(colonIdx + 1).trim();
+        result[key] = value;
+    }
+    return result;
+}
+/**
+ * Parse a YAML-style inline array of numbers, e.g. `[660, 661, 662]`.
+ */
+function parseNumberArray(raw) {
+    const inner = raw.replace(/^\[/, "").replace(/\]$/, "");
+    if (!inner.trim())
+        return [];
+    return inner.split(",").map((s) => Number(s.trim()));
+}
+/**
+ * Parse a depends_on value like `[phase-1, phase-2]` or `[GH-44]` or `null`.
+ * Returns raw string references (e.g. "phase-1", "GH-44") or empty array for null/absent.
+ */
+function parseDependsOn(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === "null" || trimmed === "")
+        return [];
+    const inner = trimmed.replace(/^\[/, "").replace(/\]$/, "");
+    if (!inner.trim())
+        return [];
+    return inner.split(",").map((s) => s.trim());
+}
+/**
+ * Parse a plan markdown document and extract the dependency graph.
+ */
+export function parsePlanGraph(content) {
+    const frontmatter = parseFrontmatter(content);
+    const type = (frontmatter.type ?? "plan");
+    const issues = parseNumberArray(frontmatter.github_issues ?? "[]");
+    const primaryIssue = Number(frontmatter.primary_issue ?? "0");
+    const phaseToIssue = new Map();
+    const edges = [];
+    const lines = content.split("\n");
+    if (type === "plan") {
+        // Scan for ## Phase N: ... (GH-NNN) headings
+        const phasePattern = /^## Phase (\d+):.*\(GH-(\d+)\)/;
+        // First pass: build phaseToIssue map
+        for (const line of lines) {
+            const m = line.match(phasePattern);
+            if (m) {
+                phaseToIssue.set(Number(m[1]), Number(m[2]));
+            }
+        }
+        // Second pass: find depends_on after each phase heading
+        let currentPhaseIssue = null;
+        for (const line of lines) {
+            const phaseMatch = line.match(phasePattern);
+            if (phaseMatch) {
+                currentPhaseIssue = Number(phaseMatch[2]);
+                continue;
+            }
+            // Check for heading that would end the current phase section
+            if (/^##\s/.test(line) && !phaseMatch) {
+                currentPhaseIssue = null;
+                continue;
+            }
+            if (currentPhaseIssue !== null) {
+                const depMatch = line.match(/^\s*-\s+\*\*depends_on\*\*:\s*(.*)/);
+                if (depMatch) {
+                    const refs = parseDependsOn(depMatch[1]);
+                    for (const ref of refs) {
+                        const phaseRef = ref.match(/^phase-(\d+)$/);
+                        const ghRef = ref.match(/^GH-(\d+)$/);
+                        if (phaseRef) {
+                            const blockingIssue = phaseToIssue.get(Number(phaseRef[1]));
+                            if (blockingIssue !== undefined) {
+                                edges.push({
+                                    blocked: currentPhaseIssue,
+                                    blocking: blockingIssue,
+                                    source: "phase-level",
+                                });
+                            }
+                        }
+                        else if (ghRef) {
+                            edges.push({
+                                blocked: currentPhaseIssue,
+                                blocking: Number(ghRef[1]),
+                                source: "phase-level",
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    else {
+        // plan-of-plans: scan for ### Feature ...: ... (GH-NNN) headings
+        const featurePattern = /^### Feature [^:]+:.*\(GH-(\d+)\)/;
+        let currentFeatureIssue = null;
+        for (const line of lines) {
+            const featureMatch = line.match(featurePattern);
+            if (featureMatch) {
+                currentFeatureIssue = Number(featureMatch[1]);
+                continue;
+            }
+            // Check for any heading (h2 or h3) that would end the current feature section
+            if (/^##\s/.test(line) && !featureMatch) {
+                currentFeatureIssue = null;
+                continue;
+            }
+            if (currentFeatureIssue !== null) {
+                const depMatch = line.match(/^\s*-\s+\*\*depends_on\*\*:\s*(.*)/);
+                if (depMatch) {
+                    const refs = parseDependsOn(depMatch[1]);
+                    for (const ref of refs) {
+                        const ghRef = ref.match(/^GH-(\d+)$/);
+                        if (ghRef) {
+                            edges.push({
+                                blocked: currentFeatureIssue,
+                                blocking: Number(ghRef[1]),
+                                source: "feature-level",
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return {
+        type,
+        issues,
+        primaryIssue,
+        phaseToIssue,
+        edges,
+    };
+}
+//# sourceMappingURL=plan-graph.js.map

package/dist/lib/state-resolution.js

@@ -41,6 +41,7 @@ const COMMAND_ALLOWED_STATES = {
     ralph_research: ["Research in Progress", "Ready for Plan", "Human Needed"],
     ralph_plan: ["Plan in Progress", "Plan in Review", "In Progress", "Human Needed"],
     ralph_plan_epic: ["Plan in Progress", "In Progress", "Human Needed"],
+    ralph_pr: ["In Review", "Human Needed"],
     ralph_impl: ["In Progress", "In Review", "Human Needed"],
     ralph_review: ["In Progress", "Ready for Plan", "Human Needed"],
     ralph_hero: ["In Review", "Human Needed"],

package/dist/tools/plan-graph-tools.js

@@ -0,0 +1,204 @@
+/**
+ * MCP tool for syncing plan dependency graphs to GitHub.
+ *
+ * Reads a plan markdown document, extracts dependency edges via parsePlanGraph,
+ * diffs against existing GitHub blockedBy edges, and adds/removes edges to
+ * converge the graph.
+ */
+import { z } from "zod";
+import { readFile } from "fs/promises";
+import { parsePlanGraph } from "../lib/plan-graph.js";
+import { toolSuccess, toolError } from "../types.js";
+import { resolveIssueNodeId, resolveConfig } from "../lib/helpers.js";
+// ---------------------------------------------------------------------------
+// Pure function: diffDependencyEdges
+// ---------------------------------------------------------------------------
+/**
+ * Compute the diff between declared edges (from the plan) and existing edges
+ * (from GitHub), scoped to plan issues only.
+ *
+ * - added: edges in declared but not in existing
+ * - removed: edges in existing but not in declared, where BOTH endpoints are plan issues
+ * - unchanged: edges present in both declared and existing
+ *
+ * External edges (where one endpoint is outside the plan) are left alone.
+ *
+ * @param declared - Edges parsed from the plan document
+ * @param existing - Edges currently on GitHub (blockedBy relationships)
+ * @param planIssues - The set of issue numbers that belong to this plan
+ */
+export function diffDependencyEdges(declared, existing, planIssues) {
+    const edgeKey = (e) => `${e.blocked}:${e.blocking}`;
+    const declaredSet = new Set(declared.map(edgeKey));
+    const existingSet = new Set(existing.map(edgeKey));
+    const added = declared.filter((e) => !existingSet.has(edgeKey(e)));
+    const unchanged = declared.filter((e) => existingSet.has(edgeKey(e)));
+    const removed = existing.filter((e) => !declaredSet.has(edgeKey(e)) &&
+        planIssues.has(e.blocked) &&
+        planIssues.has(e.blocking));
+    return { added, removed, unchanged };
+}
+// ---------------------------------------------------------------------------
+// Register plan graph tools
+// ---------------------------------------------------------------------------
+export function registerPlanGraphTools(server, client) {
+    // -------------------------------------------------------------------------
+    // ralph_hero__sync_plan_graph
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__sync_plan_graph", "Sync a plan document's dependency graph to GitHub blockedBy edges. " +
+        "Reads the plan file, extracts dependency edges, diffs against existing GitHub edges " +
+        "scoped to plan issues, and adds missing / removes stale edges. " +
+        "Use dryRun=true to preview changes without mutating (default: false).", {
+        planPath: z
+            .string()
+            .describe("Absolute path to the plan markdown document"),
+        dryRun: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("When true, report what would change without mutating GitHub. Default: false."),
+    }, async (args) => {
+        try {
+            // Step 1: Read the plan file
+            let content;
+            try {
+                content = await readFile(args.planPath, "utf-8");
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return toolError(`Failed to read plan file: ${message}`);
+            }
+            // Step 2: Parse the dependency graph
+            const graph = parsePlanGraph(content);
+            if (graph.issues.length === 0) {
+                return toolError("Plan has no github_issues in frontmatter. Cannot sync dependencies.");
+            }
+            const planIssues = new Set(graph.issues);
+            const { owner, repo } = resolveConfig(client, {});
+            // Step 3: Query existing blockedBy edges for all plan issues
+            const existingEdges = [];
+            for (const issueNum of graph.issues) {
+                try {
+                    const result = await client.query(`query($owner: String!, $repo: String!, $number: Int!) {
+                repository(owner: $owner, name: $repo) {
+                  issue(number: $number) {
+                    blockedBy(first: 50) {
+                      nodes { number }
+                    }
+                  }
+                }
+              }`, { owner, repo, number: issueNum });
+                    const blockers = result.repository?.issue?.blockedBy?.nodes ?? [];
+                    for (const blocker of blockers) {
+                        existingEdges.push({
+                            blocked: issueNum,
+                            blocking: blocker.number,
+                            source: "phase-level", // source doesn't matter for existing edges
+                        });
+                    }
+                }
+                catch (err) {
+                    // If we can't query an issue, skip it — it may not exist yet
+                    const message = err instanceof Error ? err.message : String(err);
+                    console.error(`[ralph-hero] Warning: could not query blockedBy for #${issueNum}: ${message}`);
+                }
+            }
+            // Step 4: Diff
+            const diff = diffDependencyEdges(graph.edges, existingEdges, planIssues);
+            // Step 5: If dryRun, return diff without mutating
+            if (args.dryRun) {
+                return toolSuccess({
+                    dryRun: true,
+                    planPath: args.planPath,
+                    planType: graph.type,
+                    planIssues: graph.issues,
+                    added: diff.added.map((e) => ({
+                        blocked: e.blocked,
+                        blocking: e.blocking,
+                    })),
+                    removed: diff.removed.map((e) => ({
+                        blocked: e.blocked,
+                        blocking: e.blocking,
+                    })),
+                    unchanged: diff.unchanged.map((e) => ({
+                        blocked: e.blocked,
+                        blocking: e.blocking,
+                    })),
+                    errors: [],
+                });
+            }
+            // Step 6: Apply mutations
+            const errors = [];
+            // Add missing edges
+            for (const edge of diff.added) {
+                try {
+                    const blockedId = await resolveIssueNodeId(client, owner, repo, edge.blocked);
+                    const blockingId = await resolveIssueNodeId(client, owner, repo, edge.blocking);
+                    await client.mutate(`mutation($blockedId: ID!, $blockingId: ID!) {
+                addBlockedBy(input: {
+                  issueId: $blockedId,
+                  blockingIssueId: $blockingId
+                }) {
+                  issue { id number }
+                  blockingIssue { id number }
+                }
+              }`, { blockedId, blockingId });
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    errors.push({
+                        edge: `#${edge.blocked} blocked by #${edge.blocking}`,
+                        error: `addBlockedBy failed: ${message}`,
+                    });
+                }
+            }
+            // Remove stale edges
+            for (const edge of diff.removed) {
+                try {
+                    const blockedId = await resolveIssueNodeId(client, owner, repo, edge.blocked);
+                    const blockingId = await resolveIssueNodeId(client, owner, repo, edge.blocking);
+                    await client.mutate(`mutation($blockedId: ID!, $blockingId: ID!) {
+                removeBlockedBy(input: {
+                  issueId: $blockedId,
+                  blockingIssueId: $blockingId
+                }) {
+                  issue { id number }
+                  blockingIssue { id number }
+                }
+              }`, { blockedId, blockingId });
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    errors.push({
+                        edge: `#${edge.blocked} blocked by #${edge.blocking}`,
+                        error: `removeBlockedBy failed: ${message}`,
+                    });
+                }
+            }
+            return toolSuccess({
+                dryRun: false,
+                planPath: args.planPath,
+                planType: graph.type,
+                planIssues: graph.issues,
+                added: diff.added.map((e) => ({
+                    blocked: e.blocked,
+                    blocking: e.blocking,
+                })),
+                removed: diff.removed.map((e) => ({
+                    blocked: e.blocked,
+                    blocking: e.blocking,
+                })),
+                unchanged: diff.unchanged.map((e) => ({
+                    blocked: e.blocked,
+                    blocking: e.blocking,
+                })),
+                errors,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to sync plan graph: ${message}`);
+        }
+    });
+}
+//# sourceMappingURL=plan-graph-tools.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-hero-mcp-server",
-  "version": "2.5.42",
+  "version": "2.5.51",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",