portage-cli 0.6.0 → 0.7.0

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.0".freeze
+    VERSION = "0.7.0".freeze
   end
 end

data/lib/portage/cli.rb

@@ -3,6 +3,7 @@ require "json"
 
 require_relative "cli/version"
 require_relative "cli/shipping_profile"
+require_relative "cli/buyer_context"
 require_relative "cli/catalog_products"
 require_relative "cli/buy"
 require_relative "cli/find"
@@ -21,7 +22,9 @@ module Portage
   module Cli
     USAGE = <<~USAGE.freeze
       usage: portage buy <url> --query "..." [--qty N] [--payment-token TOKEN]
-                                [--product-id ID] [--yes] [--dry-run] [--json]
+                                [--product-id ID] [--yes] [--dry-run]
+                                [--auto-open|--no-auto-open] [--notify-webhook URL]
+                                [--decision-backend jev|laya] [--min-confidence N] [--json]
              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]
@@ -41,13 +44,16 @@ module Portage
                                  [--velocity-count N --velocity-window-seconds N]
                                  [--allow HOST ...] [--clear-allowlist]
              portage doctor [--require FILE] [--adapter CLASS_NAME] [--json]
+             portage configure [--require FILE] [--adapter CLASS_NAME] [--json]  (alias for doctor)
+             portage setup [--require FILE] [--adapter CLASS_NAME] [--json]      (alias for doctor)
              portage generate adapter NAME [--dir DIR]
              portage generate agent-profile [--out FILE] [--key-out FILE] [--rotate]
     USAGE
 
     COMMANDS = { "buy" => :run_buy, "find" => :run_find, "compare" => :run_compare,
                  "history" => :run_history, "payment" => :run_payment, "policy" => :run_policy,
-                 "doctor" => :run_doctor, "generate" => :run_generate }.freeze
+                 "doctor" => :run_doctor, "configure" => :run_doctor, "setup" => :run_doctor,
+                 "generate" => :run_generate }.freeze
 
     # @param argv [Array<String>]
     # @return [Integer] process exit code
@@ -67,13 +73,18 @@ module Portage
 
       json = options.delete(:json)
       report = Find.new(**options).call
-      History.new.record_search(query: report[:query], offer_count: report[:offers].length,
-                                message: report[:message])
+      record_find(report)
       puts json ? JSON.pretty_generate(report) : format_find(report)
       report[:offers].any? ? 0 : 1
     end
     private_class_method :run_find
 
+    def self.record_find(report)
+      History.new.record_search(query: report[:query], offer_count: report[:offers].length,
+                                message: report[:message])
+    end
+    private_class_method :record_find
+
     def self.parse_find_options(argv)
       opts = {}
       find_option_parser(opts).parse!(argv)
@@ -153,6 +164,8 @@ module Portage
       return 1 unless parsed
 
       url = parsed[:buy][:url] || parsed[:store]
+      parsed[:confidence_check] = confidence_check(parsed, url)
+      return 1 unless parsed[:confidence_check]
       return execute_buy(parsed, url) if url
 
       buy_from_search(parsed)
@@ -166,6 +179,7 @@ module Portage
     # interactive pick has to name it. Piped/CI runs list the offers and stop.
     def self.buy_from_search(parsed)
       report = Find.new(**parsed[:find]).call
+      record_find(report)
       offer = pick_offer(report, parsed[:json])
       return report[:offers].any? ? 0 : 1 unless offer
 
@@ -192,36 +206,84 @@ module Portage
     private_class_method :prompt_for_offer
 
     def self.execute_buy(parsed, url, product_id: nil)
-      options = parsed[:buy].merge(url: url)
+      options = parsed[:buy].merge(url: url, confidence_check: parsed[:confidence_check])
       options[:product_id] ||= product_id
       report = Buy.new(**options).call
-      record_purchase(report, options[:query]) if report[:checkout]
+      record_buy(report, options[:query])
       puts parsed[:json] ? JSON.pretty_generate(report) : format_report(report)
       report[:checkout] || report[:browse] ? 0 : 1
     end
     private_class_method :execute_buy
 
-    # Only checkout attempts land here — a browse-only report never reached a
-    # checkout, so it belongs to search history, not purchase history.
-    def self.record_purchase(report, query)
-      History.new.record_purchase(
-        url: report[:url], query: query, checkout: report[:checkout],
-        checkout_status: report[:checkout_status], message: report[:message],
-        products: report[:products].map { |p| product_line(p) }
+    # Built before the buy starts (and before the search, when there's no
+    # URL), so a bad --min-confidence, or a bad PORTAGE_MIN_CONFIDENCE with
+    # a backend enabled, stops the run up front rather than after a
+    # checkout already exists.
+    def self.confidence_check(parsed, url)
+      ConfidenceCheck.new(**parsed[:confidence])
+    rescue ArgumentError => e
+      invalid_buy_option(e.message, url: url, json: parsed[:json])
+    end
+    private_class_method :confidence_check
+
+    # A buy refused before it started. Under --json that's a report like
+    # any other, with outcome `invalid_option`, so an agent loop reading
+    # stdout gets JSON rather than nothing and a line on stderr.
+    # @return [nil]
+    def self.invalid_buy_option(message, url:, json:)
+      unless json
+        warn message
+        return nil
+      end
+
+      puts JSON.pretty_generate(url: url, checkout_url: nil, products: [], warnings: [], source: "none",
+                                outcome: "invalid_option", browse: false, checkout: false, message: message)
+      nil
+    end
+    private_class_method :invalid_buy_option
+
+    # A buy that created a checkout is a purchase entry, whatever its
+    # outcome. One that never got that far (no match, browse-only, dead end,
+    # a store or adapter error) is a search at that store, so "what did I
+    # already buy" never lists a checkout that doesn't exist.
+    def self.record_buy(report, query)
+      history = History.new
+      unless report[:checkout_id]
+        return history.record_search(query: query, url: report[:url], offer_count: report[:products].length,
+                                     message: report[:message])
+      end
+
+      history.record_purchase(
+        url: report[:url], query: query, outcome: report[:outcome], source: report[:source],
+        checkout_id: report[:checkout_id], checkout_status: report[:checkout_status],
+        checkout_url: report[:checkout_url], total: report_total(report), currency: report[:currency],
+        items: Array(report[:items]).map { |item| item.transform_keys(&:to_s) }, message: report[:message]
       )
     end
-    private_class_method :record_purchase
+    private_class_method :record_buy
 
+    def self.report_total(report)
+      Portage::Ucp::Support::Totals.amount(report[:totals])
+    end
+    private_class_method :report_total
+
+    # A flag OptionParser can't read (`--min-confidence high`, `--qty two`,
+    # an unknown flag) is refused the same way as an out-of-range
+    # threshold. `--json` is looked for up front, since parsing stops at
+    # the bad flag and may never reach it.
     def self.parse_buy_options(argv)
       url = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
       buy = { url: url, qty: 1, yes: false, dry_run: false }
-      parsed = { buy: buy, find: {} }
+      parsed = { buy: buy, find: {}, confidence: {} }
+      json = argv.include?("--json")
       buy_option_parser(buy, parsed).parse!(argv)
       buy[:query] ||= ""
       return parsed if url || !buy[:query].strip.empty?
 
       warn USAGE
       nil
+    rescue OptionParser::ParseError => e
+      invalid_buy_option(e.message, url: url, json: json)
     end
     private_class_method :parse_buy_options
 
@@ -232,12 +294,23 @@ module Portage
         parser.on("--product-id ID") { |v| buy[:product_id] = v }
         parser.on("--yes") { buy[:yes] = true }
         parser.on("--dry-run") { buy[:dry_run] = true }
+        parser.on("--[no-]auto-open") { |v| buy[:auto_open] = v }
+        parser.on("--notify-webhook URL") { |v| buy[:notify_webhook] = v }
         parser.on("--json") { parsed[:json] = true }
         add_search_options(parser, buy, parsed)
+        add_confidence_options(parser, parsed[:confidence])
       end
     end
     private_class_method :buy_option_parser
 
+    # The opt-in confidence gate in front of a `--yes` completion (see
+    # ConfidenceCheck) — both default to their PORTAGE_* env vars.
+    def self.add_confidence_options(parser, confidence)
+      parser.on("--decision-backend NAME") { |v| confidence[:backend] = v }
+      parser.on("--min-confidence N", Float) { |v| confidence[:threshold] = v }
+    end
+    private_class_method :add_confidence_options
+
     # `--query` feeds both halves: it's the store search when there's no URL
     # and the catalog search once a store is settled, so it's registered once
     # here rather than twice on the same parser.
@@ -306,13 +379,30 @@ module Portage
     end
     private_class_method :format_history
 
+    # `outcome` first, since it's what the entry is for. Entries recorded
+    # before `outcome` existed fall back to their checkout_status/message.
     def self.history_purchase_line(entry)
-      "#{Time.at(entry['at'])} — #{entry['url']} (#{entry['query']}) — #{entry['checkout_status'] || entry['message']}"
+      items = Array(entry["items"]).map { |item| item_label(item) }.join(", ")
+      [
+        "#{Time.at(entry['at'])} — #{entry['outcome'] || entry['checkout_status'] || entry['message']}",
+        "#{entry['url']} (#{entry['query']})", (items unless items.empty?),
+        (format_amount(entry["total"], entry["currency"]) if entry["total"]),
+        (entry["checkout_url"] unless entry["outcome"] == "purchased")
+      ].compact.join(" — ")
     end
     private_class_method :history_purchase_line
 
+    # Takes a report's symbol-keyed item or a history entry's string-keyed
+    # one.
+    def self.item_label(item)
+      item = item.transform_keys(&:to_s)
+      "#{item['title'] || item['id']} x#{item['quantity']}"
+    end
+    private_class_method :item_label
+
     def self.history_search_line(entry)
-      "#{Time.at(entry['at'])} — \"#{entry['query']}\" — #{entry['offer_count']} offer(s)"
+      where = entry["url"] ? " at #{entry['url']}" : ""
+      "#{Time.at(entry['at'])} — \"#{entry['query']}\"#{where} — #{entry['offer_count']} result(s)"
     end
     private_class_method :history_search_line
 
@@ -594,20 +684,51 @@ module Portage
       puts "Wrote #{result[:profile_path]} (kid #{result[:kid]})"
       puts "Wrote private key to #{result[:private_key_path]} — keep this out of version control " \
            "and off the machine that serves the public profile"
+      puts "Next: commit #{result[:profile_path]}, then, once it's on main, run " \
+           "`bundle exec rake agent_profile:purge` from the repo root — see docs/agent-profile.md."
       0
     end
     private_class_method :run_generate_agent_profile
 
     # --- output ---
 
+    # The `[outcome]` tag leads so a caller reading text, not --json, has the
+    # same value to branch on that the JSON report carries.
     def self.format_report(report)
-      lines = ["#{report[:message]} (source: #{report[:source]})"]
+      lines = ["[#{report[:outcome]}] #{report[:message]} (source: #{report[:source]})"]
       report[:products].each { |p| lines << "  - #{product_line(p)}" }
+      lines.concat(format_checkout(report))
       lines << "  checkout: #{report[:checkout_url]}" if report[:checkout_url]
+      lines.concat(format_handoff(report[:handoff])) if report[:handoff]
+      lines.concat(format_decisions(report[:decisions])) if report[:decisions]&.any?
       lines.join("\n")
     end
     private_class_method :format_report
 
+    # What the checkout holds, as opposed to the search results above it,
+    # and where it differs from the request.
+    def self.format_checkout(report)
+      lines = Array(report[:items]).map { |item| "  in checkout: #{item_label(item)}" }
+      total = report_total(report)
+      lines << "  total: #{format_amount(total, report[:currency])}" if total
+      lines + Array(report[:warnings]).map { |w| "  warning: #{w}" }
+    end
+    private_class_method :format_checkout
+
+    def self.format_decisions(decisions)
+      decisions.map do |name, verdict|
+        "  decision #{name}: #{verdict.compact.map { |key, value| "#{key}=#{value}" }.join(' ')}"
+      end
+    end
+    private_class_method :format_decisions
+
+    def self.format_handoff(handoff)
+      lines = ["  opened in browser: #{handoff[:opened]}", "  notified: #{handoff[:notified]}"]
+      lines << "  notify error: #{handoff[:notify_error]}" if handoff[:notify_error]
+      lines
+    end
+    private_class_method :format_handoff
+
     def self.product_line(product)
       product.respond_to?(:title) ? "#{product.id}: #{product.title}" : "#{product['id']}: #{product['title']}"
     end
@@ -644,8 +765,13 @@ module Portage
     def self.format_price(offer)
       return "price n/a" unless offer[:amount]
 
-      "#{format('%.2f', offer[:amount] / 100.0)}#{" #{offer[:currency]}" if offer[:currency]}"
+      format_amount(offer[:amount], offer[:currency])
     end
     private_class_method :format_price
+
+    def self.format_amount(amount, currency)
+      "#{format('%.2f', amount / 100.0)}#{" #{currency}" if currency}"
+    end
+    private_class_method :format_amount
   end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portage-cli
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Tom Whitbread
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: portage-ucp
@@ -15,28 +16,34 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.8'
+        version: '0.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.8'
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: portage-ucp-client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.2
 - !ruby/object:Gem::Dependency
   name: portage-ucp-journal
   requirement: !ruby/object:Gem::Requirement
@@ -118,7 +125,10 @@ description: 'Ships the `portage` executable. `portage buy <url>` tries native U
   no SERP scraping. Depends on portage-ucp (for platform detection via Resolver),
   portage-ucp-client (for the actual buy calls), and portage-ucp-journal (for `portage-console`''s
   read-only view of local purchase/transaction/order state); no single adapter gem
-  is a hard dependency.'
+  is a hard dependency. Ranking, escalation and the spend-policy check use portage-ucp
+  core''s rules; portage-ucp-decision is optional and only the opt-in confidence gate
+  needs it.'
+email:
 executables:
 - portage
 - portage-console
@@ -132,20 +142,27 @@ files:
 - exe/portage-console
 - lib/portage/cli.rb
 - lib/portage/cli/buy.rb
+- lib/portage/cli/buyer_context.rb
 - lib/portage/cli/catalog_products.rb
+- lib/portage/cli/checkout_handoff.rb
 - lib/portage/cli/compare.rb
+- lib/portage/cli/confidence_check.rb
+- lib/portage/cli/config.rb
 - lib/portage/cli/console.rb
+- lib/portage/cli/decisions.rb
 - lib/portage/cli/doctor.rb
 - lib/portage/cli/find.rb
 - lib/portage/cli/generate/adapter.rb
 - lib/portage/cli/generate/agent_profile.rb
 - lib/portage/cli/history.rb
+- lib/portage/cli/notifier.rb
 - lib/portage/cli/payment_methods.rb
 - lib/portage/cli/payment_methods/env_backend.rb
 - lib/portage/cli/payment_methods/keychain_backend.rb
 - lib/portage/cli/payment_methods/secret_service_backend.rb
 - lib/portage/cli/probe_cache.rb
 - lib/portage/cli/search_backends.rb
+- lib/portage/cli/setting.rb
 - lib/portage/cli/shipping_profile.rb
 - lib/portage/cli/version.rb
 homepage: https://github.com/tomtom87/Portage/tree/main/portage-cli
@@ -155,6 +172,7 @@ metadata:
   source_code_uri: https://github.com/tomtom87/Portage/tree/main/portage-cli
   changelog_uri: https://github.com/tomtom87/Portage/blob/main/portage-cli/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -169,7 +187,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.21
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: portage — one CLI command to buy from any store, native UCP or not
 test_files: []