portage-cli 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a7b8a3138a4fdb27a32fdd32637d783ded5536e8933ad27a42ba688e550d51e
-  data.tar.gz: 7e55c31d7d3ca91b7647152bff300c191b4593ca7e4956baf11488384ba7dd75
+  metadata.gz: a4a3c3b0ce94430985a4660b316c7fafb711d8814bc9497bba70d866bf927dc1
+  data.tar.gz: ac8bbf8f8f08ca0eda4962adfa8d240dae05e54b571a40b8aed68a8b3dd3ea03
 SHA512:
-  metadata.gz: 6f081ed17df4df877b15a25d3f0892c1f9fc891ce5fa82a5782acbe5a9deec9636b0b4a9b4c98f0ceea631e9711af9bb321ed1d2e65b34733f114cff35c3a5b1
-  data.tar.gz: 120db3f4d0cbf97ce2a24e877ac3ce017ba9db39bb53bcf944249cf3e507c04a49193267253b41940d5688cd4aa55c3c420f2e1ccbc6e15541bde045585013ff
+  metadata.gz: 7484fb5d07dc6c4c9bcfbfb01f84909b6c0c551d3e117bb4854ca5e67049779657272ea3c5c904847d2381780b11ffd839efa0e689c9eb20d2db8bd903126737
+  data.tar.gz: 70e0a2624e6e20714c2898069e53440cb620044c513a2644f12576b3da96bd0b2be5cc6603a2774a4f229eb8e19d5724889b9353ef3fab628ec6c06587a03a00

data/CHANGELOG.md

@@ -4,6 +4,31 @@ 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.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,10 @@ 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]
 ```
 
 - `--query` — search term. Against the store's catalog when you name a store,
@@ -82,6 +95,73 @@ 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.
+
 ### 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

@@ -131,7 +131,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 +243,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)
@@ -299,7 +300,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/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Cli
-    VERSION = "0.2.0".freeze
+    VERSION = "0.3.0".freeze
   end
 end

data/lib/portage/cli.rb

@@ -3,8 +3,11 @@ require "json"
 
 require_relative "cli/version"
 require_relative "cli/shipping_profile"
+require_relative "cli/catalog_products"
 require_relative "cli/buy"
 require_relative "cli/find"
+require_relative "cli/compare"
+require_relative "cli/history"
 
 module Portage
   # `portage` — the single command-line entrypoint for acting as a shopper's
@@ -17,6 +20,10 @@ module Portage
                                 [--product-id 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]
     USAGE
 
     # @param argv [Array<String>]
@@ -26,6 +33,8 @@ module Portage
       case command
       when "buy" then run_buy(rest)
       when "find" then run_find(rest)
+      when "compare" then run_compare(rest)
+      when "history" then run_history(rest)
       else
         warn USAGE
         1
@@ -40,6 +49,8 @@ module Portage
 
       json = options.delete(:json)
       report = Find.new(**options).call
+      History.new.record_search(query: report[:query], offer_count: report[:offers].length,
+                                message: report[:message])
       puts json ? JSON.pretty_generate(report) : format_find(report)
       report[:offers].any? ? 0 : 1
     end
@@ -73,6 +84,50 @@ module Portage
     def self.to_minor_units(major) = (major * 100).round
     private_class_method :to_minor_units
 
+    # --- compare ---
+
+    def self.run_compare(argv)
+      options = parse_compare_options(argv)
+      return 1 unless options
+
+      json = options.delete(:json)
+      url = options.delete(:url)
+      report = Compare.new(origin_url: url, **options).call
+      # Recorded as a search, not a purchase — compare never checks out. The
+      # query string names the compare so `portage history list` doesn't
+      # read it as a plain text search for the origin product's own title.
+      History.new.record_search(query: "compare: #{url} (product #{options[:origin_product_id]})",
+                                offer_count: report[:offers].length, message: report[:message])
+      puts json ? JSON.pretty_generate(report) : format_compare(report)
+      report[:offers].any? ? 0 : 1
+    end
+    private_class_method :run_compare
+
+    def self.parse_compare_options(argv)
+      url = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
+      opts = { identity: [] }
+      compare_option_parser(opts).parse!(argv)
+      if !url || opts[:origin_product_id].to_s.strip.empty?
+        warn USAGE
+        return nil
+      end
+
+      opts[:url] = url
+      opts
+    end
+    private_class_method :parse_compare_options
+
+    def self.compare_option_parser(opts)
+      OptionParser.new do |parser|
+        parser.on("--product-id ID") { |v| opts[:origin_product_id] = v }
+        parser.on("--id VALUE") { |v| opts[:identity] << v }
+        parser.on("--results N", Integer) { |v| opts[:results] = v }
+        parser.on("--max-price N", Float) { |v| opts[:max_price] = to_minor_units(v) }
+        parser.on("--json") { opts[:json] = true }
+      end
+    end
+    private_class_method :compare_option_parser
+
     # --- buy ---
 
     def self.run_buy(argv)
@@ -122,11 +177,23 @@ module Portage
       options = parsed[:buy].merge(url: url)
       options[:product_id] ||= product_id
       report = Buy.new(**options).call
+      record_purchase(report, options[:query]) if report[:checkout]
       puts parsed[:json] ? JSON.pretty_generate(report) : format_report(report)
       report[:checkout] || report[:browse] ? 0 : 1
     end
     private_class_method :execute_buy
 
+    # Only checkout attempts land here — a browse-only report never reached a
+    # checkout, so it belongs to search history, not purchase history.
+    def self.record_purchase(report, query)
+      History.new.record_purchase(
+        url: report[:url], query: query, checkout: report[:checkout],
+        checkout_status: report[:checkout_status], message: report[:message],
+        products: report[:products].map { |p| product_line(p) }
+      )
+    end
+    private_class_method :record_purchase
+
     def self.parse_buy_options(argv)
       url = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
       buy = { url: url, qty: 1, yes: false, dry_run: false }
@@ -164,6 +231,73 @@ module Portage
     end
     private_class_method :add_search_options
 
+    # --- history ---
+
+    def self.run_history(argv)
+      sub = argv.first && !argv.first.start_with?("-") ? argv.shift : "list"
+      case sub
+      when "list" then run_history_list(argv)
+      when "clear" then run_history_clear(argv)
+      else
+        warn USAGE
+        1
+      end
+    end
+    private_class_method :run_history
+
+    def self.run_history_list(argv)
+      opts = { limit: History::MAX_ENTRIES }
+      history_option_parser(opts).parse!(argv)
+      json = opts.delete(:json)
+      kind = opts.delete(:kind)
+      history = History.new
+      result = { purchases: kind == "searches" ? [] : history.purchases(limit: opts[:limit]),
+                 searches: kind == "purchases" ? [] : history.searches(limit: opts[:limit]) }
+      puts json ? JSON.pretty_generate(result) : format_history(result)
+      0
+    end
+    private_class_method :run_history_list
+
+    def self.run_history_clear(argv)
+      opts = {}
+      history_option_parser(opts).parse!(argv)
+      History.new.clear(kind: opts[:kind])
+      puts "Cleared #{opts[:kind] || 'purchase and search'} history."
+      0
+    end
+    private_class_method :run_history_clear
+
+    def self.history_option_parser(opts)
+      OptionParser.new do |parser|
+        parser.on("--purchases") { opts[:kind] = "purchases" }
+        parser.on("--searches") { opts[:kind] = "searches" }
+        parser.on("--limit N", Integer) { |v| opts[:limit] = v }
+        parser.on("--json") { opts[:json] = true }
+      end
+    end
+    private_class_method :history_option_parser
+
+    def self.format_history(result)
+      lines = ["Purchases:"]
+      result[:purchases].each { |p| lines << "  #{history_purchase_line(p)}" }
+      lines << "(none)" if result[:purchases].empty?
+      lines << "Searches:"
+      result[:searches].each { |s| lines << "  #{history_search_line(s)}" }
+      lines << "(none)" if result[:searches].empty?
+      lines.join("\n")
+    end
+    private_class_method :format_history
+
+    def self.history_purchase_line(entry)
+      "#{Time.at(entry['at'])} — #{entry['url']} (#{entry['query']}) — #{entry['checkout_status'] || entry['message']}"
+    end
+    private_class_method :history_purchase_line
+
+    def self.history_search_line(entry)
+      "#{Time.at(entry['at'])} — \"#{entry['query']}\" — #{entry['offer_count']} offer(s)"
+    end
+    private_class_method :history_search_line
+
     # --- output ---
 
     def self.format_report(report)
@@ -193,6 +327,20 @@ module Portage
     end
     private_class_method :offer_line
 
+    def self.format_compare(report)
+      lines = [report[:message].to_s]
+      report[:offers].each_with_index { |offer, index| lines << "  #{index + 1}. #{compare_offer_line(offer)}" }
+      lines.join("\n")
+    end
+    private_class_method :format_compare
+
+    def self.compare_offer_line(offer)
+      parts = ["[#{offer[:match]}] #{offer[:store]} — #{offer[:title]} (#{offer[:product_id]})", format_price(offer)]
+      parts << "browse only" unless offer[:checkout]
+      parts.join(" — ")
+    end
+    private_class_method :compare_offer_line
+
     def self.format_price(offer)
       return "price n/a" unless offer[:amount]
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: portage-cli
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Tom Whitbread
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: portage-ucp-client
   requirement: !ruby/object:Gem::Requirement
@@ -114,7 +114,10 @@ files:
 - exe/portage
 - lib/portage/cli.rb
 - lib/portage/cli/buy.rb
+- lib/portage/cli/catalog_products.rb
+- lib/portage/cli/compare.rb
 - lib/portage/cli/find.rb
+- lib/portage/cli/history.rb
 - lib/portage/cli/probe_cache.rb
 - lib/portage/cli/search_backends.rb
 - lib/portage/cli/shipping_profile.rb
@@ -140,7 +143,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.18
+rubygems_version: 3.6.9
 specification_version: 4
 summary: portage — one CLI command to buy from any store, native UCP or not
 test_files: []