[PR #6288] feat(harmony): add xpanda-backed Ark bytecode analysis #7259

Open
opened 2026-11-01 21:46:32 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/6288
Author: @asmjmp0
Created: 10/22/2026
Status: 🔄 Open

Base: main ← Head: feat/harmony/xpanda


📝 Commits (1)

  • 3c608c2 feat(harmony): add xpanda-backed Ark bytecode analysis

📊 Changes

71 files changed (+5005 additions, -461 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+7 -0)
📝 README.md (+3 -1)
📝 docs/cli.md (+7 -5)
➕ docs/harmony-abc-analysis.md (+103 -0)
📝 docs/harmony-analysis.md (+4 -2)
📝 docs/index.md (+13 -13)
📝 docs/installation.md (+7 -7)
📝 docs/readme/README_ar.md (+25 -25)
📝 docs/readme/README_de.md (+2 -2)
📝 docs/readme/README_el.md (+2 -2)
📝 docs/readme/README_es.md (+2 -2)
📝 docs/readme/README_fa.md (+2 -2)
📝 docs/readme/README_fr.md (+2 -2)
📝 docs/readme/README_id.md (+2 -2)
📝 docs/readme/README_it.md (+2 -2)
📝 docs/readme/README_ja.md (+2 -2)
📝 docs/readme/README_ko.md (+2 -2)
📝 docs/readme/README_ml.md (+2 -2)
📝 docs/readme/README_pl.md (+25 -25)
📝 docs/readme/README_pt-BR.md (+2 -2)

...and 51 more files

📄 Description

Summary

Adds a dedicated HarmonyOS provider for Ark bytecode (.abc) analysis, backed by a caller-supplied xpanda checkout. docs/harmony-analysis.md deferred bytecode contents and versions until a dedicated HarmonyOS provider existed; this is that provider (roadmap #1431).

No issue is linked: the scope comes from the deferred-provider statement in docs/harmony-analysis.md.

Problem and expected behavior

Before: REA could inventory HAP/HSP/.app package structure but could not read Ark bytecode. Analysts had to leave REA to inspect classes, decompiled JavaScript or method disassembly.

After: six new MCP tools and matching one-shot CLI commands answer header facts, class inventory, single-class and whole-file decompilation, method disassembly, and string-pool search. Results are inline Evidence bound to the selected .abc file.

Change and scope

  • src/harmony/ owns the adapter: configuration (REA_XPANDA_ROOT, absolute path, 2.x admitted), engine tree digest, producer protocol/response parsing, the retained stdio MCP bridge, failure capture, and doctor readiness.
  • Proxy shape follows the JADX MCP bridge: one owned, serialized bridge per REA instance, 60 s idle retirement, shutdown cleanup, and a fresh respawn after fatal transport or deadline failures. Producer coherence errors (unknown class/method) keep the bridge.
  • Every operation stages a private snapshot of the selected input, verifies it against a stable source read, and binds Evidence to the analyzed bytes. A new abc Evidence subject format carries the file identity.
  • Producer output is parsed at one boundary: JSON tool results are schema-validated, the two text-shaped tools keep producer rendering verbatim behind strictly parsed header lines with payload-length and truncation checks, and producer errors map onto the existing tagged error algebra.
  • src/providers/McpStdioTransport.ts extracts the newline-framed MCP stdio transport previously embedded in the JADX adapter; src/android/JadxMcpTransport.ts is now a thin subclass preserving JADX attribution.
  • Wired availability (binary_session reporting), doctor (--provider xpanda), setup registration environment propagation, tool effects audit, product/MCP catalogs, authored skill guidance, and provider documentation.

Intentionally not included: deep-provider integration (open_binary + provider selection) for .abc targets; that remains a follow-up increment. Windows is not enabled because process-tree ownership for the bridge is unverified there.

Scope decision: static parsing and rendering only — no target execution, injection, mutation, or protection recovery, so the new-provider maintainer scope decision does not apply. The provider does launch the caller-supplied engine process, consistent with existing JADX/Binwalk/Kuna integrations.

Contract and boundary impact

  • Semantic owner and earliest changed stage: src/harmony/ owns producer semantics from bridge launch through response parsing; src/domain/harmony/harmonyAbcAnalysis.ts owns caller contracts.
  • Contribution scope fit and linked maintainer decision: static analysis capability; not applicable (no execution/injection/mutation/protection recovery).
  • CLI and MCP/tool-catalog contract: +6 MCP tools and +6 CLI commands; docs/public/product-catalog.json regenerated; CLI/MCP share one service.
  • Provider, bridge, target-format, or platform compatibility: provider id xpanda; xpanda 2.x admitted (verified 2.1.0), other majors refused; Linux and macOS only.
  • Evidence, artifact, provenance, or reconstruction contract: new abc subject format; staged-input SHA-256; engine package.json+src tree digest; producer version and explicit limitations.
  • Target selection, authority, upstream behavior, and cleanup details: no target execution. Owned bridge process with proven stop and retained cleanup retry; failed producer session close is reported in raw facts (producer LRU bounds leaks).
  • Generated metadata: catalogs, recorded digests, product catalog, and packaged skill regenerated by the build; authored instructions updated in .agents/skills/reverse-engineer-anything/. No build outputs committed.

Expected effects:

  • Read existing files or captured data.
  • Launch or attach to a process. (Caller-configured xpanda MCP server.)
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration. (Writes decompiled JavaScript only into the caller-selected absent output directory.)
  • 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: src/harmony/XpandaProtocol.test.ts, src/harmony/XpandaConfiguration.test.ts, tests/boundary/providers/harmony/* (scripted fake MCP engine with captured producer reply shapes), tests/boundary/mcp/harmonyAbcMcp.test.ts, tests/boundary/cli/harmonyAbcCommands.test.ts, plus absolute-path coverage in tests/boundary/mcp/absoluteLocalPathSchema.test.ts and effect-wording audit entries.

  • Base reproduction or other evidence: behavior is new; the provider absence was documented in docs/harmony-analysis.md.

  • User-visible CLI/MCP output: verify:xpanda exercises the compiled CLI and SDK-connected MCP server; representative output is the inline Evidence with subject.format: "abc".

  • Remaining proof gaps: the full npm run test:boundary suite was not completed in this environment; the affected built suites were run individually (listed below). Decompilation fidelity for arbitrary bytecode versions and untested xpanda 2.x releases is producer-owned and not independently verified.

  • 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

  • npm run check:fast — typecheck and lint pass (0 errors).
  • npm run test:fast — 832 files, 13,921 tests passed, 22 skipped.
  • npm run test:focused -- tests/boundary/providers/harmony/xpandaProvider.test.ts tests/boundary/mcp/harmonyAbcMcp.test.ts tests/boundary/cli/harmonyAbcCommands.test.ts tests/boundary/mcp/absoluteLocalPathSchema.test.ts — 4 files, 20 tests passed.
  • npm run test:local -- src/harmony/XpandaProtocol.test.ts src/harmony/XpandaConfiguration.test.ts — 31 tests passed.
  • Focused built suites for tool coverage, product catalog, server identity, tool schema validity, compact schemas, input admission, output schema profile, deferred runtime, CLI startup imports, setup/doctor, JADX transport regression, and acceptance/conformance — all passed.
  • npm run docs:check — passed.
  • REA_XPANDA_ROOT=/Users/jmp0/xpanda npm run verify:xpanda — passed against a local xpanda 2.1.0 checkout through the compiled CLI and SDK-connected stdio MCP: header inspection (2 classes, bytecode 11.0.2.0), class listing, single-class decompilation, method disassembly, string search, whole-file decompilation, CLI/MCP parity, and a typed absent-class failure.

Compatibility, safety, and release

  • Breaking changes or migration steps: none.
  • Real Hopper/Ghidra, browser, or OS coverage: not applicable (no native provider changes). Real xpanda 2.1.0 verified on macOS arm64; Linux path is shared but not run in this environment; Windows is refused.
  • Package or release metadata impact: no new runtime dependency; new environment variable REA_XPANDA_ROOT; catalogs and skill tool count regenerated.
  • Security, privacy, process, or containment review: the bridge runs the caller's own checkout with REA-owned process supervision, stages input under a 256 MiB bound in a private runtime root, never executes decompiled output, and records engine provenance without inheriting unneeded environment values.

Author readiness

Human owner: @asmjmp0

  • 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/6288 **Author:** [@asmjmp0](https://github.com/asmjmp0) **Created:** 10/22/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `feat/harmony/xpanda` --- ### 📝 Commits (1) - [`3c608c2`](https://github.com/morluto/rea/commit/3c608c2b672c4b570f97306f29f6884676add1b5) feat(harmony): add xpanda-backed Ark bytecode analysis ### 📊 Changes **71 files changed** (+5005 additions, -461 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+7 -0) 📝 `README.md` (+3 -1) 📝 `docs/cli.md` (+7 -5) ➕ `docs/harmony-abc-analysis.md` (+103 -0) 📝 `docs/harmony-analysis.md` (+4 -2) 📝 `docs/index.md` (+13 -13) 📝 `docs/installation.md` (+7 -7) 📝 `docs/readme/README_ar.md` (+25 -25) 📝 `docs/readme/README_de.md` (+2 -2) 📝 `docs/readme/README_el.md` (+2 -2) 📝 `docs/readme/README_es.md` (+2 -2) 📝 `docs/readme/README_fa.md` (+2 -2) 📝 `docs/readme/README_fr.md` (+2 -2) 📝 `docs/readme/README_id.md` (+2 -2) 📝 `docs/readme/README_it.md` (+2 -2) 📝 `docs/readme/README_ja.md` (+2 -2) 📝 `docs/readme/README_ko.md` (+2 -2) 📝 `docs/readme/README_ml.md` (+2 -2) 📝 `docs/readme/README_pl.md` (+25 -25) 📝 `docs/readme/README_pt-BR.md` (+2 -2) _...and 51 more files_ </details> ### 📄 Description ## Summary Adds a dedicated HarmonyOS provider for Ark bytecode (`.abc`) analysis, backed by a caller-supplied [xpanda](https://github.com/asmjmp0/xpanda) checkout. `docs/harmony-analysis.md` deferred bytecode contents and versions until a dedicated HarmonyOS provider existed; this is that provider (roadmap #1431). No issue is linked: the scope comes from the deferred-provider statement in `docs/harmony-analysis.md`. ## Problem and expected behavior Before: REA could inventory HAP/HSP/.app package structure but could not read Ark bytecode. Analysts had to leave REA to inspect classes, decompiled JavaScript or method disassembly. After: six new MCP tools and matching one-shot CLI commands answer header facts, class inventory, single-class and whole-file decompilation, method disassembly, and string-pool search. Results are inline Evidence bound to the selected `.abc` file. ## Change and scope - `src/harmony/` owns the adapter: configuration (`REA_XPANDA_ROOT`, absolute path, 2.x admitted), engine tree digest, producer protocol/response parsing, the retained stdio MCP bridge, failure capture, and doctor readiness. - Proxy shape follows the JADX MCP bridge: one owned, serialized bridge per REA instance, 60 s idle retirement, shutdown cleanup, and a fresh respawn after fatal transport or deadline failures. Producer coherence errors (unknown class/method) keep the bridge. - Every operation stages a private snapshot of the selected input, verifies it against a stable source read, and binds Evidence to the analyzed bytes. A new `abc` Evidence subject format carries the file identity. - Producer output is parsed at one boundary: JSON tool results are schema-validated, the two text-shaped tools keep producer rendering verbatim behind strictly parsed header lines with payload-length and truncation checks, and producer errors map onto the existing tagged error algebra. - `src/providers/McpStdioTransport.ts` extracts the newline-framed MCP stdio transport previously embedded in the JADX adapter; `src/android/JadxMcpTransport.ts` is now a thin subclass preserving JADX attribution. - Wired availability (`binary_session` reporting), doctor (`--provider xpanda`), setup registration environment propagation, tool effects audit, product/MCP catalogs, authored skill guidance, and provider documentation. Intentionally not included: deep-provider integration (`open_binary` + provider selection) for `.abc` targets; that remains a follow-up increment. Windows is not enabled because process-tree ownership for the bridge is unverified there. Scope decision: static parsing and rendering only — no target execution, injection, mutation, or protection recovery, so the new-provider maintainer scope decision does not apply. The provider does launch the caller-supplied engine process, consistent with existing JADX/Binwalk/Kuna integrations. ## Contract and boundary impact - Semantic owner and earliest changed stage: `src/harmony/` owns producer semantics from bridge launch through response parsing; `src/domain/harmony/harmonyAbcAnalysis.ts` owns caller contracts. - Contribution scope fit and linked maintainer decision: static analysis capability; not applicable (no execution/injection/mutation/protection recovery). - CLI and MCP/tool-catalog contract: +6 MCP tools and +6 CLI commands; `docs/public/product-catalog.json` regenerated; CLI/MCP share one service. - Provider, bridge, target-format, or platform compatibility: provider id `xpanda`; xpanda 2.x admitted (verified 2.1.0), other majors refused; Linux and macOS only. - Evidence, artifact, provenance, or reconstruction contract: new `abc` subject format; staged-input SHA-256; engine `package.json`+`src` tree digest; producer version and explicit limitations. - Target selection, authority, upstream behavior, and cleanup details: no target execution. Owned bridge process with proven stop and retained cleanup retry; failed producer session close is reported in raw facts (producer LRU bounds leaks). - Generated metadata: catalogs, recorded digests, product catalog, and packaged skill regenerated by the build; authored instructions updated in `.agents/skills/reverse-engineer-anything/`. No build outputs committed. Expected effects: - [x] Read existing files or captured data. - [x] Launch or attach to a process. (Caller-configured xpanda MCP server.) - [ ] Inject instrumentation or run scripts/code. - [x] Change process memory, registers, files, or configuration. (Writes decompiled JavaScript only into the caller-selected absent output directory.) - [ ] 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: `src/harmony/XpandaProtocol.test.ts`, `src/harmony/XpandaConfiguration.test.ts`, `tests/boundary/providers/harmony/*` (scripted fake MCP engine with captured producer reply shapes), `tests/boundary/mcp/harmonyAbcMcp.test.ts`, `tests/boundary/cli/harmonyAbcCommands.test.ts`, plus absolute-path coverage in `tests/boundary/mcp/absoluteLocalPathSchema.test.ts` and effect-wording audit entries. - Base reproduction or other evidence: behavior is new; the provider absence was documented in `docs/harmony-analysis.md`. - User-visible CLI/MCP output: `verify:xpanda` exercises the compiled CLI and SDK-connected MCP server; representative output is the inline Evidence with `subject.format: "abc"`. - Remaining proof gaps: the full `npm run test:boundary` suite was not completed in this environment; the affected built suites were run individually (listed below). Decompilation fidelity for arbitrary bytecode versions and untested xpanda 2.x releases is producer-owned and not independently verified. - [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 - `npm run check:fast` — typecheck and lint pass (0 errors). - `npm run test:fast` — 832 files, 13,921 tests passed, 22 skipped. - `npm run test:focused -- tests/boundary/providers/harmony/xpandaProvider.test.ts tests/boundary/mcp/harmonyAbcMcp.test.ts tests/boundary/cli/harmonyAbcCommands.test.ts tests/boundary/mcp/absoluteLocalPathSchema.test.ts` — 4 files, 20 tests passed. - `npm run test:local -- src/harmony/XpandaProtocol.test.ts src/harmony/XpandaConfiguration.test.ts` — 31 tests passed. - Focused built suites for tool coverage, product catalog, server identity, tool schema validity, compact schemas, input admission, output schema profile, deferred runtime, CLI startup imports, setup/doctor, JADX transport regression, and acceptance/conformance — all passed. - `npm run docs:check` — passed. - `REA_XPANDA_ROOT=/Users/jmp0/xpanda npm run verify:xpanda` — passed against a local xpanda 2.1.0 checkout through the compiled CLI and SDK-connected stdio MCP: header inspection (2 classes, bytecode 11.0.2.0), class listing, single-class decompilation, method disassembly, string search, whole-file decompilation, CLI/MCP parity, and a typed absent-class failure. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: not applicable (no native provider changes). Real xpanda 2.1.0 verified on macOS arm64; Linux path is shared but not run in this environment; Windows is refused. - Package or release metadata impact: no new runtime dependency; new environment variable `REA_XPANDA_ROOT`; catalogs and skill tool count regenerated. - Security, privacy, process, or containment review: the bridge runs the caller's own checkout with REA-owned process supervision, stages input under a 256 MiB bound in a private runtime root, never executes decompiled output, and records engine provenance without inheriting unneeded environment values. ## Author readiness Human owner: @asmjmp0 - [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#7259
No description provided.