backspin 0.3.0 → 0.4.1

data/fixtures/backspin/nil_filter.yml

@@ -0,0 +1,14 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Open3::Capture3
+  args:
+  - echo
+  - "'test'"
+  stdout: 'test
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/none_mode_test.yml

@@ -0,0 +1,14 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Open3::Capture3
+  args:
+  - echo
+  - "'original'"
+  stdout: 'original
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/path_test.yml

@@ -0,0 +1,17 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Open3::Capture3
+  args:
+  - echo
+  - "'File"
+  - saved
+  - to
+  - "/Users/testuser/project/output.txt'"
+  stdout: 'File saved to PROJECT_ROOT/output.txt
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/playback_system.yml

@@ -0,0 +1,12 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Kernel::System
+  args:
+  - echo
+  - recorded
+  stdout: ''
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/playback_test.yml

@@ -0,0 +1,14 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Open3::Capture3
+  args:
+  - echo
+  - original
+  stdout: 'original
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/stderr_test.yml

@@ -0,0 +1,19 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Open3::Capture3
+  args:
+  - sh
+  - "-c"
+  - "'echo"
+  - error
+  - ">&2;"
+  - exit
+  - 1'
+  stdout: ''
+  stderr: 'error
+
+    '
+  status: 1
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/system_echo.yml

@@ -0,0 +1,12 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Kernel::System
+  args:
+  - echo
+  - hello
+  stdout: ''
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/system_false.yml

@@ -0,0 +1,18 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Kernel::System
+  args:
+  - 'true'
+  stdout: ''
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'
+- command_type: Kernel::System
+  args:
+  - 'false'
+  stdout: ''
+  stderr: ''
+  status: 1
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/timestamp_test.yml

@@ -0,0 +1,18 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Open3::Capture3
+  args:
+  - echo
+  - "'Test"
+  - run
+  - at
+  - '2024-01-15'
+  - 10:30:45'
+  stdout: 'Test run at TIMESTAMP
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/use_record_filter.yml

@@ -0,0 +1,15 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Open3::Capture3
+  args:
+  - echo
+  - "'hello"
+  - world'
+  stdout: 'HELLO WORLD
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/verify_system.yml

@@ -0,0 +1,12 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Kernel::System
+  args:
+  - echo
+  - hello
+  stdout: ''
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/verify_system_diff.yml

@@ -0,0 +1,11 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Kernel::System
+  args:
+  - 'true'
+  stdout: ''
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/fixtures/backspin/version_test.yml

@@ -0,0 +1,14 @@
+---
+first_recorded_at: '2025-05-01T12:00:00Z'
+format_version: '2.0'
+commands:
+- command_type: Open3::Capture3
+  args:
+  - ruby
+  - "--version"
+  stdout: 'ruby 3.4.4 (2025-05-14 revision a38531fd3f) +PRISM [arm64-darwin24]
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2025-05-01T12:00:00Z'

data/lib/backspin/command.rb

@@ -1,14 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "command_result"
+
 module Backspin
   class Command
-    attr_reader :args, :stdout, :stderr, :status, :recorded_at, :method_class
+    attr_reader :args, :result, :recorded_at, :method_class
 
-    def initialize(method_class:, args:, stdout: nil, stderr: nil, status: nil, recorded_at: nil)
+    def initialize(method_class:, args:, stdout: nil, stderr: nil, status: nil, result: nil, recorded_at: nil)
       @method_class = method_class
       @args = args
-      @stdout = stdout
-      @stderr = stderr
-      @status = status
       @recorded_at = recorded_at
+
+      # Accept either a CommandResult or individual stdout/stderr/status
+      @result = result || CommandResult.new(
+        stdout: stdout || "",
+        stderr: stderr || "",
+        status: status || 0
+      )
+    end
+
+    def stdout
+      @result.stdout
+    end
+
+    def stderr
+      @result.stderr
+    end
+
+    def status
+      @result.status
     end
 
     # Convert to hash for YAML serialization
@@ -16,16 +36,14 @@ module Backspin
       data = {
         "command_type" => @method_class.name,
         "args" => scrub_args(@args),
-        "stdout" => Backspin.scrub_text(@stdout),
-        "stderr" => Backspin.scrub_text(@stderr),
-        "status" => @status,
+        "stdout" => Backspin.scrub_text(@result.stdout),
+        "stderr" => Backspin.scrub_text(@result.stderr),
+        "status" => @result.status,
         "recorded_at" => @recorded_at
       }
 
       # Apply filter if provided
-      if filter
-        data = filter.call(data)
-      end
+      data = filter.call(data) if filter
 
       data
     end
@@ -59,11 +77,12 @@ module Backspin
       return args unless Backspin.configuration.scrub_credentials && args
 
       args.map do |arg|
-        if arg.is_a?(String)
+        case arg
+        when String
           Backspin.scrub_text(arg)
-        elsif arg.is_a?(Array)
+        when Array
           scrub_args(arg)
-        elsif arg.is_a?(Hash)
+        when Hash
           arg.transform_values { |v| v.is_a?(String) ? Backspin.scrub_text(v) : v }
         else
           arg

data/lib/backspin/command_diff.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Backspin
+  # Represents the difference between a recorded command and actual execution
+  # Handles verification and diff generation for a single command
+  class CommandDiff
+    attr_reader :recorded_command, :actual_result, :matcher
+
+    def initialize(recorded_command:, actual_result:, matcher: nil)
+      @recorded_command = recorded_command
+      @actual_result = actual_result
+      @matcher = matcher
+    end
+
+    # @return [Boolean] true if the command output matches
+    def verified?
+      if matcher
+        matcher.call(recorded_command.to_h, actual_result.to_h)
+      else
+        recorded_command.result == actual_result
+      end
+    end
+
+    # @return [String, nil] Human-readable diff if not verified
+    def diff
+      return nil if verified?
+
+      parts = []
+
+      parts << stdout_diff if recorded_command.stdout != actual_result.stdout
+
+      parts << stderr_diff if recorded_command.stderr != actual_result.stderr
+
+      if recorded_command.status != actual_result.status
+        parts << "Exit status: expected #{recorded_command.status}, got #{actual_result.status}"
+      end
+
+      parts.join("\n\n")
+    end
+
+    # @return [String] Single line summary for error messages
+    def summary
+      if verified?
+        "✓ Command verified"
+      else
+        "✗ Command failed: #{failure_reason}"
+      end
+    end
+
+    private
+
+    def failure_reason
+      reasons = []
+      reasons << "stdout differs" if recorded_command.stdout != actual_result.stdout
+      reasons << "stderr differs" if recorded_command.stderr != actual_result.stderr
+      reasons << "exit status differs" if recorded_command.status != actual_result.status
+      reasons.join(", ")
+    end
+
+    def stdout_diff
+      "stdout diff:\n#{generate_line_diff(recorded_command.stdout, actual_result.stdout)}"
+    end
+
+    def stderr_diff
+      "stderr diff:\n#{generate_line_diff(recorded_command.stderr, actual_result.stderr)}"
+    end
+
+    def generate_line_diff(expected, actual)
+      expected_lines = (expected || "").lines
+      actual_lines = (actual || "").lines
+
+      diff_lines = []
+      max_lines = [expected_lines.length, actual_lines.length].max
+
+      max_lines.times do |i|
+        expected_line = expected_lines[i]
+        actual_line = actual_lines[i]
+
+        if expected_line != actual_line
+          diff_lines << "-#{expected_line.chomp}" if expected_line
+          diff_lines << "+#{actual_line.chomp}" if actual_line
+        end
+      end
+
+      diff_lines.join("\n")
+    end
+  end
+end

data/lib/backspin/command_result.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Backspin
+  # Represents the result of executing a command
+  # Stores stdout, stderr, and exit status
+  class CommandResult
+    attr_reader :stdout, :stderr, :status
+
+    def initialize(stdout:, stderr:, status:)
+      @stdout = stdout
+      @stderr = stderr
+      @status = normalize_status(status)
+    end
+
+    # @return [Boolean] true if the command succeeded (exit status 0)
+    def success?
+      status.zero?
+    end
+
+    # @return [Boolean] true if the command failed (non-zero exit status)
+    def failure?
+      !success?
+    end
+
+    # @return [Hash] Hash representation of the result
+    def to_h
+      {
+        "stdout" => stdout,
+        "stderr" => stderr,
+        "status" => status
+      }
+    end
+
+    # Compare two results for equality
+    def ==(other)
+      return false unless other.is_a?(CommandResult)
+
+      stdout == other.stdout &&
+        stderr == other.stderr &&
+        status == other.status
+    end
+
+    def inspect
+      "#<Backspin::CommandResult status=#{status} stdout=#{stdout.inspect.truncate(50)} stderr=#{stderr.inspect.truncate(50)}>"
+    end
+
+    private
+
+    def normalize_status(status)
+      case status
+      when Integer
+        status
+      when Process::Status
+        status.exitstatus
+      else
+        status.respond_to?(:exitstatus) ? status.exitstatus : status.to_i
+      end
+    end
+  end
+end

data/lib/backspin/record.rb

@@ -4,6 +4,7 @@ module Backspin
   class NoMoreRecordingsError < StandardError; end
 
   class Record
+    FORMAT_VERSION = "2.0"
     attr_reader :path, :commands, :first_recorded_at
 
     def initialize(path)
@@ -22,10 +23,9 @@ module Backspin
 
     def save(filter: nil)
       FileUtils.mkdir_p(File.dirname(@path))
-      # New format: top-level metadata with commands array
       record_data = {
         "first_recorded_at" => @first_recorded_at,
-        "format_version" => "2.0",
+        "format_version" => FORMAT_VERSION,
         "commands" => @commands.map { |cmd| cmd.to_h(filter: filter) }
       }
       File.write(@path, record_data.to_yaml)

data/lib/backspin/record_result.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Backspin
+  # Result object for all Backspin record operations
+  # Provides a consistent interface whether recording, verifying, or playing back
+  class RecordResult
+    attr_reader :output, :record_path, :commands, :mode, :command_diffs
+
+    def initialize(output:, mode:, record_path:, commands:, verified: nil, command_diffs: nil)
+      @output = output
+      @mode = mode
+      @record_path = record_path
+      @commands = commands
+      @verified = verified
+      @command_diffs = command_diffs || []
+    end
+
+    # @return [Boolean] true if this result is from recording
+    def recorded?
+      mode == :record
+    end
+
+    # @return [Boolean, nil] true/false for verification results, nil for recording
+    def verified?
+      @verified
+    end
+
+    # @return [Boolean] true if this result is from playback mode
+    def playback?
+      mode == :playback
+    end
+
+    # @return [String, nil] Human-readable error message if verification failed
+    def error_message
+      return nil unless verified? == false
+      return "No commands to verify" if command_diffs.empty?
+
+      failed_diffs = command_diffs.reject(&:verified?)
+      return "All commands verified" if failed_diffs.empty?
+
+      msg = "Output verification failed for #{failed_diffs.size} command(s):\n\n"
+
+      command_diffs.each_with_index do |diff, idx|
+        next if diff.verified?
+
+        msg += "Command #{idx + 1}: #{diff.summary}\n"
+        msg += diff.diff
+        msg += "\n\n" if idx < command_diffs.size - 1
+      end
+
+      msg
+    end
+
+    # @return [String, nil] Combined diff from all failed commands
+    def diff
+      return nil if command_diffs.empty?
+
+      failed_diffs = command_diffs.reject(&:verified?)
+      return nil if failed_diffs.empty?
+
+      diff_parts = []
+      command_diffs.each_with_index do |cmd_diff, idx|
+        diff_parts << "Command #{idx + 1}:\n#{cmd_diff.diff}" unless cmd_diff.verified?
+      end
+
+      diff_parts.join("\n\n")
+    end
+
+    # Convenience accessors for command output
+    # For single command (common case), these provide direct access
+    # For multiple commands, use all_stdout, all_stderr, etc.
+
+    # @return [String, nil] stdout from the first command
+    def stdout
+      commands.first&.result&.stdout
+    end
+
+    # @return [String, nil] stderr from the first command
+    def stderr
+      commands.first&.result&.stderr
+    end
+
+    # @return [Integer, nil] exit status from the first command
+    def status
+      commands.first&.result&.status
+    end
+
+    # Multiple command accessors
+
+    # @return [Array<String>] stdout from all commands
+    def all_stdout
+      commands.map { |cmd| cmd.result.stdout }
+    end
+
+    # @return [Array<String>] stderr from all commands
+    def all_stderr
+      commands.map { |cmd| cmd.result.stderr }
+    end
+
+    # @return [Array<Integer>] exit status from all commands
+    def all_status
+      commands.map { |cmd| cmd.result.status }
+    end
+
+    # @return [Boolean] true if this result contains multiple commands
+    def multiple_commands?
+      commands.size > 1
+    end
+
+    # @return [Boolean] true if all commands succeeded (exit status 0)
+    def success?
+      if multiple_commands?
+        # Check all commands - if any command has non-zero status, we're not successful
+        commands.all? { |cmd| cmd.result.status.zero? }
+      else
+        status&.zero? || false
+      end
+    end
+
+    # @return [Boolean] true if any command failed (non-zero exit status)
+    def failure?
+      !success?
+    end
+
+    # @return [Hash] Summary of the result for debugging
+    def to_h
+      hash = {
+        mode: mode,
+        recorded: recorded?,
+        playback: playback?,
+        stdout: stdout,
+        stderr: stderr,
+        status: status,
+        record_path: record_path.to_s
+      }
+
+      # Only include verified if it's not nil
+      hash[:verified] = verified? unless verified?.nil?
+
+      # Only include diff if present
+      hash[:diff] = diff if diff
+
+      # Include number of failed commands if in verify mode
+      hash[:failed_commands] = command_diffs.count { |d| !d.verified? } if mode == :verify && command_diffs.any?
+
+      hash
+    end
+
+    def inspect
+      "#<Backspin::RecordResult mode=#{mode} verified=#{verified?.inspect} status=#{status}>"
+    end
+  end
+end