pdf-tooling 0.2.0__tar.gz → 0.3.0__tar.gz

{pdf_tooling-0.2.0 → pdf_tooling-0.3.0}/Makefile

@@ -1,4 +1,4 @@
-# pdf-toolkit — developer entry points.
+# pdf-tooling — developer entry points.
 #
 # `make ci` is a SUBSET of CI, run with the same commands -- it does not
 # predict CI. What runs locally, what does not, and why is declared in
@@ -9,6 +9,16 @@
 
 .DEFAULT_GOAL := help
 SHELL := /bin/bash
+# PDF-34 / B-231: `-o pipefail` ONLY, and the narrowness is deliberate and
+# asserted by a test. Without this, a recipe line that pipes a failing
+# command into a reader inherits the READER's status, so `docs-gate`'s arms 1
+# and 3 discarded pytest's verdict and the target exited 0 on a red suite --
+# a gate that cannot fail is not a gate, eight lines after this file says so.
+# `-e` is excluded because make already checks each recipe line's status, so
+# it buys nothing here and would change four `;`-chained recipes; `-u` is
+# excluded because `ARGS`/`PYTEST_ARGS` and several `$$`-shell variables
+# expand empty BY DESIGN. `-c` stays last: make appends the command to it.
+.SHELLFLAGS := -o pipefail -c
 
 ARGS ?=
 PYTEST_ARGS ?=
@@ -31,7 +41,7 @@ endif
 .PHONY: help build install run doctor test test-e2e cover fmt fmt-check lint \
         typecheck vulncheck sast secret-scan licenses samples-scratch samples-check \
         samples-gate engines-gate licenses-check artifacts-check gate-timing \
-        docs-gate ci clean
+        docs-gate shim-reap ci clean
 
 help: ## Show this help
 	@grep -hE '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
@@ -40,14 +50,14 @@ help: ## Show this help
 build: ## Build the sdist and wheel into dist/
 	uv build
 
-install: ## Install the CLI onto your PATH as `pdftoolkit`
+install: ## Install the CLI onto your PATH as `pdftooling`
 	uv tool install --force .
 
 run: ## Run the CLI: make run ARGS="version -o json"
-	uv run pdftoolkit $(ARGS)
+	uv run pdftooling $(ARGS)
 
 doctor: ## Report which engines resolved (arrives with the engine-ports work; exits 2 until then)
-	uv run pdftoolkit doctor
+	uv run pdftooling doctor
 
 test: ## Run the test suite
 	$(UV_RUN) pytest $(PYTEST_ARGS)
@@ -94,7 +104,7 @@ cover: ## Run the suite under coverage against the project's floor
 	echo "$$$$" > "$$lock/pid"; \
 	trap 'rm -rf "$$lock"' EXIT INT TERM; \
 	COVERAGE_FILE=$(CURDIR)/.coverage \
-	  $(UV_RUN) pytest --cov=pdf_toolkit --cov-report=term-missing --cov-fail-under=85 $(PYTEST_ARGS)
+	  $(UV_RUN) pytest --cov=pdf_tooling --cov-report=term-missing --cov-fail-under=85 $(PYTEST_ARGS)
 
 fmt: ## Format the tree
 	uv run ruff format .
@@ -327,14 +337,28 @@ export DOCS_GATE_ENGINES_ASSERT
 # measured wall clock ever argues for inclusion, that is a number for the PM,
 # not a decision taken in this recipe (decision.md §5 R-1).
 #
-# THE ARMS THAT CANNOT ALWAYS RUN SAY SO. Two of them read the maintainer's
-# planning tree (`PDF_TOOLKIT_PLANNING_DIR`) and four read git history deeper
-# than a shallow checkout. `ci.yml`'s `test` job has neither, so in CI those
-# arms SKIP -- and a skipped arm is NEVER agreement. `-rs` prints every skip
-# reason and the epilogue below repeats the count, so "it ran" and "it could
-# not run" can never be read as the same green (X-153).
+# THE ARMS THAT CANNOT ALWAYS RUN SAY SO. MEASURED at PDF-34 HEAD by running
+# the thing in each condition, because the previous figures here ("two" and
+# "four") were BOTH wrong and nothing checked them -- a stale count in the
+# comment above a skip census is the same defect this target exists to end:
+#   FIVE  arms read the maintainer's planning tree (`PDF_TOOLKIT_PLANNING_DIR`);
+#         recipe: PDF_TOOLKIT_PLANNING_DIR=/nonexistent make docs-gate
+#   ELEVEN arms read git history deeper than a shallow checkout, in TWO classes
+#         -- 10 against MINIMUM_HISTORY_DEPTH, plus 1 that cannot check a depth
+#         precondition against a checkout never given the depth to check it;
+#         recipe: run the three arm-3 files inside `git clone --depth 1`.
+# `ci.yml`'s `test` job has neither, so in CI all SIXTEEN skip -- and a skipped
+# arm is NEVER agreement. `-rs` prints every skip reason and the epilogue below
+# repeats the count, so "it ran" and "it could not run" can never be read as
+# the same green (X-153).
+#
+# PDF-34 D3: `DOCS_GATE_STRICT=1` turns that sentence into an exit code. Unset
+# (the default) is byte-for-byte today's behaviour -- skips are printed and
+# counted and the target still exits 0 -- because the five planning arms
+# LEGITIMATELY cannot run in CI, which checks out this repository alone. The
+# cadence that CAN see both trees runs it strict, where zero arms may skip.
 define DOCS_GATE_EPILOGUE
-import re, sys
+import os, re, sys
 text = sys.stdin.read()
 sys.stdout.write(text)
 # pytest AGGREGATES identical skip reasons as `SKIPPED [N] <reason>`, so
@@ -352,6 +376,21 @@ if skipped:
     print("  A SKIPPED ARM IS NOT AGREEMENT. Re-run with PDF_TOOLKIT_PLANNING_DIR")
     print("  pointed at the planning tree, and in a full (non-shallow) clone, to")
     print("  turn these into real comparisons. `make ci` does not run this target.")
+# PDF-34 D3. For as long as this epilogue has existed it has PRINTED
+# "A SKIPPED ARM IS NOT AGREEMENT" and then exited 0 anyway -- the rule stated
+# in prose, by the gate, about itself, with nothing enforcing it. Strict mode
+# is that sentence as an exit code, and it is opt-in for one measured reason:
+# CI checks out this repository alone, so the five planning arms skip there for
+# a reason that is not a defect, and a strict CI run would fail honestly-shaped
+# but wrongly. The Tier-2 cadence runs where BOTH trees exist, so zero arms may
+# skip and any skip is real news.
+if skipped and os.environ.get("DOCS_GATE_STRICT", "").strip() not in ("", "0", "false", "no"):
+    print("")
+    print("  DOCS_GATE_STRICT=1: %d skipped arm(s) in %d class(es) is a FAILURE."
+          % (arms, len(skipped)))
+    print("  A SKIPPED ARM IS NOT AGREEMENT -- and under this posture that is an")
+    print("  exit code, not a paragraph. Classes above name what could not run.")
+    sys.exit(1)
 endef
 export DOCS_GATE_EPILOGUE
 
@@ -374,3 +413,23 @@ ci: fmt-check lint typecheck cover licenses sast vulncheck ## Run the full local
 clean: ## Remove build, cache and coverage artefacts
 	rm -rf dist build .pytest_cache .ruff_cache .mypy_cache htmlcov .coverage coverage.xml .scratch .make-cover.lock
 	rm -f .coverage.*
+
+# PDF-46 D5. The engine-hiding shim used to leak one directory per pytest
+# process -- and under the project's default parallel mode, one per xdist
+# worker plus one for the controller, which is the multiplier that made this
+# worth fixing. `tests/conftest.py` now reclaims its own at interpreter exit,
+# which fixes the leak going FORWARD and deliberately removes nothing that was
+# already there: the standing residue is the sentinel's recorded evidence, and
+# an engineer deleting another agent's evidence mid-cycle is the same class of
+# act as editing the ledger.
+#
+# So this target LISTS by default and the destructive path needs a word typed.
+# It is a prerequisite of NOTHING -- not `clean`, not `test`, not `cover`, not
+# `ci`, not `engines-gate`, not `docs-gate` -- and that is asserted by parsing
+# this file (tests/test_engine_hiding_shim.py), not trusted. A reaper that had
+# quietly become part of `clean` or `ci` would delete a concurrent session's
+# LIVE shim, and the symptom would look like a flake.
+SHIM_REAP_ARGS ?=
+
+shim-reap: ## List stale engine-hiding shim directories left by earlier runs; removes only with CONFIRM=1
+	$(UV_RUN) python scripts/reap_shims.py $(if $(CONFIRM),--confirm) $(SHIM_REAP_ARGS)

{pdf_tooling-0.2.0 → pdf_tooling-0.3.0}/NOTICE

@@ -1,4 +1,4 @@
-pdf-toolkit
+pdf-tooling
 Copyright 2026 Armando Herra
 
 Licensed under the Apache License, Version 2.0. See LICENSE for the full text.

{pdf_tooling-0.2.0 → pdf_tooling-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pdf-tooling
-Version: 0.2.0
+Version: 0.3.0
 Summary: One safe, permissively-licensed command-line tool for the common PDF chores.
 Project-URL: Homepage, https://github.com/ArmandoHerra/pdf-tooling
 Project-URL: Repository, https://github.com/ArmandoHerra/pdf-tooling
@@ -38,9 +38,9 @@ Provides-Extra: html
 Requires-Dist: weasyprint<70,>=69.0; extra == 'html'
 Description-Content-Type: text/markdown
 
-# pdf-toolkit
+# pdf-tooling
 
-An Apache-2.0 PDF toolkit CLI in Python. One safe command-line tool (`pdftoolkit`) for the common PDF chores — `merge`, `split`, `extract`, `delete`, `rotate`, `reorder`, `rasterize`, `compose`, `create`, `text`, `tables`, `compress`, `repair`, `linearize`, `encrypt`, `decrypt`, `permissions`, `meta`, `watermark`, `stamp`, `ocr` and `convert`, plus `doctor`, `info` and `version` — built on a permissively licensed engine stack (pypdf, pypdfium2, reportlab, pikepdf, pdfplumber, Tesseract, LibreOffice) with nothing AGPL or GPL on the call graph.
+An Apache-2.0 PDF toolkit CLI in Python. One safe command-line tool (`pdftooling`) for the common PDF chores — `merge`, `split`, `extract`, `delete`, `rotate`, `reorder`, `rasterize`, `compose`, `create`, `text`, `tables`, `compress`, `repair`, `linearize`, `encrypt`, `decrypt`, `permissions`, `meta`, `watermark`, `stamp`, `ocr` and `convert`, plus `doctor`, `info` and `version` — built on a permissively licensed engine stack (pypdf, pypdfium2, reportlab, pikepdf, pdfplumber, Tesseract, LibreOffice) with nothing AGPL or GPL on the call graph.
 
 Safety is first-class: a global `--dry-run`, no-clobber by default, atomic write-to-temp-then-rename, and inputs that are never mutated unless you ask for `--in-place`.
 
@@ -48,12 +48,6 @@ Safety is first-class: a global `--dry-run`, no-clobber by default, atomic write
 
 - **Website:** https://armandoherra.github.io/pdf-tooling/ — the public landing page (source in `website/`).
 
-## This is not `pdftk`
-
-`pdf-toolkit` shares no code with `pdftk`, is not a fork of it, and is not a drop-in replacement for it. `pdftk` is GPL-licensed; this project is **Apache-2.0**, and its engine policy forbids anything under AGPL, GPL or LGPL from appearing as an import, an optional extra, or a `subprocess` fallback. The console script is named `pdftoolkit` precisely so the two cannot be confused on your `PATH`.
-
-The PyPI **distribution** to install is **`pdf-tooling`**. The distribution named `pdftoolkit` on PyPI is an unrelated GPL-3.0 project and is not this software. The names this project owns, and which of them moved, are the contract in [Naming](#naming).
-
 ## Naming
 
 The names below are this project's contract. They differ deliberately, and a reader
@@ -62,31 +56,36 @@ citing any of them should cite the table rather than the prose around it.
 | Kind | Name |
 |---|---|
 | PyPI distribution | `pdf-tooling` |
-| Repository | `github.com/ArmandoHerra/pdf-tooling` |
-| Import package | `pdf_toolkit` |
-| Console scripts | `pdftoolkit` (canonical), `pdf-toolkit` (alias) |
-
-**Why the distribution is not `pdf-toolkit`.** That name sits too close to names already
-on PyPI, and the distribution called `pdftoolkit` there is an unrelated GPL-3.0 project
-that is not this software. The repository followed the distribution; the import package
-and both console scripts did not, because they are published surfaces and moving them
-would break an install that already works.
-
-**Both console scripts are supported.** `pdftoolkit` is canonical and `pdf-toolkit` is a
-documented alias; they resolve to the same entry point, and the alias is not deprecated
-by this rename.
+| Repository | `pdf-tooling` |
+| Import package | `pdf_tooling` |
+| Console script | `pdftooling` |
+| Aliases | `pdf-tooling`, plus deprecated `pdftoolkit` and `pdf-toolkit` until `v1.0.0` |
+
+**Why the names differ.** The PyPI distribution is `pdf-tooling` because `pdf-toolkit`
+sits too close to names already on PyPI, and the distribution called `pdftoolkit` there
+is an unrelated GPL-3.0 project that is not this software. The repository followed the
+distribution; the import package and the console script followed it in turn, once the
+deprecation window below made moving a published surface safe.
+
+**The deprecation window.** `pdftoolkit` and `pdf-toolkit` remain installed and fully
+functional through `v1.0.0` — same behaviour, same exit codes — each printing one line
+on stderr naming `pdftooling` as the replacement. The distribution named `pdftoolkit` on
+PyPI is an unrelated GPL-3.0 project; this project's deprecated `pdftoolkit` console
+script — and this warning with it — is removed at `v1.0.0`.
 
 **Release history, so the install lines above can be read against it.** `v0.1.0` was
 git-install-only and was never published to PyPI under either name; `v0.1.1` is the
 first published release, as `pdf-tooling`; `v0.2.0` is the first published under the
-renamed repository.
+renamed repository; `v0.3.0` is the first release to ship the renamed `pdftooling`
+console script and `pdf_tooling` import package, with `pdftoolkit`/`pdf-toolkit`/
+`pdf_toolkit` deprecated behind it.
 
 ## Getting Started
 
 ```bash
 uv tool install pdf-tooling
 # or: pip install pdf-tooling
-pdftoolkit --help
+pdftooling --help
 ```
 
 ### From source
@@ -96,7 +95,7 @@ pdftoolkit --help
 git clone https://github.com/ArmandoHerra/pdf-tooling.git
 cd pdf-tooling
 uv sync
-uv run pdftoolkit --help
+uv run pdftooling --help
 ```
 
 `uv sync` installs the runtime stack *and* the development tooling, so there is no separate bootstrap step.
@@ -120,18 +119,18 @@ The complete top-level roster, by family:
 
 That table is asserted against the live command tree by set-inclusion, so a verb
 shipped tomorrow turns the check red with no author action — but
-`uv run pdftoolkit --help` remains the authoritative list.
+`uv run pdftooling --help` remains the authoritative list.
 
 ```bash
-uv run pdftoolkit --help               # the full verb tree; always the authoritative list
-uv run pdftoolkit doctor               # which engines resolved, and how
-uv run pdftoolkit merge a.pdf b.pdf -O merged.pdf
-uv run pdftoolkit rotate report.pdf --pages 2-4 --angle 90 -O rotated.pdf
-uv run pdftoolkit compress report.pdf -O small.pdf
-uv run pdftoolkit --version            # tool, Python and engine versions on one line
+uv run pdftooling --help               # the full verb tree; always the authoritative list
+uv run pdftooling doctor               # which engines resolved, and how
+uv run pdftooling merge a.pdf b.pdf -O merged.pdf
+uv run pdftooling rotate report.pdf --pages 2-4 --angle 90 -O rotated.pdf
+uv run pdftooling compress report.pdf -O small.pdf
+uv run pdftooling --version            # tool, Python and engine versions on one line
 ```
 
-`uv run pdftoolkit --help` is the authoritative list of what is actually available at any moment — if a verb is not printed there, it does not exist yet.
+`uv run pdftooling --help` is the authoritative list of what is actually available at any moment — if a verb is not printed there, it does not exist yet.
 
 ## Output contract
 
@@ -145,9 +144,42 @@ Rendered payloads go to **stdout**; diagnostics, warnings and progress go to **s
 
 Errors are the one deliberate asymmetry: with `-o table` an error is a one-line `error: …` on stderr, but with `-o json`/`-o ndjson` it is an object on **stdout**, so a machine consumer reading stdout never has to also read stderr to learn that the run failed. That holds for **every** failure you can reach, an unknown flag and a missing argument included: those are usage errors (exit 2) carrying the same envelope, not a human `Usage:` block.
 
-**A command group does not take the global block.** `meta` groups `meta get` and `meta set`, and the global flags are declared at the root and on every verb, never on a group — so `pdftoolkit meta -o json` is a usage error (exit 2) rather than a run. It names the two positions that do work: `pdftoolkit -o json meta get FILE` (before the group) and `pdftoolkit meta get FILE -o json` (after the subcommand).
+**A command group does not take the global block.** `meta` groups `meta get` and `meta set`, and the global flags are declared at the root and on every verb, never on a group — so `pdftooling meta -o json` is a usage error (exit 2) rather than a run. It names the two positions that do work: `pdftooling -o json meta get FILE` (before the group) and `pdftooling meta get FILE -o json` (after the subcommand).
+
+**Global flags with no command at all** — `pdftooling -o json` — are an incomplete invocation and exit 2 as well, pointing at `--help`. `pdftooling` on its own, with no arguments, still prints help and exits 0.
+
+### The collection key
+
+Every `-o json` envelope that carries a collection of rows carries them under `items`. `doctor` and `info` additionally publish that same list under a name of their own, and both names are frozen: `doctor`'s `ports` is pinned by the plan's own `pdftooling doctor -o json | jq '.ports[] | select(.available == false)'` example, and `info`'s `documents` is its shipped shape. Neither is being renamed. The alias was added beside them so that a single `jq` expression works against every verb.
+
+| Verb | Primary key | Universal alias | Relationship |
+|---|---|---|---|
+| every verb that returns an operation result | `items` | `items` | the same list |
+| `info` | `documents` | `items` | the same list |
+| `doctor` | `ports` | `items` | the same list |
+
+`meta get` publishes a single document's report rather than a collection, so it has no row collection and names none.
+
+Every `-o json` envelope also carries `exit_code`, `warnings` and `duration_ms`, on every verb. `warnings` is a list and is `[]` when empty — never `null`, never absent. `exit_code` is the code the process exits with for the run the envelope describes, and `duration_ms` is `0` on the verbs whose output must be reproducible byte-for-byte.
+
+### A batch reports every input, and never denies a file it wrote
+
+A multi-input run writing into `--out-dir` records **every input by name, in command-line order**, in the payload's collection — the inputs that succeeded and the input that failed alike. A failing input is recorded, the run continues, and the run exits `1` at the end; each row carries its own `ok`, `exit_code` and `message`. A row that succeeded names its artifact in `output`, and that path is on disk.
 
-**Global flags with no command at all** — `pdftoolkit -o json` — are an incomplete invocation and exit 2 as well, pointing at `--help`. `pdftoolkit` on its own, with no arguments, still prints help and exits 0.
+**This is a behaviour change on a failure path, inside the pre-`1.0.0` window.** A multi-input `--out-dir` failure used to emit the error envelope — `{"schema_version": 1, "error": {…, "path": null}}`, with no collection at all — in place of the operation envelope, so the input that succeeded went unreported and the input that failed went unnamed even while its sibling's artifact sat on disk. A script that parsed such a failure by reading `payload["error"]` now finds `payload["items"]` instead. **`schema_version` stays `1`**: no key is renamed, removed, retyped or repurposed, and the error envelope itself is unchanged.
+
+Failures that are properties of the invocation rather than of an input stay run-scoped and keep the error envelope: a usage error, a directory where a file was expected, a nonexistent input, a missing engine, and the refusals the safety gate raises. A missing engine fails identically for every input, so it stays a single accurate diagnosis carrying its own exit code rather than becoming a row per input that also changes what the process exits with. A single-input run likewise reports that item's own code, which is what keeps the per-input codes distinguishable at all.
+
+### `schema_version` is `1`, and this is what would move it
+
+`schema_version` is `1` and stays `1` for as long as the envelope changes only by **addition**. Adding a key never moves it; nor does adding a verb, an item field, or an output format. It increments on the first change a consumer that reads keys by name cannot survive, which is exactly this list:
+
+- a published key is **renamed**;
+- a published key is **removed**;
+- a published key's **type** changes — including `[]` becoming `null`, or a scalar becoming an object;
+- a published key's **meaning** changes while its name and type stay the same.
+
+An increment is **coupled to a major version bump**; they move together or not at all.
 
 The structured shapes and the exit-code table below are **public API from v1.0.0**. Breaking either requires a major version bump and a `schema_version` increment. Pre-1.0 releases are explicitly still moving.
 
@@ -200,15 +232,36 @@ No secure erasure is claimed, anywhere. A resolved password is held in a buffer
 
 `encrypt --in-place` needs one more word from you, and it is the one place where the safety default and the security default point in opposite directions. The `.bak` sidecar is a copy of the **original**, so an in-place encryption would leave plaintext sitting next to the ciphertext, silently. So it refuses (exit 5) unless you pass `--no-backup` (keep no plaintext copy) or `-y` (keep it, knowingly).
 
+### The permission vocabularies
+
+`pdftooling info -o json` and `pdftooling permissions -o json` are **both public output**, and they spell some of their permission tokens differently. That is a documented divergence, not a defect to be tidied: both spellings shipped, both are `schema_version: 1` public API, and renaming either would break a published contract. So the crossing is published here instead. **`--allow` accepts the left column only** — the right column is `info`'s output spelling and is not an input token.
+
+| `--allow` / `permissions` | `info` | `ISO 32000-1 Table 22` bit |
+|---|---|---|
+| `print` | `print` | `3` |
+| `modify` | `modify` | `4` |
+| `copy` | `copy` | `5` |
+| `annotate` | `annotate` | `6` |
+| `forms` | `fill-forms` | `9` |
+| `accessibility` | `extract-accessibility` | `10` |
+| `assemble` | `assemble` | `11` |
+| `print-highres` | `print-high-resolution` | `12` |
+
+The tokens spelled identically on both surfaces need no translation; the ones that diverge are the same bit under a different name. Without this table, a consumer that runs both verbs against the same encrypted document sees phantom differences on every file. The table is derived from the source constants by a test, so it cannot rot away from what the tool actually emits.
+
 **Permission bits are advisory.** They are a request to the reader, not a lock: only cooperating readers honour them, any reader holding the file may ignore every bit, and a reader that can display a page can extract it. Encryption protects the content; the bits on their own protect nothing. `--allow` takes a comma-separated, repeatable list from `print`, `print-highres`, `copy`, `modify`, `annotate`, `forms`, `assemble`, `accessibility`, plus the exclusive `all` and `none`; omitting it grants nothing. `accessibility` is granted whatever you ask for — PDF 2.0 deprecated that bit and conforming readers always permit it — and `permissions` reports what the document actually grants rather than what was requested. **`print-highres` also grants `print`**: a reader permitted to print at full resolution may obviously print at low resolution, and the format has no spelling for “high but not low”, so asking for the one token grants two. That is the format's behaviour rather than this tool's choice, and it is disclosed at the flag that causes it instead of being left for `permissions` to reveal afterwards.
 
+### `--password-file` is global: honoured or refused, never silently ignored
+
+`--password-file` (and its resolution siblings — the `PDF_TOOLKIT_PASSWORD` environment variable and the interactive prompt) is declared on **every** verb, because any of them may meet a password-protected input — including the report-only ones. A verb that can open an encrypted document uses the resolved password there, on the SAME first-hit-wins chain `encrypt`/`decrypt` already document above; a verb that structurally cannot use one (it takes no document operand, or it already declares its own dedicated password flag) refuses it up front, at exit **2**, naming the flag rather than accepting it and doing nothing — the same "declared but silently inert" shape this tool refuses for every other global flag (see the safety contract above). There is no hand-maintained list of which verbs fall into which group here: run the verb's own `--help` to see the flag declared, or try it — a verb that cannot honour it says so immediately, before any document is opened.
+
 `decrypt` round-trips the **page tree** byte for byte: the decoded content streams, the page dictionaries and every embedded image's raw bytes come back identical. The whole file does not, and nothing here claims it does — `/ID`, `/Encrypt`, the trailer, the cross-reference table and object numbering all legitimately change on any resave.
 
 ## OCR and Office conversion
 
-`ocr` and `convert` are the two verbs that depend on a system binary rather than a Python wheel — the two verbs `pdftoolkit doctor` can legitimately report as unavailable.
+`ocr` and `convert` are the two verbs that depend on a system binary rather than a Python wheel — the two verbs `pdftooling doctor` can legitimately report as unavailable.
 
-`ocr` drives the **tesseract** binary. For every selected page it renders the page, recognises a text-only layer, and overlays that layer on the **original** page object — the page's own image is never re-rendered, and a byte-level check proves the image stream is identical before and after. `--skip-text-pages` leaves a page that already has extractable text untouched (no render, no OCR call). This build ships whatever tessdata language packs the host has installed; `--lang` is validated against exactly that list (`pdftoolkit doctor`), and a pack that is not installed exits 3 with an install hint naming it. No accuracy or confidence claim is made anywhere in this tool — `ocr` is described here by its engine, not by a quality promise.
+`ocr` drives the **tesseract** binary. For every selected page it renders the page, recognises a text-only layer, and overlays that layer on the **original** page object — the page's own image is never re-rendered, and a byte-level check proves the image stream is identical before and after. `--skip-text-pages` leaves a page that already has extractable text untouched (no render, no OCR call). This build ships whatever tessdata language packs the host has installed; `--lang` is validated against exactly that list (`pdftooling doctor`), and a pack that is not installed exits 3 with an install hint naming it. No accuracy or confidence claim is made anywhere in this tool — `ocr` is described here by its engine, not by a quality promise.
 
 `convert` drives headless **LibreOffice** (`soffice`) to turn an office document into a PDF. Each invocation gets its own isolated LibreOffice profile directory and converts into a private scratch location first — LibreOffice never writes to the destination directly, and the destination is only touched through this tool's one write chokepoint. An exit 0 from `soffice` having produced no output file is treated as a failure here, not a success, because that is a real and well-known LibreOffice failure mode. `--timeout` bounds one conversion; on expiry the whole process group is killed, so no `soffice.bin` daemon is left running.
 
@@ -238,4 +291,4 @@ If a sweep ever records nothing open, this section still stands and reads *no op
 
 ## License
 
-Apache-2.0 — see `LICENSE` and `NOTICE`. `THIRD_PARTY_LICENSES` is generated from the resolved environment and ships in both the sdist and the wheel.
+Apache-2.0 — see `LICENSE` and `NOTICE`. `THIRD_PARTY_LICENSES` is generated from the resolved environment and ships in both the sdist and the wheel. `pdftk` is GPL-licensed; this project is **Apache-2.0**, and its engine policy forbids anything under AGPL, GPL or LGPL from appearing as an import, an optional extra, or a `subprocess` fallback.

{pdf_tooling-0.2.0 → pdf_tooling-0.3.0}/README.md

@@ -1,6 +1,6 @@
-# pdf-toolkit
+# pdf-tooling
 
-An Apache-2.0 PDF toolkit CLI in Python. One safe command-line tool (`pdftoolkit`) for the common PDF chores — `merge`, `split`, `extract`, `delete`, `rotate`, `reorder`, `rasterize`, `compose`, `create`, `text`, `tables`, `compress`, `repair`, `linearize`, `encrypt`, `decrypt`, `permissions`, `meta`, `watermark`, `stamp`, `ocr` and `convert`, plus `doctor`, `info` and `version` — built on a permissively licensed engine stack (pypdf, pypdfium2, reportlab, pikepdf, pdfplumber, Tesseract, LibreOffice) with nothing AGPL or GPL on the call graph.
+An Apache-2.0 PDF toolkit CLI in Python. One safe command-line tool (`pdftooling`) for the common PDF chores — `merge`, `split`, `extract`, `delete`, `rotate`, `reorder`, `rasterize`, `compose`, `create`, `text`, `tables`, `compress`, `repair`, `linearize`, `encrypt`, `decrypt`, `permissions`, `meta`, `watermark`, `stamp`, `ocr` and `convert`, plus `doctor`, `info` and `version` — built on a permissively licensed engine stack (pypdf, pypdfium2, reportlab, pikepdf, pdfplumber, Tesseract, LibreOffice) with nothing AGPL or GPL on the call graph.
 
 Safety is first-class: a global `--dry-run`, no-clobber by default, atomic write-to-temp-then-rename, and inputs that are never mutated unless you ask for `--in-place`.
 
@@ -8,12 +8,6 @@ Safety is first-class: a global `--dry-run`, no-clobber by default, atomic write
 
 - **Website:** https://armandoherra.github.io/pdf-tooling/ — the public landing page (source in `website/`).
 
-## This is not `pdftk`
-
-`pdf-toolkit` shares no code with `pdftk`, is not a fork of it, and is not a drop-in replacement for it. `pdftk` is GPL-licensed; this project is **Apache-2.0**, and its engine policy forbids anything under AGPL, GPL or LGPL from appearing as an import, an optional extra, or a `subprocess` fallback. The console script is named `pdftoolkit` precisely so the two cannot be confused on your `PATH`.
-
-The PyPI **distribution** to install is **`pdf-tooling`**. The distribution named `pdftoolkit` on PyPI is an unrelated GPL-3.0 project and is not this software. The names this project owns, and which of them moved, are the contract in [Naming](#naming).
-
 ## Naming
 
 The names below are this project's contract. They differ deliberately, and a reader
@@ -22,31 +16,36 @@ citing any of them should cite the table rather than the prose around it.
 | Kind | Name |
 |---|---|
 | PyPI distribution | `pdf-tooling` |
-| Repository | `github.com/ArmandoHerra/pdf-tooling` |
-| Import package | `pdf_toolkit` |
-| Console scripts | `pdftoolkit` (canonical), `pdf-toolkit` (alias) |
-
-**Why the distribution is not `pdf-toolkit`.** That name sits too close to names already
-on PyPI, and the distribution called `pdftoolkit` there is an unrelated GPL-3.0 project
-that is not this software. The repository followed the distribution; the import package
-and both console scripts did not, because they are published surfaces and moving them
-would break an install that already works.
-
-**Both console scripts are supported.** `pdftoolkit` is canonical and `pdf-toolkit` is a
-documented alias; they resolve to the same entry point, and the alias is not deprecated
-by this rename.
+| Repository | `pdf-tooling` |
+| Import package | `pdf_tooling` |
+| Console script | `pdftooling` |
+| Aliases | `pdf-tooling`, plus deprecated `pdftoolkit` and `pdf-toolkit` until `v1.0.0` |
+
+**Why the names differ.** The PyPI distribution is `pdf-tooling` because `pdf-toolkit`
+sits too close to names already on PyPI, and the distribution called `pdftoolkit` there
+is an unrelated GPL-3.0 project that is not this software. The repository followed the
+distribution; the import package and the console script followed it in turn, once the
+deprecation window below made moving a published surface safe.
+
+**The deprecation window.** `pdftoolkit` and `pdf-toolkit` remain installed and fully
+functional through `v1.0.0` — same behaviour, same exit codes — each printing one line
+on stderr naming `pdftooling` as the replacement. The distribution named `pdftoolkit` on
+PyPI is an unrelated GPL-3.0 project; this project's deprecated `pdftoolkit` console
+script — and this warning with it — is removed at `v1.0.0`.
 
 **Release history, so the install lines above can be read against it.** `v0.1.0` was
 git-install-only and was never published to PyPI under either name; `v0.1.1` is the
 first published release, as `pdf-tooling`; `v0.2.0` is the first published under the
-renamed repository.
+renamed repository; `v0.3.0` is the first release to ship the renamed `pdftooling`
+console script and `pdf_tooling` import package, with `pdftoolkit`/`pdf-toolkit`/
+`pdf_toolkit` deprecated behind it.
 
 ## Getting Started
 
 ```bash
 uv tool install pdf-tooling
 # or: pip install pdf-tooling
-pdftoolkit --help
+pdftooling --help
 ```
 
 ### From source
@@ -56,7 +55,7 @@ pdftoolkit --help
 git clone https://github.com/ArmandoHerra/pdf-tooling.git
 cd pdf-tooling
 uv sync
-uv run pdftoolkit --help
+uv run pdftooling --help
 ```
 
 `uv sync` installs the runtime stack *and* the development tooling, so there is no separate bootstrap step.
@@ -80,18 +79,18 @@ The complete top-level roster, by family:
 
 That table is asserted against the live command tree by set-inclusion, so a verb
 shipped tomorrow turns the check red with no author action — but
-`uv run pdftoolkit --help` remains the authoritative list.
+`uv run pdftooling --help` remains the authoritative list.
 
 ```bash
-uv run pdftoolkit --help               # the full verb tree; always the authoritative list
-uv run pdftoolkit doctor               # which engines resolved, and how
-uv run pdftoolkit merge a.pdf b.pdf -O merged.pdf
-uv run pdftoolkit rotate report.pdf --pages 2-4 --angle 90 -O rotated.pdf
-uv run pdftoolkit compress report.pdf -O small.pdf
-uv run pdftoolkit --version            # tool, Python and engine versions on one line
+uv run pdftooling --help               # the full verb tree; always the authoritative list
+uv run pdftooling doctor               # which engines resolved, and how
+uv run pdftooling merge a.pdf b.pdf -O merged.pdf
+uv run pdftooling rotate report.pdf --pages 2-4 --angle 90 -O rotated.pdf
+uv run pdftooling compress report.pdf -O small.pdf
+uv run pdftooling --version            # tool, Python and engine versions on one line
 ```
 
-`uv run pdftoolkit --help` is the authoritative list of what is actually available at any moment — if a verb is not printed there, it does not exist yet.
+`uv run pdftooling --help` is the authoritative list of what is actually available at any moment — if a verb is not printed there, it does not exist yet.
 
 ## Output contract
 
@@ -105,9 +104,42 @@ Rendered payloads go to **stdout**; diagnostics, warnings and progress go to **s
 
 Errors are the one deliberate asymmetry: with `-o table` an error is a one-line `error: …` on stderr, but with `-o json`/`-o ndjson` it is an object on **stdout**, so a machine consumer reading stdout never has to also read stderr to learn that the run failed. That holds for **every** failure you can reach, an unknown flag and a missing argument included: those are usage errors (exit 2) carrying the same envelope, not a human `Usage:` block.
 
-**A command group does not take the global block.** `meta` groups `meta get` and `meta set`, and the global flags are declared at the root and on every verb, never on a group — so `pdftoolkit meta -o json` is a usage error (exit 2) rather than a run. It names the two positions that do work: `pdftoolkit -o json meta get FILE` (before the group) and `pdftoolkit meta get FILE -o json` (after the subcommand).
+**A command group does not take the global block.** `meta` groups `meta get` and `meta set`, and the global flags are declared at the root and on every verb, never on a group — so `pdftooling meta -o json` is a usage error (exit 2) rather than a run. It names the two positions that do work: `pdftooling -o json meta get FILE` (before the group) and `pdftooling meta get FILE -o json` (after the subcommand).
+
+**Global flags with no command at all** — `pdftooling -o json` — are an incomplete invocation and exit 2 as well, pointing at `--help`. `pdftooling` on its own, with no arguments, still prints help and exits 0.
+
+### The collection key
+
+Every `-o json` envelope that carries a collection of rows carries them under `items`. `doctor` and `info` additionally publish that same list under a name of their own, and both names are frozen: `doctor`'s `ports` is pinned by the plan's own `pdftooling doctor -o json | jq '.ports[] | select(.available == false)'` example, and `info`'s `documents` is its shipped shape. Neither is being renamed. The alias was added beside them so that a single `jq` expression works against every verb.
+
+| Verb | Primary key | Universal alias | Relationship |
+|---|---|---|---|
+| every verb that returns an operation result | `items` | `items` | the same list |
+| `info` | `documents` | `items` | the same list |
+| `doctor` | `ports` | `items` | the same list |
+
+`meta get` publishes a single document's report rather than a collection, so it has no row collection and names none.
+
+Every `-o json` envelope also carries `exit_code`, `warnings` and `duration_ms`, on every verb. `warnings` is a list and is `[]` when empty — never `null`, never absent. `exit_code` is the code the process exits with for the run the envelope describes, and `duration_ms` is `0` on the verbs whose output must be reproducible byte-for-byte.
+
+### A batch reports every input, and never denies a file it wrote
+
+A multi-input run writing into `--out-dir` records **every input by name, in command-line order**, in the payload's collection — the inputs that succeeded and the input that failed alike. A failing input is recorded, the run continues, and the run exits `1` at the end; each row carries its own `ok`, `exit_code` and `message`. A row that succeeded names its artifact in `output`, and that path is on disk.
 
-**Global flags with no command at all** — `pdftoolkit -o json` — are an incomplete invocation and exit 2 as well, pointing at `--help`. `pdftoolkit` on its own, with no arguments, still prints help and exits 0.
+**This is a behaviour change on a failure path, inside the pre-`1.0.0` window.** A multi-input `--out-dir` failure used to emit the error envelope — `{"schema_version": 1, "error": {…, "path": null}}`, with no collection at all — in place of the operation envelope, so the input that succeeded went unreported and the input that failed went unnamed even while its sibling's artifact sat on disk. A script that parsed such a failure by reading `payload["error"]` now finds `payload["items"]` instead. **`schema_version` stays `1`**: no key is renamed, removed, retyped or repurposed, and the error envelope itself is unchanged.
+
+Failures that are properties of the invocation rather than of an input stay run-scoped and keep the error envelope: a usage error, a directory where a file was expected, a nonexistent input, a missing engine, and the refusals the safety gate raises. A missing engine fails identically for every input, so it stays a single accurate diagnosis carrying its own exit code rather than becoming a row per input that also changes what the process exits with. A single-input run likewise reports that item's own code, which is what keeps the per-input codes distinguishable at all.
+
+### `schema_version` is `1`, and this is what would move it
+
+`schema_version` is `1` and stays `1` for as long as the envelope changes only by **addition**. Adding a key never moves it; nor does adding a verb, an item field, or an output format. It increments on the first change a consumer that reads keys by name cannot survive, which is exactly this list:
+
+- a published key is **renamed**;
+- a published key is **removed**;
+- a published key's **type** changes — including `[]` becoming `null`, or a scalar becoming an object;
+- a published key's **meaning** changes while its name and type stay the same.
+
+An increment is **coupled to a major version bump**; they move together or not at all.
 
 The structured shapes and the exit-code table below are **public API from v1.0.0**. Breaking either requires a major version bump and a `schema_version` increment. Pre-1.0 releases are explicitly still moving.
 
@@ -160,15 +192,36 @@ No secure erasure is claimed, anywhere. A resolved password is held in a buffer
 
 `encrypt --in-place` needs one more word from you, and it is the one place where the safety default and the security default point in opposite directions. The `.bak` sidecar is a copy of the **original**, so an in-place encryption would leave plaintext sitting next to the ciphertext, silently. So it refuses (exit 5) unless you pass `--no-backup` (keep no plaintext copy) or `-y` (keep it, knowingly).
 
+### The permission vocabularies
+
+`pdftooling info -o json` and `pdftooling permissions -o json` are **both public output**, and they spell some of their permission tokens differently. That is a documented divergence, not a defect to be tidied: both spellings shipped, both are `schema_version: 1` public API, and renaming either would break a published contract. So the crossing is published here instead. **`--allow` accepts the left column only** — the right column is `info`'s output spelling and is not an input token.
+
+| `--allow` / `permissions` | `info` | `ISO 32000-1 Table 22` bit |
+|---|---|---|
+| `print` | `print` | `3` |
+| `modify` | `modify` | `4` |
+| `copy` | `copy` | `5` |
+| `annotate` | `annotate` | `6` |
+| `forms` | `fill-forms` | `9` |
+| `accessibility` | `extract-accessibility` | `10` |
+| `assemble` | `assemble` | `11` |
+| `print-highres` | `print-high-resolution` | `12` |
+
+The tokens spelled identically on both surfaces need no translation; the ones that diverge are the same bit under a different name. Without this table, a consumer that runs both verbs against the same encrypted document sees phantom differences on every file. The table is derived from the source constants by a test, so it cannot rot away from what the tool actually emits.
+
 **Permission bits are advisory.** They are a request to the reader, not a lock: only cooperating readers honour them, any reader holding the file may ignore every bit, and a reader that can display a page can extract it. Encryption protects the content; the bits on their own protect nothing. `--allow` takes a comma-separated, repeatable list from `print`, `print-highres`, `copy`, `modify`, `annotate`, `forms`, `assemble`, `accessibility`, plus the exclusive `all` and `none`; omitting it grants nothing. `accessibility` is granted whatever you ask for — PDF 2.0 deprecated that bit and conforming readers always permit it — and `permissions` reports what the document actually grants rather than what was requested. **`print-highres` also grants `print`**: a reader permitted to print at full resolution may obviously print at low resolution, and the format has no spelling for “high but not low”, so asking for the one token grants two. That is the format's behaviour rather than this tool's choice, and it is disclosed at the flag that causes it instead of being left for `permissions` to reveal afterwards.
 
+### `--password-file` is global: honoured or refused, never silently ignored
+
+`--password-file` (and its resolution siblings — the `PDF_TOOLKIT_PASSWORD` environment variable and the interactive prompt) is declared on **every** verb, because any of them may meet a password-protected input — including the report-only ones. A verb that can open an encrypted document uses the resolved password there, on the SAME first-hit-wins chain `encrypt`/`decrypt` already document above; a verb that structurally cannot use one (it takes no document operand, or it already declares its own dedicated password flag) refuses it up front, at exit **2**, naming the flag rather than accepting it and doing nothing — the same "declared but silently inert" shape this tool refuses for every other global flag (see the safety contract above). There is no hand-maintained list of which verbs fall into which group here: run the verb's own `--help` to see the flag declared, or try it — a verb that cannot honour it says so immediately, before any document is opened.
+
 `decrypt` round-trips the **page tree** byte for byte: the decoded content streams, the page dictionaries and every embedded image's raw bytes come back identical. The whole file does not, and nothing here claims it does — `/ID`, `/Encrypt`, the trailer, the cross-reference table and object numbering all legitimately change on any resave.
 
 ## OCR and Office conversion
 
-`ocr` and `convert` are the two verbs that depend on a system binary rather than a Python wheel — the two verbs `pdftoolkit doctor` can legitimately report as unavailable.
+`ocr` and `convert` are the two verbs that depend on a system binary rather than a Python wheel — the two verbs `pdftooling doctor` can legitimately report as unavailable.
 
-`ocr` drives the **tesseract** binary. For every selected page it renders the page, recognises a text-only layer, and overlays that layer on the **original** page object — the page's own image is never re-rendered, and a byte-level check proves the image stream is identical before and after. `--skip-text-pages` leaves a page that already has extractable text untouched (no render, no OCR call). This build ships whatever tessdata language packs the host has installed; `--lang` is validated against exactly that list (`pdftoolkit doctor`), and a pack that is not installed exits 3 with an install hint naming it. No accuracy or confidence claim is made anywhere in this tool — `ocr` is described here by its engine, not by a quality promise.
+`ocr` drives the **tesseract** binary. For every selected page it renders the page, recognises a text-only layer, and overlays that layer on the **original** page object — the page's own image is never re-rendered, and a byte-level check proves the image stream is identical before and after. `--skip-text-pages` leaves a page that already has extractable text untouched (no render, no OCR call). This build ships whatever tessdata language packs the host has installed; `--lang` is validated against exactly that list (`pdftooling doctor`), and a pack that is not installed exits 3 with an install hint naming it. No accuracy or confidence claim is made anywhere in this tool — `ocr` is described here by its engine, not by a quality promise.
 
 `convert` drives headless **LibreOffice** (`soffice`) to turn an office document into a PDF. Each invocation gets its own isolated LibreOffice profile directory and converts into a private scratch location first — LibreOffice never writes to the destination directly, and the destination is only touched through this tool's one write chokepoint. An exit 0 from `soffice` having produced no output file is treated as a failure here, not a success, because that is a real and well-known LibreOffice failure mode. `--timeout` bounds one conversion; on expiry the whole process group is killed, so no `soffice.bin` daemon is left running.
 
@@ -198,4 +251,4 @@ If a sweep ever records nothing open, this section still stands and reads *no op
 
 ## License
 
-Apache-2.0 — see `LICENSE` and `NOTICE`. `THIRD_PARTY_LICENSES` is generated from the resolved environment and ships in both the sdist and the wheel.
+Apache-2.0 — see `LICENSE` and `NOTICE`. `THIRD_PARTY_LICENSES` is generated from the resolved environment and ships in both the sdist and the wheel. `pdftk` is GPL-licensed; this project is **Apache-2.0**, and its engine policy forbids anything under AGPL, GPL or LGPL from appearing as an import, an optional extra, or a `subprocess` fallback.