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

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

@@ -0,0 +1,262 @@
+"""BR: Backup and Retrieve"""
+
+import re
+from platform import system
+from typing import Literal, Optional
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+
+from machineconfig.utils.io import read_ini
+from machineconfig.utils.source_of_truth import DEFAULTS_PATH
+from machineconfig.utils.code import print_code
+from machineconfig.utils.options import choose_cloud_interactively
+from machineconfig.scripts.python.helpers.helpers_cloud.helpers2 import ES
+from machineconfig.scripts.python.helpers.helpers_devops.backup_config import (
+    BackupConfig, BackupGroup, VALID_OS, USER_BACKUP_PATH, DEFAULT_BACKUP_HEADER,
+    normalize_os_name, os_applies, read_backup_config,
+)
+from machineconfig.profile.create_links_export import REPO_LOOSE
+
+DIRECTION = Literal["BACKUP", "RETRIEVE"]
+
+
+def _sanitize_entry_name(value: str) -> str:
+    token = value.strip().replace(".", "_").replace("-", "_")
+    token = re.sub(r"\s+", "_", token)
+    token = re.sub(r"[^A-Za-z0-9_]", "_", token)
+    return token or "backup_item"
+
+
+def _format_backup_entry_block(
+    entry_name: str,
+    path_local: str,
+    path_cloud: str,
+    zip: bool,
+    encrypt: bool,
+    rel2home: bool,
+    os_value: str,
+) -> str:
+    parts = [
+        f"path_local = '{path_local}'",
+        f"path_cloud = '{path_cloud}'",
+        f"encrypt = {str(encrypt).lower()}",
+        f"zip = {str(zip).lower()}",
+        f"rel2home = {str(rel2home).lower()}",
+        f"os = '{os_value}'",
+    ]
+    return f"{entry_name} = {{ {', '.join(parts)} }}"
+
+
+def _upsert_backup_entry(content: str, group_name: str, entry_name: str, entry_line: str) -> tuple[str, bool]:
+    header = f"[{group_name}]"
+    lines = content.splitlines()
+    new_lines: list[str] = []
+    in_target = False
+    entry_written = False
+    replaced = False
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith("[") and stripped.endswith("]"):
+            if in_target and not entry_written:
+                new_lines.append(entry_line)
+                entry_written = True
+            in_target = False
+            if stripped == header:
+                in_target = True
+            new_lines.append(line)
+            continue
+        if in_target:
+            if stripped.startswith(f"{entry_name} ="):
+                new_lines.append(entry_line)
+                replaced = True
+                entry_written = True
+                continue
+        new_lines.append(line)
+    if not entry_written:
+        if header not in content:
+            if new_lines and new_lines[-1].strip():
+                new_lines.append("")
+            new_lines.append(header)
+        new_lines.append(entry_line)
+    updated = "\n".join(new_lines).rstrip() + "\n"
+    return updated, replaced
+
+
+def register_backup_entry(
+    path_local: str,
+    group: str,
+    entry_name: Optional[str] = None,
+    path_cloud: Optional[str] = None,
+    zip: bool = True,
+    encrypt: bool = True,
+    rel2home: Optional[bool] = None,
+    os: str = "any",
+) -> tuple[Path, str, bool]:
+    local_path = Path(path_local).expanduser().absolute()
+    if not local_path.exists():
+        raise ValueError(f"Local path does not exist: {local_path}")
+    os_parts = [part.strip() for part in os.split(",")]
+    os_tokens: list[str] = []
+    for part in os_parts:
+        if not part:
+            continue
+        token = normalize_os_name(part)
+        if token in {"any", "all", "*"}:
+            os_tokens = ["any"]
+            break
+        if token not in VALID_OS:
+            raise ValueError(f"Invalid os value: {os!r}. Expected one of: {sorted(VALID_OS)}")
+        os_tokens.append(token)
+    if not os_tokens:
+        raise ValueError(f"Invalid os value: {os!r}. Expected one of: {sorted(VALID_OS)}")
+    home = Path.home()
+    in_home = local_path.is_relative_to(home)
+    if rel2home is None:
+        rel2home = in_home
+    if rel2home and not in_home:
+        raise ValueError("rel2home is true, but the local path is not under the home directory.")
+    group_name = _sanitize_entry_name(group) if group and group.strip() else "default"
+    if entry_name is None or not entry_name.strip():
+        base_name = _sanitize_entry_name(local_path.stem)
+        os_tag = "any" if "any" in os_tokens else "_".join(os_tokens)
+        entry_name = f"{base_name}_{os_tag}" if os_tag != "any" else base_name
+    else:
+        entry_name = _sanitize_entry_name(entry_name)
+    local_display = f"~/{local_path.relative_to(home)}" if rel2home and in_home else local_path.as_posix()
+    cloud_value = path_cloud.strip() if path_cloud and path_cloud.strip() else ES
+    os_value = "any" if "any" in os_tokens else ",".join(os_tokens)
+    entry_block = _format_backup_entry_block(
+        entry_name=entry_name,
+        path_local=local_display,
+        path_cloud=cloud_value,
+        zip=zip,
+        encrypt=encrypt,
+        rel2home=rel2home,
+        os_value=os_value,
+    )
+    USER_BACKUP_PATH.parent.mkdir(parents=True, exist_ok=True)
+    if USER_BACKUP_PATH.exists():
+        content = USER_BACKUP_PATH.read_text(encoding="utf-8")
+    else:
+        content = DEFAULT_BACKUP_HEADER
+    updated, replaced = _upsert_backup_entry(content=content, group_name=group_name, entry_name=entry_name, entry_line=entry_block)
+    USER_BACKUP_PATH.write_text(updated, encoding="utf-8")
+    return USER_BACKUP_PATH, entry_name, replaced
+
+
+def main_backup_retrieve(direction: DIRECTION, which: Optional[str], cloud: Optional[str], repo: REPO_LOOSE) -> None:
+    console = Console()
+    if cloud is None or not cloud.strip():
+        try:
+            cloud = read_ini(DEFAULTS_PATH)["general"]["rclone_config_name"].strip()
+            console.print(Panel(f"⚠️  DEFAULT CLOUD CONFIGURATION\n🌥️  Using default cloud: {cloud}", title="[bold blue]Cloud Configuration[/bold blue]", border_style="blue"))
+        except (FileNotFoundError, KeyError, IndexError):
+            console.print(Panel("🔍 DEFAULT CLOUD NOT FOUND\n🔄 Please select a cloud configuration from the options below", title="[bold red]Error: Cloud Not Found[/bold red]", border_style="red"))
+            cloud = choose_cloud_interactively().strip()
+    else:
+        cloud = cloud.strip()
+        console.print(Panel(f"🌥️  Using provided cloud: {cloud}", title="[bold blue]Cloud Configuration[/bold blue]", border_style="blue"))
+    assert cloud is not None
+    bu_file: BackupConfig = read_backup_config(repo=repo)
+    system_raw = system()
+    normalized_system = normalize_os_name(system_raw)
+    filtered: BackupConfig = {}
+    for group_name, group_items in bu_file.items():
+        matched: BackupGroup = {}
+        for key, val in group_items.items():
+            if os_applies(val["os"], system_name=normalized_system):
+                matched[key] = val
+        if matched:
+            filtered[group_name] = matched
+    bu_file = filtered
+    console.print(Panel(
+        f"🖥️  {system_raw} ENVIRONMENT DETECTED\n"
+        "🔍 Filtering entries by os field\n"
+        f"✅ Found {sum(len(item) for item in bu_file.values())} applicable backup configuration entries",
+        title="[bold blue]Environment[/bold blue]",
+        border_style="blue",
+    ))
+
+    if which is None:
+        from machineconfig.utils.options_utils.tv_options import choose_from_dict_with_preview
+        choices = choose_from_dict_with_preview(
+            options_to_preview_mapping=bu_file, extension="toml", multi=True, preview_size_percent=75.0,
+        )
+        if len(choices) == 0:
+            console.print(Panel("❌ NO ITEMS SELECTED\n⚠️  Exiting without processing any items", title="[bold red]No Items Selected[/bold red]", border_style="red"))
+            return
+    else:
+        choices = [token.strip() for token in which.split(",")] if which else []
+        console.print(Panel(f"🔖 PRE-SELECTED ITEMS\n📝 Using: {', '.join(choices)}", title="[bold blue]Pre-selected Items[/bold blue]", border_style="blue"))
+
+    items: BackupConfig
+    if "all" in choices:
+        items = bu_file
+        console.print(Panel(f"📋 PROCESSING ALL ENTRIES\n🔢 Total entries to process: {sum(len(item) for item in bu_file.values())}", title="[bold blue]Process All Entries[/bold blue]", border_style="blue"))
+    else:
+        items = {}
+        unknown: list[str] = []
+        for choice in choices:
+            if not choice:
+                continue
+            if choice in bu_file:
+                items[choice] = bu_file[choice]
+                continue
+            if "." in choice:
+                group_name, item_name = choice.split(".", 1)
+                if group_name in bu_file and item_name in bu_file[group_name]:
+                    items.setdefault(group_name, {})[item_name] = bu_file[group_name][item_name]
+                    continue
+            unknown.append(choice)
+        if unknown:
+            raise ValueError(f"Unknown backup entries: {', '.join(unknown)}")
+        console.print(Panel(f"📋 PROCESSING SELECTED ENTRIES\n🔢 Total entries to process: {sum(len(item) for item in items.values())}", title="[bold blue]Process Selected Entries[/bold blue]", border_style="blue"))
+    program = ""
+    console.print(Panel(f"🚀 GENERATING {direction} SCRIPT\n🌥️  Cloud: {cloud}\n🗂️  Items: {sum(len(item) for item in items.values())}", title="[bold blue]Script Generation[/bold blue]", border_style="blue"))
+    for group_name, group_items in items.items():
+        for item_name, item in group_items.items():
+            display_name = f"{group_name}.{item_name}"
+            flags = ""
+            flags += "z" if item["zip"] else ""
+            flags += "e" if item["encrypt"] else ""
+            flags += "r" if item["rel2home"] else ""
+            flags += "o" if "any" not in item["os"] else ""
+            local_path = Path(item["path_local"]).as_posix()
+            if item["path_cloud"] in (None, ES):
+                remote_path = ES
+                remote_display = f"{ES} (deduced)"
+            else:
+                remote_path = Path(item["path_cloud"]).as_posix()
+                remote_display = remote_path
+            remote_spec = f"{cloud}:{remote_path}"
+            console.print(Panel(
+                f"📦 PROCESSING: {display_name}\n"
+                f"📂 Local path: {local_path}\n"
+                f"☁️  Remote path: {remote_display}\n"
+                f"🏳️  Flags: {flags or 'None'}",
+                title=f"[bold blue]Processing Item: {display_name}[/bold blue]",
+                border_style="blue",
+            ))
+            flag_arg = f" -{flags}" if flags else ""
+            if direction == "BACKUP":
+                program += f"""\ncloud copy "{local_path}" "{remote_spec}"{flag_arg}\n"""
+            elif direction == "RETRIEVE":
+                program += f"""\ncloud copy "{remote_spec}" "{local_path}"{flag_arg}\n"""
+            else:
+                console.print(Panel('❌ ERROR: INVALID DIRECTION\n⚠️  Direction must be either "BACKUP" or "RETRIEVE"', title="[bold red]Error: Invalid Direction[/bold red]", border_style="red"))
+                raise RuntimeError(f"Unknown direction: {direction}")
+            if group_name == "dotfiles" and system_raw == "Linux":
+                program += """\nchmod 700 ~/.ssh/*\n"""
+                console.print(Panel("🔒 SPECIAL HANDLING: SSH PERMISSIONS\n🛠️  Setting secure permissions for SSH files\n📝 Command: chmod 700 ~/.ssh/*", title="[bold blue]Special Handling: SSH Permissions[/bold blue]", border_style="blue"))
+    print_code(code=program, lexer="shell", desc=f"{direction} script")
+    console.print(Panel(f"✅ {direction} SCRIPT GENERATION COMPLETE\n🚀 Ready to execute the operations", title="[bold green]Script Generation Complete[/bold green]", border_style="green"))
+    # import subprocess
+    # subprocess.run(program, shell=True, check=True)
+    from machineconfig.utils.code import run_shell_script
+    run_shell_script(program, display_script=True, clean_env=False)
+
+
+if __name__ == "__main__":
+    pass

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

@@ -0,0 +1,130 @@
+
+
+from typing import Literal, Annotated
+from pathlib import Path
+import typer
+import machineconfig.scripts.python.helpers.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
+    msg = typer.style("Error: ", fg=typer.colors.RED) + f"Unknown shell profile type: {which}"
+    typer.echo(msg)
+
+
+
+def pwsh_theme():
+    """🔗 Select powershell prompt theme."""
+    import machineconfig.scripts.python.helpers.helpers_devops.themes as themes
+    file_path = themes.__file__
+    # if file_path is None:
+    #     typer.echo("❌ ERROR: Could not locate themes module file.", err=True)
+    #     raise typer.Exit(code=1)
+    file = Path(file_path).parent / "choose_pwsh_theme.ps1"
+    import subprocess
+    subprocess.run(["pwsh", "-File", str(file)])
+
+
+def starship_theme():
+    """🔗 Select starship prompt theme."""
+    import subprocess
+    import platform
+    import os
+    from pathlib import Path
+    
+    current_dir = Path(__file__).parent.joinpath("themes")
+    
+    if platform.system() == "Windows":
+        script_path = current_dir / "choose_starship_theme.ps1"
+        try:
+            subprocess.run(["pwsh", "-File", str(script_path)], check=True)
+        except FileNotFoundError:
+             # Fallback to powershell if pwsh is not available
+            subprocess.run(["powershell", "-File", str(script_path)], check=True)
+    else:
+        script_path = current_dir / "choose_starship_theme.sh"
+        # Ensure executable
+        os.chmod(script_path, 0o755)
+        subprocess.run(["bash", str(script_path)])
+
+
+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
+    msg = typer.style("Error: ", fg=typer.colors.RED) + f"Unknown asset type: {which}"
+    typer.echo(msg)
+
+
+def list_devices() -> None:
+    """🔗 List available mountable devices."""
+    import machineconfig.scripts.python.helpers.helpers_devops.cli_config_mount as mount_module
+    mount_module.list_devices()
+
+
+def mount_device(
+    device_query: Annotated[str | None, typer.Option("--device", "-d", help="Device query (path, key, or label).")] = None,
+    mount_point: Annotated[str | None, typer.Option("--mount-point", "-p", help="Mount point (use '-' for default on macOS).")] = None,
+    interactive: Annotated[bool, typer.Option("--interactive", "-i", help="Pick device and mount point interactively.")] = False,
+) -> None:
+    """🔗 Mount a device to a mount point."""
+    import machineconfig.scripts.python.helpers.helpers_devops.cli_config_mount as mount_module
+    if interactive:
+        mount_module.mount_interactive()
+        return
+    if device_query is None or mount_point is None:
+        msg = typer.style("Error: ", fg=typer.colors.RED) + "--device and --mount-point are required unless --interactive is set"
+        typer.echo(msg)
+        raise typer.Exit(2)
+    mount_module.mount_device(device_query=device_query, mount_point=mount_point)
+
+
+def get_app():
+    config_apps = typer.Typer(help="⚙️ [c] configuration subcommands", no_args_is_help=True, add_help_option=True, add_completion=False)
+    config_apps.command("sync", no_args_is_help=True, help="🔗 [s] Sync dotfiles.")(create_links_export.main_from_parser)
+    config_apps.command("s", no_args_is_help=True, help="Sync dotfiles.", hidden=True)(create_links_export.main_from_parser)
+
+    config_apps.command("register", no_args_is_help=True, help="🔗 [r] Register dotfiles agains user mapper.toml")(dotfile_module.register_dotfile)
+    config_apps.command("r", no_args_is_help=True,  hidden=True)(dotfile_module.register_dotfile)
+
+    config_apps.command("export-dotfiles", no_args_is_help=True, help="🔗 [e] Export dotfiles for migration to new machine.")(dotfile_module.export_dotfiles)
+    config_apps.command("e", no_args_is_help=True, help="Export dotfiles for migration to new machine.", hidden=True)(dotfile_module.export_dotfiles)
+    config_apps.command("import-dotfiles", no_args_is_help=False, help="🔗 [i] Import dotfiles from exported archive.")(dotfile_module.import_dotfiles)
+    config_apps.command("i", no_args_is_help=False, help="Import dotfiles from exported archive.", hidden=True)(dotfile_module.import_dotfiles)
+
+    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("list-devices", no_args_is_help=False, help="🔗 [l] List available devices for mounting.")(list_devices)
+    config_apps.command("l", no_args_is_help=False, help="List available devices for mounting.", hidden=True)(list_devices)
+    config_apps.command("mount", no_args_is_help=True, help="🔗 [m] Mount a device to a mount point.")(mount_device)
+    config_apps.command("m", no_args_is_help=True, help="Mount a device to a mount point.", hidden=True)(mount_device)
+
+
+    return config_apps

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

@@ -0,0 +1,274 @@
+
+"""Like yadm and dotter."""
+
+from git import Optional
+from machineconfig.profile.create_links_export import ON_CONFLICT_LOOSE, ON_CONFLICT_MAPPER, METHOD_LOOSE, METHOD_MAP
+from typing import Annotated, Literal
+from pathlib import Path
+import typer
+
+from machineconfig.utils.source_of_truth import CONFIG_ROOT
+BACKUP_ROOT_PRIVATE = Path.home().joinpath("dotfiles/machineconfig/mapper/files")
+BACKUP_ROOT_PUBLIC = Path(CONFIG_ROOT).joinpath("dotfiles/mapper")
+
+
+
+def _write_to_user_mapper(section: str, entry_name: str, original_path: Path, self_managed_path: Path, method: Literal["symlink", "copy"], is_contents: bool, os_filter: str) -> Path:
+    from machineconfig.profile.create_links import USER_MAPPER_PATH
+    mapper_path = USER_MAPPER_PATH
+    mapper_path.parent.mkdir(parents=True, exist_ok=True)
+    if mapper_path.exists():
+        content = mapper_path.read_text(encoding="utf-8")
+    else:
+        content = "# User-defined config file mappings\n# Created by `d c` CLI tool\n\n"
+    home = Path.home()
+    original_str = f"~/{original_path.relative_to(home)}" if original_path.is_relative_to(home) else original_path.as_posix()
+    self_managed_str = f"~/{self_managed_path.relative_to(home)}" if self_managed_path.is_relative_to(home) else self_managed_path.as_posix()
+    entry_dict_parts: list[str] = [f"original = '{original_str}'", f"self_managed = '{self_managed_str}'"]
+    if is_contents:
+        entry_dict_parts.append("contents = true")
+    if method == "copy":
+        entry_dict_parts.append("copy = true")
+    entry_dict_parts.append(f"os = '{os_filter}'")
+    entry_line = f"{entry_name} = {{ {', '.join(entry_dict_parts)} }}"
+    section_header = f"[{section}]"
+    if section_header in content:
+        lines = content.split("\n")
+        new_lines: list[str] = []
+        in_section = False
+        entry_updated = False
+        for line in lines:
+            if line.strip().startswith("[") and line.strip().endswith("]"):
+                if in_section and not entry_updated:
+                    new_lines.append(entry_line)
+                    entry_updated = True
+                in_section = line.strip() == section_header
+            if in_section and line.strip().startswith(f"{entry_name} ="):
+                new_lines.append(entry_line)
+                entry_updated = True
+                continue
+            new_lines.append(line)
+        if in_section and not entry_updated:
+            new_lines.append(entry_line)
+        content = "\n".join(new_lines)
+    else:
+        content = content.rstrip() + f"\n\n{section_header}\n{entry_line}\n"
+    mapper_path.write_text(content, encoding="utf-8")
+    return mapper_path
+
+def record_mapping(orig_path: Path, new_path: Path, method: METHOD_LOOSE, section: str, os_filter: str) -> None:
+    entry_name = orig_path.stem.replace(".", "_").replace("-", "_")
+    method_resolved = METHOD_MAP[method]
+    mapper_file = _write_to_user_mapper(section=section, entry_name=entry_name, original_path=orig_path, self_managed_path=new_path, method=method_resolved, is_contents=False, os_filter=os_filter)
+    home = Path.home()
+    orig_display = f"~/{orig_path.relative_to(home)}" if orig_path.is_relative_to(home) else orig_path.as_posix()
+    new_display = f"~/{new_path.relative_to(home)}" if new_path.is_relative_to(home) else new_path.as_posix()
+    from rich.console import Console
+    from rich.panel import Panel
+    console = Console()
+    console.print(Panel(f"📝 Mapping recorded in: [cyan]{mapper_file}[/cyan]\n[{section}]\n{entry_name} = {{ original = '{orig_display}', self_managed = '{new_display}', os = '{os_filter}' }}", title="Mapper Entry Saved", border_style="cyan", padding=(1, 2),))
+
+
+def get_backup_path(orig_path: Path, sensitivity: Literal["private", "v", "public", "b"], destination: Optional[str], shared: bool) -> Path:
+    match sensitivity:
+        case "private" | "v":
+            backup_root = BACKUP_ROOT_PRIVATE
+        case "public" | "b":
+            backup_root = BACKUP_ROOT_PUBLIC
+    if destination is None:
+        if shared:
+            new_path = backup_root.joinpath("shared").joinpath(orig_path.name)
+        else:
+            new_path = backup_root.joinpath(orig_path.relative_to(Path.home()))
+    else:
+        if shared:
+            dest_path = Path(destination).expanduser().absolute()
+            new_path = dest_path.joinpath("shared").joinpath(orig_path.name)
+        else:
+            dest_path = Path(destination).expanduser().absolute()
+            new_path = dest_path.joinpath(orig_path.name)
+    return new_path
+
+
+def get_original_path_from_backup_path(backup_path: Path, sensitivity: Literal["private", "v", "public", "b"], destination: Optional[str], shared: bool) -> Path:
+    match sensitivity:
+        case "private" | "v":
+            backup_root = BACKUP_ROOT_PRIVATE
+        case "public" | "b":
+            backup_root = BACKUP_ROOT_PUBLIC
+    if destination is None:
+        if shared:
+            relative_part = backup_path.relative_to(backup_root.joinpath("shared"))
+        else:
+            relative_part = backup_path.relative_to(backup_root)
+        original_path = Path.home().joinpath(relative_part)
+    else:
+        dest_path = Path(destination).expanduser().absolute()
+        if shared:
+            relative_part = backup_path.relative_to(dest_path.joinpath("shared"))
+        else:
+            relative_part = backup_path.relative_to(dest_path)
+        original_path = Path.home().joinpath(relative_part)
+    return original_path
+
+
+def register_dotfile(
+    file: Annotated[str, typer.Argument(help="file/folder path.")],
+    method: Annotated[METHOD_LOOSE, 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[Optional[str], typer.Option("--destination", "-d", help="destination folder (override the default, use at your own risk)")] = None,
+    section: Annotated[str, typer.Option("--section", "-se", help="Section name in mapper_dotfiles.toml to record this mapping.")] = "default",
+    os_filter: Annotated[str, typer.Option("--os", help="Comma-separated OS list or 'any' to apply everywhere.")] = "any",
+    shared: Annotated[bool, typer.Option("--shared", "-sh", help="Whether the config file is shared across destinations directory.")] = False,
+    record: Annotated[bool, typer.Option("--record", "-r", help="Record the mapping in user's mapper.toml")] = True,
+    ) -> None:
+    from rich.console import Console
+    from rich.panel import Panel
+    from machineconfig.utils.links import symlink_map, copy_map
+    console = Console()
+    orig_path = Path(file).expanduser().absolute()
+    new_path = get_backup_path(orig_path=orig_path, sensitivity=sensitivity, destination=destination, shared=shared)
+    if not orig_path.exists() and not new_path.exists():
+        console.print(f"[red]Error:[/] Neither original file nor self-managed file exists:\n  Original: {orig_path}\n  Self-managed: {new_path}")
+        raise typer.Exit(code=1)
+    new_path.parent.mkdir(parents=True, exist_ok=True)
+    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:
+                msg = typer.style("Error: ", fg=typer.colors.RED) + str(e)
+                typer.echo(msg)
+                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:
+                msg = typer.style("Error: ", fg=typer.colors.RED) + str(e)
+                typer.echo(msg)
+                typer.Exit(code=1)
+                return
+        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),))
+    if record:
+        record_mapping(orig_path=orig_path, new_path=new_path, method=method, section=section, os_filter=os_filter)
+
+
+def export_dotfiles(
+        pwd: Annotated[str, typer.Argument(..., help="Password for zip encryption")],
+        over_internet: Annotated[bool, typer.Option("--over-internet", "-i", help="Use internet-based transfer (wormhole-magic)")] = False,
+        over_ssh: Annotated[bool, typer.Option("--over-ssh", "-s", help="Use SSH-based transfer (scp) to a remote machine")] = False,
+        ):
+    """🔗 Export dotfiles for migration to new machine."""
+    if over_ssh:
+        code_sample = """ftpx ~/dotfiles user@remote_host:^ -z"""
+        print("🔗 Exporting dotfiles via SSH-based transfer (scp).")
+        print(f"💡 Run the following command on your local machine to copy dotfiles to the remote machine:\n{code_sample}")
+        remote_address = typer.prompt("Enter the remote machine address (user@host) to copy dotfiles to ")
+        code_concrete = f"fptx ~/dotfiles {remote_address}:^ -z"
+        from machineconfig.utils.code import run_shell_script
+        run_shell_script(code_concrete, display_script=True, clean_env=False)
+    dotfiles_dir = Path.home().joinpath("dotfiles")
+    if not dotfiles_dir.exists() or not dotfiles_dir.is_dir():
+        print(f"❌ Dotfiles directory does not exist: {dotfiles_dir}")
+        raise typer.Exit(code=1)
+    dotfiles_zip = Path.home().joinpath("dotfiles.zip")
+    if dotfiles_zip.exists():
+        dotfiles_zip.unlink()
+    import shutil
+    zipfile = shutil.make_archive(base_name=str(dotfiles_zip)[:-4], format="zip", root_dir=str(dotfiles_dir), base_dir=".", verbose=False)
+    from machineconfig.utils.io import encrypt
+    zipfile_enc_bytes = encrypt(
+        msg=Path(zipfile).read_bytes(),
+        pwd=pwd,
+    )
+    Path(zipfile).unlink()
+    zipfile_enc_path = Path(f"{zipfile}.enc")
+    if zipfile_enc_path.exists():
+        zipfile_enc_path.unlink()
+    zipfile_enc_path.write_bytes(zipfile_enc_bytes)
+    print(f"✅ Dotfiles exported to: {zipfile_enc_path}")
+    if over_internet:
+        # rm ~/dotfiles.zip || true
+        # ouch c ~/dotfiles dotfiles.zip
+        # # INSECURE OVER INTERNET: uvx wormhole-magic send ~/dotfiles.zip
+        raise NotImplementedError("Internet-based transfer not yet implemented.")
+    else:
+        # devops network share-server --no-auth ./dotfiles.zip
+        import machineconfig.scripts.python.helpers.helpers_devops.cli_share_server as cli_share_server
+        from  machineconfig.scripts.python.helpers.helpers_network.address import select_lan_ipv4
+        localipv4 = select_lan_ipv4(prefer_vpn=False)
+        port = 8888
+        msg = f"""On the remote machine, run the following:
+d c i -u http://{localipv4}:{port} -p {pwd}
+"""
+        from machineconfig.utils.accessories import display_with_flashy_style
+        display_with_flashy_style(msg=msg, title="Remote Machine Instructions",)
+        cli_share_server.web_file_explorer(
+            path=str(zipfile_enc_path),
+            no_auth=True,
+            port=port,
+            # bind_address="
+        )
+
+
+def import_dotfiles(
+        url: Annotated[Optional[str], typer.Option(..., "--url", "-u", help="URL or local path to the encrypted dotfiles zip")] = None,
+        pwd: Annotated[Optional[str], typer.Option(..., "--pwd", "-p", help="Password for zip decryption")] = None,
+        use_ssh: Annotated[bool, typer.Option("--use-ssh", "-s", help="Use SSH-based transfer (scp) from a remote machine that has dotfiles.")]=False,
+        ):  
+    # # INSECURE cd $HOME; uvx wormhole-magic receive dotfiles.zip.enc --accept-file
+    # ☁️  [bold blue]Method 3: USING INTERNET SECURE SHARE[/bold blue]
+    #     [dim]cd ~
+    #     cloud copy SHARE_URL . --config ss[/dim]
+    if use_ssh:
+        print("🔗 Importing dotfiles via SSH-based transfer (scp).")
+        code = """fptx $USER@$(hostname):^ ~/dotfiles -z"""
+        print(f"💡 Run the following command on the remote machine that has the dotfiles:\n{code}")
+        url = typer.prompt("Enter the remote machine address (user@host) to copy dotfiles from ")
+        code_concrete = f"fptx {url}:^ ~/dotfiles -z"
+        from machineconfig.utils.code import run_shell_script
+        run_shell_script(code_concrete, display_script=True, clean_env=False)
+        print("✅ Dotfiles copied via SSH.")
+        return
+    if url is None:
+        url = typer.prompt("Enter the URL or local path to the encrypted dotfiles zip (e..g 192.168.20.4:8888) ")
+    if pwd is None:
+        pwd = typer.prompt("Enter the password for zip decryption", hide_input=True)
+    from machineconfig.scripts.python.helpers.helpers_utils.download import download
+    downloaded_file = download(url=url, decompress=False, output_dir=str(Path.home()))
+    if downloaded_file is None or not downloaded_file.exists():
+        print(f"❌ Failed to download file from URL: {url}")
+        raise typer.Exit(code=1)
+    zipfile_enc_path = downloaded_file
+    from machineconfig.utils.io import decrypt
+    zipfile_bytes = decrypt(
+        token=zipfile_enc_path.read_bytes(),
+        pwd=pwd,
+    )
+    zipfile_path = Path(str(zipfile_enc_path)[:-4])
+    if zipfile_path.exists():
+        print(f"⚠️  WARNING: Overwriting existing file: {zipfile_path}")
+        zipfile_path.unlink()
+    zipfile_path.write_bytes(zipfile_bytes)
+    print(f"✅ Decrypted zip file saved to: {zipfile_path}")
+    import zipfile
+    if Path.home().joinpath("dotfiles").exists():
+        print(f"⚠️  WARNING: Overwriting existing directory: {Path.home().joinpath('dotfiles')}")
+        import shutil
+        shutil.rmtree(Path.home().joinpath("dotfiles"))
+    with zipfile.ZipFile(zipfile_path, 'r') as zip_ref:
+        zip_ref.extractall(Path.home().joinpath("dotfiles"))
+    print(f"✅ Dotfiles extracted to: {Path.home().joinpath('dotfiles')}")
+    zipfile_path.unlink()
+
+
+def arg_parser() -> None:
+    typer.run(register_dotfile)
+
+
+if __name__ == "__main__":
+    arg_parser()