backspin 0.7.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 803ecdad9628acd396e0d70b1e9e4081c612562f6872af8fa05108a820c61590
-  data.tar.gz: 563d3b7e8c413742453971859cf4bb31aeff11dbeee38d5804922ffa150615bb
+  metadata.gz: c8a6c6a0ef97c99ace7fb068e7b85bc40c2f45594bc30ce5002920fd62fcd384
+  data.tar.gz: f62c15526c0a19a4ae876b8c737b172e2557c54a55f4d5045a0dbc499ccfcd51
 SHA512:
-  metadata.gz: 17aff3cf0ab930e13da63fa427135cde5e41816341d75ca7712662d4feefb4df1d753db983668a57562c9922d2dda4ae5f54d8cc579ce720d0ac9009015740ff
-  data.tar.gz: 203e8c9f1158712ae20e64864a20645cf5fad7e3bd79627bf6dfc7d7efa40cd51d5cbd2e5ac037ebe9a9f8c0408c33921f948400435aa023db32da9df9dfa8fc
+  metadata.gz: 117a79e8e448bae03c68b44e8a6de23671d746d2ea664094e7dc82792d8ff323af7c6faf73f85a9aa020bb259127660abc8d7687cf861b627049b6e3b88ff41f
+  data.tar.gz: dfeabf728ef8448d01889dbe2d62d9d2a8236da296d9f6ee21619f6e3f976218cd0af3da2ac8b7f4ab1ff9cbc19dd4afaef1ca64ac777f3f9215180a1349c1c0

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,20 @@
 # Changelog
 
+## 0.9.0 - 2026-02-11
+* Breaking: `Backspin.run` and `Backspin.capture` now return `Backspin::BackspinResult` with explicit `result.actual` / `result.expected` snapshots.
+* Breaking: result convenience accessors (`result.stdout`, `result.stderr`, `result.status`) were removed in favor of snapshot access.
+* Breaking: record format bumped to 4.0 and now persists a single `snapshot` object (v3 records are rejected).
+* Simplification: removed legacy `Command`, `CommandResult`, and `RecordResult` layers; matcher/diff now operate directly on snapshots.
+* Added focused coverage for the new result contract and capture stream restoration behavior.
+* Updated project docs to reflect the BackspinResult + Snapshot API surface.
+
+## 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 +51,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

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## 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.
+Backspin is a Ruby gem for characterization testing of command-line interfaces. It records and verifies CLI interactions by capturing stdout, stderr, and exit status from shell commands, similar to how VCR works for HTTP interactions. Backspin uses YAML "records" to store snapshots.
 
 ## Development Commands
 
@@ -41,29 +41,33 @@ 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`)
-- Represents a single CLI execution
-- Stores: args, stdout, stderr, status, recorded_at
+**Snapshot Class** (`lib/backspin/snapshot.rb`)
+- Represents a single captured execution snapshot
+- Stores: command type, args, env, stdout, stderr, status, recorded_at
+
+**BackspinResult Class** (`lib/backspin/backspin_result.rb`)
+- Return object from `run` and `capture`
+- Exposes `actual` and `expected` snapshots plus verification metadata
 
 **Record Class** (`lib/backspin/record.rb`)
 - Manages YAML record files
-- Handles recording/playback sequencing
+- Handles record/verify sequencing
 
-**RSpecMetadata** (`lib/backspin/rspec_metadata.rb`)
-- Auto-generates record names from RSpec context
+**Recorder Class** (`lib/backspin/recorder.rb`)
+- Implements block capture recording and verification
+- Restores stdout/stderr streams safely after capture
 
 ### 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
 
@@ -87,4 +91,4 @@ bin/rake standard                # Alternative: Run via Rake task
 
 ### Updating Credential Patterns
 - Add patterns to `DEFAULT_CREDENTIAL_PATTERNS` in `lib/backspin.rb`
-- Test with appropriate fixtures in specs
+- Test with appropriate fixtures in specs

data/CONTRIBUTING.md

@@ -17,11 +17,11 @@ Note that Backspin is in early development and the API _will_ change before stab
 
 ## 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.
+Backspin is a Ruby gem for characterization testing of command-line interfaces. It records and verifies 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
+- Ruby 3.2, 3.3, 3.4, or 4.0
 - Bundler
 - Git
 
@@ -71,17 +71,21 @@ 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
 
-- **Command Class** (`lib/backspin/command.rb`)
-  - Represents a single CLI execution
-  - Stores: args, stdout, stderr, status, recorded_at, etc
+- **Snapshot Class** (`lib/backspin/snapshot.rb`)
+  - Represents a single execution snapshot
+  - Stores: command type, args, env, stdout, stderr, status, recorded_at
+
+- **BackspinResult Class** (`lib/backspin/backspin_result.rb`)
+  - Return object from `Backspin.run` / `Backspin.capture`
+  - Exposes `actual` and `expected` snapshots plus verify details
 
 - **Record Class** (`lib/backspin/record.rb`)
   - Manages YAML record files
-  - Handles recording/playback sequencing
+  - Handles record/verify sequencing
 
 ### Common Development Tasks
 
@@ -132,16 +136,9 @@ 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")
+    result = Backspin.run(["echo", "hello"], name: "my_test_record")
+
+    expect(result.actual.stdout).to eq("hello\n")
   end
 end
 ```
@@ -162,7 +159,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
 
@@ -219,4 +216,4 @@ If you have questions about contributing, feel free to:
 - Check existing issues and pull requests
 - Review the test suite for examples
 
-Thank you for contributing to Backspin!
+Thank you for contributing to Backspin!

data/Gemfile.lock

@@ -1,9 +1,7 @@
 PATH
   remote: .
   specs:
-    backspin (0.7.1)
-      ostruct
-      rspec-mocks (~> 3)
+    backspin (0.9.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.