Walkthrough

Adds a first-class --rsc-pro generator mode, updates generator flag logic and error/recovery messaging, pins matched Pro/RSC gem and npm versions during generation, and enhances RSC dependency installation to try version-pinned packages then fall back to unpinned packages with warnings and retry.

Changes

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant CLI as Install Generator
    participant Helper as Generator Helper
    participant ProSetup as Pro Setup
    participant DepMgr as JS Dependency Manager
    participant NPM as npm Registry

    User->>CLI: run generator with --rsc-pro
    CLI->>Helper: use_rsc_pro_mode?()
    Helper-->>CLI: true
    CLI->>Helper: use_pro?(), use_rsc?()
    Helper-->>CLI: true / true

    CLI->>ProSetup: validate Pro gem / prepare auto-install
    ProSetup-->>CLI: gem present or `bundle add ... --version='...' --strict` command

    CLI->>DepMgr: add_rsc_dependencies()
    DepMgr->>DepMgr: rsc_packages_with_version()
    DepMgr->>NPM: install pinned RSC packages
    alt pinned install succeeds
        NPM-->>DepMgr: success
    else pinned install fails
        DepMgr-->>CLI: emit warning about pinned mismatch
        DepMgr->>NPM: install unversioned RSC packages
        NPM-->>DepMgr: success
    end

    CLI->>CLI: generate files (hello-server, scripts)
    CLI-->>User: emit rsc_pro_verification_message and completion info

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I hopped through flags and version strings,

pinned Pro and RSC with careful rings,
tried a pinned install, then tried once more,
retried unpinned and opened the door,
a rabbit cheers: “Generation springs!”

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Greptile Summary

This PR introduces a first-class --rsc-pro install flag that combines --pro and --rsc behaviour into a single semantic mode. It threads the new flag through all generator decision points: option declaration, sub-generator invocation, recovery/error messages, dirty-worktree prerequisites, and post-install verification. It also adds version-pinned RSC npm install with a graceful unversioned fallback, and uses exact version pinning (rather than ~>) for the Pro gem bundle add command when in RSC Pro mode.

Key changes:

• New use_rsc_pro_mode? helper in GeneratorHelper; use_pro? and use_rsc? extended to recognise :rsc_pro.
• install_generator.rb: new --rsc-pro option, updated invoke_generators, recovery_install_command, installation_prerequisites_met?, plus rsc_pro_verification_message post-install checklist.
• js_dependency_manager.rb: rsc_packages_with_version pins RSC npm package to the gem version; add_rsc_dependencies retries with the unversioned package if the pinned install fails.
• pro_setup.rb: pro_gem_auto_install_command uses exact version pinning for --rsc-pro; context-line helpers are extracted for better error messaging.
• Comprehensive spec coverage for all new paths (flag logic, file generation, dirty-worktree error, exact bundle-add version, fallback npm install).

Minor observations:

• The manual fallback instruction in both the dirty-worktree error (install_generator.rb line 256) and missing_pro_gem? (pro_setup.rb line 72) still suggests gem 'react_on_rails_pro', '~> version' even in --rsc-pro mode, while the auto-install command uses exact pinning. This is a small messaging inconsistency worth a comment or alignment.
• missing_pro_required_flag (install_generator.rb) and pro_requirement_flag (pro_setup.rb) are near-duplicate flag-name resolvers with slightly different internal implementations; consider consolidating into GeneratorHelper.

Confidence Score: 4/5

• Safe to merge; the new flag is additive, well-tested, and doesn't break existing --rsc or --pro paths.
• All new and modified code paths are covered by targeted specs, the flag propagation logic is correct and consistent across generator boundaries, and the fallback npm-install behaviour is thoroughly exercised. The only gaps are minor messaging inconsistencies (exact-vs-pessimistic version in manual fallback instructions) and duplicated flag-name resolution logic — neither affects runtime correctness.
• pro_setup.rb and install_generator.rb — the dual flag-name resolution methods and the ~> vs exact-pinning inconsistency in manual fallback messages are worth a second look before merge.

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[rails generate react_on_rails:install] --> B{Flag check}
    B -->|--rsc-pro| C[use_rsc_pro_mode? = true\nuse_rsc? = true\nuse_pro? = true]
    B -->|--rsc AND --pro| C
    B -->|--rsc only| D[use_rsc_pro_mode? = false\nuse_rsc? = true\nuse_pro? = true]
    B -->|--pro only| E[use_rsc_pro_mode? = false\nuse_rsc? = false\nuse_pro? = true]

    C --> F[pro_gem_auto_install_command\nuses EXACT version pinning\nbundle add react_on_rails_pro\n--version='16.x.y']
    D --> G[pro_gem_auto_install_command\nuses pessimistic constraint\nbundle add react_on_rails_pro\n--version='~> 16.x.y']
    E --> G

    C --> H[add_rsc_dependencies\nTry [email protected]\nFallback to react-on-rails-rsc]
    D --> H

    C --> I[recovery_install_command\n--rsc-pro flag]
    D --> J[recovery_install_command\n--rsc flag]
    E --> K[recovery_install_command\n--pro flag]

    C --> L[Post-install: rsc_pro_verification_message\nshown]
    D --> M[Post-install: standard message only]
    E --> M

_{Reviews (1): Last reviewed commit: "Add first-class --rsc-pro install mode" | Re-trigger Greptile}

Code Review

Overall this is a clean addition of a first-class --rsc-pro mode. The option routing, sub-generator propagation, and fallback logic are all sound. A few issues worth addressing before merge:

Issues posted as inline comments

1. respond_to?(:use_rsc_pro_mode?) guards in pro_setup.rb (lines 96 & 475) — the module's own docs already require includers to also include GeneratorHelper, so these defensive guards hide a missing-include bug rather than surfacing it. Either drop the guards (rely on the documented contract) or add a default stub def use_rsc_pro_mode? = false inside ProSetup so the method is always defined.

2. Manual gem-install instructions don't match auto-install pinning (install_generator.rb:256 and pro_setup.rb:72) — pro_gem_auto_install_command uses an exact version for --rsc-pro, but the manual fallback messages still emit ~>. A user on a dirty worktree who follows the manual path will install a potentially-different version than what auto-install would have pinned.

3. Silent error suppression in rsc_packages_with_version (js_dependency_manager.rb) — the bare rescue StandardError discards the exception message. Including e.message in the warning would make version-resolution failures easier to diagnose.

Minor observations (no action required)

• add_rsc_dependencies compares rsc_packages != RSC_DEPENDENCIES to detect whether a versioned install was attempted. This works correctly (including the rescue path), but a named boolean flag would make intent slightly more explicit.
• The rsc_pro_verification_message uses Rainbow for styled output; the standalone --rsc path has no equivalent post-install guidance. Worth a comment clarifying whether that omission is intentional.

Addressed the CI regression for RSC install modes.

What I changed:

• Fixed GeneratorHelper#add_npm_dependencies to respect the return value from package_json manager add operations (it can return false without raising).
  • This allows add_rsc_dependencies to correctly detect the failed pinned add ([email protected]) and fall back to unpinned react-on-rails-rsc.
• Updated recovery_install_command to emit --rsc-pro only when --rsc-pro is explicitly set. For --rsc installs (even if pro is true internally), recovery now keeps --rsc as expected.
• Added/updated specs in generator_helper_spec for boolean return handling from manager.add.

Validation run locally:

• bundle exec rspec react_on_rails/spec/react_on_rails/generators/install_generator_spec.rb:1421 react_on_rails/spec/react_on_rails/generators/install_generator_spec.rb:1531 react_on_rails/spec/react_on_rails/generators/install_generator_spec.rb:1563 react_on_rails/spec/react_on_rails/generators/install_generator_spec.rb:1613 react_on_rails/spec/react_on_rails/generators/install_generator_spec.rb:1748 react_on_rails/spec/react_on_rails/generators/generator_helper_spec.rb:71 (10 examples, 0 failures)
• bundle exec rubocop react_on_rails/lib/generators/react_on_rails/generator_helper.rb react_on_rails/lib/generators/react_on_rails/install_generator.rb react_on_rails/spec/react_on_rails/generators/generator_helper_spec.rb

Commit: 4322e7be

Overall the PR is well-structured. The rsc-pro flag is a clean ergonomic improvement, the fallback for version-pinned RSC packages is a solid reliability win, and the test coverage is thorough. Inline comments have been posted on the specific issues. Summary of findings: (1) Must-fix: The respond_to guard on use_rsc_pro_mode? in pro_setup.rb lines 91 and 475 silently swallows NoMethodError if modules are mis-combined. (2) Must-fix: The dirty-worktree error message always shows a pessimistic version constraint but pro_gem_auto_install_command uses exact pinning for rsc-pro - inconsistent guidance. (3) Should-fix: The rsc_packages != RSC_DEPENDENCIES comparison relies on object identity from the fallback path returning the constant itself - fragile to future refactoring. (4) Nit: result ? true : false is equivalent to !!result. (5) Nit: Hardcoded localhost:3000 in verification message.

Code Review

Overall: Clean addition of a first-class --rsc-pro mode. The option routing, sub-generator propagation, and RSC fallback logic are well-structured. A few items below.

Must-fix:

1. Missing react-on-rails-rsc version assertion in the --rsc-pro test (inline comment posted)

install_generator_spec.rb:1492-1500 - The example is named "pins Pro dependencies and installs the RSC dependency" but only asserts react-on-rails-pro and react-on-rails-pro-node-renderer. The react-on-rails-rsc pin is not validated. See inline suggestion.

2. pro_packages_with_version silently drops the error message in its rescue

js_dependency_manager.rb:377-379 - The newly added rsc_packages_with_version correctly logs e.message in its rescue block, but the pre-existing pro_packages_with_version uses a bare rescue StandardError without capturing the exception. Since this PR introduces the sister method and establishes the pattern, fix the inconsistency: change to rescue StandardError => e and include e.message in the warning.

Do NOT apply Cursor Bugbot autofix:

Cursor Bugbot proposed fix changes add_npm_dependencies to always return true after pj.manager.add. This would be a regression. The intentional change in this PR flips both add_npm_dependencies and add_package from unconditional true to result ? true : false. This makes the RSC fallback in add_rsc_dependencies work: a false return from add_packages(rsc_packages_with_version) signals the pinned package is unavailable and triggers the unversioned retry. Reverting to always returning true would make the fallback never fire.

Nits (no action required):

• Hardcoded localhost:3000 (install_generator.rb:473) - The verification message includes a styled link to http://localhost:3000/hello_server with an "(or your configured port)" note. Users on non-3000 ports see the hardcoded URL highlighted. Consider omitting the full URL and just referencing the path.

• missing_pro_required_flag proxy (install_generator.rb:478-480) - This method is a one-liner that delegates straight to pro_requirement_flag from ProSetup. The indirection adds no value.

• CodeRabbit RSC fallback concern - CodeRabbit flags the retry as "ineffective" claiming add_packages runs before the install step. This is a false positive: the package_json gem's manager.add handles both updating package.json and running the package manager install atomically. When a pinned npm version does not exist, the add call fails (returning false), which the fallback correctly detects.

Review Summary

The overall approach is sound — adding --rsc-pro as a first-class flag with proper fallthrough to use_pro?/use_rsc?, exact version pinning for the paired RSC npm package, and clear recovery messaging is a clean design. The test coverage is good breadth.

A few issues worth addressing before merge:

Medium — Potential regression in add_npm_dependencies / add_package

Both generator_helper.rb and js_dependency_manager.rb now check !result.nil? && result != false to determine success. The original code always returned true after a non-raising call. This is only safe if the package_json gem guarantees a truthy return on success and false specifically on failure — if the gem uses Ruby's void convention and returns nil on success, every successful package install will now be misreported as failure, triggering spurious fallback warnings. The test suite mocks the return value so it can't catch this. Worth verifying the package_json gem's documented return contract. (Inline comments on both affected lines.)

Medium — options.key? vs options[key] in pro_flag_specified_for_context?

Thor always populates the options hash with declared option defaults, so options.key?(:rsc_pro) is true even when the user didn't pass any flag. As a result, pro_gem_requirement_context_line can say "You specified --pro" for a plain rails generate react_on_rails:install invocation. This was a pre-existing issue with :pro/:rsc, but it's now slightly more likely to trigger via InstallGenerator (which declares all three). Fix: check options[:pro] || options[:rsc] || options[:rsc_pro]. (Inline comment.)

Low — Exact version + --strict may block pre-release auto-install

bundle add react_on_rails_pro --version='16.4.0.rc.5' --strict fails immediately if that exact RC hasn't been published to RubyGems yet — a common situation when developing both gems in the same cycle. A graceful fallback or a clearer error message would help. (Inline comment.)

Low — Hardcoded hello_server route in verification message

The rsc_pro_verification_message hard-codes /hello_server as the verification URL. If the template renames this route, the message becomes silently stale. Linking it to the template source (or a shared constant) would keep the two in sync. (Inline comment.)

Nit — Incomplete version assertion for RSC dep in --rsc-pro spec

The test checks deps["react-on-rails-pro"] for exact version equality but only checks include("react-on-rails-rsc") without asserting the version. A silent version-pin fallback would go undetected. (Inline comment.)

Review

Overall the PR is well-structured and the expanded test coverage gives good confidence in the new flag semantics. A few things worth addressing before merge:

Issues

Double blank line in error message (pro_setup.rb:71)
When rsc_pro_prerelease_note returns "" (the common case - no prerelease, or not RSC Pro mode), the heredoc interpolation leaves a blank line in the output, producing a double blank gap before "Please add manually...". Minor but visually rough; guard the interpolation so the note line is omitted entirely when empty.

bundle add --strict + pre-release version = silent hard failure (pro_setup.rb:490)
In RSC Pro mode pro_gem_version_requirement returns the exact gem version string including any pre-release suffix. Paired with --strict, Bundler will refuse to install if that exact version is not on RubyGems yet. The rsc_pro_prerelease_note in the error path helps, but the auto-install attempt fails silently with no diagnostic about why. Worth surfacing the captured bundle-add output in the failure branch, or at least noting in the auto-install log that exact-version pinning plus --strict may be the cause.

Hardcoded RSC_PACKAGE_VERSION_PIN (js_dependency_manager.rb:129)
This constant is intentionally independent of gem versioning (RSC follows the React 19.0.x line), but there is no mechanism to remind maintainers to bump it on releases. Should be documented in the release checklist or CHANGELOG guidelines - otherwise it will silently go stale.

Nits / Design feedback

rsc_packages_with_version / used_version_pins tuple - The two-element return value and the used_version_pins flag exist solely to support a hypothetical future subclass override (no override exists today). The resulting complexity in add_rsc_dependencies (destructuring, conditional branch, manual_install_packages) could be simplified to a straightforward pinned-then-fallback sequence without the tuple API.

pro_flag_specified_for_context? - Single-line wrapper around use_pro? with no distinguishing logic. Either document the override contract or inline the call.

manual_install_packages dead code in exception path - In the rescue block, manual_install_packages is never read; the block always interpolates RSC_DEPENDENCIES directly. No bug, but worth a brief comment to avoid confusion for the next reader.

Closing as redundant: current generator semantics already treat --rsc as including Pro by design, so introducing --rsc-pro adds an unnecessary parallel mode.