shellfie 0.1.1 → 1.1.0

data/lib/shellfie/config_validation.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+module Shellfie
+  module ConfigValidation
+    RESOURCE_LIMIT_CEILINGS = {
+      max_lines: 10_000,
+      max_frames: 500,
+      max_render_frames: 2_000,
+      max_characters: 200_000,
+      max_pixels: 50_000_000,
+      max_total_pixels: 2_000_000_000,
+      max_temp_bytes: 8_000_000_000
+    }.freeze
+    MAX_FRAME_DELAY_MS = 86_400_000
+
+    def validate!
+      validate_version!
+      validate_theme!
+      validate_window!
+      validate_appearance!
+      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_optional_positive_integer!(@window[:height], "window.height")
+      validate_non_negative_integer!(@window[:padding], "window.padding")
+      raise ValidationError, "window.padding must be at most 40" if @window[:padding] > 40
+      %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_inclusion!(@window[:ambiguous_width], "window.ambiguous_width", [1, 2])
+      validate_inclusion!(@window[:osc_policy], "window.osc_policy", %w[ignore preserve apply])
+      validate_inclusion!(@window[:graphics_policy], "window.graphics_policy", %w[ignore error])
+      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_appearance!
+      raise ValidationError, "title must be a string" unless @title.is_a?(String)
+      unless @colors.values.all?(String)
+        raise ValidationError, "colors values must be strings"
+      end
+      %i[title_bar_height button_size button_spacing button_width corner_radius].each do |key|
+        next unless @window_decoration.key?(key)
+
+        validate_non_negative_number!(@window_decoration[key], "window_decoration.#{key}")
+      end
+      return unless @window_decoration.key?(:shadow)
+
+      shadow = @window_decoration[:shadow]
+      raise ValidationError, "window_decoration.shadow must be a mapping" unless shadow.is_a?(Hash)
+      validate_non_negative_number!(shadow[:blur], "window_decoration.shadow.blur") if shadow.key?(:blur)
+      %i[offset_x offset_y].each do |key|
+        validate_finite_number!(shadow[key], "window_decoration.shadow.#{key}") if shadow.key?(key)
+      end
+      if shadow.key?(:color) && !shadow[:color].is_a?(String)
+        raise ValidationError, "window_decoration.shadow.color must be a string"
+      end
+    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_non_negative_integer!(@animation[:seed], "animation.seed")
+      raise ValidationError, "animation.seed must be at most 2147483647" if @animation[:seed] > 2_147_483_647
+      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")
+      %i[typing_speed command_delay output_delay final_delay].each do |key|
+        if @animation[key] > MAX_FRAME_DELAY_MS
+          raise ValidationError, "animation.#{key} must be at most #{MAX_FRAME_DELAY_MS}"
+        end
+      end
+      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_boolean!(@animation[:gif_optimize], "animation.gif_optimize")
+      validate_boolean!(@animation[:webp_lossless], "animation.webp_lossless")
+      validate_inclusion!(@animation[:palette], "animation.palette", self.class::VALID_PALETTES)
+      validate_inclusion!(@animation[:apng_prediction], "animation.apng_prediction", self.class::VALID_APNG_PREDICTIONS)
+      validate_positive_integer!(@animation[:gif_colors], "animation.gif_colors")
+      raise ValidationError, "animation.gif_colors must be between 2 and 256" unless @animation[:gif_colors].between?(2, 256)
+      %i[webp_quality webp_near_lossless].each do |key|
+        validate_non_negative_integer!(@animation[key], "animation.#{key}")
+        raise ValidationError, "animation.#{key} must be at most 100" if @animation[key] > 100
+      end
+      validate_non_negative_integer!(@animation[:webp_method], "animation.webp_method")
+      raise ValidationError, "animation.webp_method must be at most 6" if @animation[:webp_method] > 6
+      unless @animation[:loop_count].nil?
+        validate_non_negative_integer!(@animation[:loop_count], "animation.loop_count")
+        raise ValidationError, "animation.loop_count must be at most 65535" if @animation[:loop_count] > 65_535
+      end
+      validate_inclusion!(@animation[:scroll_easing], "animation.scroll_easing", self.class::VALID_SCROLL_EASINGS)
+      validate_inclusion!(@animation[:direction], "animation.direction", self.class::VALID_ANIMATION_DIRECTIONS)
+      validate_non_negative_integer!(@animation[:loop_offset], "animation.loop_offset")
+      validate_positive_integer!(@animation[:framerate], "animation.framerate")
+      validate_positive_number!(@animation[:playback_speed], "animation.playback_speed")
+      raise ValidationError, "animation.framerate must be at most 120" if @animation[:framerate] > 120
+      raise ValidationError, "animation.playback_speed must be at most 100" if @animation[:playback_speed] > 100
+    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)
+      @frames.each_with_index do |frame, index|
+        unless frame.respond_to?(:delay) && frame.delay.is_a?(Integer) && frame.delay.between?(0, MAX_FRAME_DELAY_MS)
+          raise ValidationError, "frames[#{index}].delay must be between 0 and #{MAX_FRAME_DELAY_MS}"
+        end
+      end
+    end
+
+    def validate_limits!
+      unknown = @limits.keys - RESOURCE_LIMIT_CEILINGS.keys
+      raise ValidationError, "Unknown limits key(s): #{unknown.join(", ")}" unless unknown.empty?
+
+      @limits.each_key do |key|
+        validate_positive_integer!(@limits[key], "limits.#{key}")
+        ceiling = RESOURCE_LIMIT_CEILINGS.fetch(key)
+        raise ValidationError, "limits.#{key} must be at most #{ceiling}" if @limits[key] > ceiling
+      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!
+      return if @window[:width] >= 120
+
+      raise ValidationError, "window.width must be at least 120px"
+    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.finite? && value.positive?
+
+      raise ValidationError, "#{name} must be a positive number"
+    end
+
+    def validate_non_negative_number!(value, name)
+      return if value.is_a?(Numeric) && value.finite? && value >= 0
+
+      raise ValidationError, "#{name} must be a non-negative number"
+    end
+
+    def validate_finite_number!(value, name)
+      return if value.is_a?(Numeric) && value.finite?
+
+      raise ValidationError, "#{name} must be a finite 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,147 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require "open3"
+require "tempfile"
+require_relative "font_resolver"
+
+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 ffmpeg_path
+        @ffmpeg_path ||= find_executable(%w[ffmpeg], verify_imagemagick: false)
+      end
+
+      def ensure_ffmpeg!
+        return if ffmpeg_path
+
+        raise DependencyError, "ffmpeg not found; install ffmpeg to generate APNG, MP4, or WebM"
+      end
+
+      def ffmpeg_version
+        return unless ffmpeg_path
+
+        output, = Open3.capture3(ffmpeg_path, "-version")
+        output.lines.first&.strip
+      rescue SystemCallError
+        nil
+      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)
+        details = imagemagick_details
+        video_version = ffmpeg_version
+        [
+          check("Ruby", RUBY_VERSION, Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.0.0")),
+          check("ImageMagick", details[:version] || "not found", imagemagick_available?),
+          check("Image formats", details[:formats].empty? ? "unavailable" : details[:formats].join(", "),
+                (required_formats - details[:formats]).empty?),
+          check("Image render", details[:render_ok] ? "1x1 PNG generated" : "failed", details[:render_ok]),
+          check("Fonts", details[:font_count].to_s, details[:font_count].positive?),
+          check("Security policy", details[:policy] || "unavailable", !details[:policy].nil?),
+          check("ffmpeg (optional)", video_version || "not found; required only for APNG/MP4/WebM", true),
+          check("Writable output", output_dir, File.writable?(output_dir)),
+          check("Encoding", Encoding.default_external.name, true)
+        ]
+      end
+
+      def imagemagick_details
+        return { version: nil, formats: [], font_count: 0, render_ok: false, policy: nil } unless imagemagick_available?
+
+        version_output, _error, version_status = Open3.capture3(imagemagick_path, "-version")
+        formats_output, _error, formats_status = Open3.capture3(imagemagick_path, "-list", "format")
+        fonts_output, _error, fonts_status = Open3.capture3(imagemagick_path, "-list", "font")
+        policy_output, _error, policy_status = Open3.capture3(imagemagick_path, "-list", "policy")
+        {
+          version: version_status.success? ? version_output.lines.first&.strip : nil,
+          formats: formats_status.success? ? required_formats.select { |format| formats_output.match?(/^\s*#{format}\*?\s/im) } : [],
+          font_count: (fonts_status.success? ? fonts_output.scan(/^\s*Font:/).size : 0) +
+            FontResolver::FONT_FILES.values.uniq.count { |path| File.file?(path) },
+          render_ok: render_smoke_test,
+          policy: policy_status.success? ? "#{policy_output.scan(/^\s*Policy:/).size} rules loaded" : nil
+        }
+      rescue SystemCallError
+        { version: nil, formats: [], font_count: 0, render_ok: false, policy: nil }
+      end
+
+      private
+
+      def check(name, detail, ok)
+        { name: name, detail: detail, ok: ok }
+      end
+
+      def find_executable(names, verify_imagemagick: true)
+        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}")
+              next unless File.file?(candidate) && File.executable?(candidate)
+              return candidate unless verify_imagemagick
+              return candidate if imagemagick_executable?(candidate)
+            end
+          end
+        end
+
+        nil
+      end
+
+      def imagemagick_executable?(candidate)
+        output, = Open3.capture3(candidate, "-version")
+        output.include?("ImageMagick")
+      rescue SystemCallError
+        false
+      end
+
+      def required_formats
+        %w[PNG GIF WEBP SVG]
+      end
+
+      def render_smoke_test
+        Tempfile.create(["shellfie-doctor", ".png"]) do |file|
+          _output, _error, status = Open3.capture3(imagemagick_path, "-size", "1x1", "xc:none", file.path)
+          return status.success? && File.binread(file.path, 8) == "\x89PNG\r\n\x1a\n".b
+        end
+      rescue SystemCallError, EOFError
+        false
+      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,26 @@
 # 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
+  class ExecutionError < Error; end
 end

data/lib/shellfie/ffmpeg_encoder.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tempfile"
+require_relative "errors"
+
+module Shellfie
+  class FfmpegEncoder
+    def self.encode(images, output_path, format:, command:, framerate:, playback_speed:, loop:, loop_count: nil,
+                    apng_prediction: nil)
+      list = Tempfile.new(["shellfie-frames", ".txt"])
+      minimum_delay = 1_000.0 / framerate
+      images.each do |image|
+        list.puts "file '#{image[:path].gsub("'", "'\\''")}'"
+        list.puts "duration #{[image[:delay].to_f, minimum_delay].max / 1_000.0 / playback_speed}"
+      end
+      list.puts "file '#{images.last[:path].gsub("'", "'\\''")}'"
+      list.close
+
+      total_duration = images.sum { |image| [image[:delay].to_f, minimum_delay].max } / 1_000.0 / playback_speed
+      filters = ["fps=#{framerate}"]
+      codec = case format
+              when "mp4"
+                filters << "pad=ceil(iw/2)*2:ceil(ih/2)*2"
+                %w[-c:v libx264 -pix_fmt yuv420p -movflags +faststart]
+              when "webm"
+                filters << "pad=ceil(iw/2)*2:ceil(ih/2)*2"
+                %w[-c:v libvpx-vp9 -pix_fmt yuva420p]
+              when "apng"
+                filters << "format=rgba"
+                options = ["-plays", (loop_count || (loop ? 0 : 1)).to_s]
+                options.concat(["-pred", apng_prediction]) if apng_prediction
+                options.concat(["-f", "apng"])
+              else raise RenderError, "Unsupported ffmpeg format: #{format}"
+              end
+      timing = ["-vf", filters.join(","), "-fps_mode", "cfr", "-t", total_duration.to_s]
+      _stdout, stderr, status = Open3.capture3(command, "-y", "-f", "concat", "-safe", "0", "-i", list.path,
+                                               *timing, *codec, output_path)
+      raise RenderError, "ffmpeg encode failed: #{stderr}" unless status.success?
+
+      output_path
+    ensure
+      list&.close!
+    end
+  end
+end

data/lib/shellfie/font_resolver.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "open3"
+require "digest"
+
+module Shellfie
+  class FontResolver
+    FONT_FILES = {
+      "Monaco" => "/System/Library/Fonts/Monaco.ttf",
+      "SF Mono" => "/System/Library/Fonts/SFNSMono.ttf",
+      "SF Mono Italic" => "/System/Library/Fonts/SFNSMonoItalic.ttf",
+      "Menlo" => "/System/Library/Fonts/Menlo.ttc",
+      "Courier" => "/System/Library/Fonts/Courier.ttc",
+      "Courier New" => "/System/Library/Fonts/Supplemental/Courier New.ttf",
+      "DejaVu-Sans-Mono" => "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf",
+      "DejaVu Sans Mono" => "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf"
+    }.freeze
+
+    def initialize(command_provider)
+      @command_provider = command_provider
+    end
+
+    def resolve(font_config, italic:)
+      candidates = []
+      candidates << font_config[:italic_family] if italic
+      candidates << font_config[:family]
+      candidates << font_config[:fallback_family]
+      candidates << font_config[:emoji_family]
+      candidates << "Menlo"
+      candidates << "DejaVu-Sans-Mono"
+      candidates << "Courier"
+
+      candidates.compact.flat_map { |candidate| font_candidates(candidate.to_s) }
+                .find { |candidate| font_available?(candidate) }
+    end
+
+    def details(font_config)
+      { regular: resolve(font_config, italic: false), italic: resolve(font_config, italic: true) }.transform_values do |font|
+        { name: font, sha256: File.file?(font.to_s) ? Digest::SHA256.file(font).hexdigest : nil }
+      end
+    end
+
+    private
+
+    def font_available?(font)
+      return true if File.exist?(font)
+      return true if available_fonts.include?(font)
+
+      false
+    end
+
+    def font_candidates(font)
+      [font, FONT_FILES[font]].compact
+    end
+
+    def available_fonts
+      @available_fonts ||= begin
+        command = @command_provider.call
+        if command.empty?
+          []
+        else
+          stdout, = Open3.capture3(command, "-list", "font")
+          stdout.scan(/^\s*Font:\s+(.+)$/).flatten
+        end
+      end
+    end
+  end
+end

data/lib/shellfie/format_resolver.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Shellfie
+  class FormatResolver
+    class << self
+      def resolve(output_path, explicit:, default:)
+        return explicit if explicit
+        return default if output_path == "-"
+
+        extension = File.extname(output_path).delete_prefix(".")
+        extension.empty? ? default : extension
+      end
+    end
+  end
+end