portage-cli 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a7b8a3138a4fdb27a32fdd32637d783ded5536e8933ad27a42ba688e550d51e
-  data.tar.gz: 7e55c31d7d3ca91b7647152bff300c191b4593ca7e4956baf11488384ba7dd75
+  metadata.gz: 2dda5ce1d230eb5063b5a0a5a576acfce59be4a12abd415f85a0ba6d5d01d6d6
+  data.tar.gz: 4c4732f171e0da0dd8480cd260e1a273e3938ad7b500d3166e86445d2ae7beca
 SHA512:
-  metadata.gz: 6f081ed17df4df877b15a25d3f0892c1f9fc891ce5fa82a5782acbe5a9deec9636b0b4a9b4c98f0ceea631e9711af9bb321ed1d2e65b34733f114cff35c3a5b1
-  data.tar.gz: 120db3f4d0cbf97ce2a24e877ac3ce017ba9db39bb53bcf944249cf3e507c04a49193267253b41940d5688cd4aa55c3c420f2e1ccbc6e15541bde045585013ff
+  metadata.gz: 15c3ec9d03069d07adf77b404741867755b24bce9dcbb15ca11005db4344195c1f9cfb741e6340609bcb43b40ea875d8f6c420017132ae98c93d9acca60b45a2
+  data.tar.gz: d9f8dcaee95eaafa9197b313cab7ee70410f1808ad2bf5d4bd722276cd9f7fa7e7074d3080d49723c56e0ba677fa036822bfaa30ebe42471aadce46cfb0fe49d

data/CHANGELOG.md

@@ -4,6 +4,55 @@ All notable changes to this project are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project is
 pre-1.0, so APIs may still shift between minor versions.
 
+## [Unreleased]
+
+## [0.4.0] - 2026-09-14
+
+- Added `portage payment list/enroll/set-default/remove/freeze/revoke` —
+  card-on-file storage so `buy`'s `--payment-token` dead-end can fall back to
+  a stored default (`@payment_token ||= PaymentMethods.default`) instead of
+  requiring a fresh token on every call (docs/plans/agentic-payments.md
+  Phase 1). Storage picks macOS Keychain / Linux Secret Service (`secret-tool`,
+  D-Bus session required) / a headless `PORTAGE_PAYMENT_TOKEN`-only tier, in
+  that order, with no homegrown fallback store. `enroll` is a browser handoff
+  to a gateway-hosted setup page (the new `app.portage-ucp.payment_enrollment`
+  capability in `portage-ucp`) — no raw card number ever reaches this
+  process.
+- Added `portage payment enroll --scope-merchant/--scope-max-amount/
+  --scope-currency` — binds a Phase 2 per-token policy scope at enrollment
+  time, written to `Portage::Ucp::Policy` keyed by the same `token_ref`
+  `PolicyGuard` derives from the token at charge time.
+- Added `portage policy show/set` — manages the Phase 2 policy file's
+  top-level caps/velocity/allowlist (`Portage::Ucp::Policy`), checked by
+  `PolicyGuard` on every `complete_checkout`.
+- Widened the `portage-ucp` dependency pin from `~> 0.4` to `~> 0.5` and the
+  `portage-ucp-client` pin from `~> 0.2` to `~> 0.3` — this release's
+  `Policy`/`PolicyGuard`/`TokenRef` and `Session#create_payment_enrollment`
+  calls only exist from those versions on.
+
+## [0.3.0] - 2026-08-28
+
+- Fixed: `find` and `buy` were treating `search_catalog`'s wire envelope
+  (`{"ucp" => ..., "products" => [...]}`) as the product list itself —
+  `Array(session.search_catalog(...))` wrapped the whole envelope Hash into a
+  single-element array instead of unwrapping `"products"`, so every offer
+  built from it was malformed against any real store. `Portage::Cli::CatalogProducts.from`
+  now unwraps the envelope (and the own-store adapter's raw
+  `CatalogSearchResult`) before either command touches the result.
+- `portage compare <url> --product-id ID` (`Portage::Cli::Compare`, §22's
+  "find this same item elsewhere" mode) — resolves a named product, then runs
+  `find`'s own candidate-discovery/probe/rank pipeline against its title.
+  Every offer carries a `match:` tier (`confirmed`/`likely`/`unconfirmed`)
+  based on shared barcode/sku/`--id` identity, the origin store is excluded
+  by host, and `--results` truncates after ranking. Catalog-price only — no
+  `create_checkout` against candidate stores. Recorded to `portage history`
+  as a search.
+- `portage history` — local purchase/search history (`Portage::Cli::History`),
+  logged automatically to `~/.portage/history.json` on every `find`/checkout-
+  reaching `buy`. `list` (`--purchases`/`--searches`, `--limit`, `--json`) and
+  `clear` (same scoping flags) subcommands. Separate from `ProbeCache`, which
+  remembers hosts, not actions.
+
 ## [0.2.0] - 2026-08-21
 
 - `PORTAGE_SHIP_*` env vars (`Portage::Cli::ShippingProfile`) — configure a

data/README.md

@@ -29,6 +29,15 @@ portage find --query "burton snowboard" --max-price 400
 
 `portage buy` with no URL runs that search and then buys the offer you pick.
 
+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
+match is:
+
+```bash
+portage compare https://your-shop.example --product-id prod_123 --results 5
+```
+
 Depends on [`portage-ucp`](https://github.com/tomtom87/Portage/tree/main/portage-ucp)
 (for platform detection via `Resolver`) and
 [`portage-ucp-client`](https://github.com/tomtom87/Portage/tree/main/portage-ucp-client)
@@ -60,6 +69,22 @@ portage buy <url> --query "..." [--qty N] [--payment-token TOKEN] [--product-id
                                 [--yes] [--dry-run] [--json]
 portage buy --query "..." [--store URL] [--max-price N] [--limit N] ...
 portage find --query "..." [--max-price N] [--limit N] [--json]
+portage compare <url> --product-id ID [--id VALUE ...] [--results N]
+                       [--max-price N] [--json]
+portage history [list] [--purchases|--searches] [--limit N] [--json]
+portage history clear [--purchases|--searches]
+portage payment list [--json]
+portage payment enroll <url> [--label NAME] [--json]
+                              [--scope-merchant HOST ...] [--scope-max-amount N] [--scope-currency CUR]
+portage payment set-default <id>
+portage payment remove <id>
+portage payment freeze <id>
+portage payment revoke <id>
+portage policy show [--json]
+portage policy set [--per-transaction-cap N --currency CUR]
+                    [--rolling-cap N --rolling-window-seconds N --currency CUR]
+                    [--velocity-count N --velocity-window-seconds N]
+                    [--allow HOST ...] [--clear-allowlist]
 ```
 
 - `--query` — search term. Against the store's catalog when you name a store,
@@ -67,7 +92,9 @@ portage find --query "..." [--max-price N] [--limit N] [--json]
 - `--qty` — quantity, default `1`.
 - `--payment-token` — a tokenized payment credential (never a raw card number —
   `PaymentTokenGuard` in the core gem rejects those before they reach the wire).
-  Omit for `--dry-run` or to just browse.
+  Omit for `--dry-run` or to just browse, or to fall back to whatever
+  `portage payment` has on file as the default (see "Payment" below) — the
+  flag always wins when both are present.
 - `--product-id` — buy exactly this product rather than whatever the catalog
   search ranks first. If the id isn't in the results, nothing is bought.
 - `--store` — name the merchant without giving a full URL; skips the search.
@@ -82,6 +109,150 @@ Exits `0` when a checkout completed (or a dry-run/browse/search resolved
 successfully), `1` otherwise — including the "no native manifest, no adapter
 credentials" dead-end case, so it's scriptable in CI.
 
+### Compare
+
+`portage compare <url> --product-id ID` finds other stores selling the same
+item you already have. It resolves the named product, then runs `find`'s own
+candidate-discovery/probe/rank pipeline against the product's title, scoring
+each surviving offer instead of treating them all as equally confident hits:
+
+- `--product-id` — required. The item to compare, at the store you name.
+- `--id VALUE` — repeatable. A SKU, barcode (UPC/EAN/GTIN), or MPN you already
+  know, matched case-insensitively against every candidate's own identity
+  values. There's no way to tell the matcher which *kind* of identifier you
+  passed — the wire format doesn't distinguish them — so it doesn't pretend
+  to; passing one just adds it to the matching corpus. When omitted, the
+  origin product's own first variant sku/barcodes are used instead.
+- `--results N` — how many ranked offers to return, default 5. Applies after
+  ranking, not before — a truncated result is always the *worst* N dropped,
+  never an arbitrary N. The underlying probe cap (candidate origins checked,
+  not results returned) stays `find`'s own limit and isn't exposed on this
+  subcommand.
+- `--max-price` — same semantics as `find`'s.
+
+Every offer carries a `match:` tier so a caller never mistakes a coincidence
+for a confirmed match:
+
+| Tier | Means |
+| --- | --- |
+| `confirmed` | Origin and candidate share a barcode value (UPC/EAN/GTIN) — the one identifier the spec treats as globally unique. |
+| `likely` | Origin and candidate share a SKU, or an explicit `--id` hit landed on the candidate — both are "some string matched", not "a global identifier matched", so they share one tier rather than a false precision gradient. |
+| `unconfirmed` | Same search query, nothing shared. Could be the same item; could just have a similar title. |
+
+The origin store itself is excluded from results, matched by host (not by
+raw origin string), so an `http://`/`https://`/trailing-slash variant of your
+own store's URL doesn't show up as a "competitor." A `www.` variant is
+treated as a different host, same as `find`'s own candidate dedupe — worth
+knowing if your store answers on both.
+
+**Known limitation: recall, not ranking, is the ceiling.** Compare searches
+the backends using the origin product's own title — a store-specific
+marketing string. If a backend never surfaces the competitor for that title,
+no amount of tiering helps; every offer that *does* come back may be
+`unconfirmed` because nothing more specific was searched. There's no
+barcode/SKU-keyed second search pass yet.
+
+**Catalog-price only.** No `create_checkout` step runs against any candidate
+store — ranking uses each store's listed price, never a landed price
+(shipping/tax included). Verifying the actual cheapest landed price would
+mean starting a checkout on a store the shopper hasn't chosen, which risks
+abandoned carts on someone else's site; left out of scope for now.
+
+### History
+
+Every `find` (and `buy`, once it reaches a search) and every `buy` that
+reaches checkout is logged locally to `~/.portage/history.json` — most recent
+200 entries each, purchases and searches kept separately. Browse-only `buy`
+reports (no checkout reached) aren't logged as purchases.
+
+```bash
+portage history                       # both lists, most recent last
+portage history list --purchases      # just purchases
+portage history list --searches --limit 20
+portage history clear                 # wipe both
+portage history clear --purchases     # wipe just one
+```
+
+This is a local convenience cache, not an audit log — `portage history clear`
+deletes it outright, and there's no server-side record.
+
+### Payment
+
+Card-on-file storage for `--payment-token`, so an autonomous agent can
+complete a checkout without a human handing over a fresh token every time
+(docs/plans/agentic-payments.md Phase 1). No raw card number ever touches
+this process — enrollment is a browser handoff to the gateway's own hosted
+setup page:
+
+```bash
+portage payment enroll https://your-shop.example --label "Ops card"
+# → prints a setup_url; visit it, enter the card there, this process polls
+#   until the gateway hands back a token, then stores it.
+
+portage payment list
+portage payment set-default <id>
+portage payment freeze <id>    # blocks spend, keeps the enrollment
+portage payment revoke <id>    # deletes the token and the enrollment
+portage payment remove <id>    # same as revoke — no processor-side
+                                # "invalidate this token" call to differ by
+```
+
+`--scope-merchant`/`--scope-max-amount`/`--scope-currency` bind a Phase 2
+policy scope to the token at enrollment time, rather than after the fact:
+
+```bash
+portage payment enroll https://your-shop.example --label "Ops card" \
+  --scope-merchant your-shop.example --scope-max-amount 5000 --scope-currency USD
+```
+
+Written to `Policy` keyed by the same `token_ref` `PolicyGuard` derives from
+the token at charge time — enrollment is the only place a scope gets
+attached to a specific token; `portage policy set` below only touches the
+global caps/velocity/allowlist, not per-token scopes.
+
+Storage picks the strongest tier your platform actually has, in order, with
+no homegrown fallback store of its own:
+
+1. **macOS Keychain**, via the `security` CLI.
+2. **Linux Secret Service** (GNOME Keyring/KWallet), via `secret-tool` — only
+   when a D-Bus session is actually live.
+3. **Headless** — no local storage at all. The token *is*
+   `PORTAGE_PAYMENT_TOKEN`; `list`/`enroll`/`freeze`/etc. don't apply, since
+   there's nothing local to manage.
+
+**Local policy guards agent mistakes, not a compromised agent.** Anyone
+running as the local user can read/edit `~/.portage/payment_methods.json` or
+the Keychain/Secret Service entry directly — this is a convenience store, not
+a security boundary. The real backstop against a rogue or compromised agent
+is an issuer-side limit (a virtual card via Stripe Issuing, Privacy.com,
+etc.), not anything in this gem.
+
+### Policy
+
+`portage policy show`/`set` manage the Phase 2 policy file
+(`Portage::Ucp::Policy`, checked by `PolicyGuard` on every `complete_checkout`)
+— top-level caps, velocity, and a merchant allowlist that apply regardless of
+which token is spending:
+
+```bash
+portage policy show
+portage policy show --json
+
+portage policy set --per-transaction-cap 10000 --currency USD
+portage policy set --rolling-cap 50000 --rolling-window-seconds 86400 --currency USD
+portage policy set --velocity-count 5 --velocity-window-seconds 3600
+portage policy set --allow shop.example.com --allow other-shop.example.com
+portage policy set --clear-allowlist
+```
+
+Each `--*` group is applied independently — `portage policy set --allow
+shop.example.com` touches only the allowlist, leaving caps/velocity as they
+were, so caps and the allowlist can be configured in separate invocations.
+An empty policy (nothing ever set) means every check passes; this is an
+opt-in guardrail, not a default-deny one. Per-token scopes (merchant/amount
+limits bound to one enrolled card) are set via `portage payment enroll
+--scope-*` above, not here.
+
 ### Shipping address (own-store checkouts only)
 
 When buying against your own store (`portage buy`'s step 2 adapter-credentials

data/lib/portage/cli/buy.rb

@@ -3,6 +3,7 @@ require "uri"
 require "json"
 require "portage/ucp"
 require "portage/ucp/client"
+require_relative "payment_methods"
 
 module Portage
   module Cli
@@ -131,7 +132,7 @@ module Portage
       end
 
       def catalog_only_adapter(adapter, platform)
-        products = Array(adapter.search_catalog(query: @query, limit: 10))
+        products = CatalogProducts.from(adapter.search_catalog(query: @query, limit: 10))
         checkout = redirect_checkout(adapter, products)
         build_report(
           source: "adapter:#{platform.name}", browse: true, checkout: !!checkout,
@@ -243,12 +244,13 @@ module Portage
         products.find { |product| product_id_of(product) == @product_id }
       end
 
-      # search_catalog's results are raw Portage::Ucp::Product structs over
-      # the loopback transport (Product has no #to_wire_h, see
-      # Dispatcher#wrap) but string-keyed wire hashes over stdio/HTTP (the
-      # `mcp` gem's client parses real JSON) — handle both.
+      # #select_product only ever sees products from #safe_search, which reads
+      # through a Session — native remote or the own-store loopback session
+      # built via Client.for_adapter alike — so Dispatcher#wrap has already
+      # called #to_wire_h on every result; a string-keyed wire hash either
+      # way, never a raw Portage::Ucp::Product struct.
       def product_id_of(product)
-        product.respond_to?(:id) ? product.id : product["id"]
+        product["id"]
       end
 
       def finish_checkout(session, source, products, checkout)
@@ -261,9 +263,11 @@ module Portage
       end
 
       def complete(session, source, products, checkout)
+        @payment_token ||= PaymentMethods.default
         unless @payment_token
           return checkout_report(source, products, checkout,
-                                 message: "No --payment-token given — can't complete the purchase.")
+                                 message: "No --payment-token given, and no default payment method on file — " \
+                                          "run `portage payment enroll` or pass --payment-token.")
         end
 
         completed = session.complete_checkout(checkout_id: checkout["id"], payment_token: @payment_token)
@@ -299,7 +303,7 @@ module Portage
       end
 
       def safe_search(session)
-        Array(session.search_catalog(query: @query, limit: 10))
+        CatalogProducts.from(session.search_catalog(query: @query, limit: 10))
       end
 
       # --- Homepage fetch (used by both the manifest-not-found path and the

data/lib/portage/cli/catalog_products.rb

@@ -0,0 +1,29 @@
+module Portage
+  module Cli
+    # Unwraps whatever shape a catalog search call actually returns.
+    #
+    # Every call that goes through a Portage::Ucp::Client::Session — native
+    # remote stores and the own-store loopback session built via
+    # Client.for_adapter alike — passes through Dispatcher#wrap, which calls
+    # `to_wire_h` on the result before handing it back. So a Session's
+    # `search_catalog` always comes back as the wire-shaped envelope
+    # `{"ucp" => ..., "products" => [...]}`, never a bare array and never a
+    # raw struct.
+    #
+    # The one exception is Buy's own-store catalog-only path
+    # (`Buy#catalog_only_adapter`), which calls `Adapter#search_catalog`
+    # directly — no Session, no Dispatcher — and gets back the real
+    # `Portage::Ucp::CatalogSearchResult` the adapter built.
+    module CatalogProducts
+      module_function
+
+      def from(result)
+        case result
+        when Portage::Ucp::CatalogSearchResult then result.products
+        when Hash then Array(result["products"])
+        else Array(result)
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/compare.rb

@@ -0,0 +1,160 @@
+require_relative "find"
+
+module Portage
+  module Cli
+    # `portage compare <url> --product-id ID` — §22's "find this same item
+    # elsewhere" mode. Resolves a product a shopper already has in hand, then
+    # runs Find's own candidate-discovery/probe/rank pipeline against the
+    # product's own title, scoring each surviving offer by how confident we
+    # actually are that it's the *same* item rather than just a similarly
+    # titled one.
+    #
+    # Catalog-price only: nothing here calls create_checkout against a
+    # candidate store, so a ranked offer's price is the listed price, never a
+    # landed price. See docs/plans/portage-compare.md for why that's a
+    # deliberate scope cut, not an oversight.
+    class Compare < Find
+      RESULT_LIMIT = 5
+      TIER_RANK = { confirmed: 0, likely: 1, unconfirmed: 2 }.freeze
+
+      # `identity:` is one repeatable value, not four aliases (--mpn/--sku/
+      # --upc/--gtin) for the same untyped string corpus — the wire format
+      # doesn't distinguish barcode types, so a flag name implying it could
+      # would be lying about the matcher's actual precision. `find_options:`
+      # bundles Find's own backends:/cache:/throttle: pass-through so this
+      # initializer stays under Metrics/ParameterLists without an exclusion.
+      def initialize(origin_url:, origin_product_id:, identity: [], results: RESULT_LIMIT, max_price: nil,
+                     find_options: {})
+        @origin_url = origin_url
+        @origin_product_id = origin_product_id
+        @explicit_identity = identity
+        @result_limit = results
+        # `query: nil` — the real query isn't known until #call resolves the
+        # origin product; Find reads @query at #call time, not construction
+        # time, so #call can overwrite it before invoking Find#call via super.
+        super(query: nil, max_price: max_price, **find_options)
+      end
+
+      def call
+        origin = resolve_origin
+        return origin if origin[:message]
+
+        @origin_host = origin[:host]
+        @identity = build_identity(origin[:product])
+        @query = origin[:title]
+        result = super
+        finish(result)
+      end
+
+      private
+
+      # --- Origin resolution ---
+
+      def resolve_origin
+        uri = parse_http(@origin_url)
+        return report(message: "Not a store URL: #{@origin_url.inspect}") unless uri
+
+        session = discover(origin_of(uri))
+        return report(message: "#{origin_of(uri)} doesn't speak UCP.") unless session
+
+        wrapped = session.get_product(product_id: @origin_product_id)
+        product = wrapped.is_a?(Hash) ? wrapped["product"] : nil
+        return report(message: "Product #{@origin_product_id.inspect} not found at #{origin_of(uri)}.") unless product
+
+        { host: uri.host, title: field(product, "title"), product: product }
+      end
+
+      # --- Identity ---
+
+      # Explicit `--id` values win when given; otherwise fall back to the
+      # origin product's own first variant sku/barcodes. First-variant-only,
+      # same scope Find's own single-product reads already assume.
+      def build_identity(product)
+        variant = first_variant(product)
+        { barcodes: normalize_all(barcode_values(variant)), sku: normalize(variant["sku"]),
+          explicit: normalize_all(@explicit_identity) }
+      end
+
+      def first_variant(product) = Array(field(product, "variants")).first || {}
+
+      def barcode_values(variant) = Array(variant["barcodes"]).filter_map { |b| b.is_a?(Hash) ? b["value"] : nil }
+
+      def normalize(value)
+        value = value.to_s.strip
+        value.empty? ? nil : value.downcase
+      end
+
+      def normalize_all(values) = values.map { |v| normalize(v) }.compact.uniq
+
+      # --- Candidate offers: stash identity + host for scoring/exclusion ---
+
+      # Find#offer only flattens id/title/price/url off the top-level
+      # product. Compare additionally needs each candidate's own variant
+      # sku/barcodes (to score against) and a normalized store host (to
+      # exclude the origin store by host rather than by string equality on
+      # `store:`, which misses scheme/www differences) — kept scoped to
+      # Compare rather than pushed into Find, since plain `find` has no use
+      # for either.
+      def offer(store, product)
+        base = super
+        return nil unless base
+
+        variant = first_variant(product)
+        identity_values = { barcodes: normalize_all(barcode_values(variant)), sku: normalize(variant["sku"]) }
+        base.merge(identity_values: identity_values, store_host: parse_http(store[:origin])&.host)
+      end
+
+      # --- Finish: exclude origin, score, rank, truncate, rewrite message ---
+
+      def finish(result)
+        offers = result[:offers].reject { |o| same_host?(o[:store_host], @origin_host) }
+        excluded_origin = result[:offers].length - offers.length
+        scored = offers.map { |o| o.merge(match: match_tier(o)) }
+        ranked = scored.sort_by { |o| [TIER_RANK[o[:match]], o[:checkout] ? 0 : 1, o[:amount] || 0] }
+        kept = ranked.first(@result_limit)
+        result.merge(offers: kept, message: compare_summary(kept, ranked.length - kept.length, excluded_origin))
+      end
+
+      def same_host?(candidate_host, origin_host)
+        candidate_host && origin_host && candidate_host.downcase == origin_host.downcase
+      end
+
+      # Three tiers, honest about what the wire format can actually prove:
+      # barcodes are the one value the spec treats as globally unique, so
+      # only a shared barcode earns :confirmed. A shared SKU is merchant-
+      # internal and collides across stores constantly, so it — and an
+      # explicit --id hit that isn't a barcode match — lands in :likely.
+      # Everything else rode in on the search query alone.
+      def match_tier(offer)
+        candidate = offer[:identity_values]
+        return :confirmed if shared_barcode?(candidate[:barcodes])
+        return :likely if shared_sku?(candidate[:sku]) || explicit_hit?(candidate)
+
+        :unconfirmed
+      end
+
+      def shared_barcode?(candidate_barcodes) = @identity[:barcodes].intersect?(Array(candidate_barcodes))
+
+      def shared_sku?(candidate_sku) = @identity[:sku] && candidate_sku && @identity[:sku] == candidate_sku
+
+      def explicit_hit?(candidate)
+        @identity[:explicit].intersect?((Array(candidate[:barcodes]) + [candidate[:sku]]).compact)
+      end
+
+      def compare_summary(kept, truncated, excluded_origin)
+        return empty_compare_summary(excluded_origin) if kept.empty?
+
+        parts = ["Found #{kept.length} offer(s) for \"#{@query}\""]
+        parts << "#{truncated} more not shown (--results #{@result_limit})" if truncated.positive?
+        parts << "#{excluded_origin} excluded (origin store)" if excluded_origin.positive?
+        "#{parts.join(', ')}."
+      end
+
+      def empty_compare_summary(excluded_origin)
+        message = "No comparable offers found for \"#{@query}\" outside #{@origin_host}"
+        message += ", #{excluded_origin} excluded (origin store)" if excluded_origin.positive?
+        "#{message}."
+      end
+    end
+  end
+end

data/lib/portage/cli/find.rb

@@ -135,7 +135,7 @@ module Portage
       # --- Step 3: ask the survivors what they stock ---
 
       def offers_for(store)
-        products = Array(store[:session].search_catalog(query: @query, limit: PER_STORE_RESULTS))
+        products = CatalogProducts.from(store[:session].search_catalog(query: @query, limit: PER_STORE_RESULTS))
         products.filter_map { |product| offer(store, product) }
       rescue StandardError
         []
@@ -161,10 +161,12 @@ module Portage
 
       # --- Shapes ---
 
-      # Products arrive as `Portage::Ucp::Product` structs over the loopback
-      # transport and as string-keyed wire hashes over stdio/HTTP (same split
-      # Buy#product_id_of documents), and the wire shape carries a
-      # `price_range` rather than a scalar price.
+      # Every product here comes from #offers_for, which reads through
+      # Session#search_catalog — Dispatcher#wrap has already called
+      # #to_wire_h on the result, so this is always a string-keyed wire hash,
+      # never a raw Portage::Ucp::Product struct (same posture as
+      # Buy#product_id_of), and it carries a `price_range` rather than a
+      # scalar price.
       def price_of(product)
         range = field(product, "price_range")
         return [money_amount(range["min"]), range["min"]["currency"]] if range.is_a?(Hash) && range["min"].is_a?(Hash)
@@ -184,11 +186,7 @@ module Portage
 
       def money_amount(price) = price["amount"]
 
-      def field(product, key)
-        return product[key] if product.is_a?(Hash)
-
-        product.respond_to?(key) ? product.public_send(key) : nil
-      end
+      def field(product, key) = product[key]
 
       def report(**fields)
         { query: @query, candidates: [], stores: [], offers: [], message: nil }.merge(fields)

data/lib/portage/cli/history.rb

@@ -0,0 +1,72 @@
+require "json"
+require "fileutils"
+
+module Portage
+  module Cli
+    # Local record of what `portage` has searched for and bought, entirely
+    # separate from ProbeCache (which remembers *hosts*, not *actions*). Two
+    # append-only, size-capped lists — purchases and searches — so `portage
+    # history list` can answer "what did I already look for" and "what did I
+    # already buy" without re-running anything, and `portage history clear`
+    # can wipe either or both.
+    class History
+      PATH = File.join(Dir.home, ".portage", "history.json").freeze
+      MAX_ENTRIES = 200
+
+      def initialize(path: PATH, now: Time.now)
+        @path = path
+        @now = now.to_i
+      end
+
+      def record_purchase(url:, query:, checkout:, message:, checkout_status: nil, products: [])
+        append("purchases", { "url" => url, "query" => query, "checkout" => checkout,
+                              "checkout_status" => checkout_status, "message" => message,
+                              "products" => products, "at" => @now })
+      end
+
+      def record_search(query:, offer_count:, message:)
+        append("searches", { "query" => query, "offer_count" => offer_count, "message" => message, "at" => @now })
+      end
+
+      def purchases(limit: MAX_ENTRIES) = store["purchases"].last(limit)
+
+      def searches(limit: MAX_ENTRIES) = store["searches"].last(limit)
+
+      # @param kind [String, nil] "purchases", "searches", or nil for both.
+      def clear(kind: nil)
+        kinds = kind ? [kind] : %w[purchases searches]
+        kinds.each { |k| store[k] = [] }
+        write
+      end
+
+      private
+
+      def append(kind, entry)
+        store[kind] = (store[kind] + [entry]).last(MAX_ENTRIES)
+        write
+        entry
+      end
+
+      def store
+        @store ||= read
+      end
+
+      def read
+        parsed = File.readable?(@path) ? JSON.parse(File.read(@path)) : {}
+        parsed = {} unless parsed.is_a?(Hash)
+        { "purchases" => Array(parsed["purchases"]), "searches" => Array(parsed["searches"]) }
+      rescue StandardError
+        { "purchases" => [], "searches" => [] }
+      end
+
+      # A history that can't be written just doesn't remember this run —
+      # never a failed buy or search.
+      def write
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, JSON.generate(@store))
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/portage/cli/payment_methods/env_backend.rb

@@ -0,0 +1,28 @@
+module Portage
+  module Cli
+    class PaymentMethods
+      # Headless tier (no D-Bus session — the common case for a server-
+      # deployed agent): no local storage at all, consistent with how
+      # Resolver.env_for already resolves platform credentials. The token
+      # *is* PORTAGE_PAYMENT_TOKEN — there's no id/enrollment/freeze/revoke
+      # bookkeeping to do, since there's nowhere local to keep it.
+      class EnvBackend
+        VAR = "PORTAGE_PAYMENT_TOKEN".freeze
+
+        def self.available? = true
+
+        def read(_id) = ENV.fetch(VAR, nil)
+
+        def write(_id, _token)
+          raise NotSupportedError, "headless mode has no local storage — set #{VAR} instead"
+        end
+
+        def delete(_id)
+          raise NotSupportedError, "headless mode has no local storage — unset #{VAR} instead"
+        end
+      end
+
+      class NotSupportedError < StandardError; end
+    end
+  end
+end