refactor: share Android and firmware provider factories (#826)
This commit is contained in:
+38
-4
@@ -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."
|
||||
}
|
||||
|
||||
@@ -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/Unknown
|
||||
mutations and optimistic revisions. Preserve current close and failed-cleanup
|
||||
@@ -77,3 +77,19 @@ verification. Its integration is broader than swapping a provider. The migration
|
||||
should 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.
|
||||
|
||||
@@ -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 () => {
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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);
|
||||
@@ -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);
|
||||
@@ -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,
|
||||
|
||||
@@ -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",
|
||||
);
|
||||
},
|
||||
);
|
||||
@@ -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", {
|
||||
|
||||
@@ -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", {
|
||||
|
||||
@@ -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");
|
||||
|
||||
Vendored
+2
-2
@@ -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({
|
||||
|
||||
Vendored
+2
-2
@@ -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",
|
||||
|
||||
Reference in New Issue
Block a user