diffbutler 0.5.0__py3-none-any.whl

diffbutler/__init__.py

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

diffbutler/__main__.py

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

diffbutler/config/__init__.py

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

diffbutler/config/default.toml

@@ -0,0 +1,91 @@
+# DiffButler configuration. Omitted options use their built-in defaults.
+# No forge or reviewer is configured until you add one below.
+forges = []
+reviewers = []
+
+[general]
+# Minimum: 60 seconds with authenticated accounts, 600 with any public account.
+# poll_interval_s = 600 # Override the minimum; low authenticated quota slows polling.
+max_concurrent_reviews = 2
+# Omit workspace_root to follow $XDG_DATA_HOME/diffbutler/reviews
+# (default ~/.local/share/diffbutler/reviews).
+# workspace_root = "~/diffbutler-reviews"
+# Shared bare repositories; default $XDG_DATA_HOME/diffbutler/repos.
+# repository_root = "~/diffbutler-repos"
+# Evict unused repositories after 30 days; active session pins never expire.
+# repository_retention_days = 30
+# Optional reconstructible snapshots; conversations remain in workspace_root.
+# Use a new private directory, separate from the other managed roots.
+# snapshot_root = "/tmp/diffbutler-snapshots-yourname"
+
+[db]
+auto_migrate = true
+# Omit url to follow $XDG_DATA_HOME/diffbutler/diffbutler.db
+# (default ~/.local/share/diffbutler/diffbutler.db).
+# url = "sqlite+aiosqlite:///~/my-data/diffbutler.db"
+
+[review]
+findings_threshold = "minor" # blocking | important | minor | nit | question
+min_confidence = 0.5
+exclude_globs = ["**/*.lock", "**/vendor/**", "**/*.min.js", "**/generated/**"]
+mode = "source_only"
+checkout = "worktree" # Native reviews currently use pinned source snapshots.
+# default_reviewer = "codex"
+# prompt = "~/review-instructions.md"
+
+[ui]
+include_own_prs = false # Set true to review PRs authored by your account.
+include_assigned_prs = false # Set true to review PRs assigned to your account.
+columns = ["number", "title", "author", "state"]
+sort_by = "attention"
+sort_desc = true
+preview_pane = true
+default_filter = "active"
+# browser_command = ["firefox", "--new-tab"]
+
+[ui.attention]
+blocking = 100
+important = 40
+age_pressure_per_day = 5
+size_penalty_per_100_lines = 2
+
+[keys]
+open_in_browser = ["o", "ctrl+o"]
+
+[repos]
+# Add per-repository settings, for example:
+# [repos."acme/api"]
+# enabled = true
+# path = "~/src/acme/api"
+# git_transport = "auto" # auto | https | ssh; remembers the last successful fetch.
+# default_reviewer = "codex"
+# prompt = "~/review-instructions.md"
+# checkout = "mediated"
+
+# Remove the top-level forges = [] before adding forge accounts:
+# [[forges]]
+# kind = "github"
+# base_url = "https://api.github.com"
+# token_env = "GITHUB_TOKEN" # Omit for public access (None); login is then required.
+# include_team_requests = true
+# repositories = [] # Empty means review requests from all accessible repositories.
+# login = "your-login"
+
+# Remove the top-level reviewers = [] before adding reviewers:
+# [[reviewers]]
+# id = "codex"
+# kind = "cli"
+# command = ["codex"]
+# preset = "codex"
+# timeout_s = 900
+# parse = "json_envelope" # The Codex preset uses its fixed JSONL protocol.
+# json_path = "result"
+# stdin = "prompt"
+
+# Claude Code can be configured alongside Codex; select with --reviewer claude
+# or press n in the dashboard, or set review.default_reviewer = "claude" above.
+# [[reviewers]]
+# id = "claude"
+# kind = "cli"
+# command = ["claude"]
+# preset = "claude"

diffbutler/config/diagnostics.py

@@ -0,0 +1,90 @@
+"""Private, bounded application diagnostics without agent or forge content."""
+
+import copy
+import logging
+import os
+import time
+import traceback
+from importlib.metadata import version
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+from types import TracebackType
+
+from diffbutler.config.settings import ConfigError
+from diffbutler.sources.git import SourceError
+
+
+def state_path() -> Path:
+    return (
+        Path(os.environ.get("XDG_STATE_HOME") or Path.home() / ".local/state").expanduser()
+        / "diffbutler"
+    )
+
+
+def log_path() -> Path:
+    return state_path() / "logs" / "diffbutler.log"
+
+
+type ExceptionInfo = (
+    tuple[type[BaseException], BaseException, TracebackType | None] | tuple[None, None, None]
+)
+
+
+class DiagnosticFormatter(logging.Formatter):
+    converter = time.gmtime
+
+    def format(self, record: logging.LogRecord) -> str:
+        record = copy.copy(record)
+        record.exc_text = None
+        return super().format(record)
+
+    def formatException(
+        self,
+        ei: ExceptionInfo,
+    ) -> str:
+        # Exception messages, source lines, and locals can contain remote content or secrets.
+        # These exceptions guarantee safe diagnostics without raw command output.
+        lines = ["Traceback (most recent call last):"]
+        for frame in traceback.extract_tb(ei[2]):
+            lines.append(f"  {Path(frame.filename).name}:{frame.lineno} in {frame.name}")
+        lines.append(type(ei[1]).__name__)
+        if isinstance(ei[1], (ConfigError, SourceError)):
+            lines.append(str(ei[1]))
+        return "\n".join(lines)
+
+
+class DiagnosticHandler(RotatingFileHandler):
+    def handleError(self, record: logging.LogRecord) -> None:
+        # A full disk must not print logging failures into an interactive agent's terminal.
+        pass
+
+
+def stop_logging() -> None:
+    logger = logging.getLogger("diffbutler")
+    if not any(isinstance(handler, logging.NullHandler) for handler in logger.handlers):
+        logger.addHandler(logging.NullHandler())
+    for handler in tuple(logger.handlers):
+        if isinstance(handler, DiagnosticHandler):
+            logger.removeHandler(handler)
+            handler.close()
+
+
+def configure_logging(*, level: int = logging.INFO) -> Path:
+    path = log_path()
+    stop_logging()
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    path.parent.chmod(0o700)
+    fd = os.open(path, os.O_CREAT | os.O_APPEND | os.O_WRONLY, 0o600)
+    os.close(fd)
+    path.chmod(0o600)
+    handler = DiagnosticHandler(path, maxBytes=5 * 1024 * 1024, backupCount=3, encoding="utf-8")
+    handler.setFormatter(
+        DiagnosticFormatter("%(asctime)sZ %(levelname)s pid=%(process)d %(name)s %(message)s")
+    )
+    logger = logging.getLogger("diffbutler")
+    logger.setLevel(level)
+    logger.propagate = False
+    logger.addHandler(handler)
+    if level <= logging.DEBUG:
+        logger.debug("Debug diagnostics enabled version=%s", version("diffbutler"))
+    return path

diffbutler/config/file.py

@@ -0,0 +1,30 @@
+"""Read the user's configuration verbatim, creating defaults only when absent."""
+
+from importlib.resources import files
+from pathlib import Path
+
+from diffbutler.config.settings import ConfigError, config_path
+
+
+def show_config_file(path: Path | None = None) -> tuple[Path, str]:
+    selected = (path or config_path()).expanduser().absolute()
+    try:
+        try:
+            content = selected.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            defaults = (
+                files("diffbutler.config").joinpath("default.toml").read_text(encoding="utf-8")
+            )
+            selected.parent.mkdir(parents=True, exist_ok=True)
+            try:
+                # Exclusive creation preserves files created since the initial read.
+                with selected.open("x", encoding="utf-8") as stream:
+                    stream.write(defaults)
+            except FileExistsError:
+                pass
+            content = selected.read_text(encoding="utf-8")
+    except OSError, UnicodeError:
+        raise ConfigError(
+            f"config: could not read or create configuration file: {selected}"
+        ) from None
+    return selected, content

diffbutler/config/instance.py

@@ -0,0 +1,55 @@
+"""One CLI/TUI process per standard data home, using a kernel-held advisory lock."""
+
+import fcntl
+import os
+import stat
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+
+from diffbutler.config.settings import ConfigError, data_path
+
+
+def instance_lock_path() -> Path:
+    # Outside the reset target: unlinking a held flock file permits a second inode/owner.
+    return data_path().parent / ".diffbutler-instance.lock"
+
+
+@contextmanager
+def single_instance() -> Generator[None]:
+    """Keep a stable inode; a leftover PID is diagnostic only, never ownership proof."""
+    path = instance_lock_path()
+    fd: int | None = None
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        fd = os.open(path, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW | os.O_CLOEXEC, 0o600)
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid() or info.st_nlink != 1:
+            raise ConfigError("Invalid DiffButler instance lock; check its ownership and file type")
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            pid = os.pread(fd, 32, 0).strip()
+            owner = f" (PID {int(pid)})" if pid and pid.isdigit() else ""
+            raise ConfigError(
+                f"DiffButler is already running{owner}; close it before starting another command "
+                "or resetting. Do not delete the instance lock file."
+            ) from None
+        os.fchmod(fd, 0o600)
+        os.ftruncate(fd, 0)
+        os.write(fd, f"{os.getpid()}\n".encode("ascii"))
+    except OSError:
+        if fd is not None:
+            os.close(fd)
+        raise ConfigError(
+            "Could not acquire the DiffButler instance lock; check permissions"
+        ) from None
+    except BaseException:
+        if fd is not None:
+            os.close(fd)
+        raise
+    try:
+        yield
+    finally:
+        # Closing releases the kernel lock. Never unlink, including after a clean exit.
+        os.close(fd)

diffbutler/config/settings.py

@@ -0,0 +1,297 @@
+"""Validated local configuration; loading never starts reviews or contacts a forge."""
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Any, Literal, Self, cast
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    PrivateAttr,
+    ValidationError,
+    field_validator,
+    model_validator,
+)
+from pydantic_settings import BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict
+from pydantic_settings.exceptions import SettingsError
+from pydantic_settings.sources import InitSettingsSource
+
+from diffbutler.domain.forge import PRQuery
+
+NATIVE_PRESETS: tuple[Literal["codex", "claude"], ...] = ("codex", "claude")
+
+
+class ConfigError(ValueError):
+    """A user-facing configuration error with no input values or secrets."""
+
+
+class Section(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class General(Section):
+    workspace_root: Path = Field(default_factory=lambda: data_path() / "reviews")
+    repository_root: Path = Field(default_factory=lambda: data_path() / "repos")
+    repository_retention_days: int = Field(default=30, ge=0)
+    snapshot_root: Path | None = None
+    poll_interval_s: int | None = Field(default=None, gt=0)
+    max_concurrent_reviews: int = Field(default=2, gt=0)
+
+
+def data_path() -> Path:
+    return (
+        Path(os.environ.get("XDG_DATA_HOME", str(Path.home() / ".local/share"))).expanduser()
+        / "diffbutler"
+    )
+
+
+class Database(Section):
+    url: str = Field(default_factory=lambda: f"sqlite+aiosqlite:///{data_path() / 'diffbutler.db'}")
+    auto_migrate: bool = True
+
+
+class Forge(Section):
+    kind: Literal["github", "gitlab"]
+    base_url: str
+    token_env: str | None = Field(default=None, pattern=r"^[A-Za-z_][A-Za-z0-9_]*$")
+    include_team_requests: bool = True
+    login: str | None = None
+    repositories: list[str] = Field(default_factory=list)
+
+    @field_validator("repositories")
+    @classmethod
+    def valid_repositories(cls, values: list[str]) -> list[str]:
+        for value in values:
+            PRQuery(repository=value)
+        return values
+
+
+class Review(Section):
+    default_reviewer: str | None = None
+    findings_threshold: Literal["blocking", "important", "minor", "nit", "question"] = "minor"
+    min_confidence: float = Field(default=0.5, ge=0, le=1)
+    # Accepted for compatibility with existing configuration; no longer enforced.
+    max_diff_bytes: int | None = Field(default=None, exclude=True)
+    exclude_globs: list[str] = Field(
+        default_factory=lambda: ["**/*.lock", "**/vendor/**", "**/*.min.js", "**/generated/**"]
+    )
+    mode: Literal["source_only"] = "source_only"
+    checkout: Literal["worktree", "mediated"] = "worktree"
+    prompt: Path | None = None
+
+
+class Reviewer(Section):
+    id: str = Field(min_length=1)
+    kind: Literal["cli"] = "cli"
+    command: list[str] = Field(min_length=1)
+    preset: Literal["codex", "claude"] | None = None
+    # Accepted for compatibility with existing configuration; no longer enforced.
+    max_output_bytes: int | None = Field(default=None, exclude=True)
+    timeout_s: int = Field(default=900, gt=0)
+    parse: Literal["json_envelope", "jsonl_stream"] = "json_envelope"
+    json_path: str | None = None
+    stdin: Literal["prompt"] | None = None
+
+
+class Attention(Section):
+    blocking: int = 100
+    important: int = 40
+    age_pressure_per_day: int = 5
+    size_penalty_per_100_lines: int = 2
+
+
+class UI(Section):
+    include_own_prs: bool = False
+    include_assigned_prs: bool = False
+    browser_command: list[str] | None = Field(default=None, min_length=1)
+
+    @model_validator(mode="after")
+    def known_columns(self) -> Self:
+        from diffbutler.domain.dashboard import COLUMN_IDS
+
+        if not self.columns or len(set(self.columns)) != len(self.columns):
+            raise ValueError("ui.columns must be nonempty and unique")
+        if any(column not in COLUMN_IDS for column in [*self.columns, self.sort_by]):
+            raise ValueError("Unknown column; valid columns: " + ", ".join(COLUMN_IDS))
+        return self
+
+    columns: list[str] = Field(
+        default_factory=lambda: [
+            "number",
+            "title",
+            "author",
+            "state",
+        ]
+    )
+    sort_by: str = "attention"
+    sort_desc: bool = True
+    preview_pane: bool = True
+    default_filter: Literal[
+        "active", "requested", "following", "all", "triage", "posted", "snoozed", "history"
+    ] = "active"
+    attention: Attention = Field(default_factory=Attention)
+
+
+class Repository(Section):
+    enabled: bool = True
+    path: Path | None = None
+    default_reviewer: str | None = None
+    prompt: Path | None = None
+    checkout: Literal["worktree", "mediated"] | None = None
+    git_transport: Literal["auto", "https", "ssh"] = "auto"
+
+
+class Settings(BaseSettings):
+    _config_file: Path | None = PrivateAttr(default=None)
+    model_config = SettingsConfigDict(
+        env_prefix="DIFFBUTLER_", env_nested_delimiter="__", extra="forbid"
+    )
+    general: General = Field(default_factory=General)
+    db: Database = Field(default_factory=Database)
+    forges: list[Forge] = Field(default_factory=list[Forge])
+    review: Review = Field(default_factory=Review)
+    reviewers: list[Reviewer] = Field(default_factory=list[Reviewer])
+    ui: UI = Field(default_factory=UI)
+    keys: dict[str, list[str]] = Field(default_factory=lambda: {"open_in_browser": ["o", "ctrl+o"]})
+    repos: dict[str, Repository] = Field(default_factory=dict)
+
+    @property
+    def config_file(self) -> Path | None:
+        return self._config_file
+
+    @config_file.setter
+    def config_file(self, path: Path) -> None:
+        self._config_file = path
+
+    @property
+    def effective_poll_interval_s(self) -> int:
+        if self.general.poll_interval_s is not None:
+            return self.general.poll_interval_s
+        # One poll refreshes every account; retain the public cadence in mixed setups.
+        authenticated = self.forges and all(forge.token_env is not None for forge in self.forges)
+        return 60 if authenticated else 600
+
+    @field_validator("keys", mode="before")
+    @classmethod
+    def key_lists(cls, value: object) -> object:
+        if isinstance(value, dict):
+            return {
+                key: [keys] if isinstance(keys, str) else keys
+                for key, keys in cast(dict[str, object], value).items()
+            }
+        return value
+
+    @model_validator(mode="after")
+    def reviewer_references(self) -> Self:
+        ids = [reviewer.id for reviewer in self.reviewers]
+        if len(ids) != len(set(ids)):
+            raise ValueError("reviewers.id must be unique")
+        for name in [
+            self.review.default_reviewer,
+            *(repo.default_reviewer for repo in self.repos.values()),
+        ]:
+            if name is not None and name not in ids:
+                raise ValueError(
+                    "review.default_reviewer / repos.default_reviewer "
+                    "must name a configured reviewers.id"
+                )
+        return self
+
+
+def config_path() -> Path:
+    return (
+        Path(os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config"))).expanduser()
+        / "diffbutler/config.toml"
+    )
+
+
+def load_settings(
+    path: Path | None = None,
+    *,
+    repo: str | None = None,
+    overrides: dict[str, Any] | None = None,
+    missing_ok: bool = False,
+) -> Settings:
+    """CLI > environment > selected repo review options > TOML > defaults.
+
+    Only the implicit default config may be missing unless startup opts in with
+    missing_ok. No dotenv or repository code is loaded. Relative configured paths
+    are relative to the config directory.
+    """
+    selected = (path or config_path()).expanduser().absolute()
+    try:
+        with selected.open("rb") as stream:
+            document = tomllib.load(stream)
+    except FileNotFoundError:
+        if path is not None and not missing_ok:
+            raise ConfigError("config: explicitly selected file does not exist") from None
+        document = {}
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(
+            f"config: invalid TOML at line {exc.lineno}, column {exc.colno}"
+        ) from None
+    except OSError:
+        raise ConfigError("config: cannot read configuration file") from None
+
+    repo_values: dict[str, Any] = {}
+    repositories = document.get("repos", {})
+    if repo is not None and isinstance(repositories, dict):
+        entry = cast(dict[str, Any], repositories).get(repo, {})
+        if isinstance(entry, dict):
+            repo_values = {
+                "review": {
+                    key: value
+                    for key, value in cast(dict[str, Any], entry).items()
+                    if key in {"default_reviewer", "prompt", "checkout"}
+                }
+            }
+
+    class LoadedSettings(Settings):
+        @classmethod
+        def settings_customise_sources(
+            cls,
+            settings_cls: type[BaseSettings],
+            init_settings: PydanticBaseSettingsSource,
+            env_settings: PydanticBaseSettingsSource,
+            dotenv_settings: PydanticBaseSettingsSource,
+            file_secret_settings: PydanticBaseSettingsSource,
+        ) -> tuple[PydanticBaseSettingsSource, ...]:
+            return (
+                init_settings,
+                env_settings,
+                InitSettingsSource(settings_cls, repo_values),
+                InitSettingsSource(settings_cls, document),
+            )
+
+    try:
+        result = LoadedSettings(**(overrides or {}))
+        result.config_file = selected
+    except ValidationError as exc:
+        errors = [
+            f"{'.'.join(map(str, error['loc'])) or 'config'}: {error['msg']}"
+            for error in exc.errors(include_input=False)
+        ]
+        raise ConfigError("; ".join(errors)) from None
+    except SettingsError:
+        raise ConfigError(
+            "environment: invalid DIFFBUTLER_* value; use JSON for lists and objects"
+        ) from None
+
+    def resolve(value: Path) -> Path:
+        value = value.expanduser()
+        return value if value.is_absolute() else selected.parent / value
+
+    result.general.workspace_root = resolve(result.general.workspace_root)
+    result.general.repository_root = resolve(result.general.repository_root)
+    if result.general.snapshot_root is not None:
+        result.general.snapshot_root = resolve(result.general.snapshot_root)
+    if result.review.prompt is not None:
+        result.review.prompt = resolve(result.review.prompt)
+    for repository in result.repos.values():
+        if repository.path is not None:
+            repository.path = resolve(repository.path)
+        if repository.prompt is not None:
+            repository.prompt = resolve(repository.prompt)
+    return result

diffbutler/config/setup.py

@@ -0,0 +1,92 @@
+"""Persist first-run choices while preserving unrelated TOML and comments."""
+
+import os
+import tempfile
+from collections.abc import MutableMapping, Sequence
+from pathlib import Path
+from typing import Any, cast
+
+import tomlkit
+from tomlkit.exceptions import TOMLKitError
+
+from diffbutler.config.settings import NATIVE_PRESETS, ConfigError, Forge, Reviewer, config_path
+
+
+def save_setup(
+    path: Path | None,
+    forge: Forge | None,
+    repository_path: Path | None,
+    reviewers: Sequence[Reviewer] = (),
+    default_reviewer: str | None = None,
+) -> Path:
+    selected = (path or config_path()).expanduser().resolve()
+    try:
+        original = selected.read_text(encoding="utf-8") if selected.exists() else None
+        document = cast(MutableMapping[str, Any], tomlkit.parse(original or ""))
+        if forge is not None:
+            if document.get("forges"):
+                raise ConfigError("Forge configuration changed during setup; restart DiffButler")
+            document["forges"] = [forge.model_dump(exclude_none=True)]
+        if reviewers:
+            entries = document.get("reviewers", [])
+            for reviewer in reviewers:
+                if any(entry["id"] == reviewer.id for entry in entries):
+                    raise ConfigError(
+                        "Reviewer configuration changed during setup; restart DiffButler"
+                    )
+                entries.append(reviewer.model_dump(exclude_none=True))
+            document["reviewers"] = entries
+        if default_reviewer is not None:
+            if "review" not in document:
+                document["review"] = tomlkit.table()
+            document["review"]["default_reviewer"] = default_reviewer
+        if repository_path is not None and forge is not None:
+            repos = document.get("repos")
+            if repos is None:
+                repos = tomlkit.table()
+                document["repos"] = repos
+            if not isinstance(repos, MutableMapping):
+                raise ConfigError("Use a [repos] table to save local repository paths")
+            repos = cast(MutableMapping[str, Any], repos)
+            repository = forge.repositories[0]
+            if repository not in repos:
+                repos[repository] = {"path": str(repository_path)}
+            else:
+                entry = cast(MutableMapping[str, Any], repos[repository])
+                if "path" not in entry:
+                    entry["path"] = str(repository_path)
+        content = tomlkit.dumps(document)
+        if original is None:
+            for preset in NATIVE_PRESETS:
+                if any(entry.get("preset") == preset for entry in document.get("reviewers", [])):
+                    continue
+                example = tomlkit.dumps(
+                    {"reviewers": [{"id": preset, "preset": preset, "command": [preset]}]}
+                )
+                content += (
+                    f"\n# {preset} was not found in PATH; install it and uncomment to enable.\n"
+                    + "\n".join(f"# {line}" for line in example.splitlines())
+                    + "\n"
+                )
+        selected.parent.mkdir(parents=True, exist_ok=True)
+        temporary: Path | None = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode="w", encoding="utf-8", dir=selected.parent, delete=False
+            ) as stream:
+                temporary = Path(stream.name)
+                stream.write(content)
+            if original is not None:
+                if selected.read_text(encoding="utf-8") != original:
+                    raise ConfigError("Configuration changed during setup; restart DiffButler")
+                temporary.chmod(selected.stat().st_mode & 0o777)
+                os.replace(temporary, selected)
+            else:
+                # Atomic publication without overwriting a concurrently created file.
+                os.link(temporary, selected)
+        finally:
+            if temporary is not None:
+                temporary.unlink(missing_ok=True)
+    except OSError, UnicodeError, TOMLKitError:
+        raise ConfigError(f"Could not save startup configuration: {selected}") from None
+    return selected