@luquimbo/bi-superpowers 4.1.6 → 5.0.0

package/bin/commands/validate-projects.js

@@ -0,0 +1,425 @@
+/**
+ * Project Validation Command
+ * ==========================
+ *
+ * Validates public fixtures and private project references without copying
+ * customer repositories into this repo. Versioned descriptors live under
+ * validation/projects/*.json; private paths live in validation.local.json,
+ * which is intentionally ignored by git.
+ *
+ * Usage:
+ *   super validate-projects
+ *   super validate-projects --project super-test
+ *   super validate-projects --root C:\path\to\bi-superpowers
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_VALIDATION_DIR = 'validation';
+const DEFAULT_LOCAL_CONFIG = 'validation.local.json';
+
+function parseArgs(args) {
+  const options = {
+    rootDir: process.cwd(),
+    localConfigPath: null,
+    projectIds: [],
+    json: false,
+    list: false,
+    strict: false,
+  };
+
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+
+    if (arg === '--root') {
+      options.rootDir = readValue(args, ++index, arg);
+    } else if (arg === '--local') {
+      options.localConfigPath = readValue(args, ++index, arg);
+    } else if (arg === '--project' || arg === '-p') {
+      options.projectIds.push(readValue(args, ++index, arg));
+    } else if (arg === '--json') {
+      options.json = true;
+    } else if (arg === '--list') {
+      options.list = true;
+    } else if (arg === '--strict') {
+      options.strict = true;
+    }
+  }
+
+  options.rootDir = path.resolve(options.rootDir);
+  if (options.localConfigPath) {
+    options.localConfigPath = path.resolve(options.localConfigPath);
+  }
+  return options;
+}
+
+function readValue(args, index, flag) {
+  const value = args[index];
+  if (!value || value.startsWith('-')) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function readJsonStrict(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    throw new Error(`Cannot read JSON at ${filePath}: ${err.message}`);
+  }
+}
+
+function getValidationProjectsDir(rootDir) {
+  return path.join(rootDir, DEFAULT_VALIDATION_DIR, 'projects');
+}
+
+function getLocalConfigPath(rootDir, overridePath) {
+  return overridePath || path.join(rootDir, DEFAULT_LOCAL_CONFIG);
+}
+
+function loadProjectDescriptors(rootDir) {
+  const projectsDir = getValidationProjectsDir(rootDir);
+  if (!fs.existsSync(projectsDir)) {
+    throw new Error(
+      `Validation project descriptors not found at ${projectsDir}. ` +
+        'Run this command from the bi-superpowers source checkout or pass --root <repo>.'
+    );
+  }
+
+  const descriptorFiles = fs
+    .readdirSync(projectsDir)
+    .filter((file) => file.endsWith('.json'))
+    .sort();
+
+  if (descriptorFiles.length === 0) {
+    throw new Error(`No validation project descriptors found in ${projectsDir}.`);
+  }
+
+  return descriptorFiles.map((file) => {
+    const filePath = path.join(projectsDir, file);
+    const descriptor = readJsonStrict(filePath);
+    validateDescriptor(descriptor, filePath);
+    return { ...descriptor, descriptorPath: filePath };
+  });
+}
+
+function validateDescriptor(descriptor, filePath) {
+  if (!descriptor || typeof descriptor !== 'object' || Array.isArray(descriptor)) {
+    throw new Error(`Project descriptor must be an object: ${filePath}`);
+  }
+  if (!isValidProjectId(descriptor.id)) {
+    throw new Error(`Project descriptor has invalid id at ${filePath}`);
+  }
+  if (!descriptor.name || typeof descriptor.name !== 'string') {
+    throw new Error(`Project descriptor ${descriptor.id} must include a name`);
+  }
+  if (descriptor.path != null && typeof descriptor.path !== 'string') {
+    throw new Error(`Project descriptor ${descriptor.id} path must be a string`);
+  }
+  if (descriptor.path != null && path.isAbsolute(descriptor.path)) {
+    throw new Error(
+      `Project descriptor ${descriptor.id} path must be relative. Put private absolute paths in validation.local.json.`
+    );
+  }
+  if (descriptor.skills != null && !isStringArray(descriptor.skills)) {
+    throw new Error(`Project descriptor ${descriptor.id} skills must be an array of strings`);
+  }
+  if (descriptor.checks != null && !Array.isArray(descriptor.checks)) {
+    throw new Error(`Project descriptor ${descriptor.id} checks must be an array`);
+  }
+  for (const check of descriptor.checks || []) {
+    if (!check || typeof check !== 'object' || Array.isArray(check)) {
+      throw new Error(`Project descriptor ${descriptor.id} has an invalid check`);
+    }
+    if (!check.name || typeof check.name !== 'string') {
+      throw new Error(`Project descriptor ${descriptor.id} has a check without a name`);
+    }
+    if (!check.path || typeof check.path !== 'string') {
+      throw new Error(`Project descriptor ${descriptor.id} check ${check.name} needs a path`);
+    }
+    if (path.isAbsolute(check.path)) {
+      throw new Error(`Project descriptor ${descriptor.id} check ${check.name} must be relative`);
+    }
+  }
+}
+
+function isValidProjectId(value) {
+  return typeof value === 'string' && /^[a-z0-9][a-z0-9-]*$/.test(value);
+}
+
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+
+function loadLocalConfig(rootDir, overridePath) {
+  const localPath = getLocalConfigPath(rootDir, overridePath);
+  if (!fs.existsSync(localPath)) {
+    return { path: localPath, projects: {} };
+  }
+
+  const config = readJsonStrict(localPath);
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error(`Local validation config must be an object: ${localPath}`);
+  }
+  if (config.projects == null) {
+    return { path: localPath, projects: {} };
+  }
+  if (typeof config.projects !== 'object' || Array.isArray(config.projects)) {
+    throw new Error(`Local validation config projects must be an object: ${localPath}`);
+  }
+
+  for (const [projectId, project] of Object.entries(config.projects)) {
+    if (!isValidProjectId(projectId)) {
+      throw new Error(`Local validation config has invalid project id: ${projectId}`);
+    }
+    if (!project || typeof project !== 'object' || Array.isArray(project)) {
+      throw new Error(`Local validation project ${projectId} must be an object`);
+    }
+    if (!project.path || typeof project.path !== 'string') {
+      throw new Error(`Local validation project ${projectId} must include a path`);
+    }
+  }
+
+  return { path: localPath, projects: config.projects };
+}
+
+function mergeProjects(descriptors, localProjects) {
+  const merged = new Map();
+
+  for (const descriptor of descriptors) {
+    const local = localProjects[descriptor.id] || {};
+    merged.set(descriptor.id, {
+      ...descriptor,
+      path: local.path || descriptor.path,
+      localOnly: false,
+      localNotes: local.notes,
+    });
+  }
+
+  for (const [id, local] of Object.entries(localProjects)) {
+    if (merged.has(id)) {
+      continue;
+    }
+    merged.set(id, {
+      id,
+      name: local.name || id,
+      privacy: 'private-local',
+      path: local.path,
+      skills: local.skills || [],
+      checks: local.checks || [],
+      localOnly: true,
+      localNotes: local.notes,
+    });
+  }
+
+  return Array.from(merged.values()).sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function resolveProjectPath(rootDir, projectPath) {
+  if (!projectPath) {
+    return null;
+  }
+  return path.isAbsolute(projectPath)
+    ? path.normalize(projectPath)
+    : path.resolve(rootDir, projectPath);
+}
+
+function validateProject(project, rootDir) {
+  const resolvedPath = resolveProjectPath(rootDir, project.path);
+  const result = {
+    id: project.id,
+    name: project.name,
+    privacy: project.privacy || 'unspecified',
+    path: resolvedPath,
+    status: 'passed',
+    reason: null,
+    checks: [],
+  };
+
+  if (!resolvedPath) {
+    result.status = 'skipped';
+    result.reason = 'No path configured. Add this project to validation.local.json.';
+    return result;
+  }
+
+  if (!fs.existsSync(resolvedPath)) {
+    result.status = 'failed';
+    result.reason = `Project path does not exist: ${resolvedPath}`;
+    return result;
+  }
+
+  for (const check of project.checks || []) {
+    const checkPath = path.resolve(resolvedPath, check.path);
+    if (!isPathInside(resolvedPath, checkPath)) {
+      result.checks.push({
+        name: check.name,
+        path: checkPath,
+        passed: false,
+        reason: 'Check path escapes the project root.',
+      });
+      continue;
+    }
+    const passed = fs.existsSync(checkPath);
+    result.checks.push({
+      name: check.name,
+      path: checkPath,
+      passed,
+    });
+  }
+
+  if (result.checks.some((check) => !check.passed)) {
+    result.status = 'failed';
+    result.reason = 'One or more required project files are missing.';
+  }
+
+  return result;
+}
+
+function isPathInside(parentPath, childPath) {
+  const relative = path.relative(parentPath, childPath);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function runValidation(options) {
+  const descriptors = loadProjectDescriptors(options.rootDir);
+  const localConfig = loadLocalConfig(options.rootDir, options.localConfigPath);
+  const projects = mergeProjects(descriptors, localConfig.projects);
+  const selected = filterProjects(projects, options.projectIds);
+  const results = selected.projects.map((project) => validateProject(project, options.rootDir));
+
+  if (options.strict) {
+    for (const result of results) {
+      if (result.status === 'skipped') {
+        result.status = 'failed';
+        result.reason = `${result.reason} Strict mode treats skipped projects as failures.`;
+      }
+    }
+  }
+
+  return {
+    rootDir: options.rootDir,
+    localConfigPath: localConfig.path,
+    missingProjectIds: selected.missingProjectIds,
+    results,
+    summary: summarizeResults(results, selected.missingProjectIds),
+  };
+}
+
+function filterProjects(projects, ids) {
+  if (ids.length === 0) {
+    return { projects, missingProjectIds: [] };
+  }
+
+  const byId = new Map(projects.map((project) => [project.id, project]));
+  const selected = [];
+  const missingProjectIds = [];
+
+  for (const id of ids) {
+    if (byId.has(id)) {
+      selected.push(byId.get(id));
+    } else {
+      missingProjectIds.push(id);
+    }
+  }
+
+  return { projects: selected, missingProjectIds };
+}
+
+function summarizeResults(results, missingProjectIds = []) {
+  return {
+    total: results.length,
+    passed: results.filter((result) => result.status === 'passed').length,
+    failed:
+      results.filter((result) => result.status === 'failed').length + missingProjectIds.length,
+    skipped: results.filter((result) => result.status === 'skipped').length,
+  };
+}
+
+function printList(report) {
+  console.log('BI Agent Superpowers — Validation Projects');
+  console.log('==========================================\n');
+
+  if (report.results.length === 0) {
+    console.log('No project descriptors found.');
+    return;
+  }
+
+  for (const result of report.results) {
+    console.log(`- ${result.id}: ${result.name} (${result.privacy})`);
+  }
+}
+
+function printReport(report) {
+  console.log('BI Agent Superpowers — Project Validation');
+  console.log('=========================================\n');
+  console.log(`Root: ${report.rootDir}`);
+  console.log(`Local config: ${report.localConfigPath}`);
+  console.log('');
+
+  for (const missingId of report.missingProjectIds) {
+    console.log(`FAIL ${missingId}`);
+    console.log('  Project id was requested but no descriptor or local config exists.\n');
+  }
+
+  for (const result of report.results) {
+    const label = result.status.toUpperCase();
+    console.log(`${label} ${result.id} — ${result.name}`);
+    if (result.path) {
+      console.log(`  Path: ${result.path}`);
+    }
+    if (result.reason) {
+      console.log(`  ${result.reason}`);
+    }
+    for (const check of result.checks) {
+      const checkLabel = check.passed ? 'OK' : 'MISS';
+      console.log(`  ${checkLabel} ${check.name}: ${check.path}`);
+    }
+    console.log('');
+  }
+
+  const summary = report.summary;
+  console.log(
+    `Summary: ${summary.passed} passed, ${summary.failed} failed, ${summary.skipped} skipped (${summary.total} checked)`
+  );
+}
+
+function validateProjectsCommand(args) {
+  let options;
+  try {
+    options = parseArgs(args || []);
+    const report = runValidation(options);
+
+    if (options.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else if (options.list) {
+      printList(report);
+    } else {
+      printReport(report);
+    }
+
+    if (report.summary.failed > 0) {
+      process.exitCode = 1;
+    }
+  } catch (err) {
+    if (options && options.json) {
+      console.log(JSON.stringify({ error: err.message }, null, 2));
+    } else {
+      console.error(`Error: ${err.message}`);
+    }
+    process.exitCode = 1;
+  }
+}
+
+module.exports = Object.assign(validateProjectsCommand, {
+  parseArgs,
+  readJsonStrict,
+  loadProjectDescriptors,
+  loadLocalConfig,
+  mergeProjects,
+  resolveProjectPath,
+  validateProject,
+  isPathInside,
+  runValidation,
+  summarizeResults,
+});

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

@@ -20,12 +20,12 @@ const {
 } = require('../microsoft-mcp');
 const { parseSkillMetadata, getSkillPurpose } = require('./shared');
 
-// Currently the plugin ships 4 skills (bi-start, project-kickoff,
-// pbi-connect, report-design). bi-start is the session-opener that
+// Currently the plugin ships 4 skills (bi-start, bi-kickoff,
+// bi-connect, bi-report). bi-start is the session-opener that
 // routes to the other three; the rest are specialists.
 // 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', 'project-kickoff', 'pbi-connect', 'report-design']);
+const COMMAND_SKILLS = new Set(['bi-start', 'bi-kickoff', 'bi-connect', 'bi-report']);
 
 const REFERENCE_SKILLS = new Set();
 
@@ -124,6 +124,19 @@ 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
 // ---------------------------------------------------------------------------
@@ -185,12 +198,13 @@ 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 src/content/skills/${skill.name}.md instead. -->
+<!-- Generated by BI Agent Superpowers. Edit ${sourceEditPath} instead. -->
 
 ${preamble}${content}`;
 }
@@ -208,6 +222,7 @@ ${preamble}${content}`;
 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)}
@@ -215,7 +230,7 @@ description: ${toFrontmatterValue(getPluginDescription(skill))}
 version: ${toFrontmatterValue(version)}
 ---
 
-<!-- Generated by BI Agent Superpowers. Edit src/content/skills/${skill.name}.md instead. -->
+<!-- Generated by BI Agent Superpowers. Edit ${sourceEditPath} instead. -->
 
 ${preamble}${content}`;
 }

package/bin/lib/generators/shared.js

@@ -35,8 +35,8 @@ function parseSkillMetadata(content) {
   //   - Prose bullets:         - User mentions: "analizar proyecto", "new project"
   //   - Asterisk bullets:      * "pattern"
   // The regex intentionally doesn't anchor to bullet syntax — that's
-  // what broke extraction for project-kickoff (prose) and under-counted
-  // pbi-connect (first quote per bullet only) before this change.
+  // what broke extraction for bi-kickoff (prose) and under-counted
+  // bi-connect (first quote per bullet only) before this change.
   const triggerSection = content.match(/##\s+Trigger[\s\S]*?(?=##|$)/i);
   if (triggerSection) {
     const quotedFragments = triggerSection[0].match(/"([^"]+)"/g);
@@ -65,9 +65,9 @@ function parseSkillMetadata(content) {
  */
 const SKILL_PURPOSES = {
   'bi-start': 'Session opener — environment snapshot, update check, and routing to other skills',
-  'project-kickoff': 'Project analysis and planning',
-  'pbi-connect': 'Power BI Desktop connection',
-  'report-design': '3-page PBIR report generation for Power BI Desktop (Windows)',
+  'bi-kickoff': 'Project analysis and planning',
+  'bi-connect': 'Power BI Desktop connection and DAX UDF authoring',
+  'bi-report': '3-page PBIR report generation for Power BI Desktop (Windows)',
 };
 
 /**
@@ -205,8 +205,8 @@ function getFormatFooter() {
 ## Resources
 
 - Skills: \`skills/*/SKILL.md\` - BI workflow instructions
-- Report design references: \`skills/report-design/references/\` - PBIR layouts, themes, native visuals, and troubleshooting
-- Runtime scripts: \`skills/report-design/scripts/\` - PBIR visual, theme, and validation helpers
+- Report design references: \`skills/bi-report/references/\` - PBIR layouts, themes, native visuals, and troubleshooting
+- Runtime scripts: \`skills/bi-report/scripts/\` - PBIR visual, theme, and validation helpers
 
 ---
 

package/bin/lib/skills.js

@@ -138,16 +138,16 @@ function loadSkills(options = {}) {
 /**
  * Normalize any user-facing skill identifier into its canonical name.
  *
- * Accepts `dax`, `dax.md`, `report-design`, `report-design/SKILL.md`,
- * or `report-design\SKILL.md` (Windows separator) and returns the
+ * Accepts `dax`, `dax.md`, `bi-report`, `bi-report/SKILL.md`,
+ * or `bi-report\SKILL.md` (Windows separator) and returns the
  * canonical skill name used as the key in readSkillDirectory's
- * output map (`dax`, `report-design`).
+ * output map (`dax`, `bi-report`).
  *
  * Uses a single alternation regex so the longer suffix `/SKILL.md`
  * is tried BEFORE the bare `.md`. Earlier callers chained two
  * `.replace()` calls and stripped `.md` first, which meant the
- * `/SKILL.md` alternative never matched — `report-design/SKILL.md`
- * came out as `report-design/SKILL` and the lookup failed.
+ * `/SKILL.md` alternative never matched — `bi-report/SKILL.md`
+ * came out as `bi-report/SKILL` and the lookup failed.
  *
  * @param {string} input - User-supplied skill identifier
  * @returns {string} Canonical skill name

package/bin/postinstall.js

@@ -31,9 +31,9 @@ Funciona con los 5 agentes:
 
 4 skills iniciales:
   /bi-start          — Arrancar una sesión (menú + update + conexión)
-  /project-kickoff   — Analizá tu proyecto BI (proyecto nuevo)
-  /pbi-connect       — Conectá tu agente a Power BI Desktop
-  /report-design     — Generá reportes PBIR para Power BI Desktop (Windows)
+  /bi-kickoff   — Analizá tu proyecto BI (proyecto nuevo)
+  /bi-connect       — Conectá tu agente a Power BI Desktop
+  /bi-report     — Generá reportes PBIR para Power BI Desktop (Windows)
 
 2 MCP servers:
   powerbi-modeling-mcp — Conexión local a Power BI Desktop (XMLA)