morluto/rea

Fork 0

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

[GH-ISSUE #7645] [Bug] Initial-target launch settings lost their reference documentation #4571

New issue

Closed

opened 2026-10-31 00:50:53 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 00:50:53 +00:00

Owner

Originally created by @coygeek on GitHub (Oct 28, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/7645

Before submitting

I searched the open and closed issues for a related report.
I removed credentials, tokens, private paths, and sensitive target data.

Area

Documentation

Observed behavior

A source-checkout user can generate an MCP registration with node scripts/print-mcp-config.mjs /absolute/example-target --kind database. Its output contains HOPPER_TARGET_PATH and HOPPER_TARGET_KIND, but searching the current guides and README finds neither name. The settings previously had an explicit reference that was removed during a documentation cleanup.

This is a documentation finding. The JSON printer and documentation search were executed; opening a target and the resulting server startup behavior were checked only in source.

Reproduction

From the baseline checkout, run:

rg -n 'HOPPER_TARGET_PATH|HOPPER_TARGET_KIND' docs README.md

It prints nothing and exits 1.

Run the repository's configuration generator:
```
node scripts/print-mcp-config.mjs /absolute/example-target --kind database
```
It exits 0 and prints a registration whose environment includes the example path and database kind. The example path need not exist: this command only prints JSON.

Both checks produced these results on two runs. Do not start the generated registration to reproduce this documentation omission.

Expected behavior

Keep a discoverable reference for the existing initial-target launch settings: the path, the accepted executable and database kinds, the default kind, and the fact that selecting a startup target opens it before MCP serving begins. Explain ordinary startup-open failure and the exclusion of these one-shot settings from setup's copied environment.

The reference was present before the documentation-only change in PR #485. That change explicitly stated that CLI/MCP contracts and runtime behavior did not change. The current configuration generator and runtime still accept this configuration; the guides should describe it or explicitly state that it is unsupported.

Impact and scope

P3: users of the source-checkout generator cannot look up the meaning and startup effects of its two target fields in the guides. No consequential runtime failure was demonstrated. The normal target-free MCP workflow remains documented and accepts target selection through open_binary.

The generator itself is excluded from the npm package's files list, so this finding does not claim that npm installations ship the helper. No target or provider was started, and effects of stale target paths on an actual client were not tested.

REA version

Exact node scripts/rea.mjs --version output: 6.8.0.

Source baseline: 65f1c447344a423fa2785847dbcea1e9a9e2454a.

Runtime and platform

Node.js v24.22.1; macOS 27.0.1; Darwin arm64. No provider runtime was used.

Target and artifact context

An illustrative absolute path supplied to a JSON printer. No target file or fixture is required.

Interface

MCP

Earliest failure stage

Unknown

Relevant output or evidence

The executed printer's relevant output was:

{
  "HOPPER_TARGET_PATH": "/absolute/example-target",
  "HOPPER_TARGET_KIND": "database"
}

This is the mcpServers.rea.env object. The documentation search in step 1 returned no matches.

Contract and history evidence:

git show 36aeec958^:AGENTS.md, lines 97-110, contains the initial-target server command and the explicit path/kind reference, including default executable.
Commit 36aeec95863ca28d3e3aa5bec75a45d3824e17f5, merged in PR #485, removes that catalog. The PR describes shortening the command/environment catalog and states that runtime and CLI/MCP contracts are unchanged.
At the baseline, scripts/print-mcp-config.mjs:2-8,26-28 advertises client configuration and emits the pair. package.json retains config:print but does not package the helper.
docs/mcp-contracts.md:737-745 describes cancellation and cleanup around initial-target startup; docs/client-configuration.md:270-282 excludes one-shot target paths from setup's copied environment. Neither identifies the settings.

Source-derived runtime behavior at the baseline:

scripts/rea.mjs:31-33,63-65 routes rea mcp into the production MCP entry point.
src/config/environment.ts:121-122 validates the path and kind; src/config/parseConfig.ts:168-169 retains them.
src/main.ts:109 selects eager startup when a target is supplied; src/main/eagerRuntime.ts:103-114 opens it before starting the MCP transport.
src/main/startup.ts:16-32 opens the requested path with the requested kind. An ordinary open failure returns exit 1; shutdown cancellation has a separate exit-0 path.

Analysis or suspected cause

The evidence supports a reference omission during documentation consolidation. The settings have a previously documented production entry point and remain in the configuration generator and startup parser, so their use is not confined to tests. Restoring a short guide reference would preserve the existing interface without changing runtime behavior.

Additional context

The duplicate search covered open and closed issues, all PR states, and issue comments. Issue #6961 concerns a different setting for Cutter bridge discovery. Issue #4885 and PR #4884 concern cancellation during initial-target startup, not the missing configuration reference. Issue #653 concerns package-version pins in manual registrations.

Originally created by @coygeek on GitHub (Oct 28, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/7645 ### Before submitting - [x] I searched the open and closed issues for a related report. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Area Documentation ### Observed behavior A source-checkout user can generate an MCP registration with `node scripts/print-mcp-config.mjs /absolute/example-target --kind database`. Its output contains `HOPPER_TARGET_PATH` and `HOPPER_TARGET_KIND`, but searching the current guides and README finds neither name. The settings previously had an explicit reference that was removed during a documentation cleanup. This is a documentation finding. The JSON printer and documentation search were executed; opening a target and the resulting server startup behavior were checked only in source. ### Reproduction 1. From the baseline checkout, run: ```sh rg -n 'HOPPER_TARGET_PATH|HOPPER_TARGET_KIND' docs README.md ``` It prints nothing and exits 1. 2. Run the repository's configuration generator: ```sh node scripts/print-mcp-config.mjs /absolute/example-target --kind database ``` It exits 0 and prints a registration whose environment includes the example path and database kind. The example path need not exist: this command only prints JSON. Both checks produced these results on two runs. Do not start the generated registration to reproduce this documentation omission. ### Expected behavior Keep a discoverable reference for the existing initial-target launch settings: the path, the accepted `executable` and `database` kinds, the default kind, and the fact that selecting a startup target opens it before MCP serving begins. Explain ordinary startup-open failure and the exclusion of these one-shot settings from setup's copied environment. The reference was present before the documentation-only change in PR #485. That change explicitly stated that CLI/MCP contracts and runtime behavior did not change. The current configuration generator and runtime still accept this configuration; the guides should describe it or explicitly state that it is unsupported. ### Impact and scope P3: users of the source-checkout generator cannot look up the meaning and startup effects of its two target fields in the guides. No consequential runtime failure was demonstrated. The normal target-free MCP workflow remains documented and accepts target selection through `open_binary`. The generator itself is excluded from the npm package's files list, so this finding does not claim that npm installations ship the helper. No target or provider was started, and effects of stale target paths on an actual client were not tested. ### REA version Exact `node scripts/rea.mjs --version` output: `6.8.0`. Source baseline: `65f1c447344a423fa2785847dbcea1e9a9e2454a`. ### Runtime and platform Node.js `v24.22.1`; macOS `27.0.1`; Darwin arm64. No provider runtime was used. ### Target and artifact context An illustrative absolute path supplied to a JSON printer. No target file or fixture is required. ### Interface MCP ### Earliest failure stage Unknown ### Relevant output or evidence The executed printer's relevant output was: ```json { "HOPPER_TARGET_PATH": "/absolute/example-target", "HOPPER_TARGET_KIND": "database" } ``` This is the `mcpServers.rea.env` object. The documentation search in step 1 returned no matches. Contract and history evidence: - `git show 36aeec958^:AGENTS.md`, lines 97-110, contains the initial-target server command and the explicit path/kind reference, including default `executable`. - Commit `36aeec95863ca28d3e3aa5bec75a45d3824e17f5`, merged in [PR #485](https://github.com/morluto/rea/pull/485), removes that catalog. The PR describes shortening the command/environment catalog and states that runtime and CLI/MCP contracts are unchanged. - At the baseline, `scripts/print-mcp-config.mjs:2-8,26-28` advertises client configuration and emits the pair. `package.json` retains `config:print` but does not package the helper. - `docs/mcp-contracts.md:737-745` describes cancellation and cleanup around initial-target startup; `docs/client-configuration.md:270-282` excludes one-shot target paths from setup's copied environment. Neither identifies the settings. Source-derived runtime behavior at the baseline: - `scripts/rea.mjs:31-33,63-65` routes `rea mcp` into the production MCP entry point. - `src/config/environment.ts:121-122` validates the path and kind; `src/config/parseConfig.ts:168-169` retains them. - `src/main.ts:109` selects eager startup when a target is supplied; `src/main/eagerRuntime.ts:103-114` opens it before starting the MCP transport. - `src/main/startup.ts:16-32` opens the requested path with the requested kind. An ordinary open failure returns exit 1; shutdown cancellation has a separate exit-0 path. ### Analysis or suspected cause The evidence supports a reference omission during documentation consolidation. The settings have a previously documented production entry point and remain in the configuration generator and startup parser, so their use is not confined to tests. Restoring a short guide reference would preserve the existing interface without changing runtime behavior. ### Additional context The duplicate search covered open and closed issues, all PR states, and issue comments. [Issue #6961](https://github.com/morluto/rea/issues/6961) concerns a different setting for Cutter bridge discovery. [Issue #4885](https://github.com/morluto/rea/issues/4885) and [PR #4884](https://github.com/morluto/rea/pull/4884) concern cancellation during initial-target startup, not the missing configuration reference. [Issue #653](https://github.com/morluto/rea/issues/653) concerns package-version pins in manual registrations.

bsakaguchi closed this issue

2026-10-31 00:50:53 +00:00

bsakaguchi referenced this issue

2026-10-31 01:13:30 +00:00

[PR #4571] fix(browser): retain runtime CDP cleanup status after retry #6315