bidi2pdf 0.1.15 → 0.1.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36afd0d1f8c64ff6d72a8051785d3f65a7efcb336c07e1a6756b772ff4f17414
-  data.tar.gz: 6ecddfbacf09de3757b65009e1c41ca3cb90b8667d2fe80972200159d9f0c2b3
+  metadata.gz: b879e9c84ccd1584f5b2eb1b406972624cd8b64a50c92466e78f7275ef229441
+  data.tar.gz: 50d517dac875995c2a06ca39dcd8c521c0b18fd238b6950d5e0d9674187941dd
 SHA512:
-  metadata.gz: '0490c1e9e84467c4437eaf65128cf9adddac4509a66e7e41a791f10cb5fee6ee86d5fb821177af022a04a41441c6c57a37e8015e6a288c5e6838ecbc966bb628'
-  data.tar.gz: 935185356734aded9f38453cb2e6340501d1f99c482ffc17d62201867dd95224fe7018dfc079cfbdeed72ea44c63233fb5769987ddaa339ed7425ee6b0e281f5
+  metadata.gz: 7fca9af905a088093ff4c8ac3a1c78b4f6138068c27ad4cf87616c7ded67f44b3d57aab73b40d83b6c9d8d63097f2851b10f5b0531a91bc22088ec15aab21769
+  data.tar.gz: 835727303208ada398c0ec7456e29d49201d2b798a34edac35007c40ae5123e2a382a6e325e978237fd328ef0d58e6f573d61b1447df54bae51f9188775ab4c6

data/.rubocop.yml

@@ -1,6 +1,17 @@
+# Keep RuboCop's own default excludes (vendor/**, tmp/**, node_modules/**, .git/**) when adding to
+# AllCops/Exclude below - without this, a project-level Exclude replaces them and vendor/bundle gets
+# linted.
+inherit_mode:
+  merge:
+    - Exclude
+
 AllCops:
   NewCops: enable
   TargetRubyVersion: 3.4
+  Exclude:
+    # Local Claude devbox (gitignored). Its Dockerfile.ruby ends in ".ruby", which RuboCop takes for
+    # a Ruby source file and then fails to parse.
+    - 'docker-claude/**/*'
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes
@@ -79,6 +90,15 @@ RSpec/DescribeClass:
   Exclude:
     - 'spec/acceptance/**/*_spec.rb'
 
+# Matches bidi2pdf-rails' own spec/rails_helper.rb: scenario/when_ are custom
+# alias_example_group_to groups there (and here, see spec/spec_helper.rb), not the single example
+# Capybara's own `scenario` conventionally means - this cop doesn't know that and miscounts every
+# then_/and_ nested underneath as belonging to one example.
+RSpec/MultipleExpectations:
+  Enabled: true
+  Exclude:
+    - 'spec/acceptance/**/*_spec.rb'
+
 plugins:
   - rubocop-rake
   - rubocop-rspec

data/CHANGELOG.md

@@ -8,10 +8,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.15..HEAD
+[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.17..HEAD
 
 <!-- generated by git-cliff end -->
 
+## [0.1.17] - 2026-09-29
+
+### 🐛 Fixed
+- Let Chromium start on a read-only root
+- Do not raise when our own close ends a write
+
+### 📝 Docs
+- Describe latest as the newest Chromium build
+
+### 🔄 Changed
+- Merge pull request #143 from dieter-medium/feat/chromedriver-sha-tags
+- Merge pull request #140 from dieter-medium/fix/chromium-read-only-root
+- Merge pull request #139 from dieter-medium/fix/websocket-close-during-write
+- Merge pull request #138 from dieter-medium/feat/session-warmer-orphan-sweep
+- Merge pull request #132 from dieter-medium/dependabot/bundler/main/rubyzip-3.6.0
+
+### 🔧 Build
+- Update rubyzip requirement from ~> 2.4 to >= 2.4, < 4.0
+
+### 🚀 Added
+- Tag every chromedriver image build by commit
+- Close leftover warm sessions on start
+
+## [0.1.16] - 2026-09-22
+
+### 🐛 Fixed
+- Give NavigationDNSError its own initializer
+- Enforce the complete recipe shape in --validate, not just semantic checks
+- Close schema/validator mismatches in recipe schema
+- Document and address blank PDFs from Chrome's network checks
+- Add browser tab cookie integration specs
+
+### 🔄 Changed
+- Merge pull request #134 from dieter-medium/feat/llm-friendly-cli
+- Merge pull request #133 from dieter-medium/feat/llm-friendly-cli
+- Merge pull request #131 from dieter-medium/docs/local-network-access
+- Merge pull request #130 from dieter-medium/fix/host-only-cookie-domain
+- Merge pull request #126 from dieter-medium/chore-fix-release-creds-check
+
+### 🚀 Added
+- Agent-friendly CLI - structured JSON, diagnose, and recipes
+
 ## [0.1.15] - 2026-09-20
 
 ### 🎨 Refactored
@@ -453,7 +495,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 🔄 Released
 
-- [unreleased](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.15..HEAD)
+- [unreleased](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.17..HEAD)
+- [0.1.17](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.16..v0.1.17)
+- [0.1.16](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.15..v0.1.16)
 - [0.1.15](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.14..v0.1.15)
 - [0.1.14](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.13..v0.1.14)
 - [0.1.13](https://github.com/dieter-medium/bidi2pdf/compare/v0.1.12..v0.1.13)

data/README.md

@@ -20,16 +20,17 @@ Bidi2pdf gives you **precision, flexibility, and full control**.
 3. [Why BiDi?](#why-bidi-instead-of-cdp)
 4. [Installation](#installation)
 5. [CLI Usage](#cli-usage)
-6. [Library API](#library-api)
-7. [Architecture](#architecture)
-8. [Docker](#docker)
-9. [Configuration Options](#configuration-options)
-10. [Programmatic Configuration](#programmatic-configuration)
-11. [Rails Integration](#rails-integration)
-12. [Test Helpers](#test-helpers)
-13. [Development](#development)
-14. [Contributing](#contributing)
-15. [License](#license)
+6. [Agent and Automation Usage](#agent-and-automation-usage)
+7. [Library API](#library-api)
+8. [Architecture](#architecture)
+9. [Docker](#docker)
+10. [Configuration Options](#configuration-options)
+11. [Programmatic Configuration](#programmatic-configuration)
+12. [Rails Integration](#rails-integration)
+13. [Test Helpers](#test-helpers)
+14. [Development](#development)
+15. [Contributing](#contributing)
+16. [License](#license)
 
 ## ✨ Key Features
 
@@ -40,7 +41,9 @@ Bidi2pdf gives you **precision, flexibility, and full control**.
 ✅ **Docker-ready** – Plug and play with containers  
 ✅ **Modern architecture** – Built on Chrome's next-gen BiDi protocol  
 ✅ **Network logging** – Know which requests fail during rendering  
-✅ **Console log capture** – See what goes wrong inside the browser
+✅ **Console log capture** – See what goes wrong inside the browser  
+✅ **Agent-ready** – Structured JSON output, NDJSON progress streaming, a page diagnostic, and
+declarative recipes, so LLM agents and CI can drive it without parsing logs
 
 ---
 
@@ -109,6 +112,152 @@ bidi2pdf render \
 
 ---
 
+## 🤖 Agent and Automation Usage
+
+Every command below also works without `--json` (human-readable output on stdout); with it, stdout
+carries exactly one JSON document and nothing else - safe to pipe into `jq` or parse directly.
+Human-readable logs move to stderr for the duration of any `--json`/`--output -` call, never
+mixing into stdout. `--json-stream` works independently of the two: it always writes progress
+events to stderr, whether or not `--json` is also given - in human mode, that just means
+human-readable output keeps going to stdout as usual, alongside the stream. Full JSON Schema for
+every shape is built into the gem, so an agent can discover it without reading this file:
+
+```bash
+# 1. Check compatibility first - no browser launched
+bidi2pdf version --json
+
+# 2. Discover the shape of each command's own result, a manifest, an NDJSON event, or a recipe file
+bidi2pdf schema render
+bidi2pdf schema diagnose
+bidi2pdf schema run
+bidi2pdf schema manifest
+bidi2pdf schema event
+bidi2pdf schema recipe
+
+# 3. Validate a recipe - no browser launched, the cheapest way to iterate on one
+bidi2pdf run recipe.yml --validate
+
+# 4. Run it for real
+bidi2pdf run recipe.yml --json
+```
+
+### Structured render output
+
+```bash
+bidi2pdf render --url https://example.com/invoice/14432423 --output example.pdf --json
+```
+
+```json
+{
+  "schema_version": 1,
+  "ok": true,
+  "command": "render",
+  "output": "example.pdf",
+  "bytes": 182734,
+  "sha256": "abcd...",
+  "pages": 2,
+  "duration_ms": 842,
+  "navigation": { "requested_url": "https://example.com/invoice/14432423", "final_url": "https://example.com/invoice/14432423", "status": 200 },
+  "console": [],
+  "network_failures": [],
+  "warnings": [],
+  "error": null
+}
+```
+
+`pages` is `null`, with a warning explaining why, when the optional `pdf-reader` gem isn't
+installed - see [Docker](#docker) for why the published images always have it. A failed render
+still emits exactly this shape, with `ok: false` and a structured `error` (`code`, `message`,
+`retryable`, `hint`, `details`) instead of a stack trace:
+
+| Exit code | Meaning |
+|---|---|
+| `0` | success |
+| `2` | CLI, configuration, or recipe-validation error |
+| `3` | browser or navigation error |
+| `4` | page not as expected (a recipe action/assertion, or a diagnose selector, failed) |
+| `6` | output or PDF generation failure |
+| `70` | unexpected internal error |
+
+### stdin/stdout, manifests, and progress streaming
+
+```bash
+# Render HTML piped on stdin, PDF bytes piped out on stdout - no files touched
+cat page.html | bidi2pdf render --stdin --output - > page.pdf
+
+# A render manifest: enough to reproduce and diagnose the render later
+bidi2pdf render --url https://example.com --output example.pdf --manifest render.json
+
+# One JSON progress event per stderr line as the render happens - works with human-readable
+# output too, not just --json
+bidi2pdf render --url https://example.com --output example.pdf --json-stream
+```
+
+### Diagnosing a page before trusting its PDF
+
+`bidi2pdf diagnose` loads a page like `render` does but produces no PDF - it answers *why does the
+PDF not look like the page* (console errors, failed requests, font-loading status, `@media
+print`/`@page` rules, fixed/sticky elements, Paged.js detection), not what the page's content is:
+
+```bash
+bidi2pdf diagnose --url https://example.com/invoice/14432423 --json
+```
+
+### Declarative recipes
+
+A recipe is a rendering contract - the waits a page needs before it's printed, and the properties
+the resulting PDF must have - not a general browser-automation script:
+
+```yaml
+# invoice.yml
+version: 1
+
+source:
+  url: https://example.com/invoice/123
+
+actions:
+  - wait_for:
+      selector: "#invoice"
+      timeout: 10
+  - click:
+      selector: "#show-details"
+  - wait_network_idle:
+      timeout: 10
+
+assert:
+  - selector_exists:
+      selector: "#total"
+  - no_console_errors: true
+  - page_count: 2
+  - pdf_text_present:
+      text: "Invoice #123"
+
+output:
+  pdf: invoice.pdf
+  manifest: invoice.json
+```
+
+```bash
+bidi2pdf run invoice.yml --validate   # schema + known actions/assertions, no browser
+bidi2pdf run invoice.yml --json       # actions, then the PDF, then assertions against it
+```
+
+Actions (`wait_for`, `click`, `evaluate`, `inject_script`, `inject_style`, `set_viewport`,
+`wait_network_idle`) and page assertions (`selector_exists`, `text_present`, `no_console_errors`,
+`no_network_failures`, `fonts_loaded`) are a thin layer over the same `BrowserTab` methods the
+[Programmatic API](#-programmatic-api) below uses directly. PDF assertions (`page_count`,
+`pdf_text_present`, `pdf_not_blank`) need the `pdf-reader` gem - a recipe using one fails
+`--validate` immediately, before any browser launches, when it isn't installed.
+
+`no_console_errors`, `no_network_failures`, `fonts_loaded`, and `pdf_not_blank` are presence-only
+assertions - the step is either there or it isn't, nothing reads the value beside it - so they must
+be written as `true` exactly, e.g. `- no_console_errors: true`; `false` (or any other value) is
+rejected by both `bidi2pdf schema recipe` and `--validate` rather than being silently ignored.
+`wait_for` needs exactly one of `selector`, `paged_js`, `script` - zero or more than one is
+rejected the same way, before any browser launches.
+
+---
+
 ## 🧠 Programmatic API
 
 ### Classic Approach
@@ -286,6 +435,30 @@ docker run -it --rm \
 
 ✅ Tip: Mount your local directory (e.g. ./output) to /reports in the container to easily access the generated PDFs.
 
+✅ All images run with a read-only root filesystem (`--read-only`) as long as `/tmp` is writable,
+e.g. `--tmpfs /tmp`: they point Chromium's `XDG_CONFIG_HOME`/`XDG_CACHE_HOME` there, without
+which Chromium's crash handler fails to start and every launch aborts with
+`chrome_crashpad_handler: --database is required`.
+
+✅ Both published images also install [`pdf-reader`](https://github.com/yob/pdf-reader) - not a
+runtime dependency of the gem itself (see [Agent and Automation Usage](#agent-and-automation-usage)) -
+so `pages` and the `page_count`/`pdf_text_present`/`pdf_not_blank` recipe assertions work out of
+the box in either image, no extra install step needed.
+
+### ChromeDriver image tags
+
+[`dieters877565/chromedriver`](https://hub.docker.com/r/dieters877565/chromedriver) is built for
+`linux/amd64` and `linux/arm64` with these tags:
+
+| Tag | Moves? | Use |
+|---|---|---|
+| `0.1.17` (a release) | no | a fixed Chromium, pinned together with the gem version |
+| `sha-<short commit>` | only if that commit is built again by hand | a fix on `main` not released yet |
+| `latest`, `main` | yes, every push to `main` | the newest build and its Chromium security fixes |
+
+Chromium comes from Debian's packages at build time, so every build can carry a different
+Chromium - for a byte-exact pin use the digest (`docker buildx imagetools inspect <image:tag>`).
+
 ### Docker Compose
 
 ```bash
@@ -332,6 +505,15 @@ docker compose -f docker/docker-compose.yml down
 | `--log_level`          | Log level: debug, info, warn, error, fatal |
 | `--remote_browser_url` | Connect to remote Chrome session           |
 | `--default_timeout`    | Operation timeout (default: 60s)           |
+| `--json`                | Emit a single structured JSON result document (see `bidi2pdf schema render`) |
+| `--json_stream`         | Emit one JSON progress event per line to stderr (see `bidi2pdf schema event`) - works with or without `--json` |
+| `--stdin`               | Read the HTML document from stdin, instead of `--url`/`--html-file`         |
+| `--output -`            | Write raw PDF bytes to stdout instead of a file                             |
+| `--manifest FILE`       | Write a render manifest (see `bidi2pdf schema manifest`) to `FILE`          |
+
+See [Agent and Automation Usage](#agent-and-automation-usage) above for `bidi2pdf diagnose`,
+`bidi2pdf run recipe.yml`, `bidi2pdf schema <kind>`, and `bidi2pdf version --json` - a separate
+set of commands with their own options, not additional flags on `render`.
 
 ---
 
@@ -388,6 +570,24 @@ Bidi2pdf::SessionWarmer.shutdown
 | `headless`           | `true`                | Run Chrome headless.                                                                                      |
 | `chrome_args`        | `DEFAULT_CHROME_ARGS` | Chrome launch arguments.                                                                                  |
 | `remote_browser_url` | `nil`                 | Connect each slot to a remote chromedriver instead of starting a local one.                               |
+| `orphan_age`         | `:auto`               | Remote only: on start, close sessions other warmers left behind older than this (`:auto` = 2 × `max_idle_age`, `nil` = off). |
+| `registry_dir`       | `Dir.tmpdir`          | Where the session registry file lives - every process that should clean up after the others must share it. |
+
+#### Leftover sessions on a shared chromedriver
+
+A remote chromedriver keeps a session - a whole Chrome - until someone deletes it. A warmer closes
+its own sessions when they idle past `max_idle_age` and when the process shuts down cleanly, but a
+process that is killed or crashes leaves its sessions open, and enough of them stop the container
+from starting any new Chrome. So in remote mode each warmer records the sessions it opens in a small
+registry file (`<registry_dir>/bidi2pdf-sessions-<hash of the URL>.json`, mode 0600), and on start
+closes recorded sessions older than `orphan_age`. The default, twice `max_idle_age`, is beyond the
+point where any live warmer would already have recycled its own spare, so a running process never
+loses one. Sessions nobody recorded (other tools on the same chromedriver) are never touched.
+chromedriver drops custom capabilities, so a session cannot carry a tag of its own - hence the file.
+
+Everything here is fail-open: if the registry directory is not writable, the warmer logs one
+warning, instruments `session_warmer.registry_unavailable.bidi2pdf`, and keeps rendering - only the
+cleanup is off. Closed leftovers are reported as `session_warmer.orphans_closed.bidi2pdf`.
 
 > **Security note:** an idle warm session is an open, unauthenticated automation endpoint
 > (chromedriver's port, Chrome's debugging port - loopback only for a local chromedriver) for as
@@ -395,6 +595,28 @@ Bidi2pdf::SessionWarmer.shutdown
 > nothing else can reach those ports. With `remote_browser_url`, who can reach that endpoint on the
 > network is what matters, exactly as it does without the warmer.
 
+### Customizing Chrome arguments (and blank PDFs from inline HTML)
+
+`Bidi2pdf::Bidi::Session::DEFAULT_CHROME_ARGS` already contains one `--disable-features=...` entry,
+and Chrome only honors the **last** occurrence of that switch. To turn another feature off, extend
+that entry instead of appending a second switch, which would silently drop the defaults:
+
+```ruby
+chrome_args = Bidi2pdf::Bidi::Session::DEFAULT_CHROME_ARGS.map do |arg|
+  arg.start_with?("--disable-features=") ? "#{arg},LocalNetworkAccessChecks" : arg
+end
+```
+
+`LocalNetworkAccessChecks` is the one you are most likely to need. HTML rendered through
+`BrowserTab#render_html_content` is loaded as a `data:` URL, which Chrome treats as a public origin;
+if that HTML references assets on a private address (`localhost`, a Docker hostname, ...), recent
+Chrome versions (confirmed with Chrome 153) block those requests before they are sent. Nothing
+raises - the assets show up as failed network events, the server never sees a request, and the PDF
+comes out unstyled or blank. Disable the check only where the asset host really is private, and keep
+it on when rendering pages you do not control.
+The [bidi2pdf-rails README](https://github.com/dieter-medium/bidi2pdf-rails#readme) has the full
+walkthrough under "Blank PDFs: Chrome's Local Network Access Check".
+
 ---
 
 ## 🚂 Rails Integration

data/docker/Dockerfile

@@ -34,10 +34,21 @@ WORKDIR /app
 # Copy your gem into container
 COPY ./pkg/bidi2pdf-*.gem ./
 
+# pdf-reader is deliberately not a bidi2pdf runtime dependency - it is installed here, as its own
+# step, so the published image always has `pages`/PDF assertions available, the environment an
+# agent or CI job actually renders in.
 RUN gem install ./bidi2pdf-*.gem && \
+    gem install pdf-reader -v "~> 2.14" && \
     chown -R appuser:appuser /app
 
 # Switch to non-root user
+# Chromium's crash handler gets its database path from the XDG config dir. On a read-only root
+# (docker run --read-only) that dir cannot be created, the handler refuses to start
+# ("--database is required") and Chrome aborts on every launch. /tmp is the one place such a
+# container is expected to mount writable (--tmpfs /tmp).
+ENV XDG_CONFIG_HOME=/tmp/xdg-config \
+    XDG_CACHE_HOME=/tmp/xdg-cache
+
 USER appuser
 
 CMD ["/usr/bin/bash"]

data/docker/Dockerfile.chromedriver

@@ -53,6 +53,13 @@ WORKDIR /app
 RUN mkdir -p /tmp/.X11-unix && chmod 1777 /tmp/.X11-unix
 
 # Switch to non-root user
+# Chromium's crash handler gets its database path from the XDG config dir. On a read-only root
+# (docker run --read-only) that dir cannot be created, the handler refuses to start
+# ("--database is required") and Chrome aborts on every launch. /tmp is the one place such a
+# container is expected to mount writable (--tmpfs /tmp).
+ENV XDG_CONFIG_HOME=/tmp/xdg-config \
+    XDG_CACHE_HOME=/tmp/xdg-cache
+
 USER appuser
 
 # RUN gem install chromedriver-binary && ruby -e 'require "chromedriver/binary"; puts Chromedriver::Binary::ChromedriverDownloader.update'

data/docker/Dockerfile.slim

@@ -26,7 +26,11 @@ WORKDIR /app
 # Copy your gem into container
 COPY ./pkg/bidi2pdf-*.gem ./
 
-RUN gem install ./bidi2pdf-*.gem
+# pdf-reader is deliberately not a bidi2pdf runtime dependency - it is installed here, as its own
+# step, so the published image always has `pages`/PDF assertions available, the environment an
+# agent or CI job actually renders in.
+RUN gem install ./bidi2pdf-*.gem && \
+    gem install pdf-reader -v "~> 2.14"
 
 
 # Stage 2
@@ -69,6 +73,13 @@ WORKDIR /app
 RUN chown -R appuser:appuser /app
 
 # Switch to non-root user
+# Chromium's crash handler gets its database path from the XDG config dir. On a read-only root
+# (docker run --read-only) that dir cannot be created, the handler refuses to start
+# ("--database is required") and Chrome aborts on every launch. /tmp is the one place such a
+# container is expected to mount writable (--tmpfs /tmp).
+ENV XDG_CONFIG_HOME=/tmp/xdg-config \
+    XDG_CACHE_HOME=/tmp/xdg-cache
+
 USER appuser
 
 CMD ["/usr/bin/bash"]

data/lib/bidi2pdf/bidi/buffered_web_socket_client.rb

@@ -92,8 +92,17 @@ module Bidi2pdf
         @listeners_mutex.synchronize { @listeners[event].dup }.each { |listener| listener.call(*) }
       end
 
+      # The reader closes the socket from its own thread when the peer hangs up, and #close does not
+      # wait for a write in flight - so a write can fail with "stream closed in another thread" (or
+      # EPIPE) because *we* closed it. By then the connection is over and :close has been emitted;
+      # there is nothing left to report. Seen in the handshake write of #connect, which had no
+      # rescue: a server that answered and hung up at once made #connect raise although the
+      # handshake went through. Any other write failure still raises (#send and #say_goodbye
+      # handle it).
       def write(bytes)
         @write_mutex.synchronize { @socket&.write bytes }
+      rescue IOError, SystemCallError, OpenSSL::SSL::SSLError
+        raise unless @closed
       end
 
       def say_goodbye

data/lib/bidi2pdf/bidi/session.rb

@@ -74,6 +74,10 @@ module Bidi2pdf
       # @return [Array<String>] The Chrome arguments for the session.
       attr_reader :chrome_args
 
+      # @return [String, nil] chromedriver's id for this session, once it was created - what
+      #   SessionWarmer records so a later process can close it if this one dies uncleanly.
+      attr_reader :session_id
+
       # Initializes a new session.
       #
       # @param [String] session_url The URL for the session.
@@ -227,7 +231,7 @@ module Bidi2pdf
         value = session_data["value"]
         handle_error(value) if value.nil? || value["error"]
 
-        session_id = value["sessionId"]
+        @session_id = value["sessionId"]
         ws_url = value["capabilities"]["webSocketUrl"]
 
         Bidi2pdf.logger.info "Created session with ID: #{session_id}"

data/lib/bidi2pdf/cli/json_output.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  class CLI < Thor
+    # Shared machinery for --json/--json-stream/--output - across render/diagnose/run: reserving
+    # stdout for exactly one machine-readable payload, and mapping a Result to a process exit
+    # status.
+    module JsonOutput
+      private
+
+      # Bidi2pdf.logger (and friends) default to $stdout (see lib/bidi2pdf.rb), so a
+      # --json/--output - render has to redirect them for its duration or every log line would
+      # land in the same stream as the JSON document / PDF bytes it is trying to keep pure.
+      # Logger#reopen swaps the destination in place, so nothing else holding a reference to
+      # these loggers needs to know.
+      def reserve_stdout_for_machine_output
+        loggers = [Bidi2pdf.logger, Bidi2pdf.network_events_logger, Bidi2pdf.browser_console_logger].compact
+        loggers.each { |logger| logger.logger.reopen($stderr) }
+
+        yield
+      ensure
+        loggers.each { |logger| logger.logger.reopen($stdout) }
+      end
+
+      def exit_for_result(result)
+        exit(result.ok? ? Bidi2pdf::ExitCodes::SUCCESS : Bidi2pdf::ExitCodes.for(result.error[:code]))
+      end
+    end
+  end
+end