pivotkit-cli 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to `pivotkit-cli` are documented in this file. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this package adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-13
+
+First release.
+
+### Added
+
+- A workbook over `archiveEntries` or `unpackedBytes` is a `limit` error with the code
+  `LIMIT_EXCEEDED` (pivotkit-xlsx [#208](https://github.com/eizedev/pivotkit/issues/208)); the docs
+  give the measured time and memory of untrusted workbooks at the default limits and recommend
+  `--limit unpackedBytes=...` and a time limit for them.
+- `pivotkit render`, `validate`, `describe`, `completion` (bash, zsh, fish, PowerShell) and `help`,
+  with exit codes 0, 1 (findings) and 2 (usage, file, limit, template) and `--json`
+  ([#165](https://github.com/eizedev/pivotkit/issues/165)).
+- Files read once as regular files with their size checked before reading, written through a
+  temporary file; `--allow-dir` limits every file to the directories named (real paths); no file
+  content in a message.
+- Defaults from `PIVOTKIT_LOCALE`, `PIVOTKIT_TIME_ZONE` and `PIVOTKIT_NOW`; every command checks them
+  and names the variable a wrong value came from.
+- `--bom auto|on|off`: a CSV file of `-o` starts with a byte order mark for Excel, CSV on stdout not.
+- The format comes from `-f` or a known extension of `-o`; another extension (`-o report.pdf`) is a
+  usage error instead of HTML in a `.pdf`.
+- An option that does nothing in the chosen format (`--width` with `csv`) is a warning `ignoredOption`.
+
+[Unreleased]: https://github.com/eizedev/pivotkit/compare/pivotkit-cli@0.1.0...HEAD
+[0.1.0]: https://github.com/eizedev/pivotkit/releases/tag/pivotkit-cli@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 eizedev
+
+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,39 @@
-# Temporary Holding Version
+# pivotkit-cli
 
-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.
+The [pivotkit](https://pivotkit.eize.dev/) command line, `pivotkit`: run a view over a CSV, JSON or
+Excel file and write an HTML report, CSV, JSON, XLSX or the chart as SVG; validate and describe views
+in CI with stable exit codes and `--json`. No network, no browser; with `--now` the output is the same
+on every run. Files are read and written only as regular files, and `--allow-dir` limits them to the
+directories you name.
+
+## Install
+
+```bash
+npm install --global pivotkit-cli    # or: npx pivotkit-cli render ...
+```
+
+Node 22 or later. It brings pivotkit-core, pivotkit-report, pivotkit-xlsx and ECharts 6.1.0.
+
+## Example
+
+```bash
+pivotkit render sales.pivot.json --data sales.csv -o sales.html --now 2026-11-13
+pivotkit validate sales.pivot.json --data sales.csv --strict --json
+pivotkit describe sales.csv
+```
+
+Exit codes: 0 done, 1 findings (an error in the view, or a warning with `--strict`), 2 a usage, file,
+limit or template error.
+
+## Where in the docs
+
+| Topic | Page |
+| --- | --- |
+| Commands, options, exit codes, `--json`, completion, file safety | [pivotkit-cli reference](https://pivotkit.eize.dev/reference/cli/) |
+| The print template of `--template` | [Print template](https://pivotkit.eize.dev/reference/print-template/) |
+| The library it runs on | [pivotkit-report reference](https://pivotkit.eize.dev/reference/report/) |
+| Changes | [CHANGELOG](https://github.com/eizedev/pivotkit/blob/main/packages/pivotkit-cli/CHANGELOG.md) |
+
+## License
+
+[MIT](https://github.com/eizedev/pivotkit/blob/main/LICENSE)

package/bin/pivotkit.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// pivotkit: the command line of pivotkit-report (docs/reference/cli.md).
+import { main } from "../src/cli.js";
+
+process.exitCode = await main(process.argv.slice(2), { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr, env: process.env, cwd: process.cwd() });

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "pivotkit-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The pivotkit command line: render views over CSV, JSON or Excel data to HTML reports, CSV, JSON, XLSX and SVG, and validate or describe views in CI.",
+  "license": "MIT",
+  "author": "eizedev <oss@eize.dev>",
+  "homepage": "https://pivotkit.eize.dev/reference/cli/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eizedev/pivotkit.git",
+    "directory": "packages/pivotkit-cli"
+  },
+  "bugs": "https://github.com/eizedev/pivotkit/issues",
+  "keywords": [
+    "pivotkit",
+    "pivot-table",
+    "cli",
+    "reporting",
+    "report",
+    "csv",
+    "excel",
+    "pivot-grid",
+    "pivottable",
+    "excel-export"
+  ],
+  "type": "module",
+  "bin": {
+    "pivotkit": "bin/pivotkit.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/cli.d.ts",
+      "default": "./src/cli.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "types",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\"",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-include=\"src/**\" \"test/*.test.js\"",
+    "types": "tsc -p .",
+    "test:types": "tsc -p test/types",
+    "prepack": "npm run types && node -e \"require('node:fs').copyFileSync('../../LICENSE', 'LICENSE')\""
+  },
+  "dependencies": {
+    "echarts": "6.1.0",
+    "pivotkit-core": "^0.5.0",
+    "pivotkit-report": "^0.1.0",
+    "pivotkit-xlsx": "^0.2.0"
+  },
+  "types": "./types/cli.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.4"
+  }
+}