nukadoko 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b6d047ee71c9d370c302adba5f7746fc297ddb145f34a7edb4aadf19d6b9174c
+  data.tar.gz: 9498233a5e767889d79c193ac243f0e4a14fea417bca0ace600b7391ed077916
+SHA512:
+  metadata.gz: 823e46b1d92101a548e63b42ab808d0ae3739d53179c037ce6af1ecdca5622fde9694b34b6080f646e8942c17f793ad66ed1df4a81a3cff4e816ee905a6854c9
+  data.tar.gz: 0c768c8cd2e6ef4d3eeb28cbc02cb58be4e34b038996429687630261490db2ce95a6428ff6f243d94cc43c6f4bea4504c7710f4ac37bf46e1e8a05ea28c23169

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+Notable changes to the `nukadoko` gem, the Ruby engine. The npm package has
+its own changelog, `../CHANGELOG.md`, and its own versions. Each release's
+notes come from the section below whose heading starts with `## [<version>]`.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-14
+
+### Added
+
+- The first Ruby engine: steps written as Ruby classes with typed `args` and
+  `returns`, `nuka check`, `nuka run`, `nuka steps`, `nuka describe`, and
+  `nuka sig` for Steep. It passes every case under `conformance/`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 meganemura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.ja.md

@@ -0,0 +1,71 @@
+# nukadoko の Ruby 版
+
+[nukadoko](../README.ja.md) の Ruby のエンジンです。
+Gherkin のステップに型付きの契約を付け、シナリオのまちがいを実行前に見つけます。
+TypeScript 版と同じ feature ファイルを読み、同じ判定を返す必要があります。
+[`../conformance/`](../conformance/README.md) のケースがそれを確かめます。
+
+状態: 初期の核です。
+`conformance/` の 10 のケースを通します。
+HTTP のステップ、ブラウザのステップ、コマンドラインのステップ、プロジェクトが定義するフィクスチャ、parts でできたステップ、poll する Then ステップ、`from`、docstring、Scenario Outline、条件つきの環境、control と proof run、判定表です。
+`--base`、`nuka check` の指摘の多くなど、TypeScript 版の機能の多くはまだありません。
+
+## インストール
+
+テストするプロジェクトの Gemfile に足します。
+Ruby 3.4 以上が要ります。
+
+```ruby
+gem "nukadoko", group: :test
+```
+
+## ステップ
+
+`features/steps/` の下に 1 ファイル 1 ステップで書きます。
+ファイル名がステップ名です(`add_todo.rb` は `add-todo`)。
+
+```ruby
+class AddTodo < Nukadoko::Step
+  pattern "a todo titled {title:string} is added"
+  args { string :title, "The title of the todo to create" }
+  returns do
+    string :id
+    string :title
+    boolean :done
+  end
+
+  def run(request:, args:)
+    request.post("/todos", data: { title: args.title }).json
+  end
+end
+```
+
+- nil を許すフィールドには `null: true` を付けます。`enum :outcome, %w[accepted refused]` はその語だけを許し、Steep はリテラルの和として扱います。
+- パターンの取り出し部分にはすべて名前を付けます。名前は `args` のキーです。
+- `run`(Then ステップでは `observe`)のキーワード引数が、ステップが使うフィクスチャです。`nuka check` は本体を呼ばずに `Method#parameters` で読みます。
+- Then ステップは `claims` と、世界を読む `observe` を書きます。claim の判定は nukadoko が行います。claim が比べる args のキーは `observe` に渡されません。
+
+## コマンド
+
+- `nuka check [--json]` は、実行前にまちがいを報告します。
+- `nuka run [--json] [--no-check]` は、プログラムを起動してすべてのシナリオを実行し、ステップごとの記録を `.nukadoko/runs/` に書きます。
+- ブラウザの起動設定は `nukadoko.config.rb` に `Nukadoko.config(browser: { executablePath: "..." })` と書きます。`page` を使うステップは、シナリオごとに自分のブラウザコンテキストを持ちます。ステップの記録には、ページが送ったリクエストとステップのトレースが残ります。
+- `scratch` を使うステップは `scratch.dir` で新しいディレクトリを得ます。シナリオが終わると消えます。`Nukadoko.run_command(command, args, cwd:)` はプログラムを実行し、`{ exitCode:, stdout:, stderr: }` を返します。ステップの記録には実行したプロセスが残ります。
+- プロジェクトのフィクスチャは `nukadoko.config.rb` に書きます。ブロックは値を `use` に渡し、その後ろが後片付けです。例: `Nukadoko.fixture(:store) { |use| use.(Store.new) }`。`scope: :process` にすると、環境ごとの実行全体で 1 つの値を使います。
+- `parts [CreateTodo, CompleteById]` で、ステップが呼べるステップを宣言します。`call.(CreateTodo, title: args.title)` で 1 つを実行し、args と返り値を確かめます。パターンのない part も書けます。呼び出しは、呼んだステップの記録の `calls` に残ります。`nuka check` は、`parts` の循環と、`mutates false` なのに `mutates true` の part を持つステップを報告します。
+- `poll timeout_ms: 3000` は、すべての claim が 2 回続けて成り立つか時間切れになるまで、100 ミリ秒おきに `observe` を読み直します。`settled:` には、一度なったら変わらない状態を書きます。2 回続けてその状態なら、壊れた claim を待つのをやめます。読んだ結果はすべてステップの記録に残ります。
+- `nuka steps [--json]` は語彙の一覧を出します。`nuka describe <step>` は 1 つのステップを、args と返り値の JSON Schema とともに出します。項目は TypeScript 版と同じです。
+- 契約が宣言していない返り値のキーは、zod のオブジェクトと同じく捨てられます。ステップの記録の `returns_dropped` に、捨てたキーが残ります。
+- `nuka sig` は `sig/nukadoko/steps.rbs` を書きます。Steep を使うと、宣言していない args のキーを読む本体や、形のちがう値を返す本体がエラーになります。
+
+テストするプログラムは `nukadoko.program.rb` に書きます。
+
+```ruby
+Nukadoko.program serve: { command: "bin/rails server -p {port}", ready: "/up" }
+```
+
+## 開発
+
+- このディレクトリで `bundle install` を実行します。
+- `bundle exec ruby ../conformance/run-rb.rb` で、すべての検査ケースをこのエンジンで走らせます。
+- `bundle exec bin/test` で単体テストと、`test/hegel/` の Hegel の性質テストを走らせます。gem には Ruby 3.4 以上が要ります。

data/README.md

@@ -0,0 +1,66 @@
+# nukadoko for Ruby
+
+The Ruby engine of [nukadoko](../README.md): typed step contracts for Gherkin, written in Ruby, so a scenario can be told wrong before it runs.
+It reads the same feature files as the TypeScript engine and must judge them the same way; the cases in [`../conformance/`](../conformance/README.md) hold it to that.
+
+Status: an early core. It passes the ten cases in `conformance/`: HTTP steps, browser steps, command-line steps, fixtures a project defines, steps made of parts, polling Then steps, `from`, docstrings, Scenario Outlines, environments with conditions, controls with proof runs, and the verdict table. Much of what the TypeScript engine does is not here yet, such as `--base`, and most of what `nuka check` reports.
+
+## Install
+
+Add it to the Gemfile of the project under test. It needs Ruby 3.4 or later.
+
+```ruby
+gem "nukadoko", group: :test
+```
+
+## A step
+
+One step per file under `features/steps/`. The file name is the step name (`add_todo.rb` is `add-todo`).
+
+```ruby
+class AddTodo < Nukadoko::Step
+  pattern "a todo titled {title:string} is added"
+  args { string :title, "The title of the todo to create" }
+  returns do
+    string :id
+    string :title
+    boolean :done
+  end
+
+  def run(request:, args:)
+    request.post("/todos", data: { title: args.title }).json
+  end
+end
+```
+
+- A field takes `null: true` when nil is allowed. `enum :outcome, %w[accepted refused]` allows only those words, and Steep sees them as a union of literals.
+- Every capture in the pattern is named, and each name is a key of `args`.
+- The keyword arguments of `run` (or `observe`, in a Then step) name the fixtures the step needs. `nuka check` reads them with `Method#parameters`, without calling the body.
+- A Then step declares `claims` and an `observe` that reads the world. nukadoko judges the claims. `observe` does not receive an args key that a claim compares with.
+
+## Commands
+
+- `nuka check [--json]` reports what is wrong before anything runs.
+- `nuka run [--json] [--no-check]` starts the program, runs every scenario, and writes a record per step under `.nukadoko/runs/`.
+- Browser launch options go in `nukadoko.config.rb`, as `Nukadoko.config(browser: { executablePath: "..." })`. A step that names `page` gets a browser context of its own for each scenario; each step record holds the requests the page sent and a trace of the step.
+- A step that names `scratch` gets `scratch.dir`, a fresh directory that is removed when the scenario ends. `Nukadoko.run_command(command, args, cwd:)` runs a program and returns `{ exitCode:, stdout:, stderr: }`; the step record lists each run.
+- A project fixture goes in `nukadoko.config.rb`. The block calls `use` with the value, and what follows is the teardown: `Nukadoko.fixture(:store) { |use| use.(Store.new) }`. `scope: :process` keeps one value for the whole run of an environment.
+- `parts [CreateTodo, CompleteById]` declares the steps a step may run, and `call.(CreateTodo, title: args.title)` runs one, with its args and returns checked. A part needs no pattern. Each call is kept under `calls` in the calling step's record. `nuka check` reports a cycle in `parts` and a `mutates false` step whose part declares `mutates true`.
+- `poll timeout_ms: 3000` reads `observe` again, 100 ms apart, until every claim holds on two readings in a row or the time runs out. `settled:` names a state that cannot change once reached, so two settled readings in a row stop the wait for a claim that broke. Every reading is kept in the step record.
+- `nuka steps [--json]` lists the vocabulary, and `nuka describe <step>` prints one step with the JSON Schema of its args and returns, in the fields the TypeScript engine prints.
+- A returned key the contract does not declare is dropped, as a zod object drops it, and the step record names it under `returns_dropped`.
+- `nuka sig` writes `sig/nukadoko/steps.rbs`. With Steep, a body that reads an undeclared args key or returns the wrong shape is an error.
+
+The program under test is described in `nukadoko.program.rb`:
+
+```ruby
+Nukadoko.program serve: { command: "bin/rails server -p {port}", ready: "/up" }
+```
+
+## Development
+
+- `bundle install` in this directory.
+- `bundle exec ruby ../conformance/run-rb.rb` runs every conformance case under this engine.
+- `bundle exec bin/test` runs the unit tests and the Hegel property tests under `test/hegel/`. The gem needs Ruby 3.4 or later.
+
+[日本語](README.ja.md)

data/exe/nuka

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/nukadoko"
+require_relative "../lib/nukadoko/cli"
+
+exit Nukadoko::CLI.new(ARGV).call

data/lib/nukadoko/check.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+# What `check` can say without running anything: every finding follows from
+# the step classes, their patterns and schemas, `Method#parameters`, and the
+# feature files. The codes are the TypeScript engine's codes, so one set of
+# conformance cases judges both engines.
+module Nukadoko
+  module Engine
+    Finding = Data.define(:severity, :code, :file, :line, :step, :message, :fix) do
+      def self.about_step(severity, code, step, message, fix)
+        new(severity, code, step.file, step.line, step.step_name, message, fix)
+      end
+
+      def to_h = super.compact
+    end
+
+    FIXTURES = %w[baseURL call context env evidence page pageAs poll request requireEnv result scratch].freeze
+
+    class Check
+      attr_reader :findings, :usable
+
+      def initialize(steps, scenarios)
+        @steps = steps
+        @scenarios = scenarios
+        @findings = []
+        @usable = steps.reject { definition_broken?(_1) }
+        @usable.each { check_contract(_1) }
+        check_parts
+        check_shapes
+        check_lines
+      end
+
+      def passed? = findings.none? { _1.severity == "error" }
+
+      private
+
+      # A step whose definition cannot stand (an unknown claim compare) is left
+      # out of the vocabulary, as the TypeScript engine leaves out a step file
+      # that fails to import, so it can never match a line.
+      def definition_broken?(step)
+        problems = Claims.unknown_compares(step.claims || []).map { "claims compare must be one of #{Claims::COMPARES.join(", ")}; got #{_1.inspect}." }
+        problems += Definition.new(step).problems
+        problems.each do |problem|
+          findings << Finding.about_step("error", "step-file-import-failed", step, problem,
+                                         "Correct the error that the message names in the file, then run nuka check again.")
+        end
+        problems.any?
+      end
+
+      def check_contract(step)
+        keys = step.args.fields.map { _1.name.to_s }
+        (step.pattern ? Pattern.new(step.pattern).keys - keys : []).each do |key|
+          findings << Finding.about_step("error", "unknown-capture-key", step,
+                                         %(Step "#{step.step_name}" pattern "#{step.pattern}" binds key "#{key}", which is not a key of its args schema),
+                                         "Rename the capture to a key of the args schema, or add the key to the schema.")
+        end
+        undescribed = [step.args, step.returns].compact.flat_map(&:fields).reject(&:description)
+        if undescribed.any?
+          findings << Finding.about_step("note", "schema-field-undescribed", step,
+                                         "Step \"#{step.step_name}\" has schema fields with no description: #{undescribed.map(&:name).join(", ")}",
+                                         "Give each field a description, so nuka steps and an agent can say what it means.")
+        end
+        known = FIXTURES + Nukadoko.project_fixtures.keys.map(&:to_s)
+        (step.fixtures.map(&:to_s) - known).each do |name|
+          findings << Finding.about_step("error", "fixture-structural-violation", step,
+                                         %(#{step.body}() names unknown fixture "#{name}": known fixtures are #{known.uniq.sort.join(", ")}),
+                                         "Name a known fixture as a keyword argument.")
+        end
+      end
+
+      # A cycle never closes into a fixture bag, and a read-only step cannot
+      # reach a part that writes: both can only end one way, so both are errors.
+      def check_parts
+        @usable.each do |step|
+          step.parts.reject { _1.is_a?(Class) && _1 < Step && @steps.include?(_1) }.each do |part|
+            findings << Finding.about_step("error", "part-structural-violation", step,
+                                           "Step \"#{step.step_name}\" declares #{part.inspect} as a part, which is not a registered step",
+                                           "Make each parts entry a step that a step file registers.")
+          end
+          step.parts.select { step.mutates == false && _1.respond_to?(:mutates) && _1.mutates == true }.each do |part|
+            findings << Finding.about_step("error", "part-mutates-contradiction", step,
+                                           "Step \"#{step.step_name}\" declares mutates: false, but its part \"#{part.step_name}\" declares mutates: true",
+                                           "Declare mutates: true on the step, or remove the part that declares mutates: true.")
+          end
+        end
+        part_cycles.each do |cycle|
+          findings << Finding.about_step("error", "part-cycle", cycle.first,
+                                         "part cycle: #{cycle.map(&:step_name).join(" -> ")}",
+                                         "Remove one part from the chain, so that no step reaches itself.")
+        end
+      end
+
+      # Each cycle once, named from the step whose walk first closed it.
+      def part_cycles
+        done = []
+        cycles = []
+        visit = lambda do |step, stack|
+          stack += [step]
+          step.parts.each do |part|
+            next unless @steps.include?(part)
+
+            if stack.include?(part) then cycles << stack.drop(stack.index(part)) + [part]
+            elsif !done.include?(part) then visit.(part, stack)
+            end
+          end
+          done << step
+        end
+        @usable.each { visit.(_1, []) unless done.include?(_1) }
+        cycles
+      end
+
+      # A scenario with steps of its own and no Then can never be judged on
+      # an outcome. The Background's steps count toward the Then.
+      def check_shapes
+        @scenarios.uniq { [_1.uri, _1.keyword_line] }.each do |scenario|
+          next if scenario.steps.all?(&:background) || scenario.steps.any? { _1.kind == "Outcome" }
+
+          findings << Finding.new("warning", "scenario-without-then", scenario.uri, scenario.keyword_line, nil,
+                                  %(Scenario "#{scenario.name}" has no Then step, so nothing about its outcome is judged),
+                                  "Add a Then step that states the outcome.")
+        end
+      end
+
+      def check_lines
+        undefined = []
+        @scenarios.each do |scenario|
+          scenario.steps.each do |line|
+            matches = Engine.matches(@usable, line.text)
+            case matches.size
+            when 0 then undefined << [scenario, line]
+            when 1 then check_fill(scenario, line, *matches.first)
+            else
+              findings << Finding.new("error", "ambiguous-step", scenario.uri, line.line, nil,
+                                      "#{matches.size} steps match \"#{line.text}\"", "Make the patterns distinct.")
+            end
+          end
+        end
+        suppress_undefined(undefined)
+      end
+
+      # While a step definition is broken, a line it would have matched looks
+      # undefined. Saying so would send the reader after the wrong fix, so the
+      # judgment waits for the broken definition, with one warning.
+      def suppress_undefined(undefined)
+        broken = @steps - @usable
+        if broken.any? && undefined.any?
+          findings << Finding.about_step("warning", "undefined-step-check-suppressed", broken.first,
+                                         "Suppressed #{undefined.size} undefined-step issues because #{broken.size} step file could not be read",
+                                         "Correct the step-file-import-failed error, then run nuka check again.")
+          return
+        end
+        undefined.each do |scenario, line|
+          findings << Finding.new("error", "undefined-step", scenario.uri, line.line, nil,
+                                  %(No step matches "#{line.text}"), "Add a step whose pattern matches the line.")
+        end
+      end
+
+      def check_fill(scenario, line, step, captures)
+        missing = step.args.fields.map { _1.name.to_s } - captures.keys - step.from.keys
+        missing = missing.drop(1) if (line.table || line.doc_string) && missing.any?
+        missing.each do |key|
+          findings << Finding.new("error", "unfillable-required-key", scenario.uri, line.line, step.step_name,
+                                  %(Step "#{step.step_name}"'s args key "#{key}" is required, but nothing on this line can fill it),
+                                  "Capture the key in the pattern, attach a table, or make the key optional.")
+        end
+      end
+    end
+
+    def self.matches(steps, text)
+      steps.filter_map { |step| step.pattern && (captures = Pattern.new(step.pattern).match(text)) && [step, captures] }
+    end
+  end
+end

data/lib/nukadoko/claims.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# A Then step declares what it compares; the engine judges. A claim names the
+# actual value (a key the step observed or was given, and an optional `at`
+# path into it), a compare, and where the expected value comes from: an args
+# key, `{ literal: v }`, or `{ from: key }` for an args key an earlier step
+# filled. The judge returns every comparison it made, so a broken claim shows
+# what was read.
+module Nukadoko
+  module Engine
+    module Claims
+      COMPARES = %w[equal not-equal contains-text starts-with-text ends-with-text has-item has-same-items has-fields
+                    lacks-field fits-text fits-aria-snapshot is-a matches greater-than at-least less-than at-most judged-as].freeze
+
+      def self.unknown_compares(node)
+        case node
+        in Array then node.flat_map { unknown_compares(_1) }
+        in Hash
+          own = node.key?(:compare) && !COMPARES.include?(node[:compare]) ? [node[:compare]] : []
+          own + node.values.flat_map { unknown_compares(_1) }
+        else []
+        end
+      end
+
+      def self.judge(claims, observed, args)
+        claims.map { judge_one(_1, observed, args) }
+      end
+
+      def self.judge_one(claim, observed, args)
+        actual = dig(view(claim[:view], read(observed, claim[:actual])), claim[:at])
+        return judge_each(claim[:each], actual, args) if claim[:each]
+
+        expected = expected_value(claim, args)
+        { actual: actual, compare: claim[:compare], expected: expected, holds: holds?(claim[:compare], actual, expected) }
+      end
+
+      def self.judge_each(each, items, args)
+        chosen = Array(items).select { |item| each[:where].all? { judge_one(_1, item, args)[:holds] } }
+        results = chosen.flat_map { |item| each[:claims].map { judge_one(_1, item, args) } }
+        { each: results, chosen: chosen.size, holds: !chosen.empty? && results.all? { _1[:holds] } }
+      end
+
+      def self.expected_value(claim, args)
+        value =
+          case claim[:expected]
+          in String => key then read(args, key)
+          in { literal: literal } then literal
+          in { from: String => key } then read(args, key)
+          end
+        claim[:expected_view] == "json" ? JSON.parse(value) : value
+      end
+
+      VIEWS = %w[text lines comma-list json].freeze
+
+      # A view reads a string as something else before `at` walks into it.
+      def self.view(name, value)
+        return value unless name
+        raise ArgumentError, "view #{name} reads a string, and the value is #{value.inspect}" unless value.is_a?(String)
+
+        case name
+        when "text" then value.rstrip
+        when "lines" then value.rstrip.empty? ? [] : value.rstrip.split(/\r?\n/)
+        when "comma-list" then value.strip.empty? ? [] : value.strip.split(",").map(&:strip)
+        when "json" then JSON.parse(value)
+        else raise ArgumentError, "unknown view #{name}"
+        end
+      end
+
+      def self.read(hash, key)
+        hash = hash.transform_keys(&:to_s) if hash.is_a?(Hash)
+        hash.fetch(key.to_s)
+      end
+
+      def self.dig(value, path)
+        return value unless path
+
+        path.to_s.split(".").reduce(value) { |v, part| v.is_a?(Array) ? v[Integer(part)] : read(v, part) }
+      end
+
+      def self.same?(a, b) = normal(a) == normal(b)
+
+      def self.normal(value)
+        case value
+        when Hash then value.to_h { |k, v| [k.to_s, normal(v)] }
+        when Array then value.map { normal(_1) }
+        when Symbol then value.to_s
+        else value
+        end
+      end
+
+      def self.holds?(compare, actual, expected)
+        case compare
+        when "equal" then same?(actual, expected)
+        when "not-equal" then !same?(actual, expected)
+        when "contains-text" then actual.to_s.include?(expected.to_s)
+        when "starts-with-text" then actual.to_s.start_with?(expected.to_s)
+        when "ends-with-text" then actual.to_s.end_with?(expected.to_s)
+        when "has-item" then Array(actual).any? { same?(_1, expected) }
+        when "has-same-items" then Array(actual).map { normal(_1) }.tally == Array(expected).map { normal(_1) }.tally
+        when "greater-than" then actual.is_a?(Numeric) && actual > expected
+        when "at-least" then actual.is_a?(Numeric) && actual >= expected
+        when "less-than" then actual.is_a?(Numeric) && actual < expected
+        when "at-most" then actual.is_a?(Numeric) && actual <= expected
+        when "matches" then Regexp.new(expected.to_s).match?(actual.to_s)
+        else raise NotImplementedError, "the Ruby engine cannot judge #{compare} yet"
+        end
+      end
+    end
+  end
+end

data/lib/nukadoko/cli.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# The `nuka` command. With --json it prints one envelope in the shape the
+# TypeScript engine prints, so an agent reads both engines the same way.
+module Nukadoko
+  class CLI
+    def initialize(argv, project: Dir.pwd, out: $stdout)
+      @command, *rest = argv
+      @json = rest.delete("--json")
+      @no_check = rest.delete("--no-check")
+      @rest = rest
+      @project = File.expand_path(project)
+      @out = out
+    end
+
+    def call
+      %w[nukadoko.config.rb nukadoko.program.rb].each do |name|
+        file = File.join(@project, name)
+        load file if File.exist?(file)
+      end
+      steps = Nukadoko.load_steps(File.join(@project, "features", "steps"))
+      scenarios = Dir.chdir(@project) { Engine.load_features("features") }
+      check = Engine::Check.new(steps, scenarios)
+      findings = check.findings.map { relative(_1).to_h }
+      case @command
+      when "check" then finish("check", check.passed?, findings: findings)
+      when "sig"
+        path = File.join(@project, "sig", "nukadoko", "steps.rbs")
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, Signature.of(steps))
+        @out.puts "wrote #{path.delete_prefix("#{@project}/")}"
+        0
+      when "steps"
+        entries = check.usable.sort_by(&:file)
+        return finish("steps", true, findings: findings, steps: entries.map { Vocabulary.entry(_1, @project) }) if @json
+
+        @out.puts entries.map { Vocabulary.text(_1) }.join("\n\n")
+        0
+      when "describe"
+        step = check.usable.find { _1.step_name == @rest.first }
+        @json = true
+        unless step
+          refusal = { severity: "refused", code: "unknown-step", message: "Unknown step: #{@rest.first}", fix: "Name a step that nuka steps lists.", do: "nuka steps" }
+          return finish("describe", false, findings: findings + [refusal], verdict: "refused")
+        end
+
+        finish("describe", true, findings: findings, **Vocabulary.describe(step, @project))
+      when "run"
+        return finish("run", false, findings: findings) unless @no_check || check.passed?
+
+        result = Engine::Run.new(@project, check.usable, scenarios, Nukadoko.program_options, out: @json ? $stderr : @out).call
+        passed = result.delete(:passed)
+        finish("run", passed, findings: findings, **result)
+      else
+        warn "usage: nuka check|run|steps|describe <step>|sig [--json] [--no-check]"
+        2
+      end
+    end
+
+    private
+
+    def relative(finding)
+      finding.with(file: finding.file&.delete_prefix("#{@project}/"))
+    end
+
+    def finish(command, passed, findings:, verdict: passed ? "passed" : "failed", **rest)
+      if @json
+        @out.puts JSON.pretty_generate({ nukadoko: VERSION, engine: "ruby", command: command, verdict: verdict, findings: findings, **rest })
+      else
+        findings.each { @out.puts [_1[:severity], _1[:code], [_1[:file], _1[:line]].compact.join(":"), _1[:message]].join("\t") }
+        @out.puts "ok: no issues found" if command == "check" && findings.empty?
+      end
+      passed ? 0 : 1
+    end
+  end
+end

data/lib/nukadoko/command.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tmpdir"
+require "fileutils"
+
+# What a command-line scenario needs: scratch directories that live as long
+# as one scenario, and a way to run the program under test that keeps every
+# run for the step record. Both are engine-built, so a step never removes a
+# directory it made or forgets to note a process it started.
+module Nukadoko
+  # Runs a command and gives what it left: the exit code (nil when a signal
+  # ended it), stdout, and stderr. Inside a step, the run is noted in the
+  # step record's processes.
+  def self.run_command(command, args = [], cwd: Dir.pwd, env: {}, stdin: nil)
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    stdout, stderr, status = Open3.capture3(env.transform_keys(&:to_s), command, *args, chdir: cwd, stdin_data: stdin.to_s)
+    result = { exitCode: status.exitstatus, stdout: stdout, stderr: stderr }
+    Engine::Processes.current&.push(
+      command: command, args: args, cwd: File.expand_path(cwd), exit_code: status.exitstatus,
+      signal: status.termsig && Signal.signame(status.termsig),
+      duration_ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+    )
+    result
+  end
+
+  module Engine
+    # The processes the running step started, kept per thread so a step
+    # that calls run_command from a helper is still measured.
+    module Processes
+      def self.current = Thread.current[:nukadoko_processes]
+
+      # Fills `into` even when the step raises, so a failed step still names
+      # the processes it ran.
+      def self.collect(into)
+        Thread.current[:nukadoko_processes] = into
+        yield
+      ensure
+        Thread.current[:nukadoko_processes] = nil
+      end
+    end
+
+    # The `scratch` fixture: `dir` makes a fresh directory, and the engine
+    # removes every one of them when the scenario ends, passed or failed.
+    class Scratch
+      def initialize
+        @dirs = []
+      end
+
+      def dir(prefix = "nukadoko-scratch")
+        raise ArgumentError, "a scratch prefix cannot hold a path separator: #{prefix}" if prefix.match?(%r{[/\\]})
+
+        Dir.mktmpdir(prefix).tap { @dirs << _1 }
+      end
+
+      def dirs = @dirs.dup
+
+      def remove_all
+        @dirs.each { FileUtils.rm_rf(_1) }
+      end
+    end
+  end
+end