[PR #848] [MERGED] feat(javascript): recover readable modules with Wakaru #2286

New issue

Closed

opened 2026-10-16 21:16:46 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:16:46 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/848
Author: @N0zoM1z0
Created: 10/7/2026
Status: ✅ Merged
Merged: 10/7/2026
Merged by: @N0zoM1z0

Base: main ← Head: feat/javascript-source-recovery

📝 Commits (5)

ab49e24 feat(javascript): recover readable modules with Wakaru
4d97e31 fix(javascript): align recovery catalog and browser verification
73b90af refactor(javascript): consume the investigation evidence writer
ca1d136 chore(test): account for isolated recovery fixture compilers
c4accfa fix(javascript): validate recovery paths before acquiring the engine

📊 Changes

60 files changed (+2840 additions, -25 deletions)

View changed files

📝 .github/workflows/real-browser.yml (+1 -0)
➕ .github/workflows/real-javascript-recovery.yml (+69 -0)
📝 .gitmodules (+3 -0)
📝 .oxlintrc.json (+6 -2)
📝 README.md (+6 -1)
📝 README_ar.md (+1 -1)
📝 README_ja.md (+1 -1)
📝 README_ko.md (+1 -1)
📝 README_zh.md (+1 -1)
➕ docs/javascript-recovery.md (+90 -0)
📝 docs/product-catalog.json (+16 -8)
📝 docs/testing.md (+14 -0)
📝 docs/verification/managed-conformance-manifest.json (+2 -2)
📝 knip.json (+1 -1)
📝 package.json (+2 -1)
➕ scripts/fixtures/javascript-recovery/entry.mjs (+3 -0)
➕ scripts/fixtures/javascript-recovery/helpers.mjs (+6 -0)
📝 scripts/lib/catalog-builders.mjs (+7 -0)
📝 scripts/lib/catalog-core.mjs (+3 -0)
➕ scripts/lib/javascript-recovery-fixtures.mjs (+104 -0)

...and 40 more files

📄 Description

Outcome

Adds recover_javascript_sources / recover-javascript-sources: derive readable modules from a selected local JavaScript bundle, preserve its byte identity and extraction provenance, and return the arguments for existing JS analysis inline.

Fixes #827; refs #774.

Boundaries

Shared provider-neutral contract/workflow behind JavaScriptRecoveryPort; optional target-free composition factory. Wakaru protocol/process/files/publication remain separate adapter modules.
Unchanged Apache-2.0 upstream submodule pinned to v1.13.0 (6070266d24b32951fa2fe1d2dad5b4313bd5c81b). Caller-supplied executable required; executed binary/version fingerprinted, executed source revision explicitly unknown. No global installation or input/recovered-code execution.
Owned private snapshot/staging; exact producer report parsing, regular-file/module/range checks, original and engine identity checks, cancellation/cleanup, exclusive verified publication and rollback. One worker and bounded execution/resources. Version probe and recovery share a 120-second execution budget.
Complete derived files/digests/maps/warnings/provenance inline. Structural splitting can fall back to one file; original names, map accuracy and arbitrary runtime equivalence remain unknown. Valid partial reports retain their failures and files.
New conditional real Wakaru CI lane installs pinned/checksummed release and isolated fixture compilers. Existing real Chrome lane gains its missing standalone DOM-verifier trigger; its page disconnect check now waits for the existing observation-ready progress event instead of a fixed 100ms delay.

MCP example

{"path":"/tmp/web-scripts/app.js","output_directory":"/tmp/recovered-app"}

The inline result includes analysis_input such as:

{"input_path":"/tmp/recovered-app/modules","format":"directory"}

Pass that object to analyze_javascript_application.

Verification

Rebased onto main bef4321a, preserving optional-provider diagnostics, the new investigation record owner and firmware/path/plist updates. The recovery registrar uses the narrow EvidenceWriter port. Focused post-rebase runs passed: 70 tests across 7 files on the first integration; 18 tests across 4 files on the latest integration, plus an SDK test asserting real record ownership.
Scoped domain/service/contract/producer/MCP and compiled CLI acceptance tests; 48 tests in the initial complete focused run, 60 tests in the final schema/availability/import-boundary run. Final producer/MCP run: 24 tests; deadline/producer run: 25 tests.
Post-rebase npm run check:fast, generated docs checks and test discovery (494 files exactly once) passed.
Actual official Wakaru 1.13.0 Linux x64 (SHA-256 e8c7ca052974604197389f6ace7464e4dd24dce64e2730971521bd6606ec9c9e), genuine esbuild 0.25.10 and webpack 5.101.3 fixtures.
Post-rebase real source-built CLI + stdio MCP passed all 10 cases; npm-packed and locally installed artifact: all 10 combinations pass, including heuristic/aggressive and inspection/minimal. Byte/map/report/manifest readback and reuse by existing JS analysis verified. Finite controlled-fixture results match for executable fixtures; inspection output is never executed. No arbitrary equivalence claim.
After initial CI findings, catalog/service/producer regressions: 41 tests passed; full formatting check passed. Provider identity is shared with generated catalog and CLI mode options are self-describing. Full local real Chrome lane passed, including network/script/DOM/screenshot/CLI/MCP and owned cleanup.
Final source review found and fixed relative-path validation ordering: 2 failing-before regressions; service and compiled CLI/MCP parity now pass 13 tests. Invalid paths return field-specific invalid_format before engine acquisition. Exact external fixture compiler dependencies accounted for in Knip; no root toolchain dependencies or installs.
No game data/binaries, dist, node_modules, local plans or tool executables tracked. Real Hopper/Ghidra not run for this unrelated adapter.

_{🔄 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/848 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/7/2026 **Status:** ✅ Merged **Merged:** 10/7/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `feat/javascript-source-recovery` --- ### 📝 Commits (5) - [`ab49e24`](https://github.com/morluto/rea/commit/ab49e2406ac6535ab37112b9134c01b39643df48) feat(javascript): recover readable modules with Wakaru - [`4d97e31`](https://github.com/morluto/rea/commit/4d97e3103937e1fea9bb5244ccdc9dacee02c2a4) fix(javascript): align recovery catalog and browser verification - [`73b90af`](https://github.com/morluto/rea/commit/73b90af51a0135426acb6ee16f6e9386bae3847f) refactor(javascript): consume the investigation evidence writer - [`ca1d136`](https://github.com/morluto/rea/commit/ca1d13641e659cdf13c75db8d22e6c1e4f9dce18) chore(test): account for isolated recovery fixture compilers - [`c4accfa`](https://github.com/morluto/rea/commit/c4accfaa74835656ebbf377175aa32f1d7d89261) fix(javascript): validate recovery paths before acquiring the engine ### 📊 Changes **60 files changed** (+2840 additions, -25 deletions) <details> <summary>View changed files</summary> 📝 `.github/workflows/real-browser.yml` (+1 -0) ➕ `.github/workflows/real-javascript-recovery.yml` (+69 -0) 📝 `.gitmodules` (+3 -0) 📝 `.oxlintrc.json` (+6 -2) 📝 `README.md` (+6 -1) 📝 `README_ar.md` (+1 -1) 📝 `README_ja.md` (+1 -1) 📝 `README_ko.md` (+1 -1) 📝 `README_zh.md` (+1 -1) ➕ `docs/javascript-recovery.md` (+90 -0) 📝 `docs/product-catalog.json` (+16 -8) 📝 `docs/testing.md` (+14 -0) 📝 `docs/verification/managed-conformance-manifest.json` (+2 -2) 📝 `knip.json` (+1 -1) 📝 `package.json` (+2 -1) ➕ `scripts/fixtures/javascript-recovery/entry.mjs` (+3 -0) ➕ `scripts/fixtures/javascript-recovery/helpers.mjs` (+6 -0) 📝 `scripts/lib/catalog-builders.mjs` (+7 -0) 📝 `scripts/lib/catalog-core.mjs` (+3 -0) ➕ `scripts/lib/javascript-recovery-fixtures.mjs` (+104 -0) _...and 40 more files_ </details> ### 📄 Description ## Outcome Adds `recover_javascript_sources` / `recover-javascript-sources`: derive readable modules from a selected local JavaScript bundle, preserve its byte identity and extraction provenance, and return the arguments for existing JS analysis inline. Fixes #827; refs #774. ## Boundaries - Shared provider-neutral contract/workflow behind JavaScriptRecoveryPort; optional target-free composition factory. Wakaru protocol/process/files/publication remain separate adapter modules. - Unchanged Apache-2.0 upstream submodule pinned to v1.13.0 (`6070266d24b32951fa2fe1d2dad5b4313bd5c81b`). Caller-supplied executable required; executed binary/version fingerprinted, executed source revision explicitly unknown. No global installation or input/recovered-code execution. - Owned private snapshot/staging; exact producer report parsing, regular-file/module/range checks, original and engine identity checks, cancellation/cleanup, exclusive verified publication and rollback. One worker and bounded execution/resources. Version probe and recovery share a 120-second execution budget. - Complete derived files/digests/maps/warnings/provenance inline. Structural splitting can fall back to one file; original names, map accuracy and arbitrary runtime equivalence remain unknown. Valid partial reports retain their failures and files. - New conditional real Wakaru CI lane installs pinned/checksummed release and isolated fixture compilers. Existing real Chrome lane gains its missing standalone DOM-verifier trigger; its page disconnect check now waits for the existing observation-ready progress event instead of a fixed 100ms delay. ### MCP example ```json {"path":"/tmp/web-scripts/app.js","output_directory":"/tmp/recovered-app"} ``` The inline result includes `analysis_input` such as: ```json {"input_path":"/tmp/recovered-app/modules","format":"directory"} ``` Pass that object to `analyze_javascript_application`. ## Verification - Rebased onto main `bef4321a`, preserving optional-provider diagnostics, the new investigation record owner and firmware/path/plist updates. The recovery registrar uses the narrow EvidenceWriter port. Focused post-rebase runs passed: 70 tests across 7 files on the first integration; 18 tests across 4 files on the latest integration, plus an SDK test asserting real record ownership. - Scoped domain/service/contract/producer/MCP and compiled CLI acceptance tests; 48 tests in the initial complete focused run, 60 tests in the final schema/availability/import-boundary run. Final producer/MCP run: 24 tests; deadline/producer run: 25 tests. - Post-rebase `npm run check:fast`, generated docs checks and test discovery (494 files exactly once) passed. - Actual official Wakaru 1.13.0 Linux x64 (SHA-256 `e8c7ca052974604197389f6ace7464e4dd24dce64e2730971521bd6606ec9c9e`), genuine esbuild 0.25.10 and webpack 5.101.3 fixtures. - Post-rebase real source-built CLI + stdio MCP passed all 10 cases; npm-packed and locally installed artifact: all 10 combinations pass, including heuristic/aggressive and inspection/minimal. Byte/map/report/manifest readback and reuse by existing JS analysis verified. Finite controlled-fixture results match for executable fixtures; inspection output is never executed. No arbitrary equivalence claim. - After initial CI findings, catalog/service/producer regressions: 41 tests passed; full formatting check passed. Provider identity is shared with generated catalog and CLI mode options are self-describing. Full local real Chrome lane passed, including network/script/DOM/screenshot/CLI/MCP and owned cleanup. - Final source review found and fixed relative-path validation ordering: 2 failing-before regressions; service and compiled CLI/MCP parity now pass 13 tests. Invalid paths return field-specific invalid_format before engine acquisition. Exact external fixture compiler dependencies accounted for in Knip; no root toolchain dependencies or installs. - No game data/binaries, dist, node_modules, local plans or tool executables tracked. Real Hopper/Ghidra not run for this unrelated adapter. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:16:46 +00:00