@vibescope/mcp-server 0.0.1 → 0.2.0

package/src/validators.test.ts

@@ -1,223 +1,223 @@
-import { describe, it, expect } from 'vitest';
-import {
-	ValidationError,
-	validateRequired,
-	validateUUID,
-	validateTaskStatus,
-	validateProjectStatus,
-	validatePriority,
-	validateProgressPercentage,
-	validateEstimatedMinutes,
-	validateEnvironment,
-	VALID_TASK_STATUSES,
-	VALID_PROJECT_STATUSES,
-	VALID_ENVIRONMENTS,
-} from './validators.js';
-
-describe('ValidationError', () => {
-	it('should create error with message', () => {
-		const error = new ValidationError('Test error');
-		expect(error.message).toBe('Test error');
-		expect(error.name).toBe('ValidationError');
-	});
-
-	it('should include optional fields', () => {
-		const error = new ValidationError('Test error', {
-			field: 'test_field',
-			hint: 'Test hint',
-			validValues: ['a', 'b'],
-		});
-		expect(error.field).toBe('test_field');
-		expect(error.hint).toBe('Test hint');
-		expect(error.validValues).toEqual(['a', 'b']);
-	});
-
-	it('should serialize to JSON correctly', () => {
-		const error = new ValidationError('Test error', {
-			field: 'test_field',
-			hint: 'Test hint',
-			validValues: ['a', 'b'],
-		});
-		const json = error.toJSON();
-		expect(json.error).toBe('validation_error');
-		expect(json.message).toBe('Test error');
-		expect(json.field).toBe('test_field');
-		expect(json.hint).toBe('Test hint');
-		expect(json.valid_values).toEqual(['a', 'b']);
-	});
-});
-
-describe('validateRequired', () => {
-	it('should pass for valid values', () => {
-		expect(() => validateRequired('value', 'field')).not.toThrow();
-		expect(() => validateRequired(0, 'field')).not.toThrow();
-		expect(() => validateRequired(false, 'field')).not.toThrow();
-		expect(() => validateRequired({}, 'field')).not.toThrow();
-	});
-
-	it('should throw for undefined', () => {
-		expect(() => validateRequired(undefined, 'test_field')).toThrow(ValidationError);
-		expect(() => validateRequired(undefined, 'test_field')).toThrow('Missing required field: test_field');
-	});
-
-	it('should throw for null', () => {
-		expect(() => validateRequired(null, 'test_field')).toThrow(ValidationError);
-	});
-
-	it('should throw for empty string', () => {
-		expect(() => validateRequired('', 'test_field')).toThrow(ValidationError);
-	});
-});
-
-describe('validateUUID', () => {
-	it('should pass for valid UUIDs', () => {
-		expect(() => validateUUID('123e4567-e89b-12d3-a456-426614174000', 'id')).not.toThrow();
-		expect(() => validateUUID('00000000-0000-0000-0000-000000000000', 'id')).not.toThrow();
-		expect(() => validateUUID('FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF', 'id')).not.toThrow();
-	});
-
-	it('should pass for undefined (optional)', () => {
-		expect(() => validateUUID(undefined, 'id')).not.toThrow();
-	});
-
-	it('should pass for empty string (treated as optional)', () => {
-		expect(() => validateUUID('', 'id')).not.toThrow();
-	});
-
-	it('should throw for invalid UUIDs', () => {
-		expect(() => validateUUID('not-a-uuid', 'id')).toThrow(ValidationError);
-		expect(() => validateUUID('123', 'id')).toThrow(ValidationError);
-		expect(() => validateUUID('123e4567-e89b-12d3-a456', 'id')).toThrow(ValidationError);
-		expect(() => validateUUID('123e4567-e89b-12d3-a456-426614174000-extra', 'id')).toThrow(ValidationError);
-	});
-});
-
-describe('validateTaskStatus', () => {
-	it('should pass for valid task statuses', () => {
-		for (const status of VALID_TASK_STATUSES) {
-			expect(() => validateTaskStatus(status)).not.toThrow();
-		}
-	});
-
-	it('should pass for undefined (optional)', () => {
-		expect(() => validateTaskStatus(undefined)).not.toThrow();
-	});
-
-	it('should throw for invalid status', () => {
-		expect(() => validateTaskStatus('invalid')).toThrow(ValidationError);
-		expect(() => validateTaskStatus('PENDING')).toThrow(ValidationError);
-		expect(() => validateTaskStatus('done')).toThrow(ValidationError);
-	});
-});
-
-describe('validateProjectStatus', () => {
-	it('should pass for valid project statuses', () => {
-		for (const status of VALID_PROJECT_STATUSES) {
-			expect(() => validateProjectStatus(status)).not.toThrow();
-		}
-	});
-
-	it('should pass for undefined (optional)', () => {
-		expect(() => validateProjectStatus(undefined)).not.toThrow();
-	});
-
-	it('should throw for invalid status', () => {
-		expect(() => validateProjectStatus('invalid')).toThrow(ValidationError);
-		expect(() => validateProjectStatus('ACTIVE')).toThrow(ValidationError);
-	});
-});
-
-describe('validatePriority', () => {
-	it('should pass for valid priorities 1-5', () => {
-		for (let i = 1; i <= 5; i++) {
-			expect(() => validatePriority(i)).not.toThrow();
-		}
-	});
-
-	it('should pass for undefined (optional)', () => {
-		expect(() => validatePriority(undefined)).not.toThrow();
-	});
-
-	it('should throw for out of range values', () => {
-		expect(() => validatePriority(0)).toThrow(ValidationError);
-		expect(() => validatePriority(6)).toThrow(ValidationError);
-		expect(() => validatePriority(-1)).toThrow(ValidationError);
-	});
-
-	it('should throw for non-integers', () => {
-		expect(() => validatePriority(1.5)).toThrow(ValidationError);
-		expect(() => validatePriority(2.7)).toThrow(ValidationError);
-	});
-});
-
-describe('validateProgressPercentage', () => {
-	it('should pass for valid percentages 0-100', () => {
-		expect(() => validateProgressPercentage(0)).not.toThrow();
-		expect(() => validateProgressPercentage(50)).not.toThrow();
-		expect(() => validateProgressPercentage(100)).not.toThrow();
-		expect(() => validateProgressPercentage(33.33)).not.toThrow();
-	});
-
-	it('should pass for undefined (optional)', () => {
-		expect(() => validateProgressPercentage(undefined)).not.toThrow();
-	});
-
-	it('should throw for out of range values', () => {
-		expect(() => validateProgressPercentage(-1)).toThrow(ValidationError);
-		expect(() => validateProgressPercentage(101)).toThrow(ValidationError);
-		expect(() => validateProgressPercentage(150)).toThrow(ValidationError);
-	});
-
-	it('should throw for non-finite values', () => {
-		expect(() => validateProgressPercentage(Infinity)).toThrow(ValidationError);
-		expect(() => validateProgressPercentage(NaN)).toThrow(ValidationError);
-	});
-});
-
-describe('validateEstimatedMinutes', () => {
-	it('should pass for valid positive integers', () => {
-		expect(() => validateEstimatedMinutes(1)).not.toThrow();
-		expect(() => validateEstimatedMinutes(30)).not.toThrow();
-		expect(() => validateEstimatedMinutes(120)).not.toThrow();
-	});
-
-	it('should pass for undefined (optional)', () => {
-		expect(() => validateEstimatedMinutes(undefined)).not.toThrow();
-	});
-
-	it('should throw for zero', () => {
-		expect(() => validateEstimatedMinutes(0)).toThrow(ValidationError);
-	});
-
-	it('should throw for negative values', () => {
-		expect(() => validateEstimatedMinutes(-1)).toThrow(ValidationError);
-		expect(() => validateEstimatedMinutes(-30)).toThrow(ValidationError);
-	});
-
-	it('should throw for non-integers', () => {
-		expect(() => validateEstimatedMinutes(1.5)).toThrow(ValidationError);
-		expect(() => validateEstimatedMinutes(30.5)).toThrow(ValidationError);
-	});
-});
-
-describe('validateEnvironment', () => {
-	it('should pass for valid environments', () => {
-		for (const env of VALID_ENVIRONMENTS) {
-			expect(() => validateEnvironment(env)).not.toThrow();
-		}
-	});
-
-	it('should pass for undefined (optional)', () => {
-		expect(() => validateEnvironment(undefined)).not.toThrow();
-	});
-
-	it('should pass for empty string (treated as optional)', () => {
-		expect(() => validateEnvironment('')).not.toThrow();
-	});
-
-	it('should throw for invalid environment', () => {
-		expect(() => validateEnvironment('invalid')).toThrow(ValidationError);
-		expect(() => validateEnvironment('PRODUCTION')).toThrow(ValidationError);
-		expect(() => validateEnvironment('prod')).toThrow(ValidationError);
-	});
-});
+import { describe, it, expect } from 'vitest';
+import {
+	ValidationError,
+	validateRequired,
+	validateUUID,
+	validateTaskStatus,
+	validateProjectStatus,
+	validatePriority,
+	validateProgressPercentage,
+	validateEstimatedMinutes,
+	validateEnvironment,
+	VALID_TASK_STATUSES,
+	VALID_PROJECT_STATUSES,
+	VALID_ENVIRONMENTS,
+} from './validators.js';
+
+describe('ValidationError', () => {
+	it('should create error with message', () => {
+		const error = new ValidationError('Test error');
+		expect(error.message).toBe('Test error');
+		expect(error.name).toBe('ValidationError');
+	});
+
+	it('should include optional fields', () => {
+		const error = new ValidationError('Test error', {
+			field: 'test_field',
+			hint: 'Test hint',
+			validValues: ['a', 'b'],
+		});
+		expect(error.field).toBe('test_field');
+		expect(error.hint).toBe('Test hint');
+		expect(error.validValues).toEqual(['a', 'b']);
+	});
+
+	it('should serialize to JSON correctly', () => {
+		const error = new ValidationError('Test error', {
+			field: 'test_field',
+			hint: 'Test hint',
+			validValues: ['a', 'b'],
+		});
+		const json = error.toJSON();
+		expect(json.error).toBe('validation_error');
+		expect(json.message).toBe('Test error');
+		expect(json.field).toBe('test_field');
+		expect(json.hint).toBe('Test hint');
+		expect(json.valid_values).toEqual(['a', 'b']);
+	});
+});
+
+describe('validateRequired', () => {
+	it('should pass for valid values', () => {
+		expect(() => validateRequired('value', 'field')).not.toThrow();
+		expect(() => validateRequired(0, 'field')).not.toThrow();
+		expect(() => validateRequired(false, 'field')).not.toThrow();
+		expect(() => validateRequired({}, 'field')).not.toThrow();
+	});
+
+	it('should throw for undefined', () => {
+		expect(() => validateRequired(undefined, 'test_field')).toThrow(ValidationError);
+		expect(() => validateRequired(undefined, 'test_field')).toThrow('Missing required field: test_field');
+	});
+
+	it('should throw for null', () => {
+		expect(() => validateRequired(null, 'test_field')).toThrow(ValidationError);
+	});
+
+	it('should throw for empty string', () => {
+		expect(() => validateRequired('', 'test_field')).toThrow(ValidationError);
+	});
+});
+
+describe('validateUUID', () => {
+	it('should pass for valid UUIDs', () => {
+		expect(() => validateUUID('123e4567-e89b-12d3-a456-426614174000', 'id')).not.toThrow();
+		expect(() => validateUUID('00000000-0000-0000-0000-000000000000', 'id')).not.toThrow();
+		expect(() => validateUUID('FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF', 'id')).not.toThrow();
+	});
+
+	it('should pass for undefined (optional)', () => {
+		expect(() => validateUUID(undefined, 'id')).not.toThrow();
+	});
+
+	it('should pass for empty string (treated as optional)', () => {
+		expect(() => validateUUID('', 'id')).not.toThrow();
+	});
+
+	it('should throw for invalid UUIDs', () => {
+		expect(() => validateUUID('not-a-uuid', 'id')).toThrow(ValidationError);
+		expect(() => validateUUID('123', 'id')).toThrow(ValidationError);
+		expect(() => validateUUID('123e4567-e89b-12d3-a456', 'id')).toThrow(ValidationError);
+		expect(() => validateUUID('123e4567-e89b-12d3-a456-426614174000-extra', 'id')).toThrow(ValidationError);
+	});
+});
+
+describe('validateTaskStatus', () => {
+	it('should pass for valid task statuses', () => {
+		for (const status of VALID_TASK_STATUSES) {
+			expect(() => validateTaskStatus(status)).not.toThrow();
+		}
+	});
+
+	it('should pass for undefined (optional)', () => {
+		expect(() => validateTaskStatus(undefined)).not.toThrow();
+	});
+
+	it('should throw for invalid status', () => {
+		expect(() => validateTaskStatus('invalid')).toThrow(ValidationError);
+		expect(() => validateTaskStatus('PENDING')).toThrow(ValidationError);
+		expect(() => validateTaskStatus('done')).toThrow(ValidationError);
+	});
+});
+
+describe('validateProjectStatus', () => {
+	it('should pass for valid project statuses', () => {
+		for (const status of VALID_PROJECT_STATUSES) {
+			expect(() => validateProjectStatus(status)).not.toThrow();
+		}
+	});
+
+	it('should pass for undefined (optional)', () => {
+		expect(() => validateProjectStatus(undefined)).not.toThrow();
+	});
+
+	it('should throw for invalid status', () => {
+		expect(() => validateProjectStatus('invalid')).toThrow(ValidationError);
+		expect(() => validateProjectStatus('ACTIVE')).toThrow(ValidationError);
+	});
+});
+
+describe('validatePriority', () => {
+	it('should pass for valid priorities 1-5', () => {
+		for (let i = 1; i <= 5; i++) {
+			expect(() => validatePriority(i)).not.toThrow();
+		}
+	});
+
+	it('should pass for undefined (optional)', () => {
+		expect(() => validatePriority(undefined)).not.toThrow();
+	});
+
+	it('should throw for out of range values', () => {
+		expect(() => validatePriority(0)).toThrow(ValidationError);
+		expect(() => validatePriority(6)).toThrow(ValidationError);
+		expect(() => validatePriority(-1)).toThrow(ValidationError);
+	});
+
+	it('should throw for non-integers', () => {
+		expect(() => validatePriority(1.5)).toThrow(ValidationError);
+		expect(() => validatePriority(2.7)).toThrow(ValidationError);
+	});
+});
+
+describe('validateProgressPercentage', () => {
+	it('should pass for valid percentages 0-100', () => {
+		expect(() => validateProgressPercentage(0)).not.toThrow();
+		expect(() => validateProgressPercentage(50)).not.toThrow();
+		expect(() => validateProgressPercentage(100)).not.toThrow();
+		expect(() => validateProgressPercentage(33.33)).not.toThrow();
+	});
+
+	it('should pass for undefined (optional)', () => {
+		expect(() => validateProgressPercentage(undefined)).not.toThrow();
+	});
+
+	it('should throw for out of range values', () => {
+		expect(() => validateProgressPercentage(-1)).toThrow(ValidationError);
+		expect(() => validateProgressPercentage(101)).toThrow(ValidationError);
+		expect(() => validateProgressPercentage(150)).toThrow(ValidationError);
+	});
+
+	it('should throw for non-finite values', () => {
+		expect(() => validateProgressPercentage(Infinity)).toThrow(ValidationError);
+		expect(() => validateProgressPercentage(NaN)).toThrow(ValidationError);
+	});
+});
+
+describe('validateEstimatedMinutes', () => {
+	it('should pass for valid positive integers', () => {
+		expect(() => validateEstimatedMinutes(1)).not.toThrow();
+		expect(() => validateEstimatedMinutes(30)).not.toThrow();
+		expect(() => validateEstimatedMinutes(120)).not.toThrow();
+	});
+
+	it('should pass for undefined (optional)', () => {
+		expect(() => validateEstimatedMinutes(undefined)).not.toThrow();
+	});
+
+	it('should throw for zero', () => {
+		expect(() => validateEstimatedMinutes(0)).toThrow(ValidationError);
+	});
+
+	it('should throw for negative values', () => {
+		expect(() => validateEstimatedMinutes(-1)).toThrow(ValidationError);
+		expect(() => validateEstimatedMinutes(-30)).toThrow(ValidationError);
+	});
+
+	it('should throw for non-integers', () => {
+		expect(() => validateEstimatedMinutes(1.5)).toThrow(ValidationError);
+		expect(() => validateEstimatedMinutes(30.5)).toThrow(ValidationError);
+	});
+});
+
+describe('validateEnvironment', () => {
+	it('should pass for valid environments', () => {
+		for (const env of VALID_ENVIRONMENTS) {
+			expect(() => validateEnvironment(env)).not.toThrow();
+		}
+	});
+
+	it('should pass for undefined (optional)', () => {
+		expect(() => validateEnvironment(undefined)).not.toThrow();
+	});
+
+	it('should pass for empty string (treated as optional)', () => {
+		expect(() => validateEnvironment('')).not.toThrow();
+	});
+
+	it('should throw for invalid environment', () => {
+		expect(() => validateEnvironment('invalid')).toThrow(ValidationError);
+		expect(() => validateEnvironment('PRODUCTION')).toThrow(ValidationError);
+		expect(() => validateEnvironment('prod')).toThrow(ValidationError);
+	});
+});

package/src/validators.ts

@@ -120,3 +120,130 @@ export function validateEnvironment(environment: string | undefined): void {
 		});
 	}
 }
+
+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);
+	};
+}

package/tsconfig.json

@@ -12,5 +12,5 @@
     "forceConsistentCasingInFileNames": true
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/__test-*.ts", "src/handlers/checkouts.ts", "src/handlers/knowledge-query.ts", "src/handlers/roles.ts"]
 }

package/vitest.config.ts

@@ -1,13 +1,14 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-	test: {
-		globals: true,
-		environment: 'node',
-		include: ['src/**/*.test.ts'],
-		coverage: {
-			provider: 'v8',
-			reporter: ['text', 'json', 'html'],
-		},
-	},
-});
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+	test: {
+		globals: true,
+		environment: 'node',
+		include: ['src/**/*.test.ts'],
+		setupFiles: ['./src/handlers/__test-setup__.ts'],
+		coverage: {
+			provider: 'v8',
+			reporter: ['text', 'json', 'html'],
+		},
+	},
+});

package/dist/cli.test.d.ts

@@ -1 +0,0 @@
-export {};