pikuri 0.0.1

data/lib/pikuri/tool/read.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    # The +read+ tool, expressed as a {Tool} subclass: instantiating
+    # +Tool::Read.new(workspace: ws)+ produces a tool whose
+    # {Tool#to_ruby_llm_tool} wiring is identical to any bundled tool's,
+    # so ruby_llm sees nothing special about it. Same shape as
+    # {Tool::SubAgent} — workspace is captured by the +execute+ closure
+    # at construction.
+    #
+    # == Output format
+    #
+    # cat-n: each line is rendered as +"%6d\t%s"+ (six-column right-
+    # padded line number, tab, content). Chosen for breadth of training-
+    # data exposure: +cat -n+ output shows up across virtually every Unix
+    # tutorial and Stack Overflow answer, so even small local models
+    # recognize the shape. opencode's shorter +"<n>: <content>"+ format
+    # saves a few thousand tokens per 2K-line file but trades model
+    # familiarity; pi omits line numbers entirely (cheapest tokens, but
+    # the model loses the ability to cite ranges or pick {Edit}
+    # boundaries precisely).
+    #
+    # == Truncation rules
+    #
+    # Two independent limits, whichever fires first wins:
+    #
+    # * *Line limit* — {DEFAULT_LIMIT} lines (overridable via +limit+).
+    # * *Byte cap* — {MAX_BYTES} bytes of input content; not exposed as a
+    #   parameter. Bypassable in practice by paging via +offset+.
+    #
+    # Additionally, individual lines longer than {MAX_LINE_LENGTH} chars
+    # are truncated with {LINE_TRUNCATION_MARKER} appended; the model is
+    # told to reach for +grep+ to find content inside such files.
+    #
+    # == Refusals
+    #
+    # * Path outside the workspace → caught from
+    #   {Tool::Workspace::Error}, returned as +"Error: ..."+.
+    # * File not found, EACCES → +"Error: ..."+.
+    # * Path is a directory → +"Error: ... use the glob tool"+, keeping
+    #   directory listing as the glob tool's responsibility (Step 9).
+    # * Binary content → sniffed from the first {BINARY_SAMPLE_BYTES} of
+    #   the file: any +NUL+ byte, or more than {BINARY_NONPRINTABLE_THRESHOLD}
+    #   non-printable bytes (control chars outside +\t \n \v \f \r+),
+    #   triggers refusal. Catches images, PDFs, archives, and compiled
+    #   artifacts without an extension list to maintain.
+    # * Offset past EOF → +"Error: offset N is beyond end of file (M lines total)"+.
+    class Read < Tool
+      # @return [Integer] default value of the +limit+ parameter (number
+      #   of lines to read per call).
+      DEFAULT_LIMIT = 2000
+
+      # @return [Integer] per-line character cap; longer lines are
+      #   truncated with {LINE_TRUNCATION_MARKER}.
+      MAX_LINE_LENGTH = 2000
+
+      # @return [String] suffix appended to lines truncated by
+      #   {MAX_LINE_LENGTH}.
+      LINE_TRUNCATION_MARKER = "... (line truncated to #{MAX_LINE_LENGTH} chars)"
+
+      # @return [Integer] hard byte cap on input content collected per
+      #   call. Counted on the line bytes (plus one for the joining
+      #   newline); the rendered output is slightly larger due to the
+      #   per-line +"%6d\t"+ prefix.
+      MAX_BYTES = 50 * 1024
+
+      # @return [String] human-readable form of {MAX_BYTES} for the
+      #   continuation marker.
+      MAX_BYTES_LABEL = "#{MAX_BYTES / 1024} KB"
+
+      # @return [Integer] number of bytes sampled from the start of the
+      #   file for binary-content detection.
+      BINARY_SAMPLE_BYTES = 4096
+
+      # @return [Float] fraction of the sample that may be non-printable
+      #   before the file is classified as binary. Matches opencode's
+      #   30%.
+      BINARY_NONPRINTABLE_THRESHOLD = 0.30
+
+      # Description shown to the LLM. Follows the opencode-shape (summary
+      # + +Usage:+ bullets) prescribed by the project's tool-description
+      # convention. Per-parameter constraints (defaults, format) live in
+      # the parameter descriptions, not here.
+      #
+      # @return [String]
+      DESCRIPTION = <<~DESC
+        Read a file from the workspace and return its contents with line numbers.
+
+        Usage:
+        - Output is line-numbered in `cat -n` style so subsequent edits can reference exact line numbers.
+        - Use `offset` and `limit` to page through large files; when the response ends in `Use offset=N to continue`, call again with that offset.
+        - Lines longer than #{MAX_LINE_LENGTH} chars are truncated with a marker — use `grep` for content inside such files.
+        - Binary files (images, PDFs, archives, compiled artifacts) are refused; this tool reads text only.
+        - Directories are refused — use the `glob` tool to list files.
+        - If unsure of the path, use `glob` first to look up filenames.
+        - Avoid tiny repeated slices — if you need more context, read a larger window.
+      DESC
+
+      # @param workspace [Tool::Workspace] captured for path resolution;
+      #   all reads route through +workspace.resolve_for_read+.
+      # @return [Read]
+      def initialize(workspace:)
+        super(
+          name: 'read',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.required_string :path,
+                              'Path to the file to read. Relative paths ' \
+                              'resolve against the workspace root, e.g. ' \
+                              '"lib/foo.rb" or "/abs/path/to/file.txt".'
+            p.optional_integer :offset,
+                               'Line number to start reading from (1-indexed). ' \
+                               "Defaults to 1, e.g. 200."
+            p.optional_integer :limit,
+                               'Maximum number of lines to read. Defaults to ' \
+                               "#{DEFAULT_LIMIT}, e.g. 500."
+          },
+          execute: ->(path:, offset: 1, limit: DEFAULT_LIMIT) {
+            Read.read(workspace: workspace, path: path, offset: offset, limit: limit)
+          }
+        )
+      end
+
+      # Resolve +path+ against +workspace+, refuse directories / binaries /
+      # missing files, and return either the cat-n-formatted slice or an
+      # +"Error: ..."+ observation.
+      #
+      # @param workspace [Tool::Workspace]
+      # @param path [String] raw path as supplied by the LLM
+      # @param offset [Integer] 1-indexed line number to start at
+      # @param limit [Integer] maximum lines to return
+      # @return [String] tool observation
+      def self.read(workspace:, path:, offset:, limit:)
+        return "Error: offset must be >= 1, got #{offset}" if offset < 1
+        return "Error: limit must be >= 1, got #{limit}"   if limit < 1
+
+        resolved = workspace.resolve_for_read(path)
+        return "Error: file not found: #{path}" unless resolved.exist?
+        return "Error: #{path} is a directory; use the glob tool to list files." if resolved.directory?
+
+        sample = read_sample(resolved)
+        return "Error: cannot read binary file: #{path}" if binary?(sample)
+
+        format_slice(path: path, resolved: resolved, offset: offset, limit: limit)
+      rescue Tool::Workspace::Error => e
+        "Error: #{e.message}"
+      rescue Errno::EACCES => e
+        "Error: cannot read #{path}: #{e.message}"
+      end
+
+      # Read up to {BINARY_SAMPLE_BYTES} of the file in binary mode for
+      # the {.binary?} sniff. Returns an empty String for an empty file
+      # (which {.binary?} treats as not-binary).
+      #
+      # @param resolved [Pathname]
+      # @return [String] raw bytes (ASCII-8BIT encoding)
+      def self.read_sample(resolved)
+        resolved.open('rb') { |io| io.read(BINARY_SAMPLE_BYTES) || +'' }
+      end
+      private_class_method :read_sample
+
+      # Heuristic binary classifier matching opencode's: any NUL byte
+      # forces +true+; otherwise count bytes outside the printable +\t \n
+      # \v \f \r+ + ASCII-32..126 range and ratio against the sample
+      # size. UTF-8 continuation bytes (0x80-0xBF) are >127 so they sit
+      # outside the non-printable ranges and pass through unflagged,
+      # letting UTF-8 text read fine.
+      #
+      # Public because {Tool::Edit} reuses it to refuse binary targets —
+      # if Edit accepted a binary file the model has no way to have read,
+      # it could corrupt bytes the model never inspected. Same sniff, same
+      # threshold, one definition.
+      #
+      # @param bytes [String] sample bytes
+      # @return [Boolean]
+      def self.binary?(bytes)
+        return false if bytes.empty?
+
+        non_printable = 0
+        bytes.each_byte do |b|
+          return true if b.zero?
+
+          non_printable += 1 if b < 9 || (b > 13 && b < 32)
+        end
+        non_printable.to_f / bytes.bytesize > BINARY_NONPRINTABLE_THRESHOLD
+      end
+
+      # Stream the file line-by-line, collect at most +limit+ lines
+      # starting at +offset+, and stop early if {MAX_BYTES} is reached.
+      # We keep counting lines past the collection window so the trailer
+      # can report total line count when the line limit (not the byte
+      # cap) was the stopping criterion — same trick opencode uses.
+      #
+      # @return [String]
+      def self.format_slice(path:, resolved:, offset:, limit:)
+        start_index   = offset - 1
+        collected     = []
+        total_lines   = 0
+        bytes         = 0
+        byte_cap_hit  = false
+        has_more      = false
+
+        resolved.each_line do |raw|
+          total_lines += 1
+          next if total_lines <= start_index
+
+          if collected.length >= limit
+            has_more = true
+            next
+          end
+
+          line = raw.chomp
+          if line.length > MAX_LINE_LENGTH
+            line = line[0, MAX_LINE_LENGTH] + LINE_TRUNCATION_MARKER
+          end
+
+          size = line.bytesize + 1 # +1 for the joining newline
+          if bytes + size > MAX_BYTES
+            byte_cap_hit = true
+            has_more = true
+            break
+          end
+
+          collected << line
+          bytes += size
+        end
+
+        return '(Empty file)' if total_lines.zero?
+
+        if start_index >= total_lines
+          return "Error: offset #{offset} is beyond end of file (#{total_lines} lines total)"
+        end
+
+        last_line = offset + collected.length - 1
+        body = collected.each_with_index.map { |line, i| format("%6d\t%s", i + offset, line) }.join("\n")
+
+        trailer =
+          if byte_cap_hit
+            "(Output capped at #{MAX_BYTES_LABEL}. Showing lines #{offset}-#{last_line}. " \
+              "Use offset=#{last_line + 1} to continue.)"
+          elsif has_more
+            "(Showing lines #{offset}-#{last_line} of #{total_lines}. " \
+              "Use offset=#{last_line + 1} to continue.)"
+          else
+            "(End of file - total #{total_lines} lines)"
+          end
+
+        "#{body}\n\n#{trailer}"
+      end
+      private_class_method :format_slice
+    end
+  end
+end

data/lib/pikuri/tool/scraper/fetch_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    module Scraper
+      # Raised by anything in the scraper stack when a URL cannot be
+      # rendered into Markdown text — HTTP non-2xx, network failure,
+      # redirect-loop, missing +Location+, unsupported content-type, or a
+      # parse failure that reads as "try a different URL" to the LLM.
+      # Catching this in {Tool::WEB_SCRAPE} / {Tool::FETCH} turns the
+      # failure into an +"Error: ..."+ observation; anything else bubbles
+      # up so genuine bugs stay visible.
+      class FetchError < StandardError; end
+    end
+  end
+end

data/lib/pikuri/tool/scraper/html.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'nokogiri'
+require 'readability'
+require 'reverse_markdown'
+
+module Pikuri
+  class Tool
+    module Scraper
+      # HTML → Markdown extractor used by {Simple.visit} when the fetched
+      # response carries an HTML content-type.
+      #
+      # Always renders both views of the page when available:
+      #
+      # 1. JSON-LD section. Any +<script type="application/ld+json">+ node
+      #    whose +@type+ matches a substantive schema.org content type
+      #    (Product, Article, Recipe, ...) is rendered as a header — title,
+      #    metadata bullets (brand, SKU, price, rating, author, published),
+      #    and the +articleBody+/+description+ copy when present.
+      # 2. Readability section. The page is run through +Readability+ +
+      #    +reverse_markdown+, with a +<main>+/+<article>+ fallback for
+      #    pages whose content sits mostly outside +<p>+ tags.
+      #
+      # Concatenated with a horizontal rule, so the LLM gets both the
+      # structured metadata and the rendered body and can pick whichever
+      # is more useful for the task. Trades some duplication (when a
+      # publisher embeds the article body in JSON-LD AND in HTML) for
+      # fewer type-based heuristics on which branch should win — the
+      # earlier "is this Article's +description+ a teaser or the real
+      # body?" carve-out is no longer needed because both end up in
+      # the output regardless.
+      #
+      # Pure parser — no I/O. {.extract} takes an HTML string and returns
+      # Markdown, so tests can drive it against fixture HTML without a
+      # network round-trip.
+      module HTML
+        # @return [Array<String>] schema.org +@type+ values that we treat
+        #   as "the primary entity of this page" when picking a JSON-LD
+        #   node to render. Order does not matter — the first matching
+        #   node wins. Skips noise nodes (Organization, BreadcrumbList,
+        #   WebSite, ...) that ship on most pages but carry no page
+        #   content.
+        INTERESTING_TYPES = %w[
+          Product Article NewsArticle BlogPosting Recipe Event Book Movie
+        ].freeze
+
+        # @return [Array<String>] HTML tags preserved by the readability
+        #   pass. Anything outside this list is stripped before Markdown
+        #   conversion.
+        READABILITY_TAGS = %w[
+          h1 h2 h3 h4 h5 h6 p div span ul ol li blockquote pre code a img
+          strong em b i br hr table thead tbody tr td th
+        ].freeze
+
+        # @return [Array<String>] HTML attributes preserved by the
+        #   readability pass; everything else (class, id, style, data-*)
+        #   is dropped before Markdown conversion
+        READABILITY_ATTRS = %w[href src alt title].freeze
+
+        # @return [Float] minimum +<main>+/+<article>+ to Readability
+        #   text-length ratio that triggers the semantic-container
+        #   fallback in {.readability_to_markdown}. Picked low enough to
+        #   catch the failure mode (Readability collapsing a page that
+        #   uses divs/lists instead of +<p>+ — e.g. +vaadin.com/company+,
+        #   ~5x) but high enough that pages where both produce
+        #   comparable output keep Readability's noise filtering.
+        MAIN_FALLBACK_RATIO = 2.0
+
+        # @return [Integer] minimum text length the
+        #   +<main>+/+<article>+ container must hold before the fallback
+        #   in {.readability_to_markdown} can fire. Below this, the
+        #   ratio comparison is dominated by noise and we'd swap on
+        #   tiny pages where Readability is doing the right thing.
+        MAIN_FALLBACK_MIN_CHARS = 500
+
+        # Render +html+ as Markdown by emitting both the JSON-LD section
+        # (when an interesting node is present) and the readability /
+        # +<main>+ section, joined by a horizontal rule. Either section
+        # may be missing — pages with no JSON-LD return only the
+        # readability output, and a malformed page with no extractable
+        # body returns only the JSON-LD render.
+        #
+        # @param html [String] HTML document body
+        # @return [String] Markdown representation
+        def self.extract(html)
+          sections = [jsonld_section(html), readability_to_markdown(html)]
+          sections.reject! { |s| s.nil? || s.strip.empty? }
+          sections.join("\n\n---\n\n")
+        end
+
+        # Pick the first JSON-LD node whose +@type+ matches one of
+        # {INTERESTING_TYPES} and render it as Markdown. Returns +nil+
+        # when no such node exists, in which case {.extract} emits only
+        # the readability section.
+        #
+        # No content-field gating: a node carrying just +name+/+author+/
+        # +datePublished+ still renders (as a metadata-only header),
+        # because the readability pass independently produces the page
+        # body. That is the trade-off that lets us drop the type-based
+        # "is this teaser or article copy?" heuristics — duplication is
+        # acceptable when both views are available, and the LLM can
+        # pick whichever it needs.
+        #
+        # @param html [String] HTML document body
+        # @return [String, nil] Markdown render of the picked JSON-LD
+        #   node, or +nil+ when nothing matched
+        def self.jsonld_section(html)
+          node = parse_jsonld(html).find do |n|
+            Array(n['@type']).any? { |t| INTERESTING_TYPES.include?(t) }
+          end
+          node ? jsonld_to_markdown(node) : nil
+        end
+
+        # Collect every JSON-LD payload embedded in +html+, flattening
+        # +@graph+ wrappers so callers see one flat array of schema.org
+        # nodes. Malformed JSON blocks are silently skipped — sites
+        # frequently ship broken JSON-LD and we only need at least one
+        # parseable block.
+        #
+        # @param html [String] HTML document body
+        # @return [Array<Hash>] parsed JSON-LD nodes; possibly empty
+        def self.parse_jsonld(html)
+          doc = Nokogiri::HTML(html)
+          blobs = doc.css('script[type="application/ld+json"]').map(&:text)
+
+          blobs.flat_map do |raw|
+            parsed = begin
+              JSON.parse(raw)
+            rescue JSON::ParserError
+              nil
+            end
+            next [] unless parsed
+
+            nodes = parsed.is_a?(Array) ? parsed : [parsed]
+            nodes.flat_map { |n| n['@graph'].is_a?(Array) ? n['@graph'] : [n] }
+          end
+        end
+
+        # Render a single JSON-LD +node+ as Markdown: a top-level title
+        # from +name+/+headline+, a bullet list of common useful fields
+        # (brand, SKU, price, rating, author, published date, ...), the
+        # body copy, and the lead image.
+        #
+        # When the node carries +articleBody+ (the full publisher-supplied
+        # article text), that wins over +description+ — the description
+        # is typically a lede teaser and would just repeat the article's
+        # opening lines.
+        #
+        # @param node [Hash] JSON-LD node, typically picked by
+        #   {.jsonld_section}
+        # @return [String] Markdown representation
+        def self.jsonld_to_markdown(node)
+          out = +''
+          name = node['name'] || node['headline']
+          out << "# #{name}\n\n" if name
+
+          offer  = first_obj(node['offers'])
+          rating = first_obj(node['aggregateRating'])
+          brand  = first_obj_or_string(node['brand'])
+          author = first_obj_or_string(node['author'])
+
+          brand_name  = brand.is_a?(Hash)  ? brand['name']  : brand
+          author_name = author.is_a?(Hash) ? author['name'] : author
+
+          fields = {
+            'Brand'        => brand_name,
+            'SKU'          => node['sku'],
+            'GTIN'         => node['gtin13'] || node['gtin'],
+            'Price'        => [offer['price'], offer['priceCurrency']].compact.join(' '),
+            'Availability' => offer['availability'],
+            'Rating'       => rating['ratingValue'],
+            'Reviews'      => rating['reviewCount'],
+            'Author'       => author_name,
+            'Published'    => node['datePublished']
+          }.reject { |_, v| v.nil? || v.to_s.strip.empty? }
+
+          unless fields.empty?
+            fields.each { |k, v| out << "- **#{k}:** #{v}\n" }
+            out << "\n"
+          end
+
+          if (body = node['articleBody'] || node['description'])
+            out << "#{body}\n\n"
+          end
+
+          if (img = node['image'])
+            img = img.first if img.is_a?(Array)
+            img = img['url'] if img.is_a?(Hash)
+            out << "![image](#{img})\n\n" if img
+          end
+
+          out
+        end
+
+        # Run +Readability+ over +html+ to isolate the main content node,
+        # then convert that to Markdown via +reverse_markdown+. The page
+        # +<title>+ is rendered as a top-level heading.
+        #
+        # When the page uses semantic HTML5 (+<main>+ or +<article>+) but
+        # leaves most of its content outside +<p>+ tags — divs, lists,
+        # spans — Readability's paragraph-density scoring collapses the
+        # extraction to a sliver of the page. In that case we render the
+        # +<main>+/+<article>+ container directly. The fallback only
+        # fires when the container holds substantially more text than
+        # Readability picked up (see {MAIN_FALLBACK_RATIO} /
+        # {MAIN_FALLBACK_MIN_CHARS}); on pages where both agree we keep
+        # Readability so its noise filtering still strips nav/ads/etc.
+        #
+        # @param html [String] HTML document body
+        # @return [String] Markdown representation
+        def self.readability_to_markdown(html)
+          rdoc = Readability::Document.new(
+            html,
+            tags: READABILITY_TAGS,
+            attributes: READABILITY_ATTRS,
+            remove_empty_nodes: true
+          )
+          readability_html = rdoc.content
+          title = rdoc.title
+
+          body_html = main_fallback_html(html, readability_html) || readability_html
+          body = ReverseMarkdown.convert(body_html, unknown_tags: :bypass, github_flavored: true)
+
+          out = +''
+          out << "# #{title.strip}\n\n" if title && !title.strip.empty?
+          out << body
+          out
+        end
+
+        # If +html+ has a +<main>+ or +<article>+ element holding
+        # substantially more text than Readability extracted, return that
+        # container's HTML so the caller can render it instead. Returns
+        # +nil+ when the fallback should not fire — when there is no
+        # semantic container, when it's too small to be meaningful, or
+        # when Readability's output is already comparable.
+        #
+        # @param html [String] full HTML document body, used to locate
+        #   the +<main>+/+<article>+ container
+        # @param readability_html [String] HTML produced by
+        #   +Readability::Document#content+, used as the comparison
+        #   baseline
+        # @return [String, nil] container HTML when the fallback should
+        #   fire, +nil+ otherwise
+        def self.main_fallback_html(html, readability_html)
+          doc = Nokogiri::HTML(html)
+          container = doc.at_css('main') || doc.at_css('article')
+          return nil unless container
+
+          container_text_len = container.text.gsub(/\s+/, ' ').strip.length
+          return nil if container_text_len < MAIN_FALLBACK_MIN_CHARS
+
+          readability_text_len = Nokogiri::HTML(readability_html).text.gsub(/\s+/, ' ').strip.length
+          return nil if container_text_len < MAIN_FALLBACK_RATIO * readability_text_len
+
+          container.to_html
+        end
+        private_class_method :main_fallback_html
+
+        # JSON-LD fields can be a string, hash, or array of either.
+        # Normalize to a single hash (the first one if it's a list) so
+        # callers can +.dig+ safely.
+        #
+        # @param value [Object] raw JSON-LD field value
+        # @return [Hash] empty hash when +value+ does not contain a hash
+        def self.first_obj(value)
+          value = value.first if value.is_a?(Array)
+          value.is_a?(Hash) ? value : {}
+        end
+        private_class_method :first_obj
+
+        # Same idea as {.first_obj} but preserves a bare string (e.g.
+        # +brand: "Apple"+) instead of replacing it with +{}+.
+        #
+        # @param value [Object] raw JSON-LD field value
+        # @return [String, Hash, nil]
+        def self.first_obj_or_string(value)
+          value = value.first if value.is_a?(Array)
+          value
+        end
+        private_class_method :first_obj_or_string
+      end
+    end
+  end
+end

data/lib/pikuri/tool/scraper/pdf.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'pdf-reader'
+require 'stringio'
+
+module Pikuri
+  class Tool
+    module Scraper
+      # PDF → text extractor used by {Simple.visit} when the fetched
+      # response carries +application/pdf+. Wraps the +pdf-reader+ gem:
+      # walk every page, concatenate the extracted text, hand the result
+      # back as a single string the LLM can read.
+      #
+      # Best-effort by design. +pdf-reader+ produces clean text from PDFs
+      # generated from a digital source (LaTeX, Word export, ...) but
+      # returns nothing useful from scanned documents — there is no OCR
+      # in this path. When extraction yields no text we still return an
+      # empty string rather than raising, so the caller's cache stores a
+      # consistent result and the LLM sees an empty observation it can
+      # react to.
+      #
+      # Pure parser — no I/O. {.extract} takes PDF bytes and returns text,
+      # so tests can drive it against an in-memory fixture without
+      # touching the network.
+      module PDF
+        # Render +bytes+ as plain text, one page per paragraph.
+        #
+        # +pdf-reader+ raises a handful of typed exceptions for documents
+        # it cannot parse — broken xrefs ({::PDF::Reader::MalformedPDFError}),
+        # invalid page references ({::PDF::Reader::InvalidPageError}),
+        # encrypted/XFA files ({::PDF::Reader::UnsupportedFeatureError}).
+        # All three describe a property of the PDF the LLM can react to
+        # ("try a different URL"), so we re-raise them as {FetchError} —
+        # same convention as the HTTP layer in {Simple.fetch}. Genuine
+        # bugs in +pdf-reader+ itself surface as their own classes and
+        # crash loud.
+        #
+        # @param bytes [String] raw PDF document (binary string)
+        # @return [String] concatenated page text; possibly empty when
+        #   the PDF carries no extractable text (scanned image, empty
+        #   document)
+        # @raise [FetchError] when +pdf-reader+ refuses the document
+        def self.extract(bytes)
+          reader = ::PDF::Reader.new(StringIO.new(bytes))
+          reader.pages.map { |p| p.text.strip }.reject(&:empty?).join("\n\n")
+        rescue ::PDF::Reader::MalformedPDFError,
+               ::PDF::Reader::InvalidPageError,
+               ::PDF::Reader::UnsupportedFeatureError => e
+          raise FetchError, "PDF rendering failed: #{e.class.name.split('::').last}: #{e.message}"
+        end
+      end
+    end
+  end
+end