bi-superpowers 1.0.0

package/bin/commands/lint.js

@@ -0,0 +1,441 @@
+/**
+ * Lint Command (checkup)
+ * ======================
+ * Validates skill files for proper structure and format.
+ *
+ * Usage:
+ *   super checkup                Lint all skills
+ *   super checkup dax.md         Lint specific skill
+ *   super checkup --fix          Auto-fix issues (where possible)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const tui = require('../utils/tui');
+const { readSkillDirectory, normalizeSkillName } = require('../lib/skills');
+
+// Lint rules configuration
+const RULES = {
+  // Required sections
+  requiredSections: {
+    enabled: true,
+    severity: 'error',
+    sections: ['Trigger', 'Identity', 'MANDATORY RULES'],
+  },
+
+  // Trigger section validation
+  triggerFormat: {
+    enabled: true,
+    severity: 'warning',
+    description: 'Trigger section should have bullet points with quoted phrases',
+  },
+
+  // Title validation
+  hasTitle: {
+    enabled: true,
+    severity: 'error',
+    description: 'Skill must have an H1 title',
+  },
+
+  // Code block validation
+  codeBlocks: {
+    enabled: true,
+    severity: 'warning',
+    description: 'Code blocks should have language specified',
+  },
+
+  // Link validation
+  brokenLinks: {
+    enabled: true,
+    severity: 'warning',
+    description: 'Internal links should point to existing files',
+  },
+
+  // Maximum file size
+  maxSize: {
+    enabled: true,
+    severity: 'warning',
+    maxBytes: 50000, // 50KB
+  },
+
+  // Naming convention. Folder-based skills follow Anthropic's convention
+  // of `<folder>/SKILL.md` (uppercase), so allow that literal too.
+  naming: {
+    enabled: true,
+    severity: 'error',
+    pattern: /^([a-z0-9-]+\.md|SKILL\.md)$/,
+    description: 'Skill files should be lowercase-kebab-case.md, or SKILL.md inside a skill folder',
+  },
+};
+
+/**
+ * Lint a single skill file
+ * @param {string} filePath - Path to skill file
+ * @returns {Object} Lint result with errors and warnings
+ */
+function lintFile(filePath) {
+  const result = {
+    file: path.basename(filePath),
+    path: filePath,
+    errors: [],
+    warnings: [],
+  };
+
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch (e) {
+    result.errors.push({ rule: 'file-read', message: `Cannot read file: ${e.message}` });
+    return result;
+  }
+
+  const lines = content.split('\n');
+  const filename = path.basename(filePath);
+
+  // Rule: File naming convention
+  if (RULES.naming.enabled && !RULES.naming.pattern.test(filename)) {
+    addIssue(
+      result,
+      'naming',
+      RULES.naming.severity,
+      `File name "${filename}" should be lowercase-kebab-case.md`
+    );
+  }
+
+  // Rule: Max file size
+  if (RULES.maxSize.enabled) {
+    const stats = fs.statSync(filePath);
+    if (stats.size > RULES.maxSize.maxBytes) {
+      addIssue(
+        result,
+        'maxSize',
+        RULES.maxSize.severity,
+        `File size (${(stats.size / 1024).toFixed(1)}KB) exceeds ${RULES.maxSize.maxBytes / 1024}KB limit`
+      );
+    }
+  }
+
+  // Rule: Has H1 title
+  if (RULES.hasTitle.enabled) {
+    const hasH1 = lines.some((line) => /^#\s+.+/.test(line));
+    if (!hasH1) {
+      addIssue(
+        result,
+        'hasTitle',
+        RULES.hasTitle.severity,
+        'Missing H1 title (should start with "# Title")'
+      );
+    }
+  }
+
+  // Rule: Required sections
+  if (RULES.requiredSections.enabled) {
+    RULES.requiredSections.sections.forEach((section) => {
+      const sectionPattern = new RegExp(`^##\\s+${section}`, 'mi');
+      if (!sectionPattern.test(content)) {
+        addIssue(
+          result,
+          'requiredSections',
+          RULES.requiredSections.severity,
+          `Missing required section: "## ${section}"`
+        );
+      }
+    });
+  }
+
+  // Rule: Trigger format validation
+  if (RULES.triggerFormat.enabled) {
+    const triggerSection = extractSection(content, 'Trigger');
+    if (triggerSection) {
+      const hasBullets = /[-*]\s+["'].+["']/.test(triggerSection);
+      if (!hasBullets) {
+        const lineNum = findSectionLine(lines, 'Trigger');
+        addIssue(
+          result,
+          'triggerFormat',
+          RULES.triggerFormat.severity,
+          'Trigger section should have bullet points with quoted phrases (e.g., - "keyword")',
+          lineNum
+        );
+      }
+    }
+  }
+
+  // Rule: Code blocks should have language
+  if (RULES.codeBlocks.enabled) {
+    // Track fence open/close state so we only flag OPENING fences that lack a
+    // language specifier. Closing fences are always bare ``` and must never be
+    // flagged (the previous next-line heuristic mis-flagged every closing fence).
+    let inFence = false;
+    lines.forEach((line, index) => {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith('```')) {
+        return;
+      }
+      if (inFence) {
+        inFence = false; // closing fence — carries no language by definition
+        return;
+      }
+      inFence = true; // opening fence
+      if (trimmed === '```') {
+        addIssue(
+          result,
+          'codeBlocks',
+          RULES.codeBlocks.severity,
+          'Code block missing language specifier (e.g., ```dax)',
+          index + 1
+        );
+      }
+    });
+  }
+
+  // Rule: Check internal links
+  if (RULES.brokenLinks.enabled) {
+    const linkPattern = /\[([^\]]+)\]\(([^)]+)\)/g;
+    let match;
+    while ((match = linkPattern.exec(content)) !== null) {
+      const linkPath = match[2];
+      // Only check relative markdown links
+      if (linkPath.endsWith('.md') && !linkPath.startsWith('http')) {
+        const resolvedPath = path.resolve(path.dirname(filePath), linkPath);
+        if (!fs.existsSync(resolvedPath)) {
+          const lineNum = findLineWithText(lines, match[0]);
+          addIssue(
+            result,
+            'brokenLinks',
+            RULES.brokenLinks.severity,
+            `Broken internal link: ${linkPath}`,
+            lineNum
+          );
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Add an issue to the result
+ * @param {Object} result - Result object
+ * @param {string} rule - Rule name
+ * @param {string} severity - 'error' or 'warning'
+ * @param {string} message - Issue message
+ * @param {number} [line] - Line number
+ */
+function addIssue(result, rule, severity, message, line) {
+  const issue = { rule, message };
+  if (line) issue.line = line;
+
+  if (severity === 'error') {
+    result.errors.push(issue);
+  } else {
+    result.warnings.push(issue);
+  }
+}
+
+/**
+ * Extract a section from markdown content
+ * @param {string} content - Markdown content
+ * @param {string} sectionName - Section name (without ##)
+ * @returns {string|null} Section content or null
+ */
+function extractSection(content, sectionName) {
+  // Locate the section heading first, then slice from there to the next
+  // H2 heading or horizontal rule. The earlier regex used a multiline
+  // `$` as a stop anchor, which matches end of LINE — so it returned
+  // only the heading line and dropped the body, breaking downstream
+  // rules like triggerFormat that inspect the body.
+  const headingMatch = new RegExp(`^##\\s+${sectionName}\\b`, 'mi').exec(content);
+  if (!headingMatch) return null;
+  const tail = content.slice(headingMatch.index);
+  const next = tail.search(/\n##\s+|\n---+\s*\n/);
+  return next === -1 ? tail : tail.slice(0, next);
+}
+
+/**
+ * Find line number of a section
+ * @param {string[]} lines - Array of lines
+ * @param {string} sectionName - Section name
+ * @returns {number|null} Line number or null
+ */
+function findSectionLine(lines, sectionName) {
+  for (let i = 0; i < lines.length; i++) {
+    if (new RegExp(`^##\\s+${sectionName}`, 'i').test(lines[i])) {
+      return i + 1;
+    }
+  }
+  return null;
+}
+
+/**
+ * Find line number containing text
+ * @param {string[]} lines - Array of lines
+ * @param {string} text - Text to find
+ * @returns {number|null} Line number or null
+ */
+function findLineWithText(lines, text) {
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes(text)) {
+      return i + 1;
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse command line arguments
+ * @param {string[]} args - CLI arguments
+ * @returns {Object} Parsed options
+ */
+function parseArgs(args) {
+  const options = {
+    files: [],
+    fix: false,
+    json: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--fix') {
+      options.fix = true;
+    } else if (arg === '--json') {
+      options.json = true;
+    } else if (!arg.startsWith('-')) {
+      options.files.push(arg);
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Display lint summary
+ * @param {Object[]} results - Array of lint results
+ */
+function displaySummary(results) {
+  const totalErrors = results.reduce((sum, r) => sum + r.errors.length, 0);
+  const totalWarnings = results.reduce((sum, r) => sum + r.warnings.length, 0);
+  const filesWithIssues = results.filter(
+    (r) => r.errors.length > 0 || r.warnings.length > 0
+  ).length;
+
+  console.log('');
+  tui.section('Summary');
+
+  const table = tui.createTable(
+    ['Metric', 'Count'],
+    [
+      ['Files checked', results.length.toString()],
+      ['Files with issues', filesWithIssues.toString()],
+      ['Errors', tui.colors.error(totalErrors.toString())],
+      ['Warnings', tui.colors.warning(totalWarnings.toString())],
+    ]
+  );
+  console.log(table);
+
+  if (totalErrors > 0) {
+    console.log(`\n${tui.icons.error} ${tui.colors.error(`${totalErrors} error(s) found`)}`);
+  } else if (totalWarnings > 0) {
+    console.log(
+      `\n${tui.icons.warning} ${tui.colors.warning(`${totalWarnings} warning(s) found`)}`
+    );
+  } else {
+    console.log(`\n${tui.icons.success} ${tui.colors.success('All skills passed validation!')}`);
+  }
+}
+
+/**
+ * Main lint command handler
+ * @param {string[]} args - Command arguments
+ * @param {Object} config - CLI configuration with paths
+ */
+function lintCommand(args, config) {
+  const options = parseArgs(args);
+
+  // Try cache directory first, fall back to local skills
+  let skillsDir = config.skillsDir;
+  const localSkills = path.join(config.packageDir, '.agents', 'prompts', 'skills');
+
+  if (!fs.existsSync(skillsDir)) {
+    if (fs.existsSync(localSkills)) {
+      skillsDir = localSkills;
+    } else {
+      tui.error('Skills directory not found. Try reinstalling: npm install -g bi-superpowers');
+      process.exit(1);
+    }
+  }
+
+  tui.header('BI Agent Superpowers', 'Skill Linter');
+
+  // Determine which files to lint. Use the shared skill loader so we
+  // catch both flat (`<name>.md`) and folder-based (`<name>/SKILL.md`)
+  // skills — a previous version filtered with `f.endsWith('.md')` and
+  // silently skipped every folder-based skill.
+  const allSkills = readSkillDirectory(skillsDir);
+  const skillsByName = new Map(allSkills.map((s) => [s.name, s]));
+  let filesToLint = [];
+
+  if (options.files.length > 0) {
+    filesToLint = options.files
+      .map((f) => {
+        // Existing absolute / relative file path the user passed verbatim.
+        if (fs.existsSync(f) && fs.statSync(f).isFile()) {
+          return f;
+        }
+        // Look up by skill name. normalizeSkillName accepts `dax`,
+        // `dax.md`, `folder-skill`, or `folder-skill/SKILL.md`.
+        const skill = skillsByName.get(normalizeSkillName(f));
+        if (skill) return skill.path;
+
+        tui.warning(`Skill not found: ${f}`);
+        return null;
+      })
+      .filter(Boolean);
+  } else {
+    filesToLint = allSkills.map((s) => s.path);
+  }
+
+  if (filesToLint.length === 0) {
+    tui.warning('No skill files found to lint');
+    return;
+  }
+
+  tui.info(`Linting ${filesToLint.length} skill file(s)...`);
+  console.log('');
+
+  // Run linting
+  const results = filesToLint.map((file) => lintFile(file));
+
+  // Output results
+  if (options.json) {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+
+  // Display individual results
+  results.forEach((result) => {
+    tui.lintResult(result);
+  });
+
+  // Display summary
+  displaySummary(results);
+
+  // Exit with error code if there are errors
+  const hasErrors = results.some((r) => r.errors.length > 0);
+  if (hasErrors) {
+    process.exit(1);
+  }
+}
+
+// Expose primitives for tests (B3 — replace fake tests with real ones).
+module.exports = Object.assign(lintCommand, {
+  lintFile,
+  parseArgs,
+  extractSection,
+  findSectionLine,
+  findLineWithText,
+  addIssue,
+  RULES,
+});

package/bin/commands/mcp-setup.js

@@ -0,0 +1,255 @@
+/**
+ * MCP Setup Command
+ * =================
+ * Configures the official Microsoft MCP servers for an existing project-local
+ * BI Superpowers plugin. Normal multi-agent setup is user-level via
+ * `super install --all --yes`; this command refuses arbitrary repo-local writes.
+ *
+ * Usage:
+ *   super mcp-setup
+ *   super mcp-setup --tool claude-plugin
+ *   super mcp-setup --dry-run
+ */
+
+const fs = require('fs');
+const path = require('path');
+const tui = require('../utils/tui');
+const mcpDetect = require('../utils/mcp-detect');
+const {
+  ABSOLUTE_LAUNCHER_MODE,
+  PLUGIN_ROOT_LAUNCHER_MODE,
+  createMcpConfigForFormat,
+  mergeMcpConfig,
+} = require('../lib/microsoft-mcp');
+const { readJsonStrict, readJsoncStrict, writeJson } = require('../lib/mcp-config');
+
+const MCP_CONFIGS = {
+  'claude-plugin': {
+    name: 'Claude Code Plugin',
+    configPath: '.mcp.json',
+    format: 'plugin',
+  },
+  'claude-code': {
+    name: 'Claude Code (legacy standalone)',
+    configPath: '.claude/settings.json',
+    format: 'claude',
+  },
+  cursor: {
+    name: 'Cursor (legacy)',
+    configPath: '.cursor/mcp.json',
+    format: 'cursor',
+  },
+  kilocode: {
+    name: 'Kilo Code (legacy)',
+    configPath: '.kilo/kilo.jsonc',
+    format: 'kilo',
+  },
+  'open-code': {
+    name: 'OpenCode (legacy)',
+    configPath: 'opencode.config.json',
+    format: 'opencode',
+  },
+  vscode: {
+    name: 'VS Code (legacy)',
+    configPath: '.vscode/settings.json',
+    format: 'vscode',
+  },
+};
+
+function parseArgs(args) {
+  const options = {
+    tool: null,
+    dryRun: false,
+    targetDir: process.cwd(),
+    deprecatedFlags: [],
+  };
+
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+
+    if (arg === '--tool' || arg === '-t') {
+      options.tool = args[++index];
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--port' || arg === '-p' || arg === '--github' || arg === '-g') {
+      options.deprecatedFlags.push(arg);
+      if (args[index + 1] && !args[index + 1].startsWith('-')) {
+        index++;
+      }
+    } else if (!arg.startsWith('-')) {
+      options.targetDir = arg;
+    }
+  }
+
+  return options;
+}
+
+function loadConfiguredTools(targetDir) {
+  const configPath = path.join(targetDir, '.bi-superpowers.json');
+  if (fs.existsSync(configPath)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (Array.isArray(config.tools) && config.tools.length > 0) {
+        return Array.from(new Set(config.tools));
+      }
+    } catch (error) {
+      // Ignore invalid config and fall back below.
+    }
+  }
+
+  const pluginManifest = path.join(targetDir, '.claude-plugin', 'plugin.json');
+  if (fs.existsSync(pluginManifest)) {
+    return ['claude-plugin'];
+  }
+
+  return ['claude-plugin'];
+}
+
+function hasLocalPluginMarker(targetDir) {
+  return (
+    fs.existsSync(path.join(targetDir, '.bi-superpowers.json')) ||
+    fs.existsSync(path.join(targetDir, '.claude-plugin', 'plugin.json'))
+  );
+}
+
+function writeConfig(filePath, config, dryRun) {
+  if (dryRun) {
+    tui.info(`Would write: ${tui.formatPath(filePath)}`);
+    tui.muted(JSON.stringify(config, null, 2).slice(0, 220) + '...');
+    return true;
+  }
+
+  try {
+    writeJson(filePath, config);
+    return true;
+  } catch (error) {
+    tui.error(`Failed to write ${filePath}: ${error.message}`);
+    return false;
+  }
+}
+
+function getLauncherMode(targetDir, packageDir, tool) {
+  if (tool === 'claude-plugin' && path.resolve(targetDir) === path.resolve(packageDir)) {
+    return PLUGIN_ROOT_LAUNCHER_MODE;
+  }
+
+  return ABSOLUTE_LAUNCHER_MODE;
+}
+
+function mcpSetupCommand(args, config) {
+  const options = parseArgs(args);
+  const targetDir = path.resolve(options.targetDir);
+
+  tui.header('BI Agent Superpowers', 'Microsoft MCP Setup');
+
+  if (options.dryRun) {
+    tui.dryRunNotice();
+  }
+
+  if (options.deprecatedFlags.length > 0) {
+    tui.warning(
+      `Deprecated flags ignored: ${options.deprecatedFlags.join(', ')}. MCP setup now targets local Claude Code plugin configs and uses the official Microsoft servers.`
+    );
+  }
+
+  if (options.tool && !MCP_CONFIGS[options.tool]) {
+    tui.error(`Unknown tool: ${options.tool}`);
+    tui.info(`Available tools: ${Object.keys(MCP_CONFIGS).join(', ')}`);
+    process.exit(1);
+  }
+
+  if (!hasLocalPluginMarker(targetDir)) {
+    tui.warning('mcp-setup is only for existing project-local BI Superpowers plugin configs.');
+    tui.info(
+      'For Codex, GitHub Copilot, Gemini CLI, Kilo Code, and Claude Code user-level installs, run:'
+    );
+    tui.listItem('super install --all --yes');
+    tui.info(
+      'That writes user-level skills and MCP config under your home directory without creating files in this repo.'
+    );
+    tui.info(
+      'If you intentionally need local Claude Code plugin files, run `super kickoff` first, then rerun `super mcp-setup` inside that initialized repo.'
+    );
+    process.exitCode = 2;
+    return;
+  }
+
+  let configuredTools = loadConfiguredTools(targetDir);
+
+  if (options.tool) {
+    configuredTools = [options.tool];
+  }
+
+  tui.section('Configured Outputs');
+  configuredTools.forEach((tool) => {
+    tui.success(MCP_CONFIGS[tool].name);
+  });
+
+  const status = mcpDetect.getMcpStatus();
+
+  tui.section('Official Microsoft MCP Status');
+  if (status.local.installed) {
+    tui.success(`Power BI Modeling MCP detected: ${status.local.path}`);
+    if (status.local.version) {
+      tui.info(`Version: ${status.local.version}`);
+    }
+  } else {
+    tui.warning('Power BI Modeling MCP not detected locally.');
+    tui.info(mcpDetect.getModelingMcpError());
+  }
+
+  tui.success('Microsoft Learn MCP: https://learn.microsoft.com/api/mcp');
+
+  const results = {
+    success: [],
+    failed: [],
+  };
+
+  tui.section('Writing Configurations');
+  configuredTools.forEach((tool) => {
+    const toolConfig = MCP_CONFIGS[tool];
+    const filePath = path.join(targetDir, toolConfig.configPath);
+    let ok = false;
+
+    try {
+      const existingConfig =
+        toolConfig.format === 'kilo'
+          ? readJsoncStrict(filePath) || {}
+          : readJsonStrict(filePath) || {};
+      const generatedConfig = createMcpConfigForFormat(toolConfig.format, {
+        packageDir: config.packageDir,
+        launcherMode: getLauncherMode(targetDir, config.packageDir, tool),
+      });
+      const mergedConfig = mergeMcpConfig(existingConfig, generatedConfig, toolConfig.format);
+      ok = writeConfig(filePath, mergedConfig, options.dryRun);
+    } catch (error) {
+      tui.error(`Failed to prepare ${filePath}: ${error.message}`);
+    }
+
+    if (ok) {
+      results.success.push(toolConfig.name);
+      tui.success(`${toolConfig.name}: ${tui.formatPath(toolConfig.configPath)}`);
+    } else {
+      results.failed.push(toolConfig.name);
+    }
+  });
+
+  console.log('');
+  tui.section('Next Steps');
+  tui.listItem(
+    'Install the official Microsoft Power BI Modeling MCP extension in VS Code/Cursor on Windows if you need write access to Desktop/PBIP semantic models.'
+  );
+  tui.listItem('Refresh or restart your MCP client after config changes.');
+
+  if (configuredTools.includes('claude-plugin')) {
+    tui.listItem(`Run Claude Code with the plugin: claude --plugin-dir ${targetDir}`);
+  }
+
+  if (results.failed.length > 0) {
+    console.log('');
+    tui.warning(`Completed with failures: ${results.failed.join(', ')}`);
+    process.exit(1);
+  }
+}
+
+module.exports = mcpSetupCommand;