gitpane 1.0.0__py3-none-any.whl

gitpane/tool/terminal_recipe.py

@@ -0,0 +1,390 @@
+"""Detect the terminals this machine offers, from known recipes."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import sys
+import urllib.parse
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, Signal
+
+from gitpane.config import LINUX_PLATFORM, MACOS_PLATFORM, SYSTEM_ROOT_ENVIRONMENT_NAME, WINDOWS_PLATFORM
+from gitpane.tool.app_bundle import bundled_program, find_application, read_bundle
+from gitpane.tool.git_executable import GIT_BINARY_DIR_BASENAME, GIT_SHELL_DIR_BASENAME, git_root_dirs
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+    from gitpane.preference.preference_store import PreferenceStore
+    from gitpane.tool.app_bundle import AppBundle
+
+
+class TerminalLaunch(Enum):
+    """How a terminal recipe is started once its program or application has been found."""
+
+    # The recipe's own executable, found on the PATH or in known folders, started detached.
+    PROGRAM = "program"
+    # A program inside the macOS application found (a known tool, or the declared program), started detached.
+    BUNDLE_PROGRAM = "bundle-program"
+    # macOS's open command with the recipe arguments: it hands the request to LaunchServices and answers at once.
+    OPEN = "open"
+
+
+@dataclass(frozen=True)
+class TerminalRecipe:
+    """Describe only documented arguments, preserving registry order for initial choice.
+
+    On macOS ``executable`` is the application folder name searched in the application folders, and ``bundle_program``
+    the path of the program to start inside it (empty: the program the application declares). Arguments may hold the
+    markers ``{directory}``, ``{directory_url}`` (the folder encoded for a URL) and ``{bundle}`` (the application folder).
+    """
+
+    id: str
+    label: str
+    platform: str
+    executable: str
+    arguments: tuple[str, ...]
+    new_console: bool = False
+    launch: TerminalLaunch = TerminalLaunch.PROGRAM
+    bundle_program: tuple[str, ...] = ()
+
+
+TERMINAL_RECIPES = (
+    # Terminal.app ships with macOS, so it always comes first and is the default choice whatever else is installed.
+    # open -a gives it the folder, in which it opens a new window; no AppleScript, so no permission prompt.
+    TerminalRecipe("terminal-macos", "Terminal", MACOS_PLATFORM, "Terminal.app", ("-a", "{bundle}", "{directory}"), launch=TerminalLaunch.OPEN),
+    # Third-party macOS terminals, offered only when installed, in this fixed order. Their ids are saved in the
+    # preferences and must never be renamed.
+    # iTerm2 opens a window in the folder it is given through open -a, like Terminal.
+    TerminalRecipe("iterm2", "iTerm2", MACOS_PLATFORM, "iTerm.app", ("-a", "{bundle}", "{directory}"), launch=TerminalLaunch.OPEN),
+    # Ghostty documents --working-directory. Started by open it defaults to the home folder, and an already running
+    # Ghostty would apply its own inherited folder, so -n starts a new instance that reads the option.
+    TerminalRecipe("ghostty", "Ghostty", MACOS_PLATFORM, "Ghostty.app", ("-na", "{bundle}", "--args", "--working-directory={directory}"), launch=TerminalLaunch.OPEN),
+    # kitty's documentation runs the program inside its application for command line options, which open would not
+    # pass; --directory changes to the folder at launch.
+    TerminalRecipe("kitty", "kitty", MACOS_PLATFORM, "kitty.app", ("--directory", "{directory}"), launch=TerminalLaunch.BUNDLE_PROGRAM,
+                   bundle_program=("Contents", "MacOS", "kitty")),
+    # Alacritty's declared program accepts --working-directory, documented as the folder the shell starts in.
+    TerminalRecipe("alacritty", "Alacritty", MACOS_PLATFORM, "Alacritty.app", ("--working-directory", "{directory}"), launch=TerminalLaunch.BUNDLE_PROGRAM),
+    # The declared program of WezTerm is its interface; its command line tool, wezterm, documents start --cwd.
+    TerminalRecipe("wezterm", "WezTerm", MACOS_PLATFORM, "WezTerm.app", ("start", "--cwd", "{directory}"), launch=TerminalLaunch.BUNDLE_PROGRAM,
+                   bundle_program=("Contents", "MacOS", "wezterm")),
+    # Warp documents a link that opens a window in a folder; the folder is encoded so that &, # or ? in its name
+    # never become parameters of the link.
+    TerminalRecipe("warp", "Warp", MACOS_PLATFORM, "Warp.app", ("warp://action/new_window?path={directory_url}",), launch=TerminalLaunch.OPEN),
+    TerminalRecipe("wt", "Windows Terminal", WINDOWS_PLATFORM, "wt.exe", ("new-tab", "-d", "{directory}")),
+    TerminalRecipe("pwsh", "PowerShell", WINDOWS_PLATFORM, "pwsh.exe", ("-NoExit",), True),
+    TerminalRecipe("powershell", "Windows PowerShell", WINDOWS_PLATFORM, "powershell.exe", ("-NoExit",), True),
+    TerminalRecipe("cmd", "Command Prompt", WINDOWS_PLATFORM, "cmd.exe", ("/D", "/K"), True),
+    TerminalRecipe("ptyxis", "Ptyxis", LINUX_PLATFORM, "ptyxis", ("--new-window", "--working-directory", "{directory}")),
+    TerminalRecipe("gnome-terminal", "GNOME Terminal", LINUX_PLATFORM, "gnome-terminal", ("--working-directory", "{directory}")),
+    TerminalRecipe("konsole", "Konsole", LINUX_PLATFORM, "konsole", ("--workdir", "{directory}")),
+    TerminalRecipe("xfce4-terminal", "Xfce Terminal", LINUX_PLATFORM, "xfce4-terminal", ("--working-directory={directory}",)),
+    TerminalRecipe("xterm", "XTerm", LINUX_PLATFORM, "xterm", ()),
+)
+# Stable id saved in the preferences for the Git Bash entry, whichever of its three executables was found.
+GIT_BASH_TERMINAL_ID = "git-bash"
+GIT_BASH_LABEL = "Git Bash"
+# Git for Windows ships a windowed launcher; bash and sh are the console programs Git Extensions falls back to.
+GIT_BASH_EXECUTABLE_BASENAME = "git-bash.exe"
+BASH_EXECUTABLE_BASENAME = "bash.exe"
+SH_EXECUTABLE_BASENAME = "sh.exe"
+# Folder name of a Git for Windows installation under Program Files.
+GIT_INSTALLATION_DIR_BASENAME = "Git"
+NATIVE_PROGRAM_FILES_ENVIRONMENT_NAME = "ProgramW6432"
+X86_PROGRAM_FILES_ENVIRONMENT_NAME = "ProgramFiles(x86)"
+# The launcher is a windowed program and opens its own window; bash.exe and sh.exe need a new console. Started bare,
+# usr\bin\bash.exe skips the Git for Windows profile and has neither ls nor git on its PATH; a login interactive
+# shell reads that profile, as git-bash.exe does, and keeps the folder it was started in.
+GIT_BASH_SHELL_ARGUMENTS = ("--login", "-i")
+GIT_BASH_RECIPES = (
+    TerminalRecipe(GIT_BASH_TERMINAL_ID, GIT_BASH_LABEL, WINDOWS_PLATFORM, GIT_BASH_EXECUTABLE_BASENAME, ()),
+    TerminalRecipe("git-bash-bash", GIT_BASH_LABEL, WINDOWS_PLATFORM, BASH_EXECUTABLE_BASENAME, GIT_BASH_SHELL_ARGUMENTS, True),
+    TerminalRecipe("git-bash-sh", GIT_BASH_LABEL, WINDOWS_PLATFORM, SH_EXECUTABLE_BASENAME, GIT_BASH_SHELL_ARGUMENTS, True),
+)
+RECIPE_BY_ID: dict[str, TerminalRecipe] = {}
+# Git Bash recipes are launchable by id but stay out of TERMINAL_RECIPES: they have their own search,
+# and the generic loop only knows the installation folders of the other Windows terminals.
+for recipe in (*TERMINAL_RECIPES, *GIT_BASH_RECIPES):
+    RECIPE_BY_ID[recipe.id] = recipe
+
+
+@dataclass(frozen=True)
+class TerminalDescriptor:
+    """Keep detected and formerly selected terminals identifiable without substituting tools."""
+
+    id: str
+    label: str
+    program_filename: str
+    recipe_id: str
+    available: bool = True
+
+
+class TerminalRegistry(QObject):
+    """Publish one persisted terminal choice to every repository window."""
+
+    changed = Signal()
+
+    def __init__(self, preference: PreferenceStore, detector: Callable[[], list[TerminalDescriptor]] | None = None, parent: QObject | None = None) -> None:
+        """Inject detection and retain useful names when a selected executable disappears."""
+        super().__init__(parent)
+        self.preference = preference
+        self.detector = detector if detector is not None else detect_terminal
+        self.detected_terminals: list[TerminalDescriptor] = []
+        self.terminals: list[TerminalDescriptor] = []
+        self.selected_id = ""
+        self.warning = ""
+        preference.changed.connect(self._preference_changed)
+        self.redetect()
+
+    def redetect(self) -> None:
+        """Reinventory known recipes without silently replacing a saved missing terminal."""
+        self.detected_terminals = self.detector()
+        self.preference.refresh()
+        self.warning = ""
+        if not self.preference.value_by_key["terminal_id"] and self.detected_terminals:
+            first_terminal_index = 0
+            try:
+                self.select(self.detected_terminals[first_terminal_index].id)
+            except OSError as error:
+                self.warning = str(error)
+        self._rebuild()
+
+    def select(self, terminal_id: str) -> None:
+        """Persist the complete selection atomically before announcing it to other windows."""
+        for terminal in self.detected_terminals:
+            if terminal.id == terminal_id and terminal.available:
+                self.preference.update({"terminal_id": terminal.id, "terminal_label": terminal.label, "terminal_filename": terminal.program_filename})
+                self.warning = ""
+                self._rebuild()
+                return
+        raise OSError("This terminal is unavailable. Detect terminals again.")
+
+    def selected(self) -> TerminalDescriptor | None:
+        """Return exactly the shared choice, including its unavailable representation."""
+        for terminal in self.terminals:
+            if terminal.id == self.selected_id:
+                return terminal
+        return None
+
+    def _preference_changed(self, changed_value_by_key: dict[str, object]) -> None:
+        if any(key.startswith("terminal_") for key in changed_value_by_key):
+            self._rebuild()
+
+    def _rebuild(self) -> None:
+        """Combine the inventory with saved identity without constructing executable commands."""
+        self.terminals = list(self.detected_terminals)
+        self.selected_id = str(self.preference.value_by_key["terminal_id"])
+        if self.selected_id and not any(terminal.id == self.selected_id for terminal in self.terminals):
+            recipe = RECIPE_BY_ID.get(self.selected_id)
+            label = str(self.preference.value_by_key["terminal_label"]) or (recipe.label if recipe else self.selected_id)
+            program_filename = str(self.preference.value_by_key["terminal_filename"])
+            self.terminals.append(TerminalDescriptor(self.selected_id, label, program_filename, self.selected_id, False))
+        self.changed.emit()
+
+
+def executable_available(program_filename: str) -> bool:
+    """Check a concrete executable without evaluating a shell command.
+
+    A relative name is accepted and read from the current folder; the SSH and credential searches use
+    ``absolute_executable_available`` of ``gitpane.account.ssh`` instead, which refuses one.
+    """
+    return bool(program_filename) and os.path.isfile(program_filename) and os.access(program_filename, os.X_OK)
+
+
+def _windows_candidate_filenames(recipe: TerminalRecipe, environment_by_name: Mapping[str, str]) -> list[str]:
+    """Use known installation directories only when the corresponding environment exists."""
+    location_by_id = {
+        "wt": ("LOCALAPPDATA", "Microsoft", "WindowsApps"),
+        "pwsh": ("ProgramFiles", "PowerShell", "7"),
+        "powershell": (SYSTEM_ROOT_ENVIRONMENT_NAME, "System32", "WindowsPowerShell", "v1.0"),
+        "cmd": (SYSTEM_ROOT_ENVIRONMENT_NAME, "System32"),
+    }
+    environment_name, *directory_parts = location_by_id[recipe.id]
+    root_dir = environment_by_name.get(environment_name, "")
+    if not root_dir:
+        return []
+    return [os.path.join(root_dir, *directory_parts, recipe.executable)]
+
+
+def git_bash_candidate_filenames(executable: str, git_filename: str, git_utility_dir: str, which: Callable[[str], str | None],
+                                  environment_by_name: Mapping[str, str]) -> list[str]:
+    """List where one Git Bash executable may be, in search order, starting beside the Git GitPane runs.
+
+    After the Git in use comes the order of Git Extensions: both Program Files, the Git utilities folder, the Linux
+    tool folders of the installation, then the PATH. The bin folder of the installation, whose bash.exe sets up the
+    Git for Windows environment itself, is looked at before the Linux tool folders. An environment variable that is
+    absent or empty adds nothing.
+    """
+    root_dirs = git_root_dirs(git_filename)
+    installation_dirs = []
+    for environment_name in (NATIVE_PROGRAM_FILES_ENVIRONMENT_NAME, X86_PROGRAM_FILES_ENVIRONMENT_NAME):
+        program_files_dir = environment_by_name.get(environment_name, "")
+        if program_files_dir:
+            installation_dirs.append(os.path.join(program_files_dir, GIT_INSTALLATION_DIR_BASENAME))
+    candidate_filenames = []
+    for root_dir in root_dirs:
+        candidate_filenames.append(os.path.join(root_dir, executable))
+    for installation_dir in installation_dirs:
+        candidate_filenames.append(os.path.join(installation_dir, executable))
+    if git_utility_dir:
+        candidate_filenames.append(os.path.join(git_utility_dir, executable))
+    native_program_files_dir = environment_by_name.get(NATIVE_PROGRAM_FILES_ENVIRONMENT_NAME, "")
+    for tool_dir_parts in ((GIT_BINARY_DIR_BASENAME,), (GIT_SHELL_DIR_BASENAME, GIT_BINARY_DIR_BASENAME)):
+        for root_dir in root_dirs:
+            candidate_filenames.append(os.path.join(root_dir, *tool_dir_parts, executable))
+        if native_program_files_dir:
+            candidate_filenames.append(os.path.join(native_program_files_dir, GIT_INSTALLATION_DIR_BASENAME, *tool_dir_parts, executable))
+    path_filename = which(executable)
+    if path_filename:
+        candidate_filenames.append(path_filename)
+    return candidate_filenames
+
+
+def inside_system_root(filename: str, environment_by_name: Mapping[str, str]) -> bool:
+    """Tell whether a file lies under the Windows folder, where only system programs live."""
+    system_root_dir = environment_by_name.get(SYSTEM_ROOT_ENVIRONMENT_NAME, "")
+    if not system_root_dir:
+        return False
+    normalized_filename = os.path.normcase(os.path.abspath(filename))
+    normalized_system_root_dir = os.path.normcase(os.path.abspath(system_root_dir))
+    try:
+        return os.path.commonpath((normalized_filename, normalized_system_root_dir)) == normalized_system_root_dir
+    except ValueError:
+        return False
+
+
+def _detect_git_bash(git_filename: str, git_utility_dir: str, which: Callable[[str], str | None], available: Callable[[str], bool],
+                     environment_by_name: Mapping[str, str]) -> TerminalDescriptor | None:
+    """Find Git Bash the way Git Extensions does: git-bash.exe first, then bash.exe, then sh.exe.
+
+    All three forms share one saved id so the user's choice survives a fallback; only the launch recipe differs.
+    """
+    for recipe in GIT_BASH_RECIPES:
+        for candidate_filename in git_bash_candidate_filenames(recipe.executable, git_filename, git_utility_dir, which, environment_by_name):
+            # The WSL launcher in System32 is also named bash.exe; taking it would open another machine, not Git Bash.
+            if inside_system_root(candidate_filename, environment_by_name):
+                continue
+            if available(candidate_filename):
+                return TerminalDescriptor(GIT_BASH_TERMINAL_ID, GIT_BASH_LABEL, os.path.abspath(candidate_filename), recipe.id)
+    return None
+
+
+def bundle_recipe_program(recipe: TerminalRecipe, bundle_dir: str) -> str:
+    """Return the program a bundle recipe starts inside ``bundle_dir``, or ``""`` when the application does not hold it.
+
+    It is the known tool the recipe names, or else the program the application declares in its Info.plist; either way
+    only an executable file inside the application folder comes out.
+    """
+    if recipe.bundle_program:
+        return bundled_program(bundle_dir, recipe.bundle_program)
+    bundle = read_bundle(bundle_dir)
+    if bundle is None:
+        return ""
+    return bundle.executable_filename
+
+
+def _detect_macos_terminals(find_bundle: Callable[[tuple[str, ...]], AppBundle | None]) -> list[TerminalDescriptor]:
+    """List the installed macOS terminals in the order of the recipe table, each named by its application folder.
+
+    An application is offered once, from the first application folder that holds it; a recipe that starts a program
+    inside the application is only offered when that program is there.
+    """
+    terminals = []
+    bundle_identity_set: set[str] = set()
+    for recipe in TERMINAL_RECIPES:
+        if recipe.platform != MACOS_PLATFORM:
+            continue
+        bundle = find_bundle((recipe.executable,))
+        if bundle is None:
+            continue
+        if recipe.launch == TerminalLaunch.BUNDLE_PROGRAM and not bundle_recipe_program(recipe, bundle.bundle_dir):
+            continue
+        bundle_identity = os.path.normcase(bundle.bundle_dir)
+        if bundle_identity in bundle_identity_set:
+            continue
+        bundle_identity_set.add(bundle_identity)
+        terminals.append(TerminalDescriptor(recipe.id, recipe.label, bundle.bundle_dir, recipe.id))
+    return terminals
+
+
+def detect_terminal(platform: str = sys.platform, which: Callable[[str], str | None] = shutil.which,
+                    realpath: Callable[[str], str] = os.path.realpath, available: Callable[[str], bool] = executable_available,
+                    environment_by_name: Mapping[str, str] | None = None, git_filename: str = "", git_utility_dir: str = "",
+                    find_bundle: Callable[[tuple[str, ...]], AppBundle | None] = find_application) -> list[TerminalDescriptor]:
+    """Inventory recognized executables with a stable order and a recognized Linux alternative first.
+
+    On Windows, Git Bash comes first, searched from the Git GitPane runs (git_filename) and the Git utilities
+    directory before the usual installation folders and the PATH. On macOS terminals are applications, looked up by
+    their folder name in the application folders (find_bundle), with Terminal first.
+    """
+    if platform == MACOS_PLATFORM:
+        return _detect_macos_terminals(find_bundle)
+    environment_by_name = os.environ if environment_by_name is None else environment_by_name
+    terminals = []
+    program_identity_set: set[str] = set()
+    recipe_id_set: set[str] = set()
+    if platform == WINDOWS_PLATFORM:
+        git_bash = _detect_git_bash(git_filename, git_utility_dir, which, available, environment_by_name)
+        if git_bash is not None:
+            terminals.append(git_bash)
+            program_identity_set.add(os.path.normcase(git_bash.program_filename))
+    if platform == LINUX_PLATFORM:
+        alternative_filename = which("x-terminal-emulator")
+        if alternative_filename:
+            target_filename = realpath(alternative_filename)
+            for recipe in TERMINAL_RECIPES:
+                if recipe.platform == platform and os.path.basename(target_filename) == recipe.executable and available(target_filename):
+                    terminals.append(TerminalDescriptor(recipe.id, recipe.label, target_filename, recipe.id))
+                    program_identity_set.add(os.path.normcase(target_filename))
+                    recipe_id_set.add(recipe.id)
+                    break
+    for recipe in TERMINAL_RECIPES:
+        if recipe.platform != platform or recipe.id in recipe_id_set:
+            continue
+        program_filename = which(recipe.executable)
+        candidate_filenames = [program_filename] if program_filename else []
+        if platform == WINDOWS_PLATFORM:
+            candidate_filenames.extend(_windows_candidate_filenames(recipe, environment_by_name))
+        for candidate_filename in candidate_filenames:
+            if not available(candidate_filename):
+                continue
+            canonical_filename = os.path.abspath(candidate_filename) if platform == WINDOWS_PLATFORM else realpath(candidate_filename)
+            program_identity = os.path.normcase(canonical_filename)
+            if program_identity not in program_identity_set:
+                terminals.append(TerminalDescriptor(recipe.id, recipe.label, canonical_filename, recipe.id))
+                program_identity_set.add(program_identity)
+            break
+    return terminals
+
+
+# Markers a recipe argument may hold, each replaced by one value in a single pass, so a folder name that happens to
+# contain a marker's text is never expanded a second time.
+TERMINAL_ARGUMENT_MARKER_PATTERN = re.compile(r"\{(directory|directory_url|bundle)\}")
+# Characters a folder path keeps unencoded inside a URL: only the separator, so &, #, ? and spaces never become syntax.
+URL_PATH_SAFE_CHARACTERS = "/"
+
+
+def terminal_arguments(descriptor: TerminalDescriptor, repository_dir: str) -> list[str]:
+    """Expand the directory as a single argument, never as executable shell text.
+
+    The application folder (a macOS terminal's descriptor names it) and the folder encoded for a URL are expanded the
+    same way, one element per argument.
+    """
+    recipe = RECIPE_BY_ID.get(descriptor.recipe_id)
+    if recipe is None:
+        raise ValueError(f"Unknown terminal recipe: {descriptor.recipe_id}")
+    value_by_marker = {
+        "directory": repository_dir,
+        "directory_url": urllib.parse.quote(repository_dir, safe=URL_PATH_SAFE_CHARACTERS),
+        "bundle": descriptor.program_filename,
+    }
+    arguments = []
+    for argument in recipe.arguments:
+        arguments.append(TERMINAL_ARGUMENT_MARKER_PATTERN.sub(lambda match: value_by_marker[match.group(1)], argument))
+    return arguments