@luquimbo/bi-superpowers 1.0.0

package/bin/cli.js

@@ -0,0 +1,1064 @@
+#!/usr/bin/env node
+
+/**
+ * BI Agent Superpowers - Command Line Interface
+ * ==============================================
+ *
+ * This is the main entry point for the BI Agent Superpowers CLI tool.
+ * It provides commands to initialize, configure, and manage AI-powered
+ * assistance for Power BI, Fabric, and Excel development.
+ *
+ * Architecture:
+ * - Single Source of Truth: Skills are defined ONCE in src/content/skills/
+ *   and generated for the Claude Code plugin.
+ * - Supports: Claude Code, 1code.dev, Claude Desktop (via MCPB).
+ *
+ * License System:
+ * - Premium content requires activation via `bi-superpowers unlock`
+ * - License validation happens against https://acadevor.com API
+ * - Content is cached locally in ~/.bi-superpowers/
+ *
+ * @module cli
+ * @author Lucas Sanchez (@luquimbo)
+ * @license MIT
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const readline = require('readline');
+const os = require('os');
+const { loadSkills } = require('./lib/skills');
+
+// Import lib modules (extracted from cli.js for better organization)
+let licensing, generators;
+try {
+  licensing = require('./lib/licensing');
+  generators = require('./lib/generators');
+} catch (e) {
+  // Modules may not be available during npm install phase
+}
+
+// Import command modules - these provide the xray, checkup, scan, sentinel, and mcp-setup commands
+// Wrapped in try-catch because they may not be available during initial npm install
+let searchCommand, lintCommand, diffCommand, watchCommand, mcpSetupCommand, tui;
+let setupCommand, addCommand, pullCommand, pushCommand, syncProfileCommand, syncSourceCommand;
+let changelogCommand, buildDesktopCommand;
+try {
+  searchCommand = require('./commands/search'); // Fuzzy search across library content
+  lintCommand = require('./commands/lint'); // Skill file validation
+  diffCommand = require('./commands/diff'); // Compare source vs generated configs
+  watchCommand = require('./commands/watch'); // Auto-regenerate on file changes
+  mcpSetupCommand = require('./commands/mcp-setup'); // MCP server configuration
+  tui = require('./utils/tui'); // Terminal UI helpers (colors, tables, etc.)
+
+  // Repo multi-project commands (v3)
+  setupCommand = require('./commands/setup'); // Onboarding wizard for bi-repo
+  addCommand = require('./commands/add'); // Add project to repo
+  pullCommand = require('./commands/pull'); // Pull changes from original file
+  pushCommand = require('./commands/push'); // Push changes to original file
+  syncProfileCommand = require('./commands/sync-profile'); // Sync snippets to profile
+  syncSourceCommand = require('./commands/sync-source'); // Bidirectional sync
+  changelogCommand = require('./commands/changelog'); // Generate changelog from Git
+  buildDesktopCommand = require('./commands/build-desktop'); // Build MCPB for Claude Desktop
+} catch (e) {
+  // Silent fail - commands may not be available during npm install phase
+  // This is expected behavior, not an error condition
+}
+
+// ============================================
+// CONFIGURATION CONSTANTS
+// ============================================
+
+/** Package version from package.json */
+const VERSION = require('../package.json').version;
+
+/** Dynamic skill/command counts from the plugin generator (avoids hardcoding) */
+let COMMAND_COUNT = 11;
+let TOTAL_SKILL_COUNT = 24;
+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 to defaults during npm install phase
+}
+
+/** Directory where the npm package is installed */
+const PACKAGE_DIR = path.dirname(__dirname);
+
+/** Directory for cached premium content (skills, snippets, themes) */
+const CONTENT_CACHE_DIR = path.join(os.homedir(), '.bi-superpowers');
+
+// File paths - premium content is downloaded to CONTENT_CACHE_DIR
+/** Directory containing skill definition files (.md) */
+const SKILLS_DIR = path.join(CONTENT_CACHE_DIR, 'src', 'content', 'skills');
+
+/** Directory containing code snippets, templates, and themes */
+const LIBRARY_DIR = path.join(CONTENT_CACHE_DIR, 'library');
+
+/** Project-local config file name (stores tool selections) */
+const CONFIG_FILE = '.bi-superpowers.json';
+
+/** Symlink name created in projects pointing to content cache */
+const SYMLINK_NAME = '.bi-superpowers';
+
+/** npm package name for update commands */
+const PACKAGE_NAME = '@luquimbo/bi-superpowers';
+const DEFAULT_TOOLS = ['claude-plugin'];
+
+/**
+ * AI Tools Configuration - uses generators from lib/generators module
+ * Falls back to empty object if module not loaded
+ */
+const AI_TOOLS = generators ? generators.AI_TOOLS : {};
+
+/**
+ * Command Routing Map
+ *
+ * Maps CLI command names to their handler functions.
+ * Supports both branded names (kickoff, recharge) and legacy names (init, sync)
+ * for backward compatibility.
+ *
+ * Command Categories:
+ * - Core: Basic info commands (help, version, about, status)
+ * - Setup: Project initialization and configuration (kickoff, recharge, unlock, upgrade)
+ * - Developer: Advanced tools for content management (xray, checkup, scan, sentinel, powers)
+ * - Legacy: Old command names maintained for backward compatibility
+ */
+const commands = {
+  // Core commands - basic info and status
+  help: showHelp,
+  version: showVersion,
+  about: showInfo,
+  status: showLicenseStatus,
+
+  // Setup & sync - project configuration
+  kickoff: initProject, // Interactive project setup wizard
+  recharge: syncProject, // Regenerate AI tool configs from skills
+  unlock: activateLicense, // Activate license key
+  upgrade: updatePackage, // Update to latest npm version
+
+  // Developer tools - content management
+  xray: runSearch, // Fuzzy search library content
+  checkup: runLint, // Validate skill files
+  scan: runDiff, // Compare source vs generated
+  sentinel: runWatch, // Watch and auto-regenerate
+  powers: listAgents, // List available skills
+  'mcp-setup': runMcpSetup, // Configure MCP servers for AI tools
+  mcp: runMcpSetup, // Alias for mcp-setup
+  'build-desktop': runBuildDesktop, // Build MCPB extension for Claude Desktop
+
+  // Repo multi-project commands (v3)
+  setup: runSetup, // Onboarding wizard - creates bi-repo
+  add: runAdd, // Add project to bi-repo
+  pull: runPull, // Pull changes from original file to repo
+  push: runPush, // Push changes from repo to original file
+  'sync-source': runSyncSource, // Bidirectional sync with original file
+  'sync-profile': runSyncProfile, // Sync snippets to base profile
+  changelog: runChangelog, // Generate changelog from Git history
+
+  // Legacy aliases (backward compatibility with v2.0.x)
+  init: initProject,
+  sync: syncProject,
+  activate: activateLicense,
+  update: updatePackage,
+  search: runSearch,
+  lint: runLint,
+  diff: runDiff,
+  watch: runWatch,
+  list: listAgents,
+  info: showInfo,
+};
+
+/**
+ * Main entry point - parses CLI arguments and routes to appropriate command
+ */
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0] || 'help';
+
+  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}
+================================
+
+Claude Code plugin for Power BI, Fabric & Excel development.
+Works with: Claude Code, 1code.dev, Claude Desktop.
+
+Usage:
+  super <command> [options]
+
+Commands:
+  unlock            Activate your license key
+  kickoff [path]    Initialize the Claude Code plugin in your project
+  recharge [path]   Regenerate the plugin from source skills
+  build-desktop     Build .mcpb extension for Claude Desktop
+  powers            List available skills and resources
+  xray <query>      Search snippets and library content
+  checkup [file]    Validate skill files
+  scan              Show changes between source and generated configs
+  sentinel          Watch for changes and auto-regenerate
+  mcp-setup         Configure official Microsoft MCP servers
+  upgrade           Update to latest version
+  status          Show license status
+  about           Show installation info
+  help            Show this help
+
+Repo Multi-Proyecto (v3):
+  setup           Create your bi-repo for version control
+  add <file>      Add a .pbix/.xlsx project to the repo
+  pull [project]  Pull changes from original file to repo
+  push [project]  Push changes from repo to original file
+  sync-source     Bidirectional sync (detects which is newer)
+  sync-profile    Sync snippets to a base profile
+
+Options:
+  --dry-run       Preview changes without creating files (kickoff, recharge)
+
+Examples:
+  super unlock                   # Activate your license
+  super kickoff                  # Initialize plugin in current directory
+  super kickoff ./my-project     # Initialize in specific directory
+  super kickoff --dry-run        # Preview what would be created
+  super recharge                 # Regenerate plugin from source skills
+  super build-desktop            # Build .mcpb for Claude Desktop
+  super xray "YTD"               # Search for time intelligence patterns
+  super xray --category dax      # Search within a category
+  super checkup                  # Validate all skills
+  super mcp-setup                # Configure official Microsoft MCPs
+  super powers                   # Show available superpowers
+  claude --plugin-dir .          # Run Claude Code with the plugin
+
+Repo Multi-Proyecto:
+  super setup                    # Create your bi-repo (first time)
+  super add "Sales.pbix"         # Add project to repo
+  super pull                     # Pull changes from original
+  super push                     # Push changes to original
+  super sync-source              # Auto-detect and sync
+  super sync-profile             # Save snippets to profile
+
+Get your license at: https://acadevor.com/bi-superpowers
+Documentation: https://github.com/luquimbo/bi-superpowers
+`);
+}
+
+function showVersion() {
+  console.log(`BI Agent Superpowers v${VERSION}`);
+}
+
+function showInfo() {
+  const skillCount = getSkillFiles().length;
+  const license = loadLicense();
+  const licenseStatus = license ? `Active (${license.email})` : 'Not activated';
+  const contentStatus = isContentInstalled() ? `Installed (${skillCount} skills)` : 'Not installed';
+  const aiToolsList = Object.entries(AI_TOOLS)
+    .map(([_k, v]) => `  - ${v.name}`)
+    .join('\n');
+
+  console.log(`
+BI Agent Superpowers - Installation Info
+========================================
+
+Version:        ${VERSION}
+Author:         Lucas Sanchez (@luquimbo)
+Package dir:    ${PACKAGE_DIR}
+Content dir:    ${CONTENT_CACHE_DIR}
+License:        ${licenseStatus}
+Content:        ${contentStatus}
+
+Architecture:   Single Source of Truth
+                Skills defined once, generated for the Claude Code plugin
+
+Compatible with:
+  - Claude Code (plugin)
+  - 1code.dev (uses Claude Code SDK)
+  - Claude Desktop (via MCPB extension)
+
+Plugin Generators:
+${aiToolsList}
+
+GitHub: https://github.com/luquimbo/bi-superpowers
+`);
+}
+
+/**
+ * Creates a readline interface for interactive CLI prompts
+ * @returns {readline.Interface} Readline interface
+ */
+function createReadline() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+/**
+ * Promisified readline question
+ * @param {readline.Interface} rl - Readline interface
+ * @param {string} question - Question to display
+ * @returns {Promise<string>} User's trimmed answer
+ */
+function prompt(rl, question) {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => resolve(answer.trim()));
+  });
+}
+
+// ============================================
+// LICENSE MANAGEMENT
+// ============================================
+// These functions handle license storage, validation, and premium content downloads.
+// Licenses are stored in ~/.bi-superpowers-license as JSON.
+
+// License functions - delegated to lib/licensing module
+function loadLicense() {
+  return licensing ? licensing.loadLicense() : null;
+}
+
+function saveLicense(data) {
+  if (licensing) licensing.saveLicense(data);
+}
+
+// HTTP/download/extract functions - delegated to lib/licensing module
+function isContentInstalled() {
+  return licensing ? licensing.isContentInstalled() : false;
+}
+
+async function validateLicense(licenseKey) {
+  return licensing
+    ? licensing.validateLicense(licenseKey)
+    : { valid: false, error: 'Module not loaded' };
+}
+
+async function downloadPremiumContent(downloadUrl) {
+  return licensing ? licensing.downloadPremiumContent(downloadUrl) : false;
+}
+
+/**
+ * Show license status command handler
+ *
+ * Displays current license status including:
+ * - Whether a license is activated
+ * - Email and activation date if active
+ * - Instructions for activation if not active
+ */
+function showLicenseStatus() {
+  const license = loadLicense();
+
+  if (!license) {
+    console.log(`
+License Status: NOT ACTIVATED
+
+Run 'bi-superpowers unlock' to activate your license.
+Get your license at: https://acadevor.com/bi-superpowers
+`);
+    return;
+  }
+
+  console.log(`
+License Status: ACTIVE ✓
+
+Email:        ${license.email}
+License:      ${license.license.substring(0, 8)}...
+Activated:    ${license.activatedAt || 'Unknown'}
+
+Run 'bi-superpowers unlock' to re-activate or change license.
+`);
+}
+
+/**
+ * Activate license command handler (super unlock)
+ *
+ * Interactive command that:
+ * 1. Prompts user for their license key
+ * 2. Validates the key against the API
+ * 3. Downloads premium content if validation succeeds
+ * 4. Saves the license locally for future sessions
+ *
+ * This is typically the first command users run after installation.
+ */
+async function activateLicense() {
+  console.log(`
+BI Agent Superpowers - License Activation
+=========================================
+`);
+
+  const existingLicense = loadLicense();
+  if (existingLicense) {
+    console.log(
+      `Current license: ${existingLicense.license.substring(0, 8)}... (${existingLicense.email})`
+    );
+    console.log('');
+  }
+
+  const rl = createReadline();
+
+  try {
+    const licenseKey = await prompt(rl, 'Enter your license key: ');
+
+    if (!licenseKey) {
+      console.log('\nNo license key provided.');
+      process.exit(1);
+    }
+
+    console.log('\nValidating license...');
+
+    const result = await validateLicense(licenseKey);
+
+    if (!result.valid) {
+      console.log(`\n✗ License invalid: ${result.error || 'Unknown error'}`);
+      console.log('\nGet your license at: https://acadevor.com/bi-superpowers');
+      process.exit(1);
+    }
+
+    console.log('\n✓ License validated!');
+    console.log(`  Email: ${result.email}`);
+    if (result.name) {
+      console.log(`  Name: ${result.name}`);
+    }
+
+    // Download premium content
+    console.log('');
+    if (result.downloadUrl) {
+      const downloaded = await downloadPremiumContent(result.downloadUrl);
+      if (!downloaded) {
+        console.log('\n⚠ Content download failed. You can retry with "bi-superpowers unlock"');
+      }
+    }
+
+    // Save license
+    saveLicense({
+      license: licenseKey,
+      email: result.email,
+      name: result.name,
+      activatedAt: new Date().toISOString(),
+      contentVersion: VERSION,
+    });
+
+    console.log(`
+════════════════════════════════════════════════════════════
+  License activated successfully!
+════════════════════════════════════════════════════════════
+
+  You can now run:
+
+    super kickoff          # Initialize in current project
+    super powers           # See available skills
+
+════════════════════════════════════════════════════════════
+`);
+  } finally {
+    rl.close();
+  }
+}
+
+// requireLicense - delegated to lib/licensing module
+async function requireLicense() {
+  return licensing ? licensing.requireLicense(VERSION) : process.exit(1);
+}
+
+// ============================================
+// SKILL FILE MANAGEMENT
+// ============================================
+// Functions for reading and parsing skill definition files.
+// Skills are markdown files in src/content/skills/ that define
+// AI assistant behaviors, triggers, and code patterns.
+
+/**
+ * Get all skill files from the source directory
+ *
+ * Reads all .md files from the skills directory and returns their metadata.
+ * Each skill file contains:
+ * - Trigger keywords that activate the skill
+ * - Identity/role description for the AI
+ * - Mandatory rules and constraints
+ * - Code examples and patterns
+ *
+ * @returns {Array<{name: string, path: string, content: string}>} Array of skill objects
+ */
+function getSkillFiles() {
+  return loadSkills({
+    packageDir: PACKAGE_DIR,
+    contentCacheDir: CONTENT_CACHE_DIR,
+  });
+}
+
+/**
+ * Extract skill metadata from markdown content
+ * Delegates to generators module if available
+ */
+function parseSkillMetadata(content) {
+  if (generators && generators.parseSkillMetadata) {
+    return generators.parseSkillMetadata(content);
+  }
+  // Fallback for when module not loaded
+  const metadata = { title: '', triggers: [], identity: '' };
+  const titleMatch = content.match(/^#\s+(.+)/m);
+  if (titleMatch) metadata.title = titleMatch[1];
+  return metadata;
+}
+
+// ============================================
+// PROJECT INITIALIZATION
+// ============================================
+// Functions for setting up BI Agent Superpowers in a user's project.
+// This involves generating tool-specific config files and saving preferences.
+
+/**
+ * Initialize project with interactive prompts (super kickoff)
+ *
+ * This is the main setup wizard that:
+ * 1. Validates the user's license
+ * 2. Prompts for which AI tools to configure
+ * 3. Generates config files for each selected tool
+ * 4. Creates a symlink to the content cache for easy access
+ * 5. Saves the selected tools to .bi-superpowers.json
+ *
+ * Supports --dry-run flag to preview changes without writing files.
+ *
+ * @param {string[]} args - Command line arguments
+ * @param {string} [args[0]] - Target directory (defaults to cwd)
+ */
+async function initProject(args) {
+  const dryRun = hasDryRunFlag(args);
+  const cleanArgs = removeDryRunFlag(args);
+  const targetDir = cleanArgs[0] ? path.resolve(cleanArgs[0]) : process.cwd();
+
+  // Require valid license
+  await requireLicense();
+
+  const skills = getSkillFiles();
+
+  console.log(`
+BI Agent Superpowers v${VERSION}
+================================
+Claude Code Plugin Setup
+
+Initializing in: ${targetDir}
+Skills available: ${skills.length}
+`);
+
+  // Show dry-run notice
+  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;
+  }
+
+  // Save selected tools to config
+  saveToolConfig(targetDir, selectedTools);
+
+  // Ensure project-level config.json exists (used as AI preferences/context)
+  ensureProjectConfigJson(targetDir);
+
+  // Create library symlink used by generated plugin files
+  createSymlink(targetDir);
+
+  // Generate configs for selected tools
+  console.log('');
+  for (const tool of selectedTools) {
+    await generateForTool(tool, targetDir, skills);
+  }
+
+  showCompletionMessage(targetDir, selectedTools, skills.length);
+}
+
+/**
+ * Sync project - regenerate configs without prompts (super recharge)
+ *
+ * Regenerates the Claude Code plugin and any configured legacy adapters.
+ * Uses the saved tool preferences from .bi-superpowers.json.
+ *
+ * Use this command after:
+ * - Editing skill files in src/content/skills/
+ * - Updating the package to a new version
+ * - Adding new AI tools to your project
+ *
+ * Supports --dry-run flag to preview changes without writing files.
+ *
+ * @param {string[]} args - Command line arguments
+ * @param {string} [args[0]] - Target directory (defaults to cwd)
+ */
+async function syncProject(args) {
+  const dryRun = hasDryRunFlag(args);
+  const cleanArgs = removeDryRunFlag(args);
+  const targetDir = cleanArgs[0] ? path.resolve(cleanArgs[0]) : process.cwd();
+
+  // Require valid license
+  await requireLicense();
+
+  const skills = getSkillFiles();
+
+  console.log(`
+BI Agent Superpowers - Sync
+===========================
+Regenerating configs from ${skills.length} skills...
+`);
+
+  // Show dry-run notice
+  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');
+    }
+  }
+
+  // Read saved config or default to plugin only
+  const config = loadToolConfig(targetDir);
+  const selectedTools = ensurePluginTool(config.tools || [...DEFAULT_TOOLS]);
+
+  if (dryRun) {
+    // Preview what would be regenerated
+    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 updated.
+
+Tip: Run 'super build-desktop' to rebuild the Claude Desktop extension.
+`);
+}
+
+/**
+ * Preview what files would be generated (for dry-run mode)
+ * Delegates to the generators module
+ */
+function previewGeneration(targetDir, tools, skills) {
+  if (generators) {
+    generators.previewGeneration(targetDir, tools, skills, CONFIG_FILE);
+  }
+}
+
+/**
+ * Save tool configuration to project directory
+ * @param {string} targetDir - Project directory path
+ * @param {string[]} tools - Array of selected AI tool IDs
+ */
+function ensurePluginTool(tools = []) {
+  const normalized = Array.from(new Set((tools || []).filter(Boolean)));
+  if (!normalized.includes('claude-plugin')) {
+    normalized.unshift('claude-plugin');
+  }
+  return normalized;
+}
+
+/**
+ * Resolve generation options for a target directory.
+ *
+ * @param {string} targetDir - Target project directory
+ * @returns {Object} Options passed into generators
+ */
+function getGenerationOptions(targetDir) {
+  const usePluginRootLauncher = path.resolve(targetDir) === PACKAGE_DIR;
+  const libraryPrefix = fs.existsSync(path.join(targetDir, 'library'))
+    ? 'library'
+    : `${SYMLINK_NAME}/library`;
+
+  return {
+    packageDir: PACKAGE_DIR,
+    version: VERSION,
+    usePluginRootLauncher,
+    libraryPrefix,
+  };
+}
+
+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,
+    },
+    legacyTools: normalizedTools.filter((tool) => tool !== 'claude-plugin'),
+    version: VERSION,
+    lastSync: new Date().toISOString(),
+  };
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+}
+
+/**
+ * Preview project-level config.json creation (for dry-run mode)
+ * This file is used by AI assistants as preferences/context, not by the CLI runtime.
+ * @param {string} targetDir - Project directory path
+ */
+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}`);
+  }
+}
+
+/**
+ * Ensure project-level config.json exists
+ * Copies the package template config.json into the project directory if missing.
+ * @param {string} targetDir - Project directory path
+ * @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 tool configuration from project directory
+ * @param {string} targetDir - Project directory path
+ * @returns {Object} Configuration object or empty object if not found
+ */
+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 || []);
+      config.legacyTools = config.tools.filter((tool) => tool !== 'claude-plugin');
+      if (!config.plugin) {
+        config.plugin = {
+          name: 'bi-superpowers',
+          enabled: true,
+        };
+      }
+      return config;
+    } catch (e) {
+      return {};
+    }
+  }
+  return {
+    tools: [...DEFAULT_TOOLS],
+    legacyTools: [],
+    plugin: {
+      name: 'bi-superpowers',
+      enabled: true,
+    },
+  };
+}
+
+/**
+ * Generate config for a specific AI tool
+ * Delegates to the tool-specific generator from lib/generators module
+ */
+async function generateForTool(tool, targetDir, skills) {
+  if (generators) {
+    await generators.generateForTool(tool, targetDir, skills, getGenerationOptions(targetDir));
+  }
+}
+
+/**
+ * Create symlink to content cache directory for easy access to library
+ */
+function createSymlink(targetDir) {
+  if (generators) {
+    generators.createSymlink(targetDir, CONTENT_CACHE_DIR, SYMLINK_NAME);
+  }
+}
+
+function showCompletionMessage(targetDir, tools, skillCount) {
+  console.log(`
+════════════════════════════════════════════════════════════
+  BI Agent Superpowers configured successfully!
+════════════════════════════════════════════════════════════
+
+  Skills:     ${skillCount} skills generated
+  Library:    ${LIBRARY_DIR}
+
+────────────────────────────────────────────────────────────
+  CLAUDE CODE / 1CODE.DEV
+────────────────────────────────────────────────────────────
+
+  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
+
+  Then double-click bi-superpowers.mcpb to install.
+
+────────────────────────────────────────────────────────────
+
+  Regenerate after changes:  super recharge
+  Free models (OpenRouter):  See docs/openrouter-free-models.md
+
+════════════════════════════════════════════════════════════
+`);
+}
+
+/**
+ * Update the package to the latest version using detected package manager
+ */
+function updatePackage() {
+  console.log(`Updating ${PACKAGE_NAME}...\n`);
+
+  try {
+    const userAgent = process.env.npm_config_user_agent || '';
+    let pm = 'npm';
+    if (userAgent.includes('pnpm')) pm = 'pnpm';
+    else if (userAgent.includes('yarn')) pm = 'yarn';
+    else if (userAgent.includes('bun')) pm = 'bun';
+
+    const cmd =
+      pm === 'yarn'
+        ? `yarn global add ${PACKAGE_NAME}@latest`
+        : `${pm} install -g ${PACKAGE_NAME}@latest`;
+
+    console.log(`Running: ${cmd}\n`);
+    execSync(cmd, { stdio: 'inherit' });
+    console.log('\n✓ Update complete!');
+  } catch (error) {
+    console.error('Update failed:', error.message);
+    console.log(`\nTry manually: npm install -g ${PACKAGE_NAME}@latest`);
+    process.exit(1);
+  }
+}
+
+function listAgents() {
+  const skills = getSkillFiles();
+  const license = loadLicense();
+  const contentInstalled = isContentInstalled();
+
+  console.log(`
+BI Agent Superpowers - Skills & Resources
+=========================================
+Single Source of Truth: ${skills.length} skills
+License: ${license ? `Active (${license.email})` : 'Not activated'}
+Content: ${contentInstalled ? 'Installed' : 'Not installed (run "bi-superpowers unlock")'}
+`);
+
+  if (!contentInstalled) {
+    console.log('⚠ Premium content not installed. Run "bi-superpowers unlock" first.\n');
+    return;
+  }
+
+  console.log('Skills (source content for the plugin and optional adapters):');
+  for (const skill of skills) {
+    const meta = parseSkillMetadata(skill.content);
+    console.log(`  /${skill.name.padEnd(20)} ${meta.title || ''}`);
+  }
+  console.log('');
+
+  // List snippets
+  const snippetsDir = path.join(LIBRARY_DIR, 'snippets');
+  if (fs.existsSync(snippetsDir)) {
+    console.log('Snippets:');
+    fs.readdirSync(snippetsDir).forEach((category) => {
+      const categoryPath = path.join(snippetsDir, category);
+      try {
+        if (fs.statSync(categoryPath).isDirectory()) {
+          const count = fs.readdirSync(categoryPath).filter((f) => f.endsWith('.md')).length;
+          console.log(`  📝 ${category} (${count} patterns)`);
+        }
+      } catch (e) {
+        // Skip directories that can't be read
+      }
+    });
+    console.log('');
+  }
+
+  // List themes
+  const themesDir = path.join(LIBRARY_DIR, 'themes', 'power-bi');
+  if (fs.existsSync(themesDir)) {
+    console.log('Themes:');
+    fs.readdirSync(themesDir).forEach((file) => {
+      if (file.endsWith('.json')) {
+        console.log(`  🎨 ${file.replace('.json', '')}`);
+      }
+    });
+    console.log('');
+  }
+
+  console.log('Supported AI Tools:');
+  Object.entries(AI_TOOLS).forEach(([, config]) => {
+    console.log(`  • ${config.name}`);
+  });
+  console.log('');
+
+  console.log("Run 'bi-superpowers recharge' to regenerate configs after editing skills.");
+}
+
+// ============================================
+// COMMAND WRAPPERS
+// ============================================
+
+/**
+ * Get configuration object for commands
+ */
+function getCommandConfig() {
+  return {
+    skillsDir: SKILLS_DIR,
+    libraryDir: LIBRARY_DIR,
+    contentCacheDir: CONTENT_CACHE_DIR,
+    packageDir: PACKAGE_DIR,
+    version: VERSION,
+  };
+}
+
+/**
+ * Create a command wrapper with error handling
+ * Factory pattern to reduce boilerplate in command handlers
+ *
+ * @param {Function|null} commandModule - The command module function
+ * @param {string} commandName - Display name for error messages
+ * @returns {Function} Wrapped command handler
+ */
+function createCommandWrapper(commandModule, commandName) {
+  return (args) => {
+    if (!commandModule) {
+      console.error(`${commandName} command not available. Try reinstalling the package.`);
+      process.exit(1);
+    }
+    commandModule(args, getCommandConfig());
+  };
+}
+
+// Command wrappers using factory pattern
+const runSearch = createCommandWrapper(searchCommand, 'Search');
+const runLint = createCommandWrapper(lintCommand, 'Lint');
+const runDiff = createCommandWrapper(diffCommand, 'Diff');
+const runMcpSetup = createCommandWrapper(mcpSetupCommand, 'MCP setup');
+const runSetup = createCommandWrapper(setupCommand, 'Setup');
+const runAdd = createCommandWrapper(addCommand, 'Add');
+const runPull = createCommandWrapper(pullCommand, 'Pull');
+const runPush = createCommandWrapper(pushCommand, 'Push');
+const runSyncSource = createCommandWrapper(syncSourceCommand, 'Sync-source');
+const runSyncProfile = createCommandWrapper(syncProfileCommand, 'Sync-profile');
+const runChangelog = createCommandWrapper(changelogCommand, 'Changelog');
+const runBuildDesktop = createCommandWrapper(buildDesktopCommand, 'Build Desktop');
+
+/**
+ * Run watch command (special case - needs additional context)
+ */
+function runWatch(args) {
+  if (!watchCommand) {
+    console.error('Watch command not available. Try reinstalling the package.');
+    process.exit(1);
+  }
+
+  // Create a reference to sync function for watch to use
+  const cliModule = {
+    syncProjectInternal: (targetDir, tools) => {
+      const skills = getSkillFiles();
+      for (const tool of tools) {
+        const config = AI_TOOLS[tool];
+        if (config && config.generate) {
+          config.generate(targetDir, skills, { packageDir: PACKAGE_DIR });
+        }
+      }
+    },
+  };
+
+  watchCommand(args, getCommandConfig(), cliModule);
+}
+
+/**
+ * Check if --dry-run flag is present in args
+ */
+function hasDryRunFlag(args) {
+  return args.includes('--dry-run') || args.includes('-n');
+}
+
+/**
+ * Remove --dry-run flag from args
+ */
+function removeDryRunFlag(args) {
+  return args.filter((a) => a !== '--dry-run' && a !== '-n');
+}
+
+// ============================================
+// EXPORT FOR INTERNAL USE
+// ============================================
+
+module.exports = {
+  getSkillFiles,
+  loadToolConfig,
+  saveToolConfig,
+  AI_TOOLS,
+  SKILLS_DIR,
+  LIBRARY_DIR,
+  CONTENT_CACHE_DIR,
+  VERSION,
+};
+
+main();