@luquimbo/bi-superpowers 3.2.0 → 4.1.1

package/skills/report-design/references/troubleshooting.md

@@ -0,0 +1,135 @@
+# Report design troubleshooting
+
+Common failure modes when generating reports via `pbi-cli-tool` + the close-write-open pattern, and how to resolve them.
+
+## Install / environment
+
+### `pbi: command not found`
+
+`pbi-cli-tool` is not installed or `pipx` bin dir is not on PATH.
+
+1. Install: `pipx install pbi-cli-tool`
+2. If still missing: `python -m pipx ensurepath`
+3. **Close and reopen the terminal** to pick up the new PATH entries.
+
+### `Error: pywin32 is not installed. Install with: pip install pywin32`
+
+You installed `pywin32` into the wrong Python environment. The CLI runs in its own isolated `pipx` venv and doesn't see user-site packages.
+
+Fix:
+
+```bash
+python -m pipx inject pbi-cli-tool pywin32
+```
+
+### `pipx --version` works but `pbi --version` says command not found
+
+PATH race after `ensurepath`. Close and reopen the terminal. If still broken:
+
+```bash
+python -m pipx list
+```
+
+Confirm `pbi-cli-tool` is listed. If not, install it again. Look for the "apps are available" line that includes `pbi.exe`.
+
+### `Environment not ready` from `pbi setup`
+
+Output usually names the specific check that failed. Common causes:
+- Python version too old (need 3.10+)
+- Missing Microsoft DLLs — re-run `pipx install pbi-cli-tool --force`
+- No Power BI Desktop running — setup requires at least one .pbip open
+
+## Connection
+
+### `pbi connect` says "No Power BI Desktop instance found"
+
+Desktop is not running, or the `.pbip` hasn't finished loading yet. Open Desktop with a .pbip, wait for the model to fully load (status bar shows "Connected"), then retry `pbi connect`.
+
+### `pbi connect` succeeds but `pbi measure list` returns empty
+
+The connected Desktop instance isn't loaded with a model, or the model has no measures yet. Check with `pbi table list` — if tables exist but measures don't, the user hasn't created any measures yet. Stop and ask them to add at least one (via PBI Desktop UI or `/project-kickoff`).
+
+## Generation failures
+
+### Visuals don't render after relaunch
+
+The #1 cause is **not actually doing the close-write-open cycle**. Checks:
+
+1. Did `PBIDesktop.exe` actually die before the writes? Run `tasklist | grep PBIDesktop` before and after the kill. If before shows a PID and after still shows it, the kill failed (permission issue, maybe).
+2. Did `Start-Process` launch a *new* process? Its PID must differ from the one you killed. Compare.
+3. Does `pbi report validate` report `valid: True`? If not, the report won't load visuals that have invalid JSON.
+
+If all three are correct and visuals still don't render, see `close-write-open-pattern.md` — there might be a specific gotcha for the user's system (AV scanner, path locking).
+
+### `pbi report validate` errors
+
+Typical causes:
+
+- **"Binding references a measure/column that doesn't exist"** → the `Table[Measure]` or `Table[Column]` you passed to `pbi visual bind` doesn't match the model. Rerun `pbi measure list` / `pbi column list --table X` and use the exact names.
+- **"Page name collision"** → you tried to add a page with the same `--name` as an existing one. Use a different name or delete the existing page first (`pbi report delete-page`).
+- **"Visual of that name already exists"** → same rule, different object.
+
+### "Visual rendered but shows (Blank) or #REF"
+
+The binding resolved at write time but the data returns nothing at query time. Usually:
+- The measure filters to zero rows with the current page filters
+- The column you bound as `--category` doesn't have data for the measure's grain
+- You bound to a calculated column that depends on a hidden measure
+
+Fix: change the binding to a better-grained dim column, or add a date filter to the page.
+
+### Bar chart shows `barChart` but we specified `bar_chart`
+
+Expected — the `--type bar_chart` is a user-friendly alias. The CLI writes `"visualType": "barChart"` to disk. Desktop uses the raw ID. This is fine, not a bug.
+
+## After relaunch
+
+### Desktop crashes or hangs after relaunch
+
+Usually an AV scanner quarantining the .pbip during reopen. Wait 30s, relaunch. If persistent, add the project folder to AV exclusions.
+
+### Only some visuals render
+
+Race condition: Desktop started loading while the CLI was still writing. Can happen if `Start-Process` is called before the last CLI write finished.
+
+Fix:
+1. Wait 2-3 seconds after the last CLI command before launching Desktop
+2. Or run `pbi report validate` as a barrier — it won't complete until all writes are flushed
+
+### A visual renders but at wrong position
+
+The CLI may have ignored one of your `--x`/`--y`/`--width`/`--height` flags, or you passed them without `--no-sync` during a phase where Desktop was still running and it normalized the position.
+
+Fix with `pbi visual update`:
+
+```bash
+pbi visual --no-sync update "{name}" --page "{page}" --x 16 --y 16 --width 280 --height 120
+```
+
+Then close-write-open again to see the change.
+
+### User says "I don't see the changes" after relaunch
+
+Did they open the .pbip that we wrote to, or a different one? Confirm the full path:
+
+```
+El archivo que tenía que abrir era:
+  C:\...\pbip-files\{projectName}.pbip
+
+¿Es el que está viendo?
+```
+
+## When in doubt: checkpoint + retry
+
+If things get confusing:
+
+1. `pbi report validate` — confirms disk state
+2. `pbi visual list --page X` — confirms which visuals exist per page
+3. Full close-write-open cycle once more
+
+If that doesn't resolve it, capture:
+- Output of the last few CLI commands (especially any error text)
+- `tasklist | grep PBIDesktop` — process state
+- File listing of `./pbip-files/{proj}.Report/definition/pages/`
+
+And hand off to the user for a manual debug session.

package/skills/report-design/references/visual-types.md

@@ -0,0 +1,78 @@
+# PBIR visualType IDs — what works, what doesn't (PBI Desktop March 2026)
+
+The `pbi visual add --type` flag accepts a small set of friendly aliases. When you write `visual.json` directly (e.g. for textbox/slicer or for a chart variant the CLI doesn't expose), you set `visual.visualType` to a raw PBIR typeId.
+
+**The problem**: PBIR's JSON schema accepts MANY typeIds (`pbi report validate` returns `valid: True`), but PBI Desktop only renders a subset of them. The rest fail silently — the visual container appears empty, no error toast.
+
+This doc lists the typeIds we've personally tested in `examples/smoke-test/` against PBI Desktop standalone. Treat the **NOT NATIVE** column as authoritative for this Desktop build; if Microsoft adds support in a later build, update the table.
+
+## Confirmed native (renders correctly)
+
+| visualType | Use for | Notes |
+|---|---|---|
+| `card` | Single KPI value | |
+| `cardVisual` | New card visual (multi-row, image, reference label) | Mar 2026 — schema overrides risky, prefer `card` until validated |
+| `multiRowCard` | Compact KPI list | |
+| `kpi` | KPI with goal + trend | Use `directionGood: Positive` in theme |
+| `gauge` | Circular gauge | |
+| `slicer` | Default slicer (list / dropdown) | Modes via `mode` property — see `slicer.md` |
+| `advancedSlicerVisual` | New slicer (Mar 2026 unified slicer) | Modes via `mode` |
+| `listSlicer` | List-only slicer | Older typeId |
+| `textSlicer` | Text input slicer | |
+| `barChart` | Horizontal bars | Add `Series` field for stacking |
+| `clusteredBarChart` | Side-by-side horizontal bars | |
+| `columnChart` | Vertical bars | Add `Series` for stacking |
+| `clusteredColumnChart` | Side-by-side vertical bars | |
+| `hundredPercentStackedBarChart` | 100% horizontal | |
+| `hundredPercentStackedColumnChart` | 100% vertical | |
+| `lineChart` | Time series | |
+| `areaChart` | Area | Add `Series` for stacking |
+| `lineClusteredColumnComboChart` | Line + clustered columns | The only combo variant that works native |
+| `pieChart` | Single-level part-to-whole | |
+| `donutChart` | Pie with hole | |
+| `treemap` | Hierarchical part-to-whole | |
+| `funnelChart` | Funnel / pipeline | |
+| `scatterChart` | X/Y/Size correlation | |
+| `waterfallChart` | Increase/decrease bridges | |
+| `tableEx` | Modern table | |
+| `pivotTable` | Matrix / pivot | |
+| `textbox` | Static text panels | Schema in `textbox.md` |
+
+## NOT NATIVE — passes `validate` but Desktop won't render
+
+If you write any of these, the visual container appears EMPTY in Desktop. No error message. Use the workaround instead.
+
+| visualType (DON'T USE) | Replace with | Workaround note |
+|---|---|---|
+| `stackedBarChart` | `barChart` | Add a `Series` (Legend) field — Desktop auto-stacks when a series is present |
+| `stackedColumnChart` | `columnChart` | Same workaround — Series field triggers stacking |
+| `stackedAreaChart` | `areaChart` | Series field stacks the areas |
+| `lineStackedColumnComboChart` | `lineClusteredColumnComboChart` | The clustered variant works; the stacked variant does not |
+| `funnel` | `funnelChart` | The bare `funnel` typeId is from older PBIR; modern Desktop uses `funnelChart` |
+| `ribbonChart` | (test before using) | Untested as of Mar 2026 — likely needs Power BI Visuals preview flag |
+
+## Maps (special case — need geo data)
+
+| visualType | Renders without bindings? |
+|---|---|
+| `map` | yes (placeholder/world map) |
+| `filledMap` | yes |
+| `azureMap` | yes (requires Azure Maps preview enabled in Desktop options) |
+| `shapeMap` | needs preview flag — many users have it off |
+
+For a model without geo columns, the map visual still draws an empty world — useful for theme galleries, useless for data.
+
+## Source of this list
+
+- Personally tested in `examples/smoke-test/pbip-files/super-test.Report/definition/pages/theme/` against PBI Desktop standalone (build 2.152.x, March 2026).
+- The `stackedBarChart` finding was first captured in commit `0243acf` (B4 fix). The `stackedAreaChart` and `lineStackedColumnComboChart` findings came from the smoke test "Galería de Visuales" iteration.
+- If you discover a new typeId that fails silently or works unexpectedly, update this table and reference it from `SKILL.md` PHASE 4.2.
+
+## How to verify a typeId yourself
+
+1. Write a minimal `visual.json` with the typeId in question + a known-good binding.
+2. Run `pbi report validate` — must return `valid: True`. (If it fails, the typeId is wrong-spelled.)
+3. Close-write-open: kill PBIDesktop, save, relaunch via `cmd /c start "" "{exePath}" "{pbipPath}"`.
+4. Open the page. If the container is empty (no chart, no error), the typeId is **NOT NATIVE**. Add it to the bottom table above with the workaround.
+
+This is cheap to test — under 30s per typeId — and the only way to know for sure, since Microsoft doesn't publish a definitive list of supported typeIds per Desktop build.

package/skills/report-design/scripts/apply-theme.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * apply-theme.js — register a custom PBIR theme correctly
+ *
+ * Power BI Desktop March 2026 (build 2.152.x) rejects the report.json
+ * shape that `pbi report set-theme` writes for custom themes:
+ *
+ *   - It writes `themeCollection.customTheme.reportVersionAtImport`
+ *     with the wrong type (string instead of {visual, report, page}).
+ *   - It writes `resourcePackages[].items[].type` with the wrong value
+ *     ("RegisteredResources" instead of "CustomTheme").
+ *
+ * Both errors block the .pbip from opening. This script bypasses that
+ * regression and writes the canonical PBIR shape verified against the
+ * K201-MonthSlicer.Report example shipped with Kurt Buhler's pbip
+ * skill (research/.../K201-MonthSlicer.Report).
+ *
+ * Canonical shape produced:
+ *
+ *   themeCollection.customTheme = {
+ *     name: "<themeFileName>.json",
+ *     reportVersionAtImport: { visual, report, page },   // copied from baseTheme
+ *     type: "RegisteredResources"                         // package name (where it lives)
+ *   }
+ *
+ *   resourcePackages += {
+ *     name: "RegisteredResources",
+ *     type: "RegisteredResources",
+ *     items: [
+ *       { name: "<themeFileName>.json", path: "<themeFileName>.json", type: "CustomTheme" }
+ *     ]
+ *   }
+ *
+ *   <reportPath>/StaticResources/RegisteredResources/<themeFileName>.json   <- physical theme JSON
+ *
+ * Usage:
+ *   node apply-theme.js --report-path ./pbip-files/MyProj.Report \
+ *                       --theme-file ./references/themes/BISuperpowers.json
+ *
+ * Idempotent: re-running with the same theme file replaces the existing
+ * customTheme entry in place; re-running with a different theme replaces
+ * the previous custom theme so only one is registered at a time.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function fail(msg) {
+  process.stderr.write(`apply-theme: ${msg}\n`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--report-path' || a === '-p') out.reportPath = argv[++i];
+    else if (a === '--theme-file' || a === '-f') out.themeFile = argv[++i];
+    else if (a === '--name' || a === '-n') out.name = argv[++i];
+    else if (a === '--help' || a === '-h') out.help = true;
+    else fail(`unknown argument: ${a}`);
+  }
+  return out;
+}
+
+function help() {
+  process.stdout.write(
+    [
+      'Usage: apply-theme.js --report-path <path> --theme-file <path> [--name <name>]',
+      '',
+      'Options:',
+      '  -p, --report-path  Path to the .Report folder (e.g. ./pbip-files/MyProj.Report).',
+      '  -f, --theme-file   Path to the theme JSON file to register.',
+      '  -n, --name         Optional override for the registered file name (defaults to basename of --theme-file).',
+      '  -h, --help         Show this help.',
+      '',
+    ].join('\n')
+  );
+}
+
+function readJson(filePath, label) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    fail(`could not read ${label} (${filePath}): ${err.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    fail(`${label} is not valid JSON (${filePath}): ${err.message}`);
+  }
+  return null; // unreachable
+}
+
+function writeJsonAtomic(filePath, data) {
+  // Backup once if a file already exists, write to .tmp, atomic rename.
+  // Same pattern as bin/lib/mcp-config.js writeFileAtomic — protects
+  // against half-written report.json on crash mid-write.
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  if (fs.existsSync(filePath)) {
+    fs.copyFileSync(filePath, `${filePath}.bak`);
+  }
+  const tmp = `${filePath}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n');
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch (_) {
+      // best-effort cleanup
+    }
+    throw err;
+  }
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    help();
+    return;
+  }
+  if (!args.reportPath) fail('--report-path is required');
+  if (!args.themeFile) fail('--theme-file is required');
+
+  const reportPath = path.resolve(args.reportPath);
+  const themeFile = path.resolve(args.themeFile);
+
+  if (!fs.existsSync(reportPath)) fail(`report path not found: ${reportPath}`);
+  if (!fs.existsSync(themeFile)) fail(`theme file not found: ${themeFile}`);
+
+  const reportJsonPath = path.join(reportPath, 'definition', 'report.json');
+  if (!fs.existsSync(reportJsonPath))
+    fail(`expected ${reportJsonPath} to exist; is this a .Report folder?`);
+
+  const reportJson = readJson(reportJsonPath, 'report.json');
+  // Sanity-validate the theme JSON. PBI themes always have a `name` field.
+  const themeJson = readJson(themeFile, 'theme JSON');
+  if (typeof themeJson.name !== 'string' || themeJson.name.length === 0)
+    fail('theme JSON must contain a non-empty top-level "name" field');
+
+  // Resolve the canonical registered file name. Default to the basename
+  // of the input file so paths in report.json stay stable across reruns.
+  const registeredName = args.name || path.basename(themeFile);
+  if (!/\.json$/i.test(registeredName))
+    fail(`registered name must end with .json (got: ${registeredName})`);
+  // Reject path separators to avoid accidental writes outside the
+  // StaticResources/RegisteredResources/ directory via --name.
+  if (/[/\\]/.test(registeredName))
+    fail(`registered name must not contain path separators (got: ${registeredName})`);
+
+  // Copy the theme into StaticResources/RegisteredResources/.
+  const registeredDir = path.join(reportPath, 'StaticResources', 'RegisteredResources');
+  fs.mkdirSync(registeredDir, { recursive: true });
+  const registeredFile = path.join(registeredDir, registeredName);
+  fs.copyFileSync(themeFile, registeredFile);
+
+  // Determine reportVersionAtImport for customTheme. We mirror the
+  // baseTheme value so the version stamp matches the schema the report
+  // is currently running. This is what Desktop expects (verified against
+  // K201-MonthSlicer.Report).
+  const baseVersion =
+    reportJson &&
+    reportJson.themeCollection &&
+    reportJson.themeCollection.baseTheme &&
+    reportJson.themeCollection.baseTheme.reportVersionAtImport;
+
+  if (
+    !baseVersion ||
+    typeof baseVersion.visual !== 'string' ||
+    typeof baseVersion.report !== 'string' ||
+    typeof baseVersion.page !== 'string'
+  ) {
+    fail(
+      'report.json themeCollection.baseTheme.reportVersionAtImport is missing or malformed; ' +
+        'cannot derive customTheme version. Open the .pbip in Desktop once to let it write a clean baseTheme block, then retry.'
+    );
+  }
+
+  // 1) Patch themeCollection.customTheme
+  reportJson.themeCollection = reportJson.themeCollection || {};
+  reportJson.themeCollection.customTheme = {
+    name: registeredName,
+    reportVersionAtImport: {
+      visual: baseVersion.visual,
+      report: baseVersion.report,
+      page: baseVersion.page,
+    },
+    type: 'RegisteredResources',
+  };
+
+  // 2) Patch resourcePackages — find or create the RegisteredResources package.
+  reportJson.resourcePackages = Array.isArray(reportJson.resourcePackages)
+    ? reportJson.resourcePackages
+    : [];
+  let registered = reportJson.resourcePackages.find(
+    (p) => p && p.name === 'RegisteredResources' && p.type === 'RegisteredResources'
+  );
+  if (!registered) {
+    registered = { name: 'RegisteredResources', type: 'RegisteredResources', items: [] };
+    reportJson.resourcePackages.push(registered);
+  }
+  registered.items = Array.isArray(registered.items) ? registered.items : [];
+
+  // Replace (or insert) the CustomTheme item for this registered file.
+  // Drop any other CustomTheme items to keep a single active custom theme,
+  // matching how Desktop handles it through the UI.
+  const otherItems = registered.items.filter(
+    (item) => !item || item.type !== 'CustomTheme'
+  );
+  registered.items = [
+    ...otherItems,
+    {
+      name: registeredName,
+      path: registeredName,
+      type: 'CustomTheme',
+    },
+  ];
+
+  // 3) Write report.json atomically.
+  writeJsonAtomic(reportJsonPath, reportJson);
+
+  process.stdout.write(
+    [
+      'apply-theme: ✓ custom theme registered',
+      `  theme file:   ${themeFile}`,
+      `  copied to:    ${registeredFile}`,
+      `  report.json:  ${reportJsonPath}`,
+      `  customTheme:  ${registeredName} (type: RegisteredResources)`,
+      `  versions:     visual ${baseVersion.visual} / report ${baseVersion.report} / page ${baseVersion.page}`,
+      '',
+      'Next:',
+      '  1. pbi report -p "<reportPath>" validate',
+      '  2. close PBI Desktop fully (taskkill /IM PBIDesktop.exe /F),',
+      '  3. relaunch the .pbip via the standalone exe (see references/pbi-desktop-installation.md).',
+      '',
+    ].join('\n')
+  );
+}
+
+main();