Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(adb): complete ADB device support for Android reverse engineering (#1552)
Quentin Limofef6f730643d
diff --git a/README.md b/README.mdindex f517b3896..fcf48f432 100644--- a/README.md+++ b/README.md@@ -158,6 +158,7 @@ Additional tools and host support depend on the target:| Saved network captures | Requests, responses, exposed payloads and source locations | HAR; mitmdump on Linux for native mitmproxy captures; [capture guide](docs/web-network-captures.md) || .NET assemblies | Metadata, CIL instructions, declared native dependencies and build comparisons | None (static only); [managed-code guide](docs/managed-code-analysis.md) || Android APKs | Manifest declarations, classes, decompiled methods and references | Headless JADX and a full JDK on Linux/macOS/Windows x64; [Android guide](docs/android-analysis.md) |+| Android devices | Devices, packages, processes, logs, dumps, screen captures, and APK/file transfers | Caller-supplied adb (emulator or hardware); [ADB guide](docs/adb-device-analysis.md) || Firmware | Regions, extraction results and native-analysis handoffs | Binwalk / Unblob on Linux; [firmware guide](docs/firmware-analysis.md) || Packages and resources | File inventories, digests, plists, Apple bundle anatomy and extracted resources | [Artifact and JavaScript guide](docs/javascript-artifact-reconstruction.md), [Apple applications](docs/apple-application-analysis.md) || Process behavior | Terminal output, interactions, exit and filesystem observations, and run comparisons | Linux/macOS with a native PTY; [process capture](docs/process-capture.md) |diff --git a/README_ar.md b/README_ar.mdindex 237e9ad77..57c3262b7 100644--- a/README_ar.md+++ b/README_ar.md@@ -142,6 +142,7 @@ npx rea-agents@latest setup| تسجيلات الشبكة المحفوظة | الطلبات، والاستجابات، ومحتويات الحمولة المتاحة، ومواضعها في المصدر | HAR؛ وmitmdump على Linux لتسجيلات mitmproxy بصيغتها الأصلية؛ [دليل تسجيلات الشبكة](docs/web-network-captures.md) || تجميعات .NET | البيانات الوصفية، وتعليمات CIL، واعتماديات الشيفرة الأصلية المعلنة، ومقارنات البناء | فحص ثابت؛ [دليل الشيفرة المُدارة](docs/managed-code-analysis.md) || حزم Android APK | تصريحات ملف manifest، والأصناف، والدوال الناتجة عن فك الترجمة، والمراجع | JADX دون واجهة رسومية وJDK كامل على Linux/macOS/Windows x64؛ [دليل Android](docs/android-analysis.md) |+| أجهزة Android | الأجهزة والحزم والعمليات والسجلات والدامبات ولقطات الشاشة ونقل APK/الملفات | adb يوفّره المُستدعي (محاكي أو جهاز)؛ [دليل ADB](docs/adb-device-analysis.md) || البرامج الثابتة | المناطق، ونتائج الاستخراج، وما يُمرّر إلى تحليل الشيفرة الأصلية | Binwalk / Unblob على Linux؛ [دليل البرامج الثابتة](docs/firmware-analysis.md) || الحزم والموارد | قوائم الملفات، والبصمات، وملفات plist، وبنية حزم Apple، والموارد المستخرجة | [دليل تحليل الملفات وJavaScript](docs/javascript-artifact-reconstruction.md)، [تطبيقات Apple](docs/apple-application-analysis.md) || سلوك العمليات | مخرجات الطرفية، والتفاعلات، وملاحظات الخروج ونظام الملفات، ومقارنات التشغيل | Linux/macOS مع PTY أصلي؛ [تسجيل سلوك العمليات](docs/process-capture.md) |diff --git a/README_de.md b/README_de.mdindex 31f2ae4c2..b69d5b1eb 100644--- a/README_de.md+++ b/README_de.md@@ -142,6 +142,7 @@ REA benötigt Node.js 22.x (>=22.19), 24.x (>=24.11) oder 26+ sowie npm. Zusätz| Gespeicherte Netzwerkaufzeichnungen | Anfragen, Antworten, zugängliche Nutzdaten und Quellpositionen | HAR; mitmdump unter Linux für Aufzeichnungen im nativen mitmproxy-Format; [Leitfaden zu Netzwerkaufzeichnungen](docs/web-network-captures.md) || .NET-Assemblies | Metadaten, CIL-Anweisungen, deklarierte native Abhängigkeiten und Build-Vergleiche | Statische Untersuchung; [Leitfaden für verwalteten Code](docs/managed-code-analysis.md) || Android-APKs | Manifest-Deklarationen, Klassen, dekompilierte Methoden und Verweise | JADX ohne grafische Oberfläche und ein vollständiges JDK unter Linux/macOS/Windows x64; [Android-Leitfaden](docs/android-analysis.md) |+| Android-Geräte | Geräte, Pakete, Prozesse, Logs, Dumps, Bildschirmaufnahmen sowie APK- und Dateiübertragungen | Vom Aufrufer bereitgestelltes adb (Emulator oder Gerät); [ADB-Leitfaden](docs/adb-device-analysis.md) || Firmware | Bereiche, Extraktionsergebnisse und Übergaben an die native Analyse | Binwalk / Unblob unter Linux; [Firmware-Leitfaden](docs/firmware-analysis.md) || Pakete und Ressourcen | Dateiinventare, Hashwerte, plists, Aufbau von Apple-Bundles und extrahierte Ressourcen | [Artefakt- und JavaScript-Leitfaden](docs/javascript-artifact-reconstruction.md), [Apple-Anwendungen](docs/apple-application-analysis.md) || Prozessverhalten | Terminalausgabe, Interaktionen, Beobachtungen zu Prozessende und Dateisystem sowie Laufvergleiche | Linux/macOS mit nativer PTY; [Prozessaufzeichnung](docs/process-capture.md) |diff --git a/README_es.md b/README_es.mdindex f032f173e..0bc4ad4c8 100644--- a/README_es.md+++ b/README_es.md@@ -142,6 +142,7 @@ REA requiere Node.js 22.x (>=22.19), 24.x (>=24.11) o 26+, además de npm. Las h| Capturas de red guardadas | Solicitudes, respuestas, contenido accesible de las cargas útiles y ubicaciones de origen | HAR; mitmdump en Linux para capturas en formato nativo de mitmproxy; [guía de capturas](docs/web-network-captures.md) || Ensamblados .NET | Metadatos, instrucciones CIL, dependencias nativas declaradas y comparaciones de compilaciones | Inspección estática; [guía de código administrado](docs/managed-code-analysis.md) || APK de Android | Declaraciones del manifiesto, clases, métodos descompilados y referencias | JADX sin interfaz gráfica y un JDK completo en Linux/macOS/Windows x64; [guía de Android](docs/android-analysis.md) |+| Dispositivos Android | Dispositivos, paquetes, procesos, registros, volcados, capturas de pantalla y transferencias de APK/archivos | adb suministrado por el autor de la llamada (emulador o dispositivo); [guía de ADB](docs/adb-device-analysis.md) || Firmware | Regiones, resultados de extracción y derivaciones al análisis nativo | Binwalk / Unblob en Linux; [guía de firmware](docs/firmware-analysis.md) || Paquetes y recursos | Inventarios de archivos, resúmenes criptográficos, plists, estructura de paquetes de Apple y recursos extraídos | [Guía de artefactos y JavaScript](docs/javascript-artifact-reconstruction.md), [aplicaciones de Apple](docs/apple-application-analysis.md) || Comportamiento de procesos | Salida de la terminal, interacciones, observaciones de salida y del sistema de archivos, y comparaciones entre ejecuciones | Linux/macOS con una PTY nativa; [captura de procesos](docs/process-capture.md) |diff --git a/README_fa.md b/README_fa.mdindex 47bdcfc8e..ec515c66b 100644--- a/README_fa.md+++ b/README_fa.md@@ -134,6 +134,7 @@ REA به Node.js 22.x (>=22.19)، 24.x (>=24.11) یا 26+، بههمراه np| دادههای ضبطشدهٔ شبکه | درخواستها، پاسخها، payloadهای آشکارشده و مکان آنها در منبع | HAR؛ ابزار mitmdump در لینوکس برای ضبطهای بومی mitmproxy؛ [راهنمای ضبط شبکه](docs/web-network-captures.md) || اسمبلیهای .NET | فراداده، دستورالعملهای CIL، وابستگیهای بومی اعلامشده و مقایسهٔ buildها | بررسی ایستا؛ [راهنمای کد مدیریتشده](docs/managed-code-analysis.md) || فایلهای APK اندروید | تعاریف Manifest، کلاسها، متدهای دیکامپایلشده و ارجاعات | JADX بدون رابط گرافیکی و JDK کامل در Linux/macOS/Windows x64؛ [راهنمای اندروید](docs/android-analysis.md) |+| دستگاههای اندروید | دستگاهها، بستهها، فرایندها، لاگها، دامپها، اسکرینشاتها و انتقال APK/فایل | adb تأمینشده توسط فراخوانکننده (شبیهساز یا دستگاه)؛ [راهنمای ADB](docs/adb-device-analysis.md) || Firmware | ناحیهها، نتایج استخراج و تحویل به ابزارهای تحلیل بومی | Binwalk / Unblob در لینوکس؛ [راهنمای Firmware](docs/firmware-analysis.md) || بستهها و منابع | فهرست فایلها، digestها، فایلهای plist، ساختار bundle اپل و منابع استخراجشده | [راهنمای آرتیفکت و JavaScript](docs/javascript-artifact-reconstruction.md)، [برنامههای اپل](docs/apple-application-analysis.md) || رفتار فرایند | خروجی ترمینال، تعاملات، وضعیت خروج، مشاهدات سیستم فایل و مقایسهٔ اجراها | Linux/macOS با PTY بومی؛ [ضبط فرایند](docs/process-capture.md) |diff --git a/README_fr.md b/README_fr.mdindex adbcb1631..0f627f8c2 100644--- a/README_fr.md+++ b/README_fr.md@@ -143,6 +143,7 @@ REA nécessite Node.js 22.x (>=22.19), 24.x (>=24.11) ou 26+, ainsi que npm. Les| Captures réseau enregistrées | Requêtes, réponses, payloads exposés et emplacements dans le code source | HAR ; mitmdump sous Linux pour les captures mitmproxy natives ; [guide des captures](docs/web-network-captures.md) || Assemblys .NET | Métadonnées, instructions CIL, dépendances natives déclarées et comparaisons de builds | Inspection statique ; [guide du code managé](docs/managed-code-analysis.md) || APK Android | Déclarations du manifeste, classes, méthodes décompilées et références | JADX headless et un JDK complet sous Linux/macOS/Windows x64 ; [guide Android](docs/android-analysis.md) |+| Appareils Android | Appareils, paquets, processus, journaux, dumps, captures d'écran et transferts d'APK/fichiers | adb fourni par l'appelant (émulateur ou appareil) ; [guide ADB](docs/adb-device-analysis.md) || Firmware | Régions, résultats d'extraction et passage de relais vers l'analyse native | Binwalk / Unblob sous Linux ; [guide firmware](docs/firmware-analysis.md) || Paquets et ressources | Inventaires de fichiers, empreintes, plists, anatomie des bundles Apple et ressources extraites | [Guide artefacts et JavaScript](docs/javascript-artifact-reconstruction.md), [applications Apple](docs/apple-application-analysis.md) || Comportement des processus | Sortie du terminal, interactions, code de sortie, observations du système de fichiers et comparaisons | Linux/macOS avec un PTY natif ; [capture de processus](docs/process-capture.md) |diff --git a/README_id.md b/README_id.mdindex 225c6d317..dfeef6ae6 100644--- a/README_id.md+++ b/README_id.md@@ -146,6 +146,7 @@ Alat tambahan dan dukungan sistem host bergantung pada target yang dianalisis:| Rekaman jaringan tersimpan | Permintaan, respons, payload yang terekspos, dan lokasi sumber | HAR; mitmdump di Linux untuk rekaman native mitmproxy; [panduan rekaman](docs/web-network-captures.md) || Assembly .NET | Metadata, instruksi CIL, dependensi native yang dideklarasikan, dan perbandingan build | Tidak ada (hanya analisis statis); [panduan kode terkelola](docs/managed-code-analysis.md) || APK Android | Deklarasi manifest, kelas, metode hasil dekompilasi, dan referensi | JADX mode headless dan JDK lengkap di Linux/macOS/Windows x64; [panduan Android](docs/android-analysis.md) |+| Perangkat Android | Perangkat, paket, proses, log, dump, tangkapan layar, serta transfer APK/berkas | adb buatan pemanggil (emulator atau perangkat); [panduan ADB](docs/adb-device-analysis.md) || Firmware | Wilayah, hasil ekstraksi, dan pengalihan ke analisis native | Binwalk / Unblob di Linux; [panduan firmware](docs/firmware-analysis.md) || Paket dan sumber daya | Inventaris berkas, digest, plist, struktur paket Apple, dan sumber daya yang diekstrak | [Panduan artefak dan JavaScript](docs/javascript-artifact-reconstruction.md), [aplikasi Apple](docs/apple-application-analysis.md) || Perilaku proses | Keluaran terminal, interaksi, pengamatan proses keluar dan sistem berkas, serta perbandingan eksekusi | Linux/macOS dengan PTY native; [perekaman proses](docs/process-capture.md) |diff --git a/README_ja.md b/README_ja.mdindex a0db801d1..1a377703e 100644--- a/README_ja.md+++ b/README_ja.md@@ -142,6 +142,7 @@ REA には Node.js 22.x(>=22.19)、24.x(>=24.11)、または 26+ と npm| 保存済みのネットワークキャプチャ | リクエスト、レスポンス、取得可能なペイロード、ソース内の位置 | HAR;mitmproxy ネイティブ形式のキャプチャには Linux 上の mitmdump;[キャプチャガイド](docs/web-network-captures.md) || .NET アセンブリ | メタデータ、CIL 命令、宣言されたネイティブ依存関係、ビルドの比較 | 静的な検査;[マネージドコードのガイド](docs/managed-code-analysis.md) || Android APK | マニフェストの宣言、クラス、逆コンパイルされたメソッド、参照 | Linux/macOS/Windows x64 上のヘッドレス JADX と完全な JDK;[Android ガイド](docs/android-analysis.md) |+| Android デバイス | デバイス、パッケージ、プロセス、ログ、ダンプ、スクリーンキャプチャ、APK/ファイル転送 | 呼び出し側が用意した adb(エミュレーターまたは実機);[ADB ガイド](docs/adb-device-analysis.md) || ファームウェア | 領域、抽出結果、ネイティブ分析への引き継ぎ | Linux 上の Binwalk / Unblob;[ファームウェアガイド](docs/firmware-analysis.md) || パッケージとリソース | ファイル一覧、ダイジェスト、plist、Apple バンドルの構造、抽出されたリソース | [アーティファクトと JavaScript のガイド](docs/javascript-artifact-reconstruction.md)、[Apple アプリケーション](docs/apple-application-analysis.md) || プロセスの動作 | ターミナル出力、対話、終了とファイルシステムの観測結果、実行の比較 | ネイティブ PTY を備えた Linux/macOS;[プロセスキャプチャ](docs/process-capture.md) |diff --git a/README_ko.md b/README_ko.mdindex d27b8f405..4791602eb 100644--- a/README_ko.md+++ b/README_ko.md@@ -142,6 +142,7 @@ REA에는 Node.js 22.x(>=22.19), 24.x(>=24.11) 또는 26+와 npm이 필요합니| 저장된 네트워크 캡처 | 요청, 응답, 접근 가능한 페이로드, 소스 위치 | HAR; mitmproxy 네이티브 캡처에는 Linux의 mitmdump; [캡처 가이드](docs/web-network-captures.md) || .NET 어셈블리 | 메타데이터, CIL 명령, 선언된 네이티브 의존성, 빌드 비교 | 정적 검사; [관리 코드 가이드](docs/managed-code-analysis.md) || Android APK | 매니페스트 선언, 클래스, 디컴파일된 메서드, 참조 | Linux/macOS/Windows x64의 헤드리스 JADX와 전체 JDK; [Android 가이드](docs/android-analysis.md) |+| Android 기기 | 기기, 패키지, 프로세스, 로그, 덤프, 화면 캡처, APK/파일 전송 | 호출자 제공 adb(에뮬레이터 또는 실제 기기); [ADB 가이드](docs/adb-device-analysis.md) || 펌웨어 | 영역, 추출 결과, 네이티브 분석으로 전달할 정보 | Linux의 Binwalk / Unblob; [펌웨어 가이드](docs/firmware-analysis.md) || 패키지 및 리소스 | 파일 목록, 다이제스트, plist, Apple 번들 구조, 추출한 리소스 | [아티팩트 및 JavaScript 가이드](docs/javascript-artifact-reconstruction.md), [Apple 애플리케이션](docs/apple-application-analysis.md) || 프로세스 동작 | 터미널 출력, 상호작용, 종료 및 파일 시스템 관찰 결과, 실행 비교 | 네이티브 PTY를 지원하는 Linux/macOS; [프로세스 캡처](docs/process-capture.md) |diff --git a/README_pl.md b/README_pl.mdindex 0eaf1810e..b5c6ffa99 100644--- a/README_pl.md+++ b/README_pl.md@@ -142,6 +142,7 @@ REA wymaga Node.js 22.x (>=22.19), 24.x (>=24.11) lub 26+ oraz npm. Dodatkowe na| Zapisane przechwycenia ruchu sieciowego | Żądania, odpowiedzi, dostępne dane przesyłane i lokalizacje źródłowe | HAR; mitmdump w systemie Linux dla natywnych przechwyceń mitmproxy; [przewodnik przechwytywania](docs/web-network-captures.md) || Zestawy .NET | Metadane, instrukcje CIL, zadeklarowane zależności natywne i porównania kompilacji | Analiza statyczna; [przewodnik kodu zarządzanego](docs/managed-code-analysis.md) || Pakiety APK dla Androida | Deklaracje manifestu, klasy, zdekompilowane metody i odwołania | JADX bez interfejsu graficznego i pełny JDK w systemach Linux/macOS/Windows x64; [przewodnik Androida](docs/android-analysis.md) |+| Urządzenia z Androidem | Urządzenia, pakiety, procesy, logi, zrzuty, zrzuty ekranu oraz transfery APK/plików | adb dostarczony przez wywołującego (emulator lub urządzenie); [przewodnik ADB](docs/adb-device-analysis.md) || Oprogramowanie układowe | Regiony, wyniki wyodrębniania i przekazanie do analizy kodu natywnego | Binwalk / Unblob w systemie Linux; [przewodnik oprogramowania układowego](docs/firmware-analysis.md) || Pakiety i zasoby | Spisy plików, skróty, pliki plist, struktura pakietów Apple i wyodrębnione zasoby | [Przewodnik artefaktów i JavaScript](docs/javascript-artifact-reconstruction.md), [aplikacje Apple](docs/apple-application-analysis.md) || Zachowanie procesów | Wyjście terminala, interakcje, obserwacje zakończenia i systemu plików oraz porównania uruchomień | Linux/macOS z natywnym PTY; [przechwytywanie procesów](docs/process-capture.md) |diff --git a/README_pt-BR.md b/README_pt-BR.mdindex 172286add..656a10daa 100644--- a/README_pt-BR.md+++ b/README_pt-BR.md@@ -142,6 +142,7 @@ O REA requer Node.js 22.x (>=22.19), 24.x (>=24.11) ou 26+, além do npm. As fer| Capturas de rede salvas | Requisições, respostas, payloads acessíveis e localizações de origem | HAR; mitmdump no Linux para capturas no formato nativo do mitmproxy; [guia de capturas](docs/web-network-captures.md) || Assemblies .NET | Metadados, instruções CIL, dependências nativas declaradas e comparações de builds | Inspeção estática; [guia de código gerenciado](docs/managed-code-analysis.md) || APKs Android | Declarações do manifesto, classes, métodos descompilados e referências | JADX sem interface gráfica e um JDK completo no Linux/macOS/Windows x64; [guia de Android](docs/android-analysis.md) |+| Dispositivos Android | Dispositivos, pacotes, processos, logs, despejos, capturas de tela e transferências de APK/arquivos | adb fornecido pelo chamador (emulador ou aparelho); [guia de ADB](docs/adb-device-analysis.md) || Firmware | Regiões, resultados de extração e encaminhamentos à análise nativa | Binwalk / Unblob no Linux; [guia de firmware](docs/firmware-analysis.md) || Pacotes e recursos | Inventários de arquivos, digests, plists, estrutura de bundles Apple e recursos extraídos | [Guia de artefatos e JavaScript](docs/javascript-artifact-reconstruction.md), [aplicativos Apple](docs/apple-application-analysis.md) || Comportamento de processos | Saída do terminal, interações, observações de encerramento e do sistema de arquivos, e comparações entre execuções | Linux/macOS com PTY nativo; [captura de processos](docs/process-capture.md) |diff --git a/README_ru.md b/README_ru.mdindex 8e8e744ca..6912c9848 100644--- a/README_ru.md+++ b/README_ru.md@@ -142,6 +142,7 @@ REA требует Node.js 22.x (>=22.19), 24.x (>=24.11) или 26+, а так| Сохранённые сетевые захваты | Запросы, ответы, доступные полезные данные и позиции в источнике | HAR; mitmdump в Linux для захватов в собственном формате mitmproxy; [руководство по сетевым захватам](docs/web-network-captures.md) || Сборки .NET | Метаданные, инструкции CIL, объявленные нативные зависимости и сравнения сборок | Статическое исследование; [руководство по управляемому коду](docs/managed-code-analysis.md) || Android APK | Объявления манифеста, классы, декомпилированные методы и ссылки | JADX без графического интерфейса и полный JDK в Linux/macOS/Windows x64; [руководство по Android](docs/android-analysis.md) |+| Устройства Android | Устройства, пакеты, процессы, журналы, дампы, снимки экрана и передача APK/файлов | adb, предоставленный вызывающей стороной (эмулятор или устройство); [руководство по ADB](docs/adb-device-analysis.md) || Прошивки | Области, результаты извлечения и передача в нативный анализ | Binwalk / Unblob в Linux; [руководство по прошивкам](docs/firmware-analysis.md) || Пакеты и ресурсы | Списки файлов, хеши, plist, структура пакетов Apple и извлечённые ресурсы | [Руководство по артефактам и JavaScript](docs/javascript-artifact-reconstruction.md), [приложения Apple](docs/apple-application-analysis.md) || Поведение процессов | Вывод терминала, взаимодействия, наблюдения за завершением и файловой системой, сравнения запусков | Linux/macOS с нативным PTY; [захват процессов](docs/process-capture.md) |diff --git a/README_th.md b/README_th.mdindex 1e93f93b9..9c8e0fb5b 100644--- a/README_th.md+++ b/README_th.md@@ -142,6 +142,7 @@ REA ต้องใช้ Node.js 22.x (>=22.19), 24.x (>=24.11) หรือ 26| ข้อมูลเครือข่ายที่บันทึกไว้ | คำขอ คำตอบ เพย์โหลดที่ปรากฏ และตำแหน่งต้นทาง | HAR; mitmdump บน Linux สำหรับข้อมูลที่บันทึกในรูปแบบเนทีฟของ mitmproxy; [คู่มือการบันทึกข้อมูล](docs/web-network-captures.md) || แอสเซมบลี .NET | เมทาดาทา คำสั่ง CIL การพึ่งพาเนทีฟที่ประกาศไว้ และการเปรียบเทียบผลการบิลด์ | การตรวจสอบแบบสถิต; [คู่มือโค้ดแบบจัดการ](docs/managed-code-analysis.md) || APK ของ Android | การประกาศใน manifest คลาส เมธอดที่ดีคอมไพล์ และการอ้างอิง | JADX แบบไม่มี GUI และ JDK แบบเต็มบน Linux/macOS/Windows x64; [คู่มือ Android](docs/android-analysis.md) |+| อุปกรณ์ Android | อุปกรณ์ แพ็กเกจ โพรเซส บันทึก ดัมพ์ ภาพหน้าจอ และการถ่ายโอน APK/ไฟล์ | adb ที่ผู้เรียกจัดเตรียม (โปรแกรมจำลองหรืออุปกรณ์จริง); [คู่มือ ADB](docs/adb-device-analysis.md) || เฟิร์มแวร์ | พื้นที่ข้อมูล ผลการแตกไฟล์ และการส่งต่อไปวิเคราะห์เนทีฟ | Binwalk / Unblob บน Linux; [คู่มือเฟิร์มแวร์](docs/firmware-analysis.md) || แพ็กเกจและทรัพยากร | รายการไฟล์ ค่าแฮช plist โครงสร้างบันเดิลของ Apple และทรัพยากรที่แตกออกมา | [คู่มืออาร์ติแฟกต์และ JavaScript](docs/javascript-artifact-reconstruction.md), [แอปพลิเคชัน Apple](docs/apple-application-analysis.md) || พฤติกรรมของโปรเซส | เอาต์พุตเทอร์มินัล การโต้ตอบ ข้อมูลการสิ้นสุดและระบบไฟล์ที่สังเกตได้ และการเปรียบเทียบการรัน | Linux/macOS ที่มี PTY เนทีฟ; [การบันทึกโปรเซส](docs/process-capture.md) |diff --git a/README_tr.md b/README_tr.mdindex 46e1ab81d..cad5ef758 100644--- a/README_tr.md+++ b/README_tr.md@@ -142,6 +142,7 @@ REA; Node.js 22.x (>=22.19), 24.x (>=24.11) veya 26+ ve npm gerektirir. Ek araç| Kaydedilmiş ağ yakalamaları | İstekler, yanıtlar, erişilebilir yük içerikleri ve kaynak konumları | HAR; mitmproxy'nin kendi biçimindeki yakalamalar için Linux üzerinde mitmdump; [ağ yakalama rehberi](docs/web-network-captures.md) || .NET derlemeleri | Meta veriler, CIL talimatları, bildirilmiş yerel bağımlılıklar ve derleme karşılaştırmaları | Statik inceleme; [yönetilen kod rehberi](docs/managed-code-analysis.md) || Android APK'leri | Manifest bildirimleri, sınıflar, tersine derlenmiş metotlar ve referanslar | Linux/macOS/Windows x64 üzerinde arayüzsüz JADX ve tam bir JDK; [Android rehberi](docs/android-analysis.md) |+| Android cihazları | Cihazlar, paketler, süreçler, günlükler, dökümler, ekran görüntüleri ve APK/dosya aktarımları | Çağıranın sağladığı adb (emülatör veya cihaz); [ADB rehberi](docs/adb-device-analysis.md) || Donanım yazılımı | Bölgeler, çıkarma sonuçları ve yerel kod analizine devirler | Linux üzerinde Binwalk / Unblob; [donanım yazılımı rehberi](docs/firmware-analysis.md) || Paketler ve kaynaklar | Dosya envanterleri, özet değerleri, plist'ler, Apple paket yapısı ve çıkarılmış kaynaklar | [Artefakt ve JavaScript rehberi](docs/javascript-artifact-reconstruction.md), [Apple uygulamaları](docs/apple-application-analysis.md) || Süreç davranışı | Terminal çıktısı, etkileşimler, sonlanma ve dosya sistemi gözlemleri, çalıştırma karşılaştırmaları | Yerel PTY ile Linux/macOS; [süreç yakalama](docs/process-capture.md) |diff --git a/README_uk.md b/README_uk.mdindex c71e6f695..0d3d3e94c 100644--- a/README_uk.md+++ b/README_uk.md@@ -142,6 +142,7 @@ REA потребує Node.js 22.x (>=22.19), 24.x (>=24.11) або 26+, а та| Збережені мережеві захоплення | Запити, відповіді, доступні корисні дані та місця в джерелі | HAR; mitmdump у Linux для захоплень у власному форматі mitmproxy; [посібник мережевих захоплень](docs/web-network-captures.md) || Збірки .NET | Метадані, інструкції CIL, оголошені нативні залежності й порівняння збірок | Статична перевірка; [посібник керованого коду](docs/managed-code-analysis.md) || Android APK | Оголошення маніфесту, класи, декомпільовані методи й посилання | JADX без графічного інтерфейсу й повний JDK у Linux/macOS/Windows x64; [посібник Android](docs/android-analysis.md) |+| Пристрої Android | Пристрої, пакети, процеси, журнали, дампи, знімки екрана та передавання APK/файлів | adb, наданий викликаючою стороною (емулятор або пристрій); [підручник ADB](docs/adb-device-analysis.md) || Прошивки | Області, результати видобування й передавання до нативного аналізу | Binwalk / Unblob у Linux; [посібник прошивок](docs/firmware-analysis.md) || Пакети й ресурси | Переліки файлів, хеші, plist, структура пакетів Apple та видобуті ресурси | [Посібник артефактів і JavaScript](docs/javascript-artifact-reconstruction.md), [застосунки Apple](docs/apple-application-analysis.md) || Поведінка процесів | Вивід термінала, взаємодії, спостереження за завершенням і файловою системою та порівняння запусків | Linux/macOS із нативним PTY; [захоплення процесів](docs/process-capture.md) |diff --git a/README_vi.md b/README_vi.mdindex dc8c45a04..c837f7f63 100644--- a/README_vi.md+++ b/README_vi.md@@ -142,6 +142,7 @@ REA yêu cầu Node.js 22.x (>=22.19), 24.x (>=24.11) hoặc 26+, cùng với np| Bản ghi lưu lượng mạng đã lưu | Yêu cầu, phản hồi, payload có thể truy cập và vị trí nguồn | HAR; mitmdump trên Linux cho bản ghi định dạng gốc của mitmproxy; [hướng dẫn bản ghi mạng](docs/web-network-captures.md) || Assembly .NET | Siêu dữ liệu, lệnh CIL, các phụ thuộc mã máy được khai báo và so sánh bản dựng | Kiểm tra tĩnh; [hướng dẫn mã được quản lý](docs/managed-code-analysis.md) || APK Android | Khai báo manifest, lớp, phương thức được dịch ngược và tham chiếu | JADX không giao diện đồ họa và JDK đầy đủ trên Linux/macOS/Windows x64; [hướng dẫn Android](docs/android-analysis.md) |+| Thiết bị Android | Thiết bị, gói, tiến trình, nhật ký, dump, ảnh chụp màn hình và truyền APK/tệp | adb do nơi gọi cung cấp (trình giả lập hoặc thiết bị); [hướng dẫn ADB](docs/adb-device-analysis.md) || Phần sụn | Các vùng, kết quả trích xuất và dữ liệu chuyển sang phân tích mã máy | Binwalk / Unblob trên Linux; [hướng dẫn phần sụn](docs/firmware-analysis.md) || Gói và tài nguyên | Danh sách tệp, giá trị băm, plist, cấu trúc bundle Apple và tài nguyên được trích xuất | [Hướng dẫn hiện vật phần mềm và JavaScript](docs/javascript-artifact-reconstruction.md), [ứng dụng Apple](docs/apple-application-analysis.md) || Hành vi tiến trình | Đầu ra terminal, tương tác, quan sát khi thoát và hệ thống tệp, cùng so sánh các lần chạy | Linux/macOS có PTY gốc; [ghi lại tiến trình](docs/process-capture.md) |diff --git a/README_zh-TW.md b/README_zh-TW.mdindex 65167490f..df3eeaf28 100644--- a/README_zh-TW.md+++ b/README_zh-TW.md@@ -142,6 +142,7 @@ REA 需要 Node.js 22.x(>=22.19)、24.x(>=24.11)或 26+,以及 npm。| 已保存的網路擷取 | 請求、回應、可訪問的酬載和來源位置 | HAR;原生 mitmproxy 擷取需要 Linux 上的 mitmdump;[擷取指南](docs/web-network-captures.md) || .NET 程式集 | 中繼資料、CIL 指令、聲明的原生依賴和建置對比 | 靜態檢查;[托管程式碼指南](docs/managed-code-analysis.md) || Android APK | 清單聲明、類別、反編譯的方法和引用 | Linux/macOS/Windows x64 上的無界面 JADX 和完整 JDK;[Android 指南](docs/android-analysis.md) |+| Android 裝置 | 裝置、套件、程序、日誌、傾印、螢幕擷取以及 APK/檔案傳輸 | 呼叫端提供的 adb(模擬器或實體裝置);[ADB 指南](docs/adb-device-analysis.md) || 韌體 | 區域、提取結果和轉交原生分析的內容 | Linux 上的 Binwalk / Unblob;[韌體指南](docs/firmware-analysis.md) || 軟體包與資源 | 檔案清單、摘要、plist、Apple bundle 結構和提取的資源 | [製品與 JavaScript 指南](docs/javascript-artifact-reconstruction.md)、[Apple 應用](docs/apple-application-analysis.md) || 處理程序行為 | 終端輸出、互動、退出和檔案系統觀察結果,以及執行對比 | 支援原生 PTY 的 Linux/macOS;[處理程序擷取](docs/process-capture.md) |diff --git a/README_zh.md b/README_zh.mdindex 458f2b240..25aaa8449 100644--- a/README_zh.md+++ b/README_zh.md@@ -142,6 +142,7 @@ REA 需要 Node.js 22.x(>=22.19)、24.x(>=24.11)或 26+,以及 npm。| 已保存的网络捕获 | 请求、响应、可访问的载荷和来源位置 | HAR;原生 mitmproxy 捕获需要 Linux 上的 mitmdump;[捕获指南](docs/web-network-captures.md) || .NET 程序集 | 元数据、CIL 指令、声明的原生依赖和构建对比 | 静态检查;[托管代码指南](docs/managed-code-analysis.md) || Android APK | 清单声明、类、反编译的方法和引用 | Linux/macOS/Windows x64 上的无界面 JADX 和完整 JDK;[Android 指南](docs/android-analysis.md) |+| Android 设备 | 设备、软件包、进程、日志、转储、屏幕截图以及 APK/文件传输 | 调用方提供的 adb(模拟器或实体设备);[ADB 指南](docs/adb-device-analysis.md) || 固件 | 区域、提取结果和转交原生分析的内容 | Linux 上的 Binwalk / Unblob;[固件指南](docs/firmware-analysis.md) || 软件包与资源 | 文件清单、摘要、plist、Apple bundle 结构和提取的资源 | [制品与 JavaScript 指南](docs/javascript-artifact-reconstruction.md)、[Apple 应用](docs/apple-application-analysis.md) || 进程行为 | 终端输出、交互、退出和文件系统观察结果,以及运行对比 | 支持原生 PTY 的 Linux/macOS;[进程捕获](docs/process-capture.md) |diff --git a/docs/adb-device-analysis.md b/docs/adb-device-analysis.mdnew file mode 100644index 000000000..aa9e3e251--- /dev/null+++ b/docs/adb-device-analysis.md@@ -0,0 +1,164 @@+# ADB device inspection and acquisition++REA inspects connected Android devices, reads device state, and transfers+files and packages through the caller's `adb` binary. Emulators, USB+devices, and network devices participate alike: REA neither starts nor+manages them and never installs platform tools. Every operation composes a+fixed adb argument vector — caller values occupy positional arguments only+and are quoted when adb forwards them to the device shell.++The adb client may start its local server on first device query; that is adb+client behavior, recorded in the tool result when observed.+`inspect_adb_client` probes only the binary and never contacts the server.++## Supply tools++Use any Android platform-tools `adb` (verified with 34.0.5). Select it+through the environment:++```sh+# Optional: absolute path to the adb binary; without it, adb resolves from PATH.+export REA_ADB_PATH=/absolute/path/to/adb+```++REA never installs the Android SDK, an emulator, or a system image.+Readiness is `rea inspect-adb-client`: it runs `adb version` and reports the+resolved binary, its version, and where it was selected from. A missing+binary reports `capability_unavailable` with the `REA_ADB_PATH` remediation+rather than attempting an installation.++## Answer an analyst question++```sh+# Device identity+rea inspect-adb-client+rea list-adb-devices+rea inspect-adb-device emulator-5554+rea inspect-adb-display emulator-5554+rea list-adb-features emulator-5554+rea list-adb-services emulator-5554++# Find and acquire an app (the easy-get flow)+rea resolve-adb-packages emulator-5554 whatsapp+rea list-adb-packages emulator-5554 --scope third_party+rea inspect-adb-package emulator-5554 com.whatsapp+rea pull-adb-package emulator-5554 com.whatsapp --output-directory /tmp/acq+rea inspect-android-package /tmp/acq/com.whatsapp/base.apk++# Device state and files+rea list-adb-processes emulator-5554+rea inspect-adb-window emulator-5554+rea read-adb-setting emulator-5554 global adb_enabled+rea read-adb-logcat emulator-5554 --count 200+rea list-adb-directory emulator-5554 /data/data/com.whatsapp+rea pull-adb-file emulator-5554 /data/local/tmp/notes.txt --output-directory /tmp/acq+rea push-adb-file emulator-5554 /tools/frida-server /data/local/tmp/frida-server+rea capture-adb-screen emulator-5554 --output-directory /tmp/shots+rea collect-adb-bugreport emulator-5554 --output-directory /tmp/bugs++# Package lifecycle and dynamic analysis (device-mutating)+rea install-adb-package emulator-5554 /tmp/app.apk --replace+rea start-adb-app emulator-5554 com.example.app+rea read-adb-logcat emulator-5554 --pid 12345+rea start-adb-activity emulator-5554 android.intent.action.VIEW --data-uri https://example.com+rea stop-adb-app emulator-5554 com.example.app+rea uninstall-adb-package emulator-5554 com.example.app+```++Equivalent MCP methods use the snake_case names (`list_adb_devices`,+`pull_adb_package`, `resolve_adb_packages`, …). Device operations take+`serial` exactly as `adb devices` reports it. The pulled APK set feeds the+existing analysis families directly, for example+`rea inspect-android-package /tmp/acq/<package>/base.apk`.++## Operations++| Tool | Kind | What it does |+| ----------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `inspect_adb_client` | read | Resolved binary, version, install path; never contacts the server |+| `list_adb_devices` | read | Serial, state, transport, model metadata, inferred emulator/physical kind with basis |+| `inspect_adb_device` | read | Fixed `getprop` whitelist: build, SDK, patch, fingerprint, product, ABIs, debuggable, `ro.kernel.qemu` |+| `inspect_adb_display` | read | `wm size` and `wm density` as declared |+| `list_adb_features` | read | `pm list features` (hardware/software features, hex GL versions) |+| `list_adb_services` | read | `service list` binder services and interfaces |+| `list_adb_processes` | read | `ps -A`: user, pid, ppid, rss, state, name |+| `inspect_adb_window` | read | `dumpsys window` focus declarations (what is on screen) |+| `read_adb_setting` | read | One `settings get` value; device-side null is reported as such |+| `read_adb_logcat` | read | Bounded `logcat -d -t` dump for one buffer, optional pid filter |+| `list_adb_packages` | read | `pm list packages -f` with scope; base APK device paths |+| `resolve_adb_packages` | read | Case-insensitive package-name substring search with exact-match flag |+| `inspect_adb_package` | read | `dumpsys package` projection: versions, install times, installer, flags, permission count |+| `list_adb_directory` | read | `ls -la`: kinds, permissions, owner, group, sizes, symlink targets |+| `pull_adb_package` | read | Complete split APK set from `pm path`, each file digested |+| `pull_adb_file` | read | One absolute device path pulled and digested |+| `capture_adb_screen` | read | One `screencap -p` frame (exec-out, no device-side file) with dimensions |+| `collect_adb_bugreport` | read | Device-generated bugreport zip, digested |+| `push_adb_file` | **mutates device** | One local file to a device path (e.g. pushing tools into `/data/local/tmp`); refuses existing targets without explicit overwrite; verifies via the device's own sha256sum |+| `install_adb_package` | **mutates device** | Local APK via `adb install [-r]`; preserves the device's Success/Failure verdict |+| `uninstall_adb_package` | **mutates device** | Removes a package and its data for user 0 |+| `start_adb_app` | **mutates device** | Resolves the package's launcher activity (`cmd package resolve-activity --brief`) and starts it (`am start -n`) |+| `start_adb_activity` | **mutates device** | Starts an intent (`am start -a` with optional URI, component, and up to 16 typed extras); preserves the activity manager's verdict |+| `stop_adb_app` | **mutates device** | Force-stops every process of a package, ending a dynamic-analysis run |++## Interpret the result++- **Inferences carry their basis.** Device `kind` reports+ `kind_basis` (serial prefix or USB transport); APK `role` reports+ `role_basis: file_name`; `emulator_observed` is the build's own+ `ro.kernel.qemu` value, `null` when absent.+- **Device paths are not host paths.** `base_apk_device_path` values live on+ the device filesystem. Only pulls and captures produce host-local paths,+ each paired with byte size and SHA-256 digest.+- **Splits are part of the answer.** `pm path` enumerates the base APK and+ every installed split; pulls cover the whole set. System packages whose+ APKs keep other names report the `unknown` role rather than guessing.+- **Partial results keep facts.** Failed individual pulls return successful+ artifacts with `coverage: "partial"` and per-file `failures`. Listings+ that contain unrecognized lines report them as `unparsed_lines` and mark+ partial coverage instead of dropping rows.+- **Mutations are explicit.** `push_adb_file`, `install_adb_package`, and+ `uninstall_adb_package` declare `mutatesTarget` and never run implicitly:+ pushes refuse existing device files unless `overwrite` is set and verify+ the transfer with the device's own `sha256sum`; installs preserve the+ device's `Failure [...]` reason verbatim.+- **Producer identity stays attached.** Every result embeds the producing+ adb client (`binary_path`, `path_source`, `version`, `installed_path`).++## Resource and lifecycle limits++- Caller values reach adb only as positional arguments in fixed vectors;+ no tool accepts an arbitrary shell command line, and UI interaction+ (`input`, `am`, `monkey`) is deliberately not exposed.+- Per-invocation budgets: client/devices 10-20 s, shell reads 20-60 s with+ 64 KiB-8 MiB capture caps (logcat 4 MiB, screen 32 MiB), transfers and+ bugreports 600 s. Exceeded budgets report `resource_constraint`; stopped+ commands report `provider_timeout`.+- Pull and capture outputs are additive: the destination must not already+ exist. Re-running a completed pull refuses the existing directory instead+ of overwriting evidence.+- The provider holds no long-lived processes; every invocation is one+ bounded adb run. The adb server belongs to the caller.++## Related capability and follow-up lanes++UI interaction beyond intent starts (tapping, typing, monkey fuzzing, screen+recording) remains a separate lane: candidates such as+[mobile-device-mcp](https://github.com/srmorete/mobile-device-mcp) install+driver software on the device and pair with the Frida instrumentation lane+(#1359) behind explicit mutation-authority contracts. Network transports+beyond already-connected devices (`adb connect`) are not exposed yet.++## Real verification++`npm run verify:adb` exercises every operation against a live device. It+requires `adb` (or `REA_ADB_PATH`) and any attached emulator or phone;+`--serial` selects one when several are attached, `--pull PACKAGE` pulls a+real package and verifies the returned digests against the files on disk,+and `--install-apk PATH` drives a full install → resolve → uninstall+lifecycle with a lane-owned probe.++Record: verified against adb 34.0.5 on Linux against an Android 14+(API 34) x86_64 emulator — all operations above, a 224-package inventory,+287 services, 92 features, a real two-APK split set pulled with byte-exact+digests, a verified push/pull roundtrip, a 1.3 MB screen capture, and the+complete package lifecycle; see `docs/testing.md` for the lane summary.diff --git a/docs/testing.md b/docs/testing.mdindex 61440dfb1..d4c0366ae 100644--- a/docs/testing.md+++ b/docs/testing.md@@ -545,6 +545,37 @@ Synthetic producer regressions run independently:npm run test:focused -- tests/boundary/process/jadxIntegration.test.ts tests/boundary/process/androidAnalysisMcp.test.ts```+## ADB device acquisition++`npm run verify:adb` exercises every ADB operation against a live device or+emulator through the caller's adb binary (`REA_ADB_PATH` or PATH). No SDK+installation or emulator management is involved; the device-mutating tools+run only in the explicit lifecycle section (`--install-apk` drives a+lane-owned install → resolve → start → observe → force-stop → uninstall+probe). `--pull` acquires a real package and re-digests the pulled files on+disk against the returned SHA-256 values; `--serial` selects a device when+several are attached.++Record: adb 34.0.5-debian on Linux against an Android 14 (API 34) x86_64+emulator. The lane covered the complete observation surface — 337-process+listing, 287 binder services including AIDL `/`-suffixed names, 92 features+including hex GL versions, display size/density, window focus (legitimately+null on headless devices), `settings get global adb_enabled`, bounded+logcat, directory listings — plus a real two-APK split set+(`base.apk` plus `split_probe.apk`, built and installed through+`install-multiple`) pulled with byte-exact digests, a push/pull roundtrip+verified by the device's own sha256sum, a 1.3 MB screen capture with PNG+dimensions, `dumpsys package` projection, and the full lifecycle: unique+resolution before launch, launcher-activity start through+`cmd package resolve-activity` with `am start -W`, the started app visible+in the process listing, force-stop, uninstall, and zero matches after+removal. System-package pulls whose APKs keep non-`base.apk` names report+the `unknown` role with the file-name basis, verified with+`com.android.settings` (single 73.9 MB APK). Parser goldens for+`adb devices -l`, `getprop`, `pm list packages -f`, and `pm path` come from+the same device. See [ADB device analysis](adb-device-analysis.md) for+boundaries and budgets.+## Optional NativeAOT Ghidra analysisThis lane is separate from the default native lane. `build:fixtures:nativeaot`diff --git a/package.json b/package.jsonindex ed36813a8..018594047 100644--- a/package.json+++ b/package.json@@ -146,6 +146,7 @@"verify:macos-bundle": "npm run build:cached && node scripts/verify/apple/macos-bundle.mjs","verify:legacy-simulator": "npm run build:cached && node scripts/verify/apple/legacy-simulator.mjs","verify:architecture-guards": "node scripts/verify/architecture-guards.mjs",+ "verify:adb": "npm run build:cached && node scripts/verify-adb.mjs","verify:ghidra": "npm run build:cached && node scripts/verify-real-ghidra.mjs","verify:ghidra:swift": "npm run build:cached && node scripts/verify-real-ghidra-swift.mjs","verify:ida": "npm run build:cached && node scripts/verify-real-ida.mjs",diff --git a/scripts/lib/catalog-builders.mjs b/scripts/lib/catalog-builders.mjsindex 7aefdf734..9218dc8e2 100644--- a/scripts/lib/catalog-builders.mjs+++ b/scripts/lib/catalog-builders.mjs@@ -47,6 +47,11 @@ export const toolFamilyCatalog = (sources) => {surface: "android-provider",contracts: sources.androidContracts.ANDROID_TOOL_CONTRACTS,},+ {+ id: "adb",+ surface: "adb-provider",+ contracts: sources.adbContracts.ADB_TOOL_CONTRACTS,+ },{id: "browser",surface: "browser-provider",@@ -188,6 +193,10 @@ export const providerCatalog = (sources) => {identity: sources.androidProvider.JADX_PROVIDER_IDENTITY,contracts: sources.androidContracts.ANDROID_TOOL_CONTRACTS,},+ {+ identity: sources.adbProvider.ADB_PROVIDER_IDENTITY,+ contracts: sources.adbContracts.ADB_TOOL_CONTRACTS,+ },{identity: sources.webNetworkCaptureProvider.HAR_CAPTURE_PROVIDER_IDENTITY,contracts:diff --git a/scripts/lib/catalog-core.mjs b/scripts/lib/catalog-core.mjsindex 7792c1932..4254177d6 100644--- a/scripts/lib/catalog-core.mjs+++ b/scripts/lib/catalog-core.mjs@@ -53,6 +53,8 @@ const SOURCE_PATHS = {firmwareProvider: "dist/firmware/FirmwareRelease.js",androidContracts: "dist/contracts/android/androidToolContracts.js",androidProvider: "dist/android/JadxRelease.js",+ adbContracts: "dist/contracts/adb/adbToolContracts.js",+ adbProvider: "dist/adb/AdbProvider.js",managedWorkflowContracts:"dist/contracts/managed/managedWorkflowToolContracts.js",browserContracts: "dist/contracts/browserToolContracts.js",diff --git a/scripts/verify-adb.mjs b/scripts/verify-adb.mjsnew file mode 100644index 000000000..27c9cd5bf--- /dev/null+++ b/scripts/verify-adb.mjs@@ -0,0 +1,400 @@+import { createHash } from "node:crypto";+import { mkdtemp, readFile, rm, stat } from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { AdbDeviceAnalysisService } from "../dist/application/adb/AdbDeviceAnalysisService.js";+import { createAdbDeviceAnalysisProvider } from "../dist/composition/adb.js";++const options = parseArguments(process.argv.slice(2));+if (options.help) {+ process.stdout.write(+ "Usage: npm run verify:adb [-- --serial SERIAL --pull PACKAGE]\n" ++ "Requires a caller-selected adb binary (REA_ADB_PATH or PATH) and a\n" ++ "connected device or emulator. Verifies all five operations against\n" ++ "the live device; --pull acquires a real package and re-digests the\n" ++ "files on disk against the returned SHA-256 values.\n",+ );+ process.exit(0);+}++const provider = createAdbDeviceAnalysisProvider(process.env);+const service = new AdbDeviceAnalysisService(provider);+let failures = 0;+const check = (name, condition, detail = "") => {+ const mark = condition ? "ok" : "FAIL";+ process.stdout.write(+ `[${mark}] ${name}${detail === "" ? "" : ` — ${detail}`}\n`,+ );+ if (!condition) failures += 1;+};++const run = async (operation, input) => {+ const result = await service.execute(operation, input);+ if (!result.ok) {+ process.stdout.write(`[FAIL] ${operation} — ${result.error.message}\n`);+ failures += 1;+ return null;+ }+ return result.value.normalized_result;+};++const client = await run("inspect_adb_client", {});+if (client !== null) {+ check(+ "adb client reports a version",+ typeof client.client.version === "string" && client.client.version !== "",+ `binary=${client.client.binary_path} version=${client.client.version}`,+ );+}++const listing = await run("list_adb_devices", {});+let serial = options.serial ?? null;+if (listing !== null) {+ check(+ "device listing parsed",+ Array.isArray(listing.devices),+ `${listing.devices.length} device(s)`,+ );+ const usable = listing.devices.filter((device) => device.state === "device");+ if (serial === null && usable.length > 0) serial = usable[0].serial;+ if (serial === null) {+ process.stdout.write(+ "[FAIL] no usable device is attached; start an emulator or connect a phone\n",+ );+ failures += 1;+ } else {+ const selected = listing.devices.find((device) => device.serial === serial);+ check(+ "selected device present with a kind inference",+ selected !== undefined &&+ ["emulator", "physical", "unknown"].includes(selected.kind),+ `serial=${serial} kind=${selected?.kind} basis=${selected?.kind_basis}`,+ );+ }+}++if (serial !== null) {+ const device = await run("inspect_adb_device", { serial });+ if (device !== null) {+ check(+ "device build identity projected",+ device.properties.some(+ (property) => property.name === "ro.build.version.sdk",+ ),+ `sdk=${+ device.properties.find((p) => p.name === "ro.build.version.sdk")?.value+ } emulator_observed=${String(device.emulator_observed)}`,+ );+ }++ // Observation tools: processes, window, display, settings, logcat.+ const processes = await run("list_adb_processes", { serial });+ if (processes !== null) {+ check(+ "process listing is non-empty with a header",+ processes.processes.length > 0 && typeof processes.columns === "string",+ `${processes.processes.length} process(es)`,+ );+ }+ const window = await run("inspect_adb_window", { serial });+ if (window !== null)+ check(+ "window focus observation completed",+ typeof window.focused_window === "string" ||+ window.focused_window === null,+ `focused_window=${String(window.focused_window).slice(0, 60)} (null is legitimate on headless devices)`,+ );+ const display = await run("inspect_adb_display", { serial });+ if (display !== null)+ check(+ "display reports a physical size",+ display.physical_size !== null &&+ display.physical_size.width > 0 &&+ display.physical_size.height > 0,+ `${display.physical_size?.width}x${display.physical_size?.height} @${String(display.physical_density)}`,+ );+ const setting = await run("read_adb_setting", {+ serial,+ namespace: "global",+ key: "adb_enabled",+ });+ if (setting !== null)+ check(+ "settings read returns the device's own value",+ setting.value === "1",+ `adb_enabled=${String(setting.value)}`,+ );+ const logcat = await run("read_adb_logcat", {+ serial,+ count: 20,+ buffer: "main",+ });+ if (logcat !== null)+ check(+ "logcat dump returns bounded lines",+ logcat.lines.length <= 20,+ `${logcat.lines.length} line(s), coverage=${logcat.coverage}`,+ );+ const features = await run("list_adb_features", { serial });+ if (features !== null)+ check(+ "feature inventory is non-empty",+ features.coverage === "complete" && features.features.length > 0,+ `${features.features.length} feature(s)`,+ );+ const services = await run("list_adb_services", { serial });+ if (services !== null)+ check(+ "service inventory is non-empty",+ services.coverage === "complete" && services.services.length > 0,+ `${services.services.length} service(s)`,+ );+ const directory = await run("list_adb_directory", {+ serial,+ device_path: "/data/local/tmp",+ });+ if (directory !== null)+ check(+ "directory listing completed",+ directory.coverage === "complete",+ `${directory.entries.length} entr(ies)`,+ );++ const packages = await run("list_adb_packages", {+ serial,+ scope: "third_party",+ });+ let pullCandidate = options.pull ?? null;+ if (packages !== null) {+ // A third-party scope may legitimately be empty (clean emulator images);+ // completeness is about unparsed lines, not row count.+ check(+ "third-party package listing reports complete coverage",+ packages.coverage === "complete",+ `${packages.packages.length} package(s)`,+ );+ const allPackages = await run("list_adb_packages", {+ serial,+ scope: "all",+ });+ if (allPackages !== null) {+ check(+ "full package inventory is non-empty",+ allPackages.coverage === "complete" && allPackages.packages.length > 0,+ `${allPackages.packages.length} package(s)`,+ );+ }+ if (pullCandidate === null && packages.packages.length > 0)+ pullCandidate = packages.packages[0].package_name;+ }++ if (pullCandidate !== null) {+ const directory = await mkdtemp(join(tmpdir(), "rea-adb-verify-"));+ try {+ const pull = await run("pull_adb_package", {+ serial,+ package: pullCandidate,+ output_directory: directory,+ });+ if (pull !== null) {+ // Installed /data/app packages name their APKs base.apk and+ // split_*.apk; system packages keep arbitrary names, so the lane+ // checks a non-empty artifact set and verifies each file on disk.+ check(+ "pull returned a non-empty artifact set",+ pull.artifacts.length > 0,+ `${pull.artifacts.length} artifact(s), coverage=${pull.coverage}, roles=${pull.artifacts.map((a) => a.role).join(",")}`,+ );+ for (const artifact of pull.artifacts) {+ const bytes = await stat(artifact.local_path).then(+ (info) => info.size,+ );+ const digest = createHash("sha256")+ .update(await readFile(artifact.local_path))+ .digest("hex");+ check(+ `artifact digest matches on disk: ${artifact.file_name}`,+ bytes === artifact.bytes && digest === artifact.sha256,+ `${bytes} bytes`,+ );+ }+ }+ } finally {+ await rm(directory, { recursive: true, force: true });+ }+ }++ // File transfer: push one lane-owned file, verify both digests, pull it+ // back, then clean up the device copy through the same fixed argv surface.+ const transferRoot = await mkdtemp(join(tmpdir(), "rea-adb-transfer-"));+ try {+ const payload = join(transferRoot, "rea-verify.txt");+ const payloadBytes = "rea adb transfer verification\n";+ await import("node:fs/promises").then((fs) =>+ fs.writeFile(payload, payloadBytes),+ );+ const deviceTarget = `/data/local/tmp/rea-verify-${Date.now()}.txt`;+ const pushed = await run("push_adb_file", {+ serial,+ local_path: payload,+ device_path: deviceTarget,+ overwrite: false,+ });+ if (pushed !== null) {+ check(+ "push reports matching device-side digest",+ pushed.device_digest_source === "device_sha256sum" &&+ pushed.device_sha256 === pushed.sha256,+ `${pushed.bytes} bytes`,+ );+ const pulled = await run("pull_adb_file", {+ serial,+ device_path: deviceTarget,+ output_directory: transferRoot,+ });+ if (pulled !== null)+ check(+ "pulled file digest matches the pushed digest",+ pulled.sha256 === pushed.sha256,+ `${pulled.bytes} bytes`,+ );+ }+ const screenRoot = await mkdtemp(join(tmpdir(), "rea-adb-screen-"));+ try {+ const screen = await run("capture_adb_screen", {+ serial,+ output_directory: screenRoot,+ });+ if (screen !== null)+ check(+ "screen capture is a sized PNG",+ screen.width !== null && screen.height !== null && screen.bytes > 0,+ `${screen.width}x${screen.height}, ${screen.bytes} bytes`,+ );+ } finally {+ await rm(screenRoot, { recursive: true, force: true });+ }+ if (options.pull !== null) {+ const details = await run("inspect_adb_package", {+ serial,+ package: options.pull,+ });+ if (details !== null)+ check(+ "dumpsys package projection completed",+ details.coverage === "complete",+ `versionCode=${String(details.version_code)}`,+ );+ }+ if (options.installApk !== null && options.installApk !== undefined) {+ const probePackage = "com.rea.adb.probe";+ const installedProbe = await run("install_adb_package", {+ serial,+ apk_path: options.installApk,+ replace: false,+ });+ if (installedProbe !== null) {+ check(+ "install reports the APK digest",+ typeof installedProbe.sha256 === "string" &&+ installedProbe.sha256.length === 64,+ `${installedProbe.bytes} bytes`,+ );+ const resolved = await run("resolve_adb_packages", {+ serial,+ query: "rea.adb.probe",+ });+ if (resolved !== null)+ check(+ "resolve finds the installed probe uniquely",+ resolved.matches.length === 1 &&+ resolved.matches[0]?.package_name === probePackage,+ `${resolved.matches.length} match(es)`,+ );+ const started = await run("start_adb_app", {+ serial,+ package: probePackage,+ });+ if (started !== null)+ check(+ "app start resolves and launches the launcher activity",+ typeof started.component === "string" &&+ started.component.startsWith(probePackage),+ String(started.component),+ );+ const observedProcesses = await run("list_adb_processes", { serial });+ if (observedProcesses !== null)+ check(+ "started app appears in the process listing",+ observedProcesses.processes.some(+ (process) => process.name === probePackage,+ ),+ );+ const stopped = await run("stop_adb_app", {+ serial,+ package: probePackage,+ });+ if (stopped !== null)+ check(+ "force-stop completes the dynamic-analysis run",+ stopped.package_name === probePackage,+ );+ const removed = await run("uninstall_adb_package", {+ serial,+ package: probePackage,+ });+ if (removed !== null)+ check(+ "uninstall completes the lifecycle",+ removed.package_name === probePackage,+ );+ const afterRemoval = await run("resolve_adb_packages", {+ serial,+ query: "rea.adb.probe",+ });+ if (afterRemoval !== null)+ check(+ "resolve reports zero matches after removal",+ afterRemoval.matches.length === 0,+ );+ }+ }+ } finally {+ await rm(transferRoot, { recursive: true, force: true });+ }+}++try {+ await provider.close();+} catch {+ // The provider owns nothing long-lived; closing is best-effort.+}++if (failures > 0) {+ process.stdout.write(`\n${failures} check(s) failed\n`);+ process.exit(1);+}+process.stdout.write("\nall adb device checks passed\n");++function parseArguments(argv) {+ const parsed = { help: false, serial: null, pull: null, installApk: null };+ for (let index = 0; index < argv.length; index += 1) {+ const argument = argv[index];+ if (argument === "--help" || argument === "-h") parsed.help = true;+ else if (argument === "--serial") {+ parsed.serial = argv[index + 1] ?? null;+ index += 1;+ } else if (argument === "--pull") {+ parsed.pull = argv[index + 1] ?? null;+ index += 1;+ } else if (argument === "--install-apk") {+ parsed.installApk = argv[index + 1] ?? null;+ index += 1;+ } else {+ process.stderr.write(`unknown argument: ${argument}\n`);+ process.exit(2);+ }+ }+ return parsed;+}diff --git a/src/adb/AdbConfiguration.test.ts b/src/adb/AdbConfiguration.test.tsnew file mode 100644index 000000000..ea5039d22--- /dev/null+++ b/src/adb/AdbConfiguration.test.ts@@ -0,0 +1,58 @@+import { describe, expect, it } from "vitest";++import {+ ADB_BINARY_ENV,+ parseAdbVersionOutput,+ resolveAdbBinary,+} from "./AdbConfiguration.js";++describe("resolveAdbBinary", () => {+ it("prefers an absolute REA_ADB_PATH", () => {+ expect(resolveAdbBinary({ [ADB_BINARY_ENV]: "/opt/tools/adb" })).toEqual({+ binary: "/opt/tools/adb",+ pathSource: "environment",+ });+ });++ it("falls back to PATH resolution without the environment key", () => {+ expect(resolveAdbBinary({})).toEqual({+ binary: "adb",+ pathSource: "path",+ });+ expect(resolveAdbBinary({ [ADB_BINARY_ENV]: " " })).toEqual({+ binary: "adb",+ pathSource: "path",+ });+ });++ it("rejects a relative environment path explicitly", () => {+ expect(() => resolveAdbBinary({ [ADB_BINARY_ENV]: "tools/adb" })).toThrow(+ /must be an absolute path/u,+ );+ });+});++describe("parseAdbVersionOutput", () => {+ it("reads the build version and install path from real output", () => {+ expect(+ parseAdbVersionOutput(+ [+ "Android Debug Bridge version 1.0.41",+ "Version 34.0.5-debian",+ "Installed as /usr/lib/android-sdk/platform-tools/adb",+ "",+ ].join("\n"),+ ),+ ).toEqual({+ version: "34.0.5-debian",+ installedPath: "/usr/lib/android-sdk/platform-tools/adb",+ });+ });++ it("reports null identity fields when the named lines are absent", () => {+ expect(parseAdbVersionOutput("unexpected output")).toEqual({+ version: null,+ installedPath: null,+ });+ });+});diff --git a/src/adb/AdbConfiguration.ts b/src/adb/AdbConfiguration.tsnew file mode 100644index 000000000..15e2e40eb--- /dev/null+++ b/src/adb/AdbConfiguration.ts@@ -0,0 +1,144 @@+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;diff --git a/src/adb/AdbDeviceOutput.test.ts b/src/adb/AdbDeviceOutput.test.tsnew file mode 100644index 000000000..b85061cae--- /dev/null+++ b/src/adb/AdbDeviceOutput.test.ts@@ -0,0 +1,242 @@+import { describe, expect, it } from "vitest";++import {+ parseAdbDevicesOutput,+ parseGetpropOutput,+ parsePackageListOutput,+ parsePmPathOutput,+} from "./AdbDeviceOutput.js";++describe("parseAdbDevicesOutput", () => {+ it("parses emulator, USB, and network devices with their metadata", () => {+ const output = [+ "List of devices attached",+ "emulator-5554 device product:sdk_gphone64_x86_64 model:sdk_gphone64_x86_64 device:emu64xa transport_id:1",+ "07ef9c2a device usb:1-1 product:raven model:Pixel_6_Pro device:raven transport_id:2",+ "192.168.1.42:5555 device product:mock model:mock transport_id:3",+ "",+ ].join("\n");+ const { devices, unparsedLines, daemonStarted } =+ parseAdbDevicesOutput(output);+ expect(unparsedLines).toEqual([]);+ expect(daemonStarted).toBe(false);+ expect(devices).toEqual([+ {+ serial: "emulator-5554",+ state: "device",+ transport: "tcp",+ product: "sdk_gphone64_x86_64",+ model: "sdk_gphone64_x86_64",+ device: "emu64xa",+ transport_id: 1,+ kind: "emulator",+ kind_basis: "emulator_serial_prefix",+ },+ {+ serial: "07ef9c2a",+ state: "device",+ transport: "usb",+ product: "raven",+ model: "Pixel_6_Pro",+ device: "raven",+ transport_id: 2,+ kind: "physical",+ kind_basis: "usb_transport",+ },+ {+ serial: "192.168.1.42:5555",+ state: "device",+ transport: "tcp",+ product: "mock",+ model: "mock",+ device: null,+ transport_id: 3,+ kind: "unknown",+ kind_basis: "none",+ },+ ]);+ });++ it("recognizes daemon startup notices instead of failing the listing", () => {+ const output = [+ "* daemon not running; starting now at tcp:5037",+ "* daemon started successfully",+ "List of devices attached",+ "emulator-5554 device transport_id:1",+ "",+ ].join("\n");+ const { devices, daemonStarted } = parseAdbDevicesOutput(output);+ expect(daemonStarted).toBe(true);+ expect(devices).toHaveLength(1);+ });++ it("keeps non-device states such as unauthorized and offline", () => {+ const output = [+ "List of devices attached",+ "emulator-5556 offline transport_id:2",+ "HT84L0240512 unauthorized usb:1-2 transport_id:3",+ "",+ ].join("\n");+ const { devices } = parseAdbDevicesOutput(output);+ expect(devices.map((device) => [device.serial, device.state])).toEqual([+ ["emulator-5556", "offline"],+ ["HT84L0240512", "unauthorized"],+ ]);+ });++ it("returns unrecognized lines instead of dropping them", () => {+ const output = [+ "List of devices attached",+ "this is not a device line",+ "",+ ].join("\n");+ const { unparsedLines } = parseAdbDevicesOutput(output);+ expect(unparsedLines).toEqual(["this is not a device line"]);+ });++ it("reports a non-numeric transport_id as unknown", () => {+ const output = [+ "List of devices attached",+ "emulator-5554 device transport_id:not-a-number",+ "",+ ].join("\n");+ const { devices } = parseAdbDevicesOutput(output);+ expect(devices[0]?.transport_id).toBeNull();+ });+});++describe("parseGetpropOutput", () => {+ it("projects the whitelisted build identity from a real dump", () => {+ const dump = [+ "[ro.build.version.release]: [14]",+ "[ro.build.version.sdk]: [34]",+ "[ro.build.version.security_patch]: [2024-06-05]",+ "[ro.build.id]: [AP21.240617.014]",+ "[ro.build.fingerprint]: [google/sdk_gphone64_x86_64/emu64xa:14/AP21.240617.014/12094027:userdebug/dev-keys]",+ "[ro.product.brand]: [google]",+ "[ro.product.device]: [emu64xa]",+ "[ro.product.manufacturer]: [Google]",+ "[ro.product.model]: [sdk_gphone64_x86_64]",+ "[ro.product.cpu.abilist]: [x86_64,x86,arm64-v8a,armeabi-v7a,armeabi]",+ "[ro.kernel.qemu]: [1]",+ "[ro.debuggable]: [1]",+ "[sys.unlisted.property]: [dropped]",+ "",+ ].join("\n");+ const { properties, emulatorObserved } = parseGetpropOutput(dump);+ expect(emulatorObserved).toBe(true);+ expect(properties).not.toContainEqual({+ name: "sys.unlisted.property",+ value: "dropped",+ });+ expect(properties).toEqual([+ { name: "ro.build.version.release", value: "14" },+ { name: "ro.build.version.sdk", value: "34" },+ { name: "ro.build.version.security_patch", value: "2024-06-05" },+ { name: "ro.build.id", value: "AP21.240617.014" },+ {+ name: "ro.build.fingerprint",+ value:+ "google/sdk_gphone64_x86_64/emu64xa:14/AP21.240617.014/12094027:userdebug/dev-keys",+ },+ { name: "ro.debuggable", value: "1" },+ { name: "ro.kernel.qemu", value: "1" },+ { name: "ro.product.brand", value: "google" },+ { name: "ro.product.device", value: "emu64xa" },+ { name: "ro.product.manufacturer", value: "Google" },+ { name: "ro.product.model", value: "sdk_gphone64_x86_64" },+ {+ name: "ro.product.cpu.abilist",+ value: "x86_64,x86,arm64-v8a,armeabi-v7a,armeabi",+ },+ ]);+ });++ it("reports an explicit non-emulator build without inventing a value", () => {+ const dump = [+ "[ro.build.version.release]: [13]",+ "[ro.kernel.qemu]: [0]",+ "",+ ].join("\n");+ const { emulatorObserved } = parseGetpropOutput(dump);+ expect(emulatorObserved).toBe(false);+ });++ it("reports the emulator indicator unknown when the build omits it", () => {+ const { emulatorObserved } = parseGetpropOutput(+ "[ro.build.version.sdk]: [33]\n",+ );+ expect(emulatorObserved).toBeNull();+ });+});++describe("parsePackageListOutput", () => {+ it("parses package lines with their base APK device paths", () => {+ const output = [+ "package:/data/app/~~xy==/com.example.npzyCvVb1I-YzKIsGFvVYw==/base.apk=com.example",+ "package:/system/app/WebView/WebView.apk=com.android.webview",+ "",+ ].join("\n");+ const { packages, unparsedLines } = parsePackageListOutput(output);+ expect(unparsedLines).toEqual([]);+ expect(packages).toEqual([+ {+ package_name: "com.example",+ base_apk_device_path:+ "/data/app/~~xy==/com.example.npzyCvVb1I-YzKIsGFvVYw==/base.apk",+ },+ {+ package_name: "com.android.webview",+ base_apk_device_path: "/system/app/WebView/WebView.apk",+ },+ ]);+ });++ it("keeps unrecognized lines for partial coverage reporting", () => {+ const { packages, unparsedLines } = parsePackageListOutput(+ "package:/data/app/x/base.apk=com.ok\ngarbage line\n",+ );+ expect(packages).toHaveLength(1);+ expect(unparsedLines).toEqual(["garbage line"]);+ });+});++describe("parsePmPathOutput", () => {+ it("classifies base and split APKs from their file names", () => {+ const output = [+ "package:/data/app/~~a==/com.example.b==/base.apk",+ "package:/data/app/~~a==/com.example.b==/split_config.arm64_v8a.apk",+ "package:/data/app/~~a==/com.example.b==/split_config.en.apk",+ "",+ ].join("\n");+ const { paths, unparsedLines } = parsePmPathOutput(output);+ expect(unparsedLines).toEqual([]);+ expect(paths).toEqual([+ {+ device_path: "/data/app/~~a==/com.example.b==/base.apk",+ file_name: "base.apk",+ role: "base",+ },+ {+ device_path:+ "/data/app/~~a==/com.example.b==/split_config.arm64_v8a.apk",+ file_name: "split_config.arm64_v8a.apk",+ role: "split",+ },+ {+ device_path: "/data/app/~~a==/com.example.b==/split_config.en.apk",+ file_name: "split_config.en.apk",+ role: "split",+ },+ ]);+ });++ it("reports an unknown role for names that follow neither convention", () => {+ const { paths } = parsePmPathOutput("package:/system/app/X/Y.apk\n");+ expect(paths[0]).toEqual({+ device_path: "/system/app/X/Y.apk",+ file_name: "Y.apk",+ role: "unknown",+ });+ });+});diff --git a/src/adb/AdbDeviceOutput.ts b/src/adb/AdbDeviceOutput.tsnew file mode 100644index 000000000..44bbb53ba--- /dev/null+++ b/src/adb/AdbDeviceOutput.ts@@ -0,0 +1,248 @@+/**+ * 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 };+};diff --git a/src/adb/AdbProvider.test.ts b/src/adb/AdbProvider.test.tsnew file mode 100644index 000000000..444fe5e83--- /dev/null+++ b/src/adb/AdbProvider.test.ts@@ -0,0 +1,960 @@+import { createHash } from "node:crypto";+import {+ chmod,+ mkdir,+ mkdtemp,+ readFile,+ rm,+ writeFile,+} from "node:fs/promises";+import { join } from "node:path";+import { expect, onTestFinished, test } from "vitest";++import { AdbProvider } from "./AdbProvider.js";+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";+import type { AdbRequest } from "../domain/adb/adbDeviceAnalysis.js";++const it = test.skipIf(process.platform === "win32");++const VERSION_BLOCK =+ "printf 'Android Debug Bridge version 1.0.41\\nVersion 34.0.5-stub\\nInstalled as %s\\n' \"$0\"";++const writeAdbStub = async (+ body: (root: string) => string,+): Promise<{ readonly binary: string; readonly root: string }> => {+ const root = await mkdtemp(join("/tmp", "rea-adb-"));+ onTestFinished(() => rm(root, { recursive: true, force: true }));+ const binary = join(root, "adb");+ await writeFile(binary, `#!/bin/sh\n${body(root)}\n`, { mode: 0o755 });+ await chmod(binary, 0o755);+ return { binary, root };+};++const providerOver = (binary: string): AdbProvider =>+ new AdbProvider({ environment: { REA_ADB_PATH: binary } });++const evidenceResult = async (+ provider: AdbProvider,+ request: AdbRequest,+): Promise<Record<string, unknown>> => {+ const result = await provider.execute(request);+ if (!result.ok) throw new Error(result.error.message);+ return result.value.result as Record<string, unknown>;+};++const refusedBy = async (+ provider: AdbProvider,+ request: AdbRequest,+): Promise<ReturnType<typeof projectAnalysisError>> => {+ const result = await provider.execute(request);+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("expected a refusal");+ return projectAnalysisError(result.error);+};++it("inspects the adb client without contacting the server", async () => {+ const { binary } = await writeAdbStub(+ () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; fi`,+ );+ const result = await evidenceResult(providerOver(binary), {+ operation: "inspect_adb_client",+ input: {},+ });+ expect(result.client).toMatchObject({+ path_source: "environment",+ version: "34.0.5-stub",+ installed_path: binary,+ });+ expect(result.contacted_adb_server).toBe(false);+});++it("lists devices with inferred kinds and observed daemon startup", async () => {+ const { binary } = await writeAdbStub(+ () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "devices" ]; then+ printf '* daemon not running; starting now at tcp:5037\\n* daemon started successfully\\n'+ printf 'List of devices attached\\n'+ printf 'emulator-5554 device product:sdk_gphone64_x86_64 model:sdk_gphone64_x86_64 device:emu64xa transport_id:1\\n'+ exit 0+fi`,+ );+ const result = await evidenceResult(providerOver(binary), {+ operation: "list_adb_devices",+ input: {},+ });+ expect(result.may_have_started_adb_server).toBe(true);+ expect(result.devices).toEqual([+ {+ serial: "emulator-5554",+ state: "device",+ transport: "tcp",+ product: "sdk_gphone64_x86_64",+ model: "sdk_gphone64_x86_64",+ device: "emu64xa",+ transport_id: 1,+ kind: "emulator",+ kind_basis: "emulator_serial_prefix",+ },+ ]);+});++it("inspects a device through the getprop whitelist", async () => {+ const { binary } = await writeAdbStub(+ () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "-s" ] && [ "$3" = "shell" ] && [ "$4" = "getprop" ]; then+ printf '[ro.build.version.sdk]: [34]\\n[ro.kernel.qemu]: [1]\\n[sys.private]: [x]\\n'+ exit 0+fi`,+ );+ const result = await evidenceResult(providerOver(binary), {+ operation: "inspect_adb_device",+ input: { serial: "emulator-5554" },+ });+ expect(result.emulator_observed).toBe(true);+ expect(result.properties).toEqual([+ { name: "ro.build.version.sdk", value: "34" },+ { name: "ro.kernel.qemu", value: "1" },+ ]);+});++it("passes the caller scope as an exact fixed argv vector", async () => {+ const { binary, root } = await writeAdbStub(+ (root) => `printf '%s\\n' "$@" >> ${join(root, "argv.log")}+if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "-s" ] && [ "$3" = "shell" ]; then printf 'package:/data/app/x/base.apk=com.example\\n'; exit 0; fi`,+ );+ const result = await evidenceResult(providerOver(binary), {+ operation: "list_adb_packages",+ input: { serial: "emulator-5554", scope: "third_party" },+ });+ expect(result.coverage).toBe("complete");+ expect(result.packages).toEqual([+ {+ package_name: "com.example",+ base_apk_device_path: "/data/app/x/base.apk",+ },+ ]);+ const logged = (await readFile(join(root, "argv.log"), "utf8"))+ .trim()+ .split("\n");+ expect(logged).toEqual([+ "version",+ "-s",+ "emulator-5554",+ "shell",+ "pm",+ "list",+ "packages",+ "-f",+ "-3",+ ]);+});++const pullStub = (+ paths: string,+ pullBody: string,+): string => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "-s" ] && [ "$4" = "pm" ] && [ "$5" = "path" ]; then+ printf '%s\\n' ${paths}+ exit 0+fi+if [ "$1" = "-s" ] && [ "$3" = "pull" ]; then+${pullBody}+ exit 0+fi+printf 'unexpected arguments: %s\\n' "$@"+exit 1`;++/** Stub dispatching one canned stdout per first shell word (and optional second). */+const shellStub = (+ dispatch: Readonly<Record<string, string>>,+): ((root: string) => string) => {+ const cases = Object.entries(dispatch)+ .map(([key, output]) => {+ const [first, second] = key.split(":");+ const guard =+ second === undefined+ ? `[ "$4" = "${first}" ]`+ : `[ "$4" = "${first}" ] && [ "$5" = "${second}" ]`;+ return ` if ${guard}; then printf '%b' '${output.replace(/'/gu, "'\\''")}'; exit 0; fi`;+ })+ .join("\n");+ return () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "-s" ] && [ "$3" = "shell" ]; then+${cases}+ printf 'unexpected shell command: %s %s %s\\n' "$4" "$5" "$6" >&2+ exit 1+fi+printf 'unexpected arguments: %s\\n' "$@"+exit 1`;+};++it("pulls a complete split set with digests into a new package directory", async () => {+ const { binary, root } = await writeAdbStub(() =>+ pullStub(+ "'package:/data/app/~~a==/com.example.b==/base.apk' 'package:/data/app/~~a==/com.example.b==/split_config.en.apk'",+ ` printf 'apk-bytes-for-testing' > "$5"+ printf '1 file pulled, 0 skipped.\\n'`,+ ),+ );+ const output = join(root, "pulls");+ const result = await evidenceResult(providerOver(binary), {+ operation: "pull_adb_package",+ input: {+ serial: "emulator-5554",+ package: "com.example",+ output_directory: output,+ },+ });+ expect(result.coverage).toBe("complete");+ expect(result.failures).toEqual([]);+ const artifacts = result.artifacts as {+ file_name: string;+ local_path: string;+ sha256: string;+ role: string;+ }[];+ expect(+ artifacts.map((artifact) => [artifact.file_name, artifact.role]),+ ).toEqual([+ ["base.apk", "base"],+ ["split_config.en.apk", "split"],+ ]);+ const digest = createHash("sha256")+ .update("apk-bytes-for-testing")+ .digest("hex");+ for (const artifact of artifacts) expect(artifact.sha256).toBe(digest);+ const pulled = await readFile(+ join(output, "com.example", "base.apk"),+ "utf8",+ );+ expect(pulled).toBe("apk-bytes-for-testing");+});++it("keeps successful artifacts when one split pull fails", async () => {+ const { binary, root } = await writeAdbStub(() =>+ pullStub(+ "'package:/data/app/y/base.apk' 'package:/data/app/y/split_dpi.apk'",+ `case "$4" in+ */split_dpi.apk) printf 'error: closed\\n' >&2; exit 1;;+ *) printf 'apk-bytes-for-testing' > "$5"; printf '1 file pulled.\\n';;+ esac`,+ ),+ );+ const result = await evidenceResult(providerOver(binary), {+ operation: "pull_adb_package",+ input: {+ serial: "emulator-5554",+ package: "com.partial",+ output_directory: join(root, "pulls"),+ },+ });+ expect(result.coverage).toBe("partial");+ expect(result.artifacts).toHaveLength(1);+ expect(result.failures).toEqual([+ {+ device_path: "/data/app/y/split_dpi.apk",+ stage: "pull",+ message: expect.stringContaining("closed") as unknown,+ },+ ]);+});++it("refuses to reuse an existing package output directory", async () => {+ const { binary, root } = await writeAdbStub(() =>+ pullStub("'package:/data/app/z/base.apk'", ` printf 'x' > "$5"`),+ );+ const output = join(root, "existing");+ await mkdir(join(output, "com.example"), { recursive: true });+ const provider = providerOver(binary);+ const result = await provider.execute({+ operation: "pull_adb_package",+ input: {+ serial: "emulator-5554",+ package: "com.example",+ output_directory: output,+ },+ });+ expect(result.ok).toBe(false);+ if (result.ok) return;+ expect(projectAnalysisError(result.error)).toMatchObject({+ code: "unreadable_output",+ });+ expect(result.error.message).toContain("already exists");+});++it("reports an uninstalled package from empty pm path output", async () => {+ const { binary } = await writeAdbStub(+ () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "-s" ] && [ "$4" = "pm" ] && [ "$5" = "path" ]; then exit 0; fi`,+ );+ const projected = await refusedBy(providerOver(binary), {+ operation: "pull_adb_package",+ input: {+ serial: "emulator-5554",+ package: "com.absent",+ output_directory: "/tmp/rea-adb-absent",+ },+ });+ expect(projected).toMatchObject({ code: "unsupported_target" });+ expect(projected.message).toContain("no APK paths");+});++it.each([+ ["not found", "error: device 'emulator-9' not found", "not found"],+ ["offline", "error: device offline", "offline"],+ ["unauthorized", "error: device unauthorized", "unauthorized"],+] as const)(+ "reports the %s device state as a target refusal",+ async (_, stderr, excerpt) => {+ const { binary } = await writeAdbStub(+ () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "-s" ]; then printf '%s\\n' "${stderr.replace(/'/gu, "'\\''")}" >&2; exit 1; fi`,+ );+ const projected = await refusedBy(providerOver(binary), {+ operation: "inspect_adb_device",+ input: { serial: "emulator-5554" },+ });+ expect(projected).toMatchObject({ code: "unsupported_target" });+ expect(projected.message).toContain(excerpt);+ },+);++it("reports a missing selected binary as a capability gap with recovery", async () => {+ const provider = new AdbProvider({+ environment: { REA_ADB_PATH: "/nonexistent/adb" },+ });+ const availability = await provider.inspectAvailability();+ expect(availability).toMatchObject({ status: "unavailable" });+ if (availability.status !== "unavailable") return;+ expect(availability.diagnostics.remediation).toContain("REA_ADB_PATH");+ const result = await provider.execute({+ operation: "list_adb_devices",+ input: {},+ });+ expect(result.ok).toBe(false);+ if (result.ok) return;+ const projected = projectAnalysisError(result.error);+ expect(projected).toMatchObject({ code: "capability_unavailable" });+ expect(projected.details).toMatchObject({+ provider_id: "adb",+ reason: expect.stringContaining("not found") as unknown,+ });+});++it("cancels before spawning anything", async () => {+ const { binary, root } = await writeAdbStub(+ (root) => `: > ${join(root, "spawned")}+if [ "$1" = "version" ]; then ${VERSION_BLOCK}; fi`,+ );+ const controller = new AbortController();+ controller.abort();+ const cancelled = await providerOver(binary).execute(+ { operation: "list_adb_devices", input: {} },+ { signal: controller.signal },+ );+ expect(cancelled.ok).toBe(false);+ if (cancelled.ok) return;+ expect(projectAnalysisError(cancelled.error)).toMatchObject({+ code: "cancelled",+ });+ expect(+ await readFile(join(root, "spawned")).then(+ () => true,+ () => false,+ ),+ ).toBe(false);+});++it("reads a bounded logcat dump with the caller count and buffer", async () => {+ const { binary } = await writeAdbStub(+ shellStub({+ logcat:+ "08-10 13:00:00.000 I/Tag( 123): first\\n08-10 13:00:01.000 I/Tag( 123): second\\n",+ }),+ );+ const result = await evidenceResult(providerOver(binary), {+ operation: "read_adb_logcat",+ input: { serial: "emulator-5554", count: 500, buffer: "main" },+ });+ expect(result.lines).toEqual([+ "08-10 13:00:00.000 I/Tag( 123): first",+ "08-10 13:00:01.000 I/Tag( 123): second",+ ]);+});++it("projects package details from dumpsys package output", async () => {+ const { binary } = await writeAdbStub(+ shellStub({+ "dumpsys:package": `Packages:+ Package [com.example] (abcdef):+ userId=10234+ versionName=1.2.3+ versionCode=45 minSdk=24 targetSdk=34+ firstInstallTime=2026-01-02 03:04:05+ lastUpdateTime=2026-02-03 04:05:06+ installerPackageName=com.android.vending+ pkgFlags=[ HAS_CODE ALLOW_CLEAR_USER_DATA ]+ requested permissions:+ android.permission.INTERNET+ android.permission.CAMERA+`,+ }),+ );+ const result = await evidenceResult(providerOver(binary), {+ operation: "inspect_adb_package",+ input: { serial: "emulator-5554", package: "com.example" },+ });+ expect(result).toMatchObject({+ version_name: "1.2.3",+ version_code: 45,+ first_install_time: "2026-01-02 03:04:05",+ last_update_time: "2026-02-03 04:05:06",+ installer_package_name: "com.android.vending",+ user_id: 10234,+ requested_permissions_count: 2,+ coverage: "complete",+ });+});++it("reports an uninstalled package from dumpsys refusal output", async () => {+ const { binary } = await writeAdbStub(+ shellStub({ "dumpsys:package": "Unable to find package: com.absent\n" }),+ );+ const projected = await refusedBy(providerOver(binary), {+ operation: "inspect_adb_package",+ input: { serial: "emulator-5554", package: "com.absent" },+ });+ expect(projected).toMatchObject({ code: "unsupported_target" });+});++it("pulls one device file with a digest", async () => {+ const { binary, root } = await writeAdbStub(+ () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "-s" ] && [ "$3" = "pull" ]; then printf 'file-bytes' > "$5"; exit 0; fi+exit 1`,+ );+ const output = join(root, "pulls");+ const result = await evidenceResult(providerOver(binary), {+ operation: "pull_adb_file",+ input: {+ serial: "emulator-5554",+ device_path: "/data/local/tmp/notes.txt",+ output_directory: output,+ },+ });+ const digest = createHash("sha256").update("file-bytes").digest("hex");+ expect(result).toMatchObject({+ device_path: "/data/local/tmp/notes.txt",+ local_path: join(output, "notes.txt"),+ bytes: 10,+ sha256: digest,+ });+});++it("pushes a file and verifies the device-side digest", async () => {+ const { binary, root } = await writeAdbStub(+ () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "-s" ] && [ "$4" = "test" ]; then exit 1; fi+if [ "$1" = "-s" ] && [ "$3" = "push" ]; then exit 0; fi+if [ "$1" = "-s" ] && [ "$4" = "sha256sum" ]; then printf '%s %s\\n' "8748b5d17d1ebcec7d46674fa6a8b92c0f95598a552f27c1c8a132eb58c04043" "$5"; exit 0; fi+exit 1`,+ );+ const localFile = join(root, "payload.bin");+ await writeFile(localFile, "push-payload");+ const digest = createHash("sha256").update("push-payload").digest("hex");+ const pushed = await evidenceResult(providerOver(binary), {+ operation: "push_adb_file",+ input: {+ serial: "emulator-5554",+ local_path: localFile,+ device_path: "/data/local/tmp/payload.bin",+ overwrite: false,+ },+ });+ expect(pushed).toMatchObject({+ bytes: 12,+ sha256: digest,+ device_sha256: digest,+ overwritten: false,+ device_digest_source: "device_sha256sum",+ });+});++it("reports a digest mismatch after push as a changed artifact", async () => {+ const { binary, root } = await writeAdbStub(+ () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "-s" ] && [ "$4" = "test" ]; then exit 1; fi+if [ "$1" = "-s" ] && [ "$3" = "push" ]; then exit 0; fi+if [ "$1" = "-s" ] && [ "$4" = "sha256sum" ]; then printf '%s %s\\n' "$(printf 'a%.0s' 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64)" "$5"; exit 0; fi+exit 1`,+ );+ const localFile = join(root, "payload.bin");+ await writeFile(localFile, "push-payload");+ const projected = await refusedBy(providerOver(binary), {+ operation: "push_adb_file",+ input: {+ serial: "emulator-5554",+ local_path: localFile,+ device_path: "/data/local/tmp/payload.bin",+ overwrite: false,+ },+ });+ expect(projected).toMatchObject({ code: "artifact_changed" });+});++it("refuses a push onto an existing device path without overwrite", async () => {+ const { binary, root } = await writeAdbStub(+ () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "-s" ] && [ "$4" = "test" ]; then exit 0; fi+exit 1`,+ );+ const localFile = join(root, "payload.bin");+ await writeFile(localFile, "x");+ const result = await providerOver(binary).execute({+ operation: "push_adb_file",+ input: {+ serial: "emulator-5554",+ local_path: localFile,+ device_path: "/data/local/tmp/exists.bin",+ overwrite: false,+ },+ });+ expect(result.ok).toBe(false);+ if (result.ok) return;+ expect(projectAnalysisError(result.error)).toMatchObject({+ code: "unreadable_output",+ });+ expect(result.error.message).toContain("overwrite");+});++it("reports a local push source that does not exist", async () => {+ const { binary } = await writeAdbStub(+ () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+exit 1`,+ );+ const projected = await refusedBy(providerOver(binary), {+ operation: "push_adb_file",+ input: {+ serial: "emulator-5554",+ local_path: "/nonexistent/payload.bin",+ device_path: "/data/local/tmp/payload.bin",+ overwrite: false,+ },+ });+ expect(projected).toMatchObject({ code: "invalid_request" });+});++it("captures the screen as a digested PNG with its dimensions", async () => {+ const { binary, root } = await writeAdbStub(+ () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "-s" ] && [ "$3" = "exec-out" ]; then+ printf '\\211PNG\\r\\n\\032\\n\\0\\0\\0\\rIHDR\\0\\0\\0\\004\\0\\0\\0\\003'+ exit 0+fi+exit 1`,+ );+ const output = join(root, "captures");+ const result = await evidenceResult(providerOver(binary), {+ operation: "capture_adb_screen",+ input: { serial: "emulator-5554", output_directory: output },+ });+ expect(result).toMatchObject({ width: 4, height: 3 });+ expect(+ await readFile(join(output, "screen.png")).then(+ (bytes) => bytes.subarray(1, 4).toString("latin1") === "PNG",+ () => false,+ ),+ ).toBe(true);+});++it("lists processes, features, and services through fixed commands", async () => {+ const { binary } = await writeAdbStub(+ shellStub({+ ps: "USER PID PPID VSZ RSS WCHAN ADDR S NAME\nu0_a1 1234 567 123456 7890 0 0 S com.example.app\n",+ "pm:list":+ "feature:android.hardware.camera\nfeature:android.hardware.nfc=1\n",+ "service:list":+ "Found 2 services:\n 1 package: [android.content.pm.IPackageManager]\n 2 activity: [android.app.IActivityManager]\n",+ }),+ );+ const processes = await evidenceResult(providerOver(binary), {+ operation: "list_adb_processes",+ input: { serial: "emulator-5554" },+ });+ expect(processes.processes).toEqual([+ {+ user: "u0_a1",+ pid: 1234,+ ppid: 567,+ rss: 7890,+ state: "S",+ name: "com.example.app",+ },+ ]);+ const features = await evidenceResult(providerOver(binary), {+ operation: "list_adb_features",+ input: { serial: "emulator-5554" },+ });+ expect(features.features).toEqual([+ { name: "android.hardware.camera", version: null },+ { name: "android.hardware.nfc", version: 1 },+ ]);+ const services = await evidenceResult(providerOver(binary), {+ operation: "list_adb_services",+ input: { serial: "emulator-5554" },+ });+ expect(services.services).toEqual([+ { name: "package", interface: "android.content.pm.IPackageManager" },+ { name: "activity", interface: "android.app.IActivityManager" },+ ]);+});++it("lists a device directory with kinds and symlink targets", async () => {+ const { binary } = await writeAdbStub(+ shellStub({+ ls: "total 4\n-rw-rw---- u0_a1 u0_a1 4096 2026-01-02 11:00 app.db\nlrwxrwxrwx root root 2026-01-01 10:00 lib -> /apex/com.android.art/lib\n",+ }),+ );+ const result = await evidenceResult(providerOver(binary), {+ operation: "list_adb_directory",+ input: {+ serial: "emulator-5554",+ device_path: "/data/data/com.example.app",+ },+ });+ expect(result.entries).toEqual([+ {+ name: "app.db",+ kind: "file",+ permissions: "-rw-rw----",+ owner: "u0_a1",+ group: "u0_a1",+ bytes: 4096,+ date: "2026-01-02 11:00",+ link_target: null,+ },+ {+ name: "lib",+ kind: "symlink",+ permissions: "lrwxrwxrwx",+ owner: "root",+ group: "root",+ bytes: null,+ date: "2026-01-01 10:00",+ link_target: "/apex/com.android.art/lib",+ },+ ]);+});++it("inspects the display and window focus", async () => {+ const { binary } = await writeAdbStub(+ shellStub({+ "wm:size": "Physical size: 1080x2340\n",+ "wm:density": "Physical density: 420\n",+ "dumpsys:window":+ " mCurrentFocus=Window{abcdef u0 com.example.app/com.example.app.MainActivity}\n",+ }),+ );+ const display = await evidenceResult(providerOver(binary), {+ operation: "inspect_adb_display",+ input: { serial: "emulator-5554" },+ });+ expect(display.physical_size).toEqual({ width: 1080, height: 2340 });+ expect(display.physical_density).toBe(420);+ const window = await evidenceResult(providerOver(binary), {+ operation: "inspect_adb_window",+ input: { serial: "emulator-5554" },+ });+ expect(window.focused_window).toBe(+ "Window{abcdef u0 com.example.app/com.example.app.MainActivity}",+ );+});++it("reads one settings value and reports device-side nulls", async () => {+ const { binary } = await writeAdbStub(shellStub({ "settings:get": "1\n" }));+ const enabled = await evidenceResult(providerOver(binary), {+ operation: "read_adb_setting",+ input: {+ serial: "emulator-5554",+ namespace: "secure",+ key: "adb_enabled",+ },+ });+ expect(enabled.value).toBe("1");+ const { binary: nullBinary } = await writeAdbStub(+ shellStub({ "settings:get": "null\n" }),+ );+ const absent = await evidenceResult(providerOver(nullBinary), {+ operation: "read_adb_setting",+ input: {+ serial: "emulator-5554",+ namespace: "global",+ key: "absent_key",+ },+ });+ expect(absent.value).toBeNull();+ expect(absent.device_reported_null).toBe(true);+});++it("resolves packages by case-insensitive substring", async () => {+ const { binary } = await writeAdbStub(+ shellStub({+ "pm:list":+ "package:/data/app/x/base.apk=com.whatsapp\\npackage:/data/app/y/base.apk=com.whatsapp.w4b\\npackage:/data/app/z/base.apk=com.example\\n",+ }),+ );+ const result = await evidenceResult(providerOver(binary), {+ operation: "resolve_adb_packages",+ input: { serial: "emulator-5554", query: "WhatsApp" },+ });+ expect(result.matches).toEqual([+ {+ package_name: "com.whatsapp",+ base_apk_device_path: "/data/app/x/base.apk",+ },+ {+ package_name: "com.whatsapp.w4b",+ base_apk_device_path: "/data/app/y/base.apk",+ },+ ]);+ expect(result.exact_match).toBe(false);+ expect(result.coverage).toBe("complete");+});++it("installs a local APK and preserves the device's failure verdict", async () => {+ const { binary, root } = await writeAdbStub(+ () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "-s" ] && [ "$3" = "install" ]; then printf 'Success\\n'; exit 0; fi+exit 1`,+ );+ const apk = join(root, "app.apk");+ await writeFile(apk, "apk");+ const digest = createHash("sha256").update("apk").digest("hex");+ const installed = await evidenceResult(providerOver(binary), {+ operation: "install_adb_package",+ input: { serial: "emulator-5554", apk_path: apk, replace: false },+ });+ expect(installed).toMatchObject({+ bytes: 3,+ sha256: digest,+ replaced: false,+ });++ const { binary: failing } = await writeAdbStub(+ () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "-s" ] && [ "$3" = "install" ]; then printf 'Failure [INSTALL_FAILED_ALREADY_EXISTS]\\n'; exit 0; fi+exit 1`,+ );+ const projected = await refusedBy(providerOver(failing), {+ operation: "install_adb_package",+ input: {+ serial: "emulator-5554",+ apk_path: apk,+ replace: false,+ },+ });+ expect(projected).toMatchObject({ code: "unsupported_target" });+ expect(projected.message).toContain("INSTALL_FAILED_ALREADY_EXISTS");+});++it("uninstalls a package and reports the device's refusal for absent ones", async () => {+ const { binary } = await writeAdbStub(+ () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "-s" ] && [ "$3" = "uninstall" ]; then printf 'Success\\n'; exit 0; fi+exit 1`,+ );+ const removed = await evidenceResult(providerOver(binary), {+ operation: "uninstall_adb_package",+ input: { serial: "emulator-5554", package: "com.example" },+ });+ expect(removed.package_name).toBe("com.example");++ const { binary: refusing } = await writeAdbStub(+ () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "-s" ] && [ "$3" = "uninstall" ]; then printf 'Failure [not installed for 0]\\n'; exit 0; fi+exit 1`,+ );+ const projected = await refusedBy(providerOver(refusing), {+ operation: "uninstall_adb_package",+ input: { serial: "emulator-5554", package: "com.absent" },+ });+ expect(projected).toMatchObject({ code: "unsupported_target" });+ expect(projected.message).toContain("not installed for 0");+});++it("starts an app through resolved launcher component and force-stops it", async () => {+ const { binary } = await writeAdbStub(+ shellStub({+ "cmd:package":+ "priority=0 preferredOrder=0 match=0x00108000 specificIndex=-1 isDefault=true\ncom.example/.Main",+ "am:start":+ "Starting: Intent { act=android.intent.action.MAIN cat=[android.intent.category.LAUNCHER] cmp=com.example/.Main }\n",+ "am:force-stop": "",+ }),+ );+ const provider = providerOver(binary);+ const started = await evidenceResult(provider, {+ operation: "start_adb_app",+ input: { serial: "emulator-5554", package: "com.example" },+ });+ expect(started).toMatchObject({+ package_name: "com.example",+ component: "com.example/.Main",+ started_activity: expect.stringContaining(+ "cmp=com.example/.Main",+ ) as unknown,+ });+ const stopped = await evidenceResult(provider, {+ operation: "stop_adb_app",+ input: { serial: "emulator-5554", package: "com.example" },+ });+ expect(stopped.package_name).toBe("com.example");+});++it("reports an app without a launcher activity as unsupported", async () => {+ const { binary } = await writeAdbStub(+ shellStub({ "cmd:package": "No activity found\n" }),+ );+ const projected = await refusedBy(providerOver(binary), {+ operation: "start_adb_app",+ input: { serial: "emulator-5554", package: "com.library.only" },+ });+ expect(projected).toMatchObject({ code: "unsupported_target" });+ expect(projected.message).toContain("No launcher activity");+});++it("starts an intent with typed extras as a fixed argv vector", async () => {+ const { binary, root } = await writeAdbStub(+ (root) => `printf '%s\\n' "$@" >> ${join(root, "argv.log")}+${shellStub({ "am:start": "Starting: Intent { act=android.intent.action.VIEW dat=https://example.com/ }\n" })(root)}`,+ );+ const started = await evidenceResult(providerOver(binary), {+ operation: "start_adb_activity",+ input: {+ serial: "emulator-5554",+ action: "android.intent.action.VIEW",+ data_uri: "https://example.com/",+ extras: [+ { key: "level", type: "int", value: "3" },+ { key: "label", type: "string", value: "probe" },+ ],+ },+ });+ expect(started.action).toBe("android.intent.action.VIEW");+ const logged = (await readFile(join(root, "argv.log"), "utf8"))+ .trim()+ .split("\n");+ expect(logged).toEqual([+ "version",+ "-s",+ "emulator-5554",+ "shell",+ "am",+ "start",+ "-W",+ "-a",+ "android.intent.action.VIEW",+ "-d",+ "https://example.com/",+ "--ei",+ "level",+ "3",+ "--es",+ "label",+ "probe",+ ]);+});++it("rejects mistyped intent extras before touching the device", async () => {+ const { binary } = await writeAdbStub(+ () => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+: > should-not-exist`,+ );+ const projected = await refusedBy(providerOver(binary), {+ operation: "start_adb_activity",+ input: {+ serial: "emulator-5554",+ action: "com.example.ACTION",+ extras: [{ key: "flag", type: "boolean", value: "yes" }],+ },+ });+ expect(projected).toMatchObject({ code: "invalid_request" });+});++it("collects a device bugreport archive with its digest", async () => {+ const { binary, root } = await writeAdbStub(+ (root) => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+if [ "$1" = "-s" ] && [ "$3" = "bugreport" ]; then+ printf 'bugreport-bytes' > "${join(root, "bugreport test.zip")}"+ printf 'Bug report copied to ${join(root, "bugreport test.zip")}\\n'+ exit 0+fi+exit 1`,+ );+ const result = await evidenceResult(providerOver(binary), {+ operation: "collect_adb_bugreport",+ input: { serial: "emulator-5554", output_directory: root },+ });+ const digest = createHash("sha256").update("bugreport-bytes").digest("hex");+ expect(result).toMatchObject({+ local_path: join(root, "bugreport test.zip"),+ bytes: 15,+ sha256: digest,+ adb_reported_path: join(root, "bugreport test.zip"),+ });+});++it("quotes caller text before adb joins the remote shell command", async () => {+ const { binary, root } = await writeAdbStub(+ (root) => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+shift 3+# Model adb's remote command joining, then execute the resulting shell string.+printf '#!/bin/sh\nprintf "%%s" "$@" > "${join(root, "observed")}"\n' > "${join(root, "ls")}"+chmod +x "${join(root, "ls")}"+PATH="${root}:$PATH" sh -c "$*"+`,+ );+ const value = `/sdcard/a 'quoted'; touch ${join(root, "injected")}`;+ await providerOver(binary).execute({+ operation: "list_adb_directory",+ input: { serial: "device", device_path: value },+ });+ expect(await readFile(join(root, "observed"), "utf8")).toContain(value);+ await expect(readFile(join(root, "injected"))).rejects.toThrow();+});++it("preserves a screen output created while capture is running", async () => {+ const { binary, root } = await writeAdbStub(+ (root) => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi+printf 'existing evidence' > "${join(root, "captures", "screen.png")}"+printf '\\211PNG\\r\\n\\032\\n\\0\\0\\0\\rIHDR\\0\\0\\0\\004\\0\\0\\0\\003'+`,+ );+ const result = await providerOver(binary).execute({+ operation: "capture_adb_screen",+ input: { serial: "device", output_directory: join(root, "captures") },+ });+ expect(result.ok).toBe(false);+ expect(await readFile(join(root, "captures", "screen.png"), "utf8")).toBe(+ "existing evidence",+ );+});++it("reports cancellation arriving during the version probe", async () => {+ const { binary } = await writeAdbStub(() => "exec sleep 30");+ const controller = new AbortController();+ const pending = providerOver(binary).execute(+ { operation: "inspect_adb_client", input: {} },+ { signal: controller.signal },+ );+ const timer = setTimeout(() => controller.abort(), 50);+ try {+ const result = await pending;+ expect(result.ok).toBe(false);+ if (!result.ok)+ expect(projectAnalysisError(result.error).code).toBe("cancelled");+ } finally {+ clearTimeout(timer);+ }+});diff --git a/src/adb/AdbProvider.ts b/src/adb/AdbProvider.tsnew file mode 100644index 000000000..f2bafdb51--- /dev/null+++ b/src/adb/AdbProvider.ts@@ -0,0 +1,1776 @@+import { execFile } from "node:child_process";+import { createHash } from "node:crypto";+import { createReadStream, constants as fsConstants } from "node:fs";+import { access, lstat, mkdir, rm, stat, writeFile } from "node:fs/promises";+import { basename, join, resolve } from "node:path";++import type {+ ExecutionOptions,+ ProviderAvailability,+} from "../application/AnalysisProvider.js";+import {+ createAnalysisExecution,+ type AnalysisExecution,+} from "../application/AnalysisProvider.js";+import type { AdbRequest } from "../domain/adb/adbDeviceAnalysis.js";+import {+ AnalysisArtifactChangedError,+ AnalysisCapabilityUnavailableError,+ AnalysisCancelledError,+ AnalysisInputError,+ AnalysisOutputError,+ AnalysisProtocolError,+ AnalysisResourceConstraintError,+ AnalysisTimeoutError,+ AnalysisUnsupportedTargetError,+} from "../domain/analysisErrorCore.js";+import type { AnalysisError } from "../domain/analysisErrorBase.js";+import { err, ok, type Result } from "../domain/result.js";+import {+ execFileOutput,+ execFileOutputFailure,+} from "../process/ExecFileOutput.js";+import {+ AdbConfigurationFailure,+ inspectAdbClient,+ resolveAdbBinary,+ type AdbBinarySelection,+ type AdbClientIdentity,+} from "./AdbConfiguration.js";+import {+ parseAdbDevicesOutput,+ parseGetpropOutput,+ parsePackageListOutput,+ parsePmPathOutput,+} from "./AdbDeviceOutput.js";+import {+ parseAmStartOutput,+ parseBugreportCopiedPath,+ parseDumpsysPackageOutput,+ parseFeatureListOutput,+ parseLsOutput,+ parsePackageChangeOutput,+ parseProcessListOutput,+ parsePngDimensions,+ parseResolveActivityOutput,+ parseServiceListOutput,+ parseSettingsGetOutput,+ parseWindowFocusOutput,+ parseWmDensityOutput,+ parseWmSizeOutput,+} from "./AdbShellOutput.js";++/** Stable identity for the ADB device-acquisition provider. */+export const ADB_PROVIDER_IDENTITY = {+ id: "adb",+ name: "Android Debug Bridge",+ version: null,+} as const;++const VERSION_TIMEOUT_MS = 10_000;+const VERSION_MAX_OUTPUT_BYTES = 64 * 1024;+const DEVICES_TIMEOUT_MS = 20_000;+const DEVICES_MAX_OUTPUT_BYTES = 1024 * 1024;+const SHELL_TIMEOUT_MS = 30_000;+const GETPROP_MAX_OUTPUT_BYTES = 2 * 1024 * 1024;+const PACKAGE_LIST_TIMEOUT_MS = 60_000;+const PACKAGE_LIST_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;+const PM_PATH_TIMEOUT_MS = 30_000;+const PM_PATH_MAX_OUTPUT_BYTES = 64 * 1024;+const PULL_TIMEOUT_MS = 600_000;+const PULL_MAX_OUTPUT_BYTES = 1024 * 1024;+const LOGCAT_TIMEOUT_MS = 60_000;+const LOGCAT_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;+const DUMPSYS_PACKAGE_TIMEOUT_MS = 60_000;+const DUMPSYS_PACKAGE_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;+const DUMPSYS_WINDOW_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;+const LISTING_TIMEOUT_MS = 30_000;+const LISTING_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;+const SETTINGS_TIMEOUT_MS = 20_000;+const SETTINGS_MAX_OUTPUT_BYTES = 1024 * 1024;+const SCREEN_TIMEOUT_MS = 60_000;+const SCREEN_MAX_OUTPUT_BYTES = 32 * 1024 * 1024;+const BUGREPORT_TIMEOUT_MS = 600_000;+const BUGREPORT_MAX_OUTPUT_BYTES = 1024 * 1024;+const STDERR_EXCERPT_BYTES = 512;+const UNPARSED_LINES_REPORTED = 10;+const STOP_GRACE_MS = 5_000;++/** Stream a local file digest without retaining large files in memory. */+const sha256File = async (path: string): Promise<string> => {+ const hash = createHash("sha256");+ for await (const chunk of createReadStream(path)) hash.update(chunk);+ return hash.digest("hex");+};++/** adb joins shell operands into a remote POSIX command; quote at that boundary. */+const quoteShellOperand = (value: string): string =>+ /^[A-Za-z0-9_./:=@+,\-]+$/u.test(value)+ ? value+ : "'" + value.replaceAll("'", "'\\''") + "'";++const adbArguments = (+ serial: string | undefined,+ arguments_: readonly string[],+): readonly string[] => {+ const operands =+ arguments_[0] === "shell"+ ? ["shell", ...arguments_.slice(1).map(quoteShellOperand)]+ : [...arguments_];+ return serial === undefined ? operands : ["-s", serial, ...operands];+};++interface AdbRunLimits {+ readonly timeoutMs: number;+ readonly maxOutputBytes: number;+}++/** Run one bounded adb invocation and keep its exact failure shape. */+const runAdb = async (+ operation: string,+ targetPath: string,+ binary: string,+ arguments_: readonly string[],+ limits: AdbRunLimits,+ signal: AbortSignal | undefined,+): Promise<Result<{ stdout: string; stderr: string }, AnalysisError>> => {+ if (signal?.aborted === true)+ return err(new AnalysisCancelledError(operation));+ try {+ return ok(+ await execFileOutput(binary, arguments_, {+ timeout: limits.timeoutMs,+ maxBuffer: limits.maxOutputBytes,+ stopSignal: "SIGTERM",+ ...(signal === undefined ? {} : { signal }),+ }),+ );+ } catch (cause) {+ if (signal?.aborted || execFileOutputFailure(cause)?.code === "ABORT_ERR")+ return err(new AnalysisCancelledError(operation, { cause }));+ const failure = execFileOutputFailure(cause);+ if (failure === undefined)+ return err(+ new AnalysisProtocolError(`adb failed for ${operation}`, { cause }),+ );+ if (failure.outputTruncated)+ return err(+ new AnalysisResourceConstraintError(+ operation,+ "memory",+ `adb output exceeded the ${String(limits.maxOutputBytes)}-byte capture budget`,+ { max_output_bytes: limits.maxOutputBytes },+ { cause },+ ),+ );+ const excerpt = failure.stderr.trim().slice(0, STDERR_EXCERPT_BYTES);+ if (/unauthorized/iu.test(excerpt))+ return err(+ new AnalysisUnsupportedTargetError(operation, targetPath, excerpt, {+ cause,+ }),+ );+ if (+ /device[^\n]*not found|device offline|still authorizing|more than one device/iu.test(+ excerpt,+ )+ )+ return err(+ new AnalysisUnsupportedTargetError(operation, targetPath, excerpt, {+ cause,+ }),+ );+ if (+ /No such file or directory|Permission denied|read: Permission denied/iu.test(+ excerpt,+ )+ )+ return err(+ new AnalysisUnsupportedTargetError(operation, targetPath, excerpt, {+ cause,+ }),+ );+ if (failure.killed)+ return err(+ new AnalysisTimeoutError(operation, limits.timeoutMs, { cause }),+ );+ return err(+ new AnalysisProtocolError(+ excerpt === ""+ ? `adb exited with code ${String(failure.code)} for ${operation}`+ : excerpt,+ { cause },+ ),+ );+ }+};++/** Capture one adb invocation's raw binary stdout (screencap PNG). */+const runAdbBinary = (+ operation: string,+ binary: string,+ arguments_: readonly string[],+ limits: AdbRunLimits,+ signal: AbortSignal | undefined,+): Promise<Result<Buffer, AnalysisError>> =>+ new Promise((settle) => {+ if (signal?.aborted === true)+ return settle(err(new AnalysisCancelledError(operation)));+ let stopped: "abort" | "timeout" | undefined;+ let deadline: NodeJS.Timeout | undefined;+ let grace: NodeJS.Timeout | undefined;+ const child = execFile(+ binary,+ [...arguments_],+ {+ encoding: "buffer" as const,+ maxBuffer: limits.maxOutputBytes,+ killSignal: "SIGTERM",+ timeout: 0,+ },+ (error, stdout) => {+ signal?.removeEventListener("abort", onAbort);+ clearTimeout(deadline);+ clearTimeout(grace);+ if (stopped === "abort")+ return settle(err(new AnalysisCancelledError(operation)));+ if (stopped === "timeout")+ return settle(+ err(new AnalysisTimeoutError(operation, limits.timeoutMs)),+ );+ if (error !== null)+ return settle(+ err(+ new AnalysisProtocolError(+ `adb failed for ${operation}: ${error.message}`,+ { cause: error },+ ),+ ),+ );+ settle(ok(stdout as Buffer));+ },+ );+ const stop = (reason: "abort" | "timeout"): void => {+ if (stopped !== undefined) return;+ stopped = reason;+ child.kill("SIGTERM");+ grace = setTimeout(() => child.kill("SIGKILL"), STOP_GRACE_MS);+ };+ const onAbort = (): void => stop("abort");+ signal?.addEventListener("abort", onAbort, { once: true });+ deadline = setTimeout(() => stop("timeout"), limits.timeoutMs);+ });++const clientIdentityResult = (+ selection: AdbBinarySelection,+ identity: AdbClientIdentity,+) => ({+ binary_path: selection.binary,+ path_source: selection.pathSource,+ version: identity.version,+ installed_path: identity.installedPath,+});++type ClientIdentity = ReturnType<typeof clientIdentityResult>;+type ProviderIdentity = { id: string; name: string; version: string | null };++const reported = (+ unparsedLines: readonly string[],+ coverage: "complete" | "partial",+) => ({+ unparsed_lines: unparsedLines.slice(0, UNPARSED_LINES_REPORTED),+ coverage:+ coverage === "partial" || unparsedLines.length > 0 ? "partial" : "complete",+});++const unparsedOverflowLimitation = (+ unparsedLines: readonly string[],+): string[] =>+ unparsedLines.length > UNPARSED_LINES_REPORTED+ ? [+ `unparsed_lines reports the first ${String(UNPARSED_LINES_REPORTED)} of ${String(unparsedLines.length)} unrecognized lines`,+ ]+ : [];++/** Materialize the caller's output directory, refusing existing files inside. */+const prepareOutputDirectory = async (+ operation: string,+ directory: string,+): Promise<Result<string, AnalysisError>> => {+ const root = resolve(directory);+ try {+ await mkdir(root, { recursive: true });+ await access(root, fsConstants.W_OK);+ } catch (cause) {+ return err(+ new AnalysisOutputError(+ operation,+ `The output directory is not writable or could not be created: ${root}`,+ { cause },+ ),+ );+ }+ return ok(root);+};++const refuseExistingTarget = async (+ operation: string,+ path: string,+): Promise<AnalysisError | undefined> => {+ if (+ await lstat(path).then(+ () => true,+ () => false,+ )+ )+ return new AnalysisOutputError(+ operation,+ `The output file already exists: ${path}`,+ );+ return undefined;+};++export interface AdbProviderOptions {+ readonly environment?: Readonly<Record<string, string | undefined>>;+}++/**+ * ADB device inspection and acquisition over a caller-selected adb binary.+ *+ * Every operation composes fixed adb argument vectors: caller values occupy+ * positional arguments, escaped when adb forwards them to the device shell. The provider never+ * starts an emulator, installs platform tools, or drives the device UI; the+ * only device mutation is the caller-requested file push, which requires an+ * explicit overwrite choice and verifies its transfer digest.+ */+export class AdbProvider {+ private readonly environment: Readonly<Record<string, string | undefined>>;++ constructor(options: AdbProviderOptions = {}) {+ this.environment = options.environment ?? process.env;+ }++ private selection(): AdbBinarySelection {+ return resolveAdbBinary(this.environment);+ }++ /** Probe the selected adb binary; never contacts devices or the server. */+ async inspectAvailability(+ signal?: AbortSignal,+ ): Promise<ProviderAvailability> {+ const selection = this.selection();+ try {+ await inspectAdbClient(selection, signal);+ return {+ status: "available",+ code: null,+ reason: null,+ diagnostics: {+ selected_binary: selection.binary,+ path_source: selection.pathSource,+ },+ };+ } catch (cause) {+ if (cause instanceof AdbConfigurationFailure)+ return {+ status: "unavailable",+ code:+ cause.code === "binary_missing"+ ? "executable_missing"+ : cause.code === "not_absolute"+ ? "not_configured"+ : "version_unresolved",+ reason: cause.message,+ diagnostics: { ...cause.diagnostics },+ };+ throw cause;+ }+ }++ /** The provider holds no long-lived resources; the adb server is caller-owned. */+ async close(): Promise<void> {}++ async execute(+ request: AdbRequest,+ options?: ExecutionOptions,+ ): Promise<Result<AnalysisExecution, AnalysisError>> {+ const signal = options?.signal;+ if (signal?.aborted === true)+ return err(new AnalysisCancelledError(request.operation));+ const selection = this.selection();+ let identity: AdbClientIdentity;+ try {+ identity = await inspectAdbClient(selection, signal);+ } catch (cause) {+ if (cause instanceof AnalysisCancelledError) return err(cause);+ if (cause instanceof AdbConfigurationFailure)+ return err(+ new AnalysisCapabilityUnavailableError(+ ADB_PROVIDER_IDENTITY.id,+ request.operation,+ typeof cause.diagnostics.remediation === "string"+ ? `${cause.message} ${cause.diagnostics.remediation}`+ : cause.message,+ { cause },+ ),+ );+ return err(+ new AnalysisProtocolError(+ `adb version probe failed for ${request.operation}`,+ { cause },+ ),+ );+ }+ const client = clientIdentityResult(selection, identity);+ const provider: ProviderIdentity = {+ ...ADB_PROVIDER_IDENTITY,+ version: identity.version,+ };+ const { operation } = request;+ const shell = (arguments_: readonly string[], limits: AdbRunLimits) =>+ runAdb(+ operation,+ "serial" in request.input ? request.input.serial : operation,+ selection.binary,+ adbArguments(+ "serial" in request.input ? request.input.serial : undefined,+ ["shell", ...arguments_],+ ),+ limits,+ signal,+ );+ switch (operation) {+ case "inspect_adb_client":+ return ok(+ createAnalysisExecution(+ { client, contacted_adb_server: false },+ provider,+ ),+ );+ case "list_adb_devices": {+ const ran = await runAdb(+ operation,+ "adb-devices",+ selection.binary,+ ["devices", "-l"],+ {+ timeoutMs: DEVICES_TIMEOUT_MS,+ maxOutputBytes: DEVICES_MAX_OUTPUT_BYTES,+ },+ signal,+ );+ if (!ran.ok) return ran;+ const { devices, unparsedLines, daemonStarted } = parseAdbDevicesOutput(+ ran.value.stdout,+ );+ if (unparsedLines.length > 0)+ return err(+ new AnalysisProtocolError(+ `adb devices reported an unrecognized line: ${unparsedLines[0]}`,+ ),+ );+ return ok(+ createAnalysisExecution(+ { client, devices, may_have_started_adb_server: daemonStarted },+ provider,+ {+ limitations: [+ "Device kind is inferred from the emulator serial prefix and USB transport metadata, not from device attestation",+ "Kind stays unknown for TCP transports unless the serial is an emulator port",+ ],+ },+ ),+ );+ }+ case "inspect_adb_device": {+ const ran = await runAdb(+ operation,+ request.input.serial,+ selection.binary,+ adbArguments(request.input.serial, ["shell", "getprop"]),+ {+ timeoutMs: SHELL_TIMEOUT_MS,+ maxOutputBytes: GETPROP_MAX_OUTPUT_BYTES,+ },+ signal,+ );+ if (!ran.ok) return ran;+ const { properties, emulatorObserved } = parseGetpropOutput(+ ran.value.stdout,+ );+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: request.input.serial,+ properties,+ property_count: properties.length,+ emulator_observed: emulatorObserved,+ },+ provider,+ {+ limitations: [+ "Properties are a fixed whitelist of build identity facts, not the full getprop dump",+ "emulator_observed is null when the build does not report ro.kernel.qemu",+ ],+ },+ ),+ );+ }+ case "list_adb_packages": {+ const scopeFlag =+ request.input.scope === "third_party"+ ? "-3"+ : request.input.scope === "system"+ ? "-s"+ : null;+ const ran = await shell(+ [+ "pm",+ "list",+ "packages",+ "-f",+ ...(scopeFlag === null ? [] : [scopeFlag]),+ ],+ {+ timeoutMs: PACKAGE_LIST_TIMEOUT_MS,+ maxOutputBytes: PACKAGE_LIST_MAX_OUTPUT_BYTES,+ },+ );+ if (!ran.ok) return ran;+ const { packages, unparsedLines } = parsePackageListOutput(+ ran.value.stdout,+ );+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: request.input.serial,+ scope: request.input.scope,+ packages,+ ...reported(unparsedLines, "complete"),+ },+ provider,+ {+ limitations: [+ "base_apk_device_path is a device filesystem path, not a host-local path",+ ...unparsedOverflowLimitation(unparsedLines),+ ],+ },+ ),+ );+ }+ case "pull_adb_package":+ return this.pullPackage(+ operation,+ selection,+ client,+ provider,+ request.input,+ signal,+ );+ case "read_adb_logcat": {+ const ran = await shell(+ [+ "logcat",+ "-d",+ "-b",+ request.input.buffer,+ "-t",+ String(request.input.count),+ ...(request.input.pid === undefined+ ? []+ : ["--pid", String(request.input.pid)]),+ ],+ {+ timeoutMs: LOGCAT_TIMEOUT_MS,+ maxOutputBytes: LOGCAT_MAX_OUTPUT_BYTES,+ },+ );+ if (!ran.ok) return ran;+ const lines = ran.value.stdout.split(/\r?\n/u);+ if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();+ const bounded = lines.slice(-request.input.count);+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: request.input.serial,+ count: request.input.count,+ buffer: request.input.buffer,+ pid: request.input.pid ?? null,+ lines: bounded,+ total_bytes: ran.value.stdout.length,+ coverage:+ bounded.length !== lines.length ||+ bounded.length === request.input.count+ ? "partial"+ : "complete",+ },+ provider,+ {+ limitations: [+ "Reads a bounded dump (logcat -d); the newest lines are kept when the count cap trims",+ "coverage is partial when the requested count or capture budget truncated the dump",+ ],+ },+ ),+ );+ }+ case "inspect_adb_package": {+ const ran = await shell(["dumpsys", "package", request.input.package], {+ timeoutMs: DUMPSYS_PACKAGE_TIMEOUT_MS,+ maxOutputBytes: DUMPSYS_PACKAGE_MAX_OUTPUT_BYTES,+ });+ if (!ran.ok) return ran;+ const stdout = ran.value.stdout;+ if (/Unable to find package:/u.test(stdout) || stdout.trim() === "")+ return err(+ new AnalysisUnsupportedTargetError(+ operation,+ request.input.serial,+ `Package Manager did not report details for ${request.input.package}; it may not be installed for user 0`,+ ),+ );+ const details = parseDumpsysPackageOutput(stdout);+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: request.input.serial,+ package_name: request.input.package,+ version_name: details.versionName,+ version_code: details.versionCode,+ first_install_time: details.firstInstallTime,+ last_update_time: details.lastUpdateTime,+ installer_package_name: details.installerPackageName,+ user_id: details.userId,+ pkg_flags: details.pkgFlags,+ requested_permissions_count: details.requestedPermissions,+ coverage:+ details.versionCode === null && details.versionName === null+ ? "partial"+ : "complete",+ },+ provider,+ {+ limitations: [+ "Fields are a fixed projection of dumpsys package output; version-dependent sections are ignored rather than guessed",+ "requested_permissions_count counts the listed requested permissions section only",+ ],+ },+ ),+ );+ }+ case "pull_adb_file":+ return this.pullFile(+ operation,+ selection,+ client,+ provider,+ request.input,+ signal,+ );+ case "push_adb_file":+ return this.pushFile(+ operation,+ selection,+ client,+ provider,+ request.input,+ signal,+ );+ case "capture_adb_screen":+ return this.captureScreen(+ operation,+ selection,+ client,+ provider,+ request.input,+ signal,+ );+ case "collect_adb_bugreport":+ return this.collectBugreport(+ operation,+ selection,+ client,+ provider,+ request.input,+ signal,+ );+ case "list_adb_processes": {+ const ran = await shell(["ps", "-A"], {+ timeoutMs: LISTING_TIMEOUT_MS,+ maxOutputBytes: LISTING_MAX_OUTPUT_BYTES,+ });+ if (!ran.ok) return ran;+ const { columns, processes, unparsedLines } = parseProcessListOutput(+ ran.value.stdout,+ );+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: request.input.serial,+ columns,+ processes,+ ...reported(unparsedLines, "complete"),+ },+ provider,+ { limitations: unparsedOverflowLimitation(unparsedLines) },+ ),+ );+ }+ case "list_adb_directory": {+ const ran = await shell(["ls", "-la", request.input.device_path], {+ timeoutMs: LISTING_TIMEOUT_MS,+ maxOutputBytes: LISTING_MAX_OUTPUT_BYTES,+ });+ if (!ran.ok) return ran;+ const { entries, unparsedLines } = parseLsOutput(ran.value.stdout);+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: request.input.serial,+ device_path: request.input.device_path,+ entries,+ ...reported(unparsedLines, "complete"),+ },+ provider,+ {+ limitations: [+ "Entry kinds derive from the permission string's type character",+ ...unparsedOverflowLimitation(unparsedLines),+ ],+ },+ ),+ );+ }+ case "list_adb_features": {+ const ran = await shell(["pm", "list", "features"], {+ timeoutMs: LISTING_TIMEOUT_MS,+ maxOutputBytes: LISTING_MAX_OUTPUT_BYTES,+ });+ if (!ran.ok) return ran;+ const { features, unparsedLines } = parseFeatureListOutput(+ ran.value.stdout,+ );+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: request.input.serial,+ features,+ ...reported(unparsedLines, "complete"),+ },+ provider,+ { limitations: unparsedOverflowLimitation(unparsedLines) },+ ),+ );+ }+ case "list_adb_services": {+ const ran = await shell(["service", "list"], {+ timeoutMs: LISTING_TIMEOUT_MS,+ maxOutputBytes: LISTING_MAX_OUTPUT_BYTES,+ });+ if (!ran.ok) return ran;+ const { services, unparsedLines } = parseServiceListOutput(+ ran.value.stdout,+ );+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: request.input.serial,+ services,+ ...reported(unparsedLines, "complete"),+ },+ provider,+ { limitations: unparsedOverflowLimitation(unparsedLines) },+ ),+ );+ }+ case "inspect_adb_display": {+ const size = await shell(["wm", "size"], {+ timeoutMs: SETTINGS_TIMEOUT_MS,+ maxOutputBytes: SETTINGS_MAX_OUTPUT_BYTES,+ });+ if (!size.ok) return size;+ const density = await shell(["wm", "density"], {+ timeoutMs: SETTINGS_TIMEOUT_MS,+ maxOutputBytes: SETTINGS_MAX_OUTPUT_BYTES,+ });+ if (!density.ok) return density;+ const parsedSize = parseWmSizeOutput(size.value.stdout);+ if (parsedSize.physical === null)+ return err(+ new AnalysisProtocolError(+ "wm size did not report a physical size; the build may use an unsupported format",+ ),+ );+ const parsedDensity = parseWmDensityOutput(density.value.stdout);+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: request.input.serial,+ physical_size: parsedSize.physical,+ override_size: parsedSize.override,+ physical_density: parsedDensity.physical,+ override_density: parsedDensity.override,+ },+ provider,+ {+ limitations: [+ "Override values are present only when a build has overridden the physical values",+ ],+ },+ ),+ );+ }+ case "inspect_adb_window": {+ const ran = await shell(["dumpsys", "window", "windows"], {+ timeoutMs: SHELL_TIMEOUT_MS,+ maxOutputBytes: DUMPSYS_WINDOW_MAX_OUTPUT_BYTES,+ });+ if (!ran.ok) return ran;+ const { focusedWindow, focusedApp } = parseWindowFocusOutput(+ ran.value.stdout,+ );+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: request.input.serial,+ focused_window: focusedWindow,+ focused_app: focusedApp,+ observed_lines: [+ ...(focusedWindow === null ? [] : [focusedWindow]),+ ...(focusedApp === null ? [] : [focusedApp]),+ ],+ },+ provider,+ {+ limitations: [+ "Focus values are the window manager's declarations at read time; no interaction occurred",+ ],+ },+ ),+ );+ }+ case "read_adb_setting": {+ const ran = await shell(+ ["settings", "get", request.input.namespace, request.input.key],+ {+ timeoutMs: SETTINGS_TIMEOUT_MS,+ maxOutputBytes: SETTINGS_MAX_OUTPUT_BYTES,+ },+ );+ if (!ran.ok) return ran;+ const { value, deviceReportedNull } = parseSettingsGetOutput(+ ran.value.stdout,+ );+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: request.input.serial,+ namespace: request.input.namespace,+ key: request.input.key,+ value,+ device_reported_null: deviceReportedNull,+ },+ provider,+ {+ limitations: [+ "Android prints the literal string null for absent keys; that is reported as a device-side null observation",+ ],+ },+ ),+ );+ }+ case "resolve_adb_packages": {+ const ran = await shell(["pm", "list", "packages", "-f"], {+ timeoutMs: PACKAGE_LIST_TIMEOUT_MS,+ maxOutputBytes: PACKAGE_LIST_MAX_OUTPUT_BYTES,+ });+ if (!ran.ok) return ran;+ const { packages, unparsedLines } = parsePackageListOutput(+ ran.value.stdout,+ );+ const needle = request.input.query.toLowerCase();+ const matches = packages.filter((entry) =>+ entry.package_name.toLowerCase().includes(needle),+ );+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: request.input.serial,+ query: request.input.query,+ matches,+ exact_match:+ matches.length === 1 &&+ matches[0]!.package_name.toLowerCase() === needle,+ coverage: unparsedLines.length > 0 ? "partial" : "complete",+ },+ provider,+ {+ limitations: [+ "Matching is a case-insensitive substring over package names; application display labels are not part of pm output",+ ...unparsedOverflowLimitation(unparsedLines),+ ],+ },+ ),+ );+ }+ case "install_adb_package":+ return this.installPackage(+ operation,+ selection,+ client,+ provider,+ request.input,+ signal,+ );+ case "uninstall_adb_package":+ return this.uninstallPackage(+ operation,+ selection,+ client,+ provider,+ request.input,+ signal,+ );+ case "start_adb_app":+ return this.startApp(+ operation,+ selection,+ client,+ provider,+ request.input,+ signal,+ );+ case "start_adb_activity":+ return this.startActivity(+ operation,+ selection,+ client,+ provider,+ request.input,+ signal,+ );+ case "stop_adb_app":+ return this.stopApp(+ operation,+ selection,+ client,+ provider,+ request.input,+ signal,+ );+ }+ }++ private async pullPackage(+ operation: "pull_adb_package",+ selection: AdbBinarySelection,+ client: ClientIdentity,+ provider: ProviderIdentity,+ input: {+ readonly serial: string;+ readonly package: string;+ readonly output_directory: string;+ },+ signal: AbortSignal | undefined,+ ): Promise<Result<AnalysisExecution, AnalysisError>> {+ const { serial, package: packageName } = input;+ const paths = await runAdb(+ operation,+ serial,+ selection.binary,+ adbArguments(serial, ["shell", "pm", "path", packageName]),+ {+ timeoutMs: PM_PATH_TIMEOUT_MS,+ maxOutputBytes: PM_PATH_MAX_OUTPUT_BYTES,+ },+ signal,+ );+ if (!paths.ok) return paths;+ const parsed = parsePmPathOutput(paths.value.stdout);+ if (parsed.paths.length === 0 && parsed.unparsedLines.length === 0)+ return err(+ new AnalysisUnsupportedTargetError(+ operation,+ serial,+ `Package Manager reported no APK paths for ${packageName}; it may not be installed for user 0`,+ ),+ );+ if (parsed.unparsedLines.length > 0)+ return err(+ new AnalysisProtocolError(+ `pm path reported an unrecognized line: ${parsed.unparsedLines[0]}`,+ ),+ );+ const directory = await prepareOutputDirectory(+ operation,+ input.output_directory,+ );+ if (!directory.ok) return directory;+ const packageDirectory = join(directory.value, packageName);+ try {+ if (+ await stat(packageDirectory).then(+ () => true,+ () => false,+ )+ )+ throw new Error(+ `The package output directory already exists: ${packageDirectory}`,+ );+ await mkdir(packageDirectory);+ } catch (cause) {+ return err(+ new AnalysisOutputError(+ operation,+ cause instanceof Error ? cause.message : String(cause),+ { cause },+ ),+ );+ }+ const artifacts: {+ device_path: string;+ file_name: string;+ local_path: string;+ bytes: number;+ sha256: string;+ role: "base" | "split" | "unknown";+ role_basis: "file_name";+ }[] = [];+ const failures: {+ device_path: string | null;+ stage: "resolve_paths" | "pull" | "digest";+ message: string;+ }[] = [];+ const seenFileNames = new Set<string>();+ for (const entry of parsed.paths) {+ if (seenFileNames.has(entry.file_name)) {+ failures.push({+ device_path: entry.device_path,+ stage: "pull",+ message: `Duplicate file name ${entry.file_name} in the APK set; refusing to overwrite`,+ });+ continue;+ }+ seenFileNames.add(entry.file_name);+ const localPath = join(packageDirectory, entry.file_name);+ const pulled = await runAdb(+ operation,+ serial,+ selection.binary,+ adbArguments(serial, ["pull", entry.device_path, localPath]),+ { timeoutMs: PULL_TIMEOUT_MS, maxOutputBytes: PULL_MAX_OUTPUT_BYTES },+ signal,+ );+ if (!pulled.ok) {+ if (pulled.error instanceof AnalysisCancelledError) return pulled;+ failures.push({+ device_path: entry.device_path,+ stage: "pull",+ message: pulled.error.message,+ });+ continue;+ }+ try {+ const info = await stat(localPath);+ const sha256 = await sha256File(localPath);+ artifacts.push({+ device_path: entry.device_path,+ file_name: entry.file_name,+ local_path: localPath,+ bytes: info.size,+ sha256,+ role: entry.role,+ role_basis: "file_name",+ });+ } catch {+ failures.push({+ device_path: entry.device_path,+ stage: "digest",+ message: `The pulled file could not be read back after pulling: ${localPath}`,+ });+ }+ }+ if (artifacts.length === 0 && failures.length > 0) {+ await rm(packageDirectory, { recursive: true, force: true }).catch(+ () => undefined,+ );+ return err(+ new AnalysisProtocolError(+ `Every APK pull failed for ${packageName} on ${serial}: ${failures[0]!.message}`,+ ),+ );+ }+ return ok(+ createAnalysisExecution(+ {+ client,+ serial,+ package_name: packageName,+ output_directory: directory.value,+ artifacts,+ failures,+ coverage: failures.length === 0 ? "complete" : "partial",+ },+ provider,+ {+ limitations: [+ "APK role names derive from the pulled file names (base.apk, split_*.apk)",+ "Pulled artifacts are host-local copies; the device retains the originals",+ ],+ },+ ),+ );+ }++ private async pullFile(+ operation: "pull_adb_file",+ selection: AdbBinarySelection,+ client: ClientIdentity,+ provider: ProviderIdentity,+ input: {+ readonly serial: string;+ readonly device_path: string;+ readonly output_directory: string;+ },+ signal: AbortSignal | undefined,+ ): Promise<Result<AnalysisExecution, AnalysisError>> {+ const directory = await prepareOutputDirectory(+ operation,+ input.output_directory,+ );+ if (!directory.ok) return directory;+ const fileName = basename(input.device_path) || "pulled";+ const localPath = join(directory.value, fileName);+ const existing = await refuseExistingTarget(operation, localPath);+ if (existing !== undefined) return err(existing);+ const pulled = await runAdb(+ operation,+ input.serial,+ selection.binary,+ adbArguments(input.serial, ["pull", input.device_path, localPath]),+ { timeoutMs: PULL_TIMEOUT_MS, maxOutputBytes: PULL_MAX_OUTPUT_BYTES },+ signal,+ );+ if (!pulled.ok) return pulled;+ try {+ const info = await stat(localPath);+ const sha256 = await sha256File(localPath);+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: input.serial,+ device_path: input.device_path,+ local_path: localPath,+ bytes: info.size,+ sha256,+ },+ provider,+ {+ limitations: [+ "The pulled file is a host-local copy; the device retains the original",+ ],+ },+ ),+ );+ } catch (cause) {+ return err(+ new AnalysisOutputError(+ operation,+ `The pulled file could not be read back after pulling: ${localPath}`,+ { cause },+ ),+ );+ }+ }++ private async pushFile(+ operation: "push_adb_file",+ selection: AdbBinarySelection,+ client: ClientIdentity,+ provider: ProviderIdentity,+ input: {+ readonly serial: string;+ readonly local_path: string;+ readonly device_path: string;+ readonly overwrite: boolean;+ },+ signal: AbortSignal | undefined,+ ): Promise<Result<AnalysisExecution, AnalysisError>> {+ const localPath = resolve(input.local_path);+ const info = await stat(localPath).then(+ (value) => value,+ () => null,+ );+ if (info === null || !info.isFile())+ return err(+ new AnalysisInputError(operation, {+ cause: new Error(`The local file does not exist: ${localPath}`),+ }),+ );+ const sha256 = await sha256File(localPath);+ const existsProbe = await runAdb(+ operation,+ input.device_path,+ selection.binary,+ adbArguments(input.serial, ["shell", "test", "-e", input.device_path]),+ { timeoutMs: SETTINGS_TIMEOUT_MS, maxOutputBytes: 1024 },+ signal,+ );+ let deviceExists: boolean;+ if (existsProbe.ok) deviceExists = true;+ else if (existsProbe.error instanceof AnalysisProtocolError)+ deviceExists = false;+ else if (existsProbe.error instanceof AnalysisTimeoutError)+ return existsProbe;+ else if (existsProbe.error instanceof AnalysisCancelledError)+ return existsProbe;+ else if (existsProbe.error instanceof AnalysisResourceConstraintError)+ return existsProbe;+ else deviceExists = true; // authorization/refusal states surface on push instead+ if (deviceExists && !input.overwrite)+ return err(+ new AnalysisOutputError(+ operation,+ `The device path already exists and overwrite was not requested: ${input.device_path}`,+ ),+ );+ const pushed = await runAdb(+ operation,+ input.device_path,+ selection.binary,+ adbArguments(input.serial, ["push", localPath, input.device_path]),+ { timeoutMs: PULL_TIMEOUT_MS, maxOutputBytes: PULL_MAX_OUTPUT_BYTES },+ signal,+ );+ if (!pushed.ok) return pushed;+ const deviceDigest = await runAdb(+ operation,+ input.device_path,+ selection.binary,+ adbArguments(input.serial, ["shell", "sha256sum", input.device_path]),+ { timeoutMs: SHELL_TIMEOUT_MS, maxOutputBytes: 1024 },+ signal,+ );+ if (deviceDigest.ok) {+ const digestMatch = /^([a-f0-9]{64})\s/u.exec(deviceDigest.value.stdout);+ if (digestMatch !== null && digestMatch[1] !== sha256)+ return err(+ new AnalysisArtifactChangedError(+ operation,+ input.device_path,+ `The device-reported digest does not match the pushed local file: ${localPath}`,+ ),+ );+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: input.serial,+ local_path: localPath,+ device_path: input.device_path,+ bytes: info.size,+ sha256,+ device_sha256: digestMatch?.[1] ?? null,+ overwritten: deviceExists,+ device_digest_source: "device_sha256sum",+ },+ provider,+ {+ limitations: [+ "Push writes the caller's file to the device; this is the only device-mutating ADB tool",+ ],+ },+ ),+ );+ }+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: input.serial,+ local_path: localPath,+ device_path: input.device_path,+ bytes: info.size,+ sha256,+ device_sha256: null,+ overwritten: deviceExists,+ device_digest_source: "unavailable",+ },+ provider,+ {+ limitations: [+ "The device did not answer sha256sum, so the transfer is not device-side verified",+ "Push writes the caller's file to the device; this is the only device-mutating ADB tool",+ ],+ },+ ),+ );+ }++ private async installPackage(+ operation: "install_adb_package",+ selection: AdbBinarySelection,+ client: ClientIdentity,+ provider: ProviderIdentity,+ input: {+ readonly serial: string;+ readonly apk_path: string;+ readonly replace: boolean;+ },+ signal: AbortSignal | undefined,+ ): Promise<Result<AnalysisExecution, AnalysisError>> {+ const apkPath = resolve(input.apk_path);+ const info = await stat(apkPath).then(+ (value) => value,+ () => null,+ );+ if (info === null || !info.isFile())+ return err(+ new AnalysisInputError(operation, {+ cause: new Error(`The local APK does not exist: ${apkPath}`),+ }),+ );+ const sha256 = await sha256File(apkPath);+ const installed = await runAdb(+ operation,+ input.serial,+ selection.binary,+ adbArguments(input.serial, [+ "install",+ ...(input.replace ? ["-r"] : []),+ apkPath,+ ]),+ { timeoutMs: PULL_TIMEOUT_MS, maxOutputBytes: PULL_MAX_OUTPUT_BYTES },+ signal,+ );+ if (!installed.ok) return installed;+ const verdict = parsePackageChangeOutput(installed.value.stdout);+ if (verdict.status === "failure")+ return err(+ new AnalysisUnsupportedTargetError(+ operation,+ input.serial,+ verdict.reason ?? "the device refused the installation",+ ),+ );+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: input.serial,+ apk_path: apkPath,+ bytes: info.size,+ sha256,+ replaced: input.replace,+ },+ provider,+ {+ limitations: [+ "Install changes device state; the installed APK's digest is the host file's digest",+ ],+ },+ ),+ );+ }++ private async uninstallPackage(+ operation: "uninstall_adb_package",+ selection: AdbBinarySelection,+ client: ClientIdentity,+ provider: ProviderIdentity,+ input: { readonly serial: string; readonly package: string },+ signal: AbortSignal | undefined,+ ): Promise<Result<AnalysisExecution, AnalysisError>> {+ const uninstalled = await runAdb(+ operation,+ input.serial,+ selection.binary,+ adbArguments(input.serial, ["uninstall", input.package]),+ {+ timeoutMs: PACKAGE_LIST_TIMEOUT_MS,+ maxOutputBytes: PULL_MAX_OUTPUT_BYTES,+ },+ signal,+ );+ if (!uninstalled.ok) return uninstalled;+ const verdict = parsePackageChangeOutput(uninstalled.value.stdout);+ if (verdict.status === "failure")+ return err(+ new AnalysisUnsupportedTargetError(+ operation,+ input.serial,+ verdict.reason ?? "the device refused the removal",+ ),+ );+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: input.serial,+ package_name: input.package,+ },+ provider,+ {+ limitations: [+ "Uninstall removes the package and its data for user 0; keeping data (-k) is not exposed",+ ],+ },+ ),+ );+ }++ private async startApp(+ operation: "start_adb_app",+ selection: AdbBinarySelection,+ client: ClientIdentity,+ provider: ProviderIdentity,+ input: { readonly serial: string; readonly package: string },+ signal: AbortSignal | undefined,+ ): Promise<Result<AnalysisExecution, AnalysisError>> {+ const resolved = await runAdb(+ operation,+ input.serial,+ selection.binary,+ adbArguments(input.serial, [+ "shell",+ "cmd",+ "package",+ "resolve-activity",+ "--brief",+ "-c",+ "android.intent.category.LAUNCHER",+ input.package,+ ]),+ { timeoutMs: SHELL_TIMEOUT_MS, maxOutputBytes: PM_PATH_MAX_OUTPUT_BYTES },+ signal,+ );+ if (!resolved.ok) return resolved;+ const component = parseResolveActivityOutput(resolved.value.stdout);+ if (component === null)+ return err(+ new AnalysisUnsupportedTargetError(+ operation,+ input.serial,+ `No launcher activity is declared for ${input.package}`,+ ),+ );+ return this.runAmStart(+ operation,+ selection,+ client,+ provider,+ input.serial,+ ["-n", component],+ {+ client,+ serial: input.serial,+ package_name: input.package,+ component,+ },+ signal,+ );+ }++ private async startActivity(+ operation: "start_adb_activity",+ selection: AdbBinarySelection,+ client: ClientIdentity,+ provider: ProviderIdentity,+ input: {+ readonly serial: string;+ readonly action: string;+ readonly data_uri?: string | undefined;+ readonly component?: string | undefined;+ readonly extras: readonly {+ readonly key: string;+ readonly type: "string" | "boolean" | "int" | "long" | "float";+ readonly value: string;+ }[];+ },+ signal: AbortSignal | undefined,+ ): Promise<Result<AnalysisExecution, AnalysisError>> {+ const extraFlags: Record<+ "string" | "boolean" | "int" | "long" | "float",+ string+ > = {+ string: "--es",+ boolean: "--ez",+ int: "--ei",+ long: "--el",+ float: "--ef",+ };+ for (const extra of input.extras)+ if (extra.type === "boolean" && !/^(true|false)$/u.test(extra.value))+ return err(+ new AnalysisInputError(operation, {+ cause: new Error(+ `Boolean extra ${extra.key} must be true or false`,+ ),+ }),+ );+ else if (+ (extra.type === "int" || extra.type === "long") &&+ !/^-?\d+$/u.test(extra.value)+ )+ return err(+ new AnalysisInputError(operation, {+ cause: new Error(+ `${extra.type === "int" ? "Integer" : "Long"} extra ${extra.key} must be an integer`,+ ),+ }),+ );+ else if (extra.type === "float" && !/^-?\d+(\.\d+)?$/u.test(extra.value))+ return err(+ new AnalysisInputError(operation, {+ cause: new Error(`Float extra ${extra.key} must be a number`),+ }),+ );+ const arguments_ = [+ "-a",+ input.action,+ ...(input.data_uri === undefined ? [] : ["-d", input.data_uri]),+ ...(input.component === undefined ? [] : ["-n", input.component]),+ ...input.extras.flatMap((extra) => [+ extraFlags[extra.type],+ extra.key,+ extra.value,+ ]),+ ];+ return this.runAmStart(+ operation,+ selection,+ client,+ provider,+ input.serial,+ arguments_,+ {+ client,+ serial: input.serial,+ action: input.action,+ data_uri: input.data_uri ?? null,+ component: input.component ?? null,+ extras: input.extras.map((extra) => ({ ...extra })),+ },+ signal,+ );+ }++ private async runAmStart(+ operation: "start_adb_app" | "start_adb_activity",+ selection: AdbBinarySelection,+ client: ClientIdentity,+ provider: ProviderIdentity,+ serial: string,+ arguments_: readonly string[],+ resultFields: Record<string, unknown>,+ signal: AbortSignal | undefined,+ ): Promise<Result<AnalysisExecution, AnalysisError>> {+ const started = await runAdb(+ operation,+ serial,+ selection.binary,+ adbArguments(serial, ["shell", "am", "start", "-W", ...arguments_]),+ { timeoutMs: SHELL_TIMEOUT_MS, maxOutputBytes: PM_PATH_MAX_OUTPUT_BYTES },+ signal,+ );+ if (!started.ok) return started;+ const verdict = parseAmStartOutput(started.value.stdout);+ if (verdict.status === "refused")+ return err(+ new AnalysisUnsupportedTargetError(+ operation,+ serial,+ verdict.reason ?? "am start refused the intent",+ ),+ );+ return ok(+ createAnalysisExecution(+ {+ ...resultFields,+ started_activity: verdict.startedActivity,+ },+ provider,+ {+ limitations: [+ "Starting an activity changes device state; am start -W waits for launch completion but no lifecycle observation is captured",+ ],+ },+ ) as AnalysisExecution,+ );+ }++ private async stopApp(+ operation: "stop_adb_app",+ selection: AdbBinarySelection,+ client: ClientIdentity,+ provider: ProviderIdentity,+ input: { readonly serial: string; readonly package: string },+ signal: AbortSignal | undefined,+ ): Promise<Result<AnalysisExecution, AnalysisError>> {+ const stopped = await runAdb(+ operation,+ input.serial,+ selection.binary,+ adbArguments(input.serial, ["shell", "am", "force-stop", input.package]),+ { timeoutMs: SHELL_TIMEOUT_MS, maxOutputBytes: PM_PATH_MAX_OUTPUT_BYTES },+ signal,+ );+ if (!stopped.ok) return stopped;+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: input.serial,+ package_name: input.package,+ },+ provider,+ {+ limitations: [+ "Force-stop succeeds even for packages with no running process; it reports completion, not prior state",+ ],+ },+ ),+ );+ }++ private async captureScreen(+ operation: "capture_adb_screen",+ selection: AdbBinarySelection,+ client: ClientIdentity,+ provider: ProviderIdentity,+ input: { readonly serial: string; readonly output_directory: string },+ signal: AbortSignal | undefined,+ ): Promise<Result<AnalysisExecution, AnalysisError>> {+ const directory = await prepareOutputDirectory(+ operation,+ input.output_directory,+ );+ if (!directory.ok) return directory;+ const localPath = join(directory.value, "screen.png");+ const existing = await refuseExistingTarget(operation, localPath);+ if (existing !== undefined) return err(existing);+ const captured = await runAdbBinary(+ operation,+ selection.binary,+ adbArguments(input.serial, ["exec-out", "screencap", "-p"]),+ { timeoutMs: SCREEN_TIMEOUT_MS, maxOutputBytes: SCREEN_MAX_OUTPUT_BYTES },+ signal,+ );+ if (!captured.ok) return captured;+ const dimensions = parsePngDimensions(captured.value);+ if (dimensions.width === null)+ return err(+ new AnalysisProtocolError(+ "screencap did not return a PNG payload; the device may not expose a display",+ ),+ );+ try {+ await writeFile(localPath, captured.value, { flag: "wx" });+ } catch (cause) {+ return err(+ new AnalysisOutputError(+ operation,+ `The screen output could not be created exclusively: ${localPath}`,+ { cause },+ ),+ );+ }+ const sha256 = createHash("sha256").update(captured.value).digest("hex");+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: input.serial,+ local_path: localPath,+ bytes: captured.value.byteLength,+ sha256,+ width: dimensions.width,+ height: dimensions.height,+ },+ provider,+ {+ limitations: [+ "The capture is one frame at read time; no recording or interaction occurred",+ ],+ },+ ),+ );+ }++ private async collectBugreport(+ operation: "collect_adb_bugreport",+ selection: AdbBinarySelection,+ client: ClientIdentity,+ provider: ProviderIdentity,+ input: { readonly serial: string; readonly output_directory: string },+ signal: AbortSignal | undefined,+ ): Promise<Result<AnalysisExecution, AnalysisError>> {+ const directory = await prepareOutputDirectory(+ operation,+ input.output_directory,+ );+ if (!directory.ok) return directory;+ const collected = await runAdb(+ operation,+ input.serial,+ selection.binary,+ adbArguments(input.serial, ["bugreport", directory.value]),+ {+ timeoutMs: BUGREPORT_TIMEOUT_MS,+ maxOutputBytes: BUGREPORT_MAX_OUTPUT_BYTES,+ },+ signal,+ );+ if (!collected.ok) return collected;+ const reportedPath = parseBugreportCopiedPath(collected.value.stdout);+ if (reportedPath === null)+ return err(+ new AnalysisProtocolError(+ "adb bugreport did not report an archive path; the build may use an unsupported format",+ ),+ );+ try {+ const info = await stat(reportedPath);+ const sha256 = await sha256File(reportedPath);+ return ok(+ createAnalysisExecution(+ {+ client,+ serial: input.serial,+ local_path: reportedPath,+ bytes: info.size,+ sha256,+ adb_reported_path: reportedPath,+ },+ provider,+ {+ limitations: [+ "The archive is device-generated: dumpstate, dumpsys, and logcat content is the device's own report",+ ],+ },+ ),+ );+ } catch (cause) {+ return err(+ new AnalysisOutputError(+ operation,+ `The reported bugreport archive could not be read back: ${reportedPath}`,+ { cause },+ ),+ );+ }+ }+}diff --git a/src/adb/AdbShellOutput.ts b/src/adb/AdbShellOutput.tsnew file mode 100644index 000000000..a67cf8e89--- /dev/null+++ b/src/adb/AdbShellOutput.ts@@ -0,0 +1,433 @@+/**+ * Parsers for fixed observation commands REA runs through `adb shell`.+ *+ * Formats follow toybox output on Android 8+ (verified against an Android 14+ * emulator). Unparseable lines are retained rather than dropped so callers+ * can see the format drift instead of silently losing rows.+ */++export interface AdbProcessEntry {+ readonly user: string;+ readonly pid: number;+ readonly ppid: number | null;+ readonly rss: number | null;+ readonly state: string | null;+ readonly name: string;+}++const PROCESS_LINE =+ /^(\S+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(.+)$/u;++/** Parse `ps -A` output; the header line is preserved verbatim as `columns`. */+export const parseProcessListOutput = (+ stdout: string,+): {+ columns: string | null;+ processes: readonly AdbProcessEntry[];+ unparsedLines: readonly string[];+} => {+ const processes: AdbProcessEntry[] = [];+ const unparsedLines: string[] = [];+ let columns: string | null = null;+ for (const rawLine of stdout.split(/\r?\n/u)) {+ const line = rawLine.trimEnd();+ if (line === "") continue;+ if (/^USER\s+PID\s+PPID\b/u.test(line)) {+ columns = line.trim();+ continue;+ }+ const match = PROCESS_LINE.exec(line);+ if (match === null) {+ unparsedLines.push(line);+ continue;+ }+ processes.push({+ user: match[1]!,+ pid: Number(match[2]!),+ ppid: Number.isSafeInteger(Number(match[3]!)) ? Number(match[3]!) : null,+ rss: Number.isSafeInteger(Number(match[5]!)) ? Number(match[5]!) : null,+ state: match[8]!,+ name: match[9]!.trim(),+ });+ }+ return { columns, processes, unparsedLines };+};++export interface AdbDirectoryEntry {+ readonly name: string;+ readonly kind: "directory" | "file" | "symlink" | "other";+ readonly permissions: string | null;+ readonly owner: string | null;+ readonly group: string | null;+ readonly bytes: number | null;+ readonly date: string | null;+ readonly link_target: string | null;+}++const LS_LINE =+ /^([bcdlps-][rwxstST-]{9})\s+(?:(\d+)\s+)?(\S+)\s+(\S+)\s+(?:(\d+)\s+)?([\d-]{10})\s+([\d:]{4,8})\s+(.+)$/u;++/** Parse `ls -la` output, including `total` headers and symlink targets. */+export const parseLsOutput = (+ stdout: string,+): {+ entries: readonly AdbDirectoryEntry[];+ unparsedLines: readonly string[];+} => {+ const entries: AdbDirectoryEntry[] = [];+ const unparsedLines: string[] = [];+ for (const rawLine of stdout.split(/\r?\n/u)) {+ const line = rawLine.trimEnd();+ if (line === "" || line.startsWith("total ")) continue;+ const match = LS_LINE.exec(line);+ if (match === null) {+ if (line.trim() !== "") unparsedLines.push(line);+ continue;+ }+ const permissions = match[1]!;+ let name = match[8]!.trim();+ let linkTarget: string | null = null;+ const linkArrow = name.indexOf(" -> ");+ if (linkArrow !== -1 && permissions.startsWith("l")) {+ linkTarget = name.slice(linkArrow + 4);+ name = name.slice(0, linkArrow);+ }+ entries.push({+ name,+ kind: permissions.startsWith("d")+ ? "directory"+ : permissions.startsWith("l")+ ? "symlink"+ : permissions.startsWith("-")+ ? "file"+ : "other",+ permissions,+ owner: match[3] ?? null,+ group: match[4] ?? null,+ bytes: match[5] === undefined ? null : Number(match[5]),+ date: `${match[6] ?? ""} ${match[7] ?? ""}`.trim() || null,+ link_target: linkTarget,+ });+ }+ return { entries, unparsedLines };+};++export interface AdbFeatureEntry {+ readonly name: string;+ readonly version: number | null;+}++const FEATURE_LINE = /^feature:([^=\s]+)(?:=(0x[0-9a-fA-F]+|\d+))?$/u;++const parseFeatureVersion = (text: string): number =>+ text.startsWith("0x") ? Number.parseInt(text.slice(2), 16) : Number(text);++/** Parse `pm list features` output, including hex GL versions. */+export const parseFeatureListOutput = (+ stdout: string,+): {+ features: readonly AdbFeatureEntry[];+ unparsedLines: readonly string[];+} => {+ const features: AdbFeatureEntry[] = [];+ const unparsedLines: string[] = [];+ for (const rawLine of stdout.split(/\r?\n/u)) {+ const line = rawLine.trim();+ if (line === "") continue;+ const match = FEATURE_LINE.exec(line);+ if (match === null) {+ unparsedLines.push(line);+ continue;+ }+ features.push({+ name: match[1]!,+ version: match[2] === undefined ? null : parseFeatureVersion(match[2]!),+ });+ }+ return { features, unparsedLines };+};++export interface AdbServiceEntry {+ readonly name: string;+ readonly interface: string | null;+}++const SERVICE_LINE = /^\s*(?:\d+\s+)?([A-Za-z0-9._$/-]+):\s*\[([^\]]*)\]\s*$/u;++/** Parse `service list` output, tolerating numbered and plain formats. */+export const parseServiceListOutput = (+ stdout: string,+): {+ services: readonly AdbServiceEntry[];+ unparsedLines: readonly string[];+} => {+ const services: AdbServiceEntry[] = [];+ const unparsedLines: string[] = [];+ for (const rawLine of stdout.split(/\r?\n/u)) {+ const line = rawLine.trimEnd();+ if (line.trim() === "" || /^Found \d+ services:/u.test(line.trim()))+ continue;+ const match = SERVICE_LINE.exec(line);+ if (match === null) {+ if (line.trim() !== "") unparsedLines.push(line.trim());+ continue;+ }+ services.push({+ name: match[1]!,+ interface: match[2] === "" ? null : match[2]!,+ });+ }+ return { services, unparsedLines };+};++const SIZE_PAIR = /^Physical size:\s+(\d+)x(\d+)$/u;+const SIZE_OVERRIDE = /^Override size:\s+(\d+)x(\d+)$/u;+const DENSITY_PHYSICAL = /^Physical density:\s+(\d+)$/u;+const DENSITY_OVERRIDE = /^Override density:\s+(\d+)$/u;++/** Parse `wm size` output into physical and optional override sizes. */+export const parseWmSizeOutput = (+ stdout: string,+): {+ physical: { readonly width: number; readonly height: number } | null;+ override: { readonly width: number; readonly height: number } | null;+} => {+ let physical = null;+ let override = null;+ for (const line of stdout.split(/\r?\n/u)) {+ const trimmed = line.trim();+ const physicalMatch = SIZE_PAIR.exec(trimmed);+ if (physicalMatch !== null)+ physical = {+ width: Number(physicalMatch[1]!),+ height: Number(physicalMatch[2]!),+ };+ const overrideMatch = SIZE_OVERRIDE.exec(trimmed);+ if (overrideMatch !== null)+ override = {+ width: Number(overrideMatch[1]!),+ height: Number(overrideMatch[2]!),+ };+ }+ return { physical, override };+};++/** Parse `wm density` output. Older builds print a bare number. */+export const parseWmDensityOutput = (+ stdout: string,+): {+ physical: number | null;+ override: number | null;+} => {+ let physical = null;+ let override = null;+ for (const line of stdout.split(/\r?\n/u)) {+ const trimmed = line.trim();+ const physicalMatch = DENSITY_PHYSICAL.exec(trimmed);+ if (physicalMatch !== null) physical = Number(physicalMatch[1]!);+ const overrideMatch = DENSITY_OVERRIDE.exec(trimmed);+ if (overrideMatch !== null) override = Number(overrideMatch[1]!);+ }+ return { physical, override };+};++/** Parse the focus declarations from `dumpsys window windows`. */+export const parseWindowFocusOutput = (+ stdout: string,+): {+ focusedWindow: string | null;+ focusedApp: string | null;+} => {+ let focusedWindow = null;+ let focusedApp = null;+ for (const line of stdout.split(/\r?\n/u)) {+ const trimmed = line.trim();+ if (focusedWindow === null && trimmed.startsWith("mCurrentFocus="))+ focusedWindow = trimmed.slice("mCurrentFocus=".length).trim();+ if (focusedApp === null && trimmed.startsWith("mFocusedApp="))+ focusedApp = trimmed.slice("mFocusedApp=".length).trim();+ }+ return { focusedWindow, focusedApp };+};++export interface AdbPackageDetails {+ readonly versionName: string | null;+ readonly versionCode: number | null;+ readonly firstInstallTime: string | null;+ readonly lastUpdateTime: string | null;+ readonly installerPackageName: string | null;+ readonly userId: number | null;+ readonly pkgFlags: string | null;+ readonly requestedPermissions: number | null;+}++const DETAIL_LINE = /^\s+([A-Za-z][A-Za-z0-9_]*)=(.*)$/u;++/**+ * Project `dumpsys package PACKAGE` output. Only the listed fields are+ * extracted; the input is version-dependent and everything else is ignored+ * by design rather than guessed.+ */+export const parseDumpsysPackageOutput = (+ stdout: string,+): AdbPackageDetails => {+ const details: {+ versionName: string | null;+ versionCode: number | null;+ firstInstallTime: string | null;+ lastUpdateTime: string | null;+ installerPackageName: string | null;+ userId: number | null;+ pkgFlags: string | null;+ } = {+ versionName: null,+ versionCode: null,+ firstInstallTime: null,+ lastUpdateTime: null,+ installerPackageName: null,+ userId: null,+ pkgFlags: null,+ };+ let inPermissions = false;+ let permissions = 0;+ for (const line of stdout.split(/\r?\n/u)) {+ if (line.trim().startsWith("requested permissions:")) {+ inPermissions = true;+ continue;+ }+ if (inPermissions && /^\s{2,}[A-Za-z0-9._]+$/.test(line)) {+ permissions += 1;+ continue;+ }+ inPermissions = false;+ const match = DETAIL_LINE.exec(line);+ if (match === null) continue;+ const key = match[1]!;+ const value = match[2]!.trim();+ if (key === "versionName" && details.versionName === null)+ details.versionName = value === "" ? null : value;+ else if (key === "versionCode" && details.versionCode === null) {+ const parsed = /^(\d+)/u.exec(value);+ if (parsed !== null) details.versionCode = Number(parsed[1]!);+ } else if (key === "firstInstallTime" && details.firstInstallTime === null)+ details.firstInstallTime = value === "" ? null : value;+ else if (key === "lastUpdateTime" && details.lastUpdateTime === null)+ details.lastUpdateTime = value === "" ? null : value;+ else if (+ key === "installerPackageName" &&+ details.installerPackageName === null+ )+ details.installerPackageName = value === "" ? null : value;+ else if (key === "userId" && details.userId === null) {+ const parsed = /^(\d+)/u.exec(value);+ if (parsed !== null) details.userId = Number(parsed[1]!);+ } else if (key === "pkgFlags" && details.pkgFlags === null)+ details.pkgFlags = value === "" ? null : value;+ }+ return { ...details, requestedPermissions: permissions };+};++/**+ * Parse `settings get` output. Android prints the literal string `null` for+ * absent keys; that is reported as a device-side null observation.+ */+export const parseSettingsGetOutput = (+ stdout: string,+): {+ value: string | null;+ deviceReportedNull: boolean;+} => {+ const trimmed = stdout.replace(/\r?\n$/u, "");+ if (trimmed === "null") return { value: null, deviceReportedNull: true };+ return { value: trimmed, deviceReportedNull: false };+};++/** Parse the host-side completion line from `adb bugreport`. */+export const parseBugreportCopiedPath = (stdout: string): string | null => {+ const match = /^Bug report copied to (.+)\r?$/mu.exec(stdout.trim());+ return match === null ? null : match[1]!;+};++/**+ * Parse `adb install`/`adb uninstall` output. adb can print `Failure [...]`+ * with a zero exit code, so the text decides, not the exit status.+ */+export const parsePackageChangeOutput = (+ stdout: string,+): {+ readonly status: "success" | "failure";+ readonly reason: string | null;+} => {+ const text = stdout.trim();+ if (/^Success$/mu.test(text)) return { status: "success", reason: null };+ const failure = /Failure \[([^\]]+)\]/u.exec(text);+ return {+ status: "failure",+ reason: failure?.[1] ?? (text === "" ? null : text.slice(0, 512)),+ };+};++/**+ * Parse `cmd package resolve-activity --brief` output: the component is the+ * last non-empty line.+ */+export const parseResolveActivityOutput = (stdout: string): string | null => {+ const lines = stdout+ .split(/\r?\n/u)+ .map((line) => line.trim())+ .filter((line) => line !== "" && !/^No activity found$/iu.test(line));+ return lines.length === 0 ? null : lines[lines.length - 1]!;+};++/**+ * Parse `am start` output. Success prints `Starting: Intent { ... }`;+ * refusals print lines starting with `Error:` or `Warning:` and activity+ * classes that do not exist name the component.+ */+export const parseAmStartOutput = (+ stdout: string,+): {+ readonly status: "started" | "refused";+ readonly startedActivity: string | null;+ readonly reason: string | null;+} => {+ const text = stdout.trim();+ const starting = /^Starting:\s+Intent\s*\{(.*)\}\s*$/mu.exec(text);+ if (starting !== null)+ return {+ status: "started",+ startedActivity: starting[1]!.trim(),+ reason: null,+ };+ const error = /^(?:Error|Warning|Exception)(?::|\b)(.*)$/mu.exec(text);+ return {+ status: "refused",+ startedActivity: null,+ reason:+ error?.[1]?.trim() ??+ (text === "" ? "am start returned no activity" : text.slice(0, 512)),+ };+};++const PNG_SIGNATURE = Buffer.from([+ 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,+]);++/** Read image dimensions from a PNG header, or null for other payloads. */+export const parsePngDimensions = (+ bytes: Uint8Array,+): {+ width: number | null;+ height: number | null;+} => {+ if (+ bytes.length < 24 ||+ !Buffer.from(bytes.subarray(0, 8)).equals(PNG_SIGNATURE)+ )+ return { width: null, height: null };+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);+ return {+ width: view.getUint32(16),+ height: view.getUint32(20),+ };+};diff --git a/src/application/adb/AdbDeviceAnalysisPort.ts b/src/application/adb/AdbDeviceAnalysisPort.tsnew file mode 100644index 000000000..a4b541a83--- /dev/null+++ b/src/application/adb/AdbDeviceAnalysisPort.ts@@ -0,0 +1,23 @@+import type {+ AnalysisExecution,+ ExecutionOptions,+ ProviderAvailability,+} from "../AnalysisProvider.js";+import type { AdbRequest } from "../../domain/adb/adbDeviceAnalysis.js";+import type { AnalysisError } from "../../domain/analysisErrorBase.js";+import type { Result } from "../../domain/result.js";++/**+ * ADB device inspection boundary over a caller-selected adb binary.+ * Implementation details belong to the provider adapter.+ */+export interface AdbDeviceAnalysisPort {+ /** Probe the selected adb binary without contacting devices. */+ inspectAvailability(signal?: AbortSignal): Promise<ProviderAvailability>;+ /** The provider holds no long-lived resources; safe to call always. */+ close(): Promise<void>;+ execute(+ request: AdbRequest,+ options?: ExecutionOptions,+ ): Promise<Result<AnalysisExecution, AnalysisError>>;+}diff --git a/src/application/adb/AdbDeviceAnalysisService.test.ts b/src/application/adb/AdbDeviceAnalysisService.test.tsnew file mode 100644index 000000000..6e3f62641--- /dev/null+++ b/src/application/adb/AdbDeviceAnalysisService.test.ts@@ -0,0 +1,96 @@+import { expect, it } from "vitest";++import { AdbDeviceAnalysisService } from "./AdbDeviceAnalysisService.js";+import type { AdbDeviceAnalysisPort } from "./AdbDeviceAnalysisPort.js";+import { createAnalysisExecution } from "../AnalysisProvider.js";+import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";+import { parseEvidence } from "../../domain/evidence.js";+import { ok } from "../../domain/result.js";++const identity = { id: "adb", name: "Android Debug Bridge", version: null };++const execution = createAnalysisExecution(+ {+ client: {+ binary_path: "/usr/bin/adb",+ path_source: "path",+ version: "34.0.5-debian",+ installed_path: "/usr/bin/adb",+ },+ devices: [],+ may_have_started_adb_server: false,+ },+ identity,+);++const refusedPort: AdbDeviceAnalysisPort = {+ async inspectAvailability() {+ throw new Error("must not probe");+ },+ async close() {},+ async execute() {+ throw new Error("must not execute");+ },+};++it.each([+ [{ serial: "" }],+ [{ serial: "has space" }],+ [{ serial: "emulator-5554", scope: "unknown" }],+ [{ serial: "emulator-5554", extra: true }],+])("rejects invalid device selection before any effect: %j", async (input) => {+ const service = new AdbDeviceAnalysisService(refusedPort);+ expect(await service.execute("inspect_adb_device", input)).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisInputError" },+ });+});++it("rejects an unknown operation before any effect", async () => {+ const service = new AdbDeviceAnalysisService(refusedPort);+ expect(+ await service.execute("inspect_adb_device" as never, {}),+ ).toMatchObject({ ok: false, error: { _tag: "AnalysisInputError" } });+});++it("composes observed Evidence with the caller parameters inline", async () => {+ const port: AdbDeviceAnalysisPort = {+ async inspectAvailability() {+ return { status: "available", code: null, reason: null, diagnostics: {} };+ },+ async close() {},+ async execute(request) {+ expect(request).toEqual({+ operation: "list_adb_devices",+ input: {},+ });+ return ok(execution);+ },+ };+ const result = await new AdbDeviceAnalysisService(port).execute(+ "list_adb_devices",+ {},+ );+ if (!result.ok) throw new Error(result.error.message);+ const evidence = parseEvidence(result.value);+ expect(evidence.provider).toEqual(identity);+ expect(evidence.operation).toBe("list_adb_devices");+ expect(evidence.parameters).toEqual({});+ expect(evidence.confidence).toBe("observed");+});++it("preserves cancellation before execution", async () => {+ const controller = new AbortController();+ controller.abort();+ const service = new AdbDeviceAnalysisService(refusedPort);+ const result = await service.execute(+ "list_adb_devices",+ {},+ {+ signal: controller.signal,+ },+ );+ expect(result.ok).toBe(false);+ if (result.ok) return;+ expect(result.error).toBeInstanceOf(AnalysisCancelledError);+});diff --git a/src/application/adb/AdbDeviceAnalysisService.ts b/src/application/adb/AdbDeviceAnalysisService.tsnew file mode 100644index 000000000..64d6f98f3--- /dev/null+++ b/src/application/adb/AdbDeviceAnalysisService.ts@@ -0,0 +1,46 @@+import type { AdbDeviceAnalysisPort } from "./AdbDeviceAnalysisPort.js";+import type { ExecutionOptions } from "../AnalysisProvider.js";+import {+ adbRequestSchema,+ type AdbOperation,+} from "../../domain/adb/adbDeviceAnalysis.js";+import {+ AnalysisCancelledError,+ AnalysisInputError,+} from "../../domain/analysisErrorCore.js";+import type { AnalysisError } from "../../domain/analysisErrorBase.js";+import { createEvidence, type Evidence } from "../../domain/evidence.js";+import { jsonObjectSchema } from "../../domain/jsonValue.js";+import { err, ok, type Result } from "../../domain/result.js";++/** Shared CLI/MCP admission, execution, and Evidence composition for ADB. */+export class AdbDeviceAnalysisService {+ constructor(readonly provider: AdbDeviceAnalysisPort) {}++ /** Run one caller-selected ADB request and retain device provenance inline. */+ async execute(+ operation: AdbOperation,+ input: unknown,+ options?: ExecutionOptions,+ ): Promise<Result<Evidence, AnalysisError>> {+ if (options?.signal?.aborted === true)+ return err(new AnalysisCancelledError(operation));+ const request = adbRequestSchema.safeParse({ operation, input });+ if (!request.success)+ return err(new AnalysisInputError(operation, { cause: request.error }));+ const executed = await this.provider.execute(request.data, options);+ if (!executed.ok) return executed;+ const execution = executed.value;+ return ok(+ createEvidence(execution.subject ?? undefined, execution.provider, {+ operation,+ parameters: jsonObjectSchema.parse(request.data.input),+ result: execution.result,+ rawResult: execution.rawResult,+ limitations: execution.limitations,+ locations: execution.locations,+ confidence: "observed",+ }),+ );+ }+}diff --git a/src/cli.ts b/src/cli.tsindex 36dcd1275..3099e5071 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -15,6 +15,7 @@ import { registerArtifactCommands } from "./cli/artifactCommands.js";import { registerManagedCommands } from "./cli/managedCommands.js";import { registerFirmwareCommands } from "./cli/firmwareCommands.js";import { registerAndroidCommands } from "./cli/androidCommands.js";+import { registerAdbCommands } from "./cli/adbCommands.js";import { registerEvidenceCommands } from "./cliEvidenceCommands.js";import { registerProcessCommands } from "./cli/processCommands.js";import { registerBrowserCommands } from "./cli/browserCommands.js";@@ -73,6 +74,7 @@ export const createCli = (registerArtifactCommands(cli, logger, analysis.runProviderAnalysis);registerManagedCommands(cli, logger, analysis.runProviderAnalysis);registerAndroidCommands(cli, logger, environment);+ registerAdbCommands(cli, logger, environment);registerFirmwareCommands(cli, logger, environment);registerBinaryDiagnosticsCommands(cli, logger, environment);registerAnalysisViewCommands(cli, logger);diff --git a/src/cli/adbCommands.ts b/src/cli/adbCommands.tsnew file mode 100644index 000000000..677cf8f91--- /dev/null+++ b/src/cli/adbCommands.ts@@ -0,0 +1,393 @@+import { z } from "incur";+import { AnalysisError } from "../domain/analysisErrorBase.js";+import { AdbDeviceAnalysisService } from "../application/adb/AdbDeviceAnalysisService.js";+import type { AdbDeviceAnalysisPort } from "../application/adb/AdbDeviceAnalysisPort.js";+import { createAdbDeviceAnalysisProvider } from "../composition/adb.js";+import { CLI_COMMANDS } from "../cliCommandNames.js";+import { logCliCommand } from "../cliLogging.js";+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";+import type { AdbOperation } from "../domain/adb/adbDeviceAnalysis.js";+import type { Logger } from "pino";+import type { CliInstance } from "./types.js";+import { withCommandCancellation } from "./commandCancellation.js";++/** Expose the same explicit ADB requests through one-shot CLI commands. */+export const registerAdbCommands = (+ cli: CliInstance,+ logger: Logger,+ environment: Readonly<Record<string, string | undefined>>,+ provider: AdbDeviceAnalysisPort = createAdbDeviceAnalysisProvider(+ environment,+ ),+): void => {+ const service = new AdbDeviceAnalysisService(provider);+ const execute = (name: string, operation: AdbOperation, input: unknown) =>+ withCommandCancellation((signal) =>+ logCliCommand(logger, name, async () => {+ const result = await service.execute(operation, input, { signal });+ try {+ await provider.close();+ } catch (cause) {+ if (cause instanceof AnalysisError)+ return projectAnalysisError(cause);+ throw cause;+ }+ return result.ok ? result.value : projectAnalysisError(result.error);+ }),+ );++ const serial = z+ .string()+ .min(1)+ .describe("Device serial exactly as `adb devices` reports it");++ cli.command(CLI_COMMANDS.inspectAdbClient, {+ description:+ "Inspect the caller-selected adb client without contacting devices",+ args: z.object({}),+ run: () => execute(CLI_COMMANDS.inspectAdbClient, "inspect_adb_client", {}),+ });+ cli.command(CLI_COMMANDS.listAdbDevices, {+ description:+ "List attached devices with serial, state, transport, and inferred kind",+ args: z.object({}),+ run: () => execute(CLI_COMMANDS.listAdbDevices, "list_adb_devices", {}),+ });+ cli.command(CLI_COMMANDS.inspectAdbDevice, {+ description:+ "Inspect one device's build identity through a fixed getprop whitelist",+ args: z.object({ serial }),+ run: ({ args }) =>+ execute(CLI_COMMANDS.inspectAdbDevice, "inspect_adb_device", args),+ });+ cli.command(CLI_COMMANDS.listAdbPackages, {+ description:+ "List installed packages on one device with base APK device paths",+ args: z.object({ serial }),+ options: z.object({+ scope: z+ .enum(["all", "third_party", "system"])+ .default("all")+ .describe("Restrict to third-party or system packages"),+ }),+ run: ({ args, options }) =>+ execute(CLI_COMMANDS.listAdbPackages, "list_adb_packages", {+ serial: args.serial,+ scope: options.scope,+ }),+ });+ cli.command(CLI_COMMANDS.pullAdbPackage, {+ description:+ "Pull one installed package's complete APK set with SHA-256 digests",+ args: z.object({+ serial,+ package: z.string().min(1).describe("Installed package name"),+ }),+ options: z.object({+ "output-directory": z+ .string()+ .min(1)+ .describe(+ "Local directory for the pulled APK set; a package-named subdirectory is created inside",+ ),+ }),+ run: ({ args, options }) =>+ execute(CLI_COMMANDS.pullAdbPackage, "pull_adb_package", {+ serial: args.serial,+ package: args.package,+ output_directory: options["output-directory"],+ }),+ });+ cli.command(CLI_COMMANDS.readAdbLogcat, {+ description: "Read a bounded dump of the device log for one buffer",+ args: z.object({ serial }),+ options: z.object({+ count: z+ .number()+ .int()+ .min(1)+ .max(10_000)+ .default(500)+ .describe("Number of most recent lines to read"),+ buffer: z+ .enum(["main", "system", "radio", "events", "crash"])+ .default("main")+ .describe("Log buffer to read"),+ pid: z+ .number()+ .int()+ .positive()+ .optional()+ .describe("Restrict to one process id"),+ }),+ run: ({ args, options }) =>+ execute(CLI_COMMANDS.readAdbLogcat, "read_adb_logcat", {+ serial: args.serial,+ count: options.count,+ buffer: options.buffer,+ ...(options.pid === undefined ? {} : { pid: options.pid }),+ }),+ });+ cli.command(CLI_COMMANDS.inspectAdbPackage, {+ description:+ "Inspect one installed package's version, installer, and flags through dumpsys",+ args: z.object({ serial, package: z.string().min(1).describe("Package") }),+ run: ({ args }) =>+ execute(CLI_COMMANDS.inspectAdbPackage, "inspect_adb_package", {+ serial: args.serial,+ package: args.package,+ }),+ });+ cli.command(CLI_COMMANDS.pullAdbFile, {+ description: "Pull one device file to a local copy with a SHA-256 digest",+ args: z.object({+ serial,+ "device-path": z.string().min(1).describe("Absolute device path to pull"),+ }),+ options: z.object({+ "output-directory": z+ .string()+ .min(1)+ .describe("Local directory for the pulled file"),+ }),+ run: ({ args, options }) =>+ execute(CLI_COMMANDS.pullAdbFile, "pull_adb_file", {+ serial: args.serial,+ device_path: args["device-path"],+ output_directory: options["output-directory"],+ }),+ });+ cli.command(CLI_COMMANDS.pushAdbFile, {+ description:+ "Push one local file to the device; refuses existing targets without --overwrite",+ args: z.object({+ serial,+ "local-path": z.string().min(1).describe("Existing local file"),+ "device-path": z.string().min(1).describe("Absolute device destination"),+ }),+ options: z.object({+ overwrite: z+ .boolean()+ .default(false)+ .describe("Allow replacing an existing device file"),+ }),+ run: ({ args, options }) =>+ execute(CLI_COMMANDS.pushAdbFile, "push_adb_file", {+ serial: args.serial,+ local_path: args["local-path"],+ device_path: args["device-path"],+ overwrite: options.overwrite,+ }),+ });+ cli.command(CLI_COMMANDS.captureAdbScreen, {+ description: "Capture one screen frame as a digested PNG",+ args: z.object({ serial }),+ options: z.object({+ "output-directory": z+ .string()+ .min(1)+ .describe("Local directory for screen.png"),+ }),+ run: ({ args, options }) =>+ execute(CLI_COMMANDS.captureAdbScreen, "capture_adb_screen", {+ serial: args.serial,+ output_directory: options["output-directory"],+ }),+ });+ cli.command(CLI_COMMANDS.listAdbProcesses, {+ description: "List running processes exactly as ps -A reports them",+ args: z.object({ serial }),+ run: ({ args }) =>+ execute(CLI_COMMANDS.listAdbProcesses, "list_adb_processes", args),+ });+ cli.command(CLI_COMMANDS.listAdbDirectory, {+ description: "List one device directory with kinds, permissions, and sizes",+ args: z.object({+ serial,+ "device-path": z+ .string()+ .min(1)+ .describe("Absolute device directory path to list"),+ }),+ run: ({ args }) =>+ execute(CLI_COMMANDS.listAdbDirectory, "list_adb_directory", {+ serial: args.serial,+ device_path: args["device-path"],+ }),+ });+ cli.command(CLI_COMMANDS.listAdbFeatures, {+ description: "List the device's declared hardware and software features",+ args: z.object({ serial }),+ run: ({ args }) =>+ execute(CLI_COMMANDS.listAdbFeatures, "list_adb_features", args),+ });+ cli.command(CLI_COMMANDS.listAdbServices, {+ description: "List the device's binder services and interfaces",+ args: z.object({ serial }),+ run: ({ args }) =>+ execute(CLI_COMMANDS.listAdbServices, "list_adb_services", args),+ });+ cli.command(CLI_COMMANDS.inspectAdbDisplay, {+ description: "Report the display's declared size and density",+ args: z.object({ serial }),+ run: ({ args }) =>+ execute(CLI_COMMANDS.inspectAdbDisplay, "inspect_adb_display", args),+ });+ cli.command(CLI_COMMANDS.inspectAdbWindow, {+ description: "Report the window manager's current focus declarations",+ args: z.object({ serial }),+ run: ({ args }) =>+ execute(CLI_COMMANDS.inspectAdbWindow, "inspect_adb_window", args),+ });+ cli.command(CLI_COMMANDS.readAdbSetting, {+ description: "Read one settings value from system, secure, or global",+ args: z.object({+ serial,+ namespace: z+ .enum(["system", "secure", "global"])+ .describe("Settings namespace to read"),+ key: z.string().min(1).describe("Setting key to read"),+ }),+ run: ({ args }) =>+ execute(CLI_COMMANDS.readAdbSetting, "read_adb_setting", {+ serial: args.serial,+ namespace: args.namespace,+ key: args.key,+ }),+ });+ cli.command(CLI_COMMANDS.collectAdbBugreport, {+ description: "Collect and digest one device-generated bugreport archive",+ args: z.object({ serial }),+ options: z.object({+ "output-directory": z+ .string()+ .min(1)+ .describe("Local directory for the bugreport zip"),+ }),+ run: ({ args, options }) =>+ execute(CLI_COMMANDS.collectAdbBugreport, "collect_adb_bugreport", {+ serial: args.serial,+ output_directory: options["output-directory"],+ }),+ });+ cli.command(CLI_COMMANDS.resolveAdbPackages, {+ description: "Find installed packages by case-insensitive name substring",+ args: z.object({+ serial,+ query: z.string().min(2).describe("Package-name substring to find"),+ }),+ run: ({ args }) =>+ execute(CLI_COMMANDS.resolveAdbPackages, "resolve_adb_packages", {+ serial: args.serial,+ query: args.query,+ }),+ });+ cli.command(CLI_COMMANDS.installAdbPackage, {+ description:+ "Install one local APK; --replace re-installs keeping the app's data",+ args: z.object({+ serial,+ "apk-path": z.string().min(1).describe("Local APK file to install"),+ }),+ options: z.object({+ replace: z+ .boolean()+ .default(false)+ .describe("Replace an existing install and keep its data"),+ }),+ run: ({ args, options }) =>+ execute(CLI_COMMANDS.installAdbPackage, "install_adb_package", {+ serial: args.serial,+ apk_path: args["apk-path"],+ replace: options.replace,+ }),+ });+ cli.command(CLI_COMMANDS.uninstallAdbPackage, {+ description: "Uninstall one package and its data from the device",+ args: z.object({+ serial,+ package: z.string().min(1).describe("Installed package to uninstall"),+ }),+ run: ({ args }) =>+ execute(CLI_COMMANDS.uninstallAdbPackage, "uninstall_adb_package", {+ serial: args.serial,+ package: args.package,+ }),+ });+ cli.command(CLI_COMMANDS.startAdbApp, {+ description:+ "Start one installed app by resolving and launching its launcher activity",+ args: z.object({+ serial,+ package: z.string().min(1).describe("Installed package to start"),+ }),+ run: ({ args }) =>+ execute(CLI_COMMANDS.startAdbApp, "start_adb_app", {+ serial: args.serial,+ package: args.package,+ }),+ });+ cli.command(CLI_COMMANDS.startAdbActivity, {+ description:+ "Start an intent with am start (action, URI, component, extras)",+ args: z.object({+ serial,+ action: z.string().min(1).describe("Intent action to start"),+ }),+ options: z.object({+ "data-uri": z.string().min(1).optional().describe("Intent data URI (-d)"),+ component: z+ .string()+ .min(1)+ .optional()+ .describe("Explicit component in package/activity form (-n)"),+ extra: z+ .array(z.string().min(1))+ .default([])+ .describe(+ "Typed extra as type:key:value (string, boolean, int, long, float), repeatable",+ ),+ }),+ run: ({ args, options }) => {+ const extras = options.extra.map((entry) => {+ const first = entry.indexOf(":");+ const second = entry.indexOf(":", first + 1);+ if (first === -1 || second === -1)+ throw new Error(`--extra expects type:key:value, received: ${entry}`);+ return {+ type: entry.slice(0, first) as+ | "string"+ | "boolean"+ | "int"+ | "long"+ | "float",+ key: entry.slice(first + 1, second),+ value: entry.slice(second + 1),+ };+ });+ return execute(CLI_COMMANDS.startAdbActivity, "start_adb_activity", {+ serial: args.serial,+ action: args.action,+ ...(options["data-uri"] === undefined+ ? {}+ : { data_uri: options["data-uri"] }),+ ...(options.component === undefined+ ? {}+ : { component: options.component }),+ extras,+ });+ },+ });+ cli.command(CLI_COMMANDS.stopAdbApp, {+ description: "Force-stop every process of one package",+ args: z.object({+ serial,+ package: z.string().min(1).describe("Package to force-stop"),+ }),+ run: ({ args }) =>+ execute(CLI_COMMANDS.stopAdbApp, "stop_adb_app", {+ serial: args.serial,+ package: args.package,+ }),+ });+};diff --git a/src/cliCommandNames.ts b/src/cliCommandNames.tsindex dd0329eb0..99db69fb6 100644--- a/src/cliCommandNames.ts+++ b/src/cliCommandNames.ts@@ -45,6 +45,30 @@ export const CLI_COMMANDS = Object.freeze({inspectFirmwareRegions: "inspect-firmware-regions",extractFirmware: "extract-firmware",inspectAndroidPackage: "inspect-android-package",+ inspectAdbClient: "inspect-adb-client",+ listAdbDevices: "list-adb-devices",+ inspectAdbDevice: "inspect-adb-device",+ listAdbPackages: "list-adb-packages",+ pullAdbPackage: "pull-adb-package",+ readAdbLogcat: "read-adb-logcat",+ inspectAdbPackage: "inspect-adb-package",+ pullAdbFile: "pull-adb-file",+ pushAdbFile: "push-adb-file",+ captureAdbScreen: "capture-adb-screen",+ listAdbProcesses: "list-adb-processes",+ listAdbDirectory: "list-adb-directory",+ listAdbFeatures: "list-adb-features",+ listAdbServices: "list-adb-services",+ inspectAdbDisplay: "inspect-adb-display",+ inspectAdbWindow: "inspect-adb-window",+ readAdbSetting: "read-adb-setting",+ collectAdbBugreport: "collect-adb-bugreport",+ resolveAdbPackages: "resolve-adb-packages",+ installAdbPackage: "install-adb-package",+ uninstallAdbPackage: "uninstall-adb-package",+ startAdbApp: "start-adb-app",+ startAdbActivity: "start-adb-activity",+ stopAdbApp: "stop-adb-app",searchAndroidClasses: "search-android-classes",inspectAndroidClass: "inspect-android-class",inspectAndroidMethod: "inspect-android-method",diff --git a/src/composition/adb.ts b/src/composition/adb.tsnew file mode 100644index 000000000..b88d8b971--- /dev/null+++ b/src/composition/adb.ts@@ -0,0 +1,7 @@+import type { AdbDeviceAnalysisPort } from "../application/adb/AdbDeviceAnalysisPort.js";+import { AdbProvider } from "../adb/AdbProvider.js";++/** Construct one ADB provider bound to the caller-selected binary. */+export const createAdbDeviceAnalysisProvider = (+ environment: Readonly<Record<string, string | undefined>> = process.env,+): AdbDeviceAnalysisPort => new AdbProvider({ environment });diff --git a/src/contracts/adb/adbToolContracts.ts b/src/contracts/adb/adbToolContracts.tsnew file mode 100644index 000000000..30377069a--- /dev/null+++ b/src/contracts/adb/adbToolContracts.ts@@ -0,0 +1,382 @@+import {+ adbInputSchemas,+ adbResultSchemas,+} from "../../domain/adb/adbDeviceAnalysis.js";+import type { ToolContract } from "../toolContractTypes.js";+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";+import { toolContractMetadata } from "../toolEffects.js";++/** ADB device inspection and acquisition over a caller-supplied binary. */+export const ADB_TOOL_CONTRACTS = [+ {+ name: "inspect_adb_client",+ ...toolContractMetadata("inspect_adb_client"),+ description:+ "Inspect the caller-selected adb client: resolved binary, version, and install path. Never contacts devices and never starts the adb server. REA never installs platform tools; select a binary with REA_ADB_PATH (absolute) or adb on PATH.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.inspect_adb_client,+ outputSchema: evidenceResultOf(adbResultSchemas.inspect_adb_client),+ examples: [{ title: "Check the adb client", input: {} }],+ },+ {+ name: "list_adb_devices",+ ...toolContractMetadata("list_adb_devices"),+ description:+ "List attached devices exactly as `adb devices -l` reports them: serial, state, transport, model metadata, and an inferred emulator/physical kind with its evidence basis. Emulators and USB or network devices appear alike; REA neither starts nor manages them. May start the local adb server on first use.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.list_adb_devices,+ outputSchema: evidenceResultOf(adbResultSchemas.list_adb_devices),+ examples: [{ title: "List attached devices", input: {} }],+ },+ {+ name: "inspect_adb_device",+ ...toolContractMetadata("inspect_adb_device"),+ description:+ "Inspect one device's build identity through a fixed `getprop` whitelist: Android and SDK versions, security patch, fingerprint, product identity, CPU ABIs, and debuggable flag, plus the observed emulator indicator ro.kernel.qemu. Read-only with respect to the device.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.inspect_adb_device,+ outputSchema: evidenceResultOf(adbResultSchemas.inspect_adb_device),+ examples: [+ { title: "Inspect one device", input: { serial: "emulator-5554" } },+ ],+ },+ {+ name: "list_adb_packages",+ ...toolContractMetadata("list_adb_packages"),+ description:+ "List installed packages on one device with each base APK's device path, optionally scoped to third-party or system packages. Paths are device filesystem paths, not host-local. Read-only.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.list_adb_packages,+ outputSchema: evidenceResultOf(adbResultSchemas.list_adb_packages),+ examples: [+ {+ title: "List third-party packages",+ input: { serial: "emulator-5554", scope: "third_party" },+ },+ ],+ },+ {+ name: "pull_adb_package",+ ...toolContractMetadata("pull_adb_package"),+ description:+ "Pull one installed package's complete APK set (base plus every split, as `pm path` reports) from the device into a caller-selected output directory, creating a package-named subdirectory that must not already exist. Every pulled file is digested with SHA-256; partial pulls keep successful artifacts and per-file failure reasons. The device keeps the originals.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.pull_adb_package,+ outputSchema: evidenceResultOf(adbResultSchemas.pull_adb_package),+ examples: [+ {+ title: "Pull a package APK set",+ input: {+ serial: "emulator-5554",+ package: "com.example.app",+ output_directory: "/tmp/rea-pulls",+ },+ },+ ],+ },+ {+ name: "read_adb_logcat",+ ...toolContractMetadata("read_adb_logcat"),+ description:+ "Read a bounded dump of the device log (`logcat -d -t`) for one buffer, optionally restricted to a process id. No streaming, no clearing; the newest lines are kept when the count cap trims. Read-only.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.read_adb_logcat,+ outputSchema: evidenceResultOf(adbResultSchemas.read_adb_logcat),+ examples: [+ {+ title: "Read the last 200 main-buffer lines",+ input: { serial: "emulator-5554", count: 200, buffer: "main" },+ },+ ],+ },+ {+ name: "inspect_adb_package",+ ...toolContractMetadata("inspect_adb_package"),+ description:+ "Inspect one installed package through `dumpsys package`: version name/code, install and update times, installer, user id, flags, and the requested-permission count. A fixed projection of version-dependent output; unknown sections are ignored rather than guessed. Read-only.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.inspect_adb_package,+ outputSchema: evidenceResultOf(adbResultSchemas.inspect_adb_package),+ examples: [+ {+ title: "Inspect an installed package",+ input: { serial: "emulator-5554", package: "com.example.app" },+ },+ ],+ },+ {+ name: "pull_adb_file",+ ...toolContractMetadata("pull_adb_file"),+ description:+ "Pull one absolute device path (a database, shared-preferences XML, or any readable file) into a caller-selected output directory, digesting it with SHA-256. The local copy must not already exist. Read-only with respect to the device.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.pull_adb_file,+ outputSchema: evidenceResultOf(adbResultSchemas.pull_adb_file),+ examples: [+ {+ title: "Pull an app database",+ input: {+ serial: "emulator-5554",+ device_path: "/data/data/com.example.app/databases/app.db",+ output_directory: "/tmp/rea-pulls",+ },+ },+ ],+ },+ {+ name: "push_adb_file",+ ...toolContractMetadata("push_adb_file"),+ description:+ "Push one local file to an absolute device path. The only device-mutating ADB tool: existing device files are refused unless overwrite is explicitly requested, and the transfer is verified by comparing the local digest with the device's own sha256sum when the device provides one.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.push_adb_file,+ outputSchema: evidenceResultOf(adbResultSchemas.push_adb_file),+ examples: [+ {+ title: "Push a script to tmp",+ input: {+ serial: "emulator-5554",+ local_path: "/tmp/frida-server",+ device_path: "/data/local/tmp/frida-server",+ },+ },+ ],+ },+ {+ name: "capture_adb_screen",+ ...toolContractMetadata("capture_adb_screen"),+ description:+ "Capture one frame of the device screen as a PNG (`screencap -p` through exec-out, no device-side file) into a caller-selected output directory, digesting it and reporting its dimensions. No recording or interaction.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.capture_adb_screen,+ outputSchema: evidenceResultOf(adbResultSchemas.capture_adb_screen),+ examples: [+ {+ title: "Capture the current screen",+ input: {+ serial: "emulator-5554",+ output_directory: "/tmp/rea-captures",+ },+ },+ ],+ },+ {+ name: "list_adb_processes",+ ...toolContractMetadata("list_adb_processes"),+ description:+ "List running processes exactly as `ps -A` reports them: user, pid, ppid, rss, state, and name. Useful for pairing with instrumentation lanes. Read-only.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.list_adb_processes,+ outputSchema: evidenceResultOf(adbResultSchemas.list_adb_processes),+ examples: [{ title: "List processes", input: { serial: "emulator-5554" } }],+ },+ {+ name: "list_adb_directory",+ ...toolContractMetadata("list_adb_directory"),+ description:+ "List one absolute device directory (`ls -la`): names, kinds, permissions, owner, group, sizes, dates, and symlink targets. Recognizes the standard errors for absent paths and denied reads. Read-only.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.list_adb_directory,+ outputSchema: evidenceResultOf(adbResultSchemas.list_adb_directory),+ examples: [+ {+ title: "List an app's data directory",+ input: {+ serial: "emulator-5554",+ device_path: "/data/data/com.example.app",+ },+ },+ ],+ },+ {+ name: "list_adb_features",+ ...toolContractMetadata("list_adb_features"),+ description:+ "List the device's declared hardware and software features (`pm list features`) for device fingerprinting. Read-only.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.list_adb_features,+ outputSchema: evidenceResultOf(adbResultSchemas.list_adb_features),+ examples: [{ title: "List features", input: { serial: "emulator-5554" } }],+ },+ {+ name: "list_adb_services",+ ...toolContractMetadata("list_adb_services"),+ description:+ "List the device's binder services with their interfaces (`service list`). Read-only.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.list_adb_services,+ outputSchema: evidenceResultOf(adbResultSchemas.list_adb_services),+ examples: [{ title: "List services", input: { serial: "emulator-5554" } }],+ },+ {+ name: "inspect_adb_display",+ ...toolContractMetadata("inspect_adb_display"),+ description:+ "Report the display's physical and any overridden size (`wm size`) and density (`wm density`) as the device declares them. Read-only; setting values is not exposed.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.inspect_adb_display,+ outputSchema: evidenceResultOf(adbResultSchemas.inspect_adb_display),+ examples: [+ { title: "Inspect the display", input: { serial: "emulator-5554" } },+ ],+ },+ {+ name: "inspect_adb_window",+ ...toolContractMetadata("inspect_adb_window"),+ description:+ "Report the window manager's current focus declarations (`dumpsys window windows`: mCurrentFocus and mFocusedApp) — what is on screen at read time without any interaction. Read-only.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.inspect_adb_window,+ outputSchema: evidenceResultOf(adbResultSchemas.inspect_adb_window),+ examples: [+ { title: "Inspect window focus", input: { serial: "emulator-5554" } },+ ],+ },+ {+ name: "read_adb_setting",+ ...toolContractMetadata("read_adb_setting"),+ description:+ "Read one settings value (`settings get`) from the system, secure, or global namespace. Absent keys report the device's own null observation. Read-only; writing settings is not exposed.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.read_adb_setting,+ outputSchema: evidenceResultOf(adbResultSchemas.read_adb_setting),+ examples: [+ {+ title: "Read the ADB-enabled setting",+ input: {+ serial: "emulator-5554",+ namespace: "secure",+ key: "adb_enabled",+ },+ },+ ],+ },+ {+ name: "collect_adb_bugreport",+ ...toolContractMetadata("collect_adb_bugreport"),+ description:+ "Collect one device-generated bugreport archive (`adb bugreport`) into a caller-selected output directory, digesting the zip. The archive contains the device's own dumpstate, dumpsys, and logcat report; collection can take minutes. Read-only with respect to configuration.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.collect_adb_bugreport,+ outputSchema: evidenceResultOf(adbResultSchemas.collect_adb_bugreport),+ examples: [+ {+ title: "Collect a bugreport",+ input: {+ serial: "emulator-5554",+ output_directory: "/tmp/rea-bugreports",+ },+ },+ ],+ },+ {+ name: "resolve_adb_packages",+ ...toolContractMetadata("resolve_adb_packages"),+ description:+ "Find installed packages by case-insensitive substring of the package name (e.g. `whatsapp` → `com.whatsapp`), returning each match's base APK device path. The first step of an easy get: resolve, then pull_adb_package the exact name. Read-only.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.resolve_adb_packages,+ outputSchema: evidenceResultOf(adbResultSchemas.resolve_adb_packages),+ examples: [+ {+ title: "Find a package by partial name",+ input: { serial: "emulator-5554", query: "whatsapp" },+ },+ ],+ },+ {+ name: "install_adb_package",+ ...toolContractMetadata("install_adb_package"),+ description:+ "Install one local APK on the device (`adb install [-r]`), recording the APK's host digest and byte size. A device-mutating tool: `replace` re-installs over an existing package while keeping its data; the device's own Success/Failure verdict is preserved with its reason.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.install_adb_package,+ outputSchema: evidenceResultOf(adbResultSchemas.install_adb_package),+ examples: [+ {+ title: "Install an APK",+ input: { serial: "emulator-5554", apk_path: "/tmp/app.apk" },+ },+ {+ title: "Replace an existing install keeping data",+ input: {+ serial: "emulator-5554",+ apk_path: "/tmp/app.apk",+ replace: true,+ },+ },+ ],+ },+ {+ name: "uninstall_adb_package",+ ...toolContractMetadata("uninstall_adb_package"),+ description:+ "Uninstall one package from the device (`adb uninstall`), removing its data for user 0. A device-mutating tool; absent packages report the device's own refusal reason.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.uninstall_adb_package,+ outputSchema: evidenceResultOf(adbResultSchemas.uninstall_adb_package),+ examples: [+ {+ title: "Uninstall a package",+ input: { serial: "emulator-5554", package: "com.example.app" },+ },+ ],+ },+ {+ name: "start_adb_app",+ ...toolContractMetadata("start_adb_app"),+ description:+ "Start one installed app by launching its declared launcher activity: the component is resolved through `cmd package resolve-activity --brief`, then started with `am start -n`. A device-mutating tool for dynamic-analysis workflows; pair with `read_adb_logcat` (pid filter) and `list_adb_processes` to observe the started app, and `stop_adb_app` to end the run.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.start_adb_app,+ outputSchema: evidenceResultOf(adbResultSchemas.start_adb_app),+ examples: [+ {+ title: "Start an app",+ input: { serial: "emulator-5554", package: "com.example.app" },+ },+ ],+ },+ {+ name: "start_adb_activity",+ ...toolContractMetadata("start_adb_activity"),+ description:+ "Start an intent with `am start`: one action, optional data URI, optional explicit component, and up to 16 typed extras (string, boolean, int, long, float). A device-mutating tool; the activity manager's Starting/Error verdict is preserved verbatim.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.start_adb_activity,+ outputSchema: evidenceResultOf(adbResultSchemas.start_adb_activity),+ examples: [+ {+ title: "Open a deep link",+ input: {+ serial: "emulator-5554",+ action: "android.intent.action.VIEW",+ data_uri: "https://example.com/path",+ },+ },+ {+ title: "Start with typed extras",+ input: {+ serial: "emulator-5554",+ action: "com.example.APP_ACTION",+ extras: [{ key: "level", type: "int", value: "3" }],+ },+ },+ ],+ },+ {+ name: "stop_adb_app",+ ...toolContractMetadata("stop_adb_app"),+ description:+ "Force-stop every process of one package (`am force-stop`), ending a dynamic-analysis run. A device-mutating tool; it succeeds whether or not the package had running processes.",+ kind: "adb-provider",+ inputSchema: adbInputSchemas.stop_adb_app,+ outputSchema: evidenceResultOf(adbResultSchemas.stop_adb_app),+ examples: [+ {+ title: "Stop an app",+ input: { serial: "emulator-5554", package: "com.example.app" },+ },+ ],+ },+] as const satisfies readonly ToolContract[];diff --git a/src/contracts/toolContractTypes.ts b/src/contracts/toolContractTypes.tsindex c4234d25a..0e1cb43cc 100644--- a/src/contracts/toolContractTypes.ts+++ b/src/contracts/toolContractTypes.ts@@ -25,6 +25,7 @@ export const TOOL_KINDS = ["artifact-provider","managed-provider","android-provider",+ "adb-provider","firmware-provider","browser-provider","electron-provider",diff --git a/src/contracts/toolContracts.ts b/src/contracts/toolContracts.tsindex 212a748bd..7446a55fb 100644--- a/src/contracts/toolContracts.ts+++ b/src/contracts/toolContracts.ts@@ -6,6 +6,7 @@ import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js";import { MANAGED_TOOL_CONTRACTS } from "./managed/managedToolContracts.js";import { FIRMWARE_TOOL_CONTRACTS } from "./firmware/firmwareToolContracts.js";import { ANDROID_TOOL_CONTRACTS } from "./android/androidToolContracts.js";+import { ADB_TOOL_CONTRACTS } from "./adb/adbToolContracts.js";import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "./managed/managedWorkflowToolContracts.js";import { BROWSER_PROVIDER_TOOL_CONTRACTS } from "./browserProviderToolContracts.js";import { ELECTRON_TOOL_CONTRACTS } from "./javascript/electronToolContracts.js";@@ -30,6 +31,7 @@ export const TOOL_CONTRACTS = [...EVM_TOOL_CONTRACTS,...MANAGED_TOOL_CONTRACTS,...ANDROID_TOOL_CONTRACTS,+ ...ADB_TOOL_CONTRACTS,...FIRMWARE_TOOL_CONTRACTS,...MANAGED_WORKFLOW_TOOL_CONTRACTS,...BROWSER_PROVIDER_TOOL_CONTRACTS,diff --git a/src/contracts/toolEffects.ts b/src/contracts/toolEffects.tsindex 35a51010b..2c4cc0240 100644--- a/src/contracts/toolEffects.ts+++ b/src/contracts/toolEffects.ts@@ -97,6 +97,146 @@ export const TOOL_EFFECTS: Readonly<Record<string, ToolEffects>> = {launchesProcess: true,writesFilesystem: true,}),+ inspect_adb_client: effects({+ mutatesSession: true,+ launchesProcess: true,+ }),+ list_adb_devices: effects({+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ }),+ inspect_adb_device: effects({+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ }),+ list_adb_packages: effects({+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ }),+ pull_adb_package: effects({+ mutatesSession: true,+ launchesProcess: true,+ writesFilesystem: true,+ accessesNetwork: true,+ idempotent: false,+ }),+ read_adb_logcat: effects({+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ }),+ inspect_adb_package: effects({+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ }),+ pull_adb_file: effects({+ mutatesSession: true,+ launchesProcess: true,+ writesFilesystem: true,+ accessesNetwork: true,+ idempotent: false,+ }),+ push_adb_file: effects({+ mutatesTarget: true,+ mutatesSession: true,+ launchesProcess: true,+ writesFilesystem: true,+ accessesNetwork: true,+ idempotent: false,+ }),+ capture_adb_screen: effects({+ mutatesSession: true,+ launchesProcess: true,+ writesFilesystem: true,+ accessesNetwork: true,+ idempotent: false,+ }),+ list_adb_processes: effects({+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ }),+ list_adb_directory: effects({+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ }),+ list_adb_features: effects({+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ }),+ list_adb_services: effects({+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ }),+ inspect_adb_display: effects({+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ }),+ inspect_adb_window: effects({+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ }),+ read_adb_setting: effects({+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ }),+ collect_adb_bugreport: effects({+ mutatesSession: true,+ launchesProcess: true,+ writesFilesystem: true,+ accessesNetwork: true,+ idempotent: false,+ }),+ resolve_adb_packages: effects({+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ }),+ install_adb_package: effects({+ mutatesTarget: true,+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ idempotent: false,+ }),+ uninstall_adb_package: effects({+ mutatesTarget: true,+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ idempotent: false,+ }),+ start_adb_app: effects({+ mutatesTarget: true,+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ idempotent: false,+ }),+ start_adb_activity: effects({+ mutatesTarget: true,+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ idempotent: false,+ }),+ stop_adb_app: effects({+ mutatesTarget: true,+ mutatesSession: true,+ launchesProcess: true,+ accessesNetwork: true,+ idempotent: false,+ }),search_android_classes: effects({mutatesSession: true,launchesProcess: true,diff --git a/src/domain/adb/adbDeviceAnalysis.ts b/src/domain/adb/adbDeviceAnalysis.tsnew file mode 100644index 000000000..31684e800--- /dev/null+++ b/src/domain/adb/adbDeviceAnalysis.ts@@ -0,0 +1,706 @@+import { z } from "zod";+import { localPathStringSchema } from "../localPath.js";++/**+ * Device serials as adb prints them: emulator-5554, USB identifiers, and+ * host:port transports. The pattern keeps arguments free of whitespace and+ * quotes; argv is positional in the provider, so this is admission hygiene+ * rather than injection defense.+ */+const deviceSerialSchema = z+ .string()+ .min(1)+ .max(256)+ .regex(+ /^[^\x00\s"']+$/u,+ "Device serial cannot contain whitespace or quotes",+ );++/**+ * Android package names as Package Manager reports them. System entries can+ * be a single segment (`android`), so at least one identifier is required.+ */+const packageNameSchema = z+ .string()+ .min(1)+ .max(256)+ .regex(+ /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)*$/u,+ "Package name must be dot-separated Java identifiers",+ );++/**+ * Caller intent for ADB-backed device inspection and acquisition.+ *+ * REA never installs platform tools, starts an emulator, or manages devices;+ * every operation addresses devices the caller already connected, through the+ * adb binary the caller selected.+ */+export const adbInputSchemas = {+ inspect_adb_client: z.strictObject({}),+ list_adb_devices: z.strictObject({}),+ inspect_adb_device: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ }),+ list_adb_packages: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ scope: z+ .enum(["all", "third_party", "system"])+ .default("all")+ .describe(+ "Package scope: all packages, third-party only (-3), or system only (-s)",+ ),+ }),+ pull_adb_package: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ package: packageNameSchema.describe(+ "Installed package name whose APK set is pulled",+ ),+ output_directory: localPathStringSchema.describe(+ "Local directory for the pulled APK set; REA creates a package-named subdirectory inside it",+ ),+ }),+ read_adb_logcat: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ count: z+ .number()+ .int()+ .min(1)+ .max(10_000)+ .default(500)+ .describe("Number of most recent lines to read (logcat -d -t)"),+ buffer: z+ .enum(["main", "system", "radio", "events", "crash"])+ .default("main")+ .describe("Log buffer to read (logcat -b)"),+ pid: z+ .number()+ .int()+ .positive()+ .optional()+ .describe("Restrict to one process id (logcat --pid)"),+ }),+ inspect_adb_package: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ package: packageNameSchema.describe("Installed package to inspect"),+ }),+ pull_adb_file: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ device_path: z+ .string()+ .min(1)+ .regex(/^\/[^\x00]*$/u, "Device path must be absolute")+ .describe("Absolute device filesystem path to pull"),+ output_directory: localPathStringSchema.describe(+ "Local directory for the pulled file; must not already contain the file",+ ),+ }),+ push_adb_file: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ local_path: localPathStringSchema.describe(+ "Existing local regular file to push",+ ),+ device_path: z+ .string()+ .min(1)+ .regex(/^\/[^\x00]*$/u, "Device path must be absolute")+ .describe("Absolute destination path on the device"),+ overwrite: z+ .boolean()+ .default(false)+ .describe("Allow replacing an existing device file; refused by default"),+ }),+ capture_adb_screen: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ output_directory: localPathStringSchema.describe(+ "Local directory for the captured PNG; must not already contain it",+ ),+ }),+ list_adb_processes: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ }),+ list_adb_directory: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ device_path: z+ .string()+ .min(1)+ .regex(/^\/[^\x00]*$/u, "Device path must be absolute")+ .describe("Absolute device directory path to list (ls -la)"),+ }),+ list_adb_features: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ }),+ list_adb_services: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ }),+ inspect_adb_display: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ }),+ inspect_adb_window: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ }),+ read_adb_setting: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ namespace: z+ .enum(["system", "secure", "global"])+ .describe("Settings namespace to read"),+ key: z+ .string()+ .min(1)+ .max(256)+ .regex(+ /^[A-Za-z0-9._-]+$/u,+ "Setting keys are restricted to identifiers",+ )+ .describe("Setting key to read"),+ }),+ collect_adb_bugreport: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ output_directory: localPathStringSchema.describe(+ "Local directory for the bugreport archive; REA writes exactly one new zip into it",+ ),+ }),+ resolve_adb_packages: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ query: z+ .string()+ .min(2)+ .max(256)+ .describe(+ "Case-insensitive substring matched against installed package names (e.g. whatsapp)",+ ),+ }),+ install_adb_package: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ apk_path: localPathStringSchema.describe(+ "Existing local APK file to install",+ ),+ replace: z+ .boolean()+ .default(false)+ .describe(+ "Replace an existing installation and keep its data (adb install -r)",+ ),+ }),+ uninstall_adb_package: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ package: packageNameSchema.describe("Installed package to uninstall"),+ }),+ start_adb_app: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ package: packageNameSchema.describe(+ "Installed package whose launcher activity is started",+ ),+ }),+ start_adb_activity: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ action: z+ .string()+ .min(1)+ .max(256)+ .regex(+ /^[A-Za-z][A-Za-z0-9._-]*$/u,+ "Intent action must be a dotted identifier such as android.intent.action.VIEW",+ )+ .describe("Intent action to start"),+ data_uri: z+ .string()+ .min(1)+ .max(2048)+ .regex(/^[^\x00\s]+$/u, "Data URI cannot contain whitespace or NUL")+ .optional()+ .describe("Intent data URI (-d)"),+ component: z+ .string()+ .min(1)+ .max(512)+ .regex(+ /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]*)?$/u,+ "Component must be package/activity form",+ )+ .optional()+ .describe("Explicit component to start (-n)"),+ extras: z+ .array(+ z.strictObject({+ key: z+ .string()+ .min(1)+ .max(256)+ .regex(/^[A-Za-z0-9._-]+$/u, "Extra keys are identifiers")+ .describe("Extra key"),+ type: z+ .enum(["string", "boolean", "int", "long", "float"])+ .describe("Extra value type"),+ value: z+ .string()+ .min(1)+ .max(2048)+ .regex(/^[^\x00]*$/u, "Extra values cannot contain NUL")+ .describe("Extra value as text, parsed per type"),+ }),+ )+ .max(16)+ .default([])+ .describe("Typed intent extras (--es/--ez/--ei/--el/--ef)"),+ }),+ stop_adb_app: z.strictObject({+ serial: deviceSerialSchema.describe(+ "Device serial exactly as `adb devices` reports it",+ ),+ package: packageNameSchema.describe(+ "Package whose processes are force-stopped",+ ),+ }),+} as const;++/** Supported ADB-backed operations. */+export type AdbOperation = keyof typeof adbInputSchemas;+/** Validated ADB requests carry their selected operation. */+export type AdbRequest = {+ [Name in AdbOperation]: {+ operation: Name;+ input: z.infer<(typeof adbInputSchemas)[Name]>;+ };+}[AdbOperation];++/** Validate operation and input together so their types remain correlated. */+export const adbRequestSchema = z.discriminatedUnion("operation", [+ z.strictObject({+ operation: z.literal("inspect_adb_client"),+ input: adbInputSchemas.inspect_adb_client,+ }),+ z.strictObject({+ operation: z.literal("list_adb_devices"),+ input: adbInputSchemas.list_adb_devices,+ }),+ z.strictObject({+ operation: z.literal("inspect_adb_device"),+ input: adbInputSchemas.inspect_adb_device,+ }),+ z.strictObject({+ operation: z.literal("list_adb_packages"),+ input: adbInputSchemas.list_adb_packages,+ }),+ z.strictObject({+ operation: z.literal("pull_adb_package"),+ input: adbInputSchemas.pull_adb_package,+ }),+ z.strictObject({+ operation: z.literal("read_adb_logcat"),+ input: adbInputSchemas.read_adb_logcat,+ }),+ z.strictObject({+ operation: z.literal("inspect_adb_package"),+ input: adbInputSchemas.inspect_adb_package,+ }),+ z.strictObject({+ operation: z.literal("pull_adb_file"),+ input: adbInputSchemas.pull_adb_file,+ }),+ z.strictObject({+ operation: z.literal("push_adb_file"),+ input: adbInputSchemas.push_adb_file,+ }),+ z.strictObject({+ operation: z.literal("capture_adb_screen"),+ input: adbInputSchemas.capture_adb_screen,+ }),+ z.strictObject({+ operation: z.literal("list_adb_processes"),+ input: adbInputSchemas.list_adb_processes,+ }),+ z.strictObject({+ operation: z.literal("list_adb_directory"),+ input: adbInputSchemas.list_adb_directory,+ }),+ z.strictObject({+ operation: z.literal("list_adb_features"),+ input: adbInputSchemas.list_adb_features,+ }),+ z.strictObject({+ operation: z.literal("list_adb_services"),+ input: adbInputSchemas.list_adb_services,+ }),+ z.strictObject({+ operation: z.literal("inspect_adb_display"),+ input: adbInputSchemas.inspect_adb_display,+ }),+ z.strictObject({+ operation: z.literal("inspect_adb_window"),+ input: adbInputSchemas.inspect_adb_window,+ }),+ z.strictObject({+ operation: z.literal("read_adb_setting"),+ input: adbInputSchemas.read_adb_setting,+ }),+ z.strictObject({+ operation: z.literal("collect_adb_bugreport"),+ input: adbInputSchemas.collect_adb_bugreport,+ }),+ z.strictObject({+ operation: z.literal("resolve_adb_packages"),+ input: adbInputSchemas.resolve_adb_packages,+ }),+ z.strictObject({+ operation: z.literal("install_adb_package"),+ input: adbInputSchemas.install_adb_package,+ }),+ z.strictObject({+ operation: z.literal("uninstall_adb_package"),+ input: adbInputSchemas.uninstall_adb_package,+ }),+ z.strictObject({+ operation: z.literal("start_adb_app"),+ input: adbInputSchemas.start_adb_app,+ }),+ z.strictObject({+ operation: z.literal("start_adb_activity"),+ input: adbInputSchemas.start_adb_activity,+ }),+ z.strictObject({+ operation: z.literal("stop_adb_app"),+ input: adbInputSchemas.stop_adb_app,+ }),+]);++const client = z.strictObject({+ binary_path: z.string().min(1),+ path_source: z.enum(["environment", "path"]),+ version: z.string().min(1).nullable(),+ installed_path: z.string().min(1).nullable(),+});++const device = z.strictObject({+ serial: z.string().min(1),+ state: z.string().min(1),+ transport: z.enum(["usb", "tcp", "unknown"]),+ product: z.string().nullable(),+ model: z.string().nullable(),+ device: z.string().nullable(),+ transport_id: z.number().int().positive().nullable(),+ /**+ * Inferred device kind with its evidence basis. The serial prefix and the+ * `device:` metadata line are observations; the kind itself is derived.+ */+ kind: z.enum(["emulator", "physical", "unknown"]),+ kind_basis: z.enum(["emulator_serial_prefix", "usb_transport", "none"]),+});++const pulledArtifact = z.strictObject({+ device_path: z.string().min(1),+ file_name: z.string().min(1),+ local_path: z.string().min(1),+ bytes: z.number().int().nonnegative(),+ sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ role: z.enum(["base", "split", "unknown"]),+ role_basis: z.literal("file_name"),+});++const pullFailure = z.strictObject({+ device_path: z.string().min(1).nullable(),+ stage: z.enum(["resolve_paths", "pull", "digest"]),+ message: z.string().min(1),+});++/** Portable ADB observations with explicit identity and coverage limitations. */+export const adbResultSchemas = {+ inspect_adb_client: z.strictObject({+ client,+ /**+ * `adb version` never contacts the adb server; this tool starts nothing.+ * Recorded explicitly so the session keeps the distinction observable.+ */+ contacted_adb_server: z.literal(false),+ }),+ list_adb_devices: z.strictObject({+ client,+ devices: z.array(device),+ /**+ * Starting the local adb server is an adb client behavior on first use;+ * REA observes whichever server state the caller's environment has.+ */+ may_have_started_adb_server: z.boolean(),+ }),+ inspect_adb_device: z.strictObject({+ client,+ serial: z.string().min(1),+ properties: z.array(+ z.strictObject({ name: z.string().min(1), value: z.string().min(1) }),+ ),+ property_count: z.number().int().nonnegative(),+ emulator_observed: z.boolean().nullable(),+ }),+ list_adb_packages: z.strictObject({+ client,+ serial: z.string().min(1),+ scope: z.enum(["all", "third_party", "system"]),+ packages: z.array(+ z.strictObject({+ package_name: packageNameSchema,+ /** Device filesystem path; not a host-local path. */+ base_apk_device_path: z.string().min(1),+ }),+ ),+ unparsed_lines: z.array(z.string().min(1)),+ coverage: z.enum(["complete", "partial"]),+ }),+ pull_adb_package: z.strictObject({+ client,+ serial: z.string().min(1),+ package_name: packageNameSchema,+ output_directory: z.string().min(1),+ artifacts: z.array(pulledArtifact),+ failures: z.array(pullFailure),+ coverage: z.enum(["complete", "partial"]),+ }),+ read_adb_logcat: z.strictObject({+ client,+ serial: z.string().min(1),+ count: z.number().int().positive(),+ buffer: z.enum(["main", "system", "radio", "events", "crash"]),+ pid: z.number().int().positive().nullable(),+ lines: z.array(z.string()),+ total_bytes: z.number().int().nonnegative(),+ coverage: z.enum(["complete", "partial"]),+ }),+ inspect_adb_package: z.strictObject({+ client,+ serial: z.string().min(1),+ package_name: packageNameSchema,+ version_name: z.string().nullable(),+ version_code: z.number().int().nullable(),+ first_install_time: z.string().nullable(),+ last_update_time: z.string().nullable(),+ installer_package_name: z.string().nullable(),+ user_id: z.number().int().nullable(),+ pkg_flags: z.string().nullable(),+ requested_permissions_count: z.number().int().nonnegative().nullable(),+ coverage: z.enum(["complete", "partial"]),+ }),+ pull_adb_file: z.strictObject({+ client,+ serial: z.string().min(1),+ device_path: z.string().min(1),+ local_path: z.string().min(1),+ bytes: z.number().int().nonnegative(),+ sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ }),+ push_adb_file: z.strictObject({+ client,+ serial: z.string().min(1),+ local_path: z.string().min(1),+ device_path: z.string().min(1),+ bytes: z.number().int().nonnegative(),+ sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ device_sha256: z+ .string()+ .regex(/^[a-f0-9]{64}$/u)+ .nullable(),+ overwritten: z.boolean(),+ device_digest_source: z.enum(["device_sha256sum", "unavailable"]),+ }),+ capture_adb_screen: z.strictObject({+ client,+ serial: z.string().min(1),+ local_path: z.string().min(1),+ bytes: z.number().int().nonnegative(),+ sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ width: z.number().int().positive().nullable(),+ height: z.number().int().positive().nullable(),+ }),+ list_adb_processes: z.strictObject({+ client,+ serial: z.string().min(1),+ columns: z.string().nullable(),+ processes: z.array(+ z.strictObject({+ user: z.string(),+ pid: z.number().int().nonnegative(),+ ppid: z.number().int().nullable(),+ rss: z.number().int().nullable(),+ state: z.string().nullable(),+ name: z.string(),+ }),+ ),+ unparsed_lines: z.array(z.string().min(1)),+ coverage: z.enum(["complete", "partial"]),+ }),+ list_adb_directory: z.strictObject({+ client,+ serial: z.string().min(1),+ device_path: z.string().min(1),+ entries: z.array(+ z.strictObject({+ name: z.string().min(1),+ kind: z.enum(["directory", "file", "symlink", "other"]),+ permissions: z.string().nullable(),+ owner: z.string().nullable(),+ group: z.string().nullable(),+ bytes: z.number().int().nullable(),+ date: z.string().nullable(),+ link_target: z.string().nullable(),+ }),+ ),+ unparsed_lines: z.array(z.string().min(1)),+ coverage: z.enum(["complete", "partial"]),+ }),+ list_adb_features: z.strictObject({+ client,+ serial: z.string().min(1),+ features: z.array(+ z.strictObject({+ name: z.string().min(1),+ version: z.number().int().nullable(),+ }),+ ),+ unparsed_lines: z.array(z.string().min(1)),+ coverage: z.enum(["complete", "partial"]),+ }),+ list_adb_services: z.strictObject({+ client,+ serial: z.string().min(1),+ services: z.array(+ z.strictObject({+ name: z.string().min(1),+ interface: z.string().nullable(),+ }),+ ),+ unparsed_lines: z.array(z.string().min(1)),+ coverage: z.enum(["complete", "partial"]),+ }),+ inspect_adb_display: z.strictObject({+ client,+ serial: z.string().min(1),+ physical_size: z.strictObject({+ width: z.number().int().positive(),+ height: z.number().int().positive(),+ }),+ override_size: z+ .strictObject({+ width: z.number().int().positive(),+ height: z.number().int().positive(),+ })+ .nullable(),+ physical_density: z.number().int().positive().nullable(),+ override_density: z.number().int().positive().nullable(),+ }),+ inspect_adb_window: z.strictObject({+ client,+ serial: z.string().min(1),+ focused_window: z.string().nullable(),+ focused_app: z.string().nullable(),+ observed_lines: z.array(z.string().min(1)),+ }),+ read_adb_setting: z.strictObject({+ client,+ serial: z.string().min(1),+ namespace: z.enum(["system", "secure", "global"]),+ key: z.string().min(1),+ value: z.string().nullable(),+ device_reported_null: z.boolean(),+ }),+ collect_adb_bugreport: z.strictObject({+ client,+ serial: z.string().min(1),+ local_path: z.string().min(1),+ bytes: z.number().int().nonnegative(),+ sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ adb_reported_path: z.string().nullable(),+ }),+ resolve_adb_packages: z.strictObject({+ client,+ serial: z.string().min(1),+ query: z.string().min(1),+ matches: z.array(+ z.strictObject({+ package_name: packageNameSchema,+ base_apk_device_path: z.string().min(1),+ }),+ ),+ exact_match: z.boolean(),+ coverage: z.enum(["complete", "partial"]),+ }),+ install_adb_package: z.strictObject({+ client,+ serial: z.string().min(1),+ apk_path: z.string().min(1),+ bytes: z.number().int().nonnegative(),+ sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ replaced: z.boolean(),+ }),+ uninstall_adb_package: z.strictObject({+ client,+ serial: z.string().min(1),+ package_name: packageNameSchema,+ }),+ start_adb_app: z.strictObject({+ client,+ serial: z.string().min(1),+ package_name: packageNameSchema,+ component: z.string().min(1),+ started_activity: z.string().nullable(),+ }),+ start_adb_activity: z.strictObject({+ client,+ serial: z.string().min(1),+ action: z.string().min(1),+ data_uri: z.string().nullable(),+ component: z.string().nullable(),+ extras: z.array(+ z.strictObject({+ key: z.string().min(1),+ type: z.enum(["string", "boolean", "int", "long", "float"]),+ value: z.string(),+ }),+ ),+ started_activity: z.string().nullable(),+ }),+ stop_adb_app: z.strictObject({+ client,+ serial: z.string().min(1),+ package_name: packageNameSchema,+ }),+} as const;diff --git a/src/server/createServer.ts b/src/server/createServer.tsindex 1896355c6..1d49156c1 100644--- a/src/server/createServer.ts+++ b/src/server/createServer.ts@@ -62,9 +62,13 @@ import { FirmwareAnalysisService } from "../application/firmware/FirmwareAnalysiimport type { FirmwareAnalysisPort } from "../application/firmware/FirmwareAnalysisPort.js";import { createFirmwareAnalysisProvider } from "../composition/firmware.js";import { registerAndroidTools } from "./registerAndroidTools.js";+import { registerAdbTools } from "./registerAdbTools.js";import { AndroidAnalysisService } from "../application/android/AndroidAnalysisService.js";import type { AndroidAnalysisPort } from "../application/android/AndroidAnalysisPort.js";+import type { AdbDeviceAnalysisPort } from "../application/adb/AdbDeviceAnalysisPort.js";+import { AdbDeviceAnalysisService } from "../application/adb/AdbDeviceAnalysisService.js";import { createAndroidAnalysisProvider } from "../composition/android.js";+import { createAdbDeviceAnalysisProvider } from "../composition/adb.js";import { registerManagedWorkflowTools } from "./registerManagedWorkflowTools.js";import { NATIVE_TOOL_CONTRACTS } from "../contracts/native/nativeToolContracts.js";import { registerEvidenceTools } from "./registerEvidenceTools.js";@@ -99,6 +103,7 @@ export interface CreateServerOptions {readonly webRuntime?: WebRuntimeService;readonly webNetworkCapture?: WebNetworkCaptureService;readonly androidAnalysis?: AndroidAnalysisPort;+ readonly adbDeviceAnalysis?: AdbDeviceAnalysisPort;readonly browserObservation?: BrowserObservationPort;readonly browserScenarioCapture?: BrowserScenarioCapturePort;readonly electronObservation?: ElectronObservationPort;@@ -197,6 +202,8 @@ export const createServer = ();const android =options.androidAnalysis ?? createAndroidAnalysisProvider(environment);+ const adbDevice =+ options.adbDeviceAnalysis ?? createAdbDeviceAnalysisProvider(environment);const availability = installSessionToolAvailability(session,selectedOptions,@@ -239,6 +246,12 @@ export const createServer = (if (result.status === "rejected") throw result.reason;};registerConfiguredAnalysisTools(toolContext, android);+ registerAdbTools(+ server,+ new AdbDeviceAnalysisService(adbDevice),+ toolLogger,+ recordEvidence,+ );registerObservationTools(toolContext);registerGuidedPrompts(server, analysis, session);if (session !== undefined) {diff --git a/src/server/registerAdbTools.ts b/src/server/registerAdbTools.tsnew file mode 100644index 000000000..4e5dc5e95--- /dev/null+++ b/src/server/registerAdbTools.ts@@ -0,0 +1,66 @@+import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";+import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";+import type { ServerContext } from "@modelcontextprotocol/server";+import { AdbDeviceAnalysisService } from "../application/adb/AdbDeviceAnalysisService.js";+import { toolContract } from "../contracts/toolContracts.js";+import type { ToolContract } from "../contracts/toolContractTypes.js";+import type { AdbOperation } from "../domain/adb/adbDeviceAnalysis.js";+import type { Logger } from "pino";+import { logToolExecution } from "./toolLogging.js";+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";++/** Bind ADB handlers to their exact named contracts through shared workflows. */+export const registerAdbTools = (+ server: EvidenceMcpServer,+ service: AdbDeviceAnalysisService,+ logger: Logger,+ recordEvidence?: EvidenceWriter["recordEvidence"],+): void => {+ const handler = (contract: ToolContract<AdbOperation>) => {+ const name = contract.name;+ return async (input: unknown, context: ServerContext) => {+ const result = await logToolExecution(logger, name, () =>+ service.execute(name, input, { signal: context.mcpReq.signal }),+ );+ if (!result.ok) return server.delivery.toCallToolResult(result, contract);+ const recorded = recordEvidence?.(result.value);+ return server.delivery.toEvidenceToolResult(+ result.value,+ contract,+ recorded,+ );+ };+ };+ for (const contract of [+ toolContract("inspect_adb_client"),+ toolContract("list_adb_devices"),+ toolContract("inspect_adb_device"),+ toolContract("list_adb_packages"),+ toolContract("pull_adb_package"),+ toolContract("read_adb_logcat"),+ toolContract("inspect_adb_package"),+ toolContract("pull_adb_file"),+ toolContract("push_adb_file"),+ toolContract("capture_adb_screen"),+ toolContract("list_adb_processes"),+ toolContract("list_adb_directory"),+ toolContract("list_adb_features"),+ toolContract("list_adb_services"),+ toolContract("inspect_adb_display"),+ toolContract("inspect_adb_window"),+ toolContract("read_adb_setting"),+ toolContract("collect_adb_bugreport"),+ toolContract("resolve_adb_packages"),+ toolContract("install_adb_package"),+ toolContract("uninstall_adb_package"),+ toolContract("start_adb_app"),+ toolContract("start_adb_activity"),+ toolContract("stop_adb_app"),+ ] as const) {+ server.registerTool(+ contract.name,+ toolRegistrationOptions(contract),+ handler(contract),+ );+ }+};diff --git a/tests/boundary/cli/adbCli.test.ts b/tests/boundary/cli/adbCli.test.tsnew file mode 100644index 000000000..0f5824237--- /dev/null+++ b/tests/boundary/cli/adbCli.test.ts@@ -0,0 +1,77 @@+import { expect, it } from "vitest";++import { createCli } from "../../../src/cli.js";++const serve = async (+ argv: readonly string[],+ environment: Readonly<Record<string, string | undefined>> = {},+): Promise<{ readonly stdout: string; readonly exitCode: number }> => {+ const cli = createCli(environment);+ let stdout = "";+ let exitCode = 0;+ await cli.serve([...argv], {+ env: {},+ exit: (code) => {+ exitCode = code;+ },+ stdout: (text) => {+ stdout += text;+ },+ });+ return { stdout, exitCode };+};++it.each([+ ["inspect-adb-client"],+ ["list-adb-devices"],+ ["inspect-adb-device"],+ ["list-adb-packages"],+ ["pull-adb-package"],+ ["read-adb-logcat"],+ ["inspect-adb-package"],+ ["pull-adb-file"],+ ["push-adb-file"],+ ["capture-adb-screen"],+ ["list-adb-processes"],+ ["list-adb-directory"],+ ["list-adb-features"],+ ["list-adb-services"],+ ["inspect-adb-display"],+ ["inspect-adb-window"],+ ["read-adb-setting"],+ ["collect-adb-bugreport"],+ ["resolve-adb-packages"],+ ["install-adb-package"],+ ["uninstall-adb-package"],+ ["start-adb-app"],+ ["start-adb-activity"],+ ["stop-adb-app"],+])("%s advertises a schema through the public CLI", async (command) => {+ const result = await serve([command, "--schema", "--json"]);+ expect(result.exitCode, command).toBe(0);+ const schema = JSON.parse(result.stdout) as { args?: unknown };+ expect(schema).toBeTruthy();+});++it("reports a missing adb binary with recovery guidance", async () => {+ const result = await serve(["inspect-adb-client", "--json"], {+ REA_ADB_PATH: "/nonexistent/adb",+ });+ expect(result.stdout).toContain("capability_unavailable");+ expect(result.stdout).toContain("REA_ADB_PATH");+});++it("validates device serials before contacting any device", async () => {+ const result = await serve(["inspect-adb-device", "bad serial", "--json"]);+ expect(result.stdout).toContain("invalid_input");+});++it("requires the output directory option on pull", async () => {+ const result = await serve([+ "pull-adb-package",+ "emulator-5554",+ "com.example",+ "--json",+ ]);+ expect(result.exitCode).not.toBe(0);+});diff --git a/tests/boundary/mcp/adbMcp.test.ts b/tests/boundary/mcp/adbMcp.test.tsnew file mode 100644index 000000000..5b87da373--- /dev/null+++ b/tests/boundary/mcp/adbMcp.test.ts@@ -0,0 +1,397 @@+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";+import { Ajv2020 } from "ajv/dist/2020.js";+import { expect, it, onTestFinished } from "vitest";++import type { AdbDeviceAnalysisPort } from "../../../src/application/adb/AdbDeviceAnalysisPort.js";+import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js";+import { toolContract } from "../../../src/contracts/toolContracts.js";+import { parseEvidence } from "../../../src/domain/evidence.js";+import { ok } from "../../../src/domain/result.js";+import { createServer } from "../../../src/server/createServer.js";+import { createTestBinarySession } from "../../fixtures/binarySession.js";++const identity = { id: "adb", name: "Android Debug Bridge", version: null };++const clientIdentity = {+ binary_path: "/usr/bin/adb",+ path_source: "path",+ version: "34.0.5-debian",+ installed_path: "/usr/bin/adb",+};++const results: Readonly<Record<string, unknown>> = {+ inspect_adb_client: {+ client: clientIdentity,+ contacted_adb_server: false,+ },+ list_adb_devices: {+ client: clientIdentity,+ devices: [+ {+ serial: "emulator-5554",+ state: "device",+ transport: "tcp",+ product: "sdk_gphone64_x86_64",+ model: "sdk_gphone64_x86_64",+ device: "emu64xa",+ transport_id: 1,+ kind: "emulator",+ kind_basis: "emulator_serial_prefix",+ },+ ],+ may_have_started_adb_server: false,+ },+ inspect_adb_device: {+ client: clientIdentity,+ serial: "emulator-5554",+ properties: [{ name: "ro.build.version.sdk", value: "34" }],+ property_count: 1,+ emulator_observed: true,+ },+ list_adb_packages: {+ client: clientIdentity,+ serial: "emulator-5554",+ scope: "third_party",+ packages: [+ {+ package_name: "com.example",+ base_apk_device_path: "/data/app/x/base.apk",+ },+ ],+ unparsed_lines: [],+ coverage: "complete",+ },+ pull_adb_package: {+ client: clientIdentity,+ serial: "emulator-5554",+ package_name: "com.example",+ output_directory: "/tmp/rea-pulls",+ artifacts: [+ {+ device_path: "/data/app/x/base.apk",+ file_name: "base.apk",+ local_path: "/tmp/rea-pulls/com.example/base.apk",+ bytes: 2048,+ sha256: "a".repeat(64),+ role: "base",+ role_basis: "file_name",+ },+ ],+ failures: [],+ coverage: "complete",+ },+ read_adb_logcat: {+ client: clientIdentity,+ serial: "emulator-5554",+ count: 500,+ buffer: "main",+ pid: null,+ lines: ["08-10 13:00:00.000 I/Tag( 123): message"],+ total_bytes: 34,+ coverage: "complete",+ },+ inspect_adb_package: {+ client: clientIdentity,+ serial: "emulator-5554",+ package_name: "com.example",+ version_name: "1.2.3",+ version_code: 45,+ first_install_time: "2026-01-02 03:04:05",+ last_update_time: "2026-02-03 04:05:06",+ installer_package_name: null,+ user_id: 10234,+ pkg_flags: "[ HAS_CODE ]",+ requested_permissions_count: 2,+ coverage: "complete",+ },+ pull_adb_file: {+ client: clientIdentity,+ serial: "emulator-5554",+ device_path: "/data/local/tmp/notes.txt",+ local_path: "/tmp/rea-pulls/notes.txt",+ bytes: 10,+ sha256: "a".repeat(64),+ },+ push_adb_file: {+ client: clientIdentity,+ serial: "emulator-5554",+ local_path: "/tmp/payload.bin",+ device_path: "/data/local/tmp/payload.bin",+ bytes: 12,+ sha256: "a".repeat(64),+ device_sha256: "a".repeat(64),+ overwritten: false,+ device_digest_source: "device_sha256sum",+ },+ capture_adb_screen: {+ client: clientIdentity,+ serial: "emulator-5554",+ local_path: "/tmp/rea-captures/screen.png",+ bytes: 8192,+ sha256: "a".repeat(64),+ width: 1080,+ height: 2340,+ },+ list_adb_processes: {+ client: clientIdentity,+ serial: "emulator-5554",+ columns: "USER PID PPID VSZ RSS WCHAN ADDR S NAME",+ processes: [+ {+ user: "u0_a1",+ pid: 1234,+ ppid: 567,+ rss: 7890,+ state: "S",+ name: "com.example.app",+ },+ ],+ unparsed_lines: [],+ coverage: "complete",+ },+ list_adb_directory: {+ client: clientIdentity,+ serial: "emulator-5554",+ device_path: "/data/local/tmp",+ entries: [+ {+ name: "notes.txt",+ kind: "file",+ permissions: "-rw-rw-rw-",+ owner: "shell",+ group: "shell",+ bytes: 10,+ date: "2026-01-01 10:00",+ link_target: null,+ },+ ],+ unparsed_lines: [],+ coverage: "complete",+ },+ list_adb_features: {+ client: clientIdentity,+ serial: "emulator-5554",+ features: [{ name: "android.hardware.camera", version: null }],+ unparsed_lines: [],+ coverage: "complete",+ },+ list_adb_services: {+ client: clientIdentity,+ serial: "emulator-5554",+ services: [+ { name: "package", interface: "android.content.pm.IPackageManager" },+ ],+ unparsed_lines: [],+ coverage: "complete",+ },+ inspect_adb_display: {+ client: clientIdentity,+ serial: "emulator-5554",+ physical_size: { width: 1080, height: 2340 },+ override_size: null,+ physical_density: 420,+ override_density: null,+ },+ inspect_adb_window: {+ client: clientIdentity,+ serial: "emulator-5554",+ focused_window: "Window{abcdef u0 com.example.app/Main}",+ focused_app: null,+ observed_lines: ["Window{abcdef u0 com.example.app/Main}"],+ },+ read_adb_setting: {+ client: clientIdentity,+ serial: "emulator-5554",+ namespace: "secure",+ key: "adb_enabled",+ value: "1",+ device_reported_null: false,+ },+ collect_adb_bugreport: {+ client: clientIdentity,+ serial: "emulator-5554",+ local_path: "/tmp/rea-bugreports/bugreport.zip",+ bytes: 1024,+ sha256: "a".repeat(64),+ adb_reported_path: "/tmp/rea-bugreports/bugreport.zip",+ },+ resolve_adb_packages: {+ client: clientIdentity,+ serial: "emulator-5554",+ query: "whatsapp",+ matches: [+ {+ package_name: "com.whatsapp",+ base_apk_device_path: "/data/app/x/base.apk",+ },+ ],+ exact_match: true,+ coverage: "complete",+ },+ install_adb_package: {+ client: clientIdentity,+ serial: "emulator-5554",+ apk_path: "/tmp/app.apk",+ bytes: 2048,+ sha256: "a".repeat(64),+ replaced: false,+ },+ uninstall_adb_package: {+ client: clientIdentity,+ serial: "emulator-5554",+ package_name: "com.whatsapp",+ },+ start_adb_app: {+ client: clientIdentity,+ serial: "emulator-5554",+ package_name: "com.example.app",+ component: "com.example.app/.Main",+ started_activity:+ "act=android.intent.action.MAIN cat=[android.intent.category.LAUNCHER] cmp=com.example.app/.Main",+ },+ start_adb_activity: {+ client: clientIdentity,+ serial: "emulator-5554",+ action: "android.intent.action.VIEW",+ data_uri: "https://example.com/",+ component: null,+ extras: [],+ started_activity: "act=android.intent.action.VIEW dat=https://example.com/",+ },+ stop_adb_app: {+ client: clientIdentity,+ serial: "emulator-5554",+ package_name: "com.example.app",+ },+};++it("advertises exact valid ADB schemas and records inline evidence through MCP", async () => {+ const provider: AdbDeviceAnalysisPort = {+ async inspectAvailability() {+ return { status: "available", code: null, reason: null, diagnostics: {} };+ },+ async close() {},+ async execute(request) {+ return ok(createAnalysisExecution(results[request.operation], identity));+ },+ };+ const session = createTestBinarySession(() => {+ throw new Error("deep provider must not start");+ });+ const server = createServer(+ { kind: "session", session },+ { adbDeviceAnalysis: provider },+ );+ onTestFinished(() => server.close());+ const [clientTransport, serverTransport] =+ InMemoryTransport.createLinkedPair();+ await server.connect(serverTransport);+ const client = new Client({ name: "adb-boundary", version: "0.0.0" });+ onTestFinished(() => client.close());+ await client.connect(clientTransport);++ const { tools } = await client.listTools();+ const names = tools.map((tool) => tool.name);+ const operationNames = [+ "inspect_adb_client",+ "list_adb_devices",+ "inspect_adb_device",+ "list_adb_packages",+ "pull_adb_package",+ "read_adb_logcat",+ "inspect_adb_package",+ "pull_adb_file",+ "push_adb_file",+ "capture_adb_screen",+ "list_adb_processes",+ "list_adb_directory",+ "list_adb_features",+ "list_adb_services",+ "inspect_adb_display",+ "inspect_adb_window",+ "read_adb_setting",+ "collect_adb_bugreport",+ "resolve_adb_packages",+ "install_adb_package",+ "uninstall_adb_package",+ "start_adb_app",+ "start_adb_activity",+ "stop_adb_app",+ ] as const;+ for (const name of operationNames) expect(names, name).toContain(name);++ const ajv = new Ajv2020({ strict: false, allErrors: true });+ for (const name of operationNames) {+ const contract = toolContract(name);+ const listed = tools.find((tool) => tool.name === name);+ expect(listed, name).toBeTruthy();+ if (listed?.inputSchema === undefined) continue;+ // The server may present a compacted form of the contract schema; what+ // must hold is that the advertised schema compiles and accepts the+ // contract's own examples, and rejects unknown input.+ const validate = ajv.compile(+ JSON.parse(JSON.stringify(listed.inputSchema)),+ );+ for (const example of contract.examples)+ expect(validate(example.input), `${name} example`).toBe(true);+ expect(validate({ unknown_argument: true }), `${name} rejects`).toBe(false);+ }++ const pulled = await client.callTool({+ name: "pull_adb_package",+ arguments: {+ serial: "emulator-5554",+ package: "com.example",+ output_directory: "/tmp/rea-pulls",+ },+ });+ expect(pulled.isError).not.toBe(true);+ const text = (pulled.content as { readonly text?: string }[])+ .map((part) => part.text ?? "")+ .join("");+ const evidence = parseEvidence(JSON.parse(text));+ expect(evidence.provider.id).toBe("adb");+ expect(evidence.operation).toBe("pull_adb_package");+ expect(evidence.normalized_result).toMatchObject({+ artifacts: [{ file_name: "base.apk", role: "base", bytes: 2048 }],+ coverage: "complete",+ });+});++it("rejects invalid tool input before reaching the provider", async () => {+ const provider: AdbDeviceAnalysisPort = {+ async inspectAvailability() {+ return { status: "available", code: null, reason: null, diagnostics: {} };+ },+ async close() {},+ async execute() {+ throw new Error("must not execute");+ },+ };+ const server = createServer(+ {+ kind: "session",+ session: createTestBinarySession(() => {+ throw new Error("must not start");+ }),+ },+ { adbDeviceAnalysis: provider },+ );+ onTestFinished(() => server.close());+ const [clientTransport, serverTransport] =+ InMemoryTransport.createLinkedPair();+ await server.connect(serverTransport);+ const client = new Client({ name: "adb-boundary-invalid", version: "0.0.0" });+ onTestFinished(() => client.close());+ await client.connect(clientTransport);++ const rejected = await client.callTool({+ name: "inspect_adb_device",+ arguments: { serial: "bad serial" },+ });+ expect(rejected.isError).toBe(true);+ const text = (rejected.content as { readonly text?: string }[])+ .map((part) => part.text ?? "")+ .join("");+ expect(text).toContain("Invalid arguments for tool inspect_adb_device");+});diff --git a/vitest.config.ts b/vitest.config.tsindex 8c629580d..32edc6856 100644--- a/vitest.config.ts+++ b/vitest.config.ts@@ -37,7 +37,7 @@ const TEST_PROJECTS = [name: "adapters",include: ["src/*.test.ts",- "src/{artifacts,browser,dotnet,evm,firmware,ghidra,hopper,ida,inspector,javascript,native,process,reference,server,windows}/**/*.test.ts",+ "src/{adb,artifacts,browser,dotnet,evm,firmware,ghidra,hopper,ida,inspector,javascript,native,process,reference,server,windows}/**/*.test.ts",],pool: "forks" as const,maxWorkers: MAX_TEST_WORKERS,