qodalis-cli-server 1.0.0b1__py3-none-any.whl

qodalis_cli/controllers/filesystem_controller.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+from dataclasses import asdict
+from datetime import datetime, timezone
+from typing import Any, Union
+
+from fastapi import APIRouter, File, Form, HTTPException, UploadFile
+from fastapi.responses import FileResponse, StreamingResponse
+
+from qodalis_cli_filesystem import (
+    FileStorageExistsError,
+    FileStorageIsADirectoryError,
+    FileStorageNotADirectoryError,
+    FileStorageNotFoundError,
+    FileStoragePermissionError,
+    IFileStorageProvider,
+)
+
+from ..filesystem.filesystem_path_validator import FileSystemPathValidator
+
+
+def _map_provider_error(exc: Exception) -> HTTPException:
+    """Map a file-storage error to the appropriate HTTP exception."""
+    if isinstance(exc, FileStorageNotFoundError):
+        return HTTPException(status_code=404, detail=str(exc))
+    if isinstance(exc, FileStoragePermissionError):
+        return HTTPException(status_code=403, detail=str(exc))
+    if isinstance(exc, (FileStorageNotADirectoryError, FileStorageIsADirectoryError)):
+        return HTTPException(status_code=400, detail=str(exc))
+    if isinstance(exc, FileStorageExistsError):
+        return HTTPException(status_code=409, detail=str(exc))
+    return HTTPException(status_code=500, detail=str(exc))
+
+
+# ---------------------------------------------------------------------------
+# Provider-based router (new)
+# ---------------------------------------------------------------------------
+
+
+def create_filesystem_router(
+    provider_or_validator: Union[IFileStorageProvider, FileSystemPathValidator],
+) -> APIRouter:
+    """Create a FastAPI router exposing filesystem operations.
+
+    Accepts either a :class:`IFileStorageProvider` (new approach) or a
+    :class:`FileSystemPathValidator` (legacy approach) for backward
+    compatibility.
+    """
+    if isinstance(provider_or_validator, FileSystemPathValidator):
+        return _create_legacy_router(provider_or_validator)
+
+    return _create_provider_router(provider_or_validator)
+
+
+def _create_provider_router(provider: IFileStorageProvider) -> APIRouter:
+    """Create a router that delegates to *provider*."""
+
+    router = APIRouter()
+
+    @router.get("/ls")
+    async def list_directory(path: str) -> dict[str, Any]:
+        try:
+            entries = await provider.list(path)
+            return {"entries": [asdict(e) for e in entries]}
+        except (
+            FileStorageNotFoundError,
+            FileStorageNotADirectoryError,
+            FileStoragePermissionError,
+        ) as exc:
+            raise _map_provider_error(exc) from exc
+
+    @router.get("/cat")
+    async def read_file(path: str) -> dict[str, str]:
+        try:
+            content = await provider.read_file(path)
+            return {"content": content}
+        except (
+            FileStorageNotFoundError,
+            FileStorageIsADirectoryError,
+            FileStoragePermissionError,
+        ) as exc:
+            raise _map_provider_error(exc) from exc
+
+    @router.get("/stat")
+    async def stat_path(path: str) -> dict[str, Any]:
+        try:
+            info = await provider.stat(path)
+            return asdict(info)
+        except (
+            FileStorageNotFoundError,
+            FileStoragePermissionError,
+        ) as exc:
+            raise _map_provider_error(exc) from exc
+
+    @router.get("/download")
+    async def download_file(path: str) -> StreamingResponse:
+        try:
+            stream = await provider.get_download_stream(path)
+            filename = path.rstrip("/").rsplit("/", 1)[-1] or "download"
+            return StreamingResponse(
+                stream,
+                media_type="application/octet-stream",
+                headers={
+                    "Content-Disposition": f'attachment; filename="{filename}"'
+                },
+            )
+        except (
+            FileStorageNotFoundError,
+            FileStorageIsADirectoryError,
+            FileStoragePermissionError,
+        ) as exc:
+            raise _map_provider_error(exc) from exc
+
+    @router.post("/upload")
+    async def upload_file(
+        file: UploadFile = File(...),
+        path: str = Form(...),
+    ) -> dict[str, str]:
+        try:
+            contents = await file.read()
+            await provider.upload_file(path, contents)
+            return {"path": path, "status": "uploaded"}
+        except (
+            FileStorageNotFoundError,
+            FileStorageIsADirectoryError,
+            FileStoragePermissionError,
+        ) as exc:
+            raise _map_provider_error(exc) from exc
+
+    @router.post("/mkdir")
+    async def make_directory(body: dict[str, Any]) -> dict[str, str]:
+        raw_path = body.get("path")
+        if not raw_path:
+            raise HTTPException(status_code=400, detail="'path' is required")
+
+        recursive = body.get("recursive", True)
+        try:
+            await provider.mkdir(raw_path, recursive=recursive)
+            return {"path": raw_path, "status": "created"}
+        except (
+            FileStorageNotFoundError,
+            FileStorageExistsError,
+            FileStoragePermissionError,
+        ) as exc:
+            raise _map_provider_error(exc) from exc
+
+    @router.delete("/rm")
+    async def remove_path(path: str, recursive: bool = True) -> dict[str, str]:
+        try:
+            await provider.remove(path, recursive=recursive)
+            return {"path": path, "status": "deleted"}
+        except (
+            FileStorageNotFoundError,
+            FileStoragePermissionError,
+        ) as exc:
+            raise _map_provider_error(exc) from exc
+
+    return router
+
+
+# ---------------------------------------------------------------------------
+# Legacy validator-based router (backward compatible)
+# ---------------------------------------------------------------------------
+
+
+def _safe_validate(validator: FileSystemPathValidator, path: str) -> str:
+    """Validate *path* via the validator, raising a 403 on failure."""
+    try:
+        return validator.validate(path)
+    except PermissionError as exc:
+        raise HTTPException(status_code=403, detail=str(exc)) from exc
+
+
+def _stat_entry(resolved: str) -> dict[str, Any]:
+    """Return a stat dictionary for the given resolved path."""
+    st = os.stat(resolved)
+    entry_type = "directory" if stat.S_ISDIR(st.st_mode) else "file"
+    return {
+        "name": os.path.basename(resolved),
+        "type": entry_type,
+        "size": st.st_size,
+        "modified": datetime.fromtimestamp(st.st_mtime, tz=timezone.utc).isoformat(),
+        "created": datetime.fromtimestamp(st.st_ctime, tz=timezone.utc).isoformat(),
+        "permissions": stat.filemode(st.st_mode),
+    }
+
+
+def _create_legacy_router(validator: FileSystemPathValidator) -> APIRouter:
+    """Create a router using the legacy :class:`FileSystemPathValidator`."""
+
+    router = APIRouter()
+
+    @router.get("/ls")
+    async def list_directory(path: str) -> dict[str, Any]:
+        resolved = _safe_validate(validator, path)
+
+        if not os.path.exists(resolved):
+            raise HTTPException(status_code=404, detail="Path not found")
+        if not os.path.isdir(resolved):
+            raise HTTPException(status_code=400, detail="Path is not a directory")
+
+        entries: list[dict[str, Any]] = []
+        try:
+            for name in sorted(os.listdir(resolved)):
+                full = os.path.join(resolved, name)
+                try:
+                    st = os.stat(full)
+                    entry_type = "directory" if stat.S_ISDIR(st.st_mode) else "file"
+                    entries.append(
+                        {
+                            "name": name,
+                            "type": entry_type,
+                            "size": st.st_size,
+                            "modified": datetime.fromtimestamp(
+                                st.st_mtime, tz=timezone.utc
+                            ).isoformat(),
+                            "permissions": stat.filemode(st.st_mode),
+                        }
+                    )
+                except OSError:
+                    continue
+        except OSError as exc:
+            raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+        return {"entries": entries}
+
+    @router.get("/cat")
+    async def read_file(path: str) -> dict[str, str]:
+        resolved = _safe_validate(validator, path)
+
+        if not os.path.exists(resolved):
+            raise HTTPException(status_code=404, detail="Path not found")
+        if not os.path.isfile(resolved):
+            raise HTTPException(status_code=400, detail="Path is not a file")
+
+        try:
+            with open(resolved, "r", encoding="utf-8", errors="replace") as fh:
+                content = fh.read()
+        except OSError as exc:
+            raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+        return {"content": content}
+
+    @router.get("/stat")
+    async def stat_path(path: str) -> dict[str, Any]:
+        resolved = _safe_validate(validator, path)
+
+        if not os.path.exists(resolved):
+            raise HTTPException(status_code=404, detail="Path not found")
+
+        try:
+            return _stat_entry(resolved)
+        except OSError as exc:
+            raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    @router.get("/download")
+    async def download_file(path: str) -> FileResponse:
+        resolved = _safe_validate(validator, path)
+
+        if not os.path.exists(resolved):
+            raise HTTPException(status_code=404, detail="Path not found")
+        if not os.path.isfile(resolved):
+            raise HTTPException(status_code=400, detail="Path is not a file")
+
+        filename = os.path.basename(resolved)
+        return FileResponse(
+            resolved,
+            filename=filename,
+            media_type="application/octet-stream",
+        )
+
+    @router.post("/upload")
+    async def upload_file(
+        file: UploadFile = File(...),
+        path: str = Form(...),
+    ) -> dict[str, str]:
+        resolved = _safe_validate(validator, path)
+
+        parent = os.path.dirname(resolved)
+        if not os.path.isdir(parent):
+            raise HTTPException(
+                status_code=400, detail="Parent directory does not exist"
+            )
+
+        try:
+            contents = await file.read()
+            with open(resolved, "wb") as fh:
+                fh.write(contents)
+        except OSError as exc:
+            raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+        return {"path": resolved, "status": "uploaded"}
+
+    @router.post("/mkdir")
+    async def make_directory(body: dict[str, str]) -> dict[str, str]:
+        raw_path = body.get("path")
+        if not raw_path:
+            raise HTTPException(status_code=400, detail="'path' is required")
+
+        resolved = _safe_validate(validator, raw_path)
+
+        try:
+            os.makedirs(resolved, exist_ok=True)
+        except OSError as exc:
+            raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+        return {"path": resolved, "status": "created"}
+
+    @router.delete("/rm")
+    async def remove_path(path: str) -> dict[str, str]:
+        resolved = _safe_validate(validator, path)
+
+        if not os.path.exists(resolved):
+            raise HTTPException(status_code=404, detail="Path not found")
+
+        try:
+            if os.path.isdir(resolved):
+                shutil.rmtree(resolved)
+            else:
+                os.remove(resolved)
+        except OSError as exc:
+            raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+        return {"path": resolved, "status": "deleted"}
+
+    return router

qodalis_cli/create_cli_server.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from typing import Callable
+
+from fastapi import FastAPI, WebSocket
+from fastapi.middleware.cors import CORSMiddleware
+
+from qodalis_cli_filesystem.providers.os_provider import OsFileStorageProvider, OsProviderOptions
+
+from .controllers import create_cli_router, create_cli_router_v2, create_cli_version_router
+from .controllers.filesystem_controller import create_filesystem_router
+from .extensions import CliBuilder
+from .filesystem import FileSystemPathValidator
+from .services import (
+    CliCommandExecutorService,
+    CliCommandRegistry,
+    CliEventSocketManager,
+    CliLogSocketManager,
+    CliShellSessionManager,
+    WebSocketLogHandler,
+)
+
+
+@dataclass
+class CliServerOptions:
+    base_path: str = "/api/cli"
+    cors: bool = True
+    cors_origins: list[str] = field(default_factory=lambda: ["*"])
+    configure: Callable[[CliBuilder], None] | None = None
+
+
+@dataclass
+class CliServerResult:
+    app: FastAPI
+    registry: CliCommandRegistry
+    builder: CliBuilder
+    event_socket_manager: CliEventSocketManager
+    log_socket_manager: CliLogSocketManager
+
+
+def create_cli_server(options: CliServerOptions | None = None) -> CliServerResult:
+    opts = options or CliServerOptions()
+
+    event_socket_manager = CliEventSocketManager()
+    log_socket_manager = CliLogSocketManager()
+    shell_session_manager = CliShellSessionManager()
+
+    # Attach a log handler that forwards to WebSocket clients
+    log_handler = WebSocketLogHandler(log_socket_manager)
+    logging.getLogger().addHandler(log_handler)
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        yield
+        await event_socket_manager.broadcast_disconnect()
+        await log_socket_manager.broadcast_disconnect()
+        logging.getLogger().removeHandler(log_handler)
+
+    app = FastAPI(title="Qodalis CLI Server", lifespan=lifespan)
+
+    if opts.cors:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=opts.cors_origins,
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+    registry = CliCommandRegistry()
+    builder = CliBuilder(registry)
+
+    if opts.configure:
+        opts.configure(builder)
+
+    executor = CliCommandExecutorService(registry)
+    router = create_cli_router(registry, executor)
+    router_v2 = create_cli_router_v2(registry, executor)
+    version_router = create_cli_version_router()
+
+    # API v1 routes
+    app.include_router(router, prefix="/api/v1/cli")
+
+    # API v2 routes
+    app.include_router(router_v2, prefix="/api/v2/cli")
+
+    # Version discovery routes
+    app.include_router(version_router, prefix="/api/cli")
+
+    # Custom basePath fallback (when user overrides the default)
+    if opts.base_path != "/api/v1/cli":
+        app.include_router(router, prefix=opts.base_path)
+
+    # Filesystem API (opt-in via builder.set_file_storage_provider() or
+    # legacy builder.add_filesystem())
+    if builder.file_storage_provider is not None:
+        fs_router = create_filesystem_router(builder.file_storage_provider)
+        app.include_router(fs_router, prefix="/api/cli/fs")
+    elif builder.filesystem_options is not None:
+        # Legacy path: create an OsFileStorageProvider from the options
+        os_provider = OsFileStorageProvider(
+            OsProviderOptions(
+                allowed_paths=builder.filesystem_options.allowed_paths
+            )
+        )
+        fs_router = create_filesystem_router(os_provider)
+        app.include_router(fs_router, prefix="/api/cli/fs")
+
+    # WebSocket event stream
+    @app.websocket("/ws/v1/cli/events")
+    async def websocket_events_v1(websocket: WebSocket) -> None:
+        await event_socket_manager.handle_connection(websocket)
+
+    @app.websocket("/ws/cli/events")
+    async def websocket_events(websocket: WebSocket) -> None:
+        await event_socket_manager.handle_connection(websocket)
+
+    # Log WebSocket endpoints
+    async def _handle_logs(websocket: WebSocket) -> None:
+        level_filter = websocket.query_params.get("level") or None
+        await log_socket_manager.handle_connection(websocket, level_filter)
+
+    @app.websocket("/ws/v1/cli/logs")
+    async def websocket_logs_v1(websocket: WebSocket) -> None:
+        await _handle_logs(websocket)
+
+    @app.websocket("/ws/cli/logs")
+    async def websocket_logs(websocket: WebSocket) -> None:
+        await _handle_logs(websocket)
+
+    # Shell WebSocket endpoints
+    async def _handle_shell(websocket: WebSocket) -> None:
+        await websocket.accept()
+        cols = int(websocket.query_params.get("cols", "80")) or 80
+        rows = int(websocket.query_params.get("rows", "24")) or 24
+        cmd = websocket.query_params.get("cmd") or None
+        await shell_session_manager.handle_session(websocket, cols, rows, cmd)
+
+    @app.websocket("/ws/v1/cli/shell")
+    async def websocket_shell_v1(websocket: WebSocket) -> None:
+        await _handle_shell(websocket)
+
+    @app.websocket("/ws/cli/shell")
+    async def websocket_shell(websocket: WebSocket) -> None:
+        await _handle_shell(websocket)
+
+    return CliServerResult(
+        app=app,
+        registry=registry,
+        builder=builder,
+        event_socket_manager=event_socket_manager,
+        log_socket_manager=log_socket_manager,
+    )

qodalis_cli/extensions/__init__.py

@@ -0,0 +1,3 @@
+from .cli_builder import CliBuilder
+
+__all__ = ["CliBuilder"]

qodalis_cli/extensions/cli_builder.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..abstractions import ICliCommandProcessor, ICliModule
+from ..filesystem import FileSystemOptions
+from ..services.cli_command_registry import CliCommandRegistry
+
+if TYPE_CHECKING:
+    from qodalis_cli_filesystem import IFileStorageProvider
+
+
+class CliBuilder:
+    def __init__(self, registry: CliCommandRegistry) -> None:
+        self._registry = registry
+        self._filesystem_options: FileSystemOptions | None = None
+        self._file_storage_provider: IFileStorageProvider | None = None
+
+    def add_processor(self, processor: ICliCommandProcessor) -> CliBuilder:
+        self._registry.register(processor)
+        return self
+
+    def add_module(self, module: ICliModule) -> CliBuilder:
+        for processor in module.processors:
+            self._registry.register(processor)
+        return self
+
+    def add_filesystem(self, options: FileSystemOptions) -> CliBuilder:
+        """Enable the filesystem API with the given options (legacy)."""
+        self._filesystem_options = options
+        return self
+
+    def set_file_storage_provider(
+        self, provider: IFileStorageProvider
+    ) -> CliBuilder:
+        """Set a custom file storage provider for the filesystem API."""
+        self._file_storage_provider = provider
+        return self
+
+    @property
+    def file_storage_provider(self) -> IFileStorageProvider | None:
+        """Return the configured file storage provider, if any."""
+        return self._file_storage_provider
+
+    @property
+    def filesystem_options(self) -> FileSystemOptions | None:
+        return self._filesystem_options
+
+    @property
+    def registry(self) -> CliCommandRegistry:
+        return self._registry

qodalis_cli/filesystem/__init__.py

@@ -0,0 +1,4 @@
+from .filesystem_options import FileSystemOptions
+from .filesystem_path_validator import FileSystemPathValidator
+
+__all__ = ["FileSystemOptions", "FileSystemPathValidator"]

qodalis_cli/filesystem/filesystem_options.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class FileSystemOptions:
+    """Configuration for the filesystem API.
+
+    Attributes:
+        allowed_paths: List of absolute directory paths that clients are
+            permitted to access.  Every requested path is resolved and
+            checked against this whitelist before any I/O is performed.
+    """
+
+    allowed_paths: list[str] = field(default_factory=list)

qodalis_cli/filesystem/filesystem_path_validator.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import os
+
+
+class FileSystemPathValidator:
+    """Validates that requested paths fall within an allowed whitelist.
+
+    Every path is resolved to its real, absolute form (following symlinks)
+    before the check, which prevents path-traversal attacks.
+    """
+
+    def __init__(self, allowed_paths: list[str]) -> None:
+        # Pre-resolve allowed roots so comparisons are consistent.
+        self._allowed_paths: list[str] = [
+            os.path.realpath(p) for p in allowed_paths
+        ]
+
+    @property
+    def allowed_paths(self) -> list[str]:
+        return list(self._allowed_paths)
+
+    def validate(self, path: str) -> str:
+        """Resolve *path* and verify it lives under an allowed root.
+
+        Returns:
+            The resolved absolute path on success.
+
+        Raises:
+            PermissionError: If the resolved path is not within any
+                allowed directory.
+        """
+        resolved = os.path.realpath(path)
+
+        for allowed in self._allowed_paths:
+            # Use os.sep to ensure "/tmp/evil" doesn't match "/tmp/ev"
+            if resolved == allowed or resolved.startswith(allowed + os.sep):
+                return resolved
+
+        raise PermissionError(
+            f"Access denied: '{path}' is outside the allowed paths"
+        )

qodalis_cli/models/__init__.py

@@ -0,0 +1,13 @@
+from .cli_server_output import CliServerOutput
+from .cli_server_response import CliServerResponse
+from .cli_server_command_descriptor import (
+    CliServerCommandDescriptor,
+    CliServerCommandParameterDescriptorDto,
+)
+
+__all__ = [
+    "CliServerOutput",
+    "CliServerResponse",
+    "CliServerCommandDescriptor",
+    "CliServerCommandParameterDescriptorDto",
+]

qodalis_cli/models/cli_server_command_descriptor.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class CliServerCommandParameterDescriptorDto(BaseModel):
+    name: str
+    description: str
+    required: bool = False
+    type: str = "string"
+    aliases: list[str] | None = None
+    default_value: Any = Field(alias="defaultValue", default=None)
+
+    model_config = {"populate_by_name": True}
+
+
+class CliServerCommandDescriptor(BaseModel):
+    command: str
+    description: str
+    version: str = "1.0.0"
+    api_version: int | None = Field(alias="apiVersion", default=None)
+    parameters: list[CliServerCommandParameterDescriptorDto] | None = None
+    processors: list["CliServerCommandDescriptor"] | None = None
+    allow_unlisted_commands: bool | None = Field(alias="allowUnlistedCommands", default=None)
+    value_required: bool | None = Field(alias="valueRequired", default=None)
+    author: dict[str, str] | None = None
+
+    model_config = {"populate_by_name": True}