xtrm-cli 2.1.14 → 2.1.18

package/package.json

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

package/src/commands/install-project.ts

@@ -139,6 +139,92 @@ 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 };
 
@@ -266,7 +352,15 @@ export async function installProjectSkill(toolName: string, projectRootOverride?
         }
 
         const incomingSettings = JSON.parse(await fs.readFile(skillSettingsPath, 'utf8'));
-        const mergedSettings = deepMergeHooks(existingSettings, incomingSettings);
+        
+        // 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);
 
         await fs.writeFile(targetSettingsPath, JSON.stringify(mergedSettings, null, 2) + '\n');
         console.log(`${kleur.green('  ✓')} settings.json (hooks merged)`);

package/src/commands/install.ts

@@ -125,6 +125,15 @@ function isDoltInstalled(): boolean {
     }
 }
 
+function isGitnexusInstalled(): boolean {
+    try {
+        execSync('gitnexus --version', { stdio: 'ignore' });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
 interface GlobalInstallFlags {
     dryRun: boolean;
     yes: boolean;
@@ -221,6 +230,34 @@ async function runGlobalInstall(
         }
     }
 
+    // Gitnexus global install (for MCP server + CLI tools)
+    console.log(t.bold('\n  ⚙  gitnexus  (code intelligence)'));
+    console.log(t.muted('  GitNexus provides knowledge graph queries for impact analysis, execution flows, and symbol context.'));
+
+    const gitnexusOk = isGitnexusInstalled();
+    if (gitnexusOk) {
+        console.log(t.success('  ✓ gitnexus already installed\n'));
+    } else {
+        let doInstallGitnexus = effectiveYes;
+        if (!effectiveYes) {
+            const { install } = await prompts({
+                type: 'confirm',
+                name: 'install',
+                message: 'Install gitnexus globally? (recommended for MCP server and CLI tools)',
+                initial: true,
+            });
+            doInstallGitnexus = install;
+        }
+
+        if (doInstallGitnexus) {
+            console.log(t.muted('\n  Installing gitnexus...'));
+            spawnSync('npm', ['install', '-g', 'gitnexus'], { stdio: 'inherit' });
+            console.log(t.success('  ✓ gitnexus installed\n'));
+        } else {
+            console.log(t.muted('  ℹ Skipped. Install later with: npm install -g gitnexus\n'));
+        }
+    }
+
     const diffTasks = new Listr<DiffCtx>(
         targets.map(target => ({
             title: formatTargetLabel(target),

package/src/utils/atomic-config.ts

@@ -72,9 +72,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) {

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

package/test/hooks.test.ts

@@ -121,6 +121,15 @@ describe('main-guard.mjs — MAIN_GUARD_PROTECTED_BRANCHES', () => {
     }
   });
 
+  it('allows touch .beads/.memory-gate-done on protected branch', () => {
+    const r = runHook(
+      'main-guard.mjs',
+      { tool_name: 'Bash', tool_input: { command: 'touch .beads/.memory-gate-done' } },
+      { MAIN_GUARD_PROTECTED_BRANCHES: CURRENT_BRANCH },
+    );
+    expect(r.status).toBe(0);
+  });
+
   it('allows Bash when MAIN_GUARD_ALLOW_BASH=1 is set', () => {
     const r = runHook(
       'main-guard.mjs',
@@ -187,9 +196,11 @@ describe('main-guard-post-push.mjs', () => {
         repoDir,
       );
       expect(r.status).toBe(0);
-      const out = parseHookJson(r.stdout);
-      expect(out?.systemMessage).toContain('gh pr create --fill');
-      expect(out?.systemMessage).toContain('gh pr merge --squash');
+      expect(r.stdout).toContain('gh pr create --fill');
+      expect(r.stdout).toContain('gh pr merge --squash');
+      // output must be plain text (agent-only), not a JSON systemMessage banner
+      expect(parseHookJson(r.stdout)).toBeNull();
+
     } finally {
       rmSync(repoDir, { recursive: true, force: true });
     }
@@ -586,3 +597,259 @@ describe('gitnexus-impact-reminder.py', () => {
     expect(r.stdout.trim()).toBe('');
   });
 });
+
+
+// ── beads-gate-core.mjs — decision functions ──────────────────────────────────
+
+describe('beads-gate-core.mjs — decision functions', () => {
+  const corePath = path.join(HOOKS_DIR, 'beads-gate-core.mjs');
+
+  it('exports all required decision functions', () => {
+    const r = spawnSync('node', ['--input-type=module'], {
+      input: `
+import {
+  readHookInput,
+  resolveSessionContext,
+  resolveClaimAndWorkState,
+  decideEditGate,
+  decideCommitGate,
+  decideStopGate,
+} from '${corePath}';
+const ok = [readHookInput, resolveSessionContext, resolveClaimAndWorkState,
+            decideEditGate, decideCommitGate, decideStopGate]
+  .every(fn => typeof fn === 'function');
+process.exit(ok ? 0 : 1);
+`,
+      encoding: 'utf8',
+    });
+    expect(r.status).toBe(0);
+  });
+
+  describe('decideEditGate', () => {
+    it('allows when not a beads project', async () => {
+      const { decideEditGate } = await import(corePath);
+      const decision = decideEditGate(
+        { isBeadsProject: false },
+        { claimed: false, claimId: null, totalWork: 0, inProgress: null }
+      );
+      expect(decision.allow).toBe(true);
+    });
+
+    it('allows when session has a claim', async () => {
+      const { decideEditGate } = await import(corePath);
+      const decision = decideEditGate(
+        { isBeadsProject: true, sessionId: 'test-session' },
+        { claimed: true, claimId: 'issue-123', totalWork: 5, inProgress: null }
+      );
+      expect(decision.allow).toBe(true);
+    });
+
+    it('allows when no trackable work exists', async () => {
+      const { decideEditGate } = await import(corePath);
+      const decision = decideEditGate(
+        { isBeadsProject: true, sessionId: 'test-session' },
+        { claimed: false, claimId: null, totalWork: 0, inProgress: null }
+      );
+      expect(decision.allow).toBe(true);
+    });
+
+    it('blocks when no claim but work exists', async () => {
+      const { decideEditGate } = await import(corePath);
+      const decision = decideEditGate(
+        { isBeadsProject: true, sessionId: 'test-session' },
+        { claimed: false, claimId: null, totalWork: 3, inProgress: null }
+      );
+      expect(decision.allow).toBe(false);
+      expect(decision.reason).toBe('no_claim_with_work');
+    });
+
+    it('fails open when bd unavailable (state is null)', async () => {
+      const { decideEditGate } = await import(corePath);
+      const decision = decideEditGate(
+        { isBeadsProject: true, sessionId: 'test-session' },
+        null
+      );
+      expect(decision.allow).toBe(true);
+    });
+  });
+
+  describe('decideCommitGate', () => {
+    it('allows when no active claim', async () => {
+      const { decideCommitGate } = await import(corePath);
+      const decision = decideCommitGate(
+        { isBeadsProject: true, sessionId: 'test-session' },
+        { claimed: false, claimId: null, totalWork: 3, inProgress: { count: 1, summary: 'test' } }
+      );
+      expect(decision.allow).toBe(true);
+    });
+
+    it('blocks when session has unclosed claim', async () => {
+      const { decideCommitGate } = await import(corePath);
+      const decision = decideCommitGate(
+        { isBeadsProject: true, sessionId: 'test-session' },
+        { claimed: true, claimId: 'issue-123', totalWork: 3, inProgress: { count: 1, summary: 'test' } }
+      );
+      expect(decision.allow).toBe(false);
+      expect(decision.reason).toBe('unclosed_claim');
+    });
+  });
+
+  describe('decideStopGate', () => {
+    it('allows when claim is stale (no in_progress issues)', async () => {
+      const { decideStopGate } = await import(corePath);
+      const decision = decideStopGate(
+        { isBeadsProject: true, sessionId: 'test-session' },
+        { claimed: true, claimId: 'issue-123', totalWork: 3, inProgress: { count: 0, summary: '' } }
+      );
+      expect(decision.allow).toBe(true);
+    });
+
+    it('blocks when claim exists and in_progress issues remain', async () => {
+      const { decideStopGate } = await import(corePath);
+      const decision = decideStopGate(
+        { isBeadsProject: true, sessionId: 'test-session' },
+        { claimed: true, claimId: 'issue-123', totalWork: 3, inProgress: { count: 2, summary: 'test' } }
+      );
+      expect(decision.allow).toBe(false);
+      expect(decision.reason).toBe('unclosed_claim');
+    });
+  });
+});
+
+
+// ── beads-compact-save.mjs ───────────────────────────────────────────────────
+describe('beads-compact-save.mjs', () => {
+  it('exits 0 silently when no .beads directory exists', () => {
+    const r = runHook('beads-compact-save.mjs', { hook_event_name: 'PreCompact', cwd: '/tmp' });
+    expect(r.status).toBe(0);
+    expect(r.stdout).toBe('');
+  });
+
+  it('exits 0 silently and writes no file when no in_progress issues', () => {
+    const projectDir = mkdtempSync(path.join(os.tmpdir(), 'xtrm-compact-save-'));
+    mkdirSync(path.join(projectDir, '.beads'));
+    const fake = withFakeBdDir(`#!/usr/bin/env bash
+if [[ "$1" == "list" ]]; then
+  echo ""
+  echo "--------------------------------------------------------------------------------"
+  echo "Total: 2 issues (2 open, 0 in progress)"
+  exit 0
+fi
+exit 1
+`);
+    try {
+      const r = runHook(
+        'beads-compact-save.mjs',
+        { hook_event_name: 'PreCompact', cwd: projectDir },
+        { PATH: `${fake.tempDir}:${process.env.PATH ?? ''}` },
+      );
+      expect(r.status).toBe(0);
+      const { existsSync } = require('node:fs');
+      expect(existsSync(path.join(projectDir, '.beads', '.last_active'))).toBe(false);
+    } finally {
+      rmSync(fake.tempDir, { recursive: true, force: true });
+      rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+
+  it('writes .beads/.last_active with in_progress issue IDs', () => {
+    const projectDir = mkdtempSync(path.join(os.tmpdir(), 'xtrm-compact-save-'));
+    mkdirSync(path.join(projectDir, '.beads'));
+    const fake = withFakeBdDir(`#!/usr/bin/env bash
+if [[ "$1" == "list" ]]; then
+  cat <<'EOF'
+◐ proj-abc123 ● P1 First in_progress issue
+◐ proj-def456 ● P2 Second in_progress issue
+
+--------------------------------------------------------------------------------
+Total: 2 issues (0 open, 2 in progress)
+EOF
+  exit 0
+fi
+exit 1
+`);
+    try {
+      const r = runHook(
+        'beads-compact-save.mjs',
+        { hook_event_name: 'PreCompact', cwd: projectDir },
+        { PATH: `${fake.tempDir}:${process.env.PATH ?? ''}` },
+      );
+      expect(r.status).toBe(0);
+      const { readFileSync: rfs } = require('node:fs');
+      const saved = rfs(path.join(projectDir, '.beads', '.last_active'), 'utf8').trim().split('\n');
+      expect(saved).toContain('proj-abc123');
+      expect(saved).toContain('proj-def456');
+    } finally {
+      rmSync(fake.tempDir, { recursive: true, force: true });
+      rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+});
+
+// ── beads-compact-restore.mjs ────────────────────────────────────────────────
+describe('beads-compact-restore.mjs', () => {
+  it('exits 0 silently when no .beads/.last_active file exists', () => {
+    const projectDir = mkdtempSync(path.join(os.tmpdir(), 'xtrm-compact-restore-'));
+    mkdirSync(path.join(projectDir, '.beads'));
+    try {
+      const r = runHook(
+        'beads-compact-restore.mjs',
+        { hook_event_name: 'SessionStart', cwd: projectDir },
+      );
+      expect(r.status).toBe(0);
+      expect(r.stdout).toBe('');
+    } finally {
+      rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+
+  it('restores in_progress status, deletes .last_active, and injects additionalSystemPrompt', () => {
+    const projectDir = mkdtempSync(path.join(os.tmpdir(), 'xtrm-compact-restore-'));
+    mkdirSync(path.join(projectDir, '.beads'));
+    const { writeFileSync: wfs } = require('node:fs');
+    wfs(path.join(projectDir, '.beads', '.last_active'), 'proj-abc123\nproj-def456\n', 'utf8');
+
+    const callLog = path.join(projectDir, 'bd-calls.log');
+    const fake = withFakeBdDir(`#!/usr/bin/env bash
+echo "$@" >> "${callLog}"
+exit 0
+`);
+    try {
+      const r = runHook(
+        'beads-compact-restore.mjs',
+        { hook_event_name: 'SessionStart', cwd: projectDir },
+        { PATH: `${fake.tempDir}:${process.env.PATH ?? ''}` },
+      );
+      expect(r.status).toBe(0);
+      // .last_active must be deleted
+      const { existsSync: exs, readFileSync: rfs } = require('node:fs');
+      expect(exs(path.join(projectDir, '.beads', '.last_active'))).toBe(false);
+      // bd update called for each ID
+      const calls = rfs(callLog, 'utf8');
+      expect(calls).toContain('proj-abc123');
+      expect(calls).toContain('proj-def456');
+      // additionalSystemPrompt injected for agent
+      const out = parseHookJson(r.stdout);
+      expect(out?.hookSpecificOutput?.additionalSystemPrompt).toMatch(/Restored 2 in_progress issue/);
+    } finally {
+      rmSync(fake.tempDir, { recursive: true, force: true });
+      rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+});
+
+
+// ── hooks.json wiring ────────────────────────────────────────────────────────
+describe('hooks.json — beads-compact hooks wiring', () => {
+  it('wires beads-compact-save.mjs to PreCompact event', () => {
+    const cfg = JSON.parse(readFileSync(path.join(__dirname, '../../config/hooks.json'), 'utf8'));
+    const preCompact: Array<{ script: string }> = cfg.hooks.PreCompact ?? [];
+    expect(preCompact.some((h) => h.script === 'beads-compact-save.mjs')).toBe(true);
+  });
+
+  it('wires beads-compact-restore.mjs to SessionStart event', () => {
+    const cfg = JSON.parse(readFileSync(path.join(__dirname, '../../config/hooks.json'), 'utf8'));
+    const sessionStart: Array<{ script: string }> = cfg.hooks.SessionStart ?? [];
+    expect(sessionStart.some((h) => h.script === 'beads-compact-restore.mjs')).toBe(true);
+  });
+});