feat: add android-fs5 CLI toolset
- fs5 entrypoint with status, push, pull, app, shell, logs commands - lib/adb.sh: ADB wrapper functions with idempotency and --force guards - lib/output.sh: human + JSON output formatting via Python - 33 bats tests (6 status, 9 transfer, 7 app, 5 shell, 6 logs) — all passing - Zero shellcheck warnings - .env-based config (device serial, log path) - Spec-Driven Development artifacts in specs/001-android-fs5-management/ Device: exone GmbH FS5 (RD51QE202392, Android 9)
This commit is contained in:
@@ -0,0 +1,99 @@
|
||||
# Project Constitution: android-fs5
|
||||
|
||||
**Version**: 1.0.0
|
||||
**Created**: 2026-03-02
|
||||
**Status**: Active
|
||||
|
||||
## Preamble
|
||||
|
||||
This constitution governs all development decisions for the android-fs5 project —
|
||||
a CLI toolset for managing the exone GmbH FS5 Android 9 device connected via USB/ADB.
|
||||
These principles are NON-NEGOTIABLE and apply to every specification, plan, and task.
|
||||
|
||||
---
|
||||
|
||||
## Article I: Shell-First Principle
|
||||
|
||||
**MUST** implement all device interactions as composable shell scripts or Python CLI tools.
|
||||
**MUST NOT** build GUI applications or web interfaces unless explicitly requested.
|
||||
|
||||
**Rationale**: Infrastructure tooling must be scriptable, automatable, and CI/CD-friendly.
|
||||
|
||||
---
|
||||
|
||||
## Article II: ADB as the Single Interface
|
||||
|
||||
**MUST** use ADB (Android Debug Bridge) as the exclusive communication layer with the device.
|
||||
**MUST NOT** require rooted device access for core functionality.
|
||||
**SHOULD** gracefully degrade when optional ADB features are unavailable.
|
||||
|
||||
**Rationale**: ADB is the standard, stable, and non-destructive interface for Android devices.
|
||||
|
||||
---
|
||||
|
||||
## Article III: Test-First Imperative (NON-NEGOTIABLE)
|
||||
|
||||
**MUST** write tests before implementation code.
|
||||
**MUST** validate tests FAIL before writing implementation.
|
||||
**MUST** validate tests PASS after implementation.
|
||||
**MUST NOT** merge implementation without passing tests.
|
||||
|
||||
**Rationale**: Device management tools can cause data loss; correctness is paramount.
|
||||
|
||||
---
|
||||
|
||||
## Article IV: Idempotency
|
||||
|
||||
**MUST** design all operations to be safely re-runnable without side effects.
|
||||
**MUST** check state before mutating (e.g., file exists before push, app installed before install).
|
||||
|
||||
**Rationale**: Scripts run in automation pipelines must not fail on second execution.
|
||||
|
||||
---
|
||||
|
||||
## Article V: Non-Destructive by Default
|
||||
|
||||
**MUST** default to read-only/dry-run mode for any destructive operation.
|
||||
**MUST** require explicit `--force` or `--confirm` flags for delete/wipe operations.
|
||||
**MUST** log all write operations with timestamps.
|
||||
|
||||
**Rationale**: Prevent accidental data loss on the connected device.
|
||||
|
||||
---
|
||||
|
||||
## Article VI: Device Identity Awareness
|
||||
|
||||
**MUST** target device by serial number (`RD51QE202392`) to prevent wrong-device operations.
|
||||
**MUST** validate device connectivity before any operation.
|
||||
**SHOULD** support multiple device profiles via configuration.
|
||||
|
||||
**Rationale**: ADB can connect to multiple devices; explicit targeting prevents mistakes.
|
||||
|
||||
---
|
||||
|
||||
## Article VII: Simplicity Gate
|
||||
|
||||
**MUST** use ≤3 top-level modules/scripts for the initial implementation.
|
||||
**MUST NOT** add abstraction layers without documented justification.
|
||||
**MUST NOT** future-proof beyond current requirements.
|
||||
|
||||
**Rationale**: Infrastructure tools rot when over-engineered.
|
||||
|
||||
---
|
||||
|
||||
## Article VIII: Structured Output
|
||||
|
||||
**MUST** support `--json` output flag on all commands for machine-readable results.
|
||||
**MUST** use exit codes correctly (0=success, 1=error, 2=device-not-found).
|
||||
**SHOULD** provide human-readable output by default.
|
||||
|
||||
**Rationale**: Tools must integrate with monitoring, logging, and automation pipelines.
|
||||
|
||||
---
|
||||
|
||||
## Article IX: Configuration over Hardcoding
|
||||
|
||||
**MUST** store device serial, paths, and settings in a `.env` or `config.yaml` file.
|
||||
**MUST NOT** hardcode device serials or paths in script logic.
|
||||
|
||||
**Rationale**: Enables reuse across different devices and environments.
|
||||
Reference in New Issue
Block a user