Jane Alesi
e6e5f34455
- 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)
100 lines
3.2 KiB
Markdown
100 lines
3.2 KiB
Markdown
# 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.
|