feat: Implement structured logging system with TUI and log guidelines (#160)

Author: finxo

.claude/docs/logging.md

@@ -10,18 +10,26 @@
 -
 
 ## 🧪 Testing
-<!-- How has this been tested? -->
-- [ ] Unit tests added/updated
-- [ ] Integration tests added/updated
-- [ ] Manual testing performed
-- [ ] All tests passing
+<!-- How has this been tested? Check all that apply -->
+- [ ] Unit tests added/updated (`poetry run pytest`)
+- [ ] All tests passing (`make test`)
+- [ ] Manual testing with `titan-dev`
+
+<!-- If unit tests were added, briefly describe what is covered -->
+
+## 📊 Logs
+<!-- List new log events introduced by this PR, or check the box if none -->
+- [ ] No new log events
+
+<!-- If logs were added, list them:
+- `event_name` (DEBUG/INFO/ERROR) — description of when it fires and what fields it includes
+Example:
+- `git_command_ok` (DEBUG) — subcommand, duration
+- `ai_call_failed` (DEBUG) — provider, operation, max_tokens, duration
+-->
 
 ## ✅ Checklist
-- [ ] My code follows the project's style guidelines
-- [ ] I have performed a self-review of my own code
-- [ ] I have commented my code, particularly in hard-to-understand areas
-- [ ] I have made corresponding changes to the documentation
-- [ ] My changes generate no new warnings
-- [ ] I have added tests that prove my fix is effective or that my feature works
-- [ ] New and existing unit tests pass locally with my changes
-- [ ] Any dependent changes have been merged and published
+- [ ] Self-review done
+- [ ] Follows the project's [logging rules](.claude/docs/logging.md) (no secrets, no content in logs)
+- [ ] New and existing tests pass
+- [ ] Documentation updated if needed

.github/pull_request_template.md

@@ -8,8 +8,11 @@
 """
 import subprocess
 import shutil
+import time
 from typing import List, Optional
 
+from titan_cli.core.logging.config import get_logger
+
 from ...exceptions import (
     GitError,
     GitClientError,
@@ -44,6 +47,7 @@ def __init__(self, repo_path: str = "."):
             GitNotRepositoryError: If not in a git repository
         """
         self.repo_path = repo_path
+        self._logger = get_logger(__name__)
         self._check_git_installed()
         self._check_repository()
 
@@ -98,6 +102,10 @@ def run_command(
             >>> output = network.run_command(["git", "status", "--short"])
             >>> # Returns: "M file1.txt\\n?? file2.txt"
         """
+        # Log only the subcommand — never args[2:] (may contain remote URLs, commit messages)
+        subcommand = args[1] if len(args) > 1 else "unknown"
+        start = time.time()
+
         try:
             result = subprocess.run(
                 args,
@@ -106,8 +114,19 @@ def run_command(
                 text=True,
                 check=check
             )
+            self._logger.debug(
+                "git_command_ok",
+                subcommand=subcommand,
+                duration=round(time.time() - start, 3),
+            )
             return result.stdout.strip()
         except subprocess.CalledProcessError as e:
+            self._logger.debug(
+                "git_command_failed",
+                subcommand=subcommand,
+                duration=round(time.time() - start, 3),
+                exit_code=e.returncode,
+            )
             error_msg = e.stderr.strip() if e.stderr else str(e)
             if "not a git repository" in error_msg:
                 raise GitNotRepositoryError(

plugins/titan-plugin-git/titan_plugin_git/clients/network/git_network.py

@@ -8,6 +8,7 @@
 from typing import List
 
 from titan_cli.core.result import ClientResult, ClientSuccess, ClientError
+from titan_cli.core.logging import log_client_operation
 
 from ..network import GitNetwork
 from ...models.network.branch import NetworkGitBranch
@@ -34,6 +35,7 @@ def __init__(self, git_network: GitNetwork):
         """
         self.git = git_network
 
+    @log_client_operation()
     def get_current_branch(self) -> ClientResult[str]:
         """
         Get current branch name.
@@ -47,6 +49,7 @@ def get_current_branch(self) -> ClientResult[str]:
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="BRANCH_ERROR")
 
+    @log_client_operation()
     def get_branches(self, remote: bool = False) -> ClientResult[List[UIGitBranch]]:
         """
         List branches.
@@ -107,6 +110,7 @@ def get_branches(self, remote: bool = False) -> ClientResult[List[UIGitBranch]]:
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="BRANCH_LIST_ERROR")
 
+    @log_client_operation()
     def create_branch(
         self, branch_name: str, start_point: str = "HEAD"
     ) -> ClientResult[None]:
@@ -129,6 +133,7 @@ def create_branch(
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="BRANCH_CREATE_ERROR")
 
+    @log_client_operation()
     def delete_branch(
         self, branch: str, force: bool = False
     ) -> ClientResult[None]:
@@ -152,6 +157,7 @@ def delete_branch(
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="BRANCH_DELETE_ERROR")
 
+    @log_client_operation()
     def checkout(self, branch: str) -> ClientResult[None]:
         """
         Checkout a branch.
@@ -176,7 +182,8 @@ def checkout(self, branch: str) -> ClientResult[None]:
             except GitCommandError:
                 return ClientError(
                     error_message=msg.Git.BRANCH_NOT_FOUND.format(branch=branch),
-                    error_code="BRANCH_NOT_FOUND"
+                    error_code="BRANCH_NOT_FOUND",
+                    log_level="warning"
                 )
 
             # Checkout
@@ -192,10 +199,12 @@ def checkout(self, branch: str) -> ClientResult[None]:
             if "would be overwritten" in error_str or "uncommitted changes" in error_str:
                 return ClientError(
                     error_message=msg.Git.CANNOT_CHECKOUT_UNCOMMITTED_CHANGES,
-                    error_code="DIRTY_WORKING_TREE"
+                    error_code="DIRTY_WORKING_TREE",
+                    log_level="warning"
                 )
             return ClientError(error_message=str(e), error_code="CHECKOUT_ERROR")
 
+    @log_client_operation()
     def branch_exists_on_remote(
         self, branch: str, remote: str = "origin"
     ) -> ClientResult[bool]:

plugins/titan-plugin-git/titan_plugin_git/clients/services/branch_service.py

@@ -8,6 +8,7 @@
 from typing import List, Optional
 
 from titan_cli.core.result import ClientResult, ClientSuccess, ClientError
+from titan_cli.core.logging import log_client_operation
 
 from ..network import GitNetwork
 from ...exceptions import GitCommandError
@@ -34,6 +35,7 @@ def __init__(self, git_network: GitNetwork, main_branch: str = "main", default_r
         self.main_branch = main_branch
         self.default_remote = default_remote
 
+    @log_client_operation()
     def commit(
         self, message: str, all: bool = False, no_verify: bool = True
     ) -> ClientResult[str]:
@@ -68,6 +70,7 @@ def commit(
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="COMMIT_ERROR")
 
+    @log_client_operation()
     def get_current_commit(self) -> ClientResult[str]:
         """
         Get current commit SHA (HEAD).
@@ -84,6 +87,7 @@ def get_current_commit(self) -> ClientResult[str]:
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="COMMIT_ERROR")
 
+    @log_client_operation()
     def get_commit_sha(self, ref: str) -> ClientResult[str]:
         """
         Get commit SHA for any git ref.
@@ -103,6 +107,7 @@ def get_commit_sha(self, ref: str) -> ClientResult[str]:
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="COMMIT_ERROR")
 
+    @log_client_operation()
     def get_commits_vs_base(self) -> ClientResult[List[str]]:
         """
         Get commit messages from base branch to HEAD.
@@ -129,6 +134,7 @@ def get_commits_vs_base(self) -> ClientResult[List[str]]:
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="COMMIT_ERROR")
 
+    @log_client_operation()
     def get_branch_commits(
         self, base_branch: str, head_branch: str
     ) -> ClientResult[List[str]]:
@@ -161,6 +167,7 @@ def get_branch_commits(
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="COMMIT_ERROR")
 
+    @log_client_operation()
     def count_commits_ahead(self, base_branch: str = "develop") -> ClientResult[int]:
         """
         Count how many commits current branch is ahead of base branch.
@@ -183,6 +190,7 @@ def count_commits_ahead(self, base_branch: str = "develop") -> ClientResult[int]
         except (GitCommandError, ValueError) as e:
             return ClientError(error_message=str(e), error_code="COMMIT_COUNT_ERROR")
 
+    @log_client_operation()
     def count_unpushed_commits(
         self, branch: Optional[str] = None, remote: str = "origin"
     ) -> ClientResult[int]:

plugins/titan-plugin-git/titan_plugin_git/clients/services/commit_service.py

@@ -6,6 +6,7 @@
 Uses network layer to execute commands and returns diff outputs.
 """
 from titan_cli.core.result import ClientResult, ClientSuccess, ClientError
+from titan_cli.core.logging import log_client_operation
 
 from ..network import GitNetwork
 from ...exceptions import GitCommandError
@@ -30,6 +31,7 @@ def __init__(self, git_network: GitNetwork, default_remote: str = "origin"):
         self.git = git_network
         self.default_remote = default_remote
 
+    @log_client_operation()
     def get_diff(self, base_ref: str, head_ref: str = "HEAD") -> ClientResult[str]:
         """
         Get diff between two references.
@@ -50,6 +52,7 @@ def get_diff(self, base_ref: str, head_ref: str = "HEAD") -> ClientResult[str]:
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="DIFF_ERROR")
 
+    @log_client_operation()
     def get_uncommitted_diff(self) -> ClientResult[str]:
         """
         Get diff of all uncommitted changes (staged + unstaged + untracked).
@@ -69,6 +72,7 @@ def get_uncommitted_diff(self) -> ClientResult[str]:
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="DIFF_ERROR")
 
+    @log_client_operation()
     def get_staged_diff(self) -> ClientResult[str]:
         """
         Get diff of staged changes only (index vs HEAD).
@@ -82,6 +86,7 @@ def get_staged_diff(self) -> ClientResult[str]:
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="DIFF_ERROR")
 
+    @log_client_operation()
     def get_unstaged_diff(self) -> ClientResult[str]:
         """
         Get diff of unstaged changes only (working directory vs index).
@@ -95,6 +100,7 @@ def get_unstaged_diff(self) -> ClientResult[str]:
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="DIFF_ERROR")
 
+    @log_client_operation()
     def get_uncommitted_diff_stat(self) -> ClientResult[str]:
         """
         Get diff stat summary of uncommitted changes (working tree vs HEAD).
@@ -114,6 +120,7 @@ def get_uncommitted_diff_stat(self) -> ClientResult[str]:
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="DIFF_ERROR")
 
+    @log_client_operation()
     def get_file_diff(self, file_path: str) -> ClientResult[str]:
         """
         Get diff for a specific file.
@@ -133,6 +140,7 @@ def get_file_diff(self, file_path: str) -> ClientResult[str]:
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="DIFF_ERROR")
 
+    @log_client_operation()
     def get_branch_diff(self, base_branch: str, head_branch: str) -> ClientResult[str]:
         """
         Get diff between two branches.
@@ -156,6 +164,7 @@ def get_branch_diff(self, base_branch: str, head_branch: str) -> ClientResult[st
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="DIFF_ERROR")
 
+    @log_client_operation()
     def get_diff_stat(self, base_ref: str, head_ref: str = "HEAD") -> ClientResult[str]:
         """
         Get diff stat summary between two references.

plugins/titan-plugin-git/titan_plugin_git/clients/services/diff_service.py

@@ -9,6 +9,7 @@
 from typing import Optional, Tuple
 
 from titan_cli.core.result import ClientResult, ClientSuccess, ClientError
+from titan_cli.core.logging import log_client_operation
 
 from ..network import GitNetwork
 from ...exceptions import GitCommandError
@@ -30,6 +31,7 @@ def __init__(self, git_network: GitNetwork):
         """
         self.git = git_network
 
+    @log_client_operation()
     def push(
         self,
         remote: str = "origin",
@@ -69,6 +71,7 @@ def push(
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="PUSH_ERROR")
 
+    @log_client_operation()
     def pull(
         self, remote: str = "origin", branch: Optional[str] = None
     ) -> ClientResult[None]:
@@ -94,6 +97,7 @@ def pull(
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="PULL_ERROR")
 
+    @log_client_operation()
     def fetch(
         self,
         remote: str = "origin",
@@ -127,6 +131,7 @@ def fetch(
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="FETCH_ERROR")
 
+    @log_client_operation()
     def get_github_repo_info(self) -> ClientResult[Tuple[Optional[str], Optional[str]]]:
         """
         Extract GitHub repository owner and name from 'origin' remote URL.

plugins/titan-plugin-git/titan_plugin_git/clients/services/remote_service.py

@@ -9,6 +9,7 @@
 from typing import Optional
 
 from titan_cli.core.result import ClientResult, ClientSuccess, ClientError
+from titan_cli.core.logging import log_client_operation
 
 from ..network import GitNetwork
 from ...exceptions import GitCommandError
@@ -31,6 +32,7 @@ def __init__(self, git_network: GitNetwork):
         """
         self.git = git_network
 
+    @log_client_operation()
     def stash_push(self, message: Optional[str] = None) -> ClientResult[bool]:
         """
         Stash uncommitted changes.
@@ -52,6 +54,7 @@ def stash_push(self, message: Optional[str] = None) -> ClientResult[bool]:
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="STASH_ERROR")
 
+    @log_client_operation()
     def stash_pop(self, stash_ref: Optional[str] = None) -> ClientResult[bool]:
         """
         Pop stash (apply and remove).
@@ -72,6 +75,7 @@ def stash_pop(self, stash_ref: Optional[str] = None) -> ClientResult[bool]:
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="STASH_POP_ERROR")
 
+    @log_client_operation()
     def find_stash_by_message(self, message: str) -> ClientResult[Optional[str]]:
         """
         Find stash by message.
@@ -98,6 +102,7 @@ def find_stash_by_message(self, message: str) -> ClientResult[Optional[str]]:
         except GitCommandError as e:
             return ClientError(error_message=str(e), error_code="STASH_FIND_ERROR")
 
+    @log_client_operation()
     def restore_stash(self, message: str) -> ClientResult[bool]:
         """
         Restore stash by finding it with a message and popping it.