backspin 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a1f998c2134e48ab2c3eee38e86e64ec1a4325ba8d81dca4e7c8e042513dde13
+  data.tar.gz: 43aa6c53243fce4cab5911a6635944f25cb339ee5c58dbeb421f15bd30960a7a
+SHA512:
+  metadata.gz: 15ded2144dfe4db263a8cd54f449aaf591d6f90da25675e77de3a22b7dd0384d8d226f44ed7a7ccfd96e7edb5eae72ecdf95ae6152b38d288153a001b085cb71
+  data.tar.gz: 0bb9f49eb95c197403e8a7d7869cd5b33bb45323c6d9461e07af23df3f24deaa87af5571fd8475759eff5b87d2dc4de94ff3ff898a71e8cc3154e1b1e874122e

data/.gitignore

@@ -0,0 +1,19 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/.claude
+/.cursor
+
+# rspec failure tracking
+.rspec_status
+
+# Backspin cassettes
+/tmp/backspin/
+
+# Bundler
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,7 @@
+# StandardRB configuration for Backspin
+parallel: true
+format: progress
+
+ignore:
+  - 'tmp/**/*'
+  - 'vendor/**/*'

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+
+## [0.2.0] - 2025-06-05
+- First public release of Backspin, extracteed from `name-TBD` CLI tool
+
+## [0.2.1] - 2025-06-04
+- major refactoring, add support for `system` calls
+
+## [0.1.0] - 2025-06-02
+
+### Added
+- Initial (internal) release of Backspin
+- `record` method to capture CLI command outputs
+- `verify` and `verify!` methods for output verification
+- `use_cassette` method for VCR-style record/replay
+- Support for multiple verification modes (strict, playback, custom matcher)
+- Multi-command recording support
+- RSpec integration using RSpec's mocking framework

data/CLAUDE.md

@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Backspin is a Ruby gem for characterization testing of command-line interfaces. It records and replays CLI interactions by capturing stdout, stderr, and exit status from shell commands - similar to how VCR works for HTTP interactions. Backspin uses "records" (YAML files) to store recorded command outputs.
+
+## Development Commands
+
+### Setup
+```bash
+bundle install
+bin/setup
+```
+
+### Testing
+```bash
+bin/rake spec                    # Run all tests
+rspec spec/[file]           # Run specific test file
+rspec spec/[file]:[line]    # Run specific test
+```
+
+### Building and Releasing
+```bash
+bundle exec rake install     # Install gem locally for testing
+bundle exec rake release     # Release to RubyGems (updates version, tags, pushes)
+```
+
+### Code Quality
+```bash
+bin/rake standard               # Run Standard Ruby linter
+```
+
+## Architecture
+
+### Core Components
+
+**Backspin Module** (`lib/backspin.rb`)
+- Main API: `call`, `verify`, `verify!`, `use_record`
+- Credential scrubbing logic
+- Configuration management
+
+**Command Class** (`lib/backspin.rb`)
+- Represents a single CLI execution
+- Stores: args, stdout, stderr, status, recorded_at
+
+**Record Class** (`lib/backspin/record.rb`)
+- Manages YAML record files
+- Handles recording/playback sequencing
+
+**RSpecMetadata** (`lib/backspin/rspec_metadata.rb`)
+- Auto-generates record names from RSpec context
+
+### Key Design Patterns
+
+- Uses RSpec mocking to intercept `Open3.capture3` calls
+- Records are stored as YAML arrays to support multiple commands
+- Automatic credential scrubbing for security (AWS keys, API tokens, passwords)
+- VCR-style recording modes: `:once`, `:all`, `:none`, `:new_episodes`
+
+### Testing Approach
+
+- Integration-focused tests that exercise the full stack
+- Default record directory is `spec/backspin_data` (can be configured)
+- Tests use real shell commands (`echo`, `date`, etc.)
+- Configuration is reset between tests to avoid side effects
+- **Important**: Backspin specs MUST be as local and un-DRY as possible. Each spec should be self-contained with its own setup, expectations, and cleanup if needed. Avoid shared contexts or helpers that hide important test details.
+
+## Common Development Tasks
+
+### Adding New Features
+1. Write integration tests in `spec/backspin/`
+2. Implement in appropriate module (usually `lib/backspin.rb`)
+3. Update README.md if adding public API
+4. Run tests with `rake spec`
+
+### Debugging Tests
+- Records are saved to `spec/backspin_data/` by default
+- Check YAML files to see recorded command outputs
+- Use `VERBOSE=1` for additional output during tests
+
+### Updating Credential Patterns
+- Add patterns to `DEFAULT_CREDENTIAL_PATTERNS` in `lib/backspin.rb`
+- Test with appropriate fixtures in specs

data/Gemfile

@@ -0,0 +1,11 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in backspin.gemspec
+gemspec
+
+group :development do
+  gem "rake", "~> 13.0"
+  gem "rspec", "~> 3.0"
+  gem "timecop", "~> 0.9"
+  gem "standard", "~> 1.0"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Backspin contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,149 @@
+# Backspin
+
+Backspin records and replays CLI interactions in Ruby for easy snapshot testing of command-line interfaces. Currently supports `Open3.capture3` and `system` and requires `rspec-mocks`.  More system calls and flexible test integration are welcome - PRs welcome!
+
+**NOTE:** Backspin is in early development (version 0.2.x), and you can expect the API to change. It is being developed along-side in-production CLI apps, so the API will be refined and improved as we get to 1.0.
+
+Inspired by [VCR](https://github.com/vcr/vcr) and other [golden master](https://en.wikipedia.org/wiki/Golden_master_(software_development)) libraries.
+
+## Overview
+
+Backspin is a Ruby library for snapshot testing (or characterization testing) of command-line interfaces. While VCR records and replays HTTP interactions, Backspin records and replays CLI interactions - capturing stdout, stderr, and exit status from shell commands. 
+
+## Installation
+
+Add this line to your application's Gemfile in the `:test` group:
+
+```ruby
+group :test do
+  gem "backspin"
+end
+```
+
+And then run `bundle install`.
+
+## Usage
+
+### Recording CLI interactions
+
+```ruby
+require "backspin" 
+
+# Record a command's output
+result = Backspin.call("echo_hello") do
+  stdout, stderr, status = Open3.capture3("echo hello")
+  # This will save the output to `spec/backspin_data/echo_hello.yaml`.
+end
+
+```
+
+### Verifying CLI output
+
+```ruby
+# Verify that a command produces the expected output
+result = Backspin.verify("echo_hello") do
+  Open3.capture3("echo hello")
+end
+
+expect(result.verified?).to be true
+```
+
+### Using verify! for automatic test failures
+
+```ruby
+# Automatically fail the test if output doesn't match
+Backspin.verify!("echo_hello") do
+  Open3.capture3("echo hello")
+end
+```
+
+### Playback mode for fast tests
+
+```ruby
+# Return recorded output without running the command
+result = Backspin.verify("slow_command", mode: :playback) do
+  Open3.capture3("slow_command")  # Not executed - will playback from the record yaml (assuming it exists)
+end
+```
+
+### Custom matchers
+
+```ruby
+# Use custom logic to verify output
+Backspin.verify("version_check", 
+                matcher: ->(recorded, actual) {
+                  # Just check that both start with "ruby"
+                  recorded["stdout"].start_with?("ruby") && 
+                  actual["stdout"].start_with?("ruby")
+                }) do
+  Open3.capture3("ruby --version")
+end
+```
+
+### VCR-style use_record
+
+_The plan is to make something like this the main entry point API for ease of use_
+
+```ruby
+# Record on first run, replay on subsequent runs
+Backspin.use_record("my_command", record: :once) do
+  Open3.capture3("echo hello")
+end
+```
+
+### Credential Scrubbing
+
+If the CLI interaction you are recording contains sensitive data in stdout or stderr, you should be careful to make sure it is not recorded to yaml!
+
+By default, Backspin automatically scrubs [common credential patterns](https://github.com/rsanheim/backspin/blob/f8661f084aad0ae759cd971c4af31ccf9bdc6bba/lib/backspin.rb#L46-L65) from records, but this will only handle some common cases.
+Always review your record files before commiting them to source control. 
+
+A tool like [trufflehog](https://github.com/trufflesecurity/trufflehog) or [gitleaks](https://github.com/gitleaks/gitleaks) run via a pre-commit to catch any sensitive data before commit. 
+
+```ruby
+# This will automatically scrub AWS keys, API tokens, passwords, etc.
+Backspin.call("aws_command") do
+  Open3.capture3("aws s3 ls")
+end
+
+# Add custom patterns to scrub
+Backspin.configure do |config|
+  config.add_credential_pattern(/MY_SECRET_[A-Z0-9]+/)
+end
+
+# Disable credential scrubbing - use with caution!
+Backspin.configure do |config|
+  config.scrub_credentials = false
+end
+
+```
+
+Automatic scrubbing includes:
+- AWS access keys, secret keys, and session tokens
+- Google API keys and OAuth client IDs
+- Generic API keys, auth tokens, and passwords
+- Private keys (RSA, etc.)
+
+## Features
+
+- **Simple recording**: Capture stdout, stderr, and exit status
+- **Flexible verification**: Strict matching, playback mode, or custom matchers
+- **Auto-naming**: Automatically generate record names from RSpec examples
+- **Multiple commands**: Record sequences of commands in a single record
+- **RSpec integration**: Works seamlessly with RSpec's mocking framework
+- **Human-readable**: YAML records are easy to read and edit
+- **Credential scrubbing**: Automatically removes sensitive data like API keys and passwords
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rsanheim/backspin.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "standard/rake"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: [:spec, :standard]

data/backspin.gemspec

@@ -0,0 +1,29 @@
+require_relative "lib/backspin/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "backspin"
+  spec.version = Backspin::VERSION
+  spec.authors = ["Rob Sanheim"]
+  spec.email = ["rsanheim@gmail.com"]
+
+  spec.summary = "Record and replay CLI interactions for testing"
+  spec.description = "Backspin is a Ruby library for characterization testing of command-line interfaces. Inspired by VCR's cassette-based approach, it records and replays CLI interactions to make testing faster and more deterministic."
+  spec.homepage = "https://github.com/rsanheim/backspin"
+  spec.license = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.5.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir = "bin"
+  spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rspec-mocks", "~> 3.0"
+  spec.add_dependency "ostruct"
+end

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/backspin/command.rb

@@ -0,0 +1,66 @@
+module Backspin
+  class Command
+    attr_reader :args, :stdout, :stderr, :status, :recorded_at, :method_class
+
+    def initialize(method_class:, args:, stdout: nil, stderr: nil, status: nil, recorded_at: nil)
+      @method_class = method_class
+      @args = args
+      @stdout = stdout
+      @stderr = stderr
+      @status = status
+      @recorded_at = recorded_at
+    end
+
+    # Convert to hash for YAML serialization
+    def to_h(filter: nil)
+      data = {
+        "command_type" => @method_class.name,
+        "args" => @args,
+        "stdout" => Backspin.scrub_text(@stdout),
+        "stderr" => Backspin.scrub_text(@stderr),
+        "status" => @status,
+        "recorded_at" => @recorded_at
+      }
+
+      # Apply filter if provided
+      if filter
+        data = filter.call(data)
+      end
+
+      data
+    end
+
+    # Create from hash (for loading from YAML)
+    def self.from_h(data)
+      # Determine method class from command_type
+      method_class = case data["command_type"]
+      when "Open3::Capture3"
+        Open3::Capture3
+      when "Kernel::System"
+        ::Kernel::System
+      else
+        # Default to capture3 for backwards compatibility
+        Open3::Capture3
+      end
+
+      new(
+        method_class: method_class,
+        args: data["args"],
+        stdout: data["stdout"],
+        stderr: data["stderr"],
+        status: data["status"],
+        recorded_at: data["recorded_at"]
+      )
+    end
+  end
+end
+
+# Define the Open3::Capture3 class for identification
+module Open3
+  class Capture3; end
+end
+
+# Define the Kernel::System class for identification
+module ::Kernel
+  class System; end
+end

data/lib/backspin/record.rb

@@ -0,0 +1,87 @@
+module Backspin
+  class RecordFormatError < StandardError; end
+
+  class NoMoreRecordingsError < StandardError; end
+
+  class Record
+    attr_reader :path, :commands, :first_recorded_at
+
+    def initialize(path)
+      @path = path
+      @commands = []
+      @first_recorded_at = nil
+      @playback_index = 0
+      load_from_file if File.exist?(@path)
+    end
+
+    def add_command(command)
+      @commands << command
+      @first_recorded_at ||= command.recorded_at
+      self
+    end
+
+    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",
+        "commands" => @commands.map { |cmd| cmd.to_h(filter: filter) }
+      }
+      File.write(@path, record_data.to_yaml)
+    end
+
+    def reload
+      @commands = []
+      @playback_index = 0
+      load_from_file if File.exist?(@path)
+      @playback_index = 0  # Reset again after loading to ensure it's at 0
+    end
+
+    def exists?
+      File.exist?(@path)
+    end
+
+    def empty?
+      @commands.empty?
+    end
+
+    def size
+      @commands.size
+    end
+
+    def next_command
+      if @playback_index >= @commands.size
+        raise NoMoreRecordingsError, "No more recordings available for replay"
+      end
+
+      command = @commands[@playback_index]
+      @playback_index += 1
+      command
+    end
+
+    def clear
+      @commands = []
+      @playback_index = 0
+    end
+
+    def self.load_or_create(path)
+      new(path)
+    end
+
+    private
+
+    def load_from_file
+      data = YAML.load_file(@path.to_s)
+
+      unless data.is_a?(Hash) && data["format_version"] == "2.0"
+        raise RecordFormatError, "Invalid record format: expected format version 2.0"
+      end
+
+      @first_recorded_at = data["first_recorded_at"]
+      @commands = data["commands"].map { |command_data| Command.from_h(command_data) }
+    rescue Psych::SyntaxError => e
+      raise RecordFormatError, "Invalid record format: #{e.message}"
+    end
+  end
+end

data/lib/backspin/recorder.rb

@@ -0,0 +1,193 @@
+require "open3"
+require "ostruct"
+require "rspec/mocks"
+
+module Backspin
+  # Handles stubbing and recording of command executions
+  class Recorder
+    include RSpec::Mocks::ExampleMethods
+
+    attr_reader :commands, :verification_data, :mode, :record
+
+    def initialize(mode: :record, record: nil)
+      @mode = mode
+      @record = record
+      @commands = []
+      @verification_data = {}
+    end
+
+    def record_calls(*command_types)
+      command_types = [:capture3, :system] if command_types.empty?
+
+      command_types.each do |command_type|
+        record_call(command_type)
+      end
+    end
+
+    def record_call(command_type)
+      case command_type
+      when :system
+        setup_system_call_stub
+      when :capture3
+        setup_capture3_call_stub
+      else
+        raise ArgumentError, "Unknown command type: #{command_type}"
+      end
+    end
+
+    # Setup stubs for playback mode - just return recorded values
+    def setup_playback_stub(command)
+      if command.method_class == Open3::Capture3
+        actual_status = OpenStruct.new(exitstatus: command.status)
+        allow(Open3).to receive(:capture3).and_return([command.stdout, command.stderr, actual_status])
+      elsif command.method_class == ::Kernel::System
+        # For system, return true if exit status was 0
+        allow_any_instance_of(Object).to receive(:system).and_return(command.status == 0)
+      end
+    end
+
+    # Setup stubs for verification - capture actual output
+    def setup_verification_stub(command)
+      @verification_data = {}
+
+      if command.method_class == Open3::Capture3
+        allow(Open3).to receive(:capture3).and_wrap_original do |original_method, *args|
+          stdout, stderr, status = original_method.call(*args)
+          @verification_data["stdout"] = stdout
+          @verification_data["stderr"] = stderr
+          @verification_data["status"] = status.exitstatus
+          [stdout, stderr, status]
+        end
+      elsif command.method_class == ::Kernel::System
+        allow_any_instance_of(Object).to receive(:system).and_wrap_original do |original_method, receiver, *args|
+          # Execute the real system call
+          result = original_method.call(receiver, *args)
+
+          # For system calls, we only track the exit status
+          @verification_data["stdout"] = ""
+          @verification_data["stderr"] = ""
+          # Derive exit status from result: true = 0, false = non-zero
+          @verification_data["status"] = result ? 0 : 1
+
+          result
+        end
+      end
+    end
+
+    # Setup stubs for replay mode - returns recorded values for multiple commands
+    def setup_replay_stubs
+      raise ArgumentError, "Record required for replay mode" unless @record
+
+      setup_capture3_replay_stub
+      setup_system_replay_stub
+    end
+
+    private
+
+    def setup_capture3_replay_stub
+      allow(Open3).to receive(:capture3) do |*args|
+        command = @record.next_command
+
+        # Make sure this is a capture3 command
+        unless command.method_class == Open3::Capture3
+          raise RecordNotFoundError, "Expected Open3::Capture3 command but got #{command.method_class.name}"
+        end
+
+        recorded_stdout = command.stdout
+        recorded_stderr = command.stderr
+        recorded_status = OpenStruct.new(exitstatus: command.status)
+
+        [recorded_stdout, recorded_stderr, recorded_status]
+      rescue NoMoreRecordingsError => e
+        raise RecordNotFoundError, e.message
+      end
+    end
+
+    def setup_system_replay_stub
+      allow_any_instance_of(Object).to receive(:system) do |receiver, *args|
+        command = @record.next_command
+
+        # Make sure this is a system command
+        unless command.method_class == ::Kernel::System
+          raise RecordNotFoundError, "Expected Kernel::System command but got #{command.method_class.name}"
+        end
+
+        # Return true if exit status was 0, false otherwise
+        command.status == 0
+      rescue NoMoreRecordingsError => e
+        raise RecordNotFoundError, e.message
+      end
+    end
+
+    def setup_capture3_call_stub
+      allow(Open3).to receive(:capture3).and_wrap_original do |original_method, *args|
+        # Execute the real command
+        stdout, stderr, status = original_method.call(*args)
+
+        # Parse command args
+        cmd_args = if args.length == 1 && args.first.is_a?(String)
+          args.first.split(" ")
+        else
+          args
+        end
+
+        # Create command with interaction data
+        command = Command.new(
+          method_class: Open3::Capture3,
+          args: cmd_args,
+          stdout: stdout,
+          stderr: stderr,
+          status: status.exitstatus,
+          recorded_at: Time.now.iso8601
+        )
+        @commands << command
+
+        # Store output for later access (last one wins)
+        Backspin.last_output = stdout
+
+        # Return original result
+        [stdout, stderr, status]
+      end
+    end
+
+    def setup_system_call_stub
+      allow_any_instance_of(Object).to receive(:system).and_wrap_original do |original_method, receiver, *args|
+        # Execute the real system call
+        result = original_method.call(receiver, *args)
+
+        # Parse command args based on how system was called
+        parsed_args = if args.empty? && receiver.is_a?(String)
+          # Single string form - split the command string
+          receiver.split(" ")
+        else
+          # Multi-arg form - already an array
+          args
+        end
+
+        # For system calls, stdout and stderr are not captured
+        # The caller of system() doesn't have access to them
+        stdout = ""
+        stderr = ""
+        # Derive exit status from result: true = 0, false = non-zero, nil = command failed
+        status = result ? 0 : 1
+
+        # Create command with interaction data
+        command = Command.new(
+          method_class: ::Kernel::System,
+          args: parsed_args,
+          stdout: stdout,
+          stderr: stderr,
+          status: status,
+          recorded_at: Time.now.iso8601
+        )
+        @commands << command
+
+        # Store output for later access (for consistency with capture3)
+        Backspin.last_output = stdout
+
+        # Return the original result (true/false/nil)
+        result
+      end
+    end
+  end
+end

data/lib/backspin/version.rb

@@ -0,0 +1,3 @@
+module Backspin
+  VERSION = "0.2.1"
+end

data/lib/backspin.rb

@@ -0,0 +1,431 @@
+require "yaml"
+require "fileutils"
+require "open3"
+require "pathname"
+require "ostruct"
+require "rspec/mocks"
+require "backspin/version"
+require "backspin/command"
+require "backspin/record"
+require "backspin/recorder"
+
+module Backspin
+  class RecordNotFoundError < StandardError; end
+
+  # Include RSpec mocks methods
+  extend RSpec::Mocks::ExampleMethods
+
+  # Configuration for Backspin
+  class Configuration
+    attr_accessor :scrub_credentials
+    # The directory where backspin will store its files - defaults to spec/backspin_data
+    attr_accessor :backspin_dir
+    # Regex patterns to scrub from saved output
+    attr_reader :credential_patterns
+
+    def initialize
+      @scrub_credentials = true
+      @credential_patterns = default_credential_patterns
+      @backspin_dir = Pathname(Dir.pwd).join("spec", "backspin_data")
+    end
+
+    def add_credential_pattern(pattern)
+      @credential_patterns << pattern
+    end
+
+    def clear_credential_patterns
+      @credential_patterns = []
+    end
+
+    def reset_credential_patterns
+      @credential_patterns = default_credential_patterns
+    end
+
+    private
+
+    def default_credential_patterns
+      [
+        # AWS credentials
+        /AKIA[0-9A-Z]{16}/,                                    # AWS Access Key ID
+        /aws_secret_access_key\s*[:=]\s*["']?([A-Za-z0-9\/+=]{40})["']?/i,  # AWS Secret Key
+        /aws_session_token\s*[:=]\s*["']?([A-Za-z0-9\/+=]+)["']?/i,         # AWS Session Token
+
+        # Google Cloud credentials
+        /AIza[0-9A-Za-z\-_]{35}/,                              # Google API Key
+        /[0-9]+-[0-9A-Za-z_]{32}\.apps\.googleusercontent\.com/, # Google OAuth2 client ID
+        /-----BEGIN (RSA )?PRIVATE KEY-----/,                  # Private keys
+
+        # Generic patterns
+        /api[_-]?key\s*[:=]\s*["']?([A-Za-z0-9\-_]{20,})["']?/i,  # Generic API keys
+        /auth[_-]?token\s*[:=]\s*["']?([A-Za-z0-9\-_]{20,})["']?/i, # Auth tokens
+        /password\s*[:=]\s*["']?([^"'\s]{8,})["']?/i,             # Passwords
+        /secret\s*[:=]\s*["']?([A-Za-z0-9\-_]{20,})["']?/i       # Generic secrets
+      ]
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+
+  class Result
+    attr_reader :commands, :record_path
+
+    def initialize(commands:, record_path:)
+      @commands = commands
+      @record_path = record_path
+    end
+  end
+
+  class VerifyResult
+    attr_reader :record_path, :expected_output, :actual_output, :diff, :stderr_diff
+
+    def initialize(verified:, record_path:, expected_output: nil, actual_output: nil,
+      expected_stderr: nil, actual_stderr: nil, expected_status: nil, actual_status: nil,
+      command_executed: true)
+      @verified = verified
+      @record_path = record_path
+      @expected_output = expected_output
+      @actual_output = actual_output
+      @expected_stderr = expected_stderr
+      @actual_stderr = actual_stderr
+      @expected_status = expected_status
+      @actual_status = actual_status
+      @command_executed = command_executed
+
+      if !verified && expected_output && actual_output
+        @diff = generate_diff(expected_output, actual_output)
+      end
+
+      if !verified && expected_stderr && actual_stderr && expected_stderr != actual_stderr
+        @stderr_diff = generate_diff(expected_stderr, actual_stderr)
+      end
+    end
+
+    def verified?
+      @verified
+    end
+
+    def output
+      @actual_output
+    end
+
+    def error_message
+      return nil if verified?
+
+      "Output verification failed\nExpected: #{@expected_output.chomp}\nActual: #{@actual_output.chomp}"
+    end
+
+    def command_executed?
+      @command_executed
+    end
+
+    private
+
+    def generate_diff(expected, actual)
+      expected_lines = expected.lines
+      actual_lines = actual.lines
+      diff = []
+
+      # Simple diff for now
+      expected_lines.each do |line|
+        unless actual_lines.include?(line)
+          diff << "-#{line.chomp}"
+        end
+      end
+
+      actual_lines.each do |line|
+        unless expected_lines.include?(line)
+          diff << "+#{line.chomp}"
+        end
+      end
+
+      diff.join("\n")
+    end
+  end
+
+  class << self
+    attr_accessor :last_output
+
+    def scrub_text(text)
+      return text unless configuration.scrub_credentials && text
+
+      scrubbed = text.dup
+      configuration.credential_patterns.each do |pattern|
+        scrubbed.gsub!(pattern) do |match|
+          # Replace with asterisks of the same length
+          "*" * match.length
+        end
+      end
+      scrubbed
+    end
+
+    def call(record_name, filter: nil)
+      raise ArgumentError, "record_name is required" if record_name.nil? || record_name.empty?
+
+      record_path = build_record_path(record_name)
+
+      # Create recorder to handle stubbing and command recording
+      recorder = Recorder.new
+      recorder.record_calls(:capture3, :system)
+
+      yield
+
+      # Save commands using new format
+      FileUtils.mkdir_p(File.dirname(record_path))
+      # Don't load existing data when creating new record
+      record = Record.new(record_path)
+      record.clear  # Clear any loaded data
+      recorder.commands.each { |cmd| record.add_command(cmd) }
+      record.save(filter: filter)
+
+      Result.new(commands: recorder.commands, record_path: Pathname.new(record_path))
+    end
+
+    def output
+      last_output
+    end
+
+    def use_record(record_name, options = {}, &block)
+      raise ArgumentError, "record_name is required" if record_name.nil? || record_name.empty?
+
+      record_path = build_record_path(record_name)
+      record_mode = options[:record] || :once
+      filter = options[:filter]
+
+      case record_mode
+      when :none
+        # Never record, only replay
+        unless File.exist?(record_path)
+          raise RecordNotFoundError, "Record not found: #{record_path}"
+        end
+        replay_record(record_path, &block)
+      when :all
+        # Always record
+        record_and_save_record(record_path, filter: filter, &block)
+      when :once
+        # Record if doesn't exist, replay if exists
+        if File.exist?(record_path)
+          replay_record(record_path, &block)
+        else
+          record_and_save_record(record_path, filter: filter, &block)
+        end
+      when :new_episodes
+        # Record new commands not in record
+        # For now, simplified: just append new recordings
+        record_new_episode(record_path, filter: filter, &block)
+      else
+        raise ArgumentError, "Unknown record mode: #{record_mode}"
+      end
+    end
+
+    def verify(record_name, mode: :strict, matcher: nil, &block)
+      record_path = build_record_path(record_name)
+
+      record = Record.load_or_create(record_path)
+      unless record.exists?
+        raise RecordNotFoundError, "Record not found: #{record_path}"
+      end
+
+      if record.empty?
+        raise RecordNotFoundError, "No commands found in record"
+      end
+
+      # For verify, we only handle single command verification for now
+      # Use the first command
+      command = record.commands.first
+
+      # Create recorder for verification
+      recorder = Recorder.new
+
+      if mode == :playback
+        # Playback mode: return recorded output without running command
+        recorder.setup_playback_stub(command)
+
+        yield
+
+        # In playback mode, always verified
+        VerifyResult.new(
+          verified: true,
+          record_path: Pathname.new(record_path),
+          expected_output: command.stdout,
+          actual_output: command.stdout,
+          expected_stderr: command.stderr,
+          actual_stderr: command.stderr,
+          expected_status: command.status,
+          actual_status: command.status,
+          command_executed: false
+        )
+      elsif matcher
+        # Custom matcher verification
+        recorder.setup_verification_stub(command)
+
+        yield
+
+        # Call custom matcher - convert command back to hash format for matcher
+        recorded_data = command.to_h
+        verified = matcher.call(recorded_data, recorder.verification_data)
+
+        VerifyResult.new(
+          verified: verified,
+          record_path: Pathname.new(record_path),
+          expected_output: command.stdout,
+          actual_output: recorder.verification_data["stdout"],
+          expected_stderr: command.stderr,
+          actual_stderr: recorder.verification_data["stderr"],
+          expected_status: command.status,
+          actual_status: recorder.verification_data["status"]
+        )
+      else
+        # Default strict mode
+        recorder.setup_verification_stub(command)
+
+        yield
+
+        # Compare outputs
+        actual_stdout = recorder.verification_data["stdout"]
+        actual_stderr = recorder.verification_data["stderr"]
+        actual_status = recorder.verification_data["status"]
+
+        verified =
+          command.stdout == actual_stdout &&
+          command.stderr == actual_stderr &&
+          command.status == actual_status
+
+        VerifyResult.new(
+          verified: verified,
+          record_path: Pathname.new(record_path),
+          expected_output: command.stdout,
+          actual_output: actual_stdout,
+          expected_stderr: command.stderr,
+          actual_stderr: actual_stderr,
+          expected_status: command.status,
+          actual_status: actual_status
+        )
+      end
+    end
+
+    def verify!(record_name, mode: :strict, matcher: nil, &block)
+      result = verify(record_name, mode: mode, matcher: matcher, &block)
+
+      unless result.verified?
+        error_message = "Backspin verification failed!\n"
+        error_message += "Record: #{result.record_path}\n"
+        error_message += "Expected output:\n#{result.expected_output}\n"
+        error_message += "Actual output:\n#{result.actual_output}\n"
+
+        if result.diff && !result.diff.empty?
+          error_message += "Diff:\n#{result.diff}\n"
+        end
+
+        if result.stderr_diff && !result.stderr_diff.empty?
+          error_message += "Stderr diff:\n#{result.stderr_diff}\n"
+        end
+
+        # Raise RSpec's expectation failure for proper integration
+        raise RSpec::Expectations::ExpectationNotMetError, error_message
+      end
+
+      result
+    end
+
+    private
+
+    def replay_record(record_path, &block)
+      record = Record.load_or_create(record_path)
+      unless record.exists?
+        raise RecordNotFoundError, "Record not found: #{record_path}"
+      end
+
+      if record.empty?
+        raise RecordNotFoundError, "No commands found in record"
+      end
+
+      # Create recorder in replay mode
+      recorder = Recorder.new(mode: :replay, record: record)
+      recorder.setup_replay_stubs
+
+      block_return_value = yield
+
+      # Return stdout, stderr, status if the block returned capture3 results
+      # Otherwise return the block's return value
+      if block_return_value.is_a?(Array) && block_return_value.size == 3 &&
+          block_return_value[0].is_a?(String) && block_return_value[1].is_a?(String)
+        # Convert status to integer for consistency
+        stdout, stderr, status = block_return_value
+        status_int = status.respond_to?(:exitstatus) ? status.exitstatus : status
+        [stdout, stderr, status_int]
+      else
+        block_return_value
+      end
+    end
+
+    def record_and_save_record(record_path, filter: nil, &block)
+      # Create recorder to handle stubbing and command recording
+      recorder = Recorder.new
+      recorder.record_calls(:capture3, :system)
+
+      block_return_value = yield
+
+      # Save commands using new format
+      FileUtils.mkdir_p(File.dirname(record_path))
+      # Don't load existing data when creating new record
+      record = Record.new(record_path)
+      record.clear  # Clear any loaded data
+      recorder.commands.each { |cmd| record.add_command(cmd) }
+      record.save(filter: filter)
+
+      # Return appropriate value
+      if block_return_value.is_a?(Array) && block_return_value.size == 3
+        # Return stdout, stderr, status as integers
+        stdout, stderr, status = block_return_value
+        [stdout, stderr, status.respond_to?(:exitstatus) ? status.exitstatus : status]
+      else
+        block_return_value
+      end
+    end
+
+    def record_new_episode(record_path, filter: nil, &block)
+      # For new_episodes mode, we'd need to track which commands have been seen
+      # For now, simplified implementation that just appends
+      record = Record.load_or_create(record_path)
+
+      # Create recorder to handle stubbing and command recording
+      recorder = Recorder.new
+      recorder.record_calls(:capture3, :system)
+
+      result = yield
+
+      # Save all recordings (existing + new)
+      if recorder.commands.any?
+        recorder.commands.each { |cmd| record.add_command(cmd) }
+        record.save(filter: filter)
+      end
+
+      # Return appropriate value
+      if result.is_a?(Array) && result.size == 3
+        stdout, stderr, status = result
+        [stdout, stderr, status.respond_to?(:exitstatus) ? status.exitstatus : status]
+      else
+        result
+      end
+    end
+
+    def build_record_path(name)
+      backspin_dir = configuration.backspin_dir
+      backspin_dir.mkpath
+
+      File.join(backspin_dir, "#{name}.yaml")
+    end
+  end
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: backspin
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+platform: ruby
+authors:
+- Rob Sanheim
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec-mocks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Backspin is a Ruby library for characterization testing of command-line
+  interfaces. Inspired by VCR's cassette-based approach, it records and replays CLI
+  interactions to make testing faster and more deterministic.
+email:
+- rsanheim@gmail.com
+executables:
+- setup
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".standard.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- backspin.gemspec
+- bin/setup
+- lib/backspin.rb
+- lib/backspin/command.rb
+- lib/backspin/record.rb
+- lib/backspin/recorder.rb
+- lib/backspin/version.rb
+homepage: https://github.com/rsanheim/backspin
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rsanheim/backspin
+  source_code_uri: https://github.com/rsanheim/backspin
+  changelog_uri: https://github.com/rsanheim/backspin/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Record and replay CLI interactions for testing
+test_files: []