ralph-hero-mcp-server 2.4.15 → 2.4.16

package/dist/lib/routing-config.js

@@ -0,0 +1,100 @@
+/**
+ * Routing config loader and live validation.
+ *
+ * Two-phase validation:
+ * 1. Structural: YAML parse + Zod schema validation (loadRoutingConfig)
+ * 2. Referential: field option checks against FieldOptionCache (validateRulesLive)
+ *
+ * Consumers:
+ * - #178 configure_routing tool: loads config for CRUD operations
+ * - #179 validate_rules operation: calls validateRulesLive
+ */
+import { readFile } from "fs/promises";
+import { parse as yamlParse } from "yaml";
+import { RoutingConfigSchema } from "./routing-types.js";
+const DEFAULT_CONFIG = {
+    version: 1,
+    stopOnFirstMatch: true,
+    rules: [],
+};
+/**
+ * Load and validate a routing config file.
+ *
+ * Returns a discriminated union:
+ * - "loaded": valid config parsed from file
+ * - "missing": file not found, returns default empty config
+ * - "error": YAML parse or schema validation errors
+ */
+export async function loadRoutingConfig(configPath) {
+    // Read file — gracefully handle missing files
+    let contents;
+    try {
+        contents = await readFile(configPath, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return { status: "missing", config: DEFAULT_CONFIG };
+        }
+        throw err;
+    }
+    // Parse YAML
+    let parsed;
+    try {
+        parsed = yamlParse(contents);
+    }
+    catch (err) {
+        return {
+            status: "error",
+            errors: [
+                {
+                    phase: "yaml_parse",
+                    path: [],
+                    message: err instanceof Error ? err.message : String(err),
+                },
+            ],
+        };
+    }
+    // Validate against Zod schema
+    const result = RoutingConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const errors = result.error.issues.map((issue) => ({
+            phase: "schema_validation",
+            path: issue.path.map(String),
+            message: issue.message,
+        }));
+        return { status: "error", errors };
+    }
+    return { status: "loaded", config: result.data, filePath: configPath };
+}
+/**
+ * Validate routing rules against live project field data.
+ *
+ * Checks that referenced workflow states exist in the FieldOptionCache.
+ * The caller must ensure the cache is populated (via ensureFieldCache)
+ * before calling this function.
+ *
+ * Skips disabled rules (enabled === false).
+ */
+export function validateRulesLive(config, fieldCache) {
+    const errors = [];
+    for (let i = 0; i < config.rules.length; i++) {
+        const rule = config.rules[i];
+        // Skip disabled rules
+        if (rule.enabled === false)
+            continue;
+        // Validate workflowState references
+        if (rule.action.workflowState) {
+            const optionId = fieldCache.resolveOptionId("Workflow State", rule.action.workflowState);
+            if (optionId === undefined) {
+                const valid = fieldCache.getOptionNames("Workflow State");
+                errors.push({
+                    phase: "live_validation",
+                    path: ["rules", String(i), "action", "workflowState"],
+                    message: `Workflow state "${rule.action.workflowState}" not found in project. Valid: ${valid.join(", ")}`,
+                });
+            }
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=routing-config.js.map

package/dist/tools/routing-tools.js

@@ -1,21 +1,32 @@
 /**
  * MCP tool for managing routing rules in .ralph-routing.yml.
  *
- * Provides a single `ralph_hero__configure_routing` tool with four
- * CRUD operations: list_rules, add_rule, update_rule, remove_rule.
+ * Provides a single `ralph_hero__configure_routing` tool with six
+ * operations: list_rules, add_rule, update_rule, remove_rule,
+ * validate_rules, dry_run.
  */
 import fs from "node:fs/promises";
 import { parse, stringify } from "yaml";
 import { z } from "zod";
-import { toolSuccess, toolError } from "../types.js";
+import { toolSuccess, toolError, resolveProjectOwner } from "../types.js";
+import { ensureFieldCache } from "../lib/helpers.js";
+import { validateRoutingConfig } from "../lib/routing-types.js";
+import { evaluateRules } from "../lib/routing-engine.js";
 // ---------------------------------------------------------------------------
 // Register routing tools
 // ---------------------------------------------------------------------------
-export function registerRoutingTools(server, _client, _fieldCache) {
-    server.tool("ralph_hero__configure_routing", "Manage routing rules in .ralph-routing.yml. CRUD operations: list, add, update, remove rules. Config path: configPath arg > RALPH_ROUTING_CONFIG env var > .ralph-routing.yml. Returns: updated rule list and configPath.", {
+export function registerRoutingTools(server, client, fieldCache) {
+    server.tool("ralph_hero__configure_routing", "Manage routing rules in .ralph-routing.yml. Operations: list_rules, add_rule, update_rule, remove_rule (CRUD), validate_rules (check field references), dry_run (simulate matching for an issue). Config path: configPath arg > RALPH_ROUTING_CONFIG env var > .ralph-routing.yml.", {
         operation: z
-            .enum(["list_rules", "add_rule", "update_rule", "remove_rule"])
-            .describe("CRUD operation to perform"),
+            .enum([
+            "list_rules",
+            "add_rule",
+            "update_rule",
+            "remove_rule",
+            "validate_rules",
+            "dry_run",
+        ])
+            .describe("Operation to perform"),
         configPath: z
             .string()
             .optional()
@@ -37,6 +48,10 @@ export function registerRoutingTools(server, _client, _fieldCache) {
             .number()
             .optional()
             .describe("Zero-based rule index (required for update_rule, remove_rule)"),
+        issueNumber: z
+            .number()
+            .optional()
+            .describe("Issue number (required for dry_run)"),
     }, async (args) => {
         const configPath = args.configPath ??
             process.env.RALPH_ROUTING_CONFIG ??
@@ -73,6 +88,77 @@ export function registerRoutingTools(server, _client, _fieldCache) {
                     config.rules = config.rules.filter((_, i) => i !== args.ruleIndex);
                     await fs.writeFile(configPath, stringify(config, { lineWidth: 0 }));
                     return toolSuccess({ rules: config.rules, configPath });
+                case "validate_rules": {
+                    const errors = [];
+                    // Populate field cache for the default project
+                    const projectOwner = resolveProjectOwner(client.config);
+                    const projectNumber = client.config.projectNumber;
+                    if (projectOwner && projectNumber) {
+                        await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
+                    }
+                    for (let i = 0; i < config.rules.length; i++) {
+                        const rule = config.rules[i];
+                        if (rule.action.workflowState) {
+                            const optionId = fieldCache.resolveOptionId("Workflow State", rule.action.workflowState);
+                            if (optionId === undefined) {
+                                const valid = fieldCache.getOptionNames("Workflow State");
+                                errors.push({
+                                    ruleIndex: i,
+                                    field: "action.workflowState",
+                                    message: `"${rule.action.workflowState}" is not a valid Workflow State. Valid: ${valid.join(", ")}`,
+                                });
+                            }
+                        }
+                    }
+                    return toolSuccess({
+                        valid: errors.length === 0,
+                        ruleCount: config.rules.length,
+                        errors,
+                        configPath,
+                    });
+                }
+                case "dry_run": {
+                    if (!args.issueNumber) {
+                        return toolError("issueNumber is required for dry_run operation");
+                    }
+                    const owner = client.config.owner;
+                    const repo = client.config.repo;
+                    if (!owner || !repo) {
+                        return toolError("owner and repo must be configured (set RALPH_GH_OWNER and RALPH_GH_REPO env vars)");
+                    }
+                    // Parse config through Zod for proper RoutingConfig type
+                    const typedConfig = validateRoutingConfig(raw ? parse(raw) : { version: 1, rules: [] });
+                    // Fetch issue details
+                    const issueResult = await client.query(`query($owner: String!, $repo: String!, $issueNum: Int!) {
+                repository(owner: $owner, name: $repo) {
+                  issue(number: $issueNum) {
+                    number
+                    title
+                    labels(first: 20) { nodes { name } }
+                    repository { nameWithOwner }
+                  }
+                }
+              }`, { owner, repo, issueNum: args.issueNumber });
+                    const issue = issueResult.repository?.issue;
+                    if (!issue) {
+                        return toolError(`Issue #${args.issueNumber} not found in ${owner}/${repo}`);
+                    }
+                    const issueContext = {
+                        repo: issue.repository.nameWithOwner,
+                        labels: issue.labels.nodes.map((l) => l.name),
+                        issueType: "issue",
+                    };
+                    const evalResult = evaluateRules(typedConfig, issueContext);
+                    return toolSuccess({
+                        issueNumber: args.issueNumber,
+                        issueTitle: issue.title,
+                        issueContext,
+                        matchedRules: evalResult.matchedRules,
+                        stoppedEarly: evalResult.stoppedEarly,
+                        note: "No mutations performed -- dry run only",
+                        configPath,
+                    });
+                }
             }
         }
         catch (error) {

package/package.json

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