[PR #7473] feat(install): warn when installed rea is not on PATH #7861

Open
opened 2026-11-05 01:48:12 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/7473
Author: @DeryFerd
Created: 10/27/2026
Status: 🔄 Open

Base: main ← Head: fix/install-warn-when-rea-off-path


📝 Commits (1)

  • 3eca571 feat(install): warn when installed rea is not on PATH

📊 Changes

2 files changed (+41 additions, -0 deletions)

View changed files

📝 install.sh (+4 -0)
📝 tests/boundary/filesystem/installScript.test.ts (+37 -0)

📄 Description

Summary

Installing REA via install.sh verifies the installed binary through its full path but never checks whether rea resolves on PATH. A fresh install can print REA X is installed while a bare rea still fails with command not found, forcing the operator to discover the missing PATH entry by trial and error. This PR adds one PATH admission note after a successful install: when command -v rea fails, the installer prints the unreachable command path and its directory, plus how to add it to PATH. Behavior is unchanged when rea already resolves on PATH. No related issue exists; this is a standalone installer UX improvement discovered while testing local setup.

Problem and expected behavior

The smallest trigger is running bash install.sh on a host where npm's install prefix (for example $HOME/.local on Linux or npm prefix --global on macOS) is not on the shell PATH. The previous behavior prints REA X is installed and then Run <full-path> setup; typing bare rea afterward fails. The expected behavior is for the installer itself to say the command is not on PATH, show where it was installed, and tell the operator exactly what to add to PATH — all on stdout, keeping stderr empty so existing TTY and truncation-guard expectations stay intact.

Change and scope

The chosen approach is additive and idempotent: after version verification succeeds, install.sh runs command -v rea; on failure it prints the NOTE line and the Add ... to PATH line, then continues to the existing setup-or-hint branch. Nothing is removed, no command flags change, and no package metadata or catalog is regenerated. Follow the contribution scope at https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope. Unresolved scope, authority, side effects, or required verification block integration. Link the required maintainer scope decision for new providers or capabilities involving target execution, injection, mutation, or protection recovery; ordinary fixes within existing boundaries state not applicable. Draft PRs may leave the scope decision pending and the readiness and merge checklists unchecked. Maintainers can help resolve open questions.

Contract and boundary impact

  • Semantic owner and earliest changed stage: install.sh post-install verification step (the stage that reports REA X is installed); consumer is the human operator's shell and tests/boundary/filesystem/installScript.test.ts. No superseded paths removed; no distinct policy, lifecycle, lazy-loading, or compatibility responsibility retained.
  • Contribution scope fit and linked maintainer decision: not applicable — routine documentation/usability change within existing boundaries (installer output only).
  • CLI and MCP/tool-catalog contract: none — no CLI flags, input schemas, MCP tools, or catalog entries change; rea setup keeps using the full path hint.
  • Provider, bridge, target-format, or platform compatibility: POSIX bash installer only (macOS/Linux via curl|bash); uses the command -v POSIX builtin. Windows installs through npm/packaged paths outside install.sh scope.
  • Evidence, artifact, provenance, or reconstruction contract: none — installer emits a static note with no target data.
  • Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable.
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact (CI generates and validates ignored catalogs and skills/; edit authored instructions in .agents/skills/reverse-engineer-anything/ and never commit build outputs): none — install.sh is already listed in package files; content change only, no version bump, no catalog/skill regeneration, ignored outputs untouched and uncommitted.

Expected effects (check known effects; use documentation-only on its own). Unchecked items do not establish absence; leave uncertainties visible.

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

Tests added or updated: tests/boundary/filesystem/installScript.test.ts — new installer PATH report describe block with two cases: NOTE emitted on stdout when the install prefix is off PATH, and silent output when rea already resolves on PATH.

Base reproduction or other evidence: local Git Bash harness with fake node/npm/curl/uname/rea-source stubs in an isolated HOME, running install.sh --version 0.3.0 --no-setup; observed NOTE present on stdout (exit 0, stderr empty) when PATH lacks the prefix, and absent with empty stderr when PATH includes it; truncation guard intact (closing } remains the final byte).

User-visible CLI/MCP output (if applicable): installer stdout now includes NOTE: the installed command is not on PATH: <path>/bin/rea followed by Add <path>/bin to PATH to run rea without a path.

Remaining proof gaps: the vitest suite for tests/boundary/filesystem/installScript.test.ts could not run on this Windows host — all 43 tests fail fixture setup with EPERM creating POSIX symlinks (a pre-existing host limitation that applies equally to the unmodified file); per CONTRIBUTING Windows source checkouts, POSIX-path fixture suites run on the Linux CI lane instead. npm run verify:package and npm pack --dry-run did not complete on this host (packaging harness failure), so CI owns packaging validation per CONTRIBUTING.

For boundary fixes, identify the applicable boundary regressions at docs/testing.md#boundary-regressions and lifecycle regressions at docs/testing.md#lifecycle-regressions covered by the evidence above, and explain relevant gaps. Not a parser/inventory/snapshot/projection fix; the closest class is public success and error delivery (public installer success path and its representative output), covered by the two new test cases; other failure classes are not applicable to an installer message.

For evidence-bearing changes:

  • Observed, derived, and inferred claims remain distinguishable.
  • Artifact identity, source provenance, and failed attempts remain preserved.
  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

List only commands that actually ran, with observed results. Include the relevant real-provider or platform workflow, or explain why it was unavailable.

  • bash install.sh --version 0.3.0 --no-setup in an isolated Git Bash harness with PATH lacking the install prefix — NOTE printed on stdout, exit code 0, stderr empty (was absent before the change).
  • bash install.sh --version 0.3.0 --no-setup with PATH including the prefix — no NOTE, exit code 0, stderr empty (quiet behavior unchanged).
  • Truncation guard verified: closing brace group remains the final bytes of install.sh, so curl ... | bash short-download safety is preserved.
  • npx oxlint tests/boundary/filesystem/installScript.test.ts — 0 warnings, 0 errors.
  • npm run lint — exit 0, 0 errors across 5,676 files; module-boundary verification passed.
  • node scripts/run-typescript.mjs --noEmit -p .tmp-tsconfig.json with a narrow config including the changed test file — no errors attributable to this change; one unrelated pre-existing error in src/frida/FridaInstrumentationManager.ts because the optional frida dependency is not installed on this checkout (postinstall blocked by allowScripts).
  • NOT run on this host: npm run test:focused -- tests/boundary/filesystem/installScript.test.ts — fixture symlinks fail with EPERM on Windows for all 43 tests including pre-existing ones; Linux CI lane runs POSIX fixtures. npm run verify:package and npm pack --dry-run — packaging harness does not complete on this host; CI validates generated outputs per CONTRIBUTING packaging/setup/distribution requirements.

Compatibility, safety, and release

Call out breaking changes, migrations, package effects, platform/provider limits, security/privacy/containment implications, and meaningful proof gaps.

  • Breaking changes or migration steps: none — additive stdout message only; no CLI flags, input schemas, MCP tools, or migration steps; every existing invocation keeps working.
  • Real Hopper/Ghidra, browser, or OS coverage: none — installer-only change with no target interaction, no engine workflows, and no provider paths touched.
  • Package or release metadata impact: install.sh ships in package files; content change only, no version bump (6.8.0 unchanged), no catalog or skill regeneration; ignored outputs docs/public/product-catalog.json, docs/verification/managed-conformance-*.json, and skills/ remain untouched and uncommitted.
  • Security, privacy, process, or containment review: none — command -v is a read-only PATH probe; no secrets, credentials, target execution, injection, mutation, or protection recovery involved.

Author readiness

The human owner completes these declarations before requesting review. The PR author is the owner by default. AI agents leave these declarations to a human to dictate to them.

Human owner: @DeryFerd

  • 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

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🔄 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/7473 **Author:** [@DeryFerd](https://github.com/DeryFerd) **Created:** 10/27/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `fix/install-warn-when-rea-off-path` --- ### 📝 Commits (1) - [`3eca571`](https://github.com/morluto/rea/commit/3eca57125682afe59bec1ff53c757df89d4f4dce) feat(install): warn when installed rea is not on PATH ### 📊 Changes **2 files changed** (+41 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `install.sh` (+4 -0) 📝 `tests/boundary/filesystem/installScript.test.ts` (+37 -0) </details> ### 📄 Description ## Summary Installing REA via `install.sh` verifies the installed binary through its full path but never checks whether `rea` resolves on PATH. A fresh install can print `REA X is installed` while a bare `rea` still fails with command not found, forcing the operator to discover the missing PATH entry by trial and error. This PR adds one PATH admission note after a successful install: when `command -v rea` fails, the installer prints the unreachable command path and its directory, plus how to add it to PATH. Behavior is unchanged when `rea` already resolves on PATH. No related issue exists; this is a standalone installer UX improvement discovered while testing local setup. ## Problem and expected behavior The smallest trigger is running `bash install.sh` on a host where npm's install prefix (for example `$HOME/.local` on Linux or `npm prefix --global` on macOS) is not on the shell PATH. The previous behavior prints `REA X is installed` and then `Run <full-path> setup`; typing bare `rea` afterward fails. The expected behavior is for the installer itself to say the command is not on PATH, show where it was installed, and tell the operator exactly what to add to PATH — all on stdout, keeping stderr empty so existing TTY and truncation-guard expectations stay intact. ## Change and scope The chosen approach is additive and idempotent: after version verification succeeds, `install.sh` runs `command -v rea`; on failure it prints the NOTE line and the `Add ... to PATH` line, then continues to the existing setup-or-hint branch. Nothing is removed, no command flags change, and no package metadata or catalog is regenerated. Follow the contribution scope at https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope. Unresolved scope, authority, side effects, or required verification block integration. Link the required maintainer scope decision for new providers or capabilities involving target execution, injection, mutation, or protection recovery; ordinary fixes within existing boundaries state not applicable. Draft PRs may leave the scope decision pending and the readiness and merge checklists unchecked. Maintainers can help resolve open questions. ## Contract and boundary impact - Semantic owner and earliest changed stage: `install.sh` post-install verification step (the stage that reports `REA X is installed`); consumer is the human operator's shell and `tests/boundary/filesystem/installScript.test.ts`. No superseded paths removed; no distinct policy, lifecycle, lazy-loading, or compatibility responsibility retained. - Contribution scope fit and linked maintainer decision: not applicable — routine documentation/usability change within existing boundaries (installer output only). - CLI and MCP/tool-catalog contract: none — no CLI flags, input schemas, MCP tools, or catalog entries change; `rea setup` keeps using the full path hint. - Provider, bridge, target-format, or platform compatibility: POSIX bash installer only (macOS/Linux via curl|bash); uses the `command -v` POSIX builtin. Windows installs through npm/packaged paths outside install.sh scope. - Evidence, artifact, provenance, or reconstruction contract: none — installer emits a static note with no target data. - Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact (CI generates and validates ignored catalogs and `skills/`; edit authored instructions in `.agents/skills/reverse-engineer-anything/` and never commit build outputs): none — `install.sh` is already listed in package `files`; content change only, no version bump, no catalog/skill regeneration, ignored outputs untouched and uncommitted. Expected effects (check known effects; use documentation-only on its own). Unchecked items do not establish absence; leave uncertainties visible. - [x] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [ ] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage Tests added or updated: `tests/boundary/filesystem/installScript.test.ts` — new `installer PATH report` describe block with two cases: NOTE emitted on stdout when the install prefix is off PATH, and silent output when `rea` already resolves on PATH. Base reproduction or other evidence: local Git Bash harness with fake node/npm/curl/uname/rea-source stubs in an isolated HOME, running `install.sh --version 0.3.0 --no-setup`; observed NOTE present on stdout (exit 0, stderr empty) when PATH lacks the prefix, and absent with empty stderr when PATH includes it; truncation guard intact (closing `}` remains the final byte). User-visible CLI/MCP output (if applicable): installer stdout now includes `NOTE: the installed command is not on PATH: <path>/bin/rea` followed by `Add <path>/bin to PATH to run rea without a path.` Remaining proof gaps: the vitest suite for `tests/boundary/filesystem/installScript.test.ts` could not run on this Windows host — all 43 tests fail fixture setup with EPERM creating POSIX symlinks (a pre-existing host limitation that applies equally to the unmodified file); per CONTRIBUTING Windows source checkouts, POSIX-path fixture suites run on the Linux CI lane instead. `npm run verify:package` and `npm pack --dry-run` did not complete on this host (packaging harness failure), so CI owns packaging validation per CONTRIBUTING. For boundary fixes, identify the applicable boundary regressions at docs/testing.md#boundary-regressions and lifecycle regressions at docs/testing.md#lifecycle-regressions covered by the evidence above, and explain relevant gaps. Not a parser/inventory/snapshot/projection fix; the closest class is public success and error delivery (public installer success path and its representative output), covered by the two new test cases; other failure classes are not applicable to an installer message. For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed List only commands that actually ran, with observed results. Include the relevant real-provider or platform workflow, or explain why it was unavailable. - `bash install.sh --version 0.3.0 --no-setup` in an isolated Git Bash harness with PATH lacking the install prefix — NOTE printed on stdout, exit code 0, stderr empty (was absent before the change). - `bash install.sh --version 0.3.0 --no-setup` with PATH including the prefix — no NOTE, exit code 0, stderr empty (quiet behavior unchanged). - Truncation guard verified: closing brace group remains the final bytes of `install.sh`, so `curl ... | bash` short-download safety is preserved. - `npx oxlint tests/boundary/filesystem/installScript.test.ts` — 0 warnings, 0 errors. - `npm run lint` — exit 0, 0 errors across 5,676 files; module-boundary verification passed. - `node scripts/run-typescript.mjs --noEmit -p .tmp-tsconfig.json` with a narrow config including the changed test file — no errors attributable to this change; one unrelated pre-existing error in `src/frida/FridaInstrumentationManager.ts` because the optional `frida` dependency is not installed on this checkout (postinstall blocked by `allowScripts`). - NOT run on this host: `npm run test:focused -- tests/boundary/filesystem/installScript.test.ts` — fixture symlinks fail with EPERM on Windows for all 43 tests including pre-existing ones; Linux CI lane runs POSIX fixtures. `npm run verify:package` and `npm pack --dry-run` — packaging harness does not complete on this host; CI validates generated outputs per CONTRIBUTING packaging/setup/distribution requirements. ## Compatibility, safety, and release Call out breaking changes, migrations, package effects, platform/provider limits, security/privacy/containment implications, and meaningful proof gaps. - Breaking changes or migration steps: none — additive stdout message only; no CLI flags, input schemas, MCP tools, or migration steps; every existing invocation keeps working. - Real Hopper/Ghidra, browser, or OS coverage: none — installer-only change with no target interaction, no engine workflows, and no provider paths touched. - Package or release metadata impact: `install.sh` ships in package `files`; content change only, no version bump (6.8.0 unchanged), no catalog or skill regeneration; ignored outputs `docs/public/product-catalog.json`, `docs/verification/managed-conformance-*.json`, and `skills/` remain untouched and uncommitted. - Security, privacy, process, or containment review: none — `command -v` is a read-only PATH probe; no secrets, credentials, target execution, injection, mutation, or protection recovery involved. ## Author readiness The human owner completes these declarations before requesting review. The PR author is the owner by default. AI agents leave these declarations to a human to dictate to them. Human owner: @DeryFerd - [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 - [ ] This PR addresses a concrete problem or an agreed enhancement. - [ ] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [ ] The PR has one focused outcome and the title follows `type(scope): outcome`. - [ ] Related issue is linked, or the reason for not linking one is stated above. - [ ] Tests cover changed observable behavior and meaningful failure paths. - [ ] Owning docs, contracts, and generated metadata are updated where needed. - [ ] User-visible CLI/MCP changes include representative output. - [ ] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Sign in to join this conversation.
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#7861
No description provided.