[PR #3760] fix(windows): name the missing native artifact and its recovery path on source checkouts #5879

Open
opened 2026-10-31 01:10:08 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/3760
Author: @Jackzigen
Created: 10/14/2026
Status: 🔄 Open

Base: main ← Head: fix/windows-native-manifest


📝 Commits (10+)

  • 2eaeb63 fix(windows): name the missing native artifact and its recovery path on source checkouts
  • 3ded799 fix(reference): never resolve a directory to an extensionless index (#3789)
  • 90c6922 fix(javascript): keep empty URL path segments significant (#3792)
  • 7a66470 fix(apple): report plist dates the decoder cannot represent as unknown (#3793)
  • af6a998 fix(javascript): keep string Worker paths unresolved without a document base (#3797)
  • 4692bb3 fix(reference): stop attributing overwritten require members to Node (#3801)
  • baad9ee fix(javascript): reject FIFO recovery inputs without blocking (#3788)
  • 847b732 fix(comparison): keep unnamed reference endpoints distinct or unknown (#3809)
  • 0781716 fix(cli): accept --flag=value for global output flags (#3811)
  • 4135c91 fix(javascript): keep recovered invalid templates dynamic in semantic effects (#3815)

📊 Changes

150 files changed (+9587 additions, -747 deletions)

View changed files

📝 docs/cli.md (+3 -1)
📝 docs/installation.md (+31 -0)
📝 docs/javascript-artifact-reconstruction.md (+8 -1)
📝 docs/native-investigation.md (+12 -1)
📝 licenses/npm-dependencies.txt (+6 -1)
📝 licenses/npm-runtime-notices.txt (+175 -1)
📝 package-lock.json (+19 -0)
📝 package.json (+1 -0)
📝 scripts/hopper-demo-x11.py (+12 -10)
📝 scripts/rea.mjs (+6 -4)
📝 scripts/verify-linux-setup-e2e.mjs (+15 -6)
📝 scripts/verify-package-environment.mjs (+9 -0)
📝 scripts/verify-package-platform.mjs (+20 -5)
📝 scripts/verify-real-hopper-fat.mjs (+1 -1)
📝 scripts/verify-real-hopper.mjs (+1 -1)
📝 src/apktool/ApktoolConfiguration.ts (+73 -21)
📝 src/apktool/ApktoolProvider.ts (+65 -4)
➕ src/apktool/ApktoolVersionProbe.lifecycle.test.ts (+107 -0)
➕ src/apktool/ApktoolVersionProbe.test.ts (+147 -0)
📝 src/application/Doctor.fixture.ts (+11 -1)

...and 80 more files

📄 Description

Summary

Fixes #3501.

A git source checkout on Windows failed every provider admission with a bare ENOENT on native/windows/build/manifest.json, because that directory is gitignored (only the Linux cross-compile lane and the npm tarball carry it). rea doctor also gave no artifact-specific remediation. This PR names the missing artifact and gives an actionable recovery path on source checkouts.

Problem and expected behavior

  • Trigger: install from a git clone on Windows, run any provider command (or rea doctor)
  • Old behavior: every provider rejected at admission with bare ENOENT on manifest.json; doctor hinted unsupported_host with no artifact-specific help
  • Expected: the error names the missing native artifact and tells the user how to get it (npm tarball install, or the documented cross-compile lane)

Change and scope

  • Detect the missing per-platform native manifest on Windows source checkouts and produce a ConfigurationError that names the missing file and lists the recovery paths (npm package install or the Linux cross-compile build lane documented in the README)
  • rea doctor surfaces the same artifact-specific remediation instead of a generic host hint

Follow the contribution scope: error-message and doctor improvements within existing boundaries — no target execution, injection, mutation, or protection recovery, so no maintainer scope decision is required (not applicable).

Contract and boundary impact

  • Semantic owner and earliest changed stage: config/admission layer; doctor output downstream
  • Contribution scope fit and linked maintainer decision: not applicable (ordinary fix within existing boundaries)
  • CLI and MCP/tool-catalog contract: no command or tool added or changed; error text improves
  • Provider, bridge, target-format, or platform compatibility: Windows source-checkout installs; npm tarball and Linux lanes unchanged
  • Evidence, artifact, provenance, or reconstruction contract: none
  • Target selection, authority, upstream behavior, and cleanup details: not applicable
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact: none

Expected effects (check known effects; use documentation-only on its own).

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject into a process or target.
  • Modify a target or its environment.
  • Send data over a network.
  • Modify this repository or workspace files.
  • none / documentation-only

Compatibility, safety, and release

  • Breaking changes or migration steps: none — error text and doctor output only
  • Real Hopper/Ghidra, browser, or OS coverage: Windows source-checkout scenario covered by tests
  • Package or release metadata impact: none
  • Security, privacy, process, or containment review: no new data exposure; errors name file paths only

Author readiness

Human owner: @Jackzigen

  • 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.
  • Related issue is linked: Fixes #3501.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • 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: the new error text naming the missing artifact and recovery paths.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

Problem

A git clone does not contain native/windows/build/ (gitignored by design — the README documents the Linux cross-compile lane), so a Windows source install rejected every provider at admission with a bare ENOENT on manifest.json, and rea doctor surfaced only an unsupported_host-adjacent hint with no artifact-specific remediation. The npm tarball ships both files, but nothing told the user that.

Changes

  • src/windows/WindowsNativeLoader.ts — the catch on artifact load now distinguishes ENOENT: the failure names the missing manifest.json + rea-windows-x64.node pair, explains why they are absent in source installs (gitignored; ship only in the npm package), and gives both recovery paths: npm run build:windows-native or copying the two files from the matching-version npm tarball into native/windows/build/.
  • src/process/WindowsAuthority.ts — the artifact stage remediation now also points source checkouts at native/windows/README.md.
  • native/windows/README.md — new "Source checkouts on Windows" section with the exact npm pack + tar --strip-components=3 command sequence.
  • Non-ENOENT artifact failures (integrity, PE checks, etc.) keep their original diagnostic text — only the missing-artifact case changed.

Safety

Admission still enforces package version, ABI, Node-API compatibility, PE32+ architecture, and SHA-256 after any manual copy — no validation was relaxed. This is a diagnostics-only change.

Verification

  • src/windows/WindowsNativeLoader.test.ts: +2 tests (ENOENT → actionable message, non-ENOENT unchanged); suite 22/22 green
  • src/ghidra/GhidraDoctor.test.ts: 16/16 green (remediation string still matches its stringContaining lock)
  • Full npm run test:fast: 7665 passed | 13 skipped, 0 failed
  • npx oxfmt clean; oxlint on touched files: 0 warnings 0 errors

🔄 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/3760 **Author:** [@Jackzigen](https://github.com/Jackzigen) **Created:** 10/14/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `fix/windows-native-manifest` --- ### 📝 Commits (10+) - [`2eaeb63`](https://github.com/morluto/rea/commit/2eaeb63f7ed70eac9f88bb6d64d9548cd66ede35) fix(windows): name the missing native artifact and its recovery path on source checkouts - [`3ded799`](https://github.com/morluto/rea/commit/3ded799bc7b9a588404913b4064aff8c1412a045) fix(reference): never resolve a directory to an extensionless index (#3789) - [`90c6922`](https://github.com/morluto/rea/commit/90c69229050cd251f86294a6f3ff5e22abf6912f) fix(javascript): keep empty URL path segments significant (#3792) - [`7a66470`](https://github.com/morluto/rea/commit/7a66470385636e57191f964ca584484e4bd01d34) fix(apple): report plist dates the decoder cannot represent as unknown (#3793) - [`af6a998`](https://github.com/morluto/rea/commit/af6a9980669129aae882c9216766fc8d9f544079) fix(javascript): keep string Worker paths unresolved without a document base (#3797) - [`4692bb3`](https://github.com/morluto/rea/commit/4692bb33300c7cb77b095b6cc0c33da861c1b860) fix(reference): stop attributing overwritten require members to Node (#3801) - [`baad9ee`](https://github.com/morluto/rea/commit/baad9eebe4c4a381be1e69ab0021acfea382f339) fix(javascript): reject FIFO recovery inputs without blocking (#3788) - [`847b732`](https://github.com/morluto/rea/commit/847b7328cf73907511acc71c554613af31a87b5b) fix(comparison): keep unnamed reference endpoints distinct or unknown (#3809) - [`0781716`](https://github.com/morluto/rea/commit/0781716788f553aba739b339560402b3fe8eb0ec) fix(cli): accept --flag=value for global output flags (#3811) - [`4135c91`](https://github.com/morluto/rea/commit/4135c911d3a3414b17fcd8954a15f6c7ec6ae8f4) fix(javascript): keep recovered invalid templates dynamic in semantic effects (#3815) ### 📊 Changes **150 files changed** (+9587 additions, -747 deletions) <details> <summary>View changed files</summary> 📝 `docs/cli.md` (+3 -1) 📝 `docs/installation.md` (+31 -0) 📝 `docs/javascript-artifact-reconstruction.md` (+8 -1) 📝 `docs/native-investigation.md` (+12 -1) 📝 `licenses/npm-dependencies.txt` (+6 -1) 📝 `licenses/npm-runtime-notices.txt` (+175 -1) 📝 `package-lock.json` (+19 -0) 📝 `package.json` (+1 -0) 📝 `scripts/hopper-demo-x11.py` (+12 -10) 📝 `scripts/rea.mjs` (+6 -4) 📝 `scripts/verify-linux-setup-e2e.mjs` (+15 -6) 📝 `scripts/verify-package-environment.mjs` (+9 -0) 📝 `scripts/verify-package-platform.mjs` (+20 -5) 📝 `scripts/verify-real-hopper-fat.mjs` (+1 -1) 📝 `scripts/verify-real-hopper.mjs` (+1 -1) 📝 `src/apktool/ApktoolConfiguration.ts` (+73 -21) 📝 `src/apktool/ApktoolProvider.ts` (+65 -4) ➕ `src/apktool/ApktoolVersionProbe.lifecycle.test.ts` (+107 -0) ➕ `src/apktool/ApktoolVersionProbe.test.ts` (+147 -0) 📝 `src/application/Doctor.fixture.ts` (+11 -1) _...and 80 more files_ </details> ### 📄 Description ## Summary Fixes #3501. A git source checkout on Windows failed every provider admission with a bare `ENOENT` on `native/windows/build/manifest.json`, because that directory is gitignored (only the Linux cross-compile lane and the npm tarball carry it). `rea doctor` also gave no artifact-specific remediation. This PR names the missing artifact and gives an actionable recovery path on source checkouts. ## Problem and expected behavior - **Trigger**: install from a git clone on Windows, run any provider command (or `rea doctor`) - **Old behavior**: every provider rejected at admission with bare `ENOENT` on `manifest.json`; doctor hinted `unsupported_host` with no artifact-specific help - **Expected**: the error names the missing native artifact and tells the user how to get it (npm tarball install, or the documented cross-compile lane) ## Change and scope - Detect the missing per-platform native manifest on Windows source checkouts and produce a `ConfigurationError` that names the missing file and lists the recovery paths (npm package install or the Linux cross-compile build lane documented in the README) - `rea doctor` surfaces the same artifact-specific remediation instead of a generic host hint Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope): error-message and doctor improvements within existing boundaries — no target execution, injection, mutation, or protection recovery, so no maintainer scope decision is required (not applicable). ## Contract and boundary impact - Semantic owner and earliest changed stage: config/admission layer; doctor output downstream - Contribution scope fit and linked maintainer decision: not applicable (ordinary fix within existing boundaries) - CLI and MCP/tool-catalog contract: no command or tool added or changed; error text improves - Provider, bridge, target-format, or platform compatibility: Windows source-checkout installs; npm tarball and Linux lanes unchanged - Evidence, artifact, provenance, or reconstruction contract: none - Target selection, authority, upstream behavior, and cleanup details: not applicable - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact: none Expected effects (check known effects; use documentation-only on its own). - [x] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject into a process or target. - [ ] Modify a target or its environment. - [ ] Send data over a network. - [ ] Modify this repository or workspace files. - [ ] none / documentation-only ## Compatibility, safety, and release - Breaking changes or migration steps: none — error text and doctor output only - Real Hopper/Ghidra, browser, or OS coverage: Windows source-checkout scenario covered by tests - Package or release metadata impact: none - Security, privacy, process, or containment review: no new data exposure; errors name file paths only ## Author readiness Human owner: @Jackzigen - [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 - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Related issue is linked: Fixes #3501. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output: the new error text naming the missing artifact and recovery paths. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- ## Problem A git clone does not contain `native/windows/build/` (gitignored by design — the README documents the Linux cross-compile lane), so a Windows **source** install rejected every provider at admission with a bare `ENOENT` on `manifest.json`, and `rea doctor` surfaced only an `unsupported_host`-adjacent hint with no artifact-specific remediation. The npm tarball ships both files, but nothing told the user that. ## Changes - **`src/windows/WindowsNativeLoader.ts`** — the catch on artifact load now distinguishes `ENOENT`: the failure names the missing `manifest.json` + `rea-windows-x64.node` pair, explains why they are absent in source installs (gitignored; ship only in the npm package), and gives both recovery paths: `npm run build:windows-native` or copying the two files from the matching-version npm tarball into `native/windows/build/`. - **`src/process/WindowsAuthority.ts`** — the `artifact` stage remediation now also points source checkouts at `native/windows/README.md`. - **`native/windows/README.md`** — new "Source checkouts on Windows" section with the exact `npm pack` + `tar --strip-components=3` command sequence. - Non-ENOENT artifact failures (integrity, PE checks, etc.) keep their original diagnostic text — only the missing-artifact case changed. ## Safety Admission still enforces package version, ABI, Node-API compatibility, PE32+ architecture, and SHA-256 after any manual copy — no validation was relaxed. This is a diagnostics-only change. ## Verification - `src/windows/WindowsNativeLoader.test.ts`: +2 tests (ENOENT → actionable message, non-ENOENT unchanged); suite 22/22 green - `src/ghidra/GhidraDoctor.test.ts`: 16/16 green (remediation string still matches its `stringContaining` lock) - Full `npm run test:fast`: **7665 passed | 13 skipped, 0 failed** - `npx oxfmt` clean; `oxlint` on touched files: 0 warnings 0 errors --- <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#5879
No description provided.