backspin 0.2.1 → 0.4.0

checksums.yaml

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

data/.circleci/config.yml

@@ -0,0 +1,31 @@
+# See: https://circleci.com/docs/configuration-reference
+version: 2.1
+
+orbs:
+  # See: https://circleci.com/developer/orbs/orb/circleci/ruby
+  ruby: circleci/ruby@2.5.3
+
+jobs:
+  build:
+    resource_class: medium
+    parameters:
+      ruby-version:
+        type: string
+    docker:
+      - image: cimg/ruby:<< parameters.ruby-version >>
+
+    steps:
+      - checkout
+      - ruby/install-deps:
+          key: gems-v1-ruby<< parameters.ruby-version >>
+      - run:
+          name: Run specs and lint
+          command: bundle exec rake
+
+workflows:
+  build:
+    jobs:
+      - build:
+          matrix:
+            parameters:
+              ruby-version: ["3.2", "3.3", "3.4"]

data/.gitignore

@@ -2,18 +2,15 @@
 /.yardoc
 /_yardoc/
 /coverage/
-/doc/
 /pkg/
 /spec/reports/
 /tmp/
 /.claude
 /.cursor
 
+/backspin*.gem
 # rspec failure tracking
 .rspec_status
 
 # Backspin cassettes
 /tmp/backspin/
-
-# Bundler
-Gemfile.lock

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.4.0] - 2025-06-06
+
+Simpler, unified API: `Backspin.run` and `Backspin run!` methods that automatically record on first use and verify on subsequent runs. `run!` will raise an error if results differ, whereas `run` will return the result for the caller to decide what to do with
+
+## [0.3.0] - 2025-06-05
+- Scrub credentials from command arguments
 
 ## [0.2.0] - 2025-06-05
 - First public release of Backspin, extracteed from `name-TBD` CLI tool

data/CLAUDE.md

@@ -17,14 +17,14 @@ bin/setup
 ### Testing
 ```bash
 bin/rake spec                    # Run all tests
-rspec spec/[file]           # Run specific test file
-rspec spec/[file]:[line]    # Run specific test
+bin/rspec spec/[file]           # Run specific test file
+bin/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)
+bin/rake install     # Install gem locally for testing
+bin/rake release     # Release to RubyGems (updates version, tags, pushes)
 ```
 
 ### Code Quality
@@ -78,7 +78,6 @@ bin/rake standard               # Run Standard Ruby linter
 ### 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`

data/CONTRIBUTING.md

@@ -0,0 +1,222 @@
+# Contributing to Backspin
+
+Thank you for your interest in contributing to Backspin! This guide will help you get started with development and walk you through the contribution process.
+
+Note that Backspin is in early development and the API _will_ change before stabilizing at 1.0.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Making Changes](#making-changes)
+- [Testing](#testing)
+- [Submitting Changes](#submitting-changes)
+- [Code Style](#code-style)
+- [Reporting Issues](#reporting-issues)
+- [Feature Requests](#feature-requests)
+
+## Getting Started
+
+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.
+
+### Prerequisites
+
+- Ruby 3.2, 3.3, or 3.4
+- Bundler
+- Git
+
+## Development Setup
+
+1. Fork and clone the repository:
+   ```bash
+   git clone https://github.com/rsanheim/backspin.git
+   cd backspin
+   ```
+
+2. Run the setup script:
+   ```bash
+   bin/setup
+   ```
+
+3. Run the full build (specs & standardrb linting) to ensure everything is working:
+   ```bash
+   bin/rake spec
+   ```
+
+## Making Changes
+
+### Development Workflow
+
+1. Create a feature branch:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes following the project conventions
+
+3. Run tests frequently:
+   ```bash
+   bin/rake spec
+   ```
+
+4. Run the linter:
+   ```bash
+   bin/rake standard
+   ```
+
+5. Commit your changes with clear, descriptive messages
+
+### Architecture Overview
+
+**Core Components:**
+
+- **Backspin Module** (`lib/backspin.rb`)
+  - Main API: `call`, `verify`, `verify!`, `use_record`
+  - Credential scrubbing logic
+  - Configuration management
+
+- **Command Class** (`lib/backspin/command.rb`)
+  - Represents a single CLI execution
+  - Stores: args, stdout, stderr, status, recorded_at, etc
+
+- **Record Class** (`lib/backspin/record.rb`)
+  - Manages YAML record files
+  - Handles recording/playback sequencing
+
+### 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 the the full build
+
+#### Updating Credential Patterns
+
+- Add patterns to `DEFAULT_CREDENTIAL_PATTERNS` in `lib/backspin.rb`
+- Test with appropriate fixtures in specs
+
+#### Debugging Tests
+
+- Records are saved to `spec/backspin_data/` by default
+- Check YAML files to see recorded command outputs
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+bin/rake spec
+
+# Run specific test file
+bundle exec rspec spec/backspin/record_spec.rb
+
+# Run specific test
+bundle exec rspec spec/backspin/record_spec.rb:42
+```
+
+### Writing Tests
+
+Backspin uses integration-focused tests that exercise the full stack. When writing tests:
+
+- Keep specs self-contained with their own setup, expectations, and cleanup
+- Avoid shared contexts or helpers that hide important test details
+- Use real shell commands (`echo`, `date`, etc.) for testing
+- Ensure configuration is reset between tests to avoid side effects
+- Verify new or updated test records in `spec/backspin_data/`
+
+Example test structure:
+
+```ruby
+RSpec.describe "Feature name" do
+  it "does something specific" do
+    # Setup
+    record_name = "my_test_record"
+    
+    # Exercise
+    result = Backspin.call(record_name) do
+      Open3.capture3("echo", "hello")
+    end
+    
+    # Verify
+    expect(result.stdout).to eq("hello\n")
+  end
+end
+```
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. Ensure all tests pass
+2. Update documentation if needed
+3. Add entries to CHANGELOG.md following the existing format
+4. Push your branch and create a pull request
+5. Provide a clear description of your changes
+6. Link any related issues
+
+### Pull Request Guidelines
+
+- Keep changes focused and atomic
+- Include tests for new functionality
+- Update examples in README.md if changing public APIs
+- Ensure CI passes (tests against Ruby 3.2, 3.3, and 3.4)
+
+## Code Style
+
+Backspin uses [Standard Ruby](https://github.com/standardrb/standard) for code formatting. Run the linter before committing:
+
+```bash
+bin/rake standard
+```
+
+To automatically fix issues:
+
+```bash
+bin/rake standard:fix
+```
+
+## Reporting Issues
+
+### Bug Reports
+
+When reporting bugs, please include *full logs* including:
+
+1. Ruby version (`ruby -v`) and ruby version manager info
+2. Backspin version
+3. Minimal reproduction code
+4. Expected behavior vs actual behavior
+5. Full error messages and stack traces
+6. Relevant YAML record files (sanitized of sensitive data)
+
+### Security Issues
+
+For security vulnerabilities, please email the maintainers directly rather than opening a public issue.
+
+## Feature Requests
+
+We welcome feature requests! When proposing new features:
+
+1. Check existing issues to avoid duplicates
+2. Describe the use case and motivation
+3. Provide code examples of how the feature would work
+4. Be open to discussion and alternative approaches
+
+## Additional Resources
+
+- [Project README](README.md)
+- [CLAUDE.md](CLAUDE.md) - AI assistant guidance
+- [RSpec Documentation](https://rspec.info/)
+- [Standardrb linting](https://github.com/standardrb/standard)
+
+## Questions?
+
+If you have questions about contributing, feel free to:
+
+- Open an issue for discussion
+- Check existing issues and pull requests
+- Review the test suite for examples
+
+Thank you for contributing to Backspin!

data/Gemfile

@@ -7,5 +7,5 @@ group :development do
   gem "rake", "~> 13.0"
   gem "rspec", "~> 3.0"
   gem "timecop", "~> 0.9"
-  gem "standard", "~> 1.0"
+  gem "standard"
 end

data/Gemfile.lock

@@ -0,0 +1,87 @@
+PATH
+  remote: .
+  specs:
+    backspin (0.4.0)
+      ostruct (~> 0.5.0)
+      rspec-mocks (~> 3.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    diff-lcs (1.6.2)
+    json (2.12.2)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    ostruct (0.5.5)
+    parallel (1.27.0)
+    parser (3.3.8.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.4.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.0)
+    regexp_parser (2.10.0)
+    rspec (3.13.1)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.4)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.4)
+    rubocop (1.75.8)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.44.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-performance (1.25.0)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+    ruby-progressbar (1.13.0)
+    standard (1.50.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.75.5)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.8.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.25.0)
+    timecop (0.9.10)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+
+PLATFORMS
+  arm64-darwin-24
+  ruby
+
+DEPENDENCIES
+  backspin!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  standard
+  timecop (~> 0.9)
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -1,8 +1,8 @@
-# Backspin
+# Backspin   [![Gem Version](https://badge.fury.io/rb/backspin.svg)](https://badge.fury.io/rb/backspin) [![CircleCI](https://dl.circleci.com/status-badge/img/gh/rsanheim/backspin/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/rsanheim/backspin/tree/main)
 
-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!
+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 test integrations are welcome - send a PR!
 
-**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.
+**NOTE:** Backspin should be considered alpha quality software while pre v1.0. It is in heavy development, and you can expect the API to change. It is being developed in conjunction with 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.
 
@@ -24,73 +24,147 @@ And then run `bundle install`.
 
 ## Usage
 
-### Recording CLI interactions
+### Quick Start
+
+The simplest way to use Backspin is with the `run` method, which automatically records on the first execution and verifies on subsequent runs:
 
 ```ruby
-require "backspin" 
+require "backspin"
+
+# First run: records the output
+result = Backspin.run("my_command") do
+  Open3.capture3("echo hello world")
+end
 
-# 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`.
+# Subsequent runs: verifies the output matches
+result = Backspin.run("my_command") do
+  Open3.capture3("echo hello world")
 end
 
+# Use run! to automatically fail tests on mismatch
+Backspin.run!("my_command") do
+  Open3.capture3("echo hello mars")
+end
+# Raises an error because stdout will not match the recorded output
 ```
 
-### Verifying CLI output
+### Recording Modes
+
+Backspin supports different modes for controlling how commands are recorded and verified:
 
 ```ruby
-# Verify that a command produces the expected output
-result = Backspin.verify("echo_hello") do
+# Auto mode (default): Record on first run, verify on subsequent runs
+result = Backspin.run("my_command") do
+  Open3.capture3("echo hello")
+end
+
+# Explicit record mode: Always record, overwriting existing recordings
+result = Backspin.run("echo_test", mode: :record) do
   Open3.capture3("echo hello")
 end
+# This will save the output to `spec/backspin_data/echo_test.yml`.
 
+# Explicit verify mode: Always verify against existing recording
+result = Backspin.run("echo_test", mode: :verify) do
+  Open3.capture3("echo hello")
+end
 expect(result.verified?).to be true
+
+# Playback mode: Return recorded output without running the command
+result = Backspin.run("slow_command", mode: :playback) do
+  Open3.capture3("slow_command")  # Not executed - returns recorded output
+end
 ```
 
-### Using verify! for automatic test failures
+### Using run! for automatic test failures
+
+The `run!` method works exactly like `run` but automatically fails the test if verification fails:
 
 ```ruby
 # Automatically fail the test if output doesn't match
-Backspin.verify!("echo_hello") do
+Backspin.run!("echo_test") do
   Open3.capture3("echo hello")
 end
+# Raises an error with detailed diff if verification fails from recorded data in "echo_test.yml"
 ```
 
-### Playback mode for fast tests
+### Custom matchers
+
+For cases where exact matching isn't suitable, you can provide custom verification logic:
 
 ```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)
+# Use custom logic to verify output
+result = Backspin.run("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
 ```
 
-### Custom matchers
+### Working with the Result Object
+
+The API returns a `RecordResult` object with helpful methods:
 
 ```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")
+result = Backspin.run("my_test") do
+  Open3.capture3("echo out; echo err >&2; exit 42")
 end
+
+# Check the mode
+result.recorded?  # true on first run
+result.verified?  # true/false on subsequent runs, nil when recording
+result.playback?  # true in playback mode
+
+# Access output (first command for single commands)
+result.stdout     # "out\n"
+result.stderr     # "err\n" 
+result.status     # 42
+result.success?   # false (non-zero exit)
+result.output     # The raw return value from the block
+
+# Debug information
+result.record_path  # Path to the YAML file
+result.error_message  # Human-readable error if verification failed
+result.diff  # Diff between expected and actual output
 ```
 
-### VCR-style use_record
+### Multiple Commands
 
-_The plan is to make something like this the main entry point API for ease of use_
+Backspin automatically records and verifies all commands executed in a block:
 
 ```ruby
-# Record on first run, replay on subsequent runs
-Backspin.use_record("my_command", record: :once) do
-  Open3.capture3("echo hello")
+result = Backspin.run("multi_command_test") do
+  # All of these commands will be recorded
+  version, = Open3.capture3("ruby --version")
+  files, = Open3.capture3("ls -la")
+  system("echo 'Processing...'")  # Note: system doesn't capture output
+  data, stderr, = Open3.capture3("curl https://api.example.com/data")
+  
+  # Return whatever you need
+  { version: version.strip, file_count: files.lines.count, data: data }
 end
+
+# Access individual command results
+result.commands.size       # 4
+result.multiple_commands?  # true
+
+# For multiple commands, use these accessors
+result.all_stdout  # Array of stdout from each command
+result.all_stderr  # Array of stderr from each command
+result.all_status  # Array of exit statuses
+
+# Or access specific commands
+result.commands[0].stdout  # Ruby version output
+result.commands[1].stdout  # ls output
+result.commands[2].status  # system call exit status (stdout is empty)
+result.commands[3].stderr  # curl errors if any
 ```
 
+When verifying multiple commands, Backspin ensures all commands match in the exact order they were recorded. If any command differs, you'll get a detailed error showing which commands failed.
+
 ### 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!
@@ -102,7 +176,7 @@ A tool like [trufflehog](https://github.com/trufflesecurity/trufflehog) or [gitl
 
 ```ruby
 # This will automatically scrub AWS keys, API tokens, passwords, etc.
-Backspin.call("aws_command") do
+Backspin.run("aws_command") do
   Open3.capture3("aws s3 ls")
 end
 
@@ -146,4 +220,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/rsanhe
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/backspin.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   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.required_ruby_version = Gem::Requirement.new(">= 3.1.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
@@ -20,10 +20,10 @@ Gem::Specification.new do |spec|
   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.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
   spec.add_dependency "rspec-mocks", "~> 3.0"
-  spec.add_dependency "ostruct"
+  spec.add_dependency "ostruct", "~> 0.5.0"
 end

data/bin/rake

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")