machineconfig 5.15__py3-none-any.whl → 7.98__py3-none-any.whl

machineconfig/scripts/python/helpers_devops/cli_config.py

@@ -0,0 +1,105 @@
+
+
+from typing import Literal, Annotated
+from pathlib import Path
+import typer
+import machineconfig.scripts.python.helpers_devops.cli_config_dotfile as dotfile_module
+import machineconfig.profile.create_links_export as create_links_export
+
+
+def configure_shell_profile(which: Annotated[Literal["default", "d", "nushell", "n"], typer.Option(..., "--which", "-w", help="Which shell profile to create/configure")]="default"):
+    """🔗 Configure your shell profile."""
+    from machineconfig.profile.create_shell_profile import create_default_shell_profile,  create_nu_shell_profile
+    match which:
+        case "nushell" | "n":
+            create_nu_shell_profile()
+            return
+        case "default" | "d":
+            create_default_shell_profile()
+            return
+    typer.echo(f"[red]Error:[/] Unknown shell profile type: {which}")
+
+
+
+def pwsh_theme():
+    """🔗 Select powershell prompt theme."""
+    import machineconfig.scripts.python.helpers_devops.themes as themes
+    file = Path(themes.__file__).parent / "choose_pwsh_theme.ps1"
+    import subprocess
+    subprocess.run(["pwsh", "-File", str(file)])
+
+
+def starship_theme():
+    """🔗 Select starship prompt theme."""
+    import subprocess
+    from machineconfig.utils.code import run_shell_script
+    
+    presets: list[str] = ["catppuccin-powerline", "pastel-powerline", "tokyo-night", "gruvbox-rainbow", "jetpack"]
+    config_path: Path = Path.home() / ".config" / "starship.toml"
+    
+    typer.echo("\n🚀 Starship Theme Selector\n")
+    for idx, preset in enumerate(presets, start=1):
+        typer.echo(f"{idx}. {preset}")
+    
+    choice: str = typer.prompt("Select a preset")
+    
+    try:
+        choice_idx: int = int(choice)
+        if 1 <= choice_idx <= len(presets):
+            selected_preset: str = presets[choice_idx - 1]
+            typer.echo(f"\n✨ Applying {selected_preset}...")
+            run_shell_script(f"""starship preset {selected_preset} -o {config_path}""")
+            typer.echo("\n📋 Preview:")
+            subprocess.run(["starship", "module", "all"], check=False)
+            typer.echo(f"\n✅ {selected_preset} applied!")
+        else:
+            typer.echo("❌ Invalid selection")
+    except ValueError:
+        typer.echo("❌ Please enter a valid number")
+
+
+def copy_assets(which: Annotated[Literal["scripts", "s", "settings", "t", "both", "b"], typer.Argument(..., help="Which assets to copy")]):
+    """🔗 Copy asset files from library to machine."""
+    import machineconfig.profile.create_helper as create_helper
+    match which:
+        case "both" | "b":
+            create_helper.copy_assets_to_machine(which="scripts")
+            create_helper.copy_assets_to_machine(which="settings")
+            return
+        case "scripts" | "s":
+            create_helper.copy_assets_to_machine(which="scripts")
+            return
+        case "settings" | "t":
+            create_helper.copy_assets_to_machine(which="settings")
+            return
+    typer.echo(f"[red]Error:[/] Unknown asset type: {which}")
+
+
+def link_wsl_and_windows_home():
+    """🔗 Link WSL home and Windows home directories."""
+    import machineconfig.utils.ssh_utils.wsl as wsl_utils
+    wsl_utils.link_wsl_and_windows()
+
+
+def get_app():
+    config_apps = typer.Typer(help="⚙️ [c] configuration subcommands", no_args_is_help=True, add_help_option=False, add_completion=False)
+    config_apps.command("private", no_args_is_help=True, help="🔗 [v] Manage private configuration files.")(create_links_export.main_private_from_parser)
+    config_apps.command("v", no_args_is_help=True, hidden=True)(create_links_export.main_private_from_parser)
+    config_apps.command("public", no_args_is_help=True, help="🔗 [b] Manage public configuration files.")(create_links_export.main_public_from_parser)
+    config_apps.command("b", no_args_is_help=True, help="Manage public configuration files.", hidden=True)(create_links_export.main_public_from_parser)
+    config_apps.command("dotfile", no_args_is_help=True, help="🔗 [d] Manage dotfiles.")(dotfile_module.main)
+    config_apps.command("d", no_args_is_help=True,  hidden=True)(dotfile_module.main)
+    config_apps.command("shell", no_args_is_help=False, help="🔗 [s] Configure your shell profile.")(configure_shell_profile)
+    config_apps.command("s", no_args_is_help=False, help="Configure your shell profile.", hidden=True)(configure_shell_profile)
+    config_apps.command("starship-theme", no_args_is_help=False, help="🔗 [t] Select starship prompt theme.")(starship_theme)
+    config_apps.command("t", no_args_is_help=False, help="Select starship prompt theme.", hidden=True)(starship_theme)
+    config_apps.command("pwsh-theme", no_args_is_help=False, help="🔗 [T] Select powershell prompt theme.")(pwsh_theme)
+    config_apps.command("T", no_args_is_help=False, help="Select powershell prompt theme.", hidden=True)(pwsh_theme)
+
+    config_apps.command("copy-assets", no_args_is_help=True, help="🔗 [c] Copy asset files from library to machine.", hidden=False)(copy_assets)
+    config_apps.command("c", no_args_is_help=True, help="Copy asset files from library to machine.", hidden=True)(copy_assets)
+
+    config_apps.command("link-wsl-windows", no_args_is_help=False, help="🔗 [l] Link WSL home and Windows home directories.", hidden=False)(link_wsl_and_windows_home)
+    config_apps.command("l", no_args_is_help=False, help="Link WSL home and Windows home directories.", hidden=True)(link_wsl_and_windows_home)
+
+    return config_apps

machineconfig/scripts/python/helpers_devops/cli_config_dotfile.py

@@ -0,0 +1,89 @@
+
+"""Like yadm and dotter."""
+
+from machineconfig.profile.create_links_export import ON_CONFLICT_LOOSE, ON_CONFLICT_MAPPER
+from typing import Annotated, Literal
+import typer
+
+
+
+def main(
+    file: Annotated[str, typer.Argument(help="file/folder path.")],
+    method: Annotated[Literal["symlink", "s", "copy", "c"], typer.Option(..., "--method", "-m", help="Method to use for linking files")] = "copy",
+    on_conflict: Annotated[ON_CONFLICT_LOOSE, typer.Option(..., "--on-conflict", "-o", help="Action to take on conflict")] = "throw-error",
+    sensitivity: Annotated[Literal["private", "v", "public", "b"], typer.Option(..., "--sensitivity", "-s", help="Sensitivity of the config file.")] = "private",
+    destination: Annotated[str, typer.Option("--destination", "-d", help="destination folder (override the default, use at your own risk)")] = "",
+    shared: Annotated[bool, typer.Option("--shared", "-sh", help="Whether the config file is shared across destinations directory.")] = False,
+    ) -> None:
+    from rich.console import Console
+    from rich.panel import Panel
+    from machineconfig.utils.links import symlink_map, copy_map
+    from pathlib import Path
+    match sensitivity:
+        case "private" | "v":
+            backup_root = Path.home().joinpath("dotfiles/mapper")
+        case "public" | "b":
+            from machineconfig.utils.source_of_truth import CONFIG_ROOT
+            backup_root = Path(CONFIG_ROOT).joinpath("dotfiles/mapper")
+
+    console = Console()
+    orig_path = Path(file).expanduser().absolute()
+    if destination == "":
+        if shared:
+            new_path = backup_root.joinpath("shared").joinpath(orig_path.name)
+            new_path.parent.mkdir(parents=True, exist_ok=True)
+        else:
+            new_path = backup_root.joinpath(orig_path.relative_to(Path.home()))
+            new_path.parent.mkdir(parents=True, exist_ok=True)
+    else:
+        if shared:
+            dest_path = Path(destination).expanduser().absolute()
+            dest_path.mkdir(parents=True, exist_ok=True)
+            new_path = dest_path.joinpath("shared").joinpath(orig_path.name)
+            new_path.parent.mkdir(parents=True, exist_ok=True)
+        else:
+            dest_path = Path(destination).expanduser().absolute()
+            dest_path.mkdir(parents=True, exist_ok=True)
+            new_path = dest_path.joinpath(orig_path.name)
+    match method:
+        case "copy" | "c":
+            try:
+                copy_map(config_file_default_path=orig_path, self_managed_config_file_path=new_path, on_conflict=ON_CONFLICT_MAPPER[on_conflict])  # type: ignore[arg-type]
+            except Exception as e:
+                typer.echo(f"[red]Error:[/] {e}")
+                typer.Exit(code=1)
+                return
+        case "symlink" | "s":
+            try:
+                symlink_map(config_file_default_path=orig_path, self_managed_config_file_path=new_path, on_conflict=ON_CONFLICT_MAPPER[on_conflict])  # type: ignore[arg-type]
+            except Exception as e:
+                typer.echo(f"[red]Error:[/] {e}")
+                typer.Exit(code=1)
+        case _:
+            raise ValueError(f"Unknown method: {method}")
+    console.print(Panel("\n".join(["✅ Symbolic link created successfully!", "🔄 Add the following snippet to mapper.toml to persist this mapping:",]), title="Symlink Created", border_style="green", padding=(1, 2),))
+
+    # mapper_snippet = "\n".join(
+    #     [
+    #         f"[bold]📝 Edit configuration file:[/] [cyan]nano {Path(CONFIG_ROOT)}/symlinks/mapper.toml[/cyan]",
+    #         "",
+    #         f"[{new_path.parent.name}]",
+    #         f"{orig_path.name.split('.')[0]} = {{ this = '{orig_path.as_posix()}', to_this = '{new_path.as_posix()}' }}",
+    #     ]
+    # )
+    # console.print(
+    #     Panel(
+    #         mapper_snippet,
+    #         title="Mapper Entry",
+    #         border_style="cyan",
+    #         padding=(1, 2),
+    #     )
+    # )
+
+
+def arg_parser() -> None:
+    typer.run(main)
+
+
+if __name__ == "__main__":
+    arg_parser()

machineconfig/scripts/python/helpers_devops/cli_data.py

@@ -0,0 +1,25 @@
+
+import typer
+from typing import Annotated, Optional
+
+def backup(cloud: Annotated[Optional[str], typer.Option("--cloud", "-c", help="☁️  Cloud configuration name (rclone config name)")] = None,
+           which: Annotated[Optional[str], typer.Option("--which", "-w", help="📝 Comma-separated list of items to BACKUP (from backup.toml), or 'all' for all items")] = None):
+    """💾 BACKUP"""
+    from machineconfig.scripts.python.helpers_devops.devops_backup_retrieve import main_backup_retrieve
+    main_backup_retrieve(direction="BACKUP", which=which, cloud=cloud)
+
+
+def retrieve(cloud: Annotated[Optional[str], typer.Option("--cloud", "-c", help="☁️  Cloud configuration name (rclone config name)")] = None,
+             which: Annotated[Optional[str], typer.Option("--which", "-w", help="📝 Comma-separated list of items to RETRIEVE (from backup.toml), or 'all' for all items")] = None):
+    """📥 RETRIEVE"""
+    from machineconfig.scripts.python.helpers_devops.devops_backup_retrieve import main_backup_retrieve
+    main_backup_retrieve(direction="RETRIEVE", which=which, cloud=cloud)
+
+
+def get_app() -> typer.Typer:
+    app = typer.Typer(name="data", help="💾 [d] Backup and Retrieve configuration files and directories to/from cloud storage using rclone.", no_args_is_help=True)
+    app.command(name="backup", no_args_is_help=True, hidden=False, help="💾 [b] Backup files and directories to cloud storage using rclone.")(backup)
+    app.command(name="b", no_args_is_help=True, hidden=True,)(backup)
+    app.command(name="retrieve", no_args_is_help=True, hidden=False, help="📥 [r] Retrieve files and directories from cloud storage using rclone.")(retrieve)
+    app.command(name="r", no_args_is_help=True, hidden=True, )(retrieve)
+    return app

machineconfig/scripts/python/helpers_devops/cli_nw.py

@@ -0,0 +1,214 @@
+
+import machineconfig.scripts.python.helpers_devops.cli_share_file
+import machineconfig.scripts.python.helpers_devops.cli_share_terminal as cli_share_terminal
+import machineconfig.scripts.python.helpers_devops.cli_share_server as cli_share_server
+import typer
+from typing import Optional, Annotated
+
+
+
+def install_ssh_server():
+    """📡 SSH install server"""
+    import platform
+    if platform.system() == "Windows":
+        from machineconfig.setup_windows import SSH_SERVER
+    elif platform.system() == "Linux" or platform.system() == "Darwin":
+        from machineconfig.setup_linux import SSH_SERVER
+    else:
+        raise NotImplementedError(f"Platform {platform.system()} is not supported.")
+    from machineconfig.utils.code import run_shell_script
+    run_shell_script(script=SSH_SERVER.read_text(encoding="utf-8"))
+
+
+def add_ssh_key(path: Annotated[Optional[str], typer.Option(..., help="Path to the public key file")] = None,
+         choose: Annotated[bool, typer.Option(..., "--choose", "-c", help="Choose from available public keys in ~/.ssh/*.pub")] = False,
+         value: Annotated[bool, typer.Option(..., "--value", "-v", help="Paste the public key content manually")] = False,
+         github: Annotated[Optional[str], typer.Option(..., "--github", "-g", help="Fetch public keys from a GitHub username")] = None
+):
+    """🔑 SSH add pub key to this machine so its accessible by owner of corresponding private key."""
+    import machineconfig.scripts.python.helpers_network.devops_add_ssh_key as helper
+    helper.main(pub_path=path, pub_choose=choose, pub_val=value, from_github=github)
+def add_ssh_identity():
+    """🗝️ SSH add identity (private key) to this machine"""
+    import machineconfig.scripts.python.helpers_network.devops_add_identity as helper
+    helper.main()
+
+
+def show_address() -> None:
+    """📌 Show this computer addresses on network"""
+    from machineconfig.utils.installer_utils.installer_cli import install_if_missing
+    import subprocess
+    install_if_missing("ipinfo")
+    result = subprocess.run(
+        ["ipinfo", "myip", "--json"],
+        check=True,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+    )
+    import json
+    loaded_json = json.loads(result.stdout)
+    from rich import print_json
+    print_json(data=loaded_json)
+
+    import machineconfig.scripts.python.helpers_network.address as helper
+    from rich.table import Table
+    from rich.console import Console
+    res = helper.get_all_ipv4_addresses()
+    res.append( ("Public IP", loaded_json.get("ip", "N/A")))
+    
+    # loc = loaded_json["loc"]
+    # cmd = f"""curl "https://maps.geoapify.com/v1/staticmap?style=osm-bright&width=600&height=300&center=lonlat:{loc}&zoom=6&marker=lonlat:{loc};color:%23ff0000;size:medium&apiKey=$GEOAPIFY_API_KEY" -o map.png && chafa map.png"""
+    # from machineconfig.utils.code import run_shell_script
+    # run_shell_script(script=cmd)
+
+    table = Table(title="Network Interfaces")
+    table.add_column("Interface", style="cyan")
+    table.add_column("IP Address", style="green")
+    
+    for iface, ip in res:
+        table.add_row(iface, ip)
+    
+    console = Console()
+    console.print(table)
+    
+    res = helper.select_lan_ipv4(prefer_vpn=False)
+    if res is not None:
+        # ip, iface = res
+        # print(f"Selected IP: {ip} on interface: {iface}")
+        print(f"LAN IPv4: {res}")
+    else:
+        print("No network interfaces found.")
+
+
+
+def bind_wsl_port(port: Annotated[int, typer.Option(..., "--port", "-p", help="Port number to bind")]):
+    code = f"""
+
+$wsl_ip = (wsl.exe hostname -I).Trim().Split(' ')[0]
+netsh interface portproxy add v4tov4 listenport={port} listenaddress=0.0.0.0 connectport={port} connectaddress=$wsl_ip
+
+"""
+    from machineconfig.utils.code import exit_then_run_shell_script
+    exit_then_run_shell_script(code)
+
+
+def debug_ssh():
+    """🐛 SSH debug"""
+    from platform import system
+    if system() == "Linux" or system() == "Darwin":
+        import machineconfig.scripts.python.helpers_network.ssh_debug_linux as helper
+        helper.ssh_debug_linux()
+    elif system() == "Windows":
+        import machineconfig.scripts.python.helpers_network.ssh_debug_windows as helper
+        helper.ssh_debug_windows()
+    else:
+        raise NotImplementedError(f"Platform {system()} is not supported.")
+
+def wifi_select(
+    ssid: Annotated[str, typer.Option("-n", "--ssid", help="🔗 SSID of WiFi (from config)")] = "MyPhoneHotSpot",
+    manual: Annotated[bool, typer.Option("-m", "--manual", help="🔍 Manual network selection mode")] = False,
+    list_: Annotated[bool, typer.Option("-l", "--list", help="📡 List available networks only")] = False,
+) -> None:
+    """Main function with fallback network selection"""
+    from rich.panel import Panel
+    from rich.prompt import Confirm
+    from rich.console import Console
+    from machineconfig.scripts.python.helpers_network.wifi_conn import try_config_connection, manual_network_selection, display_available_networks
+    console = Console()
+    console.print(Panel("📶 Welcome to the WiFi Connector Tool", title="[bold blue]WiFi Connection[/bold blue]", border_style="blue"))
+
+    # If user just wants to list networks
+    if list_:
+        display_available_networks()
+        return
+
+    # If user wants manual mode, skip config and go straight to selection
+    if manual:
+        console.print("[blue]🔍 Manual network selection mode[/blue]")
+        if manual_network_selection():
+            console.print("[green]🎉 Successfully connected![/green]")
+        else:
+            console.print("[red]❌ Failed to connect[/red]")
+        return
+
+    # Try to connect using configuration first
+    console.print(f"[blue]🔍 Attempting to connect to configured network: {ssid}[/blue]")
+
+    if try_config_connection(ssid):
+        console.print("[green]🎉 Successfully connected using configuration![/green]")
+        return
+
+    # Configuration failed, offer fallback options
+    console.print("\n[yellow]⚠️  Configuration connection failed or not available[/yellow]")
+
+    if Confirm.ask("[blue]Would you like to manually select a network?[/blue]", default=True):
+        if manual_network_selection():
+            console.print("[green]🎉 Successfully connected![/green]")
+        else:
+            console.print("[red]❌ Failed to connect[/red]")
+    else:
+        console.print("[blue]👋 Goodbye![/blue]")
+
+
+
+def reset_cloudflare_tunnel():
+    code = """
+# cloudflared tunnel route dns glenn  # creates CNAMES in Cloudflare dashboard
+# sudo systemctl stop cloudflared
+# test: cloudflared tunnel run glenn
+home_dir=$HOME
+cloudflared_path="$home_dir/.local/bin/cloudflared"
+sudo $cloudflared_path service uninstall
+sudo rm /etc/cloudflared/config.yml || true
+sudo $cloudflared_path --config $home_dir/.cloudflared/config.yml service install
+"""
+    print(code)
+def add_ip_exclusion_to_warp(ip: Annotated[str, typer.Option(..., "--ip", help="IP address to exclude from WARP")]):
+    code = f"""
+sudo warp-cli tunnel ip add {ip}
+sudo warp-cli disconnect
+sudo warp-cli connect
+"""
+    print(code)
+
+
+def get_app():
+    nw_apps = typer.Typer(help="🔐 [n] Network subcommands", no_args_is_help=True, add_help_option=False, add_completion=False)
+    nw_apps.command(name="share-terminal", help="📡  [t] Share terminal via web browser")(cli_share_terminal.share_terminal)
+    nw_apps.command(name="t", help="Share terminal via web browser", hidden=True)(cli_share_terminal.share_terminal)
+
+    nw_apps.command(name="share-server", help="🌐  [s] Start local/global server to share files/folders via web browser", no_args_is_help=True)(cli_share_server.web_file_explorer)
+    nw_apps.command(name="s", help="Start local/global server to share files/folders via web browser", hidden=True, no_args_is_help=True)(cli_share_server.web_file_explorer)
+
+    # app = cli_share_server.get_share_file_app()
+    # nw_apps.add_typer(app, name="share-file", help="📁  [f] Share a file via relay server", no_args_is_help=True)
+    # nw_apps.add_typer(app, name="f", help="Share a file via relay server", hidden=True, no_args_is_help=True)
+    nw_apps.command(name="send", no_args_is_help=True, hidden=False, help="📁 [sx] send files from here.")(machineconfig.scripts.python.helpers_devops.cli_share_file.share_file_send)
+    nw_apps.command(name="sx", no_args_is_help=True, hidden=True, help="📁 [sx] send files from here.")(machineconfig.scripts.python.helpers_devops.cli_share_file.share_file_send)
+    nw_apps.command(name="receive", no_args_is_help=True, hidden=False, help="📁 [rx] receive files to here.")(machineconfig.scripts.python.helpers_devops.cli_share_file.share_file_receive)
+    nw_apps.command(name="rx", no_args_is_help=True, hidden=True, help="📁 [rx] receive files to here.")(machineconfig.scripts.python.helpers_devops.cli_share_file.share_file_receive)
+
+    nw_apps.command(name="install-ssh-server", help="📡  [i] Install SSH server")(install_ssh_server)
+    nw_apps.command(name="i", help="Install SSH server", hidden=True)(install_ssh_server)
+    nw_apps.command(name="add-ssh-key", help="🔑  [k] Add SSH public key to this machine", no_args_is_help=True)(add_ssh_key)
+    nw_apps.command(name="k", help="Add SSH public key to this machine", hidden=True, no_args_is_help=True)(add_ssh_key)
+    nw_apps.command(name="add-ssh-identity", help="🗝️  [A] Add SSH identity (private key) to this machine")(add_ssh_identity)
+    nw_apps.command(name="A", help="Add SSH identity (private key) to this machine", hidden=True)(add_ssh_identity)
+    nw_apps.command(name="show-address", help="📌  [a] Show this computer addresses on network")(show_address)
+    nw_apps.command(name="a", help="Show this computer addresses on network", hidden=True)(show_address)
+    nw_apps.command(name="debug-ssh", help="🐛  [d] Debug SSH connection")(debug_ssh)
+    nw_apps.command(name="d", help="Debug SSH connection", hidden=True)(debug_ssh)
+
+    nw_apps.command(name="wifi-select", no_args_is_help=True, help="📶  [w] WiFi connection utility.")(wifi_select)
+    nw_apps.command(name="w", no_args_is_help=True, hidden=True)(wifi_select)
+
+    nw_apps.command(name="bind-wsl-port", help="🔌  [b] Bind WSL port to Windows host", no_args_is_help=True)(bind_wsl_port)
+    nw_apps.command(name="b", help="Bind WSL port to Windows host", hidden=True, no_args_is_help=True)(bind_wsl_port)
+
+    nw_apps.command(name="reset-cloudflare-tunnel", help="☁️  [r] Reset Cloudflare tunnel service")(reset_cloudflare_tunnel)
+    nw_apps.command(name="r", help="Reset Cloudflare tunnel service", hidden=True)(reset_cloudflare_tunnel)
+    nw_apps.command(name="add-ip-exclusion-to-warp", help="🚫  [p] Add IP exclusion to WARP")(add_ip_exclusion_to_warp)
+    nw_apps.command(name="p", help="Add IP exclusion to WARP", hidden=True)(add_ip_exclusion_to_warp)
+
+    return nw_apps

machineconfig/scripts/python/helpers_devops/cli_repos.py

@@ -0,0 +1,215 @@
+"""Repos CLI powered by Typer.
+
+# TODO use gh api user --jq '.login' to get the username and use it to clone the repos.
+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
+from machineconfig.scripts.python.helpers_repos.cloud_repo_sync import main as secure_repo_main
+
+
+DirectoryArgument = Annotated[Optional[str], typer.Argument(help="📁 Directory containing repo(s).")]
+RecursiveOption = Annotated[bool, typer.Option("--recursive", "-r", help="🔍 Recurse into nested repositories.")]
+UVsyncOption = Annotated[bool, typer.Option("--uv-sync/--no-uv-sync", "-u/-ns", help="Automatic uv sync after pulls.")]
+CloudOption = Annotated[Optional[str], typer.Option("--cloud", "-c", help="☁️ Upload to or download from this cloud remote.")]
+
+
+def push(directory: DirectoryArgument = None, recursive: RecursiveOption = False, auto_uv_sync: UVsyncOption = False) -> None:
+    """🚀 Push changes across repositories."""
+    from machineconfig.scripts.python.helpers_repos.entrypoint import git_operations
+    git_operations(directory, pull=False, commit=False, push=True, recursive=recursive, auto_uv_sync=auto_uv_sync)
+
+
+def pull(directory: DirectoryArgument = None, recursive: RecursiveOption = False, auto_uv_sync: UVsyncOption = False) -> None:
+    """⬇️ Pull changes across repositories."""
+    from machineconfig.scripts.python.helpers_repos.entrypoint import git_operations
+
+    git_operations(directory, pull=True, commit=False, push=False, recursive=recursive, auto_uv_sync=auto_uv_sync)
+
+
+def commit(directory: DirectoryArgument = None, recursive: RecursiveOption = False, auto_uv_sync: UVsyncOption = False) -> None:
+    """💾 Commit changes across repositories."""
+    from machineconfig.scripts.python.helpers_repos.entrypoint import git_operations
+    git_operations(directory, pull=False, commit=True, push=False, recursive=recursive, auto_uv_sync=auto_uv_sync)
+
+
+def sync(directory: DirectoryArgument = None, recursive: RecursiveOption = False, auto_uv_sync: UVsyncOption = False) -> None:
+    """🔄 Pull, commit, and push changes across repositories."""
+    from machineconfig.scripts.python.helpers_repos.entrypoint import git_operations
+    git_operations(directory, pull=True, commit=True, push=True, recursive=recursive, auto_uv_sync=auto_uv_sync)
+
+
+def capture(directory: DirectoryArgument = None, cloud: CloudOption = None) -> None:
+    """📝 Record repositories into a repos.json specification."""
+    from machineconfig.scripts.python.helpers_repos.entrypoint import resolve_directory
+    repos_root = resolve_directory(directory)
+    from machineconfig.scripts.python.helpers_repos.record import main_record 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)
+
+
+def clone(directory: DirectoryArgument = None, cloud: CloudOption = None) -> None:
+    """📥 Clone repositories described by a repos.json specification."""
+    from machineconfig.scripts.python.helpers_repos.entrypoint import clone_from_specs
+    clone_from_specs(directory, cloud, checkout_branch_flag=False, checkout_commit_flag=False)
+
+
+def checkout_command(directory: DirectoryArgument = None, cloud: CloudOption = None) -> None:
+    """🔀 Check out specific commits listed in the specification."""
+    from machineconfig.scripts.python.helpers_repos.entrypoint import clone_from_specs    
+    clone_from_specs(directory, cloud, checkout_branch_flag=False, checkout_commit_flag=True)
+
+
+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.helpers_repos.entrypoint import clone_from_specs
+    clone_from_specs(directory, cloud, checkout_branch_flag=True, checkout_commit_flag=False)
+
+
+def count_lines_in_repo(repo_path: Annotated[str, typer.Argument(..., help="Path to the git repository")]):
+    def func(repo_path: str):
+        from machineconfig.scripts.python.helpers_repos import repo_analyzer_1
+        repo_analyzer_1.count_historical_line_edits(repo_path=repo_path)
+    from machineconfig.utils.code import run_lambda_function
+    run_lambda_function(lambda: func(repo_path=repo_path), uv_project_dir=None, uv_with=["machineconfig>=7.98"])
+
+
+def print_python_files_by_size(repo_path: Annotated[str, typer.Argument(..., help="Path to the git repository")]):
+    def func(repo_path: str):
+        from machineconfig.scripts.python.helpers_repos.repo_analyzer_2 import print_python_files_by_size_impl
+        print_python_files_by_size_impl(repo_path=repo_path)
+    from machineconfig.utils.code import run_lambda_function
+    run_lambda_function(lambda: func(repo_path=repo_path), uv_project_dir=None, uv_with=["machineconfig[plot]>=7.98"])
+
+
+def analyze_repo_development(repo_path: Annotated[str, typer.Argument(..., help="Path to the git repository")]):
+    # from machineconfig.scripts.python.helpers_repos import count_lines
+    # from pathlib import Path
+
+    # count_lines_path = Path(count_lines.__file__)
+    # # --project $HOME/code/ machineconfig --group plot
+    # cmd = f"""uv run --python 3.14 --with "machineconfig[plot]>=7.98" {count_lines_path} analyze-over-time {repo_path}"""
+    # from machineconfig.utils.code import run_shell_script
+    # run_shell_script(cmd)
+    def func(repo_path: str):
+        from machineconfig.scripts.python.helpers_repos.repo_analyzer_2 import analyze_over_time
+        analyze_over_time(repo_path=repo_path)
+    from machineconfig.utils.code import run_lambda_function
+    run_lambda_function(lambda: func(repo_path=repo_path), uv_project_dir=None, uv_with=["machineconfig[plot]>=7.98"])
+
+
+def gource_viz(
+    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,
+    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 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)
+
+
+def cleanup(repo: DirectoryArgument = None, recursive: RecursiveOption = False) -> None:
+    """🧹 Clean repository directories from cache files."""
+    if repo is None:
+        repo = Path.cwd().as_posix()
+    
+    arg_path = Path(repo).expanduser().absolute()
+    from git import Repo, InvalidGitRepositoryError
+    if not recursive:
+        # Check if the directory is a git repo
+        try:
+            Repo(str(arg_path), search_parent_directories=False)
+        except InvalidGitRepositoryError:
+            typer.echo(f"❌ {arg_path} is not a git repository. Use -r flag for recursive cleanup.")
+            return
+        # Run cleanup on this repo
+        repos_to_clean = [arg_path]
+    else:
+        # Find all git repos recursively under the directory
+        git_dirs = list(arg_path.rglob('.git'))
+        repos_to_clean = [git_dir.parent for git_dir in git_dirs if git_dir.is_dir()]
+        if not repos_to_clean:
+            typer.echo(f"❌ No git repositories found under {arg_path}")
+            return
+    
+    for repo_path in repos_to_clean:
+        typer.echo(f"🧹 Cleaning {repo_path}")
+        script = fr"""
+cd "{repo_path}"
+uv run --with cleanpy cleanpy .
+# mcinit .
+# find "." -type f \( -name "*.py" -o -name "*.md" -o -name "*.json" \) -not -path "*/\.*" -not -path "*/__pycache__/*" -print0 | xargs -0 sed -i 's/[[:space:]]*$//'
+"""
+        from machineconfig.utils.code import run_shell_script
+        run_shell_script(script)
+
+
+def get_app():
+    repos_apps = typer.Typer(help="📁 [r] Manage development repositories", no_args_is_help=True, add_help_option=False, add_completion=False)
+    mirror_app = typer.Typer(help="🔄 [m] Manage repository specifications and syncing", no_args_is_help=True, add_help_option=False, add_completion=False)
+    repos_apps.add_typer(mirror_app, name="mirror", help="🔄  [m] mirror repositories using saved specs")
+    repos_apps.add_typer(mirror_app, name="m", help="mirror repositories using saved specs", hidden=True)
+
+    repos_apps.command(name="push", help="🚀  [p] Push changes across repositories")(push)
+    repos_apps.command(name="p", help="Push changes across repositories", hidden=True)(push)
+    repos_apps.command(name="pull", help="⬇️  [P] Pull changes across repositories")(pull)
+    repos_apps.command(name="P", help="Pull changes across repositories", hidden=True)(pull)
+    repos_apps.command(name="commit", help="💾  [c] Commit changes across repositories")(commit)
+    repos_apps.command(name="c", help="Commit changes across repositories", hidden=True)(commit)
+    repos_apps.command(name="sync", help="🔄  [y] Pull, commit, and push changes across repositories")(sync)
+    repos_apps.command(name="s", help="Pull, commit, and push changes across repositories", hidden=True)(sync)
+    repos_apps.command(name="analyze", help="📊  [a] Analyze repository development over time")(analyze_repo_development)
+    repos_apps.command(name="a", help="Analyze repository development over time", hidden=True)(analyze_repo_development)
+    repos_apps.command(name="secure", help="🔐  [s] Securely sync git repository to/from cloud with encryption")(secure_repo_main)
+    repos_apps.command(name="s", help="Securely sync git repository to/from cloud with encryption", hidden=True)(secure_repo_main)
+
+    repos_apps.command(name="viz", help="🎬  [v] Visualize repository activity using Gource")(gource_viz)
+    repos_apps.command(name="v", help="Visualize repository activity using Gource", hidden=True)(gource_viz)
+
+    repos_apps.command(name="count-lines", help="📄  [l] Count python lines of code in current repo + historical edits.")(count_lines_in_repo)
+    repos_apps.command(name="l", help="Count python lines of code in current repo + historical edits.", hidden=True)(count_lines_in_repo)
+
+    repos_apps.command(name="cleanup", help="🧹  [n] Clean repository directories from cache files")(cleanup)
+    repos_apps.command(name="n", help="Clean repository directories from cache files", hidden=True)(cleanup)
+
+    mirror_app.command(name="capture", help="📝  [cap] Record repositories into a repos.json specification")(capture)
+    mirror_app.command(name="cap", help="Record repositories into a repos.json specification", hidden=True)(capture)
+
+    mirror_app.command(name="clone", help="📥  [clo] Clone repositories described by a repos.json specification")(clone)
+    mirror_app.command(name="clo", help="Clone repositories described by a repos.json specification", hidden=True)(clone)
+
+    mirror_app.command(name="checkout-to-commit", help="🔀  [ctc] Check out specific commits listed in the specification")(checkout_command)
+    mirror_app.command(name="ctc", help="Check out specific commits listed in the specification", hidden=True)(checkout_command)
+
+    mirror_app.command(name="checkout-to-branch", help="🔀  [ctb] Check out to the main branch defined in the specification")(checkout_to_branch_command)
+    mirror_app.command(name="ctb", help="Check out to the main branch defined in the specification", hidden=True)(checkout_to_branch_command)
+
+    return repos_apps
+