@vibescope/mcp-server 0.4.9 → 0.5.1

package/src/validators.ts

@@ -1,249 +1,249 @@
-// ============================================================================
-// Validation Helpers
-// ============================================================================
-
-export const VALID_TASK_STATUSES = ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'] as const;
-export const VALID_PROJECT_STATUSES = ['active', 'paused', 'completed', 'archived'] as const;
-export const VALID_BLOCKER_STATUSES = ['open', 'resolved'] as const;
-export const VALID_DEPLOYMENT_STATUSES = ['pending', 'validating', 'ready', 'deploying', 'deployed', 'failed'] as const;
-export const VALID_ENVIRONMENTS = ['development', 'staging', 'production'] as const;
-
-export type TaskStatus = typeof VALID_TASK_STATUSES[number];
-export type ProjectStatus = typeof VALID_PROJECT_STATUSES[number];
-export type BlockerStatus = typeof VALID_BLOCKER_STATUSES[number];
-export type DeploymentStatus = typeof VALID_DEPLOYMENT_STATUSES[number];
-export type Environment = typeof VALID_ENVIRONMENTS[number];
-
-export class ValidationError extends Error {
-	field?: string;
-	hint?: string;
-	validValues?: readonly string[];
-
-	constructor(message: string, options?: { field?: string; hint?: string; validValues?: readonly string[] }) {
-		super(message);
-		this.name = 'ValidationError';
-		this.field = options?.field;
-		this.hint = options?.hint;
-		this.validValues = options?.validValues;
-	}
-
-	toJSON() {
-		return {
-			error: 'validation_error',
-			message: this.message,
-			field: this.field,
-			hint: this.hint,
-			valid_values: this.validValues,
-		};
-	}
-}
-
-export function validateRequired(value: unknown, fieldName: string): void {
-	if (value === undefined || value === null || value === '') {
-		throw new ValidationError(`Missing required field: ${fieldName}`, {
-			field: fieldName,
-			hint: `Please provide a value for "${fieldName}"`,
-		});
-	}
-}
-
-export function validateUUID(value: string | undefined, fieldName: string): void {
-	if (!value) return;
-	const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-	if (!uuidRegex.test(value)) {
-		throw new ValidationError(`Invalid UUID format for ${fieldName}: "${value}"`, {
-			field: fieldName,
-			hint: 'UUIDs should be in format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
-		});
-	}
-}
-
-export function validateTaskStatus(status: string | undefined): void {
-	if (!status) return;
-	if (!VALID_TASK_STATUSES.includes(status as TaskStatus)) {
-		throw new ValidationError(`Invalid task status: "${status}"`, {
-			field: 'status',
-			validValues: VALID_TASK_STATUSES,
-			hint: `Status must be one of: ${VALID_TASK_STATUSES.join(', ')}`,
-		});
-	}
-}
-
-export function validateProjectStatus(status: string | undefined): void {
-	if (!status) return;
-	if (!VALID_PROJECT_STATUSES.includes(status as ProjectStatus)) {
-		throw new ValidationError(`Invalid project status: "${status}"`, {
-			field: 'status',
-			validValues: VALID_PROJECT_STATUSES,
-			hint: `Status must be one of: ${VALID_PROJECT_STATUSES.join(', ')}`,
-		});
-	}
-}
-
-export function validatePriority(priority: number | undefined): void {
-	if (priority === undefined) return;
-	if (!Number.isInteger(priority) || priority < 1 || priority > 5) {
-		throw new ValidationError(`Invalid priority: ${priority}. Must be an integer between 1 and 5`, {
-			field: 'priority',
-			hint: 'Priority 1 is highest, 5 is lowest',
-		});
-	}
-}
-
-export function validateProgressPercentage(percentage: number | undefined): void {
-	if (percentage === undefined) return;
-	if (!Number.isFinite(percentage) || percentage < 0 || percentage > 100) {
-		throw new ValidationError(`Invalid progress_percentage: ${percentage}. Must be between 0 and 100`, {
-			field: 'progress_percentage',
-			hint: 'Use 0 for not started, 100 for complete',
-		});
-	}
-}
-
-export function validateEstimatedMinutes(minutes: number | undefined): void {
-	if (minutes === undefined) return;
-	if (!Number.isInteger(minutes) || minutes < 1) {
-		throw new ValidationError(`Invalid estimated_minutes: ${minutes}. Must be a positive integer`, {
-			field: 'estimated_minutes',
-			hint: 'Estimate the task duration in minutes (e.g., 30 for half an hour)',
-		});
-	}
-}
-
-export function validateEnvironment(environment: string | undefined): void {
-	if (!environment) return;
-	if (!VALID_ENVIRONMENTS.includes(environment as Environment)) {
-		throw new ValidationError(`Invalid environment: "${environment}"`, {
-			field: 'environment',
-			validValues: VALID_ENVIRONMENTS,
-			hint: `Environment must be one of: ${VALID_ENVIRONMENTS.join(', ')}`,
-		});
-	}
-}
-
-export function validateEnum<T extends readonly string[]>(
-	value: string | undefined,
-	validValues: T,
-	fieldName: string
-): void {
-	if (!value) return;
-	if (!validValues.includes(value)) {
-		throw new ValidationError(`Invalid ${fieldName}: "${value}"`, {
-			field: fieldName,
-			validValues: validValues,
-			hint: `${fieldName} must be one of: ${validValues.join(', ')}`,
-		});
-	}
-}
-
-// ============================================================================
-// Type-Safe Argument Parsing
-// ============================================================================
-
-export type FieldType = 'string' | 'number' | 'boolean' | 'array' | 'object';
-
-export interface FieldSchema {
-	type: FieldType;
-	required?: boolean;
-	validate?: (value: unknown, fieldName: string) => void;
-	default?: unknown;
-}
-
-export type ArgSchema = Record<string, FieldSchema>;
-
-export type InferArgs<T extends ArgSchema> = {
-	[K in keyof T]: T[K]['required'] extends true
-		? T[K]['type'] extends 'string' ? string
-		: T[K]['type'] extends 'number' ? number
-		: T[K]['type'] extends 'boolean' ? boolean
-		: T[K]['type'] extends 'array' ? unknown[]
-		: T[K]['type'] extends 'object' ? Record<string, unknown>
-		: unknown
-		: T[K]['type'] extends 'string' ? string | undefined
-		: T[K]['type'] extends 'number' ? number | undefined
-		: T[K]['type'] extends 'boolean' ? boolean | undefined
-		: T[K]['type'] extends 'array' ? unknown[] | undefined
-		: T[K]['type'] extends 'object' ? Record<string, unknown> | undefined
-		: unknown | undefined;
-};
-
-function checkType(value: unknown, type: FieldType): boolean {
-	if (value === undefined || value === null) return true;
-	switch (type) {
-		case 'string': return typeof value === 'string';
-		case 'number': return typeof value === 'number';
-		case 'boolean': return typeof value === 'boolean';
-		case 'array': return Array.isArray(value);
-		case 'object': return typeof value === 'object' && value !== null && !Array.isArray(value);
-		default: return true;
-	}
-}
-
-export function parseArgs<T extends ArgSchema>(args: Record<string, unknown>, schema: T): InferArgs<T> {
-	const result: Record<string, unknown> = {};
-	for (const [fieldName, fieldSchema] of Object.entries(schema)) {
-		let value = args[fieldName];
-		if (value === undefined && fieldSchema.default !== undefined) {
-			value = fieldSchema.default;
-		}
-		if (fieldSchema.required && (value === undefined || value === null || value === '')) {
-			throw new ValidationError(`Missing required field: ${fieldName}`, {
-				field: fieldName,
-				hint: `Please provide a value for "${fieldName}"`,
-			});
-		}
-		if (value !== undefined && value !== null && !checkType(value, fieldSchema.type)) {
-			throw new ValidationError(`Invalid type for ${fieldName}: expected ${fieldSchema.type}, got ${typeof value}`, {
-				field: fieldName,
-				hint: `The "${fieldName}" field must be a ${fieldSchema.type}`,
-			});
-		}
-		if (fieldSchema.validate && value !== undefined && value !== null) {
-			fieldSchema.validate(value, fieldName);
-		}
-		result[fieldName] = value;
-	}
-	return result as InferArgs<T>;
-}
-
-export function uuidValidator(value: unknown, fieldName: string): void {
-	if (typeof value !== 'string') return;
-	validateUUID(value, fieldName);
-}
-
-export function taskStatusValidator(value: unknown, _fieldName: string): void {
-	if (typeof value !== 'string') return;
-	validateTaskStatus(value);
-}
-
-export function projectStatusValidator(value: unknown, _fieldName: string): void {
-	if (typeof value !== 'string') return;
-	validateProjectStatus(value);
-}
-
-export function priorityValidator(value: unknown, _fieldName: string): void {
-	if (typeof value !== 'number') return;
-	validatePriority(value);
-}
-
-export function progressValidator(value: unknown, _fieldName: string): void {
-	if (typeof value !== 'number') return;
-	validateProgressPercentage(value);
-}
-
-export function minutesValidator(value: unknown, _fieldName: string): void {
-	if (typeof value !== 'number') return;
-	validateEstimatedMinutes(value);
-}
-
-export function environmentValidator(value: unknown, _fieldName: string): void {
-	if (typeof value !== 'string') return;
-	validateEnvironment(value);
-}
-
-export function createEnumValidator<T extends readonly string[]>(validValues: T) {
-	return (value: unknown, fieldName: string): void => {
-		if (typeof value !== 'string') return;
-		validateEnum(value, validValues, fieldName);
-	};
-}
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+
+export const VALID_TASK_STATUSES = ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'] as const;
+export const VALID_PROJECT_STATUSES = ['active', 'paused', 'completed', 'archived'] as const;
+export const VALID_BLOCKER_STATUSES = ['open', 'resolved'] as const;
+export const VALID_DEPLOYMENT_STATUSES = ['pending', 'validating', 'ready', 'deploying', 'deployed', 'failed'] as const;
+export const VALID_ENVIRONMENTS = ['development', 'staging', 'production'] as const;
+
+export type TaskStatus = typeof VALID_TASK_STATUSES[number];
+export type ProjectStatus = typeof VALID_PROJECT_STATUSES[number];
+export type BlockerStatus = typeof VALID_BLOCKER_STATUSES[number];
+export type DeploymentStatus = typeof VALID_DEPLOYMENT_STATUSES[number];
+export type Environment = typeof VALID_ENVIRONMENTS[number];
+
+export class ValidationError extends Error {
+	field?: string;
+	hint?: string;
+	validValues?: readonly string[];
+
+	constructor(message: string, options?: { field?: string; hint?: string; validValues?: readonly string[] }) {
+		super(message);
+		this.name = 'ValidationError';
+		this.field = options?.field;
+		this.hint = options?.hint;
+		this.validValues = options?.validValues;
+	}
+
+	toJSON() {
+		return {
+			error: 'validation_error',
+			message: this.message,
+			field: this.field,
+			hint: this.hint,
+			valid_values: this.validValues,
+		};
+	}
+}
+
+export function validateRequired(value: unknown, fieldName: string): void {
+	if (value === undefined || value === null || value === '') {
+		throw new ValidationError(`Missing required field: ${fieldName}`, {
+			field: fieldName,
+			hint: `Please provide a value for "${fieldName}"`,
+		});
+	}
+}
+
+export function validateUUID(value: string | undefined, fieldName: string): void {
+	if (!value) return;
+	const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+	if (!uuidRegex.test(value)) {
+		throw new ValidationError(`Invalid UUID format for ${fieldName}: "${value}"`, {
+			field: fieldName,
+			hint: 'UUIDs should be in format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+		});
+	}
+}
+
+export function validateTaskStatus(status: string | undefined): void {
+	if (!status) return;
+	if (!VALID_TASK_STATUSES.includes(status as TaskStatus)) {
+		throw new ValidationError(`Invalid task status: "${status}"`, {
+			field: 'status',
+			validValues: VALID_TASK_STATUSES,
+			hint: `Status must be one of: ${VALID_TASK_STATUSES.join(', ')}`,
+		});
+	}
+}
+
+export function validateProjectStatus(status: string | undefined): void {
+	if (!status) return;
+	if (!VALID_PROJECT_STATUSES.includes(status as ProjectStatus)) {
+		throw new ValidationError(`Invalid project status: "${status}"`, {
+			field: 'status',
+			validValues: VALID_PROJECT_STATUSES,
+			hint: `Status must be one of: ${VALID_PROJECT_STATUSES.join(', ')}`,
+		});
+	}
+}
+
+export function validatePriority(priority: number | undefined): void {
+	if (priority === undefined) return;
+	if (!Number.isInteger(priority) || priority < 1 || priority > 5) {
+		throw new ValidationError(`Invalid priority: ${priority}. Must be an integer between 1 and 5`, {
+			field: 'priority',
+			hint: 'Priority 1 is highest, 5 is lowest',
+		});
+	}
+}
+
+export function validateProgressPercentage(percentage: number | undefined): void {
+	if (percentage === undefined) return;
+	if (!Number.isFinite(percentage) || percentage < 0 || percentage > 100) {
+		throw new ValidationError(`Invalid progress_percentage: ${percentage}. Must be between 0 and 100`, {
+			field: 'progress_percentage',
+			hint: 'Use 0 for not started, 100 for complete',
+		});
+	}
+}
+
+export function validateEstimatedMinutes(minutes: number | undefined): void {
+	if (minutes === undefined) return;
+	if (!Number.isInteger(minutes) || minutes < 1) {
+		throw new ValidationError(`Invalid estimated_minutes: ${minutes}. Must be a positive integer`, {
+			field: 'estimated_minutes',
+			hint: 'Estimate the task duration in minutes (e.g., 30 for half an hour)',
+		});
+	}
+}
+
+export function validateEnvironment(environment: string | undefined): void {
+	if (!environment) return;
+	if (!VALID_ENVIRONMENTS.includes(environment as Environment)) {
+		throw new ValidationError(`Invalid environment: "${environment}"`, {
+			field: 'environment',
+			validValues: VALID_ENVIRONMENTS,
+			hint: `Environment must be one of: ${VALID_ENVIRONMENTS.join(', ')}`,
+		});
+	}
+}
+
+export function validateEnum<T extends readonly string[]>(
+	value: string | undefined,
+	validValues: T,
+	fieldName: string
+): void {
+	if (!value) return;
+	if (!validValues.includes(value)) {
+		throw new ValidationError(`Invalid ${fieldName}: "${value}"`, {
+			field: fieldName,
+			validValues: validValues,
+			hint: `${fieldName} must be one of: ${validValues.join(', ')}`,
+		});
+	}
+}
+
+// ============================================================================
+// Type-Safe Argument Parsing
+// ============================================================================
+
+export type FieldType = 'string' | 'number' | 'boolean' | 'array' | 'object';
+
+export interface FieldSchema {
+	type: FieldType;
+	required?: boolean;
+	validate?: (value: unknown, fieldName: string) => void;
+	default?: unknown;
+}
+
+export type ArgSchema = Record<string, FieldSchema>;
+
+export type InferArgs<T extends ArgSchema> = {
+	[K in keyof T]: T[K]['required'] extends true
+		? T[K]['type'] extends 'string' ? string
+		: T[K]['type'] extends 'number' ? number
+		: T[K]['type'] extends 'boolean' ? boolean
+		: T[K]['type'] extends 'array' ? unknown[]
+		: T[K]['type'] extends 'object' ? Record<string, unknown>
+		: unknown
+		: T[K]['type'] extends 'string' ? string | undefined
+		: T[K]['type'] extends 'number' ? number | undefined
+		: T[K]['type'] extends 'boolean' ? boolean | undefined
+		: T[K]['type'] extends 'array' ? unknown[] | undefined
+		: T[K]['type'] extends 'object' ? Record<string, unknown> | undefined
+		: unknown | undefined;
+};
+
+function checkType(value: unknown, type: FieldType): boolean {
+	if (value === undefined || value === null) return true;
+	switch (type) {
+		case 'string': return typeof value === 'string';
+		case 'number': return typeof value === 'number';
+		case 'boolean': return typeof value === 'boolean';
+		case 'array': return Array.isArray(value);
+		case 'object': return typeof value === 'object' && value !== null && !Array.isArray(value);
+		default: return true;
+	}
+}
+
+export function parseArgs<T extends ArgSchema>(args: Record<string, unknown>, schema: T): InferArgs<T> {
+	const result: Record<string, unknown> = {};
+	for (const [fieldName, fieldSchema] of Object.entries(schema)) {
+		let value = args[fieldName];
+		if (value === undefined && fieldSchema.default !== undefined) {
+			value = fieldSchema.default;
+		}
+		if (fieldSchema.required && (value === undefined || value === null || value === '')) {
+			throw new ValidationError(`Missing required field: ${fieldName}`, {
+				field: fieldName,
+				hint: `Please provide a value for "${fieldName}"`,
+			});
+		}
+		if (value !== undefined && value !== null && !checkType(value, fieldSchema.type)) {
+			throw new ValidationError(`Invalid type for ${fieldName}: expected ${fieldSchema.type}, got ${typeof value}`, {
+				field: fieldName,
+				hint: `The "${fieldName}" field must be a ${fieldSchema.type}`,
+			});
+		}
+		if (fieldSchema.validate && value !== undefined && value !== null) {
+			fieldSchema.validate(value, fieldName);
+		}
+		result[fieldName] = value;
+	}
+	return result as InferArgs<T>;
+}
+
+export function uuidValidator(value: unknown, fieldName: string): void {
+	if (typeof value !== 'string') return;
+	validateUUID(value, fieldName);
+}
+
+export function taskStatusValidator(value: unknown, _fieldName: string): void {
+	if (typeof value !== 'string') return;
+	validateTaskStatus(value);
+}
+
+export function projectStatusValidator(value: unknown, _fieldName: string): void {
+	if (typeof value !== 'string') return;
+	validateProjectStatus(value);
+}
+
+export function priorityValidator(value: unknown, _fieldName: string): void {
+	if (typeof value !== 'number') return;
+	validatePriority(value);
+}
+
+export function progressValidator(value: unknown, _fieldName: string): void {
+	if (typeof value !== 'number') return;
+	validateProgressPercentage(value);
+}
+
+export function minutesValidator(value: unknown, _fieldName: string): void {
+	if (typeof value !== 'number') return;
+	validateEstimatedMinutes(value);
+}
+
+export function environmentValidator(value: unknown, _fieldName: string): void {
+	if (typeof value !== 'string') return;
+	validateEnvironment(value);
+}
+
+export function createEnumValidator<T extends readonly string[]>(validValues: T) {
+	return (value: unknown, fieldName: string): void => {
+		if (typeof value !== 'string') return;
+		validateEnum(value, validValues, fieldName);
+	};
+}