xtrm-cli 0.5.0

package/lib/diff.js

@@ -0,0 +1,142 @@
+import path from 'path';
+import fs from 'fs-extra';
+import crypto from 'crypto';
+
+/**
+ * Calculate MD5 hash of a file or directory
+ */
+async function getHash(targetPath) {
+    if (!fs.existsSync(targetPath)) return null;
+
+    const stats = await fs.stat(targetPath);
+
+    if (stats.isDirectory()) {
+        const children = await fs.readdir(targetPath);
+        const childHashes = await Promise.all(
+            children.sort().map(async child => {
+                const h = await getHash(path.join(targetPath, child));
+                return `${child}:${h}`;
+            })
+        );
+        return crypto.createHash('md5').update(childHashes.join('|')).digest('hex');
+    } else {
+        const content = await fs.readFile(targetPath);
+        return crypto.createHash('md5').update(content).digest('hex');
+    }
+}
+
+async function getNewestMtime(targetPath) {
+    const stats = await fs.stat(targetPath);
+    let maxTime = stats.mtimeMs;
+
+    if (stats.isDirectory()) {
+        const children = await fs.readdir(targetPath);
+        for (const child of children) {
+            const childPath = path.join(targetPath, child);
+            const childTime = await getNewestMtime(childPath);
+            if (childTime > maxTime) maxTime = childTime;
+        }
+    }
+    return maxTime;
+}
+
+export async function calculateDiff(repoRoot, systemRoot) {
+    const isClaude = systemRoot.includes('.claude') || systemRoot.includes('Claude');
+    const isQwen = systemRoot.includes('.qwen') || systemRoot.includes('Qwen');
+    const isGemini = systemRoot.includes('.gemini') || systemRoot.includes('Gemini');
+
+    const changeSet = {
+        skills: { missing: [], outdated: [], drifted: [], total: 0 },
+        hooks: { missing: [], outdated: [], drifted: [], total: 0 },
+        config: { missing: [], outdated: [], drifted: [], total: 0 },
+        commands: { missing: [], outdated: [], drifted: [], total: 0 },
+        'qwen-commands': { missing: [], outdated: [], drifted: [], total: 0 },
+        'antigravity-workflows': { missing: [], outdated: [], drifted: [], total: 0 }
+    };
+
+    // 1. Folders: Skills & Hooks & Commands (for different environments)
+    const folders = ['skills', 'hooks'];
+    if (isQwen) {
+        folders.push('qwen-commands');
+    } else if (isGemini) {
+        folders.push('commands', 'antigravity-workflows');
+    } else if (!isClaude) {
+        folders.push('commands');
+    }
+
+    for (const category of folders) {
+        let repoPath;
+        if (category === 'commands') {
+            // Commands are always in .gemini/commands in repo
+            repoPath = path.join(repoRoot, '.gemini', 'commands');
+        } else if (category === 'qwen-commands') {
+            // Qwen commands are in .qwen/commands in repo
+            repoPath = path.join(repoRoot, '.qwen', 'commands');
+        } else if (category === 'antigravity-workflows') {
+            // Antigravity workflows are in .gemini/antigravity/global_workflows in repo
+            repoPath = path.join(repoRoot, '.gemini', 'antigravity', 'global_workflows');
+        } else {
+            repoPath = path.join(repoRoot, category);
+        }
+        
+        let systemPath;
+        if (category === 'qwen-commands') {
+            systemPath = path.join(systemRoot, 'commands');
+        } else if (category === 'antigravity-workflows') {
+            systemPath = path.join(systemRoot, '.gemini', 'antigravity', 'global_workflows');
+        } else if (category === 'commands') {
+            systemPath = path.join(systemRoot, category);
+        } else {
+            systemPath = path.join(systemRoot, category);
+        }
+
+        if (!fs.existsSync(repoPath)) continue;
+
+        const items = await fs.readdir(repoPath);
+        changeSet[category].total = items.length;
+
+        for (const item of items) {
+            const itemRepoPath = path.join(repoPath, item);
+            const itemSystemPath = path.join(systemPath, item);
+
+            await compareItem(category, item, itemRepoPath, itemSystemPath, changeSet);
+        }
+    }
+
+    // 2. Config Files (Explicit Mapping)
+    const configMapping = {
+        'settings.json': { repo: 'config/settings.json', sys: 'settings.json' }
+    };
+
+    for (const [name, paths] of Object.entries(configMapping)) {
+        const itemRepoPath = path.join(repoRoot, paths.repo);
+        const itemSystemPath = path.join(systemRoot, paths.sys);
+        
+        if (fs.existsSync(itemRepoPath)) {
+            await compareItem('config', name, itemRepoPath, itemSystemPath, changeSet);
+        }
+    }
+
+    return changeSet;
+}
+
+async function compareItem(category, item, repoPath, systemPath, changeSet) {
+    if (!fs.existsSync(systemPath)) {
+        changeSet[category].missing.push(item);
+        return;
+    }
+
+    const repoHash = await getHash(repoPath);
+    const systemHash = await getHash(systemPath);
+
+    if (repoHash !== systemHash) {
+        const repoMtime = await getNewestMtime(repoPath);
+        const systemMtime = await getNewestMtime(systemPath);
+
+        if (systemMtime > repoMtime + 2000) {
+            changeSet[category].drifted.push(item);
+        } else {
+            changeSet[category].outdated.push(item);
+        }
+    }
+}

package/lib/env-manager.js

@@ -0,0 +1,160 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import kleur from 'kleur';
+import dotenv from 'dotenv';
+
+/**
+ * Environment file location: ~/.config/jaggers-agent-tools/.env
+ */
+const CONFIG_DIR = path.join(os.homedir(), '.config', 'jaggers-agent-tools');
+const ENV_FILE = path.join(CONFIG_DIR, '.env');
+const ENV_EXAMPLE_FILE = path.join(CONFIG_DIR, '.env.example');
+
+/**
+ * Required environment variables for MCP servers
+ */
+const REQUIRED_ENV_VARS = {
+  'CONTEXT7_API_KEY': {
+    description: 'Context7 MCP server API key',
+    example: 'ctx7sk-your-api-key-here',
+    getUrl: () => 'https://context7.com/'
+  }
+};
+
+/**
+ * Ensure config directory and .env file exist
+ */
+export function ensureEnvFile() {
+  // Create config directory if missing
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.ensureDirSync(CONFIG_DIR);
+    console.log(kleur.gray(`  Created config directory: ${CONFIG_DIR}`));
+  }
+
+  // Create .env.example if missing
+  if (!fs.existsSync(ENV_EXAMPLE_FILE)) {
+    createEnvExample();
+  }
+
+  // Create .env if missing
+  if (!fs.existsSync(ENV_FILE)) {
+    createEnvFile();
+    return false; // File was created (user needs to fill it)
+  }
+
+  return true; // File already exists
+}
+
+/**
+ * Create .env.example file
+ */
+function createEnvExample() {
+  const content = [
+    '# Jaggers Agent Tools - Environment Variables',
+    '# Copy this file to .env and fill in your actual values',
+    '',
+    ...Object.entries(REQUIRED_ENV_VARS).map(([key, config]) => {
+      return [
+        `# ${config.description}`,
+        `# Get your key from: ${config.getUrl()}`,
+        `${key}=${config.example}`,
+        ''
+      ].join('\n');
+    }).join('\n'),
+    '# See config/.env.example in the repository for all available options',
+    ''
+  ];
+
+  fs.writeFileSync(ENV_EXAMPLE_FILE, content);
+  console.log(kleur.gray(`  Created example file: ${ENV_EXAMPLE_FILE}`));
+}
+
+/**
+ * Create empty .env file with header
+ */
+function createEnvFile() {
+  const content = [
+    '# Jaggers Agent Tools - Environment Variables',
+    '# Generated automatically by jaggers-agent-tools CLI',
+    '',
+    '# Copy values from .env.example and fill in your actual keys',
+    '',
+  ].join('\n');
+
+  fs.writeFileSync(ENV_FILE, content);
+  console.log(kleur.green(`  Created environment file: ${ENV_FILE}`));
+}
+
+/**
+ * Load environment variables from .env file
+ * Also loads from process.env (which takes precedence)
+ */
+export function loadEnvFile() {
+  if (fs.existsSync(ENV_FILE)) {
+    const envConfig = dotenv.parse(fs.readFileSync(ENV_FILE));
+    
+    // Merge with process.env (process.env takes precedence)
+    for (const [key, value] of Object.entries(envConfig)) {
+      if (!process.env[key]) {
+        process.env[key] = value;
+      }
+    }
+    
+    return envConfig;
+  }
+  
+  return {};
+}
+
+/**
+ * Check if required environment variables are set
+ * Returns array of missing variable names
+ */
+export function checkRequiredEnvVars() {
+  const missing = [];
+  
+  for (const [key, config] of Object.entries(REQUIRED_ENV_VARS)) {
+    if (!process.env[key]) {
+      missing.push(key);
+    }
+  }
+  
+  return missing;
+}
+
+/**
+ * Prompt user about missing environment variables
+ * Returns true if user wants to proceed anyway
+ */
+export function handleMissingEnvVars(missing) {
+  if (missing.length === 0) {
+    return true;
+  }
+
+  console.log(kleur.yellow('\n  ⚠️  Missing environment variables:'));
+  for (const key of missing) {
+    const config = REQUIRED_ENV_VARS[key];
+    console.log(kleur.yellow(`    - ${key}: ${config.description}`));
+    console.log(kleur.dim(`      Get your key from: ${config.getUrl()}`));
+  }
+
+  console.log(kleur.yellow(`\n  Please edit: ${ENV_FILE}`));
+  console.log(kleur.gray(`  Or copy from example: ${ENV_EXAMPLE_FILE}`));
+  
+  return false; // Don't proceed automatically
+}
+
+/**
+ * Get the path to the .env file
+ */
+export function getEnvFilePath() {
+  return ENV_FILE;
+}
+
+/**
+ * Get the path to the config directory
+ */
+export function getConfigDir() {
+  return CONFIG_DIR;
+}

package/lib/sync-mcp-cli.js

@@ -0,0 +1,345 @@
+import { execSync } from 'child_process';
+import fs from 'fs-extra';
+import path from 'path';
+import kleur from 'kleur';
+import { ensureEnvFile, loadEnvFile, checkRequiredEnvVars, handleMissingEnvVars, getEnvFilePath } from './env-manager.js';
+
+/**
+ * Agent-specific MCP CLI handlers
+ */
+const AGENT_CLI = {
+  claude: {
+    command: 'claude',
+    listArgs: ['mcp', 'list'], // list doesn't support -s flag
+    addStdio: (name, cmd, args, env) => {
+      // Use -s user for user-level config (~/.claude.json global)
+      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) => {
+      // Use -s user for user-level config
+      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_-]+):/)
+  },
+  gemini: {
+    command: 'gemini',
+    listArgs: ['mcp', 'list'],
+    addStdio: (name, cmd, args, env) => {
+      const base = ['mcp', 'add', name, cmd];
+      if (args && args.length > 0) base.push(...args);
+      if (env && Object.keys(env).length > 0) {
+        for (const [key, value] of Object.entries(env)) {
+          base.push('-e', `${key}=${resolveEnvVar(value)}`);
+        }
+      }
+      return base;
+    },
+    addHttp: (name, url, headers) => {
+      const base = ['mcp', 'add', '-t', 'http', name, url];
+      if (headers) {
+        for (const [key, value] of Object.entries(headers)) {
+          base.push('-H', `${key}=${resolveEnvVar(value)}`);
+        }
+      }
+      return base;
+    },
+    addSse: (name, url) => {
+      return ['mcp', 'add', '-t', 'sse', name, url];
+    },
+    remove: (name) => ['mcp', 'remove', name],
+    parseList: (output) => parseMcpListOutput(output, /^✓ ([a-zA-Z0-9_-]+):/)
+  },
+  qwen: {
+    command: 'qwen',
+    listArgs: ['mcp', 'list'],
+    addStdio: (name, cmd, args, env) => {
+      const base = ['mcp', 'add', name, cmd];
+      if (args && args.length > 0) base.push(...args);
+      if (env && Object.keys(env).length > 0) {
+        for (const [key, value] of Object.entries(env)) {
+          base.push('-e', `${key}=${resolveEnvVar(value)}`);
+        }
+      }
+      return base;
+    },
+    addHttp: (name, url, headers) => {
+      const base = ['mcp', 'add', '-t', 'http', name, url];
+      if (headers) {
+        for (const [key, value] of Object.entries(headers)) {
+          base.push('-H', `${key}=${resolveEnvVar(value)}`);
+        }
+      }
+      return base;
+    },
+    addSse: (name, url) => {
+      return ['mcp', 'add', '-t', 'sse', name, url];
+    },
+    remove: (name) => ['mcp', 'remove', name],
+    parseList: (output) => parseMcpListOutput(output, /^✓ ([a-zA-Z0-9_-]+):/)
+  }
+};
+
+/**
+ * Parse MCP list output to extract server names
+ */
+function parseMcpListOutput(output, pattern) {
+  const servers = [];
+  for (const line of output.split('\n')) {
+    const match = line.match(pattern);
+    if (match) {
+      servers.push(match[1]);
+    }
+  }
+  return servers;
+}
+
+/**
+ * Resolve environment variable references like ${VAR}
+ */
+function resolveEnvVar(value) {
+  if (typeof value !== 'string') return value;
+  
+  const envMatch = value.match(/\$\{([A-Z0-9_]+)\}/i);
+  if (envMatch) {
+    const envName = envMatch[1];
+    const envValue = process.env[envName];
+    if (envValue) {
+      return envValue;
+    } else {
+      // Return empty string - server will be added but won't work until key is added
+      console.warn(kleur.yellow(`  ⚠️  Environment variable ${envName} is not set in ${getEnvFilePath()}`));
+      return '';
+    }
+  }
+  
+  return value;
+}
+
+/**
+ * Detect which agent CLI is available
+ */
+export function detectAgent(systemRoot) {
+  if (systemRoot.includes('.claude') || systemRoot.includes('Claude')) {
+    return 'claude';
+  } else if (systemRoot.includes('.gemini') || systemRoot.includes('Gemini')) {
+    return 'gemini';
+  } else if (systemRoot.includes('.qwen') || systemRoot.includes('Qwen')) {
+    return 'qwen';
+  }
+  return null;
+}
+
+/**
+ * Build MCP add commands for a server
+ */
+function buildAddCommand(agent, name, server) {
+  const cli = AGENT_CLI[agent];
+  if (!cli) return null;
+
+  // HTTP/SSE servers
+  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);
+    }
+  }
+  
+  // Stdio servers
+  if (server.command) {
+    return cli.addStdio(name, server.command, server.args, server.env);
+  }
+  
+  console.warn(kleur.yellow(`  ⚠️  Skipping server "${name}": Unknown configuration`));
+  return null;
+}
+
+/**
+ * Execute an MCP command
+ */
+function executeCommand(agent, args, dryRun = false) {
+  const cli = AGENT_CLI[agent];
+  
+  // Build command string with proper quoting for arguments with spaces
+  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] ${command}`));
+    return { success: true, dryRun: true };
+  }
+
+  try {
+    execSync(command, { stdio: 'pipe' });
+    console.log(kleur.green(`  ✓ ${args.slice(2).join(' ')}`));
+    return { success: true };
+  } catch (error) {
+    const stderr = error.stderr?.toString() || error.message;
+    
+    // Handle "already exists" case as success (idempotent)
+    if (stderr.includes('already exists') || stderr.includes('already configured')) {
+      // Extract server name based on agent
+      let serverName = 'unknown';
+      if (agent === 'claude') {
+        // Claude: claude mcp add [-s scope] [--transport type] <name> ...
+        // Find the server name: first non-flag arg after 'add' that's not scope or transport
+        const addIndex = args.indexOf('add');
+        for (let i = addIndex + 1; i < args.length; i++) {
+          const arg = args[i];
+          if (arg === '--') continue; // Skip separator
+          if (arg.startsWith('-')) continue; // Skip flags
+          if (['local', 'user', 'project', 'http', 'sse', 'stdio'].includes(arg)) continue; // Skip scope and transport
+          serverName = arg;
+          break;
+        }
+      } else if (agent === 'gemini' || agent === 'qwen') {
+        // Gemini/Qwen: <agent> mcp add [-t type] <name> <url>...
+        // Find first non-flag arg after 'add' that's not a transport type
+        const addIndex = args.indexOf('add');
+        for (let i = addIndex + 1; i < args.length; i++) {
+          const arg = args[i];
+          if (arg === '-t') { i++; continue; } // Skip transport flag and value
+          if (arg.startsWith('-')) continue; // Skip other flags
+          if (['http', 'sse', 'stdio'].includes(arg)) continue; // Skip transport types
+          serverName = arg;
+          break;
+        }
+      } else {
+        // Fallback: use third arg
+        serverName = args[2];
+      }
+      console.log(kleur.dim(`  ✓ ${serverName} (already configured)`));
+      return { success: true, skipped: true };
+    }
+    
+    console.log(kleur.red(`  ✗ Failed: ${stderr.trim()}`));
+    return { success: false, error: stderr };
+  }
+}
+
+/**
+ * Get current MCP servers for an agent
+ */
+function getCurrentServers(agent) {
+  const cli = AGENT_CLI[agent];
+  try {
+    const output = execSync(`${cli.command} ${cli.listArgs.join(' ')}`, { 
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'ignore']
+    });
+    return cli.parseList(output);
+  } catch (error) {
+    return [];
+  }
+}
+
+/**
+ * Sync MCP servers to an agent using official CLI
+ * 
+ * @param {string} agent - 'claude', 'gemini', or 'qwen'
+ * @param {Object} mcpConfig - Canonical MCP configuration
+ * @param {boolean} dryRun - Show commands without executing
+ * @param {boolean} prune - Remove servers not in canonical config
+ */
+export async function syncMcpServersWithCli(agent, mcpConfig, dryRun = false, prune = false) {
+  const cli = AGENT_CLI[agent];
+  if (!cli) {
+    console.log(kleur.yellow(`  ⚠️  Unsupported agent: ${agent}`));
+    return;
+  }
+
+  console.log(kleur.bold(`\nSyncing MCP servers to ${agent}...`));
+
+  // Step 0: Ensure .env file exists and load it
+  ensureEnvFile();
+  loadEnvFile();
+
+  // Step 1: Check for missing required env vars
+  const missingEnvVars = checkRequiredEnvVars();
+  if (missingEnvVars.length > 0) {
+    handleMissingEnvVars(missingEnvVars);
+    // Continue anyway - servers will be added but may not work until keys are added
+  }
+
+  // Step 2: Get current servers
+  const currentServers = getCurrentServers(agent);
+  const canonicalServers = new Set(Object.keys(mcpConfig.mcpServers || {}));
+
+  // Step 2: Remove servers not in canonical (if prune mode)
+  if (prune) {
+    console.log(kleur.red('\n  Prune mode: Removing servers not in canonical config...'));
+    for (const serverName of currentServers) {
+      if (!canonicalServers.has(serverName)) {
+        console.log(kleur.red(`  Removing: ${serverName}`));
+        executeCommand(agent, cli.remove(serverName), dryRun);
+      }
+    }
+  }
+
+  // Step 3: Add/update canonical servers
+  console.log(kleur.cyan('\n  Adding/Updating canonical servers...'));
+  let successCount = 0;
+  
+  for (const [name, server] of Object.entries(mcpConfig.mcpServers)) {
+    const cmd = buildAddCommand(agent, name, server);
+    if (cmd) {
+      const result = executeCommand(agent, cmd, dryRun);
+      if (result.success) {
+        successCount++;
+      }
+    }
+  }
+
+  // Summary
+  console.log(kleur.green(`\n  ✓ Synced ${successCount} MCP servers`));
+}
+
+/**
+ * Load canonical MCP config from repository
+ */
+export function loadCanonicalMcpConfig(repoRoot) {
+  const corePath = path.join(repoRoot, 'config', 'mcp_servers.json');
+  const optionalPath = path.join(repoRoot, 'config', 'mcp_servers_optional.json');
+  
+  const config = { mcpServers: {} };
+  
+  // Always load core servers
+  if (fs.existsSync(corePath)) {
+    const core = fs.readJsonSync(corePath);
+    config.mcpServers = { ...config.mcpServers, ...core.mcpServers };
+  }
+  
+  // Optionally load optional servers (user would have selected these)
+  // For now, we don't auto-load them
+  // if (fs.existsSync(optionalPath)) {
+  //   const optional = fs.readJsonSync(optionalPath);
+  //   config.mcpServers = { ...config.mcpServers, ...optional.mcpServers };
+  // }
+  
+  return config;
+}