synapse-hub 2.4.0 → 2.4.2

package/tools/api_fuzzer.py

@@ -115,12 +115,21 @@ class ApiFuzzer:
         parsed = urllib.parse.urlparse(self.base_url)
         host = (parsed.hostname or "").lower().strip()
         is_safe_env = self._is_safe_non_prod_host(host)
-        if host and not is_safe_env and not os.environ.get("SYNAPSE_ALLOW_PROD_FUZZ"):
+        allowed_hosts = {
+            h.strip().lower() for h in os.environ.get("SYNAPSE_ALLOW_PROD_HOSTS", "").split(",") if h.strip()
+        }
+        is_host_specifically_allowed = host in allowed_hosts
+        global_override = os.environ.get("SYNAPSE_ALLOW_PROD_FUZZ") in ("1", "true", "TRUE")
+
+        if host and not is_safe_env and not (is_host_specifically_allowed or global_override):
             raise PermissionError(
                 f"[SAFETY FIREWALL - REJECTED] Target host '{host}' is not in the allowed non-production environment allowlist "
                 "(localhost, private IP, .local/.internal, or verified dev/staging/qa/test subdomain). "
-                "Set SYNAPSE_ALLOW_PROD_FUZZ=1 only if authorized."
+                f"To authorize this host specifically, set SYNAPSE_ALLOW_PROD_HOSTS='{host}' or SYNAPSE_ALLOW_PROD_FUZZ=1 if authorized."
             )
+        if host and not is_safe_env and global_override and not is_host_specifically_allowed:
+            print(f"  ⚠️ [SECURITY WARNING] SYNAPSE_ALLOW_PROD_FUZZ=1 global override active for host '{host}'. "
+                  f"Prefer setting SYNAPSE_ALLOW_PROD_HOSTS='{host}' for host-scoped permission.")
 
         # Prepare SSL context (support self-signed staging certificates via explicit --insecure flag)
         self.ssl_context = ssl.create_default_context()

package/tools/browser_helpers.js

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

package/tools/bump_version.py

@@ -195,6 +195,10 @@ def main():
     # 7. tools/mcp_excel_server.ps1
     update_file("tools/mcp_excel_server.ps1", r'(version\s*=\s*")[^"]+(")', rf"\g<1>{new_ver}\g<2>", args.dry_run)
 
+    # 7b. tools/mcp_excel_server.py
+    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
     update_file("docs/ARCHITECTURE.md", r'(>\s*\*\*Version:\*\*\s*`)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
 
@@ -214,6 +218,10 @@ def main():
     # 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)
 
+    # 13. tools/update_sentinel.py
+    update_file("tools/update_sentinel.py", r'(\.get\("version",\s*")[^"]+(")', rf"\g<1>{new_ver}\g<2>", args.dry_run)
+    update_file("tools/update_sentinel.py", r'(return\s*")[0-9]+\.[0-9]+\.[0-9]+(")', rf"\g<1>{new_ver}\g<2>", args.dry_run)
+
     if args.dry_run:
         print("\n[INFO] Dry-run completed. No files modified on disk.")
         return

package/tools/check_version_sync.py

@@ -93,6 +93,24 @@ def extract_versions(repo_root: str) -> Dict[str, str]:
             if m:
                 versions["tools/__init__.py"] = m.group(1)
 
+    # 9. tools/mcp_excel_server.py
+    excel_mcp_path = os.path.join(repo_root, "tools", "mcp_excel_server.py")
+    if os.path.exists(excel_mcp_path):
+        with open(excel_mcp_path, "r", encoding="utf-8") as f:
+            content = f.read()
+            m = re.search(r'"serverInfo":\s*\{[^}]*"version":\s*["\']([^"\']+)["\']', content)
+            if m:
+                versions["tools/mcp_excel_server.py"] = m.group(1)
+
+    # 10. docs/ARCHITECTURE.md
+    arch_path = os.path.join(repo_root, "docs", "ARCHITECTURE.md")
+    if os.path.exists(arch_path):
+        with open(arch_path, "r", encoding="utf-8") as f:
+            content = f.read()
+            m = re.search(r'>\s*\*\*Version:\*\*\s*`([^`]+)`', content)
+            if m:
+                versions["docs/ARCHITECTURE.md"] = m.group(1)
+
     return versions
 
 

package/tools/cli.py

@@ -13,6 +13,8 @@ Dispatches commands to underlying specialized tools in tools/.
 import os
 import sys
 import json
+import re
+import difflib
 import argparse
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
@@ -27,10 +29,19 @@ SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
 REPO_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, ".."))
 sys.path.insert(0, SCRIPT_DIR)
 
+# ANSI Color formatting
+CYAN = "\033[96m"
+GREEN = "\033[92m"
+YELLOW = "\033[93m"
+RED = "\033[91m"
+BOLD = "\033[1m"
+RESET = "\033[0m"
+
 
 def cmd_version(args):
+    """Displays the current hub version, skill catalog count, and license information."""
     manifest_path = os.path.join(REPO_ROOT, "skills_manifest.json")
-    version = "2.4.0"
+    version = "2.4.2"
     if os.path.exists(manifest_path):
         try:
             import json
@@ -45,7 +56,7 @@ def cmd_version(args):
         try:
             import json
             with open(manifest_path, "r", encoding="utf-8") as f:
-                manifest_skills = json.load(f).get("totalSkills", 37)
+                manifest_skills = json.load(f).get("totalSkills", 38)
         except (OSError, json.JSONDecodeError):
             pass
     print(f"Catalog: {manifest_skills} Standardized Skills | 6 Subagent Swarm Profiles")
@@ -54,6 +65,7 @@ def cmd_version(args):
 
 
 def cmd_verify_author(args):
+    """Validates author attribution and MIT provenance integrity across the repository."""
     from author_integrity import verify_author_attribution, get_canonical_watermark, enforce_author_attribution
     valid, violations = verify_author_attribution()
     if valid:
@@ -63,33 +75,52 @@ def cmd_verify_author(args):
         enforce_author_attribution(strict=True)
 
 
+def _forward_subcommand_args(args_or_name=None) -> list:
+    """Safely extracts and forwards arguments intended for the underlying subcommand tool."""
+    subcmd = None
+    if isinstance(args_or_name, str):
+        subcmd = args_or_name
+    elif hasattr(args_or_name, "subcommand"):
+        subcmd = args_or_name.subcommand
+
+    if subcmd and subcmd in sys.argv:
+        idx = sys.argv.index(subcmd)
+        return [sys.argv[0]] + sys.argv[idx + 1:]
+    return [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+
+
 def cmd_verify(args):
+    """Executes the 9 Quality Gates Definition of Done (DoD) verification suite."""
     from verify_all import main as verify_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(verify_main())
 
 
 def cmd_lint(args):
+    """Runs the Meta Infer-style AST Fake-Pass, zero-assertion, and hard sleep scanner."""
     from infer_linter import main as lint_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(lint_main())
 
 
 def cmd_heal(args):
+    """Interacts with the central episodic self-healing solution memory cache."""
     from cache_resolver import main as heal_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(heal_main())
 
 
 def cmd_distill(args):
+    """Distills and filters high-volume CI/CD test execution logs by ~95%."""
     from distill_log import main as distill_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(distill_main())
 
 
 def cmd_impact(args):
+    """Analyzes code change impact and scopes affected tests using AST graph mapping."""
     from test_impact import main as impact_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(impact_main())
 
 
@@ -119,36 +150,42 @@ def cmd_clean(args):
 
 
 def cmd_flaky(args):
+    """Detects non-deterministic flaky tests and manages quarantine governance."""
     from flaky_detector import main as flaky_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(flaky_main())
 
 
 def cmd_canary(args):
+    """Executes the autonomous canary self-healing benchmark across 8 failure vectors."""
     from agent_canary import main as canary_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(canary_main())
 
 
 def cmd_analyze(args):
+    """Runs comprehensive 5-in-1 project health and AST architecture analysis."""
     from analyze_project import main as analyze_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(analyze_main())
 
 
 def cmd_setup(args):
+    """Bootstraps a target test repository with AI guide, Git hook, and AST map."""
     from setup_project import main as setup_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(setup_main())
 
 
 def cmd_doctor(args):
+    """Runs a 1-click diagnostic check of system environment, tools, and dependencies."""
     from check_env import main as check_env_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(check_env_main())
 
 
 def cmd_uninstall(args):
+    """Reverts and cleans configuration files and Git hooks installed by setup in target project."""
     from setup_project import uninstall_setup, resolve_target_repo
     target = getattr(args, "target", None)
     target_repo = resolve_target_repo(cli_target=target)
@@ -156,43 +193,50 @@ def cmd_uninstall(args):
 
 
 def cmd_auto_heal(args):
+    """Executes closed-loop test failure diagnosis and creates a locator healing plan."""
     from auto_heal import main as auto_heal_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(auto_heal_main())
 
 
 def cmd_safety_check(args):
+    """Validates actions against the Action Safety Firewall to prevent destructive operations."""
     from safety_firewall import main as safety_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(safety_main())
 
 
 def cmd_contract_drift(args):
+    """Detects breaking API changes across OpenAPI / Swagger contract specifications."""
     from api_drift_sentinel import main as drift_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(drift_main())
 
 
 def cmd_mcp_serve(args):
+    """Starts the JSON-RPC 2.0 stdio Model Context Protocol (MCP) server."""
     from mcp_server import run_stdio_server
     run_stdio_server()
 
 
 def cmd_mutate(args):
+    """Injects syntactic micro-mutations to measure test assertion sensitivity."""
     from micro_mutator import main as mut_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(mut_main())
 
 
 def cmd_heal_pr(args):
+    """Calculates self-healing confidence and generates an automated Git pull request draft."""
     from heal_pr_automator import main as pr_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(pr_main())
 
 
 def cmd_shard(args):
+    """Balances parallel CI/CD test execution using duration-balanced bin-packing."""
     from matrix_sharder import main as shard_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(shard_main())
 
 
@@ -231,37 +275,37 @@ def cmd_omni_scan(args):
 
 def cmd_report_bug(args):
     from bug_reporter import main as bug_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(bug_main())
 
 
 def cmd_mock_shield(args):
     from network_mock_shield import main as mock_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(mock_main())
 
 
 def cmd_visual_mask(args):
     from smart_visual_masker import main as mask_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(mask_main())
 
 
 def cmd_review_spec(args):
     from goldfish_review import main as review_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(review_main())
 
 
 def cmd_drift_check(args):
     from spec_drift_sentinel import main as drift_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(drift_main())
 
 
 def cmd_ci_hook(args):
     from ci_healing_hook import main as hook_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(hook_main())
 
 
@@ -295,67 +339,67 @@ def cmd_migrate(args):
 
 def cmd_decouple_config(args):
     from config_decoupler import main as decouple_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(decouple_main())
 
 
 def cmd_fuzz_api(args):
     from api_fuzzer import main as fuzz_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(fuzz_main())
 
 
 def cmd_som(args):
     from visual_som_helper import main as som_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(som_main())
 
 
 def cmd_gherkin(args):
     from gherkin_suite import main as gherkin_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(gherkin_main())
 
 
 def cmd_export_postman(args):
     from export_postman_collection import main as postman_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(postman_main())
 
 
 def cmd_generate_jmx(args):
     from generate_jmx_plan import main as jmx_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(jmx_main())
 
 
 def cmd_skillspector(args):
     from skillspector import main as skillspector_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(skillspector_main())
 
 
 def cmd_analyze_jtl(args):
     from jtl_analyzer import main as jtl_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(jtl_main())
 
 
 def cmd_export_excel(args):
     from md_to_xlsx import main as excel_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(excel_main())
 
 
 def cmd_correlate_telemetry(args):
     from telemetry_correlator import main as telem_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(telem_main())
 
 
 def cmd_analyze_newman(args):
     from newman_analyzer import main as newman_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(newman_main())
 
 
@@ -376,73 +420,103 @@ def cmd_update(args):
 
 def cmd_tokens(args):
     import count_tokens
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     count_tokens.main()
 
 
 def cmd_dashboard(args):
     import dashboard_generator
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     dashboard_generator.main()
 
 
 def cmd_watch(args):
     import watch_mode
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     watch_mode.main()
 
 
 def cmd_welcome(args):
     import welcome_page
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     welcome_page.main()
 
 
 def cmd_wcag_audit(args):
     from wcag_audit import main as wcag_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(wcag_main())
 
 
 def cmd_lookup_tc(args):
     from lookup_tc import main as tc_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(tc_main())
 
 
 def cmd_lookup_xpath(args):
     from lookup_xpath import main as xpath_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(xpath_main())
 
 
 def cmd_trace_data_flow(args):
     from trace_data_flow import main as tdf_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(tdf_main())
 
 
 def cmd_generate_tc(args):
     from generate_tc_from_story import main as gen_tc_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(gen_tc_main())
 
 
 def cmd_pinpoint_failure(args):
     from pinpoint_failure import main as pp_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(pp_main())
 
 
 def cmd_sync_rules(args):
     from sync_agent_rules import main as sync_rules_main
-    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.argv = _forward_subcommand_args(args)
     sys.exit(sync_rules_main())
 
 
+def cmd_api_matrix(args):
+    from generate_api_matrix import main as api_matrix_main
+    sys.argv = _forward_subcommand_args(args)
+    sys.exit(api_matrix_main())
+
+
+def cmd_canvas_diff(args):
+    from visual_diff_canvas import main as canvas_diff_main
+    sys.argv = _forward_subcommand_args(args)
+    sys.exit(canvas_diff_main())
+
+
+def cmd_validate_groovy(args):
+    from validate_groovy_scripts import main as groovy_main
+    sys.argv = _forward_subcommand_args(args)
+    sys.exit(groovy_main())
+
+
+def cmd_check_version(args):
+    from check_version_sync import main as ver_sync_main
+    sys.argv = _forward_subcommand_args(args)
+    sys.exit(ver_sync_main())
+
+
+def cmd_mcp_excel(args):
+    from mcp_excel_server import main as mcp_excel_main
+    sys.argv = _forward_subcommand_args(args)
+    sys.exit(mcp_excel_main())
+
+
 def _hub_version():
     manifest_path = os.path.join(REPO_ROOT, "skills_manifest.json")
-    version = "2.4.0"
+    version = "2.4.2"
     if os.path.exists(manifest_path):
         try:
             import json
@@ -453,8 +527,32 @@ def _hub_version():
     return version
 
 
+class SynapseArgumentParser(argparse.ArgumentParser):
+    """Enhanced ArgumentParser providing fuzzy Did-You-Mean suggestions on command typos."""
+    def error(self, message):
+        import difflib
+        m = re.search(r"invalid choice: '([^']+)'", message)
+        if m:
+            bad_choice = m.group(1)
+            choices = []
+            for action in self._actions:
+                if isinstance(action, argparse._SubParsersAction):
+                    choices = list(action.choices.keys())
+                    break
+            matches = difflib.get_close_matches(bad_choice, choices, n=3, cutoff=0.4)
+            sys.stderr.write(f"\n{BOLD}{RED}❌ Error: Lệnh '{bad_choice}' không tồn tại trong Synapse-Hub.{RESET}\n")
+            if matches:
+                suggestions = ", ".join(f"{BOLD}{GREEN}{c}{RESET}" for c in matches)
+                sys.stderr.write(f"💡 Có phải ý bạn là: {suggestions} ?\n\n")
+                sys.stderr.write(f"👉 Thử chạy: {BOLD}agent-qa {matches[0]} --help{RESET}\n\n")
+            else:
+                sys.stderr.write(f"👉 Gõ {BOLD}agent-qa --help{RESET} để xem danh sách tất cả các lệnh khả dụng.\n\n")
+            sys.exit(2)
+        super().error(message)
+
+
 def main():
-    parser = argparse.ArgumentParser(
+    parser = SynapseArgumentParser(
         prog="agent-qa",
         description="Enterprise AI Agent Quality Engineering & Test Automation Hub CLI"
     )
@@ -755,12 +853,76 @@ def main():
     p_drift.add_argument("--json", action="store_true", help="Output machine-readable JSON format")
     p_drift.set_defaults(func=cmd_drift_check)
 
+    # api-matrix
+    p_api_mat = subparsers.add_parser("api-matrix", help="Generate Positive, Boundary, and Negative test matrix from OpenAPI/Swagger")
+    p_api_mat.add_argument("--spec", "-s", help="Path to OpenAPI / Swagger JSON/YAML file")
+    p_api_mat.add_argument("--format", "-f", choices=["markdown", "json"], default="markdown", help="Output format (markdown, json)")
+    p_api_mat.add_argument("--output", "-o", help="Output file path")
+    p_api_mat.add_argument("--sample", action="store_true", help="Generate a sample matrix using built-in demonstration schema")
+    p_api_mat.set_defaults(func=cmd_api_matrix)
+
+    # canvas-diff
+    p_canvas = subparsers.add_parser("canvas-diff", help="HTML5 Canvas visual regression diffing & blank check")
+    p_canvas.add_argument("canvas_args", nargs="*", help="Subcommand (compare/check-blank) and image paths")
+    p_canvas.set_defaults(func=cmd_canvas_diff)
+
+    # validate-groovy
+    p_groovy = subparsers.add_parser("validate-groovy", help="Pre-check Groovy scripts & keywords syntax balance")
+    p_groovy.add_argument("target", nargs="?", default=None, help="Target repository or file to validate")
+    p_groovy.add_argument("--dir", "-d", help="Explicit directory to scan")
+    p_groovy.set_defaults(func=cmd_validate_groovy)
+
+    # check-version
+    p_ver_sync = subparsers.add_parser("check-version", help="Verify universal version synchronization across all files")
+    p_ver_sync.add_argument("--expected-version", "-e", help="Expected version string (e.g. from git tag)", default=None)
+    p_ver_sync.set_defaults(func=cmd_check_version)
+
+    # mcp-excel
+    p_mcp_excel = subparsers.add_parser("mcp-excel", help="Start the JSON-RPC 2.0 stdio MCP Excel server")
+    p_mcp_excel.set_defaults(func=cmd_mcp_excel)
+
     args, unknown = parser.parse_known_args()
     if getattr(args, "offline", False):
         os.environ["AGENT_QA_OFFLINE"] = "1"
         print("🔒 [OFFLINE MODE] Air-Gapped Deterministic Mode Active. 100% Local AST & Heuristics (Zero External API calls).")
 
     if not args.subcommand:
+        # If running in an interactive terminal, offer a friendly quick-start menu
+        is_interactive = hasattr(sys.stdin, "isatty") and sys.stdin.isatty() and not os.environ.get("CI") and not os.environ.get("SYNAPSE_NON_INTERACTIVE")
+        if is_interactive:
+            print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
+            print(f"{BOLD}{CYAN}    🧠 SYNAPSE HUB — INTERACTIVE TERMINAL WIZARD                      {RESET}")
+            print(f"{BOLD}{CYAN}======================================================================{RESET}")
+            print("Chào bạn! Hãy chọn nhanh một tác vụ để bắt đầu (hoặc nhấn Enter để xem Trợ Giúp):")
+            print(f"  {BOLD}1.{RESET} 🩺 {BOLD}Doctor{RESET}       - Kiểm tra chẩn đoán môi trường (Node, Python, Chrome, Git)")
+            print(f"  {BOLD}2.{RESET} 🚀 {BOLD}Setup{RESET}        - Thiết lập bảo vệ 1-click cho dự án kiểm thử mục tiêu")
+            print(f"  {BOLD}3.{RESET} 🔍 {BOLD}Lint{RESET}         - Quét phát hiện test pass ảo, 0 assert, sleep cứng")
+            print(f"  {BOLD}4.{RESET} 🛡️  {BOLD}Verify{RESET}       - Chạy kiểm tra 9 Cổng Chất Lượng DoD")
+            print(f"  {BOLD}5.{RESET} 🌐 {BOLD}Welcome{RESET}      - Mở trang Landing Page trực quan")
+            print(f"  {BOLD}6.{RESET} ❓ {BOLD}Help{RESET}         - Xem danh sách đầy đủ tất cả các lệnh CLI")
+            print(f"{BOLD}{CYAN}======================================================================{RESET}")
+            try:
+                choice = input(f"Nhập lựa chọn {BOLD}[1-6]{RESET} (mặc định: 6): ").strip()
+            except (EOFError, KeyboardInterrupt):
+                print()
+                sys.exit(0)
+
+            if choice == "1":
+                args.subcommand = "doctor"
+                return cmd_doctor(args)
+            elif choice == "2":
+                args.subcommand = "setup"
+                return cmd_setup(args)
+            elif choice == "3":
+                args.subcommand = "lint"
+                return cmd_lint(args)
+            elif choice == "4":
+                args.subcommand = "verify"
+                return cmd_verify(args)
+            elif choice == "5":
+                args.subcommand = "welcome"
+                return cmd_welcome(args)
+
         parser.print_help()
         print("\n💡 Tip: Run 'npx synapse-hub welcome' (or 'npm start') to launch the visual landing page.")
         sys.exit(0)