ralph-hero-mcp-server 2.5.24 → 2.5.50

package/dist/github-client.js

@@ -166,6 +166,27 @@ export function createGitHubClient(clientConfig, debugLogger) {
             cache.set(cacheKey, login, 60 * 60 * 1000); // Cache for 1 hour
             return login;
         },
+        async restPost(path, body, useProjectToken = true) {
+            const token = useProjectToken
+                ? (clientConfig.projectToken ?? clientConfig.token)
+                : clientConfig.token;
+            const url = `https://api.github.com${path}`;
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    Authorization: `token ${token}`,
+                    Accept: "application/vnd.github+json",
+                    "X-GitHub-Api-Version": "2022-11-28",
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                const text = await response.text().catch(() => "");
+                throw new Error(`GitHub REST API error ${response.status} for ${path}: ${text}`);
+            }
+            return response.json();
+        },
     };
 }
 //# sourceMappingURL=github-client.js.map

package/dist/index.js

@@ -22,6 +22,8 @@ import { registerProjectManagementTools } from "./tools/project-management-tools
 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.
  */
@@ -301,6 +303,10 @@ async function main() {
     registerHygieneTools(server, client, fieldCache);
     // Decompose feature tool (cross-repo decomposition via .ralph-repos.yml)
     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/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/dist/tools/project-tools.js

@@ -386,6 +386,52 @@ async function fetchProject(client, owner, number) {
     }
     return null;
 }
+const VIEWS_QUERY_USER = `
+  query($login: String!, $number: Int!) {
+    user(login: $login) {
+      projectV2(number: $number) {
+        views(first: 50) {
+          nodes { id name number layout filter }
+        }
+      }
+    }
+  }
+`;
+const VIEWS_QUERY_ORG = `
+  query($login: String!, $number: Int!) {
+    organization(login: $login) {
+      projectV2(number: $number) {
+        views(first: 50) {
+          nodes { id name number layout filter }
+        }
+      }
+    }
+  }
+`;
+/**
+ * Fetch project views via GraphQL with user→org fallback.
+ * Returns views AND the resolved ownerType so callers can construct
+ * the correct REST API path without a separate round-trip.
+ */
+export async function fetchProjectViews(client, owner, projectNumber) {
+    // Try user first
+    try {
+        const result = await client.projectQuery(VIEWS_QUERY_USER, { login: owner, number: projectNumber });
+        const nodes = result.user?.projectV2?.views?.nodes;
+        if (nodes)
+            return { views: nodes, ownerType: "users" };
+    }
+    catch {
+        // fall through to org
+    }
+    // Try org
+    const result = await client.projectQuery(VIEWS_QUERY_ORG, { login: owner, number: projectNumber });
+    const nodes = result.organization?.projectV2?.views?.nodes;
+    if (!nodes) {
+        throw new Error(`Project #${projectNumber} not found for owner "${owner}"`);
+    }
+    return { views: nodes, ownerType: "orgs" };
+}
 async function createSingleSelectField(client, projectId, fieldName, options) {
     const result = await client.projectMutate(`mutation($projectId: ID!, $name: String!, $dataType: ProjectV2CustomFieldType!, $singleSelectOptions: [ProjectV2SingleSelectFieldOptionInput!]) {
       createProjectV2Field(input: {

package/dist/tools/view-tools.js

@@ -0,0 +1,102 @@
+/**
+ * MCP tools for GitHub Projects V2 view management.
+ *
+ * Copies views from a source project (read via GraphQL) to a target
+ * project using the REST API POST endpoint.
+ */
+import { z } from "zod";
+import { toolError, toolSuccess } from "../types.js";
+import { fetchProjectViews } from "./project-tools.js";
+/**
+ * Convert GraphQL layout enum to REST API layout value.
+ * All three variants are handled exhaustively — TypeScript will error
+ * at build time if a new layout variant is added and not handled here.
+ */
+export function toRestLayout(layout) {
+    switch (layout) {
+        case "TABLE_LAYOUT":
+            return "table";
+        case "BOARD_LAYOUT":
+            return "board";
+        case "ROADMAP_LAYOUT":
+            return "roadmap";
+    }
+}
+export function registerViewTools(server, client, _fieldCache) {
+    server.tool("ralph_hero__create_views", "Copy views from a source GitHub Project V2 to a target project using the REST API. Reads view names, layouts, and filter strings from the source project via GraphQL, then creates matching views in the target. Note: sort/group configuration is not available via API and must be set manually after creation.", {
+        owner: z
+            .string()
+            .optional()
+            .describe("GitHub owner (user or org). Defaults to RALPH_GH_OWNER env var"),
+        sourceProjectNumber: z.coerce
+            .number()
+            .describe("Project number to copy views FROM"),
+        targetProjectNumber: z.coerce
+            .number()
+            .describe("Project number to copy views INTO"),
+    }, async (args) => {
+        const owner = args.owner ?? client.config.projectOwner ?? client.config.owner;
+        if (!owner) {
+            return toolError("owner is required — set RALPH_GH_OWNER or pass owner param");
+        }
+        // Read views from source project; ownerType drives REST path selection
+        let sourceViews;
+        let ownerType;
+        try {
+            const result = await fetchProjectViews(client, owner, args.sourceProjectNumber);
+            sourceViews = result.views;
+            ownerType = result.ownerType;
+        }
+        catch (err) {
+            return toolError(`Failed to read views from project #${args.sourceProjectNumber}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (sourceViews.length === 0) {
+            return toolSuccess({
+                created: [],
+                failed: [],
+                count: 0,
+                sourceProject: args.sourceProjectNumber,
+                targetProject: args.targetProjectNumber,
+                message: "Source project has no views",
+            });
+        }
+        // REST path uses owner login (not numeric ID).
+        // filter is a plain top-level string matching the GraphQL field value.
+        const basePath = ownerType === "users"
+            ? `/users/${owner}/projectsV2/${args.targetProjectNumber}/views`
+            : `/orgs/${owner}/projectsV2/${args.targetProjectNumber}/views`;
+        const created = [];
+        const failed = [];
+        for (const view of sourceViews) {
+            const body = {
+                name: view.name,
+                layout: toRestLayout(view.layout),
+            };
+            if (view.filter) {
+                body.filter = view.filter;
+            }
+            try {
+                const createdView = await client.restPost(basePath, body);
+                created.push({
+                    name: createdView.name,
+                    layout: createdView.layout,
+                    id: createdView.id,
+                });
+            }
+            catch (err) {
+                failed.push({
+                    name: view.name,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return toolSuccess({
+            created,
+            failed,
+            count: created.length,
+            sourceProject: args.sourceProjectNumber,
+            targetProject: args.targetProjectNumber,
+        });
+    });
+}
+//# sourceMappingURL=view-tools.js.map

package/package.json

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