bi-superpowers 1.0.0

package/bin/lib/template-scaffold.js

@@ -0,0 +1,366 @@
+/**
+ * Template Scaffolding
+ * ====================
+ *
+ * Copies a packaged template (under `templates/<name>/`) into a user project
+ * as `<targetDir>/pbip-files/<projectName>.*`, renaming the PBIP descriptor,
+ * the `.SemanticModel/` and `.Report/` folders, and the internal cross-
+ * references that Power BI Desktop uses to wire the report to the model.
+ *
+ * Why this exists: the `bi-kickoff` skill needs a deterministic, testable
+ * way to bootstrap a new project from the BISuperpowers reference template
+ * without asking the agent to copy files by hand. PBIP rebinding is fiddly
+ * (two JSON files reference each other by relative path, plus two
+ * `.platform` files carry a displayName + logicalId) so this lives in code,
+ * not in markdown instructions.
+ *
+ * The function only writes inside `<targetDir>/pbip-files/`. It refuses to
+ * overwrite existing PBIP files unless `--force` is passed, regenerates
+ * Fabric logicalIds so two projects derived from the same template do not
+ * collide in Power BI Service, and skips the template's own `AGENTS.md`
+ * because `bi-kickoff` PHASE 5 writes a fresh one with the 8-rule contract.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const PROJECT_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const PBIP_SUBFOLDER = 'pbip-files';
+const TEMPLATE_AGENTS_FILE = 'AGENTS.md';
+const SKIPPED_ENTRY_NAMES = new Set(['.pbi', 'DAXQueries']);
+const SKIPPED_FILE_NAMES = new Set(['localSettings.json', 'cache.abf']);
+
+function getTemplatesRoot(packageDir) {
+  return path.join(packageDir, 'templates');
+}
+
+function listTemplates(packageDir) {
+  const root = getTemplatesRoot(packageDir);
+  if (!fs.existsSync(root)) {
+    return [];
+  }
+  const entries = fs.readdirSync(root, { withFileTypes: true });
+  const templates = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const templateDir = path.join(root, entry.name);
+    const pbip = findPbipFile(templateDir);
+    if (pbip) {
+      templates.push({
+        name: entry.name,
+        pbipFile: path.basename(pbip),
+        path: templateDir,
+      });
+    }
+  }
+  return templates.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function findPbipFile(templateDir) {
+  if (!fs.existsSync(templateDir)) return null;
+  const entries = fs.readdirSync(templateDir);
+  const pbip = entries.find((file) => file.toLowerCase().endsWith('.pbip'));
+  return pbip ? path.join(templateDir, pbip) : null;
+}
+
+function validateProjectName(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error('projectName is required.');
+  }
+  if (name.length > 64) {
+    throw new Error('projectName must be 64 characters or fewer.');
+  }
+  if (!PROJECT_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `projectName "${name}" is invalid. Use letters, digits, hyphen, or underscore; must start with a letter.`
+    );
+  }
+  return name;
+}
+
+function resolveTemplate(packageDir, templateName) {
+  if (!templateName) {
+    throw new Error('templateName is required.');
+  }
+  const templates = listTemplates(packageDir);
+  const match = templates.find((t) => t.name === templateName);
+  if (!match) {
+    const available = templates.map((t) => t.name).join(', ') || '(none)';
+    throw new Error(
+      `Template "${templateName}" not found in templates/. Available templates: ${available}.`
+    );
+  }
+  return match;
+}
+
+function getTemplatePrefix(template) {
+  // The .pbip filename without extension is the prefix shared by the
+  // SemanticModel and Report folders in every template that follows the
+  // BISuperpowers convention.
+  return path.basename(template.pbipFile, path.extname(template.pbipFile));
+}
+
+function getPbipDestination(targetDir) {
+  return path.join(targetDir, PBIP_SUBFOLDER);
+}
+
+function scaffoldFromTemplate({
+  packageDir,
+  templateName,
+  targetDir,
+  projectName,
+  force = false,
+  dryRun = false,
+}) {
+  const safeName = validateProjectName(projectName);
+  const template = resolveTemplate(packageDir, templateName);
+  const templatePrefix = getTemplatePrefix(template);
+
+  if (!targetDir || typeof targetDir !== 'string') {
+    throw new Error('targetDir is required.');
+  }
+  const resolvedTarget = path.resolve(targetDir);
+  if (!fs.existsSync(resolvedTarget)) {
+    throw new Error(`targetDir does not exist: ${resolvedTarget}`);
+  }
+  if (!fs.statSync(resolvedTarget).isDirectory()) {
+    throw new Error(`targetDir is not a directory: ${resolvedTarget}`);
+  }
+
+  const pbipDir = getPbipDestination(resolvedTarget);
+  const existingPbip = fs.existsSync(pbipDir) ? findPbipFile(pbipDir) : null;
+  if (existingPbip && !force) {
+    throw new Error(
+      `Refusing to overwrite existing PBIP file at ${existingPbip}. Pass force=true to replace.`
+    );
+  }
+
+  const plannedWrites = [];
+  const sourceRoot = template.path;
+  const entries = listTemplateEntries(sourceRoot);
+
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceRoot, entry.relativeFromTemplate);
+    const destRelative = renameRelative(entry.relativeFromTemplate, templatePrefix, safeName);
+    const destPath = path.join(pbipDir, destRelative);
+    plannedWrites.push({ sourcePath, destPath, kind: entry.kind, destRelative });
+  }
+
+  if (dryRun) {
+    return {
+      template: template.name,
+      projectName: safeName,
+      pbipDir,
+      planned: plannedWrites.map((entry) => ({
+        from: entry.sourcePath,
+        to: entry.destPath,
+        kind: entry.kind,
+      })),
+      written: [],
+      dryRun: true,
+    };
+  }
+
+  if (force && fs.existsSync(pbipDir)) {
+    removeDestinationProject({ pbipDir, projectName: safeName });
+  }
+
+  fs.mkdirSync(pbipDir, { recursive: true });
+
+  const written = [];
+  for (const entry of plannedWrites) {
+    if (entry.kind === 'directory') {
+      fs.mkdirSync(entry.destPath, { recursive: true });
+      written.push({ path: entry.destPath, action: 'mkdir' });
+    } else {
+      fs.mkdirSync(path.dirname(entry.destPath), { recursive: true });
+      const buffer = fs.readFileSync(entry.sourcePath);
+      fs.writeFileSync(entry.destPath, buffer);
+      written.push({ path: entry.destPath, action: 'copy' });
+    }
+  }
+
+  const updates = rewriteInternalReferences({
+    pbipDir,
+    projectName: safeName,
+    templatePrefix,
+  });
+
+  return {
+    template: template.name,
+    projectName: safeName,
+    pbipDir,
+    written,
+    updatedJson: updates,
+    dryRun: false,
+  };
+}
+
+function listTemplateEntries(sourceRoot) {
+  const results = [];
+
+  function walk(relative) {
+    const absolute = path.join(sourceRoot, relative);
+    const stat = fs.statSync(absolute);
+    if (stat.isDirectory()) {
+      if (relative !== '') {
+        results.push({ relativeFromTemplate: relative, kind: 'directory' });
+      }
+      const entries = fs.readdirSync(absolute, { withFileTypes: true });
+      for (const entry of entries) {
+        if (shouldSkipEntry(entry.name, relative)) continue;
+        walk(path.join(relative, entry.name));
+      }
+    } else if (stat.isFile()) {
+      results.push({ relativeFromTemplate: relative, kind: 'file' });
+    }
+  }
+
+  const topEntries = fs.readdirSync(sourceRoot, { withFileTypes: true });
+  for (const entry of topEntries) {
+    if (shouldSkipEntry(entry.name, '')) continue;
+    walk(entry.name);
+  }
+  return results;
+}
+
+function shouldSkipEntry(name, relativeDir) {
+  if (relativeDir === '' && name === TEMPLATE_AGENTS_FILE) {
+    return true;
+  }
+  if (SKIPPED_ENTRY_NAMES.has(name)) {
+    return true;
+  }
+  if (SKIPPED_FILE_NAMES.has(name)) {
+    return true;
+  }
+  return false;
+}
+
+function removeDestinationProject({ pbipDir, projectName }) {
+  const targets = [
+    path.join(pbipDir, `${projectName}.pbip`),
+    path.join(pbipDir, `${projectName}.SemanticModel`),
+    path.join(pbipDir, `${projectName}.Report`),
+  ];
+
+  for (const target of targets) {
+    assertPathInside(pbipDir, target);
+    if (fs.existsSync(target)) {
+      fs.rmSync(target, { recursive: true, force: true });
+    }
+  }
+}
+
+function assertPathInside(baseDir, targetPath) {
+  const resolvedBase = path.resolve(baseDir);
+  const resolvedTarget = path.resolve(targetPath);
+  const relative = path.relative(resolvedBase, resolvedTarget);
+  if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Refusing to remove path outside PBIP output directory: ${resolvedTarget}`);
+  }
+}
+
+function renameRelative(relative, templatePrefix, projectName) {
+  const segments = relative.split(path.sep);
+  const renamed = segments.map((segment) => {
+    if (segment === `${templatePrefix}.pbip`) {
+      return `${projectName}.pbip`;
+    }
+    if (segment === `${templatePrefix}.SemanticModel`) {
+      return `${projectName}.SemanticModel`;
+    }
+    if (segment === `${templatePrefix}.Report`) {
+      return `${projectName}.Report`;
+    }
+    return segment;
+  });
+  return renamed.join(path.sep);
+}
+
+function rewriteInternalReferences({ pbipDir, projectName, templatePrefix }) {
+  const updates = [];
+
+  const pbipPath = path.join(pbipDir, `${projectName}.pbip`);
+  if (fs.existsSync(pbipPath)) {
+    const pbip = readJson(pbipPath);
+    if (Array.isArray(pbip.artifacts)) {
+      for (const artifact of pbip.artifacts) {
+        if (
+          artifact &&
+          artifact.report &&
+          typeof artifact.report.path === 'string' &&
+          artifact.report.path === `${templatePrefix}.Report`
+        ) {
+          artifact.report.path = `${projectName}.Report`;
+        }
+      }
+    }
+    writeJson(pbipPath, pbip);
+    updates.push(pbipPath);
+  }
+
+  const pbirPath = path.join(pbipDir, `${projectName}.Report`, 'definition.pbir');
+  if (fs.existsSync(pbirPath)) {
+    const pbir = readJson(pbirPath);
+    if (
+      pbir &&
+      pbir.datasetReference &&
+      pbir.datasetReference.byPath &&
+      typeof pbir.datasetReference.byPath.path === 'string'
+    ) {
+      const expected = `../${templatePrefix}.SemanticModel`;
+      if (pbir.datasetReference.byPath.path === expected) {
+        pbir.datasetReference.byPath.path = `../${projectName}.SemanticModel`;
+      }
+    }
+    writeJson(pbirPath, pbir);
+    updates.push(pbirPath);
+  }
+
+  for (const folder of [`${projectName}.SemanticModel`, `${projectName}.Report`]) {
+    const platformPath = path.join(pbipDir, folder, '.platform');
+    if (!fs.existsSync(platformPath)) continue;
+    const platform = readJson(platformPath);
+    if (platform && platform.metadata && platform.metadata.displayName === templatePrefix) {
+      platform.metadata.displayName = projectName;
+    }
+    if (platform && platform.config && typeof platform.config.logicalId === 'string') {
+      platform.config.logicalId = crypto.randomUUID();
+    }
+    writeJson(platformPath, platform);
+    updates.push(platformPath);
+  }
+
+  return updates;
+}
+
+function readJson(filePath) {
+  let raw = fs.readFileSync(filePath, 'utf8');
+  // Power BI Desktop frequently re-saves PBIP/.pbir/.platform JSON with a UTF-8
+  // BOM; strip the leading U+FEFF code unit so JSON.parse doesn't throw on it.
+  if (raw.charCodeAt(0) === 0xfeff) {
+    raw = raw.slice(1);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Failed to parse JSON in ${filePath}: ${err.message}`);
+  }
+}
+
+function writeJson(filePath, value) {
+  const text = JSON.stringify(value, null, 2);
+  fs.writeFileSync(filePath, text + '\n');
+}
+
+module.exports = {
+  PBIP_SUBFOLDER,
+  PROJECT_NAME_PATTERN,
+  listTemplates,
+  validateProjectName,
+  resolveTemplate,
+  scaffoldFromTemplate,
+  getPbipDestination,
+};

package/bin/mcp/powerbi-modeling-launcher.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+/**
+ * Power BI Modeling MCP Launcher
+ * ==============================
+ *
+ * Wrapper that locates the official Microsoft Power BI Modeling MCP
+ * executable and starts it with stdio transport for Claude Code.
+ */
+
+const { spawn } = require('child_process');
+const { findLocalMcp, getModelingMcpError } = require('../utils/mcp-detect');
+
+const executablePath = findLocalMcp();
+
+if (!executablePath) {
+  console.error(getModelingMcpError());
+  process.exit(1);
+}
+
+const child = spawn(
+  executablePath,
+  ['--readwrite', '--skip-confirmation', ...process.argv.slice(2)],
+  {
+    stdio: 'inherit',
+    env: process.env,
+  }
+);
+
+child.on('error', (error) => {
+  console.error(`Failed to launch Power BI Modeling MCP: ${error.message}`);
+  process.exit(1);
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  process.exit(code === null ? 1 : code);
+});

package/bin/postinstall.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install script for BI Agent Superpowers
+ * Shows helpful information after npm install.
+ * Developed by Lucas Sanchez (@luquimbo)
+ */
+
+const path = require('path');
+const { loadSkills } = require('./lib/skills');
+const { getSkillPurpose } = require('./lib/generators/shared');
+
+const VERSION = require('../package.json').version;
+const PACKAGE_DIR = path.dirname(__dirname);
+
+const skills = loadSkills({ packageDir: PACKAGE_DIR });
+const skillLines = skills
+  .map((s) => `  /${s.name.padEnd(18)} — ${getSkillPurpose(s.name)}`)
+  .join('\n');
+
+console.log(`
+╔═══════════════════════════════════════════════════════════╗
+║                                                           ║
+║   BI Agent Superpowers v${VERSION.padEnd(34)}║
+║   Power BI Desktop toolkit — open source (MIT)            ║
+║   Developed by Lucas Sanchez (@luquimbo)                 ║
+║                                                           ║
+╚═══════════════════════════════════════════════════════════╝
+
+Installed successfully.
+
+Quick Start:
+  super install              # Install skills + MCPs in your AI agents
+
+Works with 5 agents:
+  • Claude Code
+  • GitHub Copilot
+  • Codex (OpenAI)
+  • Gemini CLI
+  • Kilo Code
+
+${skills.length} skills:
+${skillLines}
+
+2 MCP servers:
+  powerbi-modeling-mcp — Local Power BI Desktop connection (XMLA)
+  microsoft-learn      — Microsoft Learn docs in context
+
+Documentation: https://bi-superpowers.dev
+`);