@vibescope/mcp-server 0.5.0 → 0.5.2

package/src/handlers/deployment.ts

@@ -1,570 +1,570 @@
-/**
- * Deployment Handlers
- *
- * Handles deployment coordination and requirements:
- * - request_deployment
- * - claim_deployment_validation
- * - report_validation
- * - check_deployment_status
- * - start_deployment
- * - complete_deployment
- * - cancel_deployment
- * - add_deployment_requirement
- * - complete_deployment_requirement
- * - get_deployment_requirements
- * - get_deployment_requirements_stats
- * - reorder_deployment_requirements
- */
-
-import type { Handler, HandlerRegistry } from './types.js';
-import {
-	ValidationError,
-	parseArgs,
-	uuidValidator,
-	createEnumValidator,
-} from '../validators.js';
-import { getApiClient } from '../api-client.js';
-
-const ENVIRONMENTS = ['development', 'staging', 'production'] as const;
-const VERSION_BUMPS = ['patch', 'minor', 'major'] as const;
-const REQUIREMENT_TYPES = ['migration', 'env_var', 'config', 'manual', 'breaking_change', 'agent_task'] as const;
-const REQUIREMENT_STAGES = ['preparation', 'deployment', 'verification'] as const;
-const REQUIREMENT_STATUSES = ['pending', 'completed', 'converted_to_task', 'all'] as const;
-const SCHEDULE_TYPES = ['once', 'hourly', 'daily', 'weekly', 'monthly'] as const;
-
-type Environment = typeof ENVIRONMENTS[number];
-type VersionBump = typeof VERSION_BUMPS[number];
-type RequirementType = typeof REQUIREMENT_TYPES[number];
-type RequirementStage = typeof REQUIREMENT_STAGES[number];
-type RequirementStatus = typeof REQUIREMENT_STATUSES[number];
-type ScheduleType = typeof SCHEDULE_TYPES[number];
-
-// ============================================================================
-// Argument Schemas
-// ============================================================================
-
-const requestDeploymentSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	environment: { type: 'string' as const, default: 'production', validate: createEnumValidator(ENVIRONMENTS) },
-	version_bump: { type: 'string' as const, default: 'patch', validate: createEnumValidator(VERSION_BUMPS) },
-	notes: { type: 'string' as const },
-	git_ref: { type: 'string' as const },
-};
-
-const claimDeploymentValidationSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-const reportValidationSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	build_passed: { type: 'boolean' as const, required: true as const },
-	tests_passed: { type: 'boolean' as const },
-	error_message: { type: 'string' as const },
-};
-
-const checkDeploymentStatusSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-const startDeploymentSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-const completeDeploymentSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	success: { type: 'boolean' as const, required: true as const },
-	summary: { type: 'string' as const },
-};
-
-const cancelDeploymentSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	reason: { type: 'string' as const },
-};
-
-const addDeploymentRequirementSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	type: { type: 'string' as const, required: true as const, validate: createEnumValidator(REQUIREMENT_TYPES) },
-	title: { type: 'string' as const, required: true as const },
-	description: { type: 'string' as const },
-	file_path: { type: 'string' as const },
-	stage: { type: 'string' as const, default: 'preparation', validate: createEnumValidator(REQUIREMENT_STAGES) },
-	blocking: { type: 'boolean' as const, default: false },
-	recurring: { type: 'boolean' as const, default: true },
-};
-
-const completeDeploymentRequirementSchema = {
-	requirement_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-const getDeploymentRequirementsSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	status: { type: 'string' as const, default: 'pending', validate: createEnumValidator(REQUIREMENT_STATUSES) },
-	stage: { type: 'string' as const, validate: createEnumValidator([...REQUIREMENT_STAGES, 'all'] as const) },
-	limit: { type: 'number' as const, default: 50 },
-	offset: { type: 'number' as const, default: 0 },
-};
-
-const getDeploymentRequirementsStatsSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-const scheduleDeploymentSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	environment: { type: 'string' as const, default: 'production', validate: createEnumValidator(ENVIRONMENTS) },
-	version_bump: { type: 'string' as const, default: 'patch', validate: createEnumValidator(VERSION_BUMPS) },
-	schedule_type: { type: 'string' as const, default: 'once', validate: createEnumValidator(SCHEDULE_TYPES) },
-	scheduled_at: { type: 'string' as const, required: true as const },
-	auto_trigger: { type: 'boolean' as const, default: true },
-	hours_interval: { type: 'number' as const, default: 1 },
-	notes: { type: 'string' as const },
-	git_ref: { type: 'string' as const },
-};
-
-const getScheduledDeploymentsSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	include_disabled: { type: 'boolean' as const, default: false },
-	limit: { type: 'number' as const, default: 50 },
-	offset: { type: 'number' as const, default: 0 },
-};
-
-const updateScheduledDeploymentSchema = {
-	schedule_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	environment: { type: 'string' as const, validate: createEnumValidator(ENVIRONMENTS) },
-	version_bump: { type: 'string' as const, validate: createEnumValidator(VERSION_BUMPS) },
-	schedule_type: { type: 'string' as const, validate: createEnumValidator(SCHEDULE_TYPES) },
-	scheduled_at: { type: 'string' as const },
-	auto_trigger: { type: 'boolean' as const },
-	hours_interval: { type: 'number' as const },
-	enabled: { type: 'boolean' as const },
-	notes: { type: 'string' as const },
-	git_ref: { type: 'string' as const },
-};
-
-const deleteScheduledDeploymentSchema = {
-	schedule_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-const triggerScheduledDeploymentSchema = {
-	schedule_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-const checkDueDeploymentsSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-};
-
-export const requestDeployment: Handler = async (args, ctx) => {
-	const { project_id, environment, version_bump, notes, git_ref } = parseArgs(args, requestDeploymentSchema);
-	const { session } = ctx;
-
-	const apiClient = getApiClient();
-	const response = await apiClient.requestDeployment(project_id, {
-		environment,
-		version_bump,
-		notes,
-		git_ref
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to request deployment' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const claimDeploymentValidation: Handler = async (args, ctx) => {
-	const { project_id } = parseArgs(args, claimDeploymentValidationSchema);
-	const { session } = ctx;
-
-	const apiClient = getApiClient();
-	const response = await apiClient.claimDeploymentValidation(
-		project_id,
-		session.currentSessionId || undefined
-	);
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to claim deployment validation' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const reportValidation: Handler = async (args, ctx) => {
-	const { project_id, build_passed, tests_passed, error_message } = parseArgs(args, reportValidationSchema);
-	const { session } = ctx;
-
-	const apiClient = getApiClient();
-	const response = await apiClient.reportValidation(project_id, {
-		build_passed,
-		tests_passed: tests_passed ?? true,
-		error_message
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to report validation' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const checkDeploymentStatus: Handler = async (args, ctx) => {
-	const { project_id } = parseArgs(args, checkDeploymentStatusSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.checkDeploymentStatus(project_id);
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to check deployment status' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const startDeployment: Handler = async (args, ctx) => {
-	const { project_id } = parseArgs(args, startDeploymentSchema);
-	const { session } = ctx;
-
-	const apiClient = getApiClient();
-	const response = await apiClient.startDeployment(
-		project_id,
-		session.currentSessionId || undefined
-	);
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to start deployment' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const completeDeployment: Handler = async (args, ctx) => {
-	const { project_id, success, summary } = parseArgs(args, completeDeploymentSchema);
-	const { session } = ctx;
-
-	const apiClient = getApiClient();
-	const response = await apiClient.completeDeployment(project_id, {
-		success,
-		summary
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to complete deployment' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const cancelDeployment: Handler = async (args, ctx) => {
-	const { project_id, reason } = parseArgs(args, cancelDeploymentSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.cancelDeployment(project_id, reason);
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to cancel deployment' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const addDeploymentRequirement: Handler = async (args, ctx) => {
-	const { project_id, type, title, description, file_path, stage, blocking, recurring } = parseArgs(args, addDeploymentRequirementSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.addDeploymentRequirement(project_id, {
-		type: type as 'migration' | 'env_var' | 'config' | 'manual' | 'breaking_change' | 'agent_task',
-		title,
-		description,
-		file_path,
-		stage: stage as 'preparation' | 'deployment' | 'verification',
-		blocking,
-		recurring
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to add deployment requirement' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const completeDeploymentRequirement: Handler = async (args, ctx) => {
-	const { requirement_id } = parseArgs(args, completeDeploymentRequirementSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.completeDeploymentRequirement(requirement_id);
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to complete deployment requirement' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const getDeploymentRequirements: Handler = async (args, ctx) => {
-	const { project_id, status, stage, limit, offset } = parseArgs(args, getDeploymentRequirementsSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.getDeploymentRequirements(project_id, {
-		status: status as 'pending' | 'completed' | 'converted_to_task' | 'all',
-		stage: stage as 'preparation' | 'deployment' | 'verification' | 'all' | undefined,
-		limit,
-		offset
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to get deployment requirements' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-/**
- * Get aggregate statistics about deployment requirements for a project.
- * Returns total count and breakdowns by status, stage, and type.
- * More token-efficient than get_deployment_requirements when you just need to understand the overall state.
- */
-export const getDeploymentRequirementsStats: Handler = async (args, ctx) => {
-	const { project_id } = parseArgs(args, getDeploymentRequirementsStatsSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.getDeploymentRequirementsStats(project_id);
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to get deployment requirements stats' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-// ============================================================================
-// Reorder Deployment Requirements
-// ============================================================================
-
-const reorderDeploymentRequirementsSchema = {
-	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
-	stage: { type: 'string' as const, required: true as const, validate: createEnumValidator(REQUIREMENT_STAGES) },
-	requirement_ids: { type: 'object' as const, required: true as const },
-};
-
-export const reorderDeploymentRequirements: Handler = async (args, ctx) => {
-	const { project_id, stage, requirement_ids } = parseArgs(args, reorderDeploymentRequirementsSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.reorderDeploymentRequirements(project_id, {
-		stage,
-		requirement_ids: requirement_ids as unknown as string[],
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to reorder deployment requirements' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-// ============================================================================
-// Scheduled Deployments
-// ============================================================================
-
-export const scheduleDeployment: Handler = async (args, ctx) => {
-	const {
-		project_id,
-		environment,
-		version_bump,
-		schedule_type,
-		scheduled_at,
-		auto_trigger,
-		hours_interval,
-		notes,
-		git_ref,
-	} = parseArgs(args, scheduleDeploymentSchema);
-
-	// Parse and validate scheduled_at
-	const scheduledDate = new Date(scheduled_at);
-	if (isNaN(scheduledDate.getTime())) {
-		throw new ValidationError('Invalid scheduled_at date format', {
-			field: 'scheduled_at',
-			hint: 'Use ISO 8601 format, e.g., 2025-01-15T14:00:00Z',
-		});
-	}
-
-	if (scheduledDate.getTime() <= Date.now()) {
-		throw new ValidationError('scheduled_at must be in the future', {
-			field: 'scheduled_at',
-		});
-	}
-
-	// Validate hours_interval for hourly schedule type (default is 1)
-	const hoursInterval = hours_interval ?? 1;
-	if (schedule_type === 'hourly' && (hoursInterval < 1 || hoursInterval > 24)) {
-		throw new ValidationError('hours_interval must be between 1 and 24', {
-			field: 'hours_interval',
-		});
-	}
-
-	const apiClient = getApiClient();
-	const response = await apiClient.scheduleDeployment(project_id, {
-		environment: environment as 'development' | 'staging' | 'production',
-		version_bump: version_bump as 'patch' | 'minor' | 'major',
-		schedule_type: schedule_type as 'once' | 'hourly' | 'daily' | 'weekly' | 'monthly',
-		scheduled_at: scheduledDate.toISOString(),
-		auto_trigger,
-		hours_interval: hoursInterval,
-		notes,
-		git_ref
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to schedule deployment' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const getScheduledDeployments: Handler = async (args, ctx) => {
-	const { project_id, include_disabled, limit, offset } = parseArgs(args, getScheduledDeploymentsSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.getScheduledDeployments(project_id, {
-		includeDisabled: include_disabled,
-		limit,
-		offset
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to get scheduled deployments' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const updateScheduledDeployment: Handler = async (args, ctx) => {
-	const {
-		schedule_id,
-		environment,
-		version_bump,
-		schedule_type,
-		scheduled_at,
-		auto_trigger,
-		hours_interval,
-		enabled,
-		notes,
-		git_ref,
-	} = parseArgs(args, updateScheduledDeploymentSchema);
-
-	const updates: Record<string, unknown> = {};
-
-	if (environment !== undefined) updates.environment = environment;
-	if (version_bump !== undefined) updates.version_bump = version_bump;
-	if (schedule_type !== undefined) updates.schedule_type = schedule_type;
-
-	if (scheduled_at !== undefined) {
-		const scheduledDate = new Date(scheduled_at);
-		if (isNaN(scheduledDate.getTime())) {
-			throw new ValidationError('Invalid scheduled_at date format');
-		}
-		updates.scheduled_at = scheduledDate.toISOString();
-	}
-
-	if (auto_trigger !== undefined) updates.auto_trigger = auto_trigger;
-	if (hours_interval !== undefined) {
-		if (hours_interval < 1 || hours_interval > 24) {
-			throw new ValidationError('hours_interval must be between 1 and 24');
-		}
-		updates.hours_interval = hours_interval;
-	}
-	if (enabled !== undefined) updates.enabled = enabled;
-	if (notes !== undefined) updates.notes = notes;
-	if (git_ref !== undefined) updates.git_ref = git_ref;
-
-	if (Object.keys(updates).length === 0) {
-		return { result: { success: false, error: 'No updates provided' } };
-	}
-
-	const apiClient = getApiClient();
-	const response = await apiClient.updateScheduledDeployment(schedule_id, updates as {
-		environment?: 'development' | 'staging' | 'production';
-		version_bump?: 'patch' | 'minor' | 'major';
-		schedule_type?: 'once' | 'hourly' | 'daily' | 'weekly' | 'monthly';
-		scheduled_at?: string;
-		auto_trigger?: boolean;
-		hours_interval?: number;
-		enabled?: boolean;
-		notes?: string;
-		git_ref?: string;
-	});
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to update scheduled deployment' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const deleteScheduledDeployment: Handler = async (args, ctx) => {
-	const { schedule_id } = parseArgs(args, deleteScheduledDeploymentSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.deleteScheduledDeployment(schedule_id);
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to delete scheduled deployment' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const triggerScheduledDeployment: Handler = async (args, ctx) => {
-	const { schedule_id } = parseArgs(args, triggerScheduledDeploymentSchema);
-	const { session } = ctx;
-
-	const apiClient = getApiClient();
-	const response = await apiClient.triggerScheduledDeployment(
-		schedule_id,
-		session.currentSessionId || undefined
-	);
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to trigger scheduled deployment' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-export const checkDueDeployments: Handler = async (args, ctx) => {
-	const { project_id } = parseArgs(args, checkDueDeploymentsSchema);
-
-	const apiClient = getApiClient();
-	const response = await apiClient.checkDueDeployments(project_id);
-
-	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to check due deployments' }, isError: true };
-	}
-
-	return { result: response.data };
-};
-
-/**
- * Deployment handlers registry
- */
-export const deploymentHandlers: HandlerRegistry = {
-	request_deployment: requestDeployment,
-	claim_deployment_validation: claimDeploymentValidation,
-	report_validation: reportValidation,
-	check_deployment_status: checkDeploymentStatus,
-	start_deployment: startDeployment,
-	complete_deployment: completeDeployment,
-	cancel_deployment: cancelDeployment,
-	add_deployment_requirement: addDeploymentRequirement,
-	complete_deployment_requirement: completeDeploymentRequirement,
-	get_deployment_requirements: getDeploymentRequirements,
-	get_deployment_requirements_stats: getDeploymentRequirementsStats,
-	reorder_deployment_requirements: reorderDeploymentRequirements,
-	// Scheduled deployments
-	schedule_deployment: scheduleDeployment,
-	get_scheduled_deployments: getScheduledDeployments,
-	update_scheduled_deployment: updateScheduledDeployment,
-	delete_scheduled_deployment: deleteScheduledDeployment,
-	trigger_scheduled_deployment: triggerScheduledDeployment,
-	check_due_deployments: checkDueDeployments,
-};
+/**
+ * Deployment Handlers
+ *
+ * Handles deployment coordination and requirements:
+ * - request_deployment
+ * - claim_deployment_validation
+ * - report_validation
+ * - check_deployment_status
+ * - start_deployment
+ * - complete_deployment
+ * - cancel_deployment
+ * - add_deployment_requirement
+ * - complete_deployment_requirement
+ * - get_deployment_requirements
+ * - get_deployment_requirements_stats
+ * - reorder_deployment_requirements
+ */
+
+import type { Handler, HandlerRegistry } from './types.js';
+import {
+	ValidationError,
+	parseArgs,
+	uuidValidator,
+	createEnumValidator,
+} from '../validators.js';
+import { getApiClient } from '../api-client.js';
+
+const ENVIRONMENTS = ['development', 'staging', 'production'] as const;
+const VERSION_BUMPS = ['patch', 'minor', 'major'] as const;
+const REQUIREMENT_TYPES = ['migration', 'env_var', 'config', 'manual', 'breaking_change', 'agent_task'] as const;
+const REQUIREMENT_STAGES = ['preparation', 'deployment', 'verification'] as const;
+const REQUIREMENT_STATUSES = ['pending', 'completed', 'converted_to_task', 'all'] as const;
+const SCHEDULE_TYPES = ['once', 'hourly', 'daily', 'weekly', 'monthly'] as const;
+
+type Environment = typeof ENVIRONMENTS[number];
+type VersionBump = typeof VERSION_BUMPS[number];
+type RequirementType = typeof REQUIREMENT_TYPES[number];
+type RequirementStage = typeof REQUIREMENT_STAGES[number];
+type RequirementStatus = typeof REQUIREMENT_STATUSES[number];
+type ScheduleType = typeof SCHEDULE_TYPES[number];
+
+// ============================================================================
+// Argument Schemas
+// ============================================================================
+
+const requestDeploymentSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	environment: { type: 'string' as const, default: 'production', validate: createEnumValidator(ENVIRONMENTS) },
+	version_bump: { type: 'string' as const, default: 'patch', validate: createEnumValidator(VERSION_BUMPS) },
+	notes: { type: 'string' as const },
+	git_ref: { type: 'string' as const },
+};
+
+const claimDeploymentValidationSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const reportValidationSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	build_passed: { type: 'boolean' as const, required: true as const },
+	tests_passed: { type: 'boolean' as const },
+	error_message: { type: 'string' as const },
+};
+
+const checkDeploymentStatusSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const startDeploymentSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const completeDeploymentSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	success: { type: 'boolean' as const, required: true as const },
+	summary: { type: 'string' as const },
+};
+
+const cancelDeploymentSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	reason: { type: 'string' as const },
+};
+
+const addDeploymentRequirementSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	type: { type: 'string' as const, required: true as const, validate: createEnumValidator(REQUIREMENT_TYPES) },
+	title: { type: 'string' as const, required: true as const },
+	description: { type: 'string' as const },
+	file_path: { type: 'string' as const },
+	stage: { type: 'string' as const, default: 'preparation', validate: createEnumValidator(REQUIREMENT_STAGES) },
+	blocking: { type: 'boolean' as const, default: false },
+	recurring: { type: 'boolean' as const, default: true },
+};
+
+const completeDeploymentRequirementSchema = {
+	requirement_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const getDeploymentRequirementsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	status: { type: 'string' as const, default: 'pending', validate: createEnumValidator(REQUIREMENT_STATUSES) },
+	stage: { type: 'string' as const, validate: createEnumValidator([...REQUIREMENT_STAGES, 'all'] as const) },
+	limit: { type: 'number' as const, default: 50 },
+	offset: { type: 'number' as const, default: 0 },
+};
+
+const getDeploymentRequirementsStatsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const scheduleDeploymentSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	environment: { type: 'string' as const, default: 'production', validate: createEnumValidator(ENVIRONMENTS) },
+	version_bump: { type: 'string' as const, default: 'patch', validate: createEnumValidator(VERSION_BUMPS) },
+	schedule_type: { type: 'string' as const, default: 'once', validate: createEnumValidator(SCHEDULE_TYPES) },
+	scheduled_at: { type: 'string' as const, required: true as const },
+	auto_trigger: { type: 'boolean' as const, default: true },
+	hours_interval: { type: 'number' as const, default: 1 },
+	notes: { type: 'string' as const },
+	git_ref: { type: 'string' as const },
+};
+
+const getScheduledDeploymentsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	include_disabled: { type: 'boolean' as const, default: false },
+	limit: { type: 'number' as const, default: 50 },
+	offset: { type: 'number' as const, default: 0 },
+};
+
+const updateScheduledDeploymentSchema = {
+	schedule_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	environment: { type: 'string' as const, validate: createEnumValidator(ENVIRONMENTS) },
+	version_bump: { type: 'string' as const, validate: createEnumValidator(VERSION_BUMPS) },
+	schedule_type: { type: 'string' as const, validate: createEnumValidator(SCHEDULE_TYPES) },
+	scheduled_at: { type: 'string' as const },
+	auto_trigger: { type: 'boolean' as const },
+	hours_interval: { type: 'number' as const },
+	enabled: { type: 'boolean' as const },
+	notes: { type: 'string' as const },
+	git_ref: { type: 'string' as const },
+};
+
+const deleteScheduledDeploymentSchema = {
+	schedule_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const triggerScheduledDeploymentSchema = {
+	schedule_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const checkDueDeploymentsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+export const requestDeployment: Handler = async (args, ctx) => {
+	const { project_id, environment, version_bump, notes, git_ref } = parseArgs(args, requestDeploymentSchema);
+	const { session } = ctx;
+
+	const apiClient = getApiClient();
+	const response = await apiClient.requestDeployment(project_id, {
+		environment,
+		version_bump,
+		notes,
+		git_ref
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to request deployment' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const claimDeploymentValidation: Handler = async (args, ctx) => {
+	const { project_id } = parseArgs(args, claimDeploymentValidationSchema);
+	const { session } = ctx;
+
+	const apiClient = getApiClient();
+	const response = await apiClient.claimDeploymentValidation(
+		project_id,
+		session.currentSessionId || undefined
+	);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to claim deployment validation' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const reportValidation: Handler = async (args, ctx) => {
+	const { project_id, build_passed, tests_passed, error_message } = parseArgs(args, reportValidationSchema);
+	const { session } = ctx;
+
+	const apiClient = getApiClient();
+	const response = await apiClient.reportValidation(project_id, {
+		build_passed,
+		tests_passed: tests_passed ?? true,
+		error_message
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to report validation' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const checkDeploymentStatus: Handler = async (args, ctx) => {
+	const { project_id } = parseArgs(args, checkDeploymentStatusSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.checkDeploymentStatus(project_id);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to check deployment status' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const startDeployment: Handler = async (args, ctx) => {
+	const { project_id } = parseArgs(args, startDeploymentSchema);
+	const { session } = ctx;
+
+	const apiClient = getApiClient();
+	const response = await apiClient.startDeployment(
+		project_id,
+		session.currentSessionId || undefined
+	);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to start deployment' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const completeDeployment: Handler = async (args, ctx) => {
+	const { project_id, success, summary } = parseArgs(args, completeDeploymentSchema);
+	const { session } = ctx;
+
+	const apiClient = getApiClient();
+	const response = await apiClient.completeDeployment(project_id, {
+		success,
+		summary
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to complete deployment' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const cancelDeployment: Handler = async (args, ctx) => {
+	const { project_id, reason } = parseArgs(args, cancelDeploymentSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.cancelDeployment(project_id, reason);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to cancel deployment' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const addDeploymentRequirement: Handler = async (args, ctx) => {
+	const { project_id, type, title, description, file_path, stage, blocking, recurring } = parseArgs(args, addDeploymentRequirementSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.addDeploymentRequirement(project_id, {
+		type: type as 'migration' | 'env_var' | 'config' | 'manual' | 'breaking_change' | 'agent_task',
+		title,
+		description,
+		file_path,
+		stage: stage as 'preparation' | 'deployment' | 'verification',
+		blocking,
+		recurring
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to add deployment requirement' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const completeDeploymentRequirement: Handler = async (args, ctx) => {
+	const { requirement_id } = parseArgs(args, completeDeploymentRequirementSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.completeDeploymentRequirement(requirement_id);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to complete deployment requirement' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const getDeploymentRequirements: Handler = async (args, ctx) => {
+	const { project_id, status, stage, limit, offset } = parseArgs(args, getDeploymentRequirementsSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.getDeploymentRequirements(project_id, {
+		status: status as 'pending' | 'completed' | 'converted_to_task' | 'all',
+		stage: stage as 'preparation' | 'deployment' | 'verification' | 'all' | undefined,
+		limit,
+		offset
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to get deployment requirements' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+/**
+ * Get aggregate statistics about deployment requirements for a project.
+ * Returns total count and breakdowns by status, stage, and type.
+ * More token-efficient than get_deployment_requirements when you just need to understand the overall state.
+ */
+export const getDeploymentRequirementsStats: Handler = async (args, ctx) => {
+	const { project_id } = parseArgs(args, getDeploymentRequirementsStatsSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.getDeploymentRequirementsStats(project_id);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to get deployment requirements stats' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+// ============================================================================
+// Reorder Deployment Requirements
+// ============================================================================
+
+const reorderDeploymentRequirementsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	stage: { type: 'string' as const, required: true as const, validate: createEnumValidator(REQUIREMENT_STAGES) },
+	requirement_ids: { type: 'object' as const, required: true as const },
+};
+
+export const reorderDeploymentRequirements: Handler = async (args, ctx) => {
+	const { project_id, stage, requirement_ids } = parseArgs(args, reorderDeploymentRequirementsSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.reorderDeploymentRequirements(project_id, {
+		stage,
+		requirement_ids: requirement_ids as unknown as string[],
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to reorder deployment requirements' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+// ============================================================================
+// Scheduled Deployments
+// ============================================================================
+
+export const scheduleDeployment: Handler = async (args, ctx) => {
+	const {
+		project_id,
+		environment,
+		version_bump,
+		schedule_type,
+		scheduled_at,
+		auto_trigger,
+		hours_interval,
+		notes,
+		git_ref,
+	} = parseArgs(args, scheduleDeploymentSchema);
+
+	// Parse and validate scheduled_at
+	const scheduledDate = new Date(scheduled_at);
+	if (isNaN(scheduledDate.getTime())) {
+		throw new ValidationError('Invalid scheduled_at date format', {
+			field: 'scheduled_at',
+			hint: 'Use ISO 8601 format, e.g., 2025-01-15T14:00:00Z',
+		});
+	}
+
+	if (scheduledDate.getTime() <= Date.now()) {
+		throw new ValidationError('scheduled_at must be in the future', {
+			field: 'scheduled_at',
+		});
+	}
+
+	// Validate hours_interval for hourly schedule type (default is 1)
+	const hoursInterval = hours_interval ?? 1;
+	if (schedule_type === 'hourly' && (hoursInterval < 1 || hoursInterval > 24)) {
+		throw new ValidationError('hours_interval must be between 1 and 24', {
+			field: 'hours_interval',
+		});
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.scheduleDeployment(project_id, {
+		environment: environment as 'development' | 'staging' | 'production',
+		version_bump: version_bump as 'patch' | 'minor' | 'major',
+		schedule_type: schedule_type as 'once' | 'hourly' | 'daily' | 'weekly' | 'monthly',
+		scheduled_at: scheduledDate.toISOString(),
+		auto_trigger,
+		hours_interval: hoursInterval,
+		notes,
+		git_ref
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to schedule deployment' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const getScheduledDeployments: Handler = async (args, ctx) => {
+	const { project_id, include_disabled, limit, offset } = parseArgs(args, getScheduledDeploymentsSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.getScheduledDeployments(project_id, {
+		includeDisabled: include_disabled,
+		limit,
+		offset
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to get scheduled deployments' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const updateScheduledDeployment: Handler = async (args, ctx) => {
+	const {
+		schedule_id,
+		environment,
+		version_bump,
+		schedule_type,
+		scheduled_at,
+		auto_trigger,
+		hours_interval,
+		enabled,
+		notes,
+		git_ref,
+	} = parseArgs(args, updateScheduledDeploymentSchema);
+
+	const updates: Record<string, unknown> = {};
+
+	if (environment !== undefined) updates.environment = environment;
+	if (version_bump !== undefined) updates.version_bump = version_bump;
+	if (schedule_type !== undefined) updates.schedule_type = schedule_type;
+
+	if (scheduled_at !== undefined) {
+		const scheduledDate = new Date(scheduled_at);
+		if (isNaN(scheduledDate.getTime())) {
+			throw new ValidationError('Invalid scheduled_at date format');
+		}
+		updates.scheduled_at = scheduledDate.toISOString();
+	}
+
+	if (auto_trigger !== undefined) updates.auto_trigger = auto_trigger;
+	if (hours_interval !== undefined) {
+		if (hours_interval < 1 || hours_interval > 24) {
+			throw new ValidationError('hours_interval must be between 1 and 24');
+		}
+		updates.hours_interval = hours_interval;
+	}
+	if (enabled !== undefined) updates.enabled = enabled;
+	if (notes !== undefined) updates.notes = notes;
+	if (git_ref !== undefined) updates.git_ref = git_ref;
+
+	if (Object.keys(updates).length === 0) {
+		return { result: { success: false, error: 'No updates provided' } };
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.updateScheduledDeployment(schedule_id, updates as {
+		environment?: 'development' | 'staging' | 'production';
+		version_bump?: 'patch' | 'minor' | 'major';
+		schedule_type?: 'once' | 'hourly' | 'daily' | 'weekly' | 'monthly';
+		scheduled_at?: string;
+		auto_trigger?: boolean;
+		hours_interval?: number;
+		enabled?: boolean;
+		notes?: string;
+		git_ref?: string;
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to update scheduled deployment' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const deleteScheduledDeployment: Handler = async (args, ctx) => {
+	const { schedule_id } = parseArgs(args, deleteScheduledDeploymentSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.deleteScheduledDeployment(schedule_id);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to delete scheduled deployment' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const triggerScheduledDeployment: Handler = async (args, ctx) => {
+	const { schedule_id } = parseArgs(args, triggerScheduledDeploymentSchema);
+	const { session } = ctx;
+
+	const apiClient = getApiClient();
+	const response = await apiClient.triggerScheduledDeployment(
+		schedule_id,
+		session.currentSessionId || undefined
+	);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to trigger scheduled deployment' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+export const checkDueDeployments: Handler = async (args, ctx) => {
+	const { project_id } = parseArgs(args, checkDueDeploymentsSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.checkDueDeployments(project_id);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to check due deployments' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
+/**
+ * Deployment handlers registry
+ */
+export const deploymentHandlers: HandlerRegistry = {
+	request_deployment: requestDeployment,
+	claim_deployment_validation: claimDeploymentValidation,
+	report_validation: reportValidation,
+	check_deployment_status: checkDeploymentStatus,
+	start_deployment: startDeployment,
+	complete_deployment: completeDeployment,
+	cancel_deployment: cancelDeployment,
+	add_deployment_requirement: addDeploymentRequirement,
+	complete_deployment_requirement: completeDeploymentRequirement,
+	get_deployment_requirements: getDeploymentRequirements,
+	get_deployment_requirements_stats: getDeploymentRequirementsStats,
+	reorder_deployment_requirements: reorderDeploymentRequirements,
+	// Scheduled deployments
+	schedule_deployment: scheduleDeployment,
+	get_scheduled_deployments: getScheduledDeployments,
+	update_scheduled_deployment: updateScheduledDeployment,
+	delete_scheduled_deployment: deleteScheduledDeployment,
+	trigger_scheduled_deployment: triggerScheduledDeployment,
+	check_due_deployments: checkDueDeployments,
+};