xtrm-cli 2.1.18 → 2.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-cli",
-  "version": "2.1.18",
+  "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/commands/install-project.ts

@@ -139,92 +139,6 @@ export async function getAvailableProjectSkills(): Promise<string[]> {
  * Deep merge settings.json hooks without overwriting existing user hooks.
  * Appends new hooks to existing events intelligently.
  */
-/**
- * Extract script filename from a hook command.
- */
-function getScriptFilename(hook: any): string | null {
-    const cmd = hook.command || hook.hooks?.[0]?.command || '';
-    if (typeof cmd !== 'string') return null;
-    // Match script filename (e.g., "beads-edit-gate.mjs" or "gitnexus/gitnexus-hook.cjs")
-    const m = cmd.match(/([A-Za-z0-9._/-]+\.(?:py|cjs|mjs|js))(?!.*[A-Za-z0-9._/-]+\.(?:py|cjs|mjs|js))/);
-    return m?.[1] ?? null;
-}
-
-/**
- * Prune hooks from settings.json that are NOT in the canonical config.
- * This removes stale entries from old versions before merging new ones.
- * 
- * @param existing Current settings.json hooks
- * @param canonical Canonical hooks config from hooks.json
- * @returns Pruned settings with stale hooks removed
- */
-export function pruneStaleHooks(
-    existing: Record<string, any>,
-    canonical: Record<string, any>,
-): { result: Record<string, any>; removed: string[] } {
-    const result = { ...existing };
-    const removed: string[] = [];
-
-    if (!result.hooks || typeof result.hooks !== 'object') {
-        return { result, removed };
-    }
-    if (!canonical.hooks || typeof canonical.hooks !== 'object') {
-        return { result, removed };
-    }
-
-    // Collect all canonical script filenames
-    const canonicalScripts = new Set<string>();
-    for (const [event, hooks] of Object.entries(canonical.hooks)) {
-        const hookList = Array.isArray(hooks) ? hooks : [hooks];
-        for (const wrapper of hookList) {
-            const innerHooks = wrapper.hooks || [wrapper];
-            for (const hook of innerHooks) {
-                const script = getScriptFilename(hook);
-                if (script) canonicalScripts.add(script);
-            }
-        }
-    }
-
-    // Prune existing hooks not in canonical
-    for (const [event, hooks] of Object.entries(result.hooks)) {
-        if (!Array.isArray(hooks)) continue;
-
-        const prunedWrappers: any[] = [];
-        for (const wrapper of hooks) {
-            const innerHooks = wrapper.hooks || [wrapper];
-            const keptInner: any[] = [];
-
-            for (const hook of innerHooks) {
-                const script = getScriptFilename(hook);
-                // Keep if: no script (not a file-based hook) OR script is canonical
-                if (!script || canonicalScripts.has(script)) {
-                    keptInner.push(hook);
-                } else {
-                    removed.push(`${event}:${script}`);
-                }
-            }
-
-            if (keptInner.length > 0) {
-                if (wrapper.hooks) {
-                    prunedWrappers.push({ ...wrapper, hooks: keptInner });
-                } else if (keptInner.length === 1) {
-                    prunedWrappers.push(keptInner[0]);
-                } else {
-                    prunedWrappers.push({ ...wrapper, hooks: keptInner });
-                }
-            }
-        }
-
-        if (prunedWrappers.length > 0) {
-            result.hooks[event] = prunedWrappers;
-        } else {
-            delete result.hooks[event];
-        }
-    }
-
-    return { result, removed };
-}
-
 export function deepMergeHooks(existing: Record<string, any>, incoming: Record<string, any>): Record<string, any> {
     const result = { ...existing };
 
@@ -352,15 +266,7 @@ export async function installProjectSkill(toolName: string, projectRootOverride?
         }
 
         const incomingSettings = JSON.parse(await fs.readFile(skillSettingsPath, 'utf8'));
-        
-        // First prune stale hooks not in canonical config
-        const { result: prunedSettings, removed } = pruneStaleHooks(existingSettings, incomingSettings);
-        if (removed.length > 0) {
-            console.log(kleur.yellow(`  ↳ Pruned ${removed.length} stale hook(s): ${removed.join(', ')}`));
-        }
-        
-        // Then merge canonical hooks
-        const mergedSettings = deepMergeHooks(prunedSettings, incomingSettings);
+        const mergedSettings = deepMergeHooks(existingSettings, incomingSettings);
 
         await fs.writeFile(targetSettingsPath, JSON.stringify(mergedSettings, null, 2) + '\n');
         console.log(`${kleur.green('  ✓')} settings.json (hooks merged)`);

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()),
@@ -130,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/hooks.test.ts

@@ -77,7 +77,7 @@ describe('main-guard.mjs — MAIN_GUARD_PROTECTED_BRANCHES', () => {
     );
     expect(r.status).toBe(2);
     const out = parseHookJson(r.stdout);
-    expect(out?.systemMessage).toContain('Bash is restricted');
+    expect(out?.systemMessage).toContain('Bash restricted');
   });
 
   it('allows safe Bash commands on protected branch', () => {
@@ -117,7 +117,7 @@ describe('main-guard.mjs — MAIN_GUARD_PROTECTED_BRANCHES', () => {
       );
       expect(r.status, `expected exit 2 for: ${command}`).toBe(2);
       const out = parseHookJson(r.stdout);
-      expect(out?.systemMessage).toContain('Bash is restricted');
+      expect(out?.systemMessage).toContain('Bash restricted');
     }
   });
 
@@ -331,7 +331,7 @@ exit 1
         { PATH: `${fake.tempDir}:${process.env.PATH ?? ''}` },
       );
       expect(r.status).toBe(2);
-      expect(r.stderr).toContain('no active claim');
+      expect(r.stderr).toContain('active claim');
     } finally {
       rmSync(fake.tempDir, { recursive: true, force: true });
       rmSync(projectDir, { recursive: true, force: true });
@@ -456,7 +456,7 @@ exit 1
         { PATH: `${fake.tempDir}:${process.env.PATH ?? ''}` },
       );
       expect(r.status).toBe(2);
-      expect(r.stderr).toContain('MEMORY GATE');
+      expect(r.stderr).toContain('Memory gate');
     } finally {
       rmSync(fake.tempDir, { recursive: true, force: true });
       rmSync(projectDir, { recursive: true, force: true });
@@ -553,51 +553,6 @@ exit 2
 });
 
 
-// ── gitnexus-impact-reminder.py ──────────────────────────────────────────────
-
-function runPythonHook(
-  hookFile: string,
-  input: Record<string, unknown>,
-) {
-  return spawnSync('python3', [path.join(HOOKS_DIR, hookFile)], {
-    input: JSON.stringify(input),
-    encoding: 'utf8',
-    env: { ...process.env },
-  });
-}
-
-describe('gitnexus-impact-reminder.py', () => {
-  it('injects additionalContext when prompt contains an edit-intent keyword', () => {
-    const r = runPythonHook('gitnexus-impact-reminder.py', {
-      hook_event_name: 'UserPromptSubmit',
-      prompt: 'fix the broken auth logic in login.ts',
-    });
-    expect(r.status).toBe(0);
-    const out = parseHookJson(r.stdout);
-    expect(out?.hookSpecificOutput?.additionalContext).toContain('gitnexus impact');
-  });
-
-  it('does nothing (no output) when prompt has no edit-intent keywords', () => {
-    const r = runPythonHook('gitnexus-impact-reminder.py', {
-      hook_event_name: 'UserPromptSubmit',
-      prompt: 'explain how the beads gate works',
-    });
-    expect(r.status).toBe(0);
-    expect(r.stdout.trim()).toBe('');
-  });
-
-  it('does nothing for non-UserPromptSubmit events', () => {
-    const r = runPythonHook('gitnexus-impact-reminder.py', {
-      hook_event_name: 'PreToolUse',
-      tool_name: 'Edit',
-      tool_input: { file_path: 'foo.ts' },
-      prompt: 'fix something',
-    });
-    expect(r.status).toBe(0);
-    expect(r.stdout.trim()).toBe('');
-  });
-});
-
 
 // ── beads-gate-core.mjs — decision functions ──────────────────────────────────