Skip to content

v1.2.0 — pdfnative 1.5.0: page-tree (merge/split/extract), annotations, bookmarks, math font, native crypto & AI-governance (HITL)

Choose a tag to compare

View all tags
@Nizoka Nizoka released this 06 Jul 19:02
· 6 commits to main since this release
v1.2.0
df5eb40
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

pdfnative-cli v1.2.0

Released 2026-07-06

v1.2.0 lands the pdfnative 1.5.0 engine's page-tree and annotation APIs
on the CLI as five new commands, adds document bookmarks, a math font, layout
introspection, native constant-time signing, and — for autonomous agents —
surfaces pdfnative's AI-governance / Human-in-the-Loop (HITL) contract.

New commands: merge (concatenate PDFs), split (one PDF → many,
per-page or per-range), extract (pull selected pages), annotate
(attach markup annotations with an incremental save — signatures stay intact),
and govern (rules / policy / verify-issue). render gains PDF
bookmarks (--outline), a bundled math font (--font math), and layout
introspection (--inspect-layout / --debug-layout). sign now uses native
node:crypto for constant-time signatures by default (--pure-crypto opts
out). inspect reports page labels and lists markup/link annotations
(--annotations). Adds the stable E_POLICY error code.

100% backward-compatible with v1.1.0 — every existing invocation keeps working.

⭐ Star pdfnative — the
zero-dependency PDF engine that powers this CLI. Every star helps the
long-term project.

Highlights

  • Page-tree operations. merge, split, and extract expose pdfnative
    1.5.0's mergePdfs / splitPdf / extractPages. All three honour
    --drop-annotations and a --max-output-size guard, validate every path
    against traversal, and bounds-check page references.
  • Markup annotations. annotate --annotations <spec.json> attaches
    highlight / text / underline / strikeout / squiggly / square / circle / line /
    freetext annotations via an incremental save, so the original bytes — and
    any existing signature — stay intact. Only known fields are forwarded (no
    dictionary injection).
  • AI-governance / HITL. govern makes pdfnative's monorepo governance model
    actionable: agents are draftsmen, never autonomous submitters.
    govern verify-issue gates a local draft (exit 1 / E_POLICY on a violation)
    before a human reviews and submits it. Fully offline.
  • PDF bookmarks. render --outline auto derives a bookmark tree from the
    document's headings; --outline <tree.json> supplies an explicit
    OutlineItem[] tree.
  • Math & layout tooling. render --font math registers the bundled Noto
    Sans Math font; --inspect-layout emits a LayoutInspection JSON report and
    --debug-layout overlays margin/content/cell guides.
  • Native constant-time signing. sign routes CMS signing through Node's
    node:crypto by default for side-channel-resistant RSA/ECDSA;
    --pure-crypto selects the portable pure-JS path.
  • Richer inspection. inspect --annotations lists markup + link
    annotations, and /PageLabels are reported automatically when present.

What's new

New commands

merge

pdfnative merge a.pdf b.pdf c.pdf --output combined.pdf

Concatenate 2–50 PDFs (positional paths and/or repeatable --input) via
mergePdfs. Flags: --output, --drop-annotations, --max-output-size,
--dry-run.

split

# One output per page (default)
pdfnative split --input report.pdf --output-dir pages/ --prefix page

# One output per comma-separated range
pdfnative split --input report.pdf --output-dir out/ --pages "1-2,3-4"

Split one PDF via splitPdf. --output-dir is required; parts are written as
<prefix>-<n>.pdf (zero-padded).

extract

pdfnative extract --input report.pdf --output cover.pdf --pages "4,1-2"

Pull selected pages via extractPages. --pages is 1-based; order is preserved
and repeats are allowed.

annotate

pdfnative annotate --input report.pdf --output annotated.pdf \
  --annotations notes.json

notes.json is a JSON array (or { "annotations": [...] }), each entry a markup
annotation plus a 1-based page. Written with an incremental save, so existing
signatures stay valid. Read them back with inspect --annotations.

govern

pdfnative govern rules                  # human/agent protocol (AGENT_RULES)
pdfnative govern policy --json          # machine-readable policy JSON
pdfnative govern verify-issue draft.md  # gate a draft (exit 1 / E_POLICY)

Agents act as draftsmen: a human must always review and submit under their
own GitHub identity. verify-issue fails a draft that proposes an external
runtime dependency or omits a reproduction code block; missing recommended
fields are surfaced as warnings. A passing check is necessary but not
sufficient — the human review gate always applies.

render

  • --outline auto | <tree.json> — add a navigable PDF bookmark tree
    (/Outlines). auto derives it from headings; a file supplies an explicit
    OutlineItem[].
  • --font math — register the bundled Noto Sans Math font; pdfnative
    auto-routes math-operator / geometric-shape code points to it.
  • --inspect-layout — emit a LayoutInspection JSON report (per-page
    blocks, positions, sizes) instead of a PDF (document variant only).
  • --debug-layout [margins,content,cells] — render a normal PDF with layout
    debug guides overlaid.

sign

  • Native node:crypto by default — constant-time, side-channel-resistant
    RSA/ECDSA signing via createNativeCryptoProvider. Pass --pure-crypto to
    force pdfnative's portable pure-JS bignum path.

inspect

  • --annotations — list markup and link annotations per page.
  • Page labels — the /PageLabels number tree is reported automatically when
    present.

Agent / governance

  • E_POLICY stable error code for governance-gate failures.
  • schema gains annotate (annotation-spec input) and govern-verify
    ({ ok, errors, warnings }) subjects. --dry-run now also covers merge /
    split / extract / annotate.
  • New governance files: .github/ai-governance.json, .github/AGENT_RULES.md,
    .github/drafts/README.md — mirrored by the govern command.

Compatibility

  • Built on pdfnative ^1.5.0 (was ^1.3.0).
  • Node.js ≥ 20, Bun, Deno (node dist/cli.cjs).
  • Zero extra runtime dependencies — pdfnative remains the sole dependency.
  • 100% backward-compatible with v1.1.0.

Security

  • npm audit clean — added js-yaml ^4.3.0 and vite ^8.0.16 overrides to
    resolve two transitive dev-only advisories (0 vulnerabilities).
  • merge / split / extract / annotate validate every path (incl. merge
    positionals and --output-dir) against traversal, cap output via
    --max-output-size, and bounds-check page references. annotate re-keys only
    known annotation fields — no dictionary injection.
  • govern verify-issue is a pure, fully offline validator — no GitHub or network
    access.
  • Native node:crypto signing is constant-time; key material is never logged.

Notes

  • Sign-side LTV (embedding timestamps / /DSS at signing time) remains
    upstream-blocked in pdfnative; sign --timestamp stays reserved and errors
    clearly. See ROADMAP.md and SECURITY.md.
  • The govern command adds no network surface — it only prints the policy /
    rules and validates local drafts. The CLI stays offline by default.
Assets 3
Loading