@vibescope/mcp-server 0.3.0 → 0.3.3

package/src/tools/tools.test.ts

@@ -0,0 +1,222 @@
+/**
+ * Tests for split tool definitions
+ *
+ * Validates that domain-specific tool files:
+ * - Export valid Tool arrays
+ * - Have unique tool names
+ * - Have required inputSchema properties
+ */
+
+import { describe, it, expect } from 'vitest';
+import { sessionTools } from './session.js';
+import { costTools } from './cost.js';
+import { discoveryTools } from './discovery.js';
+import { worktreeTools } from './worktrees.js';
+import { projectTools } from './project.js';
+import { blockerTools } from './blockers.js';
+import { decisionTools } from './decisions.js';
+import { ideaTools } from './ideas.js';
+import { buildToolList, toolCategories } from './index.js';
+
+describe('Split Tool Definitions', () => {
+	describe('sessionTools', () => {
+		it('should export an array of tools', () => {
+			expect(Array.isArray(sessionTools)).toBe(true);
+			expect(sessionTools.length).toBeGreaterThan(0);
+		});
+
+		it('should include expected session tools', () => {
+			const toolNames = sessionTools.map(t => t.name);
+			expect(toolNames).toContain('start_work_session');
+			expect(toolNames).toContain('heartbeat');
+			expect(toolNames).toContain('end_work_session');
+			expect(toolNames).toContain('signal_idle');
+			expect(toolNames).toContain('get_token_usage');
+			expect(toolNames).toContain('report_token_usage');
+		});
+
+		it('should have valid inputSchema for all tools', () => {
+			for (const tool of sessionTools) {
+				expect(tool.inputSchema).toBeDefined();
+				expect(tool.inputSchema.type).toBe('object');
+				expect(tool.inputSchema.properties).toBeDefined();
+			}
+		});
+	});
+
+	describe('costTools', () => {
+		it('should export an array of tools', () => {
+			expect(Array.isArray(costTools)).toBe(true);
+			expect(costTools.length).toBeGreaterThan(0);
+		});
+
+		it('should include expected cost tools', () => {
+			const toolNames = costTools.map(t => t.name);
+			expect(toolNames).toContain('get_cost_summary');
+			expect(toolNames).toContain('add_cost_alert');
+			expect(toolNames).toContain('update_cost_alert');
+			expect(toolNames).toContain('delete_cost_alert');
+		});
+	});
+
+	describe('discoveryTools', () => {
+		it('should export an array of tools', () => {
+			expect(Array.isArray(discoveryTools)).toBe(true);
+			expect(discoveryTools.length).toBeGreaterThan(0);
+		});
+
+		it('should include expected discovery tools', () => {
+			const toolNames = discoveryTools.map(t => t.name);
+			expect(toolNames).toContain('query_knowledge_base');
+			expect(toolNames).toContain('discover_tools');
+			expect(toolNames).toContain('get_tool_info');
+		});
+	});
+
+	describe('worktreeTools', () => {
+		it('should export an array of tools', () => {
+			expect(Array.isArray(worktreeTools)).toBe(true);
+			expect(worktreeTools.length).toBeGreaterThan(0);
+		});
+
+		it('should include expected worktree tools', () => {
+			const toolNames = worktreeTools.map(t => t.name);
+			expect(toolNames).toContain('get_stale_worktrees');
+			expect(toolNames).toContain('clear_worktree_path');
+		});
+	});
+
+	describe('projectTools', () => {
+		it('should export an array of tools', () => {
+			expect(Array.isArray(projectTools)).toBe(true);
+			expect(projectTools.length).toBeGreaterThan(0);
+		});
+
+		it('should include expected project tools', () => {
+			const toolNames = projectTools.map(t => t.name);
+			expect(toolNames).toContain('get_project_context');
+			expect(toolNames).toContain('create_project');
+			expect(toolNames).toContain('update_project');
+			expect(toolNames).toContain('get_project_summary');
+		});
+	});
+
+	describe('blockerTools', () => {
+		it('should export an array of tools', () => {
+			expect(Array.isArray(blockerTools)).toBe(true);
+			expect(blockerTools.length).toBeGreaterThan(0);
+		});
+
+		it('should include expected blocker tools', () => {
+			const toolNames = blockerTools.map(t => t.name);
+			expect(toolNames).toContain('add_blocker');
+			expect(toolNames).toContain('resolve_blocker');
+			expect(toolNames).toContain('get_blockers');
+			expect(toolNames).toContain('delete_blocker');
+		});
+	});
+
+	describe('decisionTools', () => {
+		it('should export an array of tools', () => {
+			expect(Array.isArray(decisionTools)).toBe(true);
+			expect(decisionTools.length).toBeGreaterThan(0);
+		});
+
+		it('should include expected decision tools', () => {
+			const toolNames = decisionTools.map(t => t.name);
+			expect(toolNames).toContain('log_decision');
+			expect(toolNames).toContain('get_decisions');
+			expect(toolNames).toContain('delete_decision');
+		});
+	});
+
+	describe('ideaTools', () => {
+		it('should export an array of tools', () => {
+			expect(Array.isArray(ideaTools)).toBe(true);
+			expect(ideaTools.length).toBeGreaterThan(0);
+		});
+
+		it('should include expected idea tools', () => {
+			const toolNames = ideaTools.map(t => t.name);
+			expect(toolNames).toContain('add_idea');
+			expect(toolNames).toContain('update_idea');
+			expect(toolNames).toContain('get_ideas');
+			expect(toolNames).toContain('convert_idea_to_task');
+		});
+	});
+
+	describe('buildToolList', () => {
+		it('should combine all domain tools', () => {
+			const allTools = buildToolList();
+			expect(Array.isArray(allTools)).toBe(true);
+
+			// Should include tools from all domains
+			const toolNames = allTools.map(t => t.name);
+			expect(toolNames).toContain('start_work_session');
+			expect(toolNames).toContain('get_cost_summary');
+			expect(toolNames).toContain('discover_tools');
+			expect(toolNames).toContain('get_stale_worktrees');
+			expect(toolNames).toContain('get_project_context');
+			expect(toolNames).toContain('add_blocker');
+			expect(toolNames).toContain('log_decision');
+			expect(toolNames).toContain('add_idea');
+		});
+
+		it('should have unique tool names', () => {
+			const allTools = buildToolList();
+			const toolNames = allTools.map(t => t.name);
+			const uniqueNames = new Set(toolNames);
+			expect(uniqueNames.size).toBe(toolNames.length);
+		});
+	});
+
+	describe('toolCategories', () => {
+		it('should have categories for all domains', () => {
+			expect(toolCategories.session).toBeDefined();
+			expect(toolCategories.cost).toBeDefined();
+			expect(toolCategories.discovery).toBeDefined();
+			expect(toolCategories.worktrees).toBeDefined();
+			expect(toolCategories.project).toBeDefined();
+			expect(toolCategories.blockers).toBeDefined();
+			expect(toolCategories.decisions).toBeDefined();
+			expect(toolCategories.ideas).toBeDefined();
+		});
+
+		it('should have correct tool names per category', () => {
+			expect(toolCategories.session).toContain('start_work_session');
+			expect(toolCategories.cost).toContain('get_cost_summary');
+			expect(toolCategories.discovery).toContain('discover_tools');
+			expect(toolCategories.worktrees).toContain('get_stale_worktrees');
+			expect(toolCategories.project).toContain('get_project_context');
+			expect(toolCategories.blockers).toContain('add_blocker');
+			expect(toolCategories.decisions).toContain('log_decision');
+			expect(toolCategories.ideas).toContain('add_idea');
+		});
+	});
+
+	describe('tool structure validation', () => {
+		const allTools = buildToolList();
+
+		it('all tools should have a name', () => {
+			for (const tool of allTools) {
+				expect(tool.name).toBeDefined();
+				expect(typeof tool.name).toBe('string');
+				expect(tool.name.length).toBeGreaterThan(0);
+			}
+		});
+
+		it('all tools should have a description', () => {
+			for (const tool of allTools) {
+				expect(tool.description).toBeDefined();
+				expect(typeof tool.description).toBe('string');
+			}
+		});
+
+		it('all tools should have an inputSchema', () => {
+			for (const tool of allTools) {
+				expect(tool.inputSchema).toBeDefined();
+				expect(tool.inputSchema.type).toBe('object');
+			}
+		});
+	});
+});

package/src/tools/types.ts

@@ -0,0 +1,9 @@
+/**
+ * Tool Definition Types
+ *
+ * Re-export the Tool type from the MCP SDK for use in domain-specific tool files.
+ */
+
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+export type { Tool };

package/src/tools/validation.ts

@@ -0,0 +1,75 @@
+/**
+ * Validation Tool Definitions
+ *
+ * Tools for task validation workflow:
+ * - get_tasks_awaiting_validation
+ * - claim_validation
+ * - validate_task
+ */
+
+import type { Tool } from './types.js';
+
+export const validationTools: Tool[] = [
+	{
+		name: 'get_tasks_awaiting_validation',
+		description: `Get completed tasks not yet validated.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'claim_validation',
+		description: 'Claim a completed task for review. Shows "being reviewed" on dashboard.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID to claim for review',
+				},
+			},
+			required: ['task_id'],
+		},
+	},
+	{
+		name: 'validate_task',
+		description: 'Validate a completed task. Include test results in validation_notes. For github-flow/git-flow projects, a PR must exist and checks must pass before approval.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID to validate',
+				},
+				validation_notes: {
+					type: 'string',
+					description: 'Notes about the validation (what was checked, any issues found)',
+				},
+				approved: {
+					type: 'boolean',
+					description: 'Whether the task passes validation (true = approved, false = needs more work)',
+				},
+				pr_checks_passing: {
+					type: 'boolean',
+					description: 'REQUIRED when approving tasks with PRs. Confirm you verified PR checks are passing via `gh pr view <PR_NUMBER> --json statusCheckRollup`. Set to true only if all required checks pass.',
+				},
+				skip_pr_check: {
+					type: 'boolean',
+					description: 'Skip PR existence check (use only for tasks that legitimately do not need a PR)',
+				},
+				create_fix_task: {
+					type: 'boolean',
+					description: 'When rejecting (approved: false), create a new fix task linked to the original. The fix task will contain the rejection reason and be assigned the same git branch.',
+				},
+			},
+			required: ['task_id', 'approved'],
+		},
+	},
+];

package/src/tools/worktrees.ts

@@ -0,0 +1,66 @@
+/**
+ * Git Worktree Tool Definitions
+ *
+ * Tools for managing git worktrees:
+ * - get_stale_worktrees: Get worktrees that need cleanup
+ * - clear_worktree_path: Clear worktree_path from a task after cleanup
+ */
+
+import type { Tool } from './types.js';
+
+export const worktreeTools: Tool[] = [
+	{
+		name: 'get_stale_worktrees',
+		description: `Get worktrees that need cleanup.
+
+Returns tasks with worktree_path set where:
+- Task is completed or cancelled (worktree should have been cleaned up)
+- Task has been abandoned (no activity for 24+ hours while in_progress)
+
+IMPORTANT: Pass hostname (os.hostname()) to only see worktrees created on THIS machine.
+Worktrees created on other machines cannot be removed locally.
+
+For each stale worktree:
+1. Run: git worktree remove <worktree_path>
+2. Call: clear_worktree_path(task_id)`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: {
+					type: 'string',
+					description: 'Project UUID',
+				},
+				hostname: {
+					type: 'string',
+					description: 'Machine hostname (os.hostname()). Only returns worktrees created on this machine, preventing attempts to clean up worktrees on other machines.',
+				},
+				limit: {
+					type: 'number',
+					description: 'Max worktrees to return (default: 50)',
+				},
+				offset: {
+					type: 'number',
+					description: 'Number of worktrees to skip for pagination (default: 0)',
+				},
+			},
+			required: ['project_id'],
+		},
+	},
+	{
+		name: 'clear_worktree_path',
+		description: `Clear the worktree_path from a task after cleanup.
+
+Call this AFTER removing the worktree with git worktree remove.
+This marks the task as cleaned up so it won't appear in get_stale_worktrees.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'Task UUID',
+				},
+			},
+			required: ['task_id'],
+		},
+	},
+];

package/src/tools.test.ts

@@ -7,7 +7,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { tools } from './tools.js';
+import { tools } from './tools/index.js';
 
 // Valid JSON Schema types
 const VALID_SCHEMA_TYPES = ['string', 'number', 'boolean', 'object', 'array', 'null', 'integer'];

package/src/utils.test.ts

@@ -10,6 +10,11 @@ import {
 	isValidDeploymentStatusTransition,
 	extractProjectNameFromGitUrl,
 	normalizeGitUrl,
+	getErrorMessage,
+	hasErrorProperty,
+	extractApiError,
+	capPagination,
+	PAGINATION_LIMITS,
 } from './utils.js';
 
 // ============================================================================
@@ -783,3 +788,227 @@ describe('normalizeGitUrl', () => {
 		});
 	});
 });
+
+// ============================================================================
+// Error Handling Utilities Tests
+// ============================================================================
+
+describe('getErrorMessage', () => {
+	it('extracts message from Error object', () => {
+		const error = new Error('Something went wrong');
+		expect(getErrorMessage(error)).toBe('Something went wrong');
+	});
+
+	it('extracts message from TypeError', () => {
+		const error = new TypeError('Invalid type');
+		expect(getErrorMessage(error)).toBe('Invalid type');
+	});
+
+	it('returns string errors as-is', () => {
+		expect(getErrorMessage('Direct error string')).toBe('Direct error string');
+	});
+
+	it('converts numbers to string', () => {
+		expect(getErrorMessage(404)).toBe('404');
+	});
+
+	it('converts null to string', () => {
+		expect(getErrorMessage(null)).toBe('null');
+	});
+
+	it('converts undefined to string', () => {
+		expect(getErrorMessage(undefined)).toBe('undefined');
+	});
+
+	it('converts objects to string', () => {
+		expect(getErrorMessage({ foo: 'bar' })).toBe('[object Object]');
+	});
+
+	it('handles empty Error message', () => {
+		const error = new Error('');
+		expect(getErrorMessage(error)).toBe('');
+	});
+});
+
+describe('hasErrorProperty', () => {
+	it('returns true for object with error property', () => {
+		expect(hasErrorProperty({ error: 'some error' })).toBe(true);
+	});
+
+	it('returns true for object with error as object', () => {
+		expect(hasErrorProperty({ error: { message: 'nested' } })).toBe(true);
+	});
+
+	it('returns true for object with null error', () => {
+		expect(hasErrorProperty({ error: null })).toBe(true);
+	});
+
+	it('returns false for null', () => {
+		expect(hasErrorProperty(null)).toBe(false);
+	});
+
+	it('returns false for undefined', () => {
+		expect(hasErrorProperty(undefined)).toBe(false);
+	});
+
+	it('returns false for string', () => {
+		expect(hasErrorProperty('error')).toBe(false);
+	});
+
+	it('returns false for object without error property', () => {
+		expect(hasErrorProperty({ success: true })).toBe(false);
+	});
+
+	it('returns false for empty object', () => {
+		expect(hasErrorProperty({})).toBe(false);
+	});
+
+	it('returns false for array', () => {
+		expect(hasErrorProperty(['error'])).toBe(false);
+	});
+});
+
+describe('extractApiError', () => {
+	it('extracts string error from response', () => {
+		expect(extractApiError({ error: 'Not found' })).toBe('Not found');
+	});
+
+	it('extracts message from nested error object', () => {
+		expect(extractApiError({ error: { message: 'Validation failed' } })).toBe('Validation failed');
+	});
+
+	it('returns "Unknown error" for non-string error without message', () => {
+		expect(extractApiError({ error: { code: 500 } })).toBe('Unknown error');
+	});
+
+	it('returns null for data without error property', () => {
+		expect(extractApiError({ success: true })).toBeNull();
+	});
+
+	it('returns null for null input', () => {
+		expect(extractApiError(null)).toBeNull();
+	});
+
+	it('returns null for undefined input', () => {
+		expect(extractApiError(undefined)).toBeNull();
+	});
+
+	it('returns null for string input', () => {
+		expect(extractApiError('error')).toBeNull();
+	});
+
+	it('returns null for empty object', () => {
+		expect(extractApiError({})).toBeNull();
+	});
+
+	it('handles empty string error', () => {
+		expect(extractApiError({ error: '' })).toBe('');
+	});
+
+	it('returns "Unknown error" for error as number', () => {
+		expect(extractApiError({ error: 404 })).toBe('Unknown error');
+	});
+
+	it('returns "Unknown error" for error as boolean', () => {
+		expect(extractApiError({ error: true })).toBe('Unknown error');
+	});
+
+	it('handles deeply nested message', () => {
+		// Only extracts from immediate .message property
+		expect(extractApiError({ error: { nested: { message: 'deep' } } })).toBe('Unknown error');
+	});
+});
+
+// ============================================================================
+// Pagination Utilities Tests
+// ============================================================================
+
+describe('PAGINATION_LIMITS', () => {
+	it('should have expected default values', () => {
+		expect(PAGINATION_LIMITS.DEFAULT_MAX_LIMIT).toBe(50);
+		expect(PAGINATION_LIMITS.DEFAULT_LIMIT).toBe(20);
+		expect(PAGINATION_LIMITS.TASK_LIMIT).toBe(20);
+	});
+});
+
+describe('capPagination', () => {
+	describe('limit capping', () => {
+		it('should cap limit to maxLimit when exceeded', () => {
+			const { cappedLimit } = capPagination(100, 0, 50);
+			expect(cappedLimit).toBe(50);
+		});
+
+		it('should use limit when under maxLimit', () => {
+			const { cappedLimit } = capPagination(25, 0, 50);
+			expect(cappedLimit).toBe(25);
+		});
+
+		it('should use default maxLimit when not specified', () => {
+			const { cappedLimit } = capPagination(100, 0);
+			expect(cappedLimit).toBe(PAGINATION_LIMITS.DEFAULT_MAX_LIMIT);
+		});
+
+		it('should enforce minimum limit of 1', () => {
+			const { cappedLimit } = capPagination(0, 0, 50);
+			expect(cappedLimit).toBe(1);
+		});
+
+		it('should handle negative limit', () => {
+			const { cappedLimit } = capPagination(-5, 0, 50);
+			expect(cappedLimit).toBe(1);
+		});
+
+		it('should use DEFAULT_LIMIT when limit is undefined', () => {
+			const { cappedLimit } = capPagination(undefined, 0, 50);
+			expect(cappedLimit).toBe(PAGINATION_LIMITS.DEFAULT_LIMIT);
+		});
+	});
+
+	describe('offset safety', () => {
+		it('should keep positive offset unchanged', () => {
+			const { safeOffset } = capPagination(10, 50, 50);
+			expect(safeOffset).toBe(50);
+		});
+
+		it('should convert negative offset to 0', () => {
+			const { safeOffset } = capPagination(10, -10, 50);
+			expect(safeOffset).toBe(0);
+		});
+
+		it('should handle zero offset', () => {
+			const { safeOffset } = capPagination(10, 0, 50);
+			expect(safeOffset).toBe(0);
+		});
+
+		it('should use 0 when offset is undefined', () => {
+			const { safeOffset } = capPagination(10, undefined, 50);
+			expect(safeOffset).toBe(0);
+		});
+	});
+
+	describe('combined behavior', () => {
+		it('should return both cappedLimit and safeOffset', () => {
+			const result = capPagination(100, -5, 20);
+			expect(result).toEqual({
+				cappedLimit: 20,
+				safeOffset: 0,
+			});
+		});
+
+		it('should work with task limit constant', () => {
+			const result = capPagination(50, 10, PAGINATION_LIMITS.TASK_LIMIT);
+			expect(result).toEqual({
+				cappedLimit: 20,
+				safeOffset: 10,
+			});
+		});
+
+		it('should handle all undefined values', () => {
+			const result = capPagination(undefined, undefined);
+			expect(result).toEqual({
+				cappedLimit: PAGINATION_LIMITS.DEFAULT_LIMIT,
+				safeOffset: 0,
+			});
+		});
+	});
+});