hecks 2.8.0 → 3.0.0

data/lib/hecks/hecks/adapters/pg_admin.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "console_capture"
+
+module Hecks
+  module Adapters
+    # The `PgAdmin` port's adapter: the Postgres administration that happens outside the
+    # persistence adapters, namely roles and scratch databases.
+    #
+    # Connections are made to the maintenance database (`postgres`) or to the database being
+    # administered, as the current operating-system user, exactly as `psql` would. Nothing here
+    # creates the ledger database itself: PostgresEra provisions the tables it needs on first
+    # connect, and an operator makes the database with `createdb`.
+    class PgAdmin
+      # The role the QA ledger connects as when none is named.
+      DEFAULT_ROLE = "hecks_qa"
+
+      # What every database this adapter drops must start with, and be followed by a name.
+      SCRATCH = /\Ascratch_\w+\z/
+
+      # Databases that are never dropped, whatever their name: the maintenance and template
+      # databases.
+      SYSTEM_DATABASES = %w[postgres template0 template1].freeze
+
+      # The environment variables that name the ledger or production database in use.
+      CONFIGURED_DATABASES = %w[PGDATABASE HECKS_LEDGER_DATABASE HECKS_DATABASE].freeze
+
+      # Relation kinds in `pg_class` mapped to the `ALTER` keyword that changes their owner.
+      # Partitions are their own rows, so `ALTER TABLE ... OWNER` on a parent does not reach them.
+      KINDS = { "r" => "TABLE", "p" => "TABLE", "S" => "SEQUENCE", "v" => "VIEW",
+                "m" => "MATERIALIZED VIEW" }.freeze
+
+      class << self
+        # @return [#call, nil] opens a connection given `dbname:` and answers an object with
+        #   `exec`, `exec_params`, `quote_ident` and `close`; a spec replaces it so no server is
+        #   reached. The `pg` gem is required only when this is nil.
+        attr_accessor :connector
+      end
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Creates the ordinary role the QA ledger connects as and makes it own the database, its
+      # schema, and everything in it. Safe to repeat: what is already right is reported, not redone.
+      #
+      # A superuser or BYPASSRLS role is refused, because the era write-fence cannot bind it.
+      #
+      # @param held [Hash] `database` (required) and `role` (`hecks_qa` when absent)
+      # @return [Hash{Symbol => Hash}] `report:` what was done and what already held
+      # @raise [ConsoleCapture::Failure] if no database is named or it does not exist, or the role
+      #   exists with privileges the fence cannot bind
+      def create_ledger_role(**held)
+        database = named(held)
+        role = plain(held[:role]) || DEFAULT_ROLE
+
+        done = []
+        skipped = []
+        with(dbname: "postgres") do |admin|
+          ensure_role(admin, role, done, skipped)
+          hand_over_database(admin, database, role, done, skipped)
+        end
+        with(dbname: database) { |db| hand_over_contents(db, role, done) }
+
+        { report: { value: ledger_report(database, role, done, skipped) } }
+      end
+
+      # Creates an empty database, for a scratch run that needs one. Repeating it reports that the
+      # database exists.
+      #
+      # @param held [Hash] `database` (required)
+      # @return [Hash{Symbol => Hash}] `report:` what happened
+      # @raise [ConsoleCapture::Failure] if no database is named
+      def create_database(**held)
+        database = named(held)
+        with(dbname: "postgres") do |admin|
+          if exists?(admin, database)
+            { report: { value: "database #{database} already exists" } }
+          else
+            admin.exec("CREATE DATABASE #{admin.quote_ident(database)}")
+            { report: { value: "created database #{database}" } }
+          end
+        end
+      end
+
+      # Drops a scratch database if it is there, ending other sessions on it first so one left
+      # open by a crashed run does not block the drop. Ending every session on a database is
+      # only safe for a throwaway one, so a name must start with `scratch_` and must not be the
+      # ledger or production database the environment names.
+      #
+      # @param held [Hash] `database` (required)
+      # @return [Hash{Symbol => Hash}] `report:` what happened
+      # @raise [ConsoleCapture::Failure] if no database is named, it is not a scratch name, or it
+      #   is a configured ledger or production database
+      def drop_database(**held)
+        database = named(held)
+        refuse_to_drop!(database)
+        with(dbname: "postgres") do |admin|
+          if exists?(admin, database)
+            admin.exec_params("SELECT pg_terminate_backend(pid) FROM pg_stat_activity " \
+                              "WHERE datname = $1 AND pid <> pg_backend_pid()", [database])
+            admin.exec("DROP DATABASE #{admin.quote_ident(database)}")
+            { report: { value: "dropped database #{database}" } }
+          else
+            { report: { value: "no database #{database}" } }
+          end
+        end
+      end
+
+      private
+
+      def refuse_to_drop!(database)
+        if SYSTEM_DATABASES.include?(database.downcase) || configured_databases.include?(database)
+          raise ConsoleCapture::Failure, "refusing to drop #{database}: it is the ledger, production or " \
+                                         "a system database"
+        end
+        return if database.match?(SCRATCH)
+
+        raise ConsoleCapture::Failure, "refusing to drop #{database}: only databases named scratch_<name> " \
+                                       "are dropped"
+      end
+
+      def configured_databases
+        named = CONFIGURED_DATABASES.filter_map { |variable| ENV.fetch(variable, nil) }
+        url = ENV.fetch("DATABASE_URL", nil)
+        named << URI.parse(url).path.to_s.delete_prefix("/") if url && !url.empty?
+        named.reject(&:empty?)
+      rescue URI::InvalidURIError
+        named
+      end
+
+      def named(held)
+        database = plain(held[:database])
+        raise ConsoleCapture::Failure, "no database named" if database.to_s.empty?
+
+        database
+      end
+
+      def ensure_role(admin, role, done, skipped)
+        found = admin.exec_params("SELECT rolsuper, rolbypassrls FROM pg_roles WHERE rolname = $1", [role])
+        if found.ntuples.zero?
+          # CREATE ROLE has no IF NOT EXISTS, and concurrent creates can lose on the catalog
+          # index (unique_violation) as well as on duplicate_object, so the block rescues both.
+          admin.exec(<<~SQL)
+            DO $$ BEGIN
+              CREATE ROLE #{admin.quote_ident(role)} LOGIN NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE;
+            EXCEPTION WHEN duplicate_object OR unique_violation THEN NULL;
+            END $$
+          SQL
+          done << "created role #{role} (LOGIN, no SUPERUSER, no BYPASSRLS)"
+        elsif found[0]["rolsuper"] == "t" || found[0]["rolbypassrls"] == "t"
+          kind = found[0]["rolsuper"] == "t" ? "a superuser" : "a BYPASSRLS role"
+          raise ConsoleCapture::Failure,
+                "role #{role} already exists as #{kind}: the era write-fence cannot bind it. " \
+                "Pick another role, or ALTER ROLE #{role} NOSUPERUSER NOBYPASSRLS first."
+        else
+          skipped << "role #{role} exists, ordinary"
+        end
+      end
+
+      def hand_over_database(admin, database, role, done, skipped)
+        owner = admin.exec_params(
+          "SELECT pg_get_userbyid(datdba) AS owner FROM pg_database WHERE datname = $1", [database]
+        )
+        if owner.ntuples.zero?
+          raise ConsoleCapture::Failure,
+                "no database #{database}: createdb it first (PostgresEra provisions every table it " \
+                "needs on first connect, never the database itself)"
+        elsif owner[0]["owner"] == role
+          skipped << "database #{database} already owned by #{role}"
+        else
+          admin.exec("ALTER DATABASE #{admin.quote_ident(database)} OWNER TO #{admin.quote_ident(role)}")
+          done << "database #{database}: owner #{owner[0]['owner']} -> #{role}"
+        end
+      end
+
+      def hand_over_contents(db, role, done)
+        quoted = db.quote_ident(role)
+        schema = db.exec("SELECT pg_get_userbyid(nspowner) AS owner FROM pg_namespace WHERE nspname = 'public'")
+        if schema.ntuples.positive? && schema[0]["owner"] != role
+          db.exec("ALTER SCHEMA public OWNER TO #{quoted}")
+          done << "schema public: owner #{schema[0]['owner']} -> #{role}"
+        end
+
+        relations = db.exec_params(<<~SQL, [role])
+          SELECT c.relname, c.relkind, pg_get_userbyid(c.relowner) AS owner
+          FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE n.nspname = 'public' AND c.relkind IN ('r', 'p', 'S', 'v', 'm') AND pg_get_userbyid(c.relowner) <> $1
+          ORDER BY c.relkind, c.relname
+        SQL
+        relations.each do |row|
+          db.exec("ALTER #{KINDS.fetch(row['relkind'])} #{db.quote_ident(row['relname'])} OWNER TO #{quoted}")
+        end
+        done << "#{relations.ntuples} relation(s) in public -> #{role}" if relations.ntuples.positive?
+
+        functions = db.exec_params(<<~SQL, [role])
+          SELECT p.proname, pg_get_function_identity_arguments(p.oid) AS args
+          FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+          WHERE n.nspname = 'public' AND pg_get_userbyid(p.proowner) <> $1
+          ORDER BY p.proname
+        SQL
+        functions.each do |row|
+          db.exec("ALTER FUNCTION #{db.quote_ident(row['proname'])}(#{row['args']}) OWNER TO #{quoted}")
+        end
+        done << "#{functions.ntuples} function(s) in public -> #{role}" if functions.ntuples.positive?
+      end
+
+      def ledger_report(database, role, done, skipped)
+        lines = ["#{database} is #{role}'s"]
+        done.each { |line| lines << "  did:     #{line}" }
+        skipped.each { |line| lines << "  already: #{line}" }
+        lines << "  bind it: database \"postgres://#{role}@localhost/#{database}\"" if done.any?
+        lines.join("\n")
+      end
+
+      def exists?(admin, database)
+        admin.exec_params("SELECT 1 FROM pg_database WHERE datname = $1", [database]).ntuples.positive?
+      end
+
+      def with(dbname:)
+        connection = connect(dbname)
+        yield connection
+      rescue ConsoleCapture::Failure
+        raise
+      rescue StandardError => e
+        raise ConsoleCapture::Failure, "postgres: #{e.message.strip}"
+      ensure
+        connection&.close
+      end
+
+      def connect(dbname)
+        return self.class.connector.call(dbname: dbname) if self.class.connector
+
+        require "pg"
+        PG.connect(dbname: dbname)
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/process_pool.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/process_pool"
+
+Hecks.adapter "ProcessPool" do
+  port "ProcessPool"
+end

data/lib/hecks/hecks/adapters/process_pool.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require "tempfile"
+require_relative "console_capture"
+require_relative "rust_workspace"
+
+module Hecks
+  module Adapters
+    # The `ProcessPool` port's adapter: starts a long-running child (a fuzz sweep forks its own
+    # workers) and stays with it until it ends.
+    #
+    # The child runs in its own process group, and an interrupt or termination sent to this
+    # process is passed on to the whole group, so stopping a launcher stops the workers it
+    # started instead of leaving them running. Output goes to a temporary file, not a pipe, so a
+    # child that writes a lot never blocks on a reader that is waiting for it to exit.
+    class ProcessPool
+      # What a child said and how it ended.
+      #
+      # @!attribute [r] output
+      #   @return [String] what it wrote to stdout and stderr, in order
+      # @!attribute [r] status
+      #   @return [Process::Status] how it ended
+      Finished = Struct.new(:output, :status) do
+        # @return [Boolean] whether the child ended with status 0
+        def ok? = status.success?
+      end
+
+      # The library the sweep child loads `Hecks::Tools` from.
+      LIB = File.expand_path("../../..", __dir__)
+
+      # What the sweep child runs: the `fuzz` tool, which takes the flags that follow.
+      ENTRY = 'require "hecks/tools"; Hecks::Tools.script("fuzz", ARGV)'
+
+      # Signals passed on to a running child's process group.
+      FORWARDED = %w[INT TERM HUP QUIT].freeze
+
+      class << self
+        # @return [#call, nil] runs a child given `(command, env, chdir)` and answers a `Finished`;
+        #   a spec replaces it so nothing is started
+        attr_accessor :starter
+      end
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Runs a fuzz sweep over one domain, or over every domain of the checkout when none is named.
+      #
+      # @param held [Hash] the `Fuzzing` record: `domain`, `seeds`, `steps`, `workers`, `adapter`
+      # @return [Hash{Symbol => Hash}] `report:` what the sweep printed
+      # @raise [ConsoleCapture::Failure] when the sweep found something, or could not run
+      def sweep(**held)
+        if plain(held[:domain]).nil? && !RustWorkspace.new.checkout?
+          raise ConsoleCapture::Failure, "name a domain (hecks fuzz <domain>): sweeping every domain " \
+                                         "needs a hecks checkout"
+        end
+
+        command = [RbConfig.ruby, "-I", LIB, "-e", ENTRY, "--"]
+        command << plain(held[:domain]) if plain(held[:domain])
+        { "--seeds" => :seeds, "--steps" => :steps, "--workers" => :workers, "--adapter" => :adapter }.each do |flag, key|
+          command.push(flag, plain(held[key]).to_s) unless plain(held[key]).nil?
+        end
+
+        answer(run(command))
+      end
+
+      # Starts a child, forwards interrupts to it, and waits for it to end.
+      #
+      # @param command [Array<String>] the program, then its arguments
+      # @param env [Hash{String => String}] variables to set for it
+      # @param chdir [String, nil] the directory to run it in
+      # @return [Finished] what it said and how it ended
+      def run(command, env: {}, chdir: nil)
+        starter = self.class.starter
+        return starter.call(command, env, chdir) if starter
+
+        output = Tempfile.new("process-pool")
+        options = { pgroup: true, out: output, err: output }
+        options[:chdir] = chdir if chdir
+        # Traps go in before the spawn, so a signal that lands while the child is starting is held
+        # and passed on the moment its pid is known, instead of orphaning it.
+        pid = nil
+        held = []
+        previous = FORWARDED.to_h do |name|
+          [name, trap(name) { pid ? forward(name, pid) : held << name }]
+        end
+        pid = spawn(env, *command, **options)
+        held.each { |name| forward(name, pid) }
+        _, status = Process.wait2(pid)
+        Finished.new(File.read(output.path), status)
+      rescue Errno::ENOENT => e
+        Finished.new(e.message, Struct.new(:success?, :exitstatus).new(false, 127))
+      ensure
+        previous&.each { |name, handler| trap(name, handler) }
+        output&.close!
+      end
+
+      private
+
+      def forward(name, pid)
+        Process.kill(name, -pid)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def answer(finished)
+        raise ConsoleCapture::Failure, finished.output.strip unless finished.ok?
+
+        { report: { value: finished.output } }
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rust_toolchain.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/rust_toolchain"
+
+Hecks.adapter "RustToolchain" do
+  port "RustToolchain"
+end

data/lib/hecks/hecks/adapters/rust_toolchain.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require_relative "console_capture"
+require_relative "rust_workspace"
+require_relative "process_pool"
+require "hecks/rust_build"
+
+module Hecks
+  module Adapters
+    # The `RustToolchain` port's adapter: generates a domain's Rust source, compiles it (native,
+    # WASI, browser) and checks the build against the Ruby engine.
+    #
+    # Each ask runs one of the `Hecks::RustBuild` tools in this process, in the workspace
+    # `RustWorkspace` names: the checkout's own `rust/`, or a copy of the packaged workspace under
+    # the client's `.hecks/rust/<version>/`. The tool is told that workspace and a `target/`
+    # beside it, so a build never writes into the installed gem. A tool that ends non-zero is a
+    # refusal whose reason is what it printed. The benchmark is the exception: it can run for
+    # minutes, so it starts as a child through `ProcessPool`.
+    class RustToolchain
+      # The `Hecks::RustBuild` tool each ask runs.
+      TOOLS = { generate: "project_rust", wasm: "project_wasm", browser_wasm: "project_wasm_browser",
+                conform: "rust_conformance", replay: "rust_conformance_fuzz",
+                coverage: "rust_coverage" }.freeze
+
+      # The load path the benchmark child runs with: this checkout's or gem's `lib/`.
+      LIB = File.expand_path("../../..", __dir__)
+
+      # The program the benchmark child runs: `hecks bench`'s command line.
+      BENCH = 'require "hecks"; require "hecks/bench"; exit Hecks::Bench::CLI.run(ARGV)'
+
+      # `Hecks::Bench::CLI`'s flag for each `FuzzRun` field a benchmark takes.
+      BENCH_FLAGS = { "--domain" => :domains, "--targets" => :targets, "--iterations" => :iterations,
+                      "--warmup" => :warmup, "--runs" => :runs, "--rust-binary" => :rust_binary,
+                      "--format" => :format, "--output" => :output }.freeze
+
+      class << self
+        # @return [#run, nil] starts the long-running benchmark; a `ProcessPool` when nil
+        attr_accessor :pool
+
+        # @return [#capture, nil] runs each tool, as `capture(tool, argv, env:)` answering an
+        #   object with `out`, `err`, `status` and `ok?`; `Hecks::RustBuild` when nil. A spec
+        #   replaces it, so no toolchain is needed to test what is asked of it.
+        attr_accessor :runner
+
+        # @return [RustWorkspace, nil] the workspace to build in; `RustWorkspace.new` when nil
+        attr_accessor :workspace
+      end
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Generates the domain's Rust source into the workspace, with a Cargo feature for it.
+      #
+      # @param held [Hash] the `Build` record: `domain` (its directory)
+      # @return [Hash{Symbol => Hash}] `output:` what the generator reported
+      # @raise [ConsoleCapture::Failure] when the domain cannot be generated, or the install has no
+      #   Rust workspace to build in
+      def generate(**held)
+        child(:generate, [plain(held[:domain])])
+      end
+
+      # Generates the domain, then compiles it to a `wasm32-wasip1` module.
+      #
+      # @param held [Hash] the `Build` record: `domain`
+      # @return [Hash{Symbol => Hash}] `output:` where the module was written
+      # @raise [ConsoleCapture::Failure] when the wasm target or the build is missing
+      def wasm(**held)
+        child(:wasm, [plain(held[:domain])])
+      end
+
+      # Generates the domain, then compiles it to an ES module for a browser through wasm-bindgen.
+      #
+      # @param held [Hash] the `Build` record: `domain`
+      # @return [Hash{Symbol => Hash}] `output:` where the module was written
+      # @raise [ConsoleCapture::Failure] when the target, the wasm-bindgen version or the build is
+      #   missing
+      def browser_wasm(**held)
+        child(:browser_wasm, [plain(held[:domain])])
+      end
+
+      # Replays a step script through the Ruby engine and, when an artifact is named, through that
+      # artifact too, and compares what each did.
+      #
+      # @param held [Hash] the `Build` record: `domain`, `script` (a JSON file of steps) and
+      #   `artifact` (`native`, `build`, a `.wasm` file or a binary; Ruby's own result when absent)
+      # @return [Hash{Symbol => Hash}] `output:` the comparison, or Ruby's result as JSON
+      # @raise [ConsoleCapture::Failure] when the two disagree, or the artifact cannot be run
+      def conform(**held)
+        child(:conform, [plain(held[:domain]), plain(held[:script]), plain(held[:artifact])].compact)
+      end
+
+      # Replays generated step sequences through the Ruby engine and an artifact.
+      #
+      # @param held [Hash] the `Build` record: `domain`, `artifact`, `seeds` (10 when absent) and
+      #   `steps` (25 when absent)
+      # @return [Hash{Symbol => Hash}] `output:` how many sequences matched
+      # @raise [ConsoleCapture::Failure] at the first seed that diverges, naming how to reproduce it
+      def replay(**held)
+        argv = [plain(held[:domain]), plain(held[:artifact]), (plain(held[:seeds]) || 10).to_s,
+                (plain(held[:steps]) || 25).to_s]
+        child(:replay, argv)
+      end
+
+      # Checks that every rule of the coverage allowlist still excuses a real gap.
+      #
+      # @param _held [Hash] the `Build` record, which holds nothing this needs
+      # @return [Hash{Symbol => Hash}] `output:` the check's verdict
+      # @raise [ConsoleCapture::Failure] when a rule excuses nothing
+      def audit(**_held)
+        child(:coverage, ["--check-allowlist"])
+      end
+
+      # Measures command throughput and latency for each target, building the Rust binary in the
+      # workspace when it is a target and none was named. The benchmark can run for minutes, so it
+      # starts through `ProcessPool`, which passes an interrupt on to it.
+      #
+      # @param held [Hash] the `FuzzRun` record: `domains`, `targets`, `iterations`, `warmup`,
+      #   `runs`, `rust_binary`, `format` and `output` (a file the full JSON is also written to)
+      # @return [Hash{Symbol => Hash}] `report:` what the benchmark printed
+      # @raise [ConsoleCapture::Failure] when it could not run, or the install has no Rust workspace
+      def measure(**held)
+        flags = BENCH_FLAGS.filter_map { |flag, key| [flag, plain(held[key]).to_s] unless plain(held[key]).nil? }
+        env = (self.class.workspace || RustWorkspace.new).environment.merge("HECKS_NO_3_0_NOTICE" => "1")
+        command = [RbConfig.ruby, "-I", LIB, "-e", BENCH, "--", *flags.flatten]
+        finished = (self.class.pool || ProcessPool.new).run(command, env: env)
+        raise ConsoleCapture::Failure, finished.output.strip unless finished.ok?
+
+        { report: { value: finished.output } }
+      rescue RustWorkspace::Unavailable => e
+        raise ConsoleCapture::Failure, e.message
+      end
+
+      # Reports whether each construct of a generated module has a routed implementation.
+      #
+      # @param module_name [Hash, String] the generated module (a domain's directory name)
+      # @param codegen [Hash, String, nil] `ruby` (the default) or `rust`: which generator's
+      #   manifest to read
+      # @return [Hash] `text:` the report, gaps included: a gap is what it says, not a refusal
+      # @raise [ConsoleCapture::Failure] when there is no such module, or no report could be made
+      def rust_coverage(module_name:, codegen: nil)
+        argv = [plain(module_name)]
+        argv << "--codegen=#{plain(codegen)}" if plain(codegen)
+        result = run(:coverage, argv)
+        return { text: result.out } if result.ok? || result.out.start_with?("=" * 8)
+
+        raise ConsoleCapture::Failure, message_of(result)
+      end
+
+      private
+
+      def child(ask, argv)
+        result = run(ask, argv)
+        raise ConsoleCapture::Failure, message_of(result) unless result.ok?
+
+        { output: { value: result.out } }
+      end
+
+      def run(ask, argv)
+        space = self.class.workspace || RustWorkspace.new
+        env = space.environment
+        (self.class.runner || RustBuild).capture(TOOLS.fetch(ask), argv, env: env)
+      rescue RustWorkspace::Unavailable => e
+        raise ConsoleCapture::Failure, e.message
+      end
+
+      def message_of(result)
+        text = [result.err, result.out].map(&:strip).reject(&:empty?).join("\n")
+        text.empty? ? "the build ended with status #{result.status}" : text
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end