machineconfig 3.99__py3-none-any.whl → 7.66__py3-none-any.whl

machineconfig/scripts/python/helpers_navigator/main_app.py

@@ -0,0 +1,272 @@
+"""
+Main TUI application for navigating machineconfig commands.
+"""
+
+import subprocess
+from textual.app import App, ComposeResult
+from textual.widgets import Header, Footer, Input, Tree
+from textual.binding import Binding
+from machineconfig.scripts.python.helpers_navigator.command_builder import CommandBuilderScreen
+from machineconfig.scripts.python.helpers_navigator.command_tree import CommandTree
+from machineconfig.scripts.python.helpers_navigator.command_detail import CommandDetail
+from machineconfig.scripts.python.helpers_navigator.search_bar import SearchBar
+from machineconfig.scripts.python.helpers_navigator.data_models import CommandInfo
+
+
+class CommandNavigatorApp(App[None]):
+    """TUI application for navigating machineconfig commands."""
+
+    CSS = """
+    Screen {
+        layout: grid;
+        grid-size: 2 3;
+        grid-rows: auto 1fr auto;
+        grid-columns: 1fr 1fr;
+        height: 100%;
+        width: 100%;
+    }
+
+    Header {
+        column-span: 2;
+        background: $boost;
+        color: $text;
+        width: 100%;
+    }
+
+    #search-bar {
+        column-span: 2;
+        padding: 1;
+        background: $surface;
+        height: auto;
+        width: 100%;
+    }
+
+    .search-label {
+        width: auto;
+        padding-right: 1;
+    }
+
+    #search-input {
+        width: 1fr;
+    }
+
+    #command-tree {
+        row-span: 1;
+        border: solid $primary;
+        padding: 1;
+        width: 100%;
+        height: 100%;
+    }
+
+    #command-detail {
+        row-span: 1;
+        border: solid $primary;
+        padding: 1;
+        width: 100%;
+        height: 100%;
+    }
+
+    Footer {
+        column-span: 2;
+        background: $boost;
+        width: 100%;
+    }
+
+    Button {
+        margin: 1;
+    }
+
+    CommandBuilderScreen {
+        align: center middle;
+    }
+
+    CommandBuilderScreen > VerticalScroll {
+        width: 80;
+        height: auto;
+        max-height: 90%;
+        background: $surface;
+        border: thick $primary;
+        padding: 2;
+    }
+
+    CommandBuilderScreen .title {
+        margin-bottom: 1;
+    }
+
+    CommandBuilderScreen Label {
+        margin-top: 1;
+        margin-bottom: 0;
+    }
+
+    CommandBuilderScreen Input {
+        margin-bottom: 1;
+    }
+
+    CommandBuilderScreen .buttons {
+        margin-top: 2;
+        height: auto;
+        align: center middle;
+    }
+    """
+
+    BINDINGS = [
+        Binding("q", "quit", "Quit", priority=True),
+        Binding("c", "copy_command", "Copy Command"),
+        Binding("/", "focus_search", "Search"),
+        Binding("?", "help", "Help"),
+        Binding("r", "run_command", "Run Command"),
+        Binding("b", "build_command", "Build Command"),
+    ]
+
+    def compose(self) -> ComposeResult:
+        """Create child widgets for the app."""
+        yield Header(show_clock=True)
+        yield SearchBar(id="search-bar")
+        yield CommandTree("📚 machineconfig Commands", id="command-tree")
+        yield CommandDetail(id="command-detail")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        """Actions when app is mounted."""
+        self.title = "machineconfig Command Navigator"
+        self.sub_title = "Navigate and explore all available commands"
+        tree = self.query_one(CommandTree)
+        tree.focus()
+
+    def on_tree_node_selected(self, event: Tree.NodeSelected[CommandInfo]) -> None:
+        """Handle tree node selection."""
+        command_info = event.node.data
+        detail_widget = self.query_one("#command-detail", CommandDetail)
+        detail_widget.update_command(command_info)
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        """Handle search input changes."""
+        if event.input.id != "search-input":
+            return
+
+        search_term = event.value.lower()
+        tree = self.query_one(CommandTree)
+
+        if not search_term:
+            # Show all nodes - expand all root children
+            for node in tree.root.children:
+                node.expand()
+            return
+
+        # Filter nodes based on search term
+        def filter_tree(node):  # type: ignore
+            if node.data and not node.data.is_group:
+                match = (search_term in node.data.name.lower() or
+                        search_term in node.data.description.lower() or
+                        search_term in node.data.command.lower())
+                return match
+            return False
+
+        # Expand parents of matching nodes by walking through all nodes
+        def walk_nodes(node):  # type: ignore
+            """Recursively walk through tree nodes."""
+            yield node
+            for child in node.children:
+                yield from walk_nodes(child)
+
+        for node in walk_nodes(tree.root):
+            if filter_tree(node):
+                parent = node.parent
+                while parent and parent != tree.root:
+                    parent.expand()
+                    parent = parent.parent  # type: ignore
+
+    def action_copy_command(self) -> None:
+        """Copy the selected command to clipboard."""
+        tree = self.query_one(CommandTree)
+        if tree.cursor_node and tree.cursor_node.data:
+            command = tree.cursor_node.data.command
+            try:
+                import pyperclip  # type: ignore
+                pyperclip.copy(command)
+                self.notify(f"Copied: {command}", severity="information")
+            except ImportError:
+                self.notify("Install pyperclip to enable clipboard support", severity="warning")
+
+    def action_run_command(self) -> None:
+        """Run the selected command without arguments."""
+        tree = self.query_one(CommandTree)
+        if tree.cursor_node and tree.cursor_node.data:
+            command_info = tree.cursor_node.data
+            if command_info.is_group:
+                self.notify("Cannot run command groups directly", severity="warning")
+                return
+
+            self._execute_command(command_info.command)
+
+    def action_build_command(self) -> None:
+        """Open command builder for selected command."""
+        tree = self.query_one(CommandTree)
+        if tree.cursor_node and tree.cursor_node.data:
+            command_info = tree.cursor_node.data
+            if command_info.is_group:
+                self.notify("Cannot build command for groups", severity="warning")
+                return
+
+            self.push_screen(CommandBuilderScreen(command_info), self._handle_builder_result)
+
+    def _handle_builder_result(self, result: str | None) -> None:
+        """Handle result from command builder."""
+        if not result:
+            return
+
+        if result.startswith("EXECUTE:"):
+            command = result[8:]
+            self._execute_command(command)
+        elif result.startswith("COPY:"):
+            command = result[5:]
+            self._copy_to_clipboard(command)
+
+    def _execute_command(self, command: str) -> None:
+        """Execute a shell command."""
+        try:
+            self.notify(f"Executing: {command}", severity="information")
+            result = subprocess.run(command, shell=True, capture_output=True, text=True, timeout=30)
+
+            if result.returncode == 0:
+                output = result.stdout.strip()
+                if output:
+                    self.notify(f"Success: {output[:100]}...", severity="information", timeout=5)
+                else:
+                    self.notify("Command executed successfully", severity="information")
+            else:
+                error = result.stderr.strip() or "Unknown error"
+                self.notify(f"Error: {error[:100]}...", severity="error", timeout=10)
+        except subprocess.TimeoutExpired:
+            self.notify("Command timed out after 30 seconds", severity="warning")
+        except Exception as e:
+            self.notify(f"Failed to execute: {str(e)}", severity="error")
+
+    def _copy_to_clipboard(self, command: str) -> None:
+        """Copy command to clipboard."""
+        try:
+            import pyperclip  # type: ignore
+            pyperclip.copy(command)
+            self.notify(f"Copied: {command}", severity="information")
+        except ImportError:
+            self.notify("Install pyperclip to enable clipboard support", severity="warning")
+
+    def action_focus_search(self) -> None:
+        """Focus the search input."""
+        search_input = self.query_one("#search-input", Input)
+        search_input.focus()
+
+    def action_help(self) -> None:
+        """Show help information."""
+        help_text = """
+        Navigation:
+        - ↑↓: Navigate tree
+        - Enter: Expand/collapse node
+        - /: Focus search
+        - c: Copy command to clipboard
+        - r: Run command directly (no args)
+        - b: Build command with arguments
+        - q: Quit
+        - ?: Show this help
+        """
+        self.notify(help_text, severity="information", timeout=10)

machineconfig/scripts/python/helpers_navigator/search_bar.py

@@ -0,0 +1,15 @@
+"""
+Search bar widget for filtering commands.
+"""
+
+from textual.app import ComposeResult
+from textual.containers import Horizontal
+from textual.widgets import Label, Input
+
+
+class SearchBar(Horizontal):
+    """Search bar widget."""
+
+    def compose(self) -> ComposeResult:
+        yield Label("🔍 Search: ", classes="search-label")
+        yield Input(placeholder="Type to search commands...", id="search-input")

machineconfig/scripts/python/helpers_repos/action.py

@@ -0,0 +1,209 @@
+from machineconfig.scripts.python.helpers_repos.action_helper import GitAction, GitOperationResult, GitOperationSummary, print_git_operations_summary
+from machineconfig.utils.path_extended import PathExtended
+from machineconfig.utils.accessories import randstr
+from machineconfig.scripts.python.helpers_repos.update import update_repository
+
+from typing import Optional, Dict, Any, List, cast
+import concurrent.futures
+import os
+
+from rich import print as pprint
+
+
+def git_action(path: PathExtended, action: GitAction, mess: Optional[str], r: bool, auto_uv_sync: bool) -> GitOperationResult:
+    """Perform git actions using Python instead of shell scripts. Returns detailed operation result."""
+    from git.exc import InvalidGitRepositoryError
+    from git.repo import Repo
+
+    try:
+        repo = Repo(str(path), search_parent_directories=False)
+    except InvalidGitRepositoryError:
+        pprint(f"⚠️ Skipping {path} because it is not a git repository.")
+        if r:
+            results = [git_action(path=sub_path, action=action, mess=mess, r=r, auto_uv_sync=auto_uv_sync) for sub_path in path.search()]
+            # For recursive calls, we need to aggregate results somehow
+            # For now, return success if all recursive operations succeeded
+            all_successful = all(result.success for result in results)
+            return GitOperationResult(
+                repo_path=path,
+                action=action.value,
+                success=all_successful,
+                message=f"Recursive operation: {len([r for r in results if r.success])}/{len(results)} succeeded",
+                is_git_repo=False,
+            )
+        else:
+            return GitOperationResult(repo_path=path, action=action.value, success=False, message="Not a git repository", is_git_repo=False)
+
+    print(f">>>>>>>>> 🔧{action} - {path}")
+    remote_count = len(repo.remotes)
+
+    try:
+        if action == GitAction.commit:
+            if mess is None:
+                mess = "auto_commit_" + randstr()
+
+            # Check if there are changes to commit
+            if repo.is_dirty() or repo.untracked_files:
+                repo.git.add(A=True)  # Stage all changes
+                repo.index.commit(mess)
+                print(f"✅ Committed changes with message: {mess}")
+                return GitOperationResult(
+                    repo_path=path,
+                    action=action.value,
+                    success=True,
+                    message=f"Committed changes with message: {mess}",
+                    had_changes=True,
+                    remote_count=remote_count,
+                )
+            else:
+                print("ℹ️  No changes to commit")
+                return GitOperationResult(
+                    repo_path=path, action=action.value, success=True, message="No changes to commit", had_changes=False, remote_count=remote_count
+                )
+
+        elif action == GitAction.push:
+            if not repo.remotes:
+                print("⚠️ No remotes configured for push")
+                return GitOperationResult(repo_path=path, action=action.value, success=False, message="No remotes configured", remote_count=0)
+
+            success = True
+            failed_remotes = []
+            for remote in repo.remotes:
+                try:
+                    print(f"🚀 Pushing to {remote.url}")
+                    remote.push(repo.active_branch.name)
+                    print(f"✅ Pushed to {remote.name}")
+                except Exception as e:
+                    print(f"❌ Failed to push to {remote.name}: {e}")
+                    failed_remotes.append(f"{remote.name}: {str(e)}")
+                    success = False
+
+            message = "Push successful" if success else f"Push failed for: {', '.join(failed_remotes)}"
+            return GitOperationResult(repo_path=path, action=action.value, success=success, message=message, remote_count=remote_count)
+
+        elif action == GitAction.pull:
+            # Use the enhanced update function with uv sync support
+            try:
+                update_repository(repo, auto_uv_sync=auto_uv_sync, allow_password_prompt=False)
+                print("✅ Pull completed")
+                return GitOperationResult(
+                    repo_path=path, action=action.value, success=True, message="Pull completed successfully", remote_count=remote_count
+                )
+            except Exception as e:
+                print(f"❌ Pull failed: {e}")
+                return GitOperationResult(
+                    repo_path=path, action=action.value, success=False, message=f"Pull failed: {str(e)}", remote_count=remote_count
+                )
+
+    except Exception as e:
+        print(f"❌ Error performing {action} on {path}: {e}")
+        return GitOperationResult(repo_path=path, action=action.value, success=False, message=f"Error: {str(e)}", remote_count=remote_count)
+
+    # This should never be reached, but just in case
+    return GitOperationResult(repo_path=path, action=action.value, success=False, message="Unknown error", remote_count=remote_count)
+
+
+def perform_git_operations(repos_root: PathExtended, pull: bool, commit: bool, push: bool, recursive: bool, auto_uv_sync: bool) -> None:
+    """Perform git operations on all repositories and provide detailed summary."""
+    print(f"\n🔄 Performing Git actions on repositories @ `{repos_root}`...")
+    summary = GitOperationSummary()
+    # Keep track of which operations we are performing
+    operations_performed: List[str] = []
+    if pull:
+        operations_performed.append("pull")
+    if commit:
+        operations_performed.append("commit")
+    if push:
+        operations_performed.append("push")
+
+    # Collect all candidate paths first
+    paths = list(repos_root.search("*"))
+
+    def _process_path(a_path: PathExtended) -> Dict[str, Any]:
+        """Worker that processes a single path and returns metadata and results."""
+        from git.exc import InvalidGitRepositoryError
+        from git.repo import Repo
+
+        result_payload: Dict[str, Any] = {"path": a_path, "is_git": False, "results": [], "repo_remotes_count": 0}
+        print(f"{('Handling ' + str(a_path)).center(80, '-')}")
+
+        try:
+            repo = Repo(str(a_path), search_parent_directories=False)
+        except InvalidGitRepositoryError:
+            result_payload["non_git"] = True
+            pprint(f"⚠️ Skipping {a_path} because it is not a git repository.")
+            return result_payload
+
+        # It's a git repo
+        result_payload["is_git"] = True
+        result_payload["repo_remotes_count"] = len(repo.remotes)
+
+        # Perform configured operations sequentially for this repo (the repo-level work is done concurrently between repos)
+        try:
+            if pull:
+                r = git_action(path=a_path, action=GitAction.pull, mess=None, r=recursive, auto_uv_sync=auto_uv_sync)
+                result_payload["results"].append(r)
+            if commit:
+                r = git_action(path=a_path, action=GitAction.commit, mess=None, r=recursive, auto_uv_sync=auto_uv_sync)
+                result_payload["results"].append(r)
+            if push:
+                r = git_action(path=a_path, action=GitAction.push, mess=None, r=recursive, auto_uv_sync=auto_uv_sync)
+                result_payload["results"].append(r)
+        except Exception as e:
+            # Capture any unexpected exception for this path
+            pprint(f"❌ Error processing {a_path}: {e}")
+
+        return result_payload
+
+    # Choose a reasonable number of workers
+    max_workers = min(32, (os.cpu_count() or 1) * 5, len(paths) or 1)
+
+    # Run the workers in parallel and aggregate results
+    with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as exc:
+        future_to_path = {exc.submit(_process_path, p): p for p in paths}
+        for fut in concurrent.futures.as_completed(future_to_path):
+            payload = fut.result()
+            a_path = cast(PathExtended, payload.get("path"))
+            summary.total_paths_processed += 1
+
+            if not payload.get("is_git"):
+                summary.non_git_paths += 1
+                continue
+
+            # git repo found
+            summary.git_repos_found += 1
+            if payload.get("repo_remotes_count", 0) == 0:
+                summary.repos_without_remotes.append(a_path)
+
+            for r in payload.get("results", []):
+                action_name = r.action if hasattr(r, "action") else ""
+                # Pull
+                if action_name == "pull":
+                    summary.pulls_attempted += 1
+                    if r.success:
+                        summary.pulls_successful += 1
+                    else:
+                        summary.pulls_failed += 1
+                        summary.failed_operations.append(r)
+                # Commit
+                elif action_name == "commit":
+                    summary.commits_attempted += 1
+                    if r.success:
+                        if getattr(r, "had_changes", False):
+                            summary.commits_successful += 1
+                        else:
+                            summary.commits_no_changes += 1
+                    else:
+                        summary.commits_failed += 1
+                        summary.failed_operations.append(r)
+                # Push
+                elif action_name == "push":
+                    summary.pushes_attempted += 1
+                    if r.success:
+                        summary.pushes_successful += 1
+                    else:
+                        summary.pushes_failed += 1
+                        summary.failed_operations.append(r)
+
+    # Print the detailed summary
+    print_git_operations_summary(summary, operations_performed)

machineconfig/scripts/python/helpers_repos/action_helper.py

@@ -0,0 +1,150 @@
+from enum import Enum
+from machineconfig.utils.path_extended import PathExtended
+
+
+from dataclasses import dataclass
+
+from rich.columns import Columns
+from rich.panel import Panel
+from rich.table import Table
+
+
+@dataclass
+class GitOperationResult:
+    """Result of a git operation on a single repository."""
+    repo_path: PathExtended
+    action: str
+    success: bool
+    message: str
+    is_git_repo: bool = True
+    had_changes: bool = False
+    remote_count: int = 0
+
+
+class GitAction(Enum):
+    commit = "commit"
+    push = "push"
+    pull = "pull"
+
+
+@dataclass
+class GitOperationSummary:
+    """Summary of all git operations performed."""
+
+    # Basic statistics
+    total_paths_processed: int = 0
+    git_repos_found: int = 0
+    non_git_paths: int = 0
+
+    # Per-operation statistics
+    commits_attempted: int = 0
+    commits_successful: int = 0
+    commits_no_changes: int = 0
+    commits_failed: int = 0
+
+    pulls_attempted: int = 0
+    pulls_successful: int = 0
+    pulls_failed: int = 0
+
+    pushes_attempted: int = 0
+    pushes_successful: int = 0
+    pushes_failed: int = 0
+
+    def __post_init__(self):
+        self.failed_operations: list[GitOperationResult] = []
+        self.repos_without_remotes: list[PathExtended] = []
+
+
+def print_git_operations_summary(summary: GitOperationSummary, operations_performed: list[str]) -> None:
+    """Print a detailed summary of git operations with rich formatting and tables."""
+    from rich.console import Console
+
+    console = Console()
+
+    # Main summary panel
+    summary_stats = [
+        f"Total paths processed: {summary.total_paths_processed}",
+        f"Git repositories found: {summary.git_repos_found}",
+        f"Non-git paths skipped: {summary.non_git_paths}",
+    ]
+
+    console.print(Panel.fit("\n".join(summary_stats), title="[bold blue]📊 Git Operations Summary[/bold blue]", border_style="blue"))
+
+    # Statistics panels in columns
+    stat_panels = []
+
+    if "commit" in operations_performed:
+        commit_stats = [
+            f"Attempted: {summary.commits_attempted}",
+            f"Successful: {summary.commits_successful}",
+            f"No changes: {summary.commits_no_changes}",
+            f"Failed: {summary.commits_failed}",
+        ]
+        stat_panels.append(Panel.fit("\n".join(commit_stats), title="[bold green]💾 Commit Operations[/bold green]", border_style="green"))
+
+    if "pull" in operations_performed:
+        pull_stats = [f"Attempted: {summary.pulls_attempted}", f"Successful: {summary.pulls_successful}", f"Failed: {summary.pulls_failed}"]
+        stat_panels.append(Panel.fit("\n".join(pull_stats), title="[bold cyan]⬇️ Pull Operations[/bold cyan]", border_style="cyan"))
+
+    if "push" in operations_performed:
+        push_stats = [f"Attempted: {summary.pushes_attempted}", f"Successful: {summary.pushes_successful}", f"Failed: {summary.pushes_failed}"]
+        stat_panels.append(Panel.fit("\n".join(push_stats), title="[bold magenta]🚀 Push Operations[/bold magenta]", border_style="magenta"))
+
+    if stat_panels:
+        console.print(Columns(stat_panels, equal=True, expand=True))
+
+    # Repositories without remotes warning
+    if summary.repos_without_remotes:
+        repos_table = Table(title="[bold yellow]⚠️ Repositories Without Remotes[/bold yellow]")
+        repos_table.add_column("Repository Name", style="cyan", no_wrap=True)
+        repos_table.add_column("Full Path", style="dim")
+
+        for repo_path in summary.repos_without_remotes:
+            repos_table.add_row(repo_path.name, str(repo_path))
+
+        console.print(repos_table)
+        console.print("[yellow]These repositories cannot be pushed to remote servers.[/yellow]")
+    elif "push" in operations_performed:
+        console.print("[green]✅ All repositories have remote configurations.[/green]")
+
+    # Failed operations table
+    if summary.failed_operations:
+        failed_table = Table(title=f"[bold red]❌ Failed Operations ({len(summary.failed_operations)} total)[/bold red]")
+        failed_table.add_column("Action", style="bold red", no_wrap=True)
+        failed_table.add_column("Repository", style="cyan", no_wrap=True)
+        failed_table.add_column("Problem", style="red")
+
+        # Group failed operations by type for better organization
+        failed_by_action = {}
+        for failed_op in summary.failed_operations:
+            if failed_op.action not in failed_by_action:
+                failed_by_action[failed_op.action] = []
+            failed_by_action[failed_op.action].append(failed_op)
+
+        for action, failures in failed_by_action.items():
+            for failure in failures:
+                repo_name = failure.repo_path.name if failure.is_git_repo else f"{failure.repo_path.name} (not git repo)"
+                problem = failure.message if failure.is_git_repo else "Not a git repository"
+                failed_table.add_row(action.upper(), repo_name, problem)
+
+        console.print(failed_table)
+    else:
+        console.print("[green]✅ All git operations completed successfully![/green]")
+
+    # Overall success assessment
+    total_failed = len(summary.failed_operations)
+    total_operations = summary.commits_attempted + summary.pulls_attempted + summary.pushes_attempted
+
+    if total_failed == 0 and total_operations > 0:
+        console.print(f"\n[bold green]🎉 SUCCESS: All {total_operations} operations completed successfully![/bold green]")
+    elif total_operations == 0:
+        console.print("\n[blue]📝 No git operations were performed.[/blue]")
+    else:
+        success_rate = ((total_operations - total_failed) / total_operations * 100) if total_operations > 0 else 0
+        if total_failed > 0:
+            console.print(
+                f"\n[bold yellow]⚖️ SUMMARY: {total_operations - total_failed}/{total_operations} operations succeeded ({success_rate:.1f}% success rate)[/bold yellow]"
+            )
+            console.print("[yellow]Review the failed operations table above for details on what needs attention.[/yellow]")
+        else:
+            console.print(f"\n[bold green]⚖️ SUMMARY: {total_operations}/{total_operations} operations succeeded (100% success rate)[/bold green]")

machineconfig/scripts/python/{repos_helper_clone.py → helpers_repos/clone.py}

@@ -1,5 +1,5 @@
-from __future__ import annotations
 
+from pathlib import Path
 from typing import Literal, Optional, cast
 
 from git import Repo as GitRepo
@@ -7,7 +7,6 @@ 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
 
@@ -26,8 +25,8 @@ def choose_remote(remotes: list[RepoRemote], preferred_remote: Optional[str]) ->
     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()
+def ensure_destination(parent_dir: str, name: str) -> Path:
+    parent_path = Path(parent_dir).expanduser().absolute()
     parent_path.mkdir(parents=True, exist_ok=True)
     return parent_path.joinpath(name)
 
@@ -94,9 +93,9 @@ def clone_single_repo(repo_spec: RepoRecordDict, preferred_remote: Optional[str]
     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"]
+def clone_repos(spec_path: Path, preferred_remote: Optional[str], checkout_branch_flag: bool, checkout_commit_flag: bool) -> list[tuple[CloneStatus, str]]:
+    spec_file = cast(RepoRecordFile, read_json(path=spec_path))
+    repos = spec_file["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))