foundry_mcp/filesystem/
mod.rs

1//! File system operations and directory management
2//!
3//! This module provides safe, atomic file system operations for the Project Manager MCP server.
4//! It handles project directory structure creation, file read/write operations with backup support,
5//! and path management with proper validation.
6//!
7//! # Key Features
8//!
9//! * **Atomic file writes** - Uses temporary files and atomic moves to prevent corruption
10//! * **Automatic backups** - Creates backups before overwriting existing files
11//! * **Directory management** - Creates and manages the standard project structure
12//! * **Path validation** - Prevents directory traversal and ensures safe file operations
13//! * **Error handling** - Comprehensive error reporting for file system issues
14//!
15//! # Directory Structure
16//!
17//! The file system manager creates and maintains this directory structure:
18//!
19//! ```text
20//! ~/.foundry/               # Base directory
21//! ├── project-1/                        # Project directory
22//! │   ├── project/                      # Project metadata
23//! │   │   ├── metadata.json            # Project information
24//! │   │   ├── tech-stack.md            # Technology stack
25//! │   │   └── vision.md                # Business vision
26//! │   └── specs/                        # Specifications directory
27//! │       ├── 20240115_auth/           # Individual specification
28//! │       │   ├── metadata.json        # Spec metadata
29//! │       │   ├── spec.md              # Specification content
30//! │       │   ├── task-list.md         # Implementation tasks
31//! │       │   └── notes.md             # Development notes
32//! │       └── 20240116_api/            # Another specification
33//! │           └── ...
34//! └── project-2/                        # Another project
35//!     └── ...
36//! ```
37//!
38//! # Usage
39//!
40//! ```rust
41//! use project_manager_mcp::filesystem::FileSystemManager;
42//! use std::path::Path;
43//!
44//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
45//! // Create a file system manager
46//! let fs_manager = FileSystemManager::new()?;
47//!
48//! // Create project structure
49//! fs_manager.create_project_structure("my-project")?;
50//!
51//! // Write a file safely
52//! let file_path = fs_manager.project_dir("my-project").join("README.md");
53//! fs_manager.write_file_safe(&file_path, "# My Project\n\nProject description.")?;
54//!
55//! // Read the file
56//! let content = fs_manager.read_file(&file_path)?;
57//! println!("File content: {}", content);
58//!
59//! // Check if project exists
60//! if fs_manager.project_exists("my-project") {
61//!     println!("Project exists!");
62//! }
63//!
64//! // List all projects
65//! let projects = fs_manager.list_projects()?;
66//! for project in projects {
67//!     println!("Found project: {}", project);
68//! }
69//! # Ok(())
70//! # }
71//! ```
72//!
73//! # Safety and Reliability
74//!
75//! The file system manager prioritizes data safety through:
76//!
77//! * **Atomic writes** - Files are written to temporary locations then moved atomically
78//! * **Backup creation** - Existing files are backed up before being overwritten
79//! * **Error recovery** - Failed operations can be rolled back using backups
80//! * **Path validation** - All paths are validated to prevent directory traversal
81//! * **Unicode support** - Handles international file names and content correctly
82
83pub mod manager;
84
85pub use manager::FileSystemManager;
foundry_mcp/filesystem/mod.rs

foundry_mcp/filesystem/
mod.rs
