seedPass/dev-plan.md

SeedPass Road-to-1.0 — Detailed Development Plan

(Assumes today = 1 July 2025, team of 1-3 devs, weekly release cadence)

Phase	Goal	Key Deliverables	Target Window
0 – Vision Lock-in	Be explicit about where you’re going so every later trade-off is easy.	• 2-page “north-star” doc covering product scope, security promises, platforms, and “CLI is source of truth” principle. • Public roadmap Kanban board.	Week 0
1 – Package-ready Codebase	Turn loose src/ tree into a pip-installable library + console script.	• pyproject.toml with PEP-621 metadata, setuptools-scm dynamic version. • Restructure to seedpass/ (or keep src/ but list packages = ["seedpass"]). • Entry-point: seedpass = "seedpass.main:cli". • Dev extras: pytest-cov, ruff, mypy, pre-commit. • Split pure business logic from I/O (e.g., encryption, BIP-85, vault ops) so GUI can reuse.	Weeks 0-2
2 – Local Quality Net	Fail fast before CI runs.	• make test / tox quick matrix (3.10–3.12). • 90 % line coverage gate. • Static checks in pre-commit (black, ruff, mypy).	Weeks 1-3
3 – CI / Release Automation	One Git tag → everything ships.	• GitHub Actions matrix (Ubuntu, macOS, Windows). • Steps: install → unit tests → build wheels (python -m build) → PyInstaller one-file artefacts → upload to Release. • Secrets for PyPI / code-signing left empty until 1.0.	Weeks 2-4
4 – OS-Native Packages	Users can “apt install / brew install / flatpak install / download .exe”.	Linux • stdeb → .deb, reprepro mini-APT repo. Flatpak • YAML manifest + GitHub Action to build & push to Flathub beta repo. Windows • PyInstaller --onefile → NSIS installer. macOS • Briefcase → notarised .pkg or .dmg (signing cert later).	Weeks 4-8
5 – Experimental GUI Track	Ship a GUI without slowing CLI velocity.	• Decide stack (recommend Textual first; upgrade later to Toga or PySide). • Create seedpass.gui package calling existing APIs; flag with --gui. • Feature flag via env var SEEDPASS_GUI=1 or CLI switch. • Separate workflow that builds GUI artefacts, but does not block CLI releases.	Weeks 6-12 (parallel)
6 – Plugin / Extensibility Layer	Keep core slim while allowing future features.	• Define entry_points={"seedpass.plugins": …}. • Document simple example plugin (e.g., custom password rule). • Load plugins lazily to avoid startup cost.	Weeks 10-14
7 – Security & Hardening	Turn security assumptions into guarantees before 1.0	• SAST scan (Bandit, Semgrep). • Threat-model doc: key-storage, BIP-85 determinism, Nostr backup flow. • Repro-build check for PyInstaller artefacts. • Signed releases (Sigstore, minisign).	Weeks 12-16
8 – 1.0 Launch Prep	Final polish + docs.	• User manual (MkDocs, docs.seedpass.org). • In-app --check-update hitting GitHub API. • Blog post & template release notes.	Weeks 16-18

---

Ongoing Practices to Keep Development Nimble

Practice	What to do
Dynamic versioning	Keep version dynamic via setuptools-scm / hatch-vcs; tag and push – nothing else.
Trunk-based dev	Short-lived branches, PRs < 300 LOC; merge when tests pass.
Feature flags	seedpass.config.is_enabled("X") so unfinished work can ship dark.
Fast feedback loops	Local editable install; invoke run --watch (or uvicorn --reload for GUI) to hot-reload.
Weekly beta release	Even during heavy GUI work, cut “beta” tags weekly; real users shake out regressions early.

---

First 2-Week Sprint (Concrete To-Dos)

1. Bootstrap packaging

   pip install --upgrade pip build setuptools_scm
   poetry init   # if you prefer Poetry, else stick with setuptools
   

   Add pyproject.toml, move code to seedpass/.

2. Console entry-point In seedpass/__main__.py add from .main import cli; cli().

3. Editable dev install pip install -e .[dev] → run seedpass --help.

4. Set up pre-commit pre-commit install with ruff + black + mypy hooks.

5. GitHub Action skeleton (.github/workflows/ci.yml)

   jobs:
     test:
       strategy:
         matrix: os: [ubuntu-latest, windows-latest, macos-latest]
         python-version: ['3.12', '3.11']
       steps:
         - uses: actions/checkout@v4
         - uses: actions/setup-python@v5
           with: {python-version: ${{ matrix.python-version }}}
         - run: pip install --upgrade pip
         - run: pip install -e .[dev]
         - run: pytest -n auto
   

6. Smoke PyInstaller locally pyinstaller --onefile seedpass/main.py – fix missing data/hooks; check binary runs.

When that’s green, cut tag v0.1.0-beta and let CI build artefacts automatically.

---

Choosing the GUI Path (decision by Week 6)

If you value…	Choose
Terminal-first UX, live coding	Textual (Rich-TUI)
Native look, single code base	Toga / Briefcase
Advanced widgets, designer tooling	PySide-6 / Qt for Python

Prototype one screen (vault list + “Add” dialog) and benchmark bundle size + startup time with PyInstaller before committing.

---

Recap

• Packaging & CI first – lets every future feature ride an established release train.
• GUI lives in its own layer – CLI stays stable; dev cycles remain quick.
• Security & signing land after functionality is stable, before v1.0 marketing push.

Follow the phase table, keep weekly betas flowing, and you’ll reach a polished, installer-ready, GUI-enhanced 1.0 in roughly four months without sacrificing day-to-day agility.