xtrm-cli 0.5.0

package/lib/sync.js

@@ -0,0 +1,227 @@
+import path from 'path';
+import fs from 'fs-extra';
+import kleur from 'kleur';
+import { transformGeminiConfig, transformSkillToCommand } from './transform-gemini.js';
+import { safeMergeConfig } from './atomic-config.js';
+import { ConfigAdapter } from './config-adapter.js';
+import { syncMcpServersWithCli, loadCanonicalMcpConfig, detectAgent } from './sync-mcp-cli.js';
+
+/**
+ * Execute a sync plan based on changeset and mode
+ */
+export async function executeSync(repoRoot, systemRoot, changeSet, mode, actionType, isDryRun = false) {
+  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 categories = ['skills', 'hooks', 'config'];
+  
+  if (isQwen) {
+    categories.push('qwen-commands');
+  } else if (isGemini) {
+    categories.push('commands', 'antigravity-workflows');
+  } else if (!isClaude) {
+    categories.push('commands');
+  }
+
+  let count = 0;
+  const adapter = new ConfigAdapter(systemRoot);
+
+  // Special handling for agents with official MCP CLI: Always sync MCP servers
+  // Supported: claude, gemini, qwen
+  const agent = detectAgent(systemRoot);
+  if (agent && actionType === 'sync') {
+    console.log(kleur.gray(`  --> ${agent} MCP servers (via ${agent} mcp CLI)`));
+    
+    // Load canonical MCP config
+    const canonicalConfig = loadCanonicalMcpConfig(repoRoot);
+    
+    // Sync using official CLI
+    await syncMcpServersWithCli(agent, canonicalConfig, isDryRun, mode === 'prune');
+    
+    count++;
+  }
+
+  for (const category of categories) {
+    const itemsToProcess = [];
+
+    if (actionType === 'sync') {
+      itemsToProcess.push(...changeSet[category].missing);
+      itemsToProcess.push(...changeSet[category].outdated);
+
+      // PRUNE: Handle removals from system if no longer in repo
+      if (mode === 'prune') {
+        for (const itemToDelete of changeSet[category].drifted || []) {
+           const dest = path.join(systemRoot, category, itemToDelete);
+           console.log(kleur.red(`  [x] PRUNING ${category}/${itemToDelete}`));
+           if (!isDryRun) await fs.remove(dest);
+           count++;
+        }
+      }
+    } else if (actionType === 'backport') {
+      itemsToProcess.push(...changeSet[category].drifted);
+    }
+
+    for (const item of itemsToProcess) {
+      let src, dest;
+
+      if (category === 'config' && item === 'settings.json' && actionType === 'sync') {
+        src = path.join(repoRoot, 'config', 'settings.json');
+        dest = path.join(systemRoot, 'settings.json');
+
+        console.log(kleur.gray(`  --> config/settings.json`));
+
+        // Skip settings.json sync for agents with official MCP CLI
+        // MCP servers are managed via CLI, hooks are not supported
+        if (agent) {
+          console.log(kleur.gray(`  (Skipped: ${agent} uses ${agent} mcp CLI for MCP servers)`));
+          count++;
+          continue;
+        }
+
+        const repoConfig = await fs.readJson(src);
+        let finalRepoConfig = resolveConfigPaths(repoConfig, systemRoot);
+
+        // Inject Hooks
+        const hooksSrc = path.join(repoRoot, 'config', 'hooks.json');
+        if (await fs.pathExists(hooksSrc)) {
+          const hooksRaw = await fs.readJson(hooksSrc);
+          const hooksAdapted = adapter.adaptHooksConfig(hooksRaw);
+          if (hooksAdapted.hooks) {
+            finalRepoConfig.hooks = { ...(finalRepoConfig.hooks || {}), ...hooksAdapted.hooks };
+            if (!isDryRun) console.log(kleur.dim(`      (Injected hooks)`));
+          }
+        }
+
+        if (fs.existsSync(dest)) {
+          const localConfig = await fs.readJson(dest);
+          const resolvedLocalConfig = resolveConfigPaths(localConfig, systemRoot);
+
+          // Handle PRUNE mode for mcpServers and hooks
+          if (mode === 'prune') {
+            // Remove local MCP servers NOT in our canonical source
+            if (localConfig.mcpServers && finalRepoConfig.mcpServers) {
+                const canonicalServers = new Set(Object.keys(finalRepoConfig.mcpServers));
+                for (const serverName of Object.keys(localConfig.mcpServers)) {
+                    if (!canonicalServers.has(serverName)) {
+                        delete localConfig.mcpServers[serverName];
+                        if (!isDryRun) console.log(kleur.red(`      (Pruned local MCP server: ${serverName})`));
+                    }
+                }
+            }
+          }
+
+          const mergeResult = await safeMergeConfig(dest, finalRepoConfig, {
+            backupOnSuccess: true,
+            preserveComments: true,
+            dryRun: isDryRun,
+            resolvedLocalConfig: resolvedLocalConfig
+          });
+
+          if (mergeResult.updated) {
+            console.log(kleur.blue(`      (Configuration safely merged)`));
+          }
+        } else {
+          if (!isDryRun) {
+            await fs.ensureDir(path.dirname(dest));
+            await fs.writeJson(dest, finalRepoConfig, { spaces: 2 });
+          }
+          console.log(kleur.green(`      (Created new configuration)`));
+        }
+        count++;
+        continue;
+      }
+
+      // Standard file sync for other items
+      const repoPath = category === 'commands' ? path.join(repoRoot, '.gemini', 'commands') :
+                       category === 'qwen-commands' ? path.join(repoRoot, '.qwen', 'commands') :
+                       category === 'antigravity-workflows' ? path.join(repoRoot, '.gemini', 'antigravity', 'global_workflows') :
+                       path.join(repoRoot, category);
+
+      const systemPath = category === 'qwen-commands' ? path.join(systemRoot, 'commands') :
+                         category === 'antigravity-workflows' ? path.join(systemRoot, '.gemini', 'antigravity', 'global_workflows') :
+                         path.join(systemRoot, category);
+
+      if (actionType === 'backport') {
+        src = path.join(systemPath, item);
+        dest = path.join(repoPath, item);
+      } else {
+        src = path.join(repoPath, item);
+        dest = path.join(systemPath, item);
+      }
+
+      console.log(kleur.gray(`  ${actionType === 'backport' ? '<--' : '-->'} ${category}/${item}`));
+
+      if (mode === 'symlink' && actionType === 'sync' && category !== 'config') {
+        if (!isDryRun) {
+          await fs.remove(dest);
+          await fs.ensureSymlink(src, dest);
+        }
+      } else {
+        if (!isDryRun) {
+          await fs.remove(dest);
+          await fs.copy(src, dest);
+        }
+      }
+
+      // Gemini Skill -> Command transformation
+      if (category === 'skills' && !isClaude && actionType === 'sync') {
+        const skillMdPath = path.join(src, 'SKILL.md');
+        if (fs.existsSync(skillMdPath)) {
+          const result = await transformSkillToCommand(skillMdPath);
+          if (result && !isDryRun) {
+            const commandDest = path.join(systemRoot, 'commands', `${result.commandName}.toml`);
+            await fs.ensureDir(path.dirname(commandDest));
+            await fs.writeFile(commandDest, result.toml);
+            console.log(kleur.cyan(`      (Auto-generated slash command: /${result.commandName})`));
+          }
+        }
+      }
+
+      count++;
+    }
+  }
+
+  // Final Step: Write Sync Manifest
+  if (!isDryRun && actionType === 'sync') {
+    const manifestPath = path.join(systemRoot, '.jaggers-sync-manifest.json');
+    const manifest = {
+        lastSync: new Date().toISOString(),
+        repoRoot,
+        items: count
+    };
+    await fs.writeJson(manifestPath, manifest, { spaces: 2 });
+  }
+
+  return count;
+}
+
+/**
+ * Recursively resolves paths in the config to match the target directory
+ *
+ * This function corrects hardcoded paths (e.g. /home/dawid/...) to match the current user's home directory.
+ * It's applied to both repository config AND local config to ensure existing installations get updated.
+ *
+ * @param {Object} config - The configuration object to process
+ * @param {string} targetDir - The target directory (e.g. /home/jagger/.claude)
+ * @returns {Object} - New config object with resolved paths
+ */
+function resolveConfigPaths(config, targetDir) {
+  const newConfig = JSON.parse(JSON.stringify(config));
+
+  function recursiveReplace(obj) {
+    for (const key in obj) {
+      if (typeof obj[key] === 'string') {
+        // Match absolute paths containing /hooks/ and replace the prefix with targetDir/hooks
+        if (obj[key].match(/\/[^\s"']+\/hooks\//)) {
+           const hooksDir = path.join(targetDir, 'hooks');
+           obj[key] = obj[key].replace(/(\/[^\s"']+\/hooks\/)/g, `${hooksDir}/`);
+        }
+      } else if (typeof obj[key] === 'object' && obj[key] !== null) {
+        recursiveReplace(obj[key]);
+      }
+    }
+  }
+
+  recursiveReplace(newConfig);
+  return newConfig;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "xtrm-cli",
+  "version": "0.5.0",
+  "description": "Claude Code tools installer (skills, hooks, MCP servers)",
+  "main": "./dist/index.js",
+  "type": "module",
+  "bin": {
+    "xtrm": "dist/index.cjs",
+    "xt": "dist/index.cjs"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "start": "node dist/index.cjs"
+  },
+  "dependencies": {
+    "boxen": "^8.0.1",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3",
+    "comment-json": "^4.2.3",
+    "conf": "^12.0.0",
+    "dotenv": "^16.4.5",
+    "fs-extra": "^11.2.0",
+    "kleur": "^4.1.5",
+    "listr2": "^10.1.1",
+    "minimist": "^1.2.8",
+    "ora": "^9.3.0",
+    "project": "^0.1.6",
+    "prompts": "^2.4.2",
+    "tdd-guard": "^1.1.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^25.3.0",
+    "tdd-guard-vitest": "^0.1.6",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/adapters/base.ts

@@ -0,0 +1,29 @@
+import type { Skill, MCPServer, Hook, Command } from '../types/models.js';
+
+export interface AdapterCapabilities {
+    skills: boolean;
+    hooks: boolean;
+    mcp: boolean;
+    commands: boolean;
+}
+
+export interface AdapterConfig {
+    tool: string;
+    baseDir: string;
+    displayName: string;
+}
+
+export abstract class ToolAdapter {
+    abstract readonly toolName: string;
+    abstract readonly displayName: string;
+    abstract readonly config: AdapterConfig;
+
+    // Capabilities
+    abstract getCapabilities(): AdapterCapabilities;
+
+    // Paths
+    abstract getConfigDir(): string;
+    abstract getSkillsDir(): string;
+    abstract getHooksDir(): string;
+    abstract getCommandsDir(): string;
+}

package/src/adapters/claude.ts

@@ -0,0 +1,38 @@
+import { join } from 'path';
+import { ToolAdapter, type AdapterCapabilities } from './base.js';
+
+export class ClaudeAdapter extends ToolAdapter {
+    readonly toolName = 'claude-code';
+    readonly displayName = 'Claude Code';
+    readonly config: { tool: string; baseDir: string; displayName: string };
+
+    constructor(baseDir: string) {
+        super();
+        this.config = { tool: this.toolName, baseDir, displayName: this.displayName };
+    }
+
+    getConfigDir(): string {
+        return this.config.baseDir;
+    }
+
+    getSkillsDir(): string {
+        return join(this.config.baseDir, 'skills');
+    }
+
+    getHooksDir(): string {
+        return join(this.config.baseDir, 'hooks');
+    }
+
+    getCommandsDir(): string {
+        return join(this.config.baseDir, 'commands'); // Though Claude doesn't strictly use bare commands like Gemini
+    }
+
+    getCapabilities(): AdapterCapabilities {
+        return {
+            skills: true,
+            hooks: true,
+            mcp: true,
+            commands: false, // Claude uses Skills instead of Slash Commands natively
+        };
+    }
+}

package/src/adapters/registry.ts

@@ -0,0 +1,21 @@
+import { ToolAdapter } from './base.js';
+import { ClaudeAdapter } from './claude.js';
+
+/**
+ * Adapter registry for Claude Code only.
+ * 
+ * ARCHITECTURAL DECISION (v2.0.0): xtrm-tools now supports Claude Code exclusively.
+ * Gemini and Qwen adapters were removed due to fragile, undocumented hook ecosystems.
+ * See PROJECT-SKILLS-ARCHITECTURE.md Section 3.1 for details.
+ */
+
+export function detectAdapter(systemRoot: string): ToolAdapter | null {
+    // Windows compatibility: Normalize backslashes before matching paths
+    const normalized = systemRoot.replace(/\\/g, '/').toLowerCase();
+
+    if (normalized.includes('.claude') || normalized.includes('/claude')) {
+        return new ClaudeAdapter(systemRoot);
+    }
+
+    return null;
+}

package/src/commands/claude.ts

@@ -0,0 +1,122 @@
+import { Command } from 'commander';
+import kleur from 'kleur';
+import { execSync, spawnSync } from 'node:child_process';
+import path from 'node:path';
+import fs from 'fs-extra';
+import { findRepoRoot } from '../utils/repo-root.js';
+import { t } from '../utils/theme.js';
+import { installPlugin } from './install.js';
+import { launchWorktreeSession } from '../utils/worktree-session.js';
+
+export function createClaudeCommand(): Command {
+    const cmd = new Command('claude')
+        .description('Launch a Claude session in a sandboxed worktree, or manage the Claude runtime')
+        .argument('[name]', 'Optional session name — used as xt/<name> branch (random if omitted)')
+        .action(async (name: string | undefined) => {
+            await launchWorktreeSession({ runtime: 'claude', name });
+        });
+
+    cmd.command('install')
+        .description('Install/refresh the xtrm-tools Claude plugin and official plugins')
+        .option('--dry-run', 'Preview without making changes', false)
+        .action(async (opts) => {
+            const repoRoot = await findRepoRoot();
+            await installPlugin(repoRoot, opts.dryRun);
+        });
+
+    cmd.command('reload')
+        .alias('reinstall')
+        .description('Reinstall Claude plugin from live repo (refreshes cached copy)')
+        .action(async () => {
+            const repoRoot = await findRepoRoot();
+            await installPlugin(repoRoot, false);
+        });
+
+    cmd.command('status')
+        .description('Show Claude CLI version, plugin status, and hook wiring')
+        .action(async () => {
+            console.log(t.bold('\n  Claude Code Status\n'));
+
+            try {
+                const version = execSync('claude --version', { encoding: 'utf8', stdio: 'pipe' }).trim();
+                console.log(t.success(`  ✓ claude CLI: ${version}`));
+            } catch {
+                console.log(kleur.red('  ✗ claude CLI not found'));
+                console.log('');
+                return;
+            }
+
+            const listResult = spawnSync('claude', ['plugin', 'list'], { encoding: 'utf8', stdio: 'pipe' });
+            const pluginOutput = listResult.stdout ?? '';
+            if (pluginOutput.includes('xtrm-tools')) {
+                console.log(t.success('  ✓ xtrm-tools plugin installed'));
+            } else {
+                console.log(kleur.yellow('  ⚠ xtrm-tools plugin not installed — run: xt claude install'));
+            }
+
+            try {
+                execSync('bd --version', { stdio: 'ignore' });
+                console.log(t.success('  ✓ beads (bd) available'));
+            } catch {
+                console.log(kleur.dim('  ○ beads (bd) not installed'));
+            }
+
+            console.log('');
+        });
+
+    cmd.command('doctor')
+        .description('Run diagnostic checks on Claude Code setup')
+        .action(async () => {
+            console.log(t.bold('\n  Claude Code Doctor\n'));
+
+            let allOk = true;
+
+            try {
+                execSync('claude --version', { stdio: 'ignore' });
+                console.log(t.success('  ✓ claude CLI available'));
+            } catch {
+                console.log(kleur.red('  ✗ claude CLI not found — install Claude Code'));
+                allOk = false;
+            }
+
+            const listResult = spawnSync('claude', ['plugin', 'list'], { encoding: 'utf8', stdio: 'pipe' });
+            if (listResult.stdout?.includes('xtrm-tools')) {
+                console.log(t.success('  ✓ xtrm-tools plugin installed'));
+            } else {
+                console.log(kleur.yellow('  ⚠ xtrm-tools plugin missing — run: xt claude install'));
+                allOk = false;
+            }
+
+            try {
+                execSync('bd --version', { stdio: 'ignore' });
+                console.log(t.success('  ✓ beads (bd) installed'));
+            } catch {
+                console.log(kleur.yellow('  ⚠ beads not installed — run: npm install -g @beads/bd'));
+                allOk = false;
+            }
+
+            try {
+                execSync('dolt version', { stdio: 'ignore' });
+                console.log(t.success('  ✓ dolt installed'));
+            } catch {
+                console.log(kleur.yellow('  ⚠ dolt not installed — required for beads storage'));
+                allOk = false;
+            }
+
+            try {
+                execSync('gitnexus --version', { stdio: 'ignore' });
+                console.log(t.success('  ✓ gitnexus installed'));
+            } catch {
+                console.log(kleur.dim('  ○ gitnexus not installed (optional) — npm install -g gitnexus'));
+            }
+
+            console.log('');
+            if (allOk) {
+                console.log(t.boldGreen('  ✓ All checks passed\n'));
+            } else {
+                console.log(kleur.yellow('  ⚠ Some checks failed — see above\n'));
+            }
+        });
+
+    return cmd;
+}