morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #3763] [CLOSED] docs(setup): explain recovery from workspace npm overrides #5881

New issue

Closed

opened 2026-10-31 01:10:09 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:10:09 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/3763
Author: @Abdooo2235
Created: 10/14/2026
Status: ❌ Closed

Base: main ← Head: fix/mcp-launcher-workspace-guidance

📝 Commits (2)

595f90d docs(setup): explain recovery from workspace npm overrides
d598a3e docs(setup): reconcile recovery guidance with main

📊 Changes

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

View changed files

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

📄 Description

Summary

Fixes #3690 by documenting the existing installed-executable recovery path for MCP launches that fail with npm EOVERRIDE.

Problem and expected behavior

npx can reject an unrelated workspace's dependency overrides before REA starts, even with the requested package cached. Users need a way to connect from that workspace without changing its dependencies or the meaning of relative input paths.

Change and scope

Add a troubleshooting section to the installation guide: install REA outside the affected project, preview and apply setup through the installed rea command, then restart the client. Explain why rerunning setup through npx retains the failing launcher.

This uses the existing direct-entrypoint registration. No launcher, configuration format, working-directory default, or runtime behavior changes. A new wrapper or automatic directory change would add unnecessary behavior. Maintainer scope decision: not applicable to this documentation correction.

Contract and boundary impact

Installation guidance only; no CLI/MCP schema, provider, Evidence, generated metadata, package dependency, or target authority changes.

Documentation or usability only; no target interaction.

Evidence and regression coverage

On Windows, reproduced the reported manifest conflict with cached rea-agents@6.4.0: npx --offline -y rea-agents@6.4.0 mcp exited 1 with EOVERRIDE. Reproduced with the pinned Node 24.18.0/npm 11.16.0 toolchain as well as the host toolchain.

Installed the same package into an isolated global prefix, ran setup preview and application against isolated OpenCode configuration, and verified the generated absolute Node/script registration. From the same conflicting workspace, that registration completed MCP initialization and tools/list with 170 tools. The workspace manifest remained byte-for-byte unchanged. No real user configuration was changed.

Validation performed

After merging main at 9ac76d3d and resolving the overlapping installation-guide additions on d598a3ea:

npm run test:local -- src/application/Setup.configuration.test.ts — 21 passed.
npm run check — passed; lint reported zero errors and 1660 warnings.
npm run docs:check — passed, including five README consistency tests.
Real installed-package setup and stdio MCP verification described above — passed on the original documentation revision with published 6.4.0; not repeated after this text-only merge.
git diff --check — passed.
GitHub CI on d598a3ea — all four required checks passed. Automated review may still be running.

Source checks used Node 24.18.0 and npm 11.16.0. Locked dependencies were installed with npm ci --ignore-scripts; the ordinary install stalled in the optional Frida installer. Repository hook preparation was run explicitly. No Frida verification is claimed.

Compatibility, safety, and release

No breaking change or migration. The recovery uses the existing reviewed setup flow. Real verification used Windows and the published 6.4.0 package; OpenCode itself and other operating systems were not exercised. Full-suite CI and optional analysis engines are outside this documentation change's local verification.

Author readiness

Human owner: @Abdooo2235

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.

_{🔄 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/3763 **Author:** [@Abdooo2235](https://github.com/Abdooo2235) **Created:** 10/14/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/mcp-launcher-workspace-guidance` --- ### 📝 Commits (2) - [`595f90d`](https://github.com/morluto/rea/commit/595f90d2c08fe0aa6d0bab0f02fc886bcd7fd4b8) docs(setup): explain recovery from workspace npm overrides - [`d598a3e`](https://github.com/morluto/rea/commit/d598a3ea14f6d4fa8325e32e0f7b69a7a5eddb68) docs(setup): reconcile recovery guidance with main ### 📊 Changes **1 file changed** (+33 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `docs/installation.md` (+33 -0) </details> ### 📄 Description ## Summary Fixes #3690 by documenting the existing installed-executable recovery path for MCP launches that fail with npm `EOVERRIDE`. ## Problem and expected behavior `npx` can reject an unrelated workspace's dependency overrides before REA starts, even with the requested package cached. Users need a way to connect from that workspace without changing its dependencies or the meaning of relative input paths. ## Change and scope Add a troubleshooting section to the installation guide: install REA outside the affected project, preview and apply setup through the installed `rea` command, then restart the client. Explain why rerunning setup through `npx` retains the failing launcher. This uses the existing direct-entrypoint registration. No launcher, configuration format, working-directory default, or runtime behavior changes. A new wrapper or automatic directory change would add unnecessary behavior. Maintainer scope decision: not applicable to this documentation correction. ## Contract and boundary impact Installation guidance only; no CLI/MCP schema, provider, Evidence, generated metadata, package dependency, or target authority changes. - [x] Documentation or usability only; no target interaction. ## Evidence and regression coverage On Windows, reproduced the reported manifest conflict with cached `rea-agents@6.4.0`: `npx --offline -y rea-agents@6.4.0 mcp` exited 1 with `EOVERRIDE`. Reproduced with the pinned Node 24.18.0/npm 11.16.0 toolchain as well as the host toolchain. Installed the same package into an isolated global prefix, ran setup preview and application against isolated OpenCode configuration, and verified the generated absolute Node/script registration. From the same conflicting workspace, that registration completed MCP initialization and `tools/list` with 170 tools. The workspace manifest remained byte-for-byte unchanged. No real user configuration was changed. ## Validation performed After merging `main` at `9ac76d3d` and resolving the overlapping installation-guide additions on `d598a3ea`: - `npm run test:local -- src/application/Setup.configuration.test.ts` — 21 passed. - `npm run check` — passed; lint reported zero errors and 1660 warnings. - `npm run docs:check` — passed, including five README consistency tests. - Real installed-package setup and stdio MCP verification described above — passed on the original documentation revision with published 6.4.0; not repeated after this text-only merge. - `git diff --check` — passed. - [GitHub CI on `d598a3ea`](https://github.com/morluto/rea/actions/runs/39070419445) — all four required checks passed. Automated review may still be running. Source checks used Node 24.18.0 and npm 11.16.0. Locked dependencies were installed with `npm ci --ignore-scripts`; the ordinary install stalled in the optional Frida installer. Repository hook preparation was run explicitly. No Frida verification is claimed. ## Compatibility, safety, and release No breaking change or migration. The recovery uses the existing reviewed setup flow. Real verification used Windows and the published 6.4.0 package; OpenCode itself and other operating systems were not exercised. Full-suite CI and optional analysis engines are outside this documentation change's local verification. ## Author readiness Human owner: @Abdooo2235 - [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. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:10:09 +00:00

closed this issue
added the
pull-request
label

bsakaguchi referenced this issue

2026-11-01 21:45:24 +00:00

[PR #5905] [MERGED] fix: preserve unknown JSON omission counts #7104

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#5881

No description provided.

Rows
Columns