@vibescope/mcp-server 0.2.0 → 0.2.2

package/src/handlers/types.ts

@@ -74,14 +74,93 @@ export interface HandlerContext {
 }
 
 /**
- * Result returned by handlers
+ * Success result with typed data
  */
-export interface HandlerResult {
+export interface SuccessResult<T = unknown> {
+	result: T;
+	content?: Array<{ type: string; text: string }>;
+	isError?: false;
+}
+
+/**
+ * Error result with error information
+ */
+export interface ErrorResult {
+	result: { error: string; [key: string]: unknown };
+	content?: Array<{ type: string; text: string }>;
+	isError: true;
+}
+
+/**
+ * Result returned by handlers - discriminated union for type safety
+ * Use the helper functions success() and error() to create properly typed results.
+ */
+export type HandlerResult<T = unknown> = SuccessResult<T> | ErrorResult;
+
+/**
+ * Legacy HandlerResult interface for backward compatibility
+ * @deprecated Use HandlerResult<T> discriminated union instead
+ */
+export interface LegacyHandlerResult {
 	result?: unknown;
 	content?: Array<{ type: string; text: string }>;
 	isError?: boolean;
 }
 
+// ============================================================================
+// Result Factory Functions - use these for type-safe handler results
+// ============================================================================
+
+/**
+ * Create a success result with typed data
+ * @example
+ * return success({ tasks: data, total_count: count });
+ */
+export function success<T>(data: T): SuccessResult<T> {
+	return { result: data };
+}
+
+/**
+ * Create an error result
+ * @example
+ * return error('Task not found');
+ * return error('Validation failed', { field: 'title', reason: 'too long' });
+ */
+export function error(message: string, details?: Record<string, unknown>): ErrorResult {
+	return {
+		result: { error: message, ...details },
+		isError: true
+	};
+}
+
+// ============================================================================
+// Type Predicates - use for runtime type narrowing
+// ============================================================================
+
+/**
+ * Check if a handler result is a success (not an error)
+ * @example
+ * const result = await handler(args, ctx);
+ * if (isSuccess(result)) {
+ *   console.log(result.result); // typed as T
+ * }
+ */
+export function isSuccess<T>(result: HandlerResult<T>): result is SuccessResult<T> {
+	return !result.isError;
+}
+
+/**
+ * Check if a handler result is an error
+ * @example
+ * const result = await handler(args, ctx);
+ * if (isError(result)) {
+ *   console.log(result.result.error); // string
+ * }
+ */
+export function isError(result: HandlerResult<unknown>): result is ErrorResult {
+	return result.isError === true;
+}
+
 /**
  * Handler function type
  */

package/src/handlers/validation.test.ts

@@ -116,16 +116,19 @@ describe('getTasksAwaitingValidation', () => {
 		expect(mockApiClient.getTasksAwaitingValidation).toHaveBeenCalledWith(VALID_UUID);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.getTasksAwaitingValidation.mockResolvedValue({
 			ok: false,
 			error: 'Failed to fetch tasks awaiting validation',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			getTasksAwaitingValidation({ project_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Failed to fetch tasks awaiting validation');
+		const result = await getTasksAwaitingValidation({ project_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Failed to fetch tasks awaiting validation',
+		});
 	});
 });
 
@@ -150,52 +153,64 @@ describe('claimValidation', () => {
 		).rejects.toThrow(ValidationError);
 	});
 
-	it('should throw error when task not found', async () => {
+	it('should return error when task not found', async () => {
 		mockApiClient.claimValidation.mockResolvedValue({
 			ok: false,
 			error: 'Task not found',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			claimValidation({ task_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Task not found');
+		const result = await claimValidation({ task_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Task not found',
+		});
 	});
 
-	it('should throw error when task is not completed', async () => {
+	it('should return error when task is not completed', async () => {
 		mockApiClient.claimValidation.mockResolvedValue({
 			ok: false,
 			error: 'Can only claim completed tasks for review',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			claimValidation({ task_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Can only claim completed tasks for review');
+		const result = await claimValidation({ task_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Can only claim completed tasks for review',
+		});
 	});
 
-	it('should throw error when task is already validated', async () => {
+	it('should return error when task is already validated', async () => {
 		mockApiClient.claimValidation.mockResolvedValue({
 			ok: false,
 			error: 'Task has already been validated',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			claimValidation({ task_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Task has already been validated');
+		const result = await claimValidation({ task_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Task has already been validated',
+		});
 	});
 
-	it('should throw error when task is being reviewed by another agent', async () => {
+	it('should return error when task is being reviewed by another agent', async () => {
 		mockApiClient.claimValidation.mockResolvedValue({
 			ok: false,
 			error: 'Task is already being reviewed by another agent',
 		});
 		const ctx = createMockContext({ sessionId: 'session-123' });
 
-		await expect(
-			claimValidation({ task_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Task is already being reviewed by another agent');
+		const result = await claimValidation({ task_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Task is already being reviewed by another agent',
+		});
 	});
 
 	it('should allow same agent to re-claim their own review', async () => {
@@ -268,16 +283,19 @@ describe('claimValidation', () => {
 		);
 	});
 
-	it('should throw error when claim fails', async () => {
+	it('should return error when claim fails', async () => {
 		mockApiClient.claimValidation.mockResolvedValue({
 			ok: false,
 			error: 'Failed to claim task for validation',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			claimValidation({ task_id: VALID_UUID }, ctx)
-		).rejects.toThrow('Failed to claim task for validation');
+		const result = await claimValidation({ task_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Failed to claim task for validation',
+		});
 	});
 });
 
@@ -309,43 +327,52 @@ describe('validateTask', () => {
 
 		await expect(
 			validateTask({ task_id: VALID_UUID }, ctx)
-		).rejects.toThrow('approved is required');
+		).rejects.toThrow(ValidationError);
 	});
 
-	it('should throw error when task not found', async () => {
+	it('should return error when task not found', async () => {
 		mockApiClient.validateTask.mockResolvedValue({
 			ok: false,
 			error: 'Task not found',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			validateTask({ task_id: VALID_UUID, approved: true }, ctx)
-		).rejects.toThrow('Task not found');
+		const result = await validateTask({ task_id: VALID_UUID, approved: true }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Task not found',
+		});
 	});
 
-	it('should throw error when task is not completed', async () => {
+	it('should return error when task is not completed', async () => {
 		mockApiClient.validateTask.mockResolvedValue({
 			ok: false,
 			error: 'Can only validate completed tasks',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			validateTask({ task_id: VALID_UUID, approved: true }, ctx)
-		).rejects.toThrow('Can only validate completed tasks');
+		const result = await validateTask({ task_id: VALID_UUID, approved: true }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Can only validate completed tasks',
+		});
 	});
 
-	it('should throw error when task already validated', async () => {
+	it('should return error when task already validated', async () => {
 		mockApiClient.validateTask.mockResolvedValue({
 			ok: false,
 			error: 'Task has already been validated',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			validateTask({ task_id: VALID_UUID, approved: true }, ctx)
-		).rejects.toThrow('Task has already been validated');
+		const result = await validateTask({ task_id: VALID_UUID, approved: true }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Task has already been validated',
+		});
 	});
 
 	describe('when approved', () => {
@@ -471,28 +498,34 @@ describe('validateTask', () => {
 		});
 	});
 
-	it('should throw error when validation fails on approval', async () => {
+	it('should return error when validation fails on approval', async () => {
 		mockApiClient.validateTask.mockResolvedValue({
 			ok: false,
 			error: 'Failed to validate task',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			validateTask({ task_id: VALID_UUID, approved: true }, ctx)
-		).rejects.toThrow('Failed to validate task');
+		const result = await validateTask({ task_id: VALID_UUID, approved: true }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Failed to validate task',
+		});
 	});
 
-	it('should throw error when validation fails on rejection', async () => {
+	it('should return error when validation fails on rejection', async () => {
 		mockApiClient.validateTask.mockResolvedValue({
 			ok: false,
 			error: 'Failed to validate task',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			validateTask({ task_id: VALID_UUID, approved: false }, ctx)
-		).rejects.toThrow('Failed to validate task');
+		const result = await validateTask({ task_id: VALID_UUID, approved: false }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Failed to validate task',
+		});
 	});
 
 	describe('PR requirement', () => {

package/src/handlers/validation.ts

@@ -8,30 +8,40 @@
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
-import { validateRequired, validateUUID } from '../validators.js';
+import { parseArgs, uuidValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
-export const getTasksAwaitingValidation: Handler = async (args, ctx) => {
-	const { project_id } = args as { project_id: string };
+// Argument schemas for type-safe parsing
+const getTasksAwaitingValidationSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const claimValidationSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
 
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+const validateTaskSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	approved: { type: 'boolean' as const, required: true as const },
+	validation_notes: { type: 'string' as const },
+	skip_pr_check: { type: 'boolean' as const },
+};
+
+export const getTasksAwaitingValidation: Handler = async (args, _ctx) => {
+	const { project_id } = parseArgs(args, getTasksAwaitingValidationSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.getTasksAwaitingValidation(project_id);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to fetch tasks awaiting validation');
+		return { result: { error: response.error || 'Failed to fetch tasks awaiting validation' }, isError: true };
 	}
 
 	return { result: response.data };
 };
 
 export const claimValidation: Handler = async (args, ctx) => {
-	const { task_id } = args as { task_id: string };
-
-	validateRequired(task_id, 'task_id');
-	validateUUID(task_id, 'task_id');
+	const { task_id } = parseArgs(args, claimValidationSchema);
 
 	const { session } = ctx;
 	const currentSessionId = session.currentSessionId;
@@ -40,26 +50,14 @@ export const claimValidation: Handler = async (args, ctx) => {
 	const response = await apiClient.claimValidation(task_id, currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to claim task for validation');
+		return { result: { error: response.error || 'Failed to claim task for validation' }, isError: true };
 	}
 
 	return { result: response.data };
 };
 
 export const validateTask: Handler = async (args, ctx) => {
-	const { task_id, validation_notes, approved, skip_pr_check } = args as {
-		task_id: string;
-		validation_notes?: string;
-		approved: boolean;
-		skip_pr_check?: boolean;
-	};
-
-	validateRequired(task_id, 'task_id');
-	validateUUID(task_id, 'task_id');
-
-	if (approved === undefined) {
-		throw new Error('approved is required');
-	}
+	const { task_id, approved, validation_notes, skip_pr_check } = parseArgs(args, validateTaskSchema);
 
 	const { session } = ctx;
 	const currentSessionId = session.currentSessionId;
@@ -83,7 +81,7 @@ export const validateTask: Handler = async (args, ctx) => {
 				},
 			};
 		}
-		throw new Error(response.error || 'Failed to validate task');
+		return { result: { error: response.error || 'Failed to validate task' }, isError: true };
 	}
 
 	return { result: response.data };