clack 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 82be7312cfdade424ca896c9ddb5c70e2bfadadc5f61c411a073d01d1daa73c5
+  data.tar.gz: 2322b602de289654d8ba79925b804027b49a2027eb1e76fe8708d315527706a6
+SHA512:
+  metadata.gz: 2412c28b3f625313df7249154a2a7a72cd039e336f3ee2764130e7dc52a5f932358a1576bc793d8fa33b5862d60cf5dff319a5b6495546bd59cef24714c93b1f
+  data.tar.gz: dc26d51d23d264c510c913383e448b3b8552312d1a1a78db7cba71e69ace120cc8638f69adc615fb844652065520947286a46cf75657a6a8ecdbcb499ee58bfc

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [Unreleased]
+
+### 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
+
+### Changed
+- Ruby 3.2+ support
+
+## [0.1.0]
+
+Initial release.

data/LICENSE

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

data/README.md

@@ -0,0 +1,424 @@
+# Clack
+
+**Effortlessly beautiful CLI prompts for Ruby.**
+
+A faithful Ruby port of [@clack/prompts](https://github.com/bombshell-dev/clack).
+
+<p align="center">
+  <img src="examples/demo.gif" width="640" alt="Clack demo">
+</p>
+
+## 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
+- **Composable** - Group prompts together with `Clack.group`
+
+## Installation
+
+```ruby
+# Gemfile
+gem "clack"
+
+# Or from GitHub
+gem "clack", github: "swhitt/clackrb"
+```
+
+```bash
+# Or install directly
+gem install clack
+```
+
+## Quick Start
+
+```ruby
+require "clack"
+
+Clack.intro "project-setup"
+
+result = Clack.group do |g|
+  g.prompt(:name) { Clack.text(message: "Project name?", placeholder: "my-app") }
+  g.prompt(:framework) do
+    Clack.select(
+      message: "Pick a framework",
+      options: [
+        { value: "rails", label: "Ruby on Rails", hint: "recommended" },
+        { value: "sinatra", label: "Sinatra" },
+        { value: "roda", label: "Roda" }
+      ]
+    )
+  end
+  g.prompt(:features) do
+    Clack.multiselect(
+      message: "Select features",
+      options: %w[api auth admin websockets]
+    )
+  end
+end
+
+if Clack.cancel?(result)
+  Clack.cancel("Setup cancelled")
+  exit 1
+end
+
+Clack.outro "You're all set!"
+```
+
+## Demo
+
+Try it yourself:
+
+```bash
+ruby examples/full_demo.rb
+```
+
+<details>
+<summary>Recording the demo GIF</summary>
+
+Install [VHS](https://github.com/charmbracelet/vhs) and run:
+
+```bash
+vhs examples/demo.tape
+```
+</details>
+
+## Prompts
+
+All prompts return the user's input, or `Clack::CANCEL` if they pressed Escape/Ctrl+C.
+
+```ruby
+# Always check for cancellation
+result = Clack.text(message: "Name?")
+exit 1 if Clack.cancel?(result)
+```
+
+### Text
+
+```ruby
+name = Clack.text(
+  message: "What is your project named?",
+  placeholder: "my-project",       # Shown when empty (dim)
+  default_value: "untitled",       # Used if submitted empty
+  initial_value: "hello-world",    # Pre-filled, editable
+  validate: ->(v) { "Required!" if v.empty? }
+)
+```
+
+### Password
+
+```ruby
+secret = Clack.password(
+  message: "Enter your API key",
+  mask: "*"  # Default: "▪"
+)
+```
+
+### Confirm
+
+```ruby
+proceed = Clack.confirm(
+  message: "Deploy to production?",
+  active: "Yes, ship it!",
+  inactive: "No, abort",
+  initial_value: false
+)
+```
+
+### Select
+
+Single selection with keyboard navigation.
+
+```ruby
+db = Clack.select(
+  message: "Choose a database",
+  options: [
+    { value: "pg", label: "PostgreSQL", hint: "recommended" },
+    { value: "mysql", label: "MySQL" },
+    { value: "sqlite", label: "SQLite", disabled: true }
+  ],
+  initial_value: "pg",
+  max_items: 5  # Enable scrolling
+)
+```
+
+### Multiselect
+
+Multiple selections with toggle controls.
+
+```ruby
+features = Clack.multiselect(
+  message: "Select features to install",
+  options: [
+    { value: "api", label: "API Mode" },
+    { value: "auth", label: "Authentication" },
+    { value: "jobs", label: "Background Jobs" }
+  ],
+  initial_values: ["api"],
+  required: true,     # Must select at least one
+  max_items: 5        # Enable scrolling
+)
+```
+
+**Shortcuts:** `Space` toggle | `a` all | `i` invert
+
+### Autocomplete
+
+Type to filter from a list of options.
+
+```ruby
+color = Clack.autocomplete(
+  message: "Pick a color",
+  options: %w[red orange yellow green blue indigo violet],
+  placeholder: "Type to search..."
+)
+```
+
+### Autocomplete Multiselect
+
+Type to filter with multi-selection support.
+
+```ruby
+colors = Clack.autocomplete_multiselect(
+  message: "Pick colors",
+  options: %w[red orange yellow green blue indigo violet],
+  placeholder: "Type to filter...",
+  required: true,              # At least one selection required
+  initial_values: ["red"]      # Pre-selected values
+)
+```
+
+**Shortcuts:** `Space` toggle | `a` toggle all | `i` invert | `Enter` confirm
+
+### Path
+
+File/directory path selector with filesystem navigation.
+
+```ruby
+project_dir = Clack.path(
+  message: "Where should we create your project?",
+  only_directories: true,  # Only show directories
+  root: "."               # Starting directory
+)
+```
+
+**Navigation:** Type to filter | `Tab` to autocomplete | `↑↓` to select
+
+### Select Key
+
+Quick selection using keyboard shortcuts.
+
+```ruby
+action = Clack.select_key(
+  message: "What would you like to do?",
+  options: [
+    { value: "create", label: "Create new project", key: "c" },
+    { value: "open", label: "Open existing", key: "o" },
+    { value: "quit", label: "Quit", key: "q" }
+  ]
+)
+```
+
+### Spinner
+
+Non-blocking animated indicator for async work.
+
+```ruby
+spinner = Clack.spinner
+spinner.start("Installing dependencies...")
+
+# Do your work...
+sleep 2
+
+spinner.stop("Dependencies installed!")
+# Or: spinner.error("Installation failed")
+# Or: spinner.cancel("Cancelled")
+```
+
+### Progress
+
+Visual progress bar for measurable operations.
+
+```ruby
+progress = Clack.progress(total: 100, message: "Downloading...")
+progress.start
+
+files.each_with_index do |file, i|
+  download(file)
+  progress.update(i + 1)
+end
+
+progress.stop("Download complete!")
+```
+
+### Tasks
+
+Run multiple tasks with status indicators.
+
+```ruby
+results = Clack.tasks(tasks: [
+  { title: "Checking dependencies", task: -> { check_deps } },
+  { title: "Building project", task: -> { build } },
+  { title: "Running tests", task: -> { run_tests } }
+])
+```
+
+### Group Multiselect
+
+Multiselect with options organized into groups.
+
+```ruby
+features = Clack.group_multiselect(
+  message: "Select features",
+  options: [
+    {
+      label: "Frontend",
+      options: [
+        { value: "hotwire", label: "Hotwire" },
+        { value: "stimulus", label: "Stimulus" }
+      ]
+    },
+    {
+      label: "Background",
+      options: [
+        { value: "sidekiq", label: "Sidekiq" },
+        { value: "solid_queue", label: "Solid Queue" }
+      ]
+    }
+  ]
+)
+```
+
+## Prompt Groups
+
+Chain multiple prompts and collect results in a hash. Cancellation is handled automatically.
+
+```ruby
+result = Clack.group do |g|
+  g.prompt(:name) { Clack.text(message: "Your name?") }
+  g.prompt(:email) { Clack.text(message: "Your email?") }
+  g.prompt(:confirm) { |r| Clack.confirm(message: "Create account for #{r[:email]}?") }
+end
+
+return if Clack.cancel?(result)
+
+puts "Welcome, #{result[:name]}!"
+```
+
+Handle cancellation with a callback:
+
+```ruby
+Clack.group(on_cancel: ->(r) { cleanup(r) }) do |g|
+  # prompts...
+end
+```
+
+## Logging
+
+Beautiful, consistent log messages.
+
+```ruby
+Clack.log.info("Starting build...")
+Clack.log.success("Build completed!")
+Clack.log.warn("Cache is stale")
+Clack.log.error("Build failed")
+Clack.log.step("Running migrations")
+Clack.log.message("Custom message")
+```
+
+### Stream
+
+Stream output from iterables, enumerables, or shell commands:
+
+```ruby
+# Stream from an array or enumerable
+Clack.stream.info(["Line 1", "Line 2", "Line 3"])
+Clack.stream.step(["Step 1", "Step 2", "Step 3"])
+
+# Stream from a shell command (returns true/false for success)
+success = Clack.stream.command("npm install", type: :info)
+
+# Stream from any IO or StringIO
+Clack.stream.success(io_stream)
+```
+
+## Note
+
+Display important information in a box.
+
+```ruby
+Clack.note(<<~MSG, title: "Next Steps")
+  cd my-project
+  bundle install
+  bin/rails server
+MSG
+```
+
+### Box
+
+Render a customizable bordered box.
+
+```ruby
+Clack.box("Hello, World!", title: "Greeting")
+
+# With options
+Clack.box(
+  "Centered content",
+  title: "My Box",
+  content_align: :center,    # :left, :center, :right
+  title_align: :center,
+  width: 40,                 # or :auto to fit content
+  rounded: true              # rounded or square corners
+)
+```
+
+### Task Log
+
+Streaming log that clears on success and shows full output on failure. Useful for build output.
+
+```ruby
+tl = Clack.task_log(title: "Building...", limit: 10)
+
+tl.message("Compiling file 1...")
+tl.message("Compiling file 2...")
+
+# On success: clears the log
+tl.success("Build complete!")
+
+# On error: keeps the log visible
+# tl.error("Build failed!")
+```
+
+## Session Markers
+
+```ruby
+Clack.intro("my-cli v1.0")  # ┌ my-cli v1.0
+# ... your prompts ...
+Clack.outro("Done!")        # └ Done!
+
+# Or on error:
+Clack.cancel("Aborted")     # └ Aborted (red)
+```
+
+## Requirements
+
+- Ruby 3.2+
+- No runtime dependencies
+
+## Development
+
+```bash
+bundle install
+bundle exec rake        # Lint + tests
+bundle exec rake spec   # Tests only
+COVERAGE=true bundle exec rake spec  # With coverage
+```
+
+## Credits
+
+This is a Ruby port of [Clack](https://github.com/bombshell-dev/clack), created by [Nate Moore](https://github.com/natemoo-re) and the [Astro](https://astro.build) team.
+
+## License
+
+MIT - See [LICENSE](LICENSE)

data/exe/clack-demo

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Support running from development checkout
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "clack"
+Clack.demo

data/lib/clack/box.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Clack
+  # Renders a box with optional title around content
+  # Supports alignment, padding, and rounded/square corners
+  module Box
+    class << self
+      # @param message [String] Content to display in the box
+      # @param title [String] Optional title for the box
+      # @param content_align [:left, :center, :right] Content alignment
+      # @param title_align [:left, :center, :right] Title alignment
+      # @param width [Integer, :auto] Box width (auto fits to content)
+      # @param title_padding [Integer] Padding around title
+      # @param content_padding [Integer] Padding around content
+      # @param rounded [Boolean] Use rounded corners (default: true)
+      # @param format_border [Proc] Optional proc to format border characters
+      # @param output [IO] Output stream
+      def render(
+        message = "",
+        title: "",
+        content_align: :left,
+        title_align: :left,
+        width: :auto,
+        title_padding: 1,
+        content_padding: 2,
+        rounded: true,
+        format_border: nil,
+        output: $stdout
+      )
+        ctx = build_context(message, title, title_padding, content_padding, width, rounded, format_border)
+        output.puts build_top_border(ctx[:display_title], ctx[:inner_width], title_padding, title_align, ctx[:symbols], ctx[:h_symbol])
+        render_content_lines(output, ctx, content_align, content_padding)
+        output.puts "#{ctx[:symbols][2]}#{ctx[:h_symbol] * ctx[:inner_width]}#{ctx[:symbols][3]}"
+      end
+
+      private
+
+      def build_context(message, title, title_padding, content_padding, width, rounded, format_border)
+        format_border ||= ->(text) { Colors.gray(text) }
+        symbols = corner_symbols(rounded).map(&format_border)
+        lines = message.to_s.lines.map(&:chomp)
+        box_width = calculate_width(lines, title.length, title_padding, content_padding, width)
+        inner_width = box_width - 2
+        max_title_len = inner_width - (title_padding * 2)
+        display_title = (title.length > max_title_len) ? "#{title[0, max_title_len - 3]}..." : title
+
+        {
+          symbols: symbols,
+          h_symbol: format_border.call(Symbols::S_BAR_H),
+          v_symbol: format_border.call(Symbols::S_BAR),
+          lines: lines,
+          inner_width: inner_width,
+          display_title: display_title
+        }
+      end
+
+      def render_content_lines(output, ctx, content_align, content_padding)
+        ctx[:lines].each do |line|
+          left_pad, right_pad = padding_for_line(line.length, ctx[:inner_width], content_padding, content_align)
+          output.puts "#{ctx[:v_symbol]}#{" " * left_pad}#{line}#{" " * right_pad}#{ctx[:v_symbol]}"
+        end
+      end
+
+      def corner_symbols(rounded)
+        if rounded
+          [
+            Symbols::S_CORNER_TOP_LEFT,
+            Symbols::S_CORNER_TOP_RIGHT,
+            Symbols::S_CORNER_BOTTOM_LEFT,
+            Symbols::S_CORNER_BOTTOM_RIGHT
+          ]
+        else
+          [
+            Symbols::S_BAR_START,
+            Symbols::S_BAR_START_RIGHT,
+            Symbols::S_BAR_END,
+            Symbols::S_BAR_END_RIGHT
+          ]
+        end
+      end
+
+      def calculate_width(lines, title_len, title_padding, content_padding, width)
+        return width + 2 if width.is_a?(Integer) # Add 2 for borders
+
+        # Auto width: fit to content
+        max_line = lines.map(&:length).max || 0
+        title_with_padding = title_len + (title_padding * 2)
+        content_with_padding = max_line + (content_padding * 2)
+
+        [title_with_padding, content_with_padding].max + 2
+      end
+
+      def build_top_border(title, inner_width, title_padding, title_align, symbols, h_symbol)
+        if title.empty?
+          "#{symbols[0]}#{h_symbol * inner_width}#{symbols[1]}"
+        else
+          left_pad, right_pad = padding_for_line(title.length, inner_width, title_padding, title_align)
+          "#{symbols[0]}#{h_symbol * left_pad}#{title}#{h_symbol * right_pad}#{symbols[1]}"
+        end
+      end
+
+      def padding_for_line(line_length, inner_width, padding, align)
+        case align
+        when :center
+          left = (inner_width - line_length) / 2
+          right = inner_width - left - line_length
+          [left, right]
+        when :right
+          left = inner_width - line_length - padding
+          right = padding
+          [[left, 0].max, right]
+        else # :left
+          left = padding
+          right = inner_width - left - line_length
+          [left, [right, 0].max]
+        end
+      end
+    end
+  end
+end

data/lib/clack/colors.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Clack
+  # ANSI color codes for terminal output styling.
+  # Colors are automatically disabled when:
+  # - Output is not a TTY (piped/redirected)
+  # - NO_COLOR environment variable is set
+  # - FORCE_COLOR environment variable forces colors on
+  module Colors
+    class << self
+      def enabled?
+        return true if ENV["FORCE_COLOR"] && ENV["FORCE_COLOR"] != "0"
+        return false if ENV["NO_COLOR"]
+
+        $stdout.tty?
+      end
+
+      # Foreground colors (standard)
+      def gray(text) = wrap(text, "90")
+      def cyan(text) = wrap(text, "36")
+      def green(text) = wrap(text, "32")
+      def yellow(text) = wrap(text, "33")
+      def red(text) = wrap(text, "31")
+      def blue(text) = wrap(text, "34")
+      def magenta(text) = wrap(text, "35")
+      def white(text) = wrap(text, "37")
+
+      # Text styles
+      def dim(text) = wrap(text, "2")
+      def bold(text) = wrap(text, "1")
+      def italic(text) = wrap(text, "3")
+      def underline(text) = wrap(text, "4")
+      def inverse(text) = wrap(text, "7")
+      def strikethrough(text) = wrap(text, "9")
+      def hidden(text) = wrap(text, "8")
+
+      # Bright/vivid foreground colors (higher contrast)
+      def bright_cyan(text) = wrap(text, "96")
+      def bright_green(text) = wrap(text, "92")
+      def bright_yellow(text) = wrap(text, "93")
+      def bright_red(text) = wrap(text, "91")
+      def bright_blue(text) = wrap(text, "94")
+      def bright_magenta(text) = wrap(text, "95")
+      def bright_white(text) = wrap(text, "97")
+
+      private
+
+      def wrap(text, code)
+        return text.to_s unless enabled?
+
+        "\e[#{code}m#{text}\e[0m"
+      end
+    end
+  end
+end