@vibescope/mcp-server 0.4.9 → 0.5.1

package/src/cli-init.ts

@@ -1,558 +1,558 @@
-#!/usr/bin/env node
-
-/**
- * Vibescope Init CLI
- * 
- * Usage: npx vibescope init
- * 
- * Detects installed AI agents, configures MCP, and stores credentials.
- */
-
-import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
-import { getAgentGuidelinesTemplate, VIBESCOPE_SECTION_START, VIBESCOPE_SECTION_END } from './templates/agent-guidelines.js';
-import { homedir, platform } from 'node:os';
-import { join, dirname } from 'node:path';
-import { exec, execSync } from 'node:child_process';
-import { createInterface } from 'node:readline';
-
-const VIBESCOPE_SETTINGS_URL = 'https://vibescope.dev/dashboard/settings';
-const VIBESCOPE_API_URL = 'https://vibescope.dev';
-const CREDENTIALS_DIR = join(homedir(), '.vibescope');
-const CREDENTIALS_PATH = join(CREDENTIALS_DIR, 'credentials.json');
-
-// ============================================================================
-// Terminal Colors
-// ============================================================================
-
-const c = {
-	reset: '\x1b[0m',
-	bold: '\x1b[1m',
-	dim: '\x1b[2m',
-	green: '\x1b[32m',
-	yellow: '\x1b[33m',
-	blue: '\x1b[34m',
-	magenta: '\x1b[35m',
-	cyan: '\x1b[36m',
-	red: '\x1b[31m',
-	white: '\x1b[37m',
-};
-
-const icon = {
-	check: `${c.green}✔${c.reset}`,
-	cross: `${c.red}✘${c.reset}`,
-	arrow: `${c.cyan}→${c.reset}`,
-	dot: `${c.dim}·${c.reset}`,
-	warn: `${c.yellow}⚠${c.reset}`,
-};
-
-// ============================================================================
-// Types
-// ============================================================================
-
-interface Agent {
-	id: string;
-	name: string;
-	detected: boolean;
-	configure: (apiKey: string) => Promise<void>;
-}
-
-// ============================================================================
-// Prompts
-// ============================================================================
-
-function prompt(question: string): Promise<string> {
-	const rl = createInterface({ input: process.stdin, output: process.stdout });
-	return new Promise((resolve) => {
-		rl.question(question, (answer) => {
-			rl.close();
-			resolve(answer.trim());
-		});
-	});
-}
-
-async function promptConfirm(question: string, defaultYes = true): Promise<boolean> {
-	const hint = defaultYes ? 'Y/n' : 'y/N';
-	const answer = await prompt(`${question} (${hint}): `);
-	if (!answer) return defaultYes;
-	return answer.toLowerCase().startsWith('y');
-}
-
-async function promptCheckboxes(label: string, items: { id: string; name: string; detected: boolean }[]): Promise<string[]> {
-	console.log(`\n${c.bold}${label}${c.reset}\n`);
-	items.forEach((item, i) => {
-		const tag = item.detected ? `${c.green}detected${c.reset}` : `${c.dim}not detected${c.reset}`;
-		console.log(`  ${i + 1}) ${item.name} [${tag}]`);
-	});
-	console.log(`  ${c.dim}a) All detected${c.reset}`);
-
-	const answer = await prompt(`\nSelect agents (comma-separated numbers, or 'a' for all detected): `);
-
-	if (answer.toLowerCase() === 'a') {
-		const detected = items.filter(i => i.detected).map(i => i.id);
-		return detected.length > 0 ? detected : items.map(i => i.id);
-	}
-
-	const indices = answer.split(',').map(s => parseInt(s.trim(), 10) - 1).filter(i => i >= 0 && i < items.length);
-	if (indices.length === 0) {
-		// Default to all detected
-		const detected = items.filter(i => i.detected).map(i => i.id);
-		return detected.length > 0 ? detected : [items[0].id];
-	}
-	return indices.map(i => items[i].id);
-}
-
-// ============================================================================
-// Credential Storage
-// ============================================================================
-
-export function readCredentials(): { apiKey?: string } {
-	try {
-		if (existsSync(CREDENTIALS_PATH)) {
-			const data = JSON.parse(readFileSync(CREDENTIALS_PATH, 'utf-8'));
-			return { apiKey: data.apiKey };
-		}
-	} catch { /* ignore */ }
-	return {};
-}
-
-export function writeCredentials(apiKey: string): void {
-	if (!existsSync(CREDENTIALS_DIR)) {
-		mkdirSync(CREDENTIALS_DIR, { recursive: true });
-	}
-	writeFileSync(CREDENTIALS_PATH, JSON.stringify({ apiKey }, null, 2) + '\n', { mode: 0o600 });
-	try {
-		chmodSync(CREDENTIALS_PATH, 0o600);
-	} catch { /* Windows doesn't support chmod, that's ok */ }
-}
-
-/**
- * Resolve API key from env var or credentials file.
- * Used by the MCP server at startup.
- */
-export function resolveApiKey(): string | null {
-	// 1. Environment variable (highest priority)
-	if (process.env.VIBESCOPE_API_KEY) {
-		return process.env.VIBESCOPE_API_KEY;
-	}
-	// 2. Credentials file
-	const creds = readCredentials();
-	if (creds.apiKey) {
-		return creds.apiKey;
-	}
-	// 3. Not found
-	return null;
-}
-
-// ============================================================================
-// Agent Detection & Configuration
-// ============================================================================
-
-function commandExists(cmd: string): boolean {
-	try {
-		execSync(`which ${cmd}`, { stdio: 'pipe', timeout: 3000 });
-		return true;
-	} catch {
-		// On Windows, try 'where'
-		if (platform() === 'win32') {
-			try {
-				execSync(`where ${cmd}`, { stdio: 'pipe', timeout: 3000 });
-				return true;
-			} catch { /* not found */ }
-		}
-		return false;
-	}
-}
-
-function dirExists(path: string): boolean {
-	return existsSync(path);
-}
-
-function detectAgents(): Agent[] {
-	const home = homedir();
-
-	const agents: Agent[] = [
-		{
-			id: 'claude-code',
-			name: 'Claude Code',
-			detected: commandExists('claude') || dirExists(join(home, '.claude')),
-			configure: configureClaudeCode,
-		},
-		{
-			id: 'cursor',
-			name: 'Cursor',
-			detected: commandExists('cursor') || dirExists(join(home, '.cursor')),
-			configure: configureCursor,
-		},
-		{
-			id: 'windsurf',
-			name: 'Windsurf',
-			detected: dirExists(join(home, '.windsurf')) || dirExists(join(home, '.codeium')),
-			configure: configureWindsurf,
-		},
-		{
-			id: 'gemini',
-			name: 'Gemini CLI',
-			detected: commandExists('gemini') || dirExists(join(home, '.gemini')),
-			configure: configureGemini,
-		},
-	];
-
-	return agents;
-}
-
-// ============================================================================
-// Agent Configurators
-// ============================================================================
-
-async function configureClaudeCode(apiKey: string): Promise<void> {
-	// Write project-level .mcp.json (works reliably across all platforms)
-	const configPath = join(process.cwd(), '.mcp.json');
-	writeMcpJson(configPath, apiKey);
-	console.log(`  ${icon.check} Wrote ${c.cyan}.mcp.json${c.reset} (Claude Code project config)`);
-
-	// Also offer to write user-level config for global access
-	const globalConfig = platform() === 'win32'
-		? join(homedir(), '.claude', 'settings.json')
-		: join(homedir(), '.claude', 'settings.json');
-
-	const addGlobal = await promptConfirm(`  Also add Vibescope globally (all projects)?`, true);
-	if (addGlobal) {
-		const existing = readJsonFile(globalConfig);
-		const mcpServers = (existing.mcpServers as Record<string, unknown>) || {};
-		mcpServers['vibescope'] = buildMcpServerConfig(apiKey);
-		existing.mcpServers = mcpServers;
-		writeJsonFile(globalConfig, existing);
-		console.log(`  ${icon.check} Wrote ${c.cyan}~/.claude/settings.json${c.reset} (global config)`);
-	}
-}
-
-async function configureCursor(apiKey: string): Promise<void> {
-	const configPath = join(process.cwd(), '.cursor', 'mcp.json');
-	writeMcpJson(configPath, apiKey);
-	console.log(`  ${icon.check} Wrote ${c.cyan}.cursor/mcp.json${c.reset}`);
-}
-
-async function configureWindsurf(apiKey: string): Promise<void> {
-	const configPath = join(homedir(), '.codeium', 'windsurf', 'mcp_config.json');
-	writeMcpJson(configPath, apiKey);
-	console.log(`  ${icon.check} Wrote ${c.cyan}~/.codeium/windsurf/mcp_config.json${c.reset}`);
-}
-
-async function configureGemini(apiKey: string): Promise<void> {
-	const configPath = join(homedir(), '.gemini', 'settings.json');
-	const existing = readJsonFile(configPath);
-	const mcpServers = (existing.mcpServers as Record<string, unknown>) || {};
-	mcpServers['vibescope'] = {
-		...buildMcpServerConfig(apiKey),
-		timeout: 30000,
-		trust: true,
-	};
-	existing.mcpServers = mcpServers;
-	writeJsonFile(configPath, existing);
-	console.log(`  ${icon.check} Wrote ${c.cyan}~/.gemini/settings.json${c.reset}`);
-}
-
-// ============================================================================
-// Config File Helpers
-// ============================================================================
-
-function readJsonFile(path: string): Record<string, unknown> {
-	try {
-		if (existsSync(path)) {
-			return JSON.parse(readFileSync(path, 'utf-8'));
-		}
-	} catch { /* ignore */ }
-	return {};
-}
-
-function writeJsonFile(path: string, data: Record<string, unknown>): void {
-	const dir = dirname(path);
-	if (!existsSync(dir)) {
-		mkdirSync(dir, { recursive: true });
-	}
-	writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
-}
-
-function buildMcpServerConfig(apiKey: string): Record<string, unknown> {
-	const isWindows = platform() === 'win32';
-	// Prefer globally installed binary (instant start) with npx fallback
-	if (isWindows) {
-		return {
-			command: 'cmd',
-			args: ['/c', 'where vibescope-mcp >nul 2>&1 && vibescope-mcp || npx -y -p @vibescope/mcp-server@latest vibescope-mcp'],
-			env: { VIBESCOPE_API_KEY: apiKey },
-		};
-	}
-	return {
-		command: 'bash',
-		args: ['-c', 'command -v vibescope-mcp >/dev/null 2>&1 && exec vibescope-mcp || exec npx -y -p @vibescope/mcp-server@latest vibescope-mcp'],
-		env: { VIBESCOPE_API_KEY: apiKey },
-	};
-}
-
-function writeMcpJson(configPath: string, apiKey: string): void {
-	const existing = readJsonFile(configPath);
-	const mcpServers = (existing.mcpServers as Record<string, unknown>) || {};
-	mcpServers['vibescope'] = buildMcpServerConfig(apiKey);
-	existing.mcpServers = mcpServers;
-	writeJsonFile(configPath, existing);
-}
-
-function checkExistingConfig(agentId: string): boolean {
-	switch (agentId) {
-		case 'claude-code':
-			return existsSync(join(process.cwd(), '.mcp.json')) &&
-				readJsonFile(join(process.cwd(), '.mcp.json')).mcpServers !== undefined &&
-				'vibescope' in ((readJsonFile(join(process.cwd(), '.mcp.json')).mcpServers as Record<string, unknown>) || {});
-		case 'cursor':
-			return existsSync(join(process.cwd(), '.cursor', 'mcp.json')) &&
-				'vibescope' in ((readJsonFile(join(process.cwd(), '.cursor', 'mcp.json')).mcpServers as Record<string, unknown>) || {});
-		case 'windsurf':
-			return 'vibescope' in ((readJsonFile(join(homedir(), '.codeium', 'windsurf', 'mcp_config.json')).mcpServers as Record<string, unknown>) || {});
-		case 'gemini':
-			return 'vibescope' in ((readJsonFile(join(homedir(), '.gemini', 'settings.json')).mcpServers as Record<string, unknown>) || {});
-		default:
-			return false;
-	}
-}
-
-// ============================================================================
-// API Key Validation
-// ============================================================================
-
-async function validateApiKey(apiKey: string): Promise<{ valid: boolean; message: string }> {
-	try {
-		const response = await fetch(`${VIBESCOPE_API_URL}/api/mcp/auth/validate`, {
-			method: 'POST',
-			headers: {
-				'Content-Type': 'application/json',
-				'X-API-Key': apiKey,
-			},
-			body: JSON.stringify({ api_key: apiKey }),
-		});
-		const data = await response.json() as { valid?: boolean; error?: string };
-		if (response.ok && data.valid) {
-			return { valid: true, message: 'API key is valid' };
-		}
-		return { valid: false, message: data.error || 'Invalid API key' };
-	} catch {
-		return { valid: true, message: 'Could not validate (network issue), proceeding' };
-	}
-}
-
-// ============================================================================
-// Browser
-// ============================================================================
-
-function openBrowser(url: string): Promise<void> {
-	return new Promise((resolve) => {
-		const plat = platform();
-		const cmd = plat === 'darwin' ? `open "${url}"` :
-			plat === 'win32' ? `start "" "${url}"` :
-				`xdg-open "${url}"`;
-		exec(cmd, () => resolve());
-	});
-}
-
-// ============================================================================
-// Main Init Flow
-// ============================================================================
-
-async function runInit(): Promise<void> {
-	console.log(`
-${c.bold}${c.magenta}  ╦  ╦╦╔╗ ╔═╗╔═╗╔═╗╔═╗╔═╗╔═╗${c.reset}
-${c.bold}${c.magenta}  ╚╗╔╝║╠╩╗║╣ ╚═╗║  ║ ║╠═╝║╣ ${c.reset}
-${c.bold}${c.magenta}   ╚╝ ╩╚═╝╚═╝╚═╝╚═╝╚═╝╩  ╚═╝${c.reset}
-${c.dim}  AI project tracking for vibe coders${c.reset}
-`);
-
-	// Step 1: Detect agents
-	const agents = detectAgents();
-	const detected = agents.filter(a => a.detected);
-
-	if (detected.length > 0) {
-		console.log(`${icon.check} Detected agents:`);
-		detected.forEach(a => console.log(`  ${icon.dot} ${a.name}`));
-	} else {
-		console.log(`${icon.warn} No AI agents detected automatically`);
-	}
-
-	// Step 2: Select agents
-	const selectedIds = await promptCheckboxes(
-		'Which agents do you want to configure?',
-		agents.map(a => ({ id: a.id, name: a.name, detected: a.detected }))
-	);
-	const selectedAgents = agents.filter(a => selectedIds.includes(a.id));
-
-	if (selectedAgents.length === 0) {
-		console.log(`\n${icon.cross} No agents selected. Exiting.`);
-		process.exit(0);
-	}
-
-	// Step 3: API Key
-	let apiKey: string | null = null;
-
-	// Check env var first
-	if (process.env.VIBESCOPE_API_KEY) {
-		apiKey = process.env.VIBESCOPE_API_KEY;
-		console.log(`\n${icon.check} Using API key from ${c.cyan}VIBESCOPE_API_KEY${c.reset} env var`);
-	}
-
-	// Check credentials file
-	if (!apiKey) {
-		const creds = readCredentials();
-		if (creds.apiKey) {
-			apiKey = creds.apiKey;
-			console.log(`\n${icon.check} Found existing API key in ${c.cyan}~/.vibescope/credentials.json${c.reset}`);
-			const reuse = await promptConfirm('Use existing API key?', true);
-			if (!reuse) apiKey = null;
-		}
-	}
-
-	// Prompt for key if needed
-	if (!apiKey) {
-		console.log(`\n${c.bold}API Key Setup${c.reset}`);
-		console.log(`${icon.arrow} Get your API key at ${c.cyan}${VIBESCOPE_SETTINGS_URL}${c.reset}`);
-
-		const openIt = await promptConfirm('Open settings page in browser?', true);
-		if (openIt) await openBrowser(VIBESCOPE_SETTINGS_URL);
-
-		for (let attempt = 0; attempt < 3; attempt++) {
-			apiKey = await prompt(`\n${c.bold}Paste your API key:${c.reset} `);
-			if (!apiKey) {
-				console.log(`${icon.cross} API key is required`);
-				continue;
-			}
-			process.stdout.write(`  Validating... `);
-			const result = await validateApiKey(apiKey);
-			if (result.valid) {
-				console.log(`${icon.check} ${result.message}`);
-				break;
-			} else {
-				console.log(`${icon.cross} ${result.message}`);
-				apiKey = null;
-			}
-		}
-
-		if (!apiKey) {
-			console.log(`\n${icon.cross} Could not get a valid API key. Exiting.`);
-			process.exit(1);
-		}
-
-		// Store credentials
-		try {
-			writeCredentials(apiKey);
-			console.log(`\n${icon.check} API key saved to ${c.cyan}~/.vibescope/credentials.json${c.reset}`);
-		} catch (err) {
-			console.log(`\n${icon.warn} Could not save credentials: ${err instanceof Error ? err.message : 'unknown error'}`);
-			console.log(`  ${c.dim}Set VIBESCOPE_API_KEY env var as fallback${c.reset}`);
-		}
-	}
-
-	// Step 4: Configure each agent
-	console.log(`\n${c.bold}Configuring agents...${c.reset}\n`);
-
-	for (const agent of selectedAgents) {
-		const hasExisting = checkExistingConfig(agent.id);
-		if (hasExisting) {
-			const overwrite = await promptConfirm(`  ${agent.name} already configured. Update?`, true);
-			if (!overwrite) {
-				console.log(`  ${icon.dot} Skipped ${agent.name}`);
-				continue;
-			}
-		}
-		try {
-			await agent.configure(apiKey);
-		} catch (err) {
-			console.log(`  ${icon.cross} Failed to configure ${agent.name}: ${err instanceof Error ? err.message : 'unknown error'}`);
-		}
-	}
-
-	// Step 5: Generate or update .claude/CLAUDE.md
-	const claudeMdPath = join(process.cwd(), '.claude', 'CLAUDE.md');
-	const claudeDir = join(process.cwd(), '.claude');
-	if (!existsSync(claudeDir)) {
-		mkdirSync(claudeDir, { recursive: true });
-	}
-
-	const vibescopeGuidelines = getAgentGuidelinesTemplate();
-
-	if (existsSync(claudeMdPath)) {
-		const existing = readFileSync(claudeMdPath, 'utf-8');
-		const hasVibescopeSection = existing.includes(VIBESCOPE_SECTION_START);
-
-		if (hasVibescopeSection) {
-			// Replace existing Vibescope section
-			const update = await promptConfirm(`\n  ${c.cyan}.claude/CLAUDE.md${c.reset} already has Vibescope guidelines. Update them?`, true);
-			if (update) {
-				const startIdx = existing.indexOf(VIBESCOPE_SECTION_START);
-				const endIdx = existing.indexOf(VIBESCOPE_SECTION_END);
-				if (startIdx !== -1 && endIdx !== -1) {
-					const updated = existing.substring(0, startIdx) + vibescopeGuidelines + existing.substring(endIdx + VIBESCOPE_SECTION_END.length);
-					writeFileSync(claudeMdPath, updated);
-					console.log(`  ${icon.check} Updated Vibescope section in ${c.cyan}.claude/CLAUDE.md${c.reset}`);
-				}
-			} else {
-				console.log(`  ${icon.dot} Skipped CLAUDE.md update`);
-			}
-		} else {
-			// Append Vibescope guidelines to existing file
-			const append = await promptConfirm(`\n  ${c.cyan}.claude/CLAUDE.md${c.reset} exists. Append Vibescope guidelines?`, true);
-			if (append) {
-				const separator = existing.endsWith('\n') ? '\n' : '\n\n';
-				writeFileSync(claudeMdPath, existing + separator + vibescopeGuidelines);
-				console.log(`  ${icon.check} Appended Vibescope guidelines to ${c.cyan}.claude/CLAUDE.md${c.reset}`);
-			} else {
-				console.log(`  ${icon.dot} Skipped CLAUDE.md`);
-			}
-		}
-	} else {
-		writeFileSync(claudeMdPath, vibescopeGuidelines);
-		console.log(`  ${icon.check} Created ${c.cyan}.claude/CLAUDE.md${c.reset} with agent guidelines`);
-	}
-
-	// Done!
-	console.log(`
-${c.green}${c.bold}Setup complete!${c.reset}
-
-${c.bold}Next steps:${c.reset}
-  ${icon.arrow} Restart your AI agent / IDE
-  ${icon.arrow} Start coding — Vibescope tracks automatically
-
-${c.dim}Need help? https://vibescope.dev/docs${c.reset}
-`);
-}
-
-// ============================================================================
-// CLI Entry Point
-// ============================================================================
-
-async function main() {
-	const args = process.argv.slice(2);
-	const command = args[0];
-
-	if (command === 'init' || !command) {
-		await runInit();
-	} else if (command === '--help' || command === '-h' || command === 'help') {
-		console.log(`
-${c.bold}Vibescope CLI${c.reset}
-
-Usage:
-  npx vibescope init     Set up Vibescope for your AI agents
-  npx vibescope help     Show this help
-
-Docs: https://vibescope.dev/docs
-`);
-	} else {
-		console.log(`Unknown command: ${command}\nRun ${c.cyan}npx vibescope help${c.reset} for usage.`);
-		process.exit(1);
-	}
-}
-
-const isMainModule = import.meta.url === `file://${process.argv[1]?.replace(/\\/g, '/')}`;
-if (isMainModule || process.argv[1]?.endsWith('cli-init.js')) {
-	main().catch((err) => {
-		console.error(`${icon.cross} ${err instanceof Error ? err.message : 'Unknown error'}`);
-		process.exit(1);
-	});
-}
+#!/usr/bin/env node
+
+/**
+ * Vibescope Init CLI
+ * 
+ * Usage: npx vibescope init
+ * 
+ * Detects installed AI agents, configures MCP, and stores credentials.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
+import { getAgentGuidelinesTemplate, VIBESCOPE_SECTION_START, VIBESCOPE_SECTION_END } from './templates/agent-guidelines.js';
+import { homedir, platform } from 'node:os';
+import { join, dirname } from 'node:path';
+import { exec, execSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
+
+const VIBESCOPE_SETTINGS_URL = 'https://vibescope.dev/dashboard/settings';
+const VIBESCOPE_API_URL = 'https://vibescope.dev';
+const CREDENTIALS_DIR = join(homedir(), '.vibescope');
+const CREDENTIALS_PATH = join(CREDENTIALS_DIR, 'credentials.json');
+
+// ============================================================================
+// Terminal Colors
+// ============================================================================
+
+const c = {
+	reset: '\x1b[0m',
+	bold: '\x1b[1m',
+	dim: '\x1b[2m',
+	green: '\x1b[32m',
+	yellow: '\x1b[33m',
+	blue: '\x1b[34m',
+	magenta: '\x1b[35m',
+	cyan: '\x1b[36m',
+	red: '\x1b[31m',
+	white: '\x1b[37m',
+};
+
+const icon = {
+	check: `${c.green}✔${c.reset}`,
+	cross: `${c.red}✘${c.reset}`,
+	arrow: `${c.cyan}→${c.reset}`,
+	dot: `${c.dim}·${c.reset}`,
+	warn: `${c.yellow}⚠${c.reset}`,
+};
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface Agent {
+	id: string;
+	name: string;
+	detected: boolean;
+	configure: (apiKey: string) => Promise<void>;
+}
+
+// ============================================================================
+// Prompts
+// ============================================================================
+
+function prompt(question: string): Promise<string> {
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	return new Promise((resolve) => {
+		rl.question(question, (answer) => {
+			rl.close();
+			resolve(answer.trim());
+		});
+	});
+}
+
+async function promptConfirm(question: string, defaultYes = true): Promise<boolean> {
+	const hint = defaultYes ? 'Y/n' : 'y/N';
+	const answer = await prompt(`${question} (${hint}): `);
+	if (!answer) return defaultYes;
+	return answer.toLowerCase().startsWith('y');
+}
+
+async function promptCheckboxes(label: string, items: { id: string; name: string; detected: boolean }[]): Promise<string[]> {
+	console.log(`\n${c.bold}${label}${c.reset}\n`);
+	items.forEach((item, i) => {
+		const tag = item.detected ? `${c.green}detected${c.reset}` : `${c.dim}not detected${c.reset}`;
+		console.log(`  ${i + 1}) ${item.name} [${tag}]`);
+	});
+	console.log(`  ${c.dim}a) All detected${c.reset}`);
+
+	const answer = await prompt(`\nSelect agents (comma-separated numbers, or 'a' for all detected): `);
+
+	if (answer.toLowerCase() === 'a') {
+		const detected = items.filter(i => i.detected).map(i => i.id);
+		return detected.length > 0 ? detected : items.map(i => i.id);
+	}
+
+	const indices = answer.split(',').map(s => parseInt(s.trim(), 10) - 1).filter(i => i >= 0 && i < items.length);
+	if (indices.length === 0) {
+		// Default to all detected
+		const detected = items.filter(i => i.detected).map(i => i.id);
+		return detected.length > 0 ? detected : [items[0].id];
+	}
+	return indices.map(i => items[i].id);
+}
+
+// ============================================================================
+// Credential Storage
+// ============================================================================
+
+export function readCredentials(): { apiKey?: string } {
+	try {
+		if (existsSync(CREDENTIALS_PATH)) {
+			const data = JSON.parse(readFileSync(CREDENTIALS_PATH, 'utf-8'));
+			return { apiKey: data.apiKey };
+		}
+	} catch { /* ignore */ }
+	return {};
+}
+
+export function writeCredentials(apiKey: string): void {
+	if (!existsSync(CREDENTIALS_DIR)) {
+		mkdirSync(CREDENTIALS_DIR, { recursive: true });
+	}
+	writeFileSync(CREDENTIALS_PATH, JSON.stringify({ apiKey }, null, 2) + '\n', { mode: 0o600 });
+	try {
+		chmodSync(CREDENTIALS_PATH, 0o600);
+	} catch { /* Windows doesn't support chmod, that's ok */ }
+}
+
+/**
+ * Resolve API key from env var or credentials file.
+ * Used by the MCP server at startup.
+ */
+export function resolveApiKey(): string | null {
+	// 1. Environment variable (highest priority)
+	if (process.env.VIBESCOPE_API_KEY) {
+		return process.env.VIBESCOPE_API_KEY;
+	}
+	// 2. Credentials file
+	const creds = readCredentials();
+	if (creds.apiKey) {
+		return creds.apiKey;
+	}
+	// 3. Not found
+	return null;
+}
+
+// ============================================================================
+// Agent Detection & Configuration
+// ============================================================================
+
+function commandExists(cmd: string): boolean {
+	try {
+		execSync(`which ${cmd}`, { stdio: 'pipe', timeout: 3000 });
+		return true;
+	} catch {
+		// On Windows, try 'where'
+		if (platform() === 'win32') {
+			try {
+				execSync(`where ${cmd}`, { stdio: 'pipe', timeout: 3000 });
+				return true;
+			} catch { /* not found */ }
+		}
+		return false;
+	}
+}
+
+function dirExists(path: string): boolean {
+	return existsSync(path);
+}
+
+function detectAgents(): Agent[] {
+	const home = homedir();
+
+	const agents: Agent[] = [
+		{
+			id: 'claude-code',
+			name: 'Claude Code',
+			detected: commandExists('claude') || dirExists(join(home, '.claude')),
+			configure: configureClaudeCode,
+		},
+		{
+			id: 'cursor',
+			name: 'Cursor',
+			detected: commandExists('cursor') || dirExists(join(home, '.cursor')),
+			configure: configureCursor,
+		},
+		{
+			id: 'windsurf',
+			name: 'Windsurf',
+			detected: dirExists(join(home, '.windsurf')) || dirExists(join(home, '.codeium')),
+			configure: configureWindsurf,
+		},
+		{
+			id: 'gemini',
+			name: 'Gemini CLI',
+			detected: commandExists('gemini') || dirExists(join(home, '.gemini')),
+			configure: configureGemini,
+		},
+	];
+
+	return agents;
+}
+
+// ============================================================================
+// Agent Configurators
+// ============================================================================
+
+async function configureClaudeCode(apiKey: string): Promise<void> {
+	// Write project-level .mcp.json (works reliably across all platforms)
+	const configPath = join(process.cwd(), '.mcp.json');
+	writeMcpJson(configPath, apiKey);
+	console.log(`  ${icon.check} Wrote ${c.cyan}.mcp.json${c.reset} (Claude Code project config)`);
+
+	// Also offer to write user-level config for global access
+	const globalConfig = platform() === 'win32'
+		? join(homedir(), '.claude', 'settings.json')
+		: join(homedir(), '.claude', 'settings.json');
+
+	const addGlobal = await promptConfirm(`  Also add Vibescope globally (all projects)?`, true);
+	if (addGlobal) {
+		const existing = readJsonFile(globalConfig);
+		const mcpServers = (existing.mcpServers as Record<string, unknown>) || {};
+		mcpServers['vibescope'] = buildMcpServerConfig(apiKey);
+		existing.mcpServers = mcpServers;
+		writeJsonFile(globalConfig, existing);
+		console.log(`  ${icon.check} Wrote ${c.cyan}~/.claude/settings.json${c.reset} (global config)`);
+	}
+}
+
+async function configureCursor(apiKey: string): Promise<void> {
+	const configPath = join(process.cwd(), '.cursor', 'mcp.json');
+	writeMcpJson(configPath, apiKey);
+	console.log(`  ${icon.check} Wrote ${c.cyan}.cursor/mcp.json${c.reset}`);
+}
+
+async function configureWindsurf(apiKey: string): Promise<void> {
+	const configPath = join(homedir(), '.codeium', 'windsurf', 'mcp_config.json');
+	writeMcpJson(configPath, apiKey);
+	console.log(`  ${icon.check} Wrote ${c.cyan}~/.codeium/windsurf/mcp_config.json${c.reset}`);
+}
+
+async function configureGemini(apiKey: string): Promise<void> {
+	const configPath = join(homedir(), '.gemini', 'settings.json');
+	const existing = readJsonFile(configPath);
+	const mcpServers = (existing.mcpServers as Record<string, unknown>) || {};
+	mcpServers['vibescope'] = {
+		...buildMcpServerConfig(apiKey),
+		timeout: 30000,
+		trust: true,
+	};
+	existing.mcpServers = mcpServers;
+	writeJsonFile(configPath, existing);
+	console.log(`  ${icon.check} Wrote ${c.cyan}~/.gemini/settings.json${c.reset}`);
+}
+
+// ============================================================================
+// Config File Helpers
+// ============================================================================
+
+function readJsonFile(path: string): Record<string, unknown> {
+	try {
+		if (existsSync(path)) {
+			return JSON.parse(readFileSync(path, 'utf-8'));
+		}
+	} catch { /* ignore */ }
+	return {};
+}
+
+function writeJsonFile(path: string, data: Record<string, unknown>): void {
+	const dir = dirname(path);
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+	}
+	writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+}
+
+function buildMcpServerConfig(apiKey: string): Record<string, unknown> {
+	const isWindows = platform() === 'win32';
+	// Prefer globally installed binary (instant start) with npx fallback
+	if (isWindows) {
+		return {
+			command: 'cmd',
+			args: ['/c', 'where vibescope-mcp >nul 2>&1 && vibescope-mcp || npx -y -p @vibescope/mcp-server@latest vibescope-mcp'],
+			env: { VIBESCOPE_API_KEY: apiKey },
+		};
+	}
+	return {
+		command: 'bash',
+		args: ['-c', 'command -v vibescope-mcp >/dev/null 2>&1 && exec vibescope-mcp || exec npx -y -p @vibescope/mcp-server@latest vibescope-mcp'],
+		env: { VIBESCOPE_API_KEY: apiKey },
+	};
+}
+
+function writeMcpJson(configPath: string, apiKey: string): void {
+	const existing = readJsonFile(configPath);
+	const mcpServers = (existing.mcpServers as Record<string, unknown>) || {};
+	mcpServers['vibescope'] = buildMcpServerConfig(apiKey);
+	existing.mcpServers = mcpServers;
+	writeJsonFile(configPath, existing);
+}
+
+function checkExistingConfig(agentId: string): boolean {
+	switch (agentId) {
+		case 'claude-code':
+			return existsSync(join(process.cwd(), '.mcp.json')) &&
+				readJsonFile(join(process.cwd(), '.mcp.json')).mcpServers !== undefined &&
+				'vibescope' in ((readJsonFile(join(process.cwd(), '.mcp.json')).mcpServers as Record<string, unknown>) || {});
+		case 'cursor':
+			return existsSync(join(process.cwd(), '.cursor', 'mcp.json')) &&
+				'vibescope' in ((readJsonFile(join(process.cwd(), '.cursor', 'mcp.json')).mcpServers as Record<string, unknown>) || {});
+		case 'windsurf':
+			return 'vibescope' in ((readJsonFile(join(homedir(), '.codeium', 'windsurf', 'mcp_config.json')).mcpServers as Record<string, unknown>) || {});
+		case 'gemini':
+			return 'vibescope' in ((readJsonFile(join(homedir(), '.gemini', 'settings.json')).mcpServers as Record<string, unknown>) || {});
+		default:
+			return false;
+	}
+}
+
+// ============================================================================
+// API Key Validation
+// ============================================================================
+
+async function validateApiKey(apiKey: string): Promise<{ valid: boolean; message: string }> {
+	try {
+		const response = await fetch(`${VIBESCOPE_API_URL}/api/mcp/auth/validate`, {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/json',
+				'X-API-Key': apiKey,
+			},
+			body: JSON.stringify({ api_key: apiKey }),
+		});
+		const data = await response.json() as { valid?: boolean; error?: string };
+		if (response.ok && data.valid) {
+			return { valid: true, message: 'API key is valid' };
+		}
+		return { valid: false, message: data.error || 'Invalid API key' };
+	} catch {
+		return { valid: true, message: 'Could not validate (network issue), proceeding' };
+	}
+}
+
+// ============================================================================
+// Browser
+// ============================================================================
+
+function openBrowser(url: string): Promise<void> {
+	return new Promise((resolve) => {
+		const plat = platform();
+		const cmd = plat === 'darwin' ? `open "${url}"` :
+			plat === 'win32' ? `start "" "${url}"` :
+				`xdg-open "${url}"`;
+		exec(cmd, () => resolve());
+	});
+}
+
+// ============================================================================
+// Main Init Flow
+// ============================================================================
+
+async function runInit(): Promise<void> {
+	console.log(`
+${c.bold}${c.magenta}  ╦  ╦╦╔╗ ╔═╗╔═╗╔═╗╔═╗╔═╗╔═╗${c.reset}
+${c.bold}${c.magenta}  ╚╗╔╝║╠╩╗║╣ ╚═╗║  ║ ║╠═╝║╣ ${c.reset}
+${c.bold}${c.magenta}   ╚╝ ╩╚═╝╚═╝╚═╝╚═╝╚═╝╩  ╚═╝${c.reset}
+${c.dim}  AI project tracking for vibe coders${c.reset}
+`);
+
+	// Step 1: Detect agents
+	const agents = detectAgents();
+	const detected = agents.filter(a => a.detected);
+
+	if (detected.length > 0) {
+		console.log(`${icon.check} Detected agents:`);
+		detected.forEach(a => console.log(`  ${icon.dot} ${a.name}`));
+	} else {
+		console.log(`${icon.warn} No AI agents detected automatically`);
+	}
+
+	// Step 2: Select agents
+	const selectedIds = await promptCheckboxes(
+		'Which agents do you want to configure?',
+		agents.map(a => ({ id: a.id, name: a.name, detected: a.detected }))
+	);
+	const selectedAgents = agents.filter(a => selectedIds.includes(a.id));
+
+	if (selectedAgents.length === 0) {
+		console.log(`\n${icon.cross} No agents selected. Exiting.`);
+		process.exit(0);
+	}
+
+	// Step 3: API Key
+	let apiKey: string | null = null;
+
+	// Check env var first
+	if (process.env.VIBESCOPE_API_KEY) {
+		apiKey = process.env.VIBESCOPE_API_KEY;
+		console.log(`\n${icon.check} Using API key from ${c.cyan}VIBESCOPE_API_KEY${c.reset} env var`);
+	}
+
+	// Check credentials file
+	if (!apiKey) {
+		const creds = readCredentials();
+		if (creds.apiKey) {
+			apiKey = creds.apiKey;
+			console.log(`\n${icon.check} Found existing API key in ${c.cyan}~/.vibescope/credentials.json${c.reset}`);
+			const reuse = await promptConfirm('Use existing API key?', true);
+			if (!reuse) apiKey = null;
+		}
+	}
+
+	// Prompt for key if needed
+	if (!apiKey) {
+		console.log(`\n${c.bold}API Key Setup${c.reset}`);
+		console.log(`${icon.arrow} Get your API key at ${c.cyan}${VIBESCOPE_SETTINGS_URL}${c.reset}`);
+
+		const openIt = await promptConfirm('Open settings page in browser?', true);
+		if (openIt) await openBrowser(VIBESCOPE_SETTINGS_URL);
+
+		for (let attempt = 0; attempt < 3; attempt++) {
+			apiKey = await prompt(`\n${c.bold}Paste your API key:${c.reset} `);
+			if (!apiKey) {
+				console.log(`${icon.cross} API key is required`);
+				continue;
+			}
+			process.stdout.write(`  Validating... `);
+			const result = await validateApiKey(apiKey);
+			if (result.valid) {
+				console.log(`${icon.check} ${result.message}`);
+				break;
+			} else {
+				console.log(`${icon.cross} ${result.message}`);
+				apiKey = null;
+			}
+		}
+
+		if (!apiKey) {
+			console.log(`\n${icon.cross} Could not get a valid API key. Exiting.`);
+			process.exit(1);
+		}
+
+		// Store credentials
+		try {
+			writeCredentials(apiKey);
+			console.log(`\n${icon.check} API key saved to ${c.cyan}~/.vibescope/credentials.json${c.reset}`);
+		} catch (err) {
+			console.log(`\n${icon.warn} Could not save credentials: ${err instanceof Error ? err.message : 'unknown error'}`);
+			console.log(`  ${c.dim}Set VIBESCOPE_API_KEY env var as fallback${c.reset}`);
+		}
+	}
+
+	// Step 4: Configure each agent
+	console.log(`\n${c.bold}Configuring agents...${c.reset}\n`);
+
+	for (const agent of selectedAgents) {
+		const hasExisting = checkExistingConfig(agent.id);
+		if (hasExisting) {
+			const overwrite = await promptConfirm(`  ${agent.name} already configured. Update?`, true);
+			if (!overwrite) {
+				console.log(`  ${icon.dot} Skipped ${agent.name}`);
+				continue;
+			}
+		}
+		try {
+			await agent.configure(apiKey);
+		} catch (err) {
+			console.log(`  ${icon.cross} Failed to configure ${agent.name}: ${err instanceof Error ? err.message : 'unknown error'}`);
+		}
+	}
+
+	// Step 5: Generate or update .claude/CLAUDE.md
+	const claudeMdPath = join(process.cwd(), '.claude', 'CLAUDE.md');
+	const claudeDir = join(process.cwd(), '.claude');
+	if (!existsSync(claudeDir)) {
+		mkdirSync(claudeDir, { recursive: true });
+	}
+
+	const vibescopeGuidelines = getAgentGuidelinesTemplate();
+
+	if (existsSync(claudeMdPath)) {
+		const existing = readFileSync(claudeMdPath, 'utf-8');
+		const hasVibescopeSection = existing.includes(VIBESCOPE_SECTION_START);
+
+		if (hasVibescopeSection) {
+			// Replace existing Vibescope section
+			const update = await promptConfirm(`\n  ${c.cyan}.claude/CLAUDE.md${c.reset} already has Vibescope guidelines. Update them?`, true);
+			if (update) {
+				const startIdx = existing.indexOf(VIBESCOPE_SECTION_START);
+				const endIdx = existing.indexOf(VIBESCOPE_SECTION_END);
+				if (startIdx !== -1 && endIdx !== -1) {
+					const updated = existing.substring(0, startIdx) + vibescopeGuidelines + existing.substring(endIdx + VIBESCOPE_SECTION_END.length);
+					writeFileSync(claudeMdPath, updated);
+					console.log(`  ${icon.check} Updated Vibescope section in ${c.cyan}.claude/CLAUDE.md${c.reset}`);
+				}
+			} else {
+				console.log(`  ${icon.dot} Skipped CLAUDE.md update`);
+			}
+		} else {
+			// Append Vibescope guidelines to existing file
+			const append = await promptConfirm(`\n  ${c.cyan}.claude/CLAUDE.md${c.reset} exists. Append Vibescope guidelines?`, true);
+			if (append) {
+				const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+				writeFileSync(claudeMdPath, existing + separator + vibescopeGuidelines);
+				console.log(`  ${icon.check} Appended Vibescope guidelines to ${c.cyan}.claude/CLAUDE.md${c.reset}`);
+			} else {
+				console.log(`  ${icon.dot} Skipped CLAUDE.md`);
+			}
+		}
+	} else {
+		writeFileSync(claudeMdPath, vibescopeGuidelines);
+		console.log(`  ${icon.check} Created ${c.cyan}.claude/CLAUDE.md${c.reset} with agent guidelines`);
+	}
+
+	// Done!
+	console.log(`
+${c.green}${c.bold}Setup complete!${c.reset}
+
+${c.bold}Next steps:${c.reset}
+  ${icon.arrow} Restart your AI agent / IDE
+  ${icon.arrow} Start coding — Vibescope tracks automatically
+
+${c.dim}Need help? https://vibescope.dev/docs${c.reset}
+`);
+}
+
+// ============================================================================
+// CLI Entry Point
+// ============================================================================
+
+async function main() {
+	const args = process.argv.slice(2);
+	const command = args[0];
+
+	if (command === 'init' || !command) {
+		await runInit();
+	} else if (command === '--help' || command === '-h' || command === 'help') {
+		console.log(`
+${c.bold}Vibescope CLI${c.reset}
+
+Usage:
+  npx vibescope init     Set up Vibescope for your AI agents
+  npx vibescope help     Show this help
+
+Docs: https://vibescope.dev/docs
+`);
+	} else {
+		console.log(`Unknown command: ${command}\nRun ${c.cyan}npx vibescope help${c.reset} for usage.`);
+		process.exit(1);
+	}
+}
+
+const isMainModule = import.meta.url === `file://${process.argv[1]?.replace(/\\/g, '/')}`;
+if (isMainModule || process.argv[1]?.endsWith('cli-init.js')) {
+	main().catch((err) => {
+		console.error(`${icon.cross} ${err instanceof Error ? err.message : 'Unknown error'}`);
+		process.exit(1);
+	});
+}