feat: enhance folder listing functionality with prefix support

[Kaiohz]

Summary

• Add prefix parameter to list_folders (MCP tool + REST route + use case + adapter) for hierarchical folder navigation in MinIO
• Fix read_file MCP tool: replace silent error responses (returning FileContentResponse with error content) with proper ToolError exceptions so MCP reports isError: true
• Add _validate_prefix to reject path traversal (..) and absolute paths in both MCP tools (list_files, list_folders) and REST routes (/files/list, /files/folders)
• Add list_folders MCP tool (was missing from the tools registered with FastMCP)

Changes

Layer	File	Change
Domain	storage_port.py	Add prefix param to list_folders
Infra	minio_adapter.py	Forward prefix to MinIO client
Use case	list_folders_use_case.py	Add prefix param
REST	file_routes.py	Add _validate_prefix + prefix validation on list_files & list_folders
MCP	mcp_file_tools.py	Add _validate_prefix, list_folders tool, ToolError for read_file
Tests	test_mcp_file_tools.py	Tests for ToolError, _validate_prefix, list_folders
Tests	test_file_routes.py	Tests for prefix validation on list_files & list_folders
Tests	test_list_folders_use_case.py	Test with prefix
Tests	test_minio_adapter.py	Test list_folders with prefix

[Kaiohz]

🟡 Review: Enhance folder listing with prefix support — Score 6/10

✅ Points positifs

1. Feature cohérente : ajout du prefix sur list_folders permet de naviguer dans l'arborescence MinIO, ce qui manquait
2. Propagation propre : port → use case → route → MCP — le paramètre traverse bien toutes les couches hexagonales
3. 6 tests ajoutés : route, use case, adapter — bonne couverture du nouveau paramètre
4. Retro-compatibilité : prefix: str = "" par défaut, ne casse pas l'existant

🔴 Points critiques

1. read_file : erreurs silencieuses — Les exceptions FileNotFoundError et Exception sont maintenant attrapées et retournées comme FileContentResponse valide (status 200). C'est un anti-pattern dangereux :

   • Le client MCP pense que le fichier a été lu avec succès
   • Pas de distinction entre un contenu réel et un message d'erreur
   • metadata.error existe mais n'est pas standardisé dans le contrat MCP
   • Un agent LLM qui appelle read_file va traiter le contenu d'erreur comme du texte réel

   Correction : Lever une ToolError MCP ou retourner un status d'erreur explicite dans le protocole MCP.

2. Pas de validation prefix — Le paramètre prefix n'est pas validé (path traversal possible avec ../). list_files a cette validation, list_folders non. Inconsistance.

⚠️ Points d'attention

1. Pas de test pour le cas read_file erreur — Le changement de comportement de read_file (exception → response) n'a aucun test unitaire
2. Pas de référence Jira dans le titre de la PR
3. Pas de description dans la PR

💡 Suggestions

• Revert le changement sur read_file ou utiliser MCP ToolError au lieu de retourner un faux contenu
• Ajouter validate_prefix sur list_folders (comme list_files le fait pour file_path)
• Ajouter des tests pour le comportement d'erreur de read_file
• Ajouter description + référence Jira

---

Review by SoluBot 🤖

[Kaiohz]

🟢 Re-Review: Enhance folder listing with prefix support — Score 9/10

✅ Corrections apportées depuis la dernière review

1. read_file erreurs : ToolError au lieu de faux contenu 200 ✅ — Les erreurs sont maintenant correctement propagées via ToolError (FastMCP), pas de faux FileContentResponse. Un agent LLM verra une erreur, pas du texte factice.

2. Validation prefix ajoutée ✅ — _validate_prefix() avec :

   • posixpath.normpath + backslash normalization
   • Path traversal rejeté (../../etc → 422/ToolError)
   • Absolute path rejeté (/etc/passwd → 422/ToolError)
   • Trailing slash préservé après normpath
   • Utilisée sur les 3 endpoints : list_files, list_folders, et l'outil MCP list_folders

3. list_folders ajouté comme outil MCP ✅ — mcp_file_tools.py expose maintenant list_folders en plus de list_files et read_file

4. Tests complets ✅ :

   • TestValidatePrefix : 7 tests (vide, valide, trailing slash, backslash, dot, traversal, absolu)
   • TestListFiles : 2 nouveaux tests (traversal, absolu)
   • TestListFolders : 4 tests (retour, prefix forwarding, traversal, absolu)
   • TestReadFile : mis à jour ValueError → ToolError, RuntimeError → ToolError
   • Route tests : 4 nouveaux (traversal + absolu pour list_files et list_folders)
   • MinioAdapter : 1 nouveau (prefix forwarding)

⚠️ Points d'attention mineurs

1. Duplication _validate_prefix — La fonction existe en 2 copies : file_routes.py et mcp_file_tools.py. La version routes lève HTTPException(422), la version MCP lève ToolError. Même logique, différentes exceptions. Pourrait être un shared util avec un param raise_fn ou une factory.

2. Pas de test pour _validate_prefix dans file_routes.py — Les tests de validation de prefix en routes testent directement les endpoints, pas la fonction isolée. OK mais moins granulaire que le test MCP.

📋 Bilan

Tous les points critiques de la première review ont été corrigés. Code solide, bien testé, architecture hexagonale respectée. La validation de prefix est robustesse et cohérente.

Score : 5/10 → 9/10 👍

---

Re-review by SoluBot 🤖