shellfie 0.1.0 → 1.0.0

data/lib/shellfie/cli_info.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Shellfie
+  module CLIInfo
+    private
+
+    def run_init
+      puts <<~YAML
+        # Shellfie configuration file
+        theme: macos
+        title: "Terminal — zsh"
+
+        window:
+          width: 600
+          padding: 20
+
+        lines:
+          - prompt: "$ "
+            command: "gem install shellfie"
+
+          - output: |
+              Fetching shellfie-#{VERSION}.gem
+              Successfully installed shellfie-#{VERSION}
+              1 gem installed
+
+          - prompt: "$ "
+            command: "shellfie --version"
+
+          - output: "shellfie #{VERSION}"
+      YAML
+    end
+
+    def run_themes
+      puts "Available themes:"
+      puts
+      ThemeRegistry.available_themes.each { |theme| puts "  #{theme}" }
+      puts
+      puts "Available color schemes:"
+      ThemeRegistry.available_color_schemes.each { |scheme| puts "  #{scheme}" }
+      puts
+      puts "Use: shellfie generate config.yml -o output.png -t THEME_NAME"
+    end
+
+    def run_validate
+      input_file = @args.shift
+      raise ConfigError, "Input file is required" unless input_file
+
+      config = Parser.parse(input_file)
+      puts "✓ Configuration is valid"
+      puts "  Theme: #{config.theme}"
+      puts "  Title: #{config.title}"
+      puts "  Mode: #{config.animated? ? "animated" : "static"}"
+      puts "  Lines: #{config.lines.size}" if config.static?
+      puts "  Source frames: #{config.frames.size}" if config.animated?
+      puts "  Estimated render frames: #{AnimationFrameBuilder.new(config).build.size}" if config.animated?
+      geometry = Renderer.new(config).estimate
+      puts "  Estimated size: #{geometry[:canvas_width]}x#{geometry[:canvas_height]}"
+      puts "  Logical size: #{geometry[:logical_width]}x#{geometry[:logical_height]} @#{geometry[:scale]}x"
+    end
+
+    def run_inspect
+      input_file = @args.shift
+      raise ConfigError, "Input file is required" unless input_file
+
+      info = Shellfie.inspect_config(input_file)
+      puts "Config:"
+      puts "  Version: #{info[:config][:version]}"
+      puts "  Theme: #{info[:theme]}"
+      puts "  Title: #{info[:config][:title]}"
+      puts "  Mode: #{info[:config][:frames].empty? ? "static" : "animated"}"
+      puts "  Lines: #{info[:config][:lines].size}"
+      puts "  Frames: #{info[:config][:frames].size}"
+      puts "  Estimated size: #{info[:geometry][:canvas_width]}x#{info[:geometry][:canvas_height]}"
+      puts "  Logical size: #{info[:geometry][:logical_width]}x#{info[:geometry][:logical_height]} @#{info[:geometry][:scale]}x"
+    end
+
+    def run_doctor
+      failed = false
+      DependencyChecker.doctor.each do |check|
+        status = check[:ok] ? "ok" : "fail"
+        failed ||= !check[:ok]
+        puts "#{status.ljust(4)} #{check[:name]}: #{check[:detail]}"
+      end
+      exit 4 if failed
+    end
+
+    def run_version
+      puts "shellfie #{VERSION}"
+    end
+
+    def show_help
+      puts <<~HELP
+        Shellfie - Terminal screenshot-style image generator
+
+        Usage: shellfie <command> [options]
+               shf <command> [options]
+
+        Commands:
+          generate    Generate image from configuration file
+          init        Output sample configuration
+          themes      List available themes
+          validate    Validate configuration file
+          inspect     Print resolved config and estimated image size
+          doctor      Check dependencies and local environment
+          version     Show version
+          help        Show this help
+
+        Generate Options:
+          -o, --output PATH      Output file path (required)
+          -t, --theme NAME       Override theme (macos, ubuntu, windows)
+          -a, --animate          Generate animated GIF
+          -s, --scale FACTOR     Output scale (1, 2, 3)
+          -w, --width PIXELS     Override width
+          --no-shadow            Disable shadow effect
+          --no-header            Disable window header (headless mode)
+          --transparent          Transparent background
+          --fps FPS              Override animation typing FPS
+          --overflow MODE        Line overflow mode: clip, wrap, scroll
+          --wrap, --no-wrap      Enable or disable long-line wrapping
+          --exact-size           Match canvas to configured window size
+          --format FORMAT        Output format: png, gif, svg, webp, apng
+          --force                Overwrite existing output files
+          --quiet                Suppress non-error output
+          --verbose              Print progress details
+
+        Examples:
+          shellfie generate config.yml -o terminal.png
+          shellfie generate config.yml -o demo.gif --animate
+          shellfie generate config.yml -o retina.png --scale 2
+          shellfie init > my-config.yml
+          shellfie themes
+
+          # Short form
+          shf generate config.yml -o terminal.png
+          shf init > config.yml
+      HELP
+    end
+  end
+end

data/lib/shellfie/config.rb

@@ -1,40 +1,83 @@
 # frozen_string_literal: true
 
+require_relative "config_validation"
+require_relative "config_defaults"
+require_relative "errors"
+require_relative "theme_registry"
+
 module Shellfie
   class Config
-    DEFAULTS = {
-      theme: "macos",
-      window: {
-        width: 600,
-        padding: 20,
-        opacity: 1.0,
-        visible_lines: nil
-      },
-      font: {
-        family: "Monaco",
-        size: 14,
-        line_height: 1.4
-      },
-      animation: {
-        typing_speed: 80,
-        command_delay: 500,
-        cursor_blink: true,
-        loop: false
-      }
-    }.freeze
+    include ConfigValidation
+
+    VALID_THEMES = ThemeRegistry.available_themes.freeze
+    VALID_OVERFLOW_MODES = %w[clip wrap scroll].freeze
+    VALID_CURSOR_STYLES = %w[block bar underline].freeze
+    VALID_PALETTES = %w[global adaptive theme].freeze
+    VALID_SCROLL_EASINGS = %w[linear ease_in ease_out ease_in_out].freeze
+
+    class << self
+      def deep_dup(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(key, nested_value), result| result[key] = deep_dup(nested_value) }
+        when Array
+          value.map { |nested_value| deep_dup(nested_value) }
+        else
+          value
+        end
+      end
+
+      def deep_freeze(value)
+        case value
+        when Hash
+          value.each_value { |nested_value| deep_freeze(nested_value) }
+        when Array
+          value.each { |nested_value| deep_freeze(nested_value) }
+        end
+        value.freeze
+      end
+
+      def normalize_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested_value), result|
+            normalized_key = key.is_a?(String) ? key.to_sym : key
+            result[normalized_key] = normalize_keys(nested_value)
+          end
+        when Array
+          value.map { |nested_value| normalize_keys(nested_value) }
+        else
+          value
+        end
+      end
+    end
+
+    DEFAULTS = deep_freeze(deep_dup(ConfigDefaults::VALUES))
 
-    attr_reader :theme, :title, :window, :font, :lines, :animation, :frames, :headless
+    attr_reader :version, :theme, :window_theme, :color_scheme, :colors, :window_decoration, :title, :window, :font,
+                :lines, :animation, :frames, :headless, :cursor, :limits
 
     def initialize(options = {})
+      options = self.class.normalize_keys(options)
       merged = merge_defaults(options)
+      @version = merged[:version]
       @theme = merged[:theme]
+      @window_theme = merged[:window_theme]
+      @color_scheme = merged[:color_scheme]
+      @colors = merged[:colors]
+      @window_decoration = merged[:window_decoration]
       @title = merged[:title] || "Terminal"
       @window = merged[:window]
       @font = merged[:font]
       @lines = merged[:lines] || []
       @animation = merged[:animation]
       @frames = merged[:frames] || []
-      @headless = options[:headless] || false
+      @cursor = merged[:cursor]
+      @limits = merged[:limits]
+      @headless = merged[:headless] || false
+
+      validate!
+      freeze_state!
     end
 
     def static?
@@ -45,21 +88,61 @@ module Shellfie
       !static?
     end
 
+    def to_h
+      {
+        version: version,
+        theme: theme,
+        window_theme: window_theme,
+        color_scheme: color_scheme,
+        colors: colors,
+        window_decoration: window_decoration,
+        title: title,
+        window: window,
+        font: font,
+        animation: animation,
+        cursor: cursor,
+        limits: limits,
+        headless: headless,
+        lines: lines.map(&:to_h),
+        frames: frames.map(&:to_h)
+      }
+    end
+
     private
 
     def merge_defaults(options)
-      result = {}
+      result = self.class.deep_dup(DEFAULTS)
       DEFAULTS.each do |key, value|
+        next unless options.key?(key)
+
         result[key] = if value.is_a?(Hash) && options[key].is_a?(Hash)
-                        value.merge(options[key])
+                        result[key].merge(options[key])
                       else
-                        options.key?(key) ? options[key] : value
+                        self.class.deep_dup(options[key])
                       end
       end
       result[:title] = options[:title]
       result[:lines] = options[:lines]
       result[:frames] = options[:frames]
+      result[:headless] = options[:headless] if options.key?(:headless)
       result
     end
+
+    def freeze_state!
+      @colors = self.class.deep_freeze(@colors)
+      @window_decoration = self.class.deep_freeze(@window_decoration)
+      @window = self.class.deep_freeze(@window)
+      @font = self.class.deep_freeze(@font)
+      @animation = self.class.deep_freeze(@animation)
+      @cursor = self.class.deep_freeze(@cursor)
+      @limits = self.class.deep_freeze(@limits)
+      @lines = self.class.deep_freeze(@lines)
+      @frames = self.class.deep_freeze(@frames)
+      @title.freeze
+      @theme.freeze
+      @window_theme.freeze if @window_theme
+      @color_scheme.freeze if @color_scheme
+      freeze
+    end
   end
 end

data/lib/shellfie/config_defaults.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Shellfie
+  module ConfigDefaults
+    VALUES = {
+      version: 1,
+      theme: "macos",
+      window_theme: nil,
+      color_scheme: nil,
+      colors: {},
+      window_decoration: {},
+      window: {
+        width: 600,
+        padding: 20,
+        opacity: 1.0,
+        visible_lines: nil,
+        max_lines: nil,
+        max_height: nil,
+        wrap: false,
+        overflow: "clip",
+        margin: nil,
+        exact_size: false,
+        trim: false,
+        tab_width: 8,
+        ansi_state: "persistent",
+        background_gradient: nil,
+        scroll_offset: 0.0
+      },
+      font: {
+        family: "Monaco",
+        size: 14,
+        line_height: 1.4,
+        fallback_family: nil,
+        italic_family: nil,
+        emoji_family: nil
+      },
+      animation: {
+        typing_speed: 80,
+        command_delay: 500,
+        cursor_blink: true,
+        loop: false,
+        typing_jitter: 0.0,
+        typing_chunk_size: 1,
+        output_delay: 0,
+        final_delay: 1_000,
+        max_frames: nil,
+        dither: true,
+        palette: "global",
+        scroll_easing: "linear"
+      },
+      cursor: {
+        style: "block",
+        color: nil
+      },
+      limits: {
+        max_lines: 10_000,
+        max_frames: 500,
+        max_render_frames: 2_000,
+        max_characters: 200_000,
+        max_pixels: 50_000_000
+      }
+    }.freeze
+  end
+end

data/lib/shellfie/config_validation.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Shellfie
+  module ConfigValidation
+    def validate!
+      validate_version!
+      validate_theme!
+      validate_window!
+      validate_font!
+      validate_animation!
+      validate_cursor!
+      validate_lines!
+      validate_limits!
+      validate_headless!
+      validate_resource_limits!
+    end
+
+    private
+
+    def validate_version!
+      return if @version == 1
+
+      raise ValidationError, "Unsupported config version '#{@version}'"
+    end
+
+    def validate_theme!
+      return if ThemeRegistry.valid_theme?(@theme)
+
+      raise ValidationError, "Invalid theme '#{@theme}'\n  → Available themes: #{ThemeRegistry.available_themes.join(", ")}"
+    end
+
+    def validate_window_theme!
+      return if @window_theme.nil? || ThemeRegistry.valid_window_theme?(@window_theme)
+
+      raise ValidationError, "Invalid window_theme '#{@window_theme}'"
+    end
+
+    def validate_color_scheme!
+      return if ThemeRegistry.valid_color_scheme?(@color_scheme)
+
+      raise ValidationError, "Invalid color_scheme '#{@color_scheme}'"
+    end
+
+    def validate_window!
+      validate_window_theme!
+      validate_color_scheme!
+      validate_positive_integer!(@window[:width], "window.width")
+      validate_non_negative_integer!(@window[:padding], "window.padding")
+      %i[opacity scroll_offset].each { |key| validate_number_range!(@window[key], "window.#{key}", 0.0, 1.0) }
+      validate_optional_positive_integer!(@window[:visible_lines], "window.visible_lines")
+      validate_optional_positive_integer!(@window[:max_lines], "window.max_lines")
+      validate_optional_positive_integer!(@window[:max_height], "window.max_height")
+      validate_optional_non_negative_integer!(@window[:margin], "window.margin")
+      validate_positive_integer!(@window[:tab_width], "window.tab_width")
+      validate_boolean!(@window[:wrap], "window.wrap")
+      validate_boolean!(@window[:exact_size], "window.exact_size")
+      validate_boolean!(@window[:trim], "window.trim")
+      validate_overflow!
+      validate_ansi_state!
+      validate_background_gradient!
+      validate_minimum_width!
+    end
+
+    def validate_font!
+      validate_optional_string!(@font[:family], "font.family")
+      validate_optional_string!(@font[:fallback_family], "font.fallback_family")
+      validate_optional_string!(@font[:italic_family], "font.italic_family")
+      validate_optional_string!(@font[:emoji_family], "font.emoji_family")
+      validate_positive_number!(@font[:size], "font.size")
+      validate_positive_number!(@font[:line_height], "font.line_height")
+    end
+
+    def validate_animation!
+      validate_non_negative_integer!(@animation[:typing_speed], "animation.typing_speed")
+      validate_non_negative_integer!(@animation[:command_delay], "animation.command_delay")
+      validate_number_range!(@animation[:typing_jitter], "animation.typing_jitter", 0.0, 1.0)
+      validate_positive_integer!(@animation[:typing_chunk_size], "animation.typing_chunk_size")
+      validate_non_negative_integer!(@animation[:output_delay], "animation.output_delay")
+      validate_non_negative_integer!(@animation[:final_delay], "animation.final_delay")
+      validate_optional_positive_integer!(@animation[:max_frames], "animation.max_frames")
+      validate_boolean!(@animation[:cursor_blink], "animation.cursor_blink")
+      validate_boolean!(@animation[:loop], "animation.loop")
+      validate_boolean!(@animation[:dither], "animation.dither")
+      validate_inclusion!(@animation[:palette], "animation.palette", self.class::VALID_PALETTES)
+      validate_inclusion!(@animation[:scroll_easing], "animation.scroll_easing", self.class::VALID_SCROLL_EASINGS)
+    end
+
+    def validate_cursor!
+      return if self.class::VALID_CURSOR_STYLES.include?(@cursor[:style])
+
+      raise ValidationError, "cursor.style must be one of: #{self.class::VALID_CURSOR_STYLES.join(", ")}"
+    end
+
+    def validate_lines!
+      raise ValidationError, "lines must be an Array" unless @lines.is_a?(Array)
+      raise ValidationError, "frames must be an Array" unless @frames.is_a?(Array)
+    end
+
+    def validate_limits!
+      @limits.each_key do |key|
+        validate_positive_integer!(@limits[key], "limits.#{key}")
+      end
+    end
+
+    def validate_headless!
+      validate_boolean!(@headless, "headless")
+    end
+
+    def validate_resource_limits!
+      raise ResourceLimitError, "Too many lines (max #{@limits[:max_lines]})" if @lines.size > @limits[:max_lines]
+      raise ResourceLimitError, "Too many frames (max #{@limits[:max_frames]})" if @frames.size > @limits[:max_frames]
+
+      total_characters = (@lines.sum { |line| line.to_s.length } + @frames.sum { |frame| frame.to_s.length })
+      return if total_characters <= @limits[:max_characters]
+
+      raise ResourceLimitError, "Configuration text is too large (max #{@limits[:max_characters]} characters)"
+    end
+
+    def validate_overflow!
+      return if self.class::VALID_OVERFLOW_MODES.include?(@window[:overflow])
+
+      raise ValidationError, "window.overflow must be one of: #{self.class::VALID_OVERFLOW_MODES.join(", ")}"
+    end
+
+    def validate_ansi_state!
+      return if %w[persistent line].include?(@window[:ansi_state])
+
+      raise ValidationError, "window.ansi_state must be persistent or line"
+    end
+
+    def validate_background_gradient!
+      gradient = @window[:background_gradient]
+      return if gradient.nil?
+      return if gradient.is_a?(Array) && gradient.size == 2 && gradient.all? { |color| color.is_a?(String) }
+
+      raise ValidationError, "window.background_gradient must be an array of two colors"
+    end
+
+    def validate_minimum_width!
+      min_width = [120, (@window[:padding] * 2) + 40].max
+      return if @window[:width] >= min_width
+
+      raise ValidationError, "window.width must be at least #{min_width}px for the configured padding"
+    end
+
+    def validate_optional_positive_integer!(value, name)
+      return if value.nil?
+
+      validate_positive_integer!(value, name)
+    end
+
+    def validate_optional_non_negative_integer!(value, name)
+      return if value.nil?
+
+      validate_non_negative_integer!(value, name)
+    end
+
+    def validate_optional_string!(value, name)
+      return if value.nil? || value.is_a?(String)
+
+      raise ValidationError, "#{name} must be a string"
+    end
+
+    def validate_positive_integer!(value, name)
+      return if value.is_a?(Integer) && value.positive?
+
+      raise ValidationError, "#{name} must be a positive integer"
+    end
+
+    def validate_non_negative_integer!(value, name)
+      return if value.is_a?(Integer) && value >= 0
+
+      raise ValidationError, "#{name} must be a non-negative integer"
+    end
+
+    def validate_positive_number!(value, name)
+      return if value.is_a?(Numeric) && value.positive?
+
+      raise ValidationError, "#{name} must be a positive number"
+    end
+
+    def validate_number_range!(value, name, min, max)
+      return if value.is_a?(Numeric) && value >= min && value <= max
+
+      raise ValidationError, "#{name} must be between #{min} and #{max}"
+    end
+
+    def validate_inclusion!(value, name, allowed)
+      return if allowed.include?(value)
+
+      raise ValidationError, "#{name} must be one of: #{allowed.join(", ")}"
+    end
+
+    def validate_boolean!(value, name)
+      return if value == true || value == false
+
+      raise ValidationError, "#{name} must be true or false"
+    end
+  end
+end

data/lib/shellfie/dependency_checker.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Shellfie
+  class DependencyChecker
+    IMAGE_MAGICK_COMMANDS = %w[magick convert].freeze
+
+    class << self
+      def imagemagick_path
+        @imagemagick_path ||= find_executable(IMAGE_MAGICK_COMMANDS)
+      end
+
+      def imagemagick_available?
+        !imagemagick_path.to_s.empty?
+      end
+
+      def ensure_imagemagick!
+        return if imagemagick_available?
+
+        raise DependencyError, <<~MSG
+          ImageMagick not found
+            → Please install ImageMagick: brew install imagemagick
+            → Or visit: https://imagemagick.org/script/download.php
+        MSG
+      end
+
+      def configure_mini_magick!(timeout: 30)
+        return unless defined?(MiniMagick) && MiniMagick.respond_to?(:timeout=)
+
+        MiniMagick.timeout = timeout
+      end
+
+      def doctor(output_dir: Dir.pwd)
+        [
+          check("Ruby", RUBY_VERSION, Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.0.0")),
+          check("ImageMagick", imagemagick_path || "not found", imagemagick_available?),
+          check("Writable output", output_dir, File.writable?(output_dir)),
+          check("Encoding", Encoding.default_external.name, true)
+        ]
+      end
+
+      private
+
+      def check(name, detail, ok)
+        { name: name, detail: detail, ok: ok }
+      end
+
+      def find_executable(names)
+        paths = ENV.fetch("PATH", "").split(File::PATH_SEPARATOR)
+        extensions = executable_extensions
+
+        names.each do |name|
+          paths.each do |path|
+            extensions.each do |extension|
+              candidate = File.join(path, "#{name}#{extension}")
+              return candidate if File.file?(candidate) && File.executable?(candidate)
+            end
+          end
+        end
+
+        nil
+      end
+
+      def executable_extensions
+        return [""] unless windows?
+
+        ENV.fetch("PATHEXT", ".COM;.EXE;.BAT;.CMD").split(";")
+      end
+
+      def windows?
+        RbConfig::CONFIG["host_os"].match?(/mswin|mingw|cygwin/i)
+      end
+    end
+  end
+end

data/lib/shellfie/errors.rb

@@ -1,15 +1,25 @@
 # frozen_string_literal: true
 
 module Shellfie
-  class Error < StandardError; end
+  class Error < StandardError
+    attr_reader :category, :context
+
+    def initialize(message = nil, category: nil, context: {})
+      @category = category
+      @context = context.freeze
+      super(message)
+    end
+  end
 
   class ConfigError < Error; end
   class ParseError < ConfigError; end
   class ValidationError < ConfigError; end
+  class ResourceLimitError < ConfigError; end
 
   class RenderError < Error; end
   class FontError < RenderError; end
   class ImageError < RenderError; end
 
   class DependencyError < Error; end
+  class FileSystemError < Error; end
 end