@hivehub/rulebook 3.3.1 → 3.4.2

package/dist/mcp/rulebook-server.js

@@ -781,11 +781,13 @@ export async function startRulebookMcpServer() {
                 const configData = await configManager.loadConfig();
                 const maxIterations = configData.ralph?.maxIterations || 10;
                 const tool = (configData.ralph?.tool || 'claude');
-                await ralphManager.initialize(maxIterations, tool);
+                // Generate PRD first, then initialize with correct task count
                 const prd = await prdGenerator.generatePRD(basename(config.projectRoot) || 'project');
                 const { writeFile } = await import('../utils/file-system.js');
                 const prdPath = join(config.projectRoot, '.rulebook', 'ralph', 'prd.json');
                 await writeFile(prdPath, JSON.stringify(prd, null, 2));
+                // Initialize after PRD is written so task count is correct
+                await ralphManager.initialize(maxIterations, tool);
                 return {
                     content: [
                         {
@@ -826,182 +828,297 @@ export async function startRulebookMcpServer() {
                 const { RalphManager } = await import('../core/ralph-manager.js');
                 const { RalphParser } = await import('../agents/ralph-parser.js');
                 const { spawn } = await import('child_process');
+                const { execSync } = await import('child_process');
                 const logger = new Logger(config.projectRoot);
                 const ralphManager = new RalphManager(config.projectRoot, logger);
                 const configData = await configManager.loadConfig();
                 const maxIterations = args.maxIterations || configData.ralph?.maxIterations || 10;
                 const tool = (args.tool || configData.ralph?.tool || 'claude');
-                // Resume existing state if available, otherwise initialize fresh
-                const existingState = await ralphManager.getStatus();
-                if (!existingState) {
-                    await ralphManager.initialize(maxIterations, tool);
+                // ── Concurrency guard: prevent multiple simultaneous Ralph runs ──
+                const lockAcquired = await ralphManager.acquireLock(tool);
+                if (!lockAcquired) {
+                    const lockInfo = await ralphManager.getLockInfo();
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    success: false,
+                                    error: `Ralph is already running (PID ${lockInfo?.pid}, started ${lockInfo?.startedAt}, task: ${lockInfo?.currentTask || 'starting'}, iteration: ${lockInfo?.iteration || 0}). Wait for it to finish or check ralph_status. Do NOT start another run.`,
+                                }),
+                            },
+                        ],
+                    };
                 }
-                // Helper: run a shell command and return stdout
-                const runCmd = (cmd, cmdArgs) => new Promise((resolve) => {
-                    let stdout = '';
-                    let stderr = '';
-                    const proc = spawn(cmd, cmdArgs, {
-                        cwd: config.projectRoot,
-                        shell: true,
-                        stdio: ['pipe', 'pipe', 'pipe'],
-                    });
-                    proc.stdout?.on('data', (d) => {
-                        stdout += d.toString();
-                    });
-                    proc.stderr?.on('data', (d) => {
-                        stderr += d.toString();
-                    });
-                    proc.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
-                    proc.on('error', (err) => resolve({ code: 1, stdout, stderr: err.message }));
-                });
-                // Helper: build prompt for AI agent
-                const buildPrompt = (task, prd) => {
-                    const criteria = (task.acceptanceCriteria || [])
-                        .map((c) => `- ${c}`)
-                        .join('\n');
-                    return [
-                        `You are working on project: ${prd?.project || 'unknown'}`,
-                        ``,
-                        `## Current Task: ${task.title}`,
-                        `ID: ${task.id}`,
-                        ``,
-                        `## Description`,
-                        task.description,
-                        ``,
-                        `## Acceptance Criteria`,
-                        criteria,
-                        ``,
-                        task.notes ? `## Notes\n${task.notes}\n` : '',
-                        `## Instructions`,
-                        `1. Implement the changes described above`,
-                        `2. Ensure all acceptance criteria are met`,
-                        `3. Run quality checks: type-check, lint, tests`,
-                        `4. Fix any issues found by quality checks`,
-                        `5. When done, summarize what was changed`,
-                    ]
-                        .filter(Boolean)
-                        .join('\n');
+                // Ensure lock is released on exit, even on crashes
+                const cleanupLock = async () => {
+                    await ralphManager.releaseLock();
                 };
-                // Helper: execute AI agent
-                const executeAgent = (agentTool, prompt) => new Promise((resolve, reject) => {
-                    let output = '';
-                    const toolCmds = {
-                        claude: {
-                            cmd: 'claude',
-                            args: ['-p', '--dangerously-skip-permissions', '--verbose'],
-                            stdinPrompt: true,
-                        },
-                        amp: { cmd: 'amp', args: ['-p', prompt], stdinPrompt: false },
-                        gemini: { cmd: 'gemini', args: ['-p', prompt], stdinPrompt: false },
+                process.on('SIGTERM', cleanupLock);
+                process.on('SIGINT', cleanupLock);
+                try {
+                    // Validate tool is available before starting
+                    const toolCmdNames = {
+                        claude: 'claude',
+                        amp: 'amp',
+                        gemini: 'gemini',
                     };
-                    const cfg = toolCmds[agentTool] || toolCmds.claude;
-                    const proc = spawn(cfg.cmd, cfg.args, {
-                        cwd: config.projectRoot,
-                        shell: true,
-                        stdio: ['pipe', 'pipe', 'pipe'],
-                    });
-                    if (cfg.stdinPrompt && proc.stdin) {
-                        proc.stdin.write(prompt);
-                        proc.stdin.end();
+                    const toolCmd = toolCmdNames[tool] || 'claude';
+                    try {
+                        execSync(`${toolCmd} --version`, { stdio: 'pipe', timeout: 10000 });
+                    }
+                    catch {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        success: false,
+                                        error: `CLI tool "${toolCmd}" not found or not responding. Install it first: https://docs.anthropic.com/claude-code`,
+                                    }),
+                                },
+                            ],
+                        };
+                    }
+                    // Resume existing state if available, otherwise initialize fresh
+                    const existingState = await ralphManager.getStatus();
+                    if (!existingState) {
+                        await ralphManager.initialize(maxIterations, tool);
                     }
-                    proc.stdout?.on('data', (d) => {
-                        output += d.toString();
+                    // Helper: run a shell command and return stdout
+                    const runCmd = (cmd, cmdArgs) => new Promise((resolve) => {
+                        let stdout = '';
+                        let stderr = '';
+                        const proc = spawn(cmd, cmdArgs, {
+                            cwd: config.projectRoot,
+                            shell: true,
+                            stdio: ['pipe', 'pipe', 'pipe'],
+                        });
+                        proc.stdout?.on('data', (d) => {
+                            stdout += d.toString();
+                        });
+                        proc.stderr?.on('data', (d) => {
+                            stderr += d.toString();
+                        });
+                        proc.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
+                        proc.on('error', (err) => resolve({ code: 1, stdout, stderr: err.message }));
                     });
-                    proc.stderr?.on('data', () => { });
-                    proc.on('close', (code) => {
-                        if (code === 0 || output.length > 0)
-                            resolve(output);
-                        else
-                            reject(new Error(`Agent ${agentTool} exited with code ${code}`));
+                    // Helper: build prompt for AI agent
+                    const buildPrompt = (task, projectName) => {
+                        const criteria = (task.acceptanceCriteria || [])
+                            .map((c) => `- ${c}`)
+                            .join('\n');
+                        return [
+                            `You are working on project: ${projectName}`,
+                            ``,
+                            `## Current Task: ${task.title}`,
+                            `ID: ${task.id}`,
+                            ``,
+                            `## Description`,
+                            task.description,
+                            ``,
+                            `## Acceptance Criteria`,
+                            criteria,
+                            ``,
+                            task.notes ? `## Notes\n${task.notes}\n` : '',
+                            `## Instructions`,
+                            `1. Implement the changes described above`,
+                            `2. Ensure all acceptance criteria are met`,
+                            `3. Run quality checks: type-check, lint, tests`,
+                            `4. Fix any issues found by quality checks`,
+                            `5. When done, summarize what was changed`,
+                        ]
+                            .filter(Boolean)
+                            .join('\n');
+                    };
+                    // Helper: execute AI agent with proper error handling
+                    const executeAgent = (agentTool, prompt) => new Promise((resolve, reject) => {
+                        let output = '';
+                        let stderrOutput = '';
+                        const toolCmds = {
+                            claude: {
+                                cmd: 'claude',
+                                args: ['-p', '--dangerously-skip-permissions', '--verbose'],
+                                stdinPrompt: true,
+                            },
+                            amp: { cmd: 'amp', args: ['-p', prompt], stdinPrompt: false },
+                            gemini: { cmd: 'gemini', args: ['-p', prompt], stdinPrompt: false },
+                        };
+                        const cfg = toolCmds[agentTool] || toolCmds.claude;
+                        let settled = false;
+                        const settle = (fn) => {
+                            if (!settled) {
+                                settled = true;
+                                fn();
+                            }
+                        };
+                        const proc = spawn(cfg.cmd, cfg.args, {
+                            cwd: config.projectRoot,
+                            shell: true,
+                            stdio: ['pipe', 'pipe', 'pipe'],
+                        });
+                        if (cfg.stdinPrompt && proc.stdin) {
+                            proc.stdin.write(prompt);
+                            proc.stdin.end();
+                        }
+                        proc.stdout?.on('data', (d) => {
+                            output += d.toString();
+                        });
+                        proc.stderr?.on('data', (d) => {
+                            stderrOutput += d.toString();
+                        });
+                        proc.on('close', (code) => {
+                            settle(() => {
+                                if (code === 0 || output.length > 0) {
+                                    resolve(output);
+                                }
+                                else {
+                                    reject(new Error(`Agent ${agentTool} exited with code ${code}${stderrOutput ? ': ' + stderrOutput.slice(0, 500) : ''}`));
+                                }
+                            });
+                        });
+                        proc.on('error', (err) => {
+                            settle(() => reject(new Error(`Failed to spawn ${agentTool}: ${err.message}`)));
+                        });
+                        const timeout = setTimeout(() => {
+                            proc.kill('SIGTERM');
+                            settle(() => resolve(output || `Agent ${agentTool} timed out after 10 minutes`));
+                        }, 600000);
+                        proc.on('close', () => clearTimeout(timeout));
                     });
-                    proc.on('error', (err) => reject(err));
-                    setTimeout(() => {
-                        proc.kill('SIGTERM');
-                        resolve(output || 'Agent timed out');
-                    }, 600000);
-                });
-                // Sync task count from PRD
-                await ralphManager.refreshTaskCount();
-                const prd = await ralphManager.loadPRD();
-                let iterationCount = 0;
-                while (ralphManager.canContinue() && iterationCount < maxIterations) {
-                    iterationCount++;
-                    const task = await ralphManager.getNextTask();
-                    if (!task)
-                        break;
-                    const startTime = Date.now();
-                    // 1. Execute AI agent
-                    let agentOutput = '';
-                    try {
-                        const prompt = buildPrompt(task, prd);
-                        agentOutput = await executeAgent(tool, prompt);
-                    }
-                    catch (agentErr) {
-                        agentOutput = `Error: ${agentErr.message || agentErr}`;
+                    // Sync task count from PRD
+                    await ralphManager.refreshTaskCount();
+                    // Load PRD for project name (used in prompts)
+                    const prd = await ralphManager.loadPRD();
+                    if (!prd || !prd.userStories || prd.userStories.length === 0) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        success: false,
+                                        error: 'No PRD found or no user stories. Run rulebook_ralph_init first.',
+                                    }),
+                                },
+                            ],
+                        };
                     }
-                    // 2. Run quality gates
-                    const [typeCheck, lint, tests] = await Promise.all([
-                        runCmd('npm', ['run', 'type-check']).then((r) => r.code === 0),
-                        runCmd('npm', ['run', 'lint']).then((r) => r.code === 0),
-                        runCmd('npm', ['test']).then((r) => r.code === 0),
-                    ]);
-                    const qualityChecks = { type_check: typeCheck, lint, tests, coverage_met: tests };
-                    const allPass = typeCheck && lint && tests;
-                    const passCount = Object.values(qualityChecks).filter(Boolean).length;
-                    const status = allPass
-                        ? 'success'
-                        : passCount >= 2
-                            ? 'partial'
-                            : 'failed';
-                    // 3. Git commit if all gates pass
-                    let gitCommit;
-                    if (allPass) {
-                        await runCmd('git', ['add', '-A']);
-                        const commitResult = await runCmd('git', [
-                            'commit',
-                            '-m',
-                            `ralph(${task.id}): ${task.title}\n\nIteration ${iterationCount} - Ralph autonomous loop`,
+                    const projectName = prd.project || 'unknown';
+                    const totalTasks = prd.userStories.filter((s) => !s.passes).length;
+                    let iterationCount = 0;
+                    const iterationResults = [];
+                    // Log to stderr so MCP callers can see progress
+                    const logProgress = (msg) => {
+                        process.stderr.write(`[Ralph] ${msg}\n`);
+                    };
+                    logProgress(`Starting Ralph loop: ${totalTasks} pending tasks, max ${maxIterations} iterations, tool=${tool}`);
+                    while (ralphManager.canContinue() && iterationCount < maxIterations) {
+                        iterationCount++;
+                        const task = await ralphManager.getNextTask();
+                        if (!task)
+                            break;
+                        // Update lock with current progress
+                        await ralphManager.updateLockProgress(iterationCount, `${task.id}: ${task.title}`);
+                        logProgress(`Iteration ${iterationCount}/${maxIterations} — Task: ${task.id} "${task.title}"`);
+                        const startTime = Date.now();
+                        // 1. Execute AI agent
+                        let agentOutput = '';
+                        try {
+                            logProgress(`  Executing ${tool} agent...`);
+                            const prompt = buildPrompt(task, projectName);
+                            agentOutput = await executeAgent(tool, prompt);
+                            logProgress(`  Agent finished (${((Date.now() - startTime) / 1000).toFixed(0)}s)`);
+                        }
+                        catch (agentErr) {
+                            agentOutput = `Error: ${agentErr.message || agentErr}`;
+                            logProgress(`  Agent error: ${agentErr.message || agentErr}`);
+                        }
+                        // 2. Run quality gates
+                        logProgress(`  Running quality gates...`);
+                        const [typeCheck, lint, tests] = await Promise.all([
+                            runCmd('npm', ['run', 'type-check']).then((r) => r.code === 0),
+                            runCmd('npm', ['run', 'lint']).then((r) => r.code === 0),
+                            runCmd('npm', ['test']).then((r) => r.code === 0),
                         ]);
-                        const hashMatch = commitResult.stdout.match(/\[[\w/.-]+ ([a-f0-9]+)\]/);
-                        gitCommit = hashMatch ? hashMatch[1] : undefined;
-                        await ralphManager.markStoryComplete(task.id);
+                        const qualityChecks = { type_check: typeCheck, lint, tests, coverage_met: tests };
+                        const allPass = typeCheck && lint && tests;
+                        const passCount = Object.values(qualityChecks).filter(Boolean).length;
+                        const status = allPass
+                            ? 'success'
+                            : passCount >= 2
+                                ? 'partial'
+                                : 'failed';
+                        logProgress(`  Quality: type-check=${typeCheck ? 'PASS' : 'FAIL'} lint=${lint ? 'PASS' : 'FAIL'} tests=${tests ? 'PASS' : 'FAIL'} → ${status.toUpperCase()}`);
+                        // 3. Git commit if all gates pass
+                        let gitCommit;
+                        if (allPass) {
+                            await runCmd('git', ['add', '-A']);
+                            const commitResult = await runCmd('git', [
+                                'commit',
+                                '-m',
+                                `ralph(${task.id}): ${task.title}\n\nIteration ${iterationCount} - Ralph autonomous loop`,
+                            ]);
+                            const hashMatch = commitResult.stdout.match(/\[[\w/.-]+ ([a-f0-9]+)\]/);
+                            gitCommit = hashMatch ? hashMatch[1] : undefined;
+                            await ralphManager.markStoryComplete(task.id);
+                            logProgress(`  Committed: ${gitCommit || 'no hash'} — Story ${task.id} COMPLETE`);
+                        }
+                        const iterDuration = Date.now() - startTime;
+                        // 4. Parse output for learnings/errors
+                        const parsed = RalphParser.parseAgentOutput(agentOutput, iterationCount, task.id, task.title, tool);
+                        // 5. Record iteration and refresh task count for canContinue()
+                        await ralphManager.recordIteration({
+                            iteration: iterationCount,
+                            timestamp: new Date().toISOString(),
+                            task_id: task.id,
+                            task_title: task.title,
+                            status,
+                            ai_tool: tool,
+                            execution_time_ms: iterDuration,
+                            quality_checks: qualityChecks,
+                            output_summary: parsed.output_summary || `Iteration ${iterationCount}: ${task.title}`,
+                            git_commit: gitCommit,
+                            learnings: parsed.learnings,
+                            errors: parsed.errors,
+                            metadata: {
+                                context_loss_count: parsed.metadata.context_loss_count,
+                                parsed_completion: parsed.metadata.parsed_completion,
+                            },
+                        });
+                        iterationResults.push({
+                            iteration: iterationCount,
+                            taskId: task.id,
+                            taskTitle: task.title,
+                            status,
+                            durationMs: iterDuration,
+                        });
+                        // Refresh task count so canContinue() reflects updated PRD
+                        await ralphManager.refreshTaskCount();
+                        logProgress(`  Iteration ${iterationCount} complete (${(iterDuration / 1000).toFixed(0)}s)\n`);
                     }
-                    // 4. Parse output for learnings/errors
-                    const parsed = RalphParser.parseAgentOutput(agentOutput, iterationCount, task.id, task.title, tool);
-                    // 5. Record iteration
-                    await ralphManager.recordIteration({
-                        iteration: iterationCount,
-                        timestamp: new Date().toISOString(),
-                        task_id: task.id,
-                        task_title: task.title,
-                        status,
-                        ai_tool: tool,
-                        execution_time_ms: Date.now() - startTime,
-                        quality_checks: qualityChecks,
-                        output_summary: parsed.output_summary || `Iteration ${iterationCount}: ${task.title}`,
-                        git_commit: gitCommit,
-                        learnings: parsed.learnings,
-                        errors: parsed.errors,
-                        metadata: {
-                            context_loss_count: parsed.metadata.context_loss_count,
-                            parsed_completion: parsed.metadata.parsed_completion,
-                        },
-                    });
+                    const stats = await ralphManager.getTaskStats();
+                    logProgress(`Ralph loop finished: ${iterationCount} iterations, ${stats.completed}/${stats.total} tasks completed`);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    success: true,
+                                    iterations: iterationCount,
+                                    completed: stats.completed,
+                                    total: stats.total,
+                                    results: iterationResults,
+                                }),
+                            },
+                        ],
+                    };
+                }
+                finally {
+                    // Always release lock, even on error
+                    await ralphManager.releaseLock();
+                    process.removeListener('SIGTERM', cleanupLock);
+                    process.removeListener('SIGINT', cleanupLock);
                 }
-                const stats = await ralphManager.getTaskStats();
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({
-                                success: true,
-                                iterations: iterationCount,
-                                completed: stats.completed,
-                                total: stats.total,
-                            }),
-                        },
-                    ],
-                };
             }
             catch (error) {
                 return {
@@ -1037,12 +1154,24 @@ export async function startRulebookMcpServer() {
                     };
                 }
                 const stats = await ralphManager.getTaskStats();
+                // Check if Ralph is currently running (lock held by alive process)
+                const running = await ralphManager.isRunning();
+                const lockInfo = running ? await ralphManager.getLockInfo() : null;
                 return {
                     content: [
                         {
                             type: 'text',
                             text: JSON.stringify({
                                 success: true,
+                                running,
+                                ...(running && lockInfo
+                                    ? {
+                                        runningPid: lockInfo.pid,
+                                        runningTask: lockInfo.currentTask || null,
+                                        runningIteration: lockInfo.iteration || 0,
+                                        runningSince: lockInfo.startedAt,
+                                    }
+                                    : {}),
                                 iteration: status.current_iteration,
                                 maxIterations: status.max_iterations,
                                 completedTasks: stats.completed,