synapse-hub 2.2.4 → 2.4.0

package/tools/db_sandbox.py

@@ -11,19 +11,29 @@ Features:
   2. Ephemeral Snapshot & Rapid Restore (< 0.5s):
      - Takes snapshot of database state before test suite execution.
      - Restores pristine clean state immediately after test completion.
-     - Supports SQLite, PostgreSQL schema isolation, MySQL, and Docker/Testcontainers hooks.
+     - SQLite implemented natively; other engines via file-copy hooks. Boot
+       containers with external `docker`/Testcontainers, then gate readiness
+       with the `wait-ready` command (see Wait Strategies below).
   3. Taint Pollution Auditor:
      - Automatically detects orphan rows created during test sessions and performs
        dependency-aware cascading cleanup.
+  4. Container Readiness Wait Strategies (`wait-ready`):
+     - port / http / sqlite probes with deadline + backoff, so CI never races
+       a not-yet-ready database (concept borrowed from the Testcontainers
+       WaitStrategy taxonomy, Apache-2.0, re-implemented stdlib-only).
 """
 
 import os
+import re
 import sys
 import time
 import json
 import shutil
+import socket
 import sqlite3
 import argparse
+import urllib.request
+import urllib.error
 from typing import Dict, Any, List, Optional, Tuple
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
@@ -51,13 +61,24 @@ class DBSandbox:
     # -------------------------------------------------------------------------
     # 1. SNAPSHOT & RAPID RESTORE
     # -------------------------------------------------------------------------
+    def _resolve_safe_snapshot_paths(self, snapshot_id: str) -> Tuple[str, str, str]:
+        """Sanitizes snapshot_id and ensures target paths remain inside self.snapshot_dir."""
+        clean_id = re.sub(r'[^a-zA-Z0-9_\-]', '', snapshot_id.strip())
+        if not clean_id:
+            clean_id = "pristine_baseline"
+        base_dir = os.path.abspath(self.snapshot_dir)
+        snap_path = os.path.abspath(os.path.join(base_dir, f"{clean_id}.db"))
+        meta_path = os.path.abspath(os.path.join(base_dir, f"{clean_id}_meta.json"))
+        if not snap_path.startswith(base_dir + os.sep) or not meta_path.startswith(base_dir + os.sep):
+            raise ValueError(f"Path traversal detected in snapshot_id: '{snapshot_id}'")
+        return clean_id, snap_path, meta_path
+
     def create_snapshot(self, snapshot_id: str = "pristine_baseline") -> Dict[str, Any]:
         """
         Creates an instantaneous pristine snapshot of the database state.
         """
         start_time = time.perf_counter()
-        snapshot_file = os.path.join(self.snapshot_dir, f"{snapshot_id}.db")
-        meta_file = os.path.join(self.snapshot_dir, f"{snapshot_id}_meta.json")
+        clean_id, snapshot_file, meta_file = self._resolve_safe_snapshot_paths(snapshot_id)
 
         if self.db_type == "sqlite":
             if not self.db_path:
@@ -86,7 +107,7 @@ class DBSandbox:
         elapsed = round(time.perf_counter() - start_time, 4)
 
         metadata = {
-            "snapshot_id": snapshot_id,
+            "snapshot_id": clean_id,
             "db_type": self.db_type,
             "source_db": self.db_path,
             "snapshot_path": snapshot_file,
@@ -104,17 +125,19 @@ class DBSandbox:
         Restores database to pristine baseline, wiping 100% of test data junk.
         """
         start_time = time.perf_counter()
-        snapshot_file = os.path.join(self.snapshot_dir, f"{snapshot_id}.db")
+        try:
+            clean_id, snapshot_file, meta_file = self._resolve_safe_snapshot_paths(snapshot_id)
+        except ValueError as e:
+            return {"status": "ERROR", "message": str(e)}
 
         if not os.path.exists(snapshot_file):
             return {
                 "status": "ERROR",
-                "message": f"Snapshot '{snapshot_id}' does not exist at {snapshot_file}"
+                "message": f"Snapshot '{clean_id}' does not exist at {snapshot_file}"
             }
 
         # Resolve target db path if not explicitly provided
         if not self.db_path:
-            meta_file = os.path.join(self.snapshot_dir, f"{snapshot_id}_meta.json")
             if os.path.exists(meta_file):
                 try:
                     with open(meta_file, "r", encoding="utf-8") as f:
@@ -137,7 +160,7 @@ class DBSandbox:
         elapsed = round(time.perf_counter() - start_time, 4)
         return {
             "status": "RESTORED",
-            "snapshot_id": snapshot_id,
+            "snapshot_id": clean_id,
             "target_db": self.db_path,
             "restore_duration_sec": elapsed,
             "zero_pollution_guaranteed": True
@@ -200,9 +223,20 @@ class DBSandbox:
     # -------------------------------------------------------------------------
     # 3. TAINT POLLUTION AUDIT & PURGE
     # -------------------------------------------------------------------------
-    def audit_and_purge_pollution(self, known_test_prefixes: Tuple[str, ...] = ("AUTO_", "TEST_", "TEMP_")) -> Dict[str, Any]:
+    @staticmethod
+    def _escape_sql_like(prefix: str) -> str:
+        """Escapes SQL LIKE wildcard characters (_, %) so prefix is matched literally."""
+        return prefix.replace('\\', '\\\\').replace('%', '\\%').replace('_', '\\_')
+
+    def audit_and_purge_pollution(
+        self,
+        known_test_prefixes: Tuple[str, ...] = ("AUTO_", "TEST_", "TEMP_"),
+        dry_run: bool = False
+    ) -> Dict[str, Any]:
         """
         Scans all tables for orphan records carrying test prefixes and purges them.
+        Properly escapes SQL LIKE wildcards ('_' and '%') with an explicit ESCAPE clause
+        to avoid deleting real business data (e.g. 'Automotive', 'Tester', 'Tempest').
         """
         if not self.db_path:
             candidate = os.path.join(self.snapshot_dir, "active_test.db")
@@ -228,32 +262,151 @@ class DBSandbox:
         purge_log = []
 
         for table in tables:
-            cursor.execute(f"PRAGMA table_info({table});")
+            # Validate table identifier to protect against injection
+            if not re.match(r'^[a-zA-Z0-9_]+$', table):
+                continue
+            cursor.execute(f"PRAGMA table_info([{table}]);")
             columns = [c[1] for c in cursor.fetchall()]
 
             # Look for code or name columns
-            target_cols = [c for c in columns if c.lower() in ("code", "username", "name", "email", "status")]
+            target_cols = [c for c in columns if c.lower() in ("code", "username", "name", "email", "status") and re.match(r'^[a-zA-Z0-9_]+$', c)]
             for col in target_cols:
                 for prefix in known_test_prefixes:
-                    cursor.execute(f"SELECT COUNT(*) FROM {table} WHERE {col} LIKE '{prefix}%'")
+                    escaped_pattern = self._escape_sql_like(prefix) + "%"
+                    cursor.execute(
+                        f"SELECT COUNT(*) FROM [{table}] WHERE [{col}] LIKE ? ESCAPE '\\'",
+                        (escaped_pattern,)
+                    )
                     c_count = cursor.fetchone()[0]
                     if c_count > 0:
-                        cursor.execute(f"DELETE FROM {table} WHERE {col} LIKE '{prefix}%'")
+                        if not dry_run:
+                            cursor.execute(
+                                f"DELETE FROM [{table}] WHERE [{col}] LIKE ? ESCAPE '\\'",
+                                (escaped_pattern,)
+                            )
                         total_purged += c_count
-                        purge_log.append(f"Table '{table}' ({col}): deleted {c_count} rows matching '{prefix}%'")
+                        action_str = "previewed" if dry_run else "deleted"
+                        purge_log.append(f"Table '{table}' ({col}): {action_str} {c_count} rows matching literal prefix '{prefix}'")
 
-        conn.commit()
+        if not dry_run:
+            conn.commit()
         conn.close()
 
         return {
-            "status": "CLEAN",
+            "status": "CLEAN" if not dry_run else "DRY_RUN",
             "tables_audited": len(tables),
             "total_purged_rows": total_purged,
             "purge_details": purge_log,
-            "zero_pollution_achieved": True
+            "zero_pollution_achieved": True,
+            "dry_run": dry_run
         }
 
 
+# -------------------------------------------------------------------------
+# 4. CONTAINER READINESS WAIT STRATEGIES
+#    (Concept borrowed from the Testcontainers WaitStrategy taxonomy,
+#     Apache-2.0 - re-implemented stdlib-only. Boot the container with
+#     external `docker`/Testcontainers, then gate on readiness here.)
+# -------------------------------------------------------------------------
+
+def _probe_sqlite(target: str) -> Tuple[bool, str]:
+    """Ready when the SQLite file opens read-only and answers a pragma."""
+    try:
+        conn = sqlite3.connect(f"file:{target}?mode=ro", uri=True, timeout=2.0)
+        try:
+            conn.execute("PRAGMA schema_version").fetchone()
+        finally:
+            conn.close()
+        return True, "sqlite pragma answered"
+    except sqlite3.Error as exc:
+        return False, f"sqlite probe failed: {exc}"
+
+
+def _probe_port(target: str) -> Tuple[bool, str]:
+    """Ready when a TCP connection to host:port succeeds."""
+    m = re.match(r"^(?:[\w.\-]+://)?([\w.\-]+):(\d+)$", target)
+    if not m:
+        return False, f"invalid host:port target '{target}'"
+    host, port = m.group(1), int(m.group(2))
+    try:
+        with socket.create_connection((host, port), timeout=2.0):
+            return True, f"tcp {host}:{port} accepted"
+    except OSError as exc:
+        return False, f"tcp {host}:{port} refused: {exc}"
+
+
+def _probe_http(target: str) -> Tuple[bool, str]:
+    """Ready when the endpoint answers with any non-5xx status (an auth wall
+    such as 401/403 still proves the service is up)."""
+    try:
+        req = urllib.request.Request(target, method="GET")
+        with urllib.request.urlopen(req, timeout=2.0) as resp:
+            return True, f"http {resp.getcode()}"
+    except urllib.error.HTTPError as exc:
+        if exc.code < 500:
+            return True, f"http {exc.code} (service reachable)"
+        return False, f"http {exc.code} server error"
+    except (urllib.error.URLError, OSError) as exc:
+        return False, f"http probe failed: {exc}"
+
+
+def infer_wait_strategy(target: str) -> str:
+    """Auto-detects the wait strategy from the target shape."""
+    lowered = target.lower()
+    if lowered.startswith("http://") or lowered.startswith("https://"):
+        return "http"
+    if lowered.endswith((".db", ".sqlite", ".sqlite3")) or os.path.exists(target):
+        return "sqlite"
+    if re.match(r"^[\w.\-]+:\d+$", target):
+        return "port"
+    return "port"
+
+
+def wait_for_ready(target: str, strategy: str = "auto", timeout_sec: float = 30.0) -> Dict[str, Any]:
+    """Polls a readiness probe until it succeeds or the deadline expires.
+
+    Returns a structured result; exit codes are enforced by the CLI
+    (0 = ready, 1 = timeout) so CI pipelines can gate on database health
+    before dispatching suites.
+    """
+    if strategy == "auto":
+        strategy = infer_wait_strategy(target)
+    probes = {"sqlite": _probe_sqlite, "port": _probe_port, "http": _probe_http}
+    probe = probes.get(strategy)
+    if probe is None:
+        return {"target": target, "strategy": strategy, "ready": False,
+                "elapsed_ms": 0, "attempts": 0, "error": f"unknown strategy '{strategy}'"}
+
+    start = time.perf_counter()
+    attempts = 0
+    backoff = 0.25
+    last_error = ""
+    while time.perf_counter() - start < timeout_sec:
+        attempts += 1
+        ok, detail = probe(target)
+        if ok:
+            return {
+                "target": target,
+                "strategy": strategy,
+                "ready": True,
+                "elapsed_ms": round((time.perf_counter() - start) * 1000, 1),
+                "attempts": attempts,
+                "error": None,
+            }
+        last_error = detail
+        time.sleep(backoff)
+        backoff = min(backoff * 2, 2.0)
+
+    return {
+        "target": target,
+        "strategy": strategy,
+        "ready": False,
+        "elapsed_ms": round((time.perf_counter() - start) * 1000, 1),
+        "attempts": attempts,
+        "error": last_error or "timeout expired before readiness",
+    }
+
+
 def main():
     parser = argparse.ArgumentParser(description="Zero-Pollution Database Sandbox & Ephemeral Teardown")
     subparsers = parser.add_subparsers(dest="command", help="Sandbox command")
@@ -279,10 +432,33 @@ def main():
     # Command: audit
     aud_p = subparsers.add_parser("audit", help="Audit orphan test junk and purge")
     aud_p.add_argument("--db-path", default="", help="Path to database file")
+    aud_p.add_argument("--dry-run", action="store_true", help="Preview test records to purge without deleting")
     aud_p.add_argument("--json", action="store_true", help="Output JSON format")
 
+    # Command: wait-ready (Testcontainers-style readiness gate)
+    wait_p = subparsers.add_parser("wait-ready", help="Wait until a database/container is ready (port|http|sqlite probe)")
+    wait_p.add_argument("target", help="URL (http(s)://), host:port, or SQLite file path")
+    wait_p.add_argument("--strategy", choices=["auto", "port", "http", "sqlite"], default="auto",
+                        help="Readiness probe strategy (default: auto-detect)")
+    wait_p.add_argument("--timeout", type=float, default=30.0, help="Deadline in seconds (default: 30)")
+    wait_p.add_argument("--json", action="store_true", help="Output JSON format")
+
     args = parser.parse_args()
 
+    if args.command == "wait-ready":
+        res = wait_for_ready(args.target, strategy=args.strategy, timeout_sec=args.timeout)
+        if args.json:
+            print(json.dumps(res, indent=2))
+        else:
+            if res["ready"]:
+                print(f"✅ [READY] {res['target']} via {res['strategy']} probe "
+                      f"({res['elapsed_ms']}ms, {res['attempts']} attempt(s))")
+            else:
+                print(f"❌ [NOT READY] {res['target']} via {res['strategy']} probe "
+                      f"after {res['elapsed_ms']}ms / {res['attempts']} attempt(s)")
+                print(f"   Last error: {res['error']}")
+        return 0 if res["ready"] else 1
+
     sandbox = DBSandbox(db_path=args.db_path)
 
     if args.command == "snapshot":
@@ -322,14 +498,16 @@ def main():
         return 0
 
     elif args.command == "audit":
-        res = sandbox.audit_and_purge_pollution()
+        res = sandbox.audit_and_purge_pollution(dry_run=args.dry_run)
         if args.json:
             print(json.dumps(res, indent=2))
         else:
-            print(f"🧹 [TAINT POLLUTION AUDIT] Purged {res['total_purged_rows']} orphan test records.")
+            action_label = "Previewed" if args.dry_run else "Purged"
+            print(f"🧹 [TAINT POLLUTION AUDIT] {action_label} {res['total_purged_rows']} orphan test records.")
             for detail in res.get("purge_details", []):
                 print(f"   - {detail}")
-            print("   ✅ Zero Pollution Achieved.")
+            if not args.dry_run:
+                print("   ✅ Zero Pollution Achieved.")
         return 0
 
     else:

package/tools/e2e_flow_prober.ps1

@@ -1,65 +1,13 @@
-param(
-    [string]$Mode = "katalon" # "katalon" or "playwright"
-)
-
-Write-Host "==========================================================" -ForegroundColor Cyan
-Write-Host "   ENTERPRISE AUTOMATION - E2E FLOW PROBER & XPATH CRAWLER" -ForegroundColor Cyan
-Write-Host "==========================================================" -ForegroundColor Cyan
-
-$projectDir = Split-Path -Parent $PSScriptRoot
-
-if ($Mode -eq "playwright") {
-    $pythonCmd = Get-Command python -ErrorAction SilentlyContinue
-    if (-not $pythonCmd) { $pythonCmd = Get-Command py -ErrorAction SilentlyContinue }
-    if ($pythonCmd) {
-        Write-Host "[+] Khởi chạy crawler qua Playwright (real_e2e_runner.py)..." -ForegroundColor Green
-        & $pythonCmd "$projectDir\real_e2e_runner.py" --probe
-        exit 0
-    } else {
-        Write-Host "[!] Không tìm thấy Python trên máy host." -ForegroundColor Yellow
-        Write-Host "[+] Tự động chuyển sang chế độ Katalon Native Runner..." -ForegroundColor Cyan
-        $Mode = "katalon"
-    }
+# Enterprise Automation - E2E Flow Prober Wrapper
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$pythonCmd = Get-Command python -ErrorAction SilentlyContinue
+if (-not $pythonCmd) { $pythonCmd = Get-Command py -ErrorAction SilentlyContinue }
+if (-not $pythonCmd) { $pythonCmd = Get-Command python3 -ErrorAction SilentlyContinue }
+
+if ($pythonCmd) {
+    & $pythonCmd.Source "$scriptDir\e2e_flow_prober.py" $args
+    exit $LASTEXITCODE
+} else {
+    Write-Error "Python 3 is required to run e2e_flow_prober.py."
+    exit 1
 }
-
-if ($Mode -eq "katalon") {
-    Write-Host "[+] Khởi chạy crawler qua Katalon Native Test Suite (PROBE_E2E_Flow)..." -ForegroundColor Green
-    
-    $katalonExec = $null
-    $possiblePaths = @(
-        $env:KATALON_HOME,
-        "C:\Katalon_Studio_Engine\katalonc.exe",
-        "C:\Katalon_Studio\katalon.exe"
-    )
-    foreach ($p in $possiblePaths) {
-        if ($p -and (Test-Path $p)) {
-            $katalonExec = $p
-            break
-        }
-    }
-
-    if ($katalonExec) {
-        Write-Host "[+] Sử dụng Katalon Engine tại: $katalonExec" -ForegroundColor Cyan
-        $prjPath = "$projectDir\project.prj"
-        $suiteRelPath = "Test Suites/PROBE_E2E_Flow"
-        
-        $argsList = @(
-            "-noSplash",
-            "-runMode=console",
-            "-projectPath=`"$prjPath`"",
-            "-retry=0",
-            "-testSuitePath=`"$suiteRelPath`"",
-            "-browserType=`"Chrome`""
-        )
-        if ($env:KATALON_API_KEY) {
-            $argsList += "-apiKey=`"$($env:KATALON_API_KEY)`""
-        }
-        
-        & $katalonExec $argsList
-    } else {
-        Write-Host "`n[!] Để chạy bộ dò luồng tự động:" -ForegroundColor Yellow
-        Write-Host "    1. Mở Katalon Studio -> Open Project tại thư mục dự án này" -ForegroundColor White
-        Write-Host "    2. Chọn Test Suites -> 'PROBE_E2E_Flow' -> Bấm nút Run (Chrome)" -ForegroundColor White
-        Write-Host "    3. Hoặc chạy lệnh trong Docker: docker-compose up" -ForegroundColor White
-    }
-}

package/tools/e2e_flow_prober.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""
+Enterprise E2E Flow Prober & XPath Crawler Dispatcher (Cross-Platform)
+----------------------------------------------------------------------
+Dispatches autonomous flow probing across Katalon Studio and Playwright.
+Replaces PowerShell-only script with a zero-dependency, cross-platform engine.
+"""
+
+import os
+import sys
+import shutil
+import argparse
+import subprocess
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+PROJECT_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, ".."))
+
+
+def find_katalon_binary():
+    """Locates the katalonc binary across Windows, macOS, and Linux."""
+    from_path = shutil.which("katalonc") or shutil.which("katalon")
+    if from_path:
+        return from_path
+
+    env_home = os.environ.get("KATALON_HOME")
+    if env_home:
+        for candidate in ["katalonc", "katalonc.exe", "katalon", "katalon.exe"]:
+            p = os.path.join(env_home, candidate)
+            if os.path.isfile(p):
+                return p
+
+    standard_paths = [
+        "C:\\Katalon_Studio_Engine\\katalonc.exe",
+        "C:\\Katalon_Studio\\katalon.exe",
+        "/Applications/Katalon Studio Engine.app/Contents/MacOS/katalonc",
+        "/opt/katalon/katalonc",
+        "/opt/homebrew/bin/katalonc",
+    ]
+    for p in standard_paths:
+        if os.path.isfile(p):
+            return p
+    return None
+
+
+def run_prober(mode="playwright", suite_path="Test Suites/PROBE_E2E_Flow"):
+    """Dispatches flow prober according to selected mode."""
+    print("==========================================================")
+    print("   ENTERPRISE AUTOMATION - E2E FLOW PROBER & XPATH CRAWLER")
+    print("==========================================================")
+
+    if mode == "playwright":
+        runner_path = os.path.join(PROJECT_ROOT, "real_e2e_runner.py")
+        if os.path.exists(runner_path):
+            print(f"[+] Launching Playwright E2E Crawler ({runner_path})...")
+            return subprocess.run([sys.executable, runner_path, "--probe"]).returncode
+        else:
+            print("[!] real_e2e_runner.py not found in project root.")
+            print("[+] Falling back to Playwright test runner...")
+            npx = shutil.which("npx")
+            if npx:
+                return subprocess.run([npx, "playwright", "test", "--grep", "@probe"]).returncode
+            print("[ERROR] Neither real_e2e_runner.py nor npx found.")
+            return 1
+
+    elif mode == "katalon":
+        katalon_bin = find_katalon_binary()
+        if not katalon_bin:
+            print("[!] Katalon Runtime Engine (katalonc) not found on PATH or standard locations.")
+            print("    Please set KATALON_HOME or ensure katalonc is installed.")
+            return 1
+
+        print(f"[+] Launching Katalon Suite Prober via {katalon_bin}...")
+        cmd = [
+            katalon_bin,
+            "-noSplash",
+            "-runMode=console",
+            f"-testSuitePath={suite_path}",
+            "-browserType=Chrome (headless)"
+        ]
+        return subprocess.run(cmd).returncode
+
+    else:
+        print(f"[ERROR] Unsupported mode '{mode}'. Choose 'playwright' or 'katalon'.")
+        return 2
+
+
+def main():
+    parser = argparse.ArgumentParser(description="E2E Flow Prober and DOM Crawler Dispatcher")
+    parser.add_argument("--mode", choices=["playwright", "katalon"], default="playwright",
+                        help="Execution engine for prober (default: playwright)")
+    parser.add_argument("--suite", default="Test Suites/PROBE_E2E_Flow",
+                        help="Katalon test suite path (if mode=katalon)")
+    args = parser.parse_args()
+
+    sys.exit(run_prober(mode=args.mode, suite_path=args.suite))
+
+
+if __name__ == "__main__":
+    main()

package/tools/e2e_flow_prober.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Enterprise E2E Flow Prober Wrapper
+set -e
+python3 "$(dirname "$0")/e2e_flow_prober.py" "$@"

package/tools/flaky_detector.py

@@ -20,6 +20,7 @@ import sys
 import glob
 import json
 import time
+import shlex
 import argparse
 import subprocess
 import xml.etree.ElementTree as ET
@@ -56,12 +57,12 @@ RESET = "\033[0m"
 
 
 def run_command(cmd: str, timeout: int = 300) -> Tuple[int, str, str, float]:
-    """Executes a shell command and returns (returncode, stdout, stderr, elapsed_ms)."""
+    """Executes a command safely without shell=True and returns (returncode, stdout, stderr, elapsed_ms)."""
     start = time.time()
     try:
+        args = shlex.split(cmd, posix=sys.platform != "win32")
         res = subprocess.run(
-            cmd,
-            shell=True,
+            args,
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             text=True,

package/tools/generate_allure_report.ps1

@@ -1,30 +1,13 @@
-Write-Host "==========================================================" -ForegroundColor Cyan
-Write-Host "   ENTERPRISE AUTOMATION - ALLURE REPORT GENERATOR" -ForegroundColor Cyan
-Write-Host "==========================================================" -ForegroundColor Cyan
-
-$projectDir = Split-Path -Parent $PSScriptRoot
-$resultsDir = Join-Path $projectDir "allure-results"
-$reportDir  = Join-Path $projectDir "allure-report"
-
-if (-not (Test-Path $resultsDir)) {
-    Write-Host "[!] Không tìm thấy thư mục: $resultsDir" -ForegroundColor Yellow
-    Write-Host "[!] Hãy thực thi Test Suite trước để sinh dữ liệu kết quả." -ForegroundColor Yellow
-    exit 0
-}
-
-# Kiểm tra Allure CLI
-$allureCmd = Get-Command allure -ErrorAction SilentlyContinue
-
-if ($allureCmd) {
-    Write-Host "[+] Đang xuất báo cáo Allure HTML..." -ForegroundColor Green
-    allure generate $resultsDir -o $reportDir --clean
-    Write-Host "[+] Xuất báo cáo hoàn tất tại: $reportDir" -ForegroundColor Green
-    Write-Host "[+] Đang mở báo cáo trên trình duyệt..." -ForegroundColor Cyan
-    allure open $reportDir
+# Enterprise Automation - Allure Report Generator Wrapper
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$pythonCmd = Get-Command python -ErrorAction SilentlyContinue
+if (-not $pythonCmd) { $pythonCmd = Get-Command py -ErrorAction SilentlyContinue }
+if (-not $pythonCmd) { $pythonCmd = Get-Command python3 -ErrorAction SilentlyContinue }
+
+if ($pythonCmd) {
+    & $pythonCmd.Source "$scriptDir\generate_allure_report.py" $args
+    exit $LASTEXITCODE
 } else {
-    Write-Host "[!] Không tìm thấy công cụ Allure CLI trong hệ thống." -ForegroundColor Yellow
-    Write-Host "[*] Hướng dẫn cài đặt nhanh:" -ForegroundColor White
-    Write-Host "    Cách 1: npm install -g allure-commandline" -ForegroundColor Gray
-    Write-Host "    Cách 2: scoop install allure" -ForegroundColor Gray
-    Write-Host "    Cách 3: choco install allure-commandline" -ForegroundColor Gray
-}
+    Write-Error "Python 3 is required to run generate_allure_report.py."
+    exit 1
+}

package/tools/generate_allure_report.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""
+Enterprise Allure HTML Report Generator (Cross-Platform)
+---------------------------------------------------------
+Dispatches Allure report generation and local web serving across Windows, macOS, and Linux.
+Replaces legacy PowerShell-only scripts with a zero-dependency, cross-platform engine.
+"""
+
+import os
+import sys
+import shutil
+import subprocess
+import argparse
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+PROJECT_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, ".."))
+
+
+def generate_allure_report(results_dir=None, report_dir=None, clean=True, open_browser=False):
+    """Generates an Allure HTML report from raw result files."""
+    results_path = results_dir or os.path.join(PROJECT_ROOT, "allure-results")
+    report_path = report_dir or os.path.join(PROJECT_ROOT, "allure-report")
+
+    if not os.path.exists(results_path):
+        print(f"[!] Results directory not found: {results_path}")
+        print("[!] Please execute your test suite first to generate raw test result files.")
+        return 0
+
+    allure_cmd = shutil.which("allure")
+    if not allure_cmd:
+        print("[!] Allure CLI executable was not found on PATH.")
+        print("[*] Quick installation instructions:")
+        print("    npm install -g allure-commandline")
+        print("    brew install allure  (macOS)")
+        print("    scoop install allure  (Windows)")
+        return 1
+
+    cmd = [allure_cmd, "generate", results_path, "-o", report_path]
+    if clean:
+        cmd.append("--clean")
+
+    print(f"[+] Generating Allure HTML report from '{results_path}' to '{report_path}'...")
+    try:
+        ret = subprocess.run(cmd, check=True)
+        print(f"[+] Report generated successfully at: {report_path}")
+    except subprocess.CalledProcessError as e:
+        print(f"[ERROR] Allure report generation failed with exit code {e.returncode}")
+        return e.returncode
+
+    if open_browser:
+        print("[+] Launching Allure report server...")
+        try:
+            subprocess.run([allure_cmd, "open", report_path])
+        except KeyboardInterrupt:
+            print("\n[+] Allure server closed.")
+
+    return 0
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate and serve Allure HTML test reports")
+    parser.add_argument("--results-dir", default=None, help="Directory containing raw allure-results")
+    parser.add_argument("--report-dir", default=None, help="Output directory for generated HTML report")
+    parser.add_argument("--no-clean", action="store_true", help="Do not clean output report directory before generation")
+    parser.add_argument("--open", action="store_true", help="Automatically open report in browser via local server")
+    args = parser.parse_args()
+
+    sys.exit(generate_allure_report(
+        results_dir=args.results_dir,
+        report_dir=args.report_dir,
+        clean=not args.no_clean,
+        open_browser=args.open
+    ))
+
+
+if __name__ == "__main__":
+    main()

package/tools/generate_allure_report.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Enterprise Allure Report Generator Wrapper
+set -e
+python3 "$(dirname "$0")/generate_allure_report.py" "$@"