@luquimbo/bi-superpowers 4.1.5 → 5.0.0

package/bin/cli.js

@@ -45,6 +45,7 @@ let watchCommand;
 let mcpSetupCommand;
 let buildDesktopCommand;
 let installCommand;
+let validateProjectsCommand;
 let tui;
 try {
   lintCommand = require('./commands/lint'); // checkup: skill file validation
@@ -53,6 +54,7 @@ try {
   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
+  validateProjectsCommand = require('./commands/validate-projects'); // repo/project validation harness
   tui = require('./utils/tui'); // colors, tables, boxes for CLI output
 } catch (_) {
   // Expected during `npm install` — modules become available after deps are linked.
@@ -171,6 +173,7 @@ 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-projects Validate public fixtures + local private project references
 
 Options:
   --dry-run         Preview changes without writing files (kickoff, recharge)
@@ -185,7 +188,9 @@ Examples:
   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 validate-projects          # Developer QA against validation/ descriptors
 
 Open source — MIT licensed.
 Documentation: https://github.com/luquimbo/bi-superpowers
@@ -428,15 +433,12 @@ function ensurePluginTool(tools = []) {
 
 /**
  * Build the options object passed into individual generators.
- * If the target directory has its own local `library/` folder, skills
- * will reference that; otherwise they reference the library bundled
- * inside the installed npm package.
+ * `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'
-    : path.join(PACKAGE_DIR, 'library');
+  const libraryPrefix = fs.existsSync(path.join(targetDir, 'library')) ? 'library' : null;
 
   return {
     packageDir: PACKAGE_DIR,
@@ -581,9 +583,9 @@ function showCompletionMessage(targetDir, tools, skillCount) {
 
   To build the Desktop extension:
 
-    super build-desktop
+    super build-desktop --output dist
 
-  Then double-click bi-superpowers.mcpb to install.
+  Then double-click dist/bi-superpowers.mcpb to install.
 
 ────────────────────────────────────────────────────────────
 
@@ -759,6 +761,7 @@ const runDiff = createCommandWrapper(diffCommand, 'Diff');
 const runMcpSetup = createCommandWrapper(mcpSetupCommand, 'MCP setup');
 const runBuildDesktop = createCommandWrapper(buildDesktopCommand, 'Build Desktop');
 const runInstall = createCommandWrapper(installCommand, 'Install');
+const runValidateProjects = createCommandWrapper(validateProjectsCommand, 'Validate projects');
 
 // Register wrapper-based commands into the command map (phase 2).
 commands.install = runInstall;
@@ -768,6 +771,7 @@ commands.sentinel = runWatch;
 commands['mcp-setup'] = runMcpSetup;
 commands.mcp = runMcpSetup;
 commands['build-desktop'] = runBuildDesktop;
+commands['validate-projects'] = runValidateProjects;
 commands.lint = runLint;
 commands.diff = runDiff;
 commands.watch = runWatch;

package/bin/commands/build-desktop.js

@@ -100,14 +100,48 @@ function shouldSkipRuntimeFile(filePath) {
   );
 }
 
+/**
+ * Parse build-desktop CLI arguments.
+ *
+ * @param {string[]} args - CLI arguments after `build-desktop`
+ * @returns {{outputDir: string}} Build options
+ */
+function parseArgs(args) {
+  const options = {
+    outputDir: process.cwd(),
+  };
+
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+
+    if (arg === '--output' || arg === '-o') {
+      const value = args[++index];
+      if (!value || value.startsWith('-')) {
+        throw new Error(`${arg} requires a path`);
+      }
+      options.outputDir = path.resolve(value);
+    }
+  }
+
+  return options;
+}
+
 /**
  * Build the .mcpb extension for Claude Desktop.
  *
  * @param {string[]} args - CLI arguments
  * @param {Object} config - Command config from CLI
  */
-function buildDesktop(_args, _config) {
-  const outputDir = process.cwd();
+function buildDesktop(args, _config) {
+  let options;
+  try {
+    options = parseArgs(args || []);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+  const outputDir = options.outputDir;
+  fs.mkdirSync(outputDir, { recursive: true });
 
   console.log(`
 BI Agent Superpowers — Build Desktop Extension
@@ -239,3 +273,4 @@ module.exports = buildDesktop;
 module.exports.bundleSkills = bundleSkills;
 module.exports.copyRuntimeTree = copyRuntimeTree;
 module.exports.shouldSkipRuntimeFile = shouldSkipRuntimeFile;
+module.exports.parseArgs = parseArgs;

package/bin/commands/diff.js

@@ -331,8 +331,8 @@ function diffCommand(args, config) {
   let skillFiles = [];
 
   if (options.skill) {
-    // normalizeSkillName accepts `dax`, `dax.md`, `report-design`, or
-    // `report-design/SKILL.md` and returns the canonical skill name.
+    // normalizeSkillName accepts `dax`, `dax.md`, `bi-report`, or
+    // `bi-report/SKILL.md` and returns the canonical skill name.
     const skill = skillsByName.get(normalizeSkillName(options.skill));
     if (skill) {
       skillFiles = [skill.path];

package/bin/commands/install.js

@@ -13,7 +13,8 @@
  * 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. MCPs are written to each agent's
+ * 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.
  *
@@ -116,10 +117,31 @@ async function selectMultiple(rl, items, preselected = []) {
  * @param {string} destDir - Destination directory
  */
 function copySkillDir(srcDir, destDir) {
-  if (!fs.existsSync(destDir)) {
-    fs.mkdirSync(destDir, { recursive: true });
+  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);
@@ -435,7 +457,7 @@ async function installCommand(args, config) {
       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."
+          "    Re-ejecutá 'super install' tras cada upgrade; la copia se espeja y elimina runtimes viejos."
       )
     );
   }
@@ -474,11 +496,11 @@ async function installCommand(args, config) {
         '\n' +
         chalk.gray('  /bi-start         — Arrancar una sesión: menú + update + conexión') +
         '\n' +
-        chalk.gray('  /project-kickoff  — Analizá tu proyecto BI (proyecto nuevo)') +
+        chalk.gray('  /bi-kickoff  — Analizá tu proyecto BI (proyecto nuevo)') +
         '\n' +
-        chalk.gray('  /pbi-connect      — Conectá tu agente a Power BI Desktop') +
+        chalk.gray('  /bi-connect      — Conectá Power BI + guía UDF DAX') +
         '\n' +
-        chalk.gray('  /report-design    — Generá reportes PBIR para Power BI Desktop (Windows)'),
+        chalk.gray('  /bi-report    — Generá reportes PBIR para Power BI Desktop (Windows)'),
       {
         padding: 1,
         margin: { top: 1 },

package/bin/commands/lint.js

@@ -366,7 +366,7 @@ function lintCommand(args, config) {
   // Determine which files to lint. Use the shared skill loader so we
   // catch both flat (`<name>.md`) and folder-based (`<name>/SKILL.md`)
   // skills — a previous version filtered with `f.endsWith('.md')` and
-  // silently skipped every folder-based skill (e.g. `report-design`).
+  // silently skipped every folder-based skill (e.g. `bi-report`).
   const allSkills = readSkillDirectory(skillsDir);
   const skillsByName = new Map(allSkills.map((s) => [s.name, s]));
   let filesToLint = [];
@@ -379,7 +379,7 @@ function lintCommand(args, config) {
           return f;
         }
         // Look up by skill name. normalizeSkillName accepts `dax`,
-        // `dax.md`, `report-design`, or `report-design/SKILL.md`.
+        // `dax.md`, `bi-report`, or `bi-report/SKILL.md`.
         const skill = skillsByName.get(normalizeSkillName(f));
         if (skill) return skill.path;
 

package/bin/commands/mcp-setup.js

@@ -2,7 +2,8 @@
  * MCP Setup Command
  * =================
  * Configures the official Microsoft MCP servers for an existing project-local
- * Claude Code plugin and legacy adapter formats.
+ * BI Superpowers plugin. Normal multi-agent setup is user-level via
+ * `super install --all --yes`; this command refuses arbitrary repo-local writes.
  *
  * Usage:
  *   super mcp-setup
@@ -20,6 +21,7 @@ const {
   createMcpConfigForFormat,
   mergeMcpConfig,
 } = require('../lib/microsoft-mcp');
+const { readJsonStrict, writeJson } = require('../lib/mcp-config');
 
 const MCP_CONFIGS = {
   'claude-plugin': {
@@ -110,21 +112,7 @@ function hasLocalPluginMarker(targetDir) {
   );
 }
 
-function readJson(filePath) {
-  if (!fs.existsSync(filePath)) {
-    return {};
-  }
-
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch (error) {
-    return {};
-  }
-}
-
 function writeConfig(filePath, config, dryRun) {
-  const directory = path.dirname(filePath);
-
   if (dryRun) {
     tui.info(`Would write: ${tui.formatPath(filePath)}`);
     tui.muted(JSON.stringify(config, null, 2).slice(0, 220) + '...');
@@ -132,11 +120,7 @@ function writeConfig(filePath, config, dryRun) {
   }
 
   try {
-    if (!fs.existsSync(directory)) {
-      fs.mkdirSync(directory, { recursive: true });
-    }
-
-    fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
+    writeJson(filePath, config);
     return true;
   } catch (error) {
     tui.error(`Failed to write ${filePath}: ${error.message}`);
@@ -174,8 +158,8 @@ function mcpSetupCommand(args, config) {
     process.exit(1);
   }
 
-  if ((!options.tool || options.tool === 'claude-plugin') && !hasLocalPluginMarker(targetDir)) {
-    tui.warning('mcp-setup is only for project-local Claude Code plugin configs.');
+  if (!hasLocalPluginMarker(targetDir)) {
+    tui.warning('mcp-setup is only for existing project-local BI Superpowers plugin configs.');
     tui.info(
       'For Codex, GitHub Copilot, Gemini CLI, Kilo Code, and Claude Code user-level installs, run:'
     );
@@ -184,7 +168,7 @@ function mcpSetupCommand(args, config) {
       'That writes user-level skills and MCP config under your home directory without creating files in this repo.'
     );
     tui.info(
-      'If you intentionally need a local Claude Code plugin, run `super kickoff` first or pass `--tool claude-plugin`.'
+      'If you intentionally need local Claude Code plugin files, run `super kickoff` first, then rerun `super mcp-setup` inside that initialized repo.'
     );
     process.exitCode = 2;
     return;
@@ -225,13 +209,19 @@ function mcpSetupCommand(args, config) {
   configuredTools.forEach((tool) => {
     const toolConfig = MCP_CONFIGS[tool];
     const filePath = path.join(targetDir, toolConfig.configPath);
-    const existingConfig = readJson(filePath);
-    const generatedConfig = createMcpConfigForFormat(toolConfig.format, {
-      packageDir: config.packageDir,
-      launcherMode: getLauncherMode(targetDir, config.packageDir, tool),
-    });
-    const mergedConfig = mergeMcpConfig(existingConfig, generatedConfig, toolConfig.format);
-    const ok = writeConfig(filePath, mergedConfig, options.dryRun);
+    let ok = false;
+
+    try {
+      const existingConfig = readJsonStrict(filePath) || {};
+      const generatedConfig = createMcpConfigForFormat(toolConfig.format, {
+        packageDir: config.packageDir,
+        launcherMode: getLauncherMode(targetDir, config.packageDir, tool),
+      });
+      const mergedConfig = mergeMcpConfig(existingConfig, generatedConfig, toolConfig.format);
+      ok = writeConfig(filePath, mergedConfig, options.dryRun);
+    } catch (error) {
+      tui.error(`Failed to prepare ${filePath}: ${error.message}`);
+    }
 
     if (ok) {
       results.success.push(toolConfig.name);