@vibescope/mcp-server 0.5.0 → 0.5.2

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

@@ -1,750 +1,750 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import {
-	checkoutFile,
-	checkinFile,
-	getFileCheckouts,
-	abandonCheckout,
-	isFileAvailable,
-	getFileCheckoutsStats,
-} 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, offset: 0 }
-		);
-	});
-
-	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, offset: 0 }
-		);
-	});
-
-	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, offset: 0 }
-		);
-	});
-
-	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();
-	});
-});
-
-// ============================================================================
-// getFileCheckoutsStats Tests
-// ============================================================================
-
-describe('getFileCheckoutsStats', () => {
-	beforeEach(() => vi.clearAllMocks());
-
-	it('should throw error for missing project_id', async () => {
-		const ctx = createMockContext();
-
-		await expect(
-			getFileCheckoutsStats({}, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should throw error for invalid project_id UUID', async () => {
-		const ctx = createMockContext();
-
-		await expect(
-			getFileCheckoutsStats({ project_id: 'invalid-uuid' }, ctx)
-		).rejects.toThrow(ValidationError);
-	});
-
-	it('should return stats from API', async () => {
-		mockApiClient.getFileCheckoutsStats.mockResolvedValue({
-			ok: true,
-			data: {
-				total: 10,
-				by_status: {
-					checked_out: 5,
-					checked_in: 3,
-					abandoned: 2,
-				},
-			},
-		});
-		const ctx = createMockContext();
-
-		const result = await getFileCheckoutsStats(
-			{ project_id: VALID_UUID },
-			ctx
-		);
-
-		expect(result.result).toMatchObject({
-			total: 10,
-			by_status: {
-				checked_out: 5,
-				checked_in: 3,
-				abandoned: 2,
-			},
-		});
-		expect(mockApiClient.getFileCheckoutsStats).toHaveBeenCalledWith(VALID_UUID);
-	});
-
-	it('should return error when API call fails', async () => {
-		mockApiClient.getFileCheckoutsStats.mockResolvedValue({
-			ok: false,
-			error: 'Database error',
-		});
-		const ctx = createMockContext();
-
-		const result = await getFileCheckoutsStats({ project_id: VALID_UUID }, ctx);
-
-		expect(result.isError).toBe(true);
-		expect(result.result).toMatchObject({ error: 'Database error' });
-	});
-
-	it('should return default error when API fails without message', async () => {
-		mockApiClient.getFileCheckoutsStats.mockResolvedValue({
-			ok: false,
-		});
-		const ctx = createMockContext();
-
-		const result = await getFileCheckoutsStats({ project_id: VALID_UUID }, ctx);
-
-		expect(result.isError).toBe(true);
-		expect(result.result).toMatchObject({ error: 'Failed to get file checkouts stats' });
-	});
-});
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+	checkoutFile,
+	checkinFile,
+	getFileCheckouts,
+	abandonCheckout,
+	isFileAvailable,
+	getFileCheckoutsStats,
+} 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, offset: 0 }
+		);
+	});
+
+	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, offset: 0 }
+		);
+	});
+
+	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, offset: 0 }
+		);
+	});
+
+	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();
+	});
+});
+
+// ============================================================================
+// getFileCheckoutsStats Tests
+// ============================================================================
+
+describe('getFileCheckoutsStats', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			getFileCheckoutsStats({}, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid project_id UUID', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			getFileCheckoutsStats({ project_id: 'invalid-uuid' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should return stats from API', async () => {
+		mockApiClient.getFileCheckoutsStats.mockResolvedValue({
+			ok: true,
+			data: {
+				total: 10,
+				by_status: {
+					checked_out: 5,
+					checked_in: 3,
+					abandoned: 2,
+				},
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await getFileCheckoutsStats(
+			{ project_id: VALID_UUID },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			total: 10,
+			by_status: {
+				checked_out: 5,
+				checked_in: 3,
+				abandoned: 2,
+			},
+		});
+		expect(mockApiClient.getFileCheckoutsStats).toHaveBeenCalledWith(VALID_UUID);
+	});
+
+	it('should return error when API call fails', async () => {
+		mockApiClient.getFileCheckoutsStats.mockResolvedValue({
+			ok: false,
+			error: 'Database error',
+		});
+		const ctx = createMockContext();
+
+		const result = await getFileCheckoutsStats({ project_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Database error' });
+	});
+
+	it('should return default error when API fails without message', async () => {
+		mockApiClient.getFileCheckoutsStats.mockResolvedValue({
+			ok: false,
+		});
+		const ctx = createMockContext();
+
+		const result = await getFileCheckoutsStats({ project_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Failed to get file checkouts stats' });
+	});
+});