bidi2pdf 0.1.14 → 0.1.16

data/lib/bidi2pdf/diagnose.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Bidi2pdf
+  # Collects the render-focused diagnostics behind `bidi2pdf diagnose`: why does the PDF not look
+  # like the page, not what the page's content is. Everything here reuses
+  # BrowserTab#execute_script - no DOM dump, no headings/links/forms extraction; console and
+  # network data come from the caller's own
+  # ResultCollector, the same source `render` uses, not from here.
+  #
+  # Each script returns (or resolves to) a JSON string, extracted via #dig("result", "value") -
+  # BiDi's script.evaluate already awaits a returned Promise (awaitPromise: true, see
+  # Commands::ScriptEvaluate), so document.fonts.ready needs no wrap_in_promise: wrapper.
+  class Diagnose
+    PAGE_SCRIPT = <<~JS
+      JSON.stringify({
+        title: document.title,
+        url: window.location.href,
+        lang: document.documentElement.lang || null
+      })
+    JS
+
+    FONTS_SCRIPT = <<~JS
+      document.fonts.ready.then(function () {
+        var loaded = [];
+        var failed = [];
+        document.fonts.forEach(function (face) {
+          var label = face.family + " " + face.weight + " " + face.style;
+          if (face.status === "error") { failed.push(label); } else { loaded.push(label); }
+        });
+        return JSON.stringify({ status: failed.length > 0 ? "partial" : "loaded", loaded: loaded, failed: failed });
+      })
+    JS
+
+    PRINT_MEDIA_SCRIPT = <<~JS
+      (function () {
+        var printSheets = [];
+        var pageRules = [];
+        var unreadable = [];
+
+        for (var i = 0; i < document.styleSheets.length; i++) {
+          var sheet = document.styleSheets[i];
+          try {
+            var rules = sheet.cssRules || sheet.rules;
+            for (var j = 0; j < rules.length; j++) {
+              var rule = rules[j];
+              if (rule.media && Array.prototype.includes.call(rule.media, "print")) {
+                printSheets.push(sheet.href || "(inline)");
+              }
+              if (typeof CSSRule !== "undefined" && rule.type === CSSRule.PAGE_RULE) {
+                pageRules.push(rule.cssText);
+              }
+            }
+          } catch (e) {
+            unreadable.push(sheet.href || "(inline)");
+          }
+        }
+
+        var fixedOrSticky = [];
+        var breakInsideAvoidCount = 0;
+        var elements = document.querySelectorAll("body *");
+        for (var k = 0; k < elements.length; k++) {
+          var el = elements[k];
+          var computed = window.getComputedStyle(el);
+          if (computed.position === "fixed" || computed.position === "sticky") {
+            var classPart = typeof el.className === "string" && el.className.trim() ? "." + el.className.trim().split(/\\s+/).join(".") : "";
+            var selector = el.id ? "#" + el.id : el.tagName.toLowerCase() + classPart;
+            fixedOrSticky.push({ selector: selector, position: computed.position });
+          }
+          if (computed.breakInside === "avoid" || computed.pageBreakInside === "avoid") {
+            breakInsideAvoidCount++;
+          }
+        }
+
+        return JSON.stringify({
+          stylesheets_with_print_rules: Array.from(new Set(printSheets)),
+          page_rules: pageRules,
+          break_inside_avoid_count: breakInsideAvoidCount,
+          fixed_or_sticky_elements: fixedOrSticky,
+          unreadable_stylesheets: Array.from(new Set(unreadable))
+        });
+      })()
+    JS
+
+    PAGED_JS_SCRIPT = <<~JS
+      (function () {
+        var detected = !!(window.Paged || window.PagedPolyfill);
+        var pages = document.querySelectorAll(".pagedjs_page").length;
+        return JSON.stringify({ detected: detected, ready: pages > 0, pages: pages });
+      })()
+    JS
+
+    def initialize(tab:)
+      @tab = tab
+    end
+
+    def call
+      {
+        page: collect(PAGE_SCRIPT),
+        fonts: collect(FONTS_SCRIPT),
+        print_media: collect(PRINT_MEDIA_SCRIPT),
+        paged_js: collect(PAGED_JS_SCRIPT)
+      }
+    end
+
+    private
+
+    def collect(script)
+      response = @tab.execute_script(script)
+      return nil unless response.is_a?(Hash) && response["type"] == "success"
+
+      value = response.dig("result", "value")
+      value ? JSON.parse(value) : nil
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/bidi2pdf/error_codes.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  # Maps an exception to the stable, machine-readable code used by --json/--json-stream/manifests
+  # and recipe results. Derived from the existing Bidi2pdf::Error hierarchy rather than duplicated
+  # beside it: a new failure mode gets a new subclass in lib/bidi2pdf.rb and a row here, never a
+  # bare string minted ad hoc.
+  #
+  # MAPPING is ordered most-specific-subclass first - #for walks it in order and returns the first
+  # match, so a subclass must appear before any of its ancestors.
+  module ErrorCodes
+    MAPPING = {
+      MissingInputError => "MISSING_INPUT",
+      MultipleInputSourcesError => "MULTIPLE_INPUT_SOURCES",
+      EmptyInputError => "EMPTY_INPUT",
+      InvalidConfigError => "INVALID_CONFIG",
+      InvalidPrintOptionError => "INVALID_PRINT_OPTION",
+      InvalidRecipeError => "INVALID_RECIPE",
+      PdfInspectionUnavailableError => "PDF_INSPECTION_UNAVAILABLE",
+      SessionNotStartedError => "BROWSER_LAUNCH_FAILED",
+      CmdTimeoutError => "COMMAND_TIMEOUT",
+      WebsocketError => "BROWSER_DISCONNECTED",
+      NavigationTimeoutError => "NAVIGATION_TIMEOUT",
+      NavigationAuthError => "NAVIGATION_AUTH",
+      NavigationNotFoundError => "NAVIGATION_NOT_FOUND",
+      NavigationDNSError => "DNS_ERROR",
+      NavigationError => "NAVIGATION_FAILED",
+      SelectorNotFoundError => "SELECTOR_NOT_FOUND",
+      PageNotAsExpectedError => "PAGE_NOT_AS_EXPECTED",
+      ScriptInjectionError => "SCRIPT_ERROR",
+      StyleInjectionError => "STYLE_ERROR",
+      PrintError => "PDF_GENERATION_FAILED",
+      ScreenshotError => "SCREENSHOT_FAILED",
+      OutputWriteError => "OUTPUT_WRITE_FAILED",
+      Error => "INTERNAL_ERROR"
+    }.freeze
+
+    DEFAULT_CODE = "INTERNAL_ERROR"
+
+    def self.for(exception)
+      _klass, code = MAPPING.find { |klass, _code| exception.is_a?(klass) }
+
+      code || DEFAULT_CODE
+    end
+
+    # Builds the {code:, message:, retryable:, hint:, details:} hash used as Result#error and in
+    # recipe action/assertion failures. Works for any StandardError, not only a Bidi2pdf::Error -
+    # an unexpected exception still gets INTERNAL_ERROR with retryable/hint defaulted safely.
+    def self.describe(exception, details: {})
+      {
+        code: self.for(exception),
+        message: exception.message,
+        retryable: exception.respond_to?(:retryable?) ? exception.retryable? : false,
+        hint: exception.respond_to?(:hint) ? exception.hint : nil,
+        details: exception.respond_to?(:details) && !exception.details.empty? ? exception.details : details
+      }
+    end
+  end
+end

data/lib/bidi2pdf/exit_codes.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  # Maps an ErrorCodes string to the process exit status the CLI reports. Centralized here so
+  # render/diagnose/run share one table instead of each re-deciding what a given failure is worth.
+  module ExitCodes
+    SUCCESS = 0
+    CLI_ERROR = 2
+    BROWSER_ERROR = 3
+    PAGE_NOT_AS_EXPECTED = 4
+    OUTPUT_ERROR = 6
+    INTERNAL_ERROR = 70
+
+    CODE_TO_EXIT = {
+      "MISSING_INPUT" => CLI_ERROR,
+      "MULTIPLE_INPUT_SOURCES" => CLI_ERROR,
+      "EMPTY_INPUT" => CLI_ERROR,
+      "INVALID_CONFIG" => CLI_ERROR,
+      "INVALID_PRINT_OPTION" => CLI_ERROR,
+      "INVALID_RECIPE" => CLI_ERROR,
+      "PDF_INSPECTION_UNAVAILABLE" => CLI_ERROR,
+      "BROWSER_LAUNCH_FAILED" => BROWSER_ERROR,
+      "BROWSER_DISCONNECTED" => BROWSER_ERROR,
+      "COMMAND_TIMEOUT" => BROWSER_ERROR,
+      "NAVIGATION_FAILED" => BROWSER_ERROR,
+      "NAVIGATION_TIMEOUT" => BROWSER_ERROR,
+      "NAVIGATION_AUTH" => BROWSER_ERROR,
+      "NAVIGATION_NOT_FOUND" => BROWSER_ERROR,
+      "DNS_ERROR" => BROWSER_ERROR,
+      "SELECTOR_NOT_FOUND" => PAGE_NOT_AS_EXPECTED,
+      "PAGE_NOT_AS_EXPECTED" => PAGE_NOT_AS_EXPECTED,
+      "SCRIPT_ERROR" => PAGE_NOT_AS_EXPECTED,
+      "STYLE_ERROR" => PAGE_NOT_AS_EXPECTED,
+      "PDF_GENERATION_FAILED" => OUTPUT_ERROR,
+      "SCREENSHOT_FAILED" => OUTPUT_ERROR,
+      "OUTPUT_WRITE_FAILED" => OUTPUT_ERROR,
+      "INTERNAL_ERROR" => INTERNAL_ERROR
+    }.freeze
+
+    def self.for(code)
+      CODE_TO_EXIT.fetch(code, INTERNAL_ERROR)
+    end
+  end
+end

data/lib/bidi2pdf/launcher.rb

@@ -77,7 +77,30 @@ module Bidi2pdf
       runner.run
     end
 
+    # Like #launch, but navigates only (see SessionRunner#run_diagnose) and leaves the tab open -
+    # used by `bidi2pdf diagnose`, which has no PDF to produce. #stop closes it, same as it stops
+    # everything else #launch/#diagnose started.
+    #
+    # @return [Bidi2pdf::Bidi::BrowserTab] the navigated tab.
+    def diagnose
+      @diagnose_runner = SessionRunner.new(
+        session: session,
+        url: @url,
+        inputfile: @inputfile,
+        output: @output,
+        cookies: @cookies,
+        headers: @headers,
+        auth: @auth,
+        wait_window_loaded: @wait_window_loaded,
+        wait_network_idle: @wait_network_idle,
+        print_options: @print_options,
+        network_log_format: @network_log_format
+      )
+      @diagnose_runner.run_diagnose
+    end
+
     def stop
+      @diagnose_runner&.close_all
       @manager&.stop
       @custom_session&.close
     end

data/lib/bidi2pdf/manifest.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Bidi2pdf
+  # Builds the render manifest (--manifest FILE) from a completed Bidi2pdf::Result plus the
+  # input/browser/header context around it. Redacts secret-
+  # bearing headers and never records cookie values at all.
+  class Manifest
+    SCHEMA_VERSION = 1
+
+    REDACT_HEADER_NAMES = %w[authorization proxy-authorization cookie set-cookie x-api-key api-key].freeze
+    SENSITIVE_SUBSTRINGS = %w[token secret password authorization api-key apikey].freeze
+
+    def initialize(result:, input:, headers: {}, navigation_duration_ms: nil, browser: {})
+      @result = result
+      @input = input
+      @headers = headers
+      @navigation_duration_ms = navigation_duration_ms
+      @browser = browser
+    end
+
+    def self.redact(headers)
+      headers.to_h { |key, value| [key, sensitive?(key) ? "[REDACTED]" : value] }
+    end
+
+    def self.sensitive?(key)
+      normalized = key.to_s.downcase
+
+      REDACT_HEADER_NAMES.include?(normalized) || SENSITIVE_SUBSTRINGS.any? { |substring| normalized.include?(substring) }
+    end
+
+    def to_h
+      base = {
+        schema_version: SCHEMA_VERSION,
+        bidi2pdf_version: Bidi2pdf::VERSION,
+        created_at: Time.now.utc.iso8601,
+        input: @input,
+        output: output_section,
+        browser: @browser,
+        navigation: navigation_section,
+        render: { duration_ms: @result.duration_ms },
+        console: @result.console,
+        network_failures: @result.network_failures,
+        warnings: @result.warnings
+      }
+
+      @headers.empty? ? base : base.merge(headers: self.class.redact(@headers))
+    end
+
+    def to_json(*)
+      to_h.to_json(*)
+    end
+
+    private
+
+    def output_section
+      { path: @result.output, pages: @result.pages, bytes: @result.bytes, sha256: @result.sha256 }
+    end
+
+    def navigation_section
+      (@result.navigation || {}).merge(duration_ms: @navigation_duration_ms)
+    end
+  end
+end

data/lib/bidi2pdf/notifications/json_subscriber.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Bidi2pdf
+  module Notifications
+    # Emits one JSON object per line to an IO (stderr for --json-stream, docs/specs/llm-friendly-
+    # spec.md section 7) as a render progresses, by subscribing to the same Bidi2pdf::Notifications
+    # events Bidi2pdf::ResultCollector and LoggingSubscriber already use - no new instrumentation
+    # points needed. #emit_result writes the final "result" event once the caller has a Result.
+    class JsonSubscriber
+      SCHEMA_VERSION = 1
+
+      def initialize(io: $stderr)
+        @io = io
+        @start = now_ms
+        subscribe
+      end
+
+      def emit_result(result)
+        write(event: "result", result: result.to_h)
+      end
+
+      def unsubscribe
+        Array(@registered).each { |pattern, block| Bidi2pdf.notification_service.unsubscribe(pattern, block) }
+      end
+
+      private
+
+      def now_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+
+      def elapsed_ms = (now_ms - @start).round
+
+      def subscribe
+        handlers = {
+          "navigate_to.bidi2pdf" => method(:on_navigate),
+          "render_html_content.bidi2pdf" => method(:on_navigate),
+          "page_loaded.bidi2pdf" => method(:on_page_loaded),
+          "network_idle.bidi2pdf" => method(:on_network_idle),
+          "browser_console_log_received.bidi2pdf" => method(:on_console),
+          "print.bidi2pdf" => method(:on_print),
+          "screenshot.bidi2pdf" => method(:on_screenshot)
+        }
+
+        @registered = handlers.map { |pattern, handler| [pattern, Bidi2pdf.notification_service.subscribe(pattern, &handler)] }
+      end
+
+      def on_navigate(event)
+        write(event: "navigate", url: event.payload[:url])
+      end
+
+      def on_page_loaded(_event)
+        write(event: "page_loaded")
+      end
+
+      def on_network_idle(_event)
+        write(event: "network_idle")
+      end
+
+      def on_console(event)
+        payload = event.payload
+        write(event: "console", level: payload[:level], text: payload[:text])
+      end
+
+      def on_print(_event)
+        write(event: "print")
+      end
+
+      def on_screenshot(_event)
+        write(event: "screenshot")
+      end
+
+      def write(fields)
+        @io.puts({ schema_version: SCHEMA_VERSION, t_ms: elapsed_ms }.merge(fields).to_json)
+      end
+    end
+  end
+end

data/lib/bidi2pdf/notifications/logging_subscriber.rb

@@ -95,6 +95,8 @@ module Bidi2pdf
           end
         when Array
           obj.map { |item| redact_sensitive_fields(item, sensitive_keys) }
+        when String
+          Bidi2pdf.truncate_for_log(obj)
         else
           obj
         end

data/lib/bidi2pdf/pdf_inspection.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Bidi2pdf
+  # Lazy, optional wrapper around the pdf-reader gem. pdf-reader is deliberately NOT a bidi2pdf
+  # runtime dependency - render works fine without it,
+  # just with `pages` left nil and a warning, and a recipe assertion that needs it fails
+  # INVALID_RECIPE at validation time rather than crashing mid-render. The official Docker images
+  # (docker/Dockerfile, docker/Dockerfile.slim) install it, so a render inside one of them - the
+  # environment an agent or CI job actually uses - always has page counts and PDF assertions
+  # available without anyone opting in by hand.
+  module PdfInspection
+    class << self
+      def available?
+        return @available if defined?(@available)
+
+        @available = load_pdf_reader
+      end
+
+      # @param bytes [String, nil] raw PDF bytes.
+      # @return [Integer, nil] page count, or nil when pdf-reader is unavailable, bytes is nil,
+      #   or the PDF is malformed.
+      def page_count(bytes)
+        return nil unless bytes && available?
+
+        reader_for(bytes).page_count
+      rescue PDF::Reader::MalformedPDFError
+        nil
+      end
+
+      # @param bytes [String, nil] raw PDF bytes.
+      # @return [String, nil] extracted text across all pages, joined with newlines.
+      def text(bytes)
+        return nil unless bytes && available?
+
+        reader_for(bytes).pages.map(&:text).join("\n")
+      rescue PDF::Reader::MalformedPDFError
+        nil
+      end
+
+      # Clears the memoized availability check - test-only, so a spec can exercise both branches
+      # of #available? regardless of load order elsewhere in the process.
+      def reset_for_testing!
+        remove_instance_variable(:@available) if defined?(@available)
+      end
+
+      private
+
+      def load_pdf_reader
+        require "pdf-reader"
+        true
+      rescue LoadError
+        false
+      end
+
+      def reader_for(bytes)
+        PDF::Reader.new(StringIO.new(bytes))
+      end
+    end
+  end
+end

data/lib/bidi2pdf/recipe/loader.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+
+module Bidi2pdf
+  class Recipe
+    # Reads a recipe file (YAML, or JSON when the extension is .json) into a plain Hash. Never
+    # launches a browser - a malformed file fails right here.
+    #
+    # Security: YAML is parsed with Psych.safe_load and no extra options. Its defaults already
+    # refuse both custom type tags (no arbitrary Ruby object instantiation) and aliases - the
+    # latter matters concretely: a small file using nested YAML anchors/aliases ("billion laughs")
+    # can expand to millions of elements in memory; confirmed live, a 273-byte such file produced
+    # 10 million array elements in under 2ms. Neither aliases nor a Date/Time value are used by any
+    # field a recipe defines, so neither is turned back on "just in case" - only what the format
+    # actually needs is permitted. MAX_BYTES bounds the file itself before it is even parsed.
+    module Loader
+      MAX_BYTES = 1_048_576 # 1 MiB - generous for a recipe file, small enough to bound a huge one.
+
+      # rubocop:disable-next Metrics/AbcSize
+      def self.load(path)
+        raise Bidi2pdf::InvalidRecipeError.new("Recipe file not found: #{path}", details: { path: path }) unless File.exist?(path)
+
+        raise Bidi2pdf::InvalidRecipeError.new("Recipe file '#{path}' is too large (max #{MAX_BYTES} bytes)", details: { path: path }) if File.size(path) > MAX_BYTES
+
+        content = File.read(path)
+        parsed = path.end_with?(".json") ? JSON.parse(content) : YAML.safe_load(content)
+
+        raise Bidi2pdf::InvalidRecipeError.new("Recipe must be a mapping at the top level", details: { path: "." }) unless parsed.is_a?(Hash)
+
+        parsed
+      rescue Psych::Exception, JSON::ParserError => e
+        # Psych::Exception covers SyntaxError, AliasesNotEnabled and DisallowedClass alike, so a
+        # recipe attempting to use any of the features safe_load refuses fails the same clean way
+        # a syntax error would, not with an unhandled exception. The message is truncated the same
+        # way Bidi2pdf.truncate_for_log bounds any other value that can hold arbitrary input -
+        # a recipe may carry credentials (basic auth, headers), and a parser error's own message
+        # can otherwise quote a slice of the offending content straight back.
+        raise Bidi2pdf::InvalidRecipeError.new("Could not parse recipe '#{path}': #{Bidi2pdf.truncate_for_log(e.message)}", details: { path: path })
+      end
+    end
+  end
+end