🚀 Enhance bin/dev with configurable routes and improved production asset handling (#1790)

* 🚀 Enhance bin/dev script with configurable routes and improved error handling

## Major Improvements

### 🎯 Configurable Route Support
- Add `--route` parameter to bin/dev for custom URL display
- Default to root URL (/) instead of hardcoded /hello_world
- Generators pass specific routes (hello_world) when creating demo apps
- Clean abstraction in ReactOnRails::Dev::ServerManager

### 🛠️ Enhanced Error Handling
- Comprehensive error messages for `bin/dev prod` failures
- Specific guidance for missing secret_key_base, database issues, dependencies
- Suggest `bin/dev static` as alternative for development with production-like assets
- Color-coded, actionable error messages with specific commands

### 🏗️ Architecture Cleanup
- Remove duplicate bin/dev files - single source of truth in templates/
- Abstract command-line logic into ServerManager.run_from_command_line()
- Eliminate complex route detection - simple generator-based approach
- Update install generator to copy directly from templates

### 🔧 Configuration Fixes
- Add nil-safe operators for PackerUtils.packer_type calls
- Improve handling when Shakapacker is not available
- Better deprecation warnings with fallback values

## Benefits
- ✅ Cleaner development workflow with configurable URLs
- ✅ Better error messages guide users to solutions
- ✅ Reduced code duplication and maintenance overhead
- ✅ More robust configuration handling
- ✅ Preserved backwards compatibility

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* 🔍 Capture and display precompile error output for better debugging

## Improvement
- Use Open3.capture3 to capture both stdout and stderr from asset precompilation
- Display actual error output when bin/dev prod fails
- Provide contextual fixes based on error content analysis
- Smart detection of specific issues (secret_key_base, database, webpack, gems)

## Benefits
- ✅ Users see the actual error message instead of generic failure
- ✅ Contextual guidance based on error type
- ✅ Better debugging experience for production asset compilation
- ✅ No more hidden error output

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* ✨ Add --rails-env option for configurable asset precompilation environment

## New Feature
- Add `--rails-env` option to `bin/dev prod` for custom Rails environment during assets:precompile
- Default: NODE_ENV=production, RAILS_ENV=development (avoids credentials complexity)
- Option: `--rails-env=production` for full production Rails environment
- Clear documentation that option only affects assets:precompile, not server processes

## Enhanced Documentation
- Comprehensive help text with examples and environment explanations
- Clear runtime messaging about environment configuration
- Separation of asset precompilation vs server process environments
- Guidance on when to use each option

## Usage Examples
```bash
bin/dev prod                          # Default: production webpack, development Rails
bin/dev prod --rails-env=production   # Full production environment
bin/dev prod --route=dashboard        # Custom route in URLs
```

## Benefits
- ✅ Production webpack optimizations without production Rails complexity by default
- ✅ Option for full production environment when needed (testing credentials, etc.)
- ✅ Clear documentation prevents confusion about scope
- ✅ Better error handling with environment-specific guidance

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* Fix test failures: restore PackerUtils logic and update bin/dev tests

- Restore proper PackerUtils.using_packer? logic from master branch
- Fix precompile? method to handle missing shakapacker properly
- Update bin/dev tests to match new simplified template structure
- Update server_manager_spec to expect Open3.capture3 instead of system

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* Fix RuboCop violations in server_manager_spec.rb

- Use instance_double instead of double for Process::Status
- Break long line for readability

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* Apply suggestions from code review

Co-authored-by: Copilot <[email protected]>

* Fix shell injection vulnerability in server_manager.rb

Security improvements:
- Replace string interpolation with env hash and argv array for Open3.capture3
- Add rails_env validation with allowlist pattern (/^[a-z0-9_]+$/i)
- Update error handling to use safe command display
- Add tests for rails_env validation and custom environment usage
- Prevent arbitrary shell command execution via --rails-env parameter

🤖 Generated with [Claude Code](https://claude.ai/code)

Author: justin808

docs/contributor-info/coding-agents-guide.md

@@ -16,7 +16,7 @@ This guide provides structured instructions for AI coding agents working with Re
 ### Version Compatibility Matrix
 
 | react_on_rails | Shakapacker | Webpack | Node.js | Ruby |
-|----------------|-------------|---------|---------|------|
+| -------------- | ----------- | ------- | ------- | ---- |
 | v16.x          | >= 6.0      | v5      | 20-22   | 3.2+ |
 | v14.x          | >= 6.0      | v5      | 18-20   | 2.7+ |
 | v13.x          | >= 6.0      | v5      | 16-18   | 2.7+ |
@@ -206,25 +206,29 @@ fix_webpack_cache() {
 #### 1. Missing Routes File (js-routes gem)
 
 **Detection:**
+
 ```regex
 /Cannot read properties of undefined.*reading 'module'/
 /ProvidedDependencyTemplate\.apply/
 ```
 
 **Auto-fix:**
+
 ```bash
 bundle exec rails js:export
 ```
 
 #### 2. ProvidePlugin Module Missing
 
 **Detection:**
+
 ```regex
 /Error: Can't resolve.*\$app/
 /Module not found.*utils\/routes/
 ```
 
 **Auto-fix:**
+
 ```bash
 # Check if file exists, generate if missing
 [ -f "app/javascript/utils/routes.js" ] || bundle exec rails js:export
@@ -236,12 +240,14 @@ grep -q "\$app" config/webpack/*.js || echo "⚠️  Missing webpack alias"
 #### 3. Version Incompatibility
 
 **Detection:**
+
 ```regex
 /webpack.*incompatible/
 /peer dep.*react-on-rails/
 ```
 
 **Auto-fix:**
+
 ```bash
 # Update to compatible versions
 npm install react-on-rails@^16.0.0
@@ -370,18 +376,21 @@ After successful upgrades, suggest:
 ### If Build Completely Breaks
 
 1. **Rollback immediately:**
+
    ```bash
    git checkout HEAD~1 -- Gemfile package.json Gemfile.lock package-lock.json
    bundle install
    npm install
    ```
 
 2. **Identify the issue:**
+
    ```bash
    npm run build 2>&1 | tee build-error.log
    ```
 
 3. **Apply targeted fixes:**
+
    - Missing routes: `rails js:export`
    - Cache issues: `rm -rf node_modules/.cache tmp/cache`
    - Dependencies: `bundle update && npm install`
@@ -391,6 +400,7 @@ After successful upgrades, suggest:
 ### If Rails Environment Unavailable
 
 Use minimal commands:
+
 ```bash
 # Skip database operations
 DATABASE_URL=sqlite3:tmp/minimal.db rails js:export
@@ -401,4 +411,4 @@ RAILS_ENV=test rails js:export
 
 ---
 
-This guide ensures consistent, reliable React on Rails operations for coding agents while providing clear error recovery paths.
+This guide ensures consistent, reliable React on Rails operations for coding agents while providing clear error recovery paths.

docs/guides/upgrading-react-on-rails.md

@@ -88,6 +88,7 @@ rails generate react_on_rails:install
 **Symptoms:** Webpack cannot find modules referenced in your configuration
 
 **Solutions:**
+
 1. Clear webpack cache: `rm -rf node_modules/.cache`
 2. Verify all ProvidePlugin modules exist
 3. Check webpack alias configuration

docs/javascript/troubleshooting-build-errors.md

@@ -15,80 +15,96 @@ This guide covers common webpack build errors encountered when using react_on_ra
 **Note:** This error only occurs if you're using the optional `js-routes` gem to access Rails routes in JavaScript.
 
 ### Error Message
+
 ```
 Cannot read properties of undefined (reading 'module')
 TypeError: Cannot read properties of undefined (reading 'module')
     at ProvidedDependencyTemplate.apply
 ```
 
 ### Root Cause
+
 This error occurs when:
+
 1. Your webpack config references Rails routes via ProvidePlugin
 2. The `js-routes` gem hasn't generated the JavaScript routes file
 3. You're using `js-routes` integration but missing the generated file
 
 ### When You Need js-routes
+
 `js-routes` is **optional** and typically used when:
+
 - Rails-heavy apps with React components that need to navigate to Rails routes
 - Server-side rendered apps mixing Rails and React routing
 - Legacy Rails apps migrating ERB views to React
 - Apps using Rails routing patterns for RESTful APIs
 
 ### When You DON'T Need js-routes
+
 Most modern React apps use:
+
 - Client-side routing (React Router) instead of Rails routes
 - Hardcoded API endpoints or environment variables
 - SPA (Single Page App) architecture with API-only Rails backend
 
 ### Solution (if using js-routes)
+
 1. **Generate JavaScript routes file:**
+
    ```bash
    bundle exec rails js:export
    ```
 
 2. **Verify the routes file was created:**
+
    ```bash
    ls app/javascript/utils/routes.js
    ```
 
 3. **Check webpack configuration includes ProvidePlugin:**
    ```javascript
    new webpack.ProvidePlugin({
-     Routes: "$app/utils/routes"
-   })
+     Routes: '$app/utils/routes',
+   });
    ```
 
 ### Alternative Solution (if NOT using js-routes)
+
 Remove the Routes ProvidePlugin from your webpack configuration:
+
 ```javascript
 // Remove this line if you don't use js-routes
 new webpack.ProvidePlugin({
-  Routes: "$app/utils/routes"  // ← Remove this
-})
+  Routes: '$app/utils/routes', // ← Remove this
+});
 ```
 
 ## ProvidePlugin Module Resolution Errors
 
 ### Common Error Patterns
+
 - `Cannot read properties of undefined (reading 'module')`
 - `Module not found: Error: Can't resolve 'module_name'`
 - `ERROR in ./path/to/file.js: Cannot find name 'GlobalVariable'`
 
 ### Debugging Steps
 
 1. **Check file existence:**
+
    ```bash
    find app/javascript -name "routes.*" -type f
    find app/javascript -name "*global*" -type f
    ```
 
 2. **Verify webpack aliases:**
+
    ```javascript
    // In your webpack config
    console.log('Webpack aliases:', config.resolve.alias);
    ```
 
 3. **Test module resolution:**
+
    ```bash
    # Run webpack with debug output
    bin/shakapacker --debug-shakapacker
@@ -109,6 +125,7 @@ new webpack.ProvidePlugin({
 ## Environment Setup Dependencies
 
 ### Rails Environment Required
+
 Some operations require a working Rails environment:
 
 - `rails js:export` (generates routes - **only needed if using js-routes gem**)
@@ -118,17 +135,20 @@ Some operations require a working Rails environment:
 ### Common Issues
 
 1. **Database Connection Errors:**
+
    ```
    MONGODB | Error checking localhost:27017: Connection refused
    ```
 
    **Solution:** These are usually warnings and don't prevent operation. To silence:
+
    ```bash
    # Run with minimal environment
    RAILS_ENV=development bundle exec rails js:export
    ```
 
 2. **Missing Dependencies:**
+
    ```
    sidekiq-pro is not installed
    ```
@@ -138,6 +158,7 @@ Some operations require a working Rails environment:
 ### Workarounds
 
 1. **Skip database initialization:**
+
    ```bash
    DATABASE_URL=sqlite3:tmp/db.sqlite3 rails js:export
    ```
@@ -152,14 +173,15 @@ Some operations require a working Rails environment:
 ### Version Compatibility Matrix
 
 | react_on_rails | Shakapacker | Webpack | Node.js |
-|----------------|-------------|---------|---------|
+| -------------- | ----------- | ------- | ------- |
 | v16.x          | >= 6.0      | v5      | 20-22   |
 | v14.x          | >= 6.0      | v5      | 18-20   |
 | v13.x          | >= 6.0      | v5      | 16-18   |
 
 ### Common Upgrade Issues
 
 1. **Webpacker to Shakapacker migration incomplete:**
+
    ```bash
    # Remove webpacker references
    grep -r "webpacker" config/
@@ -172,6 +194,7 @@ Some operations require a working Rails environment:
    ```
 
 ### Migration Steps
+
 1. Follow the [Shakapacker upgrade guide](https://github.com/shakacode/shakapacker/blob/main/docs/v6_upgrade.md)
 2. Update webpack configurations
 3. Regenerate configurations with `rails generate react_on_rails:install`
@@ -254,4 +277,4 @@ fi
 
 - Check the [general troubleshooting guide](./troubleshooting-when-using-shakapacker.md)
 - Review [webpack configuration docs](./webpack.md)
-- Contact [[email protected]](mailto:[email protected]) for professional support
+- Contact [[email protected]](mailto:[email protected]) for professional support

lib/generators/react_on_rails/bin/dev

@@ -38,7 +38,7 @@ def clear
       @output = []
     end
 
-    def helpful_message_after_installation(component_name: "HelloWorld")
+    def helpful_message_after_installation(component_name: "HelloWorld", route: "hello_world")
       process_manager_section = build_process_manager_section
       testing_section = build_testing_section
       package_manager = detect_package_manager
@@ -62,7 +62,7 @@ def helpful_message_after_installation(component_name: "HelloWorld")
            ./bin/dev prod         # Production-like mode for testing
            ./bin/dev help         # See all available options
 
-        3. Visit: #{Rainbow('http://localhost:3000/hello_world').cyan.underline}
+        3. Visit: #{Rainbow(route ? "http://localhost:3000/#{route}" : 'http://localhost:3000').cyan.underline}
         ✨ KEY FEATURES:
         ─────────────────────────────────────────────────────────────────────────
         • Auto-registration enabled - Your layout only needs:

lib/generators/react_on_rails/generator_messages.rb

@@ -136,11 +136,13 @@ def shakapacker_in_gemfile?
       end
 
       def add_bin_scripts
-        directory "#{__dir__}/bin", "bin"
+        # Copy bin scripts from templates
+        template_bin_path = "#{__dir__}/templates/base/base/bin"
+        directory template_bin_path, "bin"
 
         # Make these and only these files executable
         files_to_copy = []
-        Dir.chdir("#{__dir__}/bin") do
+        Dir.chdir(template_bin_path) do
           files_to_copy.concat(Dir.glob("*"))
         end
         files_to_become_executable = files_to_copy.map { |filename| "bin/#{filename}" }
@@ -149,7 +151,14 @@ def add_bin_scripts
       end
 
       def add_post_install_message
-        GeneratorMessages.add_info(GeneratorMessages.helpful_message_after_installation)
+        # Determine what route will be created by the generator
+        route = "hello_world" # This is the hardcoded route from base_generator.rb
+        component_name = options.redux? ? "HelloWorldApp" : "HelloWorld"
+
+        GeneratorMessages.add_info(GeneratorMessages.helpful_message_after_installation(
+                                     component_name: component_name,
+                                     route: route
+                                   ))
       end
 
       def shakapacker_loaded_in_process?(gem_name)

lib/generators/react_on_rails/install_generator.rb

@@ -68,7 +68,7 @@ def add_redux_specific_messages
         require_relative "generator_messages"
         GeneratorMessages.output.clear
         GeneratorMessages.add_info(
-          GeneratorMessages.helpful_message_after_installation(component_name: "HelloWorldApp")
+          GeneratorMessages.helpful_message_after_installation(component_name: "HelloWorldApp", route: "hello_world")
         )
       end
     end

lib/generators/react_on_rails/react_with_redux_generator.rb

@@ -28,19 +28,4 @@ rescue LoadError
 end
 
 # Main execution
-case ARGV[0]
-when "production-assets", "prod"
-  ReactOnRails::Dev::ServerManager.start(:production_like)
-when "static"
-  ReactOnRails::Dev::ServerManager.start(:static, "Procfile.dev-static-assets")
-when "kill"
-  ReactOnRails::Dev::ServerManager.kill_processes
-when "help", "--help", "-h"
-  ReactOnRails::Dev::ServerManager.show_help
-when "hmr", nil
-  ReactOnRails::Dev::ServerManager.start(:development, "Procfile.dev")
-else
-  puts "Unknown argument: #{ARGV[0]}"
-  puts "Run 'bin/dev help' for usage information"
-  exit 1
-end
+ReactOnRails::Dev::ServerManager.run_from_command_line(ARGV)