@luquimbo/bi-superpowers 3.2.0 → 4.1.1

package/src/content/skills/report-design/scripts/ensure-pbi-cli.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# ensure-pbi-cli.sh — idempotent installer for pbi-cli-tool + pywin32
+# Run from any directory. Requires Python 3.10+ and pip on PATH.
+# Exit code 0 = ready, 1 = install failed
+
+set -e
+
+check_python() {
+  python --version 2>/dev/null | grep -qE "Python 3\.(1[0-9]|[2-9][0-9])" && return 0
+  python3 --version 2>/dev/null | grep -qE "Python 3\.(1[0-9]|[2-9][0-9])" && return 0
+  echo "❌ Python 3.10+ required. Install from Microsoft Store or python.org."
+  exit 1
+}
+
+check_pipx() {
+  pipx --version 2>/dev/null && return 0
+  python -m pipx --version 2>/dev/null && return 0
+  echo "📦 Installing pipx..."
+  pip install --user pipx 2>/dev/null || python -m pip install --user pipx
+  python -m pipx ensurepath
+  echo "⚠ Close and reopen your terminal, then re-run this script."
+  exit 1
+}
+
+check_pbi() {
+  pbi --version 2>/dev/null && return 0
+  echo "📦 Installing pbi-cli-tool..."
+  python -m pipx install pbi-cli-tool
+}
+
+inject_pywin32() {
+  python -m pipx inject pbi-cli-tool pywin32 2>/dev/null || true
+}
+
+echo "Checking pbi-cli-tool environment..."
+check_python
+check_pipx
+check_pbi
+inject_pywin32
+echo "✅ pbi-cli-tool is ready."
+pbi --version

package/src/content/skills/report-design/scripts/validate-pbir.js

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+/**
+ * validate-pbir.js — allowlist-driven PBIR validator.
+ *
+ * Complements `pbi report validate` (which does schema sanity) by enforcing
+ * the native-visuals allowlist maintained in create-visual.js. Catches:
+ *
+ *   - visualType that's not a native PBIR type (e.g. `stackedBarChart`,
+ *     typos) — Desktop renders these as "objeto visual personalizado" but
+ *     the CLI validate passes them. This is the exact bug F1 that motivated
+ *     the migration away from the CLI.
+ *
+ *   - bindings on roles that the type doesn't declare (e.g. `--bind size`
+ *     on a funnelChart) — CLI validate doesn't catch these either.
+ *
+ *   - missing required roles (e.g. a barChart with no Category).
+ *
+ *   - visualContainer schema drift (wrong $schema URL or missing `name`).
+ *
+ * Usage:
+ *   node validate-pbir.js <reportPath>
+ *   node validate-pbir.js --json <reportPath>    # machine-readable output
+ *
+ * Exit codes:
+ *   0  valid
+ *   1  validation errors found
+ *   2  I/O error (bad path, corrupt JSON)
+ *
+ * NOT a replacement for `pbi report validate` — run both. This validator
+ * trusts that the .Report folder is structurally correct (has definition/,
+ * pages/, etc.) and focuses on visual-level correctness that the CLI misses.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { NATIVE_VISUAL_TYPES, KNOWN_NON_NATIVE_TYPES } = require('./create-visual.js');
+
+const EXPECTED_VISUAL_SCHEMA =
+  'https://developer.microsoft.com/json-schemas/fabric/item/report/definition/visualContainer/2.7.0/schema.json';
+
+function fail(msg, code = 2) {
+  process.stderr.write(`validate-pbir: ${msg}\n`);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const out = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--json') out.json = true;
+    else if (a === '-h' || a === '--help') out.help = true;
+    else if (a.startsWith('-')) fail(`unknown flag: ${a}`, 2);
+    else positional.push(a);
+  }
+  out.reportPath = positional[0];
+  return out;
+}
+
+function printHelp() {
+  process.stdout.write(
+    [
+      'Usage: validate-pbir.js [--json] <reportPath>',
+      '',
+      'Arguments:',
+      '  reportPath   Path to a .Report folder',
+      '',
+      'Options:',
+      '  --json       Emit JSON instead of human-readable output',
+      '  -h, --help   Show this help',
+      '',
+      'Exit codes:',
+      '  0  valid',
+      '  1  validation errors found',
+      '  2  I/O error',
+      '',
+    ].join('\n')
+  );
+}
+
+function listPages(reportPath) {
+  const pagesDir = path.join(reportPath, 'definition', 'pages');
+  if (!fs.existsSync(pagesDir)) {
+    fail(`pages directory not found: ${pagesDir}`, 2);
+  }
+  const out = [];
+  for (const entry of fs.readdirSync(pagesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const pageJsonPath = path.join(pagesDir, entry.name, 'page.json');
+    if (!fs.existsSync(pageJsonPath)) continue;
+    out.push({ name: entry.name, dir: path.join(pagesDir, entry.name) });
+  }
+  return out;
+}
+
+function listVisuals(pageDir) {
+  const visualsDir = path.join(pageDir, 'visuals');
+  if (!fs.existsSync(visualsDir)) return [];
+  const out = [];
+  for (const entry of fs.readdirSync(visualsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const visualJsonPath = path.join(visualsDir, entry.name, 'visual.json');
+    if (!fs.existsSync(visualJsonPath)) continue;
+    out.push({ name: entry.name, path: visualJsonPath });
+  }
+  return out;
+}
+
+function readJsonSafe(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return { data: JSON.parse(raw), err: null };
+  } catch (err) {
+    return { data: null, err };
+  }
+}
+
+// Extracts the set of roles that have at least one projection bound.
+function boundRoles(visualData) {
+  const qs = visualData && visualData.visual && visualData.visual.query && visualData.visual.query.queryState;
+  if (!qs || typeof qs !== 'object') return new Set();
+  const bound = new Set();
+  for (const [role, spec] of Object.entries(qs)) {
+    const projections = spec && spec.projections;
+    if (Array.isArray(projections) && projections.length > 0) bound.add(role);
+  }
+  return bound;
+}
+
+function validateVisual(visual) {
+  const errors = [];
+  const { data, path: filePath } = visual;
+
+  // Schema URL check.
+  if (data.$schema !== EXPECTED_VISUAL_SCHEMA) {
+    errors.push({
+      severity: 'warn',
+      rule: 'schema-url',
+      message: `unexpected $schema (got ${data.$schema || 'none'})`,
+    });
+  }
+
+  // `name` must exist and match the folder.
+  if (typeof data.name !== 'string' || !data.name) {
+    errors.push({ severity: 'error', rule: 'name', message: 'missing "name"' });
+  }
+
+  const vt = data.visual && data.visual.visualType;
+  if (!vt) {
+    errors.push({ severity: 'error', rule: 'visual-type', message: 'missing visualType' });
+    return errors;
+  }
+
+  // Allowlist: known non-native (like stackedBarChart).
+  if (KNOWN_NON_NATIVE_TYPES[vt]) {
+    errors.push({
+      severity: 'error',
+      rule: 'non-native-type',
+      visualType: vt,
+      message: KNOWN_NON_NATIVE_TYPES[vt],
+    });
+    return errors;
+  }
+
+  const def = NATIVE_VISUAL_TYPES[vt];
+  if (!def) {
+    errors.push({
+      severity: 'error',
+      rule: 'unknown-type',
+      visualType: vt,
+      message: `visualType "${vt}" is not in the native allowlist. Run create-visual.js --list-types for the canonical list.`,
+    });
+    return errors;
+  }
+
+  // Check required roles are bound (skip for textbox — no roles).
+  if (vt !== 'textbox') {
+    const bound = boundRoles(data);
+    for (const [role, spec] of Object.entries(def.roles)) {
+      if (spec.required && !bound.has(role)) {
+        errors.push({
+          severity: 'error',
+          rule: 'missing-required-role',
+          visualType: vt,
+          role,
+          message: `required role "${role}" has no projections (visualType: ${vt})`,
+        });
+      }
+    }
+
+    // Check that every bound role is valid for this type.
+    for (const role of bound) {
+      if (!(role in def.roles)) {
+        errors.push({
+          severity: 'error',
+          rule: 'invalid-role',
+          visualType: vt,
+          role,
+          message: `role "${role}" is not valid for visualType ${vt}. Valid: ${Object.keys(def.roles).join(', ') || '(none)'}`,
+        });
+      }
+    }
+  }
+
+  return errors;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    return;
+  }
+  if (!args.reportPath) fail('reportPath is required. Run --help for usage.', 2);
+
+  const reportPath = path.resolve(args.reportPath);
+  if (!fs.existsSync(reportPath)) fail(`not found: ${reportPath}`, 2);
+
+  const pages = listPages(reportPath);
+  const results = {
+    reportPath,
+    pagesChecked: pages.length,
+    visualsChecked: 0,
+    errors: [],
+  };
+
+  for (const page of pages) {
+    const visuals = listVisuals(page.dir);
+    // Track visual.name per page so we can flag duplicates. PBI Desktop
+    // does not reject a duplicate-name pair on load, but downstream tooling
+    // that references visuals by name (filters, bookmarks, selections) gets
+    // ambiguous — validate-pbir treats it as a hard error.
+    const namesSeenOnPage = new Map();
+    for (const v of visuals) {
+      results.visualsChecked += 1;
+      const { data, err } = readJsonSafe(v.path);
+      if (err) {
+        results.errors.push({
+          page: page.name,
+          visual: v.name,
+          severity: 'error',
+          rule: 'bad-json',
+          message: `could not parse visual.json: ${err.message}`,
+        });
+        continue;
+      }
+
+      // Duplicate-name check (page-scoped).
+      const declaredName = data && typeof data.name === 'string' ? data.name : null;
+      if (declaredName) {
+        if (namesSeenOnPage.has(declaredName)) {
+          results.errors.push({
+            page: page.name,
+            visual: v.name,
+            severity: 'error',
+            rule: 'duplicate-name',
+            message: `visual name "${declaredName}" is also used by "${namesSeenOnPage.get(declaredName)}" on this page`,
+          });
+        } else {
+          namesSeenOnPage.set(declaredName, v.name);
+        }
+      }
+
+      const visualErrors = validateVisual({ data, path: v.path });
+      for (const e of visualErrors) {
+        results.errors.push({
+          page: page.name,
+          visual: v.name,
+          ...e,
+        });
+      }
+    }
+  }
+
+  const errorCount = results.errors.filter((e) => e.severity === 'error').length;
+  const warnCount = results.errors.filter((e) => e.severity === 'warn').length;
+  const valid = errorCount === 0;
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify({ ...results, valid, errorCount, warnCount }, null, 2) + '\n');
+  } else {
+    const W = 77; // inner width between the | borders
+    const padRow = (label, value) => {
+      const text = `${label}: ${value}`;
+      return `| ${text}${' '.repeat(Math.max(0, W - text.length - 1))}|`;
+    };
+    const border = `+${'-'.repeat(W)}+`;
+    process.stdout.write(border + '\n');
+    process.stdout.write(padRow('valid', valid ? 'True' : 'False') + '\n');
+    process.stdout.write(padRow('pages_checked', String(results.pagesChecked)) + '\n');
+    process.stdout.write(padRow('visuals_checked', String(results.visualsChecked)) + '\n');
+    process.stdout.write(padRow('errors', String(errorCount)) + '\n');
+    process.stdout.write(padRow('warnings', String(warnCount)) + '\n');
+    process.stdout.write(border + '\n');
+    if (results.errors.length) {
+      process.stdout.write('\nIssues:\n');
+      for (const e of results.errors) {
+        const icon = e.severity === 'error' ? '✗' : '⚠';
+        const loc = `${e.page}/${e.visual}`;
+        process.stdout.write(`  ${icon} [${e.rule}] ${loc}: ${e.message}\n`);
+      }
+      process.stdout.write('\n');
+    }
+  }
+
+  process.exit(valid ? 0 : 1);
+}
+
+module.exports = {
+  validateVisual,
+  boundRoles,
+  listPages,
+  listVisuals,
+  parseArgs,
+};
+
+if (require.main === module) {
+  main();
+}

package/bin/commands/install.test.js

@@ -1,289 +0,0 @@
-/**
- * Unit tests for the install command
- *
- * Run with: npm test
- */
-
-const { test, describe, beforeEach, afterEach } = require('node:test');
-const assert = require('node:assert');
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-const installCommand = require('./install');
-const { parseArgs, detectAgents, copySkillDir, formatFsError, AGENTS, UNIVERSAL_DIR } =
-  installCommand;
-
-describe('install command - parseArgs', () => {
-  test('parses --yes/-y flag', () => {
-    assert.strictEqual(parseArgs(['--yes']).isYes, true);
-    assert.strictEqual(parseArgs(['-y']).isYes, true);
-    assert.strictEqual(parseArgs([]).isYes, false);
-  });
-
-  test('parses --all flag', () => {
-    assert.strictEqual(parseArgs(['--all']).isAll, true);
-    assert.strictEqual(parseArgs([]).isAll, false);
-  });
-
-  test('parses multiple --agent flags', () => {
-    const opts = parseArgs(['--agent', 'claude-code', '--agent', 'codex']);
-    assert.deepStrictEqual(opts.agentFlags, ['claude-code', 'codex']);
-  });
-
-  test('parses short -a flag', () => {
-    const opts = parseArgs(['-a', 'claude-code', '-a', 'kilo']);
-    assert.deepStrictEqual(opts.agentFlags, ['claude-code', 'kilo']);
-  });
-
-  test('ignores --agent without value (end of args)', () => {
-    const opts = parseArgs(['--agent']);
-    assert.deepStrictEqual(opts.agentFlags, []);
-  });
-
-  test('ignores --agent when next arg is another flag', () => {
-    const opts = parseArgs(['--agent', '--yes']);
-    assert.deepStrictEqual(opts.agentFlags, []);
-    assert.strictEqual(opts.isYes, true);
-  });
-
-  test('combines all flags correctly', () => {
-    const opts = parseArgs(['--all', '--yes', '-a', 'claude-code']);
-    assert.strictEqual(opts.isAll, true);
-    assert.strictEqual(opts.isYes, true);
-    assert.deepStrictEqual(opts.agentFlags, ['claude-code']);
-  });
-});
-
-describe('install command - AGENTS registry', () => {
-  test('has exactly 5 supported agents', () => {
-    assert.strictEqual(Object.keys(AGENTS).length, 5);
-  });
-
-  test('includes the 5 officially supported agents', () => {
-    const ids = Object.keys(AGENTS);
-    assert.ok(ids.includes('github-copilot'));
-    assert.ok(ids.includes('claude-code'));
-    assert.ok(ids.includes('codex'));
-    assert.ok(ids.includes('gemini-cli'));
-    assert.ok(ids.includes('kilo'));
-  });
-
-  test('every agent has name and dir fields', () => {
-    for (const [id, agent] of Object.entries(AGENTS)) {
-      assert.ok(agent.name, `${id} missing name`);
-      assert.ok(agent.dir, `${id} missing dir`);
-      assert.ok(agent.dir.startsWith('.'), `${id} dir should start with .`);
-    }
-  });
-
-  test('UNIVERSAL_DIR is .agents/skills', () => {
-    assert.strictEqual(UNIVERSAL_DIR, '.agents/skills');
-  });
-
-  test('codex uses UNIVERSAL_DIR', () => {
-    assert.strictEqual(AGENTS.codex.dir, UNIVERSAL_DIR);
-  });
-});
-
-describe('install command - detectAgents', () => {
-  let tempDir;
-
-  beforeEach(() => {
-    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bi-install-test-'));
-  });
-
-  afterEach(() => {
-    fs.rmSync(tempDir, { recursive: true, force: true });
-  });
-
-  test('returns empty array when no agents are installed', () => {
-    const detected = detectAgents(tempDir);
-    assert.deepStrictEqual(detected, []);
-  });
-
-  test('detects claude-code when .claude exists', () => {
-    fs.mkdirSync(path.join(tempDir, '.claude'), { recursive: true });
-    const detected = detectAgents(tempDir);
-    assert.ok(detected.includes('claude-code'));
-  });
-
-  test('detects multiple agents', () => {
-    fs.mkdirSync(path.join(tempDir, '.claude'), { recursive: true });
-    fs.mkdirSync(path.join(tempDir, '.copilot'), { recursive: true });
-    fs.mkdirSync(path.join(tempDir, '.gemini'), { recursive: true });
-    const detected = detectAgents(tempDir);
-    assert.ok(detected.includes('claude-code'));
-    assert.ok(detected.includes('github-copilot'));
-    assert.ok(detected.includes('gemini-cli'));
-  });
-});
-
-describe('install command - copySkillDir', () => {
-  let srcDir;
-  let destDir;
-
-  beforeEach(() => {
-    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bi-install-copy-'));
-    srcDir = path.join(tempDir, 'src');
-    destDir = path.join(tempDir, 'dest');
-    fs.mkdirSync(srcDir, { recursive: true });
-  });
-
-  afterEach(() => {
-    fs.rmSync(path.dirname(srcDir), { recursive: true, force: true });
-  });
-
-  test('copies a single file', () => {
-    fs.writeFileSync(path.join(srcDir, 'SKILL.md'), '# Test');
-    copySkillDir(srcDir, destDir);
-    assert.strictEqual(fs.readFileSync(path.join(destDir, 'SKILL.md'), 'utf8'), '# Test');
-  });
-
-  test('creates destination directory if missing', () => {
-    fs.writeFileSync(path.join(srcDir, 'SKILL.md'), 'content');
-    copySkillDir(srcDir, destDir);
-    assert.ok(fs.existsSync(destDir));
-  });
-
-  test('copies nested directories recursively', () => {
-    fs.writeFileSync(path.join(srcDir, 'SKILL.md'), 'top');
-    fs.mkdirSync(path.join(srcDir, 'references'));
-    fs.writeFileSync(path.join(srcDir, 'references', 'notes.md'), 'nested');
-    fs.mkdirSync(path.join(srcDir, 'scripts'));
-    fs.writeFileSync(path.join(srcDir, 'scripts', 'run.sh'), '#!/bin/sh');
-
-    copySkillDir(srcDir, destDir);
-
-    assert.strictEqual(fs.readFileSync(path.join(destDir, 'SKILL.md'), 'utf8'), 'top');
-    assert.strictEqual(
-      fs.readFileSync(path.join(destDir, 'references', 'notes.md'), 'utf8'),
-      'nested'
-    );
-    assert.strictEqual(
-      fs.readFileSync(path.join(destDir, 'scripts', 'run.sh'), 'utf8'),
-      '#!/bin/sh'
-    );
-  });
-});
-
-describe('install command - formatFsError', () => {
-  test('includes the context and error message', () => {
-    const err = new Error('oops');
-    err.code = 'UNKNOWN';
-    const msg = formatFsError(err, 'Failed');
-    assert.ok(msg.includes('Failed'));
-    assert.ok(msg.includes('oops'));
-  });
-
-  test('adds hint for EACCES', () => {
-    const err = new Error('permission denied');
-    err.code = 'EACCES';
-    const msg = formatFsError(err, 'Failed');
-    assert.ok(msg.toLowerCase().includes('permiso'));
-  });
-
-  test('adds hint for EPERM (Windows admin)', () => {
-    const err = new Error('not permitted');
-    err.code = 'EPERM';
-    const msg = formatFsError(err, 'Failed');
-    assert.ok(msg.toLowerCase().includes('admin'));
-  });
-
-  test('adds hint for ENOSPC', () => {
-    const err = new Error('no space');
-    err.code = 'ENOSPC';
-    const msg = formatFsError(err, 'Failed');
-    assert.ok(msg.toLowerCase().includes('espacio'));
-  });
-});
-
-describe('install command - module exports', () => {
-  test('module default export is a function', () => {
-    assert.strictEqual(typeof installCommand, 'function');
-  });
-
-  test('exposes internal helpers for testing', () => {
-    assert.strictEqual(typeof installCommand.parseArgs, 'function');
-    assert.strictEqual(typeof installCommand.detectAgents, 'function');
-    assert.strictEqual(typeof installCommand.copySkillDir, 'function');
-    assert.strictEqual(typeof installCommand.formatFsError, 'function');
-  });
-});
-
-describe('install command - integration: --all --yes', () => {
-  let tempHome;
-  let tempPkg;
-  let origHome;
-
-  beforeEach(() => {
-    tempHome = fs.mkdtempSync(path.join(os.tmpdir(), 'bi-install-int-home-'));
-    tempPkg = fs.mkdtempSync(path.join(os.tmpdir(), 'bi-install-int-pkg-'));
-
-    // Minimal fake package layout: skills/<name>/SKILL.md + launcher file
-    const skillsDir = path.join(tempPkg, 'skills');
-    for (const skillName of ['project-kickoff', 'pbi-connect']) {
-      const dir = path.join(skillsDir, skillName);
-      fs.mkdirSync(dir, { recursive: true });
-      fs.writeFileSync(
-        path.join(dir, 'SKILL.md'),
-        `---\nname: ${skillName}\ndescription: fake skill for test\n---\n# ${skillName}\n`
-      );
-    }
-    fs.mkdirSync(path.join(tempPkg, 'bin', 'mcp'), { recursive: true });
-    fs.writeFileSync(
-      path.join(tempPkg, 'bin', 'mcp', 'powerbi-modeling-launcher.js'),
-      '// fake launcher\n'
-    );
-
-    origHome = os.homedir;
-    os.homedir = () => tempHome;
-  });
-
-  afterEach(() => {
-    os.homedir = origHome;
-    fs.rmSync(tempHome, { recursive: true, force: true });
-    fs.rmSync(tempPkg, { recursive: true, force: true });
-  });
-
-  test('installs skills and writes MCP config for all 5 agents', async () => {
-    const origExitCode = process.exitCode;
-    try {
-      await installCommand(['--all', '--yes'], {
-        packageDir: tempPkg,
-        version: '9.9.9-test',
-      });
-    } finally {
-      // Reset exit code so subsequent tests aren't affected
-      process.exitCode = origExitCode;
-    }
-
-    // Skills installed at universal path
-    assert.ok(
-      fs.existsSync(path.join(tempHome, '.agents', 'skills', 'project-kickoff', 'SKILL.md'))
-    );
-    assert.ok(fs.existsSync(path.join(tempHome, '.agents', 'skills', 'pbi-connect', 'SKILL.md')));
-
-    // MCP configs written for all 5 agents
-    const expectedMcpFiles = [
-      path.join(tempHome, '.claude.json'),
-      path.join(tempHome, '.copilot', 'mcp-config.json'),
-      path.join(tempHome, '.codex', 'config.toml'),
-      path.join(tempHome, '.gemini', 'settings.json'),
-      path.join(tempHome, '.kilo', 'mcp_settings.json'),
-    ];
-    for (const filePath of expectedMcpFiles) {
-      assert.ok(fs.existsSync(filePath), `expected MCP config at ${filePath}`);
-    }
-
-    // Claude Code config has both servers under mcpServers
-    const claudeConfig = JSON.parse(fs.readFileSync(path.join(tempHome, '.claude.json'), 'utf8'));
-    assert.ok(claudeConfig.mcpServers['powerbi-modeling']);
-    assert.ok(claudeConfig.mcpServers['microsoft-learn']);
-
-    // Codex TOML has both sections
-    const codexToml = fs.readFileSync(path.join(tempHome, '.codex', 'config.toml'), 'utf8');
-    assert.ok(codexToml.includes('[mcp_servers.powerbi-modeling]'));
-    assert.ok(codexToml.includes('[mcp_servers.microsoft-learn]'));
-  });
-});