mirror of
https://github.com/PR0M3TH3AN/SeedPass.git
synced 2025-09-08 07:18:47 +00:00
114 lines
8.7 KiB
Markdown
114 lines
8.7 KiB
Markdown
# SeedPass v2 Roadmap — CLI → Desktop GUI
|
||
|
||
> **Guiding principles**
|
||
>
|
||
> 1. **Core-first** – a headless, testable Python package (`seedpass.core`) that is 100 % GUI-agnostic.
|
||
> 2. **Thin adapters** – CLI, GUI, and future mobile layers merely call the core API.
|
||
> 3. **Stateless UI** – all persistence lives in core services; UI never touches vault files directly.
|
||
> 4. **Parity at every step** – CLI must keep working while GUI evolves.
|
||
|
||
---
|
||
|
||
## Phase 0 • Tooling Baseline
|
||
|
||
| # | Task | Rationale |
|
||
| --- | ---------------------------------------------------------------------------------------------- | --------------------------------- |
|
||
| 0.1 | ✅ **Adopt `poetry`** (or `hatch`) for builds & dependency pins. | Single-source version + lockfile. |
|
||
| 0.2 | ✅ **GitHub Actions**: lint (ruff), type-check (mypy), tests (pytest -q), coverage gate ≥ 85 %. | Prevent regressions. |
|
||
| 0.3 | ✅ Pre-commit hooks: ruff –fix, black, isort. | Uniform style. |
|
||
|
||
---
|
||
|
||
## Phase 1 • Finalize Core Refactor (CLI still primary)
|
||
|
||
> *Most of this is already drafted – here’s what must ship before GUI work starts.*
|
||
|
||
| # | Component | Must-have work |
|
||
| --- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
||
| 1.1 | **`kinds.py` registry + per-kind handler modules** | import-safe; handler signature `(data,fingerprint,**svc)` |
|
||
| 1.2 | **`StateManager`** | JSON file w/ fcntl lock<br>keys: `last_bip85_idx`, `last_sync_ts` |
|
||
| 1.3 | **Checksum inside entry metadata** | `sha256(json.dumps(data,sort_keys=True))` |
|
||
| 1.4 | **Replaceable Nostr events** (kind 31111, `d` tag = `"{kindtag}{entry_num}"`) | publish/update/delete tombstone |
|
||
| 1.5 | **Per-entry `EntryManager` / `BackupManager`** | Save / load / backup / restore individual encrypted files |
|
||
| 1.6 | **CLI rewritten with Typer** | Typer commands map 1-to-1 with core service methods; preserves colours. |
|
||
| 1.7 | **Legacy index migration command** | `seedpass migrate-legacy` – idempotent, uses `add_entry()` under the hood. |
|
||
| 1.8 | **bcrypt + NFKD master password hash** | Stored per fingerprint. |
|
||
|
||
> **Exit-criteria:** end-to-end flow (`add → list → sync → restore`) green in CI and covered by tests.
|
||
|
||
---
|
||
|
||
## Phase 2 • Core API Hardening (prep for GUI)
|
||
|
||
| # | Task | Deliverable |
|
||
| --- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
||
| 2.1 | **Public Service Layer** (`seedpass.api`) | Facade classes:<br>`VaultService`, `ProfileService`, `SyncService` – *no* CLI / UI imports. |
|
||
| 2.2 | **Thread-safe gate** | Re-entrancy locks so GUI threads can call core safely. |
|
||
| 2.3 | **Fast in-process event bus** | Simple `pubsub.py` (observer pattern) for GUI to receive progress callbacks (e.g. sync progress, long ops). |
|
||
| 2.4 | **Docstrings + pydantic models** | Typed request/response objects → eases RPC later (e.g. REST, gRPC). |
|
||
| 2.5 | **Library packaging** | `python -m pip install .` gives importable `seedpass`. |
|
||
|
||
---
|
||
|
||
## Phase 3 • Desktop GUI MVP
|
||
|
||
| # | Decision | Notes |
|
||
| --- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
||
| 3.0 | **Framework: PySide 6 (Qt 6)** | ✓ LGPL, ✓ native look, ✓ Python-first, ✓ WebEngine if needed. |
|
||
| 3.1 | **Process model** | *Same* process; GUI thread ↔ core API via signals/slots.<br>(If we outgrow this, swap to a local gRPC server later.) |
|
||
| 3.2 | **UI Skeleton (milestone “Hello Vault”)** | |
|
||
| – | `LoginWindow` | master-password prompt → opens default profile |
|
||
| – | `VaultWindow` | sidebar (Profiles, Entries, Backups) + stacked views |
|
||
| – | `EntryTableView` | QTableView bound to `VaultService.list_entries()` |
|
||
| – | `EntryEditorDialog` | Add / Edit forms – field set driven by `kinds.py` |
|
||
| – | `SyncStatusBar` | pulse animation + last-sync timestamp |
|
||
| 3.3 | **Icons / theming** | Start with Qt-built-in icons; later swap to SVG set. |
|
||
| 3.4 | **Packaging** | `PyInstaller --onefile` for Win / macOS / Linux AppImage; GitHub Actions matrix build. |
|
||
| 3.5 | **GUI E2E tests** | PyTest + pytest-qt (QtBot) smoke flows; run headless in CI (Xvfb). |
|
||
|
||
> **Stretch option:** wrap the same UI in **Tauri** later for a lighter binary (\~5 MB), reusing the core API through a local websocket RPC.
|
||
|
||
---
|
||
|
||
## Phase 4 • Unified Workflows & Coverage
|
||
|
||
| # | Task |
|
||
| --- | --------------------------------------------------------------------------------------- |
|
||
| 4.1 | Extend GitHub Actions to build GUI artifacts on every tag. |
|
||
| 4.2 | Add synthetic coverage for GUI code paths (QtBot). |
|
||
| 4.3 | Nightly job: spin up headless GUI, run `sync` against test relay, assert no exceptions. |
|
||
|
||
---
|
||
|
||
## Phase 5 • Future-Proofing (post-GUI v1)
|
||
|
||
| Idea | Sketch |
|
||
| -------------------------- | ----------------------------------------------------------------------------------------- |
|
||
| **Background daemon** | Optional `seedpassd` exposing Unix socket + JSON-RPC; both CLI & GUI become thin clients. |
|
||
| **Hardware-wallet unlock** | Replace master password with HWW + SLIP-39 share; requires PyUSB bridge. |
|
||
| **Mobile companion app** | Reuse core via BeeWare or Flutter FFI; sync over Nostr only (no local vault). |
|
||
| **End-to-end test farm** | dedicated relay docker-compose + pytest-subprocess to fake flaky relays. |
|
||
|
||
---
|
||
|
||
## Deliverables Checklist
|
||
|
||
* [ ] Core refactor merged, tests ≥ 85 % coverage
|
||
* [ ] `seedpass` installs and passes `python -m seedpass.cli --help`
|
||
* [ ] `seedpass-gui` binary opens vault, lists entries, adds & edits, syncs
|
||
* [ ] GitHub Actions builds binaries for Win/macOS/Linux on tag
|
||
* [ ] `docs/ARCHITECTURE.md` diagrams core ↔ CLI ↔ GUI layers
|
||
|
||
When the above are ✅ we can ship `v2.0.0-beta.1` and invite early desktop testers.
|
||
|
||
---
|
||
|
||
### 🔑 Key Takeaways
|
||
|
||
1. **Keep all state & crypto in the core package.**
|
||
2. **Expose a clean Python API first – GUI is “just another client.”**
|
||
3. **Checksum + replaceable Nostr events give rock-solid sync & conflict handling.**
|
||
4. **Lock files and StateManager prevent index reuse and vault corruption.**
|
||
5. **The GUI sprint starts only after Phase 1 + 2 are fully green in CI.**
|
||
|