portage-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a4a32f5894d104c340e147d698772d21492c3172d6b8e102c4508e431d210a9e
+  data.tar.gz: dbf75ae4f0c5bd7996095d40c0a7e019d4cf9e0376b529356e227d5879363a4a
+SHA512:
+  metadata.gz: e41a7814ccdf875fae65a3ec9001c678e6cd0f951c504a0f675d3a34c3126349486df39919e514056b2529305d6560745ca4e028269c69b58e60d6610465f3fc
+  data.tar.gz: 75503266fb054b39739bcd2786083454e0afdefae6e64aaa2573ebc6b4633fd4c3956b16c61707cdbb3bc688a56e31734c4b04293678473b8ffc776a80ceb4d5

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+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.
+
+## [0.1.0] - Unreleased
+
+- Initial pre-release. `portage buy <url>` — native UCP discovery first,
+  adapter fallback only when this process already has that platform's own
+  credentials.
+- `portage find --query "..."` — find UCP stores that stock something without
+  knowing a URL, via an allowlist, DuckDuckGo, Brave, or a Google Programmable
+  Search engine, then probe each candidate for `/.well-known/ucp` and search
+  the survivors' catalogs. Probe results are cached in
+  `~/.portage/discovery-cache.json`.
+- `portage buy` with no URL runs that search and buys the offer you pick.
+  `--yes` alone won't buy from a search result: the merchant has to be named by
+  `--store` or an interactive pick.
+- `portage buy --product-id ID` buys exactly that product instead of whatever
+  the catalog search ranks first.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Whitbread
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,129 @@
+# portage-cli
+
+Ships the `portage` executable — one CLI command to buy from any store, native
+UCP or not.
+
+```bash
+portage buy https://your-shop.example --query "snowboard" --qty 1 --payment-token spt_1a2b3c...
+```
+
+`portage buy <url>`:
+
+1. Tries native UCP discovery first (`GET /.well-known/ucp`, then a `<link
+   rel="ucp">`-style tag on the homepage) — zero credentials, works on any
+   store that's opted in.
+2. Falls back to a `portage-ucp-<platform>` adapter **only** when this process
+   already has that platform's own credentials in env — i.e. it's your own
+   store, or one you're integrated with.
+3. Otherwise says so plainly and stops — never scrapes or session-hijacks as an
+   anonymous shopper. That fallback path is a ToS violation this gem
+   deliberately refuses to take.
+
+Don't have a URL? `portage find` asks a search backend which stores might sell
+the thing, keeps the ones that answer `/.well-known/ucp`, and lists what they
+actually stock:
+
+```bash
+portage find --query "burton snowboard" --max-price 400
+```
+
+`portage buy` with no URL runs that search and then buys the offer you pick.
+
+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)
+(for the actual buy calls). No single adapter gem is a hard dependency — install
+whichever `portage-ucp-<platform>` gem matches the store you're integrated with,
+if any.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "portage-cli"
+```
+
+```bash
+bundle install
+```
+
+Or standalone:
+
+```bash
+gem install portage-cli
+```
+
+## Usage
+
+```bash
+portage buy <url> --query "..." [--qty N] [--payment-token TOKEN] [--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]
+```
+
+- `--query` — search term. Against the store's catalog when you name a store,
+  against the search backends when you don't.
+- `--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.
+- `--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.
+- `--max-price` — in major units (`400` means 400), compared per offer in that
+  offer's own currency. No FX conversion.
+- `--limit` — how many candidate stores to probe, capped at 12.
+- `--yes` — skip the confirmation prompt before completing checkout.
+- `--dry-run` — resolve and price the order without completing checkout.
+- `--json` — machine-readable report instead of the human-readable summary.
+
+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.
+
+## Buying without a URL
+
+`portage find` and URL-less `portage buy` share one pipeline:
+
+1. **Ask the backends** which stores might sell it (see below).
+2. **Probe each candidate origin** for `/.well-known/ucp`, one request each,
+   throttled, with results cached in `~/.portage/discovery-cache.json` (misses
+   for a day, hits for six hours) so repeat searches don't re-probe the same
+   hosts. A tool that fans out an unsolicited request per host per invocation
+   is a crawler; this one isn't.
+3. **Search the survivors' catalogs** and merge the offers, buyable stores
+   first, then cheapest.
+
+**`--yes` is not enough to buy from a search result.** With a URL you chose the
+merchant; without one a search ranker chose it, so the merchant has to be named
+by a person — either `--store`, or an interactive pick from the listed offers.
+A piped or CI run with no `--store` prints the offers and stops.
+
+### Search backends
+
+Every backend talks to a documented API. None of them parse a results page:
+scraping a search engine is the same class of ToS violation `portage buy`
+already refuses to commit against a merchant.
+
+| Backend | Credentials | Notes |
+| --- | --- | --- |
+| Allowlist | `~/.portage/stores.yml` (YAML array of URLs) or `PORTAGE_STORES` (comma-separated) | Stores you already trust. Checked first, costs no network call. |
+| DuckDuckGo | none | The [Instant Answer API](https://api.duckduckgo.com/api). Answers *entity* queries, not web queries: `burton snowboards` resolves to burton.com, `snowboard` resolves to nothing. |
+| Brave | `BRAVE_SEARCH_API_KEY` | Real web results. Set this up if you want open-ended queries to work. |
+| Google | `GOOGLE_CSE_KEY` + `GOOGLE_CSE_CX` | Programmable Search JSON API. |
+
+Backends that have no credentials sit out; DuckDuckGo is the keyless default
+because it's the only no-key engine with a real API, and its narrowness is the
+price of not scraping.
+
+## Development
+
+```bash
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2026 Tom Whitbread.

data/exe/portage

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "portage/cli"
+
+exit(Portage::Cli.run(ARGV))

data/lib/portage/cli/buy.rb

@@ -0,0 +1,282 @@
+require "net/http"
+require "uri"
+require "json"
+require "portage/ucp"
+require "portage/ucp/client"
+
+module Portage
+  module Cli
+    # `portage buy <url>` — the single entrypoint for "get this thing bought",
+    # regardless of whether the target store speaks native UCP, only offers a
+    # catalog, or doesn't speak UCP at all but happens to run a platform we
+    # have an adapter (and this process's own credentials) for.
+    #
+    # Never tries to buy as an anonymous shopper via scraping/session-hijacking
+    # (ToS violation, explicitly ruled out), and never falls back to an
+    # adapter unless this process already has that platform's own env vars
+    # set — i.e. it's your own store, or one you're integrated with, never a
+    # stranger's. See docs/design-log.md for the reasoning behind it.
+    class Buy
+      CART_CAP = "dev.ucp.shopping.cart".freeze
+      CHECKOUT_CAP = "dev.ucp.shopping.checkout".freeze
+      REDIRECT_LIMIT = 5
+
+      # @param product_id [String, nil] buy exactly this product instead of
+      #   whatever the catalog search happens to rank first — how `portage
+      #   find` hands a picked offer over without the ranking being guessed
+      #   twice.
+      def initialize(url:, query:, qty: 1, payment_token: nil, yes: false, dry_run: false, product_id: nil)
+        raw = url.to_s.strip
+        raw = "https://#{raw}" unless raw =~ %r{\Ahttps?://}i
+        @uri = URI.parse(raw)
+        @query = query
+        @qty = qty
+        @payment_token = payment_token
+        @yes = yes
+        @dry_run = dry_run
+        @product_id = product_id
+      end
+
+      def call
+        session = discover(@uri)
+        return native_flow(session) if session
+
+        body, headers = fetch_homepage(@uri)
+
+        linked = manifest_link(body)
+        if linked
+          session = discover(linked)
+          return native_flow(session) if session
+        end
+
+        platform = Portage::Ucp::Resolver.detect_platform(body, headers)
+        adapter_flow(platform) || dead_end
+      end
+
+      private
+
+      # --- Step 1: native UCP manifest ---
+
+      def discover(url)
+        Portage::Ucp::Client.discover(url.to_s)
+      rescue Portage::Ucp::Client::DiscoveryError
+        nil
+      end
+
+      def native_flow(session)
+        if session.advertises?(CART_CAP) && session.advertises?(CHECKOUT_CAP)
+          full_buy(session, source: "native_ucp")
+        else
+          catalog_only(session)
+        end
+      end
+
+      def catalog_only(session)
+        products = safe_search(session)
+        report = build_report(
+          source: "native_ucp", browse: true, checkout: false, products: products,
+          message: "I can browse this store but can't check out via UCP yet."
+        )
+        merge_adapter_checkout_fallback(report)
+      end
+
+      # No manifest advertised checkout — see whether a platform adapter can
+      # still cover it (fetches the homepage fresh; the "fetch once" rule in
+      # the design only covers the "no manifest at all" branch below, since
+      # this is a genuinely separate path).
+      def merge_adapter_checkout_fallback(report)
+        body, headers = fetch_homepage(@uri)
+        platform = Portage::Ucp::Resolver.detect_platform(body, headers)
+        fallback = platform && adapter_flow(platform)
+        return report unless fallback && fallback[:checkout]
+
+        report.merge(source: fallback[:source], checkout: true, checkout_url: fallback[:checkout_url])
+      end
+
+      # --- Step 1 fallback: alternate manifest pointer in <head> ---
+
+      def manifest_link(body)
+        return nil unless body
+
+        match = body.match(/<link[^>]+rel=["']ucp["'][^>]+href=["']([^"']+)["']/i) ||
+                body.match(/<link[^>]+href=["']([^"']+)["'][^>]+rel=["']ucp["']/i)
+        match && URI.join(@uri, match[1])
+      end
+
+      # --- Step 2/3: platform detection + adapter fallback ---
+
+      def adapter_flow(platform)
+        return nil unless platform
+
+        env = Portage::Ucp::Resolver.env_for(platform)
+        return nil if Portage::Ucp::Resolver.missing_env(platform, env).any?
+
+        adapter = Portage::Ucp::Resolver.build_adapter(platform, env)
+        if adapter_supports_checkout?(adapter)
+          full_buy(client_for(adapter), source: "adapter:#{platform.name}")
+        else
+          catalog_only_adapter(adapter, platform)
+        end
+      rescue LoadError, StandardError
+        nil
+      end
+
+      def adapter_supports_checkout?(adapter)
+        Portage::Ucp::Capabilities::CART.advertised_for?(adapter) &&
+          Portage::Ucp::Capabilities::CHECKOUT.advertised_for?(adapter)
+      end
+
+      def client_for(adapter)
+        Portage::Ucp::Client.for_adapter(adapter, authenticator: PermissiveAuthenticator.new)
+      end
+
+      def catalog_only_adapter(adapter, platform)
+        products = Array(adapter.search_catalog(query: @query, limit: 10))
+        checkout = redirect_checkout(adapter, products)
+        build_report(
+          source: "adapter:#{platform.name}", browse: true, checkout: !!checkout,
+          products: products, checkout_url: checkout && checkout.links.first&.url,
+          message: "Found it on #{platform.name}, but checkout there isn't a live UCP transaction — " \
+                   "#{checkout ? 'follow the link to buy it yourself.' : 'no checkout path at all.'}"
+        )
+      end
+
+      def redirect_checkout(adapter, products)
+        return nil if products.empty? || !Portage::Ucp::Capabilities::CHECKOUT.advertised_for?(adapter)
+
+        adapter.create_checkout(line_items: [{ product_id: products.first.id, quantity: @qty }],
+                                idempotency_key: "portage-buy-#{products.first.id}")
+      rescue StandardError
+        nil
+      end
+
+      # --- The actual buy, shared by native and adapter-loopback sources ---
+
+      def full_buy(session, source:)
+        products = safe_search(session)
+        product = select_product(products)
+        unless product
+          return build_report(source: source, browse: true, checkout: true, products: products,
+                              message: no_match_message)
+        end
+
+        checkout = session.create_checkout(line_items: [{ product_id: product_id_of(product), quantity: @qty }])
+        finish_checkout(session, source, products, checkout)
+      end
+
+      def no_match_message
+        return "No product matched \"#{@query}\"." unless @product_id
+
+        "Product #{@product_id} isn't in this store's results for \"#{@query}\"."
+      end
+
+      # With a --product-id, that exact product or nothing: falling back to the
+      # top search hit when the requested id isn't in the results would buy
+      # something the caller never chose.
+      def select_product(products)
+        return products.first unless @product_id
+
+        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.
+      def product_id_of(product)
+        product.respond_to?(:id) ? product.id : product["id"]
+      end
+
+      def finish_checkout(session, source, products, checkout)
+        status = checkout["status"]
+        return escalation_report(source, products, checkout) if status == "requires_escalation"
+        return dry_run_report(source, products, checkout) if @dry_run
+        return confirmation_needed_report(source, products, checkout) unless confirmed?
+
+        complete(session, source, products, checkout)
+      end
+
+      def complete(session, source, products, checkout)
+        unless @payment_token
+          return checkout_report(source, products, checkout,
+                                 message: "No --payment-token given — can't complete the purchase.")
+        end
+
+        completed = session.complete_checkout(checkout_id: checkout["id"], payment_token: @payment_token)
+        checkout_report(source, products, completed, message: "Purchased.")
+      end
+
+      def confirmed?
+        @yes
+      end
+
+      def escalation_report(source, products, checkout)
+        checkout_report(source, products, checkout,
+                        checkout_url: checkout["links"]&.find { |l| l["url"] }&.fetch("url", nil),
+                        message: "Checkout requires buyer escalation — visit the link to complete it.")
+      end
+
+      def dry_run_report(source, products, checkout)
+        checkout_report(source, products, checkout, message: "Dry run — checkout created but not completed.")
+      end
+
+      def confirmation_needed_report(source, products, checkout)
+        checkout_report(source, products, checkout, message: "Checkout ready — pass --yes to confirm the purchase.")
+      end
+
+      # Flattens the parts of a Checkout wire hash a CLI caller actually
+      # wants to see (id/status/totals) onto the report, rather than nesting
+      # the raw hash under a key that'd collide with the boolean `checkout:`
+      # field the output struct already reserves (§ output shape).
+      def checkout_report(source, products, checkout, message:, checkout_url: nil)
+        build_report(source: source, browse: true, checkout: true, products: products, message: message,
+                     checkout_url: checkout_url, checkout_id: checkout["id"], checkout_status: checkout["status"],
+                     totals: checkout["totals"])
+      end
+
+      def safe_search(session)
+        Array(session.search_catalog(query: @query, limit: 10))
+      end
+
+      # --- Homepage fetch (used by both the manifest-not-found path and the
+      # catalog-only-native adapter-checkout-fallback path) ---
+
+      def fetch_homepage(uri, limit = REDIRECT_LIMIT)
+        return [nil, {}] if limit.zero?
+
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                                       open_timeout: 5, read_timeout: 5) do |http|
+          http.get(uri.request_uri, { "User-Agent" => "portage-buy" })
+        end
+
+        case response
+        when Net::HTTPRedirection
+          fetch_homepage(URI.join(uri, response["location"]), limit - 1)
+        when Net::HTTPSuccess
+          [response.body, response.to_hash]
+        else
+          [nil, {}]
+        end
+      rescue StandardError
+        [nil, {}]
+      end
+
+      def dead_end
+        build_report(source: "none", browse: false, checkout: false,
+                     message: "No automated path — visit #{@uri} yourself.")
+      end
+
+      def build_report(**fields)
+        { url: @uri.to_s, checkout_url: nil, products: [] }.merge(fields)
+      end
+
+      # Loopback buy against your own store needs *some* authenticator (§9
+      # rejects anonymous mutation by default) — since this process already
+      # has this platform's own credentials (that's the gate to even reach
+      # here), authenticating this local CLI session is reasonable.
+      class PermissiveAuthenticator < Portage::Ucp::Authenticator
+        def call(_server_context) = :local_cli
+      end
+    end
+  end
+end

data/lib/portage/cli/find.rb

@@ -0,0 +1,217 @@
+require "uri"
+require "portage/ucp"
+require "portage/ucp/client"
+
+require_relative "search_backends"
+require_relative "probe_cache"
+
+module Portage
+  module Cli
+    # `portage find --query "..."` — the "I don't have a URL" half of the CLI.
+    #
+    # Ask a search backend which stores might sell the thing, keep only the
+    # ones that answer `/.well-known/ucp`, ask each of those what it actually
+    # stocks, and return the merged offers. Buy then takes over from a store
+    # the caller picked.
+    #
+    # The split matters: Find never buys. Handing the merchant choice to a
+    # search ranker and the purchase decision to `--yes` in one breath is how
+    # you end up owning a counterfeit from a shop you've never heard of, so
+    # picking a store stays an explicit act (see Cli.run_buy's `--store` gate).
+    class Find
+      CART_CAP = "dev.ucp.shopping.cart".freeze
+      CHECKOUT_CAP = "dev.ucp.shopping.checkout".freeze
+      MAX_PROBES = 12
+      PER_STORE_RESULTS = 5
+      THROTTLE = 0.1
+
+      # @param max_price [Integer, nil] minor units, matching the protocol's
+      #   own money representation — the CLI converts from major units.
+      def initialize(query:, limit: MAX_PROBES, max_price: nil, backends: nil, cache: nil, throttle: THROTTLE)
+        @query = query.to_s
+        @limit = [limit, MAX_PROBES].min
+        @max_price = max_price
+        @backends = backends || SearchBackends.default
+        @cache = cache || ProbeCache.new
+        @throttle = throttle
+      end
+
+      def call
+        return report(message: "Nothing to search for — pass --query.") if @query.strip.empty?
+
+        candidates = candidate_origins
+        return report(candidates: candidates, message: no_candidates_message) if candidates.empty?
+
+        stores = probe(candidates)
+        offers = rank(stores.flat_map { |store| offers_for(store) })
+        report(candidates: candidates, stores: stores.map { |s| s.slice(:origin, :source, :checkout) },
+               offers: offers, message: summary(candidates, stores, offers))
+      end
+
+      private
+
+      # --- Step 1: ask the backends who might sell this ---
+
+      def candidate_origins
+        seen = {}
+        @backends.each do |backend|
+          urls_from(backend).each { |url| add_candidate(seen, backend, url) }
+        end
+        seen.values.first(@limit)
+      end
+
+      # Keyed by host rather than by full origin: backends routinely hand back
+      # both `http://` and `https://` for the same shop, and probing one host
+      # twice over two schemes is a wasted request every time. https wins when
+      # both show up; an http-only host is still probed as it was given. The
+      # backend credited stays the one that found the host first.
+      def add_candidate(seen, backend, url)
+        uri = parse_http(url)
+        return unless uri
+
+        existing = seen[uri.host]
+        return if existing && !upgradable?(existing, uri)
+
+        seen[uri.host] = { origin: origin_of(uri), source: existing ? existing[:source] : backend.name }
+      end
+
+      def upgradable?(existing, uri)
+        uri.scheme == "https" && existing[:origin].start_with?("http://")
+      end
+
+      # One backend being down, rate-limited, or misconfigured shouldn't take
+      # the whole search with it.
+      def urls_from(backend)
+        Array(backend.search(@query, limit: @limit))
+      rescue StandardError
+        []
+      end
+
+      def parse_http(url)
+        uri = URI.parse(url.to_s)
+        uri if uri.host && uri.scheme.to_s.start_with?("http")
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      # Collapse every deep link a backend returns onto the origin, since
+      # that's the only thing `/.well-known/ucp` hangs off.
+      def origin_of(uri)
+        port = uri.port == uri.default_port ? "" : ":#{uri.port}"
+        "#{uri.scheme}://#{uri.host}#{port}"
+      end
+
+      # --- Step 2: keep the ones that actually speak UCP ---
+
+      # A cached *miss* is the only verdict that saves work here — a cached hit
+      # still has to connect, because a live session is the thing we need next.
+      def probe(candidates)
+        probed = 0
+        candidates.filter_map do |candidate|
+          next if @cache.fetch(candidate[:origin]) == false
+
+          throttle(probed)
+          probed += 1
+          session = discover(candidate[:origin])
+          @cache.record(candidate[:origin], !session.nil?)
+          session && candidate.merge(session: session, checkout: checkout?(session))
+        end
+      end
+
+      def throttle(probed)
+        sleep(@throttle) if probed.positive? && @throttle.to_f.positive?
+      end
+
+      def discover(origin)
+        Portage::Ucp::Client.discover(origin)
+      rescue StandardError
+        nil
+      end
+
+      def checkout?(session)
+        session.advertises?(CART_CAP) && session.advertises?(CHECKOUT_CAP)
+      end
+
+      # --- 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.filter_map { |product| offer(store, product) }
+      rescue StandardError
+        []
+      end
+
+      def offer(store, product)
+        amount, currency = price_of(product)
+        return nil if @max_price && amount && amount > @max_price
+
+        { store: store[:origin], source: store[:source], checkout: store[:checkout],
+          product_id: field(product, "id"), title: field(product, "title"),
+          amount: amount, currency: currency, url: field(product, "url") }
+      end
+
+      # Buyable first, then cheapest, then unpriced. Sorting on price alone
+      # would float a browse-only store above one you can actually check out
+      # from, which is the wrong answer to "buy me this".
+      def rank(offers)
+        offers.sort_by do |offer|
+          [offer[:checkout] ? 0 : 1, offer[:amount] ? 0 : 1, offer[:amount] || 0]
+        end
+      end
+
+      # --- 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.
+      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)
+
+        scalar_price(field(product, "price"))
+      end
+
+      def scalar_price(price)
+        case price
+        when Hash then [money_amount(price), price["currency"]]
+        when Integer then [price, nil]
+        when nil then [nil, nil]
+        else [price.respond_to?(:amount_minor) ? price.amount_minor : nil,
+              price.respond_to?(:currency) ? price.currency : nil]
+        end
+      end
+
+      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 report(**fields)
+        { query: @query, candidates: [], stores: [], offers: [], message: nil }.merge(fields)
+      end
+
+      def no_candidates_message
+        names = @backends.map(&:name)
+        return no_backends_message if names.empty?
+
+        "No candidate stores came back from #{names.join(', ')} for \"#{@query}\"."
+      end
+
+      def no_backends_message
+        "No search backend available — set BRAVE_SEARCH_API_KEY, GOOGLE_CSE_KEY/GOOGLE_CSE_CX, " \
+          "or list stores in ~/.portage/stores.yml."
+      end
+
+      def summary(candidates, stores, offers)
+        return "Found #{offers.length} offer(s) across #{stores.length} UCP store(s)." if offers.any?
+        return "#{stores.length} store(s) speak UCP but none stock \"#{@query}\"." if stores.any?
+
+        "Checked #{candidates.length} store(s); none of them speak UCP."
+      end
+    end
+  end
+end

data/lib/portage/cli/probe_cache.rb

@@ -0,0 +1,64 @@
+require "json"
+require "fileutils"
+
+module Portage
+  module Cli
+    # Remembers which origins answered `/.well-known/ucp` and which didn't.
+    #
+    # Without this, every URL-less search re-probes the same dozen hosts, and a
+    # tool that fans out one unsolicited request per host per invocation is a
+    # crawler wearing a CLI's clothes. Negative results are cached too — and
+    # for longer — because "this shop doesn't speak UCP" is the answer that
+    # would otherwise be re-asked most often and changes least.
+    class ProbeCache
+      PATH = File.join(Dir.home, ".portage", "discovery-cache.json").freeze
+      HIT_TTL = 6 * 60 * 60
+      MISS_TTL = 24 * 60 * 60
+
+      def initialize(path: PATH, now: Time.now)
+        @path = path
+        @now = now.to_i
+      end
+
+      # @return [Boolean, nil] cached verdict, or nil when unknown/expired.
+      def fetch(origin)
+        entry = store[origin]
+        return nil unless entry.is_a?(Hash) && entry.key?("ucp")
+
+        ttl = entry["ucp"] ? HIT_TTL : MISS_TTL
+        return nil if @now - entry["at"].to_i > ttl
+
+        entry["ucp"]
+      end
+
+      def record(origin, ucp)
+        store[origin] = { "ucp" => ucp, "at" => @now }
+        write
+        ucp
+      end
+
+      private
+
+      def store
+        @store ||= read
+      end
+
+      def read
+        return {} unless File.readable?(@path)
+
+        parsed = JSON.parse(File.read(@path))
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue StandardError
+        {}
+      end
+
+      # A cache that can't be written is a slow cache, never a failed run.
+      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/search_backends.rb

@@ -0,0 +1,201 @@
+require "net/http"
+require "uri"
+require "json"
+require "yaml"
+
+module Portage
+  module Cli
+    # Where "which stores might sell this?" comes from when the caller never
+    # named a store.
+    #
+    # Every backend here talks to a documented machine interface and returns
+    # bare candidate URLs. None of them parse a results page: scraping a search
+    # engine's HTML is the same class of ToS violation Buy already refuses to
+    # commit against a merchant, and it would be odd to be scrupulous about the
+    # shop and cavalier about the index. That rules out the usual
+    # `html.duckduckgo.com/html/?q=` trick — see DuckDuckGo below for what we
+    # use instead and what it costs us.
+    module SearchBackends
+      OPEN_TIMEOUT = 5
+      READ_TIMEOUT = 5
+      USER_AGENT = "portage-find".freeze
+
+      # Reference works and marketplaces-of-links that a search backend will
+      # happily return for a product query but that are never themselves a UCP
+      # store — cheap to skip, and each one skipped is one fewer host we probe.
+      NON_STORE_HOSTS = %w[
+        wikipedia.org wikimedia.org duckduckgo.com google.com bing.com
+        reddit.com youtube.com facebook.com x.com twitter.com pinterest.com
+      ].freeze
+
+      # Ordered cheapest/most-trusted first: your own allowlist costs no
+      # network call and needs no key, DuckDuckGo needs no key, the keyed
+      # engines only participate when their credentials are actually present.
+      def self.default
+        [Allowlist.new, DuckDuckGo.new, Brave.new, GoogleCse.new].select(&:available?)
+      end
+
+      def self.get_json(uri, params: {}, headers: {})
+        uri = uri.dup
+        uri.query = URI.encode_www_form(params) unless params.empty?
+        response = request(uri, headers)
+        response.is_a?(Net::HTTPSuccess) ? JSON.parse(response.body) : nil
+      rescue StandardError
+        nil
+      end
+
+      def self.request(uri, headers)
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                            open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT) do |http|
+          http.get(uri.request_uri, { "User-Agent" => USER_AGENT }.merge(headers))
+        end
+      end
+      private_class_method :request
+
+      # @return [Boolean] true when the URL is worth spending a manifest probe on.
+      def self.store_candidate?(url)
+        host = URI.parse(url.to_s).host
+        !!host && NON_STORE_HOSTS.none? { |bad| host == bad || host.end_with?(".#{bad}") }
+      rescue URI::InvalidURIError
+        false
+      end
+
+      # Stores you've already decided you trust, listed in
+      # `~/.portage/stores.yml` (a bare YAML array of URLs) or `PORTAGE_STORES`
+      # (comma-separated — the PATH-style colon can't separate values that
+      # contain `https://`). Query-independent on purpose: the point of the file
+      # is "always consider these", and the store's own catalog search is what
+      # decides whether it stocks the thing.
+      class Allowlist
+        PATH = File.join(Dir.home, ".portage", "stores.yml").freeze
+
+        def initialize(path: PATH, env: ENV.fetch("PORTAGE_STORES", nil))
+          @path = path
+          @env = env
+        end
+
+        def name = "allowlist"
+
+        def available? = !entries.empty?
+
+        def search(_query, limit: 10) = entries.first(limit)
+
+        private
+
+        def entries
+          @entries ||= (env_entries + file_entries).map { |e| e.to_s.strip }.reject(&:empty?).uniq
+        end
+
+        def env_entries = @env.to_s.split(",")
+
+        def file_entries
+          return [] unless File.readable?(@path)
+
+          Array(YAML.safe_load_file(@path))
+        rescue StandardError
+          []
+        end
+      end
+
+      # DuckDuckGo's Instant Answer API — official, documented, no key
+      # (https://api.duckduckgo.com/api).
+      #
+      # Know what it is before you lean on it: it answers *entity* queries, not
+      # web queries. "burton snowboards" resolves to burton.com through
+      # `Results`; "snowboard" resolves to nothing at all. So it covers "buy me
+      # a <brand> thing" well and open-ended shopping not at all. It's the
+      # keyless default because it's the only no-key engine with a real API;
+      # pair it with Brave or a Google CSE for actual breadth.
+      class DuckDuckGo
+        ENDPOINT = "https://api.duckduckgo.com/".freeze
+
+        def name = "duckduckgo"
+
+        def available? = true
+
+        def search(query, limit: 10)
+          data = SearchBackends.get_json(
+            URI.parse(ENDPOINT),
+            params: { q: query, format: "json", no_html: "1", no_redirect: "1", t: "portage" }
+          )
+          return [] unless data
+
+          urls(data).select { |u| SearchBackends.store_candidate?(u) }.uniq.first(limit)
+        end
+
+        private
+
+        # `Results` is the official-site answer and the only genuinely
+        # commercial field. `RelatedTopics` is mostly duckduckgo.com category
+        # links (filtered out downstream) but occasionally carries a real
+        # vendor, so it's worth flattening. `AbstractURL` is deliberately
+        # ignored — it's the encyclopedia entry, never the shop.
+        def urls(data)
+          direct = Array(data["Results"]).map { |r| r["FirstURL"] }
+          related = Array(data["RelatedTopics"]).flat_map { |topic| topic_urls(topic) }
+          (direct + related).compact
+        end
+
+        def topic_urls(topic)
+          return [] unless topic.is_a?(Hash)
+          return Array(topic["Topics"]).flat_map { |t| topic_urls(t) } if topic["Topics"]
+
+          [topic["FirstURL"]].compact
+        end
+      end
+
+      # Brave Search API (https://api-dashboard.search.brave.com) — real web
+      # results, needs BRAVE_SEARCH_API_KEY. This is the backend to set up if
+      # you want URL-less buying to work for generic queries.
+      class Brave
+        ENDPOINT = "https://api.search.brave.com/res/v1/web/search".freeze
+
+        def initialize(api_key: ENV.fetch("BRAVE_SEARCH_API_KEY", nil))
+          @api_key = api_key
+        end
+
+        def name = "brave"
+
+        def available? = !@api_key.to_s.empty?
+
+        def search(query, limit: 10)
+          data = SearchBackends.get_json(
+            URI.parse(ENDPOINT),
+            params: { q: query, count: limit },
+            headers: { "Accept" => "application/json", "X-Subscription-Token" => @api_key }
+          )
+          return [] unless data
+
+          Array(data.dig("web", "results")).map { |r| r["url"] }.compact
+                                           .select { |u| SearchBackends.store_candidate?(u) }.first(limit)
+        end
+      end
+
+      # Google Programmable Search (Custom Search JSON API) — needs
+      # GOOGLE_CSE_KEY and GOOGLE_CSE_CX. The documented API, not the SERP.
+      class GoogleCse
+        ENDPOINT = "https://www.googleapis.com/customsearch/v1".freeze
+
+        def initialize(api_key: ENV.fetch("GOOGLE_CSE_KEY", nil), cx: ENV.fetch("GOOGLE_CSE_CX", nil))
+          @api_key = api_key
+          @cx = cx
+        end
+
+        def name = "google_cse"
+
+        def available? = !@api_key.to_s.empty? && !@cx.to_s.empty?
+
+        def search(query, limit: 10)
+          data = SearchBackends.get_json(
+            URI.parse(ENDPOINT),
+            params: { key: @api_key, cx: @cx, q: query, num: [limit, 10].min }
+          )
+          return [] unless data
+
+          Array(data["items"]).map { |i| i["link"] }.compact
+                              .select { |u| SearchBackends.store_candidate?(u) }.first(limit)
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/version.rb

@@ -0,0 +1,5 @@
+module Portage
+  module Cli
+    VERSION = "0.1.0".freeze
+  end
+end

data/lib/portage/cli.rb

@@ -0,0 +1,202 @@
+require "optparse"
+require "json"
+
+require_relative "cli/version"
+require_relative "cli/buy"
+require_relative "cli/find"
+
+module Portage
+  # `portage` — the single command-line entrypoint for acting as a shopper's
+  # agent against any store, native-UCP or not. See Cli::Buy for the buying
+  # algorithm and Cli::Find for the "I don't have a URL" search that feeds it;
+  # this module is just argument parsing + subcommand dispatch.
+  module Cli
+    USAGE = <<~USAGE.freeze
+      usage: portage buy <url> --query "..." [--qty N] [--payment-token TOKEN]
+                                [--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]
+    USAGE
+
+    # @param argv [Array<String>]
+    # @return [Integer] process exit code
+    def self.run(argv)
+      command, *rest = argv
+      case command
+      when "buy" then run_buy(rest)
+      when "find" then run_find(rest)
+      else
+        warn USAGE
+        1
+      end
+    end
+
+    # --- find ---
+
+    def self.run_find(argv)
+      options = parse_find_options(argv)
+      return 1 unless options
+
+      json = options.delete(:json)
+      report = Find.new(**options).call
+      puts json ? JSON.pretty_generate(report) : format_find(report)
+      report[:offers].any? ? 0 : 1
+    end
+    private_class_method :run_find
+
+    def self.parse_find_options(argv)
+      opts = {}
+      find_option_parser(opts).parse!(argv)
+      if opts[:query].to_s.strip.empty?
+        warn USAGE
+        return nil
+      end
+
+      opts
+    end
+    private_class_method :parse_find_options
+
+    def self.find_option_parser(opts)
+      OptionParser.new do |parser|
+        parser.on("--query QUERY") { |v| opts[:query] = v }
+        parser.on("--limit N", Integer) { |v| opts[:limit] = 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 :find_option_parser
+
+    # `--max-price 400` means 400 of whatever the offer is priced in, and the
+    # comparison happens per-offer in that offer's own currency — no FX
+    # conversion, and no attempt to handle zero-decimal currencies like JPY.
+    def self.to_minor_units(major) = (major * 100).round
+    private_class_method :to_minor_units
+
+    # --- buy ---
+
+    def self.run_buy(argv)
+      parsed = parse_buy_options(argv)
+      return 1 unless parsed
+
+      url = parsed[:buy][:url] || parsed[:store]
+      return execute_buy(parsed, url) if url
+
+      buy_from_search(parsed)
+    end
+    private_class_method :run_buy
+
+    # `portage buy` with no URL: search first, then buy from the store the
+    # caller picks. `--yes` alone deliberately isn't enough to get here —
+    # without a URL the merchant would have been chosen by a search ranker
+    # rather than by a person, so either `--store` (handled above) or an
+    # interactive pick has to name it. Piped/CI runs list the offers and stop.
+    def self.buy_from_search(parsed)
+      report = Find.new(**parsed[:find]).call
+      offer = pick_offer(report, parsed[:json])
+      return report[:offers].any? ? 0 : 1 unless offer
+
+      execute_buy(parsed, offer[:store], product_id: offer[:product_id])
+    end
+    private_class_method :buy_from_search
+
+    def self.pick_offer(report, json)
+      output = json ? JSON.pretty_generate(report) : format_find(report)
+      puts output
+      return nil unless $stdin.tty? && report[:offers].any?
+
+      prompt_for_offer(report[:offers])
+    end
+    private_class_method :pick_offer
+
+    def self.prompt_for_offer(offers)
+      print "\nPick 1-#{offers.length} to buy (Enter to quit): "
+      choice = $stdin.gets.to_s.strip
+      return nil unless choice.match?(/\A\d+\z/)
+
+      offers[choice.to_i - 1] if choice.to_i.between?(1, offers.length)
+    end
+    private_class_method :prompt_for_offer
+
+    def self.execute_buy(parsed, url, product_id: nil)
+      options = parsed[:buy].merge(url: url)
+      options[:product_id] ||= product_id
+      report = Buy.new(**options).call
+      puts parsed[:json] ? JSON.pretty_generate(report) : format_report(report)
+      report[:checkout] || report[:browse] ? 0 : 1
+    end
+    private_class_method :execute_buy
+
+    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 }
+      parsed = { buy: buy, find: {} }
+      buy_option_parser(buy, parsed).parse!(argv)
+      buy[:query] ||= ""
+      return parsed if url || !buy[:query].strip.empty?
+
+      warn USAGE
+      nil
+    end
+    private_class_method :parse_buy_options
+
+    def self.buy_option_parser(buy, parsed)
+      OptionParser.new do |parser|
+        parser.on("--qty N", Integer) { |v| buy[:qty] = v }
+        parser.on("--payment-token TOKEN") { |v| buy[:payment_token] = v }
+        parser.on("--product-id ID") { |v| buy[:product_id] = v }
+        parser.on("--yes") { buy[:yes] = true }
+        parser.on("--dry-run") { buy[:dry_run] = true }
+        parser.on("--json") { parsed[:json] = true }
+        add_search_options(parser, buy, parsed)
+      end
+    end
+    private_class_method :buy_option_parser
+
+    # `--query` feeds both halves: it's the store search when there's no URL
+    # and the catalog search once a store is settled, so it's registered once
+    # here rather than twice on the same parser.
+    def self.add_search_options(parser, buy, parsed)
+      parser.on("--query QUERY") { |v| parsed[:find][:query] = buy[:query] = v }
+      parser.on("--store URL") { |v| parsed[:store] = v }
+      parser.on("--limit N", Integer) { |v| parsed[:find][:limit] = v }
+      parser.on("--max-price N", Float) { |v| parsed[:find][:max_price] = to_minor_units(v) }
+    end
+    private_class_method :add_search_options
+
+    # --- output ---
+
+    def self.format_report(report)
+      lines = ["#{report[:message]} (source: #{report[:source]})"]
+      report[:products].each { |p| lines << "  - #{product_line(p)}" }
+      lines << "  checkout: #{report[:checkout_url]}" if report[:checkout_url]
+      lines.join("\n")
+    end
+    private_class_method :format_report
+
+    def self.product_line(product)
+      product.respond_to?(:title) ? "#{product.id}: #{product.title}" : "#{product['id']}: #{product['title']}"
+    end
+    private_class_method :product_line
+
+    def self.format_find(report)
+      lines = [report[:message].to_s]
+      report[:offers].each_with_index { |offer, index| lines << "  #{index + 1}. #{offer_line(offer)}" }
+      lines.join("\n")
+    end
+    private_class_method :format_find
+
+    def self.offer_line(offer)
+      parts = ["#{offer[:store]} — #{offer[:title]} (#{offer[:product_id]})", format_price(offer)]
+      parts << "browse only" unless offer[:checkout]
+      parts.join(" — ")
+    end
+    private_class_method :offer_line
+
+    def self.format_price(offer)
+      return "price n/a" unless offer[:amount]
+
+      "#{format('%.2f', offer[:amount] / 100.0)}#{" #{offer[:currency]}" if offer[:currency]}"
+    end
+    private_class_method :format_price
+  end
+end

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: portage-cli
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tom Whitbread
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-08-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: portage-ucp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: portage-ucp-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.88'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.88'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.24'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.24'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: 'Ships the `portage` executable. `portage buy <url>` tries native UCP
+  discovery first (zero credentials, works on any store that''s opted in), falls back
+  to a portage-ucp-* platform adapter only when this process already has that platform''s
+  own credentials in env (i.e. it''s your own store or one you''re integrated with),
+  and otherwise says so plainly — never scrapes or session-hijacks as an anonymous
+  shopper. `portage find` covers the no-URL case: ask an allowlist, DuckDuckGo, Brave,
+  or a Google Programmable Search engine which stores might sell something, keep the
+  ones answering /.well-known/ucp, and search their catalogs — documented APIs only,
+  no SERP scraping. Depends on portage-ucp (for platform detection via Resolver) and
+  portage-ucp-client (for the actual buy calls); no single adapter gem is a hard dependency.'
+email:
+executables:
+- portage
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/portage
+- lib/portage/cli.rb
+- lib/portage/cli/buy.rb
+- lib/portage/cli/find.rb
+- lib/portage/cli/probe_cache.rb
+- lib/portage/cli/search_backends.rb
+- lib/portage/cli/version.rb
+homepage: https://github.com/tomtom87/Portage/tree/main/portage-cli
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/tomtom87/Portage/tree/main/portage-cli
+  changelog_uri: https://github.com/tomtom87/Portage/blob/main/portage-cli/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: portage — one CLI command to buy from any store, native UCP or not
+test_files: []