dotman-git 1.0.0__py3-none-any.whl

dot_man/__init__.py

@@ -0,0 +1,4 @@
+"""dot-man: Dotfile manager with git-powered branching."""
+
+__version__ = "1.0.0"
+__author__ = "Bishoy Ehab"

dot_man/backups.py

@@ -0,0 +1,211 @@
+"""Backup management for dot-man."""
+
+__all__ = ["BackupManager"]
+
+import json
+import shutil
+from datetime import datetime
+from pathlib import Path
+
+from .constants import BACKUPS_DIR, MAX_BACKUPS
+from .exceptions import BackupError
+
+
+class BackupManager:
+    """Manages local safety snapshots."""
+
+    def __init__(self, backups_dir: Path | None = None, max_backups: int | None = None):
+        self.backups_dir = backups_dir or BACKUPS_DIR
+        self.max_backups = max_backups or MAX_BACKUPS
+        # Ensure backups directory exists
+        self.backups_dir.mkdir(parents=True, exist_ok=True)
+
+    def _get_backup_name(self, note: str = "manual") -> str:
+        """Generate a unique backup name."""
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        # Sanitize note
+        note_safe = "".join(c if c.isalnum() else "_" for c in note)
+        return f"{timestamp}_{note_safe}"
+
+    def create_backup(self, paths: list[Path], note: str = "manual") -> str:
+        """
+        Create a backup snapshot of the given paths.
+
+        Args:
+            paths: List of file/directory paths to backup.
+            note: Short description/reason for backup.
+
+        Returns:
+            The name (ID) of the created backup.
+        """
+        if not paths:
+            return ""
+
+        backup_id = self._get_backup_name(note)
+        backup_path = self.backups_dir / backup_id
+
+        try:
+            backup_path.mkdir()
+
+            # Metadata to store original paths relative to home or absolute
+            manifest = {}
+            count = 0
+
+            for path in paths:
+                if not path.exists():
+                    continue
+
+                # Determine destination structure within backup
+                # We replicate the structure relative to user's home or root
+                # For simplicity, we flattening somewhat or mirroring full path?
+                # Mirroring full path is safest to avoid collisions.
+                # E.g. /home/user/.bashrc -> backup/home/user/.bashrc
+
+                # Strip root anchor to make it relative
+                rel_path = path.relative_to(path.anchor)
+                dest = backup_path / rel_path
+
+                dest.parent.mkdir(parents=True, exist_ok=True)
+
+                if path.is_file():
+                    shutil.copy2(path, dest)
+                elif path.is_dir():
+                    shutil.copytree(path, dest)
+
+                manifest[str(rel_path)] = str(path)
+                count += 1
+
+            if count == 0:
+                # No files backed up, remove empty directory
+                backup_path.rmdir()
+                return ""
+
+            # Save manifest
+            (backup_path / "manifest.json").write_text(
+                json.dumps(manifest, indent=2), encoding="utf-8"
+            )
+
+            # Rotate old backups
+            self._rotate_backups()
+
+            return backup_id
+
+        except OSError as e:
+            # Cleanup on failure
+            if backup_path.exists():
+                shutil.rmtree(backup_path, ignore_errors=True)
+            raise BackupError(f"Failed to create backup '{backup_id}': {e}")
+
+    def list_backups(self) -> list[dict]:
+        """
+        List all available backups.
+
+        Returns:
+            List of dicts with keys: id, date, note, path
+        """
+        backups = []
+        if not self.backups_dir.exists():
+            return []
+
+        for p in self.backups_dir.iterdir():
+            if p.is_dir():
+                # Parse name: YYYYMMDD_HHMMSS_note
+                parts = p.name.split("_", 2)
+                if len(parts) >= 2:
+                    date_str = f"{parts[0]} {parts[1][:2]}:{parts[1][2:4]}"
+                    note = parts[2] if len(parts) > 2 else "auto"
+                    backups.append(
+                        {"id": p.name, "date": date_str, "note": note, "path": p}
+                    )
+
+        # Sort by ID (timestamp) descending
+        return sorted(backups, key=lambda x: x["id"], reverse=True)
+
+    def restore_backup(self, backup_id: str) -> bool:
+        """
+        Restore files from a backup.
+
+        Args:
+           backup_id: The ID (folder name) of the backup to restore.
+        """
+        backup_path = self.backups_dir / backup_id
+        if not backup_path.exists():
+            raise BackupError(f"Backup '{backup_id}' not found")
+
+        manifest_file = backup_path / "manifest.json"
+        if not manifest_file.exists():
+            raise BackupError(f"Backup '{backup_id}' is corrupt (missing manifest)")
+
+        try:
+            manifest = json.loads(manifest_file.read_text(encoding="utf-8"))
+
+            for rel_path_str, original_path_str in manifest.items():
+                start_source = backup_path / rel_path_str
+                original_path = Path(original_path_str)
+
+                if start_source.exists():
+                    # Ensure parent exists
+                    original_path.parent.mkdir(parents=True, exist_ok=True)
+
+                    if original_path.exists():
+                        if original_path.is_dir():
+                            shutil.rmtree(original_path)
+                        else:
+                            original_path.unlink()
+
+                    if start_source.is_dir():
+                        shutil.copytree(start_source, original_path)
+                    else:
+                        shutil.copy2(start_source, original_path)
+
+            return True
+
+        except (OSError, json.JSONDecodeError) as e:
+            raise BackupError(f"Failed to restore backup '{backup_id}': {e}")
+
+    def _rotate_backups(self) -> None:
+        """Keep only the last MAX_BACKUPS backups."""
+        self.clean_backups(keep=MAX_BACKUPS)
+
+    def delete_backup(self, backup_id: str) -> bool:
+        """
+        Delete a specific backup by ID.
+
+        Args:
+            backup_id: The ID of the backup to delete.
+
+        Returns:
+            True if deleted, False if not found.
+        """
+        backup_path = self.backups_dir / backup_id
+        if not backup_path.exists():
+            return False
+
+        try:
+            shutil.rmtree(backup_path)
+            return True
+        except OSError:
+            return False
+
+    def clean_backups(self, keep: int = 0) -> int:
+        """
+        Remove old backups, keeping the specified number of most recent ones.
+
+        Args:
+            keep: Number of recent backups to keep.
+
+        Returns:
+            Number of backups deleted.
+        """
+        backups = self.list_backups()
+        if len(backups) <= keep:
+            return 0
+
+        to_delete = backups[keep:]
+        deleted_count = 0
+
+        for b in to_delete:
+            if self.delete_backup(b["id"]):
+                deleted_count += 1
+
+        return deleted_count

dot_man/branch_ops.py

@@ -0,0 +1,347 @@
+"""Branch and revert operations mixin for DotManOperations."""
+
+from abc import abstractmethod
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+from .constants import LOCK_FILE, REPO_DIR
+from .exceptions import DotManError
+from .files import atomic_write_text, clear_comparison_cache, copy_file
+from .lock import FileLock
+from .merge import get_hook_for_config
+from .secrets import SecretMatch
+from .ui import warn
+
+if TYPE_CHECKING:
+    pass
+
+FILE_TO_HOOK_MAP = {
+    ".bashrc": "bash_reload",
+    ".zshrc": "zsh_reload",
+    ".bash_profile": "bash_reload",
+    ".zprofile": "zsh_reload",
+    ".config/fish": "fish_reload",
+    ".tmux.conf": "tmux_reload",
+    ".config/nvim": "nvim_sync",
+    ".config/kitty": "kitty_reload",
+    ".config/alacritty": "alacritty_reload",
+    ".config/wezterm": "wezterm_reload",
+    ".config/hypr": "hyprland_reload",
+    ".config/hyprland": "hyprland_reload",
+    ".config/sway": "sway_reload",
+    ".config/i3": "i3_reload",
+    ".config/awesome": "awesome_reload",
+    ".config/polybar": "polybar_reload",
+    ".config/waybar": "waybar_reload",
+    ".config/dunst": "dunst_reload",
+    ".config/picom": "picom_reload",
+    ".Xresources": "xreload",
+    ".config/starship": "starship_reload",
+    ".fzf.bash": "fzf_reload",
+    ".fzf.zsh": "fzf_reload",
+    ".emacs.d": "emacs_reload",
+    ".vimrc": "vim_reload",
+    ".gitconfig": "git_reload",
+}
+
+
+class BranchMixin:
+    """Mixin providing branch switch and file revert operations."""
+
+    @property
+    @abstractmethod
+    def current_branch(self) -> str: ...
+
+    @abstractmethod
+    def save_all(
+        self, secret_handler: Optional[Callable[[SecretMatch], str]] = None
+    ) -> dict[str, Any]: ...
+
+    @property
+    @abstractmethod
+    def git(self) -> Any: ...
+
+    @abstractmethod
+    def reload_config(self) -> None: ...
+
+    @abstractmethod
+    def get_sections(self) -> list[str]: ...
+
+    @abstractmethod
+    def get_section(self, name: str) -> Any: ...
+
+    @property
+    @abstractmethod
+    def backups(self) -> Any: ...
+
+    @abstractmethod
+    def scan_deployable_changes(self, sections: list[Any]) -> Any: ...
+
+    @abstractmethod
+    def execute_deployment_plan(self, plan: Any) -> dict[str, Any]: ...
+
+    @property
+    @abstractmethod
+    def global_config(self) -> Any: ...
+
+    @property
+    @abstractmethod
+    def vault(self) -> Any: ...
+
+    def switch_branch(
+        self,
+        target_branch: str,
+        dry_run: bool = False,
+        secret_handler: Optional[Callable[[SecretMatch], str]] = None,
+    ) -> dict:
+        """
+        Switch to a different branch.
+
+        Returns dict with:
+            - saved_count: files saved from current branch
+            - deployed_count: files deployed from target branch
+            - secrets_redacted: number of secrets redacted
+            - pre_hooks: list of pre-deploy commands
+            - post_hooks: list of post-deploy commands
+            - created_branch: True if branch was newly created
+            - errors: list of error messages
+        """
+        current_branch = self.current_branch
+        result: dict[str, Any] = {
+            "saved_count": 0,
+            "deployed_count": 0,
+            "secrets_redacted": 0,
+            "pre_hooks": [],
+            "post_hooks": [],
+            "created_branch": False,
+            "errors": [],
+        }
+
+        if current_branch == target_branch and not dry_run:
+            return result
+
+        import contextlib
+
+        lock_context = FileLock(LOCK_FILE) if not dry_run else contextlib.nullcontext()
+
+        with lock_context:
+            # Phase 1: Save current branch
+            if not dry_run:
+                save_result = self.save_all(secret_handler)
+                result["saved_count"] = save_result["saved"]
+                result["secrets_redacted"] = len(save_result["secrets"])
+                result["errors"].extend(save_result["errors"])
+
+                commit_msg = f"Auto-save from '{current_branch}' before switch to '{target_branch}'"
+                self.git.commit(commit_msg)
+
+            # Phase 2: Switch git branch
+            branch_exists = self.git.branch_exists(target_branch)
+            result["created_branch"] = not branch_exists
+
+            if not dry_run:
+                self.git.checkout(target_branch, create=not branch_exists)
+                self.reload_config()
+
+            # Phase 3: Deploy target branch
+            if not dry_run:
+                # Auto-backup before potentially destructive deployment
+                try:
+                    paths_to_backup = []
+                    for section_name in self.get_sections():
+                        section = self.get_section(section_name)
+                        paths_to_backup.extend([p for p in section.paths if p.exists()])
+
+                    if paths_to_backup:
+                        self.backups.create_backup(
+                            paths_to_backup, note=f"pre-switch-{target_branch}"
+                        )
+                except Exception as e:
+                    result["errors"].append(f"Warning: Auto-backup failed: {e}")
+
+                # Two-Phase Deployment for Target Branch
+                try:
+                    sections = [self.get_section(name) for name in self.get_sections()]
+
+                    plan = self.scan_deployable_changes(sections)
+
+                    result["pre_hooks"].extend(plan["pre_hooks"])
+                    result["post_hooks"].extend(plan["post_hooks"])
+                    result["errors"].extend(plan["errors"])
+
+                    result["pre_hooks"] = list(dict.fromkeys(result["pre_hooks"]))
+                    result["post_hooks"] = list(dict.fromkeys(result["post_hooks"]))
+
+                    deploy_result = self.execute_deployment_plan(plan)
+
+                    result["deployed_count"] = deploy_result["deployed"]
+                    result["errors"].extend(deploy_result["errors"])
+
+                    # Auto-detect hooks based on changed files
+                    changed_files = self.get_changed_files_between_branches(
+                        current_branch, target_branch
+                    )
+                    if changed_files:
+                        auto_hooks = self.detect_hooks_for_changed_files(changed_files)
+                        for hook in auto_hooks:
+                            if hook and hook not in result["post_hooks"]:
+                                result["post_hooks"].append(hook)
+
+                except Exception as e:
+                    result["errors"].append(
+                        f"Critical error during switch deployment: {e}"
+                    )
+
+                self.global_config.current_branch = target_branch
+                self.global_config.save()
+
+            # Clear file comparison cache since files have likely changed
+            clear_comparison_cache()
+
+        return result
+
+    def revert_file(self, path: Path) -> bool:
+        """
+        Revert a specific file to its repository version.
+
+        Args:
+            path: Absolute path to the file to revert.
+
+        Returns:
+            True if successful, False if file not tracked or not found in repo.
+        """
+        path = path.resolve()
+
+        # Find which section tracks this file
+        target_section = None
+        repo_source = None
+
+        for section_name in self.get_sections():
+            section = self.get_section(section_name)
+            if path in section.paths:
+                target_section = section
+                repo_source = section.get_repo_path(path, REPO_DIR)
+                break
+
+            for p in section.paths:
+                if p.is_dir() and p in path.parents:
+                    target_section = section
+                    repo_source = section.get_repo_path(path, REPO_DIR)
+                    break
+
+            if target_section:
+                break
+
+        if not target_section or not repo_source:
+            warn(f"File not tracked by any section: {path}")
+            return False
+
+        if not repo_source.exists():
+            warn(
+                f"File not found in repository (branch: {self.current_branch}): {repo_source}"
+            )
+            return False
+
+        try:
+            success, _ = copy_file(repo_source, path, filter_secrets_enabled=False)
+
+            if success and target_section.secrets_filter:
+                try:
+                    content = path.read_text(encoding="utf-8")
+                    restored = self.vault.restore_secrets_in_content(
+                        content, str(path), self.current_branch
+                    )
+                    if restored != content:
+                        atomic_write_text(path, restored)
+                except (OSError, UnicodeDecodeError):
+                    pass
+
+            return success
+
+        except Exception as e:
+            raise DotManError(f"Failed to revert {path}: {e}")
+
+    def get_changed_files_between_branches(
+        self, source_branch: str, target_branch: str
+    ) -> list[str]:
+        """Get list of files that differ between two branches.
+
+        Args:
+            source_branch: The source branch name
+            target_branch: The target branch name
+
+        Returns:
+            List of file paths that changed
+        """
+        try:
+            diff_output = self.git.repo.git.diff(
+                f"{source_branch}...{target_branch}", "--name-only"
+            )
+            if diff_output.strip():
+                return [f.strip() for f in diff_output.strip().split("\n") if f.strip()]
+        except Exception:
+            pass
+        return []
+
+    def detect_hooks_for_changed_files(self, changed_files: list[str]) -> list[str]:
+        """Determine which hooks to run based on changed files.
+
+        Args:
+            changed_files: List of file paths that changed
+
+        Returns:
+            List of hook commands to execute (deduplicated)
+        """
+        hooks_to_run = set()
+
+        for file_path in changed_files:
+            file_str = str(file_path)
+
+            for pattern, hook_name in FILE_TO_HOOK_MAP.items():
+                if pattern in file_str or file_str.endswith(pattern):
+                    hook_cmd = get_hook_for_config(pattern)
+                    if hook_cmd:
+                        hooks_to_run.add(hook_cmd)
+                    break
+
+            section_name = self._find_section_for_file(file_path)
+            if section_name:
+                section = self.get_section(section_name)
+                if section.pre_deploy:
+                    hooks_to_run.add(section.pre_deploy)
+                if section.post_deploy:
+                    hooks_to_run.add(section.post_deploy)
+
+        return list(hooks_to_run)
+
+    def _find_section_for_file(self, file_path: str) -> str | None:
+        """Find which section tracks a given file path.
+
+        Args:
+            file_path: Path to search for
+
+        Returns:
+            Section name or None
+        """
+        path = (
+            Path(file_path).expanduser()
+            if file_path.startswith("~")
+            else Path(file_path)
+        )
+
+        for section_name in self.get_sections():
+            section = self.get_section(section_name)
+            for section_path in section.paths:
+                if path == section_path or (
+                    section_path.is_dir() and self._is_subpath(path, section_path)
+                ):
+                    return section_name
+        return None
+
+    def _is_subpath(self, path: Path, parent: Path) -> bool:
+        """Check if path is under parent directory."""
+        try:
+            path.resolve().relative_to(parent.resolve())
+            return True
+        except ValueError:
+            return False

dot_man/cli/__init__.py

@@ -0,0 +1,113 @@
+"""dot-man CLI package.
+
+This package provides the CLI entry point for dot-man.
+It exposes the modular CLI implementation.
+"""
+
+from .add_cmd import add
+from .audit_cmd import audit
+from .backup_cmd import backup
+from .branch_cmd import branch
+from .clean_cmd import clean
+from .common import (
+    DotManGroup,
+    _clear_completion_cache,
+    _set_git_runner,
+    complete_branches,
+    complete_commits,
+    complete_config_keys,
+    complete_profiles,
+    complete_switch_args,
+    complete_tags,
+    complete_template_keys,
+    error,
+    get_secret_handler,
+    parse_branch_arg,
+    require_init,
+    success,
+    warn,
+)
+from .completions_cmd import completions
+from .config_cmd import config
+from .deploy_cmd import deploy
+from .discover_cmd import discover_cmd
+from .doctor_cmd import doctor
+from .edit_cmd import edit
+from .encrypt_cmd import encrypt_cmd
+from .export_cmd import export_cmd
+from .import_cmd import import_cmd
+
+# Import commands for easier access and backward compatibility
+from .init_cmd import init
+from .interface import cli
+from .log_cmd import checkout, diff, log
+from .main import main
+from .navigate_cmd import hooks, navigate
+from .onboarding import is_first_run, mark_onboarded, run_onboarding
+from .profile_cmd import profile
+from .remote_cmd import remote, sync
+from .restore_cmd import restore
+from .revert_cmd import revert
+from .show_cmd import show
+from .status_cmd import status
+from .switch_cmd import switch
+from .tag_cmd import tag
+from .template_cmd import template
+from .tui_cmd import tui
+from .verify_cmd import verify
+
+__all__ = [
+    "main",
+    "cli",
+    "error",
+    "success",
+    "warn",
+    "require_init",
+    "DotManGroup",
+    "complete_branches",
+    "complete_tags",
+    "complete_commits",
+    "complete_template_keys",
+    "complete_config_keys",
+    "complete_profiles",
+    "complete_switch_args",
+    "parse_branch_arg",
+    "get_secret_handler",
+    "_set_git_runner",
+    "_clear_completion_cache",
+    "run_onboarding",
+    "is_first_run",
+    "mark_onboarded",
+    "init",
+    "add",
+    "status",
+    "switch",
+    "deploy",
+    "edit",
+    "audit",
+    "backup",
+    "branch",
+    "remote",
+    "sync",
+    "tui",
+    "config",
+    "revert",
+    "restore",
+    "clean",
+    "doctor",
+    "verify",
+    "log",
+    "show",
+    "checkout",
+    "diff",
+    "tag",
+    "template",
+    "profile",
+    "navigate",
+    "hooks",
+    "import_cmd",
+    "export_cmd",
+    "encrypt_cmd",
+    "discover_cmd",
+    "completions",
+]