backspin 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 803ecdad9628acd396e0d70b1e9e4081c612562f6872af8fa05108a820c61590
-  data.tar.gz: 563d3b7e8c413742453971859cf4bb31aeff11dbeee38d5804922ffa150615bb
+  metadata.gz: 3937af0a8fc0d808e6cc2f8788481ee479a46b6c21353a7c73820711995f9b96
+  data.tar.gz: a30e4ebd5608ad6718fc0d5cbda3685adc49b97cbb5af188db604f3b1b0de3be
 SHA512:
-  metadata.gz: 17aff3cf0ab930e13da63fa427135cde5e41816341d75ca7712662d4feefb4df1d753db983668a57562c9922d2dda4ae5f54d8cc579ce720d0ac9009015740ff
-  data.tar.gz: 203e8c9f1158712ae20e64864a20645cf5fad7e3bd79627bf6dfc7d7efa40cd51d5cbd2e5ac037ebe9a9f8c0408c33921f948400435aa023db32da9df9dfa8fc
+  metadata.gz: 1343b731c00281871a50f4d61e276068d4aa18d54ba60f80f7ad780f88191c06f6af5168d53c7559f82c9d722e67521b8ca56aeb7998a2f61f410b925caff1aa
+  data.tar.gz: a3e496f886dae99cc6f624399655955b18b131991f332b2470ecd57ed74fb7e4c8e58a8cf89237f2faa9e10456ab67566ebc18da3c6fdc253716a8abb4728061

data/.circleci/config.yml

@@ -6,26 +6,38 @@ orbs:
   ruby: circleci/ruby@2.5.3
 
 jobs:
-  build:
+  test:
     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
+          name: Run specs
+          command: bundle exec rake spec
+
+  lint:
+    resource_class: medium
+    docker:
+      - image: cimg/ruby:4.0
+    steps:
+      - checkout
+      - ruby/install-deps:
+          key: gems-v1-ruby4.0
+      - run:
+          name: Run Standard Ruby linter
+          command: bundle exec rake standard
 
 workflows:
   build:
     jobs:
-      - build:
+      - test:
           matrix:
             parameters:
-              ruby-version: ["3.2", "3.3", "3.4"]
+              ruby-version: ["3.2", "3.3", "3.4", "4.0"]
+      - lint

data/.ruby-version

@@ -0,0 +1 @@
+4.0.0

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.8.0 - 2026-02-05
+* Breaking: new `Backspin.run("command", name:, env:)` command API plus block capture via `Backspin.run(name:) { ... }` and `Backspin.capture("name") { ... }`
+* Breaking: remove `run!` and `:playback`
+* Breaking: drop RSpec dependency; verification failures raise `Backspin::VerificationError`
+* Breaking: record format bumped to 3.0 and only `Open3::Capture3` / `Backspin::Capturer` records are accepted
+* Scrub credential patterns apply to stdout, stderr, args, and env values
+
 ## 0.7.1 - 2025-12-02
 * Include result object on VerificationError to make it easier for callers to debug verification errors
 
@@ -36,4 +43,4 @@ Simpler, unified API: `Backspin.run` and `Backspin run!` methods that automatica
 - `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
+- RSpec integration using RSpec's mocking framework

data/CLAUDE.md

@@ -41,13 +41,11 @@ bin/rake standard                # Alternative: Run via Rake task
 ### Core Components
 
 **Backspin Module** (`lib/backspin.rb`)
-- Main API: `run`, `run!` (both raise on verification failure by default)
-- Capture API: `capture` (raises `VerificationError` on verification failure by default)
-- Legacy API: `call`, `verify`, `verify!`, `use_record`
+- Main API: `run` (direct command execution and block capture), `capture` (alias for block form)
 - Credential scrubbing logic
-- Configuration management (including `raise_on_verification_failure` which defaults to `true` and affects both `run` and `capture`)
+- Configuration management (including `raise_on_verification_failure` which defaults to `true`)
 
-**Command Class** (`lib/backspin.rb`)
+**Command Class** (`lib/backspin/command.rb`)
 - Represents a single CLI execution
 - Stores: args, stdout, stderr, status, recorded_at
 
@@ -60,10 +58,11 @@ bin/rake standard                # Alternative: Run via Rake task
 
 ### 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`
+- Direct `Open3.capture3` execution for command runs
+- Tempfile-based FD capture for block forms
+- Single-command records stored as YAML
+- Automatic credential scrubbing for security (AWS keys, API tokens, passwords, env values)
+- Recording modes: `:auto`, `:record`, `:verify`
 
 ### Testing Approach
 

data/CONTRIBUTING.md

@@ -21,7 +21,7 @@ Backspin is a Ruby gem for characterization testing of command-line interfaces.
 
 ### Prerequisites
 
-- Ruby 3.2, 3.3, or 3.4
+- Ruby 3.2, 3.3, 3.4, or 4.0
 - Bundler
 - Git
 
@@ -71,7 +71,7 @@ Backspin is a Ruby gem for characterization testing of command-line interfaces.
 **Core Components:**
 
 - **Backspin Module** (`lib/backspin.rb`)
-  - Main API: `call`, `verify`, `verify!`, `use_record`
+  - Main API: `run` (direct command execution and block capture), `capture` (alias for block form)
   - Credential scrubbing logic
   - Configuration management
 
@@ -132,15 +132,8 @@ 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
+    result = Backspin.run(["echo", "hello"], name: "my_test_record")
+
     expect(result.stdout).to eq("hello\n")
   end
 end
@@ -162,7 +155,7 @@ end
 - 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)
+- Ensure CI passes (tests against Ruby 3.2, 3.3, 3.4, and 4.0)
 
 ## Code Style
 

data/Gemfile.lock

@@ -1,9 +1,7 @@
 PATH
   remote: .
   specs:
-    backspin (0.7.1)
-      ostruct
-      rspec-mocks (~> 3)
+    backspin (0.8.0)
 
 GEM
   remote: https://rubygems.org/
@@ -13,7 +11,6 @@ GEM
     json (2.16.0)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
-    ostruct (0.6.1)
     parallel (1.27.0)
     parser (3.3.10.0)
       ast (~> 2.4.1)
@@ -70,7 +67,7 @@ GEM
     timecop (0.9.10)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
-    unicode-emoji (4.1.0)
+    unicode-emoji (4.2.0)
 
 PLATFORMS
   arm64-darwin-24
@@ -84,4 +81,4 @@ DEPENDENCIES
   timecop (~> 0.9)
 
 BUNDLED WITH
-  4.0.0.beta2
+  4.0.5

data/MATCHERS.md

@@ -13,14 +13,11 @@ Backspin supports custom matchers for flexible verification of command outputs.
 A proc matcher receives full command hashes and can check any combination of fields:
 
 ```ruby
-# Check that output starts with expected prefix
-result = Backspin.run("version_test",
+result = Backspin.run(["node", "--version"], name: "version_test",
   matcher: ->(recorded, actual) {
-    recorded["stdout"].start_with?("v") && 
+    recorded["stdout"].start_with?("v") &&
     actual["stdout"].start_with?("v")
-  }) do
-  Open3.capture3("node --version")
-end
+  })
 ```
 
 ### 2. Field-Specific Hash Matchers
@@ -29,33 +26,13 @@ Use a hash to specify matchers for individual fields. Only specified fields are
 
 ```ruby
 # Only check stdout - stderr and status are ignored
-result = Backspin.run("timestamp_test",
+result = Backspin.run(["date"], name: "timestamp_test",
   matcher: {
     stdout: ->(recorded, actual) {
-      # Both should contain a timestamp
       recorded.match?(/\d{4}-\d{2}-\d{2}/) &&
       actual.match?(/\d{4}-\d{2}-\d{2}/)
     }
-  }) do
-  Open3.capture3("date")
-end
-
-# Check multiple specific fields
-result = Backspin.run("api_test",
-  matcher: {
-    stdout: ->(recorded, actual) {
-      # Check JSON structure exists
-      recorded.include?("\"data\":") &&
-      actual.include?("\"data\":")
-    },
-    status: ->(recorded, actual) {
-      # Both should succeed
-      recorded == 0 && actual == 0
-    }
-    # Note: stderr is NOT checked
-  }) do
-  Open3.capture3("curl", "-s", "https://api.example.com")
-end
+  })
 ```
 
 ### 3. The :all Matcher
@@ -63,17 +40,13 @@ end
 The `:all` matcher receives complete command hashes with all fields:
 
 ```ruby
-# Cross-field validation
-result = Backspin.run("build_test",
+result = Backspin.run(["./build.sh"], name: "build_test",
   matcher: {
     all: ->(recorded, actual) {
-      # Check overall success: stdout has "BUILD SUCCESSFUL" AND status is 0
       actual["stdout"].include?("BUILD SUCCESSFUL") &&
       actual["status"] == 0
     }
-  }) do
-  Open3.capture3("./build.sh")
-end
+  })
 ```
 
 ### 4. Combining :all with Field Matchers
@@ -81,23 +54,12 @@ end
 When both `:all` and field matchers are present, all must pass:
 
 ```ruby
-result = Backspin.run("complex_test",
+result = Backspin.run(["./process_data.sh"], name: "complex_test",
   matcher: {
-    all: ->(recorded, actual) {
-      # Overall check: command succeeded
-      actual["status"] == 0
-    },
-    stdout: ->(recorded, actual) {
-      # Specific check: output contains result
-      actual.include?("Result:")
-    },
-    stderr: ->(recorded, actual) {
-      # No errors expected
-      actual.empty?
-    }
-  }) do
-  Open3.capture3("./process_data.sh")
-end
+    all: ->(recorded, actual) { actual["status"] == 0 },
+    stdout: ->(recorded, actual) { actual.include?("Result:") },
+    stderr: ->(recorded, actual) { actual.empty? }
+  })
 ```
 
 ## Matcher Proc Arguments
@@ -108,10 +70,11 @@ Field-specific matchers receive field values:
 
 The `:all` matcher receives full hashes with these keys:
 - `"stdout"` - String output
-- `"stderr"` - String error output  
-- `"status"` - Integer exit code
-- `"command_type"` - String like "Open3::Capture3"
-- `"args"` - Array of command arguments
+- `"stderr"` - String error output
+- `"status"` - Integer exit code (placeholder `0` for block capture)
+- `"command_type"` - String like "Open3::Capture3" or "Backspin::Capturer"
+- `"args"` - String or Array of command arguments
+- `"env"` - Optional Hash of env vars (command runs only)
 - `"recorded_at"` - Timestamp string
 
 ## Examples
@@ -119,116 +82,45 @@ The `:all` matcher receives full hashes with these keys:
 ### Matching Version Numbers
 
 ```ruby
-# Match major version only
-matcher: {
+matcher = {
   stdout: ->(recorded, actual) {
-    recorded_major = recorded[/(\d+)\./, 1]
-    actual_major = actual[/(\d+)\./, 1]
+    recorded_major = recorded[/\d+/, 0]
+    actual_major = actual[/\d+/, 0]
     recorded_major == actual_major
   }
 }
+
+Backspin.run(["ruby", "--version"], name: "ruby_version", matcher: matcher)
 ```
 
 ### Ignoring Timestamps
 
 ```ruby
-# Strip timestamps before comparing
-matcher: {
+matcher = {
   stdout: ->(recorded, actual) {
     pattern = /\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/
-    recorded.gsub(pattern, '[TIME]') == actual.gsub(pattern, '[TIME]')
+    recorded.gsub(pattern, "[TIME]") == actual.gsub(pattern, "[TIME]")
   }
 }
-```
 
-### JSON Response Validation
-
-```ruby
-# Validate JSON structure, ignore values
-matcher: {
-  stdout: ->(recorded, actual) {
-    begin
-      recorded_data = JSON.parse(recorded)
-      actual_data = JSON.parse(actual)
-      
-      # Same keys at top level
-      recorded_data.keys.sort == actual_data.keys.sort
-    rescue JSON::ParserError
-      false
-    end
-  }
-}
+Backspin.run(["date"], name: "timestamp_test", matcher: matcher)
 ```
 
 ### Logging/Debugging with :all
 
 ```ruby
-# Use :all for side effects while other matchers do validation
 logged_commands = []
 
-result = Backspin.run("debug_test",
+Backspin.run(["./test.sh"], name: "debug_test",
   matcher: {
     all: ->(recorded, actual) {
-      # Log for debugging
       logged_commands << {
         args: actual["args"],
         exit: actual["status"],
         output_size: actual["stdout"].size
       }
-      true  # Always pass
+      true
     },
-    stdout: ->(recorded, actual) {
-      # Actual validation
-      actual.include?("SUCCESS")
-    }
-  }) do
-  Open3.capture3("./test.sh")
-end
-
-# Can inspect logged_commands after run
-```
-
-## Using with run!
-
-The `run!` method automatically fails tests when matchers return false:
-
-```ruby
-# This will raise an error if the matcher fails
-Backspin.run!("critical_test",
-  matcher: {
-    stdout: ->(r, a) { a.include?("OK") },
-    status: ->(r, a) { a == 0 }
-  }) do
-  Open3.capture3("./health_check.sh")
-end
-```
-
-## Migration from match_on
-
-The `match_on` option is deprecated. To migrate:
-
-```ruby
-# Old match_on style:
-Backspin.run("test", 
-  match_on: [:stdout, ->(r, a) { ... }])
-
-# New matcher style:
-Backspin.run("test",
-  matcher: { stdout: ->(r, a) { ... } })
-
-# Old match_on with multiple fields:
-Backspin.run("test",
-  match_on: [
-    [:stdout, ->(r, a) { ... }],
-    [:stderr, ->(r, a) { ... }]
-  ])
-
-# New matcher style:
-Backspin.run("test", 
-  matcher: {
-    stdout: ->(r, a) { ... },
-    stderr: ->(r, a) { ... }
+    stdout: ->(recorded, actual) { actual.include?("SUCCESS") }
   })
 ```
-
-Key difference: `match_on` required other fields to match exactly, while the new `matcher` hash only checks specified fields.