bi-superpowers 1.0.0

package/bin/cli.js

@@ -0,0 +1,891 @@
+#!/usr/bin/env node
+
+/**
+ * BI Agent Superpowers — Command Line Interface
+ * ==============================================
+ *
+ * Main entry point for the `super` CLI. Provides commands to install
+ * skills and MCP servers into AI coding agents, and to generate the
+ * native Claude Code plugin into a project.
+ *
+ * Architecture:
+ * - Skills are authored once in src/content/skills/ and copied out to
+ *   each supported agent by `super install`.
+ * - `super kickoff` optionally generates a local Claude Code plugin tree in a
+ *   user project (skills + commands + MCP config).
+ * - `super recharge` regenerates an existing local Claude Code plugin after edits.
+ *
+ * Supported agents: Claude Code, GitHub Copilot, Codex, Gemini CLI, Kilo Code.
+ * License: MIT. This project is fully open source — no activation, no keys.
+ *
+ * @module cli
+ * @author Lucas Sanchez (@luquimbo)
+ * @license MIT
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { loadSkills } = require('./lib/skills');
+
+// Optional lib import — may not be available during npm install phase.
+let generators;
+try {
+  generators = require('./lib/generators');
+} catch (_) {
+  // Silent fallback; commands will report a useful error when invoked.
+}
+
+// Optional command imports — each module may fail to load during npm
+// install before dependencies are wired up. The CLI still renders `help`
+// and `version` because those are hoisted, module-free functions.
+let lintCommand;
+let diffCommand;
+let watchCommand;
+let mcpSetupCommand;
+let buildDesktopCommand;
+let installCommand;
+let uninstallCommand;
+let autoupdateCommand;
+let validateCasesCommand;
+let validateProjectsCommand;
+let smokeTestCommand;
+let createFromTemplateCommand;
+let tui;
+try {
+  lintCommand = require('./commands/lint'); // checkup: skill file validation
+  diffCommand = require('./commands/diff'); // scan: diff source vs generated
+  watchCommand = require('./commands/watch'); // sentinel: watch + auto regen
+  mcpSetupCommand = require('./commands/mcp-setup'); // MCP server configuration
+  buildDesktopCommand = require('./commands/build-desktop'); // .mcpb for Claude Desktop
+  installCommand = require('./commands/install'); // multi-agent skill + MCP installer
+  uninstallCommand = require('./commands/uninstall'); // multi-agent skill + MCP remover
+  autoupdateCommand = require('./commands/autoupdate'); // opt-in SessionStart self-update hook
+  validateCasesCommand = require('./commands/validate-cases'); // validation playbook discovery
+  validateProjectsCommand = require('./commands/validate-projects'); // repo/project validation harness
+  smokeTestCommand = require('./commands/smoke-test'); // live base-template smoke test
+  createFromTemplateCommand = require('./commands/create-from-template'); // PBIP scaffold from templates/
+  tui = require('./utils/tui'); // colors, tables, boxes for CLI output
+} catch (_) {
+  // Expected during `npm install` — modules become available after deps are linked.
+}
+
+// ============================================
+// CONFIGURATION CONSTANTS
+// ============================================
+
+/** Package version (read from package.json at runtime) */
+const VERSION = require('../package.json').version;
+
+/**
+ * Skill and command counts used by the help text and dry-run previews.
+ * Pulled dynamically from the generator so we never hardcode outdated totals.
+ */
+let COMMAND_COUNT = 0;
+let TOTAL_SKILL_COUNT = 0;
+try {
+  const { COMMAND_SKILLS, REFERENCE_SKILLS } = require('./lib/generators/claude-plugin');
+  COMMAND_COUNT = COMMAND_SKILLS.size;
+  TOTAL_SKILL_COUNT = COMMAND_SKILLS.size + REFERENCE_SKILLS.size;
+} catch (_) {
+  // Fallback during npm install phase — values stay at 0 until the module loads.
+}
+
+/** Absolute path to the installed package directory (one level above bin/) */
+const PACKAGE_DIR = path.dirname(__dirname);
+
+/** Directory containing the authoring source for each skill */
+const SKILLS_DIR = path.join(PACKAGE_DIR, 'src', 'content', 'skills');
+
+/** Project-local config file name used by kickoff/recharge */
+const CONFIG_FILE = '.bi-superpowers.json';
+
+/** npm package name for the upgrade command */
+const PACKAGE_NAME = 'bi-superpowers';
+
+/** Default tool set generated by kickoff (currently only the Claude Code plugin) */
+const DEFAULT_TOOLS = ['claude-plugin'];
+
+/** Generator registry (populated from lib/generators if available) */
+const AI_TOOLS = generators ? generators.AI_TOOLS : {};
+
+// ============================================
+// COMMAND ROUTING
+// ============================================
+// Commands are registered in two phases to avoid temporal-dead-zone errors.
+// Phase 1: hoisted function declarations (help, version, about, kickoff...)
+//          go directly into the object literal below.
+// Phase 2: wrapper-based commands that depend on createCommandWrapper
+//          (defined further below) are attached imperatively.
+const commands = {
+  // Core commands — hoisted functions, safe to reference here.
+  help: showHelp,
+  version: showVersion,
+  about: showInfo,
+
+  // Primary flow — also hoisted functions.
+  kickoff: initProject,
+  recharge: syncProject,
+  upgrade: updatePackage,
+  powers: listAgents,
+
+  // Legacy aliases kept for backwards compatibility.
+  init: initProject,
+  sync: syncProject,
+  update: updatePackage,
+  list: listAgents,
+  info: showInfo,
+};
+
+/**
+ * Main entry point — parses CLI arguments and routes to the handler.
+ */
+function main() {
+  const args = process.argv.slice(2);
+  let command = args[0] || 'help';
+
+  // Accept the conventional flag forms so `--help`/`--version` work like any CLI.
+  if (command === '--help' || command === '-h') command = 'help';
+  else if (command === '--version' || command === '-v') command = 'version';
+
+  if (commands[command]) {
+    commands[command](args.slice(1));
+  } else {
+    console.error(`Unknown command: ${command}`);
+    showHelp();
+    process.exit(1);
+  }
+}
+
+function showHelp() {
+  console.log(`
+BI Agent Superpowers v${VERSION}
+================================
+
+Open-source toolkit for Power BI Desktop development across 5 AI coding agents:
+Claude Code · GitHub Copilot · Codex · Gemini CLI · Kilo Code.
+
+Quick Start:
+  super install --all --yes  # Install skills + MCPs user-level for all agents
+  super powers               # List the skills and MCPs available
+
+Usage:
+  super <command> [options]
+
+Primary commands:
+  install                Install ${TOTAL_SKILL_COUNT || 'the'} skills + 2 MCPs user-level across your AI agents
+  uninstall              Remove the skills + 2 MCPs from your AI agents
+  kickoff [path]         Optional: generate a repo-local Claude Code plugin
+  recharge [path]        Optional: regenerate an existing repo-local Claude Code plugin
+  create-from-template   Scaffold a new PBIP project from templates/<name>/ into pbip-files/
+  build-desktop          Build the .mcpb extension for Claude Desktop
+  mcp-setup              Refresh MCP config for an existing Claude Code local plugin
+  powers                 List available skills and MCPs
+  smoke-test             Run the live base-template smoke test
+  upgrade                Update to the latest version on npm
+  autoupdate <on|off>    Toggle silent self-update on session start (Claude Code)
+  about                  Show installation info
+  help                   Show this help
+
+Developer tools:
+  checkup [file]    Lint/validate skill source files
+  scan              Diff between source skills and generated plugin
+  sentinel          Watch skill sources and auto-regenerate
+  validate-cases    List, print, or live-run validation playbooks
+  validate-projects Validate public fixtures + local private project references
+
+Options:
+  --dry-run         Preview changes without writing files (kickoff, recharge)
+
+Examples:
+  super install                    # Interactive installer for all agents
+  super install --all --yes        # Non-interactive install for every agent
+  super install -a codex           # Install user-level skills + MCPs for Codex
+  super install -a claude-code     # Install only for Claude Code
+  super kickoff                    # Claude Code only: create local plugin files
+  super kickoff ./my-project       # Claude Code only: initialize in a repo
+  super kickoff --dry-run          # Preview local Claude Code plugin files
+  super recharge                   # Regenerate existing local Claude Code plugin
+  super build-desktop              # Build .mcpb for Claude Desktop
+  super build-desktop --output dist
+  super mcp-setup                  # Existing local Claude Code plugin only
+  super smoke-test                 # Run the live Desktop smoke test directly
+  super validate-cases             # List the repo playbooks or print one playbook
+  super validate-cases --case base-template-smoke-test --live  # Run the live Desktop smoke test
+  super validate-projects          # Developer QA against validation/ descriptors
+  super create-from-template --list                                          # List bundled templates
+  super create-from-template --template base-template --name bi-personal     # Scaffold from base template
+  super create-from-template --template base-template --name bi-personal --dry-run # Preview only
+
+Open source — MIT licensed.
+Documentation: https://bi-superpowers.dev
+`);
+}
+
+function showVersion() {
+  console.log(`BI Agent Superpowers v${VERSION}`);
+}
+
+function showInfo() {
+  const skillCount = getSkillFiles().length;
+  const aiToolsList = Object.entries(AI_TOOLS)
+    .map(([, v]) => `  - ${v.name}`)
+    .join('\n');
+
+  console.log(`
+BI Agent Superpowers — Installation Info
+========================================
+
+Version:        ${VERSION}
+Author:         Lucas Sanchez (@luquimbo)
+Package dir:    ${PACKAGE_DIR}
+Skills:         ${skillCount} available
+License:        MIT (open source)
+
+Supported AI agents:
+  - Claude Code        (native plugin + MCP)
+  - GitHub Copilot     (agent skills + MCP)
+  - Codex (OpenAI)     (agent skills + MCP)
+  - Gemini CLI         (agent skills + MCP)
+  - Kilo Code          (agent skills + MCP)
+
+Plugin generators:
+${aiToolsList}
+
+GitHub: https://github.com/luquimbo/bi-superpowers
+`);
+}
+
+// ============================================
+// SKILL FILE MANAGEMENT
+// ============================================
+
+/**
+ * Load all skill source files from the package.
+ * @returns {Array<{name: string, path: string, content: string}>}
+ */
+function getSkillFiles() {
+  return loadSkills({ packageDir: PACKAGE_DIR });
+}
+
+/**
+ * Extract lightweight metadata (title, triggers, identity) from a skill's
+ * markdown content. Delegates to the generators module when available.
+ */
+function parseSkillMetadata(content) {
+  if (generators && generators.parseSkillMetadata) {
+    return generators.parseSkillMetadata(content);
+  }
+  // Minimal fallback when the module isn't loaded yet.
+  const metadata = { title: '', triggers: [], identity: '' };
+  const titleMatch = content.match(/^#\s+(.+)/m);
+  if (titleMatch) metadata.title = titleMatch[1];
+  return metadata;
+}
+
+// ============================================
+// PROJECT INITIALIZATION (kickoff / recharge)
+// ============================================
+
+/**
+ * `super kickoff` — generate an optional local Claude Code plugin in the target directory.
+ *
+ * What it does:
+ *  1. Generates .claude-plugin/, .mcp.json, commands/, skills/ in the target.
+ *  2. Writes .bi-superpowers.json tracking tool selections.
+ *  3. Copies a default config.json template if none exists yet.
+ *
+ * Supports --dry-run to preview without writing files.
+ *
+ * @param {string[]} args - CLI arguments (first positional = target dir)
+ */
+async function initProject(args) {
+  const dryRun = hasDryRunFlag(args);
+  const cleanArgs = removeDryRunFlag(args);
+  const targetDir = cleanArgs[0] ? path.resolve(cleanArgs[0]) : process.cwd();
+
+  const skills = getSkillFiles();
+
+  console.log(`
+BI Agent Superpowers v${VERSION}
+================================
+Claude Code local plugin setup
+
+Initializing in: ${targetDir}
+Skills available: ${skills.length}
+
+This is not the multi-agent install path. For Codex, GitHub Copilot,
+Gemini CLI, Kilo Code, and user-level Claude Code installs, run:
+
+  super install --all --yes
+
+kickoff writes repo-local Claude Code plugin files only.
+`);
+
+  if (dryRun) {
+    if (tui) {
+      tui.dryRunNotice();
+    } else {
+      console.log('══════════════════════════════════════');
+      console.log('  DRY RUN MODE');
+      console.log('  No files will be created or modified');
+      console.log('══════════════════════════════════════\n');
+    }
+  }
+
+  const selectedTools = [...DEFAULT_TOOLS];
+
+  console.log('Plugin output:');
+  console.log('  • .claude-plugin/plugin.json');
+  console.log('  • .mcp.json');
+  console.log(`  • commands/ (${COMMAND_COUNT} slash commands)`);
+  console.log(`  • skills/ (${TOTAL_SKILL_COUNT} SKILL.md files)\n`);
+
+  if (dryRun) {
+    console.log('[DRY RUN] Would create the following files:\n');
+    previewGeneration(targetDir, selectedTools, skills);
+    previewProjectConfigJson(targetDir);
+    console.log('\nRun without --dry-run to apply changes.');
+    return;
+  }
+
+  saveToolConfig(targetDir, selectedTools);
+  ensureProjectConfigJson(targetDir);
+
+  console.log('');
+  for (const tool of selectedTools) {
+    await generateForTool(tool, targetDir, skills);
+  }
+
+  showCompletionMessage(targetDir, selectedTools, skills.length);
+}
+
+/**
+ * `super recharge` — regenerate an existing local Claude Code plugin without prompts.
+ *
+ * Re-reads the saved tool preferences from .bi-superpowers.json (or falls
+ * back to the default toolset) and regenerates everything. Useful after:
+ *  - editing files in src/content/skills/
+ *  - bumping the package version
+ *  - adding new supported tools
+ *
+ * @param {string[]} args - CLI arguments (first positional = target dir)
+ */
+async function syncProject(args) {
+  const dryRun = hasDryRunFlag(args);
+  const cleanArgs = removeDryRunFlag(args);
+  const targetDir = cleanArgs[0] ? path.resolve(cleanArgs[0]) : process.cwd();
+
+  const skills = getSkillFiles();
+
+  console.log(`
+BI Agent Superpowers — Sync
+===========================
+Regenerating configs from ${skills.length} skills...
+`);
+
+  if (dryRun) {
+    if (tui) {
+      tui.dryRunNotice();
+    } else {
+      console.log('══════════════════════════════════════');
+      console.log('  DRY RUN MODE');
+      console.log('  No files will be created or modified');
+      console.log('══════════════════════════════════════\n');
+    }
+  }
+
+  if (!hasProjectLocalPlugin(targetDir)) {
+    console.log(`
+This repo does not contain a local Claude Code plugin generated by super kickoff.
+
+For Codex, GitHub Copilot, Gemini CLI, Kilo Code, and user-level Claude Code
+installs, refresh the user-level install instead:
+
+  super install --all --yes
+
+If you intentionally want repo-local Claude Code plugin files, run:
+
+  super kickoff
+`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const config = loadToolConfig(targetDir);
+  const selectedTools = ensurePluginTool(config.tools || [...DEFAULT_TOOLS]);
+
+  if (dryRun) {
+    console.log('[DRY RUN] Would regenerate the following files:\n');
+    previewGeneration(targetDir, selectedTools, skills);
+    console.log('\nRun without --dry-run to apply changes.');
+    return;
+  }
+
+  for (const tool of selectedTools) {
+    await generateForTool(tool, targetDir, skills);
+  }
+
+  console.log(`
+Done. Plugin regenerated for: ${selectedTools.map((t) => AI_TOOLS[t].name).join(', ')}
+
+If you modified skills in src/content/skills/, your Claude Code plugin is now up to date.
+
+Tip: run 'super build-desktop' to rebuild the Claude Desktop MCPB extension.
+`);
+}
+
+/**
+ * Delegate to the generators module to preview what would be written.
+ */
+function previewGeneration(targetDir, tools, skills) {
+  if (generators) {
+    generators.previewGeneration(targetDir, tools, skills, CONFIG_FILE);
+  }
+}
+
+/**
+ * Ensure the tool list always includes the Claude Code plugin as the
+ * primary target. Deduplicates and preserves order.
+ */
+function ensurePluginTool(tools = []) {
+  const normalized = Array.from(new Set((tools || []).filter(Boolean)));
+  if (!normalized.includes('claude-plugin')) {
+    normalized.unshift('claude-plugin');
+  }
+  return normalized;
+}
+
+/**
+ * Build the options object passed into individual generators.
+ * `library/` is no longer shipped by this package. Keep local project
+ * library references unchanged only when the target repo provides them.
+ */
+function getGenerationOptions(targetDir) {
+  const usePluginRootLauncher = path.resolve(targetDir) === PACKAGE_DIR;
+  const libraryPrefix = fs.existsSync(path.join(targetDir, 'library')) ? 'library' : null;
+
+  return {
+    packageDir: PACKAGE_DIR,
+    version: VERSION,
+    usePluginRootLauncher,
+    libraryPrefix,
+  };
+}
+
+/**
+ * Write .bi-superpowers.json with the current tool selection and metadata.
+ */
+function saveToolConfig(targetDir, tools) {
+  const configPath = path.join(targetDir, CONFIG_FILE);
+  const normalizedTools = ensurePluginTool(tools);
+  const config = {
+    tools: normalizedTools,
+    plugin: {
+      name: 'bi-superpowers',
+      enabled: true,
+    },
+    version: VERSION,
+    lastSync: new Date().toISOString(),
+  };
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+}
+
+/**
+ * Log what config.json the kickoff would create (dry-run only).
+ */
+function previewProjectConfigJson(targetDir) {
+  const projectConfigPath = path.join(targetDir, 'config.json');
+  if (fs.existsSync(projectConfigPath)) {
+    return;
+  }
+  if (tui) {
+    tui.info(`Would create: ${tui.formatPath(projectConfigPath)}`);
+  } else {
+    console.log(`[DRY RUN] Would create: ${projectConfigPath}`);
+  }
+}
+
+/**
+ * Copy the package's config.json template into the target directory
+ * unless one already exists there.
+ * @returns {{created: boolean, path: string, reason?: string, error?: string}}
+ */
+function ensureProjectConfigJson(targetDir) {
+  const projectConfigPath = path.join(targetDir, 'config.json');
+  if (fs.existsSync(projectConfigPath)) {
+    return { created: false, path: projectConfigPath, reason: 'already-exists' };
+  }
+
+  const templatePath = path.join(PACKAGE_DIR, 'config.json');
+  if (!fs.existsSync(templatePath)) {
+    if (process.env.DEBUG === 'true') {
+      console.error(`[DEBUG] Missing config.json template at: ${templatePath}`);
+    }
+    return { created: false, path: projectConfigPath, reason: 'template-missing' };
+  }
+
+  try {
+    fs.copyFileSync(templatePath, projectConfigPath);
+    return { created: true, path: projectConfigPath };
+  } catch (e) {
+    if (process.env.DEBUG === 'true') {
+      console.error(`[DEBUG] Failed to create config.json: ${e.message}`);
+    }
+    return { created: false, path: projectConfigPath, reason: 'copy-failed', error: e.message };
+  }
+}
+
+/**
+ * Load the previously saved tool selection from .bi-superpowers.json.
+ * Falls back to the default toolset if the file is missing or invalid.
+ */
+function loadToolConfig(targetDir) {
+  const configPath = path.join(targetDir, CONFIG_FILE);
+  if (fs.existsSync(configPath)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      config.tools = ensurePluginTool(config.tools || []);
+      if (!config.plugin) {
+        config.plugin = { name: 'bi-superpowers', enabled: true };
+      }
+      return config;
+    } catch (_) {
+      return {};
+    }
+  }
+  return {
+    tools: [...DEFAULT_TOOLS],
+    plugin: { name: 'bi-superpowers', enabled: true },
+  };
+}
+
+function hasProjectLocalPlugin(targetDir) {
+  return (
+    fs.existsSync(path.join(targetDir, CONFIG_FILE)) ||
+    fs.existsSync(path.join(targetDir, '.claude-plugin', 'plugin.json'))
+  );
+}
+
+/**
+ * Dispatch to the tool-specific generator.
+ */
+async function generateForTool(tool, targetDir, skills) {
+  if (generators) {
+    await generators.generateForTool(tool, targetDir, skills, getGenerationOptions(targetDir));
+  }
+}
+
+function showCompletionMessage(targetDir, tools, skillCount) {
+  console.log(`
+════════════════════════════════════════════════════════════
+  BI Agent Superpowers configured successfully!
+════════════════════════════════════════════════════════════
+
+  Skills:     ${skillCount} skills generated
+
+  Note: this is a repo-local Claude Code plugin only.
+  Codex, GitHub Copilot, Gemini CLI, Kilo Code, and user-level Claude Code
+  installs use: super install --all --yes
+
+────────────────────────────────────────────────────────────
+  CLAUDE CODE
+────────────────────────────────────────────────────────────
+
+  Plugin files:
+    ${path.join(targetDir, '.claude-plugin', 'plugin.json')}
+    ${path.join(targetDir, '.mcp.json')}
+    ${path.join(targetDir, 'commands')}/  (${COMMAND_COUNT} slash commands)
+    ${path.join(targetDir, 'skills')}/    (${skillCount} SKILL.md)
+
+  To run with Claude Code:
+
+    claude --plugin-dir ${targetDir}
+
+────────────────────────────────────────────────────────────
+  CLAUDE DESKTOP
+────────────────────────────────────────────────────────────
+
+  To build the Desktop extension:
+
+    super build-desktop --output dist
+
+  Then double-click dist/bi-superpowers.mcpb to install.
+
+────────────────────────────────────────────────────────────
+
+  Regenerate after edits:  super recharge
+
+════════════════════════════════════════════════════════════
+`);
+}
+
+/**
+ * Detect the package manager the user ran from the npm_config_user_agent.
+ * Returns the pm name ('npm', 'pnpm', 'yarn', 'bun') and the install command
+ * string appropriate for a global install to @latest.
+ *
+ * Exported (via module.exports) so tests can exercise the detection without
+ * spawning a real install.
+ */
+function getUpgradeCommand(userAgent) {
+  const agent = userAgent || '';
+  let pm = 'npm';
+  if (agent.includes('pnpm')) pm = 'pnpm';
+  else if (agent.includes('yarn')) pm = 'yarn';
+  else if (agent.includes('bun')) pm = 'bun';
+
+  const cmd =
+    pm === 'yarn'
+      ? `yarn global add ${PACKAGE_NAME}@latest`
+      : `${pm} install -g ${PACKAGE_NAME}@latest`;
+
+  return { pm, cmd };
+}
+
+/**
+ * `super upgrade` — reinstall the package at the latest version.
+ *
+ * After the reinstall, prints a "next steps" block with the refresh paths
+ * for marketplace installs, user-profile installs, and project-local
+ * plugins generated by `super kickoff`, so users know how to propagate
+ * the new skills into their agents. We
+ * intentionally don't auto-chain into `super install`:
+ *   - Claude Code users who installed via the plugin marketplace refresh
+ *     from inside Claude Code (`/plugin update bi-superpowers`), they don't
+ *     need `super install`.
+ *   - npm users want to be able to opt out of re-propagation (e.g. testing
+ *     a version before rolling it across all agents).
+ */
+/**
+ * Wipe ~/.bi-superpowers/update-state.json after a successful upgrade so
+ * the new version starts with a clean cache (no stale snooze TTL, no
+ * cached "latest" from the previous version). Best-effort: any failure
+ * is swallowed — the reset is a convenience, not a correctness gate.
+ *
+ * Separate function + exported so tests can exercise it without spawning
+ * a real `super upgrade`.
+ */
+function resetUpdateCheckStateAfterUpgrade(homeDir) {
+  try {
+    const { resetState } = require('./commands/update-check');
+    resetState(path.join(homeDir, '.bi-superpowers'));
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function getUpgradeRefreshSteps() {
+  return [
+    {
+      label: 'Claude Code (installed via marketplace):',
+      command: '/plugin update bi-superpowers',
+    },
+    {
+      label: 'Skills installed in your user profile (npm + super install):',
+      command: 'super install --all --yes',
+    },
+    {
+      label:
+        'Project-local Claude Code plugin (run inside each repo where you used super kickoff):',
+      command: 'super recharge',
+    },
+  ];
+}
+
+function updatePackage() {
+  console.log(`Updating ${PACKAGE_NAME}...\n`);
+
+  try {
+    const { cmd } = getUpgradeCommand(process.env.npm_config_user_agent);
+    console.log(`Running: ${cmd}\n`);
+    execSync(cmd, { stdio: 'inherit' });
+    console.log('\n✓ CLI upgraded.');
+
+    // Clear the update-check cache + snooze state so the newly-installed
+    // version gets a fresh read on next skill invocation.
+    resetUpdateCheckStateAfterUpgrade(require('os').homedir());
+
+    console.log('\nNext step — refresh the skills + MCPs in your agents:\n');
+    for (const step of getUpgradeRefreshSteps()) {
+      console.log(`  ${step.label}`);
+      console.log(`    ${step.command}`);
+      console.log('');
+    }
+    console.log(
+      'If you only wanted the CLI updated (e.g. developing locally), you can skip the above.'
+    );
+  } catch (error) {
+    console.error('Update failed:', error.message);
+    console.log(`\nTry manually: npm install -g ${PACKAGE_NAME}@latest`);
+    process.exit(1);
+  }
+}
+
+/**
+ * `super powers` — list the available skills (and their titles).
+ */
+function listAgents() {
+  const skills = getSkillFiles();
+
+  console.log(`
+BI Agent Superpowers — Skills
+=============================
+Single Source of Truth: ${skills.length} skills (open source)
+`);
+
+  console.log('Skills:');
+  for (const skill of skills) {
+    const meta = parseSkillMetadata(skill.content);
+    console.log(`  /${skill.name.padEnd(20)} ${meta.title || ''}`);
+  }
+  console.log('');
+
+  console.log('Supported AI tools:');
+  Object.entries(AI_TOOLS).forEach(([, cfg]) => {
+    console.log(`  • ${cfg.name}`);
+  });
+  console.log('');
+
+  console.log("Run 'super recharge' to regenerate configs after editing skills.");
+}
+
+// ============================================
+// COMMAND WRAPPERS
+// ============================================
+
+/**
+ * Shared config object passed into every command module.
+ */
+function getCommandConfig() {
+  return {
+    skillsDir: SKILLS_DIR,
+    packageDir: PACKAGE_DIR,
+    version: VERSION,
+  };
+}
+
+/**
+ * Factory that wraps a command module with a consistent "missing module"
+ * error so every non-core command fails the same way during `npm install`.
+ */
+function createCommandWrapper(commandModule, commandName) {
+  return (args) => {
+    if (!commandModule) {
+      console.error(`${commandName} command not available. Try reinstalling the package.`);
+      process.exit(1);
+    }
+    commandModule(args, getCommandConfig());
+  };
+}
+
+// Wrapper instances — created after createCommandWrapper is defined.
+const runLint = createCommandWrapper(lintCommand, 'Lint');
+const runDiff = createCommandWrapper(diffCommand, 'Diff');
+const runMcpSetup = createCommandWrapper(mcpSetupCommand, 'MCP setup');
+const runBuildDesktop = createCommandWrapper(buildDesktopCommand, 'Build Desktop');
+const runInstall = createCommandWrapper(installCommand, 'Install');
+const runUninstall = createCommandWrapper(uninstallCommand, 'Uninstall');
+const runAutoupdate = createCommandWrapper(autoupdateCommand, 'Autoupdate');
+const runValidateCases = createCommandWrapper(validateCasesCommand, 'Validate cases');
+const runValidateProjects = createCommandWrapper(validateProjectsCommand, 'Validate projects');
+const runSmokeTest = createCommandWrapper(smokeTestCommand, 'Smoke test');
+const runCreateFromTemplate = createCommandWrapper(
+  createFromTemplateCommand,
+  'Create from template'
+);
+
+// Register wrapper-based commands into the command map (phase 2).
+commands.install = runInstall;
+commands.uninstall = runUninstall;
+commands.autoupdate = runAutoupdate;
+commands.checkup = runLint;
+commands.scan = runDiff;
+commands.sentinel = runWatch;
+commands['mcp-setup'] = runMcpSetup;
+commands.mcp = runMcpSetup;
+commands['build-desktop'] = runBuildDesktop;
+commands['smoke-test'] = runSmokeTest;
+commands['validate-cases'] = runValidateCases;
+commands['validate-projects'] = runValidateProjects;
+commands['create-from-template'] = runCreateFromTemplate;
+commands.lint = runLint;
+commands.diff = runDiff;
+commands.watch = runWatch;
+
+/**
+ * `super sentinel` — watch skill sources and auto-regenerate the plugin.
+ * Needs extra context (a reference to the sync function) so it has its
+ * own wrapper instead of using createCommandWrapper.
+ */
+function runWatch(args) {
+  if (!watchCommand) {
+    console.error('Watch command not available. Try reinstalling the package.');
+    process.exit(1);
+  }
+
+  watchCommand(args, getCommandConfig(), createWatchCliModule());
+}
+
+/**
+ * Build the tiny adapter used by `super sentinel`.
+ * It intentionally delegates through generateForTool(), the same path as
+ * kickoff/recharge, so regenerated plugin files keep the real package version,
+ * library prefix, and MCP launcher mode.
+ *
+ * @param {Object} [deps] - Test seams
+ * @param {Function} [deps.getSkillFilesFn] - Skill loader
+ * @param {Function} [deps.generateForToolFn] - Tool generator
+ * @returns {{syncProjectInternal: Function}} Watch command adapter
+ */
+function createWatchCliModule(deps = {}) {
+  const getSkillFilesFn = deps.getSkillFilesFn || getSkillFiles;
+  const generateForToolFn = deps.generateForToolFn || generateForTool;
+
+  return {
+    syncProjectInternal: async (targetDir, tools) => {
+      const skills = getSkillFilesFn();
+      for (const tool of tools) {
+        await generateForToolFn(tool, targetDir, skills);
+      }
+    },
+  };
+}
+
+/**
+ * Check if --dry-run (or -n) is present in the argument list.
+ */
+function hasDryRunFlag(args) {
+  return args.includes('--dry-run') || args.includes('-n');
+}
+
+/**
+ * Strip the --dry-run / -n flag from the argument list.
+ */
+function removeDryRunFlag(args) {
+  return args.filter((a) => a !== '--dry-run' && a !== '-n');
+}
+
+// ============================================
+// EXPORT FOR INTERNAL USE
+// ============================================
+
+module.exports = {
+  getSkillFiles,
+  loadToolConfig,
+  saveToolConfig,
+  getUpgradeCommand,
+  getUpgradeRefreshSteps,
+  resetUpdateCheckStateAfterUpgrade,
+  createWatchCliModule,
+  getGenerationOptions,
+  AI_TOOLS,
+  SKILLS_DIR,
+  VERSION,
+};
+
+// Only run main() when invoked as the binary (not when required from tests).
+if (require.main === module) {
+  main();
+}