portage-cli 0.7.5 → 0.9.0

data/lib/portage/cli/browser_import/importer.rb

@@ -0,0 +1,248 @@
+require "uri"
+
+require_relative "../classifier"
+require_relative "../index"
+require_relative "../index/builder"
+require_relative "profiles"
+require_relative "readers"
+require_relative "filter"
+require_relative "prober"
+require_relative "categorize"
+require_relative "saver"
+require_relative "domains"
+
+module Portage
+  module Cli
+    module BrowserImport
+      # `portage browser import` (docs/plans/buy-skill-and-local-browser.md
+      # Phase 3, Tier A): bookmarks and history in, a short list of shop
+      # domains out, written to the user's own Index::Store only after the
+      # user has seen the list and said yes (Cli.run_browser_import owns
+      # that gate; this class only ever writes from #save).
+      #
+      # #plan reads the profile's allowed files (Profiles::ALLOWED_FILES,
+      # nothing else), reduces every row to its domain, and decides each
+      # domain locally first — skipped as an obvious non-shop (Filter),
+      # excluded by the user, on the hand-off-only list, or already in the
+      # index — before spending one of at most `max_probes` Prober probes
+      # on an unknown one. A domain is kept only when it answers
+      # `/.well-known/ucp`, matches a WebMCP preset, or is hand-off only.
+      # Each kept domain is classified from what the user actually looked
+      # at there (page titles, bookmark folder names, URL slugs), weighted
+      # by visit count.
+      #
+      # Kept domains land in Index::Store with `sources: ["history"]`/
+      # `["bookmark"]` — the same untrusted index every other source
+      # writes, so an imported store reaches `find` only as a
+      # `source: "index"` candidate (never Policy#merchant_allowlist, never
+      # past the `--store`/interactive pick a `--yes` buy requires), and
+      # Index::Exporter treats both labels as personal: never exported.
+      class Importer
+        DEFAULT_HISTORY_DAYS = 90
+        MAX_PROBES = 200
+
+        FULL_DISK_ACCESS = "macOS won't let this terminal read Safari's history and bookmarks without Full Disk " \
+                           "Access. To allow it, open System Settings > Privacy & Security > Full Disk Access, " \
+                           "turn it on for the terminal app you run portage from, then quit and reopen that app " \
+                           "and re-run this command. Portage doesn't try any other way in. Nothing was imported, " \
+                           "probed or saved.".freeze
+
+        # Any other browser: the same "explain and stop", without claiming
+        # to know which protection said no (macOS privacy settings, a
+        # sandboxed terminal, file permissions).
+        PERMISSION_DENIED = "Permission denied reading %<browser>s's profile folder. If your terminal runs " \
+                            "sandboxed or macOS is protecting that folder, allow access (System Settings > " \
+                            "Privacy & Security > Full Disk Access) and re-run. Portage doesn't try any other way " \
+                            "in. Nothing was imported, probed or saved.".freeze
+
+        Options = Struct.new(:browser, :root, :history_days, :include_product_pages, :max_probes, :exclude,
+                             keyword_init: true) do
+          def initialize(history_days: DEFAULT_HISTORY_DAYS, include_product_pages: false, max_probes: MAX_PROBES,
+                         exclude: [], **)
+            super
+          end
+        end
+
+        # @param handoff_only_hosts [Array<String>] Tier C hosts (Phase 5
+        #   will supply the user's own `handoff_only_hosts:` config; nothing
+        #   ships that list yet, so it defaults to empty). A history domain
+        #   on it is kept — hand-off only, never probed, never automated.
+        # @param webmcp_preset_for [#call, nil] `->(origin) { preset_or_nil }`.
+        #   Matching a WebMCP preset needs a browser bridge an import doesn't
+        #   have (same posture as Index::Sources::WebmcpSweep), so nil (the
+        #   default) skips the check entirely.
+        # @param readers [#call] `->(family) { reader }` — see Readers.for.
+        def initialize(stores: Index::Store.new, products: Index::ProductStore.new,
+                       known_cache: Index::KnownCache.new, prober: Prober.new, handoff_only_hosts: [],
+                       webmcp_preset_for: nil, readers: Readers.method(:for), now: Time.now)
+          @stores = stores
+          @products = products
+          @known_cache = known_cache
+          @prober = prober
+          @handoff_only_hosts = handoff_only_hosts.map { |h| h.to_s.downcase.delete_prefix("www.") }
+          @webmcp_preset_for = webmcp_preset_for
+          @readers = readers
+          @now = now
+        end
+
+        # @return [Hash] the proposal: counts, `kept` (domains to save) and
+        #   `products` (only with include_product_pages) — or `error:` /
+        #   `message:` when the browser's files couldn't be read (Safari
+        #   without Full Disk Access, no sqlite3, no profile found).
+        def plan(options)
+          profiles = Profiles.locate(options.browser, root: options.root)
+          return no_profile(options) if profiles.empty?
+
+          rows, opened = read_rows(profiles, since: @now.to_i - (options.history_days.to_i * 86_400))
+          summarize(options, profiles, opened, rows)
+        rescue Sqlite::PermissionDenied
+          permission_denied(options)
+        rescue Sqlite::Unavailable => e
+          { browser: options.browser, error: "reader_unavailable",
+            message: "Couldn't read the browser's files: #{e.message}." }
+        end
+
+        # Writes a #plan's kept domains (and products) into the index — see
+        # Saver.
+        # @return [Hash] stores:, products: — how many entries were written.
+        def save(proposal) = Saver.new(stores: @stores, products: @products, now: @now).save(proposal)
+
+        private
+
+        # --- Reading ---
+
+        def read_rows(profiles, since:)
+          opened = []
+          rows = profiles.flat_map do |profile|
+            reader = @readers.call(profile.family)
+            opened.concat([profile.history, profile.bookmarks].compact)
+            reader.history(profile, since: since) + reader.bookmarks(profile)
+          end
+          [rows, opened.uniq]
+        end
+
+        # --- Deciding each domain ---
+
+        def summarize(options, profiles, opened, rows)
+          groups = Domains.group(rows)
+          state = { skipped: Hash.new(0), kept: [], cached_miss: 0, not_ucp: 0, unprobed: 0 }
+          groups.sort_by { |_key, g| -g[:visits] }.each { |key, group| decide(key, group, options, state) }
+          report(options, profiles, opened, rows, groups, state)
+        end
+
+        def decide(key, group, options, state)
+          reason = local_skip_reason(key, options)
+          return state[:skipped][reason] += 1 if reason
+
+          verdict = local_verdict(key) || probe_verdict(Domains.origin_for(group), options, state)
+          state[:kept] << kept_entry(key, group, verdict) if verdict
+        end
+
+        def local_skip_reason(key, options)
+          return :excluded if Array(options.exclude).any? { |h| h.to_s.downcase.delete_prefix("www.") == key }
+
+          Filter.skip_reason(key)
+        end
+
+        # Everything decidable with no network call at all.
+        def local_verdict(key)
+          return { verdict: "handoff_only", handoff_only: true } if handoff_only?(key)
+
+          own = own_entry(key)
+          return { verdict: "indexed", origin: own["origin"] } if own
+
+          known = known_entry(key)
+          return unless known
+
+          { verdict: "known", origin: known["origin"], capabilities: known["capabilities"],
+            last_verified: known["last_verified"] }
+        end
+
+        # A cached "no UCP" verdict or the probe cap skips the probe, but
+        # not the WebMCP check (when a bridge is injected) — a page can
+        # expose WebMCP tools without any manifest at all.
+        def probe_verdict(origin, options, state)
+          session = ucp_session(origin, options, state)
+          return nil if session == :capped
+          return { verdict: "ucp", origin: origin, capabilities: Index::Builder.capabilities_of(session) } if session
+
+          preset = @webmcp_preset_for&.call(origin)
+          return { verdict: "webmcp", origin: origin, webmcp_preset: preset } if preset
+
+          state[:not_ucp] += 1 unless session == false
+          nil
+        end
+
+        # @return [Session, nil, false, :capped] a session; nil when the
+        #   probe found no UCP; false for a cached miss (no request made);
+        #   :capped once max_probes is spent.
+        def ucp_session(origin, options, state)
+          if @prober.cached_miss?(origin)
+            state[:cached_miss] += 1
+            false
+          elsif @prober.probes >= options.max_probes.to_i
+            state[:unprobed] += 1
+            :capped
+          else
+            @prober.probe(origin)
+          end
+        end
+
+        def handoff_only?(key)
+          @handoff_only_hosts.any? { |h| key == h || key.end_with?(".#{h}") }
+        end
+
+        def own_entry(key) = @stores.all.find { |e| Domains.key_of(e["origin"]) == key }
+
+        def known_entry(key) = @known_cache.stores.values.find { |e| Domains.key_of(e["origin"]) == key }
+
+        # --- The proposal ---
+
+        def kept_entry(key, group, verdict)
+          { domain: key, origin: verdict[:origin] || Domains.origin_for(group), verdict: verdict[:verdict],
+            sources: group[:rows].map { |r| r[:kind] }.uniq.sort, visits: group[:visits],
+            categories: Categorize.domain(group[:rows]), rows: group[:rows] }
+            .merge(verdict.slice(:capabilities, :webmcp_preset, :handoff_only, :last_verified))
+        end
+
+        def report(options, profiles, opened, rows, groups, state)
+          kept = state[:kept]
+          { browser: options.browser, profiles: profiles.length, files_opened: opened, rows: row_counts(rows),
+            domains: groups.length, skipped: state[:skipped].transform_keys(&:to_s),
+            already_indexed: count(kept, "indexed"), known: count(kept, "known"), probed: @prober.probes,
+            cached_miss: state[:cached_miss], not_ucp: state[:not_ucp], unprobed: state[:unprobed],
+            capped: state[:unprobed].positive?, kept: kept.map { |entry| public_entry(entry) },
+            products: options.include_product_pages ? Categorize.products(kept) : [] }
+        end
+
+        def row_counts(rows)
+          kinds = rows.map { |r| r[:kind] }
+          { history: kinds.count("history"), bookmark: kinds.count("bookmark") }
+        end
+
+        def public_entry(entry)
+          entry.except(:rows).merge(category_names: Classifier.names_for(entry[:categories].keys))
+        end
+
+        def count(kept, verdict) = kept.count { |e| e[:verdict] == verdict }
+
+        # --- Helpers ---
+
+        def no_profile(options)
+          where = options.root ? " under #{options.root}" : ""
+          { browser: options.browser, error: "no_profile",
+            message: "No #{options.browser} profile with history or bookmarks found#{where}." }
+        end
+
+        def permission_denied(options)
+          if options.browser == "safari"
+            { browser: "safari", error: "full_disk_access_required", message: FULL_DISK_ACCESS }
+          else
+            { browser: options.browser, error: "permission_denied",
+              message: format(PERMISSION_DENIED, browser: options.browser) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_import/plist_xml.rb

@@ -0,0 +1,72 @@
+require "strscan"
+
+module Portage
+  module Cli
+    module BrowserImport
+      # Just enough of Apple's XML property-list format to read Safari's
+      # Bookmarks.plist once `plutil -convert xml1` has turned its binary
+      # form into XML. `plutil -convert json` would be simpler but refuses
+      # any plist holding a <date> (Safari's Reading List entries carry
+      # them), and a real XML library (rexml) isn't a runtime dependency of
+      # this gem — this is ~50 lines instead of a new one.
+      #
+      # Dates, data and numbers come back as their raw text; bookmark
+      # import only ever reads strings out of the tree.
+      module PlistXml
+        class ParseError < StandardError; end
+
+        SCALARS = "string|key|data|date|integer|real".freeze
+        ENTITIES = { "amp" => "&", "lt" => "<", "gt" => ">", "quot" => '"', "apos" => "'" }.freeze
+
+        def self.parse(xml)
+          scanner = StringScanner.new(xml.to_s)
+          raise ParseError, "not an XML plist" unless scanner.skip_until(/<plist[^>]*>/)
+
+          value(scanner)
+        end
+
+        def self.value(scanner)
+          scanner.skip(/\s*/)
+          if scanner.scan(%r{<(dict|array|#{SCALARS})\s*/>}) then empty(scanner[1])
+          elsif scanner.scan(%r{<(true|false)\s*/>}) then scanner[1] == "true"
+          elsif scanner.scan("<dict>") then dict(scanner)
+          elsif scanner.scan("<array>") then array(scanner)
+          elsif scanner.scan(%r{<(#{SCALARS})>(.*?)</\1>}m) then unescape(scanner[2])
+          else raise ParseError, "unexpected plist content at #{scanner.pos}"
+          end
+        end
+
+        def self.dict(scanner)
+          result = {}
+          until scanner.skip(%r{\s*</dict>})
+            key = value(scanner)
+            raise ParseError, "dict key isn't a string" unless key.is_a?(String)
+
+            result[key] = value(scanner)
+          end
+          result
+        end
+
+        def self.array(scanner)
+          result = []
+          result << value(scanner) until scanner.skip(%r{\s*</array>})
+          result
+        end
+
+        def self.empty(tag)
+          { "dict" => {}, "array" => [] }.fetch(tag, "")
+        end
+
+        def self.unescape(text)
+          text.gsub(/&(#x?)?(\w+);/) do
+            if Regexp.last_match(1) == "#x" then [Regexp.last_match(2).to_i(16)].pack("U")
+            elsif Regexp.last_match(1) == "#" then [Regexp.last_match(2).to_i].pack("U")
+            else ENTITIES.fetch(Regexp.last_match(2), Regexp.last_match(0))
+            end
+          end
+        end
+        private_class_method :value, :dict, :array, :empty, :unescape
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_import/prober.rb

@@ -0,0 +1,60 @@
+require "timeout"
+require "portage/ucp/client"
+
+require_relative "../user_agent"
+require_relative "../probe_cache"
+
+module Portage
+  module Cli
+    module BrowserImport
+      # The only way a browser-imported domain ever leaves this machine:
+      # one `GET /.well-known/ucp` through Portage::Ucp::Client.discover
+      # (the same discovery path `find` and `index build` use), recorded
+      # in the shared ProbeCache so a domain that didn't answer last time
+      # isn't asked again. No page, title, path or visit count is ever
+      # sent — just the origin, as the host of that one request.
+      class Prober
+        THROTTLE = 0.1
+
+        # Net::HTTP's own defaults are 60s each way — fine for one store,
+        # not for 200 history domains, some of which will be dead hosts.
+        TIMEOUT = 5
+
+        # @param discover [#call, nil] `->(origin) { session_or_nil }` —
+        #   injectable so specs never make a real request; nil (the
+        #   default) uses Portage::Ucp::Client.discover.
+        def initialize(cache: ProbeCache.new, discover: nil, throttle: THROTTLE, timeout: TIMEOUT)
+          @cache = cache
+          @discover = discover || method(:ucp_discover)
+          @throttle = throttle
+          @timeout = timeout
+          @probes = 0
+        end
+
+        attr_reader :probes
+
+        # A cached "no UCP here" verdict — answered with no request at all.
+        def cached_miss?(origin) = @cache.fetch(origin) == false
+
+        # @return [Portage::Ucp::Client::Session, nil]
+        def probe(origin)
+          sleep(@throttle) if @probes.positive? && @throttle.to_f.positive?
+          @probes += 1
+          session = safely { @discover.call(origin) }
+          @cache.record(origin, !session.nil?)
+          session
+        end
+
+        private
+
+        def safely(&)
+          Timeout.timeout(@timeout, &)
+        rescue StandardError # Timeout::Error included
+          nil
+        end
+
+        def ucp_discover(origin) = Portage::Ucp::Client.discover(origin, headers: UserAgent.headers)
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_import/profiles.rb

@@ -0,0 +1,114 @@
+require_relative "sqlite"
+
+module Portage
+  module Cli
+    module BrowserImport
+      # Where each supported browser keeps its profiles, and the exact
+      # files `portage browser import` is allowed to read from one.
+      #
+      # ALLOWED_FILES is the whole list — History/Bookmarks for the
+      # Chromium family, places.sqlite for Firefox, History.db/
+      # Bookmarks.plist for Safari. Nothing else in a profile directory is
+      # ever opened, copied or listed: not `Login Data`, `Cookies`,
+      # `Web Data` (autofill), `logins.json`, `key4.db`, `cookies.sqlite`,
+      # `formhistory.sqlite`, nor the keychain (docs/plans/
+      # buy-skill-and-local-browser.md, "Never, in any tier"; profiles_spec/
+      # importer_spec assert this against a fixture profile full of decoys).
+      # (Sqlite also copies an allowed database's own `-wal` file when one
+      # exists — it's part of that same database, holding its newest rows.)
+      # A profile's own *directory* is only ever stat'ed for these names,
+      # never listed; the one directory listing this does is the profile
+      # *root* (which profile folders exist — `Default`, `Profile 1`, …),
+      # never a profile's own contents.
+      module Profiles
+        Profile = Struct.new(:browser, :family, :dir, :history, :bookmarks, keyword_init: true)
+
+        CHROMIUM = %w[chrome edge brave arc].freeze
+
+        ALLOWED_FILES = {
+          "chromium" => { history: "History", bookmarks: "Bookmarks" },
+          "firefox" => { history: "places.sqlite", bookmarks: "places.sqlite" },
+          "safari" => { history: "History.db", bookmarks: "Bookmarks.plist" }
+        }.freeze
+
+        # Relative to the user's home. The first existing root wins, so a
+        # macOS path and a Linux path can share one entry.
+        ROOTS = {
+          "chrome" => ["Library/Application Support/Google/Chrome", ".config/google-chrome"],
+          "edge" => ["Library/Application Support/Microsoft Edge", ".config/microsoft-edge"],
+          "brave" => ["Library/Application Support/BraveSoftware/Brave-Browser", ".config/BraveSoftware/Brave-Browser"],
+          "arc" => ["Library/Application Support/Arc/User Data"],
+          "firefox" => ["Library/Application Support/Firefox", ".mozilla/firefox"],
+          "safari" => ["Library/Safari"]
+        }.freeze
+
+        # Default order when `--browser` isn't given. Safari is last: on
+        # macOS its directory exists whether or not the user uses it, and
+        # it's the only one that needs Full Disk Access.
+        BROWSERS = %w[chrome arc brave edge firefox safari].freeze
+
+        def self.family(browser)
+          return "chromium" if CHROMIUM.include?(browser)
+
+          browser
+        end
+
+        # @return [String, nil] the first root that exists for `browser`.
+        def self.default_root(browser, home: Dir.home)
+          ROOTS.fetch(browser, []).map { |rel| File.join(home, rel) }.find { |path| File.directory?(path) }
+        end
+
+        # @return [String, nil] the first browser in BROWSERS with a root on
+        #   this machine.
+        def self.detect(home: Dir.home) = BROWSERS.find { |b| default_root(b, home: home) }
+
+        # @param root [String] the browser's profile root — injectable so
+        #   specs (and a live check) point at a fixture or a specific copy.
+        # @return [Array<Profile>] every profile under `root` holding at
+        #   least one of the allowed files.
+        def self.locate(browser, root:)
+          family = family(browser)
+          return [] unless ALLOWED_FILES.key?(family) && root && File.directory?(root)
+
+          profile_dirs(family, root).filter_map { |dir| profile_for(browser, family, dir) }
+        rescue Errno::EPERM, Errno::EACCES => e
+          # macOS privacy protection (or a sandbox) refusing even the root
+          # listing — reported, never worked around (see Importer).
+          raise Sqlite::PermissionDenied, e.message
+        end
+
+        # The only directory listing in this module: the profile root's own
+        # folder names. Safari has no per-profile folders — its root *is*
+        # the profile, so nothing is listed there at all.
+        def self.profile_dirs(family, root)
+          case family
+          when "chromium" then Dir.glob(File.join(root, "{Default,Profile *}"))
+          when "firefox"
+            profiles = File.directory?(File.join(root, "Profiles")) ? File.join(root, "Profiles") : root
+            Dir.glob(File.join(profiles, "*")).select { |d| File.directory?(d) }.sort
+          else [root]
+          end
+        end
+        private_class_method :profile_dirs
+
+        def self.profile_for(browser, family, dir)
+          files = ALLOWED_FILES.fetch(family)
+          history = existing(dir, files[:history])
+          bookmarks = existing(dir, files[:bookmarks])
+          return nil unless history || bookmarks
+
+          Profile.new(browser: browser, family: family, dir: dir, history: history, bookmarks: bookmarks)
+        end
+        private_class_method :profile_for
+
+        # A stat, never an open — File.exist? on a name from ALLOWED_FILES
+        # only.
+        def self.existing(dir, name)
+          path = File.join(dir, name)
+          File.exist?(path) ? path : nil
+        end
+        private_class_method :existing
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_import/readers.rb

@@ -0,0 +1,179 @@
+require "json"
+require "open3"
+require "tmpdir"
+require "fileutils"
+
+require_relative "sqlite"
+require_relative "plist_xml"
+
+module Portage
+  module Cli
+    module BrowserImport
+      # One reader per browser family. Each turns a Profiles::Profile into
+      # plain rows — `{ kind: "history"|"bookmark", url:, title:, folder:,
+      # visits: }` — and reads nothing but that profile's own allowed files
+      # (Profiles::ALLOWED_FILES). A row is just what the browser recorded;
+      # reducing it to a domain, filtering and probing is Importer's job.
+      module Readers
+        # Seconds between the Unix epoch and each browser's own clock:
+        # Chromium counts microseconds from 1601-01-01, Safari (Core Data)
+        # seconds from 2001-01-01, Firefox microseconds from the Unix epoch.
+        WEBKIT_EPOCH_OFFSET = 11_644_473_600
+        CORE_DATA_EPOCH_OFFSET = 978_307_200
+
+        def self.for(family, sqlite: Sqlite.new, plist: Plist.new)
+          case family
+          when "chromium" then Chromium.new(sqlite: sqlite)
+          when "firefox" then Firefox.new(sqlite: sqlite)
+          when "safari" then Safari.new(sqlite: sqlite, plist: plist)
+          end
+        end
+
+        def self.row(kind, url, title: nil, folder: nil, visits: 1)
+          { kind: kind, url: url.to_s, title: title.to_s.strip, folder: folder.to_s.strip,
+            visits: [visits.to_i, 1].max }
+        end
+
+        # `History` (SQLite, copied first — Chrome keeps it locked) and
+        # `Bookmarks` (plain JSON, read in place: it's rewritten whole, never
+        # held open).
+        class Chromium
+          def initialize(sqlite:)
+            @sqlite = sqlite
+          end
+
+          def history(profile, since:)
+            return [] unless profile.history
+
+            cutoff = (since.to_i + WEBKIT_EPOCH_OFFSET) * 1_000_000
+            sql = "SELECT url, title, visit_count AS visits FROM urls WHERE last_visit_time >= #{cutoff}"
+            @sqlite.with_copy(profile.history) { |query| query.call(sql) }
+                   .map { |r| Readers.row("history", r["url"], title: r["title"], visits: r["visits"]) }
+          end
+
+          def bookmarks(profile)
+            return [] unless profile.bookmarks
+
+            data = JSON.parse(File.read(profile.bookmarks, encoding: "UTF-8"))
+            Hash(data["roots"]).values.grep(Hash).flat_map { |node| walk(node, nil) }
+          rescue JSON::ParserError
+            []
+          rescue Errno::EPERM, Errno::EACCES => e
+            raise Sqlite::PermissionDenied, e.message
+          end
+
+          private
+
+          def walk(node, folder)
+            if node["type"] == "url"
+              [Readers.row("bookmark", node["url"], title: node["name"], folder: folder)]
+            else
+              Array(node["children"]).flat_map { |child| walk(child, node["name"]) }
+            end
+          end
+        end
+
+        # `places.sqlite` holds both history and bookmarks — one copy, two
+        # queries.
+        class Firefox
+          def initialize(sqlite:)
+            @sqlite = sqlite
+          end
+
+          def history(profile, since:)
+            return [] unless profile.history
+
+            sql = "SELECT url, title, visit_count AS visits FROM moz_places " \
+                  "WHERE last_visit_date >= #{since.to_i * 1_000_000}"
+            @sqlite.with_copy(profile.history) { |query| query.call(sql) }
+                   .map { |r| Readers.row("history", r["url"], title: r["title"], visits: r["visits"]) }
+          end
+
+          def bookmarks(profile)
+            return [] unless profile.bookmarks
+
+            sql = "SELECT p.url AS url, b.title AS title, f.title AS folder FROM moz_bookmarks b " \
+                  "JOIN moz_places p ON p.id = b.fk LEFT JOIN moz_bookmarks f ON f.id = b.parent WHERE b.type = 1"
+            @sqlite.with_copy(profile.bookmarks) { |query| query.call(sql) }
+                   .map { |r| Readers.row("bookmark", r["url"], title: r["title"], folder: r["folder"]) }
+          end
+        end
+
+        # `History.db` (SQLite) and `Bookmarks.plist` (binary plist). Both
+        # sit under ~/Library/Safari, which macOS guards behind Full Disk
+        # Access — a copy attempt without it raises Sqlite::PermissionDenied,
+        # which Importer turns into an explanation, never a workaround.
+        class Safari
+          def initialize(sqlite:, plist:)
+            @sqlite = sqlite
+            @plist = plist
+          end
+
+          def history(profile, since:)
+            return [] unless profile.history
+
+            cutoff = since.to_i - CORE_DATA_EPOCH_OFFSET
+            sql = "SELECT i.url AS url, v.title AS title, i.visit_count AS visits, MAX(v.visit_time) AS latest " \
+                  "FROM history_items i JOIN history_visits v ON v.history_item = i.id " \
+                  "WHERE v.visit_time >= #{cutoff} GROUP BY i.id"
+            @sqlite.with_copy(profile.history) { |query| query.call(sql) }
+                   .map { |r| Readers.row("history", r["url"], title: r["title"], visits: r["visits"]) }
+          end
+
+          def bookmarks(profile)
+            return [] unless profile.bookmarks
+
+            walk(@plist.read(profile.bookmarks), nil)
+          end
+
+          private
+
+          def walk(node, folder)
+            return [] unless node.is_a?(Hash)
+
+            if node["URLString"]
+              title = Hash(node["URIDictionary"])["title"]
+              [Readers.row("bookmark", node["URLString"], title: title, folder: folder)]
+            else
+              Array(node["Children"]).flat_map { |child| walk(child, node["Title"]) }
+            end
+          end
+        end
+
+        # Reads a (binary or XML) plist: copies it into a private tmpdir,
+        # converts the copy to XML with macOS's own `plutil`, parses it with
+        # PlistXml, and deletes the copy.
+        class Plist
+          def initialize(command: "plutil")
+            @command = command
+          end
+
+          def read(path)
+            Dir.mktmpdir("portage-browser-import") do |dir|
+              copy = File.join(dir, "copy.plist")
+              copy_file(path, copy)
+              PlistXml.parse(convert(copy))
+            end
+          end
+
+          private
+
+          def copy_file(path, copy)
+            FileUtils.cp(path, copy)
+          rescue Errno::EPERM, Errno::EACCES => e
+            raise Sqlite::PermissionDenied, e.message
+          end
+
+          def convert(copy)
+            out, err, status = Open3.capture3(@command, "-convert", "xml1", "-o", "-", copy)
+            raise Sqlite::Unavailable, "plutil failed: #{err.strip}" unless status.success?
+
+            out.dup.force_encoding("UTF-8").scrub
+          rescue Errno::ENOENT
+            raise Sqlite::Unavailable, "the plutil command isn't available (it ships with macOS)"
+          end
+        end
+      end
+    end
+  end
+end