@hivehub/rulebook 4.3.0 → 4.4.1

package/dist/mcp/rulebook-server.js

@@ -9,6 +9,17 @@ import { BackgroundIndexer } from '../core/indexer/background-indexer.js';
 import { SkillsManager, getDefaultTemplatesPath } from '../core/skills-manager.js';
 import { TaskManager } from '../core/task-manager.js';
 import { WorkspaceManager } from '../core/workspace/workspace-manager.js';
+// --- Timeout guard for MCP tool handlers ---
+// Prevents the MCP server from hanging when a tool handler blocks (SQLite, WASM, fs).
+const MCP_TOOL_TIMEOUT_MS = parseInt(process.env.RULEBOOK_MCP_TIMEOUT_MS ?? '10000', 10);
+function withTimeout(promise, ms = MCP_TOOL_TIMEOUT_MS, label = 'tool') {
+    return new Promise((resolve, reject) => {
+        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); });
+    });
+}
 // Find .rulebook file/directory by walking up directories
 export function findRulebookConfig(startDir) {
     let current = resolve(startDir);
@@ -57,18 +68,30 @@ function loadConfig() {
 }
 export async function startRulebookMcpServer() {
     // --- Workspace vs Single-Project Mode ---
-    const isWorkspaceMode = process.argv.includes('--workspace');
+    let isWorkspaceMode = process.argv.includes('--workspace');
     let workspaceManager = null;
     // Default managers (single-project mode OR default workspace project)
     let taskManager;
     let skillsManager;
     let configManager;
     let projectRoot;
+    // Resolve start directory (shared by both modes)
+    const projectRootFlagIndex = process.argv.indexOf('--project-root');
+    const startDir = projectRootFlagIndex !== -1 && process.argv[projectRootFlagIndex + 1]
+        ? process.argv[projectRootFlagIndex + 1]
+        : process.cwd();
+    // Auto-detect workspace mode: if not explicitly set, check if a workspace
+    // config exists (workspace.json, .code-workspace, or monorepo indicators).
+    // This handles the common case where VSCode multi-root workspaces or
+    // monorepos start the MCP server from the workspace root without --workspace.
+    if (!isWorkspaceMode) {
+        const autoDetected = WorkspaceManager.findWorkspaceConfig(startDir);
+        if (autoDetected) {
+            isWorkspaceMode = true;
+            console.error('[rulebook-mcp] Auto-detected workspace configuration, switching to workspace mode.');
+        }
+    }
     if (isWorkspaceMode) {
-        const projectRootFlagIndex = process.argv.indexOf('--project-root');
-        const startDir = projectRootFlagIndex !== -1 && process.argv[projectRootFlagIndex + 1]
-            ? process.argv[projectRootFlagIndex + 1]
-            : process.cwd();
         const wsConfig = WorkspaceManager.findWorkspaceConfig(startDir);
         if (!wsConfig) {
             console.error('[rulebook-mcp] No workspace config found. Run `rulebook workspace init` to create .rulebook/workspace.json.');
@@ -129,7 +152,25 @@ export async function startRulebookMcpServer() {
     }
     const server = new McpServer({
         name: 'rulebook-task-management',
-        version: '4.2.2',
+        version: '4.4.1',
+    });
+    // --- Wrap all tool handlers with timeout guard ---
+    // Intercept registerTool to automatically add timeout protection to every handler.
+    const originalRegisterTool = server.registerTool.bind(server);
+    server.registerTool = ((name, config, handler) => {
+        const wrappedHandler = async (...handlerArgs) => {
+            try {
+                return await withTimeout(handler(...handlerArgs), MCP_TOOL_TIMEOUT_MS, name);
+            }
+            catch (error) {
+                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 }) }],
+                };
+            }
+        };
+        return originalRegisterTool(name, config, wrappedHandler);
     });
     // Zod schema reused across tools for workspace project targeting
     const projectIdSchema = z
@@ -660,9 +701,16 @@ export async function startRulebookMcpServer() {
                 console.error(`[rulebook-mcp] Memory DB: ${memoryDbPath}`);
                 memoryManager = createMemoryManager(projectRoot, rulebookConfig.memory);
                 autoCaptureEnabled = rulebookConfig.memory.autoCapture !== false;
-                // Boot Background Indexer
+                // Boot Background Indexer — deferred to avoid blocking server startup
                 bgIndexer = new BackgroundIndexer(memoryManager, projectRoot, { enabled: true });
-                bgIndexer.start();
+                setTimeout(() => {
+                    try {
+                        bgIndexer?.start();
+                    }
+                    catch (e) {
+                        console.error('[rulebook-mcp] BackgroundIndexer start failed:', e);
+                    }
+                }, 5000);
                 global.__indexerStatus = () => bgIndexer?.getStatus();
             }
             catch (e) {
@@ -685,24 +733,28 @@ export async function startRulebookMcpServer() {
     /**
      * 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.
      */
+    const AUTO_CAPTURE_TIMEOUT_MS = 2000;
     async function autoCapture(toolName, args, resultText) {
         if (!memoryManager || !autoCaptureEnabled)
             return;
         try {
-            const { captureFromToolCall } = await import('../memory/memory-hooks.js');
-            const captured = captureFromToolCall(toolName, args, resultText);
-            if (!captured)
-                return;
-            await memoryManager.saveMemory({
-                type: captured.type,
-                title: captured.title,
-                content: captured.content,
-                tags: captured.tags,
-            });
+            await withTimeout((async () => {
+                const { captureFromToolCall } = await import('../memory/memory-hooks.js');
+                const captured = captureFromToolCall(toolName, args, resultText);
+                if (!captured)
+                    return;
+                await memoryManager.saveMemory({
+                    type: captured.type,
+                    title: captured.title,
+                    content: captured.content,
+                    tags: captured.tags,
+                });
+            })(), AUTO_CAPTURE_TIMEOUT_MS, `autoCapture(${toolName})`);
         }
         catch {
-            // Never fail the original tool call
+            // Never fail the original tool call — timeout or error is silently dropped
         }
     }
     function memoryNotEnabled() {
@@ -1628,6 +1680,450 @@ export async function startRulebookMcpServer() {
             }
         });
     }
+    // ============================================
+    // Context Intelligence Layer Tools (v4.4)
+    // ============================================
+    // Register tool: rulebook_decision_create
+    server.registerTool('rulebook_decision_create', {
+        title: 'Create Decision Record',
+        description: 'Create a new architectural decision record (ADR)',
+        inputSchema: {
+            title: z.string().describe('Decision title'),
+            context: z.string().optional().describe('Context and problem statement'),
+            decision: z.string().optional().describe('The decision made'),
+            alternatives: z.array(z.string()).optional().describe('Alternatives considered'),
+            consequences: z.string().optional().describe('Consequences and tradeoffs'),
+            relatedTasks: z.array(z.string()).optional().describe('Related task IDs'),
+            projectId: projectIdSchema,
+        },
+    }, async (args) => {
+        try {
+            const root = args.projectId && workspaceManager
+                ? (await workspaceManager.getWorker(args.projectId)).projectRoot
+                : projectRoot;
+            const { DecisionManager } = await import('../core/decision-manager.js');
+            const dm = new DecisionManager(root);
+            const decision = await dm.create(args.title, {
+                context: args.context,
+                decision: args.decision,
+                alternatives: args.alternatives,
+                consequences: args.consequences,
+                relatedTasks: args.relatedTasks,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, decision }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                    },
+                ],
+            };
+        }
+    });
+    // Register tool: rulebook_decision_list
+    server.registerTool('rulebook_decision_list', {
+        title: 'List Decision Records',
+        description: 'List all architectural decision records',
+        inputSchema: {
+            status: z.string().optional().describe('Filter by status (proposed, accepted, rejected, superseded, deprecated)'),
+            projectId: projectIdSchema,
+        },
+    }, async (args) => {
+        try {
+            const root = args.projectId && workspaceManager
+                ? (await workspaceManager.getWorker(args.projectId)).projectRoot
+                : projectRoot;
+            const { DecisionManager } = await import('../core/decision-manager.js');
+            const dm = new DecisionManager(root);
+            const decisions = await dm.list(args.status);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, decisions, count: decisions.length }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                    },
+                ],
+            };
+        }
+    });
+    // Register tool: rulebook_decision_show
+    server.registerTool('rulebook_decision_show', {
+        title: 'Show Decision Record',
+        description: 'Show full details of a decision record',
+        inputSchema: {
+            id: z.number().describe('Decision ID'),
+            projectId: projectIdSchema,
+        },
+    }, async (args) => {
+        try {
+            const root = args.projectId && workspaceManager
+                ? (await workspaceManager.getWorker(args.projectId)).projectRoot
+                : projectRoot;
+            const { DecisionManager } = await import('../core/decision-manager.js');
+            const dm = new DecisionManager(root);
+            const result = await dm.show(args.id);
+            if (!result) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ success: false, error: `Decision ${args.id} not found` }),
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, decision: result.decision, content: result.content }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                    },
+                ],
+            };
+        }
+    });
+    // Register tool: rulebook_decision_update
+    server.registerTool('rulebook_decision_update', {
+        title: 'Update Decision Record',
+        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)'),
+            context: z.string().optional().describe('Updated context'),
+            decision: z.string().optional().describe('Updated decision text'),
+            projectId: projectIdSchema,
+        },
+    }, async (args) => {
+        try {
+            const root = args.projectId && workspaceManager
+                ? (await workspaceManager.getWorker(args.projectId)).projectRoot
+                : projectRoot;
+            const { DecisionManager } = await import('../core/decision-manager.js');
+            const dm = new DecisionManager(root);
+            const updated = await dm.update(args.id, {
+                status: args.status,
+                context: args.context,
+                decision: args.decision,
+            });
+            if (!updated) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ success: false, error: `Decision ${args.id} not found` }),
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, decision: updated }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                    },
+                ],
+            };
+        }
+    });
+    // Register tool: rulebook_knowledge_add
+    server.registerTool('rulebook_knowledge_add', {
+        title: 'Add Knowledge Entry',
+        description: 'Add a new pattern or anti-pattern to the project knowledge base',
+        inputSchema: {
+            type: z.string().describe('Knowledge type: "pattern" or "anti-pattern"'),
+            title: z.string().describe('Entry title'),
+            category: z.string().describe('Category (e.g. code, architecture, testing, security)'),
+            description: z.string().describe('Description of the pattern'),
+            example: z.string().optional().describe('Code or usage example'),
+            whenToUse: z.string().optional().describe('When to use this pattern'),
+            whenNotToUse: z.string().optional().describe('When NOT to use this pattern'),
+            tags: z.array(z.string()).optional().describe('Tags for search'),
+            projectId: projectIdSchema,
+        },
+    }, async (args) => {
+        try {
+            const root = args.projectId && workspaceManager
+                ? (await workspaceManager.getWorker(args.projectId)).projectRoot
+                : projectRoot;
+            const { KnowledgeManager } = await import('../core/knowledge-manager.js');
+            const km = new KnowledgeManager(root);
+            const entry = await km.add(args.type, args.title, {
+                category: args.category,
+                description: args.description,
+                example: args.example,
+                whenToUse: args.whenToUse,
+                whenNotToUse: args.whenNotToUse,
+                tags: args.tags,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, entry }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                    },
+                ],
+            };
+        }
+    });
+    // Register tool: rulebook_knowledge_list
+    server.registerTool('rulebook_knowledge_list', {
+        title: 'List Knowledge Entries',
+        description: 'List patterns and anti-patterns in the project knowledge base',
+        inputSchema: {
+            type: z.string().optional().describe('Filter by type: "pattern" or "anti-pattern"'),
+            category: z.string().optional().describe('Filter by category'),
+            projectId: projectIdSchema,
+        },
+    }, async (args) => {
+        try {
+            const root = args.projectId && workspaceManager
+                ? (await workspaceManager.getWorker(args.projectId)).projectRoot
+                : projectRoot;
+            const { KnowledgeManager } = await import('../core/knowledge-manager.js');
+            const km = new KnowledgeManager(root);
+            const entries = await km.list(args.type, args.category);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, entries, count: entries.length }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                    },
+                ],
+            };
+        }
+    });
+    // Register tool: rulebook_knowledge_show
+    server.registerTool('rulebook_knowledge_show', {
+        title: 'Show Knowledge Entry',
+        description: 'Show full details of a knowledge entry',
+        inputSchema: {
+            id: z.string().describe('Knowledge entry ID (slug)'),
+            projectId: projectIdSchema,
+        },
+    }, async (args) => {
+        try {
+            const root = args.projectId && workspaceManager
+                ? (await workspaceManager.getWorker(args.projectId)).projectRoot
+                : projectRoot;
+            const { KnowledgeManager } = await import('../core/knowledge-manager.js');
+            const km = new KnowledgeManager(root);
+            const result = await km.show(args.id);
+            if (!result) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ success: false, error: `Knowledge entry "${args.id}" not found` }),
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, entry: result.entry, content: result.content }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                    },
+                ],
+            };
+        }
+    });
+    // Register tool: rulebook_learn_capture
+    server.registerTool('rulebook_learn_capture', {
+        title: 'Capture Learning',
+        description: 'Capture a learning or insight for future reference',
+        inputSchema: {
+            title: z.string().describe('Brief title for the learning'),
+            content: z.string().describe('Full content of the learning'),
+            tags: z.array(z.string()).optional().describe('Tags for search'),
+            relatedTask: z.string().optional().describe('Related task ID'),
+            projectId: projectIdSchema,
+        },
+    }, async (args) => {
+        try {
+            const root = args.projectId && workspaceManager
+                ? (await workspaceManager.getWorker(args.projectId)).projectRoot
+                : projectRoot;
+            const { LearnManager } = await import('../core/learn-manager.js');
+            const lm = new LearnManager(root);
+            const learning = await lm.capture(args.title, args.content, {
+                tags: args.tags,
+                relatedTask: args.relatedTask,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, learning }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                    },
+                ],
+            };
+        }
+    });
+    // Register tool: rulebook_learn_list
+    server.registerTool('rulebook_learn_list', {
+        title: 'List Learnings',
+        description: 'List captured learnings, newest first',
+        inputSchema: {
+            limit: z.number().optional().describe('Maximum number of learnings to return'),
+            projectId: projectIdSchema,
+        },
+    }, async (args) => {
+        try {
+            const root = args.projectId && workspaceManager
+                ? (await workspaceManager.getWorker(args.projectId)).projectRoot
+                : projectRoot;
+            const { LearnManager } = await import('../core/learn-manager.js');
+            const lm = new LearnManager(root);
+            const learnings = await lm.list(args.limit);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, learnings, count: learnings.length }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                    },
+                ],
+            };
+        }
+    });
+    // Register tool: rulebook_learn_promote
+    server.registerTool('rulebook_learn_promote', {
+        title: 'Promote Learning',
+        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'),
+            title: z.string().optional().describe('Override title for the promoted entry'),
+            projectId: projectIdSchema,
+        },
+    }, async (args) => {
+        try {
+            const root = args.projectId && workspaceManager
+                ? (await workspaceManager.getWorker(args.projectId)).projectRoot
+                : projectRoot;
+            const { LearnManager } = await import('../core/learn-manager.js');
+            const lm = new LearnManager(root);
+            const result = await lm.promote(args.id, args.target, { title: args.title });
+            if (!result) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ success: false, error: `Learning "${args.id}" not found` }),
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, promoted: result }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }),
+                    },
+                ],
+            };
+        }
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }