xtrm-cli 0.5.0

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;
+    }
+}

package/src/utils/env-manager.ts

@@ -0,0 +1,193 @@
+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');
+
+interface EnvVarConfig {
+    description: string;
+    example: string;
+    getUrl: () => string;
+}
+
+/**
+ * Required environment variables for MCP servers
+ */
+const REQUIRED_ENV_VARS: Record<string, EnvVarConfig> = {
+    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(): boolean {
+    // 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
+}
+
+function createEnvExample(): void {
+    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');
+        }),
+        '# See config/.env.example in the repository for all available options',
+        '',
+    ].join('\n');
+
+    fs.writeFileSync(ENV_EXAMPLE_FILE, content);
+    console.log(kleur.gray(`  Created example file: ${ENV_EXAMPLE_FILE}`));
+}
+
+function createEnvFile(): void {
+    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(): Record<string, string> {
+    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.
+ * Pass an optional `subset` of var names to check only those.
+ * Known vars (in REQUIRED_ENV_VARS) get rich metadata; unknown vars are
+ * still checked so server-defined ${VAR} references are never silently dropped.
+ * Returns array of missing variable names.
+ */
+export function checkRequiredEnvVars(subset?: string[]): string[] {
+    const missing: string[] = [];
+    const keysToCheck = subset ?? Object.keys(REQUIRED_ENV_VARS);
+
+    for (const key of keysToCheck) {
+        if (!process.env[key]) {
+            missing.push(key);
+        }
+    }
+
+    return missing;
+}
+
+/**
+ * Prompt user to enter missing environment variables interactively.
+ * Saves provided values to .env and sets them in process.env.
+ * Returns true if all missing vars were provided (sync can continue).
+ */
+export async function handleMissingEnvVars(missing: string[]): Promise<boolean> {
+    if (missing.length === 0) {
+        return true;
+    }
+
+    // @ts-ignore
+    const prompts = (await import('prompts')).default;
+
+    const answers: Record<string, string> = {};
+
+    for (const key of missing) {
+        const config = REQUIRED_ENV_VARS[key];
+        if (config) {
+            console.log(kleur.yellow(`\n  ⚠️  ${config.description} is required`));
+            console.log(kleur.dim(`     Get your key from: ${config.getUrl()}`));
+        } else {
+            console.log(kleur.yellow(`\n  ⚠️  ${key} is required by a selected MCP server`));
+        }
+
+        const { value } = await prompts({
+            type: 'text',
+            name: 'value',
+            message: `Enter ${key}:`,
+            validate: (v: string) => v.trim().length > 0 || 'Value cannot be empty'
+        });
+
+        if (!value) {
+            console.log(kleur.gray(`  Skipped — ${key} not provided. MCP server will be skipped.`));
+            return false;
+        }
+
+        answers[key] = value.trim();
+        process.env[key] = value.trim();
+    }
+
+    // Persist to .env file
+    let envContent = fs.existsSync(ENV_FILE) ? fs.readFileSync(ENV_FILE, 'utf8') : '';
+    for (const [key, value] of Object.entries(answers)) {
+        const line = `${key}=${value}`;
+        const regex = new RegExp(`^${key}=.*$`, 'm');
+        if (regex.test(envContent)) {
+            envContent = envContent.replace(regex, line);
+        } else {
+            envContent += `\n${line}\n`;
+        }
+    }
+    fs.writeFileSync(ENV_FILE, envContent);
+    console.log(kleur.green(`  ✓ Saved to ${ENV_FILE}`));
+
+    return true;
+}
+
+export function getEnvFilePath(): string {
+    return ENV_FILE;
+}
+
+export function getConfigDir(): string {
+    return CONFIG_DIR;
+}

package/src/utils/hash.ts

@@ -0,0 +1,42 @@
+import { createHash } from 'crypto';
+import fs from 'fs-extra';
+import { join } from 'path';
+
+export async function hashFile(filePath: string): Promise<string> {
+    const content = await fs.readFile(filePath);
+    return createHash('md5').update(content).digest('hex');
+}
+
+export async function hashDirectory(dirPath: string): Promise<string> {
+    if (!(await fs.pathExists(dirPath))) return '';
+    const stats = await fs.stat(dirPath);
+
+    if (!stats.isDirectory()) {
+        return hashFile(dirPath);
+    }
+
+    const children = await fs.readdir(dirPath);
+    const childHashes = await Promise.all(
+        children.sort().map(async (child) => {
+            const h = await hashDirectory(join(dirPath, child));
+            return `${child}:${h}`;
+        })
+    );
+    return createHash('md5').update(childHashes.join('|')).digest('hex');
+}
+
+export async function getNewestMtime(targetPath: string): Promise<number> {
+    if (!(await fs.pathExists(targetPath))) return 0;
+
+    const stats = await fs.stat(targetPath);
+    let maxTime = 0;
+
+    if (stats.isDirectory()) {
+        const children = await fs.readdir(targetPath);
+        for (const child of children) {
+            const childTime = await getNewestMtime(join(targetPath, child));
+            if (childTime > maxTime) maxTime = childTime;
+        }
+    }
+    return maxTime;
+}

package/src/utils/repo-root.ts

@@ -0,0 +1,39 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+async function walkUp(startDir: string): Promise<string | null> {
+    let dir = path.resolve(startDir);
+
+    while (true) {
+        const skillsPath = path.join(dir, 'skills');
+        const hooksPath  = path.join(dir, 'hooks');
+
+        if (await fs.pathExists(skillsPath) && await fs.pathExists(hooksPath)) {
+            return dir;
+        }
+
+        const parent = path.dirname(dir);
+        if (parent === dir) return null;
+        dir = parent;
+    }
+}
+
+/**
+ * Finds the jaggers-agent-tools repo root by:
+ * 1. Walking up from process.cwd() — works when run inside a cloned repo.
+ * 2. Walking up from __dirname    — works when run via `npx`, where the
+ *    package is extracted to a temp/cache directory that contains skills/ & hooks/.
+ */
+export async function findRepoRoot(): Promise<string> {
+    const fromCwd = await walkUp(process.cwd());
+    if (fromCwd) return fromCwd;
+
+    // __dirname is cli/dist/ inside the package — two levels up is the repo root.
+    const fromBundle = await walkUp(path.resolve(__dirname, '..', '..'));
+    if (fromBundle) return fromBundle;
+
+    throw new Error(
+        'Could not locate jaggers-agent-tools repo root.\n' +
+        'Run via `npx -y github:Jaggerxtrm/jaggers-agent-tools` or from within the cloned repository.'
+    );
+}