bugcap 0.2.2__tar.gz → 0.4.0__tar.gz

{bugcap-0.2.2/src/bugcap.egg-info → bugcap-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bugcap
-Version: 0.2.2
+Version: 0.4.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
@@ -63,13 +63,13 @@ 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 for reporting many bugs in a row. |
+| 🪟 **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. |
 
 ## Quick start
 
 ```bash
-# install (from GitHub until the PyPI release is live)
-pipx install 'bugcap[mcp] @ git+https://github.com/amenalahassa/bugcap'
+# install from PyPI
+pipx install 'bugcap[mcp]'
 
 bugcap setup --yes                      # detects or installs a capture tool
 cd ~/code/myproject && bugcap init      # scope reports to this repo
@@ -128,8 +128,8 @@ Requires Python 3.10 or newer. The core CLI uses only the standard library (plus
 Python 3.11). The MCP server is an optional extra.
 
 ```bash
-pipx install 'bugcap[mcp] @ git+https://github.com/amenalahassa/bugcap'   # recommended
-uv tool install 'bugcap[mcp] @ git+https://github.com/amenalahassa/bugcap'
+pipx install 'bugcap[mcp]'   # recommended
+uv tool install 'bugcap[mcp]'
 pip install -e '.[dev,mcp]'                                             # development
 ```
 
@@ -146,7 +146,7 @@ pull and sync, MCP, and where data lives per OS.
 
 Notes on the more involved behaviour:
 
-- **`@` references.** `@1` or `@login-error` in a note points at an image. They are validated on save, and relabelling or removing a referenced image needs `--force`.
+- **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`.
 - **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.
 

{bugcap-0.2.2 → bugcap-0.4.0}/README.md

@@ -47,13 +47,13 @@ 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 for reporting many bugs in a row. |
+| 🪟 **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. |
 
 ## Quick start
 
 ```bash
-# install (from GitHub until the PyPI release is live)
-pipx install 'bugcap[mcp] @ git+https://github.com/amenalahassa/bugcap'
+# install from PyPI
+pipx install 'bugcap[mcp]'
 
 bugcap setup --yes                      # detects or installs a capture tool
 cd ~/code/myproject && bugcap init      # scope reports to this repo
@@ -112,8 +112,8 @@ Requires Python 3.10 or newer. The core CLI uses only the standard library (plus
 Python 3.11). The MCP server is an optional extra.
 
 ```bash
-pipx install 'bugcap[mcp] @ git+https://github.com/amenalahassa/bugcap'   # recommended
-uv tool install 'bugcap[mcp] @ git+https://github.com/amenalahassa/bugcap'
+pipx install 'bugcap[mcp]'   # recommended
+uv tool install 'bugcap[mcp]'
 pip install -e '.[dev,mcp]'                                             # development
 ```
 
@@ -130,7 +130,7 @@ pull and sync, MCP, and where data lives per OS.
 
 Notes on the more involved behaviour:
 
-- **`@` references.** `@1` or `@login-error` in a note points at an image. They are validated on save, and relabelling or removing a referenced image needs `--force`.
+- **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`.
 - **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.
 

{bugcap-0.2.2 → bugcap-0.4.0}/pyproject.toml

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

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

{bugcap-0.2.2 → bugcap-0.4.0}/src/bugcap/agent_api.py

@@ -120,7 +120,8 @@ def update_notes(store: Store, id: int, notes: str) -> dict:
     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}
+    warnings = service.report_ref_warnings(store, report.notes)
+    return {"report_id": report.id, "notes": report.notes, "references": view.references, "warnings": warnings}
 
 
 def _resolve_slug(explicit: Optional[str]) -> Optional[str]:

{bugcap-0.2.2 → bugcap-0.4.0}/src/bugcap/cli.py

@@ -42,17 +42,26 @@ 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 "")
-        print(f"added #{media.idx} {name} ({media.kind}, {human_size(media.size_bytes)})")
+        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)
 
 
 # --- capture / list / show ----------------------------------------------------
 
+def _warn_report_refs(store: Store, notes) -> None:
+    """Soft warnings for `#N` references to reports that do not exist (never a failure)."""
+    for line in service.report_ref_warnings(store, notes or ""):
+        print(line, file=sys.stderr)
+
+
 def cmd_capture(args: argparse.Namespace) -> int:
     cfg = current_repo()
     captured: Optional[str] = None
-    if not args.image:
+    if args.no_image and (args.image or args.label):
+        print("error: --no-image cannot be combined with --image or --label", file=sys.stderr)
+        return 2
+    if not args.image and not args.no_image:
         try:
             captured = str(capture.capture_screenshot())
         except CaptureError as exc:
@@ -89,6 +98,8 @@ def cmd_capture(args: argparse.Namespace) -> int:
         except ServiceError as exc:
             print_service_error(exc)
             return 1
+        if report is not None:
+            _warn_report_refs(store, report.notes)
 
     if report is None:
         print_ingest([], result.rejected)
@@ -103,6 +114,27 @@ def cmd_capture(args: argparse.Namespace) -> int:
     return 1 if result.rejected else 0
 
 
+def cmd_delete(args: argparse.Namespace) -> int:
+    with Store() as store:
+        report = resolve_report(store, args.id)
+        if report is None:
+            return 1
+        if not args.yes:
+            if sys.stdin is None or not sys.stdin.isatty():
+                print("error: refusing to delete without confirmation; re-run with --yes", file=sys.stderr)
+                return 2
+            answer = input(
+                f"Delete report #{report.id} {report.title!r} and its {len(report.media)} image(s)? [y/N] "
+            ).strip().lower()
+            if answer != "y":
+                print("Nothing deleted.")
+                return 1
+        service.delete_report(store, args.id)
+
+    print(f"Deleted report #{report.id}: {report.title}")
+    return 0
+
+
 def cmd_list(args: argparse.Namespace) -> int:
     cfg = current_repo()
     scope = cfg.key if (cfg is not None and not args.all) else None
@@ -142,7 +174,7 @@ def cmd_show(args: argparse.Namespace) -> int:
         for m in detailed:
             where = m.path or f"({len(m.frames)} frames)"
             origin = f"  (source: {m.source})" if m.source else ""
-            print(f"    #{m.idx}  {m.kind:8s} {m.label or '-':12s} {where}  {human_size(m.size_bytes)}{origin}")
+            print(f"    {refs.media_token(m)}  {m.kind:8s} {m.label or '-':12s} {where}  {human_size(m.size_bytes)}{origin}")
     print(f"  synced_refs:")
     if report.synced_refs:
         for tracker, ref in report.synced_refs.items():
@@ -440,6 +472,8 @@ def cmd_edit(args: argparse.Namespace) -> int:
             print(f"error: {exc}", file=sys.stderr)
             return 2
 
+        _warn_report_refs(store, report.notes)
+
     changed = []
     if args.title is not None:
         changed.append("title")
@@ -529,6 +563,7 @@ def cmd_attach(args: argparse.Namespace) -> int:
                 print("warning: the image was attached but the note was not saved.", file=sys.stderr)
                 return 1
         current = store.get(args.id)
+        _warn_report_refs(store, current.notes)
         if args.image:
             try:
                 refs.validate_references(current.notes, current.media)
@@ -552,7 +587,7 @@ def cmd_images(args: argparse.Namespace) -> int:
         if args.action is None:
             for m in report.media:
                 where = m.path or f"({len(m.frames)} frames)"
-                print(f"#{m.idx}  {m.label or '-':12s} {m.kind:8s} {human_size(m.size_bytes):>9s}  {where}")
+                print(f"{refs.media_token(m)}  {m.label or '-':12s} {m.kind:8s} {human_size(m.size_bytes):>9s}  {where}")
             return 0
         try:
             if args.action == "relabel":
@@ -634,8 +669,9 @@ def cmd_record(args: argparse.Namespace) -> int:
             recorder.discard(result)
             print_service_error(exc)
             return 1
+        _warn_report_refs(store, report.notes)
     print(f"recorded {result.duration:.1f} s, {human_size(result.size_bytes)} ({result.kind}), stopped: {result.reason}")
-    print(f"added #{media.idx} to report #{report.id}")
+    print(f"added {refs.media_token(media)} to report #{report.id}")
     return 0
 
 
@@ -828,8 +864,15 @@ def build_parser() -> argparse.ArgumentParser:
     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("--no-image", dest="no_image", action="store_true",
+                   help="Save a text-only report: no capture tool and no image.")
     p.set_defaults(func=cmd_capture)
 
+    p = sub.add_parser("delete", help="Permanently delete a report and its images (not synced GitHub issues).")
+    p.add_argument("id", type=int, help="Report id (see `bugcap list`).")
+    p.add_argument("--yes", action="store_true", help="Delete without the confirmation prompt.")
+    p.set_defaults(func=cmd_delete)
+
     p = sub.add_parser("list", help="List reports (current repo only, unless --all).")
     p.add_argument("--all", action="store_true", help="List reports from every repo.")
     p.set_defaults(func=cmd_list)

{bugcap-0.2.2 → bugcap-0.4.0}/src/bugcap/dashboard/api.py

@@ -101,5 +101,7 @@ 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)
+    report = service.set_notes(store, report_id, notes)
+    view = get_report(store, report_id)
+    view["warnings"] = service.report_ref_warnings(store, report.notes)
+    return view

{bugcap-0.2.2 → bugcap-0.4.0}/src/bugcap/dashboard/static/app.js

@@ -94,7 +94,8 @@
       var i = document.createElement("img");
       i.src = m.url; i.alt = m.label || ("image " + m.index); fig.appendChild(i);
     }
-    var label = caption || ("#" + m.index);
+    var letters = {image: "i", video: "v", animated: "g", frames: "f"};
+    var label = caption || ("@" + (letters[m.kind] || "i") + m.index);
     if (m.label) label += " (" + m.label + ")";
     fig.appendChild(el("figcaption", label + " · " + m.kind + " · " + Math.round(m.size_bytes / 1024) + " KB"));
     return fig;

bugcap-0.4.0/src/bugcap/drafts.py

@@ -0,0 +1,134 @@
+"""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."""
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from .paths import drafts_dir
+
+FIELDS = ("title", "notes", "tags", "status")
+
+
+@dataclass
+class Draft:
+    id: str
+    created_at: str
+    repo: Optional[str]
+    title: str = ""
+    notes: str = ""
+    tags: list = None  # type: ignore[assignment]
+    status: str = "open"
+    # [{"kind", "path" (absolute or None), "mime", "size_bytes", "frames": [(path, size)]}]
+    items: list = field(default_factory=list)
+
+    def fields(self) -> dict:
+        return {"title": self.title, "notes": self.notes, "tags": list(self.tags or []), "status": self.status}
+
+    @property
+    def png_path(self) -> Optional[Path]:
+        """The first stored file (the screenshot of a single-image draft), if any."""
+        for item in self.items:
+            if item["path"]:
+                return Path(item["path"])
+        return None
+
+
+def _move(source, target: Path) -> Path:
+    shutil.move(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."""
+    if items is None:
+        items = [{"kind": "image", "path": str(png_path), "mime": "image/png", "size_bytes": 0, "frames": []}] if png_path else []
+    draft_id = str(uuid.uuid4())
+    directory = drafts_dir()
+    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
+        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,
+        })
+    meta = {
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "repo": repo,
+        "title": fields.get("title", ""),
+        "notes": fields.get("notes", ""),
+        "tags": list(fields.get("tags") or []),
+        "status": fields.get("status", "open"),
+        "media": listed,
+    }
+    (directory / f"{draft_id}.json").write_text(json.dumps(meta, indent=2))
+    return load_draft(draft_id)  # type: ignore[return-value]
+
+
+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"
+        if not png.is_file():
+            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
+        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):
+            raise ValueError("incomplete draft")
+        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,
+        })
+    return items
+
+
+def load_draft(draft_id: str) -> Optional[Draft]:
+    directory = drafts_dir()
+    sidecar = directory / f"{draft_id}.json"
+    try:
+        meta = json.loads(sidecar.read_text())
+        if not isinstance(meta, dict):
+            raise ValueError("incomplete draft")
+        return Draft(
+            draft_id, meta.get("created_at", ""), meta.get("repo"),
+            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),
+        )
+    except (OSError, ValueError, TypeError, KeyError) as exc:
+        print(f"warning: skipping unreadable draft {draft_id}: {exc}", file=sys.stderr)
+        return None
+
+
+def list_drafts(repo: Optional[str]) -> list[Draft]:
+    """Drafts saved for this repo (or without a repo), oldest first."""
+    found = []
+    for sidecar in sorted(drafts_dir().glob("*.json")):
+        draft = load_draft(sidecar.stem)
+        if draft is not None and draft.repo == repo:
+            found.append(draft)
+    return sorted(found, key=lambda d: d.created_at)
+
+
+def delete_draft(draft_id: str) -> None:
+    directory = drafts_dir()
+    (directory / f"{draft_id}.json").unlink(missing_ok=True)
+    (directory / f"{draft_id}.png").unlink(missing_ok=True)
+    for leftover in directory.glob(f"{draft_id}-*"):
+        leftover.unlink(missing_ok=True)