Repository: Textualize/textual
Pull request: Add a post-run warning hook to `textual run`
Implements #1944 and in doing so adds a place to add more checks and warnings to a list. The idea here being that if a user is using `textual run`, on exit, problematic environments can be tested for and warnings displayed.

Right now the only warning added is for using `terminal.app` under macOS.

This also adds a new entry to the FAQ explaining how `terminal.app` isn't good for Textual.

Problem statement:
Warn users about macOS Terminal
I'm thinking we might detect macOS terminal when running `textual run` and direct them to a better terminal, like iTerm.

Otherwise, I suspect many people wouldn't realise it could look a lot better.

On exit from `textual run`, we should print out a short message which a link to our site somewhere. Suggest adding a FAQ entry.

Hints from issue discussion:

Commit message: Rebuild the FAQ

Patch to review:
diff --git a/FAQ.md b/FAQ.md
index 239d53570c..29265366d9 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -7,6 +7,7 @@
 - [How can I select and copy text in a Textual app?](#how-can-i-select-and-copy-text-in-a-textual-app)
 - [How do I center a widget in a screen?](#how-do-i-center-a-widget-in-a-screen)
 - [How do I pass arguments to an app?](#how-do-i-pass-arguments-to-an-app)
+- [Why doesn't Textual look good on macOS?](#why-doesn't-textual-look-good-on-macos)
 - [Why doesn't Textual support ANSI themes?](#why-doesn't-textual-support-ansi-themes)
 
 <a name="does-textual-support-images"></a>
@@ -104,6 +105,16 @@ Greetings(to_greet="davep").run()
 Greetings("Well hello", "there").run()
 ```
 
+<a name="why-doesn't-textual-look-good-on-macos"></a>
+## Why doesn't Textual look good on macOS?
+
+The default macOS `Terminal.app` is getting rather old now; it has problems
+such as being limited to just 256 colors, being slow to draw and not all
+box-drawing characters are fully-supported. We recommend installing a newer
+terminal such as [iTerm2](https://iterm2.com/),
+[Kitty](https://sw.kovidgoyal.net/kitty/) or
+[WezTerm](https://wezfurlong.org/wezterm/).
+
 <a name="why-doesn't-textual-support-ansi-themes"></a>
 ## Why doesn't Textual support ANSI themes?
 
diff --git a/questions/why-looks-bad-on-macos.question.md b/questions/why-looks-bad-on-macos.question.md
new file mode 100644
index 0000000000..9808a3c0ee
--- /dev/null
+++ b/questions/why-looks-bad-on-macos.question.md
@@ -0,0 +1,18 @@
+---
+title: "Why doesn't Textual look good on macOS?"
+alt_titles:
+  - "looks bad on macOS"
+  - "dashed lines on macOS"
+  - "broken borders on macOS"
+  - "pale colors on macOS"
+  - "pale colours on macOS"
+  - "mac terminal"
+  - "macOS terminal"
+---
+
+The default macOS `Terminal.app` is getting rather old now; it has problems
+such as being limited to just 256 colors, being slow to draw and not all
+box-drawing characters are fully-supported. We recommend installing a newer
+terminal such as [iTerm2](https://iterm2.com/),
+[Kitty](https://sw.kovidgoyal.net/kitty/) or
+[WezTerm](https://wezfurlong.org/wezterm/).
diff --git a/src/textual/cli/cli.py b/src/textual/cli/cli.py
index 16ca139cbf..a2c8a5849d 100644
--- a/src/textual/cli/cli.py
+++ b/src/textual/cli/cli.py
@@ -38,6 +38,38 @@ def console(verbose: bool, exclude: list[str]) -> None:
         console.show_cursor(True)
 
 
+def _post_run_warnings() -> None:
+    """Look for and report any issues with the environment.
+
+    This is the right place to add code that looks at the terminal, or other
+    environmental issues, and if a problem is seen it should be printed so
+    the developer can see it easily.
+    """
+    import os
+    import platform
+
+    from rich.console import Console
+    from rich.panel import Panel
+
+    console = Console()
+
+    # Add any test/warning pair here. The list contains a tuple where the
+    # first item is `True` if a problem situation is detected, and the
+    # second item is a message to show the user on exit from `textual run`.
+    warnings = [
+        (
+            platform.system() == "Darwin"
+            and os.environ.get("TERM_PROGRAM") == "Apple_Terminal",
+            "The default terminal app on macOS is limited to 256 colors. See our FAQ for more details:\n\n"
+            "https://github.com/Textualize/textual/blob/main/FAQ.md#why-doesn't-textual-look-good-on-macos",
+        )
+    ]
+
+    for concering, concern in warnings:
+        if concering:
+            console.print(Panel.fit(f"⚠️ [bold green] {concern}[/]", style="cyan"))
+
+
 @run.command(
     "run",
     context_settings={
@@ -119,6 +151,8 @@ async def run_press_keys(pilot: Pilot) -> None:
         console.print("[b]The app returned:")
         console.print(Pretty(result))
 
+    _post_run_warnings()
+
 
 @run.command("borders")
 def borders():


Code review comments:
diff_hunk: @@ -38,6 +38,38 @@ def console(verbose: bool, exclude: list[str]) -> None:
         console.show_cursor(True)
 
 
+def _post_run_warnings() -> None:
+    """Look for and report any issues with the environment.
+
+    This is the right place to add code that looks at the terminal, or other
+    environmental issues, and if a problem is seen it should be printed so
+    the developer can see it easily.
+    """
+    import os
+    import platform
+
+    from rich.console import Console
+    from rich.panel import Panel
+
+    console = Console()
+
+    # Add any test/warning pair here. The list contains a tuple where the
+    # first item is `True` if a problem situation is detected, and the
+    # second item is a message to show the user on exit from `textual run`.
+    warnings = [
+        (
+            platform.system() == "Darwin"
+            and os.environ.get("TERM_PROGRAM") == "Apple_Terminal",
+            "The default terminal app on macOS is limited to 256 colors. See our FAQ for more details:\n\n"
+            "https://github.com/Textualize/textual/blob/main/FAQ.md#why-doesn't-textual-look-good-on-macos",
+        )
+    ]
+
+    for concering, concern in warnings:
path: src/textual/cli/cli.py
text: @user1:
typo

@author:
Excellent spot!