hecks 3.13.0 → 4.0.0

data/lib/hecks/composer/adapters/jev.rb

@@ -0,0 +1,66 @@
+require "json"
+require "open3"
+require "tmpdir"
+
+require_relative "../agent"
+
+module Hecks
+  module Adapters
+    # `composer_agent` fulfillment for `classify` alone: the `jev` categorizer, which answers a
+    # multiple-choice question about a piece of text. It carries no key of its own; the script
+    # reads one from the environment or from 1Password, so nothing secret is written here.
+    #
+    # `draft` and `wire` are not this adapter's work.
+    module Jev
+      QUESTIONS = {
+        "intent" => {
+          "type"         => "choice",
+          "instructions" => "What is the author of a domain bluebook asking an editor to do?",
+          "criteria"     => {
+            "edit"       => "change what the domain declares: an aggregate, command, attribute, rule or lifecycle",
+            "wire"       => "change how the domain is wired to the outside: persistence, adapters, ports, deployment",
+            "question"   => "explain or answer something about the domain, changing nothing",
+            "new_domain" => "start a new domain from a description of a business"
+          }
+        }
+      }.freeze
+
+      module_function
+
+      # @param prompt [String] what the author typed
+      # @return [Hash] `"intent"` one of {Composer::Agent::INTENTS}
+      # @raise [Composer::Agent::Unavailable] if `jev` is missing, fails or answers nothing
+      def classify(prompt:)
+        answers = ask(prompt)
+        { "intent" => choice(answers["intent"]) }
+      end
+
+      # @api private
+      def ask(prompt)
+        Dir.mktmpdir("hecks-jev") { |dir| JSON.parse(run(prompt, File.join(dir, "questions.json"))) }
+      rescue Errno::ENOENT => e
+        raise Composer::Agent::Unavailable, "jev is not on PATH: #{e.message}"
+      rescue JSON::ParserError => e
+        raise Composer::Agent::Unavailable, "jev's answer was not JSON: #{e.message}"
+      end
+
+      # Runs `jev` on the prompt, with the questions written to `path` beside it.
+      # @api private
+      def run(prompt, path)
+        File.write(path, JSON.generate(QUESTIONS))
+        out, err, status = Open3.capture3(ENV.fetch("HECKS_JEV", "jev"), path, "-", stdin_data: prompt)
+        return out if status.success?
+
+        raise Composer::Agent::Unavailable, "jev exited #{status.exitstatus}: #{err.lines.first}"
+      end
+
+      # `jev` names a choice by its key; accept the bare key or a row that carries it.
+      # @api private
+      def choice(answer)
+        return answer unless answer.is_a?(Hash)
+
+        answer.values_at("choice", "answer", "value", "label").compact.first
+      end
+    end
+  end
+end

data/lib/hecks/composer/agent.rb

@@ -0,0 +1,113 @@
+require_relative "../runtime/registry"
+
+module Hecks
+  module Composer
+    # The agent the Composer asks, on the hecksagon side: one port, `composer_agent`, resolved to
+    # the single adapter a registry holds for it. The caller never sees the adapter, only answers
+    # this module has checked, so a spec can stand a scripted adapter in for the real one.
+    #
+    # Two of the asks change the workspace on disk and answer with a note about what changed:
+    # `draft` edits a bluebook, `wire` edits the `.hecksagon` and `.world` files that bind it. The
+    # third, `classify`, only names what a prompt is asking for.
+    module Agent
+      NAME = "composer_agent".freeze
+      PORT = File.expand_path("ports/composer_agent.port", __dir__).freeze
+      ADAPTERS = File.expand_path("adapters", __dir__).freeze
+
+      # What a prompt can be asking for.
+      INTENTS = %w[edit wire question new_domain].freeze
+
+      # The adapter's answer arrived but was unusable; asking again will not help.
+      class ValidationError < StandardError
+      end
+
+      # Nothing answered (missing binary, dead subprocess, timeout); retry or fall back.
+      class Unavailable < StandardError
+      end
+
+      module_function
+
+      # Asks the agent to change a workspace's bluebooks as the prompt says.
+      #
+      # @param registry [Runtime::Registry] a registry holding the port and one adapter for it
+      # @param prompt [String] what the author asked for
+      # @param dir [String] the workspace directory, whose files the agent edits in place
+      # @return [String] the agent's one-line account of what it changed
+      # @raise [ValidationError] unless the answer is a Hash with a non-blank `"note"`
+      # @raise [Unavailable] if the adapter cannot answer
+      # @raise [Runtime::WiringError] unless exactly one adapter implements the port
+      def draft(registry, prompt:, dir:)
+        note(adapter(registry).draft(prompt: prompt, dir: dir))
+      end
+
+      # Asks the agent to change how a workspace's chapter is wired, never what it declares.
+      #
+      # @param registry [Runtime::Registry] a registry holding the port and one adapter for it
+      # @param prompt [String] what the author asked for
+      # @param dir [String] the workspace directory, whose `.hecksagon` and `.world` files the
+      #   agent edits in place
+      # @return [String] the agent's one-line account of what it changed
+      # @raise [ValidationError] unless the answer is a Hash with a non-blank `"note"`
+      # @raise [Unavailable] if the adapter cannot answer
+      def wire(registry, prompt:, dir:)
+        note(adapter(registry).wire(prompt: prompt, dir: dir))
+      end
+
+      # Names what a prompt is asking for.
+      #
+      # @param registry [Runtime::Registry] a registry holding the port and one adapter for it
+      # @param prompt [String] what the author typed
+      # @return [String] one of `Composer::Agent::INTENTS`
+      # @raise [ValidationError] unless the answer is a Hash whose `"intent"` is one of those
+      # @raise [Unavailable] if the adapter cannot answer
+      def classify(registry, prompt:)
+        answer = adapter(registry).classify(prompt: prompt)
+        intent = answer["intent"] if answer.is_a?(Hash)
+        return intent if INTENTS.include?(intent)
+
+        raise ValidationError, "an intent is one of #{INTENTS.join(", ")}, got #{intent.inspect}"
+      end
+
+      # Builds a registry in which exactly one adapter implements the port.
+      #
+      # @param adapter_file [String] the adapter's `.adapter` declaration
+      # @return [Runtime::Registry] a registry holding the port and that adapter
+      def registry_with(adapter_file)
+        registry = Runtime::Registry.new
+        Hecks.with_registry(registry) do
+          Kernel.load(PORT)
+          Kernel.load(adapter_file)
+        end
+        registry
+      end
+
+      # Finds the single adapter bound to the port.
+      #
+      # @param registry [Runtime::Registry] the registry to search
+      # @return [Module] the adapter implementing the port
+      # @raise [Runtime::WiringError] if none, or more than one, implements the port
+      def adapter(registry)
+        implementations = registry.adapters.values.select { |found| found.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
+
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # @api private
+      def note(answer)
+        text = answer["note"].to_s.strip if answer.is_a?(Hash)
+        return text unless text.nil? || text.empty?
+
+        raise ValidationError, "an agent's answer carries a non-blank \"note\", got #{answer.inspect}"
+      end
+
+      # @api private
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can edit the draft" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
+      end
+    end
+  end
+end

data/lib/hecks/composer/assistant.rb

@@ -0,0 +1,110 @@
+require_relative "agent"
+require_relative "check"
+require_relative "layout"
+require_relative "session"
+
+module Hecks
+  module Composer
+    # Carries one request from the author to the agent and back, on the hecksagon side: records it
+    # in the draft's conversation, has the prompt classified, asks the agent to change the
+    # workspace's files, judges what it left, asks once more when the check refused the result, and
+    # records the agent's reply and the verdict.
+    #
+    # The agent edits the workspace on disk, so the files it changes are read before and after to
+    # show the author what moved.
+    class Assistant
+      # How many times the agent may be asked about one request: the request, then a repair.
+      ROUNDS = 2
+
+      QUESTION_NOTE = "That reads as a question, so nothing was edited.".freeze
+
+      # @param workspace [String] the domain directory the agent edits
+      # @param agents [Runtime::Registry] a registry holding the `composer_agent` port and one
+      #   adapter
+      # @param session [Session] the editor's in-memory draft bookkeeping
+      def initialize(workspace:, agents:, session:)
+        @workspace = workspace
+        @agents = agents
+        @session = session
+      end
+
+      # @param prompt [String] what the author asked for
+      # @return [Hash] `intent`, `note` (the agent's one-line account), `rounds` (how many times it
+      #   was asked), `changed` (`{path => {before:, after:}}` for each file that differs), `check`
+      #   (the whole check on what is now on disk) and `layout` (the panels to open, see {Layout})
+      def ask(prompt)
+        slug = File.basename(@workspace)
+        before = snapshot
+        open_draft(slug, before)
+        @session.ask(slug: slug, said: prompt)
+        intent = classify(prompt)
+        note, rounds = edit(intent, prompt)
+        outcome(slug, intent, note, rounds, before)
+      end
+
+      private
+
+      def open_draft(slug, files)
+        chapter = Parse.bluebooks(@workspace).keys.first || "Workspace"
+        @session.open(slug: slug, chapter_name: chapter, text: files.values.first.to_s)
+      end
+
+      # The prompt's intent; a classifier that cannot answer leaves it an edit.
+      def classify(prompt)
+        Agent.classify(@agents, prompt: prompt)
+      rescue Agent::Unavailable
+        "edit"
+      end
+
+      def edit(intent, prompt)
+        return [QUESTION_NOTE, 0] if intent == "question"
+
+        note = ask_agent(intent, prompt)
+        refusal = Check.call(dir: @workspace)[:diagnostic]
+        return [note, 1] unless refusal
+
+        [ask_agent(intent, repair(prompt, refusal)), ROUNDS]
+      end
+
+      def ask_agent(intent, prompt)
+        return Agent.wire(@agents, prompt: prompt, dir: @workspace) if intent == "wire"
+
+        Agent.draft(@agents, prompt: prompt, dir: @workspace)
+      end
+
+      def repair(prompt, refusal)
+        where = refusal[:line] ? "#{refusal[:file]} line #{refusal[:line]}: " : ""
+        expected = refusal[:expected].to_a.empty? ? "" : " (expected one of: #{refusal[:expected].join(", ")})"
+        "#{prompt}\n\nYour last edit was refused by the check, so fix it: #{where}#{refusal[:message]}#{expected}"
+      end
+
+      def outcome(slug, intent, note, rounds, before)
+        after = snapshot
+        check = Check.call(dir: @workspace)
+        @session.answer(slug: slug, said: note, text: after.values.first.to_s)
+        @session.judge(slug: slug, diagnostic: check[:diagnostic])
+        moved = changed(before, after)
+        record(moved)
+        { intent: intent, note: note, rounds: rounds, changed: moved, check: check,
+          layout: Layout.propose(intent: intent, check: check, changed: moved) }
+      end
+
+      # Keeps each file the agent changed in the timeline, as a save would.
+      def record(moved)
+        moved.each { |path, text| @session.record(path: path, text: text[:after]) if text[:after] }
+      end
+
+      def changed(before, after)
+        (before.keys | after.keys).sort.each_with_object({}) do |path, moved|
+          next if before[path] == after[path]
+
+          moved[path] = { before: before[path], after: after[path] }
+        end
+      end
+
+      def snapshot
+        Workspace.files(@workspace).to_h { |path| [path, File.read(File.join(@workspace, path))] }
+      end
+    end
+  end
+end

data/lib/hecks/composer/behavior_run.rb

@@ -0,0 +1,53 @@
+require "hecks"
+require "hecks/behaviors"
+require_relative "workspace"
+
+module Hecks
+  module Composer
+    # Runs a workspace's `.behaviors` files as they stand on screen and reports each test as plain
+    # data. Like the other composer files it sits on the hecksagon side: it stages the text, calls
+    # the behaviors runner and changes nothing on disk.
+    module BehaviorRun
+      module_function
+
+      # @param dir [String] the workspace directory
+      # @param buffers [Hash{String => String}] unsaved text by path relative to `dir`
+      # @return [Hash] `files` (`{path:, parse_error:, runs: [{status:, description:, message:}]}`
+      #   per behaviors file, paths relative to the workspace, status "pass", "fail" or "error")
+      #   and `summary` (`total`, `passed`, `failed`, `errored` and `parse_errors` counts)
+      # @raise [Workspace::OutsideWorkspace] if a buffer's path leaves the workspace
+      def call(dir:, buffers: {})
+        Workspace.stage(dir: dir, buffers: buffers) do |stage|
+          files = Hecks::Behaviors.run_all(stage).files.map { |file| report(stage, file) }
+          { files: files, summary: tally(files) }
+        end
+      end
+
+      # @api private
+      def report(stage, file)
+        {
+          path:        file.path.to_s.delete_prefix("#{File.realpath(stage)}/").delete_prefix("#{stage}/"),
+          parse_error: file.parse_error,
+          runs:        file.runs.map { |run| run_hash(run) }
+        }
+      end
+
+      # @api private
+      def run_hash(run)
+        { status: run.status.to_s, description: run.description, message: run.message }
+      end
+
+      # @api private
+      def tally(files)
+        runs = files.flat_map { |file| file[:runs] }
+        {
+          total:        runs.size,
+          passed:       runs.count { |run| run[:status] == "pass" },
+          failed:       runs.count { |run| run[:status] == "fail" },
+          errored:      runs.count { |run| run[:status] == "error" },
+          parse_errors: files.count { |file| file[:parse_error] }
+        }
+      end
+    end
+  end
+end

data/lib/hecks/composer/bluebook/composer.bluebook

@@ -0,0 +1,178 @@
+# The Composer chapter: a bluebook being written in an editor, by hand or by asking an agent.
+#
+# A Draft is the editor's working copy of one chapter: the text on screen, the conversation that
+# shaped it, and whether the last check of it passed. The files on disk stay the truth; a Draft
+# only holds what is being changed and what was said about it. The check itself (parse, load,
+# project, model-check) and the agent that rewrites the text are the outside, reached through the
+# Composer's hecksagon, so nothing here knows how either is done.
+Hecks.bluebook "Composer" do
+  vision "Write a bluebook in an editor and watch the domain draw itself, with an agent that can change the draft when asked."
+
+  aggregate "Draft" do
+    description "One chapter being edited: its text, the conversation about it, and whether its last check passed."
+
+    attribute :slug,         DraftSlug
+    attribute :chapter_name, ChapterName
+    attribute :text,         SourceText
+    attribute :note,         Note, optional: true
+    attribute :turns,        list_of(Turn)
+
+    identified_by :slug
+
+    value_object "DraftSlug" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a draft is named") { !value.to_s.empty? }
+    end
+
+    # The name a chapter's `Hecks.bluebook "Name"` header declares, which is also the name the
+    # check loads it under.
+    value_object "ChapterName" do
+      attribute :value, String, pattern: '[A-Z][A-Za-z0-9]*'
+
+      invariant("a chapter is named") { !value.to_s.empty? }
+    end
+
+    # What is on screen. A draft may be empty or half-written; the check judges it, not this.
+    value_object "SourceText" do
+      attribute :value, String
+    end
+
+    # The check's last word on the draft, or the agent's one-line account of what it changed.
+    value_object "Note" do
+      attribute :value, String
+    end
+
+    value_object "TurnSequence" do
+      attribute :value, Integer
+
+      invariant("a turn sequence is positive") { value.positive? }
+    end
+
+    value_object "Speaker" do
+      attribute :value, String, one_of: ["author", "agent"]
+    end
+
+    value_object "Utterance" do
+      attribute :value, String
+
+      invariant("a turn says something") { !value.to_s.empty? }
+    end
+
+    # The sequence is supplied by the caller, who already knows how many turns are on screen, so
+    # the order of a conversation is not a fact this chapter invents on write.
+    entity "Turn" do
+      description "One thing said in the conversation about the draft, by the author or by the agent."
+
+      attribute :sequence, TurnSequence
+
+      identified_by :sequence
+
+      attribute :speaker, Speaker
+      attribute :said,    Utterance
+    end
+
+    lifecycle :status, default: "drafting" do
+      transition "Accept" => "valid",    from: %w[drafting valid invalid]
+      transition "Reject" => "invalid",  from: %w[drafting valid invalid]
+      transition "Revise" => "drafting", from: %w[drafting valid invalid]
+    end
+
+    command "Begin" do
+      role "Author"
+      goal "Open a chapter for editing, with the text it starts from"
+
+      attribute :slug,         DraftSlug
+      attribute :chapter_name, ChapterName
+      attribute :text,         SourceText
+
+      sets :slug
+      sets :chapter_name
+      sets :text
+
+      emits "DraftBegun"
+    end
+
+    command "Revise" do
+      role "Author"
+      goal "Replace the draft's text with what is now on screen"
+
+      reference_to Draft
+      attribute :text, SourceText
+
+      sets :text
+
+      emits "DraftRevised"
+    end
+
+    command "Accept" do
+      role "System"
+      goal "Record that the draft's text passed its check"
+
+      reference_to Draft
+      attribute :note, Note
+
+      sets :note
+
+      emits "DraftAccepted"
+    end
+
+    command "Reject" do
+      role "System"
+      goal "Record that the draft's text failed its check, and why"
+
+      reference_to Draft
+      attribute :note, Note
+
+      sets :note
+
+      emits "DraftRejected"
+    end
+
+    command "Ask" do
+      role "Author"
+      goal "Put a request for the agent to the draft's conversation"
+
+      reference_to Draft
+      attribute :sequence, TurnSequence
+      attribute :said,     Utterance
+
+      sets :turns, append: { sequence: :sequence, speaker: { value: "author" }, said: :said }
+
+      emits "TurnAsked"
+    end
+
+    command "Answer" do
+      role "System"
+      goal "Record the agent's reply and the text it left the draft with"
+
+      reference_to Draft
+      attribute :sequence, TurnSequence
+      attribute :said,     Utterance
+      attribute :text,     SourceText
+
+      sets :text
+      sets :turns, append: { sequence: :sequence, speaker: { value: "agent" }, said: :said }
+
+      emits "TurnAnswered"
+    end
+
+    query "Drafting" do
+      description "Every draft still being edited."
+      where(status: "drafting")
+      order_by :slug
+    end
+
+    query "Valid" do
+      description "Every draft whose last check passed."
+      where(status: "valid")
+      order_by :slug
+    end
+
+    query "Invalid" do
+      description "Every draft whose last check failed."
+      where(status: "invalid")
+      order_by :slug
+    end
+  end
+end

data/lib/hecks/composer/bluebook/composer.hecksagon

@@ -0,0 +1,16 @@
+# The Composer domain, bound so it boots standing alone (a fuzz or model_check boot of this
+# directory). Drafts are working state; the files on disk are the truth, so nothing here outlives
+# the process.
+Hecks.hecksagon "Composer" do
+  attaches "Governance"
+  persisted_by "Memory"
+  # The editor reaches this domain through Web, and every tool that boots a corpus domain (fuzz,
+  # model_check, the Composer's own Session) through Ruby; the launcher, the forms and MCP do not.
+  driven_by "Web"
+  driven_by "Ruby"
+end
+
+# The anti-corruption layer for Governance, which the chapter's roles are checked against.
+Hecks.hecksagon "Governance" do
+  persisted_by "Memory"
+end

data/lib/hecks/composer/board.rb

@@ -0,0 +1,65 @@
+module Hecks
+  module Composer
+    # The event-storming board of a chapter, on the hecksagon side: its aggregates with their
+    # commands, the events each command emits, and the policies that make one event trigger another
+    # command. It is read off the booted chapter, so it always shows what the text declares; the
+    # board's own edits go through {BoardEdit}, which rewrites the text.
+    module Board
+      module_function
+
+      # @param chapter [Bluebook::Chapter] the booted chapter
+      # @param outline [Array<Hash>] the text outline (see {Outline}), which says where each note
+      #   is declared
+      # @return [Hash] `aggregates` (each with `name`, `at` and its `commands`, each command with
+      #   `name`, `role`, `goal`, `emits` and `at`) and `policies` (`name`, `on`, `trigger`, `at`),
+      #   where `at` is `{file:, line:}` or nil, and `on` and `trigger` read `Aggregate.Name`
+      def call(chapter, outline:)
+        places = Places.new(outline)
+        { aggregates: chapter.aggregates.map { |aggregate| aggregate_note(aggregate, places) },
+          policies:   chapter.policies.map { |policy| policy_note(policy, places) } }
+      end
+
+      # @api private
+      def aggregate_note(aggregate, places)
+        name = aggregate.hecks_name
+        { name: name, at: places.of("aggregate", name),
+          commands: aggregate.commands.map { |command| command_note(name, command, places) } }
+      end
+
+      # @api private
+      def command_note(owner, command, places)
+        name = command.hecks_name
+        { name: name, role: command.role, goal: command.goal, emits: Array(command.emits).map(&:to_s),
+          at: places.of("command", name, owner: owner) }
+      end
+
+      # @api private
+      def policy_note(policy, places)
+        { name: policy.name, on: policy.on_event, trigger: policy.trigger_command,
+          at: places.of("policy", policy.name) }
+      end
+
+      # Where each declaration sits in the text, found by kind and name, and for a command by the
+      # aggregate that holds it.
+      class Places
+        # @param outline [Array<Hash>] see {Outline}
+        def initialize(outline)
+          owner = nil
+          @entries = outline.map do |entry|
+            owner = entry[:name] if entry[:kind] == "aggregate"
+            entry.merge(owner: entry[:kind] == "command" ? owner : nil)
+          end
+        end
+
+        # @param kind [String] `aggregate`, `command` or `policy`
+        # @param name [String] the declared name
+        # @param owner [String, nil] the aggregate, for a command
+        # @return [Hash, nil] `{file:, line:}` of the first match, or nil when the text has none
+        def of(kind, name, owner: nil)
+          found = @entries.find { |e| e[:kind] == kind && e[:name] == name && e[:owner] == owner }
+          found && { file: found[:file], line: found[:line] }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/composer/board_edit/command_text.rb

@@ -0,0 +1,39 @@
+module Hecks
+  module Composer
+    module BoardEdit
+      # The text of a command the board adds. The first command of an aggregate creates it, setting
+      # the key the aggregate is known by; every later one acts on a record of it. A command with an
+      # event says so on a line of its own.
+      module CommandText
+        module_function
+
+        # @param block [Array<String>] the lines of the aggregate's block, after its declaration
+        # @param indent [Integer] how far the aggregate's declaration is indented
+        # @param aggregate [String] the aggregate's name
+        # @param name [String] the new command's name
+        # @param event [String] the event it emits, or an empty string for none
+        # @return [Array<String>] the command's lines, indented one step inside the aggregate
+        # @raise [Refused] if the aggregate's key cannot be read, for a command that must set it
+        def lines(block:, indent:, aggregate:, name:, event:)
+          pad = " " * (indent + 2)
+          body = acts_on_a_record?(block, indent) ? ["reference_to #{aggregate}"] : creates(block, aggregate)
+          inner = [%(goal "Describe #{name}."), *body, (event.empty? ? nil : "emits #{event}")].compact
+          ["", %(#{pad}command "#{name}" do), *inner.map { |line| "#{pad}  #{line}" }, "#{pad}end"]
+        end
+
+        # @api private
+        def acts_on_a_record?(block, indent) = block.any? { |line| line.match?(/\A {#{indent + 2}}command\s+"/) }
+
+        # The attribute and `sets` that give a new record its key.
+        # @api private
+        def creates(block, aggregate)
+          field = block.filter_map { |line| line[/\A\s*identified_by\s+:(\w+)\s*\z/, 1] }.first
+          type = field && block.filter_map { |line| line[/\A\s*attribute\s+:#{field},\s*([A-Za-z:]+)/, 1] }.first
+          raise Refused, "#{aggregate} has no key the board can read; write its first command in the text" unless type
+
+          ["attribute :#{field}, #{type}", "sets :#{field}"]
+        end
+      end
+    end
+  end
+end