@vibescope/mcp-server 0.2.0 → 0.2.1

package/src/handlers/fallback.ts

@@ -11,7 +11,7 @@
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
-import { validateRequired, validateUUID } from '../validators.js';
+import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js';
 import { FALLBACK_ACTIVITIES } from '../utils.js';
 import { getApiClient } from '../api-client.js';
 
@@ -26,23 +26,38 @@ const VALID_ACTIVITIES = [
 	'documentation_review',
 	'dependency_audit',
 	'validate_completed_tasks',
-];
+] as const;
 
-export const startFallbackActivity: Handler = async (args, ctx) => {
-	const { project_id, activity } = args as { project_id: string; activity: string };
+type FallbackActivity = typeof VALID_ACTIVITIES[number];
 
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
-	validateRequired(activity, 'activity');
+// Argument schemas for type-safe parsing
+const startFallbackActivitySchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	activity: { type: 'string' as const, required: true as const, validate: createEnumValidator(VALID_ACTIVITIES) },
+};
 
-	if (!VALID_ACTIVITIES.includes(activity)) {
-		throw new Error(`Invalid activity. Must be one of: ${VALID_ACTIVITIES.join(', ')}`);
-	}
+const stopFallbackActivitySchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	summary: { type: 'string' as const },
+};
+
+const getActivityHistorySchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	activity_type: { type: 'string' as const },
+	limit: { type: 'number' as const, default: 50 },
+};
+
+const getActivitySchedulesSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+export const startFallbackActivity: Handler = async (args, ctx) => {
+	const { project_id, activity } = parseArgs(args, startFallbackActivitySchema);
 
 	const { session } = ctx;
 	const apiClient = getApiClient();
 
-	const response = await apiClient.startFallbackActivity(project_id, activity, session.currentSessionId || undefined);
+	const response = await apiClient.startFallbackActivity(project_id, activity as FallbackActivity, session.currentSessionId || undefined);
 
 	if (!response.ok) {
 		throw new Error(`Failed to start fallback activity: ${response.error}`);
@@ -75,10 +90,7 @@ export const startFallbackActivity: Handler = async (args, ctx) => {
 };
 
 export const stopFallbackActivity: Handler = async (args, ctx) => {
-	const { project_id, summary } = args as { project_id: string; summary?: string };
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+	const { project_id, summary } = parseArgs(args, stopFallbackActivitySchema);
 
 	const { session } = ctx;
 	const apiClient = getApiClient();
@@ -97,15 +109,8 @@ export const stopFallbackActivity: Handler = async (args, ctx) => {
 	};
 };
 
-export const getActivityHistory: Handler = async (args, ctx) => {
-	const { project_id, activity_type, limit = 50 } = args as {
-		project_id: string;
-		activity_type?: string;
-		limit?: number;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+export const getActivityHistory: Handler = async (args, _ctx) => {
+	const { project_id, activity_type, limit } = parseArgs(args, getActivityHistorySchema);
 
 	const apiClient = getApiClient();
 
@@ -138,11 +143,8 @@ export const getActivityHistory: Handler = async (args, ctx) => {
 	};
 };
 
-export const getActivitySchedules: Handler = async (args, ctx) => {
-	const { project_id } = args as { project_id: string };
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+export const getActivitySchedules: Handler = async (args, _ctx) => {
+	const { project_id } = parseArgs(args, getActivitySchedulesSchema);
 
 	const apiClient = getApiClient();
 

package/src/handlers/file-checkouts.test.ts

@@ -0,0 +1,477 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+	checkoutFile,
+	checkinFile,
+	getFileCheckouts,
+	abandonCheckout,
+} from './file-checkouts.js';
+import { ValidationError } from '../validators.js';
+import { createMockContext, testUUID } from './__test-utils__.js';
+import { mockApiClient } from './__test-setup__.js';
+
+const VALID_UUID = testUUID();
+
+// ============================================================================
+// checkoutFile Tests
+// ============================================================================
+
+describe('checkoutFile', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			checkoutFile({ file_path: '/src/index.ts' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid project_id UUID', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			checkoutFile({ project_id: 'invalid', file_path: '/src/index.ts' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for missing file_path', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			checkoutFile({ project_id: VALID_UUID }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should checkout file successfully', async () => {
+		mockApiClient.checkoutFile.mockResolvedValue({
+			ok: true,
+			data: { success: true, checkout_id: 'checkout-1', file_path: '/src/index.ts' },
+		});
+		const ctx = createMockContext();
+
+		const result = await checkoutFile(
+			{
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			checkout_id: 'checkout-1',
+		});
+	});
+
+	it('should include reason in API call when provided', async () => {
+		mockApiClient.checkoutFile.mockResolvedValue({
+			ok: true,
+			data: { success: true, checkout_id: 'checkout-1', file_path: '/src/index.ts' },
+		});
+		const ctx = createMockContext({ sessionId: 'my-session' });
+
+		await checkoutFile(
+			{
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+				reason: 'Editing for feature X',
+			},
+			ctx
+		);
+
+		expect(mockApiClient.checkoutFile).toHaveBeenCalledWith(
+			VALID_UUID,
+			'/src/index.ts',
+			'Editing for feature X',
+			'my-session'
+		);
+	});
+
+	it('should throw error when API call fails', async () => {
+		mockApiClient.checkoutFile.mockResolvedValue({
+			ok: false,
+			error: 'File already checked out',
+		});
+		const ctx = createMockContext();
+
+		await expect(
+			checkoutFile({
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+			}, ctx)
+		).rejects.toThrow('File already checked out');
+	});
+
+	it('should throw default error when API fails without message', async () => {
+		mockApiClient.checkoutFile.mockResolvedValue({
+			ok: false,
+		});
+		const ctx = createMockContext();
+
+		await expect(
+			checkoutFile({
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+			}, ctx)
+		).rejects.toThrow('Failed to checkout file');
+	});
+});
+
+// ============================================================================
+// checkinFile Tests
+// ============================================================================
+
+describe('checkinFile', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error when neither checkout_id nor project_id+file_path provided', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			checkinFile({}, ctx)
+		).rejects.toThrow('Either checkout_id or both project_id and file_path are required');
+	});
+
+	it('should throw error when only project_id provided without file_path', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			checkinFile({ project_id: VALID_UUID }, ctx)
+		).rejects.toThrow('Either checkout_id or both project_id and file_path are required');
+	});
+
+	it('should throw error when only file_path provided without project_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			checkinFile({ file_path: '/src/index.ts' }, ctx)
+		).rejects.toThrow('Either checkout_id or both project_id and file_path are required');
+	});
+
+	it('should throw error for invalid checkout_id UUID', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			checkinFile({ checkout_id: 'invalid' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should checkin file successfully with checkout_id', async () => {
+		mockApiClient.checkinFile.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+		const ctx = createMockContext();
+
+		const result = await checkinFile(
+			{ checkout_id: VALID_UUID },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ success: true });
+	});
+
+	it('should checkin file successfully with project_id and file_path', async () => {
+		mockApiClient.checkinFile.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+		const ctx = createMockContext();
+
+		const result = await checkinFile(
+			{
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ success: true });
+	});
+
+	it('should include summary in API call', async () => {
+		mockApiClient.checkinFile.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+		const ctx = createMockContext({ sessionId: 'my-session' });
+
+		await checkinFile(
+			{
+				checkout_id: VALID_UUID,
+				summary: 'Added validation logic',
+			},
+			ctx
+		);
+
+		expect(mockApiClient.checkinFile).toHaveBeenCalledWith(
+			{
+				checkout_id: VALID_UUID,
+				project_id: undefined,
+				file_path: undefined,
+				summary: 'Added validation logic',
+			},
+			'my-session'
+		);
+	});
+
+	it('should throw error when API call fails', async () => {
+		mockApiClient.checkinFile.mockResolvedValue({
+			ok: false,
+			error: 'Checkout not found',
+		});
+		const ctx = createMockContext();
+
+		await expect(
+			checkinFile({ checkout_id: VALID_UUID }, ctx)
+		).rejects.toThrow('Checkout not found');
+	});
+});
+
+// ============================================================================
+// getFileCheckouts Tests
+// ============================================================================
+
+describe('getFileCheckouts', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			getFileCheckouts({}, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid project_id UUID', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			getFileCheckouts({ project_id: 'invalid' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid status', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			getFileCheckouts({ project_id: VALID_UUID, status: 'invalid_status' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should get file checkouts successfully', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: true,
+			data: {
+				checkouts: [
+					{ id: 'checkout-1', file_path: '/src/index.ts', status: 'checked_out' },
+				],
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await getFileCheckouts(
+			{ project_id: VALID_UUID },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			checkouts: [
+				{ id: 'checkout-1', file_path: '/src/index.ts', status: 'checked_out' },
+			],
+		});
+	});
+
+	it('should filter by status', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: true,
+			data: { checkouts: [] },
+		});
+		const ctx = createMockContext();
+
+		await getFileCheckouts(
+			{ project_id: VALID_UUID, status: 'checked_out' },
+			ctx
+		);
+
+		expect(mockApiClient.getFileCheckouts).toHaveBeenCalledWith(
+			VALID_UUID,
+			{ status: 'checked_out', file_path: undefined, limit: 50 }
+		);
+	});
+
+	it('should filter by file_path', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: true,
+			data: { checkouts: [] },
+		});
+		const ctx = createMockContext();
+
+		await getFileCheckouts(
+			{ project_id: VALID_UUID, file_path: '/src/utils.ts' },
+			ctx
+		);
+
+		expect(mockApiClient.getFileCheckouts).toHaveBeenCalledWith(
+			VALID_UUID,
+			{ status: undefined, file_path: '/src/utils.ts', limit: 50 }
+		);
+	});
+
+	it('should use custom limit', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: true,
+			data: { checkouts: [] },
+		});
+		const ctx = createMockContext();
+
+		await getFileCheckouts(
+			{ project_id: VALID_UUID, limit: 10 },
+			ctx
+		);
+
+		expect(mockApiClient.getFileCheckouts).toHaveBeenCalledWith(
+			VALID_UUID,
+			{ status: undefined, file_path: undefined, limit: 10 }
+		);
+	});
+
+	it('should accept all valid status values', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: true,
+			data: { checkouts: [] },
+		});
+		const ctx = createMockContext();
+
+		for (const status of ['checked_out', 'checked_in', 'abandoned']) {
+			await getFileCheckouts(
+				{ project_id: VALID_UUID, status },
+				ctx
+			);
+		}
+
+		expect(mockApiClient.getFileCheckouts).toHaveBeenCalledTimes(3);
+	});
+
+	it('should throw error when API call fails', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: false,
+			error: 'Database error',
+		});
+		const ctx = createMockContext();
+
+		await expect(
+			getFileCheckouts({ project_id: VALID_UUID }, ctx)
+		).rejects.toThrow('Database error');
+	});
+});
+
+// ============================================================================
+// abandonCheckout Tests
+// ============================================================================
+
+describe('abandonCheckout', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error when neither checkout_id nor project_id+file_path provided', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			abandonCheckout({}, ctx)
+		).rejects.toThrow('Either checkout_id or both project_id and file_path are required');
+	});
+
+	it('should throw error when only project_id provided without file_path', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			abandonCheckout({ project_id: VALID_UUID }, ctx)
+		).rejects.toThrow('Either checkout_id or both project_id and file_path are required');
+	});
+
+	it('should throw error for invalid checkout_id UUID', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			abandonCheckout({ checkout_id: 'invalid' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should abandon checkout successfully with checkout_id', async () => {
+		mockApiClient.abandonCheckout.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+		const ctx = createMockContext();
+
+		const result = await abandonCheckout(
+			{ checkout_id: VALID_UUID },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ success: true });
+	});
+
+	it('should abandon checkout successfully with project_id and file_path', async () => {
+		mockApiClient.abandonCheckout.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+		const ctx = createMockContext();
+
+		const result = await abandonCheckout(
+			{
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ success: true });
+	});
+
+	it('should pass params correctly to API', async () => {
+		mockApiClient.abandonCheckout.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+		const ctx = createMockContext();
+
+		await abandonCheckout(
+			{
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+			},
+			ctx
+		);
+
+		expect(mockApiClient.abandonCheckout).toHaveBeenCalledWith({
+			checkout_id: undefined,
+			project_id: VALID_UUID,
+			file_path: '/src/index.ts',
+		});
+	});
+
+	it('should throw error when API call fails', async () => {
+		mockApiClient.abandonCheckout.mockResolvedValue({
+			ok: false,
+			error: 'Checkout not found',
+		});
+		const ctx = createMockContext();
+
+		await expect(
+			abandonCheckout({ checkout_id: VALID_UUID }, ctx)
+		).rejects.toThrow('Checkout not found');
+	});
+
+	it('should throw default error when API fails without message', async () => {
+		mockApiClient.abandonCheckout.mockResolvedValue({
+			ok: false,
+		});
+		const ctx = createMockContext();
+
+		await expect(
+			abandonCheckout({ checkout_id: VALID_UUID }, ctx)
+		).rejects.toThrow('Failed to abandon checkout');
+	});
+});

package/src/handlers/file-checkouts.ts

@@ -0,0 +1,127 @@
+/**
+ * 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
+ */
+
+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 },
+};
+
+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) {
+		throw new Error(response.error || 'Failed to checkout file');
+	}
+
+	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)) {
+		throw new Error('Either checkout_id or both project_id and file_path are required');
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.checkinFile({
+		checkout_id,
+		project_id,
+		file_path,
+		summary
+	}, ctx.session.currentSessionId || undefined);
+
+	if (!response.ok) {
+		throw new Error(response.error || 'Failed to checkin file');
+	}
+
+	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) {
+		throw new Error(response.error || 'Failed to get file checkouts');
+	}
+
+	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)) {
+		throw new Error('Either checkout_id or both project_id and file_path are required');
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.abandonCheckout({
+		checkout_id,
+		project_id,
+		file_path
+	});
+
+	if (!response.ok) {
+		throw new Error(response.error || 'Failed to abandon checkout');
+	}
+
+	return { result: response.data };
+};
+
+/**
+ * File Checkouts handlers registry
+ */
+export const fileCheckoutHandlers: HandlerRegistry = {
+	checkout_file: checkoutFile,
+	checkin_file: checkinFile,
+	get_file_checkouts: getFileCheckouts,
+	abandon_checkout: abandonCheckout,
+};