@ghl-ai/aw 0.1.44 → 0.1.46

package/integrations.mjs

@@ -0,0 +1,954 @@
+// integrations.mjs — Registry, manifest, and installation for third-party integrations.
+// Handles four types:
+//   - plugin      (claude plugin install)
+//   - remote-mcp  (add to mcp.json / config.toml)
+//   - universal-installer (runs the integration's cross-IDE installer)
+//   - python-cli  (pip-install a Python CLI tool, then run its setup commands)
+
+import { promisify } from 'node:util';
+import { exec } from 'node:child_process';
+import { execSync } from 'node:child_process';
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  rmSync,
+} from 'node:fs';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+import * as fmt from './fmt.mjs';
+import { chalk } from './fmt.mjs';
+
+const execAsync = promisify(exec);
+const HOME = homedir();
+const MANIFEST_PATH = join(HOME, '.aw_registry', '.integration-manifest.json');
+
+// ────────────────────────────────────────────────────────────────────────────────
+// INTEGRATION REGISTRY
+// ────────────────────────────────────────────────────────────────────────────────
+
+export const INTEGRATIONS = {
+  // PLUGINS (installed via: claude plugin install)
+  'codex': {
+    type: 'plugin',
+    label: 'OpenAI Codex',
+    installCmd: 'codex@openai-codex',
+    marketplaceSource: 'openai/codex-plugin-cc',
+    description: '/codex:review, /codex:adversarial-review, /codex:rescue — delegate tasks or get code reviews from Codex',
+    teams: [],  // universal
+    requiresAuth: true,
+    authNote: 'Run /codex:setup to verify Codex is ready. If not logged in yet, run: !codex login',
+  },
+
+  'lean-ctx': {
+    type: 'universal-installer',
+    label: 'LeanCTX',
+    description: 'Context OS for AI — compresses file reads + shell output + memory (60-99% fewer input tokens)',
+    scripts: {
+      win32: null,         // no PS1 — uses npm fallback (lean-ctx-bin)
+      posix: 'https://leanctx.com/install.sh',
+    },
+    npmPackage: 'lean-ctx-bin',  // Windows fallback via npm
+    postInstall: ['lean-ctx setup'],  // auto-detects + configures all IDEs in one shot
+    teams: [],  // universal
+    requiresAuth: false,
+    authNote: 'Restart your IDE after install — lean-ctx setup auto-configures Claude Code, Cursor, Codex, Gemini, and more',
+  },
+
+  rtk: {
+    type: 'universal-installer',
+    label: 'RTK (Rust Token Killer)',
+    description: 'CLI proxy that filters/compresses shell output (git, tests, logs) by 60-90%',
+    scripts: {
+      win32: null, // use WSL fallback
+      posix: 'https://raw.githubusercontent.com/rtk-ai/rtk/main/install.sh',
+    },
+    postInstall: [
+      'rtk init -g',                  // Claude Code
+      'rtk init -g --gemini',         // Gemini CLI
+      'rtk init -g --codex',          // Codex
+      'rtk init -g --agent cursor',   // Cursor
+    ],
+    teams: [], // universal — every team benefits
+    requiresAuth: false,
+    authNote: 'Restart Claude Code after install for the auto-rewrite hook to take effect',
+  },
+
+  caveman: {
+    type: 'plugin',
+    label: 'Caveman',
+    installCmd: 'caveman@caveman',
+    marketplaceSource: 'JuliusBrussee/caveman',
+    description: 'Token-efficient responses — ~75% fewer output tokens (lite / full / ultra / wenyan modes)',
+    teams: [],  // universal — every team benefits
+    requiresAuth: false,
+    authNote: 'Activate with /caveman in any session (lite / full / ultra modes)',
+  },
+
+  skills: {
+    type: 'universal-installer',
+    label: 'Agent Skills (Matt Pocock)',
+    description: 'Slash commands for real engineering: /tdd, /diagnose, /grill-me, /grill-with-docs, /triage, /to-prd, /zoom-out',
+    scripts: {
+      win32: null,
+      posix: null,  // no binary — installed entirely via npx below
+    },
+    postInstall: [
+      'npx skills@latest add mattpocock/skills',
+    ],
+    teams: [],
+    requiresAuth: false,
+    authNote: 'Interactive install — pick which skills + agents you want. Then run /setup-matt-pocock-skills once per repo.',
+  },
+
+  // PYTHON CLIs (installed via uv / pipx / pip, then runs post-install hooks)
+  graphify: {
+    type: 'python-cli',
+    label: 'Graphify (Knowledge Graph)',
+    description: 'Builds a queryable knowledge graph of your codebase + docs',
+    pipPackage: 'graphifyy',
+    cliCommand: 'graphify',
+    minPython: { major: 3, minor: 10 },
+    postInstall: [
+      ['install'],            // global: registers the /graphify skill in ~/.claude/skills/
+    ],
+    perProjectInstall: [
+      // IDE wiring — only runs if that IDE's config dir exists on this machine.
+      // Each command writes the IDE-specific CLAUDE.md/AGENTS.md section + hook.
+      { args: ['claude',  'install'], requiresGit: false, requiresIde: '.claude' },
+      { args: ['codex',   'install'], requiresGit: false, requiresIde: '.codex'  },
+      { args: ['cursor',  'install'], requiresGit: false, requiresIde: '.cursor' },
+      { args: ['gemini',  'install'], requiresGit: false, requiresIde: '.gemini' },
+      // Git hooks — post-commit AST rebuild + post-checkout sync + merge driver
+      { args: ['hook',    'install'], requiresGit: true },
+      // If a graph already exists, register it into the global graph immediately.
+      // appendCwdBasename appends the project folder name as the --as tag.
+      { args: ['global', 'add', 'graphify-out/graph.json', '--as'], appendCwdBasename: true, requiresFile: 'graphify-out/graph.json' },
+    ],
+    teams: [],                // universal — every team benefits from a knowledge graph
+    requiresAuth: false,
+    authNote: 'run /graphify . inside your IDE to build the graph whenever you need it',
+  },
+};
+
+// ────────────────────────────────────────────────────────────────────────────────
+// BUNDLES (preset groups for common use cases)
+// ────────────────────────────────────────────────────────────────────────────────
+
+export const BUNDLES = {};
+
+// ────────────────────────────────────────────────────────────────────────────────
+// MANIFEST MANAGEMENT
+// ────────────────────────────────────────────────────────────────────────────────
+
+export function readManifest() {
+  if (!existsSync(MANIFEST_PATH)) {
+    return { version: 1, installed: {} };
+  }
+
+  try {
+    return JSON.parse(readFileSync(MANIFEST_PATH, 'utf8'));
+  } catch {
+    return { version: 1, installed: {} };
+  }
+}
+
+export function writeManifest(manifest) {
+  mkdirSync(join(HOME, '.aw_registry'), { recursive: true });
+  writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n');
+}
+
+export function isInstalled(key) {
+  const manifest = readManifest();
+  const entry = manifest.installed[key];
+  if (!entry) return false;
+  // Backward compat: pre-existing entries have no `status` field — treat as installed.
+  // Skipped entries (e.g. python-cli skipped because Python missing) return false so
+  // autoInstallIntegrations retries them on the next `aw init` run.
+  return entry.status !== 'skipped';
+}
+
+function recordInstalled(key, type) {
+  const manifest = readManifest();
+  manifest.installed[key] = {
+    type,
+    status: 'installed',
+    installedAt: new Date().toISOString(),
+  };
+  writeManifest(manifest);
+}
+
+function recordSkipped(key, type, reason) {
+  const manifest = readManifest();
+  manifest.installed[key] = {
+    type,
+    status: 'skipped',
+    reason,
+    installedAt: new Date().toISOString(),
+  };
+  writeManifest(manifest);
+}
+
+// ────────────────────────────────────────────────────────────────────────────────
+// JSON MCP CONFIG MERGE (Claude & Cursor)
+// ────────────────────────────────────────────────────────────────────────────────
+
+function addToJsonMcp(filePath, serverName, config) {
+  mkdirSync(join(filePath, '..'), { recursive: true });
+
+  let existing = {};
+  if (existsSync(filePath)) {
+    try {
+      existing = JSON.parse(readFileSync(filePath, 'utf8'));
+    } catch {
+      // Corrupted file, start fresh
+    }
+  }
+
+  existing.mcpServers = existing.mcpServers || {};
+  existing.mcpServers[serverName] = config;
+
+  writeFileSync(filePath, JSON.stringify(existing, null, 2) + '\n');
+}
+
+// ────────────────────────────────────────────────────────────────────────────────
+// TOML MCP CONFIG MERGE (Codex)
+// ────────────────────────────────────────────────────────────────────────────────
+
+function addToTomlMcp(filePath, serverName, url) {
+  mkdirSync(join(filePath, '..'), { recursive: true });
+
+  let content = '';
+  if (existsSync(filePath)) {
+    content = readFileSync(filePath, 'utf8');
+  }
+
+  // Remove any existing block for this server (idempotent)
+  const blockRegex = new RegExp(`\\[mcp_servers\\.${serverName}\\][^\\[]*`, 'g');
+  content = content.replace(blockRegex, '');
+
+  // Append new block
+  const newBlock = `[mcp_servers.${serverName}]\nurl = "${url}"\nstartup_timeout_sec = 30\n\n`;
+  content = content + newBlock;
+
+  writeFileSync(filePath, content);
+}
+
+// ────────────────────────────────────────────────────────────────────────────────
+// PYTHON CLI INSTALLER (pip / pipx / uv tool, cross-platform)
+// ────────────────────────────────────────────────────────────────────────────────
+
+const IS_WINDOWS = process.platform === 'win32';
+const WHICH_CMD = IS_WINDOWS ? 'where' : 'which';
+
+// Try interpreters in order; return the first that meets minPython, or null.
+async function detectPython({ major, minor }) {
+  const candidates = IS_WINDOWS
+    ? ['py -3', 'python', 'python3']
+    : ['python3', 'python'];
+
+  for (const cmd of candidates) {
+    try {
+      const { stdout } = await execAsync(`${cmd} --version`, { timeout: 10000 });
+      const m = stdout.match(/Python (\d+)\.(\d+)/);
+      if (!m) continue;
+      const [maj, min] = [parseInt(m[1], 10), parseInt(m[2], 10)];
+      if (maj > major || (maj === major && min >= minor)) {
+        return { cmd, version: `${maj}.${min}` };
+      }
+    } catch {
+      // Interpreter not present on PATH; try next.
+    }
+  }
+  return null;
+}
+
+// Pick the best available Python package installer. Prefers tools that manage PATH.
+async function pickPythonInstaller(pythonCmd) {
+  for (const tool of ['uv', 'pipx']) {
+    try {
+      await execAsync(`${WHICH_CMD} ${tool}`, { timeout: 5000 });
+      if (tool === 'uv')   return { name: 'uv',   build: pkg => `uv tool install "${pkg}"` };
+      if (tool === 'pipx') return { name: 'pipx', build: pkg => `pipx install "${pkg}"` };
+    } catch {
+      // Not on PATH; try next.
+    }
+  }
+  // Fall back to user-site pip. Note: bin dir may not be on PATH after install
+  // — we work around that by falling back to `python -m <module>` when needed.
+  return { name: 'pip', build: pkg => `${pythonCmd} -m pip install --user "${pkg}"` };
+}
+
+// Write a global SessionStart hook to ~/.claude/settings.json that registers the
+// current project's graph into ~/.graphify/global-graph.json every time Claude Code
+// opens in a project that has a built graph. Fast (JSON merge only, no LLM).
+// Written globally so one hook covers all projects — guarded by graph.json existence.
+export function installGraphifyGlobalAddHook(homeDir) {
+  const claudeDir = join(homeDir, '.claude');
+  if (!existsSync(claudeDir)) return;
+
+  const settingsPath = join(claudeDir, 'settings.json');
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try { settings = JSON.parse(readFileSync(settingsPath, 'utf8')); } catch { /* corrupt — start fresh */ }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.SessionStart)) settings.hooks.SessionStart = [];
+
+  const MARKER = 'graphify-global-add';
+  settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
+    e => e?.description !== MARKER,
+  );
+
+  // Always use `python -m graphify` (never the bare binary) so the hook is safe
+  // across future shell sessions where an old graphify binary might shadow the
+  // currently-installed version via PATH. Derived fresh here rather than baking
+  // in the cli token resolved at install time.
+  const pythonExe = IS_WINDOWS ? 'python' : 'python3';
+  const cmd = `[ -f graphify-out/graph.json ] && ${pythonExe} -m graphify global add graphify-out/graph.json --as "$(basename "$PWD")" > /dev/null 2>&1 || true`;
+
+  settings.hooks.SessionStart.push({
+    description: MARKER,
+    hooks: [{ type: 'command', command: cmd }],
+  });
+
+  mkdirSync(claudeDir, { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+}
+
+// Write the graphify-global MCP server entry to ~/.claude/settings.json so Claude Code
+// auto-starts it on launch. Uses `python -m graphify.serve` to avoid PATH issues with
+// stale graphify.exe binaries that may shadow the currently installed version.
+//
+// The command is a single stable token — `python` on Windows, `python3` on POSIX —
+// so the JSON args array is always parseable (py.cmd can be `py -3` which has a space
+// and would break if used directly as the command field).
+export function installGraphifyMcpServer(homeDir) {
+  const claudeDir = join(homeDir, '.claude');
+  if (!existsSync(claudeDir)) return;
+
+  const settingsPath = join(claudeDir, 'settings.json');
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try { settings = JSON.parse(readFileSync(settingsPath, 'utf8')); } catch { /* corrupt — start fresh */ }
+  }
+
+  if (!settings.mcpServers) settings.mcpServers = {};
+
+  // Use join() so the path uses OS-correct separators on all platforms.
+  const globalGraphPath = join(homeDir, '.graphify', 'global-graph.json');
+  // `python` on Windows (Microsoft Store + standard installer both put it on PATH),
+  // `python3` on macOS/Linux (standard convention; `python` may not exist).
+  const pythonExe = IS_WINDOWS ? 'python' : 'python3';
+
+  settings.mcpServers['graphify-global'] = {
+    command: pythonExe,
+    args: ['-m', 'graphify.serve', globalGraphPath],
+  };
+
+  mkdirSync(claudeDir, { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+}
+
+// After pip install, the CLI binary may not be on PATH (pip --user puts it in a Scripts
+// dir that is often missing from PATH, and on Windows an old binary can shadow the new
+// one). When pip was used, always prefer `python -m <module>` to guarantee we run the
+// just-installed version. For uv/pipx the binary is on PATH — probe with which/where
+// (not --version, since some CLIs don't support that flag and exit non-zero).
+async function resolveCliInvocation(cliCommand, pythonCmd, installer) {
+  if (installer?.name === 'pip') {
+    return `${pythonCmd} -m ${cliCommand}`;
+  }
+  try {
+    await execAsync(`${WHICH_CMD} ${cliCommand}`, { timeout: 10000 });
+    return cliCommand;
+  } catch {
+    return `${pythonCmd} -m ${cliCommand}`;
+  }
+}
+
+async function runPythonCli(integration, key, { silent = false } = {}) {
+  const spinner = silent ? null : fmt.spinner();
+
+  // 1. Detect Python ≥ minPython.
+  if (!silent) spinner.start(`Checking for Python ${integration.minPython.major}.${integration.minPython.minor}+...`);
+  const py = await detectPython(integration.minPython);
+  if (!py) {
+    if (!silent) spinner.stop(chalk.yellow('Python not found'));
+    recordSkipped(key, 'python-cli', 'python-not-found');
+    if (!silent) {
+      fmt.logWarn(
+        `${integration.label} skipped — Python ${integration.minPython.major}.${integration.minPython.minor}+ required.`,
+      );
+      fmt.note(
+        `Install Python from https://www.python.org/downloads/ and re-run \`aw init\` to retry.`,
+        'Skipped',
+      );
+    }
+    return false;
+  }
+  if (!silent) spinner.stop(`✓ Python ${py.version} found`);
+
+  // 2. Pick installer (uv > pipx > pip --user).
+  const installer = await pickPythonInstaller(py.cmd);
+
+  // 3. Install the package.
+  if (!silent) spinner.start(`Installing ${integration.pipPackage} via ${installer.name}...`);
+  try {
+    await execAsync(installer.build(integration.pipPackage), {
+      timeout: 5 * 60 * 1000,
+      maxBuffer: 20 * 1024 * 1024,
+    });
+    if (!silent) spinner.stop('✓ Package installed');
+  } catch (e) {
+    if (!silent) spinner.stop(chalk.yellow('Package install failed'));
+    throw new Error(`${installer.name} install failed: ${e.message}`);
+  }
+
+  // 4. Resolve the CLI invocation (handles pip --user PATH gaps).
+  //    Pass installer so pip-installed tools always use `python -m` (avoids Windows
+  //    PATH shadowing where an old binary intercepts the command).
+  const cli = await resolveCliInvocation(integration.cliCommand, py.cmd, installer);
+
+  // 5. Run global post-install hooks (e.g. `graphify install` registers the skill).
+  for (const args of integration.postInstall || []) {
+    let resolvedArgs = [...args];
+    // graphify install needs --platform windows on Windows so the SKILL.md it writes
+    // uses PowerShell syntax instead of bash — without this the skill fails on first use.
+    if (integration.cliCommand === 'graphify' && resolvedArgs[0] === 'install' && IS_WINDOWS) {
+      resolvedArgs = [...resolvedArgs, '--platform', 'windows'];
+    }
+    const cmd = `${cli} ${resolvedArgs.join(' ')}`;
+    try {
+      await execAsync(cmd, { timeout: 60 * 1000, maxBuffer: 10 * 1024 * 1024 });
+    } catch (e) {
+      if (!silent) fmt.logWarn(`${cmd} failed: ${e.message}`);
+      // Non-fatal — global registration may already exist.
+    }
+  }
+
+  // 5b. For graphify: wire up the global MCP server and the SessionStart hook that
+  //     auto-registers any built graph into ~/.graphify/global-graph.json on IDE open.
+  //     The graph itself is built manually via `/graphify .` — graphify's own per-IDE
+  //     install (step 6 below) writes the CLAUDE.md / AGENTS.md sections for that.
+  if (integration.cliCommand === 'graphify') {
+    installGraphifyMcpServer(HOME);
+    installGraphifyGlobalAddHook(HOME);
+  }
+
+  // 6. Run per-project hooks if cwd looks like a real project (not HOME).
+  const cwd = process.cwd();
+  const isHome = cwd === HOME;
+  const hasGit = existsSync(join(cwd, '.git'));
+  if (!isHome) {
+    for (const step of integration.perProjectInstall || []) {
+      if (step.requiresGit && !hasGit) continue;
+      // Skip IDE-specific steps when that IDE is not configured on this machine.
+      if (step.requiresIde && !existsSync(join(HOME, step.requiresIde))) continue;
+      // Skip steps that require a specific file to exist in the project (e.g. graph.json).
+      if (step.requiresFile && !existsSync(join(cwd, step.requiresFile))) continue;
+      const args = step.appendCwdBasename ? [...step.args, basename(cwd)] : step.args;
+      const cmd = `${cli} ${args.join(' ')}`;
+      try {
+        await execAsync(cmd, { cwd, timeout: 5 * 60 * 1000, maxBuffer: 10 * 1024 * 1024 });
+      } catch (e) {
+        if (!silent) fmt.logWarn(`${cmd} failed: ${e.message}`);
+        // Non-fatal — user can re-run later.
+      }
+    }
+  }
+
+  return true;
+}
+
+// ────────────────────────────────────────────────────────────────────────────────
+// PLUGIN INSTALLER (claude plugin install)
+// ────────────────────────────────────────────────────────────────────────────────
+
+async function runClaudePlugin(installCmd, { silent = false, marketplaceSource = null } = {}) {
+  const spinner = silent ? null : fmt.spinner();
+
+  try {
+    if (!silent) spinner.start(`Installing ${installCmd}...`);
+
+    // Check if claude CLI is available (cross-platform)
+    try {
+      execSync(process.platform === 'win32' ? 'where claude' : 'which claude', { stdio: 'ignore' });
+    } catch {
+      if (!silent) {
+        spinner.stop(chalk.yellow('Claude CLI not found'));
+      }
+      throw new Error('claude: command not found (install Claude Code first)');
+    }
+
+    // Some plugins require a marketplace add step before install
+    if (marketplaceSource) {
+      await execAsync(`claude plugin marketplace add ${marketplaceSource}`, {
+        timeout: 60000,
+        maxBuffer: 10 * 1024 * 1024,
+      });
+    }
+
+    // Run the install
+    await execAsync(`claude plugin install ${installCmd}`, {
+      timeout: 120000,
+      maxBuffer: 10 * 1024 * 1024,
+    });
+
+    if (!silent) spinner.stop('✓ Installed');
+    return true;
+  } catch (e) {
+    if (!silent) spinner.stop(chalk.yellow('Installation failed'));
+    throw e;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────────
+// UNIVERSAL INSTALLER (OS-detected master script — covers all IDEs in one shot)
+// ────────────────────────────────────────────────────────────────────────────────
+
+async function runUniversalInstaller(integration, key, { silent = false } = {}) {
+  const spinner = silent ? null : fmt.spinner();
+
+  if (!silent) spinner.start(`Installing ${integration.label} for all detected IDEs...`);
+
+  try {
+    let cmd;
+
+    // If no scripts defined at all, skip binary install and go straight to postInstall
+    const hasScript = integration.scripts?.win32 || integration.scripts?.posix;
+
+    if (!hasScript && IS_WINDOWS && integration.npmPackage) {
+      // npm-only tool on Windows (e.g. Skills)
+      if (!silent) fmt.logWarn(`No binary installer — using npm for ${integration.label}`);
+      cmd = `npm install -g ${integration.npmPackage}`;
+    } else if (!hasScript) {
+      // No binary, no npm — skip straight to postInstall (e.g. npx-only tools)
+      cmd = null;
+    } else if (IS_WINDOWS) {
+      if (integration.scripts.win32) {
+        cmd = `powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm '${integration.scripts.win32}' | iex"`;
+      } else {
+        // No Windows script — try WSL first, then npm fallback
+        let wslOk = false;
+        try {
+          execSync('wsl --status', { stdio: 'ignore' });
+          // Verify bash is actually available inside WSL
+          execSync('wsl -- bash --version', { stdio: 'ignore' });
+          wslOk = true;
+        } catch { /* WSL absent or bash not installed */ }
+
+        if (wslOk) {
+          cmd = `wsl -- bash -c "curl -fsSL '${integration.scripts.posix}' | sh"`;
+        } else if (integration.npmPackage) {
+          if (!silent) fmt.logWarn('WSL/bash not available — installing via npm instead');
+          cmd = `npm install -g ${integration.npmPackage}`;
+        } else {
+          if (!silent) {
+            spinner.stop(chalk.yellow('WSL not found'));
+            fmt.logWarn(
+              `${integration.label} requires WSL on Windows for full support.\n` +
+              `  Install WSL: https://learn.microsoft.com/en-us/windows/wsl/install`,
+              'Skipped',
+            );
+          }
+          recordSkipped(key, 'universal-installer', 'wsl-not-found');
+          return false;
+        }
+      }
+    } else {
+      cmd = `curl -fsSL '${integration.scripts.posix}' | bash`;
+    }
+
+    if (cmd) {
+      await execAsync(cmd, {
+        timeout: 5 * 60 * 1000,
+        maxBuffer: 20 * 1024 * 1024,
+      });
+    }
+
+    // Run post-install commands (e.g. rtk init -g to wire the agent hook)
+    for (const postCmd of integration.postInstall || []) {
+      let finalPostCmd = postCmd;
+      // If on Windows and we used WSL for the main install, we must use it for the post command too
+      if (IS_WINDOWS && cmd && cmd.startsWith('wsl')) {
+        finalPostCmd = `wsl -- ${postCmd}`;
+      }
+
+      try {
+        await execAsync(finalPostCmd, { timeout: 60 * 1000, maxBuffer: 10 * 1024 * 1024 });
+      } catch (e) {
+        if (!silent) fmt.logWarn(`Post-install step failed: ${finalPostCmd} — ${e.message}`);
+        // Non-fatal — user can re-run later
+      }
+    }
+
+    if (!silent) spinner.stop('✓ Installed');
+    return true;
+  } catch (e) {
+    if (!silent) spinner.stop(chalk.yellow('Installation failed'));
+    throw e;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────────
+// INTEGRATION INSTALLER
+// ────────────────────────────────────────────────────────────────────────────────
+
+export async function installIntegration(key, { silent = false } = {}) {
+  const integration = INTEGRATIONS[key];
+  if (!integration) {
+    throw new Error(`Unknown integration: ${key}`);
+  }
+
+  if (isInstalled(key)) {
+    if (!silent) fmt.logWarn(`${integration.label} is already installed`);
+    return false;
+  }
+
+  try {
+    if (integration.type === 'plugin') {
+      // PLUGIN: Run claude plugin install
+      await runClaudePlugin(integration.installCmd, { silent, marketplaceSource: integration.marketplaceSource ?? null });
+      recordInstalled(key, 'plugin');
+
+      if (!silent) {
+        fmt.logSuccess(`${integration.label} plugin installed`);
+        if (integration.authNote) {
+          fmt.note(integration.authNote, 'Next Step');
+        }
+      }
+    } else if (integration.type === 'remote-mcp') {
+      // REMOTE MCP: Add to mcp.json files
+      if (!silent) fmt.logStep(`Adding ${integration.label} MCP server...`);
+
+      const config = { type: 'http', url: integration.mcpUrl };
+
+      // Claude Code: ~/.claude.json
+      addToJsonMcp(
+        join(HOME, '.claude.json'),
+        key,
+        config
+      );
+
+      // Cursor: ~/.cursor/mcp.json
+      addToJsonMcp(
+        join(HOME, '.cursor', 'mcp.json'),
+        key,
+        config
+      );
+
+      // Codex: ~/.codex/config.toml
+      addToTomlMcp(
+        join(HOME, '.codex', 'config.toml'),
+        key,
+        integration.mcpUrl
+      );
+
+      recordInstalled(key, 'remote-mcp');
+
+      if (!silent) {
+        fmt.logSuccess(`${integration.label} added to MCP servers`);
+        if (integration.authNote) {
+          fmt.note(integration.authNote, 'Note');
+        }
+      }
+    } else if (integration.type === 'python-cli') {
+      // PYTHON CLI: pip-install + run post-install + per-project hooks
+      const ok = await runPythonCli(integration, key, { silent });
+      if (!ok) return false;  // skipped (e.g. Python missing) — manifest already recorded
+
+      recordInstalled(key, 'python-cli');
+
+      if (!silent) {
+        fmt.logSuccess(`${integration.label} installed`);
+        if (integration.authNote) {
+          fmt.note(integration.authNote, 'Note');
+        }
+      }
+    } else if (integration.type === 'universal-installer') {
+      // UNIVERSAL INSTALLER: OS-detected master script, covers all IDEs in one shot
+      const ok = await runUniversalInstaller(integration, key, { silent });
+      if (!ok) return false;  // skipped (e.g. WSL not found) — manifest already recorded
+      recordInstalled(key, 'universal-installer');
+
+      if (!silent) {
+        fmt.logSuccess(`${integration.label} installed across all detected IDEs`);
+        if (integration.authNote) {
+          fmt.note(integration.authNote, 'Note');
+        }
+      }
+    }
+
+    return true;
+  } catch (e) {
+    if (!silent) {
+      fmt.logError(`Failed to install ${integration.label}: ${e.message}`);
+    }
+    // Don't record as installed if it failed
+    return false;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────────
+// INTEGRATION REMOVER
+// ────────────────────────────────────────────────────────────────────────────────
+
+export async function removeIntegration(key, { silent = false } = {}) {
+  const integration = INTEGRATIONS[key];
+  if (!integration) {
+    throw new Error(`Unknown integration: ${key}`);
+  }
+
+  if (!isInstalled(key)) {
+    if (!silent) fmt.logWarn(`${integration.label} is not installed`);
+    return false;
+  }
+
+  try {
+    if (integration.type === 'plugin') {
+      // PLUGIN: Manual removal instruction
+      if (!silent) {
+        fmt.logWarn(
+          `To remove the ${integration.label} plugin, run: /plugin in Claude Code and disable it`,
+          'Manual Removal'
+        );
+      }
+    } else if (integration.type === 'remote-mcp') {
+      // REMOTE MCP: Remove from mcp.json files
+      if (!silent) fmt.logStep(`Removing ${integration.label} MCP server...`);
+
+      // Claude Code
+      try {
+        const claudePath = join(HOME, '.claude.json');
+        if (existsSync(claudePath)) {
+          const config = JSON.parse(readFileSync(claudePath, 'utf8'));
+          delete config.mcpServers?.[key];
+          writeFileSync(claudePath, JSON.stringify(config, null, 2) + '\n');
+        }
+      } catch {
+        // Best effort
+      }
+
+      // Cursor
+      try {
+        const cursorPath = join(HOME, '.cursor', 'mcp.json');
+        if (existsSync(cursorPath)) {
+          const config = JSON.parse(readFileSync(cursorPath, 'utf8'));
+          delete config.mcpServers?.[key];
+          writeFileSync(cursorPath, JSON.stringify(config, null, 2) + '\n');
+        }
+      } catch {
+        // Best effort
+      }
+
+      // Codex
+      try {
+        const codexPath = join(HOME, '.codex', 'config.toml');
+        if (existsSync(codexPath)) {
+          let content = readFileSync(codexPath, 'utf8');
+          const blockRegex = new RegExp(
+            `\\[mcp_servers\\.${key}\\][^\\[]*`,
+            'g'
+          );
+          content = content.replace(blockRegex, '');
+          writeFileSync(codexPath, content);
+        }
+      } catch {
+        // Best effort
+      }
+
+      if (!silent) fmt.logSuccess(`${integration.label} removed from MCP servers`);
+    } else if (integration.type === 'python-cli') {
+      // PYTHON CLI: only remove the manifest entry — leave the pip package installed
+      // because the user may use the CLI outside of `aw`. Print manual cleanup hints.
+      if (!silent) {
+        fmt.logWarn(
+          `Removed ${integration.label} from the aw manifest. The Python package was left installed.\n` +
+          `  To fully remove, run in each project: \`${integration.cliCommand} claude uninstall\` and \`${integration.cliCommand} hook uninstall\`\n` +
+          `  Then uninstall the package: \`pip uninstall ${integration.pipPackage.split(/[<>=]/)[0]}\` (or \`uv tool uninstall\` / \`pipx uninstall\`)`,
+          'Manual Cleanup',
+        );
+      }
+    } else if (integration.type === 'universal-installer') {
+      if (!silent) {
+        fmt.logWarn(
+          `Removed ${integration.label} from the aw manifest.\n` +
+          `  To fully uninstall: follow the uninstall instructions for ${integration.label} in its documentation.`,
+          'Manual Cleanup',
+        );
+      }
+    }
+
+    // Remove from manifest
+    const manifest = readManifest();
+    delete manifest.installed[key];
+    writeManifest(manifest);
+
+    return true;
+  } catch (e) {
+    if (!silent) {
+      fmt.logError(`Failed to remove ${integration.label}: ${e.message}`);
+    }
+    return false;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────────
+// HELPERS
+// ────────────────────────────────────────────────────────────────────────────────
+
+export function getInstalledList() {
+  const manifest = readManifest();
+  // Only return entries actually installed — skipped entries (e.g. Python missing)
+  // shouldn't show up as "installed" to the rest of the system.
+  return Object.entries(manifest.installed)
+    .filter(([, entry]) => entry.status !== 'skipped')
+    .map(([key]) => key);
+}
+
+export function suggestForTeam(namespace) {
+  if (!namespace) return [];
+
+  const team = namespace.split('/')[0]; // e.g. 'platform' from 'platform/crm'
+
+  return Object.entries(INTEGRATIONS)
+    .filter(([, integration]) => {
+      // Show if: team is in the integration's teams list OR teams list is empty (universal)
+      return (
+        integration.teams.length === 0 || integration.teams.includes(team)
+      );
+    })
+    .map(([key]) => key);
+}
+
+// ────────────────────────────────────────────────────────────────────────────────
+// AUTO-INSTALL (called from init.mjs - installs suggested integrations)
+// ────────────────────────────────────────────────────────────────────────────────
+
+export async function autoInstallIntegrations(team, { silent = false, installer = installIntegration } = {}) {
+  // Get suggested integrations for this team
+  const suggested = suggestForTeam(team);
+  if (!suggested || suggested.length === 0) {
+    return [];
+  }
+
+  // Only install if they're not already installed
+  const toInstall = suggested.filter((key) => !isInstalled(key));
+  if (toInstall.length === 0) {
+    return [];
+  }
+
+  if (!silent) {
+    fmt.logStep(`Setting up integrations for ${team}...`);
+  }
+
+  const installed = [];
+  for (const key of toInstall) {
+    const success = await installer(key, { silent });
+    if (success) {
+      installed.push(INTEGRATIONS[key].label);
+    }
+  }
+
+  return installed;
+}
+
+// ────────────────────────────────────────────────────────────────────────────────
+// INTERACTIVE SETUP (can be called via: aw integrations)
+// ────────────────────────────────────────────────────────────────────────────────
+
+export async function promptAndInstall(team, { silent = false } = {}) {
+  // Skip if: silent mode, no TTY, or all integrations already installed
+  if (silent || !process.stdin.isTTY) {
+    return [];
+  }
+
+  const suggested = suggestForTeam(team);
+  if (!suggested || suggested.length === 0) {
+    return [];
+  }
+
+  // Check if any suggested integrations are NOT installed
+  const availableToInstall = suggested.filter((key) => !isInstalled(key));
+  if (availableToInstall.length === 0) {
+    // All already installed
+    return [];
+  }
+
+  // Prompt user
+  const p = await import('@clack/prompts');
+  const shouldSetup = await p.default.confirm({
+    message: `Your team (${team}) can use integrations like Codex, Caveman, etc. Set up any now?`,
+    initialValue: false,
+  });
+
+  if (p.default.isCancel(shouldSetup) || !shouldSetup) {
+    return [];
+  }
+
+  // Show bundles + individual tools
+  const bundleOptions = Object.entries(BUNDLES)
+    .filter(([, bundle]) => {
+      return (
+        bundle.teams.length === 0 || bundle.teams.includes(team.split('/')[0])
+      );
+    })
+    .map(([bundleKey, bundle]) => ({
+      value: `bundle:${bundleKey}`,
+      label: `📦 ${bundle.label}`,
+      description: bundle.description,
+    }));
+
+  const individualOptions = availableToInstall.map((key) => {
+    const integration = INTEGRATIONS[key];
+    const icon =
+      integration.type === 'plugin' ? '🔌'
+      : integration.type === 'remote-mcp' ? '🌐'
+      : integration.type === 'python-cli' ? '🐍'
+      : '⚙️';
+    return {
+      value: `integration:${key}`,
+      label: `${icon} ${integration.label}`,
+      description: integration.description,
+    };
+  });
+
+  const choices = [...bundleOptions, ...individualOptions];
+
+  const selected = await p.default.multiselect({
+    message: 'Select integrations to install:',
+    options: choices,
+    required: false,
+  });
+
+  if (p.default.isCancel(selected)) {
+    return [];
+  }
+
+  // Process selections
+  const toInstall = new Set();
+  for (const selection of selected) {
+    if (selection.startsWith('bundle:')) {
+      const bundleKey = selection.replace('bundle:', '');
+      const bundle = BUNDLES[bundleKey];
+      bundle.includes.forEach((key) => toInstall.add(key));
+    } else if (selection.startsWith('integration:')) {
+      const integrationKey = selection.replace('integration:', '');
+      toInstall.add(integrationKey);
+    }
+  }
+
+  // Install all
+  const installed = [];
+  for (const key of toInstall) {
+    const success = await installIntegration(key, { silent: false });
+    if (success) {
+      installed.push(INTEGRATIONS[key].label);
+    }
+  }
+
+  return installed;
+}