ralph-hero-mcp-server 2.5.119 → 2.5.120

package/dist/index.js

@@ -16,6 +16,7 @@ import { FieldOptionCache } from "./lib/cache.js";
 import { createDebugLogger, wrapServerToolWithLogging } from "./lib/debug-logger.js";
 import { toolSuccess, resolveProjectOwner } from "./types.js";
 import { resolveRepoFromProject } from "./lib/helpers.js";
+import { detectOrphanRepoIssues } from "./lib/health.js";
 import { registerProjectTools } from "./tools/project-tools.js";
 import { registerIssueTools } from "./tools/issue-tools.js";
 import { registerRelationshipTools } from "./tools/relationship-tools.js";
@@ -188,7 +189,7 @@ function initGitHubClient(debugLogger) {
  */
 function registerCoreTools(server, client) {
     // Health check tool - comprehensive validation of auth, repo, project, and fields
-    server.tool("ralph_hero__health_check", "Validate GitHub API connectivity, token permissions, repo access, project access, and required fields", {}, async () => {
+    server.tool("ralph_hero__health_check", "Validate GitHub API connectivity, token permissions, repo access, project access, and required fields. Also surfaces repo-scope mismatch via the `orphanRepoIssues` field when OPEN issues exist in the repo but are NOT on the configured project board (such issues are invisible to discovery tools like next_actions, list_issues, pipeline_dashboard, project_hygiene). The field is omitted entirely when the board contains every OPEN repo issue. Shape when present: `{ count, repoOpen, boardItems, sample: number[], note }` — `sample` is up to 10 orphan issue numbers (ascending) for diagnostic display.", {}, async () => {
         const checks = {};
         // 1. Auth check (repo token)
         try {
@@ -297,6 +298,26 @@ function registerCoreTools(server, client) {
                 detail: "RALPH_GH_PROJECT_NUMBER not set",
             };
         }
+        // 5. Orphan repo issues check — only runs when both repo and project
+        // access succeeded above. Failures here are non-fatal: orphan detection
+        // is informational and shouldn't downgrade the overall health status,
+        // because the underlying access checks already capture the real failure
+        // mode (broken token, missing project, etc.).
+        let orphanRepoIssues = null;
+        if (checks.repoAccess?.status === "ok" &&
+            checks.projectAccess?.status === "ok" &&
+            client.config.owner &&
+            client.config.repo &&
+            projOwner &&
+            projNum) {
+            try {
+                orphanRepoIssues = await detectOrphanRepoIssues(client, client.config.owner, client.config.repo, projOwner, projNum);
+            }
+            catch (e) {
+                // Non-fatal — log via stderr but don't fail health_check.
+                console.error(`[ralph-hero] Orphan repo issues check failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
         // Token source detection — re-derive which env vars resolved
         const repoTokenSource = resolveEnv("RALPH_GH_REPO_TOKEN")
             ? "RALPH_GH_REPO_TOKEN"
@@ -327,6 +348,9 @@ function registerCoreTools(server, client) {
                     ? `Repo operations use ${repoTokenSource}, project operations use ${projectTokenSource}`
                     : `Both repo and project operations use ${repoTokenSource}`,
             },
+            // Omit the field entirely when there are no orphans, per the field's
+            // contract (`null` from `detectOrphanRepoIssues` means "clean board").
+            ...(orphanRepoIssues ? { orphanRepoIssues } : {}),
         });
     });
 }

package/dist/lib/health.js

@@ -0,0 +1,180 @@
+/**
+ * Health-check helpers — pure functions that probe the GitHub API for
+ * configuration drift between the project board and its underlying repo.
+ *
+ * `detectOrphanRepoIssues` compares the set of OPEN issues in the configured
+ * repo against the set of `type=ISSUE` items on the configured project
+ * board. Issues present in the repo but not on the board are "orphans" —
+ * they exist but are structurally invisible to the discovery tools
+ * (`next_actions`, `list_issues`, `pipeline_dashboard`, `project_hygiene`),
+ * which all read from the project board.
+ *
+ * Surfaced via `health_check` so users discover the mismatch without having
+ * to grep `gh issue list` against the board contents by hand.
+ */
+/**
+ * Maximum number of orphan issue numbers to include in the response sample.
+ * The sample is for diagnostic display only; the full set is summarized via `count`.
+ */
+export const ORPHAN_SAMPLE_LIMIT = 10;
+/**
+ * Page size used when paginating repo issues and project items.
+ *
+ * GitHub GraphQL caps `first:` at 100. Most projects fit comfortably in a
+ * handful of pages — pagination is implemented for correctness, not because
+ * every call hits it.
+ */
+const PAGE_SIZE = 100;
+/**
+ * Hard cap on pages walked when enumerating repo issues or project items.
+ * Defensive: prevents a runaway loop on a misconfigured giant repo.
+ */
+const MAX_PAGES = 20;
+/**
+ * Standard explanatory note attached to the orphan-repo-issues warning.
+ * Lifted to a constant so tests can assert against a single canonical string.
+ */
+export const ORPHAN_REPO_ISSUES_NOTE = "Issues exist in the repo that are not on the project board. They are " +
+    "invisible to discovery tools (next_actions, list_issues, pipeline_dashboard, " +
+    "project_hygiene). To make them visible, add them to the project or use " +
+    "'gh issue list' directly.";
+/**
+ * Fetch all OPEN issue numbers in the repo via paginated GraphQL.
+ *
+ * Returns `{ totalCount, numbers }`. `totalCount` is taken from the first
+ * page (it is constant across pages). `numbers` is the union of all
+ * `node.number` values walked.
+ */
+async function fetchRepoOpenIssueNumbers(client, owner, repo) {
+    const numbers = new Set();
+    let totalCount = 0;
+    let cursor = null;
+    let pages = 0;
+    while (pages < MAX_PAGES) {
+        const response = await client.query(`query($owner: String!, $repo: String!, $cursor: String, $first: Int!) {
+        repository(owner: $owner, name: $repo) {
+          issues(states: OPEN, first: $first, after: $cursor) {
+            totalCount
+            pageInfo { hasNextPage endCursor }
+            nodes { number }
+          }
+        }
+      }`, { owner, repo, cursor, first: PAGE_SIZE });
+        const page = response.repository?.issues;
+        if (!page)
+            break;
+        if (pages === 0)
+            totalCount = page.totalCount;
+        for (const node of page.nodes)
+            numbers.add(node.number);
+        if (!page.pageInfo.hasNextPage)
+            break;
+        cursor = page.pageInfo.endCursor;
+        pages += 1;
+    }
+    return { totalCount, numbers };
+}
+/**
+ * Fetch all `type=ISSUE` item numbers on the project board via paginated GraphQL.
+ *
+ * The query tries `user(login)` first, then falls back to `organization(login)`
+ * to handle both account types. PRs and DraftIssues are skipped — only true
+ * `Issue`-typed content with a `number` field is collected.
+ */
+async function fetchBoardIssueNumbers(client, projectOwner, projectNumber) {
+    const numbers = new Set();
+    let totalCount = 0;
+    let cursor = null;
+    let pages = 0;
+    // The project items query is identical across user/org owner — only the
+    // root selector changes. Build a closure that runs the same shape and
+    // tries both owner types on the first page.
+    const runQuery = async (cur) => {
+        for (const ownerType of ["user", "organization"]) {
+            try {
+                const res = await client.projectQuery(`query($owner: String!, $number: Int!, $cursor: String, $first: Int!) {
+            ${ownerType}(login: $owner) {
+              projectV2(number: $number) {
+                items(first: $first, after: $cursor) {
+                  totalCount
+                  pageInfo { hasNextPage endCursor }
+                  nodes {
+                    type
+                    content {
+                      __typename
+                      ... on Issue { number }
+                    }
+                  }
+                }
+              }
+            }
+          }`, { owner: projectOwner, number: projectNumber, cursor: cur, first: PAGE_SIZE });
+                const proj = res[ownerType]?.projectV2;
+                if (proj)
+                    return proj;
+            }
+            catch {
+                // Try next owner type
+            }
+        }
+        return null;
+    };
+    while (pages < MAX_PAGES) {
+        const proj = await runQuery(cursor);
+        if (!proj || !proj.items)
+            break;
+        if (pages === 0)
+            totalCount = proj.items.totalCount;
+        for (const node of proj.items.nodes) {
+            // Only count Issue-typed content. Type field is "ISSUE" but we double-check
+            // via __typename because draft-issue items can have type=DRAFT_ISSUE and
+            // should never count as repo-issue overlap.
+            if (node.type === "ISSUE" &&
+                node.content?.__typename === "Issue" &&
+                typeof node.content.number === "number") {
+                numbers.add(node.content.number);
+            }
+        }
+        if (!proj.items.pageInfo.hasNextPage)
+            break;
+        cursor = proj.items.pageInfo.endCursor;
+        pages += 1;
+    }
+    return { totalCount, numbers };
+}
+/**
+ * Detect repo issues that are absent from the project board.
+ *
+ * Returns the orphan summary when at least one orphan exists, or `null`
+ * when the board contains every OPEN repo issue.
+ *
+ * Returns `null` (not an empty result) so the `health_check` caller can
+ * omit the field entirely on a clean board — keeping the response tight
+ * for the common no-orphans case.
+ */
+export async function detectOrphanRepoIssues(client, owner, repo, projectOwner, projectNumber) {
+    const [repoSide, boardSide] = await Promise.all([
+        fetchRepoOpenIssueNumbers(client, owner, repo),
+        fetchBoardIssueNumbers(client, projectOwner, projectNumber),
+    ]);
+    // Orphans = OPEN issues in the repo whose number is NOT in the board set.
+    // We compare against the actual numbers walked rather than just totalCount,
+    // because a board may contain issues from OTHER repos (multi-repo project)
+    // — those would inflate `boardItems` but contribute zero to the overlap.
+    const orphanNumbers = [];
+    for (const n of repoSide.numbers) {
+        if (!boardSide.numbers.has(n))
+            orphanNumbers.push(n);
+    }
+    orphanNumbers.sort((a, b) => a - b);
+    if (orphanNumbers.length === 0)
+        return null;
+    return {
+        count: orphanNumbers.length,
+        repoOpen: repoSide.totalCount,
+        boardItems: boardSide.totalCount,
+        sample: orphanNumbers.slice(0, ORPHAN_SAMPLE_LIMIT),
+        note: ORPHAN_REPO_ISSUES_NOTE,
+    };
+}
+//# sourceMappingURL=health.js.map

package/package.json

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