portage-cli 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a0e9e7e0b7046fc20978a89fb06056bf1827df5efa45c47ddfb0b16f332d53f
-  data.tar.gz: 9ab0f0c9caa507147fae5069dda27c86a92e4c26f273c9cbc14cee8fbfddf368
+  metadata.gz: 4acb63ece20e24b7d43048315145a96e15ded1c4e5b0cf83c3f045603a033af6
+  data.tar.gz: 536057c80badcd44ee1be90679fd7f9233adb3d5a1c07b5b11a12201fbae5701
 SHA512:
-  metadata.gz: 247e88dba38ac3171cedccd90d0d1e56ff225cf8aa2526598c3d670391d79fc908fe9fe81735aa71f1c389516ae04c5c71512c61e56bc39802b92bd213d6b40a
-  data.tar.gz: 07d42f21ba32010310394a39a664599c09e840a58cc1be6dd5bcbed7e9d0adf46639364f2bbd70ee70f63fcbfe9407a6d04af9ea75669cc5ae6a5f0f226c5226
+  metadata.gz: 54bc26bf74fe96c2a2154062ab41619e10bf046da1cc06f067fc1f0f7eaec9c29ff6ab461e9cf2907ede4084805b8718f65557e5d4c3c79c486650eea10c1075
+  data.tar.gz: deb45f093ce769ebae837bad5af628c8970aac76b6741ea8b083393b45038451a455ece2d603671c3d2884e3974858941ff6c29d96affd7bd3bbcc89f6a689d9

data/CHANGELOG.md

@@ -4,6 +4,39 @@ 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.6.0] - 2026-09-17
+
+- Fixed `buy`/`find` crashing with a raw `Faraday::UnprocessableContentError`
+  against a real UCP store, once manifest parsing succeeded — the actual
+  `search_catalog`/`create_checkout` calls were still built in the wrong
+  wire shape (see `portage-ucp-client` 0.4.0). Both commands
+  now report a clear, actionable message instead: set `PORTAGE_AGENT_PROFILE`
+  when it's missing, or surface the store's rejection cleanly when it's set
+  but not accepted.
+- Added `PORTAGE_AGENT_PROFILE` — required for `find`/`buy` against a real,
+  external UCP store (not your own store via an adapter). No default; see
+  `.env.example`.
+- Fixed `buy` sending a catalog product's own id as the purchasable line
+  item — correct for a backend where "the product" and "the thing you add
+  to a cart" share one id, but wrong for Shopify (confirmed live: every
+  `portage buy` against a real Shopify test store failed with "Invalid id",
+  since Storefront's cart takes a `ProductVariant` GID, not the parent
+  `Product` GID `search_catalog` returns as `id`). `Buy#full_buy` and
+  `#redirect_checkout` now build `line_items` from a product's first/
+  default variant id when one exists, falling back to the product id
+  otherwise; `--product-id` matching (`#product_id_of`) is unchanged, since
+  it still needs to match the catalog-level id `find`/`compare` show the
+  caller.
+- Added `portage generate agent-profile`, which writes a real UCP
+  agent-identity document (the JSON a store fetches from the
+  `meta.ucp-agent.profile` URL to decide whether to answer at all).
+  `portage-cli`'s own generated profile is checked in at
+  `agent-profile/agent-profile.json` and published to a stable URL by
+  `.github/workflows/publish-agent-profile.yml`, which is what
+  `PORTAGE_AGENT_PROFILE` defaults to pointing at.
+- Widens the `portage-ucp` pin to `~> 0.8` and the `portage-ucp-client` pin
+  to `~> 0.4` so this gem installs alongside the 0.8.0-line releases.
+
 ## [0.5.1] - 2026-09-16
 
 - No behavior change — 0.5.0 was built and pushed with `gem build` run from

data/lib/portage/cli/buy.rb

@@ -61,6 +61,14 @@ module Portage
 
       def discover(url)
         Portage::Ucp::Client.discover(url.to_s)
+      rescue Portage::Ucp::Client::ManifestShapeError => e
+        # The store *is* running UCP — this client just couldn't parse its
+        # manifest. Distinct from a genuine 404/unreachable host below:
+        # falling through silently there would hide a bug in this gem behind
+        # the same "no automated path" message a store with no UCP support
+        # gets, so this warns instead.
+        warn "portage: #{url} serves a UCP manifest this client couldn't parse (#{e.message})"
+        nil
       rescue Portage::Ucp::Client::DiscoveryError
         nil
       end
@@ -71,6 +79,30 @@ module Portage
         else
           catalog_only(session)
         end
+      rescue Portage::Ucp::Client::MissingAgentProfileError, Portage::Ucp::Client::UnsupportedWireShapeError,
+             MCP::Client::RequestHandlerError => e
+        native_flow_error_report(e)
+      end
+
+      def native_flow_error_report(error)
+        case error
+        when Portage::Ucp::Client::MissingAgentProfileError
+          build_report(source: "native_ucp", browse: false, checkout: false,
+                       message: "Set PORTAGE_AGENT_PROFILE to a URL that describes this agent — " \
+                                "#{@uri} verifies it before answering any UCP call.")
+        when Portage::Ucp::Client::UnsupportedWireShapeError
+          build_report(source: "native_ucp", browse: true, checkout: false,
+                       message: "Can't complete checkout on #{@uri} yet: #{error.message}")
+        else
+          # MCP::Client::RequestHandlerError doesn't retain the server's JSON
+          # error body on this path, so this can't quote the server's own
+          # explanation — a common cause is PORTAGE_AGENT_PROFILE not
+          # pointing at a real, JSON agent-profile document the store's UCP
+          # endpoint accepts.
+          build_report(source: "native_ucp", browse: false, checkout: false,
+                       message: "#{@uri} rejected the request (#{error.message}) — if PORTAGE_AGENT_PROFILE " \
+                                "is set, check it points at a real agent-profile document the store accepts.")
+        end
       end
 
       def catalog_only(session)
@@ -156,8 +188,9 @@ module Portage
       def redirect_checkout(adapter, products)
         return nil if products.empty? || !Portage::Ucp::Capabilities::CHECKOUT.advertised_for?(adapter)
 
-        adapter.create_checkout(line_items: [{ product_id: products.first.id, quantity: @qty }],
-                                idempotency_key: "portage-buy-#{products.first.id}")
+        item_id = products.first.variants&.first&.id || products.first.id
+        adapter.create_checkout(line_items: [{ product_id: item_id, quantity: @qty }],
+                                idempotency_key: "portage-buy-#{item_id}")
       rescue StandardError
         nil
       end
@@ -178,8 +211,9 @@ module Portage
                               message: no_match_message)
         end
 
-        checkout = session.create_checkout(line_items: [{ product_id: product_id_of(product), quantity: @qty }],
-                                           fulfillment: requested_fulfillment(fulfillment_adapter))
+        checkout = session.create_checkout(line_items: [{ product_id: line_item_id_of(product), quantity: @qty }],
+                                           fulfillment: requested_fulfillment(fulfillment_adapter),
+                                           meta: agent_meta)
         checkout = select_cheapest_shipping(session, checkout) if fulfillment_adapter
         finish_checkout(session, source, products, checkout)
       end
@@ -264,6 +298,20 @@ module Portage
         product["id"]
       end
 
+      # `create_checkout`'s `line_items[].product_id` is the conformance
+      # kit's overloaded name (portage-ucp/lib/portage/ucp/rspec.rb) for
+      # "whatever id this adapter's cart actually takes" — for a backend
+      # where a product's variants have their own id (confirmed live on
+      # Shopify: a ProductVariant GID, distinct from the parent Product
+      # GID), that's the first/default variant, not the catalog id
+      # #product_id_of returns for display/--product-id matching. A
+      # product with no variants (or a backend that doesn't distinguish
+      # the two) falls back to the product id unchanged (see
+      # docs/design-log.md §41).
+      def line_item_id_of(product)
+        product["variants"]&.first&.dig("id") || product_id_of(product)
+      end
+
       def finish_checkout(session, source, products, checkout)
         status = checkout["status"]
         return escalation_report(source, products, checkout) if status == "requires_escalation"
@@ -314,7 +362,15 @@ module Portage
       end
 
       def safe_search(session)
-        CatalogProducts.from(session.search_catalog(query: @query, limit: 10))
+        CatalogProducts.from(session.search_catalog(query: @query, limit: 10, meta: agent_meta))
+      end
+
+      # Real UCP servers fetch this URL to verify the caller's identity
+      # before answering any call (see Transports::Http) — the own-store
+      # loopback path ignores it harmlessly, so it's cheapest to always pass
+      # it rather than branch on which transport `session` happens to be.
+      def agent_meta
+        { agent_profile: ENV.fetch("PORTAGE_AGENT_PROFILE", nil) }
       end
 
       # --- Homepage fetch (used by both the manifest-not-found path and the

data/lib/portage/cli/find.rb

@@ -46,6 +46,10 @@ module Portage
         offers = rank(stores.flat_map { |store| offers_for(store) })
         report(candidates: candidates, stores: stores.map { |s| s.slice(:origin, :source, :checkout) },
                offers: offers, message: summary(candidates, stores, offers))
+      rescue Portage::Ucp::Client::MissingAgentProfileError
+        report(candidates: candidates, stores: stores.map { |s| s.slice(:origin, :source, :checkout) },
+               message: "Set PORTAGE_AGENT_PROFILE to a URL that describes this agent — each store " \
+                        "verifies it before answering a catalog search.")
       end
 
       private
@@ -135,12 +139,23 @@ module Portage
       # --- Step 3: ask the survivors what they stock ---
 
       def offers_for(store)
-        products = CatalogProducts.from(store[:session].search_catalog(query: @query, limit: PER_STORE_RESULTS))
+        products = CatalogProducts.from(
+          store[:session].search_catalog(query: @query, limit: PER_STORE_RESULTS, meta: agent_meta)
+        )
         products.filter_map { |product| offer(store, product) }
+      rescue Portage::Ucp::Client::MissingAgentProfileError
+        raise
       rescue StandardError
         []
       end
 
+      # Real UCP servers fetch this URL to verify the caller's identity
+      # before answering any call (see Transports::Http) — the own-store
+      # loopback path ignores it harmlessly.
+      def agent_meta
+        { agent_profile: ENV.fetch("PORTAGE_AGENT_PROFILE", nil) }
+      end
+
       def offer(store, product)
         amount, currency = price_of(product)
         return nil if @max_price && amount && amount > @max_price

data/lib/portage/cli/generate/agent_profile.rb

@@ -0,0 +1,142 @@
+require "openssl"
+require "digest"
+require "base64"
+require "json"
+require "fileutils"
+require "portage/ucp"
+
+module Portage
+  module Cli
+    module Generate
+      # Generates and (re)publishes portage-cli's own UCP agent-identity
+      # profile document — the `meta.ucp-agent.profile` URL real UCP servers
+      # fetch and validate before answering any catalog/cart/checkout call
+      # (confirmed live against Shopify's 2026-08-25 rollout: an unreachable
+      # or malformed profile 422s with `profile_unreachable`/`profile_malformed`
+      # before the request's shape is even considered). This class only
+      # produces the document and its signing key; hosting it at a stable,
+      # public URL (HTTPS, no redirects, `Cache-Control: public, max-age>=60`
+      # — see docs/agent-profile.md) is a separate, one-time infra step.
+      #
+      # Deliberately NOT Portage::Ucp::Manifest, despite the surface
+      # similarity: Manifest builds the *business's* /.well-known/ucp
+      # document and nests `signing_keys` inside its own "ucp" envelope
+      # (portage-ucp/lib/portage/ucp/manifest.rb); the UCP spec's agent
+      # profile is a different document describing the *agent* calling in,
+      # and puts `signing_keys` as a sibling of "ucp" at the document root.
+      # Same-looking key material, structurally different document — not
+      # interchangeable, so this doesn't subclass or reuse Manifest.
+      #
+      # `Portage::Ucp::Manifest::UCP_VERSION` is reused as-is (not
+      # redeclared) so the two documents can never drift to different spec
+      # versions by accident.
+      #
+      # Rotation is the future-proofing this exists for: re-running with
+      # `rotate: true` keeps every key already published (so a request
+      # signed under an older `kid` keeps verifying while callers migrate)
+      # and adds one freshly generated key alongside them. Nothing here ever
+      # drops a key — retiring one is a deliberate, separate edit once
+      # nothing signs with it any more.
+      class AgentProfile
+        UCP_VERSION = Portage::Ucp::Manifest::UCP_VERSION
+
+        Key = Struct.new(:kid, :jwk, :private_pem, keyword_init: true)
+
+        # @param out [String] path to write the public profile JSON document
+        # @param key_out [String] path to write the new private key's PEM —
+        #   caller's responsibility to keep this out of version control
+        # @param rotate [Boolean] keep existing signing_keys from `out` (if
+        #   it already exists) and add a new one, instead of replacing them
+        # @return [Hash] { profile_path:, private_key_path:, kid: } — the
+        #   kid of the newly generated key
+        def self.generate(out:, key_out:, rotate: false)
+          new(out: out, key_out: key_out, rotate: rotate).generate
+        end
+
+        def initialize(out:, key_out:, rotate: false)
+          @out = out
+          @key_out = key_out
+          @rotate = rotate
+        end
+
+        def generate
+          new_key = generate_key
+          doc = build_document(carried_forward_keys + [new_key.jwk])
+
+          write_profile(doc)
+          write_private_key(new_key.private_pem)
+
+          { profile_path: @out, private_key_path: @key_out, kid: new_key.kid }
+        end
+
+        private
+
+        def carried_forward_keys
+          return [] unless @rotate && File.exist?(@out)
+
+          JSON.parse(File.read(@out)).fetch("signing_keys", [])
+        rescue JSON::ParserError
+          []
+        end
+
+        def build_document(signing_keys)
+          {
+            "ucp" => {
+              "version" => UCP_VERSION,
+              "services" => {},
+              "capabilities" => {},
+              "payment_handlers" => {}
+            },
+            "signing_keys" => signing_keys
+          }
+        end
+
+        def write_profile(doc)
+          FileUtils.mkdir_p(File.dirname(@out))
+          File.write(@out, "#{JSON.pretty_generate(doc)}\n")
+        end
+
+        def write_private_key(pem)
+          FileUtils.mkdir_p(File.dirname(@key_out))
+          File.write(@key_out, pem)
+          File.chmod(0o600, @key_out)
+        end
+
+        # A JWK's `kid` is derived from the key material itself (RFC 7638
+        # thumbprint) rather than assigned, so it can't drift from the key
+        # it names — a caller can't accidentally publish a profile where a
+        # `kid` points at the wrong entry.
+        def generate_key
+          pkey = OpenSSL::PKey::EC.generate("prime256v1")
+          x_b64, y_b64 = coordinates(pkey)
+          kid = thumbprint(x_b64, y_b64)
+
+          jwk = { "kid" => kid, "kty" => "EC", "crv" => "P-256", "x" => x_b64, "y" => y_b64,
+                  "use" => "sig", "alg" => "ES256" }
+
+          Key.new(kid: kid, jwk: jwk, private_pem: pkey.to_pem)
+        end
+
+        # Raw uncompressed EC point encoding: 0x04 || x (32 bytes) || y (32
+        # bytes) for P-256 — see Portage::Ucp::Security::Signature::CURVES,
+        # which decodes the same layout in reverse when verifying.
+        def coordinates(pkey)
+          octets = pkey.public_key.to_bn.to_s(2)
+          coord_bytes = 32
+          x = octets[1, coord_bytes]
+          y = octets[1 + coord_bytes, coord_bytes]
+          [url_b64(x), url_b64(y)]
+        end
+
+        def thumbprint(x_b64, y_b64)
+          canonical = JSON.generate({ "crv" => "P-256", "kty" => "EC", "x" => x_b64, "y" => y_b64 })
+          url_b64(Digest::SHA256.digest(canonical))
+        end
+
+        def url_b64(bytes)
+          Base64.urlsafe_encode64(bytes, padding: false)
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Cli
-    VERSION = "0.5.1".freeze
+    VERSION = "0.6.0".freeze
   end
 end

data/lib/portage/cli.rb

@@ -11,6 +11,7 @@ require_relative "cli/history"
 require_relative "cli/payment_methods"
 require_relative "cli/doctor"
 require_relative "cli/generate/adapter"
+require_relative "cli/generate/agent_profile"
 
 module Portage
   # `portage` — the single command-line entrypoint for acting as a shopper's
@@ -41,6 +42,7 @@ module Portage
                                  [--allow HOST ...] [--clear-allowlist]
              portage doctor [--require FILE] [--adapter CLASS_NAME] [--json]
              portage generate adapter NAME [--dir DIR]
+             portage generate agent-profile [--out FILE] [--key-out FILE] [--rotate]
     USAGE
 
     COMMANDS = { "buy" => :run_buy, "find" => :run_find, "compare" => :run_compare,
@@ -552,8 +554,20 @@ module Portage
     # --- generate ---
 
     def self.run_generate(argv)
-      kind, name, *rest = argv
-      unless kind == "adapter" && name
+      kind, *rest = argv
+      case kind
+      when "adapter" then run_generate_adapter(rest)
+      when "agent-profile" then run_generate_agent_profile(rest)
+      else
+        warn USAGE
+        1
+      end
+    end
+    private_class_method :run_generate
+
+    def self.run_generate_adapter(rest)
+      name, *rest = rest
+      unless name
         warn USAGE
         return 1
       end
@@ -564,7 +578,25 @@ module Portage
       puts "Scaffolded #{path}/"
       0
     end
-    private_class_method :run_generate
+    private_class_method :run_generate_adapter
+
+    def self.run_generate_agent_profile(rest)
+      out = "agent-profile.json"
+      key_out = "agent-profile.key.pem"
+      rotate = false
+      OptionParser.new do |parser|
+        parser.on("--out FILE") { |v| out = v }
+        parser.on("--key-out FILE") { |v| key_out = v }
+        parser.on("--rotate") { rotate = true }
+      end.parse!(rest)
+
+      result = Generate::AgentProfile.generate(out: out, key_out: key_out, rotate: rotate)
+      puts "Wrote #{result[:profile_path]} (kid #{result[:kid]})"
+      puts "Wrote private key to #{result[:private_key_path]} — keep this out of version control " \
+           "and off the machine that serves the public profile"
+      0
+    end
+    private_class_method :run_generate_agent_profile
 
     # --- output ---
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: portage-cli
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Tom Whitbread
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: portage-ucp
@@ -16,28 +15,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '0.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: portage-ucp-client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: portage-ucp-journal
   requirement: !ruby/object:Gem::Requirement
@@ -120,7 +119,6 @@ description: 'Ships the `portage` executable. `portage buy <url>` tries native U
   portage-ucp-client (for the actual buy calls), and portage-ucp-journal (for `portage-console`''s
   read-only view of local purchase/transaction/order state); no single adapter gem
   is a hard dependency.'
-email:
 executables:
 - portage
 - portage-console
@@ -140,6 +138,7 @@ files:
 - lib/portage/cli/doctor.rb
 - lib/portage/cli/find.rb
 - lib/portage/cli/generate/adapter.rb
+- lib/portage/cli/generate/agent_profile.rb
 - lib/portage/cli/history.rb
 - lib/portage/cli/payment_methods.rb
 - lib/portage/cli/payment_methods/env_backend.rb
@@ -156,7 +155,6 @@ metadata:
   source_code_uri: https://github.com/tomtom87/Portage/tree/main/portage-cli
   changelog_uri: https://github.com/tomtom87/Portage/blob/main/portage-cli/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -171,8 +169,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.21
 specification_version: 4
 summary: portage — one CLI command to buy from any store, native UCP or not
 test_files: []