@vibescope/mcp-server 0.0.1

package/src/utils.ts

@@ -0,0 +1,375 @@
+// ============================================================================
+// Utilities Module - Extracted from index.ts for testability
+// ============================================================================
+
+import { randomUUID } from 'crypto';
+
+// ============================================================================
+// Agent Persona Pool
+// Short, memorable names for distinguishing agents on the dashboard
+// ============================================================================
+
+export const AGENT_PERSONAS = [
+	'Apex',
+	'Arc',
+	'Atlas',
+	'Blaze',
+	'Bolt',
+	'Byte',
+	'Cipher',
+	'Core',
+	'Dash',
+	'Drift',
+	'Echo',
+	'Edge',
+	'Ember',
+	'Flux',
+	'Forge',
+	'Ghost',
+	'Glitch',
+	'Haze',
+	'Hex',
+	'Ion',
+	'Iris',
+	'Jade',
+	'Jet',
+	'Karma',
+	'Kite',
+	'Lux',
+	'Mako',
+	'Neon',
+	'Nova',
+	'Onyx',
+	'Orbit',
+	'Pixel',
+	'Pulse',
+	'Quest',
+	'Rex',
+	'Rune',
+	'Shade',
+	'Spark',
+	'Storm',
+	'Trace',
+	'Turbo',
+	'Vex',
+	'Volt',
+	'Warp',
+	'Wave',
+	'Zen',
+	'Zero',
+] as const;
+
+export type AgentPersona = typeof AGENT_PERSONAS[number];
+
+// ============================================================================
+// Fallback Activities for Idle Agents
+// Suggested productive activities when no pending tasks exist
+// ============================================================================
+
+export const FALLBACK_ACTIVITIES = [
+	{
+		activity: 'feature_ideation',
+		title: 'Generate feature ideas',
+		description: 'Review the codebase and suggest improvements or new features. Use add_idea to record your findings.',
+		prompt: 'Explore the codebase, identify areas for improvement, and suggest 2-3 actionable feature ideas using add_idea.',
+	},
+	{
+		activity: 'feature_planning',
+		title: 'Plan features from ideas',
+		description: 'Take raw ideas and develop them into planned features with documentation.',
+		prompt: 'Call get_ideas to find ideas with status "raw" or "exploring". Pick one and develop it: research requirements, identify implementation steps, write a feature spec. Use update_idea to change status to "planned" and add a doc_url if you create documentation.',
+	},
+	{
+		activity: 'code_review',
+		title: 'Code standards review',
+		description: 'Check for inconsistencies, missing types, code smells, or patterns that could be improved.',
+		prompt: 'Review the codebase for code quality issues. Look for missing types, inconsistent patterns, or technical debt. Log findings with add_idea or add_task.',
+	},
+	{
+		activity: 'performance_audit',
+		title: 'Performance audit',
+		description: 'Identify potential performance bottlenecks or optimization opportunities.',
+		prompt: 'Analyze the codebase for performance issues: N+1 queries, unnecessary re-renders, expensive operations. Create tasks for fixes with add_task.',
+	},
+	{
+		activity: 'ux_review',
+		title: 'UX review',
+		description: 'Evaluate user flows and identify usability improvements.',
+		prompt: 'Review the UI components and user flows. Identify confusing interactions, missing feedback, or accessibility issues. Log improvements with add_idea.',
+	},
+	{
+		activity: 'cost_analysis',
+		title: 'Cost analysis',
+		description: 'Review infrastructure and API usage for cost optimization opportunities.',
+		prompt: 'Analyze the codebase for expensive operations: unnecessary API calls, inefficient queries, large bundle sizes. Suggest cost-saving alternatives with add_idea.',
+	},
+	{
+		activity: 'security_review',
+		title: 'Security review',
+		description: 'Check for common security issues: auth gaps, input validation, data exposure.',
+		prompt: 'Review the codebase for security concerns: authentication gaps, missing input validation, sensitive data handling. Create high-priority tasks for issues found.',
+	},
+	{
+		activity: 'test_coverage',
+		title: 'Test coverage analysis',
+		description: 'Find untested code paths and suggest test cases.',
+		prompt: 'Identify areas of the codebase with missing or weak test coverage. Create tasks for writing tests using add_task.',
+	},
+	{
+		activity: 'documentation_review',
+		title: 'Documentation review',
+		description: 'Identify missing or outdated documentation.',
+		prompt: 'Review existing docs and code comments. Identify gaps, outdated information, or confusing explanations. Log improvements with add_idea.',
+	},
+	{
+		activity: 'dependency_audit',
+		title: 'Dependency audit',
+		description: 'Review dependencies for updates, security issues, or unused packages.',
+		prompt: 'Check package.json for outdated dependencies, security vulnerabilities, or unused packages. Create tasks for updates with add_task.',
+	},
+	{
+		activity: 'validate_completed_tasks',
+		title: 'Validate completed tasks',
+		description: 'Review tasks completed by other agents to ensure quality.',
+		prompt: 'Call get_tasks_awaiting_validation to find completed tasks that need review. Validate each one by checking the implementation and running tests if applicable.',
+	},
+] as const;
+
+export type FallbackActivity = typeof FALLBACK_ACTIVITIES[number];
+
+/**
+ * Get a random fallback activity
+ */
+export function getRandomFallbackActivity(): FallbackActivity {
+	const index = Math.floor(Math.random() * FALLBACK_ACTIVITIES.length);
+	return FALLBACK_ACTIVITIES[index];
+}
+
+/**
+ * Select an available persona from the pool (randomly)
+ * @param usedPersonas Set of personas currently in use
+ * @param instanceId The instance ID for fallback naming
+ * @returns The selected persona name
+ */
+export function selectPersona(usedPersonas: Set<string>, instanceId: string): string {
+	const availablePersonas = AGENT_PERSONAS.filter((p) => !usedPersonas.has(p));
+	if (availablePersonas.length === 0) {
+		return `Agent-${instanceId.slice(0, 6)}`;
+	}
+	const randomIndex = Math.floor(Math.random() * availablePersonas.length);
+	return availablePersonas[randomIndex];
+}
+
+// ============================================================================
+// Rate Limiter
+// ============================================================================
+
+export interface RateLimitResult {
+	allowed: boolean;
+	remaining: number;
+	resetIn: number;
+}
+
+export class RateLimiter {
+	private requests: Map<string, { count: number; resetAt: number }> = new Map();
+	private readonly maxRequests: number;
+	private readonly windowMs: number;
+
+	constructor(maxRequests: number = 60, windowMs: number = 60000) {
+		this.maxRequests = maxRequests;
+		this.windowMs = windowMs;
+	}
+
+	check(key: string): RateLimitResult {
+		const now = Date.now();
+		const record = this.requests.get(key);
+
+		// If no record or window expired, create new record
+		if (!record || now >= record.resetAt) {
+			this.requests.set(key, { count: 1, resetAt: now + this.windowMs });
+			return { allowed: true, remaining: this.maxRequests - 1, resetIn: this.windowMs };
+		}
+
+		// Check if limit exceeded
+		if (record.count >= this.maxRequests) {
+			return { allowed: false, remaining: 0, resetIn: record.resetAt - now };
+		}
+
+		// Increment count
+		record.count++;
+		return { allowed: true, remaining: this.maxRequests - record.count, resetIn: record.resetAt - now };
+	}
+
+	// Clean up expired entries periodically
+	cleanup(): void {
+		const now = Date.now();
+		for (const [key, record] of this.requests.entries()) {
+			if (now >= record.resetAt) {
+				this.requests.delete(key);
+			}
+		}
+	}
+
+	// Expose for testing
+	getRequestCount(key: string): number | undefined {
+		return this.requests.get(key)?.count;
+	}
+}
+
+// ============================================================================
+// Task Validation Helpers
+// ============================================================================
+
+/**
+ * Check if a task can be validated by the given session
+ * @param task The task to validate
+ * @param validatorSessionId The session trying to validate
+ * @returns Object with canValidate boolean and reason if not allowed
+ */
+export function canValidateTask(
+	task: { status: string; validated_at: string | null; working_agent_session_id: string | null },
+	validatorSessionId: string | null
+): { canValidate: boolean; reason?: string } {
+	if (task.status !== 'completed') {
+		return { canValidate: false, reason: 'Can only validate completed tasks' };
+	}
+
+	if (task.validated_at) {
+		return { canValidate: false, reason: 'Task has already been validated' };
+	}
+
+	// Note: Self-validation check would go here if we tracked who completed the task
+	// Currently, working_agent_session_id is cleared on completion
+
+	return { canValidate: true };
+}
+
+/**
+ * Check if a task status transition is valid
+ * @param currentStatus Current task status
+ * @param newStatus Desired new status
+ * @returns Object with isValid boolean and reason if not valid
+ */
+export function isValidStatusTransition(
+	currentStatus: string,
+	newStatus: string
+): { isValid: boolean; reason?: string } {
+	const validTransitions: Record<string, string[]> = {
+		pending: ['in_progress', 'cancelled'],
+		in_progress: ['completed', 'pending', 'cancelled'],
+		completed: ['in_progress'], // Can reopen via validation failure
+		cancelled: ['pending'], // Can reactivate cancelled tasks
+	};
+
+	const allowed = validTransitions[currentStatus];
+	if (!allowed) {
+		return { isValid: false, reason: `Unknown current status: ${currentStatus}` };
+	}
+
+	if (!allowed.includes(newStatus)) {
+		return {
+			isValid: false,
+			reason: `Cannot transition from '${currentStatus}' to '${newStatus}'. Valid transitions: ${allowed.join(', ')}`
+		};
+	}
+
+	return { isValid: true };
+}
+
+/**
+ * Check if a deployment status transition is valid
+ * @param currentStatus Current deployment status
+ * @param newStatus Desired new status
+ * @returns Object with isValid boolean and reason if not valid
+ */
+export function isValidDeploymentStatusTransition(
+	currentStatus: string,
+	newStatus: string
+): { isValid: boolean; reason?: string } {
+	const validTransitions: Record<string, string[]> = {
+		pending: ['validating', 'failed'], // Can claim validation or cancel
+		validating: ['ready', 'failed'], // Validation passes or fails
+		ready: ['deploying', 'failed'], // Start deployment or cancel
+		deploying: ['deployed', 'failed'], // Deployment succeeds or fails
+		deployed: [], // Terminal state
+		failed: [], // Terminal state (create new deployment to retry)
+	};
+
+	const allowed = validTransitions[currentStatus];
+	if (!allowed) {
+		return { isValid: false, reason: `Unknown current status: ${currentStatus}` };
+	}
+
+	if (!allowed.includes(newStatus)) {
+		return {
+			isValid: false,
+			reason: `Cannot transition deployment from '${currentStatus}' to '${newStatus}'. Valid transitions: ${allowed.length ? allowed.join(', ') : 'none (terminal state)'}`
+		};
+	}
+
+	return { isValid: true };
+}
+
+// ============================================================================
+// Git URL Parsing
+// ============================================================================
+
+/**
+ * Extract project name from a git URL.
+ * Handles various git URL formats:
+ * - https://github.com/user/repo -> repo
+ * - https://github.com/user/repo.git -> repo
+ * - git@github.com:user/repo.git -> repo
+ * - https://gitlab.com/user/repo -> repo
+ * - ssh://git@github.com/user/repo.git -> repo
+ *
+ * @param gitUrl The git URL to parse
+ * @returns The extracted project name, or 'my-project' if parsing fails
+ */
+export function extractProjectNameFromGitUrl(gitUrl: string): string {
+	if (!gitUrl) {
+		return 'my-project';
+	}
+
+	// Match the last path segment, optionally removing .git suffix
+	// Works for:
+	// - /user/repo (https URLs)
+	// - /user/repo.git
+	// - :user/repo (ssh URLs like git@github.com:user/repo)
+	// - :user/repo.git
+	const match = gitUrl.match(/[/:]([^/:]+?)(?:\.git)?$/);
+	if (match && match[1]) {
+		return match[1];
+	}
+
+	return 'my-project';
+}
+
+/**
+ * Normalize a git URL to a consistent HTTPS format.
+ * - Removes .git suffix
+ * - Converts SSH URLs (git@host:path) to HTTPS format
+ *
+ * Supports GitHub, GitLab, and Bitbucket.
+ *
+ * @param gitUrl The git URL to normalize
+ * @returns The normalized URL, or the original if no normalization needed
+ *
+ * @example
+ * normalizeGitUrl('git@github.com:user/repo.git')
+ * // returns 'https://github.com/user/repo'
+ *
+ * normalizeGitUrl('https://github.com/user/repo.git')
+ * // returns 'https://github.com/user/repo'
+ */
+export function normalizeGitUrl(gitUrl: string): string {
+	if (!gitUrl) {
+		return gitUrl;
+	}
+
+	return gitUrl
+		.replace(/\.git$/, '')
+		.replace(/^git@github\.com:/, 'https://github.com/')
+		.replace(/^git@gitlab\.com:/, 'https://gitlab.com/')
+		.replace(/^git@bitbucket\.org:/, 'https://bitbucket.org/');
+}

package/src/validators.test.ts

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