clack 0.1.0

data/lib/clack/stream.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "English"
+require "stringio"
+
+module Clack
+  # Stream logging utility for iterables, enumerables, and IO streams
+  # Similar to Log but works with streaming data in real-time
+  module Stream
+    class << self
+      def info(source, output: $stdout, &block)
+        stream_with_symbol(source, Symbols::S_INFO, :cyan, output, &block)
+      end
+
+      def success(source, output: $stdout, &block)
+        stream_with_symbol(source, Symbols::S_SUCCESS, :green, output, &block)
+      end
+
+      def step(source, output: $stdout, &block)
+        stream_with_symbol(source, Symbols::S_STEP_SUBMIT, :green, output, &block)
+      end
+
+      def warn(source, output: $stdout, &block)
+        stream_with_symbol(source, Symbols::S_WARN, :yellow, output, &block)
+      end
+
+      def error(source, output: $stdout, &block)
+        stream_with_symbol(source, Symbols::S_ERROR, :red, output, &block)
+      end
+
+      def message(source, output: $stdout)
+        each_line(source) do |line|
+          output.puts "#{Colors.gray(Symbols::S_BAR)}  #{line.chomp}"
+          output.flush
+        end
+      end
+
+      # Stream from a subprocess command
+      # Usage: Clack.stream.command("npm install", type: :info)
+      # Returns true on success, false on failure or if command cannot be executed
+      def command(cmd, type: :info, output: $stdout)
+        IO.popen(cmd, err: %i[child out]) do |io|
+          send(type, io, output: output)
+        end
+        $CHILD_STATUS.success?
+      rescue Errno::ENOENT
+        false
+      end
+
+      private
+
+      def stream_with_symbol(source, symbol, color, output)
+        first = true
+        each_line(source) do |line|
+          line = line.chomp
+          if first
+            output.puts "#{Colors.send(color, symbol)}  #{line}"
+            first = false
+          else
+            output.puts "#{Colors.gray(Symbols::S_BAR)}  #{line}"
+          end
+          output.flush
+          yield line if block_given?
+        end
+      end
+
+      def each_line(source, &block)
+        case source
+        when IO, StringIO
+          source.each_line(&block)
+        when String
+          source.each_line(&block)
+        else
+          # Enumerable (Array, etc.)
+          source.each do |item|
+            block.call(item.to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/clack/symbols.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Clack
+  module Symbols
+    class << self
+      # Check if unicode output is enabled.
+      # CLACK_UNICODE=1 forces unicode, CLACK_UNICODE=0 forces ASCII.
+      # Otherwise auto-detects from TTY and TERM.
+      def unicode?
+        return @unicode if defined?(@unicode)
+
+        @unicode = compute_unicode_support
+      end
+
+      def reset!
+        remove_instance_variable(:@unicode) if defined?(@unicode)
+      end
+
+      private
+
+      def compute_unicode_support
+        # Explicit override
+        return ENV["CLACK_UNICODE"] == "1" if ENV["CLACK_UNICODE"]
+
+        # Default: TTY and not dumb terminal
+        $stdout.tty? && ENV["TERM"] != "dumb" && !ENV["NO_COLOR"]
+      end
+    end
+
+    # Step indicators
+    S_STEP_ACTIVE = unicode? ? "◆" : "*"
+    S_STEP_CANCEL = unicode? ? "■" : "x"
+    S_STEP_ERROR = unicode? ? "▲" : "x"
+    S_STEP_SUBMIT = unicode? ? "◇" : "o"
+
+    # Radio buttons
+    S_RADIO_ACTIVE = unicode? ? "●" : ">"
+    S_RADIO_INACTIVE = unicode? ? "○" : " "
+
+    # Checkboxes
+    S_CHECKBOX_ACTIVE = unicode? ? "◻" : "[•]"
+    S_CHECKBOX_SELECTED = unicode? ? "◼" : "[+]"
+    S_CHECKBOX_INACTIVE = unicode? ? "◻" : "[ ]"
+
+    # Password mask
+    S_PASSWORD_MASK = unicode? ? "▪" : "*"
+
+    # Bars and connectors
+    S_BAR = unicode? ? "│" : "|"
+    S_BAR_START = unicode? ? "┌" : "+"
+    S_BAR_END = unicode? ? "└" : "+"
+    S_BAR_H = unicode? ? "─" : "-"
+    S_CORNER_TOP_RIGHT = unicode? ? "╮" : "+"
+    S_CORNER_TOP_LEFT = unicode? ? "╭" : "+"
+    S_CORNER_BOTTOM_RIGHT = unicode? ? "╯" : "+"
+    S_CORNER_BOTTOM_LEFT = unicode? ? "╰" : "+"
+    S_CONNECT_LEFT = unicode? ? "├" : "+"
+
+    # Square corners (for box with rounded: false)
+    S_BAR_START_RIGHT = unicode? ? "┐" : "+"
+    S_BAR_END_RIGHT = unicode? ? "┘" : "+"
+
+    # Log symbols
+    S_INFO = unicode? ? "●" : "*"
+    S_SUCCESS = unicode? ? "◆" : "*"
+    S_WARN = unicode? ? "▲" : "!"
+    S_ERROR = unicode? ? "■" : "x"
+
+    # File system
+    S_FOLDER = unicode? ? "📁" : "[D]"
+    S_FILE = unicode? ? "📄" : "[F]"
+
+    # Spinner frames - quarter circle rotation pattern
+    SPINNER_FRAMES = unicode? ? %w[◒ ◐ ◓ ◑] : %w[• o O 0]
+    SPINNER_DELAY = unicode? ? 0.08 : 0.12
+
+    # Progress bar characters
+    S_PROGRESS_FILLED = unicode? ? "█" : "#"
+    S_PROGRESS_EMPTY = unicode? ? "░" : "-"
+
+    # Alternative progress bar (smoother gradient)
+    S_PROGRESS_BLOCKS = unicode? ? %w[░ ▒ ▓ █] : %w[- = # #]
+  end
+end

data/lib/clack/task_log.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Clack
+  # A streaming log that clears on success and remains on failure
+  # Useful for build output, npm install style streaming, etc.
+  #
+  # @example Basic usage
+  #   tl = Clack.task_log(title: "Building...")
+  #   tl.message("Compiling file 1...")
+  #   tl.message("Compiling file 2...")
+  #   tl.success("Build complete!")  # Clears the log
+  #   # or tl.error("Build failed!") # Keeps the log visible
+  #
+  class TaskLog
+    # @param title [String] Title displayed at the top
+    # @param limit [Integer, nil] Max lines to show (older lines scroll out)
+    # @param retain_log [Boolean] Keep full log history for display on error
+    # @param output [IO] Output stream
+    def initialize(title:, limit: nil, retain_log: false, output: $stdout)
+      @title = title
+      @limit = limit
+      @retain_log = retain_log
+      @output = output
+      @buffer = []
+      @full_buffer = []
+      @groups = []
+      @lines_written = 0
+      @tty = tty_output?(output)
+
+      render_title
+    end
+
+    # Add a message to the log
+    # @param msg [String] Message to display
+    # @param raw [Boolean] If true, don't add newline between messages
+    def message(msg, raw: false)
+      clear_buffer
+      @buffer << msg.to_s.gsub(/\e\[[\d;]*[ABCDEFGHfJKSTsu]/, "") # Strip cursor movement codes
+      apply_limit
+      render_buffer if @tty
+    end
+
+    # Create a named group for messages
+    # @param name [String] Group header name
+    # @return [TaskLogGroup] Group object with message/success/error methods
+    def group(name)
+      grp = TaskLogGroup.new(name, self)
+      @groups << grp
+      grp
+    end
+
+    # Complete with success - clears the log
+    # @param msg [String] Success message
+    # @param show_log [Boolean] If true, show the log even on success
+    def success(msg, show_log: false)
+      clear_all
+      @output.puts "#{Colors.green(Symbols::S_STEP_SUBMIT)}  #{msg}"
+      render_full_buffer if show_log
+      reset_buffers
+    end
+
+    # Complete with error - keeps the log visible
+    # @param msg [String] Error message
+    # @param show_log [Boolean] If false, hide the log
+    def error(msg, show_log: true)
+      clear_all
+      @output.puts "#{Colors.red(Symbols::S_STEP_ERROR)}  #{msg}"
+      render_full_buffer if show_log
+      reset_buffers
+    end
+
+    # @api private
+    def add_group_message(_group, msg)
+      clear_buffer
+      @buffer << msg.to_s
+      apply_limit
+      render_buffer if @tty
+    end
+
+    private
+
+    def render_title
+      @output.puts Colors.gray(Symbols::S_BAR)
+      @output.puts "#{Colors.green(Symbols::S_STEP_SUBMIT)}  #{@title}"
+      @output.puts Colors.gray(Symbols::S_BAR)
+      @lines_written = 3
+    end
+
+    def clear_buffer
+      return unless @tty && @lines_written.positive?
+
+      # Move up and clear the buffer lines (not the title)
+      buffer_lines = @buffer.sum { |line| line.lines.count }
+      return unless buffer_lines.positive?
+
+      @output.print "\e[#{buffer_lines}A" # Move up
+      @output.print "\e[J" # Clear to end
+    end
+
+    def clear_all
+      return unless @tty && @lines_written.positive?
+
+      total_lines = @lines_written + @buffer.sum { |line| line.lines.count }
+      @output.print "\e[#{total_lines}A" # Move up
+      @output.print "\e[J" # Clear to end
+    end
+
+    def render_buffer
+      bar = Colors.gray(Symbols::S_BAR)
+      @buffer.each do |message|
+        print_message_lines(bar, message)
+      end
+    end
+
+    def render_full_buffer
+      bar = Colors.gray(Symbols::S_BAR)
+      lines = @retain_log ? (@full_buffer + @buffer) : @buffer
+      lines.each do |message|
+        print_message_lines(bar, message)
+      end
+    end
+
+    def print_message_lines(bar, message)
+      message.each_line do |line|
+        @output.puts "#{bar}  #{Colors.dim(line.chomp)}"
+      end
+    end
+
+    def tty_output?(output)
+      output.tty?
+    rescue NoMethodError
+      false
+    end
+
+    def apply_limit
+      return unless @limit && @buffer.length > @limit
+
+      overflow = @buffer.shift(@buffer.length - @limit)
+      @full_buffer.concat(overflow) if @retain_log
+    end
+
+    def reset_buffers
+      @buffer.clear
+      @full_buffer.clear
+      @groups.clear
+      @lines_written = 0
+    end
+  end
+
+  # A group within a TaskLog
+  class TaskLogGroup
+    def initialize(name, parent)
+      @name = name
+      @parent = parent
+      @buffer = []
+    end
+
+    # Add a message to this group
+    def message(msg, raw: false)
+      @buffer << msg.to_s
+      @parent.add_group_message(self, msg)
+    end
+
+    # Complete group with success
+    def success(msg)
+      @parent.add_group_message(self, "#{Colors.green("✓")} #{msg}")
+    end
+
+    # Complete group with error
+    def error(msg)
+      @parent.add_group_message(self, "#{Colors.red("✗")} #{msg}")
+    end
+  end
+end

data/lib/clack/utils.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Clack
+  # Utility functions for text manipulation and formatting
+  module Utils
+    class << self
+      # Strip ANSI escape sequences from text
+      # @param text [String] Text with ANSI codes
+      # @return [String] Text without ANSI codes
+      def strip_ansi(text)
+        text.to_s.gsub(/\e\[[0-9;]*[a-zA-Z]/, "")
+      end
+
+      # Get visible length of text (excluding ANSI codes)
+      # @param text [String] Text potentially containing ANSI codes
+      # @return [Integer] Visible character count
+      def visible_length(text)
+        strip_ansi(text).length
+      end
+
+      # Wrap text to a specified width, preserving ANSI codes
+      # @param text [String] Text to wrap
+      # @param width [Integer] Maximum line width
+      # @return [String] Wrapped text
+      def wrap(text, width)
+        return text if width <= 0
+
+        lines = []
+        text.to_s.each_line do |line|
+          lines.concat(wrap_line(line.chomp, width))
+        end
+        lines.join("\n")
+      end
+
+      # Wrap text with a prefix on each line
+      # @param text [String] Text to wrap
+      # @param prefix [String] Prefix for each line (e.g., "│  ")
+      # @param width [Integer] Total width including prefix
+      # @return [String] Wrapped and prefixed text
+      def wrap_with_prefix(text, prefix, width)
+        prefix_len = visible_length(prefix)
+        content_width = width - prefix_len
+        return text if content_width <= 0
+
+        wrapped = wrap(text, content_width)
+        wrapped.lines.map { |line| "#{prefix}#{line.chomp}" }.join("\n")
+      end
+
+      # Truncate text to width with ellipsis
+      # @param text [String] Text to truncate
+      # @param width [Integer] Maximum width
+      # @param ellipsis [String] Ellipsis string (default: "...")
+      # @return [String] Truncated text
+      def truncate(text, width, ellipsis: "...")
+        return text if visible_length(text) <= width
+
+        target = width - ellipsis.length
+        return ellipsis if target <= 0
+
+        # Handle ANSI codes: we need to truncate visible chars while preserving codes
+        truncate_visible(text, target) + ellipsis
+      end
+
+      private
+
+      def wrap_line(line, width)
+        return [line] if visible_length(line) <= width
+
+        words = line.split(/(\s+)/)
+        lines = []
+        current = ""
+        current_len = 0
+
+        words.each do |word|
+          word_len = visible_length(word)
+
+          if current_len + word_len <= width
+            current += word
+            current_len += word_len
+          elsif word_len > width
+            # Word itself is too long, need to break it
+            unless current.empty?
+              lines << current.rstrip
+              current = ""
+              current_len = 0
+            end
+            lines.concat(break_long_word(word, width))
+          else
+            lines << current.rstrip unless current.empty?
+            current = word.lstrip
+            current_len = visible_length(current)
+          end
+        end
+
+        lines << current.rstrip unless current.empty?
+        lines
+      end
+
+      def break_long_word(word, width)
+        lines = []
+        stripped = strip_ansi(word)
+        position = 0
+
+        while position < stripped.length
+          lines << stripped[position, width]
+          position += width
+        end
+
+        lines
+      end
+
+      def truncate_visible(text, target_len)
+        result = ""
+        visible_count = 0
+        position = 0
+
+        while position < text.length && visible_count < target_len
+          if text[position] == "\e" && (match = text[position..].match(/\A\e\[[0-9;]*[a-zA-Z]/))
+            # ANSI sequence - include it but don't count
+            result += match[0]
+            position += match[0].length
+          else
+            result += text[position]
+            visible_count += 1
+            position += 1
+          end
+        end
+
+        # Add reset if we have unclosed ANSI codes
+        result += "\e[0m" if result.include?("\e[") && !result.end_with?("\e[0m")
+        result
+      end
+    end
+  end
+end

data/lib/clack/validators.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Clack
+  # Built-in validators for common validation patterns.
+  # Use these with the `validate:` option on prompts.
+  #
+  # @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 Combining validators
+  #   Clack.text(
+  #     message: "Username?",
+  #     validate: Clack::Validators.combine(
+  #       Clack::Validators.required("Username is required"),
+  #       Clack::Validators.min_length(3, "Must be at least 3 characters"),
+  #       Clack::Validators.max_length(20, "Must be at most 20 characters"),
+  #       Clack::Validators.format(/\A[a-z0-9_]+\z/i, "Only letters, numbers, and underscores")
+  #     )
+  #   )
+  #
+  module Validators
+    class << self
+      # Validates that the input is not empty.
+      #
+      # @param message [String] Custom error message
+      # @return [Proc] Validator proc
+      def required(message = "This field is required")
+        ->(value) { message if value.to_s.strip.empty? }
+      end
+
+      # Validates minimum length.
+      #
+      # @param length [Integer] Minimum length
+      # @param message [String, nil] Custom error message (supports %d placeholder)
+      # @return [Proc] Validator proc
+      def min_length(length, message = nil)
+        msg = message || "Must be at least #{length} characters"
+        ->(value) { msg if value.to_s.length < length }
+      end
+
+      # Validates maximum length.
+      #
+      # @param length [Integer] Maximum length
+      # @param message [String, nil] Custom error message
+      # @return [Proc] Validator proc
+      def max_length(length, message = nil)
+        msg = message || "Must be at most #{length} characters"
+        ->(value) { msg if value.to_s.length > length }
+      end
+
+      # Validates that input matches a regular expression.
+      #
+      # @param pattern [Regexp] Pattern to match
+      # @param message [String] Error message if pattern doesn't match
+      # @return [Proc] Validator proc
+      def format(pattern, message = "Invalid format")
+        ->(value) { message unless pattern.match?(value.to_s) }
+      end
+
+      # Validates that input is in a list of allowed values.
+      #
+      # @param allowed [Array] Allowed values
+      # @param message [String, nil] Custom error message
+      # @return [Proc] Validator proc
+      def one_of(allowed, message = nil)
+        msg = message || "Must be one of: #{allowed.join(", ")}"
+        ->(value) { msg unless allowed.include?(value) }
+      end
+
+      # Validates that input is a valid integer.
+      #
+      # @param message [String] Error message
+      # @return [Proc] Validator proc
+      def integer(message = "Must be a number")
+        ->(value) { message unless value.to_s.match?(/\A-?\d+\z/) }
+      end
+
+      # Validates that input is within a numeric range.
+      # Note: Parses value as integer for comparison.
+      #
+      # @param range [Range] Allowed range
+      # @param message [String, nil] Custom error message
+      # @return [Proc] Validator proc
+      def in_range(range, message = nil)
+        msg = message || "Must be between #{range.first} and #{range.last}"
+        lambda do |value|
+          int_val = value.to_s.to_i
+          msg unless range.cover?(int_val) && value.to_s.match?(/\A-?\d+\z/)
+        end
+      end
+
+      # Combines multiple validators. Returns the first error message, or nil if all pass.
+      #
+      # @param validators [Array<Proc>] Validators to combine
+      # @return [Proc] Combined validator proc
+      def combine(*validators)
+        ->(value) { first_failing_validation(validators, value) }
+      end
+
+      # Common email format validator.
+      #
+      # @param message [String] Error message
+      # @return [Proc] Validator proc
+      def email(message = "Must be a valid email address")
+        format(/\A[^@\s]+@[^@\s]+\.[^@\s]+\z/, message)
+      end
+
+      # Common URL format validator.
+      #
+      # @param message [String] Error message
+      # @return [Proc] Validator proc
+      def url(message = "Must be a valid URL")
+        format(%r{\Ahttps?://\S+\z}, message)
+      end
+
+      # Validates file path exists.
+      #
+      # @param message [String] Error message
+      # @return [Proc] Validator proc
+      def path_exists(message = "Path does not exist")
+        ->(value) { message unless File.exist?(value.to_s) }
+      end
+
+      # Validates directory path exists.
+      #
+      # @param message [String] Error message
+      # @return [Proc] Validator proc
+      def directory_exists(message = "Directory does not exist")
+        ->(value) { message unless File.directory?(value.to_s) }
+      end
+
+      private
+
+      def first_failing_validation(validators, value)
+        validators.each do |validator|
+          result = validator.call(value)
+          return result if result
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/clack/version.rb

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