machineconfig 5.25__py3-none-any.whl → 5.27__py3-none-any.whl

machineconfig/scripts/python/helpers_repos/grource.py

@@ -0,0 +1,341 @@
+"""Gource visualization tool for git repositories."""
+
+from pathlib import Path
+from typing import Annotated, Optional
+import subprocess
+import platform
+import zipfile
+import typer
+
+
+def get_gource_install_dir() -> Path:
+    """Get the installation directory for portable Gource."""
+    if platform.system() == "Windows":
+        appdata = Path.home() / "AppData" / "Local"
+        return appdata / "gource"
+    else:
+        return Path.home() / ".local" / "bin" / "gource"
+
+
+def get_gource_executable() -> Path:
+    """Get the path to the gource executable (inside the extracted directory with DLLs)."""
+    install_dir = get_gource_install_dir()
+    if platform.system() == "Windows":
+        possible_paths = [
+            install_dir / "gource.exe",
+            install_dir / f"gource-{get_default_version()}.win64" / "gource.exe",
+        ]
+        for path in possible_paths:
+            if path.exists():
+                return path
+        return install_dir / f"gource-{get_default_version()}.win64" / "gource.exe"
+    else:
+        return install_dir / "gource"
+
+
+def get_default_version() -> str:
+    """Get the default gource version."""
+    return "0.53"
+
+
+def install_gource_windows(version: Optional[str] = None) -> None:
+    """Install portable Gource on Windows by downloading and extracting the zip archive."""
+    if platform.system() != "Windows":
+        raise OSError(f"This installer is for Windows only. Current OS: {platform.system()}")
+
+    from machineconfig.utils.path_extended import PathExtended
+    from machineconfig.utils.source_of_truth import INSTALL_TMP_DIR
+
+    print("\n" + "=" * 80)
+    print("🚀 GOURCE PORTABLE INSTALLATION 🚀")
+    print("=" * 80 + "\n")
+
+    version_str = version or get_default_version()
+    portable_url = f"https://github.com/acaudwell/Gource/releases/download/gource-{version_str}/gource-{version_str}.win64.zip"
+    install_dir = get_gource_install_dir()
+
+    print(f"📥 Downloading portable Gource from: {portable_url}")
+    downloaded_zip = PathExtended(portable_url).download(folder=INSTALL_TMP_DIR)
+    print(f"✅ Downloaded to: {downloaded_zip}")
+
+    print(f"\n� Extracting to: {install_dir}")
+    install_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        with zipfile.ZipFile(downloaded_zip, 'r') as zip_ref:
+            zip_ref.extractall(install_dir)
+        print(f"✅ Extracted successfully to: {install_dir}")
+        print(f"   (The zip contains gource-{version_str}.win64/ directory with exe and DLL dependencies)")
+    except Exception as e:
+        print(f"❌ Extraction failed with error: {e}")
+        raise
+
+    print("\n🗑️  Cleaning up zip file...")
+    try:
+        downloaded_zip.unlink()
+        print(f"✅ Removed zip file: {downloaded_zip}")
+    except Exception as e:
+        print(f"⚠️  Warning: Could not remove zip file: {e}")
+
+    gource_exe = get_gource_executable()
+    if gource_exe.exists():
+        print(f"\n✅ Gource executable found at: {gource_exe}")
+        dll_dir = gource_exe.parent
+        dll_count = len(list(dll_dir.glob("*.dll")))
+        print(f"   Found {dll_count} DLL dependencies in: {dll_dir}")
+    else:
+        print(f"\n⚠️  Warning: Expected executable not found at: {gource_exe}")
+        print(f"   Contents of {install_dir}:")
+        for item in install_dir.rglob("*"):
+            if item.is_file():
+                print(f"     - {item.relative_to(install_dir)}")
+
+    print("\n" + "=" * 80)
+    print("✅ GOURCE PORTABLE INSTALLATION COMPLETED")
+    print("=" * 80)
+    print(f"\n📌 Gource installed to: {install_dir}")
+    print(f"   Executable: {gource_exe}")
+    print("   All DLL dependencies are kept together in the same directory.")
+    print("   This script will automatically use the portable version.")
+
+
+def visualize(
+    repo: Annotated[str, typer.Option("--repo", "-r", help="Path to git repository to visualize")] = Path.cwd().__str__(),
+    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,
+    auto_skip_seconds: Annotated[float, typer.Option("--auto-skip-seconds", "-as", help="Skip to next entry if nothing happens for X seconds")] = 1.0,
+    title: Annotated[Optional[str], typer.Option("--title", "-t", help="Title for the visualization")] = None,
+    hide_items: Annotated[list[str], typer.Option("--hide", "-h", help="Items to hide: bloom, date, dirnames, files, filenames, mouse, progress, root, tree, users, usernames")] = [],
+    key_items: Annotated[bool, typer.Option("--key", "-k", help="Show file extension key")] = False,
+    fullscreen: Annotated[bool, typer.Option("--fullscreen", "-f", help="Run in fullscreen mode")] = False,
+    viewport: Annotated[Optional[str], typer.Option("--viewport", "-v", help="Camera viewport (e.g., '1000x1000')")] = None,
+    start_date: Annotated[Optional[str], typer.Option("--start-date", help="Start date (YYYY-MM-DD)")] = None,
+    stop_date: Annotated[Optional[str], typer.Option("--stop-date", help="Stop date (YYYY-MM-DD)")] = None,
+    user_image_dir: Annotated[Optional[Path], typer.Option("--user-image-dir", help="Directory with user avatar images")] = None,
+    max_files: Annotated[int, typer.Option("--max-files", help="Maximum number of files to show (0 = no limit)")] = 0,
+    max_file_lag: Annotated[float, typer.Option("--max-file-lag", help="Max time files remain on screen after last change")] = 5.0,
+    file_idle_time: Annotated[int, typer.Option("--file-idle-time", help="Time in seconds files remain idle before being removed")] = 0,
+    framerate: Annotated[int, typer.Option("--framerate", help="Frames per second for video output")] = 60,
+    background_color: Annotated[str, typer.Option("--background-color", help="Background color in hex (e.g., 000000 for black)")] = "000000",
+    font_size: Annotated[int, typer.Option("--font-size", help="Font size")] = 22,
+    camera_mode: Annotated[str, typer.Option("--camera-mode", help="Camera mode: overview or track")] = "overview",
+) -> None:
+    """
+    Visualize git repository history using Gource with reasonable defaults.
+    
+    Examples:
+        # Basic visualization of current directory
+        python grource.py visualize
+        
+        # Visualize specific repository
+        python grource.py visualize --repo-path /path/to/repo
+        
+        # Create video output
+        python grource.py visualize --output output.mp4
+        
+        # Fast visualization with custom title
+        python grource.py visualize --seconds-per-day 0.01 --title "My Project"
+        
+        # Hide specific elements
+        python grource.py visualize --hide filenames --hide date
+        
+        # Custom resolution and viewport
+        python grource.py visualize --resolution 2560x1440 --viewport 1200x1200
+    """
+    print("\n" + "=" * 80)
+    print("🎬 GOURCE VISUALIZATION 🎬")
+    print("=" * 80 + "\n")
+    repo_path: Path = Path(repo).expanduser().resolve()
+    if not repo_path.exists():
+        print(f"❌ Error: Repository path does not exist: {repo_path}")
+        raise typer.Exit(1)
+
+    if not repo_path.joinpath(".git").exists():
+        print(f"❌ Error: Not a git repository: {repo_path}")
+        raise typer.Exit(1)
+
+    print(f"📁 Repository: {repo_path}")
+    print("⚙️  Configuration:")
+    print(f"   - Resolution: {resolution}")
+    print(f"   - Speed: {seconds_per_day} seconds per day")
+    print(f"   - Auto-skip: {auto_skip_seconds} seconds")
+    if output_file:
+        print(f"   - Output: {output_file}")
+    print()
+
+    gource_exe: Path = get_gource_executable()
+    if not gource_exe.exists():
+        if platform.system() == "Windows":
+            print(f"⚠️  Portable gource not found at {gource_exe}, installing...")
+            install_gource_windows()
+            # Check again after installation
+            if gource_exe.exists():
+                print(f"✅ Gource installed successfully at: {gource_exe}")
+                gource_cmd: str = str(gource_exe)
+            else:
+                print("❌ Installation failed, falling back to system gource")
+                gource_cmd = "gource"
+        else:
+            gource_cmd = "gource"
+            print(f"⚠️  Portable gource not found at {gource_exe}, using system gource")
+    else:
+        gource_cmd = str(gource_exe)
+
+    cmd: list[str] = [gource_cmd, str(repo_path)]
+
+    cmd.extend(["--seconds-per-day", str(seconds_per_day)])
+    cmd.extend(["--auto-skip-seconds", str(auto_skip_seconds)])
+
+    if resolution:
+        width, height = resolution.split("x")
+        cmd.extend(["-{}x{}".format(width, height)])
+
+    if title:
+        cmd.extend(["--title", title])
+    elif not title and not output_file:
+        cmd.extend(["--title", repo_path.name])
+
+    for hide_item in hide_items:
+        cmd.extend(["--hide", hide_item])
+
+    if key_items:
+        cmd.append("--key")
+
+    if fullscreen and not output_file:
+        cmd.append("--fullscreen")
+
+    if viewport:
+        cmd.extend(["--viewport", viewport])
+
+    if start_date:
+        cmd.extend(["--start-date", start_date])
+
+    if stop_date:
+        cmd.extend(["--stop-date", stop_date])
+
+    if user_image_dir and user_image_dir.exists():
+        cmd.extend(["--user-image-dir", str(user_image_dir)])
+
+    if max_files > 0:
+        cmd.extend(["--max-files", str(max_files)])
+
+    cmd.extend(["--max-file-lag", str(max_file_lag)])
+
+    if file_idle_time > 0:
+        cmd.extend(["--file-idle-time", str(file_idle_time)])
+
+    cmd.extend(["--background-colour", background_color])
+    cmd.extend(["--font-size", str(font_size)])
+    cmd.extend(["--camera-mode", camera_mode])
+
+    if output_file:
+        cmd.extend(["-r", str(framerate)])
+        if platform.system() == "Windows":
+            cmd.extend(["-o", "-"])
+            ffmpeg_cmd: list[str] = [
+                "ffmpeg",
+                "-y",
+                "-r", str(framerate),
+                "-f", "image2pipe",
+                "-vcodec", "ppm",
+                "-i", "-",
+                "-vcodec", "libx264",
+                "-preset", "medium",
+                "-pix_fmt", "yuv420p",
+                "-crf", "23",
+                str(output_file),
+            ]
+            print("🎥 Rendering video...")
+            print(f"   Command: {' '.join(cmd)} | {' '.join(ffmpeg_cmd)}")
+            print()
+            try:
+                gource_proc: subprocess.Popen[bytes] = subprocess.Popen(cmd, stdout=subprocess.PIPE)
+                ffmpeg_proc: subprocess.Popen[bytes] = subprocess.Popen(ffmpeg_cmd, stdin=gource_proc.stdout)
+                if gource_proc.stdout:
+                    gource_proc.stdout.close()
+                ffmpeg_proc.communicate()
+                print(f"\n✅ Video saved to: {output_file}")
+            except subprocess.CalledProcessError as e:
+                print(f"❌ Error during video rendering: {e}")
+                raise typer.Exit(1)
+            except FileNotFoundError:
+                print("❌ Error: ffmpeg not found. Please install ffmpeg to create video output.")
+                print("   Download from: https://ffmpeg.org/download.html")
+                raise typer.Exit(1)
+        else:
+            cmd.extend(["-o", "-"])
+            ffmpeg_cmd = [
+                "ffmpeg",
+                "-y",
+                "-r", str(framerate),
+                "-f", "image2pipe",
+                "-vcodec", "ppm",
+                "-i", "-",
+                "-vcodec", "libx264",
+                "-preset", "medium",
+                "-pix_fmt", "yuv420p",
+                "-crf", "23",
+                str(output_file),
+            ]
+            print("🎥 Rendering video...")
+            print(f"   Command: {' '.join(cmd)} | {' '.join(ffmpeg_cmd)}")
+            print()
+            try:
+                gource_proc = subprocess.Popen(cmd, stdout=subprocess.PIPE)
+                ffmpeg_proc = subprocess.Popen(ffmpeg_cmd, stdin=gource_proc.stdout)
+                if gource_proc.stdout:
+                    gource_proc.stdout.close()
+                ffmpeg_proc.communicate()
+                print(f"\n✅ Video saved to: {output_file}")
+            except subprocess.CalledProcessError as e:
+                print(f"❌ Error during video rendering: {e}")
+                raise typer.Exit(1)
+            except FileNotFoundError:
+                print("❌ Error: ffmpeg not found. Please install ffmpeg to create video output.")
+                raise typer.Exit(1)
+    else:
+        print("🎬 Launching interactive visualization...")
+        print(f"   Command: {' '.join(cmd)}")
+        print()
+        try:
+            subprocess.run(cmd, check=True)
+        except subprocess.CalledProcessError as e:
+            print(f"❌ Error running gource: {e}")
+            raise typer.Exit(1)
+        except FileNotFoundError:
+            print("❌ Error: gource not found. Please install gource first.")
+            if platform.system() == "Windows":
+                print("   Run: uv run python src/machineconfig/scripts/python/grource.py install")
+            else:
+                print("   For Linux/Mac, use your package manager:")
+                print("     - Ubuntu/Debian: sudo apt install gource")
+                print("     - macOS: brew install gource")
+                print("     - Fedora: sudo dnf install gource")
+            raise typer.Exit(1)
+
+    print("\n" + "=" * 80)
+    print("✅ VISUALIZATION COMPLETED")
+    print("=" * 80)
+
+
+def install(
+    version: Optional[str] = typer.Option("0.53", "--version", "-v", help="Gource version to install"),
+) -> None:
+    """Install portable Gource on Windows (no admin privileges required)."""
+    if platform.system() == "Windows":
+        install_gource_windows(version=version)
+    else:
+        print(f"❌ Portable installer currently supports Windows only. Current OS: {platform.system()}")
+        print("For Linux/Mac, please use your package manager:")
+        print("  - Ubuntu/Debian: sudo apt install gource")
+        print("  - macOS: brew install gource")
+        print("  - Fedora: sudo dnf install gource")
+        raise typer.Exit(1)
+
+
+if __name__ == "__main__":
+    app = typer.Typer(help="Gource visualization tool for git repositories")
+    app.command()(install)
+    app.command()(visualize)
+    app()

machineconfig/scripts/python/interactive.py

@@ -182,7 +182,7 @@ Set-Service -Name sshd -StartupType 'Automatic'"""
         console.print(Panel("💾 [bold bright_cyan]DATA RETRIEVAL[/bold bright_cyan]\n[italic]Backup restoration[/italic]", border_style="bright_cyan"))
         console.print("🔧 Retrieving backup data", style="bold cyan")
         try:
-            from machineconfig.scripts.python.devops_backup_retrieve import main_backup_retrieve
+            from machineconfig.scripts.python.devops_helpers.devops_backup_retrieve import main_backup_retrieve
             main_backup_retrieve(direction="RETRIEVE")
             console.print("✅ Backup data retrieved successfully", style="bold green")
         except Exception as e:

machineconfig/scripts/python/repos.py

@@ -5,128 +5,130 @@ in the event that username@github.com is not mentioned in the remote url.
 
 """
 
-
+from pathlib import Path
 from typing import Annotated, Optional
 import typer
 
 
-
 app = typer.Typer(help="� Manage development repositories", no_args_is_help=True)
 sync_app = typer.Typer(help="� Manage repository specifications and syncing", no_args_is_help=True)
 app.add_typer(sync_app, name="sync", help="� Sync repositories using saved specs")
 
 
-DirectoryArgument = Annotated[
-    Optional[str],
-    typer.Argument(help="📁 Folder containing repos or the specs JSON file to use."),
-]
-RecursiveOption = Annotated[
-    bool,
-    typer.Option("--recursive", "-r", help="🔍 Recurse into nested repositories."),
-]
-NoSyncOption = Annotated[
-    bool,
-    typer.Option("--no-sync", help="🚫 Disable automatic uv sync after pulls."),
-]
-CloudOption = Annotated[
-    Optional[str],
-    typer.Option("--cloud", "-c", help="☁️ Upload to or download from this cloud remote."),
-]
-
+DirectoryArgument = Annotated[Optional[str], typer.Argument(help="📁 Folder containing repos or the specs JSON file to use.")]
+RecursiveOption = Annotated[bool, typer.Option("--recursive", "-r", help="🔍 Recurse into nested repositories.")]
+NoSyncOption = Annotated[bool, typer.Option("--no-sync", help="🚫 Disable automatic uv sync after pulls.")]
+CloudOption = Annotated[Optional[str], typer.Option("--cloud", "-c", help="☁️ Upload to or download from this cloud remote.")]
 
 
 @app.command(no_args_is_help=True)
-def push(directory: DirectoryArgument = None,
-    recursive: RecursiveOption = False,
-    no_sync: NoSyncOption = False,
-) -> None:
+def push(directory: DirectoryArgument = None, recursive: RecursiveOption = False, no_sync: NoSyncOption = False) -> None:
     """🚀 Push changes across repositories."""
-    from machineconfig.scripts.python.repos_helper import git_operations
+    from machineconfig.scripts.python.repos_helpers.repos_helper import git_operations
+
     git_operations(directory, pull=False, commit=False, push=True, recursive=recursive, no_sync=no_sync)
+
+
 @app.command(no_args_is_help=True)
-def pull(
-    directory: DirectoryArgument = None,
-    recursive: RecursiveOption = False,
-    no_sync: NoSyncOption = False,
-) -> None:
+def pull(directory: DirectoryArgument = None, recursive: RecursiveOption = False, no_sync: NoSyncOption = False) -> None:
     """⬇️ Pull changes across repositories."""
-    from machineconfig.scripts.python.repos_helper import git_operations
+    from machineconfig.scripts.python.repos_helpers.repos_helper import git_operations
+
     git_operations(directory, pull=True, commit=False, push=False, recursive=recursive, no_sync=no_sync)
+
+
 @app.command(no_args_is_help=True)
-def commit(
-    directory: DirectoryArgument = None,
-    recursive: RecursiveOption = False,
-    no_sync: NoSyncOption = False,
-) -> None:
+def commit(directory: DirectoryArgument = None, recursive: RecursiveOption = False, no_sync: NoSyncOption = False) -> None:
     """💾 Commit changes across repositories."""
-    from machineconfig.scripts.python.repos_helper import git_operations
+    from machineconfig.scripts.python.repos_helpers.repos_helper import git_operations
+
     git_operations(directory, pull=False, commit=True, push=False, recursive=recursive, no_sync=no_sync)
+
+
 @app.command(no_args_is_help=True)
-def cleanup(
-    directory: DirectoryArgument = None,
-    recursive: RecursiveOption = False,
-    no_sync: NoSyncOption = False,
-) -> None:
+def cleanup(directory: DirectoryArgument = None, recursive: RecursiveOption = False, no_sync: NoSyncOption = False) -> None:
     """🔄 Pull, commit, and push changes across repositories."""
-    from machineconfig.scripts.python.repos_helper import git_operations
+    from machineconfig.scripts.python.repos_helpers.repos_helper import git_operations
+
     git_operations(directory, pull=True, commit=True, push=True, recursive=recursive, no_sync=no_sync)
 
 
 @sync_app.command(no_args_is_help=True)
-def capture(
-    directory: DirectoryArgument = None,
-    cloud: CloudOption = None,
-) -> None:
+def capture(directory: DirectoryArgument = None, cloud: CloudOption = None) -> None:
     """📝 Record repositories into a repos.json specification."""
-    from machineconfig.scripts.python.repos_helper import print_banner, resolve_directory
-    print_banner()
+    from machineconfig.scripts.python.repos_helpers.repos_helper import resolve_directory
     repos_root = resolve_directory(directory)
-    from machineconfig.scripts.python.repos_helper_record import main as record_repos
+    from machineconfig.scripts.python.repos_helpers.repos_helper_record import main as record_repos
+
     save_path = record_repos(repos_root=repos_root)
     from machineconfig.utils.path_extended import PathExtended
+
     if cloud is not None:
         PathExtended(save_path).to_cloud(rel2home=True, cloud=cloud)
+
+
 @sync_app.command(no_args_is_help=True)
-def clone(
-    directory: DirectoryArgument = None,
-    cloud: CloudOption = None,
-) -> None:
+def clone(directory: DirectoryArgument = None, cloud: CloudOption = None) -> None:
     """📥 Clone repositories described by a repos.json specification."""
-    from machineconfig.scripts.python.repos_helper import print_banner, clone_from_specs
-    print_banner()
+    from machineconfig.scripts.python.repos_helpers.repos_helper import clone_from_specs
+
+    
     clone_from_specs(directory, cloud, checkout_branch_flag=False, checkout_commit_flag=False)
 
 
 @sync_app.command(name="checkout-to-commit", no_args_is_help=True)
-def checkout_command(
-    directory: DirectoryArgument = None,
-    cloud: CloudOption = None,
-) -> None:
+def checkout_command(directory: DirectoryArgument = None, cloud: CloudOption = None) -> None:
     """🔀 Check out specific commits listed in the specification."""
-    from machineconfig.scripts.python.repos_helper import print_banner, clone_from_specs
-    print_banner()
+    from machineconfig.scripts.python.repos_helpers.repos_helper import clone_from_specs
+
+    
     clone_from_specs(directory, cloud, checkout_branch_flag=False, checkout_commit_flag=True)
 
 
 @sync_app.command(name="checkout-to-branch", no_args_is_help=True)
-def checkout_to_branch_command(
-    directory: DirectoryArgument = None,
-    cloud: CloudOption = None,
-) -> None:
+def checkout_to_branch_command(directory: DirectoryArgument = None, cloud: CloudOption = None) -> None:
     """🔀 Check out to the main branch defined in the specification."""
-    from machineconfig.scripts.python.repos_helper import print_banner, clone_from_specs
-    print_banner()
+    from machineconfig.scripts.python.repos_helpers.repos_helper import clone_from_specs
     clone_from_specs(directory, cloud, checkout_branch_flag=True, checkout_commit_flag=False)
 
 
 @app.command(no_args_is_help=True)
-def analyze(
-    directory: DirectoryArgument = None,
-) -> None:
+def analyze(directory: DirectoryArgument = None) -> None:
     """📊 Analyze repository development over time."""
-    from machineconfig.scripts.python.repos_helper import print_banner
-    print_banner()
     repo_path = directory if directory is not None else "."
-    from machineconfig.scripts.python.count_lines_frontend import analyze_repo_development
+    from machineconfig.scripts.python.repos_helpers.count_lines_frontend import analyze_repo_development
+
     analyze_repo_development(repo_path=repo_path)
 
+
+@app.command(no_args_is_help=True)
+def viz(
+    repo: str = typer.Option(Path.cwd().__str__(), "--repo", "-r", help="Path to git repository to visualize"),
+    output_file: Optional[Path] = typer.Option(None, "--output", "-o", help="Output video file (e.g., output.mp4). If specified, gource will render to video."),
+    resolution: str = typer.Option("1920x1080", "--resolution", "-res", help="Video resolution (e.g., 1920x1080, 1280x720)"),
+    seconds_per_day: float = typer.Option(0.1, "--seconds-per-day", "-spd", help="Speed of simulation (lower = faster)"),
+    auto_skip_seconds: float = typer.Option(1.0, "--auto-skip-seconds", "-as", help="Skip to next entry if nothing happens for X seconds"),
+    title: Optional[str] = typer.Option(None, "--title", "-t", help="Title for the visualization"),
+    hide_items: list[str] = typer.Option([], "--hide", "-h", help="Items to hide: bloom, date, dirnames, files, filenames, mouse, progress, root, tree, users, usernames"),
+    key_items: bool = typer.Option(False, "--key", "-k", help="Show file extension key"),
+    fullscreen: bool = typer.Option(False, "--fullscreen", "-f", help="Run in fullscreen mode"),
+    viewport: Optional[str] = typer.Option(None, "--viewport", "-v", help="Camera viewport (e.g., '1000x1000')"),
+    start_date: Optional[str] = typer.Option(None, "--start-date", help="Start date (YYYY-MM-DD)"),
+    stop_date: Optional[str] = typer.Option(None, "--stop-date", help="Stop date (YYYY-MM-DD)"),
+    user_image_dir: Optional[Path] = typer.Option(None, "--user-image-dir", help="Directory with user avatar images"),
+    max_files: int = typer.Option(0, "--max-files", help="Maximum number of files to show (0 = no limit)"),
+    max_file_lag: float = typer.Option(5.0, "--max-file-lag", help="Max time files remain on screen after last change"),
+    file_idle_time: int = typer.Option(0, "--file-idle-time", help="Time in seconds files remain idle before being removed"),
+    framerate: int = typer.Option(60, "--framerate", help="Frames per second for video output"),
+    background_color: str = typer.Option("000000", "--background-color", help="Background color in hex (e.g., 000000 for black)"),
+    font_size: int = typer.Option(22, "--font-size", help="Font size"),
+    camera_mode: str = typer.Option("overview", "--camera-mode", help="Camera mode: overview or track"),
+        ) -> None:
+    """🎬 Visualize repository activity using Gource."""
+    from machineconfig.scripts.python.helpers_repos.grource import visualize
+    visualize(repo=repo, output_file=output_file, resolution=resolution, seconds_per_day=seconds_per_day,
+              auto_skip_seconds=auto_skip_seconds, title=title, hide_items=hide_items, key_items=key_items,
+              fullscreen=fullscreen, viewport=viewport, start_date=start_date, stop_date=stop_date,
+              user_image_dir=user_image_dir, max_files=max_files, max_file_lag=max_file_lag,
+              file_idle_time=file_idle_time, framerate=framerate, background_color=background_color,
+              font_size=font_size, camera_mode=camera_mode)

machineconfig/scripts/python/{count_lines_frontend.py → repos_helpers/count_lines_frontend.py}

@@ -3,7 +3,7 @@ import typer
 
 
 def analyze_repo_development(repo_path: str = typer.Argument(..., help="Path to the git repository")):
-    from machineconfig.scripts.python import count_lines
+    from machineconfig.scripts.python.repos_helpers import count_lines
     from pathlib import Path
     count_lines_path = Path(count_lines.__file__)
     # --project $HOME/code/machineconfig --group plot

machineconfig/scripts/python/{repos_helper.py → repos_helpers/repos_helper.py}

@@ -8,14 +8,6 @@ from machineconfig.utils.source_of_truth import CONFIG_PATH, DEFAULTS_PATH
 import typer
 
 
-
-def print_banner() -> None:
-    typer.echo("\n" + "=" * 50)
-    typer.echo("📂 Welcome to the Repository Manager")
-    typer.echo("=" * 50 + "\n")
-
-
-
 def resolve_directory(directory: Optional[str]) -> Path:
     if directory is None:
         directory = Path.cwd().as_posix()
@@ -30,10 +22,10 @@ def git_operations(
     recursive: bool,
     no_sync: bool,
 ) -> None:
-    print_banner()
+    
     repos_root = resolve_directory(directory)
     auto_sync = not no_sync
-    from machineconfig.scripts.python.repos_helper_action import perform_git_operations
+    from machineconfig.scripts.python.repos_helpers.repos_helper_action import perform_git_operations
     from machineconfig.utils.path_extended import PathExtended
     perform_git_operations(
         repos_root=PathExtended(repos_root),
@@ -73,10 +65,10 @@ def clone_from_specs(
     checkout_branch_flag: bool,
     checkout_commit_flag: bool,
 ) -> None:
-    print_banner()
+    
     typer.echo("\n📥 Cloning or checking out repositories...")
     spec_path = resolve_spec_path(directory, cloud)
-    from machineconfig.scripts.python.repos_helper_clone import clone_repos
+    from machineconfig.scripts.python.repos_helpers.repos_helper_clone import clone_repos
     clone_repos(
         spec_path=spec_path,
         preferred_remote=None,

machineconfig/scripts/python/{repos_helper_action.py → repos_helpers/repos_helper_action.py}

@@ -1,6 +1,6 @@
 from machineconfig.utils.path_extended import PathExtended
 from machineconfig.utils.accessories import randstr
-from machineconfig.scripts.python.repos_helper_update import update_repository
+from machineconfig.scripts.python.repos_helpers.repos_helper_update import update_repository
 
 from typing import Optional
 from dataclasses import dataclass

machineconfig/scripts/python/sessions_multiprocess.py

@@ -41,7 +41,7 @@ def create_from_function(
 
     # =========================  choosing function to run
     if function is None or function.strip() == "":
-        from machineconfig.scripts.python.fire_jobs_route_helper import choose_function_or_lines
+        from machineconfig.scripts.python.helpers_fire_command.fire_jobs_route_helper import choose_function_or_lines
         choice_function, choice_file, _kwargs_dict = choose_function_or_lines(choice_file, kwargs_dict={})
     else:
         choice_function = function