[PR #5353] [MERGED] docs(installation): document targeted npx dependency recovery #6890

New issue

Closed

opened 2026-11-01 21:43:52 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-01 21:43:52 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/5353
Author: @ArjenS-LA
Created: 10/20/2026
Status: ✅ Merged
Merged: 10/22/2026
Merged by: @morluto

Base: main ← Head: docs/5259-npx-missing-module-recovery

📝 Commits (1)

7af8454 docs(installation): document targeted npx dependency recovery

📊 Changes

1 file changed (+47 additions, -0 deletions)

View changed files

📝 docs/installation.md (+47 -0)

📄 Description

Summary

Document recovery when an npx installation is missing a dependency file and REA cannot start even its doctor command. Relates to #5259.

Problem and expected behavior

The installation guide recommends running rea doctor, but has no recovery path when Node fails before a report can be produced. A clean Windows installation of REA 6.7.0 includes the reported missing @modelcontextprotocol/client/dist/index.mjs. In a controlled missing-file reproduction, retrying reused the incomplete installation, npm cache verify passed without restoring the file, and npm cache npx info still called the entry valid.

Change and scope

Add a troubleshooting section that identifies the affected npx entry, verifies its package/version/location, removes only that entry, and retries the same REA version with registry access. Explain the limits of cache verification and the difference between restored startup and a healthy doctor audit. No runtime, dependency, configuration, or generated metadata changes. A maintainer scope decision is not applicable to this documentation correction.

Contract and boundary impact

Semantic owner and earliest changed stage: installation troubleshooting before CLI startup.
Contribution scope fit and linked maintainer decision: documentation within the existing installation workflow; not applicable.
CLI and MCP/tool-catalog contract: unchanged.
Provider, bridge, target-format, or platform compatibility: unchanged; recovery executed on Windows x64.
Evidence, artifact, provenance, or reconstruction contract: unchanged.
Target selection, authority, upstream behavior, and cleanup details: no target interaction; documented operator action removes one selected npm runner cache entry and reinstalls its package using npm.
Generated metadata, package, or installation impact: documentation only; no automatic repair or dependency changes.

Expected effects:

Documentation or usability only; no target interaction.

Evidence and regression coverage

Executed on Windows 11 build 26200, Node 24.21.0, npm 11.19.0, with a dedicated workspace npm cache:

Installed and ran npm exec --yes --package=rea-agents@6.7.0 -- rea doctor --json: produced a JSON report; Node and host checks passed. Exit 1 reflected missing engines/registrations, not a module-loading failure.
Renamed only the isolated installation's client/dist/index.mjs, then retried the same package offline: reproduced ERR_MODULE_NOT_FOUND and Node's index.cjs suggestion.
Ran npm cache verify: exit 0, but the file remained absent. npm cache npx ls and info identified the correct entry; info reported it valid despite the missing file.
Ran npm cache npx rm with that exact verified key, then reinstalled with registry access: restored the 259,338-byte file with the same SHA-256 (8b370b8009c7b64834cc91bf5e6ab28e524d7c2ce952dfe57d943a6926f8d54b) and restored the JSON report.
Ran the documented npx --yes rea-agents@6.7.0 doctor --json: again produced the report with passing Node and host checks.

An offline reinstall attempt after cache verification failed with ENOTCACHED; the instructions explicitly require registry access. The reporter's original file-loss cause remains unknown. This verifies recovery from a deliberately incomplete installation, not an original release defect. No provider analysis or live agent connection was tested. No regression test added for this documentation-only change.

Validation performed

Using the repository-pinned Node 24.18.0 and npm 11.16.0:

npm ci --no-audit --no-fund: passed.
node scripts/verify-windows-native-artifact.mjs: passed after restoring the matching 6.7.0 addon and manifest from the clean published installation, as documented in native/windows/README.md. These ignored artifacts are not part of the diff.
npm run docs:check: passed, including all five onboarding consistency tests.
npm run check: passed (typecheck, lint, formatting, knip, metadata, module boundaries, architecture guards). Lint reported zero errors and existing warnings in unchanged code.
oxfmt --check docs/installation.md and git diff --check: passed.

Compatibility, safety, and release

Breaking changes or migration steps: none.
Real Hopper/Ghidra, browser, or OS coverage: real Windows CLI startup/recovery only; no providers or agent registration changes.
Package or release metadata impact: none.
Security, privacy, process, or containment review: recovery names one cache entry, requires clients using it to stop first, and does not advise changing module formats or disabling protections. The original cause is explicitly unknown.

Author readiness

Human owner: @ArjenS-LA

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

Before merge

Required checks pass and the human owner completes the readiness declarations.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/5353 **Author:** [@ArjenS-LA](https://github.com/ArjenS-LA) **Created:** 10/20/2026 **Status:** ✅ Merged **Merged:** 10/22/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `docs/5259-npx-missing-module-recovery` --- ### 📝 Commits (1) - [`7af8454`](https://github.com/morluto/rea/commit/7af8454ea82b7b5afb8897a59107d28e8774fdea) docs(installation): document targeted npx dependency recovery ### 📊 Changes **1 file changed** (+47 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `docs/installation.md` (+47 -0) </details> ### 📄 Description ## Summary Document recovery when an npx installation is missing a dependency file and REA cannot start even its doctor command. Relates to #5259. ## Problem and expected behavior The installation guide recommends running `rea doctor`, but has no recovery path when Node fails before a report can be produced. A clean Windows installation of REA 6.7.0 includes the reported missing `@modelcontextprotocol/client/dist/index.mjs`. In a controlled missing-file reproduction, retrying reused the incomplete installation, `npm cache verify` passed without restoring the file, and `npm cache npx info` still called the entry valid. ## Change and scope Add a troubleshooting section that identifies the affected npx entry, verifies its package/version/location, removes only that entry, and retries the same REA version with registry access. Explain the limits of cache verification and the difference between restored startup and a healthy doctor audit. No runtime, dependency, configuration, or generated metadata changes. A maintainer scope decision is not applicable to this documentation correction. ## Contract and boundary impact - Semantic owner and earliest changed stage: installation troubleshooting before CLI startup. - Contribution scope fit and linked maintainer decision: documentation within the existing installation workflow; not applicable. - CLI and MCP/tool-catalog contract: unchanged. - Provider, bridge, target-format, or platform compatibility: unchanged; recovery executed on Windows x64. - Evidence, artifact, provenance, or reconstruction contract: unchanged. - Target selection, authority, upstream behavior, and cleanup details: no target interaction; documented operator action removes one selected npm runner cache entry and reinstalls its package using npm. - Generated metadata, package, or installation impact: documentation only; no automatic repair or dependency changes. Expected effects: - [x] Documentation or usability only; no target interaction. ## Evidence and regression coverage Executed on Windows 11 build 26200, Node 24.21.0, npm 11.19.0, with a dedicated workspace npm cache: 1. Installed and ran `npm exec --yes --package=rea-agents@6.7.0 -- rea doctor --json`: produced a JSON report; Node and host checks passed. Exit 1 reflected missing engines/registrations, not a module-loading failure. 2. Renamed only the isolated installation's `client/dist/index.mjs`, then retried the same package offline: reproduced `ERR_MODULE_NOT_FOUND` and Node's `index.cjs` suggestion. 3. Ran `npm cache verify`: exit 0, but the file remained absent. `npm cache npx ls` and `info` identified the correct entry; `info` reported it valid despite the missing file. 4. Ran `npm cache npx rm` with that exact verified key, then reinstalled with registry access: restored the 259,338-byte file with the same SHA-256 (`8b370b8009c7b64834cc91bf5e6ab28e524d7c2ce952dfe57d943a6926f8d54b`) and restored the JSON report. 5. Ran the documented `npx --yes rea-agents@6.7.0 doctor --json`: again produced the report with passing Node and host checks. An offline reinstall attempt after cache verification failed with `ENOTCACHED`; the instructions explicitly require registry access. The reporter's original file-loss cause remains unknown. This verifies recovery from a deliberately incomplete installation, not an original release defect. No provider analysis or live agent connection was tested. No regression test added for this documentation-only change. ## Validation performed Using the repository-pinned Node 24.18.0 and npm 11.16.0: - `npm ci --no-audit --no-fund`: passed. - `node scripts/verify-windows-native-artifact.mjs`: passed after restoring the matching 6.7.0 addon and manifest from the clean published installation, as documented in `native/windows/README.md`. These ignored artifacts are not part of the diff. - `npm run docs:check`: passed, including all five onboarding consistency tests. - `npm run check`: passed (typecheck, lint, formatting, knip, metadata, module boundaries, architecture guards). Lint reported zero errors and existing warnings in unchanged code. - `oxfmt --check docs/installation.md` and `git diff --check`: passed. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: real Windows CLI startup/recovery only; no providers or agent registration changes. - Package or release metadata impact: none. - Security, privacy, process, or containment review: recovery names one cache entry, requires clients using it to stop first, and does not advise changing module formats or disabling protections. The original cause is explicitly unknown. ## Author readiness Human owner: @ArjenS-LA - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [x] Required checks pass and the human owner completes the readiness declarations. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-11-01 21:43:52 +00:00