@luquimbo/bi-superpowers 1.0.0

package/bin/lib/generators/shared.js

@@ -0,0 +1,282 @@
+/**
+ * Shared Generator Functions
+ * ==========================
+ *
+ * Common functions used by all AI tool generators.
+ *
+ * @module lib/generators/shared
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Extract skill metadata from markdown content
+ *
+ * Parses a skill file to extract:
+ * - title: From the first H1 heading
+ * - triggers: Array of activation phrases from the Trigger section
+ * - identity: The AI role description from the Identity section
+ *
+ * @param {string} content - Raw markdown content of skill file
+ * @returns {Object} Parsed metadata
+ */
+function parseSkillMetadata(content) {
+  const metadata = {
+    title: '',
+    triggers: [],
+    identity: '',
+  };
+
+  // Get title from first H1
+  const titleMatch = content.match(/^#\s+(.+)/m);
+  if (titleMatch) metadata.title = titleMatch[1];
+
+  // Get triggers
+  const triggerSection = content.match(/##\s+Trigger[\s\S]*?(?=##|$)/i);
+  if (triggerSection) {
+    const triggers = triggerSection[0].match(/[-*]\s+"([^"]+)"/g);
+    if (triggers) {
+      metadata.triggers = triggers.map((t) => t.replace(/[-*]\s+"/, '').replace('"', ''));
+    }
+  }
+
+  // Get identity
+  const identityMatch = content.match(/##\s+Identity[\s\S]*?(?=##|---)/i);
+  if (identityMatch) {
+    metadata.identity = identityMatch[0].replace(/##\s+Identity\s*/i, '').trim();
+  }
+
+  return metadata;
+}
+
+/**
+ * Get skill purpose description for table
+ * @param {string} skillName - Name of the skill
+ * @returns {string} Purpose description
+ */
+function getSkillPurpose(skillName) {
+  const purposes = {
+    dax: 'DAX writing and optimization',
+    'power-query': 'Power Query / M language patterns',
+    'data-modeling': 'Star schema design',
+    'data-model-design': 'Interactive model builder',
+    'excel-formulas': 'Modern Excel 365 formulas',
+    'project-kickoff': 'Project analysis and planning',
+    'theme-tweaker': 'Power BI theme customization',
+    'rls-design': 'Row-level security design',
+    'query-performance': 'Performance optimization',
+    'data-quality': 'Data validation and profiling',
+    'fabric-scripts': 'Fabric automation scripts',
+    'fast-standard': 'FAST spreadsheet standard',
+    'testing-validation': 'Testing and validation patterns',
+    'pbi-connect': 'Power BI Desktop connection',
+    contributions: 'Contribution validation',
+    // New command skills
+    'dax-doctor': 'DAX debugging and optimization wizard',
+    'model-documenter': 'Semantic model documentation generator',
+    'migration-assistant': 'Migration and upgrade assistant',
+    'report-layout': 'Report page layout planner',
+    // New reference skills
+    governance: 'Naming conventions, standards, and governance',
+    'semantic-model': 'Semantic model best practices and patterns',
+    'report-design': 'Report design and visualization principles',
+    deployment: 'CI/CD and deployment patterns for BI',
+    'dax-udf': 'DAX user-defined functions (UDFs)',
+  };
+  return purposes[skillName] || 'Specialized BI assistance';
+}
+
+/**
+ * Generate skills summary table for combined configs
+ * @param {Object[]} skills - Array of skill objects
+ * @returns {string} Markdown table
+ */
+function generateSkillsSection(skills) {
+  let section = `---
+
+## Available Skills
+
+When you detect these triggers, apply the corresponding skill knowledge:
+
+| Skill | Triggers | Purpose |
+|-------|----------|---------|
+`;
+
+  for (const skill of skills) {
+    const meta = parseSkillMetadata(skill.content);
+    const triggers =
+      meta.triggers
+        .slice(0, 3)
+        .map((t) => `"${t}"`)
+        .join(', ') || `"${skill.name}"`;
+    section += `| **${meta.title || skill.name}** | ${triggers} | ${getSkillPurpose(skill.name)} |\n`;
+  }
+
+  return section;
+}
+
+/**
+ * Get code standards section for combined configs
+ * @returns {string} Markdown code standards
+ */
+function getCodeStandards() {
+  return `---
+
+## Code Standards
+
+### DAX
+
+\`\`\`dax
+-- Use VAR/RETURN for clarity and performance
+SalesYoY =
+VAR _Current = [TotalSales]
+VAR _Prior = CALCULATE([TotalSales], SAMEPERIODLASTYEAR('Date'[Date]))
+RETURN DIVIDE(_Current - _Prior, _Prior)
+
+-- Always use DIVIDE for safe division
+Margin = DIVIDE([Profit], [Revenue], 0)
+
+-- Time intelligence
+Sales_YTD = TOTALYTD([TotalSales], 'Date'[Date])
+Sales_PY = CALCULATE([TotalSales], SAMEPERIODLASTYEAR('Date'[Date]))
+\`\`\`
+
+### Power Query
+
+\`\`\`powerquery
+let
+    Source = Sql.Database("server", "database"),
+    Filtered = Table.SelectRows(Source, each [Status] = "Active"),
+    Typed = Table.TransformColumnTypes(Filtered, {{"Date", type date}})
+in
+    Typed
+\`\`\`
+
+### Excel
+
+\`\`\`excel
+=XLOOKUP(A1, Table[ID], Table[Name], "Not Found")
+=FILTER(Data, Data[Status]="Active")
+=LET(x, SUM(A:A), y, COUNT(A:A), DIVIDE(x, y))
+\`\`\`
+
+### Naming Conventions
+
+| Element | Convention | Example |
+|---------|------------|---------|
+| Measures | PascalCase | \`TotalSales\` |
+| Tables | Singular | \`Customer\` |
+| Columns | PascalCase | \`OrderDate\` |
+| Variables | Underscore prefix | \`_Result\` |`;
+}
+
+/**
+ * Get format-specific header
+ * @param {string} format - Format type (cursor, copilot, chatgpt, generic)
+ * @param {number} skillCount - Number of skills
+ * @returns {string} Header content
+ */
+function getFormatHeader(format, skillCount) {
+  const headers = {
+    cursor: `# BI Agent Superpowers - Cursor Rules
+
+You are a Business Intelligence Expert with deep knowledge of Power BI, Microsoft Fabric, and Excel.
+Generated automatically from ${skillCount} skill definitions.`,
+
+    copilot: `# BI Agent Superpowers - GitHub Copilot Instructions
+
+You are a Business Intelligence Expert specializing in Power BI, Microsoft Fabric, and Excel development.
+Generated automatically from ${skillCount} skill definitions.`,
+
+    chatgpt: `# BI Agent Superpowers - ChatGPT Custom Instructions
+
+Copy this content to ChatGPT > Settings > Personalization > Custom Instructions.
+
+You are a Business Intelligence Expert specializing in Power BI, Microsoft Fabric, and Excel.`,
+
+    generic: `# BI Agent Superpowers - AI Context
+
+Universal context for any AI assistant working with Business Intelligence development.
+Generated automatically from ${skillCount} skill definitions.`,
+  };
+  return headers[format] || headers.generic;
+}
+
+/**
+ * Get format-specific footer
+ * @returns {string} Footer content
+ */
+function getFormatFooter() {
+  return `---
+
+## Resources
+
+- Library: \`library/snippets/\` - DAX, Power Query, Excel patterns
+- Themes: \`library/themes/power-bi/\` - JSON theme files
+- Examples: \`library/examples/\` - Reference implementations
+
+---
+
+**BI Agent Superpowers** - Developed by Lucas Sanchez (@luquimbo)
+https://github.com/luquimbo/bi-superpowers`;
+}
+
+/**
+ * Generate combined configuration for tools that use a single file
+ * @param {Object[]} skills - Array of skill objects
+ * @param {string} format - Format type (cursor, copilot, chatgpt, generic)
+ * @returns {string} Combined markdown content
+ */
+function generateCombinedConfig(skills, format) {
+  const header = getFormatHeader(format, skills.length);
+  const skillsSection = generateSkillsSection(skills);
+  const codeStandards = getCodeStandards();
+  const footer = getFormatFooter();
+
+  return `${header}
+
+${skillsSection}
+
+${codeStandards}
+
+${footer}`;
+}
+
+/**
+ * Create symlink to content cache directory for easy access to library
+ * @param {string} targetDir - Project directory path
+ * @param {string} contentCacheDir - Content cache directory path
+ * @param {string} symlinkName - Name of the symlink to create
+ */
+function createSymlink(targetDir, contentCacheDir, symlinkName) {
+  const linkPath = path.join(targetDir, symlinkName);
+  // Remove existing symlink if it exists
+  if (fs.existsSync(linkPath)) {
+    try {
+      fs.unlinkSync(linkPath);
+    } catch (e) {
+      // Ignore errors
+    }
+  }
+  try {
+    fs.symlinkSync(contentCacheDir, linkPath, 'dir');
+    console.log(`  ✓ Created ${symlinkName} symlink`);
+  } catch (e) {
+    // Symlink may fail on Windows without admin rights
+    if (process.env.DEBUG === 'true') {
+      console.error(`[DEBUG] Failed to create symlink: ${e.message}`);
+    }
+  }
+}
+
+module.exports = {
+  parseSkillMetadata,
+  getSkillPurpose,
+  generateSkillsSection,
+  getCodeStandards,
+  getFormatHeader,
+  getFormatFooter,
+  generateCombinedConfig,
+  createSymlink,
+};

package/bin/lib/licensing/index.js

@@ -0,0 +1,35 @@
+/**
+ * Licensing Module
+ * =================
+ *
+ * Unified exports for all licensing-related functionality.
+ *
+ * @module lib/licensing
+ */
+
+const storage = require('./storage');
+const validator = require('./validator');
+
+module.exports = {
+  // Storage functions
+  loadLicense: storage.loadLicense,
+  saveLicense: storage.saveLicense,
+  clearLicense: storage.clearLicense,
+  isContentInstalled: storage.isContentInstalled,
+  downloadPremiumContent: storage.downloadPremiumContent,
+  getContentCacheDir: storage.getContentCacheDir,
+  getSkillsDir: storage.getSkillsDir,
+  getLicenseFile: storage.getLicenseFile,
+
+  // Validator functions
+  makeRequest: validator.makeRequest,
+  validateLicense: validator.validateLicense,
+  requireLicense: validator.requireLicense,
+  getApiBaseUrl: validator.getApiBaseUrl,
+
+  // Constants
+  LICENSE_FILE: storage.LICENSE_FILE,
+  CONTENT_CACHE_DIR: storage.CONTENT_CACHE_DIR,
+  SKILLS_DIR: storage.SKILLS_DIR,
+  API_BASE_URL: validator.API_BASE_URL,
+};

package/bin/lib/licensing/storage.js

@@ -0,0 +1,364 @@
+/**
+ * License Storage Module
+ * ======================
+ *
+ * Handles license persistence and premium content management.
+ * Licenses are stored in ~/.bi-superpowers-license as JSON.
+ *
+ * @module lib/licensing/storage
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const https = require('https');
+const AdmZip = require('adm-zip');
+
+/** Path to the license file stored in user's home directory */
+const LICENSE_FILE = path.join(os.homedir(), '.bi-superpowers-license');
+
+/** Directory for cached premium content (skills, snippets, themes) */
+const CONTENT_CACHE_DIR = path.join(os.homedir(), '.bi-superpowers');
+
+/** Directory containing skill definition files (.md) */
+const SKILLS_DIR = path.join(CONTENT_CACHE_DIR, '.agents', 'prompts', 'skills');
+
+/**
+ * Load saved license from disk
+ *
+ * Reads the license file from the user's home directory. The license contains:
+ * - license: The license key string
+ * - email: User's email address
+ * - name: User's name (optional)
+ * - activatedAt: ISO timestamp of activation
+ * - contentVersion: Version when content was last downloaded
+ *
+ * @returns {Object|null} License data object or null if not found/invalid
+ */
+function loadLicense() {
+  try {
+    if (fs.existsSync(LICENSE_FILE)) {
+      const data = JSON.parse(fs.readFileSync(LICENSE_FILE, 'utf8'));
+      return data;
+    }
+  } catch (e) {
+    if (process.env.DEBUG === 'true') {
+      console.error(`[DEBUG] Failed to load license: ${e.message}`);
+    }
+  }
+  return null;
+}
+
+/**
+ * Save license to disk
+ *
+ * Persists license data to ~/.bi-superpowers-license for future sessions.
+ *
+ * @param {Object} data - License data to save
+ * @param {string} data.license - The license key
+ * @param {string} data.email - User's email
+ * @param {string} [data.name] - User's name
+ * @param {string} data.activatedAt - Activation timestamp
+ * @param {string} data.contentVersion - Content version
+ */
+function saveLicense(data) {
+  fs.writeFileSync(LICENSE_FILE, JSON.stringify(data, null, 2));
+}
+
+/**
+ * Clear saved license from disk
+ *
+ * Removes the license file, effectively logging out the user.
+ * Used when a license becomes invalid or user wants to switch accounts.
+ */
+function clearLicense() {
+  try {
+    if (fs.existsSync(LICENSE_FILE)) {
+      fs.unlinkSync(LICENSE_FILE);
+    }
+  } catch (e) {
+    if (process.env.DEBUG === 'true') {
+      console.error(`[DEBUG] Failed to clear license: ${e.message}`);
+    }
+  }
+}
+
+/**
+ * Check if premium content is installed
+ *
+ * Verifies that the skills directory exists and contains at least one .md file.
+ * Used to determine if content needs to be downloaded during license validation.
+ *
+ * @returns {boolean} True if skills directory exists with content
+ */
+function isContentInstalled() {
+  return (
+    fs.existsSync(SKILLS_DIR) &&
+    fs.readdirSync(SKILLS_DIR).filter((f) => f.endsWith('.md')).length > 0
+  );
+}
+
+/**
+ * Download file from URL to local filesystem
+ *
+ * Streams the response directly to a file to handle large downloads efficiently.
+ * Automatically follows HTTP 301/302 redirects.
+ *
+ * @param {string} url - URL of the file to download
+ * @param {string} destPath - Local path where file will be saved
+ * @returns {Promise<void>} Resolves when download is complete
+ * @throws {Error} On network errors or non-200 status codes
+ */
+function downloadFile(url, destPath) {
+  return downloadFileInternal(url, destPath, 0);
+}
+
+/**
+ * Resolve a redirect Location header to an absolute URL.
+ *
+ * @param {string|URL} currentUrl - The current request URL
+ * @param {string} location - The Location header value
+ * @returns {string} Absolute URL string
+ */
+function resolveRedirectUrl(currentUrl, location) {
+  const baseUrl = currentUrl instanceof URL ? currentUrl : new URL(currentUrl);
+  return new URL(location, baseUrl).toString();
+}
+
+function safeUnlink(filePath) {
+  try {
+    fs.unlinkSync(filePath);
+  } catch (e) {
+    // Ignore missing file or cleanup failures
+  }
+}
+
+function downloadFileInternal(url, destPath, redirectCount) {
+  return new Promise((resolve, reject) => {
+    const urlObj = new URL(url);
+    if (urlObj.protocol !== 'https:') {
+      reject(new Error(`Insecure download URL (HTTPS required): ${url}`));
+      return;
+    }
+
+    const MAX_REDIRECTS = 5;
+    const TIMEOUT_MS = 30000;
+    const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+
+    const request = https.get(urlObj, (response) => {
+      const status = response.statusCode || 0;
+
+      // Handle redirects (including relative Location headers)
+      if (REDIRECT_STATUSES.has(status)) {
+        response.resume();
+
+        if (redirectCount >= MAX_REDIRECTS) {
+          reject(new Error(`Download failed: too many redirects (${MAX_REDIRECTS})`));
+          return;
+        }
+
+        const location = response.headers.location;
+        if (!location) {
+          reject(new Error(`Download failed: redirect (${status}) without Location header`));
+          return;
+        }
+
+        const nextUrl = resolveRedirectUrl(urlObj, location);
+        downloadFileInternal(nextUrl, destPath, redirectCount + 1)
+          .then(resolve)
+          .catch(reject);
+        return;
+      }
+
+      if (status !== 200) {
+        response.resume();
+        reject(new Error(`Download failed with status ${status}`));
+        return;
+      }
+
+      // Only create the output file once we know the response is successful.
+      const file = fs.createWriteStream(destPath);
+
+      file.on('error', (err) => {
+        response.destroy();
+        file.close(() => {
+          safeUnlink(destPath);
+          reject(err);
+        });
+      });
+
+      response.on('error', (err) => {
+        file.close(() => {
+          safeUnlink(destPath);
+          reject(err);
+        });
+      });
+
+      response.pipe(file);
+
+      file.on('finish', () => {
+        file.close(() => resolve());
+      });
+    });
+
+    request.setTimeout(TIMEOUT_MS, () => {
+      request.destroy(new Error(`Download request timed out after ${TIMEOUT_MS}ms`));
+    });
+
+    request.on('error', (err) => {
+      safeUnlink(destPath);
+      reject(err);
+    });
+  });
+}
+
+/**
+ * Extract ZIP file to destination directory
+ * Uses native unzip command (macOS/Linux) or PowerShell (Windows)
+ *
+ * Security: Uses spawnSync with array arguments to prevent command injection
+ *
+ * @param {string} zipPath - Path to the ZIP file to extract
+ * @param {string} destDir - Destination directory for extraction
+ * @returns {Promise<void>} Resolves when extraction is complete
+ * @throws {Error} If extraction fails
+ */
+function isUnsafeZipEntry(entryName, destRoot) {
+  if (!entryName) return true;
+
+  const normalized = entryName.replace(/\\/g, '/');
+
+  // Disallow absolute paths and Windows drive letters
+  if (normalized.startsWith('/') || normalized.startsWith('\\')) return true;
+  if (/^[A-Za-z]:/.test(normalized)) return true;
+  if (normalized.startsWith('//')) return true;
+
+  const targetPath = path.resolve(destRoot, entryName);
+  const relative = path.relative(destRoot, targetPath);
+
+  return relative.startsWith('..') || path.isAbsolute(relative);
+}
+
+function extractZip(zipPath, destDir) {
+  return new Promise((resolve, reject) => {
+    try {
+      // Ensure destination directory exists
+      if (!fs.existsSync(destDir)) {
+        fs.mkdirSync(destDir, { recursive: true });
+      }
+
+      const destRoot = path.resolve(destDir);
+      const zip = new AdmZip(zipPath);
+      const entries = zip.getEntries();
+
+      for (const entry of entries) {
+        if (isUnsafeZipEntry(entry.entryName, destRoot)) {
+          throw new Error(`Unsafe ZIP entry detected: ${entry.entryName}`);
+        }
+      }
+
+      zip.extractAllTo(destRoot, true);
+
+      resolve();
+    } catch (error) {
+      reject(new Error(`Failed to extract ZIP safely: ${error.message}`));
+    }
+  });
+}
+
+/**
+ * Download and install premium content from license server
+ *
+ * This function:
+ * 1. Creates the content cache directory if needed
+ * 2. Downloads a ZIP file containing skills, snippets, themes, etc.
+ * 3. Extracts the ZIP to ~/.bi-superpowers/
+ * 4. Cleans up the temporary ZIP file
+ * 5. Verifies the skills directory was created correctly
+ *
+ * @param {string} downloadUrl - URL provided by license validation API
+ * @returns {Promise<boolean>} True if download and extraction succeeded
+ */
+async function downloadPremiumContent(downloadUrl) {
+  console.log('Downloading premium content...');
+
+  // Ensure cache directory exists
+  if (!fs.existsSync(CONTENT_CACHE_DIR)) {
+    fs.mkdirSync(CONTENT_CACHE_DIR, { recursive: true });
+  }
+
+  const zipPath = path.join(CONTENT_CACHE_DIR, 'content.zip');
+
+  try {
+    // Download the ZIP file
+    await downloadFile(downloadUrl, zipPath);
+    console.log('✓ Download complete');
+
+    // Extract the ZIP file
+    console.log('Extracting content...');
+    await extractZip(zipPath, CONTENT_CACHE_DIR);
+    console.log('✓ Extraction complete');
+
+    // Clean up ZIP file
+    fs.unlinkSync(zipPath);
+
+    // Verify skills directory exists
+    if (!fs.existsSync(SKILLS_DIR)) {
+      throw new Error('Skills directory not found after extraction');
+    }
+
+    const skillCount = fs.readdirSync(SKILLS_DIR).filter((f) => f.endsWith('.md')).length;
+    console.log(`✓ ${skillCount} skills installed`);
+
+    return true;
+  } catch (error) {
+    console.error('Content download failed:', error.message);
+    // Clean up failed download
+    if (fs.existsSync(zipPath)) {
+      fs.unlinkSync(zipPath);
+    }
+    return false;
+  }
+}
+
+/**
+ * Get the content cache directory path
+ * @returns {string} Path to content cache
+ */
+function getContentCacheDir() {
+  return CONTENT_CACHE_DIR;
+}
+
+/**
+ * Get the skills directory path
+ * @returns {string} Path to skills directory
+ */
+function getSkillsDir() {
+  return SKILLS_DIR;
+}
+
+/**
+ * Get the license file path
+ * @returns {string} Path to license file
+ */
+function getLicenseFile() {
+  return LICENSE_FILE;
+}
+
+module.exports = {
+  loadLicense,
+  saveLicense,
+  clearLicense,
+  isContentInstalled,
+  downloadFile,
+  extractZip,
+  downloadPremiumContent,
+  getContentCacheDir,
+  getSkillsDir,
+  getLicenseFile,
+  _isUnsafeZipEntry: isUnsafeZipEntry,
+  _resolveRedirectUrl: resolveRedirectUrl,
+  LICENSE_FILE,
+  CONTENT_CACHE_DIR,
+  SKILLS_DIR,
+};