portage-cli 0.7.4 → 0.7.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58834de7ed60ddb98da33896147737f518ccb8d02d58f0d3aeceb645ecef8ea6
-  data.tar.gz: 24e471dfb23e48b8ff1f157dbac941442ca84571120ad754451dfb36d9c08d60
+  metadata.gz: a682278ec8b34cb6e2cd649f345cb6779a7cec5d0bc22e6950721f7996a2d877
+  data.tar.gz: ed490b87284e6a8c9bd9ab280ea600d16877820240386d34e239309a8204b16d
 SHA512:
-  metadata.gz: 70c1a8b9db25d281091e496db0eb7e45de1e54b0afbc943a35866cc9ec2efb4a292b043a0720932ff5f3c2a93757ec3b217785d96ec4f2ece6e637132aed1d04
-  data.tar.gz: af42b5fb85cc582d86e60d616f38f177df92b6c53df59a7ccedcd8780855adb15f876e32ddbfda384bd579825ed90f68c5a833fd061ed79fce43e3a2c056edcd
+  metadata.gz: c22fd29667f7281c0173503cc9797158de1cd9d494cfcc98795bbce3ecfbaa03ed67ecb1321b3adf83000cf251168a62118db703bf1fb7b5417ba615a672b8c5
+  data.tar.gz: 42016dd1b716169b2dbaadef6f83a210ab8750584b23464e8c38c76aa39374988eeda97cfdc133c3edffaaf3c3ef8b34a76aa2fd57a9c96ad32292d529878df4

data/CHANGELOG.md

@@ -4,6 +4,27 @@ 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

data/README.md

@@ -424,10 +424,15 @@ installed, then lists anything that needs fixing:
   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; pass `--require` to load
-  your app's initializer first), the confidence gate's backend, the
-  User-Agent, and proxy settings.
+  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,
@@ -602,21 +607,58 @@ 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.
 
+### 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
 
-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:
+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

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

@@ -4,6 +4,7 @@ require_relative "confidence_check"
 require_relative "user_agent"
 require_relative "proxy_settings"
 require_relative "shipping_profile"
+require_relative "dot_env"
 
 module Portage
   module Cli
@@ -26,19 +27,27 @@ module Portage
         def to_h = super.compact
       end
 
-      def initialize(adapter_class: nil, proxy_settings: ProxySettings.new, install_doctor: InstallDoctor.new)
+      SELLER_CHECKS = "authenticator, rate limiter, signing keys, payment handlers".freeze
+
+      # @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
         [
           *@install_doctor.findings,
-          authenticator_finding,
-          rate_limiter_finding,
-          signing_keys_finding,
-          payment_handlers_finding,
+          dot_env_finding,
+          *seller_findings,
           decision_backend_finding,
           user_agent_finding,
           shipping_finding,
@@ -52,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)
 
@@ -115,8 +149,8 @@ module Portage
                                            .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.")
+        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)

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/version.rb

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

data/lib/portage/cli.rb

@@ -854,7 +854,9 @@ module Portage
       proxy_settings = apply_proxy_settings(opts[:proxy])
       return 1 unless proxy_settings
 
-      report_doctor(Doctor.new(adapter_class: adapter_class, proxy_settings: proxy_settings).call, json: opts[:json])
+      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
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: portage-cli
 version: !ruby/object:Gem::Version
-  version: 0.7.4
+  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