morluto/rea

Fork 0

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

[GH-ISSUE #7644] [Bug] Hopper guide mentions loader overrides without documenting their setting #4568

New issue

Closed

opened 2026-10-31 00:50:51 +00:00 by bsakaguchi · 2 comments

bsakaguchi commented

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

Owner

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

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

The Hopper installation guide says configured loader arguments override derived arguments, but does not explain how to configure them. Searching the guides and README for HOPPER_LOADER_ARGS_JSON returns no matches.

The public command node scripts/rea.mjs setup --client cursor --dry-run --json recognizes that variable: with ["-l","Mach-O",""], I observed status: "planned" and a Cursor registration plan containing the same key and value. With not-json, I observed exit 1, status: "needs_human", and the constraint HOPPER_LOADER_ARGS_JSON must be valid JSON. Neither command applied changes.

Reproduction

From the baseline checkout with its existing built runtime and Node.js v24.22.1, run:
```
grep -rn HOPPER_LOADER_ARGS_JSON docs README.md
grep -n 'Configured loader arguments' docs/installation.md
```
The first command prints nothing and exits 1. The second finds the guide's override sentence.

Run the public setup dry runs with a disposable home and local package-runner fixtures first on PATH:

WORK=$(mktemp -d)
trap 'rm -rf "$WORK"' EXIT
mkdir -p "$WORK/bin" "$WORK/home" "$WORK/config" "$WORK/cache" "$WORK/data" "$WORK/state"
for runner in npx npm bun; do
  cat > "$WORK/bin/$runner" <<'SH'
#!/bin/sh
printf '%s\n' "$0 $*" >> "$RUNNER_LOG"
case "$1" in --version|-v) printf 'fixture\n'; exit 0;; esac
printf 'fixture: runner execution blocked\n' >&2
exit 99
SH
  chmod +x "$WORK/bin/$runner"
done
NODE_BIN=$(dirname "$(command -v node)")
run_plan() {
  env -i PATH="$WORK/bin:$NODE_BIN:/usr/bin:/bin:/usr/sbin:/sbin" \
    HOME="$WORK/home" XDG_CONFIG_HOME="$WORK/config" \
    XDG_CACHE_HOME="$WORK/cache" XDG_DATA_HOME="$WORK/data" \
    XDG_STATE_HOME="$WORK/state" RUNNER_LOG="$WORK/runners.log" \
    HOPPER_LOADER_ARGS_JSON="$1" \
    node scripts/rea.mjs setup --client cursor --dry-run --json
}
run_plan '["-l","Mach-O",""]' > "$WORK/valid.json"
printf 'valid exit: %s\n' "$?"
run_plan 'not-json' > "$WORK/invalid.json"
printf 'invalid exit: %s\n' "$?"
node --input-type=module - "$WORK" <<'JS'
import fs from 'node:fs';
const root = process.argv[2];
for (const name of ['valid', 'invalid']) {
  const result = JSON.parse(fs.readFileSync(`${root}/${name}.json`, 'utf8'));
  console.log(name, result.status, 'planned:', result.plannedActions.length,
    'applied:', result.appliedActions.length);
  console.log(result.plannedActions.find(a => a.id === 'configure_client:cursor')
    ?.detail.match(/HOPPER_LOADER_ARGS_JSON=\[[^\]]*\]/)?.[0]
    ?? result.remediation);
}
console.log('client written:', fs.existsSync(`${root}/home/.cursor/mcp.json`));
console.log('runner invoked:', fs.existsSync(`${root}/runners.log`));
JS

The valid case exits 0, prints valid planned planned: 2 applied: 0, and includes HOPPER_LOADER_ARGS_JSON=["-l","Mach-O",""]. The invalid case exits 1 and prints invalid needs_human planned: 0 applied: 0 with the named JSON constraint. The final checks print client written: false and runner invoked: false.

The documentation check ran once. Both setup cases produced these results in two independent disposable directories, 2/2 each. No Hopper or GUI application was launched.

Expected behavior

The Hopper guide should explain the configuration mechanism for the loader overrides it already describes: name HOPPER_LOADER_ARGS_JSON, give a valid JSON-array example, describe validation, and distinguish a nonempty override from the derived-arguments default. The setup guidance should make clear that an explicitly supplied value is forwarded into the proposed client registration.

This expectation concerns that specific incomplete explanation; the guide does not claim to enumerate every environment variable.

Impact and scope

The verified impact is missing configuration guidance. A reader can learn that loader overrides exist but cannot discover their environment key or syntax from the guides or README. The setting is accepted and explicitly selected for setup forwarding, so it is not merely a test-only input.

No analysis failure, incorrect loader choice, data loss, or inability to analyze a particular target was established. Reading the configuration parser and setup source reveals the setting today. This is a P3 documentation defect.

REA version

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

6.8.0

Source baseline: 65f1c447344a423fa2785847dbcea1e9a9e2454a.

Runtime and platform

Node.js v24.22.1; Darwin 27.0.0; arm64. The checkout's existing built runtime was used. No Hopper version or provider execution was tested.

Target and artifact context

No analysis target. Inputs were a loader-argument string and disposable setup directories.

Interface

Package or setup

Earliest failure stage

Unknown

Relevant output or evidence

grep -rn HOPPER_LOADER_ARGS_JSON docs README.md: no matches, exit 1. Searches for loader-argument terminology in the guides, design documents, and agent skill references found no equivalent configuration instructions.
docs/installation.md:912-923 describes loader selection and ends with “Configured loader arguments remain explicit overrides.” docs/client-configuration.md:270-281 describes forwarding selected provider settings without explaining this key.
The valid setup result's registration detail contains HOPPER_LOADER_ARGS_JSON=["-l","Mach-O",""]; applied actions are empty. The invalid result names HOPPER_LOADER_ARGS_JSON must be valid JSON with no planned or applied actions.
Source evidence: src/config/environment.ts:123,198-208 reads the key and passes it to the loader parser. src/config/parsers.ts:16-44 requires a JSON array of NUL-free strings and preserves empty elements. src/application/SetupRegistrationEnvironment.ts:4-10,87-95 explicitly selects it for client forwarding.
Source evidence: src/hopper/HopperAnalysisProfile.ts:144-154,196-199 derives arguments first, then uses a nonempty override and records loader.source: "configured_override"; an empty array keeps derived arguments. src/hopper/BridgeLauncher.ts:402-410 places these arguments before --analysis. These are source-derived semantics; no native launch was exercised.
scripts/print-mcp-config.mjs:3-8,24-30 shows another caller-facing use through its inline --loader-args helper, but the guide does not link or explain that option. Source inline usage does not supply the missing installation guidance.

Typed outcome or recovery expected

Add a short, accurate explanation and example alongside the existing loader-override sentence, including the empty-array default and setup forwarding behavior. Do not imply that overrides bypass loader-derivation or target-admission failures.

Additional context

Duplicate searches covered open and closed issues, PRs in all states, and issue comments. Related reports concern NUL validation (#2474), configuration diagnostics (#1199), stored-registration validation (#2665/#2769), and launch-setting recovery attribution (#7548). None reports this missing loader-setting documentation. Closed #6961 concerns the separate Cutter bridge directory setting.

Triage assessment

Impact level: P3
Assessment status: supported
Impact basis: The guide references an existing configuration capability without identifying its key or accepted syntax. The observed command behavior remains functional, and no consequential analysis failure was established.
Workaround status: available
Workaround basis: The parser, explicit setup allowlist, and configuration-printer source disclose the key and accepted array format; the valid public dry run accepted the supplied example.

Originally created by @coygeek on GitHub (Oct 28, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/7644 ### 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 The Hopper installation guide says configured loader arguments override derived arguments, but does not explain how to configure them. Searching the guides and README for `HOPPER_LOADER_ARGS_JSON` returns no matches. The public command `node scripts/rea.mjs setup --client cursor --dry-run --json` recognizes that variable: with `["-l","Mach-O",""]`, I observed `status: "planned"` and a Cursor registration plan containing the same key and value. With `not-json`, I observed exit 1, `status: "needs_human"`, and the constraint `HOPPER_LOADER_ARGS_JSON must be valid JSON`. Neither command applied changes. ### Reproduction 1. From the baseline checkout with its existing built runtime and Node.js v24.22.1, run: ```sh grep -rn HOPPER_LOADER_ARGS_JSON docs README.md grep -n 'Configured loader arguments' docs/installation.md ``` The first command prints nothing and exits 1. The second finds the guide's override sentence. 2. Run the public setup dry runs with a disposable home and local package-runner fixtures first on PATH: ```sh WORK=$(mktemp -d) trap 'rm -rf "$WORK"' EXIT mkdir -p "$WORK/bin" "$WORK/home" "$WORK/config" "$WORK/cache" "$WORK/data" "$WORK/state" for runner in npx npm bun; do cat > "$WORK/bin/$runner" <<'SH' #!/bin/sh printf '%s\n' "$0 $*" >> "$RUNNER_LOG" case "$1" in --version|-v) printf 'fixture\n'; exit 0;; esac printf 'fixture: runner execution blocked\n' >&2 exit 99 SH chmod +x "$WORK/bin/$runner" done NODE_BIN=$(dirname "$(command -v node)") run_plan() { env -i PATH="$WORK/bin:$NODE_BIN:/usr/bin:/bin:/usr/sbin:/sbin" \ HOME="$WORK/home" XDG_CONFIG_HOME="$WORK/config" \ XDG_CACHE_HOME="$WORK/cache" XDG_DATA_HOME="$WORK/data" \ XDG_STATE_HOME="$WORK/state" RUNNER_LOG="$WORK/runners.log" \ HOPPER_LOADER_ARGS_JSON="$1" \ node scripts/rea.mjs setup --client cursor --dry-run --json } run_plan '["-l","Mach-O",""]' > "$WORK/valid.json" printf 'valid exit: %s\n' "$?" run_plan 'not-json' > "$WORK/invalid.json" printf 'invalid exit: %s\n' "$?" node --input-type=module - "$WORK" <<'JS' import fs from 'node:fs'; const root = process.argv[2]; for (const name of ['valid', 'invalid']) { const result = JSON.parse(fs.readFileSync(`${root}/${name}.json`, 'utf8')); console.log(name, result.status, 'planned:', result.plannedActions.length, 'applied:', result.appliedActions.length); console.log(result.plannedActions.find(a => a.id === 'configure_client:cursor') ?.detail.match(/HOPPER_LOADER_ARGS_JSON=\[[^\]]*\]/)?.[0] ?? result.remediation); } console.log('client written:', fs.existsSync(`${root}/home/.cursor/mcp.json`)); console.log('runner invoked:', fs.existsSync(`${root}/runners.log`)); JS ``` The valid case exits 0, prints `valid planned planned: 2 applied: 0`, and includes `HOPPER_LOADER_ARGS_JSON=["-l","Mach-O",""]`. The invalid case exits 1 and prints `invalid needs_human planned: 0 applied: 0` with the named JSON constraint. The final checks print `client written: false` and `runner invoked: false`. The documentation check ran once. Both setup cases produced these results in two independent disposable directories, 2/2 each. No Hopper or GUI application was launched. ### Expected behavior The Hopper guide should explain the configuration mechanism for the loader overrides it already describes: name `HOPPER_LOADER_ARGS_JSON`, give a valid JSON-array example, describe validation, and distinguish a nonempty override from the derived-arguments default. The setup guidance should make clear that an explicitly supplied value is forwarded into the proposed client registration. This expectation concerns that specific incomplete explanation; the guide does not claim to enumerate every environment variable. ### Impact and scope The verified impact is missing configuration guidance. A reader can learn that loader overrides exist but cannot discover their environment key or syntax from the guides or README. The setting is accepted and explicitly selected for setup forwarding, so it is not merely a test-only input. No analysis failure, incorrect loader choice, data loss, or inability to analyze a particular target was established. Reading the configuration parser and setup source reveals the setting today. This is a P3 documentation defect. ### REA version Exact output of `node scripts/rea.mjs --version`: ```text 6.8.0 ``` Source baseline: `65f1c447344a423fa2785847dbcea1e9a9e2454a`. ### Runtime and platform Node.js v24.22.1; Darwin 27.0.0; arm64. The checkout's existing built runtime was used. No Hopper version or provider execution was tested. ### Target and artifact context No analysis target. Inputs were a loader-argument string and disposable setup directories. ### Interface Package or setup ### Earliest failure stage Unknown ### Relevant output or evidence - `grep -rn HOPPER_LOADER_ARGS_JSON docs README.md`: no matches, exit 1. Searches for loader-argument terminology in the guides, design documents, and agent skill references found no equivalent configuration instructions. - `docs/installation.md:912-923` describes loader selection and ends with “Configured loader arguments remain explicit overrides.” `docs/client-configuration.md:270-281` describes forwarding selected provider settings without explaining this key. - The valid setup result's registration detail contains `HOPPER_LOADER_ARGS_JSON=["-l","Mach-O",""]`; applied actions are empty. The invalid result names `HOPPER_LOADER_ARGS_JSON must be valid JSON` with no planned or applied actions. - Source evidence: `src/config/environment.ts:123,198-208` reads the key and passes it to the loader parser. `src/config/parsers.ts:16-44` requires a JSON array of NUL-free strings and preserves empty elements. `src/application/SetupRegistrationEnvironment.ts:4-10,87-95` explicitly selects it for client forwarding. - Source evidence: `src/hopper/HopperAnalysisProfile.ts:144-154,196-199` derives arguments first, then uses a nonempty override and records `loader.source: "configured_override"`; an empty array keeps derived arguments. `src/hopper/BridgeLauncher.ts:402-410` places these arguments before `--analysis`. These are source-derived semantics; no native launch was exercised. - `scripts/print-mcp-config.mjs:3-8,24-30` shows another caller-facing use through its inline `--loader-args` helper, but the guide does not link or explain that option. Source inline usage does not supply the missing installation guidance. ### Typed outcome or recovery expected Add a short, accurate explanation and example alongside the existing loader-override sentence, including the empty-array default and setup forwarding behavior. Do not imply that overrides bypass loader-derivation or target-admission failures. ### Additional context Duplicate searches covered open and closed issues, PRs in all states, and issue comments. Related reports concern NUL validation (#2474), configuration diagnostics (#1199), stored-registration validation (#2665/#2769), and launch-setting recovery attribution (#7548). None reports this missing loader-setting documentation. Closed #6961 concerns the separate Cutter bridge directory setting. ## Triage assessment - Impact level: P3 - Assessment status: supported - Impact basis: The guide references an existing configuration capability without identifying its key or accepted syntax. The observed command behavior remains functional, and no consequential analysis failure was established. - Workaround status: available - Workaround basis: The parser, explicit setup allowlist, and configuration-printer source disclose the key and accepted array format; the valid public dry run accepted the supplied example.

bsakaguchi commented

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

Author

Owner

@Varshavia commented on GitHub (Oct 30, 2026):

Checked current main (c5f50e80d; source-only): docs/installation.md (around line 931) now documents HOPPER_LOADER_ARGS_JSON as a JSON array of loader arguments, and the setting is defined in src/config/environment.ts. The merged PR #7902 ("docs(setup): restore target and Hopper launch settings") looks like the change that restored it, but I did not verify that attribution line by line. This looks resolved on main and may be closable.

@Varshavia commented on GitHub (Oct 30, 2026): Checked current `main` (c5f50e80d; source-only): `docs/installation.md` (around line 931) now documents `HOPPER_LOADER_ARGS_JSON` as a JSON array of loader arguments, and the setting is defined in `src/config/environment.ts`. The merged PR #7902 ("docs(setup): restore target and Hopper launch settings") looks like the change that restored it, but I did not verify that attribution line by line. This looks resolved on `main` and may be closable.

bsakaguchi closed this issue

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

bsakaguchi commented

2026-11-01 21:11:12 +00:00

Author

Owner

@coygeek commented on GitHub (Oct 31, 2026):

I checked this against the latest main. This issue appears resolved. The Hopper installation guide previously said only that configured loader arguments remain explicit overrides, without naming the setting or its syntax, and searching the guides and README for HOPPER_LOADER_ARGS_JSON found nothing. PR #7902 (merge commit 539a494d2, merged into main on 2026-10-29) adds exactly that missing guidance in docs/installation.md: it names HOPPER_LOADER_ARGS_JSON as a JSON array of strings set in REA's launch environment to override the derived Hopper loader arguments, with the example ["-l","Mach-O"], notes that empty string elements are preserved and NUL bytes are not accepted, states that an omitted setting or empty array uses the derived arguments, and states that rea setup forwards an explicitly selected setting to supported registrations, with a server restart needed to apply a change. I confirmed the new paragraph is present on live main. That covers the name, example, validation, default, and setup-forwarding explanation this issue asked for. Closing as resolved.

@coygeek commented on GitHub (Oct 31, 2026): I checked this against the latest main. This issue appears resolved. The Hopper installation guide previously said only that configured loader arguments remain explicit overrides, without naming the setting or its syntax, and searching the guides and README for `HOPPER_LOADER_ARGS_JSON` found nothing. [PR #7902](https://github.com/morluto/rea/pull/7902) (merge commit [`539a494d2`](https://github.com/morluto/rea/commit/539a494d25df3dc68e8d7bbadeea7edb527c4884), merged into `main` on 2026-10-29) adds exactly that missing guidance in `docs/installation.md`: it names `HOPPER_LOADER_ARGS_JSON` as a JSON array of strings set in REA's launch environment to override the derived Hopper loader arguments, with the example `["-l","Mach-O"]`, notes that empty string elements are preserved and NUL bytes are not accepted, states that an omitted setting or empty array uses the derived arguments, and states that `rea setup` forwards an explicitly selected setting to supported registrations, with a server restart needed to apply a change. I confirmed the new paragraph is present on live `main`. That covers the name, example, validation, default, and setup-forwarding explanation this issue asked for. Closing as resolved.

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

No description provided.

Rows
Columns