portage-cli 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4200c871324b9f35de00e58c32177ec087c9922b3adda2ae45aa1b4673478f1
-  data.tar.gz: e719be3b212a547be84ff5fa1232b08303c96288b7acf60f0fd9c2f1982fa0ef
+  metadata.gz: 7c58c0040e6d1f58b5cf9dbbe64c91273c198a4cfc8119477e1fcbbf04c4c4dd
+  data.tar.gz: ba48da2d241487885a286eb8044e493f6727b7e7d4b96f3b9dc7d748b1644f67
 SHA512:
-  metadata.gz: 3bb580b0b6ac745462ecc241b4e151fa16c2a8651ac32aa6d53c84aca0b910da6095182680b6a832b3431539904a697332279de9b9340fb491581821eccf6519
-  data.tar.gz: 7a75983b229489dc8519caa7a176122b00c8f41f56922f4b373c551a9ab044dace860f7ecdd6ba93d63feddf84177391d3ae92f13a6280acd138e704590ea4f3
+  metadata.gz: 388d5ea84ba8ba1279862b57b07cf36db2164cec50752638ae3eb2d924fd81c56a569ea2d107994fc56f3d1989ab0d5b567fed3e0a12e9b3e7c65a291b95e198
+  data.tar.gz: fd18e9aa2c798935143742e961936c359ff68722a3f8bad2f20489322456df3467f042ef9c653a4f72f167fc4a765a08bd81680e01ec6c2a0b26fb0ce934b477

data/CHANGELOG.md

@@ -6,6 +6,103 @@ pre-1.0, so APIs may still shift between minor versions.
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-10-05
+
+- **Fix: `payment_methods` adapter fallback no longer silently fails.** `PaymentMethods#adapter_session` referenced `Buy::PermissiveAuthenticator`, which doesn't exist (the class is `Portage::Cli::PermissiveAuthenticator`); the resulting `NameError` was swallowed by the method's `rescue StandardError`, so enrolling against your own adapter-backed store always reported no session. It now requires and uses the right constant. Patch-level bug fix.
+
+- Documentation only, no code change. Comments and changelog entries that cited `docs/plans/homebrew-distribution.md`, which is retired, now cite a permalink at commit d51200f. Patch-level.
+
+- **Removed `Portage::Cli::BrowserProfile::Cdp.close_tab`.** Nothing in the CLI called it. It is a public class method, so this is **breaking** for any caller using it directly; minor-level for a pre-1.0 gem.
+
+- Internal: the Shipping, SearchKeys and RetailerKeys setup-wizard steps now share one `SetupWizard::Steps::EnvKeysStep` base class instead of three copies of the same prompt-and-save body. No behaviour change.
+
+- **`portage browser import` no longer needs the `sqlite3` command-line tool.** It reads the copied Chromium, Firefox and Safari history databases through the `sqlite3` gem, which `portage-cli` already depends on for the local index, instead of shelling out to the system `sqlite3` CLI. The copy-to-tmpdir step (with the `-wal` file) and the UTF-8 scrub are unchanged. `error: "reader_unavailable"` now means a SQLite error reading the copy (for example a corrupt or non-SQLite file) or, for Safari bookmarks, a missing `plutil`; `docs/api/cli-json.md` and the `buy` skill's `references/outcomes.md` say so. `BrowserImport::Sqlite.new` no longer takes a `command:` keyword (it only existed for a spec), which is **breaking** for any caller passing it; minor-level for a pre-1.0 gem.
+
+- **Fix: `payment_methods` enroll now finds your own store when its homepage redirects** (for example apex to `www`). The adapter fallback's homepage fetch followed no redirects; it now follows up to five, like `buy`'s, and every hop stays on the `payment` proxy route (forced direct unless a proxy is named for it). Internally, `PaymentMethods` and `HandoffReconciler` now share one `Cli::AdapterSession` for that fallback, and `HomepageFetch.call` takes a `route:` keyword (default `:store`). Patch-level.
+
+- Internal: `HandoffAgents::Webhook` and `Notifier` now make their JSON POST through one `Notifier.post_json` class method instead of two copies. Timeouts, the agent webhook's https-only check and the error messages are unchanged, and the agent webhook still never falls back to `PORTAGE_NOTIFY_WEBHOOK_URL`. No behaviour change.
+
+- Internal: `BrowserImport::PlistXml` decodes entities with `CGI.unescapeHTML` (from the default `cgi/escape` library) instead of its own table. The same for the five named entities and decimal and hex character references; an uppercase `A` now decodes (it used to become NUL) and an out-of-range code point is left as written (it used to raise `RangeError`). No gemspec change.
+
+- Internal: the private `Cli.format_amount` wrapper is gone; its four callers in `cli.rb` call `Cli::Money.format_amount` directly. No behaviour change.
+
+## [0.12.0] - 2026-10-01
+
+- **Release note: the confidence check wants `portage-ucp-decision` 0.1.2.** `portage-ucp-decision` stays an optional install, not a dependency, but 0.1.2 is the version that rejects a malformed backend answer (see its changelog); the README says so.
+
+- **`find --store URL --query Q [--max-price N]` searches one store, live.** The index-search hint, the `buy` skill and the docs already told agents to re-check an index hit this way, but `find` had no `--store`. It now skips the search backends and retailer offer sources and probes and searches only that store's catalogue (read-only: never a cart or checkout), with offers, `offer_ref`, `search_id` and the history entry shaped like any find, so `pick` and `buy --offer` work on them. A hand-off-only host is never fetched and is reported as such; a store without UCP is reported as having no catalogue; a non-http(s) URL is a usage error. The index-search hint now reads `find --store URL --query ...`.
+
+- **Security: a priced line nobody asked for is a checkout mismatch.** `buy` requests exactly one
+  line, but only checked that line, so a store that added an upsell, a "shipping protection"
+  add-on or a second copy of the item (or, on a WebMCP cart, whatever was already in the store's
+  cart) still went through. Any other line now stops a real run with `checkout_mismatch` ("Store
+  added ... to checkout, which wasn't requested."), and a dry run flags it with
+  `checkout_mismatch: true`. An extra line that costs nothing (its own total, or its unit price
+  times quantity, is 0) is allowed, so a free gift or $0 sample doesn't block a purchase; one
+  whose cost can't be read counts as priced.
+
+- **Security: the confidence check sends an allowlisted summary, and compares against the
+  approved quote.** The state sent to the decision backend (`PORTAGE_DECISION_BACKEND`, e.g.
+  `jev`, TypeSafe's hosted API) used to be a slice of the raw checkout hash, so whatever a store
+  nested under `line_items` or `totals` went along with it. It is now built field by field by the
+  new `Portage::Cli::ConfidenceState`: the request (query, store host, quantity, picked item id
+  and title), on a `buy --quote` run the approved quote (store, product id, title, quantity,
+  total, currency), and the checkout's status, currency, per-line item id, title, unit price,
+  quantity, totals and whether it's the requested line, the totals (shipping, tax, fees included),
+  applied discounts' titles and amounts and the selected shipping option's title and price, plus
+  `warnings`. Never the payment token, the address, the buyer's name, phone or email, ids, links,
+  discount codes or environment values; store strings are cut to 200 characters. The question
+  now asks the model to say yes only when the checkout matches the request and the approved
+  quote. `Buy.new` takes `quote_store:` and `quote_title:`, which `buy --quote` passes from the
+  saved quote. The check stays additive: it only sees a checkout the mismatch check, the quote
+  cap and the spend policy let through, and can hold it but never let through one they stop.
+
+- **Security: the non-preset WebMCP hand-off runs the confidence check too.** A page whose WebMCP
+  tools build a checkout (no preset, so `buy` ends in `express_stop` through `finish_checkout`)
+  applied the quote cap and the mismatch stop but not the opt-in confidence check. With a decision
+  backend enabled it now runs before the hand-off, after those two. A hold reports `low_confidence`
+  with the store's `/cart` page as `checkout_url`, as the preset flow's does, and nothing is handed
+  to the checkout (a `profile` target is not navigated there). A backend error holds the same way.
+  No backend enabled: unchanged.
+
+- **Security: the WebMCP hand-off flow runs the quote cap and the confidence check.** Against a
+  page whose preset opens checkout through its own tool (Shopify's `proceed_to_checkout`), `buy`
+  now checks, before that tool runs and before autofill: a `--quote` run's cap (`quote_changed`,
+  never handed off; this flow never checked the quote before), the mismatch check, then, when a
+  decision backend is enabled, the confidence check. A hold reports `low_confidence` with the
+  store's `/cart` page as `checkout_url`; checkout isn't opened and nothing is autofilled. A
+  backend error holds the same way.
+
+- **Security: a quote with no total refuses instead of buying uncapped.** `buy --quote` capped the
+  checkout at the quote's total only when the quote had one. A quote saved from a dry run with no
+  priced total (a WebMCP preset dry run never has one) set no cap at all, so its `--yes` run
+  bought at whatever the store asked. It now ends in `quote_changed`, saying the quote has no
+  total, and nothing is bought or handed off.
+
+- **Security: a checkout mismatch always stops the purchase.** `buy` used to stop on a checkout
+  that didn't match the request (the item dropped, another quantity, another unit price) only under
+  `PORTAGE_ABORT_ON_CHECKOUT_MISMATCH`. Without it the mismatch was a `warnings` entry and the
+  purchase went ahead, so a real `--yes` run could pay for the wrong checkout and report
+  `purchased` (reported by ClawHub's security audit of the `portage-buy` skill). Now every
+  mismatch on a run that isn't `--dry-run` escalates (`decisions.escalation.reason: "mismatch"`)
+  and ends in `checkout_mismatch` before the payment token, policy and completion are reached. The
+  quote it ran under is spent, so the person dry-runs again for a new one. There is no opt-out:
+  `PORTAGE_ABORT_ON_CHECKOUT_MISMATCH` is deprecated and ignored, whatever its value. A
+  `--dry-run` keeps its `dry_run` outcome and `warnings`, and now adds `checkout_mismatch: true`
+  and says in `message` that a real run would stop. The check also compares currency: a checkout
+  in another currency than the catalog's price is a mismatch. The quoted total and currency are
+  still `--quote`'s `quote_changed` check, unchanged.
+
+- **Security: the WebMCP hand-off flow stops on a mismatched cart too.** Against a WebMCP page
+  whose preset opens checkout through its own tool (Shopify's `proceed_to_checkout`), `buy` read
+  the cart back and checked it, but only put a mismatch in `warnings`: it still called the hand-off
+  tool, sending the browser tab to the store's checkout, and ran autofill there when it was
+  approved. Now any mismatch stops the run before that tool, with outcome `checkout_mismatch` and
+  `decisions.escalation.reason: "mismatch"`. Nothing is autofilled, and `checkout_url` is the
+  store's `/cart` page, so the shopper can look at the cart that was built. A matching cart hands
+  off as `express_stop`, as before. The dry run of this flow builds no cart, so it can't check one
+  and never carries `checkout_mismatch: true`.
+
 ## [0.11.0] - 2026-10-01
 
 - **Category classification uses the whole taxonomy.** `known-stores/categories.yml` is now generated
@@ -708,7 +805,7 @@ pre-1.0, so APIs may still shift between minor versions.
 ## [0.7.4] - 2026-09-25
 
 - **`portage doctor` reports how it was installed, and warns when another
-  `portage` shadows it** (`docs/plans/homebrew-distribution.md` Phase 4).
+  `portage` shadows it** ([plan](https://github.com/tomtom87/Portage/blob/d51200f/docs/plans/homebrew-distribution.md) Phase 4).
   New findings, all offline and without shelling out to `brew`:
   - `install`: `homebrew` (with the Cellar keg) when this gem or its Ruby
     lives under `HOMEBREW_PREFIX/Cellar/portage/` (`$HOMEBREW_PREFIX`,

data/README.md

@@ -29,6 +29,20 @@ portage find --query "burton snowboard" --max-price 400
 
 `portage buy` with no URL runs that search and then buys the offer you pick.
 
+Already know the store? `portage find --store URL --query "..."` skips the search
+backends and offer sources and searches only that store's catalogue, live and
+read-only (catalogue search only, never a cart or checkout). Use it to re-check
+an index hit or an earlier offer before quoting its price or stock. The report
+has the same shape as a normal find (`offer_ref`, `search_id`, a history entry),
+so `pick` and `buy --offer` work on its offers. A hand-off-only host is never
+fetched and is reported as such; a store that doesn't speak UCP is reported as
+having no catalogue, with exit code 1 (as for any find with no offers). `--store`
+must be an http(s) URL (a bare host is read as https).
+
+```bash
+portage find --store https://shop.example --query "cold brew" --json
+```
+
 Already have the item and want to know where else it's sold? `portage compare`
 resolves a product you name by URL + product id, then runs the same
 find pipeline against its title and ranks the results by how confident the
@@ -131,6 +145,7 @@ portage buy --offer REF [--qty N] [--yes] [--dry-run] ...
 portage buy --quote QUOTE_ID --yes [--json] ...
 portage buy --query "..." [--store URL] [--max-price N] [--limit N] ...
 portage find --query "..." [--max-price N] [--limit N] [--json]
+portage find --store URL --query "..." [--max-price N] [--json]
 portage compare <url> --product-id ID [--id VALUE ...] [--results N]
                        [--max-price N] [--json]
 portage check <url> [--json]
@@ -497,7 +512,7 @@ probes per run), throttled, with progress output. Sources:
 | --- | --- | --- |
 | `shopify_catalog` | Merchant origins and product identities, one query per top-level taxonomy node, from `catalog.shopify.com`'s open catalog | on |
 | `stores_file` | Your own `~/.portage/stores.yml` | on |
-| `browser` | Whatever `portage browser import` (below) already saved — this source itself never reads a browser | on, but yields nothing unless you've run `browser import` |
+| `browser` | Whatever `portage browser import` (below) already saved — this source itself never reads a browser | opt-in (`--sources browser`); yields nothing unless you've run `browser import` |
 | `wikidata` | Retailers'/brands' official sites via a public SPARQL query | opt-in (`--sources wikidata`) |
 | `webmcp_sweep` | Which WebMCP preset an origin matches, when a bridge is attached | opt-in, needs a bridge |
 | `storefront_products` | Each indexed Shopify store's own `/products.json`: title, brand, handle, URL, first image, options and variant ids, mapped through the UCP `Product` shape with price and availability dropped | opt-in (`--sources storefront_products`, or `index add URL --crawl`) |
@@ -811,6 +826,30 @@ checkout tool (Shopify's `proceed_to_checkout`) stops after the read-only
 product search: nothing is added to the store's cart, the tab isn't sent to
 checkout and nothing is autofilled. The `dry_run` report carries a `would:`
 key with the line item, the hand-off tool and whether autofill would run.
+Because it builds no cart, it can't check one, so it never carries
+`checkout_mismatch: true`.
+
+A real run against that kind of page reads the cart back after adding to it
+and checks it the same way `buy` checks any checkout (item, quantity, unit
+price, currency, extra lines). Any mismatch stops the run there, with outcome
+`checkout_mismatch` and `decisions.escalation.reason: "mismatch"`: the
+hand-off tool isn't called, so the tab never goes to checkout, and nothing is
+autofilled. The cart is already on the store, so `checkout_url` is the
+store's `/cart` page, for the shopper to look at. Items already sitting in
+the store's cart count as extra lines, so they stop the run too.
+
+The same run then applies the other gates a checkout gets before anything
+leaves the cart: a `--quote` run's cap (`quote_changed`), and, when a
+decision backend is enabled, the confidence check (see "Decisions"). A hold
+from the confidence check reports `low_confidence` with the `/cart` page as
+`checkout_url`; again the tab isn't sent to checkout and nothing is
+autofilled.
+
+A page whose WebMCP tools build a checkout (no preset) gets the same confidence
+check before its `express_stop` hand-off, after the quote cap and the mismatch
+stop. A hold reports `low_confidence` with the `/cart` page as `checkout_url`
+and no navigation to the checkout, so a `profile` hand-off target is never sent
+there. With no decision backend enabled, nothing changes.
 
 Once the flow hands off to the store's own checkout page, the shopper can
 opt into having it pre-filled: `--autofill`, or
@@ -842,7 +881,9 @@ gem install portage-ucp-decision   # only needed for the confidence gate
 ```
 
 The confidence gate is the one feature that needs the gem, because the
-model backends live there.
+model backends live there. Use `portage-ucp-decision` 0.1.2 or newer: it
+rejects a backend answer that isn't a probability between 0 and 1, where
+0.1.1 let an answer above 1 clear any threshold.
 
 Every `portage buy` report carries an `outcome`, so a script or agent loop
 can branch on data rather than on the message text. The text output leads
@@ -852,12 +893,12 @@ with the same value, as `[outcome]`.
 | --- | --- | --- |
 | `purchased` | Completed. | no |
 | `needs_confirmation` | Checkout ready; rerun with `--yes`. | no |
-| `dry_run` | Checkout created, `--dry-run` stopped it. | no |
+| `dry_run` | Checkout created, `--dry-run` stopped it. `checkout_mismatch: true` when a real run would stop on a mismatch. | no |
 | `requires_escalation` | The store wants the shopper to finish. | yes |
-| `checkout_mismatch` | Checkout differs from the request (`PORTAGE_ABORT_ON_CHECKOUT_MISMATCH`). | yes |
+| `checkout_mismatch` | Checkout differs from the request (item, quantity, unit price, currency, or a priced line nobody asked for); stopped before payment. | yes |
 | `no_payment_token` | No `--payment-token` and no default payment method. | yes |
 | `policy_blocked` | Your spend policy denied it; `decisions.policy.reason` says why. | yes |
-| `low_confidence` | The confidence gate held it. | yes |
+| `low_confidence` | The confidence gate held it (before a `--yes` completion, or before a WebMCP hand-off to checkout, preset or not). | yes |
 | `permission_denied` | The store doesn't let this agent complete checkout. | yes |
 | `handoff_only` | Tier C: Amazon or another hand-off-only host. `legal_notice` explains why; see "Hand-off targets and hand-off-only hosts". | yes (built, never fetched) |
 | `store_refused` | The store refused a cart/checkout call (e.g. sold out). | when the store gave one |
@@ -884,9 +925,15 @@ Every verdict has a `reason`: `null` when the gate let the purchase through,
 otherwise a string naming why it stopped it.
 
 - **escalation** — `Support::Escalation`. A `requires_escalation` checkout
-  always escalates (`reason: "requires_escalation"`). A checkout that doesn't
-  match the request escalates (`reason: "mismatch"`) only under
-  `PORTAGE_ABORT_ON_CHECKOUT_MISMATCH`; otherwise it's reported as `warnings`.
+  always escalates (`reason: "requires_escalation"`). So does a checkout that
+  doesn't match the request (`reason: "mismatch"`), on every run but
+  `--dry-run`, where the mismatch is reported in `warnings` and flagged with
+  `checkout_mismatch: true` instead. Nothing turns this off:
+  `PORTAGE_ABORT_ON_CHECKOUT_MISMATCH` is deprecated and ignored. A mismatch
+  is the requested line missing, a different quantity, a different unit
+  price or currency than the store's own catalog, or any extra line the
+  request didn't include. An extra line that costs nothing (a free gift, a
+  $0 sample) is allowed; one whose cost can't be read counts as priced.
 - **policy** — `PolicyGuard`, run on your policy file (see "Policy" above)
   before any `--yes` completion. `reason` is the guard's own
   (`per_transaction_cap_exceeded`, `rolling_spend_cap_exceeded`,
@@ -901,16 +948,39 @@ otherwise a string naming why it stopped it.
   when the store answers that it's purchased.
 - **confidence** — `ConfidenceGate`, off unless `--decision-backend` or
   `PORTAGE_DECISION_BACKEND` names a backend. Right before a `--yes`
-  completion it asks the backend whether the checkout matches the request
-  and is safe to complete unattended. It sends the query, merchant,
-  quantity, line items, totals and warnings, never the payment token. The
-  gate fails closed, so three things hold the purchase: a score below the
-  threshold (`reason: "below_threshold"`), a backend that can't answer
-  (`"backend_error"`), and naming a backend without `portage-ucp-decision`
-  installed (`"not_installed"`). For the last two, `error` says what went
-  wrong. `jev` needs `JEV_API_KEY`; `laya` needs `LAYA_BRIDGE_SCRIPT` (see
-  `portage-ucp-decision`'s README). `portage doctor` flags whichever of
-  these is missing for the selected backend.
+  completion, and before a WebMCP preset flow sends the browser to the
+  store's checkout (and autofills it), it asks the backend whether the
+  checkout matches the request, and the approved quote on a `--quote` run,
+  and is safe to complete unattended. It is additive only: it runs after
+  the mismatch check, the quote cap and the spend policy, on a checkout all
+  of them let through, so it can hold a purchase but never let through one
+  they would stop. The gate fails closed, so three things hold the
+  purchase: a score below the threshold (`reason: "below_threshold"`), a
+  backend that can't answer or answers with something that isn't a
+  probability (`"backend_error"`), and naming a backend without
+  `portage-ucp-decision` installed (`"not_installed"`). For the last two,
+  `error` says what went wrong. `jev` needs `JEV_API_KEY`; `laya` needs
+  `LAYA_BRIDGE_SCRIPT` (see `portage-ucp-decision`'s README). `portage
+  doctor` flags whichever of these is missing for the selected backend.
+
+  `jev` is TypeSafe's hosted API, so what it's sent is kept to a minimal,
+  allowlisted summary (`Portage::Cli::ConfidenceState`); nothing else on
+  the checkout is read:
+
+  - `request`: the search query, the store's host, the quantity, and the
+    picked item's id and title.
+  - `approved_quote` (`--quote` runs only): the quote's store, product id,
+    title, quantity, total and currency.
+  - `checkout`: status, currency; per line, item id, title, unit price,
+    quantity, line totals and whether it's the requested line; the totals
+    (subtotal, shipping, tax, fees, total — whatever the store lists);
+    applied discounts' titles and amounts; the selected shipping option's
+    title and price.
+  - `warnings`.
+
+  Never sent: the payment token, the shipping address, the buyer's name,
+  phone or email, checkout ids, links and URLs, discount codes, or anything
+  from your environment. Store-supplied strings are cut to 200 characters.
 - **policy** also denies a checkout with no `total` line as
   `total_unknown` whenever a spend cap is set, rather than skipping the cap.
 

data/lib/portage/cli/adapter_session.rb

@@ -0,0 +1,34 @@
+require "portage/ucp"
+require "portage/ucp/client"
+require_relative "homepage_fetch"
+require_relative "permissive_authenticator"
+
+module Portage
+  module Cli
+    # The own-store loopback fallback HandoffReconciler and PaymentMethods
+    # share, mirroring Buy's own (#adapter_flow): sniff the platform from
+    # the store's homepage and, when that platform's env vars are set,
+    # build its adapter and wrap it in a loopback client. A later process
+    # must not assume an earlier one's session or credentials still exist,
+    # only that the env vars are still set.
+    module AdapterSession
+      # @param route [Symbol] the Support::Connection route the homepage
+      #   fetch goes over (PaymentMethods passes :payment).
+      # @return [Portage::Ucp::Client::Session, nil] nil when the platform
+      #   isn't recognised, its env is incomplete, or anything fails.
+      def self.call(uri, route: :store)
+        body, headers = HomepageFetch.call(uri, route: route)
+        platform = body && Portage::Ucp::Resolver.detect_platform(body, headers)
+        return nil unless platform
+
+        env = Portage::Ucp::Resolver.env_for(platform)
+        return nil unless Portage::Ucp::Resolver.missing_env(platform, env).empty?
+
+        adapter = Portage::Ucp::Resolver.build_adapter(platform, env)
+        Portage::Ucp::Client.for_adapter(adapter, authenticator: PermissiveAuthenticator.new)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

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

@@ -88,7 +88,7 @@ module Portage
         # @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).
+        #   without Full Disk Access, a SQLite error, no plutil, no profile found).
         def plan(options)
           profiles = Profiles.locate(options.browser, root: options.root)
           return no_profile(options) if profiles.empty?

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

@@ -1,4 +1,5 @@
 require "strscan"
+require "cgi/escape"
 
 module Portage
   module Cli
@@ -8,7 +9,8 @@ module Portage
       # 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.
+      # this gem — this is ~50 lines instead of a new one. Entities go
+      # through CGI.unescapeHTML from `cgi/escape`, a default library.
       #
       # Dates, data and numbers come back as their raw text; bookmark
       # import only ever reads strings out of the tree.
@@ -16,7 +18,6 @@ module Portage
         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)
@@ -31,7 +32,7 @@ module Portage
           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])
+          elsif scanner.scan(%r{<(#{SCALARS})>(.*?)</\1>}m) then CGI.unescapeHTML(scanner[2])
           else raise ParseError, "unexpected plist content at #{scanner.pos}"
           end
         end
@@ -57,15 +58,7 @@ module Portage
           { "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
+        private_class_method :value, :dict, :array, :empty
       end
     end
   end

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

@@ -1,22 +1,21 @@
-require "json"
-require "open3"
+require "sqlite3"
 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.
+      # Reads a browser's SQLite history database: 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 read-only through the sqlite3 gem. The `-shm` index is not
+      # copied: SQLite rebuilds it from the `-wal` in the (writable) tmpdir.
+      # 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.
+      # Any SQLite error (a corrupt or non-SQLite file, a schema that
+      # doesn't match the query) is Unavailable, never a fallback.
       class Sqlite
         class Unavailable < StandardError; end
 
@@ -25,12 +24,6 @@ module Portage
         # 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).
@@ -54,14 +47,15 @@ module Portage
         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)"
+          db = SQLite3::Database.new(copy, readonly: true, results_as_hash: true)
+          db.execute(sql).map { |row| row.transform_values { |v| v.is_a?(String) ? scrub(v) : v } }
+        rescue SQLite3::Exception => e
+          raise Unavailable, "SQLite error: #{e.message}"
+        ensure
+          db&.close
         end
+
+        def scrub(text) = text.dup.force_encoding("UTF-8").scrub
       end
     end
   end

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

@@ -34,15 +34,6 @@ module Portage
           get(host, port, "/json/new?#{URI.encode_www_form_component(url)}", method: :put)
         end
 
-        # `/json/close/<id>` answers plain text ("Target is closing"), not
-        # JSON — checked by success status only, never parsed as JSON.
-        def self.close_tab(port:, id:, host: HOST)
-          uri = URI("http://#{host}:#{port}/json/close/#{id}")
-          fetch(uri, :get).is_a?(Net::HTTPSuccess)
-        rescue StandardError
-          false
-        end
-
         def self.get(host, port, path, method: :get)
           uri = URI("http://#{host}:#{port}#{path}")
           response = fetch(uri, method)