debugbrief 1.1.0__py3-none-any.whl

debugbrief/paths.py

@@ -0,0 +1,130 @@
+"""Project-root detection and the on-disk storage layout for DebugBrief.
+
+All state lives under ``<project_root>/.debugbrief/``:
+
+    .debugbrief/
+        active_session.json
+        sessions/<session_id>.json
+        reports/<session_id>-<mode>.md
+
+The project root is the enclosing Git repo root when inside a repo, otherwise
+the current working directory.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from . import git_utils
+
+DEBUGBRIEF_DIRNAME = ".debugbrief"
+ACTIVE_SESSION_FILENAME = "active_session.json"
+SESSIONS_DIRNAME = "sessions"
+REPORTS_DIRNAME = "reports"
+
+
+@dataclass
+class ProjectPaths:
+    """Resolved storage locations for a given project root."""
+
+    project_root: Path
+    is_git_repo: bool
+    repo_root: Optional[Path] = None
+
+    @property
+    def base_dir(self) -> Path:
+        return self.project_root / DEBUGBRIEF_DIRNAME
+
+    @property
+    def active_session_file(self) -> Path:
+        return self.base_dir / ACTIVE_SESSION_FILENAME
+
+    @property
+    def sessions_dir(self) -> Path:
+        return self.base_dir / SESSIONS_DIRNAME
+
+    @property
+    def reports_dir(self) -> Path:
+        return self.base_dir / REPORTS_DIRNAME
+
+    def session_file(self, session_id: str) -> Path:
+        return self.sessions_dir / f"{session_id}.json"
+
+    def report_file(self, session_id: str, mode: str) -> Path:
+        return self.reports_dir / f"{session_id}-{mode}.md"
+
+    def report_json_file(self, session_id: str, mode: str) -> Path:
+        return self.reports_dir / f"{session_id}-{mode}.json"
+
+    def ensure_directories(self) -> None:
+        """Create the .debugbrief directory tree if it does not exist."""
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        self.sessions_dir.mkdir(parents=True, exist_ok=True)
+        self.reports_dir.mkdir(parents=True, exist_ok=True)
+
+
+def resolve_project_paths(start: Optional[Path] = None) -> ProjectPaths:
+    """Resolve the project root and storage layout from ``start`` (or cwd).
+
+    If inside a Git repo, the repo root is used as the project root. Otherwise
+    the current working directory is used and we continue safely.
+    """
+    cwd = Path(start).resolve() if start is not None else Path.cwd().resolve()
+    repo_root = git_utils.find_repo_root(cwd)
+    if repo_root is not None:
+        root_path = Path(repo_root).resolve()
+        return ProjectPaths(
+            project_root=root_path, is_git_repo=True, repo_root=root_path
+        )
+    return ProjectPaths(project_root=cwd, is_git_repo=False, repo_root=None)
+
+
+def ensure_local_ignore(paths: ProjectPaths) -> Tuple[bool, List[str]]:
+    """Ensure ``.debugbrief/`` is ignored locally via ``.git/info/exclude``.
+
+    We never touch a shared/tracked ``.gitignore`` by default; ``.git/info/exclude``
+    is local to the clone and not committed. Returns (changed, warnings) where
+    ``changed`` indicates whether we wrote a new entry.
+
+    Safe and non-fatal: when not in a repo, or the exclude file is unavailable,
+    we return a warning instead of raising.
+    """
+    warnings: List[str] = []
+    if not paths.is_git_repo or paths.repo_root is None:
+        return False, warnings
+
+    git_dir = paths.repo_root / ".git"
+    # Handle worktrees / submodules where .git is a file pointing elsewhere.
+    if git_dir.is_file():
+        warnings.append(
+            "Could not update .git/info/exclude (this looks like a git worktree "
+            "or submodule). .debugbrief/ may not be ignored automatically; add it "
+            "to your ignore rules manually if desired."
+        )
+        return False, warnings
+
+    info_dir = git_dir / "info"
+    exclude_file = info_dir / "exclude"
+    entry = f"{DEBUGBRIEF_DIRNAME}/"
+
+    try:
+        if exclude_file.exists():
+            existing = exclude_file.read_text(encoding="utf-8")
+            existing_lines = {line.strip() for line in existing.splitlines()}
+            if entry in existing_lines or DEBUGBRIEF_DIRNAME in existing_lines:
+                return False, warnings
+            prefix = "" if existing.endswith("\n") or existing == "" else "\n"
+            with open(exclude_file, "a", encoding="utf-8") as handle:
+                handle.write(f"{prefix}{entry}\n")
+            return True, warnings
+        info_dir.mkdir(parents=True, exist_ok=True)
+        exclude_file.write_text(f"{entry}\n", encoding="utf-8")
+        return True, warnings
+    except OSError as exc:
+        warnings.append(
+            f"Could not update .git/info/exclude ({exc}). .debugbrief/ may not be "
+            "ignored automatically; add it to your ignore rules manually if desired."
+        )
+        return False, warnings

debugbrief/redaction.py

@@ -0,0 +1,103 @@
+"""Conservative, best-effort secret redaction applied at capture time.
+
+Reports are pasted into pull requests and handoff docs, so captured output and
+command text are scrubbed before anything is written to disk. This is pure
+standard-library regex with no dependency.
+
+Scope is deliberately limited: it masks common, recognizable secret shapes and
+nothing more. It will miss secrets that do not match a known pattern, so it is
+never presented as a guarantee. When a value is masked it is replaced with the
+literal placeholder ``[redacted]``.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Callable, List, Tuple, Union
+
+PLACEHOLDER = "[redacted]"
+
+# Tokens that mark a key as sensitive in a key/value pair. These must appear as a
+# whole segment of the key name (delimited by the start/end of the key or by a
+# ``_``/``-``/``.`` separator) so embedded substrings like the "key" in "monkey"
+# or the "api" in "rapid_mode" are not mistaken for secrets.
+_SENSITIVE_KEY = (
+    r"(?:password|passwd|pwd|secret|token|api[_\-]?key|apikey|credential|api|key)"
+)
+
+# A key name is sensitive when one of its segments is a sensitive token. The
+# token must be flanked by a non-alphanumeric boundary on both sides (start/end
+# of the key or a separator), while still allowing other segments around it.
+# The match starts at the token itself; any prefix segments are simply left in
+# place by the replacement. Anchoring at the token instead of lazily scanning
+# the whole key keeps the pass linear on long unbroken text, where the lazy
+# prefix walk was quadratic.
+_SENSITIVE_KEY_NAME = (
+    r"(?P<key>(?<![A-Za-z0-9])"
+    + _SENSITIVE_KEY
+    + r"(?![A-Za-z0-9])[A-Za-z0-9_.\-]*\s*[:=]\s*)"
+)
+
+# A redaction replacement is either a literal string or a match-to-string
+# callback, matching the two forms accepted by ``re.Pattern.subn``.
+_Replacement = Union[str, Callable[["re.Match[str]"], str]]
+
+
+def _kv_repl(match: "re.Match[str]") -> str:
+    # Preserve the key, separator and any surrounding quotes; mask the value.
+    open_quote = match.group("q") or ""
+    return f"{match.group('key')}{open_quote}{PLACEHOLDER}{open_quote}"
+
+
+# Order matters: multi-line and structured shapes first, broad key/value last.
+_RULES: List[Tuple["re.Pattern[str]", _Replacement]] = [
+    # PEM-style private key blocks (any key type), including the body.
+    (
+        re.compile(
+            r"-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----.*?-----END [A-Z0-9 ]*PRIVATE KEY-----",
+            re.DOTALL,
+        ),
+        PLACEHOLDER,
+    ),
+    # Connection strings: scheme://user:password@host -> mask only the password.
+    (
+        re.compile(r"\b([a-zA-Z][a-zA-Z0-9+.\-]*://[^\s:/@]+):[^\s:/@]+@"),
+        r"\1:" + PLACEHOLDER + "@",
+    ),
+    # Authorization headers (value may be a Bearer/Basic token).
+    (
+        re.compile(r"(?i)(authorization\s*[:=]\s*)(?:bearer\s+|basic\s+)?\S+"),
+        r"\1" + PLACEHOLDER,
+    ),
+    # Standalone bearer tokens.
+    (
+        re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._\-]+"),
+        "Bearer " + PLACEHOLDER,
+    ),
+    # Provider key shapes.
+    (re.compile(r"\bsk-[A-Za-z0-9_\-]{16,}\b"), PLACEHOLDER),  # OpenAI-style
+    (re.compile(r"\bAKIA[0-9A-Z]{16}\b"), PLACEHOLDER),  # AWS access key id
+    (re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}\b"), PLACEHOLDER),  # GitHub tokens
+    # Generic key/value pairs whose key name looks sensitive.
+    (
+        re.compile(
+            r"(?i)" + _SENSITIVE_KEY_NAME + r"(?P<q>[\"'])?(?P<val>[^\s\"',;]+)(?P=q)?"
+        ),
+        _kv_repl,
+    ),
+]
+
+
+def redact_text(text: str) -> Tuple[str, int]:
+    """Return ``(redacted_text, count)`` where ``count`` is the number of masks.
+
+    Best effort: applies each rule in turn. A ``count`` greater than zero means
+    at least one secret-shaped value was replaced.
+    """
+    if not text:
+        return text, 0
+    total = 0
+    for pattern, repl in _RULES:
+        text, n = pattern.subn(repl, text)
+        total += n
+    return text, total

debugbrief/reporters/__init__.py

@@ -0,0 +1,108 @@
+"""Report rendering: dispatch a finalized session to a mode-specific reporter."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Type
+
+from ..models import Session
+from .base import BaseReporter, build_context
+
+VALID_MODES = ("pr", "handoff", "incident")
+
+
+def _reporters() -> Dict[str, Type[BaseReporter]]:
+    # Imported lazily so the mode modules can import from .base without a cycle.
+    from .handoff import HandoffReporter
+    from .incident import IncidentReporter
+    from .pr import PRReporter
+
+    return {"pr": PRReporter, "handoff": HandoffReporter, "incident": IncidentReporter}
+
+
+def _check_mode(mode: str) -> None:
+    if mode not in VALID_MODES:
+        raise ValueError(
+            f"Unknown report mode {mode!r}. Valid modes: {', '.join(VALID_MODES)}."
+        )
+
+
+def render_report(session: Session, mode: str) -> str:
+    """Render a markdown report for ``session`` in the requested ``mode``."""
+    _check_mode(mode)
+    context = build_context(session)
+    reporter = _reporters()[mode](context)
+    return reporter.render()
+
+
+def render_report_json(session: Session, mode: str) -> Dict[str, Any]:
+    """Render the same derived content as a structured JSON-ready dict.
+
+    The keys mirror the markdown report's derived sections so the two formats
+    stay in sync. Like the markdown, fields with no evidence are null/empty.
+    """
+    _check_mode(mode)
+    context = build_context(session)
+    d = context.derivation
+    s = session
+
+    rtg = None
+    if d.red_to_green is not None:
+        rtg = {
+            "command": d.red_to_green.command,
+            "failed_at": d.red_to_green.failed_at,
+            "passed_at": d.red_to_green.passed_at,
+            "window_seconds": d.red_to_green.window_seconds,
+            "changed_files": list(d.red_to_green.changed_files),
+        }
+
+    return {
+        "mode": mode,
+        "session_id": s.session_id,
+        "title": s.title,
+        "status": s.status,
+        "project_root": s.project_root,
+        "started_at": s.timestamps.start,
+        "ended_at": s.timestamps.end,
+        "git": {
+            "is_repo": s.git.is_repo,
+            "branch": s.git.branch,
+            "detached_head": s.git.detached_head,
+            "initial_sha": s.git.initial_sha,
+            "final_sha": s.git.final_sha,
+        },
+        "counts": {
+            "notes": s.summary.notes_count,
+            "commands": s.summary.commands_count,
+            "failed_commands": s.summary.failed_commands_count,
+        },
+        "one_liner": d.one_liner,
+        "reproduce_command": d.reproduce_command,
+        "verify_command": d.verify_command,
+        "red_to_green": rtg,
+        "observed_error": d.observed_error,
+        "ruled_out": [
+            {
+                "command": r.command,
+                "status": r.status,
+                "exit_code": r.exit_code,
+                "timestamp": r.timestamp,
+            }
+            for r in d.ruled_out
+        ],
+        "timeline": [
+            {"timestamp": e.timestamp, "kind": e.kind, "text": e.text}
+            for e in context.timeline
+        ],
+        "changed_files": [
+            {"status": fc.status, "path": fc.path} for fc in s.summary.file_changes
+        ],
+        "verification": [
+            {"command": rc.command, "tool": rc.tool, "is_test": rc.is_test}
+            for rc in context.verification_commands
+        ],
+        "notes": [text for _ts, text in context.notes],
+        "redaction_applied": d.redaction_applied,
+    }
+
+
+__all__ = ["render_report", "render_report_json", "VALID_MODES", "build_context"]