git-panic 0.1.0__py3-none-any.whl

git_panic/__init__.py

@@ -0,0 +1,3 @@
+"""Git-Panic: guided, safety-first Git recovery."""
+
+__version__ = "0.1.0"

git_panic/__main__.py

@@ -0,0 +1,5 @@
+from git_panic.cli import app
+
+
+if __name__ == "__main__":
+    app()

git_panic/cli.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Confirm
+from rich.table import Table
+
+from git_panic.diagnosis import DiagnosisEngine
+from git_panic.git import GitExecutor, GitRepository
+from git_panic.models import GitPanicError, RecoveryPlan
+from git_panic.safety import SafetyValidator
+from git_panic.workflows import RecoveryPlanner
+
+app = typer.Typer(
+    name="git-panic",
+    help="Safely recover from common local Git mistakes.",
+    no_args_is_help=False,
+    add_completion=False,
+)
+console = Console()
+
+
+def _show_plan(plan: RecoveryPlan, dry_run: bool) -> None:
+    label = "DRY RUN: no commands will execute" if dry_run else "Review before execution"
+    console.print(Panel(plan.summary, title=plan.title, subtitle=label, border_style="cyan"))
+    for warning in plan.warnings:
+        console.print(Panel(warning, title="Important", border_style="bold red"))
+    table = Table(title="Recovery commands")
+    table.add_column("Step", justify="right", style="bold cyan")
+    table.add_column("Why")
+    table.add_column("Exact command", style="yellow")
+    for index, command in enumerate(plan.commands, start=1):
+        table.add_row(str(index), command.explanation, command.display)
+    console.print(table)
+    if plan.backup_ref:
+        console.print(f"Safety branch: [bold green]{plan.backup_ref}[/bold green]")
+    else:
+        console.print("[bold red]Warning: safety branch creation is disabled.[/bold red]")
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    dry_run: bool = typer.Option(False, "--dry-run", help="Print commands without executing them."),
+    safety_branch: bool = typer.Option(
+        True,
+        "--safety-branch/--no-safety-branch",
+        help="Create a rescue branch before executing recovery commands.",
+    ),
+    repository: Path = typer.Option(
+        Path("."),
+        "--repo",
+        exists=True,
+        file_okay=False,
+        resolve_path=True,
+        help="Git working tree to inspect.",
+    ),
+) -> None:
+    if ctx.invoked_subcommand is not None:
+        return
+
+    try:
+        repo = GitRepository(repository)
+        validator = SafetyValidator(repo)
+        validator.validate_preflight()
+        planner = RecoveryPlanner(repo, validator, create_safety_branch=safety_branch)
+        plan = DiagnosisEngine(repo, planner, console).diagnose()
+        _show_plan(plan, dry_run)
+
+        executor = GitExecutor(repo)
+        if dry_run:
+            executor.execute(plan, confirmed=False, dry_run=True)
+            console.print("[bold cyan]Dry run complete. Repository state was not changed.[/bold cyan]")
+            return
+
+        confirmed = Confirm.ask(
+            "Execute every command above in order?",
+            default=False,
+            console=console,
+        )
+        if not confirmed:
+            console.print("[yellow]Cancelled. No commands were executed.[/yellow]")
+            raise typer.Exit(0)
+
+        executor.execute(plan, confirmed=True)
+        result_message = "Recovery completed."
+        if plan.backup_ref:
+            result_message += f" Keep [bold]{plan.backup_ref}[/bold] until you have verified the result."
+        console.print(
+            Panel(
+                result_message,
+                border_style="green",
+            )
+        )
+    except GitPanicError as error:
+        console.print(Panel(str(error), title="Git-Panic stopped safely", border_style="red"))
+        raise typer.Exit(1) from error
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Cancelled. No further commands were executed.[/yellow]")
+        raise typer.Exit(130)
+
+
+if __name__ == "__main__":
+    app()

git_panic/diagnosis.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from rich import box
+from rich.console import Console
+from rich.prompt import IntPrompt, Prompt
+from rich.table import Table
+
+from git_panic.git import GitRepository
+from git_panic.models import RecoveryPlan, SafetyError, WorkflowKind
+from git_panic.workflows import RecoveryPlanner
+
+
+MENU_GROUPS: tuple[tuple[str, tuple[tuple[int, str, WorkflowKind, bool | None], ...]], ...] = (
+    (
+        "UNCOMMITTED WORK",
+        (
+            (1, "I want to discard all changes I have not committed yet", WorkflowKind.DISCARD_CHANGES, None),
+            (2, "I deleted a local file and want it back", WorkflowKind.DELETED_FILE, None),
+        ),
+    ),
+    (
+        "LAST COMMIT, NOT SHARED",
+        (
+            (3, "I committed on the wrong branch", WorkflowKind.WRONG_BRANCH, None),
+            (4, "I forgot a small change in my last commit", WorkflowKind.AMEND_CHANGES, None),
+            (5, "I need to change my last commit message", WorkflowKind.FIX_MESSAGE, None),
+            (6, "I committed sensitive information, but have not pushed it yet", WorkflowKind.SENSITIVE_FILE, False),
+            (7, "I want to undo my last commit but keep the changes", WorkflowKind.UNDO_KEEP_CHANGES, None),
+        ),
+    ),
+    (
+        "PUSHED OR PUBLISHED HISTORY",
+        (
+            (8, "I committed and pushed sensitive information", WorkflowKind.SENSITIVE_FILE, True),
+            (9, "I need to undo the latest published commit safely", WorkflowKind.REVERT_PUBLISHED, None),
+        ),
+    ),
+    (
+        "GO BACK IN TIME",
+        (
+            (10, "I need to recover an earlier state", WorkflowKind.REFLOG_RESCUE, None),
+        ),
+    ),
+)
+
+
+class DiagnosisEngine:
+    def __init__(self, repository: GitRepository, planner: RecoveryPlanner, console: Console) -> None:
+        self.repository = repository
+        self.planner = planner
+        self.console = console
+
+    def diagnose(self) -> RecoveryPlan:
+        choices = {
+            number: (workflow, published)
+            for _, scenarios in MENU_GROUPS
+            for number, _, workflow, published in scenarios
+        }
+        self.console.print("[bold]What happened?[/bold]")
+        self.console.print("Choose the situation that best matches your repository.\n")
+        for group, scenarios in MENU_GROUPS:
+            self.console.print(f"[bold cyan]{group}[/bold cyan]")
+            table = Table(show_header=False, box=box.SIMPLE, pad_edge=False)
+            table.add_column("Choice", style="bold cyan", justify="right", width=2)
+            table.add_column("Situation")
+            for number, label, _, _ in scenarios:
+                table.add_row(str(number), label)
+            self.console.print(table)
+        choice = IntPrompt.ask(
+            "Choose what happened",
+            choices=[str(number) for number in choices],
+        )
+        workflow, published = choices[choice]
+
+        if workflow is WorkflowKind.WRONG_BRANCH:
+            destination = Prompt.ask("Name for the new branch that should keep the commit")
+            return self.planner.wrong_branch(destination)
+        if workflow is WorkflowKind.AMEND_CHANGES:
+            return self.planner.amend_changes()
+        if workflow is WorkflowKind.SENSITIVE_FILE:
+            path = Prompt.ask("Repository-relative path of the sensitive file")
+            return self.planner.sensitive_file(path, published=bool(published))
+        if workflow is WorkflowKind.UNDO_KEEP_CHANGES:
+            state = IntPrompt.ask(
+                "Keep the former commit's changes as [1] staged or [2] unstaged",
+                choices=["1", "2"],
+                default=2,
+            )
+            return self.planner.undo_keep_changes(staged=state == 1)
+        if workflow is WorkflowKind.FIX_MESSAGE:
+            message = Prompt.ask("New commit message")
+            return self.planner.fix_message(message)
+        if workflow is WorkflowKind.DISCARD_CHANGES:
+            scope = IntPrompt.ask(
+                "Set aside changes from [1] one path or [2] the entire working tree",
+                choices=["1", "2"],
+                default=1,
+            )
+            path = Prompt.ask("Repository-relative path") if scope == 1 else None
+            return self.planner.discard_changes(path)
+        if workflow is WorkflowKind.DELETED_FILE:
+            path = Prompt.ask("Repository-relative path of the deleted file")
+            return self.planner.deleted_file(path)
+        if workflow is WorkflowKind.REVERT_PUBLISHED:
+            return self.planner.revert_published_head()
+        return self._reflog_plan()
+
+    def _reflog_plan(self) -> RecoveryPlan:
+        entries = self.repository.reflog()
+        if not entries:
+            raise SafetyError("No reflog entries are available for recovery.")
+        table = Table(title="Recent reflog entries")
+        table.add_column("Choice", style="bold cyan", justify="right")
+        table.add_column("Commit", style="yellow")
+        table.add_column("Selector")
+        table.add_column("Action")
+        for index, (commit, selector, subject) in enumerate(entries, start=1):
+            table.add_row(str(index), commit[:10], selector, subject)
+        self.console.print(table)
+        choice = IntPrompt.ask(
+            "Choose the state to recover",
+            choices=[str(i) for i in range(1, len(entries) + 1)],
+        )
+        destination = Prompt.ask("Name for the new recovery branch", default="recovered-work")
+        return self.planner.reflog_rescue(entries[choice - 1][0], destination)

git_panic/git.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from git_panic.models import CommandError, FileAppend, GitCommand, RecoveryPlan
+
+
+class GitRepository:
+    """Read-only queries for one Git working tree."""
+
+    def __init__(self, path: Path | str = ".") -> None:
+        requested = Path(path).resolve()
+        result = self._run_at(requested, ("rev-parse", "--show-toplevel"), check=False)
+        if result.returncode != 0:
+            raise CommandError(
+                "git rev-parse --show-toplevel",
+                result.stderr.strip() or "not inside a Git working tree",
+                result.returncode,
+            )
+        self.root = Path(result.stdout.strip()).resolve()
+
+    @staticmethod
+    def _run_at(
+        path: Path,
+        args: tuple[str, ...],
+        *,
+        check: bool = True,
+    ) -> subprocess.CompletedProcess[str]:
+        try:
+            result = subprocess.run(
+                ("git", *args),
+                cwd=path,
+                text=True,
+                capture_output=True,
+                check=False,
+            )
+        except OSError as error:
+            command = GitCommand(args, "Read repository state", state_changing=False)
+            raise CommandError(command.display, str(error), 127) from error
+        if check and result.returncode != 0:
+            command = GitCommand(args, "Read repository state", state_changing=False)
+            raise CommandError(
+                command.display,
+                result.stderr.strip() or result.stdout.strip() or "unknown Git error",
+                result.returncode,
+            )
+        return result
+
+    def run(
+        self,
+        *args: str,
+        check: bool = True,
+    ) -> subprocess.CompletedProcess[str]:
+        return self._run_at(self.root, tuple(args), check=check)
+
+    def output(self, *args: str) -> str:
+        return self.run(*args).stdout.strip()
+
+    def git_path(self, name: str) -> Path:
+        path = Path(self.output("rev-parse", "--git-path", name))
+        return path if path.is_absolute() else self.root / path
+
+    def head(self) -> str:
+        return self.output("rev-parse", "--verify", "HEAD")
+
+    def head_parent(self) -> str:
+        result = self.run("rev-parse", "--verify", "HEAD^", check=False)
+        if result.returncode != 0:
+            raise CommandError(
+                "git rev-parse --verify 'HEAD^'",
+                "the current commit has no parent",
+                result.returncode,
+            )
+        return result.stdout.strip()
+
+    def head_parent_count(self) -> int:
+        fields = self.output("rev-list", "--parents", "-n", "1", "HEAD").split()
+        return max(0, len(fields) - 1)
+
+    def current_branch(self) -> str | None:
+        result = self.run("symbolic-ref", "--quiet", "--short", "HEAD", check=False)
+        return result.stdout.strip() if result.returncode == 0 else None
+
+    def branch_exists(self, name: str) -> bool:
+        return self.run("show-ref", "--verify", "--quiet", f"refs/heads/{name}", check=False).returncode == 0
+
+    def valid_branch_name(self, name: str) -> bool:
+        return self.run("check-ref-format", "--branch", name, check=False).returncode == 0
+
+    def is_dirty(self) -> bool:
+        return bool(self.output("status", "--porcelain=v1", "--untracked-files=normal"))
+
+    def has_staged_changes(self) -> bool:
+        return self.run("diff", "--cached", "--quiet", check=False).returncode != 0
+
+    def staged_paths(self) -> set[str]:
+        output = self.run("diff", "--cached", "--name-only", "-z").stdout
+        return {path for path in output.split("\0") if path}
+
+    def has_unmerged_paths(self) -> bool:
+        return bool(self.output("diff", "--name-only", "--diff-filter=U"))
+
+    def upstream_divergence(self) -> tuple[int, int] | None:
+        status = self.output("status", "--porcelain=v2", "--branch")
+        for line in status.splitlines():
+            if line.startswith("# branch.ab "):
+                ahead_text, behind_text = line.removeprefix("# branch.ab ").split()
+                return int(ahead_text), abs(int(behind_text))
+        return None
+
+    def head_is_published(self) -> bool:
+        if self.current_branch() is None:
+            return False
+        upstream = self.run("rev-parse", "--verify", "@{upstream}", check=False)
+        if upstream.returncode != 0:
+            return False
+        return self.run("merge-base", "--is-ancestor", "HEAD", "@{upstream}", check=False).returncode == 0
+
+    def head_is_upstream_tip(self) -> bool:
+        upstream = self.run("rev-parse", "--verify", "@{upstream}", check=False)
+        return upstream.returncode == 0 and self.head() == upstream.stdout.strip()
+
+    def tracked(self, path: str) -> bool:
+        literal_path = f":(literal){path}"
+        result = self.output("ls-tree", "-r", "--name-only", "HEAD", "--", literal_path)
+        return path in result.splitlines()
+
+    def path_has_changes(self, path: str) -> bool:
+        literal_path = f":(literal){path}"
+        return bool(
+            self.output(
+                "status",
+                "--porcelain=v1",
+                "--untracked-files=normal",
+                "--",
+                literal_path,
+            )
+        )
+
+    def repository_ignore_source(self, path: str) -> str | None:
+        result = self.run("check-ignore", "--verbose", "--no-index", "--", path, check=False)
+        if result.returncode != 0 or not result.stdout:
+            return None
+        metadata = result.stdout.split("\t", 1)[0]
+        parts = metadata.rsplit(":", 2)
+        if len(parts) != 3:
+            return None
+        source = Path(parts[0])
+        candidate = source if source.is_absolute() else self.root / source
+        try:
+            relative = candidate.resolve().relative_to(self.root)
+        except ValueError:
+            return None
+        if relative.name != ".gitignore":
+            return None
+        return relative.as_posix()
+
+    def index_tracks(self, path: str) -> bool:
+        literal_path = f":(literal){path}"
+        return self.run("ls-files", "--error-unmatch", "--", literal_path, check=False).returncode == 0
+
+    def has_unstaged_changes(self, path: str) -> bool:
+        literal_path = f":(literal){path}"
+        return self.run("diff", "--quiet", "--", literal_path, check=False).returncode != 0
+
+    def reflog(self, limit: int = 15) -> list[tuple[str, str, str]]:
+        result = self.output(
+            "reflog",
+            "show",
+            f"-{limit}",
+            "--format=%H%x09%gd%x09%gs",
+        )
+        entries: list[tuple[str, str, str]] = []
+        for line in result.splitlines():
+            parts = line.split("\t", 2)
+            if len(parts) == 3:
+                entries.append((parts[0], parts[1], parts[2]))
+        return entries
+
+
+class GitExecutor:
+    """The only component permitted to execute mutating Git commands."""
+
+    def __init__(self, repository: GitRepository) -> None:
+        self.repository = repository
+
+    def execute(
+        self,
+        plan: RecoveryPlan,
+        *,
+        confirmed: bool,
+        dry_run: bool = False,
+    ) -> list[str]:
+        displays = [command.display for command in plan.commands]
+        if dry_run:
+            return displays
+        if any(command.state_changing for command in plan.commands) and not confirmed:
+            from git_panic.models import ConfirmationRequired
+
+            raise ConfirmationRequired("Explicit confirmation is required before changing repository state.")
+
+        completed: list[str] = []
+        for command in plan.commands:
+            if isinstance(command, FileAppend):
+                target = self.repository.root / command.path
+                try:
+                    existing = target.read_text(encoding="utf-8") if target.exists() else ""
+                    prefix = "" if not existing or existing.endswith("\n") else "\n"
+                    with target.open("a", encoding="utf-8") as stream:
+                        stream.write(f"{prefix}{command.line}\n")
+                except OSError as error:
+                    raise CommandError(command.display, str(error), 1) from error
+            else:
+                self.repository.run(*command.args)
+            completed.append(command.display)
+        return completed

git_panic/models.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import shlex
+from dataclasses import dataclass
+from enum import Enum
+
+
+class WorkflowKind(str, Enum):
+    WRONG_BRANCH = "wrong-branch"
+    AMEND_CHANGES = "amend-changes"
+    SENSITIVE_FILE = "sensitive-file"
+    UNDO_KEEP_CHANGES = "undo-keep-changes"
+    FIX_MESSAGE = "fix-message"
+    DISCARD_CHANGES = "discard-changes"
+    DELETED_FILE = "deleted-file"
+    REVERT_PUBLISHED = "revert-published"
+    REFLOG_RESCUE = "reflog-rescue"
+
+
+@dataclass(frozen=True)
+class GitCommand:
+    args: tuple[str, ...]
+    explanation: str
+    state_changing: bool = True
+
+    @property
+    def display(self) -> str:
+        return shlex.join(("git", *self.args))
+
+
+@dataclass(frozen=True)
+class FileAppend:
+    path: str
+    line: str
+    explanation: str
+    state_changing: bool = True
+
+    @property
+    def display(self) -> str:
+        return f"append {self.line!r} to {self.path}"
+
+
+@dataclass(frozen=True)
+class RecoveryPlan:
+    workflow: WorkflowKind
+    title: str
+    summary: str
+    backup_ref: str | None
+    commands: tuple[GitCommand | FileAppend, ...]
+    warnings: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ReflogEntry:
+    commit: str
+    selector: str
+    subject: str
+
+
+class GitPanicError(RuntimeError):
+    """Base error for errors that should be shown without a traceback."""
+
+
+class SafetyError(GitPanicError):
+    """Raised when repository state makes an operation unsafe."""
+
+
+class CommandError(GitPanicError):
+    def __init__(self, command: str, detail: str, returncode: int) -> None:
+        super().__init__(f"{command} failed ({returncode}): {detail}")
+        self.command = command
+        self.detail = detail
+        self.returncode = returncode
+
+
+class ConfirmationRequired(GitPanicError):
+    """Raised when a mutating plan was not explicitly confirmed."""

git_panic/safety.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from git_panic.git import GitRepository
+from git_panic.models import SafetyError
+
+
+class SafetyValidator:
+    IN_PROGRESS_MARKERS = {
+        "MERGE_HEAD": "merge",
+        "CHERRY_PICK_HEAD": "cherry-pick",
+        "REVERT_HEAD": "revert",
+        "BISECT_LOG": "bisect",
+        "rebase-apply": "rebase",
+        "rebase-merge": "rebase",
+    }
+
+    def __init__(self, repository: GitRepository) -> None:
+        self.repository = repository
+
+    def validate_preflight(self) -> None:
+        active = {
+            label
+            for marker, label in self.IN_PROGRESS_MARKERS.items()
+            if self.repository.git_path(marker).exists()
+        }
+        if active:
+            operations = ", ".join(sorted(active))
+            raise SafetyError(
+                f"Git-Panic will not run during an active {operations} operation. "
+                "Finish or abort it manually, then retry."
+            )
+        if self.repository.has_unmerged_paths():
+            raise SafetyError(
+                "The repository has unresolved conflicts. Resolve them or abort the current operation first."
+            )
+        divergence = self.repository.upstream_divergence()
+        if divergence and divergence[0] > 0 and divergence[1] > 0:
+            raise SafetyError(
+                "The current branch has diverged from its upstream. Git-Panic's local-only workflows "
+                "cannot safely choose how to reconcile the remote history."
+            )
+
+    def require_attached_head(self) -> str:
+        branch = self.repository.current_branch()
+        if branch is None:
+            raise SafetyError("This workflow requires a named branch. Use Reflog Rescue for a detached HEAD.")
+        return branch
+
+    def require_clean_worktree(self, workflow: str) -> None:
+        if self.repository.is_dirty():
+            raise SafetyError(
+                f"{workflow} requires a clean working tree so existing changes cannot be mixed into recovery."
+            )
+
+    def refuse_published_head(self) -> None:
+        if self.repository.head_is_published():
+            raise SafetyError(
+                "The last commit appears to exist on the configured upstream. Git-Panic only rewrites "
+                "unpublished local history and will not alter shared history."
+            )
+
+    def require_published_head(self) -> None:
+        if not self.repository.head_is_upstream_tip():
+            raise SafetyError(
+                "The current commit is not the configured upstream tip. Update your remote-tracking state "
+                "and check out the latest published commit before creating a revert commit."
+            )