debugbrief 1.1.0__tar.gz

debugbrief-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DebugBrief contributors
+
+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.

debugbrief-1.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: debugbrief
+Version: 1.1.0
+Summary: Local-first CLI that records the meaningful context of a debugging session and turns it into a useful markdown brief.
+Author: DebugBrief
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/harihkk/Debug-Brief
+Project-URL: Repository, https://github.com/harihkk/Debug-Brief
+Project-URL: Changelog, https://github.com/harihkk/Debug-Brief/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/harihkk/Debug-Brief/issues
+Keywords: cli,debugging,pull-request,handoff,incident,report
+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: Topic :: Software Development
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+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)](https://pypi.org/project/debugbrief/)
+
+Turn a debugging session into an honest markdown brief for a PR, a handoff, or an
+incident note.
+
+You record notes and run commands through DebugBrief while you work. When you are
+done, it writes a report built only from what actually happened: what you tried,
+what failed, what then passed, and which files changed in between. It never
+invents a root cause and never claims a test result you did not get.
+
+It is local-first and dependency-free: standard library plus native `git`, no
+network, no AI, no telemetry. Unix-like systems only.
+
+See a real generated report: [examples/sample-pr.md](examples/sample-pr.md).
+
+## Install
+
+```bash
+pip install debugbrief
+```
+
+Or from a clone: `pip install -e .`. Needs Python 3.9+ and native `git` on a
+Unix-like system (Linux, macOS, BSD).
+
+## 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 again: passes
+debugbrief end                                       # writes the pr-style brief
+```
+
+Everything after `--` runs exactly as you typed it, with its output streaming
+live to your terminal; DebugBrief flags (`--timeout`, `--shell`, `--no-redact`)
+go before the `--`. Quoting the whole command also works: `debugbrief run
+"pytest -q"`. `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
+```
+
+`run` and `note` auto-start a session if you forget to, so a capture is never
+lost (and `debugbrief cancel` discards a session you did not mean to start).
+The resulting report leads with a derived one-liner like:
+
+> Failing check `python -m pytest -q test_calc.py` passed after 2 attempts over
+> 2s, changes touched calc.py.
+
+## How it works
+
+- `run` executes a command, records its real exit code, bounded output, duration,
+  and a per-command git snapshot, then returns the command's own exit code.
+- Pass/fail comes only from the exit code. A command counts as "verified" only if
+  a recognized test/build/lint/typecheck command actually exited `0`.
+- `end` derives the report from those events: the red-to-green window, the
+  reproduce/verify commands, a timeline, the observed error verbatim, and what
+  was ruled out. Empty sections are omitted, never padded.
+- Secret-like values in captured output are replaced with `[redacted]` before
+  anything is written to disk (best effort; `--no-redact` opts out).
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `start "<title>"` | Start a session |
+| `note <text ...>` | Record a note (quoting optional) |
+| `run -- <command ...>` | Execute and capture a command |
+| `redo` | Re-run the last captured command |
+| `end [--mode pr\|handoff\|incident]` | Finalize and write a report (default `pr`) |
+| `cancel [--yes]` | Discard the active session, no report |
+| `status` | Show the active session |
+| `doctor [--fix]` | Health-check the project and state |
+| `last` / `open` | Find or open the most recent report |
+| `list` / `show <id>` | Browse recorded sessions |
+
+Full detail, flags, and the report modes: [docs/COMMANDS.md](docs/COMMANDS.md).
+
+Post a brief straight to a PR (GitHub CLI optional):
+
+```bash
+debugbrief end --stdout | gh pr comment --body-file -
+```
+
+## Limitations
+
+- Unix-like only; no Windows/PowerShell.
+- Capture is explicit via `debugbrief run`. There is no terminal transcript or
+  PTY capture, and output is stored as bounded previews, not full logs.
+- Interactive and TUI commands (a pdb session, watch modes) will behave oddly
+  under `run`, because output is piped for capture rather than attached to a
+  terminal. 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 repo they are omitted honestly.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

debugbrief-1.1.0/README.md

@@ -0,0 +1,113 @@
+# 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)](https://pypi.org/project/debugbrief/)
+
+Turn a debugging session into an honest markdown brief for a PR, a handoff, or an
+incident note.
+
+You record notes and run commands through DebugBrief while you work. When you are
+done, it writes a report built only from what actually happened: what you tried,
+what failed, what then passed, and which files changed in between. It never
+invents a root cause and never claims a test result you did not get.
+
+It is local-first and dependency-free: standard library plus native `git`, no
+network, no AI, no telemetry. Unix-like systems only.
+
+See a real generated report: [examples/sample-pr.md](examples/sample-pr.md).
+
+## Install
+
+```bash
+pip install debugbrief
+```
+
+Or from a clone: `pip install -e .`. Needs Python 3.9+ and native `git` on a
+Unix-like system (Linux, macOS, BSD).
+
+## 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 again: passes
+debugbrief end                                       # writes the pr-style brief
+```
+
+Everything after `--` runs exactly as you typed it, with its output streaming
+live to your terminal; DebugBrief flags (`--timeout`, `--shell`, `--no-redact`)
+go before the `--`. Quoting the whole command also works: `debugbrief run
+"pytest -q"`. `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
+```
+
+`run` and `note` auto-start a session if you forget to, so a capture is never
+lost (and `debugbrief cancel` discards a session you did not mean to start).
+The resulting report leads with a derived one-liner like:
+
+> Failing check `python -m pytest -q test_calc.py` passed after 2 attempts over
+> 2s, changes touched calc.py.
+
+## How it works
+
+- `run` executes a command, records its real exit code, bounded output, duration,
+  and a per-command git snapshot, then returns the command's own exit code.
+- Pass/fail comes only from the exit code. A command counts as "verified" only if
+  a recognized test/build/lint/typecheck command actually exited `0`.
+- `end` derives the report from those events: the red-to-green window, the
+  reproduce/verify commands, a timeline, the observed error verbatim, and what
+  was ruled out. Empty sections are omitted, never padded.
+- Secret-like values in captured output are replaced with `[redacted]` before
+  anything is written to disk (best effort; `--no-redact` opts out).
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `start "<title>"` | Start a session |
+| `note <text ...>` | Record a note (quoting optional) |
+| `run -- <command ...>` | Execute and capture a command |
+| `redo` | Re-run the last captured command |
+| `end [--mode pr\|handoff\|incident]` | Finalize and write a report (default `pr`) |
+| `cancel [--yes]` | Discard the active session, no report |
+| `status` | Show the active session |
+| `doctor [--fix]` | Health-check the project and state |
+| `last` / `open` | Find or open the most recent report |
+| `list` / `show <id>` | Browse recorded sessions |
+
+Full detail, flags, and the report modes: [docs/COMMANDS.md](docs/COMMANDS.md).
+
+Post a brief straight to a PR (GitHub CLI optional):
+
+```bash
+debugbrief end --stdout | gh pr comment --body-file -
+```
+
+## Limitations
+
+- Unix-like only; no Windows/PowerShell.
+- Capture is explicit via `debugbrief run`. There is no terminal transcript or
+  PTY capture, and output is stored as bounded previews, not full logs.
+- Interactive and TUI commands (a pdb session, watch modes) will behave oddly
+  under `run`, because output is piped for capture rather than attached to a
+  terminal. 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 repo they are omitted honestly.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

debugbrief-1.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+# 77+ understands the PEP 639 SPDX `license` string below.
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "debugbrief"
+version = "1.1.0"
+description = "Local-first CLI that records the meaningful context of a debugging session and turns it into a useful markdown brief."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "DebugBrief" }]
+keywords = ["cli", "debugging", "pull-request", "handoff", "incident", "report"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+]
+
+# DebugBrief intentionally has ZERO runtime dependencies.
+# It uses only the Python standard library and native `git`.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/harihkk/Debug-Brief"
+Repository = "https://github.com/harihkk/Debug-Brief"
+Changelog = "https://github.com/harihkk/Debug-Brief/blob/main/CHANGELOG.md"
+Issues = "https://github.com/harihkk/Debug-Brief/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.scripts]
+debugbrief = "debugbrief.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+# "UP" is deliberately excluded to preserve the explicit typing.List/Optional
+# style required for Python 3.9 support.
+select = ["E", "F", "W", "I", "B", "SIM", "C4", "RET", "PIE"]
+
+[tool.ruff.lint.per-file-ignores]
+# Test files carry long assertion and snapshot literals.
+"tests/*" = ["E501"]

debugbrief-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

debugbrief-1.1.0/src/debugbrief/__init__.py

@@ -0,0 +1,13 @@
+"""DebugBrief: a local-first CLI for recording debugging sessions.
+
+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.
+"""
+
+__version__ = "1.1.0"
+
+__all__ = ["__version__"]

debugbrief-1.1.0/src/debugbrief/__main__.py

@@ -0,0 +1,10 @@
+"""Allow running the CLI via ``python -m debugbrief``."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())