bi-superpowers 1.0.0

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

@@ -0,0 +1,529 @@
+/**
+ * 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');
+
+// Currently the plugin ships 9 command skills:
+// - bi-start: session-opener that routes to the BI specialists.
+// - bi-kickoff: new-project bootstrap with AGENTS.md scaffolding.
+// - bi-modeling / bi-dax / bi-performance: model design, DAX, profiling.
+// - bi-connect: MCP connection + DAX UDFs.
+// - bi-powerquery: Power Query staging for Demo/Real appends.
+// - bi-scorecard: Power BI Service scorecards and goals automation.
+// - bi-refactor: existing-project cleanup without report rebuilds.
+// The old reference-skills split is kept as an empty set so that any
+// downstream code that checks `REFERENCE_SKILLS.has(x)` still works.
+const COMMAND_SKILLS = new Set([
+  'bi-start',
+  'bi-kickoff',
+  'bi-modeling',
+  'bi-dax',
+  'bi-performance',
+  'bi-connect',
+  'bi-powerquery',
+  'bi-scorecard',
+  'bi-refactor',
+]);
+
+const REFERENCE_SKILLS = new Set();
+
+/**
+ * Ensure a directory exists.
+ *
+ * @param {string} directory - Directory path
+ */
+function ensureDirectory(directory) {
+  if (!fs.existsSync(directory)) {
+    fs.mkdirSync(directory, { recursive: true });
+  }
+}
+
+/**
+ * Recursively copy a directory tree from `source` to `target`.
+ * Follows the Node built-in cp() semantics: overwrites existing files,
+ * preserves directory structure. No-op if source does not exist.
+ *
+ * Used to propagate `references/` and `scripts/` subfolders from
+ * folder-based source skills into the generated plugin so the agent can
+ * load on-demand material and run bundled helper scripts.
+ *
+ * @param {string} source - Source directory (must exist to do anything)
+ * @param {string} target - Target directory (created if missing)
+ */
+function copyDirectory(source, target) {
+  if (!fs.existsSync(source)) {
+    return;
+  }
+  ensureDirectory(target);
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const sourcePath = path.join(source, entry.name);
+    const targetPath = path.join(target, entry.name);
+    if (entry.isDirectory()) {
+      copyDirectory(sourcePath, targetPath);
+    } else if (entry.isFile()) {
+      // Don't ship test/build artifacts (e.g. *.expected.json oracles) bundled
+      // beside references/scripts/examples — mirror copyRuntimeTree's filter so
+      // both distribution paths exclude the same files.
+      if (/\.(test|spec)\.js$|\.expected\.json$|\.bak$|\.tmp$/.test(entry.name)) {
+        continue;
+      }
+      fs.copyFileSync(sourcePath, targetPath);
+    }
+    // Ignore symlinks / other entry types to match the conservative
+    // behaviour of readSkillDirectory().
+  }
+}
+
+/**
+ * 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 with at least { name, content }
+ * @returns {string} Description string
+ * @throws {Error} If skill is missing required fields
+ */
+function getPluginDescription(skill) {
+  if (!skill || typeof skill !== 'object' || !skill.name || typeof skill.content !== 'string') {
+    const hint = skill && skill.path ? ` (path: ${skill.path})` : '';
+    throw new Error(
+      `Invalid skill object: missing name or content${hint}. ` +
+        'Check the source file in src/content/skills/.'
+    );
+  }
+
+  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);
+}
+
+/**
+ * Return the canonical source path that maintainers should edit.
+ *
+ * @param {Object} skill - Skill definition object
+ * @returns {string} Source path relative to the repository root
+ */
+function getSourceEditPath(skill) {
+  if (skill.bundleDir) {
+    return `src/content/skills/${skill.name}/SKILL.md`;
+  }
+  return `src/content/skills/${skill.name}.md`;
+}
+
+// ---------------------------------------------------------------------------
+// Update-check preamble
+// ---------------------------------------------------------------------------
+// Cross-agent "auto-update" mechanism (see ROADMAP item 4 / gstack pattern).
+// The preamble is prepended to every generated SKILL.md and command Markdown
+// so the agent reading the skill content runs the version check at the top
+// of each conversation, surfaces an update notice if available, and then
+// proceeds with the skill. The check caches for 24h on disk and degrades to
+// no-output on network failure — it must never block the skill invocation.
+//
+// The update-check.js script is shipped alongside each skill's `scripts/`
+// folder at generation time (see copyUpdateCheckScript) so `{skillBundleDir}`
+// resolves correctly regardless of the install path (npm-based `super
+// install` OR Claude Code plugin marketplace).
+
+const UPDATE_CHECK_PREAMBLE = `<!-- bi-superpowers update-check preamble (auto-generated, do not edit) -->
+## ⬆ Update check
+
+Before handling the user's request below, run this command **once per conversation** and interpret the output:
+
+\`\`\`bash
+node "{skillBundleDir}/scripts/update-check.js" --silent-if-uptodate --silent-if-snoozed
+\`\`\`
+
+- Empty output or \`UPTODATE\` — proceed with the skill silently. No message.
+- \`UPDATE_AVAILABLE <installed> <latest>\` — tell the user exactly once this conversation, before diving into the skill:
+  > "bi-superpowers v{latest} is available (you are on v{installed}). Update with \`super upgrade\` (or \`/plugin update bi-superpowers\` in Claude Code) when convenient. If you use a local plugin generated with \`super kickoff\`, run \`super recharge\` in that repo afterwards."
+
+  Then continue with the skill below.
+- \`SNOOZED <iso>\` — proceed silently.
+
+If the command fails (missing binary, permissions, offline), ignore the error and proceed with the skill. The update check must never block the user's request.
+
+---
+<!-- /bi-superpowers update-check preamble -->
+
+`;
+
+function shouldIncludeUpdateCheckPreamble(skill, options = {}) {
+  if (options.skipPreamble) {
+    return false;
+  }
+  // bi-start owns the interactive update flow itself in PHASE 0. If we also
+  // prepend the generic passive preamble, the session-opener gets two
+  // competing update contracts in the same skill.
+  return skill.name !== 'bi-start';
+}
+
+/**
+ * Build command markdown with Claude Code frontmatter.
+ *
+ * @param {Object} skill - Skill definition object
+ * @param {string} libraryPrefix - Library prefix used in generated target
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.skipPreamble] - Omit the update-check preamble (tests)
+ * @returns {string} Command markdown
+ */
+function buildCommandMarkdown(skill, libraryPrefix, options = {}) {
+  const description = getSkillPurpose(skill.name);
+  const content = rewriteLibraryReferences(skill.content, libraryPrefix);
+  const preamble = shouldIncludeUpdateCheckPreamble(skill, options) ? UPDATE_CHECK_PREAMBLE : '';
+  const sourceEditPath = getSourceEditPath(skill);
+
+  return `---
+description: ${toFrontmatterValue(description)}
+---
+
+<!-- Generated by BI Agent Superpowers. Edit ${sourceEditPath} instead. -->
+
+${preamble}${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
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.skipPreamble] - Omit the update-check preamble (tests)
+ * @returns {string} Skill markdown
+ */
+function buildSkillMarkdown(skill, version, libraryPrefix, options = {}) {
+  const content = rewriteLibraryReferences(skill.content, libraryPrefix);
+  const preamble = shouldIncludeUpdateCheckPreamble(skill, options) ? UPDATE_CHECK_PREAMBLE : '';
+  const sourceEditPath = getSourceEditPath(skill);
+
+  return `---
+name: ${toFrontmatterValue(skill.name)}
+description: ${toFrontmatterValue(getPluginDescription(skill))}
+version: ${toFrontmatterValue(version)}
+---
+
+<!-- Generated by BI Agent Superpowers. Edit ${sourceEditPath} instead. -->
+
+${preamble}${content}`;
+}
+
+/**
+ * Copy bin/commands/update-check.js into each generated skill's scripts/
+ * directory so the preamble's `{skillBundleDir}/scripts/update-check.js`
+ * invocation works under both install paths (npm-based `super install` and
+ * Claude Code plugin marketplace). The file is bundled with the npm tarball
+ * via bin/, so this is purely a generation-time copy into skills/.
+ *
+ * @param {string} packageDir - npm package root (source of the canonical script)
+ * @param {string} targetDir - plugin target root (contains skills/<name>/)
+ * @param {Object[]} skills - Skills to wire the script into
+ */
+function copyUpdateCheckScript(packageDir, targetDir, skills, version = null) {
+  if (!packageDir) return;
+  const src = path.join(packageDir, 'bin', 'commands', 'update-check.js');
+  if (!fs.existsSync(src)) return;
+  const sourceContent = fs.readFileSync(src, 'utf8');
+  let bundledContent = sourceContent;
+  if (version) {
+    bundledContent = sourceContent.replace(
+      'const BUNDLED_INSTALLED_VERSION = null;',
+      `const BUNDLED_INSTALLED_VERSION = ${JSON.stringify(version)};`
+    );
+  }
+  for (const skill of skills) {
+    const scriptsDir = path.join(targetDir, 'skills', skill.name, 'scripts');
+    ensureDirectory(scriptsDir);
+    fs.writeFileSync(path.join(scriptsDir, 'update-check.js'), bundledContent);
+  }
+}
+
+/**
+ * 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);
+
+  // Pull discoverable metadata from the installed package.json when available
+  // so the generated plugin.json has the same repo/license/keywords/homepage
+  // fields as the published npm package. Falls back to bare identity fields
+  // if options.packageDir is missing (unit tests, detached generation).
+  let pkgMetadata = {};
+  if (options.packageDir) {
+    try {
+      const pkg = require(path.join(options.packageDir, 'package.json'));
+      pkgMetadata = {
+        repository: pkg.repository,
+        homepage: pkg.homepage,
+        license: pkg.license,
+        keywords: Array.isArray(pkg.keywords) ? pkg.keywords : undefined,
+      };
+    } catch (_) {
+      // Package.json unreadable — generate a minimal manifest and move on.
+    }
+  }
+
+  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',
+    },
+    ...(pkgMetadata.repository !== undefined ? { repository: pkgMetadata.repository } : {}),
+    ...(pkgMetadata.homepage !== undefined ? { homepage: pkgMetadata.homepage } : {}),
+    ...(pkgMetadata.license !== undefined ? { license: pkgMetadata.license } : {}),
+    ...(pkgMetadata.keywords !== undefined ? { keywords: pkgMetadata.keywords } : {}),
+  };
+
+  fs.writeFileSync(
+    path.join(pluginDir, 'plugin.json'),
+    JSON.stringify(pluginManifest, null, 2) + '\n'
+  );
+
+  // Generate marketplace.json with all skills listed and synced version.
+  // The descriptions are derived from the actual skill count so they never
+  // drift out of sync with the real plugin contents.
+  const skillCount = skills.length;
+  const skillsPlural = skillCount === 1 ? 'skill' : 'skills';
+  const metadataDescription = `AI-powered ${skillsPlural} for Power BI Desktop development. Works with Claude Code, GitHub Copilot, Codex, Gemini CLI, and Kilo Code.`;
+  const pluginDescription = `${skillCount} AI ${skillsPlural} + Power BI Modeling and Microsoft Learn MCP servers for local Power BI Desktop workflows across 5 AI agents.`;
+
+  const marketplaceManifest = {
+    name: 'bi-superpowers',
+    owner: {
+      name: 'Lucas Sanchez',
+      url: 'https://github.com/luquimbo',
+    },
+    metadata: {
+      description: metadataDescription,
+      version,
+      repository: 'https://github.com/luquimbo/bi-superpowers',
+    },
+    plugins: [
+      {
+        name: 'bi-superpowers',
+        description: pluginDescription,
+        source: './',
+        strict: false,
+        skills: skills.map((skill) => `./skills/${skill.name}`).sort(),
+      },
+    ],
+  };
+
+  fs.writeFileSync(
+    path.join(pluginDir, 'marketplace.json'),
+    JSON.stringify(marketplaceManifest, null, 2) + '\n'
+  );
+
+  // Generate skill-manifest.json — a compact summary of all skills with
+  // frontmatter metadata (name, title, description, category). Used by
+  // internal tooling (xray, powers, checkup) and as a CI consistency check.
+  // Intentionally omits timestamps so the file is deterministic and doesn't
+  // show as dirty in git on every build.
+  const skillManifest = {
+    name: 'bi-superpowers',
+    version,
+    skillCount: skills.length,
+    skills: skills.map((skill) => {
+      const metadata = parseSkillMetadata(skill.content);
+      return {
+        name: skill.name,
+        title: metadata.title || skill.name,
+        description: getPluginDescription(skill),
+        category: COMMAND_SKILLS.has(skill.name) ? 'command' : 'reference',
+        triggerCount: metadata.triggers.length,
+        path: `skills/${skill.name}/SKILL.md`,
+      };
+    }),
+  };
+
+  fs.writeFileSync(
+    path.join(pluginDir, 'skill-manifest.json'),
+    JSON.stringify(skillManifest, null, 2) + '\n'
+  );
+
+  // Open Plugin Spec — vendor-neutral manifest
+  // https://github.com/vercel-labs/open-plugin-spec
+  // Lives alongside the Claude-specific .claude-plugin/plugin.json so that
+  // non-Claude agents (future Cursor/Windsurf plugins, etc.) can discover
+  // bi-superpowers without depending on Claude-specific paths.
+  const openPluginDir = path.join(targetDir, '.plugin');
+  ensureDirectory(openPluginDir);
+  const openPluginManifest = {
+    spec: 'open-plugin-spec@1',
+    name: 'bi-superpowers',
+    version,
+    description: pluginManifest.description,
+    author: pluginManifest.author,
+    repository: 'https://github.com/luquimbo/bi-superpowers',
+    license: 'MIT',
+    skills: './skills/',
+    commands: './commands/',
+    mcpServers: './.mcp.json',
+  };
+  fs.writeFileSync(
+    path.join(openPluginDir, 'plugin.json'),
+    JSON.stringify(openPluginManifest, 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)
+  // Folder-based skills additionally get their `references/` and `scripts/`
+  // subfolders copied verbatim so the agent can load on-demand material and
+  // invoke helper scripts bundled with the skill.
+  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)
+    );
+
+    if (skill.bundleDir) {
+      copyDirectory(path.join(skill.bundleDir, 'references'), path.join(skillDir, 'references'));
+      copyDirectory(path.join(skill.bundleDir, 'scripts'), path.join(skillDir, 'scripts'));
+      copyDirectory(path.join(skill.bundleDir, 'examples'), path.join(skillDir, 'examples'));
+    }
+  }
+
+  // Ship the update-check helper alongside every skill so the SKILL.md
+  // preamble can invoke it via `{skillBundleDir}/scripts/update-check.js`
+  // regardless of install path.
+  copyUpdateCheckScript(options.packageDir, targetDir, skills, version);
+
+  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,
+  buildCommandMarkdown,
+  buildSkillMarkdown,
+  copyUpdateCheckScript,
+  UPDATE_CHECK_PREAMBLE,
+  COMMAND_SKILLS,
+  REFERENCE_SKILLS,
+};

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,
+};