xtrm-cli 0.5.0

package/src/commands/clean.ts

@@ -0,0 +1,371 @@
+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';
+import { findRepoRoot } from '../utils/repo-root.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-claim-sync.mjs',
+    'beads-compact-save.mjs',
+    'beads-compact-restore.mjs',
+    'branch-state.mjs',
+    'quality-check.cjs',
+    'quality-check.py',
+    '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',
+    'using-quality-gates',
+    'using-service-skills',
+    'updating-service-skills',
+    'creating-service-skills',
+    'scoping-service-skills',
+]);
+
+// 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, repoRoot: string | null): 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);
+        }
+    }
+    canonicalScripts.add('gitnexus/gitnexus-hook.cjs');
+
+    // Build canonical wiring map from config/hooks.json: script -> Set<"event:::matcher|NONE">
+    // Used to detect canonical scripts wired to wrong events or with stale matchers.
+    const canonicalWiringKeys = new Map<string, Set<string>>();
+    if (repoRoot) {
+        const hooksJsonPath = path.join(repoRoot, 'config', 'hooks.json');
+        try {
+            if (await fs.pathExists(hooksJsonPath)) {
+                const hooksJson = await fs.readJson(hooksJsonPath);
+                for (const [event, entries] of Object.entries(hooksJson.hooks ?? {})) {
+                    for (const entry of entries as any[]) {
+                        const script: string = entry.script;
+                        if (!script) continue;
+                        const key = `${event}:::${entry.matcher ?? 'NONE'}`;
+                        if (!canonicalWiringKeys.has(script)) canonicalWiringKeys.set(script, new Set());
+                        canonicalWiringKeys.get(script)!.add(key);
+                    }
+                }
+            }
+        } catch { /* ignore, fall back to script-only check */ }
+    }
+
+    // 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 || '';
+                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) {
+                // Validate canonical wiring: check that this (event, matcher) combo exists in canonical source
+                if (canonicalWiringKeys.size > 0) {
+                    const firstCmd: string = keptInner[0]?.command || '';
+                    const sm = firstCmd.match(/\/hooks\/([A-Za-z0-9_/-]+\.(?:py|cjs|mjs|js))/);
+                    const script = sm?.[1];
+
+                    if (script && canonicalScripts.has(script)) {
+                        const validKeys = canonicalWiringKeys.get(script);
+                        const wiringKey = `${event}:::${(wrapper.matcher as string | undefined) ?? 'NONE'}`;
+                        if (validKeys && !validKeys.has(wiringKey)) {
+                            removed.push(`${event}:${script} (stale wiring)`);
+                            modified = true;
+                            continue; // drop this wrapper
+                        }
+                    }
+                }
+
+                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...'));
+                let repoRoot: string | null = null;
+                try { repoRoot = await findRepoRoot(); } catch { /* not in repo context */ }
+                const orphanedEntries = await cleanOrphanedHookEntries(dryRun, repoRoot);
+                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/end.ts

@@ -0,0 +1,239 @@
+import { Command } from 'commander';
+import kleur from 'kleur';
+import prompts from 'prompts';
+import { spawnSync, execSync } from 'node:child_process';
+import { t } from '../utils/theme.js';
+
+interface EndOptions {
+    draft: boolean;
+    keep: boolean;
+    yes: boolean;
+}
+
+function git(args: string[], cwd: string): { ok: boolean; out: string; err: string } {
+    const r = spawnSync('git', args, { cwd, encoding: 'utf8', stdio: 'pipe' });
+    return { ok: r.status === 0, out: (r.stdout ?? '').trim(), err: (r.stderr ?? '').trim() };
+}
+
+function bd(args: string[], cwd: string): { ok: boolean; out: string } {
+    const r = spawnSync('bd', args, { cwd, encoding: 'utf8', stdio: 'pipe' });
+    return { ok: r.status === 0, out: (r.stdout ?? '').trim() };
+}
+
+/** Extract issue IDs from commit messages like "reason (jaggers-agent-tools-xxxx)" */
+function extractIssueIds(commitLog: string): string[] {
+    const matches = commitLog.matchAll(/\(([a-z0-9]+-[a-z0-9]+-[a-z0-9]+)\)/g);
+    return [...new Set([...matches].map(m => m[1]))];
+}
+
+/** Generate PR title from issue data */
+function buildPrTitle(issues: Array<{ id: string; reason: string; title: string }>): string {
+    if (issues.length === 0) return 'session changes';
+    if (issues.length === 1) return issues[0].reason || issues[0].title;
+    return `${issues[0].reason || issues[0].title} (+${issues.length - 1} more)`;
+}
+
+/** Generate PR body from issues, commit log, diff stat */
+function buildPrBody(
+    issues: Array<{ id: string; title: string; description: string; reason: string }>,
+    commitLog: string,
+    diffStat: string,
+    branch: string,
+): string {
+    const lines: string[] = [];
+
+    lines.push('## What');
+    if (issues.length > 0) {
+        for (const issue of issues) {
+            lines.push(`- **${issue.id}**: ${issue.title}`);
+            if (issue.description) lines.push(`  ${issue.description.split('\n')[0]}`);
+        }
+    } else {
+        lines.push(`Session branch: \`${branch}\``);
+    }
+
+    if (issues.some(i => i.reason)) {
+        lines.push('', '## Why');
+        for (const issue of issues) {
+            if (issue.reason) lines.push(`- ${issue.id}: ${issue.reason}`);
+        }
+    }
+
+    if (commitLog) {
+        lines.push('', '## Changes');
+        const commits = commitLog.split('\n').slice(0, 20);
+        lines.push(...commits.map(c => `- ${c}`));
+        if (commitLog.split('\n').length > 20) lines.push('- *(and more...)*');
+    }
+
+    if (diffStat) {
+        lines.push('', '## Files changed');
+        lines.push('```');
+        lines.push(diffStat);
+        lines.push('```');
+    }
+
+    if (issues.length > 0) {
+        lines.push('', `Closes: ${issues.map(i => i.id).join(' ')}`);
+    }
+
+    return lines.join('\n');
+}
+
+export function createEndCommand(): Command {
+    return new Command('end')
+        .description('Close session: rebase, push, open PR, link beads issues, clean up worktree')
+        .option('--draft', 'Open PR as draft', false)
+        .option('--keep', 'Keep worktree after PR creation (default: prompt)', false)
+        .option('-y, --yes', 'Skip confirmation prompts', false)
+        .action(async (opts: EndOptions) => {
+            const cwd = process.cwd();
+
+            // 1. Gate: must be in an xt worktree (branch starts with xt/)
+            const branchResult = git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+            const branch = branchResult.out;
+
+            if (!branch.startsWith('xt/')) {
+                console.error(kleur.red(
+                    `\n  ✗ Not in an xt worktree (current branch: ${branch})\n` +
+                    `  xt end must be run from inside a worktree created by xt claude/pi\n`
+                ));
+                process.exit(1);
+            }
+
+            // 2. Gate: no uncommitted changes
+            const statusResult = git(['status', '--porcelain'], cwd);
+            if (statusResult.out.length > 0) {
+                console.error(kleur.red(
+                    '\n  ✗ Uncommitted changes detected. Commit or stash before running xt end.\n'
+                ));
+                console.error(kleur.dim(statusResult.out));
+                process.exit(1);
+            }
+
+            console.log(t.bold(`\n  xt end — closing session on ${branch}\n`));
+
+            // 3. Collect closed issues from commit log
+            const logResult = git(['log', 'origin/main..HEAD', '--oneline'], cwd);
+            const issueIds = extractIssueIds(logResult.out);
+
+            const issues: Array<{ id: string; title: string; description: string; reason: string }> = [];
+            for (const id of issueIds) {
+                const showResult = bd(['show', id, '--json'], cwd);
+                if (showResult.ok) {
+                    try {
+                        const data = JSON.parse(showResult.out);
+                        issues.push({
+                            id,
+                            title: data.title ?? id,
+                            description: data.description ?? '',
+                            reason: data.close_reason ?? '',
+                        });
+                    } catch {
+                        issues.push({ id, title: id, description: '', reason: '' });
+                    }
+                }
+            }
+
+            if (issues.length > 0) {
+                console.log(t.success(`  ✓ Found ${issues.length} closed issue(s): ${issueIds.join(', ')}`));
+            } else {
+                console.log(kleur.dim('  ○ No beads issues found in commit log'));
+            }
+
+            // 4. Fetch to ensure origin/main is current
+            console.log(kleur.dim('  Fetching origin/main...'));
+            git(['fetch', 'origin', 'main'], cwd);
+
+            // 5. Rebase
+            console.log(kleur.dim('  Rebasing onto origin/main...'));
+            const rebaseResult = git(['rebase', 'origin/main'], cwd);
+            if (!rebaseResult.ok) {
+                const conflicts = git(['diff', '--name-only', '--diff-filter=U'], cwd).out;
+                console.error(kleur.red('\n  ✗ Rebase conflicts detected:\n'));
+                if (conflicts) {
+                    for (const f of conflicts.split('\n')) console.error(kleur.yellow(`    ${f}`));
+                }
+                console.error(kleur.dim(
+                    '\n  Resolve conflicts, then:\n' +
+                    '    git add <files> && git rebase --continue\n' +
+                    '  Then re-run: xt end\n'
+                ));
+                process.exit(1);
+            }
+            console.log(t.success('  ✓ Rebased onto origin/main'));
+
+            // 6. Push (force-with-lease = safe after rebase)
+            console.log(kleur.dim('  Pushing branch...'));
+            const pushResult = git(['push', 'origin', branch, '--force-with-lease'], cwd);
+            if (!pushResult.ok) {
+                console.error(kleur.red(`\n  ✗ Push failed:\n  ${pushResult.err}\n`));
+                process.exit(1);
+            }
+            console.log(t.success(`  ✓ Pushed ${branch}`));
+
+            // 7. Build PR content
+            const fullLog = git(['log', 'origin/main..HEAD', '--oneline'], cwd).out;
+            const diffStat = git(['diff', 'origin/main', '--stat'], cwd).out;
+            const prTitle = buildPrTitle(issues);
+            const prBody = buildPrBody(issues, fullLog, diffStat, branch);
+
+            // 8. Create PR
+            console.log(kleur.dim('  Creating PR...'));
+            const prArgs = ['pr', 'create', '--title', prTitle, '--body', prBody];
+            if (opts.draft) prArgs.push('--draft');
+
+            const prResult = spawnSync('gh', prArgs, { cwd, encoding: 'utf8', stdio: 'pipe' });
+            if (prResult.status !== 0) {
+                console.error(kleur.red(`\n  ✗ PR creation failed:\n  ${prResult.stderr?.trim()}\n`));
+                process.exit(1);
+            }
+            const prUrl = prResult.stdout.trim();
+            console.log(t.success(`  ✓ PR created: ${prUrl}`));
+
+            // 9. Beads linkage: add PR URL to each closed issue's notes
+            for (const issue of issues) {
+                bd(['update', issue.id, '--notes', `PR: ${prUrl}`], cwd);
+            }
+            if (issues.length > 0) {
+                console.log(t.success(`  ✓ Linked PR to ${issues.length} issue(s)`));
+            }
+
+            // 10. Worktree cleanup
+            if (!opts.keep) {
+                let doRemove = opts.yes;
+                if (!opts.yes) {
+                    const { remove } = await prompts({
+                        type: 'confirm',
+                        name: 'remove',
+                        message: `Remove local worktree at ${cwd}?`,
+                        initial: false,
+                    });
+                    doRemove = remove;
+                }
+
+                if (doRemove) {
+                    // Must run from outside the worktree
+                    try {
+                        const repoRoot = git(['rev-parse', '--show-toplevel'], cwd).out;
+                        const removeResult = spawnSync(
+                            'git', ['worktree', 'remove', cwd, '--force'],
+                            { cwd: repoRoot, encoding: 'utf8', stdio: 'pipe' }
+                        );
+                        if (removeResult.status === 0) {
+                            console.log(t.success('  ✓ Worktree removed'));
+                        } else {
+                            console.log(kleur.yellow('  ⚠ Could not remove worktree — remove manually:'));
+                            console.log(kleur.dim(`    git worktree remove ${cwd} --force`));
+                        }
+                    } catch {
+                        console.log(kleur.yellow('  ⚠ Could not remove worktree automatically'));
+                    }
+                }
+            }
+
+            console.log(t.boldGreen('\n  ✓ Session closed\n'));
+            console.log(kleur.dim(`  PR: ${prUrl}`));
+            console.log(kleur.dim('  Merge: review and merge when CI is green\n'));
+        });
+}

package/src/commands/finish.ts

@@ -0,0 +1,25 @@
+import { Command } from 'commander';
+import kleur from 'kleur';
+import { runXtrmFinish } from '../core/xtrm-finish.js';
+
+export function createFinishCommand(): Command {
+  return new Command('finish')
+    .description('Complete session closure lifecycle (phase1 + merge polling + cleanup)')
+    .option('--poll-interval-ms <ms>', 'Polling interval for PR state checks', (v) => Number(v), 5000)
+    .option('--timeout-ms <ms>', 'Maximum wait time before pending-cleanup', (v) => Number(v), 10 * 60 * 1000)
+    .action(async (opts) => {
+      const result = await runXtrmFinish({
+        cwd: process.cwd(),
+        pollIntervalMs: opts.pollIntervalMs,
+        timeoutMs: opts.timeoutMs,
+      });
+
+      if (result.ok) {
+        console.log(kleur.green(`\n✓ ${result.message}\n`));
+        return;
+      }
+
+      console.error(kleur.red(`\n✗ ${result.message}\n`));
+      process.exitCode = 1;
+    });
+}