File Management Toolset#

This toolset provides tools for managing files and directories within the current working directory.

delete_file#

Purpose: Deletes a specified file by moving it to a .deleted_files/ folder with a ms-resolution timestamp prepended to the filename. This allows for file recovery if deletion was accidental.

Parameters#

Success Case Example#

Input:

{
  "file_path": "example.txt"
}

Output:

{
  "message": "File deleted successfully, by renaming 'example.txt' to '.deleted_files/20231015_143025_123_example.txt'."
}

Error Case Examples#

1. Missing File Path:

   {
     "error": "The required file_path was not specified"
   }

2. Invalid Path:

   {
     "error": "Access to the specified path 'example.txt' is not allowed."
   }

3. File Does Not Exist:

   {
     "error": "The specified file 'example.txt' does not exist."
   }

4. Cannot Delete from Deleted Files Folder:

   {
     "error": "Cannot delete files from the `.deleted_files/` folder."
   }

5. Failed to Create Deleted Files Directory:

   {
     "error": "Failed to create deleted files directory: Permission denied"
   }

6. Error While Deleting File:

   {
     "error": "An error occurred while deleting the file: No such file or directory"
   }

Notes#

• The tool preserves the directory structure in the .deleted_files/ folder.
• Timestamps are added to filenames for easy identification and recovery.

create_directory#

Purpose: Creates a new directory at the specified relative path. The operation is restricted to remain inside the current working directory.

Parameters#

Success Case Example#

Input:

{
  "directory_path": "new_folder"
}

Output:

{
  "directory_path": "new_folder",
  "status": "created"
}

Error Case Examples#

1. Missing Directory Path:

   {
     "error": "The required directory_path was not specified"
   }

2. Invalid Path:

   {
     "error": "The specified path 'new_folder' is outside the allowed directory."
   }

3. Failed to Create Directory:

   {
     "error": "Failed to create directory: Permission denied"
   }

Notes#

• The tool ensures the directory is created within the current working directory.
• It supports creating nested directories using Dir.mkdir_p.

rename_file#

Purpose: Renames a specified file to a new name within the current directory, including support for moving a file to a different path within the current directory.

Parameters#

Success Case Example#

Input:

{
  "current_path": "old_name.txt",
  "new_name": "new_name.txt"
}

Output:

{
  "message": "File 'old_name.txt' renamed to 'new_name.txt' successfully."
}

Error Case Examples#

1. Missing Current Path:

   {
     "error": "The required current_path was not specified"
   }

2. Missing New Name:

   {
     "error": "The required new_name was not specified"
   }

3. Invalid Path:

   {
     "error": "Access to the specified path 'old_name.txt' is not allowed."
   }

4. File Does Not Exist:

   {
     "error": "The specified file 'old_name.txt' does not exist."
   }

5. New Name Already Exists:

   {
     "error": "A file or directory with the new name 'new_name.txt' already exists."
   }

6. Error While Renaming File:

   {
     "error": "An error occurred while renaming the file: Permission denied"
   }

Notes#

• The tool ensures the operation is performed securely within the allowed directory.
• It supports moving files to different paths within the current directory.

list_files#

Purpose: Lists all files and directories in a specified folder (or the current folder if no path is provided), separating them into categories.

Parameters#

Success Case Example#

Input:

{
  "folder": "src"
}

Output:

{
  "path": "src",
  "files": ["file1.txt", "file2.txt"],
  "directories": ["tools", "utils"]
}

Error Case Examples#

1. Invalid Path:

   {
     "error": "Access to the specified path 'src' is not allowed."
   }

2. Path Does Not Exist:

   {
     "error": "The specified path 'src' does not exist or is not a directory."
   }

Notes#

• The tool ensures the operation is performed securely within the allowed directory.
• It separates entries into files and directories for clarity.