gum 0.2.1 → 0.3.0

data/lib/gum/commands/log.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+# typed: true
+# rbs_inline: enabled
+
+module Gum
+  # Log messages with different levels and formatting
+  #
+  # @example Basic logging
+  #   Gum.log("Application started", level: :info)
+  #
+  # @example Structured logging with key-value pairs
+  #   Gum.log("User created", level: :info, user_id: 123, email: "user@example.com")
+  #
+  # @example With timestamp
+  #   Gum.log("Error occurred", level: :error, time: :rfc822)
+  #
+  class Log
+    LEVELS = [:debug, :info, :warn, :error, :fatal, :none].freeze #: Array[Symbol]
+
+    TIME_FORMATS = [
+      :ansic, :unixdate, :rubydate, :rfc822, :rfc822z, :rfc850, :rfc1123, :rfc1123z, :rfc3339, :rfc3339nano, :kitchen
+    ].freeze #: Array[Symbol]
+
+    # Log a message
+    #
+    # @rbs message: String -- log message text
+    # @rbs level: Symbol | String | nil -- log level (:debug, :info, :warn, :error, :fatal, :none)
+    # @rbs time: Symbol | String | nil -- time format (:rfc822, :rfc3339, :kitchen, etc.) or custom Go time format
+    # @rbs structured: bool? -- output structured log format (key=value pairs)
+    # @rbs formatter: Symbol | String | nil -- log formatter (:text, :json, :logfmt)
+    # @rbs prefix: String? -- log message prefix
+    # @rbs **fields: untyped -- additional key-value fields for structured logging
+    # @rbs return: String? -- formatted log output
+    def self.call(
+      message,
+      level: nil,
+      time: nil,
+      structured: nil,
+      formatter: nil,
+      prefix: nil,
+      **fields
+    )
+      options = {
+        level: level&.to_s,
+        time: time&.to_s,
+        structured: structured,
+        formatter: formatter&.to_s,
+        prefix: prefix,
+      }
+
+      args = Command.build_args("log", **options.compact)
+
+      args << message
+
+      fields.each do |key, value|
+        args << key.to_s
+        args << value.to_s
+      end
+
+      Command.run(*args, interactive: false)
+    end
+
+    # @rbs message: String -- log message text
+    # @rbs **fields: untyped -- additional key-value fields
+    # @rbs return: String? -- formatted debug log output
+    def self.debug(message, **fields)
+      call(message, level: :debug, **fields)
+    end
+
+    # @rbs message: String -- log message text
+    # @rbs **fields: untyped -- additional key-value fields
+    # @rbs return: String? -- formatted info log output
+    def self.info(message, **fields)
+      call(message, level: :info, **fields)
+    end
+
+    # @rbs message: String -- log message text
+    # @rbs **fields: untyped -- additional key-value fields
+    # @rbs return: String? -- formatted warn log output
+    def self.warn(message, **fields)
+      call(message, level: :warn, **fields)
+    end
+
+    # @rbs message: String -- log message text
+    # @rbs **fields: untyped -- additional key-value fields
+    # @rbs return: String? -- formatted error log output
+    def self.error(message, **fields)
+      call(message, level: :error, **fields)
+    end
+
+    # @rbs message: String -- log message text
+    # @rbs **fields: untyped -- additional key-value fields
+    # @rbs return: String? -- formatted fatal log output
+    def self.fatal(message, **fields)
+      call(message, level: :fatal, **fields)
+    end
+  end
+end

data/lib/gum/commands/pager.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+# typed: true
+# rbs_inline: enabled
+
+module Gum
+  # Scroll through content in a pager
+  #
+  # @example View file content
+  #   Gum.pager(File.read("README.md"))
+  #
+  # @example With line numbers
+  #   Gum.pager(content, show_line_numbers: true)
+  #
+  # @example Soft wrap long lines
+  #   Gum.pager(content, soft_wrap: true)
+  #
+  class Pager
+    # Display content in a scrollable pager
+    #
+    # @rbs content: String -- content to display in the pager
+    # @rbs show_line_numbers: bool? -- display line numbers
+    # @rbs soft_wrap: bool? -- wrap long lines instead of horizontal scrolling
+    # @rbs timeout: Integer? -- timeout in seconds (0 = no timeout)
+    # @rbs help_style: Hash[Symbol, untyped]? -- help text style
+    # @rbs line_number_style: Hash[Symbol, untyped]? -- line number style
+    # @rbs match_style: Hash[Symbol, untyped]? -- search match style
+    # @rbs match_highlight_style: Hash[Symbol, untyped]? -- current search match highlight style
+    # @rbs return: void
+    def self.call(
+      content,
+      show_line_numbers: nil,
+      soft_wrap: nil,
+      timeout: nil,
+      help_style: nil,
+      line_number_style: nil,
+      match_style: nil,
+      match_highlight_style: nil
+    )
+      options = {
+        "show-line-numbers": show_line_numbers,
+        "soft-wrap": soft_wrap,
+        timeout: timeout ? "#{timeout}s" : nil,
+      }
+
+      args = Command.build_args("pager", **options.compact)
+
+      Command.add_style_args(args, :help, help_style)
+      Command.add_style_args(args, :"line-number", line_number_style)
+      Command.add_style_args(args, :match, match_style)
+      Command.add_style_args(args, :"match-highlight", match_highlight_style)
+
+      Command.run_display_only(*args, input: content)
+    end
+  end
+end

data/lib/gum/commands/spin.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+# typed: true
+# rbs_inline: enabled
+
+require "shellwords"
+
+module Gum
+  # Display a spinner while running a command or block
+  #
+  # @example With shell command
+  #   Gum.spin("Installing...", command: "npm install")
+  #
+  # @example With Ruby block
+  #   result = Gum.spin("Processing...") do
+  #     # long running operation
+  #     expensive_computation
+  #   end
+  #
+  # @example Custom spinner type
+  #   Gum.spin("Loading...", spinner: :dot, command: "sleep 5")
+  #
+  class Spin
+    SPINNERS = [
+      :line, :dot, :minidot, :jump, :pulse, :points, :globe, :moon, :monkey, :meter, :hamburger
+    ].freeze #: Array[Symbol]
+
+    # Display a spinner while running a command or block
+    #
+    # @rbs title: String -- spinner title text (default: "Loading...")
+    # @rbs command: String? -- shell command to execute
+    # @rbs spinner: Symbol | String | nil -- spinner type (see SPINNERS constant)
+    # @rbs show_output: bool? -- show command stdout after completion
+    # @rbs show_error: bool? -- show command stderr after completion
+    # @rbs align: Symbol? -- alignment of spinner and title (:left, :right)
+    # @rbs timeout: Integer? -- timeout in seconds (0 = no timeout)
+    # @rbs spinner_style: Hash[Symbol, untyped]? -- spinner animation style
+    # @rbs title_style: Hash[Symbol, untyped]? -- title text style
+    # @rbs &block: ^() -> untyped | nil -- Ruby block to execute (alternative to command)
+    # @rbs return: String | untyped | nil -- command output or block result, nil if cancelled
+    def self.call(
+      title = "Loading...",
+      command: nil,
+      spinner: nil,
+      show_output: nil,
+      show_error: nil,
+      align: nil,
+      timeout: nil,
+      spinner_style: nil,
+      title_style: nil,
+      &block
+    )
+      raise ArgumentError, "Cannot specify both command and block" if block && command
+
+      if block
+        run_with_block(title, spinner: spinner, spinner_style: spinner_style, title_style: title_style, &block)
+      else
+        run_with_command(
+          title,
+          command: command,
+          spinner: spinner,
+          show_output: show_output,
+          show_error: show_error,
+          align: align,
+          timeout: timeout,
+          spinner_style: spinner_style,
+          title_style: title_style
+        )
+      end
+    end
+
+    # @rbs title: String -- spinner title text
+    # @rbs command: String -- shell command to execute
+    # @rbs spinner: Symbol | String | nil -- spinner type
+    # @rbs show_output: bool? -- show command stdout
+    # @rbs show_error: bool? -- show command stderr
+    # @rbs align: Symbol? -- alignment of spinner
+    # @rbs timeout: Integer? -- timeout in seconds
+    # @rbs spinner_style: Hash[Symbol, untyped]? -- spinner animation style
+    # @rbs title_style: Hash[Symbol, untyped]? -- title text style
+    # @rbs return: bool? -- true if command succeeded, false/nil otherwise
+    def self.run_with_command(
+      title,
+      command:,
+      spinner:,
+      show_output:,
+      show_error:,
+      align:,
+      timeout:,
+      spinner_style:,
+      title_style:
+    )
+      raise ArgumentError, "Command is required when not using a block" unless command
+
+      options = {
+        title: title,
+        spinner: spinner&.to_s,
+        "show-output": show_output,
+        "show-error": show_error,
+        align: align&.to_s,
+        timeout: timeout ? "#{timeout}s" : nil,
+      }
+
+      args = Command.build_args("spin", **options.compact)
+
+      Command.add_style_args(args, :spinner, spinner_style)
+      Command.add_style_args(args, :title, title_style)
+
+      args << "--"
+      args.concat(command.shellsplit)
+
+      system(Gum.executable, *args.map(&:to_s))
+    end
+
+    # @rbs title: String -- spinner title text
+    # @rbs spinner: Symbol | String | nil -- spinner type
+    # @rbs spinner_style: Hash[Symbol, untyped]? -- spinner animation style
+    # @rbs title_style: Hash[Symbol, untyped]? -- title text style
+    # @rbs &block: ^() -> untyped -- Ruby block to execute
+    # @rbs return: untyped -- block result
+    def self.run_with_block(
+      title,
+      spinner:,
+      spinner_style:,
+      title_style:,
+      &block
+    )
+      require "fileutils"
+
+      result = nil
+      error = nil
+      marker_path = "/tmp/gum_spin_done_#{Process.pid}_#{Time.now.to_i}"
+
+      options = {
+        title: title,
+        spinner: spinner&.to_s,
+      }
+
+      args = Command.build_args("spin", **options.compact)
+
+      Command.add_style_args(args, :spinner, spinner_style)
+      Command.add_style_args(args, :title, title_style)
+
+      args << "--"
+      args.push("bash", "-c", "while [ ! -f #{marker_path} ]; do sleep 0.1; done")
+
+      spinner_pid = Process.fork do
+        exec(Gum.executable, *args.map(&:to_s))
+      end
+
+      begin
+        result = block.call
+      rescue StandardError => e
+        error = e
+      end
+
+      FileUtils.touch(marker_path)
+      Process.wait(spinner_pid)
+      FileUtils.rm_f(marker_path)
+
+      raise error if error
+
+      result
+    end
+
+    private_class_method :run_with_command, :run_with_block
+  end
+end

data/lib/gum/commands/style.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+# typed: true
+# rbs_inline: enabled
+
+module Gum
+  # Apply styling to text
+  #
+  # @example Basic styling
+  #   styled = Gum.style("Hello", foreground: "212", bold: true)
+  #
+  # @example With border
+  #   box = Gum.style("Content", border: :double, padding: "1 2")
+  #
+  # @example Multiple lines
+  #   styled = Gum.style("Line 1", "Line 2", align: :center, width: 50)
+  #
+  class Style
+    BORDERS = [:none, :hidden, :rounded, :double, :thick, :normal].freeze #: Array[Symbol]
+    ALIGNMENTS = [:left, :center, :right, :top, :middle, :bottom].freeze #: Array[Symbol]
+
+    # Apply styling to text
+    #
+    # @rbs *text: String -- text content to style (multiple strings become separate lines)
+    # @rbs foreground: String | Integer | nil -- text color (ANSI code, hex, or color name)
+    # @rbs background: String | Integer | nil -- background color (ANSI code, hex, or color name)
+    # @rbs border: Symbol | String | nil -- border style (:none, :hidden, :rounded, :double, :thick, :normal)
+    # @rbs border_foreground: String | Integer | nil -- border color
+    # @rbs border_background: String | Integer | nil -- border background color
+    # @rbs align: Symbol | String | nil -- text alignment (:left, :center, :right)
+    # @rbs height: Integer? -- fixed height in lines
+    # @rbs width: Integer? -- fixed width in characters
+    # @rbs margin: String | Array[Integer] | nil -- margin around the box ("1" or "1 2" or [1, 2, 1, 2])
+    # @rbs padding: String | Array[Integer] | nil -- padding inside the box ("1" or "1 2" or [1, 2, 1, 2])
+    # @rbs bold: bool? -- bold text
+    # @rbs italic: bool? -- italic text
+    # @rbs strikethrough: bool? -- strikethrough text
+    # @rbs underline: bool? -- underlined text
+    # @rbs faint: bool? -- faint/dim text
+    # @rbs return: String? -- styled text output
+    def self.call(
+      *text,
+      foreground: nil,
+      background: nil,
+      border: nil,
+      border_foreground: nil,
+      border_background: nil,
+      align: nil,
+      height: nil,
+      width: nil,
+      margin: nil,
+      padding: nil,
+      bold: nil,
+      italic: nil,
+      strikethrough: nil,
+      underline: nil,
+      faint: nil
+    )
+      options = {
+        foreground: foreground&.to_s,
+        background: background&.to_s,
+        border: border&.to_s,
+        "border-foreground": border_foreground&.to_s,
+        "border-background": border_background&.to_s,
+        align: align&.to_s,
+        height: height,
+        width: width,
+        margin: format_spacing(margin),
+        padding: format_spacing(padding),
+        bold: bold,
+        italic: italic,
+        strikethrough: strikethrough,
+        underline: underline,
+        faint: faint,
+      }
+
+      args = Command.build_args("style", *text, **options.compact)
+      Command.run(*args, interactive: false)
+    end
+
+    # @rbs value: String | Integer | Array[Integer] | nil -- spacing value to format
+    # @rbs return: String? -- formatted spacing string
+    def self.format_spacing(value)
+      case value
+      when Array
+        value.join(" ")
+      when String, Integer
+        value.to_s
+      end
+    end
+
+    private_class_method :format_spacing
+  end
+end

data/lib/gum/commands/table.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+# typed: true
+# rbs_inline: enabled
+
+module Gum
+  # Display and select from tabular data
+  #
+  # @example From array of arrays
+  #   selection = Gum.table([["Alice", 30], ["Bob", 25]], columns: %w[Name Age])
+  #
+  # @example From CSV string
+  #   Gum.table(File.read("data.csv"))
+  #
+  # @example With custom separator
+  #   Gum.table(data, separator: "\t")
+  #
+  class Table
+    # Display tabular data and optionally allow row selection
+    #
+    # @rbs data: String | Array[Array[untyped]] -- CSV string or array of row arrays
+    # @rbs columns: Array[String]? -- column headers (required when data is array)
+    # @rbs separator: String? -- column separator (default: ",")
+    # @rbs widths: Array[Integer]? -- column widths
+    # @rbs height: Integer? -- table height in rows
+    # @rbs print: bool? -- print table without selection (non-interactive)
+    # @rbs border: Symbol | String | nil -- border style (:rounded, :thick, :normal, :hidden, :double, :none)
+    # @rbs border_foreground: String | Integer | nil -- border color
+    # @rbs border_background: String | Integer | nil -- border background color
+    # @rbs cell_foreground: String | Integer | nil -- cell text color
+    # @rbs cell_background: String | Integer | nil -- cell background color
+    # @rbs header_foreground: String | Integer | nil -- header text color
+    # @rbs header_background: String | Integer | nil -- header background color
+    # @rbs selected_foreground: String | Integer | nil -- selected row text color
+    # @rbs selected_background: String | Integer | nil -- selected row background color
+    # @rbs return: String? -- selected row data, or nil if cancelled
+    def self.call(
+      data,
+      columns: nil,
+      separator: nil,
+      widths: nil,
+      height: nil,
+      print: nil,
+      border: nil,
+      border_foreground: nil,
+      border_background: nil,
+      cell_foreground: nil,
+      cell_background: nil,
+      header_foreground: nil,
+      header_background: nil,
+      selected_foreground: nil,
+      selected_background: nil
+    )
+      separator ||= ","
+
+      csv_data = if data.is_a?(Array)
+                   rows = [] #: Array[String]
+                   rows << columns.join(separator) if columns
+                   rows.concat(data.map { |row| row.join(separator) })
+                   rows.join("\n")
+                 else
+                   data.to_s
+                 end
+
+      options = {
+        separator: separator,
+        widths: widths&.join(","),
+        height: height,
+        print: print,
+        border: border&.to_s,
+        "border.foreground": border_foreground&.to_s,
+        "border.background": border_background&.to_s,
+        "cell.foreground": cell_foreground&.to_s,
+        "cell.background": cell_background&.to_s,
+        "header.foreground": header_foreground&.to_s,
+        "header.background": header_background&.to_s,
+        "selected.foreground": selected_foreground&.to_s,
+        "selected.background": selected_background&.to_s,
+      }
+
+      args = Command.build_args("table", **options.compact)
+
+      if print
+        IO.popen([Gum.executable, *args.map(&:to_s)], "w") do |io|
+          io.write(csv_data)
+        end
+
+        nil
+      else
+        Command.run(*args, input: csv_data, interactive: true)
+      end
+    end
+  end
+end

data/lib/gum/commands/write.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+# typed: true
+# rbs_inline: enabled
+
+module Gum
+  # Prompt for multi-line text input
+  #
+  # @example Basic multi-line input
+  #   description = Gum.write(placeholder: "Enter description...")
+  #
+  # @example With dimensions
+  #   notes = Gum.write(width: 80, height: 10, header: "Notes")
+  #
+  class Write
+    # Prompt for multi-line text input (Ctrl+D to submit)
+    #
+    # @rbs placeholder: String? -- placeholder text shown when empty
+    # @rbs prompt: String? -- prompt string shown at the start of each line
+    # @rbs value: String? -- initial value for the text area
+    # @rbs char_limit: Integer? -- maximum number of characters allowed
+    # @rbs width: Integer? -- width of the text area
+    # @rbs height: Integer? -- height of the text area in lines
+    # @rbs header: String? -- header text displayed above the input
+    # @rbs show_cursor_line: bool? -- highlight the line with the cursor
+    # @rbs show_line_numbers: bool? -- display line numbers
+    # @rbs timeout: Integer? -- timeout in seconds (0 = no timeout)
+    # @rbs cursor: Hash[Symbol, untyped]? -- cursor style options
+    # @rbs cursor_line: Hash[Symbol, untyped]? -- cursor line highlight style
+    # @rbs placeholder_style: Hash[Symbol, untyped]? -- placeholder text style
+    # @rbs prompt_style: Hash[Symbol, untyped]? -- prompt text style
+    # @rbs end_of_buffer: Hash[Symbol, untyped]? -- end of buffer character style
+    # @rbs line_number: Hash[Symbol, untyped]? -- line number style
+    # @rbs header_style: Hash[Symbol, untyped]? -- header text style
+    # @rbs base: Hash[Symbol, untyped]? -- base text style
+    # @rbs return: String? -- the entered text, or nil if cancelled
+    def self.call(
+      placeholder: nil,
+      prompt: nil,
+      value: nil,
+      char_limit: nil,
+      width: nil,
+      height: nil,
+      header: nil,
+      show_cursor_line: nil,
+      show_line_numbers: nil,
+      timeout: nil,
+      cursor: nil,
+      cursor_line: nil,
+      placeholder_style: nil,
+      prompt_style: nil,
+      end_of_buffer: nil,
+      line_number: nil,
+      header_style: nil,
+      base: nil
+    )
+      options = {
+        placeholder: placeholder,
+        prompt: prompt,
+        value: value,
+        char_limit: char_limit,
+        width: width,
+        height: height,
+        header: header,
+        show_cursor_line: show_cursor_line,
+        show_line_numbers: show_line_numbers,
+        timeout: timeout ? "#{timeout}s" : nil,
+        base: base,
+      }
+
+      options[:cursor] = cursor if cursor
+      options[:cursor_line] = cursor_line if cursor_line
+      options[:end_of_buffer] = end_of_buffer if end_of_buffer
+      options[:line_number] = line_number if line_number
+
+      args = Command.build_args("write", **options.compact)
+
+      Command.add_style_args(args, :placeholder, placeholder_style)
+      Command.add_style_args(args, :prompt, prompt_style)
+      Command.add_style_args(args, :header, header_style)
+
+      Command.run(*args)
+    end
+  end
+end

data/lib/gum/upstream.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# typed: true
+# rbs_inline: enabled
+
+module Gum
+  module Upstream
+    VERSION = "0.17.0"
+
+    NATIVE_PLATFORMS = {
+      "arm64-darwin" => "gum_#{VERSION}_Darwin_arm64.tar.gz",
+      "x86_64-darwin" => "gum_#{VERSION}_Darwin_x86_64.tar.gz",
+      "arm64-linux" => "gum_#{VERSION}_Linux_arm64.tar.gz",
+      "aarch64-linux" => "gum_#{VERSION}_Linux_arm64.tar.gz",
+      "x86_64-linux" => "gum_#{VERSION}_Linux_x86_64.tar.gz",
+    }.freeze
+  end
+end

data/lib/gum/version.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+# typed: true
+# rbs_inline: enabled
+
 module Gum
-  VERSION = '0.2.1'.freeze
+  VERSION = "0.3.0"
 end