portage-cli 0.7.4 → 0.8.0

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

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

@@ -0,0 +1,62 @@
+require_relative "categorize"
+
+module Portage
+  module Cli
+    module BrowserImport
+      # Writes an approved Importer#plan into the user's own index — only
+      # ever called after BrowserImport::Confirm said :save. A kept domain
+      # becomes an Index::Store entry with `sources: ["history"]`/
+      # `["bookmark"]`; one already in the index just gains those labels
+      # and the new category weights (its capabilities and last_verified
+      # are left for `index refresh` to re-check, same as Index::Builder's
+      # #update_existing). A domain kept because the published
+      # known-stores list already had it keeps that list's own
+      # last_verified — this import never probed it. A kept product page becomes an
+      # Index::ProductStore entry with the same `sources` labels, so
+      # Index::Exporter never publishes it.
+      class Saver
+        def initialize(stores:, products:, now: Time.now)
+          @stores = stores
+          @products = products
+          @now = now
+        end
+
+        # @return [Hash] stores:, products: — how many entries were written.
+        def save(plan)
+          kept = Array(plan[:kept])
+          products = Array(plan[:products])
+          kept.each { |entry| save_store(entry) }
+          products.each { |product| save_product(product) }
+          { stores: kept.length, products: products.length }
+        end
+
+        private
+
+        def save_store(entry)
+          existing = @stores.find(entry[:origin])
+          fields = { sources: (Array(existing && existing["sources"]) + entry[:sources]).uniq,
+                     categories: merge_categories(existing && existing["categories"], entry[:categories]) }
+          fields.merge!(new_store_fields(entry)) unless existing
+          @stores.upsert(entry[:origin], **fields)
+        end
+
+        def new_store_fields(entry)
+          { platform: nil, capabilities: Array(entry[:capabilities]), webmcp_preset: entry[:webmcp_preset],
+            last_verified: entry[:last_verified] || @now.to_i, handoff_only: entry[:handoff_only] ? true : false }
+        end
+
+        def merge_categories(existing, fresh)
+          tally = Hash.new(0)
+          [existing, fresh].each { |cats| Hash(cats).each { |id, weight| tally[id.to_s] += weight.to_i } }
+          tally.sort_by { |_id, weight| -weight }.first(Categorize::TOP_CATEGORIES).to_h
+        end
+
+        def save_product(product)
+          @products.upsert(product[:key], origin: product[:origin], seen_at: @now.to_i, title: product[:title],
+                                          brand: nil, gtin: nil, category: product[:category],
+                                          sources: [product[:source]])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+require "json"
+require "open3"
+require "tmpdir"
+require "fileutils"
+
+module Portage
+  module Cli
+    module BrowserImport
+      # Reads a browser's SQLite history database without a native gem:
+      # the database (plus its `-wal` file, when the browser left one — it
+      # holds the most recent visits until the next checkpoint) is copied
+      # into a private tmpdir first, since a running browser holds it
+      # locked, and the copy is queried with the system `sqlite3` CLI in
+      # `-readonly -json` mode. The copy is deleted before this returns,
+      # success or not. The original file is only ever read by the copy.
+      #
+      # `sqlite3` ships with macOS and every mainstream Linux distro; when
+      # it's missing, Unavailable says so rather than falling back to
+      # anything else.
+      class Sqlite
+        class Unavailable < StandardError; end
+
+        # Raised when macOS refuses to let this process read the file at
+        # all (Safari's History.db without Full Disk Access). Never worked
+        # around — see Importer's own handling.
+        class PermissionDenied < StandardError; end
+
+        # @param command [String] the sqlite3 executable — injectable so a
+        #   spec can prove the missing-binary path without uninstalling it.
+        def initialize(command: "sqlite3")
+          @command = command
+        end
+
+        # Copies `path` once and yields a query proc, so one copy serves
+        # several queries (Firefox's history and bookmarks both live in
+        # places.sqlite).
+        # @yieldparam query [Proc] `query.call(sql)` => Array<Hash>
+        def with_copy(path)
+          Dir.mktmpdir("portage-browser-import") do |dir|
+            copy = copy_database(path, dir)
+            yield ->(sql) { run(copy, sql) }
+          end
+        end
+
+        private
+
+        def copy_database(path, dir)
+          copy = File.join(dir, "copy.sqlite")
+          FileUtils.cp(path, copy)
+          FileUtils.cp("#{path}-wal", "#{copy}-wal") if File.exist?("#{path}-wal")
+          copy
+        rescue Errno::EPERM, Errno::EACCES => e
+          raise PermissionDenied, e.message
+        end
+
+        def run(copy, sql)
+          out, err, status = Open3.capture3(@command, "-readonly", "-json", copy, sql)
+          raise Unavailable, "sqlite3 failed: #{err.strip}" unless status.success?
+
+          text = out.dup.force_encoding("UTF-8").scrub
+          text.strip.empty? ? [] : JSON.parse(text)
+        rescue Errno::ENOENT
+          raise Unavailable, "the sqlite3 command isn't installed (it ships with macOS and most Linux distros)"
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_import.rb

@@ -0,0 +1,23 @@
+require_relative "browser_import/filter"
+require_relative "browser_import/profiles"
+require_relative "browser_import/sqlite"
+require_relative "browser_import/plist_xml"
+require_relative "browser_import/readers"
+require_relative "browser_import/prober"
+require_relative "browser_import/importer"
+require_relative "browser_import/confirm"
+
+module Portage
+  module Cli
+    # `portage browser import` — bookmarks and history as index seeds
+    # (docs/plans/buy-skill-and-local-browser.md Phase 3, Tier A). Opt-in,
+    # local-only, reduced to shop domains, and shown to the user before
+    # anything is saved. Never reads a browser's password, cookie or
+    # autofill store (see Profiles::ALLOWED_FILES), never attaches to or
+    # drives the browser, and never sends anything about the user's
+    # history anywhere except one `/.well-known/ucp` probe per unknown
+    # domain (Prober).
+    module BrowserImport
+    end
+  end
+end

data/lib/portage/cli/browser_profile/allowlist.rb

@@ -0,0 +1,40 @@
+require_relative "../handoff_only"
+
+module Portage
+  module Cli
+    module BrowserProfile
+      # The domain allowlist Phase 6 requires: driving the profile browser
+      # (evaluating WebMCP tool calls, filling checkout fields, navigating)
+      # is limited to the store being bought from, plus its checkout host
+      # once one is known. Anything else stops the run — see Bridge and
+      # DomainNotAllowedError.
+      #
+      # Reuses HandoffOnly's own host normalization/matching (a base host
+      # matches itself or any subdomain, "www." stripped, a full URL or a
+      # bare host both accepted) rather than a second copy of that logic.
+      class Allowlist
+        def initialize(hosts: [])
+          @hosts = hosts.filter_map { |h| HandoffOnly.normalize_entry(h) }
+        end
+
+        def hosts = @hosts.dup
+
+        def allowed?(host) = HandoffOnly.matches_any?(host, @hosts)
+
+        # Adds a host once it's known to be exactly what Portage itself is
+        # deliberately navigating to (the checkout URL a hand-off is about
+        # to open) — never called for a navigation a driven page made on
+        # its own; that's what #allowed? guards against.
+        # @return [String, nil] the normalized host that was added (or
+        #   already present), nil when `host_or_url` didn't parse to one.
+        def permit!(host_or_url)
+          normalized = HandoffOnly.normalize_entry(host_or_url)
+          return nil unless normalized
+
+          @hosts << normalized unless @hosts.include?(normalized)
+          normalized
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_profile/bridge.rb

@@ -0,0 +1,120 @@
+require "uri"
+require_relative "allowlist"
+require_relative "errors"
+
+module Portage
+  module Cli
+    module BrowserProfile
+      # docs/plans/buy-skill-and-local-browser.md Phase 6: the WebMCP
+      # bridge `Cli.run_buy` hands to `Buy.new(webmcp_bridge:)` when
+      # `--handoff-target profile` — the Portage browser profile's own
+      # page target, reached over CdpSocket, wrapped so every call stays
+      # inside the domain allowlist. Everything WebMCP-shaped (#list_tools,
+      # #execute_tool, #autofill) is delegated to a real
+      # Portage::Ucp::WebMcp::Bridges::ScriptEvaluator built from this
+      # bridge's own #evaluate — this class exists to add exactly two
+      # things ScriptEvaluator doesn't have: the allowlist check on every
+      # call, and #navigate (Portage's own deliberate navigation to a
+      # checkout URL, as opposed to a page-driven one).
+      #
+      # Requires `portage-ucp-webmcp` to already be loaded — only ever
+      # built by `Cli.run_buy` after `Portage::Cli::Webmcp.available?`,
+      # same guard every other WebMCP call site in this gem already uses
+      # (see Buy#webmcp_flow) — so nothing here calls `require` itself.
+      #
+      # #headless? is always false: this is, by construction, a headed
+      # browser the shopper can see and pay in (WebMcp::Autofill's own
+      # `headless?(bridge)` check — see docs/plans/
+      # webmcp-universal-outbound.md Phase 3 — never returns
+      # :needs_headed_browser for it).
+      class Bridge
+        def initialize(socket:, allowlist:)
+          @socket = socket
+          @allowlist = allowlist
+          @page_enabled = false
+        end
+
+        def headless? = false
+
+        def location
+          raw_evaluate("Promise.resolve(window.location.href)")
+        end
+
+        # Portage's own navigation — to the checkout URL a hand-off is
+        # about to show the shopper. Permits that URL's host first (this
+        # is exactly "the store's checkout host" the allowlist is meant to
+        # grow to include, per the plan), then navigates.
+        def navigate(url)
+          host = URI.parse(url.to_s).host
+          @allowlist.permit!(host)
+          ensure_page_enabled!
+          @socket.call("Page.navigate", "url" => url.to_s)
+          nil
+        end
+
+        def list_tools = script_evaluator.list_tools
+        def execute_tool(name, input) = script_evaluator.execute_tool(name, input)
+        def autofill(fields, selectors: {}) = script_evaluator.autofill(fields, selectors: selectors)
+
+        private
+
+        def script_evaluator
+          @script_evaluator ||= Portage::Ucp::WebMcp::Bridges::ScriptEvaluator.new(evaluate: method(:evaluate),
+                                                                                   headless: false)
+        end
+
+        # Every driven call (a WebMCP tool call, an autofill attempt)
+        # checks the page's *current* location against the allowlist
+        # before running — including a navigation a previous call already
+        # caused (e.g. a preset's handoff_checkout tool navigating to
+        # checkout): that navigation's own evaluate call already ran
+        # before the page moved, so this is the first following call that
+        # can actually see where it ended up. That's the plan's "stops the
+        # run" in practice — a driven page that jumps somewhere unexpected
+        # is caught on its very next use, not mid-navigation (there's no
+        # navigation-event hook in this minimal a CDP client).
+        def evaluate(expression)
+          enforce_allowlist!
+          raw_evaluate(expression)
+        end
+
+        def enforce_allowlist!
+          host = current_host
+          return if @allowlist.allowed?(host)
+
+          raise DomainNotAllowedError,
+                "the profile browser navigated to #{host.inspect}, outside the allowed domains " \
+                "(#{@allowlist.hosts.join(', ')}) — stopping"
+        end
+
+        def current_host
+          URI.parse(raw_evaluate("Promise.resolve(window.location.href)").to_s).host
+        rescue URI::InvalidURIError
+          nil
+        end
+
+        def raw_evaluate(expression)
+          response = @socket.call("Runtime.evaluate", "expression" => expression, "awaitPromise" => true,
+                                                      "returnByValue" => true, "userGesture" => true)
+          raise_on_exception!(response)
+          response.dig("result", "value")
+        end
+
+        def raise_on_exception!(response)
+          details = response["exceptionDetails"]
+          return unless details
+
+          text = details.dig("exception", "description") || details["text"] || "script evaluation failed"
+          raise Portage::Ucp::WebMcp::BridgeError, text
+        end
+
+        def ensure_page_enabled!
+          return if @page_enabled
+
+          @socket.call("Page.enable", {})
+          @page_enabled = true
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_profile/browsers.rb

@@ -0,0 +1,69 @@
+require_relative "../browser_import/profiles"
+
+module Portage
+  module Cli
+    module BrowserProfile
+      # Where to find a Chromium-family browser's own executable, and
+      # which family is supported at all (docs/plans/
+      # buy-skill-and-local-browser.md Phase 6). Firefox/Safari are out of
+      # scope for driving (see the plan's Phase 6 section) even though
+      # BrowserImport::Profiles already knows their profile roots — this
+      # module only ever launches one of CHROMIUM.
+      module Browsers
+        CHROMIUM = BrowserImport::Profiles::CHROMIUM
+
+        # macOS app bundle executables. The first existing path wins.
+        MAC_APPS = {
+          "chrome" => "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+          "edge" => "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+          "brave" => "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+          "arc" => "/Applications/Arc.app/Contents/MacOS/Arc"
+        }.freeze
+
+        # Linux binary names, tried on PATH. Arc has no Linux build.
+        LINUX_BINARIES = {
+          "chrome" => %w[google-chrome google-chrome-stable chromium chromium-browser],
+          "edge" => %w[microsoft-edge microsoft-edge-stable],
+          "brave" => %w[brave-browser brave-browser-stable],
+          "arc" => []
+        }.freeze
+
+        # @param path [String] PATH-shaped, injectable so a spec can point
+        #   ".which" at a fixture directory instead of mutating ENV.
+        # @return [String, nil] the first launchable binary for `browser`
+        #   on this machine, or nil when it isn't installed.
+        def self.binary_for(browser, darwin: RUBY_PLATFORM.include?("darwin"), path: ENV.fetch("PATH", ""))
+          mac_binary(browser, darwin) || linux_binary(browser, path)
+        end
+
+        def self.mac_binary(browser, darwin)
+          return nil unless darwin
+
+          path = MAC_APPS[browser]
+          path if path && File.exist?(path)
+        end
+        private_class_method :mac_binary
+
+        def self.linux_binary(browser, path)
+          LINUX_BINARIES.fetch(browser, []).filter_map { |name| which(name, path) }.first
+        end
+        private_class_method :linux_binary
+
+        def self.which(cmd, path)
+          path.split(File::PATH_SEPARATOR).map { |dir| File.join(dir, cmd) }
+                                          .find { |candidate| File.file?(candidate) && File.executable?(candidate) }
+        end
+        private_class_method :which
+
+        # @return [String, nil] the first CHROMIUM browser that's actually
+        #   installed on this machine, reusing BrowserImport::Profiles's
+        #   own "does this browser's default profile root exist" check
+        #   purely as an installed-or-not signal — nothing under that root
+        #   is ever read here.
+        def self.detect(home: Dir.home)
+          CHROMIUM.find { |b| BrowserImport::Profiles.default_root(b, home: home) }
+        end
+      end
+    end
+  end
+end