hecks 3.0.5 → 3.1.1

data/lib/hecks/cli/domain_writer.rb

@@ -0,0 +1,39 @@
+require "fileutils"
+
+module Hecks
+  module CLI
+    # Writes the files `hecks init` and `hecks interview` produce, never replacing one (ADR 0087).
+    #
+    # Every target is checked before the first is written, so a refusal leaves nothing half-written.
+    module DomainWriter
+      module_function
+
+      # @param files [Hash{String => String}] each file's path under the target, and its text
+      # @param target [String] the absolute path of the domain directory
+      # @return [Array<String>] the paths written, relative to the target
+      # @raise [ArgumentError] when any file, or a bluebook the files would add, is already there
+      def write!(files, target)
+        taken = taken(files, target)
+        raise ArgumentError, "nothing written; already there: #{taken.join(', ')}" unless taken.empty?
+
+        files.each do |path, text|
+          full = File.join(target, path)
+          FileUtils.mkdir_p(File.dirname(full))
+          File.write(full, text)
+        end
+        files.keys
+      end
+
+      # @param files [Hash{String => String}] the files about to be written
+      # @param target [String] the domain directory
+      # @return [Array<String>] the paths in the way, relative to the target
+      def taken(files, target)
+        taken = files.keys.select { |path| File.exist?(File.join(target, path)) }
+        if files.keys.any? { |path| path.match?(%r{\Abluebook/[^/]+\.bluebook\z}) }
+          taken |= Dir.glob(File.join(target, "bluebook", "*.bluebook")).map { |full| full.delete_prefix("#{target}/") }
+        end
+        taken
+      end
+    end
+  end
+end

data/lib/hecks/cli/interview_agent.rb

@@ -0,0 +1,59 @@
+require_relative "../runtime/registry"
+require_relative "../ports/agent"
+
+module Hecks
+  module CLI
+    # The interviewer an interview session talks to: the agent port, resolved against a registry
+    # that holds one adapter (ADR 0088). The session never sees the adapter, only validated
+    # questions and proposals, so a spec can stand a scripted adapter in for the real one.
+    class InterviewAgent
+      PORT = File.expand_path("../ports/agent.port", __dir__)
+      CLAUDE_CODE = File.expand_path("../adapters/driven/claude_code.adapter", __dir__)
+
+      # The agent a real interview uses: the developer's own `claude`, no key or model of hecks's.
+      #
+      # @return [InterviewAgent] one resolved against the Claude Code adapter
+      def self.claude
+        require_relative "../adapters/driven/claude_code"
+        new(registry_with(CLAUDE_CODE))
+      end
+
+      # @param adapter_files [Array<String>] adapter declarations to load beside the agent port
+      # @return [Runtime::Registry] a registry in which exactly those adapters implement the port
+      def self.registry_with(*adapter_files)
+        registry = Runtime::Registry.new
+        Hecks.with_registry(registry) do
+          Kernel.load(PORT)
+          adapter_files.each { |file| Kernel.load(file) }
+        end
+        registry
+      end
+
+      # @return [Boolean] whether a `claude` executable is on the path, so a model can be tried
+      def self.claude_available?
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, "claude")) }
+      end
+
+      # @param registry [Runtime::Registry] a registry with the agent port and one adapter for it
+      def initialize(registry)
+        @registry = registry
+      end
+
+      # @param state [Hash] the interview so far, as the session describes it
+      # @param asked [Array<String>] the questions already asked
+      # @return [Ports::Agent::Question, nil] the next question, or nil if the adapter offered none
+      # @raise [Ports::Agent::Unavailable, Ports::Agent::ValidationError] when it could not answer
+      def question(state:, asked:)
+        Ports::Agent.ask(@registry, state: state, asked: asked).first
+      end
+
+      # @param prose [String] what the expert just said, as the developer typed it
+      # @param state [Hash] the interview so far
+      # @return [Array<Ports::Agent::Proposal>] the findings the sentence names; none for a question
+      # @raise [Ports::Agent::Unavailable, Ports::Agent::ValidationError] when it could not answer
+      def proposals(prose:, state:)
+        Ports::Agent.interpret(@registry, prose: prose, state: state)
+      end
+    end
+  end
+end

data/lib/hecks/cli/interview_draft.rb

@@ -0,0 +1,246 @@
+require_relative "../naming"
+require_relative "domain_stub"
+
+module Hecks
+  module CLI
+    # Turns an interview's accepted findings into the files of a first domain (ADR 0088).
+    #
+    # Pure: it answers the text of each file and writes none, so the command that runs an interview
+    # can check every target before it writes the first, and a spec can boot the result. It shares
+    # the files around a bluebook with `hecks init` (`DomainStub.support_files`) and renders the
+    # bluebook itself, from what the developer accepted, where `init` writes a fixed stub.
+    #
+    # Only `accepted` findings reach the bluebook; every finding reaches the record. A rule is never
+    # turned into code from prose: it is a comment citing its source, to become a `given` by hand.
+    module InterviewDraft
+      ACCEPTED = "accepted".freeze
+
+      # The pattern every generated string field carries: it refuses a blank value.
+      PATTERN = %q('[^ \t\n\r]').freeze
+
+      # What stands in for a creating command nothing in the interview named.
+      STUB_NOTE = "    # TODO: no action that creates was accepted; replace Create with the real one.".freeze
+      private_constant :PATTERN, :STUB_NOTE
+
+      module_function
+
+      # The files a first interview writes: the bluebook, the files around it, and the record.
+      #
+      # @param interview [Hash] the interview, with at least one accepted thing
+      # @param adapter [String, nil] an adapter in `DomainStub::ADAPTERS`; its default when nil
+      # @return [Hash{String => String}] each file's path under the domain directory, and its text
+      # @raise [ArgumentError] when nothing was accepted, or the subject or adapter is refused
+      def files(interview, adapter: nil)
+        name = interview.fetch(:subject)
+        support = DomainStub.support_files(name: name, adapter: adapter)
+        { "bluebook/#{Naming.snake(name)}.bluebook" => bluebook(interview) }
+          .merge(support)
+          .merge(record_file(interview))
+      end
+
+      # What a later interview writes: its record, ending in the aggregates and commands it would
+      # add, for a developer to merge. An existing domain is never touched (ADR 0088).
+      #
+      # @param interview [Hash] the interview
+      # @return [Hash{String => String}] the one file, `interviews/<reference>.md`
+      def additions(interview)
+        record_file(interview, "\n## Proposed additions\n\nMerge by hand into the domain's bluebook.\n\n" \
+                               "```ruby\n#{fragment(interview)}```\n")
+      end
+
+      # The interview's record: every exchange in order, and every finding with how it was decided.
+      #
+      # @param interview [Hash] the interview
+      # @return [String] Markdown
+      def record(interview)
+        lines = ["# Interview #{interview.fetch(:reference)}: #{interview.fetch(:subject)}", "",
+                 "Expert: #{interview.fetch(:expert)}", "", "## Exchanges", ""]
+        interview.fetch(:exchanges).each_with_index { |ex, i| lines.concat(exchange_lines(ex, i + 1)) }
+        lines << "" << "## Findings" << ""
+        lines.concat(finding_lines(interview))
+        "#{lines.join("\n")}\n"
+      end
+
+      # Reads the plain interview out of an `Interview` record booted from the SME chapter.
+      #
+      # @param interview [Object] the booted record
+      # @return [Hash] the plain interview this module takes: `reference`, `subject`, `expert`,
+      #   `exchanges` (`question`, `answer`, `topic`), and `things`, `actions` and `rules`, each a
+      #   finding with its `number`, `source` and `status` and the fields of its kind
+      def from_record(interview)
+        { reference: plain(interview.reference), subject: plain(interview.subject), expert: plain(interview.expert),
+          exchanges: interview.exchanges.map { |ex| slice(ex, :question, :answer, :topic) },
+          things:    interview.thing_findings.map { |f| slice(f, :number, :name, :identifier, :source, :status) },
+          actions:   interview.action_findings.map { |f| slice(f, :number, :name, :thing, :event, :creates, :source, :status) },
+          rules:     interview.rule_findings.map { |f| slice(f, :number, :statement, :source, :status) } }
+      end
+
+      # @api private
+      def record_file(interview, tail = "")
+        { "interviews/#{file_stem(interview.fetch(:reference))}.md" => record(interview) + tail }
+      end
+
+      # @api private
+      def file_stem(reference) = reference.to_s.gsub(/[^A-Za-z0-9._-]/, "_")
+
+      # @api private
+      def bluebook(interview)
+        name = interview.fetch(:subject)
+        things = accepted(interview, :things)
+        raise ArgumentError, "nothing was accepted: a draft needs at least one thing" if things.empty?
+
+        out = ["Hecks.bluebook #{name.inspect} do"]
+        out.concat(header(interview))
+        out << %(  vision "TODO: say in one sentence what #{name} is for.")
+        out << "  supporting" << ""
+        out.concat(rule_lines(interview))
+        out << fragment(interview).chomp << "end"
+        "#{out.join("\n")}\n"
+      end
+
+      # The aggregates, with their commands: the part a later interview offers to merge.
+      # @api private
+      def fragment(interview)
+        things = accepted(interview, :things)
+        actions = accepted(interview, :actions)
+        placed = things.map { |t| word(t[:name]) }
+        blocks = things.map { |thing| aggregate(interview, thing, actions) }
+        loose = actions.reject { |a| placed.include?(word(a[:thing])) }
+        blocks << unplaced(interview, loose) unless loose.empty?
+        "#{blocks.join("\n\n")}\n"
+      end
+
+      # @api private
+      def header(interview)
+        ["  # Drafted from interview #{interview[:reference]} with #{interview[:expert]}. Each name below cites the",
+         "  # exchange it came from; edit freely."]
+      end
+
+      # @api private
+      def rule_lines(interview)
+        rules = accepted(interview, :rules)
+        return [] if rules.empty?
+
+        ["  # RULES the expert gave, for you to turn into `given` clauses:"] +
+          rules.map { |r| "  #   - #{cite(interview, r)} #{one_line(r[:statement])}" } + [""]
+      end
+
+      # @api private
+      def aggregate(interview, thing, actions)
+        name = word(thing[:name])
+        field = Naming.snake(word(thing[:identifier]))
+        field_type = identifier_type(name, field)
+        mine = actions.select { |a| word(a[:thing]) == name }
+        creating = mine.select { |a| a[:creates] }
+        rest = mine - creating
+        lines = ["  # #{source_note(interview, thing)}".rstrip,
+                 "  aggregate #{name.inspect} do",
+                 "    description #{"TODO: describe what a #{name} is.".inspect}", "",
+                 "    identified_by :#{field}", "",
+                 "    attribute :#{field}, #{field_type}", "",
+                 "    value_object #{field_type.inspect} do",
+                 "      attribute :value, String, pattern: #{PATTERN}",
+                 "    end"]
+        creating = [stub_create(name)] if creating.empty?
+        creating.each { |action| lines.concat(creating_command(interview, action, field, field_type)) }
+        rest.each { |action| lines.concat(mutating_command(interview, action, name)) }
+        (lines << "  end").join("\n")
+      end
+
+      # The creating command nothing in the interview named: a stub, marked for the developer.
+      # @api private
+      def stub_create(name) = { name: "Create", event: "#{name}Created", stub: true }
+
+      # @api private
+      def creating_command(interview, action, field, field_type)
+        verb = word(action[:name])
+        note = action[:stub] ? STUB_NOTE : "    # #{source_note(interview, action)}"
+        ["", note, "    command #{verb.inspect} do", "      goal #{"TODO: say what #{verb} does".inspect}", "",
+         "      attribute :#{field}, #{field_type}", "", "      emits #{word(action[:event]).inspect}", "    end"]
+      end
+
+      # @api private
+      def mutating_command(interview, action, name)
+        verb = word(action[:name])
+        ["", "    # #{source_note(interview, action)}", "    command #{verb.inspect} do",
+         "      goal #{"TODO: say what #{verb} does".inspect}", "", "      reference_to #{name}", "",
+         "      emits #{word(action[:event]).inspect}", "    end"]
+      end
+
+      # An action whose thing nobody accepted has nowhere to go; it is kept as a comment, not lost.
+      # @api private
+      def unplaced(interview, actions)
+        lines = ["  # UNPLACED: these accepted actions name a thing that was not accepted. Place each, or drop it."]
+        actions.each do |action|
+          lines << "  #   - #{cite(interview, action)} #{word(action[:name])} on #{action[:thing]}, announcing #{action[:event]}"
+        end
+        lines.join("\n")
+      end
+
+      # @api private
+      def identifier_type(name, field)
+        type = Naming.pascal(field)
+        type == name ? "#{type}Id" : type
+      end
+
+      # @api private
+      def exchange_lines(exchange, number)
+        lines = ["#{number}. **Q:** #{one_line(exchange[:question])}", "   **A:** #{one_line(exchange[:answer])}"]
+        topic = exchange[:topic].to_s
+        lines << "   _Topic: #{one_line(topic)}_" unless topic.empty?
+        lines
+      end
+
+      # @api private
+      def finding_lines(interview)
+        lines = interview.fetch(:things).map do |f|
+          "- Thing #{f[:number]}, #{f[:status]}: **#{f[:name]}**, identified by `#{f[:identifier]}` (exchange #{f[:source]})"
+        end
+        lines += interview.fetch(:actions).map do |f|
+          creates = f[:creates] ? ", creates it" : ""
+          "- Action #{f[:number]}, #{f[:status]}: **#{f[:name]}** on #{f[:thing]}, " \
+            "announcing `#{f[:event]}`#{creates} (exchange #{f[:source]})"
+        end
+        lines + interview.fetch(:rules).map do |f|
+          "- Rule #{f[:number]}, #{f[:status]}: #{one_line(f[:statement])} (exchange #{f[:source]})"
+        end
+      end
+
+      # @api private
+      def accepted(interview, kind) = interview.fetch(kind).select { |finding| finding[:status] == ACCEPTED }
+
+      # A free-text name as a PascalCase word safe to write into Ruby: `lend a book` is `LendABook`.
+      # @api private
+      def word(text) = text.to_s.split(/[^A-Za-z0-9]+/).reject(&:empty?).map { |part| part.sub(/\A./, &:upcase) }.join
+
+      # @api private
+      def one_line(text) = text.to_s.gsub(/\s+/, " ").strip
+
+      # @api private
+      def cite(interview, finding) = "#{interview[:reference]} ##{finding[:source]}:"
+
+      # Where a name came from: the interview, the exchange, and a short quotation of the answer.
+      # @api private
+      def source_note(interview, finding)
+        exchange = interview.fetch(:exchanges)[finding[:source].to_i - 1]
+        note = "from #{cite(interview, finding)}"
+        return note unless exchange
+
+        text = one_line(exchange[:answer])
+        text = "#{text[0, 77]}..." if text.length > 80
+        "#{note} #{text.inspect}"
+      end
+
+      # @api private
+      def plain(value)
+        return nil if value.nil?
+
+        found = value.respond_to?(:to_h) && !value.is_a?(String) ? value.to_h : value
+        found.is_a?(Hash) && found.key?(:value) ? found[:value] : found
+      end
+
+      # @api private
+      def slice(record, *keys) = keys.to_h { |key| [key, plain(record[key])] }
+    end
+  end
+end

data/lib/hecks/cli/interview_run.rb

@@ -0,0 +1,87 @@
+require_relative "../../hecks"
+require_relative "domain_stub"
+require_relative "domain_writer"
+require_relative "interview_agent"
+require_relative "interview_session"
+
+module Hecks
+  module CLI
+    # The command behind `hecks interview <Name>` (ADR 0088): boots the SME chapter on demand, holds
+    # the interview at the terminal, then writes the first domain, or the next interview's proposed
+    # additions, and says what to type next. Nothing is written unless the interview concludes.
+    module InterviewRun
+      SME = File.expand_path("../sme", __dir__)
+
+      module_function
+
+      # @param name [String] the domain being discovered, as its bluebook will spell it
+      # @param adapter [String, nil] a persistence adapter from `DomainStub::ADAPTERS`
+      # @param dir [String, nil] where the domain goes; the snake-cased name here when nil
+      # @param expert [String, nil] who is interviewed; asked for when nil
+      # @param use_ai [Boolean] false runs the plain prompts (`--no-ai`)
+      # @param input [#gets] where the developer types
+      # @param output [#puts, #print] where the session speaks
+      # @param agent [#question, #proposals, nil] an interviewer to use instead of the real one
+      # @param runtime [Runtime, nil] a booted SME chapter to use instead of booting one
+      # @return [String] the report that was printed, or "" when nothing was written
+      # @raise [ArgumentError] when the name or adapter is refused, or a file would be replaced
+      def call(name:, adapter: nil, dir: nil, expert: nil, use_ai: true, input: $stdin, output: $stdout, agent: nil, runtime: nil)
+        DomainStub.support_files(name: name, adapter: adapter)
+        target = File.expand_path(dir || DomainStub.directory(name), Dir.pwd)
+        expert = who(expert, input, output)
+        result = InterviewSession.new(runtime: runtime || Hecks.boot(SME), agent: interviewer(use_ai, agent, output),
+                                      input: input, output: output, reference: next_reference(target),
+                                      subject: name, expert: expert).call
+        return "" unless result.status == :concluded
+
+        report(target, DomainWriter.write!(files(result.interview, adapter, target), target))
+          .tap { |text| output.puts(text) }
+      end
+
+      # @api private
+      def who(expert, input, output)
+        return expert unless expert.to_s.strip.empty?
+
+        output.print("Who is the expert? ")
+        input.gets.to_s.strip.then { |text| text.empty? ? "the expert" : text }
+      end
+
+      # @api private
+      def interviewer(use_ai, agent, output)
+        return nil unless use_ai
+        return agent if agent
+        return InterviewAgent.claude if InterviewAgent.claude_available?
+
+        output.puts("`claude` is not installed, so this runs without the AI. Use --no-ai to skip this note.")
+        nil
+      end
+
+      # The first interview names a domain; a later one finds a bluebook there and offers additions.
+      # @api private
+      def files(interview, adapter, target)
+        return InterviewDraft.additions(interview) unless Dir.glob(File.join(target, "bluebook", "*.bluebook")).empty?
+
+        InterviewDraft.files(interview, adapter: adapter)
+      end
+
+      # @api private
+      def next_reference(target)
+        "INT-#{Dir.glob(File.join(target, 'interviews', 'INT-*.md')).length + 1}"
+      end
+
+      # @api private
+      def report(target, written)
+        where = target.delete_prefix("#{Dir.pwd}/")
+        lines = ["wrote #{written.length} #{written.length == 1 ? 'file' : 'files'} in #{where}/:"] +
+                written.sort.map { |path| "  #{path}" }
+        lines << "" << "next:"
+        if written.any? { |path| path.start_with?("bluebook/") }
+          lines << "  hecks docs #{where}/bluebook" << "  hecks console subject=#{where}"
+        else
+          lines << "  merge the proposed additions in #{where}/#{written.first} into the domain's bluebook"
+        end
+        lines.join("\n")
+      end
+    end
+  end
+end