Skip to content

Commit 026356b

Browse files
justin808justin808
authored
Implement core functionality for swap-shakacode-deps gem (#55)
Why Enable local development by swapping Shakacode gem dependencies to local paths or GitHub branches across projects. Summary Complete gem implementation with backup/restore, Gemfile/package.json modification, CLI interface, and comprehensive test coverage (42 tests). Key improvements - Automated backup/restore prevents data loss during swap operations - Security validation blocks path traversal and system directory access - Only updates actually-swapped gems during restore, not all supported Impact - Existing: No changes to demo projects, new standalone gem - New: Developers can swap dependencies with swap-shakacode-deps CLI Risks - Path validation must be maintained for security - Backup mechanism critical for safe file modifications
1 parent 299b382 commit 026356b

35 files changed

+3363
-0
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,3 +67,4 @@ commit_message.txt
6767
# Local development configuration
6868
.swap-deps.yml
6969
*.backup
70+
swap-shakacode-deps/.rspec_status

‎swap-shakacode-deps-implementation-plan.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# swap-shakacode-deps Implementation Plan
2+
3+
## Executive Summary
4+
5+
Create a globally installable Ruby gem `swap-shakacode-deps` that provides the dependency swapping functionality currently in `react_on_rails_demo_common`, making it available for use in any repository.
6+
7+
## Architecture Overview
8+
9+
### Package Type: Ruby Gem
10+
- **Rationale**: Ruby ecosystem provides better file manipulation, process management, and cross-platform compatibility
11+
- **Global Installation**: `gem install swap-shakacode-deps`
12+
- **Command**: `swap-shakacode-deps [options]`
13+
14+
## Core Features (Maintaining Full Parity)
15+
16+
1. **Local Path Swapping**
17+
- `--shakapacker PATH`
18+
- `--react-on-rails PATH`
19+
- `--cypress-on-rails PATH`
20+
21+
2. **GitHub Repository Swapping**
22+
- `--github user/repo#branch`
23+
- `--github user/repo@tag`
24+
25+
3. **Configuration File Support**
26+
- `.swap-deps.yml` in project root
27+
- `--apply` to use config file
28+
29+
4. **Backup & Restore**
30+
- Automatic backup creation
31+
- `--restore` to revert changes
32+
33+
5. **Build Management**
34+
- `--build` / `--skip-build`
35+
- `--watch` for auto-rebuild
36+
37+
6. **Watch Process Management**
38+
- `--list-watch`
39+
- `--kill-watch`
40+
41+
7. **Cache Management**
42+
- `--show-cache`
43+
- `--clean-cache [GEM]`
44+
45+
8. **Status Reporting**
46+
- `--status` to show current swaps
47+
48+
9. **Dry Run & Verbose Modes**
49+
- `--dry-run`
50+
- `--verbose`
51+
52+
## File Structure
53+
54+
```plaintext
55+
swap-shakacode-deps/
56+
├── bin/
57+
│ └── swap-shakacode-deps # Executable
58+
├── lib/
59+
│ ├── swap_shakacode_deps.rb # Main entry
60+
│ ├── swap_shakacode_deps/
61+
│ │ ├── version.rb
62+
│ │ ├── cli.rb # CLI parser
63+
│ │ ├── swapper.rb # Core swapping logic
64+
│ │ ├── gem_swapper.rb # Gemfile manipulation
65+
│ │ ├── npm_swapper.rb # package.json manipulation
66+
│ │ ├── github_handler.rb # GitHub repo management
67+
│ │ ├── cache_manager.rb # Cache operations
68+
│ │ ├── watch_manager.rb # Watch process management
69+
│ │ ├── backup_manager.rb # Backup/restore logic
70+
│ │ └── config_loader.rb # YAML config handling
71+
├── spec/ # Tests
72+
├── README.md
73+
├── CHANGELOG.md
74+
├── LICENSE
75+
├── Gemfile
76+
├── Rakefile
77+
└── swap-shakacode-deps.gemspec
78+
```
79+
80+
## Key Implementation Details
81+
82+
### 1. Context Detection
83+
The gem will detect project type by looking for:
84+
- `Gemfile` (Ruby project)
85+
- `package.json` (Node project)
86+
- `.swap-deps.yml` (Configuration file)
87+
88+
### 2. Multi-Project Support
89+
Unlike the current implementation that works with `demos/` directories, the global tool will:
90+
- Work in the current directory by default
91+
- Support `--path` option to specify target directory
92+
- Support `--recursive` to process subdirectories
93+
94+
### 3. Improved Error Handling
95+
- Clear error messages for missing dependencies
96+
- Validation before making changes
97+
- Rollback on partial failures
98+
99+
### 4. Platform Compatibility
100+
- macOS (primary)
101+
- Linux
102+
- Windows (WSL)
103+
104+
## Migration Strategy
105+
106+
### Phase 1: Gem Development
107+
1. Extract core logic from `demo_scripts`
108+
2. Remove demo-specific assumptions
109+
3. Generalize for any project structure
110+
111+
### Phase 2: Integration
112+
1. Create gem with full feature parity
113+
2. Test with various project types
114+
3. Publish to RubyGems
115+
116+
### Phase 3: Update react_on_rails_demo_common
117+
1. Add gem as dependency
118+
2. Create wrapper script that delegates to gem
119+
3. Maintain backward compatibility
120+
121+
## Installation & Usage
122+
123+
### Installation
124+
```bash
125+
# Global installation
126+
gem install swap-shakacode-deps
127+
128+
# Or add to Gemfile for project-specific use
129+
gem 'swap-shakacode-deps'
130+
```
131+
132+
### Basic Usage
133+
```bash
134+
# Swap to local shakapacker
135+
swap-shakacode-deps --shakapacker ~/dev/shakapacker
136+
137+
# Use GitHub branch
138+
swap-shakacode-deps --github shakacode/react_on_rails#feature-x
139+
140+
# Apply from config
141+
swap-shakacode-deps --apply
142+
143+
# Restore originals
144+
swap-shakacode-deps --restore
145+
```
146+
147+
## Configuration File Format
148+
149+
```yaml
150+
# .swap-deps.yml
151+
gems:
152+
shakapacker: ~/dev/shakapacker
153+
react_on_rails: ~/dev/react_on_rails
154+
155+
github:
156+
shakapacker:
157+
repo: shakacode/shakapacker
158+
branch: main
159+
```
160+
161+
## Benefits Over Current Implementation
162+
163+
1. **Global Availability**: Use in any project, not just react_on_rails_demo_common
164+
2. **Simplified Maintenance**: Single source of truth for the tool
165+
3. **Better Testing**: Isolated gem with its own test suite
166+
4. **Version Management**: Semantic versioning for the tool
167+
5. **Documentation**: Dedicated docs for the tool
168+
6. **Community Contribution**: Easier for others to contribute
169+
170+
## Timeline Estimate
171+
172+
- **Week 1**: Core gem structure and logic extraction
173+
- **Week 2**: Feature implementation and testing
174+
- **Week 3**: Documentation and publishing
175+
- **Week 4**: Integration with react_on_rails_demo_common
176+
177+
## Success Criteria
178+
179+
1. All current swap-deps features work globally
180+
2. No breaking changes for existing users
181+
3. Clear upgrade path
182+
4. Comprehensive documentation
183+
5. Published to RubyGems
184+
6. Works with any Shakacode project

‎swap-shakacode-deps/.gitignore‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
*.gem
2+
*.rbc
3+
/.config
4+
/coverage/
5+
/InstalledFiles
6+
/pkg/
7+
/spec/reports/
8+
/spec/examples.txt
9+
/test/tmp/
10+
/test/version_tmp/
11+
/tmp/
12+
13+
# Used by dotenv library to load environment variables
14+
# .env
15+
16+
# Ignore Byebug command history file
17+
.byebug_history
18+
19+
## Specific to RubyMotion:
20+
.dat*
21+
.repl_history
22+
build/
23+
*.bridgesupport
24+
build-iPhoneOS/
25+
build-iPhoneSimulator/
26+
27+
## Specific to RubyMotion (use of CocoaPods):
28+
#
29+
# We recommend against adding the Pods directory to your .gitignore. However
30+
# you should judge for yourself, the pros and cons are mentioned at:
31+
# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
32+
# vendor/Pods/
33+
34+
## Documentation cache and generated files:
35+
/.yardoc/
36+
/_yardoc/
37+
/doc/
38+
/rdoc/
39+
40+
## Environment normalization:
41+
/.bundle/
42+
/vendor/bundle
43+
/lib/bundler/man/
44+
45+
# for a library or gem, you might want to ignore these files since the code is
46+
# intended to run in multiple environments; otherwise, check them in:
47+
# Gemfile.lock
48+
# .ruby-version
49+
# .ruby-gemset
50+
51+
# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
52+
.rvmrc
53+
54+
# Used by RuboCop. Remote config files pulled in from inherit_from directive.
55+
# .rubocop-https?--*
56+
57+
# RSpec artifacts
58+
/spec/support/fixtures/
59+
/spec/tmp/
60+
61+
# Ignore IDE files
62+
.idea/
63+
.vscode/
64+
*.swp
65+
*.swo
66+
*~
67+
68+
# OS files
69+
.DS_Store
70+
Thumbs.db

‎swap-shakacode-deps/.rspec‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
--require spec_helper
2+
--color
3+
--format documentation

‎swap-shakacode-deps/.rubocop.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
require:
2+
- rubocop-rspec
3+
4+
AllCops:
5+
TargetRubyVersion: 2.7
6+
NewCops: enable
7+
Exclude:
8+
- 'bin/console'
9+
- 'vendor/**/*'
10+
- 'tmp/**/*'
11+
12+
Style/Documentation:
13+
Enabled: false
14+
15+
Metrics/MethodLength:
16+
Max: 20
17+
18+
Metrics/ClassLength:
19+
Max: 150
20+
21+
Metrics/BlockLength:
22+
Exclude:
23+
- 'spec/**/*'
24+
- '*.gemspec'
25+
26+
RSpec/ExampleLength:
27+
Max: 15
28+
29+
RSpec/MultipleExpectations:
30+
Max: 5

‎swap-shakacode-deps/.swap-deps.yml.example‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Example configuration file for swap-shakacode-deps
2+
# Copy this file to .swap-deps.yml and customize for your environment
3+
# The .swap-deps.yml file should be git-ignored for local development
4+
5+
# Local gem paths
6+
# These paths will be used when running: swap-shakacode-deps --apply
7+
gems:
8+
# Path to your local shakapacker repository
9+
shakapacker: ~/dev/shakapacker
10+
11+
# Path to your local react_on_rails repository
12+
react_on_rails: ~/dev/react_on_rails
13+
14+
# Path to your local cypress-on-rails repository (if used)
15+
# cypress-on-rails: ~/dev/cypress-on-rails
16+
17+
# GitHub repositories
18+
# Use these for testing specific branches or tags
19+
# Uncomment and modify as needed
20+
# github:
21+
# shakapacker:
22+
# repo: shakacode/shakapacker
23+
# branch: main # or use a specific branch like 'feature-xyz'
24+
#
25+
# react_on_rails:
26+
# repo: shakacode/react_on_rails
27+
# branch: main # or use a tag with ref_type: tag
28+
#
29+
# # Example using a tag instead of branch
30+
# # cypress-on-rails:
31+
# # repo: shakacode/cypress-on-rails
32+
# # branch: v1.0.0
33+
# # ref_type: tag
34+
35+
# Note: You can mix local paths and GitHub repos
36+
# Local paths take precedence when both are specified

‎swap-shakacode-deps/CHANGELOG.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Changelog
2+
3+
All notable changes to swap-shakacode-deps will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
- Initial release of swap-shakacode-deps
12+
- Support for swapping shakapacker, react_on_rails, and cypress-on-rails gems
13+
- Local path swapping with `--shakapacker`, `--react-on-rails`, `--cypress-on-rails` options
14+
- GitHub repository support with branches and tags via `--github` option
15+
- Configuration file support via `.swap-deps.yml` and `--apply` option
16+
- Backup and restore functionality with `--restore` option
17+
- NPM package building with `--build` and `--skip-build` options
18+
- Watch mode for auto-rebuilding with `--watch` option
19+
- Watch process management with `--list-watch` and `--kill-watch` options
20+
- Cache management with `--show-cache` and `--clean-cache` options
21+
- Status reporting with `--status` option
22+
- Dry-run mode with `--dry-run` option
23+
- Verbose output with `--verbose` option
24+
- Support for processing specific directories with `--path` option
25+
- Recursive directory processing with `--recursive` option
26+
- Comprehensive error handling and validation
27+
- Automatic backup file creation
28+
- File locking for atomic operations
29+
- Cross-platform compatibility (macOS, Linux, Windows via WSL)
30+
31+
[Unreleased]: https://github.com/shakacode/swap-shakacode-deps

‎swap-shakacode-deps/Gemfile‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# frozen_string_literal: true
2+
3+
source 'https://rubygems.org'
4+
5+
# Specify gem dependencies in swap-shakacode-deps.gemspec
6+
gemspec

0 commit comments

Comments
 (0)