gitpane 1.0.0__py3-none-any.whl

gitpane/transport/credential_read_retry.py

@@ -0,0 +1,35 @@
+"""Decide when a failed Git network step is started again because the credential manager could not read back a secret.
+
+Git Credential Manager sometimes fails to read a secret it keeps, right after storing it, while the reads before and
+after succeed. It fails before Git sends any authenticated request, so a step that is safe to repeat is started again
+a moment later, a bounded number of times, instead of asking the user to click Retry. Each service decides which of its
+own steps are safe to repeat; this module holds the rule they share and the line the console shows.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from gitpane.config import CREDENTIAL_READ_RETRY_DELAY_MS, CREDENTIAL_READ_RETRY_LIMIT, MILLISECONDS_PER_SECOND, SharedText
+from gitpane.process.process_runner import ProcessStatus
+from gitpane.transport.git_refusal import credential_store_read_failed
+
+if TYPE_CHECKING:
+    from gitpane.process.process_runner import ProcessResult
+
+
+def credential_read_retry_due(result: ProcessResult, retry_count: int) -> bool:
+    """Tell whether a finished step must be started again: it failed on the credential manager's own words and has retries left.
+
+    Only a command that ran to a failing end counts: a stop, a timeout or a launch that never happened is not a failed
+    secret read. ``retry_count`` is how many times this same step was already started again.
+    """
+    if result.status != ProcessStatus.FAILED or retry_count >= CREDENTIAL_READ_RETRY_LIMIT:
+        return False
+    return credential_store_read_failed(result.stderr.decode("utf-8", "replace"))
+
+
+def credential_read_retry_text(attempt: int) -> str:
+    """Return the console and ``--log`` line that announces the retry numbered ``attempt``, counted from 1."""
+    seconds = f"{CREDENTIAL_READ_RETRY_DELAY_MS / MILLISECONDS_PER_SECOND:g}"
+    return SharedText.CREDENTIAL_READ_RETRY.value.format(seconds=seconds, attempt=attempt, limit=CREDENTIAL_READ_RETRY_LIMIT)

gitpane/transport/git_refusal.py

@@ -0,0 +1,207 @@
+"""Read what Git says when a transfer fails.
+
+Git prints the server's own explanation as ``remote:`` lines, then its ``fatal:`` line. A form shows that output as Git
+wrote it, only without debug traces, with each progress line reduced to its last value and with the credentials part of
+every URL removed. The usual authentication refusals are recognised from the words of the answer, never from the name
+of a service, so a self-hosted server that explains itself the same way is read the same way.
+"""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from gitpane.config import HTTPS_PREFIX
+from gitpane.operation.diagnostic import ANSI_PATTERN, URL_USERINFO_PATTERN, terminal_text
+
+if TYPE_CHECKING:
+    from gitpane.operation.diagnostic import PreparedDiagnostic
+
+
+class RefusalKind(Enum):
+    """Say why a server refused to let Git in."""
+
+    PASSWORD_NOT_ACCEPTED = "password_not_accepted"
+    CREDENTIALS_REFUSED = "credentials_refused"
+    CREDENTIALS_MISSING = "credentials_missing"
+
+
+REMOTE_LINE_PREFIX = "remote:"
+# Git, curl (through GIT_TRACE_CURL) and Git Credential Manager all start their trace records with the time of day.
+TRACE_TIME_PATTERN_TEXT = r"\d{2}:\d{2}:\d{2}\.\d{6} "
+TRACE_RECORD_PATTERN = re.compile("^" + TRACE_TIME_PATTERN_TEXT)
+# A local remote runs the server side of a Push on this machine with the trace settings it inherits from the pushing Git,
+# and Git sends what that side writes back to the client after "remote:", so its trace records arrive with that prefix.
+REMOTE_TRACE_RECORD_PATTERN = re.compile("^" + re.escape(REMOTE_LINE_PREFIX) + r"\s+" + TRACE_TIME_PATTERN_TEXT)
+# curl's header, data and information markers, for a trace line that reaches the output without its time of day.
+CURL_TRACE_PATTERN = re.compile(r"^(?:=> Send|<= Recv|== Info)\b")
+# Git Credential Manager writes the .NET stack of an exception on its standard error, which Git passes on unchanged: one
+# indented "at <method>" line per frame, and "--- End of ... stack trace ..." separators between the parts.
+STACK_TRACE_LINE_PATTERN = re.compile(r"^\s+at \S|^\s*--- End of .*stack trace")
+# Git could not ask anyone for a username or a password: no account answered and prompts are disabled. Older Git says it
+# could not read them, Git with credential.interactive=false says it could not get the password, and Git Credential
+# Manager says it may not prompt.
+CREDENTIALS_MISSING_PATTERN = re.compile(
+    r"could not read (?:Username|Password)\b"
+    r"|unable to get password from user"
+    r"|Cannot prompt because user interactivity has been disabled",
+    re.IGNORECASE,
+)
+# Git Credential Manager's words when the system's credential store cannot be reached or stays locked: no desktop
+# session, no session bus, a keyring nobody unlocked, or an unlock the user cancelled. Such a message never proves that
+# a secret is missing; the store simply did not answer.
+CREDENTIAL_STORE_UNAVAILABLE_PATTERN = re.compile(r"secret\s?service|d-?bus|keyring|unlock", re.IGNORECASE)
+# Git Credential Manager's words when it could not read back a secret it keeps, although the store answered: seen now and
+# then right after it stored that secret, while the reads before and after succeed. It fails on its "get", before Git
+# sends any authenticated request, so nothing reached the server. It is neither a refusal of the server nor a locked or
+# unreachable store, and the same step usually succeeds a moment later.
+CREDENTIAL_STORE_READ_FAILURE_PATTERN = re.compile(r"Received invalid secret from the secret storage|Failed to load the secret", re.IGNORECASE)
+# A server line saying plainly that account passwords are refused for Git. "password" must be followed in the same
+# sentence by the refusal word, so a message that only mentions a password among other causes does not match.
+PASSWORD_NOT_ACCEPTED_PATTERN = re.compile(
+    r"password[^.!?\n]*\b(?:removed|not available|not supported|no longer|not accepted|disabled)\b"
+    r"|stopped supporting[^.!?\n]*password"
+    r"|must use a personal access token",
+    re.IGNORECASE,
+)
+CREDENTIALS_REFUSED_PATTERN = re.compile(r"Authentication failed for|returned error: 401\b", re.IGNORECASE)
+# Git's own line when the server answers that the repository does not exist: a private repository hidden from the
+# account used gets the same answer. It is not an authentication refusal, so it is kept apart from refusal_kind.
+REPOSITORY_NOT_FOUND_PATTERN = re.compile(r"^fatal: repository '[^']*' not found$")
+# Git's own line when protocol.file.allow refuses the file transport to a clone Git starts by itself, such as the clone
+# of a submodule whose URL is a local folder or a file:// URL. Only a whole line counts, so a server cannot fake it inside
+# another sentence.
+FILE_TRANSPORT_REFUSED_PATTERN = re.compile(r"^fatal: transport 'file' not allowed$", re.MULTILINE)
+# The form shows only the end of a long output: the refusal and the fatal line are always last.
+GIT_MESSAGE_LINE_LIMIT = 20
+EARLIER_OUTPUT_TEXT = "… earlier lines are in Git's full output."
+# The URL Git quotes in its own refusal line. A submodule initialization keeps no URL of its own, so the notice reads the
+# address from there.
+REFUSED_URL_PATTERN = re.compile(r"(?:Authentication failed for|could not read (?:Username|Password) for) '(?P<url>[^']+)'"
+                                 r"|unable to access '(?P<status_url>[^']+)': The requested URL returned error: 401\b", re.IGNORECASE)
+
+
+def is_trace_line(line: str) -> bool:
+    """Tell whether a line is a debug trace record or a .NET stack line rather than something Git says to the user.
+
+    The forms and the operation consoles both use it, so a line left out of one is left out of the other.
+    """
+    return bool(TRACE_RECORD_PATTERN.match(line) or REMOTE_TRACE_RECORD_PATTERN.match(line) or CURL_TRACE_PATTERN.match(line)
+                or STACK_TRACE_LINE_PATTERN.match(line))
+
+
+def git_output_lines(stderr_text: str) -> list[str]:
+    """Return every line of Git's standard error worth showing, in order.
+
+    Trace records and stack lines are dropped, each progress line keeps its last value, terminal colour and control
+    sequences are removed as a terminal would not show them, the credentials part of any URL is removed (including a
+    part already replaced by a mask) and blank lines around the output are dropped.
+    """
+    lines: list[str] = []
+    for line in terminal_text(ANSI_PATTERN.sub("", stderr_text)).split("\n"):
+        if is_trace_line(line):
+            continue
+        lines.append(URL_USERINFO_PATTERN.sub(r"\1", line.rstrip()))
+    while lines and not lines[-1]:
+        lines.pop()
+    first_index = 0
+    while first_index < len(lines) and not lines[first_index]:
+        first_index += 1
+    return lines[first_index:]
+
+
+def git_message_text(stderr_text: str) -> str:
+    """Return Git's standard error as a form shows it: readable, without secrets, and short enough to fit.
+
+    Only the last lines are kept, where Git puts the server's refusal and its own fatal line; a first line then says
+    that the beginning is in Git's full output. Dropped trace and stack lines are never counted as cut lines.
+    """
+    lines = git_output_lines(stderr_text)
+    if len(lines) <= GIT_MESSAGE_LINE_LIMIT:
+        return "\n".join(lines)
+    return "\n".join([EARLIER_OUTPUT_TEXT, *lines[-GIT_MESSAGE_LINE_LIMIT:]])
+
+
+def credential_store_unavailable(text: str) -> bool:
+    """Tell whether a credential manager's message says the system's credential store could not be reached or unlocked.
+
+    Git Credential Manager wraps its messages at about 80 columns, so line breaks and repeated spaces are merged first,
+    and words cut across two lines are still found.
+    """
+    return CREDENTIAL_STORE_UNAVAILABLE_PATTERN.search(" ".join(text.split())) is not None
+
+
+def credential_store_read_failed(stderr_text: str) -> bool:
+    """Tell whether Git's standard error says the credential manager could not read back a secret it keeps.
+
+    Only the credential manager's own words count, never "any failure": a real refusal or a wrong account must fail at
+    once, while this read failure passes by itself and calls for no decision of the user. The lines are read as a form
+    shows them, so a trace record never counts, and a server's ``remote:`` line that quotes the same words is left out.
+    Git Credential Manager wraps its messages at about 80 columns, so the remaining lines are joined first.
+    """
+    own_lines: list[str] = []
+    for line in git_output_lines(stderr_text):
+        if line.lstrip().startswith(REMOTE_LINE_PREFIX):
+            continue
+        own_lines.append(line)
+    return CREDENTIAL_STORE_READ_FAILURE_PATTERN.search(" ".join(" ".join(own_lines).split())) is not None
+
+
+def refusal_kind(text: str) -> RefusalKind | None:
+    """Recognise an authentication refusal from Git's output, or return None for any other failure.
+
+    Only the words of the answer are read. An ambiguous answer, such as one that says the password was wrong or that
+    a token may be required, is read as a plain refusal: the same text is sent for a mistyped password.
+    """
+    if CREDENTIALS_MISSING_PATTERN.search(text):
+        return RefusalKind.CREDENTIALS_MISSING
+    for line in text.split("\n"):
+        if line.lstrip().startswith(REMOTE_LINE_PREFIX) and PASSWORD_NOT_ACCEPTED_PATTERN.search(line):
+            return RefusalKind.PASSWORD_NOT_ACCEPTED
+    if CREDENTIALS_REFUSED_PATTERN.search(text):
+        return RefusalKind.CREDENTIALS_REFUSED
+    return None
+
+
+def authentication_refused(diagnostic: PreparedDiagnostic) -> bool:
+    """Tell whether a failed transfer was refused for authentication, reading Git's output as a form shows it."""
+    return refusal_kind("\n".join(git_output_lines(diagnostic.stderr))) is not None
+
+
+def repository_not_found(lines: list[str]) -> bool:
+    """Tell whether Git said the repository does not exist, reading the lines already cleaned by ``git_output_lines``.
+
+    Kept apart from ``refusal_kind`` on purpose: a missing repository is not an authentication refusal, so checking a
+    new account must not start recognising the server for it.
+    """
+    for line in lines:
+        if REPOSITORY_NOT_FOUND_PATTERN.match(line):
+            return True
+    return False
+
+
+def file_transport_refused(stderr_text: str) -> bool:
+    """Tell whether Git refused the file transport to a submodule clone, reading its whole standard error.
+
+    The console then explains the refusal in plain words, whatever kind of URL the parent was cloned from. Windows line
+    ends and the carriage returns that end Git's progress lines become plain line ends first, so the line is matched
+    whole on every system.
+    """
+    return FILE_TRANSPORT_REFUSED_PATTERN.search(stderr_text.replace("\r\n", "\n").replace("\r", "\n")) is not None
+
+
+def refused_https_url(stderr_text: str) -> str:
+    """Return the HTTPS URL Git named in its authentication refusal, without any credentials part, or an empty text.
+
+    The lines are read as a form shows them, so a username or a secret written in the URL is already gone. A refusal
+    quoting another kind of URL (plain HTTP, SSH, a local path) gives nothing, since no account applies there.
+    """
+    for line in git_output_lines(stderr_text):
+        match = REFUSED_URL_PATTERN.search(line)
+        if match is None:
+            continue
+        url = match.group("url") or match.group("status_url")
+        if url.lower().startswith(HTTPS_PREFIX):
+            return url
+    return ""

gitpane/transport/push_tracking.py

@@ -0,0 +1,121 @@
+"""Decide whether a pushed branch is linked to its remote branch.
+
+A Push asks whether to link the branch only when Git would not already follow a remote branch for it, and the answer
+the user keeps for a repository is saved in the preferences file, never in the repository's Git configuration.
+"""
+
+from __future__ import annotations
+
+import json
+from enum import Enum
+from typing import TYPE_CHECKING, Self
+
+from gitpane.config import LOCAL_PREFIX, PUSH_TRACKING_PREFERENCE_KEY, SharedText
+from gitpane.system.path_identity import canonical_path
+from gitpane.transport.remote_config import MERGE_TRACKING_FIELD, remote_tracking_ref, tracking_values
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from gitpane.preference.preference_store import PreferenceStore
+    from gitpane.transport.remote_config import RemoteSnapshot
+
+
+class PushTrackingChoice(Enum):
+    """What a Push does about linking a branch that follows no remote branch: ask each time, always link, or never link.
+
+    The value is the word saved in the preferences file, which every system and older GitPane versions read; the label
+    is the text Settings shows. ``ASK`` is never written: it is the absence of an entry for the repository, so going
+    back to it removes the entry.
+    """
+
+    ASK = ("ask", "Ask")
+    ALWAYS_ADD = ("always-add", "Always add")
+    NEVER_ADD = ("never-add", "Never add")
+
+    def __new__(cls, value: str, label: str) -> Self:
+        """Keep the saved word as the value and the Settings text beside it."""
+        member = object.__new__(cls)
+        member._value_ = value
+        member.label = label
+        return member
+
+
+def tracking_question_applies(snapshot: RemoteSnapshot, remote_name: str, source_ref: str, destination_ref: str, tag_refs: Sequence[tuple[str, str]]) -> bool:
+    """Tell whether a push of ``source_ref`` to ``destination_ref`` on ``remote_name`` may link the branch to its remote branch.
+
+    Only a local branch pushed alone to an active configured remote qualifies, and only when it has no
+    ``branch.<name>.merge`` at all: a branch whose upstream is gone, one that follows a local branch (remote ".") and one
+    whose setting comes from a global file already have an upstream that Git uses. A push to a typed address has no
+    remote name, and Git does not know an inactive remote as a remote, so neither can be linked. A destination that no
+    Fetch refspec of the remote maps to a remote-tracking branch (a push-only remote, a mirror, a narrowed refspec)
+    cannot be linked either, since Git only links a branch to a remote-tracking branch: asking would only end on a link
+    that is not set, at every Push of that branch.
+    """
+    if not remote_name or tag_refs or not source_ref.startswith(LOCAL_PREFIX):
+        return False
+    entry = snapshot.entry_by_name.get(remote_name)
+    if entry is None or not entry.active:
+        return False
+    if not remote_tracking_ref(snapshot, remote_name, destination_ref):
+        return False
+    return not tracking_values(snapshot, source_ref, MERGE_TRACKING_FIELD)
+
+
+def push_tracking_entry_by_repository(value: object) -> dict[str, object]:
+    """Read the saved JSON object mapping a repository's shared Git folder to its kept entry, each entry as stored.
+
+    This version writes a word per repository. A word it does not know, or an entry of another shape (a number, an
+    object a later GitPane may write), is kept as it is and only reads as no choice: refusing it would make the whole
+    key unreadable and block every later "Don't ask again" and Settings save. Only a value that is not a JSON object is
+    refused, TypeError when it is JSON of another shape and ValueError when it is not JSON at all, with a text that
+    names the key, since only removing it from the preferences file brings the choices back.
+    """
+    if not isinstance(value, str):
+        raise TypeError(SharedText.PUSH_TRACKING_UNREADABLE.value)
+    try:
+        entry_by_repository = json.loads(value)
+    except ValueError as error:
+        raise ValueError(SharedText.PUSH_TRACKING_UNREADABLE.value) from error
+    if not isinstance(entry_by_repository, dict):
+        raise TypeError(SharedText.PUSH_TRACKING_UNREADABLE.value)
+    return entry_by_repository
+
+
+def validate_push_tracking_json(value: object) -> str:
+    """Accept any JSON object keyed by repository, whatever its entries hold, and keep its text as saved."""
+    push_tracking_entry_by_repository(value)
+    return value
+
+
+def push_tracking_choice(preference: PreferenceStore, common_git_dir: str) -> PushTrackingChoice:
+    """Return the choice kept for the repository whose shared Git folder is ``common_git_dir``, or ``ASK`` when none is kept.
+
+    Linked worktrees share that folder, so they share the choice. A word this version does not know, and an entry that
+    is not a word, read as ``ASK``.
+    """
+    entry_by_repository = push_tracking_entry_by_repository(preference.read(PUSH_TRACKING_PREFERENCE_KEY))
+    word = entry_by_repository.get(canonical_path(common_git_dir))
+    if not isinstance(word, str):
+        return PushTrackingChoice.ASK
+    try:
+        return PushTrackingChoice(word)
+    except ValueError:
+        return PushTrackingChoice.ASK
+
+
+def save_push_tracking_choice(preference: PreferenceStore, common_git_dir: str, choice: PushTrackingChoice) -> None:
+    """Keep ``choice`` for the repository whose shared Git folder is ``common_git_dir``, leaving every other entry as it is.
+
+    The write starts from the value stored right now, never from the copy in memory: another GitPane open at the same
+    time may have kept the choice of another repository meanwhile. The entries of other repositories are written back
+    exactly as stored, whatever they hold. ``ASK`` removes the entry. OSError, ValueError and TypeError are left to the
+    caller, and nothing is written then.
+    """
+    entry_by_repository = push_tracking_entry_by_repository(preference.read_saved(PUSH_TRACKING_PREFERENCE_KEY))
+    repository_key = canonical_path(common_git_dir)
+    if choice == PushTrackingChoice.ASK:
+        entry_by_repository.pop(repository_key, None)
+    else:
+        entry_by_repository[repository_key] = choice.value
+    preference.update({PUSH_TRACKING_PREFERENCE_KEY: json.dumps(entry_by_repository, ensure_ascii=False)})

gitpane/transport/refusal_notice.py

@@ -0,0 +1,225 @@
+"""Say a transfer refusal of Git in plain words.
+
+A failed transfer starts with one factual sentence naming the address and the account used, when one applies, and a
+refusal that needs an account is described for the Accounts page without any secret.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from gitpane.transport.git_refusal import REMOTE_LINE_PREFIX, credential_store_unavailable, git_message_text, git_output_lines, refusal_kind, repository_not_found
+
+if TYPE_CHECKING:
+    from gitpane.operation.diagnostic import PreparedDiagnostic
+    from gitpane.transport.branch_exchange import ServerRefusal
+
+
+@dataclass(frozen=True)
+class TransferAccount:
+    """Say which address a transfer contacted and with which account, so a failure can name both without any secret.
+
+    ``address`` is the host and port only, without scheme or path; an empty ``label`` means no account was used.
+    ``needs_reconnect`` says a check of the system credential store found that account's secret gone.
+    """
+
+    address: str
+    label: str = ""
+    needs_reconnect: bool = False
+
+
+@dataclass(frozen=True)
+class AccountNotice:
+    """Say which remote needs an account, at which address, and which account it was refused with, without any secret.
+
+    ``subject`` names what was contacted (a remote name, a submodule, the repository to clone); ``address`` is the host
+    and port only; an empty ``account_label`` means no account was used. It only describes the refusal: the caller
+    decides where to show it.
+    """
+
+    subject: str
+    address: str
+    account_label: str = ""
+
+
+# GitPane's own explanation, shown once after Git's lines: Git decides, the user changes the setting if they want to.
+FILE_TRANSPORT_REFUSED_TEXT = ("Git's protocol.file.allow setting does not allow cloning submodules from local folders or file:// URLs, so the submodule"
+                               " clone was refused. Change this Git setting if you want to allow it.")
+NO_GIT_MESSAGE_TEXT = "Git gave no other explanation."
+# Cause shown under a failed Fetch, Push or clone when the server refused and no account is connected for its address.
+NO_CONNECTED_ACCOUNT_NOTICE_TEXT = "No account is connected for {address}. Click Add account… to add one."
+# GitPane's own refusal to start an HTTPS Fetch or Push when no account is chosen for its address: Git never runs, so
+# this cause is the only sign that the transfer failed for lack of an account.
+NO_ACCOUNT_CONFIGURED_TEXT = "No account configured. Choose an account in Settings before continuing."
+AUTHENTICATION_FAILED_TEXT = "Authentication failed for {address} with account {account}. Reconnect it in Settings › Accounts."
+# Added under that sentence once a check confirmed the account's secret is gone: Git and Git Credential Manager erase a
+# secret by themselves when the server refuses it.
+NEEDS_RECONNECT_TEXT = "{account}: Needs reconnect. Its saved sign-in is no longer in the system credential store."
+REPOSITORY_HIDDEN_TEXT = "The account used ({account}) cannot see this repository. Check the URL, or choose another account."
+# The orange notice shown at the top of Settings › Accounts after a refusal; the address part is left out when unknown.
+ACCOUNT_NOTICE_MISSING_TEXT = "{subject}{address_part} needs an account. Add one with Add account…"
+ACCOUNT_NOTICE_REFUSED_TEXT = "{subject}{address_part} refused account {account}. Select it in Connected accounts and click Reconnect."
+ACCOUNT_NOTICE_ADDRESS_TEXT = " ({address})"
+SUBMODULE_NOTICE_SUBJECT_TEXT = "Submodule {path}"
+# A clone has no remote name yet, so the notice names what the user typed the address for.
+CLONE_NOTICE_SUBJECT_TEXT = "The repository to clone"
+# The first sentence of a Push the server itself refused (a hook, for instance), naming every refused branch or tag.
+SERVER_REFUSAL_TEXT = "The server refused the push of {names}."
+SERVER_REFUSAL_NAME_SEPARATOR = ", "
+SERVER_REFUSAL_REASON_TEXT = "({reason})"
+# A progress line the server sends during a Push ("Resolving deltas: 100% (3/3), done."): it says nothing about a refusal.
+PROGRESS_LINE_PATTERN = re.compile(r"^[A-Za-z][A-Za-z ]*:\s+\d+% \(\d+/\d+\)")
+
+
+def _own_cause_text(cause: str, stderr_text: str) -> str:
+    """Return the part of a failure cause that is not Git's standard error itself.
+
+    A process that fails without its own explanation takes its whole standard error as cause, sometimes after a sentence
+    of GitPane's (a preserved partial clone). A cause that does not end like the standard error (a timeout, a modified
+    folder) is entirely GitPane's own and is returned whole.
+    """
+    cause_lines = cause.strip().split("\n")
+    stderr_lines: list[str] = []
+    for line in stderr_text.strip().split("\n"):
+        stderr_lines.append(line.rstrip())
+    if not stderr_lines or cause_lines[-1].rstrip() != stderr_lines[-1]:
+        return cause.strip()
+    own_lines: list[str] = []
+    for line in cause_lines:
+        if line.rstrip() == stderr_lines[0]:
+            break
+        own_lines.append(line)
+    return "\n".join(own_lines).strip()
+
+
+def failure_headline(diagnostic: PreparedDiagnostic, account: TransferAccount | None) -> str:
+    """Return the one factual sentence that explains a failed transfer, or an empty text when none applies.
+
+    Without a known address (an SSH or local transfer) nothing is said. An authentication refusal names the account
+    that was used and points to Reconnect; without an account it says none is connected and how to add one. The
+    sentence never guesses a cause from the server's advice, since the same words come back for a revoked token. A
+    repository reported missing after an account was used may just be hidden from that account, so the account is
+    named; without an account Git's own line already says the repository does not exist. When the account's secret is
+    known to be gone, a second line says so right under the refusal sentence. A credential store that could not be
+    reached gets no sentence: the credential manager's own message says it.
+    """
+    if account is None:
+        return ""
+    lines = git_output_lines(diagnostic.stderr)
+    git_output = "\n".join(lines)
+    # The credential manager's own message, already in the console, says the system's credential store did not answer;
+    # the account's secret may well be intact, so no account is named as refused and no reconnect is suggested.
+    if credential_store_unavailable(git_output):
+        return ""
+    if refusal_kind(git_output) is not None:
+        if not account.label:
+            return NO_CONNECTED_ACCOUNT_NOTICE_TEXT.format(address=account.address)
+        headline = AUTHENTICATION_FAILED_TEXT.format(address=account.address, account=account.label)
+        if account.needs_reconnect:
+            headline += "\n" + NEEDS_RECONNECT_TEXT.format(account=account.label)
+        return headline
+    if account.label and repository_not_found(lines):
+        return REPOSITORY_HIDDEN_TEXT.format(account=account.label)
+    return ""
+
+
+def is_no_account_refusal(text: str) -> bool:
+    """Tell whether a shown text holds, as one whole line, GitPane's refusal to start an HTTPS transfer without an account.
+
+    Every window recognises the refusal here instead of copying its sentence; the sentence only counts as a whole line,
+    so a server or Git line that merely quotes it is not taken for it.
+    """
+    return NO_ACCOUNT_CONFIGURED_TEXT in text.split("\n")
+
+
+def account_notice(diagnostic: PreparedDiagnostic, account: TransferAccount | None, subject: str) -> AccountNotice | None:
+    """Describe the account a refused HTTPS transfer needs, or return None when the failure is not about an account.
+
+    A transfer GitPane refused to start because no account is chosen for its address counts as a refusal too. Without
+    an address (an SSH or local transfer) or without an authentication refusal (a missing repository, a refused
+    connection), nothing is asked of the user, so Settings is left alone; a credential store that could not be reached
+    says nothing about the account either.
+    """
+    if account is None:
+        return None
+    if not account.label and is_no_account_refusal(diagnostic.cause):
+        return AccountNotice(subject, account.address)
+    git_output = "\n".join(git_output_lines(diagnostic.stderr))
+    if credential_store_unavailable(git_output) or refusal_kind(git_output) is None:
+        return None
+    return AccountNotice(subject, account.address, account.label)
+
+
+def account_notice_text(notice: AccountNotice) -> str:
+    """Say who needs an account and where, or which account was refused, in the words shown on the Accounts page."""
+    address_part = ACCOUNT_NOTICE_ADDRESS_TEXT.format(address=notice.address) if notice.address else ""
+    if notice.account_label:
+        return ACCOUNT_NOTICE_REFUSED_TEXT.format(subject=notice.subject, address_part=address_part, account=notice.account_label)
+    return ACCOUNT_NOTICE_MISSING_TEXT.format(subject=notice.subject, address_part=address_part)
+
+
+def server_refusal_headline(refusals: tuple[ServerRefusal, ...], stderr_text: str) -> str:
+    """Say in a few lines which references the server refused and why, or return an empty text when it refused none.
+
+    The sentence names every refused branch or tag, then come the server's own lines without their "remote:" prefix
+    (trace records and progress left out), then Git's reasons in parentheses, each said once. ``stderr_text`` is Git's
+    standard error as already filtered for secrets, so a window can show these lines as they are.
+    """
+    if not refusals:
+        return ""
+    names: list[str] = []
+    reasons: list[str] = []
+    for refusal in refusals:
+        names.append(refusal.short_name())
+        if refusal.reason and refusal.reason not in reasons:
+            reasons.append(refusal.reason)
+    lines = [SERVER_REFUSAL_TEXT.format(names=SERVER_REFUSAL_NAME_SEPARATOR.join(names))]
+    for line in git_output_lines(stderr_text):
+        if not line.startswith(REMOTE_LINE_PREFIX):
+            continue
+        message = line.removeprefix(REMOTE_LINE_PREFIX).strip()
+        if message and not PROGRESS_LINE_PATTERN.match(message):
+            lines.append(message)
+    for reason in reasons:
+        lines.append(SERVER_REFUSAL_REASON_TEXT.format(reason=reason))
+    return "\n".join(lines)
+
+
+def headline_first(headline: str, text: str) -> str:
+    """Put a failure headline above the rest of a summary, leaving out whichever part is empty.
+
+    A window that filters what it shows filters the rest on its own and keeps the headline out of the filter: the
+    headline holds only an address and an account label, or the server's lines already filtered with the rest of Git's
+    output, and a filter that has learned the Git username from a URL would otherwise hide the account it names.
+    """
+    parts: list[str] = []
+    for part in (headline, text):
+        if part:
+            parts.append(part)
+    return "\n".join(parts)
+
+
+def failure_summary(diagnostic: PreparedDiagnostic, account: TransferAccount | None = None) -> str:
+    """Return what a form shows for a failed Git transfer: its own cause, the factual headline, then Git's output.
+
+    ``account`` is the address and account the transfer used, so the headline can name them; None when the transfer
+    was not an HTTPS one. Without any standard error the cause is all there is to say. The complete, filtered detail
+    stays available to the user through the details view.
+    """
+    if not diagnostic.stderr.strip():
+        return diagnostic.cause
+    parts: list[str] = []
+    own_cause = _own_cause_text(diagnostic.cause, diagnostic.stderr)
+    if own_cause:
+        parts.append(own_cause)
+    headline = failure_headline(diagnostic, account)
+    if headline:
+        parts.append(headline)
+    message = git_message_text(diagnostic.stderr)
+    if message:
+        parts.append(message)
+    elif not own_cause:
+        parts.append(NO_GIT_MESSAGE_TEXT)
+    return "\n".join(parts)