fix: Check for semver before patch-release.js requires it

[kriszyp]

Authored by Claude Sonnet 5 (dispatch harper-pro-patch-release-deps-preflight).

⊙ Problem

scripts/patch-release.js loads semver at module load with no guard. In a fresh release clone with no node_modules, the script dies with a raw MODULE_NOT_FOUND stack and never prints a RESULT: line, so neither a human nor a --json caller learns the fix. Seen during the 5.2.0 release cut.

❓ Your call: Fix as specified. The check runs before any git, version, or push step, so a missing dependency stops the run before it changes anything.

💡 Solution

• When run as the CLI, the script calls require.resolve('semver') before the require and, on failure, exits 1 with semver is not installed. Run npm ci in <repo root> first. plus a RESULT: {"ok":false,...} line.
• CONTRIBUTING.md adds npm ci before node scripts/patch-release.js in the release procedure.

❓ Your call: The failure writes its RESULT: line without --json. Other die() calls emit only under --json. This one follows the --yes missing-backport abort path, which already emits without --json (CONTRIBUTING.md). Changing it is a one-line edit.

❓ Your call: The one-line comment at scripts/patch-release.js:93 (why the check is skipped under require()) is kept. A review nit asked to drop it. The reason is not visible in the code.

⚖️ Alternatives

• Docs only (npm ci in CONTRIBUTING.md). Rejected: a run without npm ci still crashes with the raw stack and no RESULT: line.
• npm pre script wrapper. Rejected: a second entry point for one script.

🔧 Changes

• require.resolve('semver') preflight. Look hardest at the require.main === module guard: it keeps require() importers throwing instead of exiting their host process.
• runtime dependency preflight test. The hide-semver.cjs preload overrides Module._resolveFilename so the child fails require('semver') on any host.
• npm ci step in CONTRIBUTING.md.

❓ Your call: The dispatch's acceptance route named NODE_PATH at an empty dir or a fixture copy without node_modules. Neither isolates the child from ancestor or global node_modules on a given host, so the test runs the real script with a -r preload that makes require('semver') fail.

✅ Verification

• mocha --require unitTests/unitTestSetup.cjs unitTests/scripts/patchRelease.test.mjs unitTests/scripts/patchReleasePresence.test.mjs on 93ef0250: 63 passing.
• Fails on base: the new test, run against 36efd7e4:scripts/patch-release.js, fails. The base crashes with Cannot find module 'semver' and no RESULT: line.
• Manual run on base, semver absent: raw MODULE_NOT_FOUND stack, no RESULT: line. On this branch: the npm ci message, RESULT: {"ok":false,...}, exit 1.
• prettier --check and oxlint --deny-warnings clean on the changed files.
• Not run: full npm run test:unit and integration tests. The change is a script and its test; no build output changes.
• Pre-push review (codex + gemini + cursor-composer + harper-domain): 6 rounds, all exit 0. Converged on 93ef0250; receipt on the pushed head. Round 1 found one test-isolation minor and two nits, all fixed. Rounds 3–4 drove the switch to the -r preload and comment trims. One Gemini major (undefined tmpdir) was dropped as factually wrong: tmpdir is imported at unitTests/scripts/patchRelease.test.mjs:16.

No tracking issue: the bug was found during the 5.2.0 release cut.

🤖 Generated with Claude Code

Related PRs: none found

_{Review-Coverage: authored=claude; ran=cursor-composer,gemini,codex; adjudicated=domain; declined=cursor-grok,cursor-kimi,cursor-muse; rounds=6; full=2 @ 93ef025}

_{Review-Attention: skim ~12m (decisions: result-line-without-json) @ 93ef025}

[gemini-code-assist]

Code Review

This pull request introduces a runtime dependency preflight check to scripts/patch-release.js to ensure that the semver package is installed before execution, providing a clear error message to run npm ci if it is missing. It also updates CONTRIBUTING.md with instructions to install dependencies first and adds a comprehensive unit test suite to verify this preflight behavior. There are no review comments, and I have no feedback to provide.