@luquimbo/bi-superpowers 1.0.0

package/bin/lib/generators/claude-plugin.js

@@ -0,0 +1,266 @@
+/**
+ * Claude Code Plugin Generator
+ * ============================
+ *
+ * Generates a native Claude Code plugin structure at the target root:
+ * - .claude-plugin/plugin.json
+ * - .mcp.json
+ * - command markdown files
+ * - plugin skill directories with SKILL.md files
+ *
+ * @module lib/generators/claude-plugin
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  PLUGIN_ROOT_LAUNCHER_MODE,
+  ABSOLUTE_LAUNCHER_MODE,
+  createPluginMcpConfig,
+} = require('../microsoft-mcp');
+const { parseSkillMetadata, getSkillPurpose } = require('./shared');
+
+const COMMAND_SKILLS = new Set([
+  'project-kickoff',
+  'data-model-design',
+  'theme-tweaker',
+  'pbi-connect',
+  'rls-design',
+  'fabric-scripts',
+  'contributions',
+  // Phase 2 — new interactive wizards
+  'dax-doctor',
+  'model-documenter',
+  'migration-assistant',
+  'report-layout',
+]);
+
+const REFERENCE_SKILLS = new Set([
+  'dax',
+  'power-query',
+  'data-modeling',
+  'query-performance',
+  'testing-validation',
+  'data-quality',
+  'fast-standard',
+  'excel-formulas',
+  // Phase 3 — new background knowledge
+  'governance',
+  'semantic-model',
+  'report-design',
+  'deployment',
+  'dax-udf',
+]);
+
+/**
+ * Ensure a directory exists.
+ *
+ * @param {string} directory - Directory path
+ */
+function ensureDirectory(directory) {
+  if (!fs.existsSync(directory)) {
+    fs.mkdirSync(directory, { recursive: true });
+  }
+}
+
+/**
+ * Rewrite library references for generated plugin targets.
+ *
+ * @param {string} content - Original markdown content
+ * @param {string} libraryPrefix - Prefix to use for library references
+ * @returns {string} Rewritten content
+ */
+function rewriteLibraryReferences(content, libraryPrefix) {
+  if (!libraryPrefix || libraryPrefix === 'library') {
+    return content;
+  }
+
+  return content.replace(/(^|[^.`])library\//g, `$1${libraryPrefix}/`);
+}
+
+/**
+ * Build a concise frontmatter description for plugin skills.
+ *
+ * @param {Object} skill - Skill definition object
+ * @returns {string} Description string
+ */
+function getPluginDescription(skill) {
+  const metadata = parseSkillMetadata(skill.content);
+
+  if (metadata.triggers.length > 0) {
+    const triggerList = metadata.triggers
+      .slice(0, 6)
+      .map((trigger) => `"${trigger}"`)
+      .join(', ');
+    return `Use when the user asks about ${metadata.title || skill.name}, especially phrases like ${triggerList}.`;
+  }
+
+  return `${metadata.title || skill.name}: ${getSkillPurpose(skill.name)}.`;
+}
+
+/**
+ * Serialize values safely for YAML frontmatter.
+ *
+/**
+ * @param {string} value - Raw value
+ * @returns {string} JSON-escaped string valid in YAML
+ */
+function toFrontmatterValue(value) {
+  return JSON.stringify(value);
+}
+
+/**
+ * Build command markdown with Claude Code frontmatter.
+ *
+ * @param {Object} skill - Skill definition object
+ * @param {string} libraryPrefix - Library prefix used in generated target
+ * @returns {string} Command markdown
+ */
+function buildCommandMarkdown(skill, libraryPrefix) {
+  const description = getSkillPurpose(skill.name);
+  const content = rewriteLibraryReferences(skill.content, libraryPrefix);
+
+  return `---
+description: ${toFrontmatterValue(description)}
+---
+
+<!-- Generated by BI Agent Superpowers. Edit src/content/skills/${skill.name}.md instead. -->
+
+${content}`;
+}
+
+/**
+ * Build plugin skill markdown with required frontmatter.
+ *
+ * @param {Object} skill - Skill definition object
+ * @param {string} version - Package version
+ * @param {string} libraryPrefix - Library prefix used in generated target
+ * @returns {string} Skill markdown
+ */
+function buildSkillMarkdown(skill, version, libraryPrefix) {
+  const content = rewriteLibraryReferences(skill.content, libraryPrefix);
+
+  return `---
+name: ${toFrontmatterValue(skill.name)}
+description: ${toFrontmatterValue(getPluginDescription(skill))}
+version: ${toFrontmatterValue(version)}
+---
+
+<!-- Generated by BI Agent Superpowers. Edit src/content/skills/${skill.name}.md instead. -->
+
+${content}`;
+}
+
+/**
+ * Remove stale generated files from a managed directory.
+ *
+ * @param {string} directory - Directory path
+ * @param {string[]} expectedEntries - Expected file or directory names
+ */
+function removeStaleEntries(directory, expectedEntries) {
+  if (!fs.existsSync(directory)) {
+    return;
+  }
+
+  const expected = new Set(expectedEntries);
+  for (const entry of fs.readdirSync(directory)) {
+    if (!expected.has(entry)) {
+      fs.rmSync(path.join(directory, entry), { recursive: true, force: true });
+    }
+  }
+}
+
+/**
+ * Generate a native Claude Code plugin.
+ *
+ * @param {string} targetDir - Target directory
+ * @param {Object[]} skills - Source skill objects
+ * @param {Object} [options] - Generator options
+ * @param {string} [options.packageDir] - Package installation directory
+ * @param {string} [options.version] - Package version
+ * @param {boolean} [options.usePluginRootLauncher] - Whether to use ${CLAUDE_PLUGIN_ROOT}
+ * @param {string} [options.libraryPrefix] - Library reference prefix
+ */
+async function generate(targetDir, skills, options = {}) {
+  const version = options.version || '0.0.0';
+  const usePluginRootLauncher = options.usePluginRootLauncher === true;
+  const libraryPrefix = options.libraryPrefix || 'library';
+  const launcherMode = usePluginRootLauncher ? PLUGIN_ROOT_LAUNCHER_MODE : ABSOLUTE_LAUNCHER_MODE;
+
+  const pluginDir = path.join(targetDir, '.claude-plugin');
+  const commandsDir = path.join(targetDir, 'commands');
+  const skillsDir = path.join(targetDir, 'skills');
+
+  ensureDirectory(pluginDir);
+  ensureDirectory(commandsDir);
+  ensureDirectory(skillsDir);
+
+  const pluginManifest = {
+    name: 'bi-superpowers',
+    description:
+      'Claude Code plugin for Power BI, Microsoft Fabric, and semantic model workflows powered by the official Microsoft MCP servers.',
+    version,
+    author: {
+      name: 'Lucas Sanchez',
+    },
+  };
+
+  fs.writeFileSync(
+    path.join(pluginDir, 'plugin.json'),
+    JSON.stringify(pluginManifest, null, 2) + '\n'
+  );
+  fs.writeFileSync(
+    path.join(targetDir, '.mcp.json'),
+    JSON.stringify(
+      createPluginMcpConfig({
+        packageDir: options.packageDir,
+        launcherMode,
+      }),
+      null,
+      2
+    ) + '\n'
+  );
+
+  const commandSkills = skills.filter((skill) => COMMAND_SKILLS.has(skill.name));
+
+  // Clean up stale entries — commands only have command skills, but ALL skills get SKILL.md
+  removeStaleEntries(
+    commandsDir,
+    commandSkills.map((skill) => `${skill.name}.md`)
+  );
+  removeStaleEntries(
+    skillsDir,
+    skills.map((skill) => skill.name)
+  );
+
+  // Command skills → commands/*.md (slash commands, Claude Code only)
+  for (const skill of commandSkills) {
+    fs.writeFileSync(
+      path.join(commandsDir, `${skill.name}.md`),
+      buildCommandMarkdown(skill, libraryPrefix)
+    );
+  }
+
+  // ALL skills → skills/*/SKILL.md (universal, discoverable by all Claude tools)
+  for (const skill of skills) {
+    const skillDir = path.join(skillsDir, skill.name);
+    ensureDirectory(skillDir);
+    fs.writeFileSync(
+      path.join(skillDir, 'SKILL.md'),
+      buildSkillMarkdown(skill, version, libraryPrefix)
+    );
+  }
+
+  console.log('  ✓ Created Claude Code plugin manifest');
+  console.log('  ✓ Created .mcp.json with official Microsoft MCP servers');
+  console.log(`  ✓ Created ${commandSkills.length} plugin commands`);
+  console.log(`  ✓ Created ${skills.length} plugin skills (SKILL.md)`);
+}
+
+module.exports = {
+  name: 'Claude Code Plugin',
+  description: 'Native Claude Code plugin (recommended)',
+  generate,
+  COMMAND_SKILLS,
+  REFERENCE_SKILLS,
+};

package/bin/lib/generators/claude-plugin.test.js

@@ -0,0 +1,110 @@
+/**
+ * Tests for the native Claude Code plugin generator.
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const claudePlugin = require('./claude-plugin');
+
+function makeSkill(name, title) {
+  return {
+    name,
+    path: `/virtual/${name}.md`,
+    content: `# ${title}
+
+## Trigger
+- "${name}"
+
+## Identity
+You are the ${title} guide.
+
+## MANDATORY RULES
+1. Stay helpful.
+
+Reference: library/snippets/example.md
+`,
+  };
+}
+
+describe('claude-plugin generator', () => {
+  test('creates plugin manifest, mcp config, commands, and skills', async () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bi-superpowers-plugin-'));
+
+    try {
+      const skills = [
+        makeSkill('project-kickoff', 'Project Kickoff'),
+        makeSkill('pbi-connect', 'PBI Connect'),
+        makeSkill('dax', 'DAX'),
+        makeSkill('excel-formulas', 'Excel Formulas'),
+      ];
+
+      await claudePlugin.generate(tempDir, skills, {
+        packageDir: '/tmp/bi-superpowers',
+        version: '9.9.9',
+        usePluginRootLauncher: true,
+        libraryPrefix: 'library',
+      });
+
+      const pluginManifestPath = path.join(tempDir, '.claude-plugin', 'plugin.json');
+      const pluginMcpPath = path.join(tempDir, '.mcp.json');
+      const commandPath = path.join(tempDir, 'commands', 'project-kickoff.md');
+      const skillPath = path.join(tempDir, 'skills', 'dax', 'SKILL.md');
+
+      assert.ok(fs.existsSync(pluginManifestPath));
+      assert.ok(fs.existsSync(pluginMcpPath));
+      assert.ok(fs.existsSync(commandPath));
+      assert.ok(fs.existsSync(skillPath));
+
+      const pluginManifest = JSON.parse(fs.readFileSync(pluginManifestPath, 'utf8'));
+      const pluginMcp = JSON.parse(fs.readFileSync(pluginMcpPath, 'utf8'));
+      const commandContent = fs.readFileSync(commandPath, 'utf8');
+      const skillContent = fs.readFileSync(skillPath, 'utf8');
+
+      assert.strictEqual(pluginManifest.name, 'bi-superpowers');
+      assert.strictEqual(pluginManifest.version, '9.9.9');
+
+      assert.ok(pluginMcp['powerbi-remote']);
+      assert.ok(pluginMcp['fabric-mcp-server']);
+      assert.ok(pluginMcp['powerbi-modeling-mcp']);
+      assert.strictEqual(pluginMcp['powerbi-remote'].type, 'http');
+      assert.strictEqual(pluginMcp['fabric-mcp-server'].command, 'npx');
+      assert.strictEqual(pluginMcp['powerbi-modeling-mcp'].command, 'node');
+      assert.ok(
+        pluginMcp['powerbi-modeling-mcp'].args[0].includes(
+          '${CLAUDE_PLUGIN_ROOT}/bin/mcp/powerbi-modeling-launcher.js'
+        )
+      );
+
+      assert.ok(commandContent.includes('description: "Project analysis and planning"'));
+      assert.ok(commandContent.includes('Generated by BI Agent Superpowers'));
+      assert.ok(skillContent.includes('name: "dax"'));
+      assert.ok(skillContent.includes('version: "9.9.9"'));
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  test('rewrites library references for generated project outputs', async () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bi-superpowers-plugin-'));
+
+    try {
+      const skills = [makeSkill('dax', 'DAX')];
+
+      await claudePlugin.generate(tempDir, skills, {
+        packageDir: '/tmp/bi-superpowers',
+        version: '1.0.0',
+        libraryPrefix: '.bi-superpowers/library',
+      });
+
+      const skillContent = fs.readFileSync(path.join(tempDir, 'skills', 'dax', 'SKILL.md'), 'utf8');
+
+      assert.ok(skillContent.includes('.bi-superpowers/library/snippets/example.md'));
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+});

package/bin/lib/generators/index.js

@@ -0,0 +1,116 @@
+/**
+ * Generators Module
+ * ==================
+ *
+ * Factory and registry for the Claude ecosystem generator.
+ * Supports: Claude Code, 1code.dev, Claude Desktop (via MCPB).
+ *
+ * @module lib/generators
+ */
+
+const claudePlugin = require('./claude-plugin');
+const shared = require('./shared');
+
+/**
+ * AI Tools Configuration Registry
+ *
+ * Only claude-plugin is needed — it covers Claude Code + 1code.dev.
+ * Claude Desktop is handled separately via `super build-desktop` (MCPB).
+ */
+const AI_TOOLS = {
+  'claude-plugin': claudePlugin,
+};
+
+/**
+ * Get a generator by tool ID
+ * @param {string} toolId - Tool identifier
+ * @returns {Object|null} Generator object or null if not found
+ */
+function getGenerator(toolId) {
+  return AI_TOOLS[toolId] || null;
+}
+
+/**
+ * Get all available tool IDs
+ * @returns {string[]} Array of tool IDs
+ */
+function getAvailableTools() {
+  return Object.keys(AI_TOOLS);
+}
+
+/**
+ * Get tool display info for all tools
+ * @returns {Object[]} Array of {id, name, description}
+ */
+function getToolsInfo() {
+  return Object.entries(AI_TOOLS).map(([id, tool]) => ({
+    id,
+    name: tool.name,
+    description: tool.description,
+  }));
+}
+
+/**
+ * Generate config for a specific AI tool
+ *
+ * @param {string} toolId - Tool ID (e.g., 'claude-plugin')
+ * @param {string} targetDir - Target project directory
+ * @param {Object[]} skills - Array of skill objects
+ * @param {Object} options - Additional options passed to generator
+ */
+async function generateForTool(toolId, targetDir, skills, options = {}) {
+  const generator = AI_TOOLS[toolId];
+  if (generator && generator.generate) {
+    console.log(`Generating for ${generator.name}...`);
+    await generator.generate(targetDir, skills, options);
+  }
+}
+
+/**
+ * Preview what files would be generated (for dry-run mode)
+ *
+ * @param {string} targetDir - Target project directory
+ * @param {string[]} tools - Array of tool IDs to generate for
+ * @param {Object[]} skills - Array of skill objects
+ * @param {string} configFile - Name of config file
+ */
+function previewGeneration(targetDir, tools, skills, configFile) {
+  const path = require('path');
+
+  for (const tool of tools) {
+    const toolConfig = AI_TOOLS[tool];
+    if (!toolConfig) continue;
+
+    console.log(`${toolConfig.name}:`);
+
+    if (tool === 'claude-plugin') {
+      console.log(`  \u{1F4C1} ${path.join(targetDir, '.claude-plugin')}/`);
+      console.log('     \u2514\u2500 plugin.json');
+      console.log(`  \u{1F4C4} ${path.join(targetDir, '.mcp.json')}`);
+      console.log(`  \u{1F4C1} ${path.join(targetDir, 'commands')}/`);
+      console.log(`  \u{1F4C1} ${path.join(targetDir, 'skills')}/`);
+    }
+    console.log('');
+  }
+
+  console.log('Config file:');
+  console.log(`  \u{1F4C4} ${path.join(targetDir, configFile)}`);
+}
+
+module.exports = {
+  // Registry
+  AI_TOOLS,
+
+  // Factory functions
+  getGenerator,
+  getAvailableTools,
+  getToolsInfo,
+  generateForTool,
+  previewGeneration,
+
+  // Individual generators
+  claudePlugin,
+
+  // Shared utilities
+  ...shared,
+};