[codex] Document and harden helper binstub PATH fix (#1201)

## Summary

- Adds an `[Unreleased]` changelog entry for #1200 as the `10.2.1`
patch-release item.
- Treats `PATH=""` as a single empty PATH entry, matching shell lookup
semantics by resolving it to the launch directory in helper binstubs.
- Adds regression coverage for a wholly empty PATH alongside the
existing leading/trailing empty PATH entry cases.

## Review context

- Adversarial Claude review was triggered on the merged #1200 fix and
completed successfully:
https://github.com/shakacode/shakapacker/actions/runs/28724619218
- Claude final review comment:
#1200 (comment)
- Claude found no blocker in the #1200 code path, but flagged the
missing changelog entry as a release-process blocker and noted the
untested `PATH=""` edge case addressed here.
- Local Codex review of `v10.2.0..main` found no actionable issues.

## Validation

- `bundle exec rspec spec/shakapacker/helper_binstubs_spec.rb
spec/shakapacker/binstub_sync_spec.rb`
- `ruby -c lib/install/bin/shakapacker-config && ruby -c
lib/install/bin/diff-bundler-config && ruby -c
spec/dummy/bin/shakapacker-config`
- `yarn test --runInBand test/configExporter/createBinStub.test.js
test/package/configExporter/cli.test.js`
- `bundle exec rubocop --cache false lib/install/bin/shakapacker-config
lib/install/bin/diff-bundler-config spec/dummy/bin/shakapacker-config
spec/shakapacker/helper_binstubs_spec.rb`
- `yarn type-check`
- `git diff --check`
- `.agents/bin/validate`

## Release note

Yes: because `v10.2.0` shipped the Ruby-binstub regression and #1200 is
the only code delta from `v10.2.0` to `main`, this should be released as
`10.2.1`.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Bug Fixes**
* Fixed shell-compatible helper binstub behavior to restore reliable
Node lookup when `PATH` is unset/empty.
* Improved `PATH` normalization by defensively handling empty/blank
values and preserving trailing-empty fields, ensuring consistent
absolute-path `PATH` construction.
* Applied the same more robust `PATH` handling to generated Ruby
binstubs and related helper scripts.

* **Tests**
* Expanded helper binstubs coverage to include a wholly empty (`""`)
`PATH` case.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: justin808

CHANGELOG.md

@@ -9,6 +9,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- **Fixed helper binstubs delegating Node resolution to Ruby `exec` in unset and empty `PATH` environments.** [PR #1200](https://github.com/shakacode/shakapacker/pull/1200) and [PR #1201](https://github.com/shakacode/shakapacker/pull/1201) by [justin808](https://github.com/justin808). Restores shell-compatible Node lookup for `bin/shakapacker-config` and `bin/diff-bundler-config` after the `v10.2.0` Ruby-binstub regression, while keeping friendly missing-Node errors for `ENOENT` and `EACCES`.
+
 ## [v10.2.0] - July 3, 2026
 
 ### Added

lib/install/bin/diff-bundler-config

@@ -26,7 +26,10 @@ end
 def shakapacker_exec_env(launch_dir)
   return {} unless ENV.key?("PATH")
 
-  normalized_path = ENV["PATH"].split(File::PATH_SEPARATOR, -1).map do |entry|
+  path_entries = ENV["PATH"].split(File::PATH_SEPARATOR, -1)
+  path_entries = [""] if path_entries.empty?
+
+  normalized_path = path_entries.map do |entry|
     entry.empty? ? launch_dir : File.absolute_path(entry, launch_dir)
   end.join(File::PATH_SEPARATOR)
 

lib/install/bin/shakapacker-config

@@ -26,7 +26,10 @@ end
 def shakapacker_exec_env(launch_dir)
   return {} unless ENV.key?("PATH")
 
-  normalized_path = ENV["PATH"].split(File::PATH_SEPARATOR, -1).map do |entry|
+  path_entries = ENV["PATH"].split(File::PATH_SEPARATOR, -1)
+  path_entries = [""] if path_entries.empty?
+
+  normalized_path = path_entries.map do |entry|
     entry.empty? ? launch_dir : File.absolute_path(entry, launch_dir)
   end.join(File::PATH_SEPARATOR)
 

package/configExporter/cli.ts

@@ -560,7 +560,10 @@ end
 def shakapacker_exec_env(launch_dir)
   return {} unless ENV.key?("PATH")
 
-  normalized_path = ENV["PATH"].split(File::PATH_SEPARATOR, -1).map do |entry|
+  path_entries = ENV["PATH"].split(File::PATH_SEPARATOR, -1)
+  path_entries = [""] if path_entries.empty?
+
+  normalized_path = path_entries.map do |entry|
     entry.empty? ? launch_dir : File.absolute_path(entry, launch_dir)
   end.join(File::PATH_SEPARATOR)
 

spec/dummy/bin/shakapacker-config

@@ -26,7 +26,10 @@ end
 def shakapacker_exec_env(launch_dir)
   return {} unless ENV.key?("PATH")
 
-  normalized_path = ENV["PATH"].split(File::PATH_SEPARATOR, -1).map do |entry|
+  path_entries = ENV["PATH"].split(File::PATH_SEPARATOR, -1)
+  path_entries = [""] if path_entries.empty?
+
+  normalized_path = path_entries.map do |entry|
     entry.empty? ? launch_dir : File.absolute_path(entry, launch_dir)
   end.join(File::PATH_SEPARATOR)
 

spec/shakapacker/helper_binstubs_spec.rb

@@ -537,10 +537,11 @@ def exec(*args)
     end
 
     {
+      "wholly empty" => "",
       "leading" => "#{File::PATH_SEPARATOR}/nonexistent",
       "trailing" => "/nonexistent#{File::PATH_SEPARATOR}"
     }.each do |position, path_value|
-      it "honors a #{position} empty PATH entry as the current directory for #{command}" do
+      it "honors a #{position} PATH entry as the current directory for #{command}" do
         Dir.mktmpdir("shakapacker-binstub-") do |app_path|
           File.write(File.join(app_path, "Gemfile"), "")
           FileUtils.mkdir_p(File.join(app_path, "bin"))