diffbutler 0.5.0__tar.gz

diffbutler-0.5.0/LICENSE.txt

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

diffbutler-0.5.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: diffbutler
+Version: 0.5.0
+Summary: A terminal dashboard for human-directed AI code reviews.
+Keywords: code-review,github,terminal,ai
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Dist: aiosqlite>=0.22.1
+Requires-Dist: alembic>=1.19.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: pydantic-settings>=2.15.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.52
+Requires-Dist: textual>=8.2.8
+Requires-Dist: tomlkit>=0.15.1
+Requires-Dist: typer>=0.27.2
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# DiffButler
+
+A terminal dashboard for human-directed AI code reviews on GitHub.
+
+Keep track of what each pull request needs next: AI review, your review, or author
+changes. Start an AI review, discuss its findings in the agent's own session, and
+finish your review in the browser.
+
+![DiffButler dashboard showing pull requests and the next review action](diffbutler.png)
+
+## Install
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and Git.
+From a local checkout of this repository, run:
+
+```sh
+uv tool install --python 3.14 .
+```
+
+uv manages Python and dependencies in an isolated environment. No virtual environment
+activation is needed. If `diffbutler` is not on your PATH, run `uv tool update-shell`
+and restart your shell.
+
+Install and sign in to Codex CLI or Claude Code before requesting AI reviews.
+The native presets support Codex CLI or Claude Code on Linux and macOS without version checks.
+Reviews use your normal agent settings, including model and reasoning effort, with
+background permission and output overrides. New conversations remain in the agent’s
+own history after DiffButler cleans up its workspaces; existing private sessions
+retain their original home for resume.
+See [supported agents and validation](docs/native-reviews.md) for details.
+
+## Use
+
+Use authenticated GitHub access, including for public repositories. If you already
+use `gh auth login`, export its token before launching DiffButler:
+
+```sh
+export GITHUB_TOKEN="$(gh auth token)"
+```
+
+Alternatively, create a [fine-grained personal access token](https://github.com/settings/personal-access-tokens)
+for the repositories you want to review with **Pull requests: Read-only** permission,
+and set it as `GITHUB_TOKEN`. Anonymous access is a last resort for public repositories;
+its low API quota makes it unsuitable for regular polling. See the
+[authentication guide](docs/github.md#authentication-options) for host/account selection,
+HTTPS versus SSH Git setup, and token permissions.
+
+From the GitHub repository you want to review, launch:
+
+```sh
+diffbutler
+```
+
+First-run setup detects the local repository, looks up your GitHub username using
+the selected token, asks for your preferred agent, and saves your choices. If username detection
+is unavailable, setup asks for it. Choose the recommended token access for public repositories;
+private repositories require it. Setup asks for the token's environment variable name
+and validates access. It never saves the token.
+New configs silently enable both Codex and Claude when found in `PATH`; setup asks
+only which detected agent should be the default. Missing agents get commented-out
+entries you can enable after installation.
+Later launches reuse your configuration.
+
+The dashboard shows active reviews, including followed PRs whose GitHub review
+requests have disappeared after you posted feedback. Waiting-for-author reviews
+stay visible across refreshes and restarts. If an approved PR receives new commits,
+it reappears as `done+` at the end of the queue without starting another AI review.
+Authenticated polling slows when API quota is scarce and speeds back up when it
+recovers, accounting for refresh cost and time until the quota resets.
+
+Select a PR with the arrow keys, then work through the review:
+
+1. Optionally press `n` to change the current configured AI reviewer for all PRs.
+   Press `r` to start a background AI review. Reviews start only when you request them.
+   The agent is instructed to read the PR description, discussion, and earlier review
+   threads and replies before reviewing the local code, reporting any unavailable context.
+   DiffButler caches full Git history and reviews changes from the PR merge base
+   to its head, excluding unrelated changes made later on the target branch.
+2. A successful review shows `approve` only when the AI explicitly reports no findings;
+   otherwise it shows `check`. Press `Enter` to read the results, or `c` to resume
+   the saved agent conversation.
+   If the agent exits normally but DiffButler cannot parse its output, the task also
+   shows `check`; use `c` to inspect the saved conversation or `L` for captured output.
+   Changing reviewers leaves that conversation available through `c`; pressing `r`
+   starts a new run with the current reviewer and replaces the current review details.
+   Ask questions and explicitly tell the agent which comments to post, if any.
+3. Exit the agent to return to the dashboard, which refreshes activity from GitHub.
+   Press `w` if you are waiting for author changes, or `o` to review in your browser.
+4. After approving on GitHub, press `m` to mark the task complete locally. DiffButler
+   also detects your approval, closure, or merge and cleans up owned session resources
+   while retaining review history.
+
+`Space` performs the selected PR's next action: start a review, discuss findings,
+or open the browser. An AI review never counts as your approval. Background analysis
+uses the agent's [native permission controls](docs/native-reviews.md#native-permissions-and-authentication)
+and read-only review instructions; source sent to the agent may go to its model provider.
+
+- `/`: Filter the queue.
+- `a`: Toggle monitoring all open PRs in configured repositories.
+- `b`: Browse accessible PRs and follow one.
+- `R`: Refresh from GitHub.
+- `k`: Stop the selected PR's review and reset its local tracking and owned resources.
+  It disappears until a forge refresh rediscovers it; review history is retained.
+- `h`: View completed review history.
+- `?`: Show all keyboard shortcuts.
+- `q`: Quit.
+
+See the [dashboard guide](docs/dashboard.md) for all actions and
+[configuration guide](docs/configuration.md) for settings.
+
+Your own PRs are hidden from the review queue by default, including direct and team
+requests. Set `include_own_prs = true` in `[ui]` to review them, such as PRs an agent
+created using your account. PRs assigned to you are also hidden by default, even when
+you are requested directly or through a team. Set `include_assigned_prs = true` in
+`[ui]` to include them.
+
+## Reset
+
+Close running DiffButler sessions, then run:
+
+```sh
+diffbutler reset
+```
+
+DiffButler refuses a second command or dashboard using the same data home, including
+`reset`, while another instance is running. Its instance lock releases on process
+exit; a leftover PID file does not block startup. See the
+[locking details](docs/configuration.md#single-instance) before handling Git lock files
+or resetting after a crash.
+
+After confirmation, this permanently removes DiffButler's standard configuration,
+data, and state directories, including review history, saved sessions, and diagnostic
+logs. Custom files outside those directories are preserved. Use `diffbutler reset --force`
+to skip confirmation. Run `diffbutler` again to repeat first-run setup.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and checks.
+
+## License
+
+[MIT](LICENSE.txt).

diffbutler-0.5.0/README.md

@@ -0,0 +1,142 @@
+# DiffButler
+
+A terminal dashboard for human-directed AI code reviews on GitHub.
+
+Keep track of what each pull request needs next: AI review, your review, or author
+changes. Start an AI review, discuss its findings in the agent's own session, and
+finish your review in the browser.
+
+![DiffButler dashboard showing pull requests and the next review action](diffbutler.png)
+
+## Install
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and Git.
+From a local checkout of this repository, run:
+
+```sh
+uv tool install --python 3.14 .
+```
+
+uv manages Python and dependencies in an isolated environment. No virtual environment
+activation is needed. If `diffbutler` is not on your PATH, run `uv tool update-shell`
+and restart your shell.
+
+Install and sign in to Codex CLI or Claude Code before requesting AI reviews.
+The native presets support Codex CLI or Claude Code on Linux and macOS without version checks.
+Reviews use your normal agent settings, including model and reasoning effort, with
+background permission and output overrides. New conversations remain in the agent’s
+own history after DiffButler cleans up its workspaces; existing private sessions
+retain their original home for resume.
+See [supported agents and validation](docs/native-reviews.md) for details.
+
+## Use
+
+Use authenticated GitHub access, including for public repositories. If you already
+use `gh auth login`, export its token before launching DiffButler:
+
+```sh
+export GITHUB_TOKEN="$(gh auth token)"
+```
+
+Alternatively, create a [fine-grained personal access token](https://github.com/settings/personal-access-tokens)
+for the repositories you want to review with **Pull requests: Read-only** permission,
+and set it as `GITHUB_TOKEN`. Anonymous access is a last resort for public repositories;
+its low API quota makes it unsuitable for regular polling. See the
+[authentication guide](docs/github.md#authentication-options) for host/account selection,
+HTTPS versus SSH Git setup, and token permissions.
+
+From the GitHub repository you want to review, launch:
+
+```sh
+diffbutler
+```
+
+First-run setup detects the local repository, looks up your GitHub username using
+the selected token, asks for your preferred agent, and saves your choices. If username detection
+is unavailable, setup asks for it. Choose the recommended token access for public repositories;
+private repositories require it. Setup asks for the token's environment variable name
+and validates access. It never saves the token.
+New configs silently enable both Codex and Claude when found in `PATH`; setup asks
+only which detected agent should be the default. Missing agents get commented-out
+entries you can enable after installation.
+Later launches reuse your configuration.
+
+The dashboard shows active reviews, including followed PRs whose GitHub review
+requests have disappeared after you posted feedback. Waiting-for-author reviews
+stay visible across refreshes and restarts. If an approved PR receives new commits,
+it reappears as `done+` at the end of the queue without starting another AI review.
+Authenticated polling slows when API quota is scarce and speeds back up when it
+recovers, accounting for refresh cost and time until the quota resets.
+
+Select a PR with the arrow keys, then work through the review:
+
+1. Optionally press `n` to change the current configured AI reviewer for all PRs.
+   Press `r` to start a background AI review. Reviews start only when you request them.
+   The agent is instructed to read the PR description, discussion, and earlier review
+   threads and replies before reviewing the local code, reporting any unavailable context.
+   DiffButler caches full Git history and reviews changes from the PR merge base
+   to its head, excluding unrelated changes made later on the target branch.
+2. A successful review shows `approve` only when the AI explicitly reports no findings;
+   otherwise it shows `check`. Press `Enter` to read the results, or `c` to resume
+   the saved agent conversation.
+   If the agent exits normally but DiffButler cannot parse its output, the task also
+   shows `check`; use `c` to inspect the saved conversation or `L` for captured output.
+   Changing reviewers leaves that conversation available through `c`; pressing `r`
+   starts a new run with the current reviewer and replaces the current review details.
+   Ask questions and explicitly tell the agent which comments to post, if any.
+3. Exit the agent to return to the dashboard, which refreshes activity from GitHub.
+   Press `w` if you are waiting for author changes, or `o` to review in your browser.
+4. After approving on GitHub, press `m` to mark the task complete locally. DiffButler
+   also detects your approval, closure, or merge and cleans up owned session resources
+   while retaining review history.
+
+`Space` performs the selected PR's next action: start a review, discuss findings,
+or open the browser. An AI review never counts as your approval. Background analysis
+uses the agent's [native permission controls](docs/native-reviews.md#native-permissions-and-authentication)
+and read-only review instructions; source sent to the agent may go to its model provider.
+
+- `/`: Filter the queue.
+- `a`: Toggle monitoring all open PRs in configured repositories.
+- `b`: Browse accessible PRs and follow one.
+- `R`: Refresh from GitHub.
+- `k`: Stop the selected PR's review and reset its local tracking and owned resources.
+  It disappears until a forge refresh rediscovers it; review history is retained.
+- `h`: View completed review history.
+- `?`: Show all keyboard shortcuts.
+- `q`: Quit.
+
+See the [dashboard guide](docs/dashboard.md) for all actions and
+[configuration guide](docs/configuration.md) for settings.
+
+Your own PRs are hidden from the review queue by default, including direct and team
+requests. Set `include_own_prs = true` in `[ui]` to review them, such as PRs an agent
+created using your account. PRs assigned to you are also hidden by default, even when
+you are requested directly or through a team. Set `include_assigned_prs = true` in
+`[ui]` to include them.
+
+## Reset
+
+Close running DiffButler sessions, then run:
+
+```sh
+diffbutler reset
+```
+
+DiffButler refuses a second command or dashboard using the same data home, including
+`reset`, while another instance is running. Its instance lock releases on process
+exit; a leftover PID file does not block startup. See the
+[locking details](docs/configuration.md#single-instance) before handling Git lock files
+or resetting after a crash.
+
+After confirmation, this permanently removes DiffButler's standard configuration,
+data, and state directories, including review history, saved sessions, and diagnostic
+logs. Custom files outside those directories are preserved. Use `diffbutler reset --force`
+to skip confirmation. Run `diffbutler` again to repeat first-run setup.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and checks.
+
+## License
+
+[MIT](LICENSE.txt).

diffbutler-0.5.0/pyproject.toml

@@ -0,0 +1,142 @@
+[project]
+name = "diffbutler"
+version = "0.5.0"
+description = "A terminal dashboard for human-directed AI code reviews."
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE.txt"]
+keywords = [
+    "code-review",
+    "github",
+    "terminal",
+    "ai",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aiosqlite>=0.22.1",
+    "alembic>=1.19.1",
+    "httpx>=0.28.1",
+    "pydantic>=2.13.5",
+    "pydantic-settings>=2.15.0",
+    "rich>=15.0.0",
+    "sqlalchemy[asyncio]>=2.0.52",
+    "textual>=8.2.8",
+    "tomlkit>=0.15.1",
+    "typer>=0.27.2",
+]
+
+[project.scripts]
+diffbutler = "diffbutler.ui.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "import-linter>=2.14",
+    "markdown-it-py>=4.2.0",
+    "pip-audit>=2.10.1",
+    "pyright[nodejs]>=1.1.411",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+    "pytest-xdist>=3.8.0",
+    "ruff>=0.16.5",
+]
+
+[tool.uv]
+required-version = ">=0.12.13,<0.13"
+exclude-newer = "15 days"
+
+[tool.ruff]
+target-version = "py314"
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "C4",
+    "RUF",
+]
+
+[tool.pyright]
+include = [
+    "src",
+    "tests",
+    "scripts",
+]
+pythonVersion = "3.14"
+typeCheckingMode = "strict"
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+minversion = "9.0"
+testpaths = ["tests"]
+addopts = [
+    "--strict-config",
+    "--strict-markers",
+    "--import-mode=importlib",
+    "--dist=worksteal",
+]
+markers = ["serial: timing-sensitive UI, terminal, or native-agent integration; run without xdist"]
+filterwarnings = ["error"]
+asyncio_mode = "strict"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.coverage.run]
+branch = true
+source = ["diffbutler"]
+omit = ["src/diffbutler/__main__.py"]
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true
+
+[tool.importlinter]
+root_package = "diffbutler"
+include_external_packages = true
+
+[[tool.importlinter.contracts]]
+name = "Layered architecture"
+type = "layers"
+layers = [
+    "diffbutler.ui",
+    "diffbutler.core",
+    "diffbutler.forges | diffbutler.reviewers | diffbutler.sources | diffbutler.store",
+    "diffbutler.domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Terminal rendering stays out of the core and adapters"
+type = "forbidden"
+source_modules = [
+    "diffbutler.core",
+    "diffbutler.domain",
+    "diffbutler.forges",
+    "diffbutler.reviewers",
+    "diffbutler.sources",
+    "diffbutler.store",
+    "diffbutler.config",
+]
+forbidden_modules = [
+    "textual",
+    "rich",
+]

diffbutler-0.5.0/pyproject.toml.orig

@@ -0,0 +1,112 @@
+[project]
+name = "diffbutler"
+version = "0.5.0"
+description = "A terminal dashboard for human-directed AI code reviews."
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE.txt"]
+keywords = ["code-review", "github", "terminal", "ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aiosqlite>=0.22.1",
+    "alembic>=1.19.1",
+    "httpx>=0.28.1",
+    "pydantic>=2.13.5",
+    "pydantic-settings>=2.15.0",
+    "rich>=15.0.0",
+    "sqlalchemy[asyncio]>=2.0.52",
+    "textual>=8.2.8",
+    "tomlkit>=0.15.1",
+    "typer>=0.27.2",
+]
+
+[project.scripts]
+diffbutler = "diffbutler.ui.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "import-linter>=2.14",
+    "markdown-it-py>=4.2.0",
+    "pip-audit>=2.10.1",
+    "pyright[nodejs]>=1.1.411",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+    "pytest-xdist>=3.8.0",
+    "ruff>=0.16.5",
+]
+
+[tool.uv]
+required-version = ">=0.12.13,<0.13"
+# Give new dependency releases time to settle before routine upgrades.
+exclude-newer = "15 days"
+
+[tool.ruff]
+target-version = "py314"
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "C4", "RUF"]
+
+[tool.pyright]
+include = ["src", "tests", "scripts"]
+pythonVersion = "3.14"
+typeCheckingMode = "strict"
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+minversion = "9.0"
+testpaths = ["tests"]
+addopts = ["--strict-config", "--strict-markers", "--import-mode=importlib", "--dist=worksteal"]
+markers = ["serial: timing-sensitive UI, terminal, or native-agent integration; run without xdist"]
+filterwarnings = ["error"]
+asyncio_mode = "strict"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.coverage.run]
+branch = true
+source = ["diffbutler"]
+omit = ["src/diffbutler/__main__.py"]
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true
+
+[tool.importlinter]
+root_package = "diffbutler"
+include_external_packages = true
+
+[[tool.importlinter.contracts]]
+name = "Layered architecture"
+type = "layers"
+layers = [
+    "diffbutler.ui",
+    "diffbutler.core",
+    "diffbutler.forges | diffbutler.reviewers | diffbutler.sources | diffbutler.store",
+    "diffbutler.domain",
+]
+
+[[tool.importlinter.contracts]]
+name = "Terminal rendering stays out of the core and adapters"
+type = "forbidden"
+source_modules = [
+    "diffbutler.core", "diffbutler.domain", "diffbutler.forges",
+    "diffbutler.reviewers", "diffbutler.sources", "diffbutler.store", "diffbutler.config",
+]
+forbidden_modules = ["textual", "rich"]

diffbutler-0.5.0/src/diffbutler/__init__.py

@@ -0,0 +1 @@
+"""DiffButler: human-directed AI code reviews."""

diffbutler-0.5.0/src/diffbutler/__main__.py

@@ -0,0 +1,6 @@
+"""Support ``python -m diffbutler``."""
+
+from diffbutler.ui.cli import main
+
+if __name__ == "__main__":
+    main()

diffbutler-0.5.0/src/diffbutler/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration loading and validation."""