synapse-hub 2.1.1 → 2.2.0

package/tools/newman_analyzer.py

@@ -0,0 +1,385 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+tools/newman_analyzer.py — Enterprise Newman Test Results Analyzer & CI/CD Quality Gate
+---------------------------------------------------------------------------------------
+Parses Postman / Newman CLI execution reports (JSON format), calculates statistical
+pass/fail rates, triages failed assertions with root causes, evaluates latency SLAs,
+and enforces deterministic Quality Gates in CI/CD pipelines (Exit Code 0 vs 1).
+
+Features:
+  1. Universal Newman JSON Ingestion: Reads standard `--reporters json` exports.
+  2. Multi-Metric Aggregation:
+     - Total Executions, Passed/Failed Requests, Error Rate (%)
+     - Total pm.test Assertions, Failed Assertions, Pass Ratio (%)
+     - Latency statistics (Average, Min, Max response time in ms)
+  3. Failure Triage & RCA Engine:
+     - Isolates exact failing Request Name, HTTP Method, and URL
+     - Highlights exact `pm.test` assertion name and Chai error details
+     - Distinguishes between HTTP 4xx/5xx crashes vs Schema / Assertion mismatches
+  4. CI/CD SLA Quality Gate:
+     - `--max-failures <int>`: Zero-tolerance or configurable failure threshold
+     - `--sla-avg <ms>`: Average latency SLA threshold
+     - Returns deterministic Exit Code 0 on PASS, 1 on FAIL
+  5. PR Reporting: Generates clean GitHub/GitLab Markdown reports and JSON telemetry.
+
+Usage:
+  newman run collection.json -e env.json -r cli,json --reporter-json-export report.json
+  python tools/newman_analyzer.py report.json --max-failures 0 --sla-avg 500
+  agent-qa analyze-newman report.json --markdown pr_api_report.md
+"""
+
+import os
+import sys
+import json
+import argparse
+from typing import Dict, List, Any, Optional, Tuple
+
+# Enforce UTF-8 stdout encoding for Windows/macOS/Linux console compatibility
+if hasattr(sys.stdout, "reconfigure"):
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
+
+def parse_newman_json(report_path: str) -> Dict[str, Any]:
+    """Parses standard Newman JSON execution report."""
+    if not os.path.exists(report_path):
+        raise FileNotFoundError(f"Newman report file not found: {report_path}")
+
+    with open(report_path, "r", encoding="utf-8", errors="replace") as f:
+        data = json.load(f)
+
+    run = data.get("run", {})
+    stats = run.get("stats", {})
+    timings = run.get("timings", {})
+    executions = run.get("executions", [])
+    failures = run.get("failures", [])
+
+    # Stats extraction
+    req_stats = stats.get("requests", {})
+    total_requests = req_stats.get("total", 0)
+    failed_requests = req_stats.get("failed", 0)
+    passed_requests = total_requests - failed_requests
+
+    assert_stats = stats.get("assertions", {})
+    total_assertions = assert_stats.get("total", 0)
+    failed_assertions = assert_stats.get("failed", 0)
+    passed_assertions = total_assertions - failed_assertions
+
+    # Latencies
+    response_times = run.get("timings", {}).get("responseAverage", 0)
+    min_time = run.get("timings", {}).get("responseMin", 0)
+    max_time = run.get("timings", {}).get("responseMax", 0)
+
+    # Detailed Request Breakdown
+    request_rows: List[Dict[str, Any]] = []
+    for ex in executions:
+        item = ex.get("item", {})
+        req = ex.get("request", {})
+        resp = ex.get("response", {})
+
+        name = item.get("name", "Unknown Request")
+        method = req.get("method", "GET")
+        url_obj = req.get("url", {})
+        url_str = url_obj if isinstance(url_obj, str) else url_obj.get("raw", "/")
+        status_code = resp.get("code", 0) if resp else 0
+        resp_time = resp.get("responseTime", 0) if resp else 0
+
+        # Assertions inside this execution
+        assertions_list = ex.get("assertions", [])
+        ex_assert_total = len(assertions_list)
+        ex_assert_failed = sum(1 for a in assertions_list if a.get("error"))
+
+        request_rows.append({
+            "name": name,
+            "method": method,
+            "url": url_str,
+            "status_code": status_code,
+            "response_time_ms": resp_time,
+            "assertions_total": ex_assert_total,
+            "assertions_failed": ex_assert_failed,
+            "passed": (ex_assert_failed == 0 and status_code < 400 and status_code > 0)
+        })
+
+    # Triage Failures
+    triaged_failures: List[Dict[str, str]] = []
+    for f in failures:
+        err = f.get("error", {})
+        source = f.get("source", {})
+        cursor = f.get("cursor", {})
+        
+        req_name = source.get("name", cursor.get("ref", "Request"))
+        assert_name = err.get("test", err.get("name", "Assertion Failure"))
+        message = err.get("message", "Unknown assertion error")
+
+        triaged_failures.append({
+            "request_name": req_name,
+            "assertion_name": assert_name,
+            "message": message
+        })
+
+    error_rate = (failed_requests / total_requests * 100.0) if total_requests > 0 else 0.0
+    pass_ratio = (passed_assertions / total_assertions * 100.0) if total_assertions > 0 else 100.0
+
+    return {
+        "collection_name": data.get("collection", {}).get("info", {}).get("name", "Postman Collection"),
+        "total_requests": total_requests,
+        "failed_requests": failed_requests,
+        "passed_requests": passed_requests,
+        "error_rate_pct": round(error_rate, 2),
+        "total_assertions": total_assertions,
+        "failed_assertions": failed_assertions,
+        "passed_assertions": passed_assertions,
+        "assertion_pass_ratio_pct": round(pass_ratio, 2),
+        "latency": {
+            "avg_ms": round(float(response_times), 2),
+            "min_ms": round(float(min_time), 2),
+            "max_ms": round(float(max_time), 2)
+        },
+        "requests": request_rows,
+        "failures": triaged_failures
+    }
+
+
+def evaluate_newman_sla(
+    summary: Dict[str, Any],
+    max_failures: int = 0,
+    sla_avg: Optional[float] = None
+) -> Tuple[bool, List[str]]:
+    """Evaluates computed Newman summary against CI/CD SLA gates."""
+    violations: List[str] = []
+
+    total_failed = summary["failed_requests"] + summary["failed_assertions"]
+    if total_failed > max_failures:
+        violations.append(f"Failed Tests SLA Breached: {total_failed} failures > allowable limit ({max_failures})")
+
+    avg_latency = summary["latency"]["avg_ms"]
+    if sla_avg is not None and avg_latency > sla_avg:
+        violations.append(f"Average Latency SLA Breached: {avg_latency}ms > {sla_avg}ms threshold")
+
+    passed = (len(violations) == 0)
+    return passed, violations
+
+
+def format_cli_table(summary: Dict[str, Any]) -> str:
+    """Formats requests into a clean CLI table."""
+    headers = ["Method", "Request Name", "Status", "Latency", "Asserts (Pass/Fail)"]
+    col_w = [8, 36, 8, 12, 20]
+
+    lines = []
+    header_str = " | ".join(h.ljust(col_w[i]) for i, h in enumerate(headers))
+    sep_str = "-+-".join("-" * col_w[i] for i in range(len(headers)))
+
+    lines.append(header_str)
+    lines.append(sep_str)
+
+    for r in summary["requests"]:
+        req_name = r["name"]
+        if len(req_name) > 34:
+            req_name = req_name[:31] + "..."
+        assert_info = f"{r['assertions_total'] - r['assertions_failed']} / {r['assertions_total']}"
+        status_display = str(r["status_code"]) if r["status_code"] > 0 else "FAIL"
+
+        lines.append(" | ".join([
+            f"[{r['method']}]".ljust(col_w[0]),
+            req_name.ljust(col_w[1]),
+            status_display.center(col_w[2]),
+            f"{r['response_time_ms']} ms".rjust(col_w[3]),
+            assert_info.center(col_w[4])
+        ]))
+
+    return "\n".join(lines)
+
+
+def generate_markdown_report(summary: Dict[str, Any], passed: bool, violations: List[str]) -> str:
+    """Generates Pull Request Markdown report."""
+    status_badge = "✅ **PASSED (100% QUALITY GATE MET)**" if passed else "❌ **FAILED (QUALITY GATE BREACHED)**"
+
+    lines = [
+        f"# 📬 Postman / Newman API Automated Test Report: `{summary['collection_name']}`",
+        "",
+        f"- **Quality Gate Status:** {status_badge}",
+        f"- **Total Requests Executed:** `{summary['total_requests']}` ({summary['failed_requests']} failed)",
+        f"- **Total Assertions Checked:** `{summary['total_assertions']}` ({summary['failed_assertions']} failed)",
+        f"- **Assertion Pass Ratio:** `{summary['assertion_pass_ratio_pct']}%`",
+        f"- **Average Response Latency:** `{summary['latency']['avg_ms']} ms` (Min: `{summary['latency']['min_ms']} ms`, Max: `{summary['latency']['max_ms']} ms`)",
+        "",
+    ]
+
+    if violations:
+        lines.extend([
+            "### ⚠️ CI/CD Quality Gate Violations",
+            ""
+        ])
+        for v in violations:
+            lines.append(f"- 🔴 `{v}`")
+        lines.append("")
+
+    if summary["failures"]:
+        lines.extend([
+            "### 🔍 Failed Assertions Triage (Root Cause)",
+            "",
+            "| Request Name | Failed pm.test Assertion | Error Details |",
+            "| :--- | :--- | :--- |"
+        ])
+        for f in summary["failures"]:
+            lines.append(f"| `{f['request_name']}` | **{f['assertion_name']}** | `{f['message']}` |")
+        lines.append("")
+
+    lines.extend([
+        "### 📊 Detailed Endpoint Execution Breakdown",
+        "",
+        "| Method | Request Name | Status Code | Latency | Assertions | Result |",
+        "| :---: | :--- | :---: | :---: | :---: | :---: |"
+    ])
+
+    for r in summary["requests"]:
+        verdict = "✅ PASS" if r["passed"] else "❌ FAIL"
+        lines.append(f"| `{r['method']}` | {r['name']} | `{r['status_code']}` | `{r['response_time_ms']} ms` | `{r['assertions_total'] - r['assertions_failed']}/{r['assertions_total']}` | {verdict} |")
+
+    lines.extend([
+        "",
+        "---",
+        "*Report auto-generated by Synapse-Hub `newman_analyzer.py` - Enterprise API Quality Gate.*"
+    ])
+
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Postman / Newman Test Results Analyzer & CI/CD Quality Gatekeeper."
+    )
+    parser.add_argument("report_file", nargs="?", help="Path to Newman JSON report file (--reporters json).")
+    parser.add_argument("--max-failures", type=int, default=0, help="Allowable failed requests / assertions threshold. Default: 0.")
+    parser.add_argument("--sla-avg", type=float, default=None, help="Average Latency threshold in ms (fails if exceeded).")
+    parser.add_argument("--markdown", "-m", help="Path to export Markdown report.")
+    parser.add_argument("--json", "-j", help="Path to export JSON summary.")
+    parser.add_argument("--sample", action="store_true", help="Generate and analyze a mock Newman test dataset.")
+
+    args = parser.parse_args()
+
+    if args.sample or not args.report_file:
+        import tempfile
+        temp_file = os.path.join(tempfile.gettempdir(), "sample_newman_report.json")
+        sample_data = {
+            "collection": {"info": {"name": "Enterprise Banking & Billing API"}},
+            "run": {
+                "stats": {
+                    "requests": {"total": 4, "failed": 0},
+                    "assertions": {"total": 12, "failed": 1}
+                },
+                "timings": {
+                    "responseAverage": 185.5,
+                    "responseMin": 120.0,
+                    "responseMax": 340.0
+                },
+                "executions": [
+                    {
+                        "item": {"name": "1. User Authentication (Login)"},
+                        "request": {"method": "POST", "url": {"raw": "https://api.staging.enterprise.local/api/v1/auth/login"}},
+                        "response": {"code": 200, "responseTime": 145},
+                        "assertions": [
+                            {"assertion": "Status code is 200", "error": None},
+                            {"assertion": "Response time is below 500ms", "error": None},
+                            {"assertion": "Response matches OpenAPI JSON Schema", "error": None}
+                        ]
+                    },
+                    {
+                        "item": {"name": "2. Get Account Balance"},
+                        "request": {"method": "GET", "url": {"raw": "https://api.staging.enterprise.local/api/v1/accounts/me"}},
+                        "response": {"code": 200, "responseTime": 120},
+                        "assertions": [
+                            {"assertion": "Status code is 200", "error": None},
+                            {"assertion": "Response matches OpenAPI JSON Schema", "error": None}
+                        ]
+                    },
+                    {
+                        "item": {"name": "3. Transfer Funds (Dynamic Idempotency)"},
+                        "request": {"method": "POST", "url": {"raw": "https://api.staging.enterprise.local/api/v1/transfers"}},
+                        "response": {"code": 201, "responseTime": 340},
+                        "assertions": [
+                            {"assertion": "Status code is 201", "error": None},
+                            {"assertion": "Response matches OpenAPI JSON Schema", "error": None},
+                            {"assertion": "Transfer status is COMPLETED", "error": {"message": "expected 'PENDING' to equal 'COMPLETED'"}}
+                        ]
+                    },
+                    {
+                        "item": {"name": "4. Audit Transaction Log"},
+                        "request": {"method": "GET", "url": {"raw": "https://api.staging.enterprise.local/api/v1/transfers/last"}},
+                        "response": {"code": 200, "responseTime": 137},
+                        "assertions": [
+                            {"assertion": "Status code is 200", "error": None},
+                            {"assertion": "Response matches OpenAPI JSON Schema", "error": None}
+                        ]
+                    }
+                ],
+                "failures": [
+                    {
+                        "source": {"name": "3. Transfer Funds (Dynamic Idempotency)"},
+                        "error": {
+                            "test": "Transfer status is COMPLETED",
+                            "message": "expected 'PENDING' to equal 'COMPLETED'"
+                        }
+                    }
+                ]
+            }
+        }
+        with open(temp_file, "w", encoding="utf-8") as f:
+            json.dump(sample_data, f, indent=2)
+        args.report_file = temp_file
+        print(f"🔬 [SAMPLE MODE] Generated synthetic Newman report: {temp_file}")
+
+    summary = parse_newman_json(args.report_file)
+    passed, violations = evaluate_newman_sla(
+        summary,
+        max_failures=args.max_failures,
+        sla_avg=args.sla_avg
+    )
+
+    print("\n" + "=" * 90)
+    print(f"  POSTMAN / NEWMAN API AUTOMATED TEST MATRIX: {summary['collection_name']}")
+    print("=" * 90)
+    print(format_cli_table(summary))
+    print("=" * 90)
+    print(f"Total Requests   : {summary['total_requests']} (Passed: {summary['passed_requests']} | Failed: {summary['failed_requests']})")
+    print(f"Total Assertions : {summary['total_assertions']} (Passed: {summary['passed_assertions']} | Failed: {summary['failed_assertions']})")
+    print(f"Pass Ratio       : {summary['assertion_pass_ratio_pct']}% | Avg Latency: {summary['latency']['avg_ms']} ms")
+    print("-" * 90)
+
+    # Print SLA Verdict
+    print(f"🎯 [QUALITY GATE SLA VERDICT]")
+    if passed:
+        print("✅ ALL API FUNCTIONAL & SLA GATES PASSED! Safe to merge/deploy.")
+    else:
+        print("❌ API QUALITY GATE BREACHED:")
+        for v in violations:
+            print(f"   🔴 {v}")
+        if summary["failures"]:
+            print("\n🔍 Failing Assertions Breakdown:")
+            for f in summary["failures"]:
+                print(f"   • [{f['request_name']}] -> {f['assertion_name']}: {f['message']}")
+
+    # Export Markdown
+    if args.markdown:
+        md = generate_markdown_report(summary, passed, violations)
+        os.makedirs(os.path.dirname(os.path.abspath(args.markdown)) or ".", exist_ok=True)
+        with open(args.markdown, "w", encoding="utf-8") as f:
+            f.write(md)
+        print(f"\n📄 Markdown Report exported: {args.markdown}")
+
+    # Export JSON
+    if args.json:
+        os.makedirs(os.path.dirname(os.path.abspath(args.json)) or ".", exist_ok=True)
+        with open(args.json, "w", encoding="utf-8") as f:
+            json.dump(summary, f, indent=2)
+        print(f"📊 JSON Metrics exported: {args.json}")
+
+    sys.exit(0 if passed else 1)
+
+
+if __name__ == "__main__":
+    main()

package/tools/setup_project.py

@@ -8,8 +8,10 @@ Dispatched automatically by AI Agents (Zero-Command Protocol) or via 'agent-qa s
 Automated actions:
   1. Detects project tech stack (Katalon, Playwright, Cypress, Pytest).
   2. Generates tailored 'PROJECT_AI_GUIDE.md' if missing.
-  3. Installs automated Git Pre-Push Hook (.git/hooks/pre-push) for zero-leakage protection.
-  4. Triggers 5-in-1 Health Audit (tools/analyze_project.py):
+  3. Deploys Universal AI Bridges (.cursor/rules, CLAUDE.md, .github/copilot-instructions.md, .windsurfrules).
+  4. Injects Antigravity Global Plugin (~/.gemini/config/plugins/synapse-hub).
+  5. Installs automated Git Pre-Push Hook (.git/hooks/pre-push) for zero-leakage protection.
+  6. Triggers 5-in-1 Health Audit (tools/analyze_project.py):
      - Maps AST method signatures (repo_map.txt).
      - Scans fake passes (infer_linter).
      - Audits database teardown hygiene (trace_data_flow).
@@ -54,17 +56,29 @@ def resolve_target_repo(cli_target=None, cli_repo=None):
         resolved = os.path.abspath(chosen)
         if not os.path.exists(resolved):
             raise FileNotFoundError(f"Target repository path not found: {resolved}")
+        if resolved.lower() == HUB_ROOT.lower():
+            print(f"{RED}{BOLD}X [CWD CONFUSION GUARD] Target repository cannot be Synapse-Hub itself!{RESET}")
+            print("  Synapse-Hub is the centralized skill hub, not an automation target project.")
+            print("   Please specify a target project: python tools/setup_project.py --target /path/to/target-project")
+            sys.exit(1)
         return resolved
 
     env_dir = os.environ.get("TARGET_PROJECT_DIR")
     if env_dir and os.path.exists(env_dir):
-        return os.path.abspath(env_dir)
+        resolved_env = os.path.abspath(env_dir)
+        if resolved_env.lower() == HUB_ROOT.lower():
+            print(f"{RED}{BOLD}X [CWD CONFUSION GUARD] TARGET_PROJECT_DIR points to Synapse-Hub itself!{RESET}")
+            sys.exit(1)
+        return resolved_env
 
     cwd = os.path.abspath(os.getcwd())
     if cwd.lower() != HUB_ROOT.lower():
         return cwd
 
-    return HUB_ROOT
+    print(f"{RED}{BOLD}X [CWD CONFUSION GUARD] Current working directory is Synapse-Hub!{RESET}")
+    print("  You must run setup inside your target project folder or supply --target:")
+    print("   python tools/setup_project.py --target <path_to_target_project>")
+    sys.exit(1)
 
 
 def detect_tech_stack(target_dir):
@@ -175,19 +189,27 @@ def install_git_pre_push_hook(target_dir):
     analyze_script = os.path.join(SCRIPT_DIR, "analyze_project.py").replace("\\", "/")
 
     hook_content = f"""#!/bin/sh
-# Automated Zero-Leakage Pre-Push Hook (Installed by Enterprise Agent-QA)
-# Automatically enforces 7 Quality Gates and syncs project health before pushing.
-
-echo "\\n[AI-GUARD] Running Pre-Push Verification (7 Quality Gates DoD)..."
-python3 "{verify_all_script}" || python "{verify_all_script}"
+# Automated Zero-Leakage Pre-Push Hook (Installed by Synapse-Hub)
+# Enforces 8 Quality Gates DoD and syncs project intelligence before pushing.
+
+echo "\\n[AI-GUARD] Running Pre-Push Verification (8 Quality Gates DoD)..."
+if command -v npx >/dev/null 2>&1; then
+    npx synapse-hub verify
+elif [ -f "{verify_all_script}" ]; then
+    python3 "{verify_all_script}" || python "{verify_all_script}"
+fi
 if [ $? -ne 0 ]; then
-    echo "\\n[AI-GUARD - REJECTED] Git Push aborted: 7 Quality Gates verification failed!"
-    echo "Please fix defects or run 'agent-qa verify' locally before pushing.\\n"
+    echo "\\n[AI-GUARD - REJECTED] Git Push aborted: Quality Gates verification failed!"
+    echo "Please fix defects or run 'npx synapse-hub verify' locally before pushing.\\n"
     exit 1
 fi
 
-echo "[AI-GUARD - PASSED] 7 Quality Gates satisfied. Syncing project health report..."
-python3 "{analyze_script}" || python "{analyze_script}"
+echo "[AI-GUARD - PASSED] 8 Quality Gates satisfied. Syncing project health report..."
+if command -v npx >/dev/null 2>&1; then
+    npx synapse-hub analyze
+elif [ -f "{analyze_script}" ]; then
+    python3 "{analyze_script}" || python "{analyze_script}"
+fi
 echo "[AI-GUARD - READY] Pushing to remote...\\n"
 exit 0
 """
@@ -208,6 +230,151 @@ exit 0
         return False
 
 
+def inject_antigravity_global_plugin():
+    """
+    Automatically injects Synapse-Hub into Antigravity's Global Plugin Directory
+    (~/.gemini/config/plugins/synapse-hub).
+    Ensures that running `npx synapse-hub setup` activates the 27 skills and 6 subagents
+    globally across ALL projects in Google Antigravity.
+    """
+    try:
+        plugins_dir = os.path.expanduser("~/.gemini/config/plugins")
+        target_plugin_dir = os.path.join(plugins_dir, "synapse-hub")
+        os.makedirs(target_plugin_dir, exist_ok=True)
+
+        # 1. plugin.json
+        src_plugin_json = os.path.join(HUB_ROOT, "plugin.json")
+        dst_plugin_json = os.path.join(target_plugin_dir, "plugin.json")
+        if os.path.exists(src_plugin_json):
+            if not os.path.exists(dst_plugin_json) or not os.path.samefile(src_plugin_json, dst_plugin_json):
+                shutil.copy2(src_plugin_json, dst_plugin_json)
+
+        # 2. README.md
+        src_readme = os.path.join(HUB_ROOT, "README.md")
+        dst_readme = os.path.join(target_plugin_dir, "README.md")
+        if os.path.exists(src_readme):
+            if not os.path.exists(dst_readme) or not os.path.samefile(src_readme, dst_readme):
+                shutil.copy2(src_readme, dst_readme)
+
+        # Helper to sync directory (junction or copy)
+        def sync_dir(src, dst):
+            if not os.path.exists(src):
+                return
+            if os.path.exists(dst) and os.path.samefile(src, dst):
+                return
+            if os.path.islink(dst):
+                try:
+                    os.unlink(dst)
+                except Exception:
+                    pass
+            if sys.platform == "win32":
+                try:
+                    import _winapi
+                    if not os.path.exists(dst):
+                        _winapi.CreateJunction(src, dst)
+                        return
+                except Exception:
+                    pass
+            shutil.copytree(src, dst, dirs_exist_ok=True, ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.tmp"))
+
+        sync_dir(os.path.join(HUB_ROOT, ".agents", "skills"), os.path.join(target_plugin_dir, "skills"))
+        sync_dir(os.path.join(HUB_ROOT, ".agents", "agents"), os.path.join(target_plugin_dir, "agents"))
+        sync_dir(os.path.join(HUB_ROOT, "tools"), os.path.join(target_plugin_dir, "tools"))
+
+        # 3. Rules (AGENTS.md)
+        dst_rules = os.path.join(target_plugin_dir, "rules")
+        os.makedirs(dst_rules, exist_ok=True)
+        src_agents_md = os.path.join(HUB_ROOT, "AGENTS.md")
+        dst_agents_md = os.path.join(dst_rules, "AGENTS.md")
+        if os.path.exists(src_agents_md):
+            if not os.path.exists(dst_agents_md) or not os.path.samefile(src_agents_md, dst_agents_md):
+                shutil.copy2(src_agents_md, dst_agents_md)
+
+        print(f"  {GREEN}[OK] Injected Antigravity Global Plugin:{RESET} {target_plugin_dir}")
+        return True
+    except Exception as e:
+        print(f"  ⚠️ Antigravity Global Plugin notice: {e}")
+        return False
+
+
+def install_universal_ai_bridges(target_dir):
+    """
+    Deploys Universal AI Bridge configuration files into the target project workspace
+    for seamless integration with Cursor, Claude Code, GitHub Copilot, and Windsurf.
+    """
+    bridges_dir = os.path.join(TEMPLATES_DIR, "ai_bridges")
+    if not os.path.exists(bridges_dir):
+        return False
+
+    deployed = []
+
+    # 1. Cursor (.cursor/rules/synapse-qa.mdc)
+    cursor_dir = os.path.join(target_dir, ".cursor", "rules")
+    os.makedirs(cursor_dir, exist_ok=True)
+    src_cursor = os.path.join(bridges_dir, "cursor_synapse_qa.mdc")
+    dst_cursor = os.path.join(cursor_dir, "synapse-qa.mdc")
+    if os.path.exists(src_cursor):
+        shutil.copy2(src_cursor, dst_cursor)
+        deployed.append("Cursor (.cursor/rules/synapse-qa.mdc)")
+
+    # 2. Claude Code (CLAUDE.md)
+    dst_claude = os.path.join(target_dir, "CLAUDE.md")
+    src_claude = os.path.join(bridges_dir, "CLAUDE.md")
+    if os.path.exists(src_claude):
+        if not os.path.exists(dst_claude):
+            shutil.copy2(src_claude, dst_claude)
+            deployed.append("Claude Code (CLAUDE.md)")
+        else:
+            with open(dst_claude, "r", encoding="utf-8", errors="ignore") as f:
+                c_content = f.read()
+            if "Synapse-Hub" not in c_content:
+                with open(src_claude, "r", encoding="utf-8") as f:
+                    append_data = f.read()
+                with open(dst_claude, "a", encoding="utf-8") as f:
+                    f.write("\n\n" + append_data)
+                deployed.append("Claude Code (appended to CLAUDE.md)")
+
+    # 3. GitHub Copilot (.github/copilot-instructions.md)
+    github_dir = os.path.join(target_dir, ".github")
+    os.makedirs(github_dir, exist_ok=True)
+    dst_copilot = os.path.join(github_dir, "copilot-instructions.md")
+    src_copilot = os.path.join(bridges_dir, "copilot-instructions.md")
+    if os.path.exists(src_copilot):
+        if not os.path.exists(dst_copilot):
+            shutil.copy2(src_copilot, dst_copilot)
+            deployed.append("GitHub Copilot (.github/copilot-instructions.md)")
+        else:
+            with open(dst_copilot, "r", encoding="utf-8", errors="ignore") as f:
+                cp_content = f.read()
+            if "Synapse-Hub" not in cp_content:
+                with open(src_copilot, "r", encoding="utf-8") as f:
+                    append_data = f.read()
+                with open(dst_copilot, "a", encoding="utf-8") as f:
+                    f.write("\n\n" + append_data)
+                deployed.append("GitHub Copilot (appended to copilot-instructions.md)")
+
+    # 4. Windsurf (.windsurfrules)
+    dst_windsurf = os.path.join(target_dir, ".windsurfrules")
+    src_windsurf = os.path.join(bridges_dir, "windsurfrules")
+    if os.path.exists(src_windsurf):
+        if not os.path.exists(dst_windsurf):
+            shutil.copy2(src_windsurf, dst_windsurf)
+            deployed.append("Windsurf (.windsurfrules)")
+        else:
+            with open(dst_windsurf, "r", encoding="utf-8", errors="ignore") as f:
+                w_content = f.read()
+            if "Synapse-Hub" not in w_content:
+                with open(src_windsurf, "r", encoding="utf-8") as f:
+                    append_data = f.read()
+                with open(dst_windsurf, "a", encoding="utf-8") as f:
+                    f.write("\n\n" + append_data)
+                deployed.append("Windsurf (appended to .windsurfrules)")
+
+    if deployed:
+        print(f"  {GREEN}[OK] Deployed Universal AI Bridges:{RESET} {', '.join(deployed)}")
+    return True
+
+
 def run_setup(target_repo):
     """Main execution entrypoint for automated project setup."""
     print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
@@ -221,16 +388,32 @@ def run_setup(target_repo):
     print(f"📂 Structure Scope : Pages: `{stack_info['page_dir']}` | Tests: `{stack_info['test_dir']}`\n")
 
     # 2. Ensure PROJECT_AI_GUIDE.md & PROJECT_STATE.md
-    print(f"{BOLD}[1/3] Checking Project AI Guide & State Anchor...{RESET}")
+    print(f"{BOLD}[1/5] Checking Project AI Guide & State Anchor...{RESET}")
     guide_created = ensure_project_ai_guide(target_repo, stack_info)
     project_state.init_state(target_repo)
 
-    # 3. Install Pre-Push Git Hook
-    print(f"\n{BOLD}[2/3] Installing Zero-Leakage Git Pre-Push Hook...{RESET}")
+    # 3. Deploy Universal AI Bridges (Cursor, Claude Code, GitHub Copilot, Windsurf)
+    print(f"\n{BOLD}[2/5] Deploying Universal AI Bridges (Cursor, Claude, Copilot, Windsurf)...{RESET}")
+    bridges_deployed = install_universal_ai_bridges(target_repo)
+
+    # 4. Inject Antigravity Global Plugin
+    print(f"\n{BOLD}[3/5] Injecting Antigravity Global Plugin (~/.gemini/config/plugins)...{RESET}")
+    plugin_injected = inject_antigravity_global_plugin()
+
+    # 4.1 Initialize Central Agent Memory (SQLite Cache)
+    try:
+        import cache_resolver
+        cache_resolver.init_db(seed=True)
+        print(f"  {GREEN}[OK] Initialized Central Agent Memory (SQLite):{RESET} ~/.agent_memory/global_cache.db")
+    except Exception as e:
+        print(f"  ⚠️ Could not initialize memory cache: {e}")
+
+    # 5. Install Pre-Push Git Hook
+    print(f"\n{BOLD}[4/5] Installing Zero-Leakage Git Pre-Push Hook...{RESET}")
     hook_installed = install_git_pre_push_hook(target_repo)
 
-    # 4. Run 5-in-1 Comprehensive Health & AST Analysis
-    print(f"\n{BOLD}[3/3] Executing Initial Health Audit & AST Mapping...{RESET}")
+    # 6. Run 5-in-1 Comprehensive Health & AST Analysis
+    print(f"\n{BOLD}[5/5] Executing Initial Health Audit & AST Mapping...{RESET}")
     analysis_code = analyze_project.run_full_analysis(target_repo)
 
     print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
@@ -238,6 +421,8 @@ def run_setup(target_repo):
     print(f"{BOLD}{CYAN}======================================================================{RESET}")
     print(f"  Target Framework    : {stack_info['framework']}")
     print(f"  AI Project Guide    : {os.path.join(target_repo, 'PROJECT_AI_GUIDE.md')}")
+    print(f"  Universal Bridges   : Cursor (.cursor/rules), Claude Code, Copilot, Windsurf")
+    print(f"  Antigravity Plugin  : {'ACTIVE (~/.gemini/config/plugins/synapse-hub)' if plugin_injected else 'STANDALONE'}")
     print(f"  AST Method Map      : {os.path.join(target_repo, 'repo_map.txt')}")
     print(f"  Health Report       : {os.path.join(target_repo, 'PROJECT_HEALTH_REPORT.md')}")
     print(f"  Pre-Push Sentinel   : {'ACTIVE (.git/hooks/pre-push)' if hook_installed else 'MANUAL (No .git folder)'}")