pvectl 0.2.0

data/lib/pvectl/formatters/color_support.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Formatters
+    # Manages color output based on TTY detection and user flags.
+    #
+    # Implements color flag priority:
+    # 1. --no-color flag (highest) -> disabled
+    # 2. --color flag -> enabled
+    # 3. NO_COLOR env var -> disabled (see https://no-color.org/)
+    # 4. TTY detection (lowest) -> $stdout.tty?
+    #
+    # @example Check if colors are enabled
+    #   ColorSupport.enabled?(explicit_flag: nil)   # TTY auto-detect
+    #   ColorSupport.enabled?(explicit_flag: true)  # forced on
+    #   ColorSupport.enabled?(explicit_flag: false) # forced off
+    #
+    # @example Get Pastel instance
+    #   pastel = ColorSupport.pastel(explicit_flag: global_options[:color])
+    #   puts pastel.green("Success!")
+    #
+    # @example Colorize status value
+    #   pastel = ColorSupport.pastel(explicit_flag: true)
+    #   ColorSupport.colorize_status("running", pastel) #=> "\e[32mrunning\e[0m"
+    #
+    module ColorSupport
+      # Status color mapping following kubectl conventions.
+      # @return [Hash<String, Symbol>] mapping of status to Pastel color method
+      STATUS_COLORS = {
+        "running" => :green,
+        "stopped" => :red,
+        "paused" => :yellow
+      }.freeze
+
+      class << self
+        # Determines if color output should be enabled.
+        #
+        # Priority order:
+        # 1. explicit_flag: false (--no-color) -> disabled
+        # 2. explicit_flag: true (--color) -> enabled
+        # 3. NO_COLOR env var present -> disabled
+        # 4. TTY detection -> $stdout.tty?
+        #
+        # @param explicit_flag [Boolean, nil] value from --color / --no-color flag
+        #   - true: --color was passed
+        #   - false: --no-color was passed
+        #   - nil: no flag passed, use auto-detection
+        # @return [Boolean] true if colors should be used
+        def enabled?(explicit_flag: nil)
+          return false if explicit_flag == false
+          return true if explicit_flag == true
+          return false if ENV.key?("NO_COLOR")
+
+          $stdout.tty?
+        end
+
+        # Returns a Pastel instance configured based on color settings.
+        #
+        # @param explicit_flag [Boolean, nil] value from --color / --no-color flag
+        # @return [Pastel] pastel instance with appropriate enabled state
+        #
+        # @example
+        #   pastel = ColorSupport.pastel(explicit_flag: true)
+        #   pastel.green("text") #=> "\e[32mtext\e[0m"
+        def pastel(explicit_flag: nil)
+          require "pastel"
+          Pastel.new(enabled: enabled?(explicit_flag: explicit_flag))
+        end
+
+        # Colors status text according to kubectl conventions.
+        #
+        # Status colors:
+        # - running -> green
+        # - stopped -> red
+        # - paused -> yellow
+        # - unknown status -> dim (gray)
+        #
+        # @param status [String, nil] status value
+        # @param pastel_instance [Pastel] pastel instance
+        # @return [String] colored text (or "-" if nil, or dim if unknown status)
+        def colorize_status(status, pastel_instance)
+          return "-" if status.nil?
+
+          color = STATUS_COLORS[status.to_s.downcase]
+          color ? pastel_instance.public_send(color, status) : pastel_instance.dim(status)
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/formatters/json.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Pvectl
+  module Formatters
+    # Formats data as JSON output.
+    #
+    # Collections are rendered as JSON arrays.
+    # Single resources are rendered as JSON objects.
+    # Empty collections return "[]".
+    # Nil values are rendered as JSON null.
+    #
+    # @example JSON output for collection
+    #   [
+    #     {"name": "vm-100", "status": "running"},
+    #     {"name": "vm-101", "status": "stopped"}
+    #   ]
+    #
+    # @example JSON output for single resource
+    #   {"name": "vm-100", "status": "running", "node": "pve1"}
+    #
+    class Json < Base
+      # Formats data as JSON output.
+      #
+      # @param data [Array, Object] collection of models or single model
+      # @param presenter [Presenters::Base] presenter for hash conversion
+      # @param color_enabled [Boolean] ignored for JSON (always plain text)
+      # @param describe [Boolean] whether this is a describe command
+      # @param context [Hash] ignored for JSON output
+      # @return [String] formatted JSON string (pretty-printed)
+      def format(data, presenter, color_enabled: true, describe: false, **context)
+        if describe && !collection?(data)
+          # Use to_description for describe mode
+          JSON.pretty_generate(presenter.to_description(data))
+        elsif collection?(data)
+          hashes = data.map { |model| presenter.to_hash(model) }
+          JSON.pretty_generate(hashes)
+        else
+          JSON.pretty_generate(presenter.to_hash(data))
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/formatters/output_helper.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Formatters
+    # Facade for output formatting in commands.
+    #
+    # Coordinates Formatter and Presenter to produce formatted output.
+    # Handles color flag interpretation and prints to stdout.
+    #
+    # @example Usage in a command
+    #   def self.execute(global_options)
+    #     service = Pvectl::Services::Vm.new
+    #     vms = service.list
+    #     presenter = Pvectl::Presenters::Vm.new
+    #
+    #     OutputHelper.print(
+    #       data: vms,
+    #       presenter: presenter,
+    #       format: global_options[:output],
+    #       color_flag: global_options[:color]
+    #     )
+    #   end
+    #
+    # @example Rendering without printing (for testing)
+    #   output = OutputHelper.render(
+    #     data: vms,
+    #     presenter: presenter,
+    #     format: "json"
+    #   )
+    #
+    module OutputHelper
+      class << self
+        # Formats data and prints to stdout.
+        #
+        # @param data [Array, Object] collection of models or single model
+        # @param presenter [Presenters::Base] presenter for the resource type
+        # @param format [String] output format ("table", "json", "yaml", "wide")
+        # @param color_flag [Boolean, nil] color flag from CLI
+        #   - true: --color was passed
+        #   - false: --no-color was passed
+        #   - nil: auto-detect based on TTY
+        # @param describe [Boolean] whether this is a describe command (default: false)
+        # @param context [Hash] additional context passed to presenter
+        # @return [void]
+        def print(data:, presenter:, format: "table", color_flag: nil, describe: false, **context)
+          output = render(data: data, presenter: presenter, format: format, color_flag: color_flag, describe: describe, **context)
+          puts output
+        end
+
+        # Returns formatted string without printing.
+        #
+        # Useful for testing or when you need to manipulate the output
+        # before displaying.
+        #
+        # @param data [Array, Object] collection of models or single model
+        # @param presenter [Presenters::Base] presenter for the resource type
+        # @param format [String] output format ("table", "json", "yaml", "wide")
+        # @param color_flag [Boolean, nil] color flag from CLI
+        # @param describe [Boolean] whether this is a describe command
+        # @param context [Hash] additional context passed to presenter
+        # @return [String] formatted output
+        def render(data:, presenter:, format: "table", color_flag: nil, describe: false, **context)
+          formatter = Registry.for(format)
+          color_enabled = ColorSupport.enabled?(explicit_flag: color_flag)
+
+          formatter.format(
+            data,
+            presenter,
+            color_enabled: color_enabled,
+            describe: describe,
+            **context
+          )
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/formatters/registry.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Formatters
+    # Registry for looking up formatters by name.
+    #
+    # Implements the Registry Pattern to map format names
+    # ("table", "json", "yaml", "wide") to formatter classes.
+    #
+    # @example Getting a formatter
+    #   formatter = Registry.for("json")
+    #   output = formatter.format(data, presenter)
+    #
+    # @example Listing available formats
+    #   Registry.available_formats #=> ["table", "wide", "json", "yaml"]
+    #
+    # @example Checking if format is supported
+    #   Registry.supported?("json")  #=> true
+    #   Registry.supported?("xml")   #=> false
+    #
+    class Registry
+      # Mapping of format names to formatter classes.
+      # @return [Hash<String, Class>] frozen hash of format name to class
+      FORMATS = {
+        "table" => Table,
+        "wide" => Wide,
+        "json" => Json,
+        "yaml" => Yaml
+      }.freeze
+
+      class << self
+        # Gets a formatter instance for the specified format.
+        #
+        # @param format_name [String, Symbol] format name (table, wide, json, yaml)
+        # @return [Base] formatter instance
+        # @raise [ArgumentError] if format is not found
+        #
+        # @example
+        #   formatter = Registry.for("json")
+        #   formatter.format(data, presenter)
+        def for(format_name)
+          formatter_class = FORMATS[format_name.to_s]
+          raise ArgumentError, "Unknown format: #{format_name}" unless formatter_class
+
+          formatter_class.new
+        end
+
+        # Returns list of available format names.
+        #
+        # @return [Array<String>] available format names
+        #
+        # @example
+        #   Registry.available_formats #=> ["table", "wide", "json", "yaml"]
+        def available_formats
+          FORMATS.keys
+        end
+
+        # Checks if a format is supported.
+        #
+        # @param format_name [String, Symbol] format name
+        # @return [Boolean] true if format is supported
+        #
+        # @example
+        #   Registry.supported?("json")  #=> true
+        #   Registry.supported?("xml")   #=> false
+        def supported?(format_name)
+          FORMATS.key?(format_name.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/formatters/table.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "tty-table"
+
+module Pvectl
+  module Formatters
+    # Formats data as a table using tty-table gem.
+    #
+    # For collections: renders standard horizontal table with headers.
+    # For single resources (describe): renders vertical key-value layout.
+    #
+    # @example Table output for collection
+    #   NAME    STATUS   NODE
+    #   vm-100  running  pve1
+    #   vm-101  stopped  pve2
+    #
+    # @example Vertical output for single resource (describe)
+    #   Name:     vm-100
+    #   Status:   running
+    #   Node:     pve1
+    #
+    # @see Pvectl::Formatters::Wide for extended column output
+    #
+    class Table < Base
+      # Formats data as table output.
+      #
+      # @param data [Array, Object] collection of models or single model
+      # @param presenter [Presenters::Base] presenter for column/row definitions
+      # @param color_enabled [Boolean] whether to apply color formatting
+      # @param describe [Boolean] whether this is a describe command (single resource)
+      # @param context [Hash] additional context passed to presenter
+      # @return [String] formatted table string
+      def format(data, presenter, color_enabled: true, describe: false, **context)
+        pastel = ColorSupport.pastel(explicit_flag: color_enabled)
+
+        if describe || !collection?(data)
+          format_describe(data, presenter, pastel)
+        else
+          format_table(data, presenter, pastel, **context)
+        end
+      end
+
+      private
+
+      # Formats collection as horizontal table.
+      #
+      # @param data [Array] collection of models
+      # @param presenter [Presenters::Base] presenter
+      # @param pastel [Pastel] pastel instance for coloring
+      # @param context [Hash] context passed to presenter
+      # @return [String] formatted table
+      def format_table(data, presenter, pastel, **context)
+        headers = presenter.columns
+        rows = data.map do |model|
+          row = presenter.to_row(model, **context)
+          colorize_row(row, headers, pastel)
+        end
+
+        render_table(headers, rows)
+      end
+
+      # Formats single resource as vertical key-value layout.
+      # Supports nested Hashes (sections) and Arrays of Hashes (tables).
+      #
+      # @param model [Object] single model
+      # @param presenter [Presenters::Base] presenter
+      # @param pastel [Pastel] pastel instance for coloring
+      # @return [String] formatted vertical layout
+      def format_describe(model, presenter, pastel)
+        hash = presenter.to_description(model)
+        format_describe_hash(hash, pastel, indent: 0)
+      end
+
+      # Colorizes status columns in a row.
+      #
+      # @param row [Array] row values
+      # @param headers [Array<String>] column headers
+      # @param pastel [Pastel] pastel instance
+      # @return [Array] row with colorized values
+      def colorize_row(row, headers, pastel)
+        row.each_with_index.map do |value, idx|
+          header = headers[idx].to_s.downcase
+          if header == "status"
+            ColorSupport.colorize_status(value, pastel)
+          else
+            normalize_nil(value)
+          end
+        end
+      end
+
+      # Recursively formats a hash for describe output.
+      #
+      # At indent 0 (top level), once a section (Hash/Array) has been rendered,
+      # all subsequent entries get a blank line separator for consistent spacing.
+      #
+      # @param hash [Hash] hash to format
+      # @param pastel [Pastel] pastel instance
+      # @param indent [Integer] current indentation level
+      # @return [String] formatted output
+      def format_describe_hash(hash, pastel, indent: 0)
+        return "-" if hash.nil?
+
+        lines = []
+        prefix = "  " * indent
+
+        # Calculate max key length for alignment (only for non-nested values)
+        simple_keys = hash.select { |_, v| !v.is_a?(Hash) && !(v.is_a?(Array) && v.first.is_a?(Hash)) && !v.to_s.include?("\n") }
+        max_key_length = simple_keys.keys.map { |k| k.to_s.length }.max || 0
+
+        # Track whether we've passed a nested section (Hash/Array).
+        # Once a section appears, all subsequent simple entries get blank-line separators.
+        prev_was_section = false
+
+        hash.each do |key, value|
+          human_key = humanize_key(key)
+
+          if value.is_a?(Hash)
+            # Nested section
+            lines << ""
+            lines << "#{prefix}#{human_key}:"
+            lines << format_describe_hash(value, pastel, indent: indent + 1)
+            prev_was_section = true
+          elsif value.is_a?(Array) && !value.empty? && value.first.is_a?(Hash)
+            # Array of hashes -> inline table
+            lines << ""
+            lines << "#{prefix}#{human_key}:"
+            lines << format_describe_table(value, indent: indent + 1)
+            prev_was_section = true
+          elsif value.is_a?(Array) && value.empty?
+            # Empty array -> show as "-"
+            lines << "" if prev_was_section
+            formatted_key = "#{human_key}:".ljust(max_key_length + 2)
+            lines << "#{prefix}#{formatted_key}-"
+          else
+            formatted_value = format_describe_value(value, key.to_s, pastel)
+            if formatted_value.include?("\n")
+              # Multi-line value: render as block section
+              lines << ""
+              lines << "#{prefix}#{human_key}:"
+              formatted_value.each_line do |line|
+                lines << "#{prefix}  #{line.chomp}"
+              end
+              prev_was_section = true
+            else
+              # Simple key-value — add separator after sections at any indent level
+              lines << "" if prev_was_section
+              formatted_key = "#{human_key}:".ljust(max_key_length + 2)
+              lines << "#{prefix}#{formatted_key}#{formatted_value}"
+            end
+          end
+        end
+
+        lines.join("\n").sub(/\A\n+/, "").rstrip
+      end
+
+      # Formats array of hashes as inline table.
+      #
+      # @param array [Array<Hash>] array of hashes
+      # @param indent [Integer] indentation level
+      # @return [String] formatted table
+      def format_describe_table(array, indent: 0)
+        return "  " * indent + "-" if array.empty?
+
+        prefix = "  " * indent
+        headers = array.first.keys.map { |k| k.to_s.upcase }
+        rows = array.map { |item| item.values.map(&:to_s) }
+
+        # Calculate column widths
+        widths = headers.each_with_index.map do |h, i|
+          [h.length, *rows.map { |r| r[i]&.length || 0 }].max
+        end
+
+        lines = []
+        # Header
+        header_line = headers.each_with_index.map { |h, i| h.ljust(widths[i]) }.join("  ")
+        lines << "#{prefix}#{header_line}"
+
+        # Rows
+        rows.each do |row|
+          row_line = row.each_with_index.map { |v, i| (v || "-").ljust(widths[i]) }.join("  ")
+          lines << "#{prefix}#{row_line}"
+        end
+
+        lines.join("\n")
+      end
+
+      # Formats a value for describe output.
+      #
+      # @param value [Object] value to format
+      # @param key [String] key name (used for status detection)
+      # @param pastel [Pastel] pastel instance
+      # @return [String] formatted value
+      def format_describe_value(value, key, pastel)
+        return "-" if value.nil?
+
+        if key.downcase == "status"
+          ColorSupport.colorize_status(value, pastel)
+        else
+          value.to_s
+        end
+      end
+
+      # Converts snake_case or kebab-case key to Title Case.
+      # Preserves already-formatted keys (e.g., "CPU", "DNS", "Cloud-Init").
+      #
+      # @param key [String, Symbol] key to humanize
+      # @return [String] humanized key
+      def humanize_key(key)
+        str = key.to_s
+        # If the key is already formatted (contains spaces, is all caps,
+        # or has uppercase letters indicating intentional formatting), return as-is
+        return str if str.include?(" ") || str == str.upcase || str.match?(/[A-Z]/)
+
+        str.split(/[_-]/).map(&:capitalize).join(" ")
+      end
+
+      # Renders table using tty-table.
+      #
+      # Uses :basic renderer for clean kubectl-like output (no borders).
+      # Handles non-TTY environments gracefully by rescuing ioctl errors.
+      #
+      # @param headers [Array<String>] column headers
+      # @param rows [Array<Array>] row data
+      # @return [String] rendered table
+      def render_table(headers, rows)
+        table = TTY::Table.new(header: headers, rows: rows)
+        table.render(:basic, padding: [0, 2]) || headers.join("\t")
+      rescue NoMethodError
+        # TTY::Screen may call ioctl on non-TTY streams (e.g., StringIO in tests)
+        # Fall back to simple tab-separated output
+        ([headers] + rows).map { |row| row.join("\t") }.join("\n")
+      end
+    end
+  end
+end

data/lib/pvectl/formatters/wide.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "tty-table"
+
+module Pvectl
+  module Formatters
+    # Formats data as a wide table with extended columns.
+    #
+    # For collections: uses wide_columns and to_wide_row from presenter.
+    # For single resources (describe): delegates to Table (no wide variant).
+    #
+    # @example Wide table output
+    #   NAME    STATUS   NODE   MEMORY   CPU   UPTIME
+    #   vm-100  running  pve1   2048     2     3d 5h
+    #
+    # @see Pvectl::Formatters::Table for standard table output
+    # @see Pvectl::Presenters::Base#wide_columns for wide column definitions
+    #
+    class Wide < Base
+      # Formats data as wide table output.
+      #
+      # @param data [Array, Object] collection of models or single model
+      # @param presenter [Presenters::Base] presenter for column/row definitions
+      # @param color_enabled [Boolean] whether to apply color formatting
+      # @param describe [Boolean] whether this is a describe command
+      # @param context [Hash] additional context passed to presenter
+      # @return [String] formatted wide table string
+      def format(data, presenter, color_enabled: true, describe: false, **context)
+        # For describe (single resource), delegate to Table formatter
+        # Wide format has no meaning for vertical key-value layout
+        if describe || !collection?(data)
+          Table.new.format(data, presenter, color_enabled: color_enabled, describe: true, **context)
+        else
+          format_wide_table(data, presenter, color_enabled, **context)
+        end
+      end
+
+      private
+
+      # Formats collection as wide table.
+      #
+      # @param data [Array] collection of models
+      # @param presenter [Presenters::Base] presenter
+      # @param color_enabled [Boolean] whether to apply color
+      # @param context [Hash] context passed to presenter
+      # @return [String] formatted wide table
+      def format_wide_table(data, presenter, color_enabled, **context)
+        pastel = ColorSupport.pastel(explicit_flag: color_enabled)
+        headers = presenter.wide_columns
+        rows = data.map do |model|
+          row = presenter.to_wide_row(model, **context)
+          colorize_row(row, headers, pastel)
+        end
+
+        render_table(headers, rows)
+      end
+
+      # Colorizes status columns in a row.
+      #
+      # @param row [Array] row values
+      # @param headers [Array<String>] column headers
+      # @param pastel [Pastel] pastel instance
+      # @return [Array] row with colorized values
+      def colorize_row(row, headers, pastel)
+        row.each_with_index.map do |value, idx|
+          header = headers[idx].to_s.downcase
+          if header == "status"
+            ColorSupport.colorize_status(value, pastel)
+          else
+            value.nil? ? "-" : value
+          end
+        end
+      end
+
+      # Renders table using tty-table.
+      #
+      # Uses :basic renderer for clean kubectl-like output (no borders).
+      # Handles non-TTY environments gracefully by rescuing ioctl errors.
+      #
+      # @param headers [Array<String>] column headers
+      # @param rows [Array<Array>] row data
+      # @return [String] rendered table
+      def render_table(headers, rows)
+        table = TTY::Table.new(header: headers, rows: rows)
+        table.render(:basic, padding: [0, 2]) || headers.join("\t")
+      rescue NoMethodError
+        # TTY::Screen may call ioctl on non-TTY streams (e.g., StringIO in tests)
+        # Fall back to simple tab-separated output
+        ([headers] + rows).map { |row| row.join("\t") }.join("\n")
+      end
+    end
+  end
+end

data/lib/pvectl/formatters/yaml.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Pvectl
+  module Formatters
+    # Formats data as YAML output.
+    #
+    # Collections are rendered as YAML arrays.
+    # Single resources are rendered as YAML mappings.
+    # Empty collections return "--- []\n".
+    # Nil values are rendered as YAML null (~).
+    #
+    # @example YAML output for collection
+    #   ---
+    #   - name: vm-100
+    #     status: running
+    #   - name: vm-101
+    #     status: stopped
+    #
+    # @example YAML output for single resource
+    #   ---
+    #   name: vm-100
+    #   status: running
+    #   node: pve1
+    #
+    class Yaml < Base
+      # Formats data as YAML output.
+      #
+      # @param data [Array, Object] collection of models or single model
+      # @param presenter [Presenters::Base] presenter for hash conversion
+      # @param color_enabled [Boolean] ignored for YAML (always plain text)
+      # @param describe [Boolean] whether this is a describe command
+      # @param context [Hash] ignored for YAML output
+      # @return [String] formatted YAML string
+      def format(data, presenter, color_enabled: true, describe: false, **context)
+        if describe && !collection?(data)
+          # Use to_description for describe mode
+          presenter.to_description(data).to_yaml
+        elsif collection?(data)
+          hashes = data.map { |model| presenter.to_hash(model) }
+          hashes.to_yaml
+        else
+          presenter.to_hash(data).to_yaml
+        end
+      end
+    end
+  end
+end