ralph-hero-mcp-server 2.4.30 → 2.4.32

package/dist/lib/transition-comments.js

@@ -0,0 +1,113 @@
+/**
+ * Transition comment format specification, builder, and parsers.
+ *
+ * Defines the canonical machine-parseable transition comment format
+ * (`<!-- ralph-transition: {...} -->`) and provides parsers for both
+ * the HTML comment format and #19's handoff_ticket markdown audit
+ * comment format.
+ *
+ * Pure utility module — no API dependencies.
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Regex pattern for HTML transition comments: <!-- ralph-transition: {...} --> */
+export const TRANSITION_COMMENT_PATTERN = /<!-- ralph-transition: (\{.*?\}) -->/g;
+/** Regex pattern for #19 handoff_ticket audit comments */
+export const AUDIT_COMMENT_PATTERN = /\*\*State transition\*\*: (.+?) → (.+?) \(intent: .+?\)\n\*\*Command\*\*: ralph_(\w+)/g;
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+/**
+ * Build a machine-parseable HTML comment encoding a transition record.
+ * The HTML comment is invisible in rendered GitHub markdown.
+ * JSON is compact (no pretty-printing) for single-line format.
+ */
+export function buildTransitionComment(record) {
+    const json = JSON.stringify({
+        from: record.from,
+        to: record.to,
+        command: record.command,
+        at: record.at,
+    });
+    return `<!-- ralph-transition: ${json} -->`;
+}
+// ---------------------------------------------------------------------------
+// Parsers
+// ---------------------------------------------------------------------------
+/**
+ * Parse transition records from HTML comment format.
+ * Scans text for all `<!-- ralph-transition: {...} -->` patterns.
+ * Gracefully handles malformed JSON (skips unparseable entries).
+ */
+export function parseTransitionComments(text) {
+    const records = [];
+    const regex = new RegExp(TRANSITION_COMMENT_PATTERN.source, "g");
+    let match;
+    while ((match = regex.exec(text)) !== null) {
+        try {
+            const parsed = JSON.parse(match[1]);
+            if (parsed.from && parsed.to && parsed.command && parsed.at) {
+                records.push({
+                    from: parsed.from,
+                    to: parsed.to,
+                    command: parsed.command,
+                    at: parsed.at,
+                });
+            }
+        }
+        catch {
+            // Skip malformed JSON entries
+        }
+    }
+    return records;
+}
+/**
+ * Parse transition records from #19's handoff_ticket markdown audit format.
+ * Pattern: `**State transition**: X → Y (intent: Z)\n**Command**: ralph_cmd`
+ * Uses `commentCreatedAt` as the `at` timestamp since audit comments don't
+ * embed their own timestamp.
+ */
+export function parseAuditComments(text, commentCreatedAt) {
+    const records = [];
+    const regex = new RegExp(AUDIT_COMMENT_PATTERN.source, "g");
+    let match;
+    while ((match = regex.exec(text)) !== null) {
+        records.push({
+            from: match[1],
+            to: match[2],
+            command: `ralph_${match[3]}`,
+            at: commentCreatedAt,
+        });
+    }
+    return records;
+}
+/**
+ * Parse transition records from a comment body, trying both formats.
+ * Prefers HTML comment format; falls back to audit format.
+ * Deduplicates records that appear in both formats (by from+to+command).
+ *
+ * This is the primary entry point for future analytics tools.
+ */
+export function parseAllTransitions(commentBody, commentCreatedAt) {
+    const htmlRecords = parseTransitionComments(commentBody);
+    const auditRecords = parseAuditComments(commentBody, commentCreatedAt);
+    if (htmlRecords.length === 0) {
+        return auditRecords;
+    }
+    if (auditRecords.length === 0) {
+        return htmlRecords;
+    }
+    // Both present — deduplicate by from+to+command
+    const seen = new Set(htmlRecords.map((r) => `${r.from}|${r.to}|${r.command}`));
+    const unique = [...htmlRecords];
+    for (const r of auditRecords) {
+        const key = `${r.from}|${r.to}|${r.command}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            unique.push(r);
+        }
+    }
+    return unique;
+}
+//# sourceMappingURL=transition-comments.js.map

package/dist/tools/project-tools.js

@@ -231,6 +231,197 @@ export function registerProjectTools(server, client, fieldCache) {
         }
     });
     // -------------------------------------------------------------------------
+    // ralph_hero__list_projects
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__list_projects", "List all GitHub Projects V2 for an owner (user or organization). Returns project summaries with item/field/view counts. Supports open/closed filtering.", {
+        owner: z
+            .string()
+            .optional()
+            .describe("GitHub owner (user or org). Defaults to RALPH_GH_PROJECT_OWNER or RALPH_GH_OWNER env var"),
+        state: z
+            .enum(["open", "closed", "all"])
+            .optional()
+            .default("open")
+            .describe('Filter by project state: "open" (default), "closed", or "all"'),
+        limit: z
+            .number()
+            .optional()
+            .default(50)
+            .describe("Maximum number of projects to return (default: 50, max: 100)"),
+    }, async (args) => {
+        try {
+            const owner = args.owner || resolveProjectOwner(client.config);
+            if (!owner) {
+                return toolError("owner is required (set RALPH_GH_PROJECT_OWNER or RALPH_GH_OWNER env var or pass explicitly)");
+            }
+            const maxItems = Math.min(args.limit ?? 50, 100);
+            const LIST_PROJECTS_QUERY = `
+          query($owner: String!, $cursor: String, $first: Int!) {
+            OWNER_TYPE(login: $owner) {
+              projectsV2(first: $first, after: $cursor, orderBy: {field: TITLE, direction: ASC}) {
+                totalCount
+                pageInfo { hasNextPage endCursor }
+                nodes {
+                  id
+                  number
+                  title
+                  shortDescription
+                  public
+                  closed
+                  url
+                  items { totalCount }
+                  fields { totalCount }
+                  views { totalCount }
+                }
+              }
+            }
+          }
+        `;
+            let allProjects = [];
+            let totalCount;
+            for (const ownerType of ["user", "organization"]) {
+                try {
+                    const result = await paginateConnection((q, vars) => client.projectQuery(q, vars), LIST_PROJECTS_QUERY.replace("OWNER_TYPE", ownerType), { owner }, `${ownerType}.projectsV2`, { maxItems });
+                    allProjects = result.nodes;
+                    totalCount = result.totalCount;
+                    break;
+                }
+                catch {
+                    // Try next owner type
+                }
+            }
+            // Client-side state filtering
+            const filtered = args.state === "all"
+                ? allProjects
+                : args.state === "closed"
+                    ? allProjects.filter((p) => p.closed)
+                    : allProjects.filter((p) => !p.closed);
+            const projects = filtered.map((p) => ({
+                id: p.id,
+                number: p.number,
+                title: p.title,
+                shortDescription: p.shortDescription,
+                public: p.public,
+                closed: p.closed,
+                url: p.url,
+                itemCount: p.items?.totalCount ?? 0,
+                fieldCount: p.fields?.totalCount ?? 0,
+                viewCount: p.views?.totalCount ?? 0,
+            }));
+            return toolSuccess({
+                owner,
+                state: args.state,
+                projects,
+                totalCount: totalCount ?? projects.length,
+                returnedCount: projects.length,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to list projects: ${message}`);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // ralph_hero__copy_project
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__copy_project", "Copy (duplicate) a GitHub Project V2, preserving views, custom fields, workflows, and insights. Does NOT copy items, collaborators, team links, or repository links.", {
+        sourceProjectNumber: z
+            .number()
+            .describe("Project number of the source project to copy"),
+        sourceOwner: z
+            .string()
+            .optional()
+            .describe("Owner of the source project. Defaults to RALPH_GH_PROJECT_OWNER or RALPH_GH_OWNER env var"),
+        title: z.string().describe("Title for the new project"),
+        targetOwner: z
+            .string()
+            .optional()
+            .describe("Owner for the new project. Defaults to sourceOwner. Supports cross-owner copy (e.g., personal to org)"),
+        includeDraftIssues: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Include draft issues from the source project in the copy (default: false)"),
+    }, async (args) => {
+        try {
+            const sourceOwner = args.sourceOwner || resolveProjectOwner(client.config);
+            if (!sourceOwner) {
+                return toolError("sourceOwner is required (set RALPH_GH_PROJECT_OWNER or RALPH_GH_OWNER env var or pass explicitly)");
+            }
+            // Step 1: Resolve source project node ID via fetchProject
+            const sourceProject = await fetchProject(client, sourceOwner, args.sourceProjectNumber);
+            if (!sourceProject) {
+                return toolError(`Source project #${args.sourceProjectNumber} not found for owner "${sourceOwner}"`);
+            }
+            // Step 2: Resolve target owner node ID (try user first, then org)
+            const targetOwnerLogin = args.targetOwner || sourceOwner;
+            let targetOwnerId;
+            try {
+                const userResult = await client.query(`query($login: String!) {
+              user(login: $login) { id }
+            }`, { login: targetOwnerLogin }, { cache: true });
+                targetOwnerId = userResult.user?.id;
+            }
+            catch {
+                // Not a user, try org below
+            }
+            if (!targetOwnerId) {
+                try {
+                    const orgResult = await client.query(`query($login: String!) {
+                organization(login: $login) { id }
+              }`, { login: targetOwnerLogin }, { cache: true });
+                    targetOwnerId = orgResult.organization?.id;
+                }
+                catch {
+                    // Not an org either
+                }
+            }
+            if (!targetOwnerId) {
+                return toolError(`Target owner "${targetOwnerLogin}" not found as user or organization`);
+            }
+            // Step 3: Execute copyProjectV2 mutation
+            const copyResult = await client.projectMutate(`mutation($projectId: ID!, $ownerId: ID!, $title: String!, $includeDraftIssues: Boolean!) {
+            copyProjectV2(input: {
+              projectId: $projectId
+              ownerId: $ownerId
+              title: $title
+              includeDraftIssues: $includeDraftIssues
+            }) {
+              projectV2 {
+                id
+                number
+                url
+                title
+              }
+            }
+          }`, {
+                projectId: sourceProject.id,
+                ownerId: targetOwnerId,
+                title: args.title,
+                includeDraftIssues: args.includeDraftIssues ?? false,
+            });
+            const newProject = copyResult.copyProjectV2.projectV2;
+            return toolSuccess({
+                project: {
+                    id: newProject.id,
+                    number: newProject.number,
+                    url: newProject.url,
+                    title: newProject.title,
+                },
+                copiedFrom: {
+                    number: args.sourceProjectNumber,
+                    owner: sourceOwner,
+                    title: sourceProject.title,
+                },
+                note: "Copied views, custom fields, workflows, and insights. Items, collaborators, team links, and repository links were NOT copied.",
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to copy project: ${message}`);
+        }
+    });
+    // -------------------------------------------------------------------------
     // ralph_hero__list_project_items
     // -------------------------------------------------------------------------
     server.tool("ralph_hero__list_project_items", "List items in a GitHub Project V2, optionally filtered by Workflow State, Estimate, or Priority", {

package/package.json

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