@vibescope/mcp-server 0.2.0 → 0.2.2

package/src/handlers/file-checkouts.ts

@@ -0,0 +1,165 @@
+/**
+ * File Checkouts Handlers
+ *
+ * Handles file checkout/checkin for multi-agent coordination:
+ * - checkout_file: Check out a file before editing
+ * - checkin_file: Check in a file after editing
+ * - get_file_checkouts: Get active checkouts for a project
+ * - abandon_checkout: Force release a checkout
+ * - is_file_available: Check if a file is available for checkout
+ */
+
+import type { Handler, HandlerRegistry } from './types.js';
+import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
+import { getApiClient } from '../api-client.js';
+
+const VALID_CHECKOUT_STATUSES = ['checked_out', 'checked_in', 'abandoned'] as const;
+
+// Argument schemas for type-safe parsing
+const checkoutFileSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	file_path: { type: 'string' as const, required: true as const },
+	reason: { type: 'string' as const },
+};
+
+const checkinFileSchema = {
+	checkout_id: { type: 'string' as const, validate: uuidValidator },
+	project_id: { type: 'string' as const, validate: uuidValidator },
+	file_path: { type: 'string' as const },
+	summary: { type: 'string' as const },
+};
+
+const getFileCheckoutsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	status: { type: 'string' as const, validate: createEnumValidator(VALID_CHECKOUT_STATUSES) },
+	file_path: { type: 'string' as const },
+	limit: { type: 'number' as const, default: 50 },
+};
+
+const abandonCheckoutSchema = {
+	checkout_id: { type: 'string' as const, validate: uuidValidator },
+	project_id: { type: 'string' as const, validate: uuidValidator },
+	file_path: { type: 'string' as const },
+};
+
+const isFileAvailableSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	file_path: { type: 'string' as const, required: true as const },
+};
+
+export const checkoutFile: Handler = async (args, ctx) => {
+	const { project_id, file_path, reason } = parseArgs(args, checkoutFileSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.checkoutFile(project_id, file_path, reason, ctx.session.currentSessionId || undefined);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to checkout file' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const checkinFile: Handler = async (args, ctx) => {
+	const { checkout_id, project_id, file_path, summary } = parseArgs(args, checkinFileSchema);
+
+	// Validate that either checkout_id or both project_id and file_path are provided
+	if (!checkout_id && (!project_id || !file_path)) {
+		return { result: { error: 'Either checkout_id or both project_id and file_path are required' }, isError: true };
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.checkinFile({
+		checkout_id,
+		project_id,
+		file_path,
+		summary
+	}, ctx.session.currentSessionId || undefined);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to checkin file' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const getFileCheckouts: Handler = async (args, _ctx) => {
+	const { project_id, status, file_path, limit } = parseArgs(args, getFileCheckoutsSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.getFileCheckouts(project_id, {
+		status,
+		file_path,
+		limit
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to get file checkouts' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const abandonCheckout: Handler = async (args, _ctx) => {
+	const { checkout_id, project_id, file_path } = parseArgs(args, abandonCheckoutSchema);
+
+	// Validate that either checkout_id or both project_id and file_path are provided
+	if (!checkout_id && (!project_id || !file_path)) {
+		return { result: { error: 'Either checkout_id or both project_id and file_path are required' }, isError: true };
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.abandonCheckout({
+		checkout_id,
+		project_id,
+		file_path
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to abandon checkout' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const isFileAvailable: Handler = async (args, _ctx) => {
+	const { project_id, file_path } = parseArgs(args, isFileAvailableSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.getFileCheckouts(project_id, {
+		status: 'checked_out',
+		file_path,
+		limit: 1
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to check file availability' }, isError: true };
+	}
+
+	const checkouts = response.data?.checkouts || [];
+	const activeCheckout = checkouts.length > 0 ? checkouts[0] : null;
+
+	return {
+		result: {
+			available: !activeCheckout,
+			file_path,
+			checked_out_by: activeCheckout ? {
+				checkout_id: activeCheckout.id,
+				checked_out_by: activeCheckout.checked_out_by,
+				checked_out_at: activeCheckout.checked_out_at,
+				reason: activeCheckout.checkout_reason
+			} : null
+		}
+	};
+};
+
+/**
+ * File Checkouts handlers registry
+ */
+export const fileCheckoutHandlers: HandlerRegistry = {
+	checkout_file: checkoutFile,
+	checkin_file: checkinFile,
+	get_file_checkouts: getFileCheckouts,
+	abandon_checkout: abandonCheckout,
+	is_file_available: isFileAvailable,
+};

package/src/handlers/findings.test.ts

@@ -5,6 +5,7 @@ import {
 	getFindingsStats,
 	updateFinding,
 	deleteFinding,
+	queryKnowledgeBase,
 } from './findings.js';
 import { ValidationError } from '../validators.js';
 import { createMockContext } from './__test-utils__.js';
@@ -105,16 +106,17 @@ describe('addFinding', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.addFinding.mockResolvedValue({
 			ok: false,
 			error: 'Insert failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			addFinding({ project_id: VALID_UUID, title: 'Test' }, ctx)
-		).rejects.toThrow('Insert failed');
+		const result = await addFinding({ project_id: VALID_UUID, title: 'Test' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Insert failed' });
 	});
 });
 
@@ -258,16 +260,17 @@ describe('getFindings', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.getFindings.mockResolvedValue({
 			ok: false,
 			error: 'Query failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			getFindings({ project_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Query failed');
+		const result = await getFindings({ project_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Query failed' });
 	});
 });
 
@@ -338,16 +341,17 @@ describe('updateFinding', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.updateFinding.mockResolvedValue({
 			ok: false,
 			error: 'Update failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			updateFinding({ finding_id: VALID_UUID, title: 'Test' }, ctx)
-		).rejects.toThrow('Update failed');
+		const result = await updateFinding({ finding_id: VALID_UUID, title: 'Test' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Update failed' });
 	});
 });
 
@@ -396,16 +400,17 @@ describe('deleteFinding', () => {
 		expect(mockApiClient.deleteFinding).toHaveBeenCalledWith(VALID_UUID);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.deleteFinding.mockResolvedValue({
 			ok: false,
 			error: 'Delete failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			deleteFinding({ finding_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Delete failed');
+		const result = await deleteFinding({ finding_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Delete failed' });
 	});
 });
 
@@ -460,15 +465,169 @@ describe('getFindingsStats', () => {
 		expect(mockApiClient.getFindingsStats).toHaveBeenCalledWith(VALID_UUID);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.getFindingsStats.mockResolvedValue({
 			ok: false,
 			error: 'Query failed',
 		});
 		const ctx = createMockContext();
 
+		const result = await getFindingsStats({ project_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Query failed' });
+	});
+});
+
+// ============================================================================
+// queryKnowledgeBase Tests
+// ============================================================================
+
+describe('queryKnowledgeBase', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(queryKnowledgeBase({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid project_id UUID', async () => {
+		const ctx = createMockContext();
+
 		await expect(
-			getFindingsStats({ project_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Query failed');
+			queryKnowledgeBase({ project_id: 'invalid' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid scope value', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			queryKnowledgeBase({ project_id: VALID_UUID, scope: 'invalid_scope' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should query with default parameters', async () => {
+		mockApiClient.queryKnowledgeBase.mockResolvedValue({
+			ok: true,
+			data: {
+				findings: [],
+				decisions: [],
+				completed_tasks: [],
+				resolved_blockers: [],
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await queryKnowledgeBase({ project_id: VALID_UUID }, ctx);
+
+		expect(result.result).toMatchObject({
+			findings: [],
+			decisions: [],
+		});
+		expect(mockApiClient.queryKnowledgeBase).toHaveBeenCalledWith(
+			VALID_UUID,
+			expect.objectContaining({
+				scope: 'summary',
+				limit: 5,
+			})
+		);
+	});
+
+	it('should pass scope parameter', async () => {
+		mockApiClient.queryKnowledgeBase.mockResolvedValue({
+			ok: true,
+			data: { findings: [] },
+		});
+		const ctx = createMockContext();
+
+		await queryKnowledgeBase({ project_id: VALID_UUID, scope: 'detailed' }, ctx);
+
+		expect(mockApiClient.queryKnowledgeBase).toHaveBeenCalledWith(
+			VALID_UUID,
+			expect.objectContaining({ scope: 'detailed' })
+		);
+	});
+
+	it('should pass categories filter', async () => {
+		mockApiClient.queryKnowledgeBase.mockResolvedValue({
+			ok: true,
+			data: { findings: [], decisions: [] },
+		});
+		const ctx = createMockContext();
+
+		await queryKnowledgeBase({
+			project_id: VALID_UUID,
+			categories: ['findings', 'decisions']
+		}, ctx);
+
+		expect(mockApiClient.queryKnowledgeBase).toHaveBeenCalledWith(
+			VALID_UUID,
+			expect.objectContaining({
+				categories: ['findings', 'decisions']
+			})
+		);
+	});
+
+	it('should cap limit at 20', async () => {
+		mockApiClient.queryKnowledgeBase.mockResolvedValue({
+			ok: true,
+			data: { findings: [] },
+		});
+		const ctx = createMockContext();
+
+		await queryKnowledgeBase({ project_id: VALID_UUID, limit: 100 }, ctx);
+
+		expect(mockApiClient.queryKnowledgeBase).toHaveBeenCalledWith(
+			VALID_UUID,
+			expect.objectContaining({ limit: 20 })
+		);
+	});
+
+	it('should enforce minimum limit of 1', async () => {
+		mockApiClient.queryKnowledgeBase.mockResolvedValue({
+			ok: true,
+			data: { findings: [] },
+		});
+		const ctx = createMockContext();
+
+		await queryKnowledgeBase({ project_id: VALID_UUID, limit: -5 }, ctx);
+
+		expect(mockApiClient.queryKnowledgeBase).toHaveBeenCalledWith(
+			VALID_UUID,
+			expect.objectContaining({ limit: 1 })
+		);
+	});
+
+	it('should pass search_query', async () => {
+		mockApiClient.queryKnowledgeBase.mockResolvedValue({
+			ok: true,
+			data: { findings: [] },
+		});
+		const ctx = createMockContext();
+
+		await queryKnowledgeBase({
+			project_id: VALID_UUID,
+			search_query: 'security'
+		}, ctx);
+
+		expect(mockApiClient.queryKnowledgeBase).toHaveBeenCalledWith(
+			VALID_UUID,
+			expect.objectContaining({ search_query: 'security' })
+		);
+	});
+
+	it('should return error when API call fails', async () => {
+		mockApiClient.queryKnowledgeBase.mockResolvedValue({
+			ok: false,
+			error: 'Query failed',
+		});
+		const ctx = createMockContext();
+
+		const result = await queryKnowledgeBase({ project_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Query failed' });
 	});
 });

package/src/handlers/findings.ts

@@ -10,68 +10,97 @@
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
-import { validateRequired, validateUUID } from '../validators.js';
+import { success, error } from './types.js';
+import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
-type FindingCategory = 'performance' | 'security' | 'code_quality' | 'accessibility' | 'documentation' | 'architecture' | 'testing' | 'other';
-type FindingSeverity = 'info' | 'low' | 'medium' | 'high' | 'critical';
-type FindingStatus = 'open' | 'addressed' | 'dismissed' | 'wontfix';
+const VALID_FINDING_CATEGORIES = ['performance', 'security', 'code_quality', 'accessibility', 'documentation', 'architecture', 'testing', 'other'] as const;
+const VALID_FINDING_SEVERITIES = ['info', 'low', 'medium', 'high', 'critical'] as const;
+const VALID_FINDING_STATUSES = ['open', 'addressed', 'dismissed', 'wontfix'] as const;
+
+type FindingCategory = typeof VALID_FINDING_CATEGORIES[number];
+type FindingSeverity = typeof VALID_FINDING_SEVERITIES[number];
+type FindingStatus = typeof VALID_FINDING_STATUSES[number];
+
+// Argument schemas for type-safe parsing
+const addFindingSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const, required: true as const },
+	description: { type: 'string' as const },
+	category: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_CATEGORIES) },
+	severity: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_SEVERITIES) },
+	file_path: { type: 'string' as const },
+	line_number: { type: 'number' as const },
+	related_task_id: { type: 'string' as const, validate: uuidValidator },
+};
+
+const getFindingsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	category: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_CATEGORIES) },
+	severity: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_SEVERITIES) },
+	status: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_STATUSES) },
+	limit: { type: 'number' as const, default: 50 },
+	offset: { type: 'number' as const, default: 0 },
+	search_query: { type: 'string' as const },
+	summary_only: { type: 'boolean' as const, default: false },
+};
+
+const getFindingsStatsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const updateFindingSchema = {
+	finding_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const },
+	description: { type: 'string' as const },
+	severity: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_SEVERITIES) },
+	status: { type: 'string' as const, validate: createEnumValidator(VALID_FINDING_STATUSES) },
+	resolution_note: { type: 'string' as const },
+};
+
+const deleteFindingSchema = {
+	finding_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const VALID_SCOPES = ['summary', 'detailed'] as const;
+
+const queryKnowledgeBaseSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	scope: { type: 'string' as const, default: 'summary', validate: createEnumValidator(VALID_SCOPES) },
+	categories: { type: 'array' as const },
+	limit: { type: 'number' as const, default: 5 },
+	search_query: { type: 'string' as const },
+};
 
 export const addFinding: Handler = async (args, ctx) => {
-	const { project_id, category, title, description, severity, file_path, line_number, related_task_id } = args as {
-		project_id: string;
-		category?: FindingCategory;
-		title: string;
-		description?: string;
-		severity?: FindingSeverity;
-		file_path?: string;
-		line_number?: number;
-		related_task_id?: string;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
-	validateRequired(title, 'title');
-	if (related_task_id) validateUUID(related_task_id, 'related_task_id');
+	const { project_id, title, description, category, severity, file_path, line_number, related_task_id } = parseArgs(args, addFindingSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.addFinding(project_id, {
 		title,
 		description,
-		category,
-		severity,
+		category: category as FindingCategory | undefined,
+		severity: severity as FindingSeverity | undefined,
 		file_path,
 		line_number,
 		related_task_id
 	}, ctx.session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to add finding');
+		return error(response.error || 'Failed to add finding');
 	}
 
-	return { result: response.data };
+	return success(response.data);
 };
 
-export const getFindings: Handler = async (args, ctx) => {
-	const { project_id, category, severity, status, limit = 50, offset = 0, search_query, summary_only = false } = args as {
-		project_id: string;
-		category?: FindingCategory;
-		severity?: FindingSeverity;
-		status?: FindingStatus;
-		limit?: number;
-		offset?: number;
-		search_query?: string;
-		summary_only?: boolean;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+export const getFindings: Handler = async (args, _ctx) => {
+	const { project_id, category, severity, status, limit, offset, search_query, summary_only } = parseArgs(args, getFindingsSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.getFindings(project_id, {
-		category,
-		severity,
-		status,
+		category: category as FindingCategory | undefined,
+		severity: severity as FindingSeverity | undefined,
+		status: status as FindingStatus | undefined,
 		limit,
 		offset,
 		search_query,
@@ -79,10 +108,10 @@ export const getFindings: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to get findings');
+		return error(response.error || 'Failed to get findings');
 	}
 
-	return { result: response.data };
+	return success(response.data);
 };
 
 /**
@@ -90,67 +119,75 @@ export const getFindings: Handler = async (args, ctx) => {
  * Returns counts by category, severity, and status without the actual finding data.
  * This is much more token-efficient than get_findings for understanding the overall state.
  */
-export const getFindingsStats: Handler = async (args, ctx) => {
-	const { project_id } = args as {
-		project_id: string;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+export const getFindingsStats: Handler = async (args, _ctx) => {
+	const { project_id } = parseArgs(args, getFindingsStatsSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.getFindingsStats(project_id);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to get findings stats');
+		return error(response.error || 'Failed to get findings stats');
 	}
 
-	return { result: response.data };
+	return success(response.data);
 };
 
-export const updateFinding: Handler = async (args, ctx) => {
-	const { finding_id, status, resolution_note, title, description, severity } = args as {
-		finding_id: string;
-		status?: FindingStatus;
-		resolution_note?: string;
-		title?: string;
-		description?: string;
-		severity?: FindingSeverity;
-	};
-
-	validateRequired(finding_id, 'finding_id');
-	validateUUID(finding_id, 'finding_id');
+export const updateFinding: Handler = async (args, _ctx) => {
+	const { finding_id, title, description, severity, status, resolution_note } = parseArgs(args, updateFindingSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.updateFinding(finding_id, {
 		title,
 		description,
-		severity,
-		status,
+		severity: severity as FindingSeverity | undefined,
+		status: status as FindingStatus | undefined,
 		resolution_note
 	});
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to update finding');
+		return error(response.error || 'Failed to update finding');
 	}
 
-	return { result: response.data };
+	return success(response.data);
 };
 
-export const deleteFinding: Handler = async (args, ctx) => {
-	const { finding_id } = args as { finding_id: string };
-
-	validateRequired(finding_id, 'finding_id');
-	validateUUID(finding_id, 'finding_id');
+export const deleteFinding: Handler = async (args, _ctx) => {
+	const { finding_id } = parseArgs(args, deleteFindingSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.deleteFinding(finding_id);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to delete finding');
+		return error(response.error || 'Failed to delete finding');
+	}
+
+	return success(response.data);
+};
+
+/**
+ * Query aggregated project knowledge in a single call.
+ * Returns findings, Q&A, decisions, completed tasks, and resolved blockers.
+ * Use this instead of multiple separate tool calls to reduce token usage.
+ */
+export const queryKnowledgeBase: Handler = async (args, _ctx) => {
+	const { project_id, scope, categories, limit, search_query } = parseArgs(args, queryKnowledgeBaseSchema);
+
+	// Validate limit range
+	const effectiveLimit = Math.min(Math.max(1, limit ?? 5), 20);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.queryKnowledgeBase(project_id, {
+		scope: scope as 'summary' | 'detailed' | undefined,
+		categories: categories as string[] | undefined,
+		limit: effectiveLimit,
+		search_query
+	});
+
+	if (!response.ok) {
+		return error(response.error || 'Failed to query knowledge base');
 	}
 
-	return { result: response.data };
+	return success(response.data);
 };
 
 /**
@@ -162,4 +199,5 @@ export const findingHandlers: HandlerRegistry = {
 	get_findings_stats: getFindingsStats,
 	update_finding: updateFinding,
 	delete_finding: deleteFinding,
+	query_knowledge_base: queryKnowledgeBase,
 };