clack 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82be7312cfdade424ca896c9ddb5c70e2bfadadc5f61c411a073d01d1daa73c5
-  data.tar.gz: 2322b602de289654d8ba79925b804027b49a2027eb1e76fe8708d315527706a6
+  metadata.gz: 3035b53cb615be8f42827389fc118990457a06e20e9a118c9eb77a97ff5352f8
+  data.tar.gz: 98b12f8e74d475a50987a10c719f231050d83484989acd101c4e03bf11ad4b5e
 SHA512:
-  metadata.gz: 2412c28b3f625313df7249154a2a7a72cd039e336f3ee2764130e7dc52a5f932358a1576bc793d8fa33b5862d60cf5dff319a5b6495546bd59cef24714c93b1f
-  data.tar.gz: dc26d51d23d264c510c913383e448b3b8552312d1a1a78db7cba71e69ace120cc8638f69adc615fb844652065520947286a46cf75657a6a8ecdbcb499ee58bfc
+  metadata.gz: 770e87fe78a09c35ed8150aaee98dbc75ccadb8d23ba39a2b2ba684e00e5cf50b536e1cc0bce00aee9e9aaf22baa2dad566c75c0f64d7b80d799a70009bd2057
+  data.tar.gz: f77bf005240ce8533d1b1110bcd430409847fa9263682df3b7362c72b599570a77ad9eb2fad31bbc8690599348bdbd026a05733d5dad357aaa9824120382c8f5

data/CHANGELOG.md

@@ -2,16 +2,24 @@
 
 ## [Unreleased]
 
+## [0.1.2]
+
 ### Added
-- Full prompt library: text, password, confirm, select, multiselect, autocomplete, path, select_key, spinner, progress, tasks, group_multiselect
-- `Clack.group` for chaining prompts with shared results
-- `Clack.stream` for streaming output from commands and iterables
-- Vim-style navigation (`hjkl`) alongside arrow keys
-- Zero runtime dependencies
+- `multiline_text` prompt for multi-line input (Ctrl+D to submit)
+- `help:` option on all prompts for contextual help text
+- Documentation for blocking validation (database/API calls work out of the box)
+
+## [0.1.1]
 
-### Changed
-- Ruby 3.2+ support
+### Fixed
+- Path prompt now correctly rejects paths outside root (fixed boundary check bug)
+- Password backspace properly removes Unicode grapheme clusters, not just bytes
+- Terminal cleanup handles closed output streams gracefully
+- SIGWINCH handler uses explicit signal check instead of rescue
+
+### Added
+- Terminal resize support via SIGWINCH signal handling
 
 ## [0.1.0]
 
-Initial release.
+Initial release with full prompt library.

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Steve Whittaker
+Copyright (c) 2026 Steve Whittaker
 
 This project is a Ruby port of Clack (https://github.com/bombshell-dev/clack)
 Originally created by Nate Moore and contributors, licensed under MIT.

data/README.md

@@ -10,7 +10,6 @@ A faithful Ruby port of [@clack/prompts](https://github.com/bombshell-dev/clack)
 
 ## Why Clack?
 
-- **Zero dependencies** - Pure Ruby, stdlib only
 - **Beautiful by default** - Thoughtfully designed prompts that just look right
 - **Vim-friendly** - Navigate with `hjkl` or arrow keys
 - **Accessible** - Graceful ASCII fallbacks for limited terminals

data/lib/clack/core/prompt.rb

@@ -27,6 +27,36 @@ module Clack
     #   end
     #
     class Prompt
+      # Track active prompts for SIGWINCH notification.
+      # Signal handler may fire during register/unregister. We can't use
+      # .dup (allocates, forbidden in trap context) so we accept a benign
+      # race: worst case, a prompt misses one resize notification.
+      @active_prompts = []
+
+      class << self
+        attr_reader :active_prompts
+
+        # Register a prompt instance for resize notifications
+        def register(prompt)
+          @active_prompts << prompt
+        end
+
+        def unregister(prompt)
+          @active_prompts.delete(prompt)
+        end
+
+        # Set up SIGWINCH handler (called once on load).
+        # Signal handlers must avoid mutex/complex operations.
+        def setup_signal_handler
+          return if Clack::Environment.windows?
+          return unless Signal.list.key?("WINCH")
+
+          Signal.trap("WINCH") do
+            @active_prompts.each(&:request_redraw)
+          end
+        end
+      end
+
       # @return [Symbol] current state (:initial, :active, :error, :submit, :cancel)
       attr_reader :state
       # @return [Object] the current/final value
@@ -35,11 +65,13 @@ module Clack
       attr_reader :error_message
 
       # @param message [String] the prompt message to display
+      # @param help [String, nil] optional help text shown below the message
       # @param validate [Proc, nil] optional validation proc; returns error string or nil
       # @param input [IO] input stream (default: $stdin)
       # @param output [IO] output stream (default: $stdout)
-      def initialize(message:, validate: nil, input: $stdin, output: $stdout)
+      def initialize(message:, help: nil, validate: nil, input: $stdin, output: $stdout)
         @message = message
+        @help = help
         @validate = validate
         @input = input
         @output = output
@@ -48,6 +80,13 @@ module Clack
         @error_message = nil
         @prev_frame = nil
         @cursor = 0
+        @needs_redraw = false
+      end
+
+      # Request a full redraw on next render cycle.
+      # Called by SIGWINCH handler when terminal is resized.
+      def request_redraw
+        @needs_redraw = true
       end
 
       # Run the prompt interaction loop.
@@ -57,6 +96,7 @@ module Clack
       #
       # @return [Object, Clack::CANCEL] the submitted value or CANCEL sentinel
       def run
+        Prompt.register(self)
         setup_terminal
         render
         @state = :active
@@ -72,6 +112,7 @@ module Clack
         finalize
         (terminal_state? && @state == :cancel) ? CANCEL : @value
       ensure
+        Prompt.unregister(self)
         cleanup_terminal
       end
 
@@ -121,9 +162,16 @@ module Clack
       end
 
       # Render the current frame using differential rendering.
-      # Only redraws if the frame content has changed.
+      # Only redraws if the frame content has changed or redraw was requested.
       def render
         frame = build_frame
+
+        # Force redraw if terminal was resized
+        if @needs_redraw
+          @needs_redraw = false
+          @prev_frame = nil
+        end
+
         return if frame == @prev_frame
 
         if @state == :initial
@@ -176,6 +224,8 @@ module Clack
 
       def cleanup_terminal
         @output.print Cursor.show
+      rescue IOError, SystemCallError
+        # Output unavailable - terminal may need manual reset
       end
 
       def restore_cursor
@@ -198,6 +248,12 @@ module Clack
         (@state == :error) ? Colors.yellow(Symbols::S_BAR_END) : Colors.gray(Symbols::S_BAR_END)
       end
 
+      def help_line
+        return "" unless @help
+
+        "#{bar}  #{Colors.dim(@help)}\n"
+      end
+
       def cursor_block
         Colors.inverse(" ")
       end

data/lib/clack/core/settings.rb

@@ -10,6 +10,7 @@ module Clack
       KEY_BACKSPACE = "\b"        # ASCII 8: Backspace
       KEY_DELETE = "\u007F"       # ASCII 127: Delete (often sent by backspace key)
       KEY_CTRL_C = "\u0003"       # ASCII 3: Ctrl+C (interrupt)
+      KEY_CTRL_D = "\u0004"       # ASCII 4: Ctrl+D (EOF, used for multiline submit)
       KEY_ESCAPE = "\e"           # ASCII 27: Escape
       KEY_ENTER = "\r"            # ASCII 13: Carriage return
       KEY_NEWLINE = "\n"          # ASCII 10: Line feed

data/lib/clack/prompts/autocomplete.rb

@@ -89,6 +89,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
         lines << "#{active_bar}  #{input_display}\n"
 
         visible_options.each_with_index do |opt, idx|

data/lib/clack/prompts/autocomplete_multiselect.rb

@@ -136,6 +136,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
         lines << "#{active_bar}  #{Colors.dim("Search:")} #{search_input_display}#{match_count}\n"
 
         visible_options.each_with_index do |opt, idx|

data/lib/clack/prompts/confirm.rb

@@ -65,6 +65,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
         lines << "#{bar}  #{options_display}\n"
         lines << "#{Colors.gray(Symbols::S_BAR_END)}\n"
         lines.join

data/lib/clack/prompts/group_multiselect.rb

@@ -59,6 +59,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
 
         prev_was_group = false
         @flat_items.each_with_index do |item, idx|

data/lib/clack/prompts/multiline_text.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Clack
+  module Prompts
+    # Multi-line text input prompt with line navigation.
+    #
+    # Features:
+    # - Enter inserts newline, Ctrl+D submits
+    # - Arrow key navigation (up/down between lines, left/right within line)
+    # - Backspace merges lines when at line start
+    # - Validation support
+    #
+    # @example Basic usage
+    #   message = Clack.multiline_text(message: "Enter your commit message:")
+    #
+    # @example With initial value and validation
+    #   content = Clack.multiline_text(
+    #     message: "Description:",
+    #     initial_value: "feat: ",
+    #     validate: ->(v) { "Required!" if v.strip.empty? }
+    #   )
+    #
+    class MultilineText < Core::Prompt
+      # @param message [String] the prompt message
+      # @param initial_value [String, nil] pre-filled editable text (can contain newlines)
+      # @param validate [Proc, nil] validation proc returning error string or nil
+      # @param opts [Hash] additional options passed to {Core::Prompt}
+      def initialize(message:, initial_value: nil, **opts)
+        super(message:, **opts)
+        @lines = parse_initial_value(initial_value)
+        @line_index = @lines.length - 1
+        @column = current_line.grapheme_clusters.length
+      end
+
+      protected
+
+      def handle_key(key)
+        return if terminal_state?
+
+        @state = :active if @state == :error
+
+        case key
+        when Core::Settings::KEY_CTRL_D
+          submit
+        when Core::Settings::KEY_ESCAPE, Core::Settings::KEY_CTRL_C
+          @state = :cancel
+        when Core::Settings::KEY_ENTER, Core::Settings::KEY_NEWLINE
+          insert_newline
+        else
+          handle_input(key)
+        end
+      end
+
+      def handle_input(key)
+        case key
+        when "\e[A" then move_up
+        when "\e[B" then move_down
+        when "\e[C" then move_right
+        when "\e[D" then move_left
+        else handle_text_input(key)
+        end
+      end
+
+      def submit
+        @value = @lines.join("\n")
+        super
+      end
+
+      def build_frame
+        lines = []
+        lines << "#{bar}\n"
+        lines << "#{symbol_for_state}  #{@message} #{Colors.dim("(Ctrl+D to submit)")}\n"
+        lines << help_line
+
+        @lines.each_with_index do |line, idx|
+          display = (idx == @line_index) ? line_with_cursor(line) : line
+          lines << "#{active_bar}  #{display}\n"
+        end
+
+        lines << "#{bar_end}\n"
+        lines[-1] = "#{Colors.yellow(Symbols::S_BAR_END)}  #{Colors.yellow(@error_message)}\n" if @state == :error
+
+        lines.join
+      end
+
+      def build_final_frame
+        lines = []
+        lines << "#{bar}\n"
+        lines << "#{symbol_for_state}  #{@message}\n"
+
+        if @state == :cancel
+          @lines.each { |line| lines << "#{bar}  #{Colors.strikethrough(Colors.dim(line))}\n" }
+        else
+          @lines.each { |line| lines << "#{bar}  #{Colors.dim(line)}\n" }
+        end
+
+        lines.join
+      end
+
+      private
+
+      def parse_initial_value(value)
+        return [""] if value.nil? || value.empty?
+
+        value.split("\n", -1) # -1 preserves trailing empty strings
+      end
+
+      def current_line
+        @lines[@line_index] || ""
+      end
+
+      def line_with_cursor(line)
+        chars = line.grapheme_clusters
+        return cursor_block if chars.empty?
+        return "#{line}#{cursor_block}" if @column >= chars.length
+
+        before = chars[0...@column].join
+        current = Colors.inverse(chars[@column])
+        after = chars[(@column + 1)..].join
+        "#{before}#{current}#{after}"
+      end
+
+      def insert_newline
+        chars = current_line.grapheme_clusters
+        before = chars[0...@column].join
+        after = chars[@column..].join
+
+        @lines[@line_index] = before
+        @lines.insert(@line_index + 1, after)
+        @line_index += 1
+        @column = 0
+      end
+
+      def move_up
+        return if @line_index.zero?
+
+        @line_index -= 1
+        clamp_column
+      end
+
+      def move_down
+        return if @line_index >= @lines.length - 1
+
+        @line_index += 1
+        clamp_column
+      end
+
+      def move_left
+        return if @column.zero?
+
+        @column -= 1
+      end
+
+      def move_right
+        max = current_line.grapheme_clusters.length
+        return if @column >= max
+
+        @column += 1
+      end
+
+      def clamp_column
+        max = current_line.grapheme_clusters.length
+        @column = [@column, max].min
+      end
+
+      def handle_text_input(key)
+        return handle_backspace if Core::Settings.backspace?(key)
+        return unless Core::Settings.printable?(key)
+
+        chars = current_line.grapheme_clusters
+        chars.insert(@column, key)
+        @lines[@line_index] = chars.join
+        @column += 1
+      end
+
+      def handle_backspace
+        if @column.zero?
+          return if @line_index.zero?
+
+          merge_line_up
+        else
+          chars = current_line.grapheme_clusters
+          chars.delete_at(@column - 1)
+          @lines[@line_index] = chars.join
+          @column -= 1
+        end
+      end
+
+      def merge_line_up
+        return if @line_index.zero?
+
+        current_content = @lines.delete_at(@line_index)
+        @line_index -= 1
+        prev_length = current_line.grapheme_clusters.length
+        @lines[@line_index] = current_line + current_content
+        @column = prev_length
+      end
+    end
+  end
+end

data/lib/clack/prompts/multiselect.rb

@@ -94,6 +94,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
 
         visible_options.each_with_index do |opt, idx|
           actual_idx = @scroll_offset + idx

data/lib/clack/prompts/password.rb

@@ -30,7 +30,8 @@ module Clack
         return unless Core::Settings.printable?(key)
 
         if Core::Settings.backspace?(key)
-          @value = @value.chop
+          clusters = @value.grapheme_clusters
+          @value = (clusters.length > 0) ? clusters[0..-2].join : ""
         else
           @value += key
         end
@@ -40,6 +41,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
         lines << "#{active_bar}  #{masked_display}\n"
         lines << "#{bar_end}\n"
 
@@ -53,7 +55,7 @@ module Clack
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
 
-        masked = @mask * @value.length
+        masked = @mask * @value.grapheme_clusters.length
         display = (@state == :cancel) ? Colors.strikethrough(Colors.dim(masked)) : Colors.dim(masked)
         lines << "#{bar}  #{display}\n"
 
@@ -63,7 +65,7 @@ module Clack
       private
 
       def masked_display
-        masked = @mask * @value.length
+        masked = @mask * @value.grapheme_clusters.length
         return cursor_block if masked.empty?
 
         "#{masked}#{cursor_block}"

data/lib/clack/prompts/path.rb

@@ -92,6 +92,12 @@ module Clack
       def submit_selection
         path = @value.empty? ? @root : resolve_path(@value)
 
+        unless path_within_root?(path)
+          @error_message = "Path must be within #{@root}"
+          @state = :error
+          return
+        end
+
         if @validate
           result = @validate.call(path)
           if result
@@ -109,6 +115,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
         lines << "#{active_bar}  #{input_display}\n"
 
         visible_suggestions.each_with_index do |path, idx|
@@ -138,6 +145,13 @@ module Clack
 
       def update_suggestions
         base_path = resolve_path(@value)
+
+        # Only show suggestions for paths within root
+        unless path_within_root?(base_path)
+          @suggestions = []
+          return
+        end
+
         search_dir = File.directory?(base_path) ? base_path : File.dirname(base_path)
         prefix = File.directory?(base_path) ? "" : File.basename(base_path).downcase
 
@@ -157,10 +171,10 @@ module Clack
 
       def format_entry(dir, entry)
         full_path = File.join(dir, entry)
-        if full_path.start_with?(@root)
+        if full_path == @root || full_path.start_with?("#{@root}/")
           # Show relative path without leading ./
           path = full_path[@root.length..]
-          path = path.sub(%r{^/}, "") # Remove leading slash
+          path = path.sub(%r{^/}, "")
           path = entry if path.empty?
         else
           path = full_path
@@ -172,13 +186,21 @@ module Clack
       def resolve_path(input)
         return @root if input.empty?
 
-        if input.start_with?("/")
+        path = if input.start_with?("/")
           input
         elsif input.start_with?("~")
           File.expand_path(input)
         else
           File.join(@root, input)
         end
+
+        # Canonicalize to resolve .. and symlinks
+        File.expand_path(path)
+      end
+
+      def path_within_root?(path)
+        expanded = File.expand_path(path)
+        expanded == @root || expanded.start_with?("#{@root}/")
       end
 
       def visible_suggestions

data/lib/clack/prompts/progress.rb

@@ -35,7 +35,6 @@ module Clack
         @message = message
         @output = output
         @started = false
-        @rendered_once = false
         @width = 40
       end
 
@@ -106,17 +105,13 @@ module Clack
       def render
         return unless @started
 
-        # Move cursor up and clear line if not first render
-        if @rendered_once
-          @output.print "\e[1A\e[2K"
-        end
-        @rendered_once = true
-        @output.puts "#{symbol}  #{progress_bar} #{percentage}#{message_text}"
+        @output.print "\r\e[2K"  # Return to start of line and clear it
+        @output.print "#{symbol}  #{progress_bar} #{percentage}#{message_text}"
+        @output.flush
       end
 
       def render_final(state)
-        # Move up and clear the progress line
-        @output.print "\e[1A\e[2K" if @rendered_once
+        @output.print "\r\e[2K"  # Clear the progress line
         sym = (state == :success) ? Colors.green(Symbols::S_STEP_SUBMIT) : Colors.red(Symbols::S_STEP_CANCEL)
         @output.puts "#{sym}  #{@message}"
       end

data/lib/clack/prompts/select.rb

@@ -69,6 +69,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
 
         visible_options.each_with_index do |opt, idx|
           actual_idx = @scroll_offset + idx

data/lib/clack/prompts/select_key.rb

@@ -55,6 +55,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
 
         @options.each do |opt|
           lines << "#{bar}  #{option_display(opt)}\n"

data/lib/clack/prompts/text.rb

@@ -70,6 +70,7 @@ module Clack
         lines = []
         lines << "#{bar}\n"
         lines << "#{symbol_for_state}  #{@message}\n"
+        lines << help_line
         lines << "#{active_bar}  #{input_display}\n"
         lines << "#{bar_end}\n" if @state == :active || @state == :initial
 

data/lib/clack/validators.rb

@@ -4,11 +4,22 @@ module Clack
   # Built-in validators for common validation patterns.
   # Use these with the `validate:` option on prompts.
   #
+  # Validation procs can perform any operation including slow I/O (database
+  # lookups, API calls, etc.) - they simply block until complete.
+  #
   # @example Using built-in validators
   #   Clack.text(message: "Name?", validate: Clack::Validators.required)
   #   Clack.text(message: "Email?", validate: Clack::Validators.format(/@/, "Must be an email"))
   #   Clack.password(message: "Password?", validate: Clack::Validators.min_length(8))
   #
+  # @example Database validation (blocking I/O)
+  #   Clack.text(
+  #     message: "Email?",
+  #     validate: ->(email) {
+  #       "Already taken" if User.exists?(email: email)
+  #     }
+  #   )
+  #
   # @example Combining validators
   #   Clack.text(
   #     message: "Username?",

data/lib/clack/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clack
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/lib/clack.rb

@@ -12,6 +12,7 @@ require_relative "clack/core/prompt"
 require_relative "clack/core/options_helper"
 require_relative "clack/core/text_input_helper"
 require_relative "clack/prompts/text"
+require_relative "clack/prompts/multiline_text"
 require_relative "clack/prompts/password"
 require_relative "clack/prompts/confirm"
 require_relative "clack/prompts/select"
@@ -128,6 +129,19 @@ module Clack
       Prompts::Text.new(message:, **opts).run
     end
 
+    # Prompt for multi-line text input.
+    #
+    # Enter inserts a newline, Ctrl+D submits. Useful for commit messages,
+    # notes, or any multi-line content.
+    #
+    # @param message [String] the prompt message
+    # @param initial_value [String, nil] pre-filled editable text (can contain newlines)
+    # @param validate [Proc, nil] validation function returning error message or nil
+    # @return [String, CANCEL] user input (lines joined with \n) or CANCEL if cancelled
+    def multiline_text(message:, **opts)
+      Prompts::MultilineText.new(message:, **opts).run
+    end
+
     # Prompt for password input (masked display).
     #
     # @param message [String] the prompt message
@@ -574,3 +588,6 @@ previous_int_handler = trap("INT") do
   else exit(130)
   end
 end
+
+# Set up SIGWINCH handler for terminal resize
+Clack::Core::Prompt.setup_signal_handler

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clack
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Steve Whittaker
@@ -39,6 +39,7 @@ files:
 - lib/clack/prompts/autocomplete_multiselect.rb
 - lib/clack/prompts/confirm.rb
 - lib/clack/prompts/group_multiselect.rb
+- lib/clack/prompts/multiline_text.rb
 - lib/clack/prompts/multiselect.rb
 - lib/clack/prompts/password.rb
 - lib/clack/prompts/path.rb