xtrm-cli 2.1.4

package/src/types/models.ts

@@ -0,0 +1,52 @@
+export interface Skill {
+    name: string;
+    description: string;
+    content: string;
+}
+
+export interface Command {
+    name: string;
+    description: string;
+    prompt: string;
+}
+
+export interface Hook {
+    name?: string;
+    type?: string;
+    command?: string;
+    script?: string;
+    timeout?: number;
+    events?: string[];
+    matcher?: string;
+}
+
+export interface MCPServer {
+    type?: 'stdio' | 'http' | 'sse';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    serverUrl?: string;
+    headers?: Record<string, string>;
+    disabled?: boolean;
+}
+
+export interface SyncOptions {
+    dryRun?: boolean;
+    yes?: boolean;
+    prune?: boolean;
+}
+
+export interface ManifestItem {
+    type: 'skill' | 'hook' | 'config' | 'command';
+    name: string;
+    hash: string;
+    lastSync: string;
+    source: string;
+}
+
+export interface Manifest {
+    version: string;
+    lastSync: string;
+    items: Record<string, ManifestItem>;
+}

package/src/utils/atomic-config.ts

@@ -0,0 +1,222 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'fs-extra';
+// @ts-ignore
+import { parse, stringify } from 'comment-json';
+
+/**
+ * Atomic Configuration Handler with Vault Pattern
+ * Ensures safe read/write operations with protection against corruption during crashes
+ */
+
+// Protected keys that should never be overwritten if they exist locally
+const PROTECTED_KEYS = [
+    'permissions.allow',       // User-defined permissions
+    'hooks.UserPromptSubmit',  // Claude hooks
+    'hooks.SessionStart',
+    'hooks.PreToolUse',
+    'hooks.BeforeAgent',       // Gemini hooks
+    'hooks.BeforeTool',        // Gemini hooks
+    'security',                // Auth secrets/OAuth data
+    'general',                 // Personal preferences
+    'enabledPlugins',          // User-enabled/disabled plugins
+    'model',                   // User's preferred model
+    'skillSuggestions.enabled' // User preferences
+];
+
+/**
+ * Check if a key path is exactly protected or a parent of a protected key
+ */
+export function isProtectedPath(keyPath: string): boolean {
+    return PROTECTED_KEYS.some(protectedPath =>
+        keyPath === protectedPath || protectedPath.startsWith(keyPath + '.')
+    );
+}
+
+/**
+ * Check if a key path is a protected key or a child of a protected key
+ */
+export function isValueProtected(keyPath: string): boolean {
+    return PROTECTED_KEYS.some(protectedPath =>
+        keyPath === protectedPath || keyPath.startsWith(protectedPath + '.')
+    );
+}
+
+/**
+ * Deep merge two objects, preserving protected values from the original
+ */
+export function deepMergeWithProtection(original: any, updates: any, currentPath: string = ''): any {
+    const result = { ...original };
+
+    for (const [key, value] of Object.entries(updates)) {
+        const keyPath = currentPath ? `${currentPath}.${key}` : key;
+
+        // If this specific value is protected and exists locally, skip it
+        if (isValueProtected(keyPath) && original.hasOwnProperty(key)) {
+            continue;
+        }
+
+        // Special handling for mcpServers: merge individual server entries
+        if (key === 'mcpServers' && typeof value === 'object' && value !== null &&
+            typeof original[key] === 'object' && original[key] !== null) {
+
+            result[key] = { ...original[key] }; // Start with original servers
+
+            // Add servers from updates that don't exist in original
+            for (const [serverName, serverConfig] of Object.entries(value)) {
+                if (!result[key].hasOwnProperty(serverName)) {
+                    result[key][serverName] = serverConfig;
+                }
+            }
+        } else if (
+            typeof value === 'object' &&
+            value !== null &&
+            !Array.isArray(value) &&
+            typeof original[key] === 'object' &&
+            original[key] !== null &&
+            !Array.isArray(original[key])
+        ) {
+            // Recursively merge nested objects
+            result[key] = deepMergeWithProtection(original[key], value, keyPath);
+        } else {
+            // Overwrite with new value for non-protected keys
+            result[key] = value;
+        }
+    }
+
+    return result;
+}
+
+interface AtomicWriteOptions {
+    preserveComments?: boolean;
+    backupOnSuccess?: boolean;
+    backupSuffix?: string;
+}
+
+/**
+ * Atomically write data to a file using a temporary file
+ */
+export async function atomicWrite(filePath: string, data: any, options: AtomicWriteOptions = {}): Promise<void> {
+    const {
+        preserveComments = false,
+        backupOnSuccess = false,
+        backupSuffix = '.bak'
+    } = options;
+
+    const tempFilePath = `${filePath}.tmp.${randomUUID()}`;
+
+    try {
+        let content: string;
+        if (preserveComments) {
+            content = stringify(data, null, 2);
+        } else {
+            content = JSON.stringify(data, null, 2);
+        }
+
+        await fs.writeFile(tempFilePath, content, 'utf8');
+
+        const tempStats = await fs.stat(tempFilePath);
+        if (tempStats.size === 0) {
+            throw new Error('Temporary file is empty - write failed');
+        }
+
+        if (backupOnSuccess && await fs.pathExists(filePath)) {
+            const backupPath = `${filePath}${backupSuffix}`;
+            await fs.copy(filePath, backupPath);
+        }
+
+        await fs.rename(tempFilePath, filePath);
+    } catch (error) {
+        try {
+            if (await fs.pathExists(tempFilePath)) {
+                await fs.unlink(tempFilePath);
+            }
+        } catch (cleanupError) { }
+        throw error;
+    }
+}
+
+/**
+ * Safely read a JSON configuration file with error handling
+ */
+export async function safeReadConfig(filePath: string): Promise<any> {
+    try {
+        if (!(await fs.pathExists(filePath))) {
+            return {};
+        }
+
+        const content = await fs.readFile(filePath, 'utf8');
+
+        try {
+            return parse(content);
+        } catch (parseError) {
+            return JSON.parse(content);
+        }
+    } catch (error: any) {
+        if (error.code === 'ENOENT') return {};
+        throw new Error(`Failed to read config file: ${error.message}`);
+    }
+}
+
+interface MergeOptions {
+    preserveComments?: boolean;
+    backupOnSuccess?: boolean;
+    dryRun?: boolean;
+    resolvedLocalConfig?: any;
+}
+
+export interface MergeResult {
+    updated: boolean;
+    changes: string[];
+}
+
+/**
+ * Perform a safe merge of repository config with local config
+ */
+export async function safeMergeConfig(localConfigPath: string, repoConfig: any, options: MergeOptions = {}): Promise<MergeResult> {
+    const {
+        preserveComments = true,
+        backupOnSuccess = true,
+        dryRun = false,
+        resolvedLocalConfig = null
+    } = options;
+
+    const localConfig = resolvedLocalConfig || await safeReadConfig(localConfigPath);
+    const changes: string[] = [];
+
+    if (localConfig.mcpServers && typeof localConfig.mcpServers === 'object') {
+        const localServerNames = Object.keys(localConfig.mcpServers);
+        if (localServerNames.length > 0) {
+            changes.push(`Preserved ${localServerNames.length} local mcpServers: ${localServerNames.join(', ')}`);
+        }
+    }
+
+    if (repoConfig.mcpServers && typeof repoConfig.mcpServers === 'object') {
+        const repoServerNames = Object.keys(repoConfig.mcpServers);
+        const newServerNames = repoServerNames.filter(name =>
+            !localConfig.mcpServers || !localConfig.mcpServers.hasOwnProperty(name)
+        );
+
+        if (newServerNames.length > 0) {
+            changes.push(`Added ${newServerNames.length} new non-conflicting mcpServers from repository: ${newServerNames.join(', ')}`);
+        }
+    }
+
+    const mergedConfig = deepMergeWithProtection(localConfig, repoConfig);
+    const configsAreEqual = JSON.stringify(localConfig) === JSON.stringify(mergedConfig);
+
+    if (!configsAreEqual && !dryRun) {
+        await atomicWrite(localConfigPath, mergedConfig, {
+            preserveComments,
+            backupOnSuccess
+        });
+    }
+
+    return {
+        updated: !configsAreEqual,
+        changes
+    };
+}
+
+export function getProtectedKeys(): string[] {
+    return [...PROTECTED_KEYS];
+}

package/src/utils/banner.ts

@@ -0,0 +1,194 @@
+import kleur from 'kleur';
+
+// ── ASCII art ───────────────────────────────────────────────────────────────
+const ART = [
+    ' ██╗  ██╗████████╗██████╗ ███╗   ███╗    ████████╗ ██████╗  ██████╗ ██╗     ███████╗',
+    ' ╚██╗██╔╝╚══██╔══╝██╔══██╗████╗ ████║    ╚══██╔══╝██╔═══██╗██╔═══██╗██║     ██╔════╝',
+    '  ╚███╔╝    ██║   ██████╔╝██╔████╔██║       ██║   ██║   ██║██║   ██║██║     ███████╗',
+    '  ██╔██╗    ██║   ██╔══██╗██║╚██╔╝██║       ██║   ██║   ██║██║   ██║██║     ╚════██║',
+    ' ██╔╝ ██╗   ██║   ██║  ██║██║ ╚═╝ ██║       ██║   ╚██████╔╝╚██████╔╝███████╗███████║',
+    ' ╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝╚═╝     ╚═╝       ╚═╝    ╚═════╝  ╚═════╝ ╚══════╝╚══════╝',
+];
+
+const ART_WIDTH = 84;
+
+// ── Detection helpers ───────────────────────────────────────────────────────
+
+function isTTY(): boolean { return Boolean(process.stdout.isTTY); }
+
+function hasColor(): boolean {
+    if (process.env.NO_COLOR !== undefined) return false;
+    if (process.env.FORCE_COLOR !== undefined) return true;
+    if (process.env.TERM === 'dumb') return false;
+    return isTTY();
+}
+
+function isCI(): boolean { return Boolean(process.env.CI); }
+function isDumb(): boolean { return process.env.TERM === 'dumb'; }
+function columns(): number { return process.stdout.columns ?? 80; }
+
+function hasUnicode(): boolean {
+    if (process.platform === 'win32') {
+        return Boolean(process.env.WT_SESSION || process.env.TERM_PROGRAM);
+    }
+    const lang = (process.env.LANG ?? process.env.LC_ALL ?? process.env.LC_CTYPE ?? '').toUpperCase();
+    return lang.includes('UTF') || lang === '';
+}
+
+function hasTruecolor(): boolean {
+    const ct = (process.env.COLORTERM ?? '').toLowerCase();
+    return ct === 'truecolor' || ct === '24bit';
+}
+
+// ── Tier selection ──────────────────────────────────────────────────────────
+
+type Tier = 0 | 1 | 2 | 3 | 4;
+
+function selectTier(): Tier {
+    if (!isTTY() || isDumb() || isCI()) return 4;
+    if (!hasColor()) return 4;
+    if (!hasUnicode()) return 3;
+    const cols = columns();
+    if (cols < 40) return 4;
+    if (cols < 85) return 2;
+    if (hasTruecolor()) return 0;
+    return 1;
+}
+
+// ── Press-any-key with passive 1s auto-timeout ─────────────────────────────
+
+function pressAnyKey(): Promise<void> {
+    return new Promise(resolve => {
+        process.stdout.write(kleur.dim('\n  press any key to continue...'));
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+
+        let done = false;
+        const finish = (): void => {
+            if (done) return;
+            done = true;
+            process.stdin.setRawMode(false);
+            process.stdin.pause();
+            process.stdout.write('\r\x1b[2K');
+            resolve();
+        };
+
+        process.stdin.once('data', finish);
+        setTimeout(finish, 4000);
+    });
+}
+
+// ── Typewriter tagline (bold-white, 42ms per char) ─────────────────────────
+
+function delay(ms: number): Promise<void> {
+    return new Promise(r => setTimeout(r, ms));
+}
+
+async function typewriterTagline(text: string): Promise<void> {
+    const CHAR_DELAY = 42; // ms per character
+    const prefix = `  \x1b[2m\u2014\x1b[0m  \x1b[1m\x1b[37m`;
+    const suffix = `\x1b[0m  \x1b[2m\u2014\x1b[0m`;
+
+    process.stdout.write(prefix);
+    for (const ch of text) {
+        process.stdout.write(ch);
+        await delay(CHAR_DELAY);
+    }
+    process.stdout.write(suffix + '\n');
+}
+
+// ── Truecolor gradient (item 7: 170°→230° teal→indigo, sat=0.6) ───────────
+
+const HUE_START = 170;
+const HUE_END   = 230;
+const SAT       = 0.6;
+const LIG       = 0.72;
+
+function hslToRgb(h: number, s: number, l: number): [number, number, number] {
+    const a = s * Math.min(l, 1 - l);
+    const f = (n: number): number => {
+        const k = (n + h / 30) % 12;
+        return l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+    };
+    return [Math.round(f(0) * 255), Math.round(f(8) * 255), Math.round(f(4) * 255)];
+}
+
+const RESET = '\x1b[0m';
+
+function gradientLine(line: string): string {
+    let out = '';
+    const len = line.length;
+    for (let i = 0; i < len; i++) {
+        const t = len > 1 ? i / (len - 1) : 0;
+        const hue = HUE_START + t * (HUE_END - HUE_START);
+        const [r, g, b] = hslToRgb(hue, SAT, LIG);
+        out += `\x1b[38;2;${r};${g};${b}m` + line[i];
+    }
+    return out + RESET;
+}
+
+// ── Renderers ───────────────────────────────────────────────────────────────
+
+async function renderTier0(version: string): Promise<void> {
+    const rule = '\x1b[2m ' + '─'.repeat(ART_WIDTH - 1) + '\x1b[0m';
+
+    process.stdout.write('\n');
+    for (const line of ART) {
+        process.stdout.write(gradientLine(line) + '\n');
+    }
+    process.stdout.write(rule + '\n');
+    process.stdout.write('  \x1b[2mv' + version + '\x1b[0m\n');
+    await typewriterTagline('Sync agent tools across AI environments');
+}
+
+function renderTier1(version: string): void {
+    console.log('');
+    for (const line of ART) { console.log(kleur.cyan(line)); }
+    console.log(kleur.dim(' ' + '─'.repeat(ART_WIDTH - 1)));
+    console.log(kleur.dim('  v' + version));
+    console.log(
+        '  ' + kleur.dim('\u2014') + '  ' +
+        kleur.bold().white('Sync agent tools across AI environments') +
+        '  ' + kleur.dim('\u2014'),
+    );
+    console.log('');
+}
+
+function renderTier2(version: string): void {
+    console.log('');
+    console.log(
+        kleur.cyan('  ◈  ') +
+        kleur.bold().white('xtrm-tools') +
+        kleur.dim('  v' + version),
+    );
+    console.log(kleur.dim('     Sync agent tools across AI environments'));
+    console.log('');
+}
+
+function renderTier3(version: string): void {
+    console.log('');
+    console.log(kleur.bold('  xtrm-tools') + kleur.dim(' v' + version));
+    console.log(kleur.dim('  Sync agent tools across AI environments'));
+    console.log('');
+}
+
+function renderTier4(version: string): void {
+    console.log('');
+    console.log('xtrm-tools v' + version);
+    console.log('Sync agent tools across AI environments');
+    console.log('');
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+export async function printBanner(version: string): Promise<void> {
+    const tier = selectTier();
+    switch (tier) {
+        case 0: await renderTier0(version); break;
+        case 1: renderTier1(version); break;
+        case 2: renderTier2(version); break;
+        case 3: renderTier3(version); break;
+        case 4: renderTier4(version); return;
+    }
+    if (isTTY()) await pressAnyKey();
+}

package/src/utils/config-adapter.ts

@@ -0,0 +1,90 @@
+import path from 'path';
+import os from 'os';
+
+/**
+ * ConfigAdapter for Claude Code only.
+ * 
+ * ARCHITECTURAL DECISION (v2.0.0): xtrm-tools now supports Claude Code exclusively.
+ * Hook translation for Gemini/Qwen was removed due to fragile, undocumented ecosystems.
+ * See PROJECT-SKILLS-ARCHITECTURE.md Section 3.1 for details.
+ */
+export class ConfigAdapter {
+    systemRoot: string;
+    homeDir: string;
+    hooksDir: string;
+
+    constructor(systemRoot: string) {
+        this.systemRoot = systemRoot;
+        this.homeDir = os.homedir();
+        this.hooksDir = path.join(this.systemRoot, 'hooks');
+    }
+
+    /**
+     * Adapt hooks config for Claude Code format.
+     * Transforms flat hook definitions into Claude's wrapped format.
+     */
+    adaptHooksConfig(canonicalHooks: any): any {
+        if (!canonicalHooks) return {};
+
+        const hooksConfig = JSON.parse(JSON.stringify(canonicalHooks));
+        this.resolveHookScripts(hooksConfig);
+        return hooksConfig;
+    }
+
+    /**
+     * Resolve hook script paths and transform into Claude's command format.
+     * Converts { script: "foo.py" } → { type: "command", command: "python3 /full/path/foo.py" }
+     */
+    resolveHookScripts(hooksConfig: any): void {
+        if (hooksConfig.hooks) {
+            for (const [event, hooks] of Object.entries(hooksConfig.hooks)) {
+                if (Array.isArray(hooks)) {
+                    // Transform flat hooks into Claude's wrapped format:
+                    // { matcher?, hooks: [{ type, command, timeout }] }
+                    hooksConfig.hooks[event] = hooks.map((hook: any) => {
+                        if (hook.script) {
+                            const resolvedScriptPath = this.resolvePath(path.join(this.hooksDir, hook.script));
+                            const command = this.buildScriptCommand(hook.script, resolvedScriptPath);
+                            const innerHook: any = { type: "command", command };
+                            if (hook.timeout) innerHook.timeout = hook.timeout;
+
+                            const wrapper: any = { hooks: [innerHook] };
+                            if (hook.matcher) wrapper.matcher = hook.matcher;
+                            return wrapper;
+                        }
+                        return hook;
+                    });
+                }
+            }
+        }
+        if (hooksConfig.statusLine && hooksConfig.statusLine.script) {
+            const resolvedScriptPath = this.resolvePath(path.join(this.hooksDir, hooksConfig.statusLine.script));
+            const command = this.buildScriptCommand(hooksConfig.statusLine.script, resolvedScriptPath);
+            hooksConfig.statusLine = { type: "command", command };
+        }
+    }
+
+    buildScriptCommand(scriptName: string, resolvedPath: string): string {
+        const ext = path.extname(scriptName).toLowerCase();
+        if (ext === '.js' || ext === '.cjs' || ext === '.mjs') {
+            return `node "${resolvedPath}"`;
+        } else if (ext === '.sh') {
+            return `bash "${resolvedPath}"`;
+        } else {
+            const pythonBin = process.platform === 'win32' ? 'python' : 'python3';
+            return `${pythonBin} "${resolvedPath}"`;
+        }
+    }
+
+    resolvePath(p: string): string {
+        if (!p || typeof p !== 'string') return p;
+        let resolved = p.replace(/~\//g, this.homeDir + '/').replace(/\${HOME}/g, this.homeDir);
+
+        // Windows compatibility: use forward slashes in config files
+        if (process.platform === 'win32') {
+            resolved = resolved.replace(/\\/g, '/');
+        }
+
+        return resolved;
+    }
+}

package/src/utils/config-injector.ts

@@ -0,0 +1,81 @@
+import path from 'path';
+import fs from 'fs-extra';
+// @ts-ignore
+import { parse, stringify } from 'comment-json';
+import kleur from 'kleur';
+
+/**
+ * Safely inject hook configuration into settings.json
+ */
+export async function injectHookConfig(targetDir: string, repoRoot: string): Promise<boolean> {
+    const settingsPath = path.join(targetDir, 'settings.json');
+
+    if (!(await fs.pathExists(settingsPath))) {
+        console.log(kleur.yellow(`  [!] settings.json not found in ${targetDir}. Skipping auto-config.`));
+        return false;
+    }
+
+    try {
+        const rawContent = await fs.readFile(settingsPath, 'utf8');
+        const settings = parse(rawContent);
+
+        if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+            console.log(kleur.yellow(`  [!] settings.json is not a valid object. Skipping auto-config.`));
+            return false;
+        }
+
+        // Define our required hooks
+        const requiredHooks = [
+            {
+                name: 'skill-suggestion',
+                path: path.join(targetDir, 'hooks', 'skill-suggestion.py'), // It's python!
+                events: ['userPromptSubmit'],
+            },
+            {
+                name: 'serena-workflow-reminder',
+                path: path.join(targetDir, 'hooks', 'serena-workflow-reminder.py'),
+                events: ['toolUse'],
+            },
+        ];
+
+        let modified = false;
+
+        if (!Array.isArray((settings as any).hooks)) {
+            (settings as any).hooks = [];
+            modified = true;
+        }
+
+        for (const req of requiredHooks) {
+            const exists = (settings as any).hooks.find((h: any) => h.name === req.name || h.path === req.path);
+
+            if (!exists) {
+                console.log(kleur.blue(`  [+] Adding hook: ${req.name}`));
+                (settings as any).hooks.push(req);
+                modified = true;
+            } else {
+                // Optional: Update path if it changed
+                if (exists.path !== req.path) {
+                    console.log(kleur.blue(`  [^] Updating hook path: ${req.name}`));
+                    exists.path = req.path;
+                    modified = true;
+                }
+            }
+        }
+
+        if (modified) {
+            // Backup
+            const backupPath = `${settingsPath}.bak`;
+            await fs.copy(settingsPath, backupPath);
+            console.log(kleur.gray(`  [i] Backup created at settings.json.bak`));
+
+            // Write back with comments preserved
+            await fs.writeFile(settingsPath, stringify(settings, null, 2));
+            return true;
+        }
+
+        return false;
+    } catch (err: any) {
+        console.error(kleur.red(`  [!] Error parsing settings.json: ${err.message}`));
+        return false;
+    }
+}