[GH-ISSUE #243] Source-checkout MCP registrations break when build artifacts are absent #148

New issue

Closed

opened 2026-10-15 18:21:39 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 18:21:39 +00:00

Owner

Originally created by @morluto on GitHub (Jul 15, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/243

Bug Description

Running setup from a source checkout can persist MCP registrations that point to scripts/rea.mjs, even though that launcher requires generated files under the gitignored dist/ directory. A fresh or cleaned checkout leaves those registrations unable to start REA.

The registration health check compares only the configured command path and arguments, so it reports the local command as aligned when dist/main.js and dist/cli.js are absent. Because the same launcher is also needed to run rea doctor, the failure presents as a raw Node MODULE_NOT_FOUND error instead of a REA diagnostic.

The registry package is not affected: rea-agents@1.6.0 contains dist/main.js, dist/cli.js, and scripts/rea.mjs, and its CLI starts successfully.

Steps to Reproduce

Start from a clean source checkout with no node_modules/ or dist/.
Run npm ci.
Confirm that dist/ is still absent; the prepare lifecycle runs husky, not the build.
Run npm start or node scripts/rea.mjs --help.
For the persistent form of the bug, build the checkout, run setup so clients are registered to the absolute scripts/rea.mjs path, then remove the ignored build output or recreate the checkout at the same path.

Expected Behavior

Source-checkout setup should not report a client registration as ready/aligned unless its persisted command is runnable. A clean or rebuilt source checkout should either preserve a runnable registration or provide an actionable REA diagnostic identifying the missing build artifacts and the exact remediation.

Actual Behavior

After npm ci, npm start fails before REA code runs:

Error: Cannot find module '/root/rea/dist/main.js'
code: 'MODULE_NOT_FOUND'

The CLI dispatcher fails similarly while importing /root/rea/dist/cli.js.

After npm run build, rea doctor --json succeeds and reports the affected client registrations as aligned, for example:

{
  "command": ["/root/rea/scripts/rea.mjs", "mcp"],
  "state": "aligned",
  "remediation": null
}

This shows the underlying application and Hopper provider are healthy, while the persisted registration depends on disposable build output that its health classification does not check.

Environment

REA version: 1.6.0, source checkout at main
Node.js version: 24.18.0
npm version: 11.16.0
Host: Ubuntu 24.04
Hopper: /opt/hopper/bin/Hopper; all rea doctor --json Hopper checks pass after building
Target binary format: not applicable; failure occurs before target or provider startup

Additional Context

Reproduced with Codex, Claude Code, Cursor, and Windsurf registrations pointing to the local source launcher.
dist/ and node_modules/ are intentionally ignored.
package.json builds in prepack, so the published npm tarball includes the required files. The local npm ci lifecycle runs postinstall and prepare but does not build.
Official npm lifecycle guidance recommends prepare for platform-independent compilation needed before a package is used. The appropriate fix may instead be a setup precondition, a more durable registration command, or launcher-level diagnostics; the required outcome is that setup cannot persist or bless an unrunnable source registration.
Regression coverage should exercise a local-source registration with missing build artifacts, not only packaged tarballs whose prepack hook has already generated dist/.

Originally created by @morluto on GitHub (Jul 15, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/243 ## Bug Description Running setup from a source checkout can persist MCP registrations that point to `scripts/rea.mjs`, even though that launcher requires generated files under the gitignored `dist/` directory. A fresh or cleaned checkout leaves those registrations unable to start REA. The registration health check compares only the configured command path and arguments, so it reports the local command as `aligned` when `dist/main.js` and `dist/cli.js` are absent. Because the same launcher is also needed to run `rea doctor`, the failure presents as a raw Node `MODULE_NOT_FOUND` error instead of a REA diagnostic. The registry package is not affected: `rea-agents@1.6.0` contains `dist/main.js`, `dist/cli.js`, and `scripts/rea.mjs`, and its CLI starts successfully. ## Steps to Reproduce 1. Start from a clean source checkout with no `node_modules/` or `dist/`. 2. Run `npm ci`. 3. Confirm that `dist/` is still absent; the `prepare` lifecycle runs `husky`, not the build. 4. Run `npm start` or `node scripts/rea.mjs --help`. 5. For the persistent form of the bug, build the checkout, run setup so clients are registered to the absolute `scripts/rea.mjs` path, then remove the ignored build output or recreate the checkout at the same path. ## Expected Behavior Source-checkout setup should not report a client registration as ready/aligned unless its persisted command is runnable. A clean or rebuilt source checkout should either preserve a runnable registration or provide an actionable REA diagnostic identifying the missing build artifacts and the exact remediation. ## Actual Behavior After `npm ci`, `npm start` fails before REA code runs: ```text Error: Cannot find module '/root/rea/dist/main.js' code: 'MODULE_NOT_FOUND' ``` The CLI dispatcher fails similarly while importing `/root/rea/dist/cli.js`. After `npm run build`, `rea doctor --json` succeeds and reports the affected client registrations as `aligned`, for example: ```json { "command": ["/root/rea/scripts/rea.mjs", "mcp"], "state": "aligned", "remediation": null } ``` This shows the underlying application and Hopper provider are healthy, while the persisted registration depends on disposable build output that its health classification does not check. ## Environment - REA version: 1.6.0, source checkout at `main` - Node.js version: 24.18.0 - npm version: 11.16.0 - Host: Ubuntu 24.04 - Hopper: `/opt/hopper/bin/Hopper`; all `rea doctor --json` Hopper checks pass after building - Target binary format: not applicable; failure occurs before target or provider startup ## Additional Context - Reproduced with Codex, Claude Code, Cursor, and Windsurf registrations pointing to the local source launcher. - `dist/` and `node_modules/` are intentionally ignored. - `package.json` builds in `prepack`, so the published npm tarball includes the required files. The local `npm ci` lifecycle runs `postinstall` and `prepare` but does not build. - Official npm lifecycle guidance recommends `prepare` for platform-independent compilation needed before a package is used. The appropriate fix may instead be a setup precondition, a more durable registration command, or launcher-level diagnostics; the required outcome is that setup cannot persist or bless an unrunnable source registration. - Regression coverage should exercise a local-source registration with missing build artifacts, not only packaged tarballs whose `prepack` hook has already generated `dist/`.

bsakaguchi

2026-10-15 18:21:39 +00:00

closed this issue
added the
triage

bug
labels

bsakaguchi referenced this issue

2026-10-16 21:11:59 +00:00

[PR #217] [MERGED] fix(reference): preserve distinct parse failures #1869

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#148

No description provided.

Rows
Columns