semantics

backend/src/plugins/storage/plugin.py

@@ -1,4 +1,4 @@
-# #region StoragePlugin [TYPE Module] [SEMANTICS storage, files, filesystem, plugin]
+# #region StoragePlugin [TYPE Module] [SEMANTICS fastapi, storage, filesystem, backup, archive]
 #
 # @BRIEF Provides core filesystem operations for managing backups and repositories.
 # @LAYER:     App
@@ -28,17 +28,17 @@ class StoragePlugin(PluginBase):
     Plugin for managing local file storage for backups and repositories.
     """
 
-    # [DEF:__init__:Function]
+    # region __init__ [TYPE Function]
     # @PURPOSE: Initializes the StoragePlugin and ensures required directories exist.
     # @PRE: Configuration manager must be accessible.
     # @POST: Storage root and category directories are created on disk.
     def __init__(self):
         with belief_scope("StoragePlugin:init"):
             self.ensure_directories()
-    # [/DEF:__init__:Function]
+    # endregion __init__
 
     @property
-    # [DEF:id:Function]
+    # region id [TYPE Function]
     # @PURPOSE: Returns the unique identifier for the storage plugin.
     # @PRE: None.
     # @POST: Returns the plugin ID string.
@@ -46,10 +46,10 @@ class StoragePlugin(PluginBase):
     def id(self) -> str:
         with belief_scope("StoragePlugin:id"):
             return "storage-manager"
-    # [/DEF:id:Function]
+    # endregion id
 
     @property
-    # [DEF:name:Function]
+    # region name [TYPE Function]
     # @PURPOSE: Returns the human-readable name of the storage plugin.
     # @PRE: None.
     # @POST: Returns the plugin name string.
@@ -57,10 +57,10 @@ class StoragePlugin(PluginBase):
     def name(self) -> str:
         with belief_scope("StoragePlugin:name"):
             return "Storage Manager"
-    # [/DEF:name:Function]
+    # endregion name
 
     @property
-    # [DEF:description:Function]
+    # region description [TYPE Function]
     # @PURPOSE: Returns a description of the storage plugin.
     # @PRE: None.
     # @POST: Returns the plugin description string.
@@ -68,10 +68,10 @@ class StoragePlugin(PluginBase):
     def description(self) -> str:
         with belief_scope("StoragePlugin:description"):
             return "Manages local file storage for backups and repositories."
-    # [/DEF:description:Function]
+    # endregion description
 
     @property
-    # [DEF:version:Function]
+    # region version [TYPE Function]
     # @PURPOSE: Returns the version of the storage plugin.
     # @PRE: None.
     # @POST: Returns the version string.
@@ -79,18 +79,18 @@ class StoragePlugin(PluginBase):
     def version(self) -> str:
         with belief_scope("StoragePlugin:version"):
             return "1.0.0"
-    # [/DEF:version:Function]
+    # endregion version
 
     @property
-    # [DEF:ui_route:Function]
+    # region ui_route [TYPE Function]
     # @PURPOSE: Returns the frontend route for the storage plugin.
     # @RETURN: str - "/tools/storage"
     def ui_route(self) -> str:
         with belief_scope("StoragePlugin:ui_route"):
             return "/tools/storage"
-    # [/DEF:ui_route:Function]
+    # endregion ui_route
 
-    # [DEF:get_schema:Function]
+    # region get_schema [TYPE Function]
     # @PURPOSE: Returns the JSON schema for storage plugin parameters.
     # @PRE: None.
     # @POST: Returns a dictionary representing the JSON schema.
@@ -108,9 +108,9 @@ class StoragePlugin(PluginBase):
             },
             "required": ["category"]
         }
-    # [/DEF:get_schema:Function]
+    # endregion get_schema
 
-    # [DEF:execute:Function]
+    # region execute [TYPE Function]
     # @PURPOSE: Executes storage-related tasks with TaskContext support.
     # @PARAM: params (Dict[str, Any]) - Storage parameters.
     # @PARAM: context (Optional[TaskContext]) - Task context for logging with source attribution.
@@ -126,9 +126,9 @@ class StoragePlugin(PluginBase):
             log.with_source("filesystem") if context else log
             
             storage_log.info(f"Executing with params: {params}")
-    # [/DEF:execute:Function]
+    # endregion execute
 
-    # [DEF:get_storage_root:Function]
+    # region get_storage_root [TYPE Function]
     # @PURPOSE: Resolves the absolute path to the storage root.
     # @PRE: Settings must define a storage root path.
     # @POST: Returns a Path object representing the storage root.
@@ -148,9 +148,9 @@ class StoragePlugin(PluginBase):
                 project_root = Path(__file__).parents[3]
                 root = (project_root / root).resolve()
             return root
-    # [/DEF:get_storage_root:Function]
+    # endregion get_storage_root
 
-    # [DEF:resolve_path:Function]
+    # region resolve_path [TYPE Function]
     # @PURPOSE: Resolves a dynamic path pattern using provided variables.
     # @PARAM: pattern (str) - The path pattern to resolve.
     # @PARAM: variables (Dict[str, str]) - Variables to substitute in the pattern.
@@ -172,9 +172,9 @@ class StoragePlugin(PluginBase):
                 logger.warning(f"[StoragePlugin][Coherence:Failed] Missing variable for path resolution: {e}")
                 # Fallback to literal pattern if formatting fails partially (or handle as needed)
                 return pattern.replace("{", "").replace("}", "")
-    # [/DEF:resolve_path:Function]
+    # endregion resolve_path
 
-    # [DEF:ensure_directories:Function]
+    # region ensure_directories [TYPE Function]
     # @PURPOSE: Creates the storage root and category subdirectories if they don't exist.
     # @PRE: Storage root must be resolvable.
     # @POST: Directories are created on the filesystem.
@@ -187,9 +187,9 @@ class StoragePlugin(PluginBase):
                 path = root / category.value
                 path.mkdir(parents=True, exist_ok=True)
                 logger.reason(f"Ensured directory: {path}", extra={"src": "StoragePlugin.ensure_directories"})
-    # [/DEF:ensure_directories:Function]
+    # endregion ensure_directories
 
-    # [DEF:validate_path:Function]
+    # region validate_path [TYPE Function]
     # @PURPOSE: Prevents path traversal attacks by ensuring the path is within the storage root.
     # @PRE: path must be a Path object.
     # @POST: Returns the resolved absolute path if valid, otherwise raises ValueError.
@@ -203,9 +203,9 @@ class StoragePlugin(PluginBase):
                 logger.error(f"[StoragePlugin][Coherence:Failed] Path traversal detected: {resolved} is not under {root}")
                 raise ValueError("Access denied: Path is outside of storage root.")
             return resolved
-    # [/DEF:validate_path:Function]
+    # endregion validate_path
 
-    # [DEF:list_files:Function]
+    # region list_files [TYPE Function]
     # @PURPOSE: Lists all files and directories in a specific category and subpath.
     # @PARAM: category (Optional[FileCategory]) - The category to list.
     # @PARAM: subpath (Optional[str]) - Nested path within the category.
@@ -302,9 +302,9 @@ class StoragePlugin(PluginBase):
             
             # Sort: directories first, then by name
             return sorted(files, key=lambda x: (x.mime_type != "directory", x.name))
-    # [/DEF:list_files:Function]
+    # endregion list_files
 
-    # [DEF:save_file:Function]
+    # region save_file [TYPE Function]
     # @PURPOSE: Saves an uploaded file to the specified category and optional subpath.
     # @PARAM: file (UploadFile) - The uploaded file.
     # @PARAM: category (FileCategory) - The target category.
@@ -336,9 +336,9 @@ class StoragePlugin(PluginBase):
                 category=category,
                 mime_type=file.content_type
             )
-    # [/DEF:save_file:Function]
+    # endregion save_file
 
-    # [DEF:delete_file:Function]
+    # region delete_file [TYPE Function]
     # @PURPOSE: Deletes a file or directory from the specified category and path.
     # @PARAM: category (FileCategory) - The category.
     # @PARAM: path (str) - The relative path of the file or directory.
@@ -362,9 +362,9 @@ class StoragePlugin(PluginBase):
                 logger.reason(f"Deleted: {full_path}", extra={"src": "StoragePlugin.delete_file"})
             else:
                 raise FileNotFoundError(f"Item {path} not found")
-    # [/DEF:delete_file:Function]
+    # endregion delete_file
 
-    # [DEF:get_file_path:Function]
+    # region get_file_path [TYPE Function]
     # @PURPOSE: Returns the absolute path of a file for download.
     # @PARAM: category (FileCategory) - The category.
     # @PARAM: path (str) - The relative path of the file.
@@ -383,7 +383,7 @@ class StoragePlugin(PluginBase):
                 raise FileNotFoundError(f"File {path} not found")
             
             return file_path
-    # [/DEF:get_file_path:Function]
+    # endregion get_file_path
 
 # #endregion StoragePlugin
 # #endregion StoragePlugin