xtrm-cli 0.5.0

package/test/install-service-skills.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import fsExtra from 'fs-extra';
+import { mergeSettingsHooks, installSkills, installGitHooks } from '../src/commands/install-service-skills.js';
+
+// __dirname in vitest context = cli/test/
+const REPO_ROOT = path.resolve(__dirname, '../..');
+const ACTUAL_SKILLS_SRC = path.join(REPO_ROOT, 'project-skills', 'service-skills-set', '.claude', 'skills');
+const ACTUAL_CLAUDE_SRC = path.join(REPO_ROOT, 'project-skills', 'service-skills-set', '.claude');
+
+describe('mergeSettingsHooks', () => {
+    it('adds all three hooks to empty settings', () => {
+        const { result, added, skipped } = mergeSettingsHooks({});
+        const hooks = result.hooks as Record<string, unknown>;
+        expect(added).toEqual(['SessionStart', 'PreToolUse', 'PostToolUse']);
+        expect(skipped).toEqual([]);
+        expect(hooks).toHaveProperty('SessionStart');
+        expect(hooks).toHaveProperty('PreToolUse');
+        expect(hooks).toHaveProperty('PostToolUse');
+    });
+
+    it('preserves existing keys and skips them', () => {
+        const existing = { hooks: { SessionStart: [{ custom: true }] } };
+        const { result, added, skipped } = mergeSettingsHooks(existing);
+        const hooks = result.hooks as Record<string, unknown>;
+        expect(skipped).toEqual(['SessionStart']);
+        expect(added).toEqual(['PreToolUse', 'PostToolUse']);
+        expect(hooks.SessionStart).toEqual([{ custom: true }]);
+    });
+
+    it('preserves non-hook keys in settings', () => {
+        const existing = { apiKey: 'abc', permissions: { allow: [] } };
+        const { result } = mergeSettingsHooks(existing);
+        expect(result.apiKey).toBe('abc');
+        expect(result.permissions).toEqual({ allow: [] });
+    });
+});
+
+describe('installSkills', () => {
+    let tmpDir: string;
+
+    beforeEach(async () => {
+        tmpDir = await mkdtemp(path.join(tmpdir(), 'jaggers-test-'));
+    });
+
+    afterEach(async () => {
+        await rm(tmpDir, { recursive: true, force: true });
+    });
+
+    it('creates .claude/skills/<skill> directories', async () => {
+        await installSkills(tmpDir, ACTUAL_SKILLS_SRC);
+        for (const skill of ['creating-service-skills', 'using-service-skills', 'updating-service-skills', 'scoping-service-skills']) {
+            const dest = path.join(tmpDir, '.claude', 'skills', skill);
+            expect(await fsExtra.pathExists(dest)).toBe(true);
+        }
+    });
+
+    it('is idempotent (safe to run twice)', async () => {
+        await installSkills(tmpDir, ACTUAL_SKILLS_SRC);
+        await expect(installSkills(tmpDir, ACTUAL_SKILLS_SRC)).resolves.not.toThrow();
+    });
+});
+
+describe('installGitHooks', () => {
+    let tmpDir: string;
+
+    beforeEach(async () => {
+        tmpDir = await mkdtemp(path.join(tmpdir(), 'jaggers-test-'));
+        await fsExtra.mkdirp(path.join(tmpDir, '.git', 'hooks'));
+    });
+
+    afterEach(async () => {
+        await rm(tmpDir, { recursive: true, force: true });
+    });
+
+    it('creates .githooks/pre-commit with doc-reminder snippet', async () => {
+        await installGitHooks(tmpDir, ACTUAL_CLAUDE_SRC);
+        const content = await fsExtra.readFile(path.join(tmpDir, '.githooks', 'pre-commit'), 'utf8');
+        expect(content).toContain('# [jaggers] doc-reminder');
+        expect(content).toContain('.claude/git-hooks/doc_reminder.py');
+    });
+
+    it('creates .githooks/pre-push with skill-staleness snippet', async () => {
+        await installGitHooks(tmpDir, ACTUAL_CLAUDE_SRC);
+        const content = await fsExtra.readFile(path.join(tmpDir, '.githooks', 'pre-push'), 'utf8');
+        expect(content).toContain('# [jaggers] skill-staleness');
+        expect(content).toContain('.claude/git-hooks/skill_staleness.py');
+    });
+
+    it('copies hook scripts into .claude/git-hooks/', async () => {
+        await installGitHooks(tmpDir, ACTUAL_CLAUDE_SRC);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'git-hooks', 'doc_reminder.py'))).toBe(true);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'git-hooks', 'skill_staleness.py'))).toBe(true);
+    });
+
+    it('activates hooks in .git/hooks/', async () => {
+        await installGitHooks(tmpDir, ACTUAL_CLAUDE_SRC);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.git', 'hooks', 'pre-commit'))).toBe(true);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.git', 'hooks', 'pre-push'))).toBe(true);
+    });
+
+    it('is idempotent — does not duplicate snippets on re-run', async () => {
+        await installGitHooks(tmpDir, ACTUAL_CLAUDE_SRC);
+        await installGitHooks(tmpDir, ACTUAL_CLAUDE_SRC);
+        const content = await fsExtra.readFile(path.join(tmpDir, '.githooks', 'pre-commit'), 'utf8');
+        const count = (content.match(/# \[jaggers\] doc-reminder/g) ?? []).length;
+        expect(count).toBe(1);
+    });
+
+    it('chains hooks into configured core.hooksPath when beads owns hooks path', async () => {
+        spawnSync('git', ['init'], { cwd: tmpDir, stdio: 'pipe' });
+        spawnSync('git', ['config', 'core.hooksPath', '.beads/hooks'], { cwd: tmpDir, stdio: 'pipe' });
+
+        await installGitHooks(tmpDir, ACTUAL_CLAUDE_SRC);
+
+        const beadsPreCommit = path.join(tmpDir, '.beads', 'hooks', 'pre-commit');
+        const beadsPrePush = path.join(tmpDir, '.beads', 'hooks', 'pre-push');
+        expect(await fsExtra.pathExists(beadsPreCommit)).toBe(true);
+        expect(await fsExtra.pathExists(beadsPrePush)).toBe(true);
+
+        const preCommitContent = await fsExtra.readFile(beadsPreCommit, 'utf8');
+        const prePushContent = await fsExtra.readFile(beadsPrePush, 'utf8');
+        expect(preCommitContent).toContain('# [jaggers] chain-githooks');
+        expect(prePushContent).toContain('# [jaggers] chain-githooks');
+        expect(preCommitContent).toContain(path.join(tmpDir, '.githooks', 'pre-commit'));
+        expect(prePushContent).toContain(path.join(tmpDir, '.githooks', 'pre-push'));
+    });
+});

package/test/install-surface.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.join(__dirname, '../dist/index.cjs');
+
+function run(args: string[]): { stdout: string; stderr: string; status: number } {
+    const r = spawnSync('node', [CLI_BIN, ...args], {
+        encoding: 'utf8',
+        timeout: 10000,
+        env: { ...process.env },
+    });
+    return { stdout: r.stdout ?? '', stderr: r.stderr ?? '', status: r.status ?? -1 };
+}
+
+describe('install command surface (c1qd, j2jk, 6gpf, a875)', () => {
+
+    it('xtrm install all prints deprecation notice', () => {
+        const r = run(['install', 'all']);
+        expect(r.stdout + r.stderr).toMatch(/deprecated/i);
+    });
+
+    it('xtrm install basic prints deprecation notice', () => {
+        const r = run(['install', 'basic']);
+        expect(r.stdout + r.stderr).toMatch(/deprecated/i);
+    });
+
+    it('xtrm install project exits with unknown command error', () => {
+        const r = run(['install', 'project', 'something']);
+        const combined = r.stdout + r.stderr;
+        expect(combined.toLowerCase()).toMatch(/unknown command|error/);
+    });
+
+    it('xtrm project exits with unknown command error', () => {
+        const r = run(['project', 'init']);
+        const combined = r.stdout + r.stderr;
+        expect(combined.toLowerCase()).toMatch(/unknown command|error/);
+    });
+
+    it('xtrm install --help does not describe all/basic as primary install subcommands', () => {
+        const r = run(['install', '--help']);
+        expect(r.stdout).not.toMatch(/install everything.*beads/i);
+        expect(r.stdout).not.toMatch(/no beads gate/i);
+    });
+
+    it('xtrm install pi shows install help (pi is a target-selector, not a pi-runtime subcommand)', () => {
+        // 'pi' is treated as a target-selector argument by the install command,
+        // not as a pi-runtime management subcommand (that lives under xt pi install)
+        const r = run(['install', 'pi', '--help']);
+        expect(r.stdout).toMatch(/install/i);
+        expect(r.stdout).not.toMatch(/launch.*pi.*session|worktree.*session/i);
+    });
+
+    it('xt pi install is registered under xt pi namespace', () => {
+        const r = run(['pi', 'install', '--help']);
+        expect(r.status).toBe(0);
+        expect(r.stdout).toMatch(/extension|package|install/i);
+    });
+
+    it('xtrm init is registered', () => {
+        const r = run(['init', '--help']);
+        expect(r.status).toBe(0);
+    });
+
+    it('xtrm --help does not mention gemini', () => {
+        const r = run(['--help']);
+        expect(r.stdout).not.toMatch(/gemini/i);
+        expect(r.stdout).not.toMatch(/qwen/i);
+    });
+});

package/test/runtime-subcommands.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.join(__dirname, '../dist/index.cjs');
+
+function run(args: string[]): { stdout: string; stderr: string; status: number } {
+    const r = spawnSync('node', [CLI_BIN, ...args], {
+        encoding: 'utf8',
+        timeout: 10000,
+        env: { ...process.env },
+    });
+    return { stdout: r.stdout ?? '', stderr: r.stderr ?? '', status: r.status ?? -1 };
+}
+
+describe('xt claude runtime subcommands (bjvn)', () => {
+
+    it('xt claude --help lists subcommands', () => {
+        const r = run(['claude', '--help']);
+        expect(r.status).toBe(0);
+        const out = r.stdout;
+        expect(out).toMatch(/install/);
+        expect(out).toMatch(/reload/);
+        expect(out).toMatch(/status/);
+        expect(out).toMatch(/doctor/);
+    });
+
+    it('xt claude install --help exits 0', () => {
+        const r = run(['claude', 'install', '--help']);
+        expect(r.status).toBe(0);
+        expect(r.stdout).toMatch(/install|plugin/i);
+    });
+
+    it('xt claude install --dry-run exits without error', () => {
+        const r = run(['claude', 'install', '--dry-run']);
+        // dry-run may fail if repo root can't be found in test env, but should not crash
+        const combined = r.stdout + r.stderr;
+        expect(combined).not.toMatch(/TypeError|ReferenceError|Cannot read/i);
+    });
+
+    it('xt claude reload --help exits 0', () => {
+        const r = run(['claude', 'reload', '--help']);
+        expect(r.status).toBe(0);
+    });
+
+    it('xt claude status --help exits 0', () => {
+        const r = run(['claude', 'status', '--help']);
+        expect(r.status).toBe(0);
+    });
+
+    it('xt claude doctor --help exits 0', () => {
+        const r = run(['claude', 'doctor', '--help']);
+        expect(r.status).toBe(0);
+    });
+
+    it('xt claude is described as session launcher with worktree', () => {
+        const r = run(['claude', '--help']);
+        expect(r.status).toBe(0);
+        expect(r.stdout).toMatch(/session|worktree/i);
+    });
+});
+
+describe('xt pi runtime subcommands (bjvn)', () => {
+
+    it('xt pi --help lists subcommands', () => {
+        const r = run(['pi', '--help']);
+        expect(r.status).toBe(0);
+        const out = r.stdout;
+        expect(out).toMatch(/install/);
+        expect(out).toMatch(/setup/);
+        expect(out).toMatch(/status/);
+        expect(out).toMatch(/doctor/);
+        expect(out).toMatch(/reload/);
+    });
+
+    it('xt pi install --help exits 0', () => {
+        const r = run(['pi', 'install', '--help']);
+        expect(r.status).toBe(0);
+        expect(r.stdout).toMatch(/install|extension|package/i);
+    });
+
+    it('xt pi setup --help exits 0', () => {
+        const r = run(['pi', 'setup', '--help']);
+        expect(r.status).toBe(0);
+        expect(r.stdout).toMatch(/setup|api|key|interactive/i);
+    });
+
+    it('xt pi status --help exits 0', () => {
+        const r = run(['pi', 'status', '--help']);
+        expect(r.status).toBe(0);
+    });
+
+    it('xt pi doctor --help exits 0', () => {
+        const r = run(['pi', 'doctor', '--help']);
+        expect(r.status).toBe(0);
+    });
+
+    it('xt pi reload --help exits 0', () => {
+        const r = run(['pi', 'reload', '--help']);
+        expect(r.status).toBe(0);
+    });
+
+    it('xt pi is described as session launcher with worktree', () => {
+        const r = run(['pi', '--help']);
+        expect(r.status).toBe(0);
+        expect(r.stdout).toMatch(/session|worktree/i);
+    });
+
+    it('xt pi install is under the pi namespace (not xtrm install)', () => {
+        // xt install treats "pi" as a target-selector (not a pi runtime subcommand)
+        // The install command help should NOT mention pi runtime management
+        const r = run(['install', 'pi', '--help']);
+        expect(r.stdout).not.toMatch(/launch.*pi.*session|worktree.*session/i);
+        // xt pi install --help IS the pi runtime install
+        const r2 = run(['pi', 'install', '--help']);
+        expect(r2.status).toBe(0);
+        expect(r2.stdout).toMatch(/extension|package|install/i);
+    });
+});

package/test/session-launcher.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.join(__dirname, '../dist/index.cjs');
+
+function run(args: string[], opts: { cwd?: string; env?: NodeJS.ProcessEnv } = {}): { stdout: string; stderr: string; status: number } {
+    const r = spawnSync('node', [CLI_BIN, ...args], {
+        encoding: 'utf8',
+        timeout: 15000,
+        cwd: opts.cwd,
+        env: { ...process.env, ...opts.env },
+    });
+    return { stdout: r.stdout ?? '', stderr: r.stderr ?? '', status: r.status ?? -1 };
+}
+
+function git(args: string[], cwd: string): void {
+    const r = spawnSync('git', args, { cwd, encoding: 'utf8', stdio: 'pipe' });
+    if (r.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${r.stderr}`);
+}
+
+function removeWorktree(wtPath: string, repoDir: string): void {
+    spawnSync('git', ['worktree', 'remove', wtPath, '--force'], { cwd: repoDir, stdio: 'pipe' });
+    try { fs.rmSync(wtPath, { recursive: true, force: true }); } catch { /* ignore */ }
+}
+
+let siblingBase: string;
+let repoDir: string;
+
+beforeAll(() => {
+    siblingBase = fs.mkdtempSync(path.join(os.tmpdir(), 'xtrm-parent-'));
+    repoDir = path.join(siblingBase, 'myproject');
+    fs.mkdirSync(repoDir);
+    git(['init'], repoDir);
+    git(['config', 'user.email', 'test@test.com'], repoDir);
+    git(['config', 'user.name', 'Test'], repoDir);
+    fs.writeFileSync(path.join(repoDir, 'README.md'), '# test');
+    git(['add', '.'], repoDir);
+    git(['commit', '-m', 'init'], repoDir);
+});
+
+afterAll(() => {
+    try { fs.rmSync(siblingBase, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+describe('session launcher CLI surface (2q8j)', () => {
+
+    it('xt claude --help shows [name] as optional argument', () => {
+        const r = run(['claude', '--help']);
+        expect(r.status).toBe(0);
+        expect(r.stdout).toMatch(/\[name\]/);
+    });
+
+    it('xt pi --help shows [name] as optional argument', () => {
+        const r = run(['pi', '--help']);
+        expect(r.status).toBe(0);
+        expect(r.stdout).toMatch(/\[name\]/);
+    });
+
+    it('xt claude fails gracefully if claude binary not found', () => {
+        const r = run(['claude'], {
+            cwd: repoDir,
+            env: { PATH: '/usr/bin:/bin' },
+        });
+        const combined = r.stdout + r.stderr;
+        expect(combined).not.toMatch(/TypeError|ReferenceError|Cannot read properties/i);
+    });
+
+    it('xt pi fails gracefully if pi binary not found', () => {
+        const r = run(['pi'], {
+            cwd: repoDir,
+            env: { PATH: '/usr/bin:/bin' },
+        });
+        const combined = r.stdout + r.stderr;
+        expect(combined).not.toMatch(/TypeError|ReferenceError|Cannot read properties/i);
+    });
+});
+
+describe('worktree creation naming convention (2q8j)', () => {
+
+    it('creates worktree with xt/<name> branch when name is provided', () => {
+        const today = new Date();
+        const dateStr = `${today.getFullYear()}${String(today.getMonth() + 1).padStart(2, '0')}${String(today.getDate()).padStart(2, '0')}`;
+        const expectedName = `myproject-xt-claude-${dateStr}`;
+        const expectedPath = path.join(siblingBase, expectedName);
+
+        // Pre-clean any stale worktree from previous runs
+        if (fs.existsSync(expectedPath)) {
+            removeWorktree(expectedPath, repoDir);
+        }
+
+        run(['claude', 'mysession'], {
+            cwd: repoDir,
+            env: { PATH: '/usr/bin:/bin' },
+        });
+
+        if (fs.existsSync(expectedPath)) {
+            const branchResult = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+                cwd: expectedPath, encoding: 'utf8', stdio: 'pipe',
+            });
+            expect(branchResult.stdout.trim()).toBe('xt/mysession');
+
+            // Verify it's a sibling of repoDir, not nested inside it
+            // Use repoDir + sep to avoid "myproject-xt-..." startsWith "myproject"
+            expect(expectedPath.startsWith(repoDir + path.sep)).toBe(false);
+            expect(path.dirname(expectedPath)).toBe(siblingBase);
+
+            removeWorktree(expectedPath, repoDir);
+        }
+    });
+
+    it('creates worktree with random xt/<slug> branch when no name provided', () => {
+        const today = new Date();
+        const dateStr = `${today.getFullYear()}${String(today.getMonth() + 1).padStart(2, '0')}${String(today.getDate()).padStart(2, '0')}`;
+        const expectedName = `myproject-xt-pi-${dateStr}`;
+        const expectedPath = path.join(siblingBase, expectedName);
+
+        if (fs.existsSync(expectedPath)) {
+            removeWorktree(expectedPath, repoDir);
+        }
+
+        run(['pi'], {
+            cwd: repoDir,
+            env: { PATH: '/usr/bin:/bin' },
+        });
+
+        if (fs.existsSync(expectedPath)) {
+            const branchResult = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+                cwd: expectedPath, encoding: 'utf8', stdio: 'pipe',
+            });
+            expect(branchResult.stdout.trim()).toMatch(/^xt\/[a-z0-9]{4}$/);
+            removeWorktree(expectedPath, repoDir);
+        }
+    });
+});

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "declaration": true,
+        "sourceMap": true
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist",
+        "test"
+    ]
+}

package/tsup.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+    entry: ['src/index.ts'],
+    format: ['cjs'],
+    target: 'node18',
+    clean: true,
+    dts: true,
+    sourcemap: true,
+    outDir: 'dist',
+    banner: { js: '#!/usr/bin/env node' },
+    // Bundle ALL dependencies inline so dist/index.cjs is self-contained.
+    // Required for npx-from-git to work (cli/node_modules won't exist).
+    noExternal: [/.*/],
+    splitting: false,
+});
+

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config'
+import { VitestReporter } from 'tdd-guard-vitest'
+import path from 'path'
+
+export default defineConfig({
+  test: {
+    reporters: ['default', new VitestReporter(path.resolve(__dirname, '..'))],
+    testTimeout: 30000,
+  },
+})