Refactor: AI generated enhanced version

README.md

@@ -0,0 +1,192 @@
+# ADB Log Monitor (Enhanced)
+
+A robust, configurable, enterprise-grade logcat watcher for Android development.
+Automatically detects devices, tracks app restarts, captures logs into timestamped files, and optionally restarts the target app if its process disappears.
+
+**Author:** Reza Esmaeili
+**Purpose:** Reliable long-running log capture for debugging and QA.
+
+---
+
+## Features
+
+* 🔍 **Automatic device detection** (handles single/multiple devices)
+* 📦 **Monitors any Android package** via `pidof` or `ps`
+* 🔁 **Auto-restart option** for apps that crash or reboot
+* 📝 **Writes logs to timestamped files** in a dedicated directory
+* 🎛 **Fully configurable CLI flags**
+* 🧼 **Graceful cleanup** on exit (`Ctrl+C`)
+* ⚙️ **Strict scripting style** for reliability
+* 🚀 **Drop-in ready for CI, QA, or development machines**
+
+---
+
+## Requirements
+
+* Android `adb` (Platform-tools) installed and in PATH
+* A connected Android device or emulator authorized for debugging
+
+---
+
+## Installation
+
+Place the script anywhere in your project, e.g.:
+
+```
+scripts/adb-log-monitor.sh
+```
+
+Make it executable:
+
+```bash
+chmod +x adb-log-monitor.sh
+```
+
+(Optional) Add to PATH:
+
+```bash
+sudo ln -s /path/to/adb-log-monitor.sh /usr/local/bin/adb-log-monitor
+```
+
+---
+
+## Usage
+
+Basic usage:
+
+```bash
+./adb-log-monitor.sh
+```
+
+This will:
+
+* Detect the connected device
+* Wait for the app to start
+* Start logging when the process becomes available
+* Write logs into `logs/`
+
+---
+
+## CLI Options
+
+```
+-p PACKAGE       Android package name (default: ir.avaair.avaair)
+-a APP_NAME      Friendly name for log filenames (default: derived from package)
+-d DEVICE        adb device ID (serial). If omitted: auto-detect
+-o DIR           Output directory for logs (default: logs)
+-f FILTER        Logcat filter (default: "*:V")
+--no-restart     Do NOT restart the app automatically
+--help           Show usage
+```
+
+You may also pass filters as positional args:
+
+```bash
+./adb-log-monitor.sh *:E
+```
+
+---
+
+## Examples
+
+### Log all messages for default package
+
+```bash
+./adb-log-monitor.sh
+```
+
+### Log only errors
+
+```bash
+./adb-log-monitor.sh -f "*:E"
+```
+
+### Specify a different package
+
+```bash
+./adb-log-monitor.sh -p com.example.myapp
+```
+
+### Target a specific device
+
+```bash
+./adb-log-monitor.sh -d emulator-5554
+```
+
+### Disable auto-restart behavior
+
+```bash
+./adb-log-monitor.sh --no-restart
+```
+
+### Save logs into a custom directory
+
+```bash
+./adb-log-monitor.sh -o /tmp/mylogs
+```
+
+---
+
+## Log Output
+
+Each log session is written to:
+
+```
+logs/<app_name>_YYYY-MM-DD_HH-MM-SS_pid_<pid>.log
+```
+
+Example:
+
+```
+logs/avaair_2025-01-14_11-07-22_pid_1234.log
+```
+
+---
+
+## Behavior Summary
+
+* If the app is **not running**, the script waits indefinitely.
+* When the process **starts**, logging begins immediately.
+* If the process **restarts**, logging restarts seamlessly.
+* On **Ctrl+C**, the script kills the background logcat and exits cleanly.
+
+---
+
+## Suggested `.gitignore`
+
+```
+logs/
+```
+
+This keeps your repo clean and prevents accidental log uploads.
+
+---
+
+## Troubleshooting
+
+### "Device unauthorized"
+
+Accept the ADB RSA prompt on your device.
+
+### “Device offline”
+
+Restart:
+
+```bash
+adb kill-server
+adb start-server
+```
+
+### No logs generated
+
+Ensure the package name is correct:
+
+```bash
+adb shell pm list packages | grep <keyword>
+```
+
+---
+
+## License
+
+MIT License — feel free to modify and extend.