Metadata-Version: 2.4
Name: debugbrief
Version: 1.4.0
Summary: Records debugging commands, outcomes, notes, and Git changes, then generates evidence-backed reports for pull requests, handoffs, and incidents.
Author: Hari Krishna Kancharla
License-Expression: MIT
Project-URL: Homepage, https://github.com/hari-kancharla/Debug-Brief
Project-URL: Repository, https://github.com/hari-kancharla/Debug-Brief
Project-URL: Documentation, https://github.com/hari-kancharla/Debug-Brief/tree/main/docs
Project-URL: Changelog, https://github.com/hari-kancharla/Debug-Brief/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/hari-kancharla/Debug-Brief/issues
Project-URL: Security, https://github.com/hari-kancharla/Debug-Brief/security/policy
Keywords: cli,debugging,developer-tools,git,testing,pull-request,handoff,incident,report,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tomli>=2.0.1; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.0; extra == "release"
Requires-Dist: twine>=5.0; extra == "release"
Dynamic: license-file

# DebugBrief

[![CI](https://github.com/hari-kancharla/Debug-Brief/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/hari-kancharla/Debug-Brief/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/debugbrief?cacheSeconds=3600)](https://pypi.org/project/debugbrief/)

Record what you do while debugging and turn it into an evidence-backed report for a pull request, a handoff, or an incident note.

![A failing test streams live, the fix lands, redo passes, and the generated report appears](https://raw.githubusercontent.com/hari-kancharla/Debug-Brief/main/docs/demo.gif)

DebugBrief captures the notes you write and the commands you run, then builds a report from what actually happened: what you tried, what failed, what passed, and which files changed in between. It does not use AI and does not infer a root cause or report a test result you did not get.

The product site includes the workflow, command reference and a local JSON Evidence Explorer: [open the site source](https://github.com/hari-kancharla/Debug-Brief/tree/main/site), or run `python3 scripts/serve_site.py` for a local preview. The site uses CDN fonts and optional animation libraries; imported reports stay in the browser and are never uploaded. It is included in the source distribution and is intentionally repository/deployment content rather than runtime wheel data.

## Install

```bash
pipx install debugbrief
# or
uv tool install debugbrief
```

These examples require DebugBrief 1.4.0 or newer. Upgrade an older install with `pipx upgrade debugbrief` or `uv tool upgrade debugbrief`. Plain `pip install --upgrade debugbrief` works too inside an environment. DebugBrief needs Python 3.9 or newer. Native Git is used when available to capture repository metadata and changed files. The project you debug does not need to be Python; only DebugBrief runs on Python.

## Quickstart

```bash
debugbrief run -- pytest -q test_calc.py             # auto-starts a local session
# make the fix
debugbrief redo                                      # same test, now passes
debugbrief end --format html --open                 # review the proof in your browser
```

A session title and notes are optional; add them when the output tells you something worth keeping. Everything after `--` runs exactly as you typed it, with its output streaming live to your terminal. DebugBrief flags (`--timeout`, `--shell`, `--no-redact`, `--verify`) go before the `--`. `redo` runs the last captured command again in its recorded directory using the current files and environment; use `redo --dry-run` to preview it without a lease or execution. Conservative destructive redos ask for confirmation, and `--yes` bypasses that prompt. `end` defaults to the `pr` report mode.

Tip: a one-line alias makes the capture prefix disappear in daily use.

```bash
alias db="debugbrief run --"
db pytest -q
```

## What you get

A report built only from recorded evidence. A short excerpt from a real run:

```markdown
## Summary

Failing check `python -m pytest -q test_calc.py` passed after 2 attempts over 2s, changes touched calc.py.

## Red to green

A check failed at 12:02:09 and `python -m pytest -q test_calc.py` passed at 12:02:10 (window 1s).

Between the failing and passing checks, these files changed (correlation, not proven cause):
- `calc.py`
```

Full samples: [PR](https://github.com/hari-kancharla/Debug-Brief/blob/main/examples/sample-pr.md), [handoff](https://github.com/hari-kancharla/Debug-Brief/blob/main/examples/sample-handoff.md), [incident](https://github.com/hari-kancharla/Debug-Brief/blob/main/examples/sample-incident.md).

## How it works

- `run` executes a command under a pseudo-terminal so its output streams live, then records the real exit code, a bounded output preview, the duration, and a per-command `git` snapshot when the project is a repository.
- Pass or fail comes only from the exit code. A command counts as verified when a recognized test, build, lint, or typecheck runner exits 0, or when you explicitly declare another command with `--verify` and its exit status is trustworthy. Help, version and collection/list modes do not count, even with `--verify`. A prior failure is not required, but a currently failed or invalid check keeps the report unverified.
- It works with any language. A recognized runner (pytest, jest, vitest, go test, cargo test, dotnet test, make check, and more) is classified automatically. Any other command is still captured, and you mark it a check with `--verify`.
- `end` derives the report from those events: an explicit evidence state, the red-to-green window, the reproduce and verify commands, a timeline, the observed error, and the failed attempts. PR reports are compact by default; pass `--detail full` for the complete record. Empty sections are omitted.
- `end --format html` writes a self-contained browser view; `end --format all` writes Markdown, JSON, and HTML together. Review it with `debugbrief open --html`, or use `debugbrief last --open` for a one-step handoff.
- Generated reports show only the local repository basename by default; pass `--include-full-path` to `end` or `preview` when the absolute project root is intentional. Absolute paths in recorded commands, notes and output can still appear. Reports retain project-relative working directories; missing legacy directory data remains unknown.
- Secrets are redacted before anything is written to disk. Redaction is best effort; `--no-redact` opts out for a single command.

Full command reference and the complete recognized-runner list: [docs/COMMANDS.md](https://github.com/hari-kancharla/Debug-Brief/blob/main/docs/COMMANDS.md). Security model and redaction details: [SECURITY.md](https://github.com/hari-kancharla/Debug-Brief/blob/main/SECURITY.md).

Post a report straight to a pull request (GitHub CLI optional):

```bash
debugbrief end --stdout | gh pr comment --body-file -
```

## Commands

The six you use most:

| Command | What it does |
| --- | --- |
| `start "<title>"` | Start a session |
| `note <text>` | Record an observation |
| `run -- <command>` | Run and capture a command |
| `redo [--dry-run] [--yes]` | Re-run the last captured command, with a safe preview/confirmation gate |
| `end [--mode pr\|handoff\|incident] [--format md\|json\|html\|both\|all]` | Finalize and write a report (default `pr`, Markdown) |
| `open --html` / `last --open` | Review the saved proof in a browser or editor |

The rest:

| Command | What it does |
| --- | --- |
| `init` | Set up the project and show the workflow |
| `status` | Show the active session |
| `preview [--mode ...] [--format md\|json\|html]` | Print a report preview without ending the session |
| `cancel [--yes]` | Abandon the active session; no report, local record retained |
| `doctor [--fix]` | Health-check the project and state |
| `recover` | Repair a broken session pointer after a crash |
| `last` | Show the most recent report path |
| `open` | Open the most recent report |
| `list` | List recorded sessions |
| `show <id>` | Show a recorded session |

Full flags and behavior for each: [docs/COMMANDS.md](https://github.com/hari-kancharla/Debug-Brief/blob/main/docs/COMMANDS.md).

## Dependencies

DebugBrief uses the Python standard library and native `git`. On Python 3.11 and newer it needs nothing else. On Python 3.9 and 3.10 it uses the small `tomli` package to read an optional `.debugbrief.toml`. DebugBrief itself makes no network requests, uses no AI, and collects no telemetry.

## Supported platforms

Linux and macOS are tested in CI across Python 3.9 through 3.14. Other Unix-like systems may work but are not currently tested. Native Windows and PowerShell are not supported.

## Limitations

- Capture is explicit through `debugbrief run`. Output streams live while a bounded preview is stored for the report, so there is no full transcript.
- Full-screen TUIs (a `vim` session, `htop`) are not meaningfully captured. Run those directly and record the outcome with `note`.
- Redaction is conservative and best effort; it does not catch every secret.
- Git sections need native `git`; outside a repository they are omitted.

## Development

```bash
pip install -e ".[dev]"
pytest
```

See [CONTRIBUTING.md](https://github.com/hari-kancharla/Debug-Brief/blob/main/CONTRIBUTING.md) for the full setup and contribution guidelines.

## License

MIT. See [LICENSE](https://github.com/hari-kancharla/Debug-Brief/blob/main/LICENSE).
