portage-cli 0.7.0 → 0.7.4

data/lib/portage/cli/install_doctor.rb

@@ -0,0 +1,239 @@
+require "rbconfig"
+require_relative "version"
+
+module Portage
+  module Cli
+    # Phase 4 of docs/plans/homebrew-distribution.md's `doctor` checks: how
+    # this copy of portage-cli was installed (Homebrew formula or plain
+    # `gem install`), which Ruby it runs on, which first-party adapter gems
+    # it can load, and whether the `portage` a shell would actually run is
+    # this one.
+    #
+    # That last check is the one that matters. The formula installs into its
+    # own Cellar keg, and a `gem install portage-cli` copy in a mise/rbenv/
+    # asdf/rvm Ruby's bin usually comes earlier on PATH, so `portage` in a
+    # shell silently keeps running the old gem after `brew install` or
+    # `brew upgrade` (Homebrew's own caveat hit exactly this on the
+    # maintainer's machine). Homebrew's `bin/portage` is a symlink into the
+    # Cellar, whose env_script wrapper execs the libexec binary, so every
+    # comparison here is between canonical Cellar locations, never raw PATH
+    # entries.
+    #
+    # Everything is read from the filesystem and the process: no `brew`
+    # shell-out, no network, so doctor stays fast and works offline (the
+    # formula's `test do` block runs it in Homebrew's sandbox).
+    class InstallDoctor
+      DEFAULT_HOMEBREW_PREFIXES = %w[/opt/homebrew /usr/local /home/linuxbrew/.linuxbrew].freeze
+      ADAPTER_GEMS = %w[shopify wix woocommerce bigcommerce magento etsy instagram webmcp decision]
+                     .map { |name| "portage-ucp-#{name}" }.freeze
+      EXECUTABLE = "portage".freeze
+
+      def self.homebrew_prefixes
+        [ENV.fetch("HOMEBREW_PREFIX", nil), *DEFAULT_HOMEBREW_PREFIXES].reject { |p| p.to_s.empty? }.uniq
+      end
+
+      # @param path [String] PATH to search for `portage` executables.
+      # @param homebrew_prefixes [Array<String>] candidate HOMEBREW_PREFIXes.
+      # @param gem_dir [String] this gem's own directory (its `lib/`'s parent).
+      # @param ruby [String] the running Ruby's executable path.
+      # @param adapter_probe [#call] gem name -> { installed:, loadable:, version:, error: }.
+      def initialize(path: ENV.fetch("PATH", ""), homebrew_prefixes: self.class.homebrew_prefixes,
+                     gem_dir: File.expand_path("../../..", __dir__), ruby: RbConfig.ruby,
+                     adapter_probe: method(:probe_adapter))
+        @path = path
+        @homebrew_prefixes = homebrew_prefixes.map { |prefix| canonical(prefix) }
+        @gem_dir = canonical(gem_dir)
+        @ruby = ruby
+        @adapter_probe = adapter_probe
+      end
+
+      def findings
+        [install_finding, runtime_finding, adapters_finding, path_finding].compact
+      end
+
+      # @return [String, nil] the HOMEBREW_PREFIX this copy runs from, nil for a gem install.
+      def homebrew_prefix
+        return @homebrew_prefix if defined?(@homebrew_prefix)
+
+        @homebrew_prefix = @homebrew_prefixes.find do |prefix|
+          [@gem_dir, canonical(@ruby)].any? { |dir| under?(dir, keg_root(prefix)) }
+        end
+      end
+
+      def homebrew? = !homebrew_prefix.nil?
+
+      private
+
+      # --- install method -------------------------------------------------
+
+      def install_finding
+        method = homebrew? ? "homebrew" : "gem"
+        path = homebrew? ? installed_keg : @gem_dir
+        details = { method: method, path: path }
+        details[:prefix] = homebrew_prefix if homebrew?
+        info("install", "#{method} (#{path})", details)
+      end
+
+      def keg_root(prefix) = File.join(prefix, "Cellar", "portage")
+
+      # `<prefix>/Cellar/portage/<version>`, the keg this copy lives in.
+      def installed_keg
+        root = keg_root(homebrew_prefix)
+        version = @gem_dir.delete_prefix("#{root}/").split("/").first
+        File.join(root, version)
+      end
+
+      # --- runtime --------------------------------------------------------
+
+      def runtime_finding
+        info("runtime", "Ruby #{RUBY_VERSION} (#{@ruby}), portage-cli #{VERSION}",
+             { ruby_version: RUBY_VERSION, ruby_path: @ruby, portage_cli_version: VERSION })
+      end
+
+      # --- adapters -------------------------------------------------------
+
+      # A gem install without adapters is normal: `gem install portage-cli`
+      # pulls in none of them, and you add the ones you use. The formula
+      # bundles every one, so a Homebrew install missing one is broken.
+      def adapters_finding
+        report = AdapterReport.new(ADAPTER_GEMS.map { |name| { name: name }.merge(safe_probe(name)) })
+        details = { adapters: report.adapters }
+        return warning("adapters", report.homebrew_missing_message, details) if homebrew? && report.missing?
+
+        info("adapters", report.summary, details)
+      end
+
+      def safe_probe(name)
+        @adapter_probe.call(name)
+      rescue StandardError, ScriptError => e
+        { installed: true, loadable: false, version: nil, error: "#{e.class}: #{e.message}" }
+      end
+
+      def probe_adapter(name)
+        specs = Gem::Specification.find_all_by_name(name)
+        return { installed: false, loadable: false, version: nil } if specs.empty?
+
+        require "portage/ucp/#{name.delete_prefix('portage-ucp-')}"
+        spec = Gem.loaded_specs[name] || specs.max_by(&:version)
+        { installed: true, loadable: true, version: spec.version.to_s }
+      end
+
+      # --- PATH shadowing -------------------------------------------------
+
+      def path_finding
+        candidates = path_candidates
+        return if candidates.empty?
+
+        details = { first: candidates.first[:path], candidates: candidates }
+        message = shadow_message(candidates.first)
+        return warning("path", message, details) if message
+
+        # Only a Homebrew keg can be matched to this copy for certain; a gem
+        # install's binstub can sit behind a mise/rbenv shim.
+        suffix = homebrew? ? " (this install)" : ""
+        info("path", "`portage` on PATH is #{candidates.first[:path]}#{suffix}", details)
+      end
+
+      # Every `portage` on PATH, first match first, one entry per real file:
+      # the same Homebrew bin can sit on PATH twice, and `bin/portage` and
+      # `opt/portage/bin/portage` both resolve to one keg.
+      def path_candidates
+        candidates = @path.split(File::PATH_SEPARATOR).reject(&:empty?).filter_map { |dir| candidate(dir) }
+        candidates.uniq { |c| c[:realpath] }
+      end
+
+      def candidate(dir)
+        file = File.join(dir, EXECUTABLE)
+        return unless File.file?(file) && File.executable?(file)
+
+        real = canonical(file)
+        { path: file, realpath: real, kind: homebrew_keg?(real) ? "homebrew" : "other" }
+      end
+
+      def shadow_message(first)
+        if homebrew?
+          return if under?(first[:realpath], keg_root(homebrew_prefix))
+
+          homebrew_shadowed_message(first)
+        elsif first[:kind] == "homebrew"
+          gem_shadowed_message(first)
+        end
+      end
+
+      def homebrew_shadowed_message(first)
+        brew_bin = File.join(homebrew_prefix, "bin")
+        "`portage` on PATH runs #{first[:path]}, not this Homebrew install (#{brew_bin}/portage), " \
+          "so `brew upgrade portage` won't change what your shell runs. Check with `which -a portage`. " \
+          "Fix: if that's a `gem install` copy, run `gem uninstall portage-cli` with that Ruby active; " \
+          "or put #{brew_bin} ahead of #{File.dirname(first[:path])} in PATH."
+      end
+
+      def gem_shadowed_message(first)
+        "`portage` on PATH runs the Homebrew install (#{first[:path]}), not this gem install " \
+          "(#{@gem_dir}). Check with `which -a portage`. Fix: keep one — `brew uninstall portage` " \
+          "to use the gem, or `gem uninstall portage-cli` to use Homebrew; or reorder PATH."
+      end
+
+      def homebrew_keg?(realpath)
+        @homebrew_prefixes.any? { |prefix| under?(realpath, keg_root(prefix)) }
+      end
+
+      # --- helpers --------------------------------------------------------
+
+      def under?(path, root) = path.start_with?("#{root}/")
+
+      def canonical(path)
+        File.realpath(path)
+      rescue SystemCallError
+        File.expand_path(path)
+      end
+
+      def info(check, message, details) = finding(check, message, details, "info")
+      def warning(check, message, details) = finding(check, message, details, "warning")
+
+      def finding(check, message, details, level)
+        Doctor::Finding.new(check: check, message: message, level: level, details: details)
+      end
+    end
+
+    # The adapters line of InstallDoctor's report, one probe result per gem:
+    # `{ name:, installed:, loadable:, version:, error: }`.
+    class InstallDoctor
+      class AdapterReport
+        attr_reader :adapters
+
+        def initialize(adapters)
+          @adapters = adapters
+        end
+
+        def missing = @adapters.reject { |a| a[:loadable] }
+        def missing? = missing.any?
+
+        def summary
+          loaded, broken, absent = partitioned
+          parts = [loaded.empty? ? "none loadable" : loaded.map { |a| "#{short(a)} #{a[:version]}" }.join(", ")]
+          parts << "failed to load: #{names(broken)}" unless broken.empty?
+          parts << "not installed: #{names(absent)}" unless absent.empty?
+          parts.join("; ")
+        end
+
+        def homebrew_missing_message
+          described = missing.map { |a| a[:error] ? "#{short(a)} (#{a[:error]})" : short(a) }
+          "This Homebrew install bundles every adapter, but #{described.join(', ')} can't be loaded — " \
+            "reinstall with `brew reinstall portage`."
+        end
+
+        private
+
+        def partitioned
+          loaded, rest = @adapters.partition { |a| a[:loadable] }
+          broken, absent = rest.partition { |a| a[:installed] }
+          [loaded, broken, absent]
+        end
+
+        def names(adapters) = adapters.map { |a| short(a) }.join(", ")
+        def short(adapter) = adapter[:name].delete_prefix("portage-ucp-")
+      end
+    end
+  end
+end

data/lib/portage/cli/macos_notifier.rb

@@ -0,0 +1,37 @@
+module Portage
+  module Cli
+    # docs/plans/handoff-reconcile.md Phase 3's "macos" notify channel — a
+    # native notification banner for a settled handoff. Opt-in (see
+    # ReconcileNotify), and a no-op off Darwin.
+    #
+    # `system("osascript", "-e", script)` in array form, never an
+    # interpolated shell string — same posture as CheckoutHandoff's
+    # `open`/`xdg-open`. The injection surface that remains is the
+    # AppleScript source itself: `title`/`message` come from a merchant
+    # name and an amount, both untrusted, so they're never spliced into the
+    # script raw. #applescript_string escapes backslashes and double quotes
+    # before interpolating, so a merchant name like `foo" & do shell script
+    # "rm -rf ~" & "` can't break out of its quoted string and run as
+    # AppleScript.
+    class MacosNotifier
+      def call(title:, message:)
+        return false unless RbConfig::CONFIG["host_os"] =~ /darwin/i
+
+        script = "display notification #{applescript_string(message)} with title #{applescript_string(title)}"
+        !!system("osascript", "-e", script)
+      rescue StandardError
+        false
+      end
+
+      private
+
+      def applescript_string(text)
+        # Block form, not a replacement string: gsub treats "\\" in a
+        # replacement *string* as a backreference escape, which would
+        # collapse a literal backslash right back down to one.
+        escaped = text.to_s.gsub("\\") { "\\\\" }.gsub('"') { '\"' }
+        "\"#{escaped}\""
+      end
+    end
+  end
+end

data/lib/portage/cli/notifier.rb

@@ -1,8 +1,11 @@
 require "net/http"
 require "json"
 require "uri"
+require "portage/ucp"
+require "portage/ucp/support/connection"
 require_relative "config"
 require_relative "setting"
+require_relative "user_agent"
 
 module Portage
   module Cli
@@ -63,9 +66,9 @@ module Portage
       private
 
       def post(uri, body)
-        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
-                                            open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
-          http.post(uri.request_uri, body, "Content-Type" => "application/json")
+        Portage::Ucp::Support::Connection.start(uri, route: :notify, open_timeout: TIMEOUT,
+                                                     read_timeout: TIMEOUT) do |http|
+          http.post(uri.request_uri, body, UserAgent.headers.merge("Content-Type" => "application/json"))
         end
       end
     end

data/lib/portage/cli/payment_methods.rb

@@ -5,6 +5,7 @@ require "uri"
 require "net/http"
 require "portage/ucp"
 require "portage/ucp/client"
+require "portage/ucp/support/connection"
 
 # Buy::PermissiveAuthenticator (adapter-loopback auth) is used by
 # #adapter_session below — not require_relative'd here to avoid a load
@@ -14,6 +15,7 @@ require "portage/ucp/client"
 require_relative "payment_methods/keychain_backend"
 require_relative "payment_methods/secret_service_backend"
 require_relative "payment_methods/env_backend"
+require_relative "user_agent"
 
 module Portage
   module Cli
@@ -199,7 +201,7 @@ module Portage
       # entangled with cart/checkout-specific branching this only needs the
       # session object from.
       def discover_session(url)
-        native = Portage::Ucp::Client.discover(url)
+        native = Portage::Ucp::Client.discover(url, headers: UserAgent.headers)
         native if native
       rescue Portage::Ucp::Client::DiscoveryError
         adapter_session(url)
@@ -221,9 +223,9 @@ module Portage
       end
 
       def fetch_homepage(uri)
-        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-payment-enroll" })
+        response = Portage::Ucp::Support::Connection.start(uri, route: :payment, open_timeout: 5,
+                                                                read_timeout: 5) do |http|
+          http.get(uri.request_uri, UserAgent.headers)
         end
         response.is_a?(Net::HTTPSuccess) ? [response.body, response.to_hash] : [nil, {}]
       rescue StandardError

data/lib/portage/cli/permissive_authenticator.rb

@@ -0,0 +1,16 @@
+require "portage/ucp"
+
+module Portage
+  module Cli
+    # 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 the
+    # adapter-fallback path, in both Buy and HandoffReconciler), authenticating
+    # this local CLI session is reasonable. Shared by both rather than
+    # defined once as a nested class of Buy, since HandoffReconciler's own
+    # reconnect needs it too and shouldn't reach into Buy's internals for it.
+    class PermissiveAuthenticator < Portage::Ucp::Authenticator
+      def call(_server_context) = :local_cli
+    end
+  end
+end

data/lib/portage/cli/proxy_doctor.rb

@@ -0,0 +1,149 @@
+require "uri"
+require_relative "proxy_settings"
+
+module Portage
+  module Cli
+    # Phase 2 of docs/plans/proxy-support.md's `doctor` checks for whatever
+    # `ProxySettings` resolved: each configured proxy's own reachability (a
+    # real CONNECT/GET through it, via Support::Connection — same code path
+    # a real request would use, not a re-implementation), whether a
+    # configured gateway answers at all, and the two warnings the plan calls
+    # out by name (plaintext credentials sitting in config.json, an
+    # intercepting proxy on the payment route). Every message redacts
+    # credentials the same way Support::Connection.redact does — never the
+    # real userinfo, in any finding this produces.
+    #
+    # Stays entirely separate from Doctor's own Phase 0 `proxy_finding`
+    # (the raw $http_proxy/$https_proxy env report) rather than replacing
+    # it — that one is still accurate and still worth showing for anyone who
+    # hasn't touched Phase 2 flags/config.json at all.
+    class ProxyDoctor
+      PROBE_URI = URI("https://example.com/").freeze
+      ROUTE_NAMES = %w[store search notify payment platform probe].freeze
+
+      def initialize(proxy_settings:, config: Config.load, timeout: 5, probe_uri: PROBE_URI)
+        @proxy_settings = proxy_settings
+        @config = config
+        @timeout = timeout
+        @probe_uri = probe_uri
+      end
+
+      def findings
+        [*route_summary_findings, *reachability_findings, *plaintext_credential_findings,
+         *payment_intercept_findings].compact
+      end
+
+      private
+
+      def routes = @proxy_settings.routes
+
+      # --- effective routing, credentials redacted -----------------------
+
+      def route_summary_findings
+        return [] unless anything_configured?
+
+        lines = ROUTE_NAMES.map { |name| "#{name}: #{effective_description(name)}" }
+        [Doctor::Finding.new(check: "proxy_routes", message: lines.join("; "))]
+      end
+
+      def direct_profile = Portage::Ucp::Support::ProxyConfig::Profile::DIRECT
+
+      def anything_configured?
+        routes.any? { |name, spec| name != "payment" || spec != direct_profile }
+      end
+
+      def effective_description(name)
+        return describe(routes[name]) if routes.key?(name)
+        return describe(routes["default"]) if routes.key?("default")
+
+        "unconfigured (falls back to HTTP_PROXY/HTTPS_PROXY env, or direct)"
+      end
+
+      def describe(spec)
+        spec.is_a?(Array) ? spec.map { |hop| describe_hop(hop) }.join(" -> ") : describe_hop(spec)
+      end
+
+      def describe_hop(hop)
+        return "direct" if hop.direct?
+
+        "#{hop.mode} #{redact(hop.url)}"
+      end
+
+      def redact(url)
+        return "(none)" unless url
+
+        uri = URI(url)
+        userinfo = uri.userinfo ? "***@" : ""
+        "#{uri.scheme}://#{userinfo}#{uri.host}:#{uri.port}"
+      rescue URI::InvalidURIError
+        "(unparseable)"
+      end
+
+      # --- reachability ---------------------------------------------------
+
+      def reachability_findings
+        collect_profiles.filter_map { |profile| reachability_finding(profile) }
+      end
+
+      def collect_profiles
+        hops = routes.values.flat_map { |spec| spec.is_a?(Array) ? spec : [spec] }
+        hops.reject(&:direct?).uniq(&:url)
+      end
+
+      def reachability_finding(profile)
+        probe(profile)
+        nil
+      rescue StandardError => e
+        Doctor::Finding.new(check: "proxy_reachability",
+                            message: "#{profile.mode} proxy #{redact(profile.url)} is not reachable: " \
+                                     "#{e.class}: #{e.message}")
+      end
+
+      def probe(profile)
+        synthetic = Portage::Ucp::Support::ProxyConfig.new(routes: { "probe" => profile })
+        Portage::Ucp::Support::Connection.start(@probe_uri, route: "probe", proxy: synthetic,
+                                                            open_timeout: @timeout, read_timeout: @timeout) do |http|
+          http.get(@probe_uri.request_uri, {})
+        end
+      end
+
+      # --- warnings ---------------------------------------------------
+
+      def plaintext_credential_findings
+        offenders = credential_bearing_profiles.select { |profile| plaintext_password?(profile) }
+        return [] if offenders.empty?
+
+        [Doctor::Finding.new(check: "proxy_credentials",
+                             message: "#{offenders.length} proxy profile(s) in config.json carry a plaintext " \
+                                      "password in their url — use password_ref (Keychain/Secret Service) or " \
+                                      "${ENV} instead.")]
+      end
+
+      def credential_bearing_profiles
+        raw = @config.get("proxy") || {}
+        [raw["default"], *raw.fetch("chains", {}).values.flatten, *raw.fetch("routes", {}).values].grep(Hash)
+      end
+
+      def plaintext_password?(profile)
+        uri = URI(profile["url"].to_s)
+        !uri.password.to_s.empty?
+      rescue URI::InvalidURIError
+        false
+      end
+
+      def payment_intercept_findings
+        spec = routes["payment"]
+        return [] unless intercepting?(spec)
+
+        [Doctor::Finding.new(check: "proxy_payment_intercept",
+                             message: "the payment route is routed through a proxy that can see plaintext payment " \
+                                      "data (ca_file set, or gateway mode): #{describe(spec)}.")]
+      end
+
+      def intercepting?(spec)
+        hops = spec.is_a?(Array) ? spec : [spec]
+        hops.any? { |hop| hop.gateway? || hop.ca_file }
+      end
+    end
+  end
+end

data/lib/portage/cli/proxy_settings/password_ref.rb

@@ -0,0 +1,48 @@
+require "open3"
+require_relative "../payment_methods"
+
+module Portage
+  module Cli
+    class ProxySettings
+      # Resolves `proxy.password_ref` (and any per-hop `password_ref`) the
+      # same three-tier way PaymentMethods.detect_backend picks a payment
+      # secret store: macOS Keychain, then Linux Secret Service, then
+      # nothing in headless mode. Deliberately its own service name rather
+      # than PaymentMethods::KeychainBackend/SecretServiceBackend directly —
+      # those are scoped to "portage-cli-payment", and their headless tier
+      # (EnvBackend#read(_id)) answers *every* id with PORTAGE_PAYMENT_TOKEN
+      # regardless of what was asked for, which would make a misconfigured
+      # proxy.password_ref silently leak the payment token as a proxy
+      # password. A ref that can't be resolved here just comes back nil —
+      # ProxySettings turns that into a clear config error rather than
+      # sending a proxy request with a literal "password_ref" placeholder.
+      module PasswordRef
+        SERVICE = "portage-cli-proxy".freeze
+
+        module_function
+
+        def resolve(ref)
+          return nil if ref.to_s.strip.empty?
+          return keychain(ref) if macos? && Portage::Cli::PaymentMethods.executable?("security")
+          return secret_service(ref) if linux_session? && Portage::Cli::PaymentMethods.executable?("secret-tool")
+
+          nil
+        end
+
+        def macos? = RUBY_PLATFORM.include?("darwin")
+
+        def linux_session? = ENV["DBUS_SESSION_BUS_ADDRESS"].to_s != ""
+
+        def keychain(ref)
+          out, status = Open3.capture2("security", "find-generic-password", "-a", ref, "-s", SERVICE, "-w")
+          status.success? ? out.chomp : nil
+        end
+
+        def secret_service(ref)
+          out, status = Open3.capture2("secret-tool", "lookup", "service", SERVICE, "account", ref)
+          status.success? ? out.chomp : nil
+        end
+      end
+    end
+  end
+end