Filesystem Module

The Filesystem module provides comprehensive file and directory operations with advanced features like snapshot management, permission handling, and real-time monitoring. Built with safety and reliability in mind, it's perfect for managing codebases, configuration files, and data storage.

Overview

The Filesystem module includes 13 powerful tools for complete file system control:

• Basic Operations: Read, write, create, delete, move, copy
• Advanced Features: Snapshots, permissions, watching, metadata
• Search Capabilities: Pattern matching, detailed listings
• Desktop Integration: Organize desktop files automatically

Available Tools

fs_read

Read file contents, optionally reading specific line ranges.

Parameters:

• path (string, required) - Absolute or relative path to the file
• lines (array, optional) - Array of line ranges to read, e.g. [[1,10], [15,20]] reads lines 1-10 and 15-20

Example - Read Entire File:

{
  "name": "fs_read",
  "arguments": {
    "path": "/etc/hosts"
  }
}

Example - Read Specific Lines:

{
  "name": "fs_read",
  "arguments": {
    "path": "/var/log/app.log",
    "lines": [[1, 10], [50, 60]]
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": "Line 1\nLine 2\n...\nLine 10\nLine 50\n...\nLine 60",
    "size": 150,
    "path": "/var/log/app.log"
  }
}

Use Cases:

• Reading configuration files
• Loading specific sections of large log files
• Extracting function/class definitions from source code
• Reading file headers and footers without loading entire file
• Inspecting specific error ranges in logs

Notes:

• Lines are 1-indexed (first line is 1, not 0)
• Ranges are inclusive: [1,5] includes lines 1, 2, 3, 4, 5
• Multiple ranges are concatenated in order
• Without lines parameter, reads entire file

---

fs_write

Write content to files, optionally replacing specific line ranges.

Parameters:

• path (string, required) - Target file path
• content (string, required) - Content to write
• lines (array, optional) - Array of line ranges to replace, e.g. [[1,10], [15,20]]. Content is split and distributed across ranges.

Example - Write Entire File:

{
  "name": "fs_write",
  "arguments": {
    "path": "/tmp/config.json",
    "content": "{\"api_key\": \"secret\"}"
  }
}

Example - Replace Specific Lines:

{
  "name": "fs_write",
  "arguments": {
    "path": "/tmp/script.sh",
    "content": "# Updated header\n# Version 2.0",
    "lines": [[1, 2]]
  }
}

Example - Replace Multiple Ranges:

{
  "name": "fs_write",
  "arguments": {
    "path": "/etc/config.conf",
    "content": "new_setting=1\nother_setting=2\nfooter_line=end",
    "lines": [[5, 6], [20, 20]]
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "success": true,
    "path": "/tmp/config.json",
    "bytes_written": 24
  }
}

Best Practices:

• Create snapshots before overwriting important files
• Use lines parameter for surgical edits to large files
• Content lines are distributed sequentially across specified ranges
• File is automatically extended with empty lines if needed

Notes:

• Lines are 1-indexed (first line is 1)
• Ranges are inclusive: [3,5] replaces lines 3, 4, 5
• Without lines parameter, overwrites entire file
• With lines, existing file content is preserved except for specified ranges

---

fs_move

Move files or directories to a new location.

Parameters:

• source (string, required) - Source path
• destination (string, required) - Destination path
• overwrite (boolean, optional) - Overwrite if destination exists (default: false)

Example:

{
  "name": "fs_move",
  "arguments": {
    "source": "/tmp/old_name.txt",
    "destination": "/tmp/new_name.txt",
    "overwrite": false
  }
}

Important:

• Moving across filesystems may be slower (requires copy + delete)
• Moving directories moves all contents recursively
• Use overwrite: true carefully to avoid data loss

---

fs_copy

Copy files or directories recursively.

Parameters:

• source (string, required) - Source path
• destination (string, required) - Destination path
• recursive (boolean, optional) - Copy directories recursively (default: true)
• preserve_permissions (boolean, optional) - Preserve file permissions (default: true)

Example:

{
  "name": "fs_copy",
  "arguments": {
    "source": "/home/user/project",
    "destination": "/backup/project",
    "recursive": true,
    "preserve_permissions": true
  }
}

Use Cases:

• Creating backups
• Duplicating project structures
• Copying template directories
• Migrating data between locations

---

fs_create

Create new files or directories.

Parameters:

• path (string, required) - Path to create
• type (string, required) - "file" or "directory"
• parents (boolean, optional) - Create parent directories (default: false)

Example - Create Directory:

{
  "name": "fs_create",
  "arguments": {
    "path": "/tmp/my_project/src/components",
    "type": "directory",
    "parents": true
  }
}

Example - Create File:

{
  "name": "fs_create",
  "arguments": {
    "path": "/tmp/README.md",
    "type": "file"
  }
}

Notes:

• Creating a file creates an empty file (0 bytes)
• Use parents: true to create intermediate directories
• Returns error if path already exists

---

fs_delete

Delete files or directories.

Parameters:

• path (string, required) - Path to delete
• recursive (boolean, optional) - Delete directories recursively (default: false)

Example:

{
  "name": "fs_delete",
  "arguments": {
    "path": "/tmp/old_project",
    "recursive": true
  }
}

⚠️ Warning:

• Deletion is permanent - files are not moved to trash
• Use snapshots before deleting important data
• recursive: true is required for non-empty directories
• Double-check paths before deletion

---

fs_snapshot

Create timestamped backups with automatic rotation.

Parameters:

• path (string, required) - Path to snapshot
• max_snapshots (number, optional) - Maximum snapshots to keep (default: 5)
• compression (boolean, optional) - Compress snapshot (default: false)

Example:

{
  "name": "fs_snapshot",
  "arguments": {
    "path": "/important/project",
    "max_snapshots": 10,
    "compression": true
  }
}

Snapshot Format:

/important/project.snapshot.2024-01-20T15-30-45.tar.gz

Features:

• Automatic timestamp generation
• Configurable snapshot rotation
• Optional gzip compression
• Preserves all file permissions and attributes

Best Practices:

• Create snapshots before major refactoring
• Use compression for large directories
• Set appropriate max_snapshots based on disk space
• Store snapshots on different physical drive for safety

---

fs_find

Search for files using glob patterns.

Parameters:

• path (string, required) - Directory to search
• pattern (string, required) - Glob pattern (e.g., ".ts", "**/.json")
• max_depth (number, optional) - Maximum directory depth (default: unlimited)
• case_sensitive (boolean, optional) - Case-sensitive matching (default: true)

Example - Find TypeScript Files:

{
  "name": "fs_find",
  "arguments": {
    "path": "./src",
    "pattern": "**/*.{ts,tsx}",
    "max_depth": 5
  }
}

Example - Find Config Files:

{
  "name": "fs_find",
  "arguments": {
    "path": ".",
    "pattern": "*config.{json,yaml,toml}",
    "case_sensitive": false
  }
}

Pattern Syntax:

• * - Match any characters except /
• ** - Match any characters including / (recursive)
• ? - Match single character
• [abc] - Match any character in brackets
• {js,ts} - Match either extension

---

fs_ld

Detailed directory listing (like ls -la).

Parameters:

• path (string, required) - Directory path
• show_hidden (boolean, optional) - Include hidden files (default: true)
• sort_by (string, optional) - Sort by "name", "size", "modified" (default: "name")

Example:

{
  "name": "fs_ld",
  "arguments": {
    "path": "/home/user/project",
    "show_hidden": true,
    "sort_by": "modified"
  }
}

Response:

{
  "entries": [
    {
      "name": "src",
      "type": "directory",
      "size": 4096,
      "permissions": "755",
      "modified": "2024-01-20T15:30:45Z",
      "owner": "user",
      "group": "user"
    },
    {
      "name": "README.md",
      "type": "file",
      "size": 2048,
      "permissions": "644",
      "modified": "2024-01-20T14:20:30Z"
    }
  ]
}

---

fs_stat

Get detailed metadata for files or directories.

Parameters:

• path (string, required) - Path to inspect

Example:

{
  "name": "fs_stat",
  "arguments": {
    "path": "/etc/passwd"
  }
}

Response:

{
  "type": "file",
  "size": 2048,
  "permissions": "644",
  "owner": "root",
  "group": "root",
  "created": "2024-01-01T00:00:00Z",
  "modified": "2024-01-20T15:30:45Z",
  "accessed": "2024-01-20T16:00:00Z",
  "is_symlink": false,
  "is_readonly": false
}

---

fs_permissions

Get or set Unix file permissions.

Parameters:

• path (string, required) - File path
• mode (string, optional) - Permissions in octal (e.g., "755", "644")
• recursive (boolean, optional) - Apply recursively to directories (default: false)

Example - Get Permissions:

{
  "name": "fs_permissions",
  "arguments": {
    "path": "/tmp/script.sh"
  }
}

Example - Set Permissions:

{
  "name": "fs_permissions",
  "arguments": {
    "path": "/tmp/script.sh",
    "mode": "755"
  }
}

Common Permission Modes:

• 755 - Owner: rwx, Group: r-x, Others: r-x (executable scripts)
• 644 - Owner: rw-, Group: r--, Others: r-- (data files)
• 600 - Owner: rw-, Group: ---, Others: --- (private files)
• 777 - Full access for everyone (⚠️ use with caution)

---

fs_watch

Monitor file or directory changes in real-time.

Parameters:

• path (string, required) - Path to watch
• recursive (boolean, optional) - Watch subdirectories (default: false)
• events (array, optional) - Event types to monitor: ["create", "modify", "delete", "rename"]

Example:

{
  "name": "fs_watch",
  "arguments": {
    "path": "./src",
    "recursive": true,
    "events": ["modify", "create", "delete"]
  }
}

Events:

• create - New file or directory created
• modify - File content changed
• delete - File or directory removed
• rename - File or directory renamed/moved

Use Cases:

• Hot reloading during development
• Monitoring log files
• Triggering builds on file changes
• Security monitoring

---

fs_move_desktop

Organize items within Desktop directory automatically.

Parameters:

• action (string, required) - "organize_by_type" or "organize_by_date"
• dry_run (boolean, optional) - Preview changes without applying (default: false)

Example:

{
  "name": "fs_move_desktop",
  "arguments": {
    "action": "organize_by_type",
    "dry_run": true
  }
}

Organization Strategies:

By Type:

• Documents → ~/Desktop/Documents/
• Images → ~/Desktop/Images/
• Videos → ~/Desktop/Videos/
• Archives → ~/Desktop/Archives/
• Code → ~/Desktop/Code/

By Date:

• ~/Desktop/2024-01/
• ~/Desktop/2024-02/
• etc.

Advanced Usage Patterns

Atomic File Updates

Always use this pattern for safe file updates:

// 1. Create snapshot
{"name": "fs_snapshot", "arguments": {"path": "/config/app.conf"}}

// 2. Read current content
{"name": "fs_read", "arguments": {"path": "/config/app.conf"}}

// 3. Modify content (in memory)

// 4. Write new content
{"name": "fs_write", "arguments": {"path": "/config/app.conf", "content": "..."}}

// 5. Verify write
{"name": "fs_read", "arguments": {"path": "/config/app.conf"}}

Batch File Operations

Process multiple files efficiently:

// 1. Find all target files
{"name": "fs_find", "arguments": {"path": "./src", "pattern": "*.ts"}}

// 2. For each file:
//    - Read content
//    - Process
//    - Write back

Safe Directory Deletion

// 1. Create snapshot of parent directory
{"name": "fs_snapshot", "arguments": {"path": "/parent"}}

// 2. List contents to verify
{"name": "fs_ld", "arguments": {"path": "/parent/to_delete"}}

// 3. Delete if confirmed
{"name": "fs_delete", "arguments": {"path": "/parent/to_delete", "recursive": true}}

Error Handling

Common errors and solutions:

Permission Denied

Error: Permission denied: /etc/secure_file Solution: Run with appropriate permissions or modify file ownership

Path Not Found

Error: No such file or directory: /missing/path Solution: Verify path exists, check for typos, create parent directories

Disk Full

Error: No space left on device Solution: Free up disk space, use compression, clean snapshots

Invalid Path

Error: Invalid path: /path/with/../traversal Solution: Use absolute paths, avoid path traversal

Performance Considerations

Large File Operations

• Read/write large files in chunks
• Use compression for snapshots
• Consider disk I/O limits

Recursive Operations

• Set max_depth for fs_find to limit scope
• Use fs_ld instead of recursive fs_stat
• Monitor resource usage with silent_resources

Concurrent Operations

• Limit concurrent file writes
• Use file locking for shared access
• Batch operations when possible

Security Best Practices

1. Validate Paths: Always validate user-provided paths
2. Use Snapshots: Create backups before destructive operations
3. Check Permissions: Verify file permissions before modification
4. Sanitize Input: Validate file content before writing
5. Limit Scope: Use max_depth and patterns to limit operation scope