synapse-hub 2.2.3 → 2.4.0

package/tools/bug_reporter.py

@@ -16,6 +16,19 @@ import argparse
 from typing import Dict, List, Optional, Any
 from datetime import datetime
 
+try:
+    from tools.cache_resolver import compute_error_fingerprint
+except ImportError:
+    try:
+        from cache_resolver import compute_error_fingerprint
+    except ImportError:
+        def compute_error_fingerprint(err_type: str, err_msg: str, stack_anchor: str = "") -> str:
+            raw = f"{(err_type or '').strip().lower()}:{(err_msg or '').strip()[:200]}"
+            h = 5381
+            for b in raw.encode("utf-8", errors="ignore"):
+                h = (((h << 5) + h) + b) & 0xFFFFFFFF
+            return f"fp_{h:08x}"
+
 
 class BugReporter:
     """Enterprise Automated Bug Ticket & RCA Generator."""
@@ -104,6 +117,8 @@ class BugReporter:
         rca = cls.classify_root_cause(error_message, stack_trace)
         distilled_stack = cls.distill_stack_trace(stack_trace)
         timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        anchor = distilled_stack.splitlines()[0].strip() if distilled_stack else ""
+        fingerprint = compute_error_fingerprint(rca["type"], error_message, anchor)
 
         steps = steps_executed or [
             f"1. Navigate to target application under test",
@@ -111,11 +126,26 @@ class BugReporter:
             f"3. Trigger operation causing failure: {error_message[:80]}"
         ]
 
+        if format_type.lower() == "json":
+            return json.dumps({
+                "test_id": test_id,
+                "title": test_title,
+                "fingerprint": fingerprint,
+                "rca": rca,
+                "error_message": error_message,
+                "distilled_stack": distilled_stack,
+                "screenshot": screenshot_path,
+                "steps": steps,
+                "environment": environment,
+                "timestamp": timestamp
+            }, indent=2)
+
         if format_type.lower() == "jira":
             report = [
                 f"h2. [BUG][{rca['severity'].upper()}] {test_id}: {test_title} - {error_message[:90]}",
                 "",
                 f"* *Issue Type:* Bug",
+                f"* *Error Fingerprint:* {fingerprint}",
                 f"* *Root Cause Category:* {rca['label']}",
                 f"* *Severity / Priority:* {rca['severity']}",
                 f"* *Assigned Team:* {rca['suggested_team']}",
@@ -155,7 +185,7 @@ class BugReporter:
         md = [
             f"# [BUG][{rca['severity'].upper()}] {test_id}: {test_title}",
             "",
-            f"> **Root Cause Analysis:** `{rca['label']}`  ",
+            f"> **Fingerprint:** `{fingerprint}` | **Root Cause Category:** `{rca['label']}`  ",
             f"> **Severity:** **{rca['severity']}** | **Assigned To:** `{rca['suggested_team']}` | **Detected:** {timestamp}",
             "",
             "## 📌 1. Steps to Reproduce",

package/tools/bump_version.py

@@ -65,7 +65,10 @@ def get_current_version() -> str:
     pkg_file = os.path.join(REPO_ROOT, "package.json")
     with open(pkg_file, "r", encoding="utf-8") as f:
         data = json.load(f)
-    return data.get("version", "2.0.0")
+    version = data.get("version")
+    if not version:
+        raise ValueError("package.json does not contain a valid 'version' field.")
+    return version
 
 def update_json_root_version(rel_path: str, new_ver: str, dry_run: bool = False) -> bool:
     full_path = os.path.join(REPO_ROOT, rel_path)
@@ -127,7 +130,7 @@ def run_tests() -> bool:
     if res_verify.returncode != 0:
         print("❌ Quality Gates failed! Aborting release.")
         return False
-    print("✅ 8 Quality Gates DoD PASSED.")
+    print("✅ 9 Quality Gates DoD PASSED.")
     return True
 
 def git_commit_and_tag(version: str, push: bool = False):
@@ -167,12 +170,18 @@ def main():
     # 1. package.json
     update_json_root_version("package.json", new_ver, args.dry_run)
 
+    # 1b. plugin.json
+    update_json_root_version("plugin.json", new_ver, args.dry_run)
+
     # 2. pyproject.toml
     update_file("pyproject.toml", r'(version\s*=\s*")[^"]+(")', rf"\g<1>{new_ver}\g<2>", args.dry_run)
 
     # 3. skills_manifest.json
     update_json_root_version("skills_manifest.json", new_ver, args.dry_run)
 
+    # 3b. synapse.config.json
+    update_json_root_version("synapse.config.json", new_ver, args.dry_run)
+
     # 4. tools/cli.py
     update_file("tools/cli.py", r'(version\s*=\s*")[^"]+(")', rf"\g<1>{new_ver}\g<2>", args.dry_run)
 
@@ -189,10 +198,21 @@ def main():
     # 8. docs/ARCHITECTURE.md
     update_file("docs/ARCHITECTURE.md", r'(>\s*\*\*Version:\*\*\s*`)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
 
-    # 9. README.md (Documentation headings and mermaid badges)
+    # 9. README.md & README.en.md (Documentation headings and badges)
     update_file("README.md", r'(Phiên bản Hub:\*\*\s*`v)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
     update_file("README.md", r'(Hub Version:\*\*\s*`v)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
     update_file("README.md", r'(Intelligence Core v)[^")\]]+', rf"\g<1>{new_ver}", args.dry_run)
+    update_file("README.en.md", r'(Hub Version:\*\*\s*`v)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
+    update_file("README.en.md", r'(Intelligence Core v)[^")\]]+', rf"\g<1>{new_ver}", args.dry_run)
+
+    # 10. tools/__init__.py
+    update_file("tools/__init__.py", r'(__version__\s*=\s*")[^"]+(")', rf"\g<1>{new_ver}\g<2>", args.dry_run)
+
+    # 11. tools/welcome_page.py
+    update_file("tools/welcome_page.py", r'("version":\s*")[^"]+(")', rf"\g<1>{new_ver}\g<2>", args.dry_run)
+
+    # 12. tools/dashboard_generator.py
+    update_file("tools/dashboard_generator.py", r'(Synapse-Hub v)[0-9]+\.[0-9]+\.[0-9]+', rf"\g<1>{new_ver}", args.dry_run)
 
     if args.dry_run:
         print("\n[INFO] Dry-run completed. No files modified on disk.")

package/tools/cache_resolver.py

@@ -32,28 +32,127 @@ if hasattr(sys.stdout, 'reconfigure'):
     except Exception:
         pass
 
+def _find_project_root():
+    """Traverses up from CWD or script directory to find the target project root."""
+    curr = os.path.abspath(os.getcwd())
+    while True:
+        if any(os.path.exists(os.path.join(curr, m)) for m in ("package.json", "PROJECT_AI_GUIDE.md", ".git", "pyproject.toml")):
+            return curr
+        parent = os.path.dirname(curr)
+        if parent == curr:
+            break
+        curr = parent
+    return os.path.abspath(os.path.dirname(os.path.dirname(__file__)))
+
+
 GLOBAL_DIR = os.path.expanduser("~/.agent_memory")
 GLOBAL_DB = os.path.join(GLOBAL_DIR, "global_cache.db")
-LOCAL_DB = os.path.join(os.path.dirname(os.path.abspath(__file__)), "memory_cache.db")
+LOCAL_DIR = os.path.join(_find_project_root(), ".synapse")
+LOCAL_DB = os.path.join(LOCAL_DIR, "cache.db")
 
 
 def resolve_db_path(use_local=False):
-    """Returns the SQLite database path. Defaults to Global Central Memory."""
-    if use_local:
-        return LOCAL_DB
-    os.makedirs(GLOBAL_DIR, exist_ok=True)
-    return GLOBAL_DB
+    """
+    Returns the SQLite database path.
+    Defaults to project-local store (.synapse/cache.db) to prevent cross-project NDA/IP leakage.
+    Global memory (~/.agent_memory/global_cache.db) is only used when SYNAPSE_GLOBAL_CACHE=1
+    or when explicit use_local=False is called with SYNAPSE_GLOBAL_CACHE enabled.
+    Zero filesystem mutation on module import: directories are lazy-created upon connection.
+    """
+    if os.environ.get("SYNAPSE_CACHE_DB"):
+        return os.environ.get("SYNAPSE_CACHE_DB")
+    if os.environ.get("SYNAPSE_GLOBAL_CACHE", "").lower() in ("1", "true", "yes") and not use_local:
+        return GLOBAL_DB
+    return LOCAL_DB
 
 
 DB_FILE = resolve_db_path()
 
+SECRET_PATTERNS = [
+    (re.compile(r'(?i)(api[_-]?key|secret|token|password|auth|passwd|credential)[\s:=]+["\']?([a-zA-Z0-9_\-\.]{8,})["\']?'), r'\1="[REDACTED]"'),
+    (re.compile(r'-----BEGIN[ A-Z_-]+PRIVATE KEY-----[\s\S]+?-----END[ A-Z_-]+PRIVATE KEY-----'), '[REDACTED_PRIVATE_KEY]'),
+    (re.compile(r'https?://([^:]+):([^@]+)@'), r'https://\1:[REDACTED]@'),
+    (re.compile(r'Bearer\s+[a-zA-Z0-9_\-\.]{15,}'), 'Bearer [REDACTED_TOKEN]'),
+]
+
+
+def sanitize_text(text):
+    """Redacts passwords, API tokens, and private keys before persisting to SQLite memory."""
+    if not text or not isinstance(text, str):
+        return text or ""
+    sanitized = text
+    for pattern, repl in SECRET_PATTERNS:
+        sanitized = pattern.sub(repl, sanitized)
+    return sanitized
+
+
+def djb2_hash(s: str) -> str:
+    """Computes a 32-bit unsigned DJB2 hash formatted as an 8-char hex string."""
+    h = 5381
+    for byte in s.encode('utf-8', errors='ignore'):
+        h = (((h << 5) + h) + byte) & 0xFFFFFFFF
+    return f"{h:08x}"
+
+
+def compute_error_fingerprint(error_type: str, error_msg: str, stack_anchor: str = "") -> str:
+    """
+    Computes a deterministic, normalized fingerprint hash for an error.
+    Strips volatile elements (timestamps, hex addresses, line numbers) so semantically
+    identical errors across test runs produce the identical fingerprint.
+    """
+    norm_type = (error_type or "").strip().lower()
+    msg = error_msg or ""
+    # Strip hex memory addresses
+    msg = re.sub(r'0x[0-9a-fA-F]+', '0xADDR', msg)
+    # Strip ISO/standard timestamps
+    msg = re.sub(r'\b\d{4}-\d{2}-\d{2}[T\s]\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?\b', 'TIMESTAMP', msg)
+    # Strip variable line numbers in filenames like "file.py:123"
+    msg = re.sub(r':\d+\b', ':LINE', msg)
+    # Collapse whitespace
+    msg = re.sub(r'\s+', ' ', msg).strip()[:200]
+
+    anchor = (stack_anchor or "").strip().lower()
+    if anchor:
+        anchor = re.sub(r':\d+\b', ':LINE', anchor)
+        raw = f"{norm_type}:{msg}@{anchor}"
+    else:
+        raw = f"{norm_type}:{msg}"
+    return f"fp_{djb2_hash(raw)}"
+
+
+def group_errors_by_fingerprint(error_list: list, repeat_threshold: int = 3) -> dict:
+    """
+    Groups error events by fingerprint and detects repeated errors (exceeding repeat_threshold).
+    """
+    grouped = {}
+    for item in error_list:
+        err_type = item.get("error_type") or item.get("type") or "UnknownError"
+        err_msg = item.get("error_message") or item.get("message") or item.get("symptom") or ""
+        anchor = item.get("stack_anchor") or item.get("file") or ""
+        fp = compute_error_fingerprint(err_type, err_msg, anchor)
+        if fp not in grouped:
+            grouped[fp] = {
+                "fingerprint": fp,
+                "count": 0,
+                "is_repeated": False,
+                "error_type": err_type,
+                "sample_message": err_msg,
+                "items": []
+            }
+        grouped[fp]["count"] += 1
+        if grouped[fp]["count"] >= repeat_threshold:
+            grouped[fp]["is_repeated"] = True
+        grouped[fp]["items"].append(item)
+    return grouped
+
+
 SEED_SOLUTIONS = [
     {
         "error_signature": "ElementClickInterceptedException",
         "module_name": "GLOBAL",
         "symptom": "Modal backdrop or PrimeNG overlay (.p-component-overlay) blocks button click.",
         "root_cause": "Angular PrimeNG animation fade-out latency.",
-        "groovy_patch": "((JavascriptExecutor) driver).executeScript(\"arguments[0].click();\", element);"
+        "groovy_patch": "waitForElementNotVisible(By.cssSelector(\".p-component-overlay, .modal-backdrop\"), 5);\nfindElement(by).click();"
     },
     {
         "error_signature": "Save_Button_Disabled",
@@ -67,7 +166,7 @@ SEED_SOLUTIONS = [
         "module_name": "GLOBAL",
         "symptom": "Element is not attached to the DOM.",
         "root_cause": "Angular re-rendered DOM node after async API response.",
-        "groovy_patch": "for (int i = 0; i < 3; i++) {\n    try {\n        findElement(by).click();\n        break;\n    } catch (StaleElementReferenceException e) {\n        sleep(500);\n    }\n}"
+        "groovy_patch": "for (int i = 0; i < 3; i++) {\n    try {\n        waitForElementVisible(by, 5);\n        findElement(by).click();\n        break;\n    } catch (StaleElementReferenceException e) {\n        waitForPageLoaded(5);\n    }\n}"
     },
     {
         "error_signature": "Duplicate_Code_Error",
@@ -165,10 +264,22 @@ def retry_on_locked(max_retries=5, initial_delay=0.05, backoff=2.0):
     return decorator
 
 
+class ManagedConnection(sqlite3.Connection):
+    """Resilient SQLite connection that automatically commits/rollbacks and closes on context exit."""
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        try:
+            super().__exit__(exc_type, exc_val, exc_tb)
+        finally:
+            self.close()
+
+
 def get_db(db_path=None, timeout=30.0):
-    """Returns a resilient SQLite connection configured with WAL mode and busy timeout."""
-    target = db_path or DB_FILE
-    conn = sqlite3.connect(target, timeout=timeout)
+    """Returns a resilient SQLite connection configured with WAL mode, busy timeout, and auto-close."""
+    target = db_path or resolve_db_path()
+    parent_dir = os.path.dirname(os.path.abspath(target))
+    if parent_dir and not os.path.exists(parent_dir):
+        os.makedirs(parent_dir, exist_ok=True)
+    conn = sqlite3.connect(target, timeout=timeout, factory=ManagedConnection)
     conn.row_factory = sqlite3.Row
     try:
         conn.execute("PRAGMA journal_mode=WAL;")
@@ -451,6 +562,9 @@ def get_failed_fixes(error_signature):
 @retry_on_locked()
 def record_failed_fix(error_signature, attempted_patch, failure_reason, agent_role="pom-crafter"):
     """Records a failed bug fix attempt into negative memory so AI agents will never repeat it."""
+    error_signature = sanitize_text(error_signature)
+    attempted_patch = sanitize_text(attempted_patch)
+    failure_reason = sanitize_text(failure_reason)
     init_db(seed=True)
     with get_db() as conn:
         cursor = conn.cursor()
@@ -557,7 +671,10 @@ def query_solution(error_signature, module_name="GLOBAL", threshold=0.35):
 @retry_on_locked()
 def learn_solution(error_signature, module_name, symptom, root_cause, groovy_patch, code_patch=None):
     """Saves a verified solution into positive memory."""
-    patch = code_patch or groovy_patch
+    patch = sanitize_text(code_patch or groovy_patch)
+    error_signature = sanitize_text(error_signature)
+    symptom = sanitize_text(symptom)
+    root_cause = sanitize_text(root_cause)
     init_db(seed=True)
     with get_db() as conn:
         cursor = conn.cursor()
@@ -640,16 +757,22 @@ def sync_db():
 def record_lesson(page_context, error_signature, root_cause, failed_attempt, successful_fix, lesson_summary):
     """
     Episodic Reflexion Memory:
-    Records a concise lesson learned (maximum 2 lines) into SQLite for cross-session reflection.
+    Records a concise lesson learned (maximum 2 lines) into SQLite for cross-session reflection after secret sanitization.
     """
     init_db(seed=True)
+    page_context = sanitize_text(page_context or "GLOBAL")
+    error_signature = sanitize_text(error_signature)
+    root_cause = sanitize_text(root_cause)
+    failed_attempt = sanitize_text(failed_attempt)
+    successful_fix = sanitize_text(successful_fix)
+    lesson_summary = sanitize_text(lesson_summary.strip())
     with get_db() as conn:
         cursor = conn.cursor()
         cursor.execute("""
             INSERT INTO lessons_learned 
             (page_context, error_signature, root_cause, failed_attempt, successful_fix, lesson_summary)
             VALUES (?, ?, ?, ?, ?, ?)
-        """, (page_context or "GLOBAL", error_signature, root_cause, failed_attempt, successful_fix, lesson_summary.strip()))
+        """, (page_context, error_signature, root_cause, failed_attempt, successful_fix, lesson_summary))
         conn.commit()
         return True
 
@@ -700,6 +823,8 @@ def record_test_telemetry(test_id, status, is_retry=0, duration_ms=0.0, error_si
     Records an individual test execution into persistent SQLite telemetry.
     Used for computing 30-day historical flakiness index and auto-quarantine decisions.
     """
+    error_signature = sanitize_text(error_signature)
+    context = sanitize_text(context)
     init_db(seed=True, target_db=target_db)
     current_db = target_db or DB_FILE
     with get_db(current_db) as conn:
@@ -793,6 +918,45 @@ def get_stats():
         }
 
 
+@retry_on_locked()
+def purge_cache(keep_seeds=True, target_db=None):
+    """Clears SQLite memory cache, preserving default seed solutions if keep_seeds=True."""
+    target = target_db or DB_FILE
+    init_db(seed=False, target_db=target)
+    with get_db(target) as conn:
+        cursor = conn.cursor()
+        cursor.execute("DELETE FROM failed_fixes")
+        cursor.execute("DELETE FROM lessons_learned")
+        cursor.execute("DELETE FROM test_telemetry")
+        if keep_seeds:
+            cursor.execute("DELETE FROM healing_cache WHERE module_name != 'GLOBAL'")
+        else:
+            cursor.execute("DELETE FROM healing_cache")
+        conn.commit()
+    if keep_seeds:
+        init_db(seed=True, target_db=target)
+    return True
+
+
+def export_cache(target_db=None):
+    """Exports all positive solutions, negative failed fixes, and lessons learned to a structured dictionary."""
+    target = target_db or DB_FILE
+    init_db(seed=True, target_db=target)
+    with get_db(target) as conn:
+        healing = [dict(r) for r in conn.execute("SELECT * FROM healing_cache").fetchall()]
+        failed = [dict(r) for r in conn.execute("SELECT * FROM failed_fixes").fetchall()]
+        lessons = [dict(r) for r in conn.execute("SELECT * FROM lessons_learned").fetchall()]
+        telemetry = [dict(r) for r in conn.execute("SELECT * FROM test_telemetry").fetchall()]
+    return {
+        "exported_at": datetime.now().isoformat(),
+        "database": target,
+        "healing_cache": healing,
+        "failed_fixes": failed,
+        "lessons_learned": lessons,
+        "test_telemetry": telemetry,
+    }
+
+
 def main():
     global DB_FILE
     parser = argparse.ArgumentParser(description="Enterprise Central Agent Memory & Self-Healing Resolver")
@@ -851,9 +1015,28 @@ def main():
     # Stats command
     subparsers.add_parser("stats", help="View memory cache statistics (Positive & Negative)")
 
+    # Fingerprint command (Deterministic Error Signature Hashing)
+    fp_parser = subparsers.add_parser("fingerprint", help="Generate deterministic DJB2 error fingerprint")
+    fp_parser.add_argument("--type", default="UnknownError", help="Error type/class (e.g. AssertionError)")
+    fp_parser.add_argument("--msg", required=True, help="Error message / symptom")
+    fp_parser.add_argument("--stack", default="", help="Optional stack anchor or file:function")
+
+    # Detect-Repeated command (Group errors and flag repeated errors)
+    rep_parser = subparsers.add_parser("detect-repeated", help="Group errors by fingerprint and flag repeated occurrences")
+    rep_parser.add_argument("--file", required=True, help="Path to JSON file containing list of error objects")
+    rep_parser.add_argument("--threshold", type=int, default=3, help="Repeat threshold (default: 3)")
+
     # Sync command
     subparsers.add_parser("sync", help="Synchronize Global Central Memory with Local Project Cache")
 
+    # Purge command
+    purge_parser = subparsers.add_parser("purge", help="Clear SQLite memory cache")
+    purge_parser.add_argument("--all", action="store_true", help="Clear all entries including default seed solutions")
+
+    # Export command
+    export_parser = subparsers.add_parser("export", help="Export memory cache and lessons to JSON")
+    export_parser.add_argument("-o", "--output", help="Output file path (default: stdout)")
+
     # Init command
     subparsers.add_parser("init", help="Initialize and seed database")
 
@@ -976,6 +1159,57 @@ def main():
         count = sync_db()
         print(f"✅ [MEMORY SYNC] Bidirectional sync completed ({count} solutions synchronized between Global & Local).")
 
+    elif args.command == "purge":
+        all_entries = getattr(args, "all", False)
+        purge_cache(keep_seeds=not all_entries)
+        scope_str = "All memory entries cleared (including default seeds)" if all_entries else "User entries cleared (seed solutions preserved)"
+        print(f"✅ [MEMORY PURGE] SQLite cache purged: {scope_str} at {DB_FILE}")
+
+    elif args.command == "export":
+        data = export_cache()
+        if getattr(args, "output", None):
+            with open(args.output, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2)
+            print(f"✅ [MEMORY EXPORT] Exported memory cache to: {args.output}")
+        else:
+            print(json.dumps(data, indent=2))
+
+    elif args.command == "fingerprint":
+        fp = compute_error_fingerprint(args.type, args.msg, args.stack)
+        print(f"🔑 Error Fingerprint: {fp}")
+        print(f"   Normalized Type  : {args.type.strip().lower()}")
+        print(f"   Raw Message      : {args.msg[:120]}")
+        if args.stack:
+            print(f"   Stack Anchor     : {args.stack}")
+
+    elif args.command == "detect-repeated":
+        if not os.path.exists(args.file):
+            print(f"❌ Error file not found: {args.file}")
+            sys.exit(1)
+        with open(args.file, "r", encoding="utf-8", errors="replace") as f:
+            error_data = json.load(f)
+        if isinstance(error_data, dict) and "errors" in error_data:
+            error_data = error_data["errors"]
+        elif not isinstance(error_data, list):
+            error_data = [error_data]
+        grouped = group_errors_by_fingerprint(error_data, repeat_threshold=args.threshold)
+        print("==================================================")
+        print(f"🔍 [ERROR FINGERPRINT GROUPING] Processed {len(error_data)} errors -> {len(grouped)} unique groups")
+        print("==================================================")
+        repeated_count = 0
+        for fp, group in grouped.items():
+            status_tag = f"🚨 [REPEATED ERROR >= {args.threshold}x]" if group["is_repeated"] else "ℹ️ [OBSERVE]"
+            if group["is_repeated"]:
+                repeated_count += 1
+            print(f"{status_tag} {fp} ({group['count']}x)")
+            print(f"   Type: {group['error_type']} | Sample: {group['sample_message'][:100]}")
+        print("==================================================")
+        if repeated_count > 0:
+            print(f"⚠️  Alert: {repeated_count} error fingerprints exceeded repeat threshold ({args.threshold}x).")
+            sys.exit(2)
+        else:
+            print("✅ Zero repeated errors exceeded threshold.")
+
     elif args.command == "init" or args.command is None:
         init_db(seed=True)
         print(f"✅ Central Agent Memory initialized at: {DB_FILE}")

package/tools/check_env.py

@@ -69,8 +69,9 @@ def resolve_target_repo(cli_target=None, cli_repo=None):
 
 
 class DiagnosticRunner:
-    def __init__(self, target_dir=None):
+    def __init__(self, target_dir=None, insecure: bool = False):
         self.target_dir = Path(target_dir or HUB_ROOT).resolve()
+        self.insecure = insecure
         self.results = []
         self.warnings = []
         self.errors = []
@@ -85,9 +86,9 @@ class DiagnosticRunner:
             else:
                 self.warnings.append((name, fix_hint))
 
-    def run_command(self, cmd):
+    def run_command(self, cmd, timeout: float = 15.0):
         try:
-            res = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, shell=isinstance(cmd, str))
+            res = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, shell=isinstance(cmd, str), timeout=timeout)
             return res.returncode == 0, res.stdout.strip()
         except Exception as e:
             return False, str(e)
@@ -99,13 +100,33 @@ class DiagnosticRunner:
         self.log_check("Operating System", "PASS", f"{os_name} {os_ver} ({arch})")
 
     def check_chrome(self):
-        # 1. Search via 'where' or 'which'
-        found, out = self.run_command("where chrome" if platform.system() == "Windows" else "which google-chrome")
-        if found:
+        # 1. Search via 'where' (Windows) or 'which' (Unix)
+        cmd = "where chrome" if platform.system() == "Windows" else "which google-chrome google-chrome-stable chromium chromium-browser"
+        found, out = self.run_command(cmd)
+        if found and out:
             self.log_check("Google Chrome (Browser)", "PASS", f"Installed at {out.splitlines()[0]}")
             return
 
-        # 2. Search standard installation paths on Windows
+        # 2. Search macOS standard application bundles
+        if platform.system() == "Darwin":
+            mac_paths = [
+                Path("/Applications/Google Chrome.app"),
+                Path.home() / "Applications/Google Chrome.app",
+                Path("/Applications/Chromium.app"),
+                Path("/Applications/Brave Browser.app"),
+                Path("/Applications/Microsoft Edge.app")
+            ]
+            for p in mac_paths:
+                if p.exists():
+                    self.log_check("Google Chrome (Browser)", "PASS", f"Installed at {p}")
+                    return
+            # Also check Playwright managed browser installations
+            pw_cache = Path.home() / "Library/Caches/ms-playwright"
+            if pw_cache.exists() and any(pw_cache.glob("chromium-*")):
+                self.log_check("Google Chrome (Browser)", "PASS", f"Playwright Chromium runtime verified at {pw_cache}")
+                return
+
+        # 3. Search Windows standard installation paths
         if platform.system() == "Windows":
             paths = [
                 os.path.expandvars(r"%ProgramFiles%\Google\Chrome\Application\chrome.exe"),
@@ -134,8 +155,15 @@ class DiagnosticRunner:
                                "Katalon includes embedded JRE, but for Gradle/Jenkins CLI, install OpenJDK 17.")
 
     def check_katalon(self):
+        # Context-aware: check if current target is actually a Katalon project
+        is_katalon_project = (
+            any(self.target_dir.glob("*.prj"))
+            or (self.target_dir / "Keywords").exists()
+            or ((self.target_dir / "Scripts").exists() and any(self.target_dir.glob("Scripts/**/*.groovy")))
+        )
+
         found, out = self.run_command("where katalonc" if platform.system() == "Windows" else "which katalonc")
-        if found:
+        if found and out:
             self.log_check("Katalon Runtime Engine (KRE)", "PASS", f"Found katalonc at {out.splitlines()[0]}")
             return
 
@@ -154,8 +182,11 @@ class DiagnosticRunner:
                             self.log_check("Katalon Studio IDE", "PASS", f"Installation directory located at {os.path.join(c, item)}")
                             return
 
-        self.log_check("Katalon Studio IDE", "WARN", "Katalon Studio installation not found in standard paths",
-                       "Download and install Katalon Studio (v8.x/v9.x/v10.x) from https://katalon.com/download")
+        if is_katalon_project:
+            self.log_check("Katalon Studio IDE", "WARN", "Katalon Studio installation not found in standard paths",
+                           "Download and install Katalon Studio from https://katalon.com/download")
+        else:
+            self.log_check("Katalon Studio IDE", "PASS", "Not installed (Optional - not required for Playwright/Cypress/Pytest)")
 
     def check_node_allure(self):
         found_node, node_ver = self.run_command("node -v")
@@ -181,7 +212,9 @@ class DiagnosticRunner:
             required_dirs = [".agents/skills", ".agents/rules", "tools", "tests"]
             missing = [rd for rd in required_dirs if not (self.target_dir / rd).exists()]
             if not missing:
-                self.log_check("Project Structure (QA Hub)", "PASS", "QA Hub integrity verified (27 Skills, Rules, Tools, Unit Tests)")
+                skills_dir = self.target_dir / ".agents" / "skills"
+                skill_count = len([d for d in skills_dir.iterdir() if d.is_dir() and not d.name.startswith(".")]) if skills_dir.exists() else 0
+                self.log_check("Project Structure (QA Hub)", "PASS", f"QA Hub integrity verified ({skill_count} Skills, Rules, Tools, Unit Tests)")
             else:
                 self.log_check("Project Structure (QA Hub)", "FAIL", f"Missing directories: {', '.join(missing)}",
                                "Restore from official agent-skills Git repository.")
@@ -225,9 +258,16 @@ class DiagnosticRunner:
             return
         test_url = f"{base}/login"
         try:
+            # Respect explicit insecure flag or environment variable; default to secure TLS
+            allow_insecure = bool(
+                getattr(self, "insecure", False)
+                or os.environ.get("SYNAPSE_INSECURE_SSL") == "1"
+            )
             ctx = ssl.create_default_context()
-            ctx.check_hostname = False
-            ctx.verify_mode = ssl.CERT_NONE
+            if allow_insecure:
+                print("  ⚠️ [SECURITY NOTICE] TLS certificate verification is bypassed (--insecure / SYNAPSE_INSECURE_SSL).")
+                ctx.check_hostname = False
+                ctx.verify_mode = ssl.CERT_NONE
 
             req = urllib.request.Request(test_url, headers={'User-Agent': 'Mozilla/5.0'})
             with urllib.request.urlopen(req, timeout=8, context=ctx) as resp:
@@ -272,6 +312,7 @@ def main():
     parser = argparse.ArgumentParser(description="Enterprise Environment Diagnostic Tool")
     parser.add_argument("target", nargs="?", default=None, help="Target repository path to diagnose")
     parser.add_argument("--repo", "--path", dest="repo_path", default=None, help="Target repository path")
+    parser.add_argument("--insecure", action="store_true", help="Allow unverified SSL certificates during connectivity checks")
     args = parser.parse_args()
 
     try:
@@ -280,7 +321,7 @@ def main():
         print(f"❌ Error: {e}")
         return 1
 
-    runner = DiagnosticRunner(target_dir=target_dir)
+    runner = DiagnosticRunner(target_dir=target_dir, insecure=args.insecure)
     return runner.run_all()