Enhance security documentation and nil safety

Security improvements:
- Clarify that Open3.capture3 doesn't invoke shell for simple commands
- Update all security warnings to explain shell metacharacters won't work
- Document recommended .gitignore approach (commit .example, gitignore actual)
- Add execution order documentation (services → hook → Procfile)
- Enhanced security note in docs with best practices

Code robustness:
- Add safe navigation operator for nil check: output&.include?(expected_output)
- Prevents NoMethodError if output is nil
- Add ArgumentError rescue for invalid command formats
- Improved inline documentation about command execution

Documentation improvements:
- Expanded security note with IMPORTANT callout
- Added recommended approach section
- Added execution order section
- Clarified that shell features will fail (not just "avoid")

All tests passing (14/14). Zero RuboCop offenses.

Addresses security and robustness feedback from PR review.

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

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

Author: justin808

docs/building-features/process-managers.md

@@ -144,7 +144,24 @@ redis
 
 #### Security Note
 
-⚠️ Commands in `.dev-services.yml` are executed during `bin/dev` startup. Only add commands from trusted sources. Consider adding `.dev-services.yml` to `.gitignore` if it contains machine-specific paths or sensitive information.
+⚠️ **IMPORTANT**: Commands in `.dev-services.yml` are executed during `bin/dev` startup without shell expansion for safety. However, you should still:
+
+- **Only add commands from trusted sources**
+- **Avoid shell metacharacters** (&&, ||, ;, |, $, etc.) - they won't work and indicate an anti-pattern
+- **Review changes carefully** if .dev-services.yml is committed to version control
+- **Consider adding to .gitignore** if it contains machine-specific paths or sensitive information
+
+**Recommended approach:**
+
+- Commit `.dev-services.yml.example` to version control (safe, documentation)
+- Add `.dev-services.yml` to `.gitignore` (developers copy from example)
+- This prevents accidental execution of untrusted commands from compromised dependencies
+
+**Execution order:**
+
+1. Service dependency checks (`.dev-services.yml`)
+2. Precompile hook (if configured in `config/shakapacker.yml`)
+3. Process manager starts processes from Procfile
 
 ## Installing a Process Manager
 

lib/generators/react_on_rails/templates/base/base/.dev-services.yml.example

@@ -14,10 +14,12 @@
 # adding .dev-services.yml to .gitignore if it contains machine-specific config.
 #
 # Security best practices:
-# - Use simple commands without shell metacharacters when possible
-# - Avoid complex shell scripts or chained commands (&&, ||, |, etc.)
+# - Commands are executed without shell expansion (shell metacharacters won't work)
+# - Use simple, single commands (e.g., "redis-cli ping", "pg_isready")
+# - Do NOT use shell features: &&, ||, |, $, ;, backticks, etc. will fail
 # - Only include services you trust
 # - Keep commands simple and focused on service health checks
+# - Consider adding .dev-services.yml to .gitignore (commit .example instead)
 #
 # Example configuration:
 #

lib/react_on_rails/dev/service_checker.rb

@@ -110,17 +110,25 @@ def check_service(_name, config)
 
           return status.success? if expected_output.nil?
 
-          status.success? && output.include?(expected_output)
+          # Safe nil check for output before calling include?
+          status.success? && output&.include?(expected_output)
         end
 
         def run_check_command(command)
           require "open3"
+          # Execute command as-is. Commands are from local .dev-services.yml config file
+          # which should be trusted. Shell metacharacters won't work as expected since
+          # Open3.capture3 doesn't invoke a shell by default for simple command strings.
           stdout, stderr, status = Open3.capture3(command, err: %i[child out])
           output = stdout + stderr
           [output, status]
         rescue Errno::ENOENT
           # Command not found - service is not available
           ["", nil]
+        rescue ArgumentError => e
+          # Invalid command format
+          warn "Invalid command format: #{e.message}" if ENV["DEBUG"]
+          ["", nil]
         rescue StandardError => e
           # Log unexpected errors for debugging
           warn "Unexpected error checking service: #{e.message}" if ENV["DEBUG"]

spec/dummy/.dev-services.yml.example

@@ -14,10 +14,12 @@
 # adding .dev-services.yml to .gitignore if it contains machine-specific config.
 #
 # Security best practices:
-# - Use simple commands without shell metacharacters when possible
-# - Avoid complex shell scripts or chained commands (&&, ||, |, etc.)
+# - Commands are executed without shell expansion (shell metacharacters won't work)
+# - Use simple, single commands (e.g., "redis-cli ping", "pg_isready")
+# - Do NOT use shell features: &&, ||, |, $, ;, backticks, etc. will fail
 # - Only include services you trust
 # - Keep commands simple and focused on service health checks
+# - Consider adding .dev-services.yml to .gitignore (commit .example instead)
 #
 # For the React on Rails dummy app, we typically don't require external services,
 # but here are some common examples you might use in a real application: