@vibescope/mcp-server 0.2.9 → 0.3.1

package/src/handlers/validation.ts

@@ -1,113 +1,164 @@
-/**
- * Validation Handlers (Migrated to API Client)
- *
- * Handles cross-agent task validation:
- * - get_tasks_awaiting_validation
- * - claim_validation
- * - validate_task
- */
-
-import type { Handler, HandlerRegistry } from './types.js';
-import { error, success } from './types.js';
-import { parseArgs, uuidValidator } from '../validators.js';
-import { getApiClient } from '../api-client.js';
-
-// 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 },
-};
-
-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) {
-		return error(response.error || 'Failed to fetch tasks awaiting validation');
-	}
-
-	// Check for application-level errors (200 OK but error in body)
-	if (response.data && typeof response.data === 'object' && 'error' in response.data) {
-		const errMsg = typeof response.data.error === 'string' ? response.data.error : 'Unknown error';
-		return error(errMsg);
-	}
-
-	return success(response.data);
-};
-
-export const claimValidation: Handler = async (args, ctx) => {
-	const { task_id } = parseArgs(args, claimValidationSchema);
-
-	const { session } = ctx;
-	const currentSessionId = session.currentSessionId;
-
-	const apiClient = getApiClient();
-	const response = await apiClient.claimValidation(task_id, currentSessionId || undefined);
-
-	if (!response.ok) {
-		return error(response.error || 'Failed to claim task for validation');
-	}
-
-	// Check for application-level errors (200 OK but error in body)
-	if (response.data && typeof response.data === 'object' && 'error' in response.data) {
-		const errMsg = typeof response.data.error === 'string' ? response.data.error : 'Unknown error';
-		return error(errMsg);
-	}
-
-	return success(response.data);
-};
-
-export const validateTask: Handler = async (args, ctx) => {
-	const { task_id, approved, validation_notes, skip_pr_check } = parseArgs(args, validateTaskSchema);
-
-	const { session } = ctx;
-	const currentSessionId = session.currentSessionId;
-
-	const apiClient = getApiClient();
-	const response = await apiClient.validateTask(task_id, {
-		approved,
-		validation_notes,
-		skip_pr_check,
-	}, currentSessionId || undefined);
-
-	if (!response.ok) {
-		// Handle PR required error specially
-		if (response.error === 'pr_required') {
-			return error('pr_required', {
-				message: response.data?.message || 'A Pull Request is required before validation approval. Create a PR and add it via add_task_reference.',
-				workflow: response.data?.workflow,
-				action_required: 'Create a PR for this task and add it via add_task_reference(task_id, pr_url, label: "Pull Request")',
-			});
-		}
-		return error(response.error || 'Failed to validate task');
-	}
-
-	// Check for application-level errors (200 OK but error in body)
-	if (response.data && typeof response.data === 'object' && 'error' in response.data) {
-		const errMsg = typeof response.data.error === 'string' ? response.data.error : 'Unknown error';
-		return error(errMsg);
-	}
-
-	return success(response.data);
-};
-
-/**
- * Validation handlers registry
- */
-export const validationHandlers: HandlerRegistry = {
-	get_tasks_awaiting_validation: getTasksAwaitingValidation,
-	claim_validation: claimValidation,
-	validate_task: validateTask,
-};
+/**
+ * Validation Handlers (Migrated to API Client)
+ *
+ * Handles cross-agent task validation:
+ * - get_tasks_awaiting_validation
+ * - claim_validation
+ * - validate_task
+ */
+
+import type { Handler, HandlerRegistry } from './types.js';
+import { error, success } from './types.js';
+import { parseArgs, uuidValidator } from '../validators.js';
+import { getApiClient } from '../api-client.js';
+
+// 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 },
+};
+
+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 },
+	// Note: pr_checks_passing may arrive as string from some MCP clients, handled in validateTask
+	pr_checks_passing: { 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) {
+		return error(response.error || 'Failed to fetch tasks awaiting validation');
+	}
+
+	// Check for application-level errors (200 OK but error in body)
+	if (response.data && typeof response.data === 'object' && 'error' in response.data) {
+		const errMsg = typeof response.data.error === 'string' ? response.data.error : 'Unknown error';
+		return error(errMsg);
+	}
+
+	return success(response.data);
+};
+
+export const claimValidation: Handler = async (args, ctx) => {
+	const { task_id } = parseArgs(args, claimValidationSchema);
+
+	const { session } = ctx;
+	const currentSessionId = session.currentSessionId;
+
+	const apiClient = getApiClient();
+	const response = await apiClient.claimValidation(task_id, currentSessionId || undefined);
+
+	if (!response.ok) {
+		return error(response.error || 'Failed to claim task for validation');
+	}
+
+	// Check for application-level errors (200 OK but error in body)
+	if (response.data && typeof response.data === 'object' && 'error' in response.data) {
+		const errMsg = typeof response.data.error === 'string' ? response.data.error : 'Unknown error';
+		return error(errMsg);
+	}
+
+	// Add VALIDATION_WORKFLOW reminder
+	const taskData = response.data as { task?: { git_branch?: string; references?: Array<{ url: string }> } } | null;
+	const gitBranch = taskData?.task?.git_branch;
+	const prUrl = taskData?.task?.references?.find((ref: { url: string }) => ref.url.includes('/pull/'))?.url;
+
+	const result = {
+		...response.data,
+		VALIDATION_WORKFLOW: {
+			message: 'Follow this validation workflow:',
+			steps: [
+				`1. Set up worktree from EXISTING branch (don't create new):`,
+				`   git fetch origin ${gitBranch || 'feature/xxx'}`,
+				`   git worktree add ../PROJECT-PERSONA-validation ${gitBranch || 'feature/xxx'}`,
+				'2. Run: pnpm install && pnpm test && pnpm build',
+				`3. Check PR is still open: gh pr view ${prUrl || '<PR_NUMBER>'} --json state`,
+				'4. If PR closed without merge → cancel_task(cancelled_reason: "pr_closed")',
+				'5. On approve → merge PR immediately → remove worktree',
+				'6. On reject → use validate_task(approved: false) with notes → remove worktree',
+			],
+			fifo_rule: 'IMPORTANT: Review lowest PR number first. Never skip to newer PRs.',
+			worktree_note: 'Use EXISTING branch - do NOT create a new feature branch for validation',
+		},
+	};
+
+	return success(result);
+};
+
+export const validateTask: Handler = async (args, ctx) => {
+	const { task_id, approved, validation_notes, skip_pr_check, pr_checks_passing } = parseArgs(args, validateTaskSchema);
+
+	const { session } = ctx;
+	const currentSessionId = session.currentSessionId;
+
+	// Ensure pr_checks_passing is a proper boolean (MCP may send as string)
+	// Cast to unknown first to satisfy TypeScript
+	const checksPassingBool = pr_checks_passing === true || (pr_checks_passing as unknown) === 'true';
+
+	const apiClient = getApiClient();
+	const response = await apiClient.validateTask(task_id, {
+		approved,
+		validation_notes,
+		skip_pr_check,
+		pr_checks_passing: pr_checks_passing !== undefined ? checksPassingBool : undefined,
+	}, currentSessionId || undefined);
+
+	if (!response.ok) {
+		// Handle PR required error specially
+		if (response.error === 'pr_required') {
+			return error('pr_required', {
+				message: response.data?.message || 'A Pull Request is required before validation approval. Create a PR and add it via add_task_reference.',
+				workflow: response.data?.workflow,
+				action_required: 'Create a PR for this task and add it via add_task_reference(task_id, pr_url, label: "Pull Request")',
+			});
+		}
+		return error(response.error || 'Failed to validate task');
+	}
+
+	// Check for application-level errors (200 OK but error in body)
+	if (response.data && typeof response.data === 'object' && 'error' in response.data) {
+		const errMsg = typeof response.data.error === 'string' ? response.data.error : 'Unknown error';
+		return error(errMsg);
+	}
+
+	// Add REJECTION_GUIDANCE when validation is rejected
+	if (!approved) {
+		const result = {
+			...response.data,
+			REJECTION_GUIDANCE: {
+				message: 'Task validation rejected. A fix task will be created automatically.',
+				what_happens: [
+					'Uses SAME branch (no new branch needed)',
+					'References SAME PR',
+					'Includes your validation notes',
+					'Another agent will pick up the fix task',
+				],
+				your_action: 'Clean up your validation worktree - fix agent creates their own',
+				cleanup_command: 'git worktree remove ../PROJECT-PERSONA-validation',
+				note: 'Your validation notes are passed to the fix task so the agent knows exactly what to fix.',
+			},
+		};
+		return success(result);
+	}
+
+	return success(response.data);
+};
+
+/**
+ * Validation handlers registry
+ */
+export const validationHandlers: HandlerRegistry = {
+	get_tasks_awaiting_validation: getTasksAwaitingValidation,
+	claim_validation: claimValidation,
+	validate_task: validateTask,
+};