@vibescope/mcp-server 0.1.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.test.ts

@@ -31,7 +31,7 @@ describe('heartbeat', () => {
 			session_id: 'session-123',
 		});
 		expect(result.result).toHaveProperty('timestamp');
-		expect(mockApiClient.heartbeat).toHaveBeenCalledWith('session-123');
+		expect(mockApiClient.heartbeat).toHaveBeenCalledWith('session-123', { current_worktree_path: undefined });
 	});
 
 	it('should use provided session_id over current session', async () => {
@@ -48,7 +48,20 @@ describe('heartbeat', () => {
 			success: true,
 			session_id: 'other-session-456',
 		});
-		expect(mockApiClient.heartbeat).toHaveBeenCalledWith('other-session-456');
+		expect(mockApiClient.heartbeat).toHaveBeenCalledWith('other-session-456', { current_worktree_path: undefined });
+	});
+
+	it('should pass worktree_path to API', async () => {
+		const ctx = createMockContext();
+		mockApiClient.heartbeat.mockResolvedValue({
+			ok: true,
+			data: { timestamp: '2026-01-14T10:00:00Z' },
+		});
+		mockApiClient.syncSession.mockResolvedValue({ ok: true });
+
+		await heartbeat({ current_worktree_path: '../project-task-abc123' }, ctx);
+
+		expect(mockApiClient.heartbeat).toHaveBeenCalledWith('session-123', { current_worktree_path: '../project-task-abc123' });
 	});
 
 	it('should return error when no active session', async () => {
@@ -101,6 +114,10 @@ describe('getHelp', () => {
 
 	it('should return help content for valid topic', async () => {
 		const ctx = createMockContext();
+		mockApiClient.getHelpTopic.mockResolvedValue({
+			ok: true,
+			data: { slug: 'tasks', title: 'Task Workflow', content: '# Task Workflow\nTest content' },
+		});
 
 		const result = await getHelp({ topic: 'tasks' }, ctx);
 
@@ -110,6 +127,10 @@ describe('getHelp', () => {
 
 	it('should return getting_started help', async () => {
 		const ctx = createMockContext();
+		mockApiClient.getHelpTopic.mockResolvedValue({
+			ok: true,
+			data: { slug: 'getting_started', title: 'Getting Started', content: '# Getting Started\nTest content' },
+		});
 
 		const result = await getHelp({ topic: 'getting_started' }, ctx);
 
@@ -119,6 +140,11 @@ describe('getHelp', () => {
 
 	it('should return error for unknown topic', async () => {
 		const ctx = createMockContext();
+		mockApiClient.getHelpTopic.mockResolvedValue({ ok: true, data: null });
+		mockApiClient.getHelpTopics.mockResolvedValue({
+			ok: true,
+			data: [{ slug: 'tasks', title: 'Tasks' }, { slug: 'getting_started', title: 'Getting Started' }],
+		});
 
 		const result = await getHelp({ topic: 'unknown_topic' }, ctx);
 
@@ -130,6 +156,15 @@ describe('getHelp', () => {
 
 	it('should list available topics for unknown topic', async () => {
 		const ctx = createMockContext();
+		mockApiClient.getHelpTopic.mockResolvedValue({ ok: true, data: null });
+		mockApiClient.getHelpTopics.mockResolvedValue({
+			ok: true,
+			data: [
+				{ slug: 'tasks', title: 'Tasks' },
+				{ slug: 'getting_started', title: 'Getting Started' },
+				{ slug: 'validation', title: 'Validation' },
+			],
+		});
 
 		const result = await getHelp({ topic: 'nonexistent' }, ctx);