qodalis-cli-server-plugin-filesystem 1.0.0b1__tar.gz

qodalis_cli_server_plugin_filesystem-1.0.0b1/.gitignore

@@ -0,0 +1,43 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Environment variables
+.env
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+TestResults/
+
+# Type checking / linting
+.mypy_cache/
+.ruff_cache/
+
+# C extensions
+*.so
+
+# IDEs and editors
+.idea/
+.vscode/*
+!.vscode/settings.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# System files
+.DS_Store
+Thumbs.db

qodalis_cli_server_plugin_filesystem-1.0.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Qodalis Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qodalis_cli_server_plugin_filesystem-1.0.0b1/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: qodalis-cli-server-plugin-filesystem
+Version: 1.0.0b1
+Summary: Filesystem abstraction layer for Qodalis CLI servers — interfaces, models, errors, and built-in providers (in-memory, OS)
+Project-URL: Homepage, https://github.com/qodalis-solutions/cli-server-python
+Project-URL: Repository, https://github.com/qodalis-solutions/cli-server-python
+Project-URL: Issues, https://github.com/qodalis-solutions/cli-server-python/issues
+Author-email: Nicolae Lupei <nicolae.lupei@qodalis.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,filesystem,plugin,qodalis,storage
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10

qodalis_cli_server_plugin_filesystem-1.0.0b1/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qodalis-cli-server-plugin-filesystem"
+version = "1.0.0b1"
+description = "Filesystem abstraction layer for Qodalis CLI servers — interfaces, models, errors, and built-in providers (in-memory, OS)"
+readme = { text = "", content-type = "text/plain" }
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Nicolae Lupei", email = "nicolae.lupei@qodalis.com" },
+]
+keywords = ["cli", "qodalis", "filesystem", "storage", "plugin"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Homepage = "https://github.com/qodalis-solutions/cli-server-python"
+Repository = "https://github.com/qodalis-solutions/cli-server-python"
+Issues = "https://github.com/qodalis-solutions/cli-server-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["qodalis_cli_filesystem"]
+
+[tool.hatch.build.targets.sdist]
+include = ["qodalis_cli_filesystem/**"]

qodalis_cli_server_plugin_filesystem-1.0.0b1/qodalis_cli_filesystem/__init__.py

@@ -0,0 +1,24 @@
+"""Qodalis CLI filesystem plugin — interfaces, models, errors, and providers."""
+
+from __future__ import annotations
+
+from .errors import (
+    FileStorageExistsError,
+    FileStorageIsADirectoryError,
+    FileStorageNotADirectoryError,
+    FileStorageNotFoundError,
+    FileStoragePermissionError,
+)
+from .i_file_storage_provider import IFileStorageProvider
+from .models import FileEntry, FileStat
+
+__all__ = [
+    "FileEntry",
+    "FileStat",
+    "FileStorageExistsError",
+    "FileStorageIsADirectoryError",
+    "FileStorageNotADirectoryError",
+    "FileStorageNotFoundError",
+    "FileStoragePermissionError",
+    "IFileStorageProvider",
+]

qodalis_cli_server_plugin_filesystem-1.0.0b1/qodalis_cli_filesystem/errors.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+
+class FileStorageNotFoundError(Exception):
+    """Raised when a path does not exist."""
+
+    def __init__(self, path: str) -> None:
+        super().__init__(f"Path not found: {path}")
+        self.path = path
+
+
+class FileStoragePermissionError(Exception):
+    """Raised when access to a path is denied."""
+
+    def __init__(self, path: str) -> None:
+        super().__init__(f"Access denied: {path}")
+        self.path = path
+
+
+class FileStorageExistsError(Exception):
+    """Raised when a path already exists and should not."""
+
+    def __init__(self, path: str) -> None:
+        super().__init__(f"Path already exists: {path}")
+        self.path = path
+
+
+class FileStorageNotADirectoryError(Exception):
+    """Raised when a path is not a directory but should be."""
+
+    def __init__(self, path: str) -> None:
+        super().__init__(f"Not a directory: {path}")
+        self.path = path
+
+
+class FileStorageIsADirectoryError(Exception):
+    """Raised when a path is a directory but should not be."""
+
+    def __init__(self, path: str) -> None:
+        super().__init__(f"Is a directory: {path}")
+        self.path = path

qodalis_cli_server_plugin_filesystem-1.0.0b1/qodalis_cli_filesystem/i_file_storage_provider.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import AsyncIterator
+
+from .models import FileEntry, FileStat
+
+
+class IFileStorageProvider(ABC):
+    """Abstract base class for file storage providers.
+
+    All methods are async to support both local and remote backends.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Human-readable name for this provider."""
+        ...
+
+    @abstractmethod
+    async def list(self, path: str) -> list[FileEntry]:
+        """List entries in a directory."""
+        ...
+
+    @abstractmethod
+    async def read_file(self, path: str) -> str:
+        """Read a file and return its text content."""
+        ...
+
+    @abstractmethod
+    async def write_file(self, path: str, content: str | bytes) -> None:
+        """Write content to a file, creating or overwriting it."""
+        ...
+
+    @abstractmethod
+    async def stat(self, path: str) -> FileStat:
+        """Return metadata for a file or directory."""
+        ...
+
+    @abstractmethod
+    async def mkdir(self, path: str, recursive: bool = False) -> None:
+        """Create a directory."""
+        ...
+
+    @abstractmethod
+    async def remove(self, path: str, recursive: bool = False) -> None:
+        """Remove a file or directory."""
+        ...
+
+    @abstractmethod
+    async def copy(self, src: str, dest: str) -> None:
+        """Copy a file or directory from *src* to *dest*."""
+        ...
+
+    @abstractmethod
+    async def move(self, src: str, dest: str) -> None:
+        """Move (rename) a file or directory from *src* to *dest*."""
+        ...
+
+    @abstractmethod
+    async def exists(self, path: str) -> bool:
+        """Return True if the path exists."""
+        ...
+
+    @abstractmethod
+    async def get_download_stream(self, path: str) -> AsyncIterator[bytes]:
+        """Yield the file content as an async byte stream."""
+        ...
+
+    @abstractmethod
+    async def upload_file(self, path: str, content: bytes) -> None:
+        """Upload raw bytes to the given path."""
+        ...

qodalis_cli_server_plugin_filesystem-1.0.0b1/qodalis_cli_filesystem/models.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class FileEntry:
+    """Represents a single entry in a directory listing."""
+
+    name: str
+    type: str  # 'file' or 'directory'
+    size: int
+    modified: str  # ISO 8601
+    permissions: str | None = None
+
+
+@dataclass
+class FileStat:
+    """Detailed metadata for a file or directory."""
+
+    name: str
+    type: str  # 'file' or 'directory'
+    size: int
+    created: str  # ISO 8601
+    modified: str  # ISO 8601
+    permissions: str | None = None

qodalis_cli_server_plugin_filesystem-1.0.0b1/qodalis_cli_filesystem/providers/__init__.py

@@ -0,0 +1,12 @@
+"""File storage provider implementations."""
+
+from __future__ import annotations
+
+from .in_memory_provider import InMemoryFileStorageProvider
+from .os_provider import OsFileStorageProvider, OsProviderOptions
+
+__all__ = [
+    "InMemoryFileStorageProvider",
+    "OsFileStorageProvider",
+    "OsProviderOptions",
+]

qodalis_cli_server_plugin_filesystem-1.0.0b1/qodalis_cli_filesystem/providers/in_memory_provider.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import AsyncIterator
+
+from ..errors import (
+    FileStorageExistsError,
+    FileStorageIsADirectoryError,
+    FileStorageNotADirectoryError,
+    FileStorageNotFoundError,
+)
+from ..i_file_storage_provider import IFileStorageProvider
+from ..models import FileEntry, FileStat
+
+
+@dataclass
+class _FileNode:
+    """Internal tree node representing a file or directory."""
+
+    name: str
+    type: str  # 'file' or 'directory'
+    content: bytes = b""
+    children: dict[str, _FileNode] = field(default_factory=dict)
+    created_at: str = ""
+    modified_at: str = ""
+    size: int = 0
+    permissions: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.created_at:
+            now = datetime.now(timezone.utc).isoformat()
+            self.created_at = now
+            self.modified_at = now
+        if self.type == "directory":
+            self.permissions = "drwxr-xr-x"
+        else:
+            self.permissions = "-rw-r--r--"
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _normalize_path(path: str) -> str:
+    """Normalize *path* to a canonical form (strip leading/trailing slashes)."""
+    # Treat empty, "/", "." as root
+    path = path.strip("/").strip()
+    if path in ("", "."):
+        return ""
+    # Collapse consecutive slashes and resolve "." / ".."
+    parts: list[str] = []
+    for segment in path.split("/"):
+        if segment in ("", "."):
+            continue
+        if segment == "..":
+            if parts:
+                parts.pop()
+        else:
+            parts.append(segment)
+    return "/".join(parts)
+
+
+class InMemoryFileStorageProvider(IFileStorageProvider):
+    """In-memory file storage backed by a tree of ``_FileNode`` objects."""
+
+    def __init__(self) -> None:
+        self._root = _FileNode(name="", type="directory")
+
+    # -- IFileStorageProvider interface ----------------------------------------
+
+    @property
+    def name(self) -> str:
+        return "in-memory"
+
+    async def list(self, path: str) -> list[FileEntry]:
+        node = self._resolve(_normalize_path(path))
+        if node is None:
+            raise FileStorageNotFoundError(path)
+        if node.type != "directory":
+            raise FileStorageNotADirectoryError(path)
+
+        entries: list[FileEntry] = []
+        for child in sorted(node.children.values(), key=lambda n: n.name):
+            entries.append(
+                FileEntry(
+                    name=child.name,
+                    type=child.type,
+                    size=child.size,
+                    modified=child.modified_at,
+                    permissions=child.permissions,
+                )
+            )
+        return entries
+
+    async def read_file(self, path: str) -> str:
+        node = self._resolve(_normalize_path(path))
+        if node is None:
+            raise FileStorageNotFoundError(path)
+        if node.type == "directory":
+            raise FileStorageIsADirectoryError(path)
+        return node.content.decode("utf-8", errors="replace")
+
+    async def write_file(self, path: str, content: str | bytes) -> None:
+        norm = _normalize_path(path)
+        if not norm:
+            raise FileStorageIsADirectoryError(path)
+
+        parts = norm.split("/")
+        parent = self._ensure_parents(parts[:-1], path)
+        file_name = parts[-1]
+
+        raw = content.encode("utf-8") if isinstance(content, str) else content
+        now = _now_iso()
+
+        existing = parent.children.get(file_name)
+        if existing is not None and existing.type == "directory":
+            raise FileStorageIsADirectoryError(path)
+
+        if existing is not None:
+            existing.content = raw
+            existing.size = len(raw)
+            existing.modified_at = now
+        else:
+            parent.children[file_name] = _FileNode(
+                name=file_name,
+                type="file",
+                content=raw,
+                created_at=now,
+                modified_at=now,
+                size=len(raw),
+            )
+
+    async def stat(self, path: str) -> FileStat:
+        node = self._resolve(_normalize_path(path))
+        if node is None:
+            raise FileStorageNotFoundError(path)
+        return FileStat(
+            name=node.name,
+            type=node.type,
+            size=node.size,
+            created=node.created_at,
+            modified=node.modified_at,
+            permissions=node.permissions,
+        )
+
+    async def mkdir(self, path: str, recursive: bool = False) -> None:
+        norm = _normalize_path(path)
+        if not norm:
+            return  # root always exists
+
+        parts = norm.split("/")
+        if recursive:
+            self._ensure_parents(parts, path)
+        else:
+            parent = self._ensure_parents(parts[:-1], path, create=False)
+            dir_name = parts[-1]
+            existing = parent.children.get(dir_name)
+            if existing is not None:
+                if existing.type != "directory":
+                    raise FileStorageExistsError(path)
+                return  # already exists
+            parent.children[dir_name] = _FileNode(name=dir_name, type="directory")
+
+    async def remove(self, path: str, recursive: bool = False) -> None:
+        norm = _normalize_path(path)
+        if not norm:
+            raise FileStoragePermissionError(path)
+
+        parts = norm.split("/")
+        parent = self._resolve("/".join(parts[:-1]))
+        if parent is None or parts[-1] not in parent.children:
+            raise FileStorageNotFoundError(path)
+
+        node = parent.children[parts[-1]]
+        if node.type == "directory" and node.children and not recursive:
+            raise FileStorageNotADirectoryError(path)
+
+        del parent.children[parts[-1]]
+
+    async def copy(self, src: str, dest: str) -> None:
+        src_node = self._resolve(_normalize_path(src))
+        if src_node is None:
+            raise FileStorageNotFoundError(src)
+
+        dest_norm = _normalize_path(dest)
+        if not dest_norm:
+            raise FileStorageIsADirectoryError(dest)
+
+        parts = dest_norm.split("/")
+        parent = self._ensure_parents(parts[:-1], dest)
+        parent.children[parts[-1]] = self._deep_copy(src_node, parts[-1])
+
+    async def move(self, src: str, dest: str) -> None:
+        src_norm = _normalize_path(src)
+        if not src_norm:
+            raise FileStoragePermissionError(src)
+
+        src_node = self._resolve(src_norm)
+        if src_node is None:
+            raise FileStorageNotFoundError(src)
+
+        dest_norm = _normalize_path(dest)
+        if not dest_norm:
+            raise FileStorageIsADirectoryError(dest)
+
+        dest_parts = dest_norm.split("/")
+        dest_parent = self._ensure_parents(dest_parts[:-1], dest)
+
+        # Copy node to new location
+        dest_parent.children[dest_parts[-1]] = self._deep_copy(
+            src_node, dest_parts[-1]
+        )
+
+        # Remove from old location
+        src_parts = src_norm.split("/")
+        src_parent = self._resolve("/".join(src_parts[:-1]))
+        if src_parent is not None:
+            del src_parent.children[src_parts[-1]]
+
+    async def exists(self, path: str) -> bool:
+        return self._resolve(_normalize_path(path)) is not None
+
+    async def get_download_stream(self, path: str) -> AsyncIterator[bytes]:
+        node = self._resolve(_normalize_path(path))
+        if node is None:
+            raise FileStorageNotFoundError(path)
+        if node.type == "directory":
+            raise FileStorageIsADirectoryError(path)
+
+        async def _stream() -> AsyncIterator[bytes]:
+            yield node.content
+
+        return _stream()
+
+    async def upload_file(self, path: str, content: bytes) -> None:
+        await self.write_file(path, content)
+
+    # -- Private helpers -------------------------------------------------------
+
+    def _resolve(self, norm_path: str) -> _FileNode | None:
+        """Walk the tree and return the node at *norm_path*, or ``None``."""
+        if not norm_path:
+            return self._root
+        node = self._root
+        for part in norm_path.split("/"):
+            if node.type != "directory" or part not in node.children:
+                return None
+            node = node.children[part]
+        return node
+
+    def _ensure_parents(
+        self, parts: list[str], original_path: str, *, create: bool = True
+    ) -> _FileNode:
+        """Ensure all parent directories exist for *parts*.
+
+        Returns the final parent node.  If *create* is ``False``, raises
+        ``FileStorageNotFoundError`` when a segment is missing.
+        """
+        node = self._root
+        for part in parts:
+            if part not in node.children:
+                if not create:
+                    raise FileStorageNotFoundError(original_path)
+                node.children[part] = _FileNode(name=part, type="directory")
+            child = node.children[part]
+            if child.type != "directory":
+                raise FileStorageNotADirectoryError(original_path)
+            node = child
+        return node
+
+    def _deep_copy(self, node: _FileNode, new_name: str) -> _FileNode:
+        """Recursively copy a node tree, assigning *new_name* to the root copy."""
+        now = _now_iso()
+        copy = _FileNode(
+            name=new_name,
+            type=node.type,
+            content=bytes(node.content),
+            created_at=now,
+            modified_at=now,
+            size=node.size,
+            permissions=node.permissions,
+        )
+        for child_name, child_node in node.children.items():
+            copy.children[child_name] = self._deep_copy(child_node, child_name)
+        return copy

qodalis_cli_server_plugin_filesystem-1.0.0b1/qodalis_cli_filesystem/providers/os_provider.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import os
+import shutil
+import stat as stat_mod
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import AsyncIterator
+
+from ..errors import (
+    FileStorageIsADirectoryError,
+    FileStorageNotADirectoryError,
+    FileStorageNotFoundError,
+    FileStoragePermissionError,
+)
+from ..i_file_storage_provider import IFileStorageProvider
+from ..models import FileEntry, FileStat
+
+
+@dataclass
+class OsProviderOptions:
+    """Configuration for :class:`OsFileStorageProvider`.
+
+    Attributes:
+        allowed_paths: Absolute directory paths that clients may access.
+            Each requested path is resolved and checked against this
+            whitelist before any I/O is performed.
+    """
+
+    allowed_paths: list[str] = field(default_factory=list)
+
+
+class OsFileStorageProvider(IFileStorageProvider):
+    """File storage provider backed by the operating system filesystem.
+
+    Access is restricted to the directories listed in *options.allowed_paths*.
+    """
+
+    def __init__(self, options: OsProviderOptions) -> None:
+        self._allowed_paths = [os.path.realpath(p) for p in options.allowed_paths]
+
+    # -- IFileStorageProvider interface ----------------------------------------
+
+    @property
+    def name(self) -> str:
+        return "os"
+
+    async def list(self, path: str) -> list[FileEntry]:
+        resolved = self._validate(path)
+
+        if not os.path.exists(resolved):
+            raise FileStorageNotFoundError(path)
+        if not os.path.isdir(resolved):
+            raise FileStorageNotADirectoryError(path)
+
+        entries: list[FileEntry] = []
+        for entry_name in sorted(os.listdir(resolved)):
+            full = os.path.join(resolved, entry_name)
+            try:
+                st = os.stat(full)
+                entry_type = "directory" if stat_mod.S_ISDIR(st.st_mode) else "file"
+                entries.append(
+                    FileEntry(
+                        name=entry_name,
+                        type=entry_type,
+                        size=st.st_size,
+                        modified=datetime.fromtimestamp(
+                            st.st_mtime, tz=timezone.utc
+                        ).isoformat(),
+                        permissions=stat_mod.filemode(st.st_mode),
+                    )
+                )
+            except OSError:
+                continue
+        return entries
+
+    async def read_file(self, path: str) -> str:
+        resolved = self._validate(path)
+
+        if not os.path.exists(resolved):
+            raise FileStorageNotFoundError(path)
+        if os.path.isdir(resolved):
+            raise FileStorageIsADirectoryError(path)
+
+        with open(resolved, "r", encoding="utf-8", errors="replace") as fh:
+            return fh.read()
+
+    async def write_file(self, path: str, content: str | bytes) -> None:
+        resolved = self._validate(path)
+
+        if os.path.isdir(resolved):
+            raise FileStorageIsADirectoryError(path)
+
+        parent = os.path.dirname(resolved)
+        if not os.path.isdir(parent):
+            raise FileStorageNotFoundError(os.path.dirname(path))
+
+        if isinstance(content, str):
+            with open(resolved, "w", encoding="utf-8") as fh:
+                fh.write(content)
+        else:
+            with open(resolved, "wb") as fh:
+                fh.write(content)
+
+    async def stat(self, path: str) -> FileStat:
+        resolved = self._validate(path)
+
+        if not os.path.exists(resolved):
+            raise FileStorageNotFoundError(path)
+
+        st = os.stat(resolved)
+        entry_type = "directory" if stat_mod.S_ISDIR(st.st_mode) else "file"
+        return FileStat(
+            name=os.path.basename(resolved),
+            type=entry_type,
+            size=st.st_size,
+            created=datetime.fromtimestamp(
+                st.st_ctime, tz=timezone.utc
+            ).isoformat(),
+            modified=datetime.fromtimestamp(
+                st.st_mtime, tz=timezone.utc
+            ).isoformat(),
+            permissions=stat_mod.filemode(st.st_mode),
+        )
+
+    async def mkdir(self, path: str, recursive: bool = False) -> None:
+        resolved = self._validate(path)
+
+        if recursive:
+            os.makedirs(resolved, exist_ok=True)
+        else:
+            parent = os.path.dirname(resolved)
+            if not os.path.isdir(parent):
+                raise FileStorageNotFoundError(os.path.dirname(path))
+            if os.path.exists(resolved):
+                return  # already exists
+            os.mkdir(resolved)
+
+    async def remove(self, path: str, recursive: bool = False) -> None:
+        resolved = self._validate(path)
+
+        if not os.path.exists(resolved):
+            raise FileStorageNotFoundError(path)
+
+        if os.path.isdir(resolved):
+            if recursive:
+                shutil.rmtree(resolved)
+            else:
+                os.rmdir(resolved)
+        else:
+            os.remove(resolved)
+
+    async def copy(self, src: str, dest: str) -> None:
+        resolved_src = self._validate(src)
+        resolved_dest = self._validate(dest)
+
+        if not os.path.exists(resolved_src):
+            raise FileStorageNotFoundError(src)
+
+        if os.path.isdir(resolved_src):
+            shutil.copytree(resolved_src, resolved_dest)
+        else:
+            shutil.copy2(resolved_src, resolved_dest)
+
+    async def move(self, src: str, dest: str) -> None:
+        resolved_src = self._validate(src)
+        resolved_dest = self._validate(dest)
+
+        if not os.path.exists(resolved_src):
+            raise FileStorageNotFoundError(src)
+
+        shutil.move(resolved_src, resolved_dest)
+
+    async def exists(self, path: str) -> bool:
+        resolved = self._validate(path)
+        return os.path.exists(resolved)
+
+    async def get_download_stream(self, path: str) -> AsyncIterator[bytes]:
+        resolved = self._validate(path)
+
+        if not os.path.exists(resolved):
+            raise FileStorageNotFoundError(path)
+        if os.path.isdir(resolved):
+            raise FileStorageIsADirectoryError(path)
+
+        async def _stream() -> AsyncIterator[bytes]:
+            with open(resolved, "rb") as fh:
+                while True:
+                    chunk = fh.read(64 * 1024)
+                    if not chunk:
+                        break
+                    yield chunk
+
+        return _stream()
+
+    async def upload_file(self, path: str, content: bytes) -> None:
+        await self.write_file(path, content)
+
+    # -- Private helpers -------------------------------------------------------
+
+    def _validate(self, path: str) -> str:
+        """Resolve *path* and check it against the allowed whitelist.
+
+        Returns the resolved absolute path.
+
+        Raises:
+            FileStoragePermissionError: If the path is outside allowed dirs.
+        """
+        resolved = os.path.realpath(path)
+
+        for allowed in self._allowed_paths:
+            if resolved == allowed or resolved.startswith(allowed + os.sep):
+                return resolved
+
+        raise FileStoragePermissionError(path)