Create swap-shakacode-deps gem structure and documentation

swap-shakacode-deps-implementation-plan.md

@@ -0,0 +1,184 @@
+# swap-shakacode-deps Implementation Plan
+
+## Executive Summary
+
+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.
+
+## Architecture Overview
+
+### Package Type: Ruby Gem
+- **Rationale**: Ruby ecosystem provides better file manipulation, process management, and cross-platform compatibility
+- **Global Installation**: `gem install swap-shakacode-deps`
+- **Command**: `swap-shakacode-deps [options]`
+
+## Core Features (Maintaining Full Parity)
+
+1. **Local Path Swapping**
+   - `--shakapacker PATH`
+   - `--react-on-rails PATH`
+   - `--cypress-on-rails PATH`
+
+2. **GitHub Repository Swapping**
+   - `--github user/repo#branch`
+   - `--github user/repo@tag`
+
+3. **Configuration File Support**
+   - `.swap-deps.yml` in project root
+   - `--apply` to use config file
+
+4. **Backup & Restore**
+   - Automatic backup creation
+   - `--restore` to revert changes
+
+5. **Build Management**
+   - `--build` / `--skip-build`
+   - `--watch` for auto-rebuild
+
+6. **Watch Process Management**
+   - `--list-watch`
+   - `--kill-watch`
+
+7. **Cache Management**
+   - `--show-cache`
+   - `--clean-cache [GEM]`
+
+8. **Status Reporting**
+   - `--status` to show current swaps
+
+9. **Dry Run & Verbose Modes**
+   - `--dry-run`
+   - `--verbose`
+
+## File Structure
+
+```
+swap-shakacode-deps/
+├── bin/
+│   └── swap-shakacode-deps         # Executable
+├── lib/
+│   ├── swap_shakacode_deps.rb      # Main entry
+│   ├── swap_shakacode_deps/
+│   │   ├── version.rb
+│   │   ├── cli.rb                  # CLI parser
+│   │   ├── swapper.rb              # Core swapping logic
+│   │   ├── gem_swapper.rb          # Gemfile manipulation
+│   │   ├── npm_swapper.rb          # package.json manipulation
+│   │   ├── github_handler.rb       # GitHub repo management
+│   │   ├── cache_manager.rb        # Cache operations
+│   │   ├── watch_manager.rb        # Watch process management
+│   │   ├── backup_manager.rb       # Backup/restore logic
+│   │   └── config_loader.rb        # YAML config handling
+├── spec/                            # Tests
+├── README.md
+├── CHANGELOG.md
+├── LICENSE
+├── Gemfile
+├── Rakefile
+└── swap-shakacode-deps.gemspec
+```
+
+## Key Implementation Details
+
+### 1. Context Detection
+The gem will detect project type by looking for:
+- `Gemfile` (Ruby project)
+- `package.json` (Node project)
+- `.swap-deps.yml` (Configuration file)
+
+### 2. Multi-Project Support
+Unlike the current implementation that works with `demos/` directories, the global tool will:
+- Work in the current directory by default
+- Support `--path` option to specify target directory
+- Support `--recursive` to process subdirectories
+
+### 3. Improved Error Handling
+- Clear error messages for missing dependencies
+- Validation before making changes
+- Rollback on partial failures
+
+### 4. Platform Compatibility
+- macOS (primary)
+- Linux
+- Windows (WSL)
+
+## Migration Strategy
+
+### Phase 1: Gem Development
+1. Extract core logic from `demo_scripts`
+2. Remove demo-specific assumptions
+3. Generalize for any project structure
+
+### Phase 2: Integration
+1. Create gem with full feature parity
+2. Test with various project types
+3. Publish to RubyGems
+
+### Phase 3: Update react_on_rails_demo_common
+1. Add gem as dependency
+2. Create wrapper script that delegates to gem
+3. Maintain backward compatibility
+
+## Installation & Usage
+
+### Installation
+```bash
+# Global installation
+gem install swap-shakacode-deps
+
+# Or add to Gemfile for project-specific use
+gem 'swap-shakacode-deps'
+```
+
+### Basic Usage
+```bash
+# Swap to local shakapacker
+swap-shakacode-deps --shakapacker ~/dev/shakapacker
+
+# Use GitHub branch
+swap-shakacode-deps --github shakacode/react_on_rails#feature-x
+
+# Apply from config
+swap-shakacode-deps --apply
+
+# Restore originals
+swap-shakacode-deps --restore
+```
+
+## Configuration File Format
+
+```yaml
+# .swap-deps.yml
+gems:
+  shakapacker: ~/dev/shakapacker
+  react_on_rails: ~/dev/react_on_rails
+
+github:
+  shakapacker:
+    repo: shakacode/shakapacker
+    branch: main
+```
+
+## Benefits Over Current Implementation
+
+1. **Global Availability**: Use in any project, not just react_on_rails_demo_common
+2. **Simplified Maintenance**: Single source of truth for the tool
+3. **Better Testing**: Isolated gem with its own test suite
+4. **Version Management**: Semantic versioning for the tool
+5. **Documentation**: Dedicated docs for the tool
+6. **Community Contribution**: Easier for others to contribute
+
+## Timeline Estimate
+
+- **Week 1**: Core gem structure and logic extraction
+- **Week 2**: Feature implementation and testing
+- **Week 3**: Documentation and publishing
+- **Week 4**: Integration with react_on_rails_demo_common
+
+## Success Criteria
+
+1. All current swap-deps features work globally
+2. No breaking changes for existing users
+3. Clear upgrade path
+4. Comprehensive documentation
+5. Published to RubyGems
+6. Works with any Shakacode project

swap-shakacode-deps/.gitignore

@@ -0,0 +1,70 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables
+# .env
+
+# Ignore Byebug command history file
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*
+
+# RSpec artifacts
+/spec/support/fixtures/
+/spec/tmp/
+
+# Ignore IDE files
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db

swap-shakacode-deps/.rubocop.yml

@@ -0,0 +1,30 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 2.7
+  NewCops: enable
+  Exclude:
+    - 'bin/console'
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+RSpec/ExampleLength:
+  Max: 15
+
+RSpec/MultipleExpectations:
+  Max: 5

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

@@ -0,0 +1,36 @@
+# Example configuration file for swap-shakacode-deps
+# Copy this file to .swap-deps.yml and customize for your environment
+# The .swap-deps.yml file should be git-ignored for local development
+
+# Local gem paths
+# These paths will be used when running: swap-shakacode-deps --apply
+gems:
+  # Path to your local shakapacker repository
+  shakapacker: ~/dev/shakapacker
+
+  # Path to your local react_on_rails repository
+  react_on_rails: ~/dev/react_on_rails
+
+  # Path to your local cypress-on-rails repository (if used)
+  # cypress-on-rails: ~/dev/cypress-on-rails
+
+# GitHub repositories
+# Use these for testing specific branches or tags
+# Uncomment and modify as needed
+# github:
+#   shakapacker:
+#     repo: shakacode/shakapacker
+#     branch: main  # or use a specific branch like 'feature-xyz'
+#
+#   react_on_rails:
+#     repo: shakacode/react_on_rails
+#     branch: main  # or use a tag with ref_type: tag
+#
+#   # Example using a tag instead of branch
+#   # cypress-on-rails:
+#   #   repo: shakacode/cypress-on-rails
+#   #   branch: v1.0.0
+#   #   ref_type: tag
+
+# Note: You can mix local paths and GitHub repos
+# Local paths take precedence when both are specified

swap-shakacode-deps/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to swap-shakacode-deps will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial release of swap-shakacode-deps
+- Support for swapping shakapacker, react_on_rails, and cypress-on-rails gems
+- Local path swapping with `--shakapacker`, `--react-on-rails`, `--cypress-on-rails` options
+- GitHub repository support with branches and tags via `--github` option
+- Configuration file support via `.swap-deps.yml` and `--apply` option
+- Backup and restore functionality with `--restore` option
+- NPM package building with `--build` and `--skip-build` options
+- Watch mode for auto-rebuilding with `--watch` option
+- Watch process management with `--list-watch` and `--kill-watch` options
+- Cache management with `--show-cache` and `--clean-cache` options
+- Status reporting with `--status` option
+- Dry-run mode with `--dry-run` option
+- Verbose output with `--verbose` option
+- Support for processing specific directories with `--path` option
+- Recursive directory processing with `--recursive` option
+- Comprehensive error handling and validation
+- Automatic backup file creation
+- File locking for atomic operations
+- Cross-platform compatibility (macOS, Linux, Windows via WSL)
+
+[Unreleased]: https://github.com/shakacode/swap-shakacode-deps

swap-shakacode-deps/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify gem dependencies in swap-shakacode-deps.gemspec
+gemspec