@luquimbo/bi-superpowers 1.1.3 → 1.2.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "bi-superpowers",
   "description": "Claude Code plugin for Power BI, Microsoft Fabric, and semantic model workflows powered by the official Microsoft MCP servers.",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "author": {
     "name": "Lucas Sanchez"
   }

package/bin/build-plugin.js

@@ -2,13 +2,57 @@
 
 /**
  * Build the repository-root Claude Code plugin artifacts.
+ *
+ * Genera los archivos del plugin desde las fuentes en src/content/skills/
+ * y valida que los outputs críticos hayan sido creados correctamente.
+ * Este script corre en el prepack de npm publish.
  */
 
+const fs = require('fs');
 const path = require('path');
 const pluginGenerator = require('./lib/generators/claude-plugin');
 const { loadSkills } = require('./lib/skills');
 const pkg = require('../package.json');
 
+/**
+ * Verifica que todos los archivos críticos del plugin hayan sido generados.
+ * @param {string} packageDir - Directorio raíz del paquete
+ * @throws {Error} Si falta cualquier archivo crítico
+ */
+function verifyPluginOutputs(packageDir) {
+  const criticalFiles = ['.claude-plugin/plugin.json', '.mcp.json', 'commands', 'skills'];
+
+  const missing = [];
+  for (const relPath of criticalFiles) {
+    const fullPath = path.join(packageDir, relPath);
+    if (!fs.existsSync(fullPath)) {
+      missing.push(relPath);
+    }
+  }
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Plugin generation completed but outputs are missing: ${missing.join(', ')}. ` +
+        'Check src/content/skills/ and the generator logic.'
+    );
+  }
+
+  // Verify the skills/ directory has at least one SKILL.md (sanity check)
+  const skillsDir = path.join(packageDir, 'skills');
+  const skillSubdirs = fs
+    .readdirSync(skillsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory());
+  const skillsWithMd = skillSubdirs.filter((d) =>
+    fs.existsSync(path.join(skillsDir, d.name, 'SKILL.md'))
+  );
+
+  if (skillsWithMd.length === 0) {
+    throw new Error(
+      `Plugin generation completed but no SKILL.md files were created in ${skillsDir}/`
+    );
+  }
+}
+
 async function main() {
   const packageDir = path.dirname(__dirname);
   const skills = loadSkills({
@@ -16,12 +60,20 @@ async function main() {
     preferLocal: true,
   });
 
+  if (skills.length === 0) {
+    throw new Error(
+      `No skills found in ${packageDir}/src/content/skills/. Cannot build plugin without sources.`
+    );
+  }
+
   await pluginGenerator.generate(packageDir, skills, {
     packageDir,
     version: pkg.version,
     usePluginRootLauncher: true,
     libraryPrefix: 'library',
   });
+
+  verifyPluginOutputs(packageDir);
 }
 
 main().catch((error) => {

package/bin/cli.js

@@ -127,10 +127,12 @@ const AI_TOOLS = generators ? generators.AI_TOOLS : {};
  * - Developer: Advanced tools for content management (xray, checkup, scan, sentinel, powers)
  * - Legacy: Old command names maintained for backward compatibility
  */
-// Commands are registered lazily to avoid TDZ issues with const wrappers.
-// Core commands use hoisted function declarations; developer commands use
-// createCommandWrapper which is defined later. We populate the map in
-// registerCommands() which runs before main().
+// Commands are registered in two phases to avoid TDZ (temporal dead zone) errors.
+// Phase 1: hoisted function declarations (showHelp, initProject, etc.) go directly
+// into the object literal below — safe because `function` declarations hoist.
+// Phase 2: wrapper-based commands that depend on `createCommandWrapper` (defined
+// further down in the file) are attached imperatively after that function exists.
+// See the `commands.xray = runSearch;` block after the wrapper `const`s.
 const commands = {
   // Core commands - basic info and status (hoisted functions, safe here)
   help: showHelp,

package/bin/commands/install.js

@@ -2,12 +2,19 @@
  * Install Command - Multi-agent skill installer
  * ===============================================
  *
- * Installs BI Agent Superpowers skills into the correct directories
- * for each AI coding agent. Inspired by the `npx skills` CLI from Vercel Labs.
+ * Instala los skills de BI Agent Superpowers en los directorios
+ * correctos para cada agente AI. Inspirado en el CLI `npx skills` de
+ * Vercel Labs.
  *
- * Skills are always installed at the user level (~/) to protect licensed content.
+ * Los skills siempre se instalan a nivel de usuario (~/) para proteger
+ * contenido licenciado. Un usuario podría copiarlos manualmente, pero
+ * no se commitean al repo del proyecto por accidente.
  *
- * Usage:
+ * Nota: este comando NO requiere licencia. Los skills son gratis de
+ * instalar; la licencia controla acceso a contenido premium vía
+ * `super unlock` + `super kickoff`.
+ *
+ * Uso:
  *   npx @luquimbo/bi-superpowers install
  *   super install
  *   super install --agent claude-code --agent codex
@@ -20,24 +27,12 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const readline = require('readline');
-
-// Agent registry: each agent's skill directory path (relative to home directory)
-// Order matches the interactive installer display order
-const AGENTS = {
-  'github-copilot': { name: 'GitHub Copilot', dir: '.github/skills' },
-  'claude-code': { name: 'Claude Code', dir: '.claude/skills' },
-  codex: { name: 'Codex (OpenAI)', dir: '.agents/skills' },
-  'gemini-cli': { name: 'Gemini CLI', dir: '.gemini/skills' },
-  kilo: { name: 'Kilo Code', dir: '.kilocode/skills' },
-};
-
-// Universal path — most agents read from .agents/skills/
-const UNIVERSAL_DIR = '.agents/skills';
+const { AGENTS, UNIVERSAL_DIR } = require('../lib/agents');
 
 /**
- * Detect which agents are available by checking for their config directories
- * @param {string} baseDir - Directory to check (project root or home)
- * @returns {string[]} Array of detected agent IDs
+ * Detecta qué agentes están instalados revisando sus directorios de config.
+ * @param {string} baseDir - Directorio base (home del usuario)
+ * @returns {string[]} IDs de agentes detectados
  */
 function detectAgents(baseDir) {
   const detected = [];
@@ -52,7 +47,7 @@ function detectAgents(baseDir) {
 }
 
 /**
- * Create readline interface for interactive prompts
+ * Crea una interface de readline para prompts interactivos.
  */
 function createReadline() {
   return readline.createInterface({
@@ -62,7 +57,7 @@ function createReadline() {
 }
 
 /**
- * Prompt user with a question
+ * Envuelve una pregunta de readline en una Promise.
  */
 function prompt(rl, question) {
   return new Promise((resolve) => {
@@ -71,11 +66,11 @@ function prompt(rl, question) {
 }
 
 /**
- * Display a numbered list and let user pick multiple items
+ * Muestra una lista numerada y deja al usuario elegir múltiples items.
  * @param {readline.Interface} rl
  * @param {Array<{id: string, name: string}>} items
- * @param {string[]} preselected - IDs to preselect
- * @returns {Promise<string[]>} Selected IDs
+ * @param {string[]} preselected - IDs preseleccionados
+ * @returns {Promise<string[]>} IDs seleccionados
  */
 async function selectMultiple(rl, items, preselected = []) {
   items.forEach((item, i) => {
@@ -83,8 +78,8 @@ async function selectMultiple(rl, items, preselected = []) {
     console.log(`  ${i + 1}) ${marker} ${item.name}`);
   });
   console.log();
-  console.log('  Enter numbers separated by commas (e.g. 1,2,3)');
-  console.log('  Press Enter for detected agents, or "a" for all');
+  console.log('  Ingresa números separados por comas (ej: 1,2,3)');
+  console.log('  Presiona Enter para los detectados, o "a" para todos');
 
   const answer = await prompt(rl, '\n  > ');
 
@@ -105,9 +100,10 @@ async function selectMultiple(rl, items, preselected = []) {
 }
 
 /**
- * Copy a skill directory to a target location
- * @param {string} srcDir - Source skill directory (containing SKILL.md)
- * @param {string} destDir - Destination directory
+ * Copia un directorio de skill recursivamente.
+ * Los errores de fs se propagan al caller para manejo centralizado.
+ * @param {string} srcDir - Directorio de skill fuente (contiene SKILL.md)
+ * @param {string} destDir - Directorio destino
  */
 function copySkillDir(srcDir, destDir) {
   if (!fs.existsSync(destDir)) {
@@ -128,43 +124,199 @@ function copySkillDir(srcDir, destDir) {
 }
 
 /**
- * Main install command handler
- * @param {string[]} args - CLI arguments
- * @param {Object} config - Command config from CLI
+ * Formatea un error de filesystem con hint útil según el código.
  */
-async function installCommand(args, config) {
-  const chalk = require('chalk');
-  const boxen = require('boxen');
+function formatFsError(err, context) {
+  const codeHints = {
+    EACCES: 'Permiso denegado. Revisa los permisos del directorio.',
+    EPERM: 'Operación no permitida. En Windows, probá ejecutar como Administrador.',
+    ENOSPC: 'No hay espacio en disco.',
+    ENOENT: 'Archivo o directorio no existe.',
+    EROFS: 'Sistema de archivos en solo lectura.',
+  };
+  const hint = codeHints[err.code] || '';
+  return `${context}: ${err.message}${hint ? `\n  ${hint}` : ''}`;
+}
 
-  const isYes = args.includes('--yes') || args.includes('-y');
-  const isAll = args.includes('--all');
-  const agentFlags = [];
+/**
+ * Parsea las flags de CLI y devuelve un objeto de opciones.
+ * Valida que cada --agent/-a tenga un valor asociado.
+ */
+function parseArgs(args) {
+  const opts = {
+    isYes: args.includes('--yes') || args.includes('-y'),
+    isAll: args.includes('--all'),
+    agentFlags: [],
+  };
 
-  // Parse --agent flags
   for (let i = 0; i < args.length; i++) {
-    if ((args[i] === '--agent' || args[i] === '-a') && args[i + 1]) {
-      agentFlags.push(args[i + 1]);
+    if (args[i] === '--agent' || args[i] === '-a') {
+      const next = args[i + 1];
+      if (next === undefined || next.startsWith('-')) {
+        // Falta valor para --agent; avisamos y seguimos sin ese flag
+        console.warn(`⚠ Flag ${args[i]} sin valor. Uso: ${args[i]} <agente-id>. Ignorando.`);
+        continue;
+      }
+      opts.agentFlags.push(next);
       i++;
     }
   }
 
-  // Always install at user level (home directory) to protect licensed content
+  return opts;
+}
+
+/**
+ * Resuelve qué agentes instalar según las flags y el modo interactivo.
+ * @returns {Promise<string[]>} IDs de agentes seleccionados
+ */
+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(`  Agentes desconocidos: ${unknown.join(', ')}`));
+      console.log(chalk.gray(`  Disponibles: ${Object.keys(AGENTS).join(', ')}\n`));
+    }
+    return known;
+  }
+
+  if (opts.isYes) {
+    return Object.keys(AGENTS);
+  }
+
+  // Modo interactivo
+  const detected = detectAgents(baseDir);
+  console.log(chalk.cyan('  Seleccioná los agentes donde querés instalar:\n'));
+
+  const items = Object.entries(AGENTS).map(([id, agent]) => ({
+    id,
+    name: detected.includes(id) ? `${agent.name} ${chalk.green('(detectado)')}` : agent.name,
+  }));
+
+  const rl = createReadline();
+  try {
+    return await selectMultiple(rl, items, detected);
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Instala los skills en los directorios seleccionados.
+ * @returns {{agentResults: Array, copyFallbacks: number}}
+ */
+function performInstall(skillsSourceDir, skillDirs, selectedAgents, baseDir) {
+  // Siempre instalamos primero en el path universal
+  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);
+  }
+
+  // Symlinks o copias para los directorios específicos de agentes
+  const agentResults = [];
+  let copyFallbacks = 0;
+
+  for (const agentId of selectedAgents) {
+    const agent = AGENTS[agentId];
+    if (agent.dir === UNIVERSAL_DIR) continue; // Ya manejado por el universal
+
+    const agentTarget = path.join(baseDir, agent.dir);
+
+    // Si ya existe y no es symlink, copiamos ahí directamente
+    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 });
+    }
+
+    // Eliminar symlink existente si hay uno (para poder recrearlo)
+    if (fs.existsSync(agentTarget) || fs.lstatSync(agentTarget, { throwIfNoEntry: false })) {
+      try {
+        fs.unlinkSync(agentTarget);
+      } catch (_) {
+        /* no existe, seguimos */
+      }
+    }
+
+    try {
+      // Symlink relativo del dir del agente al dir universal
+      const relPath = path.relative(parentDir, universalTarget);
+      fs.symlinkSync(relPath, agentTarget);
+      agentResults.push({ agent: agent.name, method: 'symlinked', dir: agent.dir });
+    } catch (symlinkErr) {
+      // Fallback a copia si el symlink falla (ej: Windows sin permisos)
+      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 };
+}
+
+/**
+ * Handler principal del comando install.
+ * @param {string[]} args - Argumentos CLI
+ * @param {Object} config - Config del comando desde el CLI
+ */
+async function installCommand(args, config) {
+  const chalk = require('chalk');
+  const boxen = require('boxen');
+
+  const opts = parseArgs(args);
+
+  // Siempre a nivel usuario (home) para proteger contenido licenciado
   const baseDir = os.homedir();
 
-  // Find skills from the package
-  const packageDir = config.packageDir || path.dirname(__dirname);
+  // Localizar los skills del paquete
+  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. Try reinstalling the package.'));
+    console.error(
+      chalk.red(
+        'Directorio de skills no encontrado. Reinstalá el paquete con: npm install -g @luquimbo/bi-superpowers'
+      )
+    );
     process.exit(1);
   }
 
-  // Read available skills
-  const skillDirs = fs
-    .readdirSync(skillsSourceDir, { withFileTypes: true })
-    .filter((d) => d.isDirectory() && fs.existsSync(path.join(skillsSourceDir, d.name, 'SKILL.md')))
-    .map((d) => d.name);
+  // Leer skills disponibles
+  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, 'No pude leer los skills')));
+    process.exit(1);
+  }
 
   // Header
   console.log(
@@ -172,7 +324,7 @@ async function installCommand(args, config) {
       chalk.bold.cyan('BI Agent Superpowers') +
         chalk.gray(` v${config.version}`) +
         '\n' +
-        chalk.gray('Multi-agent skill installer'),
+        chalk.gray('Instalador multi-agente'),
       {
         padding: 1,
         borderStyle: 'round',
@@ -181,129 +333,68 @@ async function installCommand(args, config) {
     )
   );
 
-  console.log(chalk.gray(`  Install path: ~/${UNIVERSAL_DIR}/`));
-  console.log(chalk.gray(`  Skills: ${skillDirs.length} available\n`));
-
-  // Determine which agents to install for
-  let selectedAgents;
-
-  if (isAll) {
-    selectedAgents = Object.keys(AGENTS);
-  } else if (agentFlags.length > 0) {
-    selectedAgents = agentFlags.filter((a) => AGENTS[a]);
-    const unknown = agentFlags.filter((a) => !AGENTS[a]);
-    if (unknown.length > 0) {
-      console.log(chalk.yellow(`  Unknown agents: ${unknown.join(', ')}`));
-      console.log(chalk.gray(`  Available: ${Object.keys(AGENTS).join(', ')}\n`));
-    }
-  } else if (isYes) {
-    selectedAgents = Object.keys(AGENTS);
-  } else {
-    // Interactive mode: detect and ask
-    const detected = detectAgents(baseDir);
-
-    console.log(chalk.cyan('  Select agents to install for:\n'));
+  console.log(chalk.gray(`  Ruta de instalación: ~/${UNIVERSAL_DIR}/`));
+  console.log(chalk.gray(`  Skills: ${skillDirs.length} disponibles\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 {
-      selectedAgents = await selectMultiple(rl, items, detected);
-    } finally {
-      rl.close();
-    }
-  }
+  // Resolver qué agentes instalar
+  const selectedAgents = await resolveSelectedAgents(opts, baseDir, chalk);
 
   if (selectedAgents.length === 0) {
-    console.log(chalk.yellow('\n  No agents selected. Nothing to install.'));
+    console.log(chalk.yellow('\n  Ningún agente seleccionado. Nada que instalar.'));
     return;
   }
 
   console.log(
-    chalk.cyan(`\n  Installing ${skillDirs.length} skills for ${selectedAgents.length} agents...\n`)
+    chalk.cyan(
+      `\n  Instalando ${skillDirs.length} skills para ${selectedAgents.length} agentes...\n`
+    )
   );
 
-  // Always install to universal path first
-  const universalTarget = path.join(baseDir, UNIVERSAL_DIR);
-  let installedCount = 0;
-
-  for (const skill of skillDirs) {
-    const src = path.join(skillsSourceDir, skill);
-    const dest = path.join(universalTarget, skill);
-    copySkillDir(src, dest);
-    installedCount++;
+  // Instalar
+  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, 'Falló la instalación')));
+    process.exit(1);
   }
 
-  // List agents whose default dir is the universal path (e.g. Codex)
+  // Universal
   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}/ (${installedCount} skills)${universalSuffix}`));
+  console.log(chalk.green(`  ✓ ${UNIVERSAL_DIR}/ (${skillDirs.length} skills)${universalSuffix}`));
 
-  // Symlink agent-specific directories to universal path
-  const agentResults = [];
-  for (const agentId of selectedAgents) {
-    const agent = AGENTS[agentId];
-    if (agent.dir === UNIVERSAL_DIR) continue; // Already handled
-
-    const agentTarget = path.join(baseDir, agent.dir);
-
-    // If the directory already exists and is not a symlink, copy instead
-    if (fs.existsSync(agentTarget) && !fs.lstatSync(agentTarget).isSymbolicLink()) {
-      // Copy skills into existing directory
-      for (const skill of skillDirs) {
-        copySkillDir(path.join(skillsSourceDir, skill), path.join(agentTarget, skill));
-      }
-      agentResults.push({ agent: agent.name, method: 'copied', dir: agent.dir });
-    } else {
-      // Create symlink to universal directory
-      const parentDir = path.dirname(agentTarget);
-      if (!fs.existsSync(parentDir)) {
-        fs.mkdirSync(parentDir, { recursive: true });
-      }
-
-      // Remove existing symlink if present
-      if (fs.existsSync(agentTarget)) {
-        fs.unlinkSync(agentTarget);
-      }
-
-      try {
-        // Relative symlink from agent dir to universal dir
-        const relPath = path.relative(parentDir, universalTarget);
-        fs.symlinkSync(relPath, agentTarget);
-        agentResults.push({ agent: agent.name, method: 'symlinked', dir: agent.dir });
-      } catch (_e) {
-        // Fallback to copy if symlink fails (e.g. Windows without admin)
-        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 });
-      }
-    }
-  }
-
-  // Print results
+  // Por agente
   for (const result of agentResults) {
     const icon = result.method === 'symlinked' ? '→' : '✓';
     console.log(chalk.green(`  ${icon} ${result.dir}/ (${result.method}) — ${result.agent}`));
   }
 
-  // Summary
-  const totalAgents = agentResults.length + 1; // +1 for universal
+  // Aviso si hubo fallbacks de symlink a copia
+  if (copyFallbacks > 0) {
+    console.log(
+      chalk.yellow(
+        `\n  ⚠ ${copyFallbacks} agente(s) usaron copia en vez de symlink ` +
+          '(probable Windows sin permisos de admin).\n' +
+          "    Re-ejecutá 'super install' tras cada upgrade para refrescar los archivos."
+      )
+    );
+  }
+
+  // Resumen
+  const totalAgents = agentResults.length + (universalAgents.length > 0 ? 1 : 0);
   console.log(
     boxen(
-      chalk.green.bold(`Installed ${installedCount} skills for ${totalAgents} agents`) +
+      chalk.green.bold(`Instalados ${skillDirs.length} skills para ${totalAgents} agentes`) +
         '\n\n' +
-        chalk.gray('Skills are ready to use. Open your AI agent and start prompting.') +
+        chalk.gray('Los skills están listos. Abrí tu agente AI y empezá a usarlos.') +
         '\n' +
-        chalk.gray('Example: "Help me write a DAX measure for YTD sales"'),
+        chalk.gray('Ejemplo: "Ayudame a escribir una medida DAX de ventas YTD"'),
       {
         padding: 1,
         margin: { top: 1 },
@@ -314,4 +405,11 @@ async function installCommand(args, config) {
   );
 }
 
+// Exports internos para 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;