xtrm-cli 2.1.4

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "xtrm-cli",
+  "version": "2.1.4",
+  "description": "Claude Code tools installer (skills, hooks, MCP servers)",
+  "main": "./dist/index.js",
+  "type": "module",
+  "bin": {
+    "xtrm": "./dist/index.cjs"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "start": "node dist/index.cjs"
+  },
+  "dependencies": {
+    "boxen": "^8.0.1",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3",
+    "comment-json": "^4.2.3",
+    "conf": "^12.0.0",
+    "dotenv": "^16.4.5",
+    "fs-extra": "^11.2.0",
+    "kleur": "^4.1.5",
+    "listr2": "^10.1.1",
+    "minimist": "^1.2.8",
+    "ora": "^9.3.0",
+    "project": "^0.1.6",
+    "prompts": "^2.4.2",
+    "tdd-guard": "^1.1.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^25.3.0",
+    "tdd-guard-vitest": "^0.1.6",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/src/adapters/base.ts

@@ -0,0 +1,29 @@
+import type { Skill, MCPServer, Hook, Command } from '../types/models.js';
+
+export interface AdapterCapabilities {
+    skills: boolean;
+    hooks: boolean;
+    mcp: boolean;
+    commands: boolean;
+}
+
+export interface AdapterConfig {
+    tool: string;
+    baseDir: string;
+    displayName: string;
+}
+
+export abstract class ToolAdapter {
+    abstract readonly toolName: string;
+    abstract readonly displayName: string;
+    abstract readonly config: AdapterConfig;
+
+    // Capabilities
+    abstract getCapabilities(): AdapterCapabilities;
+
+    // Paths
+    abstract getConfigDir(): string;
+    abstract getSkillsDir(): string;
+    abstract getHooksDir(): string;
+    abstract getCommandsDir(): string;
+}

package/src/adapters/claude.ts

@@ -0,0 +1,38 @@
+import { join } from 'path';
+import { ToolAdapter, type AdapterCapabilities } from './base.js';
+
+export class ClaudeAdapter extends ToolAdapter {
+    readonly toolName = 'claude-code';
+    readonly displayName = 'Claude Code';
+    readonly config: { tool: string; baseDir: string; displayName: string };
+
+    constructor(baseDir: string) {
+        super();
+        this.config = { tool: this.toolName, baseDir, displayName: this.displayName };
+    }
+
+    getConfigDir(): string {
+        return this.config.baseDir;
+    }
+
+    getSkillsDir(): string {
+        return join(this.config.baseDir, 'skills');
+    }
+
+    getHooksDir(): string {
+        return join(this.config.baseDir, 'hooks');
+    }
+
+    getCommandsDir(): string {
+        return join(this.config.baseDir, 'commands'); // Though Claude doesn't strictly use bare commands like Gemini
+    }
+
+    getCapabilities(): AdapterCapabilities {
+        return {
+            skills: true,
+            hooks: true,
+            mcp: true,
+            commands: false, // Claude uses Skills instead of Slash Commands natively
+        };
+    }
+}

package/src/adapters/registry.ts

@@ -0,0 +1,21 @@
+import { ToolAdapter } from './base.js';
+import { ClaudeAdapter } from './claude.js';
+
+/**
+ * Adapter registry for Claude Code only.
+ * 
+ * ARCHITECTURAL DECISION (v2.0.0): xtrm-tools now supports Claude Code exclusively.
+ * Gemini and Qwen adapters were removed due to fragile, undocumented hook ecosystems.
+ * See PROJECT-SKILLS-ARCHITECTURE.md Section 3.1 for details.
+ */
+
+export function detectAdapter(systemRoot: string): ToolAdapter | null {
+    // Windows compatibility: Normalize backslashes before matching paths
+    const normalized = systemRoot.replace(/\\/g, '/').toLowerCase();
+
+    if (normalized.includes('.claude') || normalized.includes('/claude')) {
+        return new ClaudeAdapter(systemRoot);
+    }
+
+    return null;
+}

package/src/commands/help.ts

@@ -0,0 +1,171 @@
+import { Command } from 'commander';
+import kleur from 'kleur';
+
+import path from 'path';
+import fs from 'fs-extra';
+import { findRepoRoot } from '../utils/repo-root.js';
+declare const __dirname: string;
+
+const HOOK_CATALOG: Array<{ file: string; event: string; desc: string; beads?: true }> = [
+    { file: 'main-guard.mjs',               event: 'PreToolUse',       desc: 'Blocks direct edits on protected branches' },
+    { file: 'skill-suggestion.py',           event: 'UserPromptSubmit', desc: 'Suggests relevant skills based on user prompt' },
+    { file: 'serena-workflow-reminder.py',   event: 'SessionStart',     desc: 'Injects Serena semantic editing workflow reminder' },
+    { file: 'type-safety-enforcement.py',    event: 'PreToolUse',       desc: 'Prevents risky Bash and enforces safe edit patterns' },
+    { file: 'gitnexus/gitnexus-hook.cjs',    event: 'PreToolUse',       desc: 'Adds GitNexus context for Grep/Glob/Bash searches' },
+    { file: 'skill-discovery.py',            event: 'UserPromptSubmit', desc: 'Discovers available skills for user requests' },
+    { file: 'agent_context.py',              event: 'Support module',   desc: 'Shared hook I/O helper used by Python hook scripts' },
+    { file: 'beads-edit-gate.mjs',           event: 'PreToolUse',       desc: 'Blocks file edits if no beads issue is claimed',      beads: true },
+    { file: 'beads-commit-gate.mjs',         event: 'PreToolUse',       desc: 'Blocks commits when no beads issue is in progress',   beads: true },
+    { file: 'beads-stop-gate.mjs',           event: 'Stop',             desc: 'Blocks session stop with an unclosed beads claim',    beads: true },
+    { file: 'beads-close-memory-prompt.mjs', event: 'PostToolUse',      desc: 'Prompts memory save when closing a beads issue',      beads: true },
+];
+
+async function readSkillsFromDir(dir: string): Promise<Array<{ name: string; desc: string }>> {
+    if (!(await fs.pathExists(dir))) return [];
+    const entries = await fs.readdir(dir);
+    const skills: Array<{ name: string; desc: string }> = [];
+    for (const name of entries.sort()) {
+        const skillMd = path.join(dir, name, 'SKILL.md');
+        if (!(await fs.pathExists(skillMd))) continue;
+        const content = await fs.readFile(skillMd, 'utf8');
+        const m = content.match(/^description:\s*(.+)$/m);
+        skills.push({ name, desc: m ? m[1].replace(/^["']|["']$/g, '').trim() : '' });
+    }
+    return skills;
+}
+
+async function readProjectSkillsFromDir(dir: string): Promise<Array<{ name: string; desc: string }>> {
+    if (!(await fs.pathExists(dir))) return [];
+    const entries = await fs.readdir(dir);
+    const skills: Array<{ name: string; desc: string }> = [];
+    for (const name of entries.sort()) {
+        const readme = path.join(dir, name, 'README.md');
+        if (!(await fs.pathExists(readme))) continue;
+        const content = await fs.readFile(readme, 'utf8');
+        const descLine = content.split('\n').find(line => {
+            const trimmed = line.trim();
+            return Boolean(trimmed) && !trimmed.startsWith('#') && !trimmed.startsWith('[') && !trimmed.startsWith('<');
+        }) || '';
+        skills.push({ name, desc: descLine.replace(/[*_`]/g, '').trim() });
+    }
+    return skills;
+}
+
+function resolvePkgRootFallback(): string | null {
+    const candidates = [
+        path.resolve(__dirname, '../..'),
+        path.resolve(__dirname, '../../..'),
+    ];
+    const match = candidates.find(candidate =>
+        fs.existsSync(path.join(candidate, 'skills')) || fs.existsSync(path.join(candidate, 'project-skills'))
+    );
+    return match || null;
+}
+
+function col(s: string, width: number): string {
+    return s.length >= width ? s.slice(0, width - 1) + '\u2026' : s.padEnd(width);
+}
+
+export function createHelpCommand(): Command {
+    return new Command('help')
+        .description('Show help information and component catalogue')
+        .action(async () => {
+            let repoRoot: string;
+            try { repoRoot = await findRepoRoot(); } catch { repoRoot = ''; }
+            const pkgRoot = resolvePkgRootFallback();
+
+            const skillsRoot = repoRoot || pkgRoot || '';
+            const projectSkillsRoot = repoRoot || pkgRoot || '';
+            const skills = skillsRoot ? await readSkillsFromDir(path.join(skillsRoot, 'skills')) : [];
+            const projectSkills = projectSkillsRoot ? await readProjectSkillsFromDir(path.join(projectSkillsRoot, 'project-skills')) : [];
+
+            const W = 80;
+            const hr = kleur.dim('-'.repeat(W));
+            const section = (title: string) => `\n${kleur.bold().cyan(title)}\n${hr}`;
+
+            const installSection = [
+                section('INSTALL COMMANDS'),
+                '',
+                `  ${kleur.bold('xtrm install all')}`,
+                `    ${kleur.dim('Global install: skills + all hooks (including beads gates) + MCP servers.')}`,
+                `    ${kleur.dim('Checks for beads+dolt and prompts to install if missing.')}`,
+                '',
+                `  ${kleur.bold('xtrm install basic')}`,
+                `    ${kleur.dim('Global install: skills + general hooks + MCP servers.')}`,
+                `    ${kleur.dim('No beads dependency -- safe to run with zero external deps.')}`,
+                '',
+                `  ${kleur.bold('xtrm install project')} ${kleur.dim('<tool-name | all>')}`,
+                `    ${kleur.dim('Project-scoped install into .claude/ of current git root.')}`,
+                `    ${kleur.dim('Run xtrm install project list to see available project skills.')}`,
+                '',
+                `  ${kleur.dim('Default target directories:')}`,
+                `    ${kleur.dim('~/.claude/hooks     (global hook scripts)')}`,
+                `    ${kleur.dim('~/.claude/skills    (global Claude skills)')}`,
+                `    ${kleur.dim('~/.agents/skills    (agents skills cache mirror)')}`,
+                '',
+                `  ${kleur.dim('Flags (all profiles): --dry-run  --yes / -y  --no-mcp  --force  --prune  --backport')}`,
+            ].join('\n');
+
+            const general = HOOK_CATALOG.filter(h => !h.beads);
+            const beads   = HOOK_CATALOG.filter(h => h.beads);
+            const hookRows = (hooks: typeof HOOK_CATALOG) =>
+                hooks.map(h =>
+                    `  ${kleur.white(col(h.file, 34))}${kleur.yellow(col(h.event, 20))}${kleur.dim(h.desc)}`
+                ).join('\n');
+
+            const hooksSection = [
+                section('GLOBAL HOOKS'),
+                '',
+                kleur.dim('  ' + col('File', 34) + col('Event', 20) + 'Description'),
+                '',
+                hookRows(general),
+                '',
+                `  ${kleur.dim('beads gate hooks (xtrm install all -- require beads+dolt):')}`,
+                hookRows(beads),
+            ].join('\n');
+
+            const skillRows = skills.map(s => {
+                const desc = s.desc.length > 46 ? s.desc.slice(0, 45) + '\u2026' : s.desc;
+                return `  ${kleur.white(col(s.name, 30))}${kleur.dim(desc)}`;
+            }).join('\n');
+
+            const skillsSection = [
+                section(`SKILLS  ${kleur.dim('(' + skills.length + ' available)')}`),
+                '',
+                skills.length ? skillRows : kleur.dim('  (none found -- run from repo root to see skills)'),
+            ].join('\n');
+
+            const psRows = projectSkills.map(s =>
+                `  ${kleur.white(col(s.name, 30))}${kleur.dim(s.desc)}`
+            ).join('\n');
+
+            const psSection = [
+                section('PROJECT SKILLS + HOOKS'),
+                '',
+                projectSkills.length ? psRows : kleur.dim('  (none found in package)'),
+                '',
+                `  ${kleur.dim('Install: xtrm install project <name>  |  xtrm install project list')}`,
+                `  ${kleur.dim('Each project skill can install .claude/skills plus project hooks/settings.')}`,
+            ].join('\n');
+
+            const otherSection = [
+                section('OTHER COMMANDS'),
+                '',
+                `  ${kleur.bold('xtrm status')}    ${kleur.dim('Show pending changes without applying them')}`,
+                `  ${kleur.bold('xtrm reset')}     ${kleur.dim('Clear saved preferences and start fresh')}`,
+                `  ${kleur.bold('xtrm help')}      ${kleur.dim('Show this overview')}`,
+            ].join('\n');
+
+            const resourcesSection = [
+                section('RESOURCES'),
+                '',
+                `  Repository  https://github.com/Jaggerxtrm/xtrm-tools`,
+                `  Issues      https://github.com/Jaggerxtrm/xtrm-tools/issues`,
+                '',
+                `  ${kleur.dim("Run 'xtrm <command> --help' for command-specific options.")}`,
+                '',
+            ].join('\n');
+
+            console.log([installSection, hooksSection, skillsSection, psSection, otherSection, resourcesSection].join('\n'));
+        });
+}