portage-cli 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86b0359cf6f3c98f45853a7407dd03e9688f91212ce1ee05e84727b34450e3ad
-  data.tar.gz: 94eeec1e819b534d38055bc55c61a74cc61730d0134e5f7bc5da7aef3a257485
+  metadata.gz: 4acb63ece20e24b7d43048315145a96e15ded1c4e5b0cf83c3f045603a033af6
+  data.tar.gz: 536057c80badcd44ee1be90679fd7f9233adb3d5a1c07b5b11a12201fbae5701
 SHA512:
-  metadata.gz: b8f1f2b0c0a9addba9154c3951c90ec4c3dcd1b8b765e03eca8c13ed17f80c23b7999efaa993c4173f045f12c7ad724705667e00164d5f3a87905caab216197a
-  data.tar.gz: 26e138751551e630c86de1ccd2e701f9cf287ef0cf6ed78e852bae7ed8c43922257d3f7a3840a3f8735de0306c4d39e01f40bf9348388041a9516c65bd3dbbd8
+  metadata.gz: 54bc26bf74fe96c2a2154062ab41619e10bf046da1cc06f067fc1f0f7eaec9c29ff6ab461e9cf2907ede4084805b8718f65557e5d4c3c79c486650eea10c1075
+  data.tar.gz: deb45f093ce769ebae837bad5af628c8970aac76b6741ea8b083393b45038451a455ece2d603671c3d2884e3974858941ff6c29d96affd7bd3bbcc89f6a689d9

data/CHANGELOG.md

@@ -4,7 +4,72 @@ 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.
 
-## [Unreleased]
+## [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
+  the workspace root instead of this gem's own directory, so `spec.files =
+  Dir[...]` resolved against the wrong working directory and packaged an
+  empty gem. 0.5.0 has been yanked; 0.5.1 repackages the exact same 0.5.0
+  code correctly.
+
+## [0.5.0] - 2026-09-16
+
+- Added `portage-console` — a read-only IRB REPL over the local
+  `TransactionLog`/`OrderLedger`/`PurchaseJournal` stores (design-log §22
+  item 6, `Portage::Cli::Console`). `transactions`/`find_transaction`/
+  `transactions_since`, `orders`/`find_order`, and `journal`. Every result
+  passes through `Portage::Ucp::Observability.redact`. Deliberately a local
+  REPL, not the admin/web panel design-log §16 also describes — see the
+  README's Console section for why. New runtime dependency on
+  `portage-ucp-journal` (`~> 0.1`).
+- `Buy#client_for` now passes a real `Portage::Ucp::Journal::PurchaseJournal`
+  (file-backed, `~/.portage/journal.jsonl`) into `Client.for_adapter` — the
+  own-store loopback path used by `portage buy` against your own store now
+  actually records to the purchase journal, closing the gap `portage-console`
+  above depends on: `journal` was empty on this path because nothing passed
+  `journal:` through it (design-log §37/§38).
+- Added `portage generate adapter` — scaffolds a new adapter gem (gemspec,
+  Gemfile, Rakefile, rubocop config, lib entrypoint, version file, an
+  `Adapter` subclass with every capability method stubbed by reflecting off
+  `Portage::Ucp::Adapter`'s real method signatures, and a conformance spec),
+  modeled on `portage-ucp-etsy`.
+- Added `portage doctor` — sanity-checks a seller's
+  `Portage::Ucp.configuration` (authenticator/rate-limiter left at
+  unconfigured fail-safe defaults, no signing keys/payment handlers
+  configured, adapter capabilities only half-implemented).
 
 ## [0.4.1] - 2026-09-15
 

data/README.md

@@ -39,11 +39,13 @@ portage compare https://your-shop.example --product-id prod_123 --results 5
 ```
 
 Depends on [`portage-ucp`](https://github.com/tomtom87/Portage/tree/main/portage-ucp)
-(for platform detection via `Resolver`) and
+(for platform detection via `Resolver`),
 [`portage-ucp-client`](https://github.com/tomtom87/Portage/tree/main/portage-ucp-client)
-(for the actual buy calls). No single adapter gem is a hard dependency — install
-whichever `portage-ucp-<platform>` gem matches the store you're integrated with,
-if any.
+(for the actual buy calls), and
+[`portage-ucp-journal`](https://github.com/tomtom87/Portage/tree/main/portage-ucp-journal)
+(for `portage-console`'s read-only view of local purchase state — see below).
+No single adapter gem is a hard dependency — install whichever
+`portage-ucp-<platform>` gem matches the store you're integrated with, if any.
 
 ## Installation
 
@@ -313,6 +315,39 @@ Backends that have no credentials sit out; DuckDuckGo is the keyless default
 because it's the only no-key engine with a real API, and its narrowness is the
 price of not scraping.
 
+### Console
+
+`portage-console` is a separate executable — a read-only IRB REPL over the
+three local `~/.portage` stores (design-log §22 item 6): `TransactionLog`
+(reserve/complete records), `OrderLedger` (settled-order snapshots), and, if
+you've wired `journal:` into your own `Dispatcher` (nothing in this gem does
+that for you), the `portage-ucp-journal` gem's `PurchaseJournal`.
+
+```bash
+portage-console
+```
+
+```ruby
+transactions                       # every reserved/completed transaction
+transactions(shop: "your-shop.example")
+find_transaction("idem_key_123")
+transactions_since(Time.now - 86400, shop: "your-shop.example")
+
+orders                             # every settled-order snapshot
+find_order("order_123")
+
+journal                            # empty unless a Dispatcher was built with journal:
+```
+
+Every result is passed through `Portage::Ucp::Observability.redact` before
+it's returned — `payment_token`/`oauth_token`/`Authorization` and the PII
+fields on an order's fulfillment destinations never print, even in a REPL you
+trust. This is deliberately a local REPL, not the admin/web panel design-log
+§16 also describes: a browser is a new place for a token to leak, and the
+process holding a web panel also holds this machine's live platform admin
+credentials in its env — problems a REPL run by whoever already has shell
+access to this machine doesn't have.
+
 ## Development
 
 ```bash

data/exe/portage-console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "irb"
+require "portage/cli/console"
+
+include Portage::Cli::Console # rubocop:disable Style/MixinUsage -- top-level REPL helpers, by design
+
+puts "portage-console — read-only helpers: transactions, find_transaction(key), " \
+     "transactions_since(time, shop:), orders, find_order(id), journal. Every result is redacted."
+IRB.start

data/lib/portage/cli/buy.rb

@@ -3,6 +3,7 @@ require "uri"
 require "json"
 require "portage/ucp"
 require "portage/ucp/client"
+require "portage/ucp/journal"
 require_relative "payment_methods"
 
 module Portage
@@ -60,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
@@ -70,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)
@@ -127,8 +160,18 @@ module Portage
           Portage::Ucp::Capabilities::CHECKOUT.advertised_for?(adapter)
       end
 
+      # `journal:` closes design-log §37's named gap — `Mcp::Server.build`
+      # (and the `Loopback`/`Client.for_adapter` it sits behind) now forward
+      # a `journal:` kwarg straight to `Dispatcher`, but nothing on this own-
+      # store loopback path ever passed one, so `portage buy` against your
+      # own store settled real transactions/orders while leaving the journal
+      # `nil`. `PurchaseJournal.new`'s own default (`FileStore.new`) is
+      # `~/.portage/journal.jsonl` — the same "real file-backed default"
+      # posture `transaction_log:`/`order_ledger:` already get from
+      # `Dispatcher#initialize`.
       def client_for(adapter)
-        Portage::Ucp::Client.for_adapter(adapter, authenticator: PermissiveAuthenticator.new)
+        Portage::Ucp::Client.for_adapter(adapter, authenticator: PermissiveAuthenticator.new,
+                                                  journal: Portage::Ucp::Journal::PurchaseJournal.new)
       end
 
       def catalog_only_adapter(adapter, platform)
@@ -145,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
@@ -167,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
@@ -253,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"
@@ -303,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/console.rb

@@ -0,0 +1,68 @@
+require "portage/ucp"
+require "portage/ucp/journal"
+
+module Portage
+  module Cli
+    # Read-only REPL helpers over the three local stores design-log §22
+    # names (`TransactionLog`, `OrderLedger`, `PurchaseJournal`) — the
+    # console remainder of item 6. Deliberately a REPL, not the web/admin
+    # panel §16 also described: that panel needs its own session auth
+    # because a browser is a new place for a token to leak, on a process
+    # that already holds live platform admin credentials in its env. A
+    # local REPL run by whoever already holds this machine's `~/.portage`
+    # files and env has neither problem, so this is `exe/portage-console`
+    # + IRB rather than a server. Every returned record still goes through
+    # `Observability.redact` regardless — no new leak surface isn't the
+    # same guarantee as never printing a secret.
+    #
+    # Each store defaults to its own real `~/.portage/*` file, injectable
+    # (same posture as `Dispatcher`'s own `transaction_log:`/`order_ledger:`/
+    # `journal:` kwargs) so a spec, or a REPL session pointed at a different
+    # machine's exported files, doesn't have to touch the real ones.
+    #
+    # `journal` reads `~/.portage/journal.jsonl` and comes back empty unless
+    # whatever built the `Dispatcher` for your purchases passed a `journal:`
+    # (core's own default is `nil`) — `transactions`/`orders` don't have
+    # that caveat, since `TransactionLog`/`OrderLedger` are Dispatcher's
+    # un-opt-out-able defaults.
+    #
+    # @example
+    #   require "portage/cli/console"
+    #   include Portage::Cli::Console
+    #   transactions(shop: "example.myshopify.com")
+    module Console
+      def transactions(shop: nil, transaction_log: Portage::Ucp::Support::TransactionLog.new)
+        scope(transaction_log.all, shop: shop)
+      end
+
+      def find_transaction(idempotency_key, transaction_log: Portage::Ucp::Support::TransactionLog.new)
+        redact(transaction_log.find(idempotency_key))
+      end
+
+      def transactions_since(since, shop:, transaction_log: Portage::Ucp::Support::TransactionLog.new)
+        redact(transaction_log.completed_since(since, shop: shop))
+      end
+
+      def orders(order_ledger: Portage::Ucp::Support::OrderLedger.new)
+        scope(order_ledger.all)
+      end
+
+      def find_order(order_id, order_ledger: Portage::Ucp::Support::OrderLedger.new)
+        redact(order_ledger.find(order_id))
+      end
+
+      def journal(shop: nil, purchase_journal: Portage::Ucp::Journal::PurchaseJournal.new)
+        scope(purchase_journal.all, shop: shop)
+      end
+
+      private
+
+      def scope(records, shop: nil)
+        records = records.select { |record| record["shop"] == shop } if shop
+        redact(records)
+      end
+
+      def redact(records) = Portage::Ucp::Observability.redact(records)
+    end
+  end
+end

data/lib/portage/cli/doctor.rb

@@ -0,0 +1,91 @@
+require "portage/ucp"
+
+module Portage
+  module Cli
+    # `portage doctor` — sanity-checks a seller's Portage::Ucp setup for the
+    # footguns nothing else catches automatically: an authenticator/rate
+    # limiter left at their fail-safe default (Configuration#initialize),
+    # no signing keys or payment handlers configured, and (when an adapter
+    # class is given) a capability that's only half-implemented — one action
+    # overridden, its siblings still raising Adapter's NotImplementedError.
+    # Runs against whatever `Portage::Ucp.configuration` looks like in this
+    # 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)
+
+      def initialize(adapter_class: nil)
+        @adapter_class = adapter_class
+      end
+
+      def call
+        [
+          authenticator_finding,
+          rate_limiter_finding,
+          signing_keys_finding,
+          payment_handlers_finding,
+          *capability_findings
+        ].compact
+      end
+
+      private
+
+      def config = Portage::Ucp.configuration
+
+      def authenticator_finding
+        return unless config.authenticator.is_a?(Portage::Ucp::UnconfiguredAuthenticator)
+
+        Finding.new(check: "authenticator",
+                    message: "UnconfiguredAuthenticator is still in place — every mutating capability " \
+                             "call is rejected. Set config.authenticator.")
+      end
+
+      def rate_limiter_finding
+        return unless config.rate_limiter.is_a?(Portage::Ucp::NullRateLimiter)
+
+        Finding.new(check: "rate_limiter",
+                    message: "NullRateLimiter is still in place — no rate limiting is applied. " \
+                             "Set config.rate_limiter if that's not intentional.")
+      end
+
+      def signing_keys_finding
+        return unless Array(config.signing_keys).empty?
+
+        Finding.new(check: "signing_keys", message: "No signing_keys configured — the manifest ships unsigned.")
+      end
+
+      def payment_handlers_finding
+        return unless Array(config.payment_handlers).empty?
+
+        Finding.new(check: "payment_handlers",
+                    message: "No payment_handlers configured — buyers can't complete a " \
+                             "payment-enrolled checkout.")
+      end
+
+      # Only action-based capabilities (predicate-based ones like discount/
+      # fulfillment need a live instance to call their predicate method, and
+      # doctor never instantiates an arbitrary adapter — it may need real
+      # credentials to construct).
+      def capability_findings
+        return [] unless @adapter_class
+
+        Portage::Ucp::Capabilities::ALL.filter_map { |capability| partial_capability_finding(capability) }
+      end
+
+      def partial_capability_finding(capability)
+        return if capability.actions.nil? || capability.actions.empty?
+
+        overridden = capability.actions.values.select { |method_name| overridden?(method_name) }
+        return if overridden.empty? || overridden.length == capability.actions.length
+
+        Finding.new(check: "capability:#{capability.name}",
+                    message: "#{capability.name} implements #{overridden.length}/#{capability.actions.length} " \
+                             "actions (#{overridden.join(', ')}) — the rest still raise NotImplementedError.")
+      end
+
+      def overridden?(method_name)
+        @adapter_class.instance_method(method_name).owner != Portage::Ucp::Adapter
+      end
+    end
+  end
+end

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

@@ -0,0 +1,225 @@
+require "fileutils"
+require "portage/ucp"
+
+module Portage
+  module Cli
+    module Generate
+      # `portage generate adapter Foo` — scaffolds a new adapter gem shaped
+      # like the bundled ones (portage-ucp-etsy is the template this follows
+      # most closely: gemspec depending on portage-ucp, Adapter subclass,
+      # conformance spec). Every capability method is stubbed as `= super`,
+      # reflected straight off Portage::Ucp::Adapter's own signatures rather
+      # than hand-copied, so the scaffold can't drift from the real contract
+      # the way a hardcoded template would the next time the contract grows.
+      class Adapter
+        def initialize(name:, dir: nil)
+          @module_name = camelize(name)
+          @slug = underscore(name)
+          @dir = dir || "portage-ucp-#{@slug}"
+        end
+
+        def call
+          FileUtils.mkdir_p(File.join(@dir, "lib", "portage", "ucp", @slug))
+          FileUtils.mkdir_p(File.join(@dir, "spec", "portage", "ucp", @slug))
+          write_gemspec
+          write_gemfile
+          write_rakefile
+          write_rubocop
+          write_lib_entrypoint
+          write_version
+          write_adapter
+          write_spec_helper
+          write_conformance_spec
+          @dir
+        end
+
+        private
+
+        def camelize(str) = str.to_s.split(/[_-]/).map { |w| w[0].upcase + w[1..] }.join
+        def underscore(str) = str.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').tr("-", "_").downcase
+
+        def write(relative_path, content)
+          File.write(File.join(@dir, relative_path), content)
+        end
+
+        def write_gemspec
+          write "#{@dir}.gemspec", <<~RUBY
+            require_relative "lib/portage/ucp/#{@slug}/version"
+
+            Gem::Specification.new do |spec|
+              spec.name = "portage-ucp-#{@slug}"
+              spec.version = Portage::Ucp::#{@module_name}::VERSION
+              spec.summary = "#{@module_name} adapter for portage-ucp"
+              spec.description = "Implements Portage::Ucp::Adapter against #{@module_name}'s API. " \\
+                                 "Generic only — no merchant-specific business logic."
+              spec.authors = ["Tom Whitbread"]
+              spec.license = "MIT"
+              spec.homepage = "https://github.com/tomtom87/Portage/tree/main/#{@dir}"
+              spec.required_ruby_version = ">= 3.2"
+
+              spec.files = Dir["lib/**/*.rb", "README.md", "LICENSE", "CHANGELOG.md"]
+              spec.require_paths = ["lib"]
+
+              spec.add_dependency "portage-ucp", "~> 0.6"
+
+              spec.add_development_dependency "rspec", "~> 3.13"
+              spec.add_development_dependency "rubocop", "~> 1.88"
+              spec.add_development_dependency "webmock", "~> 3.24"
+              spec.metadata["source_code_uri"] = "https://github.com/tomtom87/Portage/tree/main/#{@dir}"
+              spec.metadata["rubygems_mfa_required"] = "true"
+            end
+          RUBY
+        end
+
+        def write_gemfile
+          write "Gemfile", <<~RUBY
+            source "https://rubygems.org"
+
+            gemspec
+
+            gem "portage-ucp", path: "../portage-ucp"
+          RUBY
+        end
+
+        def write_rakefile
+          write "Rakefile", <<~RUBY
+            require "bundler/gem_tasks"
+            require "rspec/core/rake_task"
+
+            RSpec::Core::RakeTask.new(:spec)
+
+            task default: :spec
+          RUBY
+        end
+
+        def write_rubocop
+          write ".rubocop.yml", <<~YAML
+            AllCops:
+              NewCops: enable
+              TargetRubyVersion: 3.2
+              SuggestExtensions: false
+
+            Style/FrozenStringLiteralComment:
+              Enabled: false
+
+            Style/StringLiterals:
+              EnforcedStyle: double_quotes
+
+            Style/Documentation:
+              Enabled: false
+
+            Metrics/BlockLength:
+              Exclude:
+                - "spec/**/*.rb"
+                - "*.gemspec"
+
+            # The scaffolded Adapter subclass is all `= super` stubs until
+            # each one is replaced with a real implementation — rubocop
+            # would otherwise flag every one of them as a useless override.
+            Lint/UselessMethodDefinition:
+              Exclude:
+                - "lib/**/adapter.rb"
+
+            Gemspec/DevelopmentDependencies:
+              Enabled: false
+
+            Gemspec/RequireMFA:
+              Enabled: false
+          YAML
+        end
+
+        def write_lib_entrypoint
+          write "lib/portage/ucp/#{@slug}.rb", <<~RUBY
+            require "portage/ucp"
+            require_relative "#{@slug}/version"
+            require_relative "#{@slug}/adapter"
+          RUBY
+        end
+
+        def write_version
+          write "lib/portage/ucp/#{@slug}/version.rb", <<~RUBY
+            module Portage
+              module Ucp
+                module #{@module_name}
+                  VERSION = "0.1.0".freeze
+                end
+              end
+            end
+          RUBY
+        end
+
+        def write_adapter
+          write "lib/portage/ucp/#{@slug}/adapter.rb", <<~RUBY
+            module Portage
+              module Ucp
+                module #{@module_name}
+                  # TODO: fill in a real client/constructor, then replace each
+                  # `= super` stub below with a real implementation. Leave a
+                  # method as `= super` to leave that capability unadvertised
+                  # (Portage::Ucp::Capability#advertised_for? — see adapter.rb).
+                  class Adapter < Portage::Ucp::Adapter
+            #{adapter_method_stubs}
+                  end
+                end
+              end
+            end
+          RUBY
+        end
+
+        # One `= super` stub per public method Portage::Ucp::Adapter itself
+        # defines, with the same keyword signature — reflected via
+        # Method#parameters rather than hardcoded so this never drifts from
+        # the contract's actual shape.
+        def adapter_method_stubs
+          Portage::Ucp::Adapter.instance_methods(false).sort.filter_map do |name|
+            next if name.to_s.end_with?("_supported?")
+
+            params = Portage::Ucp::Adapter.instance_method(name).parameters
+            "        def #{name}(#{signature(params)}) = super"
+          end.join("\n")
+        end
+
+        def signature(params)
+          params.map do |type, param_name|
+            case type
+            when :keyreq then "#{param_name}:"
+            when :key then "#{param_name}: nil"
+            end
+          end.compact.join(", ")
+        end
+
+        def write_spec_helper
+          write "spec/spec_helper.rb", <<~RUBY
+            require "portage/ucp/#{@slug}"
+            require "webmock/rspec"
+
+            WebMock.disable_net_connect!
+
+            RSpec.configure do |config|
+              config.expect_with(:rspec) { |c| c.syntax = :expect }
+              config.disable_monkey_patching!
+              config.order = :random
+            end
+          RUBY
+        end
+
+        def write_conformance_spec
+          write "spec/portage/ucp/#{@slug}/conformance_spec.rb", <<~RUBY
+            require "spec_helper"
+            require "portage/ucp/rspec"
+
+            RSpec.describe Portage::Ucp::#{@module_name}::Adapter do
+              let(:adapter) { described_class.new }
+              let(:existing_product_id) { "TODO-a-real-catalog-id" }
+
+              # TODO: stub whatever HTTP calls the kit's examples below need —
+              # see portage-ucp-etsy/spec/.../conformance_spec.rb for a worked
+              # example of stubbing just enough for a catalog+checkout adapter.
+              it_behaves_like "a portage adapter"
+            end
+          RUBY
+        end
+      end
+    end
+  end
+end

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.4.1".freeze
+    VERSION = "0.6.0".freeze
   end
 end

data/lib/portage/cli.rb

@@ -9,6 +9,9 @@ require_relative "cli/find"
 require_relative "cli/compare"
 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
@@ -37,23 +40,23 @@ module Portage
                                  [--rolling-cap N --rolling-window-seconds N --currency CUR]
                                  [--velocity-count N --velocity-window-seconds N]
                                  [--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,
+                 "history" => :run_history, "payment" => :run_payment, "policy" => :run_policy,
+                 "doctor" => :run_doctor, "generate" => :run_generate }.freeze
+
     # @param argv [Array<String>]
     # @return [Integer] process exit code
     def self.run(argv)
       command, *rest = argv
-      case command
-      when "buy" then run_buy(rest)
-      when "find" then run_find(rest)
-      when "compare" then run_compare(rest)
-      when "history" then run_history(rest)
-      when "payment" then run_payment(rest)
-      when "policy" then run_policy(rest)
-      else
-        warn USAGE
-        1
-      end
+      return send(COMMANDS[command], rest) if COMMANDS.key?(command)
+
+      warn USAGE
+      1
     end
 
     # --- find ---
@@ -517,6 +520,84 @@ module Portage
     end
     private_class_method :format_payment_enroll
 
+    # --- doctor ---
+
+    def self.parse_doctor_options(argv)
+      opts = {}
+      OptionParser.new do |parser|
+        parser.on("--require FILE") { |v| opts[:require] = v }
+        parser.on("--adapter CLASS_NAME") { |v| opts[:adapter] = v }
+        parser.on("--json") { opts[:json] = true }
+      end.parse!(argv)
+      opts
+    end
+    private_class_method :parse_doctor_options
+
+    def self.run_doctor(argv)
+      opts = parse_doctor_options(argv)
+      require File.expand_path(opts[:require]) if opts[:require]
+      adapter_class = opts[:adapter] && Object.const_get(opts[:adapter])
+
+      findings = Doctor.new(adapter_class: adapter_class).call
+      puts opts[:json] ? JSON.pretty_generate(findings.map(&:to_h)) : format_doctor(findings)
+      findings.empty? ? 0 : 1
+    end
+    private_class_method :run_doctor
+
+    def self.format_doctor(findings)
+      return "No issues found." if findings.empty?
+
+      findings.map { |f| "[#{f.check}] #{f.message}" }.join("\n")
+    end
+    private_class_method :format_doctor
+
+    # --- generate ---
+
+    def self.run_generate(argv)
+      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
+
+      dir = nil
+      OptionParser.new { |parser| parser.on("--dir DIR") { |v| dir = v } }.parse!(rest)
+      path = Generate::Adapter.new(name: name, dir: dir).call
+      puts "Scaffolded #{path}/"
+      0
+    end
+    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 ---
 
     def self.format_report(report)

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: portage-cli
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Tom Whitbread
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-15 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,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        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
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -102,11 +115,13 @@ description: 'Ships the `portage` executable. `portage buy <url>` tries native U
   shopper. `portage find` covers the no-URL case: ask an allowlist, DuckDuckGo, Brave,
   or a Google Programmable Search engine which stores might sell something, keep the
   ones answering /.well-known/ucp, and search their catalogs — documented APIs only,
-  no SERP scraping. Depends on portage-ucp (for platform detection via Resolver) and
-  portage-ucp-client (for the actual buy calls); no single adapter gem is a hard dependency.'
-email:
+  no SERP scraping. Depends on portage-ucp (for platform detection via Resolver),
+  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.'
 executables:
 - portage
+- portage-console
 extensions: []
 extra_rdoc_files: []
 files:
@@ -114,11 +129,16 @@ files:
 - LICENSE
 - README.md
 - exe/portage
+- exe/portage-console
 - lib/portage/cli.rb
 - lib/portage/cli/buy.rb
 - lib/portage/cli/catalog_products.rb
 - lib/portage/cli/compare.rb
+- lib/portage/cli/console.rb
+- 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
@@ -135,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
@@ -150,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: []