bugcap 0.2.2__py3-none-any.whl

bugcap/config.py

@@ -0,0 +1,86 @@
+"""Global (per-user) config: object store settings etc. Secrets never live here."""
+from typing import Any
+
+from . import tomlio
+from .paths import config_path
+
+KNOWN_KEYS = {
+    "storage.bucket": "Bucket name (S3 / R2 / any S3-compatible)",
+    "storage.endpoint_url": "Custom endpoint, e.g. https://<account>.r2.cloudflarestorage.com",
+    "storage.region": "Region (use 'auto' for R2)",
+    "storage.prefix": "Key prefix inside the bucket, e.g. bugcap/",
+    "storage.public_base_url": "Public URL base (R2 public bucket / CDN). If unset, presigned URLs are used",
+}
+
+
+def load() -> dict[str, Any]:
+    return tomlio.load(config_path())
+
+
+def get(key: str) -> Any:
+    section, _, name = key.partition(".")
+    return load().get(section, {}).get(name)
+
+
+def set_value(key: str, value: str) -> None:
+    section, _, name = key.partition(".")
+    if not name:
+        raise ValueError("config keys look like 'storage.bucket'")
+    data = load()
+    data.setdefault(section, {})[name] = value
+    tomlio.save(config_path(), data)
+
+
+def unset(key: str) -> None:
+    section, _, name = key.partition(".")
+    data = load()
+    data.get(section, {}).pop(name, None)
+    tomlio.save(config_path(), data)
+
+
+# --- sync defaults and image-commit consent (roadmap item 8) -----------------
+
+def get_sync_defaults() -> dict[str, str]:
+    """Global `[sync]` defaults: images_repo, images_path, images_branch."""
+    section = load().get("sync", {})
+    return {
+        k: section[k]
+        for k in ("images_repo", "images_path", "images_branch")
+        if section.get(k)
+    }
+
+
+def _consent_set() -> list[str]:
+    raw = load().get("consent", {}).get("images_repos", "")
+    return [s.strip() for s in str(raw).split(",") if s.strip()]
+
+
+def consent_has(slug: str) -> bool:
+    """Whether the user has already approved committing images to this (private) repo."""
+    return slug in _consent_set()
+
+
+def consent_add(slug: str) -> None:
+    """Remember approval to commit images to a private repo (comma-separated, flat key)."""
+    repos = _consent_set()
+    if slug not in repos:
+        repos.append(slug)
+    data = load()
+    data.setdefault("consent", {})["images_repos"] = ",".join(repos)
+    tomlio.save(config_path(), data)
+
+
+DEFAULT_MAX_UPLOAD_MB = 25
+HARD_MAX_UPLOAD_MB = 100  # GitHub rejects larger files in a normal commit (see research.md)
+
+
+def get_max_upload_mb() -> float:
+    """`[sync] max_upload_mb`: per-file size above which media is not uploaded to GitHub."""
+    raw = load().get("sync", {}).get("max_upload_mb")
+    try:
+        value = float(raw)
+    except (TypeError, ValueError):
+        return float(DEFAULT_MAX_UPLOAD_MB)
+    if value <= 0:
+        return float(DEFAULT_MAX_UPLOAD_MB)
+    return min(value, float(HARD_MAX_UPLOAD_MB))

bugcap/dashboard/__init__.py

@@ -0,0 +1,3 @@
+from .server import make_server, serve
+
+__all__ = ["make_server", "serve"]

bugcap/dashboard/api.py

@@ -0,0 +1,105 @@
+"""JSON handlers for the dashboard. Each is a thin wrapper over `service`/`store`; the only
+logic here is shaping responses and mapping ServiceError codes to HTTP statuses."""
+from __future__ import annotations
+
+from .. import service
+from ..errors import ServiceError
+from ..store import Report
+
+STATUS_FOR_CODE = {
+    "bad_query": 400, "invalid_status": 400, "invalid_label": 400, "invalid_title": 400,
+    "bad_token": 403, "not_found": 404, "invalid_reference": 422,
+    "duplicate_label": 409, "referenced_image": 409,
+}
+
+
+def http_status(exc: ServiceError) -> int:
+    return STATUS_FOR_CODE.get(exc.code, 400)
+
+
+def _summary(report: Report) -> dict:
+    return {
+        "id": report.id, "title": report.title, "status": report.status, "tags": report.tags,
+        "repo": report.repo, "created_at": report.created_at, "media_count": len(report.media),
+    }
+
+
+def list_reports(store, query: dict) -> dict:
+    def one(name):
+        values = query.get(name)
+        return values[-1] if values else None
+
+    def number(name, default):
+        raw = one(name)
+        if raw is None:
+            return default
+        try:
+            return int(raw)
+        except ValueError:
+            raise ServiceError("bad_query", f"{name} must be a number")
+
+    total, items = service.list_reports_query(
+        store, repo=one("repo"), tags=query.get("tag") or [], status=one("status"), q=one("q"),
+        limit=number("limit", 200), offset=number("offset", 0),
+    )
+    return {"total": total, "items": items}
+
+
+def _links(synced_refs: dict) -> list:
+    """Clickable targets derived from sync refs (currently the GitHub issue)."""
+    links = []
+    issue = (synced_refs or {}).get("github.issue", "")
+    slug, sep, number = issue.rpartition("#")
+    if sep and number.isdigit() and slug.count("/") == 1:
+        links.append({"label": f"GitHub issue {issue}", "url": f"https://github.com/{slug}/issues/{number}"})
+    return links
+
+
+def get_report(store, report_id: int) -> dict:
+    view = service.get_report_view(store, report_id)
+    report = view.report
+    media = [
+        {
+            "id": m.id, "index": m.idx, "label": m.label, "kind": m.kind, "mime": m.mime,
+            "size_bytes": m.size_bytes, "url": f"/media/{m.id}",
+        }
+        for m in view.media
+    ]
+    frames = {
+        str(m.id): [{"frame_no": f.frame_no, "url": f"/media/{m.id}/frames/{f.frame_no}"} for f in m.frames]
+        for m in view.media if m.kind == "frames"
+    }
+    data = _summary(report)
+    data.update({
+        "notes_raw": report.notes,
+        "notes_segments": view.segments,
+        "notes_html_segments": view.segments,
+        "media": media,
+        "frames": frames,
+        "synced_refs": report.synced_refs,
+        "links": _links(report.synced_refs),
+    })
+    return data
+
+
+def set_status(store, report_id: int, body: dict) -> dict:
+    status = body.get("status")
+    if not isinstance(status, str):
+        raise ServiceError("bad_query", "body must be {\"status\": \"...\"}")
+    return _summary(service.set_status(store, report_id, status))
+
+
+def set_tags(store, report_id: int, body: dict) -> dict:
+    add, remove = body.get("add", []), body.get("remove", [])
+    for value in (add, remove):
+        if not isinstance(value, list) or not all(isinstance(t, str) for t in value):
+            raise ServiceError("bad_query", "add and remove must be lists of strings")
+    return {"tags": service.set_tags(store, report_id, add=add, remove=remove)}
+
+
+def set_notes(store, report_id: int, body: dict) -> dict:
+    notes = body.get("notes")
+    if not isinstance(notes, str):
+        raise ServiceError("bad_query", "body must be {\"notes\": \"...\"}")
+    service.set_notes(store, report_id, notes)
+    return get_report(store, report_id)

bugcap/dashboard/media.py

@@ -0,0 +1,73 @@
+"""Serve stored media by row id, never by a client-supplied path."""
+from __future__ import annotations
+
+import logging
+import re
+
+from ..paths import resolve_data_path
+
+log = logging.getLogger("bugcap.dashboard")
+_RANGE = re.compile(r"^bytes=(\d*)-(\d*)$")
+CHUNK = 64 * 1024
+
+
+def parse_range(header: str | None, size: int):
+    """None = no (usable) range, 'invalid' = unsatisfiable, else (start, end) inclusive."""
+    if not header:
+        return None
+    match = _RANGE.match(header.strip())
+    if not match or (match.group(1) == "" and match.group(2) == ""):
+        return None
+    first, last = match.groups()
+    if first == "":  # suffix: last N bytes
+        n = int(last)
+        if n == 0 or size == 0:
+            return "invalid"
+        return max(0, size - n), size - 1
+    start = int(first)
+    end = int(last) if last else size - 1
+    if start >= size or (last and int(last) < start):
+        return "invalid"
+    return start, min(end, size - 1)
+
+
+def serve_media(handler, rel_path, mime: str, range_header: str | None) -> None:
+    """`rel_path` is the stored data-relative path; it must resolve inside images/ or media/."""
+    try:
+        path = resolve_data_path(rel_path)
+        if not path.is_file():
+            raise ValueError("missing file")
+    except (ValueError, OSError, TypeError):
+        log.warning("media path rejected: %r", rel_path)
+        handler.send_json(404, {"code": "not_found", "message": "media not found"})
+        return
+    size = path.stat().st_size
+    rng = parse_range(range_header, size)
+    if rng == "invalid":
+        handler.send_response(416)
+        handler.send_security_headers()
+        handler.send_header("Content-Range", f"bytes */{size}")
+        handler.send_header("Content-Length", "0")
+        handler.end_headers()
+        return
+    start, end = rng if rng else (0, size - 1)
+    handler.send_response(206 if rng else 200)
+    handler.send_security_headers()
+    handler.send_header("Content-Type", mime)
+    handler.send_header("Accept-Ranges", "bytes")
+    handler.send_header("Cache-Control", "private, max-age=3600")
+    handler.send_header("Content-Length", str(end - start + 1) if size else "0")
+    if rng:
+        handler.send_header("Content-Range", f"bytes {start}-{end}/{size}")
+    handler.end_headers()
+    if not size:
+        return
+    remaining = end - start + 1
+    with open(path, "rb") as fh:
+        fh.seek(start)
+        while remaining > 0:
+            chunk = fh.read(min(CHUNK, remaining))
+            if not chunk:
+                break
+            handler.wfile.write(chunk)
+            remaining -= len(chunk)

bugcap/dashboard/server.py

@@ -0,0 +1,213 @@
+"""Local dashboard server: standard-library HTTP, loopback only by default.
+
+Protections: Host and Origin checks (DNS rebinding / cross-site), a per-process token on every
+write (CSRF), media served by row id with containment checks, a static allowlist, and a CSP
+that forbids external origins."""
+from __future__ import annotations
+
+import hmac
+import json
+import re
+import secrets
+import sys
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from importlib import resources
+from urllib.parse import parse_qs, urlparse
+
+from ..errors import ServiceError
+from ..store import Store
+from . import api
+from .media import serve_media
+
+LOOPBACK = ("127.0.0.1", "localhost")
+STATIC_ALLOWLIST = {"app.js": "text/javascript", "app.css": "text/css"}
+CSP = (
+    "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self'; "
+    "media-src 'self' blob:; connect-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'"
+)
+MAX_BODY = 1024 * 1024
+MUTATING = ("POST", "PUT", "PATCH", "DELETE")
+_REPORT = re.compile(r"^/api/reports/(\d+)$")
+_REPORT_ACTION = re.compile(r"^/api/reports/(\d+)/(status|tags|notes)$")
+_MEDIA = re.compile(r"^/media/(\d+)$")
+_FRAME = re.compile(r"^/media/(\d+)/frames/(\d+)$")
+
+
+class DashboardServer(ThreadingHTTPServer):
+    daemon_threads = True
+
+    def __init__(self, address, token: str, exposed: bool = False):
+        super().__init__(address, Handler)
+        self.token = token
+        self.exposed = exposed
+
+    @property
+    def port(self) -> int:
+        return self.server_address[1]
+
+
+class Handler(BaseHTTPRequestHandler):
+    server: DashboardServer
+    server_version = "bugcap"
+
+    def log_message(self, fmt, *args):  # keep the terminal quiet; no tokens in logs
+        pass
+
+    # --- response helpers ------------------------------------------------------
+
+    def send_security_headers(self) -> None:
+        self.send_header("X-Content-Type-Options", "nosniff")
+        self.send_header("Content-Security-Policy", CSP)
+        self.send_header("Referrer-Policy", "no-referrer")
+
+    def send_json(self, status: int, payload) -> None:
+        body = json.dumps(payload).encode()
+        self.send_response(status)
+        self.send_security_headers()
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _error(self, exc: ServiceError) -> None:
+        self.send_json(api.http_status(exc), exc.as_dict())
+
+    # --- access rules ----------------------------------------------------------
+
+    def _allowed_origins(self) -> set:
+        port = self.server.port
+        return {f"http://127.0.0.1:{port}", f"http://localhost:{port}"}
+
+    def _check_access(self) -> bool:
+        host = self.headers.get("Host", "")
+        if not self.server.exposed and host not in {f"127.0.0.1:{self.server.port}", f"localhost:{self.server.port}"}:
+            self.send_json(400, {"code": "bad_host", "message": "unexpected Host header"})
+            return False
+        origin = self.headers.get("Origin")
+        if origin is not None:
+            allowed = self._allowed_origins() | ({f"http://{host}"} if self.server.exposed else set())
+            if origin not in allowed:
+                self.send_json(403, {"code": "bad_origin", "message": "cross-origin request refused"})
+                return False
+        if self.command in MUTATING:
+            sent = self.headers.get("X-Bugcap-Token", "")
+            if not hmac.compare_digest(sent.encode(), self.server.token.encode()):
+                self._error(ServiceError("bad_token", "missing or wrong X-Bugcap-Token"))
+                return False
+        return True
+
+    # --- routing ---------------------------------------------------------------
+
+    def _dispatch(self) -> None:
+        if not self._check_access():
+            return
+        parsed = urlparse(self.path)
+        path, query = parsed.path, parse_qs(parsed.query)
+        try:
+            self._route(path, query)
+        except ServiceError as exc:
+            self._error(exc)
+        except (BrokenPipeError, ConnectionResetError):
+            pass
+        except Exception:  # never leak internals
+            self.send_json(500, {"code": "internal", "message": "internal error"})
+
+    do_GET = do_POST = do_PUT = do_PATCH = do_DELETE = _dispatch
+
+    def _body(self) -> dict:
+        try:
+            length = int(self.headers.get("Content-Length", "0"))
+        except ValueError:
+            length = -1
+        if not 0 < length <= MAX_BODY:
+            raise ServiceError("bad_query", "a JSON body is required")
+        try:
+            data = json.loads(self.rfile.read(length))
+        except ValueError:
+            raise ServiceError("bad_query", "body is not valid JSON")
+        if not isinstance(data, dict):
+            raise ServiceError("bad_query", "body must be a JSON object")
+        return data
+
+    def _route(self, path: str, query: dict) -> None:
+        method = self.command
+        if method == "GET":
+            if path == "/":
+                return self._static("index.html", "text/html; charset=utf-8")
+            if path.startswith("/static/") and path[len("/static/"):] in STATIC_ALLOWLIST:
+                name = path[len("/static/"):]
+                return self._static(name, STATIC_ALLOWLIST[name] + "; charset=utf-8")
+            if path == "/api/session":
+                return self.send_json(200, {"token": self.server.token})
+            if path == "/api/reports":
+                with Store() as store:
+                    return self.send_json(200, api.list_reports(store, query))
+            match = _REPORT.match(path)
+            if match:
+                with Store() as store:
+                    return self.send_json(200, api.get_report(store, int(match.group(1))))
+            match = _MEDIA.match(path)
+            if match:
+                return self._media(int(match.group(1)), None)
+            match = _FRAME.match(path)
+            if match:
+                return self._media(int(match.group(1)), int(match.group(2)))
+        else:
+            match = _REPORT_ACTION.match(path)
+            handlers = {("POST", "status"): api.set_status, ("POST", "tags"): api.set_tags,
+                        ("PUT", "notes"): api.set_notes}
+            if match and (method, match.group(2)) in handlers:
+                body = self._body()
+                with Store() as store:
+                    return self.send_json(200, handlers[(method, match.group(2))](store, int(match.group(1)), body))
+        self.send_json(404, {"code": "not_found", "message": "no such route"})
+
+    def _static(self, name: str, content_type: str) -> None:
+        data = (resources.files("bugcap.dashboard") / "static" / name).read_bytes()
+        self.send_response(200)
+        self.send_security_headers()
+        self.send_header("Content-Type", content_type)
+        self.send_header("Cache-Control", "no-cache")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    def _media(self, media_id: int, frame_no) -> None:
+        with Store() as store:
+            media = store.get_media(media_id)
+        if media is None:
+            return self.send_json(404, {"code": "not_found", "message": "media not found"})
+        if frame_no is None:
+            if media.kind == "frames" or not media.path:
+                return self.send_json(404, {"code": "not_found", "message": "media not found"})
+            return serve_media(self, media.path, media.mime, self.headers.get("Range"))
+        frame = next((f for f in media.frames if f.frame_no == frame_no), None)
+        if frame is None:
+            return self.send_json(404, {"code": "not_found", "message": "frame not found"})
+        serve_media(self, frame.path, media.mime, self.headers.get("Range"))
+
+
+def make_server(host: str = "127.0.0.1", port: int = 8765, token: str | None = None,
+                explicit_host: bool = False) -> DashboardServer:
+    """Bind the server (not yet serving). Non-loopback hosts need `explicit_host=True`."""
+    if host not in LOOPBACK and not explicit_host:
+        raise ValueError(f"refusing to bind {host}: the dashboard is local-only unless --host is given")
+    return DashboardServer((host, port), token or secrets.token_urlsafe(32), exposed=host not in LOOPBACK)
+
+
+def serve(host: str = "127.0.0.1", port: int = 8765, open_browser: bool = False,
+          explicit_host: bool = False) -> None:
+    server = make_server(host, port, explicit_host=explicit_host)
+    shown = "127.0.0.1" if host in LOOPBACK else host
+    url = f"http://{shown}:{server.port}/"
+    print(f"bugcap dashboard: {url}  (Ctrl+C to stop)", flush=True)
+    if open_browser:
+        webbrowser.open(url)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("", file=sys.stderr)
+    finally:
+        server.server_close()

bugcap/dashboard/static/app.css

@@ -0,0 +1,43 @@
+:root {
+  --bg: #fafafa; --fg: #1b1b1f; --muted: #62646c; --card: #ffffff; --line: #dcdce2;
+  --accent: #2457d6; --err: #b00020;
+  color-scheme: light;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --bg: #14151a; --fg: #ececf1; --muted: #9ea0aa; --card: #1d1f26; --line: #33353f;
+    --accent: #7ea2ff; --err: #ff6b81; color-scheme: dark;
+  }
+}
+:root[data-theme="dark"] {
+  --bg: #14151a; --fg: #ececf1; --muted: #9ea0aa; --card: #1d1f26; --line: #33353f;
+  --accent: #7ea2ff; --err: #ff6b81; color-scheme: dark;
+}
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--fg); font: 15px/1.5 system-ui, sans-serif; }
+.bar { display: flex; gap: 12px; align-items: baseline; padding: 12px 16px; border-bottom: 1px solid var(--line); }
+.bar h1 { font-size: 18px; margin: 0; }
+main { max-width: 960px; margin: 0 auto; padding: 16px; }
+.muted { color: var(--muted); }
+.error { color: var(--err); }
+.filters { display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: 8px; margin-bottom: 12px; }
+input, select, textarea, button {
+  font: inherit; color: var(--fg); background: var(--card); border: 1px solid var(--line);
+  border-radius: 6px; padding: 6px 8px; max-width: 100%;
+}
+button { cursor: pointer; }
+button:hover { border-color: var(--accent); }
+textarea { width: 100%; }
+.reports { list-style: none; margin: 0; padding: 0; display: grid; gap: 8px; }
+.reports li { background: var(--card); border: 1px solid var(--line); border-radius: 8px; padding: 10px 12px; cursor: pointer; }
+.reports li:hover { border-color: var(--accent); }
+.reports .t { font-weight: 600; }
+.badge { font-size: 12px; border: 1px solid var(--line); border-radius: 999px; padding: 0 8px; margin-left: 6px; color: var(--muted); }
+.row { display: flex; flex-wrap: wrap; gap: 12px; align-items: center; }
+.tags .badge { margin: 0 4px 0 0; cursor: pointer; }
+.inline { display: inline-flex; gap: 4px; }
+.notes { white-space: pre-wrap; background: var(--card); border: 1px solid var(--line); border-radius: 8px; padding: 10px 12px; }
+.notes img, .media img, .media video { max-width: 100%; height: auto; display: block; margin: 8px 0; border-radius: 6px; }
+.media figure { margin: 0 0 16px; }
+.media figcaption { font-size: 13px; color: var(--muted); }
+.ref-missing { color: var(--muted); font-style: italic; }