bidi2pdf 0.1.15 → 0.1.16

data/sig/bidi2pdf/recipe/schema_shape.rbs

@@ -0,0 +1,85 @@
+module Bidi2pdf
+  class Recipe
+    # Structural validation against Schema::RECIPE itself, not a hand-duplicated parallel list of
+    # rules. Validator's other #check_* methods each enforce one *semantic* rule (an action name
+    # is known, a source key is truthy, a presence assertion is `true`) with a friendly, specific
+    # message - none of them enforce the schema's own `additionalProperties: false` at every
+    # level, so an extra, unrecognized key sitting alongside an otherwise-valid one used to pass
+    # silently even though `bidi2pdf schema recipe` would reject it (`{url: "...", stdin: false}`,
+    # `{wait_for: {...}, extra: 1}` - two action names in one step, `wait_for: {selector: "#x",
+    # bogus: "y"}`). #check_shape (see Validator) closes that whole class of gap generically by
+    # walking the schema the CLI already publishes, instead of re-describing "what's allowed" a
+    # second time in Ruby - the schema is the one place that description can't drift from itself.
+    #
+    # Deliberately not a general JSON Schema engine and not a gem dependency: only the keywords
+    # Schema::RECIPE actually uses (type, const, enum, required, additionalProperties, properties,
+    # oneOf, anyOf, items, minimum, maximum). Extend the keyword list only if a future schema
+    # branch genuinely needs one this doesn't cover yet.
+    module SchemaShape
+      TYPE_CHECKS: { "object" => untyped, "array" => untyped, "string" => untyped, "integer" => untyped, "number" => untyped, "boolean" => untyped, "null" => untyped }
+
+      CHECKS: ::Array[:const_ok? | :enum_ok? | :type_ok? | :one_of_ok? | :any_of_ok? | :required_ok? | :additional_properties_ok? | :properties_ok? | :items_ok? | :bounds_ok?]
+
+      # @return [Boolean] whether value satisfies schema
+      def self?.matches?: (untyped schema, untyped value) -> untyped
+
+      VIOLATION_CHECKS: ::Array[:oneof_violation | :anyof_violation | :required_violation | :additional_properties_violation | :const_violation | :enum_violation | :type_violation | :bounds_violation | :nested_violation]
+
+      # @return [Hash, nil] {path:, reason:} for the first violation a depth-first walk finds, or
+      #   nil if value already satisfies schema. Not necessarily *the* most relevant violation
+      #   when several exist at once - good enough to point an agent at the right neighborhood,
+      #   not a substitute for reading `bidi2pdf schema recipe` for the exact shape.
+      def self?.first_violation: (untyped schema, untyped value, ?untyped path) -> (nil | untyped | { path: untyped, reason: "does not match the schema" })
+
+      def self?.const_ok?: (untyped schema, untyped value) -> untyped
+
+      def self?.enum_ok?: (untyped schema, untyped value) -> untyped
+
+      def self?.type_ok?: (untyped schema, untyped value) -> (true | untyped)
+
+      def self?.one_of_ok?: (untyped schema, untyped value) -> (true | untyped)
+
+      def self?.any_of_ok?: (untyped schema, untyped value) -> (true | untyped)
+
+      def self?.required_ok?: (untyped schema, untyped value) -> (true | untyped)
+
+      def self?.additional_properties_ok?: (untyped schema, untyped value) -> (true | untyped)
+
+      def self?.properties_ok?: (untyped schema, untyped value) -> (true | untyped)
+
+      def self?.items_ok?: (untyped schema, untyped value) -> (true | untyped)
+
+      def self?.bounds_ok?: (untyped schema, untyped value) -> (true | untyped)
+
+      def self?.display_path: (untyped path) -> untyped
+
+      # When zero branches match but exactly one is "plausible" (its own required key(s) are
+      # present, ignoring additionalProperties), recurse into that one branch for a specific
+      # reason/path instead of a bare "matched 0 of N" - this is what turns "actions[0] doesn't
+      # match any known action" into "actions[0].wait_for: unknown key(s): bogus".
+      def self?.oneof_violation: (untyped schema, untyped value, untyped path) -> (nil | untyped)
+
+      def self?.single_plausible_violation: (untyped schema, untyped value, untyped path) -> (nil | untyped)
+
+      def self?.anyof_violation: (untyped schema, untyped value, untyped path) -> (nil | { path: untyped, reason: ::String })
+
+      def self?.required_violation: (untyped schema, untyped value, untyped path) -> (nil | { path: untyped, reason: ::String })
+
+      def self?.additional_properties_violation: (untyped schema, untyped value, untyped path) -> (nil | { path: untyped, reason: ::String })
+
+      def self?.const_violation: (untyped schema, untyped value, untyped path) -> (nil | { path: untyped, reason: ::String })
+
+      def self?.enum_violation: (untyped schema, untyped value, untyped path) -> (nil | { path: untyped, reason: ::String })
+
+      def self?.type_violation: (untyped schema, untyped value, untyped path) -> (nil | { path: untyped, reason: ::String })
+
+      def self?.bounds_violation: (untyped schema, untyped value, untyped path) -> (nil | { path: untyped, reason: ::String })
+
+      def self?.nested_violation: (untyped schema, untyped value, untyped path) -> untyped
+
+      def self?.properties_violation: (untyped schema, untyped value, untyped path) -> (nil | untyped)
+
+      def self?.items_violation: (untyped schema, untyped value, untyped path) -> (nil | untyped)
+    end
+  end
+end

data/sig/bidi2pdf/recipe/validator.rbs

@@ -0,0 +1,54 @@
+module Bidi2pdf
+  class Recipe
+    # Validates a loaded recipe against the schema `bidi2pdf schema recipe` publishes, before any
+    # browser is launched - `bidi2pdf run --validate` runs exactly this and nothing else. Every
+    # failure is Bidi2pdf::InvalidRecipeError (or Bidi2pdf::PdfInspectionUnavailableError for a
+    # PDF assertion without pdf-reader installed), details carrying a `path` an agent can act on
+    # directly.
+    class Validator
+      @recipe: untyped
+
+      def initialize: (untyped recipe) -> void
+
+      def validate!: () -> untyped
+
+      private
+
+      def check_version: () -> (nil | untyped)
+
+      def check_top_level_keys: () -> (nil | untyped)
+
+      def check_source: () -> untyped
+
+      def check_steps: (untyped section, untyped steps, untyped known) -> untyped
+
+      # Mirrors Schema::RECIPE_ACTIONS' own wait_for oneOf: exactly one of selector/paged_js/script.
+      # --validate runs this check itself rather than relying on Runner#wait_for_condition, whose
+      # own "needs one of" error only fires mid-run (after a browser is already launched) and does
+      # not catch "more than one given" at all - it just silently prefers paged_js, then selector.
+      def check_wait_for_conditions: () -> untyped
+
+      # Mirrors Schema::RECIPE_ASSERT's own const: true for the 4 presence-only assertions -
+      # Runner never reads the value beside them, so anything but `true` is misleading rather than
+      # merely unusual (see Recipe::PRESENCE_ONLY_ASSERTIONS' own comment).
+      def check_presence_assertions: () -> untyped
+
+      def check_pdf_assertions_need_pdf_inspection: () -> (nil | untyped)
+
+      def check_output: () -> (nil | untyped)
+
+      def check_print_options: () -> untyped
+
+      def symbolize: (untyped hash) -> untyped
+
+      # Runs last, deliberately: everything above gives a friendlier, more specific message for
+      # the case it already knows about (an unknown action name, a non-true presence assertion, a
+      # real PrintParametersValidator error, ...), so this only ever fires for a shape violation
+      # none of them catches - an extra/unrecognized key sitting alongside an otherwise-valid one
+      # (SchemaShape's own doc comment has the concrete examples this closes).
+      def check_shape: () -> (nil | untyped)
+
+      def fail!: (untyped reason, path: untyped) -> untyped
+    end
+  end
+end

data/sig/bidi2pdf/recipe.rbs

@@ -0,0 +1,72 @@
+module Bidi2pdf
+  # A recipe is a rendering contract: the waits and preparation a page needs before it is printed,
+  # and the properties the resulting PDF must have - not a general browser-automation script.
+  # `bidi2pdf run recipe.yml` is Loader -> (an invalid recipe stops here, no browser ever
+  # launches) -> Validator -> Runner.
+  class Recipe
+    @data: untyped
+
+    @path: untyped
+
+    KNOWN_TOP_LEVEL_KEYS: ::Array["version" | "source" | "browser" | "headers" | "cookies" | "auth" | "actions" | "assert" | "print" | "output"]
+
+    KNOWN_ACTIONS: ::Array["wait_for" | "click" | "evaluate" | "inject_script" | "inject_style" | "set_viewport" | "wait_network_idle"]
+
+    PAGE_ASSERTIONS: ::Array["selector_exists" | "text_present" | "no_console_errors" | "no_network_failures" | "fonts_loaded"]
+
+    PDF_ASSERTIONS: ::Array["page_count" | "pdf_text_present" | "pdf_not_blank"]
+
+    KNOWN_ASSERTIONS: untyped
+
+    KNOWN_OUTPUTS: ::Array["pdf" | "manifest" | "screenshot"]
+
+    # These four assertions are pure presence checks - Runner never reads the value beside them
+    # (see #assertion_no_console_errors and friends), so a bare key is really what's being
+    # asserted. `false`/anything but `true` is therefore misleading, not merely unusual: schema
+    # recipe encodes this as `const: true` and Validator#check_presence_assertions enforces it too.
+    PRESENCE_ONLY_ASSERTIONS: ::Array["no_console_errors" | "no_network_failures" | "fonts_loaded" | "pdf_not_blank"]
+
+    attr_reader data: untyped
+
+    attr_reader path: untyped
+
+    def self.load: (untyped path) -> untyped
+
+    def initialize: (untyped data, ?path: untyped?) -> void
+
+    def validate!: () -> untyped
+
+    def actions: () -> untyped
+
+    def assertions: () -> untyped
+
+    def source: () -> untyped
+
+    def browser_options: () -> untyped
+
+    def headers: () -> untyped
+
+    def cookies: () -> untyped
+
+    def auth: () -> untyped
+
+    def print_options: () -> untyped
+
+    def output: () -> untyped
+
+    def needs_pdf?: () -> untyped
+
+    def self.step_name: (untyped step) -> untyped
+
+    def step_name: (untyped step) -> untyped
+
+    # The value beside a step's name - a Hash of options (`wait_for: {selector: ..., timeout:
+    # ...}`), a bare scalar (`page_count: 2`, `no_console_errors: true`), or nil.
+    def step_value: (untyped step) -> (untyped | nil)
+
+    # step_value coerced to a Hash of options - most actions/assertions take this shape; a bare
+    # scalar step (page_count: 2, no_console_errors: true) has no options of its own to offer here,
+    # so callers that need the scalar itself use #step_value directly.
+    def step_options: (untyped step) -> untyped
+  end
+end

data/sig/bidi2pdf/result.rbs

@@ -0,0 +1,71 @@
+module Bidi2pdf
+  # Structured result of a CLI command (render/diagnose/run) - the shape behind --json output, a
+  # render manifest, and the final "result" event of --json-stream. Construct via .success/
+  # .failure rather than .new directly so every Result is unambiguously one or the other.
+  class Result
+    @command: untyped
+
+    @ok: untyped
+
+    @output: untyped
+
+    @bytes: untyped
+
+    @sha256: untyped
+
+    @pages: untyped
+
+    @duration_ms: untyped
+
+    @navigation: untyped
+
+    @console: untyped
+
+    @network_failures: untyped
+
+    @warnings: untyped
+
+    @error: untyped
+
+    @metadata: untyped
+
+    SCHEMA_VERSION: 1
+
+    attr_reader command: untyped
+
+    attr_reader output: untyped
+
+    attr_reader bytes: untyped
+
+    attr_reader sha256: untyped
+
+    attr_reader pages: untyped
+
+    attr_reader duration_ms: untyped
+
+    attr_reader navigation: untyped
+
+    attr_reader console: untyped
+
+    attr_reader network_failures: untyped
+
+    attr_reader warnings: untyped
+
+    attr_reader error: untyped
+
+    attr_reader metadata: untyped
+
+    # rubocop:disable-next Metrics/ParameterLists, Naming/MethodParameterName
+    def initialize: (command: untyped, ok: untyped, ?output: untyped?, ?bytes: untyped?, ?sha256: untyped?, ?pages: untyped?, ?duration_ms: untyped?, ?navigation: untyped?, ?console: untyped, ?network_failures: untyped, ?warnings: untyped, ?error: untyped?, ?metadata: ::Hash[untyped, untyped]) -> void
+
+    def self.success: (**untyped) -> untyped
+
+    def self.failure: (error: untyped, **untyped) -> untyped
+
+    def ok?: () -> untyped
+
+    def to_h: () -> untyped
+
+    def to_json: (*untyped) -> untyped
+  end
+end

data/sig/bidi2pdf/result_collector.rbs

@@ -0,0 +1,106 @@
+module Bidi2pdf
+  # Builds a Bidi2pdf::Result by subscribing to the gem's own instrumentation events
+  # (Bidi2pdf::Notifications) around a block that does the actual rendering, rather than changing
+  # what Launcher/SessionRunner/BrowserTab return - Launcher#launch keeps returning the raw base64
+  # PDF when no output file is given, exactly as the programmatic API already promises (see
+  # spec/acceptance/launcher_spec.rb).
+  class ResultCollector
+    @requested_url: untyped
+
+    @command: untyped
+
+    @output: untyped
+
+    @console: untyped
+
+    @network_events: untyped
+
+    @pdf_bytes: untyped
+
+    # Capture the Proc #subscribe actually stored (it converts &handler into one), so
+    # #unsubscribe below can remove exactly this registration - passing the handler positionally
+    # rather than as a second &block, since Notifications#unsubscribe(pattern, block = nil)
+    # clears *every* subscriber for that pattern when block is nil/omitted.
+    @registered: untyped
+
+    @navigation_event: untyped
+
+    # #pdf_bytes is the raw, decoded PDF (nil if nothing was printed) - not part of Result#to_h
+    # (which only carries bytesize/sha256/pages), but what a stdout-output render (--output -)
+    # writes to $stdout, and what a caller can hand to Bidi2pdf::PdfInspection itself.
+    #
+    # #console/#network_failures are exposed live (not only via the Result #around eventually
+    # returns) so a caller running inside the block - Recipe::Runner's assertions - can read them
+    # before the block itself finishes.
+    attr_reader requested_url: untyped
+
+    # #pdf_bytes is the raw, decoded PDF (nil if nothing was printed) - not part of Result#to_h
+    # (which only carries bytesize/sha256/pages), but what a stdout-output render (--output -)
+    # writes to $stdout, and what a caller can hand to Bidi2pdf::PdfInspection itself.
+    #
+    # #console/#network_failures are exposed live (not only via the Result #around eventually
+    # returns) so a caller running inside the block - Recipe::Runner's assertions - can read them
+    # before the block itself finishes.
+    attr_reader navigation_event: untyped
+
+    # #pdf_bytes is the raw, decoded PDF (nil if nothing was printed) - not part of Result#to_h
+    # (which only carries bytesize/sha256/pages), but what a stdout-output render (--output -)
+    # writes to $stdout, and what a caller can hand to Bidi2pdf::PdfInspection itself.
+    #
+    # #console/#network_failures are exposed live (not only via the Result #around eventually
+    # returns) so a caller running inside the block - Recipe::Runner's assertions - can read them
+    # before the block itself finishes.
+    attr_reader pdf_bytes: untyped
+
+    # #pdf_bytes is the raw, decoded PDF (nil if nothing was printed) - not part of Result#to_h
+    # (which only carries bytesize/sha256/pages), but what a stdout-output render (--output -)
+    # writes to $stdout, and what a caller can hand to Bidi2pdf::PdfInspection itself.
+    #
+    # #console/#network_failures are exposed live (not only via the Result #around eventually
+    # returns) so a caller running inside the block - Recipe::Runner's assertions - can read them
+    # before the block itself finishes.
+    attr_reader console: untyped
+
+    def initialize: (requested_url: untyped, command: untyped, ?output: untyped?) -> void
+
+    # Runs the block with the collector subscribed, then returns a Bidi2pdf::Result - success with
+    # whatever was captured, or failure describing whatever the block raised. Never itself raises.
+    def around: () { () -> untyped } -> untyped
+
+    def network_failures: () -> untyped
+
+    private
+
+    def now_ms: () -> untyped
+
+    def elapsed_ms: (untyped start) -> untyped
+
+    def subscribe: () -> untyped
+
+    def unsubscribe: () -> untyped
+
+    # Kept for its #duration (used by Manifest's navigation.duration_ms); Result itself doesn't
+    # surface navigation timing separately from the overall duration_ms.
+    def on_navigate: (untyped event) -> untyped
+
+    def on_console: (untyped event) -> untyped
+
+    def on_network_event: (untyped event) -> (nil | untyped)
+
+    def on_print: (untyped event) -> untyped
+
+    # rubocop:disable-next Naming/MethodParameterName
+    def build_result: (ok: untyped, duration_ms: untyped, ?error: untyped?) -> untyped
+
+    def navigation_info: () -> { requested_url: untyped, final_url: untyped, status: untyped }
+
+    # Best-effort external approximation of what BrowserTab#send(:correlated_navigation_response)
+    # already computes internally (not exposed publicly): among the network events this collector
+    # observed, the ones carrying a real BiDi "navigation" id are main-frame document requests: the
+    # one with the latest start_timestamp among those sharing the most recent such navigation id is
+    # the final hop of that navigation, and its own #url is therefore the page actually reached.
+    def final_navigation_event: () -> (nil | untyped)
+
+    def warnings: () -> (::Array[untyped] | ::Array["pages requires the pdf-reader gem"])
+  end
+end

data/sig/bidi2pdf/schema.rbs

@@ -0,0 +1,45 @@
+module Bidi2pdf
+  # JSON Schema documents behind `bidi2pdf schema <kind>` - how an agent discovers the shape of
+  # --json/--manifest/--json-stream/a recipe file without reading prose documentation. These are
+  # the source of truth for those shapes; a change to Result/Diagnose's payload/Recipe::Runner's
+  # result shape/Manifest/JsonSubscriber/Recipe's own fields should update the matching schema
+  # here in the same change. Kind names match the `command` field a response already carries
+  # (`"command": "diagnose"` -> `bidi2pdf schema diagnose`), not the Ruby class names behind them.
+  module Schema
+    ERROR: { "type" => ::Array["object" | "null"], "required" => ::Array["code" | "message" | "retryable"], "properties" => { "code" => { "type" => "string" }, "message" => { "type" => "string" }, "retryable" => { "type" => "boolean" }, "hint" => { "type" => ::Array["string" | "null"] }, "details" => { "type" => "object" } } }
+
+    NAVIGATION: { "type" => ::Array["object" | "null"], "properties" => { "requested_url" => { "type" => ::Array["string" | "null"] }, "final_url" => { "type" => ::Array["string" | "null"] }, "status" => { "type" => ::Array["integer" | "null"] } } }
+
+    CONSOLE: { "type" => "array", "items" => { "type" => "object", "properties" => { "level" => { "type" => "string" }, "text" => { "type" => "string" } } } }
+
+    NETWORK_FAILURES: { "type" => "array", "items" => { "type" => "object", "properties" => { "url" => { "type" => "string" }, "method" => { "type" => ::Array["string" | "null"] }, "status" => { "type" => ::Array["integer" | "null"] }, "state" => { "type" => "string" } } } }
+
+    WARNINGS: { "type" => "array", "items" => { "type" => "string" } }
+
+    RENDER: { "$schema" => "https://json-schema.org/draft/2020-12/schema", "title" => "Bidi2pdf::Result (render)", "description" => "--json output of `bidi2pdf render`, and the final \"result\" event of its --json-stream", "type" => "object", "required" => ::Array["schema_version" | "ok" | "command" | "console" | "network_failures" | "warnings"], "properties" => { "schema_version" => { "const" => 1 }, "ok" => { "type" => "boolean" }, "command" => { "const" => "render" }, "output" => { "type" => ::Array["string" | "null"] }, "bytes" => { "type" => ::Array["integer" | "null"] }, "sha256" => { "type" => ::Array["string" | "null"] }, "pages" => { "type" => ::Array["integer" | "null"], "description" => "null when the pdf-reader gem is unavailable" }, "duration_ms" => { "type" => ::Array["integer" | "null"] }, "navigation" => untyped, "console" => untyped, "network_failures" => untyped, "warnings" => untyped, "error" => untyped } }
+
+    DIAGNOSE: { "$schema" => "https://json-schema.org/draft/2020-12/schema", "title" => "bidi2pdf diagnose result", "description" => "--json output of `bidi2pdf diagnose`, and the final \"result\" event of its --json-stream. page/fonts/print_media/paged_js are Bidi2pdf::Diagnose's own parsed script results, loosely shaped here rather than over-specified.", "type" => "object", "required" => ::Array["schema_version" | "ok" | "command" | "console" | "network_failures" | "warnings"], "properties" => { "schema_version" => { "const" => 1 }, "ok" => { "type" => "boolean" }, "command" => { "const" => "diagnose" }, "page" => { "type" => ::Array["object" | "null"] }, "console" => untyped, "network_failures" => untyped, "fonts" => { "type" => ::Array["object" | "null"] }, "print_media" => { "type" => ::Array["object" | "null"] }, "paged_js" => { "type" => ::Array["object" | "null"] }, "screenshot" => { "type" => ::Array["string" | "null"], "description" => "path written, when --screenshot was given" }, "pdf" => { "type" => ::Array["object" | "null"], "description" => "present when --pdf was given", "properties" => { "path" => { "type" => "string" }, "pages" => { "type" => ::Array["integer" | "null"] }, "not_blank" => { "type" => ::Array["boolean" | "null"] } } }, "warnings" => untyped, "error" => untyped } }
+
+    RUN_STEP: { "type" => "object", "required" => ::Array["index" | "type" | "ok"], "properties" => { "index" => { "type" => "integer" }, "type" => { "type" => "string" }, "ok" => { "type" => "boolean" }, "duration_ms" => { "type" => "integer" }, "details" => { "type" => "object" } } }
+
+    RUN: { "$schema" => "https://json-schema.org/draft/2020-12/schema", "title" => "bidi2pdf run result", "description" => "--json output of `bidi2pdf run recipe.yml`, and the final \"result\" event of its --json-stream", "type" => "object", "required" => ::Array["schema_version" | "ok" | "command" | "recipe" | "actions" | "assertions" | "warnings"], "properties" => { "schema_version" => { "const" => 1 }, "ok" => { "type" => "boolean" }, "command" => { "const" => "run" }, "recipe" => { "type" => "string", "description" => "the recipe file path given on the command line" }, "actions" => { "type" => "array", "items" => untyped }, "assertions" => { "type" => "array", "items" => untyped }, "assigned" => { "type" => "object", "description" => "values captured by evaluate ... assign:, keyed by name" }, "output" => { "type" => ::Array["object" | "null"], "description" => "null when the run failed", "properties" => { "pdf" => { "type" => ::Array["string" | "null"] }, "manifest" => { "type" => ::Array["string" | "null"] }, "screenshot" => { "type" => ::Array["string" | "null"] }, "bytes" => { "type" => ::Array["integer" | "null"] }, "sha256" => { "type" => ::Array["string" | "null"] }, "pages" => { "type" => ::Array["integer" | "null"] } } }, "duration_ms" => { "type" => ::Array["integer" | "null"] }, "warnings" => untyped, "error" => untyped } }
+
+    MANIFEST: { "$schema" => "https://json-schema.org/draft/2020-12/schema", "title" => "Bidi2pdf render manifest", "description" => "--manifest FILE output", "type" => "object", "required" => ::Array["schema_version" | "bidi2pdf_version" | "created_at" | "input" | "output" | "navigation" | "render"], "properties" => { "schema_version" => { "const" => 1 }, "bidi2pdf_version" => { "type" => "string" }, "created_at" => { "type" => "string", "format" => "date-time" }, "input" => { "type" => "object", "required" => ::Array["type"], "properties" => { "type" => { "type" => "string", "enum" => ::Array["url" | "html_file" | "stdin"] }, "url" => { "type" => ::Array["string" | "null"] } } }, "output" => { "type" => "object", "properties" => { "path" => { "type" => ::Array["string" | "null"] }, "pages" => { "type" => ::Array["integer" | "null"] }, "bytes" => { "type" => ::Array["integer" | "null"] }, "sha256" => { "type" => ::Array["string" | "null"] } } }, "browser" => { "type" => "object" }, "navigation" => untyped, "render" => { "type" => "object", "properties" => { "duration_ms" => { "type" => ::Array["integer" | "null"] } } }, "console" => untyped, "network_failures" => untyped, "warnings" => untyped, "headers" => { "type" => "object", "description" => "present only when custom headers were given; secret-bearing values are redacted" } } }
+
+    EVENT: { "$schema" => "https://json-schema.org/draft/2020-12/schema", "title" => "Bidi2pdf --json-stream event", "description" => "one JSON object per stderr line while --json-stream is active. In structured mode (--json/--output -), the last line is always {event: \"result\", result: <the matching command's own schema - see \"result\"'s own oneOf>}. In human mode (--json-stream given alone), only progress events are emitted - there is no synthetic final \"result\" event, since there is no structured result being built; the human-readable log is the completion/failure signal.", "type" => "object", "required" => ::Array["schema_version" | "t_ms" | "event"], "properties" => { "schema_version" => { "const" => 1 }, "t_ms" => { "type" => "integer", "description" => "milliseconds since the render started" }, "event" => { "type" => "string", "enum" => ::Array["navigate" | "page_loaded" | "network_idle" | "console" | "print" | "screenshot" | "result"] }, "url" => { "type" => "string", "description" => "present on a navigate event" }, "level" => { "type" => "string", "description" => "present on a console event" }, "text" => { "type" => "string", "description" => "present on a console event" }, "result" => { "description" => "present only on the final \"result\" event (structured mode only); shape depends on which command produced this stream - each branch's own \"command\" value disambiguates", "oneOf" => ::Array[untyped] } } }
+
+    RECIPE_SOURCE: { "description" => "exactly one of url, file, stdin", "oneOf" => ::Array[{ "type" => "object", "required" => ::Array["url"], "properties" => { "url" => { "type" => "string" } }, "additionalProperties" => false } | { "type" => "object", "required" => ::Array["file"], "properties" => { "file" => { "type" => "string" } }, "additionalProperties" => false } | { "type" => "object", "required" => ::Array["stdin"], "properties" => { "stdin" => { "const" => true } }, "additionalProperties" => false }] }
+
+    RECIPE_ACTIONS: { "description" => "one of the 7 known actions - a thin dispatch over BrowserTab's own methods, see README's Agent and Automation Usage section", "oneOf" => ::Array[{ "type" => "object", "required" => ::Array["wait_for"], "additionalProperties" => false, "properties" => { "wait_for" => { "type" => "object", "description" => "exactly one of selector, paged_js, script; timeout is always optional", "oneOf" => ::Array[{ "type" => "object", "required" => ::Array["selector"], "additionalProperties" => false, "properties" => { "selector" => { "type" => "string" }, "timeout" => { "type" => "number" } } } | { "type" => "object", "required" => ::Array["paged_js"], "additionalProperties" => false, "properties" => { "paged_js" => { "type" => "boolean" }, "timeout" => { "type" => "number" } } } | { "type" => "object", "required" => ::Array["script"], "additionalProperties" => false, "properties" => { "script" => { "type" => "string" }, "timeout" => { "type" => "number" } } }] } } } | { "type" => "object", "required" => ::Array["click"], "additionalProperties" => false, "properties" => { "click" => { "type" => "object", "required" => ::Array["selector"], "additionalProperties" => false, "properties" => { "selector" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["evaluate"], "additionalProperties" => false, "properties" => { "evaluate" => { "type" => "object", "required" => ::Array["script"], "additionalProperties" => false, "properties" => { "script" => { "type" => "string" }, "assign" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["inject_script"], "additionalProperties" => false, "properties" => { "inject_script" => { "type" => "object", "additionalProperties" => false, "properties" => { "url" => { "type" => "string" }, "content" => { "type" => "string" }, "id" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["inject_style"], "additionalProperties" => false, "properties" => { "inject_style" => { "type" => "object", "additionalProperties" => false, "properties" => { "url" => { "type" => "string" }, "content" => { "type" => "string" }, "id" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["set_viewport"], "additionalProperties" => false, "properties" => { "set_viewport" => { "type" => "object", "required" => ::Array["width" | "height"], "additionalProperties" => false, "properties" => { "width" => { "type" => "number" }, "height" => { "type" => "number" }, "device_pixel_ratio" => { "type" => "number" } } } } } | { "type" => "object", "required" => ::Array["wait_network_idle"], "additionalProperties" => false, "properties" => { "wait_network_idle" => { "type" => "object", "additionalProperties" => false, "properties" => { "timeout" => { "type" => "number" } } } } }] }
+
+    RECIPE_ASSERT: { "description" => "one of the 8 known assertions. The presence-only ones (no_console_errors, no_network_failures, fonts_loaded, pdf_not_blank) never have their value read at run time - Recipe::Runner only checks the key is there - so they must be written as `true`; `false` or any other value is rejected as misleading rather than silently ignored. The last 3 assertions also require the pdf-reader gem at --validate time - a runtime fact this schema cannot express, see the top-level description", "oneOf" => ::Array[{ "type" => "object", "required" => ::Array["selector_exists"], "additionalProperties" => false, "properties" => { "selector_exists" => { "type" => "object", "required" => ::Array["selector"], "additionalProperties" => false, "properties" => { "selector" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["text_present"], "additionalProperties" => false, "properties" => { "text_present" => { "type" => "object", "required" => ::Array["text"], "additionalProperties" => false, "properties" => { "text" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["no_console_errors"], "additionalProperties" => false, "properties" => { "no_console_errors" => { "const" => true } } } | { "type" => "object", "required" => ::Array["no_network_failures"], "additionalProperties" => false, "properties" => { "no_network_failures" => { "const" => true } } } | { "type" => "object", "required" => ::Array["fonts_loaded"], "additionalProperties" => false, "properties" => { "fonts_loaded" => { "const" => true } } } | { "type" => "object", "required" => ::Array["page_count"], "additionalProperties" => false, "properties" => { "page_count" => { "oneOf" => ::Array[{ "type" => "integer" } | { "type" => "object", "properties" => { "min" => { "type" => "integer" }, "max" => { "type" => "integer" } }, "additionalProperties" => false }] } } } | { "type" => "object", "required" => ::Array["pdf_text_present"], "additionalProperties" => false, "properties" => { "pdf_text_present" => { "type" => "object", "required" => ::Array["text"], "additionalProperties" => false, "properties" => { "text" => { "type" => "string" } } } } } | { "type" => "object", "required" => ::Array["pdf_not_blank"], "additionalProperties" => false, "properties" => { "pdf_not_blank" => { "const" => true } } }] }
+
+    RECIPE_PRINT: { "type" => "object", "description" => "the same options `bidi2pdf render`'s own print flags map to; validated by Bidi::Commands::PrintParametersValidator", "properties" => { "background" => { "type" => "boolean" }, "shrinkToFit" => { "type" => "boolean" }, "orientation" => { "type" => "string", "enum" => ::Array["portrait" | "landscape"] }, "scale" => { "type" => "number", "minimum" => ::Float, "maximum" => ::Float }, "pageRanges" => { "type" => "array", "items" => { "type" => ::Array["integer" | "string"] } }, "margin" => { "type" => "object", "properties" => { "top" => { "type" => "number", "minimum" => 0 }, "bottom" => { "type" => "number", "minimum" => 0 }, "left" => { "type" => "number", "minimum" => 0 }, "right" => { "type" => "number", "minimum" => 0 } } }, "page" => { "type" => "object", "properties" => { "format" => { "type" => "string" }, "width" => { "type" => "number", "minimum" => ::Float }, "height" => { "type" => "number", "minimum" => ::Float } } } } }
+
+    RECIPE: { "$schema" => "https://json-schema.org/draft/2020-12/schema", "title" => "Bidi2pdf recipe", "description" => "input to `bidi2pdf run recipe.yml` (YAML or JSON). This schema is meant to be sufficient on its own to generate a recipe `--validate` will accept, with one exception JSON Schema cannot express: a page_count/pdf_text_present/pdf_not_blank assertion also requires the pdf-reader gem to be installed at validation time (a runtime environment fact, not a document-shape one) - `--validate` still catches a violation, with error code PDF_INSPECTION_UNAVAILABLE.", "type" => "object", "required" => ::Array["version" | "source" | "output"], "additionalProperties" => false, "properties" => { "version" => { "const" => 1 }, "source" => untyped, "browser" => { "type" => "object", "properties" => { "headless" => { "type" => "boolean" } } }, "headers" => { "type" => "object" }, "cookies" => { "type" => "object" }, "auth" => { "type" => "object", "properties" => { "username" => { "type" => "string" }, "password" => { "type" => "string" } } }, "actions" => { "type" => "array", "items" => untyped }, "assert" => { "type" => "array", "items" => untyped }, "print" => untyped, "output" => { "type" => "object", "description" => "at least one of pdf, manifest, screenshot", "anyOf" => ::Array[{ "required" => ::Array["pdf"] } | { "required" => ::Array["manifest"] } | { "required" => ::Array["screenshot"] }], "properties" => { "pdf" => { "type" => "string" }, "manifest" => { "type" => "string" }, "screenshot" => { "type" => "string" } } } } }
+
+    ALL: { "render" => untyped, "diagnose" => untyped, "run" => untyped, "manifest" => untyped, "recipe" => untyped, "event" => untyped }
+
+    def self.for: (untyped kind) -> untyped
+  end
+end

data/sig/bidi2pdf/session_runner.rbs

@@ -67,6 +67,17 @@ module Bidi2pdf
 
     def run: () -> untyped
 
+    # Like #run, but stops after navigation (and the configured waits) instead of printing, and
+    # leaves the tab open for the caller to inspect - used by `bidi2pdf diagnose`, which has no PDF
+    # to produce. The caller is responsible for #close_all once done.
+    #
+    # @return [Bidi2pdf::Bidi::BrowserTab] the navigated tab.
+    def run_diagnose: () -> untyped
+
+    # Closes what #run_diagnose opened. #run's own run_flow already does this itself (in its
+    # ensure), so this is only ever needed after #run_diagnose.
+    def close_all: () -> untyped
+
     private
 
     def setup_browser: () -> untyped
@@ -77,6 +88,12 @@ module Bidi2pdf
 
     def add_basic_auth: () -> (nil | untyped)
 
+    # Navigate + wait only, no log_network_traffic/print side effects - #run_flow above
+    # intentionally keeps its own inline sequence (where log_network_traffic sits between the two
+    # waits) untouched rather than sharing this, since that render-only file-writing side effect
+    # has no place in a diagnose flow.
+    def navigate_and_wait: () -> untyped
+
     # rubocop: disable Metrics/AbcSize
     def run_flow: () -> untyped
 

data/sig/bidi2pdf/version.rbs

@@ -1,3 +1,3 @@
 module Bidi2pdf
-  VERSION: "0.1.15"
+  VERSION: "0.1.16"
 end

data/sig/bidi2pdf.rbs

@@ -11,13 +11,30 @@ module Bidi2pdf
 
   PAPER_FORMATS_CM: { letter: { width: ::Float, height: ::Float }, legal: { width: ::Float, height: ::Float }, tabloid: { width: ::Float, height: ::Float }, ledger: { width: ::Float, height: ::Float }, a0: { width: ::Float, height: ::Float }, a1: { width: ::Float, height: ::Float }, a2: { width: ::Float, height: ::Float }, a3: { width: ::Float, height: ::Float }, a4: { width: ::Float, height: ::Float }, a5: { width: ::Float, height: ::Float }, a6: { width: ::Float, height: ::Float } }
 
+  # Base class for every error this gem raises. Carries the machine-readable surface used by
+  # --json/--json-stream/manifests/recipe results (see Bidi2pdf::ErrorCodes): #retryable? and
+  # #hint are overridden per subclass below where a useful default exists; #details is set at
+  # raise time for structured, serializable context (e.g. which selector, which assertion).
   class Error < StandardError
+    @details: untyped
+
+    attr_reader details: untyped
+
+    def initialize: (?untyped? message, ?details: ::Hash[untyped, untyped]) -> void
+
+    def retryable?: () -> false
+
+    def hint: () -> nil
   end
 
   class SessionNotStartedError < Error
+    def retryable?: () -> true
+
+    def hint: () -> "Check Chrome/chromedriver are installed and reachable, or that --remote-browser-url points at a running instance"
   end
 
   class WebsocketError < Error
+    def retryable?: () -> true
   end
 
   class ClientError < WebsocketError
@@ -39,6 +56,9 @@ module Bidi2pdf
   end
 
   class CmdTimeoutError < ClientError
+    def retryable?: () -> true
+
+    def hint: () -> "Raise --default-timeout"
   end
 
   class PrintError < Error
@@ -70,15 +90,61 @@ module Bidi2pdf
     attr_reader url: untyped
 
     def initialize: (untyped url, ?untyped? message) -> void
+
+    def hint: () -> "Pass --auth user:pass, or check the credentials are still valid"
   end
 
   class NavigationTimeoutError < NavigationError
+    def retryable?: () -> true
+
+    def hint: () -> "Raise --default-timeout, or add --wait-network-idle if the page loads data after the load event"
   end
 
   class NavigationNotFoundError < NavigationError
+    def hint: () -> "Check the URL is correct"
   end
 
   class NavigationDNSError < NavigationError
+    @url: untyped
+
+    attr_reader url: untyped
+
+    def initialize: (?untyped? url, ?untyped? message) -> void
+
+    def retryable?: () -> true
+
+    def hint: () -> "Check the hostname is correct and reachable from this machine/container"
+  end
+
+  class MissingInputError < Error
+  end
+
+  class MultipleInputSourcesError < Error
+  end
+
+  class EmptyInputError < Error
+  end
+
+  class InvalidConfigError < Error
+  end
+
+  class InvalidPrintOptionError < Error
+  end
+
+  class InvalidRecipeError < Error
+  end
+
+  class SelectorNotFoundError < Error
+  end
+
+  class PageNotAsExpectedError < Error
+  end
+
+  class OutputWriteError < Error
+  end
+
+  class PdfInspectionUnavailableError < Error
+    def hint: () -> "Install the pdf-reader gem, or drop assertions/fields that need it"
   end
 
   attr_accessor self.default_timeout: untyped