enjine 0.1.0

data/lib/enjine/cli/text.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+module Enjine
+  class CLI
+    # Plain-text rendering of views, decisions, options and events.
+    # Works only from the public API (views, history, options), never engine internals.
+    class Text
+      STEP_NAMES = {
+        "untap" => "Untap", "upkeep" => "Upkeep", "draw" => "Draw", "precombat_main" => "Main 1",
+        "beginning_of_combat" => "Beginning of Combat", "declare_attackers" => "Declare Attackers",
+        "declare_blockers" => "Declare Blockers", "combat_damage" => "Combat Damage", "end_of_combat" => "End of Combat",
+        "postcombat_main" => "Main 2", "end" => "End Step", "cleanup" => "Cleanup"
+      }.freeze
+      # CR 500.1: the phases of a turn and their steps (main phases have none), as the board's turn tracker.
+      PHASES = [["Beginning", { "untap" => "untap", "upkeep" => "upkeep", "draw" => "draw" }],
+                ["Main 1", { "precombat_main" => nil }],
+                ["Combat", { "beginning_of_combat" => "begin", "declare_attackers" => "attackers",
+                             "declare_blockers" => "blockers", "combat_damage" => "damage", "end_of_combat" => "end" }],
+                ["Main 2", { "postcombat_main" => nil }],
+                ["End", { "end" => "end step", "cleanup" => "cleanup" }]].freeze
+
+      def initialize(game)
+        @game = game
+      end
+
+      # ---- board -----------------------------------------------------------------
+
+      def board(view)
+        lines = [rule(turn_title(view["turn"], view["active"], view["step"])), "  #{tracker(view["step"].to_s)}"]
+        lines << "  Priority: #{view["priority"]}" if view["priority"]
+        viewer = view["viewer"]
+        view["players"].sort_by { it["name"] == viewer ? 1 : 0 }.each { lines.concat(player_block(view, it)) }
+        lines << "  Stack (top first): #{"empty" if view["stack"].empty?}"
+        view["stack"].each { lines << "    #{stack_item(it)}" }
+        view["effects"].each do |e|
+          lines << "  Effect: +#{e["power"]}/+#{e["toughness"]} until end of turn on #{e["affected"].map do
+            name_of(it)
+          end.join(", ")}"
+        end
+        lines.join("\n")
+      end
+
+      # "Turn 3 · alice's turn · Upkeep", or "Pregame" before the first turn.
+      def turn_title(turn, active, step)
+        return "Pregame" if step.nil? || active.nil?
+
+        "Turn #{turn} · #{active}'s turn · #{STEP_NAMES.fetch(step.to_s, step.to_s)}"
+      end
+
+      # The phases of the turn with the current one marked, its steps listed:
+      # "Beginning › ▶MAIN 1 › Combat › Main 2 › End" or
+      # "Beginning › Main 1 › ▶COMBAT (begin · attackers · [blockers] · damage · end) › Main 2 › End".
+      def tracker(step)
+        return "Mulligans and play/draw choices" unless STEP_NAMES.key?(step)
+
+        PHASES.map do |phase, steps|
+          next phase unless steps.key?(step)
+
+          inner = steps.values.compact.map { |name| steps[step] == name ? "[#{name}]" : name }
+          "▶#{phase.upcase}#{" (#{inner.join(" · ")})" unless inner.empty?}"
+        end.join(" › ")
+      end
+
+      # "Combat › Declare Attackers", "Main 1".
+      def step_line(step)
+        phase, steps = PHASES.find { |_, names| names.key?(step) }
+        name = STEP_NAMES.fetch(step, step)
+        phase.nil? || steps[step].nil? ? name : "#{phase} › #{name}"
+      end
+
+      def player_block(view, player)
+        pool = player["mana_pool"].map { |t, n| "{#{t}}" * n }.join + player.fetch("restricted_mana", []).map { "{#{it["mana"]}}*" }.join
+        poison = player["poison"].positive? ? " · poison #{player["poison"]}" : ""
+        lines = ["", "  #{player["name"].upcase} — life #{player["life"]}#{poison} · " \
+                     "library #{player["library_count"]} · hand #{player["hand_count"]} · " \
+                     "graveyard #{player["graveyard"].size}#{" · mana pool #{pool}" unless pool.empty?}"]
+        perms = view["battlefield"].select { it["controller"] == player["name"] }
+        lands, others = perms.partition { it["type_line"].include?("Land") }
+        lines << "    Lands:     #{lands.empty? ? "-" : lands.map { permanent(it) }.join(", ")}"
+        lines << "    Permanents: #{"-" if others.empty?}"
+        others.each { lines << "      #{permanent(it)}" }
+        lines << "    Hand:      #{player["hand"].map { card(it) }.join(", ")}" if player["hand"]
+        if player["library"]
+          lines << "    Library (top first): #{player["library"].first(5).map do
+            it["name"]
+          end.join(", ")}#{" …" if player["library_count"] > 5}"
+        end
+        lines << "    Graveyard: #{player["graveyard"].map { it["name"] }.join(", ")}" unless player["graveyard"].empty?
+        lines
+      end
+
+      def permanent(obj)
+        parts = [obj["name"]]
+        parts << "#{obj["power"]}/#{obj["toughness"]}" if obj.key?("power")
+        parts << "loyalty #{obj["loyalty"]}" if obj.key?("loyalty")
+        parts << obj["keywords"].map { it.tr("_", " ") }.join(", ") if obj["keywords"]
+        parts << "damage #{obj["damage"]}" if obj["damage"].to_i.positive?
+        obj.fetch("counters", {}).except("loyalty").each { |kind, n| parts << "#{n}×#{kind}" }
+        parts << "tapped" if obj["tapped"]
+        parts << "sick" if obj["summoning_sick"]
+        parts << "attacking #{name_of(obj["attacking"])}" if obj["attacking"]
+        parts << "blocking #{name_of(obj["blocking"])}" if obj["blocking"]
+        "#{parts.join(" · ")} [#{obj["id"]}]"
+      end
+
+      def card(obj) = "#{obj["name"]}#{" #{obj["mana_cost"]}" if obj["mana_cost"]} [#{obj["id"]}]"
+
+      def stack_item(obj)
+        targets = obj["targets"].empty? ? "" : " → #{obj["targets"].map { name_of(it) }.join(", ")}"
+        "#{obj["name"]}#{" (#{"+" if obj["loyalty_cost"].to_i.positive?}#{obj["loyalty_cost"]})" if obj["loyalty_cost"]} " \
+          "controlled by #{obj["controller"]}#{targets} [#{obj["id"]}]"
+      end
+
+      # ---- decisions & options -------------------------------------------------
+
+      def decision(decision)
+        extra = case decision.kind
+                when "pay_cost" then " — left to pay: #{decision.details["remaining"]}"
+                when "discard" then " — discard #{decision.details["count"]} more"
+                when "bottom" then " — put #{decision.details["count"]} more on the bottom"
+                when "assign_damage" then " — #{name_of(decision.details["attacker"])}: #{decision.details["remaining"]} damage left"
+                when "choose_target" then " — target ##{decision.details["index"] + 1}"
+                when "choose_target_count" then " — how many for target ##{decision.details["index"] + 1}"
+                else ""
+                end
+        "▶ #{decision.player.upcase} must act: #{decision.kind.tr("_", " ")}#{extra}  (#{turn_title(
+          @game.turn, @game.state.active && @game.names[@game.state.active], @game.step
+        )})"
+      end
+
+      def option(opt)
+        case opt[:type]
+        when "pass" then "Pass priority"
+        when "play_land" then "Play land #{name_of(opt[:object])}"
+        when "cast" then "Cast #{name_of(opt[:object])} #{cost_of(opt[:object])}".rstrip
+        when "activate" then "Activate #{name_of(opt[:object])}: #{ability_text(opt[:object], opt[:ability])}"
+        when "special_action" then "#{ability_text(opt[:object], opt[:ability])}: #{name_of(opt[:object])} (special action)"
+        when "activate_mana"
+          "Tap #{name_of(opt[:object])} for #{opt[:mana] || "mana"} (#{ability_text(opt[:object], opt[:ability])})"
+        when "pay_mana"
+          "Pay {#{opt[:mana]}} from mana pool#{" (restricted)" if opt[:restricted]}#{" (made by an artifact)" if opt[:from]}"
+        when "target" then "Target #{name_of(opt[:target])}"
+        when "cost" then "Use #{name_of(opt[:object])} to pay the cost"
+        when "behold" then "Behold #{name_of(opt[:object])}"
+        when "pay" then opt[:cost] ? "Pay: #{opt[:cost]}" : "Pay"
+        when "cost_option" then @game.pending_decision.details["costs"][opt[:option]]
+        when "cancel" then "Cancel (rewind this cast/activation)"
+        when "attack" then "Attack #{name_of(opt[:target])} with #{name_of(opt[:object])}"
+        when "block" then "Block #{name_of(opt[:attacker])} with #{name_of(opt[:object])}"
+        when "assign" then "Assign 1 damage to #{name_of(opt[:object])}"
+        when "done" then "Done"
+        when "source" then "Choose #{name_of(opt[:object])} as the source"
+        when "devour" then "Devour #{name_of(opt[:object])}"
+        when "discard", "bottom", "find" then "#{opt[:type].capitalize} #{name_of(opt[:object])}"
+        when "keep" then "Keep hand"
+        when "call" then "Call #{opt[:call]}"
+        when "mulligan" then "Mulligan"
+        when "play", "draw" then "#{opt[:type].capitalize} first"
+        else opt.inspect
+        end
+      end
+
+      # ---- events --------------------------------------------------------------
+
+      def events(list) = list.filter_map { event(it) }
+
+      def event(ev)
+        case ev["type"]
+        when "zone_changed" then zone_changed(ev)
+        when "turn_began" then "══ Turn #{ev["turn"]}: #{ev["active"]}'s turn ══"
+        when "step_began" then "─ #{step_line(ev["step"])}"
+        when "priority_passed" then "#{ev["player"]} passes"
+        when "tapped" then "#{name_of(ev["object"])} becomes tapped"
+        when "untapped" then "#{name_of(ev["object"])} untaps"
+        when "mana_added" then "#{ev["player"]} adds #{ev["mana"]}"
+        when "mana_paid" then "#{ev["player"]} pays #{ev["mana"]}"
+        when "mana_emptied" then "#{ev["player"]}'s unused #{ev["mana"]} empties"
+        when "spell_cast" then "#{ev["player"]} casts #{name_of(ev["object"])}#{targets(ev["targets"])}"
+        when "ability_activated" then "#{ev["player"]} activates #{name_of(ev["source"])}'s ability#{targets(ev["targets"])}"
+        when "target_chosen" then "#{ev["player"]} targets #{name_of(ev["target"])}"
+        when "cast_cancelled" then "#{ev["player"]} cancels casting #{card_name(ev["card"])}"
+        when "resolved" then "#{card_name(ev["card"])}#{" ability" if ev["kind"] == "ability"} resolves"
+        when "fizzled" then "#{card_name(ev["card"])} doesn't resolve: its targets are gone"
+        when "damage_dealt" then "#{name_of(ev["source"])} deals #{ev["amount"]} damage to #{name_of(ev["target"])}"
+        when "life_changed" then "#{ev["player"]}: life #{ev["from"]} → #{ev["to"]}"
+        when "counters_changed" then "#{name_of(ev["object"])}: #{ev["counter"]} counters #{ev["from"]} → #{ev["to"]}"
+        when "effect_started" then pumped(ev)
+        when "effects_ended" then "#{ev["count"]} until-end-of-turn effect(s) end"
+        when "attacker_declared" then "#{name_of(ev["object"])} attacks #{name_of(ev["target"])}"
+        when "blocker_declared" then "#{name_of(ev["object"])} blocks #{name_of(ev["attacker"])}"
+        when "damage_assigned" then "1 damage of #{name_of(ev["attacker"])} assigned to #{name_of(ev["blocker"])}"
+        when "player_lost" then "#{ev["player"]} LOSES (#{ev["reason"]})"
+        when "game_ended" then "GAME OVER — #{result(ev)}"
+        when "library_shuffled" then "#{ev["player"]} shuffles their library"
+        when "card_revealed" then "#{ev["player"]} reveals #{card_name(ev["card"])}"
+        when "die_rolled" then "#{ev["winner"]} wins the die roll"
+        when "rolled_die" then "#{ev["player"]} rolls a d#{ev["sides"]}: #{ev["result"]}"
+        when "starting_player_chosen" then "#{ev["chooser"]} chooses to #{ev["choice"]}: #{ev["starting_player"]} goes first"
+        when "mulligan_declared" then "#{ev["player"]} declares: #{ev["choice"]}"
+        when "mulligan_taken" then "#{ev["player"]} mulligans (#{ev["mulligans"]} so far)"
+        when "hand_kept" then "#{ev["player"]} keeps#{" after #{ev["mulligans"]} mulligan(s)" if ev["mulligans"].positive?}"
+        when "game_started" then "Game started: #{ev["players"].join(" vs ")} (seed #{ev["seed"]})"
+        else mechanic_event(ev)
+        end
+      end
+
+      # Events of particular mechanics; attacks_declared is told by its attacker_declared events.
+      def mechanic_event(ev)
+        case ev["type"]
+        when "attacks_declared" then nil
+        when "ability_triggered" then "#{card_name(ev["card"])}'s ability triggers"
+        when "trigger_put_on_stack" then "#{card_name(ev["card"])}'s triggered ability goes on the stack#{targets(ev["targets"])}"
+        when "trigger_removed" then "#{card_name(ev["card"])}'s triggered ability is removed (#{ev["reason"]})"
+        when "ability_countered" then "#{card_name(ev["card"])}'s ability is countered"
+        when "spell_copied" then "#{ev["player"]} copies #{card_name(ev["card"])}#{targets(ev["targets"])}"
+        when "x_announced" then "#{ev["player"]} announces X = #{ev["value"]}"
+        when "payment_finished" then "#{ev["player"]} #{ev["outcome"]}"
+        when "attached" then "#{name_of(ev["object"])} is attached to #{name_of(ev["to"])}"
+        when "unattached" then "#{name_of(ev["object"])} becomes unattached from #{name_of(ev["from"])}"
+        when "control_changed" then "#{ev["controller"]} gains control of #{name_of(ev["object"])}"
+        when "became_blocked" then "#{name_of(ev["object"])} is blocked"
+        when "crewed_vehicle" then "#{name_of(ev["object"])} crews #{name_of(ev["vehicle"])}"
+        when "tapped_for_cost" then "#{name_of(ev["object"])} is tapped to pay a #{ev["cost"]} cost"
+        when "became_crewed" then "#{name_of(ev["object"])} becomes crewed"
+        when "transformed" then "#{name_of(ev["object"])} transforms into #{card_name(ev["card"])}"
+        when "prepared_changed" then "#{name_of(ev["object"])} #{ev["prepared"] ? "becomes prepared" : "is no longer prepared"}"
+        when "phased_out" then "#{name_of(ev["object"])} phases out"
+        when "phased_in" then "#{name_of(ev["object"])} phases in"
+        when "token_ceased" then "#{card_name(ev["card"])} token ceases to exist"
+        when "library_reordered" then "#{ev["player"]} puts #{Array(ev["top"]).size} on top and #{Array(ev["bottom"]).size} on the bottom"
+        when "looked_at" then "#{ev["player"]} looks at #{Array(ev["objects"]).size} of #{ev["owner"]}'s cards"
+        when "dilemma_faced" then "#{ev["player"]} faces a dilemma"
+        when "extra_turn_added" then "#{ev["player"]} will take an extra turn"
+        when "turn_skipped" then "#{ev["player"]} skips a turn"
+        when "emblem_created" then "#{ev["player"]} gets an emblem from #{card_name(ev["card"])}"
+        when "player_counters_changed" then "#{ev["player"]}: #{ev["counter"]} counters #{ev["from"]} → #{ev["to"]}"
+        when "speed_changed" then "#{ev["player"]}: speed #{ev["from"]} → #{ev["to"]}"
+        when "coin_flipped"
+          "#{ev["player"]} flips #{ev["heads"] ? "heads" : "tails"}#{{ true => " and wins", false => " and loses" }[ev["won"]]}"
+        when "keyword_action" then "#{ev["player"]} #{ev["action"].to_s.tr("_", " ")}#{" #{ev["amount"]}" if ev["amount"]}"
+        else "#{ev["type"]}: #{ev.except("type")}"
+        end
+      end
+
+      def pumped(ev)
+        verb = ev["affected"].size == 1 ? "gets" : "get"
+        "#{ev["affected"].map do
+          name_of(it)
+        end.join(", ")} #{verb} +#{ev["details"]["power"]}/+#{ev["details"]["toughness"]} until end of turn"
+      end
+
+      def zone_changed(ev)
+        what = ev["card"] ? card_name(ev["card"]) : "a card"
+        case ev["reason"]
+        when "draw" then "#{ev["owner"]} draws #{what}"
+        when "play_land" then "#{ev["owner"]} plays #{what}"
+        when "cast", "mulligan" then nil
+        when "resolve" then ev["to"] == "battlefield" ? "#{what} enters the battlefield" : "#{what} goes to the graveyard"
+        when "sba_lethal_damage" then "#{what} dies (lethal damage)"
+        when "sba_toughness" then "#{what} dies (0 toughness)"
+        when "sba_loyalty" then "#{what} is put into the graveyard (0 loyalty)"
+        when "countered" then "#{what} is countered"
+        when "mulligan_bottom" then "#{ev["owner"]} puts #{what} on the bottom of their library (mulligan)"
+        else "#{ev["owner"]}'s #{what}: #{ev["from"]} → #{ev["to"]} (#{ev["reason"]})"
+        end
+      end
+
+      def result(res) = res["winner"] ? "#{res["winner"]} wins (#{res["reason"]})" : "draw (#{res["reason"]})"
+
+      # ---- helpers -------------------------------------------------------------
+
+      def rule(text) = "━━ #{text} #{"━" * [4, 76 - text.size].max}"
+
+      def name_of(ref)
+        return "-" if ref.nil?
+        return ref.delete_prefix("player:") if ref.start_with?("player:")
+
+        obj = @game.state.objects[ref]
+        obj ? "#{@game.catalog.fetch(obj.card).name}#{" ability" if obj.ability?}" : card_name(ref.split("#").first)
+      end
+
+      def card_name(card_id) = @game.catalog[card_id]&.name || card_id.to_s
+
+      def cost_of(id) = @game.catalog.fetch(@game.state.object(id).card).mana_cost.to_s
+
+      # A granted ability ("granted:<card>:<ref>") lives in the granting card's data.
+      def ability_text(id, ref)
+        card, inner = Engine::AbilityLayers.granted_parts(ref) || [@game.state.object(id).card, ref]
+        @game.catalog.fetch(card).ability(inner).to_s
+      end
+
+      def targets(list) = list.nil? || list.empty? ? "" : " targeting #{list.map { name_of(it) }.join(", ")}"
+    end
+  end
+end

data/lib/enjine/cli.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "enjine/deck_builder"
+require "enjine/verify"
+require_relative "cli/text"
+
+module Enjine
+  # Interactive text client. Hot-seat by default: you play both players, see what
+  # the deciding player sees, pick numbered options, and after each choice see
+  # exactly what happened. Seats can also be "random" (uniform legal choices).
+  #
+  #   enjine --deck1 examples/decks/gruul_beats.json --deck2 examples/decks/azorius_walkers.json
+  #   enjine --pool examples/pool.json --deck1 random:colors=RG --deck2 random --p2 random
+  #   enjine --verify cards/ --games 20 --seed 1   # check a folder of card JSON (see Enjine::Verify)
+  class CLI
+    SEATS = %w[human random].freeze
+    HELP = <<~HELP
+      Commands:
+        <number>   choose that option
+        b          show the board again          o   toggle observer view (see everything)
+        h [n]      show the last n history entries (default 10)
+        u          undo your last decision (replays the game from its seed)
+        s FILE     save the game to FILE (JSON snapshot)
+        c          concede for the deciding player
+        q          quit
+    HELP
+
+    def initialize(argv, input: $stdin, output: $stdout)
+      @input = input
+      @out = output
+      @options = { p1: "human", p2: "human", quiet: false, max_decisions: 100_000,
+                   observer: false, names: %w[alice bob] }
+      parser.parse!(argv)
+      # `--random-deck colors=WU seed=7` works unquoted: the key=value words after it belong to the spec.
+      @options[:random_deck] = [@options[:random_deck], *argv.grep(/=/)].compact.join(" ") if @options.key?(:random_deck)
+    end
+
+    def run
+      return verify(@options[:verify]) if @options[:verify]
+
+      @options[:seed] ||= Random.new_seed % (2**31)
+      return validate(@options[:validate]) if @options[:validate]
+      return random_deck(@options[:random_deck]) if @options.key?(:random_deck)
+
+      @game = start_game or return 1
+      @text = Text.new(@game)
+      @seats = @game.names.zip([@options[:p1], @options[:p2]]).to_h do |name, kind|
+        [name, kind == "human" ? :human : Agents::Random.new(seed: @options[:seed] + name.sum)]
+      end
+      intro
+      loop_decisions
+      say @text.rule("GAME OVER: #{@text.result(@game.result)} · turn #{@game.turn}") if @game.over?
+      0
+    end
+
+    private
+
+    def parser
+      OptionParser.new do |o|
+        o.banner = "Usage: enjine --deck1 DECK --deck2 DECK [options]   (default: hot-seat, you play both players)"
+        o.on("--seed N", Integer, "Seed for shuffling and the die roll") { @options[:seed] = it }
+        o.on("--p1 SEAT", SEATS, "Seat 1: human (default) or random") { @options[:p1] = it }
+        o.on("--p2 SEAT", SEATS, "Seat 2: human (default) or random") { @options[:p2] = it }
+        o.on("--deck1 DECK", "Seat 1's deck: a deck document (JSON file), or random[:SPEC] from --pool") { @options[:deck1] = it }
+        o.on("--deck2 DECK", "Seat 2's deck: a deck document (JSON file), or random[:SPEC] from --pool") { @options[:deck2] = it }
+        o.on("--pool FILE", "Cards random decks are built from: a JSON array of card data blocks") { @options[:pool] = it }
+        o.on("--random-deck [SPEC]", "Print a random deck from --pool as JSON, e.g. \"colors=WU seed=7\"") do
+          @options[:random_deck] = it
+        end
+        o.on("--names A,B", Array, "Player names (default alice,bob)") { @options[:names] = it }
+        o.on("--validate FILE", "Validate a JSON array of card data blocks; prints a JSON report") { @options[:validate] = it }
+        o.on("--verify DIR", "Validate and play-test every card in DIR's JSON files; exit 1 on any problem") do
+          @options[:verify] = it
+        end
+        o.on("--games N", Integer, "With --verify: play at least N games (default 10)") { @options[:games] = it }
+        o.on("--json", "With --verify: print the report as JSON") { @options[:json] = true }
+        o.on("--load FILE", "Resume a game saved with the s command") { @options[:load] = it }
+        o.on("--observer", "Start in observer view (see both hands and library order)") { @options[:observer] = true }
+        o.on("--quiet", "Only print the result (useful with random seats)") { @options[:quiet] = true }
+        o.on("--max-decisions N", Integer, "Concede after N decisions") { @options[:max_decisions] = it }
+      end
+    end
+
+    # Machine-readable validation for card-conversion pipelines. Exit code 1 if anything is invalid.
+    def validate(path)
+      cards = JSON.parse(File.read(path))
+      cards = [cards] if cards.is_a?(Hash)
+      report = { "rules_version" => RULES_VERSION, "engine_version" => VERSION, "valid" => [], "invalid" => [] }
+      cards.each_with_index do |data, i|
+        defn = CardDefinition.from_h(data)
+        report["valid"] << { "index" => i, "id" => defn.id, "name" => defn.name, "card" => defn.to_h }
+      rescue InvalidCardDefinition => e
+        report["invalid"] << { "index" => i, "name" => data.is_a?(Hash) ? data["name"] : nil, "errors" => e.errors }
+      end
+      say JSON.pretty_generate(report)
+      report["invalid"].empty? ? 0 : 1
+    rescue JSON::ParserError => e
+      say JSON.generate("error" => "not valid JSON: #{e.message}")
+      1
+    end
+
+    # Checks a folder of cards (seed 0 unless --seed); exit code 1 if a card is invalid or a game went wrong.
+    def verify(dir)
+      report = Verify.new(dir, games: @options.fetch(:games, 10), seed: @options.fetch(:seed, 0)).run
+      say @options[:json] ? JSON.pretty_generate(report) : Verify.text(report)
+      report["ok"] ? 0 : 1
+    rescue ArgumentError => e
+      say "error: #{e.message}"
+      1
+    end
+
+    # Prints a random deck document; exit code 1 with a message if it can't be built.
+    def random_deck(spec)
+      say JSON.pretty_generate(build_random_deck(spec, @options[:seed]))
+      0
+    rescue Error, ArgumentError, SystemCallError, JSON::ParserError => e
+      say "error: #{e.message}"
+      1
+    end
+
+    # SPEC: whitespace- or comma-separated key=value pairs; a bare word continues the previous
+    # value, so "colors=W,U,seed=7" works. Keys: colors (letters like WU, a count 1-5, or any), seed, size.
+    def build_random_deck(spec, default_seed)
+      args = parse_spec(spec.to_s)
+      deck = deck_builder.build(colors: args.delete("colors") || :any, seed: Integer(args.delete("seed") || default_seed),
+                                size: Integer(args.delete("size") || DeckBuilder::BASE_SIZE))
+      raise ArgumentError, "unknown random deck option(s): #{args.keys.join(", ")}" unless args.empty?
+
+      deck
+    end
+
+    def parse_spec(spec)
+      key = nil
+      spec.split(/[\s,;]+/).reject(&:empty?).each_with_object({}) do |word, out|
+        if word.include?("=")
+          key, value = word.split("=", 2)
+          out[key] = value
+        elsif key
+          out[key] = "#{out[key]},#{word}"
+        else
+          raise ArgumentError, "random deck spec: expected key=value, got #{word.inspect}"
+        end
+      end
+    end
+
+    # One builder over the --pool, for every random deck of this run.
+    def deck_builder
+      raise ArgumentError, "random decks need --pool FILE (a JSON array of cards)" unless @options[:pool]
+
+      @deck_builder ||= DeckBuilder.new(JSON.parse(File.read(@options[:pool])))
+    end
+
+    def start_game
+      @options[:load] ? load_game : new_game
+    rescue Error, ArgumentError, SystemCallError, JSON::ParserError => e
+      say "error: #{e.message}"
+      nil
+    end
+
+    def new_game
+      decks = [@options[:deck1], @options[:deck2]].each_with_index.map { |deck, i| deck_for(deck, i) }
+      players = @options[:names].zip(decks).map { |name, deck| Player.new(name: name, deck: deck) }
+      @setup = Setup.new(*players)
+      @setup.new_game(seed: @options[:seed])
+    end
+
+    # A deck file, or "random[:SPEC]" for one built from --pool (seed defaults to game seed + seat).
+    # Remembers each deck's label for the intro.
+    def deck_for(deck, seat)
+      raise ArgumentError, "pass --deck#{seat + 1}: a deck file (see examples/decks) or random[:SPEC] with --pool" if deck.nil?
+
+      if deck.start_with?("random")
+        doc = build_random_deck(deck.delete_prefix("random").delete_prefix(":"), @options[:seed] + seat)
+        @options[:"deck#{seat + 1}"] = doc["description"]
+        return doc
+      end
+      JSON.parse(File.read(deck)).tap { @options[:"deck#{seat + 1}"] = it["name"] || File.basename(deck, ".json") }
+    end
+
+    # A saved game carries its cards (see #save), so it resumes without the decks.
+    def load_game
+      data = JSON.parse(File.read(@options[:load]))
+      cards = data.fetch("cards") { raise ArgumentError, "#{@options[:load]}: not a game saved with the s command" }
+      Game.import(data, catalog: Catalog.from_definitions(cards))
+    end
+
+    def intro
+      return if @options[:quiet]
+
+      say "Enjine #{VERSION} (Comprehensive Rules #{RULES_VERSION}) — seed #{@game.state.seed}"
+      say "#{@game.names[0]}: #{@options[:deck1]}   #{@game.names[1]}: #{@options[:deck2]}   — type ? for help"
+      show_events(@game.history.last) if @game.history.last
+    end
+
+    def loop_decisions
+      count = 0
+      until @game.over?
+        if count >= @options[:max_decisions]
+          @game.concede(@game.pending_decision.player)
+          break
+        end
+        decision = @game.pending_decision
+        seat = @seats.fetch(decision.player)
+        auto = seat == :human && only_pass?(decision) # nothing else to do: pass for them
+        option = if seat != :human then seat.choose(decision)
+                 elsif auto then { type: "pass" }
+                 else ask(decision)
+                 end
+        break if option == :quit
+        next if option == :again
+
+        entry = @game.submit(option)
+        count += 1
+        show_events(entry, auto:) unless @options[:quiet]
+      end
+    end
+
+    def ask(decision)
+      show_board(decision)
+      loop do
+        @out.print "#{decision.player}> "
+        line = @input.gets
+        return :quit if line.nil?
+
+        result = command(line.strip, decision)
+        return result unless result.nil?
+      end
+    end
+
+    def show_board(decision)
+      say @text.board(@game.view_for(viewer(decision)))
+      say ""
+      say @text.decision(decision)
+      decision.options.each_with_index { |opt, i| say format("  %2d) %s", i + 1, @text.option(opt)) }
+    end
+
+    def viewer(decision) = @options[:observer] ? :observer : decision.player
+
+    # Returns an option, :quit, :again (decision changed), or nil to keep asking.
+    def command(line, decision)
+      case line
+      when /\A\d+\z/
+        option = decision.options[line.to_i - 1]
+        option || (say("Choose 1-#{decision.options.size}.") && nil)
+      when "b" then show_board(decision) && nil
+      when "o"
+        @options[:observer] = !@options[:observer]
+        say "Observer view #{@options[:observer] ? "on" : "off"}."
+        show_board(decision)
+        nil
+      when /\Ah(?:\s+(\d+))?\z/ then show_history(Integer(::Regexp.last_match(1) || 10)) && nil
+      when "u" then undo
+      when /\As\s+(\S+)\z/ then save(::Regexp.last_match(1)) && nil
+      when "c" then @game.concede(decision.player) && :again
+      when "q" then :quit
+      when "?", "help" then say(HELP) && nil
+      else say("Unknown command. Type ? for help.") && nil
+      end
+    end
+
+    # Priority where passing is the only real choice: a human seat passes without being asked. Mana abilities
+    # don't count: with nothing castable or activatable to spend it on, the mana would just empty (CR 500.4).
+    def only_pass?(decision)
+      decision.kind == "priority" && decision.options.all? { %w[pass activate_mana].include?(it[:type]) }
+    end
+
+    def undo
+      log = @game.decision_log
+      if log.empty? || @setup.nil?
+        say(@setup ? "Nothing to undo." : "Undo needs a game started in this session.")
+        return nil
+      end
+      @game = @setup.new_game(seed: @game.state.seed).apply(log[0...-1])
+      @text = Text.new(@game)
+      say "Undid #{@text.option(log.last.transform_keys(&:to_sym))}."
+      :again
+    end
+
+    def save(path)
+      File.write(path, JSON.generate(@game.to_h.merge("cards" => @game.catalog.reject(&:token?).map(&:to_h))))
+      say "Saved to #{path}. Resume with: enjine --load #{path}"
+    end
+
+    def show_history(count)
+      viewer = @options[:observer] ? :observer : @game.pending_decision&.player || :observer
+      @game.history_for(viewer).last(count).each do |entry|
+        who = if entry["player"]
+                "#{entry["player"]}: #{entry["option"] ? @text.option(entry["option"].transform_keys(&:to_sym)) : entry["kind"]}"
+              else
+                "(game)"
+              end
+        say "  ##{entry["seq"]} T#{entry["turn"]} #{entry["step"] || "pregame"} — #{who}"
+        @text.events(entry["events"]).each { say "      #{it}" }
+      end
+    end
+
+    # An automatic pass doesn't print its own "passes" line; what it caused (a resolution, the next step) does.
+    def show_events(entry, auto: false)
+      viewer = @options[:observer] || @seats.values.none?(:human) ? :observer : entry.player || :observer
+      events = entry.for_viewer(viewer)["events"]
+      events = events.reject { it["type"] == "priority_passed" && it["player"] == entry.player } if auto
+      lines = @text.events(events)
+      lines.each { say "  #{it}" }
+    end
+
+    def say(text)
+      @out.puts(text) unless text.nil?
+      true
+    end
+  end
+end

data/lib/enjine/decisions/bottom.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Enjine
+  module Decisions
+    # CR 103.5: taking a mulligan ends with putting N cards from the new hand on the
+    # bottom of the library (asked once per card, so the order is the order chosen),
+    # before the next keep/mulligan declaration.
+    class Bottom < Base
+      def self.doc
+        "Right after a mulligan, put one card from the new hand on the bottom of the library: " \
+          '`{type: "bottom", object: id}`, once per mulligan taken so far, before declaring again. ' \
+          "Hidden from the opponent (CR 103.5)."
+      end
+
+      def self.options(engine, pending)
+        engine.player(pending["player"]).hand.map { |id| { type: "bottom", object: id } }
+      end
+
+      def self.submit(engine, _pending, option)
+        engine.move!(option[:object], :library, position: :bottom, reason: "mulligan_bottom")
+        engine.next_bottom_or_declaration!
+      end
+
+      # Which card went to the bottom is hidden from the opponent.
+      def self.redact(option, viewer_is_decider) = viewer_is_decider ? option : { type: "bottom" }
+    end
+    register("bottom", Bottom)
+  end
+end