dotman-git 1.3.0__tar.gz → 1.4.0__tar.gz

{dotman_git-1.3.0 → dotman_git-1.4.0}/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Shell completions for `add` command** — file/directory path completion using `@completes("add", param="path")` decorator
+- **Shell completions for `bootstrap` command** — package manager name completion (`brew`, `apt`, `dnf`, `pacman`, etc.) via `@completes("bootstrap", param="pm")` decorator
+- **19 new documentation pages** — dedicated pages for `init`, `add`, `deploy`, `tag`, `log`, `diff`, `revert`, `import`, `export`, `discover`, `encrypt`, `hooks`, `template`, `profile`, `watch`, `rollback`, `backup`, `verify`, `completions` commands
+- **Docs navigation restructured** — commands grouped by category (Core, Configuration, Inspection, Tags, Encryption, Import/Export, Hooks, Shell)
+- **Roadmap updated** — consistent with v1.4.0 state, removed stale duplicate sections
+
+### Fixed
+
+- **`save_cmd.py`** — fixed `_sync_shared_sections` → `sync_shared_sections` name mismatch that caused `NameError` on `--commit` flag
+- **`shared_sync.py`** — `_sync_branch` now records overridden sections in `report.skipped` even when other shared sections are still wanted (partial overrides)
+- **`test_shared_sync.py`** — fixed test expectations for `test_edits_reach_non_overriding_branches` (work overrides fish, so only server gets propagated), `test_unparsable_target_config_is_skipped_safely` (fixed `run_git()` call to use `subprocess.run` with `input=`), `test_source_branch_never_modified` (fixed log assertion to use `-1` flag)
+- **Tests** — all 1700 tests passing (up from 1691), 1 skipped
+
+### Changed
+
+- **Repository cleanup** — single source of truth for completion scripts (`dot_man/completions/`); removed the duplicated `scripts/completions/` copies and the unused packaged `install.sh`. `install.sh` now installs completions via the built-in `dot-man completions` command. Removed the stale `docs/development/roadmap.md` duplicate and surfaced `docs/roadmap.md` in the docs site nav.
+
+### Removed
+
+- **Tracked artifacts** — dropped `coverage.json` (256 KB CI artifact) and the author's personal `config.toml` from version control; both now gitignored along with benchmark output.
+- **Local clutter** — `.gitignore` fixed (broken merged pattern) and extended: coverage reports, benchmarks, stale build/dist/site outputs no longer pollute the working tree.
+
+## [1.4.0] - 2026-08-25
+
+### Added
+
+- **Decorator-driven completion engine** — new `dot_man/cli/completion_engine.py` gathers commands, subcommands, options, accepted values (static or dynamic) and defaults from the Click CLI definition itself. Extended via the `@completes(path, param=...)` decorator registry; a `(path, param)` registration wins over the generic one.
+- **`dot-man --complete <shell>` protocol** — handled before onboarding/git/side effects in `main()`. Fish output uses `value<TAB>description` lines so descriptions render natively.
+- **Defaults & choices surfaced** — option completions now show `[choices: bash|zsh|fish|all]` and `[default: all]` inline (e.g. `dot-man completions --s<TAB>`).
+- **Alias labeling** — shell shortcuts like `nav`, `cpl`, `aud` are listed as `(alias)` entries instead of indistinguishable duplicates.
+- **`--option=<TAB>` form** — completing after `=` emits full tokens (`--shell=fish`).
+- **Static choice provider** — `config set KEY <TAB>` suggests `true`/`false`.
+
+### Fixed
+
+- **Fish completions showed invalid/stale choices** — the hand-written `dot-man.fish` listed missing commands (`backup`, `tag`, `template`, `profile`, `doctor`, ...), treated navigate options as subcommands, and kept deprecated `switch` prominent. It is now a tiny delegating script calling `dot-man --complete fish` on every TAB (wifi-tracker style), so completions can never go stale.
+- **Unformatted fish output** — the old script's naive `string split ","` broke on help text containing commas and dropped descriptions. Tab-separated engine output renders descriptions natively in fish.
+
+### Tests
+
+- 37 new tests in `tests/test_completion_engine.py` (registry priority, root/subcommand listing, static choices, defaults display, alias labeling, eq-form values, dynamic git-backed callbacks, request parsing, formatting, entry safety). Suite: 1682 passed, coverage 84% (up from 81%).
+
 ## [1.3.0] - 2026-06-27
 
 ### Added

{dotman_git-1.3.0 → dotman_git-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotman-git
-Version: 1.3.0
+Version: 1.4.0
 Summary: Dotfile manager with git-powered branching
 Author-email: Bishoy Ehab <beshoyehabhhmm@gmail.com>
 License: MIT
@@ -18,7 +18,6 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Operating System :: MacOS
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -26,7 +25,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: System :: Systems Administration
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click>=8.0
@@ -64,19 +63,20 @@ Dynamic: license-file
 [![CI](https://github.com/BeshoyEhab/dot-man/actions/workflows/ci.yml/badge.svg)](https://github.com/BeshoyEhab/dot-man/actions/workflows/ci.yml)
 [![PyPI version](https://img.shields.io/pypi/v/dotman-git?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/dotman-git/)
 [![PyPI downloads](https://img.shields.io/pypi/dm/dotman-git?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/dotman-git/)
-[![Python](https://img.shields.io/pypi/pyversions/dotman-git?logo=python&logoColor=white)](https://pypi.org/project/dotman-git/)
+[![Python](https://img.shields.io/pypi/pyversions/dotman-git?logo=python&logoColor=white&v=2)](https://pypi.org/project/dotman-git/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
-[![Coverage](https://img.shields.io/badge/coverage-83%25-green)](https://github.com/BeshoyEhab/dot-man)
+[![Coverage](https://img.shields.io/badge/coverage-84%25-green)](https://github.com/BeshoyEhab/dot-man)
+[![Docs](https://img.shields.io/badge/docs-online-blue)](https://beshoyehab.github.io/dot-man/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/BeshoyEhab/dot-man/pulls)
 
 ---
 
 *Switch your entire development environment in one command.*
 
-[**Install**](#installation) · [**Quick Start**](#quick-start) · [**Commands**](#commands) · [**Config**](#configuration) · [**Docs**](docs/)
+[**Install**](https://github.com/BeshoyEhab/dot-man#installation) · [**Quick Start**](https://github.com/BeshoyEhab/dot-man#quick-start) · [**Commands**](https://github.com/BeshoyEhab/dot-man#commands) · [**Config**](https://github.com/BeshoyEhab/dot-man#configuration) · [**Docs**](https://beshoyehab.github.io/dot-man/)
 
 </div>
 
@@ -125,7 +125,7 @@ Your Machine                  dot-man Repo               Any Machine
 <td>
 
 **Developer**
-- 🐚 Shell completions (bash/zsh/fish)
+- 🐚 Shell completions (bash/zsh/fish) — decorator-driven engine, always in sync with the CLI
 - 🎨 Syntax-highlighted rich diffs
 - 🩺 `doctor` and `verify` diagnostics
 - 📦 PyPI — `pip install dotman-git`
@@ -181,7 +181,6 @@ dot-man add ~/.config/nvim
 
 # 3. Create a "work" profile (branch)
 dot-man navigate work
-# btw it was "switch" instead of "navigate" untill Bishoy decided to change it to "navigate" for some silly reasons and push that changes so as community help us to make it "switch" again.
 
 # 4. Edit your work-specific configs, then switch back — changes are saved automatically
 dot-man navigate main
@@ -480,10 +479,10 @@ System variables (`{{HOSTNAME}}`, `{{USER}}`, `{{SHELL}}`, etc.) are auto-popula
 
 | Metric | Value |
 |--------|-------|
-| Version | `1.2.3` |
+| Version | `1.4.0` |
 | Python | `3.10 · 3.11 · 3.12 · 3.13` |
 | Platforms | Linux, macOS |
-| Test Coverage | 81% (1526 tests) |
+| Test Coverage | 84% (1682 tests) |
 | Commands | 30+ |
 | PyPI | [`dotman-git`](https://pypi.org/project/dotman-git/) |
 

{dotman_git-1.3.0 → dotman_git-1.4.0}/README.md

@@ -7,19 +7,20 @@
 [![CI](https://github.com/BeshoyEhab/dot-man/actions/workflows/ci.yml/badge.svg)](https://github.com/BeshoyEhab/dot-man/actions/workflows/ci.yml)
 [![PyPI version](https://img.shields.io/pypi/v/dotman-git?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/dotman-git/)
 [![PyPI downloads](https://img.shields.io/pypi/dm/dotman-git?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/dotman-git/)
-[![Python](https://img.shields.io/pypi/pyversions/dotman-git?logo=python&logoColor=white)](https://pypi.org/project/dotman-git/)
+[![Python](https://img.shields.io/pypi/pyversions/dotman-git?logo=python&logoColor=white&v=2)](https://pypi.org/project/dotman-git/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
-[![Coverage](https://img.shields.io/badge/coverage-83%25-green)](https://github.com/BeshoyEhab/dot-man)
+[![Coverage](https://img.shields.io/badge/coverage-84%25-green)](https://github.com/BeshoyEhab/dot-man)
+[![Docs](https://img.shields.io/badge/docs-online-blue)](https://beshoyehab.github.io/dot-man/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/BeshoyEhab/dot-man/pulls)
 
 ---
 
 *Switch your entire development environment in one command.*
 
-[**Install**](#installation) · [**Quick Start**](#quick-start) · [**Commands**](#commands) · [**Config**](#configuration) · [**Docs**](docs/)
+[**Install**](https://github.com/BeshoyEhab/dot-man#installation) · [**Quick Start**](https://github.com/BeshoyEhab/dot-man#quick-start) · [**Commands**](https://github.com/BeshoyEhab/dot-man#commands) · [**Config**](https://github.com/BeshoyEhab/dot-man#configuration) · [**Docs**](https://beshoyehab.github.io/dot-man/)
 
 </div>
 
@@ -68,7 +69,7 @@ Your Machine                  dot-man Repo               Any Machine
 <td>
 
 **Developer**
-- 🐚 Shell completions (bash/zsh/fish)
+- 🐚 Shell completions (bash/zsh/fish) — decorator-driven engine, always in sync with the CLI
 - 🎨 Syntax-highlighted rich diffs
 - 🩺 `doctor` and `verify` diagnostics
 - 📦 PyPI — `pip install dotman-git`
@@ -124,7 +125,6 @@ dot-man add ~/.config/nvim
 
 # 3. Create a "work" profile (branch)
 dot-man navigate work
-# btw it was "switch" instead of "navigate" untill Bishoy decided to change it to "navigate" for some silly reasons and push that changes so as community help us to make it "switch" again.
 
 # 4. Edit your work-specific configs, then switch back — changes are saved automatically
 dot-man navigate main
@@ -423,10 +423,10 @@ System variables (`{{HOSTNAME}}`, `{{USER}}`, `{{SHELL}}`, etc.) are auto-popula
 
 | Metric | Value |
 |--------|-------|
-| Version | `1.2.3` |
+| Version | `1.4.0` |
 | Python | `3.10 · 3.11 · 3.12 · 3.13` |
 | Platforms | Linux, macOS |
-| Test Coverage | 81% (1526 tests) |
+| Test Coverage | 84% (1682 tests) |
 | Commands | 30+ |
 | PyPI | [`dotman-git`](https://pypi.org/project/dotman-git/) |
 

{dotman_git-1.3.0 → dotman_git-1.4.0}/dot_man/__init__.py

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

{dotman_git-1.3.0 → dotman_git-1.4.0}/dot_man/cli/__init__.py

@@ -4,7 +4,7 @@ This package provides the CLI entry point for dot-man.
 It exposes the modular CLI implementation.
 """
 
-from . import discover_cmd, encrypt_cmd, export_cmd, import_cmd
+from . import bootstrap_cmd, discover_cmd, encrypt_cmd, export_cmd, import_cmd
 from .add_cmd import add
 from .audit_cmd import audit
 from .backup_cmd import backup
@@ -35,19 +35,21 @@ from .config_cmd import config
 from .deploy_cmd import deploy
 from .doctor_cmd import doctor
 from .edit_cmd import edit
+from .hooks_cmd import hooks
 
 # 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 .navigate_cmd import 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 .rollback_cmd import rollback
+from .save_cmd import save
 from .show_cmd import show
 from .status_cmd import status
 from .switch_cmd import switch
@@ -96,6 +98,7 @@ __all__ = [
     "config",
     "revert",
     "restore",
+    "save",
     "clean",
     "doctor",
     "verify",
@@ -112,6 +115,7 @@ __all__ = [
     "export_cmd",
     "encrypt_cmd",
     "discover_cmd",
+    "bootstrap_cmd",
     "completions",
     "watch",
     "rollback",

dotman_git-1.4.0/dot_man/cli/bootstrap_cmd.py

@@ -0,0 +1,240 @@
+"""Bootstrap command for dot-man — install packages via system package managers."""
+
+import logging
+import shutil
+import subprocess
+
+import click
+
+from .. import ui
+from .common import require_init, success, warn
+from .interface import cli as main
+
+# Package manager detection: command → (install_cmd, update_cmd)
+PACKAGE_MANAGERS = {
+    "brew": {
+        "install": "brew install {package}",
+        "update": "brew update",
+        "detect": "brew",
+    },
+    "apt": {
+        "install": "sudo apt-get install -y {package}",
+        "update": "sudo apt-get update",
+        "detect": "apt-get",
+    },
+    "dnf": {
+        "install": "sudo dnf install -y {package}",
+        "update": "sudo dnf check-update",
+        "detect": "dnf",
+    },
+    "pacman": {
+        "install": "sudo pacman -S --noconfirm {package}",
+        "update": "sudo pacman -Sy",
+        "detect": "pacman",
+    },
+    "zypper": {
+        "install": "sudo zypper install -y {package}",
+        "update": "sudo zypper refresh",
+        "detect": "zypper",
+    },
+    "nix-env": {
+        "install": "nix-env -iA nixpkgs.{package}",
+        "update": "nix-channel --update",
+        "detect": "nix-env",
+    },
+    "xbps-install": {
+        "install": "sudo xbps-install -y {package}",
+        "update": "sudo xbps-install -Su",
+        "detect": "xbps-install",
+    },
+    "pkg": {
+        "install": "pkg install -y {package}",
+        "update": "pkg update",
+        "detect": "pkg",
+    },
+}
+
+
+def _detect_package_manager() -> str | None:
+    """Detect the available package manager on this system."""
+    import platform
+
+    os_name = platform.system().lower()
+
+    # Preferred order by OS
+    if os_name == "darwin":
+        preferred = ["brew"]
+    elif os_name == "linux":
+        preferred = ["apt", "dnf", "pacman", "zypper", "xbps-install", "nix-env"]
+    elif os_name == "freebsd":
+        preferred = ["pkg"]
+    else:
+        preferred = list(PACKAGE_MANAGERS.keys())
+
+    for pm in preferred:
+        if shutil.which(PACKAGE_MANAGERS[pm]["detect"]):
+            return pm
+
+    return None
+
+
+def _load_bootstrap_packages() -> dict[str, list[str]]:
+    """Load packages from dot-man config or bootstrap.toml."""
+    try:
+        from ..config import DotManConfig
+
+        config = DotManConfig()
+        config.load()
+
+        # Check for [bootstrap] section in config
+        bootstrap = config._data.get("bootstrap", {})
+        if bootstrap:
+            packages = {}
+            # Support both flat list and grouped format
+            if isinstance(bootstrap, dict):
+                for key, value in bootstrap.items():
+                    if key == "packages" and isinstance(value, list):
+                        packages["default"] = value
+                    elif isinstance(value, list):
+                        packages[key] = value
+            return packages
+
+    except Exception as e:
+        logging.debug(f"Failed to load bootstrap config: {e}")
+
+    return {}
+
+
+def _run_with_pm(pm: str, command_template: str, package: str) -> bool:
+    """Run a package manager command. Returns True on success."""
+    cmd = command_template.format(package=package)
+    ui.console.print(f"  [cyan]$ {cmd}[/cyan]")
+    try:
+        result = subprocess.run(
+            cmd, shell=True, capture_output=True, text=True, timeout=300
+        )
+        if result.returncode == 0:
+            return True
+        else:
+            warn(f"Failed to install {package} (exit code {result.returncode})")
+            if result.stderr:
+                for line in result.stderr.splitlines()[:3]:
+                    ui.console.print(f"    [dim]{line}[/dim]")
+            return False
+    except subprocess.TimeoutExpired:
+        warn(f"Timeout installing {package}")
+        return False
+    except Exception as e:
+        warn(f"Error installing {package}: {e}")
+        return False
+
+
+@main.command("bootstrap")
+@click.option(
+    "--list",
+    "list_only",
+    is_flag=True,
+    help="List packages that would be installed without installing",
+)
+@click.option("--pm", help="Package manager to use (auto-detected if not specified)")
+@click.option("--update", is_flag=True, help="Update package manager first")
+@click.argument("packages", nargs=-1)
+@require_init
+def bootstrap(list_only: bool, pm: str | None, update: bool, packages: tuple[str, ...]):
+    """Install system packages via package managers.
+
+    Detects your system package manager (brew, apt, dnf, pacman, etc.)
+    and installs the specified packages. Packages can also be defined
+    in your dot-man config under [bootstrap].
+
+    Examples:
+        # Install specific packages
+        dot-man bootstrap neovim tmux git
+
+        # List what would be installed from config
+        dot-man bootstrap --list
+
+        # Use a specific package manager
+        dot-man bootstrap --pm brew neovim
+
+        # Update package manager first
+        dot-man bootstrap --update neovim
+    """
+    # Detect package manager
+    if not pm:
+        pm = _detect_package_manager()
+        if not pm:
+            ui.console.print("[red]No supported package manager found.[/red]")
+            ui.console.print(
+                "Supported: brew, apt, dnf, pacman, zypper, nix-env, xbps-install, pkg"
+            )
+            ui.console.print("Use --pm to specify one manually.")
+            raise SystemExit(1)
+
+    if pm not in PACKAGE_MANAGERS:
+        ui.console.print(f"[red]Unknown package manager: {pm}[/red]")
+        raise SystemExit(1)
+
+    pm_info = PACKAGE_MANAGERS[pm]
+    ui.console.print(f"[bold]Using package manager:[/bold] [cyan]{pm}[/cyan]")
+
+    # Collect packages from args and config
+    all_packages: dict[str, list[str]] = {}
+
+    if packages:
+        all_packages["command-line"] = list(packages)
+
+    config_packages = _load_bootstrap_packages()
+    all_packages.update(config_packages)
+
+    if not all_packages:
+        ui.console.print("[yellow]No packages specified.[/yellow]")
+        ui.console.print("Usage: dot-man bootstrap <package1> <package2> ...")
+        ui.console.print("Or add [bootstrap] section to your dot-man.toml:")
+        ui.console.print('  [bootstrap]\n  packages = ["neovim", "tmux", "git"]')
+        return
+
+    # List mode
+    if list_only:
+        ui.console.print()
+        ui.console.print("[bold]Packages to install:[/bold]")
+        for group, pkgs in all_packages.items():
+            ui.console.print(f"  [cyan]{group}:[/cyan]")
+            for pkg in pkgs:
+                ui.console.print(f"    • {pkg}")
+        ui.console.print()
+        total = sum(len(pkgs) for pkgs in all_packages.values())
+        ui.console.print(f"  [dim]{total} package(s) total[/dim]")
+        return
+
+    # Update package manager if requested
+    if update:
+        ui.console.print()
+        ui.console.print("[bold]Updating package manager...[/bold]")
+        _run_with_pm(pm, pm_info["update"], "")
+
+    # Install packages
+    installed = 0
+    failed = 0
+
+    for group, pkgs in all_packages.items():
+        ui.console.print()
+        ui.console.print(f"[bold]Installing {group}:[/bold]")
+        for pkg in pkgs:
+            ui.console.print(f"\n[bold]→ {pkg}[/bold]")
+            result = _run_with_pm(pm, pm_info["install"], pkg)
+            if result:
+                installed += 1
+            else:
+                failed += 1
+
+    # Summary
+    ui.console.print()
+    ui.console.print("[bold]Bootstrap complete:[/bold]")
+    ui.console.print(f"  [green]✓ {installed} installed[/green]")
+    if failed:
+        ui.console.print(f"  [red]✗ {failed} failed[/red]")
+    ui.console.print()
+
+    if installed > 0:
+        success(f"Installed {installed} package(s) via {pm}")

{dotman_git-1.3.0 → dotman_git-1.4.0}/dot_man/cli/common.py

@@ -111,6 +111,28 @@ class DotManGroup(click.Group):
         ctx.exit(2)
 
 
+def sync_shared_sections(ops) -> None:
+    """Propagate ``shared = true`` sections to non-overriding branches.
+
+    Called after a commit was created on the current branch. Failures
+    are reported but never abort the surrounding command.
+    """
+    try:
+        from ..shared_sync import SharedSectionSync
+
+        report = SharedSectionSync(ops).sync()
+        if not report.shared_sections:
+            return
+        for branch, sections in report.propagated.items():
+            ui.console.print(
+                f"  [dim]↔ shared → '{branch}': {', '.join(sections)}[/dim]"
+            )
+        for branch, reason in report.errors.items():
+            warn(f"Shared-section sync failed for '{branch}': {reason}")
+    except Exception as e:
+        logging.debug("Shared-section sync skipped: %s", e)
+
+
 def require_init(func):
     """Decorator to require initialization before running command."""