diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ab30d0b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,99 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Commands + +### Development (full app) +```bash +bash scripts/dev.sh +``` +Builds backend, desktop, regenerates Wails bindings, type-checks frontend, then starts `wails dev` with hot reload. + +### Build for production +```bash +bash scripts/build.sh +``` + +### Per-component build/check +```bash +# Backend +cd backend-go && go build ./... + +# Desktop (Go) +cd desktop && go build ./... + +# Frontend type-check only +cd frontend-react && npx tsc -b --noEmit + +# Frontend bundle (outputs to desktop/frontend/dist/) +cd frontend-react && npm run build + +# Wails desktop binary +cd desktop && export PATH="$PATH:$(go env GOPATH)/bin" && wails build + +# Android SDK +cd android-sdk && ./gradlew :sdk:assembleDebug +``` + +### Regenerate Wails JS bindings +```bash +cd desktop && export PATH="$PATH:$(go env GOPATH)/bin" && wails generate module +``` +Run this after adding or changing any exported method on `App` in `desktop/app.go`. Output goes to `frontend-react/src/wailsjs/` — do not edit those files manually. + +--- + +## Architecture + +``` +Android App → Instrumentation SDK → ADB Tunnel → Go Backend → React Frontend → Wails Desktop Shell +``` + +### Monorepo layout + +| Directory | Module / Package | Role | +|---|---|---| +| `desktop/` | `git.achmad.dev/admin/droidscope/desktop` | Wails app — entry point, `app.go` exposes bound methods | +| `backend-go/` | `git.achmad.dev/admin/droidscope/backend` | Go packages: ADB, device, logcat, network, storage, etc. | +| `frontend-react/` | — | Vite + React + TypeScript UI | +| `android-sdk/` | `dev.achmad.droidscope` | Kotlin instrumentation SDK | +| `scripts/` | — | `dev.sh`, `build.sh`, `download-adb.sh` | + +### Go workspace +`go.work` links `./desktop` and `./backend-go` for local resolution. `desktop/go.mod` also has a `replace` directive — both are needed (`go.work` for IDE/build, `replace` for `go mod tidy`). + +### Wails ↔ React bridge +- `desktop/wails.json`: `"frontend:dir": "../frontend-react"`, `"wailsjsdir": "../frontend-react/src"` +- Vite `build.outDir` is `../desktop/frontend/dist` so Go's `//go:embed` works +- Import bound methods from `@/wailsjs/go/main/App` in React + +### State model (frontend) +- **`selectedDeviceId`** — which device the info panel is showing (can be anything) +- **`profiledDeviceId`** — the active monitoring target for all feature panels (logcat, network, etc.) +- These are separate concepts in `app-store.ts` (Zustand) + +### Active device scoping (all feature panels) +Every feature panel outside Device Management must: +1. Import `useActiveDevice` from `@/hooks/use-active-device` +2. Gate all polling/streaming behind `isMonitoring` +3. Store per-device data via `patchDeviceCache(deviceId, data)` — never cleared on device switch +4. Render `` when `!isMonitoring` + +### ADB binary resolution (runtime) +`desktop/internal/adbembed/` — resolves in order: embedded binary → `$ANDROID_HOME/platform-tools/adb` → `adb` on `$PATH`. Embed directive uses `//go:embed all:bin` (not `//go:embed bin`) because the placeholder file is hidden. + +### Static vs live device data +- `GetDeviceInfo(deviceId)` — one-time fetch, ~20 static fields (model, OS version, ABI, etc.) +- `GetDeviceLiveStats(deviceId)` — polled every 1 s (RAM, battery, thermal, storage, IP) +- `devices:changed` Wails event — emitted every 1 s for the device list + +--- + +## Key conventions + +- Never use `namespace` TypeScript syntax — it conflicts with Wails-generated `models.ts` and `erasableSyntaxOnly` must stay off in `tsconfig.app.json` +- shadcn/ui uses Base UI (not Radix UI) — `DialogTrigger` has no `asChild` prop; use controlled `open` state instead +- `tsconfig.app.json` has no `baseUrl`; path alias `@/*` → `./src/*` works via `moduleResolution: bundler` +- Do not run `go work sync` — it fails for unpublished modules; the workspace + replace approach handles everything +- Never commit anything under `frontend-react/src/wailsjs/` — it is auto-generated diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..db4df66 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,237 @@ +# DroidScope — Development Guide + +## Prerequisites + +| Tool | Version | Install | +|---|---|---| +| Go | 1.23+ | https://go.dev/dl | +| Node.js | 20+ | https://nodejs.org | +| Wails CLI | v2 | `go install github.com/wailsapp/wails/v2/cmd/wails@latest` | +| Git | any | — | + +> **macOS only:** Wails requires Xcode Command Line Tools — `xcode-select --install` +> +> **Linux only:** Wails requires `libgtk-3-dev libwebkit2gtk-4.0-dev` (Debian/Ubuntu) or equivalent. +> +> **Windows only:** Wails requires WebView2 (ships with Windows 11, otherwise install from Microsoft). + +--- + +## First-time Setup + +```bash +# 1. Install frontend dependencies +cd frontend-react +npm install + +# 2. (Optional) Download bundled ADB binaries for distribution builds +# Skip this for local dev — the app falls back to your system ADB +bash scripts/download-adb.sh + +# 3. Make sure your system ADB is accessible for local dev +# Either via ANDROID_HOME or PATH: +export ANDROID_HOME=~/Library/Android/sdk # macOS example +# or: ensure `adb` is on your PATH +``` + +--- + +## Running in Development + +```bash +bash scripts/dev.sh +``` + +**What `dev.sh` does, in order:** + +| Step | Command | What it checks | +|---|---|---| +| 1 | `go build ./...` in `backend-go/` | Backend packages compile without errors | +| 2 | `go build ./...` in `desktop/` | Desktop Go code (app.go, main.go, embeds) compiles | +| 3 | `wails generate module` in `desktop/` | Regenerates `frontend-react/src/wailsjs/` from current `app.go` bindings | +| 4 | `npm install` + `tsc -b --noEmit` in `frontend-react/` | Installs any new deps, type-checks TypeScript | +| — | `wails dev` in `desktop/` | Starts the desktop app with hot reload | + +If any step fails the script exits immediately (due to `set -e`) — fix the error and re-run. + +**What happens once running:** +- Wails compiles the Go backend and opens a native desktop window +- Wails starts the Vite dev server (`npm run dev` in `frontend-react/`) +- React/TS changes hot-reload instantly without restarting +- Go changes (in `app.go`, `backend-go/`) require re-running `dev.sh` + +> **When to re-run `dev.sh` vs just saving a file:** +> - Edited only `.tsx` / `.ts` / `.css` → Vite hot-reloads automatically, no restart needed +> - Edited `app.go` (added/changed a bound method) → re-run `dev.sh` to rebuild Go + regenerate bindings +> - Edited anything under `backend-go/` → re-run `dev.sh` to rebuild + +**Frontend only** (browser preview, no Wails bindings): + +```bash +cd frontend-react +npm run dev +# → http://localhost:5173 +``` + +> Wails bindings (`ListDevices`, `GetDeviceInfo`, etc.) are no-ops in plain browser mode — they only work inside the Wails desktop window. + +--- + +## Building for Production + +### Full desktop app (recommended) + +```bash +bash scripts/build.sh +``` + +Or manually: + +```bash +# Step 1 — build frontend (outputs to desktop/frontend/dist/) +cd frontend-react +npm run build + +# Step 2 — build desktop binary (embeds frontend dist + ADB binaries) +cd desktop +export PATH="$PATH:$(go env GOPATH)/bin" +wails build +``` + +Output: `desktop/build/bin/DroidScope` (macOS/Linux) or `desktop/build/bin/DroidScope.exe` (Windows) + +--- + +### Backend only + +```bash +cd backend-go +go build ./... +``` + +--- + +### Frontend only (static bundle) + +```bash +cd frontend-react +npm run build +# Output: desktop/frontend/dist/ +``` + +--- + +### Android SDK + +```bash +cd android-sdk +./gradlew :sdk:assembleDebug # debug AAR +./gradlew :sdk:assembleRelease # release AAR +# Output: android-sdk/sdk/build/outputs/aar/ +``` + +--- + +## Type Checking (no build) + +```bash +# TypeScript +cd frontend-react +npx tsc -b --noEmit + +# Go +cd backend-go && go build ./... +cd desktop && go build ./... +``` + +--- + +## Regenerating Wails JS Bindings + +Run this after adding or changing any exported method on `App` in `desktop/app.go`: + +```bash +cd desktop +export PATH="$PATH:$(go env GOPATH)/bin" +wails generate module +# Output: frontend-react/src/wailsjs/ +``` + +--- + +## Project Structure + +``` +DroidScope/ +├── desktop/ ← Wails app (Go entry point) +│ ├── app.go ← Wails-bound methods (called from frontend) +│ ├── main.go ← App bootstrap +│ ├── wails.json ← Wails config (frontend dir, dev server) +│ └── internal/adbembed/ ← ADB binary embedding + runtime extraction +│ +├── backend-go/ ← Go backend packages +│ ├── adb/ ← ADB command wrapper +│ ├── device/ ← Device manager + DeviceInfo fetcher +│ ├── logcat/ ← (stub) Logcat streaming +│ ├── network/ ← (stub) Network inspector +│ ├── storage/ ← (stub) SharedPrefs, SQLite, files +│ ├── runtime/ ← (stub) Runtime config override +│ ├── session/ ← (stub) Session management +│ └── protocol/ ← Shared event types (Go structs) +│ +├── frontend-react/ ← Vite + React + TypeScript +│ ├── src/ +│ │ ├── wailsjs/ ← Auto-generated Wails bindings (do not edit) +│ │ ├── features/ ← Feature modules (devices, logcat, network…) +│ │ ├── components/ ← Shared UI components (layout, shadcn/ui) +│ │ ├── hooks/ ← Shared hooks (useActiveDevice) +│ │ ├── store/ ← Zustand global state +│ │ └── types/ ← Shared TypeScript types (protocol) +│ └── vite.config.ts ← Build outputs to ../desktop/frontend/dist/ +│ +├── android-sdk/ ← Kotlin Android SDK (Gradle) +│ └── sdk/src/main/kotlin/dev/achmad/droidscope/ +│ +├── scripts/ +│ ├── dev.sh ← Start full dev environment +│ ├── build.sh ← Production build +│ └── download-adb.sh ← Download ADB binaries for bundling +│ +├── go.work ← Go workspace (links desktop + backend-go) +├── README.md ← Project overview and feature roadmap +├── TODO.md ← Implementation status +└── DEVELOPMENT.md ← This file +``` + +--- + +## Key Conventions + +### Adding a new Go method callable from the frontend + +1. Add the method to `desktop/app.go` (must be exported, receiver `*App`) +2. Run `wails generate module` from `desktop/` +3. Import from `@/wailsjs/go/main/App` in React + +### Adding a new backend-go package + +1. Create the package under `backend-go/` +2. The `go.work` workspace + `replace` directive in `desktop/go.mod` handle local resolution — no publishing needed + +### Active device scoping (all features) + +- Import `useActiveDevice` from `@/hooks/use-active-device` +- Check `isMonitoring` before starting streams or polls +- Store per-device data in `deviceCache` via `patchDeviceCache(deviceId, data)` — never cleared on device switch +- Show `` when `!isMonitoring` + +--- + +## ADB Binary Bundling + +For **local development** the app resolves ADB in this order: +1. Embedded binary in `desktop/internal/adbembed/bin/` (empty until `download-adb.sh` is run) +2. `$ANDROID_HOME/platform-tools/adb` +3. `adb` on `$PATH` + +For **distribution builds** run `scripts/download-adb.sh` once before `wails build` to embed ADB for all platforms. diff --git a/PLAN.md b/PLAN.md deleted file mode 100644 index b1d3c9c..0000000 --- a/PLAN.md +++ /dev/null @@ -1,760 +0,0 @@ -# Android Observability Platform — AI-Oriented Requirements Document - -## Project Name - -Temporary codename: -- DroidScope - ---- - -# Project Summary - -A standalone cross-platform desktop application for Android application observability and debugging. - -The platform allows developers to: - -- Connect Android devices/emulators through ADB -- Monitor application behavior in real time -- Inspect network traffic -- Inspect storage and databases -- Monitor performance metrics -- Analyze memory behavior -- Observe Jetpack Compose recompositions -- Stream logs -- Modify runtime configurations - -The application must provide a modern browser-like developer tooling experience similar to Chrome DevTools. - ---- - -# Primary Goals - -## Functional Goals - -- Real-time Android observability -- Cross-platform desktop support -- Multi-device support -- Low-overhead instrumentation -- Developer-focused workflows -- Unified debugging interface -- Plugin-capable architecture - ---- - -# Technology Stack - -## Desktop Framework - -### Wails - -Responsibilities: -- Native desktop shell -- Window management -- Packaging -- Native integrations - ---- - -## Backend - -### Go - -Responsibilities: -- ADB communication -- Device management -- Event streaming -- Monitoring orchestration -- Local APIs -- Session management -- Data aggregation - ---- - -## Frontend - -### React + TypeScript - -Responsibilities: -- Dashboard UI -- Inspector panels -- Charts -- Tables -- Interaction layer - ---- - -# High-Level Architecture - -```text -Android App - ↓ -Instrumentation SDK - ↓ -ADB Tunnel / WebSocket - ↓ -Go Backend - ↓ -React Frontend - ↓ -Wails Desktop Shell -``` - ---- - -# Repository Structure - -```text -root/ -├── desktop/ -├── backend-go/ -├── frontend-react/ -├── android-sdk/ -├── shared-protocol/ -├── docs/ -└── scripts/ -``` - ---- - -# Core Components - -# 1. Android Instrumentation SDK - -## Description - -Embedded Android SDK responsible for collecting runtime diagnostics and streaming events to the desktop application. - ---- - -## SDK Requirements - -### General - -- Kotlin-first -- Android SDK 24+ -- Modular architecture -- Debug-build focused -- Runtime enable/disable -- Minimal overhead -- Safe fallback behavior -- R8/ProGuard compatibility - ---- - -# 2. Go Backend - -## Description - -Central orchestration engine responsible for: -- ADB communication -- Session handling -- Event aggregation -- WebSocket streaming -- Data persistence - ---- - -## Backend Requirements - -### Device Management - -#### Capabilities - -- Detect connected devices -- Support multiple devices -- Wireless ADB support -- Device reconnect handling -- Emulator support - -#### Commands - -- List devices -- Connect device -- Disconnect device -- Restart session - ---- - -### Event Streaming - -#### Requirements - -- WebSocket-based streaming -- Low latency -- Event batching -- Backpressure handling -- Event replay support - ---- - -### Session Management - -#### Requirements - -- Multiple concurrent sessions -- Persistent sessions -- Session restore -- Session metadata - ---- - -### Security - -#### Requirements - -- Local-only communication by default -- Session isolation -- Optional authentication -- Safe runtime permissions - ---- - -# 3. React Frontend - -## Description - -Primary user interface for observability and inspection. - ---- - -## Frontend Requirements - -### General - -- Modern desktop UI -- Responsive layout -- Fast rendering -- Keyboard shortcuts -- Search everywhere -- Virtualized large lists -- Multi-tab support - ---- - -# Feature Requirements - -# Device Manager - -## Requirements - -### Device List - -Display: -- Device name -- Device ID -- Android version -- Connection type -- Connection status -- Battery level -- CPU architecture - ---- - -### Device Actions - -Support: -- Connect -- Disconnect -- Refresh -- Restart session -- Open shell - ---- - -# Logcat Monitoring - -## Requirements - -### Features - -- Real-time log streaming -- Structured log rendering -- Tag filtering -- Priority filtering -- Search -- Export logs - -### Supported Priorities - -- Verbose -- Debug -- Info -- Warn -- Error -- Assert - ---- - -# Network Inspector - -## Requirements - -### Capture - -- HTTP -- HTTPS -- WebSocket traffic - ---- - -### Request Inspection - -Display: -- URL -- Method -- Headers -- Query parameters -- Timing -- Body - ---- - -### Response Inspection - -Display: -- Status code -- Headers -- Body -- Response size -- Timing - ---- - -### Features - -- JSON formatting -- CURL export -- Request replay -- Filtering -- Search -- Timeline view - ---- - -# Shared Preferences Inspector - -## Requirements - -### Features - -- View entries -- Edit entries -- Delete entries -- Live updates - -### Data Types - -- String -- Int -- Long -- Float -- Boolean -- String Set - ---- - -# Database Browser - -## Requirements - -### Features - -- SQLite browsing -- Room database support -- Table inspection -- Query execution -- Schema visualization - -### Query Support - -- Read-only queries initially -- Query history -- Export support - ---- - -# File Browser - -## Requirements - -### Features - -- Browse sandbox files -- Download files -- Upload files -- Delete files -- Preview files - -### Preview Support - -- Text -- JSON -- Images - ---- - -# Runtime Configuration - -## Requirements - -### Features - -- Base URL override -- Feature flag toggles -- Runtime config editing -- Deep link launcher - ---- - -# FPS Monitoring - -## Requirements - -### Features - -- Real-time FPS tracking -- Jank detection -- Slow frame tracking -- Frame drop statistics - ---- - -# Memory Monitoring - -## Requirements - -### Features - -- Heap usage tracking -- Allocation monitoring -- GC event tracking -- Native memory visibility - ---- - -# Memory Leak Detection - -## Requirements - -### Features - -- Activity leak detection -- Fragment leak detection -- Retained object tracking -- Leak history - ---- - -# Thread Monitoring - -## Requirements - -### Features - -- Active thread list -- Main-thread blocking detection -- Thread state visibility -- ANR risk visibility - ---- - -# StrictMode Monitoring - -## Requirements - -### Features - -- Disk read violations -- Disk write violations -- Network-on-main-thread detection -- Resource leak detection - ---- - -# Compose Recomposition Monitoring - -## Requirements - -### Features - -- Recomposition counts -- Hotspot detection -- Frequent recomposition visibility -- State update tracing - ---- - -# WebView Monitoring - -## Requirements - -### Features - -- URL tracking -- Console log inspection -- Resource loading visibility -- WebView lifecycle visibility - ---- - -# Device Information - -## Requirements - -### Display - -- Device manufacturer -- Device model -- Android version -- ABI -- RAM -- Storage -- Battery -- Thermal status - ---- - -# Loaded Libraries Inspection - -## Requirements - -### Features - -- Loaded native libraries -- Dynamic library visibility -- ABI metadata - ---- - -# Secure Storage Inspection - -## Requirements - -### Features - -- Keystore visibility -- Key alias visibility -- Encryption metadata visibility - ---- - -# Dashboard Layout - -# Main Sections - -## Sidebar - -Contains: -- Devices -- Overview -- Logs -- Network -- Storage -- Performance -- Compose -- WebView -- Runtime -- Settings - ---- - -## Main Panel - -Displays: -- Active inspector -- Charts -- Tables -- Request details -- Device information - ---- - -# Non-Functional Requirements - -# Performance - -## Requirements - -- Low memory overhead -- Low CPU overhead -- Virtualized rendering -- Efficient event streaming - ---- - -# Reliability - -## Requirements - -- Graceful reconnect handling -- Crash recovery -- Offline handling -- Buffered events - ---- - -# Security - -## Requirements - -- Debug-only instrumentation by default -- Sensitive data masking -- Localhost-only communication by default - ---- - -# Packaging Requirements - -## Supported Platforms - -- macOS -- Windows -- Linux - ---- - -## Packaging Goals - -- Single installer -- Bundled ADB -- No Android Studio requirement -- Minimal setup - ---- - -# AI Agent Guidance - -# Backend Guidelines - -## Go Backend Principles - -- Use goroutines for stream handling -- Prefer event-driven architecture -- Avoid tightly coupled modules -- Use interfaces for feature modules -- Keep protocol versioned - ---- - -# Frontend Guidelines - -## React Principles - -- Use feature-based architecture -- Avoid excessive global state -- Use virtualization for large datasets -- Prefer streaming updates over polling - ---- - -# Android SDK Guidelines - -## SDK Principles - -- Avoid blocking main thread -- Ensure instrumentation can be disabled -- Prefer lightweight hooks -- Avoid unstable internal Android APIs where possible - ---- - -# Event Protocol - -## Event Structure - -All events should contain: - -```json -{ - "type": "", - "timestamp": 0, - "deviceId": "", - "sessionId": "", - "payload": {} -} -``` - ---- - -# MVP Scope - -# Phase 1 - -## Included Features - -- Device management -- Logcat streaming -- Network inspection -- SharedPreferences inspection -- SQLite browser -- File browser -- Runtime URL override - ---- - -# Phase 2 - -## Included Features - -- FPS monitoring -- Memory monitoring -- StrictMode monitoring -- Thread monitoring - ---- - -# Phase 3 - -## Included Features - -- Leak visualization -- Compose recomposition tooling -- Advanced tracing -- Flamegraphs - ---- - -# Future Scope - -## Potential Future Features - -- Plugin system -- Scripting support -- Automation support -- iOS support -- Flutter support -- React Native support -- Remote device support -- Team collaboration - ---- - -# Out of Scope - -## Explicit Non-Goals - -- Production analytics platform -- MDM solution -- CI/CD tooling -- Cloud-hosted observability platform -- Crash reporting replacement - ---- - -# Success Criteria - -## MVP Success Conditions - -- Device detection works reliably -- Logs stream in real time -- Network inspector functions correctly -- Storage inspection is stable -- Dashboard remains responsive under heavy streams - ---- - -# Product Positioning - -Primary positioning statement: - -> Chrome DevTools for Android Native Apps diff --git a/README.md b/README.md new file mode 100644 index 0000000..4e788e9 --- /dev/null +++ b/README.md @@ -0,0 +1,114 @@ +# DroidScope + +> Chrome DevTools for Android Native Apps + +A standalone cross-platform desktop application for Android application observability and debugging. Connect any Android device or emulator and get real-time visibility into logs, network traffic, storage, performance, and more — without needing Android Studio. + +--- + +## Features + +### Phase 1 — MVP +| Feature | Status | +|---|---| +| Device management (USB + wireless ADB) | ✅ Done | +| Real-time device stats (RAM, battery, thermal, storage) | ✅ Done | +| Logcat streaming | 🔧 In progress | +| Network inspector (OkHttp interceptor) | 📋 Planned | +| SharedPreferences inspector | 📋 Planned | +| SQLite browser | 📋 Planned | +| File browser | 📋 Planned | +| Runtime URL override & feature flags | 📋 Planned | + +### Phase 2 +FPS monitoring, memory monitoring, StrictMode violations, thread monitoring / ANR risk. + +### Phase 3 +Memory leak detection, Jetpack Compose recomposition tooling, advanced tracing, flamegraphs. + +--- + +## Technology Stack + +| Layer | Technology | +|---|---| +| Desktop shell | [Wails v2](https://wails.io) | +| Backend | Go 1.23+ | +| Frontend | React + TypeScript + Vite | +| Android SDK | Kotlin, minSdk 24 | +| UI components | shadcn/ui + Tailwind CSS | +| State | Zustand | +| Data fetching | TanStack Query | + +--- + +## Architecture + +``` +Android App + ↓ +DroidScope Instrumentation SDK (android-sdk/) + ↓ +ADB tunnel / WebSocket + ↓ +Go backend (backend-go/) + ↓ +React frontend (frontend-react/) + ↓ +Wails desktop shell (desktop/) +``` + +The desktop app bundles the Go backend and React UI into a single native binary. No server required — everything runs locally. + +--- + +## Repository Structure + +``` +DroidScope/ +├── desktop/ — Wails app (Go entry point, app.go bindings) +├── backend-go/ — Go packages: ADB, device, logcat, network, storage… +├── frontend-react/ — Vite + React + TypeScript UI +├── android-sdk/ — Kotlin instrumentation SDK +├── scripts/ — dev.sh, build.sh, download-adb.sh +├── go.work — Go workspace +├── DEVELOPMENT.md — Full development guide +└── TODO.md — Implementation status +``` + +--- + +## Getting Started + +See [DEVELOPMENT.md](DEVELOPMENT.md) for full setup instructions. + +**Quick start:** + +```bash +# 1. Install frontend dependencies +cd frontend-react && npm install + +# 2. Start full dev environment +bash scripts/dev.sh +``` + +Prerequisites: Go 1.23+, Node.js 20+, Wails CLI v2, system ADB accessible via `$ANDROID_HOME` or `$PATH`. + +--- + +## Design Principles + +- **Local-only by default** — all communication stays on localhost; no cloud dependency +- **Debug-build focused** — instrumentation SDK is designed for development builds, not production +- **Low overhead** — minimal CPU/memory impact on both desktop and device +- **Multi-device** — supports monitoring multiple connected devices simultaneously +- **Retained data** — switching between devices preserves previously captured data in memory + +--- + +## Out of Scope + +- Production analytics / crash reporting +- MDM / device management +- Cloud-hosted observability +- CI/CD tooling diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..c61aaf2 --- /dev/null +++ b/TODO.md @@ -0,0 +1,148 @@ +# DroidScope — TODO + +## Legend +- `[x]` Done +- `[ ]` Not started +- `[~]` In progress + +--- + +## Infrastructure + +- [x] Project scaffold (Wails + Go + React/TS + Kotlin SDK) +- [x] Monorepo structure (`desktop/`, `backend-go/`, `frontend-react/`, `android-sdk/`) +- [x] Go workspace (`go.work`) +- [x] Shared event protocol (Go structs + TypeScript types) +- [x] Dev script (`scripts/dev.sh`) — builds backend, desktop, regenerates bindings, type-checks, then starts +- [x] Build script (`scripts/build.sh`) +- [x] Development guide (`DEVELOPMENT.md`) +- [x] Bundle ADB binary infrastructure (`desktop/internal/adbembed/`) +- [x] ADB discovery at runtime (embedded → ANDROID_HOME → PATH fallback) +- [x] Download ADB binaries for distribution (`scripts/download-adb.sh` ready, run once) +- [ ] CI/CD pipeline + +--- + +## Phase 1 — MVP + +### Device Management +- [x] ADB wrapper (`backend-go/adb/`) +- [x] List connected devices (1s poll) +- [x] Device connect / disconnect +- [x] Wireless ADB support +- [x] Device reconnect handling +- [x] Emulator support +- [x] Static device info (model, Android version, ABI, manufacturer, screen, build fingerprint) +- [x] Live device stats — 1s poll (available RAM, battery level/status, thermal status, available storage, IP) +- [x] Frontend: device list panel with real-time updates +- [x] Frontend: wireless connect dialog +- [x] Frontend: disconnect action +- [x] Frontend: device info panel — static fields fetched once, live fields pulsing every second +- [x] Frontend: RAM usage progress bar (live) +- [x] Frontend: split layout — device list + info detail side by side +- [x] Frontend: selected device (info view) vs profiled device (monitoring target) — separate concepts +- [x] Frontend: Profile / Stop profiling toggle per device card +- [x] Frontend: active profiling indicator bar in device list +- [x] Frontend: auto-clear selected + profiled device when device disconnects or goes offline + +### Logcat +- [~] Backend stub (`backend-go/logcat/stream.go`) +- [ ] Real-time logcat streaming via ADB +- [ ] Structured log parsing (priority, tag, PID, message) +- [ ] Wails event push to frontend +- [ ] Frontend: log table with virtualized rendering +- [ ] Frontend: filter by tag +- [ ] Frontend: filter by priority (V/D/I/W/E/A) +- [ ] Frontend: search +- [ ] Frontend: export logs + +### Network Inspector +- [ ] Android SDK: OkHttp interceptor +- [ ] Backend: receive + store network events +- [ ] Frontend: request list +- [ ] Frontend: request detail (headers, body, timing) +- [ ] Frontend: response detail (status, headers, body, size) +- [ ] Frontend: JSON formatting +- [ ] Frontend: cURL export +- [ ] Frontend: filter / search + +### Shared Preferences Inspector +- [ ] Backend: pull + parse SharedPreferences XML via ADB +- [ ] Backend: write-back support +- [ ] Frontend: key/value table +- [ ] Frontend: inline editing (String, Int, Long, Float, Boolean, StringSet) +- [ ] Frontend: live update polling + +### SQLite Browser +- [ ] Backend: pull database file via ADB +- [ ] Backend: query execution +- [ ] Frontend: table list +- [ ] Frontend: table data viewer (paginated) +- [ ] Frontend: SQL query editor +- [ ] Frontend: query history +- [ ] Frontend: export + +### File Browser +- [ ] Backend: `adb shell ls` traversal +- [ ] Backend: file download (`adb pull`) +- [ ] Backend: file upload (`adb push`) +- [ ] Backend: file delete +- [ ] Frontend: file tree / list +- [ ] Frontend: text / JSON / image preview + +### Runtime Configuration +- [ ] Android SDK: base URL override hook +- [ ] Android SDK: feature flag toggle +- [ ] Backend: send config command to device +- [ ] Frontend: URL override input +- [ ] Frontend: feature flag toggles +- [ ] Frontend: deep link launcher + +--- + +## Phase 2 + +- [ ] FPS monitoring (backend + frontend chart) +- [ ] Memory monitoring (heap, GC events) +- [ ] StrictMode violation monitoring +- [ ] Thread monitoring + ANR risk + +--- + +## Phase 3 + +- [ ] Memory leak detection (Activity/Fragment) +- [ ] Compose recomposition tooling +- [ ] Advanced tracing +- [ ] Flamegraphs + +--- + +## Android SDK + +- [x] Project skeleton (`android-sdk/`) +- [x] `DroidScope.init()` / `shutdown()` entry point +- [ ] WebSocket transport to desktop +- [ ] Network interceptor (OkHttp) +- [ ] SharedPreferences observer +- [ ] Logcat forwarder (SDK-side filtering) +- [ ] FPS collector (Choreographer) +- [ ] Memory collector (Debug.MemoryInfo) +- [ ] StrictMode collector +- [ ] Compose recomposition collector + +--- + +## Frontend Shell + +- [x] Sidebar navigation +- [x] Dark theme +- [x] Selected device vs profiled device — two independent concepts in store +- [x] `useActiveDevice` hook — reads `profiledDeviceId`; `isMonitoring = false` pauses all feature panels +- [x] `NoDeviceSelected` shared component — guides user to Profile a device +- [x] Per-device data cache (`deviceCache`) — retained on device switch, never cleared automatically +- [ ] Persistent profiled device indicator in sidebar or top bar +- [ ] Multi-tab panel support +- [ ] Keyboard shortcuts +- [ ] Global search +- [ ] Settings page