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

qodalis_cli_server_plugin_admin-1.0.0b1/.gitignore

@@ -0,0 +1,2 @@
+# Generated dashboard files (copied by scripts/copy_dashboard.py)
+qodalis_cli_admin/dashboard/

qodalis_cli_server_plugin_admin-1.0.0b1/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: qodalis-cli-server-plugin-admin
+Version: 1.0.0b1
+Summary: Admin dashboard plugin for Qodalis CLI servers
+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
+Keywords: admin,cli,dashboard,plugin,qodalis
+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
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: pyjwt>=2.0.0

qodalis_cli_server_plugin_admin-1.0.0b1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qodalis-cli-server-plugin-admin"
+version = "1.0.0b1"
+description = "Admin dashboard plugin for Qodalis CLI servers"
+readme = { text = "", content-type = "text/plain" }
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Nicolae Lupei", email = "nicolae.lupei@qodalis.com" },
+]
+keywords = ["cli", "qodalis", "admin", "dashboard", "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",
+]
+dependencies = [
+    "PyJWT>=2.0.0",
+    "fastapi>=0.100.0",
+    "psutil>=5.9.0",
+]
+
+[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_admin"]
+
+[tool.hatch.build.targets.sdist]
+include = ["qodalis_cli_admin/**"]
+
+[tool.hatch.build]
+artifacts = ["qodalis_cli_admin/dashboard/**"]

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/__init__.py

@@ -0,0 +1,24 @@
+"""Qodalis CLI admin plugin — admin dashboard for CLI servers."""
+
+from .cli_admin_builder import CliAdminBuilder, CliAdminPlugin, AdminBuildDeps, BroadcastFn
+from .auth.jwt_service import JwtService
+from .auth.auth_middleware import create_auth_dependency
+from .auth.auth_controller import create_auth_router
+from .dashboard_resolver import resolve_dashboard_dir
+from .services.admin_config import AdminConfig
+from .services.log_ring_buffer import LogRingBuffer
+from .services.module_registry import ModuleRegistry
+
+__all__ = [
+    "AdminBuildDeps",
+    "AdminConfig",
+    "BroadcastFn",
+    "CliAdminBuilder",
+    "CliAdminPlugin",
+    "JwtService",
+    "LogRingBuffer",
+    "ModuleRegistry",
+    "create_auth_dependency",
+    "create_auth_router",
+    "resolve_dashboard_dir",
+]

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/auth/__init__.py

@@ -0,0 +1,12 @@
+"""Admin authentication — JWT service, middleware, and auth controller."""
+
+from .jwt_service import JwtService
+from .auth_middleware import create_auth_dependency, require_auth
+from .auth_controller import create_auth_router
+
+__all__ = [
+    "JwtService",
+    "create_auth_dependency",
+    "create_auth_router",
+    "require_auth",
+]

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/auth/auth_controller.py

@@ -0,0 +1,103 @@
+"""Authentication controller — login and ``/me`` endpoints."""
+
+from __future__ import annotations
+
+import time
+from collections import defaultdict
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel
+
+from .jwt_service import JwtService
+from ..services.admin_config import AdminConfig
+
+
+# ---------------------------------------------------------------------------
+# Request / Response models
+# ---------------------------------------------------------------------------
+
+
+class LoginRequest(BaseModel):
+    username: str
+    password: str
+
+
+class LoginResponse(BaseModel):
+    token: str
+    expiresIn: int
+    username: str
+
+
+# ---------------------------------------------------------------------------
+# Rate limiting helpers
+# ---------------------------------------------------------------------------
+
+_MAX_ATTEMPTS = 5
+_WINDOW_SECONDS = 60
+
+
+class _RateLimiter:
+    """Simple in-memory per-IP rate limiter for failed login attempts."""
+
+    def __init__(self) -> None:
+        self._attempts: dict[str, list[float]] = defaultdict(list)
+
+    def check(self, ip: str) -> None:
+        """Raise ``HTTPException(429)`` if the IP has exceeded the limit."""
+        now = time.time()
+        cutoff = now - _WINDOW_SECONDS
+        # Clean old entries
+        self._attempts[ip] = [t for t in self._attempts[ip] if t > cutoff]
+        if len(self._attempts[ip]) >= _MAX_ATTEMPTS:
+            raise HTTPException(status_code=429, detail="Too many failed login attempts. Try again later.")
+
+    def record_failure(self, ip: str) -> None:
+        self._attempts[ip].append(time.time())
+
+
+# ---------------------------------------------------------------------------
+# Router factory
+# ---------------------------------------------------------------------------
+
+
+def create_auth_router(
+    admin_config: AdminConfig,
+    jwt_service: JwtService,
+    auth_dependency: Any = None,
+) -> APIRouter:
+    """Create a FastAPI router with ``POST /login`` and ``GET /me``."""
+    router = APIRouter()
+    limiter = _RateLimiter()
+
+    @router.post("/login", response_model=LoginResponse)
+    async def login(body: LoginRequest, request: Request) -> Any:
+        # Check X-Forwarded-For header for real client IP behind proxy
+        forwarded_for = request.headers.get("x-forwarded-for")
+        if forwarded_for:
+            client_ip = forwarded_for.split(",")[0].strip()
+        else:
+            client_ip = request.client.host if request.client else "127.0.0.1"
+        limiter.check(client_ip)
+
+        if not admin_config.validate_credentials(body.username, body.password):
+            limiter.record_failure(client_ip)
+            raise HTTPException(status_code=401, detail="Invalid credentials")
+
+        expires_in = JwtService.DEFAULT_EXPIRY_SECONDS
+        token = jwt_service.sign_token(
+            {"username": body.username, "authenticatedAt": int(time.time())},
+            expires_in=expires_in,
+        )
+
+        return LoginResponse(token=token, expiresIn=expires_in, username=body.username)
+
+    if auth_dependency is not None:
+        @router.get("/me")
+        async def me(payload: dict[str, Any] = Depends(auth_dependency)) -> dict[str, Any]:
+            return {
+                "username": payload.get("username", ""),
+                "authenticatedAt": payload.get("authenticatedAt"),
+            }
+
+    return router

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/auth/auth_middleware.py

@@ -0,0 +1,43 @@
+"""FastAPI dependency for JWT authentication."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import jwt
+from fastapi import Request, HTTPException
+
+from .jwt_service import JwtService
+
+
+def create_auth_dependency(jwt_service: JwtService):
+    """Return a FastAPI ``Depends`` callable that validates Bearer tokens."""
+
+    async def require_auth(request: Request) -> dict[str, Any]:
+        """Extract and verify the JWT Bearer token from the Authorization header.
+
+        Returns the decoded payload on success; raises ``HTTPException(401)``
+        otherwise.
+        """
+        auth_header = request.headers.get("Authorization", "")
+
+        if not auth_header.startswith("Bearer "):
+            raise HTTPException(status_code=401, detail="Missing or invalid Authorization header")
+
+        token = auth_header[7:]
+
+        try:
+            payload = jwt_service.verify_token(token)
+        except jwt.InvalidTokenError:
+            raise HTTPException(status_code=401, detail="Invalid or expired token")
+
+        return payload
+
+    return require_auth
+
+
+# Convenience alias — requires a JwtService instance to be set externally.
+# Prefer ``create_auth_dependency(jwt_service)`` for production use.
+async def require_auth(request: Request) -> dict[str, Any]:  # noqa: F811
+    """Placeholder — use :func:`create_auth_dependency` to create a real dependency."""
+    raise HTTPException(status_code=401, detail="Auth not configured")

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/auth/jwt_service.py

@@ -0,0 +1,55 @@
+"""JWT token generation and validation using PyJWT."""
+
+from __future__ import annotations
+
+import os
+import secrets
+import time
+from typing import Any
+
+import jwt
+
+
+class JwtService:
+    """Thin wrapper around PyJWT for signing and verifying tokens."""
+
+    DEFAULT_EXPIRY_SECONDS = 24 * 60 * 60  # 24 hours
+
+    def __init__(self, secret: str = "") -> None:
+        self._secret = (
+            secret
+            or os.environ.get("QCLI_ADMIN_JWT_SECRET", "")
+            or secrets.token_hex(32)
+        )
+
+    @property
+    def secret(self) -> str:
+        return self._secret
+
+    def sign_token(
+        self,
+        payload: dict[str, Any],
+        expires_in: int | None = None,
+    ) -> str:
+        """Create a signed JWT token.
+
+        Parameters
+        ----------
+        payload:
+            Claims to embed in the token.
+        expires_in:
+            Lifetime in seconds.  Defaults to 24 hours.
+        """
+        exp = int(time.time()) + (self.DEFAULT_EXPIRY_SECONDS if expires_in is None else expires_in)
+        data = {**payload, "exp": exp, "iat": int(time.time())}
+        return jwt.encode(data, self._secret, algorithm="HS256")
+
+    def verify_token(self, token: str) -> dict[str, Any]:
+        """Decode and verify a JWT token.
+
+        Raises
+        ------
+        jwt.InvalidTokenError
+            If the token is invalid or expired.
+        """
+        return jwt.decode(token, self._secret, algorithms=["HS256"])

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/cli_admin_builder.py

@@ -0,0 +1,146 @@
+"""Fluent builder for configuring and creating the admin plugin."""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass
+from typing import Any, Callable, Awaitable
+
+from fastapi import APIRouter
+from .spa_static_files import SPAStaticFiles
+
+from .auth.jwt_service import JwtService
+from .auth.auth_middleware import create_auth_dependency
+from .auth.auth_controller import create_auth_router
+from .controllers.status_controller import create_status_router
+from .controllers.plugins_controller import create_plugins_router
+from .controllers.config_controller import create_config_router
+from .controllers.logs_controller import create_logs_router
+from .controllers.ws_clients_controller import create_ws_clients_router
+from .services.admin_config import AdminConfig
+from .services.log_ring_buffer import LogRingBuffer
+from .services.module_registry import ModuleRegistry
+from .dashboard_resolver import resolve_dashboard_dir
+
+
+BroadcastFn = Callable[[str], Awaitable[None]]
+
+
+@dataclass
+class AdminBuildDeps:
+    """Dependencies required to build the admin plugin."""
+
+    registry: Any  # CliCommandRegistry
+    event_socket_manager: Any  # CliEventSocketManager
+    builder: Any  # CliBuilder
+    broadcast_fn: BroadcastFn | None = None
+    enabled_features: list[str] | None = None
+
+
+@dataclass
+class CliAdminPlugin:
+    """Result of building the admin plugin."""
+
+    router: APIRouter
+    auth_dependency: Any
+    log_buffer: LogRingBuffer
+    dashboard_app: Any  # ASGI app (SPA fallback) or None
+
+
+class CliAdminBuilder:
+    """Fluent builder for the admin dashboard plugin."""
+
+    def __init__(self) -> None:
+        self._username: str = ""
+        self._password: str = ""
+        self._jwt_secret: str = ""
+        self._dashboard_path: str | None = None
+
+    def set_credentials(self, username: str, password: str) -> CliAdminBuilder:
+        """Set admin login credentials (overrides env vars)."""
+        self._username = username
+        self._password = password
+        return self
+
+    def set_jwt_secret(self, secret: str) -> CliAdminBuilder:
+        """Set the JWT signing secret (overrides env var)."""
+        self._jwt_secret = secret
+        return self
+
+    def set_dashboard_path(self, path: str) -> CliAdminBuilder:
+        """Set an explicit path to the dashboard dist directory."""
+        self._dashboard_path = path
+        return self
+
+    def build(self, deps: AdminBuildDeps) -> CliAdminPlugin:
+        """Build the plugin, returning the router, auth dependency, and log buffer."""
+        start_time = time.time()
+
+        # Services
+        config = AdminConfig(
+            username=self._username,
+            password=self._password,
+            jwt_secret=self._jwt_secret,
+        )
+        jwt_service = JwtService(secret=config.jwt_secret)
+        log_buffer = LogRingBuffer(broadcast_fn=deps.broadcast_fn)
+        log_buffer.install_handler()
+        module_registry = ModuleRegistry(deps.builder)
+        auth_dep = create_auth_dependency(jwt_service)
+
+        # Build the top-level router
+        router = APIRouter()
+
+        # Auth routes (login is public, /me is protected)
+        auth_router = create_auth_router(config, jwt_service, auth_dependency=auth_dep)
+        router.include_router(auth_router, prefix="/auth")
+
+        # Detect enabled features
+        enabled_features: list[str] = list(deps.enabled_features or [])
+
+        if "filesystem" not in enabled_features and (
+            getattr(deps.builder, "file_storage_provider", None) is not None
+            or getattr(deps.builder, "filesystem_options", None) is not None
+        ):
+            enabled_features.append("filesystem")
+
+        if "jobs" not in enabled_features:
+            for mod in getattr(deps.builder, "modules", []):
+                mod_name = type(mod).__name__.lower()
+                if "job" in mod_name:
+                    enabled_features.append("jobs")
+                    break
+
+        # Protected routes
+        status_router = create_status_router(
+            start_time, deps.event_socket_manager, auth_dep, enabled_features,
+            registry=deps.registry,
+        )
+        router.include_router(status_router)
+
+        plugins_router = create_plugins_router(module_registry, auth_dep)
+        router.include_router(plugins_router)
+
+        config_router = create_config_router(config, auth_dep)
+        router.include_router(config_router)
+
+        logs_router = create_logs_router(log_buffer, auth_dep)
+        router.include_router(logs_router)
+
+        ws_clients_router = create_ws_clients_router(deps.event_socket_manager, auth_dep)
+        router.include_router(ws_clients_router)
+
+        # Resolve dashboard SPA
+        dashboard_dir = resolve_dashboard_dir(self._dashboard_path)
+        dashboard_app = None
+
+        if dashboard_dir:
+            dashboard_app = SPAStaticFiles(directory=dashboard_dir, html=True)
+
+        return CliAdminPlugin(
+            router=router,
+            auth_dependency=auth_dep,
+            log_buffer=log_buffer,
+            dashboard_app=dashboard_app,
+        )

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/controllers/__init__.py

@@ -0,0 +1,15 @@
+"""Admin dashboard controllers."""
+
+from .status_controller import create_status_router
+from .plugins_controller import create_plugins_router
+from .config_controller import create_config_router
+from .logs_controller import create_logs_router
+from .ws_clients_controller import create_ws_clients_router
+
+__all__ = [
+    "create_config_router",
+    "create_logs_router",
+    "create_plugins_router",
+    "create_status_router",
+    "create_ws_clients_router",
+]

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/controllers/config_controller.py

@@ -0,0 +1,38 @@
+"""Configuration controller — read and update admin settings."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+
+from ..services.admin_config import AdminConfig
+
+
+class UpdateConfigRequest(BaseModel):
+    settings: dict[str, Any]
+
+
+def create_config_router(
+    admin_config: AdminConfig,
+    auth_dependency: Any,
+) -> APIRouter:
+    """Create a router with ``GET /config`` and ``PUT /config``."""
+    router = APIRouter()
+
+    @router.get("/config")
+    async def get_config(
+        _user: dict[str, Any] = Depends(auth_dependency),
+    ) -> dict[str, Any]:
+        return {"sections": admin_config.get_config_sections()}
+
+    @router.put("/config")
+    async def update_config(
+        body: UpdateConfigRequest,
+        _user: dict[str, Any] = Depends(auth_dependency),
+    ) -> dict[str, Any]:
+        admin_config.update_settings(body.settings)
+        return {"message": "Configuration updated", "sections": admin_config.get_config_sections()}
+
+    return router

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/controllers/logs_controller.py

@@ -0,0 +1,40 @@
+"""Logs controller — query the log ring buffer."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends, Query
+
+from ..services.log_ring_buffer import LogRingBuffer
+
+
+def create_logs_router(
+    log_buffer: LogRingBuffer,
+    auth_dependency: Any,
+) -> APIRouter:
+    """Create a router with ``GET /logs``."""
+    router = APIRouter()
+
+    @router.get("/logs")
+    async def get_logs(
+        _user: dict[str, Any] = Depends(auth_dependency),
+        level: str | None = Query(None),
+        search: str | None = Query(None),
+        limit: int = Query(100, le=1000),
+        offset: int = Query(0, ge=0),
+    ) -> dict[str, Any]:
+        items, total = log_buffer.query(
+            level=level,
+            search=search,
+            limit=limit,
+            offset=offset,
+        )
+        return {
+            "entries": items,
+            "total": total,
+            "limit": limit,
+            "offset": offset,
+        }
+
+    return router

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/controllers/plugins_controller.py

@@ -0,0 +1,39 @@
+"""Plugins controller — list and toggle registered modules."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends
+from fastapi.responses import JSONResponse
+
+from ..services.module_registry import ModuleRegistry
+
+
+def create_plugins_router(
+    module_registry: ModuleRegistry,
+    auth_dependency: Any,
+) -> APIRouter:
+    """Create a router with ``GET /plugins`` and ``POST /plugins/{id}/toggle``."""
+    router = APIRouter()
+
+    @router.get("/plugins")
+    async def list_plugins(
+        _user: dict[str, Any] = Depends(auth_dependency),
+    ) -> list[dict[str, Any]]:
+        return module_registry.list()
+
+    @router.post("/plugins/{plugin_id}/toggle")
+    async def toggle_plugin(
+        plugin_id: str,
+        _user: dict[str, Any] = Depends(auth_dependency),
+    ) -> Any:
+        try:
+            return module_registry.toggle(plugin_id)
+        except (KeyError, ValueError):
+            return JSONResponse(
+                status_code=404,
+                content={"error": "Plugin not found", "code": "PLUGIN_NOT_FOUND"},
+            )
+
+    return router

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/controllers/status_controller.py

@@ -0,0 +1,56 @@
+"""Status controller — server health and runtime information."""
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+import psutil
+from fastapi import APIRouter, Depends
+
+
+def create_status_router(
+    start_time: float,
+    event_socket_manager: Any,
+    auth_dependency: Any,
+    enabled_features: list[str] | None = None,
+    registry: Any = None,
+) -> APIRouter:
+    """Create a router that exposes ``GET /status``."""
+    router = APIRouter()
+
+    @router.get("/status")
+    async def get_status(
+        _user: dict[str, Any] = Depends(auth_dependency),
+    ) -> dict[str, Any]:
+        uptime_seconds = time.time() - start_time
+
+        proc = psutil.Process(os.getpid())
+        mem_info = proc.memory_info()
+        memory_usage_mb = mem_info.rss / (1024 * 1024)
+
+        started_at = datetime.fromtimestamp(
+            start_time, tz=timezone.utc
+        ).isoformat()
+
+        registered_commands = len(registry.processors) if registry is not None else 0
+
+        return {
+            "uptimeSeconds": uptime_seconds,
+            "memoryUsageMb": round(memory_usage_mb, 2),
+            "startedAt": started_at,
+            "platform": "python",
+            "platformVersion": platform.python_version(),
+            "os": f"{platform.system()} {platform.release()}",
+            "activeWsConnections": len(event_socket_manager.get_clients()),
+            "activeShellSessions": 0,
+            "registeredCommands": registered_commands,
+            "registeredJobs": 0,
+            "enabledFeatures": enabled_features or [],
+        }
+
+    return router

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/controllers/ws_clients_controller.py

@@ -0,0 +1,23 @@
+"""WebSocket clients controller — list connected WS clients."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends
+
+
+def create_ws_clients_router(
+    event_socket_manager: Any,
+    auth_dependency: Any,
+) -> APIRouter:
+    """Create a router with ``GET /ws/clients``."""
+    router = APIRouter()
+
+    @router.get("/ws/clients")
+    async def get_ws_clients(
+        _user: dict[str, Any] = Depends(auth_dependency),
+    ) -> list[dict[str, Any]]:
+        return event_socket_manager.get_clients()
+
+    return router

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/dashboard_resolver.py

@@ -0,0 +1,45 @@
+"""Resolves the dashboard dist directory at runtime."""
+
+import os
+from pathlib import Path
+
+
+def resolve_dashboard_dir(explicit_path: str | None = None) -> str | None:
+    """
+    Resolve the dashboard dist directory. Looks for:
+    1. Explicitly configured path
+    2. Bundled dashboard directory (embedded in this package)
+    3. node_modules/@qodalis/cli-server-dashboard/dist (npm package)
+    4. Relative development paths (sibling repo)
+    """
+    # 1. Explicit override
+    if explicit_path and os.path.isdir(explicit_path):
+        return os.path.abspath(explicit_path)
+
+    # 2. Bundled dashboard directory (embedded in this package)
+    bundled = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'dashboard')
+    if os.path.isdir(bundled):
+        return bundled
+
+    # 3. npm package — search upwards from cwd for node_modules
+    current = os.getcwd()
+    while current != os.path.dirname(current):
+        candidate = os.path.join(
+            current, "node_modules", "@qodalis", "cli-server-dashboard", "dist"
+        )
+        if os.path.isdir(candidate):
+            return os.path.abspath(candidate)
+        current = os.path.dirname(current)
+
+    # 4. Relative development paths
+    this_dir = os.path.dirname(os.path.abspath(__file__))
+    dev_paths = [
+        os.path.join(this_dir, "..", "..", "..", "..", "cli-server-dashboard", "dist"),
+        os.path.join(os.getcwd(), "..", "cli-server-dashboard", "dist"),
+    ]
+
+    for path in dev_paths:
+        if os.path.isdir(path):
+            return os.path.abspath(path)
+
+    return None

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/services/__init__.py

@@ -0,0 +1,11 @@
+"""Admin plugin services."""
+
+from .admin_config import AdminConfig
+from .log_ring_buffer import LogRingBuffer
+from .module_registry import ModuleRegistry
+
+__all__ = [
+    "AdminConfig",
+    "LogRingBuffer",
+    "ModuleRegistry",
+]

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/services/admin_config.py

@@ -0,0 +1,114 @@
+"""Admin configuration — reads credentials from environment variables."""
+
+from __future__ import annotations
+
+import hmac
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+logger = logging.getLogger("qcli-admin")
+
+
+@dataclass
+class AdminConfig:
+    """Holds admin dashboard configuration.
+
+    Credentials default to ``QCLI_ADMIN_USERNAME`` / ``QCLI_ADMIN_PASSWORD``
+    environment variables, falling back to ``admin`` / ``admin``.
+    """
+
+    username: str = ""
+    password: str = ""
+    jwt_secret: str = ""
+
+    # Mutable runtime settings
+    _mutable_settings: dict[str, Any] = field(default_factory=dict)
+
+    FORBIDDEN_KEYS: frozenset[str] = frozenset(
+        {"username", "password", "jwt_secret", "jwtSecret"}
+    )
+
+    def __post_init__(self) -> None:
+        if not self.username:
+            self.username = os.environ.get("QCLI_ADMIN_USERNAME", "admin")
+        if not self.password:
+            self.password = os.environ.get("QCLI_ADMIN_PASSWORD", "admin")
+        if not self.jwt_secret:
+            self.jwt_secret = os.environ.get("QCLI_ADMIN_JWT_SECRET", "")
+
+        if self.username == "admin" and self.password == "admin":
+            logger.warning(
+                "Using default admin credentials. Set QCLI_ADMIN_USERNAME"
+                " and QCLI_ADMIN_PASSWORD environment variables."
+            )
+
+    def validate_credentials(self, username: str, password: str) -> bool:
+        """Return *True* if the supplied credentials match."""
+        username_ok = hmac.compare_digest(username, self.username)
+        password_ok = hmac.compare_digest(password, self.password)
+        return username_ok and password_ok
+
+    def get_config_sections(self) -> list[dict[str, Any]]:
+        """Return structured configuration sections for the admin API."""
+        import platform as _platform
+        import sys as _sys
+
+        custom_entries = [
+            {
+                "key": k,
+                "value": v,
+                "type": _infer_type(v),
+                "description": "",
+                "mutable": True,
+            }
+            for k, v in self._mutable_settings.items()
+        ]
+
+        return [
+            {
+                "name": "server",
+                "mutable": False,
+                "settings": [
+                    {"key": "platform", "value": "python", "type": "string", "description": "Server platform", "mutable": False},
+                    {"key": "platformVersion", "value": _sys.version.split()[0], "type": "string", "description": "Python version", "mutable": False},
+                    {"key": "os", "value": _platform.platform(), "type": "string", "description": "Operating system", "mutable": False},
+                ],
+            },
+            {
+                "name": "auth",
+                "mutable": False,
+                "settings": [
+                    {"key": "username", "value": self.username, "type": "string", "description": "Admin username", "mutable": False},
+                    {"key": "jwtSecretConfigured", "value": bool(self.jwt_secret), "type": "boolean", "description": "Whether JWT secret is explicitly set", "mutable": False},
+                ],
+            },
+            {
+                "name": "custom",
+                "mutable": True,
+                "settings": custom_entries,
+            },
+        ]
+
+    def update_settings(self, settings: dict[str, Any]) -> None:
+        """Update mutable runtime settings.
+
+        Keys that overlap with sensitive configuration are silently rejected.
+        """
+        sanitized = {k: v for k, v in settings.items() if k not in self.FORBIDDEN_KEYS}
+        self._mutable_settings.update(sanitized)
+
+    def get_settings(self) -> dict[str, Any]:
+        """Return a copy of the current mutable runtime settings."""
+        return dict(self._mutable_settings)
+
+
+def _infer_type(val: Any) -> str:
+    if isinstance(val, bool):
+        return "boolean"
+    if isinstance(val, (int, float)):
+        return "number"
+    if isinstance(val, list):
+        return "string[]"
+    return "string"

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/services/log_ring_buffer.py

@@ -0,0 +1,127 @@
+"""Ring buffer for log entries with optional broadcast support."""
+
+from __future__ import annotations
+
+import logging
+from collections import deque
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Callable, Awaitable
+
+
+@dataclass
+class LogEntry:
+    """A single log entry."""
+
+    timestamp: str
+    level: str
+    message: str
+    logger_name: str = ""
+
+
+BroadcastFn = Callable[[str], Awaitable[None]]
+
+_LEVEL_MAP = {
+    "WARNING": "WARN",
+}
+
+
+def _normalize_level(level: str) -> str:
+    """Normalize Python log level names to SPA-expected short forms."""
+    return _LEVEL_MAP.get(level.upper(), level.upper())
+
+
+class LogRingBuffer:
+    """Fixed-size ring buffer that stores log entries.
+
+    Optionally captures records from Python's :mod:`logging` module via
+    :meth:`install_handler`.
+    """
+
+    def __init__(
+        self,
+        max_size: int = 1000,
+        broadcast_fn: BroadcastFn | None = None,
+    ) -> None:
+        self._buffer: deque[LogEntry] = deque(maxlen=max_size)
+        self._broadcast_fn = broadcast_fn
+        self._handler: _RingBufferHandler | None = None
+
+    # -- public API -----------------------------------------------------------
+
+    def add(self, entry: LogEntry) -> None:
+        """Append a log entry to the buffer."""
+        entry.level = (entry.level or "INFO").upper()
+        self._buffer.append(entry)
+
+    def query(
+        self,
+        *,
+        level: str | None = None,
+        search: str | None = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> tuple[list[dict[str, Any]], int]:
+        """Return matching entries and the total count (before pagination)."""
+        entries = list(self._buffer)
+
+        if level:
+            level_upper = level.upper()
+            # Support filtering by SPA-form "WARN" matching Python's "WARNING"
+            match_levels = {level_upper}
+            if level_upper == "WARN":
+                match_levels.add("WARNING")
+            entries = [e for e in entries if e.level in match_levels]
+
+        if search:
+            search_lower = search.lower()
+            entries = [e for e in entries if search_lower in e.message.lower()]
+
+        total = len(entries)
+        page = entries[offset: offset + limit]
+
+        return (
+            [
+                {
+                    "timestamp": e.timestamp,
+                    "level": _normalize_level(e.level),
+                    "message": e.message,
+                    "source": e.logger_name,
+                }
+                for e in page
+            ],
+            total,
+        )
+
+    # -- logging integration --------------------------------------------------
+
+    def install_handler(self, logger_name: str = "") -> None:
+        """Install a :class:`logging.Handler` that feeds into this buffer."""
+        if self._handler is not None:
+            return
+        self._handler = _RingBufferHandler(self)
+        logging.getLogger(logger_name).addHandler(self._handler)
+
+    def uninstall_handler(self, logger_name: str = "") -> None:
+        """Remove the previously installed handler."""
+        if self._handler is None:
+            return
+        logging.getLogger(logger_name).removeHandler(self._handler)
+        self._handler = None
+
+
+class _RingBufferHandler(logging.Handler):
+    """Logging handler that pushes records into a :class:`LogRingBuffer`."""
+
+    def __init__(self, ring: LogRingBuffer) -> None:
+        super().__init__()
+        self._ring = ring
+
+    def emit(self, record: logging.LogRecord) -> None:
+        entry = LogEntry(
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            level=record.levelname,
+            message=self.format(record),
+            logger_name=record.name,
+        )
+        self._ring.add(entry)

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/services/module_registry.py

@@ -0,0 +1,64 @@
+"""Module registry — reads modules from CliBuilder and tracks enabled state."""
+
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from qodalis_cli.extensions.cli_builder import CliBuilder
+
+
+class ModuleRegistry:
+    """Provides a read/toggle view over modules registered in :class:`CliBuilder`."""
+
+    def __init__(self, builder: CliBuilder) -> None:
+        self._builder = builder
+        self._disabled: set[str] = set()
+
+    def list(self) -> list[dict[str, Any]]:
+        """Return a list of all modules with their enabled/disabled state."""
+        result: list[dict[str, Any]] = []
+        for idx, module in enumerate(self._builder.modules):
+            module_id = str(idx)
+            name = getattr(module, "name", type(module).__name__)
+            result.append(
+                {
+                    "id": module_id,
+                    "name": name,
+                    "processorCount": len(module.processors),
+                    "processors": [p.command for p in module.processors],
+                    "enabled": module_id not in self._disabled,
+                }
+            )
+        return result
+
+    def toggle(self, module_id: str) -> dict[str, Any]:
+        """Toggle a module's enabled state and return the updated record."""
+        modules = self._builder.modules
+        idx = int(module_id)
+        if idx < 0 or idx >= len(modules):
+            raise KeyError(f"Module not found: {module_id}")
+
+        if module_id in self._disabled:
+            self._disabled.discard(module_id)
+            enabled = True
+        else:
+            self._disabled.add(module_id)
+            enabled = False
+
+        module = modules[idx]
+        result: dict[str, Any] = {
+            "id": module_id,
+            "name": getattr(module, "name", type(module).__name__),
+            "processorCount": len(module.processors),
+            "processors": [p.command for p in module.processors],
+            "enabled": enabled,
+        }
+
+        if not enabled:
+            result["warning"] = (
+                "Module state tracked but command unregistration is not yet"
+                " supported. Processors remain active."
+            )
+
+        return result

qodalis_cli_server_plugin_admin-1.0.0b1/qodalis_cli_admin/spa_static_files.py

@@ -0,0 +1,36 @@
+"""SPA-aware static file serving.
+
+Starlette's ``StaticFiles(html=True)`` only maps ``/`` to ``index.html``.
+For a single-page application we need *all* non-file routes to fall back to
+``index.html`` so that the client-side router can handle them.
+"""
+
+from __future__ import annotations
+
+import os
+
+from starlette.exceptions import HTTPException as StarletteHTTPException
+from starlette.responses import FileResponse, Response
+from starlette.staticfiles import StaticFiles
+from starlette.types import Scope
+
+
+class SPAStaticFiles(StaticFiles):
+    """StaticFiles subclass that falls back to ``index.html`` for missing paths.
+
+    This enables client-side routing: any request that doesn't match a real
+    file (e.g. ``/login``, ``/dashboard/settings``) is served the SPA shell
+    so the JS router can take over.
+    """
+
+    async def get_response(self, path: str, scope: Scope) -> Response:
+        try:
+            return await super().get_response(path, scope)
+        except StarletteHTTPException as exc:
+            if exc.status_code != 404:
+                raise
+            # File not found — serve index.html for SPA client-side routing
+            index = os.path.join(self.directory, "index.html")  # type: ignore[arg-type]
+            if os.path.isfile(index):
+                return FileResponse(index, media_type="text/html")
+            raise