[PR #2717] feat(java): inspect archives and decompile selected classes #5340

New issue

Open

opened 2026-10-31 01:05:51 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:05:51 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2717
Author: @nadezhdkov
Created: 10/13/2026
Status: 🔄 Open

Base: main ← Head: feat/java-archives

📝 Commits (10+)

f45b9c1 chore: add CLAUDE.md and mirror agent skills under .claude
ac3abfb feat(java): inspect and decompile JAR and class files
b10094d chore: resync .claude skills mirror with upstream skills
8fd666a fix(java): preserve archive identity and cleanup ownership
89a141b fix(java): reconcile archive readers with current main error semantics
3788b46 fix(java): preserve malformed matching class coordinates
ffc7918 fix(java): preserve archive identities and bounded parser evidence
5405f0c fix(java): budget retained facts and preserve exact selections
b095795 fix(java): bound archive summary resources
14a091a fix(comparison): recheck historical calls-only changes (#2223)

📊 Changes

48 files changed (+5925 additions, -7 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+7 -0)
📝 .agents/skills/reverse-engineer-anything/references/native-and-artifacts.md (+17 -0)
➕ .claude/skills/rea-changelog-update/SKILL.md (+134 -0)
➕ .claude/skills/rea-tool-design/SKILL.md (+20 -0)
➕ .claude/skills/reverse-engineer-anything/SKILL.md (+292 -0)
➕ .claude/skills/reverse-engineer-anything/references/android-applications.md (+34 -0)
➕ .claude/skills/reverse-engineer-anything/references/connection-and-recovery.md (+127 -0)
➕ .claude/skills/reverse-engineer-anything/references/evidence-workflows.md (+67 -0)
➕ .claude/skills/reverse-engineer-anything/references/javascript-applications.md (+175 -0)
➕ .claude/skills/reverse-engineer-anything/references/native-and-artifacts.md (+263 -0)
➕ .claude/skills/reverse-engineer-anything/references/runtime-observation.md (+43 -0)
➕ CLAUDE.md (+7 -0)
📝 README.md (+1 -0)
📝 docs/.vitepress/config.ts (+1 -0)
📝 docs/cli.md (+8 -0)
➕ docs/java-archives.md (+168 -0)
📝 scripts/lib/catalog-builders.mjs (+13 -0)
📝 scripts/lib/catalog-core.mjs (+2 -0)
📝 scripts/lib/module-boundaries.mjs (+1 -0)
📝 src/application/CapabilityInventory.ts (+14 -1)

...and 28 more files

📄 Description

Summary

Add local JVM archive and class-file inspection through shared CLI/MCP workflows, plus optional source reconstruction with a caller-supplied Vineflower engine. Analysts can inventory a JAR, WAR/EAR or standalone .class, select a class, and inspect declared structure without loading or executing target bytecode.

This is @nadezhdkov's contribution on feat/java-archives; the existing contributor commits and authorship remain in branch history. Follow-up commits address review findings and reconcile upstream changes. No issue or maintainer scope decision is linked yet.

Behavior and contracts

inspect_java_archive / inspect-java-archive returns manifest and bounded framework descriptors, entry counts, bytecode versions, packages, paged class facts, malformed-class reasons, and a labeled name-obfuscation heuristic.
inspect_java_class / inspect-java-class returns declarations, annotations, literals, referenced classes and method bytecode lengths. These facts come from the bundled TypeScript class-file reader; method bodies are not decoded or verified.
decompile_java_class / decompile-java-class uses REA_VINEFLOWER_JAR and caller-selected Java (JAVA_HOME or PATH; Java 17+). REA does not install or download either dependency. Reconstructed source is derived Evidence with engine identity, digest and tool profile; it is not original source.

The Java domain contracts and application port own shared results; provider adapters own parsing and engine execution. CLI resolves relative input paths; MCP requires absolute paths. Selection uses declared binary names across archive prefixes. Duplicate binary-name occurrences require an exact .class entry; duplicate paths can be selected with the inventory row's unique entry_id (zip-entry:N), scoped to the selected archive digest. Runtime annotation visibility is retained. Evidence retains selected artifact identity, coverage, limitations and failure reasons. Inspection works without an active native target or JVM.

Authority and resource bounds

Inspection reads the selected local bytes without launching a process or writing target files. Optional decompilation launches the caller's Java/Vineflower and writes private temporary staging/output files; it does not launch the target application. The admitted target, selected/nested classes, archive library context and engine copy are staged locally. Untrusted entry paths are checked before launch, and the private engine copy is re-hashed afterward. Failed process cleanup retains supervisor ownership; failed temporary-root cleanup is retained for retry. This process is not an OS sandbox, and caller-supplied executable behavior remains a material authority question.

Allocation guards are 512 MiB input, 200,000 entries, 16 MiB per class, 512 MiB aggregate decompressed class bytes, 16 MiB manifest, and 64 descriptors with 64 KiB text prefixes. Descriptor omissions are reported. Vineflower has a 180-second deadline, 8 MiB diagnostic budget and 32 MiB source-read guard. Expanded class-report text has a separate 16 MiB JSON text budget charged before Evidence serialization; exceeding it returns a typed resource failure without partial success. These guards do not establish an OS process-memory limit. Nested archives are inventoried rather than recursively analyzed; encrypted entries are counted without reading their content. No new installer or automatic dependency download is introduced.

Authored Java documentation, tool contracts, CLI/MCP registration and skill guidance are included. Ignored generated catalogs and packaged skills are not committed.

Evidence and validation

Existing or added source tests cover public CLI inventory/class inspection, MCP schemas and Evidence/session behavior, class parsing/literal fidelity, selection ambiguity, metadata/resource boundaries, and simulated decompiler staging/cleanup. The simulated launcher establishes no real Vineflower compatibility. An opt-in acceptance case (REA_VERIFY_VINEFLOWER_REAL=1) uses caller-supplied Java, javac and Vineflower to compile and decompile top-level/nested controls.

Final review follow-ups received source inspection and targeted formatting. Tests, builds, typechecks, lint and CI reruns were not run for these revisions at the user's explicit request. The opt-in real-provider case was not run; actual Vineflower top-level/nested output paths, platform behavior and performance remain unverified. Historical examples in the documentation do not validate the final revision.

Integration hold

Keep integration blocked pending an explicit maintainer scope decision covering these new providers, caller-selected Java/Vineflower execution authority, resource policy, cancellation/cleanup, and required verification. Correctness fixes on this contribution branch do not grant integration approval. The scope thread and real-provider verification thread remain open.

Maintainer scope decision is linked and covers the final diff.
Required real Vineflower and platform verification is completed and recorded.
Final revision passes the agreed validation gate.

_{🔄 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/2717 **Author:** [@nadezhdkov](https://github.com/nadezhdkov) **Created:** 10/13/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `feat/java-archives` --- ### 📝 Commits (10+) - [`f45b9c1`](https://github.com/morluto/rea/commit/f45b9c12ad88e738dbd2f6318b2329d755987926) chore: add CLAUDE.md and mirror agent skills under .claude - [`ac3abfb`](https://github.com/morluto/rea/commit/ac3abfbe9e55bbfc1b7ac976fa6bcddd046b3ee9) feat(java): inspect and decompile JAR and class files - [`b10094d`](https://github.com/morluto/rea/commit/b10094d18121915c0c865664f3bca00ddf2cc6d4) chore: resync .claude skills mirror with upstream skills - [`8fd666a`](https://github.com/morluto/rea/commit/8fd666a198c40b46fa23779571716de17f751384) fix(java): preserve archive identity and cleanup ownership - [`89a141b`](https://github.com/morluto/rea/commit/89a141be06322016f7c4bbc4bfc49c855d9b0eb6) fix(java): reconcile archive readers with current main error semantics - [`3788b46`](https://github.com/morluto/rea/commit/3788b465d22fdecad9e0752f5a81b2b08a2802fb) fix(java): preserve malformed matching class coordinates - [`ffc7918`](https://github.com/morluto/rea/commit/ffc79185daf96082445a1bb69a865329528aacd4) fix(java): preserve archive identities and bounded parser evidence - [`5405f0c`](https://github.com/morluto/rea/commit/5405f0cb38f5c2384182148782f73c50b5c2f351) fix(java): budget retained facts and preserve exact selections - [`b095795`](https://github.com/morluto/rea/commit/b09579540a2186231485841e9464d0125a8b3665) fix(java): bound archive summary resources - [`14a091a`](https://github.com/morluto/rea/commit/14a091af030dfb69970f05a520d7e487dd7b8cf2) fix(comparison): recheck historical calls-only changes (#2223) ### 📊 Changes **48 files changed** (+5925 additions, -7 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+7 -0) 📝 `.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md` (+17 -0) ➕ `.claude/skills/rea-changelog-update/SKILL.md` (+134 -0) ➕ `.claude/skills/rea-tool-design/SKILL.md` (+20 -0) ➕ `.claude/skills/reverse-engineer-anything/SKILL.md` (+292 -0) ➕ `.claude/skills/reverse-engineer-anything/references/android-applications.md` (+34 -0) ➕ `.claude/skills/reverse-engineer-anything/references/connection-and-recovery.md` (+127 -0) ➕ `.claude/skills/reverse-engineer-anything/references/evidence-workflows.md` (+67 -0) ➕ `.claude/skills/reverse-engineer-anything/references/javascript-applications.md` (+175 -0) ➕ `.claude/skills/reverse-engineer-anything/references/native-and-artifacts.md` (+263 -0) ➕ `.claude/skills/reverse-engineer-anything/references/runtime-observation.md` (+43 -0) ➕ `CLAUDE.md` (+7 -0) 📝 `README.md` (+1 -0) 📝 `docs/.vitepress/config.ts` (+1 -0) 📝 `docs/cli.md` (+8 -0) ➕ `docs/java-archives.md` (+168 -0) 📝 `scripts/lib/catalog-builders.mjs` (+13 -0) 📝 `scripts/lib/catalog-core.mjs` (+2 -0) 📝 `scripts/lib/module-boundaries.mjs` (+1 -0) 📝 `src/application/CapabilityInventory.ts` (+14 -1) _...and 28 more files_ </details> ### 📄 Description ## Summary Add local JVM archive and class-file inspection through shared CLI/MCP workflows, plus optional source reconstruction with a caller-supplied Vineflower engine. Analysts can inventory a JAR, WAR/EAR or standalone `.class`, select a class, and inspect declared structure without loading or executing target bytecode. This is @nadezhdkov's contribution on `feat/java-archives`; the existing contributor commits and authorship remain in branch history. Follow-up commits address review findings and reconcile upstream changes. No issue or maintainer scope decision is linked yet. ## Behavior and contracts - `inspect_java_archive` / `inspect-java-archive` returns manifest and bounded framework descriptors, entry counts, bytecode versions, packages, paged class facts, malformed-class reasons, and a labeled name-obfuscation heuristic. - `inspect_java_class` / `inspect-java-class` returns declarations, annotations, literals, referenced classes and method bytecode lengths. These facts come from the bundled TypeScript class-file reader; method bodies are not decoded or verified. - `decompile_java_class` / `decompile-java-class` uses `REA_VINEFLOWER_JAR` and caller-selected Java (`JAVA_HOME` or `PATH`; Java 17+). REA does not install or download either dependency. Reconstructed source is derived Evidence with engine identity, digest and tool profile; it is not original source. The Java domain contracts and application port own shared results; provider adapters own parsing and engine execution. CLI resolves relative input paths; MCP requires absolute paths. Selection uses declared binary names across archive prefixes. Duplicate binary-name occurrences require an exact `.class` entry; duplicate paths can be selected with the inventory row's unique `entry_id` (`zip-entry:N`), scoped to the selected archive digest. Runtime annotation visibility is retained. Evidence retains selected artifact identity, coverage, limitations and failure reasons. Inspection works without an active native target or JVM. ## Authority and resource bounds Inspection reads the selected local bytes without launching a process or writing target files. Optional decompilation launches the caller's Java/Vineflower and writes private temporary staging/output files; it does not launch the target application. The admitted target, selected/nested classes, archive library context and engine copy are staged locally. Untrusted entry paths are checked before launch, and the private engine copy is re-hashed afterward. Failed process cleanup retains supervisor ownership; failed temporary-root cleanup is retained for retry. This process is not an OS sandbox, and caller-supplied executable behavior remains a material authority question. Allocation guards are 512 MiB input, 200,000 entries, 16 MiB per class, 512 MiB aggregate decompressed class bytes, 16 MiB manifest, and 64 descriptors with 64 KiB text prefixes. Descriptor omissions are reported. Vineflower has a 180-second deadline, 8 MiB diagnostic budget and 32 MiB source-read guard. Expanded class-report text has a separate 16 MiB JSON text budget charged before Evidence serialization; exceeding it returns a typed resource failure without partial success. These guards do not establish an OS process-memory limit. Nested archives are inventoried rather than recursively analyzed; encrypted entries are counted without reading their content. No new installer or automatic dependency download is introduced. Authored Java documentation, tool contracts, CLI/MCP registration and skill guidance are included. Ignored generated catalogs and packaged skills are not committed. ## Evidence and validation Existing or added source tests cover public CLI inventory/class inspection, MCP schemas and Evidence/session behavior, class parsing/literal fidelity, selection ambiguity, metadata/resource boundaries, and simulated decompiler staging/cleanup. The simulated launcher establishes no real Vineflower compatibility. An opt-in acceptance case (`REA_VERIFY_VINEFLOWER_REAL=1`) uses caller-supplied Java, javac and Vineflower to compile and decompile top-level/nested controls. Final review follow-ups received source inspection and targeted formatting. Tests, builds, typechecks, lint and CI reruns were not run for these revisions at the user's explicit request. The opt-in real-provider case was not run; actual Vineflower top-level/nested output paths, platform behavior and performance remain unverified. Historical examples in the documentation do not validate the final revision. ## Integration hold **Keep integration blocked pending an explicit maintainer scope decision covering these new providers, caller-selected Java/Vineflower execution authority, resource policy, cancellation/cleanup, and required verification.** Correctness fixes on this contribution branch do not grant integration approval. The scope thread and real-provider verification thread remain open. - [ ] Maintainer scope decision is linked and covers the final diff. - [ ] Required real Vineflower and platform verification is completed and recorded. - [ ] Final revision passes the agreed validation gate. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi added the

pull-request

label

2026-10-31 01:05:51 +00:00

bsakaguchi referenced this issue

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

[GH-ISSUE #8311] [Bug] CLI decompile timeout describes a session that has already ended #6535

bsakaguchi referenced this issue

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

[PR #5662] [MERGED] feat(ghidra): bound one procedure's decompile without closing the session #7022