# pi-powerbi-desktop

CLI-first Power BI Desktop Bridge integration and native Pi extension. It uses Power BI
Desktop's secure local bridge API; it does not invoke Microsoft's CLI.

## Requirements

- Windows 10/11 with Power BI Desktop open.
- Power BI Desktop preview feature **Enable external tool access to Power BI Desktop
  through secure local APIs** enabled.
- Node.js 20 or newer.
- For Pi in WSL2, Windows interop and `powershell.exe` must be available. The package
  starts its included PowerShell broker; Node.js on Windows is not required.

Power BI Desktop must be running locally. This package does not provide remote access.
PBIX page discovery is best effort: it reads only `Report/Layout`; PBIP/PBIR uses the
stable `definition/pages` files. A PBIX that cannot be inspected can still be captured
when an explicit page ID is supplied.

## Install

```bash
pi install npm:pi-powerbi-desktop
```

Try it for one Pi invocation:

```bash
pi -e npm:pi-powerbi-desktop
```

The package is CLI-first and is not published by this repository's development scripts.
Build the local package with `npm run build`; `npm pack --dry-run` is the packaging check.

## Pi tools

The package registers exactly two tools:

### `powerbi_list`

No parameters. Lists connected reports, process IDs, report paths, bridge status, and
pages. An unreadable report produces a warning on that report rather than aborting the
whole list.

### `powerbi_screenshot`

Parameters:

| Parameter | Meaning |
| --- | --- |
| `report` | PID, exact path, filename, or report name. Optional only when unambiguous. |
| `page` | Visible page name or internal page ID for one-page capture. |
| `all` | Capture every detected page; defaults to `false`. |
| `scale` | Render scale from 1 through 3; defaults to `2`. |
| `output` | File for one page, directory when `all` is true. |
| `waitSeconds` | Capture timeout from 1 through 300 seconds; defaults to `60`. |

`all: true` rejects `page` and returns paths and metadata only. A single-page capture
returns its saved path and one inline PNG image for model review. Captures belonging to
the same report are sequential.

Examples of prompts:

- “List the open Power BI reports.”
- “Capture the Overview page from the Sales report.”
- “Capture all pages from Sales into `./screenshots`.”

## CLI

The same core is available through the diagnostic CLI:

```bash
pi-powerbi list
pi-powerbi screenshot --report "Sales" --page "Overview"
pi-powerbi screenshot --report "Sales" --all --output ./screenshots
```

The published executable is `dist/cli.js`; TypeScript source is built before packing.

## Core integration contract

The Pi and CLI layers import only the following narrow API from `src/core/index.ts`:

```ts
export function listReports(options?: {
  signal?: AbortSignal;
}): Promise<{ reports: PowerBiReport[]; warnings?: string[] }>;

export function captureScreenshots(
  request: {
    report?: string;
    page?: string;
    all: boolean;
    scale: number;
    output?: string;
    waitSeconds: number;
  },
  options: { cwd: string; signal?: AbortSignal },
): Promise<
  | {
      kind: "single";
      path: string;
      metadata: Record<string, unknown>;
      imageBase64: string;
      mediaType: "image/png" | "image/jpeg" | "image/webp";
    }
  | {
      kind: "all";
      screenshots: Array<{ path: string; metadata: Record<string, unknown> }>;
      report?: string;
      warnings?: string[];
    }
>;
```

The coordinator's core implementation should export those functions from
`src/core/index.ts` and include `src/platform/bridge-host.ps1`. `prepack` copies that
broker to `dist/platform/bridge-host.ps1` alongside the compiled runtime.

## Development

```bash
npm ci
npm run check          # formatting, typecheck, and extension tests
npm run build          # emits dist/ and copies the broker
npm run verify:package # checks build files and npm pack contents without publishing
```

CI runs the checks on Ubuntu and Windows. No publish workflow or publish command is
provided. The MIT license is in [LICENSE](./LICENSE).