refactor(logging[infra]): add structured logging infrastructure to all modules

why: Enable structured logging with `extra` context for filtering, testing,
and aggregation. Library modules need NullHandler per Python best practices.
what:
- Add `logging.getLogger(__name__)` to every module
- Add NullHandler in library `__init__.py`
- Add TmuxpLoggerAdapter with process() override for Python <3.13 compat
- Simplify tmuxp_echo to pure print wrapper (decoupled from logging)
- Add setup_log_file() for centralized --log-file handler setup
- Fix setup_logger to target "tmuxp" logger, skip NullHandler check
- Change default CLI log level from INFO to WARNING
- Fix timestamp format bug: %H:%m:%S -> %H:%M:%S
- Add future annotations and fix import ordering in _compat.py

Author: tony

src/tmuxp/__about__.py

@@ -2,6 +2,10 @@
 
 from __future__ import annotations
 
+import logging
+
+logger = logging.getLogger(__name__)
+
 __title__ = "tmuxp"
 __package_name__ = "tmuxp"
 __version__ = "1.65.0"

src/tmuxp/__init__.py

@@ -6,6 +6,8 @@
 
 from __future__ import annotations
 
+import logging
+
 from . import cli, util
 from .__about__ import (
     __author__,
@@ -17,3 +19,6 @@
     __title__,
     __version__,
 )
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())

src/tmuxp/_compat.py

@@ -1,18 +1,26 @@
-# flake8: NOQA
+from __future__ import annotations
+
+import logging
 import sys
 
+logger = logging.getLogger(__name__)
+
 PY3 = sys.version_info[0] == 3
 PYMINOR = sys.version_info[1]
 PYPATCH = sys.version_info[2]
 
-_identity = lambda x: x
+
+def _identity(x: object) -> object:
+    """Return *x* unchanged — used as a no-op decorator."""
+    return x
+
 
 if PY3 and PYMINOR >= 7:
-    breakpoint = breakpoint
+    breakpoint = breakpoint  # noqa: A001
 else:
     import pdb
 
-    breakpoint = pdb.set_trace
+    breakpoint = pdb.set_trace  # noqa: A001
 
 
 implements_to_string = _identity

src/tmuxp/_internal/__init__.py

@@ -1 +1,7 @@
 """Internal APIs for tmuxp."""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)

src/tmuxp/_internal/private_path.py

@@ -6,10 +6,13 @@
 
 from __future__ import annotations
 
+import logging
 import os
 import pathlib
 import typing as t
 
+logger = logging.getLogger(__name__)
+
 if t.TYPE_CHECKING:
     PrivatePathBase = pathlib.Path
 else:

src/tmuxp/_internal/types.py

@@ -12,9 +12,12 @@
 
 from __future__ import annotations
 
+import logging
 import typing as t
 from typing import TypedDict
 
+logger = logging.getLogger(__name__)
+
 if t.TYPE_CHECKING:
     import sys
 

src/tmuxp/cli/__init__.py

@@ -181,9 +181,9 @@ def create_parser() -> argparse.ArgumentParser:
         "--log-level",
         action="store",
         metavar="log-level",
-        default="info",
+        default="warning",
         choices=["debug", "info", "warning", "error", "critical"],
-        help='log level (debug, info, warning, error, critical) (default "info")',
+        help='log level (debug, info, warning, error, critical) (default "warning")',
     )
     parser.add_argument(
         "--color",
@@ -297,7 +297,7 @@ def cli(_args: list[str] | None = None) -> None:
     parser = create_parser()
     args = parser.parse_args(_args, namespace=ns)
 
-    setup_logger(logger=logger, level=args.log_level.upper())
+    setup_logger(level=args.log_level.upper())
 
     if args.subparser_name is None:
         parser.print_help()

src/tmuxp/cli/_colors.py

@@ -9,6 +9,8 @@
 
 from __future__ import annotations
 
+import logging
+
 from tmuxp._internal.colors import (
     ColorMode,
     Colors,
@@ -20,6 +22,8 @@
     unstyle,
 )
 
+logger = logging.getLogger(__name__)
+
 __all__ = [
     "ColorMode",
     "Colors",

src/tmuxp/cli/_formatter.py

@@ -13,9 +13,12 @@
 from __future__ import annotations
 
 import argparse
+import logging
 import re
 import typing as t
 
+logger = logging.getLogger(__name__)
+
 # Options that expect a value (set externally or via --option=value)
 OPTIONS_EXPECTING_VALUE = frozenset(
     {

src/tmuxp/cli/load.py

@@ -23,6 +23,8 @@
 from ._colors import ColorMode, Colors, build_description, get_color_mode
 from .utils import prompt_choices, prompt_yes_no, tmuxp_echo
 
+logger = logging.getLogger(__name__)
+
 LOAD_DESCRIPTION = build_description(
     """
     Load tmuxp workspace file(s) and create or attach to a tmux session.
@@ -74,6 +76,7 @@ class CLILoadNamespace(argparse.Namespace):
     colors: CLIColorsLiteral | None
     color: CLIColorModeLiteral
     log_file: str | None
+    log_level: str
 
 
 def load_plugins(
@@ -590,12 +593,7 @@ def command_load(
     cli_colors = Colors(get_color_mode(args.color))
 
     if args.log_file:
-        logfile_handler = logging.FileHandler(args.log_file)
-        logfile_handler.setFormatter(log.LogFormatter())
-        # Add handler to tmuxp root logger to capture all tmuxp log messages
-        tmuxp_logger = logging.getLogger("tmuxp")
-        tmuxp_logger.setLevel(logging.INFO)  # Ensure logger level allows INFO
-        tmuxp_logger.addHandler(logfile_handler)
+        log.setup_log_file(args.log_file, args.log_level)
 
     if args.workspace_files is None or len(args.workspace_files) == 0:
         tmuxp_echo(cli_colors.error("Enter at least one config"))