gitpane 1.0.0__py3-none-any.whl

gitpane/system/desktop_shortcut.py

@@ -0,0 +1,536 @@
+"""Put the shortcuts that start the installed GitPane where the user's system lists them, in the form each system reads.
+
+pip and pipx cannot run anything at install time, so GitPane writes its own shortcut once it is installed. The
+shortcut starts the gitpane command of the running installation or, when it has none, the running Python with ``-P
+-m`` and the application module; never with ``--log``. Writing it again rewrites the same file with the current paths,
+for example after a Python upgrade moved the launcher; nothing else on the desktop is ever touched or deleted. A desktop
+folder that is the home folder itself counts as no desktop folder, so nothing is written among the user's files. On Linux the same click also writes the same entry into the user's applications menu,
+where the desktop looks up the name and the icon of a running GitPane, whether the desktop folder exists or not. Each
+file gets its own line in the report, so a file written is never announced as failed because of the other one.
+
+On macOS the shortcut is a small application bundle whose program is a sh script that hands its process over to the
+command. No process watches the bundle afterwards, so the Dock may name the running GitPane after Python rather than
+after the bundle; that is something to check on a Mac. On Windows a ``.lnk`` file is made from scratch by PowerShell
+through the WScript.Shell object, the paths and the arguments travelling only in environment variables.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import ntpath
+import os
+import plistlib
+import shlex
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QStandardPaths
+
+from gitpane.config import (
+    APPLICATION_ICON_ICO_BASENAME,
+    APPLICATION_NAME,
+    DESKTOP_SHORTCUT_HELPER_TIMEOUT_MS,
+    LINUX_PLATFORM,
+    MACOS_BUNDLE_IDENTIFIER,
+    MACOS_PLATFORM,
+    MILLISECONDS_PER_SECOND,
+    SYSTEM_ROOT_ENVIRONMENT_NAME,
+    UI_RESOURCE_DIR_NAME,
+    UI_RESOURCE_PACKAGE_NAME,
+    WINDOWS_PLATFORM,
+    application_icon_png_basename,
+)
+from gitpane.system.icns_image import ICNS_256_PNG_TYPE, icns_bytes
+from gitpane.system.installed_launcher import StartCommand, command_line, installation_script_dirs, running_in_virtual_environment, start_command, start_command_line
+from gitpane.system.path_identity import canonical_path
+from gitpane.system.qt_folder import native_folder_path
+from gitpane.tool.app_bundle import BUNDLE_EXECUTABLE_KEY, BUNDLE_IDENTIFIER_KEY, BUNDLE_SUFFIX, CONTENTS_DIR_BASENAME, INFO_PLIST_BASENAME, MACOS_DIR_BASENAME
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping, Sequence
+
+    ShortcutRun = Callable[..., subprocess.CompletedProcess[bytes]]
+
+# The largest packaged picture of the logo: desktops scale it down, never up.
+SHORTCUT_ICON_SIDE = 256
+DESKTOP_ENTRY_EXTENSION = ".desktop"
+DESKTOP_ENTRY_COMMENT = "Browse Git repositories"
+DESKTOP_ENTRY_CATEGORIES = "Development;RevisionControl;"
+# Desktops only start a launcher file its owner may run; nobody else may change it.
+SHORTCUT_PROGRAM_MODE = 0o755
+# The entry of the applications menu is read by the desktop, never run: everyone may read it, only its owner change it.
+APPLICATION_ENTRY_MODE = 0o644
+SHORTCUT_LINE_END = "\n"
+SHORTCUT_TEXT_ENCODING = "utf-8"
+# Names the temporary file an entry is written to before it takes the entry's name, in the same folder. Its suffix is
+# not the entry's: a file left by a GitPane killed during the write must not be listed by the menu as a second GitPane.
+DESKTOP_ENTRY_TEMPORARY_PREFIX = "." + APPLICATION_NAME + "-"
+DESKTOP_ENTRY_TEMPORARY_SUFFIX = ".tmp"
+GIO_FILENAME = "gio"
+GIO_TRUSTED_ATTRIBUTE = "metadata::trusted"
+GIO_TRUSTED_VALUE = "true"
+# Characters the Desktop Entry specification reserves inside a quoted Exec argument, each escaped with a backslash.
+# The backslash itself comes first, so the backslashes added for the others are not escaped twice.
+EXEC_RESERVED_CHARACTERS = ("\\", '"', "`", "$")
+EXEC_QUOTE = '"'
+EXEC_FIELD_CODE_MARK = "%"
+STRING_ESCAPE_CHARACTER = "\\"
+# Below this code point, and at DELETE, a character is a control character no desktop entry value may hold.
+FIRST_PRINTABLE_CODE_POINT = 0x20
+DELETE_CODE_POINT = 0x7F
+# The macOS bundle: its resources folder, the icon file's extension, and the Info.plist keys app_bundle does not read.
+RESOURCES_DIR_BASENAME = "Resources"
+ICNS_EXTENSION = ".icns"
+BUNDLE_NAME_KEY = "CFBundleName"
+BUNDLE_DISPLAY_NAME_KEY = "CFBundleDisplayName"
+BUNDLE_ICON_FILE_KEY = "CFBundleIconFile"
+BUNDLE_PACKAGE_TYPE_KEY = "CFBundlePackageType"
+BUNDLE_APPLICATION_PACKAGE_TYPE = "APPL"
+BUNDLE_INFO_DICTIONARY_VERSION_KEY = "CFBundleInfoDictionaryVersion"
+BUNDLE_INFO_DICTIONARY_VERSION = "6.0"
+HIGH_RESOLUTION_CAPABLE_KEY = "NSHighResolutionCapable"
+BUNDLE_SCRIPT_SHELL_LINE = "#!/bin/sh"
+# The Windows shortcut: its extension, where PowerShell lives under the Windows folder, and the variables that carry the paths.
+WINDOWS_SHORTCUT_EXTENSION = ".lnk"
+WINDOWS_POWERSHELL_PATH_PARTS = ("System32", "WindowsPowerShell", "v1.0", "powershell.exe")
+WINDOWS_POWERSHELL_OPTIONS = ("-NoProfile", "-NonInteractive", "-Command")
+WINDOWS_SHORTCUT_FILENAME_VARIABLE = "GITPANE_SHORTCUT_FILENAME"
+WINDOWS_SHORTCUT_TARGET_VARIABLE = "GITPANE_SHORTCUT_TARGET"
+WINDOWS_SHORTCUT_ICON_VARIABLE = "GITPANE_SHORTCUT_ICON"
+WINDOWS_SHORTCUT_ARGUMENTS_VARIABLE = "GITPANE_SHORTCUT_ARGUMENTS"
+# The paths and the arguments travel only in the environment, so PowerShell never parses them as part of its script: a
+# quote, a dollar or a semicolon in a folder name stays plain text. [string] turns a variable Windows dropped because it
+# was empty (the gitpane command takes no argument) into an empty Arguments field. The icon index 0 is the first
+# picture of the .ico file.
+WINDOWS_SHORTCUT_SCRIPT = "; ".join([
+    "$ErrorActionPreference = 'Stop'",
+    "$shell = New-Object -ComObject WScript.Shell",
+    "$shortcut = $shell.CreateShortcut($env:" + WINDOWS_SHORTCUT_FILENAME_VARIABLE + ")",
+    "$shortcut.TargetPath = $env:" + WINDOWS_SHORTCUT_TARGET_VARIABLE,
+    "$shortcut.Arguments = [string]$env:" + WINDOWS_SHORTCUT_ARGUMENTS_VARIABLE,
+    "$shortcut.IconLocation = $env:" + WINDOWS_SHORTCUT_ICON_VARIABLE + " + ',0'",
+    "$shortcut.Save()",
+])
+POWERSHELL_EXIT_TEMPLATE = "PowerShell exited with code {code}"
+NO_APPLICATIONS_FOLDER_DETAIL = "the system names no applications folder"
+
+
+class ShortcutOutcomeKind(Enum):
+    """What a result line says of its file, without any colour: the colour belongs to the interface."""
+
+    WRITTEN = "written"
+    NOT_POSSIBLE = "not possible"
+    FAILED = "failed"
+
+
+class ShortcutStatus(Enum):
+    """How the write of one shortcut file ended: each value pairs the line Settings shows, ``{detail}`` filled by the outcome, with what it says of the file."""
+
+    CREATED = ("Desktop shortcut created: {detail}", ShortcutOutcomeKind.WRITTEN)
+    CREATED_NOT_SHOWN = ("As stated by the note below, {detail}: GitPane is added to the searchable applications list, and its desktop icon will appear once the steps are done.",
+                         ShortcutOutcomeKind.NOT_POSSIBLE)
+    """The shortcut is written and marked trusted, so its icon appears as soon as the desktop can show it, without a new click.
+
+    The desktop cannot show it yet; ``{detail}`` says why. Used when the applications entry of the same report was
+    added, since the line says so. This module never decides this status: the writer reports CREATED, and the decision
+    about the desktop replaces it.
+    """
+    CREATED_NOT_SHOWN_ENTRY_FAILED = ("As stated by the note below, {detail}: GitPane's desktop icon will appear once the steps are done.", ShortcutOutcomeKind.NOT_POSSIBLE)
+    """The same shortcut written and marked trusted, when the applications entry of the same click could not be written.
+
+    The line says nothing of the applications list, whose red line follows it. This module never decides this status
+    either: the decision about the desktop picks it from the entry's line of the same report.
+    """
+    NO_DESKTOP = ("Desktop folder not found: {detail}", ShortcutOutcomeKind.NOT_POSSIBLE)
+    NO_DESKTOP_NAMED = ("The system names no desktop folder", ShortcutOutcomeKind.NOT_POSSIBLE)
+    UNSUPPORTED_SYSTEM = ("No desktop shortcut on this system: {detail}", ShortcutOutcomeKind.FAILED)
+    WRITE_FAILED = ("Could not create the desktop shortcut: {detail}", ShortcutOutcomeKind.FAILED)
+    NO_START_COMMAND = ("Cannot tell which program starts this GitPane, so no shortcut was written", ShortcutOutcomeKind.FAILED)
+    APPLICATION_ENTRY_ADDED = ("Added to the applications list: {detail}", ShortcutOutcomeKind.WRITTEN)
+    APPLICATION_ENTRY_FAILED = ("Could not add GitPane to the applications list: {detail}", ShortcutOutcomeKind.FAILED)
+
+    @property
+    def text(self) -> str:
+        """Return the line Settings shows, before ``{detail}`` is filled."""
+        text, _outcome_kind = self.value
+        return text
+
+    @property
+    def outcome_kind(self) -> ShortcutOutcomeKind:
+        """Return whether the file was written, could not be, or failed."""
+        _text, outcome_kind = self.value
+        return outcome_kind
+
+
+@dataclass(frozen=True)
+class ShortcutOutcome:
+    """The end of the write of one shortcut file, with the path or the reason its line names."""
+
+    status: ShortcutStatus
+    detail: str = ""
+
+    def line(self) -> str:
+        """Return the one line Settings shows for this file."""
+        return self.status.text.format(detail=self.detail)
+
+
+@dataclass(frozen=True)
+class ShortcutReport:
+    """One line per file written or tried, the desktop shortcut first, then the command line the shortcut starts.
+
+    ``start_command_line`` is empty when nothing was written for want of a shortcut form or of a command to start.
+    """
+
+    file_outcomes: tuple[ShortcutOutcome, ...]
+    start_command_line: str = ""
+
+
+@dataclass(frozen=True)
+class ShortcutForm:
+    """What a system reads as a desktop shortcut: the name it has on the desktop, the function that writes it, and the one that writes its applications menu entry.
+
+    ``write`` receives the shortcut's path, the command it starts, the helper runner and the environment;
+    ``application_entry_write`` receives the entry's path and the command, and is None on a system whose menu GitPane
+    does not write.
+    """
+
+    basename: str
+    write: Callable[[str, StartCommand, ShortcutRun, Mapping[str, str]], None]
+    application_entry_write: Callable[[str, StartCommand], None] | None = None
+
+
+def _refuse_control_characters(text: str) -> None:
+    """Raise ValueError when ``text`` holds a line break or another control character, which no desktop entry value may hold."""
+    for character in text:
+        code_point = ord(character)
+        if code_point < FIRST_PRINTABLE_CODE_POINT or code_point == DELETE_CODE_POINT:
+            raise ValueError("The text holds a control character: " + repr(text))
+
+
+def desktop_entry_string_value(text: str) -> str:
+    """Write ``text`` as a desktop entry string value: backslashes doubled, control characters refused with ValueError."""
+    _refuse_control_characters(text)
+    return text.replace(STRING_ESCAPE_CHARACTER, STRING_ESCAPE_CHARACTER + STRING_ESCAPE_CHARACTER)
+
+
+def quoted_exec_argument(argument: str) -> str:
+    """Quote one argument of an Exec key whole, so no desktop splits or expands it; the string escape of the key is left to the caller.
+
+    The Desktop Entry specification escapes ``\\ " ` $`` inside the quotes with a backslash; ``%`` starts a field code,
+    so a literal one is doubled. An argument with a line break or another control character raises ValueError.
+    """
+    _refuse_control_characters(argument)
+    quoted = argument
+    for character in EXEC_RESERVED_CHARACTERS:
+        quoted = quoted.replace(character, STRING_ESCAPE_CHARACTER + character)
+    quoted = EXEC_QUOTE + quoted + EXEC_QUOTE
+    return quoted.replace(EXEC_FIELD_CODE_MARK, EXEC_FIELD_CODE_MARK + EXEC_FIELD_CODE_MARK)
+
+
+def desktop_entry_exec_value(arguments: Sequence[str]) -> str:
+    """Write the program and its arguments as the value of an Exec key, each one quoted whole, separated by a space.
+
+    Exec is also a string value, whose own escape a desktop undoes before it reads the quoting. That escape is applied
+    once, to the whole joined line: applied to each argument and then to the line, every backslash would be doubled
+    twice. A literal backslash of a path therefore takes four.
+    """
+    quoted_arguments = []
+    for argument in arguments:
+        quoted_arguments.append(quoted_exec_argument(argument))
+    return desktop_entry_string_value(" ".join(quoted_arguments))
+
+
+def desktop_entry_text(command: StartCommand, icon_filename: str) -> str:
+    """Build the desktop entry that starts ``command`` with the packaged logo, grouped under GitPane's own window class."""
+    entry_lines = [
+        "[Desktop Entry]",
+        "Type=Application",
+        "Name=" + desktop_entry_string_value(APPLICATION_NAME),
+        "Comment=" + desktop_entry_string_value(DESKTOP_ENTRY_COMMENT),
+        "Exec=" + desktop_entry_exec_value((command.program_filename, *command.arguments)),
+        "Icon=" + desktop_entry_string_value(icon_filename),
+        "Terminal=false",
+        "Categories=" + DESKTOP_ENTRY_CATEGORIES,
+        "StartupWMClass=" + desktop_entry_string_value(APPLICATION_NAME),
+    ]
+    return SHORTCUT_LINE_END.join(entry_lines) + SHORTCUT_LINE_END
+
+
+def packaged_resource_filename(basename: str) -> str:
+    """Return the path of a data file GitPane ships in its resource folder, read without importing any interface code."""
+    return str(importlib.resources.files(UI_RESOURCE_PACKAGE_NAME).joinpath(UI_RESOURCE_DIR_NAME, basename))
+
+
+def packaged_resource_bytes(basename: str) -> bytes:
+    """Read a data file GitPane ships in its resource folder."""
+    return importlib.resources.files(UI_RESOURCE_PACKAGE_NAME).joinpath(UI_RESOURCE_DIR_NAME, basename).read_bytes()
+
+
+def helper_timeout_seconds() -> float:
+    """Return the bound of a helper program the shortcut runs, in the seconds ``subprocess`` counts in."""
+    return DESKTOP_SHORTCUT_HELPER_TIMEOUT_MS / MILLISECONDS_PER_SECOND
+
+
+def write_desktop_entry(entry_filename: str, text: str, mode: int) -> None:
+    """Write ``text`` as the whole desktop entry at ``entry_filename``, with ``mode``, replacing what was there.
+
+    The text goes to a temporary file of the same folder, which then takes the entry's name: a symbolic link left at
+    that name is replaced, never followed, so the write cannot land in another file of the user. A failed write
+    removes the temporary file and raises OSError.
+    """
+    entry_dir = os.path.dirname(entry_filename)
+    descriptor, temporary_filename = tempfile.mkstemp(dir=entry_dir, prefix=DESKTOP_ENTRY_TEMPORARY_PREFIX, suffix=DESKTOP_ENTRY_TEMPORARY_SUFFIX)
+    try:
+        with os.fdopen(descriptor, "w", encoding=SHORTCUT_TEXT_ENCODING, newline=SHORTCUT_LINE_END) as stream:
+            stream.write(text)
+        os.chmod(temporary_filename, mode)
+        os.replace(temporary_filename, entry_filename)
+    except BaseException:
+        if os.path.lexists(temporary_filename):
+            os.remove(temporary_filename)
+        raise
+
+
+def linux_desktop_entry_text(command: StartCommand) -> str:
+    """Build the desktop entry of ``command`` with the largest packaged logo, the one text of the desktop shortcut and of the applications entry."""
+    return desktop_entry_text(command, packaged_resource_filename(application_icon_png_basename(SHORTCUT_ICON_SIDE)))
+
+
+def write_linux_shortcut(shortcut_filename: str, command: StartCommand, run: ShortcutRun, environment_by_name: Mapping[str, str]) -> None:
+    """Write the desktop entry, let its owner run it, then ask gio to mark it trusted.
+
+    The environment is not needed here: gio inherits GitPane's own, which holds the session bus it talks to.
+    """
+    write_desktop_entry(shortcut_filename, linux_desktop_entry_text(command), SHORTCUT_PROGRAM_MODE)
+    # GNOME's desktop icons only start a launcher marked trusted, other desktops ignore the mark, and a desktop without
+    # gio simply has no such mark: whatever gio answers, the shortcut is written.
+    try:
+        run([GIO_FILENAME, "set", shortcut_filename, GIO_TRUSTED_ATTRIBUTE, GIO_TRUSTED_VALUE], shell=False, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL, check=False, timeout=helper_timeout_seconds())
+    except (OSError, subprocess.SubprocessError):
+        pass
+
+
+def write_linux_application_entry(entry_filename: str, command: StartCommand) -> None:
+    """Write the applications menu entry of ``command``, the same text as the desktop shortcut.
+
+    GNOME finds the name and the icon of a running GitPane in this entry, matched by its file name and its
+    StartupWMClass; it needs no trust mark, since only the desktop's icons ask for one.
+    """
+    write_desktop_entry(entry_filename, linux_desktop_entry_text(command), APPLICATION_ENTRY_MODE)
+
+
+def bundle_info_plist_bytes() -> bytes:
+    """Return the Info.plist of the desktop bundle: GitPane's name, program, icon and reverse-DNS identifier."""
+    info_by_key = {
+        BUNDLE_NAME_KEY: APPLICATION_NAME,
+        BUNDLE_DISPLAY_NAME_KEY: APPLICATION_NAME,
+        BUNDLE_EXECUTABLE_KEY: APPLICATION_NAME,
+        BUNDLE_ICON_FILE_KEY: APPLICATION_NAME,
+        BUNDLE_IDENTIFIER_KEY: MACOS_BUNDLE_IDENTIFIER,
+        BUNDLE_PACKAGE_TYPE_KEY: BUNDLE_APPLICATION_PACKAGE_TYPE,
+        BUNDLE_INFO_DICTIONARY_VERSION_KEY: BUNDLE_INFO_DICTIONARY_VERSION,
+        HIGH_RESOLUTION_CAPABLE_KEY: True,
+    }
+    return plistlib.dumps(info_by_key)
+
+
+def bundle_launcher_script(command: StartCommand) -> str:
+    """Return the bundle's program: a sh script that hands its process to ``command``, each part quoted for sh, followed by every argument it got."""
+    return BUNDLE_SCRIPT_SHELL_LINE + SHORTCUT_LINE_END + "exec " + shlex.join((command.program_filename, *command.arguments)) + ' "$@"' + SHORTCUT_LINE_END
+
+
+def write_bytes(filename: str, data: bytes) -> None:
+    """Write ``data`` as the whole content of ``filename``, replacing what was there."""
+    with open(filename, "wb") as stream:
+        stream.write(data)
+
+
+def write_macos_shortcut(shortcut_filename: str, command: StartCommand, run: ShortcutRun, environment_by_name: Mapping[str, str]) -> None:
+    """Build, or build again, the ``.app`` folder whose program starts ``command``, with the packaged logo as its icon.
+
+    Only the bundle's three own files are written: Info.plist, the program and the icon. A file anyone else put in the
+    folder stays, and nothing is deleted. No helper program is needed, so ``run`` and the environment are not used.
+    """
+    contents_dir = os.path.join(shortcut_filename, CONTENTS_DIR_BASENAME)
+    program_dir = os.path.join(contents_dir, MACOS_DIR_BASENAME)
+    resources_dir = os.path.join(contents_dir, RESOURCES_DIR_BASENAME)
+    os.makedirs(program_dir, exist_ok=True)
+    os.makedirs(resources_dir, exist_ok=True)
+    write_bytes(os.path.join(contents_dir, INFO_PLIST_BASENAME), bundle_info_plist_bytes())
+    program_filename = os.path.join(program_dir, APPLICATION_NAME)
+    with open(program_filename, "w", encoding=SHORTCUT_TEXT_ENCODING, newline=SHORTCUT_LINE_END) as stream:
+        stream.write(bundle_launcher_script(command))
+    os.chmod(program_filename, SHORTCUT_PROGRAM_MODE)
+    icon_png = packaged_resource_bytes(application_icon_png_basename(SHORTCUT_ICON_SIDE))
+    write_bytes(os.path.join(resources_dir, APPLICATION_NAME + ICNS_EXTENSION), icns_bytes([(ICNS_256_PNG_TYPE, icon_png)]))
+    # Finder only draws a bundle's icon again when the folder's date changes, so a rewritten icon shows at once.
+    os.utime(shortcut_filename)
+
+
+def windows_shortcut_command(system_root: str, shortcut_filename: str, command: StartCommand, icon_filename: str,
+                             base_environment: Mapping[str, str]) -> tuple[list[str], dict[str, str]]:
+    """Return the PowerShell command that makes the .lnk, and the environment that carries its three paths and the command's arguments.
+
+    The arguments are joined the way Windows splits a command line, empty for the gitpane command.
+
+    PowerShell is taken from the Windows folder, never looked up in PATH. ``base_environment`` is copied, never changed.
+    """
+    # This only runs on Windows; ntpath keeps the path the same when the tests run it on another system.
+    powershell_filename = ntpath.join(system_root, *WINDOWS_POWERSHELL_PATH_PARTS)
+    arguments = [powershell_filename, *WINDOWS_POWERSHELL_OPTIONS, WINDOWS_SHORTCUT_SCRIPT]
+    environment_by_name = dict(base_environment)
+    environment_by_name[WINDOWS_SHORTCUT_FILENAME_VARIABLE] = shortcut_filename
+    environment_by_name[WINDOWS_SHORTCUT_TARGET_VARIABLE] = command.program_filename
+    environment_by_name[WINDOWS_SHORTCUT_ARGUMENTS_VARIABLE] = command_line(command.arguments, WINDOWS_PLATFORM)
+    environment_by_name[WINDOWS_SHORTCUT_ICON_VARIABLE] = icon_filename
+    return arguments, environment_by_name
+
+
+def first_error_line(stderr: bytes, returncode: int) -> str:
+    """Return the first non-empty line PowerShell wrote on its error output, or a line naming its exit code when it wrote none."""
+    for line in stderr.decode(SHORTCUT_TEXT_ENCODING, errors="replace").splitlines():
+        if line.strip():
+            return line.strip()
+    return POWERSHELL_EXIT_TEMPLATE.format(code=returncode)
+
+
+def write_windows_shortcut(shortcut_filename: str, command: StartCommand, run: ShortcutRun, environment_by_name: Mapping[str, str]) -> None:
+    """Make, or make again, the .lnk that starts ``command`` with the packaged logo, through PowerShell; a refusal raises OSError.
+
+    An earlier GitPane.lnk is removed first, so the new one starts empty and holds only the target, its arguments and
+    the icon.
+    """
+    system_root = environment_by_name.get(SYSTEM_ROOT_ENVIRONMENT_NAME, "")
+    if not system_root:
+        raise OSError(SYSTEM_ROOT_ENVIRONMENT_NAME + " is not set, so PowerShell cannot be found")
+    # WScript.Shell's CreateShortcut opens an existing .lnk and Save keeps every field the script does not set: an
+    # earlier GitPane.lnk that started a checkout's main.py kept that argument, which the launcher refused, so the
+    # shortcut started nothing. Removing the old file makes CreateShortcut start from an empty shortcut.
+    if os.path.isfile(shortcut_filename):
+        os.remove(shortcut_filename)
+    arguments, command_environment = windows_shortcut_command(system_root, shortcut_filename, command, packaged_resource_filename(APPLICATION_ICON_ICO_BASENAME),
+                                                              environment_by_name)
+    completed = run(arguments, env=command_environment, stdin=subprocess.DEVNULL, capture_output=True, check=False, timeout=helper_timeout_seconds(),
+                    creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0)
+    if completed.returncode != 0:
+        raise OSError(first_error_line(completed.stderr or b"", completed.returncode))
+
+
+SHORTCUT_FORM_BY_PLATFORM = {
+    WINDOWS_PLATFORM: ShortcutForm(APPLICATION_NAME + WINDOWS_SHORTCUT_EXTENSION, write_windows_shortcut),
+    LINUX_PLATFORM: ShortcutForm(APPLICATION_NAME + DESKTOP_ENTRY_EXTENSION, write_linux_shortcut, write_linux_application_entry),
+    MACOS_PLATFORM: ShortcutForm(APPLICATION_NAME + BUNDLE_SUFFIX, write_macos_shortcut),
+}
+
+
+def shortcut_form(platform: str) -> ShortcutForm:
+    """Return the shortcut form of ``platform``; a system missing from the table raises OSError."""
+    form = SHORTCUT_FORM_BY_PLATFORM.get(platform)
+    if form is None:
+        raise OSError(platform)
+    return form
+
+
+def named_desktop_dir(desktop_dir: str, home_dir: str) -> str:
+    """Return the desktop folder the shortcut may go to: ``desktop_dir`` as given, or an empty text when the system names none.
+
+    xdg-user-dirs makes the home folder the desktop folder once the user has removed theirs; a launcher written there
+    would land among the user's files, not on a desktop, so that folder counts as none. The folders are compared by
+    identity, so a trailing separator, a ``..`` or a link changes nothing; that reads the disk, as both callers do,
+    which run off the window's thread. An empty ``home_dir`` compares with nothing.
+    """
+    if not desktop_dir:
+        return ""
+    if home_dir and canonical_path(desktop_dir) == canonical_path(home_dir):
+        return ""
+    return desktop_dir
+
+
+def desktop_shortcut_outcome(desktop_dir: str, form: ShortcutForm, command: StartCommand, run: ShortcutRun, environment_by_name: Mapping[str, str]) -> ShortcutOutcome:
+    """Write, or write again, the desktop shortcut of ``command`` into ``desktop_dir``, and say how it went.
+
+    A desktop folder the system does not name, or that is not there, is no failure: nothing can be written, and the
+    folder is never created.
+    """
+    if not desktop_dir:
+        return ShortcutOutcome(ShortcutStatus.NO_DESKTOP_NAMED)
+    if not os.path.isdir(desktop_dir):
+        return ShortcutOutcome(ShortcutStatus.NO_DESKTOP, desktop_dir)
+    shortcut_filename = os.path.join(desktop_dir, form.basename)
+    try:
+        form.write(shortcut_filename, command, run, environment_by_name)
+    except (OSError, ValueError, subprocess.SubprocessError) as error:
+        return ShortcutOutcome(ShortcutStatus.WRITE_FAILED, str(error))
+    return ShortcutOutcome(ShortcutStatus.CREATED, shortcut_filename)
+
+
+def application_entry_outcome(applications_dir: str, application_entry_write: Callable[[str, StartCommand], None], basename: str, command: StartCommand) -> ShortcutOutcome:
+    """Write, or write again, the applications menu entry of ``command`` into ``applications_dir``, created when missing, and say how it went."""
+    if not applications_dir:
+        return ShortcutOutcome(ShortcutStatus.APPLICATION_ENTRY_FAILED, NO_APPLICATIONS_FOLDER_DETAIL)
+    entry_filename = os.path.join(applications_dir, basename)
+    try:
+        os.makedirs(applications_dir, exist_ok=True)
+        application_entry_write(entry_filename, command)
+    except (OSError, ValueError) as error:
+        return ShortcutOutcome(ShortcutStatus.APPLICATION_ENTRY_FAILED, str(error))
+    return ShortcutOutcome(ShortcutStatus.APPLICATION_ENTRY_ADDED, entry_filename)
+
+
+def create_desktop_shortcut(desktop_dir: str, command: StartCommand | None, platform: str = sys.platform, run: ShortcutRun = subprocess.run,
+                            environment_by_name: Mapping[str, str] | None = None, applications_dir: str = "", home_dir: str = "") -> ShortcutReport:
+    """Write, or write again, the shortcut that starts ``command`` into ``desktop_dir``, then on Linux its applications entry into ``applications_dir``.
+
+    The applications menu is where the desktop finds the name and the icon of a running GitPane, so its entry does not
+    depend on the desktop folder: it is written whether that folder exists or not, and whatever happened to the
+    desktop shortcut. Each file has its own line, so a file written is never announced as failed because of the other.
+    The applications folder belongs to the user's own data and is created when missing; the desktop folder never is.
+    A desktop folder that is ``home_dir`` itself counts as no desktop folder named, so no launcher lands among the
+    user's files.
+
+    Nothing is written when the system has no shortcut form or when there is no command to start. Only the shortcut's
+    and the entry's own fixed names are written or replaced, nothing else is deleted.
+    """
+    try:
+        form = shortcut_form(platform)
+    except OSError:
+        return ShortcutReport((ShortcutOutcome(ShortcutStatus.UNSUPPORTED_SYSTEM, platform),))
+    if command is None:
+        return ShortcutReport((ShortcutOutcome(ShortcutStatus.NO_START_COMMAND),))
+    file_outcomes = [desktop_shortcut_outcome(named_desktop_dir(desktop_dir, home_dir), form, command, run, environment_by_name if environment_by_name is not None else os.environ)]
+    if form.application_entry_write is not None:
+        file_outcomes.append(application_entry_outcome(applications_dir, form.application_entry_write, form.basename, command))
+    return ShortcutReport(tuple(file_outcomes), start_command_line(command, platform))
+
+
+def installed_start_command(application_module_name: str) -> StartCommand | None:
+    """Choose what the shortcut of the running installation starts: its gitpane command, or the running Python on ``application_module_name``.
+
+    The path of the running Python is kept as Python gives it. A system with no known launcher name leaves nothing to
+    start; ``create_desktop_shortcut`` then says the system has no shortcut form.
+    """
+    try:
+        return start_command(installation_script_dirs(running_in_virtual_environment()), sys.platform, sys.executable or "", application_module_name)
+    except OSError:
+        return None
+
+
+def create_installed_desktop_shortcut(application_module_name: str = "") -> ShortcutReport:
+    """Write the shortcut of the running installation into the desktop folder the system names, and on Linux its applications entry.
+
+    ``application_module_name`` is the module the running Python starts with ``-m`` when the installation has no
+    gitpane command; the wiring passes the name the import system gave the application module. Qt follows XDG
+    user-dirs on Linux and the Desktop known folder on Windows, OneDrive included; the applications folder is
+    ``$XDG_DATA_HOME/applications`` on Linux. The home folder goes with them, read as the desktop icon facts read it,
+    so a desktop folder that is the home folder gets no launcher. Qt only reads the system's folder settings, so this
+    can run on the Settings page's worker thread. Both folders are written with the system's own separator, which Qt
+    does not use on Windows, so the paths Settings shows read as the system writes them.
+    """
+    desktop_dir = native_folder_path(QStandardPaths.writableLocation(QStandardPaths.StandardLocation.DesktopLocation), sys.platform)
+    applications_dir = native_folder_path(QStandardPaths.writableLocation(QStandardPaths.StandardLocation.ApplicationsLocation), sys.platform)
+    return create_desktop_shortcut(desktop_dir, installed_start_command(application_module_name), applications_dir=applications_dir, home_dir=os.path.expanduser("~"))

gitpane/system/icns_image.py

@@ -0,0 +1,35 @@
+"""Pack PNG pictures into the ICNS file a macOS application bundle shows as its icon.
+
+An ICNS file is a small container: a four-byte magic, the whole file's length, then one entry per picture, each made
+of a four-byte type naming its size, its own length (header included) and its data. All lengths are big-endian.
+"""
+
+from __future__ import annotations
+
+import struct
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+ICNS_MAGIC = b"icns"
+# A 256x256 PNG entry, read by macOS since 10.7.
+ICNS_256_PNG_TYPE = b"ic08"
+ICNS_LENGTH_FORMAT = ">I"
+ICNS_TYPE_LENGTH = 4
+# The magic or the type, followed by the four-byte length.
+ICNS_HEADER_LENGTH = ICNS_TYPE_LENGTH + struct.calcsize(ICNS_LENGTH_FORMAT)
+ICNS_ENTRY_HEADER_LENGTH = ICNS_TYPE_LENGTH + struct.calcsize(ICNS_LENGTH_FORMAT)
+
+
+def icns_bytes(entries: Sequence[tuple[bytes, bytes]]) -> bytes:
+    """Return the ICNS file holding each ``(type, data)`` entry in the given order; a type that is not four bytes raises ValueError."""
+    entry_chunks = []
+    total_length = ICNS_HEADER_LENGTH
+    for entry_type, data in entries:
+        if len(entry_type) != ICNS_TYPE_LENGTH:
+            raise ValueError("An ICNS entry type is four bytes: " + repr(entry_type))
+        entry_length = ICNS_ENTRY_HEADER_LENGTH + len(data)
+        entry_chunks.append(entry_type + struct.pack(ICNS_LENGTH_FORMAT, entry_length) + data)
+        total_length += entry_length
+    return ICNS_MAGIC + struct.pack(ICNS_LENGTH_FORMAT, total_length) + b"".join(entry_chunks)