debugbrief 1.1.0__py3-none-any.whl

debugbrief/session_manager.py

@@ -0,0 +1,361 @@
+"""Session lifecycle and persistence.
+
+The canonical live record for an active session is its file under
+``.debugbrief/sessions/<id>.json``; it is rewritten immediately after every
+event so a crash never loses captured work. ``active_session.json`` is a small
+pointer to the currently-active session and is removed on a clean ``end``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from . import git_utils
+from .command_runner import RunResult
+from .models import (
+    COMMAND_STATUS_ERROR,
+    COMMAND_STATUS_FAILED,
+    COMMAND_STATUS_TIMED_OUT,
+    CommandData,
+    Event,
+    FileChange,
+    Session,
+    SessionStatus,
+)
+from .paths import ProjectPaths
+from .redaction import redact_text
+from .utils import atomic_write_json, now_iso8601, read_json
+
+
+class SessionError(Exception):
+    """Raised for expected, user-facing session errors."""
+
+
+class SessionManager:
+    def __init__(self, paths: ProjectPaths) -> None:
+        self.paths = paths
+
+    # Active-pointer handling -------------------------------------------------
+    def _read_active_pointer(self) -> Optional[Dict[str, Any]]:
+        pointer_path = self.paths.active_session_file
+        if not pointer_path.exists():
+            return None
+        try:
+            data = read_json(pointer_path)
+        except (ValueError, OSError) as exc:
+            raise SessionError(
+                f"active_session.json exists but could not be read ({exc}). "
+                "Inspect or remove .debugbrief/active_session.json to recover."
+            ) from exc
+        if not isinstance(data, dict) or "session_id" not in data:
+            raise SessionError(
+                "active_session.json is malformed. Remove "
+                ".debugbrief/active_session.json to recover."
+            )
+        return data
+
+    def _write_active_pointer(self, session: Session) -> None:
+        atomic_write_json(
+            self.paths.active_session_file,
+            {
+                "session_id": session.session_id,
+                "title": session.title,
+                "status": session.status,
+                "started_at": session.timestamps.start,
+                "session_file": str(
+                    self.paths.session_file(session.session_id)
+                ),
+            },
+        )
+
+    def _clear_active_pointer(self) -> None:
+        pointer_path = self.paths.active_session_file
+        try:
+            if pointer_path.exists():
+                pointer_path.unlink()
+        except OSError as exc:  # pragma: no cover - defensive
+            raise SessionError(
+                f"Could not clear active_session.json ({exc}). Remove it manually."
+            ) from exc
+
+    def has_active(self) -> bool:
+        return self.paths.active_session_file.exists()
+
+    # Session persistence -----------------------------------------------------
+    def save_session(self, session: Session) -> None:
+        self._recompute_counts(session)
+        atomic_write_json(
+            self.paths.session_file(session.session_id), session.to_dict()
+        )
+
+    def load_session_file(self, session_id: str) -> Session:
+        path = self.paths.session_file(session_id)
+        if not path.exists():
+            raise SessionError(f"Session file not found for id {session_id}.")
+        try:
+            return Session.from_dict(read_json(path))
+        except (ValueError, OSError) as exc:
+            raise SessionError(f"Could not read session {session_id}: {exc}") from exc
+
+    def load_active(self) -> Optional[Session]:
+        """Return the active Session, or None if no session is active.
+
+        Raises SessionError if the pointer exists but the underlying session
+        file is missing/unreadable (an interrupted/inconsistent state).
+        """
+        pointer = self._read_active_pointer()
+        if pointer is None:
+            return None
+        session_id = pointer["session_id"]
+        path = self.paths.session_file(session_id)
+        if not path.exists():
+            raise SessionError(
+                "active_session.json points to a missing session file "
+                f"({session_id}). The session looks interrupted. Remove "
+                ".debugbrief/active_session.json to recover."
+            )
+        return self.load_session_file(session_id)
+
+    def require_active(self, action: str) -> Session:
+        session = self.load_active()
+        if session is None:
+            raise SessionError(
+                f"No active DebugBrief session. Cannot {action}. "
+                'Start one with: debugbrief start "<title>"'
+            )
+        return session
+
+    # Lifecycle ---------------------------------------------------------------
+    def start(self, title: str) -> Session:
+        if self.has_active():
+            existing = self._read_active_pointer() or {}
+            raise SessionError(
+                "A DebugBrief session is already active"
+                + (f" ({existing.get('title')!r})." if existing.get("title") else ".")
+                + " End it with: debugbrief end --mode pr|handoff|incident, "
+                "or check it with: debugbrief status"
+            )
+
+        clean_title = title.strip()
+        if not clean_title:
+            raise SessionError("Session title must not be empty.")
+
+        self.paths.ensure_directories()
+        git_state = git_utils.capture_state(self.paths.project_root, initial=True)
+
+        session = Session(
+            title=clean_title,
+            project_root=str(self.paths.project_root),
+            git=git_state,
+        )
+        session.timestamps.start = now_iso8601()
+
+        # Record an initial snapshot event for an honest timeline.
+        session.events.append(
+            Event.snapshot(
+                {
+                    "phase": "start",
+                    "git": git_state.to_dict(),
+                },
+                session.timestamps.start,
+            )
+        )
+
+        self.save_session(session)
+        self._write_active_pointer(session)
+        return session
+
+    def auto_start(self, seed_text: str) -> Session:
+        """Start a session with a title derived from the time and ``seed_text``.
+
+        Used when ``run`` or ``note`` is invoked with no active session, so a
+        capture is never silently dropped.
+        """
+        from .utils import utc_now
+
+        first_line = ""
+        for line in (seed_text or "").strip().splitlines():
+            if line.strip():
+                first_line = line.strip()
+                break
+        snippet = first_line[:60] if first_line else "debug session"
+        stamp = utc_now().strftime("%Y-%m-%d %H:%M")
+        return self.start(f"Auto session {stamp}: {snippet}")
+
+    def add_note(self, text: str) -> Session:
+        session = self.require_active("add a note")
+        clean = text.strip()
+        if not clean:
+            raise SessionError("Note text must not be empty.")
+        # Notes are persisted to the session JSON and surfaced in reports, so a
+        # secret pasted into a note (an env var, a log line) must be scrubbed
+        # before it ever reaches disk, the same as captured command output.
+        clean, n_redacted = redact_text(clean)
+        note_event = Event.note(clean, now_iso8601())
+        if n_redacted:
+            note_event.data["redacted"] = True
+        session.events.append(note_event)
+        self.save_session(session)
+        self._write_active_pointer(session)
+        return session
+
+    def record_command(self, result: RunResult) -> Session:
+        session = self.require_active("run a command")
+        # Best-effort, lightweight git snapshot at the moment of the command so
+        # later reports can correlate file changes with what happened. Safe and
+        # silent outside a repo.
+        if session.git.is_repo:
+            cwd = self.paths.project_root
+            result.command_data.git_head = git_utils.current_short_sha(cwd)
+            result.command_data.git_changed_files = git_utils.changed_files(cwd)
+        session.events.append(
+            Event.command(result.command_data, result.command_data.started_at)
+        )
+        if result.error_message and (result.errored or result.timed_out):
+            session.add_warning(result.error_message, now_iso8601())
+        self.save_session(session)
+        self._write_active_pointer(session)
+        return session
+
+    def end(self, mode: str, report_format: str = "md") -> Session:
+        # Local imports avoid an import cycle with the reporters package.
+        from .reporters import render_report, render_report_json
+
+        session = self.require_active("end the session")
+
+        # Capture final Git state, preserving the initial SHA.
+        final_state = git_utils.capture_state(self.paths.project_root, initial=False)
+        session.git.final_sha = final_state.final_sha
+        session.git.branch = final_state.branch
+        session.git.detached_head = final_state.detached_head
+        session.git.is_repo = final_state.is_repo
+        if final_state.repo_root:
+            session.git.repo_root = final_state.repo_root
+
+        session.timestamps.end = now_iso8601()
+        session.status = SessionStatus.COMPLETED.value
+
+        session.events.append(
+            Event.snapshot(
+                {"phase": "end", "git": session.git.to_dict()},
+                session.timestamps.end,
+            )
+        )
+
+        self._finalize_summary(session)
+        self.save_session(session)
+
+        from .utils import write_text
+
+        if report_format in ("md", "both"):
+            report_text = render_report(session, mode)
+            write_text(self.paths.report_file(session.session_id, mode), report_text)
+        if report_format in ("json", "both"):
+            import json
+
+            payload = render_report_json(session, mode)
+            write_text(
+                self.paths.report_json_file(session.session_id, mode),
+                json.dumps(payload, indent=2) + "\n",
+            )
+
+        # Only clear the active pointer after the report is safely written.
+        self._clear_active_pointer()
+        return session
+
+    def cancel(self) -> Session:
+        """Discard the active session without writing a report.
+
+        The session file is kept on disk with status ABANDONED, so nothing is
+        silently deleted; it simply never becomes a brief.
+        """
+        session = self.require_active("cancel the session")
+        session.status = SessionStatus.ABANDONED.value
+        session.timestamps.end = now_iso8601()
+        self.save_session(session)
+        self._clear_active_pointer()
+        return session
+
+    # Status ------------------------------------------------------------------
+    def build_status(self) -> Dict[str, Any]:
+        """Return a structured status payload for the CLI to render."""
+        pointer = self._read_active_pointer()
+        if pointer is None:
+            return {"active": False}
+
+        session_id = pointer.get("session_id", "")
+        path = self.paths.session_file(session_id)
+        if not path.exists():
+            return {
+                "active": True,
+                "interrupted": True,
+                "session_id": session_id,
+                "title": pointer.get("title"),
+                "reason": "Session file is missing.",
+            }
+
+        session = self.load_session_file(session_id)
+        self._recompute_counts(session)
+        interrupted = session.status != SessionStatus.ACTIVE.value
+        return {
+            "active": True,
+            "interrupted": interrupted,
+            "session_id": session.session_id,
+            "title": session.title,
+            "status": session.status,
+            "project_root": session.project_root,
+            "start": session.timestamps.start,
+            "notes_count": session.summary.notes_count,
+            "commands_count": session.summary.commands_count,
+            "failed_commands_count": session.summary.failed_commands_count,
+            "branch": session.git.branch,
+            "detached_head": session.git.detached_head,
+            "is_repo": session.git.is_repo,
+            "warnings": list(session.warnings),
+        }
+
+    # Internal helpers --------------------------------------------------------
+    def _recompute_counts(self, session: Session) -> None:
+        commands = session.command_events()
+        notes = session.note_events()
+        failed = 0
+        for event in commands:
+            status = (event.data.get("classification") or {}).get("status")
+            if status in (
+                COMMAND_STATUS_FAILED,
+                COMMAND_STATUS_TIMED_OUT,
+                COMMAND_STATUS_ERROR,
+            ):
+                failed += 1
+        session.summary.notes_count = len(notes)
+        session.summary.commands_count = len(commands)
+        session.summary.failed_commands_count = failed
+
+    def _finalize_summary(self, session: Session) -> None:
+        self._recompute_counts(session)
+
+        tests_run: List[str] = []
+        for event in session.command_events():
+            data = CommandData.from_dict(event.data)
+            if data.classification.is_test:
+                tests_run.append(data.command)
+        session.summary.tests_run = tests_run
+
+        if session.git.is_repo:
+            pairs = git_utils.name_status(self.paths.project_root)
+            session.summary.file_changes = [
+                FileChange(status=label, path=path) for label, path in pairs
+            ]
+            session.summary.modified_files = [path for _label, path in pairs]
+            added, deleted = git_utils.shortstat(self.paths.project_root)
+            session.summary.lines_added = added
+            session.summary.lines_deleted = deleted
+        else:
+            session.summary.file_changes = []
+            session.summary.modified_files = []
+            session.summary.lines_added = 0
+            session.summary.lines_deleted = 0
+
+        # The explicit-run capture model captures exactly what was run through
+        # DebugBrief; there is no silent gap to report.
+        session.summary.command_capture_status = "full"

debugbrief/sessions_index.py

@@ -0,0 +1,78 @@
+"""Read-only helpers for enumerating and resolving stored sessions.
+
+Used by the ``list`` and ``show`` commands. None of these require an active
+session, and they never mutate state.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional, Tuple
+
+from .models import Session
+from .paths import ProjectPaths
+from .reporters import VALID_MODES, build_context
+from .utils import parse_iso8601, read_json
+
+
+def _start_seconds(session: Session) -> float:
+    start = session.timestamps.start
+    if not start:
+        return 0.0
+    try:
+        return parse_iso8601(start).timestamp()
+    except (ValueError, TypeError):
+        return 0.0
+
+
+def load_all_sessions(paths: ProjectPaths) -> List[Session]:
+    """Load every stored session, most recent first (by start time).
+
+    Unreadable session files are skipped silently so a single corrupt file
+    cannot break listing.
+    """
+    sessions_dir = paths.sessions_dir
+    if not sessions_dir.is_dir():
+        return []
+    sessions: List[Session] = []
+    for path in sessions_dir.glob("*.json"):
+        if not path.is_file():
+            continue
+        try:
+            sessions.append(Session.from_dict(read_json(path)))
+        except (ValueError, OSError, TypeError):
+            continue
+    sessions.sort(key=lambda s: (_start_seconds(s), s.session_id), reverse=True)
+    return sessions
+
+
+def report_modes_for(paths: ProjectPaths, session_id: str) -> List[str]:
+    """Return the report modes that have been generated for ``session_id``."""
+    modes = []
+    for mode in VALID_MODES:
+        if paths.report_file(session_id, mode).exists():
+            modes.append(mode)
+    return modes
+
+
+def is_verified(session: Session) -> bool:
+    """True if at least one verification command passed during the session."""
+    return len(build_context(session).verification_commands) > 0
+
+
+def resolve_session_id(
+    paths: ProjectPaths, prefix: str
+) -> Tuple[Optional[str], List[str]]:
+    """Resolve a (possibly short) session id prefix to a full id.
+
+    Returns (resolved_id, matches). ``resolved_id`` is set only when exactly one
+    session id matches; otherwise it is None and ``matches`` lists all candidate
+    ids (empty when there is no match, multiple when the prefix is ambiguous).
+    """
+    clean = prefix.strip()
+    ids = [s.session_id for s in load_all_sessions(paths)]
+    if clean in ids:
+        return clean, [clean]
+    matches = [sid for sid in ids if sid.startswith(clean)]
+    if len(matches) == 1:
+        return matches[0], matches
+    return None, matches

debugbrief/utils.py

@@ -0,0 +1,151 @@
+"""Small shared helpers: timestamps, output truncation, and atomic JSON I/O.
+
+These helpers are deliberately dependency-free and side-effect minimal so the
+rest of the package can rely on consistent, testable behavior.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Tuple
+
+# Default preview limits for captured command output. We store previews, not
+# unbounded logs, so a single noisy command can never balloon a session file.
+DEFAULT_STDOUT_PREVIEW_LIMIT = 4000
+DEFAULT_STDERR_PREVIEW_LIMIT = 4000
+
+
+def utc_now() -> datetime:
+    """Return the current time as a timezone-aware UTC datetime."""
+    return datetime.now(timezone.utc)
+
+
+def to_iso8601(moment: datetime) -> str:
+    """Serialize a datetime to an ISO8601 UTC string ending in 'Z'.
+
+    Naive datetimes are assumed to already be UTC.
+    """
+    if moment.tzinfo is None:
+        moment = moment.replace(tzinfo=timezone.utc)
+    moment = moment.astimezone(timezone.utc)
+    # Use millisecond precision; drop the '+00:00' offset in favor of 'Z'.
+    return moment.isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def now_iso8601() -> str:
+    """Convenience: current UTC time as an ISO8601 string."""
+    return to_iso8601(utc_now())
+
+
+def parse_iso8601(value: str) -> datetime:
+    """Parse an ISO8601 string (possibly ending in 'Z') into a UTC datetime."""
+    normalized = value.strip()
+    if normalized.endswith("Z"):
+        normalized = normalized[:-1] + "+00:00"
+    parsed = datetime.fromisoformat(normalized)
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def human_duration(seconds: float) -> str:
+    """Render a duration in seconds as a compact ``1h 2m 3s`` style string."""
+    total = int(round(seconds))
+    if total < 0:
+        total = 0
+    hours, remainder = divmod(total, 3600)
+    minutes, secs = divmod(remainder, 60)
+    if hours:
+        return f"{hours}h {minutes}m {secs}s"
+    if minutes:
+        return f"{minutes}m {secs}s"
+    return f"{secs}s"
+
+
+def truncate_text(text: str, limit: int) -> Tuple[str, bool]:
+    """Truncate ``text`` to ``limit`` characters, keeping the head and tail.
+
+    Returns a tuple of (possibly truncated text, was_truncated). A ``limit`` of
+    zero or negative is treated as "no limit".
+
+    When the text is longer than ``limit`` we keep a small head and a larger
+    tail with an elision marker in between. The decisive output of a debugging
+    run (tracebacks, assertions, the final build error) lands at the end, so the
+    tail gets the larger share: the head is the first ``limit // 3`` characters
+    and the tail is the remaining budget. The kept original content totals
+    ``limit`` characters; the marker is added on top.
+    """
+    if text is None:
+        return "", False
+    if limit is None or limit <= 0:
+        return text, False
+    if len(text) <= limit:
+        return text, False
+    head_len = limit // 3
+    tail_len = limit - head_len
+    omitted = len(text) - limit
+    marker = f"\n... [{omitted} characters omitted] ...\n"
+    head = text[:head_len]
+    tail = text[len(text) - tail_len:]
+    return head + marker + tail, True
+
+
+def atomic_write_json(path: Path, data: Any) -> None:
+    """Write ``data`` as JSON to ``path`` atomically.
+
+    The data is written to a temporary file in the same directory and then
+    renamed into place, so a crash mid-write cannot corrupt an existing file.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=f".{path.name}.", suffix=".tmp", dir=str(path.parent)
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(data, handle, indent=2, ensure_ascii=False, sort_keys=False)
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp_name, str(path))
+    except BaseException:
+        # Best-effort cleanup of the temp file on any failure.
+        try:
+            if os.path.exists(tmp_name):
+                os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+
+
+def read_json(path: Path) -> Any:
+    """Read and parse JSON from ``path``."""
+    with open(path, encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def write_text(path: Path, text: str) -> None:
+    """Write ``text`` to ``path``, creating parent directories as needed."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as handle:
+        handle.write(text)
+
+
+def is_supported_platform() -> bool:
+    """Return True on Unix-like platforms (Linux, macOS, BSD).
+
+    V1 explicitly does not support Windows / PowerShell.
+    """
+    return os.name == "posix"
+
+
+def eprint(*args: Any, **kwargs: Any) -> None:
+    """Print to stderr."""
+    kwargs.setdefault("file", sys.stderr)
+    print(*args, **kwargs)