# Feature Specification: Android FS5 Device Management

**Feature Branch**: `001-android-fs5-management`
**Created**: 2026-03-02
**Status**: Draft
**Device**: exone GmbH FS5 (Serial: RD51QE202392, Android 9)

---

## Overview

A CLI toolset for managing the exone GmbH FS5 Android device connected via USB/ADB.
Enables infrastructure operators to inspect device state, transfer files, manage apps,
and automate device operations from the command line on Manjaro Linux.

---

## User Scenarios & Testing

### User Story 1 — Device Status & Health Check (Priority: P1)

**Why this priority**: Operators need to verify device connectivity and health before
any operation. This is the entry point for all other workflows.

**Independent Test**: Run `./fs5 status` with device connected → shows device info.
Run with device disconnected → exits with code 2 and clear error message.

**Acceptance Scenarios**:

1. **Given** the FS5 is connected via USB, **When** I run `./fs5 status`,
   **Then** I see device model, Android version, serial, battery level, storage usage,
   and ADB connection state.

2. **Given** no device is connected, **When** I run `./fs5 status`,
   **Then** the tool exits with code 2 and prints "Device not found: RD51QE202392".

3. **Given** the FS5 is connected, **When** I run `./fs5 status --json`,
   **Then** I receive a valid JSON object with all device properties.

---

### User Story 2 — File Transfer (Push/Pull) (Priority: P1)

**Why this priority**: File transfer is the most common daily operation for device management.

**Independent Test**: Push a test file to `/sdcard/test/` → verify it exists on device.
Pull it back → verify local copy matches original.

**Acceptance Scenarios**:

1. **Given** a local file exists, **When** I run `./fs5 push <local-path> <device-path>`,
   **Then** the file is transferred to the device and a success message with file size is shown.

2. **Given** a file exists on the device, **When** I run `./fs5 pull <device-path> <local-path>`,
   **Then** the file is downloaded locally and a success message with file size is shown.

3. **Given** the destination already contains the file, **When** I run `./fs5 push` without `--force`,
   **Then** the operation is skipped with a warning "File exists, use --force to overwrite".

4. **Given** a directory path, **When** I run `./fs5 push <local-dir>/ <device-dir>/`,
   **Then** all files in the directory are transferred recursively.

---

### User Story 3 — App Management (Priority: P2)

**Why this priority**: Installing, listing, and removing APKs is a frequent maintenance task.

**Independent Test**: List installed packages → verify output contains known system apps.

**Acceptance Scenarios**:

1. **Given** an APK file, **When** I run `./fs5 app install <apk-path>`,
   **Then** the app is installed and the package name is confirmed in output.

2. **Given** an installed package, **When** I run `./fs5 app uninstall <package-name>`,
   **Then** the app is removed and exit code is 0.

3. **When** I run `./fs5 app list`,
   **Then** I see all installed non-system packages with their version codes.

4. **When** I run `./fs5 app list --all`,
   **Then** I see all packages including system apps.

---

### User Story 4 — Shell Command Execution (Priority: P2)

**Why this priority**: Enables ad-hoc device inspection and scripted automation.

**Independent Test**: Run `./fs5 shell "echo hello"` → output is "hello".

**Acceptance Scenarios**:

1. **Given** a shell command, **When** I run `./fs5 shell "<command>"`,
   **Then** the command executes on the device and stdout/stderr are forwarded.

2. **Given** a multi-line script, **When** I pipe it via `cat script.sh | ./fs5 shell`,
   **Then** the script executes on the device.

---

### User Story 5 — Log Capture (Priority: P3)

**Why this priority**: Debugging device issues requires access to Android logcat.

**Independent Test**: Run `./fs5 logs --lines 10` → outputs exactly 10 log lines.

**Acceptance Scenarios**:

1. **When** I run `./fs5 logs`,
   **Then** logcat output streams to stdout until Ctrl+C.

2. **When** I run `./fs5 logs --lines <N>`,
   **Then** the last N log lines are printed and the command exits.

3. **When** I run `./fs5 logs --filter <tag>`,
   **Then** only log lines matching the tag are shown.

4. **When** I run `./fs5 logs --output <file>`,
   **Then** logs are written to the specified file.

---

## Requirements

### Functional Requirements

- **FR-001**: System MUST detect and validate device connectivity before every operation.
- **FR-002**: System MUST support `--json` output on all commands.
- **FR-003**: System MUST use device serial `RD51QE202392` from configuration, not hardcoded.
- **FR-004**: System MUST log all write/mutating operations to a local log file with timestamps.
- **FR-005**: System MUST require `--force` flag for any destructive operation.
- **FR-006**: System MUST exit with code 2 when device is not found.
- **FR-007**: System MUST provide `--help` on all commands and subcommands.
- **FR-008**: System MUST be idempotent — re-running any command must not cause errors.

### Non-Functional Requirements

- **NFR-001**: Device status check MUST complete in < 3 seconds.
- **NFR-002**: File transfer MUST show progress for files > 1MB.
- **NFR-003**: All scripts MUST pass ShellCheck with zero warnings.
- **NFR-004**: Tool MUST work on Manjaro Linux with ADB 1.0.41+.
- **NFR-005**: No root access required on the device.

### Key Entities

- **Device**: The exone FS5 identified by serial number, with properties (model, OS, battery, storage).
- **Operation**: A command executed against the device (push, pull, install, shell, logs).
- **Config**: Project-level settings file (`.env`) storing device serial and default paths.
- **Log Entry**: Timestamped record of every mutating operation performed.

---

## Success Criteria

- **SC-001**: All 5 user stories have passing acceptance tests.
- **SC-002**: `./fs5 status` returns device info in < 3 seconds.
- **SC-003**: File push/pull operations are idempotent (safe to re-run).
- **SC-004**: Zero ShellCheck warnings across all scripts.
- **SC-005**: `--json` flag produces valid JSON on all commands.
- **SC-006**: Tool works correctly when device is disconnected (graceful error, exit code 2).
- **SC-007**: All destructive operations require explicit confirmation flag.

---

## Out of Scope

- GUI or web interface
- Wireless ADB (WiFi) setup automation
- Device rooting or system partition access
- Multi-device simultaneous management (future)
- Android backup/restore via `adb backup` (deprecated in Android 9+)