debugbrief 1.2.0__tar.gz → 1.3.0__tar.gz

debugbrief-1.3.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: debugbrief
+Version: 1.3.0
+Summary: Records debugging commands, outcomes, notes, and Git changes, then generates evidence-backed Markdown reports for pull requests, handoffs, and incidents.
+Author: Hari Krishna Kancharla
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/harihkk/Debug-Brief
+Project-URL: Repository, https://github.com/harihkk/Debug-Brief
+Project-URL: Documentation, https://github.com/harihkk/Debug-Brief/tree/main/docs
+Project-URL: Changelog, https://github.com/harihkk/Debug-Brief/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/harihkk/Debug-Brief/issues
+Project-URL: Security, https://github.com/harihkk/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/harihkk/Debug-Brief/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/harihkk/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 Markdown 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/harihkk/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.
+
+## Install
+
+```bash
+pipx install debugbrief
+# or
+uv tool install debugbrief
+```
+
+Plain `pip install debugbrief` works too. 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 start "Fix add() returning wrong result"
+debugbrief note "add() subtracts instead of adds; the test expects 5."
+debugbrief run -- python -m pytest -q test_calc.py   # fails
+# make your fix
+debugbrief redo                                      # same test, now passes
+debugbrief end                                       # writes the PR report
+```
+
+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` re-runs the last captured command, and `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/harihkk/Debug-Brief/blob/main/examples/sample-pr.md), [handoff](https://github.com/harihkk/Debug-Brief/blob/main/examples/sample-handoff.md), [incident](https://github.com/harihkk/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.
+- Pass or fail comes only from the exit code. A command counts as verified only when a recognized test, build, lint, or typecheck runner actually exits 0.
+- 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: the red-to-green window, the reproduce and verify commands, a timeline, the observed error, and the failed attempts. Empty sections are omitted.
+- 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/harihkk/Debug-Brief/blob/main/docs/COMMANDS.md). Security model and redaction details: [SECURITY.md](https://github.com/harihkk/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 five 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` | Re-run the last captured command |
+| `end [--mode pr\|handoff\|incident]` | Finalize and write a report (default `pr`) |
+
+The rest:
+
+| Command | What it does |
+| --- | --- |
+| `init` | Set up the project and show the workflow |
+| `status` | Show the active session |
+| `preview [--mode ...]` | Print the report without ending the session |
+| `cancel [--yes]` | Discard the active session, no report |
+| `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/harihkk/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/harihkk/Debug-Brief/blob/main/CONTRIBUTING.md) for the full setup and contribution guidelines.
+
+## License
+
+MIT. See [LICENSE](https://github.com/harihkk/Debug-Brief/blob/main/LICENSE).

debugbrief-1.3.0/README.md

@@ -0,0 +1,131 @@
+# DebugBrief
+
+[![CI](https://github.com/harihkk/Debug-Brief/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/harihkk/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 Markdown 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/harihkk/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.
+
+## Install
+
+```bash
+pipx install debugbrief
+# or
+uv tool install debugbrief
+```
+
+Plain `pip install debugbrief` works too. 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 start "Fix add() returning wrong result"
+debugbrief note "add() subtracts instead of adds; the test expects 5."
+debugbrief run -- python -m pytest -q test_calc.py   # fails
+# make your fix
+debugbrief redo                                      # same test, now passes
+debugbrief end                                       # writes the PR report
+```
+
+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` re-runs the last captured command, and `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/harihkk/Debug-Brief/blob/main/examples/sample-pr.md), [handoff](https://github.com/harihkk/Debug-Brief/blob/main/examples/sample-handoff.md), [incident](https://github.com/harihkk/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.
+- Pass or fail comes only from the exit code. A command counts as verified only when a recognized test, build, lint, or typecheck runner actually exits 0.
+- 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: the red-to-green window, the reproduce and verify commands, a timeline, the observed error, and the failed attempts. Empty sections are omitted.
+- 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/harihkk/Debug-Brief/blob/main/docs/COMMANDS.md). Security model and redaction details: [SECURITY.md](https://github.com/harihkk/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 five 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` | Re-run the last captured command |
+| `end [--mode pr\|handoff\|incident]` | Finalize and write a report (default `pr`) |
+
+The rest:
+
+| Command | What it does |
+| --- | --- |
+| `init` | Set up the project and show the workflow |
+| `status` | Show the active session |
+| `preview [--mode ...]` | Print the report without ending the session |
+| `cancel [--yes]` | Discard the active session, no report |
+| `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/harihkk/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/harihkk/Debug-Brief/blob/main/CONTRIBUTING.md) for the full setup and contribution guidelines.
+
+## License
+
+MIT. See [LICENSE](https://github.com/harihkk/Debug-Brief/blob/main/LICENSE).

{debugbrief-1.2.0 → debugbrief-1.3.0}/pyproject.toml

@@ -5,14 +5,25 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "debugbrief"
-version = "1.2.0"
-description = "Local-first CLI that records the meaningful context of a debugging session and turns it into a useful markdown brief."
+version = "1.3.0"
+description = "Records debugging commands, outcomes, notes, and Git changes, then generates evidence-backed Markdown reports for pull requests, handoffs, and incidents."
 readme = "README.md"
 requires-python = ">=3.9"
 license = "MIT"
 license-files = ["LICENSE"]
-authors = [{ name = "DebugBrief" }]
-keywords = ["cli", "debugging", "pull-request", "handoff", "incident", "report"]
+authors = [{ name = "Hari Krishna Kancharla" }]
+keywords = [
+    "cli",
+    "debugging",
+    "developer-tools",
+    "git",
+    "testing",
+    "pull-request",
+    "handoff",
+    "incident",
+    "report",
+    "terminal",
+]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Environment :: Console",
@@ -25,21 +36,31 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development",
 ]
 
-# DebugBrief intentionally has ZERO runtime dependencies.
-# It uses only the Python standard library and native `git`.
-dependencies = []
+# DebugBrief uses only the Python standard library and native `git`, with one
+# conditional compatibility dependency: the `tomli` TOML parser on Python < 3.11,
+# where the standard-library `tomllib` is not yet available (3.11+ needs nothing).
+dependencies = [
+    "tomli>=2.0.1; python_version < '3.11'",
+]
 
 [project.urls]
 Homepage = "https://github.com/harihkk/Debug-Brief"
 Repository = "https://github.com/harihkk/Debug-Brief"
+Documentation = "https://github.com/harihkk/Debug-Brief/tree/main/docs"
 Changelog = "https://github.com/harihkk/Debug-Brief/blob/main/CHANGELOG.md"
 Issues = "https://github.com/harihkk/Debug-Brief/issues"
+Security = "https://github.com/harihkk/Debug-Brief/security/policy"
 
 [project.optional-dependencies]
-dev = ["pytest>=7.0"]
+# Development and CI tooling only. These are never runtime dependencies;
+# DebugBrief's only runtime dependency is the conditional `tomli` below 3.11.
+dev = ["pytest>=7.0", "ruff>=0.6", "mypy>=1.8", "build>=1.0"]
+# Release tooling, used only to build and check distributions before publishing.
+release = ["build>=1.0", "twine>=5.0"]
 
 [project.scripts]
 debugbrief = "debugbrief.cli:main"

{debugbrief-1.2.0 → debugbrief-1.3.0}/src/debugbrief/__init__.py

@@ -4,10 +4,11 @@ DebugBrief captures the useful path of a debugging session -- notes, executed
 commands and their outcomes, Git state changes, and verification steps -- and
 turns it into a concise, honest markdown brief (PR, handoff, or incident).
 
-It uses only the Python standard library and native ``git``. No AI, no
-telemetry, no cloud sync, no background daemon.
+It uses the Python standard library and native ``git``, with one conditional
+dependency: the ``tomli`` TOML parser on Python < 3.11 (3.11+ uses the
+standard-library ``tomllib``). No AI, no telemetry, no cloud sync, no daemon.
 """
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"
 
 __all__ = ["__version__"]