Metadata-Version: 2.4
Name: kod8-cli
Version: 0.2.0
Summary: KOD8 Command Line Interface for local testing
Home-page: https://github.com/Rodrigue-k/kod8
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: rich
Requires-Dist: keyring
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# KOD8 CLI

Tester des exercices à fichier unique en local, puis envoyer leur code au correcteur KOD8. Les tests locaux ne valident pas la progression.

## Installation locale

```bash
cd cli
pip install -e .
```

Se connecter sur KOD8, ouvrir `/formations/python/soumissions`, créer un jeton personnel et le fournir dans `KOD8_TOKEN`. Ne jamais le committer. `KOD8_API_URL` vaut `https://kod8.live/api/cli` ; en développement : `http://localhost:5173/api/cli`.

---

## Utilisation quotidienne

### 1. Tester son code en local (sans impacter sa note)

Créez le fichier imposé par l’énoncé (par exemple `contact.py`). L’installation et la connexion se font une seule fois dans le guide d’installation, avec `kod8 login`. La CLI conserve le jeton dans le coffre système ; Codespaces peut utiliser le secret `KOD8_TOKEN`. Vérifier la version avec `kod8 --version`.

Utilisez directement le nom de l’exercice, sans extension :

```bash
kod8 test contact
```

*Ou si vous êtes directement dans le sous-dossier de l'exercice :*
```bash
kod8 test
```

L’outil exécute les tests publics disponibles sur votre ordinateur. Une grille absente ne permet pas de conclure à une réussite.

---

### 2. Valider et enregistrer officiellement sa progression

Quand tout est vert, vous soumettez votre solution en une seule commande :

```bash
kod8 submit contact
```

La commande relance les tests publics. Après réussite, elle crée un commit horodaté pour le seul fichier de l’exercice, pousse le commit, puis soumet le code pour votre compte. Seuls des tests serveur réussis valident l’exercice. Un fichier inchangé ne crée pas de commit supplémentaire. `--retry` crée une nouvelle tentative après une erreur technique ; `--no-push` est réservé aux intégrations techniques.

Codes de sortie : 0 réussite, 1 échec, 2 revue nécessaire, 3 erreur technique, 4 correction en cours. Les projets et exercices à plusieurs fichiers, à fichiers produits, d’environnement ou d’API se déposent sur leur page avec le dépôt et les preuves ; ils ne sont pas validés par un simple main.py.

Pour GitHub Actions, copier `examples/github-actions.yml` dans `.github/workflows/kod8.yml` et `examples/ci_submit.py` dans `.github/scripts/ci_submit.py` du dépôt apprenant. Ajouter le secret `KOD8_TOKEN` et la variable `KOD8_API_URL` si nécessaire. Le helper soumet les scripts nommés reconnus par le catalogue et conserve la compatibilité avec `python/m*/ex*/main.py` ; il n’exécute pas le code apprenant dans la CI. Ne pas appliquer ce workflow aux activités qui demandent un livrable en revue.

Le catalogue canonique est `lib/course-content/exercise-contracts.json`. Sa copie embarquée dans la CLI est `kod8/exercises.json`. Régénérer avec `python scripts/build-exercise-contracts.py`, puis produire l’archive téléchargeable avec `python scripts/package-cli.py`. Le paquet n’est pas confirmé publié sur PyPI.
