@vibescope/mcp-server 0.0.1

package/dist/utils.test.js

@@ -0,0 +1,532 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { AGENT_PERSONAS, FALLBACK_ACTIVITIES, getRandomFallbackActivity, selectPersona, RateLimiter, canValidateTask, isValidStatusTransition, isValidDeploymentStatusTransition, extractProjectNameFromGitUrl, normalizeGitUrl, } from './utils.js';
+// ============================================================================
+// Agent Personas Tests
+// ============================================================================
+describe('AGENT_PERSONAS', () => {
+    it('should have unique personas', () => {
+        expect(AGENT_PERSONAS.length).toBeGreaterThanOrEqual(22);
+        const uniquePersonas = new Set(AGENT_PERSONAS);
+        expect(uniquePersonas.size).toBe(AGENT_PERSONAS.length);
+    });
+    it('should contain expected personas', () => {
+        expect(AGENT_PERSONAS).toContain('Atlas');
+        expect(AGENT_PERSONAS).toContain('Bolt');
+        expect(AGENT_PERSONAS).toContain('Cipher');
+        expect(AGENT_PERSONAS).toContain('Zen');
+    });
+    it('should have short memorable names', () => {
+        // All personas should be reasonably short for dashboard display
+        for (const persona of AGENT_PERSONAS) {
+            expect(persona.length).toBeLessThanOrEqual(6);
+        }
+    });
+});
+// ============================================================================
+// Fallback Activities Tests
+// ============================================================================
+describe('FALLBACK_ACTIVITIES', () => {
+    it('should have 11 activities', () => {
+        expect(FALLBACK_ACTIVITIES).toHaveLength(11);
+    });
+    it('should have required fields on each activity', () => {
+        for (const activity of FALLBACK_ACTIVITIES) {
+            expect(activity).toHaveProperty('activity');
+            expect(activity).toHaveProperty('title');
+            expect(activity).toHaveProperty('description');
+            expect(activity).toHaveProperty('prompt');
+            expect(typeof activity.activity).toBe('string');
+            expect(typeof activity.title).toBe('string');
+            expect(typeof activity.description).toBe('string');
+            expect(typeof activity.prompt).toBe('string');
+        }
+    });
+    it('should have unique activity identifiers', () => {
+        const activityIds = FALLBACK_ACTIVITIES.map((a) => a.activity);
+        const uniqueIds = new Set(activityIds);
+        expect(uniqueIds.size).toBe(FALLBACK_ACTIVITIES.length);
+    });
+    it('should include critical activities', () => {
+        const activityIds = FALLBACK_ACTIVITIES.map((a) => a.activity);
+        expect(activityIds).toContain('feature_ideation');
+        expect(activityIds).toContain('code_review');
+        expect(activityIds).toContain('security_review');
+        expect(activityIds).toContain('test_coverage');
+        expect(activityIds).toContain('validate_completed_tasks');
+    });
+});
+describe('getRandomFallbackActivity', () => {
+    it('should return a valid fallback activity', () => {
+        const activity = getRandomFallbackActivity();
+        expect(activity).toHaveProperty('activity');
+        expect(activity).toHaveProperty('title');
+        expect(activity).toHaveProperty('description');
+        expect(activity).toHaveProperty('prompt');
+    });
+    it('should return activity from the pool', () => {
+        const activity = getRandomFallbackActivity();
+        const activityIds = FALLBACK_ACTIVITIES.map((a) => a.activity);
+        expect(activityIds).toContain(activity.activity);
+    });
+});
+// ============================================================================
+// Persona Selection Tests
+// ============================================================================
+describe('selectPersona', () => {
+    it('should return a random persona when none are in use', () => {
+        const usedPersonas = new Set();
+        const instanceId = 'abc123-def456';
+        const selected = selectPersona(usedPersonas, instanceId);
+        expect(AGENT_PERSONAS).toContain(selected);
+    });
+    it('should skip personas that are in use', () => {
+        const usedPersonas = new Set([AGENT_PERSONAS[0], AGENT_PERSONAS[1]]);
+        const instanceId = 'abc123-def456';
+        const selected = selectPersona(usedPersonas, instanceId);
+        expect(usedPersonas.has(selected)).toBe(false);
+        expect(AGENT_PERSONAS).toContain(selected);
+    });
+    it('should return fallback name when all personas are in use', () => {
+        const usedPersonas = new Set(AGENT_PERSONAS);
+        const instanceId = 'abc123-def456';
+        const selected = selectPersona(usedPersonas, instanceId);
+        expect(selected).toBe('Agent-abc123');
+    });
+    it('should handle partial instance ID', () => {
+        const usedPersonas = new Set(AGENT_PERSONAS);
+        const instanceId = 'xyz';
+        const selected = selectPersona(usedPersonas, instanceId);
+        expect(selected).toBe('Agent-xyz');
+    });
+    it('should be case-sensitive for used personas', () => {
+        const firstPersona = AGENT_PERSONAS[0];
+        const usedPersonas = new Set([firstPersona.toLowerCase(), firstPersona.toUpperCase()]); // Different case
+        const instanceId = 'abc123-def456';
+        const selected = selectPersona(usedPersonas, instanceId);
+        // Original case versions are still available (case-sensitive match)
+        expect(AGENT_PERSONAS).toContain(selected);
+        expect(usedPersonas.has(selected)).toBe(false);
+    });
+});
+// ============================================================================
+// Rate Limiter Tests
+// ============================================================================
+describe('RateLimiter', () => {
+    let rateLimiter;
+    beforeEach(() => {
+        vi.useFakeTimers();
+        rateLimiter = new RateLimiter(5, 1000); // 5 requests per second for testing
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    describe('constructor', () => {
+        it('should use default values when none provided', () => {
+            const defaultLimiter = new RateLimiter();
+            const result = defaultLimiter.check('test');
+            expect(result.remaining).toBe(59); // 60 - 1
+        });
+        it('should use custom values', () => {
+            const customLimiter = new RateLimiter(10, 5000);
+            const result = customLimiter.check('test');
+            expect(result.remaining).toBe(9); // 10 - 1
+            expect(result.resetIn).toBe(5000);
+        });
+    });
+    describe('check', () => {
+        it('should allow first request', () => {
+            const result = rateLimiter.check('user-1');
+            expect(result.allowed).toBe(true);
+            expect(result.remaining).toBe(4);
+            expect(result.resetIn).toBe(1000);
+        });
+        it('should decrement remaining count on subsequent requests', () => {
+            rateLimiter.check('user-1');
+            const result = rateLimiter.check('user-1');
+            expect(result.allowed).toBe(true);
+            expect(result.remaining).toBe(3);
+        });
+        it('should block requests when limit exceeded', () => {
+            // Use up all requests
+            for (let i = 0; i < 5; i++) {
+                rateLimiter.check('user-1');
+            }
+            const result = rateLimiter.check('user-1');
+            expect(result.allowed).toBe(false);
+            expect(result.remaining).toBe(0);
+        });
+        it('should track different keys separately', () => {
+            // Use up user-1's limit
+            for (let i = 0; i < 5; i++) {
+                rateLimiter.check('user-1');
+            }
+            // user-2 should still be allowed
+            const result = rateLimiter.check('user-2');
+            expect(result.allowed).toBe(true);
+            expect(result.remaining).toBe(4);
+        });
+        it('should reset after window expires', () => {
+            // Use up all requests
+            for (let i = 0; i < 5; i++) {
+                rateLimiter.check('user-1');
+            }
+            // Blocked
+            expect(rateLimiter.check('user-1').allowed).toBe(false);
+            // Advance time past window
+            vi.advanceTimersByTime(1001);
+            // Should be allowed again
+            const result = rateLimiter.check('user-1');
+            expect(result.allowed).toBe(true);
+            expect(result.remaining).toBe(4);
+        });
+        it('should report correct resetIn time', () => {
+            rateLimiter.check('user-1');
+            // Advance time by 300ms
+            vi.advanceTimersByTime(300);
+            const result = rateLimiter.check('user-1');
+            expect(result.resetIn).toBeLessThanOrEqual(700);
+            expect(result.resetIn).toBeGreaterThan(0);
+        });
+    });
+    describe('cleanup', () => {
+        it('should remove expired entries', () => {
+            rateLimiter.check('user-1');
+            rateLimiter.check('user-2');
+            expect(rateLimiter.getRequestCount('user-1')).toBe(1);
+            expect(rateLimiter.getRequestCount('user-2')).toBe(1);
+            // Advance past window
+            vi.advanceTimersByTime(1001);
+            rateLimiter.cleanup();
+            expect(rateLimiter.getRequestCount('user-1')).toBeUndefined();
+            expect(rateLimiter.getRequestCount('user-2')).toBeUndefined();
+        });
+        it('should keep non-expired entries', () => {
+            rateLimiter.check('user-1');
+            // Advance but not past window
+            vi.advanceTimersByTime(500);
+            rateLimiter.cleanup();
+            expect(rateLimiter.getRequestCount('user-1')).toBe(1);
+        });
+    });
+    describe('getRequestCount', () => {
+        it('should return undefined for unknown key', () => {
+            expect(rateLimiter.getRequestCount('unknown')).toBeUndefined();
+        });
+        it('should return correct count', () => {
+            rateLimiter.check('user-1');
+            rateLimiter.check('user-1');
+            rateLimiter.check('user-1');
+            expect(rateLimiter.getRequestCount('user-1')).toBe(3);
+        });
+    });
+});
+// ============================================================================
+// Task Validation Tests
+// ============================================================================
+describe('canValidateTask', () => {
+    it('should allow validation of completed tasks', () => {
+        const task = {
+            status: 'completed',
+            validated_at: null,
+            working_agent_session_id: null,
+        };
+        const result = canValidateTask(task, 'session-123');
+        expect(result.canValidate).toBe(true);
+        expect(result.reason).toBeUndefined();
+    });
+    it('should reject non-completed tasks', () => {
+        const statuses = ['pending', 'in_progress', 'cancelled'];
+        for (const status of statuses) {
+            const task = {
+                status,
+                validated_at: null,
+                working_agent_session_id: null,
+            };
+            const result = canValidateTask(task, 'session-123');
+            expect(result.canValidate).toBe(false);
+            expect(result.reason).toBe('Can only validate completed tasks');
+        }
+    });
+    it('should reject already validated tasks', () => {
+        const task = {
+            status: 'completed',
+            validated_at: '2026-01-12T00:00:00Z',
+            working_agent_session_id: null,
+        };
+        const result = canValidateTask(task, 'session-123');
+        expect(result.canValidate).toBe(false);
+        expect(result.reason).toBe('Task has already been validated');
+    });
+    it('should handle null validator session', () => {
+        const task = {
+            status: 'completed',
+            validated_at: null,
+            working_agent_session_id: null,
+        };
+        const result = canValidateTask(task, null);
+        expect(result.canValidate).toBe(true);
+    });
+});
+// ============================================================================
+// Status Transition Tests
+// ============================================================================
+describe('isValidStatusTransition', () => {
+    describe('from pending', () => {
+        it('should allow transition to in_progress', () => {
+            const result = isValidStatusTransition('pending', 'in_progress');
+            expect(result.isValid).toBe(true);
+        });
+        it('should allow transition to cancelled', () => {
+            const result = isValidStatusTransition('pending', 'cancelled');
+            expect(result.isValid).toBe(true);
+        });
+        it('should reject transition to completed', () => {
+            const result = isValidStatusTransition('pending', 'completed');
+            expect(result.isValid).toBe(false);
+            expect(result.reason).toContain('Cannot transition');
+        });
+    });
+    describe('from in_progress', () => {
+        it('should allow transition to completed', () => {
+            const result = isValidStatusTransition('in_progress', 'completed');
+            expect(result.isValid).toBe(true);
+        });
+        it('should allow transition to pending', () => {
+            const result = isValidStatusTransition('in_progress', 'pending');
+            expect(result.isValid).toBe(true);
+        });
+        it('should allow transition to cancelled', () => {
+            const result = isValidStatusTransition('in_progress', 'cancelled');
+            expect(result.isValid).toBe(true);
+        });
+    });
+    describe('from completed', () => {
+        it('should allow transition to in_progress (validation failure)', () => {
+            const result = isValidStatusTransition('completed', 'in_progress');
+            expect(result.isValid).toBe(true);
+        });
+        it('should reject transition to pending', () => {
+            const result = isValidStatusTransition('completed', 'pending');
+            expect(result.isValid).toBe(false);
+        });
+        it('should reject transition to cancelled', () => {
+            const result = isValidStatusTransition('completed', 'cancelled');
+            expect(result.isValid).toBe(false);
+        });
+    });
+    describe('from cancelled', () => {
+        it('should allow transition to pending (reactivate)', () => {
+            const result = isValidStatusTransition('cancelled', 'pending');
+            expect(result.isValid).toBe(true);
+        });
+        it('should reject transition to in_progress', () => {
+            const result = isValidStatusTransition('cancelled', 'in_progress');
+            expect(result.isValid).toBe(false);
+        });
+        it('should reject transition to completed', () => {
+            const result = isValidStatusTransition('cancelled', 'completed');
+            expect(result.isValid).toBe(false);
+        });
+    });
+    describe('unknown status', () => {
+        it('should reject unknown current status', () => {
+            const result = isValidStatusTransition('unknown', 'pending');
+            expect(result.isValid).toBe(false);
+            expect(result.reason).toContain('Unknown current status');
+        });
+    });
+});
+// ============================================================================
+// Deployment Status Transition Tests
+// ============================================================================
+describe('isValidDeploymentStatusTransition', () => {
+    describe('from pending', () => {
+        it('should allow pending → validating', () => {
+            const result = isValidDeploymentStatusTransition('pending', 'validating');
+            expect(result.isValid).toBe(true);
+        });
+        it('should allow pending → failed', () => {
+            const result = isValidDeploymentStatusTransition('pending', 'failed');
+            expect(result.isValid).toBe(true);
+        });
+        it('should reject pending → ready', () => {
+            const result = isValidDeploymentStatusTransition('pending', 'ready');
+            expect(result.isValid).toBe(false);
+        });
+        it('should reject pending → deployed', () => {
+            const result = isValidDeploymentStatusTransition('pending', 'deployed');
+            expect(result.isValid).toBe(false);
+        });
+    });
+    describe('from validating', () => {
+        it('should allow validating → ready', () => {
+            const result = isValidDeploymentStatusTransition('validating', 'ready');
+            expect(result.isValid).toBe(true);
+        });
+        it('should allow validating → failed', () => {
+            const result = isValidDeploymentStatusTransition('validating', 'failed');
+            expect(result.isValid).toBe(true);
+        });
+        it('should reject validating → deployed', () => {
+            const result = isValidDeploymentStatusTransition('validating', 'deployed');
+            expect(result.isValid).toBe(false);
+        });
+    });
+    describe('from ready', () => {
+        it('should allow ready → deploying', () => {
+            const result = isValidDeploymentStatusTransition('ready', 'deploying');
+            expect(result.isValid).toBe(true);
+        });
+        it('should allow ready → failed', () => {
+            const result = isValidDeploymentStatusTransition('ready', 'failed');
+            expect(result.isValid).toBe(true);
+        });
+        it('should reject ready → pending', () => {
+            const result = isValidDeploymentStatusTransition('ready', 'pending');
+            expect(result.isValid).toBe(false);
+        });
+    });
+    describe('from deploying', () => {
+        it('should allow deploying → deployed', () => {
+            const result = isValidDeploymentStatusTransition('deploying', 'deployed');
+            expect(result.isValid).toBe(true);
+        });
+        it('should allow deploying → failed', () => {
+            const result = isValidDeploymentStatusTransition('deploying', 'failed');
+            expect(result.isValid).toBe(true);
+        });
+        it('should reject deploying → pending', () => {
+            const result = isValidDeploymentStatusTransition('deploying', 'pending');
+            expect(result.isValid).toBe(false);
+        });
+    });
+    describe('terminal states', () => {
+        it('should reject deployed → any transition', () => {
+            const result = isValidDeploymentStatusTransition('deployed', 'pending');
+            expect(result.isValid).toBe(false);
+            expect(result.reason).toContain('terminal state');
+        });
+        it('should reject failed → any transition', () => {
+            const result = isValidDeploymentStatusTransition('failed', 'pending');
+            expect(result.isValid).toBe(false);
+            expect(result.reason).toContain('terminal state');
+        });
+    });
+    describe('unknown status', () => {
+        it('should reject unknown current status', () => {
+            const result = isValidDeploymentStatusTransition('unknown', 'pending');
+            expect(result.isValid).toBe(false);
+            expect(result.reason).toContain('Unknown current status');
+        });
+    });
+});
+// ============================================================================
+// Git URL Parsing Tests
+// ============================================================================
+describe('extractProjectNameFromGitUrl', () => {
+    it('should extract project name from https GitHub URL', () => {
+        expect(extractProjectNameFromGitUrl('https://github.com/user/repo')).toBe('repo');
+    });
+    it('should extract project name from https GitHub URL with .git', () => {
+        expect(extractProjectNameFromGitUrl('https://github.com/user/repo.git')).toBe('repo');
+    });
+    it('should extract project name from SSH GitHub URL', () => {
+        expect(extractProjectNameFromGitUrl('git@github.com:user/repo.git')).toBe('repo');
+    });
+    it('should extract project name from SSH URL without .git', () => {
+        expect(extractProjectNameFromGitUrl('git@github.com:user/repo')).toBe('repo');
+    });
+    it('should extract project name from GitLab URL', () => {
+        expect(extractProjectNameFromGitUrl('https://gitlab.com/user/project-name')).toBe('project-name');
+    });
+    it('should extract project name from ssh:// protocol URL', () => {
+        expect(extractProjectNameFromGitUrl('ssh://git@github.com/user/repo.git')).toBe('repo');
+    });
+    it('should handle nested paths (monorepo)', () => {
+        expect(extractProjectNameFromGitUrl('https://github.com/org/monorepo')).toBe('monorepo');
+    });
+    it('should handle dashes and underscores in project names', () => {
+        expect(extractProjectNameFromGitUrl('https://github.com/user/my-awesome_project')).toBe('my-awesome_project');
+    });
+    it('should return default for empty string', () => {
+        expect(extractProjectNameFromGitUrl('')).toBe('my-project');
+    });
+    it('should return default for malformed URL', () => {
+        expect(extractProjectNameFromGitUrl('not-a-url')).toBe('my-project');
+    });
+    it('should handle real Vibescope URL', () => {
+        expect(extractProjectNameFromGitUrl('https://github.com/Nonatomic/Vibescope')).toBe('Vibescope');
+    });
+});
+// ============================================================================
+// normalizeGitUrl Tests
+// ============================================================================
+describe('normalizeGitUrl', () => {
+    describe('removing .git suffix', () => {
+        it('should remove .git suffix from HTTPS URL', () => {
+            expect(normalizeGitUrl('https://github.com/user/repo.git')).toBe('https://github.com/user/repo');
+        });
+        it('should not affect URL without .git suffix', () => {
+            expect(normalizeGitUrl('https://github.com/user/repo')).toBe('https://github.com/user/repo');
+        });
+        it('should only remove .git at the end', () => {
+            expect(normalizeGitUrl('https://github.com/user/dotgit')).toBe('https://github.com/user/dotgit');
+        });
+    });
+    describe('converting SSH to HTTPS for GitHub', () => {
+        it('should convert SSH URL with .git', () => {
+            expect(normalizeGitUrl('git@github.com:user/repo.git')).toBe('https://github.com/user/repo');
+        });
+        it('should convert SSH URL without .git', () => {
+            expect(normalizeGitUrl('git@github.com:user/repo')).toBe('https://github.com/user/repo');
+        });
+        it('should convert SSH URL with org path', () => {
+            expect(normalizeGitUrl('git@github.com:Nonatomic/Vibescope.git')).toBe('https://github.com/Nonatomic/Vibescope');
+        });
+    });
+    describe('converting SSH to HTTPS for GitLab', () => {
+        it('should convert SSH URL with .git', () => {
+            expect(normalizeGitUrl('git@gitlab.com:user/repo.git')).toBe('https://gitlab.com/user/repo');
+        });
+        it('should convert SSH URL without .git', () => {
+            expect(normalizeGitUrl('git@gitlab.com:user/repo')).toBe('https://gitlab.com/user/repo');
+        });
+    });
+    describe('converting SSH to HTTPS for Bitbucket', () => {
+        it('should convert SSH URL with .git', () => {
+            expect(normalizeGitUrl('git@bitbucket.org:user/repo.git')).toBe('https://bitbucket.org/user/repo');
+        });
+        it('should convert SSH URL without .git', () => {
+            expect(normalizeGitUrl('git@bitbucket.org:user/repo')).toBe('https://bitbucket.org/user/repo');
+        });
+    });
+    describe('passthrough behavior', () => {
+        it('should pass through already-normalized HTTPS GitHub URL', () => {
+            expect(normalizeGitUrl('https://github.com/user/repo')).toBe('https://github.com/user/repo');
+        });
+        it('should pass through HTTPS GitLab URL', () => {
+            expect(normalizeGitUrl('https://gitlab.com/user/repo')).toBe('https://gitlab.com/user/repo');
+        });
+        it('should pass through HTTPS Bitbucket URL', () => {
+            expect(normalizeGitUrl('https://bitbucket.org/user/repo')).toBe('https://bitbucket.org/user/repo');
+        });
+        it('should pass through empty string', () => {
+            expect(normalizeGitUrl('')).toBe('');
+        });
+        it('should pass through unsupported git hosts', () => {
+            expect(normalizeGitUrl('git@selfhosted.example.com:user/repo.git')).toBe('git@selfhosted.example.com:user/repo');
+        });
+    });
+    describe('edge cases', () => {
+        it('should handle complex paths with dashes and underscores', () => {
+            expect(normalizeGitUrl('git@github.com:my-org/my_awesome-project.git')).toBe('https://github.com/my-org/my_awesome-project');
+        });
+        it('should handle nested paths', () => {
+            expect(normalizeGitUrl('https://gitlab.com/group/subgroup/repo.git')).toBe('https://gitlab.com/group/subgroup/repo');
+        });
+        it('should handle URLs with port numbers', () => {
+            // Port in URL - should just remove .git
+            expect(normalizeGitUrl('https://github.com:443/user/repo.git')).toBe('https://github.com:443/user/repo');
+        });
+    });
+});

package/dist/validators.d.ts

@@ -0,0 +1,35 @@
+export declare const VALID_TASK_STATUSES: readonly ["backlog", "pending", "in_progress", "completed", "cancelled"];
+export declare const VALID_PROJECT_STATUSES: readonly ["active", "paused", "completed", "archived"];
+export declare const VALID_BLOCKER_STATUSES: readonly ["open", "resolved"];
+export declare const VALID_DEPLOYMENT_STATUSES: readonly ["pending", "validating", "ready", "deploying", "deployed", "failed"];
+export declare const VALID_ENVIRONMENTS: readonly ["development", "staging", "production"];
+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 declare class ValidationError extends Error {
+    field?: string;
+    hint?: string;
+    validValues?: readonly string[];
+    constructor(message: string, options?: {
+        field?: string;
+        hint?: string;
+        validValues?: readonly string[];
+    });
+    toJSON(): {
+        error: string;
+        message: string;
+        field: string | undefined;
+        hint: string | undefined;
+        valid_values: readonly string[] | undefined;
+    };
+}
+export declare function validateRequired(value: unknown, fieldName: string): void;
+export declare function validateUUID(value: string | undefined, fieldName: string): void;
+export declare function validateTaskStatus(status: string | undefined): void;
+export declare function validateProjectStatus(status: string | undefined): void;
+export declare function validatePriority(priority: number | undefined): void;
+export declare function validateProgressPercentage(percentage: number | undefined): void;
+export declare function validateEstimatedMinutes(minutes: number | undefined): void;
+export declare function validateEnvironment(environment: string | undefined): void;

package/dist/validators.js

@@ -0,0 +1,111 @@
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+export const VALID_TASK_STATUSES = ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'];
+export const VALID_PROJECT_STATUSES = ['active', 'paused', 'completed', 'archived'];
+export const VALID_BLOCKER_STATUSES = ['open', 'resolved'];
+export const VALID_DEPLOYMENT_STATUSES = ['pending', 'validating', 'ready', 'deploying', 'deployed', 'failed'];
+export const VALID_ENVIRONMENTS = ['development', 'staging', 'production'];
+export class ValidationError extends Error {
+    field;
+    hint;
+    validValues;
+    constructor(message, options) {
+        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, fieldName) {
+    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, fieldName) {
+    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) {
+    if (!status)
+        return;
+    if (!VALID_TASK_STATUSES.includes(status)) {
+        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) {
+    if (!status)
+        return;
+    if (!VALID_PROJECT_STATUSES.includes(status)) {
+        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) {
+    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) {
+    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) {
+    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) {
+    if (!environment)
+        return;
+    if (!VALID_ENVIRONMENTS.includes(environment)) {
+        throw new ValidationError(`Invalid environment: "${environment}"`, {
+            field: 'environment',
+            validValues: VALID_ENVIRONMENTS,
+            hint: `Environment must be one of: ${VALID_ENVIRONMENTS.join(', ')}`,
+        });
+    }
+}