machineconfig 3.3__py3-none-any.whl → 3.5__py3-none-any.whl

machineconfig/scripts/python/ai/solutions/gemini/gemini.py

@@ -0,0 +1,14 @@
+from pathlib import Path
+
+from machineconfig.scripts.python.ai.solutions._shared import get_generic_instructions_path
+from machineconfig.utils.source_of_truth import LIBRARY_ROOT
+
+def build_configuration(repo_root: Path) -> None:
+    instructions_path = get_generic_instructions_path()
+    repo_root.joinpath("GEMINI.md").write_text(data=instructions_path.read_text(encoding="utf-8"), encoding="utf-8")
+
+    gemini_dir = repo_root.joinpath(".gemini")
+    settings_source_path = LIBRARY_ROOT.joinpath("scripts/python/ai/solutions/gemini/settings.json")
+    gemini_dir.mkdir(parents=True, exist_ok=True)
+
+    settings_source_path.write_text(data=settings_source_path.read_text(encoding="utf-8"), encoding="utf-8")

machineconfig/scripts/python/ai/solutions/generic.py

@@ -0,0 +1,41 @@
+from pathlib import Path
+
+from machineconfig.utils.source_of_truth import LIBRARY_ROOT
+
+
+def create_dot_scripts(repo_root: Path) -> None:
+    scripts_dir = LIBRARY_ROOT.joinpath("scripts/python/ai/scripts")
+    target_dir = repo_root.joinpath(".scripts")
+    target_dir.mkdir(parents=True, exist_ok=True)
+    for script_path in scripts_dir.iterdir():
+        target_dir.joinpath(script_path.name).write_text(data=script_path.read_text(encoding="utf-8"), encoding="utf-8")
+
+
+def adjust_gitignore(repo_root: Path) -> None:
+    dot_git_ignore_path = repo_root.joinpath(".gitignore")
+    if dot_git_ignore_path.exists() is False:
+        return
+
+    dot_git_ignore_content = dot_git_ignore_path.read_text(encoding="utf-8")
+    entries_to_add: list[str] = []
+    required_entries: list[str] = [
+        ".links",
+        "notebooks",
+        ".ai",
+        ".scripts",
+        "GEMINI.md",
+        "CLAUDE.md",
+        ".cursor",
+        ".github/instructions",
+        ".github/chatmodes",
+        ".github/prompts",
+    ]
+
+    for entry in required_entries:
+        if entry not in dot_git_ignore_content:
+            entries_to_add.append(entry)
+
+    if len(entries_to_add) == 0:
+        return
+
+    dot_git_ignore_path.write_text(data=dot_git_ignore_content + "\n" + "\n".join(entries_to_add), encoding="utf-8")

machineconfig/scripts/python/ai/solutions/kilocode/privacy.md

@@ -0,0 +1,3 @@
+
+# disable usage and erroror reports to kilocode in About/Export page.
+# Disable model api provider data collection.

machineconfig/scripts/python/ai/solutions/opencode/opencode.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [".github/instructions/*.md"]
+}

machineconfig/scripts/python/ai/solutions/opencode/opencode.py

@@ -0,0 +1 @@
+

machineconfig/scripts/python/choose_wezterm_theme.py

@@ -3,7 +3,7 @@ Choose a theme for Wezterm
 """
 
 from machineconfig.utils.options import choose_one_option
-from machineconfig.utils.path_reduced import PathExtended
+from machineconfig.utils.path_extended import PathExtended
 from typing import Any
 import time
 from rich.panel import Panel

machineconfig/scripts/python/cloud_copy.py

@@ -2,7 +2,7 @@
 CC
 """
 
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 from tenacity import retry, stop_after_attempt, wait_chain, wait_fixed
 import getpass
 import argparse
@@ -14,7 +14,7 @@ from machineconfig.scripts.python.helpers.cloud_helpers import ArgsDefaults, Arg
 from rich.console import Console
 from rich.panel import Panel
 from rich.progress import Progress
-from machineconfig.utils.utils2 import pprint
+from machineconfig.utils.accessories import pprint
 
 console = Console()
 

machineconfig/scripts/python/cloud_mount.py

@@ -1,8 +1,8 @@
 """Cloud mount script"""
 
 from machineconfig.utils.options import choose_one_option
-from machineconfig.utils.utils2 import read_ini
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.io import read_ini
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 
 import platform
 import argparse

machineconfig/scripts/python/cloud_repo_sync.py

@@ -2,9 +2,10 @@
 
 from pathlib import Path
 import git
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.io import read_ini
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 from machineconfig.utils.terminal import Terminal
-from machineconfig.utils.utils2 import randstr, read_ini
+from machineconfig.utils.accessories import randstr
 
 from machineconfig.scripts.python.helpers.repo_sync_helpers import fetch_dotfiles
 from machineconfig.utils.source_of_truth import CONFIG_PATH, DEFAULTS_PATH

machineconfig/scripts/python/croshell.py

@@ -5,8 +5,8 @@ croshell
 """
 
 import argparse
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
-from machineconfig.utils.utils2 import randstr
+from machineconfig.utils.path_extended import PathExtended as PathExtended
+from machineconfig.utils.accessories import randstr
 
 from machineconfig.utils.options import display_options
 from machineconfig.utils.ve import get_ve_activate_line
@@ -21,8 +21,10 @@ console = Console()
 
 def add_print_header_pycode(path: str, title: str):
     return f"""
-# from machineconfig.utils.path_reduced import P as PathExtended
-from crocodile.file_management import P as PathExtended
+try:
+    from crocodile.file_management import P as PathExtended
+except ImportError:
+    from machineconfig.utils.path_reduced import PathExtended
 pycode = PathExtended(r'{path}').read_text(encoding="utf-8")
 pycode = pycode.split("except Exception: print(pycode)")[2]
 
@@ -160,10 +162,13 @@ def build_parser():
     preprogram = """
 
 #%%
-from crocodile.croshell import *
+try:
+    from crocodile.croshell import *
+    print_header()
+    print_logo(logo="crocodile")
+except ImportError:
+    print("Crocodile not found, skipping import.")
 from pathlib import Path
-print_header()
-print_logo(logo="crocodile")
 print(f"🐊 Crocodile Shell | Running @ {Path.cwd()}")
 """
 

machineconfig/scripts/python/devops_add_identity.py

@@ -1,7 +1,7 @@
 """ID"""
 
 # from platform import system
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 from machineconfig.utils.options import display_options
 from rich.panel import Panel
 from rich.text import Text

machineconfig/scripts/python/devops_add_ssh_key.py

@@ -3,7 +3,7 @@
 from platform import system
 from machineconfig.utils.source_of_truth import LIBRARY_ROOT
 from machineconfig.utils.options import display_options
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 from rich.console import Console
 from rich.panel import Panel
 from rich import box  # Import box

machineconfig/scripts/python/devops_backup_retrieve.py

@@ -1,8 +1,8 @@
 """BR: Backup and Retrieve"""
 
 # import subprocess
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
-from machineconfig.utils.utils2 import read_ini, read_toml
+from machineconfig.utils.io import read_ini
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 from machineconfig.utils.source_of_truth import LIBRARY_ROOT, DEFAULTS_PATH
 from machineconfig.utils.code import print_code
 from machineconfig.utils.options import choose_cloud_interactively, choose_multiple_options
@@ -11,6 +11,7 @@ from platform import system
 from typing import Any, Literal, Optional
 from rich.console import Console
 from rich.panel import Panel
+import tomllib
 
 
 OPTIONS = Literal["BACKUP", "RETRIEVE"]
@@ -26,7 +27,7 @@ def main_backup_retrieve(direction: OPTIONS, which: Optional[str] = None) -> Non
         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()
 
-    bu_file: dict[str, Any] = read_toml(LIBRARY_ROOT.joinpath("profile/backup.toml"))
+    bu_file: dict[str, Any] = tomllib.loads(LIBRARY_ROOT.joinpath("profile/backup.toml").read_text(encoding="utf-8"))
 
     console.print(Panel(f"🧰 LOADING BACKUP CONFIGURATION\n📄 File: {LIBRARY_ROOT.joinpath('profile/backup.toml')}", title="[bold blue]Backup Configuration[/bold blue]", border_style="blue"))
 

machineconfig/scripts/python/devops_update_repos.py

@@ -3,9 +3,9 @@
 import git
 from pathlib import Path
 from machineconfig.scripts.python.repos_helper_update import RepositoryUpdateResult, run_uv_sync, update_repository
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 from machineconfig.utils.source_of_truth import DEFAULTS_PATH
-from machineconfig.utils.utils2 import read_ini
+from machineconfig.utils.io import read_ini
 
 
 def _display_summary(results: list[RepositoryUpdateResult]) -> None:

machineconfig/scripts/python/dotfile.py

@@ -1,6 +1,6 @@
 """Like yadm and dotter."""
 
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 from machineconfig.utils.links import symlink_func
 from machineconfig.utils.source_of_truth import LIBRARY_ROOT, REPO_ROOT
 import argparse

machineconfig/scripts/python/fire_agents.py

@@ -17,7 +17,7 @@ from machineconfig.scripts.python.fire_agents_help_search import search_files_by
 from machineconfig.scripts.python.fire_agents_load_balancer import chunk_prompts, SPLITTING_STRATEGY, DEFAULT_AGENT_CAP
 from machineconfig.utils.options import choose_one_option
 from machineconfig.utils.schemas.layouts.layout_types import TabConfig, LayoutConfig
-from machineconfig.utils.ve import get_repo_root
+from machineconfig.utils.accessories import get_repo_root
 
 SEARCH_STRATEGIES: TypeAlias = Literal["file_path", "keyword_search", "filename_pattern"]
 
@@ -151,7 +151,7 @@ manager.run_monitoring_routine()
 
 
 def split_too_many_tabs_to_run_in_sequential_sessions(layout_tabs: list[TabConfig], every: int):
-    from machineconfig.utils.utils2 import split
+    from machineconfig.utils.accessories import split
     from machineconfig.cluster.sessions_managers.zellij_local_manager import ZellijLocalManager
 
     for idx, layout_tabs_chunk in enumerate(split(layout_tabs, every=every)):
@@ -163,7 +163,7 @@ def split_too_many_tabs_to_run_in_sequential_sessions(layout_tabs: list[TabConfi
 
 
 def split_too_many_layouts_to_run_in_sequential_sessions(layouts: list[LayoutConfig], every: int):
-    from machineconfig.utils.utils2 import split
+    from machineconfig.utils.accessories import split
     from machineconfig.cluster.sessions_managers.zellij_local_manager import ZellijLocalManager
 
     for _idx, layout_chunk in enumerate(split(layouts, every=every)):

machineconfig/scripts/python/fire_agents_help_launch.py

@@ -1,4 +1,4 @@
-from machineconfig.utils.utils2 import randstr
+from machineconfig.utils.accessories import randstr
 
 import random
 import shlex
@@ -14,7 +14,7 @@ AGENT_NAME_FORMATTER = "agent_{idx}_cmd.sh"  # e.g., agent_0_cmd.sh
 
 
 def get_gemini_api_keys() -> list[str]:
-    from machineconfig.utils.utils2 import read_ini
+    from machineconfig.utils.io import read_ini
 
     config = read_ini(Path.home().joinpath("dotfiles/creds/llm/gemini/api_keys.ini"))
     res: list[str] = []

machineconfig/scripts/python/fire_jobs.py

@@ -11,17 +11,17 @@ from machineconfig.scripts.python.helpers.helpers4 import search_for_files_of_in
 from machineconfig.scripts.python.helpers.helpers4 import convert_kwargs_to_fire_kwargs_str
 from machineconfig.scripts.python.helpers.helpers4 import parse_pyfile
 from machineconfig.scripts.python.helpers.helpers4 import get_import_module_code
-from machineconfig.utils.ve import get_repo_root, get_ve_activate_line, get_ve_path_and_ipython_profile
+from machineconfig.utils.ve import get_ve_activate_line, get_ve_path_and_ipython_profile
 from machineconfig.utils.options import display_options, choose_one_option
-from machineconfig.utils.path import match_file_name, sanitize_path
+from machineconfig.utils.path_helper import match_file_name, sanitize_path
 
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
-from machineconfig.utils.io_save import save_toml
-from machineconfig.utils.utils2 import randstr, read_toml
+from machineconfig.utils.path_extended import PathExtended as PathExtended
+from machineconfig.utils.accessories import get_repo_root, randstr
 from machineconfig.scripts.python.fire_jobs_args_helper import get_args, FireJobArgs, extract_kwargs
 import platform
 from typing import Optional
 from pathlib import Path
+import tomllib
 # import os
 
 
@@ -113,7 +113,7 @@ def route(args: FireJobArgs) -> None:
                     toml_path = toml_path_maybe
             if toml_path is not None:
                 print(f"📄 Reading config.toml @ {toml_path}")
-                config = read_toml(toml_path)
+                config = tomllib.loads(toml_path.read_text(encoding="utf-8"))
                 if "server" in config:
                     if "port" in config["server"]:
                         port = config["server"]["port"]
@@ -121,7 +121,7 @@ def route(args: FireJobArgs) -> None:
                 if repo_root is not None:
                     secrets_template_path = PathExtended.home().joinpath(f"dotfiles/creds/streamlit/{PathExtended(repo_root).name}/{choice_file.name}/secrets.toml")
                     if args.environment != "" and not secrets_path.exists() and secrets_template_path.exists():
-                        secrets_template = read_toml(secrets_template_path)
+                        secrets_template = tomllib.loads(secrets_template_path.read_text(encoding="utf-8"))
                         if args.environment == "ip":
                             host_url = f"http://{local_ip_v4}:{port}/oauth2callback"
                         elif args.environment == "localhost":
@@ -134,7 +134,7 @@ def route(args: FireJobArgs) -> None:
                             secrets_template["auth"]["redirect_uri"] = host_url
                             secrets_template["auth"]["cookie_secret"] = randstr(35)
                             secrets_template["auth"]["auth0"]["redirect_uri"] = host_url
-                            save_toml(obj=secrets_template, path=secrets_path)
+                            # save_toml(obj=secrets_template, path=secrets_path)
                         except Exception as ex:
                             print(ex)
                             raise ex

machineconfig/scripts/python/fire_jobs_layout_helper.py

@@ -3,8 +3,8 @@ from machineconfig.utils.schemas.layouts.layout_types import LayoutConfig, Layou
 from typing import Optional, TYPE_CHECKING
 from machineconfig.scripts.python.helpers.helpers4 import search_for_files_of_interest
 from machineconfig.utils.options import choose_one_option
-from machineconfig.utils.path import match_file_name, sanitize_path
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.path_helper import match_file_name, sanitize_path
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 
 if TYPE_CHECKING:
     from machineconfig.scripts.python.fire_jobs_args_helper import FireJobArgs

machineconfig/scripts/python/ftpx.py

@@ -8,9 +8,9 @@ Currently, the only way to work around this is to predifine the host in ~/.ssh/c
 
 import argparse
 from machineconfig.utils.ssh import SSH
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 from machineconfig.scripts.python.helpers.helpers2 import ES
-from machineconfig.utils.utils2 import pprint
+from machineconfig.utils.accessories import pprint
 
 
 def main():

machineconfig/scripts/python/helpers/cloud_helpers.py

@@ -1,5 +1,6 @@
 from pathlib import Path
-from machineconfig.utils.utils2 import pprint, read_json, read_ini
+from machineconfig.utils.io import read_ini, read_json
+from machineconfig.utils.accessories import pprint
 from typing import Optional
 import os
 from machineconfig.utils.source_of_truth import DEFAULTS_PATH

machineconfig/scripts/python/helpers/helpers2.py

@@ -1,6 +1,7 @@
 from machineconfig.scripts.python.helpers.cloud_helpers import Args, ArgsDefaults, absolute, find_cloud_config, get_secure_share_cloud_config
+from machineconfig.utils.io import read_ini
 from machineconfig.utils.source_of_truth import DEFAULTS_PATH
-from machineconfig.utils.utils2 import read_ini, pprint
+from machineconfig.utils.accessories import pprint
 from typing import Optional
 from rich.console import Console
 from rich.panel import Panel
@@ -103,7 +104,7 @@ def parse_cloud_source_target(args: Args, source: str, target: str) -> tuple[str
         if len(source_parts) > 1 and source_parts[1] == ES:  # the source path is to be inferred from target.
             assert ES not in target, f"You can't use expand symbol `{ES}` in both source and target. Cyclical inference dependency arised."
             target_obj = absolute(target)
-            from machineconfig.utils.path_reduced import PathExtended as PathExtended
+            from machineconfig.utils.path_extended import PathExtended as PathExtended
 
             remote_path = PathExtended(target_obj).get_remote_path(os_specific=os_specific, root=root, rel2home=rel2home, strict=False)
             source = f"{cloud}:{remote_path.as_posix()}"
@@ -123,7 +124,7 @@ def parse_cloud_source_target(args: Args, source: str, target: str) -> tuple[str
         if len(target_parts) > 1 and target_parts[1] == ES:  # the target path is to be inferred from source.
             assert ES not in source, "You can't use $ in both source and target. Cyclical inference dependency arised."
             source_obj = absolute(source)
-            from machineconfig.utils.path_reduced import PathExtended as PathExtended
+            from machineconfig.utils.path_extended import PathExtended as PathExtended
 
             remote_path = PathExtended(source_obj).get_remote_path(os_specific=os_specific, root=root, rel2home=rel2home, strict=False)
             target = f"{cloud}:{remote_path.as_posix()}"

machineconfig/scripts/python/helpers/helpers4.py

@@ -3,7 +3,7 @@ import inspect
 import os
 
 # import argparse
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 # from machineconfig.utils.utils import choose_ssh_host
 
 

machineconfig/scripts/python/helpers/repo_sync_helpers.py

@@ -1,8 +1,8 @@
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 from machineconfig.utils.terminal import Terminal
 from machineconfig.scripts.python.get_zellij_cmd import get_zellij_cmd
 from machineconfig.utils.source_of_truth import CONFIG_PATH, DEFAULTS_PATH
-from machineconfig.utils.utils2 import read_ini
+from machineconfig.utils.io import read_ini
 from machineconfig.utils.code import write_shell_script_to_file
 import platform
 from rich.console import Console

machineconfig/scripts/python/mount_nfs.py

@@ -1,6 +1,6 @@
 """NFS mounting script"""
 
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 from machineconfig.utils.ssh import SSH
 from machineconfig.utils.terminal import Terminal
 from machineconfig.utils.options import display_options, choose_ssh_host

machineconfig/scripts/python/mount_ssh.py

@@ -3,7 +3,7 @@
 from platform import system
 from machineconfig.utils.ssh import SSH
 from machineconfig.utils.terminal import Terminal
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 
 from machineconfig.utils.options import choose_ssh_host
 

machineconfig/scripts/python/repos.py

@@ -5,11 +5,13 @@ in the event that username@github.com is not mentioned in the remote url.
 
 """
 
+from machineconfig.utils.io import read_ini
 from machineconfig.utils.source_of_truth import CONFIG_PATH, DEFAULTS_PATH
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
-from machineconfig.utils.utils2 import randstr, read_ini
+from machineconfig.utils.path_extended import PathExtended as PathExtended
+from machineconfig.utils.accessories import randstr
 from machineconfig.scripts.python.repos_helper_update import update_repository
 from machineconfig.scripts.python.repos_helper_record import main as record_repos
+from machineconfig.scripts.python.repos_helper_clone import clone_repos
 
 import argparse
 from enum import Enum
@@ -119,7 +121,7 @@ def main():
     elif args.clone or args.checkout or args.checkout_to_branch:
         print("\n📥 Cloning or checking out repositories...")
         print(">>>>>>>>> Cloning Repos")
-        if not repos_root.exists() or repos_root.name != "repos.json":  # Fixed: use name instead of stem
+        if not repos_root.exists() or repos_root.name != "repos.json":
             repos_root = PathExtended(CONFIG_PATH).joinpath("repos").joinpath(repos_root.rel2home()).joinpath("repos.json")
             if not repos_root.exists():
                 if args.cloud is None:
@@ -130,6 +132,7 @@ def main():
                     assert cloud is not None, f"Path {repos_root} does not exist and cloud was not passed. You can't clone without one of them."
                 repos_root.from_cloud(cloud=cloud, rel2home=True)
         assert (repos_root.exists() and repos_root.name == "repos.json") or args.cloud is not None, f"Path {repos_root} does not exist and cloud was not passed. You can't clone without one of them."
+        clone_repos(spec_path=repos_root, preferred_remote=None, checkout_branch_flag=args.checkout_to_branch, checkout_commit_flag=args.checkout)
 
     elif args.all or args.commit or args.pull or args.push:
         print(f"\n🔄 Performing Git actions on repositories @ `{repos_root}`...")

machineconfig/scripts/python/repos_helper_clone.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from typing import Literal, Optional, cast
+
+from git import Repo as GitRepo
+from git.exc import GitCommandError
+from rich import print as pprint
+from rich.progress import BarColumn, MofNCompleteColumn, Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
+
+from machineconfig.utils.path_extended import PathExtended as PathExtended
+from machineconfig.utils.schemas.repos.repos_types import RepoRecordDict, RepoRecordFile, RepoRemote
+from machineconfig.utils.io import read_json
+
+
+CloneStatus = Literal["cloned", "skipped", "failed"]
+
+
+def choose_remote(remotes: list[RepoRemote], preferred_remote: Optional[str]) -> Optional[RepoRemote]:
+    if preferred_remote is not None:
+        for remote in remotes:
+            if remote["name"] == preferred_remote:
+                return remote
+    for remote in remotes:
+        if remote["name"] == "origin":
+            return remote
+    return remotes[0] if len(remotes) > 0 else None
+
+
+def ensure_destination(parent_dir: str, name: str) -> PathExtended:
+    parent_path = PathExtended(parent_dir).expanduser().absolute()
+    parent_path.mkdir(parents=True, exist_ok=True)
+    return parent_path.joinpath(name)
+
+
+def checkout_branch(repo: GitRepo, branch: str) -> bool:
+    if branch == "DETACHED":
+        return False
+    current_branch = repo.active_branch.name if not repo.head.is_detached else None
+    if current_branch == branch:
+        return False
+    repo.git.checkout(branch)
+    return True
+
+
+def checkout_commit(repo: GitRepo, commit: str) -> bool:
+    if commit in {"", "UNKNOWN"}:
+        return False
+    current_commit = repo.head.commit.hexsha
+    if current_commit == commit:
+        return False
+    repo.git.checkout(commit)
+    return True
+
+
+def clone_single_repo(repo_spec: RepoRecordDict, preferred_remote: Optional[str], checkout_branch_flag: bool, checkout_commit_flag: bool) -> tuple[CloneStatus, str]:
+    destination = ensure_destination(parent_dir=repo_spec["parentDir"], name=repo_spec["name"])
+    repo_path = destination.joinpath(".git")
+    remotes = repo_spec["remotes"]
+    if len(remotes) == 0:
+        return ("failed", f"No remotes configured for {destination}")
+    remote = choose_remote(remotes=remotes, preferred_remote=preferred_remote)
+    if remote is None:
+        return ("failed", f"No usable remote for {destination}")
+    repo = None
+    status: CloneStatus
+    message: str
+    if destination.exists() and repo_path.exists():
+        status = "skipped"
+        repo = GitRepo(str(destination))
+        message = f"Skipped cloning for {destination}; existing repository reused"
+    elif destination.exists() and not repo_path.exists():
+        return ("failed", f"Destination exists but is not a git repository: {destination}")
+    else:
+        try:
+            pprint(f"📥 Cloning {repo_spec['name']} from {remote['url']}")
+            repo = GitRepo.clone_from(url=remote["url"], to_path=str(destination))
+            status = "cloned"
+            message = f"Cloned {destination}"
+        except Exception as err:  # noqa: BLE001
+            return ("failed", f"Clone failed for {destination}: {err}")
+    assert repo is not None
+    checkout_summary: list[str] = []
+    try:
+        if checkout_branch_flag:
+            if checkout_branch(repo=repo, branch=repo_spec["version"]["branch"]):
+                checkout_summary.append(f"branch {repo_spec['version']['branch']}")
+        if checkout_commit_flag:
+            if checkout_commit(repo=repo, commit=repo_spec["version"]["commit"]):
+                checkout_summary.append(f"commit {repo_spec['version']['commit'][:8]}")
+    except GitCommandError as err:
+        return ("failed", f"Checkout failed for {destination}: {err}")
+    if len(checkout_summary) > 0:
+        message = f"{message} | Checked out {' & '.join(checkout_summary)}"
+    return (status, message)
+
+
+def clone_repos(spec_path: PathExtended, preferred_remote: Optional[str], checkout_branch_flag: bool, checkout_commit_flag: bool) -> list[tuple[CloneStatus, str]]:
+    data = cast(RepoRecordFile, read_json(path=spec_path))
+    repos = data["repos"]
+    results: list[tuple[CloneStatus, str]] = []
+    with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}"), BarColumn(), MofNCompleteColumn(), TimeElapsedColumn()) as progress:
+        task_id = progress.add_task("Processing repositories...", total=len(repos))
+        for repo_spec in repos:
+            progress.update(task_id, description=f"Processing {repo_spec['name']}")
+            try:
+                result = clone_single_repo(repo_spec=repo_spec, preferred_remote=preferred_remote, checkout_branch_flag=checkout_branch_flag, checkout_commit_flag=checkout_commit_flag)
+            except Exception as err:  # noqa: BLE001
+                result = ("failed", f"Unexpected error for {repo_spec['name']}: {err}")
+            results.append(result)
+            if result[0] == "failed":
+                pprint(f"❌ {result[1]}")
+            elif result[0] == "cloned":
+                pprint(f"✅ {result[1]}")
+            else:
+                pprint(f"⏭️ {result[1]}")
+            progress.update(task_id, advance=1)
+    success_count = len([status for status, _ in results if status == "cloned"])
+    skip_count = len([status for status, _ in results if status == "skipped"])
+    fail_count = len([status for status, _ in results if status == "failed"])
+    pprint(f"✅ Cloned: {success_count} | ⏭️ Skipped: {skip_count} | ❌ Failed: {fail_count}")
+    return results

machineconfig/scripts/python/repos_helper_record.py

@@ -1,9 +1,9 @@
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 from machineconfig.utils.schemas.repos.repos_types import GitVersionInfo, RepoRecordDict, RepoRemote
 
 from machineconfig.utils.schemas.repos.repos_types import RepoRecordFile
 from machineconfig.utils.source_of_truth import CONFIG_PATH
-from machineconfig.utils.io_save import save_json
+from machineconfig.utils.io import save_json
 
 from typing import Optional
 

machineconfig/scripts/python/start_slidev.py

@@ -4,7 +4,7 @@ slidev
 
 from machineconfig.utils.source_of_truth import CONFIG_PATH
 from machineconfig.utils.code import print_code
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 from machineconfig.utils.terminal import Terminal
 import subprocess
 import platform

machineconfig/scripts/python/wsl_windows_transfer.py

@@ -1,6 +1,6 @@
 """TWSL"""
 
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 import argparse
 import platform
 import getpass

machineconfig/setup_windows/wt_and_pwsh/install_nerd_fonts.py

@@ -4,7 +4,7 @@ https://glitchbone.github.io/vscode-base16-term/#/3024
 
 """
 
-from machineconfig.utils.path_reduced import PathExtended as PathExtended
+from machineconfig.utils.path_extended import PathExtended as PathExtended
 from machineconfig.utils.source_of_truth import LIBRARY_ROOT
 from machineconfig.utils.installer_utils.installer_class import Installer
 import subprocess