@luquimbo/bi-superpowers 1.0.0

package/bin/utils/logger.js

@@ -0,0 +1,142 @@
+/**
+ * Logger Utility
+ * ===============
+ *
+ * Standardized logging for the CLI with log levels.
+ * Respects LOG_LEVEL environment variable.
+ *
+ * Usage:
+ *   const logger = require('./utils/logger');
+ *   logger.debug('Debug message', { context: 'optional' });
+ *   logger.info('Info message');
+ *   logger.warn('Warning message');
+ *   logger.error('Error message');
+ *
+ * Environment:
+ *   LOG_LEVEL=debug|info|warn|error (default: info)
+ *   DEBUG=true (shorthand for LOG_LEVEL=debug)
+ *
+ * @module utils/logger
+ */
+
+const LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  silent: 4,
+};
+
+/**
+ * Get current log level from environment
+ * @returns {string} Current log level
+ */
+function getCurrentLevel() {
+  if (process.env.DEBUG === 'true') {
+    return 'debug';
+  }
+  return process.env.LOG_LEVEL || 'info';
+}
+
+/**
+ * Check if a log level should be shown
+ * @param {string} level - Level to check
+ * @returns {boolean} Whether to show this level
+ */
+function shouldLog(level) {
+  const currentLevel = getCurrentLevel();
+  return LOG_LEVELS[level] >= LOG_LEVELS[currentLevel];
+}
+
+/**
+ * Format a log message with optional context
+ * @param {string} prefix - Log level prefix
+ * @param {string} message - Log message
+ * @param {Object|null} context - Optional context object
+ * @returns {string} Formatted message
+ */
+function formatMessage(prefix, message, context) {
+  let formatted = `[${prefix}] ${message}`;
+  if (context !== null && context !== undefined) {
+    if (typeof context === 'object') {
+      formatted += ` ${JSON.stringify(context)}`;
+    } else {
+      formatted += ` ${context}`;
+    }
+  }
+  return formatted;
+}
+
+/**
+ * Debug level logging
+ * Only shown when LOG_LEVEL=debug or DEBUG=true
+ * @param {string} message - Log message
+ * @param {Object|null} context - Optional context
+ */
+function debug(message, context = null) {
+  if (shouldLog('debug')) {
+    console.log(formatMessage('DEBUG', message, context));
+  }
+}
+
+/**
+ * Info level logging
+ * Standard informational messages
+ * @param {string} message - Log message
+ * @param {Object|null} context - Optional context
+ */
+function info(message, context = null) {
+  if (shouldLog('info')) {
+    console.log(formatMessage('INFO', message, context));
+  }
+}
+
+/**
+ * Warning level logging
+ * Non-critical issues that should be noticed
+ * @param {string} message - Log message
+ * @param {Object|null} context - Optional context
+ */
+function warn(message, context = null) {
+  if (shouldLog('warn')) {
+    console.warn(formatMessage('WARN', message, context));
+  }
+}
+
+/**
+ * Error level logging
+ * Critical errors that affect operation
+ * @param {string} message - Log message
+ * @param {Object|null} context - Optional context
+ */
+function error(message, context = null) {
+  if (shouldLog('error')) {
+    console.error(formatMessage('ERROR', message, context));
+  }
+}
+
+/**
+ * Create a child logger with a prefix
+ * Useful for module-specific logging
+ * @param {string} prefix - Prefix for all messages
+ * @returns {Object} Logger instance with prefix
+ */
+function createLogger(prefix) {
+  return {
+    debug: (msg, ctx) => debug(`[${prefix}] ${msg}`, ctx),
+    info: (msg, ctx) => info(`[${prefix}] ${msg}`, ctx),
+    warn: (msg, ctx) => warn(`[${prefix}] ${msg}`, ctx),
+    error: (msg, ctx) => error(`[${prefix}] ${msg}`, ctx),
+  };
+}
+
+module.exports = {
+  LOG_LEVELS,
+  debug,
+  info,
+  warn,
+  error,
+  createLogger,
+  getCurrentLevel,
+  shouldLog,
+};

package/bin/utils/mcp-detect.js

@@ -0,0 +1,274 @@
+/**
+ * MCP Detection Utilities for BI Agent Superpowers
+ * =================================================
+ *
+ * Detects installed MCP servers (Microsoft Power BI Modeling MCP).
+ * Supports both local (VS Code extension) and remote (Fabric) MCPs.
+ *
+ * @module utils/mcp-detect
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawnSync } = require('child_process');
+const {
+  PLUGIN_ROOT_LAUNCHER_MODE,
+  REMOTE_POWERBI_URL,
+  createMcpConfigForFormat,
+} = require('../lib/microsoft-mcp');
+
+/**
+ * Common installation paths for the Power BI Modeling MCP
+ */
+const EXTENSION_PATTERNS = [
+  // VS Code extensions folder
+  path.join(os.homedir(), '.vscode', 'extensions'),
+  // Cursor extensions folder
+  path.join(os.homedir(), '.cursor', 'extensions'),
+  // VS Code Insiders
+  path.join(os.homedir(), '.vscode-insiders', 'extensions'),
+  // Manual installation path we suggest
+  path.join(os.homedir(), '.bi-superpowers', 'mcp'),
+];
+
+/**
+ * Extension name pattern to search for
+ */
+const EXTENSION_NAME_PATTERN = /^analysis-services\.powerbi-modeling-mcp-/;
+
+const MODELING_MCP_ENV_VARS = [
+  'BI_SUPERPOWERS_POWERBI_MODELING_MCP_PATH',
+  'POWERBI_MODELING_MCP_PATH',
+  'PBI_MODELING_MCP_PATH',
+];
+
+/**
+ * Resolve an explicitly configured MCP executable path, if any.
+ *
+ * @returns {string|null} Existing executable path
+ */
+function getExplicitMcpPath() {
+  for (const envVar of MODELING_MCP_ENV_VARS) {
+    const configuredPath = process.env[envVar];
+    if (configuredPath && fs.existsSync(configuredPath)) {
+      return configuredPath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Find the Power BI Modeling MCP executable
+ * @returns {string|null} Path to the executable or null if not found
+ */
+function findLocalMcp() {
+  const explicitPath = getExplicitMcpPath();
+  if (explicitPath) {
+    return explicitPath;
+  }
+
+  if (os.platform() !== 'win32') {
+    return null;
+  }
+
+  for (const extensionsDir of EXTENSION_PATTERNS) {
+    if (!fs.existsSync(extensionsDir)) {
+      continue;
+    }
+
+    try {
+      const entries = fs.readdirSync(extensionsDir);
+
+      for (const entry of entries) {
+        if (EXTENSION_NAME_PATTERN.test(entry)) {
+          // Found the extension folder
+          const exePath = path.join(extensionsDir, entry, 'server', 'powerbi-modeling-mcp.exe');
+
+          if (fs.existsSync(exePath)) {
+            return exePath;
+          }
+
+          // Alternative path structure
+          const altExePath = path.join(
+            extensionsDir,
+            entry,
+            'extension',
+            'server',
+            'powerbi-modeling-mcp.exe'
+          );
+
+          if (fs.existsSync(altExePath)) {
+            return altExePath;
+          }
+        }
+      }
+    } catch (e) {
+      // Ignore read errors
+    }
+  }
+
+  // Check if it's in PATH
+  try {
+    const result = spawnSync('where', ['powerbi-modeling-mcp.exe'], {
+      encoding: 'utf8',
+      shell: true,
+    });
+
+    if (result.status === 0 && result.stdout) {
+      const firstLine = result.stdout.trim().split('\n')[0];
+      if (firstLine && fs.existsSync(firstLine)) {
+        return firstLine;
+      }
+    }
+  } catch (e) {
+    // Ignore errors
+  }
+
+  return null;
+}
+
+/**
+ * Get version from MCP executable
+ * @param {string} exePath - Path to the executable
+ * @returns {string|null} Version string or null
+ */
+function getMcpVersion(exePath) {
+  if (!exePath || !fs.existsSync(exePath)) {
+    return null;
+  }
+
+  try {
+    const result = spawnSync(exePath, ['--version'], {
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+
+    if (result.stdout) {
+      const match = result.stdout.match(/\d+\.\d+\.\d+/);
+      return match ? match[0] : null;
+    }
+  } catch (e) {
+    // Ignore errors
+  }
+
+  // Try to extract version from path
+  const match = exePath.match(/powerbi-modeling-mcp-(\d+\.\d+\.\d+)/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Get full MCP status
+ * @returns {Object} Status object with local and remote info
+ */
+function getMcpStatus() {
+  const localPath = findLocalMcp();
+
+  return {
+    local: {
+      installed: !!localPath,
+      path: localPath,
+      version: getMcpVersion(localPath),
+      platform: os.platform(),
+      available: os.platform() === 'win32',
+      envVars: MODELING_MCP_ENV_VARS,
+    },
+    remote: {
+      available: true, // Always available (requires auth)
+      url: REMOTE_POWERBI_URL,
+      requiresAuth: true,
+      description: 'Power BI Remote MCP (Fabric)',
+    },
+    fabric: {
+      available: true,
+      package: '@microsoft/fabric-mcp@latest',
+      description: 'Microsoft Fabric MCP Server',
+    },
+  };
+}
+
+/**
+ * Get installation instructions for local MCP
+ * @returns {Object} Installation instructions
+ */
+function getInstallInstructions() {
+  return {
+    title: 'Power BI Modeling MCP no detectado',
+    options: [
+      {
+        name: 'VS Code / Cursor',
+        steps: [
+          'Abrir VS Code o Cursor',
+          'Ir a Extensions (Ctrl+Shift+X)',
+          'Buscar "Power BI Modeling MCP"',
+          'Instalar la extensión de Microsoft',
+          'Ejecutar: super mcp-setup',
+        ],
+        link: 'https://aka.ms/powerbi-modeling-mcp-vscode',
+      },
+      {
+        name: 'Manual',
+        steps: [
+          'Descargar VSIX desde VS Code Marketplace',
+          'Renombrar .vsix a .zip',
+          `Extraer a ${path.join(os.homedir(), '.bi-superpowers', 'mcp')}`,
+          'Configurar BI_SUPERPOWERS_POWERBI_MODELING_MCP_PATH con la ruta al .exe',
+        ],
+        link: 'https://marketplace.visualstudio.com/items?itemName=analysis-services.powerbi-modeling-mcp',
+      },
+    ],
+    note:
+      os.platform() !== 'win32'
+        ? 'El MCP local solo está disponible en Windows. Puedes usar el MCP Remoto de Fabric en Mac/Linux.'
+        : null,
+  };
+}
+
+/**
+ * Build an actionable error for environments where the local Modeling MCP
+ * executable isn't available.
+ *
+ * @returns {string} Human-friendly error message
+ */
+function getModelingMcpError() {
+  if (os.platform() !== 'win32') {
+    return [
+      'Power BI Modeling MCP is only available on Windows.',
+      'You can still use the official powerbi-remote and fabric-mcp-server entries on macOS/Linux.',
+      'If you are on Windows and extracted the server manually, set BI_SUPERPOWERS_POWERBI_MODELING_MCP_PATH.',
+    ].join('\n');
+  }
+
+  return [
+    'Unable to locate the official Microsoft Power BI Modeling MCP executable.',
+    'Install the "Power BI Modeling MCP" extension in VS Code or Cursor, or set BI_SUPERPOWERS_POWERBI_MODELING_MCP_PATH to powerbi-modeling-mcp.exe.',
+  ].join('\n');
+}
+
+/**
+ * Backward-compatible config generator retained for legacy callers/tests.
+ *
+ * @param {Object} _status - Unused, kept for compatibility
+ * @param {string} format - Config format (cursor, claude, vscode, etc.)
+ * @param {Object} [options] - Additional generation options
+ * @returns {Object} Configuration object
+ */
+function generateMcpConfig(_status, format, options = {}) {
+  return createMcpConfigForFormat(format, {
+    packageDir: options.packageDir,
+    launcherMode: options.launcherMode || PLUGIN_ROOT_LAUNCHER_MODE,
+  });
+}
+
+module.exports = {
+  findLocalMcp,
+  getMcpVersion,
+  getMcpStatus,
+  getInstallInstructions,
+  generateMcpConfig,
+  getExplicitMcpPath,
+  getModelingMcpError,
+  MODELING_MCP_ENV_VARS,
+  REMOTE_POWERBI_URL,
+};

package/bin/utils/mcp-detect.test.js

@@ -0,0 +1,105 @@
+/**
+ * Tests for MCP Detection Utilities
+ * @module utils/mcp-detect.test
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert');
+
+const mcpDetect = require('./mcp-detect');
+
+describe('MCP Detection Utilities', () => {
+  test('exports expected functions', () => {
+    assert.strictEqual(typeof mcpDetect.findLocalMcp, 'function');
+    assert.strictEqual(typeof mcpDetect.getMcpVersion, 'function');
+    assert.strictEqual(typeof mcpDetect.getMcpStatus, 'function');
+    assert.strictEqual(typeof mcpDetect.getInstallInstructions, 'function');
+    assert.strictEqual(typeof mcpDetect.generateMcpConfig, 'function');
+    assert.strictEqual(typeof mcpDetect.getExplicitMcpPath, 'function');
+    assert.strictEqual(typeof mcpDetect.getModelingMcpError, 'function');
+  });
+
+  test('exports official remote url and env vars', () => {
+    assert.strictEqual(typeof mcpDetect.REMOTE_POWERBI_URL, 'string');
+    assert.strictEqual(
+      mcpDetect.REMOTE_POWERBI_URL,
+      'https://api.fabric.microsoft.com/v1/mcp/powerbi'
+    );
+    assert.ok(Array.isArray(mcpDetect.MODELING_MCP_ENV_VARS));
+    assert.ok(mcpDetect.MODELING_MCP_ENV_VARS.includes('BI_SUPERPOWERS_POWERBI_MODELING_MCP_PATH'));
+  });
+});
+
+describe('getMcpStatus', () => {
+  test('returns expected structure', () => {
+    const status = mcpDetect.getMcpStatus();
+
+    assert.ok(status.local);
+    assert.ok(status.remote);
+    assert.ok(status.fabric);
+
+    assert.ok('installed' in status.local);
+    assert.ok('path' in status.local);
+    assert.ok('version' in status.local);
+    assert.ok('platform' in status.local);
+    assert.ok('available' in status.local);
+    assert.ok(Array.isArray(status.local.envVars));
+
+    assert.strictEqual(status.remote.available, true);
+    assert.strictEqual(status.remote.url, mcpDetect.REMOTE_POWERBI_URL);
+    assert.strictEqual(status.remote.requiresAuth, true);
+
+    assert.strictEqual(status.fabric.available, true);
+    assert.strictEqual(status.fabric.package, '@microsoft/fabric-mcp@latest');
+  });
+});
+
+describe('getInstallInstructions', () => {
+  test('returns expected structure', () => {
+    const instructions = mcpDetect.getInstallInstructions();
+
+    assert.ok(instructions.title);
+    assert.ok(Array.isArray(instructions.options));
+    assert.ok(instructions.options.length > 0);
+
+    instructions.options.forEach((option) => {
+      assert.ok(option.name);
+      assert.ok(Array.isArray(option.steps));
+      assert.ok(option.link);
+    });
+  });
+});
+
+describe('generateMcpConfig', () => {
+  test('generates plugin format with official Microsoft MCPs', () => {
+    const config = mcpDetect.generateMcpConfig({}, 'plugin');
+
+    assert.ok(config['powerbi-remote']);
+    assert.ok(config['fabric-mcp-server']);
+    assert.ok(config['powerbi-modeling-mcp']);
+
+    assert.strictEqual(config['powerbi-remote'].type, 'http');
+    assert.strictEqual(config['powerbi-remote'].url, mcpDetect.REMOTE_POWERBI_URL);
+    assert.strictEqual(config['fabric-mcp-server'].command, 'npx');
+    assert.deepStrictEqual(config['fabric-mcp-server'].args, [
+      '-y',
+      '@microsoft/fabric-mcp@latest',
+      'server',
+      'start',
+      '--mode',
+      'all',
+    ]);
+    assert.strictEqual(config['powerbi-modeling-mcp'].type, 'stdio');
+    assert.strictEqual(config['powerbi-modeling-mcp'].command, 'node');
+    assert.ok(config['powerbi-modeling-mcp'].args[0].includes('powerbi-modeling-launcher.js'));
+  });
+
+  test('generates claude format with nested mcpServers object', () => {
+    const config = mcpDetect.generateMcpConfig({}, 'claude');
+
+    assert.ok(config.mcpServers);
+    assert.ok(config.mcpServers['powerbi-remote']);
+    assert.ok(config.mcpServers['fabric-mcp-server']);
+    assert.ok(config.mcpServers['powerbi-modeling-mcp']);
+  });
+});