synapse-hub 2.2.3 → 2.4.0

package/tools/visual_diff_canvas.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+from __future__ import annotations
 """
 Enterprise Canvas Visual Diff & Regression Checker
 ===================================================

package/tools/visual_som_helper.py

@@ -46,7 +46,7 @@ if hasattr(sys.stdout, 'reconfigure'):
 
 SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
 QA_HUB_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, ".."))
-DEFAULT_CACHE_DB = os.path.join(SCRIPT_DIR, "memory_cache.db")
+DEFAULT_CACHE_DB = os.path.expanduser("~/.agent_memory/global_cache.db")
 
 MARK_COLORS = [
     "#FF0055",  # Vibrant Red/Pink

package/tools/watch_mode.py

@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
+# SPDX-License-Identifier: MIT
+# Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
+
+"""
+tools/watch_mode.py — Incremental Watch Mode & Real-Time Test Engineering HUD
+----------------------------------------------------------------------------
+Continuously monitors target repository files for code changes and triggers
+near-instant (< 100ms) incremental verification:
+  1. UTF-8 No BOM validation
+  2. Forbidden machine absolute path scan
+  3. AST Static Defect / Fake-Pass Sentinel (Meta Infer-style)
+  4. POM & Test Impact Blast Radius Scoping
+
+Usage:
+  python3 tools/watch_mode.py [target]
+  python3 tools/watch_mode.py [target] --debounce 0.8
+  python3 tools/watch_mode.py [target] --once
+"""
+
+import os
+import sys
+import time
+import glob
+import re
+import argparse
+from datetime import datetime
+from typing import Dict, Set, List, Optional, Tuple, Any
+
+# Enforce UTF-8 stdout encoding for Windows console compatibility
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+HUB_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, ".."))
+
+WATCH_EXTENSIONS = (
+    ".groovy", ".tc", ".ts", ".js", ".py", ".glbl", ".json", ".feature", ".md"
+)
+
+IGNORED_DIRS = {
+    ".git", ".gradle", "node_modules", "allure-results", "Screenshots",
+    "Reports", "reports", "TestReports", "testreports", "bin", "Libs", ".settings",
+    "graphify-out", "__pycache__", "agent_qa.egg-info", "dist", "build", ".pytest_cache",
+    "claude-ecosystem-repos"
+}
+
+IGNORED_FILES = {
+    ".project", ".classpath", ".DS_Store", "memory_cache.db",
+    "verify_all.py", "git_pre_commit_guard.py", "agent_canary.py", "watch_mode.py",
+    "repo_map.txt", "repo_map.json", "PROJECT_HEALTH_REPORT.md", "PROJECT_STATE.md"
+}
+
+FORBIDDEN_PATH_PATTERNS = [
+    (re.compile(r'file:///[a-zA-Z]:', re.IGNORECASE), "Machine file URI (file:///...)"),
+    (re.compile(r'\b[a-zA-Z]:\\Users\\[a-zA-Z0-9_\-]+\\', re.IGNORECASE), "Windows User directory path"),
+    (re.compile(r'\b/Users/[a-zA-Z0-9_\-]+/', re.IGNORECASE), "macOS/Unix User directory path"),
+]
+
+# ANSI colors
+RESET = "\033[0m"
+BOLD = "\033[1m"
+GREEN = "\033[92m"
+RED = "\033[91m"
+YELLOW = "\033[93m"
+CYAN = "\033[96m"
+MAGENTA = "\033[95m"
+DIM = "\033[2m"
+BG_BLUE = "\033[44m"
+BG_DARK = "\033[100m"
+
+
+def check_inactivity(last_activity_time: float, threshold_sec: float) -> Tuple[bool, float]:
+    """
+    Checks if a monitored process or run has been silent longer than the threshold.
+    Inspired by agentblazo/blazo 'no_activity' detection rule.
+    """
+    if threshold_sec <= 0:
+        return False, 0.0
+    idle = time.time() - last_activity_time
+    return idle > threshold_sec, idle
+
+
+def format_event_badge(badge_type: str, status: str = "INFO", duration_ms: Optional[float] = None) -> str:
+    """
+    Formats compact, colorful event badges for the Live TUI HUD.
+    Inspired by agentblazo/blazo TUI event badges.
+    """
+    dur_str = f" {duration_ms}ms" if duration_ms is not None else ""
+    if status == "PASS":
+        color = GREEN
+    elif status == "FAIL" or status == "ERR":
+        color = RED
+    elif status == "WARN":
+        color = YELLOW
+    else:
+        color = CYAN
+
+    return f"{color}[{badge_type.upper()}{dur_str}]{RESET}"
+
+
+def check_file_bom(file_path: str) -> bool:
+    """Returns True if file has UTF-8 BOM bytes."""
+    try:
+        with open(file_path, "rb") as fp:
+            return fp.read(3) == b"\xef\xbb\xbf"
+    except Exception:
+        return False
+
+
+def check_forbidden_paths(file_path: str) -> List[Tuple[int, str]]:
+    """Returns list of (line_no, description) of forbidden absolute machine paths."""
+    fname = os.path.basename(file_path)
+    if fname in IGNORED_FILES:
+        return []
+
+    violations = []
+    try:
+        with open(file_path, "r", encoding="utf-8", errors="ignore") as fp:
+            for line_no, line in enumerate(fp, 1):
+                for pattern, desc in FORBIDDEN_PATH_PATTERNS:
+                    if pattern.search(line):
+                        violations.append((line_no, desc))
+    except Exception:
+        pass
+    return violations
+
+
+def run_incremental_linter(file_path: str) -> Tuple[bool, str]:
+    """Runs fast AST check on modified script."""
+    infer_script = os.path.join(SCRIPT_DIR, "infer_linter.py")
+    if not os.path.exists(infer_script):
+        return True, "infer_linter not found"
+
+    try:
+        import subprocess
+        res = subprocess.run(
+            [sys.executable, infer_script, file_path],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True
+        )
+        if res.returncode == 0:
+            return True, "Clean (0 AST Defects / 0 Fake Passes)"
+        else:
+            return False, res.stdout.strip() or res.stderr.strip()
+    except Exception as e:
+        return False, str(e)
+
+
+def run_incremental_audit(file_path: str, target_dir: str) -> Dict[str, Any]:
+    """Performs fast sub-100ms audit on a single changed file."""
+    start_t = time.perf_counter()
+    rel_path = os.path.relpath(file_path, target_dir)
+    results = {
+        "file": rel_path,
+        "bom_pass": True,
+        "path_pass": True,
+        "lint_pass": True,
+        "details": [],
+        "duration_ms": 0.0
+    }
+
+    # 1. BOM Check
+    if check_file_bom(file_path):
+        results["bom_pass"] = False
+        results["details"].append("UTF-8 BOM detected (Must be 100% UTF-8 No BOM)")
+
+    # 2. Path Portability Check
+    path_issues = check_forbidden_paths(file_path)
+    if path_issues:
+        results["path_pass"] = False
+        for lno, desc in path_issues:
+            results["details"].append(f"Line {lno}: {desc}")
+
+    # 3. Incremental AST Linter for test automation scripts (e.g. Scripts/ in target projects)
+    # Skip python unittests in hub tests/ directory
+    norm_rel = rel_path.replace("\\", "/")
+    is_target_script = norm_rel.startswith("Scripts/") or ("/Scripts/" in norm_rel)
+    if is_target_script and file_path.endswith((".groovy", ".ts", ".js", ".py")):
+        lint_ok, lint_msg = run_incremental_linter(file_path)
+        if not lint_ok:
+            results["lint_pass"] = False
+            results["details"].append(f"AST Linter: {lint_msg}")
+
+    results["duration_ms"] = round((time.perf_counter() - start_t) * 1000, 2)
+    return results
+
+
+def print_hud_banner(target_dir: str):
+    print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
+    print(f"{BOLD}{CYAN}     ⚡ SYNAPSE-HUB REAL-TIME WATCH MODE SENTINEL (INCREMENTAL HUD)   {RESET}")
+    print(f"{BOLD}{CYAN}======================================================================{RESET}")
+    print(f"{DIM}Watching directory : {RESET}{BOLD}{target_dir}{RESET}")
+    print(f"{DIM}Monitored types    : {RESET}{CYAN}{', '.join(WATCH_EXTENSIONS)}{RESET}")
+    print(f"{DIM}Trigger checks     : {RESET}UTF-8 No BOM, Absolute Paths, AST Fake-Pass Sentinel")
+    print(f"{DIM}Press {RESET}{BOLD}Ctrl+C{RESET}{DIM} to pause or stop watching.\n{RESET}")
+
+
+def print_audit_result(res: Dict[str, Any], change_type: str = "MOD"):
+    timestamp = datetime.now().strftime("%H:%M:%S")
+    rel_path = res["file"]
+    duration = res["duration_ms"]
+    all_clean = res["bom_pass"] and res["path_pass"] and res["lint_pass"]
+
+    badge = format_event_badge(change_type, "PASS" if all_clean else "FAIL", duration)
+    if all_clean:
+        print(f"[{timestamp}] {badge} {GREEN}✓ PASS{RESET} {BOLD}{rel_path}{RESET}")
+    else:
+        print(f"[{timestamp}] {badge} {RED}✗ FAIL{RESET} {BOLD}{rel_path}{RESET}")
+        for d in res["details"]:
+            print(f"   {RED}↳ {d}{RESET}")
+
+
+def scan_file_states(target_dir: str) -> Dict[str, float]:
+    """Scans all eligible files and records their mtime."""
+    file_states = {}
+    for root, dirs, files in os.walk(target_dir):
+        dirs[:] = [d for d in dirs if d not in IGNORED_DIRS]
+        for f in files:
+            if f.endswith(WATCH_EXTENSIONS):
+                full_path = os.path.join(root, f)
+                try:
+                    file_states[full_path] = os.path.getmtime(full_path)
+                except OSError:
+                    pass
+    return file_states
+
+
+def watch_directory(target_dir: str, debounce: float = 0.8, run_once: bool = False, inactivity_timeout: float = 0.0) -> int:
+    """Main watch loop with debouncing, live TUI event badges, and inactivity watchdog."""
+    target_dir = os.path.abspath(target_dir)
+    print_hud_banner(target_dir)
+
+    known_states = scan_file_states(target_dir)
+    print(f"{GREEN}● Watchdog active:{RESET} Indexed {len(known_states)} files. Ready for file changes...\n")
+
+    if run_once:
+        print(f"{CYAN}[ONCE MODE]{RESET} Executing one-time scan across {len(known_states)} indexed files...")
+        failures = 0
+        for fpath in sorted(known_states.keys()):
+            res = run_incremental_audit(fpath, target_dir)
+            if not (res["bom_pass"] and res["path_pass"] and res["lint_pass"]):
+                print_audit_result(res, change_type="AUDIT")
+                failures += 1
+        if failures == 0:
+            print(f"\n{GREEN}✅ [ALL PASS]{RESET} 100% of {len(known_states)} files passed incremental sentinel checks.")
+            return 0
+        else:
+            print(f"\n{RED}❌ [FAIL]{RESET} {failures} files violated Quality Gates.")
+            return 1
+
+    last_activity_time = time.time()
+    inactivity_alerted = False
+
+    try:
+        while True:
+            time.sleep(debounce)
+            current_states = scan_file_states(target_dir)
+            changed_files = []
+
+            for fpath, mtime in current_states.items():
+                if fpath not in known_states:
+                    changed_files.append((fpath, "CREATE"))
+                elif mtime > known_states[fpath]:
+                    changed_files.append((fpath, "MODIFY"))
+
+            known_states = current_states
+
+            if changed_files:
+                last_activity_time = time.time()
+                inactivity_alerted = False
+                for fpath, change_type in changed_files:
+                    res = run_incremental_audit(fpath, target_dir)
+                    print_audit_result(res, change_type=change_type)
+            elif inactivity_timeout > 0:
+                is_stuck, idle_sec = check_inactivity(last_activity_time, inactivity_timeout)
+                if is_stuck and not inactivity_alerted:
+                    inactivity_alerted = True
+                    badge = format_event_badge("STUCK", "WARN")
+                    print(f"\n{badge} {YELLOW}No activity for {round(idle_sec, 1)}s (Inactivity threshold: {inactivity_timeout}s){RESET}\n")
+
+    except KeyboardInterrupt:
+        print(f"\n\n{YELLOW}🛑 [WATCH STOPPED]{RESET} Exiting Watch Mode Sentinel.")
+        return 0
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Real-Time Incremental Watch Mode Sentinel")
+    parser.add_argument("target", nargs="?", default=".", help="Directory to monitor (default: current directory)")
+    parser.add_argument("--debounce", type=float, default=0.8, help="Debounce interval in seconds (default: 0.8)")
+    parser.add_argument("--inactivity-timeout", type=float, default=0.0, help="Inactivity timeout in seconds to trigger stuck warning (default: 0 = disabled)")
+    parser.add_argument("--once", action="store_true", help="Run incremental scan once on all files and exit")
+    args = parser.parse_args()
+
+    return watch_directory(target_dir=args.target, debounce=args.debounce, run_once=args.once, inactivity_timeout=args.inactivity_timeout)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/welcome_page.py

@@ -0,0 +1,291 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
+# SPDX-License-Identifier: MIT
+# Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
+
+"""
+tools/welcome_page.py — Interactive Visual Landing Page for Synapse Hub
+-------------------------------------------------------------------------
+Generates and automatically launches a modern, responsive, 100% self-contained
+HTML5 product landing page that introduces Synapse Hub's capabilities across
+Manual, Automation, API, and Performance testing.
+
+Features:
+  - Default Vietnamese interface with instant 1-click English toggle (bilingual i18n).
+  - 100% air-gapped & offline-ready (Zero external CDNs or remote dependencies).
+  - Dark glassmorphism interface with responsive layout.
+  - Interactive tabs covering the 4 Core Pillars of QA Intelligence.
+  - Interactive CLI Cheatsheet with 1-click clipboard copy.
+  - Comparison matrix vs existing industry tools (ESLint, Stryker, Allure, Healenium).
+  - 6 Subagent Swarm Profiles & 9 Quality Gates DoD showcase.
+  - Automatic browser launching on setup, pull, or CLI dispatch.
+"""
+
+import os
+import sys
+import json
+import html as html_lib
+import argparse
+import webbrowser
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+# Enforce UTF-8 stdout encoding for Windows console compatibility
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+HUB_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, ".."))
+FIRST_RUN_MARKER_FILENAME = ".welcome_shown"
+
+
+def get_hub_metadata() -> Dict[str, Any]:
+    """Retrieves version and catalog count from skills_manifest.json."""
+    manifest_path = os.path.join(HUB_ROOT, "skills_manifest.json")
+    meta = {
+        "version": "2.4.0",
+        "totalSkills": 38,
+        "author": "Thế Vị (@TeeVee998)",
+        "repo": "https://github.com/TeeVee998/Synapse-Hub"
+    }
+    if os.path.exists(manifest_path):
+        try:
+            with open(manifest_path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+                meta["version"] = data.get("version", meta["version"])
+                meta["totalSkills"] = data.get("totalSkills", meta["totalSkills"])
+        except (OSError, json.JSONDecodeError):
+            pass
+    return meta
+
+
+def is_hub_repo(path_str: Optional[str]) -> bool:
+    """Checks whether the given path corresponds to the Synapse-Hub core repository itself."""
+    if not path_str:
+        return True
+    resolved = os.path.abspath(path_str)
+    if resolved.lower() == HUB_ROOT.lower():
+        return True
+    if os.path.exists(os.path.join(resolved, "skills_manifest.json")) or os.path.isdir(os.path.join(resolved, ".agents", "skills")):
+        return True
+    return False
+
+
+def generate_welcome_html(target_repo: Optional[str] = None, stack_info: Optional[Dict[str, str]] = None, default_lang: str = "vi") -> str:
+    """Renders the standalone interactive HTML5 landing page with bilingual language switcher."""
+    meta = get_hub_metadata()
+    now_str = datetime.now().strftime("%Y-%m-%d %H:%M")
+    
+    is_external_target = bool(target_repo and not is_hub_repo(target_repo) and stack_info)
+    if is_external_target:
+        raw_target_name = (stack_info.get("name") if stack_info else "") or os.path.basename(os.path.abspath(target_repo))
+        raw_framework = (stack_info.get("framework") if stack_info else "") or "Automated QA"
+        target_name = html_lib.escape(str(raw_target_name))
+        framework_name = html_lib.escape(str(raw_framework))
+        hero_pill_content = f"""<span data-i18n="hero_pill_tag">🛡️ Trung Tâm Trí Tuệ Chất Lượng AI Doanh Nghiệp</span>
+                <span>&bull;</span>
+                <span><span data-i18n="hero_target_label">Dự án mục tiêu</span>: <strong>{target_name}</strong> ({framework_name})</span>"""
+    else:
+        hero_pill_content = """<span data-i18n="hero_pill_tag">🛡️ Trung Tâm Trí Tuệ Chất Lượng AI Doanh Nghiệp</span>
+                <span>&bull;</span>
+                <span data-i18n="hero_pill_status">Sẵn Sàng 100% Offline</span>"""
+
+    tmpl_candidates = [
+        os.path.join(HUB_ROOT, "templates", "welcome.html.tmpl"),
+        os.path.join(SCRIPT_DIR, "..", "templates", "welcome.html.tmpl"),
+        os.path.join(SCRIPT_DIR, "templates", "welcome.html.tmpl"),
+    ]
+    template_str = None
+    for cand in tmpl_candidates:
+        if os.path.exists(cand):
+            try:
+                with open(cand, "r", encoding="utf-8") as tf:
+                    template_str = tf.read()
+                    break
+            except OSError:
+                pass
+
+    if not template_str:
+        return f"""<!DOCTYPE html>
+<html><head><meta charset="UTF-8"><title>Synapse Hub</title></head>
+<body style="font-family:sans-serif;background:#0f172a;color:#f8fafc;padding:40px;text-align:center;">
+<h1>🛡️ Synapse Hub Enterprise QA v{meta.get('version', '2.4.0')}</h1>
+<p>{hero_pill_content}</p>
+<p>Total Standardized Skills: {meta.get('totalSkills', 38)}</p>
+<p>Author: {meta.get('author', 'Thế Vị (@TeeVee998)')}</p>
+</body></html>"""
+
+    rendered_html = (
+        template_str.replace("__DEFAULT_LANG__", default_lang)
+        .replace("__HERO_PILL_CONTENT__", hero_pill_content)
+        .replace("__NOW_STR__", now_str)
+        .replace("__VERSION__", str(meta.get("version", "2.4.0")))
+        .replace("__AUTHOR__", str(meta.get("author", "Thế Vị (@TeeVee998)")))
+        .replace("__TOTAL_SKILLS__", str(meta.get("totalSkills", 38)))
+        .replace("__REPO__", str(meta.get("repo", "https://github.com/TeeVee998/Synapse-Hub")))
+    )
+    return rendered_html
+
+
+def write_welcome_page(output_path: Optional[str] = None, target_repo: Optional[str] = None, stack_info: Optional[Dict[str, str]] = None, default_lang: str = "vi") -> str:
+    """Generates and writes the welcome landing page to disk."""
+    if not output_path:
+        base_dir = target_repo if target_repo else HUB_ROOT
+        reports_dir = os.path.join(base_dir, "reports")
+        os.makedirs(reports_dir, exist_ok=True)
+        output_path = os.path.join(reports_dir, "WELCOME.html")
+    else:
+        output_path = os.path.abspath(output_path)
+        os.makedirs(os.path.dirname(output_path), exist_ok=True)
+
+    html_content = generate_welcome_html(target_repo=target_repo, stack_info=stack_info, default_lang=default_lang)
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write(html_content)
+
+    return output_path
+
+
+def get_marker_path(target_repo: Optional[str] = None) -> str:
+    """Returns the path to the .welcome_shown marker file for the given repository."""
+    base = target_repo if target_repo else HUB_ROOT
+    return os.path.join(base, "reports", FIRST_RUN_MARKER_FILENAME)
+
+
+def is_first_run(target_repo: Optional[str] = None) -> bool:
+    """
+    Checks whether this is the first install / first pull for the hub.
+    Returns True if the welcome page has not been displayed yet.
+    """
+    marker_path = get_marker_path(target_repo)
+    if os.path.exists(marker_path):
+        return False
+
+    global_dir = os.path.expanduser("~/.agent_memory")
+    global_marker = os.path.join(global_dir, "welcome_shown.json")
+    if os.path.exists(global_marker):
+        try:
+            with open(global_marker, "r", encoding="utf-8") as f:
+                data = json.load(f)
+                key = os.path.realpath(target_repo or HUB_ROOT)
+                if key in data:
+                    return False
+        except (OSError, json.JSONDecodeError):
+            pass
+
+    return True
+
+
+def mark_first_run_completed(target_repo: Optional[str] = None):
+    """
+    Records that the landing page has been shown so it does not open again.
+    """
+    marker_path = get_marker_path(target_repo)
+    try:
+        os.makedirs(os.path.dirname(marker_path), exist_ok=True)
+        with open(marker_path, "w", encoding="utf-8") as f:
+            json.dump({
+                "shown_at": datetime.now().isoformat(),
+                "repo": os.path.realpath(target_repo or HUB_ROOT)
+            }, f, indent=2)
+    except OSError:
+        pass
+
+    try:
+        global_dir = os.path.expanduser("~/.agent_memory")
+        os.makedirs(global_dir, exist_ok=True)
+        global_marker = os.path.join(global_dir, "welcome_shown.json")
+        data = {}
+        if os.path.exists(global_marker):
+            try:
+                with open(global_marker, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+            except (OSError, json.JSONDecodeError):
+                data = {}
+        key = os.path.realpath(target_repo or HUB_ROOT)
+        data[key] = datetime.now().isoformat()
+        with open(global_marker, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+    except OSError:
+        pass
+
+
+def open_welcome_page(file_path: str) -> bool:
+    """
+    Opens the welcome page in the user's default browser if not running in headless/CI mode or test runner.
+    Returns True if successfully launched, False otherwise.
+    """
+    if (
+        os.environ.get("CI")
+        or os.environ.get("HEADLESS")
+        or os.environ.get("AGENT_QA_NO_BROWSER")
+        or "unittest" in sys.modules
+        or "pytest" in sys.modules
+    ):
+        return False
+
+    abs_path = os.path.abspath(file_path)
+    if not os.path.exists(abs_path):
+        return False
+
+    file_url = f"file://{abs_path}"
+    try:
+        webbrowser.open(file_url)
+        return True
+    except Exception:
+        return False
+
+
+def generate_welcome_page(target_repo: Optional[str] = None, output_path: Optional[str] = None, stack_info: Optional[Dict[str, str]] = None, open_browser: bool = True, default_lang: str = "vi") -> str:
+    """
+    Full workflow helper: generates the landing page and opens it if requested.
+    """
+    out_file = write_welcome_page(output_path=output_path, target_repo=target_repo, stack_info=stack_info, default_lang=default_lang)
+    if open_browser:
+        opened = open_welcome_page(out_file)
+        if opened:
+            print(f"  🚀 Đã mở Visual Landing Page trong trình duyệt của bạn.")
+    return out_file
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Synapse Hub Visual Landing Page Generator (Bilingual VI/EN)")
+    parser.add_argument("target", nargs="?", default=None, help="Target repository directory (default: current directory)")
+    parser.add_argument("--output", "-o", default=None, help="Output HTML file path (default: reports/WELCOME.html)")
+    parser.add_argument("--lang", choices=["vi", "en"], default="vi", help="Default initial language (default: vi = Vietnamese)")
+    parser.add_argument("--no-browser", action="store_true", help="Do not open the browser after generating the page")
+    parser.add_argument("--open", action="store_true", help="Explicitly open the browser")
+    parser.add_argument("--first-run", action="store_true", help="Only generate and open if running for the first time (e.g. npm install or first pull)")
+    args = parser.parse_args()
+
+    target_dir = os.path.abspath(args.target) if args.target else HUB_ROOT
+
+    # If --first-run requested, check if it was already displayed
+    if args.first_run:
+        if not is_first_run(target_dir):
+            return
+
+    should_open = not args.no_browser if (not os.environ.get("CI")) else args.open
+    if args.first_run and (os.environ.get("CI") or os.environ.get("HEADLESS") or "unittest" in sys.modules or "pytest" in sys.modules):
+        should_open = False
+
+    print(f"🎨 Generating Synapse Hub Visual Landing Page (Language: {args.lang.upper()})...")
+    out_path = generate_welcome_page(
+        target_repo=target_dir,
+        output_path=args.output,
+        open_browser=should_open,
+        default_lang=args.lang
+    )
+    if args.first_run or should_open:
+        mark_first_run_completed(target_dir)
+
+    print(f"✅ Landing page generated successfully at:\n   file://{out_path}")
+    print(f"👉 You can re-open it anytime with: npx synapse-hub welcome")
+
+
+if __name__ == "__main__":
+    main()