bi-superpowers 1.0.0

package/bin/utils/mcp-detect.js

@@ -0,0 +1,346 @@
+/**
+ * MCP Detection Utilities for BI Agent Superpowers
+ * =================================================
+ *
+ * Detects installed MCP servers (Microsoft Power BI Modeling MCP).
+ * Covers the local (Windows) VS Code/Cursor extension install path.
+ *
+ * @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, 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_EXE_NAME = 'powerbi-modeling-mcp.exe';
+
+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 = normalizeConfiguredPath(process.env[envVar]);
+    if (configuredPath && isMcpExecutableFile(configuredPath)) {
+      return configuredPath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Normalize common shell/user input around executable paths.
+ *
+ * @param {string|undefined} configuredPath - Environment variable value
+ * @returns {string|null} Trimmed path without surrounding quotes
+ */
+function normalizeConfiguredPath(configuredPath) {
+  if (!configuredPath) {
+    return null;
+  }
+
+  const trimmedPath = configuredPath.trim();
+  const quotedPath = trimmedPath.match(/^"(.*)"$/);
+  return quotedPath ? quotedPath[1] : trimmedPath;
+}
+
+/**
+ * Check whether a path points to the official local Modeling MCP executable.
+ *
+ * @param {string|null} candidatePath - Candidate executable path
+ * @returns {boolean} True when the path is an executable file candidate
+ */
+function isMcpExecutableFile(candidatePath) {
+  if (!candidatePath || path.basename(candidatePath).toLowerCase() !== MODELING_MCP_EXE_NAME) {
+    return false;
+  }
+
+  try {
+    return fs.statSync(candidatePath).isFile();
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Parse the extension version from a Power BI Modeling MCP extension folder.
+ *
+ * @param {string} entry - Extension folder name
+ * @returns {number[]} Numeric semver parts, or [0, 0, 0] when absent
+ */
+function getExtensionVersionParts(entry) {
+  const match = entry.match(/^analysis-services\.powerbi-modeling-mcp-(\d+)\.(\d+)\.(\d+)(?:-|$)/);
+
+  if (!match) {
+    return [0, 0, 0];
+  }
+
+  return match.slice(1).map((part) => Number.parseInt(part, 10));
+}
+
+/**
+ * Sort extension folder names newest-first, deterministically.
+ *
+ * @param {string[]} entries - Directory entries
+ * @returns {string[]} Matching extension folder names, newest first
+ */
+function sortMcpExtensionEntries(entries) {
+  return entries
+    .filter((entry) => EXTENSION_NAME_PATTERN.test(entry))
+    .sort((left, right) => {
+      const leftVersion = getExtensionVersionParts(left);
+      const rightVersion = getExtensionVersionParts(right);
+
+      for (let index = 0; index < 3; index += 1) {
+        if (leftVersion[index] !== rightVersion[index]) {
+          return rightVersion[index] - leftVersion[index];
+        }
+      }
+
+      return left.localeCompare(right);
+    });
+}
+
+/**
+ * Resolve the executable path from one extension folder.
+ *
+ * @param {string} extensionsDir - Parent extensions directory
+ * @param {string} entry - Extension folder name
+ * @returns {string|null} Executable path when valid
+ */
+function findMcpExecutableInExtensionEntry(extensionsDir, entry) {
+  const directExePath = path.join(extensionsDir, entry, 'server', MODELING_MCP_EXE_NAME);
+
+  if (isMcpExecutableFile(directExePath)) {
+    return directExePath;
+  }
+
+  const nestedExePath = path.join(
+    extensionsDir,
+    entry,
+    'extension',
+    'server',
+    MODELING_MCP_EXE_NAME
+  );
+
+  return isMcpExecutableFile(nestedExePath) ? nestedExePath : 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 = sortMcpExtensionEntries(fs.readdirSync(extensionsDir));
+
+      for (const entry of entries) {
+        const exePath = findMcpExecutableInExtensionEntry(extensionsDir, entry);
+
+        if (exePath) {
+          return exePath;
+        }
+      }
+    } catch (e) {
+      // Ignore read errors
+    }
+  }
+
+  // Check if it's in PATH
+  try {
+    // No shell: `where` is a real executable on Windows and runs fine without
+    // one. Avoids a shell-injection footgun and a PATH-precedence surprise on
+    // the path that is later launched as a read/write MCP.
+    const result = spawnSync('where', ['powerbi-modeling-mcp.exe'], {
+      encoding: 'utf8',
+    });
+
+    if (result.status === 0 && result.stdout) {
+      const firstLine = result.stdout.trim().split('\n')[0];
+      if (isMcpExecutableFile(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 for the local Power BI Modeling MCP launcher.
+ * @returns {Object} Status object
+ */
+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,
+    },
+  };
+}
+
+/**
+ * Get installation instructions for local MCP
+ * @returns {Object} Installation instructions
+ */
+function getInstallInstructions() {
+  return {
+    title: 'Power BI Modeling MCP not detected',
+    options: [
+      {
+        name: 'VS Code / Cursor',
+        steps: [
+          'Open VS Code or Cursor',
+          'Go to Extensions (Ctrl+Shift+X)',
+          'Search for "Power BI Modeling MCP"',
+          'Install the Microsoft extension',
+          'Run: super install --all --yes',
+        ],
+        link: 'https://aka.ms/powerbi-modeling-mcp-vscode',
+      },
+      {
+        name: 'Manual',
+        steps: [
+          'Download the VSIX from VS Code Marketplace',
+          'Rename .vsix to .zip',
+          `Extract to ${path.join(os.homedir(), '.bi-superpowers', 'mcp')}`,
+          'Set BI_SUPERPOWERS_POWERBI_MODELING_MCP_PATH to the .exe path',
+        ],
+        link: 'https://marketplace.visualstudio.com/items?itemName=analysis-services.powerbi-modeling-mcp',
+      },
+    ],
+    note:
+      os.platform() !== 'win32'
+        ? 'The local MCP is only available on Windows. On macOS/Linux, microsoft-learn still provides official docs.'
+        : 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 still get the microsoft-learn MCP 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,
+  isMcpExecutableFile,
+  sortMcpExtensionEntries,
+  findMcpExecutableInExtensionEntry,
+  MODELING_MCP_ENV_VARS,
+};

package/bin/utils/tui.js

@@ -0,0 +1,314 @@
+/**
+ * TUI Utilities - Rich terminal UI helpers
+ * =========================================
+ * Provides consistent styling and formatting for CLI output.
+ */
+
+const chalk = require('chalk');
+const boxen = require('boxen');
+const Table = require('cli-table3');
+
+// Color scheme
+const colors = {
+  primary: chalk.cyan,
+  success: chalk.green,
+  error: chalk.red,
+  warning: chalk.yellow,
+  info: chalk.blue,
+  muted: chalk.gray,
+  highlight: chalk.bold.white,
+  code: chalk.magenta,
+};
+
+// Icons
+const icons = {
+  success: chalk.green('✓'),
+  error: chalk.red('✗'),
+  warning: chalk.yellow('⚠'),
+  info: chalk.blue('ℹ'),
+  bullet: chalk.cyan('•'),
+  arrow: chalk.cyan('→'),
+  skill: '📚',
+  snippet: '📝',
+  theme: '🎨',
+  search: '🔍',
+  lint: '🔬',
+  diff: '📊',
+  watch: '👁',
+};
+
+/**
+ * Print a success message
+ * @param {string} message - Message to display
+ */
+function success(message) {
+  console.log(`${icons.success} ${message}`);
+}
+
+/**
+ * Print an error message
+ * @param {string} message - Message to display
+ */
+function error(message) {
+  console.log(`${icons.error} ${colors.error(message)}`);
+}
+
+/**
+ * Print a warning message
+ * @param {string} message - Message to display
+ */
+function warning(message) {
+  console.log(`${icons.warning} ${colors.warning(message)}`);
+}
+
+/**
+ * Print an info message
+ * @param {string} message - Message to display
+ */
+function info(message) {
+  console.log(`${icons.info} ${colors.info(message)}`);
+}
+
+/**
+ * Print a muted message
+ * @param {string} message - Message to display
+ */
+function muted(message) {
+  console.log(colors.muted(message));
+}
+
+/**
+ * Print a header box
+ * @param {string} title - Title text
+ * @param {string} [subtitle] - Optional subtitle
+ */
+function header(title, subtitle) {
+  const content = subtitle
+    ? `${colors.highlight(title)}\n${colors.muted(subtitle)}`
+    : colors.highlight(title);
+
+  console.log(
+    boxen(content, {
+      padding: 1,
+      margin: { top: 1, bottom: 1 },
+      borderStyle: 'round',
+      borderColor: 'cyan',
+    })
+  );
+}
+
+/**
+ * Print a section header
+ * @param {string} title - Section title
+ */
+function section(title) {
+  console.log(`\n${colors.primary(title)}`);
+  console.log(colors.muted('─'.repeat(title.length + 4)));
+}
+
+/**
+ * Create a table for displaying data
+ * @param {string[]} headers - Table headers
+ * @param {string[][]} rows - Table rows
+ * @param {Object} [options] - Additional options
+ * @returns {string} Formatted table string
+ */
+function createTable(headers, rows, options = {}) {
+  const table = new Table({
+    head: headers.map((h) => colors.primary(h)),
+    style: {
+      head: [],
+      border: ['gray'],
+    },
+    ...options,
+  });
+
+  rows.forEach((row) => table.push(row));
+  return table.toString();
+}
+
+/**
+ * Format a file path for display
+ * @param {string} filePath - File path to format
+ * @returns {string} Formatted path
+ */
+function formatPath(filePath) {
+  return colors.code(filePath);
+}
+
+/**
+ * Format a code snippet for display
+ * @param {string} code - Code to format
+ * @param {string} [language] - Optional language hint
+ * @returns {string} Formatted code
+ */
+function formatCode(code, language) {
+  const prefix = language ? colors.muted(`[${language}] `) : '';
+  return `${prefix}${colors.code(code)}`;
+}
+
+/**
+ * Print a key-value pair
+ * @param {string} key - Key/label
+ * @param {string} value - Value
+ */
+function keyValue(key, value) {
+  console.log(`  ${colors.muted(key + ':')} ${value}`);
+}
+
+/**
+ * Print a list item
+ * @param {string} text - Item text
+ * @param {number} [indent=0] - Indentation level
+ */
+function listItem(text, indent = 0) {
+  const padding = '  '.repeat(indent);
+  console.log(`${padding}${icons.bullet} ${text}`);
+}
+
+/**
+ * Print a diff line (addition)
+ * @param {string} text - Line text
+ */
+function diffAdd(text) {
+  console.log(colors.success(`+ ${text}`));
+}
+
+/**
+ * Print a diff line (deletion)
+ * @param {string} text - Line text
+ */
+function diffRemove(text) {
+  console.log(colors.error(`- ${text}`));
+}
+
+/**
+ * Print a diff line (unchanged)
+ * @param {string} text - Line text
+ */
+function diffUnchanged(text) {
+  console.log(colors.muted(`  ${text}`));
+}
+
+/**
+ * Print search result
+ * @param {Object} result - Search result object
+ * @param {string} result.title - Result title
+ * @param {string} result.path - File path
+ * @param {string} result.preview - Preview text
+ * @param {number} result.score - Match score
+ */
+function searchResult(result) {
+  console.log(`\n${icons.search} ${colors.highlight(result.title)}`);
+  console.log(`   ${colors.muted(result.path)}`);
+  if (result.preview) {
+    console.log(`   ${colors.muted(result.preview.substring(0, 100))}...`);
+  }
+  if (result.score !== undefined) {
+    console.log(`   ${colors.muted('Score:')} ${result.score.toFixed(2)}`);
+  }
+}
+
+/**
+ * Print lint result
+ * @param {Object} result - Lint result
+ * @param {string} result.file - File name
+ * @param {Object[]} result.errors - Array of errors
+ * @param {Object[]} result.warnings - Array of warnings
+ */
+function lintResult(result) {
+  const hasIssues = result.errors.length > 0 || result.warnings.length > 0;
+
+  if (!hasIssues) {
+    console.log(`${icons.success} ${formatPath(result.file)}`);
+    return;
+  }
+
+  console.log(`\n${formatPath(result.file)}`);
+
+  result.errors.forEach((err) => {
+    console.log(`  ${icons.error} ${colors.error(err.message)}`);
+    if (err.line) {
+      console.log(`    ${colors.muted(`Line ${err.line}`)}`);
+    }
+  });
+
+  result.warnings.forEach((warn) => {
+    console.log(`  ${icons.warning} ${colors.warning(warn.message)}`);
+    if (warn.line) {
+      console.log(`    ${colors.muted(`Line ${warn.line}`)}`);
+    }
+  });
+}
+
+/**
+ * Print a summary box
+ * @param {Object} summary - Summary data
+ * @param {string} summary.title - Summary title
+ * @param {Object} summary.stats - Key-value stats
+ */
+function summaryBox(summary) {
+  let content = colors.highlight(summary.title) + '\n\n';
+
+  Object.entries(summary.stats).forEach(([key, value]) => {
+    content += `${colors.muted(key + ':')} ${value}\n`;
+  });
+
+  console.log(
+    boxen(content.trim(), {
+      padding: 1,
+      margin: { top: 1, bottom: 1 },
+      borderStyle: 'round',
+      borderColor: 'green',
+    })
+  );
+}
+
+/**
+ * Print dry-run notice
+ */
+function dryRunNotice() {
+  console.log(
+    boxen(colors.warning('DRY RUN MODE\n') + colors.muted('No files will be created or modified'), {
+      padding: 1,
+      borderStyle: 'round',
+      borderColor: 'yellow',
+    })
+  );
+}
+
+/**
+ * Truncate text with ellipsis
+ * @param {string} text - Text to truncate
+ * @param {number} maxLength - Maximum length
+ * @returns {string} Truncated text
+ */
+function truncate(text, maxLength) {
+  if (text.length <= maxLength) return text;
+  return text.substring(0, maxLength - 3) + '...';
+}
+
+module.exports = {
+  colors,
+  icons,
+  success,
+  error,
+  warning,
+  info,
+  muted,
+  header,
+  section,
+  createTable,
+  formatPath,
+  formatCode,
+  keyValue,
+  listItem,
+  diffAdd,
+  diffRemove,
+  diffUnchanged,
+  searchResult,
+  lintResult,
+  summaryBox,
+  dryRunNotice,
+  truncate,
+};