xtrm-cli 0.5.0

package/src/utils/sync-mcp-cli.ts

@@ -0,0 +1,395 @@
+import { execSync, exec } from 'child_process';
+import { promisify } from 'util';
+const execAsync = promisify(exec);
+import fs from 'fs-extra';
+import path from 'path';
+import kleur from 'kleur';
+// @ts-ignore
+import ora from 'ora';
+import { ensureEnvFile, loadEnvFile, checkRequiredEnvVars, handleMissingEnvVars, getEnvFilePath } from './env-manager.js';
+
+export type AgentName = 'claude';
+
+interface AgentCLI {
+    command: string;
+    listArgs: string[];
+    addStdio: (name: string, cmd: string, args?: string[], env?: Record<string, string>) => string[];
+    addHttp: (name: string, url: string, headers?: Record<string, string>) => string[];
+    addSse: (name: string, url: string) => string[];
+    remove: (name: string) => string[];
+    parseList: (output: string) => string[];
+}
+
+const AGENT_CLI: Record<AgentName, AgentCLI> = {
+    claude: {
+        command: 'claude',
+        listArgs: ['mcp', 'list'],
+        addStdio: (name, cmd, args, env) => {
+            const base = ['mcp', 'add', '-s', 'user', name, '--'];
+            if (env && Object.keys(env).length > 0) {
+                for (const [key, value] of Object.entries(env)) {
+                    base.push('-e', `${key}=${resolveEnvVar(value)}`);
+                }
+            }
+            base.push(cmd, ...(args || []));
+            return base;
+        },
+        addHttp: (name, url, headers) => {
+            const base = ['mcp', 'add', '-s', 'user', '--transport', 'http', name, url];
+            if (headers) {
+                for (const [key, value] of Object.entries(headers)) {
+                    base.push('--header', `${key}: ${resolveEnvVar(value)}`);
+                }
+            }
+            return base;
+        },
+        addSse: (name, url) => {
+            return ['mcp', 'add', '-s', 'user', '--transport', 'sse', name, url];
+        },
+        remove: (name) => ['mcp', 'remove', '-s', 'user', name],
+        parseList: (output) => parseMcpListOutput(output, /^([a-zA-Z0-9_-]+):/)
+    },
+};
+
+// Strip ANSI escape codes (e.g. qwen wraps ✓ in color codes)
+function stripAnsi(str: string): string {
+    return str.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+function parseMcpListOutput(output: string, pattern: RegExp): string[] {
+    const servers: string[] = [];
+    for (const line of output.split('\n')) {
+        const match = stripAnsi(line).match(pattern);
+        if (match) {
+            servers.push(match[1]);
+        }
+    }
+    return servers;
+}
+
+function resolveEnvVar(value: string): string {
+    if (typeof value !== 'string') return value;
+
+    return value.replace(/\$\{([A-Z0-9_]+)\}/g, (_match, envName) => {
+        const upperName = envName.toUpperCase();
+        const envValue = process.env[upperName];
+        if (envValue) {
+            return envValue;
+        } else {
+            console.warn(kleur.yellow(`  ⚠️  Environment variable ${upperName} is not set in ${getEnvFilePath()}`));
+            return '';
+        }
+    });
+}
+
+export function detectAgent(systemRoot: string): AgentName | null {
+    const normalizedRoot = systemRoot.replace(/\\/g, '/').toLowerCase();
+    if (normalizedRoot.includes('.claude') || normalizedRoot.includes('/claude')) {
+        return 'claude';
+    }
+    return null;
+}
+
+function buildAddCommand(agent: AgentName, name: string, server: any): string[] | null {
+    const cli = AGENT_CLI[agent];
+    if (!cli) return null;
+
+    if (server.url || server.serverUrl) {
+        const url = server.url || server.serverUrl;
+        const type = server.type || (url.includes('/sse') ? 'sse' : 'http');
+
+        if (type === 'sse') {
+            return cli.addSse(name, url);
+        } else {
+            return cli.addHttp(name, url, server.headers);
+        }
+    }
+
+    if (server.command) {
+        return cli.addStdio(name, server.command, server.args, server.env);
+    }
+
+    console.warn(kleur.yellow(`  ⚠️  Skipping server "${name}": Unknown configuration`));
+    return null;
+}
+
+interface CommandResult {
+    success: boolean;
+    dryRun?: boolean;
+    skipped?: boolean;
+    error?: string;
+}
+
+function executeCommand(agent: AgentName, args: string[], dryRun: boolean = false, displayName?: string): CommandResult {
+    const cli = AGENT_CLI[agent];
+
+    const quotedArgs = args.map(arg => {
+        if (arg.includes(' ') && !arg.startsWith('"') && !arg.startsWith("'")) {
+            return `"${arg}"`;
+        }
+        return arg;
+    });
+    const command = `${cli.command} ${quotedArgs.join(' ')}`;
+
+    if (dryRun) {
+        console.log(kleur.cyan(`  [DRY RUN] ${displayName ?? args.slice(2).join(' ')}`));
+        return { success: true, dryRun: true };
+    }
+
+    try {
+        execSync(command, { stdio: 'pipe', timeout: 10000 });
+        console.log(kleur.green(`  ✓ ${displayName ?? args.slice(2).join(' ')}`));
+        return { success: true };
+    } catch (error: any) {
+        const stderr = error.stderr?.toString() || error.message;
+
+        if (stderr.includes('already exists') || stderr.includes('already configured')) {
+            let serverName = 'unknown';
+            if (agent === 'claude') {
+                const addIndex = args.indexOf('add');
+                for (let i = addIndex + 1; i < args.length; i++) {
+                    const arg = args[i];
+                    if (arg === '--') continue;
+                    if (arg.startsWith('-')) continue;
+                    if (['local', 'user', 'project', 'http', 'sse', 'stdio'].includes(arg)) continue;
+                    serverName = arg;
+                    break;
+                }
+            }
+            console.log(kleur.dim(`  ✓ ${serverName} (already configured)`));
+            return { success: true, skipped: true };
+        }
+
+        console.log(kleur.red(`  ✗ Failed: ${stderr.trim()}`));
+        return { success: false, error: stderr };
+    }
+}
+
+export function getCurrentServers(agent: AgentName): string[] {
+    const cli = AGENT_CLI[agent];
+    try {
+        const output = execSync(`${cli.command} ${cli.listArgs.join(' ')}`, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+        return cli.parseList(output);
+    } catch (error: any) {
+        // Some CLIs (e.g. gemini) write server list to stderr
+        const combined = (error.stdout || '') + '\n' + (error.stderr || '');
+        return cli.parseList(combined);
+    }
+}
+
+export async function getCurrentServersAsync(agent: AgentName): Promise<string[]> {
+    const cli = AGENT_CLI[agent];
+    try {
+        const { stdout, stderr } = await execAsync(`${cli.command} ${cli.listArgs.join(' ')}`, {
+            timeout: 10000,
+        });
+        // Some CLIs (e.g. gemini) write server list to stderr
+        return cli.parseList(stdout + '\n' + stderr);
+    } catch (error) {
+        return [];
+    }
+}
+
+/**
+ * Extract ${VAR_NAME} references from a list of server config objects
+ */
+function getServerEnvVarNames(servers: any[]): string[] {
+    const vars = new Set<string>();
+    const pattern = /\$\{([A-Z0-9_]+)\}/g;
+    for (const server of servers) {
+        const json = JSON.stringify(server);
+        let match;
+        const re = new RegExp(pattern.source, pattern.flags);
+        while ((match = re.exec(json)) !== null) {
+            vars.add(match[1]);
+        }
+    }
+    return Array.from(vars);
+}
+
+/**
+ * Sync MCP servers to an agent using official CLI
+ */
+// Prevents ensureEnvFile/loadEnvFile from firing once per target directory
+let envInitialized = false;
+
+export async function syncMcpServersWithCli(
+    agent: AgentName,
+    mcpConfig: any,
+    dryRun: boolean = false,
+    prune: boolean = false
+): Promise<void> {
+    const cli = AGENT_CLI[agent];
+    if (!cli) {
+        console.log(kleur.yellow(`  ⚠️  Unsupported agent: ${agent}`));
+        return;
+    }
+
+    if (!envInitialized) {
+        ensureEnvFile();
+        loadEnvFile();
+        envInitialized = true;
+    }
+
+    const spinner = ora({ text: kleur.dim('  checking installed servers…'), indent: 2 }).start();
+    const currentServers = await getCurrentServersAsync(agent);
+    spinner.stop();
+    const currentServersSet = new Set(currentServers);
+    const canonicalServers = new Set(Object.keys(mcpConfig.mcpServers || {}));
+
+    if (prune) {
+        const toRemove = currentServers.filter(s => !canonicalServers.has(s));
+        if (toRemove.length > 0) {
+            console.log(kleur.red(`  Pruning ${toRemove.length} server(s)...`));
+            for (const serverName of toRemove) {
+                executeCommand(agent, cli.remove(serverName), dryRun);
+            }
+        }
+    }
+
+    // Determine which servers actually need to be added
+    const toAdd = Object.entries(mcpConfig.mcpServers || {}).filter(([name]) => !currentServersSet.has(name));
+    const skippedCount = canonicalServers.size - toAdd.length;
+
+    if (toAdd.length === 0) {
+        // Nothing to add — skip env warning, no CLI calls needed
+        console.log(kleur.dim(`  ✓ ${skippedCount} server(s) already installed`));
+        return;
+    }
+
+    // Step 1: Multiselect — all servers pre-selected, user can deselect with space
+    let selectedNames: string[] = toAdd.map(([name]) => name);
+
+    if (!dryRun) {
+        // @ts-ignore
+        const prompts = await import('prompts');
+        const { selected } = await prompts.default({
+            type: 'multiselect',
+            name: 'selected',
+            message: `Select MCP servers to install via ${agent} CLI:`,
+            choices: toAdd.map(([name, server]: [string, any]) => ({
+                title: name,
+                description: (server as any)._notes?.description || '',
+                value: name,
+                selected: true
+            })),
+            hint: '- Space to toggle. Enter to confirm.',
+            instructions: false
+        });
+
+        if (!selected || selected.length === 0) {
+            console.log(kleur.gray('  Skipped MCP installation.'));
+            return;
+        }
+
+        selectedNames = selected;
+
+        // Step 2: Only ask for env vars needed by the selected servers
+        const selectedEntries = toAdd.filter(([name]) => new Set(selectedNames).has(name));
+        const neededVarNames = getServerEnvVarNames(selectedEntries.map(([, s]) => s as any));
+        const missingEnvVars = checkRequiredEnvVars(neededVarNames);
+        if (missingEnvVars.length > 0) {
+            const shouldProceed = await handleMissingEnvVars(missingEnvVars);
+            if (!shouldProceed) return;
+        }
+    }
+
+    // Step 3: Build and execute commands for selected servers only
+    const selectedSet = new Set(selectedNames);
+    const commandsToRun: Array<{ name: string; cmd: string[] }> = [];
+    for (const [name, server] of toAdd) {
+        if (!selectedSet.has(name)) continue;
+        const cmd = buildAddCommand(agent, name, server as any);
+        if (cmd) commandsToRun.push({ name, cmd });
+    }
+
+    if (commandsToRun.length === 0) return;
+
+    let successCount = 0;
+    for (const { name, cmd } of commandsToRun) {
+        const result = executeCommand(agent, cmd, dryRun, name);
+        if (result.success && !result.skipped) {
+            successCount++;
+        }
+    }
+
+    if (skippedCount > 0) {
+        console.log(kleur.dim(`  ✓ ${skippedCount} already installed, ${successCount} added`));
+    } else {
+        console.log(kleur.green(`  ✓ ${successCount} server(s) added`));
+    }
+}
+
+/**
+ * Load canonical MCP config from repository
+ */
+export function loadCanonicalMcpConfig(repoRoot: string, includeOptional: boolean = false): any {
+    const corePath = path.join(repoRoot, 'config', 'mcp_servers.json');
+    const optionalPath = path.join(repoRoot, 'config', 'mcp_servers_optional.json');
+
+    const config: any = { mcpServers: {} };
+
+    if (fs.existsSync(corePath)) {
+        const core = fs.readJsonSync(corePath);
+        config.mcpServers = { ...config.mcpServers, ...core.mcpServers };
+    }
+
+    if (includeOptional && fs.existsSync(optionalPath)) {
+        const optional = fs.readJsonSync(optionalPath);
+        config.mcpServers = { ...config.mcpServers, ...optional.mcpServers };
+    }
+
+    return config;
+}
+
+/**
+ * Prompt user to select optional MCP servers
+ */
+export async function promptOptionalServers(repoRoot: string): Promise<string[] | false> {
+    const optionalPath = path.join(repoRoot, 'config', 'mcp_servers_optional.json');
+
+    if (!fs.existsSync(optionalPath)) {
+        return false;
+    }
+
+    const optional = fs.readJsonSync(optionalPath);
+    const servers = Object.entries(optional.mcpServers || {}).map(([name, server]: [string, any]) => ({
+        name,
+        description: server._notes?.description || 'No description',
+        prerequisite: server._notes?.prerequisite || ''
+    }));
+
+    if (servers.length === 0) {
+        return false;
+    }
+
+    // @ts-ignore
+    const prompts = await import('prompts');
+
+    const { selected } = await prompts.default({
+        type: 'multiselect',
+        name: 'selected',
+        message: 'Optional MCP servers available — select to install (space to toggle, enter to confirm):',
+        choices: servers.map(s => ({
+            title: s.name,
+            description: s.prerequisite
+                ? `${s.description} — ⚠️  ${s.prerequisite}`
+                : s.description,
+            value: s.name,
+            selected: false
+        })),
+        hint: '- Space to select. Enter to skip or confirm.',
+        instructions: false
+    });
+
+    if (!selected || selected.length === 0) {
+        console.log(kleur.gray('  Skipping optional servers.\n'));
+        return false;
+    }
+
+    console.log(kleur.green(`  Selected: ${selected.join(', ')}\n`));
+    return selected;
+}

package/src/utils/theme.ts

@@ -0,0 +1,37 @@
+import kleur from 'kleur';
+
+/** Semantic color tokens */
+export const t = {
+    // Status
+    success:   (s: string) => kleur.green(s),
+    error:     (s: string) => kleur.red(s),
+    warning:   (s: string) => kleur.yellow(s),
+    info:      (s: string) => kleur.cyan(s),       // was blue — unreadable on dark terminals
+
+    // Hierarchy (3-tier weight system)
+    header:    (s: string) => kleur.bold().white(s),  // section headers
+    label:     (s: string) => kleur.dim(s),           // metadata labels
+    muted:     (s: string) => kleur.gray(s),
+    accent:    (s: string) => kleur.cyan(s),
+    bold:      (s: string) => kleur.bold(s),
+    dim:       (s: string) => kleur.dim(s),
+
+    // Compound
+    boldGreen: (s: string) => kleur.bold().green(s),
+    boldRed:   (s: string) => kleur.bold().red(s),
+};
+
+/** Status symbols with colour baked in */
+export const sym = {
+    ok:       kleur.green('✓'),
+    fail:     kleur.red('✗'),
+    warn:     kleur.yellow('⚠'),
+
+    // File change states — directional metaphor
+    missing:  kleur.green('+'),
+    outdated: kleur.yellow('↑'),
+    drifted:  kleur.magenta('≠'),    // was red '!' — magenta = conflict/divergence
+
+    arrow:    kleur.gray('→'),
+    bullet:   kleur.gray('•'),
+};

package/src/utils/worktree-session.ts

@@ -0,0 +1,93 @@
+import kleur from 'kleur';
+import path from 'node:path';
+import fs from 'fs-extra';
+import { execSync, spawnSync } from 'node:child_process';
+import { findRepoRoot } from './repo-root.js';
+
+export interface WorktreeSessionOptions {
+    runtime: 'claude' | 'pi';
+    name?: string;
+}
+
+function randomSlug(len: number = 4): string {
+    return Math.random().toString(36).slice(2, 2 + len);
+}
+
+function shortDate(): string {
+    const d = new Date();
+    return `${d.getFullYear()}${String(d.getMonth() + 1).padStart(2, '0')}${String(d.getDate()).padStart(2, '0')}`;
+}
+
+/**
+ * Launch a Claude or Pi session in a sandboxed git worktree.
+ *
+ * Worktree path: sibling to CWD, named <cwd-basename>-xt-<runtime>-<shortdate>
+ * Branch: xt/<name> if name provided, xt/<4-char-random> otherwise
+ * Dolt bootstrap: redirect worktree to main's canonical beads db
+ */
+export async function launchWorktreeSession(opts: WorktreeSessionOptions): Promise<void> {
+    const { runtime, name } = opts;
+    const cwd = process.cwd();
+    const repoRoot = await findRepoRoot();
+    const cwdBasename = path.basename(cwd);
+
+    // Resolve worktree path (sibling to cwd)
+    const date = shortDate();
+    const worktreeName = `${cwdBasename}-xt-${runtime}-${date}`;
+    const worktreePath = path.join(path.dirname(cwd), worktreeName);
+
+    // Resolve branch name
+    const branchName = `xt/${name ?? randomSlug(4)}`;
+
+    console.log(kleur.bold(`\n  Launching ${runtime} session`));
+    console.log(kleur.dim(`  worktree: ${worktreePath}`));
+    console.log(kleur.dim(`  branch:   ${branchName}\n`));
+
+    // Create worktree (create branch if it doesn't exist)
+    const branchExists = spawnSync('git', ['rev-parse', '--verify', branchName], {
+        cwd: repoRoot, stdio: 'pipe',
+    }).status === 0;
+
+    const worktreeArgs = branchExists
+        ? ['worktree', 'add', worktreePath, branchName]
+        : ['worktree', 'add', '-b', branchName, worktreePath];
+
+    const worktreeResult = spawnSync('git', worktreeArgs, { cwd: repoRoot, stdio: 'inherit' });
+    if (worktreeResult.status !== 0) {
+        console.error(kleur.red(`\n  ✗ Failed to create worktree at ${worktreePath}\n`));
+        process.exit(1);
+    }
+
+    // Dolt bootstrap: redirect worktree to main's canonical beads db
+    const mainBeadsDir = path.join(repoRoot, '.beads');
+    const worktreeBeadsDir = path.join(worktreePath, '.beads');
+    const mainPortFile = path.join(mainBeadsDir, 'dolt-server.port');
+
+    if (await fs.pathExists(mainBeadsDir)) {
+        const worktreePortFile = path.join(worktreeBeadsDir, 'dolt-server.port');
+
+        // Stop the auto-spawned isolated dolt server in the worktree
+        spawnSync('bd', ['dolt', 'stop'], { cwd: worktreePath, stdio: 'pipe' });
+
+        // Read main checkout's port and write to worktree
+        if (await fs.pathExists(mainPortFile)) {
+            const mainPort = (await fs.readFile(mainPortFile, 'utf8')).trim();
+            await fs.ensureDir(worktreeBeadsDir);
+            await fs.writeFile(worktreePortFile, mainPort, 'utf8');
+            console.log(kleur.dim(`  beads: redirected to main server (port ${mainPort})`));
+        } else {
+            console.log(kleur.dim('  beads: no port file found in main checkout, skipping redirect'));
+        }
+    }
+
+    console.log(kleur.green(`\n  ✓ Worktree ready — launching ${runtime}...\n`));
+
+    // Launch the runtime in the worktree
+    const runtimeCmd = runtime === 'claude' ? 'claude' : 'pi';
+    const launchResult = spawnSync(runtimeCmd, [], {
+        cwd: worktreePath,
+        stdio: 'inherit',
+    });
+
+    process.exit(launchResult.status ?? 0);
+}

package/test/atomic-config-prune.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest';
+import { deepMergeWithProtection } from '../src/utils/atomic-config.js';
+
+const hooksDir = '/home/user/.claude/hooks';
+const cmd = (script: string) => `node "${hooksDir}/${script}"`;
+
+function wrap(matcher: string, script: string, timeout = 5000) {
+    return { matcher, hooks: [{ type: 'command', command: cmd(script), timeout }] };
+}
+
+function wrapNoMatcher(script: string) {
+    return { hooks: [{ type: 'command', command: cmd(script) }] };
+}
+
+const canonicalHooks = {
+    SessionStart: [wrapNoMatcher('beads-compact-restore.mjs'), wrapNoMatcher('serena-workflow-reminder.py')],
+    UserPromptSubmit: [{ ...wrapNoMatcher('branch-state.mjs'), timeout: 3000 }],
+    PreToolUse: [
+        wrap('Write|Edit|MultiEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol', 'main-guard.mjs'),
+        wrap('Bash', 'main-guard.mjs'),
+    ],
+    PostToolUse: [
+        wrap('Bash|mcp__serena__find_symbol|mcp__serena__get_symbols_overview', 'gitnexus/gitnexus-hook.cjs', 10000),
+    ],
+};
+
+describe('deepMergeWithProtection — pruneHooks mode', () => {
+    it('replaces stale PreToolUse matcher with canonical one', () => {
+        const existing = {
+            hooks: {
+                PreToolUse: [
+                    wrap('Read|Grep|Glob|Write|Edit|MultiEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol', 'main-guard.mjs'),
+                    wrap('Bash', 'main-guard.mjs'),
+                ],
+            },
+        };
+
+        const result = deepMergeWithProtection(existing, { hooks: canonicalHooks }, '', { pruneHooks: true });
+        const preToolUse = result.hooks.PreToolUse;
+        expect(preToolUse).toHaveLength(2);
+        expect(preToolUse[0].matcher).toBe('Write|Edit|MultiEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol');
+        expect(preToolUse[1].matcher).toBe('Bash');
+    });
+
+    it('removes script wired to wrong event (serena-workflow-reminder.py in PreToolUse)', () => {
+        const existing = {
+            hooks: {
+                SessionStart: [wrapNoMatcher('serena-workflow-reminder.py')],
+                PreToolUse: [
+                    wrap('Read|Edit', 'serena-workflow-reminder.py'),
+                    wrap('Write|Edit|MultiEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol', 'main-guard.mjs'),
+                    wrap('Bash', 'main-guard.mjs'),
+                ],
+            },
+        };
+
+        const result = deepMergeWithProtection(existing, { hooks: canonicalHooks }, '', { pruneHooks: true });
+        const preToolUse = result.hooks.PreToolUse;
+        const hasStale = preToolUse.some((w: any) =>
+            w.hooks?.some((h: any) => h.command?.includes('serena-workflow-reminder.py'))
+        );
+        expect(hasStale).toBe(false);
+        expect(preToolUse).toHaveLength(2);
+    });
+
+    it('preserves user-local hooks (not from ~/.claude/hooks/) in canonical events', () => {
+        const userLocalHook = { hooks: [{ type: 'command', command: '/usr/local/bin/my-custom-hook.sh' }] };
+        const existing = {
+            hooks: {
+                PreToolUse: [
+                    wrap('Bash', 'main-guard.mjs'),
+                    userLocalHook,
+                ],
+            },
+        };
+
+        const result = deepMergeWithProtection(existing, { hooks: canonicalHooks }, '', { pruneHooks: true });
+        const preToolUse = result.hooks.PreToolUse;
+        const hasUserLocal = preToolUse.some((w: any) =>
+            w.hooks?.some((h: any) => h.command === '/usr/local/bin/my-custom-hook.sh')
+        );
+        expect(hasUserLocal).toBe(true);
+    });
+
+    it('normal merge (no pruneHooks) preserves stale matcher tokens', () => {
+        const existing = {
+            hooks: {
+                PreToolUse: [
+                    wrap('Read|Grep|Glob|Write|Edit|Bash', 'main-guard.mjs'),
+                ],
+            },
+        };
+
+        const result = deepMergeWithProtection(existing, { hooks: canonicalHooks }, '', { pruneHooks: false });
+        const preToolUse = result.hooks.PreToolUse;
+        const matcher = preToolUse.find((w: any) =>
+            w.hooks?.some((h: any) => h.command?.includes('main-guard.mjs'))
+        )?.matcher ?? '';
+        expect(matcher).toContain('Read');
+    });
+});