improve debug info - resolves #18

6b273f5: update insttructions - #18

c62c5b9: updated the summary instructions - #18

29bd34e: added an assert_contract feature - #18

6f9a1d0: pretty print - #18

Author: Lars Kruse

.github/instructions/summary.instructions.md

@@ -13,9 +13,11 @@ When in agent mode, and you are asked to create issues and comments to issues, p
 
 ## Read issue number from branch name
 
-When agent mode and I ask to _annotate a comment on the current changeset to the issue_ you can always read the implied issue number from the current git branch - development branches are prefixed with an integer, and that is a reference to the issue being worked on. The branch name is part of the zsh prompt in the @terminal, and can be directly accessed; The `$PS1` is set up to show the branch name too (e.g. `vscode ➜ /workspaces/gh-tt (321-Update_summary_instructions) $` equals issue 321). Let summary serve as a work log note to future self and current colleagues. It should summarize the changes made in the branch we're working on since we left `main`.
+When in agent mode and you ask to _annotate a comment on the current changeset to the issue_, extract the issue number directly from the terminal prompt shown in the `@terminal` context. Development branches are formatted as `(ISSUE_NUMBER-branch_name)` in the zsh prompt. For example, the prompt `vscode ➜ /workspaces/gh-tt (321-Update_summary_instructions) $` indicates you're working on issue 321.
 
-Equivalent to `git diff main...HEAD --name-status && git diff main...HEAD`.
+Extract the issue number (the integer before the first hyphen in the branch name shown in parentheses). If the full prompt with branch name is not visible in the `@terminal` context, run `git branch --show-current` to get the branch name, then extract the issue number from it. Do not ask for clarification—just get the information you need to proceed.
+
+Let the summary serve as a work log note to future self and current colleagues. It should summarize the changes made in the branch we're working on since we left `main`, equivalent to `git diff main...HEAD --name-status && git diff main...HEAD`.
 
 ## Change set summary
 

.vscode/launch.json

@@ -12,7 +12,7 @@
             "name": "Python Debugger: gh_tt.py with Arguments (in current workspace)",
             "type": "debugpy",
             "request": "launch",
-            "program": "-m gh_tt",
+            "module": "gh_tt",
             "console": "integratedTerminal",
             "cwd": "${workspaceFolder}",
             "args": "${command:pickArgs}"

gh_tt/classes/semver.py

@@ -10,6 +10,7 @@
 from gh_tt.classes.config import Config
 from gh_tt.classes.gitter import Gitter
 from gh_tt.classes.lazyload import Lazyload
+from gh_tt.utils import assert_contract
 
 
 class ReleaseType(StrEnum):
@@ -432,6 +433,14 @@ def bump(
         message = f"\n{message}" if message else ""
 
         current_version = self.get_current_semver().version if self.get_current_semver() is not None else None
+
+        assert_contract(
+            contract=current_version is not None,
+            msg="No current release version found. Cannot bump version.",
+            hint="Run 'gh tt semver init' to create the initial version."
+        )
+
+
         current_prerelease_version = self.get_current_semver(ReleaseType.PRERELEASE).version if self.get_current_semver(ReleaseType.PRERELEASE) is not None else None
 
         self._get_next_semvers(current_version, current_prerelease_version)

gh_tt/gh_tt.py

@@ -5,6 +5,7 @@
 from gh_tt.classes.gitter import Gitter
 from gh_tt.modules.tt_handlers import COMMAND_HANDLERS
 from gh_tt.modules.tt_parser import tt_parse
+from gh_tt.utils import ContractError
 
 
 def main():
@@ -20,9 +21,22 @@ def main():
     Gitter.read_cache()
     # Gitter.validate_gh_scope(scope='project') this check causes more problems than it solves
 
-    # Execute the appropriate command handler
-    if args.command in COMMAND_HANDLERS:
-        COMMAND_HANDLERS[args.command](args)
+    try:
+        # Execute the appropriate command handler
+        if args.command in COMMAND_HANDLERS:
+            COMMAND_HANDLERS[args.command](args)
+    except ContractError as e:
+        print(f"{e}", file=sys.stderr)
+        if Gitter.verbose:
+            tb = e.__traceback__
+            # Go back one frame from the innermost to skip the raise line in utils.py
+            # and point to where assert_contract was actually called
+            while tb.tb_next and tb.tb_next.tb_next:
+                tb = tb.tb_next
+            filename = tb.tb_frame.f_code.co_filename
+            lineno = tb.tb_lineno
+            print(f"🔦 @ {filename}:{lineno}", file=sys.stderr)
+        sys.exit(1)
 
     Gitter.write_cache()            
     sys.exit(0)

gh_tt/utils.py

@@ -0,0 +1,33 @@
+"""Utility functions for design by contract programming."""
+
+
+class ContractError(Exception):
+    """Exception raised when a contract is violated.
+    
+    Contract violations are user-facing errors representing invalid program state
+    or precondition failures, distinct from unexpected runtime errors.
+    """
+
+
+def assert_contract(*, contract: bool, msg: str, hint: str | None = None) -> None:
+    """Assert a contract condition using design by contract principles.
+    
+    Raises a ContractError with a clean, user-friendly message if the contract is violated.
+    
+    Args:
+        contract: Boolean condition that must be True for the contract to hold
+        msg: The main error message describing what went wrong
+        hint: Optional helpful hint or instruction for resolving the issue
+        
+    Raises:
+        ContractError: If contract is False, with formatted message including hint if provided
+        
+    Example:
+        >>> from gh_tt.utils import assert_contract
+        >>> assert_contract(version is not None, "No version found", "Run 'init' first")
+    """
+    if not contract:
+        error_msg = f"❌ {msg}"
+        if hint:
+            error_msg += f"\n💡 {hint}"
+        raise ContractError(error_msg)