docs: Add plan for FileSystem tools (read/write/edit)

Tools planned: read_file, write_file, edit_file, list_directory, glob_files, grep_files - Claude Code style file manipulation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-26 22:27:06 +08:00 · 2025-11-26 22:27:06 +08:00 · 92fb0b7b28
commit 92fb0b7b28
parent 1f6f95a3a0
1 changed files with 152 additions and 0 deletions
--- a/PLAN_FILESYSTEM_TOOLS.md
+++ b/PLAN_FILESYSTEM_TOOLS.md
@ -0,0 +1,152 @@
+# Plan : FileSystem Tools pour AISSIA
+
+## Objectif
+
+Ajouter des tools de manipulation de fichiers style Claude Code pour permettre à l'agent vocal de lire, écrire et modifier des fichiers.
+
+## Tools à implémenter
+
+| Tool | Paramètres | Description |
+|------|------------|-------------|
+| `read_file` | `path`, `offset?`, `limit?` | Lit un fichier (avec pagination optionnelle) |
+| `write_file` | `path`, `content` | Écrit/remplace un fichier complet |
+| `edit_file` | `path`, `old_string`, `new_string`, `replace_all?` | Remplacement exact de string |
+| `list_directory` | `path` | Liste les fichiers d'un répertoire |
+| `glob_files` | `pattern`, `path?` | Recherche par pattern glob (ex: `**/*.cpp`) |
+| `grep_files` | `pattern`, `path?`, `glob?` | Recherche regex dans les fichiers |
+
+## Architecture
+
+```
+src/shared/tools/
+├── IOBridge.hpp          # Existant
+├── InternalTools.hpp     # Existant - tools via IIO
+├── InternalTools.cpp
+├── FileSystemTools.hpp   # NOUVEAU - tools filesystem
+└── FileSystemTools.cpp
+```
+
+### Pourquoi un fichier séparé ?
+
+- Les FileSystem tools n'ont **pas besoin de IIO** (pas de communication inter-modules)
+- Exécution directe en C++ (plus rapide)
+- Séparation des responsabilités
+
+## Implémentation
+
+### FileSystemTools.hpp
+
+```cpp
+#pragma once
+#include <string>
+#include <vector>
+#include <nlohmann/json.hpp>
+
+namespace aissia::tools {
+
+struct FileSystemTools {
+    // Définitions des tools pour le LLM
+    static std::vector<nlohmann::json> getToolDefinitions();
+
+    // Exécution
+    static nlohmann::json execute(const std::string& toolName,
+                                   const nlohmann::json& params);
+
+private:
+    static nlohmann::json readFile(const nlohmann::json& params);
+    static nlohmann::json writeFile(const nlohmann::json& params);
+    static nlohmann::json editFile(const nlohmann::json& params);
+    static nlohmann::json listDirectory(const nlohmann::json& params);
+    static nlohmann::json globFiles(const nlohmann::json& params);
+    static nlohmann::json grepFiles(const nlohmann::json& params);
+};
+
+} // namespace aissia::tools
+```
+
+### Dépendances
+
+- `<filesystem>` (C++17) - pour list_directory, glob_files
+- `<regex>` - pour grep_files
+- `<fstream>` - pour read/write
+
+Pas de dépendance externe requise.
+
+## Intégration dans LLMService
+
+```cpp
+void LLMService::initializeTools() {
+    // Tools existants
+    m_internalTools = std::make_unique<InternalTools>(m_io);
+
+    // NOUVEAU: FileSystem tools
+    auto fsTools = FileSystemTools::getToolDefinitions();
+    m_allTools.insert(m_allTools.end(), fsTools.begin(), fsTools.end());
+}
+
+nlohmann::json LLMService::executeTool(const std::string& name,
+                                        const nlohmann::json& params) {
+    // FileSystem tools (direct execution)
+    if (name == "read_file" || name == "write_file" || name == "edit_file" ||
+        name == "list_directory" || name == "glob_files" || name == "grep_files") {
+        return FileSystemTools::execute(name, params);
+    }
+
+    // Internal tools (via IIO)
+    return m_internalTools->execute(name, params);
+}
+```
+
+## Sécurité
+
+### Restrictions à implémenter
+
+1. **Whitelist de répertoires** - Configurable dans `config/filesystem.json`
+   ```json
+   {
+     "allowed_paths": [
+       "/mnt/e/Users/Alexis Trouvé/Documents/Projets/",
+       "/tmp/aissia/"
+     ],
+     "blocked_patterns": [
+       "*.env",
+       "*credentials*",
+       "*.key"
+     ]
+   }
+   ```
+
+2. **Validation des chemins** - Résolution canonique pour éviter path traversal (`../`)
+
+3. **Limite de taille** - Max 1MB pour read_file, 10MB pour write_file
+
+## Étapes d'implémentation
+
+1. [ ] Créer `FileSystemTools.hpp` avec les signatures
+2. [ ] Implémenter `read_file` et `write_file`
+3. [ ] Implémenter `edit_file` (le plus complexe)
+4. [ ] Implémenter `list_directory`
+5. [ ] Implémenter `glob_files` (récursif avec pattern matching)
+6. [ ] Implémenter `grep_files`
+7. [ ] Ajouter la config de sécurité
+8. [ ] Intégrer dans LLMService
+9. [ ] Mettre à jour CMakeLists.txt
+10. [ ] Tester chaque tool
+
+## Tests
+
+```bash
+# Test read_file
+echo '{"tool": "read_file", "params": {"path": "/tmp/test.txt"}}' | ./build/aissia --test-tool
+
+# Test edit_file
+echo '{"tool": "edit_file", "params": {"path": "/tmp/test.txt", "old_string": "foo", "new_string": "bar"}}' | ./build/aissia --test-tool
+```
+
+## Estimation
+
+- FileSystemTools de base : ~200 lignes
+- Config sécurité : ~50 lignes
+- Intégration LLMService : ~30 lignes
+
+Total : ~280 lignes de code nouveau