vibe-coding-qa 0.5.0__py3-none-any.whl

dashboard/backend/config.py

@@ -0,0 +1,180 @@
+"""Runtime configuration for the dashboard backend.
+
+All settings are environment-driven so that credentials never live in the
+repository or reach the browser. ``get_settings`` is cached; tests call
+``reset_settings`` after mutating the environment.
+"""
+
+import os
+import sys
+from dataclasses import dataclass, field
+from functools import lru_cache
+from pathlib import Path
+
+
+BACKEND_DIR = Path(__file__).resolve().parent
+DASHBOARD_DIR = BACKEND_DIR.parent
+PROJECT_ROOT = DASHBOARD_DIR.parent
+
+# When the dashboard is installed as a package it lives in site-packages, so user
+# data (the SQLite database) must live in a writable, per-user location on the
+# user's own machine - never inside the installed package. Override with the
+# ``VCQA_DASHBOARD_DB`` environment variable.
+USER_DATA_DIR = Path.home() / ".vibe-coding-qa"
+DEFAULT_DB_PATH = USER_DATA_DIR / "vcqa.sqlite3"
+
+# The dashboard reuses the existing analysis engine in place; it is not a copy.
+# Put the project root on ``sys.path`` so ``import vibe_coding_qa`` works no
+# matter how the app is launched (``uvicorn``, ``python -m``, tests).
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+
+def _flag(name: str, default: bool = False) -> bool:
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _int(name: str, default: int) -> int:
+    raw = os.environ.get(name)
+    if raw is None or not raw.strip():
+        return default
+    try:
+        return int(raw)
+    except ValueError:
+        return default
+
+
+def _csv(name: str, default: list[str]) -> list[str]:
+    raw = os.environ.get(name)
+    if raw is None or not raw.strip():
+        return list(default)
+    return [part.strip() for part in raw.split(",") if part.strip()]
+
+
+def _roots(name: str, default: list[Path]) -> list[Path]:
+    raw = os.environ.get(name)
+    if raw is None or not raw.strip():
+        return list(default)
+    roots: list[Path] = []
+    for part in raw.split(os.pathsep):
+        part = part.strip()
+        if part:
+            roots.append(Path(part).expanduser())
+    return roots or list(default)
+
+
+@dataclass
+class Settings:
+    """Immutable-ish runtime settings resolved from the environment."""
+
+    host: str = "127.0.0.1"
+    port: int = 8756
+    db_path: Path = field(default_factory=lambda: DEFAULT_DB_PATH)
+
+    # Only localhost origins are allowed by default. The frontend dev server and
+    # the packaged static build are both served from localhost.
+    cors_origins: list[str] = field(
+        default_factory=lambda: [
+            "http://localhost:5173",
+            "http://127.0.0.1:5173",
+            "http://localhost:8756",
+            "http://127.0.0.1:8756",
+        ]
+    )
+
+    # Registering a local repository is restricted to these roots to prevent
+    # arbitrary filesystem access. Paths are resolved and checked against them.
+    allowed_repo_roots: list[Path] = field(
+        default_factory=lambda: [Path.home().resolve(), PROJECT_ROOT.resolve()]
+    )
+
+    max_concurrent_scans: int = 2
+    finding_page_size: int = 50
+    max_page_size: int = 200
+
+    # AI is entirely optional; the scanner and gate work without it.
+    ai_provider: str = ""
+    ai_api_key: str = ""
+    ai_base_url: str = "https://openrouter.ai/api/v1"
+    ai_model: str = "openai/gpt-3.5-turbo"
+    ai_timeout: int = 30
+    ai_max_output_tokens: int = 3000
+    ai_enable_source_context: bool = False
+    ai_max_requests_per_minute: int = 20
+    ai_max_input_chars: int = 40_000
+
+    github_token: str = ""
+
+    # Defaults surfaced to the scan UI (mirrors the CLI defaults).
+    default_scan_profile: str = "standard"
+    allow_test_execution: bool = False
+    default_test_image: str = "python:3.12-slim"
+    default_test_timeout: int = 300
+    default_max_memory_mb: int = 512
+    default_max_cpu_seconds: int = 60
+    default_max_snapshot_mb: int = 256
+    default_max_write_mb: int = 64
+    default_osv_enabled: bool = True
+
+
+def _build_settings() -> Settings:
+    return Settings(
+        host=os.environ.get("VCQA_DASHBOARD_HOST", "127.0.0.1"),
+        port=_int("VCQA_DASHBOARD_PORT", 8756),
+        db_path=Path(os.environ.get("VCQA_DASHBOARD_DB", str(DEFAULT_DB_PATH))).expanduser(),
+        cors_origins=_csv(
+            "VCQA_DASHBOARD_CORS",
+            [
+                "http://localhost:5173",
+                "http://127.0.0.1:5173",
+                "http://localhost:8756",
+                "http://127.0.0.1:8756",
+            ],
+        ),
+        allowed_repo_roots=_roots(
+            "VCQA_ALLOWED_REPO_ROOTS",
+            [Path.home().resolve(), PROJECT_ROOT.resolve()],
+        ),
+        max_concurrent_scans=max(1, _int("VCQA_MAX_CONCURRENT_SCANS", 2)),
+        finding_page_size=_int("VCQA_FINDING_PAGE_SIZE", 50),
+        max_page_size=_int("VCQA_MAX_PAGE_SIZE", 200),
+        ai_provider=os.environ.get("VCQA_AI_PROVIDER", ""),
+        ai_api_key=os.environ.get("VCQA_AI_API_KEY", ""),
+        ai_base_url=os.environ.get("VCQA_AI_BASE_URL", "https://openrouter.ai/api/v1"),
+        ai_model=os.environ.get("VCQA_AI_MODEL", "openai/gpt-3.5-turbo"),
+        ai_timeout=_int("VCQA_AI_TIMEOUT", 30),
+        ai_max_output_tokens=_int("VCQA_AI_MAX_OUTPUT_TOKENS", 3000),
+        ai_enable_source_context=_flag("VCQA_AI_ENABLE_SOURCE_CONTEXT", False),
+        ai_max_requests_per_minute=_int("VCQA_AI_MAX_REQUESTS_PER_MINUTE", 20),
+        ai_max_input_chars=_int("VCQA_AI_MAX_INPUT_CHARS", 40_000),
+        github_token=os.environ.get("VCQA_GITHUB_TOKEN", "") or os.environ.get("GITHUB_TOKEN", ""),
+        default_scan_profile=os.environ.get("VCQA_DEFAULT_SCAN_PROFILE", "standard"),
+        allow_test_execution=_flag("VCQA_ALLOW_TEST_EXECUTION", False),
+        default_test_image=os.environ.get("VCQA_TEST_CONTAINER_IMAGE", "python:3.12-slim"),
+        default_test_timeout=_int("VCQA_TEST_TIMEOUT", 300),
+        default_max_memory_mb=_int("VCQA_MAX_MEMORY_MB", 512),
+        default_max_cpu_seconds=_int("VCQA_MAX_CPU_SECONDS", 60),
+        default_max_snapshot_mb=_int("VCQA_MAX_SNAPSHOT_MB", 256),
+        default_max_write_mb=_int("VCQA_MAX_WRITE_MB", 64),
+        default_osv_enabled=_flag("VCQA_OSV_ENABLED", True),
+    )
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    return _build_settings()
+
+
+def reset_settings() -> Settings:
+    """Clear the cache (used by tests and on SIGHUP-style reloads)."""
+    get_settings.cache_clear()
+    return get_settings()
+
+
+def ai_configured(settings: Settings | None = None) -> bool:
+    settings = settings or get_settings()
+    provider = settings.ai_provider.strip().lower()
+    return bool(settings.ai_api_key) and provider not in ("", "none", "false", "0")

dashboard/backend/main.py

@@ -0,0 +1,183 @@
+"""FastAPI application factory for the Vibe Coding QA dashboard.
+
+Run it with ``python -m dashboard.backend`` (or
+``uvicorn dashboard.backend.main:create_app --factory``).
+
+Security posture:
+* bound to localhost by default;
+* CORS restricted to the configured local origins;
+* a repository must live inside an allow-listed root to be registered;
+* the AI provider key stays on the server and is never returned;
+* the release gate is computed by the engine, never by the API or the AI layer.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hmac
+import ipaddress
+import os
+from contextlib import asynccontextmanager
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from . import __version__
+from .ai.provider import AIError
+from .api import ai, dashboard, findings, intel, repositories, scans, system
+from .api.deps import build_services
+from .config import Settings, get_settings
+from .security import ValidationError, safe_error
+
+
+class BasicAuthMiddleware:
+    """Optional HTTP Basic Auth gate for a tunnelled/public deployment.
+
+    It is inert unless ``VCQA_BASIC_AUTH`` is set (``user:password``), so the
+    default localhost-only posture is unchanged. Implemented as pure ASGI
+    middleware rather than ``BaseHTTPMiddleware`` so streaming responses (the
+    SSE scan-progress feed) are never buffered.
+    """
+
+    def __init__(self, app, *, credential: str, realm: str = "Vibe Coding QA Dashboard"):
+        self.app = app
+        self.credential = credential.encode("utf-8")
+        self.realm = realm
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+        raw = dict(scope.get("headers") or []).get(b"authorization", b"")
+        if raw[:6].lower() == b"basic ":
+            token = raw[6:].strip()
+            try:
+                supplied = base64.b64decode(token + b"=" * (-len(token) % 4))
+            except (binascii.Error, ValueError):
+                supplied = b""
+            if hmac.compare_digest(supplied, self.credential):
+                await self.app(scope, receive, send)
+                return
+        body = b"Authentication required."
+        await send({
+            "type": "http.response.start",
+            "status": 401,
+            "headers": [
+                (b"content-type", b"text/plain; charset=utf-8"),
+                (b"www-authenticate", f'Basic realm="{self.realm}", charset="UTF-8"'.encode("ascii")),
+                (b"content-length", str(len(body)).encode("ascii")),
+            ],
+        })
+        await send({"type": "http.response.body", "body": body})
+
+
+class _SpaStaticFiles(StaticFiles):
+    """Serve the built dashboard and fall back to index.html for client routes."""
+
+    async def get_response(self, path: str, scope):
+        try:
+            return await super().get_response(path, scope)
+        except StarletteHTTPException as exc:
+            if exc.status_code == 404:
+                return await super().get_response("index.html", scope)
+            raise
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    resolved = settings or get_settings()
+    try:
+        host_is_loopback = resolved.host.lower() == "localhost" or ipaddress.ip_address(resolved.host).is_loopback
+    except ValueError:
+        host_is_loopback = False
+    if not host_is_loopback:
+        raise ValueError("The dashboard API must bind to a loopback host; remote access requires authentication.")
+    for origin in resolved.cors_origins:
+        parsed_origin = urlsplit(origin)
+        try:
+            origin_is_loopback = parsed_origin.hostname == "localhost" or ipaddress.ip_address(
+                parsed_origin.hostname or ""
+            ).is_loopback
+        except ValueError:
+            origin_is_loopback = False
+        if parsed_origin.scheme not in ("http", "https") or not origin_is_loopback:
+            raise ValueError("Dashboard CORS origins must be localhost origins.")
+    services = build_services(resolved)
+
+    @asynccontextmanager
+    async def lifespan(_: FastAPI):
+        # A scan that was running when the previous process died can never
+        # finish; mark it failed so the UI never shows a phantom "running" job.
+        services.scans.recover_interrupted()
+        try:
+            yield
+        finally:
+            services.scans.shutdown()
+            services.database.close()
+
+    app = FastAPI(
+        title="Vibe Coding QA Dashboard API",
+        version=__version__,
+        docs_url="/api/docs",
+        redoc_url=None,
+        openapi_url="/api/openapi.json",
+        lifespan=lifespan,
+    )
+    app.state.services = services
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=resolved.cors_origins,
+        allow_credentials=False,
+        allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+        allow_headers=["Content-Type", "Accept"],
+    )
+
+    # Added last on purpose: Starlette applies the most recently added middleware
+    # outermost, so the auth gate protects every route (and CORS preflight).
+    basic_auth = os.environ.get("VCQA_BASIC_AUTH", "").strip()
+    if basic_auth:
+        app.add_middleware(BasicAuthMiddleware, credential=basic_auth)
+
+    @app.exception_handler(ValidationError)
+    async def _validation_error(_: Request, exc: ValidationError) -> JSONResponse:
+        return JSONResponse(status_code=400, content={"detail": str(exc), "code": "validation_error"})
+
+    @app.exception_handler(AIError)
+    async def _ai_error(_: Request, exc: AIError) -> JSONResponse:
+        return JSONResponse(status_code=400, content={"detail": str(exc), "code": "ai_error"})
+
+    @app.exception_handler(KeyError)
+    async def _not_found(_: Request, exc: KeyError) -> JSONResponse:
+        return JSONResponse(
+            status_code=404,
+            content={"detail": safe_error(exc, "The requested item was not found."), "code": "not_found"},
+        )
+
+    for module in (system, dashboard, repositories, scans, findings, ai, intel):
+        app.include_router(module.router)
+
+    # Serve the built single-page dashboard when present, so one process (and one
+    # tunnelled port) exposes both the UI and the API. Mounted after the routers so
+    # /api still wins; unknown paths fall back to index.html for client routing.
+    dist = Path(__file__).resolve().parents[1] / "frontend" / "dist"
+    if dist.is_dir():
+        app.mount("/", _SpaStaticFiles(directory=dist, html=True), name="ui")
+
+    return app
+
+
+def main() -> None:
+    import uvicorn
+
+    settings = get_settings()
+    uvicorn.run(create_app(settings), host=settings.host, port=settings.port, log_level="info")
+
+
+if __name__ == "__main__":
+    main()

dashboard/backend/persistence/__init__.py

@@ -0,0 +1,5 @@
+"""Persistence package: SQLite database and data-access store."""
+
+from .database import Database, utcnow
+
+__all__ = ["Database", "utcnow"]

dashboard/backend/persistence/database.py

@@ -0,0 +1,278 @@
+"""SQLite persistence for the dashboard.
+
+A tiny, dependency-free data layer: no ORM, just ``sqlite3`` with explicit
+migrations. Scan history must survive restarts and interrupted scans must be
+identifiable, so everything the engine produces is persisted here.
+"""
+
+import sqlite3
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def utcnow() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+# Each entry is (version, [statements]). Migrations are append-only; never edit a
+# shipped migration, add a new one.
+MIGRATIONS: list[tuple[int, list[str]]] = [
+    (
+        1,
+        [
+            """
+            CREATE TABLE repositories (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                name TEXT NOT NULL,
+                source TEXT NOT NULL UNIQUE,
+                source_type TEXT NOT NULL DEFAULT 'local',
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL,
+                main_language TEXT,
+                frameworks TEXT,
+                package_manager TEXT,
+                database_tech TEXT,
+                auth_tech TEXT,
+                deployment TEXT,
+                default_branch TEXT,
+                last_commit_sha TEXT,
+                last_scan_id INTEGER
+            )
+            """,
+            """
+            CREATE TABLE scans (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                repository_id INTEGER NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,
+                status TEXT NOT NULL,
+                profile TEXT NOT NULL,
+                created_at TEXT NOT NULL,
+                started_at TEXT,
+                completed_at TEXT,
+                commit_sha TEXT,
+                overall_score REAL,
+                gate TEXT,
+                critical_count INTEGER DEFAULT 0,
+                high_count INTEGER DEFAULT 0,
+                total_findings INTEGER DEFAULT 0,
+                test_status TEXT,
+                tests_executed INTEGER,
+                tests_passed INTEGER,
+                tests_failed INTEGER,
+                tests_skipped INTEGER,
+                duration_ms INTEGER,
+                scanner_versions TEXT,
+                coverage_gaps TEXT,
+                ai_review_status TEXT,
+                error TEXT,
+                options TEXT,
+                trigger TEXT
+            )
+            """,
+            "CREATE INDEX idx_scans_repo ON scans(repository_id, id DESC)",
+            """
+            CREATE TABLE findings (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                scan_id INTEGER NOT NULL REFERENCES scans(id) ON DELETE CASCADE,
+                repository_id INTEGER NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,
+                fingerprint TEXT NOT NULL,
+                rule TEXT NOT NULL,
+                module TEXT NOT NULL,
+                severity TEXT NOT NULL,
+                file TEXT NOT NULL,
+                line INTEGER NOT NULL,
+                column INTEGER DEFAULT 0,
+                message TEXT,
+                suggestion TEXT,
+                confidence TEXT,
+                fixable INTEGER DEFAULT 0,
+                status TEXT NOT NULL DEFAULT 'open',
+                first_seen_scan_id INTEGER,
+                created_at TEXT NOT NULL
+            )
+            """,
+            "CREATE INDEX idx_findings_scan ON findings(scan_id)",
+            "CREATE INDEX idx_findings_repo ON findings(repository_id, status)",
+            "CREATE INDEX idx_findings_fingerprint ON findings(fingerprint)",
+            """
+            CREATE TABLE scan_events (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                scan_id INTEGER NOT NULL REFERENCES scans(id) ON DELETE CASCADE,
+                ts TEXT NOT NULL,
+                stage TEXT NOT NULL,
+                status TEXT,
+                message TEXT,
+                data TEXT
+            )
+            """,
+            "CREATE INDEX idx_events_scan ON scan_events(scan_id, id)",
+            """
+            CREATE TABLE ai_reviews (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                finding_id INTEGER REFERENCES findings(id) ON DELETE CASCADE,
+                scan_id INTEGER,
+                provider TEXT,
+                model TEXT,
+                kind TEXT,
+                created_at TEXT NOT NULL,
+                content TEXT,
+                error TEXT
+            )
+            """,
+            """
+            CREATE TABLE ai_conversations (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                repository_id INTEGER REFERENCES repositories(id) ON DELETE SET NULL,
+                title TEXT,
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL
+            )
+            """,
+            """
+            CREATE TABLE ai_messages (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                conversation_id INTEGER NOT NULL REFERENCES ai_conversations(id) ON DELETE CASCADE,
+                role TEXT NOT NULL,
+                content TEXT NOT NULL,
+                created_at TEXT NOT NULL,
+                metadata TEXT
+            )
+            """,
+            "CREATE INDEX idx_messages_conversation ON ai_messages(conversation_id, id)",
+            """
+            CREATE TABLE remediation_proposals (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                finding_id INTEGER REFERENCES findings(id) ON DELETE CASCADE,
+                repository_id INTEGER REFERENCES repositories(id) ON DELETE CASCADE,
+                status TEXT NOT NULL DEFAULT 'proposed',
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL,
+                provider TEXT,
+                model TEXT,
+                file TEXT,
+                original TEXT,
+                proposed TEXT,
+                diff TEXT,
+                rationale TEXT,
+                error TEXT
+            )
+            """,
+            """
+            CREATE TABLE remediation_history (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                proposal_id INTEGER NOT NULL REFERENCES remediation_proposals(id) ON DELETE CASCADE,
+                action TEXT NOT NULL,
+                ts TEXT NOT NULL,
+                actor TEXT,
+                detail TEXT
+            )
+            """,
+            """
+            CREATE TABLE app_settings (
+                key TEXT PRIMARY KEY,
+                value TEXT NOT NULL,
+                updated_at TEXT NOT NULL
+            )
+            """,
+        ],
+    ),
+]
+
+
+class Database:
+    """Thread-safe SQLite wrapper with WAL and per-thread connections."""
+
+    def __init__(self, path: Path | str):
+        self.path = Path(path)
+        if str(self.path) != ":memory:":
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._local = threading.local()
+        self._write_lock = threading.Lock()
+        self._conn_lock = threading.Lock()
+        # Every connection is tracked so shutdown can release the file handles
+        # (worker threads open their own connection and Windows keeps the file
+        # locked until all of them are closed).
+        self._open_connections: list[sqlite3.Connection] = []
+        self._memory_conn: sqlite3.Connection | None = None
+        if str(self.path) == ":memory:":
+            # A shared in-memory database must keep one connection alive, otherwise
+            # each connect() would see an empty schema.
+            self._memory_conn = self._connect_raw()
+        self.migrate()
+
+    def _connect_raw(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(str(self.path), check_same_thread=False)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA foreign_keys = ON")
+        conn.execute("PRAGMA journal_mode = WAL")
+        conn.execute("PRAGMA synchronous = NORMAL")
+        with self._conn_lock:
+            self._open_connections.append(conn)
+        return conn
+
+    def connection(self) -> sqlite3.Connection:
+        if self._memory_conn is not None:
+            return self._memory_conn
+        conn = getattr(self._local, "conn", None)
+        if conn is None:
+            conn = self._connect_raw()
+            self._local.conn = conn
+        return conn
+
+    def close(self) -> None:
+        """Close every connection opened by this database."""
+        with self._conn_lock:
+            connections = list(self._open_connections)
+            self._open_connections.clear()
+        for conn in connections:
+            try:
+                conn.close()
+            except sqlite3.Error:
+                pass
+        self._local = threading.local()
+        self._memory_conn = None
+
+    def applied_versions(self) -> set[int]:
+        conn = self.connection()
+        conn.execute(
+            "CREATE TABLE IF NOT EXISTS schema_migrations (version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL)"
+        )
+        rows = conn.execute("SELECT version FROM schema_migrations").fetchall()
+        return {row["version"] for row in rows}
+
+    def migrate(self) -> list[int]:
+        applied = self.applied_versions()
+        newly: list[int] = []
+        conn = self.connection()
+        with self._write_lock:
+            for version, statements in MIGRATIONS:
+                if version in applied:
+                    continue
+                for statement in statements:
+                    conn.execute(statement)
+                conn.execute(
+                    "INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)",
+                    (version, utcnow()),
+                )
+                conn.commit()
+                newly.append(version)
+        return newly
+
+    def execute(self, sql: str, params: tuple = ()) -> sqlite3.Cursor:
+        conn = self.connection()
+        with self._write_lock:
+            cursor = conn.execute(sql, params)
+            conn.commit()
+            return cursor
+
+    def executemany(self, sql: str, seq_params) -> None:
+        conn = self.connection()
+        with self._write_lock:
+            conn.executemany(sql, seq_params)
+            conn.commit()
+
+    def query(self, sql: str, params: tuple = ()) -> list[sqlite3.Row]:
+        return self.connection().execute(sql, params).fetchall()
+
+    def query_one(self, sql: str, params: tuple = ()) -> sqlite3.Row | None:
+        return self.connection().execute(sql, params).fetchone()