gdmcode 0.1.0__py3-none-any.whl

src/git_workflow.py

@@ -0,0 +1,651 @@
+"""Git workflow — safe branch management, checkpoints, and rollback.
+
+Every agentic task gets its own branch. Every significant change gets a
+checkpoint commit. The user can roll back to any checkpoint or the pre-task
+state with a single command.
+
+Safety invariants:
+  - NEVER force-push to main/master/develop
+  - NEVER rewrite history (no amend, no rebase on remote branches)
+  - Checkpoint commits are marked [gdm-checkpoint] for easy filtering
+  - All rollbacks require explicit user confirmation (except --force flag)
+"""
+from __future__ import annotations
+
+import logging
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from src.exceptions import GitError
+
+if TYPE_CHECKING:
+    from src.agent.commit_classifier import ConventionalCommitClassifier
+
+__all__ = [
+    "GitWorkflow",
+    "Checkpoint",
+    "WorktreeInfo",
+    "ConflictResult",
+    "ConflictResolver",
+    "cleanup_merged_branches",
+]
+
+log = logging.getLogger(__name__)
+
+_PROTECTED_BRANCHES: frozenset[str] = frozenset({"main", "master", "develop", "production"})
+_CHECKPOINT_PREFIX = "[gdm-checkpoint]"
+
+
+def _run(args: list[str], cwd: Path, check: bool = True) -> subprocess.CompletedProcess:  # type: ignore[type-arg]
+    """Run a git command, returning CompletedProcess.
+
+    Raises:
+        GitError: if the command fails and check=True.
+    """
+    try:
+        result = subprocess.run(
+            ["git"] + args,
+            cwd=str(cwd),
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise GitError(command=" ".join(args), message="git not found in PATH") from exc
+
+    if check and result.returncode != 0:
+        raise GitError(
+            command=" ".join(args),
+            message=result.stderr.strip() or result.stdout.strip(),
+        )
+    return result
+
+
+@dataclass
+class WorktreeInfo:
+    """Metadata for a single git worktree."""
+    branch: str
+    path: Path
+    db_path: Path   # each worktree gets its own .context-memory/gdm.db copy
+
+
+@dataclass
+class Checkpoint:
+    """A recorded git commit checkpoint."""
+
+    sha: str
+    message: str
+    branch: str
+
+
+class GitWorkflow:
+    """Manages git workflow for a single agentic task.
+
+    Usage::
+
+        wf = GitWorkflow(project_root=Path.cwd())
+        branch = wf.create_task_branch("fix-auth-bug")
+        wf.checkpoint("after fixing JWT validation")
+        wf.checkpoint("after updating tests")
+        wf.rollback_to(branch.sha)  # user confirmed rollback
+    """
+
+    def __init__(
+        self,
+        project_root: Path,
+        *,
+        classifier: "ConventionalCommitClassifier | None" = None,
+    ) -> None:
+        self._root = project_root
+        self._task_branch: str | None = None
+        self._pre_task_sha: str | None = None
+        self._classifier = classifier
+
+    # ------------------------------------------------------------------
+    # Branch management
+    # ------------------------------------------------------------------
+
+    def current_branch(self) -> str:
+        result = _run(["branch", "--show-current"], cwd=self._root)
+        return result.stdout.strip()
+
+    def current_sha(self) -> str:
+        result = _run(["rev-parse", "HEAD"], cwd=self._root)
+        return result.stdout.strip()
+
+    def create_task_branch(self, task_slug: str) -> str:
+        """Create and checkout a new task branch. Returns branch name.
+
+        Args:
+            task_slug: short description (will be sanitized into a branch name)
+
+        Raises:
+            GitError: if we're already on a protected branch and can't branch from it,
+                      or if the repo has no commits.
+        """
+        base = self.current_branch()
+        self._pre_task_sha = self.current_sha()
+
+        # Sanitize task_slug into a valid branch name
+        safe = "".join(
+            c if c.isalnum() or c in "-_" else "-" for c in task_slug.lower()
+        ).strip("-")[:50]
+        branch_name = f"gdm/{safe}"
+
+        _run(["checkout", "-b", branch_name], cwd=self._root)
+        self._task_branch = branch_name
+        log.info("Created task branch '%s' from '%s' @ %s", branch_name, base, self._pre_task_sha)
+        return branch_name
+
+    # ------------------------------------------------------------------
+    # Checkpointing
+    # ------------------------------------------------------------------
+
+    def checkpoint(
+        self,
+        message: str,
+        *,
+        turn_id: str = "",
+        files: "list[Path] | None" = None,
+    ) -> Checkpoint:
+        """Stage all changes and create a checkpoint commit.
+
+        Args:
+            message:  Human-readable description of what changed
+            turn_id:  Session turn ID for per-turn rollback
+            files:    Files changed in this turn (for rollback journal)
+
+        Returns:
+            Checkpoint with the commit SHA
+        """
+        if not self._task_branch:
+            log.warning("checkpoint() called outside a task branch — proceeding anyway")
+
+        _run(["add", "-A"], cwd=self._root)
+        commit_msg = f"{_CHECKPOINT_PREFIX} {message}"
+        if self._classifier is not None:
+            try:
+                cached_diff = _run(["diff", "--cached"], cwd=self._root, check=False)
+                classified = self._classifier.classify(cached_diff.stdout)
+                commit_msg = f"{_CHECKPOINT_PREFIX} {classified}"
+            except Exception:  # noqa: BLE001
+                pass  # fall back to raw message already set above
+        if turn_id or files:
+            files_csv = ",".join(f.name for f in (files or []))
+            commit_msg += f"\n\n[gdm] turn:{turn_id} files:{files_csv}"
+        result = _run(["commit", "--allow-empty", "-m", commit_msg], cwd=self._root)
+        sha = self.current_sha()
+        branch = self._task_branch or self.current_branch()
+        log.info("Checkpoint: %s (%s)", sha[:8], message)
+        return Checkpoint(sha=sha, message=commit_msg, branch=branch)
+
+    def list_checkpoints(self) -> list[Checkpoint]:
+        """Return all checkpoint commits on the current branch."""
+        result = _run(
+            ["log", "--oneline", f"--grep={_CHECKPOINT_PREFIX}"],
+            cwd=self._root,
+            check=False,
+        )
+        checkpoints: list[Checkpoint] = []
+        branch = self.current_branch()
+        for line in result.stdout.splitlines():
+            parts = line.split(maxsplit=1)
+            if len(parts) == 2:
+                checkpoints.append(Checkpoint(sha=parts[0], message=parts[1], branch=branch))
+        return checkpoints
+
+    # ------------------------------------------------------------------
+    # Rollback
+    # ------------------------------------------------------------------
+
+    def rollback_to_checkpoint(self, sha: str) -> None:
+        """Soft rollback — reset HEAD to *sha*, keep working tree.
+
+        This preserves changes as unstaged diffs — user can review before
+        discarding. For hard rollback use rollback_hard().
+        """
+        _run(["reset", sha], cwd=self._root)
+        log.info("Soft rollback to %s (working tree preserved)", sha[:8])
+
+    def rollback_hard(self, sha: str) -> None:
+        """Hard rollback — git reset --hard *sha*.
+
+        DESTRUCTIVE. Discards all changes since *sha*.
+        Caller MUST confirm with user before calling this.
+        """
+        _run(["reset", "--hard", sha], cwd=self._root)
+        log.warning("Hard rollback to %s — all subsequent changes discarded", sha[:8])
+
+    def rollback_to_pre_task(self, hard: bool = False) -> None:
+        """Roll back to the state before create_task_branch().
+
+        Raises:
+            GitError: if pre-task SHA is unknown (task branch was never created).
+        """
+        if not self._pre_task_sha:
+            raise GitError(
+                command="rollback_to_pre_task",
+                message="No pre-task SHA recorded — was create_task_branch() called?",
+            )
+        if hard:
+            self.rollback_hard(self._pre_task_sha)
+        else:
+            self.rollback_to_checkpoint(self._pre_task_sha)
+
+    # ------------------------------------------------------------------
+    # Utility
+    # ------------------------------------------------------------------
+
+    def is_clean(self) -> bool:
+        """Return True if the working tree has no uncommitted changes."""
+        result = _run(["status", "--porcelain"], cwd=self._root)
+        return result.stdout.strip() == ""
+
+    def is_git_repo(self) -> bool:
+        """Return True if *self._root* is inside a git repository."""
+        result = _run(["rev-parse", "--is-inside-work-tree"], cwd=self._root, check=False)
+        return result.returncode == 0
+
+    def is_protected(self, branch: str | None = None) -> bool:
+        """Return True if *branch* (or current branch) is a protected branch."""
+        target = branch or self.current_branch()
+        return target in _PROTECTED_BRANCHES
+
+    # ------------------------------------------------------------------
+    # Worktree management (used by BranchFarm)
+    # ------------------------------------------------------------------
+
+    def create_worktree(self, branch: str, path: Path) -> WorktreeInfo:
+        """Create a new worktree on a fresh branch at *path*.
+
+        Copies the current DB snapshot into the worktree so history is
+        inherited but all DB writes stay isolated to that branch.
+        """
+        path.mkdir(parents=True, exist_ok=True)
+        _run(["worktree", "add", "-b", branch, str(path)], cwd=self._root)
+        src_db = self._root / ".context-memory" / "gdm.db"
+        dst_db = path / ".context-memory" / "gdm.db"
+        dst_db.parent.mkdir(parents=True, exist_ok=True)
+        if src_db.exists():
+            shutil.copy2(src_db, dst_db)
+        return WorktreeInfo(branch=branch, path=path, db_path=dst_db)
+
+    def remove_worktree(self, path: Path) -> None:
+        """Remove a worktree (force — works even with untracked changes)."""
+        _run(["worktree", "remove", "--force", str(path)], cwd=self._root, check=False)
+
+    def list_worktrees(self) -> list[WorktreeInfo]:
+        """Return all worktrees as ``WorktreeInfo`` objects (main worktree included)."""
+        result = _run(["worktree", "list", "--porcelain"], cwd=self._root)
+        infos: list[WorktreeInfo] = []
+        current: dict[str, str] = {}
+        for line in result.stdout.splitlines():
+            if line.startswith("worktree "):
+                current = {"path": line[len("worktree "):].strip()}
+            elif line.startswith("branch "):
+                current["branch"] = line[len("branch "):].strip().replace("refs/heads/", "")
+            elif line == "" and current:
+                if "branch" in current:
+                    p = Path(current["path"])
+                    infos.append(WorktreeInfo(
+                        branch=current["branch"],
+                        path=p,
+                        db_path=p / ".context-memory" / "gdm.db",
+                    ))
+                current = {}
+        return infos
+
+    def delete_branch(self, branch: str) -> None:
+        """Delete a local branch (must not be checked out)."""
+        _run(["branch", "-D", branch], cwd=self._root, check=False)
+
+    def cherry_pick(self, sha: str) -> None:
+        """Cherry-pick a single commit onto the current branch."""
+        _run(["cherry-pick", sha], cwd=self._root)
+
+    def squash_merge(self, branch: str, message: str) -> None:
+        """Squash-merge *branch* into the current branch with *message*."""
+        _run(["merge", "--squash", branch], cwd=self._root)
+        _run(["commit", "-m", message], cwd=self._root)
+
+    def merge_tree_dry_run(self, branch: str) -> str:
+        """Return the output of ``git merge-tree HEAD <branch>`` (dry-run diff).
+
+        If the output contains conflict markers (``<<<<<<<``) a merge would
+        produce conflicts.
+        """
+        result = _run(["merge-tree", "HEAD", branch], cwd=self._root, check=False)
+        return result.stdout
+
+
+# ---------------------------------------------------------------------------
+# Conflict resolution
+# ---------------------------------------------------------------------------
+
+_CONFLICT_START = "<<<<<<"
+_CONFLICT_SEP = "======="
+_CONFLICT_END = ">>>>>>>"
+
+
+@dataclass
+class ConflictResult:
+    """Result of a single-file conflict resolution attempt."""
+
+    resolved: bool
+    reason: str
+    file: Path
+
+
+class ConflictResolver:
+    """Resolves merge conflicts where hunks are non-overlapping.
+
+    Algorithm:
+    1. Read the conflicted file.
+    2. Parse conflict markers: ``<<<<<<< HEAD ... ======= ... >>>>>>> branch``
+    3. For each conflict block: check if HEAD hunk and branch hunk modify
+       different lines (non-overlapping). If so, keep both (HEAD first).
+    4. If any conflict block has overlapping edits (both sides share identical
+       non-empty lines) → ABORT, leave markers in place, return
+       ``ConflictResult(resolved=False, reason="overlapping hunks")``.
+    5. Hard-fail if conflict markers remain in output (safety gate).
+
+    Safety invariant: NEVER produce a file with conflict markers.
+    If resolution is uncertain, return ``resolved=False`` and surface to user.
+    """
+
+    def resolve_file(self, path: Path) -> ConflictResult:
+        """Attempt to resolve merge conflicts in *path*.
+
+        Returns:
+            ConflictResult with ``resolved=True`` if all conflict blocks were
+            resolved and the output file is free of conflict markers;
+            ``resolved=False`` (and the file left unchanged) otherwise.
+        """
+        try:
+            original = path.read_text(encoding="utf-8")
+        except OSError as exc:
+            return ConflictResult(resolved=False, reason=str(exc), file=path)
+
+        if _CONFLICT_START not in original:
+            return ConflictResult(resolved=True, reason="no conflicts", file=path)
+
+        resolved_text, ok, reason = _resolve_conflicts(original)
+        if not ok:
+            # Leave the file untouched
+            return ConflictResult(resolved=False, reason=reason, file=path)
+
+        # Safety gate: NEVER write a file that still contains conflict markers
+        if _CONFLICT_START in resolved_text:
+            log.error(
+                "ConflictResolver safety gate: resolved text still has markers in %s", path
+            )
+            return ConflictResult(
+                resolved=False, reason="safety gate: markers remain after resolution", file=path
+            )
+
+        try:
+            path.write_text(resolved_text, encoding="utf-8")
+        except OSError as exc:
+            return ConflictResult(resolved=False, reason=str(exc), file=path)
+
+        return ConflictResult(resolved=True, reason="all blocks non-overlapping", file=path)
+
+    def resolve_repo(self) -> list[ConflictResult]:
+        """Find all conflicted files in the repo and attempt to resolve each.
+
+        Uses ``git diff --name-only --diff-filter=U`` to find conflicted files.
+
+        Returns:
+            List of ``ConflictResult`` objects, one per conflicted file.
+        """
+        try:
+            result = subprocess.run(
+                ["git", "diff", "--name-only", "--diff-filter=U"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            conflicted = [
+                p.strip() for p in result.stdout.splitlines() if p.strip()
+            ]
+        except Exception as exc:  # noqa: BLE001
+            log.warning("Could not list conflicted files: %s", exc)
+            return []
+
+        results: list[ConflictResult] = []
+        for rel_path in conflicted:
+            abs_path = Path(rel_path).resolve()
+            if not abs_path.exists():
+                abs_path = Path.cwd() / rel_path
+            results.append(self.resolve_file(abs_path))
+        return results
+
+
+def _parse_conflict_blocks(text: str) -> list[tuple[str, str, str, str, str]]:
+    """Parse *text* into segments alternating between plain text and conflict blocks.
+
+    Yields tuples of (before, head_hunk, branch_hunk, after_marker, remainder).
+    Returns list of (prefix, head_lines, branch_lines) for each conflict block
+    plus the surrounding plain segments.
+
+    More precisely, returns a list of dicts; simpler to return a structured list.
+
+    Internal helper — returns (ok, segments) where segments is a list of
+    ``("plain", text)`` or ``("conflict", head_str, branch_str)`` tuples.
+    """
+    segments: list[tuple] = []
+    remaining = text
+    while _CONFLICT_START in remaining:
+        start_idx = remaining.index(_CONFLICT_START)
+        segments.append(("plain", remaining[:start_idx]))
+        remaining = remaining[start_idx:]
+
+        # Find end of start marker line
+        nl = remaining.index("\n")
+        remaining = remaining[nl + 1:]
+
+        # Find separator
+        if _CONFLICT_SEP not in remaining:
+            # Malformed conflict — abort
+            return [("malformed",)]
+
+        sep_idx = remaining.index(_CONFLICT_SEP)
+        head_hunk = remaining[:sep_idx]
+        remaining = remaining[sep_idx + len(_CONFLICT_SEP):]
+
+        # Skip past separator newline
+        if remaining.startswith("\n"):
+            remaining = remaining[1:]
+
+        # Find end marker
+        if _CONFLICT_END not in remaining:
+            return [("malformed",)]
+
+        end_idx = remaining.index(_CONFLICT_END)
+        branch_hunk = remaining[:end_idx]
+        remaining = remaining[end_idx:]
+
+        # Skip end marker line
+        nl2 = remaining.index("\n") if "\n" in remaining else len(remaining)
+        remaining = remaining[nl2 + 1:]
+
+        segments.append(("conflict", head_hunk, branch_hunk))
+
+    segments.append(("plain", remaining))
+    return segments
+
+
+def _resolve_conflicts(text: str) -> tuple[str, bool, str]:
+    """Attempt to resolve all conflict blocks in *text*.
+
+    Returns:
+        (resolved_text, ok, reason) — if ok is False, resolved_text is
+        the original text unchanged and reason explains why.
+    """
+    segments = _parse_conflict_blocks(text)
+
+    if any(s[0] == "malformed" for s in segments):
+        return text, False, "malformed conflict markers"
+
+    output_parts: list[str] = []
+    for seg in segments:
+        if seg[0] == "plain":
+            output_parts.append(seg[1])
+        else:
+            _, head_hunk, branch_hunk = seg
+            head_lines = {
+                ln for ln in head_hunk.splitlines() if ln.strip()
+            }
+            branch_lines = {
+                ln for ln in branch_hunk.splitlines() if ln.strip()
+            }
+            overlap = head_lines & branch_lines
+            if overlap:
+                return text, False, "overlapping hunks"
+            # Non-overlapping: keep both, HEAD first (strip trailing newline
+            # from head_hunk so we don't get a blank line between them)
+            merged = head_hunk.rstrip("\n")
+            if branch_hunk:
+                merged = merged + "\n" + branch_hunk if merged else branch_hunk
+            output_parts.append(merged)
+
+    return "".join(output_parts), True, "ok"
+
+
+# ---------------------------------------------------------------------------
+# Branch cleanup (requires GitHub API)
+# ---------------------------------------------------------------------------
+
+def cleanup_merged_branches(cfg: "object") -> list[str]:
+    """Delete local and remote ``gdm/*`` branches whose PRs are merged.
+
+    Requires GitHub API credentials (``cfg.github_token``).
+    Uses GitHub REST API:
+    ``GET /repos/{owner}/{repo}/pulls?state=closed&head={branch}``
+
+    Only deletes branches where ``pull_request.merged_at`` is not null.
+
+    Args:
+        cfg: a ``GdmConfig``-like object with ``github_token``,
+             ``project_root``, and optionally ``github_repo`` attributes.
+
+    Returns:
+        List of deleted branch names (both local and remote deletions recorded).
+    """
+    import json
+    import urllib.request
+
+    github_token: str | None = getattr(cfg, "github_token", None)
+    if not github_token:
+        log.info("cleanup_merged_branches: no github_token, skipping")
+        return []
+
+    project_root: Path = getattr(cfg, "project_root", Path.cwd())
+
+    # Discover repo owner/name from git remote
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            cwd=str(project_root),
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        remote_url = result.stdout.strip()
+    except Exception as exc:  # noqa: BLE001
+        log.warning("cleanup_merged_branches: could not get remote URL: %s", exc)
+        return []
+
+    owner_repo = _parse_github_repo(remote_url)
+    if not owner_repo:
+        log.warning("cleanup_merged_branches: could not parse GitHub owner/repo from %r", remote_url)
+        return []
+    owner, repo = owner_repo
+
+    # List local gdm/* branches
+    try:
+        result = subprocess.run(
+            ["git", "branch", "--list", "gdm/*"],
+            cwd=str(project_root),
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        local_branches = [
+            b.strip().lstrip("* ") for b in result.stdout.splitlines() if b.strip()
+        ]
+    except Exception as exc:  # noqa: BLE001
+        log.warning("cleanup_merged_branches: could not list branches: %s", exc)
+        return []
+
+    deleted: list[str] = []
+    for branch in local_branches:
+        if not _is_pr_merged(github_token, owner, repo, branch):
+            continue
+
+        # Delete remote branch
+        try:
+            subprocess.run(
+                ["git", "push", "origin", "--delete", branch],
+                cwd=str(project_root),
+                capture_output=True,
+                check=False,
+            )
+        except Exception as exc:  # noqa: BLE001
+            log.warning("cleanup_merged_branches: remote delete of %r failed: %s", branch, exc)
+
+        # Delete local branch
+        try:
+            subprocess.run(
+                ["git", "branch", "-D", branch],
+                cwd=str(project_root),
+                capture_output=True,
+                check=False,
+            )
+            deleted.append(branch)
+            log.info("cleanup_merged_branches: deleted %r", branch)
+        except Exception as exc:  # noqa: BLE001
+            log.warning("cleanup_merged_branches: local delete of %r failed: %s", branch, exc)
+
+    return deleted
+
+
+def _parse_github_repo(remote_url: str) -> tuple[str, str] | None:
+    """Parse ``owner/repo`` from a GitHub remote URL."""
+    import re
+
+    # HTTPS: https://github.com/owner/repo.git
+    m = re.search(r"github\.com[/:]([^/]+)/([^/]+?)(?:\.git)?$", remote_url)
+    if m:
+        return m.group(1), m.group(2)
+    return None
+
+
+def _is_pr_merged(token: str, owner: str, repo: str, branch: str) -> bool:
+    """Return True if the branch has at least one merged PR on GitHub."""
+    import json
+    import urllib.request
+
+    url = (
+        f"https://api.github.com/repos/{owner}/{repo}/pulls"
+        f"?state=closed&head={owner}:{branch}&per_page=5"
+    )
+    req = urllib.request.Request(
+        url,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            pulls = json.loads(resp.read())
+        return any(pr.get("merged_at") for pr in pulls)
+    except Exception as exc:  # noqa: BLE001
+        log.warning("_is_pr_merged: GitHub API call failed for %r: %s", branch, exc)
+        return False
+

src/integrations/__init__.py

@@ -0,0 +1,6 @@
+"""gdm integrations -- MCP and other protocol adapters."""
+from __future__ import annotations
+
+from src.integrations.mcp_server import MCPResource, MCPServer, MCPTool
+
+__all__ = ["MCPServer", "MCPTool", "MCPResource"]