xtrm-cli 2.1.4

package/test/hooks.test.ts

@@ -0,0 +1,277 @@
+import { describe, it, expect } from 'vitest';
+import { spawnSync, execSync } from 'node:child_process';
+import { readFileSync, writeFileSync, mkdtempSync, mkdirSync, chmodSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const HOOKS_DIR = path.join(__dirname, '../../hooks');
+
+const CURRENT_BRANCH = (() => {
+  try {
+    return execSync('git branch --show-current', { encoding: 'utf8' }).trim();
+  } catch {
+    return 'main';
+  }
+})();
+
+function runHook(
+  hookFile: string,
+  input: Record<string, unknown>,
+  env: Record<string, string> = {},
+) {
+  return spawnSync('node', [path.join(HOOKS_DIR, hookFile)], {
+    input: JSON.stringify(input),
+    encoding: 'utf8',
+    env: { ...process.env, ...env },
+  });
+}
+
+function parseHookJson(stdout: string) {
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+}
+
+function withFakeBdDir(scriptBody: string) {
+  const tempDir = mkdtempSync(path.join(os.tmpdir(), 'xtrm-fakebd-'));
+  const fakeBdPath = path.join(tempDir, 'bd');
+  writeFileSync(fakeBdPath, scriptBody, { encoding: 'utf8' });
+  chmodSync(fakeBdPath, 0o755);
+  return { tempDir, fakeBdPath };
+}
+
+// ── main-guard.mjs — MAIN_GUARD_PROTECTED_BRANCHES ──────────────────────────
+
+describe('main-guard.mjs — MAIN_GUARD_PROTECTED_BRANCHES', () => {
+  it('blocks Write when current branch is listed in MAIN_GUARD_PROTECTED_BRANCHES', () => {
+    // Set env var to the actual current branch — without this env var the
+    // hook only checks hardcoded main/master, so a feature branch always exits 0.
+    const r = runHook(
+      'main-guard.mjs',
+      { tool_name: 'Write', tool_input: { file_path: '/tmp/x' } },
+      { MAIN_GUARD_PROTECTED_BRANCHES: CURRENT_BRANCH },
+    );
+    expect(r.status).toBe(0);
+    const out = parseHookJson(r.stdout);
+    expect(out?.hookSpecificOutput?.permissionDecision).toBe('deny');
+    expect(out?.systemMessage).toContain(CURRENT_BRANCH);
+  });
+
+  it('allows Write when current branch is NOT in MAIN_GUARD_PROTECTED_BRANCHES', () => {
+    const r = runHook(
+      'main-guard.mjs',
+      { tool_name: 'Write', tool_input: { file_path: '/tmp/x' } },
+      { MAIN_GUARD_PROTECTED_BRANCHES: 'nonexistent-branch-xyz' },
+    );
+    expect(r.status).toBe(0);
+  });
+
+  it('blocks Bash by default on protected branch (default-deny)', () => {
+    const r = runHook(
+      'main-guard.mjs',
+      { tool_name: 'Bash', tool_input: { command: 'cat > file.txt << EOF\nhello\nEOF' } },
+      { MAIN_GUARD_PROTECTED_BRANCHES: CURRENT_BRANCH },
+    );
+    expect(r.status).toBe(0);
+    const out = parseHookJson(r.stdout);
+    expect(out?.hookSpecificOutput?.permissionDecision).toBe('deny');
+    expect(out?.systemMessage).toContain('Bash is restricted');
+  });
+
+  it('allows safe Bash commands on protected branch', () => {
+    const safeCommands = [
+      'git status',
+      'git log --oneline -5',
+      'git diff HEAD',
+      'git checkout -b feature/x',
+      'git switch -c feature/y',
+      'git fetch origin',
+      'git pull',
+      'gh pr list',
+      'bd list',
+    ];
+    for (const command of safeCommands) {
+      const r = runHook(
+        'main-guard.mjs',
+        { tool_name: 'Bash', tool_input: { command } },
+        { MAIN_GUARD_PROTECTED_BRANCHES: CURRENT_BRANCH },
+      );
+      expect(r.status, `expected exit 0 for: ${command}`).toBe(0);
+    }
+  });
+
+  it('blocks mutating checkout forms on protected branch', () => {
+    const blockedCommands = [
+      'git checkout -- README.md',
+      'git checkout HEAD -- README.md',
+      'git switch --detach HEAD',
+    ];
+    for (const command of blockedCommands) {
+      const r = runHook(
+        'main-guard.mjs',
+        { tool_name: 'Bash', tool_input: { command } },
+        { MAIN_GUARD_PROTECTED_BRANCHES: CURRENT_BRANCH },
+      );
+      expect(r.status, `expected structured deny for: ${command}`).toBe(0);
+      const out = parseHookJson(r.stdout);
+      expect(out?.hookSpecificOutput?.permissionDecision).toBe('deny');
+      expect(out?.systemMessage).toContain('Bash is restricted');
+    }
+  });
+
+  it('allows Bash when MAIN_GUARD_ALLOW_BASH=1 is set', () => {
+    const r = runHook(
+      'main-guard.mjs',
+      { tool_name: 'Bash', tool_input: { command: 'npm run build' } },
+      { MAIN_GUARD_PROTECTED_BRANCHES: CURRENT_BRANCH, MAIN_GUARD_ALLOW_BASH: '1' },
+    );
+    expect(r.status).toBe(0);
+  });
+
+  it('blocks git commit in Bash with workflow guidance', () => {
+    const r = runHook(
+      'main-guard.mjs',
+      { tool_name: 'Bash', tool_input: { command: 'git commit -m "oops"' } },
+      { MAIN_GUARD_PROTECTED_BRANCHES: CURRENT_BRANCH },
+    );
+    expect(r.status).toBe(0);
+    const out = parseHookJson(r.stdout);
+    expect(out?.hookSpecificOutput?.permissionDecision).toBe('deny');
+    expect(out?.systemMessage).toContain('feature branch');
+  });
+});
+
+// ── beads-gate-utils.mjs ─────────────────────────────────────────────────────
+
+describe('beads-gate-utils.mjs — module integrity', () => {
+  it('exports all required symbols without crashing', () => {
+    const r = spawnSync('node', ['--input-type=module'], {
+      input: `
+import {
+  resolveCwd, isBeadsProject, getSessionClaim,
+  getTotalWork, getInProgress, clearSessionClaim, withSafeBdContext
+} from '${HOOKS_DIR}/beads-gate-utils.mjs';
+const ok = [resolveCwd, isBeadsProject, getSessionClaim, getTotalWork,
+            getInProgress, clearSessionClaim, withSafeBdContext]
+  .every(fn => typeof fn === 'function');
+process.exit(ok ? 0 : 1);
+`,
+      encoding: 'utf8',
+    });
+    expect(r.status).toBe(0);
+  });
+});
+
+// ── beads-edit-gate.mjs ───────────────────────────────────────────────────────
+
+describe('beads-edit-gate.mjs', () => {
+  it('fails open (exit 0) when no .beads directory exists', () => {
+    const r = runHook('beads-edit-gate.mjs', {
+      session_id: 'test-session',
+      tool_name: 'Write',
+      tool_input: { file_path: '/tmp/x' },
+      cwd: '/tmp',
+    });
+    expect(r.status).toBe(0);
+  });
+
+  it('imports from beads-gate-utils.mjs (no inline duplicate logic)', () => {
+    const content = readFileSync(path.join(HOOKS_DIR, 'beads-edit-gate.mjs'), 'utf8');
+    expect(content).toContain("from './beads-gate-utils.mjs'");
+  });
+
+  it('blocks when session has no claim but open issues exist (regression guard)', () => {
+    const projectDir = mkdtempSync(path.join(os.tmpdir(), 'xtrm-beads-project-'));
+    mkdirSync(path.join(projectDir, '.beads'));
+    const fake = withFakeBdDir(`#!/usr/bin/env bash
+set -euo pipefail
+if [[ "$1" == "kv" && "$2" == "get" ]]; then
+  exit 1
+fi
+if [[ "$1" == "list" ]]; then
+  cat <<'EOF'
+○ issue-1 P2 Open issue
+
+--------------------------------------------------------------------------------
+Total: 1 issues (1 open, 0 in progress)
+EOF
+  exit 0
+fi
+exit 1
+`);
+
+    try {
+      const r = runHook(
+        'beads-edit-gate.mjs',
+        {
+          session_id: 'session-regression-test',
+          tool_name: 'Write',
+          tool_input: { file_path: '/tmp/x' },
+          cwd: projectDir,
+        },
+        { PATH: `${fake.tempDir}:${process.env.PATH ?? ''}` },
+      );
+      expect(r.status).toBe(2);
+      expect(r.stderr).toContain('no active claim');
+    } finally {
+      rmSync(fake.tempDir, { recursive: true, force: true });
+      rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+});
+
+// ── beads-stop-gate.mjs ───────────────────────────────────────────────────────
+
+describe('beads-stop-gate.mjs', () => {
+  it('fails open (exit 0) when no .beads directory exists', () => {
+    const r = runHook('beads-stop-gate.mjs', { session_id: 'test', cwd: '/tmp' });
+    expect(r.status).toBe(0);
+  });
+
+  it('imports from beads-gate-utils.mjs', () => {
+    const content = readFileSync(path.join(HOOKS_DIR, 'beads-stop-gate.mjs'), 'utf8');
+    expect(content).toContain("from './beads-gate-utils.mjs'");
+  });
+});
+
+// ── beads-commit-gate.mjs ─────────────────────────────────────────────────────
+
+describe('beads-commit-gate.mjs', () => {
+  it('fails open (exit 0) when no .beads directory exists', () => {
+    const r = runHook('beads-commit-gate.mjs', {
+      session_id: 'test',
+      tool_name: 'Bash',
+      tool_input: { command: 'git commit -m test' },
+      cwd: '/tmp',
+    });
+    expect(r.status).toBe(0);
+  });
+
+  it('imports from beads-gate-utils.mjs', () => {
+    const content = readFileSync(path.join(HOOKS_DIR, 'beads-commit-gate.mjs'), 'utf8');
+    expect(content).toContain("from './beads-gate-utils.mjs'");
+  });
+});
+
+// ── beads-close-memory-prompt.mjs ────────────────────────────────────────────
+
+describe('beads-close-memory-prompt.mjs', () => {
+  it('exits 0 for non-bd-close bash commands', () => {
+    const r = runHook('beads-close-memory-prompt.mjs', {
+      session_id: 'test',
+      tool_name: 'Bash',
+      tool_input: { command: 'git status' },
+      cwd: '/tmp',
+    });
+    expect(r.status).toBe(0);
+  });
+
+  it('imports from beads-gate-utils.mjs', () => {
+    const content = readFileSync(path.join(HOOKS_DIR, 'beads-close-memory-prompt.mjs'), 'utf8');
+    expect(content).toContain("from './beads-gate-utils.mjs'");
+  });
+});

package/test/install-project.test.ts

@@ -0,0 +1,235 @@
+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 {
+    buildProjectInitGuide,
+    createProjectCommand,
+    deepMergeHooks,
+    extractReadmeDescription,
+    getAvailableProjectSkills,
+    installAllProjectSkills,
+    installProjectSkill,
+} from '../src/commands/install-project.js';
+
+describe('buildProjectInitGuide', () => {
+    it('includes recommended quality-gate skills and required config checks', () => {
+        const guide = buildProjectInitGuide();
+        expect(guide).toContain('ts-quality-gate');
+        expect(guide).toContain('py-quality-gate');
+        expect(guide).toContain('tdd-guard');
+        expect(guide.toLowerCase()).toContain('lint');
+        expect(guide.toLowerCase()).toContain('mypy');
+        expect(guide.toLowerCase()).toContain('service-skills-set');
+    });
+});
+
+describe('createProjectCommand', () => {
+    it('exposes init/list/install subcommands', () => {
+        const cmd = createProjectCommand();
+        const names = cmd.commands.map(c => c.name());
+        expect(names).toEqual(expect.arrayContaining(['init', 'list', 'install']));
+    });
+});
+
+describe('deepMergeHooks', () => {
+    it('appends new hook entries without overwriting existing events', () => {
+        const existing = {
+            hooks: {
+                PreToolUse: [{ command: 'echo existing-pre' }],
+                CustomEvent: [{ command: 'echo keep-me' }],
+            },
+        };
+
+        const incoming = {
+            hooks: {
+                PreToolUse: [{ command: 'echo new-pre' }],
+                PostToolUse: [{ command: 'echo new-post' }],
+            },
+        };
+
+        const merged = deepMergeHooks(existing, incoming);
+
+        expect(merged.hooks.PreToolUse).toEqual([
+            { command: 'echo existing-pre' },
+            { command: 'echo new-pre' },
+        ]);
+        expect(merged.hooks.CustomEvent).toEqual([{ command: 'echo keep-me' }]);
+        expect(merged.hooks.PostToolUse).toEqual([{ command: 'echo new-post' }]);
+    });
+
+    it('upgrades existing same-command matcher to include incoming Serena tools', () => {
+        const existing = {
+            hooks: {
+                PostToolUse: [{
+                    matcher: 'Write|Edit|MultiEdit',
+                    hooks: [{ command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/quality-check.cjs"' }],
+                }],
+            },
+        };
+
+        const incoming = {
+            hooks: {
+                PostToolUse: [{
+                    matcher: 'Write|Edit|MultiEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol',
+                    hooks: [{ command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/quality-check.cjs"' }],
+                }],
+            },
+        };
+
+        const merged = deepMergeHooks(existing, incoming);
+        const matcher = merged.hooks.PostToolUse[0].matcher as string;
+        expect(matcher).toContain('mcp__serena__rename_symbol');
+        expect(matcher).toContain('mcp__serena__replace_symbol_body');
+        expect(matcher).toContain('mcp__serena__insert_after_symbol');
+        expect(matcher).toContain('mcp__serena__insert_before_symbol');
+    });
+});
+
+describe('extractReadmeDescription', () => {
+    it('extracts the first prose line after the title', async () => {
+        const readme = await fsExtra.readFile(
+            path.join(__dirname, '../../project-skills/py-quality-gate/README.md'),
+            'utf8',
+        );
+
+        expect(extractReadmeDescription(readme)).toBe(
+            'Python quality gate for Claude Code. Runs ruff (linting/formatting) and mypy (type checking) automatically on every file edit.',
+        );
+    });
+
+    it('skips badge blocks and finds the first actual description line', async () => {
+        const readme = await fsExtra.readFile(
+            path.join(__dirname, '../../project-skills/tdd-guard/README.md'),
+            'utf8',
+        );
+
+        expect(extractReadmeDescription(readme)).toBe(
+            'Automated Test-Driven Development enforcement for Claude Code.',
+        );
+    });
+});
+
+describe('installProjectSkill', () => {
+    let tmpDir: string;
+
+    beforeEach(async () => {
+        tmpDir = await mkdtemp(path.join(tmpdir(), 'xtrm-project-skill-'));
+        await fsExtra.ensureDir(path.join(tmpDir, '.claude'));
+    });
+
+    afterEach(async () => {
+        await rm(tmpDir, { recursive: true, force: true });
+    });
+
+    it('copies hook assets required by the installed project skill', async () => {
+        await installProjectSkill('ts-quality-gate', tmpDir);
+
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'hooks', 'quality-check.cjs'))).toBe(true);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'hooks', 'hook-config.json'))).toBe(true);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'skills', 'using-ts-quality-gate', 'SKILL.md'))).toBe(true);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'docs', 'ts-quality-gate-readme.md'))).toBe(true);
+    });
+
+    it('merges settings without dropping existing project hooks', async () => {
+        await fsExtra.writeJson(
+            path.join(tmpDir, '.claude', 'settings.json'),
+            {
+                hooks: {
+                    PreToolUse: [{ command: 'echo existing-pre' }],
+                    CustomEvent: [{ command: 'echo keep-me' }],
+                },
+            },
+            { spaces: 2 },
+        );
+
+        await installProjectSkill('tdd-guard', tmpDir);
+
+        const settings = await fsExtra.readJson(path.join(tmpDir, '.claude', 'settings.json'));
+        expect(settings.hooks.PreToolUse).toHaveLength(2);
+        expect(settings.hooks.CustomEvent).toEqual([{ command: 'echo keep-me' }]);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'hooks', 'tdd-guard-pretool-bridge.cjs'))).toBe(true);
+    });
+
+    it('installs Node hook files that execute inside type-module projects', async () => {
+        await fsExtra.writeJson(path.join(tmpDir, 'package.json'), {
+            name: 'esm-target',
+            type: 'module',
+        }, { spaces: 2 });
+
+        await installProjectSkill('ts-quality-gate', tmpDir);
+
+        const tsRun = spawnSync(
+            'node',
+            [path.join(tmpDir, '.claude', 'hooks', 'quality-check.cjs')],
+            {
+                cwd: tmpDir,
+                input: '{"tool_name":"Edit","tool_input":{"file_path":"/tmp/does-not-exist.ts"}}',
+                encoding: 'utf8',
+            },
+        );
+        expect(tsRun.status).toBe(0);
+
+        const settings = await fsExtra.readJson(path.join(tmpDir, '.claude', 'settings.json'));
+        const postToolUseCommand = settings.hooks.PostToolUse[0].hooks[0].command;
+        expect(postToolUseCommand).toContain('quality-check.cjs');
+    });
+
+    it('installs service-skills git hooks when service-skills-set is installed', async () => {
+        await fsExtra.ensureDir(path.join(tmpDir, '.git', 'hooks'));
+        await installProjectSkill('service-skills-set', tmpDir);
+
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.githooks', 'pre-commit'))).toBe(true);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.githooks', 'pre-push'))).toBe(true);
+        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);
+    });
+});
+
+describe('installAllProjectSkills', () => {
+    let tmpDir: string;
+
+    beforeEach(async () => {
+        tmpDir = await mkdtemp(path.join(tmpdir(), 'xtrm-project-skill-all-'));
+        await fsExtra.ensureDir(path.join(tmpDir, '.claude'));
+    });
+
+    afterEach(async () => {
+        await rm(tmpDir, { recursive: true, force: true });
+    });
+
+    it('installs every available project skill with merged hooks and copied assets', async () => {
+        const availableSkills = await getAvailableProjectSkills();
+        expect(availableSkills).toEqual([
+            'py-quality-gate',
+            'service-skills-set',
+            'tdd-guard',
+            'ts-quality-gate',
+        ]);
+
+        await installAllProjectSkills(tmpDir);
+
+        const settings = await fsExtra.readJson(path.join(tmpDir, '.claude', 'settings.json'));
+        expect(settings.hooks.SessionStart).toHaveLength(2);
+        expect(settings.hooks.PreToolUse).toHaveLength(2);
+        expect(settings.hooks.PostToolUse).toHaveLength(3);
+        expect(settings.hooks.UserPromptSubmit).toHaveLength(1);
+
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'hooks', 'quality-check.cjs'))).toBe(true);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'hooks', 'quality-check.py'))).toBe(true);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'git-hooks', 'doc_reminder.py'))).toBe(true);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'service-registry.json'))).toBe(true);
+
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'skills', 'using-tdd-guard', 'SKILL.md'))).toBe(true);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'skills', 'using-ts-quality-gate', 'SKILL.md'))).toBe(true);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'skills', 'using-py-quality-gate', 'SKILL.md'))).toBe(true);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'skills', 'using-service-skills', 'SKILL.md'))).toBe(true);
+
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'docs', 'tdd-guard-readme.md'))).toBe(true);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'docs', 'ts-quality-gate-readme.md'))).toBe(true);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'docs', 'py-quality-gate-readme.md'))).toBe(true);
+        expect(await fsExtra.pathExists(path.join(tmpDir, '.claude', 'docs', 'service-skills-set-readme.md'))).toBe(true);
+    });
+});

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

@@ -0,0 +1,111 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm } from 'node:fs/promises';
+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);
+    });
+});

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,9 @@
+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, '..'))],
+  },
+})