ralph-mcp 1.0.0

package/dist/tools/stop.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { removeWorktree } from "../utils/worktree.js";
+import { deleteExecution, findExecutionByBranch, updateExecution, } from "../store/state.js";
+export const stopInputSchema = z.object({
+    branch: z.string().describe("Branch name to stop (e.g., ralph/task1-agent)"),
+    cleanup: z.boolean().default(false).describe("Also remove the worktree"),
+    deleteRecord: z.boolean().default(false).describe("Delete the execution record from database"),
+});
+export async function stop(input) {
+    // Find execution
+    const exec = await findExecutionByBranch(input.branch);
+    if (!exec) {
+        throw new Error(`No execution found for branch: ${input.branch}`);
+    }
+    const previousStatus = exec.status;
+    // Optionally clean up worktree
+    let cleanedUp = false;
+    if (input.cleanup && exec.worktreePath) {
+        try {
+            await removeWorktree(exec.projectRoot, exec.worktreePath);
+            cleanedUp = true;
+        }
+        catch (e) {
+            console.error("Failed to remove worktree:", e);
+        }
+    }
+    // Delete or update
+    let deleted = false;
+    if (input.deleteRecord) {
+        await deleteExecution(exec.id);
+        deleted = true;
+    }
+    else {
+        // Just update status
+        await updateExecution(exec.id, { status: "stopped", updatedAt: new Date() });
+    }
+    const actions = [];
+    if (deleted)
+        actions.push("deleted record");
+    if (cleanedUp)
+        actions.push("removed worktree");
+    if (!deleted)
+        actions.push("stopped");
+    return {
+        success: true,
+        branch: input.branch,
+        previousStatus,
+        cleanedUp,
+        deleted,
+        message: `${input.branch}: ${actions.join(", ")}`,
+    };
+}

package/dist/tools/update.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+export declare const updateInputSchema: z.ZodObject<{
+    branch: z.ZodString;
+    storyId: z.ZodString;
+    passes: z.ZodBoolean;
+    notes: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    branch: string;
+    storyId: string;
+    passes: boolean;
+    notes?: string | undefined;
+}, {
+    branch: string;
+    storyId: string;
+    passes: boolean;
+    notes?: string | undefined;
+}>;
+export type UpdateInput = z.infer<typeof updateInputSchema>;
+export interface UpdateResult {
+    success: boolean;
+    branch: string;
+    storyId: string;
+    passes: boolean;
+    allComplete: boolean;
+    progress: string;
+    addedToMergeQueue: boolean;
+}
+export declare function update(input: UpdateInput): Promise<UpdateResult>;

package/dist/tools/update.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import notifier from "node-notifier";
+import { findExecutionByBranch, findMergeQueueItemByExecutionId, findUserStoryById, insertMergeQueueItem, listMergeQueue, listUserStoriesByExecutionId, updateExecution, updateUserStory, } from "../store/state.js";
+export const updateInputSchema = z.object({
+    branch: z.string().describe("Branch name (e.g., ralph/task1-agent)"),
+    storyId: z.string().describe("Story ID (e.g., US-001)"),
+    passes: z.boolean().describe("Whether the story passes"),
+    notes: z.string().optional().describe("Implementation notes"),
+});
+export async function update(input) {
+    // Find execution by branch
+    const exec = await findExecutionByBranch(input.branch);
+    if (!exec) {
+        throw new Error(`No execution found for branch: ${input.branch}`);
+    }
+    // Find and update the story
+    const storyKey = `${exec.id}:${input.storyId}`;
+    const story = await findUserStoryById(storyKey);
+    if (!story) {
+        throw new Error(`No story found with ID ${input.storyId} for branch ${input.branch}`);
+    }
+    // Update story
+    await updateUserStory(storyKey, {
+        passes: input.passes,
+        notes: input.notes || story.notes,
+    });
+    // Update execution timestamp and status
+    const allStories = await listUserStoriesByExecutionId(exec.id);
+    // Check if this update completes all stories
+    const updatedStories = allStories.map((s) => s.id === storyKey ? { ...s, passes: input.passes } : s);
+    const allComplete = updatedStories.every((s) => s.passes);
+    const completedCount = updatedStories.filter((s) => s.passes).length;
+    // Update execution status
+    const newStatus = allComplete ? "completed" : "running";
+    await updateExecution(exec.id, { status: newStatus, updatedAt: new Date() });
+    // Auto add to merge queue if enabled and all complete
+    let addedToMergeQueue = false;
+    if (allComplete && exec.autoMerge) {
+        // Check if already in queue
+        const existingInQueue = await findMergeQueueItemByExecutionId(exec.id);
+        if (!existingInQueue) {
+            const queue = await listMergeQueue();
+            const maxPosition = queue.length > 0 ? Math.max(...queue.map((q) => q.position)) : 0;
+            const nextPosition = maxPosition + 1;
+            await insertMergeQueueItem({
+                executionId: exec.id,
+                position: nextPosition,
+                status: "pending",
+                createdAt: new Date(),
+            });
+            addedToMergeQueue = true;
+        }
+    }
+    // Send Windows toast notification when all complete (if enabled)
+    if (allComplete && exec.notifyOnComplete) {
+        notifier.notify({
+            title: "Ralph PRD Complete",
+            message: `${exec.branch} - All ${allStories.length} stories done!`,
+            sound: true,
+        });
+    }
+    return {
+        success: true,
+        branch: input.branch,
+        storyId: input.storyId,
+        passes: input.passes,
+        allComplete,
+        progress: `${completedCount}/${allStories.length} US`,
+        addedToMergeQueue,
+    };
+}

package/dist/utils/agent.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Generate agent prompt for PRD execution
+ */
+export declare function generateAgentPrompt(branch: string, description: string, worktreePath: string, stories: Array<{
+    storyId: string;
+    title: string;
+    description: string;
+    acceptanceCriteria: string[];
+    priority: number;
+    passes: boolean;
+}>): string;
+/**
+ * Generate merge agent prompt for conflict resolution
+ */
+export declare function generateMergeAgentPrompt(projectRoot: string, branch: string, description: string, conflictFiles: string[], prdPath?: string): string;
+/**
+ * Start a Claude agent via CLI (for merge conflicts)
+ */
+export declare function startMergeAgent(projectRoot: string, prompt: string): Promise<{
+    success: boolean;
+    output: string;
+}>;

package/dist/utils/agent.js

@@ -0,0 +1,110 @@
+import { exec } from "child_process";
+import { promisify } from "util";
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+const execAsync = promisify(exec);
+/**
+ * Generate agent prompt for PRD execution
+ */
+export function generateAgentPrompt(branch, description, worktreePath, stories) {
+    const pendingStories = stories
+        .filter((s) => !s.passes)
+        .sort((a, b) => a.priority - b.priority);
+    if (pendingStories.length === 0) {
+        return "All user stories are complete. No action needed.";
+    }
+    const storiesText = pendingStories
+        .map((s) => `
+### ${s.storyId}: ${s.title}
+${s.description}
+
+**Acceptance Criteria:**
+${s.acceptanceCriteria.map((ac) => `- ${ac}`).join("\n")}
+`)
+        .join("\n");
+    return `You are an autonomous coding agent working on the "${branch}" branch.
+
+## Working Directory
+${worktreePath}
+
+## PRD: ${description}
+
+## Pending User Stories
+${storiesText}
+
+## Instructions
+
+1. Work on ONE user story at a time, starting with the highest priority
+2. Implement the feature to satisfy all acceptance criteria
+3. Run quality checks: \`pnpm check-types\` and \`pnpm --filter api build\`
+4. Commit changes with message: \`feat: [${pendingStories[0].storyId}] - ${pendingStories[0].title}\`
+5. After completing a story, call \`ralph_update\` to mark it as passed:
+   \`ralph_update({ branch: "${branch}", storyId: "${pendingStories[0].storyId}", passes: true, notes: "..." })\`
+6. Continue to the next story until all are complete
+
+## Quality Requirements
+- ALL commits must pass typecheck and build
+- Keep changes focused and minimal
+- Follow existing code patterns
+
+## Stop Condition
+When all stories are complete, report completion.
+`;
+}
+/**
+ * Generate merge agent prompt for conflict resolution
+ */
+export function generateMergeAgentPrompt(projectRoot, branch, description, conflictFiles, prdPath) {
+    // Read CLAUDE.md for architecture context
+    let architectureContext = "";
+    const claudeMdPath = join(projectRoot, "CLAUDE.md");
+    if (existsSync(claudeMdPath)) {
+        architectureContext = readFileSync(claudeMdPath, "utf-8");
+    }
+    // Read PRD content if available
+    let prdContent = "";
+    if (prdPath && existsSync(prdPath)) {
+        prdContent = readFileSync(prdPath, "utf-8");
+    }
+    return `You are a Git merge expert. Please resolve the following merge conflicts.
+
+## Project Architecture
+${architectureContext || "No CLAUDE.md found. Use your best judgment based on the code."}
+
+## PRD Context
+${prdContent || `Branch: ${branch}\nDescription: ${description}`}
+
+## Conflict Files
+${conflictFiles.map((f) => `- ${f}`).join("\n")}
+
+## Tasks
+
+1. Read each conflict file to understand both sides of the conflict
+2. Analyze the intent of changes from both branches based on the PRD
+3. Resolve conflicts by keeping valuable changes from both sides
+4. Ensure the PRD requirements are satisfied
+5. Run \`git add <file>\` for each resolved file
+6. Run \`git commit -m "resolve: merge conflicts for ${branch}"\`
+
+## Guidelines
+- Prefer keeping both changes when they don't conflict logically
+- If changes conflict logically, prefer the feature branch changes (they implement the PRD)
+- Ensure the code compiles after resolution
+- Run \`pnpm check-types\` to verify
+`;
+}
+/**
+ * Start a Claude agent via CLI (for merge conflicts)
+ */
+export async function startMergeAgent(projectRoot, prompt) {
+    try {
+        const { stdout, stderr } = await execAsync(`echo "${prompt.replace(/"/g, '\\"')}" | claude --dangerously-skip-permissions --print`, { cwd: projectRoot, maxBuffer: 10 * 1024 * 1024 });
+        return { success: true, output: stdout || stderr };
+    }
+    catch (error) {
+        return {
+            success: false,
+            output: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/utils/merge-helpers.d.ts

@@ -0,0 +1,48 @@
+export interface QualityCheckResult {
+    success: boolean;
+    typeCheck: {
+        success: boolean;
+        output: string;
+    };
+    build: {
+        success: boolean;
+        output: string;
+    };
+}
+export interface SyncResult {
+    success: boolean;
+    hasConflicts: boolean;
+    conflictFiles?: string[];
+    message: string;
+}
+/**
+ * Sync main branch to feature branch before merge
+ */
+export declare function syncMainToBranch(worktreePath: string, branch: string): Promise<SyncResult>;
+/**
+ * Run quality checks (type check and build)
+ */
+export declare function runQualityChecks(worktreePath: string): Promise<QualityCheckResult>;
+/**
+ * Generate commit message with US list
+ */
+export declare function generateCommitMessage(branch: string, description: string, completedStories: {
+    id: string;
+    title: string;
+}[]): string;
+/**
+ * Get list of commits on branch since diverging from main
+ */
+export declare function getBranchCommits(projectRoot: string, branch: string): Promise<string[]>;
+/**
+ * Update TODO.md to mark PRD as completed
+ */
+export declare function updateTodoDoc(projectRoot: string, branch: string, description: string): boolean;
+/**
+ * Update PROJECT-STATUS.md with merge info
+ */
+export declare function updateProjectStatus(projectRoot: string, branch: string, description: string, commitHash: string): boolean;
+/**
+ * Handle schema.prisma conflicts specially
+ */
+export declare function handleSchemaConflict(projectRoot: string): Promise<boolean>;

package/dist/utils/merge-helpers.js

@@ -0,0 +1,213 @@
+import { exec } from "child_process";
+import { promisify } from "util";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+const execAsync = promisify(exec);
+/**
+ * Sync main branch to feature branch before merge
+ */
+export async function syncMainToBranch(worktreePath, branch) {
+    try {
+        // Fetch latest main
+        await execAsync("git fetch origin main", { cwd: worktreePath });
+        // Try to merge main into feature branch
+        try {
+            await execAsync("git merge origin/main --no-edit", { cwd: worktreePath });
+            return {
+                success: true,
+                hasConflicts: false,
+                message: "Successfully synced main to feature branch",
+            };
+        }
+        catch (mergeError) {
+            // Check for conflicts
+            const { stdout: status } = await execAsync("git status --porcelain", {
+                cwd: worktreePath,
+            });
+            const conflictFiles = status
+                .split("\n")
+                .filter((line) => line.startsWith("UU ") || line.startsWith("AA "))
+                .map((line) => line.slice(3));
+            if (conflictFiles.length > 0) {
+                return {
+                    success: false,
+                    hasConflicts: true,
+                    conflictFiles,
+                    message: `Conflicts when syncing main: ${conflictFiles.join(", ")}`,
+                };
+            }
+            throw mergeError;
+        }
+    }
+    catch (error) {
+        return {
+            success: false,
+            hasConflicts: false,
+            message: `Failed to sync main: ${error}`,
+        };
+    }
+}
+/**
+ * Run quality checks (type check and build)
+ */
+export async function runQualityChecks(worktreePath) {
+    const result = {
+        success: false,
+        typeCheck: { success: false, output: "" },
+        build: { success: false, output: "" },
+    };
+    // Run type check
+    try {
+        const { stdout, stderr } = await execAsync("pnpm check-types", {
+            cwd: worktreePath,
+            timeout: 120000, // 2 minutes
+        });
+        result.typeCheck = { success: true, output: stdout || stderr };
+    }
+    catch (error) {
+        const execError = error;
+        result.typeCheck = {
+            success: false,
+            output: execError.stdout || execError.stderr || String(error),
+        };
+        return result;
+    }
+    // Run build (only API for now, as it's the critical one)
+    try {
+        const { stdout, stderr } = await execAsync("pnpm --filter api build", {
+            cwd: worktreePath,
+            timeout: 180000, // 3 minutes
+        });
+        result.build = { success: true, output: stdout || stderr };
+    }
+    catch (error) {
+        const execError = error;
+        result.build = {
+            success: false,
+            output: execError.stdout || execError.stderr || String(error),
+        };
+        return result;
+    }
+    result.success = true;
+    return result;
+}
+/**
+ * Generate commit message with US list
+ */
+export function generateCommitMessage(branch, description, completedStories) {
+    const storyList = completedStories
+        .map((s) => `- ${s.id}: ${s.title}`)
+        .join("\n");
+    return `merge: ${branch} - ${description}
+
+Completed User Stories:
+${storyList || "- No stories tracked"}
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>`;
+}
+/**
+ * Get list of commits on branch since diverging from main
+ */
+export async function getBranchCommits(projectRoot, branch) {
+    try {
+        const { stdout } = await execAsync(`git log main..${branch} --oneline --no-merges`, { cwd: projectRoot });
+        return stdout.split("\n").filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Update TODO.md to mark PRD as completed
+ */
+export function updateTodoDoc(projectRoot, branch, description) {
+    const todoPath = join(projectRoot, "docs", "TODO.md");
+    if (!existsSync(todoPath)) {
+        return false;
+    }
+    try {
+        let content = readFileSync(todoPath, "utf-8");
+        // Find and update the PRD entry (mark as completed)
+        // Pattern: - [ ] PRD description -> - [x] PRD description
+        const prdPattern = new RegExp(`- \\[ \\] (.*${description.slice(0, 30)}.*|.*${branch}.*)`);
+        if (prdPattern.test(content)) {
+            content = content.replace(prdPattern, "- [x] $1");
+            writeFileSync(todoPath, content, "utf-8");
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Update PROJECT-STATUS.md with merge info
+ */
+export function updateProjectStatus(projectRoot, branch, description, commitHash) {
+    const statusPath = join(projectRoot, "docs", "PROJECT-STATUS.md");
+    if (!existsSync(statusPath)) {
+        return false;
+    }
+    try {
+        let content = readFileSync(statusPath, "utf-8");
+        // Add to recent merges section or create one
+        const date = new Date().toISOString().split("T")[0];
+        const mergeEntry = `- ${date}: ${branch} - ${description} (${commitHash.slice(0, 7)})`;
+        const recentMergesPattern = /## Recent Merges\n/;
+        if (recentMergesPattern.test(content)) {
+            content = content.replace(recentMergesPattern, `## Recent Merges\n${mergeEntry}\n`);
+        }
+        else {
+            // Add section at the end
+            content += `\n## Recent Merges\n${mergeEntry}\n`;
+        }
+        writeFileSync(statusPath, content, "utf-8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Handle schema.prisma conflicts specially
+ */
+export async function handleSchemaConflict(projectRoot) {
+    const schemaPath = join(projectRoot, "apps", "api", "src", "infra", "prisma", "schema.prisma");
+    if (!existsSync(schemaPath)) {
+        return false;
+    }
+    try {
+        // Read the conflicted file
+        let content = readFileSync(schemaPath, "utf-8");
+        // Check if there are conflict markers
+        if (!content.includes("<<<<<<<") && !content.includes(">>>>>>>")) {
+            return true; // No conflicts
+        }
+        // For schema.prisma, we typically want to keep both changes
+        // Remove conflict markers and keep all content
+        content = content
+            .replace(/<<<<<<< HEAD\n/g, "")
+            .replace(/=======\n/g, "")
+            .replace(/>>>>>>> .+\n/g, "");
+        // Remove duplicate model definitions (keep first occurrence)
+        const modelPattern = /model (\w+) \{[\s\S]*?\n\}/g;
+        const seenModels = new Set();
+        content = content.replace(modelPattern, (match, modelName) => {
+            if (seenModels.has(modelName)) {
+                return ""; // Remove duplicate
+            }
+            seenModels.add(modelName);
+            return match;
+        });
+        // Clean up extra blank lines
+        content = content.replace(/\n{3,}/g, "\n\n");
+        writeFileSync(schemaPath, content, "utf-8");
+        // Stage the resolved file
+        await execAsync(`git add "${schemaPath}"`, { cwd: projectRoot });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/prd-parser.d.ts

@@ -0,0 +1,22 @@
+export interface ParsedUserStory {
+    id: string;
+    title: string;
+    description: string;
+    acceptanceCriteria: string[];
+    priority: number;
+}
+export interface ParsedPrd {
+    title: string;
+    description: string;
+    branchName: string;
+    userStories: ParsedUserStory[];
+}
+/**
+ * Parse a PRD markdown file into structured data.
+ * Supports both markdown format and JSON format.
+ */
+export declare function parsePrdFile(filePath: string): ParsedPrd;
+/**
+ * Generate branch name from PRD title
+ */
+export declare function generateBranchName(title: string): string;