portage-cli 0.6.4 → 0.7.3

data/lib/portage/cli/checkout_handoff.rb

@@ -1,5 +1,6 @@
 require "uri"
 require_relative "config"
+require_relative "setting"
 
 module Portage
   module Cli
@@ -8,10 +9,10 @@ module Portage
     # (escalation, permission denied, no payment token) hands off a link
     # rather than completing the purchase itself.
     #
-    # Default off. Precedence for the toggle (open decision #1, resolved):
-    # a per-invocation `auto_open:` override (portage buy --auto-open /
-    # --no-auto-open) beats PORTAGE_AUTO_OPEN_CHECKOUT, which beats
-    # ~/.portage/config.json's "auto_open_checkout" (Config).
+    # Default off. Precedence for the toggle (open decision #1, resolved,
+    # see Setting): a per-invocation `auto_open:` override (portage buy
+    # --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
@@ -22,7 +23,6 @@ module Portage
     class CheckoutHandoff
       ENV_VAR = "PORTAGE_AUTO_OPEN_CHECKOUT".freeze
       CONFIG_KEY = "auto_open_checkout".freeze
-      TRUE_VALUES = %w[1 true yes].freeze
 
       def initialize(auto_open: nil, config: Config.load)
         @override = auto_open
@@ -30,12 +30,7 @@ module Portage
       end
 
       def auto_open?
-        return @override unless @override.nil?
-
-        env = env_override
-        return env unless env.nil?
-
-        !!@config.get(CONFIG_KEY)
+        Setting.flag?(override: @override, env: ENV_VAR, config: @config, config_key: CONFIG_KEY)
       end
 
       # @return [Boolean] whether the browser was actually opened.
@@ -47,13 +42,6 @@ module Portage
 
       private
 
-      def env_override
-        raw = ENV.fetch(ENV_VAR, nil)
-        return nil if raw.nil?
-
-        TRUE_VALUES.include?(raw.downcase)
-      end
-
       def https?(url)
         URI.parse(url).scheme == "https"
       rescue URI::InvalidURIError

data/lib/portage/cli/confidence_check.rb

@@ -0,0 +1,127 @@
+require "json"
+require_relative "setting"
+require_relative "decisions"
+
+module Portage
+  module Cli
+    # The confidence gate (docs/plans/system-one-decision-layer.md
+    # § Responsibilities 3) as `portage buy` uses it: one yes/no question put
+    # to a Decision::ModelBackends backend right before an unattended
+    # (`--yes`) completion — "is this checkout what the shopper asked for,
+    # and safe to complete without a person looking at it?"
+    #
+    # Default off. Nothing asks a model anything unless a backend is named,
+    # via `--decision-backend NAME` or PORTAGE_DECISION_BACKEND (`jev` or
+    # `laya`, Decision::ModelBackends::REGISTRY's keys). The threshold comes
+    # from `--min-confidence N` or PORTAGE_MIN_CONFIDENCE, else
+    # DEFAULT_THRESHOLD.
+    #
+    # This answers the plan's open question about how the gate relates to
+    # `Confirmer`: it runs in front of the completion, after `--yes` and the
+    # local PolicyCheck, and never in place of either. A low score holds the
+    # purchase and hands the checkout to the shopper. It never
+    # auto-approves anything `--yes` wouldn't already have allowed.
+    #
+    # Fails closed. An unknown backend name, a backend that isn't configured
+    # (no JEV_API_KEY, no Laya bridge), or a backend call that fails all hold
+    # the purchase, the same as a low score does. So does naming a backend
+    # without portage-ucp-decision installed: the backends live in that
+    # optional gem. Once a caller has asked for a confidence check, the
+    # check never passing is not "no opinion".
+    class ConfidenceCheck
+      BACKEND_ENV = "PORTAGE_DECISION_BACKEND".freeze
+      THRESHOLD_ENV = "PORTAGE_MIN_CONFIDENCE".freeze
+      DEFAULT_THRESHOLD = 0.8
+      QUESTION = "safe_to_complete".freeze
+      # Phrased so "yes" means "proceed": a noul answer's value is the
+      # probability of yes, and that is what ConfidenceGate thresholds.
+      INSTRUCTIONS = "The state is a checkout an agent built on a shopper's behalf: the shopper's search " \
+                     "query, the merchant, the requested quantity, the checkout's line items and totals, and " \
+                     "any warnings about where the checkout differs from the request. Answer yes only if the " \
+                     "checkout clearly matches what the shopper asked for and is safe to complete without a " \
+                     "person reviewing it first.".freeze
+
+      # @param backend [String, nil] a ModelBackends::REGISTRY key; nil
+      #   defers to PORTAGE_DECISION_BACKEND.
+      # @param threshold [Float, nil] 0.0..1.0; nil defers to
+      #   PORTAGE_MIN_CONFIDENCE, then DEFAULT_THRESHOLD.
+      # @param resolver [#call, nil] builds a backend from its name —
+      #   injectable so specs never reach a real model. nil means
+      #   ModelBackends.resolve, looked up only once a backend is needed.
+      # @raise [ArgumentError] for a threshold outside 0.0..1.0. An explicit
+      #   `threshold:` is always checked, so a mistyped `--min-confidence`
+      #   fails loudly. PORTAGE_MIN_CONFIDENCE is read, and so checked,
+      #   only once a backend is enabled: a stale value in a shell that
+      #   never uses the gate mustn't stop every `portage buy`.
+      def initialize(backend: nil, threshold: nil, resolver: nil)
+        @backend_name = Setting.resolve(override: backend, env: BACKEND_ENV)&.to_s&.strip
+        raw_threshold = enabled? ? Setting.resolve(override: threshold, env: THRESHOLD_ENV) : threshold
+        @threshold = parse_threshold(raw_threshold || DEFAULT_THRESHOLD)
+        @resolver = resolver
+      end
+
+      attr_reader :threshold
+
+      def enabled? = !@backend_name.nil?
+
+      # @param state [Hash] JSON-serializable. Never pass it a payment token.
+      # @return [Hash, nil] nil when disabled. Otherwise `proceed:`,
+      #   `reason:`, `confidence:`, `threshold:`, `backend:` and `error:`.
+      #   `reason` is nil when it proceeds, else why it held:
+      #   `below_threshold`, `backend_error` (unknown, unconfigured or
+      #   failed backend) or `not_installed` (no portage-ucp-decision).
+      #   `error` is the detail behind the last two, nil otherwise.
+      def call(state)
+        return nil unless enabled?
+        return held("not_installed", not_installed_message) unless Decisions.available?
+
+        verdict = Portage::Ucp::Decision::ConfidenceGate.via_backend(
+          backend: resolve_backend, state: JSON.generate(state), question: QUESTION,
+          instructions: INSTRUCTIONS, threshold: @threshold
+        )
+        { proceed: verdict.proceed, reason: verdict.proceed ? nil : "below_threshold",
+          confidence: verdict.confidence, threshold: @threshold, backend: @backend_name, error: nil }
+      rescue StandardError => e
+        # Any failure, not only Decision::Error: this runs after a real
+        # checkout exists, so an escaped exception would drop the report,
+        # the hand-off and the history entry along with the purchase.
+        held("backend_error", e.message)
+      end
+
+      # What `portage doctor` reports: why the named backend would hold every
+      # `--yes` purchase, before one is attempted.
+      # @return [String, nil] nil when disabled or ready to answer.
+      def configuration_problem
+        return nil unless enabled?
+        return not_installed_message unless Decisions.available?
+
+        resolve_backend.configuration_problem
+      rescue Portage::Ucp::Decision::Error => e
+        e.message
+      end
+
+      private
+
+      def resolve_backend
+        (@resolver || Portage::Ucp::Decision::ModelBackends.method(:resolve)).call(@backend_name)
+      end
+
+      def held(reason, error)
+        { proceed: false, reason: reason, confidence: nil, threshold: @threshold, backend: @backend_name,
+          error: error }
+      end
+
+      def not_installed_message
+        "portage-ucp-decision is not installed — `gem install portage-ucp-decision` to use the " \
+          "#{@backend_name} confidence check."
+      end
+
+      def parse_threshold(raw)
+        value = Float(raw, exception: false)
+        return value if value&.between?(0.0, 1.0)
+
+        raise ArgumentError, "confidence threshold must be a number between 0.0 and 1.0, got #{raw.inspect}"
+      end
+    end
+  end
+end

data/lib/portage/cli/decisions.rb

@@ -0,0 +1,72 @@
+require "portage/ucp"
+
+module Portage
+  module Cli
+    # portage-cli's judgment calls (docs/plans/system-one-decision-layer.md).
+    # The rules live in portage-ucp core: Support::OfferRanking,
+    # Support::Escalation and PolicyGuard. portage-ucp-decision's
+    # OfferRanking, EscalationPolicy and PolicyCheck are typed wrappers
+    # around those same modules, so `buy` and `find` answer the same way
+    # whether or not that gem is installed.
+    #
+    # Every method returns a plain Hash whose `reason` is a String or nil,
+    # so a caller sees the same values in-process as in `--json`.
+    #
+    # Only the confidence gate needs the optional gem, because the model
+    # backends live there (see ConfidenceCheck and .available?).
+    module Decisions
+      # Loaded the way Resolver.build_adapter's callers treat an optional
+      # adapter gem: `require`, then rescue LoadError. It isn't in the
+      # gemspec, so `gem install portage-cli` stays light.
+      # @return [Boolean] whether portage-ucp-decision could be loaded.
+      #   Memoized: `require` runs once per process.
+      def self.available?
+        return @available unless @available.nil?
+
+        @available = begin
+          require "portage/ucp/decision"
+          true
+        rescue LoadError
+          false
+        end
+      end
+
+      # @param offers [Array<Hash>] with `:checkout` (buyable) and `:amount`.
+      def self.rank(offers)
+        Portage::Ucp::Support::OfferRanking.rank(offers) { |offer| [offer[:checkout], offer[:amount]] }
+      end
+
+      # @param warnings [Array<String>] mismatches that should escalate —
+      #   pass none when mismatches are only to be reported.
+      # @return [Hash] `escalate:`, `reason:`.
+      def self.escalation(checkout_status:, warnings: [])
+        reason = Portage::Ucp::Support::Escalation.reason(checkout_status: checkout_status, warnings: warnings)
+        { escalate: !reason.nil?, reason: reason&.to_s }
+      end
+
+      # The buyer's spend policy, checked by PolicyGuard.
+      #
+      # PolicyGuard skips both spend caps when `amount` is nil, which suits
+      # its own caller (an adapter that can't price a checkout up front).
+      # Here it would let a checkout with no `total` line past a configured
+      # cap while reporting `allowed: true`, so a missing total is denied as
+      # `total_unknown` whenever a cap exists.
+      # @param transaction_log [Portage::Ucp::Support::TransactionLog] what
+      #   the rolling cap and velocity limit count.
+      # @return [Hash] `allowed:`, `reason:`.
+      def self.policy(amount:, currency:, merchant:, token_ref:,
+                      transaction_log: Portage::Ucp::Support::TransactionLog.new)
+        policy = Portage::Ucp::Policy.load
+        if amount.nil? && (policy.per_transaction_cap || policy.rolling_cap)
+          return { allowed: false, reason: "total_unknown" }
+        end
+
+        Portage::Ucp::PolicyGuard.check!(amount: amount, currency: currency, merchant: merchant,
+                                         token_ref: token_ref, policy: policy, transaction_log: transaction_log)
+        { allowed: true, reason: nil }
+      rescue Portage::Ucp::PolicyViolationError => e
+        { allowed: false, reason: e.reason.to_s }
+      end
+    end
+  end
+end

data/lib/portage/cli/doctor.rb

@@ -1,4 +1,8 @@
 require "portage/ucp"
+require "uri"
+require_relative "confidence_check"
+require_relative "user_agent"
+require_relative "proxy_settings"
 
 module Portage
   module Cli
@@ -14,8 +18,9 @@ module Portage
     class Doctor
       Finding = Struct.new(:check, :message, keyword_init: true)
 
-      def initialize(adapter_class: nil)
+      def initialize(adapter_class: nil, proxy_settings: ProxySettings.new)
         @adapter_class = adapter_class
+        @proxy_settings = proxy_settings
       end
 
       def call
@@ -24,6 +29,10 @@ module Portage
           rate_limiter_finding,
           signing_keys_finding,
           payment_handlers_finding,
+          decision_backend_finding,
+          user_agent_finding,
+          proxy_finding,
+          *proxy_doctor_findings,
           *capability_findings
         ].compact
       end
@@ -54,6 +63,95 @@ module Portage
         Finding.new(check: "signing_keys", message: "No signing_keys configured — the manifest ships unsigned.")
       end
 
+      # The confidence gate's backend, checked only once one is selected
+      # (PORTAGE_DECISION_BACKEND): the gate is off by default, and a
+      # missing key for a backend nobody chose is noise. Once one is
+      # selected, anything short of ready holds every `--yes` purchase, so
+      # it's flagged here rather than first surfacing mid-checkout. Covers
+      # the gem not being installed, an unknown backend name, a missing
+      # JEV_API_KEY, a missing Laya bridge, and a bad PORTAGE_MIN_CONFIDENCE.
+      def decision_backend_finding
+        problem = ConfidenceCheck.new.configuration_problem
+        problem && Finding.new(check: "decision_backend",
+                               message: "#{problem} — until then every `portage buy --yes` is held for the shopper.")
+      rescue ArgumentError => e
+        Finding.new(check: "decision_backend", message: e.message)
+      end
+
+      # PORTAGE_USER_AGENT / config.json's "user_agent" (UserAgent) is sent
+      # as-is on every outbound request. Net::HTTP raises ArgumentError on a
+      # header value containing CR/LF rather than send it, so a bad override
+      # would otherwise surface for the first time mid-checkout instead of
+      # here.
+      def user_agent_finding
+        value = Portage::Cli::UserAgent.value
+        return unless value =~ /[\r\n]/
+
+        Finding.new(check: "user_agent",
+                    message: "Configured User-Agent (PORTAGE_USER_AGENT or user_agent in " \
+                             "~/.portage/config.json) contains a newline — every outbound request will " \
+                             "raise instead of sending.")
+      end
+
+      # Phase 0 of docs/plans/proxy-support.md: every raw Net::HTTP.start call
+      # site in portage-cli/portage-ucp/the adapter gems resolves its proxy
+      # from Ruby stdlib's own `:ENV` default, which — confirmed against a
+      # real local proxy — only ever reads `http_proxy`/`HTTP_PROXY`, for
+      # *both* http and https targets, and never `https_proxy`/`HTTPS_PROXY`.
+      # That's surprising enough (and the failure silent enough — requests
+      # just go direct) that it's worth a doctor check on both sides: report
+      # the effective proxy when one is actually active, and flag the classic
+      # footgun of setting only HTTPS_PROXY and expecting it to do anything
+      # here.
+      def proxy_finding
+        http_proxy = ENV["http_proxy"] || ENV.fetch("HTTP_PROXY", nil)
+        return https_only_proxy_finding if !http_proxy && https_env_proxy_set?
+
+        return unless http_proxy
+
+        Finding.new(check: "proxy",
+                    message: "Outbound requests proxy through #{redact_proxy_url(http_proxy)} " \
+                             "(from #{ENV['http_proxy'] ? 'http_proxy' : 'HTTP_PROXY'}, used for both http:// " \
+                             "and https:// targets)#{no_proxy_suffix}.")
+      end
+
+      def https_only_proxy_finding
+        Finding.new(check: "proxy",
+                    message: "HTTPS_PROXY/https_proxy is set but http_proxy/HTTP_PROXY is not — Ruby's " \
+                             "Net::HTTP only ever reads http_proxy for its :ENV proxy mode (for both http:// " \
+                             "and https:// targets), so every portage-cli/portage-ucp/adapter call site is " \
+                             "proxying nothing right now. Set http_proxy (it covers https:// targets too) if " \
+                             "that traffic should go through a proxy. (portage-ucp-client's own UCP/MCP tool " \
+                             "calls are the one exception — they're Faraday-based and do read https_proxy.)")
+      end
+
+      def https_env_proxy_set?
+        !(ENV["https_proxy"].to_s.empty? && ENV["HTTPS_PROXY"].to_s.empty?)
+      end
+
+      def no_proxy_suffix
+        no_proxy = ENV["no_proxy"] || ENV.fetch("NO_PROXY", nil)
+        no_proxy ? "; no_proxy=#{no_proxy}" : ""
+      end
+
+      # `http://***@host:port` — never the real credentials (see the plan's
+      # "Credentials stay safe" constraint).
+      def redact_proxy_url(url)
+        uri = URI.parse(url.include?("://") ? url : "http://#{url}")
+        userinfo = uri.userinfo ? "***@" : ""
+        port = uri.port ? ":#{uri.port}" : ""
+        "#{uri.scheme}://#{userinfo}#{uri.host}#{port}"
+      rescue URI::InvalidURIError
+        "(unparseable proxy URL)"
+      end
+
+      # Phase 2's own checks against whatever ProxySettings resolved
+      # (flags/env/config.json), kept separate from proxy_finding above —
+      # see ProxyDoctor's own comment for why the two don't merge.
+      def proxy_doctor_findings
+        ProxyDoctor.new(proxy_settings: @proxy_settings).findings
+      end
+
       def payment_handlers_finding
         return unless Array(config.payment_handlers).empty?
 
@@ -89,3 +187,8 @@ module Portage
     end
   end
 end
+
+# Loaded after Doctor closes — ProxyDoctor calls Doctor::Finding.new, so
+# Doctor has to exist first (this file requires proxy_settings, not
+# proxy_doctor, at the top for exactly this reason).
+require_relative "proxy_doctor"

data/lib/portage/cli/find.rb

@@ -4,6 +4,8 @@ require "portage/ucp/client"
 
 require_relative "search_backends"
 require_relative "probe_cache"
+require_relative "decisions"
+require_relative "user_agent"
 
 module Portage
   module Cli
@@ -127,7 +129,7 @@ module Portage
       end
 
       def discover(origin)
-        Portage::Ucp::Client.discover(origin)
+        Portage::Ucp::Client.discover(origin, headers: UserAgent.headers)
       rescue StandardError
         nil
       end
@@ -166,14 +168,13 @@ module Portage
           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
+      # Buyable first, then cheapest, then unpriced (see Decisions.rank —
+      # core's Support::OfferRanking, the rule portage-ucp-decision's
+      # OfferRanking wraps), so an agent loop ranking its own candidate list
+      # gets the same order this command prints. 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) = Decisions.rank(offers)
 
       # --- Shapes ---
 

data/lib/portage/cli/handoff_reconciler/wire_adapters.rb

@@ -0,0 +1,50 @@
+module Portage
+  module Cli
+    class HandoffReconciler
+      # Adapts a wire hash (from #get_checkout/#get_order) to what
+      # OrderLedger#record/PurchaseJournal#record_checkout duck-type against
+      # (Portage::Ucp::Order/Checkout value objects) — see
+      # docs/plans/handoff-reconcile.md, "The journal needs a
+      # hash-to-value-object step". Deliberately not a second, parallel
+      # entry shape: both still go through PurchaseJournal#record_checkout /
+      # OrderLedger#record's own logic (`to_wire_h`) — these just wrap the
+      # already-wire-shaped hash to answer the handful of methods each one
+      # calls.
+      WireOrder = Struct.new(:wire) do
+        def id = wire["id"]
+        def to_wire_h = wire
+      end
+
+      WireCheckout = Struct.new(:wire) do
+        def currency = wire["currency"]
+        def order = wire["order"] && WireOrderRef.new(wire["order"])
+
+        def line_items
+          Array(wire["line_items"]).map { |li| WireLineItem.new(li) }
+        end
+      end
+
+      WireOrderRef = Struct.new(:wire) do
+        def id = wire["id"]
+      end
+
+      WireLineItem = Struct.new(:wire) do
+        def item = WireItem.new(wire["item"] || {})
+        def quantity = wire["quantity"]
+
+        def totals
+          Array(wire["totals"]).map { |t| WireTotal.new(t) }
+        end
+      end
+
+      WireItem = Struct.new(:wire) do
+        def id = wire["id"]
+      end
+
+      WireTotal = Struct.new(:wire) do
+        def type = wire["type"]
+        def amount = wire["amount"]
+      end
+    end
+  end
+end