portage-cli 0.6.4 → 0.7.0

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,5 @@
 require "portage/ucp"
+require_relative "confidence_check"
 
 module Portage
   module Cli
@@ -24,6 +25,7 @@ module Portage
           rate_limiter_finding,
           signing_keys_finding,
           payment_handlers_finding,
+          decision_backend_finding,
           *capability_findings
         ].compact
       end
@@ -54,6 +56,21 @@ 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
+
       def payment_handlers_finding
         return unless Array(config.payment_handlers).empty?
 

data/lib/portage/cli/find.rb

@@ -4,6 +4,7 @@ require "portage/ucp/client"
 
 require_relative "search_backends"
 require_relative "probe_cache"
+require_relative "decisions"
 
 module Portage
   module Cli
@@ -166,14 +167,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/history.rb

@@ -9,6 +9,13 @@ module Portage
     # history list` can answer "what did I already look for" and "what did I
     # already buy" without re-running anything, and `portage history clear`
     # can wipe either or both.
+    #
+    # A purchase entry is one checkout `portage buy` created, whatever came
+    # of it: `outcome` is the report's own (`purchased`, `dry_run`,
+    # `policy_blocked`, ...), so "what did I already buy" is the entries
+    # whose outcome is `purchased`, and every other entry still carries the
+    # `checkout_url` to finish it by hand. Entries written before `outcome`
+    # existed have only `checkout_status` and `message`.
     class History
       PATH = File.join(Dir.home, ".portage", "history.json").freeze
       MAX_ENTRIES = 200
@@ -18,14 +25,24 @@ module Portage
         @now = now.to_i
       end
 
-      def record_purchase(url:, query:, checkout:, message:, checkout_status: nil, products: [])
-        append("purchases", { "url" => url, "query" => query, "checkout" => checkout,
-                              "checkout_status" => checkout_status, "message" => message,
-                              "products" => products, "at" => @now })
+      # @param items [Array<Hash>] what the checkout holds (`id`, `title`,
+      #   `quantity`), not the search results it was picked from.
+      # @param total [Integer, nil] minor units of `currency`.
+      # rubocop:disable Metrics/ParameterLists -- all keywords; one entry's fields
+      def record_purchase(url:, query:, outcome:, message:, source: nil, checkout_id: nil, checkout_status: nil,
+                          checkout_url: nil, total: nil, currency: nil, items: [])
+        # rubocop:enable Metrics/ParameterLists
+        append("purchases", { "url" => url, "query" => query, "outcome" => outcome, "source" => source,
+                              "checkout_id" => checkout_id, "checkout_status" => checkout_status,
+                              "checkout_url" => checkout_url, "total" => total, "currency" => currency,
+                              "items" => items, "message" => message, "at" => @now })
       end
 
-      def record_search(query:, offer_count:, message:)
-        append("searches", { "query" => query, "offer_count" => offer_count, "message" => message, "at" => @now })
+      # @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,
+                             "at" => @now }.compact)
       end
 
       def purchases(limit: MAX_ENTRIES) = store["purchases"].last(limit)

data/lib/portage/cli/notifier.rb

@@ -1,5 +1,8 @@
 require "net/http"
+require "json"
+require "uri"
 require_relative "config"
+require_relative "setting"
 
 module Portage
   module Cli
@@ -12,15 +15,17 @@ module Portage
     # speaks HTTP.
     #
     # Default off. Precedence for the webhook URL (open decision #1,
-    # resolved, same shape as CheckoutHandoff's auto-open toggle): a
+    # resolved, same Setting as CheckoutHandoff's auto-open toggle): a
     # per-invocation `webhook_url:` override (portage buy --notify-webhook)
     # beats PORTAGE_NOTIFY_WEBHOOK_URL, which beats ~/.portage/config.json's
     # "notify_webhook_url" (Config).
     class Notifier
-      include Portage::Ucp::Support::HttpClient
-
       ENV_VAR = "PORTAGE_NOTIFY_WEBHOOK_URL".freeze
       CONFIG_KEY = "notify_webhook_url".freeze
+      TIMEOUT = 5
+      # Enough of an error body to name the problem, without pasting a whole
+      # HTML error page into the report.
+      BODY_EXCERPT = 200
 
       def initialize(webhook_url: nil, config: Config.load)
         @override = webhook_url
@@ -28,12 +33,7 @@ module Portage
       end
 
       def webhook_url
-        return @override unless @override.nil?
-
-        env = ENV.fetch(ENV_VAR, nil)
-        return env unless env.nil? || env.empty?
-
-        @config.get(CONFIG_KEY)
+        Setting.resolve(override: @override, env: ENV_VAR, config: @config, config_key: CONFIG_KEY)
       end
 
       def enabled? = !webhook_url.to_s.empty?
@@ -42,34 +42,30 @@ module Portage
       # raises out of `Buy#call` — the checkout itself is a real, correct
       # outcome independent of whether this delivery succeeded.
       #
+      # Success is any 2xx, whatever the body: Slack's incoming webhooks
+      # answer `ok` as plain text, which a JSON parse would have misreported
+      # as a failed delivery. Short timeouts, since a hand-off is waiting on
+      # this and Net::HTTP's defaults would stall it for up to two minutes.
+      #
       # @return [String, nil] the delivery failure message, or nil when
       #   disabled or on a successful POST.
       def call(payload)
         return nil unless enabled?
 
-        json_request(Net::HTTP::Post, webhook_url, body: payload)
-        nil
+        response = post(URI(webhook_url), JSON.generate(payload))
+        return nil if response.is_a?(Net::HTTPSuccess)
+
+        "webhook answered #{response.code}: #{response.body.to_s[0, BODY_EXCERPT]}"
       rescue StandardError => e
-        e.message
+        "webhook POST failed: #{e.message}"
       end
 
       private
 
-      def api_error_class
-        NotifyApiError
-      end
-
-      # Raised (internally, always rescued by #call) when the webhook POST
-      # itself fails (non-2xx) — kept distinct from a plain network error
-      # only in that it carries the response body/status, same split
-      # Confirmer::WebhookApiError draws against a raw StandardError.
-      class NotifyApiError < Portage::Ucp::Error
-        include Portage::Ucp::Support::ApiError
-
-        private
-
-        def api_label
-          "Notifier"
+      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")
         end
       end
     end

data/lib/portage/cli/setting.rb

@@ -0,0 +1,44 @@
+module Portage
+  module Cli
+    # How portage-cli resolves a standing preference, in one place
+    # (docs/plans/checkout-handoff-delivery.md open decision #1): a
+    # per-invocation override (a flag) beats its PORTAGE_* env var, which
+    # beats its ~/.portage/config.json key (Config). CheckoutHandoff,
+    # Notifier, Buy and ConfidenceCheck all read their settings through it.
+    #
+    # nil or a blank string counts as unset at every level, so an exported
+    # but empty `PORTAGE_AUTO_OPEN_CHECKOUT=` falls through to config.json
+    # rather than silently meaning "off".
+    module Setting
+      TRUE_VALUES = %w[1 true yes].freeze
+
+      module_function
+
+      # @param override [Object, nil] the flag's value, nil when not passed.
+      # @param env [String, nil] the env var's name.
+      # @param config [Config, nil]
+      # @param config_key [String, nil]
+      # @return [Object, nil] the value from the first level that's set.
+      def resolve(override: nil, env: nil, config: nil, config_key: nil)
+        return override if set?(override)
+
+        from_env = env && ENV.fetch(env, nil)
+        return from_env if set?(from_env)
+
+        from_config = config_key && config&.get(config_key)
+        from_config if set?(from_config)
+      end
+
+      # The same precedence, read as yes/no: true, or a string in
+      # TRUE_VALUES (any case). Anything else, unset included, is no.
+      def flag?(**)
+        TRUE_VALUES.include?(resolve(**).to_s.strip.downcase)
+      end
+
+      def set?(value)
+        !(value.nil? || (value.is_a?(String) && value.strip.empty?))
+      end
+      private_class_method :set?
+    end
+  end
+end

data/lib/portage/cli/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Cli
-    VERSION = "0.6.4".freeze
+    VERSION = "0.7.0".freeze
   end
 end