portage-cli 0.7.5 → 0.8.0

data/lib/portage/cli/setup_wizard/steps/index_build.rb

@@ -0,0 +1,31 @@
+module Portage
+  module Cli
+    class SetupWizard
+      module Steps
+        # Step 5 (docs/plans/buy-skill-and-local-browser.md Phase 4):
+        # `portage index build` (Phases 2b-2c). Opt-in and off by default —
+        # it's a live network sweep of Shopify's global catalog, one query
+        # per taxonomy node, which is a lot to run unasked inside a wizard.
+        # Delegates to Cli.run_index_build so the command's own sources,
+        # probe cap and progress output are exactly what a direct
+        # `portage index build` would give.
+        class IndexBuild
+          def initialize(prompt:) = @prompt = prompt
+
+          def title = "Local store index"
+          def default_yes? = false
+
+          def call
+            @prompt.say("Builds ~/.portage/index/{stores,products}.json — stores and products `find` can " \
+                        "route by on top of stores.yml, the known-stores list this repo already fetches, " \
+                        "and web search. Takes a little while: one query per product-category node against " \
+                        "Shopify's catalog, verifying each new store with a single /.well-known/ucp probe.")
+            return unless @prompt.confirm("Run `portage index build` now?", default: false)
+
+            Portage::Cli.send(:run_index_build, [], refresh: false)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/setup_wizard/steps/policy.rb

@@ -0,0 +1,60 @@
+module Portage
+  module Cli
+    class SetupWizard
+      module Steps
+        # Step 6 (docs/plans/buy-skill-and-local-browser.md Phase 4):
+        # spending policy caps (Portage::Ucp::PolicyGuard), via `portage
+        # policy set` — reused, not reimplemented, so the actual cap/
+        # allowlist logic (Cli.set_policy_cap/set_policy_allowlist) has
+        # exactly one place it lives.
+        class Policy
+          def initialize(prompt:) = @prompt = prompt
+
+          def title = "Spending policy caps"
+          def default_yes? = true
+
+          def call
+            @prompt.say("Checked before every `portage buy --yes` checkout completes. Enter skips a " \
+                        "question you don't want to answer right now — nothing here is required.")
+            args = cap_args + allowlist_args
+            return @prompt.say("No policy changes made.") if args.empty?
+
+            Portage::Cli.send(:run_policy_set, args)
+          end
+
+          private
+
+          def cap_args
+            major = @prompt.ask("Per-transaction spending cap", hint: "major units, e.g. 200 for $200; Enter to skip")
+            return [] unless major
+
+            parsed = Float(major, exception: false)
+            return not_a_number unless parsed&.positive?
+
+            currency = @prompt.ask("Currency for that cap", hint: "e.g. USD")
+            return no_currency if currency.nil?
+
+            # Cli.to_minor_units is private — reused via `send` rather than
+            # a second implementation of major-to-minor-units conversion.
+            ["--per-transaction-cap", Portage::Cli.send(:to_minor_units, parsed).to_s, "--currency", currency]
+          end
+
+          def not_a_number
+            @prompt.say("Not a number — cap not set.")
+            []
+          end
+
+          def no_currency
+            @prompt.say("No currency given — cap not set.")
+            []
+          end
+
+          def allowlist_args
+            hosts = @prompt.ask("Merchant allowlist hosts to add", hint: "comma-separated, Enter to skip")
+            Array(hosts&.split(",")).map(&:strip).reject(&:empty?).flat_map { |host| ["--allow", host] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/setup_wizard/steps/retailer_keys.rb

@@ -0,0 +1,55 @@
+require_relative "../../dot_env"
+
+module Portage
+  module Cli
+    class SetupWizard
+      module Steps
+        # Phase 7 (docs/plans/buy-skill-and-local-browser.md): the five
+        # official retailer offer sources (OfferSources) are each opt-in —
+        # this step is where their keys get written, same as SearchKeys
+        # does for Brave/Google CSE. Every one of these still ends in
+        # hand-off (see HandoffOnly / OfferSources.retail_handoff_host?):
+        # setting a key here only makes `find` show more real offers, it
+        # never lets `portage buy` complete a purchase at any of these
+        # retailers.
+        class RetailerKeys
+          FIELDS = {
+            "WALMART_AFFILIATE_API_KEY" => "Walmart Affiliate API key",
+            "EBAY_BROWSE_ACCESS_TOKEN" => "eBay Browse API access token (Buy It Now search only)",
+            "BESTBUY_API_KEY" => "Best Buy Products API key",
+            "ETSY_LISTINGS_API_KEY" => "Etsy Open API v3 key (buyer-side listing search)",
+            "AMAZON_CREATORS_ACCESS_TOKEN" => "Amazon Creators API access token"
+          }.freeze
+
+          def initialize(prompt:) = @prompt = prompt
+
+          def title = "Retailer offer sources"
+          def default_yes? = false
+
+          def call
+            @prompt.say("Optional: official buyer-side APIs for Walmart, eBay (Buy It Now only), Best " \
+                        "Buy, Etsy and Amazon. Each needs its own key from that retailer's developer " \
+                        "program — skip any you don't have. None of these ever completes a purchase: " \
+                        "every offer they return still ends in hand-off, same as Amazon today. Neither " \
+                        "key is echoed back; Enter keeps whatever's already set.")
+            assignments = collect
+            return @prompt.say("Left retailer offer source keys unchanged.") if assignments.empty?
+
+            path = DotEnv.update!(assignments)
+            @prompt.say("Saved #{assignments.keys.join(', ')} to #{path} (chmod 600).")
+          end
+
+          private
+
+          def collect
+            FIELDS.each_with_object({}) do |(var, label), assignments|
+              hint = ENV.fetch(var, nil).to_s.empty? ? "not set" : "already set"
+              answer = @prompt.ask_secret(label, hint: hint)
+              assignments[var] = answer if answer
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/setup_wizard/steps/search_keys.rb

@@ -0,0 +1,54 @@
+require_relative "../../dot_env"
+
+module Portage
+  module Cli
+    class SetupWizard
+      module Steps
+        # Step 2 (docs/plans/buy-skill-and-local-browser.md Phase 4): Brave
+        # and Google CSE search keys, written to ~/.portage/.env. See
+        # Doctor#search_backend_finding — with neither set, `find`/`buy`
+        # with no URL only ever resolves DuckDuckGo's Instant Answer API,
+        # which is keyless but only ever matches a specific brand/product
+        # name, not an open-ended query ("coffee", "hiking boots").
+        class SearchKeys
+          FIELDS = {
+            "BRAVE_SEARCH_API_KEY" => "Brave Search API key",
+            "GOOGLE_CSE_KEY" => "Google Programmable Search API key",
+            "GOOGLE_CSE_CX" => "Google Programmable Search engine id (cx)"
+          }.freeze
+
+          # Google's `cx` names which engine to query, not a credential —
+          # only the two API keys are secrets that never echo back.
+          SECRET = %w[BRAVE_SEARCH_API_KEY GOOGLE_CSE_KEY].freeze
+
+          def initialize(prompt:) = @prompt = prompt
+
+          def title = "Search API keys"
+          def default_yes? = true
+
+          def call
+            @prompt.say("DuckDuckGo's free API is already active and needs no key, but only resolves a " \
+                        "specific brand/product name — set either Brave's key, or both Google fields, for " \
+                        "real open-ended search. Neither key is echoed back; Enter keeps whatever's " \
+                        "already set.")
+            assignments = collect
+            return @prompt.say("Left search API keys unchanged.") if assignments.empty?
+
+            path = DotEnv.update!(assignments)
+            @prompt.say("Saved #{assignments.keys.join(', ')} to #{path} (chmod 600).")
+          end
+
+          private
+
+          def collect
+            FIELDS.each_with_object({}) do |(var, label), assignments|
+              hint = ENV.fetch(var, nil).to_s.empty? ? "not set" : "already set"
+              answer = SECRET.include?(var) ? @prompt.ask_secret(label, hint: hint) : @prompt.ask(label, hint: hint)
+              assignments[var] = answer if answer
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/setup_wizard/steps/shipping.rb

@@ -0,0 +1,51 @@
+require_relative "../../shipping_profile"
+require_relative "../../dot_env"
+
+module Portage
+  module Cli
+    class SetupWizard
+      module Steps
+        # Step 1 (docs/plans/buy-skill-and-local-browser.md Phase 4):
+        # PORTAGE_SHIP_*, written to ~/.portage/.env. Without at least the
+        # required fields, `portage buy` sends no shipping destination to
+        # your own store's checkout, and without the country a native UCP
+        # store prices in no market and can report in-stock items as out of
+        # stock (see Doctor#shipping_finding, which this step exists to
+        # resolve).
+        class Shipping
+          LABELS = {
+            street_address: "Street address", extended_address: "Apt/suite (optional)",
+            address_locality: "City", address_region: "State/region (optional)",
+            address_country: "Country (ISO 3166-1 alpha-2, e.g. US, GB)", postal_code: "Postal code",
+            first_name: "First name (optional)", last_name: "Last name (optional)",
+            phone_number: "Phone (optional)"
+          }.freeze
+
+          def initialize(prompt:) = @prompt = prompt
+
+          def title = "Shipping address"
+          def default_yes? = true
+
+          def call
+            @prompt.say("Enter keeps whatever's already set for a field.")
+            assignments = collect
+            return @prompt.say("Left shipping address unchanged.") if assignments.empty?
+
+            path = DotEnv.update!(assignments)
+            @prompt.say("Saved #{assignments.keys.join(', ')} to #{path} (chmod 600).")
+          end
+
+          private
+
+          def collect
+            ShippingProfile::ENV_VARS.each_with_object({}) do |(key, var), assignments|
+              hint = ENV.fetch(var, nil).to_s.empty? ? "not set" : "already set"
+              answer = @prompt.ask(LABELS.fetch(key), hint: hint)
+              assignments[var] = answer if answer
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/setup_wizard.rb

@@ -0,0 +1,74 @@
+require_relative "setup_wizard/prompt"
+require_relative "setup_wizard/steps/shipping"
+require_relative "setup_wizard/steps/search_keys"
+require_relative "setup_wizard/steps/retailer_keys"
+require_relative "setup_wizard/steps/agent_profile"
+require_relative "setup_wizard/steps/browser_import"
+require_relative "setup_wizard/steps/index_build"
+require_relative "setup_wizard/steps/policy"
+require_relative "setup_wizard/steps/handoff"
+
+module Portage
+  module Cli
+    # `portage setup`'s interactive wizard (docs/plans/
+    # buy-skill-and-local-browser.md Phase 4) — Cli.run_doctor/run_setup
+    # decide *whether* to run this (a real TTY, no --json, and either the
+    # command was `setup` outright or `doctor`/`configure` found nothing
+    # configured at all; see Doctor#nothing_configured?); this class is
+    # just the steps themselves, once that decision is already made
+    # (Phase 4 shipped seven; Phase 7 added RetailerKeys as an eighth, opt
+    # -in step between search keys and the agent profile).
+    #
+    # Every step: says what it's for, offers to skip (Enter keeps its own
+    # default — "on" for the foundational steps, "off" for the ones that
+    # are opt-in: browser import and index build's network/filesystem
+    # sweeps, and RetailerKeys' per-retailer credentials), and re-runs
+    # cleanly — Enter on any individual question inside a step
+    # always keeps whatever's already set, never clears it. No step raises
+    # its own error class: each one leans on the command it delegates to
+    # (`portage generate agent-profile`, `portage browser import`, `portage
+    # index build`, `portage policy set`) for its own validation and error
+    # reporting, so this class has nothing UCP- or network-specific to
+    # rescue.
+    class SetupWizard
+      INTRO = <<~TEXT.freeze
+        Portage setup
+
+        Walks through shipping, search, your agent profile, browser import,
+        the local store index, spending caps and hand-off. Every step can
+        be skipped, and this re-runs cleanly at any time — nothing you
+        already have set is cleared just by pressing Enter.
+      TEXT
+
+      STEPS = [Steps::Shipping, Steps::SearchKeys, Steps::RetailerKeys, Steps::AgentProfile, Steps::BrowserImport,
+               Steps::IndexBuild, Steps::Policy, Steps::Handoff].freeze
+
+      def initialize(input: $stdin, output: $stdout)
+        @prompt = Prompt.new(input: input, output: output)
+      end
+
+      # @return [Integer] always 0 — nothing about walking through (or
+      #   skipping) setup steps is a failure exit code; a step that hits a
+      #   real problem (a bad flag reaching `portage policy set`, a browser
+      #   import permission error) reports it itself, same as running that
+      #   command directly would.
+      def call
+        @prompt.say(INTRO)
+        STEPS.each { |step_class| run_step(step_class) }
+        @prompt.say("\nDone — run `portage doctor` any time to see the current state, or `portage setup` " \
+                    "again to change anything above.")
+        0
+      end
+
+      private
+
+      def run_step(step_class)
+        step = step_class.new(prompt: @prompt)
+        @prompt.say("\n== #{step.title} ==")
+        return @prompt.say("Skipped.") unless @prompt.confirm("Configure this now?", default: step.default_yes?)
+
+        step.call
+      end
+    end
+  end
+end

data/lib/portage/cli/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Cli
-    VERSION = "0.7.5".freeze
+    VERSION = "0.8.0".freeze
   end
 end

data/lib/portage/cli/webmcp.rb

@@ -8,18 +8,25 @@ module Portage
     # caller who actually passes `Buy.new(webmcp_bridge:)` ever needs it
     # installed.
     module Webmcp
-      # @return [Boolean] whether portage-ucp-webmcp could be loaded.
-      #   Memoized: `require` runs once per process.
+      # WebMcp::Autofill, Presets, Matcher and Fingerprint, which the CLI
+      # calls, first shipped in portage-ucp-webmcp 0.2.0. An older install
+      # counts as not installed rather than failing with a NameError later.
+      MIN_VERSION = "0.2.0".freeze
+
+      # @return [Boolean] whether a new-enough portage-ucp-webmcp could be
+      #   loaded. Memoized: `require` runs once per process.
       def self.available?
         return @available unless @available.nil?
 
         @available = begin
           require "portage/ucp/webmcp"
-          true
+          supported?(Portage::Ucp::WebMcp::VERSION)
         rescue LoadError
           false
         end
       end
+
+      def self.supported?(version) = Gem::Version.new(version) >= Gem::Version.new(MIN_VERSION)
     end
   end
 end

data/lib/portage/cli/webmcp_autofill_confirm.rb

@@ -0,0 +1,38 @@
+module Portage
+  module Cli
+    # docs/plans/webmcp-universal-outbound.md Phase 3, decision 2: even once
+    # `--autofill`/`PORTAGE_WEBMCP_AUTOFILL=approve` has opted a run in
+    # (WebmcpAutofillMode), nothing is typed into the store's checkout page
+    # until the shopper approves, in this prompt, exactly which fields and
+    # values are about to be entered — same shape as Phase 2's
+    # WebmcpMappingConfirm, applied to autofill instead of a tool mapping.
+    #
+    # Fields is always contact email + shipping address here — WebmcpFields
+    # never builds a payment one — but this class has no opinion on that;
+    # it only ever shows the shopper what it was given and asks.
+    class WebmcpAutofillConfirm
+      # @param interactive [Boolean] false under --json or with no TTY on
+      #   stdin — same posture as WebmcpMappingConfirm: no interactive
+      #   prompt possible means no autofill, not a guessed default.
+      def initialize(interactive:, input: $stdin, output: $stdout)
+        @interactive = interactive
+        @input = input
+        @output = output
+      end
+
+      # @param fields [Hash{String=>String}] autocomplete token => value.
+      # @return [Boolean] whether the shopper approved filling exactly these
+      #   fields. false for an empty `fields` too — nothing to confirm.
+      def call(fields)
+        return false if !@interactive || fields.empty?
+
+        @output.puts "Autofill is ready to enter this on the store's own checkout page — contact and " \
+                     "shipping only, never payment:"
+        fields.each { |token, value| @output.puts "  #{token}: #{value}" }
+        @output.print "Fill these fields now? [y/N] "
+        @output.flush
+        @input.gets.to_s.strip.downcase == "y"
+      end
+    end
+  end
+end

data/lib/portage/cli/webmcp_autofill_fields.rb

@@ -0,0 +1,60 @@
+require_relative "shipping_profile"
+
+module Portage
+  module Cli
+    # docs/plans/webmcp-universal-outbound.md Phase 3 — the shopper-approved
+    # data autofill is ever allowed to type into a store's checkout page:
+    # contact email and the PORTAGE_SHIP_* shipping address
+    # (Portage::Cli::ShippingProfile), each named by the WHATWG
+    # autocomplete token (https://html.spec.whatwg.org/#autofill) a standards
+    # -following checkout page's own field should carry, which is what
+    # Portage::Ucp::WebMcp::Autofill/assets/autofill.js match against.
+    #
+    # Deliberately the only place in this gem that reads PORTAGE_SHIP_EMAIL
+    # — a contact email is a WebMCP-autofill-only concern (native/adapter
+    # checkouts take it as part of `context`/the adapter's own contract, not
+    # a standalone shipping field), so it doesn't belong on ShippingProfile
+    # or BuyerContext, both of which are shared with paths that never touch
+    # a browser.
+    module WebmcpAutofillFields
+      EMAIL_ENV_VAR = "PORTAGE_SHIP_EMAIL".freeze
+
+      # ShippingProfile attribute => the autocomplete token
+      # assets/autofill.js looks for on the checkout page.
+      TOKENS = {
+        first_name: "shipping given-name",
+        last_name: "shipping family-name",
+        street_address: "shipping address-line1",
+        extended_address: "shipping address-line2",
+        address_locality: "shipping address-level2",
+        address_region: "shipping address-level1",
+        postal_code: "shipping postal-code",
+        address_country: "shipping country",
+        phone_number: "shipping tel"
+      }.freeze
+
+      module_function
+
+      # @param address [Portage::Ucp::PostalAddress, nil] nil (the default)
+      #   reads PORTAGE_SHIP_* fresh; injectable so a spec doesn't need real
+      #   env vars set.
+      # @return [Hash{String=>String}] autocomplete token => value. Empty
+      #   when neither an email nor a usable shipping address is
+      #   configured — #call in Buy treats that as nothing to autofill,
+      #   same as no PORTAGE_SHIP_* today.
+      def build(address: Portage::Cli::ShippingProfile.from_env)
+        fields = {}
+        email = ENV.fetch(EMAIL_ENV_VAR, nil)
+        fields["email"] = email unless email.to_s.strip.empty?
+
+        return fields unless address
+
+        TOKENS.each do |attribute, token|
+          value = address.public_send(attribute)
+          fields[token] = value unless value.to_s.strip.empty?
+        end
+        fields
+      end
+    end
+  end
+end

data/lib/portage/cli/webmcp_autofill_mode.rb

@@ -0,0 +1,39 @@
+require_relative "config"
+require_relative "setting"
+
+module Portage
+  module Cli
+    # docs/plans/webmcp-universal-outbound.md Phase 3 — the opt-in gate in
+    # front of filling the store's own checkout page. Off by default: only
+    # `--autofill` (a per-run CLI flag, forwarded to `Buy.new(autofill:)`)
+    # or `PORTAGE_WEBMCP_AUTOFILL=approve` / config.json's
+    # `"webmcp_autofill": "approve"` turn it on. Same Setting precedence
+    # everywhere else in this gem uses (WebmcpCheckoutMode, HandoffSpendMode)
+    # — override beats env beats config — except the override here is a
+    # boolean (the flag is either passed or it isn't), while the env/config
+    # level is a literal string, `"approve"`, not truthy-string parsing
+    # (Setting.flag?'s "1"/"true"/"yes"): a plan that could be
+    # `PORTAGE_WEBMCP_AUTOFILL=true` by accident from some other truthy
+    # convention shouldn't silently turn on typing into a checkout page.
+    #
+    # Turning this gate on is still only half of Phase 3's opt-in: even
+    # approved, nothing is typed until the shopper also approves the exact
+    # field/value pairs in WebmcpAutofillConfirm's own prompt.
+    module WebmcpAutofillMode
+      ENV_VAR = "PORTAGE_WEBMCP_AUTOFILL".freeze
+      CONFIG_KEY = "webmcp_autofill".freeze
+      APPROVE = "approve".freeze
+
+      module_function
+
+      # @param override [Boolean, nil] --autofill's value: true when the
+      #   flag was passed, nil otherwise (there's no --no-autofill; the flag
+      #   only ever turns this on, same as --dry-run/--yes elsewhere in Buy).
+      def approved?(override: nil, config: Config.load)
+        return true if override == true
+
+        Setting.resolve(env: ENV_VAR, config: config, config_key: CONFIG_KEY).to_s.strip.downcase == APPROVE
+      end
+    end
+  end
+end

data/lib/portage/cli/webmcp_mapping_confirm.rb

@@ -0,0 +1,68 @@
+module Portage
+  module Cli
+    # Turns a `Portage::Ucp::WebMcp::Matcher` proposal into `tool_names:`
+    # `Buy#webmcp_flow` can pass to `WebMcp.connect`, enforcing Phase 2's
+    # confirm-before-mutate rule (docs/plans/webmcp-universal-outbound.md):
+    # a read action (`search_catalog`, `get_product`, `get_cart`) is usable
+    # straight off the proposal — wrong at worst wastes a call. A mutating
+    # action (`create_cart`, `update_cart`, `create_checkout`) needs
+    # confirmation first, since a wrong guess there could add to, discard,
+    # or charge a stranger's cart.
+    #
+    # The prompt quotes a mutating tool's own `description` as what it is —
+    # page content, therefore untrusted — never as an instruction. Nothing
+    # here executes, follows, or acts on anything the description says; it
+    # is printed for the shopper to read and nothing more.
+    class WebmcpMappingConfirm
+      READ_ACTIONS = %w[search_catalog get_product get_cart].freeze
+
+      # @param interactive [Boolean] whether a prompt can actually be shown
+      #   and answered — false under --json or with no TTY on stdin (the
+      #   caller decides; this class has no opinion on how). false means a
+      #   proposal with any mutating action is always refused.
+      def initialize(interactive:, input: $stdin, output: $stdout)
+        @interactive = interactive
+        @input = input
+        @output = output
+      end
+
+      # @param proposal [Hash{String => Matcher::Proposal}]
+      # @param tools [Array<Hash>] the page's own tools, so the prompt can
+      #   quote a mutating tool's description.
+      # @return [Hash{String => String}, nil] a tool_names: hash covering
+      #   every proposed action, or nil when a mutating action was proposed
+      #   and couldn't be confirmed — no TTY, --json, or the shopper
+      #   declined. Never returns a partial mapping: either every mutating
+      #   action in the proposal is approved, or none of them are used.
+      def call(proposal, tools)
+        reads = proposal.slice(*READ_ACTIONS).transform_values(&:tool)
+        mutating = proposal.except(*READ_ACTIONS)
+        return reads if mutating.empty?
+        return nil unless confirmed?(mutating, tools)
+
+        reads.merge(mutating.transform_values(&:tool))
+      end
+
+      private
+
+      def confirmed?(mutating, tools) = @interactive && approve?(mutating, tools)
+
+      def approve?(mutating, tools)
+        @output.puts "This page's WebMCP tools weren't recognized as a known store platform. Based on their " \
+                     "names and schemas, here's the proposed mapping for cart/checkout actions — the " \
+                     "description text is quoted from the page itself, not a trusted instruction:"
+        mutating.each { |action, match| describe(action, match, tools) }
+        @output.print "Use this mapping? [y/N] "
+        @output.flush
+        @input.gets.to_s.strip.downcase == "y"
+      end
+
+      def describe(action, match, tools)
+        tool = tools.find { |t| (t["name"] || t[:name]).to_s == match.tool }
+        description = tool && (tool["description"] || tool[:description])
+        @output.puts "  #{action} -> #{match.tool} (confidence #{match.confidence}) — #{match.reason}"
+        @output.puts "    page description: #{description.inspect}" if description
+      end
+    end
+  end
+end

data/lib/portage/cli/webmcp_mappings.rb

@@ -0,0 +1,84 @@
+require "json"
+require "fileutils"
+require "time"
+
+module Portage
+  module Cli
+    # Confirmed Phase 2 `tool_names:` mappings — `~/.portage/webmcp_mappings.json`
+    # (docs/plans/webmcp-universal-outbound.md) — keyed by the page's tool
+    # fingerprint (`Portage::Ucp::WebMcp::Fingerprint.for`: sorted tool names
+    # plus a hash of each one's own input schema), never by origin
+    # (decision 3): once a shopper confirms a mapping for one store, any
+    # other store whose WebMCP tools have the exact same shape reuses it
+    # with no prompt at all — in effect a local preset. A lookalike page
+    # whose schemas differ even slightly gets a different fingerprint and
+    # has to be confirmed again, so it can't borrow a mapping with a
+    # different shape underneath the same tool names.
+    #
+    # Same "absent file or absent key means unset, a corrupt file raises
+    # rather than silently falling back" posture as Config — this is
+    # deliberately its own file, not a key under config.json, since it's
+    # confirmed data (grows with use) rather than a standing preference.
+    class WebmcpMappings
+      PATH = File.join(Dir.home, ".portage", "webmcp_mappings.json").freeze
+
+      def self.load(path: PATH) = new(path: path, data: read(path))
+
+      def initialize(path: PATH, data: {})
+        @path = path
+        @data = data
+      end
+
+      # @param tools [Array<Hash>] the page's tools, as list_tools returns
+      #   them.
+      # @return [Hash{String => String}, nil] the confirmed tool_names: for
+      #   this exact fingerprint, or nil when none has been confirmed yet.
+      def lookup(tools)
+        entry = @data[fingerprint_for(tools)]
+        entry && entry["tool_names"].transform_keys(&:to_s)
+      end
+
+      # @param tool_names [Hash] action => tool name, as just confirmed.
+      #   Merged onto whatever this fingerprint already had (so confirming a
+      #   new action later doesn't drop an earlier one), never replaced
+      #   outright.
+      # @param origin [String, nil] recorded as metadata only — the lookup
+      #   key is the fingerprint alone (decision 3), never the origin.
+      # @return [Hash{String => String}] the fingerprint's tool_names: after
+      #   merging.
+      def confirm!(tools, tool_names:, origin: nil)
+        key = fingerprint_for(tools)
+        entry = @data[key] || { "tool_names" => {}, "origins" => [] }
+        entry["tool_names"] = entry["tool_names"].merge(tool_names.transform_keys(&:to_s))
+        entry["origins"] = (entry["origins"] + [origin]).compact.uniq if origin
+        entry["confirmed_at"] = Time.now.utc.iso8601
+        @data[key] = entry
+        write
+        entry["tool_names"]
+      end
+
+      def to_h = @data.dup
+
+      def self.read(path)
+        return {} unless File.readable?(path)
+
+        raw = File.read(path)
+        return {} if raw.empty?
+
+        parsed = JSON.parse(raw)
+        parsed.is_a?(Hash) ? parsed : {}
+      end
+      private_class_method :read
+
+      private
+
+      def fingerprint_for(tools) = Portage::Ucp::WebMcp::Fingerprint.for(tools)
+
+      def write
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, JSON.pretty_generate(@data))
+        File.chmod(0o600, @path)
+      end
+    end
+  end
+end