shellfie 1.0.0 → 1.1.0

data/lib/shellfie/ansi_line_buffer.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
+require_relative "text_metrics"
+
 module Shellfie
   class AnsiLineBuffer
-    def initialize
+    CONTINUATION = Object.new.freeze
+
+    def initialize(tab_width: 8)
       @cells = []
       @column = 0
       @pending_escape = +""
+      @tab_width = tab_width
     end
 
     def write_escape(sequence)
@@ -18,13 +23,19 @@ module Shellfie
         @column = 0
       when "\b"
         @column = [@column - 1, 0].max
-        @cells[@column] = nil
+      when "\t"
+        @column += @tab_width - (@column % @tab_width)
       when "\a"
         nil
       else
+        width = TextMetrics.grapheme_width(char)
+        return if width.zero?
+
+        clear_wide_cell(@column)
         @cells[@column] = "#{@pending_escape}#{char}"
+        @cells[@column + 1] = CONTINUATION if width == 2
         @pending_escape = +""
-        @column += 1
+        @column += width
       end
     end
 
@@ -55,7 +66,7 @@ module Shellfie
       last = @cells.rindex { |cell| !cell.nil? }
       return @pending_escape unless last
 
-      @cells[0..last].map { |cell| cell || " " }.join + @pending_escape
+      @cells[0..last].map { |cell| cell.equal?(CONTINUATION) ? "" : (cell || " ") }.join + @pending_escape
     end
 
     private
@@ -83,5 +94,10 @@ module Shellfie
     def clear_range(range)
       range.each { |index| @cells[index] = nil if index < @cells.length }
     end
+
+    def clear_wide_cell(column)
+      @cells[column - 1] = nil if column.positive? && @cells[column].equal?(CONTINUATION)
+      @cells[column + 1] = nil if @cells[column + 1].equal?(CONTINUATION)
+    end
   end
 end

data/lib/shellfie/ansi_normalizer.rb

@@ -5,20 +5,25 @@ require_relative "ansi_line_buffer"
 
 module Shellfie
   module AnsiNormalizer
-    ANSI_REGEX = /\e\[([0-9;]*)m/
+    ANSI_REGEX = /\e\[([0-9;:]*)m/
     OSC_REGEX = /\e\].*?(?:\a|\e\\)/
-    CSI_CONTROL_REGEX = /\e\[[0-9;?]*[A-Za-ln-z]/
+    STRING_CONTROL_REGEX = /\e(?:P|_|\^).*?(?:\a|\e\\)/m
+    INCOMPLETE_STRING_CONTROL_REGEX = /\e(?:P|_|\^).*\z/m
+    GRAPHICS_CONTROL_PREFIX = /\e(?:_G|P[0-9;?]*q|\]1337;File=)/
+    CSI_CONTROL_REGEX = /\e\[[0-9;:?]*[A-Za-ln-z]/
 
     module_function
 
-    def normalize(text)
-      text = text.gsub(OSC_REGEX, "")
-      text = apply_line_controls(text)
+    def normalize(text, tab_width: 8, osc_policy: "ignore")
+      text = text.gsub(STRING_CONTROL_REGEX, "").gsub(INCOMPLETE_STRING_CONTROL_REGEX, "")
+      text = TextMetrics.graphemes(text).join
+      text = text.gsub(OSC_REGEX) { |sequence| osc_policy == "ignore" || !sequence.start_with?("\e]8;") ? "" : sequence }
+      text = apply_line_controls(text, tab_width: tab_width)
       text.gsub(CSI_CONTROL_REGEX, "")
     end
 
-    def apply_line_controls(text)
-      buffer = AnsiLineBuffer.new
+    def apply_line_controls(text, tab_width: 8)
+      buffer = AnsiLineBuffer.new(tab_width: tab_width)
       scanner = StringScanner.new(text)
 
       until scanner.eos?
@@ -27,6 +32,11 @@ module Shellfie
           next
         end
 
+        if scanner.scan(OSC_REGEX)
+          buffer.write_escape(scanner.matched)
+          next
+        end
+
         if scanner.scan(/\e\[([0-9;?]*)[JK]/)
           buffer.clear(scanner.matched[-1], scanner[1])
           next
@@ -42,7 +52,7 @@ module Shellfie
           next
         end
 
-        buffer.write_character(scanner.getch)
+        buffer.write_character(scanner.scan(/\X/))
       end
 
       buffer.to_s

data/lib/shellfie/ansi_parser.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 require "strscan"
+require "uri"
 require_relative "ansi_colors"
 require_relative "ansi_normalizer"
+require_relative "errors"
 
 module Shellfie
   Segment = Struct.new(
@@ -12,30 +14,57 @@ module Shellfie
     :bold,
     :italic,
     :underline,
+    :underline_style,
+    :underline_color,
     :dim,
     :reverse,
     :strikethrough,
     :overline,
+    :blink,
+    :conceal,
+    :link,
     keyword_init: true
   )
 
   class AnsiParser
-    ANSI_REGEX = /\e\[([0-9;]*)m/
+    ANSI_REGEX = /\e\[([0-9;:]*)m/
 
-    def initialize(state_mode: :persistent)
+    OSC_REGEX = /\e\](.*?)?(?:\a|\e\\)/m
+    MAX_LINK_BYTES = 2_048
+    MAX_OSC_BYTES = MAX_LINK_BYTES + 64
+    LINK_SCHEMES = %w[http https mailto].freeze
+
+    def initialize(state_mode: :persistent, tab_width: 8, osc_policy: "ignore", graphics_policy: "ignore")
       @state_mode = state_mode.to_sym
+      @tab_width = tab_width
+      @osc_policy = osc_policy.to_s
+      @graphics_policy = graphics_policy.to_s
+      @link = nil
+      @pending_osc = +""
       reset_state
     end
 
     def parse(text)
-      reset_state if @state_mode == :line
+      if @state_mode == :line
+        reset_state
+        @link = nil
+      end
 
+      input = @pending_osc + text.to_s
+      reject_terminal_graphics!(input)
+      input, @pending_osc = split_incomplete_osc(input)
       segments = []
-      scanner = StringScanner.new(AnsiNormalizer.normalize(text.to_s))
+      scanner = StringScanner.new(AnsiNormalizer.normalize(input, tab_width: @tab_width, osc_policy: @osc_policy))
       current_text = +""
 
       until scanner.eos?
-        if scanner.scan(ANSI_REGEX)
+        if scanner.scan(OSC_REGEX)
+          unless current_text.empty?
+            segments << create_segment(current_text)
+            current_text = +""
+          end
+          process_osc(scanner[1])
+        elsif scanner.scan(ANSI_REGEX)
           unless current_text.empty?
             segments << create_segment(current_text)
             current_text = +""
@@ -52,16 +81,26 @@ module Shellfie
 
     private
 
+    def reject_terminal_graphics!(text)
+      return unless @graphics_policy == "error" && text.match?(AnsiNormalizer::GRAPHICS_CONTROL_PREFIX)
+
+      raise ValidationError, "Terminal graphics are not supported; use window.graphics_policy: ignore to discard them"
+    end
+
     def reset_state
       @foreground = nil
       @background = nil
       @bold = false
       @italic = false
       @underline = false
+      @underline_style = nil
+      @underline_color = nil
       @dim = false
       @reverse = false
       @strikethrough = false
       @overline = false
+      @blink = false
+      @conceal = false
     end
 
     def create_segment(text)
@@ -72,22 +111,34 @@ module Shellfie
         bold: @bold,
         italic: @italic,
         underline: @underline,
+        underline_style: @underline_style,
+        underline_color: @underline_color,
         dim: @dim,
         reverse: @reverse,
         strikethrough: @strikethrough,
-        overline: @overline
+        overline: @overline,
+        blink: @blink,
+        conceal: @conceal,
+        link: @link
       )
     end
 
     def process_codes(codes_str)
       return reset_state if codes_str.empty?
 
-      codes = codes_str.split(";").map { |code| code.empty? ? 0 : code.to_i }
+      codes = sgr_codes(codes_str)
       i = 0
 
       while i < codes.length
         code = codes[i]
 
+        if code.is_a?(Array) && code.first == :underline_style
+          @underline_style = %i[none single double curly dotted dashed][code.last]
+          @underline = @underline_style && @underline_style != :none
+          i += 1
+          next
+        end
+
         case code
         when 0
           reset_state
@@ -99,6 +150,11 @@ module Shellfie
           @italic = true
         when 4
           @underline = true
+          @underline_style = :single
+        when 5, 6
+          @blink = true
+        when 8
+          @conceal = true
         when 7
           @reverse = true
         when 9
@@ -110,8 +166,13 @@ module Shellfie
           @italic = false
         when 24
           @underline = false
+          @underline_style = nil
+        when 25
+          @blink = false
         when 27
           @reverse = false
+        when 28
+          @conceal = false
         when 29
           @strikethrough = false
         when 30..37, 90..97
@@ -126,15 +187,67 @@ module Shellfie
           i, @background = AnsiColors.parse_extended_color(codes, i)
         when 49
           @background = nil
+        when 21
+          @underline = true
+          @underline_style = :double
         when 53
           @overline = true
         when 55
           @overline = false
+        when 58
+          i, @underline_color = AnsiColors.parse_extended_color(codes, i)
+        when 59
+          @underline_color = nil
         end
 
         i += 1
       end
     end
 
+    def sgr_codes(value)
+      value.split(";").flat_map do |field|
+        parts = field.split(":", -1)
+        next(field.empty? ? 0 : field.to_i) if parts.size == 1
+
+        code, mode = parts.values_at(0, 1).map(&:to_i)
+        if code == 4 && parts.size == 2 && parts.last.match?(/\A[0-5]\z/)
+          [[:underline_style, parts.last.to_i]]
+        elsif [38, 48, 58].include?(code) && mode == 2 && [5, 6].include?(parts.size) && parts.last(3).all? { |item| item.match?(/\A\d+\z/) }
+          [code, mode, *parts.last(3).map(&:to_i)]
+        elsif [38, 48, 58].include?(code) && mode == 5 && parts.size == 3 && parts.last.match?(/\A\d+\z/)
+          [code, mode, parts.last.to_i]
+        else
+          []
+        end
+      end
+    end
+
+    def process_osc(value)
+      return unless value.to_s.start_with?("8;")
+
+      uri = value.to_s.split(";", 3)[2].to_s
+      @link = uri.empty? ? nil : safe_link(uri)
+    end
+
+    def safe_link(value)
+      return if value.bytesize > MAX_LINK_BYTES || value.match?(/[\x00-\x1f\x7f]/)
+
+      uri = URI.parse(value)
+      value if LINK_SCHEMES.include?(uri.scheme&.downcase)
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def split_incomplete_osc(value)
+      start = value.rindex("\e]")
+      return [value, +""] unless start
+
+      tail = value[start..]
+      return [value, +""] if tail.match?(OSC_REGEX)
+      return [value[0...start], tail] if tail.bytesize <= MAX_OSC_BYTES
+
+      [value[0...start], +""]
+    end
+
   end
 end

data/lib/shellfie/cassette.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "errors"
+require_relative "output_writer"
+require_relative "session"
+
+module Shellfie
+  class Cassette
+    MAX_BYTES = 32 * 1_048_576
+    MAX_EVENTS = 10_000
+    TOP_LEVEL_KEYS = %i[version title columns rows events captures exit_status].freeze
+    EVENT_KEYS = %i[text delay visible status screen].freeze
+
+    def self.write(path, session)
+      OutputWriter.write(path, extension: "json") do |temporary_path|
+        json = JSON.pretty_generate(session.to_h)
+        raise ResourceLimitError, "Cassette is too large (max #{MAX_BYTES} bytes)" if json.bytesize > MAX_BYTES
+
+        File.write(temporary_path, json)
+      end
+    end
+
+    def self.read(path)
+      raise ParseError, "Cassette file not found: #{path}" unless File.file?(path)
+      content = File.open(path, "rb") { |file| file.read(MAX_BYTES + 1) }
+      raise ParseError, "Cassette is too large (max #{MAX_BYTES} bytes)" if content.bytesize > MAX_BYTES
+
+      raw = JSON.parse(content, symbolize_names: true)
+      validate!(raw)
+
+      Session.new(
+        columns: raw[:columns],
+        rows: raw[:rows],
+        title: raw[:title],
+        events: raw[:events] || [],
+        captures: raw[:captures] || {},
+        exit_status: raw[:exit_status]
+      )
+    rescue JSON::ParserError => e
+      raise ParseError, "Invalid cassette: #{e.message}"
+    end
+
+    def self.validate!(raw)
+      raise ParseError, "Cassette must be a JSON object" unless raw.is_a?(Hash)
+      raise ParseError, "Unsupported cassette version" unless raw[:version] == 1
+      raise ParseError, "Unknown cassette key" unless (raw.keys - TOP_LEVEL_KEYS).empty?
+      raise ParseError, "Cassette title must be a string" unless raw[:title].is_a?(String)
+      unless raw[:columns].is_a?(Integer) && raw[:columns].between?(1, 500) &&
+             raw[:rows].is_a?(Integer) && raw[:rows].between?(1, 200)
+        raise ParseError, "Invalid cassette dimensions"
+      end
+
+      events = raw[:events] || []
+      raise ParseError, "Cassette events must be an array" unless events.is_a?(Array)
+      raise ParseError, "Cassette has too many events" if events.size > MAX_EVENTS
+      events.each_with_index do |event, index|
+        unless event.is_a?(Hash) && (event.keys - EVENT_KEYS).empty? && event[:text].is_a?(String) &&
+               event[:delay].is_a?(Numeric) && event[:delay].finite? && event[:delay] >= 0 &&
+               [true, false].include?(event.fetch(:visible, true)) &&
+               (!event.key?(:screen) || event[:screen].is_a?(Array) && event[:screen].all?(String)) &&
+               (event[:status].nil? || event[:status].is_a?(Integer) && event[:status].between?(0, 255))
+          raise ParseError, "Invalid cassette event at index #{index}"
+        end
+      end
+
+      captures = raw[:captures] || {}
+      unless captures.is_a?(Hash) && captures.all? { |name, lines| name.is_a?(Symbol) && lines.is_a?(Array) && lines.all?(String) }
+        raise ParseError, "Cassette captures must map names to arrays of strings"
+      end
+      unless raw[:exit_status].nil? || raw[:exit_status].is_a?(Integer) && raw[:exit_status].between?(0, 255)
+        raise ParseError, "Invalid cassette exit status"
+      end
+    end
+  end
+end

data/lib/shellfie/cli.rb

@@ -4,14 +4,19 @@ require "optparse"
 require_relative "../shellfie"
 require_relative "cli_generate"
 require_relative "cli_info"
+require_relative "cli_run"
+require_relative "cli_authoring"
 require_relative "dependency_checker"
+require_relative "transcript_renderer"
 
 module Shellfie
   class CLI
     include CLIGenerate
     include CLIInfo
+    include CLIRun
+    include CLIAuthoring
 
-    COMMANDS = %w[generate init themes validate inspect doctor version help].freeze
+    COMMANDS = %w[generate run record replay new format compile schema completion watch init themes validate inspect doctor version help].freeze
 
     def initialize(args)
       @args = args.dup
@@ -28,6 +33,24 @@ module Shellfie
         run_generate
       when "init"
         run_init
+      when "run"
+        run_session
+      when "record"
+        run_session(record: true)
+      when "replay"
+        replay_session
+      when "new"
+        run_new
+      when "format"
+        run_format
+      when "compile"
+        run_compile
+      when "schema"
+        run_schema
+      when "completion"
+        run_completion
+      when "watch"
+        run_watch
       when "themes"
         run_themes
       when "validate"
@@ -46,15 +69,53 @@ module Shellfie
         exit 1
       end
     rescue Shellfie::Error => e
-      warn_error "Error: #{e.message}"
+      if @options[:validation_format] && @options[:validation_format] != "text"
+        emit_validation_report(valid: false, error: e)
+      else
+        warn_error "Error: #{e.message}"
+      end
       exit determine_exit_code(e)
     rescue OptionParser::ParseError => e
       warn_error "Error: #{e.message}"
       exit 1
+    rescue SystemCallError => e
+      warn_error "Error: #{e.message}"
+      exit 5
     end
 
     private
 
+    def canonical_output_path(path)
+      expanded = File.expand_path(path)
+      missing = []
+      current = expanded
+      until File.exist?(current)
+        parent = File.dirname(current)
+        break if parent == current
+
+        missing.unshift(File.basename(current))
+        current = parent
+      end
+      File.join(File.realpath(current), *missing)
+    rescue Errno::ENOENT
+      expanded
+    end
+
+    def configuration_version(path)
+      raw = YamlSafety.load_file(path, max_bytes: Parser::MAX_INCLUDE_BYTES)
+      raw.is_a?(Hash) ? raw[:version] : nil
+    end
+
+    def replaceable_png_sequence_directory?(path)
+      entries = Dir.children(path)
+      entries.empty? || (entries.include?("timeline.json") &&
+        entries.all? { |entry| entry == "timeline.json" || entry.match?(/\Aframe_\d{4}\.png\z/) })
+    end
+
+    def path_within?(path, directory)
+      path == directory || path.start_with?("#{directory}#{File::SEPARATOR}")
+    end
+
     def warn_error(message)
       $stderr.puts message
     end
@@ -69,6 +130,8 @@ module Shellfie
         4
       when FileSystemError
         5
+      when ExecutionError
+        6
       else
         1
       end