Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
refactor: share Android and firmware provider factories (#826)
N0zoM1z03ed59b281247
diff --git a/.oxlintrc.json b/.oxlintrc.jsonindex fab5b7126..557dfd7c5 100644--- a/.oxlintrc.json+++ b/.oxlintrc.json@@ -46,8 +46,14 @@{"patterns": [{- "group": ["**/ghidra/**", "**/hopper/**", "**/ida/**"],- "message": "Deep-provider imports belong behind adapters or in the application composition root."+ "group": [+ "**/ghidra/**",+ "**/hopper/**",+ "**/ida/**",+ "**/android/**",+ "**/firmware/**"+ ],+ "message": "Provider imports belong behind typed ports or in production composition."}]}@@ -80,7 +86,8 @@"**/native/**","**/process/**","**/reference/**",- "**/windows/**"+ "**/windows/**",+ "**/composition/**"],"message": "Domain and contracts depend inward; use typed ports for application, caller and provider boundaries."}@@ -89,6 +96,30 @@]}},+ {+ "files": ["src/application/**/*.ts"],+ "excludeFiles": ["src/application/runtime.ts"],+ "rules": {+ "no-restricted-imports": [+ "error",+ {+ "patterns": [+ {+ "group": [+ "**/ghidra/**",+ "**/hopper/**",+ "**/ida/**",+ "**/android/**",+ "**/firmware/**",+ "**/composition/**"+ ],+ "message": "Application workflows use typed ports; production construction belongs in composition."+ }+ ]+ }+ ]+ }+ },{"files": ["tests/**/*.ts", "src/**/*.test.ts", "src/**/*.fixture.ts"],"rules": {@@ -121,7 +152,10 @@"**/ida/**","**/replay/**","**/cli.*",- "**/main.*"+ "**/main.*",+ "**/composition/**",+ "**/android/**",+ "**/firmware/**"],"message": "Domain tests may import only their owning domain and inward dependencies."}diff --git a/docs/capability-migration.md b/docs/capability-migration.mdindex e17b700ee..57ce4449a 100644--- a/docs/capability-migration.md+++ b/docs/capability-migration.md@@ -6,17 +6,17 @@ there is no new universal provider interface or fixed module manifest.## Ownership to preserve-| Responsibility | Current owner | Migration direction |-| --------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------- |-| Analyst semantics and Evidence representation | domain | Keep pure and provider-neutral |-| Named public input/output contracts | contracts | Keep exact CLI/MCP meaning and complete discovery |-| Producer parsing and external tool protocols | provider adapters | Keep behind the relevant typed port |-| Shared analyst workflows | application | Share between CLI and MCP |-| Concrete provider construction | binary runtime, CLI registrars, MCP startup | Consolidate one capability at a time in production composition |-| Investigation Evidence and Unknowns | BinarySessionRecords | Extract one composed record owner after caller migration |-| Target/profile snapshots and invalidation | BinarySessionRecords/BinarySession | Keep binary-owned |-| Subprocess ownership and host primitives | process/windows | Reuse; preserve cancellation and cleanup |-| Public translation | CLI/MCP adapters | Delegate to shared workflows and named contracts |+| Responsibility | Current owner | Migration direction |+| --------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------- |+| Analyst semantics and Evidence representation | domain | Keep pure and provider-neutral |+| Named public input/output contracts | contracts | Keep exact CLI/MCP meaning and complete discovery |+| Producer parsing and external tool protocols | provider adapters | Keep behind the relevant typed port |+| Shared analyst workflows | application | Share between CLI and MCP |+| Concrete provider construction | binary runtime, composition, MCP startup | Consolidate one capability at a time in production composition |+| Investigation Evidence and Unknowns | BinarySessionRecords | Extract one composed record owner after caller migration |+| Target/profile snapshots and invalidation | BinarySessionRecords/BinarySession | Keep binary-owned |+| Subprocess ownership and host primitives | process/windows | Reuse; preserve cancellation and cleanup |+| Public translation | CLI/MCP adapters | Delegate to shared workflows and named contracts |Retain exact Evidence IDs, provenance, detached reads, atomic Evidence/Unknownmutations and optimistic revisions. Preserve current close and failed-cleanup@@ -77,3 +77,19 @@ verification. Its integration is broader than swapping a provider. The migrationshould eliminate incidental duplicate wiring, not erase those design decisions.Update these examples with real migrated entrypoints before closing #740.++## First production factory migration++`src/composition/android.ts` and `src/composition/firmware.ts` construct providers+behind the existing AndroidAnalysisPort and FirmwareAnalysisPort. CLI registrars+pass their selected environment; MCP uses the process environment unless a caller+injects a port. Each factory call returns a fresh instance and acquires no process,+workspace or toolchain. Queues, cleanup-failure state and per-request cleanup stay+inside the provider. The existing launcher seams remain available to boundary+fixtures, which now exercise the production factories.++Application workflows and MCP registration must not import these concrete+providers. Composition may import their implementations. Binary composition is+still at its existing entrypoint while its direct-analysis callers are investigated.+This concrete pilot does not introduce a shared provider interface or module+manifest.diff --git a/src/cli/androidCommands.ts b/src/cli/androidCommands.tsindex ab0bf9d0f..75408786f 100644--- a/src/cli/androidCommands.ts+++ b/src/cli/androidCommands.ts@@ -1,6 +1,6 @@import { z } from "incur";import { AndroidAnalysisService } from "../application/AndroidAnalysisService.js";-import { JadxProvider } from "../android/JadxProvider.js";+import { createAndroidAnalysisProvider } from "../composition/android.js";import { CLI_COMMANDS } from "../cliCommandNames.js";import { logCliCommand } from "../cliLogging.js";import { projectAnalysisError } from "../domain/analysisErrorProjection.js";@@ -15,7 +15,9 @@ export const registerAndroidCommands = (logger: Logger,environment: Readonly<Record<string, string | undefined>>,): void => {- const service = new AndroidAnalysisService(new JadxProvider(environment));+ const service = new AndroidAnalysisService(+ createAndroidAnalysisProvider(environment),+ );const execute = (name: string, operation: AndroidOperation, input: unknown) =>withCommandCancellation((signal) =>logCliCommand(logger, name, async () => {diff --git a/src/cli/firmwareCommands.ts b/src/cli/firmwareCommands.tsindex 6ed6d7fdf..dcaf9f6f4 100644--- a/src/cli/firmwareCommands.ts+++ b/src/cli/firmwareCommands.ts@@ -1,6 +1,6 @@import { z } from "incur";import { FirmwareAnalysisService } from "../application/FirmwareAnalysisService.js";-import { FirmwareProvider } from "../firmware/FirmwareProvider.js";+import { createFirmwareAnalysisProvider } from "../composition/firmware.js";import { CLI_COMMANDS } from "../cliCommandNames.js";import { logCliCommand } from "../cliLogging.js";import { projectAnalysisError } from "../domain/analysisErrorProjection.js";@@ -16,7 +16,7 @@ export const registerFirmwareCommands = (environment: Readonly<Record<string, string | undefined>>,): void => {const service = new FirmwareAnalysisService(- new FirmwareProvider(environment),+ createFirmwareAnalysisProvider(environment),);const execute = (name: string,diff --git a/src/composition/android.ts b/src/composition/android.tsnew file mode 100644index 000000000..c9d504be5--- /dev/null+++ b/src/composition/android.ts@@ -0,0 +1,9 @@+import type { AndroidAnalysisPort } from "../application/AndroidAnalysisPort.js";+import type { JadxLauncher } from "../android/JadxMcpTransport.js";+import { JadxProvider } from "../android/JadxProvider.js";++/** Construct one APK provider with its own queue and cleanup-failure state. */+export const createAndroidAnalysisProvider = (+ environment: Readonly<Record<string, string | undefined>> = process.env,+ launcher?: JadxLauncher,+): AndroidAnalysisPort => new JadxProvider(environment, launcher);diff --git a/src/composition/firmware.ts b/src/composition/firmware.tsnew file mode 100644index 000000000..d2cca7dd9--- /dev/null+++ b/src/composition/firmware.ts@@ -0,0 +1,9 @@+import type { FirmwareAnalysisPort } from "../application/FirmwareAnalysisPort.js";+import type { FirmwareLauncher } from "../firmware/FirmwareCommand.js";+import { FirmwareProvider } from "../firmware/FirmwareProvider.js";++/** Construct one firmware provider without launching or acquiring an engine. */+export const createFirmwareAnalysisProvider = (+ environment: Readonly<Record<string, string | undefined>> = process.env,+ launcher?: FirmwareLauncher,+): FirmwareAnalysisPort => new FirmwareProvider(environment, launcher);diff --git a/src/server/createServer.ts b/src/server/createServer.tsindex 22cdfb5f7..f75187629 100644--- a/src/server/createServer.ts+++ b/src/server/createServer.ts@@ -22,11 +22,11 @@ import { registerManagedTools } from "./registerManagedTools.js";import { registerFirmwareTools } from "./registerFirmwareTools.js";import { FirmwareAnalysisService } from "../application/FirmwareAnalysisService.js";import type { FirmwareAnalysisPort } from "../application/FirmwareAnalysisPort.js";-import { FirmwareProvider } from "../firmware/FirmwareProvider.js";+import { createFirmwareAnalysisProvider } from "../composition/firmware.js";import { registerAndroidTools } from "./registerAndroidTools.js";import { AndroidAnalysisService } from "../application/AndroidAnalysisService.js";import type { AndroidAnalysisPort } from "../application/AndroidAnalysisPort.js";-import { JadxProvider } from "../android/JadxProvider.js";+import { createAndroidAnalysisProvider } from "../composition/android.js";import { registerManagedWorkflowTools } from "./registerManagedWorkflowTools.js";import { registerNativeTools } from "./registerNativeTools.js";import { registerOfficialTools } from "./registerOfficialTools.js";@@ -137,14 +137,16 @@ export const createServer = (registerBinaryAnalysisTools(toolContext);registerAndroidTools(server,- new AndroidAnalysisService(options.androidAnalysis ?? new JadxProvider()),+ new AndroidAnalysisService(+ options.androidAnalysis ?? createAndroidAnalysisProvider(),+ ),toolLogger,recordEvidence,);registerFirmwareTools(server,new FirmwareAnalysisService(- options.firmwareAnalysis ?? new FirmwareProvider(),+ options.firmwareAnalysis ?? createFirmwareAnalysisProvider(),),toolLogger,recordEvidence,diff --git a/tests/acceptance/nonBinaryComposition.test.ts b/tests/acceptance/nonBinaryComposition.test.tsnew file mode 100644index 000000000..b15c9d316--- /dev/null+++ b/tests/acceptance/nonBinaryComposition.test.ts@@ -0,0 +1,88 @@+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";+import { writeFile } from "node:fs/promises";+import { join } from "node:path";+import { expect, onTestFinished } from "vitest";++import { createAndroidAnalysisProvider } from "../../src/composition/android.js";+import { createFirmwareAnalysisProvider } from "../../src/composition/firmware.js";+import { createServer } from "../../src/server/createServer.js";+import { createTestBinarySession } from "../fixtures/binarySession.js";+import { writeOrderedZip } from "../fixtures/artifactEntryOrder.js";+import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js";+import { cliTest } from "../support/cli/cliFixture.js";++const connect = async (environment: NodeJS.ProcessEnv) => {+ const session = createTestBinarySession(() => {+ throw new Error("Target-free analysis must not acquire a deep provider");+ });+ const server = createServer(session, session, {+ androidAnalysis: createAndroidAnalysisProvider(environment),+ firmwareAnalysis: createFirmwareAnalysisProvider(environment),+ });+ const client = new Client({ name: "composition-parity", version: "1" });+ onTestFinished(async () => {+ await client.close();+ await server.close();+ await session.close();+ });+ const [clientTransport, serverTransport] =+ InMemoryTransport.createLinkedPair();+ await server.connect(serverTransport);+ await client.connect(clientTransport);+ return client;+};++cliTest.skipIf(process.platform === "win32")(+ "preserves the selected APK configuration through the compiled CLI and MCP factories",+ async ({ cli }) => {+ const root = await createTestTempDirectory("rea-android-composition-");+ const apk = join(root, "fixture.apk");+ await writeOrderedZip(apk, ["AndroidManifest.xml", "classes.dex"]);+ const environment = {+ REA_LOG_LEVEL: "silent",+ JAVA_HOME: "relative-fixture-jdk",+ };+ const cliResult = await cli.run({+ arguments: ["inspect-android-package", apk, "--json"],+ environment,+ timeoutMs: 10_000,+ });+ expect(cliResult.exitCode).toBe(1);+ expect(cliResult.json).toMatchObject({ code: "capability_unavailable" });+ const client = await connect(environment);+ const response = await client.callTool({+ name: "inspect_android_package",+ arguments: { path: apk },+ });+ expect(response.isError).toBe(true);+ expect(response.structuredContent).toEqual({ error: cliResult.json });+ expect(JSON.stringify(response.structuredContent)).toContain("JAVA_HOME");+ },+);++cliTest.skipIf(process.platform !== "linux")(+ "preserves the missing firmware command reason through both caller paths",+ async ({ cli }) => {+ const root = await createTestTempDirectory("rea-firmware-composition-");+ const path = join(root, "input.bin");+ await writeFile(path, "firmware fixture");+ const environment = { REA_LOG_LEVEL: "silent" };+ const cliResult = await cli.run({+ arguments: ["inspect-firmware-regions", path, "--json"],+ environment,+ timeoutMs: 10_000,+ });+ expect(cliResult.exitCode).toBe(1);+ expect(cliResult.json).toMatchObject({ code: "capability_unavailable" });+ const client = await connect(environment);+ const response = await client.callTool({+ name: "inspect_firmware_regions",+ arguments: { path },+ });+ expect(response.isError).toBe(true);+ expect(response.structuredContent).toEqual({ error: cliResult.json });+ expect(JSON.stringify(response.structuredContent)).toContain(+ "REA_BINWALK_COMMAND",+ );+ },+);diff --git a/tests/boundary/android/jadxIntegration.test.ts b/tests/boundary/android/jadxIntegration.test.tsindex efac82772..78df3d72c 100644--- a/tests/boundary/android/jadxIntegration.test.ts+++ b/tests/boundary/android/jadxIntegration.test.ts@@ -11,6 +11,23 @@ import {const it = test.skipIf(process.platform === "win32");+it("does not carry a factory instance's cleanup failure into another instance", async () => {+ const failed = await setup("cleanup-failure");+ const healthy = await setup();+ const failure = await failed.service.execute("inspect_android_package", {+ path: failed.apk,+ });+ expect(failure).toMatchObject({+ ok: false,+ error: { cleanupIncomplete: true },+ });+ const result = await healthy.service.execute("inspect_android_package", {+ path: healthy.apk,+ });+ expect(result.ok).toBe(true);+ await verifyCleanup(healthy.launches);+});+it("retains APK identity, original input, raw producer data and normalized observations", async () => {const { service, apk, launches } = await setup();const outcome = await service.execute("inspect_android_package", {diff --git a/tests/boundary/firmware/firmwareIntegration.test.ts b/tests/boundary/firmware/firmwareIntegration.test.tsindex a10e82f9a..25a85a665 100644--- a/tests/boundary/firmware/firmwareIntegration.test.ts+++ b/tests/boundary/firmware/firmwareIntegration.test.ts@@ -13,6 +13,23 @@ import { toCallToolResult } from "../../../src/server/toolResult.js";const it = test.skipIf(process.platform !== "linux");+it("keeps cleanup-failure state local to the selected factory instance", async () => {+ const failed = await firmwareFixture("cleanup-failure");+ const healthy = await firmwareFixture();+ const failure = await failed.service.execute("inspect_firmware_regions", {+ path: failed.path,+ });+ expect(failure).toMatchObject({+ ok: false,+ error: { cleanupIncomplete: true },+ });+ const result = await healthy.service.execute("inspect_firmware_regions", {+ path: healthy.path,+ });+ expect(result.ok).toBe(true);+ await assertFirmwareCleanup(healthy.launches);+});+it("binds region observations to exact bytes and preserves provider-reported uncertainty", async () => {const fixture = await firmwareFixture();const result = await fixture.service.execute("inspect_firmware_regions", {diff --git a/tests/evaluation/moduleBoundaries.test.ts b/tests/evaluation/moduleBoundaries.test.tsindex 2ef304015..8796c4873 100644--- a/tests/evaluation/moduleBoundaries.test.ts+++ b/tests/evaluation/moduleBoundaries.test.ts@@ -11,10 +11,17 @@ describe("incremental module import boundaries", () => {["src/domain/probe.ts", "../browser/Provider.js", false],["src/contracts/probe.ts", "../android/Provider.js", false],["src/contracts/probe.ts", "../cli.js", false],+ ["src/contracts/probe.ts", "../composition/android.js", false],+ ["src/domain/probe.test.ts", "../composition/firmware.js", false],+ ["src/application/probe.ts", "../android/JadxProvider.js", false],+ ["src/application/probe.ts", "../composition/android.js", false],+ ["src/server/probe.ts", "../firmware/FirmwareProvider.js", false],["src/domain/probe.ts", "./result.js", true],["src/contracts/probe.ts", "../domain/result.js", true],["src/application/probe.ts", "../domain/result.js", true],["src/composition/probe.ts", "../ghidra/Provider.js", true],+ ["src/composition/probe.ts", "../android/JadxProvider.js", true],+ ["src/composition/probe.ts", "../firmware/FirmwareProvider.js", true],])("checks %s importing %s", async (file, dependency, allowed) => {const temporary = await createTestTempDirectory("rea-module-boundary-");const config = join(temporary, ".oxlintrc.json");diff --git a/tests/fixtures/android/jadx.ts b/tests/fixtures/android/jadx.tsindex 236b5260d..e1662f4e4 100644--- a/tests/fixtures/android/jadx.ts+++ b/tests/fixtures/android/jadx.ts@@ -3,7 +3,7 @@ import { join } from "node:path";import { fileURLToPath } from "node:url";import { expect, onTestFinished } from "vitest";import { AndroidAnalysisService } from "../../../src/application/AndroidAnalysisService.js";-import { JadxProvider } from "../../../src/android/JadxProvider.js";+import { createAndroidAnalysisProvider } from "../../../src/composition/android.js";import {ProviderProcessSupervisor,spawnOwnedProviderProcess,@@ -26,7 +26,7 @@ export const createJadxProtocolFixture = async (mode = "normal") => {cwd: string | undefined;pid: number | undefined;}[] = [];- const provider = new JadxProvider(+ const provider = createAndroidAnalysisProvider({ ...process.env, REA_JADX_MCP_JAR: jar },async (options) => {const spawned = await spawnOwnedProviderProcess({diff --git a/tests/fixtures/firmware/provider.ts b/tests/fixtures/firmware/provider.tsindex cb036e0f4..81007923f 100644--- a/tests/fixtures/firmware/provider.ts+++ b/tests/fixtures/firmware/provider.ts@@ -2,7 +2,7 @@ import { join } from "node:path";import { fileURLToPath } from "node:url";import { access, rm, writeFile } from "node:fs/promises";import { expect, onTestFinished } from "vitest";-import { FirmwareProvider } from "../../../src/firmware/FirmwareProvider.js";+import { createFirmwareAnalysisProvider } from "../../../src/composition/firmware.js";import { FirmwareAnalysisService } from "../../../src/application/FirmwareAnalysisService.js";import { spawnOwnedProviderProcess } from "../../../src/process/ProviderProcess.js";import { createTestTempDirectory } from "../temporaryDirectory.js";@@ -18,7 +18,7 @@ export const firmwareFixture = async (mode = "normal") => {pid: number | undefined;args: readonly string[];}[] = [];- const provider = new FirmwareProvider(+ const provider = createFirmwareAnalysisProvider({...process.env,REA_BINWALK_COMMAND: "/usr/bin/true",