@vibescope/mcp-server 0.3.0 → 0.3.3

package/src/api-client/decisions.ts

@@ -0,0 +1,87 @@
+/**
+ * Decisions API Methods
+ *
+ * Methods for decision tracking:
+ * - getDecisions: List decisions for a project
+ * - getDecision: Get a single decision
+ * - logDecision: Log a new decision
+ * - deleteDecision: Delete a decision
+ * - getDecisionsStats: Get decision statistics
+ */
+
+import type { ApiResponse, ProxyFn } from './types.js';
+
+export interface DecisionsMethods {
+	getDecisions(projectId: string, options?: {
+		limit?: number;
+		offset?: number;
+		search_query?: string;
+	}): Promise<ApiResponse<{
+		decisions: Array<{
+			id: string;
+			title: string;
+			description: string;
+			rationale?: string;
+			alternatives_considered?: string[];
+			created_at: string;
+		}>;
+		total_count?: number;
+		has_more?: boolean;
+	}>>;
+
+	getDecision(decisionId: string): Promise<ApiResponse<{
+		decision: {
+			id: string;
+			title: string;
+			description: string;
+			rationale?: string;
+			alternatives_considered?: string[];
+			created_at: string;
+		};
+	}>>;
+
+	logDecision(projectId: string, params: {
+		title: string;
+		description: string;
+		rationale?: string;
+		alternatives_considered?: string[];
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		decision_id: string;
+	}>>;
+
+	deleteDecision(decisionId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>>;
+
+	getDecisionsStats(projectId: string): Promise<ApiResponse<{
+		total: number;
+	}>>;
+}
+
+export function createDecisionsMethods(proxy: ProxyFn): DecisionsMethods {
+	return {
+		async getDecisions(projectId, options) {
+			return proxy('get_decisions', { project_id: projectId, ...options });
+		},
+
+		async getDecision(decisionId) {
+			return proxy('get_decision', { decision_id: decisionId });
+		},
+
+		async logDecision(projectId, params, sessionId) {
+			return proxy('log_decision', {
+				project_id: projectId,
+				...params
+			}, sessionId ? { session_id: sessionId } : undefined);
+		},
+
+		async deleteDecision(decisionId) {
+			return proxy('delete_decision', { decision_id: decisionId });
+		},
+
+		async getDecisionsStats(projectId) {
+			return proxy('get_decisions_stats', { project_id: projectId });
+		}
+	};
+}

package/src/api-client/discovery.ts

@@ -0,0 +1,81 @@
+/**
+ * Discovery API Methods
+ *
+ * Methods for knowledge and help discovery:
+ * - queryKnowledgeBase: Query aggregated project knowledge
+ * - getHelpTopic: Get help for a specific topic
+ * - getHelpTopics: List all help topics
+ */
+
+import type { ApiResponse, RequestFn } from './types.js';
+
+export interface DiscoveryMethods {
+	queryKnowledgeBase(projectId: string, params?: {
+		scope?: 'summary' | 'detailed';
+		categories?: Array<'findings' | 'qa' | 'decisions' | 'completed_tasks' | 'blockers' | 'progress'>;
+		limit?: number;
+		search_query?: string;
+	}): Promise<ApiResponse<{
+		findings?: Array<{
+			id: string;
+			title: string;
+			category: string;
+			severity: string;
+		}>;
+		qa?: Array<{
+			id: string;
+			question: string;
+			answer?: string;
+		}>;
+		decisions?: Array<{
+			id: string;
+			title: string;
+			description?: string;
+		}>;
+		completed_tasks?: Array<{
+			id: string;
+			title: string;
+			completed_at: string;
+		}>;
+		blockers?: Array<{
+			id: string;
+			description: string;
+			status: string;
+		}>;
+		progress?: Array<{
+			id: string;
+			note: string;
+			created_at: string;
+		}>;
+	}>>;
+
+	getHelpTopic(slug: string): Promise<ApiResponse<{
+		topic: {
+			slug: string;
+			title: string;
+			content: string;
+		};
+	}>>;
+
+	getHelpTopics(): Promise<ApiResponse<Array<{
+		slug: string;
+		title: string;
+		description?: string;
+	}>>>;
+}
+
+export function createDiscoveryMethods(request: RequestFn): DiscoveryMethods {
+	return {
+		async queryKnowledgeBase(projectId, params) {
+			return request('POST', `/api/mcp/projects/${projectId}/knowledge`, params || {});
+		},
+
+		async getHelpTopic(slug) {
+			return request('GET', `/api/mcp/help/${slug}`);
+		},
+
+		async getHelpTopics() {
+			return request('GET', '/api/mcp/help');
+		}
+	};
+}

package/src/api-client/ideas.ts

@@ -0,0 +1,112 @@
+/**
+ * Ideas API Methods
+ *
+ * Methods for idea management:
+ * - getIdeas: List ideas for a project
+ * - getIdea: Get a single idea
+ * - addIdea: Create a new idea
+ * - updateIdea: Update an idea
+ * - deleteIdea: Delete an idea
+ * - convertIdeaToTask: Convert an idea to a task
+ */
+
+import type { ApiResponse, ProxyFn } from './types.js';
+
+export interface IdeasMethods {
+	getIdeas(projectId: string, params?: {
+		status?: string;
+		limit?: number;
+		offset?: number;
+		search_query?: string;
+	}): Promise<ApiResponse<{
+		ideas: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			status: string;
+			doc_url?: string;
+			created_at: string;
+		}>;
+		total_count?: number;
+		has_more?: boolean;
+	}>>;
+
+	getIdea(ideaId: string): Promise<ApiResponse<{
+		idea: {
+			id: string;
+			title: string;
+			description?: string;
+			status: string;
+			doc_url?: string;
+			created_at: string;
+		};
+	}>>;
+
+	addIdea(projectId: string, params: {
+		title: string;
+		description?: string;
+		status?: string;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		idea_id: string;
+	}>>;
+
+	updateIdea(ideaId: string, updates: {
+		title?: string;
+		description?: string;
+		status?: string;
+		doc_url?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		idea_id: string;
+	}>>;
+
+	deleteIdea(ideaId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>>;
+
+	convertIdeaToTask(ideaId: string, params?: {
+		priority?: number;
+		estimated_minutes?: number;
+		update_status?: boolean;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		task_id?: string;
+		task_title?: string;
+		idea_id?: string;
+		idea_status?: string;
+		message?: string;
+		error?: string;
+	}>>;
+}
+
+export function createIdeasMethods(proxy: ProxyFn): IdeasMethods {
+	return {
+		async getIdeas(projectId, params) {
+			return proxy('get_ideas', { project_id: projectId, ...params });
+		},
+
+		async getIdea(ideaId) {
+			return proxy('get_idea', { idea_id: ideaId });
+		},
+
+		async addIdea(projectId, params, sessionId) {
+			return proxy('add_idea', {
+				project_id: projectId,
+				...params
+			}, sessionId ? { session_id: sessionId } : undefined);
+		},
+
+		async updateIdea(ideaId, updates) {
+			return proxy('update_idea', { idea_id: ideaId, ...updates });
+		},
+
+		async deleteIdea(ideaId) {
+			return proxy('delete_idea', { idea_id: ideaId });
+		},
+
+		async convertIdeaToTask(ideaId, params) {
+			return proxy('convert_idea_to_task', { idea_id: ideaId, ...params });
+		}
+	};
+}

package/src/api-client/index.ts

@@ -0,0 +1,378 @@
+/**
+ * Vibescope API Client
+ *
+ * HTTP client for communicating with the Vibescope API.
+ * All database operations are handled server-side through these endpoints.
+ *
+ * This module composes domain-specific API methods into a unified client.
+ */
+
+import type { ApiClientConfig, ApiResponse, RetryConfig, RequestFn, ProxyFn } from './types.js';
+import { createSessionMethods, type SessionMethods } from './session.js';
+import { createProjectMethods, type ProjectMethods } from './project.js';
+import { createBlockersMethods, type BlockersMethods } from './blockers.js';
+import { createCostMethods, type CostMethods } from './cost.js';
+import { createWorktreesMethods, type WorktreesMethods } from './worktrees.js';
+import { createDiscoveryMethods, type DiscoveryMethods } from './discovery.js';
+import { createDecisionsMethods, type DecisionsMethods } from './decisions.js';
+import { createIdeasMethods, type IdeasMethods } from './ideas.js';
+import { createTasksMethods, type TasksMethods } from './tasks.js';
+
+// Re-export types
+export type { ApiClientConfig, ApiResponse, RetryConfig, RequestFn, ProxyFn } from './types.js';
+export type { SessionMethods } from './session.js';
+export type { ProjectMethods } from './project.js';
+export type { BlockersMethods } from './blockers.js';
+export type { CostMethods } from './cost.js';
+export type { WorktreesMethods } from './worktrees.js';
+export type { DiscoveryMethods } from './discovery.js';
+export type { DecisionsMethods } from './decisions.js';
+export type { IdeasMethods } from './ideas.js';
+export type { TasksMethods } from './tasks.js';
+
+const DEFAULT_API_URL = 'https://vibescope.dev';
+
+// Retry configuration defaults
+const DEFAULT_RETRY_STATUS_CODES = [429, 503, 504];
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BASE_DELAY_MS = 1000;
+const DEFAULT_MAX_DELAY_MS = 30000;
+
+/**
+ * Calculate delay for exponential backoff with jitter
+ */
+function calculateBackoffDelay(
+	attempt: number,
+	baseDelayMs: number,
+	maxDelayMs: number,
+	retryAfter?: number
+): number {
+	if (retryAfter !== undefined && retryAfter > 0) {
+		return Math.min(retryAfter * 1000, maxDelayMs);
+	}
+	const exponentialDelay = baseDelayMs * Math.pow(2, attempt);
+	const jitter = Math.random() * 0.3 * exponentialDelay;
+	return Math.min(exponentialDelay + jitter, maxDelayMs);
+}
+
+/**
+ * Sleep for a specified duration
+ */
+function sleep(ms: number): Promise<void> {
+	return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Combined interface for all API methods
+ */
+export interface VibescopeApiClientMethods
+	extends SessionMethods,
+		ProjectMethods,
+		BlockersMethods,
+		CostMethods,
+		WorktreesMethods,
+		DiscoveryMethods,
+		DecisionsMethods,
+		IdeasMethods,
+		TasksMethods {}
+
+export class VibescopeApiClient implements VibescopeApiClientMethods {
+	private apiKey: string;
+	private baseUrl: string;
+	private retryConfig: Required<RetryConfig>;
+
+	// Domain method implementations
+	private sessionMethods: SessionMethods;
+	private projectMethods: ProjectMethods;
+	private blockersMethods: BlockersMethods;
+	private costMethods: CostMethods;
+	private worktreesMethods: WorktreesMethods;
+	private discoveryMethods: DiscoveryMethods;
+	private decisionsMethods: DecisionsMethods;
+	private ideasMethods: IdeasMethods;
+	private tasksMethods: TasksMethods;
+
+	constructor(config: ApiClientConfig) {
+		this.apiKey = config.apiKey;
+		this.baseUrl = config.baseUrl || process.env.VIBESCOPE_API_URL || DEFAULT_API_URL;
+		this.retryConfig = {
+			maxRetries: config.retry?.maxRetries ?? DEFAULT_MAX_RETRIES,
+			baseDelayMs: config.retry?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS,
+			maxDelayMs: config.retry?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS,
+			retryStatusCodes: config.retry?.retryStatusCodes ?? DEFAULT_RETRY_STATUS_CODES,
+		};
+
+		// Create bound request and proxy functions for domain modules
+		const request: RequestFn = this.request.bind(this);
+		const proxy: ProxyFn = this.proxy.bind(this);
+		const getApiKey = () => this.apiKey;
+
+		// Initialize domain methods
+		this.sessionMethods = createSessionMethods(request, getApiKey);
+		this.projectMethods = createProjectMethods(request);
+		this.blockersMethods = createBlockersMethods(request);
+		this.costMethods = createCostMethods(request);
+		this.worktreesMethods = createWorktreesMethods(request);
+		this.discoveryMethods = createDiscoveryMethods(request);
+		this.decisionsMethods = createDecisionsMethods(proxy);
+		this.ideasMethods = createIdeasMethods(proxy);
+		this.tasksMethods = createTasksMethods(request, proxy);
+	}
+
+	private async request<T>(method: string, path: string, body?: unknown): Promise<ApiResponse<T>> {
+		const url = `${this.baseUrl}${path}`;
+		const { maxRetries, baseDelayMs, maxDelayMs, retryStatusCodes } = this.retryConfig;
+		let lastError: Error | null = null;
+		let lastResponse: Response | null = null;
+
+		for (let attempt = 0; attempt <= maxRetries; attempt++) {
+			try {
+				const response = await fetch(url, {
+					method,
+					headers: {
+						'Content-Type': 'application/json',
+						'X-API-Key': this.apiKey
+					},
+					body: body ? JSON.stringify(body) : undefined
+				});
+
+				if (retryStatusCodes.includes(response.status) && attempt < maxRetries) {
+					lastResponse = response;
+					const retryAfterHeader = response.headers.get('Retry-After');
+					let retryAfter: number | undefined;
+					if (retryAfterHeader) {
+						const parsed = parseInt(retryAfterHeader, 10);
+						if (!isNaN(parsed)) {
+							retryAfter = parsed;
+						}
+					}
+					const delay = calculateBackoffDelay(attempt, baseDelayMs, maxDelayMs, retryAfter);
+					await sleep(delay);
+					continue;
+				}
+
+				if (!response.ok) {
+					const errorData = await response.json().catch(() => ({}));
+					return {
+						ok: false,
+						status: response.status,
+						error: errorData.error || errorData.message || `HTTP ${response.status}`
+					};
+				}
+
+				const data = await response.json();
+				return {
+					ok: true,
+					status: response.status,
+					data
+				};
+			} catch (error) {
+				lastError = error as Error;
+				if (attempt < maxRetries) {
+					const delay = calculateBackoffDelay(attempt, baseDelayMs, maxDelayMs);
+					await sleep(delay);
+					continue;
+				}
+			}
+		}
+
+		if (lastResponse && !lastResponse.ok) {
+			return {
+				ok: false,
+				status: lastResponse.status,
+				error: `Request failed after ${maxRetries + 1} attempts with status ${lastResponse.status}`
+			};
+		}
+
+		return {
+			ok: false,
+			status: 0,
+			error: lastError?.message || 'Request failed after all retries'
+		};
+	}
+
+	/**
+	 * Generic proxy method for operations that go through the MCP proxy endpoint
+	 */
+	async proxy<T>(operation: string, args: Record<string, unknown>, sessionContext?: {
+		session_id?: string;
+		project_id?: string;
+	}): Promise<ApiResponse<T>> {
+		return this.request('POST', '/api/mcp/proxy', {
+			operation,
+			args,
+			...sessionContext
+		});
+	}
+
+	// ============================================================================
+	// Session methods (delegated)
+	// ============================================================================
+	validateAuth = () => this.sessionMethods.validateAuth();
+	startSession = (params: Parameters<SessionMethods['startSession']>[0]) => this.sessionMethods.startSession(params);
+	heartbeat = (sessionId: string, options?: Parameters<SessionMethods['heartbeat']>[1]) => this.sessionMethods.heartbeat(sessionId, options);
+	endSession = (sessionId: string) => this.sessionMethods.endSession(sessionId);
+	signalIdle = (sessionId: string) => this.sessionMethods.signalIdle(sessionId);
+	syncSession = (sessionId: string, params?: Parameters<SessionMethods['syncSession']>[1]) => this.sessionMethods.syncSession(sessionId, params);
+	confirmAgentSetup = (projectId: string, agentType: string) => this.sessionMethods.confirmAgentSetup(projectId, agentType);
+
+	// ============================================================================
+	// Project methods (delegated)
+	// ============================================================================
+	listProjects = () => this.projectMethods.listProjects();
+	createProject = (params: Parameters<ProjectMethods['createProject']>[0]) => this.projectMethods.createProject(params);
+	getProject = (projectId: string, gitUrl?: string) => this.projectMethods.getProject(projectId, gitUrl);
+	updateProject = (projectId: string, updates: Parameters<ProjectMethods['updateProject']>[1]) => this.projectMethods.updateProject(projectId, updates);
+	getGitWorkflow = (projectId: string, taskId?: string) => this.projectMethods.getGitWorkflow(projectId, taskId);
+	updateProjectReadme = (projectId: string, readmeContent: string) => this.projectMethods.updateProjectReadme(projectId, readmeContent);
+	getProjectSummary = (projectId: string) => this.projectMethods.getProjectSummary(projectId);
+
+	// ============================================================================
+	// Blockers methods (delegated)
+	// ============================================================================
+	getBlockers = (projectId: string, params?: Parameters<BlockersMethods['getBlockers']>[1]) => this.blockersMethods.getBlockers(projectId, params);
+	addBlocker = (projectId: string, description: string, sessionId?: string) => this.blockersMethods.addBlocker(projectId, description, sessionId);
+	resolveBlocker = (blockerId: string, resolutionNote?: string) => this.blockersMethods.resolveBlocker(blockerId, resolutionNote);
+	deleteBlocker = (blockerId: string) => this.blockersMethods.deleteBlocker(blockerId);
+	getBlockersStats = (projectId: string) => this.blockersMethods.getBlockersStats(projectId);
+
+	// ============================================================================
+	// Cost methods (delegated)
+	// ============================================================================
+	getCostSummary = (projectId: string, params?: Parameters<CostMethods['getCostSummary']>[1]) => this.costMethods.getCostSummary(projectId, params);
+	getCostAlerts = () => this.costMethods.getCostAlerts();
+	addCostAlert = (params: Parameters<CostMethods['addCostAlert']>[0]) => this.costMethods.addCostAlert(params);
+	updateCostAlert = (alertId: string, updates: Parameters<CostMethods['updateCostAlert']>[1]) => this.costMethods.updateCostAlert(alertId, updates);
+	deleteCostAlert = (alertId: string) => this.costMethods.deleteCostAlert(alertId);
+	getTaskCosts = (projectId: string, limit?: number) => this.costMethods.getTaskCosts(projectId, limit);
+	getBodyOfWorkCosts = (params: Parameters<CostMethods['getBodyOfWorkCosts']>[0]) => this.costMethods.getBodyOfWorkCosts(params);
+	getSprintCosts = (params: Parameters<CostMethods['getSprintCosts']>[0]) => this.costMethods.getSprintCosts(params);
+	getTokenUsage = () => this.costMethods.getTokenUsage();
+	reportTokenUsage = (sessionId: string, params: Parameters<CostMethods['reportTokenUsage']>[1]) => this.costMethods.reportTokenUsage(sessionId, params);
+
+	// ============================================================================
+	// Worktrees methods (delegated)
+	// ============================================================================
+	getStaleWorktrees = (projectId: string, params?: Parameters<WorktreesMethods['getStaleWorktrees']>[1]) => this.worktreesMethods.getStaleWorktrees(projectId, params);
+	clearWorktreePath = (taskId: string) => this.worktreesMethods.clearWorktreePath(taskId);
+
+	// ============================================================================
+	// Discovery methods (delegated)
+	// ============================================================================
+	queryKnowledgeBase = (projectId: string, params?: Parameters<DiscoveryMethods['queryKnowledgeBase']>[1]) => this.discoveryMethods.queryKnowledgeBase(projectId, params);
+	getHelpTopic = (slug: string) => this.discoveryMethods.getHelpTopic(slug);
+	getHelpTopics = () => this.discoveryMethods.getHelpTopics();
+
+	// ============================================================================
+	// Decisions methods (delegated)
+	// ============================================================================
+	getDecisions = (projectId: string, options?: Parameters<DecisionsMethods['getDecisions']>[1]) => this.decisionsMethods.getDecisions(projectId, options);
+	getDecision = (decisionId: string) => this.decisionsMethods.getDecision(decisionId);
+	logDecision = (projectId: string, params: Parameters<DecisionsMethods['logDecision']>[1], sessionId?: string) => this.decisionsMethods.logDecision(projectId, params, sessionId);
+	deleteDecision = (decisionId: string) => this.decisionsMethods.deleteDecision(decisionId);
+	getDecisionsStats = (projectId: string) => this.decisionsMethods.getDecisionsStats(projectId);
+
+	// ============================================================================
+	// Ideas methods (delegated)
+	// ============================================================================
+	getIdeas = (projectId: string, params?: Parameters<IdeasMethods['getIdeas']>[1]) => this.ideasMethods.getIdeas(projectId, params);
+	getIdea = (ideaId: string) => this.ideasMethods.getIdea(ideaId);
+	addIdea = (projectId: string, params: Parameters<IdeasMethods['addIdea']>[1], sessionId?: string) => this.ideasMethods.addIdea(projectId, params, sessionId);
+	updateIdea = (ideaId: string, updates: Parameters<IdeasMethods['updateIdea']>[1]) => this.ideasMethods.updateIdea(ideaId, updates);
+	deleteIdea = (ideaId: string) => this.ideasMethods.deleteIdea(ideaId);
+	convertIdeaToTask = (ideaId: string, params?: Parameters<IdeasMethods['convertIdeaToTask']>[1]) => this.ideasMethods.convertIdeaToTask(ideaId, params);
+
+	// ============================================================================
+	// Tasks methods (delegated)
+	// ============================================================================
+	getTasks = (projectId: string, params?: Parameters<TasksMethods['getTasks']>[1]) => this.tasksMethods.getTasks(projectId, params);
+	createTask = (projectId: string, params: Parameters<TasksMethods['createTask']>[1]) => this.tasksMethods.createTask(projectId, params);
+	getNextTask = (projectId: string, sessionId?: string) => this.tasksMethods.getNextTask(projectId, sessionId);
+	getTask = (taskId: string) => this.tasksMethods.getTask(taskId);
+	getTaskById = (taskId: string, params?: Parameters<TasksMethods['getTaskById']>[1]) => this.tasksMethods.getTaskById(taskId, params);
+	searchTasks = (projectId: string, params: Parameters<TasksMethods['searchTasks']>[1]) => this.tasksMethods.searchTasks(projectId, params);
+	getTasksByPriority = (projectId: string, params?: Parameters<TasksMethods['getTasksByPriority']>[1]) => this.tasksMethods.getTasksByPriority(projectId, params);
+	getRecentTasks = (projectId: string, params?: Parameters<TasksMethods['getRecentTasks']>[1]) => this.tasksMethods.getRecentTasks(projectId, params);
+	getTaskStats = (projectId: string) => this.tasksMethods.getTaskStats(projectId);
+	updateTask = (taskId: string, updates: Parameters<TasksMethods['updateTask']>[1]) => this.tasksMethods.updateTask(taskId, updates);
+	completeTask = (taskId: string, params: Parameters<TasksMethods['completeTask']>[1]) => this.tasksMethods.completeTask(taskId, params);
+	deleteTask = (taskId: string) => this.tasksMethods.deleteTask(taskId);
+	releaseTask = (taskId: string, params?: Parameters<TasksMethods['releaseTask']>[1]) => this.tasksMethods.releaseTask(taskId, params);
+	cancelTask = (taskId: string, params?: Parameters<TasksMethods['cancelTask']>[1]) => this.tasksMethods.cancelTask(taskId, params);
+	addTaskReference = (taskId: string, url: string, label?: string) => this.tasksMethods.addTaskReference(taskId, url, label);
+	removeTaskReference = (taskId: string, url: string) => this.tasksMethods.removeTaskReference(taskId, url);
+	batchUpdateTasks = (updates: Parameters<TasksMethods['batchUpdateTasks']>[0]) => this.tasksMethods.batchUpdateTasks(updates);
+	batchCompleteTasks = (completions: Parameters<TasksMethods['batchCompleteTasks']>[0]) => this.tasksMethods.batchCompleteTasks(completions);
+
+	// ============================================================================
+	// TODO: Additional methods to be migrated from original api-client.ts
+	// The following domains need to be split into separate files:
+	// - findings.ts (getFindings, addFinding, etc.)
+	// - milestones.ts (getMilestones, addMilestone, etc.)
+	// - requests.ts (getPendingRequests, answerQuestion, etc.)
+	// - validation.ts (getTasksAwaitingValidation, validateTask, etc.)
+	// - fallback.ts (startFallbackActivity, stopFallbackActivity)
+	// - deployment.ts (requestDeployment, startDeployment, etc.)
+	// - organizations.ts (listOrganizations, etc.)
+	// - bodies-of-work.ts (createBodyOfWork, etc.)
+	// - git-issues.ts (addGitIssue, etc.)
+	// - file-checkouts.ts (checkoutFile, checkinFile, etc.)
+	// - connectors.ts (getConnectors, addConnector, etc.)
+	// - sprints.ts (getSprints, createSprint, etc.)
+	// - subtasks.ts (addSubtask, getSubtasks)
+	// - progress.ts (logProgress, getActivityHistory, etc.)
+	// ============================================================================
+}
+
+// Singleton instance
+let apiClient: VibescopeApiClient | null = null;
+
+export function getApiClient(): VibescopeApiClient {
+	if (!apiClient) {
+		const apiKey = resolveApiKeyFromSources();
+		apiClient = new VibescopeApiClient({ apiKey });
+	}
+	return apiClient;
+}
+
+/**
+ * Resolve API key from multiple sources in priority order:
+ * 1. VIBESCOPE_API_KEY env var (CI/cloud agents)
+ * 2. ~/.vibescope/credentials.json (local dev)
+ * 3. Error with helpful message
+ */
+function resolveApiKeyFromSources(): string {
+	// 1. Environment variable
+	if (process.env.VIBESCOPE_API_KEY) {
+		return process.env.VIBESCOPE_API_KEY;
+	}
+
+	// 2. Credentials file
+	try {
+		const { existsSync, readFileSync } = require('node:fs');
+		const { homedir } = require('node:os');
+		const { join } = require('node:path');
+		const credPath = join(homedir(), '.vibescope', 'credentials.json');
+		if (existsSync(credPath)) {
+			const data = JSON.parse(readFileSync(credPath, 'utf-8'));
+			if (data.apiKey) {
+				return data.apiKey;
+			}
+		}
+	} catch {
+		// ignore read errors
+	}
+
+	// 3. Not found
+	throw new Error(
+		'Vibescope API key not found.\n\n' +
+		'Set it up with:\n' +
+		'  npx vibescope init\n\n' +
+		'Or set the VIBESCOPE_API_KEY environment variable.'
+	);
+}
+
+export function initApiClient(config: ApiClientConfig): VibescopeApiClient {
+	apiClient = new VibescopeApiClient(config);
+	return apiClient;
+}