backspin 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edf2daa2123a270ca28d593b594188db57913b2ca5905a45b6a9e0d1221c0da4
-  data.tar.gz: 3ec4407d3396e3e8390f62b3c0e7d2124bdf026e4b02e74c036ee37fab8430a4
+  metadata.gz: 6373427307003e8469435ce1c461e6f9bf6ff307c952bce87f07c393470f5fdc
+  data.tar.gz: 3e8487ba8345a4fef0b8419487de0e84b756c302ada8b313e2bf0e5cd6c1ec1a
 SHA512:
-  metadata.gz: a851d194aa4f400c9104643b5521e7b5bd5e159708a0d6114c70cfd39907fb6174041a3bccffdc824edb3e224bab7db453b906c35adc7f0a2908d2b034a9b11a
-  data.tar.gz: 01b1c9b4288f978d9946090afda49e17001732ec0b4f5e47d3831767975d731e5c940cc0fbdd7ccfca4a2bdf54bc8d281eba7d3dc4cbbd137e3f4edb576d9378
+  metadata.gz: d7f1915e4632d8fb4b08ae6a8ff0e6e9846ed3f1cd783c7dcc283ca2d3816afb518173a50cd519b5859eb6d991be7636a81a48e34fb63f0176d14c9a2bdd500a
+  data.tar.gz: 7307a43c18730ec430f39dbadecb301eaad177ecc3795906f9682ec3e4781e9d5d9ec2b8c913220f8c5985393ae90e73974e5f2855a40ea17d33f87914b5a527

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/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.12.0
+* 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.
+* 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).
 * Changed default filter behavior: `filter` now applies during verify comparisons/diffs when `filter_on: :both`.
@@ -11,7 +22,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,7 +1,8 @@
 PATH
   remote: .
   specs:
-    backspin (0.10.0)
+    backspin (0.12.0)
+      logger
 
 GEM
   remote: https://rubygems.org/
@@ -11,6 +12,7 @@ GEM
     json (2.16.0)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
+    logger (1.7.0)
     parallel (1.27.0)
     parser (3.3.10.0)
       ast (~> 2.4.1)

data/README.md

@@ -91,6 +91,48 @@ 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:
+
+```yaml
+---
+format_version: "4.1"
+first_recorded_at: "2026-01-01T10:00:00Z" # immutable
+recorded_at: "2026-02-01T10:00:00Z"       # updates on each write
+record_count: 3                            # increments on each write
+snapshot:
+  command_type: "Open3::Capture3"
+  args: ["echo", "hello"]
+  stdout: "hello\n"
+  stderr: ""
+  status: 0
+  recorded_at: "2026-02-01T10:00:00Z"
+```
+
+When re-recording with `mode: :record`, Backspin preserves `first_recorded_at`, updates `recorded_at`, and increments `record_count`.
+Existing `4.0` records still load and are upgraded to `4.1` metadata on the next write.
+
 ### Environment Variables
 
 ```ruby
@@ -221,6 +263,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.
@@ -252,6 +322,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

@@ -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/backspin-result-api-sketch.md

@@ -141,14 +141,16 @@ result.expected.stdout
 - Error message is generated from `BackspinResult#error_message`.
 - Do not duplicate `diff` content in exception formatting.
 
-## Record Format Sketch (v4)
+## Record Format Sketch (v4.1)
 
 Single-snapshot format to match single-snapshot runtime model:
 
 ```yaml
 ---
-format_version: "4.0"
+format_version: "4.1"
+first_recorded_at: "2026-01-01T00:00:00Z"
 recorded_at: "2026-02-11T00:00:00Z"
+record_count: 3
 snapshot:
   command_type: "Open3::Capture3"
   args: ["echo", "hello"]
@@ -184,11 +186,11 @@ Status date: 2026-02-11
 
 1. `Snapshot` and `BackspinResult` classes are implemented and wired into runtime paths.
 2. `Backspin.run` and `Backspin.capture` now return `BackspinResult`.
-3. `Record` persistence moved to v4 single-snapshot format (`snapshot` key, no `commands` array).
+3. `Record` persistence moved to v4 single-snapshot format (`snapshot` key, no `commands` array), with v4.1 top-level metadata.
 4. `Matcher` and `CommandDiff` now operate on expected/actual snapshots.
 5. Legacy result/command layering was removed from `lib/`.
-6. Specs have been migrated to the new result contract and v4 format.
-7. Validation is green: `66 examples, 0 failures` and Standard lint passes.
+6. Specs have been migrated to the new result contract and v4.1 format.
+7. Validation is green: `89 examples, 0 failures` and Standard lint passes.
 8. Public docs now use `result.actual` / `result.expected` terminology.
 
 ## Success Criteria
@@ -198,7 +200,7 @@ Status date: 2026-02-11
 3. In `:verify` mode, `result.expected` is present, `result.verified?` is boolean, and mismatch cases populate `result.diff` plus `result.error_message`.
 4. No multi-command result API remains in the public result contract.
 5. Snapshot object exposes a stable single-command shape: `stdout`, `stderr`, `status`, `args`, `env`, `command_type`.
-6. Record format uses one snapshot (v4), not a commands array.
+6. Record format uses one snapshot (v4.x), not a commands array.
 7. Existing strict verification behavior remains: default raises `Backspin::VerificationError`, while `raise_on_verification_failure = false` returns a failed result without raising.
 8. End-to-end Unix command examples are covered in specs: `echo` record/verify, `ls -1` record/verify, `date` mismatch behavior (or matcher override), and captured `grep | wc` pipeline output via `Backspin.capture`.
 9. Matcher behavior is preserved: default matching remains stdout/stderr/status, and custom `matcher:` contract (Proc, hash fields, `:all`) continues to work for both run and capture verification.

data/fixtures/backspin/.gitkeep

@@ -0,0 +1 @@
+

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.11.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.11.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.1.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

data/fixtures/projects/dummy_cli_gem/exe/dummy_cli_gem

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "dummy_cli_gem"
+
+exit(DummyCliGem::CLI.run(ARGV))

data/fixtures/projects/dummy_cli_gem/fixtures/backspin/dummy_echo.yml

@@ -0,0 +1,18 @@
+---
+format_version: '4.1'
+first_recorded_at: '2026-02-11T01:57:42-06:00'
+recorded_at: '2026-02-11T01:57:42-06:00'
+record_count: 1
+snapshot:
+  command_type: Open3::Capture3
+  args:
+  - ruby
+  - exe/dummy_cli_gem
+  - echo
+  - hello from dummy gem
+  stdout: 'hello from dummy gem
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2026-02-11T01:57:42-06:00'

data/fixtures/projects/dummy_cli_gem/fixtures/backspin/dummy_ls.yml

@@ -0,0 +1,18 @@
+---
+format_version: '4.1'
+first_recorded_at: '2026-02-11T01:57:42-06:00'
+recorded_at: '2026-02-11T01:57:42-06:00'
+record_count: 1
+snapshot:
+  command_type: Open3::Capture3
+  args:
+  - ruby
+  - exe/dummy_cli_gem
+  - list
+  - spec/fixtures/listing_target
+  stdout: 'alpha.txt
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2026-02-11T01:57:42-06:00'

data/fixtures/projects/dummy_cli_gem/lib/dummy_cli_gem/cli.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module DummyCliGem
+  module CLI
+    module_function
+
+    def run(argv, out: $stdout, err: $stderr)
+      command = argv.first
+
+      case command
+      when "echo"
+        text = argv[1]
+        return usage(err) if text.nil? || text.empty?
+
+        stdout, stderr, status = Open3.capture3("echo", text)
+      when "list"
+        target = argv[1] || "."
+        stdout, stderr, status = Open3.capture3("ls", "-1", target)
+      else
+        return usage(err)
+      end
+
+      out.print(stdout)
+      err.print(stderr)
+      status.exitstatus
+    end
+
+    def usage(err)
+      err.puts("usage: dummy_cli_gem echo <text> | dummy_cli_gem list <path>")
+      1
+    end
+  end
+end

data/fixtures/projects/dummy_cli_gem/lib/dummy_cli_gem/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DummyCliGem
+  VERSION = "0.1.0"
+end

data/fixtures/projects/dummy_cli_gem/lib/dummy_cli_gem.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "dummy_cli_gem/version"
+require "dummy_cli_gem/cli"
+
+module DummyCliGem
+end

data/fixtures/projects/dummy_cli_gem/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "4.0.0"

data/fixtures/projects/dummy_cli_gem/spec/dummy_cli_gem_backspin_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "DummyCliGem Backspin full-stack fixture" do
+  let(:project_root) { Pathname(__dir__).join("..").expand_path }
+
+  it "verifies echo command output from committed YAML" do
+    expect(BACKSPIN_DIR.join("dummy_echo.yml")).to exist
+
+    result = Backspin.run(
+      ["ruby", "exe/dummy_cli_gem", "echo", "hello from dummy gem"],
+      name: "dummy_echo"
+    )
+
+    expect(result).to be_verified
+    expect(result.actual.stdout).to eq("hello from dummy gem\n")
+    expect(result.actual.stderr).to eq("")
+    expect(result.actual.status).to eq(0)
+  end
+
+  it "verifies list command output from committed YAML" do
+    expect(BACKSPIN_DIR.join("dummy_ls.yml")).to exist
+
+    result = Backspin.run(
+      ["ruby", "exe/dummy_cli_gem", "list", "spec/fixtures/listing_target"],
+      name: "dummy_ls"
+    )
+
+    expect(result).to be_verified
+    expect(result.actual.stdout).to eq("alpha.txt\n")
+    expect(result.actual.stderr).to eq("")
+    expect(result.actual.status).to eq(0)
+  end
+
+  it "uses current Backspin record format for fixture YAML files" do
+    %w[dummy_echo dummy_ls].each do |record_name|
+      record_path = BACKSPIN_DIR.join("#{record_name}.yml")
+      expect(record_path).to exist
+
+      record_data = YAML.load_file(record_path)
+      expect(record_data["format_version"]).to eq("4.1")
+      expect(record_data["snapshot"]["command_type"]).to eq("Open3::Capture3")
+    end
+  end
+end

data/fixtures/projects/dummy_cli_gem/spec/fixtures/backspin/dummy_echo.yml

@@ -0,0 +1,18 @@
+---
+format_version: '4.1'
+first_recorded_at: '2026-02-11T07:43:21+00:00'
+recorded_at: '2026-02-11T07:43:21+00:00'
+record_count: 1
+snapshot:
+  command_type: Open3::Capture3
+  args:
+  - ruby
+  - exe/dummy_cli_gem
+  - echo
+  - hello from dummy gem
+  stdout: 'hello from dummy gem
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2026-02-11T07:43:21+00:00'

data/fixtures/projects/dummy_cli_gem/spec/fixtures/backspin/dummy_ls.yml

@@ -0,0 +1,18 @@
+---
+format_version: '4.1'
+first_recorded_at: '2026-02-11T07:43:21+00:00'
+recorded_at: '2026-02-11T07:43:21+00:00'
+record_count: 1
+snapshot:
+  command_type: Open3::Capture3
+  args:
+  - ruby
+  - exe/dummy_cli_gem
+  - list
+  - spec/fixtures/listing_target
+  stdout: 'alpha.txt
+
+    '
+  stderr: ''
+  status: 0
+  recorded_at: '2026-02-11T07:43:21+00:00'

data/fixtures/projects/dummy_cli_gem/spec/fixtures/listing_target/alpha.txt

@@ -0,0 +1 @@
+alpha fixture file

data/fixtures/projects/dummy_cli_gem/spec/spec_helper.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "pathname"
+require "yaml"
+require "backspin"
+require "dummy_cli_gem"
+
+BACKSPIN_DIR = Pathname(__dir__).join("fixtures", "backspin")
+
+Backspin.configure do |config|
+  config.backspin_dir = BACKSPIN_DIR
+  config.logger = nil
+end
+
+RSpec.configure do |config|
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |expectations|
+    expectations.syntax = :expect
+  end
+end

data/lib/backspin/configuration.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "logger"
 require "pathname"
 
 module Backspin
@@ -10,6 +11,8 @@ module Backspin
     attr_accessor :backspin_dir
     # Whether to raise an exception when verification fails in `run`/`capture` - defaults to true
     attr_accessor :raise_on_verification_failure
+    # Logger for Backspin diagnostics - defaults to WARN level, logfmt-lite format
+    attr_accessor :logger
     # Regex patterns to scrub from saved output
     attr_reader :credential_patterns
 
@@ -18,6 +21,7 @@ module Backspin
       @raise_on_verification_failure = true
       @credential_patterns = default_credential_patterns
       @backspin_dir = Pathname(Dir.pwd).join("fixtures", "backspin")
+      @logger = default_logger
     end
 
     def add_credential_pattern(pattern)
@@ -34,6 +38,15 @@ module Backspin
 
     private
 
+    def default_logger
+      logger = Logger.new($stdout)
+      logger.level = Logger::WARN
+      logger.formatter = proc { |severity, _time, _progname, msg|
+        "level=#{severity.downcase} lib=backspin #{msg}\n"
+      }
+      logger
+    end
+
     # Some default patterns for common credential types
     def default_credential_patterns
       [