MagicCode/packages/ext-claudecode/IMPLEMENTATION.md

# Implémentation du Lot 3

## Vue d'ensemble

Le lot 3 a été complètement implémenté avec trois outils avancés :
- **WebFetch** : récupération d'URLs HTTP/HTTPS
- **TodoWrite** : gestion simple des listes TODO
- **Task** : gestion hiérarchique des tâches avec priorités

## Fichiers créés

### Outils (`packages/ext-claudecode/src/tools/`)

1. **webfetch.ts** (4400 bytes)
   - Récupère le contenu d'URLs
   - Support GET/POST/PUT/DELETE/etc.
   - En-têtes personnalisés
   - Détection automatique du type de contenu (JSON, texte, binaire)
   - Timeout configurable (30s par défaut)
   - Limitation de la sortie (100 KB)
   - Permission : "ask" (confirmation requise)

2. **todowrite.ts** (8477 bytes)
   - Stockage JSON persistant
   - Actions : add, list, done, undone, block, unblock, remove, update, export-markdown
   - Statuts : todo, done, blocked
   - Export en markdown
   - Permission : "auto" (direct, sans confirmation)

3. **task.ts** (9830 bytes)
   - Arborescence hiérarchique de tâches
   - Statuts : todo, in-progress, done, blocked
   - Priorités : low, normal, high, critical
   - Assignations (utilisateurs)
   - Actions : add, subtask, list, tree, status, assign, update, remove
   - Calcul automatique du statut parent basé sur les enfants
   - Permission : "auto"

### Tests (`packages/ext-claudecode/src/tools/lot3.test.ts`)

Tests complets pour les trois outils :
- **WebFetch** : 5 tests (GET simple, POST, erreurs URL, timeout)
- **TodoWrite** : 9 tests (CRUD complet, statuts, export markdown)
- **Task** : 9 tests (hiérarchies, assignations, arborescence)
- Total : 23 tests, tous passants

### Documentation

1. **LOT3.md** (5100 bytes)
   - Documentation complète des trois outils
   - Format JSON pour chaque action
   - Exemples d'utilisation
   - Affichage formaté avec symboles (✓, →, ⚠, ○)

2. **IMPLEMENTATION.md** (ce fichier)
   - Résumé des changements
   - Structure des données
   - Différences entre les outils

## Fichiers modifiés

### `packages/ext-claudecode/src/tools/index.ts`
- Ajout des imports pour webfetch, todowrite, task
- Mise à jour du commentaire de status
- Exports dans claudeCodeTools

### `README.md`
- Nouvelle section "Extension ClaudeCode : outils (lot 1 + lot 3)"
- Listage des 9 outils disponibles
- Lien vers LOT3.md
- Mise à jour du "Reste à faire"

## Architecture et patterns

### Pattern de Tool (interface TypeScript)

```typescript
export interface Tool {
  spec: {
    name: string;
    description: string;
    inputSchema: { /* JSON Schema */ };
  };
  permission: "auto" | "ask";
  describe?(input): string;
  execute(input, ctx): Promise<string>;
}
```

### Utilisation de helpers

Les trois outils utilisent les helpers de `helpers.ts` :
- `str()` : extraction de paramètre string requis
- `optStr()` : paramètre string optionnel
- `optNum()` : paramètre number optionnel
- `optBool()` : paramètre boolean optionnel
- `resolvePath()` : résolution de chemin relatif/absolu

### Stockage persistent

- **TodoWrite** : JSON simple avec versioning et lastModified
- **Task** : JSON avec arborescence récursive (id unique par timestamp pour subtasks)

### Format d'affichage

Les trois outils retournent du texte formaté lisible :
```
✓ [1] Tâche complète
→ [2] Tâche en cours
⚠ [3] Tâche bloquée
○ [4] Tâche à faire
```

## Intégration avec MagicCode

### Mode ClaudeCode

Les trois outils sont automatiquement disponibles via l'outil `Tool` du LLM :
1. Le LLM voit la liste complète des 9 outils disponibles
2. Décision autonome d'utiliser WebFetch, TodoWrite ou Task
3. Confirmation requise pour WebFetch (permission "ask")
4. Pas de confirmation pour TodoWrite/Task (permission "auto")

### Flux d'utilisation

```
[Utilisateur] → Message
  ↓
[LLM] Décide d'utiliser WebFetch/TodoWrite/Task
  ↓
[UI] Demande confirmation (WebFetch uniquement)
  ↓
[Tool] Exécute l'action
  ↓
[LLM] Reçoit le résultat et continue
  ↓
[UI] Affiche la réponse finale
```

## Cas d'usage

### WebFetch

```
"Récupère les stars de ce repo"
→ LLM : WebFetch https://api.github.com/repos/...
→ Résultat : JSON avec les données
```

### TodoWrite

```
"Ajoute une tâche 'Implémenter lot 3' à .todos.json"
→ LLM : TodoWrite action=add title=... file=...
→ Résultat : "Tâche ajoutée [1]"
```

### Task

```
"Crée un projet avec 3 sous-tâches assignées à Alice"
→ LLM : Task action=add title=... 
→ LLM : Task action=subtask parent=1 title=... assignee=alice
→ LLM : Task action=subtask parent=1 title=... assignee=alice
→ Résultat : Arborescence créée
```

## Différences entre TodoWrite et Task

| Aspect | TodoWrite | Task |
|--------|-----------|------|
| **Hiérarchie** | Aucune | Complète (parent/enfants) |
| **Priorités** | Aucune | 4 niveaux |
| **Assignations** | Aucune | Oui |
| **Statuts** | 3 (todo, done, blocked) | 4 (+ in-progress) |
| **Personne idéale** | Listes simples | Gestion de projets |
| **Complexité** | Basse | Moyenne |

## Tests et validation

```bash
# Exécuter les tests
pnpm test -- lot3

# Tests WebFetch
✓ devrait récupérer une URL valide (GET)
✓ devrait lever une erreur pour une URL invalide
✓ devrait lever une erreur pour une URL non accessible
✓ devrait supporter les requêtes POST
✓ should describe correctly

# Tests TodoWrite
✓ devrait ajouter une tâche
✓ devrait lister les tâches
✓ devrait marquer une tâche comme complète
✓ devrait bloquer une tâche
✓ devrait supprimer une tâche
✓ devrait exporter en markdown
✓ devrait mettre à jour une tâche
✓ should describe correctly

# Tests Task
✓ devrait créer une tâche
✓ devrait créer une sous-tâche
✓ devrait lister les tâches
✓ devrait afficher l'arborescence des tâches
✓ devrait mettre à jour le statut
✓ devrait assigner une tâche
✓ devrait supprimer une tâche
✓ should describe correctly
```

## Limitations actuelles

1. **WebFetch**
   - Pas de support du streaming (pour gros fichiers)
   - Pas de cache des réponses
   - Pas de retry automatique

2. **TodoWrite**
   - Pas de hiérarchie
   - Pas de dépendances entre tâches
   - Tags simples, sans recherche

3. **Task**
   - Pas de détection de dépendances circulaires
   - Pas de synchronisation avec services externes

## Reste à faire pour compléter lot 3+

- [ ] **WebFetch streaming** : support des gros fichiers
- [ ] **Task dépendances** : expliciter les relations
- [ ] **Hooks** : système de rappels (ex: on-status-change)
- [ ] **MCP** : Model Context Protocol integration
- [ ] **Sous-agents** : délégation de tâches
- [ ] **Synchronisation** : GitHub Issues, Jira, Trello
- [ ] **TodoWrite hiérarchie** : support parent/enfants
- [ ] **Cache** : persistance multi-sessions

## Performances

- **WebFetch** : timeout 30s, sortie max 100 KB
- **TodoWrite** : opérations O(n), pas de limitation
- **Task** : récursion jusqu'à profondeur ilimitée, O(n log n) pour tree

## Sécurité

- **WebFetch** : permission "ask" (confirmation avant chaque appel)
- **TodoWrite/Task** : permission "auto" (aucune confirmation)
- Chemins : résolus depuis cwd, ~ pour home
- Pas de risque d'injection (JSON Schema validation)