portage-cli 0.7.3 → 0.7.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 996ddc0acd1ec2676257f402fbb03148e8a38c40af9d5cf4fbe50d176416a334
-  data.tar.gz: a451d4e8130b1891fb2630d9b5e9edc1efde9486afda2ca3ff863342943d4a09
+  metadata.gz: a682278ec8b34cb6e2cd649f345cb6779a7cec5d0bc22e6950721f7996a2d877
+  data.tar.gz: ed490b87284e6a8c9bd9ab280ea600d16877820240386d34e239309a8204b16d
 SHA512:
-  metadata.gz: dd25c1c868d3e70f6ef469975f0d2b24f478c1f96bf83a739d2e4a473c38d2695fbd3586e0243ac21f9d75562b080413ad173c18924024ff1135279cfe8622be
-  data.tar.gz: e8578d6935466578e44e9e4f2e2caae61e1b9a1b2b52051934989fd28ec8ea9a163d943e3f68aac3704bdae72557d600f4694c7c81b8e9fe00b16685640a10b6
+  metadata.gz: c22fd29667f7281c0173503cc9797158de1cd9d494cfcc98795bbce3ecfbaa03ed67ecb1321b3adf83000cf251168a62118db703bf1fb7b5417ba615a672b8c5
+  data.tar.gz: 42016dd1b716169b2dbaadef6f83a210ab8750584b23464e8c38c76aa39374988eeda97cfdc133c3edffaaf3c3ef8b34a76aa2fd57a9c96ad32292d529878df4

data/CHANGELOG.md

@@ -4,6 +4,62 @@ All notable changes to this project are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project is
 pre-1.0, so APIs may still shift between minor versions.
 
+## [0.7.5] - 2026-09-25
+
+- **`portage` loads `~/.portage/.env` on startup** (`Portage::Cli::DotEnv`),
+  so the shipping address, search keys and adapter credentials can live in
+  one file instead of a shell profile. `portage-console` does too. The
+  real environment always wins, empty values are skipped, and
+  `PORTAGE_ENV_FILE` names a different file. A `./.env` in the working
+  directory is never loaded automatically, so running `portage` inside a
+  cloned repo can't pick up that repo's proxy, webhook or credential
+  settings. Stdlib only, so the Homebrew formula gains no resource.
+  `portage doctor` reports the loaded file (`env_file`) and warns when
+  other users can read it.
+- **`portage doctor` runs the seller-side checks only for a seller.** The
+  authenticator, rate limiter, signing keys and payment handlers checks
+  inspect `Portage::Ucp.configuration`, which in a bare `portage` process
+  is always the unconfigured default. So every fresh install got four
+  warnings that meant nothing to a shopper and made doctor exit 1. They
+  now run only with `--require` or `--adapter`; otherwise one info line
+  says they were skipped. `Doctor.new` keeps running them by default
+  (`seller: true`) for library callers.
+
+## [0.7.4] - 2026-09-25
+
+- **`portage doctor` reports how it was installed, and warns when another
+  `portage` shadows it** (`docs/plans/homebrew-distribution.md` Phase 4).
+  New findings, all offline and without shelling out to `brew`:
+  - `install`: `homebrew` (with the Cellar keg) when this gem or its Ruby
+    lives under `HOMEBREW_PREFIX/Cellar/portage/` (`$HOMEBREW_PREFIX`,
+    then `/opt/homebrew`, `/usr/local`, `/home/linuxbrew/.linuxbrew`),
+    otherwise `gem` with the gem's own path;
+  - `runtime`: the Ruby version and `RbConfig.ruby` path, plus the
+    `portage-cli` version;
+  - `adapters`: each first-party adapter gem (plus `webmcp` and
+    `decision`), whether it loads and at which version. A gem install
+    without adapters is normal; a Homebrew install missing one is a
+    warning, since the formula bundles them all. A broken adapter is
+    reported, never raised;
+  - `path`: every `portage` on `PATH`, compared by resolved Cellar
+    location rather than raw path. Warns when a Homebrew install is
+    shadowed by an earlier `portage` (typically a `gem install` copy in a
+    mise/rbenv/asdf/rvm Ruby), naming the winner and how to fix it, and
+    when a gem install is shadowed by a Homebrew one.
+- `portage doctor` also warns when the `PORTAGE_SHIP_*` address is missing
+  or incomplete, naming the missing variables. Without
+  `PORTAGE_SHIP_COUNTRY` a native UCP store gets no buyer context, which
+  is how a live Shopify store ended up reporting in-stock items as out of
+  stock.
+- `doctor` findings now carry a `level` (`warning` or `info`) and, for the
+  new checks, structured `details`, both in `--json`. The JSON is still a
+  top-level array. Only warnings make doctor exit 1; the text output lists
+  info findings first, then the warnings or `No issues found.`.
+- `ShippingProfile` treats an empty `PORTAGE_SHIP_*` value as unset, the
+  way `BuyerContext` and the WooCommerce billing fallback already did, so
+  a `.env` copied from `.env.example` with blanks left in no longer
+  submits an address of empty strings.
+
 ## [0.7.3] - 2026-09-25
 
 - **Proxy support** (`docs/plans/proxy-support.md` Phases 2-3). Every

data/README.md

@@ -49,26 +49,81 @@ No single adapter gem is a hard dependency — install whichever
 
 ## Installation
 
+**Homebrew** (macOS and Linux) — recommended for using the CLI:
+
+```bash
+brew install tomtom87/portage/portage
+```
+
+The formula installs `portage-cli` plus every adapter gem (Shopify, Wix,
+WooCommerce, BigCommerce, Magento, Etsy, Instagram, WebMCP, Decision) into
+its own directory, running on Homebrew's own `ruby`, so it doesn't depend on
+or change whichever Ruby you use for anything else. It gives you `portage`
+and `portage-console`.
+
+**RubyGems** — on any Ruby ≥ 3.2, or when you only want some adapters:
+
+```bash
+gem install portage-cli
+gem install portage-ucp-shopify   # optional: add only the adapters you need
+```
+
+In an app's `Gemfile` instead:
+
 ```ruby
-# Gemfile
 gem "portage-cli"
 ```
 
+### Upgrading
+
+- Homebrew: `brew upgrade portage`. Your config and data in `~/.portage`
+  (policy, payment-method metadata, transaction log, order ledger,
+  `config.json`) are left alone, as they are by `brew uninstall`.
+- RubyGems: `gem update portage-cli` (and any adapter gems you added).
+
+Portage has no self-update command, by design: whichever tool installed it
+owns upgrades.
+
+### Linux: stored secrets need `secret-tool`
+
+On Linux, stored payment tokens (`portage payment enroll`) and proxy
+passwords (`password_ref`) live in the Secret Service (GNOME Keyring,
+KWallet) via the `secret-tool` command. It comes from your distribution,
+not from the formula or the gem:
+
 ```bash
-bundle install
+sudo apt install libsecret-tools   # Debian/Ubuntu
+sudo dnf install libsecret         # Fedora
 ```
 
-Or standalone:
+Without it (or without a live D-Bus session, e.g. over SSH or in CI),
+Portage uses the headless tier: the token comes from
+`PORTAGE_PAYMENT_TOKEN` and nothing is stored locally. On macOS the
+Keychain is used and nothing extra is needed.
+
+### Two copies on PATH
+
+A `gem install` copy and a Homebrew copy can both be installed, and your
+shell runs whichever `portage` comes first on `PATH`. A common case is an
+old gem copy in a mise, rbenv, asdf or rvm Ruby's `bin`, which then keeps
+running after `brew install` or `brew upgrade`. `portage doctor` warns
+about this. To check:
 
 ```bash
-gem install portage-cli
+which -a portage
 ```
 
+To fix it, keep one copy: `gem uninstall portage-cli` (with the Ruby that
+owns the gem copy active) to use Homebrew's, or `brew uninstall portage` to
+use the gem's. Or reorder `PATH` so the one you want comes first.
+
 ## Usage
 
+<!-- usage-start -->
 ```bash
 portage buy <url> --query "..." [--qty N] [--payment-token TOKEN] [--product-id ID]
-                                [--yes] [--dry-run] [--decision-backend jev|laya]
+                                [--yes] [--dry-run] [--auto-open|--no-auto-open]
+                                [--notify-webhook URL] [--decision-backend jev|laya]
                                 [--min-confidence N] [--json]
                                 [--wait [--wait-timeout DURATION|off]]
 portage buy --query "..." [--store URL] [--max-price N] [--limit N] ...
@@ -90,7 +145,12 @@ portage policy set [--per-transaction-cap N --currency CUR]
                     [--velocity-count N --velocity-window-seconds N]
                     [--allow HOST ...] [--clear-allowlist]
 portage orders reconcile [--checkout ID] [--json]
+portage doctor [--require FILE] [--adapter CLASS_NAME] [--json]   # aliases: configure, setup
+portage generate adapter NAME [--dir DIR]
+portage generate agent-profile [--out FILE] [--key-out FILE] [--rotate]
+portage --version
 ```
+<!-- usage-end -->
 
 `buy`/`find`/`compare`/`doctor`/`payment enroll` (the network-touching commands —
 `orders reconcile` doesn't take these) also accept:
@@ -342,6 +402,42 @@ plain-text `--wait` regardless of configuration), and `journal` (the order
 snapshot journal write, already unconditional — listing it just documents
 that).
 
+### Doctor
+
+```bash
+portage doctor          # aliases: portage configure, portage setup
+portage doctor --json
+```
+
+Checks this machine's setup without touching the network (apart from
+probing any proxy you've configured). It first reports how Portage is
+installed, then lists anything that needs fixing:
+
+- `install`: `homebrew` (with the Cellar path) or `gem` (with the gem's
+  path).
+- `runtime`: the Ruby version and path it runs on, and the `portage-cli`
+  version.
+- `adapters`: which first-party adapter gems load, and at which version.
+  Missing adapters are expected on a gem install; on Homebrew, which
+  bundles them all, a missing one is a warning.
+- `path`: which `portage` your shell actually runs. Warns when another copy
+  earlier on `PATH` shadows this one (see "Two copies on PATH" above).
+- `shipping`: warns when `PORTAGE_SHIP_*` is missing or incomplete (see
+  "Shipping address" below), naming the variables to set.
+- `env_file`: which env file was loaded (see "Environment file" below).
+  Warns when other users can read it.
+- The confidence gate's backend, the User-Agent, and proxy settings.
+- Seller-side checks against `Portage::Ucp.configuration` (authenticator,
+  rate limiter, signing keys, payment handlers). These only run when you
+  pass `--require` with your app's initializer (Rails:
+  `--require ./config/environment`) or `--adapter`. Without them doctor
+  would only ever see the unconfigured defaults, so it just notes that it
+  skipped them.
+
+With `--json` the output is an array of findings, each with `check`,
+`message`, `level` (`warning` or `info`) and, for the install checks,
+`details`. Doctor exits `1` when there's at least one warning, else `0`.
+
 ### Proxy
 
 `buy`, `find`, `compare`, `doctor`, and `payment enroll` accept the flags below,
@@ -511,30 +607,80 @@ gives up after 5 seconds and reports `notify_error` instead.
 `portage find`'s offer order comes from `Support::OfferRanking`: buyable
 first, then cheapest, then unpriced.
 
-### Shipping address (own-store checkouts only)
+### Environment file
+
+`portage` and `portage-console` load `~/.portage/.env` on startup, so your
+shipping address, search keys and adapter credentials can live in one file
+rather than your shell profile. `.env.example` at the repo root lists every
+variable. Rules:
+
+- Variables already set in your shell win over the file.
+- Empty values are skipped, so blanks copied from `.env.example` set nothing.
+- `KEY=value`, `export KEY=value`, `"double"` (with `\n` and `\"` escapes) and
+  `'single'` quotes all work; `#` starts a comment.
+- `PORTAGE_ENV_FILE=path` loads a different file instead, for example
+  `PORTAGE_ENV_FILE=.env` for a project checkout's own.
+
+Keep it private (`chmod 600 ~/.portage/.env`); `portage doctor` warns if
+other users can read it.
+
+#### Why `./.env` is never loaded automatically
+
+Many tools load a `.env` from whatever directory you run them in. Portage
+deliberately doesn't, because `portage` spends money and handles payment
+tokens, and the directory you happen to be in isn't something you chose
+to trust. If it did, running `portage` inside a cloned repo, a downloaded
+project or a shared folder would silently apply that directory's
+settings, for example:
+
+- `PORTAGE_PROXY` plus `PORTAGE_PROXY_CA`, routing your store traffic
+  through someone else's intercepting proxy, where they can read it;
+- a notify webhook that sends your checkout URLs and order details to
+  someone else;
+- store credentials or `PORTAGE_STORES`, pointing purchases at a different
+  store than you think.
+
+So only `~/.portage/.env`, a file you created in your own Portage
+directory, loads automatically. To use a project's `.env`, name it on
+purpose: `PORTAGE_ENV_FILE=.env portage ...`, after reading what's in it.
+
+### Shipping address
 
-When buying against your own store (`portage buy`'s step 2 adapter-credentials
-fallback, described at the top of this file) and that adapter supports
-`dev.ucp.shopping.fulfillment`, set a default shipping address via env
-rather than a flag, same posture as adapter credentials:
+Set your shipping address in `~/.portage/.env` (or your shell) rather than
+a flag, the same way as adapter credentials. `portage doctor` warns until
+the required ones are set:
 
 ```bash
-export PORTAGE_SHIP_STREET="1 Main St"
-export PORTAGE_SHIP_CITY="Erie"
-export PORTAGE_SHIP_REGION="PA"          # optional
-export PORTAGE_SHIP_COUNTRY="US"
-export PORTAGE_SHIP_POSTAL_CODE="16501"
-export PORTAGE_SHIP_FIRST_NAME="Ada"     # optional
-export PORTAGE_SHIP_LAST_NAME="Lovelace" # optional
-export PORTAGE_SHIP_PHONE="+1..."        # optional
+PORTAGE_SHIP_STREET="1 Main St"
+PORTAGE_SHIP_CITY="Erie"
+PORTAGE_SHIP_REGION="PA"          # optional
+PORTAGE_SHIP_COUNTRY="US"
+PORTAGE_SHIP_POSTAL_CODE="16501"
+PORTAGE_SHIP_FIRST_NAME="Ada"     # optional
+PORTAGE_SHIP_LAST_NAME="Lovelace" # optional
+PORTAGE_SHIP_PHONE="+1..."        # optional
 ```
 
-`street`/`city`/`country`/`postal_code` are required — a partial profile is
-treated as no profile at all. Once the merchant prices shipping options
-against that address, `portage buy` auto-picks the cheapest per fulfillment
-group; there's no interactive rate picker, since this drives one automated
-purchase. Native (non-adapter) UCP stores don't get this yet — see
-`portage-ucp`'s design log for why.
+`street`/`city`/`country`/`postal_code` are required — a partial profile
+(or one with empty values) is treated as no profile at all.
+
+The variables are used in two ways:
+
+- **Native UCP stores** (`buy` and `find` over HTTP) get
+  `PORTAGE_SHIP_COUNTRY`, `_REGION` and `_POSTAL_CODE` (plus
+  `PORTAGE_CURRENCY` and `PORTAGE_LANGUAGE`, if set) as UCP buyer context,
+  which a store uses to pick the market it prices and stocks in. These
+  work on their own, without the full address.
+  Without at least the country, a live Shopify store can report in-stock
+  items as out of stock.
+- **Your own store** (`portage buy`'s adapter-credentials fallback,
+  described at the top of this file), when its adapter supports
+  `dev.ucp.shopping.fulfillment`, also gets the full address as the
+  checkout's shipping destination. Once the merchant prices shipping
+  options against it, `portage buy` auto-picks the cheapest per fulfillment
+  group; there's no interactive rate picker, since this drives one
+  automated purchase. Native (non-adapter) UCP stores don't get the full
+  address yet — see `portage-ucp`'s design log for why.
 
 ## Buying without a URL
 

data/exe/portage

@@ -1,6 +1,11 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+# Before anything reads ENV: ~/.portage/.env (or PORTAGE_ENV_FILE), never
+# overriding the real environment. See Portage::Cli::DotEnv.
+require "portage/cli/dot_env"
+Portage::Cli::DotEnv.load
+
 require "portage/cli"
 
 exit(Portage::Cli.run(ARGV))

data/exe/portage-console

@@ -1,6 +1,9 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+require "portage/cli/dot_env"
+Portage::Cli::DotEnv.load
+
 require "irb"
 require "portage/cli/console"
 

data/lib/portage/cli/doctor.rb

@@ -3,6 +3,8 @@ require "uri"
 require_relative "confidence_check"
 require_relative "user_agent"
 require_relative "proxy_settings"
+require_relative "shipping_profile"
+require_relative "dot_env"
 
 module Portage
   module Cli
@@ -16,21 +18,39 @@ module Portage
     # process, so a host app passes `--require` to load its own initializer
     # first (Rails: `--require ./config/environment`).
     class Doctor
-      Finding = Struct.new(:check, :message, keyword_init: true)
+      # `level` is "warning" (something to fix; any one makes doctor exit 1)
+      # or "info" (a report, e.g. how portage was installed). `details` is
+      # structured data for `--json`; `to_h` drops it when there is none.
+      Finding = Struct.new(:check, :message, :level, :details, keyword_init: true) do
+        def initialize(level: "warning", **) = super
+        def warning? = level == "warning"
+        def to_h = super.compact
+      end
+
+      SELLER_CHECKS = "authenticator, rate limiter, signing keys, payment handlers".freeze
 
-      def initialize(adapter_class: nil, proxy_settings: ProxySettings.new)
+      # @param seller [Boolean] run the seller-side checks against
+      #   Portage::Ucp.configuration. `portage doctor` passes true only when
+      #   --require or --adapter loaded a seller's setup: in a bare shopper
+      #   process that configuration is always the unconfigured default, so
+      #   those four warnings were noise on every fresh install.
+      def initialize(adapter_class: nil, proxy_settings: ProxySettings.new, install_doctor: InstallDoctor.new,
+                     seller: true, dot_env_path: DotEnv.loaded_path)
         @adapter_class = adapter_class
         @proxy_settings = proxy_settings
+        @install_doctor = install_doctor
+        @seller = seller
+        @dot_env_path = dot_env_path
       end
 
       def call
         [
-          authenticator_finding,
-          rate_limiter_finding,
-          signing_keys_finding,
-          payment_handlers_finding,
+          *@install_doctor.findings,
+          dot_env_finding,
+          *seller_findings,
           decision_backend_finding,
           user_agent_finding,
+          shipping_finding,
           proxy_finding,
           *proxy_doctor_findings,
           *capability_findings
@@ -41,6 +61,31 @@ module Portage
 
       def config = Portage::Ucp.configuration
 
+      def seller_findings
+        return [authenticator_finding, rate_limiter_finding, signing_keys_finding, payment_handlers_finding] if @seller
+
+        [Finding.new(check: "seller", level: "info",
+                     message: "Seller checks (#{SELLER_CHECKS}) skipped — pass --require with your app's " \
+                              "initializer, or --adapter, to run them.")]
+      end
+
+      # Which env file DotEnv loaded, and a warning when it's readable by
+      # other users: it's where store credentials and payment tokens end up.
+      def dot_env_finding
+        return unless @dot_env_path
+
+        mode = File.stat(@dot_env_path).mode & 0o777
+        details = { path: @dot_env_path, mode: format("%o", mode) }
+        return Finding.new(check: "env_file", level: "info", message: "Loaded #{@dot_env_path}", details: details) \
+          if mode.nobits?(0o077)
+
+        Finding.new(check: "env_file", details: details,
+                    message: "#{@dot_env_path} is readable by other users (mode #{details[:mode]}) and may hold " \
+                             "credentials — run `chmod 600 #{@dot_env_path}`.")
+      rescue SystemCallError
+        nil
+      end
+
       def authenticator_finding
         return unless config.authenticator.is_a?(Portage::Ucp::UnconfiguredAuthenticator)
 
@@ -93,6 +138,36 @@ module Portage
                              "raise instead of sending.")
       end
 
+      # PORTAGE_SHIP_* (ShippingProfile, BuyerContext) has two jobs, and both
+      # fail quietly: with no complete address an own-store checkout goes
+      # out with no shipping destination, and with no PORTAGE_SHIP_COUNTRY a
+      # native UCP store gets no buyer context, so a live Shopify store
+      # builds a cart in no market and reports in-stock items as
+      # `merchandise_out_of_stock` (docs/ucp-tool-gating-investigation.md).
+      def shipping_finding
+        missing = ShippingProfile::REQUIRED.map { |key| ShippingProfile::ENV_VARS.fetch(key) }
+                                           .select { |var| ENV[var].to_s.empty? }
+        return if missing.empty?
+
+        Finding.new(check: "shipping", message: "#{shipping_gap(missing)} Set them in ~/.portage/.env " \
+                                                "(.env.example lists every variable) or your shell.")
+      end
+
+      def shipping_gap(missing)
+        country = ShippingProfile::ENV_VARS.fetch(:address_country)
+        gap = if missing.length == ShippingProfile::REQUIRED.length
+                "No shipping address set (#{missing.join(', ')})."
+              else
+                "Shipping address incomplete: missing #{missing.join(', ')}, and a partial address is " \
+                  "treated as none."
+              end
+        gap += " `portage buy` sends no shipping destination to your own store's checkout"
+        return "#{gap}." unless missing.include?(country)
+
+        "#{gap}, and without #{country} a native UCP store (e.g. Shopify) gets no market to price in " \
+          "and can report in-stock items as out of stock."
+      end
+
       # Phase 0 of docs/plans/proxy-support.md: every raw Net::HTTP.start call
       # site in portage-cli/portage-ucp/the adapter gems resolves its proxy
       # from Ruby stdlib's own `:ENV` default, which — confirmed against a
@@ -192,3 +267,4 @@ end
 # Doctor has to exist first (this file requires proxy_settings, not
 # proxy_doctor, at the top for exactly this reason).
 require_relative "proxy_doctor"
+require_relative "install_doctor"

data/lib/portage/cli/dot_env.rb

@@ -0,0 +1,62 @@
+module Portage
+  module Cli
+    # Loads `~/.portage/.env` (or the file PORTAGE_ENV_FILE names) into ENV
+    # before `portage`/`portage-console` run, so shipping address, search
+    # keys and adapter credentials can live in one file next to config.json
+    # instead of a shell profile. A Homebrew install has no repo checkout to
+    # keep a `.env` in, so the user's own Portage directory is the one place
+    # every install method shares.
+    #
+    # Deliberately *not* `./.env` from the working directory: `portage` run
+    # inside a cloned repo would then take that repo's PORTAGE_PROXY/
+    # PORTAGE_PROXY_CA (an intercepting proxy on store traffic), notify
+    # webhooks or store credentials without the user ever choosing them.
+    # PORTAGE_ENV_FILE=.env opts into a project file explicitly.
+    #
+    # Stdlib only (no dotenv gem, so the formula gains no resource). The real
+    # environment always wins, and an empty value is skipped, so a file
+    # copied from .env.example with blanks left in sets nothing.
+    module DotEnv
+      DEFAULT_PATH = File.join(Dir.home, ".portage", ".env").freeze
+      ESCAPES = { "n" => "\n", '"' => '"', "\\" => "\\" }.freeze
+      LINE = /\A\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\z/
+
+      class << self
+        # The file #load read in this process, for `portage doctor`.
+        attr_reader :loaded_path
+      end
+
+      # @return [String, nil] the path that was loaded, if any.
+      def self.load(path: ENV.fetch("PORTAGE_ENV_FILE", nil) || DEFAULT_PATH, env: ENV)
+        path = File.expand_path(path)
+        return unless File.file?(path) && File.readable?(path)
+
+        parse(File.read(path)).each { |key, value| env[key] = value unless env.key?(key) }
+        @loaded_path = path
+      end
+
+      # @return [Hash{String => String}] non-empty assignments, in file order.
+      def self.parse(text)
+        text.each_line.filter_map do |line|
+          match = LINE.match(line.chomp)
+          next unless match
+
+          value = unquote(match[2])
+          [match[1], value] unless value.empty?
+        end.to_h
+      end
+
+      # `"..."` (with \n, \" and \\ escapes) or `'...'` (literal); unquoted
+      # values drop a trailing ` # comment`.
+      def self.unquote(raw)
+        case raw
+        when /\A"((?:[^"\\]|\\.)*)"/
+          Regexp.last_match(1).gsub(/\\([n"\\])/) { ESCAPES.fetch(Regexp.last_match(1)) }
+        when /\A'([^']*)'/ then Regexp.last_match(1)
+        else raw.sub(/\s+#.*\z/, "").strip
+        end
+      end
+      private_class_method :unquote
+    end
+  end
+end

data/lib/portage/cli/install_doctor.rb

@@ -0,0 +1,239 @@
+require "rbconfig"
+require_relative "version"
+
+module Portage
+  module Cli
+    # Phase 4 of docs/plans/homebrew-distribution.md's `doctor` checks: how
+    # this copy of portage-cli was installed (Homebrew formula or plain
+    # `gem install`), which Ruby it runs on, which first-party adapter gems
+    # it can load, and whether the `portage` a shell would actually run is
+    # this one.
+    #
+    # That last check is the one that matters. The formula installs into its
+    # own Cellar keg, and a `gem install portage-cli` copy in a mise/rbenv/
+    # asdf/rvm Ruby's bin usually comes earlier on PATH, so `portage` in a
+    # shell silently keeps running the old gem after `brew install` or
+    # `brew upgrade` (Homebrew's own caveat hit exactly this on the
+    # maintainer's machine). Homebrew's `bin/portage` is a symlink into the
+    # Cellar, whose env_script wrapper execs the libexec binary, so every
+    # comparison here is between canonical Cellar locations, never raw PATH
+    # entries.
+    #
+    # Everything is read from the filesystem and the process: no `brew`
+    # shell-out, no network, so doctor stays fast and works offline (the
+    # formula's `test do` block runs it in Homebrew's sandbox).
+    class InstallDoctor
+      DEFAULT_HOMEBREW_PREFIXES = %w[/opt/homebrew /usr/local /home/linuxbrew/.linuxbrew].freeze
+      ADAPTER_GEMS = %w[shopify wix woocommerce bigcommerce magento etsy instagram webmcp decision]
+                     .map { |name| "portage-ucp-#{name}" }.freeze
+      EXECUTABLE = "portage".freeze
+
+      def self.homebrew_prefixes
+        [ENV.fetch("HOMEBREW_PREFIX", nil), *DEFAULT_HOMEBREW_PREFIXES].reject { |p| p.to_s.empty? }.uniq
+      end
+
+      # @param path [String] PATH to search for `portage` executables.
+      # @param homebrew_prefixes [Array<String>] candidate HOMEBREW_PREFIXes.
+      # @param gem_dir [String] this gem's own directory (its `lib/`'s parent).
+      # @param ruby [String] the running Ruby's executable path.
+      # @param adapter_probe [#call] gem name -> { installed:, loadable:, version:, error: }.
+      def initialize(path: ENV.fetch("PATH", ""), homebrew_prefixes: self.class.homebrew_prefixes,
+                     gem_dir: File.expand_path("../../..", __dir__), ruby: RbConfig.ruby,
+                     adapter_probe: method(:probe_adapter))
+        @path = path
+        @homebrew_prefixes = homebrew_prefixes.map { |prefix| canonical(prefix) }
+        @gem_dir = canonical(gem_dir)
+        @ruby = ruby
+        @adapter_probe = adapter_probe
+      end
+
+      def findings
+        [install_finding, runtime_finding, adapters_finding, path_finding].compact
+      end
+
+      # @return [String, nil] the HOMEBREW_PREFIX this copy runs from, nil for a gem install.
+      def homebrew_prefix
+        return @homebrew_prefix if defined?(@homebrew_prefix)
+
+        @homebrew_prefix = @homebrew_prefixes.find do |prefix|
+          [@gem_dir, canonical(@ruby)].any? { |dir| under?(dir, keg_root(prefix)) }
+        end
+      end
+
+      def homebrew? = !homebrew_prefix.nil?
+
+      private
+
+      # --- install method -------------------------------------------------
+
+      def install_finding
+        method = homebrew? ? "homebrew" : "gem"
+        path = homebrew? ? installed_keg : @gem_dir
+        details = { method: method, path: path }
+        details[:prefix] = homebrew_prefix if homebrew?
+        info("install", "#{method} (#{path})", details)
+      end
+
+      def keg_root(prefix) = File.join(prefix, "Cellar", "portage")
+
+      # `<prefix>/Cellar/portage/<version>`, the keg this copy lives in.
+      def installed_keg
+        root = keg_root(homebrew_prefix)
+        version = @gem_dir.delete_prefix("#{root}/").split("/").first
+        File.join(root, version)
+      end
+
+      # --- runtime --------------------------------------------------------
+
+      def runtime_finding
+        info("runtime", "Ruby #{RUBY_VERSION} (#{@ruby}), portage-cli #{VERSION}",
+             { ruby_version: RUBY_VERSION, ruby_path: @ruby, portage_cli_version: VERSION })
+      end
+
+      # --- adapters -------------------------------------------------------
+
+      # A gem install without adapters is normal: `gem install portage-cli`
+      # pulls in none of them, and you add the ones you use. The formula
+      # bundles every one, so a Homebrew install missing one is broken.
+      def adapters_finding
+        report = AdapterReport.new(ADAPTER_GEMS.map { |name| { name: name }.merge(safe_probe(name)) })
+        details = { adapters: report.adapters }
+        return warning("adapters", report.homebrew_missing_message, details) if homebrew? && report.missing?
+
+        info("adapters", report.summary, details)
+      end
+
+      def safe_probe(name)
+        @adapter_probe.call(name)
+      rescue StandardError, ScriptError => e
+        { installed: true, loadable: false, version: nil, error: "#{e.class}: #{e.message}" }
+      end
+
+      def probe_adapter(name)
+        specs = Gem::Specification.find_all_by_name(name)
+        return { installed: false, loadable: false, version: nil } if specs.empty?
+
+        require "portage/ucp/#{name.delete_prefix('portage-ucp-')}"
+        spec = Gem.loaded_specs[name] || specs.max_by(&:version)
+        { installed: true, loadable: true, version: spec.version.to_s }
+      end
+
+      # --- PATH shadowing -------------------------------------------------
+
+      def path_finding
+        candidates = path_candidates
+        return if candidates.empty?
+
+        details = { first: candidates.first[:path], candidates: candidates }
+        message = shadow_message(candidates.first)
+        return warning("path", message, details) if message
+
+        # Only a Homebrew keg can be matched to this copy for certain; a gem
+        # install's binstub can sit behind a mise/rbenv shim.
+        suffix = homebrew? ? " (this install)" : ""
+        info("path", "`portage` on PATH is #{candidates.first[:path]}#{suffix}", details)
+      end
+
+      # Every `portage` on PATH, first match first, one entry per real file:
+      # the same Homebrew bin can sit on PATH twice, and `bin/portage` and
+      # `opt/portage/bin/portage` both resolve to one keg.
+      def path_candidates
+        candidates = @path.split(File::PATH_SEPARATOR).reject(&:empty?).filter_map { |dir| candidate(dir) }
+        candidates.uniq { |c| c[:realpath] }
+      end
+
+      def candidate(dir)
+        file = File.join(dir, EXECUTABLE)
+        return unless File.file?(file) && File.executable?(file)
+
+        real = canonical(file)
+        { path: file, realpath: real, kind: homebrew_keg?(real) ? "homebrew" : "other" }
+      end
+
+      def shadow_message(first)
+        if homebrew?
+          return if under?(first[:realpath], keg_root(homebrew_prefix))
+
+          homebrew_shadowed_message(first)
+        elsif first[:kind] == "homebrew"
+          gem_shadowed_message(first)
+        end
+      end
+
+      def homebrew_shadowed_message(first)
+        brew_bin = File.join(homebrew_prefix, "bin")
+        "`portage` on PATH runs #{first[:path]}, not this Homebrew install (#{brew_bin}/portage), " \
+          "so `brew upgrade portage` won't change what your shell runs. Check with `which -a portage`. " \
+          "Fix: if that's a `gem install` copy, run `gem uninstall portage-cli` with that Ruby active; " \
+          "or put #{brew_bin} ahead of #{File.dirname(first[:path])} in PATH."
+      end
+
+      def gem_shadowed_message(first)
+        "`portage` on PATH runs the Homebrew install (#{first[:path]}), not this gem install " \
+          "(#{@gem_dir}). Check with `which -a portage`. Fix: keep one — `brew uninstall portage` " \
+          "to use the gem, or `gem uninstall portage-cli` to use Homebrew; or reorder PATH."
+      end
+
+      def homebrew_keg?(realpath)
+        @homebrew_prefixes.any? { |prefix| under?(realpath, keg_root(prefix)) }
+      end
+
+      # --- helpers --------------------------------------------------------
+
+      def under?(path, root) = path.start_with?("#{root}/")
+
+      def canonical(path)
+        File.realpath(path)
+      rescue SystemCallError
+        File.expand_path(path)
+      end
+
+      def info(check, message, details) = finding(check, message, details, "info")
+      def warning(check, message, details) = finding(check, message, details, "warning")
+
+      def finding(check, message, details, level)
+        Doctor::Finding.new(check: check, message: message, level: level, details: details)
+      end
+    end
+
+    # The adapters line of InstallDoctor's report, one probe result per gem:
+    # `{ name:, installed:, loadable:, version:, error: }`.
+    class InstallDoctor
+      class AdapterReport
+        attr_reader :adapters
+
+        def initialize(adapters)
+          @adapters = adapters
+        end
+
+        def missing = @adapters.reject { |a| a[:loadable] }
+        def missing? = missing.any?
+
+        def summary
+          loaded, broken, absent = partitioned
+          parts = [loaded.empty? ? "none loadable" : loaded.map { |a| "#{short(a)} #{a[:version]}" }.join(", ")]
+          parts << "failed to load: #{names(broken)}" unless broken.empty?
+          parts << "not installed: #{names(absent)}" unless absent.empty?
+          parts.join("; ")
+        end
+
+        def homebrew_missing_message
+          described = missing.map { |a| a[:error] ? "#{short(a)} (#{a[:error]})" : short(a) }
+          "This Homebrew install bundles every adapter, but #{described.join(', ')} can't be loaded — " \
+            "reinstall with `brew reinstall portage`."
+        end
+
+        private
+
+        def partitioned
+          loaded, rest = @adapters.partition { |a| a[:loadable] }
+          broken, absent = rest.partition { |a| a[:installed] }
+          [loaded, broken, absent]
+        end
+
+        def names(adapters) = adapters.map { |a| short(a) }.join(", ")
+        def short(adapter) = adapter[:name].delete_prefix("portage-ucp-")
+      end
+    end
+  end
+end

data/lib/portage/cli/shipping_profile.rb

@@ -20,9 +20,14 @@ module Portage
 
       # @return [Portage::Ucp::PostalAddress, nil] nil unless every required
       #   field is set — a partial profile isn't enough to submit, and this
-      #   module never guesses at a missing field.
+      #   module never guesses at a missing field. An empty value counts as
+      #   unset, so a `.env` copied from `.env.example` with blanks left in
+      #   doesn't submit an address of empty strings.
       def self.from_env
-        attrs = ENV_VARS.filter_map { |key, var| [key, ENV.fetch(var, nil)] if ENV.key?(var) }.to_h
+        attrs = ENV_VARS.filter_map do |key, var|
+          value = ENV.fetch(var, nil)
+          [key, value] unless value.to_s.empty?
+        end.to_h
         return nil unless REQUIRED.all? { |key| attrs.key?(key) }
 
         Portage::Ucp::PostalAddress.new(**attrs)

data/lib/portage/cli/version.rb

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

data/lib/portage/cli.rb

@@ -854,16 +854,26 @@ module Portage
       proxy_settings = apply_proxy_settings(opts[:proxy])
       return 1 unless proxy_settings
 
-      findings = Doctor.new(adapter_class: adapter_class, proxy_settings: proxy_settings).call
-      puts opts[:json] ? JSON.pretty_generate(findings.map(&:to_h)) : format_doctor(findings)
-      findings.empty? ? 0 : 1
+      doctor = Doctor.new(adapter_class: adapter_class, proxy_settings: proxy_settings,
+                          seller: !(opts[:require] || opts[:adapter]).nil?)
+      report_doctor(doctor.call, json: opts[:json])
     end
     private_class_method :run_doctor
 
-    def self.format_doctor(findings)
-      return "No issues found." if findings.empty?
+    def self.report_doctor(findings, json:)
+      puts json ? JSON.pretty_generate(findings.map(&:to_h)) : format_doctor(findings)
+      findings.none?(&:warning?) ? 0 : 1
+    end
+    private_class_method :report_doctor
 
-      findings.map { |f| "[#{f.check}] #{f.message}" }.join("\n")
+    # Info findings (install method, Ruby, adapters, PATH) first, then the
+    # warnings, which alone decide the exit code.
+    def self.format_doctor(findings)
+      info, warnings = findings.partition { |f| !f.warning? }
+      lines = info.map { |f| "[#{f.check}] #{f.message}" }
+      lines << "" unless info.empty?
+      lines.concat(warnings.empty? ? ["No issues found."] : warnings.map { |f| "[#{f.check}] #{f.message}" })
+      lines.join("\n")
     end
     private_class_method :format_doctor
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: portage-cli
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.7.5
 platform: ruby
 authors:
 - Tom Whitbread
@@ -165,6 +165,7 @@ files:
 - lib/portage/cli/console.rb
 - lib/portage/cli/decisions.rb
 - lib/portage/cli/doctor.rb
+- lib/portage/cli/dot_env.rb
 - lib/portage/cli/find.rb
 - lib/portage/cli/generate/adapter.rb
 - lib/portage/cli/generate/agent_profile.rb
@@ -175,6 +176,7 @@ files:
 - lib/portage/cli/handoff_waiter.rb
 - lib/portage/cli/history.rb
 - lib/portage/cli/homepage_fetch.rb
+- lib/portage/cli/install_doctor.rb
 - lib/portage/cli/macos_notifier.rb
 - lib/portage/cli/notifier.rb
 - lib/portage/cli/payment_methods.rb