claws-code 0.8.0

package/lib/install.js

@@ -0,0 +1,1018 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+const { spawnSync } = require('child_process');
+
+const { findAllEditorClis, longPathPreflight, dryRunLog, detectPlatformArch } = require('./platform.js');
+const preflight   = require('./preflight.js');
+const { installCommands, installSkills, installRules, installCapabilities } = require('./capabilities.js');
+const { injectShellHook } = require('./shell-hook.js');
+const { writeMcpJson }    = require('./mcp-setup.js');
+const { verify }          = require('./verify.js');
+
+const HOME      = os.homedir();
+const REPO_ROOT = path.resolve(__dirname, '..');
+
+const TOTAL = 8;
+let _stepN = 0;
+
+function _step(label)  { _stepN++; process.stdout.write(`\n\x1b[1m\x1b[34m[${_stepN}/${TOTAL}]\x1b[0m ${label}\n`); }
+function _ok(msg)      { process.stdout.write(`  \x1b[32m✓\x1b[0m ${msg}\n`); }
+function _warn(msg)    { process.stdout.write(`  \x1b[33m!\x1b[0m ${msg}\n`); }
+function _info(msg)    { process.stdout.write(`  \x1b[2m${msg}\x1b[0m\n`); }
+
+const _SLEEP_BUF = new Int32Array(new SharedArrayBuffer(4));
+function _sleepSync(ms) { Atomics.wait(_SLEEP_BUF, 0, 0, ms); }
+
+/**
+ * Check if a process has CLAWS_TERMINAL_CORR_ID in its environment.
+ * Worker children have it set (spawned with it by the extension); the outer
+ * orchestrator running the installer does not. Only kills children.
+ * @param {number} pid
+ * @param {string} platform  os.platform() result
+ * @returns {boolean}
+ */
+function _hasCorrelationId(pid, platform) {
+  try {
+    if (platform === 'darwin') {
+      // ps -E -p <pid> appends environment variables to each process line on macOS
+      const r = spawnSync('ps', ['-E', '-p', String(pid)], { encoding: 'utf8', stdio: 'pipe' });
+      return !!(r.stdout && r.stdout.includes('CLAWS_TERMINAL_CORR_ID'));
+    } else if (platform === 'linux') {
+      // /proc/<pid>/environ is NUL-delimited env for each process
+      const environ = fs.readFileSync(`/proc/${pid}/environ`, 'latin1');
+      return environ.includes('CLAWS_TERMINAL_CORR_ID');
+    }
+  } catch (_) {}
+  return false;
+}
+
+/**
+ * Kill stale worker mcp_server.js and spawn-helper processes from prior sessions.
+ * Safe: only kills processes that (a) reference this project's .claws-bin/mcp_server.js
+ * path AND (b) have CLAWS_TERMINAL_CORR_ID in their environment (= worker children,
+ * not the outer orchestrator running this install). Idempotent — running on a fresh
+ * system with no stale workers is a no-op.
+ * @param {string} projectRoot
+ * @param {boolean} [dryRun]
+ */
+function _cleanStaleWorkerProcesses(projectRoot, dryRun) {
+  const platform = os.platform();
+  const mcpServerPath = path.join(projectRoot, '.claws-bin', 'mcp_server.js');
+  let killedProcs = 0;
+  let clearedPids = 0;
+
+  if (platform === 'darwin' || platform === 'linux') {
+    // ── mcp_server.js processes ─────────────────────────────────────────────
+    const pgrepMcp = spawnSync('pgrep', ['-af', 'mcp_server\\.js'], { encoding: 'utf8', stdio: 'pipe' });
+    if (pgrepMcp.stdout) {
+      for (const line of pgrepMcp.stdout.split('\n')) {
+        if (!line.trim()) continue;
+        // pgrep -af output: "<pid> <command line>"
+        const spaceIdx = line.indexOf(' ');
+        if (spaceIdx === -1) continue;
+        const pid = parseInt(line.slice(0, spaceIdx), 10);
+        const cmdLine = line.slice(spaceIdx + 1);
+        if (!Number.isFinite(pid)) continue;
+        // Must reference this project's mcp_server.js — full path match prevents
+        // collateral kills of other projects' MCP servers
+        if (!cmdLine.includes(mcpServerPath)) continue;
+        // Must be a worker child (CLAWS_TERMINAL_CORR_ID in env) — the outer
+        // orchestrator running this install does NOT have that env var
+        if (!_hasCorrelationId(pid, platform)) continue;
+        if (dryRun) {
+          process.stdout.write(`  [claws-clean] would kill PID ${pid}: ${cmdLine.slice(0, 80)}\n`);
+        } else {
+          process.stdout.write(`  [claws-clean] kill PID ${pid}: ${cmdLine.slice(0, 80)}\n`);
+          spawnSync('kill', ['-TERM', String(pid)], { stdio: 'pipe' });
+          _sleepSync(2000); // 2 s grace before SIGKILL
+          try { process.kill(pid, 0); spawnSync('kill', ['-KILL', String(pid)], { stdio: 'pipe' }); } catch (_) {}
+        }
+        killedProcs++;
+      }
+    }
+
+    // ── spawn-helper processes (Mac/Linux only — Windows uses winpty/conpty) ─
+    const pgrepHelper = spawnSync('pgrep', ['-af', 'spawn-helper'], { encoding: 'utf8', stdio: 'pipe' });
+    if (pgrepHelper.stdout) {
+      for (const line of pgrepHelper.stdout.split('\n')) {
+        if (!line.trim()) continue;
+        const spaceIdx = line.indexOf(' ');
+        if (spaceIdx === -1) continue;
+        const pid = parseInt(line.slice(0, spaceIdx), 10);
+        if (!Number.isFinite(pid)) continue;
+        // Only kill spawn-helpers that are worker children (CORR_ID in env)
+        if (!_hasCorrelationId(pid, platform)) continue;
+        if (dryRun) {
+          process.stdout.write(`  [claws-clean] would kill spawn-helper PID ${pid}\n`);
+        } else {
+          process.stdout.write(`  [claws-clean] kill spawn-helper PID ${pid}\n`);
+          spawnSync('kill', ['-TERM', String(pid)], { stdio: 'pipe' });
+        }
+        killedProcs++;
+      }
+    }
+  } else if (platform === 'win32') {
+    // Windows: PowerShell CIM query — Get-CimInstance Win32_Process filters node.exe
+    // by CommandLine; Stop-Process kills matching PIDs. Skip our own PID to be safe.
+    const ownPid = process.pid;
+    const escapedPath = mcpServerPath.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+    const psScript = [
+      `$myPid = ${ownPid}`,
+      `$mcpPath = '${escapedPath}'`,
+      `Get-CimInstance Win32_Process -Filter "Name='node.exe'" | ForEach-Object {`,
+      `  $proc = $_`,
+      `  if ($proc.CommandLine -and $proc.CommandLine.Contains($mcpPath) -and $proc.ProcessId -ne $myPid) {`,
+      `    Write-Output ("KILL:" + $proc.ProcessId + ":" + $proc.CommandLine.Substring(0, [Math]::Min(80, $proc.CommandLine.Length)))`,
+      `    Stop-Process -Id $proc.ProcessId -Force -ErrorAction SilentlyContinue`,
+      `  }`,
+      `}`,
+    ].join('\n');
+    const psResult = spawnSync('powershell', ['-NoProfile', '-Command', psScript],
+      { encoding: 'utf8', stdio: 'pipe' });
+    if (psResult.stdout) {
+      for (const line of psResult.stdout.split('\n')) {
+        const l = line.trim();
+        if (!l.startsWith('KILL:')) continue;
+        process.stdout.write(`  [claws-clean] killed ${l.slice(5)}\n`);
+        killedProcs++;
+      }
+    }
+  }
+
+  // ── Clear stale .claws/sidecar.pid if the recorded PID is dead ─────────────
+  const sidecarpidPath = path.join(projectRoot, '.claws', 'sidecar.pid');
+  if (fs.existsSync(sidecarpidPath)) {
+    try {
+      const sidecarpid = parseInt(fs.readFileSync(sidecarpidPath, 'utf8').trim(), 10);
+      let alive = false;
+      try { process.kill(sidecarpid, 0); alive = true; } catch (_) {}
+      if (!alive) {
+        if (!dryRun) fs.unlinkSync(sidecarpidPath);
+        process.stdout.write(`  [claws-clean] cleared stale sidecar.pid (PID ${sidecarpid} dead)\n`);
+        clearedPids++;
+      }
+    } catch (_) {}
+  }
+
+  process.stdout.write(`  [claws-clean] killed ${killedProcs} stale processes, cleared ${clearedPids} stale pid files\n`);
+}
+
+/**
+ * Run the 8-phase installer.
+ * @param {object} [opts]
+ * @param {boolean} [opts.dryRun]
+ * @param {boolean} [opts.noHooks]
+ * @param {string|null} [opts.vscodeCli]
+ * @param {boolean} [opts.force]
+ */
+function run(opts = {}) {
+  const { dryRun = false, noHooks = false, vscodeCli: cliOverride = null } = opts;
+  const projectRoot = process.cwd();
+  _stepN = 0;
+
+  _printBanner();
+
+  // ── Pre-install: kill stale worker processes from prior sessions ────────────
+  _cleanStaleWorkerProcesses(projectRoot, dryRun);
+
+  const lpWarn = longPathPreflight(HOME);
+  if (lpWarn) _warn(lpWarn);
+
+  // ── Phase 1: validate env ──────────────────────────────────────────────────
+  _step('Validate environment');
+  const { failures: preflightFailures, warnings: preflightWarnings } =
+    preflight.run(cliOverride ? { vscodeCli: cliOverride } : {});
+  for (const w of preflightWarnings) _warn(w);
+  if (preflightFailures.length > 0) {
+    for (const f of preflightFailures) process.stderr.write(`  \x1b[31m✗\x1b[0m ${f}\n`);
+    process.stderr.write('\nPreflight failed — fix the above before re-running.\n');
+    process.exit(1);
+  }
+  _info(`Prebuild key: ${detectPlatformArch()}`);
+  _ok('Environment OK');
+
+  // ── Phase 2: prepare .claws-bin/ ──────────────────────────────────────────
+  _step('Prepare .claws-bin/');
+  _prepareCLawsBin(projectRoot, dryRun);
+  _ok('.claws-bin/ ready');
+
+  // W7h-24: CLAWS_GLOBAL_MCP=1 → also register claws in ~/.claude/settings.json mcpServers.
+  // Matches install.sh:1150-1163.
+  if (process.env.CLAWS_GLOBAL_MCP === '1') {
+    _registerGlobalMcp(dryRun);
+  }
+
+  // ── Phase 3: install commands + Bug 1 sweep (project-local, matches bash) ──
+  _step('Install commands (Bug 1 sweep)');
+  installCommands(projectRoot, dryRun);
+  _writeInstallCommand(projectRoot, dryRun);
+  _ok('Commands installed');
+
+  // ── Phase 4: install skills + Bug 2 sweep ────────────────────────────────
+  _step('Install skills + rules (Bug 2 sweep)');
+  installSkills(projectRoot, dryRun);
+  installRules(projectRoot, dryRun);
+  _ok('Skills and rules installed (project-local)');
+
+  // W7h-24: CLAWS_GLOBAL_CONFIG=1 → also install commands/skills/rules into ~/.claude/
+  if (process.env.CLAWS_GLOBAL_CONFIG === '1') {
+    _step('Install global capabilities (CLAWS_GLOBAL_CONFIG=1)');
+    installCapabilities(HOME, dryRun);
+    _ok('Global capabilities installed in ~/.claude/');
+  }
+
+  // ── Phase 5: CLAUDE.md injection (after commands so CMDS_LIST is populated) ─
+  _step('Inject CLAUDE.md block');
+  _injectClaudeMd(projectRoot, dryRun);
+  _ok('CLAUDE.md updated');
+
+  // ── Phase 6: hooks registration ───────────────────────────────────────────
+  if (noHooks) {
+    _step('Register lifecycle hooks (--no-hooks: skipped)');
+    _info('Skipping ~/.claude/settings.json hook registration');
+  } else {
+    _step('Register lifecycle hooks');
+    const hooksOk = _injectHooks(projectRoot, dryRun);
+    if (hooksOk) _ok('Hooks registered');
+  }
+
+  // ── Phase 6b: dev-discipline hooks (contributor environments) ─────────────
+  // W7h-31: mirrors install.sh:1301-1332 step 6b.
+  // Install when: (a) CLAWS_INSTALL_DEV_HOOKS=1, OR (b) the project IS the Claws
+  // source tree — detected by checking projectRoot (matches bash's $PROJECT_ROOT check).
+  const isDevTree = fs.existsSync(path.join(projectRoot, 'scripts', 'install.sh')) &&
+                    fs.existsSync(path.join(projectRoot, 'extension', 'src'));
+  if ((process.env.CLAWS_INSTALL_DEV_HOOKS === '1' || isDevTree) && !dryRun) {
+    _installDevHooks(projectRoot);
+  } else if ((process.env.CLAWS_INSTALL_DEV_HOOKS === '1' || isDevTree) && dryRun) {
+    dryRunLog('install dev-hooks (contributor environment detected or CLAWS_INSTALL_DEV_HOOKS=1)');
+  }
+
+  // ── Phase 7: VS Code extension install ───────────────────────────────────
+  _step('Install VS Code extension');
+  const editorClis = cliOverride
+    ? [{ label: 'override', cliPath: cliOverride }]
+    : findAllEditorClis();
+  _installExtension(editorClis, dryRun);
+
+  // ── Phase 8: shell rc-file hook ───────────────────────────────────────────
+  if (noHooks) {
+    _step('Inject shell hook (--no-hooks / CLAWS_NO_GLOBAL_HOOKS=1: skipped)');
+    _info('Skipping shell rc-file hook injection');
+  } else {
+    _step('Inject shell hook');
+    if (dryRun) {
+      dryRunLog('inject claws shell hook into rc file');
+    } else {
+      try {
+        injectShellHook(REPO_ROOT, dryRun);
+        _ok('Shell hook injected');
+      } catch (err) {
+        _warn(`Shell hook injection failed: ${err.message}`);
+      }
+    }
+  }
+
+  // ── Post-install verify ───────────────────────────────────────────────────
+  if (!dryRun) {
+    const failures = verify(projectRoot);
+    if (failures.length > 0) {
+      process.stdout.write('\n');
+      for (const f of failures) _warn(f);
+    }
+  }
+
+  _printSuccess();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+function _prepareCLawsBin(projectRoot, dryRun) {
+  const clawsBin = path.join(projectRoot, '.claws-bin');
+  const hooksDir = path.join(clawsBin, 'hooks');
+
+  const filesToCopy = [
+    { src: path.join(REPO_ROOT, 'mcp_server.js'),                    name: 'mcp_server.js' },
+    { src: path.join(REPO_ROOT, 'scripts', 'stream-events.js'),      name: 'stream-events.js' },
+    { src: path.join(REPO_ROOT, 'scripts', 'monitor-arm-watch.js'),  name: 'monitor-arm-watch.js' },
+    { src: path.join(REPO_ROOT, 'scripts', 'shell-hook.sh'),         name: 'shell-hook.sh' },
+  ];
+
+  if (dryRun) {
+    dryRunLog(`mkdir ${clawsBin}`);
+    dryRunLog(`mkdir ${hooksDir}`);
+    for (const { src, name } of filesToCopy) {
+      dryRunLog(`copy ${src} → .claws-bin/${name}`);
+    }
+    dryRunLog(`write .claws-bin/package.json shim`);
+    dryRunLog(`write .claws-bin/README.md`);
+    if (process.env.CLAWS_SKIP_EXTENSION_COPY !== '1') {
+      _copyExtensionArtifacts(projectRoot, true);
+    }
+    writeMcpJson(projectRoot, dryRun);
+    _updateGitignore(projectRoot, dryRun);
+    _updateVscodeExtensions(projectRoot, dryRun);
+    return;
+  }
+
+  // Guard against reparse-point artifacts from macOS tarballs extracted on Windows.
+  // rmSync clears any symlink/reparse-point that would cause EPERM on mkdir.
+  try {
+    fs.rmSync(clawsBin, { recursive: true, force: true });
+  } catch (_) { /* ignore — dir may not exist or may be partially removable */ }
+
+  try {
+    fs.mkdirSync(clawsBin, { recursive: true });
+    fs.mkdirSync(hooksDir,  { recursive: true });
+  } catch (e) {
+    if (e.code === 'EEXIST') {
+      process.stdout.write('  [warn] .claws-bin/ directory conflict after cleanup — continuing\n');
+    } else {
+      throw e;
+    }
+  }
+
+  for (const { src, name } of filesToCopy) {
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(clawsBin, name));
+    }
+  }
+
+  // Copy scripts/hooks/ into .claws-bin/hooks/ — atomic to avoid partial state
+  // if the process is killed mid-copy (M-09 pattern from atomic-file.mjs).
+  const hooksSrc = path.join(REPO_ROOT, 'scripts', 'hooks');
+  if (fs.existsSync(hooksSrc)) {
+    _copyDirAtomic(hooksSrc, hooksDir);
+  }
+
+  // Copy schemas/ (MCP tool schemas + JSON schemas + type definitions)
+  const schemasSrc = path.join(REPO_ROOT, 'schemas');
+  if (fs.existsSync(schemasSrc)) {
+    fs.cpSync(schemasSrc, path.join(clawsBin, 'schemas'), { recursive: true });
+  }
+
+  // Copy claws-sdk.js (typed publish helpers for worker scripts)
+  const sdkSrc = path.join(REPO_ROOT, 'claws-sdk.js');
+  if (fs.existsSync(sdkSrc)) {
+    fs.copyFileSync(sdkSrc, path.join(clawsBin, 'claws-sdk.js'));
+  }
+
+  // CommonJS shim so Node treats .claws-bin as CJS even in ESM-default workspaces
+  const pkgShim = path.join(clawsBin, 'package.json');
+  if (!fs.existsSync(pkgShim)) {
+    fs.writeFileSync(pkgShim, '{"type":"commonjs"}\n', 'utf8');
+  }
+
+  // README so teammates can see what's in .claws-bin/
+  fs.writeFileSync(path.join(clawsBin, 'README.md'),
+    '# .claws-bin/\n\nProject-local Claws runtime. Auto-generated by the installer — do not edit.\n', 'utf8');
+
+  // Copy extension/ artifacts into .claws-bin/extension/ for visibility (W7h-13).
+  // VS Code loads from ~/.vscode/extensions/; this reference copy lets teammates
+  // confirm the installed version and see the bundle. Matches install.sh:968-983.
+  // Opt out with CLAWS_SKIP_EXTENSION_COPY=1.
+  if (process.env.CLAWS_SKIP_EXTENSION_COPY !== '1') {
+    _copyExtensionArtifacts(projectRoot, dryRun);
+  }
+
+  // Write/update .mcp.json so the MCP server is registered in the project
+  writeMcpJson(projectRoot, dryRun);
+
+  // Add Claws runtime paths to .gitignore (W7h-9)
+  _updateGitignore(projectRoot, dryRun);
+
+  // Add neunaha.claws to .vscode/extensions.json recommendations (W7h-10)
+  _updateVscodeExtensions(projectRoot, dryRun);
+}
+
+/**
+ * Append Claws runtime entries to <projectRoot>/.gitignore if not already present.
+ * Matches install.sh lines 1094-1106.
+ * @param {string} projectRoot
+ * @param {boolean} [dryRun]
+ */
+function _updateGitignore(projectRoot, dryRun) {
+  const gitignore = path.join(projectRoot, '.gitignore');
+  const entries   = ['.claws/', '.mcp.json', '.claws-bin/'];
+
+  if (dryRun) {
+    dryRunLog(`update ${gitignore} with claws entries`);
+    return;
+  }
+
+  let existing = '';
+  if (fs.existsSync(gitignore)) {
+    existing = fs.readFileSync(gitignore, 'utf8');
+  }
+
+  const toAdd = entries.filter(e => !existing.includes(e));
+  if (toAdd.length === 0) return;
+
+  const append  = '\n# Claws runtime artifacts (auto-added by installer)\n' + toAdd.join('\n') + '\n';
+  const tmp     = gitignore + '.claws-tmp.' + process.pid;
+  fs.writeFileSync(tmp, existing + append, 'utf8');
+  fs.renameSync(tmp, gitignore);
+  _ok(`.gitignore updated (${toAdd.join(', ')})`);
+}
+
+/**
+ * Merge neunaha.claws into .vscode/extensions.json workspace recommendations.
+ * Tolerates JSONC comments via inline strip. Matches install.sh lines 1113-1144.
+ * @param {string} projectRoot
+ * @param {boolean} [dryRun]
+ */
+function _updateVscodeExtensions(projectRoot, dryRun) {
+  const vscodeDir = path.join(projectRoot, '.vscode');
+  const extFile   = path.join(vscodeDir, 'extensions.json');
+  const EXT_ID    = 'neunaha.claws';
+
+  if (dryRun) {
+    dryRunLog(`merge ${EXT_ID} into ${extFile}`);
+    return;
+  }
+
+  let config = { recommendations: [] };
+  if (fs.existsSync(extFile)) {
+    try {
+      const raw = fs.readFileSync(extFile, 'utf8');
+      config = JSON.parse(_stripJsonc(raw));
+    } catch {
+      _warn('.vscode/extensions.json is malformed — skipping');
+      return;
+    }
+  }
+
+  if (!Array.isArray(config.recommendations)) config.recommendations = [];
+  if (config.recommendations.includes(EXT_ID)) return;
+
+  config.recommendations.push(EXT_ID);
+  fs.mkdirSync(vscodeDir, { recursive: true });
+  const tmp = extFile + '.claws-tmp.' + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmp, extFile);
+  _ok('.vscode/extensions.json updated');
+}
+
+// Simple JSONC comment stripper — removes line comments, block comments,
+// and trailing commas. Sufficient for .vscode/*.json written by editors.
+function _stripJsonc(text) {
+  return text
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\/\/[^\n]*/g, '')
+    .replace(/,(\s*[}\]])/g, '$1');
+}
+
+/**
+ * Register claws MCP server in ~/.claude/settings.json mcpServers (W7h-24).
+ * Matches install.sh:1150-1163. Idempotent — overwrites existing claws entry.
+ * @param {boolean} [dryRun]
+ */
+function _registerGlobalMcp(dryRun = false) {
+  const settingsPath = path.join(HOME, '.claude', 'settings.json');
+  const mcpServerPath = path.join(REPO_ROOT, 'mcp_server.js');
+
+  if (dryRun) {
+    dryRunLog(`register claws MCP in ${settingsPath} (CLAWS_GLOBAL_MCP=1)`);
+    return;
+  }
+
+  let cfg = {};
+  if (fs.existsSync(settingsPath)) {
+    try { cfg = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch (_) {}
+  }
+  if (!cfg.mcpServers) cfg.mcpServers = {};
+  cfg.mcpServers.claws = { command: 'node', args: [mcpServerPath] };
+
+  fs.mkdirSync(path.join(HOME, '.claude'), { recursive: true });
+  const tmp = settingsPath + '.claws-tmp.' + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmp, settingsPath);
+  _ok('Global MCP registered in ~/.claude/settings.json');
+}
+
+function _injectClaudeMd(projectRoot, dryRun) {
+  const injectProject = path.join(REPO_ROOT, 'scripts', 'inject-claude-md.js');
+  const injectGlobal  = path.join(REPO_ROOT, 'scripts', 'inject-global-claude-md.js');
+
+  // inject-claude-md.js does not support --dry-run; guard the call ourselves.
+  if (dryRun) {
+    dryRunLog(`inject CLAWS:BEGIN block into ${path.join(projectRoot, 'CLAUDE.md')}`);
+  } else if (fs.existsSync(injectProject)) {
+    const r = spawnSync(process.execPath, [injectProject, projectRoot], {
+      cwd: REPO_ROOT, stdio: 'inherit', encoding: 'utf8',
+    });
+    if (r.status !== 0) _warn('inject-claude-md.js failed — CLAUDE.md may be stale');
+  }
+
+  // inject-global-claude-md.js natively supports --dry-run.
+  if (fs.existsSync(injectGlobal)) {
+    const extraArgs = dryRun ? ['--dry-run'] : [];
+    const r = spawnSync(process.execPath, [injectGlobal, ...extraArgs], {
+      cwd: REPO_ROOT, stdio: 'inherit', encoding: 'utf8',
+    });
+    if (r.status !== 0 && !dryRun) _warn('inject-global-claude-md.js failed — ~/.claude/CLAUDE.md may be stale');
+  }
+}
+
+/**
+ * Copy hook scripts from <repo>/scripts/hooks/*.js to a stable global directory
+ * ($HOME/.claude/claws/hooks/) so that hooks registered in ~/.claude/settings.json
+ * survive project moves or deletions (D02 / W7h-2 Option B).
+ * Uses atomic temp+rename per file to avoid partial-copy races.
+ * @param {boolean} [dryRun]
+ * @returns {string} absolute path to the global hooks dir
+ */
+function installGlobalHooks(dryRun = false) {
+  // W7h-30B: return the PARENT of hooks/ (~/.claude/claws), not the hooks/ dir itself.
+  // inject-settings-hooks.js receives this as CLAWS_BIN and does path.join(CLAWS_BIN, 'hooks', script),
+  // so passing the parent produces the correct ~/.claude/claws/hooks/<script>.js path.
+  // Passing hooks/ directly caused ~/.claude/claws/hooks/hooks/<script>.js duplication.
+  const clawsParentDir = path.join(HOME, '.claude', 'claws');
+  const globalHooksDir = path.join(clawsParentDir, 'hooks');
+  const srcHooksDir    = path.join(REPO_ROOT, 'scripts', 'hooks');
+
+  if (dryRun) {
+    dryRunLog(`mkdir ${globalHooksDir}`);
+    if (fs.existsSync(srcHooksDir)) {
+      for (const f of fs.readdirSync(srcHooksDir)) {
+        if (f.endsWith('.js')) dryRunLog(`copy hooks/${f} → ${globalHooksDir}/${f}`);
+      }
+    }
+    return clawsParentDir;
+  }
+
+  fs.mkdirSync(globalHooksDir, { recursive: true });
+
+  if (fs.existsSync(srcHooksDir)) {
+    for (const file of fs.readdirSync(srcHooksDir)) {
+      if (!file.endsWith('.js')) continue;
+      const src = path.join(srcHooksDir, file);
+      const tmp = path.join(globalHooksDir, file + '.claws-tmp.' + process.pid);
+      const dst = path.join(globalHooksDir, file);
+      fs.copyFileSync(src, tmp);
+      fs.renameSync(tmp, dst);
+    }
+  }
+
+  return clawsParentDir;
+}
+
+function _injectHooks(projectRoot, dryRun, opts = {}) {
+  const spawnFn   = opts.spawnFn || spawnSync;
+  const script    = path.join(REPO_ROOT, 'scripts', 'inject-settings-hooks.js');
+  const extraArgs = dryRun ? ['--dry-run', '--update'] : ['--update'];
+
+  if (!fs.existsSync(script)) { _warn('inject-settings-hooks.js not found — hooks skipped'); return false; }
+
+  // D02 / W7h-2: install hook scripts to a stable global location so that
+  // settings.json hook commands survive project moves or deletions.
+  const globalHooksDir = installGlobalHooks(dryRun);
+
+  const r = spawnFn(process.execPath, [script, globalHooksDir, ...extraArgs], {
+    cwd: REPO_ROOT, stdio: 'inherit', encoding: 'utf8',
+  });
+  if (r.status !== 0 && !dryRun) {
+    _warn('inject-settings-hooks.js failed — hooks may not be registered');
+    _warn('Fix: run `node scripts/inject-settings-hooks.js` manually, then verify ~/.claude/settings.json');
+    return false;
+  }
+  return true;
+}
+
+function _installExtension(editorClis, dryRun) {
+  const extDir = path.join(REPO_ROOT, 'extension');
+  const isWin  = process.platform === 'win32';
+  // shell:true on Windows passes the whole command through cmd.exe, which splits on unquoted spaces.
+  // Wrap any path that contains spaces so cmd.exe treats it as one token.
+  const wq = (p) => (isWin && p.includes(' ') ? `"${p}"` : p);
+
+  if (dryRun) {
+    dryRunLog('check electron ABI drift (extension/native/.metadata.json vs installed editor)');
+    dryRunLog('npm install --no-fund --no-audit --loglevel=error  (cwd: extension/)');
+    dryRunLog('npm run build  (cwd: extension/)');
+    dryRunLog('npx @vscode/vsce package --skip-license --no-git-tag-version --no-update-package-json --no-dependencies -o <tmpdir>/claws-code-<version>.vsix');
+    dryRunLog('check VSIX size >= 50 KB');
+    for (const { label, cliPath } of editorClis) {
+      dryRunLog(`${cliPath} --install-extension <tmpdir>/claws-code-<version>.vsix --force  [${label}]`);
+    }
+    return;
+  }
+
+  if (editorClis.length === 0) {
+    _warn('No editor CLI found — extension not installed automatically');
+    _info('Install VS Code/Cursor/Windsurf and add CLI to PATH (or set CLAWS_VSCODE_CLI), then re-run');
+    return;
+  }
+
+  if (!fs.existsSync(extDir)) {
+    _warn('extension/ not found in source — skipping extension install');
+    return;
+  }
+
+  const version  = JSON.parse(fs.readFileSync(path.join(extDir, 'package.json'), 'utf8')).version;
+  const vsixPath = path.join(os.tmpdir(), `claws-code-${version}.vsix`);
+
+  // npm install — must include optionals (node-pty lives in optionalDependencies but is required by bundle-native.mjs)
+  _info('npm install (with node-pty)...');
+  const npmInstall = spawnSync('npm', ['install', '--no-fund', '--no-audit', '--loglevel=error'],
+    { cwd: extDir, stdio: 'inherit', shell: isWin });
+  if (npmInstall.status !== 0) {
+    if (isWin) {
+      _warn('npm install failed — node-pty likely needs C++ build tools');
+      _info('Install: winget install Microsoft.VisualStudio.BuildTools');
+      _info('Then re-run the Claws installer');
+    } else {
+      _warn('npm install failed — extension not installed');
+    }
+    return;
+  }
+
+  // Build extension bundle + native node-pty
+  _info('npm run build...');
+  const npmBuild = spawnSync('npm', ['run', 'build'],
+    { cwd: extDir, stdio: 'inherit', shell: isWin });
+  if (npmBuild.status !== 0) {
+    _warn('Extension build failed — extension not installed');
+    return;
+  }
+
+  // W7h-20: Electron ABI drift detection — warn if built binary targets a
+  // different Electron than the currently installed editor. Matches install.sh:403-454.
+  _checkElectronAbiDrift(extDir);
+
+  // Package VSIX — flags match install.sh canonical set (line 686)
+  _info('vsce package...');
+  spawnSync('npx', ['--yes', '@vscode/vsce', 'package',
+    '--skip-license', '--no-git-tag-version', '--no-update-package-json',
+    '--no-dependencies', '-o', wq(vsixPath)],
+    { cwd: extDir, stdio: 'inherit', shell: isWin });
+  if (!fs.existsSync(vsixPath)) {
+    _warn('VSIX not produced — extension not installed');
+    return;
+  }
+
+  // W7h-21: VSIX size check — <50 KB suggests native binary missing from package.
+  // Matches install.sh:697-703.
+  try {
+    const vsixSize = fs.statSync(vsixPath).size;
+    if (vsixSize < 50 * 1024) {
+      _warn(`VSIX is suspiciously small (${vsixSize} bytes < 50 KB) — native pty.node may be missing`);
+      _info('Run: cd extension && npm run build  to rebuild with native binary');
+    }
+  } catch (_) {}
+
+  // Install extension into each found editor
+  let anySucceeded = false;
+  for (const { label, cliPath } of editorClis) {
+    _info(`installing into ${label}...`);
+    // W7h-26: sudo fallback on failure (Linux/macOS only) — matches install.sh:714-719.
+    let installOk = false;
+    const installR = spawnSync(wq(cliPath), ['--install-extension', wq(vsixPath), '--force'],
+      { stdio: 'inherit', shell: isWin });
+    if (installR.status === 0) {
+      installOk = true;
+    } else if (!isWin) {
+      _info(`  ${label} install failed — retrying with sudo...`);
+      const sudoR = spawnSync('sudo', [cliPath, '--install-extension', vsixPath, '--force'],
+        { stdio: 'inherit' });
+      if (sudoR.status === 0) {
+        _info(`  installed via sudo (extensions dir required elevated permissions)`);
+        installOk = true;
+      }
+    }
+
+    if (!installOk) {
+      _warn(`Extension install failed for ${label} — VSIX at ${vsixPath}`);
+    } else {
+      const listR = spawnSync(wq(cliPath), ['--list-extensions'], { encoding: 'utf8', shell: isWin });
+      if (listR.stdout && listR.stdout.includes('neunaha.claws')) {
+        _ok(`neunaha.claws installed into ${label} (verified)`);
+      } else {
+        _ok(`Extension installed into ${label}`);
+      }
+      anySucceeded = true;
+
+      // W7h-25: Stale extension directory cleanup (matches install.sh:740-760).
+      // Remove neunaha.claws-<old-version> dirs after successful install.
+      _cleanStaleExtensionDirs(label, version);
+    }
+  }
+
+  if (!anySucceeded) {
+    _warn('Extension install failed for all editors');
+  }
+
+  // Clean up VSIX from temp dir — matches install.sh /tmp approach
+  try { fs.unlinkSync(vsixPath); } catch (_) {}
+}
+
+function _writeInstallCommand(projectRoot, dryRun) {
+  const cmdDir = path.join(projectRoot, '.claude', 'commands');
+  const dest   = path.join(cmdDir, 'claws-install.md');
+  const content = [
+    '---',
+    'name: claws-install',
+    'description: Install or update Claws — Terminal Control Bridge for VS Code.',
+    '---',
+    '',
+    '# /claws-install',
+    '',
+    'Install or update Claws in this project:',
+    '',
+    '```bash',
+    'npx claws-code install',
+    '```',
+    '',
+    'After the script completes:',
+    '1. Reload VS Code: Cmd+Shift+P → Developer: Reload Window',
+    '2. Restart Claude Code so the project-local `.mcp.json` is picked up.',
+    '3. Try `/claws-help` or `/claws-status`.',
+    '',
+    'If MCP tools don\'t appear, run `/claws-fix` or `/claws-report`.',
+    '',
+  ].join('\n');
+  if (dryRun) { dryRunLog(`write ${dest}`); return; }
+  fs.mkdirSync(cmdDir, { recursive: true });
+  fs.writeFileSync(dest, content, 'utf8');
+}
+
+/**
+ * Remove stale neunaha.claws-<old-version> dirs from the editor's extensions
+ * directory after a successful install (W7h-25). Matches install.sh:740-760.
+ * Polls up to 1s for the new version dir to appear (VS Code extracts asynchronously).
+ * @param {string} label  - editor label: 'code' | 'code-insiders' | 'cursor' | 'windsurf'
+ * @param {string} version - current version (the one just installed)
+ */
+function _cleanStaleExtensionDirs(label, version) {
+  const extDirMap = {
+    'code':          path.join(HOME, '.vscode',          'extensions'),
+    'code-insiders': path.join(HOME, '.vscode-insiders', 'extensions'),
+    'cursor':        path.join(HOME, '.cursor',          'extensions'),
+    'windsurf':      path.join(HOME, '.windsurf',        'extensions'),
+  };
+  const extDir = extDirMap[label];
+  if (!extDir || !fs.existsSync(extDir)) return;
+
+  const keptDir = path.join(extDir, `neunaha.claws-${version}`);
+  // Poll up to 1s (5x200ms) for VS Code to extract the new VSIX before cleanup.
+  for (let i = 0; i < 5; i++) {
+    if (fs.existsSync(keptDir)) break;
+    _sleepSync(200);
+  }
+
+  if (!fs.existsSync(keptDir)) {
+    _warn(`${label}: new extension dir not yet present — skipping stale cleanup`);
+    _info('(VS Code may still be extracting — stale dirs cleaned on next install)');
+    return;
+  }
+
+  let entries;
+  try { entries = fs.readdirSync(extDir); } catch (_) { return; }
+  for (const entry of entries) {
+    if (!entry.startsWith('neunaha.claws-')) continue;
+    const fullPath = path.join(extDir, entry);
+    if (fullPath === keptDir) continue;
+    if (!fs.statSync(fullPath).isDirectory()) continue;
+    try {
+      fs.rmSync(fullPath, { recursive: true, force: true });
+      _info(`  removed stale install ${entry}`);
+    } catch (_) {
+      // best-effort; ignore EPERM (running extension may hold file locks)
+    }
+  }
+}
+
+/**
+ * Detect Electron ABI drift: compare the last-built Electron version recorded
+ * in extension/native/.metadata.json against the currently installed editor's
+ * Electron version. Warns if they differ (matching install.sh:403-454, W7h-20).
+ * Silently skips when detection is not possible (metadata or editor not found).
+ * @param {string} extDir - absolute path to extension/
+ */
+function _checkElectronAbiDrift(extDir) {
+  const metaPath = path.join(extDir, 'native', '.metadata.json');
+  if (!fs.existsSync(metaPath)) return;
+
+  let lastElec = '';
+  try {
+    lastElec = JSON.parse(fs.readFileSync(metaPath, 'utf8')).electronVersion || '';
+  } catch (_) { return; }
+  if (!lastElec) return;
+
+  const currElec = _detectCurrentElectronVersion();
+  if (!currElec) {
+    _warn('Could not detect the current editor Electron version — skipping ABI drift check');
+    _info('Set CLAWS_ELECTRON_VERSION=<version> to specify it explicitly');
+    return;
+  }
+
+  if (currElec !== lastElec) {
+    _warn(`Electron ABI drift detected: built for ${lastElec}, editor is ${currElec}`);
+    _warn('Run: cd extension && npm run build  to rebuild native pty.node for your editor');
+  }
+}
+
+/**
+ * Detect the current VS Code/Cursor/Windsurf Electron version from the app bundle.
+ * macOS: reads Info.plist CFBundleVersion from the Electron Framework.
+ * Linux: runs the electron binary with --version.
+ * Respects CLAWS_ELECTRON_VERSION env override.
+ * @returns {string|null}
+ */
+function _detectCurrentElectronVersion() {
+  if (process.env.CLAWS_ELECTRON_VERSION) return process.env.CLAWS_ELECTRON_VERSION;
+
+  const platform = process.platform;
+  const term     = process.env.TERM_PROGRAM || '';
+
+  if (platform === 'darwin') {
+    const appOrder = (() => {
+      if (term === 'cursor')   return ['Cursor', 'Visual Studio Code', 'Visual Studio Code - Insiders', 'Windsurf'];
+      if (term === 'windsurf') return ['Windsurf', 'Visual Studio Code', 'Visual Studio Code - Insiders', 'Cursor'];
+      return ['Visual Studio Code', 'Visual Studio Code - Insiders', 'Cursor', 'Windsurf'];
+    })();
+    for (const app of appOrder) {
+      const plist = `/Applications/${app}.app/Contents/Frameworks/Electron Framework.framework/Resources/Info.plist`;
+      if (fs.existsSync(plist)) {
+        const r = spawnSync('plutil', ['-extract', 'CFBundleVersion', 'raw', plist],
+          { encoding: 'utf8', stdio: 'pipe' });
+        if (r.status === 0 && r.stdout && r.stdout.trim()) return r.stdout.trim();
+      }
+    }
+  } else if (platform === 'linux') {
+    const epOrder = (() => {
+      if (term === 'cursor')   return ['/usr/share/cursor/electron', '/opt/cursor/electron', '/usr/share/code/electron', '/usr/share/windsurf/electron'];
+      if (term === 'windsurf') return ['/usr/share/windsurf/electron', '/opt/windsurf/electron', '/usr/share/code/electron', '/usr/share/cursor/electron'];
+      return ['/usr/share/code/electron', '/usr/lib/code/electron', '/usr/share/cursor/electron', '/usr/share/windsurf/electron'];
+    })();
+    for (const ep of epOrder) {
+      if (fs.existsSync(ep)) {
+        const r = spawnSync(ep, ['--version'], { encoding: 'utf8', stdio: 'pipe' });
+        if (r.status === 0 && r.stdout) {
+          const v = r.stdout.trim().replace(/^v/, '').split('\n')[0];
+          if (v) return v;
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Copy extension/ artifacts into .claws-bin/extension/ for visibility (W7h-13).
+ * Copies: dist, native, package.json, package-lock.json, README.md, CHANGELOG.md,
+ * icon.png, .vscodeignore — matches install.sh lines 975-979.
+ * @param {string} projectRoot
+ * @param {boolean} [dryRun]
+ */
+function _copyExtensionArtifacts(projectRoot, dryRun = false) {
+  const srcExtDir  = path.join(REPO_ROOT, 'extension');
+  const destExtDir = path.join(projectRoot, '.claws-bin', 'extension');
+
+  const ENTRIES = [
+    'dist', 'native', 'package.json', 'package-lock.json',
+    'README.md', 'CHANGELOG.md', 'icon.png', '.vscodeignore',
+  ];
+
+  if (dryRun) {
+    for (const entry of ENTRIES) {
+      dryRunLog(`copy extension/${entry} → .claws-bin/extension/${entry}`);
+    }
+    return;
+  }
+
+  if (!fs.existsSync(srcExtDir)) return;
+
+  try {
+    fs.rmSync(destExtDir, { recursive: true, force: true });
+    fs.mkdirSync(destExtDir, { recursive: true });
+  } catch (_) {}
+
+  for (const entry of ENTRIES) {
+    const src = path.join(srcExtDir, entry);
+    if (!fs.existsSync(src)) continue;
+    const dest = path.join(destExtDir, entry);
+    try {
+      fs.cpSync(src, dest, { recursive: true });
+    } catch (_) {}
+  }
+  _ok('extension/ artifacts copied → .claws-bin/extension/');
+}
+
+/**
+ * Copy srcDir to destDir atomically via tmp → rename (M-09 pattern).
+ *   1. Copy srcDir → destDir.claws-tmp.<pid>
+ *   2. Move existing destDir aside → destDir.claws-old.<ts>
+ *   3. Rename tmp → destDir
+ *   4. Remove the moved-aside old dir (best-effort)
+ * If killed before step 3, destDir is left untouched.
+ * @param {string} srcDir
+ * @param {string} destDir
+ */
+function _copyDirAtomic(srcDir, destDir) {
+  const ts  = Date.now();
+  const tmp = destDir + '.claws-tmp.' + process.pid;
+  const old = destDir + '.claws-old.' + ts;
+
+  try {
+    if (fs.existsSync(tmp)) fs.rmSync(tmp, { recursive: true, force: true });
+    _copyDirSync(srcDir, tmp);
+  } catch (err) {
+    try { fs.rmSync(tmp, { recursive: true, force: true }); } catch (_) {}
+    throw err;
+  }
+
+  const destExists = fs.existsSync(destDir);
+  try {
+    if (destExists) fs.renameSync(destDir, old);
+    fs.renameSync(tmp, destDir);
+  } catch (err) {
+    if (destExists) {
+      try {
+        if (!fs.existsSync(destDir)) fs.renameSync(old, destDir);
+      } catch (_) {}
+    }
+    try { fs.rmSync(tmp, { recursive: true, force: true }); } catch (_) {}
+    throw err;
+  }
+
+  if (destExists) {
+    try { fs.rmSync(old, { recursive: true, force: true }); } catch (_) {}
+  }
+}
+
+function _copyDirSync(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) _copyDirSync(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+/**
+ * Install dev-discipline hooks for contributor environments (W7h-31).
+ * Copies scripts/dev-hooks/*.js into <project>/.claws-bin/dev-hooks/ and
+ * runs inject-dev-hooks.js to register them in <project>/.claude/settings.json.
+ * Matches install.sh:1301-1332.
+ * @param {string} projectRoot
+ */
+function _installDevHooks(projectRoot) {
+  const srcDir  = path.join(REPO_ROOT, 'scripts', 'dev-hooks');
+  const destDir = path.join(projectRoot, '.claws-bin', 'dev-hooks');
+  const injectScript = path.join(REPO_ROOT, 'scripts', 'inject-dev-hooks.js');
+
+  if (!fs.existsSync(srcDir)) return;
+
+  fs.mkdirSync(destDir, { recursive: true });
+
+  let count = 0;
+  for (const f of fs.readdirSync(srcDir)) {
+    if (!f.endsWith('.js')) continue;
+    fs.copyFileSync(path.join(srcDir, f), path.join(destDir, f));
+    count++;
+  }
+  _ok(`copied ${count} dev-hook scripts → ${destDir}`);
+
+  if (fs.existsSync(injectScript)) {
+    const r = spawnSync(process.execPath, [injectScript, projectRoot],
+      { cwd: REPO_ROOT, stdio: 'inherit', encoding: 'utf8' });
+    if (r.status !== 0) {
+      _warn('inject-dev-hooks.js failed — dev hooks not registered');
+    }
+  } else {
+    _warn('inject-dev-hooks.js not found — dev hooks not registered');
+  }
+}
+
+function _printBanner() {
+  // On Windows, install.ps1 already printed the ASCII banner before delegating to node.
+  // Node's Unicode box-drawing chars garble in CP437/CP1252 consoles, so skip here.
+  if (process.platform === 'win32') return;
+  const B = '\x1b[38;2;200;90;62m';
+  const R = '\x1b[0m';
+  process.stdout.write('\n');
+  process.stdout.write(`  ${B}╔═══════════════════════════════════════════╗${R}\n`);
+  process.stdout.write(`  ${B}║${R}                                           ${B}║${R}\n`);
+  process.stdout.write(`  ${B}║${R}   \x1b[1mCLAWS\x1b[0m  Terminal Control Bridge         ${B}║${R}\n`);
+  process.stdout.write(`  ${B}║${R}   \x1b[2mProject-local orchestration setup\x1b[0m       ${B}║${R}\n`);
+  process.stdout.write(`  ${B}║${R}                                           ${B}║${R}\n`);
+  process.stdout.write(`  ${B}╚═══════════════════════════════════════════╝${R}\n`);
+  process.stdout.write('\n');
+}
+
+function _printSuccess() {
+  const kbd = process.platform === 'darwin' ? 'Cmd+Shift+P' : 'Ctrl+Shift+P';
+  process.stdout.write('\n  \x1b[32m✓ Claws installed successfully\x1b[0m\n\n');
+  process.stdout.write('  \x1b[1mNext steps:\x1b[0m\n');
+  process.stdout.write(`    Reload VS Code: ${kbd} → Developer: Reload Window\n`);
+  process.stdout.write('    Then: /claws-help\n');
+  process.stdout.write('\n');
+}
+
+module.exports = { run, _injectHooks, installGlobalHooks };