Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ jobs:
run: npm run size -w pivotkit-xlsx

platforms:
# pivotkit-cli and pivotkit-server on Windows and macOS; the other jobs run on Linux. Windows:
# pivotkit-node, pivotkit-cli and pivotkit-server on Windows and macOS; the other jobs run on Linux. Windows:
# drive letters, junctions (reparse points), no O_NOFOLLOW, no POSIX modes. macOS: its own file
# system and signals. The server's tests cover the workers, the output directory, download
# markers (hard links), listen, the state directory, sign-in and the secret files. On Windows,
Expand All @@ -113,6 +113,8 @@ jobs:
run: npm ci --no-audit --no-fund --ignore-scripts
- name: Build
run: npm run build
- name: pivotkit-node tests
run: npm test -w pivotkit-node
- name: pivotkit-cli tests
run: npm test -w pivotkit-cli
- name: pivotkit-server tests
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ jobs:
REPO: ${{ github.server_url }}/${{ github.repository }}
run: |
if [ "$TAG" = main ]; then exit 0; fi
if ! [[ "$TAG" =~ ^pivotkit-(core|react|element|xlsx|report|cli|server|mcp)@[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
if ! [[ "$TAG" =~ ^pivotkit-(core|react|element|xlsx|report|node|cli|server|mcp)@[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo "::error::tag must be a release tag such as pivotkit-react@0.2.0, or main"; exit 1
fi
git ls-remote --exit-code --tags "$REPO" "refs/tags/$TAG" > /dev/null || { echo "::error::no tag $TAG"; exit 1; }
Expand Down
6 changes: 3 additions & 3 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
name: Release

# Stages a package of this repository (pivotkit-core, pivotkit-react, pivotkit-element,
# pivotkit-xlsx, pivotkit-report, pivotkit-cli, pivotkit-server or pivotkit-mcp) on npm with
# pivotkit-xlsx, pivotkit-report, pivotkit-node, pivotkit-cli, pivotkit-server or pivotkit-mcp) on npm with
# provenance when a tag <package>@<version> is pushed; a maintainer approves the staged version on
# npm with two-factor authentication before it is published. It needs trusted publishing on npm for
# this workflow and the environment "npm" (staging only), the GitHub environment "npm" with required
Expand All @@ -16,7 +16,7 @@ name: Release
# integrity the Pack step recorded.
on:
push:
tags: ["pivotkit-core@*", "pivotkit-react@*", "pivotkit-element@*", "pivotkit-xlsx@*", "pivotkit-report@*", "pivotkit-cli@*", "pivotkit-server@*", "pivotkit-mcp@*"]
tags: ["pivotkit-core@*", "pivotkit-react@*", "pivotkit-element@*", "pivotkit-xlsx@*", "pivotkit-report@*", "pivotkit-node@*", "pivotkit-cli@*", "pivotkit-server@*", "pivotkit-mcp@*"]

permissions:
contents: read
Expand Down Expand Up @@ -53,7 +53,7 @@ jobs:
run: |
name="${TAG%@*}"
case "$name" in
pivotkit-core|pivotkit-react|pivotkit-element|pivotkit-xlsx|pivotkit-report|pivotkit-cli|pivotkit-server|pivotkit-mcp) ;;
pivotkit-core|pivotkit-react|pivotkit-element|pivotkit-xlsx|pivotkit-report|pivotkit-node|pivotkit-cli|pivotkit-server|pivotkit-mcp) ;;
*) echo "tag $TAG names no package of this repository"; exit 1 ;;
esac
version="$(node -p "require('./packages/$name/package.json').version")"
Expand Down
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,8 @@ For agents and the maintainer. See also [PRODUCT.md](PRODUCT.md#what-a-contribut
- [packages/pivotkit-element/AGENTS.md](packages/pivotkit-element/AGENTS.md) - shadow root, bundle, size
- [packages/pivotkit-xlsx/AGENTS.md](packages/pivotkit-xlsx/AGENTS.md) - workbook reader safety
- [packages/pivotkit-report/AGENTS.md](packages/pivotkit-report/AGENTS.md) - rendering, operations table
- [packages/pivotkit-cli/AGENTS.md](packages/pivotkit-cli/AGENTS.md) - commands, files, remote mode
- [packages/pivotkit-node/AGENTS.md](packages/pivotkit-node/AGENTS.md) - files and the REST contract, shared
- [packages/pivotkit-cli/AGENTS.md](packages/pivotkit-cli/AGENTS.md) - commands, remote mode, sign-in
- [packages/pivotkit-server/AGENTS.md](packages/pivotkit-server/AGENTS.md) - options, sources, policy, REST
- [packages/pivotkit-mcp/AGENTS.md](packages/pivotkit-mcp/AGENTS.md) - MCP tools and plugin
- [tests/AGENTS.md](tests/AGENTS.md) - browser tests, temporary directories, repository checks
Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,7 @@ clients, data sources and platforms, and how each one was tested.
| [pivotkit-element](packages/pivotkit-element/) | The report builder as the web component `<pivot-report>`, with its own React. For Angular, PHP and plain HTML. | `npm install pivotkit-element` |
| [pivotkit-xlsx](packages/pivotkit-xlsx/) | A [plugin](https://pivotkit.eize.dev/reference/plugins/) that reads Excel workbooks in the browser. pivotkit-core reads CSV and JSON itself. | `npm install pivotkit-xlsx` |
| [pivotkit-report](packages/pivotkit-report/) | [Reports without a browser](https://pivotkit.eize.dev/reference/report/): JSON, CSV, XLSX, an SVG chart or printable HTML. | `npm install pivotkit-report echarts` |
| [pivotkit-node](packages/pivotkit-node/) | Internal: the file handling and REST contract that pivotkit-cli and pivotkit-server share. Not for direct use. | comes with pivotkit-cli and pivotkit-server |
| [pivotkit-cli](packages/pivotkit-cli/) | The [command line](https://pivotkit.eize.dev/reference/cli/) `pivotkit`: render, validate and describe views, also in CI. | `npm install --global pivotkit-cli` |
| [pivotkit-server](packages/pivotkit-server/) | A [REST service](https://pivotkit.eize.dev/reference/rest/) with sign-in by token or OAuth and policy profiles, over files or an operator's API ([HTTP sources](https://pivotkit.eize.dev/reference/sources/#http)). With pivotkit-mcp beside it, it serves MCP too. The [container image](https://pivotkit.eize.dev/reference/container/) holds both. | `npm install --global pivotkit-server pivotkit-mcp` |
| [pivotkit-mcp](packages/pivotkit-mcp/) | An [MCP server](https://pivotkit.eize.dev/reference/mcp/): an AI client builds reports and reads only what the policy shows. Over stdio or HTTP. | `npx -y pivotkit-mcp` |
Expand Down Expand Up @@ -192,7 +193,7 @@ Each package has releases of its own. The [GitHub releases](https://github.com/e
list them with their notes. Each package keeps a `CHANGELOG.md`:
[core](packages/pivotkit-core/CHANGELOG.md), [react](packages/pivotkit-react/CHANGELOG.md),
[element](packages/pivotkit-element/CHANGELOG.md), [xlsx](packages/pivotkit-xlsx/CHANGELOG.md),
[report](packages/pivotkit-report/CHANGELOG.md), [cli](packages/pivotkit-cli/CHANGELOG.md),
[report](packages/pivotkit-report/CHANGELOG.md), [node](packages/pivotkit-node/CHANGELOG.md), [cli](packages/pivotkit-cli/CHANGELOG.md),
[server](packages/pivotkit-server/CHANGELOG.md), [mcp](packages/pivotkit-mcp/CHANGELOG.md).
Before you update, read [Upgrading](https://pivotkit.eize.dev/getting-started/upgrading/).
[Versioning](https://pivotkit.eize.dev/versioning/) says which releases may break things.
Expand Down
18 changes: 11 additions & 7 deletions RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,16 @@ Release packages in this order. It follows their run-time dependencies.
3. `pivotkit-report` - core
4. `pivotkit-react` - core, report
5. `pivotkit-element` - bundles core, react and report as devDependencies
6. `pivotkit-cli` - core, report, xlsx
7. `pivotkit-server` - core, report, cli, xlsx
8. `pivotkit-mcp` - report, server

- pivotkit-server imports `pivotkit-report/operations` and `pivotkit-cli/files`.
Release both before it when they changed.
6. `pivotkit-node` - core, report, xlsx
7. `pivotkit-cli` - core, node, report, xlsx
8. `pivotkit-server` - core, node, report, cli, xlsx
9. `pivotkit-mcp` - report, server

- pivotkit-cli and pivotkit-server import `pivotkit-node/files` and `pivotkit-node/rest`.
Release pivotkit-node before them when it changed.
Before you release either, give its first version the [one-time setup](#one-time-setup).
- When pivotkit-node's minor moves, release pivotkit-cli and pivotkit-server in the same round.
- pivotkit-server imports `pivotkit-report/operations`. Release it before when it changed.
- Release pivotkit-mcp after pivotkit-server whenever pivotkit-server changed.
- pivotkit-server loads pivotkit-mcp by name and does not depend on it. There is no cycle.
- When pivotkit-core's minor moves, release every package that depends on it.
Expand Down Expand Up @@ -131,7 +135,7 @@ docker buildx imagetools inspect <image>:<tag> # shows the index digest

Done once. A new package needs steps 1 and 2 at its first release.
`npm view <package>` answers E404 when a package is not on npm yet.
All eight packages publish through staging: their trusted publishers have "Allow npm publish" unchecked.
All nine packages publish through staging: their trusted publishers have "Allow npm publish" unchecked.

1. Publish the first version of each package by hand, in publish order:

Expand Down
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
## Scope

The packages in this repository (`pivotkit-core`, `pivotkit-react`, `pivotkit-element`,
`pivotkit-xlsx`, `pivotkit-report`, `pivotkit-cli`, `pivotkit-server`, `pivotkit-mcp`) and the
`pivotkit-xlsx`, `pivotkit-report`, `pivotkit-node`, `pivotkit-cli`, `pivotkit-server`, `pivotkit-mcp`) and the
container image built from it. A view (report template), the data, a loaded file
(CSV, JSON, a workbook read by pivotkit-xlsx), a print template and a host's theme tokens can come
from users; anything that lets them run code, load or read something they should not (a file outside
Expand Down
2 changes: 1 addition & 1 deletion docker/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ RUN npm ci --omit=dev --ignore-scripts --no-audit --no-fund --include-workspace-
--workspace pivotkit-server --workspace pivotkit-mcp --workspace pivotkit-cli \
&& node scripts/examples.js \
&& mkdir -p /app/packages \
&& for p in core xlsx report cli server mcp; do cp -a "packages/pivotkit-$p" /app/packages/; done \
&& for p in core xlsx report node cli server mcp; do cp -a "packages/pivotkit-$p" /app/packages/; done \
&& rm -rf /app/packages/*/test /app/packages/*/bench /app/packages/*/node_modules \
&& cp -a node_modules LICENSE /app/ \
&& mkdir -p /app/examples /out \
Expand Down
2 changes: 1 addition & 1 deletion docs/embed/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: For developers and the people who run applications with pivotkit -

# Embed pivotkit

pivotkit comes as eight npm packages:
pivotkit comes as eight public npm packages:

- three to show the report
- one plugin to read Excel files
Expand Down
2 changes: 1 addition & 1 deletion docs/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ description: Common questions about pivotkit - which package to use, data size,
- Reports for programs over HTTP, or as a container: [pivotkit-server](getting-started/rest.md).
- Reports from an AI client: [pivotkit-mcp](getting-started/mcp.md).

[Embed pivotkit](embed/index.md) lists all eight packages and what a host switches on.
[Embed pivotkit](embed/index.md) lists the packages and what a host switches on.

## How many rows can it handle?

Expand Down
3 changes: 2 additions & 1 deletion docs/features.md
Original file line number Diff line number Diff line change
Expand Up @@ -354,7 +354,8 @@ the short version. The [comparison](compare.md) sets pivotkit beside other pivot
- `pivotkit-element`: `<pivot-report>` with its own React, for Angular, PHP and plain HTML. It
has attributes, properties, and `pivot-*` events with `respondWith()`.
- `pivotkit-core`: the engine, for the browser and Node.
- `pivotkit-xlsx`, `pivotkit-report`, `pivotkit-cli`, `pivotkit-server` and `pivotkit-mcp`.
- `pivotkit-xlsx`, `pivotkit-report`, `pivotkit-cli`, `pivotkit-server` and `pivotkit-mcp`,
with the internal `pivotkit-node` that the last three share.
- Programs over REST and AI clients through MCP. You set per field what a caller may see
([REST service](getting-started/rest.md), [MCP server](getting-started/mcp.md)).
- Recipes ([recipes](embed/recipes.md), [PowerShell Universal](getting-started/react.md#powershell-universal)):
Expand Down
8 changes: 4 additions & 4 deletions docs/reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -713,10 +713,10 @@ The JSON of Source data keeps all of it. The files hold wall-clock dates without
from a view or the data are cleaned of control characters and cut at 200 characters.
- **`pivotkit example`** writes its files the same way, in the current directory, after checking that
none of them is there yet. If one is, nothing is written (exit 2, `EXISTS`). `--allow-dir` holds.
- Templates and file paths come only from the person running the command. The [MCP server](mcp.md)
is built on the same file handling (`pivotkit-cli/files`: `readSafe`, `writeSafe`, `writeNew`,
`allowedDirs`, `readTable`). It takes a template only from its operator, and a path from a model
only inside the operator's allowed directories. It refuses hard links there.
- Templates and file paths come only from the person running the command. The REST service and the
[MCP server](mcp.md) use the same file handling (`pivotkit-cli/files`: `readSafe`, `writeSafe`,
`writeNew`, `allowedDirs`, `readTable`). They take a template only from their operator, and a path
from a model only inside the operator's allowed directories. They refuse hard links there.

## Completion

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ It needs Node 24 or later. It brings the official MCP TypeScript SDK
(`@modelcontextprotocol/server`), which speaks the protocol revision 2026-07-28 and the 2025
revisions. It also brings [pivotkit-server](rest.md), which holds what it shares with the REST
service: sources, policy, workers, output, sign-in. pivotkit-server brings
[pivotkit-report](report.md), pivotkit-cli's file handling, pivotkit-xlsx, ECharts 6.1.0 and jose
[pivotkit-report](report.md), pivotkit-node's file handling, pivotkit-xlsx, ECharts 6.1.0 and jose
(for OAuth). `pivotkit-server serve` runs this endpoint and the REST service on one port.

## Tools { #tools }
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/rest.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ npm install --global pivotkit-server pivotkit-mcp
PIVOTKIT_TOKEN=... pivotkit-server serve --config pivotkit.json --auth token # http://127.0.0.1:3333/api/v1
```

It needs Node 24 or later. It brings [pivotkit-report](report.md), pivotkit-cli's file handling,
It needs Node 24 or later. It brings [pivotkit-report](report.md), the command line pivotkit-cli,
pivotkit-xlsx, ECharts 6.1.0 and jose (for OAuth). It does not bring the MCP SDK.

## Routes { #routes }
Expand Down
2 changes: 2 additions & 0 deletions docs/versioning.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,8 @@ These are not public interface. They can change in any release:
- The wording of messages. Match on the code, not on the text.
- Internal modules: the ones no package exports, and the `internal` entry points that this
repository's packages share, such as `pivotkit-server/internal`.
- The package pivotkit-node. pivotkit-cli and pivotkit-server share it. Use `pivotkit-cli/files`
and `pivotkit-cli/rest`, which export its names.
- The layout of an exported workbook beyond its values.

## How a deprecation works
Expand Down
20 changes: 17 additions & 3 deletions eslint.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@ import js from "@eslint/js";
import reactHooks from "eslint-plugin-react-hooks";
import globals from "globals";

// pivotkit-server never imports its command line: shared code lives in pivotkit-node. The runner's
// `cli` command loads it by name with import(), which this rule does not see.
const NO_CLI_IN_SERVER = { regex: "^pivotkit-cli(/|$)", message: "shared code goes into pivotkit-node; pivotkit-server does not import its command line" };

export default [
{ ignores: ["**/node_modules/", "**/dist/", "**/coverage/", "packages/*/types/", "test-results/", "playwright-report/", "site/", "docs/playground/"] },
js.configs.recommended,
Expand Down Expand Up @@ -36,19 +40,29 @@ export default [
languageOptions: { globals: { ...globals["shared-node-browser"] } }
},
{
// the command line, the REST service and the MCP server run in Node only
files: ["packages/pivotkit-cli/src/**/*.js", "packages/pivotkit-cli/bin/**/*.js", "packages/pivotkit-server/src/**/*.js", "packages/pivotkit-server/bin/**/*.js", "packages/pivotkit-mcp/src/**/*.js", "packages/pivotkit-mcp/bin/**/*.js"],
// the command line, the REST service, the MCP server and what they share run in Node only
files: ["packages/pivotkit-node/src/**/*.js", "packages/pivotkit-cli/src/**/*.js", "packages/pivotkit-cli/bin/**/*.js", "packages/pivotkit-server/src/**/*.js", "packages/pivotkit-server/bin/**/*.js", "packages/pivotkit-mcp/src/**/*.js", "packages/pivotkit-mcp/bin/**/*.js"],
languageOptions: { globals: { ...globals.node } }
},
{
// the layering: pivotkit-node is shared by the command line and the server and imports neither
files: ["packages/pivotkit-node/src/**/*.js"],
rules: { "no-restricted-imports": ["error", { patterns: [{ regex: "^pivotkit-(cli|server|mcp)(/|$)", message: "pivotkit-node is below the command line and the services; it imports neither" }] }] }
},
{
// a caller's access token leaves auth.js only through exchangeTokenFor, and only the token
// exchange of HTTP sources (sources/auth.js) may call it
files: ["packages/pivotkit-server/src/**/*.js"],
ignores: ["packages/pivotkit-server/src/auth.js", "packages/pivotkit-server/src/sources/auth.js"],
rules: {
"no-restricted-imports": ["error", { patterns: [{ regex: "(^|/)auth\\.js$", importNames: ["exchangeTokenFor"], message: "only sources/auth.js may use exchangeTokenFor (the caller's token goes to a token endpoint and nowhere else)" }] }]
"no-restricted-imports": ["error", { patterns: [{ regex: "(^|/)auth\\.js$", importNames: ["exchangeTokenFor"], message: "only sources/auth.js may use exchangeTokenFor (the caller's token goes to a token endpoint and nowhere else)" }, NO_CLI_IN_SERVER] }]
}
},
{
// auth.js and sources/auth.js may use exchangeTokenFor, but they do not import the command line either
files: ["packages/pivotkit-server/src/auth.js", "packages/pivotkit-server/src/sources/auth.js"],
rules: { "no-restricted-imports": ["error", { patterns: [NO_CLI_IN_SERVER] }] }
},
{
// the UI, the web component, the playground and the element example run in browsers
files: ["packages/pivotkit-react/src/**", "packages/pivotkit-element/src/**", "examples/*/src/**", "examples/element/**"],
Expand Down
22 changes: 22 additions & 0 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading