hecks 2.6.0 → 2.8.0

data/lib/hecks/cli/smoke_test.rb

@@ -0,0 +1,59 @@
+require_relative "../../hecks"
+require_relative "../bluebook/smoke_test"
+
+module Hecks
+  module CLI
+    # The command behind `bin/smoke_test` and `hecks smoke_test`: boots a real domain
+    # and dispatches one synthesized call per declared command and report
+    # (`Bluebook::SmokeTest`), printing every failure rather than the first.
+    #
+    # It needs a real `.hecksagon`: a bare `.bluebook` with nothing bound to an
+    # adapter has nothing to run commands against. A failure may be a domain bug or
+    # a value the synthesizer's naive choices (0, an empty list, "smoke-test") cannot
+    # satisfy; the message underneath says which. Smoke-testing proves nothing
+    # crashes, not that an answer is right.
+    module SmokeTest
+      module_function
+
+      # Smoke-tests the domain `argv` names, or every wired domain under
+      # `root/examples/`, and exits with the verdict.
+      #
+      # @param argv [Array<String>] an optional domain directory
+      # @param root [String] the directory whose `examples/*` are tested when `argv`
+      #   names no domain
+      # @return [void]
+      # @raise [SystemExit] always: 0 when clean, 1 with failures or no domain found
+      def call(argv, root:)
+        dir_arg = argv.first
+        targets = dir_arg ? [dir_arg] : Dir.glob("#{root}/examples/*/").map { |d| d.chomp("/") }.select { |d| wired?(d) }
+        abort "no wired example domains found (none of examples/* has a .hecksagon)" if targets.empty?
+
+        ok = targets.reduce(true) { |all_ok, dir| clean?(dir) && all_ok }
+
+        puts
+        puts ok ? "Every declared command and report dispatched cleanly." : "SMOKE TEST FOUND PROBLEMS."
+        exit(ok ? 0 : 1)
+      end
+
+      # Says whether `dir`, or something nested under it, is a bindable domain.
+      #
+      # @param dir [String] a directory to check
+      # @return [Boolean] true if `dir` contains at least one `.hecksagon` file
+      def wired?(dir) = !Dir.glob(File.join(dir, "**/*.hecksagon")).empty?
+
+      # @api private
+      def clean?(dir)
+        puts "── #{File.basename(dir)}"
+        failures = Bluebook::SmokeTest.call(dir)
+        if failures.empty?
+          puts "   clean — every declared command and report dispatched cleanly"
+          return true
+        end
+
+        puts "   #{failures.size} failure(s)"
+        failures.each { |f| puts "     #{f}" }
+        false
+      end
+    end
+  end
+end

data/lib/hecks/cli/stores.rb

@@ -0,0 +1,54 @@
+require "json"
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The command behind `bin/stores` and `hecks stores`: every aggregate's current
+    # records as JSON, the head rather than the journal (`bin/history` prints the
+    # full write history).
+    module Stores
+      module_function
+
+      # Boots the domain `argv` names and prints its stores as one JSON document.
+      #
+      # @param argv [Array<String>] the domain directory, first
+      # @param program [String] the name the error message calls this command by
+      # @return [void]
+      # @raise [IndexError] when `argv` is empty
+      # @raise [SystemExit] when the domain directory does not exist
+      def call(argv, program:)
+        domain = argv.fetch(0)
+        unless Dir.exist?(domain)
+          warn "#{program}: no such domain #{domain.inspect}"
+          exit 1
+        end
+
+        registry = Hecks.boot(domain).registry
+        stores = registry.bluebooks.each_with_object({}) do |(name, bluebook), all|
+          bluebook.aggregates.each do |aggregate|
+            all[aggregate.storage_name] = data_for(registry.repository(name, aggregate))
+          end
+        end
+
+        puts JSON.generate(stores)
+      end
+
+      # Reads one aggregate's current records as plain JSON-ready hashes, ordered by id.
+      #
+      # @param repository [Ports::Persistence::AppendOnly] the aggregate's repository
+      # @return [Array<Hash{String => Object}>] one hash per stored `Runtime::Instance`,
+      #   sorted by id; `[]` when the aggregate has no records
+      def records(repository)
+        repository.all.sort_by(&:id).map { |instance| JSON.parse(JSON.generate(instance.to_h)) }
+      end
+
+      # Shapes one aggregate's dump for the top-level stores document.
+      #
+      # @param repository [Ports::Persistence::AppendOnly] the aggregate's repository
+      # @return [Hash{String => Object}] `"authoritative"` mapped to `records(repository)`
+      def data_for(repository)
+        { "authoritative" => records(repository) }
+      end
+    end
+  end
+end

data/lib/hecks/cli.rb

@@ -0,0 +1,166 @@
+module Hecks
+  # The `hecks` command an installed gem puts on the path: one router over the
+  # domain-operator tools, each of which also runs from a checkout as `bin/<name>`.
+  #
+  # ## A router, not a second copy
+  #
+  # Every subcommand's logic lives in `lib/hecks/cli/`, and the matching `bin/`
+  # script is a thin wrapper over the same entry point, so `hecks run` and
+  # `bin/run` cannot drift apart. The domain-scoped verbs go through
+  # `Facade::CliRunner`, the same way `bin/run` does.
+  #
+  # ## What a checkout has and an install does not
+  #
+  # The `bin/` wrappers pass the repository root, which is where they look for
+  # `examples/`, `rust/` and `docs/generated/`. Here the root is the working
+  # directory, so a command that lists or writes files does it where the caller
+  # stands. `model_check` with no domain sweeps the repository's corpus, which an
+  # install does not carry, so here it needs at least one domain path.
+  #
+  # ## Loading
+  #
+  # Nothing here requires the framework. A subcommand loads it when it runs, and
+  # `mcp` checks its transport before anything else loads, as
+  # `McpStdioGuard.enforce_stdio!` requires.
+  #
+  # See `docs/decisions/0066-the-gem-ships-a-hecks-executable-and-dev-tooling-stays-in-the-repo.md`.
+  module CLI
+    # One subcommand's help: a one-line summary and its usage line.
+    Command = Struct.new(:summary, :usage)
+
+    # Every subcommand, in the order the help lists them.
+    COMMANDS = {
+      "run"              => Command.new(
+        "Dispatch a verb, or run a JSON step list, against a domain.",
+        "hecks run [domain] <verb [name=value …] | script.json | - | '{\"steps\":[…]}'>"
+      ),
+      "docs"             => Command.new(
+        "Print a domain's usage document, projected from its bluebook.",
+        "hecks docs [domain-path] [aggregate]"
+      ),
+      "narrate"          => Command.new(
+        "Print a domain read back in English, projected from its bluebook.",
+        "hecks narrate [domain-path] [aggregate]"
+      ),
+      "ir"               => Command.new(
+        "Print a booted domain's IR as JSON.",
+        "hecks ir <domain> [--translations] | hecks ir --meta"
+      ),
+      "stores"           => Command.new(
+        "Print every aggregate's current records as JSON.",
+        "hecks stores <domain>"
+      ),
+      "model_check"      => Command.new(
+        "Statically check a domain's IR for dead states and unreachable steps.",
+        "hecks model_check [--strict] [--profile client] <domain> [<domain> …]"
+      ),
+      "smoke_test"       => Command.new(
+        "Boot a domain and dispatch every declared command and report once.",
+        "hecks smoke_test [domain]"
+      ),
+      "project_diagrams" => Command.new(
+        "Write a domain's Mermaid diagrams under ./docs/generated/diagrams/.",
+        "hecks project_diagrams <domain-path> <ChapterName>"
+      ),
+      "project_cli"      => Command.new(
+        "Write a command-line launcher beside each domain, named after its bluebook.",
+        "hecks project_cli [domain-path …]"
+      ),
+      "mcp"              => Command.new(
+        "Serve the MCP door over stdio (no authentication; stdio only).",
+        "hecks mcp [--stdio]"
+      )
+    }.freeze
+
+    HELP_FLAGS = ["--help", "-h"].freeze
+
+    # Exit status for a missing or unknown subcommand.
+    USAGE_STATUS = 2
+
+    module_function
+
+    # Routes `argv` to its subcommand and runs it.
+    #
+    # A subcommand followed by only `--help` or `-h` prints that subcommand's usage
+    # without running it; any other arguments pass through untouched, so
+    # `hecks run order.place --help` still reaches the verb's own help.
+    #
+    # @param argv [Array<String>] the command line, subcommand first
+    # @param out [#puts] where help goes
+    # @param err [#puts] where usage errors go
+    # @return [Integer] the process exit status for a subcommand that returns; a
+    #   subcommand that fails exits the process itself
+    def start(argv, out: $stdout, err: $stderr)
+      name, *rest = argv
+      if name.nil? || !COMMANDS.key?(name)
+        asked = HELP_FLAGS.include?(name) || name == "help"
+        err.puts "hecks: unknown command #{name.inspect}" unless asked || name.nil?
+        overview(asked ? out : err)
+        return asked ? 0 : USAGE_STATUS
+      end
+
+      if rest.length == 1 && HELP_FLAGS.include?(rest.first)
+        help(COMMANDS.fetch(name), out)
+      else
+        dispatch(name, rest)
+      end
+      0
+    end
+
+    # Runs one known subcommand with the working directory as its root.
+    #
+    # @param name [String] a key of `COMMANDS`
+    # @param argv [Array<String>] the arguments after the subcommand
+    # @return [void]
+    # @raise [SystemExit] when the subcommand exits the process itself
+    def dispatch(name, argv)
+      program = "hecks #{name}"
+      case name
+      when "run"
+        require_relative "cli/run"
+        Run.call(argv, program: program)
+      when "docs", "narrate"
+        require_relative "cli/document"
+        Document.call(argv, projection: name.to_sym, program: program, root: Dir.pwd)
+      when "ir"
+        require_relative "cli/ir"
+        Ir.call(argv, program: program)
+      when "stores"
+        require_relative "cli/stores"
+        Stores.call(argv, program: program)
+      when "model_check"
+        require_relative "cli/model_check"
+        ModelCheck.call(argv, program: program)
+      when "smoke_test"
+        require_relative "cli/smoke_test"
+        SmokeTest.call(argv, root: Dir.pwd)
+      when "project_diagrams"
+        require_relative "cli/project_diagrams"
+        ProjectDiagrams.call(argv, program: program, root: Dir.pwd)
+      when "project_cli"
+        require_relative "cli/project_cli"
+        ProjectCli.call(argv, program: program, root: Dir.pwd, remove_stale_bin: false)
+      when "mcp"
+        require_relative "cli/mcp"
+        Mcp.call(argv)
+      end
+    end
+
+    # @api private
+    def overview(io)
+      io.puts "usage: hecks <command> [arguments]"
+      io.puts ""
+      width = COMMANDS.keys.map(&:length).max
+      COMMANDS.each { |name, command| io.puts "  #{name.ljust(width)}  #{command.summary}" }
+      io.puts ""
+      io.puts "Run `hecks <command> --help` for one command's usage."
+    end
+
+    # @api private
+    def help(command, io)
+      io.puts "usage: #{command.usage}"
+      io.puts ""
+      io.puts command.summary
+    end
+  end
+end

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