backspin 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2fd83cd35c05021e0df8e585060247f0bee2fd1034d43861bf462bbb1d67101
-  data.tar.gz: 1ee344e3596a9442d17dbbaab2aaa541d676fb2f734d13b28ad34d49948b684b
+  metadata.gz: 34e60a632038ea59c7a0e95c64068032a5d3cf79584c99d622e36c6f5c610ec7
+  data.tar.gz: 49c6fc2e2902dc796072c6032c96862abf2111ad1220bd327ecc615ddb50f388
 SHA512:
-  metadata.gz: 9be21d06b0087032243e2df85bfffa060fa9a8f411ce4733a125fffbdbe40ac58d2637d1f18f9b70831730917ef9aa0baff38f6021439d37c444984f7acee886
-  data.tar.gz: 2720731b166213d551c0dd58e7478e23d20637b1d4157945fcac090298ff5059fdce1c86e3e98e20087fc5bd27de52a522b35e1a124158c914c23ede4fa53dfe
+  metadata.gz: de757488de5502e56a41e9910d7e118e93bcb1e77ef93c79014d048d59c5ac83b01644dd67c5a61a10996aa5d3ee3f372f957672cafecddcf7af9e6a4c329843
+  data.tar.gz: 805494ee3a1e0e40de7f3b1b05373d73d067798e0aed698989e5662d80ed6ef1d3b0af6a24bb6a3f1f3bc3a3affc609867c4b6daffe62c7291ee881b59499803

data/.gitignore

@@ -7,7 +7,6 @@
 /tmp/
 /.claude
 /.cursor
-/checksums/
 
 /backspin*.gem
 # rspec failure tracking

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.15.0
+* Added `stdin:` to `Backspin.run` and `Backspin.compare` to pipe a String into the command, replacing `sh -c` wrappers. For `compare`, give a side as `{command:, stdin:}`. Stdin is saved on every snapshot like stdout and stderr (empty when not given), so re-recorded files gain a `stdin` line, but it is not compared.
+* Changed `Backspin.compare` to skip credential scrubbing, so filters, matchers, and diffs see raw output and scrubbing can no longer hide mismatches (generic patterns could turn different paths into identical star runs). `run` and `capture` still scrub.
+* Added `env:` to `Backspin.compare` side Hashes (`{command:, env:, stdin:}`), so each command can get its own environment. A side's env replaces the top-level `env:` for that side, and each snapshot records the env it ran with.
+
 ## 0.14.0
 * Improved verification errors with per-field summaries for stdout, stderr, and exit status, plus three lines of context around output changes. Long diffs are limited to 50 lines; set `BACKSPIN_FULL_DIFF=1` to show the full diff.
 * Preserved custom matcher failure reasons and made missing final newlines visible in output diffs.

data/CLAUDE.md

@@ -27,7 +27,8 @@ bin/rake install     # Install gem locally for testing
 bin/rake build       # Build the gem locally
 ```
 
-Releases use a pull request that updates `lib/backspin/version.rb` and adds a matching nonempty section to `CHANGELOG.md`. Use normal premerge CI to establish readiness. After merge to `main`, the shared GitHub Actions workflow rechecks the version and changelog, invokes `rubygems/release-gem@v1` and Bundler for tagging and gem publication, then creates the GitHub release from the changelog notes. Invalid release notes prevent publication. See `CONTRIBUTING.md` for trusted publisher setup.
+Use the [shared release guide](https://github.com/rsanheim/.github#readme) and
+[Backspin quick reference](CONTRIBUTING.md#release-maintainer-setup) for releases.
 
 ### Code Quality
 ```bash

data/CONTRIBUTING.md

@@ -164,22 +164,18 @@ end
 
 ## Release Maintainer Setup
 
-Before the first automated release, configure a RubyGems trusted publisher for the `backspin` gem using the [reusable workflow setup](https://guides.rubygems.org/trusted-publishing/#using-reusable-workflows):
+Setup, trusted publishing, workflow updates, verification, and recovery live in
+[the shared release guide](https://github.com/rsanheim/.github#readme).
 
-- Repository owner: `rsanheim`
-- Repository name: `backspin`
-- Workflow filename: `gem-release.yml`
-- Workflow Repository Owner: `rsanheim`
-- Workflow Repository Name: `.github`
-- Environment: `release`
+Backspin quick reference:
 
-The workflow filename identifies the shared reusable workflow. The caller is `.github/workflows/release.yml`, which grants GitHub OIDC permission (`id-token: write`). No long-lived RubyGems API key is needed.
+1. Update `lib/backspin/version.rb` and add matching notes to `CHANGELOG.md`.
+2. Synchronize Backspin's version in `Gemfile.lock` and
+   `fixtures/projects/dummy_cli_gem/Gemfile.lock` (including its checksum entry).
+3. Run the normal checks and `BUNDLE_FROZEN=true bundle exec rake build`.
+4. Merge the reviewed PR to `main` to publish.
 
-Release pull requests update `lib/backspin/version.rb` and add a nonempty `## VERSION` section to `CHANGELOG.md`; the section body becomes the GitHub release notes. Keep the version change and its notes in the same pull request. Use the normal premerge CI checks to establish release readiness. Merging to `main` starts the release workflow, which rechecks the version and changelog before publishing; invalid release notes prevent publication. Ordinary merges do not publish anything.
-
-If publication fails before the gem is uploaded, fix the cause and manually run the Release workflow on `main`, setting `previous-ref` to the tag before the version increase. Confirm the target version is still unpublished before retrying.
-
-The shared release workflow is pinned in `.github/workflows/release.yml`. Update that commit deliberately when adopting shared release changes. Bundler's standard `build`, `install`, and `release` tasks remain available; the automated workflow is the normal publishing path.
+The caller is [`.github/workflows/release.yml`](.github/workflows/release.yml).
 
 ## Code Style
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    backspin (0.14.0)
+    backspin (0.15.0)
       logger
 
 GEM

data/README.md

@@ -92,6 +92,26 @@ result.verified?        # true when they match
 
 Only stdout, stderr, and exit status are compared, so the two commands can differ in argv and environment without any normalization. `filter` and `matcher` work exactly as they do for `Backspin.run`, and a mismatch raises `Backspin::VerificationError` unless `raise_on_verification_failure` is disabled.
 
+To pipe data into a command's stdin, give that side as a Hash with `command:` and `stdin:`:
+
+```ruby
+Backspin.compare(
+  reference: {command: ["jq", "."], stdin: '{"a": 1}'},
+  actual: {command: ["my-jq", "."], stdin: '{"a": 1}'}
+)
+```
+
+A side Hash can also take `env:`, which replaces the top-level `env:` for that side:
+
+```ruby
+Backspin.compare(
+  reference: {command: ["jq", "."], env: {"HOME" => reference_home}},
+  actual: {command: ["my-jq", "."], env: {"HOME" => actual_home}}
+)
+```
+
+`compare` records nothing, so it does not scrub credentials. Filters, matchers, and failure diffs see raw output.
+
 If the reference command produces no output at all - usually a sign it failed to start rather than that its output is genuinely empty - `compare` raises `Backspin::ReferenceCommandError` instead of comparing empty to empty.
 
 ### Recording Modes
@@ -143,6 +163,7 @@ record_count: 3                            # increments on each write
 snapshot:
   command_type: "Open3::Capture3"
   args: ["echo", "hello"]
+  stdin: ""
   stdout: "hello\n"
   stderr: ""
   status: 0
@@ -164,6 +185,14 @@ Backspin.run(
 
 If `env:` is not provided, it is not passed to `Open3.capture3` and is not recorded.
 
+### Standard Input
+
+```ruby
+Backspin.run(["cat"], name: "with_stdin", stdin: "hello from stdin")
+```
+
+`stdin:` is passed to `Open3.capture3` as `stdin_data:` and saved in the record, but only stdout, stderr, and exit status are verified. `stdin:` is not supported with the block form.
+
 ### Custom Matchers
 
 For cases where full matching isn't suitable, you can override via `matcher:`. **NOTE**: If you provide
@@ -278,7 +307,7 @@ You can configure Backspin's behavior globally:
 Backspin.configure do |config|
   config.raise_on_verification_failure = false # default is true
   config.backspin_dir = "spec/fixtures/cli_records" # default is "fixtures/backspin"
-  config.scrub_credentials = false # default is true
+  config.scrub_credentials = false # default is true; scrubs run/capture records
 end
 ```
 
@@ -331,7 +360,7 @@ end
 
 If the CLI interaction you are recording contains sensitive data in stdout/stderr, you should be careful to make sure it is not recorded to YAML.
 
-By default, Backspin automatically tries to scrub common credential patterns from recorded stdout, stderr, args, and env values. Always review your record files before commiting them to source control.
+Backspin scrubs credentials from everything it records: by default it tries to scrub common credential patterns from stdout, stderr, args, env, and stdin before `run` and `capture` save them. `compare` records nothing, so it does not scrub. Always review your record files before commiting them to source control.
 
 ```ruby
 # This will automatically scrub AWS keys, API tokens, passwords, etc.
@@ -374,11 +403,9 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 ### Releasing
 
-Open a pull request that updates `lib/backspin/version.rb` and adds a nonempty matching version section to `CHANGELOG.md` (for example, `## 0.14.0`). CI checks the effective gemspec version and fails if a version change has no release notes.
-
-Use the normal premerge CI checks to establish release readiness. After the pull request merges into `main`, the shared workflow rechecks the version and changelog, then invokes `rubygems/release-gem@v1`. The official action uses OIDC trusted publishing and Bundler's standard release task to build the gem, create and push `vVERSION`, and publish to RubyGems. After the action succeeds, the shared workflow creates a GitHub release using that changelog section. Invalid release notes prevent publication. Commits that leave the gem version unchanged do not trigger a release.
-
-The release implementation lives in [`rsanheim/.github`](https://github.com/rsanheim/.github) and is pinned to a commit in `.github/workflows/release.yml`. See [the maintainer setup](CONTRIBUTING.md#release-maintainer-setup) before enabling releases.
+See the [shared release guide](https://github.com/rsanheim/.github#readme) for
+setup and operation, and the [Backspin quick reference](CONTRIBUTING.md#release-maintainer-setup)
+for the files to update in a release PR.
 
 ## Contributing
 

data/fixtures/projects/dummy_cli_gem/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../../..
   specs:
-    backspin (0.14.0)
+    backspin (0.15.0)
       logger
 
 PATH
@@ -40,7 +40,7 @@ DEPENDENCIES
   rspec (~> 3)
 
 CHECKSUMS
-  backspin (0.14.0)
+  backspin (0.15.0)
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   dummy_cli_gem (0.1.0)
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203

data/lib/backspin/snapshot.rb

@@ -3,14 +3,16 @@
 module Backspin
   # Represents a single captured execution snapshot.
   class Snapshot
-    attr_reader :command_type, :args, :env, :stdout, :stderr, :status, :recorded_at
+    attr_reader :command_type, :args, :env, :stdin, :stdout, :stderr, :status, :recorded_at
 
-    def initialize(command_type:, args:, env: nil, stdout: "", stderr: "", status: 0, recorded_at: nil)
+    def initialize(command_type:, args:, env: nil, stdin: "", stdout: "", stderr: "", status: 0, recorded_at: nil, scrub: Backspin.configuration.scrub_credentials)
+      @scrub = scrub
       @command_type = command_type
       @args = sanitize_args(args)
       @env = env.nil? ? nil : sanitize_env(env)
-      @stdout = Backspin.scrub_text((stdout || "").dup).freeze
-      @stderr = Backspin.scrub_text((stderr || "").dup).freeze
+      @stdin = scrub_string((stdin || "").dup).freeze
+      @stdout = scrub_string((stdout || "").dup).freeze
+      @stderr = scrub_string((stderr || "").dup).freeze
       @status = status || 0
       @recorded_at = recorded_at.nil? ? nil : recorded_at.dup.freeze
       @serialized_hash = build_serialized_hash
@@ -42,6 +44,7 @@ module Backspin
         command_type: command_type,
         args: data["args"],
         env: data["env"],
+        stdin: data["stdin"],
         stdout: data["stdout"],
         stderr: data["stderr"],
         status: data["status"],
@@ -55,6 +58,7 @@ module Backspin
       data = {
         "command_type" => command_type.name,
         "args" => args,
+        "stdin" => stdin,
         "stdout" => stdout,
         "stderr" => stderr,
         "status" => status,
@@ -64,25 +68,25 @@ module Backspin
       deep_freeze(data)
     end
 
-    def scrub_args(value)
-      return value unless Backspin.configuration.scrub_credentials && value
+    def scrub_string(text)
+      @scrub ? Backspin.scrub_text(text) : text
+    end
 
+    def scrub_args(value)
       case value
       when String
-        Backspin.scrub_text(value)
+        scrub_string(value)
       when Array
         value.map { |entry| scrub_args(entry) }
       when Hash
-        value.transform_values { |entry| entry.is_a?(String) ? Backspin.scrub_text(entry) : entry }
+        value.transform_values { |entry| entry.is_a?(String) ? scrub_string(entry) : entry }
       else
         value
       end
     end
 
     def scrub_env(value)
-      return value unless Backspin.configuration.scrub_credentials && value
-
-      value.transform_values { |entry| entry.is_a?(String) ? Backspin.scrub_text(entry) : entry }
+      value.transform_values { |entry| entry.is_a?(String) ? scrub_string(entry) : entry }
     end
 
     def sanitize_args(value)

data/lib/backspin/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Backspin
-  VERSION = "0.14.0"
+  VERSION = "0.15.0"
 end

data/lib/backspin.rb

@@ -76,17 +76,19 @@ module Backspin
     # @param command [String, Array] Command to execute via Open3.capture3
     # @param name [String] Name for the record file
     # @param env [Hash] Environment variables to pass to Open3.capture3
+    # @param stdin [String] Data written to the command's stdin (recorded, not compared)
     # @param mode [Symbol] Recording mode - :auto, :record, :verify
     # @param matcher [Proc, Hash] Custom matcher for verification
     # @param filter [Proc] Custom filter for recorded data/canonicalization
     # @param filter_on [Symbol] Filter application mode - :both (default), :record
     # @return [BackspinResult] Aggregate result for this run
-    def run(command = nil, name:, env: nil, mode: :auto, matcher: nil, filter: nil, filter_on: :both, &block)
+    def run(command = nil, name:, env: nil, stdin: nil, mode: :auto, matcher: nil, filter: nil, filter_on: :both, &block)
       validate_filter_on!(filter_on)
 
       if block_given?
         raise ArgumentError, "command must be omitted when using a block" unless command.nil?
         raise ArgumentError, "env is not supported when using a block" unless env.nil?
+        raise ArgumentError, "stdin is not supported when using a block" unless stdin.nil?
 
         return perform_capture(name, mode: mode, matcher: matcher, filter: filter, filter_on: filter_on, &block)
       end
@@ -97,6 +99,7 @@ module Backspin
         command,
         name: name,
         env: env,
+        stdin: stdin,
         mode: mode,
         matcher: matcher,
         filter: filter,
@@ -126,22 +129,31 @@ module Backspin
     # Only stdout, stderr, and status are compared, so the two commands may
     # differ in argv and env without any normalization.
     #
-    # @param reference [String, Array] Command that defines the correct output
-    # @param actual [String, Array] Command under test
+    # Either side may be a Hash of {command:, env:, stdin:} to give that command
+    # its own env or stdin. A side's env replaces the top-level env for that
+    # side. Stdin is recorded on each snapshot, not compared.
+    #
+    # Credentials are not scrubbed, so the filter, matcher, and diff see raw output.
+    #
+    # @param reference [String, Array, Hash] Command that defines the correct output
+    # @param actual [String, Array, Hash] Command under test
     # @param env [Hash] Environment variables passed to both commands
     # @param matcher [Proc, Hash] Custom matcher for verification
     # @param filter [Proc] Custom filter applied to both sides before comparing
     # @return [BackspinResult] expected = reference, actual = command under test
     def compare(reference:, actual:, env: nil, matcher: nil, filter: nil)
-      normalized_env = normalize_env(env)
+      reference_command, reference_env, reference_stdin = reference.is_a?(Hash) ? reference.values_at(:command, :env, :stdin) : [reference, nil, nil]
+      actual_command, actual_env, actual_stdin = actual.is_a?(Hash) ? actual.values_at(:command, :env, :stdin) : [actual, nil, nil]
+      reference_env = normalize_env(reference_env || env)
+      actual_env = normalize_env(actual_env || env)
 
-      expected_snapshot, = capture_command_snapshot(reference, normalized_env)
+      expected_snapshot, = capture_command_snapshot(reference_command, reference_env, reference_stdin, scrub: false)
       if expected_snapshot.stdout.empty? && expected_snapshot.stderr.empty?
         raise ReferenceCommandError,
           "Reference command produced no output (exit status #{expected_snapshot.status}): #{reference.inspect}"
       end
 
-      actual_snapshot, = capture_command_snapshot(actual, normalized_env)
+      actual_snapshot, = capture_command_snapshot(actual_command, actual_env, actual_stdin, scrub: false)
 
       command_diff = CommandDiff.new(
         expected: expected_snapshot,
@@ -188,7 +200,7 @@ module Backspin
       result
     end
 
-    def perform_command_run(command, name:, env:, mode:, matcher:, filter:, filter_on:)
+    def perform_command_run(command, name:, env:, stdin:, mode:, matcher:, filter:, filter_on:)
       record_path = Record.build_record_path(name)
       mode = determine_mode(mode, record_path)
       validate_mode!(mode)
@@ -199,7 +211,7 @@ module Backspin
 
       result = case mode
       when :record
-        actual_snapshot, output = capture_command_snapshot(command, normalized_env)
+        actual_snapshot, output = capture_command_snapshot(command, normalized_env, stdin)
         record.set_snapshot(actual_snapshot)
         record.save(filter: filter)
         BackspinResult.new(
@@ -217,7 +229,7 @@ module Backspin
           raise RecordFormatError, "Invalid record format: expected Open3::Capture3 for run"
         end
 
-        actual_snapshot, output = capture_command_snapshot(command, normalized_env)
+        actual_snapshot, output = capture_command_snapshot(command, normalized_env, stdin)
         command_diff = CommandDiff.new(
           expected: expected_snapshot,
           actual: actual_snapshot,
@@ -243,16 +255,18 @@ module Backspin
       result
     end
 
-    def capture_command_snapshot(command, env)
-      stdout, stderr, status = execute_command(command, env)
+    def capture_command_snapshot(command, env, stdin, scrub: configuration.scrub_credentials)
+      stdout, stderr, status = execute_command(command, env, stdin)
       snapshot = Snapshot.new(
         command_type: Open3::Capture3,
         args: command,
         env: env,
+        stdin: stdin,
         stdout: stdout,
         stderr: stderr,
         status: status.exitstatus,
-        recorded_at: Time.now.utc.iso8601
+        recorded_at: Time.now.utc.iso8601,
+        scrub: scrub
       )
       [snapshot, [stdout, stderr, status]]
     end
@@ -264,13 +278,13 @@ module Backspin
       env.empty? ? nil : env
     end
 
-    def execute_command(command, env)
+    def execute_command(command, env, stdin)
       case command
       when String
-        env ? Open3.capture3(env, command) : Open3.capture3(command)
+        env ? Open3.capture3(env, command, stdin_data: stdin) : Open3.capture3(command, stdin_data: stdin)
       when Array
         raise ArgumentError, "command array cannot be empty" if command.empty?
-        env ? Open3.capture3(env, *command) : Open3.capture3(*command)
+        env ? Open3.capture3(env, *command, stdin_data: stdin) : Open3.capture3(*command, stdin_data: stdin)
       else
         raise ArgumentError, "command must be a String or Array"
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: backspin
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Rob Sanheim