[Fix] Stop counting files another branch ignored as changes after a switch - #524

…528)

## Why

On macOS, "Apply and rebuild" fails on Gutenberg pull requests based on
trunk from before 17 April 2026, such as
[WordPress/gutenberg#76292](WordPress/gutenberg#76292).
The screen says only `Build failed: Command failed: npm run --if-present
--workspaces --silent build`, exit 1. Without `--silent`,
`@wordpress/theme`'s `build:tokens` fails:

```
[ERROR:electron/shell/app/node_main.cc:153] Node.js environment variables are disabled because this process is invoked by other apps.
✗  [config] Cannot find module '.../packages/theme/bin/terrazzo-plugin-mode-overrides/index'
```

Reported in #525.

## What changes

Root cause: the Gutenberg script runs `cross-env
NODE_OPTIONS=--import=esbuild-esm-loader/register tz build`. `tz` starts
through our bash `node` shim, and on macOS a signed Electron removes
`NODE_OPTIONS` from any process whose parent is not part of the app, so
the `--import` never arrives. It is not a regression from #519: the main
binary fails the same way as the Helper, and the same build passes on
the system `node`.

The macOS `node`/`npm`/`npx` shims now split `NODE_OPTIONS` the way Node
does (quotes, backslash escapes, no globbing) and pass the options as
arguments, after our `--require` and before the CLI and the caller's own
arguments. Then they unset the variable, so an unsigned Electron (`npm
start`, CI) does not apply every option twice and dev behaves like the
release. Unset, not emptied: a signed Electron prints a
`node_main.cc:153` warning whenever the variable exists, even empty.
Linux and Windows shims are byte-identical to before.

Deliberately not in it: only the shim's own child gets the options. What
that child starts inherits no `NODE_OPTIONS`, as before this PR
(follow-up below).

## How to test this

Platforms: **macOS** only; the change is macOS only. Build: the
Buildkite artifact for the current head.

**Starting state:** a Gutenberg site on trunk, no work item linked, no
pull request checked out. A copy you can throw away is best: the build
rewrites `packages/theme/tokens/color.json`.

1. In **Check out a pull request**, enter `76292`, check it out and let
the install finish.
2. Click **Apply and rebuild**. Expected: the build finishes. On beta.2
it fails with the message above.
3. Unlink to go back to trunk and rebuild. Expected: the trunk build
finishes as before.

**What must not have happened:** no `node_main.cc:153 Node.js
environment variables are disabled` lines in the terminal; no Dock tiles
while the build runs (#518).

If the root build then fails on `routes/dashboard/package.json`, that is
a different bug (a trunk-only route left behind with only
`node_modules`, same with the system `node`); delete `routes/dashboard/`
on the test site and rebuild.

I reproduced the failure and checked the fix on a copy of a real site on
the PR 76292 commit, running the app's exact command, `npm run
--if-present --workspaces --silent build`:
- the installed beta.2 shims: exit 1;
- shims generated from this branch, with the same Helper: exit 0;
- the system `node`: exit 0.

The new tests in `tests/unit/node-shims.test.cjs` run the real shim
under `/bin/bash` (3.2, as macOS ships it) and fail on the old code.

## Risks and limitations

- An option that Node accepts only in `NODE_OPTIONS` but not as a flag:
none found. Command-line-only flags are now accepted, which is more
lenient, not broken.
- Malformed `NODE_OPTIONS` (unterminated quote) is passed through as
text where Node would refuse it.
- Self-review (fresh context): no bugs; 2 fix-here findings applied (the
variable cleared for the call, `/bin/bash` in the tests) and the wording
corrected. 1 follow-up, the grandchild gap above.
- The first version of that fix emptied the variable instead of
unsetting it, and the signed Buildkite build then printed the warning
for every process. The unit tests use a stand-in binary, and CI never
runs a signed Electron, so only the test's expectation guards this now
(it asserts the variable arrives unset).
- Checked on the copy with the installed signed Helper: the workspace
build and the full `npm run build` exit 0 with no warnings.

## Related

Fixes #525. Found while testing #524.

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

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…all (#530)

## Why

On a Gutenberg site installed on trunk, checking out an older pull request ([gutenberg#76292](WordPress/gutenberg#76292)) and clicking **Apply and rebuild** fails in `wp-build` with `ENOENT: ... routes/dashboard/package.json`. Reported in #529 (Switching to an older Gutenberg pull request leaves trunk-only directories that break wp-build).

## What changes

Root cause: a checkout removes a directory's tracked files but leaves its ignored ones. The trunk-only `routes/dashboard/` survives the switch holding only `node_modules`, and `wp-build` reads every directory under `routes/` as a route.

`switchToBranch` now removes, after the checkout, the topmost directories the new tree does not have, but only when everything left in them is a `node_modules` that Git ignores. A file, a symlink beside the install, or an install Git does not ignore (the #521 case, which is excluded instead) keeps the whole directory. It runs before the #521 exclude, reuses the diff that step already makes, and adds one `ls-tree` only when the switch deletes something (about 40 ms on a Gutenberg checkout). Best effort: a failure never fails the switch.

## How to test this

Platforms: **either**. Build: the Buildkite artifact for the current head.

**Starting state:** a Gutenberg site on trunk, installed, no work item linked, no pull request checked out, no changes. `routes/dashboard/node_modules/` exists in the site.

1. In **Check out a pull request**, enter `76292` and check it out. Let the install finish.
2. From a terminal in the site's directory: `ls routes`. Expected: no `dashboard`.
3. Click **Apply and rebuild**. Expected: the build succeeds.
4. Click **Unlink** to go back to trunk and let the install run. Expected: `routes/dashboard/node_modules/` is back and the site reports no changes.

**What must not have happened:** `routes/*` directories other than `dashboard` touched; the root `node_modules` rebuilt by the switch itself; anything under `packages/react-native-editor/` deleted on the way back to trunk (#521 keeps excluding it).

**Manual pass:** macOS, Buildkite artifact for `4828f2c`, on a real Gutenberg site (reached through a linked issue rather than a bare checkout). Steps 1 to 4 as expected: `routes/dashboard/` gone on `pr/76292`, build completed (48 s), back on trunk `routes/dashboard/node_modules/` reinstalled, no changes, `packages/react-native-editor/` still on disk and still excluded.

On the old code step 2 lists `dashboard` and step 3 fails. `a directory the destination tree lacks, holding only an install, does not survive the switch (issue #529)` in `tests/unit/ticket-branches.integration.test.cjs` fails on the old code (checked) and passes here.

## Risks and limitations

- Deletes: only ignored `node_modules` in a directory the new tree lacks. Switching back reinstalls when that directory is a workspace of the root lockfile, as Gutenberg's `routes/*` are.
- A file held open on Windows past the retries can leave the install half deleted and the directory still there: `wp-build` fails as before.
- Nothing is logged: `removed` is returned but no caller reads it, and the catch is silent, same as #524. Added to #523's scope.
- Only `switchToBranch` covers this. `resumeSwitch`, the ticket delete and the trunk update can leave the same leftover, like #521.
- A site already on the pull request with the leftover is not healed. Delete `routes/dashboard/` and rebuild.

## Related

Fixes #529. Follow-up: #523.

---

<details>
<summary>Design decisions and alternatives considered</summary>

- **Delete, but only `node_modules`.** #524 chose "exclude, never delete", but excluding does not help here: the directory existing is the problem. Restricting to an ignored install keeps the loss to what `npm install` recreates.
- **Generic, not `routes/`-specific.** Any tool that globs directories hits the same leftover; Gutenberg knowledge in the generic switch module would be the wrong place.
- **Rejected:** moving the directory aside and restoring it on return (new state to prune, restore collisions); cleaning `routes/*` before a build (narrow, Gutenberg-specific); a `wp-build` fix upstream (worth reporting, but older pull requests carry the old `wp-build`).
- **No index check before the delete.** It would only guard a submodule, which neither Gutenberg nor wordpress-develop has, and no test demonstrates a path (AGENTS.md).

</details>

<details>
<summary>Review outcome (required, see AGENTS.md)</summary>

0 [fix here] · 6 [follow-up]. 4 fixed here, 2 deferred.

- **Review:** completed. Fresh-context Explore subagent running `.github/instructions/code-review.instructions.md` step 3; base `375f962`, reviewed the uncommitted first version of the change; `npm run lint` clean, `npm test` 1662 pass 0 fail at that point.
- **Fixed:** tree compared without case (a directory renamed only by case is never a leftover, with a test); comment on a partial Windows delete corrected; symlink tests (beside the install: kept; inside `node_modules`: removed, target untouched); the not-ignored test now asserts #521 excludes it.
- **Deferred:** logging of `removed` and the silent catch (#523, comment added); other checkout paths (Risks).
- **Not taken:** the suggested `git ls-files` index guard, see Design decisions.
- **Since review:** the fixes above, not re-reviewed by a fresh context. Head `4828f2c`; `npm run lint` clean, `npm test` 1665 pass 0 fail.
- **CodeRabbit:** completed on `4828f2c` (base `375f962`), 2 findings. Fixed: the locked-directory test also skips as root (`226ab25`). Declined: reporting cleanup failures through switch progress, which is #523's scope (same call as on #524).
- **Since CodeRabbit:** `4828f2c` → `0d776e4`, tests only: the root skip (`226ab25`) and the case fixture committed through `commitFiles`, which had no Git identity on the Windows runner (`0d776e4`). Not re-reviewed; CI green on `0d776e4`, both platforms.

</details>

<details>
<summary>Screenshots or recording</summary>

Nothing on screen changed.

</details>

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




---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

## Why

`v1.2.0-beta.2` shipped on 23 September. Five commits reach trunk since
then: #524, #528, #530 and #532 fix what the beta.2 testing turned up
(files another branch ignored counted as changes after a switch,
`NODE_OPTIONS` lost in the macOS shims, and a trunk-only Gutenberg route
left behind by a switch to an older pull request, which broke
`wp-build`), and #531 makes the manual **Real WordPress setup** workflow
pass again, green on both platforms and both targets on trunk's app
code. Milestone `v1.2.0` holds only the umbrella #251.

`electron-builder` derives artifact names from `package.json`, so the
version has to move before the tag and the artifacts exist. This is a
stable release: it takes `releases/latest` from `v1.1.0`.

## What changes

Only the version. All three package-version fields in `package.json` and
`package-lock.json` move together from `1.2.0-beta.2` to `1.2.0`. No
dependency versions change, and there is no application behaviour change
in this PR.

## How to test this

Platforms: any for the suite; macOS and Windows for the artifact checks
that follow the merge.

1. `npm run lint` is clean and `npm test` passes, from the repository
root.
2. `node -e "console.log(require('./package.json').version)"` prints
`1.2.0`.
3. `python3 -c "import
json;d=json.load(open('package-lock.json'));print(d['version'],
d['packages']['']['version'])"` prints `1.2.0 1.2.0`.

**What must not have happened:** no dependency version may change. `git
diff` must show exactly three changed lines, all of them the root
package version.

After merge, the release build must produce artifacts named
`wordpress-contributor-toolkit-1.2.0-*`; the asar root must be exactly
`node_modules`, `package.json`, `src`, with npm 11 under
`node_modules/npm` and no `.codesigning` directory; on macOS
`CFBundleShortVersionString` reads `1.2.0`.

## Risks and limitations

No UI change. The risk is a mis-scoped edit in `package-lock.json`,
where dependencies also carry version fields; the replacement was
confined to the first 2000 bytes of the file, which hold the two root
entries and nothing else, and both files were re-parsed as JSON
afterwards.

Manual passes on what reached trunk after beta.2: #528 and #530 on macOS
in their PRs; #530 plus #532 on Windows on #532's artifact (c7ec033),
including the case that failed on e0a3faa.

## Related

Part of #251. Release notes follow on the release; docs publish for the
tag per #487.

---

<details>
<summary>Review outcome (required, see AGENTS.md)</summary>

0 [fix here] · 0 [follow-up]. Deterministic layer only: lint clean, 1667
tests pass, both files valid JSON, diff confined to the three root
version fields. No judgement pass was run: this change has no logic to
review.

- **Review:** completed, deterministic layer, in session; head is the
single bump commit / base `4c3b05a` (trunk); evidence above; outcome:
nothing to fix.
- **Since review:** none.

</details>

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

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>