backspin 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: a1f998c2134e48ab2c3eee38e86e64ec1a4325ba8d81dca4e7c8e042513dde13
4
- data.tar.gz: 43aa6c53243fce4cab5911a6635944f25cb339ee5c58dbeb421f15bd30960a7a
3
+ metadata.gz: 9afcbf90256cbfd84f6b9694544282dc593fc715d9886a9e3a9ba54e064410fc
4
+ data.tar.gz: c3d6e95547f27364b4108b5f75641ed88a9e153f0e4ccdbed3d276e82dd5f99b
5
5
  SHA512:
6
- metadata.gz: 15ded2144dfe4db263a8cd54f449aaf591d6f90da25675e77de3a22b7dd0384d8d226f44ed7a7ccfd96e7edb5eae72ecdf95ae6152b38d288153a001b085cb71
7
- data.tar.gz: 0bb9f49eb95c197403e8a7d7869cd5b33bb45323c6d9461e07af23df3f24deaa87af5571fd8475759eff5b87d2dc4de94ff3ff898a71e8cc3154e1b1e874122e
6
+ metadata.gz: 2c7c36cee5518f0944896c04c96d36ae134d56928510ee01aef646a2eb0c036c723ab65aff64c6726751ce6b4c406de90f486e4da5bd3242344fd23d8e7792f1
7
+ data.tar.gz: 116e28fadefdc8651f648f25f0da4c347d86127448a34e0ca20a244f6bb0e7f101e140052e0f0e9029ec1693b40b6363ab3d7db6a0b7c2a0ab9252976ae64c33
@@ -0,0 +1,29 @@
1
+ # See: https://circleci.com/docs/configuration-reference
2
+ version: 2.1
3
+
4
+ orbs:
5
+ # See: https://circleci.com/developer/orbs/orb/circleci/ruby
6
+ ruby: circleci/ruby@2.5.3
7
+
8
+ jobs:
9
+ build:
10
+ parameters:
11
+ ruby-version:
12
+ type: string
13
+ docker:
14
+ - image: cimg/ruby:<< parameters.ruby-version >>
15
+
16
+ steps:
17
+ - checkout
18
+ - ruby/install-deps
19
+ - run:
20
+ name: Run specs and lint
21
+ command: bundle exec rake
22
+
23
+ workflows:
24
+ build:
25
+ jobs:
26
+ - build:
27
+ matrix:
28
+ parameters:
29
+ ruby-version: ["3.2", "3.3", "3.4"]
data/.gitignore CHANGED
@@ -2,18 +2,15 @@
2
2
  /.yardoc
3
3
  /_yardoc/
4
4
  /coverage/
5
- /doc/
6
5
  /pkg/
7
6
  /spec/reports/
8
7
  /tmp/
9
8
  /.claude
10
9
  /.cursor
11
10
 
11
+ /backspin*.gem
12
12
  # rspec failure tracking
13
13
  .rspec_status
14
14
 
15
15
  # Backspin cassettes
16
16
  /tmp/backspin/
17
-
18
- # Bundler
19
- Gemfile.lock
data/CHANGELOG.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.3.0] - 2025-06-05
4
+ - Scrub credentials from command arguments
3
5
 
4
6
  ## [0.2.0] - 2025-06-05
5
7
  - First public release of Backspin, extracteed from `name-TBD` CLI tool
data/CLAUDE.md CHANGED
@@ -78,7 +78,6 @@ bin/rake standard # Run Standard Ruby linter
78
78
  ### Debugging Tests
79
79
  - Records are saved to `spec/backspin_data/` by default
80
80
  - Check YAML files to see recorded command outputs
81
- - Use `VERBOSE=1` for additional output during tests
82
81
 
83
82
  ### Updating Credential Patterns
84
83
  - Add patterns to `DEFAULT_CREDENTIAL_PATTERNS` in `lib/backspin.rb`
data/CONTRIBUTING.md ADDED
@@ -0,0 +1,224 @@
1
+ # Contributing to Backspin
2
+
3
+ Thank you for your interest in contributing to Backspin! This guide will help you get started with development and walk you through the contribution process.
4
+
5
+ Note that Backspin is in early development and the API _will_ change before stabilizing at 1.0.
6
+
7
+ ## Table of Contents
8
+
9
+ - [Getting Started](#getting-started)
10
+ - [Development Setup](#development-setup)
11
+ - [Making Changes](#making-changes)
12
+ - [Testing](#testing)
13
+ - [Submitting Changes](#submitting-changes)
14
+ - [Code Style](#code-style)
15
+ - [Reporting Issues](#reporting-issues)
16
+ - [Feature Requests](#feature-requests)
17
+
18
+ ## Getting Started
19
+
20
+ 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.
21
+
22
+ ### Prerequisites
23
+
24
+ - Ruby 3.2, 3.3, or 3.4
25
+ - Bundler
26
+ - Git
27
+
28
+ ## Development Setup
29
+
30
+ 1. Fork and clone the repository:
31
+ ```bash
32
+ git clone https://github.com/rsanheim/backspin.git
33
+ cd backspin
34
+ ```
35
+
36
+ 2. Run the setup script:
37
+ ```bash
38
+ bin/setup
39
+ ```
40
+
41
+ 3. Run the full build (specs & standardrb linting) to ensure everything is working:
42
+ ```bash
43
+ bin/rake spec
44
+ ```
45
+
46
+ ## Making Changes
47
+
48
+ ### Development Workflow
49
+
50
+ 1. Create a feature branch:
51
+ ```bash
52
+ git checkout -b feature/your-feature-name
53
+ ```
54
+
55
+ 2. Make your changes following the project conventions
56
+
57
+ 3. Run tests frequently:
58
+ ```bash
59
+ bin/rake spec
60
+ ```
61
+
62
+ 4. Run the linter:
63
+ ```bash
64
+ bin/rake standard
65
+ ```
66
+
67
+ 5. Commit your changes with clear, descriptive messages
68
+
69
+ ### Architecture Overview
70
+
71
+ **Core Components:**
72
+
73
+ - **Backspin Module** (`lib/backspin.rb`)
74
+ - Main API: `call`, `verify`, `verify!`, `use_record`
75
+ - Credential scrubbing logic
76
+ - Configuration management
77
+
78
+ - **Command Class** (`lib/backspin/command.rb`)
79
+ - Represents a single CLI execution
80
+ - Stores: args, stdout, stderr, status, recorded_at, etc
81
+
82
+ - **Record Class** (`lib/backspin/record.rb`)
83
+ - Manages YAML record files
84
+ - Handles recording/playback sequencing
85
+
86
+ ### Common Development Tasks
87
+
88
+ #### Adding New Features
89
+
90
+ 1. Write integration tests in `spec/backspin/`
91
+ 2. Implement in appropriate module (usually `lib/backspin.rb`)
92
+ 3. Update README.md if adding public API
93
+ 4. Run the the full build
94
+
95
+ #### Updating Credential Patterns
96
+
97
+ - Add patterns to `DEFAULT_CREDENTIAL_PATTERNS` in `lib/backspin.rb`
98
+ - Test with appropriate fixtures in specs
99
+
100
+ #### Debugging Tests
101
+
102
+ - Records are saved to `spec/backspin_data/` by default
103
+ - Check YAML files to see recorded command outputs
104
+
105
+ ## Testing
106
+
107
+ ### Running Tests
108
+
109
+ ```bash
110
+ # Run all tests
111
+ bin/rake spec
112
+
113
+ # Run specific test file
114
+ bundle exec rspec spec/backspin/record_spec.rb
115
+
116
+ # Run specific test
117
+ bundle exec rspec spec/backspin/record_spec.rb:42
118
+ ```
119
+
120
+ ### Writing Tests
121
+
122
+ Backspin uses integration-focused tests that exercise the full stack. When writing tests:
123
+
124
+ - Keep specs self-contained with their own setup, expectations, and cleanup
125
+ - Avoid shared contexts or helpers that hide important test details
126
+ - Use real shell commands (`echo`, `date`, etc.) for testing
127
+ - Ensure configuration is reset between tests to avoid side effects
128
+ - Verify new or updated test records in `spec/backspin_data/`
129
+
130
+ Example test structure:
131
+
132
+ ```ruby
133
+ RSpec.describe "Feature name" do
134
+ it "does something specific" do
135
+ # Setup
136
+ record_name = "my_test_record"
137
+
138
+ # Exercise
139
+ result = Backspin.call(record_name) do
140
+ Open3.capture3("echo", "hello")
141
+ end
142
+
143
+ # Verify
144
+ expect(result.stdout).to eq("hello\n")
145
+ end
146
+ end
147
+ ```
148
+
149
+ ## Submitting Changes
150
+
151
+ ### Pull Request Process
152
+
153
+ 1. Ensure all tests pass
154
+ 2. Update documentation if needed
155
+ 3. Add entries to CHANGELOG.md following the existing format
156
+ 4. Push your branch and create a pull request
157
+ 5. Provide a clear description of your changes
158
+ 6. Link any related issues
159
+
160
+ ### Pull Request Guidelines
161
+
162
+ - Keep changes focused and atomic
163
+ - Include tests for new functionality
164
+ - Maintain backward compatibility when possible
165
+ - Update examples in README.md if changing public APIs
166
+ - Ensure CI passes (tests against Ruby 3.2, 3.3, and 3.4)
167
+
168
+ ## Code Style
169
+
170
+ Backspin uses [Standard Ruby](https://github.com/standardrb/standard) for code formatting. Run the linter before committing:
171
+
172
+ ```bash
173
+ bin/rake standard
174
+ ```
175
+
176
+ To automatically fix issues:
177
+
178
+ ```bash
179
+ bin/rake standard:fix
180
+ ```
181
+
182
+ ## Reporting Issues
183
+
184
+ ### Bug Reports
185
+
186
+ When reporting bugs, please include *full logs* including:
187
+
188
+ 1. Ruby version (`ruby -v`) and ruby version manager info
189
+ 2. Backspin version
190
+ 3. Minimal reproduction code
191
+ 4. Expected behavior vs actual behavior
192
+ 5. Full error messages and stack traces
193
+ 6. Relevant YAML record files (sanitized of sensitive data)
194
+
195
+ ### Security Issues
196
+
197
+ For security vulnerabilities, please email the maintainers directly rather than opening a public issue.
198
+
199
+ ## Feature Requests
200
+
201
+ We welcome feature requests! When proposing new features:
202
+
203
+ 1. Check existing issues to avoid duplicates
204
+ 2. Describe the use case and motivation
205
+ 3. Provide code examples of how the feature would work
206
+ 4. Consider backward compatibility
207
+ 5. Be open to discussion and alternative approaches
208
+
209
+ ## Additional Resources
210
+
211
+ - [Project README](README.md)
212
+ - [CLAUDE.md](CLAUDE.md) - AI assistant guidance
213
+ - [RSpec Documentation](https://rspec.info/)
214
+ - [Standardrb linting](https://github.com/standardrb/standard)
215
+
216
+ ## Questions?
217
+
218
+ If you have questions about contributing, feel free to:
219
+
220
+ - Open an issue for discussion
221
+ - Check existing issues and pull requests
222
+ - Review the test suite for examples
223
+
224
+ Thank you for contributing to Backspin!
data/Gemfile.lock ADDED
@@ -0,0 +1,87 @@
1
+ PATH
2
+ remote: .
3
+ specs:
4
+ backspin (0.3.0)
5
+ ostruct (~> 0.5.0)
6
+ rspec-mocks (~> 3.0)
7
+
8
+ GEM
9
+ remote: https://rubygems.org/
10
+ specs:
11
+ ast (2.4.3)
12
+ diff-lcs (1.6.2)
13
+ json (2.12.2)
14
+ language_server-protocol (3.17.0.5)
15
+ lint_roller (1.1.0)
16
+ ostruct (0.5.5)
17
+ parallel (1.27.0)
18
+ parser (3.3.8.0)
19
+ ast (~> 2.4.1)
20
+ racc
21
+ prism (1.4.0)
22
+ racc (1.8.1)
23
+ rainbow (3.1.1)
24
+ rake (13.3.0)
25
+ regexp_parser (2.10.0)
26
+ rspec (3.13.1)
27
+ rspec-core (~> 3.13.0)
28
+ rspec-expectations (~> 3.13.0)
29
+ rspec-mocks (~> 3.13.0)
30
+ rspec-core (3.13.4)
31
+ rspec-support (~> 3.13.0)
32
+ rspec-expectations (3.13.5)
33
+ diff-lcs (>= 1.2.0, < 2.0)
34
+ rspec-support (~> 3.13.0)
35
+ rspec-mocks (3.13.5)
36
+ diff-lcs (>= 1.2.0, < 2.0)
37
+ rspec-support (~> 3.13.0)
38
+ rspec-support (3.13.4)
39
+ rubocop (1.75.8)
40
+ json (~> 2.3)
41
+ language_server-protocol (~> 3.17.0.2)
42
+ lint_roller (~> 1.1.0)
43
+ parallel (~> 1.10)
44
+ parser (>= 3.3.0.2)
45
+ rainbow (>= 2.2.2, < 4.0)
46
+ regexp_parser (>= 2.9.3, < 3.0)
47
+ rubocop-ast (>= 1.44.0, < 2.0)
48
+ ruby-progressbar (~> 1.7)
49
+ unicode-display_width (>= 2.4.0, < 4.0)
50
+ rubocop-ast (1.44.1)
51
+ parser (>= 3.3.7.2)
52
+ prism (~> 1.4)
53
+ rubocop-performance (1.25.0)
54
+ lint_roller (~> 1.1)
55
+ rubocop (>= 1.75.0, < 2.0)
56
+ rubocop-ast (>= 1.38.0, < 2.0)
57
+ ruby-progressbar (1.13.0)
58
+ standard (1.50.0)
59
+ language_server-protocol (~> 3.17.0.2)
60
+ lint_roller (~> 1.0)
61
+ rubocop (~> 1.75.5)
62
+ standard-custom (~> 1.0.0)
63
+ standard-performance (~> 1.8)
64
+ standard-custom (1.0.2)
65
+ lint_roller (~> 1.0)
66
+ rubocop (~> 1.50)
67
+ standard-performance (1.8.0)
68
+ lint_roller (~> 1.1)
69
+ rubocop-performance (~> 1.25.0)
70
+ timecop (0.9.10)
71
+ unicode-display_width (3.1.4)
72
+ unicode-emoji (~> 4.0, >= 4.0.4)
73
+ unicode-emoji (4.0.4)
74
+
75
+ PLATFORMS
76
+ arm64-darwin-24
77
+ ruby
78
+
79
+ DEPENDENCIES
80
+ backspin!
81
+ rake (~> 13.0)
82
+ rspec (~> 3.0)
83
+ standard (~> 1.0)
84
+ timecop (~> 0.9)
85
+
86
+ BUNDLED WITH
87
+ 2.6.9
data/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # Backspin
1
+ # Backspin   [![Gem Version](https://badge.fury.io/rb/backspin.svg)](https://badge.fury.io/rb/backspin) [![CircleCI](https://dl.circleci.com/status-badge/img/gh/rsanheim/backspin/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/rsanheim/backspin/tree/main)
2
2
 
3
3
  Backspin records and replays CLI interactions in Ruby for easy snapshot testing of command-line interfaces. Currently supports `Open3.capture3` and `system` and requires `rspec-mocks`. More system calls and flexible test integration are welcome - PRs welcome!
4
4
 
data/backspin.gemspec CHANGED
@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
10
10
  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."
11
11
  spec.homepage = "https://github.com/rsanheim/backspin"
12
12
  spec.license = "MIT"
13
- spec.required_ruby_version = Gem::Requirement.new(">= 2.5.0")
13
+ spec.required_ruby_version = Gem::Requirement.new(">= 3.1.0")
14
14
 
15
15
  spec.metadata["homepage_uri"] = spec.homepage
16
16
  spec.metadata["source_code_uri"] = spec.homepage
@@ -25,5 +25,5 @@ Gem::Specification.new do |spec|
25
25
  spec.require_paths = ["lib"]
26
26
 
27
27
  spec.add_dependency "rspec-mocks", "~> 3.0"
28
- spec.add_dependency "ostruct"
28
+ spec.add_dependency "ostruct", "~> 0.5.0"
29
29
  end
data/bin/setup CHANGED
@@ -3,6 +3,4 @@ set -euo pipefail
3
3
  IFS=$'\n\t'
4
4
  set -vx
5
5
 
6
- bundle install
7
-
8
- # Do any other automated setup that you need to do here
6
+ bundle install
@@ -15,7 +15,7 @@ module Backspin
15
15
  def to_h(filter: nil)
16
16
  data = {
17
17
  "command_type" => @method_class.name,
18
- "args" => @args,
18
+ "args" => scrub_args(@args),
19
19
  "stdout" => Backspin.scrub_text(@stdout),
20
20
  "stderr" => Backspin.scrub_text(@stderr),
21
21
  "status" => @status,
@@ -52,6 +52,24 @@ module Backspin
52
52
  recorded_at: data["recorded_at"]
53
53
  )
54
54
  end
55
+
56
+ private
57
+
58
+ def scrub_args(args)
59
+ return args unless Backspin.configuration.scrub_credentials && args
60
+
61
+ args.map do |arg|
62
+ if arg.is_a?(String)
63
+ Backspin.scrub_text(arg)
64
+ elsif arg.is_a?(Array)
65
+ scrub_args(arg)
66
+ elsif arg.is_a?(Hash)
67
+ arg.transform_values { |v| v.is_a?(String) ? Backspin.scrub_text(v) : v }
68
+ else
69
+ arg
70
+ end
71
+ end
72
+ end
55
73
  end
56
74
  end
57
75
 
@@ -1,3 +1,3 @@
1
1
  module Backspin
2
- VERSION = "0.2.1"
2
+ VERSION = "0.3.0"
3
3
  end
data/lib/backspin.rb CHANGED
@@ -43,6 +43,7 @@ module Backspin
43
43
 
44
44
  private
45
45
 
46
+ # Some default patterns for common credential types
46
47
  def default_credential_patterns
47
48
  [
48
49
  # AWS credentials
@@ -58,7 +59,9 @@ module Backspin
58
59
  # Generic patterns
59
60
  /api[_-]?key\s*[:=]\s*["']?([A-Za-z0-9\-_]{20,})["']?/i, # Generic API keys
60
61
  /auth[_-]?token\s*[:=]\s*["']?([A-Za-z0-9\-_]{20,})["']?/i, # Auth tokens
62
+ /Bearer\s+([A-Za-z0-9\-_]+)/, # Bearer tokens
61
63
  /password\s*[:=]\s*["']?([^"'\s]{8,})["']?/i, # Passwords
64
+ /-p([^"'\s]{8,})/, # MySQL-style password args
62
65
  /secret\s*[:=]\s*["']?([A-Za-z0-9\-_]{20,})["']?/i # Generic secrets
63
66
  ]
64
67
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: backspin
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.1
4
+ version: 0.3.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Rob Sanheim
@@ -27,16 +27,16 @@ dependencies:
27
27
  name: ostruct
28
28
  requirement: !ruby/object:Gem::Requirement
29
29
  requirements:
30
- - - ">="
30
+ - - "~>"
31
31
  - !ruby/object:Gem::Version
32
- version: '0'
32
+ version: 0.5.0
33
33
  type: :runtime
34
34
  prerelease: false
35
35
  version_requirements: !ruby/object:Gem::Requirement
36
36
  requirements:
37
- - - ">="
37
+ - - "~>"
38
38
  - !ruby/object:Gem::Version
39
- version: '0'
39
+ version: 0.5.0
40
40
  description: Backspin is a Ruby library for characterization testing of command-line
41
41
  interfaces. Inspired by VCR's cassette-based approach, it records and replays CLI
42
42
  interactions to make testing faster and more deterministic.
@@ -47,12 +47,15 @@ executables:
47
47
  extensions: []
48
48
  extra_rdoc_files: []
49
49
  files:
50
+ - ".circleci/config.yml"
50
51
  - ".gitignore"
51
52
  - ".rspec"
52
53
  - ".standard.yml"
53
54
  - CHANGELOG.md
54
55
  - CLAUDE.md
56
+ - CONTRIBUTING.md
55
57
  - Gemfile
58
+ - Gemfile.lock
56
59
  - LICENSE.txt
57
60
  - README.md
58
61
  - Rakefile
@@ -77,14 +80,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
77
80
  requirements:
78
81
  - - ">="
79
82
  - !ruby/object:Gem::Version
80
- version: 2.5.0
83
+ version: 3.1.0
81
84
  required_rubygems_version: !ruby/object:Gem::Requirement
82
85
  requirements:
83
86
  - - ">="
84
87
  - !ruby/object:Gem::Version
85
88
  version: '0'
86
89
  requirements: []
87
- rubygems_version: 3.6.7
90
+ rubygems_version: 3.6.9
88
91
  specification_version: 4
89
92
  summary: Record and replay CLI interactions for testing
90
93
  test_files: []