portage-cli 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2dda5ce1d230eb5063b5a0a5a576acfce59be4a12abd415f85a0ba6d5d01d6d6
-  data.tar.gz: 4c4732f171e0da0dd8480cd260e1a273e3938ad7b500d3166e86445d2ae7beca
+  metadata.gz: 2a0e9e7e0b7046fc20978a89fb06056bf1827df5efa45c47ddfb0b16f332d53f
+  data.tar.gz: 9ab0f0c9caa507147fae5069dda27c86a92e4c26f273c9cbc14cee8fbfddf368
 SHA512:
-  metadata.gz: 15c3ec9d03069d07adf77b404741867755b24bce9dcbb15ca11005db4344195c1f9cfb741e6340609bcb43b40ea875d8f6c420017132ae98c93d9acca60b45a2
-  data.tar.gz: d9f8dcaee95eaafa9197b313cab7ee70410f1808ad2bf5d4bd722276cd9f7fa7e7074d3080d49723c56e0ba677fa036822bfaa30ebe42471aadce46cfb0fe49d
+  metadata.gz: 247e88dba38ac3171cedccd90d0d1e56ff225cf8aa2526598c3d670391d79fc908fe9fe81735aa71f1c389516ae04c5c71512c61e56bc39802b92bd213d6b40a
+  data.tar.gz: 07d42f21ba32010310394a39a664599c09e840a58cc1be6dd5bcbed7e9d0adf46639364f2bbd70ee70f63fcbfe9407a6d04af9ea75669cc5ae6a5f0f226c5226

data/CHANGELOG.md

@@ -4,7 +4,45 @@ 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.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
+
+- No behavior change — widens the `portage-ucp` dependency pin to `~> 0.6`
+  so this gem can install alongside `portage-ucp` 0.6.0 (the pessimistic
+  `~> 0.5` pin published with 0.4.0 excludes it).
 
 ## [0.4.0] - 2026-09-14
 

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
@@ -127,8 +128,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)

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

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

data/lib/portage/cli.rb

@@ -9,6 +9,8 @@ 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"
 
 module Portage
   # `portage` — the single command-line entrypoint for acting as a shopper's
@@ -37,23 +39,22 @@ 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]
     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 +518,54 @@ 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, name, *rest = argv
+      unless kind == "adapter" && 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
+
     # --- output ---
 
     def self.format_report(report)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portage-cli
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Tom Whitbread
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-14 00:00:00.000000000 Z
+date: 2026-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: portage-ucp
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: portage-ucp-client
   requirement: !ruby/object:Gem::Requirement
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.3'
+- !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 +116,14 @@ 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.'
+  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.'
 email:
 executables:
 - portage
+- portage-console
 extensions: []
 extra_rdoc_files: []
 files:
@@ -114,11 +131,15 @@ 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/history.rb
 - lib/portage/cli/payment_methods.rb
 - lib/portage/cli/payment_methods/env_backend.rb