semantic update

backend/src/plugins/storage/plugin.py

@@ -31,6 +31,8 @@ class StoragePlugin(PluginBase):
 
     # [DEF:__init__: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()
@@ -39,40 +41,55 @@ class StoragePlugin(PluginBase):
     @property
     # [DEF:id:Function]
     # @PURPOSE: Returns the unique identifier for the storage plugin.
+    # @PRE: None.
+    # @POST: Returns the plugin ID string.
     # @RETURN: str - "storage-manager"
     def id(self) -> str:
-        return "storage-manager"
+        with belief_scope("StoragePlugin:id"):
+            return "storage-manager"
     # [/DEF:id:Function]
 
     @property
     # [DEF:name:Function]
     # @PURPOSE: Returns the human-readable name of the storage plugin.
+    # @PRE: None.
+    # @POST: Returns the plugin name string.
     # @RETURN: str - "Storage Manager"
     def name(self) -> str:
-        return "Storage Manager"
+        with belief_scope("StoragePlugin:name"):
+            return "Storage Manager"
     # [/DEF:name:Function]
 
     @property
     # [DEF:description:Function]
     # @PURPOSE: Returns a description of the storage plugin.
+    # @PRE: None.
+    # @POST: Returns the plugin description string.
     # @RETURN: str - Plugin description.
     def description(self) -> str:
-        return "Manages local file storage for backups and repositories."
+        with belief_scope("StoragePlugin:description"):
+            return "Manages local file storage for backups and repositories."
     # [/DEF:description:Function]
 
     @property
     # [DEF:version:Function]
     # @PURPOSE: Returns the version of the storage plugin.
+    # @PRE: None.
+    # @POST: Returns the version string.
     # @RETURN: str - "1.0.0"
     def version(self) -> str:
-        return "1.0.0"
+        with belief_scope("StoragePlugin:version"):
+            return "1.0.0"
     # [/DEF:version:Function]
 
     # [DEF:get_schema:Function]
     # @PURPOSE: Returns the JSON schema for storage plugin parameters.
+    # @PRE: None.
+    # @POST: Returns a dictionary representing the JSON schema.
     # @RETURN: Dict[str, Any] - JSON schema.
     def get_schema(self) -> Dict[str, Any]:
-        return {
+        with belief_scope("StoragePlugin:get_schema"):
+            return {
             "type": "object",
             "properties": {
                 "category": {
@@ -87,6 +104,8 @@ class StoragePlugin(PluginBase):
 
     # [DEF:execute:Function]
     # @PURPOSE: Executes storage-related tasks (placeholder for PluginBase compliance).
+    # @PRE: params must match the plugin schema.
+    # @POST: Task is executed and logged.
     async def execute(self, params: Dict[str, Any]):
         with belief_scope("StoragePlugin:execute"):
             logger.info(f"[StoragePlugin][Action] Executing with params: {params}")
@@ -94,6 +113,7 @@ class StoragePlugin(PluginBase):
 
     # [DEF:get_storage_root: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.
     def get_storage_root(self) -> Path:
         with belief_scope("StoragePlugin:get_storage_root"):
@@ -117,6 +137,8 @@ class StoragePlugin(PluginBase):
     # @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.
+    # @PRE: pattern must be a valid format string.
+    # @POST: Returns the resolved path string.
     # @RETURN: str - The resolved path.
     def resolve_path(self, pattern: str, variables: Dict[str, str]) -> str:
         with belief_scope("StoragePlugin:resolve_path"):
@@ -137,6 +159,8 @@ class StoragePlugin(PluginBase):
 
     # [DEF:ensure_directories: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.
     # @SIDE_EFFECT: Creates directories on the filesystem.
     def ensure_directories(self):
         with belief_scope("StoragePlugin:ensure_directories"):
@@ -168,6 +192,8 @@ class StoragePlugin(PluginBase):
     # @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.
+    # @PRE: Storage root must exist.
+    # @POST: Returns a list of StoredFile objects.
     # @RETURN: List[StoredFile] - List of file and directory metadata objects.
     def list_files(self, category: Optional[FileCategory] = None, subpath: Optional[str] = None) -> List[StoredFile]:
         with belief_scope("StoragePlugin:list_files"):
@@ -218,6 +244,8 @@ class StoragePlugin(PluginBase):
     # @PARAM: file (UploadFile) - The uploaded file.
     # @PARAM: category (FileCategory) - The target category.
     # @PARAM: subpath (Optional[str]) - The target subpath.
+    # @PRE: file must be a valid UploadFile; category must be valid.
+    # @POST: File is written to disk and metadata is returned.
     # @RETURN: StoredFile - Metadata of the saved file.
     # @SIDE_EFFECT: Writes file to disk.
     async def save_file(self, file: UploadFile, category: FileCategory, subpath: Optional[str] = None) -> StoredFile:
@@ -249,6 +277,8 @@ class StoragePlugin(PluginBase):
     # @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.
+    # @PRE: path must belong to the specified category and exist on disk.
+    # @POST: The file or directory is removed from disk.
     # @SIDE_EFFECT: Removes item from disk.
     def delete_file(self, category: FileCategory, path: str):
         with belief_scope("StoragePlugin:delete_file"):
@@ -273,6 +303,8 @@ class StoragePlugin(PluginBase):
     # @PURPOSE: Returns the absolute path of a file for download.
     # @PARAM: category (FileCategory) - The category.
     # @PARAM: path (str) - The relative path of the file.
+    # @PRE: path must belong to the specified category and be a file.
+    # @POST: Returns the absolute Path to the file.
     # @RETURN: Path - Absolute path to the file.
     def get_file_path(self, category: FileCategory, path: str) -> Path:
         with belief_scope("StoragePlugin:get_file_path"):