bugcap 0.2.2__py3-none-any.whl

bugcap/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.2"

bugcap/agent_api.py

@@ -0,0 +1,221 @@
+"""SDK-free implementations of the agent tools. `mcp_server.py` merely registers
+these, so the logic is unit-testable without the MCP SDK installed."""
+from __future__ import annotations
+
+import sys
+import threading
+from pathlib import Path
+from typing import Callable, Optional
+
+from . import capture, refs, repo, service, sync
+from .errors import ServiceError
+from .store import Report, Store
+
+_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+}
+
+
+def _mime(path) -> str:
+    return _MIME.get(Path(path).suffix.lower(), "application/octet-stream")
+
+
+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,
+        "synced_refs": report.synced_refs,
+    }
+
+
+def _current_repo_key() -> Optional[str]:
+    cfg = repo.load_repo_config()
+    return cfg.key if cfg else None
+
+
+def list_reports(
+    store: Store,
+    all: bool = False,
+    status: Optional[str] = None,
+    limit: Optional[int] = None,
+) -> list[dict]:
+    scope = None if all else _current_repo_key()
+    reports = store.list(repo=scope)
+    if status is not None:
+        reports = [r for r in reports if r.status == status]
+    if limit is not None:
+        reports = reports[: max(0, int(limit))]
+    return [_summary(r) for r in reports]
+
+
+def _media_meta(media) -> list[dict]:
+    return [
+        {
+            "index": m.idx,
+            "label": m.label,
+            "kind": m.kind,
+            "mime": m.mime,
+            "size_bytes": m.size_bytes,
+            **({"frames": len(m.frames)} if m.kind == "frames" else {}),
+        }
+        for m in media
+    ]
+
+
+def get_report(store: Store, id: int) -> dict:
+    report = store.get(id)
+    if report is None:
+        return {"error": f"no report with id {id}"}
+    data = _summary(report)
+    data.update({
+        "body": report.body,
+        "notes": report.notes,
+        "image_paths": report.image_paths,
+        "media": _media_meta(report.media),
+    })
+    images = []
+    for path in report.image_paths:
+        p = Path(path)
+        if p.is_file():
+            images.append({"path": path, "mime": _mime(p), "bytes": p.read_bytes()})
+    resolved = [
+        {"token": r.token, "index": found.idx}
+        for r in refs.parse_references(report.notes)
+        if r.kind in ("index", "label") and (found := refs.resolve(r, report.media)) is not None
+    ]
+    return {"report": data, "images": images, "resolved_references": resolved}
+
+
+def attach_image(store: Store, id: int, sources: list[str], labels: Optional[list] = None) -> dict:
+    """Attach images (paths, globs, http(s) URLs) to a report; partial batches are reported."""
+    if not sources or len(sources) > 20:
+        return {"code": "bad_query", "error": "sources must contain 1 to 20 entries"}
+    try:
+        result = service.add_media(store, id, list(sources), labels)
+    except ServiceError as exc:
+        return {"error": exc.message, **exc.as_dict()}
+    return {
+        "report_id": id,
+        "added": [
+            {"index": m.idx, "label": m.label, "kind": m.kind, "size_bytes": m.size_bytes, "source": m.source}
+            for m in result.added
+        ],
+        "rejected": [{"source": r["source"], "reason": r["reason"]} for r in result.rejected],
+    }
+
+
+def update_notes(store: Store, id: int, notes: str) -> dict:
+    """Replace a report's notes, validating `@` references against its images."""
+    try:
+        report = service.set_notes(store, id, notes)
+    except ServiceError as exc:
+        return {"error": exc.message, **exc.as_dict()}
+    view = service.get_report_view(store, id)
+    return {"report_id": report.id, "notes": report.notes, "references": view.references}
+
+
+def _resolve_slug(explicit: Optional[str]) -> Optional[str]:
+    if explicit:
+        return explicit
+    cfg = repo.load_repo_config()
+    return cfg.github if cfg else None
+
+
+def _resolve_target(store: Store, report_id: Optional[int], issue: Optional[str]) -> Optional[Report]:
+    """Find (or create from an issue) the report a screenshot is being requested for."""
+    if report_id is not None:
+        return store.get(report_id)
+    if not issue:
+        return None
+    if "#" in issue:
+        slug, _, number = issue.partition("#")
+        slug = slug or (_resolve_slug(None) or "")
+    else:
+        slug = _resolve_slug(None) or ""
+        number = issue
+    ref = f"{slug}#{number}"
+    existing = store.find_by_ref("github.issue", ref)
+    if existing is not None:
+        return existing
+    return store.add(
+        title=f"Issue {ref}", repo=slug or None, synced_refs={"github.issue": ref}
+    )
+
+
+def _capture_with_timeout(timeout_seconds: int) -> Path:
+    result: dict = {}
+
+    def worker():
+        try:
+            result["path"] = capture.capture_screenshot()
+        except BaseException as exc:  # re-raised on the calling thread
+            result["error"] = exc
+
+    thread = threading.Thread(target=worker, daemon=True)
+    thread.start()
+    thread.join(timeout_seconds)
+    if thread.is_alive():
+        raise TimeoutError("screenshot request timed out")
+    if "error" in result:
+        raise result["error"]
+    return result["path"]
+
+
+def request_screenshot(
+    store: Store,
+    report_id: Optional[int] = None,
+    issue: Optional[str] = None,
+    message: Optional[str] = None,
+    timeout_seconds: int = 300,
+    note: Optional[str] = None,
+) -> dict:
+    if not capture.has_display():
+        return {"status": "non_interactive", "message": "no interactive desktop UI available"}
+    report = _resolve_target(store, report_id, issue)
+    if report is None:
+        return {"status": "error", "message": "no target report or issue given"}
+    if message:
+        print(message, file=sys.stderr, flush=True)
+    print(f"bugcap: capture a screenshot for report #{report.id}...", file=sys.stderr, flush=True)
+    try:
+        path = _capture_with_timeout(timeout_seconds)
+    except capture.CaptureError as exc:
+        return {"status": "cancelled", "message": str(exc)}
+    except TimeoutError as exc:
+        return {"status": "cancelled", "message": str(exc)}
+    media = service.attach_captured(store, report.id, str(path))
+    note_error = None
+    if note:
+        try:
+            service.append_note(store, report.id, note, [media])
+        except ServiceError as exc:
+            note_error = exc.message
+    p = Path(path)
+    return {
+        **({"note_error": note_error} if note_error else {}),
+        "status": "captured",
+        "report_id": report.id,
+        "image": {"path": str(path), "mime": _mime(p), "bytes": p.read_bytes()},
+    }
+
+
+def pull_issues(
+    store: Store,
+    repo: Optional[str] = None,
+    labels: Optional[list[str]] = None,
+    limit: int = 30,
+    ask_cb: Optional[Callable] = None,
+) -> dict:
+    slug = _resolve_slug(repo)
+    if not slug:
+        return {"error": "no GitHub repo given and none configured in .bugcap.toml"}
+    return sync.pull_issues(store, slug, labels, limit, ask_cb)

bugcap/backends.py

@@ -0,0 +1,133 @@
+"""Capture backends: detection, install suggestions and (opt-in) installation, per OS."""
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+def platform_key() -> str:
+    if sys.platform == "win32":
+        return "windows"
+    if sys.platform == "darwin":
+        return "macos"
+    return "linux"
+
+
+@dataclass
+class Backend:
+    name: str
+    binaries: list[str]  # every one must be on PATH
+    description: str
+    platforms: tuple[str, ...]
+    annotates: bool
+    # platform -> [(package manager binary, argv)]
+    installs: dict[str, list[tuple[str, list[str]]]] = field(default_factory=dict)
+    manual: dict[str, str] = field(default_factory=dict)  # platform -> guidance
+
+    def available(self) -> bool:
+        if platform_key() not in self.platforms:
+            return False
+        return all(shutil.which(b) for b in self.binaries)
+
+
+BACKENDS = [
+    Backend(
+        name="flameshot",
+        binaries=["flameshot"],
+        description="Cross-platform capture + annotation UI (recommended everywhere)",
+        platforms=("linux", "macos", "windows"),
+        annotates=True,
+        installs={
+            "linux": [
+                ("apt-get", ["apt-get", "install", "-y", "flameshot"]),
+                ("dnf", ["dnf", "install", "-y", "flameshot"]),
+                ("pacman", ["pacman", "-S", "--noconfirm", "flameshot"]),
+                ("zypper", ["zypper", "install", "-y", "flameshot"]),
+                ("brew", ["brew", "install", "flameshot"]),
+            ],
+            "macos": [("brew", ["brew", "install", "--cask", "flameshot"])],
+            "windows": [
+                ("winget", ["winget", "install", "--id", "Flameshot.Flameshot", "-e"]),
+                ("scoop", ["scoop", "install", "flameshot"]),
+                ("choco", ["choco", "install", "-y", "flameshot"]),
+            ],
+        },
+        manual={
+            "linux": "See https://flameshot.org/docs/installation/",
+            "macos": "brew install --cask flameshot, or https://flameshot.org/#download",
+            "windows": "winget install Flameshot.Flameshot, or https://flameshot.org/#download",
+        },
+    ),
+    Backend(
+        name="satty",
+        binaries=["satty", "grim"],
+        description="Wayland-native annotation (needs grim for the grab)",
+        platforms=("linux",),
+        annotates=True,
+        installs={
+            "linux": [
+                ("pacman", ["pacman", "-S", "--noconfirm", "satty", "grim"]),
+                ("brew", ["brew", "install", "satty"]),
+            ]
+        },
+        manual={
+            "linux": "Install grim from your distro, and satty from "
+            "https://github.com/Satty-org/Satty (or `cargo install satty`)",
+        },
+    ),
+    Backend(
+        name="screencapture",
+        binaries=["screencapture"],
+        description="macOS built-in region capture (no annotation)",
+        platforms=("macos",),
+        annotates=False,
+        manual={"macos": "Built in to macOS; nothing to install."},
+    ),
+]
+
+
+def by_name(name: str) -> Backend:
+    for backend in BACKENDS:
+        if backend.name == name:
+            return backend
+    raise KeyError(name)
+
+
+def detect() -> Optional[Backend]:
+    """First available backend, in preference order."""
+    return next((b for b in BACKENDS if b.available()), None)
+
+
+def recommended() -> Backend:
+    """What to suggest installing on this OS. Flameshot is cross-platform and annotates,
+    so it is the recommendation on every supported OS (satty is the Wayland alternative)."""
+    return by_name("flameshot")
+
+
+def install_command(backend: Backend) -> Optional[list[str]]:
+    """Full argv (with sudo when needed) for the first usable package manager, or None."""
+    for manager, argv in backend.installs.get(platform_key(), []):
+        if not shutil.which(manager):
+            continue
+        needs_root = manager in {"apt-get", "dnf", "pacman", "zypper"}
+        if needs_root and hasattr(os, "geteuid") and os.geteuid() != 0:
+            if not shutil.which("sudo"):
+                continue
+            return ["sudo", *argv]
+        return list(argv)
+    return None
+
+
+def guidance(backend: Backend) -> str:
+    return backend.manual.get(platform_key(), "See the project's website for install steps.")
+
+
+def install(backend: Backend) -> int:
+    cmd = install_command(backend)
+    if cmd is None:
+        raise RuntimeError(
+            f"No supported package manager found for {backend.name}. {guidance(backend)}"
+        )
+    return subprocess.run(cmd).returncode

bugcap/capture.py

@@ -0,0 +1,84 @@
+import os
+import shutil
+import subprocess
+import sys
+import uuid
+from pathlib import Path
+
+from . import backends
+from .paths import images_dir
+
+
+class CaptureError(RuntimeError):
+    pass
+
+
+def has_display() -> bool:
+    """Whether an interactive graphical session is available for a capture UI.
+
+    Linux: a running X11/Wayland session (``DISPLAY`` or ``WAYLAND_DISPLAY``).
+    macOS/Windows: assumed present (the window server runs for logged-in users).
+    """
+    if sys.platform == "win32" or sys.platform == "darwin":
+        return True
+    return bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
+
+
+def _no_backend_error() -> CaptureError:
+    rec = backends.recommended()
+    return CaptureError(
+        "No capture tool found. Run `bugcap setup` to detect/install one "
+        f"(recommended: {rec.name} - {backends.guidance(rec)}), "
+        "or pass an existing screenshot with --image."
+    )
+
+
+def import_image(source: Path) -> Path:
+    """Copy an existing image into the store (no capture tool needed)."""
+    if not source.is_file():
+        raise CaptureError(f"Image not found: {source}")
+    dest = images_dir() / f"{uuid.uuid4()}{source.suffix.lower() or '.png'}"
+    shutil.copyfile(source, dest)
+    return dest
+
+
+def capture_screenshot() -> Path:
+    """Launch the detected backend's interactive capture UI and return the saved PNG path.
+    Blocks until the user finishes (saves or cancels).
+    """
+    backend = backends.detect()
+    if backend is None:
+        raise _no_backend_error()
+    dest = images_dir() / f"{uuid.uuid4()}.png"
+
+    if backend.name == "flameshot":
+        result = subprocess.run(
+            ["flameshot", "gui", "--path", str(dest)], capture_output=True, text=True
+        )
+        if result.returncode != 0:
+            raise CaptureError(f"flameshot exited with {result.returncode}: {result.stderr}")
+    elif backend.name == "satty":
+        raw = images_dir() / f"{uuid.uuid4()}-raw.png"
+        subprocess.run(["grim", str(raw)], check=True)
+        result = subprocess.run(
+            ["satty", "--filename", str(raw), "--output-filename", str(dest)],
+            capture_output=True,
+            text=True,
+        )
+        raw.unlink(missing_ok=True)
+        if result.returncode != 0:
+            raise CaptureError(f"satty exited with {result.returncode}: {result.stderr}")
+    elif backend.name == "screencapture":
+        # -i interactive region/window selection (space toggles window mode)
+        result = subprocess.run(["screencapture", "-i", str(dest)], capture_output=True, text=True)
+        if result.returncode != 0:
+            raise CaptureError(f"screencapture exited with {result.returncode}: {result.stderr}")
+    else:  # pragma: no cover
+        raise CaptureError(f"Unknown backend: {backend.name}")
+
+    if not dest.exists():
+        raise CaptureError(
+            "Capture backend exited without saving a file "
+            "(did you cancel the capture instead of saving it?)."
+        )
+    return dest