@vibescope/mcp-server 0.5.0 → 0.5.2

package/src/utils.test.ts

@@ -1,1014 +1,1014 @@
-import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
-import {
-	AGENT_PERSONAS,
-	FALLBACK_ACTIVITIES,
-	getRandomFallbackActivity,
-	selectPersona,
-	RateLimiter,
-	canValidateTask,
-	isValidStatusTransition,
-	isValidDeploymentStatusTransition,
-	extractProjectNameFromGitUrl,
-	normalizeGitUrl,
-	getErrorMessage,
-	hasErrorProperty,
-	extractApiError,
-	capPagination,
-	PAGINATION_LIMITS,
-} 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', () => {
-		// Sci-fi & fantasy character names
-		expect(AGENT_PERSONAS).toContain('Yoda');
-		expect(AGENT_PERSONAS).toContain('Gandalf');
-		expect(AGENT_PERSONAS).toContain('Spock');
-		expect(AGENT_PERSONAS).toContain('Neo');
-	});
-
-	it('should have short memorable names', () => {
-		// All personas should be reasonably short for dashboard display
-		// Max 8 chars to accommodate names like "Morpheus"
-		for (const persona of AGENT_PERSONAS) {
-			expect(persona.length).toBeLessThanOrEqual(8);
-		}
-	});
-});
-
-// ============================================================================
-// Fallback Activities Tests
-// ============================================================================
-
-describe('FALLBACK_ACTIVITIES', () => {
-	it('should have 12 activities', () => {
-		expect(FALLBACK_ACTIVITIES).toHaveLength(12);
-	});
-
-	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<string>();
-		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<string>([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: 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('null and undefined handling', () => {
-		it('returns null for null input', () => {
-			expect(normalizeGitUrl(null)).toBe(null);
-		});
-
-		it('returns null for undefined input', () => {
-			expect(normalizeGitUrl(undefined)).toBe(null);
-		});
-
-		it('returns null for empty string', () => {
-			expect(normalizeGitUrl('')).toBe(null);
-		});
-
-		it('returns null for whitespace-only string', () => {
-			expect(normalizeGitUrl('   ')).toBe(null);
-		});
-	});
-
-	describe('SSH format conversion', () => {
-		it('converts SSH format to HTTPS', () => {
-			expect(normalizeGitUrl('git@github.com:owner/repo')).toBe('https://github.com/owner/repo');
-		});
-
-		it('converts SSH format with .git suffix', () => {
-			expect(normalizeGitUrl('git@github.com:owner/repo.git')).toBe('https://github.com/owner/repo');
-		});
-
-		it('converts GitLab SSH format', () => {
-			expect(normalizeGitUrl('git@gitlab.com:group/project')).toBe('https://gitlab.com/group/project');
-		});
-
-		it('converts Bitbucket SSH format', () => {
-			expect(normalizeGitUrl('git@bitbucket.org:team/repo')).toBe('https://bitbucket.org/team/repo');
-		});
-
-		it('handles SSH format with nested paths', () => {
-			expect(normalizeGitUrl('git@github.com:org/group/repo')).toBe('https://github.com/org/group/repo');
-		});
-
-		it('converts self-hosted git SSH format', () => {
-			expect(normalizeGitUrl('git@selfhosted.example.com:user/repo.git')).toBe('https://selfhosted.example.com/user/repo');
-		});
-	});
-
-	describe('.git suffix removal', () => {
-		it('removes .git suffix from HTTPS URL', () => {
-			expect(normalizeGitUrl('https://github.com/owner/repo.git')).toBe('https://github.com/owner/repo');
-		});
-
-		it('handles URL without .git suffix', () => {
-			expect(normalizeGitUrl('https://github.com/owner/repo')).toBe('https://github.com/owner/repo');
-		});
-
-		it('does not remove .git from middle of URL', () => {
-			expect(normalizeGitUrl('https://github.com/owner/repo.github.io')).toBe('https://github.com/owner/repo.github.io');
-		});
-	});
-
-	describe('trailing slash removal', () => {
-		it('removes single trailing slash', () => {
-			expect(normalizeGitUrl('https://github.com/owner/repo/')).toBe('https://github.com/owner/repo');
-		});
-
-		it('removes multiple trailing slashes', () => {
-			expect(normalizeGitUrl('https://github.com/owner/repo///')).toBe('https://github.com/owner/repo');
-		});
-
-		it('handles URL without trailing slash', () => {
-			expect(normalizeGitUrl('https://github.com/owner/repo')).toBe('https://github.com/owner/repo');
-		});
-	});
-
-	describe('case normalization', () => {
-		it('lowercases the entire URL', () => {
-			expect(normalizeGitUrl('https://GitHub.com/Owner/Repo')).toBe('https://github.com/owner/repo');
-		});
-
-		it('lowercases mixed case URLs', () => {
-			expect(normalizeGitUrl('https://GITHUB.COM/NONATOMIC/VIBESCOPE')).toBe('https://github.com/nonatomic/vibescope');
-		});
-
-		it('lowercases SSH format before conversion', () => {
-			expect(normalizeGitUrl('git@GitHub.com:Owner/Repo')).toBe('https://github.com/owner/repo');
-		});
-	});
-
-	describe('protocol handling', () => {
-		it('upgrades http to https', () => {
-			expect(normalizeGitUrl('http://github.com/owner/repo')).toBe('https://github.com/owner/repo');
-		});
-
-		it('preserves existing https protocol', () => {
-			expect(normalizeGitUrl('https://github.com/owner/repo')).toBe('https://github.com/owner/repo');
-		});
-
-		it('adds https protocol to bare domain URLs', () => {
-			expect(normalizeGitUrl('github.com/owner/repo')).toBe('https://github.com/owner/repo');
-		});
-	});
-
-	describe('whitespace handling', () => {
-		it('trims leading whitespace', () => {
-			expect(normalizeGitUrl('   https://github.com/owner/repo')).toBe('https://github.com/owner/repo');
-		});
-
-		it('trims trailing whitespace', () => {
-			expect(normalizeGitUrl('https://github.com/owner/repo   ')).toBe('https://github.com/owner/repo');
-		});
-
-		it('trims both leading and trailing whitespace', () => {
-			expect(normalizeGitUrl('  https://github.com/owner/repo  ')).toBe('https://github.com/owner/repo');
-		});
-	});
-
-	describe('combined transformations', () => {
-		it('handles SSH with .git, different casing', () => {
-			expect(normalizeGitUrl('git@GitHub.com:Nonatomic/Vibescope.git')).toBe('https://github.com/nonatomic/vibescope');
-		});
-
-		it('handles HTTPS with trailing slash, .git suffix, and casing', () => {
-			expect(normalizeGitUrl('https://GitHub.com/Nonatomic/Vibescope.git/')).toBe('https://github.com/nonatomic/vibescope');
-		});
-
-		it('handles http with trailing slashes and casing', () => {
-			expect(normalizeGitUrl('http://GitHub.com/Owner/Repo//')).toBe('https://github.com/owner/repo');
-		});
-
-		it('handles bare domain with .git and trailing slash', () => {
-			expect(normalizeGitUrl('github.com/owner/repo.git/')).toBe('https://github.com/owner/repo');
-		});
-	});
-
-	describe('real-world examples', () => {
-		it('normalizes Vibescope registered URL', () => {
-			expect(normalizeGitUrl('https://github.com/Nonatomic/Vibescope')).toBe('https://github.com/nonatomic/vibescope');
-		});
-
-		it('normalizes Vibescope with .git suffix', () => {
-			expect(normalizeGitUrl('https://github.com/Nonatomic/Vibescope.git')).toBe('https://github.com/nonatomic/vibescope');
-		});
-
-		it('normalizes Vibescope SSH format', () => {
-			expect(normalizeGitUrl('git@github.com:Nonatomic/Vibescope.git')).toBe('https://github.com/nonatomic/vibescope');
-		});
-
-		it('normalizes Vibescope with different casing', () => {
-			expect(normalizeGitUrl('https://github.com/nonatomic/vibescope')).toBe('https://github.com/nonatomic/vibescope');
-		});
-
-		it('normalizes Vibescope with trailing slash', () => {
-			expect(normalizeGitUrl('https://github.com/Nonatomic/Vibescope/')).toBe('https://github.com/nonatomic/vibescope');
-		});
-
-		it('all Vibescope variants normalize to same value', () => {
-			const canonical = 'https://github.com/nonatomic/vibescope';
-
-			const variants = [
-				'https://github.com/Nonatomic/Vibescope',
-				'https://github.com/Nonatomic/Vibescope.git',
-				'git@github.com:Nonatomic/Vibescope.git',
-				'https://github.com/nonatomic/vibescope',
-				'https://github.com/Nonatomic/Vibescope/',
-				'https://GITHUB.COM/NONATOMIC/VIBESCOPE',
-				'http://github.com/Nonatomic/Vibescope',
-				'github.com/Nonatomic/Vibescope',
-			];
-
-			for (const variant of variants) {
-				expect(normalizeGitUrl(variant)).toBe(canonical);
-			}
-		});
-	});
-
-	describe('edge cases', () => {
-		it('handles 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('handles nested paths', () => {
-			expect(normalizeGitUrl('https://gitlab.com/group/subgroup/repo.git')).toBe('https://gitlab.com/group/subgroup/repo');
-		});
-
-		it('handles URLs with port numbers', () => {
-			expect(normalizeGitUrl('https://github.com:443/user/repo.git')).toBe('https://github.com:443/user/repo');
-		});
-	});
-});
-
-// ============================================================================
-// Error Handling Utilities Tests
-// ============================================================================
-
-describe('getErrorMessage', () => {
-	it('extracts message from Error object', () => {
-		const error = new Error('Something went wrong');
-		expect(getErrorMessage(error)).toBe('Something went wrong');
-	});
-
-	it('extracts message from TypeError', () => {
-		const error = new TypeError('Invalid type');
-		expect(getErrorMessage(error)).toBe('Invalid type');
-	});
-
-	it('returns string errors as-is', () => {
-		expect(getErrorMessage('Direct error string')).toBe('Direct error string');
-	});
-
-	it('converts numbers to string', () => {
-		expect(getErrorMessage(404)).toBe('404');
-	});
-
-	it('converts null to string', () => {
-		expect(getErrorMessage(null)).toBe('null');
-	});
-
-	it('converts undefined to string', () => {
-		expect(getErrorMessage(undefined)).toBe('undefined');
-	});
-
-	it('converts objects to string', () => {
-		expect(getErrorMessage({ foo: 'bar' })).toBe('[object Object]');
-	});
-
-	it('handles empty Error message', () => {
-		const error = new Error('');
-		expect(getErrorMessage(error)).toBe('');
-	});
-});
-
-describe('hasErrorProperty', () => {
-	it('returns true for object with error property', () => {
-		expect(hasErrorProperty({ error: 'some error' })).toBe(true);
-	});
-
-	it('returns true for object with error as object', () => {
-		expect(hasErrorProperty({ error: { message: 'nested' } })).toBe(true);
-	});
-
-	it('returns true for object with null error', () => {
-		expect(hasErrorProperty({ error: null })).toBe(true);
-	});
-
-	it('returns false for null', () => {
-		expect(hasErrorProperty(null)).toBe(false);
-	});
-
-	it('returns false for undefined', () => {
-		expect(hasErrorProperty(undefined)).toBe(false);
-	});
-
-	it('returns false for string', () => {
-		expect(hasErrorProperty('error')).toBe(false);
-	});
-
-	it('returns false for object without error property', () => {
-		expect(hasErrorProperty({ success: true })).toBe(false);
-	});
-
-	it('returns false for empty object', () => {
-		expect(hasErrorProperty({})).toBe(false);
-	});
-
-	it('returns false for array', () => {
-		expect(hasErrorProperty(['error'])).toBe(false);
-	});
-});
-
-describe('extractApiError', () => {
-	it('extracts string error from response', () => {
-		expect(extractApiError({ error: 'Not found' })).toBe('Not found');
-	});
-
-	it('extracts message from nested error object', () => {
-		expect(extractApiError({ error: { message: 'Validation failed' } })).toBe('Validation failed');
-	});
-
-	it('returns "Unknown error" for non-string error without message', () => {
-		expect(extractApiError({ error: { code: 500 } })).toBe('Unknown error');
-	});
-
-	it('returns null for data without error property', () => {
-		expect(extractApiError({ success: true })).toBeNull();
-	});
-
-	it('returns null for null input', () => {
-		expect(extractApiError(null)).toBeNull();
-	});
-
-	it('returns null for undefined input', () => {
-		expect(extractApiError(undefined)).toBeNull();
-	});
-
-	it('returns null for string input', () => {
-		expect(extractApiError('error')).toBeNull();
-	});
-
-	it('returns null for empty object', () => {
-		expect(extractApiError({})).toBeNull();
-	});
-
-	it('handles empty string error', () => {
-		expect(extractApiError({ error: '' })).toBe('');
-	});
-
-	it('returns "Unknown error" for error as number', () => {
-		expect(extractApiError({ error: 404 })).toBe('Unknown error');
-	});
-
-	it('returns "Unknown error" for error as boolean', () => {
-		expect(extractApiError({ error: true })).toBe('Unknown error');
-	});
-
-	it('handles deeply nested message', () => {
-		// Only extracts from immediate .message property
-		expect(extractApiError({ error: { nested: { message: 'deep' } } })).toBe('Unknown error');
-	});
-});
-
-// ============================================================================
-// Pagination Utilities Tests
-// ============================================================================
-
-describe('PAGINATION_LIMITS', () => {
-	it('should have expected default values', () => {
-		expect(PAGINATION_LIMITS.DEFAULT_MAX_LIMIT).toBe(50);
-		expect(PAGINATION_LIMITS.DEFAULT_LIMIT).toBe(20);
-		expect(PAGINATION_LIMITS.TASK_LIMIT).toBe(20);
-	});
-});
-
-describe('capPagination', () => {
-	describe('limit capping', () => {
-		it('should cap limit to maxLimit when exceeded', () => {
-			const { cappedLimit } = capPagination(100, 0, 50);
-			expect(cappedLimit).toBe(50);
-		});
-
-		it('should use limit when under maxLimit', () => {
-			const { cappedLimit } = capPagination(25, 0, 50);
-			expect(cappedLimit).toBe(25);
-		});
-
-		it('should use default maxLimit when not specified', () => {
-			const { cappedLimit } = capPagination(100, 0);
-			expect(cappedLimit).toBe(PAGINATION_LIMITS.DEFAULT_MAX_LIMIT);
-		});
-
-		it('should enforce minimum limit of 1', () => {
-			const { cappedLimit } = capPagination(0, 0, 50);
-			expect(cappedLimit).toBe(1);
-		});
-
-		it('should handle negative limit', () => {
-			const { cappedLimit } = capPagination(-5, 0, 50);
-			expect(cappedLimit).toBe(1);
-		});
-
-		it('should use DEFAULT_LIMIT when limit is undefined', () => {
-			const { cappedLimit } = capPagination(undefined, 0, 50);
-			expect(cappedLimit).toBe(PAGINATION_LIMITS.DEFAULT_LIMIT);
-		});
-	});
-
-	describe('offset safety', () => {
-		it('should keep positive offset unchanged', () => {
-			const { safeOffset } = capPagination(10, 50, 50);
-			expect(safeOffset).toBe(50);
-		});
-
-		it('should convert negative offset to 0', () => {
-			const { safeOffset } = capPagination(10, -10, 50);
-			expect(safeOffset).toBe(0);
-		});
-
-		it('should handle zero offset', () => {
-			const { safeOffset } = capPagination(10, 0, 50);
-			expect(safeOffset).toBe(0);
-		});
-
-		it('should use 0 when offset is undefined', () => {
-			const { safeOffset } = capPagination(10, undefined, 50);
-			expect(safeOffset).toBe(0);
-		});
-	});
-
-	describe('combined behavior', () => {
-		it('should return both cappedLimit and safeOffset', () => {
-			const result = capPagination(100, -5, 20);
-			expect(result).toEqual({
-				cappedLimit: 20,
-				safeOffset: 0,
-			});
-		});
-
-		it('should work with task limit constant', () => {
-			const result = capPagination(50, 10, PAGINATION_LIMITS.TASK_LIMIT);
-			expect(result).toEqual({
-				cappedLimit: 20,
-				safeOffset: 10,
-			});
-		});
-
-		it('should handle all undefined values', () => {
-			const result = capPagination(undefined, undefined);
-			expect(result).toEqual({
-				cappedLimit: PAGINATION_LIMITS.DEFAULT_LIMIT,
-				safeOffset: 0,
-			});
-		});
-	});
-});
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import {
+	AGENT_PERSONAS,
+	FALLBACK_ACTIVITIES,
+	getRandomFallbackActivity,
+	selectPersona,
+	RateLimiter,
+	canValidateTask,
+	isValidStatusTransition,
+	isValidDeploymentStatusTransition,
+	extractProjectNameFromGitUrl,
+	normalizeGitUrl,
+	getErrorMessage,
+	hasErrorProperty,
+	extractApiError,
+	capPagination,
+	PAGINATION_LIMITS,
+} 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', () => {
+		// Sci-fi & fantasy character names
+		expect(AGENT_PERSONAS).toContain('Yoda');
+		expect(AGENT_PERSONAS).toContain('Gandalf');
+		expect(AGENT_PERSONAS).toContain('Spock');
+		expect(AGENT_PERSONAS).toContain('Neo');
+	});
+
+	it('should have short memorable names', () => {
+		// All personas should be reasonably short for dashboard display
+		// Max 8 chars to accommodate names like "Morpheus"
+		for (const persona of AGENT_PERSONAS) {
+			expect(persona.length).toBeLessThanOrEqual(8);
+		}
+	});
+});
+
+// ============================================================================
+// Fallback Activities Tests
+// ============================================================================
+
+describe('FALLBACK_ACTIVITIES', () => {
+	it('should have 12 activities', () => {
+		expect(FALLBACK_ACTIVITIES).toHaveLength(12);
+	});
+
+	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<string>();
+		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<string>([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: 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('null and undefined handling', () => {
+		it('returns null for null input', () => {
+			expect(normalizeGitUrl(null)).toBe(null);
+		});
+
+		it('returns null for undefined input', () => {
+			expect(normalizeGitUrl(undefined)).toBe(null);
+		});
+
+		it('returns null for empty string', () => {
+			expect(normalizeGitUrl('')).toBe(null);
+		});
+
+		it('returns null for whitespace-only string', () => {
+			expect(normalizeGitUrl('   ')).toBe(null);
+		});
+	});
+
+	describe('SSH format conversion', () => {
+		it('converts SSH format to HTTPS', () => {
+			expect(normalizeGitUrl('git@github.com:owner/repo')).toBe('https://github.com/owner/repo');
+		});
+
+		it('converts SSH format with .git suffix', () => {
+			expect(normalizeGitUrl('git@github.com:owner/repo.git')).toBe('https://github.com/owner/repo');
+		});
+
+		it('converts GitLab SSH format', () => {
+			expect(normalizeGitUrl('git@gitlab.com:group/project')).toBe('https://gitlab.com/group/project');
+		});
+
+		it('converts Bitbucket SSH format', () => {
+			expect(normalizeGitUrl('git@bitbucket.org:team/repo')).toBe('https://bitbucket.org/team/repo');
+		});
+
+		it('handles SSH format with nested paths', () => {
+			expect(normalizeGitUrl('git@github.com:org/group/repo')).toBe('https://github.com/org/group/repo');
+		});
+
+		it('converts self-hosted git SSH format', () => {
+			expect(normalizeGitUrl('git@selfhosted.example.com:user/repo.git')).toBe('https://selfhosted.example.com/user/repo');
+		});
+	});
+
+	describe('.git suffix removal', () => {
+		it('removes .git suffix from HTTPS URL', () => {
+			expect(normalizeGitUrl('https://github.com/owner/repo.git')).toBe('https://github.com/owner/repo');
+		});
+
+		it('handles URL without .git suffix', () => {
+			expect(normalizeGitUrl('https://github.com/owner/repo')).toBe('https://github.com/owner/repo');
+		});
+
+		it('does not remove .git from middle of URL', () => {
+			expect(normalizeGitUrl('https://github.com/owner/repo.github.io')).toBe('https://github.com/owner/repo.github.io');
+		});
+	});
+
+	describe('trailing slash removal', () => {
+		it('removes single trailing slash', () => {
+			expect(normalizeGitUrl('https://github.com/owner/repo/')).toBe('https://github.com/owner/repo');
+		});
+
+		it('removes multiple trailing slashes', () => {
+			expect(normalizeGitUrl('https://github.com/owner/repo///')).toBe('https://github.com/owner/repo');
+		});
+
+		it('handles URL without trailing slash', () => {
+			expect(normalizeGitUrl('https://github.com/owner/repo')).toBe('https://github.com/owner/repo');
+		});
+	});
+
+	describe('case normalization', () => {
+		it('lowercases the entire URL', () => {
+			expect(normalizeGitUrl('https://GitHub.com/Owner/Repo')).toBe('https://github.com/owner/repo');
+		});
+
+		it('lowercases mixed case URLs', () => {
+			expect(normalizeGitUrl('https://GITHUB.COM/NONATOMIC/VIBESCOPE')).toBe('https://github.com/nonatomic/vibescope');
+		});
+
+		it('lowercases SSH format before conversion', () => {
+			expect(normalizeGitUrl('git@GitHub.com:Owner/Repo')).toBe('https://github.com/owner/repo');
+		});
+	});
+
+	describe('protocol handling', () => {
+		it('upgrades http to https', () => {
+			expect(normalizeGitUrl('http://github.com/owner/repo')).toBe('https://github.com/owner/repo');
+		});
+
+		it('preserves existing https protocol', () => {
+			expect(normalizeGitUrl('https://github.com/owner/repo')).toBe('https://github.com/owner/repo');
+		});
+
+		it('adds https protocol to bare domain URLs', () => {
+			expect(normalizeGitUrl('github.com/owner/repo')).toBe('https://github.com/owner/repo');
+		});
+	});
+
+	describe('whitespace handling', () => {
+		it('trims leading whitespace', () => {
+			expect(normalizeGitUrl('   https://github.com/owner/repo')).toBe('https://github.com/owner/repo');
+		});
+
+		it('trims trailing whitespace', () => {
+			expect(normalizeGitUrl('https://github.com/owner/repo   ')).toBe('https://github.com/owner/repo');
+		});
+
+		it('trims both leading and trailing whitespace', () => {
+			expect(normalizeGitUrl('  https://github.com/owner/repo  ')).toBe('https://github.com/owner/repo');
+		});
+	});
+
+	describe('combined transformations', () => {
+		it('handles SSH with .git, different casing', () => {
+			expect(normalizeGitUrl('git@GitHub.com:Nonatomic/Vibescope.git')).toBe('https://github.com/nonatomic/vibescope');
+		});
+
+		it('handles HTTPS with trailing slash, .git suffix, and casing', () => {
+			expect(normalizeGitUrl('https://GitHub.com/Nonatomic/Vibescope.git/')).toBe('https://github.com/nonatomic/vibescope');
+		});
+
+		it('handles http with trailing slashes and casing', () => {
+			expect(normalizeGitUrl('http://GitHub.com/Owner/Repo//')).toBe('https://github.com/owner/repo');
+		});
+
+		it('handles bare domain with .git and trailing slash', () => {
+			expect(normalizeGitUrl('github.com/owner/repo.git/')).toBe('https://github.com/owner/repo');
+		});
+	});
+
+	describe('real-world examples', () => {
+		it('normalizes Vibescope registered URL', () => {
+			expect(normalizeGitUrl('https://github.com/Nonatomic/Vibescope')).toBe('https://github.com/nonatomic/vibescope');
+		});
+
+		it('normalizes Vibescope with .git suffix', () => {
+			expect(normalizeGitUrl('https://github.com/Nonatomic/Vibescope.git')).toBe('https://github.com/nonatomic/vibescope');
+		});
+
+		it('normalizes Vibescope SSH format', () => {
+			expect(normalizeGitUrl('git@github.com:Nonatomic/Vibescope.git')).toBe('https://github.com/nonatomic/vibescope');
+		});
+
+		it('normalizes Vibescope with different casing', () => {
+			expect(normalizeGitUrl('https://github.com/nonatomic/vibescope')).toBe('https://github.com/nonatomic/vibescope');
+		});
+
+		it('normalizes Vibescope with trailing slash', () => {
+			expect(normalizeGitUrl('https://github.com/Nonatomic/Vibescope/')).toBe('https://github.com/nonatomic/vibescope');
+		});
+
+		it('all Vibescope variants normalize to same value', () => {
+			const canonical = 'https://github.com/nonatomic/vibescope';
+
+			const variants = [
+				'https://github.com/Nonatomic/Vibescope',
+				'https://github.com/Nonatomic/Vibescope.git',
+				'git@github.com:Nonatomic/Vibescope.git',
+				'https://github.com/nonatomic/vibescope',
+				'https://github.com/Nonatomic/Vibescope/',
+				'https://GITHUB.COM/NONATOMIC/VIBESCOPE',
+				'http://github.com/Nonatomic/Vibescope',
+				'github.com/Nonatomic/Vibescope',
+			];
+
+			for (const variant of variants) {
+				expect(normalizeGitUrl(variant)).toBe(canonical);
+			}
+		});
+	});
+
+	describe('edge cases', () => {
+		it('handles 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('handles nested paths', () => {
+			expect(normalizeGitUrl('https://gitlab.com/group/subgroup/repo.git')).toBe('https://gitlab.com/group/subgroup/repo');
+		});
+
+		it('handles URLs with port numbers', () => {
+			expect(normalizeGitUrl('https://github.com:443/user/repo.git')).toBe('https://github.com:443/user/repo');
+		});
+	});
+});
+
+// ============================================================================
+// Error Handling Utilities Tests
+// ============================================================================
+
+describe('getErrorMessage', () => {
+	it('extracts message from Error object', () => {
+		const error = new Error('Something went wrong');
+		expect(getErrorMessage(error)).toBe('Something went wrong');
+	});
+
+	it('extracts message from TypeError', () => {
+		const error = new TypeError('Invalid type');
+		expect(getErrorMessage(error)).toBe('Invalid type');
+	});
+
+	it('returns string errors as-is', () => {
+		expect(getErrorMessage('Direct error string')).toBe('Direct error string');
+	});
+
+	it('converts numbers to string', () => {
+		expect(getErrorMessage(404)).toBe('404');
+	});
+
+	it('converts null to string', () => {
+		expect(getErrorMessage(null)).toBe('null');
+	});
+
+	it('converts undefined to string', () => {
+		expect(getErrorMessage(undefined)).toBe('undefined');
+	});
+
+	it('converts objects to string', () => {
+		expect(getErrorMessage({ foo: 'bar' })).toBe('[object Object]');
+	});
+
+	it('handles empty Error message', () => {
+		const error = new Error('');
+		expect(getErrorMessage(error)).toBe('');
+	});
+});
+
+describe('hasErrorProperty', () => {
+	it('returns true for object with error property', () => {
+		expect(hasErrorProperty({ error: 'some error' })).toBe(true);
+	});
+
+	it('returns true for object with error as object', () => {
+		expect(hasErrorProperty({ error: { message: 'nested' } })).toBe(true);
+	});
+
+	it('returns true for object with null error', () => {
+		expect(hasErrorProperty({ error: null })).toBe(true);
+	});
+
+	it('returns false for null', () => {
+		expect(hasErrorProperty(null)).toBe(false);
+	});
+
+	it('returns false for undefined', () => {
+		expect(hasErrorProperty(undefined)).toBe(false);
+	});
+
+	it('returns false for string', () => {
+		expect(hasErrorProperty('error')).toBe(false);
+	});
+
+	it('returns false for object without error property', () => {
+		expect(hasErrorProperty({ success: true })).toBe(false);
+	});
+
+	it('returns false for empty object', () => {
+		expect(hasErrorProperty({})).toBe(false);
+	});
+
+	it('returns false for array', () => {
+		expect(hasErrorProperty(['error'])).toBe(false);
+	});
+});
+
+describe('extractApiError', () => {
+	it('extracts string error from response', () => {
+		expect(extractApiError({ error: 'Not found' })).toBe('Not found');
+	});
+
+	it('extracts message from nested error object', () => {
+		expect(extractApiError({ error: { message: 'Validation failed' } })).toBe('Validation failed');
+	});
+
+	it('returns "Unknown error" for non-string error without message', () => {
+		expect(extractApiError({ error: { code: 500 } })).toBe('Unknown error');
+	});
+
+	it('returns null for data without error property', () => {
+		expect(extractApiError({ success: true })).toBeNull();
+	});
+
+	it('returns null for null input', () => {
+		expect(extractApiError(null)).toBeNull();
+	});
+
+	it('returns null for undefined input', () => {
+		expect(extractApiError(undefined)).toBeNull();
+	});
+
+	it('returns null for string input', () => {
+		expect(extractApiError('error')).toBeNull();
+	});
+
+	it('returns null for empty object', () => {
+		expect(extractApiError({})).toBeNull();
+	});
+
+	it('handles empty string error', () => {
+		expect(extractApiError({ error: '' })).toBe('');
+	});
+
+	it('returns "Unknown error" for error as number', () => {
+		expect(extractApiError({ error: 404 })).toBe('Unknown error');
+	});
+
+	it('returns "Unknown error" for error as boolean', () => {
+		expect(extractApiError({ error: true })).toBe('Unknown error');
+	});
+
+	it('handles deeply nested message', () => {
+		// Only extracts from immediate .message property
+		expect(extractApiError({ error: { nested: { message: 'deep' } } })).toBe('Unknown error');
+	});
+});
+
+// ============================================================================
+// Pagination Utilities Tests
+// ============================================================================
+
+describe('PAGINATION_LIMITS', () => {
+	it('should have expected default values', () => {
+		expect(PAGINATION_LIMITS.DEFAULT_MAX_LIMIT).toBe(50);
+		expect(PAGINATION_LIMITS.DEFAULT_LIMIT).toBe(20);
+		expect(PAGINATION_LIMITS.TASK_LIMIT).toBe(20);
+	});
+});
+
+describe('capPagination', () => {
+	describe('limit capping', () => {
+		it('should cap limit to maxLimit when exceeded', () => {
+			const { cappedLimit } = capPagination(100, 0, 50);
+			expect(cappedLimit).toBe(50);
+		});
+
+		it('should use limit when under maxLimit', () => {
+			const { cappedLimit } = capPagination(25, 0, 50);
+			expect(cappedLimit).toBe(25);
+		});
+
+		it('should use default maxLimit when not specified', () => {
+			const { cappedLimit } = capPagination(100, 0);
+			expect(cappedLimit).toBe(PAGINATION_LIMITS.DEFAULT_MAX_LIMIT);
+		});
+
+		it('should enforce minimum limit of 1', () => {
+			const { cappedLimit } = capPagination(0, 0, 50);
+			expect(cappedLimit).toBe(1);
+		});
+
+		it('should handle negative limit', () => {
+			const { cappedLimit } = capPagination(-5, 0, 50);
+			expect(cappedLimit).toBe(1);
+		});
+
+		it('should use DEFAULT_LIMIT when limit is undefined', () => {
+			const { cappedLimit } = capPagination(undefined, 0, 50);
+			expect(cappedLimit).toBe(PAGINATION_LIMITS.DEFAULT_LIMIT);
+		});
+	});
+
+	describe('offset safety', () => {
+		it('should keep positive offset unchanged', () => {
+			const { safeOffset } = capPagination(10, 50, 50);
+			expect(safeOffset).toBe(50);
+		});
+
+		it('should convert negative offset to 0', () => {
+			const { safeOffset } = capPagination(10, -10, 50);
+			expect(safeOffset).toBe(0);
+		});
+
+		it('should handle zero offset', () => {
+			const { safeOffset } = capPagination(10, 0, 50);
+			expect(safeOffset).toBe(0);
+		});
+
+		it('should use 0 when offset is undefined', () => {
+			const { safeOffset } = capPagination(10, undefined, 50);
+			expect(safeOffset).toBe(0);
+		});
+	});
+
+	describe('combined behavior', () => {
+		it('should return both cappedLimit and safeOffset', () => {
+			const result = capPagination(100, -5, 20);
+			expect(result).toEqual({
+				cappedLimit: 20,
+				safeOffset: 0,
+			});
+		});
+
+		it('should work with task limit constant', () => {
+			const result = capPagination(50, 10, PAGINATION_LIMITS.TASK_LIMIT);
+			expect(result).toEqual({
+				cappedLimit: 20,
+				safeOffset: 10,
+			});
+		});
+
+		it('should handle all undefined values', () => {
+			const result = capPagination(undefined, undefined);
+			expect(result).toEqual({
+				cappedLimit: PAGINATION_LIMITS.DEFAULT_LIMIT,
+				safeOffset: 0,
+			});
+		});
+	});
+});