shellfie 0.1.0 → 1.0.0

data/lib/shellfie/output_writer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tempfile"
+require "tmpdir"
+
+module Shellfie
+  class OutputWriter
+    class << self
+      def write(path, extension:)
+        FileUtils.mkdir_p(output_directory(path)) unless stdout?(path)
+        temp = Tempfile.new(["shellfie", ".#{extension}"], output_directory(path), binmode: true)
+        temp.close
+        yield temp.path
+
+        return File.binread(temp.path) if stdout?(path)
+
+        FileUtils.mv(temp.path, path)
+        path
+      ensure
+        if temp
+          temp.close unless temp.closed?
+          File.delete(temp.path) if File.exist?(temp.path)
+        end
+      end
+
+      private
+
+      def stdout?(path)
+        path == "-"
+      end
+
+      def output_directory(path)
+        return Dir.tmpdir if stdout?(path)
+
+        directory = File.dirname(path)
+        directory == "." ? Dir.pwd : directory
+      end
+    end
+  end
+end

data/lib/shellfie/parser.rb

@@ -3,19 +3,24 @@
 require "yaml"
 require_relative "config"
 require_relative "errors"
+require_relative "parser_validation"
 
 module Shellfie
   class Parser
     class << self
+      include ParserValidation
+
       def parse(path)
+        return parse_string($stdin.read, base_dir: Dir.pwd) if path == "-"
         raise ParseError, "Configuration file not found: #{path}" unless File.exist?(path)
 
         content = File.read(path)
-        parse_string(content)
+        parse_string(content, base_dir: File.dirname(path))
       end
 
-      def parse_string(content)
-        raw = YAML.safe_load(content, symbolize_names: true)
+      def parse_string(content, base_dir: nil)
+        raw = YAML.safe_load(content, symbolize_names: true, aliases: true)
+        raw = apply_includes(raw, base_dir) if base_dir
         validate_config(raw)
         build_config(raw)
       rescue Psych::SyntaxError => e
@@ -24,27 +29,21 @@ module Shellfie
 
       private
 
-      def validate_config(raw)
-        raise ValidationError, "Empty configuration" if raw.nil? || raw.empty?
-
-        valid_themes = %w[macos ubuntu windows]
-        if raw[:theme] && !valid_themes.include?(raw[:theme])
-          raise ValidationError, "Invalid theme '#{raw[:theme]}'\n  → Available themes: #{valid_themes.join(", ")}"
-        end
-
-        if raw[:lines].nil? && raw[:frames].nil?
-          raise ValidationError, "Configuration must have either 'lines' or 'frames'"
-        end
-      end
-
       def build_config(raw)
         options = {
+          version: raw[:version],
           theme: raw[:theme],
+          window_theme: raw[:window_theme],
+          color_scheme: raw[:color_scheme],
+          colors: symbolize_hash(raw[:colors]),
+          window_decoration: symbolize_hash(raw[:window_decoration]),
           title: raw[:title],
           window: symbolize_hash(raw[:window]),
           font: symbolize_hash(raw[:font]),
           lines: parse_lines(raw[:lines]),
           animation: symbolize_hash(raw[:animation]),
+          cursor: symbolize_hash(raw[:cursor]),
+          limits: symbolize_hash(raw[:limits]),
           frames: parse_frames(raw[:frames]),
           headless: raw[:headless] || false
         }.compact
@@ -52,39 +51,130 @@ module Shellfie
         Config.new(options)
       end
 
+      def apply_includes(raw, base_dir, depth: 0)
+        return raw unless raw.is_a?(Hash) && raw[:include]
+        raise ParseError, "YAML include depth exceeded" if depth > 5
+
+        includes = Array(raw[:include])
+        included_config = includes.reduce({}) do |merged, include_path|
+          include_file = File.expand_path(include_path, base_dir)
+          raise ParseError, "Included configuration file not found: #{include_path}" unless File.exist?(include_file)
+
+          included_raw = YAML.safe_load(File.read(include_file), symbolize_names: true, aliases: true)
+          included_raw = apply_includes(included_raw, File.dirname(include_file), depth: depth + 1)
+          deep_merge(merged, included_raw || {})
+        end
+
+        deep_merge(included_config, raw.reject { |key, _value| key == :include })
+      end
+
+      def deep_merge(base, overrides)
+        base.merge(overrides) do |_key, left, right|
+          left.is_a?(Hash) && right.is_a?(Hash) ? deep_merge(left, right) : right
+        end
+      end
+
       def symbolize_hash(hash)
         return nil unless hash.is_a?(Hash)
 
-        hash.transform_keys(&:to_sym)
+        Config.normalize_keys(hash)
       end
 
       def parse_lines(lines)
-        return [] unless lines.is_a?(Array)
+        return [] if lines.nil?
 
         lines.map do |line|
           Line.new(
             prompt: line[:prompt],
             command: line[:command],
-            output: line[:output]
+            output: line[:output],
+            prompt_color: line[:prompt_color],
+            command_color: line[:command_color],
+            output_color: line[:output_color],
+            selected: line[:selected] || false
           )
         end
       end
 
       def parse_frames(frames)
-        return [] unless frames.is_a?(Array)
+        return [] if frames.nil?
 
         frames.map do |frame|
           Frame.new(
             prompt: frame[:prompt],
             type: frame[:type],
             output: frame[:output],
-            delay: frame[:delay] || 0
+            delay: frame[:delay] || 0,
+            prompt_color: frame[:prompt_color],
+            command_color: frame[:command_color],
+            output_color: frame[:output_color]
           )
         end
       end
     end
   end
 
-  Line = Struct.new(:prompt, :command, :output, keyword_init: true)
-  Frame = Struct.new(:prompt, :type, :output, :delay, keyword_init: true)
+  class Line
+    attr_reader :prompt, :command, :output, :prompt_color, :command_color, :output_color, :selected
+
+    def initialize(prompt: nil, command: nil, output: nil, prompt_color: nil, command_color: nil, output_color: nil,
+                   selected: false)
+      @prompt = prompt
+      @command = command
+      @output = output
+      @prompt_color = prompt_color
+      @command_color = command_color
+      @output_color = output_color
+      @selected = selected
+      freeze
+    end
+
+    def to_h
+      {
+        prompt: prompt,
+        command: command,
+        output: output,
+        prompt_color: prompt_color,
+        command_color: command_color,
+        output_color: output_color,
+        selected: selected
+      }.compact
+    end
+
+    def to_s
+      [prompt, command, output].compact.join("\n")
+    end
+  end
+
+  class Frame
+    attr_reader :prompt, :type, :output, :delay, :prompt_color, :command_color, :output_color
+
+    def initialize(prompt: nil, type: nil, output: nil, delay: 0, prompt_color: nil, command_color: nil,
+                   output_color: nil)
+      @prompt = prompt
+      @type = type
+      @output = output
+      @delay = delay
+      @prompt_color = prompt_color
+      @command_color = command_color
+      @output_color = output_color
+      freeze
+    end
+
+    def to_h
+      {
+        prompt: prompt,
+        type: type,
+        output: output,
+        delay: delay,
+        prompt_color: prompt_color,
+        command_color: command_color,
+        output_color: output_color
+      }.compact
+    end
+
+    def to_s
+      [prompt, type, output, delay].compact.join("\n")
+    end
+  end
 end

data/lib/shellfie/parser_validation.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Shellfie
+  module ParserValidation
+    TOP_LEVEL_KEYS = %i[
+      version include theme window_theme color_scheme colors window_decoration title window font animation cursor lines frames
+      headless limits
+    ].freeze
+    WINDOW_KEYS = %i[
+      width padding opacity visible_lines max_lines max_height wrap overflow margin exact_size trim tab_width
+      ansi_state background_gradient scroll_offset
+    ].freeze
+    FONT_KEYS = %i[family size line_height fallback_family italic_family emoji_family].freeze
+    ANIMATION_KEYS = %i[
+      typing_speed command_delay cursor_blink loop typing_jitter typing_chunk_size output_delay final_delay max_frames
+      dither palette scroll_easing
+    ].freeze
+    CURSOR_KEYS = %i[style color].freeze
+    LIMIT_KEYS = %i[max_lines max_frames max_render_frames max_characters max_pixels].freeze
+    LINE_KEYS = %i[prompt command output prompt_color command_color output_color selected].freeze
+    FRAME_KEYS = %i[prompt type output delay prompt_color command_color output_color].freeze
+
+    private
+
+    def validate_config(raw)
+      raise ValidationError, "Empty configuration" if raw.nil? || (raw.respond_to?(:empty?) && raw.empty?)
+      raise ValidationError, "Configuration must be a YAML mapping" unless raw.is_a?(Hash)
+
+      validate_keys!(raw, TOP_LEVEL_KEYS, "configuration")
+      validate_nested_hash!(raw, :window, WINDOW_KEYS)
+      validate_nested_hash!(raw, :font, FONT_KEYS)
+      validate_nested_hash!(raw, :animation, ANIMATION_KEYS)
+      validate_nested_hash!(raw, :cursor, CURSOR_KEYS)
+      validate_nested_hash!(raw, :limits, LIMIT_KEYS)
+      validate_nested_hash!(raw, :colors, nil)
+      validate_nested_hash!(raw, :window_decoration, nil)
+      validate_theme!(raw[:theme]) if raw[:theme]
+      validate_window_theme!(raw[:window_theme]) if raw[:window_theme]
+      validate_color_scheme!(raw[:color_scheme]) if raw.key?(:color_scheme)
+
+      raise ValidationError, "Configuration must have either 'lines' or 'frames'" if raw[:lines].nil? && raw[:frames].nil?
+
+      validate_lines!(raw[:lines]) if raw.key?(:lines)
+      validate_frames!(raw[:frames]) if raw.key?(:frames)
+    end
+
+    def validate_theme!(theme)
+      return if ThemeRegistry.valid_theme?(theme)
+
+      raise ValidationError, "Invalid theme '#{theme}'\n  → Available themes: #{ThemeRegistry.available_themes.join(", ")}"
+    end
+
+    def validate_window_theme!(theme)
+      return if ThemeRegistry.valid_window_theme?(theme)
+
+      raise ValidationError, "Invalid window_theme '#{theme}'"
+    end
+
+    def validate_color_scheme!(scheme)
+      return if ThemeRegistry.valid_color_scheme?(scheme)
+
+      raise ValidationError, "Invalid color_scheme '#{scheme}'"
+    end
+
+    def validate_nested_hash!(raw, key, allowed_keys)
+      return unless raw.key?(key)
+      raise ValidationError, "#{key} must be a mapping" unless raw[key].is_a?(Hash)
+
+      validate_keys!(raw[key], allowed_keys, key.to_s) if allowed_keys
+    end
+
+    def validate_keys!(hash, allowed_keys, context)
+      unknown_keys = hash.keys - allowed_keys
+      return if unknown_keys.empty?
+
+      raise ValidationError, "Unknown #{context} key(s): #{unknown_keys.join(", ")}"
+    end
+
+    def validate_lines!(lines)
+      raise ValidationError, "lines must be an array" unless lines.is_a?(Array)
+
+      lines.each_with_index do |line, index|
+        raise ValidationError, "lines[#{index}] must be a mapping" unless line.is_a?(Hash)
+
+        validate_keys!(line, LINE_KEYS, "lines[#{index}]")
+        if line.values_at(:prompt, :command, :output).all?(&:nil?)
+          raise ValidationError, "lines[#{index}] must include at least one of prompt, command, or output"
+        end
+        validate_line_values!(line, index)
+      end
+    end
+
+    def validate_frames!(frames)
+      raise ValidationError, "frames must be an array" unless frames.is_a?(Array)
+
+      frames.each_with_index do |frame, index|
+        raise ValidationError, "frames[#{index}] must be a mapping" unless frame.is_a?(Hash)
+
+        validate_keys!(frame, FRAME_KEYS, "frames[#{index}]")
+        validate_frame_shape!(frame, index)
+      end
+    end
+
+    def validate_line_values!(line, index)
+      %i[prompt command output prompt_color command_color output_color].each do |key|
+        validate_string_value!(line[key], "lines[#{index}].#{key}") if line.key?(key)
+      end
+      validate_boolean_value!(line[:selected], "lines[#{index}].selected") if line.key?(:selected)
+    end
+
+    def validate_frame_shape!(frame, index)
+      raise ValidationError, "frames[#{index}].prompt requires type" if frame[:prompt] && frame[:type].nil?
+
+      if frame.values_at(:type, :output, :delay).all?(&:nil?)
+        raise ValidationError, "frames[#{index}] must include type, output, or delay"
+      end
+
+      validate_string_value!(frame[:prompt], "frames[#{index}].prompt") if frame.key?(:prompt)
+      validate_string_value!(frame[:type], "frames[#{index}].type") if frame.key?(:type)
+      validate_string_value!(frame[:output], "frames[#{index}].output") if frame.key?(:output)
+      validate_string_value!(frame[:prompt_color], "frames[#{index}].prompt_color") if frame.key?(:prompt_color)
+      validate_string_value!(frame[:command_color], "frames[#{index}].command_color") if frame.key?(:command_color)
+      validate_string_value!(frame[:output_color], "frames[#{index}].output_color") if frame.key?(:output_color)
+      validate_non_negative_integer!(frame[:delay], "frames[#{index}].delay") if frame.key?(:delay)
+    end
+
+    def validate_string_value!(value, name)
+      return if value.is_a?(String)
+
+      raise ValidationError, "#{name} must be a string"
+    end
+
+    def validate_boolean_value!(value, name)
+      return if value == true || value == false
+
+      raise ValidationError, "#{name} must be true or false"
+    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
+  end
+end

data/lib/shellfie/raster_painter.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require_relative "image_magick_command_builder"
+require_relative "rendering/text_painter"
+require_relative "rendering/window_chrome"
+
+module Shellfie
+  class RasterPainter
+    include Rendering::TextPainter
+    include Rendering::WindowChrome
+
+    attr_reader :config, :theme, :font_resolver
+
+    def initialize(config:, theme:, font_resolver:, chrome_cache: nil)
+      @config = config
+      @theme = theme
+      @font_resolver = font_resolver
+      @chrome_cache = chrome_cache
+    end
+
+    def paint(geometry, output_path, transparent:)
+      return create_cached_image(geometry, output_path, transparent: transparent) if @chrome_cache
+
+      create_full_image(geometry, output_path, transparent: transparent)
+    end
+
+    private
+
+    def create_full_image(geometry, output_path, transparent:)
+      return create_direct_image(geometry, output_path, transparent: transparent) unless clip_content?(geometry)
+
+      with_temp_png do |base_path|
+        with_temp_png do |content_path|
+          create_chrome_image(geometry, base_path, transparent: transparent)
+          create_content_layer(geometry, content_path)
+          composite_layers(base_path, content_path, output_path)
+        end
+      end
+    end
+
+    def create_direct_image(geometry, output_path, transparent:)
+      ImageMagickCommandBuilder.convert do |convert|
+        ImageMagickCommandBuilder.canvas(
+          convert,
+          width: geometry[:canvas_width],
+          height: geometry[:canvas_height],
+          background: canvas_background(transparent)
+        )
+        draw_chrome(convert, geometry, transparent: transparent)
+        draw_content(convert, geometry)
+        finish_image(convert, output_path)
+      end
+    end
+
+    def create_cached_image(geometry, output_path, transparent:)
+      base_path = @chrome_cache.fetch(geometry, transparent: transparent) do |path|
+        create_chrome_image(geometry, path, transparent: transparent)
+      end
+      return create_cached_direct_image(base_path, geometry, output_path) unless clip_content?(geometry)
+
+      with_temp_png do |content_path|
+        create_content_layer(geometry, content_path)
+        composite_layers(base_path, content_path, output_path)
+      end
+    end
+
+    def create_cached_direct_image(base_path, geometry, output_path)
+      ImageMagickCommandBuilder.convert do |convert|
+        convert << base_path
+        draw_content(convert, geometry)
+        finish_image(convert, output_path)
+      end
+    end
+
+    def create_chrome_image(geometry, output_path, transparent:)
+      ImageMagickCommandBuilder.convert do |convert|
+        ImageMagickCommandBuilder.canvas(
+          convert,
+          width: geometry[:canvas_width],
+          height: geometry[:canvas_height],
+          background: canvas_background(transparent)
+        )
+        draw_chrome(convert, geometry, transparent: transparent)
+        ImageMagickCommandBuilder.output(convert, output_path, format: "png")
+      end
+    end
+
+    def create_content_layer(geometry, output_path)
+      ImageMagickCommandBuilder.convert do |convert|
+        ImageMagickCommandBuilder.canvas(
+          convert,
+          width: geometry[:canvas_width],
+          height: geometry[:canvas_height],
+          background: "xc:transparent"
+        )
+        ImageMagickCommandBuilder.region(convert, **content_region(geometry))
+        draw_content(convert, geometry)
+        ImageMagickCommandBuilder.clear_region(convert)
+        ImageMagickCommandBuilder.output(convert, output_path, format: "png")
+      end
+    end
+
+    def composite_layers(base_path, content_path, output_path)
+      ImageMagickCommandBuilder.convert do |convert|
+        convert << base_path
+        convert << content_path
+        ImageMagickCommandBuilder.composite_over(convert)
+        finish_image(convert, output_path)
+      end
+    end
+
+    def draw_chrome(convert, geometry, transparent:)
+      draw_shadow(convert, geometry) if geometry[:shadow]
+      draw_window(convert, geometry, transparent: transparent)
+      draw_title_bar(convert, geometry) unless config.headless
+    end
+
+    def finish_image(convert, output_path)
+      if config.window[:trim]
+        convert.trim
+        convert << "+repage"
+      end
+      ImageMagickCommandBuilder.output(convert, output_path)
+    end
+
+    def canvas_background(transparent)
+      gradient = config.window[:background_gradient]
+      return "xc:transparent" if transparent
+      return "gradient:#{gradient[0]}-#{gradient[1]}" if gradient.is_a?(Array) && gradient.size == 2
+
+      "xc:#{theme.colors[:background]}"
+    end
+
+    def clip_content?(geometry)
+      geometry[:scroll_offset].to_f.positive?
+    end
+
+    def content_region(geometry)
+      {
+        x: geometry[:margin] + geometry[:scaled_padding],
+        y: geometry[:margin] + geometry[:scaled_title_bar] + geometry[:scaled_padding],
+        width: [geometry[:scaled_width] - geometry[:scaled_padding] * 2, 1].max,
+        height: [geometry[:scaled_height] - geometry[:scaled_title_bar] - geometry[:scaled_padding] * 2, 1].max
+      }
+    end
+
+    def with_temp_png
+      file = Tempfile.new(["shellfie-layer", ".png"])
+      path = file.path
+      file.close
+      yield path
+    ensure
+      File.delete(path) if path && File.exist?(path)
+    end
+  end
+end

data/lib/shellfie/render_chrome_cache.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module Shellfie
+  class RenderChromeCache
+    def initialize
+      @entries = {}
+    end
+
+    def fetch(geometry, transparent:)
+      key = cache_key(geometry, transparent)
+      return @entries[key].path if @entries.key?(key)
+
+      temp = Tempfile.new(["shellfie-chrome", ".png"], binmode: true)
+      temp.close
+      yield temp.path
+      @entries[key] = temp
+      temp.path
+    end
+
+    def cleanup
+      @entries.each_value do |temp|
+        File.delete(temp.path) if File.exist?(temp.path)
+        temp.close unless temp.closed?
+      end
+      @entries.clear
+    end
+
+    private
+
+    def cache_key(geometry, transparent)
+      [
+        transparent,
+        geometry.values_at(:canvas_width, :canvas_height, :scaled_width, :scaled_height, :scaled_title_bar, :margin,
+          :shadow, :scaled_radius)
+      ]
+    end
+  end
+end

data/lib/shellfie/render_geometry.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "line_layout"
+
+module Shellfie
+  class RenderGeometry
+    def initialize(config:, theme:)
+      @config = config
+      @theme = theme
+    end
+
+    def build(lines, scale:, shadow:)
+      font_config = @theme.font
+      line_height = font_config[:size] * font_config[:line_height]
+      display_lines, visible_count = display_lines(lines, font_config, line_height)
+      total_height = title_bar_height + [visible_count, 1].max * line_height + padding * 2
+      margin = canvas_margin(scale, shadow && !exact_size?)
+      geometry = geometry_hash(
+        display_lines,
+        font_config,
+        line_height,
+        total_height,
+        scale,
+        margin,
+        shadow && !exact_size?,
+        visible_count
+      )
+      validate_pixel_limit!(geometry)
+      geometry
+    end
+
+    private
+
+    def display_lines(lines, font_config, line_height)
+      layout = LineLayout.new(@config)
+      display_lines = layout.prepare(
+        lines,
+        content_width: [width - (padding * 2), 1].max,
+        font_size: font_config[:size],
+        title_bar_height: title_bar_height,
+        padding: padding,
+        line_height: line_height
+      )
+      [display_lines, layout.visible_count]
+    end
+
+    def geometry_hash(lines, font_config, line_height, total_height, scale, margin, shadow, visible_count)
+      {
+        lines: lines,
+        visible_line_count: visible_count,
+        font_config: font_config,
+        width: width,
+        height: total_height,
+        padding: padding,
+        line_height: line_height,
+        font_size: font_config[:size],
+        title_bar_height: title_bar_height,
+        logical_width: width,
+        logical_height: total_height.ceil,
+        scale: scale,
+        scaled_width: (width * scale).to_i,
+        scaled_height: (total_height * scale).ceil,
+        scaled_padding: (padding * scale).to_i,
+        scaled_line_height: (line_height * scale).ceil,
+        scaled_font_size: (font_config[:size] * scale).to_i,
+        scaled_title_bar: (title_bar_height * scale).to_i,
+        scaled_radius: (corner_radius * scale).to_i,
+        scroll_offset: @config.window[:scroll_offset].to_f,
+        margin: margin,
+        canvas_width: (width * scale).to_i + margin * 2,
+        canvas_height: (total_height * scale).ceil + margin * 2,
+        shadow: shadow
+      }
+    end
+
+    def width
+      @config.window[:width]
+    end
+
+    def padding
+      @config.window[:padding]
+    end
+
+    def title_bar_height
+      @config.headless ? 0 : @theme.window_decoration[:title_bar_height]
+    end
+
+    def corner_radius
+      @config.headless ? 0 : @theme.window_decoration[:corner_radius]
+    end
+
+    def exact_size?
+      @config.window[:exact_size]
+    end
+
+    def canvas_margin(scale, shadow)
+      configured = @config.window[:margin]
+      return (configured * scale).to_i if configured
+      return 0 if @config.headless && !shadow
+      return 0 if exact_size?
+      return (10 * scale).to_i unless shadow
+
+      shadow_config = @theme.window_decoration[:shadow]
+      (([shadow_config[:blur].to_i, shadow_config[:offset_x].to_i.abs, shadow_config[:offset_y].to_i.abs].max + 10) * scale).to_i
+    end
+
+    def validate_pixel_limit!(geometry)
+      pixels = geometry[:canvas_width] * geometry[:canvas_height]
+      return if pixels <= @config.limits[:max_pixels]
+
+      raise ResourceLimitError, "Estimated image is too large (#{pixels} pixels, max #{@config.limits[:max_pixels]})"
+    end
+  end
+end