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)

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

# 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)