ralph-hero-mcp-server 2.4.13 → 2.4.15

package/dist/index.js

@@ -20,6 +20,7 @@ import { registerBatchTools } from "./tools/batch-tools.js";
 import { registerProjectManagementTools } from "./tools/project-management-tools.js";
 import { registerHygieneTools } from "./tools/hygiene-tools.js";
 import { registerRoutingTools } from "./tools/routing-tools.js";
+import { registerSyncTools } from "./tools/sync-tools.js";
 /**
  * Initialize the GitHub client from environment variables.
  */
@@ -251,6 +252,8 @@ async function main() {
     registerHygieneTools(server, client, fieldCache);
     // Routing config management tools
     registerRoutingTools(server, client, fieldCache);
+    // Cross-project sync tools
+    registerSyncTools(server, client, fieldCache);
     // Connect via stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/lib/routing-engine.js

@@ -0,0 +1,84 @@
+/**
+ * Routing rule matching engine.
+ *
+ * Evaluates routing rules against an issue context (repo, labels, type)
+ * and returns matched rules with their actions. Pure function — no I/O,
+ * no API calls, fully deterministic.
+ *
+ * Used by: configure_routing dry_run (#179), Actions routing script (#171).
+ */
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate routing rules against an issue context.
+ *
+ * Rules are evaluated top-to-bottom. Each rule's match criteria use AND
+ * logic (all specified criteria must match). Omitted criteria are vacuously
+ * true. The `negate` flag inverts the combined result.
+ *
+ * When `stopOnFirstMatch` is true (default), evaluation stops after the
+ * first matching rule. Set to false for fan-out routing (one issue →
+ * multiple projects).
+ */
+export function evaluateRules(config, issue) {
+    const results = [];
+    const stopOnFirst = config.stopOnFirstMatch ?? true;
+    for (let i = 0; i < config.rules.length; i++) {
+        const rule = config.rules[i];
+        if (rule.enabled === false)
+            continue;
+        let matched = matchesRule(rule.match, issue);
+        if (rule.match.negate)
+            matched = !matched;
+        if (matched) {
+            results.push({ rule, ruleIndex: i, matched: true, actions: rule.action });
+            if (stopOnFirst) {
+                return { matchedRules: results, stoppedEarly: true };
+            }
+        }
+    }
+    return { matchedRules: results, stoppedEarly: false };
+}
+// ---------------------------------------------------------------------------
+// Private Helpers
+// ---------------------------------------------------------------------------
+function matchesRule(criteria, issue) {
+    if (criteria.repo && !matchesRepo(criteria.repo, issue.repo))
+        return false;
+    if (criteria.labels && !matchesLabels(criteria.labels, issue.labels))
+        return false;
+    if (criteria.issueType && !matchesIssueType(criteria.issueType, issue.issueType))
+        return false;
+    return true;
+}
+function matchesRepo(pattern, repo) {
+    return matchesGlob(pattern.toLowerCase(), repo.toLowerCase());
+}
+function matchesLabels(criteria, issueLabels) {
+    const normalized = issueLabels.map((l) => l.toLowerCase());
+    if (criteria.any?.length) {
+        const hasAny = criteria.any.some((l) => normalized.includes(l.toLowerCase()));
+        if (!hasAny)
+            return false;
+    }
+    if (criteria.all?.length) {
+        const hasAll = criteria.all.every((l) => normalized.includes(l.toLowerCase()));
+        if (!hasAll)
+            return false;
+    }
+    return true;
+}
+function matchesIssueType(expected, actual) {
+    return expected.toLowerCase() === actual.toLowerCase();
+}
+function matchesGlob(pattern, input) {
+    const regexStr = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "\x00")
+        .replace(/\*/g, "[^/]*")
+        .replace(/\?/g, "[^/]")
+        .replace(/\x00/g, ".*");
+    return new RegExp(`^${regexStr}$`).test(input);
+}
+//# sourceMappingURL=routing-engine.js.map

package/dist/tools/sync-tools.js

@@ -0,0 +1,183 @@
+/**
+ * MCP tools for cross-project state synchronization.
+ *
+ * Provides `ralph_hero__sync_across_projects` to propagate Workflow State
+ * changes to all GitHub Projects an issue belongs to. Discovers project
+ * memberships via the `projectItems` GraphQL field on Issue nodes.
+ */
+import { z } from "zod";
+import { toolSuccess, toolError } from "../types.js";
+import { resolveIssueNodeId, resolveConfig } from "../lib/helpers.js";
+// ---------------------------------------------------------------------------
+// GraphQL queries and mutations
+// ---------------------------------------------------------------------------
+const SYNC_PROJECT_ITEMS_QUERY = `query($issueId: ID!) {
+  node(id: $issueId) {
+    ... on Issue {
+      projectItems(first: 20) {
+        nodes {
+          id
+          project { id number }
+          fieldValues(first: 20) {
+            nodes {
+              ... on ProjectV2ItemFieldSingleSelectValue {
+                __typename
+                name
+                field { ... on ProjectV2FieldCommon { name } }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}`;
+const PROJECT_FIELD_META_QUERY = `query($projectId: ID!) {
+  node(id: $projectId) {
+    ... on ProjectV2 {
+      fields(first: 20) {
+        nodes {
+          ... on ProjectV2SingleSelectField {
+            id
+            name
+            options { id name }
+          }
+        }
+      }
+    }
+  }
+}`;
+const UPDATE_FIELD_MUTATION = `mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
+  updateProjectV2ItemFieldValue(input: {
+    projectId: $projectId,
+    itemId: $itemId,
+    fieldId: $fieldId,
+    value: { singleSelectOptionId: $optionId }
+  }) {
+    projectV2Item { id }
+  }
+}`;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Fetch field metadata for a specific project. Returns only SingleSelectField
+ * entries (which have id, name, and options). Does not populate FieldOptionCache
+ * to avoid polluting the default project cache.
+ */
+async function fetchProjectFieldMeta(client, projectId) {
+    const result = await client.projectQuery(PROJECT_FIELD_META_QUERY, { projectId });
+    return (result.node?.fields?.nodes ?? []).filter((f) => !!f.id && !!f.options);
+}
+// ---------------------------------------------------------------------------
+// Register sync tools
+// ---------------------------------------------------------------------------
+export function registerSyncTools(server, client, _fieldCache) {
+    server.tool("ralph_hero__sync_across_projects", "Propagate a Workflow State change to all GitHub Projects an issue belongs to. " +
+        "Queries projectItems to find all project memberships, applies the target state " +
+        "to projects where current state differs. Idempotent: skips projects already at " +
+        "target state. Returns: list of projects synced and skipped with reasons.", {
+        owner: z.string().optional().describe("GitHub owner. Defaults to env var"),
+        repo: z.string().optional().describe("Repository name. Defaults to env var"),
+        number: z.number().describe("Issue number to sync"),
+        workflowState: z
+            .string()
+            .describe('Target Workflow State to propagate (e.g., "In Progress")'),
+        dryRun: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("If true, return affected projects without mutating (default: false)"),
+    }, async (args) => {
+        try {
+            const { owner, repo } = resolveConfig(client, args);
+            // 1. Resolve issue node ID
+            const issueNodeId = await resolveIssueNodeId(client, owner, repo, args.number);
+            // 2. Fetch all project memberships + current Workflow State
+            const projectItemsResult = await client.projectQuery(SYNC_PROJECT_ITEMS_QUERY, { issueId: issueNodeId });
+            const projectItems = projectItemsResult.node?.projectItems?.nodes ?? [];
+            if (!projectItems.length) {
+                return toolSuccess({
+                    number: args.number,
+                    message: "Issue is not a member of any GitHub Project",
+                    synced: [],
+                    skipped: [],
+                });
+            }
+            const synced = [];
+            const skipped = [];
+            for (const item of projectItems) {
+                const projectId = item.project.id;
+                const projectNumber = item.project.number;
+                // Extract current Workflow State from fieldValues
+                const currentState = item.fieldValues.nodes.find((fv) => fv.__typename === "ProjectV2ItemFieldSingleSelectValue" &&
+                    fv.field?.name === "Workflow State")?.name ?? null;
+                // Idempotency: skip if already at target state
+                if (currentState === args.workflowState) {
+                    skipped.push({
+                        projectNumber,
+                        reason: "already_at_target_state",
+                        currentState,
+                    });
+                    continue;
+                }
+                if (args.dryRun) {
+                    synced.push({
+                        projectNumber,
+                        currentState,
+                        targetState: args.workflowState,
+                        dryRun: true,
+                    });
+                    continue;
+                }
+                // Fetch field IDs for this project
+                const fieldMeta = await fetchProjectFieldMeta(client, projectId);
+                const wfField = fieldMeta.find((f) => f.name === "Workflow State");
+                if (!wfField) {
+                    skipped.push({
+                        projectNumber,
+                        reason: "no_workflow_state_field",
+                        currentState,
+                    });
+                    continue;
+                }
+                const targetOption = wfField.options.find((o) => o.name === args.workflowState);
+                if (!targetOption) {
+                    skipped.push({
+                        projectNumber,
+                        reason: "invalid_option",
+                        currentState,
+                        detail: `"${args.workflowState}" not found. Valid: ${wfField.options.map((o) => o.name).join(", ")}`,
+                    });
+                    continue;
+                }
+                // Apply the update
+                await client.projectMutate(UPDATE_FIELD_MUTATION, {
+                    projectId,
+                    itemId: item.id,
+                    fieldId: wfField.id,
+                    optionId: targetOption.id,
+                });
+                synced.push({
+                    projectNumber,
+                    currentState,
+                    targetState: args.workflowState,
+                });
+            }
+            return toolSuccess({
+                number: args.number,
+                workflowState: args.workflowState,
+                dryRun: args.dryRun,
+                syncedCount: synced.length,
+                skippedCount: skipped.length,
+                synced,
+                skipped,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to sync across projects: ${message}`);
+        }
+    });
+}
+//# sourceMappingURL=sync-tools.js.map

package/package.json

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