portage-cli 0.7.3 → 0.7.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 996ddc0acd1ec2676257f402fbb03148e8a38c40af9d5cf4fbe50d176416a334
-  data.tar.gz: a451d4e8130b1891fb2630d9b5e9edc1efde9486afda2ca3ff863342943d4a09
+  metadata.gz: 58834de7ed60ddb98da33896147737f518ccb8d02d58f0d3aeceb645ecef8ea6
+  data.tar.gz: 24e471dfb23e48b8ff1f157dbac941442ca84571120ad754451dfb36d9c08d60
 SHA512:
-  metadata.gz: dd25c1c868d3e70f6ef469975f0d2b24f478c1f96bf83a739d2e4a473c38d2695fbd3586e0243ac21f9d75562b080413ad173c18924024ff1135279cfe8622be
-  data.tar.gz: e8578d6935466578e44e9e4f2e2caae61e1b9a1b2b52051934989fd28ec8ea9a163d943e3f68aac3704bdae72557d600f4694c7c81b8e9fe00b16685640a10b6
+  metadata.gz: 70c1a8b9db25d281091e496db0eb7e45de1e54b0afbc943a35866cc9ec2efb4a292b043a0720932ff5f3c2a93757ec3b217785d96ec4f2ece6e637132aed1d04
+  data.tar.gz: af42b5fb85cc582d86e60d616f38f177df92b6c53df59a7ccedcd8780855adb15f876e32ddbfda384bd579825ed90f68c5a833fd061ed79fce43e3a2c056edcd

data/CHANGELOG.md

@@ -4,6 +4,41 @@ 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.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,37 @@ 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.
+- Seller-side checks against `Portage::Ucp.configuration` (authenticator,
+  rate limiter, signing keys, payment handlers; pass `--require` to load
+  your app's initializer first), the confidence gate's backend, the
+  User-Agent, and proxy settings.
+
+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,12 +602,11 @@ 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)
+### 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 via env rather than a flag, the same way as
+adapter credentials (`.env.example` at the repo root lists them all).
+`portage doctor` warns until the required ones are set:
 
 ```bash
 export PORTAGE_SHIP_STREET="1 Main St"
@@ -529,12 +619,26 @@ export PORTAGE_SHIP_LAST_NAME="Lovelace" # optional
 export 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/lib/portage/cli/doctor.rb

@@ -3,6 +3,7 @@ require "uri"
 require_relative "confidence_check"
 require_relative "user_agent"
 require_relative "proxy_settings"
+require_relative "shipping_profile"
 
 module Portage
   module Cli
@@ -16,21 +17,31 @@ 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
 
-      def initialize(adapter_class: nil, proxy_settings: ProxySettings.new)
+      def initialize(adapter_class: nil, proxy_settings: ProxySettings.new, install_doctor: InstallDoctor.new)
         @adapter_class = adapter_class
         @proxy_settings = proxy_settings
+        @install_doctor = install_doctor
       end
 
       def call
         [
+          *@install_doctor.findings,
           authenticator_finding,
           rate_limiter_finding,
           signing_keys_finding,
           payment_handlers_finding,
           decision_backend_finding,
           user_agent_finding,
+          shipping_finding,
           proxy_finding,
           *proxy_doctor_findings,
           *capability_findings
@@ -93,6 +104,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)} Export them in your shell; " \
+                                                ".env.example lists every PORTAGE_SHIP_* variable.")
+      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 +233,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/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.4".freeze
   end
 end

data/lib/portage/cli.rb

@@ -854,16 +854,24 @@ 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
+      report_doctor(Doctor.new(adapter_class: adapter_class, proxy_settings: proxy_settings).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.4
 platform: ruby
 authors:
 - Tom Whitbread
@@ -175,6 +175,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