@vibescope/mcp-server 0.2.3 → 0.2.4

package/src/handlers/types.test.ts

@@ -0,0 +1,259 @@
+import { describe, it, expect } from 'vitest';
+import {
+	success,
+	error,
+	isSuccess,
+	isError,
+	type HandlerResult,
+	type SuccessResult,
+	type ErrorResult,
+} from './types.js';
+
+describe('success', () => {
+	it('should create a success result with simple data', () => {
+		const result = success({ message: 'hello' });
+		expect(result.result).toEqual({ message: 'hello' });
+		expect(result.isError).toBeUndefined();
+	});
+
+	it('should create a success result with string data', () => {
+		const result = success('test string');
+		expect(result.result).toBe('test string');
+	});
+
+	it('should create a success result with number data', () => {
+		const result = success(42);
+		expect(result.result).toBe(42);
+	});
+
+	it('should create a success result with boolean data', () => {
+		const result = success(true);
+		expect(result.result).toBe(true);
+	});
+
+	it('should create a success result with null data', () => {
+		const result = success(null);
+		expect(result.result).toBeNull();
+	});
+
+	it('should create a success result with undefined data', () => {
+		const result = success(undefined);
+		expect(result.result).toBeUndefined();
+	});
+
+	it('should create a success result with array data', () => {
+		const result = success([1, 2, 3]);
+		expect(result.result).toEqual([1, 2, 3]);
+	});
+
+	it('should create a success result with nested object data', () => {
+		const data = {
+			tasks: [{ id: '1', title: 'Task 1' }],
+			total_count: 1,
+			metadata: { page: 1, limit: 10 },
+		};
+		const result = success(data);
+		expect(result.result).toEqual(data);
+	});
+
+	it('should preserve type information', () => {
+		interface TaskData {
+			id: string;
+			title: string;
+		}
+		const result: SuccessResult<TaskData> = success({ id: '1', title: 'Test' });
+		expect(result.result.id).toBe('1');
+		expect(result.result.title).toBe('Test');
+	});
+});
+
+describe('error', () => {
+	it('should create an error result with message only', () => {
+		const result = error('Something went wrong');
+		expect(result.result.error).toBe('Something went wrong');
+		expect(result.isError).toBe(true);
+	});
+
+	it('should create an error result with message and details', () => {
+		const result = error('Validation failed', { field: 'title', reason: 'too long' });
+		expect(result.result.error).toBe('Validation failed');
+		expect(result.result.field).toBe('title');
+		expect(result.result.reason).toBe('too long');
+		expect(result.isError).toBe(true);
+	});
+
+	it('should handle empty details object', () => {
+		const result = error('Error message', {});
+		expect(result.result.error).toBe('Error message');
+		expect(result.isError).toBe(true);
+	});
+
+	it('should handle complex details', () => {
+		const result = error('Multiple errors', {
+			errors: ['error1', 'error2'],
+			count: 2,
+			nested: { key: 'value' },
+		});
+		expect(result.result.error).toBe('Multiple errors');
+		expect(result.result.errors).toEqual(['error1', 'error2']);
+		expect(result.result.count).toBe(2);
+		expect(result.result.nested).toEqual({ key: 'value' });
+	});
+
+	it('should always set isError to true', () => {
+		const result1 = error('error1');
+		const result2 = error('error2', { detail: 'info' });
+		expect(result1.isError).toBe(true);
+		expect(result2.isError).toBe(true);
+	});
+});
+
+describe('isSuccess', () => {
+	it('should return true for success results', () => {
+		const result = success({ data: 'test' });
+		expect(isSuccess(result)).toBe(true);
+	});
+
+	it('should return true for success results with various data types', () => {
+		expect(isSuccess(success('string'))).toBe(true);
+		expect(isSuccess(success(123))).toBe(true);
+		expect(isSuccess(success(null))).toBe(true);
+		expect(isSuccess(success([]))).toBe(true);
+		expect(isSuccess(success({}))).toBe(true);
+	});
+
+	it('should return false for error results', () => {
+		const result = error('Something failed');
+		expect(isSuccess(result)).toBe(false);
+	});
+
+	it('should return false for error results with details', () => {
+		const result = error('Validation error', { field: 'name' });
+		expect(isSuccess(result)).toBe(false);
+	});
+
+	it('should narrow type correctly for success', () => {
+		const result: HandlerResult<{ id: string }> = success({ id: '123' });
+		if (isSuccess(result)) {
+			// TypeScript should know result.result is { id: string }
+			expect(result.result.id).toBe('123');
+		}
+	});
+
+	it('should work with explicitly typed results', () => {
+		const successResult: SuccessResult<number> = { result: 42 };
+		const errorResult: ErrorResult = { result: { error: 'fail' }, isError: true };
+
+		expect(isSuccess(successResult)).toBe(true);
+		expect(isSuccess(errorResult)).toBe(false);
+	});
+});
+
+describe('isError', () => {
+	it('should return true for error results', () => {
+		const result = error('Something failed');
+		expect(isError(result)).toBe(true);
+	});
+
+	it('should return true for error results with details', () => {
+		const result = error('Validation error', { field: 'name', code: 'INVALID' });
+		expect(isError(result)).toBe(true);
+	});
+
+	it('should return false for success results', () => {
+		const result = success({ data: 'test' });
+		expect(isError(result)).toBe(false);
+	});
+
+	it('should return false for success results with various data types', () => {
+		expect(isError(success('string'))).toBe(false);
+		expect(isError(success(123))).toBe(false);
+		expect(isError(success(null))).toBe(false);
+		expect(isError(success([]))).toBe(false);
+		expect(isError(success({}))).toBe(false);
+	});
+
+	it('should narrow type correctly for error', () => {
+		const result: HandlerResult<unknown> = error('Task not found');
+		if (isError(result)) {
+			// TypeScript should know result.result.error is string
+			expect(result.result.error).toBe('Task not found');
+		}
+	});
+
+	it('should work with explicitly typed results', () => {
+		const successResult: SuccessResult<number> = { result: 42 };
+		const errorResult: ErrorResult = { result: { error: 'fail' }, isError: true };
+
+		expect(isError(successResult)).toBe(false);
+		expect(isError(errorResult)).toBe(true);
+	});
+});
+
+describe('HandlerResult type usage', () => {
+	it('should work with discriminated union pattern', () => {
+		function processResult(result: HandlerResult<string>): string {
+			if (isSuccess(result)) {
+				return `Success: ${result.result}`;
+			} else {
+				return `Error: ${result.result.error}`;
+			}
+		}
+
+		expect(processResult(success('hello'))).toBe('Success: hello');
+		expect(processResult(error('failed'))).toBe('Error: failed');
+	});
+
+	it('should handle async handler patterns', async () => {
+		async function mockHandler(): Promise<HandlerResult<{ id: string }>> {
+			return success({ id: '123' });
+		}
+
+		const result = await mockHandler();
+		expect(isSuccess(result)).toBe(true);
+		if (isSuccess(result)) {
+			expect(result.result.id).toBe('123');
+		}
+	});
+
+	it('should handle error handler patterns', async () => {
+		async function mockErrorHandler(): Promise<HandlerResult<{ id: string }>> {
+			return error('Not found', { id: '123' });
+		}
+
+		const result = await mockErrorHandler();
+		expect(isError(result)).toBe(true);
+		if (isError(result)) {
+			expect(result.result.error).toBe('Not found');
+			expect(result.result.id).toBe('123');
+		}
+	});
+});
+
+describe('edge cases', () => {
+	it('should handle result with isError explicitly set to false', () => {
+		const result: SuccessResult<string> = { result: 'data', isError: false };
+		expect(isSuccess(result)).toBe(true);
+		expect(isError(result)).toBe(false);
+	});
+
+	it('should handle result without isError property', () => {
+		const result: SuccessResult<string> = { result: 'data' };
+		expect(isSuccess(result)).toBe(true);
+		expect(isError(result)).toBe(false);
+	});
+
+	it('should handle success with error-like data', () => {
+		// A success result that happens to contain an error message in its data
+		const result = success({ error: 'This is not an error result', data: 'some data' });
+		expect(isSuccess(result)).toBe(true);
+		expect(isError(result)).toBe(false);
+	});
+
+	it('should handle empty string error message', () => {
+		const result = error('');
+		expect(result.result.error).toBe('');
+		expect(result.isError).toBe(true);
+		expect(isError(result)).toBe(true);
+	});
+});

package/src/templates/agent-guidelines.ts

@@ -0,0 +1,210 @@
+/**
+ * Agent Guidelines Template
+ *
+ * This template contains the essential CLAUDE.md content that should be included
+ * in every project using Vibescope for agent tracking. These guidelines ensure
+ * agents follow proper workflows and maintain visibility.
+ */
+
+export const AGENT_GUIDELINES_TEMPLATE = `# Vibescope Agent Guidelines
+
+## Quick Start
+
+\`\`\`
+start_work_session(git_url: "https://github.com/YOUR/REPO", model: "opus")
+\`\`\`
+
+**IMPORTANT:** Always pass your model (opus/sonnet/haiku) to enable cost tracking. Check your system prompt for "You are powered by the model named..." to determine your model.
+
+This returns your persona, project info, and \`next_task\`. Start working immediately.
+
+## CRITICAL: MCP Connection Required
+
+**If the Vibescope MCP server fails to connect, you MUST end your session immediately.**
+
+### Why This Is Non-Negotiable
+
+Working without MCP connection causes:
+- **No progress visibility** - Humans can't see what you're doing
+- **Lost work tracking** - Tasks aren't tracked, time is wasted
+- **Workflow violations** - Other agents may conflict with your work
+- **Dashboard confusion** - Project state becomes inconsistent
+
+### Connection Failure Handling
+
+**If \`start_work_session\` fails or returns an error:**
+
+1. **Do NOT proceed with any work**
+2. **Inform the user** that MCP connection failed
+3. **End the session** - do not attempt workarounds
+4. **Provide troubleshooting steps:**
+   - Check if MCP server is configured: \`claude mcp list\`
+   - Verify API key is set: check \`.mcp.json\` or environment
+   - Restart Claude Code after fixing configuration
+
+**Example error responses you might see:**
+\`\`\`
+Error: Failed to start session
+Error: VIBESCOPE_API_KEY not set
+Error: Network error connecting to Vibescope API
+Error: MCP server 'vibescope' not found
+\`\`\`
+
+### Recovery Steps
+
+If MCP connection fails, tell the user:
+
+\`\`\`
+MCP connection to Vibescope failed. I cannot proceed without task tracking.
+
+To fix:
+1. Run: claude mcp list (verify vibescope is configured)
+2. Check API key: ensure VIBESCOPE_API_KEY is set
+3. Restart Claude Code
+4. Try again with: start_work_session(git_url: "...")
+
+I am ending this session to prevent untracked work.
+\`\`\`
+
+**Never "work around" a broken MCP connection.** The whole point of Vibescope is visibility and coordination. Working without it defeats the purpose.
+
+## Core Workflow
+
+1. **Start session** → \`start_work_session(git_url, model)\` - Always include your model!
+2. **Mark task in progress** → \`update_task(task_id, status: "in_progress")\` - Returns git workflow instructions!
+3. **Set up worktree** → Create isolated worktree for this task (see Git Workflow below)
+4. **Update progress** → \`update_task(task_id, progress_percentage: 50, progress_note: "...")\`
+5. **Complete task** → \`complete_task(task_id, summary: "...")\` - **MANDATORY, see below!**
+6. **Clean up** → Remove worktree, then start next task immediately
+
+## CRITICAL: Always Call complete_task (MANDATORY)
+
+**You MUST call \`complete_task()\` when you finish a task.** This is not optional.
+
+### When to Call complete_task
+
+Call \`complete_task()\` immediately after:
+- ✅ Creating and pushing a PR
+- ✅ Merging changes (for trunk-based workflow)
+- ✅ Finishing any unit of work, even if no code changes
+
+**Do NOT wait for:**
+- ❌ PR to be reviewed/merged (that's what validation is for)
+- ❌ User confirmation
+- ❌ "Perfect" summary - a brief summary is fine
+
+### The Rule
+
+\`\`\`
+PR created + pushed → complete_task() → THEN worry about next steps
+\`\`\`
+
+**If you create a PR and don't call \`complete_task()\`, you have failed the workflow.**
+
+## CRITICAL: Git Worktrees for Multi-Agent
+
+When multiple agents share a repository, you **MUST** use git worktrees to prevent conflicts.
+
+**Before starting ANY task:**
+\`\`\`bash
+# For git-flow: ensure you're on develop first, then create worktree
+git checkout develop
+git pull origin develop
+git worktree add ../worktree-<task-short-id> -b feature/<task-id>-<title>
+cd ../worktree-<task-short-id>
+\`\`\`
+
+**After task is merged:**
+\`\`\`bash
+git worktree remove ../worktree-<task-short-id>
+\`\`\`
+
+**Why?** Branch switching in shared repos causes file conflicts between agents. Worktrees provide isolated directories.
+
+Run \`get_help("git")\` for full worktree documentation.
+
+## CRITICAL: Never Ask Permission
+
+**You must NEVER:**
+- Ask "Should I continue to the next task?" → Just continue
+- Ask "Should I clear my context?" → Just clear it
+- Ask "What should I do next?" → Check \`next_task\` or use fallback activities
+- Say "All tasks are done, let me know what to do" → Use \`get_next_task\` or start fallback activity
+- Wait for confirmation before clearing context → Just do it
+
+**You must ALWAYS:**
+- Call \`complete_task()\` immediately after creating/pushing a PR - this is non-negotiable
+- Immediately start the next task after completing one
+- Clear context and restart session automatically when needed
+- Keep working until there are genuinely no tasks and no fallback activities
+
+## Continuous Work
+
+**IMPORTANT: Never stop working!** When you complete a task:
+1. \`complete_task\` returns \`next_task\` → Start it immediately
+2. No \`next_task\`? → Call \`get_next_task(project_id)\`
+3. Still no tasks? → Start a \`fallback_activity\` (code_review, security_review, etc.)
+
+**When context grows large or responses slow down:**
+1. Run \`/clear\` to reset conversation
+2. Immediately call \`start_work_session(git_url, model)\` to reload context
+3. Continue with \`next_task\` from the response
+
+**Do NOT ask the user if you should clear context. Just do it.** The dashboard tracks all your progress, so nothing is lost when you clear.
+
+## Need Help?
+
+Use \`get_help(topic)\` for detailed guidance:
+
+| Topic | Description |
+|-------|-------------|
+| \`getting_started\` | Basic workflow overview |
+| \`tasks\` | Working on tasks, progress tracking |
+| \`validation\` | Cross-agent task validation |
+| \`deployment\` | Deployment coordination |
+| \`git\` | Git workflow configuration |
+| \`blockers\` | Handling blockers |
+| \`milestones\` | Breaking down complex tasks |
+| \`fallback\` | Background activities when idle |
+| \`session\` | Session management |
+| \`topics\` | List all available topics |
+
+## MCP Server Not Connected?
+
+### Quick Setup (Claude Code)
+
+\`\`\`bash
+claude mcp add vibescope npx @vibescope/mcp-server@latest \\
+  --env VIBESCOPE_API_KEY=your_key
+\`\`\`
+
+### Manual Setup
+
+1. Copy \`.mcp.json.example\` to \`.mcp.json\`
+2. Get \`VIBESCOPE_API_KEY\` from https://vibescope.dev/dashboard/settings
+3. Restart Claude Code
+`;
+
+/**
+ * Get the agent guidelines template
+ * @returns The full agent guidelines markdown template
+ */
+export function getAgentGuidelinesTemplate(): string {
+	return AGENT_GUIDELINES_TEMPLATE;
+}
+
+/**
+ * Get a summary of the agent guidelines for inclusion in responses
+ * @returns A brief summary of key guidelines
+ */
+export function getAgentGuidelinesSummary(): string {
+	return `## Essential Agent Guidelines
+
+1. **MCP Connection Required** - If start_work_session fails, END SESSION IMMEDIATELY
+2. **Always call complete_task()** - After creating a PR, call complete_task() right away
+3. **Use git worktrees** - Create worktrees for each task to avoid conflicts
+4. **Never ask permission** - Just continue working, clear context when needed
+5. **Continuous work** - Never stop; use get_next_task or fallback activities
+
+For full guidelines, create a \`.claude/CLAUDE.md\` file in your project with the agent guidelines template.`;
+}