bi-superpowers 1.0.0

package/bin/commands/install.js

@@ -0,0 +1,542 @@
+/**
+ * Install Command — Multi-agent skill + MCP installer
+ * =====================================================
+ *
+ * Installs the bi-superpowers skills and Microsoft MCP servers into
+ * every supported AI coding agent:
+ *   - Claude Code
+ *   - GitHub Copilot
+ *   - Codex (OpenAI)
+ *   - Gemini CLI
+ *   - Kilo Code
+ *
+ * Everything is installed at the user level (~/) so it applies across
+ * all projects without polluting any specific repo. Skills land in
+ * ~/.agents/skills/ (universal path) and each agent's own skill dir is
+ * symlinked to that universal copy when possible. Copy fallback mirrors
+ * managed skill directories on every run. MCPs are written to each agent's
+ * expected config file in the format that agent requires (JSON for
+ * most, TOML for Codex) — see `lib/mcp-config.js` for details.
+ *
+ * Fully open source (MIT). CLI copy, comments, and JSDoc stay in English
+ * so contributors from any language can work on the source.
+ *
+ * Usage:
+ *   npx bi-superpowers install
+ *   super install
+ *   super install --agent claude-code --agent codex
+ *   super install --all --yes
+ *
+ * @module commands/install
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const { AGENTS, UNIVERSAL_DIR } = require('../lib/agents');
+const { writeMcpConfigForAgent } = require('../lib/mcp-config');
+const { getSkillPurpose } = require('../lib/generators/shared');
+
+/**
+ * Detect which agents are installed by checking their config directories.
+ * Used in the interactive installer to pre-select the detected agents.
+ * @param {string} baseDir - Base directory to scan (typically the user's home)
+ * @returns {string[]} IDs of detected agents
+ */
+function detectAgents(baseDir) {
+  const detected = [];
+  for (const [id, agent] of Object.entries(AGENTS)) {
+    const agentRoot = path.dirname(agent.dir);
+    const checkPaths =
+      id === 'kilo'
+        ? [path.join(baseDir, agentRoot), path.join(baseDir, '.config', 'kilo')]
+        : [path.join(baseDir, agentRoot)];
+
+    if (checkPaths.some((checkPath) => fs.existsSync(checkPath))) {
+      detected.push(id);
+    }
+  }
+  return detected;
+}
+
+/**
+ * Create a readline interface for interactive prompts.
+ */
+function createReadline() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+/**
+ * Promise-wrapped readline question.
+ */
+function prompt(rl, question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => resolve(answer.trim()));
+  });
+}
+
+/**
+ * Render a numbered multi-select list and wait for the user's choice.
+ * @param {readline.Interface} rl
+ * @param {Array<{id: string, name: string}>} items
+ * @param {string[]} preselected - IDs that should default to selected
+ * @returns {Promise<string[]>} Selected IDs
+ */
+async function selectMultiple(rl, items, preselected = []) {
+  items.forEach((item, i) => {
+    const marker = preselected.includes(item.id) ? '●' : '○';
+    console.log(`  ${i + 1}) ${marker} ${item.name}`);
+  });
+  console.log();
+  console.log('  Enter numbers separated by commas (for example: 1,2,3)');
+  console.log('  Press Enter for detected agents, or "a" for all agents');
+
+  const answer = await prompt(rl, '\n  > ');
+
+  if (answer.toLowerCase() === 'a') {
+    return items.map((item) => item.id);
+  }
+
+  if (answer === '') {
+    return preselected.length > 0 ? preselected : items.map((item) => item.id);
+  }
+
+  const indices = answer
+    .split(',')
+    .map((s) => parseInt(s.trim(), 10) - 1)
+    .filter((i) => i >= 0 && i < items.length);
+
+  return indices.map((i) => items[i].id);
+}
+
+/**
+ * Recursively copy a skill directory (SKILL.md + references/ + scripts/).
+ * Filesystem errors propagate to the caller for centralized handling.
+ * @param {string} srcDir - Source skill directory
+ * @param {string} destDir - Destination directory
+ */
+function copySkillDir(srcDir, destDir) {
+  const resolvedSrc = path.resolve(srcDir);
+  const resolvedDest = path.resolve(destDir);
+  const destRoot = path.parse(resolvedDest).root;
+
+  if (
+    resolvedSrc === resolvedDest ||
+    resolvedSrc.startsWith(`${resolvedDest}${path.sep}`) ||
+    resolvedDest === destRoot
+  ) {
+    throw new Error(`Refusing to mirror skill directory into unsafe target: ${destDir}`);
+  }
+
+  // Skill directories are package-managed. Remove the old managed copy first
+  // so upgrades cannot leave deleted scripts or references behind.
+  const existingDest = fs.lstatSync(destDir, { throwIfNoEntry: false });
+  if (existingDest) {
+    if (existingDest.isSymbolicLink()) {
+      fs.unlinkSync(destDir);
+    } else {
+      fs.rmSync(destDir, { recursive: true, force: true });
+    }
+  }
+
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copySkillDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Format a filesystem error with a user-friendly hint based on the code.
+ * Keeps the underlying error message so debugging is still possible.
+ */
+function formatFsError(err, context) {
+  const codeHints = {
+    EACCES: 'Permission denied. Check the directory permissions.',
+    EPERM: 'Operation not permitted. On Windows, try running as Administrator.',
+    ENOSPC: 'No disk space left.',
+    ENOENT: 'File or directory does not exist.',
+    EROFS: 'Read-only filesystem.',
+  };
+  const hint = codeHints[err.code] || '';
+  return `${context}: ${err.message}${hint ? `\n  ${hint}` : ''}`;
+}
+
+/**
+ * Parse CLI arguments into an options object.
+ * Validates that each --agent / -a flag is followed by a real value
+ * so we don't silently accept dangling flags.
+ */
+function parseArgs(args) {
+  const opts = {
+    isYes: args.includes('--yes') || args.includes('-y'),
+    isAll: args.includes('--all'),
+    autoUpdate: args.includes('--auto-update'),
+    agentFlags: [],
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--agent' || args[i] === '-a') {
+      const next = args[i + 1];
+      if (next === undefined || next.startsWith('-')) {
+        // Missing value — warn and skip this flag instead of crashing.
+        console.warn(
+          `⚠ Flag ${args[i]} is missing a value. Usage: ${args[i]} <agent-id>. Ignoring.`
+        );
+        continue;
+      }
+      opts.agentFlags.push(next);
+      i++;
+    }
+  }
+
+  return opts;
+}
+
+/**
+ * Resolve which agents to install based on flags or interactive prompt.
+ * @returns {Promise<string[]>} IDs of the selected agents
+ */
+async function resolveSelectedAgents(opts, baseDir, chalk) {
+  if (opts.isAll) {
+    return Object.keys(AGENTS);
+  }
+
+  if (opts.agentFlags.length > 0) {
+    const known = opts.agentFlags.filter((a) => AGENTS[a]);
+    const unknown = opts.agentFlags.filter((a) => !AGENTS[a]);
+    if (unknown.length > 0) {
+      console.log(chalk.yellow(`  Unknown agents: ${unknown.join(', ')}`));
+      console.log(chalk.gray(`  Available agents: ${Object.keys(AGENTS).join(', ')}\n`));
+    }
+    return known;
+  }
+
+  if (opts.isYes) {
+    return Object.keys(AGENTS);
+  }
+
+  // Interactive mode — detect installed agents and prompt the user.
+  const detected = detectAgents(baseDir);
+  console.log(chalk.cyan('  Select the agents where you want to install:\n'));
+
+  const items = Object.entries(AGENTS).map(([id, agent]) => ({
+    id,
+    name: detected.includes(id) ? `${agent.name} ${chalk.green('(detected)')}` : agent.name,
+  }));
+
+  const rl = createReadline();
+  try {
+    return await selectMultiple(rl, items, detected);
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Copy skills into the universal path first, then either symlink or copy
+ * each selected agent's skill directory to point at the universal copy.
+ * @returns {{agentResults: Array, copyFallbacks: number}}
+ */
+function performInstall(skillsSourceDir, skillDirs, selectedAgents, baseDir) {
+  // Always install to the universal path first. This is the source of
+  // truth that all other agent dirs symlink to.
+  const universalTarget = path.join(baseDir, UNIVERSAL_DIR);
+  for (const skill of skillDirs) {
+    const src = path.join(skillsSourceDir, skill);
+    const dest = path.join(universalTarget, skill);
+    copySkillDir(src, dest);
+  }
+
+  const agentResults = [];
+  let copyFallbacks = 0;
+
+  for (const agentId of selectedAgents) {
+    const agent = AGENTS[agentId];
+    if (agent.dir === UNIVERSAL_DIR) continue; // Already handled above.
+
+    const agentTarget = path.join(baseDir, agent.dir);
+
+    // If a real directory already exists (not a symlink), copy into it
+    // directly so we don't destroy user data.
+    if (fs.existsSync(agentTarget) && !fs.lstatSync(agentTarget).isSymbolicLink()) {
+      for (const skill of skillDirs) {
+        copySkillDir(path.join(skillsSourceDir, skill), path.join(agentTarget, skill));
+      }
+      agentResults.push({ agent: agent.name, method: 'copied', dir: agent.dir });
+      continue;
+    }
+
+    const parentDir = path.dirname(agentTarget);
+    if (!fs.existsSync(parentDir)) {
+      fs.mkdirSync(parentDir, { recursive: true });
+    }
+
+    // Remove any pre-existing symlink so we can recreate it cleanly.
+    if (fs.existsSync(agentTarget) || fs.lstatSync(agentTarget, { throwIfNoEntry: false })) {
+      try {
+        fs.unlinkSync(agentTarget);
+      } catch (_) {
+        /* target didn't exist after all — that's fine */
+      }
+    }
+
+    try {
+      // Relative symlink from the agent's dir to the universal dir.
+      const relPath = path.relative(parentDir, universalTarget);
+      fs.symlinkSync(relPath, agentTarget);
+      agentResults.push({ agent: agent.name, method: 'symlinked', dir: agent.dir });
+    } catch (symlinkErr) {
+      // Windows without admin can't create symlinks. Fall back to copy
+      // and remember so we can warn the user at the end.
+      copyFallbacks++;
+      if (!fs.existsSync(agentTarget)) {
+        fs.mkdirSync(agentTarget, { recursive: true });
+      }
+      for (const skill of skillDirs) {
+        copySkillDir(path.join(skillsSourceDir, skill), path.join(agentTarget, skill));
+      }
+      agentResults.push({
+        agent: agent.name,
+        method: 'copied',
+        dir: agent.dir,
+        fallbackReason: symlinkErr.code || symlinkErr.message,
+      });
+    }
+  }
+
+  return { agentResults, copyFallbacks };
+}
+
+/**
+ * Configure the 2 MCP servers (powerbi-modeling + microsoft-learn)
+ * for each selected agent by writing the config file in the path and
+ * format that agent expects.
+ *
+ * Per-agent errors don't abort the whole flow: they're collected in the
+ * results array so the caller can display them and decide on the exit
+ * code.
+ *
+ * @param {string[]} selectedAgents - Agent IDs to configure
+ * @param {string} packageDir - Absolute path to the installed package
+ * @param {string} baseDir - User's home directory (for display)
+ * @param {Object} chalk - chalk instance for colored output
+ * @returns {Array<{agent: string, success: boolean, configPath?: string, error?: string}>}
+ */
+function configureMcpsForAgents(selectedAgents, packageDir, baseDir, chalk) {
+  console.log(chalk.cyan('\n  Configuring MCP servers (Power BI Modeling + Microsoft Learn)...\n'));
+
+  const results = [];
+  for (const agentId of selectedAgents) {
+    const agent = AGENTS[agentId];
+    try {
+      const configPath = writeMcpConfigForAgent(agentId, packageDir);
+      if (configPath) {
+        const relPath = configPath.replace(baseDir, '~');
+        console.log(chalk.green(`  ✓ ${relPath} — ${agent.name}`));
+        results.push({ agent: agent.name, configPath, success: true });
+      }
+    } catch (err) {
+      console.log(chalk.red(`  ✗ ${agent.name}: ${err.message}`));
+      results.push({ agent: agent.name, success: false, error: err.message });
+    }
+  }
+  return results;
+}
+
+/**
+ * Main handler for the `super install` command.
+ * @param {string[]} args - CLI arguments
+ * @param {Object} config - Command config from the CLI (packageDir, version)
+ */
+async function installCommand(args, config) {
+  const chalk = require('chalk');
+  const boxen = require('boxen');
+
+  const opts = parseArgs(args);
+
+  // Always install at the user level (home directory) — skills and MCPs
+  // apply across all projects without polluting any specific repo.
+  const baseDir = os.homedir();
+
+  // Locate the skills inside the installed package.
+  const packageDir = config.packageDir || path.dirname(path.dirname(__dirname));
+  const skillsSourceDir = path.join(packageDir, 'skills');
+
+  if (!fs.existsSync(skillsSourceDir)) {
+    console.error(
+      chalk.red(
+        'Skills directory not found. Reinstall the package with: npm install -g bi-superpowers'
+      )
+    );
+    process.exit(1);
+  }
+
+  // Read the available skill directories from the package.
+  let skillDirs;
+  try {
+    skillDirs = fs
+      .readdirSync(skillsSourceDir, { withFileTypes: true })
+      .filter(
+        (d) => d.isDirectory() && fs.existsSync(path.join(skillsSourceDir, d.name, 'SKILL.md'))
+      )
+      .map((d) => d.name);
+  } catch (err) {
+    console.error(chalk.red(formatFsError(err, 'Could not read skills')));
+    process.exit(1);
+  }
+
+  // Header box shown at the top of every install run.
+  console.log(
+    boxen(
+      chalk.bold.cyan('BI Agent Superpowers') +
+        chalk.gray(` v${config.version}`) +
+        '\n' +
+        chalk.gray('Multi-agent installer'),
+      {
+        padding: 1,
+        borderStyle: 'round',
+        borderColor: 'cyan',
+      }
+    )
+  );
+
+  console.log(chalk.gray(`  Install path: ~/${UNIVERSAL_DIR}/`));
+  console.log(chalk.gray(`  Skills available: ${skillDirs.length}\n`));
+
+  // Resolve which agents to configure.
+  const selectedAgents = await resolveSelectedAgents(opts, baseDir, chalk);
+
+  if (selectedAgents.length === 0) {
+    console.log(chalk.yellow('\n  No agent selected. Nothing to install.'));
+    return;
+  }
+
+  console.log(
+    chalk.cyan(`\n  Installing ${skillDirs.length} skills for ${selectedAgents.length} agents...\n`)
+  );
+
+  // Phase 1: copy skills and create symlinks per agent.
+  let agentResults;
+  let copyFallbacks;
+  try {
+    const result = performInstall(skillsSourceDir, skillDirs, selectedAgents, baseDir);
+    agentResults = result.agentResults;
+    copyFallbacks = result.copyFallbacks;
+  } catch (err) {
+    console.error(chalk.red(formatFsError(err, 'Skill installation failed')));
+    process.exit(1);
+  }
+
+  // Report on the universal skills path.
+  const universalAgents = selectedAgents
+    .filter((id) => AGENTS[id] && AGENTS[id].dir === UNIVERSAL_DIR)
+    .map((id) => AGENTS[id].name);
+  const universalSuffix = universalAgents.length > 0 ? ` — ${universalAgents.join(', ')}` : '';
+  console.log(chalk.green(`  ✓ ${UNIVERSAL_DIR}/ (${skillDirs.length} skills)${universalSuffix}`));
+
+  // Report per agent.
+  for (const result of agentResults) {
+    const icon = result.method === 'symlinked' ? '→' : '✓';
+    console.log(chalk.green(`  ${icon} ${result.dir}/ (${result.method}) — ${result.agent}`));
+  }
+
+  // Warn if any agent fell back from symlink to copy.
+  if (copyFallbacks > 0) {
+    console.log(
+      chalk.yellow(
+        `\n  ⚠ ${copyFallbacks} agent(s) used copy fallback instead of symlink ` +
+          '(probably Windows without admin permissions).\n' +
+          "    Re-run 'super install' after each upgrade; copied installs are mirrored and stale runtimes are removed."
+      )
+    );
+  }
+
+  // Phase 2: write the 2 MCP configs per agent.
+  const mcpResults = configureMcpsForAgents(selectedAgents, packageDir, baseDir, chalk);
+
+  // Build the final summary box.
+  const totalAgents = agentResults.length + (universalAgents.length > 0 ? 1 : 0);
+  const mcpSuccess = mcpResults.filter((r) => r.success).length;
+  const mcpFailures = mcpResults.filter((r) => !r.success);
+  const hasFailures = mcpFailures.length > 0;
+
+  const successMsg = `Installed ${skillDirs.length} skills + 2 MCPs for ${totalAgents} agents`;
+  const failureMsg = `Installed ${skillDirs.length} skills. MCPs: ${mcpSuccess}/${mcpResults.length} agents ok, ${mcpFailures.length} failed.`;
+  const headerLine = hasFailures ? chalk.yellow.bold(failureMsg) : chalk.green.bold(successMsg);
+
+  const failureDetail = hasFailures
+    ? '\n' +
+      chalk.red('Agents with MCP errors:') +
+      '\n' +
+      mcpFailures.map((r) => chalk.red(`  ✗ ${r.agent}: ${r.error}`)).join('\n') +
+      '\n'
+    : '';
+
+  const skillSummary = skillDirs
+    .map((skillName) => `  /${skillName.padEnd(15)} — ${getSkillPurpose(skillName)}`)
+    .join('\n');
+
+  console.log(
+    boxen(
+      headerLine +
+        failureDetail +
+        '\n\n' +
+        chalk.gray(`MCPs configured in ${mcpSuccess}/${mcpResults.length} agents.`) +
+        '\n' +
+        chalk.gray('Restart your AI agent so it loads the new MCP configuration.') +
+        '\n\n' +
+        chalk.gray(`Skills available (${skillDirs.length}):`) +
+        '\n' +
+        chalk.gray(skillSummary),
+      {
+        padding: 1,
+        margin: { top: 1 },
+        borderStyle: 'round',
+        borderColor: hasFailures ? 'yellow' : 'green',
+      }
+    )
+  );
+
+  // Opt-in: register the Claude Code SessionStart auto-update hook.
+  if (opts.autoUpdate) {
+    try {
+      const { enableAutoupdate } = require('./autoupdate');
+      enableAutoupdate(packageDir);
+      console.log(
+        chalk.green('\n  ✓ Auto-update enabled (Claude Code SessionStart hook).') +
+          chalk.gray('\n    New Claude Code sessions self-update via npm (throttled, background).')
+      );
+    } catch (err) {
+      console.log(chalk.yellow(`\n  ⚠ Could not enable auto-update: ${err.message}`));
+    }
+  }
+
+  if (hasFailures) {
+    // Non-zero exit so CI/scripts know something went wrong. Exit code 2
+    // distinguishes partial failure (skills ok, some MCPs failed) from
+    // total failure (exit code 1).
+    process.exitCode = 2;
+  }
+}
+
+// Internal exports for testing.
+module.exports = installCommand;
+module.exports.parseArgs = parseArgs;
+module.exports.detectAgents = detectAgents;
+module.exports.copySkillDir = copySkillDir;
+module.exports.formatFsError = formatFsError;
+module.exports.AGENTS = AGENTS;
+module.exports.UNIVERSAL_DIR = UNIVERSAL_DIR;