@vibescope/mcp-server 0.2.0 → 0.2.1

package/src/handlers/roles.test.ts

@@ -0,0 +1,303 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+	getRoleSettings,
+	updateRoleSettings,
+	setSessionRole,
+	getAgentsByRole,
+} from './roles.js';
+import { createMockContext } from './__test-utils__.js';
+import { mockApiClient } from './__test-setup__.js';
+
+// ============================================================================
+// getRoleSettings Tests
+// ============================================================================
+
+describe('getRoleSettings', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should return error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		const result = await getRoleSettings({}, ctx);
+
+		expect(result.result).toMatchObject({
+			error: 'project_id is required',
+		});
+	});
+
+	it('should get role settings successfully', async () => {
+		const mockRoles = [
+			{ role: 'developer', enabled: true, display_name: 'Developer' },
+			{ role: 'validator', enabled: true, display_name: 'Validator' },
+		];
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: { roles: mockRoles },
+		});
+		const ctx = createMockContext();
+
+		const result = await getRoleSettings(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ roles: mockRoles });
+		expect(mockApiClient.proxy).toHaveBeenCalledWith(
+			'get_role_settings',
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' }
+		);
+	});
+
+	it('should return error from API', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: false,
+			error: 'Project not found',
+		});
+		const ctx = createMockContext();
+
+		const result = await getRoleSettings(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			error: 'Project not found',
+		});
+	});
+});
+
+// ============================================================================
+// updateRoleSettings Tests
+// ============================================================================
+
+describe('updateRoleSettings', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should return error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		const result = await updateRoleSettings({ role: 'developer' }, ctx);
+
+		expect(result.result).toMatchObject({
+			error: 'project_id is required',
+		});
+	});
+
+	it('should return error for missing role', async () => {
+		const ctx = createMockContext();
+
+		const result = await updateRoleSettings(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			error: 'role is required',
+		});
+	});
+
+	it('should update role settings successfully', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: { success: true, role: 'validator' },
+		});
+		const ctx = createMockContext();
+
+		const result = await updateRoleSettings(
+			{
+				project_id: '123e4567-e89b-12d3-a456-426614174000',
+				role: 'validator',
+				enabled: true,
+				auto_assign_validation: true,
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			role: 'validator',
+		});
+		expect(mockApiClient.proxy).toHaveBeenCalledWith(
+			'update_role_settings',
+			expect.objectContaining({
+				project_id: '123e4567-e89b-12d3-a456-426614174000',
+				role: 'validator',
+				enabled: true,
+				auto_assign_validation: true,
+			})
+		);
+	});
+
+	it('should return error from API', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: false,
+			error: 'Access denied',
+		});
+		const ctx = createMockContext();
+
+		const result = await updateRoleSettings(
+			{
+				project_id: '123e4567-e89b-12d3-a456-426614174000',
+				role: 'validator',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			error: 'Access denied',
+		});
+	});
+});
+
+// ============================================================================
+// setSessionRole Tests
+// ============================================================================
+
+describe('setSessionRole', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should return error for missing role', async () => {
+		const ctx = createMockContext();
+
+		const result = await setSessionRole({}, ctx);
+
+		expect(result.result).toMatchObject({
+			error: 'role is required',
+		});
+	});
+
+	it('should return error for invalid role', async () => {
+		const ctx = createMockContext();
+
+		const result = await setSessionRole({ role: 'invalid_role' }, ctx);
+
+		expect(result.result).toMatchObject({
+			error: expect.stringContaining('Invalid role: invalid_role'),
+		});
+	});
+
+	it('should set local role when no active session', async () => {
+		const ctx = createMockContext({ sessionId: null });
+
+		const result = await setSessionRole({ role: 'validator' }, ctx);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			role: 'validator',
+			message: expect.stringContaining('Local role set to validator'),
+		});
+	});
+
+	it('should update session role on server when session active', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: { success: true, session_id: 'session-123', role: 'deployer' },
+		});
+		const ctx = createMockContext({ sessionId: 'session-123' });
+
+		const result = await setSessionRole({ role: 'deployer' }, ctx);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			session_id: 'session-123',
+			role: 'deployer',
+		});
+		expect(mockApiClient.proxy).toHaveBeenCalledWith(
+			'set_session_role',
+			expect.objectContaining({
+				session_id: 'session-123',
+				role: 'deployer',
+			})
+		);
+	});
+
+	it('should update local state when setting role', async () => {
+		const updateSession = vi.fn();
+		const ctx = createMockContext({ sessionId: null });
+		ctx.updateSession = updateSession;
+
+		await setSessionRole({ role: 'reviewer' }, ctx);
+
+		expect(updateSession).toHaveBeenCalledWith({ currentRole: 'reviewer' });
+	});
+
+	it('should return error from API when updating session', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: false,
+			error: 'Session not found',
+		});
+		const ctx = createMockContext({ sessionId: 'session-123' });
+
+		const result = await setSessionRole({ role: 'maintainer' }, ctx);
+
+		expect(result.result).toMatchObject({
+			error: 'Session not found',
+		});
+	});
+});
+
+// ============================================================================
+// getAgentsByRole Tests
+// ============================================================================
+
+describe('getAgentsByRole', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should return error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		const result = await getAgentsByRole({}, ctx);
+
+		expect(result.result).toMatchObject({
+			error: 'project_id is required',
+		});
+	});
+
+	it('should get agents by role successfully', async () => {
+		const mockAgentsByRole = {
+			developer: [
+				{ session_id: 'session-1', agent_name: 'Edge', status: 'active' },
+			],
+			validator: [],
+			deployer: [],
+			reviewer: [],
+			maintainer: [],
+		};
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: { agents_by_role: mockAgentsByRole, total_active: 1 },
+		});
+		const ctx = createMockContext();
+
+		const result = await getAgentsByRole(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			agents_by_role: mockAgentsByRole,
+			total_active: 1,
+		});
+		expect(mockApiClient.proxy).toHaveBeenCalledWith(
+			'get_agents_by_role',
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' }
+		);
+	});
+
+	it('should return error from API', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: false,
+			error: 'Project not found',
+		});
+		const ctx = createMockContext();
+
+		const result = await getAgentsByRole(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			error: 'Project not found',
+		});
+	});
+});

package/src/handlers/roles.ts

@@ -0,0 +1,208 @@
+/**
+ * Role Management Handlers
+ *
+ * Handles agent role configuration and assignment:
+ * - get_role_settings: Get role configuration for a project
+ * - update_role_settings: Update role settings for a project
+ * - set_session_role: Set the role for the current session
+ * - get_agents_by_role: Get active agents grouped by their assigned roles
+ */
+
+import type { Handler, HandlerRegistry, AgentRole } from './types.js';
+import { getApiClient } from '../api-client.js';
+
+export const getRoleSettings: Handler = async (args, _ctx) => {
+	const { project_id } = args as { project_id: string };
+
+	if (!project_id) {
+		return {
+			result: { error: 'project_id is required' },
+		};
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.proxy<{
+		roles: Array<{
+			role: AgentRole;
+			enabled: boolean;
+			display_name: string | null;
+			description: string | null;
+			priority_filter: number[] | null;
+			fallback_activities: string[] | null;
+			auto_assign_validation: boolean;
+			auto_assign_deployment: boolean;
+		}>;
+	}>('get_role_settings', { project_id });
+
+	if (!response.ok) {
+		return {
+			result: { error: response.error || 'Failed to get role settings' },
+		};
+	}
+
+	return { result: response.data };
+};
+
+export const updateRoleSettings: Handler = async (args, _ctx) => {
+	const {
+		project_id,
+		role,
+		enabled,
+		display_name,
+		description,
+		priority_filter,
+		fallback_activities,
+		auto_assign_validation,
+		auto_assign_deployment,
+	} = args as {
+		project_id: string;
+		role: AgentRole;
+		enabled?: boolean;
+		display_name?: string;
+		description?: string;
+		priority_filter?: number[];
+		fallback_activities?: string[];
+		auto_assign_validation?: boolean;
+		auto_assign_deployment?: boolean;
+	};
+
+	if (!project_id) {
+		return {
+			result: { error: 'project_id is required' },
+		};
+	}
+
+	if (!role) {
+		return {
+			result: { error: 'role is required' },
+		};
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.proxy<{
+		success: boolean;
+		role: AgentRole;
+	}>('update_role_settings', {
+		project_id,
+		role,
+		enabled,
+		display_name,
+		description,
+		priority_filter,
+		fallback_activities,
+		auto_assign_validation,
+		auto_assign_deployment,
+	});
+
+	if (!response.ok) {
+		return {
+			result: { error: response.error || 'Failed to update role settings' },
+		};
+	}
+
+	return { result: response.data };
+};
+
+export const setSessionRole: Handler = async (args, ctx) => {
+	const { role, role_config } = args as {
+		role: AgentRole;
+		role_config?: Record<string, unknown>;
+	};
+	const { session, updateSession } = ctx;
+
+	if (!role) {
+		return {
+			result: { error: 'role is required' },
+		};
+	}
+
+	const validRoles: AgentRole[] = ['developer', 'validator', 'deployer', 'reviewer', 'maintainer'];
+	if (!validRoles.includes(role)) {
+		return {
+			result: {
+				error: `Invalid role: ${role}. Must be one of: ${validRoles.join(', ')}`,
+			},
+		};
+	}
+
+	// Update local session state
+	updateSession({ currentRole: role });
+
+	// If there's an active session, update it on the server too
+	if (session.currentSessionId) {
+		const apiClient = getApiClient();
+		const response = await apiClient.proxy<{
+			success: boolean;
+			session_id: string;
+			role: AgentRole;
+		}>('set_session_role', {
+			session_id: session.currentSessionId,
+			role,
+			role_config,
+		});
+
+		if (!response.ok) {
+			return {
+				result: { error: response.error || 'Failed to update session role' },
+			};
+		}
+
+		return {
+			result: {
+				success: true,
+				session_id: session.currentSessionId,
+				role,
+				message: `Session role updated to ${role}. Task filtering and fallback suggestions will now be optimized for this role.`,
+			},
+		};
+	}
+
+	return {
+		result: {
+			success: true,
+			role,
+			message: `Local role set to ${role}. Start a session to persist this role.`,
+		},
+	};
+};
+
+export const getAgentsByRole: Handler = async (args, _ctx) => {
+	const { project_id } = args as { project_id: string };
+
+	if (!project_id) {
+		return {
+			result: { error: 'project_id is required' },
+		};
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.proxy<{
+		agents_by_role: Record<AgentRole, Array<{
+			session_id: string;
+			agent_name: string;
+			status: string;
+			current_task_id: string | null;
+			current_task_title: string | null;
+			last_synced_at: string;
+		}>>;
+		total_active: number;
+	}>('get_agents_by_role', { project_id });
+
+	if (!response.ok) {
+		return {
+			result: { error: response.error || 'Failed to get agents by role' },
+		};
+	}
+
+	return { result: response.data };
+};
+
+/**
+ * Role handlers registry
+ */
+export const roleHandlers: HandlerRegistry = {
+	get_role_settings: getRoleSettings,
+	update_role_settings: updateRoleSettings,
+	set_session_role: setSessionRole,
+	get_agents_by_role: getAgentsByRole,
+};

package/src/handlers/session.ts

@@ -10,22 +10,47 @@
  */
 
 import type { Handler, HandlerRegistry, TokenUsage } from './types.js';
+import { parseArgs, createEnumValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
+const VALID_MODES = ['lite', 'full'] as const;
+const VALID_MODELS = ['opus', 'sonnet', 'haiku'] as const;
+const VALID_ROLES = ['developer', 'validator', 'deployer', 'reviewer', 'maintainer'] as const;
+
+type SessionMode = typeof VALID_MODES[number];
+type SessionModel = typeof VALID_MODELS[number];
+type SessionRole = typeof VALID_ROLES[number];
+
+// Argument schemas for type-safe parsing
+const startWorkSessionSchema = {
+	project_id: { type: 'string' as const },
+	git_url: { type: 'string' as const },
+	mode: { type: 'string' as const, default: 'lite', validate: createEnumValidator(VALID_MODES) },
+	model: { type: 'string' as const, validate: createEnumValidator(VALID_MODELS) },
+	role: { type: 'string' as const, default: 'developer', validate: createEnumValidator(VALID_ROLES) },
+};
+
+const heartbeatSchema = {
+	session_id: { type: 'string' as const },
+	current_worktree_path: { type: 'string' as const },
+};
+
+const endWorkSessionSchema = {
+	session_id: { type: 'string' as const },
+};
+
+const getHelpSchema = {
+	topic: { type: 'string' as const, required: true as const },
+};
+
 export const startWorkSession: Handler = async (args, ctx) => {
-	const { project_id, git_url, mode = 'lite', model, role = 'developer' } = args as {
-		project_id?: string;
-		git_url?: string;
-		mode?: 'lite' | 'full';
-		model?: 'opus' | 'sonnet' | 'haiku';
-		role?: 'developer' | 'validator' | 'deployer' | 'reviewer' | 'maintainer';
-	};
+	const { project_id, git_url, mode, model, role } = parseArgs(args, startWorkSessionSchema);
 
 	const { session, updateSession } = ctx;
 
 	// Reset token tracking for new session with model info
 	const normalizedModel = model ? model.toLowerCase().replace(/^claude[- ]*/i, '') : null;
-	const validModel = normalizedModel && ['opus', 'sonnet', 'haiku'].includes(normalizedModel)
+	const validModel = normalizedModel && VALID_MODELS.includes(normalizedModel as SessionModel)
 		? normalizedModel
 		: null;
 
@@ -52,9 +77,9 @@ export const startWorkSession: Handler = async (args, ctx) => {
 	const response = await apiClient.startSession({
 		project_id,
 		git_url,
-		mode,
-		model,
-		role
+		mode: mode as SessionMode,
+		model: model as SessionModel | undefined,
+		role: role as SessionRole
 	});
 
 	if (!response.ok) {
@@ -139,10 +164,7 @@ export const startWorkSession: Handler = async (args, ctx) => {
 };
 
 export const heartbeat: Handler = async (args, ctx) => {
-	const { session_id, current_worktree_path } = args as {
-		session_id?: string;
-		current_worktree_path?: string | null;
-	};
+	const { session_id, current_worktree_path } = parseArgs(args, heartbeatSchema);
 	const { session } = ctx;
 	const targetSession = session_id || session.currentSessionId;
 
@@ -186,7 +208,7 @@ export const heartbeat: Handler = async (args, ctx) => {
 };
 
 export const endWorkSession: Handler = async (args, ctx) => {
-	const { session_id } = args as { session_id?: string };
+	const { session_id } = parseArgs(args, endWorkSessionSchema);
 	const { session, updateSession } = ctx;
 	const targetSession = session_id || session.currentSessionId;
 
@@ -251,7 +273,7 @@ export const endWorkSession: Handler = async (args, ctx) => {
 };
 
 export const getHelp: Handler = async (args, _ctx) => {
-	const { topic } = args as { topic: string };
+	const { topic } = parseArgs(args, getHelpSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.getHelpTopic(topic);