xtrm-cli 2.1.16 → 2.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-cli",
-  "version": "2.1.16",
+  "version": "2.1.19",
   "description": "Claude Code tools installer (skills, hooks, MCP servers)",
   "main": "./dist/index.js",
   "type": "module",

package/src/commands/clean.ts

@@ -0,0 +1,323 @@
+import { Command } from 'commander';
+import kleur from 'kleur';
+import fs from 'fs-extra';
+import path from 'path';
+import { homedir } from 'os';
+import { t, sym } from '../utils/theme.js';
+
+// Canonical hooks (files in ~/.claude/hooks/)
+const CANONICAL_HOOKS = new Set([
+    'agent_context.py',
+    'serena-workflow-reminder.py',
+    'main-guard.mjs',
+    'main-guard-post-push.mjs',
+    'beads-gate-core.mjs',
+    'beads-gate-utils.mjs',
+    'beads-gate-messages.mjs',
+    'beads-edit-gate.mjs',
+    'beads-commit-gate.mjs',
+    'beads-stop-gate.mjs',
+    'beads-memory-gate.mjs',
+    'beads-compact-save.mjs',
+    'beads-compact-restore.mjs',
+    'gitnexus',  // directory
+    'statusline-starship.sh',
+    'README.md',
+]);
+
+// Canonical skills (directories in ~/.agents/skills/)
+const CANONICAL_SKILLS = new Set([
+    'clean-code',
+    'delegating',
+    'docker-expert',
+    'documenting',
+    'find-skills',
+    'gitnexus-debugging',
+    'gitnexus-exploring',
+    'gitnexus-impact-analysis',
+    'gitnexus-refactoring',
+    'hook-development',
+    'obsidian-cli',
+    'orchestrating-agents',
+    'prompt-improving',
+    'python-testing',
+    'senior-backend',
+    'senior-data-scientist',
+    'senior-devops',
+    'senior-security',
+    'skill-creator',
+    'using-serena-lsp',
+    'using-TDD',
+    'using-xtrm',
+]);
+
+// Directories/files to always ignore
+const IGNORED_ITEMS = new Set([
+    '__pycache__',
+    '.DS_Store',
+    'Thumbs.db',
+    '.gitkeep',
+    'node_modules',
+]);
+
+interface CleanResult {
+    hooksRemoved: string[];
+    skillsRemoved: string[];
+    cacheRemoved: string[];
+}
+
+async function cleanHooks(dryRun: boolean): Promise<{ removed: string[]; cache: string[] }> {
+    const hooksDir = path.join(homedir(), '.claude', 'hooks');
+    const removed: string[] = [];
+    const cache: string[] = [];
+
+    if (!await fs.pathExists(hooksDir)) {
+        return { removed, cache };
+    }
+
+    const entries = await fs.readdir(hooksDir);
+
+    for (const entry of entries) {
+        // Skip ignored items but track them for cache cleanup
+        if (IGNORED_ITEMS.has(entry)) {
+            if (!dryRun) {
+                const fullPath = path.join(hooksDir, entry);
+                await fs.remove(fullPath);
+            }
+            cache.push(entry);
+            continue;
+        }
+
+        // Check if it's canonical
+        if (CANONICAL_HOOKS.has(entry)) {
+            continue;
+        }
+
+        // Check if it's a file we should remove
+        const fullPath = path.join(hooksDir, entry);
+        const stat = await fs.stat(fullPath);
+
+        // Only remove files, not arbitrary directories (except cache dirs)
+        if (stat.isFile() || (stat.isDirectory() && IGNORED_ITEMS.has(entry))) {
+            if (!dryRun) {
+                await fs.remove(fullPath);
+            }
+            removed.push(entry);
+        }
+    }
+
+    return { removed, cache };
+}
+
+async function cleanSkills(dryRun: boolean): Promise<string[]> {
+    const skillsDir = path.join(homedir(), '.agents', 'skills');
+    const removed: string[] = [];
+
+    if (!await fs.pathExists(skillsDir)) {
+        return removed;
+    }
+
+    const entries = await fs.readdir(skillsDir);
+
+    for (const entry of entries) {
+        // Skip ignored items
+        if (IGNORED_ITEMS.has(entry)) {
+            continue;
+        }
+
+        // Skip README.txt
+        if (entry === 'README.txt') {
+            continue;
+        }
+
+        // Check if it's canonical
+        if (CANONICAL_SKILLS.has(entry)) {
+            continue;
+        }
+
+        // Remove non-canonical directory
+        const fullPath = path.join(skillsDir, entry);
+        const stat = await fs.stat(fullPath);
+
+        if (stat.isDirectory()) {
+            if (!dryRun) {
+                await fs.remove(fullPath);
+            }
+            removed.push(entry);
+        }
+    }
+
+    return removed;
+}
+
+async function cleanOrphanedHookEntries(dryRun: boolean): Promise<string[]> {
+    const settingsPath = path.join(homedir(), '.claude', 'settings.json');
+    const removed: string[] = [];
+
+    if (!await fs.pathExists(settingsPath)) {
+        return removed;
+    }
+
+    let settings: any = {};
+    try {
+        settings = await fs.readJson(settingsPath);
+    } catch {
+        return removed;
+    }
+
+    if (!settings.hooks || typeof settings.hooks !== 'object') {
+        return removed;
+    }
+
+    // Collect canonical script names from CANONICAL_HOOKS
+    const canonicalScripts = new Set<string>();
+    for (const hook of CANONICAL_HOOKS) {
+        if (hook.endsWith('.py') || hook.endsWith('.mjs') || hook.endsWith('.cjs') || hook.endsWith('.js')) {
+            canonicalScripts.add(hook);
+        }
+    }
+    // Add gitnexus hook
+    canonicalScripts.add('gitnexus/gitnexus-hook.cjs');
+
+    // Check each hook entry
+    let modified = false;
+    for (const [event, wrappers] of Object.entries(settings.hooks)) {
+        if (!Array.isArray(wrappers)) continue;
+
+        const keptWrappers: any[] = [];
+        for (const wrapper of wrappers) {
+            const innerHooks = wrapper.hooks || [wrapper];
+            const keptInner: any[] = [];
+
+            for (const hook of innerHooks) {
+                const cmd = hook?.command || '';
+                // Extract script filename
+                const m = cmd.match(/\/hooks\/([A-Za-z0-9_/-]+\.(?:py|cjs|mjs|js))/);
+                const script = m?.[1];
+
+                if (!script || canonicalScripts.has(script)) {
+                    keptInner.push(hook);
+                } else {
+                    removed.push(`${event}:${script}`);
+                    modified = true;
+                }
+            }
+
+            if (keptInner.length > 0) {
+                if (wrapper.hooks) {
+                    keptWrappers.push({ ...wrapper, hooks: keptInner });
+                } else if (keptInner.length === 1) {
+                    keptWrappers.push(keptInner[0]);
+                }
+            }
+        }
+
+        if (keptWrappers.length > 0) {
+            settings.hooks[event] = keptWrappers;
+        } else {
+            delete settings.hooks[event];
+            modified = true;
+        }
+    }
+
+    if (modified && !dryRun) {
+        await fs.writeJson(settingsPath, settings, { spaces: 2 });
+    }
+
+    return removed;
+}
+
+export function createCleanCommand(): Command {
+    return new Command('clean')
+        .description('Remove orphaned hooks and skills not in the canonical repository')
+        .option('--dry-run', 'Preview what would be removed without making changes', false)
+        .option('--hooks-only', 'Only clean hooks, skip skills', false)
+        .option('--skills-only', 'Only clean skills, skip hooks', false)
+        .option('-y, --yes', 'Skip confirmation prompt', false)
+        .action(async (opts) => {
+            const { dryRun, hooksOnly, skillsOnly, yes } = opts;
+
+            console.log(t.bold('\n  XTRM Clean — Remove Orphaned Components\n'));
+
+            if (dryRun) {
+                console.log(kleur.yellow('  DRY RUN — No changes will be made\n'));
+            }
+
+            const result: CleanResult = {
+                hooksRemoved: [],
+                skillsRemoved: [],
+                cacheRemoved: [],
+            };
+
+            // Clean hooks
+            if (!skillsOnly) {
+                console.log(kleur.bold('  Scanning ~/.claude/hooks/...'));
+                const { removed, cache } = await cleanHooks(dryRun);
+                result.hooksRemoved = removed;
+                result.cacheRemoved = cache;
+
+                if (removed.length > 0) {
+                    for (const f of removed) {
+                        console.log(kleur.red(`    ✗ ${f}`));
+                    }
+                } else {
+                    console.log(kleur.dim('    ✓ No orphaned hooks found'));
+                }
+
+                if (cache.length > 0) {
+                    console.log(kleur.dim(`    ↳ Cleaned ${cache.length} cache directory(ies)`));
+                }
+
+                // Clean orphaned hook entries in settings.json
+                console.log(kleur.bold('\n  Scanning settings.json for orphaned hook entries...'));
+                const orphanedEntries = await cleanOrphanedHookEntries(dryRun);
+                if (orphanedEntries.length > 0) {
+                    for (const entry of orphanedEntries) {
+                        console.log(kleur.red(`    ✗ ${entry}`));
+                    }
+                } else {
+                    console.log(kleur.dim('    ✓ No orphaned hook entries found'));
+                }
+            }
+
+            // Clean skills
+            if (!hooksOnly) {
+                console.log(kleur.bold('\n  Scanning ~/.agents/skills/...'));
+                result.skillsRemoved = await cleanSkills(dryRun);
+
+                if (result.skillsRemoved.length > 0) {
+                    for (const d of result.skillsRemoved) {
+                        console.log(kleur.red(`    ✗ ${d}/`));
+                    }
+                } else {
+                    console.log(kleur.dim('    ✓ No orphaned skills found'));
+                }
+            }
+
+            // Summary
+            const totalRemoved = result.hooksRemoved.length + result.skillsRemoved.length + result.cacheRemoved.length;
+
+            if (totalRemoved === 0) {
+                console.log(t.boldGreen('\n  ✓ All components are canonical — nothing to clean\n'));
+                return;
+            }
+
+            console.log(kleur.bold('\n  Summary:'));
+            if (result.hooksRemoved.length > 0) {
+                console.log(kleur.red(`    ${result.hooksRemoved.length} orphaned hook(s)`));
+            }
+            if (result.skillsRemoved.length > 0) {
+                console.log(kleur.red(`    ${result.skillsRemoved.length} orphaned skill(s)`));
+            }
+            if (result.cacheRemoved.length > 0) {
+                console.log(kleur.dim(`    ${result.cacheRemoved.length} cache director(y/ies)`));
+            }
+
+            if (!dryRun) {
+                console.log(t.boldGreen('\n  ✓ Cleanup complete\n'));
+                console.log(kleur.dim('  Run `xtrm install all -y` to reinstall canonical components\n'));
+            } else {
+                console.log(kleur.yellow('\n  ℹ Dry run — run without --dry-run to apply changes\n'));
+            }
+        });
+}

package/src/utils/atomic-config.ts

@@ -53,6 +53,89 @@ function commandKey(command: string): string {
     return m?.[1] || command.trim();
 }
 
+/**
+ * Extract script filename from a hook command for pruning purposes.
+ */
+function scriptKey(command: string): string | null {
+    // Match the script path relative to hooks directory
+    // Pattern: /hooks/<optional-subdir>/<filename>.<ext>
+    const m = command.match(/\/hooks\/([A-Za-z0-9_/-]+\.(?:py|cjs|mjs|js))/);
+    if (m) return m[1];
+
+    // Fallback: match just the filename if no /hooks/ path
+    const m2 = command.match(/([A-Za-z0-9_-]+\.(?:py|cjs|mjs|js))(?!.*[A-Za-z0-9._-]+\.(?:py|cjs|mjs|js))/);
+    return m2?.[1] || null;
+}
+
+/**
+ * Collect all canonical script filenames from incoming hooks.
+ */
+function collectCanonicalScripts(incomingHooks: any): Set<string> {
+    const scripts = new Set<string>();
+    if (!incomingHooks || typeof incomingHooks !== 'object') return scripts;
+
+    for (const wrappers of Object.values(incomingHooks)) {
+        if (!Array.isArray(wrappers)) continue;
+        for (const wrapper of wrappers) {
+            const commands = extractHookCommands(wrapper);
+            for (const cmd of commands) {
+                const script = scriptKey(cmd);
+                if (script) scripts.add(script);
+            }
+        }
+    }
+    return scripts;
+}
+
+/**
+ * Prune existing hook wrappers that reference scripts NOT in canonical set.
+ * Returns { pruned: wrappers[], removed: string[] }
+ */
+function pruneStaleWrappers(existing: any[], canonicalScripts: Set<string>): { pruned: any[]; removed: string[] } {
+    if (canonicalScripts.size === 0) {
+        return { pruned: existing, removed: [] };
+    }
+
+    const removed: string[] = [];
+    const pruned: any[] = [];
+
+    for (const wrapper of existing) {
+        if (!Array.isArray(wrapper.hooks)) {
+            pruned.push(wrapper);
+            continue;
+        }
+
+        const keptHooks: any[] = [];
+        for (const hook of wrapper.hooks) {
+            const cmd = hook?.command;
+            if (typeof cmd !== 'string') {
+                keptHooks.push(hook);
+                continue;
+            }
+            // Only prune hooks that are clearly xtrm-managed (have /hooks/ in their path)
+            // User-local hooks from other directories are always preserved
+            const isXtrmManaged = /\/hooks\//.test(cmd);
+            if (!isXtrmManaged) {
+                keptHooks.push(hook);
+                continue;
+            }
+            const script = scriptKey(cmd);
+            // Keep if: no script (not a file-based hook) OR script is in canonical set
+            if (!script || canonicalScripts.has(script)) {
+                keptHooks.push(hook);
+            } else {
+                removed.push(script);
+            }
+        }
+
+        if (keptHooks.length > 0) {
+            pruned.push({ ...wrapper, hooks: keptHooks });
+        }
+    }
+
+    return { pruned, removed };
+}
+
 function mergeMatcher(existingMatcher: string, incomingMatcher: string): string {
     const parts = [
         ...existingMatcher.split('|').map((s: string) => s.trim()),
@@ -72,9 +155,31 @@ function mergeHookWrappers(existing: any[], incoming: any[]): any[] {
         }
 
         const incomingKeys = new Set(incomingCommands.map(commandKey));
+        const incomingTokens = new Set(
+            typeof incomingWrapper.matcher === 'string'
+                ? incomingWrapper.matcher.split('|').map((s: string) => s.trim()).filter(Boolean)
+                : [],
+        );
+
         const existingIndex = merged.findIndex((existingWrapper: any) => {
             const existingCommands = extractHookCommands(existingWrapper);
-            return existingCommands.some((c: string) => incomingKeys.has(commandKey(c)));
+            if (!existingCommands.some((c: string) => incomingKeys.has(commandKey(c)))) return false;
+
+            // Only merge with entries whose matchers overlap (share at least one token).
+            // Disjoint matchers (e.g. "Write|Edit" vs "Bash") intentionally serve
+            // different purposes and must remain as separate entries.
+            if (
+                typeof existingWrapper.matcher === 'string' &&
+                typeof incomingWrapper.matcher === 'string' &&
+                incomingTokens.size > 0
+            ) {
+                const existingTokens = existingWrapper.matcher
+                    .split('|').map((s: string) => s.trim()).filter(Boolean);
+                const hasOverlap = existingTokens.some((t: string) => incomingTokens.has(t));
+                if (!hasOverlap) return false;
+            }
+
+            return true;
         });
 
         if (existingIndex === -1) {
@@ -108,7 +213,23 @@ function mergeHookWrappers(existing: any[], incoming: any[]): any[] {
 }
 
 function mergeHooksObject(existingHooks: any, incomingHooks: any): any {
-    const result = { ...(existingHooks || {}) };
+    // Step 1: Collect canonical script filenames from incoming hooks
+    const canonicalScripts = collectCanonicalScripts(incomingHooks);
+
+    // Step 2: Prune existing hooks that reference non-canonical scripts
+    const result: any = {};
+    for (const [event, existingWrappers] of Object.entries(existingHooks || {})) {
+        if (!Array.isArray(existingWrappers)) {
+            result[event] = existingWrappers;
+            continue;
+        }
+        const { pruned } = pruneStaleWrappers(existingWrappers, canonicalScripts);
+        if (pruned.length > 0) {
+            result[event] = pruned;
+        }
+    }
+
+    // Step 3: Merge incoming hooks with pruned existing hooks
     for (const [event, incomingWrappers] of Object.entries(incomingHooks || {})) {
         const existingWrappers = Array.isArray(result[event]) ? result[event] : [];
         const incomingArray = Array.isArray(incomingWrappers) ? incomingWrappers : [];

package/test/atomic-config.test.ts

@@ -81,3 +81,58 @@ describe('deepMergeWithProtection (hooks merge behavior)', () => {
         expect(merged.hooks.SessionStart).toHaveLength(2);
     });
 });
+
+
+describe('deepMergeWithProtection (hooks merge behavior) — matcher dedup', () => {
+    it('keeps two same-script entries separate when their matchers are disjoint', () => {
+        // Simulates config/hooks.json having main-guard wired for write-tools
+        // AND separately for Bash — they must not be merged into one entry
+        const local = {
+            hooks: {
+                PreToolUse: [] as any[],
+            },
+        };
+        const incoming = {
+            hooks: {
+                PreToolUse: [
+                    {
+                        matcher: 'Write|Edit|MultiEdit',
+                        hooks: [{ command: 'node "/hooks/main-guard.mjs"', timeout: 5000 }],
+                    },
+                    {
+                        matcher: 'Bash',
+                        hooks: [{ command: 'node "/hooks/main-guard.mjs"', timeout: 5000 }],
+                    },
+                ],
+            },
+        };
+        const merged = deepMergeWithProtection(local, incoming);
+        const wrappers = merged.hooks.PreToolUse;
+        expect(wrappers).toHaveLength(2);
+        expect(wrappers[0].matcher).toBe('Write|Edit|MultiEdit');
+        expect(wrappers[1].matcher).toBe('Bash');
+    });
+
+    it('still upgrades matcher when entries share at least one common token', () => {
+        const local = {
+            hooks: {
+                PreToolUse: [{
+                    matcher: 'Write|Edit',
+                    hooks: [{ command: 'node "/hooks/main-guard.mjs"' }],
+                }],
+            },
+        };
+        const incoming = {
+            hooks: {
+                PreToolUse: [{
+                    matcher: 'Write|Edit|MultiEdit',
+                    hooks: [{ command: 'node "/hooks/main-guard.mjs"' }],
+                }],
+            },
+        };
+        const merged = deepMergeWithProtection(local, incoming);
+        const wrappers = merged.hooks.PreToolUse;
+        expect(wrappers).toHaveLength(1);
+        expect(wrappers[0].matcher).toContain('MultiEdit');
+    });
+});