hecks 3.10.0 → 3.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ab2b4b582c53edd23595354a8db9d84a3a8ec4572d044a77ccfea2ac113c073
-  data.tar.gz: 80af1db86bd574227fc6a03e7d19b9fa1ede9d4fbf54c4934da9211c67a892a2
+  metadata.gz: beba8cd60d4c859286fa1121e3b382cc63e826e010dfd336714befa036dfad94
+  data.tar.gz: 16deb6ba2dd98c8d09385e77a9773f92ef12726d097e71601d2e3cfdbb83ae00
 SHA512:
-  metadata.gz: d28b07fb0b22a96aa8a2dbe2481010c668555a18f256572ee67dc95afb5c517d833cc749718ca804cac68a1ce34e5268e755347ad2d32668ec264d8519d81b08
-  data.tar.gz: 6e823533f842634ad3771ccb994feda57439c9f027aa189e0ff36ba049024fe3c845fd96e3543ce720cb96d6bcaf159604a1279db640f4137ac1e72677d436da
+  metadata.gz: fe730368d2f8942c67a5510c5b8344bdad86f9aa0990515903e147da4fe71fbc6f17880ea2a1b26de4ffa0d24ad20c416455df58ee8a66617e1f832b2637e2b0
+  data.tar.gz: a41080c78fc7b1e9d43347fd4b965d6811c246baee7072214c5f7895564eccc94ce699b86bc739de0f3d7d7830fb8057e6bf2e0699496e201ffd057c7e6a39d5

data/examples/pizzas/bluebook/pizzas.bluebook

@@ -35,6 +35,8 @@ Hecks.bluebook "Pizzas" do
       attribute :value, String, pattern: '[^ \t\n\r]'
 
       invariant("a topping is named") { !value.to_s.empty? }
+      # The pattern lets a form feed through; `.strip` is what sees past it.
+      invariant("a topping name is more than whitespace") { !value.to_s.strip.empty? }
     end
 
     value_object "ToppingAmount" do
@@ -69,6 +71,33 @@ Hecks.bluebook "Pizzas" do
       order_by :name
     end
 
+    # No `where`: every order answers, by identity when nothing orders them.
+    query "Everything" do
+    end
+
+    # Where-less and ordered. Equal prices keep identity order; the nested path reaches the cents.
+    query "ByPrice" do
+      order_by :"pizza.price_cents.cents"
+    end
+
+    query "ByPriceDescending" do
+      order_by :"pizza.price_cents.cents", :desc
+    end
+
+    # `customer_name` is unset until a purchase, so these show where an unset value sorts.
+    query "ByCustomer" do
+      order_by :"customer_name.value"
+    end
+
+    query "ByCustomerDescending" do
+      order_by :"customer_name.value", :desc
+    end
+
+    query "ByCustomerUnsetLast" do
+      order_by :"customer_name.value"
+      nulls :last
+    end
+
     # Both price queries reach through the nested Pizza value object with a dotted path.
     query "CostingLessThan" do
       attribute :ceiling, Price

data/examples/pizzas/bluebook/pizzas.hecksagon

@@ -4,6 +4,13 @@ Hecks.hecksagon "Pizzas" do
   attaches "Governance"
   Pizzas::Order.persisted_by("Memory")
 
+  # Every way in the example is named: the console (Ruby), `hecks run` (Cli), the forms and
+  # storehouse reader (Json) and `hecks mcp` (Mcp). An adapter left out would refuse the domain.
+  driven_by "Ruby"
+  driven_by "Cli"
+  driven_by "Json"
+  driven_by "Mcp"
+
   # The primary port: an outside adapter (a payment webhook) translates an external fact into
   # our vocabulary; business rules stay on Purchase, reached via OnPizzaPaymentReceived.
   Pizzas::Order.port "PaymentGateway" do

data/exe/hecks

@@ -41,19 +41,19 @@ rescue StandardError => e
   abort "cannot open Hecks: #{e.message.lines.first.strip}"
 end
 
-text, status, reason = Hecks::Doors::CliRunner.usage(
+text, status, reason = Hecks::Adapters::Driving::CliRunner.usage(
   runtime: described, argv: ARGV, program: program
 )
 unless text
   runtime = begin
-    Hecks::Doors::LauncherOptions.quietly(hold: MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))) { Hecks.boot_described(described, install_doors: false) }
+    Hecks::Adapters::Driving::LauncherOptions.quietly(hold: MEMORY_COMMANDS.include?(ARGV.first.to_s.chomp("!"))) { Hecks.boot_described(described, install_driving: false) }
   rescue StandardError => e
     abort "cannot open Hecks: #{e.message.lines.first.strip}"
   end
   # A question the world lists under `streams`, given `--stream`, tails until interrupted.
-  streamed = Hecks::Doors::CliRunner.stream(runtime: runtime, argv: ARGV, program: program)
+  streamed = Hecks::Adapters::Driving::CliRunner.stream(runtime: runtime, argv: ARGV, program: program)
   exit streamed unless streamed.nil?
-  text, status, reason = Hecks::Doors::CliRunner.call(
+  text, status, reason = Hecks::Adapters::Driving::CliRunner.call(
     runtime: runtime, argv: ARGV, program: program
   )
 end

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

@@ -42,7 +42,7 @@ module Hecks
         @aggregate = aggregate
         @db = connect(settings)
         # Saga rows are scoped by domain; one D1 database per domain, so aggregates share it.
-        @domain = setting(settings, :domain, aggregate.name).to_s
+        @domain = settings.fetch(:domain) { aggregate.name }.to_s
 
         # No PRAGMA synchronous: D1 is managed and its query endpoint disallows PRAGMA writes.
         create_aggregate_table!
@@ -100,7 +100,7 @@ module Hecks
 
       # The settings are read under a Symbol or a String key; each credential is required.
       def connect(settings)
-        credentials = %w[account_id database_id api_token].to_h { |name| [name, setting(settings, name.to_sym, nil)] }
+        credentials = %w[account_id database_id api_token].to_h { |name| [name, settings[name.to_sym]] }
         credentials.each do |name, value|
           raise Runtime::WiringError, "D1 needs a #{name.inspect} in its world settings" if value.to_s.empty?
         end
@@ -109,14 +109,6 @@ module Hecks
                        api_token: credentials["api_token"])
       end
 
-      # A setting read under its Symbol key, then its String key, then `default`.
-      def setting(settings, key, default)
-        return settings[key] if settings.key?(key)
-        return settings[key.to_s] if settings.key?(key.to_s)
-
-        default
-      end
-
       # The batch's first statement: what the put will do, decided against the current row.
       def status_statement(entry, insert_only)
         outcome = insert_only ? "conflicted" : "replaced"

data/lib/hecks/adapters/driven/heki.adapter

@@ -1,4 +1,4 @@
 Hecks.adapter "Heki" do
   port   "persistence"
-  field  :dir
+  field  :dir, default: "data"
 end

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

@@ -39,7 +39,7 @@ module Hecks
         @journal_path = "#{@path}.journal"
         @events = []
         # Saga scope; falls back to the aggregate's name for a directly built adapter.
-        @domain = setting(settings, :domain, aggregate.name).to_s
+        @domain = settings.fetch(:domain) { aggregate.name }.to_s
         FileUtils.mkdir_p(File.dirname(@path))
       end
 
@@ -179,22 +179,12 @@ module Hecks
         replay_journal(snapshot)
       end
 
-      # `dir: :default` means no setting; a Symbol would make `File.join` raise TypeError.
       def resolve_path(settings, root)
-        declared = setting(settings, :dir, "data")
-        declared = "data" if declared == :default
+        declared = settings[:dir]
         dir      = declared.start_with?("/") ? declared : File.join(root || Dir.pwd, declared)
 
         File.join(dir, "#{@aggregate.storage_name}.heki")
       end
-
-      # A setting read under its Symbol key, then its String key, then `default`.
-      def setting(settings, key, default)
-        return settings[key] if settings.key?(key)
-        return settings[key.to_s] if settings.key?(key.to_s)
-
-        default
-      end
     end
   end
 end

data/lib/hecks/adapters/driven/lambda.adapter

@@ -1,4 +1,4 @@
 Hecks.adapter "Lambda" do
   port "persistence"
-  field :region
+  field :region, default: "us-east-1"
 end

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

@@ -25,10 +25,10 @@ module Hecks
       #   to resolve which function to call; nil falls further back to `domain`
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
-        domain = setting(settings, :domain, aggregate.name)
-        region = setting(settings, :region, "us-east-1")
+        domain = settings.fetch(:domain) { aggregate.name }
+        region = settings[:region]
         # Explicit function name, for deployments whose function is not `hecks-<domain>`.
-        function = setting(settings, :function, nil)
+        function = settings[:function]
         # `domain` only prefixes the instances lookup; the function to call is named by
         # DOMAIN_NAME (set in a deployed Lambda, where root is always /var/task), else by
         # root's basename, which matches hecks deploy recipe.project's stack name on a local boot.
@@ -75,21 +75,6 @@ module Hecks
         Ports::Query::InMemory.execute(instances.values, specification, args)
       end
 
-      # Reads a world setting under either a Symbol or a String key, with a fallback.
-      #
-      # Settings arrive symbol-keyed from the DSL and string-keyed from a round-tripped export.
-      #
-      # @param settings [Hash] the world settings Hash to read from
-      # @param key [Symbol] the setting name, tried as itself and as `key.to_s`
-      # @param fallback [Object] the value to return when neither key is present
-      # @return [Object] the setting's value, or `fallback` when absent
-      def setting(settings, key, fallback)
-        return settings[key] if settings.key?(key)
-        return settings[key.to_s] if settings.key?(key.to_s)
-
-        fallback
-      end
-
       private
 
       # Never memoized: the adapter outlives requests on a warm container, so a cached read

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

@@ -18,6 +18,7 @@ require_relative "postgres/outbox"
 require_relative "postgres/reconnect"
 require_relative "postgres/shared_connection"
 require_relative "../../runtime/instance"
+require_relative "../../indifferent_key"
 
 module Hecks
   module Adapters
@@ -57,7 +58,7 @@ module Hecks
       # @raise [LoadError] if the `pg` gem is not installed
       def self.connect_for(name, settings)
         require_pg(name)
-        declared = settings.key?(:database) ? settings[:database] : settings["database"]
+        declared = IndifferentKey.read(settings, :database)
         refuse_undeclared(name, declared)
         configure(open_connection(declared), settings)
       rescue StandardError => e
@@ -95,7 +96,7 @@ module Hecks
       # PostgresEra's own: a schema/table that already exists is the ordinary case on every
       # boot after the first, not news.
       def self.configure(connection, settings)
-        schema = settings.key?(:schema) ? settings[:schema] : settings["schema"]
+        schema = IndifferentKey.read(settings, :schema)
         connection.exec("SET search_path TO #{connection.quote_ident(schema)}") if schema.to_s != ""
         connection.exec("SET client_min_messages = warning")
         connection
@@ -120,7 +121,7 @@ module Hecks
         @db = PostgresSharedConnection.for(aggregate.name, settings, connector: self.class)
         # Scopes saga rows; falls back to the aggregate's storage name when
         # settings gives no domain (e.g. a directly-instantiated adapter).
-        @domain = setting(settings, :domain, aggregate.storage_name).to_s
+        @domain = settings.fetch(:domain) { aggregate.storage_name }.to_s
         create_tables!
       end
 
@@ -139,14 +140,6 @@ module Hecks
         create_outbox_table!
         create_checkpoint_table!
       end
-
-      # A setting read under its Symbol key, then its String key, then `default`.
-      def setting(settings, key, default)
-        return settings[key] if settings.key?(key)
-        return settings[key.to_s] if settings.key?(key.to_s)
-
-        default
-      end
     end
   end
 end

data/lib/hecks/adapters/driven/sqlite.adapter

@@ -1,6 +1,6 @@
 Hecks.adapter "SqlitePersistence" do
   port   "persistence"
-  field  :database
+  field  :database, default: "data/{storage_name}.db"
 end
 
 Hecks.adapter "SqliteProjection" do

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

@@ -60,7 +60,7 @@ module Hecks
         @aggregate = aggregate
         @path      = resolve_path(settings, root)
         # Scopes saga rows; falls back to the aggregate's name for a directly built adapter.
-        @domain = setting(settings, :domain, aggregate.name).to_s
+        @domain = settings.fetch(:domain) { aggregate.name }.to_s
         open_database
         create_tables!
       end
@@ -106,16 +106,8 @@ module Hecks
         create_checkpoint_table!
       end
 
-      # A setting read under its Symbol key, then its String key, then `default`.
-      def setting(settings, key, default)
-        return settings[key] if settings.key?(key)
-        return settings[key.to_s] if settings.key?(key.to_s)
-
-        default
-      end
-
       def resolve_path(settings, root)
-        declared = setting(settings, :database, "data/#{table}.db")
+        declared = settings[:database]
         return declared if declared.start_with?("/")
 
         File.join(root || Dir.pwd, declared)

data/lib/hecks/adapters/driving/admission.rb

@@ -0,0 +1,46 @@
+require_relative "../../bluebook/hecksagon"
+
+module Hecks
+  module Adapters
+    module Driving
+      # Which driving adapters a hecksagon may name with `driven_by`, and the refusal an adapter
+      # gets from a domain that left it out.
+      #
+      # A domain that declares no `driven_by` is open to every adapter. One that declares any is
+      # reached through those, and each adapter it omits refuses the domain.
+      module Admission
+        # The driving adapters a hecksagon can admit.
+        ADAPTERS = Bluebook::Hecksagon::DRIVING_ADAPTERS
+
+        # Raised by an adapter that a domain's hecksagon left out of `driven_by`.
+        class Refused < StandardError; end
+
+        module_function
+
+        # The sentence a domain gives an adapter it did not admit.
+        #
+        # @param registry [Runtime::Registry] the booted registry, whose hecksagons are asked
+        # @param adapter [String] the adapter reaching in, one of `ADAPTERS`
+        # @return [String, nil] the refusal, or nil when every domain admits `adapter`
+        def refusal(registry, adapter)
+          omitting = registry.hecksagons.values.find { |hecksagon| !hecksagon.driven_by?(adapter) }
+          return unless omitting
+
+          "#{omitting.domain} is not driven by #{adapter}: its hecksagon admits only " \
+            "#{omitting.driving.join(", ")} (driven_by)"
+        end
+
+        # Raises when a domain in `registry` did not admit `adapter`.
+        #
+        # @param registry [Runtime::Registry] the booted registry
+        # @param adapter [String] the adapter reaching in, one of `ADAPTERS`
+        # @return [void]
+        # @raise [Refused] with the domain's sentence
+        def admit!(registry, adapter)
+          sentence = refusal(registry, adapter)
+          raise Refused, sentence if sentence
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/cli/nesting.rb

@@ -0,0 +1,36 @@
+module Hecks
+  module Adapters
+    module Driving
+      module Cli
+        # Sets values into the nested argument Hash a dotted path names, creating the intermediate
+        # Hashes on the way.
+        module Nesting
+          module_function
+
+          # Appends one element to a list argument, creating the list on first use.
+          #
+          # Repeats must grow the list (`bury` would silently keep only the last), and a single
+          # element is still a one-item list, since a `list_of` attribute must never see a bare
+          # object. Multi-field elements are left to `Json`: a flat command line cannot say
+          # which `a.x=` pairs with which `a.y=`.
+          def append(hash, path, value)
+            *branches, leaf = path.map(&:to_sym)
+            holder = branches[0..-2].reduce(hash) { |node, key| node[key] ||= {} }
+            list   = holder[branches.last] ||= []
+
+            list << { leaf => value }
+            hash
+          end
+
+          # Sets one value at a nested path, creating intermediate Hashes and overwriting the leaf.
+          def bury(hash, path, value)
+            *branches, leaf = path.map(&:to_sym)
+            target = branches.reduce(hash) { |node, key| node[key] ||= {} }
+            target[leaf] = value
+            hash
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/cli/shorthand.rb

@@ -0,0 +1,88 @@
+module Hecks
+  module Adapters
+    module Driving
+      module Cli
+        # Rewrites the shorthand spellings of a command line into plain `name=value` words.
+        module Shorthand
+          module_function
+
+          # Rewrites the short forms into `name=value`: `--name` for a Boolean (a following `yes`,
+          # `no`, `true`, `false`, `on`, `off`, `1` or `0` is that flag's value, not an argument),
+          # `--name=value` as `name=value`, and one bare word as the command's first argument
+          # (`to` for a command on an existing aggregate, the first attribute for one that creates).
+          def normalize(spec, words, options)
+            pairs, bare = collect(words, options)
+            raise Runtime::NotFound, too_many_bare(bare) if bare.length > 1
+
+            pairs.map { |pair| bare.include?(pair) && !pair.include?("=") ? positional(pair, spec) : pair }
+          end
+
+          # Every word as a pair, and the words that were neither a flag nor a pair.
+          def collect(words, options)
+            queue = words.dup
+            pairs = []
+            bare  = []
+            until queue.empty?
+              word = queue.shift
+              pairs << pair_for(word, queue, options)
+              bare << word if bare_word?(word)
+            end
+            [pairs, bare]
+          end
+
+          # A word that is neither a `--flag` nor a `name=value` pair.
+          def bare_word?(word)
+            !word.start_with?("--") && !word.include?("=")
+          end
+
+          # One word as a `name=value` pair; a `--flag` takes the Boolean word that follows it from
+          # `queue`.
+          def pair_for(word, queue, options)
+            return word unless word.start_with?("--")
+            return underscored(word.delete_prefix("--"), options) if word.include?("=")
+
+            path  = flag(word.delete_prefix("--"), options)
+            value = BOOLEAN_WORDS.key?(queue.first.to_s.downcase) ? queue.shift : "true"
+            "#{path}=#{value}"
+          end
+
+          # A `name=value` pair whose name is spelled with dashes (`seed-start=3`), as the argument
+          # spelled with underscores, unless an argument is named with the dashes.
+          def underscored(pair, options)
+            name, value = pair.split("=", 2)
+            options.key?(name) ? pair : "#{name.tr("-", "_")}=#{value}"
+          end
+
+          # A `--name` flag, as the path of the Boolean argument it stands for. A dashed name
+          # (`--gem-only`) is the argument spelled with underscores (`gem_only`).
+          def flag(name, options)
+            name = name.tr("-", "_") unless options.key?(name) || options.keys.any? { |key| key.start_with?("#{name}.") }
+            path = options.key?(name) ? name : Cli.expand(name, options)
+            return path if options.dig(path, :type) == "Boolean"
+
+            raise Runtime::NotFound, "--#{name} is a flag, but this command has no Boolean argument #{name.inspect}"
+          end
+
+          # The one bare word, as a pair for the command's first argument the launcher does not
+          # mint.
+          def positional(word, spec)
+            first = spec[:arguments].find { |argument| !argument[:minted] }
+            return "#{first[:path]}=#{word}" if first
+
+            if spec[:arguments].any?
+              raise Runtime::NotFound, "#{word.inspect} is not name=value; this command's only argument is its run " \
+                                       "key, which is minted when omitted (run=<key> names one)"
+            end
+
+            raise Runtime::NotFound, "#{word.inspect} is not name=value, and this command takes no arguments"
+          end
+
+          # Words the refusal for more than one unnamed argument.
+          def too_many_bare(bare)
+            "only one argument may go unnamed, not #{bare.map(&:inspect).join(", ")}; name the rest as name=value"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/cli.rb

@@ -0,0 +1,127 @@
+require_relative "../../runtime/errors"
+
+module Hecks
+  module Adapters
+    module Driving
+      # Turns `path=value` command-line words into a nested, typed argument Hash.
+      # Types come from the projection, never from guessing at the value ("99" may be a String).
+      module Cli
+        # The words a Boolean is spelled with, and what each means.
+        BOOLEAN_WORDS = { "true" => true, "yes" => true, "1" => true, "on" => true,
+                          "false" => false, "no" => false, "0" => false, "off" => false }.freeze
+
+        module_function
+
+        # Builds a command's nested, typed argument Hash from its `name=value` words.
+        #
+        #   arguments(spec, ["reference.value=A-1", "sequence.value=99"])
+        #   # => { reference: { value: "A-1" }, sequence: { value: 99 } }
+        #
+        # @param spec [Hash{Symbol => Object}] one command's entry from `Projector::CliProjector`
+        # @param pairs [Array<String>] the words after the command: `name=value` pairs (a path may
+        #   be the short form of a single-field value object), `--name` for a Boolean, and at most
+        #   one bare word, which fills the first argument
+        # @return [Hash{Symbol => Object}] the arguments nested by path, leaves cast to type
+        # @raise [Runtime::NotFound] if a path, flag or bare word does not fit the command
+        # @raise [Runtime::TypeMismatch] if a value does not parse as its Integer or Float
+        def arguments(spec, pairs)
+          options = declared_options(spec)
+          Shorthand.normalize(spec, pairs, options).each_with_object({}) { |pair, args| store(args, pair, options) }
+        end
+
+        # Every argument the command accepts, by path. Extra accepted arguments stay out of help,
+        # which teaches only to=....
+        def declared_options(spec)
+          (spec[:arguments] + Array(spec[:legacy_arguments])).to_h { |argument| [argument[:path], argument] }
+        end
+
+        # Casts the value of one `name=value` pair and sets it into `args` at its path.
+        def store(args, pair, options)
+          path, value = split(pair)
+          full, argument = declared_argument(path, options)
+          keys = full.split(".")
+          return words(args, keys, value, argument[:type]) if argument[:words]
+          return Nesting.append(args, keys, cast(value, argument[:type])) if argument[:list]
+
+          Nesting.bury(args, keys, cast(value, argument[:type]))
+        end
+
+        # The full path and declaration of the argument `path` names, expanding a value object's
+        # short form. `key?` rather than `||`, so the lookup honors the same spelling `full` chose.
+        def declared_argument(path, options)
+          full = options.key?(path) ? path : expand(path, options)
+          return [full, options[full]] if options.key?(full)
+
+          raise Runtime::NotFound, unknown(path, options.keys)
+        end
+
+        # Cuts one word at its first `=`, so a value may itself contain `=`.
+        def split(pair)
+          name, value = pair.split("=", 2)
+          raise Runtime::NotFound, "#{pair.inspect} is not name=value" if value.nil?
+
+          [name, value]
+        end
+
+        # Expands a bare value-object name into the path of its only field.
+        # Left unchanged when several fields match, since guessing which was meant is worse.
+        def expand(path, options)
+          candidates = options.keys.select { |key| key.start_with?("#{path}.") }
+          candidates.length == 1 ? candidates.first : path
+        end
+
+        # Converts one value to its declared type; only Integer, Float and Boolean convert.
+        def cast(value, type)
+          case type
+          when "Integer" then Integer(value)
+          when "Float"   then Float(value)
+          when "Boolean" then boolean(value)
+          else value
+          end
+        rescue ArgumentError
+          raise Runtime::TypeMismatch, "#{value.inspect} is not #{type} — the chapter declares this field as #{type}"
+        end
+
+        # Reads a Boolean word: `true`, `yes`, `1` or `on` is true; `false`, `no`, `0` or `off` is
+        # false; case does not matter. Anything else is refused, since guessing would turn a typo
+        # (`dry_run=ture`) into a silent false.
+        #
+        # @param value [String] the word
+        # @return [Boolean]
+        # @raise [Runtime::TypeMismatch] if the word is not one of those eight
+        def boolean(value)
+          BOOLEAN_WORDS.fetch(value.to_s.downcase) do
+            raise Runtime::TypeMismatch,
+                  "#{value.inspect} is not Boolean — use true, false, yes, no, 1, 0, on or off"
+          end
+        end
+
+        # Adds the words of a `list_of` scalar argument to its Array: a comma-separated value is
+        # several elements and a repeated name adds more, each cast to the element type. The
+        # runtime refuses a lone scalar for a list, so the adapter is where every spelling becomes
+        # an
+        # Array.
+        #
+        # @param hash [Hash{Symbol => Object}] the arguments built so far
+        # @param path [Array<String>] the argument's dotted path
+        # @param value [String] the word after `=`
+        # @param type [String] the element type
+        # @return [Hash{Symbol => Object}] `hash`
+        def words(hash, path, value, type)
+          *branches, leaf = path.map(&:to_sym)
+          holder = branches.reduce(hash) { |node, key| node[key] ||= {} }
+          list   = holder[leaf] ||= []
+          list.concat(value.split(",").map { |word| cast(word.strip, type) })
+          hash
+        end
+
+        # Words the refusal for an argument the command does not take, listing what it does.
+        def unknown(path, known)
+          "no argument #{path.inspect} — this command takes #{known.sort.join(", ")}"
+        end
+      end
+    end
+  end
+end
+require_relative "cli/nesting"
+require_relative "cli/shorthand"