bi-superpowers 1.0.0

package/bin/commands/autoupdate.js

@@ -0,0 +1,128 @@
+/**
+ * Auto-update command (opt-in gstack-style self-update)
+ * =====================================================
+ *
+ * `super autoupdate on|off|status` toggles a Claude Code `SessionStart`
+ * hook that silently keeps the plugin current — so the user never installs
+ * by hand. OFF by default; the user explicitly opts in.
+ *
+ *   - on      Register the SessionStart hook in ~/.claude/settings.json
+ *   - off     Remove it
+ *   - status  Report whether it's enabled
+ *
+ * The hook runs bin/commands/session-update.js, which throttles to once per
+ * hour and, when due, upgrades via npm (`npm install -g <pkg>@latest`) then
+ * refreshes the agent skills/MCPs (`super install --all --yes`) in a
+ * detached background process. Because it's npm-based, it works even when
+ * the GitHub repo is private.
+ *
+ * Scope note: SessionStart hooks are a Claude Code feature. Other agents
+ * (Codex, Copilot, Gemini, Kilo) don't have an equivalent simple hook, so
+ * for them the existing notify-on-invocation flow + `super upgrade` remains
+ * the path. This also only helps npm-installed setups, not Claude Code
+ * marketplace installs (those update via `/plugin update`).
+ *
+ * @module commands/autoupdate
+ */
+
+const path = require('path');
+const {
+  registerSessionStartHook,
+  unregisterSessionStartHook,
+  isSessionStartHookRegistered,
+  claudeSettingsPath,
+} = require('../lib/claude-hooks');
+
+/**
+ * Build the shell command the SessionStart hook runs.
+ * @param {string} packageDir - Absolute path to the installed package
+ */
+function hookCommand(packageDir) {
+  const script = path.join(packageDir, 'bin', 'commands', 'session-update.js');
+  return `node "${script}"`;
+}
+
+/**
+ * Enable auto-update: register the SessionStart hook. Shared with
+ * `super install --auto-update`.
+ * @returns {{ file: string, action: string }}
+ */
+function enableAutoupdate(packageDir, opts = {}) {
+  return registerSessionStartHook(hookCommand(packageDir), opts);
+}
+
+/**
+ * Disable auto-update: remove the SessionStart hook.
+ * @returns {{ file: string, removed: boolean }}
+ */
+function disableAutoupdate(opts = {}) {
+  return unregisterSessionStartHook(opts);
+}
+
+/**
+ * `super autoupdate <on|off|status>`
+ * @param {string[]} args
+ * @param {object} config - { packageDir, version }
+ */
+function autoupdateCommand(args, config) {
+  const chalk = require('chalk');
+  const sub = (args[0] || 'status').toLowerCase();
+  const packageDir = config.packageDir || path.dirname(path.dirname(__dirname));
+
+  if (sub === 'on' || sub === 'enable') {
+    try {
+      const { file } = enableAutoupdate(packageDir);
+      console.log(chalk.green('  ✓ Auto-update enabled (Claude Code SessionStart hook).'));
+      console.log(chalk.gray(`    ${file.replace(require('os').homedir(), '~')}`));
+      console.log(
+        chalk.gray(
+          '    Each new Claude Code session checks at most once/hour and, if a new\n' +
+            '    version exists, upgrades via npm + refreshes your agents in the\n' +
+            '    background. npm-based, so it works with a private GitHub repo.'
+        )
+      );
+      console.log(chalk.gray('    Other agents still use notify-on-invocation + `super upgrade`.'));
+    } catch (err) {
+      console.error(chalk.red(`  ✗ Could not enable auto-update: ${err.message}`));
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (sub === 'off' || sub === 'disable') {
+    try {
+      const { removed } = disableAutoupdate();
+      console.log(
+        removed
+          ? chalk.green('  ✓ Auto-update disabled (SessionStart hook removed).')
+          : chalk.gray('  – Auto-update was not enabled. Nothing to remove.')
+      );
+    } catch (err) {
+      console.error(chalk.red(`  ✗ Could not disable auto-update: ${err.message}`));
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (sub === 'status') {
+    const enabled = isSessionStartHookRegistered();
+    console.log(
+      enabled
+        ? chalk.green('  Auto-update: ON (Claude Code SessionStart hook registered).')
+        : chalk.gray('  Auto-update: OFF. Enable with `super autoupdate on`.')
+    );
+    console.log(
+      chalk.gray(`  Settings file: ${claudeSettingsPath().replace(require('os').homedir(), '~')}`)
+    );
+    return;
+  }
+
+  console.log(chalk.yellow(`  Unknown subcommand: ${sub}`));
+  console.log(chalk.gray('  Usage: super autoupdate <on|off|status>'));
+  process.exitCode = 1;
+}
+
+module.exports = autoupdateCommand;
+module.exports.enableAutoupdate = enableAutoupdate;
+module.exports.disableAutoupdate = disableAutoupdate;
+module.exports.hookCommand = hookCommand;

package/bin/commands/build-desktop.js

@@ -0,0 +1,368 @@
+/**
+ * Build Desktop Extension Command
+ * ================================
+ *
+ * Builds a .mcpb extension for Claude Desktop by:
+ * 1. Copying desktop-extension/ template to a temp directory
+ * 2. Copying every skill source (flat + folder-based) into temp/skills/
+ * 3. Installing dependencies
+ * 4. Running `npx @anthropic-ai/mcpb pack` to create the .mcpb file
+ * 5. Moving the result to the current directory
+ *
+ * Usage: super build-desktop [--output <path>]
+ *
+ * @module commands/build-desktop
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawnSync } = require('child_process');
+const { loadSkills } = require('../lib/skills');
+
+/** Directory where the npm package is installed */
+const PACKAGE_DIR = path.dirname(path.dirname(__dirname));
+
+/** Desktop extension template source */
+const DESKTOP_TEMPLATE_DIR = path.join(PACKAGE_DIR, 'desktop-extension');
+
+/**
+ * Bundle skills into the Desktop extension's skills/ directory.
+ *
+ * Handles both flat `src/content/skills/<name>.md` and folder-based
+ * `src/content/skills/<name>/SKILL.md` layouts by writing each skill as
+ * `<name>/SKILL.md`. Folder-based skills also get their runtime
+ * `references/` and `scripts/` subtrees copied into the MCPB, so prompts
+ * never point Claude Desktop at files missing from the installed extension.
+ *
+ * @param {string} skillsOutDir - Destination directory (created if missing)
+ * @param {string} packageDir - npm package root containing src/content/skills/
+ * @returns {string[]} Names of skills bundled into skillsOutDir
+ */
+function bundleSkills(skillsOutDir, packageDir) {
+  fs.mkdirSync(skillsOutDir, { recursive: true });
+  const skills = loadSkills({ packageDir });
+  for (const skill of skills) {
+    const skillOutDir = path.join(skillsOutDir, skill.name);
+    fs.mkdirSync(skillOutDir, { recursive: true });
+    fs.writeFileSync(path.join(skillOutDir, 'SKILL.md'), skill.content);
+
+    if (skill.bundleDir) {
+      copyRuntimeTree(
+        path.join(skill.bundleDir, 'references'),
+        path.join(skillOutDir, 'references')
+      );
+      copyRuntimeTree(path.join(skill.bundleDir, 'scripts'), path.join(skillOutDir, 'scripts'));
+      copyRuntimeTree(path.join(skill.bundleDir, 'examples'), path.join(skillOutDir, 'examples'));
+    }
+  }
+  return skills.map((s) => s.name);
+}
+
+/**
+ * Copy runtime skill assets, excluding test/build/editor artifacts.
+ *
+ * @param {string} source - Source file or directory
+ * @param {string} target - Destination file or directory
+ */
+function copyRuntimeTree(source, target) {
+  if (!fs.existsSync(source)) {
+    return;
+  }
+
+  const stat = fs.statSync(source);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(target, { recursive: true });
+    for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+      copyRuntimeTree(path.join(source, entry.name), path.join(target, entry.name));
+    }
+    return;
+  }
+
+  if (!stat.isFile() || shouldSkipRuntimeFile(source)) {
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.copyFileSync(source, target);
+}
+
+/**
+ * @param {string} filePath - Runtime asset path
+ * @returns {boolean} True if this file should not ship in the MCPB
+ */
+function shouldSkipRuntimeFile(filePath) {
+  const base = path.basename(filePath);
+  return (
+    base.endsWith('.test.js') ||
+    base.endsWith('.spec.js') ||
+    base.endsWith('.expected.json') ||
+    base.endsWith('.bak') ||
+    base.endsWith('.tmp')
+  );
+}
+
+/**
+ * Run an external command without shell string execution.
+ *
+ * @param {string} command - Executable name/path
+ * @param {string[]} args - Command arguments
+ * @param {{cwd?: string}} options - spawnSync options
+ */
+function createRunExternalOptions(options = {}) {
+  return {
+    encoding: 'utf8',
+    stdio: 'pipe',
+    // npm can emit funding/audit/deprecation notices to stdout even with
+    // --silent; the 1 MiB spawnSync default would set ENOBUFS and hard-fail
+    // the install step (which, unlike pack, has no adm-zip fallback).
+    maxBuffer: 1024 * 1024 * 64,
+    ...options,
+    shell: false,
+  };
+}
+
+function runExternal(command, args, options = {}) {
+  const result = spawnSync(command, args, createRunExternalOptions(options));
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    const stdout = typeof result.stdout === 'string' ? result.stdout.trim() : '';
+    const stderr = typeof result.stderr === 'string' ? result.stderr.trim() : '';
+    const details = [
+      `${command} ${args.join(' ')} failed with exit code ${result.status}`,
+      stdout ? `stdout:\n${stdout}` : null,
+      stderr ? `stderr:\n${stderr}` : null,
+    ].filter(Boolean);
+    throw new Error(details.join('\n'));
+  }
+}
+
+/**
+ * Resolve npm/npx in a way that avoids Windows .cmd execution with shell=false.
+ *
+ * @param {'npm'|'npx'} command - Package manager command
+ * @param {{platform?: string, execPath?: string, env?: NodeJS.ProcessEnv}} runtime - Runtime hints
+ * @returns {{command: string, argsPrefix: string[]}} Command and args prefix
+ */
+function resolvePackageManagerCommand(command, runtime = {}) {
+  const platform = runtime.platform || process.platform;
+  const execPath = runtime.execPath || process.execPath;
+  const env = runtime.env || process.env;
+
+  if (platform !== 'win32') {
+    return { command, argsPrefix: [] };
+  }
+
+  const cliPath = findPackageManagerCli(command, execPath, env);
+  if (cliPath) {
+    return { command: execPath, argsPrefix: [cliPath] };
+  }
+
+  throw new Error(`Unable to resolve ${command} JS CLI for shell-free Windows execution`);
+}
+
+function findPackageManagerCli(command, execPath, env) {
+  const cliFile = `${command}-cli.js`;
+  const candidates = [];
+
+  if (env.npm_execpath) {
+    candidates.push(path.join(path.dirname(env.npm_execpath), cliFile));
+  }
+
+  candidates.push(path.join(path.dirname(execPath), 'node_modules', 'npm', 'bin', cliFile));
+
+  try {
+    candidates.push(require.resolve(`npm/bin/${cliFile}`));
+  } catch (_) {
+    // npm is not always resolvable as a module from packaged installs.
+  }
+
+  return candidates.find((candidate) => fs.existsSync(candidate));
+}
+
+/**
+ * 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) {
+  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
+================================================
+`);
+
+  // Verify template exists
+  if (!fs.existsSync(DESKTOP_TEMPLATE_DIR)) {
+    console.error('Error: desktop-extension/ template not found in package.');
+    console.error('Try reinstalling: npm install -g bi-superpowers');
+    process.exit(1);
+  }
+
+  // Verify skills exist
+  const skillsSourceDir = path.join(PACKAGE_DIR, 'src', 'content', 'skills');
+  if (!fs.existsSync(skillsSourceDir)) {
+    console.error(
+      'Error: skill sources not found. Try reinstalling: npm install -g bi-superpowers'
+    );
+    process.exit(1);
+  }
+
+  // Create temp build directory
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bi-superpowers-mcpb-'));
+
+  try {
+    console.log('  Preparing build directory...');
+
+    // Copy template files (manifest.json, server.js, package.json)
+    for (const file of ['manifest.json', 'server.js', 'package.json']) {
+      const src = path.join(DESKTOP_TEMPLATE_DIR, file);
+      if (fs.existsSync(src)) {
+        fs.copyFileSync(src, path.join(tmpDir, file));
+      }
+    }
+
+    // Bundle every skill (flat + folder-based) into temp/skills/
+    const bundledNames = bundleSkills(path.join(tmpDir, 'skills'), PACKAGE_DIR);
+    const skillFiles = bundledNames.map((n) => `${n}/SKILL.md`);
+    console.log(`  Bundled ${bundledNames.length} skills`);
+
+    // Patch template placeholder versions with the real package version
+    const pkgVersion = require(path.join(PACKAGE_DIR, 'package.json')).version;
+    for (const file of ['manifest.json', 'package.json']) {
+      const filePath = path.join(tmpDir, file);
+      if (fs.existsSync(filePath)) {
+        const content = fs.readFileSync(filePath, 'utf8');
+        fs.writeFileSync(
+          filePath,
+          content.replace(/"version":\s*"[^"]*"/, `"version": "${pkgVersion}"`),
+          'utf8'
+        );
+      }
+    }
+    const serverPath = path.join(tmpDir, 'server.js');
+    if (fs.existsSync(serverPath)) {
+      const content = fs.readFileSync(serverPath, 'utf8');
+      fs.writeFileSync(
+        serverPath,
+        content.replace(/version:\s*'[^']*'/, `version: '${pkgVersion}'`),
+        'utf8'
+      );
+    }
+
+    // Install dependencies in temp dir
+    console.log('  Installing dependencies...');
+    const npmCommand = resolvePackageManagerCommand('npm');
+    runExternal(
+      npmCommand.command,
+      [...npmCommand.argsPrefix, 'install', '--omit=dev', '--silent'],
+      {
+        cwd: tmpDir,
+      }
+    );
+
+    // Pack into .mcpb using the official CLI
+    console.log('  Packing .mcpb extension...');
+    try {
+      const npxCommand = resolvePackageManagerCommand('npx');
+      runExternal(
+        npxCommand.command,
+        [...npxCommand.argsPrefix, '--yes', '@anthropic-ai/mcpb', 'pack', tmpDir],
+        {
+          cwd: outputDir,
+        }
+      );
+    } catch (packErr) {
+      // If mcpb CLI is not available, create zip with adm-zip (cross-platform)
+      console.log('  Note: @anthropic-ai/mcpb not available, creating zip archive...');
+      const AdmZip = require('adm-zip');
+      const zip = new AdmZip();
+      zip.addLocalFolder(tmpDir);
+      const mcpbFile = path.join(outputDir, 'bi-superpowers.mcpb');
+      zip.writeZip(mcpbFile);
+    }
+
+    // Check for output file (mcpb CLI may name it with version suffix)
+    const possibleOutputs = [
+      path.join(outputDir, 'bi-superpowers.mcpb'),
+      path.join(outputDir, `bi-superpowers-${pkgVersion}.mcpb`),
+    ];
+    const outputFile = possibleOutputs.find((f) => fs.existsSync(f));
+
+    if (outputFile) {
+      const size = (fs.statSync(outputFile).size / 1024).toFixed(1);
+      console.log(`
+  Done! Extension built successfully.
+
+  Output: ${outputFile} (${size} KB)
+
+  To install in Claude Desktop:
+    1. Double-click the .mcpb file, or
+    2. Go to Settings > Extensions > Install Extension
+
+  The extension adds ${skillFiles.length} BI skills as MCP prompts.
+  Use the "setup-mcp" prompt for Power BI Modeling MCP configuration.
+`);
+    } else {
+      console.log('\n  Build complete. Check current directory for .mcpb file.');
+    }
+  } catch (err) {
+    console.error(`\nBuild failed: ${err.message}`);
+    process.exit(1);
+  } finally {
+    // Clean up temp directory
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch (_) {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+module.exports = buildDesktop;
+module.exports.bundleSkills = bundleSkills;
+module.exports.copyRuntimeTree = copyRuntimeTree;
+module.exports.shouldSkipRuntimeFile = shouldSkipRuntimeFile;
+module.exports.parseArgs = parseArgs;
+module.exports.resolvePackageManagerCommand = resolvePackageManagerCommand;
+module.exports.createRunExternalOptions = createRunExternalOptions;

package/bin/commands/create-from-template.js

@@ -0,0 +1,165 @@
+/**
+ * Create From Template Command
+ * ============================
+ *
+ * Scaffolds a new Power BI project from a packaged template under
+ * `templates/<name>/` into `<targetDir>/pbip-files/<projectName>.*`,
+ * renaming the PBIP descriptor + the two artifact folders and rewriting
+ * the internal cross-references (.pbip, definition.pbir, both .platform
+ * files with regenerated logicalIds).
+ *
+ * Used by the `bi-kickoff` skill PHASE 0 Option C ("Comenzar desde un
+ * template del plugin") so the agent does not have to copy files by
+ * hand. Available standalone for power users who want to scaffold from
+ * the CLI without going through the skill.
+ *
+ * Usage:
+ *   super create-from-template --template base-template --name <projectName>
+ *   super create-from-template --template base-template --name <projectName> --target /path/to/project
+ *   super create-from-template --list
+ *   super create-from-template --template base-template --name <projectName> --dry-run
+ *   super create-from-template --template base-template --name <projectName> --force
+ */
+
+const path = require('path');
+const { listTemplates, scaffoldFromTemplate } = require('../lib/template-scaffold');
+
+function parseArgs(args) {
+  const options = {
+    templateName: null,
+    targetDir: process.cwd(),
+    projectName: null,
+    force: false,
+    dryRun: false,
+    list: false,
+    json: false,
+  };
+
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--template' || arg === '-t') {
+      options.templateName = readValue(args, ++index, arg);
+    } else if (arg === '--target') {
+      options.targetDir = readValue(args, ++index, arg);
+    } else if (arg === '--name' || arg === '-n') {
+      options.projectName = readValue(args, ++index, arg);
+    } else if (arg === '--force' || arg === '-f') {
+      options.force = true;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--list' || arg === '-l') {
+      options.list = true;
+    } else if (arg === '--json') {
+      options.json = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  options.targetDir = path.resolve(options.targetDir);
+  return options;
+}
+
+function readValue(args, index, flag) {
+  const value = args[index];
+  if (!value || value.startsWith('-')) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function printList(packageDir, json) {
+  const templates = listTemplates(packageDir);
+  if (json) {
+    console.log(JSON.stringify({ templates: templates.map((t) => ({ name: t.name })) }, null, 2));
+    return;
+  }
+  console.log('BI Agent Superpowers — Available Templates');
+  console.log('==========================================\n');
+  if (templates.length === 0) {
+    console.log('No templates found in templates/.');
+    return;
+  }
+  for (const template of templates) {
+    console.log(`- ${template.name} (${template.pbipFile})`);
+  }
+  console.log(
+    '\nUse: super create-from-template --template <name> --name <projectName> [--target <dir>]'
+  );
+}
+
+function printResult(result, json) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (result.dryRun) {
+    console.log('BI Agent Superpowers — create-from-template (dry-run)');
+    console.log('====================================================\n');
+    console.log(`Template:     ${result.template}`);
+    console.log(`Project name: ${result.projectName}`);
+    console.log(`Output dir:   ${result.pbipDir}\n`);
+    console.log(`Would write ${result.planned.length} entries:`);
+    for (const entry of result.planned) {
+      console.log(`  ${entry.kind === 'directory' ? 'DIR ' : 'FILE'}  ${entry.to}`);
+    }
+    console.log('\nRun without --dry-run to apply changes.');
+    return;
+  }
+
+  console.log('BI Agent Superpowers — create-from-template');
+  console.log('===========================================\n');
+  console.log(`Template:     ${result.template}`);
+  console.log(`Project name: ${result.projectName}`);
+  console.log(`Output dir:   ${result.pbipDir}`);
+  console.log(`Wrote ${result.written.length} entries.`);
+  console.log(`Updated ${result.updatedJson.length} cross-reference files.\n`);
+  console.log('Next step:');
+  console.log(
+    `  1. Open ${path.join(result.pbipDir, result.projectName + '.pbip')} in Power BI Desktop`
+  );
+  console.log('  2. Verify the model loads and the report opens');
+  console.log('  3. Continue the bi-kickoff skill, or run a commit when ready');
+}
+
+async function createFromTemplateCommand(args, config = {}) {
+  let options;
+  try {
+    options = parseArgs(args || []);
+    const packageDir = config.packageDir || path.resolve(__dirname, '..', '..');
+
+    if (options.list) {
+      printList(packageDir, options.json);
+      return;
+    }
+
+    if (!options.templateName) {
+      throw new Error('--template is required. Run with --list to see available templates.');
+    }
+    if (!options.projectName) {
+      throw new Error('--name is required (the new project name).');
+    }
+
+    const result = scaffoldFromTemplate({
+      packageDir,
+      templateName: options.templateName,
+      targetDir: options.targetDir,
+      projectName: options.projectName,
+      force: options.force,
+      dryRun: options.dryRun,
+    });
+
+    printResult(result, options.json);
+  } catch (err) {
+    if (options && options.json) {
+      console.log(JSON.stringify({ error: err.message }, null, 2));
+    } else {
+      console.error(`Error: ${err.message}`);
+    }
+    process.exitCode = 1;
+  }
+}
+
+module.exports = Object.assign(createFromTemplateCommand, {
+  parseArgs,
+});