* feat(adb): acquire installed APK sets from connected Android devices Add a read-only ADB device-acquisition family over the caller's adb binary: inspect_adb_client, list_adb_devices, inspect_adb_device, list_adb_packages, and pull_adb_package, exposed through the CLI and MCP with shared admission, Evidence provenance (binary, version, serial, transport), and fixed argv vectors that never reach a shell. pull_adb_package acquires the complete split set reported by pm path into a package-named directory that must not exist, digesting every file with SHA-256 and keeping per-file failure reasons and partial coverage. Device kind is reported as an inference with its basis; getprop whitelisting keeps build identity bounded. REA installs nothing and never manages devices or emulators; the first device query may start the caller's local adb server, recorded when observed. Verified against adb 34.0.5 on Linux with an Android 14 (API 34) x86_64 emulator: full 224-package inventory, a real two-APK split set pulled with byte-exact digests, and a 73.9 MB system-package pull. npm run verify:adb records the lane; parser goldens come from the same device. READMEs carry the new row in every supported language. * feat(adb): complete the adb surface with observation, transfer, and lifecycle tools Extend the ADB family from five to twenty-four operations, all through fixed adb argument vectors with no shell exposure: Observation: read_adb_logcat (bounded dump, count/buffer/pid), inspect_adb_package (dumpsys package projection), list_adb_processes (ps -A), list_adb_directory (ls -la with kinds and symlink targets), list_adb_features (hex GL versions), list_adb_services (AIDL slash-suffixed names), inspect_adb_display (wm size and density), inspect_adb_window (focus declarations), read_adb_setting (device-side nulls reported as such), capture_adb_screen (exec-out screencap with PNG dimensions), collect_adb_bugreport (digested device archive). Transfer and search: pull_adb_file and push_adb_file (device-side sha256sum verification, explicit overwrite authority), resolve_adb_packages (substring package search with exact-match flag — the find step of an easy get). Lifecycle for dynamic analysis, each declaring mutatesTarget: install_adb_package and uninstall_adb_package preserving the device's Success/Failure verdict, start_adb_app (resolve-activity then am start -W), start_adb_activity (typed extras as --es/--ez/--ei/--el/--ef), and stop_adb_app (am force-stop). Verified end-to-end against adb 34.0.5 on Linux with an Android 14 (API 34) x86_64 emulator: 287 services, 92 features, split-set pulls with byte-exact digests, verified push/pull roundtrip, sized screen capture, and the full install → resolve → start → observe-in-ps → force-stop → uninstall lifecycle. Fixed a v-mode regex incompatibility in the settings key pattern and added argument descriptions required by the CLI catalog audit. * fix(adb): quote remote shell operands and protect captured output * test(adb): cover bugreport destinations containing spaces --------- Co-authored-by: REA Contributor <contributor@rea.tools> Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
145 lines
4.6 KiB
TypeScript
145 lines
4.6 KiB
TypeScript
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
|
|
import { isAbsolute } from "node:path";
|
|
|
|
import {
|
|
execFileOutput,
|
|
execFileOutputFailure,
|
|
} from "../process/ExecFileOutput.js";
|
|
import type { ProviderAvailability } from "../application/AnalysisProvider.js";
|
|
import type { ProviderRejectionCode } from "../contracts/providerSelection.js";
|
|
import type { JsonValue } from "../domain/jsonValue.js";
|
|
|
|
/** Environment key selecting the caller's adb binary. */
|
|
export const ADB_BINARY_ENV = "REA_ADB_PATH";
|
|
|
|
const VERSION_TIMEOUT_MS = 10_000;
|
|
const VERSION_MAX_OUTPUT_BYTES = 64 * 1024;
|
|
|
|
/** How the adb binary was selected for this provider instance. */
|
|
export interface AdbBinarySelection {
|
|
readonly binary: string;
|
|
readonly pathSource: "environment" | "path";
|
|
}
|
|
|
|
/**
|
|
* Resolve the caller-supplied adb binary. `REA_ADB_PATH` must be absolute so
|
|
* the selection stays explicit; without it, adb is resolved from `PATH` by
|
|
* the platform exec at run time, like any bring-your-own tool.
|
|
*/
|
|
export const resolveAdbBinary = (
|
|
environment: Readonly<Record<string, string | undefined>>,
|
|
): AdbBinarySelection => {
|
|
const configured = environment[ADB_BINARY_ENV];
|
|
if (configured === undefined || configured.trim() === "")
|
|
return { binary: "adb", pathSource: "path" };
|
|
if (!isAbsolute(configured))
|
|
throw new AdbConfigurationFailure(
|
|
"not_absolute",
|
|
`${ADB_BINARY_ENV} must be an absolute path to the adb binary`,
|
|
{ configured_path: configured },
|
|
);
|
|
return { binary: configured, pathSource: "environment" };
|
|
};
|
|
|
|
export type AdbConfigurationFailureCode =
|
|
| "not_absolute"
|
|
| "binary_missing"
|
|
| "version_unresolved";
|
|
|
|
export class AdbConfigurationFailure extends Error {
|
|
constructor(
|
|
readonly code: AdbConfigurationFailureCode,
|
|
message: string,
|
|
readonly diagnostics: Readonly<Record<string, JsonValue>> = {},
|
|
options?: ErrorOptions,
|
|
) {
|
|
super(message, options);
|
|
}
|
|
}
|
|
|
|
export interface AdbClientIdentity {
|
|
readonly version: string | null;
|
|
readonly installedPath: string | null;
|
|
}
|
|
|
|
/**
|
|
* Parse `adb version` output. The first line carries the protocol version,
|
|
* `Version ` the build version (no colon), and `Installed as` the binary path.
|
|
*/
|
|
export const parseAdbVersionOutput = (stdout: string): AdbClientIdentity => {
|
|
const build = /^Version\s+(\S.*)$/mu.exec(stdout);
|
|
const installed = /^Installed as\s+(.+)$/mu.exec(stdout);
|
|
return {
|
|
version: build === null ? null : build[1]!.trim(),
|
|
installedPath: installed === null ? null : installed[1]!.trim(),
|
|
};
|
|
};
|
|
|
|
/**
|
|
* Probe the selected adb binary without contacting devices. `adb version`
|
|
* never starts the adb server, so this stays a pure client check.
|
|
*/
|
|
export const inspectAdbClient = async (
|
|
selection: AdbBinarySelection,
|
|
signal?: AbortSignal,
|
|
): Promise<AdbClientIdentity> => {
|
|
try {
|
|
const { stdout } = await execFileOutput(selection.binary, ["version"], {
|
|
timeout: VERSION_TIMEOUT_MS,
|
|
stopSignal: "SIGTERM",
|
|
maxBuffer: VERSION_MAX_OUTPUT_BYTES,
|
|
...(signal === undefined ? {} : { signal }),
|
|
});
|
|
return parseAdbVersionOutput(stdout);
|
|
} catch (cause) {
|
|
const failure = execFileOutputFailure(cause);
|
|
if (signal?.aborted || failure?.code === "ABORT_ERR")
|
|
throw new AnalysisCancelledError("inspect_adb_client", { cause });
|
|
if (failure?.code === "ENOENT")
|
|
throw new AdbConfigurationFailure(
|
|
"binary_missing",
|
|
`The selected adb binary was not found: ${selection.binary}`,
|
|
{
|
|
selected_binary: selection.binary,
|
|
path_source: selection.pathSource,
|
|
remediation: `Set ${ADB_BINARY_ENV} to an absolute path to an existing adb binary`,
|
|
},
|
|
{ cause },
|
|
);
|
|
throw new AdbConfigurationFailure(
|
|
"version_unresolved",
|
|
"The selected adb binary did not report a usable version",
|
|
{
|
|
selected_binary: selection.binary,
|
|
...(failure === undefined
|
|
? {}
|
|
: {
|
|
exit_code: failure.code,
|
|
stderr_excerpt: failure.stderr.slice(0, 512),
|
|
}),
|
|
},
|
|
{ cause },
|
|
);
|
|
}
|
|
};
|
|
|
|
/** Availability in the shape shared by every provider. */
|
|
const rejectionCodeOf = (
|
|
code: AdbConfigurationFailureCode,
|
|
): ProviderRejectionCode =>
|
|
code === "binary_missing"
|
|
? "executable_missing"
|
|
: code === "not_absolute"
|
|
? "not_configured"
|
|
: "version_unresolved";
|
|
|
|
export const adbConfigurationAvailability = (
|
|
cause: AdbConfigurationFailure,
|
|
): ProviderAvailability =>
|
|
({
|
|
status: "unavailable",
|
|
code: rejectionCodeOf(cause.code),
|
|
reason: cause.message,
|
|
diagnostics: { ...cause.diagnostics },
|
|
}) as ProviderAvailability;
|