@vibescope/mcp-server 0.0.1

package/src/cli.ts

@@ -0,0 +1,439 @@
+#!/usr/bin/env node
+
+/**
+ * Vibescope CLI - Enforcement verification tool
+ *
+ * Used by Claude Code Stop hook to verify agent compliance with Vibescope tracking.
+ * Exit codes:
+ *   0 = Compliant (allow exit)
+ *   1 = Non-compliant (block exit, loop back)
+ *   2 = Error (allow exit with warning)
+ */
+
+import { createClient } from '@supabase/supabase-js';
+import { createHash } from 'crypto';
+import { execSync } from 'child_process';
+import { normalizeGitUrl } from './utils.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface AuthContext {
+	userId: string;
+	apiKeyId: string;
+}
+
+export interface VerificationResult {
+	status: 'compliant' | 'non_compliant' | 'no_session' | 'error';
+	reason: string;
+	continuation_prompt?: string;
+	details?: {
+		session_started: boolean;
+		project_id: string | null;
+		project_name: string | null;
+		git_url: string | null;
+		in_progress_tasks: number;
+		tasks_completed_this_session: number;
+		progress_logs_this_session: number;
+		blockers_logged_this_session: number;
+		session_duration_minutes: number | null;
+	};
+}
+
+interface TaskInfo {
+	id: string;
+	title: string;
+	progress_percentage: number;
+}
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+const SUPABASE_URL = process.env.SUPABASE_URL || process.env.PUBLIC_SUPABASE_URL;
+const SUPABASE_SERVICE_KEY = process.env.SUPABASE_SERVICE_KEY;
+const API_KEY = process.env.VIBESCOPE_API_KEY;
+
+// ============================================================================
+// Git URL Detection
+// ============================================================================
+
+export function detectGitUrl(): string | null {
+	try {
+		const url = execSync('git config --get remote.origin.url', {
+			encoding: 'utf8',
+			timeout: 5000,
+			stdio: ['pipe', 'pipe', 'pipe'],
+		}).trim();
+
+		// Normalize: remove .git suffix, convert SSH to HTTPS format
+		return normalizeGitUrl(url);
+	} catch {
+		return null;
+	}
+}
+
+// ============================================================================
+// Authentication (reused from index.ts)
+// ============================================================================
+
+export function hashApiKey(key: string): string {
+	return createHash('sha256').update(key).digest('hex');
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function validateApiKey(
+	supabase: any,
+	apiKey: string
+): Promise<AuthContext | null> {
+	const keyHash = hashApiKey(apiKey);
+
+	const { data, error } = await supabase
+		.from('api_keys')
+		.select('id, user_id')
+		.eq('key_hash', keyHash)
+		.single();
+
+	if (error || !data) {
+		return null;
+	}
+
+	// Cast to expected shape since we're using untyped client
+	const row = data as { id: string; user_id: string };
+
+	return {
+		userId: row.user_id,
+		apiKeyId: row.id,
+	};
+}
+
+// ============================================================================
+// Verification Logic
+// ============================================================================
+
+export async function verify(
+	gitUrl?: string,
+	projectId?: string
+): Promise<VerificationResult> {
+	// Check environment
+	if (!SUPABASE_URL || !SUPABASE_SERVICE_KEY) {
+		return {
+			status: 'error',
+			reason: 'Missing SUPABASE_URL or SUPABASE_SERVICE_KEY environment variables',
+		};
+	}
+
+	if (!API_KEY) {
+		return {
+			status: 'error',
+			reason: 'VIBESCOPE_API_KEY environment variable not set',
+		};
+	}
+
+	const supabase = createClient(SUPABASE_URL, SUPABASE_SERVICE_KEY);
+
+	// Validate API key
+	const auth = await validateApiKey(supabase, API_KEY);
+	if (!auth) {
+		return {
+			status: 'error',
+			reason: 'Invalid VIBESCOPE_API_KEY',
+		};
+	}
+
+	// Auto-detect git URL if not provided
+	if (!gitUrl && !projectId) {
+		gitUrl = detectGitUrl() || undefined;
+	}
+
+	// Find project
+	let projectQuery = supabase
+		.from('projects')
+		.select('id, name, git_url')
+		.eq('user_id', auth.userId);
+
+	if (projectId) {
+		projectQuery = projectQuery.eq('id', projectId);
+	} else if (gitUrl) {
+		projectQuery = projectQuery.eq('git_url', gitUrl);
+	} else {
+		return {
+			status: 'no_session',
+			reason: 'Could not detect git URL and no project_id provided',
+			continuation_prompt:
+				'Could not detect which project you are working on. Please call start_work_session(git_url: "...") with your repository URL.',
+		};
+	}
+
+	const { data: project, error: projectError } = await projectQuery.single();
+
+	if (projectError || !project) {
+		// Project not found - this is OK, might be an untracked repo
+		return {
+			status: 'compliant',
+			reason: `No Vibescope project found for ${gitUrl || projectId}. Untracked repository - exit allowed.`,
+			details: {
+				session_started: false,
+				project_id: null,
+				project_name: null,
+				git_url: gitUrl || null,
+				in_progress_tasks: 0,
+				tasks_completed_this_session: 0,
+				progress_logs_this_session: 0,
+				blockers_logged_this_session: 0,
+				session_duration_minutes: null,
+			},
+		};
+	}
+
+	// Check for agent session
+	const { data: session } = await supabase
+		.from('agent_sessions')
+		.select('id, last_synced_at, created_at')
+		.eq('api_key_id', auth.apiKeyId)
+		.eq('project_id', project.id)
+		.single();
+
+	if (!session) {
+		return {
+			status: 'non_compliant',
+			reason: 'No Vibescope session started for this project',
+			continuation_prompt: `[VIBESCOPE ENFORCEMENT] You have not started a Vibescope work session.
+
+BEFORE you can exit, you MUST call:
+  start_work_session(git_url: "${project.git_url || project.id}")
+
+This registers your session and gives you project context.`,
+			details: {
+				session_started: false,
+				project_id: project.id,
+				project_name: project.name,
+				git_url: project.git_url,
+				in_progress_tasks: 0,
+				tasks_completed_this_session: 0,
+				progress_logs_this_session: 0,
+				blockers_logged_this_session: 0,
+				session_duration_minutes: null,
+			},
+		};
+	}
+
+	const sessionStartTime = new Date(session.created_at);
+	const lastSyncTime = new Date(session.last_synced_at);
+	const now = new Date();
+	const sessionDurationMinutes = Math.round(
+		(now.getTime() - sessionStartTime.getTime()) / 60000
+	);
+
+	// Grace period: if session is less than 1 minute, allow exit
+	if (sessionDurationMinutes < 1) {
+		return {
+			status: 'compliant',
+			reason: 'Very short session (< 1 minute) - exit allowed',
+			details: {
+				session_started: true,
+				project_id: project.id,
+				project_name: project.name,
+				git_url: project.git_url,
+				in_progress_tasks: 0,
+				tasks_completed_this_session: 0,
+				progress_logs_this_session: 0,
+				blockers_logged_this_session: 0,
+				session_duration_minutes: sessionDurationMinutes,
+			},
+		};
+	}
+
+	// Check for in-progress tasks
+	const { data: inProgressTasks } = await supabase
+		.from('tasks')
+		.select('id, title, progress_percentage')
+		.eq('project_id', project.id)
+		.eq('status', 'in_progress');
+
+	const inProgressCount = inProgressTasks?.length || 0;
+
+	if (inProgressCount > 0) {
+		const taskList = (inProgressTasks as TaskInfo[])
+			.map((t) => `  - ${t.title} (${t.progress_percentage}% complete)`)
+			.join('\n');
+
+		return {
+			status: 'non_compliant',
+			reason: `You have ${inProgressCount} task(s) still in_progress`,
+			continuation_prompt: `[VIBESCOPE ENFORCEMENT] You have ${inProgressCount} task(s) still marked as in_progress:
+
+${taskList}
+
+You MUST either:
+1. Complete them: complete_task(task_id: "...", summary: "...")
+2. Log why you're stopping: log_progress(project_id: "${project.id}", summary: "Stopping because...")`,
+			details: {
+				session_started: true,
+				project_id: project.id,
+				project_name: project.name,
+				git_url: project.git_url,
+				in_progress_tasks: inProgressCount,
+				tasks_completed_this_session: 0,
+				progress_logs_this_session: 0,
+				blockers_logged_this_session: 0,
+				session_duration_minutes: sessionDurationMinutes,
+			},
+		};
+	}
+
+	// Check for activity this session
+	const sessionStartIso = sessionStartTime.toISOString();
+
+	const [completedResult, progressResult, blockerResult] = await Promise.all([
+		// Tasks completed after session start
+		supabase
+			.from('tasks')
+			.select('id', { count: 'exact' })
+			.eq('project_id', project.id)
+			.eq('status', 'completed')
+			.gte('completed_at', sessionStartIso),
+
+		// Progress logs by agent after session start
+		supabase
+			.from('progress_logs')
+			.select('id', { count: 'exact' })
+			.eq('project_id', project.id)
+			.eq('created_by', 'agent')
+			.gte('created_at', sessionStartIso),
+
+		// Blockers logged by agent after session start
+		supabase
+			.from('blockers')
+			.select('id', { count: 'exact' })
+			.eq('project_id', project.id)
+			.eq('created_by', 'agent')
+			.gte('created_at', sessionStartIso),
+	]);
+
+	const tasksCompleted = completedResult.count || 0;
+	const progressLogsCount = progressResult.count || 0;
+	const blockersLogged = blockerResult.count || 0;
+
+	// Check if any tracked work was done
+	const anyWorkTracked =
+		tasksCompleted > 0 || progressLogsCount > 0 || blockersLogged > 0;
+
+	if (!anyWorkTracked && sessionDurationMinutes >= 5) {
+		return {
+			status: 'non_compliant',
+			reason: `Session active for ${sessionDurationMinutes} minutes but no work was tracked`,
+			continuation_prompt: `[VIBESCOPE ENFORCEMENT] Your session has been active for ${sessionDurationMinutes} minutes but no work was tracked.
+
+The human is watching the dashboard and will see an empty session.
+
+You MUST either:
+1. Pick a task and work on it: get_next_task(project_id: "${project.id}")
+2. Log why you did nothing: log_progress(project_id: "${project.id}", summary: "No work done because...")`,
+			details: {
+				session_started: true,
+				project_id: project.id,
+				project_name: project.name,
+				git_url: project.git_url,
+				in_progress_tasks: 0,
+				tasks_completed_this_session: tasksCompleted,
+				progress_logs_this_session: progressLogsCount,
+				blockers_logged_this_session: blockersLogged,
+				session_duration_minutes: sessionDurationMinutes,
+			},
+		};
+	}
+
+	// All checks passed - compliant!
+	return {
+		status: 'compliant',
+		reason: 'All tracked work completed properly',
+		details: {
+			session_started: true,
+			project_id: project.id,
+			project_name: project.name,
+			git_url: project.git_url,
+			in_progress_tasks: 0,
+			tasks_completed_this_session: tasksCompleted,
+			progress_logs_this_session: progressLogsCount,
+			blockers_logged_this_session: blockersLogged,
+			session_duration_minutes: sessionDurationMinutes,
+		},
+	};
+}
+
+// ============================================================================
+// CLI Entry Point
+// ============================================================================
+
+async function main() {
+	const args = process.argv.slice(2);
+	const command = args[0];
+
+	if (command === 'verify') {
+		// Parse --git-url and --project-id flags
+		let gitUrl: string | undefined;
+		let projectId: string | undefined;
+
+		for (let i = 1; i < args.length; i++) {
+			if (args[i] === '--git-url' && args[i + 1]) {
+				gitUrl = args[++i];
+			} else if (args[i] === '--project-id' && args[i + 1]) {
+				projectId = args[++i];
+			}
+		}
+
+		const result = await verify(gitUrl, projectId);
+		console.log(JSON.stringify(result, null, 2));
+
+		// Exit codes: 0=compliant, 1=non-compliant, 2=error
+		if (result.status === 'compliant') {
+			process.exit(0);
+		} else if (result.status === 'error') {
+			process.exit(2);
+		} else {
+			process.exit(1);
+		}
+	} else if (command === 'help' || command === '--help' || command === '-h') {
+		console.log(`
+Vibescope CLI - Enforcement verification tool
+
+Usage:
+  vibescope-cli verify [options]    Check Vibescope compliance before exit
+
+Options:
+  --git-url <url>       Git repository URL (auto-detected if not provided)
+  --project-id <id>     Vibescope project UUID
+
+Exit Codes:
+  0  Compliant - agent can exit
+  1  Non-compliant - agent should continue work
+  2  Error - allow exit with warning
+
+Environment Variables:
+  VIBESCOPE_API_KEY       Required - Your Vibescope API key
+  SUPABASE_URL            Required - Supabase project URL
+  SUPABASE_SERVICE_KEY    Required - Supabase service role key
+`);
+		process.exit(0);
+	} else {
+		console.error('Usage: vibescope-cli verify [--git-url <url>] [--project-id <id>]');
+		console.error('       vibescope-cli --help');
+		process.exit(2);
+	}
+}
+
+// Only run main when executed directly (not when imported for testing)
+const isMainModule = import.meta.url === `file://${process.argv[1]?.replace(/\\/g, '/')}`;
+if (isMainModule || process.argv[1]?.endsWith('cli.js')) {
+	main().catch((err) => {
+		console.error(
+			JSON.stringify({
+				status: 'error',
+				reason: err instanceof Error ? err.message : 'Unknown error',
+			})
+		);
+		process.exit(2);
+	});
+}

package/src/handlers/__test-utils__.ts

@@ -0,0 +1,217 @@
+/**
+ * Shared Test Utilities
+ *
+ * Common mock factories and test helpers used across handler tests.
+ * This eliminates ~85 lines of duplicate code per test file.
+ */
+
+import { vi } from 'vitest';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { HandlerContext, TokenUsage } from './types.js';
+
+// ============================================================================
+// Mock Supabase Factory
+// ============================================================================
+
+export interface MockSupabaseOverrides {
+	selectResult?: { data: unknown; error: unknown };
+	insertResult?: { data: unknown; error: unknown };
+	updateResult?: { data: unknown; error: unknown };
+	deleteResult?: { data: unknown; error: unknown };
+	sessionsResult?: { data: unknown; error: unknown };
+}
+
+/**
+ * Create a mock Supabase client for testing.
+ *
+ * The mock tracks which operation is being performed and returns
+ * the appropriate result from overrides.
+ *
+ * @example
+ * ```ts
+ * const supabase = createMockSupabase({
+ *   insertResult: { data: { id: 'new-id' }, error: null }
+ * });
+ * ```
+ */
+export function createMockSupabase(overrides: MockSupabaseOverrides = {}) {
+	const defaultResult = { data: null, error: null };
+
+	// Use an object to track state so it persists across all mock function calls
+	const state = {
+		currentOperation: 'select' as string,
+		currentTable: '' as string,
+		insertThenSelect: false,
+		updateCalled: false,
+	};
+
+	const mock = {
+		from: vi.fn((table: string) => {
+			state.currentTable = table;
+			// Reset state for new query chain
+			state.currentOperation = 'select';
+			state.insertThenSelect = false;
+			state.updateCalled = false;
+			return mock;
+		}),
+		select: vi.fn(() => {
+			if (state.currentOperation === 'insert') {
+				state.insertThenSelect = true;
+			} else if (!state.updateCalled) {
+				state.currentOperation = 'select';
+				state.insertThenSelect = false;
+			}
+			return mock;
+		}),
+		insert: vi.fn(() => {
+			state.currentOperation = 'insert';
+			state.insertThenSelect = false;
+			return mock;
+		}),
+		update: vi.fn(() => {
+			state.currentOperation = 'update';
+			state.updateCalled = true;
+			state.insertThenSelect = false;
+			return mock;
+		}),
+		delete: vi.fn(() => {
+			state.currentOperation = 'delete';
+			state.insertThenSelect = false;
+			return mock;
+		}),
+		eq: vi.fn().mockReturnThis(),
+		neq: vi.fn().mockReturnThis(),
+		in: vi.fn().mockReturnThis(),
+		is: vi.fn().mockReturnThis(),
+		not: vi.fn().mockReturnThis(),
+		or: vi.fn().mockReturnThis(),
+		gt: vi.fn().mockReturnThis(),
+		gte: vi.fn().mockReturnThis(),
+		lte: vi.fn().mockReturnThis(),
+		lt: vi.fn().mockReturnThis(),
+		order: vi.fn().mockReturnThis(),
+		limit: vi.fn().mockReturnThis(),
+		single: vi.fn(() => {
+			if (state.currentOperation === 'insert' || state.insertThenSelect) {
+				return Promise.resolve(overrides.insertResult ?? defaultResult);
+			}
+			if (state.updateCalled) {
+				return Promise.resolve(overrides.updateResult ?? defaultResult);
+			}
+			if (state.currentOperation === 'select') {
+				return Promise.resolve(overrides.selectResult ?? defaultResult);
+			}
+			if (state.currentOperation === 'update') {
+				return Promise.resolve(overrides.updateResult ?? defaultResult);
+			}
+			return Promise.resolve(defaultResult);
+		}),
+		maybeSingle: vi.fn(() => {
+			return Promise.resolve(overrides.selectResult ?? defaultResult);
+		}),
+		then: vi.fn((resolve: (value: unknown) => void) => {
+			// Handle special table cases
+			if (state.currentTable === 'agent_sessions' && overrides.sessionsResult) {
+				return Promise.resolve(overrides.sessionsResult).then(resolve);
+			}
+
+			if (state.currentOperation === 'insert' || state.insertThenSelect) {
+				return Promise.resolve(overrides.insertResult ?? defaultResult).then(resolve);
+			}
+			if (state.updateCalled) {
+				return Promise.resolve(overrides.updateResult ?? defaultResult).then(resolve);
+			}
+			if (state.currentOperation === 'select') {
+				return Promise.resolve(overrides.selectResult ?? defaultResult).then(resolve);
+			}
+			if (state.currentOperation === 'update') {
+				return Promise.resolve(overrides.updateResult ?? defaultResult).then(resolve);
+			}
+			if (state.currentOperation === 'delete') {
+				return Promise.resolve(overrides.deleteResult ?? defaultResult).then(resolve);
+			}
+			return Promise.resolve(defaultResult).then(resolve);
+		}),
+	};
+
+	return mock as unknown as SupabaseClient;
+}
+
+// ============================================================================
+// Mock Handler Context Factory
+// ============================================================================
+
+export interface MockContextOptions {
+	sessionId?: string | null;
+	userId?: string;
+	apiKeyId?: string;
+	instanceId?: string;
+	persona?: string;
+}
+
+/**
+ * Create a mock HandlerContext for testing.
+ *
+ * @example
+ * ```ts
+ * const ctx = createMockContext(supabase, { sessionId: 'test-session' });
+ * ```
+ */
+export function createMockContext(
+	supabase: SupabaseClient,
+	options: MockContextOptions = {}
+): HandlerContext {
+	const defaultTokenUsage: TokenUsage = {
+		callCount: 5,
+		totalTokens: 2500,
+		byTool: {},
+		byModel: {},
+		currentModel: null,
+	};
+
+	const sessionId = 'sessionId' in options ? (options.sessionId ?? null) : 'session-123';
+
+	return {
+		supabase,
+		auth: {
+			userId: options.userId ?? 'user-123',
+			apiKeyId: options.apiKeyId ?? 'api-key-123',
+			scope: 'personal' as const,
+		},
+		session: {
+			instanceId: options.instanceId ?? 'instance-abc',
+			currentSessionId: sessionId,
+			currentPersona: options.persona ?? 'Wave',
+			tokenUsage: defaultTokenUsage,
+		},
+		updateSession: vi.fn(),
+	};
+}
+
+// ============================================================================
+// Test Data Generators
+// ============================================================================
+
+/**
+ * Generate a valid UUID for testing.
+ */
+export function testUUID(): string {
+	return '123e4567-e89b-12d3-a456-426614174000';
+}
+
+/**
+ * Generate a random-ish UUID for testing (deterministic based on seed).
+ */
+export function testUUIDSeeded(seed: number): string {
+	const hex = seed.toString(16).padStart(8, '0');
+	return `${hex}-e89b-12d3-a456-426614174000`;
+}
+
+/**
+ * Create a mock timestamp for consistent testing.
+ */
+export function testTimestamp(offsetMinutes = 0): string {
+	const date = new Date('2025-01-14T12:00:00Z');
+	date.setMinutes(date.getMinutes() + offsetMinutes);
+	return date.toISOString();
+}