bugcap 0.2.2__py3-none-any.whl

bugcap-0.2.2.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: bugcap
+Version: 0.2.2
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2; python_version < "3.11"
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.2; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/assets/logo.svg" alt="bugcap" width="96">
+</p>
+
+<h1 align="center">bugcap</h1>
+
+<p align="center">
+  <b>Bug reports your AI agent can actually read.</b><br>
+  Annotated screenshots and notes, stored on your machine, readable by coding agents over MCP, and synced to GitHub issues when you choose.
+</p>
+
+<p align="center">
+  <a href="https://github.com/amenalahassa/bugcap/actions/workflows/release.yml"><img alt="tests" src="https://github.com/amenalahassa/bugcap/actions/workflows/release.yml/badge.svg"></a>
+  <img alt="python" src="https://img.shields.io/badge/python-3.10%2B-3776ab?logo=python&logoColor=white">
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-green"></a>
+  <a href="https://amenalahassa.github.io/bugcap/"><img alt="docs" src="https://img.shields.io/badge/docs-website-d9480f"></a>
+</p>
+
+<p align="center">
+  <a href="https://amenalahassa.github.io/bugcap/">Website</a> ·
+  <a href="https://amenalahassa.github.io/bugcap/usage.html">Usage guide</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#connect-your-agent-mcp">Agents (MCP)</a> ·
+  <a href="CHANGELOG.md">Changelog</a>
+</p>
+
+<p align="center">
+  <img src="docs/assets/demo.gif" alt="bugcap capturing an annotated bug and listing the report" width="760">
+</p>
+
+---
+
+## Why bugcap
+
+Reviewing an app for bugs usually leaves you with two disconnected things: a screenshot and a
+mental note. By the time you file the issue, the context is gone. Once the screenshot is attached
+to a GitHub issue, it becomes **unreadable to an API token**. The CDN only resolves in a browser
+session, so an agent using `gh` can read the text but never the picture that explains the bug.
+
+bugcap keeps the whole loop in one place:
+
+| | |
+|---|---|
+| 📸 **Capture at the moment** | Annotated screenshots through `flameshot`, `satty` or `screencapture`. No new annotation UI. |
+| 🗂️ **Local record** | A SQLite index and PNGs on disk. Nothing depends on GitHub being reachable. |
+| 🤖 **Agent-readable** | A stdio MCP server hands reports, images included, to Claude Code and other agents. |
+| 🔁 **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. |
+
+## Quick start
+
+```bash
+# install (from GitHub until the PyPI release is live)
+pipx install 'bugcap[mcp] @ git+https://github.com/amenalahassa/bugcap'
+
+bugcap setup --yes                      # detects or installs a capture tool
+cd ~/code/myproject && bugcap init      # scope reports to this repo
+
+bugcap capture --title "Login fails" --note "Error toast after submit" --tag auth
+bugcap list
+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.
+
+## Connect your agent (MCP)
+
+Requires the `mcp` extra. Then give your agent access to the reports:
+
+```bash
+claude mcp add bugcap -- bugcap mcp-serve
+```
+
+Or in a project's `.mcp.json`:
+
+```json
+{ "mcpServers": { "bugcap": { "command": "bugcap", "args": ["mcp-serve"] } } }
+```
+
+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
+directory, never to stdout.
+
+Ask your agent something like *"list the open bugcap reports for this repo and fix the one with
+the error toast"*. It can read the picture because it's a local file, not a CDN link.
+
+## How it works
+
+```
+ capture ──► local store (SQLite + images/) ──► MCP / dashboard / CLI   (read by agents and you)
+                       │
+                       └──► sync ──► GitHub issue  +  committed image copy  (readable with gh api)
+```
+
+- **`capture` / `attach` / `record`** write to the store.
+- **`mcp-serve`, `dashboard`, `list`, `show`** read from it.
+- **`sync`** is the only thing that talks to a tracker, and only when you run it.
+
+## Status
+
+Working. Roadmap items 1–5, 7 and 8 are implemented and tested, along with spec 002 (images,
+`@` references, recording, live mode and the dashboard). S3/R2 object storage (item 6) and other
+trackers (item 9) are deferred. The `Destination` seam is in place, so they can be added without
+changing the CLI. See [ROADMAP.md](ROADMAP.md).
+
+## Installation
+
+Requires Python 3.10 or newer. The core CLI uses only the standard library (plus `tomli` before
+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'
+pip install -e '.[dev,mcp]'                                             # development
+```
+
+Supported capture backends: [`flameshot`](https://flameshot.org/) (cross-platform, recommended),
+[`satty`](https://github.com/Satty-org/Satty) with `grim` (Linux/Wayland), and `screencapture`
+(macOS). Run `bugcap setup` to see what's detected. You can always import an existing image with
+`bugcap capture --image PATH`.
+
+## Documentation
+
+Full guide: **[amenalahassa.github.io/bugcap/usage.html](https://amenalahassa.github.io/bugcap/usage.html)**
+covers capture, images, recording, live mode, triage, `@` references, the dashboard, GitHub
+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`.
+- **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.
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md). Run the tests with:
+
+```bash
+uv run --extra dev --extra mcp pytest -q
+```
+
+## Architecture
+
+Module map (`src/bugcap/`):
+
+| Module | Responsibility |
+|---|---|
+| `paths.py` | Per-OS data/config dirs; `BUGCAP_HOME` override. |
+| `capture.py` | Import or capture images (`flameshot`/`satty`+`grim`/`screencapture`); `has_display()`. |
+| `backends.py` | Capture-tool detection, per-OS install commands, manual guidance. |
+| `store.py` | SQLite store (`reports`, `media`, `media_frames`; schema v2), `PRAGMA user_version` migrations, report API, `transaction()`. |
+| `service.py` | **Shared rules** used by the CLI, MCP, dashboard and live mode: media add/relabel/remove, notes validation, reference rewrite, queries. Raises `ServiceError`. |
+| `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. |
+| `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]`. |
+| `validation.py` | Format checks for repo slugs, images path and branch names. |
+| `logs.py` | `mcp-serve` logging (rotating file + stderr, never stdout). |
+| `ghcli.py` | Thin `gh` wrapper (argv lists; large payloads via stdin). **Transport.** |
+| `sync.py` | `Destination` protocol, `GitHubDestination`, `pull_issues`, `sync_report`. **Policy.** |
+| `agent_api.py` | SDK-free tool logic for the six MCP tools. |
+| `mcp_server.py` | Lazy-imports the `mcp` SDK; registers the `agent_api` tools over stdio. |
+| `cli.py` | All subcommands. |
+
+The **store is the one shared surface**. Capture writes to it; the CLI, the MCP server, and the
+sync layer only read/update it — nothing talks to a tracker except `sync.py` (via `ghcli.py`), and
+nothing requires a tracker to exist for capture to be useful.
+
+**Extension seam (roadmap 6 & 9):** `sync.py` depends only on the small `Destination` protocol
+(`ensure_ready`, `repo_visibility`, `get_file`, `put_file`, `create_issue`, `comment`,
+`supports_attach`) and on the report's `synced_refs`. A future object store or tracker implements
+that protocol — the CLI and store don't change. Refs are namespaced per destination:
+
+- `github.issue` → `owner/repo#N`
+- `github.comment_hash` → sha256 of the last synced content (so re-sync comments only on change)
+- `github.image.<basename>` / `github.media.<basename>` → `owner/repo:path@commit` (so each file is committed at most once)
+- `github.frame.<idx>.<n>` and `github.frames.<idx>` → keyframes of a recording (one commit per frame; GitHub's contents API commits one file at a time)
+
+These refs also make pull and sync **idempotent and resumable**: each step is persisted as it
+succeeds, so a re-run skips what is already recorded.
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md).
+
+## Design notes / deliberate non-goals
+
+- **No cloud storage by default, no vendor account.** The store is plain files on your disk. Sync
+  (GitHub, and optionally an S3/R2 object store) is opt-in and explicit, per report.
+- **Not a GitHub attachment replacement.** The CDN-attached image stays for humans browsing the
+  issue normally; the repo-committed copy exists purely so agents can read it. Both are written
+  on sync, deliberately redundant.
+- **Not using Git LFS for synced copies.** GitHub's Contents API returns LFS pointer files, not
+  the real bytes, for LFS-tracked paths — which would silently defeat the entire point of
+  committing the copy. Plain commits are used instead; if screenshot volume ever outgrows that,
+  the right next step is an external object store with its own token-authable download URLs, not
+  LFS.
+- **Annotation UI is not reinvented.** `bugcap` is glue around an existing capture/annotate tool,
+  not a new one.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

bugcap-0.2.2.dist-info/RECORD

@@ -0,0 +1,36 @@
+bugcap/__init__.py,sha256=m6kyaNpwBcP1XYcqrelX2oS3PJuOnElOcRdBa9pEb8c,22
+bugcap/agent_api.py,sha256=AM3myQUfj3a5uOeBO0plgozMIpy6EHBh8WHZk-ICHo0,7175
+bugcap/backends.py,sha256=G3n_xlZZ97v8yZBOfWNVcds6F2g9w4ylRr60dDiH7mk,4584
+bugcap/capture.py,sha256=CcBtR3Dgt_C7XmcUk5HX002_vPyyIa-z2ojuDG6_9fQ,3016
+bugcap/cli.py,sha256=Yt_frgMarpHwX0lhqp02wJKHXYDRETdopUetN_xvHZ4,37092
+bugcap/config.py,sha256=PXxsAUPphkAt2Zux9R0Hv4q4M96bBrKGaMBOclv-6r0,2762
+bugcap/drafts.py,sha256=CVpm4wDR-MMJpyhE4wAY7rPl1f6OZJXuC6fIIpkgxog,2811
+bugcap/errors.py,sha256=Veaaw2msLz8sdzeXT0VArZFSv6O70mtq82Ryrbab7pI,761
+bugcap/ghcli.py,sha256=AuzqdsVO5TgMUbBcdv2gYb4eJ07UpeXH-JvW8IaHQGw,6262
+bugcap/ingest.py,sha256=I9ORKKr5FreR_4dx4t2OYQLrk7QVIqVPjFOiINfHh1U,8331
+bugcap/live.py,sha256=IAMviwEnc6bH8fSroOC16tkSqkRl-awy808QBMTcYiw,11686
+bugcap/live_session.py,sha256=03PMrIO3zxMyoAOV2dppBDZCR5buVvg0FIPh0mgLdkc,4574
+bugcap/logs.py,sha256=ICoMDKLEw6URbPg9SikCpsNoclJz6mLjIHa7M9_WD9I,3037
+bugcap/mcp_server.py,sha256=voYNHqYeakygp_eHII9OpNW-VmX6wrkJHo66zkqXQP8,8085
+bugcap/paths.py,sha256=BVDSL7y2ZplGUmY31OFhUKF3ibXO-YRJlrzl8VIz1Gs,3552
+bugcap/recorder.py,sha256=5FnOiSt7IOghiazL7dek23snLzsrP043BVGGPexbVfk,14634
+bugcap/refs.py,sha256=KnUcDVm9EeVu9WPheVjVlLHfnDgVwsOV98_TRF568Oc,7009
+bugcap/repo.py,sha256=F2ihrqp_qDezsYilwEiW4KJ3ISPcgXSMuYzopuUTCrg,3970
+bugcap/service.py,sha256=3XNsuERDqBV-iWQkQboQcFyx8eHtua95vCMJBLx--Hs,16160
+bugcap/store.py,sha256=ydUaenfcBQ5gXyM9XQD1q1zz9kj62rb4pvYyio426m4,17790
+bugcap/sync.py,sha256=v7dyg9Da_YT70_cegw5D7lh-u6sjki5QW6m1WrbZOic,16868
+bugcap/tomlio.py,sha256=iY7Dq8202nBVPpOUnjaMDD7C3TQIjFM1dJwBLGnnmxc,1091
+bugcap/validation.py,sha256=sjn6ewSJ2mgTBvq0XY07K1-LNw3Kh4CNi4W7gPgLuL4,2488
+bugcap/dashboard/__init__.py,sha256=V6bUJSzfnT4V8pmh7QTsB7jsY21vuUhL5r3tCOQqRG0,75
+bugcap/dashboard/api.py,sha256=OS_EY0kO1cLdbozggNd0_5Vo7EPh5OUWHjwklzd-SNc,3769
+bugcap/dashboard/media.py,sha256=3ySoYg6Wt5AeOcHJXnj5EWpWQdV1skot6nFAuMrvNdE,2622
+bugcap/dashboard/server.py,sha256=3R7rajqJqWBmcnOC95DR378vr7lub6baoX5OjfSoD8g,9039
+bugcap/dashboard/static/app.css,sha256=OYvlvGzNdt0kCXM36H3GDjOgJn0NscpHsB8pMVVrKGk,2364
+bugcap/dashboard/static/app.js,sha256=yAgcIZ2G3NZJI7gDpc4RS6c1JxjfRpRqYKFZF1b9Gew,7101
+bugcap/dashboard/static/index.html,sha256=eTdwm6raIKiy7lE5KY_iKNMchDWWWvy7kuuiFj5Xh9Y,1979
+bugcap-0.2.2.dist-info/licenses/LICENSE,sha256=sMo2LvcKFyhkvmZwlj6pdci2rReuYIk_pUG3C6CpK5Q,1084
+bugcap-0.2.2.dist-info/METADATA,sha256=iAMhY_3-0S0_V7SvdbidhXvNWKjX3Tqh7s0Wm8jzpsw,11067
+bugcap-0.2.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+bugcap-0.2.2.dist-info/entry_points.txt,sha256=QHwoyEJmsUHcdDOuibk5YohjYmH1wKmTVBO-Y8ySao8,43
+bugcap-0.2.2.dist-info/top_level.txt,sha256=HbiK-2Q-WQsqyJ65cDSzV-qTDvbyED8eIULU5NmzaLE,7
+bugcap-0.2.2.dist-info/RECORD,,

bugcap-0.2.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bugcap-0.2.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bugcap = bugcap.cli:main

bugcap-0.2.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konrad Tagnon Amen ALAHASSA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bugcap-0.2.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+bugcap