@vibescope/mcp-server 0.1.0 → 0.2.1

package/src/handlers/fallback.test.ts

@@ -145,6 +145,84 @@ describe('startFallbackActivity', () => {
 			}, ctx)
 		).rejects.toThrow('Failed to start fallback activity');
 	});
+
+	it('should pass through worktree guidance when API returns it', async () => {
+		mockApiClient.startFallbackActivity.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				activity: 'code_review',
+				message: 'Started code_review',
+				git_workflow: {
+					workflow: 'git-flow',
+					base_branch: 'develop',
+					worktree_recommended: true,
+					note: 'Fallback activities use the base branch directly (read-only).',
+				},
+				worktree_setup: {
+					message: 'RECOMMENDED: Create a worktree to avoid conflicts.',
+					commands: [
+						'git checkout develop',
+						'git pull origin develop',
+						'git worktree add ../Project-code-review develop',
+						'cd ../Project-code-review',
+					],
+					worktree_path: '../Project-code-review',
+					branch_name: 'develop',
+					cleanup_command: 'git worktree remove ../Project-code-review',
+					report_worktree: 'heartbeat(current_worktree_path: "../Project-code-review")',
+				},
+				next_step: 'After setting up worktree: call heartbeat to report your location.',
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await startFallbackActivity(
+			{
+				project_id: '123e4567-e89b-12d3-a456-426614174000',
+				activity: 'code_review',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			activity: 'code_review',
+		});
+		expect((result.result as { git_workflow?: unknown }).git_workflow).toBeDefined();
+		expect((result.result as { git_workflow: { workflow: string } }).git_workflow.workflow).toBe('git-flow');
+		expect((result.result as { worktree_setup?: unknown }).worktree_setup).toBeDefined();
+		expect((result.result as { worktree_setup: { worktree_path: string } }).worktree_setup.worktree_path).toBe('../Project-code-review');
+		expect((result.result as { next_step?: string }).next_step).toContain('heartbeat');
+	});
+
+	it('should not include worktree guidance when API does not return it', async () => {
+		mockApiClient.startFallbackActivity.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				activity: 'code_review',
+				message: 'Started code_review',
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await startFallbackActivity(
+			{
+				project_id: '123e4567-e89b-12d3-a456-426614174000',
+				activity: 'code_review',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			activity: 'code_review',
+		});
+		expect((result.result as { git_workflow?: unknown }).git_workflow).toBeUndefined();
+		expect((result.result as { worktree_setup?: unknown }).worktree_setup).toBeUndefined();
+		expect((result.result as { next_step?: string }).next_step).toBeUndefined();
+	});
 });
 
 // ============================================================================

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}`);
@@ -51,23 +66,31 @@ export const startFallbackActivity: Handler = async (args, ctx) => {
 	// Get the activity details for the response
 	const activityInfo = FALLBACK_ACTIVITIES.find((a) => a.activity === activity);
 
-	return {
-		result: {
-			success: true,
-			activity,
-			title: activityInfo?.title || activity,
-			description: activityInfo?.description || '',
-			prompt: activityInfo?.prompt || '',
-			message: response.data?.message || `Started fallback activity: ${activityInfo?.title || activity}`,
-		},
+	const result: Record<string, unknown> = {
+		success: true,
+		activity,
+		title: activityInfo?.title || activity,
+		description: activityInfo?.description || '',
+		prompt: activityInfo?.prompt || '',
+		message: response.data?.message || `Started fallback activity: ${activityInfo?.title || activity}`,
 	};
+
+	// Pass through worktree guidance if provided
+	if (response.data?.git_workflow) {
+		result.git_workflow = response.data.git_workflow;
+	}
+	if (response.data?.worktree_setup) {
+		result.worktree_setup = response.data.worktree_setup;
+	}
+	if (response.data?.next_step) {
+		result.next_step = response.data.next_step;
+	}
+
+	return { result };
 };
 
 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();
@@ -86,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();
 
@@ -127,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');
+	});
+});