portage-cli 0.7.5 → 0.9.0

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

@@ -0,0 +1,60 @@
+require_relative "../../agent_profile_url"
+require_relative "../../dot_env"
+
+module Portage
+  module Cli
+    class SetupWizard
+      module Steps
+        # Step 3 (docs/plans/buy-skill-and-local-browser.md Phase 4): the
+        # agent profile every catalog/cart/checkout call carries
+        # (PORTAGE_AGENT_PROFILE). Phase 1 already defaults it to this
+        # repo's own published profile (AgentProfileUrl), so this step's
+        # job is explaining that default and, opt-in, generating and
+        # hosting your own — it never runs generation on its own.
+        #
+        # `portage generate agent-profile` itself is reused verbatim (via
+        # Cli.run_generate_agent_profile), not reimplemented, so its own
+        # output (where the files went, the "commit + purge the jsdelivr
+        # cache" next step) stays the one place that message lives.
+        class AgentProfile
+          def initialize(prompt:) = @prompt = prompt
+
+          def title = "Agent profile"
+          def default_yes? = true
+
+          def call
+            @prompt.say("Falls back to this repo's own published profile right now:\n  " \
+                        "#{AgentProfileUrl.resolve}\n" \
+                        "That's fine to keep using. Generating your own is only worth it once you're " \
+                        "hosting Portage for real, rather than trying it out.")
+            return unless @prompt.confirm("Generate your own agent profile now?", default: false)
+
+            generate
+            host
+          end
+
+          private
+
+          def generate
+            out = @prompt.ask("Where to write the public profile", hint: "default: agent-profile.json") ||
+                  "agent-profile.json"
+            key_out = @prompt.ask("Where to write the private signing key", hint: "default: agent-profile.key.pem") ||
+                      "agent-profile.key.pem"
+            Portage::Cli.send(:run_generate_agent_profile, ["--out", out, "--key-out", key_out])
+          end
+
+          def host
+            @prompt.say("Once it's hosted at a stable, public HTTPS URL (docs/agent-profile.md), point " \
+                        "PORTAGE_AGENT_PROFILE at it.")
+            url = @prompt.ask("URL you'll host it at", hint: "Enter to keep using the default for now")
+            return unless url
+
+            path = DotEnv.update!({ "PORTAGE_AGENT_PROFILE" => url })
+            @prompt.say("Saved PORTAGE_AGENT_PROFILE to #{path} (chmod 600) — won't take effect until " \
+                        "that URL actually serves the profile you just generated.")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module Portage
+  module Cli
+    class SetupWizard
+      module Steps
+        # Step 4 (docs/plans/buy-skill-and-local-browser.md Phase 4):
+        # `portage browser import` (Phase 3, Tier A). Opt-in and off by
+        # default here, same as the command itself — this step only asks
+        # which browser, then hands off to Cli.run_browser_import so the
+        # command's own read -> reduce -> probe -> show -> confirm flow
+        # (BrowserImport::Confirm) runs unchanged, prompt and all.
+        class BrowserImport
+          def initialize(prompt:) = @prompt = prompt
+
+          def title = "Browser import"
+          def default_yes? = false
+
+          def call
+            @prompt.say("Local-only: reduces your browser's bookmarks/history to shop domains, probes each " \
+                        "unknown one for /.well-known/ucp, and shows you the list before saving anything to " \
+                        "your local index. Never reads passwords, cookies or saved-card autofill.")
+            browser = @prompt.ask("Which browser", hint: "chrome/edge/brave/arc/firefox/safari — Enter to autodetect")
+            args = browser ? ["--browser", browser] : []
+            Portage::Cli.send(:run_browser_import, args)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+require_relative "../../config"
+require_relative "../../checkout_handoff"
+require_relative "../../handoff_target"
+require_relative "../../handoff_only"
+
+module Portage
+  module Cli
+    class SetupWizard
+      module Steps
+        # Step 7 (docs/plans/buy-skill-and-local-browser.md Phase 4 built
+        # the auto-open toggle; Phase 5 extends it): auto-open, the
+        # hand-off target, an approved named agent, and the hand-off-only
+        # host list — all through Config, the same "Enter keeps what's
+        # already set" contract every other step uses.
+        class Handoff
+          def initialize(prompt:) = @prompt = prompt
+
+          def title = "Hand-off"
+          def default_yes? = true
+
+          def call
+            @prompt.say("When a buy hands off — no payment token, an escalation, or a dead end — Portage " \
+                        "opens the checkout URL (or dispatches it to an approved agent). Amazon and any " \
+                        "other host on your hand-off-only list are never automated: Portage just opens the " \
+                        "page and you buy. #{HandoffOnly::LEGAL_NOTICE}")
+            toggle_auto_open
+            set_handoff_target
+            approve_agent
+            edit_handoff_only_hosts
+          end
+
+          private
+
+          def toggle_auto_open
+            current = CheckoutHandoff.new.auto_open?
+            answer = @prompt.confirm("Auto-open the checkout URL in your browser on hand-off?", default: current)
+            return @prompt.say("Left unchanged.") if answer == current
+
+            Config.load.set("auto_open_checkout", answer)
+            @prompt.say("Saved to ~/.portage/config.json.")
+          end
+
+          def set_handoff_target
+            current = HandoffTarget.new.label
+            answer = @prompt.ask("Hand-off target", hint: "default, print, profile, or agent:<name>; " \
+                                                          "currently #{current}; Enter to keep it")
+            return @prompt.say("Left unchanged.") if answer.nil?
+
+            HandoffTarget.new(override: answer) # validates before saving
+            Config.load.set("handoff_target", answer)
+            @prompt.say("Saved to ~/.portage/config.json.")
+          rescue ArgumentError => e
+            @prompt.say("#{e.message} Not saved.")
+          end
+
+          # Approving an `agent:<name>` target once here (or by editing
+          # config.json directly) is what #lookup requires before Buy will
+          # ever invoke it (see HandoffAgents) — nothing is approved just
+          # by naming it as the hand-off target above.
+          def approve_agent
+            name = @prompt.ask("Approve a named agent for agent:<name> hand-off", hint: "agent name, Enter to skip")
+            return unless name
+
+            command = @prompt.ask("Command to run it", hint: "space-separated argv, e.g. openclaw handoff; " \
+                                                             "Enter to use a webhook instead")
+            return approve_agent_webhook(name) unless command
+
+            save_agent(name, "command" => command.split)
+          end
+
+          def approve_agent_webhook(name)
+            webhook = @prompt.ask("Webhook URL", hint: "https://..., Enter to skip")
+            return @prompt.say("No command or webhook given — #{name.inspect} not saved.") unless webhook
+
+            save_agent(name, "webhook" => webhook)
+          end
+
+          def save_agent(name, entry)
+            config = Config.load
+            agents = config.get("handoff_agents") || {}
+            agents[name] = entry.merge("approved" => true)
+            config.set("handoff_agents", agents)
+            @prompt.say("Approved #{name.inspect} — use --handoff-target agent:#{name}.")
+          end
+
+          def edit_handoff_only_hosts
+            current = HandoffOnly.new.hosts
+            @prompt.say("Current hand-off-only hosts (#{current.length}): #{current.join(', ')}")
+            answer = @prompt.ask("Replace the list", hint: "comma-separated hosts, Enter to keep it as-is")
+            return @prompt.say("Left unchanged.") if answer.nil?
+
+            hosts = answer.split(",").map(&:strip).reject(&:empty?)
+            Config.load.set("handoff_only_hosts", hosts)
+            @prompt.say("Saved #{hosts.length} host(s) to ~/.portage/config.json.")
+          end
+        end
+      end
+    end
+  end
+end

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.9.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