inquirex-tty 0.12.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18c484c5cbd16a7bfa1563c39d859fe48a3e2d783d5a06b186c1fae848703780
-  data.tar.gz: f9f2a1e74c8db8028db8b5d1581ff35b94dd376caf5fbd1acf96ce7b963c72ec
+  metadata.gz: ef0bce06b980c6e167a092cff784d1f63f2eea80d72b78384841455baac1865c
+  data.tar.gz: 87306ae23bf1cb5472d8913970b08c26e420cc1ee5ae3659974195aa0639c97c
 SHA512:
-  metadata.gz: ffd4ae10ed877234d10bdba11d68f82d436d6422bac2d5471759ce14f0ed26ac9fe046aec0ed994693b7f989299ddf13f188c6e8122ec8263ff5fa49b7f79646
-  data.tar.gz: 5290b611af119b6222df018d542e3e41a03d169efdf10cb135f5d565e303e03e5fcdc270f5f778c32856b95f34eed9762bfdc2e40dbd9879e2d0839ab449ef48
+  metadata.gz: 288b6c184460ea72e6e75df023ee6840ebc4a805eb47607c2e0735235f02d43842be5526219dde5a0caae18668017c87430d51995f412e55458b938dd69b1abe
+  data.tar.gz: a178284089b5f66e270d6f9aa4c940be8445edd9d09b2b04ac7b8cec5c132b637ec3575567423c609cde82cddb13af9fe1575512dd7c84d9806c299d826c5b32

data/CHANGELOG.md

@@ -5,11 +5,12 @@
 Hand-written until `github_changelog_generator` regenerates this file at release. The family-wide notes are in inquirex's `INQUIREX_VERSION_LOG.md`.
 
 - **BREAKING: results go to stdout.** `run` printed its JSON results on stderr; it now prints them on stdout, and draws every prompt, box and progress line on stderr, so `inqt run flow.rb > answers.json` captures a clean document. A caller that read the results from stderr must read stdout. `-o FILE` still writes a file (and now leaves stdout empty); `-o -` names stdout.
-- **Ctrl-B goes back.** At any question after the first, Ctrl-B returns to the previous question with the earlier answer as its default (`Engine#back`, `#can_back?`, `#previous_answer` from inquirex 0.12.0). A tip line under the question names the key. Display and LLM steps in between are stepped over. Cmd-Backspace was considered and rejected: terminals do not send it to a program unless the user maps it by hand.
+- **Going back, skipping and a keymap.** At any question after the first, Backspace on an empty answer (or anywhere in a list) or Ctrl-B returns to the previous question with the earlier answer as its default (`Engine#back`, `#can_back?`, `#previous_answer` from inquirex 0.12). Ctrl-S skips an optional question (`Engine#skip`) and is refused on a required one. `?` on an empty answer shows the keymap. A hint line above each question lists the keys. Display and LLM steps in between are stepped over. Cmd-Backspace was considered and rejected: terminals do not send it to a program unless the user maps it by hand.
+- **Ctrl-C aborts cleanly** with exit status 130 and a one-line message, instead of a stack trace.
 - **Headless runs: `run --answers FILE` and `--yes`.** Preset answers (`{step_id: value}`, JSON or YAML by extension) are fed to the engine through `Inquirex::Headless`; no prompt or renderer is built, standard input is never read, no LLM adapter is called, and the public-IP probe is skipped. `--yes` answers the remaining steps with their defaults. A required step left without an answer exits 1 and names the step on stderr.
 - **Adapter selection comes from inquirex-llm.** `run` builds its LLM adapter with `Inquirex::LLM.adapter`, re-reading inquirex-llm's configuration after `.env` loads. The documented `INQUIREX_LLM_ADAPTER` / `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` order is unchanged, and the default models and limits now follow inquirex-llm's `INQUIREX_LLM_*` variables. An unknown `INQUIREX_LLM_ADAPTER` value now raises an error naming the variable instead of falling through to auto-detection.
 - Step numbers in the progress line start at 1 again (the first step printed as "Step 2").
-- **Requires `inquirex ~> 0.12` and `inquirex-llm ~> 0.12`.** 0.10.0 still required `~> 0.9.5` of both, so it could not be installed beside the 0.10.0 core.
+- **Requires `inquirex ~> 0.12` and `inquirex-llm ~> 0.12`** (locked at 0.12.1; the `openrouter` and `jev` adapters it adds are selectable through `INQUIREX_LLM_ADAPTER`). `irb` is no longer in the Gemfile: through rdoc it pulled in `erb`, a default gem that a local bundle locks with an empty checksum and a frozen CI install then rejects. 0.10.0 still required `~> 0.9.5` of both, so it could not be installed beside the 0.10.0 core.
 - README samples use a fictional person (Alan Turing, `alan.turing@manchester.edu`), as does `examples/10_answers.json`.
 - Ruby 4.1.0-preview1: the suite passes with Bundler 4.0.16; Gemfile.lock moves off Bundler 4.0.10, which fails on 4.1 with `uninitialized constant Pathname::SEPARATOR_PAT`. `spec/inquirex/tty/gemspec_spec.rb` fails when `lib/` requires a library that neither ships with the running Ruby nor is a declared runtime dependency.
 - CircleCI config copied from inquirex core; `.ruby-version` pins 4.1.0-preview1.

data/README.md

@@ -83,7 +83,19 @@ Options:
 
 **Results channel.** The results JSON goes to stdout, and only the results: every prompt, box and progress line of an interactive run is drawn on stderr. `-o FILE` writes the results to the file instead and leaves stdout empty. Until 0.12.0 the results went to stderr.
 
-**Going back.** Press **Ctrl-B** at any question to return to the previous one, with your earlier answer filled in as the default. The tip line under each question after the first names the key. Display steps and LLM steps in between are stepped over.
+**Keys.** A dim hint line above each question lists the navigation keys (`⌫ back · ^S skip · ? keys · ^C abort`); press `?` for the full keymap.
+
+| Key             | Action                                                                  |
+| --------------- | ----------------------------------------------------------------------- |
+| `Enter`         | submit the answer; an empty answer keeps the one shown in parentheses   |
+| `Backspace`     | go back to the previous question (on an empty answer; always in a list) |
+| `Ctrl-B`        | go back to the previous question                                        |
+| `Ctrl-S`        | skip the question (optional questions only)                             |
+| `↑` `↓` `Space` | move and toggle in a list                                               |
+| `?`             | show the keymap (on an empty answer; always in a list)                  |
+| `Ctrl-C`        | abort without saving (exit status 130)                                  |
+
+**Going back** returns to the previous question with your earlier answer filled in as the default. Display steps and LLM steps in between are stepped over. On the first question the back keys do nothing, and `Backspace` with text typed simply deletes a character.
 
 **Headless runs.** With `--answers` or `--yes` the flow runs without a terminal: no prompt is drawn, standard input is never read, and no LLM adapter is called, which makes it the way to run a flow in tests and CI.
 
@@ -454,8 +466,8 @@ inquirex-tty/
     │   ├── graph.rb                # Mermaid diagram export
     │   ├── export.rb               # JSON / YAML serialization
     │   └── version.rb              # Print version info
-    ├── renderer.rb                 # Node → tty-prompt widget dispatcher, Ctrl-B back
-    ├── back_key.rb                 # The back key and the exception that unwinds a prompt
+    ├── renderer.rb                 # Node → tty-prompt widget dispatcher, back/skip/help
+    ├── key_map.rb                  # Navigation keys and the exception that unwinds a prompt
     ├── answers_file.rb             # --answers: JSON or YAML preset answers
     ├── flow_loader.rb              # Load .rb flow definitions
     ├── output_path.rb              # Shared -o/--output path resolution
@@ -467,7 +479,7 @@ inquirex-tty/
 
 `Inquirex::TTY::Renderer` is the core class that maps nodes to tty-prompt calls. It reads the `:tty` widget hint from each node (via `WidgetRegistry` defaults or explicit DSL hints) and dispatches to the matching `render_*` method.
 
-`Renderer#collect(engine)` asks the engine's current step and answers it, or, when the user presses Ctrl-B, calls `Engine#back` and returns `:back`; the run loop then asks the previous question again with `Engine#previous_answer` as its default. Ctrl-B raises `Inquirex::TTY::BackKey::Pressed` from a handler on tty-reader's `:keyctrl_b` event, which unwinds whichever tty-prompt widget is open.
+`Renderer#collect(engine)` asks the engine's current step and answers it, unless the user presses a navigation key: back calls `Engine#back` and returns `:back` (the run loop then asks the previous question again with `Engine#previous_answer` as its default), skip calls `Engine#skip` on an optional step and returns `:skipped` (`:stay` on a required one), and `?` shows the keymap and returns `:help`. `Inquirex::TTY::KeyMap`, a tty-reader listener, raises `Inquirex::TTY::Navigation` for the key, which unwinds whichever tty-prompt widget is open.
 
 The `TTY::Prompt` instance is injectable for testing:
 

data/lib/inquirex/tty/commands/run.rb

@@ -29,6 +29,9 @@ module Inquirex
         def call(flow_file:, **options)
           json = on_stderr { JSON.pretty_generate(results_for(flow_file, **options)) }
           write_results(json, options[:output])
+        rescue ::TTY::Reader::InputInterrupt
+          on_stderr { error("Aborted — no answers were saved.") }
+          exit 130
         rescue Inquirex::TTY::Error => e
           on_stderr { error(e.message) }
           exit 1

data/lib/inquirex/tty/key_map.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module TTY
+    # Raised out of a tty-prompt widget when the user presses a navigation
+    # key, so whichever widget is open (ask, select, multi_select, yes?)
+    # unwinds without returning an answer. tty-prompt offers no hook that
+    # aborts a question, and a subclass per widget would mean overriding the
+    # read loop of each one; one exception covers them all.
+    class Navigation < StandardError
+      # @return [Symbol] :back, :skip or :help
+      attr_reader :action
+
+      # @param action [Symbol] :back, :skip or :help
+      def initialize(action)
+        @action = action
+        super("navigation: #{action}")
+      end
+    end
+
+    # The keys that navigate a TTY run, as a tty-reader listener that turns
+    # them into {Navigation} exceptions while a collecting prompt is open.
+    #
+    # Backspace and "?" are also editing keys, so in a text answer they
+    # navigate only while the answer is empty: Backspace on an empty line
+    # goes back, Backspace after text deletes a character, and "what?" types
+    # a question mark. Lists have no text, so there they always navigate.
+    # Ctrl-B goes back from anywhere: tty-reader maps byte 0x02 to :ctrl_b in
+    # every terminal and tty-prompt binds nothing to it.
+    #
+    # tty-reader reports a key after it has edited the line, so the listener
+    # cannot ask "was the line empty?" directly. It keeps its own count of the
+    # characters typed instead, from how much each event's line grew or
+    # shrank. A pre-filled answer is a tty-prompt +default:+, shown beside
+    # the question rather than typed into the line, so every line starts empty.
+    #
+    # @example Wrap a prompt call
+    #   prompt.subscribe(KeyMap.new(can_back: engine.can_back?))
+    class KeyMap
+      # tty-reader key names that edit text and go back on an empty answer.
+      BACKSPACE = %i[backspace ctrl_h].freeze
+
+      # Every navigation key, for the help box.
+      BINDINGS = [
+        ["Enter",      "submit the answer (an empty answer keeps the one shown)"],
+        ["Backspace",  "go back to the previous question (on an empty answer)"],
+        ["Ctrl-B",     "go back to the previous question"],
+        ["Ctrl-S",     "skip the question (optional questions only)"],
+        ["↑ ↓  Space", "move and toggle in a list"],
+        ["?",          "show this help (on an empty answer)"],
+        ["Ctrl-C",     "abort without saving"]
+      ].freeze
+
+      # @param can_back [Boolean] whether there is a question to go back to;
+      #   when false the back keys do nothing
+      def initialize(can_back: true)
+        @can_back = can_back
+        @length   = 0
+        @line     = nil
+      end
+
+      # The one-line reminder drawn above each collecting prompt.
+      #
+      # @param can_back [Boolean]
+      # @return [String]
+      def self.hint(can_back:)
+        [("⌫ back" if can_back), "^S skip", "? keys", "^C abort"].compact.join(" · ")
+      end
+
+      # tty-reader calls this for every key, after any key-specific handler.
+      #
+      # @param event [TTY::Reader::KeyEvent]
+      # @return [void]
+      # @raise [Navigation] when the key navigates
+      def keypress(event)
+        name = event.key.name
+        raise Navigation, :skip if name == :ctrl_s
+        raise Navigation, :back if @can_back && (name == :ctrl_b || (BACKSPACE.include?(name) && @length.zero?))
+        raise Navigation, :help if event.value == "?" && @length.zero?
+
+        track(event)
+      end
+
+      private
+
+      # Updates the typed-character count after an editing key.
+      #
+      # A line widget passes its whole line (prompt plus text) with each
+      # event; list widgets pass an empty string, and the only text they hold
+      # is the number typed into an enum_select.
+      #
+      # @param event [TTY::Reader::KeyEvent]
+      # @return [void]
+      def track(event)
+        return reset if %i[return enter].include?(event.key.name)
+        return track_keys(event) if event.line.to_s.empty?
+
+        delta = @line ? event.line.length - @line.length : first_delta(event)
+        @length = [@length + delta, 0].max
+        @line = event.line
+      end
+
+      # The first event of a line has nothing to diff against; the line
+      # started empty, so only a printable character changed it.
+      def first_delta(event) = printable?(event.value) ? 1 : 0
+
+      def track_keys(event)
+        if BACKSPACE.include?(event.key.name) || event.key.name == :delete
+          @length = [@length - 1, 0].max
+        elsif event.key.name == :num
+          @length += event.value.length
+        end
+      end
+
+      # Enter submits; a widget that reads several lines (multiline text)
+      # starts the next one empty.
+      def reset
+        @length = 0
+        @line = nil
+      end
+
+      def printable?(value)
+        value.to_s.length == 1 && value.match?(/[[:print:]]/)
+      end
+    end
+  end
+end

data/lib/inquirex/tty/renderer.rb

@@ -25,9 +25,9 @@ module Inquirex
     # Header display verb uses TTY::Font for large ASCII-art section titles.
     #
     # {#collect} drives one collecting step against an engine and binds the
-    # back key ({BackKey}): pressed in any open prompt, it steps the engine
-    # back and the caller's loop re-asks the previous question with its
-    # answer as the default.
+    # navigation keys ({KeyMap}): back steps the engine back and the caller's
+    # loop re-asks the previous question with its answer as the default; skip
+    # declines an optional question; "?" shows the keymap.
     class Renderer
       include UIHelper
 
@@ -67,14 +67,16 @@ module Inquirex
         sep(:magenta, "─")
       end
 
-      # Asks the engine's current collecting step and answers it. When the
-      # user presses the back key instead, the engine steps back and nothing
-      # is answered; the caller's loop then asks the previous question again,
-      # pre-filled with the answer it had.
+      # Asks the engine's current collecting step and answers it, unless the
+      # user presses a navigation key ({KeyMap}) instead:
       #
-      # The tip line naming the key appears only when there is somewhere to
-      # go back to, and the key is live only then: on the first question it
-      # does nothing.
+      # - back: the engine steps back and nothing is answered; the caller's
+      #   loop then asks the previous question again, pre-filled with the
+      #   answer it had. Back is offered only when there is somewhere to go
+      #   back to: on the first question the keys do nothing.
+      # - skip: an optional question is skipped (Engine#skip); a required one
+      #   is refused with a notice and asked again.
+      # - help: the keymap is shown, then the loop asks the question again.
       #
       # @example Drive a flow's collecting steps
       #   until engine.finished?
@@ -82,22 +84,33 @@ module Inquirex
       #   end
       #
       # @param engine [Inquirex::Engine] positioned on a collecting step
-      # @return [Symbol] +:answered+, or +:back+ when the engine stepped back
+      # @return [Symbol] +:answered+, +:back+, +:skipped+, +:help+, or +:stay+
+      #   when a required question refused a skip
       def collect(engine)
         step_id  = engine.current_step_id
         can_back = engine.can_back?
-        puts pastel.dim("#{BackKey::LABEL}: back to the previous question") if can_back
+        puts pastel.dim(KeyMap.hint(can_back:))
 
-        answer = with_back_key(can_back) do
+        answer = with_keys(can_back) do
           render(engine.current_step,
             suggestion: engine.suggestion_for(step_id),
             default:    engine.previous_answer(step_id))
         end
         engine.answer(answer)
         :answered
-      rescue BackKey::Pressed
-        go_back(engine)
-        :back
+      rescue Navigation => e
+        navigate(engine, e.action)
+      end
+
+      # Shows every navigation key in a box and waits for a key.
+      #
+      # @return [void]
+      def show_keymap
+        width = KeyMap::BINDINGS.map { |key, _| key.length }.max
+        lines = KeyMap::BINDINGS.map { |key, action| "#{key.ljust(width)}   #{action}" }
+        puts
+        puts box(lines.join("\n"), title: "Keys", bg: :blue, fg: :white, align: :left)
+        prompt.keypress(pastel.dim("Press any key to return to the question..."))
       end
 
       # Renders a node. Returns the collected answer, or +nil+ for display verbs.
@@ -131,40 +144,60 @@ module Inquirex
 
       private
 
-      # Runs the block with the back key live, when +enabled+.
-      #
-      # The handler is registered on the prompt's reader once and consulted
-      # through @back_armed, so the key raises only inside a collecting
-      # prompt: a "Press any key" on a display step treats it as any key.
+      # Runs the block with the navigation keys live. The {KeyMap} listens
+      # only while the block runs, so a "Press any key" on a display step
+      # treats every key as any key.
       #
       # tty-prompt subscribes each question to the reader and unsubscribes it
-      # only when the question returns normally. A question unwound by
-      # {BackKey::Pressed} would stay subscribed and go on reacting to every
-      # later keypress, so the listeners it added are removed here.
+      # only when the question returns normally, and tty-reader's
+      # subscribe-with-a-block does the same. A question unwound by
+      # {Navigation} would stay subscribed and go on reacting to every later
+      # keypress, so every listener added while the block ran, the KeyMap
+      # included, is removed here.
       #
-      # @param enabled [Boolean]
+      # @param can_back [Boolean]
       # @return [Object] the block's value
-      # @raise [BackKey::Pressed] when the key is pressed
-      def with_back_key(enabled)
-        return yield unless enabled && prompt.respond_to?(:on)
+      # @raise [Navigation] when a navigation key is pressed
+      def with_keys(can_back)
+        return yield unless prompt.respond_to?(:subscribe)
 
-        bind_back_key
         listeners = reader_registrations&.to_a
-        @back_armed = true
+        key_map = KeyMap.new(can_back:)
+        prompt.subscribe(key_map)
         yield
-      rescue BackKey::Pressed
-        drop_listeners_since(listeners)
-        raise
       ensure
-        @back_armed = false
+        if key_map
+          drop_listeners_since(listeners)
+          prompt.unsubscribe(key_map)
+        end
       end
 
-      # @return [void]
-      def bind_back_key
-        return if @back_key_bound
+      # Acts on a navigation key pressed during {#collect}.
+      #
+      # @param engine [Inquirex::Engine]
+      # @param action [Symbol] :back, :skip or :help
+      # @return [Symbol] what {#collect} returns
+      def navigate(engine, action)
+        case action
+        when :back then go_back(engine)
+        when :skip then skip(engine)
+        else
+          show_keymap
+          :help
+        end
+      end
 
-        prompt.on(BackKey::EVENT) { |*| raise BackKey::Pressed if @back_armed }
-        @back_key_bound = true
+      # @param engine [Inquirex::Engine]
+      # @return [Symbol] :skipped, or :stay when the question is required
+      def skip(engine)
+        if engine.current_step.required?
+          puts pastel.yellow("  ⚠ This question is required and cannot be skipped.")
+          return :stay
+        end
+
+        puts pastel.dim("↷ skipped #{engine.current_step_id}")
+        engine.skip
+        :skipped
       end
 
       # @param before [Array, nil] the reader's registrations before the prompt opened
@@ -192,11 +225,12 @@ module Inquirex
       # would rerun the extraction and carry the user straight forward again.
       #
       # @param engine [Inquirex::Engine]
-      # @return [void]
+      # @return [Symbol] :back
       def go_back(engine)
         engine.back
         engine.back while llm_step?(engine.current_step) && engine.can_back?
         puts pastel.dim("↩ back to #{engine.current_step_id}")
+        :back
       end
 
       # @param node [Inquirex::Node, nil]

data/lib/inquirex/tty/ui_helper.rb

@@ -39,13 +39,14 @@ module Inquirex
             # @param title [String, nil] optional title on the top border
             # @param bg [Symbol] background color name
             # @param fg [Symbol] foreground color name
+            # @param align [Symbol] :center, :left or :right
             # @return [void]
-            def box(text, title: nil, bg: :green, fg: :white) # rubocop:disable Naming/MethodParameterName
+            def box(text, title: nil, bg: :green, fg: :white, align: :center) # rubocop:disable Naming/MethodParameterName
               w = [width, 80].min
               args = {
                 width:   w,
                 padding: { top: 0, bottom: 0, left: 1, right: 1 },
-                align:   :center,
+                align:   align,
                 style:   { fg: fg, bg: bg,
                          border: { type: :thin, fg: fg, bg: bg } }
               }

data/lib/inquirex/tty/version.rb

@@ -2,6 +2,6 @@
 
 module Inquirex
   module TTY
-    VERSION = "0.12.0"
+    VERSION = "0.12.1"
   end
 end

data/lib/inquirex/tty.rb

@@ -41,7 +41,7 @@ require_relative "tty/ui_helper"
 require_relative "tty/flow_loader"
 require_relative "tty/output_path"
 require_relative "tty/answers_file"
-require_relative "tty/back_key"
+require_relative "tty/key_map"
 require_relative "tty/renderer"
 require_relative "tty/commands/run"
 require_relative "tty/commands/validate"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inquirex-tty
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.12.1
 platform: ruby
 authors:
   - Konstantin Gredeskoul
@@ -195,7 +195,6 @@ files:
   - lefthook.yml
   - lib/inquirex/tty.rb
   - lib/inquirex/tty/answers_file.rb
-  - lib/inquirex/tty/back_key.rb
   - lib/inquirex/tty/commands.rb
   - lib/inquirex/tty/commands/export.rb
   - lib/inquirex/tty/commands/graph.rb
@@ -203,6 +202,7 @@ files:
   - lib/inquirex/tty/commands/validate.rb
   - lib/inquirex/tty/commands/version.rb
   - lib/inquirex/tty/flow_loader.rb
+  - lib/inquirex/tty/key_map.rb
   - lib/inquirex/tty/output_path.rb
   - lib/inquirex/tty/renderer.rb
   - lib/inquirex/tty/ui_helper.rb

data/lib/inquirex/tty/back_key.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Inquirex
-  module TTY
-    # The key that takes a TTY run back to the previous question.
-    #
-    # Ctrl-B, because it arrives: tty-reader maps byte 0x02 to +:ctrl_b+ in
-    # every terminal, and tty-prompt binds nothing to it. Cmd-Backspace, the
-    # first candidate, reaches a program only where the user has mapped it by
-    # hand (iTerm2 sends nothing by default), so a run could never rely on it.
-    module BackKey
-      # @return [Symbol] the tty-reader key name
-      NAME = :ctrl_b
-
-      # @return [Symbol] the event tty-reader publishes when the key is pressed
-      EVENT = :"key#{NAME}"
-
-      # @return [String] how the tip line names the key
-      LABEL = "Ctrl-B"
-
-      # Raised from inside a tty-prompt read loop when the back key is pressed,
-      # so whichever widget is open (ask, select, multi_select, yes?) unwinds
-      # without returning an answer. tty-prompt offers no hook that aborts a
-      # question, and a subclass per widget would mean overriding the read
-      # loop of each one; one exception covers them all.
-      class Pressed < StandardError
-        def initialize(msg = "#{LABEL} pressed") = super
-      end
-    end
-  end
-end