hecks 2.6.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2220925ed910b9c63dd34c3fc75448f6cff634a64be3fb67461985d462e83563
-  data.tar.gz: 618319249d19f123171d300578ba8d70556391371457700504c92ba4bd389935
+  metadata.gz: a91dfe0fb86ceb9bb96ecc6b08da680213fed526f49f922f1a2f66d9cb89c80e
+  data.tar.gz: 22fc90a2e361f45e27796248c22391997281e62fbfeec01b25ba35378e6e5681
 SHA512:
-  metadata.gz: a24cd51e0ba290e819645aec45cbc8a55c9978cb1c5fed673180db103a050a77516ebcd224d0102fad523161ce4776866b5702acf790dd0751282c2c399e73a9
-  data.tar.gz: a779523871cd0e81d87c26305bed16e51916723ef544e55ccc30d669b6fdb38b825ee2a05515ae9f8c2f40ff31e4faa57f4d5dffc0dac68146d900d112830d92
+  metadata.gz: 824fd1d23971f6dacfd3c3ea18a35f5d0d61e7f07e2056b789d7be7d105a7bc47d13a61e0391d7aeb46d20bcfe8400e307bf05728ed10f9e4c69b46ac7d0df45
+  data.tar.gz: 3f6e4679c8187f212f913de1d17944c3bac2ed0e4385bcff3bcd259e1b6ccb49d6c8270c7f84885fcc3f308e9ca7def653341050c649d1a048b8a91228ee65e7

data/lib/hecks/adapters/driven/google_authentication.rb

@@ -6,7 +6,7 @@ module Hecks
   module Adapters
     # **Google's own OIDC handshake** — the `authentication` port's one real
     # implementation today. Consolidates what was hand-rolled per-app
-    # (an embryonaut_console `google_auth.rb` did this on its own) into
+    # (a console app's `google_auth.rb` did this on its own) into
     # one adapter, so any hecks-based app gets Google sign-in for free, the
     # same "one adapter, reusable everywhere" value every other adapter
     # in this directory already has.

data/lib/hecks/adapters/driven/lambda/client.rb

@@ -29,7 +29,7 @@ module Hecks
       # exist precisely so a domain whose AWS identity predates a rename
       # keeps targeting the stack that is actually live rather than
       # standing up a second, empty one beside it. A real one:
-      # embryonautfoundersapp deploys as `hecksagain-embryonaut`, and no
+      # a client site deploys under a fixed stack name, and no
       # value of `domain` (or of `DOMAIN_NAME`, the deployed-Lambda
       # override callers already pass) can make this computation produce
       # a name with no dash after "hecks". Every Ruby-side read and

data/lib/hecks/adapters/driven/prism.rb

@@ -72,7 +72,7 @@ module Hecks
         # That's invisible to anything that virtualizes the filesystem at
         # the Ruby level instead of the OS level (e.g. tebako's memfs,
         # which presses a hecks-based app into a single executable —
-        # see domain/README.md's "Deploying" section in lifeadelics for
+        # see domain/README.md's "Deploying" section in a client site's domain for
         # why that matters). ::Prism.parse(File.read(file)) parses the
         # exact same bytes, just read through Ruby's File.read first,
         # which those tools do intercept.

data/lib/hecks/bluebook/dsl/bootstrap_table.rb

@@ -82,6 +82,8 @@ module Hecks
           ["Type", "one_of"] => :one_of_impl,
           ["World", "realm"] => :realm_impl,
           ["World", "latest"] => :latest_impl,
+          ["World", "default_database"] => :default_database_impl,
+          ["World", "default_adapter"] => :default_adapter_impl,
           ["DomainPort", "operation"] => :tells_impl,
           ["DomainPort", "tells"] => :tells_impl,
           ["DomainPort", "asks"] => :asks_impl,

data/lib/hecks/bluebook/dsl/command_builder.rb

@@ -22,7 +22,7 @@ module Hecks
         # same as an absent `to:` and falls through to `from` (also
         # absent), so `then_set :accepted, to: false` raised "names no
         # operation" for the one value most likely to be written that way
-        # (a boolean flip). Confirmed real, live: miette's
+        # (a boolean flip). Confirmed real, live: an external project's
         # dream_interpretation.bluebook (`then_set :accepted, to: false`)
         # and transparency.bluebook (`then_set :always, to: false`). TODO
         # upstream via bin/evolve.
@@ -262,7 +262,7 @@ module Hecks
         # era keeps booting, which is the whole point of the rename column.
         #
         # Vendored addition, not (yet) upstream hecks: `then_set
-        # :target, from: :source_field` (hecks_conception/miette, found
+        # :target, from: :source_field` (an external project, found
         # live in body/doctor/bluebook/doctor.bluebook) -- semantically
         # identical to `to:` (copy this argument/field into the target),
         # different word. TODO upstream via bin/evolve (migration plan
@@ -271,7 +271,7 @@ module Hecks
         #
         # Vendored addition, not (yet) upstream hecks (migration plan
         # task 4, i106 in-DSL math): `multiply:`/`clamp:` -- per-tick organ
-        # math (miette's body/organs/bluebook: strength decays ×0.98,
+        # math (an external project's organ bluebook: strength decays ×0.98,
         # weight/strength clamp to [0, 1]), moved into the bluebook itself
         # from shell-side awk. `multiply:` mirrors
         # increment/decrement's shape exactly (a Numeric amount, applied

data/lib/hecks/bluebook/dsl/port_operation_builder.rb

@@ -34,7 +34,7 @@ module Hecks
         # only external facts with attribute" the refusal message
         # describes) rather than folding `to:` into identity_attribute's
         # existing Reference-attribute scan, which every operation already
-        # in the corpus (Banking, pizzas, lifeadelics' own vendored
+        # in the corpus (Banking, pizzas, a client site's own vendored
         # PaymentGateway) still relies on unchanged.
         #
         # @param name [String] the operation's name

data/lib/hecks/bluebook/dsl/world_builder.rb

@@ -11,8 +11,17 @@ module Hecks
         # Starts with no settings recorded.
         def initialize = @values = {}
 
-        def method_missing(key, *args, &)
-          @values[key.to_sym] = args.size == 1 ? args.first : args
+        # A call with a block records the block's own settings as a nested Hash, so a bind can
+        # group settings (`preview do ... end`); a call without one records its argument.
+        def method_missing(key, *args, &block)
+          @values[key.to_sym] =
+            if block
+              nested = SettingsCollector.new
+              nested.instance_eval(&block)
+              nested.to_h
+            else
+              args.size == 1 ? args.first : args
+            end
         end
 
         def respond_to_missing?(_name, _include_private = false) = true
@@ -96,6 +105,35 @@ module Hecks
           @latest = required(value, "latest version")
         end
 
+        # Names the connection every chapter's database-taking persistence adapter uses
+        # unless that chapter's own world settings name one.
+        #
+        # Answers the `default_database` word through the table's `calls:` column, the
+        # same way `realm_impl` does. A chapter's own
+        # `persisted_by("Adapter") { database ... }` still wins for that adapter.
+        #
+        # @param value [String] the connection, such as a database URL; blankness is
+        #   judged by the world language at `build`, not here
+        # @return [String] the connection as stored
+        def default_database_impl(value)
+          @default_database = required(value, "default database")
+        end
+
+        # Names the persistence adapter every aggregate binds to unless its own chapter's
+        # hecksagon binds it.
+        #
+        # Answers the `default_adapter` word through the table's `calls:` column, the same
+        # way `realm_impl` does. Sits between an explicit bind and the framework's
+        # in-memory fallback; whether the adapter really is a persistence adapter is
+        # judged at boot, where adapters are known.
+        #
+        # @param value [String, Symbol] the adapter's declared name, such as `"PostgresEra"`;
+        #   blankness is judged by the world language at `build`, not here
+        # @return [String] the adapter name as stored
+        def default_adapter_impl(value)
+          @default_adapter = required(value, "default adapter")
+        end
+
         def method_missing(verb, *args, **kwargs, &block)
           result = word_gate_dispatch(verb, args, kwargs, block)
           return result unless result.equal?(WordGate::NOT_ADMITTED)
@@ -134,7 +172,8 @@ module Hecks
         #   as a blank `realm`
         def build
           MetaValidator.call_world(
-            World.new(domain: @domain, realm: @realm, latest: @latest, settings: @settings)
+            World.new(domain: @domain, realm: @realm, latest: @latest, settings: @settings,
+                      default_database: @default_database, default_adapter: @default_adapter)
           )
         end
 

data/lib/hecks/bluebook/hexagon.rb

@@ -97,9 +97,10 @@ module Hecks
       include Hecks::IR
       include Behaviour::World
 
-      emits_ir(domain: :domain, realm: :realm, latest: :latest, settings: :settings)
+      emits_ir(domain: :domain, realm: :realm, latest: :latest, settings: :settings,
+               default_database: :default_database, default_adapter: :default_adapter)
 
-      attr_reader :domain, :realm, :latest, :settings
+      attr_reader :domain, :realm, :latest, :settings, :default_database, :default_adapter
 
       # @param domain [String, Symbol] the domain this world configures
       # @param realm [String, Symbol, nil] the declared realm/version marker, or `nil`
@@ -108,11 +109,18 @@ module Hecks
       #   if none is declared
       # @param settings [Hash] the declared adapter bind settings, keyed by verb and,
       #   for a qualified entry, `"verb:adapter"`
-      def initialize(domain:, realm: nil, latest: nil, settings: {})
-        @domain   = domain.to_s
-        @realm    = realm&.to_s
-        @latest   = latest&.to_s
-        @settings = settings
+      # @param default_database [String, nil] the connection every chapter's
+      #   database-taking persistence adapter uses unless its own settings name one,
+      #   or `nil` if none is declared
+      # @param default_adapter [String, nil] the persistence adapter every aggregate
+      #   binds to unless its chapter's hecksagon binds it, or `nil` if none is declared
+      def initialize(domain:, realm: nil, latest: nil, settings: {}, default_database: nil, default_adapter: nil)
+        @domain           = domain.to_s
+        @realm            = realm&.to_s
+        @latest           = latest&.to_s
+        @settings         = settings
+        @default_database = default_database&.to_s
+        @default_adapter  = default_adapter&.to_s
       end
     end
   end

data/lib/hecks/bluebook/meta_validator/world_judge.rb

@@ -40,7 +40,9 @@ module Hecks
         def judge!
           domain = @world.domain
           send_to("World::World.Declare", domain, domain: v(domain),
-                  realm: v(@world.realm), latest: v(@world.latest))
+                  realm: v(@world.realm), latest: v(@world.latest),
+                  default_database: v(@world.default_database),
+                  default_adapter: v(@world.default_adapter))
 
           Hash(@world.settings).each do |verb, values|
             # the DSL records each binding twice — once by verb, once by

data/lib/hecks/bluebook/model_check.rb

@@ -793,7 +793,7 @@ module Hecks
 
         # **Typo detection, deliberately weaker** — `known_domains` can only
         # ever be a monorepo-scoped heuristic: a real external hecks
-        # consumer's own domain (this repo's own embryonaut/lifeadelics-
+        # consumer's own domain (this repo's own embryonaut client-
         # shaped case) lives in a genuinely separate repository this
         # corpus scan can never see, so a target this check cannot find
         # is "unknown to THIS corpus," never proof of a typo. A target

data/lib/hecks/embryonaut_bluebook/lock.rb

@@ -0,0 +1,72 @@
+require "digest"
+
+module Hecks
+  module EmbryonautBluebook
+    # What a vendored package records about the release it came from:
+    # `vendor/embryonaut_bluebooks/<name>/bluebook.lock`.
+    #
+    # ## File format
+    #
+    # One `key: value` line each for `package`, `version`, `tag`, `commit`
+    # and `digest`, then one `shape: <Domain> <label>` line per domain:
+    #
+    #     package: payments
+    #     version: 1.2.0
+    #     tag: payments-v1.2.0
+    #     commit: <full commit id the tag points at>
+    #     digest: <sha256 of the vendored *.bluebook files>
+    #     shape: Payments d33c23
+    #
+    # The digest is the sha256 of the `<sha256>  <name>` lines of every
+    # top-level `*.bluebook` file, sorted by name. The source repository's own
+    # `bin/bluebook_digest` prints the same number for the tagged release, which
+    # is how a vendored copy is proven to be exactly what it claims to be.
+    Lock = Struct.new(:package, :version, :tag, :commit, :digest, :shape, keyword_init: true) do
+      # Computes the content digest of a directory's `*.bluebook` files.
+      #
+      # @param dir [String] the directory to measure
+      # @return [String, nil] 64 lowercase hex characters, nil when the directory holds
+      #   no bluebook file
+      def self.digest_of(dir)
+        names = Dir.children(dir).select { |name| name.end_with?(".bluebook") }.sort
+        return nil if names.empty?
+
+        lines = names.map { |name| "#{Digest::SHA256.file(File.join(dir, name)).hexdigest}  #{name}\n" }
+        Digest::SHA256.hexdigest(lines.join)
+      end
+
+      # Reads a lock file.
+      #
+      # @param path [String] the `bluebook.lock` path
+      # @return [Lock, nil] the parsed lock, nil when the file does not exist
+      def self.read(path)
+        return nil unless File.file?(path)
+
+        parse(File.read(path))
+      end
+
+      # Parses a lock's text.
+      #
+      # @param text [String] the file's content
+      # @return [Lock] the lock, with `shape` as an Array of lines (empty when none)
+      def self.parse(text)
+        fields = { shape: [] }
+        text.each_line do |line|
+          key, _, value = line.chomp.partition(": ")
+          next if key.empty?
+
+          key == "shape" ? fields[:shape] << value : fields[key.to_sym] = value
+        end
+        new(**fields.slice(*members))
+      end
+
+      # Renders the lock as the text written to `bluebook.lock`.
+      #
+      # @return [String] the lines described above, newline terminated
+      def to_s
+        header = %i[package version tag commit digest].map { |key| "#{key}: #{self[key]}\n" }
+        (header + Array(shape).map { |line| "shape: #{line}\n" }).join
+      end
+    end
+  end
+end

data/lib/hecks/embryonaut_bluebook/shape.rb

@@ -0,0 +1,47 @@
+require_relative "../ports/persistence/plugins/era/storage_shape"
+
+module Hecks
+  module EmbryonautBluebook
+    # The storage-shape labels of a directory of `*.bluebook` files.
+    #
+    # A label is what `PostgresEra` mints an era from, so a vendored package
+    # whose label changed is one whose next deploy mints a new era. This reads
+    # the files the way the era guard reads a held era's text: parse only, no
+    # boot, no wiring, no database, each file loaded into a scratch registry.
+    module Shape
+      module_function
+
+      # Measures every domain a directory's bluebook files declare.
+      #
+      # @param dir [String] a directory holding `*.bluebook` files
+      # @return [Array<String>] one `"<Domain> <label>"` line per domain, sorted by domain name
+      # @raise [Vendoring::Error] if the directory holds no bluebook file, or the files do
+      #   not load, the refusal a boot would raise
+      def labels(dir)
+        files = Dir[File.join(dir, "*.bluebook")]
+        raise Vendoring::Error, "no *.bluebook files in #{dir}" if files.empty?
+
+        load_all(files).bluebooks.sort_by { |name, _| name.to_s }.map do |name, bluebook|
+          "#{name} #{Runtime::StorageShape.mint_label(bluebook)}"
+        end
+      end
+
+      # Loads bluebook files into a registry of their own.
+      #
+      # @param files [Array<String>] absolute bluebook file paths, in load order
+      # @return [Runtime::Registry] the scratch registry holding what the files declared
+      # @raise [Vendoring::Error] if any file fails to load
+      def load_all(files)
+        scratch = Runtime::Registry.new
+        library = Ports::Loading.bootstrap
+        Hecks.with_registry(scratch) do
+          library.load_library
+          files.each { |file| Kernel.load(file) }
+        end
+        scratch
+      rescue StandardError, ScriptError => e
+        raise Vendoring::Error, "the bluebook files do not load: #{e.class}: #{e.message.lines.first.to_s.strip}"
+      end
+    end
+  end
+end

data/lib/hecks/embryonaut_bluebook/vendor.rb

@@ -0,0 +1,194 @@
+require "fileutils"
+require_relative "../vendoring"
+require_relative "lock"
+require_relative "shape"
+
+module Hecks
+  module EmbryonautBluebook
+    # Vendors one package of the bluebook registry into a consuming project.
+    #
+    # ## What it does
+    #
+    # Pins the package's top-level `bluebook/*.bluebook` files from one commit
+    # of a local source repository into
+    # `<root>/vendor/embryonaut_bluebooks/<name>/bluebook/`, where `load!`
+    # resolves them. Only bluebook files are taken: a `.hecksagon`, `.port` or
+    # `.adapter` is a wiring decision for whoever deploys, never part of the
+    # vendored package.
+    #
+    # ## Releases and bare commits
+    #
+    # The source repository tags each release `<name>-v<X.Y.Z>` on a commit
+    # whose `<name>/bluebook.yml` says that version. A release pin (`ref` nil for
+    # the newest tag, `"1.2.0"`, or the tag name) also writes `bluebook.lock`,
+    # which records version, tag, commit, content digest and storage shape, and
+    # holds two refusals, because a production project is bound to `PostgresEra`:
+    #
+    # - a version lower than the vendored one, unless `allow_downgrade`;
+    # - a storage-shape change that does not raise the version by at least a
+    #   minor, so a new era shows in the version number and not only in a hash.
+    #
+    # Any other commit-ish pins that commit and writes only the marker, with no
+    # lock and no version checks. Either way nothing on disk changes when a
+    # pin is refused or its files do not load.
+    class Vendor
+      # A release version, `X.Y.Z`.
+      VERSION = /\A\d+\.\d+\.\d+\z/
+
+      # A package name is a directory name and a bluebook name stem.
+      NAME = /\A[a-z][a-z0-9_]*\z/
+
+      # What a vendoring changed.
+      #
+      # @!attribute [r] previous_version
+      #   @return [String, nil] the version recorded before, nil when there was none
+      # @!attribute [r] previous_shape
+      #   @return [Array<String>, nil] the shape lines measured before, nil when there was
+      #   no earlier copy
+      Result = Struct.new(:package, :commit, :version, :tag, :digest, :shape,
+                          :previous_version, :previous_shape, :dir, keyword_init: true) do
+        # Says whether this was a release pin, which writes a lock.
+        #
+        # @return [Boolean] true for a release, false for a bare commit
+        def release? = !tag.nil?
+
+        # Says whether the storage shape moved since the earlier copy.
+        #
+        # @return [Boolean] true when an earlier copy existed and its shape differs
+        def shape_changed? = !previous_shape.nil? && previous_shape != shape
+      end
+
+      # @param name [String, Symbol] the package's directory name, such as `"payments"`
+      # @param from [String] path of the local source repository
+      # @param ref [String, nil] `X.Y.Z`, a release tag name, any commit-ish, or nil for the
+      #   newest release
+      # @param root [String] the consuming project's root
+      # @param allow_downgrade [Boolean] whether a release older than the vendored one is allowed
+      # @raise [Vendoring::Error] if the name is not a plain package name
+      def initialize(name, from:, root:, ref: nil, allow_downgrade: false)
+        @name = name.to_s
+        raise Vendoring::Error, "#{name.inspect} is not a package name" unless @name.match?(NAME)
+
+        @source = Vendoring::GitSource.new(from)
+        @ref = ref&.to_s
+        @root = root
+        @allow_downgrade = allow_downgrade
+      end
+
+      # Pins the package and reports what changed.
+      #
+      # @return [Result] the commit, version and shape now vendored
+      # @raise [Vendoring::Error] if the release or commit is not found, the tagged commit
+      #   disagrees with its own version, the files do not load, or a refusal above applies
+      def call
+        tag, version = release
+        previous_version, previous_shape = existing
+        shape = nil
+        pin = Vendoring.pin(from: @source.path, ref: tag || @ref, subtree: "#{@name}/bluebook",
+                            into: package_dir, glob: "*.bluebook") do |staged, commit|
+          shape = Shape.labels(staged)
+          next nil unless tag
+
+          refuse_unless_acceptable!(version, previous_version, previous_shape, shape)
+          { "bluebook.lock" => lock(version, tag, commit, staged, shape).to_s }
+        end
+        build_result(pin, tag, version, shape, previous_version, previous_shape)
+      end
+
+      private
+
+      def package_dir = File.join(@root, "vendor", "embryonaut_bluebooks", @name)
+
+      # Resolves what `ref` asks for into a release tag and its version.
+      #
+      # @return [Array(String, String), nil] tag and version for a release, nil for a bare commit
+      def release
+        tag = release_tag
+        return nil unless tag
+
+        version = tag.delete_prefix("#{@name}-v")
+        tagged = @source.read(tag, "#{@name}/bluebook.yml")&.[](/^version: *(\S+)/, 1)
+        unless tagged == version
+          raise Vendoring::Error, "#{tag} points at a commit whose bluebook.yml says version #{tagged.inspect}"
+        end
+
+        [tag, version]
+      end
+
+      def release_tag
+        return newest_release_tag if @ref.nil?
+        return existing_tag("#{@name}-v#{@ref}") if @ref.match?(VERSION)
+
+        @ref.match?(/\A#{Regexp.escape(@name)}-v\d+\.\d+\.\d+\z/) ? existing_tag(@ref) : nil
+      end
+
+      def newest_release_tag
+        tags = release_tags
+        raise Vendoring::Error, "no #{@name}-v* release tag in #{@source.path}" if tags.empty?
+
+        "#{@name}-v#{tags.max_by { |version| Gem::Version.new(version) }}"
+      end
+
+      def existing_tag(tag)
+        return tag if release_tags.include?(tag.delete_prefix("#{@name}-v"))
+
+        raise Vendoring::Error, "no release #{tag} in #{@source.path} (releases: #{release_tags.sort_by do |v|
+          Gem::Version.new(v)
+        end.join(' ')})"
+      end
+
+      def release_tags
+        @source.tags("#{@name}-v*").map { |tag| tag.delete_prefix("#{@name}-v") }.grep(VERSION)
+      end
+
+      # The version and storage shape of what is vendored now, measured from
+      # its files as they stand rather than read back, so a copy vendored before
+      # locks existed still gets a real "before".
+      def existing
+        version = Lock.read(File.join(package_dir, "bluebook.lock"))&.version
+        dir = File.join(package_dir, "bluebook")
+        shape = File.directory?(dir) ? Shape.labels(dir) : nil
+        [version, shape]
+      rescue Vendoring::Error
+        [version, nil]
+      end
+
+      def refuse_unless_acceptable!(version, previous_version, previous_shape, shape)
+        return unless previous_version
+
+        refuse_downgrade!(version, previous_version)
+        return if previous_shape.nil? || previous_shape == shape
+        return if minor_or_more?(previous_version, version)
+
+        raise Vendoring::Error,
+              "#{@name} #{previous_version} -> #{version} changes the storage shape but is only a patch bump " \
+              "(before: #{previous_shape.join(' ')}; after: #{shape.join(' ')}). Raise the package's version " \
+              "by at least a minor in the source repository and release again. Nothing was changed."
+      end
+
+      def refuse_downgrade!(version, previous_version)
+        return if @allow_downgrade || Gem::Version.new(version) >= Gem::Version.new(previous_version)
+
+        raise Vendoring::Error, "#{@name} #{previous_version} is vendored; #{version} is older. " \
+                                "Pass allow_downgrade to do it anyway."
+      end
+
+      def minor_or_more?(old, new)
+        old_major, old_minor = old.split(".").map(&:to_i)
+        new_major, new_minor = new.split(".").map(&:to_i)
+        new_major > old_major || (new_major == old_major && new_minor > old_minor)
+      end
+
+      def lock(version, tag, commit, staged, shape)
+        Lock.new(package: @name, version: version, tag: tag, commit: commit,
+                 digest: Lock.digest_of(staged), shape: shape)
+      end
+
+      def build_result(pin, tag, version, shape, previous_version, previous_shape)
+        Result.new(package: @name, commit: pin.commit, version: version, tag: tag,
+                   digest: Lock.digest_of(pin.dir), shape: shape, dir: pin.dir,
+                   previous_version: previous_version, previous_shape: previous_shape)
+      end
+    end
+  end
+end

data/lib/hecks/embryonaut_bluebook/vendor_cli.rb

@@ -0,0 +1,88 @@
+require "optparse"
+require_relative "vendor"
+
+module Hecks
+  module EmbryonautBluebook
+    # The command line behind `bin/vendor_bluebook`.
+    #
+    # It lives in the gem, not in a script, so a consuming project reaches it
+    # through its own bundle without a copy of the script:
+    #
+    #     bundle exec ruby -rhecks \
+    #       -e 'exit Hecks::EmbryonautBluebook::VendorCli.run(ARGV)' payments@1.2.0
+    #
+    # ## Usage
+    #
+    #     vendor_bluebook <package>[@<version-or-commit>] [--from <path>] [--root <path>]
+    #
+    # `--from` defaults to `$EMBRYONAUT_BLUEBOOKS_SRC` and `--root` to the current
+    # directory. `ALLOW_DOWNGRADE=1` in the environment permits a release older
+    # than the vendored one.
+    module VendorCli
+      USAGE = "usage: vendor_bluebook <package>[@<version-or-commit>] [--from PATH] [--root PATH]".freeze
+
+      # Runs the command and reports on the given streams.
+      #
+      # @param argv [Array<String>] the command-line arguments
+      # @param env [Hash{String => String}] the environment
+      # @param out [IO] where the report goes
+      # @param err [IO] where a refusal goes
+      # @param root [String] the default project root
+      # @return [Integer] the exit status, 0 when the package was vendored
+      def self.run(argv, env: ENV, out: $stdout, err: $stderr, root: Dir.pwd)
+        options = { from: env["EMBRYONAUT_BLUEBOOKS_SRC"], root: root }
+        spec = parse(argv, options)
+        return usage(err) unless spec && options[:from]
+
+        name, _, ref = spec.partition("@")
+        result = Vendor.new(name, from: options[:from], root: options[:root], ref: ref.empty? ? nil : ref,
+                                  allow_downgrade: env["ALLOW_DOWNGRADE"] == "1").call
+        report(result, options[:from], out)
+        0
+      rescue Vendoring::Error, OptionParser::ParseError => e
+        err.puts(e.message)
+        1
+      end
+
+      # Reads the options into a hash and picks out the package argument.
+      #
+      # @param argv [Array<String>] the command-line arguments
+      # @param options [Hash{Symbol => String}] receives `:from` and `:root` when given
+      # @return [String, nil] the one positional argument, nil unless exactly one was given
+      def self.parse(argv, options)
+        parser = OptionParser.new
+        parser.on("--from PATH") { |path| options[:from] = path }
+        parser.on("--root PATH") { |path| options[:root] = path }
+        rest = parser.parse(argv)
+        rest.first if rest.length == 1
+      end
+
+      def self.usage(err)
+        err.puts(USAGE)
+        2
+      end
+
+      def self.report(result, from, out)
+        label = result.release? ? "#{result.version} (#{result.tag}, #{result.commit[0, 7]})" : result.commit[0, 12]
+        out.puts("Vendored embryonaut_bluebooks/#{result.package} #{label} from #{from} into #{result.dir}")
+        out.puts(shape_line(result))
+      end
+
+      # The shape label tells a re-vendor that only moved the pin apart from one
+      # that will mint a new era on the next deploy.
+      def self.shape_line(result)
+        now = result.shape.join(" ")
+        if result.previous_shape.nil?
+          "Shape: #{now} (no earlier vendored copy to compare against)"
+        elsif result.shape_changed?
+          "SHAPE CHANGED: the next deploy mints a new era; add its translation edge first.\n  " \
+            "before: #{result.previous_shape.join(' ')}\n  after:  #{now}"
+        else
+          "Shape unchanged: #{now}. No new era on deploy."
+        end
+      end
+
+      private_class_method :parse, :usage, :report, :shape_line
+    end
+  end
+end