@vibescope/mcp-server 0.2.0 → 0.2.2

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

@@ -0,0 +1,670 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+	checkoutFile,
+	checkinFile,
+	getFileCheckouts,
+	abandonCheckout,
+	isFileAvailable,
+} 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 return error when API call fails', async () => {
+		mockApiClient.checkoutFile.mockResolvedValue({
+			ok: false,
+			error: 'File already checked out',
+		});
+		const ctx = createMockContext();
+
+		const result = await checkoutFile({
+			project_id: VALID_UUID,
+			file_path: '/src/index.ts',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'File already checked out' });
+	});
+
+	it('should return default error when API fails without message', async () => {
+		mockApiClient.checkoutFile.mockResolvedValue({
+			ok: false,
+		});
+		const ctx = createMockContext();
+
+		const result = await checkoutFile({
+			project_id: VALID_UUID,
+			file_path: '/src/index.ts',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Failed to checkout file' });
+	});
+});
+
+// ============================================================================
+// checkinFile Tests
+// ============================================================================
+
+describe('checkinFile', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should return error when neither checkout_id nor project_id+file_path provided', async () => {
+		const ctx = createMockContext();
+
+		const result = await checkinFile({}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Either checkout_id or both project_id and file_path are required' });
+	});
+
+	it('should return error when only project_id provided without file_path', async () => {
+		const ctx = createMockContext();
+
+		const result = await checkinFile({ project_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Either checkout_id or both project_id and file_path are required' });
+	});
+
+	it('should return error when only file_path provided without project_id', async () => {
+		const ctx = createMockContext();
+
+		const result = await checkinFile({ file_path: '/src/index.ts' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: '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 return error when API call fails', async () => {
+		mockApiClient.checkinFile.mockResolvedValue({
+			ok: false,
+			error: 'Checkout not found',
+		});
+		const ctx = createMockContext();
+
+		const result = await checkinFile({ checkout_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: '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 return error when API call fails', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: false,
+			error: 'Database error',
+		});
+		const ctx = createMockContext();
+
+		const result = await getFileCheckouts({ project_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Database error' });
+	});
+});
+
+// ============================================================================
+// abandonCheckout Tests
+// ============================================================================
+
+describe('abandonCheckout', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should return error when neither checkout_id nor project_id+file_path provided', async () => {
+		const ctx = createMockContext();
+
+		const result = await abandonCheckout({}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Either checkout_id or both project_id and file_path are required' });
+	});
+
+	it('should return error when only project_id provided without file_path', async () => {
+		const ctx = createMockContext();
+
+		const result = await abandonCheckout({ project_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: '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 return error when API call fails', async () => {
+		mockApiClient.abandonCheckout.mockResolvedValue({
+			ok: false,
+			error: 'Checkout not found',
+		});
+		const ctx = createMockContext();
+
+		const result = await abandonCheckout({ checkout_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Checkout not found' });
+	});
+
+	it('should return default error when API fails without message', async () => {
+		mockApiClient.abandonCheckout.mockResolvedValue({
+			ok: false,
+		});
+		const ctx = createMockContext();
+
+		const result = await abandonCheckout({ checkout_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Failed to abandon checkout' });
+	});
+});
+
+// ============================================================================
+// isFileAvailable Tests
+// ============================================================================
+
+describe('isFileAvailable', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			isFileAvailable({ file_path: '/src/index.ts' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid project_id UUID', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			isFileAvailable({ 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(
+			isFileAvailable({ project_id: VALID_UUID }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should return available=true when file has no active checkout', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: true,
+			data: { checkouts: [] },
+		});
+		const ctx = createMockContext();
+
+		const result = await isFileAvailable(
+			{
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			available: true,
+			file_path: '/src/index.ts',
+			checked_out_by: null,
+		});
+	});
+
+	it('should return available=false with checkout info when file is checked out', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: true,
+			data: {
+				checkouts: [{
+					id: 'checkout-123',
+					file_path: '/src/index.ts',
+					status: 'checked_out',
+					checked_out_by: 'Apex',
+					checked_out_at: '2026-01-16T10:00:00Z',
+					checkout_reason: 'Working on feature X',
+				}],
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await isFileAvailable(
+			{
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			available: false,
+			file_path: '/src/index.ts',
+			checked_out_by: {
+				checkout_id: 'checkout-123',
+				checked_out_by: 'Apex',
+				checked_out_at: '2026-01-16T10:00:00Z',
+				reason: 'Working on feature X',
+			},
+		});
+	});
+
+	it('should query API with correct parameters', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: true,
+			data: { checkouts: [] },
+		});
+		const ctx = createMockContext();
+
+		await isFileAvailable(
+			{
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+			},
+			ctx
+		);
+
+		expect(mockApiClient.getFileCheckouts).toHaveBeenCalledWith(VALID_UUID, {
+			status: 'checked_out',
+			file_path: '/src/index.ts',
+			limit: 1,
+		});
+	});
+
+	it('should return error when API call fails', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: false,
+			error: 'Project not found',
+		});
+		const ctx = createMockContext();
+
+		const result = await isFileAvailable({
+			project_id: VALID_UUID,
+			file_path: '/src/index.ts',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Project not found' });
+	});
+
+	it('should return default error when API fails without message', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: false,
+		});
+		const ctx = createMockContext();
+
+		const result = await isFileAvailable({
+			project_id: VALID_UUID,
+			file_path: '/src/index.ts',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Failed to check file availability' });
+	});
+
+	it('should handle empty checkouts array gracefully', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: true,
+			data: { checkouts: [] },
+		});
+		const ctx = createMockContext();
+
+		const result = await isFileAvailable(
+			{
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+			},
+			ctx
+		);
+
+		expect(result.result.available).toBe(true);
+		expect(result.result.checked_out_by).toBeNull();
+	});
+
+	it('should handle undefined checkouts gracefully', async () => {
+		mockApiClient.getFileCheckouts.mockResolvedValue({
+			ok: true,
+			data: {},
+		});
+		const ctx = createMockContext();
+
+		const result = await isFileAvailable(
+			{
+				project_id: VALID_UUID,
+				file_path: '/src/index.ts',
+			},
+			ctx
+		);
+
+		expect(result.result.available).toBe(true);
+		expect(result.result.checked_out_by).toBeNull();
+	});
+});