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

machineconfig/scripts/python/helpers/helpers_devops/cli_data.py

@@ -0,0 +1,67 @@
+import typer
+from typing import Annotated, Optional, Literal
+from machineconfig.profile.create_links_export import REPO_LOOSE
+
+
+def sync(
+    direction: Annotated[Literal["up", "u", "down", "d"], typer.Argument(..., help="Direction of sync: backup or 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 BACKUP (from backup.toml), or 'all' for all items")
+    ] = None,
+    repo: Annotated[REPO_LOOSE, typer.Option("--repo", "-r", help="📁 Which backup configuration to use: 'library' or 'user'")] = "all",
+    # interactive: Annotated[bool, typer.Option("--interactive", "-i", help="🤔 Prompt the selection of which items to process")] = False,
+):
+    from machineconfig.scripts.python.helpers.helpers_devops.cli_backup_retrieve import main_backup_retrieve
+    match direction:
+        case "up" | "u":
+            direction_resolved = "BACKUP"
+        case "down" | "d":
+            direction_resolved = "RETRIEVE"
+    main_backup_retrieve(direction=direction_resolved, which=which, cloud=cloud, repo=repo)
+
+
+def register_data(
+    path_local: Annotated[str, typer.Argument(..., help="Local file/folder path to back up.")],
+    group: Annotated[str, typer.Option("--group", "-g", help="Group section name in backup.toml.")] = "default",
+    name: Annotated[Optional[str], typer.Option("--name", "-n", help="Entry name inside the group in backup.toml.")] = None,
+    path_cloud: Annotated[Optional[str], typer.Option("--path-cloud", "-C", help="Cloud path override (optional).")] = None,
+    zip_: Annotated[bool, typer.Option("--zip/--no-zip", "-z/-nz", help="Zip before uploading.")] = False,
+    encrypt: Annotated[bool, typer.Option("--encrypt/--no-encrypt", "-e/-ne", help="Encrypt before uploading.")] = False,
+    rel2home: Annotated[Optional[bool], typer.Option("--rel2home/--no-rel2home", "-r/-nr", help="Treat the local path as relative to home.")] = None,
+    os: Annotated[str, typer.Option("--os", "-o", help="OS filter for this backup entry (comma-separated, or 'any').")] = "any",
+) -> None:
+    from machineconfig.scripts.python.helpers.helpers_devops.cli_backup_retrieve import register_backup_entry
+
+    try:
+        backup_path, entry_name, replaced = register_backup_entry(
+            path_local=path_local, group=group, entry_name=name, path_cloud=path_cloud, zip=zip_, encrypt=encrypt, rel2home=rel2home, os=os
+        )
+    except ValueError as exc:
+        msg = typer.style("Error: ", fg=typer.colors.RED) + str(exc)
+        typer.echo(msg)
+        raise typer.Exit(code=1)
+    action = "Updated" if replaced else "Added"
+    typer.echo(f"{action} backup entry '{entry_name}' in {backup_path}")
+
+
+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,
+        add_help_option=True,
+        add_completion=False,
+    )
+
+    app.command(name="sync", no_args_is_help=True, hidden=False, help="🔄 [s] Sync (backup) files and directories to cloud storage using rclone.")(
+        sync
+    )
+
+    app.command(name="s", no_args_is_help=True, hidden=True)(sync)
+
+    app.command(name="register", no_args_is_help=True, hidden=False, help="📝 [r] Register a new backup entry in user backup.toml.")(register_data)
+
+    app.command(name="r", no_args_is_help=True, hidden=True)(register_data)
+
+    return app

machineconfig/scripts/python/{helpers_devops → helpers/helpers_devops}/cli_nw.py

@@ -1,57 +1,33 @@
 
-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 machineconfig.scripts.python.helpers.helpers_devops.cli_share_file
+import machineconfig.scripts.python.helpers.helpers_devops.cli_share_terminal as cli_share_terminal
+import machineconfig.scripts.python.helpers.helpers_devops.cli_share_server as cli_share_server
+import machineconfig.scripts.python.helpers.helpers_devops.cli_ssh as cli_ssh
 import typer
-from typing import Optional, Annotated
+from typing import 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 switch_public_ip_address(
+    wait_seconds: Annotated[float, typer.Option(..., "--wait", "-w", help="Seconds to wait between steps")] = 2.0,
+    max_trials: Annotated[int, typer.Option(..., "--max-trials", "-m", help="Max number of switch attempts")] = 10,
+) -> None:
+    """🔁 Switch public IP address (Cloudflare WARP)"""
+    import machineconfig.scripts.python.helpers.helpers_network.address_switch as helper
+    helper.switch_public_ip_address(max_trials=max_trials, wait_seconds=wait_seconds)
 
 
 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
+    import machineconfig.scripts.python.helpers.helpers_network.address as helper
+
+    try:
+        loaded_json = helper.get_public_ip_address()
+        from rich import print_json
+        print_json(data=loaded_json)
+    except Exception as e:
+        print(f"⚠️  Could not fetch public IP address: {e}")
+        loaded_json = {}
+
     from rich.table import Table
     from rich.console import Console
     res = helper.get_all_ipv4_addresses()
@@ -91,20 +67,16 @@ netsh interface portproxy add v4tov4 listenport={port} listenaddress=0.0.0.0 con
 """
     from machineconfig.utils.code import exit_then_run_shell_script
     exit_then_run_shell_script(code)
+def open_wsl_port(ports: Annotated[str, typer.Argument(..., help="Comma-separated ports or port ranges (e.g., '8080,3000-3005,443')")]):
+    """🔥 Open Windows firewall ports for WSL (Windows only)."""
+    import machineconfig.utils.ssh_utils.wsl as wsl_utils
+    wsl_utils.open_wsl_port(ports)
+def link_wsl_and_windows_home(windows_username: Annotated[str | None, typer.Option("--windows-username", "-u", help="Windows username to use (optional, auto-detected if not provided)")] = None):
+    """🔗 Link WSL home and Windows home directories."""
+    import machineconfig.utils.ssh_utils.wsl as wsl_utils
+    wsl_utils.link_wsl_and_windows(windows_username)
 
 
-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,
@@ -114,7 +86,7 @@ def wifi_select(
     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
+    from machineconfig.scripts.python.helpers.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"))
 
@@ -164,51 +136,66 @@ 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")]):
+    print("NOTE: Please run the above commands in your terminal to apply the changes.")
+
+def add_ip_exclusion_to_warp(ip: Annotated[str, typer.Option(..., "--ip", help="IP address(es) to exclude from WARP (Comma separated)")]):
+    ips = ip.split(",")
+    res = ""
+    for an_ip in ips:
+        res += f'sudo warp-cli tunnel ip add {an_ip}\n'
+        print(f"Adding IP exclusion to WARP for: {an_ip}")
     code = f"""
-sudo warp-cli tunnel ip add {ip}
+{res}
+echo "Restarting WARP connection..."
 sudo warp-cli disconnect
+echo "Waiting for 2 seconds..."
+sleep 2
+echo "Reconnecting WARP..."
 sudo warp-cli connect
 """
     print(code)
+    print("NOTE: Please run the above commands in your terminal to apply the changes.")
 
 
 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 = typer.Typer(help="🔐 [n] Network subcommands", no_args_is_help=True, add_help_option=True, 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="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="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="send", no_args_is_help=True, hidden=False, help="📁 [sx] send files from here.")(machineconfig.scripts.python.helpers.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.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.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.helpers_devops.cli_share_file.share_file_receive)
+
+    nw_apps.add_typer(cli_ssh.get_app(), name="ssh", help="🔐 [S] SSH subcommands")
+    nw_apps.add_typer(cli_ssh.get_app(), name="S", help="SSH subcommands", hidden=True)
+
+    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="switch-public-ip", help="🔁 [c] Switch public IP address (Cloudflare WARP)")(switch_public_ip_address)
+    nw_apps.command(name="c", help="Switch public IP address (Cloudflare WARP)", hidden=True)(switch_public_ip_address)
+
+    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="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="open-wsl-port", no_args_is_help=True, help="🔥 [o] Open Windows firewall ports for WSL.", hidden=False)(open_wsl_port)
+    nw_apps.command(name="o", no_args_is_help=True, help="Open Windows firewall ports for WSL.", hidden=True)(open_wsl_port)
+    nw_apps.command(name="link-wsl-windows", no_args_is_help=False, help="🔗 [l] Link WSL home and Windows home directories.", hidden=False)(link_wsl_and_windows_home)
+    nw_apps.command(name="l", no_args_is_help=False, help="Link WSL home and Windows home directories.", hidden=True)(link_wsl_and_windows_home)
+
 
     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="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/helpers_devops/cli_repos.py

@@ -0,0 +1,274 @@
+"""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.helpers_repos.cloud_repo_sync import main as secure_repo_main
+
+
+def _resolve_directory(directory: Optional[str]) -> Path:
+    if directory is None:
+        directory = Path.cwd().as_posix()
+        typer.echo(f"📁 Using directory: {directory}")
+    return Path(directory).expanduser().absolute().resolve()
+
+
+def push(directory: Annotated[Optional[str], typer.Argument(help="📁 Directory containing repo(s).")] = None, recursive: Annotated[bool, typer.Option("--recursive", "-r", help="🔍 Recurse into nested repositories.")] = False, auto_uv_sync: Annotated[bool, typer.Option("--uv-sync/--no-uv-sync", "-u/-ns", help="Automatic uv sync after pulls.")] = False) -> None:
+    """🚀 Push changes across repositories."""
+    repos_root = _resolve_directory(directory)
+    from machineconfig.scripts.python.helpers.helpers_repos.action import perform_git_operations
+    from machineconfig.utils.path_extended import PathExtended
+    perform_git_operations(repos_root=PathExtended(repos_root), pull=False, commit=False, push=True, recursive=recursive, auto_uv_sync=auto_uv_sync)
+
+
+def pull(directory: Annotated[Optional[str], typer.Argument(help="📁 Directory containing repo(s).")] = None, recursive: Annotated[bool, typer.Option("--recursive", "-r", help="🔍 Recurse into nested repositories.")] = False, auto_uv_sync: Annotated[bool, typer.Option("--uv-sync/--no-uv-sync", "-u/-ns", help="Automatic uv sync after pulls.")] = False) -> None:
+    """⬇️ Pull changes across repositories."""
+    repos_root = _resolve_directory(directory)
+    from machineconfig.scripts.python.helpers.helpers_repos.action import perform_git_operations
+    from machineconfig.utils.path_extended import PathExtended
+    perform_git_operations(repos_root=PathExtended(repos_root), pull=True, commit=False, push=False, recursive=recursive, auto_uv_sync=auto_uv_sync)
+
+
+def commit(directory: Annotated[Optional[str], typer.Argument(help="📁 Directory containing repo(s).")] = None, recursive: Annotated[bool, typer.Option("--recursive", "-r", help="🔍 Recurse into nested repositories.")] = False, auto_uv_sync: Annotated[bool, typer.Option("--uv-sync/--no-uv-sync", "-u/-ns", help="Automatic uv sync after pulls.")] = False) -> None:
+    """💾 Commit changes across repositories."""
+    repos_root = _resolve_directory(directory)
+    from machineconfig.scripts.python.helpers.helpers_repos.action import perform_git_operations
+    from machineconfig.utils.path_extended import PathExtended
+    perform_git_operations(repos_root=PathExtended(repos_root), pull=False, commit=True, push=False, recursive=recursive, auto_uv_sync=auto_uv_sync)
+
+
+def sync(directory: Annotated[Optional[str], typer.Argument(help="📁 Directory containing repo(s).")] = None, recursive: Annotated[bool, typer.Option("--recursive", "-r", help="🔍 Recurse into nested repositories.")] = False, auto_uv_sync: Annotated[bool, typer.Option("--uv-sync/--no-uv-sync", "-u/-ns", help="Automatic uv sync after pulls.")] = False) -> None:
+    """🔄 Pull, commit, and push changes across repositories."""
+    repos_root = _resolve_directory(directory)
+    from machineconfig.scripts.python.helpers.helpers_repos.action import perform_git_operations
+    from machineconfig.utils.path_extended import PathExtended
+    perform_git_operations(repos_root=PathExtended(repos_root), pull=True, commit=True, push=True, recursive=recursive, auto_uv_sync=auto_uv_sync)
+
+
+def capture(directory: Annotated[Optional[str], typer.Argument(help="📁 Directory containing repo(s).")] = None) -> None:
+    """📝 Record repositories into a repos.json specification."""
+    from machineconfig.scripts.python.helpers.helpers_repos.record import main_record as record_repos
+    save_path = record_repos(repos_root_str=directory)
+    print(f"\n✅ Saved repository specification to {save_path}")
+
+
+def clone(directory: Annotated[str, typer.Argument(help="📁 Directory containing repo(s).")] = ".",
+          specs_path: Annotated[Optional[str], typer.Option("--specs-path", "-s", help="Path to repos.json specification file.")] = None,
+          interactive: Annotated[bool, typer.Option("--interactive/--no-interactive", "-i/-ni", help="Select interactively.")]=False
+            ) -> None:
+    """📥 Clone repositories described by a repos.json specification."""
+    if interactive:
+        from machineconfig.scripts.python.helpers.helpers_devops.cli_config_dotfile import BACKUP_ROOT_PRIVATE, BACKUP_ROOT_PUBLIC, get_original_path_from_backup_path
+        results_public = list(BACKUP_ROOT_PUBLIC.rglob("repos.json"))
+        results_private = list(BACKUP_ROOT_PRIVATE.rglob("repos.json"))
+        if len(results_public) + len(results_private) == 0:
+            print("❌ No repos.json specifications found in backup directories.")
+            return
+        from machineconfig.utils.options import choose_from_options
+        chosen_files: list[str] = choose_from_options(options=[str(p) for p in results_public + results_private], msg="Select a repos.json specification to clone from:", multi=True, tv=True)
+        for file in chosen_files:
+            if str(file).startswith(str(BACKUP_ROOT_PRIVATE)):
+                original_path = get_original_path_from_backup_path(Path(file), sensitivity="private", destination=None, shared=False)
+            else:
+                original_path = get_original_path_from_backup_path(Path(file), sensitivity="public", destination=None, shared=False)
+            typer.echo("\n📥 Cloning or checking out repositories...")
+            dir_obj = _resolve_directory(str(original_path))
+            spec_path_default = dir_obj.joinpath("repos.json")
+            from machineconfig.scripts.python.helpers.helpers_devops.cli_config_dotfile import get_backup_path
+            spec_path_self_managed = get_backup_path(orig_path=spec_path_default, sensitivity="private", destination=None, shared=False)
+            from machineconfig.scripts.python.helpers.helpers_repos.clone import clone_repos
+            clone_repos(spec_path=spec_path_self_managed, preferred_remote=None, checkout_branch_flag=False, checkout_commit_flag=False)
+        return
+    if specs_path is not None:
+        spec_path_self_managed = Path(specs_path).expanduser().absolute()
+    else:
+        dir_obj = _resolve_directory(directory)
+        spec_path_default = dir_obj.joinpath("repos.json")
+        from machineconfig.scripts.python.helpers.helpers_devops.cli_config_dotfile import get_backup_path
+        spec_path_self_managed = get_backup_path(orig_path=spec_path_default, sensitivity="private", destination=None, shared=False)
+        if not spec_path_self_managed.exists():
+            print(f"❌ Specification file not found: {spec_path_self_managed}. Ensure this file exists or provide it explicitly using --specs-path.")
+            return
+    from machineconfig.scripts.python.helpers.helpers_repos.clone import clone_repos
+    clone_repos(spec_path=spec_path_self_managed, preferred_remote=None, checkout_branch_flag=False, checkout_commit_flag=False)
+
+
+def checkout_command(directory: Annotated[Optional[str], typer.Argument(help="📁 Directory containing repo(s).")] = None) -> None:
+    """🔀 Check out specific commits listed in the specification."""
+    typer.echo("\n📥 Cloning or checking out repositories...")
+    dir_obj = _resolve_directory(directory)
+    spec_path_default = dir_obj.joinpath("repos.json")
+    from machineconfig.scripts.python.helpers.helpers_devops.cli_config_dotfile import get_backup_path
+    spec_path_self_managed = get_backup_path(orig_path=spec_path_default, sensitivity="private", destination=None, shared=False)
+    from machineconfig.scripts.python.helpers.helpers_repos.clone import clone_repos
+    clone_repos(spec_path=spec_path_self_managed, preferred_remote=None, checkout_branch_flag=False, checkout_commit_flag=True)
+
+
+def checkout_to_branch_command(directory: Annotated[Optional[str], typer.Argument(help="📁 Directory containing repo(s).")] = None) -> None:
+    """🔀 Check out to the main branch defined in the specification."""
+    typer.echo("\n📥 Cloning or checking out repositories...")
+    dir_obj = _resolve_directory(directory)
+    spec_path_default = dir_obj.joinpath("repos.json")
+    from machineconfig.scripts.python.helpers.helpers_devops.cli_config_dotfile import get_backup_path
+    spec_path_self_managed = get_backup_path(orig_path=spec_path_default, sensitivity="private", destination=None, shared=False)
+    from machineconfig.scripts.python.helpers.helpers_repos.clone import clone_repos
+    clone_repos(spec_path=spec_path_self_managed, preferred_remote=None, 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.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>=8.51"])
+    from machineconfig.scripts.python.helpers.helpers_repos import repo_analyzer_1
+    try:
+        repo_analyzer_1.count_historical_line_edits(repo_path=repo_path)
+    except Exception as e:
+        typer.echo(f"❌ Error counting lines in repo {repo_path}: {e}")
+
+
+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.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]>=8.51"])
+    from machineconfig.scripts.python.helpers.helpers_repos.repo_analyzer_2 import print_python_files_by_size_impl
+    print_python_files_by_size_impl(repo_path=repo_path)
+
+
+def analyze_repo_development(repo_path: Annotated[str, typer.Argument(..., help="Path to the git repository")]):
+    # def func(repo_path: str):
+    #     from machineconfig.scripts.python.helpers.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]>=8.51"])
+    from machineconfig.scripts.python.helpers.helpers_repos.repo_analyzer_2 import analyze_over_time
+    analyze_over_time(repo_path=repo_path)
+
+
+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",
+    self: Annotated[bool, typer.Option(..., "--self", help="Clone machineconfig repository and act on it")] = False,
+        ) -> None:
+    """🎬 Visualize repository activity using Gource."""
+    from machineconfig.scripts.python.helpers.helpers_repos.grource import visualize
+    if self:
+        repo_path = Path.home().joinpath("machineconfig")
+        if not repo_path.exists():
+            import git
+            repo_url = "https://github.com/thisismygitrepo/machineconfig.git"
+            git.Repo.clone_from(repo_url, to_path=repo_path.as_posix())
+            repo = repo_path.as_posix()
+    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: Annotated[Optional[str], typer.Argument(help="📁 Directory containing repo(s).")] = None, recursive: Annotated[bool, typer.Option("--recursive", "-r", help="🔍 Recurse into nested repositories.")] = 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, display_script=True, clean_env=False)
+
+
+def get_app():
+    repos_apps = typer.Typer(help="📁 [r] Manage development repositories", no_args_is_help=True, add_help_option=True, add_completion=False)
+    mirror_app = typer.Typer(help="🔄 [m] Manage repository specifications and syncing", no_args_is_help=True, add_help_option=True, 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="y", 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
+