machineconfig 6.82__py3-none-any.whl → 8.51__py3-none-any.whl

machineconfig/scripts/python/{helpers_repos → helpers/helpers_repos}/cloud_repo_sync.py

@@ -1,28 +1,68 @@
-import git
-from rich.console import Console
-from rich.panel import Panel
-import typer
 
-from machineconfig.utils.path_extended import PathExtended
-from machineconfig.utils.terminal import Response
-from machineconfig.utils.source_of_truth import CONFIG_ROOT, DEFAULTS_PATH
-from machineconfig.utils.code import get_uv_command_executing_python_script
-from pathlib import Path
-import platform
-import subprocess
+
 from typing import Optional, Literal, Annotated
+import typer
+from machineconfig.utils.ssh_utils.abc import MACHINECONFIG_VERSION
 
 
-console = Console()
+def get_tmp_file():
+    from pathlib import Path
+    import platform
+    from machineconfig.utils.accessories import randstr
+    name = randstr(8)
+    if platform.system() == "Windows":
+        suffix = "ps1"
+    else:
+        suffix = "sh"
+    tmp_file = Path.home().joinpath(f"tmp_results/tmp_files/{name}.{suffix}")
+    tmp_file.parent.mkdir(parents=True, exist_ok=True)
+    return tmp_file
 
 
 def main(
     cloud: Annotated[Optional[str], typer.Option(..., "--cloud", "-c", help="Cloud storage profile name. If not provided, uses default from config.")] = None,
     repo: Annotated[Optional[str], typer.Option(..., "--repo", "-r", help="Path to the local repository. Defaults to current working directory.")] = None,
     message: Annotated[Optional[str], typer.Option(..., "--message", "-m", help="Commit message for local changes.")] = None,
-    on_conflict: Annotated[Literal["ask", "push-local-merge", "overwrite-local", "stop-on-conflict", "remove-rclone-conflict"], typer.Option(..., "--on-conflict", "-oc", help="Action to take on merge conflict. Default is 'ask'.")] = "ask",
+    on_conflict: Annotated[Literal["ask", "a",
+                                   "push-local-merge", "p",
+                                   "overwrite-local", "o",
+                                   "stop-on-conflict", "s",
+                                   "remove-rclone-conflict", "r"
+                                   ], typer.Option(..., "--on-conflict", "-o", help="Action to take on merge conflict. Default is 'ask'.")] = "ask",
     pwd: Annotated[Optional[str], typer.Option(..., "--password", help="Password for encryption/decryption of the remote repository.")] = None,
 ):
+    on_conflict_mapper: dict[str, Literal["ask", "push-local-merge", "overwrite-local", "stop-on-conflict", "remove-rclone-conflict"]] = {
+        "a": "ask",
+        "ask": "ask",
+        "p": "push-local-merge",
+        "push-local-merge": "push-local-merge",
+        "o": "overwrite-local",
+        "overwrite-local": "overwrite-local",
+        "s": "stop-on-conflict",
+        "stop-on-conflict": "stop-on-conflict",
+        "r": "remove-rclone-conflict",
+        "remove-rclone-conflict": "remove-rclone-conflict",
+    }
+    on_conflict = on_conflict_mapper[on_conflict]
+    import platform
+    import git
+    from rich.console import Console
+    from rich.panel import Panel
+
+    from machineconfig.utils.path_extended import PathExtended
+    from machineconfig.utils.terminal import Response
+    from machineconfig.utils.source_of_truth import CONFIG_ROOT, DEFAULTS_PATH
+    from machineconfig.utils.code import get_uv_command_executing_python_script
+    from pathlib import Path
+    import subprocess
+    console = Console()
+
+    def _bash_single_quote(val: str) -> str:
+        return "'" + val.replace("'", "'\"'\"'") + "'"
+
+    def _ps_single_quote(val: str) -> str:
+        return "'" + val.replace("'", "''") + "'"
+
     if cloud is None:
         try:
             from machineconfig.utils.io import read_ini
@@ -35,10 +75,17 @@ def main(
     else:
         cloud_resolved = cloud
     repo_local_root = PathExtended.cwd() if repo is None else PathExtended(repo).expanduser().absolute()
-    repo_local_obj = git.Repo(repo_local_root, search_parent_directories=True)
+    try:
+        repo_local_obj = git.Repo(repo_local_root, search_parent_directories=True)
+    except git.InvalidGitRepositoryError:
+        msg = typer.style("Error: ", fg=typer.colors.RED) + f"The specified path '{repo_local_root}' is not a valid git repository."
+        typer.echo(msg)
+        typer.Exit(code=1)
+        return ""
     repo_local_root = PathExtended(repo_local_obj.working_dir)  # cwd might have been in a sub directory of repo_root, so its better to redefine it.
+    local_relative_home = PathExtended(repo_local_root.expanduser().absolute().relative_to(Path.home()))
     PathExtended(CONFIG_ROOT).joinpath("remote").mkdir(parents=True, exist_ok=True)
-    repo_remote_root = PathExtended(CONFIG_ROOT).joinpath("remote", repo_local_root.rel2home())
+    repo_remote_root = PathExtended(CONFIG_ROOT).joinpath("remote", local_relative_home)
     repo_remote_root.delete(sure=True)
     try:
         console.print(Panel("📥 DOWNLOADING REMOTE REPOSITORY", title_align="left", border_style="blue"))
@@ -55,43 +102,89 @@ def main(
     if repo_remote_obj.is_dirty():
         console.print(Panel(f"⚠️  WARNING: REMOTE REPOSITORY IS DIRTY\nLocation: {repo_remote_root}\nPlease commit or stash changes before proceeding.", title="Warning", border_style="yellow"))
 
-    script = f"""
+    message_resolved = "sync" if message is None or message.strip() == "" else message
+
+    repo_local_root_str = str(repo_local_root)
+    repo_remote_root_str = str(repo_remote_root)
+
+    script_bash = f"""
 echo ""
-echo 'echo -e "\\033[1;34m═════ COMMITTING LOCAL CHANGES ═════\\033[0m"'
-cd {repo_local_root}
+echo -e "\\033[1;34m═════ COMMITTING LOCAL CHANGES ═════\\033[0m"
+cd {_bash_single_quote(repo_local_root_str)}
 git status
-git add .
-git commit -am "{message}"
+git add -A
+if git diff --cached --quiet; then
+  echo "-> No staged changes to commit."
+else
+  git commit -m {_bash_single_quote(message_resolved)} || true
+fi
 echo ""
 echo ""
-echo 'echo -e "\\033[1;34m═════ PULLING LATEST FROM REMOTE ═════\\033[0m"'
-cd {repo_local_root}
-echo '-> Trying to removing originEnc remote from local repo if it exists.'
-# git remote remove originEnc
+echo -e "\\033[1;34m═════ PULLING LATEST FROM REMOTE ═════\\033[0m"
+cd {_bash_single_quote(repo_local_root_str)}
+echo "-> Trying to removing originEnc remote from local repo if it exists."
 git remote remove originEnc 2>/dev/null || true
-echo '-> Adding originEnc remote to local repo'
-git remote add originEnc {repo_remote_root}
-echo '-> Fetching originEnc remote.'
+echo "-> Adding originEnc remote to local repo"
+git remote add originEnc {_bash_single_quote(repo_remote_root_str)}
+echo "-> Fetching originEnc remote."
 git pull originEnc master
 
 """
 
+    script_powershell = f"""
+Write-Host ""
+Write-Host "═════ COMMITTING LOCAL CHANGES ═════" -ForegroundColor Blue
+Set-Location -LiteralPath {_ps_single_quote(repo_local_root_str)}
+git status
+git add -A
+git diff --cached --quiet
+if ($LASTEXITCODE -eq 0) {{
+    Write-Host "-> No staged changes to commit."
+}} else {{
+    git commit -m {_ps_single_quote(message_resolved)}
+    if ($LASTEXITCODE -ne 0) {{
+        Write-Host "-> Commit skipped/failed (continuing)."
+    }}
+}}
+
+Write-Host ""
+Write-Host ""
+Write-Host "═════ PULLING LATEST FROM REMOTE ═════" -ForegroundColor Blue
+Set-Location -LiteralPath {_ps_single_quote(repo_local_root_str)}
+Write-Host "-> Trying to remove originEnc remote from local repo if it exists."
+git remote remove originEnc 2>$null
+Write-Host "-> Adding originEnc remote to local repo"
+git remote add originEnc {_ps_single_quote(repo_remote_root_str)}
+Write-Host "-> Fetching originEnc remote."
+git pull originEnc master
+exit $LASTEXITCODE
+"""
+
+    script = script_powershell if platform.system() == "Windows" else script_bash
+
     if Path.home().joinpath("code/machineconfig").exists():
         uv_project_dir = f"""{str(Path.home().joinpath("code/machineconfig"))}"""
         uv_with = None
     else:
-        uv_with = ["machineconfig>=6.81"]
+        uv_with = [MACHINECONFIG_VERSION]
         uv_project_dir = None
 
-    import tempfile
-    shell_path = Path(tempfile.mkstemp(suffix=".ps1" if platform.system() == "Windows" else ".sh")[1])
+    shell_path = get_tmp_file()
     shell_path.write_text(script, encoding="utf-8")
-
-    command = f". {shell_path}"
     if platform.system() == "Windows":
-        completed = subprocess.run(["powershell", "-Command", command], capture_output=True, check=False, text=True)
+        completed = subprocess.run(
+            ["powershell", "-ExecutionPolicy", "Bypass", "-File", str(shell_path)],
+            capture_output=True,
+            check=False,
+            text=True,
+        )
     else:
-        completed = subprocess.run(command, shell=True, capture_output=True, check=False, text=True)
+        completed = subprocess.run(
+            ["bash", str(shell_path)],
+            capture_output=True,
+            check=False,
+            text=True,
+        )
     res = Response.from_completed_process(completed).capture().print()
 
     if res.is_successful(strict_err=True, strict_returcode=True):
@@ -109,46 +202,64 @@ git pull originEnc master
         option1 = "Delete remote copy and push local:"
         from machineconfig.utils.meta import lambda_to_python_script
         def func2(remote_repo: str, local_repo: str, cloud: str):
-            from machineconfig.scripts.python.helpers_repos.sync import delete_remote_repo_copy_and_push_local
+            from machineconfig.scripts.python.helpers.helpers_repos.sync import delete_remote_repo_copy_and_push_local
             delete_remote_repo_copy_and_push_local(remote_repo=remote_repo, local_repo=local_repo, cloud=cloud)
-        program_1_py = lambda_to_python_script(lambda: func2(remote_repo=str(repo_remote_root), local_repo=str(repo_local_root), cloud=str(cloud_resolved)), in_global=True, import_module=False)
+        program_1_py = lambda_to_python_script(lambda: func2(remote_repo=str(repo_remote_root), local_repo=str(repo_local_root), cloud=str(cloud_resolved)),
+                                                        in_global=True, import_module=False)
         program1, _pyfile1 = get_uv_command_executing_python_script(python_script=program_1_py, uv_with=uv_with, uv_project_dir=uv_project_dir)
         # ================================================================================
+
         option2 = "Delete local repo and replace it with remote copy:"
-        program_2 = f"""
-rm -rfd {repo_local_root}
-mv {repo_remote_root} {repo_local_root}
-"""
+        if platform.system() == "Windows":
+            program_2 = f"""
+Remove-Item -LiteralPath {_ps_single_quote(repo_local_root_str)} -Recurse -Force -ErrorAction SilentlyContinue
+Move-Item -LiteralPath {_ps_single_quote(repo_remote_root_str)} -Destination {_ps_single_quote(repo_local_root_str)} -Force
+    """
+        else:
+            program_2 = f"""
+rm -rfd {_bash_single_quote(repo_local_root_str)}
+mv {_bash_single_quote(repo_remote_root_str)} {_bash_single_quote(repo_local_root_str)}
+    """
         if platform.system() in ["Linux", "Darwin"]:
             program_2 += """
 sudo chmod 600 $HOME/.ssh/*
 sudo chmod 700 $HOME/.ssh
 sudo chmod +x $HOME/dotfiles/scripts/linux -R
 """
-        import tempfile
-        shell_file_2 = Path(tempfile.mkstemp(suffix=".ps1" if platform.system() == "Windows" else ".sh")[1])
+        shell_file_2 = get_tmp_file()
         shell_file_2.write_text(program_2, encoding="utf-8")
 
         # ================================================================================
         option3 = "Inspect repos:"
         def func(repo_local_root: str, repo_remote_root: str):
-            from machineconfig.scripts.python.helpers_repos.sync import inspect_repos
+            from machineconfig.scripts.python.helpers.helpers_repos.sync import inspect_repos
             inspect_repos(repo_local_root=repo_local_root, repo_remote_root=repo_remote_root)
         # program_3_py = function_to_script(func=func, call_with_kwargs={"repo_local_root": str(repo_local_root), "repo_remote_root": str(repo_remote_root)})
         # shell_file_3 = get_shell_file_executing_python_script(python_script=program_3_py, ve_path=None, executable=executable)
-        program_3_py = lambda_to_python_script(lambda: func(repo_local_root=str(repo_local_root), repo_remote_root=str(repo_remote_root)), in_global=True, import_module=False)
+        program_3_py = lambda_to_python_script(lambda: func(repo_local_root=str(repo_local_root), repo_remote_root=str(repo_remote_root)),
+                                                        in_global=True, import_module=False)
         program3, _pyfile3 = get_uv_command_executing_python_script(python_script=program_3_py, uv_with=uv_with, uv_project_dir=uv_project_dir)
         # ================================================================================
 
         option4 = "Remove problematic rclone file from repo and replace with remote:"
-        program_4 = f"""
+        if platform.system() == "Windows":
+            program_4 = f"""
+Remove-Item -LiteralPath "$HOME/dotfiles/creds/rclone/rclone.conf" -Force -ErrorAction SilentlyContinue
+New-Item -ItemType Directory -Path "$HOME/dotfiles/creds/rclone" -Force | Out-Null
+Copy-Item -LiteralPath "$HOME/.config/machineconfig/remote/dotfiles/creds/rclone/rclone.conf" -Destination "$HOME/dotfiles/creds/rclone/rclone.conf" -Force
+Set-Location -LiteralPath "$HOME/dotfiles"
+git commit -am "finished merging"
+{program1}
+    """
+        else:
+            program_4 = f"""
 rm $HOME/dotfiles/creds/rclone/rclone.conf
 cp $HOME/.config/machineconfig/remote/dotfiles/creds/rclone/rclone.conf $HOME/dotfiles/creds/rclone
 cd $HOME/dotfiles
 git commit -am "finished merging"
 {program1}
-"""
-        shell_file_4 = Path(tempfile.mkstemp(suffix=".ps1" if platform.system() == "Windows" else ".sh")[1])
+    """
+        shell_file_4 = get_tmp_file()
         shell_file_4.write_text(program_4, encoding="utf-8")
         # ================================================================================
 
@@ -186,6 +297,6 @@ git commit -am "finished merging"
             case _:
                 raise ValueError(f"Unknown action: {on_conflict}")
         from machineconfig.utils.code import run_shell_script
-        run_shell_script(script=program_content)
+        run_shell_script(script=program_content, display_script=True, clean_env=False)
     return program_content
 

machineconfig/scripts/python/{helpers_repos → helpers/helpers_repos}/grource.py

@@ -100,7 +100,7 @@ def install_gource_windows(version: Optional[str] = None) -> None:
 
 
 def visualize(
-    repo: Annotated[str, typer.Option("--repo", "-r", help="Path to git repository to visualize")] = Path.cwd().__str__(),
+    repo: Annotated[str, typer.Option("--repo", "-r", help="Path to git repository to visualize")] = ".",
     output_file: Annotated[Optional[Path], typer.Option("--output", "-o", help="Output video file (e.g., output.mp4). If specified, gource will render to video.")] = None,
     resolution: Annotated[str, typer.Option("--resolution", "-res", help="Video resolution (e.g., 1920x1080, 1280x720)")] = "1920x1080",
     seconds_per_day: Annotated[float, typer.Option("--seconds-per-day", "-spd", help="Speed of simulation (lower = faster)")] = 0.1,
@@ -169,7 +169,7 @@ def visualize(
         if platform.system() == "Windows":
             print(f"⚠️  Portable gource not found at {gource_exe}, installing...")
             install_gource_windows()
-            # Check again after installation
+            gource_exe = get_gource_executable()  # Re-fetch path after installation
             if gource_exe.exists():
                 print(f"✅ Gource installed successfully at: {gource_exe}")
                 gource_cmd: str = str(gource_exe)
@@ -177,7 +177,8 @@ def visualize(
                 print("❌ Installation failed, falling back to system gource")
                 raise typer.Exit(1)
         else:
-            raise FileNotFoundError(f"Gource executable not found at {gource_exe}. Please install gource using your package manager.")
+            print(f"❌ Error: Gource executable not found at {gource_exe}. Please install gource using your package manager.")
+            raise typer.Exit(1)
     else:
         gource_cmd = str(gource_exe)
 

machineconfig/scripts/python/{helpers_repos → helpers/helpers_repos}/record.py

@@ -3,7 +3,6 @@ from pathlib import Path
 from machineconfig.utils.schemas.repos.repos_types import GitVersionInfo, RepoRecordDict, RepoRemote
 
 from machineconfig.utils.schemas.repos.repos_types import RepoRecordFile
-from machineconfig.utils.source_of_truth import CONFIG_ROOT
 from machineconfig.utils.io import save_json
 
 from typing import Optional
@@ -12,7 +11,7 @@ from rich import print as pprint
 from rich.progress import Progress, TaskID, SpinnerColumn, TextColumn, BarColumn, TimeElapsedColumn, MofNCompleteColumn
 
 
-def build_tree_structure(repos: list[RepoRecordDict], repos_root: PathExtended) -> str:
+def build_tree_structure(repos: list[RepoRecordDict], repos_root: Path) -> str:
     """Build a tree structure representation of all repositories."""
     if not repos:
         return "No repositories found."
@@ -186,10 +185,18 @@ def record_repos_recursively(repos_root: str, r: bool, progress: Progress | None
     return res
 
 
-def main_record(repos_root: Path):
-    print("\n📝 Recording repositories...")
-    repos_root = PathExtended(repos_root).expanduser().absolute()
+def _resolve_directory(directory: Optional[str]) -> Path:
+    import typer
+    if directory is None:
+        directory = Path.cwd().as_posix()
+        typer.echo(f"📁 Using directory: {directory}")
+    return Path(directory).expanduser().absolute().resolve()
+
 
+def main_record(repos_root_str: Optional[str]) -> Path:
+    print("\n📝 Recording repositories...")
+    repos_root = _resolve_directory(directory=repos_root_str)
+    
     # Count total directories and repositories for accurate progress tracking
     print("🔍 Analyzing directory structure...")
     total_dirs = count_total_directories(str(repos_root), r=True)
@@ -222,7 +229,7 @@ def main_record(repos_root: Path):
     if repos_with_no_remotes:
         print(f"\n⚠️  WARNING: {len(repos_with_no_remotes)} repositories have no remotes configured:")
         for repo in repos_with_no_remotes:
-            repo_path = PathExtended(repo["parentDir"]).joinpath(repo["name"])
+            repo_path = Path(repo["parentDir"]).joinpath(repo["name"])
             print(f"   • {repo['name']} ({repo_path})")
         print("   These repositories may be local-only or have configuration issues.")
     else:
@@ -231,7 +238,7 @@ def main_record(repos_root: Path):
     if dirty_repos:
         print(f"\n⚠️  WARNING: {len(dirty_repos)} repositories have uncommitted changes:")
         for repo in dirty_repos:
-            repo_path = PathExtended(repo["parentDir"]).joinpath(repo["name"])
+            repo_path = Path(repo["parentDir"]).joinpath(repo["name"])
             print(f"   • {repo['name']} ({repo_path}) [branch: {repo['currentBranch']}]")
         print("   These repositories have uncommitted changes that may need attention.")
     else:
@@ -239,11 +246,25 @@ def main_record(repos_root: Path):
 
     # Display repository tree structure
     print("\n🌳 Repository Tree Structure:")
-    tree_structure = build_tree_structure(repo_records, repos_root)
+    tree_structure = build_tree_structure(repos=repo_records, repos_root=repos_root)
     print(tree_structure)
 
-    save_path = CONFIG_ROOT.joinpath("repos").joinpath(repos_root.rel2home()).joinpath("repos.json")
-    save_json(obj=res, path=save_path, indent=4)
-    pprint(f"📁 Result saved at {PathExtended(save_path)}")
+    spec_path_default = Path(repos_root).expanduser().absolute().joinpath("repos.json")
+    from machineconfig.scripts.python.helpers.helpers_devops.cli_config_dotfile import get_backup_path, record_mapping
+    spec_path_self_managed = get_backup_path(
+        orig_path=spec_path_default,
+        sensitivity="private",
+        destination=None,
+        shared=False,
+    )
+    save_json(obj=res, path=spec_path_self_managed, indent=4)
+    pprint(f"📁 Result saved at {PathExtended(spec_path_self_managed)}")
+
+    # record_mapping(
+    #     orig_path=spec_path_default,
+
+    # )
+    _ = record_mapping
+
     print(">>>>>>>>> Finished Recording")
-    return save_path
+    return spec_path_self_managed

machineconfig/scripts/python/helpers/helpers_repos/repo_analyzer_1.py

@@ -0,0 +1,160 @@
+
+
+import subprocess
+
+from git import Repo
+from collections import defaultdict
+from datetime import datetime, date
+from typing import Any, Dict, List, Optional, Union
+from pathlib import Path
+
+
+
+def count_historical_line_edits(repo_path: str) -> int:
+
+    repo = Repo(repo_path)
+    last_commit = next(repo.iter_commits())
+    total_lines, total_files = count_python_lines(last_commit)
+    print(f"Total lines of Python code in latest commit ({last_commit.hexsha[:8]}): {total_lines} across {total_files} files")
+
+    gitcs_viz(repo_path=repo_path, pull_full_history=True)
+
+    file_line_counts: "Dict[str, int]" = defaultdict(int)
+    total_commits: int = sum(1 for _ in repo.iter_commits())
+    print(f"Total commits to process: {total_commits}")
+    for i, commit in enumerate(repo.iter_commits(), 1):
+        if i % 100 == 0 or i == total_commits:
+            print(f"Processing commit {i}/{total_commits} ({i / total_commits:.1%})")
+        try:
+            # Handle initial commits that have no parents
+            if not commit.parents:
+                # For initial commit, count all lines in Python files
+                for file in commit.stats.files:
+                    if str(file).endswith(".py"):
+                        file_line_counts[str(file)] += commit.stats.files[file]["insertions"]
+            else:
+                # For commits with parents, use stats
+                for file in commit.stats.files:
+                    if str(file).endswith(".py"):
+                        file_line_counts[str(file)] += commit.stats.files[file]["insertions"]
+        except Exception:
+            # If stats fail (e.g., corrupted parent), skip this commit
+            print(f"Warning: Could not get stats for commit {commit.hexsha[:8]}, skipping")
+            continue
+
+    print(f"\nProcessed files: {len(file_line_counts)}")
+    res = sum(file_line_counts.values())
+    print(f"Total historical lines of Python code: {res}")
+    return res
+
+
+
+
+def count_lines_changed_in_commit(commit: "Any") -> int:
+    _total_lines = 0
+    for _file in commit.stats.files:
+        if str(_file).endswith(".py"):
+            _blob = commit.tree / _file
+            _total_lines += len(_blob.data_stream.read().decode("utf-8").splitlines())
+    return _total_lines
+def count_python_lines(commit: "Any") -> tuple[int, int]:
+    """Count total lines in Python files for a specific commit"""
+    total_lines = 0
+    total_files = 0
+    try:
+        for blob in commit.tree.traverse():
+            if blob.path.endswith(".py"):
+                try:
+                    content = blob.data_stream.read().decode("utf-8")
+                    total_lines += len(content.splitlines())
+                    total_files += 1
+                except Exception as _e:
+                    continue
+    except Exception as e:
+        print(f"Error traversing commit {commit.hexsha[:8]}: {e}")
+        pass
+    return total_lines, total_files
+
+
+def get_default_branch(repo: Repo) -> str:
+    """Get the default branch name of the repository"""
+    try:
+        _ = repo.refs["main"]
+        return "main"  # First try 'main'
+    except IndexError:
+        try:
+            _ = repo.refs["master"]
+            return "master"  # Then try 'master'
+        except IndexError:
+            return repo.head.reference.name  # If neither exists, get the branch the HEAD is pointing to
+
+
+
+def gitcs_viz(repo_path: Union[str, Path], email: Optional[str] = None, pull_full_history: bool = False) -> None:
+    """Invoke the gitcs CLI across 6-month windows covering the repo history.
+    
+    Args:
+        repo_path: Path to the git repository
+        email: Optional email filter for gitcs
+        pull_full_history: If True, unshallow the repo to fetch full history (useful for shallow clones)
+    """
+    from machineconfig.utils.installer_utils.installer_cli import install_if_missing
+    install_if_missing("gitcs")
+
+    repo_path = Path(repo_path).expanduser().resolve()
+    repo = Repo(repo_path)
+    
+    # Check if repo is shallow and optionally unshallow it
+    if pull_full_history:
+        shallow_file = Path(repo.git_dir) / "shallow"
+        if shallow_file.exists():
+            print("🔄 Detected shallow clone. Fetching full history...")
+            try:
+                repo.git.fetch("--unshallow")
+                print("✅ Successfully fetched full history")
+            except Exception as e:
+                print(f"⚠️ Failed to unshallow repository: {e}")
+                print("Continuing with available history...")
+        else:
+            print("ℹ️ Repository already has full history")
+    
+    branch_name = get_default_branch(repo)
+    commits: "List[Any]" = list(repo.iter_commits(branch_name))
+    if not commits:
+        print("⚠️ No commits found; skipping gitcs visualization.")
+        return
+
+    from datetime import timezone
+
+    commit_dates = [datetime.fromtimestamp(commit.committed_date, tz=timezone.utc).date() for commit in commits]
+    min_year = min(commit_dates).year
+    max_year = max(commit_dates).year
+
+    print(f"📆 gitcs windows: {min_year}-01-01 → {max_year}-12-31 (fixed half-year slices)")
+
+    chunk_idx = 1
+    for year in range(min_year, max_year + 1):
+        windows = [(date(year, 1, 1), date(year, 6, 30)), (date(year, 7, 1), date(year, 12, 31))]
+        for chunk_start, chunk_end in windows:
+            cmd = ["gitcs", "--since", chunk_start.isoformat(), "--until", chunk_end.isoformat()]
+            if email:
+                cmd.extend(["--email", email])
+
+            print(f"\n===== gitcs chunk {chunk_idx}: {chunk_start.isoformat()} → {chunk_end.isoformat()} =====")
+            try:
+                completed = subprocess.run(cmd, cwd=str(repo_path), capture_output=True, text=True, input=f"{repo_path}\n")
+            except FileNotFoundError:
+                print("❌ gitcs CLI is not available on PATH; aborting visualization.")
+                return
+
+            if completed.stdout.strip():
+                print(completed.stdout.strip())
+            if completed.stderr.strip():
+                print(completed.stderr.strip())
+            if completed.returncode != 0:
+                print(f"⚠️ gitcs exited with code {completed.returncode} for this range.")
+
+            chunk_idx += 1
+
+
+