hecks 6.0.0 → 7.0.0

data/lib/hecks/cli/command_table.rb

@@ -1,72 +0,0 @@
-module Hecks
-  module CLI
-    # One subcommand: a one-line summary, its usage line, the file that holds it and the
-    # call that runs it (given the argv after the name, its program name and its own name).
-    Command = Struct.new(:summary, :usage, :file, :run)
-
-    # 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\":[…]}'>",
-        "cli/run",
-        ->(argv, program, _name) { Run.call(argv, program: program) }
-      ),
-      "docs"             => Command.new(
-        "Print a domain's usage document, projected from its bluebook.",
-        "hecks docs [domain-path] [aggregate]",
-        "cli/document",
-        ->(argv, program, name) { Document.call(argv, projection: name.to_sym, program: program, root: Dir.pwd) }
-      ),
-      "narrate"          => Command.new(
-        "Print a domain read back in English, projected from its bluebook.",
-        "hecks narrate [domain-path] [aggregate]",
-        "cli/document",
-        ->(argv, program, name) { Document.call(argv, projection: name.to_sym, program: program, root: Dir.pwd) }
-      ),
-      "ir"               => Command.new(
-        "Print a booted domain's IR as JSON.",
-        "hecks ir <domain> [--translations] | hecks ir --meta",
-        "cli/ir",
-        ->(argv, program, _name) { Ir.call(argv, program: program) }
-      ),
-      "stores"           => Command.new(
-        "Print every aggregate's current records as JSON.",
-        "hecks stores <domain>",
-        "cli/stores",
-        ->(argv, program, _name) { Stores.call(argv, program: program) }
-      ),
-      "model_check"      => Command.new(
-        "Statically check a domain's IR for dead states and unreachable steps.",
-        "hecks model_check [--strict] [--profile client] [--wait] [<domain> …]",
-        "cli/model_check",
-        ->(argv, program, _name) { ModelCheck.call(argv, program: program, root: checkout_root) }
-      ),
-      "smoke_test"       => Command.new(
-        "Boot a domain and dispatch every declared command and report once.",
-        "hecks smoke_test [domain]",
-        "cli/smoke_test",
-        ->(argv, _program, _name) { SmokeTest.call(argv, root: Dir.pwd) }
-      ),
-      "project_diagrams" => Command.new(
-        "Write a domain's Mermaid diagrams under ./docs/generated/diagrams/ (positional form only).",
-        "hecks project_diagrams <domain-path> <BluebookName>  (writes) | " \
-        "hecks project_diagrams domain=<path> bluebook=<Name>  (prints; writes nothing)",
-        "cli/project_diagrams",
-        ->(argv, program, _name) { ProjectDiagrams.call(argv, program: program, root: Dir.pwd) }
-      ),
-      "project_cli"      => Command.new(
-        "Write a command-line launcher beside each domain, named after its bluebook.",
-        "hecks project_cli [domain-path …]",
-        "cli/project_cli",
-        ->(argv, program, _name) { ProjectCli.call(argv, program: program, root: Dir.pwd, remove_stale_bin: false) }
-      ),
-      "mcp"              => Command.new(
-        "Serve the MCP server over stdio (no authentication; stdio only).",
-        "hecks mcp [--stdio]",
-        "cli/mcp",
-        ->(argv, _program, _name) { Mcp.call(argv) }
-      )
-    }.freeze
-  end
-end

data/lib/hecks/cli/launcher_words.rb

@@ -1,168 +0,0 @@
-module Hecks
-  module CLI
-    # The launcher's `name=value` spellings of a subcommand's arguments, rewritten into the words
-    # the subcommand reads. `CLI` extends it.
-    module LauncherWords
-      # The launcher's flags that mean the same for every subcommand here: `--wait` (a subcommand
-      # exits with its own verdict, so waiting changes nothing) and `--confirm` (nothing here asks
-      # for one). Each may carry a Boolean word, as at the launcher.
-      GENERIC_FLAGS = ["--wait", "--confirm"].freeze
-
-      # A launcher word: `name=value`, where the name has no path characters.
-      NAME_VALUE = /\A[A-Za-z_][\w-]*=/
-
-      # The launcher's `name=value` spellings of a subcommand's positional arguments.
-      #
-      # `slots` lists, in positional order, the names that fill each place (`domain` before
-      # `aggregate`); `many` lets the first slot repeat and take a comma list; `exists` makes
-      # the first slot's values paths that must exist; `flags` and `options` are `--name`
-      # switches and `--name value` pairs; `ignored` names a launcher argument this form has no
-      # use for. A subcommand absent here (`run`, whose pairs are the verb's own, `mcp`, and
-      # `project_diagrams`, whose launcher form answers instead of writing) keeps its words.
-      LAUNCHER_FORMS = {
-        "docs"        => { slots: [%w[domain], %w[aggregate]], exists: true },
-        "narrate"     => { slots: [%w[domain], %w[aggregate]], exists: true },
-        "ir"          => { slots: [%w[domain]], flags: %w[translations meta], exists: true },
-        "stores"      => { slots: [%w[domain]], exists: true },
-        "model_check" => { slots: [%w[domains domain]], many: true, flags: %w[strict],
-                           options: %w[profile], ignored: %w[run] },
-        "smoke_test"  => { slots: [%w[subject domain]], ignored: %w[run] },
-        "project_cli" => { slots: [%w[domain]], many: true }
-      }.freeze
-
-      # Subcommands whose words are their own: `run`'s pairs and `mcp`'s flags are not the
-      # launcher's.
-      UNTOUCHED = %w[run mcp].freeze
-
-      # Subcommands whose `name=value` form is the launcher's own question, which answers
-      # differently from the positional form: `project_diagrams` writes files, the question prints.
-      LAUNCHER_ANSWERS = ["project_diagrams"].freeze
-
-      # Whether a command line is the launcher's own form of a subcommand that answers differently
-      # from its positional form, so the executable leaves it to the launcher.
-      #
-      # @param argv [Array<String>] the command line, subcommand first
-      # @return [Boolean]
-      def launcher_form?(argv)
-        LAUNCHER_ANSWERS.include?(argv.first) && argv.drop(1).any? { |word| word.match?(NAME_VALUE) }
-      end
-
-      # Rewrites the launcher's spellings into the subcommand's own: drops the generic flags and
-      # turns `name=value` words into the positionals and flags the subcommand reads.
-      #
-      # @param name [String] a key of `COMMANDS`
-      # @param rest [Array<String>] the words after the subcommand
-      # @return [Array(Array<String>, String)] the words to run with, and a refusal (nil when
-      #   there is none)
-      def launcher_words(name, rest)
-        return [rest, nil] if UNTOUCHED.include?(name)
-
-        require_relative "../adapters/driving/cli"
-        words = strip_generic(rest)
-        form  = LAUNCHER_FORMS[name]
-        return [words, nil] unless form && words.any? { |word| word.match?(NAME_VALUE) }
-
-        bind_launcher_words(form, words)
-      rescue Runtime::TypeMismatch => e
-        [nil, e.message]
-      end
-
-      # Binds the `name=value` words of `words` into the form's slots and flags.
-      # @api private
-      #
-      # @param form [Hash] an entry of `LAUNCHER_FORMS`
-      # @param words [Array<String>] the words after the subcommand, generic flags removed
-      # @return [Array(Array<String>, String)] the words to run with, and a refusal (nil when
-      #   there is none)
-      def bind_launcher_words(form, words)
-        slots, extra, refusal = bind_named_words(form, words)
-        return [nil, refusal] if refusal
-
-        missing = slots.first.find { |path| !File.exist?(path) } if form[:exists]
-        return [nil, "no such domain #{missing.inspect}"] if missing
-
-        [words.grep_v(NAME_VALUE) + extra + slots.flatten, nil]
-      end
-
-      # Sorts the `name=value` words of `words` into the form's positional slots and its flags.
-      # @api private
-      #
-      # @param form [Hash] an entry of `LAUNCHER_FORMS`
-      # @param words [Array<String>] the words after the subcommand, generic flags removed
-      # @return [Array(Array<Array<String>>, Array<String>, String)] the slot contents, the extra
-      #   flag words, and a refusal (nil when there is none)
-      def bind_named_words(form, words)
-        slots = Array.new(form[:slots].length) { [] }
-        extra = []
-        words.grep(NAME_VALUE).each do |word|
-          refusal = bind_word(form, word, slots, extra)
-          return [nil, nil, refusal] if refusal
-        end
-        [slots, extra, nil]
-      end
-
-      # Files one `name=value` word into its slot, or as a flag or option.
-      # @api private
-      #
-      # @return [String, nil] a refusal when the form takes no such argument
-      def bind_word(form, word, slots, extra)
-        key, value = word.split("=", 2)
-        key  = key.tr("-", "_")
-        slot = form[:slots].index { |names| names.include?(key) }
-        return bind_flag_or_option(form, key, value, extra) unless slot
-
-        slots[slot].concat(form[:many] ? value.split(",") : [value])
-        nil
-      end
-
-      # Appends the flag or option word for one `name=value` into `extra`.
-      # @api private
-      #
-      # @return [String, nil] a refusal when the form takes no such argument
-      def bind_flag_or_option(form, key, value, extra)
-        return add_flag(key, value, extra) if listed?(form, :flags, key)
-        return add_option(key, value, extra) if listed?(form, :options, key)
-        return if listed?(form, :ignored, key)
-
-        known = form[:slots].flatten + Array(form[:flags]) + Array(form[:options])
-        "no argument #{key.inspect} — this verb takes #{known.sort.join(", ")}"
-      end
-
-      # @api private
-      def listed?(form, kind, key) = Array(form[kind]).include?(key)
-
-      # @api private
-      def add_flag(key, value, extra)
-        extra << "--#{key.tr("_", "-")}" if Adapters::Driving::Cli.boolean(value)
-        nil
-      end
-
-      # @api private
-      def add_option(key, value, extra)
-        extra.push("--#{key}", value)
-        nil
-      end
-
-      # Takes `--wait` and `--confirm`, each with an optional Boolean word, out of `words`.
-      # @api private
-      def strip_generic(words)
-        queue = words.dup
-        kept  = []
-        until queue.empty?
-          word = queue.shift
-          flag, value = word.split("=", 2)
-          next kept << word unless GENERIC_FLAGS.include?(flag)
-
-          Adapters::Driving::Cli.boolean(value || generic_value(queue))
-        end
-        kept
-      end
-
-      # The Boolean word that follows a generic flag, or "true" when none does.
-      # @api private
-      def generic_value(queue)
-        Adapters::Driving::Cli::BOOLEAN_WORDS.key?(queue.first.to_s.downcase) ? queue.shift : "true"
-      end
-    end
-  end
-end

data/lib/hecks/cli.rb

@@ -1,133 +0,0 @@
-require_relative "cli/command_table"
-require_relative "cli/launcher_words"
-
-module Hecks
-  # The `hecks` command an installed gem puts on the path: one router over the
-  # domain-operator tools, each also runnable from a checkout as `exe/hecks <name>`.
-  #
-  # Every subcommand's logic lives under `cli/`, and `exe/hecks` routes to it.
-  #
-  # See `docs/decisions/0066-the-gem-ships-a-hecks-executable-and-dev-tooling-stays-in-the-repo.md`.
-  module CLI
-    HELP_FLAGS = ["--help", "-h"].freeze
-
-    # Printed above the usage line by `overview`, on every path that reaches it
-    # (a bare `hecks`, `hecks --help`, and an unknown subcommand alike).
-    HERO = <<~BANNER.freeze
-      #   #  #####   ####  #  #    ####
-      #   #  #      #      # #    #
-      #####  ####   #      ##      ###
-      #   #  #      #      # #        #
-      #   #  #####   ####  #  #   ####
-
-          It's all about the specs
-    BANNER
-
-    # Exit status for a missing or unknown subcommand.
-    USAGE_STATUS = 2
-
-    include LauncherWords
-    extend LauncherWords
-
-    module_function
-
-    # The checkout this library is loaded from, which a corpus sweep needs; an installed gem has
-    # none.
-    #
-    # @return [String, nil] the repository root, or nil when `hecks.gemspec` is not beside `lib/`
-    def checkout_root
-      root = File.expand_path("../..", __dir__)
-      root if File.exist?(File.join(root, "hecks.gemspec"))
-    end
-
-    # Routes `argv` to its subcommand and runs it.
-    #
-    # A subcommand followed only by `--help`/`-h` prints its usage without
-    # running it; other arguments still reach the verb itself.
-    #
-    # @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: 2 for a bad command, 1 for a bad word, the
-    #   subcommand's own Integer when it returns one, else 0; a subcommand that fails exits
-    #   the process itself
-    def start(argv, out: $stdout, err: $stderr)
-      Encoding.default_external = Encoding::UTF_8
-      Encoding.default_internal = Encoding::UTF_8
-      name, *rest = argv
-      return refuse_command(name, out, err) unless COMMANDS.key?(name)
-      return command_help(name, out) if help_asked?(name, rest)
-
-      words, problem = launcher_words(name, rest)
-      return refuse_words(name, problem, err) if problem
-
-      result = dispatch(name, words)
-      result.is_a?(Integer) ? result : 0
-    end
-
-    # Answers an absent or unknown subcommand with the overview.
-    # @api private
-    # @return [Integer] 0 when help was asked for, else the usage status
-    def refuse_command(name, out, err)
-      asked = HELP_FLAGS.include?(name) || name == "help"
-      err.puts "hecks: unknown command #{name.inspect}" unless asked || name.nil?
-      overview(asked ? out : err)
-      asked ? 0 : USAGE_STATUS
-    end
-
-    # Prints one subcommand's usage.
-    # @api private
-    # @return [Integer] 0
-    def command_help(name, out)
-      help(COMMANDS.fetch(name), out)
-      0
-    end
-
-    # Says why a subcommand's words were refused.
-    # @api private
-    # @return [Integer] 1
-    def refuse_words(name, problem, err)
-      err.puts "hecks #{name}: #{problem}"
-      1
-    end
-
-    # Whether the words ask for a subcommand's usage: a lone flag for `run`, whose other words are
-    # the verb's own, and the flag anywhere for the rest.
-    # @api private
-    def help_asked?(name, rest)
-      return rest.length == 1 && HELP_FLAGS.include?(rest.first) if name == "run"
-
-      rest.any? { |word| HELP_FLAGS.include?(word) }
-    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)
-      command = COMMANDS.fetch(name)
-      require_relative command.file
-      command.run.call(argv, "hecks #{name}", name)
-    end
-
-    # @api private
-    def overview(io)
-      io.puts HERO
-      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/hecks/agents.bluebook

@@ -1,246 +0,0 @@
-Hecks.bluebook "Hecks" do
-  # Agents: handing one brief to a background Claude session (ADR 0141). A dispatch is a run like
-  # the Custodian `*Run`s: it is requested, the outside is asked, and what came back is judged by
-  # the givens and reactions below.
-  #
-  # The bluebook decides everything: a brief must say something, an agent name cannot be mistaken
-  # for a flag, the directory must be one the `Agents` port finds, and a session that reports
-  # `done` or `stopped` has finished while `busy` and `idle` have not. The port only looks and
-  # starts: it finds a directory, starts the session, and reports the state the session is in.
-
-  aggregate "AgentRun" do
-    description "One brief handed to a background Claude session: started and tracked, or refused with the reason."
-
-    attribute :run,       RunKey
-    attribute :repo,      Path
-    attribute :brief,     Brief
-    attribute :agent,     AgentName, optional: true
-    attribute :session,   SessionId, optional: true
-    attribute :condition, Condition, optional: true
-    attribute :refusal,   Report,    optional: true
-    attribute :tidied_at, Moment,    optional: true
-    identified_by :run
-
-    value_object "RunKey" do
-      attribute :value, String, matches: :present
-    end
-
-    # The directory the session works in.
-    value_object "Path" do
-      attribute :value, String, matches: :not_empty
-    end
-
-    # What the session is asked to do. It may span lines; the dispatch refuses one that is blank.
-    value_object "Brief" do
-      attribute :value, String
-    end
-
-    # A custom agent's name. It starts with a letter or digit, so it cannot be taken for a flag.
-    value_object "AgentName" do
-      attribute :value, String, pattern: '\A[A-Za-z0-9][A-Za-z0-9._-]*\z'
-    end
-
-    value_object "SessionId" do
-      attribute :value, String, matches: :present
-    end
-
-    # What a session reported about itself the last time it was asked.
-    value_object "Condition" do
-      attribute :value, String
-    end
-
-    value_object "Report" do
-      attribute :value, String
-    end
-
-    # When the outside removed a session, as the port reports it.
-    value_object "Moment" do
-      attribute :value, String
-    end
-
-    lifecycle :status, default: "requested" do
-      mark :failure, "refused"
-      transition "Begin"   => "started",  from: "requested"
-      transition "Decline" => "refused",  from: "requested"
-      transition "Finish"  => "finished", from: "started"
-      transition "Tidied"  => "tidied",   from: "finished"
-      mark :terminal, "tidied", "refused"
-    end
-
-    command "Dispatch" do
-      role "Operator"
-      goal "Hand one brief to a background Claude session working in a directory"
-
-      attribute :run,   RunKey, sets: true
-      attribute :repo,  Path, sets: true
-      attribute :brief, Brief, sets: true
-      attribute :agent, AgentName, optional: true, sets: true
-
-      given("a brief says something") { !brief.value.to_s.strip.empty? }
-
-
-      emits AgentRunRequested
-    end
-
-    command "Begin" do
-      role "System"
-      goal "Record the session the directory's agent started"
-
-      reference_to AgentRun
-      attribute :session, SessionId, sets: true
-
-
-      emits AgentRunStarted
-    end
-
-    command "Decline" do
-      role "System"
-      goal "Record why no session was started"
-
-      reference_to AgentRun
-      attribute :refusal, Report, sets: true
-
-
-      emits AgentRunDeclined
-    end
-
-    command "Check", from: "started" do
-      role "Operator"
-      goal "Ask whether a started session is still working"
-
-      reference_to AgentRun
-
-      emits AgentCheckRequested
-    end
-
-    command "Finish" do
-      role "System"
-      goal "Record that the session has ended, and how it ended"
-
-      reference_to AgentRun
-      attribute :condition, Condition, sets: true
-
-
-      emits AgentRunFinished
-    end
-
-    # A finished run's session is removed only when it ended `done`; a session still `working`,
-    # `blocked` or `stopped` is kept, and so is one a person has taken over (the port says so).
-    command "Tidy", from: "finished" do
-      role "Operator"
-      goal "Remove the finished session of one run, unless it is unfinished or a person took it over"
-
-      reference_to AgentRun
-
-      given("the session ended done: a working, blocked or stopped session is kept") { condition.value == "done" }
-
-      emits TidyRequested
-    end
-
-    command "Tidied" do
-      role "System"
-      goal "Record that the session was removed, and when"
-
-      reference_to AgentRun
-      attribute :tidied_at, Moment, sets: true
-
-
-      emits AgentRunTidied
-    end
-
-    command "Retain" do
-      role "System"
-      goal "Record why a finished session was kept"
-
-      reference_to AgentRun
-      attribute :refusal, Report, sets: true
-
-
-      emits AgentRunRetained
-    end
-
-    query "Tidyable" do
-      description "Every finished run, oldest key first; `Tidy` keeps those that did not end done."
-      where(status: "finished")
-      order_by :run
-    end
-
-    query "Running" do
-      description "Every run whose session was started and is not known to have ended, oldest key first."
-      where(status: "started")
-      order_by :run
-    end
-
-    query "Declined" do
-      description "Every run that no session was started for, with the reason."
-      where(status: "refused")
-      order_by :run
-    end
-  end
-
-  # The directory is looked for first, so a brief is never handed to a session that has nowhere to work.
-  policy "LocateTheRepo" do
-    on      "AgentRun.AgentRunRequested"
-    ask     :locate, with: { run: :run }
-  end
-
-  policy "StartWhenTheRepoIsThere" do
-    on      "AgentRun.RepoLocated"
-    ask     :start, with: { run: :run }
-  end
-
-  policy "RecordTheSession" do
-    on      "AgentRun.AgentStarted"
-    trigger AgentRun::Begin, with: { session: :session }
-  end
-
-  policy "RecordTheMissingRepo" do
-    on      "AgentRun.RepoMissing"
-    trigger AgentRun::Decline, with: { refusal: :refusal }
-  end
-
-  policy "RecordTheRefusedStart" do
-    on      "AgentRun.StartRefused"
-    trigger AgentRun::Decline, with: { refusal: :refusal }
-  end
-
-  policy "AskTheSession" do
-    on      "AgentRun.AgentCheckRequested"
-    ask     :examine, with: { run: :run }
-  end
-
-  # The session is looked at before it is removed; the port says whether a person took it over.
-  policy "ReviewBeforeTidy" do
-    on      "AgentRun.TidyRequested"
-    ask     :review, with: { run: :run }
-  end
-
-  policy "RemoveWhenNobodyTookOver" do
-    on      "AgentRun.SessionReviewed"
-    where   { taken_over == false }
-    ask     :remove, with: { run: :run }
-  end
-
-  policy "KeepWhenAPersonTookOver" do
-    on      "AgentRun.SessionReviewed"
-    where   { taken_over != false }
-    trigger AgentRun::Retain, with: { refusal: :note }
-  end
-
-  policy "RecordTheRemoval" do
-    on      "AgentRun.SessionRemoved"
-    trigger AgentRun::Tidied, with: { tidied_at: :removed_at }
-  end
-
-  policy "RecordTheKeptSession" do
-    on      "AgentRun.RemoveRefused"
-    trigger AgentRun::Retain, with: { refusal: :refusal }
-  end
-
-  # `done` and `stopped` are a session's two ways of ending; `busy` and `idle` are not.
-  policy "FinishWhenTheSessionEnded" do
-    on      "AgentRun.SessionChecked"
-    where   { condition == "done" || condition == "stopped" }
-    trigger AgentRun::Finish, with: { condition: :condition }
-  end
-end