feat(logging[extra]): add structured log calls with extra context across all modules

why: Structured `extra` keys (tmux_session, tmux_window, tmux_pane,
tmux_config_path) enable filtering, aggregation, and test assertions
on log records rather than string matching.
what:
- Add structured DEBUG/INFO/WARNING/ERROR log calls to workspace, CLI,
  and utility modules with appropriate extra keys
- Route all raw print() calls through tmuxp_echo() in CLI commands
- Fix get_pane() exception catch type to match sibling methods
- Change before_script failure log from DEBUG to ERROR
- Remove catch-log-reraise in plugin version check

Author: tony

src/tmuxp/_internal/config_reader.py

@@ -3,11 +3,14 @@
 from __future__ import annotations
 
 import json
+import logging
 import pathlib
 import typing as t
 
 import yaml
 
+logger = logging.getLogger(__name__)
+
 if t.TYPE_CHECKING:
     from typing import TypeAlias
 
@@ -106,6 +109,7 @@ def _from_file(cls, path: pathlib.Path) -> dict[str, t.Any]:
         {'session_name': 'my session'}
         """
         assert isinstance(path, pathlib.Path)
+        logger.debug("loading config", extra={"tmux_config_path": str(path)})
         content = path.open(encoding="utf-8").read()
 
         if path.suffix in {".yaml", ".yml"}:

src/tmuxp/cli/convert.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import locale
+import logging
 import os
 import pathlib
 import typing as t
@@ -13,7 +14,9 @@
 from tmuxp.workspace.finders import find_workspace_file, get_workspace_dir
 
 from ._colors import Colors, build_description, get_color_mode
-from .utils import prompt_yes_no
+from .utils import prompt_yes_no, tmuxp_echo
+
+logger = logging.getLogger(__name__)
 
 CONVERT_DESCRIPTION = build_description(
     """
@@ -130,7 +133,7 @@ def command_convert(
             new_workspace,
             encoding=locale.getpreferredencoding(False),
         )
-        print(  # NOQA: T201 RUF100
+        tmuxp_echo(
             colors.success("New workspace file saved to ")
             + colors.info(str(PrivatePath(newfile)))
             + ".",

src/tmuxp/cli/edit.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 import os
 import subprocess
 import typing as t
@@ -10,6 +11,9 @@
 from tmuxp.workspace.finders import find_workspace_file
 
 from ._colors import Colors, build_description, get_color_mode
+from .utils import tmuxp_echo
+
+logger = logging.getLogger(__name__)
 
 EDIT_DESCRIPTION = build_description(
     """
@@ -59,7 +63,7 @@ def command_edit(
     workspace_file = find_workspace_file(workspace_file)
 
     sys_editor = os.environ.get("EDITOR", "vim")
-    print(  # NOQA: T201 RUF100
+    tmuxp_echo(
         colors.muted("Opening ")
         + colors.info(str(PrivatePath(workspace_file)))
         + colors.muted(" in ")

src/tmuxp/cli/freeze.py

@@ -4,6 +4,7 @@
 
 import argparse
 import locale
+import logging
 import os
 import pathlib
 import sys
@@ -19,7 +20,9 @@
 from tmuxp.workspace.finders import get_workspace_dir
 
 from ._colors import Colors, build_description, get_color_mode
-from .utils import prompt, prompt_choices, prompt_yes_no
+from .utils import prompt, prompt_choices, prompt_yes_no, tmuxp_echo
+
+logger = logging.getLogger(__name__)
 
 FREEZE_DESCRIPTION = build_description(
     """
@@ -141,15 +144,15 @@ def command_freeze(
         if not session:
             raise exc.SessionNotFound
     except TmuxpException as e:
-        print(colors.error(str(e)))  # NOQA: T201 RUF100
+        tmuxp_echo(colors.error(str(e)))
         return
 
     frozen_workspace = freezer.freeze(session)
     workspace = freezer.inline(frozen_workspace)
     configparser = ConfigReader(workspace)
 
     if not args.quiet:
-        print(  # NOQA: T201 RUF100
+        tmuxp_echo(
             colors.format_separator(63)
             + "\n"
             + colors.muted("Freeze does its best to snapshot live tmux sessions.")
@@ -163,7 +166,7 @@ def command_freeze(
         )
     ):
         if not args.quiet:
-            print(  # NOQA: T201 RUF100
+            tmuxp_echo(
                 colors.muted("tmuxp has examples in JSON and YAML format at ")
                 + colors.info("<http://tmuxp.git-pull.com/examples.html>")
                 + "\n"
@@ -190,7 +193,7 @@ def command_freeze(
             color_mode=color_mode,
         )
         if not args.force and os.path.exists(dest_prompt):
-            print(  # NOQA: T201 RUF100
+            tmuxp_echo(
                 colors.warning(f"{PrivatePath(dest_prompt)} exists.")
                 + " "
                 + colors.muted("Pick a new filename."),
@@ -252,8 +255,9 @@ def extract_workspace_format(
             workspace,
             encoding=locale.getpreferredencoding(False),
         )
+        logger.info("workspace saved", extra={"tmux_config_path": str(dest)})
 
         if not args.quiet:
-            print(  # NOQA: T201 RUF100
+            tmuxp_echo(
                 colors.success("Saved to ") + colors.info(str(PrivatePath(dest))) + ".",
             )

src/tmuxp/cli/import_config.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import locale
+import logging
 import os
 import pathlib
 import sys
@@ -16,6 +17,8 @@
 from ._colors import ColorMode, Colors, build_description, get_color_mode
 from .utils import prompt, prompt_choices, prompt_yes_no, tmuxp_echo
 
+logger = logging.getLogger(__name__)
+
 IMPORT_DESCRIPTION = build_description(
     """
     Import workspaces from teamocil and tmuxinator configuration files.
@@ -220,6 +223,10 @@ def import_config(
             encoding=locale.getpreferredencoding(False),
         )
 
+        logger.info(
+            "workspace saved",
+            extra={"tmux_config_path": str(dest)},
+        )
         tmuxp_echo(
             colors.success("Saved to ") + colors.info(str(PrivatePath(dest))) + ".",
         )

src/tmuxp/cli/load.py

@@ -123,6 +123,7 @@ def load_plugins(
                 module_name = ".".join(module_name[:-1])
                 plugin_name = plugin.split(".")[-1]
             except AttributeError as error:
+                logger.exception("plugin load failed")
                 tmuxp_echo(
                     colors.error("[Plugin Error]")
                     + f" Couldn't load {plugin}\n"
@@ -139,12 +140,16 @@ def load_plugins(
                     default=True,
                     color_mode=colors.mode,
                 ):
+                    logger.warning(
+                        "plugin version constraint not met, user declined skip",
+                    )
                     tmuxp_echo(
                         colors.warning("[Not Skipping]")
                         + " Plugin versions constraint not met. Exiting...",
                     )
                     sys.exit(1)
             except (ImportError, AttributeError) as error:
+                logger.exception("plugin import failed")
                 tmuxp_echo(
                     colors.error("[Plugin Error]")
                     + f" Couldn't load {plugin}\n"
@@ -178,7 +183,8 @@ def _reattach(builder: WorkspaceBuilder, colors: Colors | None = None) -> None:
         plugin.reattach(builder.session)
         proc = builder.session.cmd("display-message", "-p", "'#S'")
         for line in proc.stdout:
-            print(colors.info(line) if colors else line)  # NOQA: T201 RUF100
+            tmuxp_echo(colors.info(line) if colors else line)
+            logger.debug("reattach display-message output: %s", line.strip())
 
     if "TMUX" in os.environ:
         builder.session.switch_client()
@@ -225,7 +231,8 @@ def _load_detached(builder: WorkspaceBuilder, colors: Colors | None = None) -> N
     assert builder.session is not None
 
     msg = "Session created in detached state."
-    print(colors.info(msg) if colors else msg)  # NOQA: T201 RUF100
+    tmuxp_echo(colors.info(msg) if colors else msg)
+    logger.info("session created in detached state")
 
 
 def _load_append_windows_to_current_session(builder: WorkspaceBuilder) -> None:
@@ -347,10 +354,9 @@ def load_workspace(
     if isinstance(workspace_file, (str, os.PathLike)):
         workspace_file = pathlib.Path(workspace_file)
 
-    tmuxp_echo(
-        cli_colors.info("[Loading]")
-        + " "
-        + cli_colors.highlight(str(PrivatePath(workspace_file))),
+    logger.info(
+        "loading workspace",
+        extra={"tmux_config_path": str(workspace_file)},
     )
 
     # ConfigReader allows us to open a yaml or json file as a dict
@@ -378,13 +384,18 @@ def load_workspace(
 
     shutil.which("tmux")  # raise exception if tmux not found
 
-    try:  # load WorkspaceBuilder object for tmuxp workspace / tmux server
+    # WorkspaceBuilder creation — outside spinner so plugin prompts are safe
+    try:
         builder = WorkspaceBuilder(
             session_config=expanded_workspace,
             plugins=load_plugins(expanded_workspace, colors=cli_colors),
             server=t,
         )
     except exc.EmptyWorkspaceException:
+        logger.warning(
+            "workspace file is empty",
+            extra={"tmux_config_path": str(workspace_file)},
+        )
         tmuxp_echo(
             cli_colors.warning("[Warning]")
             + f" {PrivatePath(workspace_file)} is empty or parsed no workspace data",
@@ -393,7 +404,7 @@ def load_workspace(
 
     session_name = expanded_workspace["session_name"]
 
-    # if the session already exists, prompt the user to attach
+    # Session-exists check — outside spinner so prompt_yes_no is safe
     if builder.session_exists(session_name) and not append:
         if not detached and (
             answer_yes
@@ -442,9 +453,7 @@ def load_workspace(
             _load_attached(builder, detached)
 
     except exc.TmuxpException as e:
-        import traceback
-
-        tmuxp_echo(traceback.format_exc())
+        logger.exception("workspace build failed")
         tmuxp_echo(cli_colors.error("[Error]") + f" {e}")
 
         choice = prompt_choices(
@@ -459,6 +468,7 @@ def load_workspace(
             if builder.session is not None:
                 builder.session.kill()
                 tmuxp_echo(cli_colors.muted("Session killed."))
+                logger.info("session killed by user after build error")
         elif choice == "a":
             _reattach(builder, cli_colors)
         else:

src/tmuxp/cli/shell.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import argparse
+import logging
 import os
 import pathlib
 import typing as t
@@ -13,6 +14,9 @@
 from tmuxp._compat import PY3, PYMINOR
 
 from ._colors import Colors, build_description, get_color_mode
+from .utils import tmuxp_echo
+
+logger = logging.getLogger(__name__)
 
 SHELL_DESCRIPTION = build_description(
     """
@@ -222,7 +226,7 @@ def command_shell(
     ):
         from tmuxp._compat import breakpoint as tmuxp_breakpoint
 
-        print(  # NOQA: T201 RUF100
+        tmuxp_echo(
             cli_colors.muted("Launching ")
             + cli_colors.highlight("pdb", bold=False)
             + cli_colors.muted(" shell..."),
@@ -233,7 +237,7 @@ def command_shell(
         from tmuxp.shell import launch
 
         shell_name = args.shell or "best"
-        print(  # NOQA: T201 RUF100
+        tmuxp_echo(
             cli_colors.muted("Launching ")
             + cli_colors.highlight(shell_name, bold=False)
             + cli_colors.muted(" shell for session ")

src/tmuxp/cli/utils.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 import typing as t
 
 from tmuxp._internal.colors import (
@@ -15,6 +16,8 @@
 from tmuxp._internal.private_path import PrivatePath
 from tmuxp.log import tmuxp_echo
 
+logger = logging.getLogger(__name__)
+
 if t.TYPE_CHECKING:
     from collections.abc import Callable, Sequence
 
@@ -215,7 +218,7 @@ def prompt_choices(
             return None
         if rv in choices_:
             return rv
-        print(
+        tmuxp_echo(
             colors.warning(f"Invalid choice '{rv}'. ")
             + f"Please choose from: {', '.join(choices_)}"
         )

src/tmuxp/plugin.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 import typing as t
 
 import libtmux
@@ -11,6 +12,8 @@
 from .__about__ import __version__
 from .exc import TmuxpPluginException
 
+logger = logging.getLogger(__name__)
+
 #: Minimum version of tmux required to run tmuxp
 TMUX_MIN_VERSION = "3.2"
 
@@ -181,6 +184,7 @@ def __init__(self, **kwargs: Unpack[PluginConfigSchema]) -> None:
 
     def _version_check(self) -> None:
         """Check all dependency versions for compatibility."""
+        logger.debug("checking version constraints for %s", self.plugin_name)
         for dep, constraints in self.version_constraints.items():
             assert isinstance(constraints, dict)
             try:

src/tmuxp/shell.py

@@ -106,14 +106,17 @@ def has_bpython() -> bool:
 def detect_best_shell() -> CLIShellLiteral:
     """Return the best, most feature-rich shell available."""
     if has_ptipython():
-        return "ptipython"
-    if has_ptpython():
-        return "ptpython"
-    if has_ipython():
-        return "ipython"
-    if has_bpython():
-        return "bpython"
-    return "code"
+        shell: CLIShellLiteral = "ptipython"
+    elif has_ptpython():
+        shell = "ptpython"
+    elif has_ipython():
+        shell = "ipython"
+    elif has_bpython():
+        shell = "bpython"
+    else:
+        shell = "code"
+    logger.debug("detected shell: %s", shell)
+    return shell
 
 
 def get_bpython(