backspin 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9533baf54aa3ae09b9d483d41149a6ede985f3f974f038e287034928a0ab1e3
-  data.tar.gz: 75b9cb2018b1f1ca5878f6ce75af74bc9fc4822319ac2f12e8c654f30624f859
+  metadata.gz: 3810a17b9b213b010cadd7419559fda50aed8dee3faad5865e824e765921339d
+  data.tar.gz: 400594d38ca7937da9095c78eb6578d5d384077a1cbbf78db97f06e133c6dcd0
 SHA512:
-  metadata.gz: a8d851c2836d8cd0be15b341a7f2af332c356aaa9688766a5b51f65110539a2d500cac8238abd4bc0a668a689effbef45a8f009829a3cd28ff4acd249bb506b4
-  data.tar.gz: 0151e1de9a47285ca75552e97154b57100de50fe691100869144e1ed17e1b7c421a012599c4462a333f6abd0c4779f110a4fbffd2bbe60d14d600469da459bad
+  metadata.gz: c2614110086b787c10b31504ae0eed80b32adc7a72d61709f6fba6245e093b35f92816227faebf781b3257e25b766c45676c47e74422176ae07fbc3eafaabce2
+  data.tar.gz: 6bb11f527a1aebc8ed495ccde7ca4deddf87b33f33f160cf76da13e02bc994e9b397cbaa59df2f30656cbd4a589ea70ebe24194743ac96a9b639fcda4cd9bf22

data/.circleci/config.yml

@@ -20,6 +20,9 @@ jobs:
       - run:
           name: Run specs
           command: bundle exec rake spec
+      - run:
+          name: Run fake gem specs
+          command: bundle exec rake spec:fake_gem
 
   lint:
     resource_class: medium

data/.gitignore

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

data/.ruby-version

@@ -1 +1 @@
-4.0.0
+4

data/.standard.yml

@@ -2,6 +2,11 @@
 parallel: true
 format: progress
 
+# Match the gemspec's required_ruby_version. Without this, Standard infers the
+# target from .ruby-version (4) and flags requires that are only redundant on
+# Ruby >= 3.5 - removing them would break the 3.x versions we still support.
+ruby_version: 3.2
+
 ignore:
   - 'tmp/**/*'
   - 'vendor/**/*'

data/CHANGELOG.md

@@ -1,12 +1,22 @@
 # Changelog
 
+## 0.13.0
+* Added `Backspin.compare(reference:, actual:)` for differential testing - runs both commands live and compares their filtered output, with no record file. Only stdout, stderr, and exit status are compared, so the two commands may differ in argv and env without normalization.
+* Added `Backspin::ReferenceCommandError`, raised when a compare's reference command produces no output at all (usually a sign it failed to start), rather than comparing empty to empty.
+* Raised the minimum supported Ruby to 3.2 (3.1 reached end-of-life in March 2025).
+* Fixed snapshot timestamps to be recorded as UTC rather than local time, so re-recording in a different timezone no longer produces noisy diffs.
+* Fixed a missing `require "time"`, which could raise `NoMethodError` on `Time#iso8601` in consumers that never load the time stdlib themselves.
+
+## 0.12.0 - 2026-02-11
+* Added `BACKSPIN_MODE` environment variable to globally override recording mode (`auto`, `record`, `verify`).
+* Explicit `mode:` kwarg still takes highest precedence, followed by the env var, then auto-detection.
+* Added configurable logger to `Backspin::Configuration` (defaults to WARN level, logfmt-lite format, and can be disabled with `config.logger = nil`).
+
 ## 0.11.0 - 2026-02-11
 * Added immutable top-level `first_recorded_at` metadata for record files.
 * Added mutable top-level `recorded_at` metadata that updates on each successful re-record.
 * Added top-level `record_count`, incremented on each successful record write.
-* Record format now writes `format_version: 4.1`; loading remains backward-compatible with 4.0 record files.
-* Added acceptance coverage for v4.1 schema and 4.0-to-4.1 upgrade behavior.
-* Removed legacy committed `.yml` record fixtures from old schema versions.
+* Bumped record format to 4.1; loading remains backward-compatible with 4.0 record files.
 
 ## 0.10.0 - 2026-02-11
 * Added `filter_on` to `Backspin.run` and `Backspin.capture` (`:both` default, `:record` opt-out).
@@ -19,7 +29,6 @@
 * 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

data/Gemfile.lock

@@ -1,70 +1,72 @@
 PATH
   remote: .
   specs:
-    backspin (0.11.0)
+    backspin (0.13.0)
+      logger
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
     diff-lcs (1.6.2)
-    json (2.16.0)
-    language_server-protocol (3.17.0.5)
+    json (2.21.1)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
-    parallel (1.27.0)
-    parser (3.3.10.0)
+    logger (1.7.0)
+    parallel (1.28.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
-    prism (1.6.0)
+    prism (1.9.0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.0)
-    regexp_parser (2.11.3)
-    rspec (3.13.1)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.4)
+    rspec-core (3.13.6)
       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)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.4)
-    rubocop (1.81.7)
+    rspec-support (3.13.7)
+    rubocop (1.88.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.47.1, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.48.0)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
-    rubocop-performance (1.25.0)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     ruby-progressbar (1.13.0)
-    standard (1.52.0)
+    standard (1.56.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.81.7)
+      rubocop (~> 1.88.0)
       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)
+    standard-performance (1.9.0)
       lint_roller (~> 1.1)
-      rubocop-performance (~> 1.25.0)
-    timecop (0.9.10)
+      rubocop-performance (~> 1.26.0)
+    timecop (0.9.11)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
@@ -81,4 +83,4 @@ DEPENDENCIES
   timecop (~> 0.9)
 
 BUNDLED WITH
-  4.0.5
+  4.0.16

data/README.md

@@ -75,6 +75,25 @@ end
 
 Block capture records a single combined stdout/stderr snapshot. Exit status is a placeholder (`0`) in this mode.
 
+### Differential Testing (Compare)
+
+Use `Backspin.compare` when the question is "does my tool produce the same output as this reference tool?" Both commands run live and their output is compared directly - nothing is recorded to disk:
+
+```ruby
+result = Backspin.compare(
+  reference: ["bundle", "exec", "rspec", "spec/failing_spec.rb"],
+  actual: ["my-runner", "spec/failing_spec.rb"]
+)
+
+result.expected.stdout  # reference output
+result.actual.stdout    # output from the command under test
+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.
+
+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
 
 Backspin supports different modes for controlling how commands are recorded and verified:
@@ -91,6 +110,26 @@ result = Backspin.run(["echo", "hello"], name: "echo_test", mode: :verify)
 expect(result.verified?).to be true
 ```
 
+### Environment Variable Mode Override
+
+Set `BACKSPIN_MODE` to globally force a recording mode without changing any test code:
+
+```bash
+# Re-record all fixtures
+BACKSPIN_MODE=record bundle exec rspec
+
+# Verify-only (CI, no accidental re-records)
+BACKSPIN_MODE=verify bundle exec rspec
+```
+
+Precedence (highest to lowest):
+
+1. Explicit `mode:` kwarg (`:record` or `:verify`)
+2. `BACKSPIN_MODE` environment variable
+3. Auto-detection (record if no file exists, verify if it does)
+
+Allowed values: `auto`, `record`, `verify` (case-insensitive). Invalid values raise `ArgumentError`.
+
 ### Record Metadata
 
 Backspin writes records using `format_version: "4.1"` with top-level metadata:
@@ -191,7 +230,7 @@ Backspin.run(["echo", "id=123"], name: "record_only", filter: normalize_filter,
 
 ### Working with the Result Object
 
-The API returns a `Backspin::BackspinResult` object with helpful methods:
+The API returns a `Backspin::BackspinResult` object with details on run.
 
 ```ruby
 result = Backspin.run(["sh", "-c", "echo out; echo err >&2; exit 42"], name: "my_test")
@@ -243,6 +282,34 @@ result = Backspin.run(["echo", "different"], name: "my_test")
 Backspin.reset_configuration!
 ```
 
+### Logging
+
+Backspin includes a configurable logger for diagnostics. By default it is set to WARN level; but most messages are logged at DEBUG level. 
+So if you are looking for more detailed logs, you can set the logger to DEBUG level:
+
+```ruby
+Backspin.configure do |config|
+  config.logger = Logger.new($stdout)
+  config.logger.level = Logger::DEBUG
+end
+```
+
+To replace the logger entirely:
+
+```ruby
+Backspin.configure do |config|
+  config.logger = Logger.new("log/backspin.log")
+end
+```
+
+To disable Backspin logging entirely (for example in tests):
+
+```ruby
+Backspin.configure do |config|
+  config.logger = nil
+end
+```
+
 ### Credential Scrubbing
 
 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.
@@ -274,6 +341,18 @@ Automatic scrubbing includes:
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
 
+This repo also includes a decoupled full-stack fixture gem at `fixtures/projects/dummy_cli_gem` that uses Backspin the way downstream projects do. Run it with:
+
+```bash
+bundle exec rake full_stack:dummy_app
+```
+
+To re-record that fixture's committed YAML snapshots:
+
+```bash
+bundle exec rake full_stack:record_dummy_app
+```
+
 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

data/Rakefile

@@ -6,6 +6,33 @@ require "standard/rake"
 
 RSpec::Core::RakeTask.new(:spec)
 
+def run_in_fake_gem(command)
+  dummy_app_dir = File.expand_path("fixtures/projects/dummy_cli_gem", __dir__)
+
+  Bundler.with_unbundled_env do
+    Dir.chdir(dummy_app_dir) do
+      sh "bundle check || bundle install"
+      sh command
+    end
+  end
+end
+
+namespace :spec do
+  desc "Run the dummy fixture gem specs with Backspin (decoupled from main suite)"
+  task :fake_gem do
+    run_in_fake_gem("bundle exec rspec")
+  end
+
+  desc "Re-record Backspin YAML fixtures for the dummy fixture gem"
+  task :fake_gem_record do
+    original_record_mode = ENV["RECORD_MODE"]
+    ENV["RECORD_MODE"] = "record"
+    run_in_fake_gem("bundle exec rspec")
+  ensure
+    ENV["RECORD_MODE"] = original_record_mode
+  end
+end
+
 task default: %i[spec standard]
 
 load "release.rake" if File.exist?("release.rake")

data/backspin.gemspec

@@ -12,7 +12,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(">= 3.1.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
@@ -24,4 +24,6 @@ Gem::Specification.new do |spec|
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
+
+  spec.add_dependency "logger"
 end

data/docs/compare-api-plan.md

@@ -0,0 +1,193 @@
+# Compare API Plan — differential testing between two commands
+
+Date: 2026-07-20 (revised 2026-07-25)
+
+## Motivation
+
+The most common way Backspin is used in the `plur` test suite is *differential
+testing*: "does tool B produce the same output as reference tool A?" plur is a
+Go reimplementation of a parallel RSpec runner, and its golden specs assert that
+plur's output matches `rspec`'s own output byte-for-byte.
+
+Backspin has no first-class API for this, so today it is expressed as an
+implicit two-call dance with the same record name:
+
+```ruby
+# record rspec baseline
+chdir(fixture) { Backspin.run(rspec_cmd, name: "x", filter: normalize) }
+# verify plur against it
+result = chdir(fixture) { Backspin.run(plur_cmd, name: "x", filter: normalize) }
+expect(result.verified?).to be(true)
+```
+
+That pattern works but has sharp edges, each of which has bitten a real plur
+spec:
+
+1. **Ordering is load-bearing and invisible.** The first `run` records only
+   because the record file happens not to exist yet; if it does exist, *both*
+   calls verify against the stored baseline — a different meaning than the code
+   reads like.
+2. **A stale baseline requires a manual `rm`.** Change the fixture and the
+   committed `.yml` no longer matches the reference command, so the first call
+   fails on `reference-vs-stale-baseline`. Nothing signals that deleting the
+   snapshot is the fix.
+3. **The command line must be neutralized by hand.** The two commands *differ*
+   on purpose (`rspec …` vs `plur …`), so specs stuff `"args" => ["[PLACEHOLDER]"]`
+   into the filter to stop the recorded command from mismatching.
+4. **The filter is passed twice** and must be identical on both calls.
+5. **The dance can span two examples.** plur's minitest golden test records in
+   one `it` and verifies in a *different* `it` — order-dependent across
+   examples, so it only works because RSpec runs in defined order.
+
+The gap is small and specific: `Backspin.run` assumes the *record command* and
+the *verify command* are the same. Differential testing needs them to differ.
+
+## The idea
+
+Add `Backspin.compare`, which runs a **reference** command and an **actual**
+command and compares their (filtered) output. It is pure orchestration over
+primitives Backspin already has — no new filtering, snapshot, diff, matcher, or
+result code, and no record file.
+
+```ruby
+Backspin.compare(
+  reference:,   # String/Array command that defines correct output
+  actual:,      # String/Array command under test
+  env: nil,
+  matcher: nil, # reused as-is
+  filter: nil   # reused as-is
+)
+# => BackspinResult
+```
+
+`reference` maps to `result.expected`, `actual` maps to `result.actual` — which
+is exactly the existing `BackspinResult` contract (expected = baseline, actual =
+what just ran). See `docs/backspin-result-api-sketch.md`.
+
+## Scope: live-vs-live only
+
+An earlier draft also proposed a snapshot-backed mode (`name:` + `mode:`), where
+`compare` would record the reference to a `.yml` and later verify `actual`
+against it. That is deliberately **not** in scope:
+
+- In `mode: :verify` the `reference:` argument would be silently ignored. You
+  could change the reference command and nothing would happen until someone
+  deleted the record — sharp edge #2 wearing a new hat, plus a dead keyword arg.
+- It roughly doubles the API surface (`name`, `mode`, `BACKSPIN_MODE`,
+  `filter_on`) for a caller that does not exist yet. plur always has `rspec`
+  available, in dev and in CI.
+
+If a real caller shows up with a reference command that is expensive or absent
+in CI, add it then. `Backspin.run` already covers "freeze one command's output."
+
+## Reuse map — what each need already maps to
+
+| Need | Existing primitive | Location |
+|---|---|---|
+| Run a command → stdout/stderr/status | `execute_command(command, env)` | `lib/backspin.rb` |
+| Build a snapshot value object | `Snapshot.new(command_type: Open3::Capture3, …)` | `lib/backspin/snapshot.rb` |
+| Apply `filter` to both sides | `CommandDiff#build_comparison_snapshot` | `lib/backspin/command_diff.rb` |
+| Compare (default = stdout/stderr/status; custom matcher/hash) | `CommandDiff` + `Matcher` | `lib/backspin/command_diff.rb`, `lib/backspin/matcher.rb` |
+| `verified?` / `diff` / `summary` | `CommandDiff` | `lib/backspin/command_diff.rb` |
+| Result object (`expected`, `actual`, `verified?`, `diff`, `error_message`) | `BackspinResult` | `lib/backspin/backspin_result.rb` |
+| Raise on mismatch (config-gated) | `raise_on_verification_failure!(result)` | `lib/backspin.rb` |
+
+The heart of it: `CommandDiff.new(expected:, actual:, matcher:, filter:)`
+already takes two snapshots, applies the filter to both, runs the matcher, and
+produces `verified?`/`diff`. `compare` just has to hand it two snapshots.
+
+## Semantics that fall out for free
+
+- **args/env are not compared.** The default matcher only looks at stdout,
+  stderr, status (`Matcher#evaluate_default`), and `CommandDiff#diff` only diffs
+  those three. So two intentionally-different commands compare cleanly with no
+  `args` placeholder — deleting plur boilerplate.
+- **command_type matches.** Both sides are `Open3::Capture3`, so
+  `CommandDiff#command_types_match?` is true.
+- **Strict-by-default is preserved.** `raise_on_verification_failure!` already
+  raises `VerificationError` (with `result.diff`) unless
+  `raise_on_verification_failure = false`. `compare` reuses it verbatim.
+
+## Guard: a broken reference must not pass
+
+Live-vs-live has one failure mode the two-call dance did not: if the reference
+command fails to *run at all* — wrong directory, `bundle` not on `PATH`, a load
+error — it produces empty stdout and a non-zero status. If `actual` fails the
+same way, `verified?` is true and the spec goes green while testing nothing.
+
+`compare` raises `Backspin::ReferenceCommandError` when the reference command
+produces no output on either stream. Exit status can't be the signal: plur's
+golden specs deliberately run failing suites that exit 1.
+
+## The new code
+
+1. `Backspin.compare` public method (validation + orchestration + the guard).
+2. A private `capture_command_snapshot(command, env)` wrapping
+   `execute_command` + `Snapshot.new`. This is **extracted from existing
+   duplication** — `perform_command_run` builds that same snapshot twice, so
+   pulling it out DRYs `run` as well.
+3. One fix in `raise_on_verification_failure!`: only emit the `Record:` line
+   when there is a record path, so `compare` failures don't render a dangling
+   `Record: ` label.
+
+No changes to `CommandDiff`, `Matcher`, `Snapshot`, `Record`, or
+`BackspinResult`. `compare` lives beside `run`/`capture` in `lib/backspin.rb`.
+
+### Notes
+
+- There is no `filter_on:` keyword. `filter_on: :record` would mean "filter only
+  when persisting", and `compare` never persists — passing it would silently
+  disable filtering. Omitting the keyword makes that a plain `ArgumentError`.
+- `record_path` is `nil` on the result, and `mode` is `:verify` (nothing was
+  recorded, so `recorded?` is false).
+
+## Before / after (plur golden spec)
+
+Today (`spec/integration/spec/aggregate_failure_golden_spec.rb` in plur):
+
+```ruby
+chdir(fixture) { Backspin.run(rspec_cmd, name: "x", filter: normalize) }
+result = chdir(fixture) { Backspin.run(plur_cmd, name: "x", filter: normalize) }
+expect(result.verified?).to be(true)
+```
+
+With `compare`:
+
+```ruby
+result = chdir(fixture) do
+  Backspin.compare(reference: rspec_cmd, actual: plur_cmd, filter: normalize)
+end
+expect(result.verified?).to be(true)
+```
+
+A `dir:` option to drop the `chdir` wrapper is a possible follow-up; not needed
+here, since one wrapper now covers what took two.
+
+## Success criteria
+
+1. `Backspin.compare(reference:, actual:)` runs both and returns a
+   `BackspinResult` with `expected` = reference snapshot, `actual` = actual
+   snapshot, and boolean `verified?`.
+2. On mismatch, `result.diff` / `result.error_message` are populated by the
+   existing `CommandDiff`, and `VerificationError` is raised unless
+   `raise_on_verification_failure = false`. The failure message has no empty
+   `Record:` line.
+3. `filter` / `matcher` behave exactly as in `run` (same objects, same code
+   paths).
+4. Two commands with different argv compare on output only — no `args`
+   normalization needed.
+5. No record file is written or read.
+6. A reference command that produces no output raises
+   `ReferenceCommandError` rather than comparing empty-to-empty.
+7. No new filtering / snapshot / diff / matcher / result implementation — only a
+   `compare` entry point, the extracted `capture_command_snapshot` helper, and
+   the nil-`record_path` message fix.
+
+## Downstream: what this buys plur
+
+Six call-site pairs across four files collapse to a single call each:
+`single_failure_golden_spec.rb` (three examples), `aggregate_failure_golden_spec.rb`,
+`pending_output_spec.rb`, and `minitest_integration_spec.rb` (the cross-example
+one). Five fixture YAMLs get deleted, along with every `"args" => [...]`
+placeholder line. plur's other five Backspin specs are ordinary single-command
+snapshot tests and are untouched.

data/fixtures/projects/dummy_cli_gem/.rspec

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

data/fixtures/projects/dummy_cli_gem/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "backspin", path: "../../.."
+
+group :development, :test do
+  gem "rake", "~> 13"
+  gem "rspec", "~> 3"
+end

data/fixtures/projects/dummy_cli_gem/Gemfile.lock

@@ -0,0 +1,55 @@
+PATH
+  remote: ../../..
+  specs:
+    backspin (0.13.0)
+      logger
+
+PATH
+  remote: .
+  specs:
+    dummy_cli_gem (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.6.2)
+    logger (1.7.0)
+    rake (13.3.1)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      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.7)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+
+PLATFORMS
+  aarch64-linux
+  ruby
+
+DEPENDENCIES
+  backspin!
+  dummy_cli_gem!
+  rake (~> 13)
+  rspec (~> 3)
+
+CHECKSUMS
+  backspin (0.13.0)
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  dummy_cli_gem (0.1.0)
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
+  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
+  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
+  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
+  rspec-mocks (3.13.7) sha256=0979034e64b1d7a838aaaddf12bf065ea4dc40ef3d4c39f01f93ae2c66c62b1c
+  rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
+
+BUNDLED WITH
+  4.0.5

data/fixtures/projects/dummy_cli_gem/LICENSE.txt

@@ -0,0 +1 @@
+MIT License

data/fixtures/projects/dummy_cli_gem/README.md

@@ -0,0 +1,7 @@
+# DummyCliGem Fixture
+
+This is a minimal fixture gem used by Backspin's full-stack integration checks.
+
+- It shells out to standard unix utilities (`echo`, `ls`).
+- Its RSpec suite verifies command output through `Backspin.run`.
+- Snapshot YAML records are stored in-repo under `spec/fixtures/backspin`.

data/fixtures/projects/dummy_cli_gem/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/fixtures/projects/dummy_cli_gem/dummy_cli_gem.gemspec

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "lib/dummy_cli_gem/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "dummy_cli_gem"
+  spec.version = DummyCliGem::VERSION
+  spec.authors = ["Backspin"]
+  spec.email = ["noreply@example.com"]
+  spec.summary = "Dummy CLI gem fixture for Backspin full-stack verification"
+  spec.description = "Fixture gem that shells out to unix utilities and is tested via Backspin snapshots."
+  spec.homepage = "https://example.com/dummy_cli_gem"
+  spec.license = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir["lib/**/*.rb", "exe/*", "spec/**/*", "script/**/*", "README.md", "LICENSE.txt"]
+  end
+  spec.bindir = "exe"
+  spec.executables = ["dummy_cli_gem"]
+  spec.require_paths = ["lib"]
+end