bugcap 0.5.1__tar.gz → 0.7.0__tar.gz

{bugcap-0.5.1/src/bugcap.egg-info → bugcap-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bugcap
-Version: 0.5.1
+Version: 0.7.0
 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
@@ -64,7 +64,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
 
@@ -83,6 +83,8 @@ bugcap dashboard --open                 # browse and triage in the browser
 The [usage guide](https://amenalahassa.github.io/bugcap/usage.html) covers every command: images
 and labels, recording, live mode, `@` references, GitHub pull and sync, and the MCP tools.
 
+If a report ID is not found, the error suggests `bugcap list --all` to see report IDs across all repos.
+
 ## Connect your agent (MCP)
 
 Requires the `mcp` extra. Then give your agent access to the reports:
@@ -98,7 +100,7 @@ Or in a project's `.mcp.json`:
 ```
 
 The server exposes six tools: `list_reports`, `get_report` (returns the screenshot), `request_screenshot`,
-`pull_issues`, `attach_image` and `update_notes`. Logs go to `logs/mcp-server.log` in the data
+`pull_issues`, `attach_image`, `attach_file` and `update_notes`. Logs go to `logs/mcp-server.log` in the data
 directory, never to stdout.
 
 Ask your agent something like *"list the open bugcap reports for this repo and fix the one with
@@ -147,7 +149,7 @@ pull and sync, MCP, and where data lives per OS.
 
 Notes on the more involved behaviour:
 
-- **References.** In a note, `@i1` is image 1, `@v2` a video, `@g3` an animated GIF, `@f4` a frame set, and `@login-error` a labelled item. `#3` points at report 3 (a missing one is kept as text with a warning). Media references are validated on save, and relabelling or removing a referenced item needs `--force`.
+- **References.** In a note, `@i1` is image 1, `@v2` a video, `@g3` an animated GIF, `@f4` a frame set, `@d5` an attached file (`attach --file`, any type), and `@login-error` a labelled item. `#3` points at report 3 (a missing one is kept as text with a warning). Media references are validated on save, and relabelling or removing a referenced item needs `--force`.
 - **Repo values** (`init`, `sync`, `config repo set`) are checked for format and, with `gh`, for existence. Changing the repo identity offers to move existing reports.
 - **Media sync** over `[sync] max_upload_mb` (default 25) is skipped with a warning.
 
@@ -177,7 +179,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.5.1 → bugcap-0.7.0}/README.md

@@ -47,7 +47,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
 
@@ -66,6 +66,8 @@ bugcap dashboard --open                 # browse and triage in the browser
 The [usage guide](https://amenalahassa.github.io/bugcap/usage.html) covers every command: images
 and labels, recording, live mode, `@` references, GitHub pull and sync, and the MCP tools.
 
+If a report ID is not found, the error suggests `bugcap list --all` to see report IDs across all repos.
+
 ## Connect your agent (MCP)
 
 Requires the `mcp` extra. Then give your agent access to the reports:
@@ -81,7 +83,7 @@ Or in a project's `.mcp.json`:
 ```
 
 The server exposes six tools: `list_reports`, `get_report` (returns the screenshot), `request_screenshot`,
-`pull_issues`, `attach_image` and `update_notes`. Logs go to `logs/mcp-server.log` in the data
+`pull_issues`, `attach_image`, `attach_file` and `update_notes`. Logs go to `logs/mcp-server.log` in the data
 directory, never to stdout.
 
 Ask your agent something like *"list the open bugcap reports for this repo and fix the one with
@@ -130,7 +132,7 @@ pull and sync, MCP, and where data lives per OS.
 
 Notes on the more involved behaviour:
 
-- **References.** In a note, `@i1` is image 1, `@v2` a video, `@g3` an animated GIF, `@f4` a frame set, and `@login-error` a labelled item. `#3` points at report 3 (a missing one is kept as text with a warning). Media references are validated on save, and relabelling or removing a referenced item needs `--force`.
+- **References.** In a note, `@i1` is image 1, `@v2` a video, `@g3` an animated GIF, `@f4` a frame set, `@d5` an attached file (`attach --file`, any type), and `@login-error` a labelled item. `#3` points at report 3 (a missing one is kept as text with a warning). Media references are validated on save, and relabelling or removing a referenced item needs `--force`.
 - **Repo values** (`init`, `sync`, `config repo set`) are checked for format and, with `gh`, for existence. Changing the repo identity offers to move existing reports.
 - **Media sync** over `[sync] max_upload_mb` (default 25) is skipped with a warning.
 
@@ -160,7 +162,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.5.1 → bugcap-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bugcap"
-version = "0.5.1"
+version = "0.7.0"
 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.0/src/bugcap/__init__.py

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

{bugcap-0.5.1 → bugcap-0.7.0}/src/bugcap/agent_api.py

@@ -97,10 +97,19 @@ def get_report(store: Store, id: int) -> dict:
 
 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."""
+    return _attach(store, id, sources, labels, service.add_media)
+
+
+def attach_file(store: Store, id: int, sources: list[str], labels: Optional[list] = None) -> dict:
+    """Attach files of any type (paths, globs, http(s) URLs) to a report."""
+    return _attach(store, id, sources, labels, service.add_files)
+
+
+def _attach(store: Store, id: int, sources: list[str], labels, add) -> dict:
     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)
+        result = add(store, id, list(sources), labels)
     except ServiceError as exc:
         return {"error": exc.message, **exc.as_dict()}
     return {

bugcap-0.7.0/src/bugcap/backends.py

@@ -0,0 +1,247 @@
+"""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 pathlib import Path
+from typing import Optional
+
+
+def platform_key() -> str:
+    if sys.platform == "win32":
+        return "windows"
+    if sys.platform == "darwin":
+        return "macos"
+    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 resolvable (PATH, or a known fallback location)
+    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(resolve(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 _sync_path_from_registry() -> None:
+    """Pick up a freshly-installed Windows tool without a new terminal.
+
+    winget/scoop/choco update the user/machine PATH in the registry, but an
+    already-running process (and any shell that was already open when the
+    install happened) keeps its original PATH until it restarts. That made
+    `bugcap live` report "No capture tool found" right after `bugcap setup`
+    had just installed flameshot in the same session. Re-reading PATH from
+    the registry before every detection closes that gap. Best-effort: any
+    failure here just leaves PATH as-is.
+    """
+    if sys.platform != "win32":
+        return
+    try:
+        import winreg
+    except ImportError:
+        return
+    try:
+        chunks = [os.environ.get("PATH", "")]
+        for hive, subkey in (
+            (winreg.HKEY_CURRENT_USER, r"Environment"),
+            (winreg.HKEY_LOCAL_MACHINE, r"SYSTEM\CurrentControlSet\Control\Session Manager\Environment"),
+        ):
+            try:
+                with winreg.OpenKey(hive, subkey) as key:
+                    value, _ = winreg.QueryValueEx(key, "Path")
+                    chunks.append(value)
+            except OSError:
+                continue
+        seen = set()
+        merged = []
+        for chunk in chunks:
+            for part in chunk.split(os.pathsep):
+                key = part.lower()
+                if part and key not in seen:
+                    seen.add(key)
+                    merged.append(part)
+        os.environ["PATH"] = os.pathsep.join(merged)
+    except OSError:
+        pass
+
+
+def detect() -> Optional[Backend]:
+    """First available backend, in preference order."""
+    _sync_path_from_registry()
+    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-0.7.0/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.5.1 → bugcap-0.7.0}/src/bugcap/cli.py

@@ -24,7 +24,10 @@ def resolve_report(store: Store, report_id: int):
     """Return the report, or print the standard not-found error and return None."""
     report = store.get(report_id)
     if report is None:
-        print(f"error: no report with id {report_id}", file=sys.stderr)
+        print(
+            f"error: no report with id {report_id}; run `bugcap list --all` to see report ids",
+            file=sys.stderr,
+        )
     return report
 
 
@@ -40,7 +43,7 @@ def print_service_error(exc: ServiceError) -> None:
 def print_ingest(added, rejected) -> None:
     """One line per input: `added #<idx> ...` on stdout, `skipped ...` on stderr."""
     for media in added:
-        name = os.path.basename(media.path or "")
+        name = os.path.basename((media.source if media.kind == "file" and media.source else media.path) or "")
         print(f"added {refs.media_token(media)} {name} ({media.kind}, {human_size(media.size_bytes)})")
     for item in rejected:
         print(f"skipped {item['source']}: {item['reason']}", file=sys.stderr)
@@ -225,7 +228,15 @@ def _setup_capture(args: argparse.Namespace) -> int:
     if rc != 0:
         print(f"error: install command failed (exit {rc}).", file=sys.stderr)
         return 1
-    print(f"{rec.name} installed.")
+    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(
+        f"{rec.name} installed, but this terminal can't see it on PATH yet.\n"
+        f"Close and reopen your terminal (or start a new one), then run `bugcap setup` again."
+    )
     return 0
 
 
@@ -536,14 +547,22 @@ def cmd_attach(args: argparse.Namespace) -> int:
         added: list = []
         rejected: list = []
         shot_path = None
-        if args.image:
-            try:
-                result = service.add_media(store, args.id, list(args.image), labels)
-            except ServiceError as exc:
-                print_service_error(exc)
-                return 1
-            added, rejected = result.added, result.rejected
-            print_ingest(added, rejected)
+        if args.image or args.file:
+            batches = (
+                (args.image, service.add_media, labels),
+                (args.file, service.add_files, list(args.file_label or [])),
+            )
+            for sources, add, batch_labels in batches:
+                if not sources:
+                    continue
+                try:
+                    result = add(store, args.id, list(sources), batch_labels)
+                except ServiceError as exc:
+                    print_service_error(exc)
+                    return 1
+                added += result.added
+                rejected += result.rejected
+                print_ingest(result.added, result.rejected)
         else:
             try:
                 shot_path = capture.capture_screenshot()
@@ -568,7 +587,7 @@ def cmd_attach(args: argparse.Namespace) -> int:
                 return 1
         current = store.get(args.id)
         _warn_report_refs(store, current.notes)
-        if args.image:
+        if args.image or args.file:
             try:
                 refs.validate_references(current.notes, current.media)
             except ServiceError as exc:
@@ -901,12 +920,16 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("tags", nargs="+")
     p.set_defaults(func=cmd_tag)
 
-    p = sub.add_parser("attach", help="Attach a screenshot (captured or imported) to a report.")
+    p = sub.add_parser("attach", help="Attach a screenshot (captured or imported) or any file to a report.")
     p.add_argument("id", type=int)
     p.add_argument("--image", action="append", metavar="SRC",
                    help="Import an image (path, glob or http(s) URL) instead of launching a capture tool; repeatable.")
     p.add_argument("--label", action="append", help="Label for the --image at the same position (repeatable).")
-    p.add_argument("--note", help="Text appended to the report's notes, tied to the image(s) added here.")
+    p.add_argument("--file", action="append", metavar="SRC",
+                   help="Attach a file of any type (path, glob or http(s) URL); repeatable. "
+                        "Refer to it in notes as @d1, @d2, ... or by label.")
+    p.add_argument("--file-label", action="append", help="Label for the --file at the same position (repeatable).")
+    p.add_argument("--note", help="Text appended to the report's notes, tied to the item(s) added here.")
     p.set_defaults(func=cmd_attach)
 
     p = sub.add_parser("images", help="List a report's images, or relabel/remove one.")
@@ -982,7 +1005,27 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
+def _use_utf8_streams() -> None:
+    """Make stdout/stderr tolerant of report text the console's codepage can't show.
+
+    Report titles and notes are free-form user text and may contain characters
+    (accents, emoji, …) outside the active console codepage. On Windows that
+    codepage is often cp1252, so a bare `print()` of such text raises
+    UnicodeEncodeError and crashes the CLI (e.g. `bugcap show`). Reconfiguring
+    to UTF-8 with 'replace' keeps the command running and shows readable output
+    instead of a traceback.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(encoding="utf-8", errors="replace")
+            except (ValueError, OSError):
+                pass
+
+
 def main(argv: list[str] | None = None) -> int:
+    _use_utf8_streams()
     parser = build_parser()
     args = parser.parse_args(argv)
     return args.func(args)

{bugcap-0.5.1 → bugcap-0.7.0}/src/bugcap/dashboard/media.py

@@ -31,8 +31,10 @@ def parse_range(header: str | None, size: int):
     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/."""
+def serve_media(handler, rel_path, mime: str, range_header: str | None, download_name: str | None = None) -> None:
+    """`rel_path` is the stored data-relative path; it must resolve inside the media store.
+    With `download_name` (attached files of any type) the bytes are always sent as an opaque
+    download, never rendered, so an uploaded HTML or SVG file cannot run on the dashboard origin."""
     try:
         path = resolve_data_path(rel_path)
         if not path.is_file():
@@ -53,7 +55,12 @@ def serve_media(handler, rel_path, mime: str, range_header: str | None) -> None:
     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)
+    if download_name is not None:
+        safe = re.sub(r"[^A-Za-z0-9._-]", "_", download_name)[:100] or "file"
+        handler.send_header("Content-Type", "application/octet-stream")
+        handler.send_header("Content-Disposition", f'attachment; filename="{safe}"')
+    else:
+        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")