Organize codebase into hub, clients, and common packages with backward compatibility and comprehensive unit test suites

src/common/__init__.py

@@ -0,0 +1 @@
+# LOGAR Common Package

src/common/version.py

@@ -0,0 +1,67 @@
+"""
+LOGAR - Unified Versioning and Semantic Comparison Module
+Provides canonical application version constants and semantic version comparison utilities.
+"""
+
+import os
+import re
+from typing import Tuple, Optional
+
+
+LOGAR_VERSION = "0.3.5.2"
+__version__ = LOGAR_VERSION
+
+
+def parse_version(version_str: Optional[str]) -> Tuple[int, ...]:
+    """
+    Parses a version string into a comparable tuple of integers.
+    Strips leading 'v' or 'V' and non-numeric suffixes.
+    e.g. 'v0.3.5.2' -> (0, 3, 5, 2), '0.3.5-beta' -> (0, 3, 5, 0)
+    """
+    if not version_str:
+        return (0, 0, 0, 0)
+    
+    clean = str(version_str).strip()
+    if clean.lower().startswith("v"):
+        clean = clean[1:].strip()
+    
+    # Extract digit sequences separated by dots
+    match = re.match(r"^(\d+(?:\.\d+)*)", clean)
+    if not match:
+        return (0, 0, 0, 0)
+    
+    parts = [int(p) for p in match.group(1).split(".")]
+    # Pad to at least 4 components for consistent 4-part semantic version comparison
+    while len(parts) < 4:
+        parts.append(0)
+    return tuple(parts)
+
+
+def compare_versions(v1: Optional[str], v2: Optional[str]) -> int:
+    """
+    Compares two version strings.
+    Returns:
+       1 if v1 > v2 (v1 is newer than v2)
+       0 if v1 == v2
+      -1 if v1 < v2 (v1 is older than v2)
+    """
+    t1 = parse_version(v1)
+    t2 = parse_version(v2)
+    if t1 > t2:
+        return 1
+    elif t1 < t2:
+        return -1
+    return 0
+
+
+def is_newer_version(candidate_version: Optional[str], current_version: Optional[str] = None) -> bool:
+    """
+    Returns True if candidate_version is strictly newer than current_version (or LOGAR_VERSION).
+    """
+    base = current_version or LOGAR_VERSION
+    return compare_versions(candidate_version, base) > 0
+
+
+def get_current_version() -> str:
+    """Returns the canonical current version string."""
+    return LOGAR_VERSION