@hivehub/rulebook 4.4.1 → 5.1.1

package/dist/mcp/rulebook-server.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { existsSync, readFileSync, statSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'fs';
 import { basename, dirname, join, resolve } from 'path';
 import { z } from 'zod';
 import { ConfigManager } from '../core/config-manager.js';
@@ -17,7 +17,13 @@ function withTimeout(promise, ms = MCP_TOOL_TIMEOUT_MS, label = 'tool') {
         const timer = setTimeout(() => {
             reject(new Error(`[rulebook-mcp] ${label} timed out after ${ms}ms`));
         }, ms);
-        promise.then((val) => { clearTimeout(timer); resolve(val); }, (err) => { clearTimeout(timer); reject(err); });
+        promise.then((val) => {
+            clearTimeout(timer);
+            resolve(val);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
     });
 }
 // Find .rulebook file/directory by walking up directories
@@ -66,6 +72,58 @@ function loadConfig() {
     const archiveDir = resolve(projectRoot, mcp.archiveDir || '.rulebook/archive');
     return { projectRoot, tasksDir, archiveDir };
 }
+// --- PID file guard: prevent multiple MCP server instances for the same project ---
+const PID_FILE_NAME = 'mcp-server.pid';
+/**
+ * Check if a PID file exists and if the recorded process is still alive.
+ * If alive, exit this instance. If stale (process died), take over.
+ */
+export function acquirePidLock(projectRoot) {
+    const pidDir = join(projectRoot, '.rulebook');
+    const pidPath = join(pidDir, PID_FILE_NAME);
+    if (existsSync(pidPath)) {
+        try {
+            const raw = readFileSync(pidPath, 'utf8').trim();
+            const existingPid = parseInt(raw, 10);
+            if (!isNaN(existingPid)) {
+                // Check if process is still alive (signal 0 = existence check)
+                try {
+                    process.kill(existingPid, 0);
+                    // Process is alive — another server is running
+                    console.error(`[rulebook-mcp] Another instance is already running (PID ${existingPid}). Exiting.`);
+                    process.exit(0);
+                }
+                catch {
+                    // Process is dead — stale PID file, take over
+                    console.error(`[rulebook-mcp] Stale PID file found (PID ${existingPid} no longer exists). Taking over.`);
+                }
+            }
+        }
+        catch {
+            // Corrupt PID file — overwrite
+        }
+    }
+    // Write our PID
+    if (!existsSync(pidDir)) {
+        mkdirSync(pidDir, { recursive: true });
+    }
+    writeFileSync(pidPath, String(process.pid), 'utf8');
+    return pidPath;
+}
+export function releasePidLock(pidPath) {
+    try {
+        if (existsSync(pidPath)) {
+            const raw = readFileSync(pidPath, 'utf8').trim();
+            // Only remove if it's OUR PID (another instance may have taken over)
+            if (parseInt(raw, 10) === process.pid) {
+                unlinkSync(pidPath);
+            }
+        }
+    }
+    catch {
+        // Best-effort cleanup
+    }
+}
 export async function startRulebookMcpServer() {
     // --- Workspace vs Single-Project Mode ---
     let isWorkspaceMode = process.argv.includes('--workspace');
@@ -123,6 +181,8 @@ export async function startRulebookMcpServer() {
         skillsManager = new SkillsManager(getDefaultTemplatesPath(), projectRoot);
         configManager = new ConfigManager(projectRoot);
     }
+    // --- PID file lock: prevent multiple instances for the same project ---
+    const pidFilePath = acquirePidLock(projectRoot);
     // --- Manager Resolution Helpers (workspace-aware) ---
     async function getTaskMgr(projectId) {
         if (!projectId || !workspaceManager)
@@ -152,7 +212,7 @@ export async function startRulebookMcpServer() {
     }
     const server = new McpServer({
         name: 'rulebook-task-management',
-        version: '4.4.1',
+        version: '5.1.1',
     });
     // --- Wrap all tool handlers with timeout guard ---
     // Intercept registerTool to automatically add timeout protection to every handler.
@@ -166,7 +226,9 @@ export async function startRulebookMcpServer() {
                 const msg = error instanceof Error ? error.message : String(error);
                 console.error(`[rulebook-mcp] ${name} error: ${msg}`);
                 return {
-                    content: [{ type: 'text', text: JSON.stringify({ success: false, error: msg }) }],
+                    content: [
+                        { type: 'text', text: JSON.stringify({ success: false, error: msg }) },
+                    ],
                 };
             }
         };
@@ -701,16 +763,19 @@ export async function startRulebookMcpServer() {
                 console.error(`[rulebook-mcp] Memory DB: ${memoryDbPath}`);
                 memoryManager = createMemoryManager(projectRoot, rulebookConfig.memory);
                 autoCaptureEnabled = rulebookConfig.memory.autoCapture !== false;
-                // Boot Background Indexer — deferred to avoid blocking server startup
-                bgIndexer = new BackgroundIndexer(memoryManager, projectRoot, { enabled: true });
-                setTimeout(() => {
-                    try {
-                        bgIndexer?.start();
-                    }
-                    catch (e) {
-                        console.error('[rulebook-mcp] BackgroundIndexer start failed:', e);
-                    }
-                }, 5000);
+                // Boot Background Indexer only if memory is enabled (opt-in to save resources)
+                const indexerEnabled = rulebookConfig.memory?.enabled === true;
+                if (indexerEnabled) {
+                    bgIndexer = new BackgroundIndexer(memoryManager, projectRoot, { enabled: true });
+                    setTimeout(() => {
+                        try {
+                            bgIndexer?.start();
+                        }
+                        catch (e) {
+                            console.error('[rulebook-mcp] BackgroundIndexer start failed:', e);
+                        }
+                    }, 5000);
+                }
                 global.__indexerStatus = () => bgIndexer?.getStatus();
             }
             catch (e) {
@@ -718,31 +783,67 @@ export async function startRulebookMcpServer() {
             }
         }
     }
-    // Graceful shutdown for both modes
-    process.on('SIGINT', async () => {
-        console.error('[rulebook-mcp] Shutting down...');
-        if (workspaceManager) {
-            await workspaceManager.shutdownAll();
+    // --- Graceful shutdown for both modes ---
+    // Handles SIGINT (Ctrl+C), SIGTERM (parent exit), SIGHUP (terminal close),
+    // and stdin close (parent process died without signaling).
+    let isShuttingDown = false;
+    async function gracefulShutdown(reason) {
+        if (isShuttingDown)
+            return; // Prevent double-shutdown races
+        isShuttingDown = true;
+        console.error(`[rulebook-mcp] Shutting down (${reason})...`);
+        try {
+            if (bgIndexer)
+                bgIndexer.stop();
+            if (workspaceManager) {
+                await workspaceManager.shutdownAll();
+            }
+            if (memoryManager)
+                await memoryManager.close();
+            releasePidLock(pidFilePath);
+        }
+        catch (e) {
+            console.error('[rulebook-mcp] Error during shutdown:', e);
         }
-        if (bgIndexer)
-            bgIndexer.stop();
-        if (memoryManager)
-            await memoryManager.close();
         process.exit(0);
-    });
+    }
+    process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+    process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+    process.on('SIGHUP', () => gracefulShutdown('SIGHUP'));
+    // Detect parent process exit: when the MCP client (e.g. Claude Code) dies,
+    // stdin closes. Without this, the server becomes an orphan that leaks memory.
+    process.stdin.on('end', () => gracefulShutdown('stdin closed'));
+    process.stdin.on('close', () => gracefulShutdown('stdin closed'));
+    // Safety net: if stdin becomes unreadable but doesn't emit 'end'/'close'
+    // (can happen on Windows), poll stdin.readable every 30s.
+    const STDIN_POLL_INTERVAL_MS = 30_000;
+    const stdinPollTimer = setInterval(() => {
+        if (process.stdin.destroyed || !process.stdin.readable) {
+            clearInterval(stdinPollTimer);
+            gracefulShutdown('stdin unreadable');
+        }
+    }, STDIN_POLL_INTERVAL_MS);
+    stdinPollTimer.unref(); // Don't keep the process alive just for this timer
     /**
      * Auto-capture: save tool interactions to memory in the background.
      * Fire-and-forget — never blocks or fails the original tool call.
      * Has its own 2s timeout to prevent hanging the event loop.
+     *
+     * The dynamic import is cached after the first call to avoid repeated
+     * module loading overhead on every tool invocation.
      */
     const AUTO_CAPTURE_TIMEOUT_MS = 2000;
+    let _captureFromToolCall = null;
     async function autoCapture(toolName, args, resultText) {
         if (!memoryManager || !autoCaptureEnabled)
             return;
         try {
             await withTimeout((async () => {
-                const { captureFromToolCall } = await import('../memory/memory-hooks.js');
-                const captured = captureFromToolCall(toolName, args, resultText);
+                if (!_captureFromToolCall) {
+                    const mod = await import('../memory/memory-hooks.js');
+                    _captureFromToolCall = mod.captureFromToolCall;
+                }
+                const captured = _captureFromToolCall(toolName, args, resultText);
                 if (!captured)
                     return;
                 await memoryManager.saveMemory({
@@ -1046,12 +1147,9 @@ export async function startRulebookMcpServer() {
                         ],
                     };
                 }
-                // Ensure lock is released on exit, even on crashes
-                const cleanupLock = async () => {
-                    await ralphManager.releaseLock();
-                };
-                process.on('SIGTERM', cleanupLock);
-                process.on('SIGINT', cleanupLock);
+                // Lock cleanup is handled by the top-level SIGINT handler (line ~858)
+                // which shuts down all managers. Adding per-call SIGINT/SIGTERM listeners
+                // causes accumulation and race conditions with the server shutdown handler.
                 try {
                     // Validate tool is available before starting
                     const toolCmdNames = {
@@ -1312,8 +1410,6 @@ export async function startRulebookMcpServer() {
                 finally {
                     // Always release lock, even on error
                     await ralphManager.releaseLock();
-                    process.removeListener('SIGTERM', cleanupLock);
-                    process.removeListener('SIGINT', cleanupLock);
                 }
             }
             catch (error) {
@@ -1724,7 +1820,10 @@ export async function startRulebookMcpServer() {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
                     },
                 ],
             };
@@ -1735,7 +1834,10 @@ export async function startRulebookMcpServer() {
         title: 'List Decision Records',
         description: 'List all architectural decision records',
         inputSchema: {
-            status: z.string().optional().describe('Filter by status (proposed, accepted, rejected, superseded, deprecated)'),
+            status: z
+                .string()
+                .optional()
+                .describe('Filter by status (proposed, accepted, rejected, superseded, deprecated)'),
             projectId: projectIdSchema,
         },
     }, async (args) => {
@@ -1760,7 +1862,10 @@ export async function startRulebookMcpServer() {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
                     },
                 ],
             };
@@ -1796,7 +1901,11 @@ export async function startRulebookMcpServer() {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({ success: true, decision: result.decision, content: result.content }),
+                        text: JSON.stringify({
+                            success: true,
+                            decision: result.decision,
+                            content: result.content,
+                        }),
                     },
                 ],
             };
@@ -1806,7 +1915,10 @@ export async function startRulebookMcpServer() {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
                     },
                 ],
             };
@@ -1818,7 +1930,10 @@ export async function startRulebookMcpServer() {
         description: 'Update an existing architectural decision record',
         inputSchema: {
             id: z.number().describe('Decision ID to update'),
-            status: z.string().optional().describe('New status (proposed, accepted, rejected, superseded, deprecated)'),
+            status: z
+                .string()
+                .optional()
+                .describe('New status (proposed, accepted, rejected, superseded, deprecated)'),
             context: z.string().optional().describe('Updated context'),
             decision: z.string().optional().describe('Updated decision text'),
             projectId: projectIdSchema,
@@ -1859,7 +1974,10 @@ export async function startRulebookMcpServer() {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
                     },
                 ],
             };
@@ -1909,7 +2027,10 @@ export async function startRulebookMcpServer() {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
                     },
                 ],
             };
@@ -1946,7 +2067,10 @@ export async function startRulebookMcpServer() {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
                     },
                 ],
             };
@@ -1973,7 +2097,10 @@ export async function startRulebookMcpServer() {
                     content: [
                         {
                             type: 'text',
-                            text: JSON.stringify({ success: false, error: `Knowledge entry "${args.id}" not found` }),
+                            text: JSON.stringify({
+                                success: false,
+                                error: `Knowledge entry "${args.id}" not found`,
+                            }),
                         },
                     ],
                 };
@@ -1992,7 +2119,10 @@ export async function startRulebookMcpServer() {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
                     },
                 ],
             };
@@ -2034,7 +2164,10 @@ export async function startRulebookMcpServer() {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
                     },
                 ],
             };
@@ -2070,7 +2203,10 @@ export async function startRulebookMcpServer() {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
                     },
                 ],
             };
@@ -2082,7 +2218,9 @@ export async function startRulebookMcpServer() {
         description: 'Promote a learning to a knowledge entry or decision record',
         inputSchema: {
             id: z.string().describe('Learning ID to promote'),
-            target: z.enum(['knowledge', 'decision']).describe('Promote to knowledge base or decision record'),
+            target: z
+                .enum(['knowledge', 'decision'])
+                .describe('Promote to knowledge base or decision record'),
             title: z.string().optional().describe('Override title for the promoted entry'),
             projectId: projectIdSchema,
         },
@@ -2118,7 +2256,214 @@ export async function startRulebookMcpServer() {
                 content: [
                     {
                         type: 'text',
-                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+    // ── v5.0 Tools: Session Management, Rules, Blockers ──────────────────
+    // Register tool: rulebook_session_start
+    server.registerTool('rulebook_session_start', {
+        title: 'Start Session',
+        description: 'Load session context: reads PLANS.md and searches relevant memories. Call at the start of every session.',
+        inputSchema: {
+            query: z
+                .string()
+                .optional()
+                .describe('Optional search query to find relevant past memories'),
+            projectId: projectIdSchema,
+        },
+    }, async (args) => {
+        try {
+            const root = args.projectId && workspaceManager
+                ? (await workspaceManager.getWorker(args.projectId)).projectRoot
+                : projectRoot;
+            const { join } = await import('path');
+            const { existsSync } = await import('fs');
+            const { readFile } = await import('fs/promises');
+            const result = { plans: null, memories: [] };
+            // Read PLANS.md
+            const plansPath = join(root, '.rulebook', 'PLANS.md');
+            if (existsSync(plansPath)) {
+                result.plans = await readFile(plansPath, 'utf-8');
+            }
+            // Search relevant memories
+            if (args.query && memoryManager) {
+                const searchResults = await memoryManager.searchMemories({
+                    query: args.query,
+                    mode: 'hybrid',
+                    limit: 5,
+                });
+                result.memories = searchResults;
+            }
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: true, ...result }) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+    // Register tool: rulebook_session_end
+    server.registerTool('rulebook_session_end', {
+        title: 'End Session',
+        description: 'Save session summary to PLANS.md history section. Call at the end of every session.',
+        inputSchema: {
+            summary: z.string().describe('Session summary: what was accomplished, key decisions, next steps'),
+            projectId: projectIdSchema,
+        },
+    }, async (args) => {
+        try {
+            const root = args.projectId && workspaceManager
+                ? (await workspaceManager.getWorker(args.projectId)).projectRoot
+                : projectRoot;
+            const { join } = await import('path');
+            const { existsSync } = await import('fs');
+            const { readFile, writeFile } = await import('fs/promises');
+            const plansPath = join(root, '.rulebook', 'PLANS.md');
+            const date = new Date().toISOString().split('T')[0];
+            const entry = `### ${date}\n${args.summary}\n`;
+            if (existsSync(plansPath)) {
+                let content = await readFile(plansPath, 'utf-8');
+                // Insert after <!-- PLANS:HISTORY:START -->
+                if (content.includes('<!-- PLANS:HISTORY:START -->')) {
+                    content = content.replace('<!-- PLANS:HISTORY:START -->', `<!-- PLANS:HISTORY:START -->\n${entry}`);
+                }
+                else {
+                    content += `\n## Session History\n\n<!-- PLANS:HISTORY:START -->\n${entry}<!-- PLANS:HISTORY:END -->\n`;
+                }
+                await writeFile(plansPath, content, 'utf-8');
+            }
+            else {
+                // Create PLANS.md from scratch
+                const newContent = `# Project Plans & Session Context\n\n<!-- PLANS:CONTEXT:START -->\n_No active context._\n<!-- PLANS:CONTEXT:END -->\n\n<!-- PLANS:TASK:START -->\n_No task in progress._\n<!-- PLANS:TASK:END -->\n\n## Session History\n\n<!-- PLANS:HISTORY:START -->\n${entry}<!-- PLANS:HISTORY:END -->\n`;
+                const { mkdirSync } = await import('fs');
+                const dir = join(root, '.rulebook');
+                if (!existsSync(dir))
+                    mkdirSync(dir, { recursive: true });
+                await writeFile(plansPath, newContent, 'utf-8');
+            }
+            // Also save to memory if available
+            if (memoryManager) {
+                await memoryManager.saveMemory({
+                    type: 'observation',
+                    title: `Session summary ${date}`,
+                    content: args.summary,
+                    tags: ['session', 'summary'],
+                });
+            }
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify({ success: true, message: 'Session summary saved to PLANS.md' }) },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+    // Register tool: rulebook_rules_list
+    server.registerTool('rulebook_rules_list', {
+        title: 'List Rules',
+        description: 'List all canonical rules from .rulebook/rules/ with tier and tool targeting info',
+        inputSchema: {
+            projectId: projectIdSchema,
+        },
+    }, async (args) => {
+        try {
+            const root = args.projectId && workspaceManager
+                ? (await workspaceManager.getWorker(args.projectId)).projectRoot
+                : projectRoot;
+            const { listRules } = await import('../core/rule-engine.js');
+            const rules = await listRules(root);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ success: true, rules, count: rules.length }) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+    // Register tool: rulebook_blockers
+    server.registerTool('rulebook_blockers', {
+        title: 'Show Blockers',
+        description: 'Show task blocker chain with cascade impact analysis',
+        inputSchema: {
+            projectId: projectIdSchema,
+        },
+    }, async (args) => {
+        try {
+            const tm = await getTaskMgr(args.projectId);
+            const tasks = await tm.listTasks();
+            // Build blocker chain from task metadata
+            const blockers = [];
+            for (const task of tasks) {
+                const metadata = await tm.getTaskMetadata(task.id);
+                const blocks = Array.isArray(metadata?.blocks) ? metadata.blocks : [];
+                const blockedBy = Array.isArray(metadata?.blockedBy) ? metadata.blockedBy : [];
+                if (blocks.length > 0 || blockedBy.length > 0) {
+                    blockers.push({
+                        taskId: task.id,
+                        blocks,
+                        blockedBy,
+                        cascadeImpact: metadata?.cascadeImpact || blocks.length,
+                    });
+                }
+            }
+            // Sort by cascade impact (highest first)
+            blockers.sort((a, b) => b.cascadeImpact - a.cascadeImpact);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, blockers, count: blockers.length }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
                     },
                 ],
             };