portage-cli 0.7.5 → 0.9.0

data/lib/portage/cli/agent_profile_url.rb

@@ -0,0 +1,30 @@
+module Portage
+  module Cli
+    # Where `find`/`buy`/`OfferSources::ShopifyCatalog` get
+    # `meta.ucp-agent.profile` when the caller hasn't set
+    # PORTAGE_AGENT_PROFILE.
+    #
+    # Real UCP servers fetch and verify that URL before answering any call
+    # (Transports::Http), and the CLI used to read it via a bare
+    # `ENV.fetch("PORTAGE_AGENT_PROFILE", nil)` with no fallback — a fresh
+    # install that never copied `.env.example` got a bare
+    # MissingAgentProfileError on its very first `find`/`buy`. The repo
+    # already publishes its own profile document
+    # (`portage-cli/agent-profile/agent-profile.json`) over jsdelivr, and
+    # that URL is confirmed live against catalog.shopify.com (see
+    # docs/agent-profile.md), so it's a reasonable "works enough to try it"
+    # default — not a substitute for a caller hosting their own via
+    # `portage generate agent-profile`.
+    module AgentProfileUrl
+      DEFAULT = "https://cdn.jsdelivr.net/gh/tomtom87/Portage@main/portage-cli/agent-profile/agent-profile.json"
+                .freeze
+
+      # @return [String] PORTAGE_AGENT_PROFILE, or DEFAULT when it's unset
+      #   or blank.
+      def self.resolve
+        value = ENV.fetch("PORTAGE_AGENT_PROFILE", nil).to_s.strip
+        value.empty? ? DEFAULT : value
+      end
+    end
+  end
+end

data/lib/portage/cli/approval_policy.rb

@@ -0,0 +1,56 @@
+require "portage/ucp"
+require_relative "human_prompt"
+
+module Portage
+  module Cli
+    # `portage policy set --require-approval person|any|off`
+    # (docs/plans/human-pick-and-approve.md Phase 2, Design § 5): how much
+    # approval a real `portage buy --yes` needs before it may charge or hand
+    # off.
+    #
+    # - `off`: `--yes` alone buys (the behaviour before this setting).
+    # - `any` (the default): `--yes` needs `--quote` with an approved quote,
+    #   approved by the person at a tty or relayed by an agent.
+    # - `person`: only a quote the person approved at the tty counts — a
+    #   model with a shell can't type on `/dev/tty`.
+    #
+    # Stored as `require_approval` in ~/.portage/policy.json (Portage::Ucp::
+    # Policy), next to the caps and allowlist it sits beside in `portage
+    # policy`. Policy#set takes any key and its file format is documented as
+    # private, and PolicyGuard reads only the keys it knows, so this needs
+    # no change to the portage-ucp gem. Deliberately no env var or
+    # config.json override: either would let an agent lower it without the
+    # tty confirmation `policy set` asks for. The gate itself is CLI-only
+    # (Cli.approval_gate); Buy's library callers aren't governed by it.
+    module ApprovalPolicy
+      KEY = "require_approval".freeze
+      LEVELS = %w[off any person].freeze
+      DEFAULT = "any".freeze
+
+      module_function
+
+      # An unrecognised stored value (a hand-edited file) fails closed, to
+      # the strictest level.
+      # @return [String] one of LEVELS.
+      def level(policy = Portage::Ucp::Policy.load)
+        stored = policy.to_h[KEY]
+        return DEFAULT if stored.nil?
+
+        LEVELS.include?(stored) ? stored : "person"
+      end
+
+      def configured?(policy) = policy.to_h.key?(KEY)
+
+      def lowering?(from, to) = LEVELS.index(to) < LEVELS.index(from)
+
+      # @param quote [Hash, nil] a saved quote (Quotes).
+      def satisfied?(quote, level)
+        case level
+        when "off" then true
+        when "any" then [HumanPrompt::BY_PERSON, HumanPrompt::BY_AGENT].include?(quote&.dig("approved_by"))
+        else quote&.dig("approved_by") == HumanPrompt::BY_PERSON
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/approve.rb

@@ -0,0 +1,135 @@
+require_relative "history"
+require_relative "quotes"
+require_relative "human_prompt"
+require_relative "product_page"
+require_relative "money"
+require_relative "approval_policy"
+
+module Portage
+  module Cli
+    # `portage approve QUOTE_ID` — loop step 5, the person says yes to the
+    # exact dry-run total (docs/plans/human-pick-and-approve.md Phase 2,
+    # Design § 5). Shows title, store, qty and total and asks yes/no.
+    #
+    # A yes typed on the `tty` surface marks the quote `approved_by:
+    # "person"`; `--relayed-yes` marks it `"agent_relayed"`. The `agent`
+    # surface asks nobody and returns `needs_approval` with the summary.
+    # `--view` only opens the product page. Whether an approval is enough
+    # for `buy --quote QUOTE_ID --yes` is ApprovalPolicy's call, at buy time
+    # — except under `person`, where a relayed yes could never be enough, so
+    # it isn't recorded and the agent is told to hand the question to the
+    # person's own terminal instead.
+    #
+    # Returns a report hash; Cli.run_approve prints it.
+    class Approve
+      def initialize(quote_id:, prompt:, relayed_yes: false, view: false, quotes: Quotes.new, history: History.new,
+                     level: ApprovalPolicy.level)
+        @quote_id = quote_id
+        @prompt = prompt
+        @relayed_yes = relayed_yes
+        @view = view
+        @quotes = quotes
+        @history = history
+        @level = level
+      end
+
+      def call
+        quote = @quotes.find(@quote_id)
+        return unusable(quote) if quote.nil? || quote["used_at"]
+
+        summary = self.class.summary(quote, history: @history)
+        return view(summary) if @view
+        return relay(summary) if @relayed_yes
+        return self.class.needs_approval(summary, level: @level) unless @prompt.tty?
+
+        ask(summary)
+      rescue HumanPrompt::NoTerminal => e
+        { outcome: "no_terminal", quote_id: @quote_id, message: e.message }
+      end
+
+      # What the person is asked to approve. Title and url were saved on
+      # the quote at dry-run time; a quote saved without them falls back to
+      # its offer's (via `offer_ref`, History#offer).
+      def self.summary(quote, history: History.new)
+        offer = fallback_offer(quote, history)
+        { quote_id: quote["quote_id"], title: quote["title"] || offer&.dig("title"), store: quote["store"],
+          product_id: quote["product_id"], qty: quote["qty"], total: quote["total"], currency: quote["currency"],
+          total_display: quote["total"] ? Money.format_amount(quote["total"], quote["currency"]) : "unknown",
+          url: quote["url"] || offer&.dig("url"), approved_by: quote["approved_by"] }
+      end
+
+      def self.fallback_offer(quote, history)
+        return nil unless quote["offer_ref"] && (quote["title"].nil? || quote["url"].nil?)
+
+        history.offer(quote["offer_ref"])
+      end
+      private_class_method :fallback_offer
+
+      # Also what a refused `buy --yes` returns (Cli.approval_gate).
+      def self.needs_approval(summary, message: nil, level: ApprovalPolicy::DEFAULT)
+        { outcome: "needs_approval", quote_id: summary[:quote_id], summary: summary,
+          message: message || relay_message(summary, level) }
+      end
+
+      def self.relay_message(summary, level)
+        id = summary[:quote_id]
+        ask = if level == "person"
+                "Ask the person to run `portage approve #{id}` in their own terminal (require_approval: person " \
+                  "doesn't accept a relayed yes)"
+              else
+                "Ask the person to approve #{describe(summary)} (show the url as a link), then relay a yes: " \
+                  "`portage approve #{id} --relayed-yes`"
+              end
+        "#{ask}, then `portage buy --quote #{id} --yes`."
+      end
+      private_class_method :relay_message
+
+      def self.describe(summary)
+        "#{summary[:qty]} × #{summary[:title] || summary[:product_id]} from #{summary[:store]} " \
+          "for #{summary[:total_display]}"
+      end
+
+      private
+
+      def ask(summary)
+        @prompt.say("#{summary[:title] || summary[:product_id]} — #{summary[:store]}")
+        @prompt.say("  qty #{summary[:qty]}, total #{summary[:total_display]}#{" — #{summary[:url]}" if summary[:url]}")
+        yes = @prompt.confirm("Buy #{self.class.describe(summary)}?", view: -> { page(summary)[:message] })
+        return approve(summary, HumanPrompt::BY_PERSON) if yes
+
+        { outcome: "cancelled", quote_id: summary[:quote_id], message: "Not approved — nothing will be bought." }
+      end
+
+      def relay(summary)
+        return self.class.needs_approval(summary, level: @level) if @level == "person"
+
+        approve(summary, HumanPrompt::BY_AGENT)
+      end
+
+      def approve(summary, by)
+        quote = @quotes.approve(summary[:quote_id], by: by)
+        return { outcome: "error", quote_id: @quote_id, message: "Couldn't save the approval." } unless quote
+
+        { outcome: "approved", quote_id: summary[:quote_id], approved_by: quote["approved_by"],
+          summary: summary.merge(approved_by: quote["approved_by"]),
+          message: "Approved #{self.class.describe(summary)} — next: " \
+                   "`portage buy --quote #{summary[:quote_id]} --yes`." }
+      end
+
+      def view(summary) = page(summary).merge(quote_id: summary[:quote_id])
+
+      def page(summary) = ProductPage.new(url: summary[:url], store: summary[:store]).open
+
+      # Same outcomes `buy --quote` reports for the same two cases.
+      def unusable(quote)
+        if quote
+          { outcome: "quote_used", quote_id: @quote_id,
+            message: "Quote #{@quote_id} has already been used — dry-run again for a new one." }
+        else
+          { outcome: "quote_not_found", quote_id: @quote_id,
+            message: "No saved quote #{@quote_id} — run `portage buy ... --dry-run --json` for a new one." }
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_import/categorize.rb

@@ -0,0 +1,59 @@
+require_relative "../classifier"
+require_relative "../index/builder"
+
+module Portage
+  module Cli
+    module BrowserImport
+      # "Smarter import" (docs/plans/buy-skill-and-local-browser.md Phase
+      # 3): a kept domain's categories come from what the user actually
+      # looked at there — each row's page title, bookmark folder name and
+      # URL slug (`/products/<slug>`, `/collections/<slug>`, `/c/<slug>`,
+      # `/category/<slug>`, split on `-`/`_`), run through the same
+      # Classifier every other index source uses, and weighted by visit
+      # count. A domain none of whose rows matches a category stays
+      # uncategorised: SearchBackends::Index then routes it by name only,
+      # never for a generic query.
+      module Categorize
+        TOP_CATEGORIES = Index::Builder::TOP_CATEGORIES
+
+        # A product page, for `--include-product-pages`: `/product/<x>` or
+        # `/products/<x>` (Shopify, WooCommerce and most others).
+        PRODUCT_PATH = %r{/products?/[^/?#]+}
+
+        # @param rows [Array<Hash>] Readers rows, all for one domain.
+        # @return [Hash{String => Integer}] category id => weight, top 5.
+        def self.domain(rows)
+          texts = Hash.new(0)
+          rows.each { |row| texts[text_of(row)] += row[:visits] }
+          tally = Hash.new(0)
+          texts.each do |text, visits|
+            Classifier.categories_for(text).each { |id| tally[id] += visits } unless text.empty?
+          end
+          tally.sort_by { |_id, weight| -weight }.first(TOP_CATEGORIES).to_h
+        end
+
+        # @param kept [Array<Hash>] Importer's kept entries, rows included.
+        # @return [Array<Hash>] one product entry per distinct product-page
+        #   title — key, title, url, origin, source ("history"/"bookmark"),
+        #   category.
+        def self.products(kept)
+          kept.flat_map { |entry| products_of(entry) }.uniq { |p| p[:key] }
+        end
+
+        def self.products_of(entry)
+          entry[:rows].select { |r| r[:url].match?(PRODUCT_PATH) && !r[:title].empty? }.map do |row|
+            { key: "title:#{row[:title].downcase.gsub(/[^a-z0-9]+/, '-')}", title: row[:title], url: row[:url],
+              origin: entry[:origin], source: row[:kind], category: Classifier.categories_for(text_of(row)).first }
+          end
+        end
+        private_class_method :products_of
+
+        def self.text_of(row)
+          slugs = Classifier::SLUG_PATTERNS.filter_map { |pattern| pattern.match(row[:url])&.[](1) }
+          [row[:title], row[:folder], *slugs.map { |s| s.tr("-_", "  ") }].reject(&:empty?).join(" ")
+        end
+        private_class_method :text_of
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_import/confirm.rb

@@ -0,0 +1,35 @@
+module Portage
+  module Cli
+    module BrowserImport
+      # The "shows the list and asks before writing" gate (docs/plans/
+      # buy-skill-and-local-browser.md Phase 3), shaped like
+      # WebmcpMappingConfirm: an explicit `--yes` is the only way to save
+      # without a prompt; a prompt needs a real TTY and no `--json`; and
+      # anything else — piped, CI, an agent running `--json` — saves
+      # nothing and says how to confirm. A dry run never saves, `--yes` or
+      # not.
+      class Confirm
+        # @param interactive [Boolean] false under --json or with no TTY on
+        #   stdin (the caller decides).
+        def initialize(interactive:, input: $stdin, output: $stdout)
+          @interactive = interactive
+          @input = input
+          @output = output
+        end
+
+        # @return [Symbol] :save, :declined, :dry_run, :nothing, or
+        #   :needs_confirmation (no TTY/--json and no --yes).
+        def call(plan, yes:, dry_run:)
+          return :dry_run if dry_run
+          return :nothing if Array(plan[:kept]).empty?
+          return :save if yes
+          return :needs_confirmation unless @interactive
+
+          @output.print "Save these #{plan[:kept].length} store(s) to your local index? [y/N] "
+          @output.flush
+          @input.gets.to_s.strip.downcase == "y" ? :save : :declined
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_import/domains.rb

@@ -0,0 +1,47 @@
+require "uri"
+
+module Portage
+  module Cli
+    module BrowserImport
+      # Reduces Readers rows to domains — the only thing about a row an
+      # import keeps past this point, besides the page title/folder/slug
+      # words Categorize reads locally. `www.` is folded into the bare
+      # domain, and anything that isn't an http(s) URL with a host
+      # (`chrome://`, `file:`, `about:`, `javascript:`) is dropped.
+      module Domains
+        # @return [Hash{String => Hash}] domain => { hosts: {host => visits},
+        #   rows: [...], visits: total }.
+        def self.group(rows)
+          groups = {}
+          rows.each do |row|
+            host = host_of(row[:url])
+            next unless host
+
+            group = (groups[host.delete_prefix("www.")] ||= { hosts: Hash.new(0), rows: [], visits: 0 })
+            group[:hosts][host] += row[:visits]
+            group[:rows] << row
+            group[:visits] += row[:visits]
+          end
+          groups
+        end
+
+        # The most-visited host variant (www. or not) as an https origin —
+        # UCP is https-only, so an http-only visit still probes https.
+        def self.origin_for(group) = "https://#{group[:hosts].max_by { |_h, visits| visits }.first}"
+
+        # An index entry's origin, reduced the same way, so it compares
+        # against a group's key.
+        def self.key_of(origin) = host_of(origin)&.delete_prefix("www.")
+
+        def self.host_of(url)
+          uri = URI.parse(url.to_s)
+          return nil unless %w[http https].include?(uri.scheme) && uri.host && !uri.host.empty?
+
+          uri.host.downcase
+        rescue URI::InvalidURIError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_import/filter.rb

@@ -0,0 +1,91 @@
+require "ipaddr"
+
+require_relative "../search_backends"
+
+module Portage
+  module Cli
+    module BrowserImport
+      # "Is this host obviously not a shop?" — decided locally, before a
+      # single probe is spent (docs/plans/buy-skill-and-local-browser.md
+      # Phase 3: "skipping obvious non-shops (NON_STORE_HOSTS, webmail,
+      # banks, intranet and localhost hosts)"). A skipped host never leaves
+      # the machine at all, so these lists err on the side of skipping:
+      # a missed shop costs one `portage index add`, a probed bank costs
+      # the user's trust.
+      module Filter
+        WEBMAIL_HOSTS = %w[
+          mail.google.com outlook.live.com outlook.office.com outlook.office365.com mail.yahoo.com
+          proton.me protonmail.com icloud.com fastmail.com mail.aol.com gmx.com zoho.com
+        ].freeze
+
+        # Banks and payment/finance hosts are never a UCP storefront, and
+        # are exactly the hosts a shopper least wants anything sent about.
+        # Not exhaustive — backed up by BANK_WORD for the long tail.
+        BANK_HOSTS = %w[
+          paypal.com wise.com revolut.com monzo.com starlingbank.com chase.com wellsfargo.com
+          citi.com capitalone.com americanexpress.com discover.com schwab.com fidelity.com vanguard.com
+          hsbc.com hsbc.co.uk barclays.co.uk natwest.com santander.co.uk nationwide.co.uk halifax.co.uk
+          coinbase.com kraken.com stripe.com klarna.com
+        ].freeze
+
+        BANK_WORD = /bank|creditunion/
+
+        # Tools, social and media sites a shopper visits all day that will
+        # never answer /.well-known/ucp — skipping them saves probes for
+        # the domains that might.
+        NON_SHOP_HOSTS = %w[
+          github.com gitlab.com bitbucket.org stackoverflow.com stackexchange.com linkedin.com slack.com
+          zoom.us notion.so atlassian.net figma.com claude.ai anthropic.com openai.com chatgpt.com
+          instagram.com tiktok.com netflix.com spotify.com twitch.tv discord.com whatsapp.com
+          medium.com substack.com apple.com microsoft.com live.com office.com gstatic.com
+          googleusercontent.com cloudflare.com amazonaws.com
+        ].freeze
+
+        LOCAL_SUFFIXES = %w[localhost local internal lan corp home.arpa test intranet].freeze
+
+        # @return [Symbol, nil] why `host` is skipped (:non_store, :webmail,
+        #   :bank, :local), or nil when it's worth a probe.
+        def self.skip_reason(host)
+          host = host.to_s.downcase
+          return :local if local?(host)
+          return :webmail if webmail?(host)
+          return :bank if bank?(host)
+          return :non_store if non_store?(host)
+
+          nil
+        end
+
+        def self.local?(host)
+          return true if host.empty? || !host.include?(".")
+          return true if ip?(host)
+
+          LOCAL_SUFFIXES.any? { |suffix| host == suffix || host.end_with?(".#{suffix}") }
+        end
+
+        def self.webmail?(host)
+          host.start_with?("mail.", "webmail.") || matches?(host, WEBMAIL_HOSTS)
+        end
+
+        def self.bank?(host)
+          matches?(host, BANK_HOSTS) || host.match?(BANK_WORD)
+        end
+
+        # SearchBackends::NON_STORE_HOSTS (search engines, Wikipedia,
+        # social) plus this module's own NON_SHOP_HOSTS.
+        def self.non_store?(host)
+          !SearchBackends.store_candidate?("https://#{host}/") || matches?(host, NON_SHOP_HOSTS)
+        end
+
+        def self.matches?(host, list) = list.any? { |bad| host == bad || host.end_with?(".#{bad}") }
+
+        def self.ip?(host)
+          IPAddr.new(host.delete_prefix("[").delete_suffix("]"))
+          true
+        rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+          false
+        end
+        private_class_method :local?, :webmail?, :bank?, :non_store?, :matches?, :ip?
+      end
+    end
+  end
+end