Metadata-Version: 2.4
Name: icd-cli
Version: 1.0.1
Summary: Intelligent Commands for Developers — Django/Python CLI
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer[all]>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: openai>=1.50.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: fpdf2>=2.7.0
Requires-Dist: questionary>=2.0.0
Dynamic: license-file

# ICD-CLI

**Intelligent Commands for Developers** — un CLI Python qui génère, documente, met à jour et diagnostique des projets backend Django, avec un pipeline IA pour la conception du schéma de données.

## Sommaire

- [Installation](#installation)
- [Configuration](#configuration)
- [`icd config`](#icd-config) — configurer la clé API
- [`icd create`](#icd-create) — créer un projet
- [`icd explain`](#icd-explain) — générer la documentation
- [`icd update`](#icd-update) — mettre à jour un projet existant
- [`icd doctor`](#icd-doctor) — diagnostiquer un projet
- [Exemple de session complète](#exemple-de-session-complète)
- [Licence](#licence)

## Installation

```bash
pip install icd-cli
```

En local, pour développer sur ICD-CLI lui-même :

```bash
git clone https://github.com/<votre-compte>/icd-cli.git
cd icd-cli
python -m venv venv
venv\Scripts\activate   # Windows — source venv/bin/activate sur macOS/Linux
pip install -e .
```

## Configuration

`icd create` (avec génération de modèles par IA) et `icd explain` nécessitent une clé [OpenRouter](https://openrouter.ai/keys) (gratuite). Trois façons de la fournir, dans cet ordre de priorité (la première trouvée gagne) :

```bash
# 1. Variable d'environnement
export OPENROUTER_API_KEY="votre_cle"
```

```yaml
# 2. ~/.icd/config.yml (configuration globale, tous vos projets — écrit par `icd config`)
openrouter_api_key: votre_cle
llm_model: dots-studio/dots-3-note-preview:free
```

```yaml
# 3. .icd/config.yml (dans un projet précis — utilisé seulement si rien n'est trouvé ci-dessus)
openrouter_api_key: votre_cle
```

`icd create` et `icd explain` vérifient la présence d'une clé **avant** de faire quoi que ce soit d'utile (pour `icd create`, dès la question "Endpoints CRUD ?") et redirigent vers `icd config` si aucune n'est trouvée — plutôt que d'échouer après vous avoir fait répondre à toutes les questions.

---

## `icd config`

Configure la clé API OpenRouter, une fois pour tous vos projets.

```bash
icd config           # saisie interactive (masquée), enregistrée dans ~/.icd/config.yml
icd config --show    # affiche l'état actuel (clé tronquée, jamais en clair)
```

---

## `icd create`

Initialise un projet Django complet, en mode interactif, dans un nouveau dossier `./<nom>/`.

```bash
icd create --name <nom_du_projet> [--keep-on-failure]
```

| Option | Effet |
| --- | --- |
| `--name`, `-n` | Nom du projet (obligatoire) — devient le nom du dossier créé. |
| `--keep-on-failure` | Si une étape échoue en cours de route, conserve le dossier partiellement créé (pour déboguer) au lieu de le supprimer automatiquement. |

Questions posées, dans l'ordre :

1. **Description du projet** (texte libre — utilisée par l'IA pour générer les modèles).
2. **Framework** : Django Ninja / Django REST Framework / Django pur.
3. **Authentification** : aucune / session Django / token DRF / JWT / OAuth2.
4. **Base de données** : SQLite / PostgreSQL / MySQL / MariaDB.
5. **Endpoints CRUD ?** (oui/non) — si oui, déclenche le pipeline IA (analyse du domaine → génération du schéma → revue architecturale), puis une revue modèle par modèle (accepter / modifier / rejeter).
6. **Docker ?** (oui/non).
7. **Monitoring Prometheus + Grafana ?** (uniquement si Docker activé).
8. **Git ?** (oui/non).
9. **CI/CD** : GitHub Actions / GitLab CI / aucun.

À la fin : environnement virtuel créé, dépendances installées, migrations générées et appliquées, `.icd/state.json` initialisé.

```bash
icd create --name blog_api
cd blog_api
venv\Scripts\activate
python manage.py runserver
```

---

## `icd explain`

Génère une documentation PDF du projet courant (nécessite d'avoir été créé par `icd create`).

```bash
icd explain [--scope <valeur>] [--format <valeur>] [--output <chemin.pdf>]
```

| Option | Valeurs possibles | Effet |
| --- | --- | --- |
| `--scope` | `architecture` (défaut), `models`, `api`, `devops`, `monitoring`, `all` | Périmètre de l'explication. Seul `monitoring` filtre réellement son contenu (analyse dédiée Prometheus/Grafana) ; les autres valeurs produisent toutes le rapport complet. |
| `--format` | `default` (défaut), `backend` | `backend` restructure le document selon un gabarit technique standard en 12 sections (aperçu, architecture, démarrage rapide, configuration, référence API, modèle de données, auth, gestion des erreurs, tests, déploiement, observabilité, changelog). Ne renvoie jamais de valeur de secret, seulement les noms des variables d'environnement. |
| `--output` | chemin de fichier | Emplacement du PDF. Par défaut : `<projet>_architecture.pdf` (`_monitoring.pdf` avec `--scope monitoring`, `_documentation.pdf` avec `--format backend`). |

```bash
icd explain --scope all
icd explain --scope monitoring
icd explain --format backend
icd explain --output doc_architecture.pdf
```

---

## `icd update`

Met à jour un projet Django existant géré par ICD, en respectant les modifications manuelles (empreinte MD5 par fichier — un fichier édité à la main n'est jamais écrasé sans confirmation).

```bash
icd update [--project] [--database <valeur>] [--auth <valeur>] [--monitoring] [--dry-run] [--force]
```

Options communes à toutes les sous-commandes :

| Option | Effet |
| --- | --- |
| `--dry-run` | Affiche les changements prévus sans rien appliquer. |
| `--force` | Régénère un fichier même s'il a été modifié manuellement (une sauvegarde est créée automatiquement dans `.icd/backups/`). |

### `icd update --project`

Analyse le code réel (AST de `models.py`) et le compare à la dernière baseline connue :

- Nouveaux modèles / modèles supprimés / champs ajoutés ou retirés.
- **Renommages probables** de modèles et de champs (similarité de champs) — confirmés automatiquement auprès de Django (vraie migration `RenameModel`/`RenameField`, données préservées) uniquement si c'est le seul changement détecté ; sinon, comportement suppression + création par sécurité.
- Conflits de migrations (fusion automatique si nécessaire).
- Nouvelles dépendances dans `requirements.txt` (met à jour le Dockerfile si des paquets système sont requis).
- Nouveaux tests détectés.

```bash
icd update --project --dry-run
icd update --project
icd update --project --force
```

### `icd update --database`

Change le moteur de base de données d'un projet existant.

```bash
icd update --database <sqlite|postgres|mysql|mariadb>
```

Régénère les settings, patch ciblé de `requirements.txt` (ajoute/retire seulement le driver concerné, désinstalle l'ancien du venv), met à jour `.env` et Docker si actif. `state.json` est sauvegardé **avant** la tentative de migration — un serveur de base de données pas encore démarré n'interrompt pas la commande dans un état incohérent. Les données existantes ne sont **pas** transférées d'un moteur à l'autre.

### `icd update --auth`

Change le mode d'authentification d'un projet existant.

```bash
icd update --auth <none|session|token|jwt|oauth2>
```

Régénère settings, `urls.py` (endpoints `/api/token/` pour JWT par exemple), `requirements.txt`, et `views.py` si DRF avec des modèles existants.

### `icd update --monitoring`

Active rétroactivement le monitoring Prometheus/Grafana sur un projet qui n'en avait pas à sa création, ou répare la configuration si des fichiers ont été supprimés. Nécessite Docker actif.

```bash
icd update --monitoring
```

---

## `icd doctor`

Analyse statique du projet courant (lecture seule — aucune modification) et rapporte des points de contrôle marqués OK, avertissement ou erreur.

```bash
icd doctor [--production] [--prometheus-url <url>]
```

| Contrôle | Portée | Vérifie |
| --- | --- | --- |
| SECRET_KEY | Tous | `.env` a-t-il encore la valeur placeholder par défaut ? |
| DEBUG (prod) | Tous | `config/settings/prod.py` a-t-il `DEBUG = False` ? |
| related_name | Tous | Chaque relation a-t-elle un `related_name` explicite ? |
| permission_classes | DRF | Chaque vue définit-elle `permission_classes` quand l'auth n'est pas `none` ? |
| Pagination | DRF | `DEFAULT_PAGINATION_CLASS` est-il configuré ? |
| docker-compose.yml | Si Docker actif | `docker compose config` valide-t-il le fichier ? |
| Migrations | Tous | Modèles synchronisés avec la dernière baseline, sans conflit ? |

Le code de sortie est non nul dès qu'un contrôle n'est pas au vert — utilisable directement dans un pipeline CI.

### `icd doctor --production`

Ajoute un contrôle qui interroge l'API Prometheus déjà configurée par ICD (nécessite le monitoring actif) :

```bash
icd doctor --production
icd doctor --production --prometheus-url http://localhost:9090
```

Signale toute vue dont la latence p95 dépasse 500 ms (même requête PromQL que le dashboard Grafana généré par ICD), et rapproche le résultat de l'avertissement statique "Pagination" si les deux coïncident sur le même projet.

---

## Exemple de session complète

```bash
icd config

icd create --name store_api

cd store_api
venv\Scripts\activate
python manage.py runserver

icd explain --scope all
icd doctor

# le développeur ajoute un modèle Review à la main dans models.py
icd update --project --dry-run
icd update --project

icd update --database postgres
icd update --auth jwt
icd update --monitoring

icd doctor --production
```

## Licence

MIT — voir [LICENSE](LICENSE).
