bug2context 0.1.0__py3-none-any.whl

bug2context/__init__.py

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

bug2context/android.py

@@ -0,0 +1,179 @@
+"""Android capture: screen recording and logcat, started together.
+
+Recording both from one command is what makes the timelines line up — the
+alignment anchor is simply the moment we start, recorded on the host clock.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import time
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+DEVICE_VIDEO = "/sdcard/bug2context.mp4"
+SCREENRECORD_LIMIT = 180
+"""screenrecord stops itself at 3 minutes; asking for more silently truncates."""
+
+SETTLE_SECONDS = 3.0
+"""Grace for screenrecord to close the container before the file is pulled.
+
+Measured: pulling immediately yields a file ffprobe cannot read at all.
+"""
+
+
+class AdbError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class Capture:
+    """What a recording session produced."""
+
+    video: Path
+    logcat: Path
+    started_at: datetime
+    pid: int | None = None
+    """PID of the app under test, when a package was named."""
+    stopped_early: bool = False
+    """Whether the operator cut the recording short."""
+
+
+def _adb(*args: str, serial: str | None = None) -> list[str]:
+    return ["adb", *(["-s", serial] if serial else []), *args]
+
+
+def require_device(serial: str | None = None) -> str:
+    """Fail early with an actionable message rather than mid-recording."""
+    if shutil.which("adb") is None:
+        raise AdbError("adb not found. Install Android platform-tools.")
+
+    proc = subprocess.run(_adb("devices"), capture_output=True, text=True)
+    devices = [
+        line.split("\t")[0]
+        for line in proc.stdout.splitlines()[1:]
+        if line.strip().endswith("device")
+    ]
+    if not devices:
+        raise AdbError("No Android device connected. Check USB debugging is on.")
+    if serial and serial not in devices:
+        raise AdbError(f"Device {serial} not connected. Found: {', '.join(devices)}")
+    if not serial and len(devices) > 1:
+        raise AdbError(f"Several devices connected, pass --serial: {', '.join(devices)}")
+    return serial or devices[0]
+
+
+def resolve_pid(package: str, serial: str | None = None) -> int | None:
+    """PID of a running package, or None if it is not running.
+
+    Not running is not an error: the user may be about to launch it. The logs
+    simply stay unscoped in that case.
+    """
+    proc = subprocess.run(
+        _adb("shell", "pidof", "-s", package, serial=serial),
+        capture_output=True, text=True,
+    )
+    pid = proc.stdout.strip()
+    return int(pid) if pid.isdigit() else None
+
+
+def _stop_recording(serial: str | None) -> None:
+    """Ask screenrecord on the device to finish and close its file.
+
+    It has to be signalled on the device: terminating the local adb was
+    measured to leave an unreadable file, while SIGINT there finalises it.
+    pkill also matches processes it may not signal and says so on stderr —
+    that complaint is not about screenrecord, so it is ignored.
+    """
+    subprocess.run(
+        _adb("shell", "pkill", "-INT", "screenrecord", serial=serial),
+        capture_output=True,
+    )
+
+
+def _wait_or_kill(proc: subprocess.Popen, timeout: float = 20.0) -> None:
+    try:
+        proc.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait(timeout=5)
+
+
+def record(
+    out_dir: Path,
+    seconds: int = 60,
+    serial: str | None = None,
+    bit_rate: str = "4M",
+    size: str | None = None,
+    package: str | None = None,
+) -> Capture:
+    """Record screen and logcat together, then pull both off the device.
+
+    Blocks until the time runs out or Ctrl-C cuts it short; either way the file
+    is finalised on the device before it is pulled. The returned started_at is
+    what puts the log entries on the video clock later.
+    """
+    serial = require_device(serial)
+    if seconds > SCREENRECORD_LIMIT:
+        raise AdbError(
+            f"screenrecord caps at {SCREENRECORD_LIMIT}s; asked for {seconds}s."
+        )
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    video = out_dir / "screen.mp4"
+    logcat = out_dir / "logcat.txt"
+
+    # Capture unfiltered and scope afterwards: if the app crashes and restarts,
+    # a --pid capture would stop at the death of the old process.
+    pid = resolve_pid(package, serial) if package else None
+
+    subprocess.run(_adb("logcat", "-c", serial=serial), capture_output=True)
+
+    record_cmd = _adb(
+        "shell", "screenrecord", "--bit-rate", bit_rate,
+        "--time-limit", str(seconds),
+        *(["--size", size] if size else []),
+        DEVICE_VIDEO,
+        serial=serial,
+    )
+
+    # Both start now; this timestamp is the alignment anchor for the logs.
+    started_at = datetime.now()
+    stopped_early = False
+    with logcat.open("w") as log_file:
+        log_proc = subprocess.Popen(
+            _adb("logcat", "-v", "threadtime", serial=serial),
+            stdout=log_file, stderr=subprocess.DEVNULL,
+        )
+        # Its own session, so Ctrl-C reaches this process and not adb: killing
+        # adb mid-recording leaves an unfinalised file that ffprobe rejects.
+        rec_proc = subprocess.Popen(
+            record_cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+        try:
+            rec_proc.wait(timeout=seconds + 30)
+        except KeyboardInterrupt:
+            stopped_early = True
+            _stop_recording(serial)
+            _wait_or_kill(rec_proc)
+        except subprocess.TimeoutExpired:
+            _stop_recording(serial)
+            _wait_or_kill(rec_proc)
+        finally:
+            log_proc.terminate()
+            log_proc.wait(timeout=10)
+
+    # screenrecord finishes writing the container after it stops.
+    time.sleep(SETTLE_SECONDS)
+    pull = subprocess.run(
+        _adb("pull", DEVICE_VIDEO, str(video), serial=serial),
+        capture_output=True, text=True,
+    )
+    if pull.returncode != 0 or not video.is_file():
+        raise AdbError(f"Could not pull the recording off the device:\n{pull.stderr}")
+    subprocess.run(_adb("shell", "rm", DEVICE_VIDEO, serial=serial), capture_output=True)
+
+    return Capture(video, logcat, started_at, pid, stopped_early)

bug2context/cli.py

@@ -0,0 +1,90 @@
+from pathlib import Path
+
+import typer
+
+from .config import Config
+
+app = typer.Typer(help="Turn bug screen recordings into context for AI agents.")
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context) -> None:
+    """Run with no arguments for a guided menu; the subcommands take flags."""
+    if ctx.invoked_subcommand is None:
+        from .menu import run
+
+        run()
+
+
+@app.command()
+def process(
+    video: Path = typer.Argument(..., exists=True, dir_okay=False),
+    out: Path = typer.Option(Path("bundle"), "--out", "-o"),
+    scene_threshold: float = Config.scene_threshold,
+    max_duration: float = Config.max_duration,
+    interval_seconds: float = Config.interval_seconds,
+    max_frames: int | None = Config.max_frames,
+    phash_distance: int = Config.phash_distance,
+    ocr: bool = Config.ocr,
+    ocr_upscale: int = Config.ocr_upscale,
+    ocr_max_lines: int = Config.ocr_max_lines,
+    transcribe: bool = Config.transcribe,
+    whisper_model: str = Config.whisper_model,
+    language: str | None = Config.language,
+    logcat: Path | None = typer.Option(None, exists=True, dir_okay=False),
+    log_levels: str = Config.log_levels,
+    log_tag: str | None = Config.log_tag,
+    log_offset: float = Config.log_offset,
+    video_started_at: str | None = Config.video_started_at,
+    log_pid: int | None = Config.log_pid,
+    log_max_lines: int = Config.log_max_lines,
+) -> None:
+    """Process VIDEO into a context bundle."""
+    from .pipeline.assemble import build_bundle
+
+    cfg = Config(
+        scene_threshold, max_duration, interval_seconds, max_frames, phash_distance,
+        ocr, ocr_upscale, ocr_max_lines,
+        transcribe, whisper_model, language,
+        str(logcat) if logcat else None,
+        log_levels, log_tag, log_offset, video_started_at,
+        log_pid, log_max_lines,
+    )
+    typer.echo(build_bundle(video, out, cfg))
+
+
+@app.command()
+def record(
+    out: Path = typer.Option(Path("bundle"), "--out", "-o"),
+    seconds: int = typer.Option(60, "--seconds", "-t", help="Recording length."),
+    serial: str | None = typer.Option(None, help="Device serial, if several are attached."),
+    size: str | None = typer.Option(None, help="e.g. 720x1280 — smaller records faster."),
+    package: str | None = typer.Option(None, help="App package, to scope logs to it."),
+    log_levels: str = Config.log_levels,
+    log_tag: str | None = Config.log_tag,
+    ocr: bool = Config.ocr,
+    max_frames: int | None = Config.max_frames,
+) -> None:
+    """Record an Android device's screen and logcat, then build the bundle.
+
+    Reproduce the bug while it records; both streams share one start time, so
+    the stack trace lands next to the frame that shows the crash.
+    """
+    from .android import AdbError, record as capture
+    from .pipeline.assemble import build_bundle
+
+    try:
+        session = capture(out, seconds=seconds, serial=serial, size=size, package=package)
+    except AdbError as error:
+        raise typer.BadParameter(str(error)) from error
+
+    cfg = Config(
+        max_frames=max_frames,
+        ocr=ocr,
+        logcat_path=str(session.logcat),
+        log_levels=log_levels,
+        log_tag=log_tag,
+        video_started_at=session.started_at.isoformat(),
+        log_pid=session.pid,
+    )
+    typer.echo(build_bundle(session.video, out, cfg))

bug2context/config.py

@@ -0,0 +1,93 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Config:
+    """Pipeline options. Defaults come from PLAN section 3."""
+
+    scene_threshold: float = 0.08
+
+    max_duration: float = 600.0
+    """Refuse recordings longer than this, in seconds. 0 disables the guard.
+
+    Nothing here scales badly with length except time, and it scales linearly:
+    decoding alone ran at roughly a third of real time on a 60 fps capture, so
+    a 44 minute recording means a quarter of an hour before the first frame is
+    read. Trimming to the interesting minute is almost always what was meant.
+    """
+    interval_seconds: float = 1.0
+    max_frames: int | None = None
+    """Hard cap on published frames; None derives one from the video's length.
+
+    A fixed 20 was wrong in both directions. Deduplication already collapses
+    ordinary recordings well below it — measured 7 states in a 44 s capture and
+    12 in an 11 s one — so the cap never bound there. On an animated app it bit
+    hard: one 52 s recording held over 70 distinct states, and 20 threw away
+    two thirds of them. Across ten real analyses the cap was raised by hand
+    seven times.
+    """
+
+    phash_distance: int = 4
+    """Frames closer than this are treated as duplicates.
+
+    Calibration knob. Measured on encoded video: identical screens sit at 0, a
+    small text-only change lands around 6 before compression and can drop to 4.
+    Text is the payload of a bug report, so the default errs toward keeping —
+    the max_frames cap absorbs the extra. Raise it for videos of constantly
+    animating UI that produce noisy near-duplicates.
+    """
+
+    ocr: bool = True
+    """Read on-screen text. Silently skipped when no OCR backend is installed."""
+
+    ocr_upscale: int = 2
+    """Enlarge frames before OCR.
+
+    Calibration knob. Recompressed video (WhatsApp is the worst offender)
+    smears small text. Measured on a 1080x1920 frame, a stack trace read as
+    "Null PointerSxception Ride Requestkt14" at 1x and correctly at 3x. 2x is
+    the default because it recovers most of that at a fraction of the cost;
+    raise it for badly recompressed sources.
+    """
+
+    ocr_max_lines: int = 12
+    """Cap on text lines reported per frame, so chrome cannot bury the signal."""
+
+    transcribe: bool = False
+    """Transcribe spoken narration.
+
+    Off by default: it downloads a model on first use and is the slowest stage
+    by far, while most bug recordings have no voice-over at all.
+    """
+
+    whisper_model: str = "small"
+    """faster-whisper size. 'tiny'/'base' are faster, 'medium' more accurate."""
+
+    language: str | None = None
+    """Force a language code (e.g. "es") instead of letting whisper detect it."""
+
+    logcat_path: str | None = None
+    """Device log file to merge (`adb logcat -v threadtime > log.txt`)."""
+
+    log_levels: str = "WEF"
+    """Minimum logcat levels to keep. A crash drowns in a busy app's debug chatter."""
+
+    log_tag: str | None = None
+    """Only keep entries whose tag contains this substring."""
+
+    log_offset: float = 0.0
+    """Seconds to shift logs by. Manual escape when device and host clocks disagree."""
+
+    video_started_at: str | None = None
+    """ISO time the recording began, used to align logs. `record` fills this in."""
+
+    log_pid: int | None = None
+    """Only keep logs from this process. `record --package` resolves it for you.
+
+    Level filtering alone is not enough on a real device: a 2 min capture from
+    a phone held 7,634 W/E/F lines and none came from the app under test.
+    Crash tags (AndroidRuntime, DEBUG) are kept regardless of process.
+    """
+
+    log_max_lines: int = 80
+    """Cap on log entries in the report, most severe first. meta.json keeps all."""

bug2context/mcp_server.py

@@ -0,0 +1,119 @@
+"""MCP server: the primary interface, per PLAN principle 2.
+
+Exposes the pipeline as tools so an agent can go from "here is a video of the
+bug" to a chronology without the user running anything by hand.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+from mcp.server.mcpserver import Image, MCPServer
+
+from .config import Config
+
+DEFAULT_WORKDIR = Path("~/.bug2context").expanduser()
+
+mcp = MCPServer(
+    name="bug2context",
+    instructions=(
+        "Turns screen recordings of bugs into a chronological, readable report. "
+        "Call analyze_bug_video first; it returns the report text plus the bundle "
+        "path. Use get_frame to actually look at a moment the report describes."
+    ),
+)
+
+
+def _bundle_dir(video: Path, workdir: Path) -> Path:
+    """A directory that does not exist yet.
+
+    The timestamp only resolves to seconds, so two analyses in the same second
+    would land on the same path and the second would overwrite the first.
+    """
+    base = workdir / f"{video.stem}-{datetime.now():%Y%m%d-%H%M%S}"
+    candidate, n = base, 2
+    while candidate.exists():
+        candidate = base.with_name(f"{base.name}-{n}")
+        n += 1
+    return candidate
+
+
+@mcp.tool()
+def analyze_bug_video(
+    video_path: str,
+    max_frames: int | None = None,
+    ocr: bool = Config.ocr,
+    transcribe_audio: bool = Config.transcribe,
+    workdir: str = str(DEFAULT_WORKDIR),
+) -> str:
+    """Process a bug screen recording into a chronological markdown report.
+
+    Returns the report itself, so you can reason about it directly. Frames are
+    written next to it and referenced by relative path; use get_frame to view one.
+
+    Leave max_frames unset unless the report looks too coarse or too long: it
+    is derived from the recording's length.
+
+    Set transcribe_audio when the recording has someone narrating the bug; it
+    is slow and downloads a model on first use, so it stays off otherwise.
+    """
+    from .pipeline.assemble import build_bundle
+
+    video = Path(video_path).expanduser()
+    if not video.is_file():
+        return f"No video at {video}. Give me the full path to the recording."
+
+    out_dir = _bundle_dir(video, Path(workdir).expanduser())
+    cfg = Config(max_frames=max_frames, ocr=ocr, transcribe=transcribe_audio)
+    report_path = build_bundle(video, out_dir, cfg)
+
+    return f"Bundle: {out_dir}\n\n{report_path.read_text()}"
+
+
+@mcp.tool()
+def get_frame(bundle_path: str, frame_index: int) -> Image:
+    """Return one frame from a bundle so you can look at it.
+
+    frame_index is the 1-based number shown in the report (frame_003 -> 3).
+    """
+    frames_dir = Path(bundle_path).expanduser() / "frames"
+    matches = sorted(frames_dir.glob(f"frame_{frame_index:03d}_*.png"))
+    if not matches:
+        available = len(list(frames_dir.glob("frame_*.png")))
+        raise ValueError(
+            f"No frame {frame_index} in {bundle_path} (bundle has {available})."
+        )
+    return Image(path=matches[0])
+
+
+@mcp.tool()
+def list_bundles(workdir: str = str(DEFAULT_WORKDIR)) -> list[dict]:
+    """List previously processed bundles, newest first."""
+    root = Path(workdir).expanduser()
+    if not root.is_dir():
+        return []
+
+    bundles = []
+    for meta_path in root.glob("*/meta.json"):
+        try:
+            meta = json.loads(meta_path.read_text())
+        except (OSError, json.JSONDecodeError):
+            continue  # a half-written bundle should not break the listing
+        bundles.append({
+            "bundle_path": str(meta_path.parent),
+            "video": meta.get("video"),
+            "generated_at": meta.get("generated_at"),
+            "frames": len(meta.get("frames", [])),
+        })
+    return sorted(bundles, key=lambda b: b["generated_at"] or "", reverse=True)
+
+
+def main() -> None:
+    """Entry point for `bug2context-mcp` and `python -m bug2context.mcp_server`."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

bug2context/menu.py

@@ -0,0 +1,160 @@
+"""Guided flow for people who do not want to remember flags.
+
+Everything here is a thin shell over the same commands: the menu asks for what
+the flags would have carried, then calls the identical code path. Nothing is
+reachable only through the menu.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+
+from rich.console import Console
+from rich.prompt import Confirm, IntPrompt, Prompt
+from rich.table import Table
+
+from .config import Config
+
+DEFAULT_WORKDIR = Path("~/.bug2context").expanduser()
+console = Console()
+
+
+def _slugify(text: str) -> str:
+    kept = [c.lower() if c.isalnum() else "-" for c in text.strip()]
+    return "-".join(filter(None, "".join(kept).split("-"))) or "bug"
+
+
+def _bundle_path(label: str) -> Path:
+    """Bundles land where the MCP server looks, so Claude can find them."""
+    base = DEFAULT_WORKDIR / f"{_slugify(label)}-{date.today():%Y-%m-%d}"
+    candidate, n = base, 2
+    while candidate.exists():
+        candidate = base.with_name(f"{base.name}-{n}")
+        n += 1
+    return candidate
+
+
+def _report(bundle: Path) -> None:
+    console.print(f"\n[green]Listo[/green] → [bold]{bundle}[/bold]")
+    console.print("Pídeselo a Claude Code así:")
+    console.print(f'  [dim]analiza el bundle {bundle.name}[/dim]\n')
+
+
+def _record_android() -> None:
+    from .android import AdbError, record, resolve_pid
+
+    try:
+        from .android import require_device
+
+        serial = require_device()
+    except AdbError as error:
+        console.print(f"[red]{error}[/red]")
+        return
+
+    console.print(f"Dispositivo: [bold]{serial}[/bold]")
+    label = Prompt.ask("¿Qué bug vas a reproducir?", default="bug")
+    seconds = IntPrompt.ask(
+        "Segundos de grabación (máx. 180)", default=120, choices=None
+    )
+    if seconds > 180:
+        console.print("[yellow]screenrecord corta a 180 s; uso 180.[/yellow]")
+        seconds = 180
+
+    package = None
+    if Confirm.ask("¿Acotar los logs a una app?", default=False):
+        package = Prompt.ask("Paquete (ej. com.rumborides.driver)")
+        if resolve_pid(package, serial) is None:
+            console.print(
+                f"[yellow]{package} no está corriendo; los logs quedarán sin acotar.[/yellow]"
+            )
+
+    bundle = _bundle_path(label)
+    console.print(
+        f"\n[bold]Grabando {seconds} s.[/bold] Reproduce el bug ahora — "
+        "si la pantalla no cambia, no habrá nada que contar."
+    )
+    console.print("[dim]Ctrl-C corta antes de tiempo sin dañar el video.[/dim]\n")
+    try:
+        session = record(bundle, seconds=seconds, serial=serial, package=package)
+    except AdbError as error:
+        console.print(f"[red]{error}[/red]")
+        return
+
+    if session.stopped_early:
+        console.print("[dim]Grabación cortada por ti.[/dim]")
+
+    from .pipeline.assemble import build_bundle
+
+    with console.status("Procesando…"):
+        build_bundle(session.video, bundle, Config(
+            logcat_path=str(session.logcat),
+            log_pid=session.pid,
+            video_started_at=session.started_at.isoformat(),
+        ))
+    _report(bundle)
+
+
+def _process_video() -> None:
+    from .pipeline.assemble import build_bundle
+    from .pipeline.frames import FFmpegError
+
+    raw = Prompt.ask("Ruta del video")
+    video = Path(raw.strip().strip("'\"")).expanduser()
+    if not video.is_file():
+        console.print(f"[red]No hay ningún archivo en {video}[/red]")
+        return
+
+    cfg = Config()
+    if Confirm.ask("¿El video viene recomprimido (WhatsApp)?", default=False):
+        cfg = Config(ocr_upscale=3)
+
+    bundle = _bundle_path(Prompt.ask("Nombre para el bundle", default=video.stem))
+    with console.status("Procesando…"):
+        try:
+            build_bundle(video, bundle, cfg)
+        except FFmpegError as error:
+            console.print(f"[yellow]{error}[/yellow]")
+            return
+    _report(bundle)
+
+
+def _list_bundles() -> None:
+    from .mcp_server import list_bundles
+
+    bundles = list_bundles(str(DEFAULT_WORKDIR))
+    if not bundles:
+        console.print(f"[dim]Todavía no hay bundles en {DEFAULT_WORKDIR}[/dim]")
+        return
+
+    table = Table(box=None, header_style="bold")
+    table.add_column("Bundle")
+    table.add_column("Frames", justify="right")
+    table.add_column("Creado")
+    for entry in bundles:
+        table.add_row(
+            Path(entry["bundle_path"]).name,
+            str(entry["frames"]),
+            (entry["generated_at"] or "")[:16].replace("T", " "),
+        )
+    console.print(table)
+
+
+ACTIONS = {
+    "1": ("Grabar un Android (pantalla + logs)", _record_android),
+    "2": ("Procesar un video que ya tienes", _process_video),
+    "3": ("Ver bundles anteriores", _list_bundles),
+}
+
+
+def run() -> None:
+    """Show the menu once and run the chosen action."""
+    console.print("\n[bold]bug2context[/bold] — contexto de bugs para agentes\n")
+    for key, (label, _) in ACTIONS.items():
+        console.print(f"  [bold]{key}[/bold]  {label}")
+    console.print("  [bold]q[/bold]  Salir\n")
+
+    choice = Prompt.ask("Elige", choices=[*ACTIONS, "q"], default="1")
+    if choice == "q":
+        return
+    ACTIONS[choice][1]()