bugcap 0.6.0__tar.gz → 0.7.1__tar.gz

{bugcap-0.6.0/src/bugcap.egg-info → bugcap-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bugcap
-Version: 0.6.0
+Version: 0.7.1
 Summary: Local-first, agent-readable bug capture: annotated screenshots + notes, stored locally, synced to trackers on your own schedule.
 Author: Konrad Tagnon Amen ALAHASSA
 License: MIT
@@ -15,6 +15,7 @@ Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
 Dynamic: license-file
 
+<!-- mcp-name: io.github.amenalahassa/bugcap -->
 <p align="center">
   <img src="https://raw.githubusercontent.com/amenalahassa/bugcap/master/docs/assets/logo.svg" alt="bugcap" width="96">
 </p>
@@ -64,7 +65,7 @@ bugcap keeps the whole loop in one place:
 | 🔁 **Sync when ready** | Push to a GitHub issue with the usual inline image, plus a plain copy agents can read. |
 | 🎞️ **Record what happens** | Short screen recordings as animated GIF, video or keyframes, with size caps. |
 | 🖥️ **Triage in a browser** | A local dashboard on `127.0.0.1` to browse, filter and set statuses. |
-| 🪟 **Live mode** | An always-on-top window (top-right) to capture or record, stage several items, then file a new bug, add to an existing one, or log a note-only bug. |
+| 🪟 **Live mode** | An always-on-top window (top-right) to capture or record, stage several items (open or remove any of them), then file a new bug, add to an existing one, or log a note-only bug. |
 
 ## Quick start
 
@@ -179,7 +180,9 @@ Module map (`src/bugcap/`):
 | `ingest.py` | Path/glob/URL inputs: magic-byte validation, size/timeout/redirect limits, atomic copy into `images/`. |
 | `refs.py` | `@` reference parsing (code/email aware), validation, rewrite, display. |
 | `recorder.py` | `ffmpeg`/`wf-recorder` argv per OS, stop/caps watchdogs, animated/frames post-processing. |
-| `live.py` + `live_session.py` + `drafts.py` | Tk control window (thin) over a pure state machine; drafts on disk. |
+| `live.py` + `live_session.py` + `drafts.py` | Tk control window (thin) over a pure state machine; drafts (and the autosaved bug in progress) on disk. |
+| `screens.py` + `targets.py` | Monitors and windows per OS (Win32 via `ctypes`, `xrandr`/`wmctrl`, `wlr-randr`/`swaymsg`), what each platform can capture, and the remembered capture target. |
+| `shortcuts.py` + `opener.py` | Live mode's shortcut table (bindings, button hints, F1 help); opening a staged item in the OS default app. |
 | `dashboard/` | `http.server` UI + JSON API (loopback, Host/Origin checks, write token, Range media, static allowlist). |
 | `repo.py` + `tomlio.py` | `.bugcap.toml` discovery/read/write (tag, github slug, `[sync]`). |
 | `config.py` | Global `config.toml`: `[sync]` defaults, `[consent]` for image commits, `[log]`. |

{bugcap-0.6.0 → bugcap-0.7.1}/README.md

@@ -1,3 +1,4 @@
+<!-- mcp-name: io.github.amenalahassa/bugcap -->
 <p align="center">
   <img src="https://raw.githubusercontent.com/amenalahassa/bugcap/master/docs/assets/logo.svg" alt="bugcap" width="96">
 </p>
@@ -47,7 +48,7 @@ bugcap keeps the whole loop in one place:
 | 🔁 **Sync when ready** | Push to a GitHub issue with the usual inline image, plus a plain copy agents can read. |
 | 🎞️ **Record what happens** | Short screen recordings as animated GIF, video or keyframes, with size caps. |
 | 🖥️ **Triage in a browser** | A local dashboard on `127.0.0.1` to browse, filter and set statuses. |
-| 🪟 **Live mode** | An always-on-top window (top-right) to capture or record, stage several items, then file a new bug, add to an existing one, or log a note-only bug. |
+| 🪟 **Live mode** | An always-on-top window (top-right) to capture or record, stage several items (open or remove any of them), then file a new bug, add to an existing one, or log a note-only bug. |
 
 ## Quick start
 
@@ -162,7 +163,9 @@ Module map (`src/bugcap/`):
 | `ingest.py` | Path/glob/URL inputs: magic-byte validation, size/timeout/redirect limits, atomic copy into `images/`. |
 | `refs.py` | `@` reference parsing (code/email aware), validation, rewrite, display. |
 | `recorder.py` | `ffmpeg`/`wf-recorder` argv per OS, stop/caps watchdogs, animated/frames post-processing. |
-| `live.py` + `live_session.py` + `drafts.py` | Tk control window (thin) over a pure state machine; drafts on disk. |
+| `live.py` + `live_session.py` + `drafts.py` | Tk control window (thin) over a pure state machine; drafts (and the autosaved bug in progress) on disk. |
+| `screens.py` + `targets.py` | Monitors and windows per OS (Win32 via `ctypes`, `xrandr`/`wmctrl`, `wlr-randr`/`swaymsg`), what each platform can capture, and the remembered capture target. |
+| `shortcuts.py` + `opener.py` | Live mode's shortcut table (bindings, button hints, F1 help); opening a staged item in the OS default app. |
 | `dashboard/` | `http.server` UI + JSON API (loopback, Host/Origin checks, write token, Range media, static allowlist). |
 | `repo.py` + `tomlio.py` | `.bugcap.toml` discovery/read/write (tag, github slug, `[sync]`). |
 | `config.py` | Global `config.toml`: `[sync]` defaults, `[consent]` for image commits, `[log]`. |

{bugcap-0.6.0 → bugcap-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bugcap"
-version = "0.6.0"
+version = "0.7.1"
 description = "Local-first, agent-readable bug capture: annotated screenshots + notes, stored locally, synced to trackers on your own schedule."
 readme = "README.md"
 requires-python = ">=3.10"

bugcap-0.7.1/src/bugcap/__init__.py

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

{bugcap-0.6.0 → bugcap-0.7.1}/src/bugcap/backends.py

@@ -4,6 +4,7 @@ import shutil
 import subprocess
 import sys
 from dataclasses import dataclass, field
+from pathlib import Path
 from typing import Optional
 
 
@@ -15,10 +16,80 @@ def platform_key() -> str:
     return "linux"
 
 
+# Windows binaries known to install outside PATH with no fallback shim: their installer is a
+# plain MSI/WiX package with no winget "Commands" entry, so neither the installer nor winget
+# ever registers them on PATH (unlike scoop/choco, which always add their own shim dir, or
+# winget's own "portable" installer type, which winget manages the PATH entry for itself).
+# Checked against this project's other backends: satty/grim/wf-recorder are Linux-only and
+# screencapture is macOS-only, so this table only needs Windows-only entries.
+_WINDOWS_FALLBACK_DIRS: dict[str, list[tuple[str, ...]]] = {
+    "flameshot": [("Flameshot", "bin")],
+}
+
+
+def _windows_fallback_candidates(name: str) -> list[Path]:
+    # Path parts, not a single string: on CI, tests simulate "windows" by monkeypatching
+    # sys.platform while pathlib.Path stays bound to the real (often POSIX) OS, which would
+    # treat a literal "Flameshot\bin" as one oddly-named component instead of two.
+    rel_parts_list = _WINDOWS_FALLBACK_DIRS.get(name, [])
+    roots = [os.environ.get("ProgramFiles"), os.environ.get("ProgramFiles(x86)")]
+    return [Path(root, *rel_parts) for root in roots if root for rel_parts in rel_parts_list]
+
+
+def resolve(name: str) -> Optional[str]:
+    """Full path to the `name` executable: PATH first, then (on Windows) known install
+    locations for binaries whose installer never touches PATH. Use this instead of
+    `shutil.which` directly so a capture/record backend can actually be launched, not just
+    detected.
+    """
+    found = shutil.which(name)
+    if found:
+        return found
+    if platform_key() != "windows":
+        return None
+    for directory in _windows_fallback_candidates(name):
+        candidate = directory / f"{name}.exe"
+        if candidate.is_file():
+            return str(candidate)
+    return None
+
+
+def ensure_on_user_path(name: str) -> None:
+    """If `name` was only found via a fallback install location (not already on PATH),
+    persist that directory to the user's PATH registry so later shells and tools - not just
+    bugcap - can find it without needing the fallback. Best-effort: any failure is silent,
+    since `resolve()` already makes bugcap itself work without this.
+    """
+    if platform_key() != "windows" or shutil.which(name):
+        return
+    resolved = resolve(name)
+    if not resolved:
+        return
+    directory = str(Path(resolved).parent)
+    try:
+        import winreg
+
+        with winreg.OpenKey(
+            winreg.HKEY_CURRENT_USER, "Environment", 0, winreg.KEY_READ | winreg.KEY_SET_VALUE
+        ) as key:
+            try:
+                current, kind = winreg.QueryValueEx(key, "Path")
+            except FileNotFoundError:
+                current, kind = "", winreg.REG_EXPAND_SZ
+            parts = [p for p in current.split(os.pathsep) if p]
+            if any(p.lower() == directory.lower() for p in parts):
+                return
+            parts.append(directory)
+            winreg.SetValueEx(key, "Path", 0, kind, os.pathsep.join(parts))
+        os.environ["PATH"] = os.environ.get("PATH", "") + os.pathsep + directory
+    except OSError:
+        pass
+
+
 @dataclass
 class Backend:
     name: str
-    binaries: list[str]  # every one must be on PATH
+    binaries: list[str]  # every one must be resolvable (PATH, or a known fallback location)
     description: str
     platforms: tuple[str, ...]
     annotates: bool
@@ -29,7 +100,7 @@ class Backend:
     def available(self) -> bool:
         if platform_key() not in self.platforms:
             return False
-        return all(shutil.which(b) for b in self.binaries)
+        return all(resolve(b) for b in self.binaries)
 
 
 BACKENDS = [

bugcap-0.7.1/src/bugcap/capture.py

@@ -0,0 +1,122 @@
+import os
+import shutil
+import subprocess
+import sys
+import uuid
+from pathlib import Path
+
+from . import backends
+from .paths import images_dir
+from .recorder import TargetUnsupported, _target_parts, platform_key
+
+__all__ = ["CaptureError", "TargetUnsupported", "build_screenshot_argv", "capture_screenshot", "has_display",
+           "import_image"]
+
+
+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 _geometry(rect) -> str:
+    x, y, w, h = rect
+    return f"{w}x{h}+{x}+{y}"
+
+
+def build_screenshot_argv(backend: str, target, dest, platform=None, raw=None,
+                          resolve=lambda name: name) -> list[list[str]]:
+    """The command(s) that capture `target` (a `targets.CaptureTarget`, or None for the
+    backend's usual interactive capture) into `dest`, run in order. satty needs a grim grab
+    into `raw` first. Raises TargetUnsupported for a combination the backend cannot do."""
+    kind, rect = _target_parts(target, for_recording=False)
+    dest = str(dest)
+    if backend == "flameshot":
+        exe = resolve("flameshot")
+        if kind == "monitor":  # annotate on that screen only (bugcap report: multi-monitor Windows)
+            return [[exe, "screen", "-n", str(target.monitor.number), "-e", "--path", dest]]
+        if kind in ("region", "window"):
+            return [[exe, "gui", "--region", _geometry(rect), "--path", dest]]
+        return [[exe, "gui", "--path", dest]]
+    if backend == "satty":
+        grim = [resolve("grim")]
+        if kind == "monitor":
+            grim += ["-o", target.monitor.id]
+        elif kind == "region":
+            x, y, w, h = rect
+            grim += ["-g", f"{x},{y} {w}x{h}"]
+        elif kind == "window":
+            raise TargetUnsupported("grim cannot capture a single window")
+        return [grim + [str(raw)], [resolve("satty"), "--filename", str(raw), "--output-filename", dest]]
+    if backend == "screencapture":
+        exe = resolve("screencapture")
+        if kind == "monitor":
+            return [[exe, "-D", str(target.monitor.number + 1), dest]]
+        if kind == "region":
+            return [[exe, "-R", ",".join(str(v) for v in rect), dest]]
+        if kind == "window":
+            return [[exe, "-i", "-w", dest]]
+        # -i interactive region/window selection (space toggles window mode)
+        return [[exe, "-i", dest]]
+    raise CaptureError(f"Unknown backend: {backend}")
+
+
+def capture_screenshot(target=None) -> Path:
+    """Launch the detected backend's capture and return the saved PNG path. Without a
+    `target` it is the backend's interactive capture UI; with one (live mode) it covers just
+    that monitor, region or window. 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"
+    raw = images_dir() / f"{uuid.uuid4()}-raw.png" if backend.name == "satty" else None
+    commands = build_screenshot_argv(backend.name, target, dest, platform_key(), raw,
+                                     resolve=lambda name: backends.resolve(name) or name)
+    try:
+        for argv in commands:
+            result = subprocess.run(argv, capture_output=True, text=True)
+            if result.returncode != 0 and backend.name == "flameshot" and argv[1] == "screen":
+                # flameshot numbers screens its own way; the monitor's rectangle always works
+                fallback = [argv[0], "gui", "--region", _geometry(target.monitor.rect), "--path", str(dest)]
+                result = subprocess.run(fallback, capture_output=True, text=True)
+            if result.returncode != 0:
+                name = Path(argv[0]).stem
+                raise CaptureError(f"{name} exited with {result.returncode}: {result.stderr}")
+    finally:
+        if raw is not None:
+            raw.unlink(missing_ok=True)
+
+    if not dest.exists():
+        raise CaptureError(
+            "Capture backend exited without saving a file "
+            "(did you cancel the capture instead of saving it?)."
+        )
+    return dest

{bugcap-0.6.0 → bugcap-0.7.1}/src/bugcap/cli.py

@@ -229,6 +229,8 @@ def _setup_capture(args: argparse.Namespace) -> int:
         print(f"error: install command failed (exit {rc}).", file=sys.stderr)
         return 1
     if backends.detect() is not None:
+        for binary in rec.binaries:
+            backends.ensure_on_user_path(binary)
         print(f"{rec.name} installed.")
         return 0
     print(

{bugcap-0.6.0 → bugcap-0.7.1}/src/bugcap/drafts.py

@@ -1,10 +1,15 @@
 """Live-mode drafts: unsaved staged media (any number of images / recordings, or none) plus
 whatever was typed, kept on disk until it is saved as a report or discarded. One
 `<uuid>.json` sidecar per draft; its media files sit beside it as `<uuid>-*`. A draft made by
-an older version is just `<uuid>.png` + `<uuid>.json` and still loads."""
+an older version is just `<uuid>.png` + `<uuid>.json` and still loads.
+
+Live mode also autosaves the bug being written as a *progress* draft (`write_progress`): the
+same sidecar, rewritten atomically under a stable id, pointing at the media where it was
+staged (absolute `"path"`) instead of moving it here."""
 from __future__ import annotations
 
 import json
+import os
 import shutil
 import sys
 import uuid
@@ -29,6 +34,7 @@ class Draft:
     status: str = "open"
     # [{"kind", "path" (absolute or None), "mime", "size_bytes", "frames": [(path, size)]}]
     items: list = field(default_factory=list)
+    launch_repo: Optional[str] = None  # where live mode ran when a progress draft was written
 
     def fields(self) -> dict:
         return {"title": self.title, "notes": self.notes, "tags": list(self.tags or []), "status": self.status}
@@ -47,6 +53,11 @@ def _move(source, target: Path) -> Path:
     return target
 
 
+def _copy(source, target: Path) -> Path:
+    shutil.copyfile(str(source), target)
+    return target
+
+
 def save_draft(repo: Optional[str], png_path, fields: dict, items: Optional[list] = None) -> Draft:
     """Move the media into drafts/ and write the sidecar. `items` are dicts shaped like
     `Draft.items`; for a plain screenshot pass `png_path` instead."""
@@ -57,13 +68,16 @@ def save_draft(repo: Optional[str], png_path, fields: dict, items: Optional[list
     listed = []
     for n, item in enumerate(items, start=1):
         path = item.get("path")
-        new_path = _move(path, directory / f"{draft_id}-{n}{Path(path).suffix}") if path else None
+        # a shared upload is stored once under its content hash and may belong to reports: copy it
+        keep = _copy if item.get("shared") else _move
+        new_path = keep(path, directory / f"{draft_id}-{n}{Path(path).suffix}") if path else None
         frames = []
         for m, (frame_path, size) in enumerate(item.get("frames") or [], start=1):
             frames.append([_move(frame_path, directory / f"{draft_id}-{n}-f{m:03d}.png").name, size])
         listed.append({
             "kind": item["kind"], "file": new_path.name if new_path else None,
             "mime": item.get("mime", "image/png"), "size_bytes": item.get("size_bytes", 0), "frames": frames,
+            "number": item.get("number") or n, "source": item.get("source"), "shared": bool(item.get("shared")),
         })
     meta = {
         "created_at": datetime.now(timezone.utc).isoformat(),
@@ -78,6 +92,46 @@ def save_draft(repo: Optional[str], png_path, fields: dict, items: Optional[list
     return load_draft(draft_id)  # type: ignore[return-value]
 
 
+def write_progress(draft_id: Optional[str], repo: Optional[str], fields: dict, items: list,
+                   launch_repo: Optional[str] = None) -> str:
+    """Write (or rewrite) the progress draft `draft_id` (a new id when None) and return its id.
+    The media stays where it is; the sidecar records absolute paths. Written to a temporary
+    file and then renamed, so a crash leaves either the old sidecar or the new one."""
+    draft_id = draft_id or str(uuid.uuid4())
+    directory = drafts_dir()
+    sidecar = directory / f"{draft_id}.json"
+    now = datetime.now(timezone.utc).isoformat()
+    try:
+        created = json.loads(sidecar.read_text()).get("created_at") or now
+    except (OSError, ValueError, AttributeError):
+        created = now
+    meta = {
+        "version": 2,
+        "created_at": created,
+        "updated_at": now,
+        "repo": repo,
+        "launch_repo": launch_repo if launch_repo is not None else repo,
+        "title": fields.get("title", ""),
+        "notes": fields.get("notes", ""),
+        "tags": list(fields.get("tags") or []),
+        "status": fields.get("status") or "open",
+        "media": [{
+            "number": item.get("number"), "kind": item["kind"], "path": item.get("path"), "file": None,
+            "mime": item.get("mime", "image/png"), "size_bytes": item.get("size_bytes", 0),
+            "frames": [[str(p), size] for p, size in item.get("frames") or []],
+            "source": item.get("source"), "shared": bool(item.get("shared")),
+        } for item in items],
+    }
+    temp = directory / f"{draft_id}.json.tmp"
+    temp.write_text(json.dumps(meta, indent=2))
+    try:
+        os.replace(temp, sidecar)
+    except OSError:
+        temp.unlink(missing_ok=True)
+        raise
+    return draft_id
+
+
 def _items_from_meta(directory: Path, draft_id: str, meta: dict) -> list:
     if "media" not in meta:  # legacy: one screenshot
         png = directory / f"{draft_id}.png"
@@ -85,8 +139,9 @@ def _items_from_meta(directory: Path, draft_id: str, meta: dict) -> list:
             raise ValueError("incomplete draft")
         return [{"kind": "image", "path": str(png), "mime": "image/png", "size_bytes": png.stat().st_size, "frames": []}]
     items = []
-    for entry in meta["media"]:
-        path = directory / entry["file"] if entry.get("file") else None
+    for position, entry in enumerate(meta["media"], start=1):
+        # `path` (absolute, media left in place) for a progress draft, `file` (in drafts/) otherwise
+        path = Path(entry["path"]) if entry.get("path") else directory / entry["file"] if entry.get("file") else None
         frames = [(str(directory / name), int(size)) for name, size in entry.get("frames", [])]
         files = ([path] if path else []) + [Path(p) for p, _ in frames]
         if not files or not all(f.is_file() for f in files):
@@ -94,6 +149,8 @@ def _items_from_meta(directory: Path, draft_id: str, meta: dict) -> list:
         items.append({
             "kind": str(entry["kind"]), "path": str(path) if path else None, "mime": str(entry.get("mime", "")),
             "size_bytes": int(entry.get("size_bytes", 0)), "frames": frames,
+            "number": int(entry.get("number") or position), "source": entry.get("source"),
+            "shared": bool(entry.get("shared", False)),
         })
     return items
 
@@ -110,6 +167,7 @@ def load_draft(draft_id: str) -> Optional[Draft]:
             str(meta.get("title", "")), str(meta.get("notes", "")),
             [str(t) for t in meta.get("tags", [])], str(meta.get("status", "open")),
             _items_from_meta(directory, draft_id, meta),
+            meta.get("launch_repo", meta.get("repo")),
         )
     except (OSError, ValueError, TypeError, KeyError) as exc:
         print(f"warning: skipping unreadable draft {draft_id}: {exc}", file=sys.stderr)
@@ -117,11 +175,12 @@ def load_draft(draft_id: str) -> Optional[Draft]:
 
 
 def list_drafts(repo: Optional[str]) -> list[Draft]:
-    """Drafts saved for this repo (or without a repo), oldest first."""
+    """Drafts saved for this repo (or without a repo), oldest first. A bug in progress is
+    listed both for the repo picked in its form and for the repo live mode ran in."""
     found = []
     for sidecar in sorted(drafts_dir().glob("*.json")):
         draft = load_draft(sidecar.stem)
-        if draft is not None and draft.repo == repo:
+        if draft is not None and repo in (draft.repo, draft.launch_repo):
             found.append(draft)
     return sorted(found, key=lambda d: d.created_at)