@jaggerxtrm/specialists 3.0.2 → 3.2.1

package/bin/install.js

@@ -1,319 +1,209 @@
 #!/usr/bin/env node
-// Specialists Installer
-// Usage: npx --package=@jaggerxtrm/specialists install
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, writeFileSync, readFileSync, copyFileSync, readdirSync, chmodSync } from 'node:fs';
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-const HOME            = homedir();
-const SPECIALISTS_DIR = join(HOME, '.agents', 'specialists');
-const CLAUDE_DIR      = join(HOME, '.claude');
-const HOOKS_DIR       = join(CLAUDE_DIR, 'hooks');
-const SETTINGS_FILE   = join(CLAUDE_DIR, 'settings.json');
-const HOOK_FILE       = join(HOOKS_DIR, 'specialists-main-guard.mjs');
-const MCP_NAME        = 'specialists';
-const GITHUB_PKG      = '@jaggerxtrm/specialists';
-
-// Bundled specialists dir — resolved relative to this file (bin/../specialists/)
+const CWD = process.cwd();
+const CLAUDE_DIR = join(CWD, '.claude');
+const HOOKS_DIR = join(CLAUDE_DIR, 'hooks');
+const SETTINGS_FILE = join(CLAUDE_DIR, 'settings.json');
+const MCP_FILE = join(CWD, '.mcp.json');
+const BUNDLED_HOOKS_DIR = new URL('../hooks', import.meta.url).pathname;
 const BUNDLED_SPECIALISTS_DIR = new URL('../specialists', import.meta.url).pathname;
-const BUNDLED_HOOKS_DIR       = new URL('../hooks', import.meta.url).pathname;
+const USER_SPECIALISTS_DIR = join(homedir(), '.agents', 'specialists');
 
-// ── ANSI helpers ──────────────────────────────────────────────────────────────
-const dim    = (s) => `\x1b[2m${s}\x1b[0m`;
-const green  = (s) => `\x1b[32m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
 const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
-const bold   = (s) => `\x1b[1m${s}\x1b[0m`;
-const red    = (s) => `\x1b[31m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
 
 function section(label) {
-  const line = '─'.repeat(Math.max(0, 40 - label.length));
+  const line = '─'.repeat(Math.max(0, 44 - label.length));
   console.log(`\n${bold(`── ${label} ${line}`)}`);
 }
 
-function ok(label)   { console.log(`  ${green('✓')} ${label}`); }
+function ok(label) { console.log(`  ${green('✓')} ${label}`); }
 function skip(label) { console.log(`  ${yellow('○')} ${label}`); }
 function info(label) { console.log(`  ${dim(label)}`); }
 function fail(label) { console.log(`  ${red('✗')} ${label}`); }
 
-function isInstalled(cmd) {
-  const r = spawnSync('which', [cmd], { encoding: 'utf8' });
-  return r.status === 0 && r.stdout.trim().length > 0;
+function run(cmd, args, options = {}) {
+  return spawnSync(cmd, args, {
+    encoding: 'utf8',
+    stdio: 'pipe',
+    ...options,
+  });
 }
 
-function npmInstallGlobal(pkg) {
-  const r = spawnSync('npm', ['install', '-g', pkg], { stdio: 'inherit', encoding: 'utf8' });
-  if (r.status !== 0) throw new Error(`npm install -g ${pkg} failed`);
+function commandOk(cmd, args = ['--version']) {
+  const result = run(cmd, args);
+  return result.status === 0 && !result.error;
 }
 
-function installDolt() {
-  if (process.platform === 'darwin') {
-    info('Installing dolt via brew...');
-    const r = spawnSync('brew', ['install', 'dolt'], { stdio: 'inherit', encoding: 'utf8' });
-    r.status === 0 ? ok('dolt installed') : fail('brew install dolt failed — install manually: brew install dolt');
-  } else {
-    info('Installing dolt (requires sudo)...');
-    const r = spawnSync(
-      'sudo', ['bash', '-c', 'curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash'],
-      { stdio: 'inherit', encoding: 'utf8' }
-    );
-    if (r.status === 0) {
-      ok('dolt installed');
-    } else {
-      fail('dolt install failed — install manually:');
-      info("  sudo bash -c 'curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash'");
-    }
+function loadJson(path, fallback) {
+  if (!existsSync(path)) return structuredClone(fallback);
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return structuredClone(fallback);
   }
 }
 
-function registerMCP() {
-  const check = spawnSync('claude', ['mcp', 'get', MCP_NAME], { encoding: 'utf8' });
-  if (check.status === 0) return false;
-
-  npmInstallGlobal(GITHUB_PKG);
-
-  const r = spawnSync('claude', [
-    'mcp', 'add', '--scope', 'user', MCP_NAME, '--', MCP_NAME,
-  ], { stdio: 'inherit', encoding: 'utf8' });
-  if (r.status !== 0) throw new Error('claude mcp add failed');
-  return true;
+function saveJson(path, value) {
+  writeFileSync(path, JSON.stringify(value, null, 2) + '\n', 'utf8');
 }
 
-// ── Hook installation ─────────────────────────────────────────────────────────
-
-
-const HOOK_ENTRY = {
-  matcher: 'Edit|Write|MultiEdit|NotebookEdit|Bash',
-  hooks: [{ type: 'command', command: HOOK_FILE }],
-};
-
-
-const BEADS_EDIT_GATE_FILE   = join(HOOKS_DIR, 'beads-edit-gate.mjs');
-const BEADS_COMMIT_GATE_FILE = join(HOOKS_DIR, 'beads-commit-gate.mjs');
-const BEADS_STOP_GATE_FILE   = join(HOOKS_DIR, 'beads-stop-gate.mjs');
-
-const BEADS_EDIT_GATE_ENTRY = {
-  matcher: 'Edit|Write|MultiEdit|NotebookEdit|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol',
-  hooks: [{ type: 'command', command: BEADS_EDIT_GATE_FILE, timeout: 10000 }],
-};
-const BEADS_COMMIT_GATE_ENTRY = {
-  matcher: 'Bash',
-  hooks: [{ type: 'command', command: BEADS_COMMIT_GATE_FILE, timeout: 10000 }],
-};
-const BEADS_STOP_GATE_ENTRY = {
-  hooks: [{ type: 'command', command: BEADS_STOP_GATE_FILE, timeout: 10000 }],
-};
-const BEADS_CLOSE_MEMORY_PROMPT_FILE  = join(HOOKS_DIR, 'beads-close-memory-prompt.mjs');
-const BEADS_CLOSE_MEMORY_PROMPT_ENTRY = {
-  matcher: 'Bash',
-  hooks: [{ type: 'command', command: BEADS_CLOSE_MEMORY_PROMPT_FILE, timeout: 10000 }],
-};
-const SPECIALISTS_COMPLETE_FILE  = join(HOOKS_DIR, 'specialists-complete.mjs');
-const SPECIALISTS_COMPLETE_ENTRY = {
-  hooks: [{ type: 'command', command: SPECIALISTS_COMPLETE_FILE, timeout: 5000 }],
-};
-
-function promptYN(question) {
-  if (!process.stdin.isTTY) return true; // non-interactive: default yes
-  process.stdout.write(`${question} [Y/n]: `);
-  const r = spawnSync('/bin/sh', ['-c', 'read ans; printf "%s" "$ans"'], {
-    stdio: ['inherit', 'pipe', 'inherit'],
-    encoding: 'utf8',
-  });
-  const ans = (r.stdout ?? '').trim().toLowerCase();
-  return ans === '' || ans === 'y' || ans === 'yes';
+function sameFileContent(a, b) {
+  if (!existsSync(a) || !existsSync(b)) return false;
+  return readFileSync(a, 'utf8') === readFileSync(b, 'utf8');
 }
 
-function getHookDrift() {
-  const pairs = [
-    ['specialists-main-guard.mjs',       HOOK_FILE],
-    ['beads-edit-gate.mjs',              BEADS_EDIT_GATE_FILE],
-    ['beads-commit-gate.mjs',            BEADS_COMMIT_GATE_FILE],
-    ['beads-stop-gate.mjs',              BEADS_STOP_GATE_FILE],
-    ['beads-close-memory-prompt.mjs',    BEADS_CLOSE_MEMORY_PROMPT_FILE],
-    ['specialists-complete.mjs',          SPECIALISTS_COMPLETE_FILE],
-  ];
-  return pairs
-    .map(([bundled, dest]) => ({
-      name: bundled,
-      dest,
-      missing: !existsSync(dest),
-      changed: existsSync(dest) &&
-        readFileSync(join(BUNDLED_HOOKS_DIR, bundled), 'utf8') !==
-        readFileSync(dest, 'utf8'),
-    }))
-    .filter(h => h.missing || h.changed);
+const HOOKS = [
+  {
+    event: 'UserPromptSubmit',
+    file: 'specialists-complete.mjs',
+    timeout: 5000,
+  },
+  {
+    event: 'SessionStart',
+    file: 'specialists-session-start.mjs',
+    timeout: 8000,
+  },
+];
+
+function findHookCommands(settings, event, fileName) {
+  const entries = settings?.hooks?.[event];
+  if (!Array.isArray(entries)) return [];
+  return entries.flatMap((entry) =>
+    (entry.hooks ?? [])
+      .map((hook) => hook.command)
+      .filter((command) => typeof command === 'string' && command.includes(fileName)),
+  );
 }
 
-function installHook() {
-  mkdirSync(HOOKS_DIR, { recursive: true });
-
-  // Copy hook files from bundled hooks/ directory
-  copyFileSync(join(BUNDLED_HOOKS_DIR, 'specialists-main-guard.mjs'), HOOK_FILE);
-  chmodSync(HOOK_FILE, 0o755);
-  copyFileSync(join(BUNDLED_HOOKS_DIR, 'beads-edit-gate.mjs'), BEADS_EDIT_GATE_FILE);
-  chmodSync(BEADS_EDIT_GATE_FILE, 0o755);
-  copyFileSync(join(BUNDLED_HOOKS_DIR, 'beads-commit-gate.mjs'), BEADS_COMMIT_GATE_FILE);
-  chmodSync(BEADS_COMMIT_GATE_FILE, 0o755);
-  copyFileSync(join(BUNDLED_HOOKS_DIR, 'beads-stop-gate.mjs'), BEADS_STOP_GATE_FILE);
-  chmodSync(BEADS_STOP_GATE_FILE, 0o755);
-  copyFileSync(join(BUNDLED_HOOKS_DIR, 'beads-close-memory-prompt.mjs'), BEADS_CLOSE_MEMORY_PROMPT_FILE);
-  chmodSync(BEADS_CLOSE_MEMORY_PROMPT_FILE, 0o755);
-  copyFileSync(join(BUNDLED_HOOKS_DIR, 'specialists-complete.mjs'), SPECIALISTS_COMPLETE_FILE);
-  chmodSync(SPECIALISTS_COMPLETE_FILE, 0o755);
+function ensureHook(settings, hook) {
+  const dest = join(HOOKS_DIR, hook.file);
+  const source = join(BUNDLED_HOOKS_DIR, hook.file);
+  const existingCommands = findHookCommands(settings, hook.event, hook.file);
+  const externalOwner = existingCommands.find((command) => command !== dest);
 
-  let settings = {};
-  if (existsSync(SETTINGS_FILE)) {
-    try { settings = JSON.parse(readFileSync(SETTINGS_FILE, 'utf8')); } catch {}
+  if (externalOwner) {
+    skip(`${hook.file} already managed externally — deferring`);
+    info(`existing command: ${externalOwner}`);
+    return false;
   }
 
-  settings.hooks = settings.hooks ?? {};
-
-  // PreToolUse — replace any existing specialists-managed entries
-  if (!Array.isArray(settings.hooks.PreToolUse)) settings.hooks.PreToolUse = [];
-  settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(e =>
-    !e.hooks?.some(h =>
-      h.command?.includes('specialists-main-guard') ||
-      h.command?.includes('beads-edit-gate') ||
-      h.command?.includes('beads-commit-gate')
-    )
-  );
-  settings.hooks.PreToolUse.push(HOOK_ENTRY);
-  settings.hooks.PreToolUse.push(BEADS_EDIT_GATE_ENTRY);
-  settings.hooks.PreToolUse.push(BEADS_COMMIT_GATE_ENTRY);
-
-  // PostToolUse — replace any existing beads-close-memory-prompt entry
-  if (!Array.isArray(settings.hooks.PostToolUse)) settings.hooks.PostToolUse = [];
-  settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(e =>
-    !e.hooks?.some(h => h.command?.includes('beads-close-memory-prompt'))
-  );
-  settings.hooks.PostToolUse.push(BEADS_CLOSE_MEMORY_PROMPT_ENTRY);
-
-  // Stop — replace any existing beads-stop-gate entry
-  if (!Array.isArray(settings.hooks.Stop)) settings.hooks.Stop = [];
-  settings.hooks.Stop = settings.hooks.Stop.filter(e =>
-    !e.hooks?.some(h => h.command?.includes('beads-stop-gate'))
-  );
-  settings.hooks.Stop.push(BEADS_STOP_GATE_ENTRY);
+  mkdirSync(HOOKS_DIR, { recursive: true });
+  const changed = !sameFileContent(source, dest);
+  if (changed) {
+    copyFileSync(source, dest);
+    chmodSync(dest, 0o755);
+    ok(`${hook.file} installed in .claude/hooks/`);
+  } else {
+    skip(`${hook.file} already up to date`);
+  }
 
-  // UserPromptSubmit — replace any existing specialists-complete entry
-  if (!Array.isArray(settings.hooks.UserPromptSubmit)) settings.hooks.UserPromptSubmit = [];
-  settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(e =>
-    !e.hooks?.some(h => h.command?.includes('specialists-complete'))
+  settings.hooks ??= {};
+  settings.hooks[hook.event] ??= [];
+  settings.hooks[hook.event] = settings.hooks[hook.event].filter(
+    (entry) => !(entry.hooks ?? []).some((h) => h.command === dest),
   );
-  settings.hooks.UserPromptSubmit.push(SPECIALISTS_COMPLETE_ENTRY);
-
-  mkdirSync(CLAUDE_DIR, { recursive: true });
-  writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+  settings.hooks[hook.event].push({
+    hooks: [{ type: 'command', command: dest, timeout: hook.timeout }],
+  });
+  ok(`${hook.file} registered for ${hook.event}`);
+  return true;
 }
 
-// ── Main ──────────────────────────────────────────────────────────────────────
-console.log('\n' + bold('  Specialists — full-stack installer'));
-
-// 1. pi
-section('pi  (coding agent runtime)');
-if (isInstalled('pi')) {
-  skip('pi already installed');
-} else {
-  info('Installing @mariozechner/pi-coding-agent...');
-  npmInstallGlobal('@mariozechner/pi-coding-agent');
-  ok('pi installed');
+function installBundledSpecialists() {
+  if (!existsSync(BUNDLED_SPECIALISTS_DIR)) {
+    skip('bundled specialists dir not found — skipping');
+    return;
+  }
+  mkdirSync(USER_SPECIALISTS_DIR, { recursive: true });
+  const files = readdirSync(BUNDLED_SPECIALISTS_DIR).filter(f => f.endsWith('.specialist.yaml'));
+  for (const file of files) {
+    const source = join(BUNDLED_SPECIALISTS_DIR, file);
+    const dest = join(USER_SPECIALISTS_DIR, file);
+    if (sameFileContent(source, dest)) {
+      skip(`${file} already up to date`);
+    } else {
+      copyFileSync(source, dest);
+      ok(`${file} installed in ~/.agents/specialists/`);
+    }
+  }
 }
 
-// 2. beads
-section('beads  (issue tracker)');
-if (isInstalled('bd')) {
-  skip('bd already installed');
-} else {
-  info('Installing @beads/bd...');
-  npmInstallGlobal('@beads/bd');
-  ok('bd installed');
-}
+function ensureMcpRegistration() {
+  const mcp = loadJson(MCP_FILE, { mcpServers: {} });
+  mcp.mcpServers ??= {};
+  const existing = mcp.mcpServers.specialists;
+  const desired = { command: 'specialists', args: [] };
+
+  if (
+    existing &&
+    existing.command === desired.command &&
+    Array.isArray(existing.args) &&
+    existing.args.length === 0
+  ) {
+    skip('.mcp.json already registers specialists');
+    return;
+  }
 
-// 3. dolt
-section('dolt  (beads sync backend)');
-if (isInstalled('dolt')) {
-  skip('dolt already installed');
-} else {
-  installDolt();
+  mcp.mcpServers.specialists = desired;
+  saveJson(MCP_FILE, mcp);
+  ok('registered specialists in .mcp.json');
 }
 
-// 4. Specialists MCP
-section('Specialists MCP');
-const registered = registerMCP();
-registered
-  ? ok(`MCP '${MCP_NAME}' registered at user scope`)
-  : skip(`MCP '${MCP_NAME}' already registered`);
-
-// 5. Scaffold + copy built-in specialists
-section('Specialists');
-mkdirSync(SPECIALISTS_DIR, { recursive: true });
+console.log(`\n${bold('Specialists installer')}`);
+console.log(dim('Project scope: prerequisite check, bundled specialists, hooks, MCP registration'));
 
-const yamlFiles = existsSync(BUNDLED_SPECIALISTS_DIR)
-  ? readdirSync(BUNDLED_SPECIALISTS_DIR).filter(f => f.endsWith('.specialist.yaml'))
-  : [];
+section('Prerequisite check');
+const prereqs = [
+  { name: 'pi', ok: commandOk('pi', ['--version']), required: true, help: 'Install pi first.' },
+  { name: 'bd', ok: commandOk('bd', ['--version']), required: true, help: 'Install beads (bd) first.' },
+  { name: 'xt', ok: commandOk('xt', ['--version']), required: true, help: 'xtrm-tools is required for hooks and workflow integration.' },
+];
 
-let installed = 0;
-let skipped = 0;
-for (const file of yamlFiles) {
-  const dest = join(SPECIALISTS_DIR, file);
-  if (existsSync(dest)) {
-    skipped++;
+let prereqFailed = false;
+for (const prereq of prereqs) {
+  if (prereq.ok) {
+    ok(`${prereq.name} available`);
   } else {
-    copyFileSync(join(BUNDLED_SPECIALISTS_DIR, file), dest);
-    installed++;
+    prereqFailed = prereqFailed || prereq.required;
+    fail(`${prereq.name} not found`);
+    info(prereq.help);
   }
 }
 
-if (installed > 0) ok(`${installed} specialist(s) installed → ~/.agents/specialists/`);
-if (skipped  > 0) skip(`${skipped} specialist(s) already exist (user-modified, keeping)`);
-if (installed === 0 && skipped === 0) skip('No built-in specialists found');
-info('Edit any .specialist.yaml in ~/.agents/specialists/ to customise models, prompts, permissions');
+if (prereqFailed) {
+  console.log(`\n${red('Install aborted: required prerequisites are missing.')}`);
+  process.exit(1);
+}
 
-// 6. Claude Code hooks
-section('Claude Code hooks');
-const drift = getHookDrift();
-const hooksExist = existsSync(HOOK_FILE);
+section('Specialists hooks');
+mkdirSync(CLAUDE_DIR, { recursive: true });
+const settings = loadJson(SETTINGS_FILE, {});
+for (const hook of HOOKS) ensureHook(settings, hook);
+saveJson(SETTINGS_FILE, settings);
+ok(`updated ${SETTINGS_FILE}`);
 
-if (!hooksExist) {
-  installHook();
-  ok('hooks installed → ~/.claude/hooks/');
-} else if (drift.length === 0) {
-  skip('hooks up to date');
-} else {
-  const label = (h) => h.missing ? red('missing') : yellow('updated');
-  console.log(`  ${yellow('○')} ${drift.length} of 6 hook(s) have changes:`);
-  for (const h of drift) info(`      ${h.name}  ${label(h)}`);
-  console.log();
-  const confirmed = promptYN('  Update hooks?');
-  if (confirmed) {
-    installHook();
-    ok('hooks updated');
-  } else {
-    skip('hooks update skipped');
-  }
-}
-info('main-guard: blocks file edits and direct master pushes (enforces PR workflow)');
-info('beads-edit-gate: requires in_progress bead before editing files');
-info('beads-commit-gate: requires issues closed before git commit');
-info('beads-stop-gate: requires issues closed before session end');
-info('beads-close-memory-prompt: nudges knowledge capture after bd close');
-info('specialists-complete: injects completion banners for background jobs');
+section('Bundled specialists');
+installBundledSpecialists();
 
-// 7. Health check
-section('Health check');
-if (isInstalled('pi')) {
-  const r = spawnSync('pi', ['--list-models'], { encoding: 'utf8' });
-  r.status === 0
-    ? ok('pi has at least one active provider')
-    : skip('No active provider — run pi config to set one up');
-}
+section('MCP registration');
+ensureMcpRegistration();
 
-// 8. Done
-console.log('\n' + bold(green('  Done!')));
-console.log('\n' + bold('  Next steps:'));
-console.log(`  1. ${bold('Configure pi:')} run ${yellow('pi')} then ${yellow('pi config')} to enable model providers`);
-console.log(`  2. ${bold('Restart Claude Code')} to load the MCP and hooks`);
-console.log(`  3. ${bold('Customise specialists:')} edit files in ${yellow('~/.agents/specialists/')}`);
-console.log(`  4. ${bold('Update later:')} re-run this installer (existing specialists preserved)\n`);
+console.log(`\n${bold(green('Done!'))}`);
+console.log(`  ${dim('Hooks are project-local in .claude/, and MCP is project-local in .mcp.json.')}`);