gitpane 1.0.0__py3-none-any.whl

gitpane/tool/editor_recipe.py

@@ -0,0 +1,481 @@
+"""Keep the external text editor recipe, literal file arguments included, separate from Git preferences."""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QProcess
+
+from gitpane.config import LINUX_PLATFORM, MACOS_OPEN_FILENAME, MACOS_PLATFORM, WINDOWS_PLATFORM
+from gitpane.system.path_identity import canonical_path
+from gitpane.system.xdg_session import xdg_data_home
+from gitpane.tool.app_bundle import (
+    APPLICATION_SEARCH_DIRS,
+    BUNDLE_SUFFIX,
+    CONTENTS_DIR_BASENAME,
+    MACOS_DIR_BASENAME,
+    TEXTEDIT_BUNDLE_IDENTIFIER,
+    chosen_application_program,
+    enclosing_bundle_dir,
+    is_textedit,
+    read_bundle,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+EDITOR_PRESET_PREFERENCE_KEY = "editor_preset"
+EDITOR_FILENAME_PREFERENCE_KEY = "editor_filename"
+EDITOR_ARGUMENT_PREFERENCE_KEY = "editor_arguments"
+EDITOR_DEFAULT_BY_KEY = {EDITOR_PRESET_PREFERENCE_KEY: "custom", EDITOR_FILENAME_PREFERENCE_KEY: "", EDITOR_ARGUMENT_PREFERENCE_KEY: ""}
+EDITOR_INITIAL_PATH = os.environ.get("PATH", "")
+EDITOR_INITIAL_DIR = os.path.realpath(os.getcwd())
+EDITOR_WINDOWS_LAUNCHER_EXTENSION_SET = {".cmd", ".bat"}
+# The argument an editor command names the file with; a command without it gets the file at its end.
+EDITOR_FILE_PARAMETER = "{file}"
+FLATPAK_PROGRAM_NAME = "flatpak"
+# Flatpak's two default installations: the system's, and the user's under the user's data folder.
+FLATPAK_SYSTEM_INSTALLATION_DIR = "/var/lib/flatpak"
+FLATPAK_USER_INSTALLATION_BASENAME = "flatpak"
+FLATPAK_EXPORTS_DIR_BASENAME = "exports"
+# Where an installation exports a program for each application it deploys, named after the application's identifier.
+FLATPAK_EXPORTED_PROGRAM_PARTS = (FLATPAK_EXPORTS_DIR_BASENAME, "bin")
+# Where an installation exports the desktop file of each application it deploys.
+FLATPAK_EXPORTED_APPLICATION_PARTS = (FLATPAK_EXPORTS_DIR_BASENAME, "share", "applications")
+# The command and the marks Flatpak itself writes in the desktop file of an exported application, so that a file the
+# application's sandbox cannot see is handed to it through the document portal.
+FLATPAK_RUN_ARGUMENTS = "run --file-forwarding"
+FLATPAK_FILE_FORWARDING_MARK = "@@"
+# The platform of a preset offered on every system.
+ALL_PLATFORM = "all"
+# Systems where Settings lists only the editors found on the machine: on these systems an editor is a program or an
+# application GitPane can look for on disk, and a list of editors the user does not have would only be noise. Windows
+# keeps its whole list.
+INSTALLED_ONLY_PRESET_PLATFORM_SET = frozenset({MACOS_PLATFORM, LINUX_PLATFORM})
+UNAVAILABLE_EDITOR_TEXT = "The configured editor is unavailable. Open Settings to check its executable and arguments."
+TEXTEDIT_PRESET_ID = "textedit-macos"
+
+
+def editor_platform(platform: str) -> str:
+    """Name the presets ``platform`` uses, in the platform vocabulary of the configuration.
+
+    Windows and macOS have their own presets; Linux, whatever its version suffix, and any other Unix system use the
+    Linux presets, as they always did.
+    """
+    if platform in (WINDOWS_PLATFORM, MACOS_PLATFORM):
+        return platform
+    return LINUX_PLATFORM
+
+
+EDITOR_PLATFORM = editor_platform(sys.platform)
+
+
+@dataclass(frozen=True)
+class EditorPreset:
+    """Describe a selectable editor: the programs it can be found as and the arguments its command passes before the file."""
+
+    preset_id: str
+    label: str
+    platform: str
+    candidate_programs: tuple[str, ...]
+    arguments: str
+    # Places of the program relative to an applications folder, application folder name first; tried before the
+    # names searched in PATH.
+    bundle_programs: tuple[tuple[str, ...], ...] = ()
+    # Options of macOS's open command that show a file in this editor, for a preset whose own arguments open a new window
+    # or a separate copy of the editor and wait for it; empty when the preset's own command already fits a plain look at a
+    # file.
+    file_open_options: tuple[str, ...] = ()
+    # Names of the desktop files under which a freedesktop desktop knows this editor, whether it came as a distribution
+    # package, a snap or a Flatpak.
+    desktop_file_ids: tuple[str, ...] = ()
+    # Identifier of the editor's Flatpak application; empty when the editor has none on Flathub.
+    flatpak_app_id: str = ""
+    # Identifiers the editor's macOS application declares, under which LaunchServices names it as the default editor.
+    bundle_identifiers: tuple[str, ...] = ()
+
+    def carries_default_editor_id(self, default_editor_id: str) -> bool:
+        """Tell whether the identifier a system names its default text editor by stands for this preset.
+
+        A desktop file name is compared as written, as freedesktop desktops write it; an application identifier is
+        compared without case, since LaunchServices writes the ones it keeps in lower case.
+        """
+        if default_editor_id in self.desktop_file_ids:
+            return True
+        folded_id = default_editor_id.casefold()
+        for bundle_identifier in self.bundle_identifiers:
+            if bundle_identifier.casefold() == folded_id:
+                return True
+        return False
+
+
+def bundle_program_places(bundle_basenames: tuple[str, ...], program_parts: tuple[str, ...]) -> tuple[tuple[str, ...], ...]:
+    """Build the places of one program inside each of the application folder names it ships under, in that order."""
+    places = []
+    for bundle_basename in bundle_basenames:
+        places.append((bundle_basename, *program_parts))
+    return tuple(places)
+
+
+# TextEdit returns at once when started directly. The preset's command asks macOS's open command for a separate copy of
+# it (-n) for the file and waits until that copy quits (-W), without touching a TextEdit already open with other
+# documents. Named by its identifier, so a renamed application is still found.
+TEXTEDIT_ARGUMENTS = "-W -n -b " + TEXTEDIT_BUNDLE_IDENTIFIER
+# Show in text editor waits for nothing, so the file simply opens in the user's own TextEdit.
+TEXTEDIT_FILE_OPEN_OPTIONS = ("-b", TEXTEDIT_BUNDLE_IDENTIFIER)
+# The other macOS presets open a new window and wait (--new-window --wait, or --wait for Zed), which the rebase needs to
+# tell when its file was closed. Show in text editor hands the file to the editor through open instead, so it goes to
+# the window already open and nothing is left waiting. VS Code and Zed are named by their one identifier.
+VSCODE_BUNDLE_IDENTIFIER = "com.microsoft.VSCode"
+ZED_BUNDLE_IDENTIFIER = "dev.zed.Zed"
+# Sublime Text 4 and Sublime Text 3 ship under the same application name with their own identifier, and a recipe does
+# not record which one is installed: open names it by that name, which finds whichever version LaunchServices knows,
+# where one identifier would miss the other version.
+SUBLIME_TEXT_APPLICATION_NAME = "Sublime Text"
+
+
+EDITOR_PRESETS = (
+    EditorPreset("custom", "Custom", ALL_PLATFORM, (), ""),
+    EditorPreset("notepad", "Notepad", WINDOWS_PLATFORM, ("notepad.exe", os.path.join(os.environ.get("SystemRoot", r"C:\Windows"), "System32", "notepad.exe")), ""),
+    EditorPreset("notepad++", "Notepad++", WINDOWS_PLATFORM, ("notepad++.exe", os.path.join(os.environ.get("ProgramFiles", r"C:\Program Files"), "notepad++", "notepad++.exe")), "-multiInst -nosession"),
+    EditorPreset("sublime-windows", "Sublime Text", WINDOWS_PLATFORM, ("sublime_text.exe",), "--new-window --wait"),
+    # The Linux order is the one detection falls back on when the desktop names no known editor: the desktops' own
+    # editors first, gedit after the GNOME editor that replaced it, the developers' editors last. Their arguments are
+    # empty: the external editor only shows a file, the way the desktop's file manager opens it, so the file goes alone
+    # to the editor's window already open. The identifiers are written in the users' preferences and are never renamed.
+    EditorPreset("gnome-text-editor", "GNOME Text Editor", LINUX_PLATFORM, ("gnome-text-editor",), "",
+                 desktop_file_ids=("org.gnome.TextEditor.desktop",), flatpak_app_id="org.gnome.TextEditor"),
+    EditorPreset("kate", "Kate", LINUX_PLATFORM, ("kate",), "", desktop_file_ids=("org.kde.kate.desktop",), flatpak_app_id="org.kde.kate"),
+    EditorPreset("kwrite", "KWrite", LINUX_PLATFORM, ("kwrite",), "", desktop_file_ids=("org.kde.kwrite.desktop",), flatpak_app_id="org.kde.kwrite"),
+    EditorPreset("xed", "Xed", LINUX_PLATFORM, ("xed",), "", desktop_file_ids=("org.x.editor.desktop", "xed.desktop")),
+    EditorPreset("mousepad", "Mousepad", LINUX_PLATFORM, ("mousepad",), "", desktop_file_ids=("org.xfce.mousepad.desktop", "mousepad.desktop"), flatpak_app_id="org.xfce.mousepad"),
+    EditorPreset("pluma", "Pluma", LINUX_PLATFORM, ("pluma",), "", desktop_file_ids=("pluma.desktop",)),
+    EditorPreset("featherpad", "FeatherPad", LINUX_PLATFORM, ("featherpad",), "", desktop_file_ids=("featherpad.desktop",)),
+    EditorPreset("cosmic-edit", "COSMIC Text Editor", LINUX_PLATFORM, ("cosmic-edit",), "", desktop_file_ids=("com.system76.CosmicEdit.desktop",)),
+    EditorPreset("elementary-code", "Code (elementary)", LINUX_PLATFORM, ("io.elementary.code",), "",
+                 desktop_file_ids=("io.elementary.code.desktop",), flatpak_app_id="io.elementary.code"),
+    EditorPreset("gedit", "Gedit", LINUX_PLATFORM, ("gedit",), "", desktop_file_ids=("org.gnome.gedit.desktop", "gedit.desktop"), flatpak_app_id="org.gnome.gedit"),
+    EditorPreset("code", "VS Code", LINUX_PLATFORM, ("code",), "",
+                 desktop_file_ids=("code.desktop", "code_code.desktop", "com.visualstudio.code.desktop"), flatpak_app_id="com.visualstudio.code"),
+    EditorPreset("sublime-linux", "Sublime Text", LINUX_PLATFORM, ("subl",), "",
+                 desktop_file_ids=("sublime_text.desktop", "sublime-text_subl.desktop", "com.sublimetext.three.desktop"), flatpak_app_id="com.sublimetext.three"),
+    EditorPreset(TEXTEDIT_PRESET_ID, "TextEdit", MACOS_PLATFORM, (MACOS_OPEN_FILENAME,), TEXTEDIT_ARGUMENTS, file_open_options=TEXTEDIT_FILE_OPEN_OPTIONS,
+                 bundle_identifiers=(TEXTEDIT_BUNDLE_IDENTIFIER,)),
+    EditorPreset("code-macos", "VS Code", MACOS_PLATFORM, ("code",), "--new-window --wait", file_open_options=("-b", VSCODE_BUNDLE_IDENTIFIER),
+                 bundle_programs=bundle_program_places(("Visual Studio Code.app",), (CONTENTS_DIR_BASENAME, "Resources", "app", "bin", "code")), bundle_identifiers=(VSCODE_BUNDLE_IDENTIFIER,)),
+    EditorPreset("sublime-macos", "Sublime Text", MACOS_PLATFORM, ("subl",), "--new-window --wait", file_open_options=("-a", SUBLIME_TEXT_APPLICATION_NAME),
+                 bundle_programs=bundle_program_places((SUBLIME_TEXT_APPLICATION_NAME + BUNDLE_SUFFIX,), (CONTENTS_DIR_BASENAME, "SharedSupport", "bin", "subl")),
+                 bundle_identifiers=("com.sublimetext.4", "com.sublimetext.3")),
+    EditorPreset("zed-macos", "Zed", MACOS_PLATFORM, ("zed",), "--wait", file_open_options=("-b", ZED_BUNDLE_IDENTIFIER),
+                 bundle_programs=bundle_program_places(("Zed.app",), (CONTENTS_DIR_BASENAME, MACOS_DIR_BASENAME, "cli")), bundle_identifiers=(ZED_BUNDLE_IDENTIFIER,)),
+)
+
+
+def editor_preset(preset_id: str) -> EditorPreset | None:
+    """Return the preset saved under ``preset_id``, or None for a preset GitPane no longer offers or one written by hand."""
+    for preset in EDITOR_PRESETS:
+        if preset.preset_id == preset_id:
+            return preset
+    return None
+
+
+def file_open_options(recipe: EditorRecipe) -> tuple[str, ...]:
+    """Return the options of macOS's open command that show a file in the recipe's editor for a plain look at it, or nothing.
+
+    Only a preset recipe whose arguments are still the preset's own gets them: arguments the user changed are the user's
+    command and are started as written.
+    """
+    preset = editor_preset(recipe.preset_id)
+    if preset is None or recipe.argument_template != preset.arguments:
+        return ()
+    return preset.file_open_options
+
+
+def _is_repository_program(program_filename: str, repository_dirs: tuple[str, ...]) -> bool:
+    """Exclude executable search results inside known repositories or a discoverable Git checkout."""
+    canonical_filename = canonical_path(program_filename)
+    for repository_dir in repository_dirs:
+        canonical_dir = canonical_path(repository_dir)
+        try:
+            if os.path.commonpath((canonical_filename, canonical_dir)) == canonical_dir:
+                return True
+        except ValueError:
+            continue
+    for current_dir in (EDITOR_INITIAL_DIR, os.getcwd()):
+        if os.path.dirname(canonical_filename) == canonical_path(current_dir):
+            return True
+    current_dir = os.path.dirname(canonical_filename)
+    while current_dir:
+        if os.path.lexists(os.path.join(current_dir, ".git")):
+            return True
+        parent_dir = os.path.dirname(current_dir)
+        if parent_dir == current_dir:
+            break
+        current_dir = parent_dir
+    return False
+
+
+def resolve_editor_program(program: str, *, repository_dirs: tuple[str, ...] = (), platform: str = EDITOR_PLATFORM, search_path: str = EDITOR_INITIAL_PATH) -> str:
+    """Find an installed executable in the initial search path, without implicit current-directory lookup, and return it as found.
+
+    The path is the PATH folder joined to the name, or the absolute path given, never the target of a link: a snap
+    command such as /snap/bin/code is a link to the snap program, which picks the application by the name it is
+    started under, so started by its target it would only print snap's help. The repository check judges the link's
+    target, so a link cannot bring in a program that lives in a checkout.
+    """
+    if not program or "\0" in program:
+        return ""
+    candidate_filenames = []
+    if os.path.isabs(program):
+        candidate_filenames.append(program)
+    elif os.path.basename(program) == program:
+        for program_dir in search_path.split(os.pathsep):
+            if not program_dir or not os.path.isabs(program_dir):
+                continue
+            candidate_filenames.append(os.path.join(program_dir, program))
+            _program_root, extension = os.path.splitext(program)
+            if platform == WINDOWS_PLATFORM and not extension:
+                candidate_filenames.append(os.path.join(program_dir, program + ".exe"))
+    for candidate_filename in candidate_filenames:
+        if _is_repository_program(candidate_filename, repository_dirs):
+            continue
+        _program_root, extension = os.path.splitext(candidate_filename)
+        if platform == WINDOWS_PLATFORM and extension.casefold() in EDITOR_WINDOWS_LAUNCHER_EXTENSION_SET:
+            continue
+        if os.path.isfile(candidate_filename) and os.access(candidate_filename, os.X_OK):
+            return candidate_filename
+    return ""
+
+
+def flatpak_installation_dirs(environment_by_name: Mapping[str, str], home_dir: str) -> tuple[str, ...]:
+    """Name Flatpak's two default installations, the system's first, then the user's under the user's data folder."""
+    return (FLATPAK_SYSTEM_INSTALLATION_DIR, os.path.join(xdg_data_home(environment_by_name, home_dir), FLATPAK_USER_INSTALLATION_BASENAME))
+
+
+EDITOR_FLATPAK_DIRS = flatpak_installation_dirs(os.environ, os.path.expanduser("~"))
+
+
+def editor_flatpak_dirs(flatpak_dirs: tuple[str, ...] | None) -> tuple[str, ...]:
+    """Return the Flatpak installations to look in: ``flatpak_dirs`` when the caller gives them, otherwise the session's.
+
+    The session's installations are read from this module at the call rather than bound as a default value, so the
+    test configuration replaces them in one place.
+    """
+    if flatpak_dirs is not None:
+        return flatpak_dirs
+    return EDITOR_FLATPAK_DIRS
+
+
+def flatpak_argument_template(app_id: str) -> str:
+    """Build the arguments of ``flatpak`` that open the file in the Flatpak application ``app_id``."""
+    return " ".join((FLATPAK_RUN_ARGUMENTS, app_id, FLATPAK_FILE_FORWARDING_MARK, EDITOR_FILE_PARAMETER, FLATPAK_FILE_FORWARDING_MARK))
+
+
+def flatpak_recipe(preset: EditorPreset, *, platform: str, search_path: str, repository_dirs: tuple[str, ...], flatpak_dirs: tuple[str, ...]) -> EditorRecipe | None:
+    """Return the recipe that opens the file in the preset's Flatpak application, or None when that application cannot be used.
+
+    The application counts as installed when one of ``flatpak_dirs`` exports its program; a link to a removed
+    deployment counts as absent, since the file check follows it. It is started through ``flatpak run
+    --file-forwarding``, as Flatpak's own desktop file does, never through the exported program: that one has no file
+    forwarding, so a file the sandbox cannot see would not open. The ``flatpak`` program must be in PATH. The
+    application identifier only ever comes from the preset table. Only files are checked: no process is started.
+    """
+    if not preset.flatpak_app_id:
+        return None
+    for flatpak_dir in flatpak_dirs:
+        if not os.path.isfile(os.path.join(flatpak_dir, *FLATPAK_EXPORTED_PROGRAM_PARTS, preset.flatpak_app_id)):
+            continue
+        flatpak_filename = resolve_editor_program(FLATPAK_PROGRAM_NAME, platform=platform, search_path=search_path, repository_dirs=repository_dirs)
+        if not flatpak_filename:
+            return None
+        return EditorRecipe(preset.preset_id, flatpak_filename, flatpak_argument_template(preset.flatpak_app_id))
+    return None
+
+
+def recipe_for_preset(preset: EditorPreset, *, platform: str = EDITOR_PLATFORM, search_path: str = EDITOR_INITIAL_PATH, repository_dirs: tuple[str, ...] = (),
+                      application_dirs: tuple[str, ...] = APPLICATION_SEARCH_DIRS, flatpak_dirs: tuple[str, ...] | None = None) -> EditorRecipe:
+    """Prefill a preset using the actual installed program, leaving missing programs explicitly empty.
+
+    A program inside an application is looked for in each applications folder in turn, every known place in one folder
+    before the next folder, then the names searched in PATH, then the preset's Flatpak application in ``flatpak_dirs``:
+    a native editor wins over its Flatpak. The order comes from the table and the folders given, never from the order
+    the disk lists entries in, so an application installed twice gives the first folder's program. Only files are
+    checked: no process is started. Without ``flatpak_dirs``, the session's Flatpak installations are looked in.
+    """
+    flatpak_dirs = editor_flatpak_dirs(flatpak_dirs)
+    for application_dir in application_dirs:
+        for bundle_program in preset.bundle_programs:
+            filename = resolve_editor_program(os.path.join(application_dir, *bundle_program), platform=platform, search_path=search_path, repository_dirs=repository_dirs)
+            if filename:
+                return EditorRecipe(preset.preset_id, filename, preset.arguments)
+    for program in preset.candidate_programs:
+        filename = resolve_editor_program(program, platform=platform, search_path=search_path, repository_dirs=repository_dirs)
+        if filename:
+            return EditorRecipe(preset.preset_id, filename, preset.arguments)
+    flatpak_form = flatpak_recipe(preset, platform=platform, search_path=search_path, repository_dirs=repository_dirs, flatpak_dirs=flatpak_dirs)
+    if flatpak_form is not None:
+        return flatpak_form
+    return EditorRecipe(preset.preset_id, "", preset.arguments)
+
+
+def offered_editor_presets(platform: str, installed: Callable[[EditorPreset], bool]) -> list[EditorPreset]:
+    """List the presets Settings offers on ``platform``, in the table's order, Custom first.
+
+    On macOS and Linux only the presets ``installed`` reports present are offered; Windows offers its whole list, so
+    ``installed`` is not called there.
+    """
+    offered_presets = []
+    for preset in EDITOR_PRESETS:
+        if preset.platform == ALL_PLATFORM:
+            offered_presets.append(preset)
+            continue
+        if preset.platform != platform:
+            continue
+        if platform in INSTALLED_ONLY_PRESET_PLATFORM_SET and not installed(preset):
+            continue
+        offered_presets.append(preset)
+    return offered_presets
+
+
+def _default_editor_preset_recipe(default_editor_id: str, *, platform: str, search_path: str, repository_dirs: tuple[str, ...], application_dirs: tuple[str, ...],
+                                  flatpak_dirs: tuple[str, ...]) -> EditorRecipe | None:
+    """Answer the recipe of the preset of ``platform`` that carries the system's default editor identifier, when that preset is installed, or None.
+
+    Only Linux and macOS presets carry such identifiers, so Windows always answers None.
+    """
+    if not default_editor_id:
+        return None
+    for preset in EDITOR_PRESETS:
+        if preset.platform != platform or not preset.carries_default_editor_id(default_editor_id):
+            continue
+        recipe = recipe_for_preset(preset, platform=platform, search_path=search_path, repository_dirs=repository_dirs, application_dirs=application_dirs, flatpak_dirs=flatpak_dirs)
+        if recipe.program_filename:
+            return recipe
+    return None
+
+
+def detect_editor_recipe(*, platform: str = EDITOR_PLATFORM, search_path: str = EDITOR_INITIAL_PATH, repository_dirs: tuple[str, ...] = (),
+                         application_dirs: tuple[str, ...] = APPLICATION_SEARCH_DIRS, flatpak_dirs: tuple[str, ...] | None = None, system_editor_id: str = "") -> EditorRecipe:
+    """Use Notepad on Windows; on Linux and macOS, the preset the system opens plain text with; else, on Linux only, the first installed preset in the table's order.
+
+    ``system_editor_id`` is the identifier the system names its default text editor by, empty when it names nothing or
+    has not been read yet: on Linux the desktop file the desktop names for plain text, on macOS the identifier of the
+    application LaunchServices names for it. The preset that carries it is taken when it is installed. Otherwise, on
+    Linux the table's order decides, and an empty Custom choice is left only when no Linux preset is installed at all;
+    on macOS nothing is chosen, so Show in text editor opens macOS's default text editor until the user picks one in
+    Settings. The identifier only picks a preset of the table: an editor the table does not know is never taken from
+    it. A Linux preset counts as installed when its program is in PATH or its Flatpak application is in
+    ``flatpak_dirs``, the session's Flatpak installations when none are given. Windows ignores ``system_editor_id``.
+    """
+    flatpak_dirs = editor_flatpak_dirs(flatpak_dirs)
+    default_recipe = _default_editor_preset_recipe(system_editor_id, platform=platform, search_path=search_path, repository_dirs=repository_dirs, application_dirs=application_dirs,
+                                                   flatpak_dirs=flatpak_dirs)
+    if default_recipe is not None:
+        return default_recipe
+    if platform == MACOS_PLATFORM:
+        return EditorRecipe()
+    for preset in EDITOR_PRESETS:
+        if preset.platform != platform:
+            continue
+        recipe = recipe_for_preset(preset, platform=platform, search_path=search_path, repository_dirs=repository_dirs, application_dirs=application_dirs, flatpak_dirs=flatpak_dirs)
+        if platform == WINDOWS_PLATFORM or recipe.program_filename:
+            return recipe
+    return EditorRecipe()
+
+
+@dataclass(frozen=True)
+class EditorRecipe:
+    """Store an editor selection without interpreting its executable or arguments as shell code."""
+
+    preset_id: str = "custom"
+    program_filename: str = ""
+    argument_template: str = ""
+
+    def validate(self, *, platform: str = EDITOR_PLATFORM) -> None:
+        """Validate a draft; an empty program is a valid choice, for which Show in text editor applies the rule of the platform.
+
+        The messages are shown as they are where Settings or Show in text editor refuses the choice, so each one says what to do.
+        """
+        build_editor_arguments(self.argument_template, os.path.abspath("editor-file"))
+        if "\0" in self.program_filename or "\0" in self.preset_id:
+            raise ValueError("External editor settings cannot contain a null character.")
+        if not self.program_filename:
+            return
+        if not os.path.isabs(self.program_filename) or not os.path.isfile(self.program_filename) or not os.access(self.program_filename, os.X_OK):
+            raise ValueError(UNAVAILABLE_EDITOR_TEXT)
+        _program_root, extension = os.path.splitext(self.program_filename)
+        if platform == WINDOWS_PLATFORM and extension.casefold() in EDITOR_WINDOWS_LAUNCHER_EXTENSION_SET:
+            raise ValueError("This Windows editor launcher is not qualified. Choose an appropriate executable in Open Settings.")
+
+    def preference_value(self) -> dict[str, object]:
+        """Serialize the three editor fields together for an atomic preference update."""
+        return {EDITOR_PRESET_PREFERENCE_KEY: self.preset_id, EDITOR_FILENAME_PREFERENCE_KEY: self.program_filename, EDITOR_ARGUMENT_PREFERENCE_KEY: self.argument_template}
+
+
+def bundle_preset_program(bundle_dir: str, platform: str) -> tuple[str, str]:
+    """Return the waiting command-line tool inside an editor's application and the id of its preset, or two empty strings.
+
+    The application is recognised by the folder name the preset of ``platform`` looks for, and only when its tool is
+    really there and can be run, so an unrelated application with the same name gives nothing.
+    """
+    bundle_basename = os.path.basename(bundle_dir).casefold()
+    for preset in EDITOR_PRESETS:
+        if preset.platform != platform:
+            continue
+        for preset_bundle_basename, *program_parts in preset.bundle_programs:
+            if preset_bundle_basename.casefold() != bundle_basename:
+                continue
+            program_filename = resolve_editor_program(os.path.join(bundle_dir, *program_parts), platform=platform)
+            if program_filename:
+                return program_filename, preset.preset_id
+    return "", ""
+
+
+def chosen_program(filename: str, platform: str = EDITOR_PLATFORM) -> tuple[str, str]:
+    """Decide what a file picked in Settings' editor chooser stands for: a program for the Executable field, a preset, or both.
+
+    Returns the program and the id of the preset the pick stands for. TextEdit, picked as its application or as the
+    program inside it and recognised by the identifier it declares, stands for the TextEdit preset alone, with no
+    program: TextEdit is opened through macOS's open command, as the preset does, never by starting the program inside
+    its application. VS Code, Sublime Text or Zed, picked the same way on a system whose presets know them, stand for
+    their preset together with the waiting command-line tool inside the picked application: the program their
+    application declares also hands the file to the editor and returns at once. Another readable application gives the program it declares, with no
+    preset; anything else is kept as picked. This only judges a pick from the chooser: a command the user types by hand
+    is the user's own choice and is never refused or warned about.
+    """
+    bundle_dir = enclosing_bundle_dir(filename.rstrip(os.sep) or filename)
+    if bundle_dir:
+        bundle = read_bundle(bundle_dir)
+        if bundle is not None and is_textedit(bundle):
+            return "", TEXTEDIT_PRESET_ID
+        program_filename, preset_id = bundle_preset_program(bundle_dir, editor_platform(platform))
+        if preset_id:
+            return program_filename, preset_id
+    return chosen_application_program(filename), ""
+
+
+def build_editor_arguments(argument_template: str, file_filename: str) -> list[str]:
+    """Insert one absolute filename as one literal argument, appending it when the template omits it."""
+    if "\0" in argument_template or "\0" in file_filename:
+        raise ValueError("External editor arguments cannot contain a null character.")
+    if argument_template.replace('"""', '').count('"') % 2:
+        raise ValueError("External editor arguments contain an unclosed double quote.")
+    arguments = QProcess.splitCommand(argument_template)
+    file_count = 0
+    results = []
+    for argument in arguments:
+        if argument == EDITOR_FILE_PARAMETER:
+            file_count += 1
+            results.append(os.path.abspath(file_filename))
+        elif any(character in argument for character in ("{", "}", "$")):
+            raise ValueError("External editor arguments accept only a standalone {file} parameter.")
+        else:
+            results.append(argument)
+    if file_count > 1:
+        raise ValueError("External editor arguments must reference {file} only once.")
+    if not file_count:
+        results.append(os.path.abspath(file_filename))
+    return results

gitpane/tool/file_reveal.py

@@ -0,0 +1,94 @@
+"""Select local files through the desktop's shared file manager interface."""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import shutil
+import subprocess
+import sys
+from typing import TYPE_CHECKING
+from urllib.parse import quote_from_bytes, urlunsplit
+
+from gitpane.config import LINUX_PLATFORM, MACOS_OPEN_FILENAME, MACOS_PLATFORM, MILLISECONDS_PER_SECOND, TOOL_START_TIMEOUT_MS, WINDOWS_PLATFORM
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+# The program that asks the desktop's file manager, over the session bus, to select a file on Linux.
+DBUS_SEND_PROGRAM_NAME = "dbus-send"
+
+
+def reveal_file(filename: str, startup_id: str = "", platform: str = sys.platform,
+                run: Callable[..., subprocess.CompletedProcess[bytes]] = subprocess.run) -> bool:
+    """Request selection on a worker thread, returning false when folder fallback is needed.
+
+    On Linux the startup identifier goes to the file manager, which uses the user's action time it carries to come to
+    the front; an empty one leaves the window manager to decide. Windows brings Explorer forward by itself. On macOS
+    open -R asks the Finder to show the file selected in its folder's window, which needs no permission. The helper
+    programs are started through run, bounded by the tool startup timeout; a timeout is raised to the caller.
+    """
+    if platform == WINDOWS_PLATFORM:
+        return _reveal_windows_file(filename)
+    if platform == MACOS_PLATFORM:
+        return _reveal_macos_file(filename, run)
+    if platform != LINUX_PLATFORM:
+        return False
+    program_filename = shutil.which(DBUS_SEND_PROGRAM_NAME)
+    if program_filename is None:
+        return False
+    # Escape commas too: dbus-send treats them as array separators, even without a shell.
+    uri = urlunsplit(("file", "", quote_from_bytes(os.fsencode(filename), safe="/"), "", ""))
+    arguments = [program_filename, "--session", "--print-reply", f"--reply-timeout={TOOL_START_TIMEOUT_MS}",
+                 "--dest=org.freedesktop.FileManager1", "/org/freedesktop/FileManager1", "org.freedesktop.FileManager1.ShowItems", f"array:string:{uri}", f"string:{startup_id}"]
+    result = run(arguments, shell=False, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=TOOL_START_TIMEOUT_MS / MILLISECONDS_PER_SECOND, check=False)
+    return result.returncode == 0
+
+
+def selection_helper_available(platform: str = sys.platform) -> bool:
+    """Tell whether reveal_file has a helper to ask for the selection: on Linux it needs dbus-send, which a system may lack."""
+    return platform != LINUX_PLATFORM or shutil.which(DBUS_SEND_PROGRAM_NAME) is not None
+
+
+def _reveal_macos_file(filename: str, run: Callable[..., subprocess.CompletedProcess[bytes]]) -> bool:
+    """Ask the Finder, through open -R, to select the exact file; the name is one argument and no shell reads it.
+
+    A refusal (a file gone since the click, for instance) answers false, so the caller opens the folder instead.
+    """
+    result = run([MACOS_OPEN_FILENAME, "-R", filename], shell=False, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                 timeout=TOOL_START_TIMEOUT_MS / MILLISECONDS_PER_SECOND, check=False)
+    return result.returncode == 0
+
+
+def _reveal_windows_file(filename: str) -> bool:
+    """Use the Shell API to select an exact Unicode path without command-line parsing."""
+    shell = ctypes.WinDLL("shell32")
+    ole = ctypes.WinDLL("ole32")
+    ole.CoInitializeEx.argtypes = [ctypes.c_void_p, ctypes.c_uint32]
+    ole.CoInitializeEx.restype = ctypes.c_int32
+    ole.CoUninitialize.argtypes = []
+    ole.CoUninitialize.restype = None
+    ole.CoTaskMemFree.argtypes = [ctypes.c_void_p]
+    ole.CoTaskMemFree.restype = None
+    shell.SHParseDisplayName.argtypes = [ctypes.c_wchar_p, ctypes.c_void_p, ctypes.POINTER(ctypes.c_void_p), ctypes.c_uint32, ctypes.POINTER(ctypes.c_uint32)]
+    shell.SHParseDisplayName.restype = ctypes.c_int32
+    shell.SHOpenFolderAndSelectItems.argtypes = [ctypes.c_void_p, ctypes.c_uint32, ctypes.POINTER(ctypes.c_void_p), ctypes.c_uint32]
+    shell.SHOpenFolderAndSelectItems.restype = ctypes.c_int32
+    apartment_threaded = 0x2
+    disable_legacy_dde = 0x4
+    if ole.CoInitializeEx(None, apartment_threaded | disable_legacy_dde) < 0:
+        raise OSError("The system could not initialize file selection.")
+    item_id = ctypes.c_void_p()
+    try:
+        no_attributes = 0
+        if shell.SHParseDisplayName(filename, None, ctypes.byref(item_id), no_attributes, None) < 0:
+            raise OSError("The system could not locate the selected file.")
+        single_absolute_item = 0
+        no_flags = 0
+        if shell.SHOpenFolderAndSelectItems(item_id, single_absolute_item, None, no_flags) < 0:
+            raise OSError("The system refused to select the file in the file explorer.")
+        return True
+    finally:
+        if item_id.value is not None:
+            ole.CoTaskMemFree(item_id)
+        ole.CoUninitialize()