Add CI debugging tools for efficient local failure reproduction

## Changes

### RuboCop Configuration
- Exclude bin/* shell scripts from RuboCop checks

### Configuration Improvements
- Fix error message wording in configuration.rb (prefer :defer over :sync)
- Add explanatory comment in context.ts about TypeScript var requirement
- Improve ESLint config formatting (export at top)
- Add clarifying comment in helper spec about defer default strategy

### CI Debugging Tools
- Add bin/ci-rerun-failures: Smart script that fetches actual CI failures from GitHub and re-runs only failed jobs locally
- Add bin/ci-run-failed-specs: Parse and re-run only specific failing RSpec examples
- Add bin/ci-switch-config: Switch between latest/minimum dependency configurations

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

Co-Authored-By: Claude <noreply@anthropic.com>

Author: justin808

.claude/commands/update-changelog.md

@@ -5,7 +5,6 @@ You are helping to add an entry to the CHANGELOG.md file for the React on Rails
 ## Critical Requirements
 
 1. **User-visible changes only**: Only add changelog entries for user-visible changes:
-
    - New features
    - Bug fixes
    - Breaking changes
@@ -118,21 +117,18 @@ When a new version is released:
 ### For Regular Changelog Updates
 
 1. **ALWAYS fetch latest changes first**:
-
    - **CRITICAL**: Run `git fetch origin master` to ensure you have the latest commits
    - The workspace may be behind origin/master, causing you to miss recently merged PRs
    - After fetching, use `origin/master` for all comparisons, NOT local `master` branch
 
 2. **Determine the correct version tag to compare against**:
-
    - First, check the tag dates: `git log --tags --simplify-by-decoration --pretty="format:%ai %d" | head -10`
    - Find the latest version tag and its date
    - Compare origin/master branch date to the tag date
    - If the tag is NEWER than origin/master, it means the branch needs to be updated to include the tag's commits
    - **CRITICAL**: Always use `git log TAG..BRANCH` to find commits that are in the tag but not in the branch, as the tag may be ahead
 
 3. **Check commits and version boundaries**:
-
    - **IMPORTANT**: Use `origin/master` in all commands below, not local `master`
    - Run `git log --oneline LAST_TAG..origin/master` to see commits since the last release
    - Also check `git log --oneline origin/master..LAST_TAG` to see if the tag is ahead of origin/master
@@ -148,20 +144,17 @@ When a new version is released:
 5. **Read the current CHANGELOG.md** to understand the existing structure and formatting.
 
 6. **Determine where entries should go**:
-
    - If the latest version tag is NEWER than origin/master branch, move entries from "Unreleased" to that version section
    - If origin/master is ahead of the latest tag, add new entries to "Unreleased"
    - Always verify the version date in CHANGELOG.md matches the actual tag date
 
 7. **Add or move entries** to the appropriate section under appropriate category headings.
-
    - **CRITICAL**: When moving entries from "Unreleased" to a version section, merge them with existing entries under the same category heading
    - **NEVER create duplicate section headings** (e.g., don't create two "### Fixed" sections)
    - If the version section already has a category heading (e.g., "### Fixed"), add the moved entries to that existing section
    - Maintain the category order as defined above
 
 8. **Verify formatting**:
-
    - Bold description with period
    - Proper PR link (NO hash symbol)
    - Proper author link
@@ -181,12 +174,10 @@ When a new version is released:
 When releasing from beta to a stable version (e.g., v16.1.0-beta.3 → v16.1.0):
 
 1. **Remove all beta version labels** from the changelog:
-
    - Change `### [v16.1.0-beta.1]`, `### [v16.1.0-beta.2]`, etc. to a single `### [v16.1.0]` section
    - Combine all beta entries into the stable release section
 
 2. **Consolidate duplicate entries**:
-
    - If bug fixes or changes were made to features introduced in earlier betas, keep only the final state
    - Remove redundant changelog entries for fixes to beta features
    - Keep the most recent/accurate description of each change

.rubocop.yml

@@ -25,6 +25,7 @@ AllCops:
     - '**/node_modules/**/*'
     - '**/public/**/*'
     - '**/tmp/**/*'
+    - 'bin/*'  # Shell scripts
     - 'coverage/**/*'
     - 'gen-examples/examples/**/*'
     - 'node_modules/**/*'

CHANGELOG.md

@@ -38,7 +38,6 @@ Changes since the last non-beta release.
 #### Changed
 
 - **Shakapacker 9.0.0 Upgrade**: Upgraded Shakapacker from 8.2.0 to 9.0.0 with Babel transpiler configuration for compatibility. Key changes include:
-
   - Configured `javascript_transpiler: babel` in shakapacker.yml (Shakapacker 9.0 defaults to SWC which has PropTypes handling issues)
   - Added precompile hook support via `bin/shakapacker-precompile-hook` for ReScript builds and pack generation
   - Configured CSS Modules to use default exports (`namedExport: false`) for backward compatibility with existing `import styles from` syntax
@@ -100,7 +99,6 @@ To migrate to React on Rails Pro:
 **Note:** If you're not using any of the Pro-only methods listed above, no changes are required.
 
 - **Pro-Specific Configurations Moved to Pro Gem**: The following React Server Components (RSC) configurations have been moved from `ReactOnRails.configure` to `ReactOnRailsPro.configure`:
-
   - `rsc_bundle_js_file` - Path to the RSC bundle file
   - `react_server_client_manifest_file` - Path to the React server client manifest
   - `react_client_manifest_file` - Path to the React client manifest
@@ -126,7 +124,6 @@ To migrate to React on Rails Pro:
   See the [React on Rails Pro Configuration docs](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/docs/configuration.md) for more details.
 
 - **Streaming View Helpers Moved to Pro Gem**: The following view helpers have been removed from the open-source gem and are now only available in React on Rails Pro:
-
   - `stream_react_component` - Progressive SSR using React 18+ streaming
   - `rsc_payload_react_component` - RSC payload rendering
 
@@ -151,12 +148,10 @@ To migrate to React on Rails Pro:
 #### New Features
 
 - **Server Bundle Security**: Added new configuration options for enhanced server bundle security and organization:
-
   - `server_bundle_output_path`: Configurable directory (relative to the Rails root) for server bundle output (default: "ssr-generated"). If set to `nil`, the server bundle will be loaded from the same public directory as client bundles. [PR 1798](https://github.com/shakacode/react_on_rails/pull/1798) by [justin808](https://github.com/justin808)
   - `enforce_private_server_bundles`: When enabled, ensures server bundles are only loaded from private directories outside the public folder (default: false for backward compatibility) [PR 1798](https://github.com/shakacode/react_on_rails/pull/1798) by [justin808](https://github.com/justin808)
 
 - **Improved Bundle Path Resolution**: Bundle path resolution for server bundles now works as follows:
-
   - If `server_bundle_output_path` is set, the server bundle is loaded from that directory.
   - If `server_bundle_output_path` is not set, the server bundle falls back to the client bundle directory (typically the public output path).
   - If `enforce_private_server_bundles` is enabled:
@@ -268,7 +263,6 @@ See [Release Notes](docs/release-notes/16.0.0.md) for complete migration guide.
 
 - **`defer_generated_component_packs` deprecated** → use `generated_component_packs_loading_strategy`
 - Migration:
-
   - `defer_generated_component_packs: true` → `generated_component_packs_loading_strategy: :defer`
   - `defer_generated_component_packs: false` → `generated_component_packs_loading_strategy: :sync`
   - Recommended: `generated_component_packs_loading_strategy: :async` for best performance
@@ -677,7 +671,6 @@ for details.
 - Removal of config.symlink_non_digested_assets_regex as it's no longer needed with rails/webpacker.
   If any business needs this, we can move the code to a separate gem.
 - Added configuration option `same_bundle_for_client_and_server` with default `false` because
-
   1. Production applications would typically have a server bundle that differs from the client bundle
   2. This change only affects trying to use HMR with react_on_rails with rails/webpacker.
 
@@ -1395,13 +1388,11 @@ No changes.
 - Added automatic compilation of assets at precompile is now done by ReactOnRails. Thus, you don't need to provide your own `assets.rake` file that does the precompilation.
   [#398](https://github.com/shakacode/react_on_rails/pull/398) by [robwise](https://github.com/robwise), [jbhatab](https://github.com/jbhatab), and [justin808](https://github.com/justin808).
 - **Migration to v6**
-
   - Do not run the generator again if you've already run it.
 
   - See [shakacode/react-webpack-rails-tutorial/pull/287](https://github.com/shakacode/react-webpack-rails-tutorial/pull/287) for an example of upgrading from v5.
 
   - To configure the asset compilation you can either
-
     1. Specify a `config/react_on_rails` setting for `build_production_command` to be nil to turn this feature off.
     2. Specify the script command you want to run to build your production assets, and remove your `assets.rake` file.
 

CODING_AGENTS.md

@@ -260,18 +260,15 @@ Use `gh pr create` with:
 ## Debugging Workflow
 
 1. **Understand the Problem**
-
    - Read the issue carefully
    - Reproduce the bug if possible
    - Identify root cause
 
 2. **Create Minimal Test Case**
-
    - Write failing test that demonstrates issue
    - Keep it focused and minimal
 
 3. **Implement Fix**
-
    - Make smallest change possible
    - Ensure fix doesn't break existing functionality
    - Follow existing code patterns

CONTRIBUTING.md

@@ -607,22 +607,18 @@ This approach:
 **Common Issues and Solutions:**
 
 1. **React components not rendering (empty divs)**
-
    - **Cause**: Missing yalc setup for JavaScript package
    - **Solution**: Follow yalc setup steps above after running generator
 
 2. **Generator fails with Shakapacker errors**
-
    - **Cause**: Conflicting Shakapacker versions or incomplete installation
    - **Solution**: Clean reset and ensure consistent Shakapacker version across tests
 
 3. **Babel configuration conflicts during yalc development**
-
    - **Cause**: Both `babel.config.js` and `package.json` "babel" section defining presets
    - **Solution**: Remove "babel" section from `package.json`, keep only `babel.config.js`
 
 4. **"Package.json not found" errors**
-
    - **Cause**: Generator trying to access non-existent package.json files
    - **Solution**: Test with commits that fix this specific issue (e.g., bc69dcd0)
 

TODO.md

@@ -59,13 +59,11 @@
 ## Developer Experience
 
 - [ ] **bin/dev help command enhancements**
-
   - [x] Add emojis and colors for better readability
   - [ ] Add section about component development patterns
   - [ ] Include troubleshooting for client/server split issues
 
 - [ ] **Babel Configuration Conflict Detection**
-
   - [ ] Add validation in generator/initializer to detect conflicting Babel configs
   - [ ] Improve error messaging for duplicate preset issues
   - [ ] Common conflict: babel.config.js + package.json "babel" section

bin/ci-rerun-failures

@@ -71,22 +71,6 @@ done
 echo -e "${BLUE}=== CI Failure Re-runner ===${NC}"
 echo ""
 
-# Check required dependencies
-MISSING_DEPS=()
-command -v gh >/dev/null 2>&1 || MISSING_DEPS+=("gh (GitHub CLI)")
-command -v jq >/dev/null 2>&1 || MISSING_DEPS+=("jq")
-
-if [ ${#MISSING_DEPS[@]} -gt 0 ]; then
-  echo -e "${RED}Error: Missing required dependencies:${NC}"
-  for dep in "${MISSING_DEPS[@]}"; do
-    echo "  - $dep"
-  done
-  echo ""
-  echo "Install with:"
-  echo "  brew install gh jq"
-  exit 1
-fi
-
 # Fetch PR info
 if [ -z "$PR_NUMBER" ]; then
   if ! gh pr view --json number,commits >/dev/null 2>&1; then
@@ -230,9 +214,9 @@ echo "   3. Run: pbpaste | bin/ci-run-failed-specs"
 echo ""
 
 # Confirm before running
-read -p "Run these tests now? [Y/n] " -n 1 -r REPLY
+read -p "Run these tests now? [Y/n] " -n 1 -r
 echo
-if [[ ! "${REPLY}" =~ ^[Yy]$ ]] && [[ ! -z "${REPLY}" ]]; then
+if [[ ! $REPLY =~ ^[Yy]$ ]] && [[ ! -z $REPLY ]]; then
   echo "Cancelled."
   exit 0
 fi
@@ -255,8 +239,6 @@ for cmd in "${!COMMANDS_TO_RUN[@]}"; do
   echo -e "${BLUE}Command: $cmd${NC}"
   echo ""
 
-  # Note: Using eval here is safe because $cmd comes from predefined JOB_MAP,
-  # not from user input. Commands may contain shell operators like && and ||.
   if eval "$cmd"; then
     echo -e "${GREEN}✓ $job_name passed${NC}"
     echo ""

bin/ci-run-failed-specs

@@ -18,21 +18,6 @@ YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 NC='\033[0m' # No Color
 
-# Check required dependencies
-MISSING_DEPS=()
-command -v bundle >/dev/null 2>&1 || MISSING_DEPS+=("bundle (Ruby bundler)")
-
-if [ ${#MISSING_DEPS[@]} -gt 0 ]; then
-  echo -e "${RED}Error: Missing required dependencies:${NC}"
-  for dep in "${MISSING_DEPS[@]}"; do
-    echo "  - $dep"
-  done
-  echo ""
-  echo "Install with:"
-  echo "  gem install bundler"
-  exit 1
-fi
-
 # Show help
 show_help() {
   cat << EOF
@@ -137,35 +122,30 @@ if [[ "${UNIQUE_SPECS[0]}" == *"spec/system"* ]] || [[ "${UNIQUE_SPECS[0]}" == *
   fi
 fi
 
-# Build rspec command as array (safer than eval)
-RSPEC_CMD=("bundle" "exec" "rspec")
+# Build rspec command
+RSPEC_CMD="bundle exec rspec"
 for spec in "${UNIQUE_SPECS[@]}"; do
-  RSPEC_CMD+=("$spec")
+  RSPEC_CMD="$RSPEC_CMD '$spec'"
 done
 
-# Display command for user
-DISPLAY_CMD="bundle exec rspec"
-for spec in "${UNIQUE_SPECS[@]}"; do
-  DISPLAY_CMD="$DISPLAY_CMD '$spec'"
-done
-echo -e "${BLUE}Command:${NC} cd $WORKING_DIR && $DISPLAY_CMD"
+echo -e "${BLUE}Command:${NC} cd $WORKING_DIR && $RSPEC_CMD"
 echo ""
 
 # Confirm (read from /dev/tty to handle piped input)
 if [ -t 0 ]; then
-  read -p "Run these specs now? [Y/n] " -n 1 -r REPLY
+  read -p "Run these specs now? [Y/n] " -n 1 -r
 else
-  read -p "Run these specs now? [Y/n] " -n 1 -r REPLY < /dev/tty
+  read -p "Run these specs now? [Y/n] " -n 1 -r < /dev/tty
 fi
 echo
-if [[ ! "${REPLY}" =~ ^[Yy]$ ]] && [[ ! -z "${REPLY}" ]]; then
+if [[ ! $REPLY =~ ^[Yy]$ ]] && [[ ! -z $REPLY ]]; then
   echo "Cancelled."
   exit 0
 fi
 
-# Run the specs directly (no eval - safer)
+# Run the specs
 cd "$WORKING_DIR"
-"${RSPEC_CMD[@]}"
+eval "$RSPEC_CMD"
 RESULT=$?
 
 echo ""

bin/ci-switch-config

@@ -6,7 +6,7 @@
 #   bin/ci-switch-config latest    # Ruby 3.4, Node 22, latest deps
 #   bin/ci-switch-config status    # Show current configuration
 
-set -euo pipefail
+set -e
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
@@ -67,34 +67,30 @@ show_status() {
   echo ""
   echo "Dependency versions:"
 
-  SHAKAPACKER_GEM=""
   if [ -f "$PROJECT_ROOT/Gemfile.development_dependencies" ]; then
-    SHAKAPACKER_GEM=$(grep 'gem "shakapacker"' "$PROJECT_ROOT/Gemfile.development_dependencies" | sed -E 's/.*"([0-9.]+)".*/\1/' || echo "")
-    echo "  Shakapacker (gem): ${SHAKAPACKER_GEM:-not found}"
+    SHAKAPACKER_GEM=$(grep 'gem "shakapacker"' "$PROJECT_ROOT/Gemfile.development_dependencies" | sed -E 's/.*"([0-9.]+)".*/\1/')
+    echo "  Shakapacker (gem): $SHAKAPACKER_GEM"
   fi
 
-  SHAKAPACKER_NPM=""
   if [ -f "$PROJECT_ROOT/spec/dummy/package.json" ]; then
-    SHAKAPACKER_NPM=$(grep '"shakapacker"' "$PROJECT_ROOT/spec/dummy/package.json" | sed -E 's/.*"([0-9.]+)".*/\1/' || echo "")
-    echo "  Shakapacker (npm): ${SHAKAPACKER_NPM:-not found}"
+    SHAKAPACKER_NPM=$(grep '"shakapacker"' "$PROJECT_ROOT/spec/dummy/package.json" | sed -E 's/.*"([0-9.]+)".*/\1/')
+    echo "  Shakapacker (npm): $SHAKAPACKER_NPM"
   fi
 
-  REACT_ROOT=""
   if [ -f "$PROJECT_ROOT/package.json" ]; then
-    REACT_ROOT=$(grep '"react":' "$PROJECT_ROOT/package.json" | head -1 | sed -E 's/.*"([^"]+)".*/\1/' || echo "")
-    echo "  React (root): ${REACT_ROOT:-not found}"
+    REACT_ROOT=$(grep '"react":' "$PROJECT_ROOT/package.json" | head -1 | sed -E 's/.*"([^"]+)".*/\1/')
+    echo "  React (root): $REACT_ROOT"
   fi
 
-  REACT_DUMMY=""
   if [ -f "$PROJECT_ROOT/spec/dummy/package.json" ]; then
-    REACT_DUMMY=$(grep '"react":' "$PROJECT_ROOT/spec/dummy/package.json" | sed -E 's/.*"([^"]+)".*/\1/' || echo "")
-    echo "  React (dummy): ${REACT_DUMMY:-not found}"
+    REACT_DUMMY=$(grep '"react":' "$PROJECT_ROOT/spec/dummy/package.json" | sed -E 's/.*"([^"]+)".*/\1/')
+    echo "  React (dummy): $REACT_DUMMY"
   fi
 
   echo ""
-  if [[ "${SHAKAPACKER_GEM}" == "8.2.0" ]] && [[ "${REACT_ROOT}" == "18.0.0" ]]; then
+  if [[ "$SHAKAPACKER_GEM" == "8.2.0" ]] && [[ "$REACT_ROOT" == "18.0.0" ]]; then
     echo -e "Current config: ${GREEN}minimum${NC} (matches CI: Ruby 3.2, Node 20, minimum deps)"
-  elif [[ "${SHAKAPACKER_GEM}" == "9.3.0" ]] && [[ "${REACT_ROOT}" =~ 19 ]]; then
+  elif [[ "$SHAKAPACKER_GEM" == "9.3.0" ]] && [[ "$REACT_ROOT" =~ 19 ]]; then
     echo -e "Current config: ${GREEN}latest${NC} (matches CI: Ruby 3.4, Node 22, latest deps)"
   else
     echo -e "Current config: ${YELLOW}unknown/mixed${NC}"
@@ -112,9 +108,9 @@ switch_to_minimum() {
   # Check if we have git changes
   if ! git diff --quiet || ! git diff --cached --quiet; then
     print_warning "You have uncommitted changes. This script will modify files."
-    read -p "Continue? (y/N) " -n 1 -r REPLY
+    read -p "Continue? (y/N) " -n 1 -r
     echo
-    if [[ ! "${REPLY}" =~ ^[Yy]$ ]]; then
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
       echo "Aborted."
       exit 1
     fi
@@ -192,9 +188,9 @@ restore_to_latest() {
   # Check if we have git changes
   if ! git diff --quiet || ! git diff --cached --quiet; then
     print_warning "You have uncommitted changes. This script will restore from git."
-    read -p "Continue? This will discard changes to package.json, Gemfile, etc. (y/N) " -n 1 -r REPLY
+    read -p "Continue? This will discard changes to package.json, Gemfile, etc. (y/N) " -n 1 -r
     echo
-    if [[ ! "${REPLY}" =~ ^[Yy]$ ]]; then
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
       echo "Aborted."
       exit 1
     fi