portage-cli 0.2.0 → 0.4.0

data/lib/portage/cli.rb

@@ -3,8 +3,12 @@ require "json"
 
 require_relative "cli/version"
 require_relative "cli/shipping_profile"
+require_relative "cli/catalog_products"
 require_relative "cli/buy"
 require_relative "cli/find"
+require_relative "cli/compare"
+require_relative "cli/history"
+require_relative "cli/payment_methods"
 
 module Portage
   # `portage` — the single command-line entrypoint for acting as a shopper's
@@ -17,6 +21,22 @@ module Portage
                                 [--product-id ID] [--yes] [--dry-run] [--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]
+                                    [--max-price N] [--json]
+             portage history [list] [--purchases|--searches] [--limit N] [--json]
+             portage history clear [--purchases|--searches]
+             portage payment list [--json]
+             portage payment enroll <url> [--label NAME] [--json]
+                                    [--scope-merchant HOST ...] [--scope-max-amount N] [--scope-currency CUR]
+             portage payment set-default <id>
+             portage payment remove <id>
+             portage payment freeze <id>
+             portage payment revoke <id>
+             portage policy show [--json]
+             portage policy set [--per-transaction-cap N --currency CUR]
+                                 [--rolling-cap N --rolling-window-seconds N --currency CUR]
+                                 [--velocity-count N --velocity-window-seconds N]
+                                 [--allow HOST ...] [--clear-allowlist]
     USAGE
 
     # @param argv [Array<String>]
@@ -26,6 +46,10 @@ module Portage
       case command
       when "buy" then run_buy(rest)
       when "find" then run_find(rest)
+      when "compare" then run_compare(rest)
+      when "history" then run_history(rest)
+      when "payment" then run_payment(rest)
+      when "policy" then run_policy(rest)
       else
         warn USAGE
         1
@@ -40,6 +64,8 @@ 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])
       puts json ? JSON.pretty_generate(report) : format_find(report)
       report[:offers].any? ? 0 : 1
     end
@@ -73,6 +99,50 @@ module Portage
     def self.to_minor_units(major) = (major * 100).round
     private_class_method :to_minor_units
 
+    # --- compare ---
+
+    def self.run_compare(argv)
+      options = parse_compare_options(argv)
+      return 1 unless options
+
+      json = options.delete(:json)
+      url = options.delete(:url)
+      report = Compare.new(origin_url: url, **options).call
+      # Recorded as a search, not a purchase — compare never checks out. The
+      # query string names the compare so `portage history list` doesn't
+      # read it as a plain text search for the origin product's own title.
+      History.new.record_search(query: "compare: #{url} (product #{options[:origin_product_id]})",
+                                offer_count: report[:offers].length, message: report[:message])
+      puts json ? JSON.pretty_generate(report) : format_compare(report)
+      report[:offers].any? ? 0 : 1
+    end
+    private_class_method :run_compare
+
+    def self.parse_compare_options(argv)
+      url = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
+      opts = { identity: [] }
+      compare_option_parser(opts).parse!(argv)
+      if !url || opts[:origin_product_id].to_s.strip.empty?
+        warn USAGE
+        return nil
+      end
+
+      opts[:url] = url
+      opts
+    end
+    private_class_method :parse_compare_options
+
+    def self.compare_option_parser(opts)
+      OptionParser.new do |parser|
+        parser.on("--product-id ID") { |v| opts[:origin_product_id] = v }
+        parser.on("--id VALUE") { |v| opts[:identity] << v }
+        parser.on("--results N", Integer) { |v| opts[:results] = v }
+        parser.on("--max-price N", Float) { |v| opts[:max_price] = to_minor_units(v) }
+        parser.on("--json") { opts[:json] = true }
+      end
+    end
+    private_class_method :compare_option_parser
+
     # --- buy ---
 
     def self.run_buy(argv)
@@ -122,11 +192,23 @@ module Portage
       options = parsed[:buy].merge(url: url)
       options[:product_id] ||= product_id
       report = Buy.new(**options).call
+      record_purchase(report, options[:query]) if report[:checkout]
       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) }
+      )
+    end
+    private_class_method :record_purchase
+
     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 }
@@ -164,6 +246,277 @@ module Portage
     end
     private_class_method :add_search_options
 
+    # --- history ---
+
+    def self.run_history(argv)
+      sub = argv.first && !argv.first.start_with?("-") ? argv.shift : "list"
+      case sub
+      when "list" then run_history_list(argv)
+      when "clear" then run_history_clear(argv)
+      else
+        warn USAGE
+        1
+      end
+    end
+    private_class_method :run_history
+
+    def self.run_history_list(argv)
+      opts = { limit: History::MAX_ENTRIES }
+      history_option_parser(opts).parse!(argv)
+      json = opts.delete(:json)
+      kind = opts.delete(:kind)
+      history = History.new
+      result = { purchases: kind == "searches" ? [] : history.purchases(limit: opts[:limit]),
+                 searches: kind == "purchases" ? [] : history.searches(limit: opts[:limit]) }
+      puts json ? JSON.pretty_generate(result) : format_history(result)
+      0
+    end
+    private_class_method :run_history_list
+
+    def self.run_history_clear(argv)
+      opts = {}
+      history_option_parser(opts).parse!(argv)
+      History.new.clear(kind: opts[:kind])
+      puts "Cleared #{opts[:kind] || 'purchase and search'} history."
+      0
+    end
+    private_class_method :run_history_clear
+
+    def self.history_option_parser(opts)
+      OptionParser.new do |parser|
+        parser.on("--purchases") { opts[:kind] = "purchases" }
+        parser.on("--searches") { opts[:kind] = "searches" }
+        parser.on("--limit N", Integer) { |v| opts[:limit] = v }
+        parser.on("--json") { opts[:json] = true }
+      end
+    end
+    private_class_method :history_option_parser
+
+    def self.format_history(result)
+      lines = ["Purchases:"]
+      result[:purchases].each { |p| lines << "  #{history_purchase_line(p)}" }
+      lines << "(none)" if result[:purchases].empty?
+      lines << "Searches:"
+      result[:searches].each { |s| lines << "  #{history_search_line(s)}" }
+      lines << "(none)" if result[:searches].empty?
+      lines.join("\n")
+    end
+    private_class_method :format_history
+
+    def self.history_purchase_line(entry)
+      "#{Time.at(entry['at'])} — #{entry['url']} (#{entry['query']}) — #{entry['checkout_status'] || entry['message']}"
+    end
+    private_class_method :history_purchase_line
+
+    def self.history_search_line(entry)
+      "#{Time.at(entry['at'])} — \"#{entry['query']}\" — #{entry['offer_count']} offer(s)"
+    end
+    private_class_method :history_search_line
+
+    # --- payment ---
+
+    # Maps each single-id subcommand to the PaymentMethods method it calls —
+    # collapsing what would otherwise be four near-identical `when` branches
+    # (each just yielding a different method to #run_payment_mutate) into one
+    # table lookup.
+    PAYMENT_MUTATIONS = { "set-default" => :make_default, "remove" => :remove,
+                          "freeze" => :freeze_method, "revoke" => :revoke }.freeze
+
+    def self.run_payment(argv)
+      sub = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
+      return run_payment_list(argv) if sub == "list"
+      return run_payment_enroll(argv) if sub == "enroll"
+      return run_payment_mutate(argv, PAYMENT_MUTATIONS[sub]) if PAYMENT_MUTATIONS.key?(sub)
+
+      warn USAGE
+      1
+    end
+    private_class_method :run_payment
+
+    def self.run_payment_list(argv)
+      json = false
+      OptionParser.new { |parser| parser.on("--json") { json = true } }.parse!(argv)
+      methods = PaymentMethods.new.list
+      puts json ? JSON.pretty_generate(methods) : format_payment_list(methods)
+      0
+    end
+    private_class_method :run_payment_list
+
+    # Shared by set-default/remove/freeze/revoke — each takes exactly one
+    # `<id>` positional arg and reports the (now-updated) entry, or fails
+    # cleanly for an id that isn't enrolled.
+    def self.run_payment_mutate(argv, method_name)
+      id = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
+      unless id
+        warn USAGE
+        return 1
+      end
+
+      entry = PaymentMethods.new.public_send(method_name, id)
+      puts "#{entry['label']} (#{entry['id']}) — default: #{entry['default']}, frozen: #{entry['frozen']}"
+      0
+    rescue PaymentMethods::UnknownMethodError
+      warn "No payment method enrolled with id #{id}."
+      1
+    end
+    private_class_method :run_payment_mutate
+
+    def self.parse_payment_enroll_options(argv)
+      opts = { scope_merchants: [] }
+      OptionParser.new do |parser|
+        parser.on("--label NAME") { |v| opts[:label] = v }
+        parser.on("--json") { opts[:json] = true }
+        parser.on("--scope-merchant HOST") { |v| opts[:scope_merchants] << v }
+        parser.on("--scope-max-amount N", Integer) { |v| opts[:scope_max_amount] = v }
+        parser.on("--scope-currency CUR") { |v| opts[:scope_currency] = v }
+      end.parse!(argv)
+      opts[:url] = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
+      opts
+    end
+    private_class_method :parse_payment_enroll_options
+
+    # nil (not `{}`) when no --scope-* flag was given at all, so
+    # PaymentMethods#enroll's `scope:` default of no-scope-written stays the
+    # behavior for a plain `portage payment enroll` — Phase 2's per-token
+    # scope is opt-in.
+    def self.payment_enroll_scope(opts)
+      return nil if opts[:scope_merchants].empty? && !opts[:scope_max_amount]
+
+      { merchants: opts[:scope_merchants], max_amount: opts[:scope_max_amount], currency: opts[:scope_currency] }
+        .compact
+    end
+    private_class_method :payment_enroll_scope
+
+    def self.run_payment_enroll(argv)
+      opts = parse_payment_enroll_options(argv)
+      unless opts[:url]
+        warn USAGE
+        return 1
+      end
+
+      result = PaymentMethods.new.enroll(opts[:url], label: opts[:label],
+                                                     scope: payment_enroll_scope(opts)) do |setup_url|
+        puts "Visit this link to add a card, then wait — polling for completion:\n  #{setup_url}"
+      end
+      puts opts[:json] ? JSON.pretty_generate(result) : format_payment_enroll(result)
+      result[:status] == "complete" ? 0 : 1
+    rescue PaymentMethods::NotSupportedError => e
+      warn e.message
+      1
+    end
+    private_class_method :run_payment_enroll
+
+    # --- policy ---
+
+    def self.run_policy(argv)
+      sub = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
+      case sub
+      when "show" then run_policy_show(argv)
+      when "set" then run_policy_set(argv)
+      else
+        warn USAGE
+        1
+      end
+    end
+    private_class_method :run_policy
+
+    def self.run_policy_show(argv)
+      json = false
+      OptionParser.new { |parser| parser.on("--json") { json = true } }.parse!(argv)
+      policy = Portage::Ucp::Policy.load.to_h
+      puts json ? JSON.pretty_generate(policy) : format_policy(policy)
+      0
+    end
+    private_class_method :run_policy_show
+
+    def self.format_policy(policy)
+      return "(no policy configured — every check passes)" if policy.empty?
+
+      JSON.pretty_generate(policy)
+    end
+    private_class_method :format_policy
+
+    def self.parse_policy_set_options(argv)
+      opts = { allow: [] }
+      OptionParser.new do |parser|
+        parser.on("--per-transaction-cap N", Integer) { |v| opts[:per_transaction_cap] = v }
+        parser.on("--rolling-cap N", Integer) { |v| opts[:rolling_cap] = v }
+        parser.on("--rolling-window-seconds N", Integer) { |v| opts[:rolling_window_seconds] = v }
+        parser.on("--currency CUR") { |v| opts[:currency] = v }
+        parser.on("--velocity-count N", Integer) { |v| opts[:velocity_count] = v }
+        parser.on("--velocity-window-seconds N", Integer) { |v| opts[:velocity_window_seconds] = v }
+        parser.on("--allow HOST") { |v| opts[:allow] << v }
+        parser.on("--clear-allowlist") { opts[:clear_allowlist] = true }
+      end.parse!(argv)
+      opts
+    end
+    private_class_method :parse_policy_set_options
+
+    # Each `--*` group is applied independently and only when its required
+    # fields are present — `portage policy set --allow shop.example.com`
+    # touches only the allowlist, leaving caps/velocity untouched, so caps
+    # and the allowlist can be configured in separate invocations.
+    def self.run_policy_set(argv)
+      opts = parse_policy_set_options(argv)
+      policy = Portage::Ucp::Policy.load
+      set_policy_cap(policy, opts)
+      set_policy_velocity(policy, opts)
+      set_policy_allowlist(policy, opts)
+      puts format_policy(policy.to_h)
+      0
+    end
+    private_class_method :run_policy_set
+
+    def self.set_policy_cap(policy, opts)
+      if opts[:per_transaction_cap]
+        policy.set("per_transaction_cap",
+                   { "amount" => opts[:per_transaction_cap], "currency" => require_currency!(opts) })
+      end
+      return unless opts[:rolling_cap] && opts[:rolling_window_seconds]
+
+      policy.set("rolling_cap", { "amount" => opts[:rolling_cap], "currency" => require_currency!(opts),
+                                  "window_seconds" => opts[:rolling_window_seconds] })
+    end
+    private_class_method :set_policy_cap
+
+    def self.set_policy_velocity(policy, opts)
+      return unless opts[:velocity_count] && opts[:velocity_window_seconds]
+
+      policy.set("velocity", { "count" => opts[:velocity_count], "window_seconds" => opts[:velocity_window_seconds] })
+    end
+    private_class_method :set_policy_velocity
+
+    def self.set_policy_allowlist(policy, opts)
+      return policy.set("merchant_allowlist", []) if opts[:clear_allowlist]
+      return if opts[:allow].empty?
+
+      policy.set("merchant_allowlist", (policy.merchant_allowlist + opts[:allow]).uniq)
+    end
+    private_class_method :set_policy_allowlist
+
+    def self.require_currency!(opts)
+      opts[:currency] || raise(ArgumentError, "--currency is required alongside a cap")
+    end
+    private_class_method :require_currency!
+
+    def self.format_payment_list(methods)
+      return "(no payment methods enrolled)" if methods.empty?
+
+      methods.map { |m| "#{m['label']} (#{m['id']}) — default: #{m['default']}, frozen: #{m['frozen']}" }.join("\n")
+    end
+    private_class_method :format_payment_list
+
+    def self.format_payment_enroll(result)
+      case result[:status]
+      when "complete" then "Enrolled #{result[:label]} (#{result[:id]})."
+      when "pending"
+        "Timed out waiting for enrollment — finish it at #{result[:setup_url]}, then run " \
+        "`portage payment enroll` again."
+      else "This store doesn't support payment enrollment."
+      end
+    end
+    private_class_method :format_payment_enroll
+
     # --- output ---
 
     def self.format_report(report)
@@ -193,6 +546,20 @@ module Portage
     end
     private_class_method :offer_line
 
+    def self.format_compare(report)
+      lines = [report[:message].to_s]
+      report[:offers].each_with_index { |offer, index| lines << "  #{index + 1}. #{compare_offer_line(offer)}" }
+      lines.join("\n")
+    end
+    private_class_method :format_compare
+
+    def self.compare_offer_line(offer)
+      parts = ["[#{offer[:match]}] #{offer[:store]} — #{offer[:title]} (#{offer[:product_id]})", format_price(offer)]
+      parts << "browse only" unless offer[:checkout]
+      parts.join(" — ")
+    end
+    private_class_method :compare_offer_line
+
     def self.format_price(offer)
       return "price n/a" unless offer[:amount]
 

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portage-cli
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Tom Whitbread
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: portage-ucp
@@ -15,28 +16,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: portage-ucp-client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -103,6 +104,7 @@ description: 'Ships the `portage` executable. `portage buy <url>` tries native U
   ones answering /.well-known/ucp, and search their catalogs — documented APIs only,
   no SERP scraping. Depends on portage-ucp (for platform detection via Resolver) and
   portage-ucp-client (for the actual buy calls); no single adapter gem is a hard dependency.'
+email:
 executables:
 - portage
 extensions: []
@@ -114,7 +116,14 @@ files:
 - exe/portage
 - lib/portage/cli.rb
 - lib/portage/cli/buy.rb
+- lib/portage/cli/catalog_products.rb
+- lib/portage/cli/compare.rb
 - lib/portage/cli/find.rb
+- lib/portage/cli/history.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/shipping_profile.rb
@@ -126,6 +135,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
@@ -140,7 +150,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.18
+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: []