portage-cli 0.8.0 → 0.10.0

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/checkout_handoff.rb

@@ -1,6 +1,7 @@
 require "uri"
 require_relative "config"
 require_relative "setting"
+require_relative "browser_opener"
 
 module Portage
   module Cli
@@ -14,13 +15,11 @@ module Portage
     # --auto-open / --no-auto-open) beats PORTAGE_AUTO_OPEN_CHECKOUT, which
     # beats ~/.portage/config.json's "auto_open_checkout" (Config).
     #
-    # No new gem for the actual open — every other shell-out in this repo
-    # (PaymentMethods::KeychainBackend, SecretServiceBackend) hand-rolls
-    # `system` rather than pulling in launchy for something the OS already
-    # provides. `system(cmd, url)` (array form, never an interpolated
-    # string) so a merchant-controlled checkout_url can't inject into a
-    # shell.
+    # The open itself is BrowserOpener's array-form `system` shell-out, so
+    # a merchant-controlled checkout_url can't inject into a shell.
     class CheckoutHandoff
+      include BrowserOpener
+
       ENV_VAR = "PORTAGE_AUTO_OPEN_CHECKOUT".freeze
       CONFIG_KEY = "auto_open_checkout".freeze
 
@@ -47,24 +46,6 @@ module Portage
       rescue URI::InvalidURIError
         false
       end
-
-      def open_browser(url)
-        command = platform_command
-        return false unless command
-
-        !!system(command, url)
-      rescue StandardError => e
-        warn "portage: couldn't open #{url} (#{e.message})"
-        false
-      end
-
-      def platform_command
-        case RbConfig::CONFIG["host_os"]
-        when /darwin/i then "open"
-        when /linux|bsd/i then "xdg-open"
-        when /mswin|mingw|cygwin/i then "start"
-        end
-      end
     end
   end
 end

data/lib/portage/cli/find.rb

@@ -1,4 +1,5 @@
 require "uri"
+require "securerandom"
 require "portage/ucp"
 require "portage/ucp/client"
 
@@ -62,7 +63,7 @@ module Portage
         sourced = source_offers
         return report(candidates: candidates, message: no_candidates_message) if nothing_to_go_on?(candidates, sourced)
 
-        offers = rank(sourced + probed.flat_map { |store| offers_for(store) })
+        offers = rank(sourced + probed.flat_map { |store| offers_for(store) }).map { |o| with_offer_ref(o) }
         report(candidates: candidates, stores: store_summaries(stores), offers: offers,
                message: summary(candidates, stores, offers))
       rescue Portage::Ucp::Client::MissingAgentProfileError
@@ -78,6 +79,12 @@ module Portage
       # the complexity budget.
       def nothing_to_go_on?(candidates, sourced) = candidates.empty? && sourced.empty?
 
+      # A short opaque id `portage buy --offer` resolves from history, so a
+      # later step can point at one offer without re-sending its store,
+      # product id and query. Added last, after ranking, so it never
+      # influences the order.
+      def with_offer_ref(offer) = { offer_ref: "of_#{SecureRandom.hex(3)}" }.merge(offer)
+
       # --- Step 1: ask the backends who might sell this ---
 
       def candidate_origins

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/history.rb

@@ -1,5 +1,6 @@
 require "json"
 require "fileutils"
+require "securerandom"
 
 module Portage
   module Cli
@@ -40,11 +41,43 @@ module Portage
 
       # @param url [String, nil] the store, for a `portage buy` that never
       #   reached a checkout there; nil for a cross-store `portage find`.
-      def record_search(query:, offer_count:, message:, url: nil)
-        append("searches", { "query" => query, "url" => url, "offer_count" => offer_count, "message" => message,
+      # @param offers [Array<Hash>] a `find`'s (or `compare`'s) offers, kept
+      #   so `portage buy --offer REF` can resolve an `offer_ref` later (see
+      #   #offer). A search that keeps offers also gets a `search_id`, which
+      #   `portage pick --search` names it by (docs/plans/
+      #   human-pick-and-approve.md Phase 2).
+      # @return [Hash] the saved entry.
+      def record_search(query:, offer_count:, message:, url: nil, offers: [])
+        kept = offers.empty? ? nil : saved_offers(offers)
+        append("searches", { "search_id" => kept && "se_#{SecureRandom.hex(4)}", "query" => query, "url" => url,
+                             "offer_count" => offer_count, "message" => message, "offers" => kept,
                              "at" => @now }.compact)
       end
 
+      # @param id [String, nil] a `search_id`, or nil/"LAST" for the most
+      #   recent search that kept offers.
+      # @return [Hash, nil]
+      def search(id = nil)
+        with_offers = store["searches"].select { |search| Array(search["offers"]).any? }
+        return with_offers.last if id.nil? || id.casecmp?("last")
+
+        with_offers.reverse.find { |search| search["search_id"] == id }
+      end
+
+      # @return [Hash, nil] the saved offer for `ref` (store, product_id,
+      #   title, amount, currency, url, checkout, found_at) plus the catalog
+      #   `query` to buy it with — the offer's own when it was saved with
+      #   one (a compare result, searched by the compared product's title),
+      #   else that of the search that found it — from the most recent
+      #   search that holds it.
+      def offer(ref)
+        store["searches"].reverse_each do |search|
+          found = Array(search["offers"]).find { |saved| saved["offer_ref"] == ref }
+          return { "query" => search["query"] }.merge(found) if found
+        end
+        nil
+      end
+
       def purchases(limit: MAX_ENTRIES) = store["purchases"].last(limit)
 
       def searches(limit: MAX_ENTRIES) = store["searches"].last(limit)
@@ -58,6 +91,18 @@ module Portage
 
       private
 
+      # Takes a report's symbol-keyed offers or already-saved string-keyed
+      # ones (`pick` re-saves the offer it compared alongside the results).
+      def saved_offers(offers)
+        offers.map do |offer|
+          offer = offer.transform_keys(&:to_s)
+          saved = { "offer_ref" => offer["offer_ref"], "store" => offer["store"], "product_id" => offer["product_id"],
+                    "title" => offer["title"], "amount" => offer["amount"], "currency" => offer["currency"],
+                    "url" => offer["url"], "checkout" => offer["checkout"], "found_at" => offer["found_at"] || @now }
+          offer["query"] ? saved.merge("query" => offer["query"]) : saved
+        end
+      end
+
       def append(kind, entry)
         store[kind] = (store[kind] + [entry]).last(MAX_ENTRIES)
         write

data/lib/portage/cli/human_prompt.rb

@@ -0,0 +1,118 @@
+module Portage
+  module Cli
+    # The one way portage-cli asks a person something during a buy —
+    # `portage pick` (loop step 3), `portage approve` (step 5), the numbered
+    # pick `portage buy --query` shows, and the confirmation that lowers
+    # `--require-approval` (docs/plans/human-pick-and-approve.md Phase 2,
+    # Design § 3).
+    #
+    # Two surfaces:
+    #
+    # - `tty` reads and writes `/dev/tty`, not stdin/stdout, so it still
+    #   reaches the person when stdout is piped to an agent. An answer typed
+    #   there is recorded `by: "person"`. With no controlling terminal
+    #   (opening `/dev/tty` fails, e.g. ENXIO) it raises NoTerminal, which
+    #   each command reports as a clean `no_terminal` outcome.
+    # - `agent` prompts nobody: the command returns a `needs_*` outcome with
+    #   render-ready choices, and the agent relays the person's answer
+    #   (`--choose`, `--relayed-yes`), recorded `by: "agent_relayed"`.
+    #
+    # `via: "auto"` (the default) is `tty` when there's a controlling
+    # terminal and the run isn't `--json`, else `agent`.
+    #
+    # `terminal:` is injectable (anything with #gets/#print/#puts), so specs
+    # never open the real `/dev/tty`; the default is HumanPrompt.open_terminal.
+    class HumanPrompt
+      PATH = "/dev/tty".freeze
+      VIAS = %w[auto tty agent].freeze
+      BY_PERSON = "person".freeze
+      BY_AGENT = "agent_relayed".freeze
+
+      class NoTerminal < StandardError; end
+
+      def self.open_terminal = File.open(PATH, "r+")
+
+      # @param via [String] one of VIAS.
+      # @param json [Boolean] whether the run is `--json` (only read by `auto`).
+      # @param terminal [#gets, #print, #puts, nil] an already-open terminal.
+      def initialize(via: "auto", json: false, terminal: nil)
+        raise ArgumentError, "Unknown --via #{via.inspect} (auto, tty or agent)" unless VIAS.include?(via)
+
+        @via = via
+        @json = json
+        @terminal = terminal
+      end
+
+      # @return [String] "tty" or "agent".
+      def surface
+        @surface ||= case @via
+                     when "tty", "agent" then @via
+                     else !@json && terminal ? "tty" : "agent"
+                     end
+      end
+
+      def tty? = surface == "tty"
+
+      # A numbered pick. `v N` calls `view` with that choice and asks again
+      # — viewing is never an answer. Blank (or end of input) cancels; any
+      # other answer that isn't a listed number asks again.
+      # @param choices [Array<Hash>] each with `:label`.
+      # @param view [#call, nil] choice -> message to show.
+      # @return [Integer, nil] the chosen index, nil when cancelled.
+      def choose(question, choices, view: nil)
+        choices.each_with_index { |choice, i| say("  #{i + 1}. #{choice[:label]}") }
+        hint = view ? ", v N to view" : ""
+        loop do
+          answer = ask("#{question} (1-#{choices.length}#{hint}, Enter to cancel): ")
+          return nil if answer.empty?
+
+          index = chosen_index(answer, choices.length)
+          next say("Not one of the choices.") unless index
+          return index unless answer.match?(/\Av/i)
+
+          say(view ? view.call(choices[index]) : "Nothing to view.")
+        end
+      end
+
+      # A yes/no. `v` calls `view` and asks again; only "y"/"yes" is a yes.
+      # @return [Boolean]
+      def confirm(question, view: nil)
+        loop do
+          answer = ask("#{question} [y/N#{', v to view' if view}] ").downcase
+          return %w[y yes].include?(answer) unless answer == "v" && view
+
+          say(view.call)
+        end
+      end
+
+      def say(text) = terminal!.puts(text)
+
+      private
+
+      def ask(question)
+        terminal!.print(question)
+        terminal!.flush if terminal!.respond_to?(:flush)
+        terminal!.gets.to_s.strip
+      end
+
+      # "3" or "v 3" (1-based), within range.
+      def chosen_index(answer, count)
+        number = answer[/\A(?:v\s*)?(\d+)\z/i, 1]
+        return nil unless number
+
+        number.to_i.between?(1, count) ? number.to_i - 1 : nil
+      end
+
+      def terminal!
+        terminal || raise(NoTerminal, "No terminal to ask on (#{PATH} can't be opened) — run with --via agent " \
+                                      "and relay the person's answer, or run this from a terminal.")
+      end
+
+      def terminal
+        @terminal ||= self.class.open_terminal
+      rescue SystemCallError, IOError
+        nil
+      end
+    end
+  end
+end

data/lib/portage/cli/money.rb

@@ -0,0 +1,18 @@
+module Portage
+  module Cli
+    # How portage-cli prints an amount in minor units, in one place, so
+    # `find`/`history`/`buy` output, Buy's `quote_changed` message and the
+    # `approve` summary (docs/plans/human-pick-and-approve.md Phase 2) never
+    # disagree on what a total looks like. No FX and no zero-decimal
+    # currencies, same as Cli.to_minor_units.
+    module Money
+      module_function
+
+      # @param amount [Integer] minor units.
+      # @param currency [String, nil]
+      def format_amount(amount, currency)
+        "#{format('%.2f', amount / 100.0)}#{" #{currency}" if currency}"
+      end
+    end
+  end
+end

data/lib/portage/cli/offer_choice.rb

@@ -0,0 +1,38 @@
+require_relative "product_page"
+require_relative "money"
+
+module Portage
+  module Cli
+    # One offer as a render-ready choice (docs/plans/human-pick-and-approve.md
+    # Phase 2): what `portage pick` returns in `needs_pick`'s `choices[]`,
+    # and what HumanPrompt#choose lists for `pick` and `buy --query` alike.
+    # `url` is the product page as find/compare returned it; the agent shows
+    # it as a link next to the choice.
+    module OfferChoice
+      module_function
+
+      # @param offer [Hash] a find report's symbol-keyed offer or a saved
+      #   (History) string-keyed one.
+      def for(offer)
+        offer = offer.transform_keys(&:to_s)
+        { ref: offer["offer_ref"], label: label(offer), store: offer["store"], product_id: offer["product_id"],
+          title: offer["title"], amount: offer["amount"], currency: offer["currency"],
+          checkout: offer["checkout"], url: offer["url"] }
+      end
+
+      def label(offer)
+        price = offer["amount"] ? Money.format_amount(offer["amount"], offer["currency"]) : "price n/a"
+        parts = [offer["store"], offer["title"], price]
+        parts << "browse only" if offer["checkout"] == false
+        parts.compact.join(" — ")
+      end
+
+      # The tty `v N` answer for one choice: the page's own outcome message.
+      def view_message(choice)
+        return "Nothing to view for that choice." unless choice[:store]
+
+        ProductPage.new(url: choice[:url], store: choice[:store]).open[:message]
+      end
+    end
+  end
+end