synapse-hub 2.7.0 → 3.0.1

package/tools/api_fuzzer.py

@@ -24,7 +24,7 @@ import urllib.request
 import urllib.error
 import urllib.parse
 import argparse
-from typing import Dict, Any, List, Optional, Tuple
+from typing import Dict, Any, List, Optional
 
 # Enforce UTF-8 stdout encoding for Windows/macOS/Linux compatibility
 if hasattr(sys.stdout, 'reconfigure'):
@@ -578,13 +578,13 @@ class ApiFuzzer:
             print(f"  Verdict           : {GREEN}[PASS] API resilient against input fuzzing & chaos.{RESET}")
         else:
             print(f"  Verdict           : {RED}[FAIL] {total_failures} defect alarms detected. Backend fixes required!{RESET}")
-        print(f"======================================================================\n")
+        print("======================================================================\n")
 
         # Save Report
         os.makedirs(REPORTS_DIR, exist_ok=True)
         report_path = os.path.join(REPORTS_DIR, "api_fuzz_report.json")
-        with open(report_path, "w", encoding="utf-8") as f:
-            json.dump(scorecard, f, indent=2)
+        with open(report_path, "w", encoding="utf-8") as out_file:
+            json.dump(scorecard, out_file, indent=2)
         print(f"Full telemetry report saved to: {report_path}")
 
         return scorecard
@@ -622,7 +622,7 @@ class ApiFuzzer:
                 if not is_protected and method.lower() in ("post", "put", "patch", "delete"):
                     severity = "HIGH" if re.search(r"admin|internal|user", path, re.IGNORECASE) else "MEDIUM"
                     findings.append({
-                        "finding": f"AUTH_NOT_DECLARED: Mutating endpoint declares no security requirement",
+                        "finding": "AUTH_NOT_DECLARED: Mutating endpoint declares no security requirement",
                         "severity": severity,
                         "target": label,
                         "recommendation": "Declare securitySchemes/security for this operation or document why it is public.",
@@ -678,7 +678,7 @@ class ApiFuzzer:
             print(f"  Verdict            : {RED}[FAIL] {blocking} HIGH/CRITICAL pre-flight finding(s).{RESET}")
         else:
             print(f"  Verdict            : {GREEN}[PASS] No HIGH/CRITICAL spec-level finding.{RESET}")
-        print(f"======================================================================\n")
+        print("======================================================================\n")
         for f in findings:
             print(f"  - [{f['severity']}] {f['target']} - {f['finding']}")
             print(f"      👉 {f['recommendation']}")
@@ -694,8 +694,8 @@ class ApiFuzzer:
             "severity_summary": severity_summary,
             "findings": findings,
         }
-        with open(report_path, "w", encoding="utf-8") as f:
-            json.dump(scorecard, f, indent=2)
+        with open(report_path, "w", encoding="utf-8") as out_file:
+            json.dump(scorecard, out_file, indent=2)
         print(f"\nFull telemetry report saved to: {report_path}")
 
         return scorecard

package/tools/auto_heal.py

@@ -2,7 +2,7 @@
 """
 Enterprise Closed-Loop Autonomous Test Healer Engine
 -----------------------------------------------------
-Diagnoses test failures in 0.1s from JUnit XML and terminal logs, queries the 
+Diagnoses test failures in 0.1s from JUnit XML and terminal logs, queries the
 semantic memory cache for proven patches, and orchestrates targeted re-tests.
 Dispatched automatically by AI Agents when test runs encounter failures.
 """
@@ -12,7 +12,6 @@ import sys
 import re
 import json
 import argparse
-from pathlib import Path
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
 if hasattr(sys.stdout, 'reconfigure'):
@@ -103,7 +102,7 @@ def diagnose_and_plan_heal(target_dir, junit_xml_path=None):
         "heuristic_match": None,
         "recommended_patch": None,
         "verbal_reflection": None,
-        "episodic_lessons": [l["lesson_summary"] for l in lessons]
+        "episodic_lessons": [les["lesson_summary"] for les in lessons]
     }
 
     # 2b. Reflexion Verbal Diagnosis
@@ -113,8 +112,8 @@ def diagnose_and_plan_heal(target_dir, junit_xml_path=None):
 
     if lessons:
         print(f"  {CYAN}🧠 [EPISODIC REFLEXION] Top Historical Lessons for Context:{RESET}")
-        for idx, l in enumerate(lessons, 1):
-            print(f"     {idx}. [{l['page_context']}]: {l['lesson_summary']}")
+        for idx, les in enumerate(lessons, 1):
+            print(f"     {idx}. [{les['page_context']}]: {les['lesson_summary']}")
     print(f"  {CYAN}💡 [REFLEXION DIAGNOSIS] {verbal_reflection}{RESET}")
 
     if cache_solution:

package/tools/auto_heal_reflexion.py

@@ -24,8 +24,8 @@ import os
 import sys
 import json
 import argparse
-from dataclasses import dataclass, asdict
-from typing import List, Optional, Callable, Dict, Any, Tuple
+from dataclasses import dataclass
+from typing import List, Optional, Callable, Tuple
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
 if hasattr(sys.stdout, 'reconfigure'):
@@ -67,6 +67,14 @@ class ClosedLoopHealer:
             return "Reflection: DOM node re-rendered asynchronously after API call. Adjustment: Must wait for loader/backdrop detachment before re-querying element."
         elif "intercepted" in err_lower or "click" in err_lower:
             return "Reflection: Click intercepted by fading overlay/spinner animation. Adjustment: Use smart wait for overlay detachment or bypass via safe JS click."
+        elif "hydration" in err_lower or "did not match" in err_lower:
+            return "Reflection: React/Next.js hydration mismatch caused DOM element to re-render. Adjustment: Ensure DOM is interactive and wait for loadState('domcontentloaded') before query."
+        elif "shadow" in err_lower or "shadowroot" in err_lower:
+            return "Reflection: Target element encapsulated inside closed Shadow DOM boundary. Adjustment: Pierce Shadow DOM via locator piercing syntax or evaluate via CDP."
+        elif "iframe" in err_lower or "frame" in err_lower:
+            return "Reflection: Target element resides inside cross-origin iframe container. Adjustment: Switch context to frameLocator('iframe#...') before clicking."
+        elif any(auth_err in err_lower for auth_err in ("401", "403", "unauthorized", "forbidden", "token expired")):
+            return "Reflection: Session auth token or cookie expired mid-test. Adjustment: Refresh storageState or trigger silent token re-authentication via API fixture."
         elif "timeout" in err_lower or "nosuchelement" in err_lower:
             return "Reflection: Static selector did not appear within timeout window. Adjustment: Fallback to Accessibility role/label or dynamic data-testid attribute."
         elif "assert" in err_lower:

package/tools/autogen_qa_broker.py

@@ -25,7 +25,7 @@ import json
 import time
 import argparse
 from datetime import datetime, timezone
-from typing import Dict, Any, List, Optional, Tuple
+from typing import Dict, Any, List, Optional
 
 # Enforce UTF-8 stdout encoding
 if hasattr(sys.stdout, 'reconfigure'):
@@ -174,7 +174,7 @@ class ActorQaBroker:
                     if isinstance(data, list):
                         test_items = data
                     elif isinstance(data, dict):
-                        test_items = data.get("tests", data.get("test_cases", []))
+                        test_items = data.get("tests") or data.get("test_cases") or []
             except Exception as e:
                 sys.stderr.write(f"Notice: Could not parse manifest ({e}), using default mock items.\n")
 

package/tools/browser_helpers.js

@@ -13,7 +13,7 @@
 (function () {
   'use strict';
 
-  if (window.__qa && window.__qa.__version === '2.7.0') {
+  if (window.__qa && window.__qa.__version === '3.0.1') {
     return window.__qa;
   }
 
@@ -47,7 +47,7 @@
   }
 
   const qa = {
-    __version: '2.7.0',
+    __version: '3.0.1',
 
     /**
      * 1. Smart Action Batching

package/tools/browsergym_eval.py

@@ -22,9 +22,8 @@ import sys
 import re
 import json
 import time
-import ast
 import argparse
-from typing import Dict, Any, List, Optional, Tuple
+from typing import Dict, Any, List, Optional
 
 # Enforce UTF-8 stdout encoding
 if hasattr(sys.stdout, 'reconfigure'):
@@ -35,7 +34,7 @@ if hasattr(sys.stdout, 'reconfigure'):
         pass
 
 
-DEFAULT_BENCHMARK_TASKS = {
+DEFAULT_BENCHMARK_TASKS: Dict[str, Any] = {
     "ecommerce_order": {
         "name": "E-Commerce Checkout & Order Generation",
         "steps": [

package/tools/bug_reporter.py

@@ -9,11 +9,9 @@ reproduction steps, distills stacktraces (0 noise), and attaches evidence.
 """
 
 import os
-import re
-import sys
 import json
 import argparse
-from typing import Dict, List, Optional, Any
+from typing import Dict, List, Optional
 from datetime import datetime
 
 try:
@@ -22,8 +20,8 @@ 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]}"
+        def compute_error_fingerprint(error_type: str, error_msg: str, stack_anchor: str = "") -> str:
+            raw = f"{(error_type or '').strip().lower()}:{(error_msg or '').strip()[:200]}"
             h = 5381
             for b in raw.encode("utf-8", errors="ignore"):
                 h = (((h << 5) + h) + b) & 0xFFFFFFFF
@@ -90,13 +88,13 @@ class BugReporter:
     @staticmethod
     def distill_stack_trace(raw_stack: str, max_lines: int = 5) -> str:
         """Filters noisy framework stack trace down to actionable lines."""
-        lines = [l.strip() for l in raw_stack.splitlines() if l.strip()]
+        lines = [line.strip() for line in raw_stack.splitlines() if line.strip()]
         actionable = []
-        for l in lines:
+        for line in lines:
             # Filter standard framework internals
-            if any(internal in l for internal in ["at Module.", "node_modules", "org.gradle", "sun.reflect", "jdk.internal"]):
+            if any(internal in line for internal in ["at Module.", "node_modules", "org.gradle", "sun.reflect", "jdk.internal"]):
                 continue
-            actionable.append(l)
+            actionable.append(line)
             if len(actionable) >= max_lines:
                 break
         return "\n".join(actionable) if actionable else raw_stack[:300]
@@ -121,7 +119,7 @@ class BugReporter:
         fingerprint = compute_error_fingerprint(rca["type"], error_message, anchor)
 
         steps = steps_executed or [
-            f"1. Navigate to target application under test",
+            "1. Navigate to target application under test",
             f"2. Execute test workflow for {test_title}",
             f"3. Trigger operation causing failure: {error_message[:80]}"
         ]
@@ -144,7 +142,7 @@ class BugReporter:
             report = [
                 f"h2. [BUG][{rca['severity'].upper()}] {test_id}: {test_title} - {error_message[:90]}",
                 "",
-                f"* *Issue Type:* Bug",
+                "* *Issue Type:* Bug",
                 f"* *Error Fingerprint:* {fingerprint}",
                 f"* *Root Cause Category:* {rca['label']}",
                 f"* *Severity / Priority:* {rca['severity']}",
@@ -160,7 +158,7 @@ class BugReporter:
             report.extend([
                 "",
                 "h3. 2. Expected Result",
-                f"Operation completes successfully without errors, assertions pass.",
+                "Operation completes successfully without errors, assertions pass.",
                 "",
                 "h3. 3. Actual Result",
                 f"{{color:red}}*Failure:* {error_message}{{color}}",
@@ -199,7 +197,7 @@ class BugReporter:
             "Application executes workflow smoothly and passes all validations.",
             "",
             "## ❌ 3. Actual Result",
-            f"**Error Encountered:**",
+            "**Error Encountered:**",
             f"```text\n{error_message}\n```",
             "",
             "## 🔍 4. Distilled Stack Trace (0-Noise)",

package/tools/bump_version.py

@@ -42,12 +42,32 @@ if hasattr(sys.stdout, 'reconfigure'):
 REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 
 def parse_semver(v_str: str):
+    """Parses a semantic version string into major, minor, patch integers and optional suffix.
+
+    Args:
+        v_str: The version string to parse (e.g. '2.9.0' or '2.9.0-rc1').
+
+    Returns:
+        A tuple of (major, minor, patch, suffix).
+
+    Raises:
+        ValueError: If the string does not follow semantic versioning.
+    """
     m = re.match(r"^(\d+)\.(\d+)\.(\d+)(.*)$", v_str.strip())
     if not m:
         raise ValueError(f"Invalid semver: '{v_str}'. Must follow major.minor.patch[-suffix]")
     return int(m.group(1)), int(m.group(2)), int(m.group(3)), m.group(4)
 
 def calculate_next_version(current: str, action: str) -> str:
+    """Computes the target version based on an action or explicit semver string.
+
+    Args:
+        current: Current semver version string.
+        action: 'patch', 'minor', 'major', or an explicit target version string.
+
+    Returns:
+        The computed next semver version string.
+    """
     major, minor, patch, suffix = parse_semver(current)
     action = action.lower()
     if action == "patch":
@@ -62,6 +82,14 @@ def calculate_next_version(current: str, action: str) -> str:
         return action
 
 def get_current_version() -> str:
+    """Reads the current canonical version from package.json in the repository root.
+
+    Returns:
+        The version string.
+
+    Raises:
+        ValueError: If package.json is missing or lacks a valid version field.
+    """
     pkg_file = os.path.join(REPO_ROOT, "package.json")
     with open(pkg_file, "r", encoding="utf-8") as f:
         data = json.load(f)
@@ -71,6 +99,16 @@ def get_current_version() -> str:
     return version
 
 def update_json_root_version(rel_path: str, new_ver: str, dry_run: bool = False) -> bool:
+    """Updates the top-level 'version' property in a JSON manifest file.
+
+    Args:
+        rel_path: Relative path to the target JSON file from repo root.
+        new_ver: Target version string.
+        dry_run: If True, previews changes without writing to disk.
+
+    Returns:
+        True if the file was modified or would be updated.
+    """
     full_path = os.path.join(REPO_ROOT, rel_path)
     if not os.path.exists(full_path):
         print(f"  [WARN] File not found: {rel_path}")
@@ -95,6 +133,17 @@ def update_json_root_version(rel_path: str, new_ver: str, dry_run: bool = False)
     return True
 
 def update_file(rel_path: str, pattern: str, replacement: str, dry_run: bool = False) -> bool:
+    """Performs regex replacement within a target file to update version strings.
+
+    Args:
+        rel_path: Relative path to the target file from repo root.
+        pattern: Regular expression pattern matching existing version occurrences.
+        replacement: String replacement containing the new version.
+        dry_run: If True, previews changes without writing to disk.
+
+    Returns:
+        True if matches were found and updated.
+    """
     full_path = os.path.join(REPO_ROOT, rel_path)
     if not os.path.exists(full_path):
         print(f"  [WARN] File not found: {rel_path}")
@@ -117,6 +166,11 @@ def update_file(rel_path: str, pattern: str, replacement: str, dry_run: bool = F
     return True
 
 def run_tests() -> bool:
+    """Executes the test suite and 10 DoD Quality Gates before release.
+
+    Returns:
+        True if all tests and gates pass.
+    """
     print("\n🔍 Running verification suite...")
     cmd = [sys.executable, "-m", "unittest", "discover", "tests", "-p", "test_*.py"]
     res = subprocess.run(cmd, cwd=REPO_ROOT)
@@ -130,33 +184,40 @@ def run_tests() -> bool:
     if res_verify.returncode != 0:
         print("❌ Quality Gates failed! Aborting release.")
         return False
-    print("✅ 9 Quality Gates DoD PASSED.")
+    print("✅ 10 Quality Gates DoD PASSED.")
     return True
 
 def git_commit_and_tag(version: str, push: bool = False):
+    """Creates a conventional Git release commit and tags the repository.
+
+    Args:
+        version: Target version string.
+        push: If True, pushes the commit and tag to git remote origin.
+    """
     print(f"\n📦 Creating Git commit and tag v{version}...")
-    subprocess.run(["git", "add", "-A"], cwd=REPO_ROOT, check=True)
-    subprocess.run(["git", "commit", "-m", f"chore(release): bump version to v{version}"], cwd=REPO_ROOT, check=True)
-    subprocess.run(["git", "tag", f"v{version}"], cwd=REPO_ROOT, check=True)
+    subprocess.run(["git", "add", "-u"], cwd=REPO_ROOT, check=True, timeout=30.0)
+    subprocess.run(["git", "commit", "-m", f"chore(release): bump version to v{version}"], cwd=REPO_ROOT, check=True, timeout=30.0)
+    subprocess.run(["git", "tag", f"v{version}"], cwd=REPO_ROOT, check=True, timeout=30.0)
     print(f"✅ Git commit and tag v{version} created.")
 
     if push:
-        print(f"🚀 Pushing commit and tags to remote origin...")
-        res = subprocess.run(["git", "branch", "--show-current"], cwd=REPO_ROOT, stdout=subprocess.PIPE, text=True)
+        print("🚀 Pushing commit and tags to remote origin...")
+        res = subprocess.run(["git", "branch", "--show-current"], cwd=REPO_ROOT, stdout=subprocess.PIPE, text=True, timeout=30.0)
         cur_branch = res.stdout.strip()
         if cur_branch == "develop":
             try:
-                subprocess.run(["git", "checkout", "main"], cwd=REPO_ROOT, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
-                subprocess.run(["git", "merge", "develop", "--ff-only"], cwd=REPO_ROOT, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
-                subprocess.run(["git", "checkout", "develop"], cwd=REPO_ROOT, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
-                subprocess.run(["git", "push", "origin", "develop", "main", "--tags"], cwd=REPO_ROOT, check=True)
+                subprocess.run(["git", "checkout", "main"], cwd=REPO_ROOT, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=30.0)
+                subprocess.run(["git", "merge", "develop", "--ff-only"], cwd=REPO_ROOT, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=30.0)
+                subprocess.run(["git", "checkout", "develop"], cwd=REPO_ROOT, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=30.0)
+                subprocess.run(["git", "push", "origin", "develop", "main", "--tags"], cwd=REPO_ROOT, check=True, timeout=60.0)
             except Exception:
-                subprocess.run(["git", "push", "origin", "HEAD", "--tags"], cwd=REPO_ROOT, check=True)
+                subprocess.run(["git", "push", "origin", "HEAD", "--tags"], cwd=REPO_ROOT, check=True, timeout=60.0)
         else:
-            subprocess.run(["git", "push", "origin", "HEAD", "--tags"], cwd=REPO_ROOT, check=True)
-        print(f"✅ Remote origin synchronized.")
+            subprocess.run(["git", "push", "origin", "HEAD", "--tags"], cwd=REPO_ROOT, check=True, timeout=60.0)
+        print("✅ Remote origin synchronized.")
 
 def main():
+    """CLI entrypoint for bumping Synapse Hub version synchronously across manifests."""
     parser = argparse.ArgumentParser(description="Atomic Universal Version Bumper for Synapse Hub")
     parser.add_argument("action", nargs="?", default="patch", help="patch | minor | major | <explicit_version> (default: patch)")
     parser.add_argument("--dry-run", action="store_true", help="Preview version changes without writing files")
@@ -210,15 +271,25 @@ def main():
     update_file("tools/mcp_excel_server.py", r'(SERVER_VERSION\s*=\s*")[^"]+(")', rf"\g<1>{new_ver}\g<2>", args.dry_run)
     update_file("tools/mcp_excel_server.py", r'("serverInfo":\s*\{[^}]*"version":\s*")[^"]+(")', rf"\g<1>{new_ver}\g<2>", args.dry_run)
 
-    # 8. docs/ARCHITECTURE.md
+    # 8. docs/ARCHITECTURE.md & docs/ARCHITECTURE.en.md
     update_file("docs/ARCHITECTURE.md", r'(>\s*\*\*Version:\*\*\s*`)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
+    update_file("docs/ARCHITECTURE.en.md", r'(>\s*\*\*Version:\*\*\s*`)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
 
     # 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'(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.md", r'(rev:\s*v)[0-9]+\.[0-9]+\.[0-9]+', rf"\g<1>{new_ver}", args.dry_run)
+    update_file("README.md", r'(Synapse Hub \(Core v)[0-9]+\.[0-9]+\.[0-9]+(\))', rf"\g<1>{new_ver}\g<2>", 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)
+    update_file("README.en.md", r'(rev:\s*v)[0-9]+\.[0-9]+\.[0-9]+', rf"\g<1>{new_ver}", args.dry_run)
+    update_file("README.en.md", r'(Synapse Hub \(Core v)[0-9]+\.[0-9]+\.[0-9]+(\))', rf"\g<1>{new_ver}\g<2>", args.dry_run)
+
+    # 9b. SECURITY.md
+    major, minor, _, _ = parse_semver(new_ver)
+    current_branch = f"{major}.{minor}.x"
+    update_file("SECURITY.md", r'(\|\s*`)[0-9]+\.[0-9]+\.x(`\s*\|\s*✅)', rf"\g<1>{current_branch}\g<2>", 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)
@@ -267,8 +338,8 @@ def main():
     print(f"🎉 VERSION BUMP COMPLETE: v{current_ver} ➔ v{new_ver}")
     print("======================================================================")
     print("Next steps:")
-    print(f"  • Publish to NPM : npm publish")
-    print(f"  • Or Git Push    : git push origin HEAD --tags")
+    print("  • Publish to NPM : npm publish")
+    print("  • Or Git Push    : git push origin HEAD --tags")
     print("======================================================================")
 
 if __name__ == "__main__":