* 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>
249 lines
7.2 KiB
TypeScript
249 lines
7.2 KiB
TypeScript
/**
|
|
* Parsers for the exact adb and Package Manager output formats REA consumes.
|
|
*
|
|
* Each parser preserves what the tool actually printed: unparseable lines are
|
|
* retained rather than silently dropped, and derived classifications carry
|
|
* their evidence basis.
|
|
*/
|
|
|
|
/** One device exactly as `adb devices -l` reports it. */
|
|
export interface AdbDeviceEntry {
|
|
readonly serial: string;
|
|
readonly state: string;
|
|
readonly transport: "usb" | "tcp" | "unknown";
|
|
readonly product: string | null;
|
|
readonly model: string | null;
|
|
readonly device: string | null;
|
|
readonly transport_id: number | null;
|
|
readonly kind: "emulator" | "physical" | "unknown";
|
|
readonly kind_basis: "emulator_serial_prefix" | "usb_transport" | "none";
|
|
}
|
|
|
|
/**
|
|
* Device states adb prints after the serial, longest first so two-word
|
|
* states match before their single-word prefixes. A line whose remainder
|
|
* starts with none of them is not a device line.
|
|
*/
|
|
const DEVICE_STATES = [
|
|
"no permissions",
|
|
"unauthorized",
|
|
"authorizing",
|
|
"offline",
|
|
"recovery",
|
|
"sideload",
|
|
"connecting",
|
|
"bootloader",
|
|
"device",
|
|
"unknown",
|
|
"host",
|
|
] as const;
|
|
|
|
const DEVICE_LINE = /^(\S+)\s+(.*)$/u;
|
|
|
|
const metadataValue = (remainder: string, key: string): string | null => {
|
|
const match = new RegExp(`(?:^|\\s)${key}:(\\S+)`, "u").exec(remainder);
|
|
return match === null ? null : match[1]!;
|
|
};
|
|
|
|
/**
|
|
* Parse `adb devices -l` device lines. The banner, blank lines, and the
|
|
* daemon startup notices adb prints on first use are recognized separately;
|
|
* every other unrecognized line is returned for honest reporting.
|
|
*/
|
|
export const parseAdbDevicesOutput = (
|
|
stdout: string,
|
|
): {
|
|
devices: readonly AdbDeviceEntry[];
|
|
unparsedLines: readonly string[];
|
|
daemonStarted: boolean;
|
|
} => {
|
|
const devices: AdbDeviceEntry[] = [];
|
|
const unparsedLines: string[] = [];
|
|
let daemonStarted = false;
|
|
for (const rawLine of stdout.split(/\r?\n/u)) {
|
|
const line = rawLine.trimEnd();
|
|
if (line === "" || line.startsWith("List of devices attached")) continue;
|
|
if (line.startsWith("* daemon")) {
|
|
if (line.includes("started successfully")) daemonStarted = true;
|
|
continue;
|
|
}
|
|
const match = DEVICE_LINE.exec(line);
|
|
const state = DEVICE_STATES.find((candidate) =>
|
|
match?.[2]?.startsWith(candidate),
|
|
);
|
|
if (match === null || state === undefined) {
|
|
if (line.trim() !== "") unparsedLines.push(line);
|
|
continue;
|
|
}
|
|
const serial = match[1]!;
|
|
const remainder = match[2]!.slice(state.length);
|
|
const usb = metadataValue(remainder, "usb");
|
|
const transportIdText = metadataValue(remainder, "transport_id");
|
|
const parsedTransportId =
|
|
transportIdText === null || !/^\d+$/u.test(transportIdText)
|
|
? null
|
|
: Number(transportIdText);
|
|
const isEmulator = /^emulator-\d+$/u.test(serial);
|
|
const kind = isEmulator
|
|
? ("emulator" as const)
|
|
: usb !== null
|
|
? ("physical" as const)
|
|
: ("unknown" as const);
|
|
devices.push({
|
|
serial,
|
|
state,
|
|
transport:
|
|
usb !== null
|
|
? "usb"
|
|
: isEmulator || serial.includes(":")
|
|
? "tcp"
|
|
: "unknown",
|
|
product: metadataValue(remainder, "product"),
|
|
model: metadataValue(remainder, "model"),
|
|
device: metadataValue(remainder, "device"),
|
|
transport_id: parsedTransportId,
|
|
kind,
|
|
kind_basis:
|
|
kind === "emulator"
|
|
? "emulator_serial_prefix"
|
|
: kind === "physical"
|
|
? "usb_transport"
|
|
: "none",
|
|
});
|
|
}
|
|
return { devices, unparsedLines, daemonStarted };
|
|
};
|
|
|
|
/**
|
|
* Properties projected from a `getprop` dump. The whitelist keeps device
|
|
* inspection to build identity facts; a full dump is out of scope.
|
|
*/
|
|
const DEVICE_PROPERTY_WHITELIST = [
|
|
"ro.build.version.release",
|
|
"ro.build.version.sdk",
|
|
"ro.build.version.security_patch",
|
|
"ro.build.id",
|
|
"ro.build.fingerprint",
|
|
"ro.build.characteristics",
|
|
"ro.debuggable",
|
|
"ro.kernel.qemu",
|
|
"ro.product.brand",
|
|
"ro.product.device",
|
|
"ro.product.manufacturer",
|
|
"ro.product.model",
|
|
"ro.product.cpu.abilist",
|
|
] as const;
|
|
|
|
export interface AdbDeviceProperty {
|
|
readonly name: string;
|
|
readonly value: string;
|
|
}
|
|
|
|
/** Parse a full `getprop` dump into `[name]: [value]` pairs. */
|
|
export const parseGetpropOutput = (
|
|
stdout: string,
|
|
): {
|
|
properties: readonly AdbDeviceProperty[];
|
|
emulatorObserved: boolean | null;
|
|
} => {
|
|
const values = new Map<string, string>();
|
|
for (const rawLine of stdout.split(/\r?\n/u)) {
|
|
const match = /^\[([^\]]+)\]:\s*\[(.*)\]$/u.exec(rawLine.trim());
|
|
if (match === null) continue;
|
|
values.set(match[1]!, match[2]!);
|
|
}
|
|
const properties = DEVICE_PROPERTY_WHITELIST.flatMap((name) => {
|
|
const value = values.get(name);
|
|
return value === undefined || value === ""
|
|
? []
|
|
: [{ name, value } satisfies AdbDeviceProperty];
|
|
});
|
|
const qemu = values.get("ro.kernel.qemu");
|
|
return {
|
|
properties,
|
|
emulatorObserved: qemu === undefined ? null : qemu === "1",
|
|
};
|
|
};
|
|
|
|
/** One installed package exactly as `pm list packages -f` reports it. */
|
|
export interface AdbPackageEntry {
|
|
readonly package_name: string;
|
|
readonly base_apk_device_path: string;
|
|
}
|
|
|
|
const PACKAGE_LINE = /^package:(.+)=([^\s=]+)$/u;
|
|
|
|
/** Parse `pm list packages -f` lines, retaining unrecognized lines. */
|
|
export const parsePackageListOutput = (
|
|
stdout: string,
|
|
): {
|
|
packages: readonly AdbPackageEntry[];
|
|
unparsedLines: readonly string[];
|
|
} => {
|
|
const packages: AdbPackageEntry[] = [];
|
|
const unparsedLines: string[] = [];
|
|
for (const rawLine of stdout.split(/\r?\n/u)) {
|
|
const line = rawLine.trim();
|
|
if (line === "") continue;
|
|
const match = PACKAGE_LINE.exec(line);
|
|
if (match === null) {
|
|
unparsedLines.push(line);
|
|
continue;
|
|
}
|
|
packages.push({
|
|
package_name: match[2]!,
|
|
base_apk_device_path: match[1]!,
|
|
});
|
|
}
|
|
return { packages, unparsedLines };
|
|
};
|
|
|
|
/** One APK of an installed package exactly as `pm path` reports it. */
|
|
export interface AdbPackagePathEntry {
|
|
readonly device_path: string;
|
|
readonly file_name: string;
|
|
readonly role: "base" | "split" | "unknown";
|
|
}
|
|
|
|
const fileNameOf = (devicePath: string): string => {
|
|
const parts = devicePath.split(/\//u);
|
|
return parts[parts.length - 1] ?? devicePath;
|
|
};
|
|
|
|
/**
|
|
* Parse `pm path PACKAGE` lines. The base/split role is derived from the file
|
|
* name (`base.apk`, `split_*.apk`), which is the only signal the output
|
|
* carries; any other name reports an unknown role.
|
|
*/
|
|
export const parsePmPathOutput = (
|
|
stdout: string,
|
|
): {
|
|
paths: readonly AdbPackagePathEntry[];
|
|
unparsedLines: readonly string[];
|
|
} => {
|
|
const paths: AdbPackagePathEntry[] = [];
|
|
const unparsedLines: string[] = [];
|
|
for (const rawLine of stdout.split(/\r?\n/u)) {
|
|
const line = rawLine.trim();
|
|
if (line === "") continue;
|
|
const match = /^package:(\S+)$/u.exec(line);
|
|
if (match === null) {
|
|
unparsedLines.push(line);
|
|
continue;
|
|
}
|
|
const devicePath = match[1]!;
|
|
const fileName = fileNameOf(devicePath);
|
|
paths.push({
|
|
device_path: devicePath,
|
|
file_name: fileName,
|
|
role:
|
|
fileName === "base.apk"
|
|
? "base"
|
|
: fileName.startsWith("split_") && fileName.endsWith(".apk")
|
|
? "split"
|
|
: "unknown",
|
|
});
|
|
}
|
|
return { paths, unparsedLines };
|
|
};
|