salesforce-reports-mcp 0.0.0-stage → 0.2.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "salesforce-reports",
+  "owner": { "name": "nelsben" },
+  "description": "Salesforce reports for Claude.",
+  "plugins": [
+    {
+      "name": "salesforce-reports",
+      "source": "./",
+      "description": "Explore, design and deploy Salesforce reports with Claude.",
+      "category": "productivity"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "salesforce-reports",
+  "version": "0.2.0",
+  "description": "Explore, design and deploy Salesforce reports with Claude: three skills and an MCP server over the Reports and Dashboards REST API.",
+  "author": { "name": "nelsben" },
+  "homepage": "https://github.com/nelsben/salesforce-reports-mcp",
+  "repository": "https://github.com/nelsben/salesforce-reports-mcp",
+  "license": "MIT",
+  "keywords": ["salesforce", "reports", "mcp", "analytics"],
+  "skills": "./skills",
+  "mcpServers": {
+    "salesforce-reports": {
+      "command": "npx",
+      "args": ["-y", "salesforce-reports-mcp"]
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nelsben
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# salesforce-reports-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Claude finds, builds, runs and saves Salesforce reports. You ask a question in plain words and get the answer, with the report behind it.
+
+This repo is working software, and a demonstration. It takes one useful job, reports, and delivers it to Claude three ways, from a server on your laptop to a feature that lives inside Salesforce. Every design choice is written down with what it costs. Built by [Ben Nelsen](https://github.com/nelsben).
+
+> **You:** List the report types I can build on, then build me an opportunity report grouped by stage without saving it.
+>
+> **Claude:** The org has 156 report types; here they are by category. Opportunities by stage: 8 open deals, $3,091,000. Negotiation/Review holds 3 of them and 39% of the value. Salesforce applied its default filters: close date this fiscal quarter, probability above 0. Nothing was saved. Want it across all close dates, or saved to your Private Reports?
+>
+> *claude.ai, through the MCP server hosted by Salesforce, signed in as the user ([rehearsal](docs/rehearsals/runner-hosted.md)).*
+
+## What this repo shows
+
+| Claim | Where to look | Evidence you can check |
+| --- | --- | --- |
+| **1. Three ways to connect Salesforce and Claude**, each with its own trade-offs | [Three ways to connect](#three-ways-to-connect) | One tool contract and result shape on every door (12 tools locally, 11 in the org); a [parity check](docs/decisions/0010-verification-by-parity.md) runs the same calls through two doors against a real org and compares them |
+| **2. A useful feature added to Salesforce itself**, packaged the way an admin expects | [A feature inside Salesforce](#a-feature-inside-salesforce) | Three package directories; layered Apex with a CI test that fails if the layers leak; 65 Apex tests at 98% coverage |
+| **3. Security, authentication and integration** done deliberately, per door | [Security and identity](#security-and-identity) | A different identity per door, a per-user JWT named credential with no stored secret, writes behind a custom permission, and a test that keeps org values out of the repo |
+| **4. Product and architecture judgment**, shown in the work | [How it was built](#how-it-was-built) | Personas and [experiences](docs/experiences.md), [6 probes](docs/probes/) before building, [14 decision records](docs/decisions/README.md), [live findings](docs/design.md), [7 rehearsals](docs/rehearsals/README.md) |
+
+## The product
+
+**The problem.** Reports are how a Salesforce org answers questions, and they are hard to use. A seller wants a number, not Report Builder. An analyst wants to try three versions of a report before saving one. An admin wants a report in another org or in git. As of October 2026, Salesforce's own Claude skills and its standard hosted MCP servers had no report tools, and the closest open-source servers could run or create a report, but none could change, clone or combine one, or run one that was never saved.
+
+**Three experiences.** Each is a Claude skill, and Claude picks the right one from what you say.
+
+| Skill | For | What Claude does |
+| --- | --- | --- |
+| [report-runner](skills/report-runner/SKILL.md) | A seller or manager who wants an answer | Finds the report, says in plain words what it counts, runs it, leads with the answer, offers the next slice. Never saves. |
+| [report-designer](skills/report-designer/SKILL.md) | Someone who wants a report changed or made | Drafts the report in your words, previews it on real data, changes it until you like it, saves it in one step when you ask. |
+| [report-deploy](skills/report-deploy/SKILL.md) | An admin moving a report between orgs or into git | Retrieves the report's metadata, checks it with a dry run, deploys only after you say yes. |
+
+> **You:** Start from my Pipeline by Stage report. Add Next Step and group it by owner, then save it as Pipeline by Owner.
+>
+> **Claude:** Preview, with 8 deals under two owners. Saved as a new report in your Private Reports; the original is untouched. Link.
+
+**Answers you can trust.** Every run returns the same compact shape: the filters that were applied, including the ones Salesforce adds on its own, the groups and totals, and notes that say when rows were cut or Salesforce ignored part of the request. The [experiences page](docs/experiences.md) has the personas and the facts that shaped them.
+
+**A report card in the chat.** In Claude Desktop, a report run on the local server also draws as a card the way Salesforce draws it: the title, the filters, the groups with totals, a link to open it in Salesforce and, for an unsaved report, a button that asks Claude to save it. It is an MCP App that loads nothing from the network. Clients that show only text, such as Claude Code, get the same result as text ([decision 0013](docs/decisions/0013-report-view-as-an-mcp-app.md)).
+
+![The report card for an unsaved opportunity report grouped by stage, drawn in light, then dark, then at phone width](docs/assets/report-view.gif)
+
+*Drawn by the [render test](docs/decisions/0014-render-tests-through-a-test-host.md)'s host page from anonymised test data.*
+
+## Three ways to connect
+
+The same tools reach Claude three ways. They differ in where the code runs, who hosts it and how the user signs in.
+
+```mermaid
+flowchart LR
+  subgraph Laptop["Your machine"]
+    CC["Claude Code / Desktop"]
+    LS["Local MCP server<br/>(Node)"]
+    CLI["sf CLI"]
+  end
+  subgraph Cloud["claude.ai"]
+    CAI["Claude"]
+  end
+  subgraph SF["Salesforce org"]
+    GW["Hosted MCP<br/>(Salesforce gateway)"]
+    REST["ReportsApi<br/>(Apex REST)"]
+    CORE["Reports service<br/>(Apex)"]
+    API["Reports REST API"]
+  end
+  CC -- "1. stdio" --> LS -- "REST" --> API
+  CC -- "2. skills + CLI" --> CLI -- "Apex REST" --> REST
+  CAI -- "3. MCP over OAuth" --> GW --> REST
+  REST --> CORE --> API
+```
+
+| | 1. Local MCP server | 2. In-org REST door with skills | 3. Hosted MCP door |
+| --- | --- | --- | --- |
+| **Direction** | Claude reaches into Salesforce | Salesforce offers a feature; Claude calls it | Salesforce serves Claude directly |
+| **Runs** | Node on your machine | Apex in the org | Salesforce's MCP gateway, then the same Apex |
+| **Installed in the org** | Nothing | `force-app` | `force-app`, `mcp-app`, optionally `callout-app` |
+| **Signs in with** | Your `sf` CLI session or a token | Your own Salesforce session | OAuth with PKCE through an External Client App |
+| **Clients** | Claude Code, Claude Desktop, any MCP client | Claude Code and any agent with a shell; Flow, Agentforce, any HTTP client | claude.ai and any remote MCP client, with nothing to host |
+| **Tools** | All 12, delete only with a flag | 11, no delete | 11, no delete |
+| **Choose it when** | One person, no org change allowed | An admin wants the feature in the org, used from scripts and agents | A team wants Claude in the browser, governed by the org |
+
+Each door gets the same tool names, the same input and the same result ([decision 0001](docs/decisions/0001-one-contract-three-doors.md)). The skills bind to tool names, not to a door, so one skill works over all three. [docs/architecture.md](docs/architecture.md) has the sequence diagrams.
+
+## A feature inside Salesforce
+
+The in-org doors are a Salesforce feature an admin installs, not a script. They ship as three package directories in [salesforce/](salesforce/README.md) ([decision 0009](docs/decisions/0009-two-shipping-units.md)):
+
+| Package | Holds | Needs |
+| --- | --- | --- |
+| `force-app` | The Apex service, its tests, two permission sets and a custom permission | Nothing else; complete on its own |
+| `mcp-app` | The API Catalog entry, the MCP server definition and the External Client App Claude signs in through. No code. | `force-app` |
+| `callout-app` | The per-user named credential that lets the hosted door call the org's own API as the user. No code. | `force-app`; used by the hosted door |
+
+The Apex is layered as ports and adapters ([decision 0003](docs/decisions/0003-one-apex-class-behind-both-in-org-doors.md)). One service does the work; the REST class is only an adapter, and [a test](test/apex-layers.test.ts) fails CI if the core ever names it or sets an HTTP status. Reads use `Reports.ReportManager` inside the org; only what Apex cannot do (list report types, run an unsaved report, save) calls the org's own REST API ([decision 0004](docs/decisions/0004-reportmanager-first-callout-for-the-rest.md)). There is no delete in the org ([decision 0006](docs/decisions/0006-no-delete-in-the-org.md)).
+
+## Security and identity
+
+Each door signs in differently, and each is least privilege by default.
+
+| Door | Identity | What it can do |
+| --- | --- | --- |
+| Local | The user's `sf` CLI session, refetched on expiry; never written anywhere | Whatever the user can do. `--read-only` removes every write tool; `delete_report` exists only with `--allow-delete`. |
+| REST | The caller's own Salesforce session | Reads with `Salesforce_Reports`. Saves only with `Salesforce_Reports_Write`, checked in the service, not by hiding tools ([decision 0005](docs/decisions/0005-saves-behind-a-custom-permission.md)). |
+| Hosted MCP | OAuth with PKCE through the External Client App `SalesforceReportsMcp`, scopes `mcp_api` and `refresh_token` only | The same permission sets. For the calls that need the org's REST API, a per-user JWT named credential mints a token for the signed-in user. |
+
+Sharing, folder access and field-level security apply on every door, because every call runs as the user.
+
+**The hard part, and how it was solved.** Under a hosted MCP sign-in, Apex has no session, and asking for one throws an exception no `catch` block can stop. The first version leaked a raw platform error to claude.ai. The fix came in two steps, each with a decision record:
+
+1. The hosted door got its own route, so the code knows which door called before it asks for a session, and answers a clear `CALLOUT_SESSION` instead ([decision 0007](docs/decisions/0007-callout-identity-under-hosted-mcp.md)).
+2. A probe showed that a [per-user JWT named credential](docs/probes/v0.2-phase3c.md) lets the org mint a token for the running user from a certificate it made itself. No secret is stored, no user clicks anything, and the connector's own app keeps its narrow scopes ([decision 0012](docs/decisions/0012-per-user-jwt-named-credential.md)). `npm run callout:renew` renews the certificate.
+
+No token, consumer key, org address or certificate reaches the repo, logs or error messages. The tracked metadata holds placeholders that setup scripts fill at deploy time, and a test enforces it.
+
+## How it was built
+
+The method was the same for every feature: probe the platform, decide in writing, build, then check against a real org.
+
+| Step | What it produced |
+| --- | --- |
+| **Probe** before building | [6 probe write-ups](docs/probes/): can a hosted MCP server wrap Apex, can Apex call its own org's API, how big a result fits in the heap, which identity works under a hosted sign-in |
+| **Decide** in writing | [14 decision records](docs/decisions/README.md), each with what it costs and what was turned down |
+| **Build** to one contract | [design.md](docs/design.md): the input and output shapes, and the live findings where Salesforce did not behave as documented |
+| **Verify** against a real org | 161 unit and server tests, 8 render tests that draw the report card in a browser, 65 Apex tests, a live end-to-end check that leaves no report behind, and a parity check across doors |
+| **Rehearse** the experience | [7 rehearsals](docs/rehearsals/README.md): real Claude runs of each skill on each door, with what went wrong and what changed |
+
+## Get started
+
+| You want | Start here |
+| --- | --- |
+| Claude Code or Desktop on your own org, nothing installed in Salesforce | [Local MCP server](docs/install.md#the-local-mcp-server) |
+| The feature inside your org, called from the CLI, scripts or agents | [The REST door](docs/install.md#the-rest-door) |
+| Claude in the browser, signed in through Salesforce | [The MCP door](docs/install.md#the-mcp-door), then [the callout tools](docs/install.md#the-callout-tools-on-the-mcp-door) |
+
+The quickest try is the Claude Code plugin, which bundles the skills and the local server:
+
+```
+claude plugin marketplace add nelsben/salesforce-reports-mcp
+claude plugin install salesforce-reports@salesforce-reports
+```
+
+The tools, the result shape, the safety rails and the limits are in [docs/reference.md](docs/reference.md).
+
+## Develop
+
+```
+npm install
+npm run build
+npm test
+npm run test:render                            # draw the report card in Chromium and compare screenshots
+npm run live -- --org <alias> --allow-delete   # end-to-end run against an org you can write to
+npm run capture -- --org <alias>               # refresh the test fixtures (anonymised)
+```
+
+`npm run live` creates several private reports named `zz-live-check-*`, deletes them, and fails if any remain. Use a sandbox or scratch org.
+
+## Roadmap
+
+- Dashboards: list, describe, refresh, and read component data.
+- Joined reports, report charts, and subscriptions.
+
+## License
+
+MIT.

package/dist/format.js

@@ -0,0 +1,49 @@
+import { CombineError } from "./reports/combine.js";
+import { ConnectionError } from "./salesforce/connection.js";
+import { SalesforceError } from "./salesforce/client.js";
+export function ok(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+/**
+ * ok() for a tool that carries the report view: the same text result, plus the value as
+ * structuredContent for a host that draws MCP Apps. Hosts without UI read the text, as before.
+ */
+export function okView(value) {
+    return { ...ok(value), structuredContent: value };
+}
+export function fail(error) {
+    const body = describeError(error);
+    return { isError: true, content: [{ type: "text", text: JSON.stringify({ error: body }) }] };
+}
+function describeError(error) {
+    if (error instanceof SalesforceError) {
+        return { code: error.code, message: error.message, hint: hintFor(error) };
+    }
+    if (error instanceof ConnectionError) {
+        return { code: "CONNECTION", message: error.message, hint: "Check the --org alias, or log in with `sf org login web`." };
+    }
+    if (error instanceof CombineError || error instanceof InputError) {
+        return { code: "INVALID_INPUT", message: error.message };
+    }
+    return { code: "UNEXPECTED", message: error instanceof Error ? error.message : "Unexpected error." };
+}
+function hintFor(error) {
+    const text = `${error.code} ${error.message}`;
+    if (error.status === 401)
+        return "Log in again with `sf org login web`, or pass a fresh token.";
+    if (error.status === 404 || /NOT_FOUND|INVALID_ID/i.test(error.code)) {
+        return "Check the id with search_reports (reports) or list_report_types (report types).";
+    }
+    if (/column|field|grouping|aggregate|filter|operator/i.test(text)) {
+        return "Check column API names, filter operators and aggregates with describe_report_type, or the report's own columns with describe_report.";
+    }
+    if (/REQUEST_LIMIT_EXCEEDED|limit/i.test(text)) {
+        return "Salesforce allows 500 synchronous report runs per org per hour. Wait, or reduce the number of runs.";
+    }
+    if (/INSUFFICIENT_ACCESS|FORBIDDEN|permission/i.test(text)) {
+        return "The authenticated user lacks access. They need the Run Reports permission, and for saving, Create and Customize Reports.";
+    }
+    return undefined;
+}
+export class InputError extends Error {
+}

package/dist/index.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { parseArgs } from "node:util";
+import { ReportsApi } from "./reports/api.js";
+import { createClient, DEFAULT_API_VERSION } from "./salesforce/client.js";
+import { resolveConnection } from "./salesforce/connection.js";
+import { buildServer } from "./server.js";
+const HELP = `salesforce-reports-mcp: an MCP server for Salesforce reports (stdio)
+
+Usage: salesforce-reports-mcp [--org <alias>] [options]
+
+  --org <alias>        Authenticate through the Salesforce CLI (env SF_ORG). Default: the sf default org.
+                       Or set SF_INSTANCE_URL and SF_ACCESS_TOKEN to use a token you already hold.
+  --api-version <v>    REST API version (env SF_API_VERSION). Default ${DEFAULT_API_VERSION}.
+  --read-only          Register no write tools (env SF_REPORTS_READ_ONLY=1).
+  --allow-delete       Register delete_report (env SF_REPORTS_ALLOW_DELETE=1).
+  --max-rows <n>       Default cap on detail rows per result (env SF_REPORTS_MAX_ROWS). Default 200, ceiling 2000.
+  -h, --help           Show this help.
+`;
+function flag(value, envName) {
+    return value ?? ["1", "true"].includes((process.env[envName] ?? "").toLowerCase());
+}
+async function main() {
+    const { values } = parseArgs({
+        options: {
+            org: { type: "string" },
+            "api-version": { type: "string" },
+            "read-only": { type: "boolean" },
+            "allow-delete": { type: "boolean" },
+            "max-rows": { type: "string" },
+            help: { type: "boolean", short: "h" },
+        },
+        strict: true,
+    });
+    if (values.help) {
+        process.stderr.write(HELP);
+        return;
+    }
+    const maxRowsRaw = values["max-rows"] ?? process.env.SF_REPORTS_MAX_ROWS;
+    const maxRows = maxRowsRaw ? Number.parseInt(maxRowsRaw, 10) : 200;
+    if (!Number.isInteger(maxRows) || maxRows < 1 || maxRows > 2000) {
+        throw new Error("--max-rows must be a whole number from 1 to 2000.");
+    }
+    const connection = resolveConnection({ org: values.org });
+    const client = createClient(connection, { apiVersion: values["api-version"] ?? process.env.SF_API_VERSION });
+    const server = buildServer(new ReportsApi(client), {
+        readOnly: flag(values["read-only"], "SF_REPORTS_READ_ONLY"),
+        allowDelete: flag(values["allow-delete"], "SF_REPORTS_ALLOW_DELETE"),
+        maxRows,
+    });
+    await server.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+    process.stderr.write(`salesforce-reports-mcp: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/dist/reports/api.js

@@ -0,0 +1,86 @@
+import { SalesforceError } from "../salesforce/client.js";
+const enc = encodeURIComponent;
+export function soqlString(value) {
+    return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+/** For a `LIKE` clause: escape the quote and backslash, and the two wildcards. */
+export function soqlLike(value) {
+    return soqlString(value).replace(/([%_])/g, "\\$1");
+}
+export class ReportsApi {
+    api;
+    sleep;
+    constructor(api, sleep = (ms) => new Promise((r) => setTimeout(r, ms))) {
+        this.api = api;
+        this.sleep = sleep;
+    }
+    instanceUrl() {
+        return this.api.instanceUrl();
+    }
+    reportTypes() {
+        return this.api.request("GET", "/analytics/reportTypes");
+    }
+    describeReportType(type) {
+        return this.api.request("GET", `/analytics/reportTypes/${enc(type)}`);
+    }
+    describeReport(id) {
+        return this.api.request("GET", `/analytics/reports/${enc(id)}/describe`);
+    }
+    async run(id, options) {
+        const path = `/analytics/reports/${enc(id)}?includeDetails=${options.includeDetails}`;
+        try {
+            const raw = options.overrides
+                ? await this.api.request("POST", path, { reportMetadata: options.overrides })
+                : await this.api.request("GET", path);
+            return { raw, async: false };
+        }
+        catch (error) {
+            if (!isTimeout(error))
+                throw error;
+            return { raw: await this.runAsync(id, options.overrides), async: true };
+        }
+    }
+    query(metadata, includeDetails) {
+        return this.api.request("POST", `/analytics/reports/query?includeDetails=${includeDetails}`, { reportMetadata: metadata });
+    }
+    create(metadata) {
+        return this.api.request("POST", "/analytics/reports", { reportMetadata: metadata });
+    }
+    patch(id, metadata) {
+        return this.api.request("PATCH", `/analytics/reports/${enc(id)}`, { reportMetadata: metadata });
+    }
+    clone(id, metadata) {
+        return this.api.request("POST", `/analytics/reports?cloneId=${enc(id)}`, { reportMetadata: metadata });
+    }
+    async remove(id) {
+        await this.api.request("DELETE", `/analytics/reports/${enc(id)}`);
+    }
+    async soql(query) {
+        const out = await this.api.request("GET", `/query?q=${enc(query)}`);
+        return out.records;
+    }
+    async runAsync(id, overrides) {
+        const started = await this.api.request("POST", `/analytics/reports/${enc(id)}/instances?includeDetails=true`, overrides ? { reportMetadata: overrides } : undefined);
+        const instanceId = started.id ?? started.attributes?.id;
+        if (!instanceId)
+            throw new SalesforceError(500, "NO_INSTANCE", "Salesforce did not return an async report instance.");
+        for (let attempt = 0; attempt < 30; attempt++) {
+            await this.sleep(Math.min(1000 + attempt * 500, 4000));
+            const instance = await this.api.request("GET", `/analytics/reports/${enc(id)}/instances/${enc(instanceId)}`);
+            const status = instance.attributes?.status ?? instance.status;
+            if (status === "Success")
+                return instance;
+            if (status === "Error")
+                throw new SalesforceError(500, "REPORT_RUN_FAILED", "The async report run failed in Salesforce.");
+        }
+        throw new SalesforceError(504, "REPORT_RUN_PENDING", `The async report run (${instanceId}) did not finish in time. Try again, or narrow the filters.`);
+    }
+}
+function isTimeout(error) {
+    if (!(error instanceof SalesforceError))
+        return false;
+    return (error.status === 408 ||
+        error.status === 504 ||
+        /TIMEOUT|TOO_LONG|ASYNC/i.test(error.code) ||
+        /timed out|time out|asynchronous/i.test(error.message));
+}

package/dist/reports/combine.js

@@ -0,0 +1,116 @@
+export class CombineError extends Error {
+}
+export function combineResults(mode, inputs, options = {}) {
+    if (inputs.length < 2 || inputs.length > 5)
+        throw new CombineError("combine_reports takes 2 to 5 inputs.");
+    const aliases = inputs.map((i) => i.alias);
+    if (new Set(aliases).size !== aliases.length)
+        throw new CombineError("Each input needs its own alias.");
+    const base = {
+        report: {
+            id: null,
+            name: `combined: ${aliases.join(", ")}`,
+            format: mode === "join" ? "SUMMARY" : "TABULAR",
+            reportType: "combined",
+        },
+        filters: inputs.flatMap((i) => i.result.filters.map((f) => `${i.alias}: ${f}`)),
+        notes: inputs.flatMap((i) => i.result.notes.map((n) => `${i.alias}: ${n}`)),
+    };
+    const body = mode === "join" ? join(inputs, options.joinOn) : stack(inputs);
+    return { ...base, ...body };
+}
+function stack(inputs) {
+    if (inputs.every((i) => i.result.groups)) {
+        const dims = unionBy(inputs.flatMap((i) => i.result.groups.dimensions), (d) => d.name);
+        const measures = unionBy(inputs.flatMap((i) => i.result.groups.measures), (m) => m.name);
+        const rows = [];
+        for (const { alias, result } of inputs) {
+            const g = result.groups;
+            const dimIdx = g.dimensions.map((d) => d.name);
+            const measureIdx = g.measures.map((m) => m.name);
+            for (const row of g.rows) {
+                rows.push([
+                    alias,
+                    ...dims.map((d) => pick(row, dimIdx.indexOf(d.name))),
+                    ...measures.map((m) => pick(row, measureIdx.indexOf(m.name) < 0 ? -1 : dimIdx.length + measureIdx.indexOf(m.name))),
+                ]);
+            }
+        }
+        return { groups: { dimensions: [{ name: "source", label: "Source", axis: "down" }, ...dims], measures, rows } };
+    }
+    if (inputs.every((i) => i.result.detail)) {
+        const columns = unionBy(inputs.flatMap((i) => i.result.detail.columns), (c) => c.name);
+        const rows = [];
+        for (const { alias, result } of inputs) {
+            const d = result.detail;
+            const idx = d.columns.map((c) => c.name);
+            for (const row of d.rows)
+                rows.push([alias, ...columns.map((c) => pick(row, idx.indexOf(c.name)))]);
+        }
+        const all = [{ name: "source", label: "Source", dataType: "string" }, ...columns];
+        return { detail: { columns: all, rows, rowCount: rows.length, truncated: inputs.some((i) => i.result.detail.truncated) } };
+    }
+    throw new CombineError("To stack, every input must return grouped rows, or every input must return detail rows. Group all of them the same way, or run all of them with detail.");
+}
+function join(inputs, joinOn) {
+    const plans = inputs.map(({ alias, result }) => {
+        const g = result.groups;
+        if (!g)
+            throw new CombineError(`Input "${alias}" has no groupings. Join needs grouped reports; use stack for flat tables.`);
+        const downs = g.dimensions.filter((d) => d.axis === "down");
+        const keys = joinOn ?? (downs[0] ? [downs[0].name] : []);
+        if (!keys.length)
+            throw new CombineError(`Input "${alias}" has no down grouping to join on.`);
+        const idx = keys.map((k) => g.dimensions.findIndex((d) => d.name === k));
+        const missing = keys.filter((_, n) => idx[n] < 0);
+        if (missing.length) {
+            throw new CombineError(`Input "${alias}" is not grouped by ${missing.join(", ")}. It has: ${g.dimensions.map((d) => d.name).join(", ")}.`);
+        }
+        if (g.dimensions.length > keys.length) {
+            throw new CombineError(`Input "${alias}" is grouped by more than the join key (${g.dimensions.map((d) => d.name).join(", ")}). Set joinOn to all of its groupings, or remove the extra groupings.`);
+        }
+        return { alias, g, idx };
+    });
+    const first = plans[0];
+    const keyDims = first.idx.map((i) => ({ ...first.g.dimensions[i], axis: "down" }));
+    const measures = plans.flatMap((p) => p.g.measures.map((m) => ({ name: `${p.alias}:${m.name}`, label: `${p.alias}: ${m.label}`, dataType: m.dataType })));
+    const table = new Map();
+    for (const p of plans) {
+        for (const row of p.g.rows) {
+            const labels = p.idx.map((i) => row[i] ?? null);
+            const key = labels.map((l) => String(l ?? "").trim().toLowerCase()).join("\u0000");
+            let entry = table.get(key);
+            if (!entry) {
+                entry = { labels, values: new Map() };
+                table.set(key, entry);
+            }
+            entry.values.set(p.alias, row.slice(p.g.dimensions.length));
+        }
+    }
+    const rows = [];
+    for (const entry of table.values()) {
+        const out = [...entry.labels];
+        for (const p of plans) {
+            const values = entry.values.get(p.alias);
+            for (let m = 0; m < p.g.measures.length; m++)
+                out.push(values?.[m] ?? null);
+        }
+        rows.push(out);
+    }
+    return { groups: { dimensions: keyDims, measures, rows } };
+}
+function pick(row, index) {
+    return index < 0 ? null : (row[index] ?? null);
+}
+function unionBy(items, key) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        const k = key(item);
+        if (!seen.has(k)) {
+            seen.add(k);
+            out.push(item);
+        }
+    }
+    return out;
+}