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)
3.2 KiB
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.