From 4e72ddc32ffdb5fdeb8a0a8a66c855196642c477 Mon Sep 17 00:00:00 2001 From: sylvain Date: Tue, 10 Mar 2026 18:21:33 +0100 Subject: [PATCH] chore: init project structure Discovery synthesis, docs tree, Python src layout, CLAUDE.md, pyproject.toml. Co-Authored-By: Claude Opus 4.6 --- .gitignore | 15 ++++++++++ CLAUDE.md | 49 +++++++++++++++++++++++++++++++ README.md | 22 +++++++++++++- docs/README.md | 48 +++++++++++++++++++++++++++++++ docs/discovery/synthesis.md | 51 +++++++++++++++++++++++++++++++++ docs/project/demandes.md | 23 +++++++++++++++ docs/project/descriptif.md | 50 ++++++++++++++++++++++++++++++++ docs/technical/ARCHITECTURE.md | 5 ++++ docs/technical/decisions.md | 18 ++++++++++++ docs/technical/research.md | 5 ++++ pyproject.toml | 32 +++++++++++++++++++++ src/gitea_dashboard/__init__.py | 1 + src/gitea_dashboard/cli.py | 6 ++++ tests/__init__.py | 0 14 files changed, 324 insertions(+), 1 deletion(-) create mode 100644 .gitignore create mode 100644 CLAUDE.md create mode 100644 docs/README.md create mode 100644 docs/discovery/synthesis.md create mode 100644 docs/project/demandes.md create mode 100644 docs/project/descriptif.md create mode 100644 docs/technical/ARCHITECTURE.md create mode 100644 docs/technical/decisions.md create mode 100644 docs/technical/research.md create mode 100644 pyproject.toml create mode 100644 src/gitea_dashboard/__init__.py create mode 100644 src/gitea_dashboard/cli.py create mode 100644 tests/__init__.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..1dc7ad3 --- /dev/null +++ b/.gitignore @@ -0,0 +1,15 @@ +__pycache__/ +*.py[cod] +*$py.class +*.egg-info/ +dist/ +build/ +.eggs/ +*.egg +.venv/ +venv/ +.env +.pytest_cache/ +.ruff_cache/ +.coverage +htmlcov/ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..16185eb --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,49 @@ +# gitea-dashboard + +Dashboard CLI Python affichant l'etat des repos Gitea (issues, releases, milestones). + +## Stack + +- **Langage** : Python 3.x +- **Dependances** : requests, rich +- **API** : Gitea REST v1 +- **Instance** : http://192.168.0.106:3000 + +## Principes + +1. **Lecture seule** — le dashboard ne modifie jamais de donnees Gitea +2. **Configuration externalisee** — token et URL en variables d'environnement, jamais dans le code +3. **Separation des responsabilites** — client API / formatage / point d'entree distincts +4. **Gestion gracieuse** — un repo sans release ou milestone ne casse pas l'affichage + +## Points d'attention + +- Ne jamais committer de token ou secret +- Gerer la pagination API Gitea (reponses potentiellement tronquees) +- Tester avec des repos sans release et sans milestone +- L'API Gitea peut varier selon la version — tester sur l'instance reelle + +## Commandes + +```bash +# Installation +pip install -e . + +# Execution +gitea-dashboard +# ou +python -m gitea_dashboard + +# Tests +pytest + +# Lint +ruff check src/ tests/ +``` + +## Variables d'environnement + +| Variable | Description | Defaut | +|----------|-------------|--------| +| `GITEA_URL` | URL de l'instance Gitea | http://192.168.0.106:3000 | +| `GITEA_TOKEN` | Token API Gitea | (requis) | diff --git a/README.md b/README.md index 45fbdda..7ff1b7a 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,23 @@ # gitea-dashboard -CLI Python dashboard for Gitea repos status (issues, releases, milestones) \ No newline at end of file +Dashboard CLI affichant l'etat des repos Gitea : issues ouvertes, dernieres releases, milestones. + +## Installation + +```bash +pip install -e . +``` + +## Configuration + +Variables d'environnement requises : voir `CLAUDE.md` (section "Variables d'environnement"). + +## Usage + +```bash +gitea-dashboard +``` + +## Licence + +Usage personnel. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..698b42c --- /dev/null +++ b/docs/README.md @@ -0,0 +1,48 @@ + + +# Documentation — gitea-dashboard + +## Structure + +``` +docs/ +├── project/ # Pilotage projet +│ ├── descriptif.md # Brief initial (etape 3) +│ └── demandes.md # Inbox features (/workflow demande) +├── technical/ # Architecture et decisions +│ ├── ARCHITECTURE.md # Architecture technique (etape 6, architect) +│ ├── decisions.md # ADR (Architecture Decision Records) +│ └── research.md # Resultats de recherche (etape 4, researcher) +├── discovery/ # Livrables discovery (etape 1, majeur uniquement) +│ └── synthesis.md # Synthese d'interview +├── plans/ # Plans de version (etape 6) +│ └── vX.Y.Z-plan.md # Un plan par version (architect) +├── guides/ # Documentation utilisateur (optionnel) +│ └── [sujet].md # deployment.md, api-usage.md, getting-started.md +├── dev/ # Notes de developpement (optionnel) +│ └── [sujet].md # setup.md, conventions.md, troubleshooting.md +└── README.md # Ce fichier +``` + +## Conventions + +- **MAJUSCULES.md** : documents officiels et de pilotage (ARCHITECTURE, CHANGELOG) +- **minuscules.md** : documents de travail et notes (descriptif, demandes, research, decisions) +- **Nommage fichiers** : minuscules, tirets pour separer les mots (deployment.md, api-usage.md) +- Les dossiers `guides/` et `dev/` sont crees quand le besoin apparait +- Chaque document a un emplacement unique — pas de doc ailleurs que dans cette arborescence +- **Roadmap** : Gitea milestones (pas de ROADMAP.md local) +- **Backlog** : Gitea issues avec label `backlog` (pas de BACKLOG.md local) + +## Ou mettre ma doc ? + +| Type de doc | Ou | +|-------------|-----| +| Guide utilisateur (install, usage, config) | `guides/` | +| Notes dev (setup, conventions, debug) | `dev/` | +| Architecture, ADR, recherche | `technical/` | +| Brief, demandes | `project/` | +| Plan de version | `plans/` | +| Synthese discovery | `discovery/` | +| Roadmap, jalons | Gitea milestones | +| Backlog, idees, dette technique | Gitea issues (label `backlog`) | diff --git a/docs/discovery/synthesis.md b/docs/discovery/synthesis.md new file mode 100644 index 0000000..e788755 --- /dev/null +++ b/docs/discovery/synthesis.md @@ -0,0 +1,51 @@ + + +# Discovery Synthesis — gitea-dashboard + +## Contexte + +Besoin d'un outil de supervision rapide pour l'instance Gitea personnelle. +Actuellement, il faut naviguer dans l'interface web repo par repo pour voir +l'etat des issues, releases et milestones. Un dashboard CLI permet d'avoir +une vue d'ensemble en une commande. + +## Utilisateurs cibles + +Utilisateur unique (admin de l'instance Gitea). Usage en terminal, execution +ponctuelle pour avoir un snapshot de l'etat des repos. + +## Besoins identifies + +### Fonctionnels +- Lister tous les repos de l'utilisateur +- Afficher le nombre d'issues ouvertes par repo +- Afficher la derniere release par repo (tag, date) +- Afficher l'etat des milestones (ouvertes, progression) +- Formatage terminal lisible et structure (tableaux, couleurs) + +### Non-fonctionnels +- Temps de reponse acceptable (< 10s pour une dizaine de repos) +- Code maintenable, teste, structure proprement +- Configuration externalisee (URL, token) + +## Contraintes + +- API Gitea REST a http://192.168.0.106:3000 +- Authentification par token API (variable d'environnement) +- Python 3.x avec requests et rich +- Affichage unique (pas de mode watch/refresh) +- Pas de filtre par owner/org en v1 — tous les repos + +## Decisions prises + +| Decision | Justification | +|----------|---------------| +| Python + requests | Stack simple, maitrisee, suffisante pour des appels REST | +| rich pour le formatage | Tableaux, couleurs, mise en page terminal de qualite | +| Token en variable d'env | Securite : pas de secret dans le code ou les fichiers | +| Pas de filtre en v1 | Nombre de repos limite, simplifier le scope initial | + +## Questions ouvertes + +- Pagination API : verifier si l'API Gitea pagine les resultats (a traiter en recherche step 4) +- Gestion des repos sans release ou sans milestone (affichage gracieux) diff --git a/docs/project/demandes.md b/docs/project/demandes.md new file mode 100644 index 0000000..4bff7bf --- /dev/null +++ b/docs/project/demandes.md @@ -0,0 +1,23 @@ + + +# Demandes — gitea-dashboard + +> **Note** : ce projet utilise Gitea, les issues Gitea sont la source de verite. +> Ce fichier sert de fallback. +> Utiliser `/workflow demande` pour traiter les demandes. + +## En attente de classification + +- + +## Classifiees — en attente + +- + +## Terminees + +- + +## Demandes ecosystem + +- diff --git a/docs/project/descriptif.md b/docs/project/descriptif.md new file mode 100644 index 0000000..7d25720 --- /dev/null +++ b/docs/project/descriptif.md @@ -0,0 +1,50 @@ + + +# Descriptif — gitea-dashboard + +## Contexte + +Supervision de l'instance Gitea personnelle (192.168.0.106:3000). +Pas de vue d'ensemble disponible sans naviguer repo par repo dans l'interface web. + +## Objectifs + +- Afficher en une commande l'etat de tous les repos Gitea +- Visualiser les issues ouvertes, dernieres releases et milestones +- Fournir un output terminal lisible et structure + +## Perimetre + +### Inclus + +- Connexion API Gitea avec authentification token +- Liste de tous les repos de l'utilisateur +- Nombre d'issues ouvertes par repo +- Derniere release par repo (tag + date) +- Etat des milestones (nom, progression open/closed) +- Formatage rich (tableaux, couleurs) + +### Exclus + +- Interface web ou GUI +- Mode watch / rafraichissement automatique +- Filtrage par owner/organisation +- Modification de donnees (lecture seule) +- Notifications ou alertes + +## Utilisateurs cibles + +Administrateur unique de l'instance Gitea. Usage terminal. + +## Contraintes + +- Python 3.x +- Dependances : requests, rich +- API Gitea REST v1 +- Token en variable d'environnement (GITEA_TOKEN) +- Instance locale : http://192.168.0.106:3000 + +## References + +- API Gitea : https://gitea.io/en-us/ (documentation Swagger disponible sur l'instance) +- Rich : https://rich.readthedocs.io/ diff --git a/docs/technical/ARCHITECTURE.md b/docs/technical/ARCHITECTURE.md new file mode 100644 index 0000000..6fd1065 --- /dev/null +++ b/docs/technical/ARCHITECTURE.md @@ -0,0 +1,5 @@ + + +# Architecture — gitea-dashboard + + diff --git a/docs/technical/decisions.md b/docs/technical/decisions.md new file mode 100644 index 0000000..f4a8455 --- /dev/null +++ b/docs/technical/decisions.md @@ -0,0 +1,18 @@ + + +# Architecture Decision Records — gitea-dashboard + +## ADR-001 : Stack Python + requests + rich + +**Date** : 2026-03-10 +**Statut** : accepte + +**Contexte** : Besoin d'un outil CLI de dashboard pour Gitea. Choix du langage et des librairies. + +**Decision** : Python avec requests pour les appels API et rich pour le formatage terminal. + +**Consequences** : +- Stack simple et maitrisee par l'utilisateur +- Pas de framework CLI lourd (argparse suffit si besoin) +- rich offre des tableaux et couleurs sans configuration complexe +- Dependance a requests (pas de client async, acceptable pour un affichage unique) diff --git a/docs/technical/research.md b/docs/technical/research.md new file mode 100644 index 0000000..f9cd272 --- /dev/null +++ b/docs/technical/research.md @@ -0,0 +1,5 @@ + + +# Recherche technique — gitea-dashboard + + diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..fd4804f --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,32 @@ +[build-system] +requires = ["setuptools>=68.0", "wheel"] +build-backend = "setuptools.backends._legacy:_Backend" + +[project] +name = "gitea-dashboard" +version = "0.0.0" +description = "CLI dashboard for Gitea repos status" +requires-python = ">=3.10" +dependencies = [ + "requests>=2.31", + "rich>=13.0", +] + +[project.optional-dependencies] +dev = [ + "pytest>=7.0", + "ruff>=0.4", +] + +[project.scripts] +gitea-dashboard = "gitea_dashboard.cli:main" + +[tool.setuptools.packages.find] +where = ["src"] + +[tool.pytest.ini_options] +testpaths = ["tests"] + +[tool.ruff] +src = ["src", "tests"] +line-length = 100 diff --git a/src/gitea_dashboard/__init__.py b/src/gitea_dashboard/__init__.py new file mode 100644 index 0000000..bdf0ec4 --- /dev/null +++ b/src/gitea_dashboard/__init__.py @@ -0,0 +1 @@ +"""Gitea Dashboard — CLI dashboard for Gitea repos status.""" diff --git a/src/gitea_dashboard/cli.py b/src/gitea_dashboard/cli.py new file mode 100644 index 0000000..dd0813a --- /dev/null +++ b/src/gitea_dashboard/cli.py @@ -0,0 +1,6 @@ +"""Entry point for gitea-dashboard CLI.""" + + +def main(): + """Run the dashboard.""" + pass diff --git a/tests/__init__.py b/tests/__init__.py new file mode 100644 index 0000000..e69de29