hecks 3.14.0 → 5.0.0

data/lib/hecks/composer/web.rb

@@ -0,0 +1,156 @@
+require "json"
+require "rack"
+require_relative "../composer"
+require_relative "domains"
+require_relative "workbench"
+
+module Hecks
+  module Composer
+    # The Composer's driving side, on the hecksagon side: a Rack app that serves the editor page
+    # and the JSON routes it speaks to, over one workspace directory at a time. It binds no
+    # business meaning. The routes are the tables below: the page and files, the editor's own
+    # (save, remove, parse, check, ask), the domain list, and the lower panels', which {Panels}
+    # answers.
+    class Web
+      PAGE = File.expand_path("page.html", __dir__).freeze
+      PREFIX = "/composer".freeze
+
+      # @param workspace [String] the domain directory the editor opens
+      # @param agents [Runtime::Registry, nil] see {Workbench#initialize}
+      # @param root [String] the checkout whose domains the picker lists
+      # @return [Web] a Rack app
+      def self.app(workspace:, agents: nil, root: Parse::ROOT) = new(workspace: workspace, agents: agents, root: root)
+
+      # @param workspace [String] the domain directory the editor opens
+      # @param agents [Runtime::Registry, nil] see {Workbench#initialize}
+      # @param root [String] the checkout whose domains the picker lists
+      def initialize(workspace:, agents: nil, root: Parse::ROOT)
+        @agents = agents
+        @root = File.expand_path(root)
+        @bench = Workbench.new(workspace: workspace, agents: agents)
+      end
+
+      # @param env [Hash] the Rack environment
+      # @return [Array] the Rack response triple
+      def call(env)
+        request = Rack::Request.new(env)
+        route(request)
+      rescue Workspace::OutsideWorkspace, KeyError, JSON::ParserError => e
+        json(400, error: e.message)
+      rescue Domains::Unknown => e
+        json(404, error: e.message)
+      rescue Parse::ParserMissing => e
+        json(503, error: e.message)
+      end
+
+      private
+
+      # Routes that answer from the workspace alone, those that read a JSON body first, and those
+      # the lower panels ask (answered by {Panels}).
+      READS = { "GET " => :page, "GET #{PREFIX}" => :page, "GET #{PREFIX}/files" => :listing,
+                "GET #{PREFIX}/draft" => :conversation, "GET #{PREFIX}/domains" => :domains }.freeze
+      WRITES = { "PUT #{PREFIX}/file" => :save, "DELETE #{PREFIX}/file" => :remove,
+                 "POST #{PREFIX}/parse" => :parse, "POST #{PREFIX}/check" => :check,
+                 "POST #{PREFIX}/ask" => :ask, "POST #{PREFIX}/open" => :open_domain }.freeze
+      PANEL_ROUTES = { "POST #{PREFIX}/live/commands" => :commands, "POST #{PREFIX}/live/dispatch" => :dispatch,
+                       "POST #{PREFIX}/live/records" => :records, "POST #{PREFIX}/behaviors" => :behaviors,
+                       "POST #{PREFIX}/timeline" => :timeline, "POST #{PREFIX}/board/edit" => :board_edit,
+                       "GET #{PREFIX}/catalog" => :catalog,
+                       "POST #{PREFIX}/help" => :help, "POST #{PREFIX}/run" => :run,
+                       "GET #{PREFIX}/eras" => :eras, "POST #{PREFIX}/job" => :start_job,
+                       "GET #{PREFIX}/job" => :job_state, "DELETE #{PREFIX}/job" => :cancel_job }.freeze
+      private_constant :READS, :WRITES, :PANEL_ROUTES
+
+      def route(request)
+        key = "#{request.request_method} #{request.path_info.chomp("/")}"
+        answer_for(key, request) || json(404, error: "no such route")
+      end
+
+      # The response the key's table gives, or nil when no table has the key.
+      def answer_for(key, request)
+        return send(READS[key]) if READS.key?(key)
+        return send(WRITES[key], body(request)) if WRITES.key?(key)
+
+        json(200, @bench.panels.public_send(PANEL_ROUTES[key], body(request))) if PANEL_ROUTES.key?(key)
+      end
+
+      def workspace = @bench.workspace
+
+      def listing = json(200, files: files)
+
+      def conversation = json(200, draft: @bench.session.summary(@bench.slug))
+
+      # The known domains, and the directory the editor has open now.
+      def domains = json(200, domains: Domains.known(root: @root), current: File.basename(workspace))
+
+      # Opens a known domain as a scratch copy, replacing everything kept for the old workspace.
+      def open_domain(body)
+        id = body.fetch("id")
+        opened = Domains.open(root: @root, id: id)
+        @bench.close
+        @bench = Workbench.new(workspace: opened, agents: @agents)
+        json(200, opened: id, current: File.basename(opened))
+      end
+
+      def ask(body)
+        json(200, @bench.assistant.ask(body.fetch("prompt")))
+      rescue Agent::Unavailable => e
+        json(503, error: e.message)
+      rescue Agent::ValidationError => e
+        json(502, error: e.message)
+      end
+
+      def page = [200, { "content-type" => "text/html; charset=utf-8" }, [File.read(PAGE)]]
+
+      def files
+        Workspace.files(workspace).map { |path| { path: path, text: File.read(File.join(workspace, path)) } }
+      end
+
+      def save(body)
+        path = domain_path(body) or return refused(body)
+
+        target = File.join(workspace, path)
+        FileUtils.mkdir_p(File.dirname(target))
+        File.write(target, body.fetch("text"))
+        @bench.session.record(path: path, text: body.fetch("text"))
+        json(200, saved: path)
+      end
+
+      def remove(body)
+        path = domain_path(body) or return refused(body)
+
+        FileUtils.rm_f(File.join(workspace, path))
+        json(200, removed: path)
+      end
+
+      # The request's path when it names a domain file inside the workspace, else nil.
+      def domain_path(body)
+        path = body.fetch("path")
+        Workspace.refuse_escapes!([path])
+        path if Workspace::EXTENSIONS.include?(File.extname(path).delete_prefix("."))
+      end
+
+      def refused(body) = json(400, error: "#{body["path"].inspect} is not a domain file")
+
+      def parse(body)
+        refusal = Workspace.stage(dir: workspace, buffers: buffers(body)) { |stage| Parse.call(stage) }
+        json(200, diagnostic: refusal)
+      end
+
+      def check(body)
+        json(200, Check.call(dir: workspace, buffers: buffers(body), chapter_name: body["chapter_name"]))
+      end
+
+      def buffers(body) = body.fetch("buffers", {})
+
+      def body(request)
+        raw = request.body&.read.to_s
+        raw.empty? ? {} : JSON.parse(raw)
+      end
+
+      def json(status, payload)
+        [status, { "content-type" => "application/json" }, [JSON.generate(payload)]]
+      end
+    end
+  end
+end

data/lib/hecks/composer/workbench.rb

@@ -0,0 +1,51 @@
+require_relative "agent"
+require_relative "assistant"
+require_relative "panels"
+require_relative "session"
+
+module Hecks
+  module Composer
+    # Everything the editor keeps for one workspace, on the hecksagon side: the draft bookkeeping,
+    # the agent that edits it and the panels beneath the editor. Opening another domain builds a
+    # new workbench, so nothing of the old workspace carries over.
+    class Workbench
+      # @return [String] the domain directory this workbench is for
+      attr_reader :workspace
+
+      # @param workspace [String] the domain directory
+      # @param agents [Runtime::Registry, nil] a registry holding the `composer_agent` port and one
+      #   adapter; the one `HECKS_COMPOSER_AGENT` names (`claude`, the default, or `fake`) when nil
+      def initialize(workspace:, agents: nil)
+        @workspace = File.expand_path(workspace)
+        @agents = agents
+      end
+
+      # @return [String] the workspace's directory name, which names its draft
+      def slug = File.basename(workspace)
+
+      # @return [Session] the draft bookkeeping, booted on first use
+      def session = @session ||= Session.new
+
+      # @return [Assistant] the agent loop over this workspace
+      def assistant = @assistant ||= Assistant.new(workspace: workspace, agents: agents, session: session)
+
+      # @return [Panels] what answers the lower panels
+      def panels = @panels ||= Panels.new(workspace: workspace, session: session)
+
+      # Releases what the panels booted.
+      # @return [void]
+      def close = @panels&.close
+
+      private
+
+      def agents = @agents ||= default_agents
+
+      # The adapter `HECKS_COMPOSER_AGENT` names: the real `claude`, or a scripted `fake`.
+      def default_agents
+        name = ENV.fetch("HECKS_COMPOSER_AGENT", "claude") == "fake" ? "fake_agent" : "claude_composer"
+        require_relative "adapters/#{name}"
+        Agent.registry_with(File.join(Agent::ADAPTERS, "#{name}.adapter"))
+      end
+    end
+  end
+end

data/lib/hecks/composer/workspace.rb

@@ -0,0 +1,81 @@
+require "fileutils"
+require "tmpdir"
+
+module Hecks
+  module Composer
+    # A workspace is a directory of domain files; an editor holds unsaved text for some of them.
+    # Staging lays that text over a copy of the files on disk so a check sees what is on screen
+    # and the directory itself stays untouched.
+    module Workspace
+      # The files a domain is made of; anything else in the directory is data, not declaration.
+      EXTENSIONS = %w[bluebook hecksagon world adapter port behaviors].freeze
+
+      # Raised when an unsaved buffer names a path outside the workspace.
+      class OutsideWorkspace < ArgumentError; end
+
+      module_function
+
+      # Copies the workspace's declaration files into a temporary directory, lays the buffers over
+      # them, and yields that directory.
+      #
+      # @param dir [String] the workspace directory
+      # @param buffers [Hash{String => String}] unsaved text by path relative to `dir`; a path
+      #   with no file on disk yet is created
+      # @yieldparam stage [String] the temporary directory holding the staged files
+      # @return [Object] what the block returned
+      # @raise [OutsideWorkspace] if a buffer's path is absolute or climbs out of the workspace
+      def stage(dir:, buffers: {})
+        stage = materialize(dir: dir, buffers: buffers)
+        yield stage
+      ensure
+        FileUtils.rm_rf(stage) if stage
+      end
+
+      # Stages as {stage} does, but leaves the directory for the caller to remove, so a booted
+      # domain can keep reading its files after this returns.
+      #
+      # @param dir [String] the workspace directory
+      # @param buffers [Hash{String => String}] unsaved text by path relative to `dir`
+      # @return [String] the temporary directory holding the staged files
+      # @raise [OutsideWorkspace] if a buffer's path is absolute or climbs out of the workspace
+      def materialize(dir:, buffers: {})
+        refuse_escapes!(buffers.keys)
+        stage = Dir.mktmpdir("hecks-composer")
+        copy_declarations(dir, stage)
+        buffers.each { |path, text| write(File.join(stage, path), text) }
+        stage
+      rescue StandardError
+        FileUtils.rm_rf(stage) if stage
+        raise
+      end
+
+      # @param stage [String] a staged directory
+      # @return [Array<String>] the declaration files in it, relative and sorted
+      def files(stage)
+        Dir.glob("**/*.{#{EXTENSIONS.join(",")}}", base: stage).sort
+      end
+
+      # @api private
+      def copy_declarations(dir, stage)
+        files(dir).each do |relative|
+          FileUtils.mkdir_p(File.dirname(File.join(stage, relative)))
+          FileUtils.cp(File.join(dir, relative), File.join(stage, relative))
+        end
+      end
+
+      # @api private
+      def write(path, text)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, text)
+      end
+
+      # @api private
+      def refuse_escapes!(paths)
+        offender = paths.find { |path| path.start_with?("/") || path.split("/").include?("..") }
+        return unless offender
+
+        raise OutsideWorkspace, "#{offender.inspect} is not inside the workspace"
+      end
+    end
+  end
+end

data/lib/hecks/composer.rb

@@ -0,0 +1,17 @@
+require_relative "composer/plain"
+require_relative "composer/workspace"
+require_relative "composer/parse"
+require_relative "composer/outline"
+require_relative "composer/layout"
+require_relative "composer/behavior_run"
+require_relative "composer/live"
+require_relative "composer/toolbox"
+require_relative "composer/jobs"
+require_relative "composer/check"
+
+module Hecks
+  # The Composer's outside, on the hecksagon side: staging a workspace, judging its text and
+  # projecting what it declares. The Composer chapter's bluebook is in `composer/bluebook/`.
+  module Composer
+  end
+end

data/lib/hecks/corpus/adapters.rb

@@ -0,0 +1,22 @@
+module Hecks
+  module Corpus
+    # Where `.adapter` files live, for the parser parity check. Extended onto `Corpus`.
+    module Adapters
+      # Directories that hold copies or build output, never a source `.adapter`.
+      EXCLUDED_DIRS = %w[vendor node_modules target tmp .git .aws-sam].freeze
+
+      ADAPTER_GLOBS = %w[lib/**/*.adapter examples/**/*.adapter spec/fixtures/**/*.adapter].freeze
+
+      # Every `.adapter` file the repo carries.
+      #
+      # @param root [String] repository root to search under
+      # @return [Array<String>] absolute paths, sorted, none under a vendored, `node_modules`,
+      #   `target` or scratch directory
+      def adapter_files(root: Corpus::ROOT)
+        ADAPTER_GLOBS.flat_map { |glob| Dir.glob(File.join(root, glob)) }.uniq.sort.reject do |path|
+          path.delete_prefix("#{root}/").split("/").intersect?(EXCLUDED_DIRS)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/corpus/rust.rb

@@ -3,7 +3,7 @@ module Hecks
     # Every Rust-facing list reads `rust/Cargo.toml`'s `[features]` as its
     # one source, rather than each consumer typing it out by hand.
     GENERATED_DIR = "rust/src/generated".freeze
-    RUST_DOMAIN_KINDS = %i[example stress fixture].freeze
+    RUST_DOMAIN_KINDS = %i[example stress semantics fixture].freeze
 
     RustDomain = Struct.new(:feature, :dir, :kind)
 

data/lib/hecks/corpus/worlds.rb

@@ -0,0 +1,19 @@
+module Hecks
+  module Corpus
+    # Where `.world` files live, for the parser parity check. Extended onto `Corpus`.
+    module Worlds
+      WORLD_GLOBS = %w[lib/**/*.world examples/**/*.world qa/**/*.world spec/fixtures/**/*.world].freeze
+
+      # Every `.world` file the repo carries.
+      #
+      # @param root [String] repository root to search under
+      # @return [Array<String>] absolute paths, sorted, none under a vendored, `node_modules`,
+      #   `target` or scratch directory
+      def world_files(root: Corpus::ROOT)
+        WORLD_GLOBS.flat_map { |glob| Dir.glob(File.join(root, glob)) }.uniq.sort.reject do |path|
+          path.delete_prefix("#{root}/").split("/").intersect?(Adapters::EXCLUDED_DIRS)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/corpus.rb

@@ -1,7 +1,9 @@
 require_relative "fuzzing/target_capabilities"
+require_relative "corpus/adapters"
 require_relative "corpus/routes"
 require_relative "corpus/rust"
 require_relative "corpus/sources"
+require_relative "corpus/worlds"
 
 module Hecks
   # The corpus: every place in this repo that holds a real domain, named once.
@@ -36,6 +38,7 @@ module Hecks
       deploy:    "lib/hecks/deploy/bluebook/*.bluebook",
       site:      "lib/hecks/site/bluebook/*.bluebook",
       tickets:   "lib/hecks/tickets/bluebook/*.bluebook",
+      composer:  "lib/hecks/composer/bluebook/*.bluebook",
       tenancy:   "lib/hecks/tenancy/bluebook/*.bluebook",
       sme:       "lib/hecks/sme/bluebook/*.bluebook",
       fixture:   "spec/fixtures/**/*.bluebook"
@@ -43,8 +46,10 @@ module Hecks
 
     KINDS = (DIRECTORY_KINDS.keys + FILE_KINDS.keys).freeze
 
+    extend Adapters
     extend Rust
     extend Sources
+    extend Worlds
 
     module_function
 

data/lib/hecks/forms/app/commands.rb

@@ -28,11 +28,10 @@ module Hecks
         # @param page [Hash] optionally `status:`, the submitted `values:`, the `error:` to show and
         #   the `prefill:` values
         def command_form(domain, aggregate, command, action, **page)
-          html("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}",
+          html(Humanize.phrase(command.hecks_name),
                CommandFormRenderer.render(registry: @registry, domain: domain, aggregate: aggregate, command: command,
                                           action: action, **page.slice(:values, :error, :prefill)),
-               breadcrumbs: [[domain, "/"], [aggregate.hecks_name, "/#{domain}/#{aggregate.hecks_name}.html"],
-                             [command.hecks_name, nil]],
+               breadcrumbs: verb_breadcrumbs(domain, aggregate, command),
                status:      page.fetch(:status, 200))
         end
 

data/lib/hecks/forms/app/queries.rb

@@ -25,11 +25,10 @@ module Hecks
         def query_html(domain, aggregate, query, asked)
           action = "/#{domain}/#{aggregate.hecks_name}/#{query.hecks_name}.html"
           results, error = asked.empty? ? [nil, nil] : run_query(domain, aggregate, query, asked)
-          html("#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}",
+          html(Humanize.phrase(query.hecks_name),
                QueryFormRenderer.render(registry: @registry, domain: domain, aggregate: aggregate, query: query,
                                         action: action, params: asked, results: results, error: error),
-               breadcrumbs: [[domain, "/"], [aggregate.hecks_name, "/#{domain}/#{aggregate.hecks_name}.html"],
-                             [query.hecks_name, nil]],
+               breadcrumbs: verb_breadcrumbs(domain, aggregate, query),
                status:      error ? 422 : 200)
         end
 

data/lib/hecks/forms/app/records.rb

@@ -12,9 +12,9 @@ module Hecks
           return respond(405, "text/plain", "GET only") unless request.get?
           return aggregate_json(chapter, aggregate) unless format == "html"
 
-          html("#{chapter.name}::#{aggregate.hecks_name}",
+          html(Naming.plural(Humanize.phrase(aggregate.hecks_name)),
                RecordRenderer.index(registry: @registry, domain: chapter.name, aggregate: aggregate),
-               breadcrumbs: [[chapter.name, "/"], [aggregate.hecks_name, nil]])
+               breadcrumbs: [[chapter.name, "/"], [Humanize.phrase(aggregate.hecks_name), nil]])
         end
 
         def aggregate_json(chapter, aggregate)
@@ -52,10 +52,22 @@ module Hecks
           # `id:` last, as in `aggregate_route`.
           return json(200, instance.state.merge(id: instance.id)) if format != "html"
 
-          html("#{domain}::#{aggregate.hecks_name} #{id}",
+          html("#{Humanize.phrase(aggregate.hecks_name)} #{id}",
                RecordRenderer.show(registry: @registry, domain: domain, aggregate: aggregate, id: id),
-               breadcrumbs: [[domain, "/"], [aggregate.hecks_name, "/#{domain}/#{aggregate.hecks_name}.html"],
-                             [id, nil]])
+               breadcrumbs: aggregate_crumbs(domain, aggregate) + [[id, nil]])
+        end
+
+        # @return [Array<Array(String, String)>] the domain and aggregate crumbs every page
+        #   under an aggregate starts with, the aggregate named in words
+        def aggregate_crumbs(domain, aggregate)
+          [[domain, "/"], [Humanize.phrase(aggregate.hecks_name), "/#{domain}/#{aggregate.hecks_name}.html"]]
+        end
+
+        # @param verb [Bluebook::Command, Bluebook::Query] the command or query the page is for
+        # @return [Array<Array(String, String), Array(String, nil)>] the aggregate crumbs, then
+        #   the verb named in words as the current page
+        def verb_breadcrumbs(domain, aggregate, verb)
+          aggregate_crumbs(domain, aggregate) + [[Humanize.phrase(verb.hecks_name), nil]]
         end
 
         def find_aggregate(chapter, name)

data/lib/hecks/forms/app/responses.rb

@@ -1,5 +1,6 @@
 require "json"
 require_relative "../page"
+require_relative "../../runtime/value"
 
 module Hecks
   module Forms
@@ -13,8 +14,9 @@ module Hecks
           respond(status, "text/html; charset=utf-8", Page.render(title: title, body: body, breadcrumbs: breadcrumbs))
         end
 
+        # A single-field value object answers as its bare field, as `Json.materialize` does.
         def json(status, payload)
-          respond(status, "application/json", JSON.pretty_generate(payload))
+          respond(status, "application/json", JSON.pretty_generate(Runtime::Value.materialize_unwrapped(payload)))
         end
 
         def redirect(location)

data/lib/hecks/forms/command_form_renderer.rb

@@ -43,7 +43,7 @@ module Hecks
         fields_html = fields_markup(registry, domain, all_fields, form)
         action = form.fetch(:action)
         cancel = "/#{domain}/#{aggregate.hecks_name}"
-        [header(domain, aggregate, command), error_banner(form[:error]),
+        [header(aggregate, command), error_banner(form[:error]),
          form_markup(action, fields_html, command, cancel).chomp,
          inspect_panel(domain, aggregate, command, action, all_fields)].join("\n").concat("\n")
       end
@@ -64,7 +64,7 @@ module Hecks
           <form method="post" action="#{Escape.attr(action)}" novalidate>
             #{fields_html}
             <div class="actions">
-              <button type="submit">#{Escape.html(command.hecks_name)}</button>
+              <button type="submit">#{Escape.html(Humanize.phrase(command.hecks_name))}</button>
               <a class="button secondary" href="#{Escape.attr(cancel)}">Cancel</a>
             </div>
           </form>
@@ -72,33 +72,58 @@ module Hecks
       end
 
       # Builds the `to` field a non-creating command uses to name the record it acts on,
-      # labelled with the aggregate's identity paths.
+      # labelled with the aggregate's name and helped by what identifies one ("the order's
+      # name").
       #
       # @param aggregate [Bluebook::Aggregate] the aggregate whose records the picker offers
       # @return [Forms::Field] a `:reference` field at path `"to"` targeting `aggregate`
       def self.identity_field(aggregate)
-        Field.new(path: "to", label: "#{aggregate.hecks_name} (#{aggregate.identity_paths.join(", ")})",
+        noun = Humanize.noun(aggregate.hecks_name)
+        Field.new(path: "to", label: Humanize.phrase(aggregate.hecks_name),
                   kind: :reference, html_type: "text", target_aggregate: aggregate,
-                  help: "The record this command acts on.")
+                  help: "Which #{noun} this is for, by the #{noun}'s #{identity_words(aggregate)}.")
       end
 
-      # Renders the form's heading: the command's qualified name, its role and creates
-      # badges, its goal, and its preconditions callout.
+      # Names what identifies a record in words: `["name.value"]` -> "name", a composite
+      # `["bank", "number"]` -> "bank and number". A dotted path names its first segment,
+      # since the hops after it reach inside a value object.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose identity is named
+      # @return [String] the identity's field names as lowercase words; "id" when it has none
+      def self.identity_words(aggregate)
+        names = aggregate.identity_paths.map { |path| Humanize.noun(path.to_s.split(".").first) }.uniq
+        names.empty? ? "id" : Naming.to_sentence_list(names)
+      end
+
+      # Renders the form's heading: the command's name in words, its role and creates
+      # badges, its goal, and its preconditions callout. The code name stays in the inspect
+      # panel.
       #
-      # @param domain [String] name of the domain (chapter) the aggregate belongs to
       # @param aggregate [Bluebook::Aggregate] the aggregate that declares the command
       # @param command [Bluebook::Command] the command being described
       # @return [String] HTML for the heading block
-      def self.header(domain, aggregate, command)
+      def self.header(aggregate, command)
         <<~HTML
-          <h1>#{Escape.html("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}")}</h1>
-          #{%(<span class="badge role" title="Declared on the command; this prototype dispatches with no caller bound, so the check does not run.">role: #{Escape.html(command.role)} (not enforced here)</span>) if command.role}
-          #{%(<span class="badge">creates a new #{Escape.html(aggregate.hecks_name)}</span>) if command.creates?}
+          <h1>#{Escape.html(Humanize.phrase(command.hecks_name))}</h1>
+          #{role_badge(command)}
+          #{%(<span class="badge">Creates a new #{Escape.html(Humanize.noun(aggregate.hecks_name))}</span>) if command.creates?}
           #{%(<p class="goal">#{Escape.html(command.goal)}</p>) if command.goal}
           #{givens_callout(command)}
         HTML
       end
 
+      # Names who the command is for. The preview dispatches with no caller bound, so the role
+      # is shown but not checked, and the badge says so.
+      #
+      # @param command [Bluebook::Command] the command whose declared role is shown
+      # @return [String] HTML for the badge, or `""` when the command declares no role
+      def self.role_badge(command)
+        return "" unless command.role
+
+        title = "The bluebook declares who does this. This preview signs nobody in, so it does not check."
+        %(<span class="badge role" title="#{title}">Done by: #{Escape.html(command.role)} (not checked in this preview)</span>)
+      end
+
       # Renders the command's `given` preconditions as a callout, so a caller sees what
       # would refuse the submission before making it.
       #
@@ -108,7 +133,8 @@ module Hecks
         return "" if command.givens.empty?
 
         items = command.givens.map { |given| "<li>#{Escape.html(given.description)}</li>" }
-        %(<div class="callout"><strong>Preconditions</strong> — refused if any fail:<ul>#{items.join}</ul></div>)
+        %(<div class="callout"><strong>Checked first.</strong> The action is refused if any of these fail:) \
+          "<ul>#{items.join}</ul></div>"
       end
 
       # Renders a refused submission as an alert banner carrying the refusal's class name
@@ -121,7 +147,7 @@ module Hecks
 
         <<~HTML
           <div class="error-banner" role="alert">
-            <p><strong>#{Escape.html(error.class.name.split("::").last)}</strong> — #{Escape.html(error.message)}</p>
+            <p><strong>Refused (#{Escape.html(error.class.name.split("::").last)}):</strong> #{Escape.html(error.message)}</p>
           </div>
         HTML
       end
@@ -174,9 +200,9 @@ module Hecks
       def self.inspect_head(verb, command, curl)
         <<~HTML
           <details class="inspect">
-            <summary>Inspect — #{Escape.html(verb)}</summary>
+            <summary>Inspect: #{Escape.html(verb)}</summary>
             <p>Emits: #{emitted_events(command)}</p>
-            <p>Equivalent request (as <code>curl</code>) — every field is <code>#{Escape.html("name.path")}</code>-encoded, form or JSON alike:</p>
+            <p>The same request as <code>curl</code>. Every field is sent by its dotted path (<code>#{Escape.html("name.path")}</code>), as a form or as JSON:</p>
             <div class="link-row"><code id="curl-snippet">#{Escape.html(curl)}</code><button type="button" class="copy" data-copy="#curl-snippet">copy</button></div>
         HTML
       end

data/lib/hecks/forms/field_controls.rb

@@ -65,7 +65,7 @@ module Hecks
             %(<option value="#{Escape.attr(option_value)}"#{" selected" if option_value.to_s == selected.to_s}>) \
               "#{Escape.html(option_label)}</option>"
           end
-          blank = field.optional? ? %(<option value="">—</option>) : ""
+          blank = field.optional? ? %(<option value="">(none)</option>) : ""
           select_tag(field, "#{blank}#{options.join}")
         end
 
@@ -80,7 +80,7 @@ module Hecks
         end
 
         def self.reference_blank(field, value)
-          return %(<option value="">—</option>) if field.optional?
+          return %(<option value="">(none)</option>) if field.optional?
 
           %(<option value="" disabled#{" selected" unless value}>choose one…</option>)
         end

data/lib/hecks/forms/field_renderer.rb

@@ -51,7 +51,7 @@ module Hecks
 
       def self.list_tail(field, item)
         <<~HTML
-            <span class="help" id="#{dom_id(field.path)}-help">One #{Escape.html(item.label.downcase)} per line#{" — each line is one JSON object" unless item.leaf?}.</span>
+            <span class="help" id="#{dom_id(field.path)}-help">One #{Escape.html(item.label.downcase)} per line#{", each line one JSON object" unless item.leaf?}.</span>
           </div>
         HTML
       end