portage-cli 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d34c9ba25977baefa9f1f802e38ae6b2175e455d246f7a0dd3a2833136c46e8
-  data.tar.gz: 2c1d701bafd9c914115bdb02ab661906eaddba139e0627a56bfa0cf094e71d06
+  metadata.gz: c506344f3b17a2ea4199f84efaf70d658b0debec2fe03d167b847c58617e800b
+  data.tar.gz: 20c00c246e59fa9059611f7bb54380140295eada2c5deb457a11ec94309c1b04
 SHA512:
-  metadata.gz: ec3b6bf08d832abbe197591050b229f38a3650603feb6e94b47a6e84fbb9d3b9ddf531c51e84d71c8b708131b655e6b501e6a55662908eb6edb60981da4f14a2
-  data.tar.gz: 137b718fd1283383aa70879a6f2290a35dc1bc3f3a898ceff6965019b110329caf943dcf3ef39c04c29d1661beee3da6edd3a056877b7a6c3a932debce90c99f
+  metadata.gz: 9a3eff64f57ab81774a2a52034232a4667227aaff13aa7279d26dd41cf52faeafeea691711755fb41fd2f3a0a67f77d144d248d48c2631779a49c10bec9f2882
+  data.tar.gz: ade0a2ba64ba928ec1272a8902858bad1f79897f5059d428528b8978e4045047ee1a0e6e2579dc2f8a468fa73b0c3491cc66c48f2bc1a18951600e05bd2a25e1

data/CHANGELOG.md

@@ -6,6 +6,18 @@ pre-1.0, so APIs may still shift between minor versions.
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-29
+
+- **`portage check <url> [--json]`.** Reports whether Portage can buy from a store and
+  how: `verdict` (`automated`, `webmcp`, `handoff`, `unsupported`), `next_step`, and the
+  detail behind them (native UCP, platform, adapter install and missing env, hand-off-only,
+  WebMCP status). Wraps `Portage::Ucp::Check` and follows the precedence `buy` uses.
+  Plain GETs only, hand-off-only hosts are not contacted, and WebMCP is read only from an
+  already-open Portage profile tab. Exits `0` for `automated` and `webmcp`. The hand-off-only
+  test moved into a shared `HandoffHost` so `buy` and `check` can't disagree.
+  Follows a homepage `<link rel="ucp">` manifest pointer through `portage-ucp` 0.11.0,
+  which this release now requires (`~> 0.11`).
+
 ## [0.9.0] - 2026-09-29
 
 - **Human pick and approve** (`docs/plans/human-pick-and-approve.md`, Phases 1-3).

data/README.md

@@ -133,6 +133,7 @@ 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 check <url> [--json]
 portage pick [--search LAST|SEARCH_ID] [--via auto|tty|agent] [--json]
              [--choose REF | --compare REF | --view REF]
 portage approve QUOTE_ID [--via auto|tty|agent] [--relayed-yes | --view] [--json]
@@ -218,6 +219,18 @@ used (an unreadable value, an out-of-range threshold) stops the buy before
 anything runs: on stderr normally, or as a JSON report with `outcome:
 "invalid_option"` under `--json`.
 
+### Check
+
+`portage check <url> [--json]` answers "can Portage buy from this store, and how?".
+It checks for a native `/.well-known/ucp` manifest, detects the platform, notes
+whether its adapter gem is installed and which env vars are missing, and looks for
+WebMCP tools, using the same hand-off-only rules as `buy`. `verdict` is
+`automated`, `webmcp`, `handoff` or `unsupported`, with a plain-English
+`next_step`. Exits `0` for `automated` and `webmcp`. It sends plain GETs only, and
+never contacts a hand-off-only host. WebMCP is read only from a tab your Portage
+browser profile already has open on the store; it never launches a browser.
+Takes the `--proxy*` flags.
+
 ### Compare
 
 `portage compare <url> --product-id ID` finds other stores selling the same

data/lib/portage/cli/buy.rb

@@ -13,6 +13,7 @@ require_relative "checkout_handoff"
 require_relative "money"
 require_relative "notifier"
 require_relative "handoff_only"
+require_relative "handoff_host"
 require_relative "offer_sources"
 require_relative "handoff_target"
 require_relative "handoff_agents"
@@ -189,32 +190,10 @@ module Portage
       # "handoff_only_hosts" is the user's own list (see HandoffOnly).
       def handoff_only?
         @handoff_only ||= HandoffOnly.new
-        return true if @handoff_only.host?(@uri.host)
-        return true if OfferSources.retail_handoff_host?(@uri.host)
-
-        etsy_buyer_host?
-      end
-
-      # Phase 7 (docs/plans/buy-skill-and-local-browser.md):
-      # portage-ucp-etsy is a *seller*-side adapter — a shop owner with
-      # their own ETSY_* credentials set still reaches #adapter_flow
-      # unchanged below, the same "only your own store" rule every other
-      # adapter already gets (see the class comment at the top of this
-      # file). An ordinary buyer with no Etsy credentials of their own
-      # gets routed to hand-off here instead of a homepage fetch +
-      # platform detection that would just be scraping a stranger's
-      # listing — the buyer-side offer OfferSources::EtsyListings hands
-      # `find` has nothing this process can check out anyway.
-      def etsy_buyer_host?
-        HandoffOnly.matches_any?(@uri.host, %w[etsy.com]) && !etsy_adapter_configured?
+        HandoffHost.restricted?(@uri.host, handoff_only: @handoff_only)
       end
 
-      def etsy_adapter_configured?
-        platform = Portage::Ucp::Resolver::PLATFORMS.find { |p| p.name == "Etsy" }
-        return false unless platform
-
-        Portage::Ucp::Resolver.missing_env(platform, Portage::Ucp::Resolver.env_for(platform)).empty?
-      end
+      def etsy_buyer_host? = HandoffHost.etsy_buyer_host?(@uri.host)
 
       # No checkout was ever built — there's nothing to browse or complete,
       # just a link and why. `checkout_url` is built, never fetched: the

data/lib/portage/cli/check.rb

@@ -0,0 +1,154 @@
+require "uri"
+require "portage/ucp"
+require_relative "handoff_only"
+require_relative "handoff_host"
+require_relative "check_next_step"
+require_relative "webmcp"
+require_relative "browser_profile"
+
+module Portage
+  module Cli
+    # `portage check <url>` — "can Portage buy from this store, and how?"
+    #
+    # Wraps Portage::Ucp::Check (native `/.well-known/ucp`, platform
+    # detection, live adapter probe) and adds what only the CLI knows, so
+    # the answer matches what `portage buy` would actually do: the
+    # hand-off-only list (HandoffHost, shared with Buy), whether the adapter
+    # gem is installed, and whether the page exposes WebMCP tools.
+    #
+    # Precedence mirrors Buy#call: hand-off-only host, then native UCP, then
+    # WebMCP, then a platform adapter, then nothing. A hand-off-only host
+    # short-circuits before any request is made.
+    #
+    # Read-only and quiet: plain GETs only (through Ucp::Check), never a
+    # cart, never a checkout. WebMCP needs a live page, and Portage never
+    # launches a browser for this: it only reads tools from a tab the
+    # Portage browser profile already has open on the store's host
+    # (`portage browser profile open --url ...`). With no such tab, or with
+    # portage-ucp-webmcp not installed, `webmcp.status` is "skipped" and says
+    # why. A `webmcp_bridge:` can be injected instead (specs, library use).
+    class Check
+      CART_CAP = "dev.ucp.shopping.cart".freeze
+      CHECKOUT_CAP = "dev.ucp.shopping.checkout".freeze
+
+      # Verdicts `portage check` exits 0 for.
+      USABLE_VERDICTS = %w[automated webmcp].freeze
+
+      NO_TAB_REASON = "no Portage browser profile tab is open on this store " \
+                      "(portage browser profile open --url URL), and check never launches a browser".freeze
+
+      def self.call(url, **) = new(url, **).call
+
+      # @param webmcp_bridge [#list_tools, nil] a bridge over the store's page.
+      # @param handoff_only [HandoffOnly]
+      # @param checker [#call] url -> Portage::Ucp::Check report (injectable).
+      def initialize(url, webmcp_bridge: nil, handoff_only: HandoffOnly.new, checker: Portage::Ucp::Check.method(:call))
+        raw = url.to_s.strip
+        @uri = URI.parse(raw =~ %r{\Ahttps?://}i ? raw : "https://#{raw}")
+        @webmcp_bridge = webmcp_bridge
+        @handoff_only = handoff_only
+        @checker = checker
+      end
+
+      def call
+        return handoff_only_report if HandoffHost.restricted?(@uri.host, handoff_only: @handoff_only)
+
+        report = @checker.call(@uri.to_s).merge(handoff_only: false)
+        report = report.merge(adapter: adapter_for(report))
+        report = report.merge(webmcp: webmcp_for(report))
+        verdict = verdict_for(report)
+        report.merge(verdict: verdict, next_step: CheckNextStep.call(verdict, report))
+      end
+
+      private
+
+      def handoff_only_report
+        { url: @uri.to_s, native_ucp: nil, platform: nil, recommended_gem: nil, handoff_only: true, adapter: nil,
+          webmcp: webmcp_skipped("#{@uri.host} is hand-off only, so it isn't probed"),
+          verdict: "handoff",
+          next_step: "#{@uri.host} restricts automated purchasing agents. Portage opens the page and you buy." }
+      end
+
+      # --- adapter ---
+
+      def adapter_for(report)
+        platform = Portage::Ucp::Resolver::PLATFORMS.find { |p| p.name == report[:platform] }
+        return nil unless platform
+
+        { gem: platform.gem, installed: gem_installed?(platform),
+          missing_env: Portage::Ucp::Resolver.missing_env(platform, Portage::Ucp::Resolver.env_for(platform)) }
+      end
+
+      # Same test the live probe uses: the adapter's require_path either
+      # loads or it doesn't. Loading has no I/O.
+      def gem_installed?(platform)
+        require platform.require_path
+        true
+      rescue LoadError
+        false
+      end
+
+      # --- webmcp ---
+
+      def webmcp_for(report)
+        return webmcp_skipped("the store speaks UCP natively") if report[:native_ucp]
+        return webmcp_skipped("portage-ucp-webmcp isn't installed") unless Webmcp.available?
+
+        bridge = @webmcp_bridge || existing_tab_bridge
+        return webmcp_skipped(NO_TAB_REASON) unless bridge
+
+        detect_webmcp(bridge)
+      rescue StandardError => e
+        { status: "error", tools: [], reason: "#{e.class}: #{e.message}" }
+      end
+
+      def webmcp_skipped(reason) = { status: "skipped", tools: [], reason: reason }
+
+      def detect_webmcp(bridge)
+        tools = bridge.list_tools
+        names = tools.map { |tool| (tool["name"] || tool[:name]).to_s }
+        return { status: "none", tools: [], reason: "the page registers no WebMCP tools" } if names.empty?
+
+        preset = Portage::Ucp::WebMcp::Presets.detect(tools)
+        session = Portage::Ucp::WebMcp.connect(bridge: bridge, preset: preset)
+        return { status: "available", tools: names, reason: nil } if cart_and_checkout?(session)
+
+        { status: "none", tools: names,
+          reason: "the page's WebMCP tools aren't a cart and checkout set Portage recognises" }
+      end
+
+      def cart_and_checkout?(session) = session.advertises?(CART_CAP) && session.advertises?(CHECKOUT_CAP)
+
+      # Only ever a tab that is already open on the store's host: no new tab
+      # is created, no browser is started, nothing is navigated.
+      def existing_tab_bridge
+        profile = BrowserProfile::Profile.new
+        return nil unless profile.status[:running]
+
+        tab = BrowserProfile::Cdp.list(port: profile.port).find { |t| t["type"] == "page" && same_host?(t["url"]) }
+        ws_url = tab && tab["webSocketDebuggerUrl"]
+        return nil unless ws_url
+
+        BrowserProfile::Bridge.new(socket: BrowserProfile::CdpSocket.connect(ws_url),
+                                   allowlist: BrowserProfile::Allowlist.new(hosts: [@uri.host]))
+      end
+
+      def same_host?(url)
+        URI(url.to_s).host == @uri.host
+      rescue URI::InvalidURIError
+        false
+      end
+
+      # --- verdict ---
+
+      def verdict_for(report)
+        return "automated" if report[:native_ucp]
+        return "webmcp" if report.dig(:webmcp, :status) == "available"
+        return "automated" if report.dig(:live_probe, :status) == "ok"
+        return "handoff" if report[:platform]
+
+        "unsupported"
+      end
+    end
+  end
+end

data/lib/portage/cli/check_next_step.rb

@@ -0,0 +1,51 @@
+module Portage
+  module Cli
+    # The plain-English `next_step` of a Check report, one sentence per
+    # verdict — kept apart from Check so its detection logic stays readable.
+    module CheckNextStep
+      def self.call(verdict, report)
+        case verdict
+        when "automated" then automated(report)
+        when "webmcp" then "Portage will build the cart; you pay in your browser."
+        when "handoff" then adapter(report)
+        else unsupported(report)
+        end
+      end
+
+      def self.automated(report)
+        return "Nothing to do — this store speaks UCP natively." if report[:native_ucp]
+
+        "Nothing more to set up — the #{report[:platform]} adapter (#{report.dig(:adapter, :gem)}) is installed " \
+          "and answered a live probe."
+      end
+
+      def self.adapter(report)
+        adapter = report[:adapter]
+        return "#{report[:url]} restricts automated purchasing agents. Portage opens the page and you buy." unless
+          adapter
+
+        actions = []
+        actions << "install #{adapter[:gem]}" unless adapter[:installed]
+        actions << "set #{adapter[:missing_env].join(', ')}" if adapter[:missing_env].any?
+        return probe_failed(report) if actions.empty?
+
+        "To automate this #{report[:platform]} store (adapters act as the store's owner), " \
+          "#{actions.join(' and ')}. Until then Portage opens the store and you buy."
+      end
+
+      def self.probe_failed(report)
+        reason = report.dig(:live_probe, :reason)
+        "The #{report[:platform]} adapter is set up but its live probe failed#{" (#{reason})" if reason}. " \
+          "Run `portage doctor`; until then Portage opens the store and you buy."
+      end
+
+      def self.unsupported(report)
+        webmcp = report[:webmcp]
+        note = webmcp[:status] == "skipped" ? " (WebMCP not checked: #{webmcp[:reason]})" : ""
+        "No UCP manifest, known platform or WebMCP cart found#{note}. Portage can only open the store " \
+          "for you to browse."
+      end
+      private_class_method :automated, :adapter, :probe_failed, :unsupported
+    end
+  end
+end

data/lib/portage/cli/handoff_host.rb

@@ -0,0 +1,33 @@
+require_relative "handoff_only"
+require_relative "offer_sources"
+
+module Portage
+  module Cli
+    # The one answer to "is this host hand-off only?" that both `buy` and
+    # `check` give, so `portage check` never says something `portage buy`
+    # wouldn't do. Three sources, in the order Buy has always consulted them:
+    # the user's own list (HandoffOnly, Amazon by default), the built-in
+    # retail hand-off hosts (Walmart, eBay, Best Buy), and Etsy for an
+    # ordinary buyer — portage-ucp-etsy is a seller-side adapter, so a shop
+    # owner with their own ETSY_* credentials set is not hand-off only.
+    module HandoffHost
+      def self.restricted?(host, handoff_only: HandoffOnly.new)
+        return true if handoff_only.host?(host)
+        return true if OfferSources.retail_handoff_host?(host)
+
+        etsy_buyer_host?(host)
+      end
+
+      def self.etsy_buyer_host?(host)
+        HandoffOnly.matches_any?(host, %w[etsy.com]) && !etsy_adapter_configured?
+      end
+
+      def self.etsy_adapter_configured?
+        platform = Portage::Ucp::Resolver::PLATFORMS.find { |p| p.name == "Etsy" }
+        return false unless platform
+
+        Portage::Ucp::Resolver.missing_env(platform, Portage::Ucp::Resolver.env_for(platform)).empty?
+      end
+    end
+  end
+end

data/lib/portage/cli/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Cli
-    VERSION = "0.9.0".freeze
+    VERSION = "0.10.0".freeze
   end
 end

data/lib/portage/cli.rb

@@ -15,6 +15,7 @@ require_relative "cli/browser_profile"
 require_relative "cli/buy"
 require_relative "cli/find"
 require_relative "cli/compare"
+require_relative "cli/check"
 require_relative "cli/history"
 require_relative "cli/quotes"
 require_relative "cli/money"
@@ -56,6 +57,7 @@ module Portage
              portage find --query "..." [--max-price N] [--limit N] [--json]
              portage compare <url> --product-id ID [--id VALUE ...] [--results N]
                                     [--max-price N] [--json]
+             portage check <url> [--json]
              portage pick [--search LAST|SEARCH_ID] [--via auto|tty|agent] [--json]
                           [--choose REF | --compare REF | --view REF]
              portage approve QUOTE_ID [--via auto|tty|agent] [--relayed-yes | --view] [--json]
@@ -93,13 +95,13 @@ module Portage
              portage generate agent-profile [--out FILE] [--key-out FILE] [--rotate]
              portage --version
 
-           proxy flags (buy/find/compare/doctor/payment enroll):
+           proxy flags (buy/find/compare/check/doctor/payment enroll):
              [--proxy URL] [--proxy-mode forward|gateway] [--proxy-header "Name: value"]
              [--no-proxy HOSTS] [--proxy-route ROUTE=URL|direct] [--proxy-chain URL,URL,...]
              [--proxy-passthrough HEADER] [--proxy-ca FILE] [--no-env-proxy]
     USAGE
 
-    COMMANDS = { "buy" => :run_buy, "find" => :run_find, "compare" => :run_compare,
+    COMMANDS = { "buy" => :run_buy, "find" => :run_find, "compare" => :run_compare, "check" => :run_check,
                  "pick" => :run_pick, "approve" => :run_approve,
                  "history" => :run_history, "payment" => :run_payment, "policy" => :run_policy,
                  "orders" => :run_orders, "index" => :run_index, "browser" => :run_browser,
@@ -207,6 +209,53 @@ module Portage
     def self.to_minor_units(major) = (major * 100).round
     private_class_method :to_minor_units
 
+    # --- check ---
+
+    # `portage check <url>` — can Portage buy from this store, and how?
+    # Exit 0 for `automated`/`webmcp`, 1 for anything else (and for a bad
+    # or missing URL, with the usage on stderr).
+    def self.run_check(argv)
+      opts = parse_check_options(argv)
+      return 1 unless opts
+      return 1 unless apply_proxy_settings(opts[:proxy])
+
+      report = Check.new(opts[:url]).call
+      puts opts[:json] ? JSON.pretty_generate(report) : format_check(report)
+      Check::USABLE_VERDICTS.include?(report[:verdict]) ? 0 : 1
+    end
+    private_class_method :run_check
+
+    def self.parse_check_options(argv)
+      opts = { proxy: {} }
+      OptionParser.new do |parser|
+        parser.on("--json") { opts[:json] = true }
+        ProxySettings.add_options(parser, opts[:proxy])
+      end.parse!(argv)
+      opts[:url] = argv.shift.to_s.strip
+      return opts if !opts[:url].empty? && argv.empty? && valid_check_url?(opts[:url])
+
+      warn USAGE
+      nil
+    end
+    private_class_method :parse_check_options
+
+    def self.valid_check_url?(url)
+      uri = URI.parse(url =~ %r{\Ahttps?://}i ? url : "https://#{url}")
+      uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+    rescue URI::InvalidURIError
+      false
+    end
+    private_class_method :valid_check_url?
+
+    def self.format_check(report)
+      lines = ["#{report[:url]}: #{report[:verdict]}"]
+      lines << "  platform: #{report[:platform]}" if report[:platform]
+      lines << "  webmcp: #{report[:webmcp][:status]}#{" (#{report[:webmcp][:reason]})" if report[:webmcp][:reason]}"
+      lines << "  next: #{report[:next_step]}"
+      lines.join("\n")
+    end
+    private_class_method :format_check
+
     # --- compare ---
 
     def self.run_compare(argv)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: portage-cli
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Tom Whitbread
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '0.11'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '0.11'
 - !ruby/object:Gem::Dependency
   name: portage-ucp-client
   requirement: !ruby/object:Gem::Requirement
@@ -184,6 +184,8 @@ files:
 - lib/portage/cli/buy.rb
 - lib/portage/cli/buyer_context.rb
 - lib/portage/cli/catalog_products.rb
+- lib/portage/cli/check.rb
+- lib/portage/cli/check_next_step.rb
 - lib/portage/cli/checkout_handoff.rb
 - lib/portage/cli/classifier.rb
 - lib/portage/cli/compare.rb
@@ -197,6 +199,7 @@ files:
 - lib/portage/cli/generate/adapter.rb
 - lib/portage/cli/generate/agent_profile.rb
 - lib/portage/cli/handoff_agents.rb
+- lib/portage/cli/handoff_host.rb
 - lib/portage/cli/handoff_only.rb
 - lib/portage/cli/handoff_reconciler.rb
 - lib/portage/cli/handoff_reconciler/wire_adapters.rb