# Plan : FileSystem Tools pour CELUNA

## 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 celuna::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 celuna::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/celuna/"
     ],
     "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/celuna --test-tool

# Test edit_file
echo '{"tool": "edit_file", "params": {"path": "/tmp/test.txt", "old_string": "foo", "new_string": "bar"}}' | ./build/celuna --test-tool
```

## Estimation

- FileSystemTools de base : ~200 lignes
- Config sécurité : ~50 lignes
- Intégration LLMService : ~30 lignes

Total : ~280 lignes de code nouveau
