synapse-hub 2.7.0 → 3.0.1

package/tools/contract_validator.py

@@ -0,0 +1,141 @@
+#!/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)
+
+"""
+Swarm Data Contract Validator (Single Front-Door Integrity Guard)
+-----------------------------------------------------------------
+Validates the JSON Data Contract emitted by `live-explorer` before
+`pom-crafter` consumes it for Clean POM code synthesis.
+Ensures zero locator guessing, validates semantic ARIA roles, and enforces
+latency measurement (< 200ms) for durable selectors.
+"""
+
+import os
+import sys
+import json
+import argparse
+from typing import Dict, Any, List, Tuple
+
+# 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
+
+CONTRACT_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "SelectorContract",
+    "type": "object",
+    "required": ["url", "screen_name", "elements"],
+    "properties": {
+        "url": {"type": "string"},
+        "screen_name": {"type": "string"},
+        "viewport": {
+            "type": "object",
+            "properties": {
+                "width": {"type": "integer"},
+                "height": {"type": "integer"}
+            }
+        },
+        "elements": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+                "type": "object",
+                "required": ["name", "role"],
+                "properties": {
+                    "name": {"type": "string"},
+                    "role": {"type": "string"},
+                    "selector": {"type": "string"},
+                    "target": {"type": "string"},
+                    "latency_ms": {"type": "number"},
+                    "action_type": {"type": "string"}
+                }
+            }
+        }
+    }
+}
+
+
+def validate_contract_dict(data: Dict[str, Any]) -> Tuple[bool, List[str]]:
+    """Validates contract structure without external dependencies."""
+    errors = []
+    if not isinstance(data, dict):
+        return False, ["Root contract must be a JSON object."]
+
+    # Required top-level fields
+    for field in ("url", "screen_name", "elements"):
+        if field not in data:
+            errors.append(f"Missing required top-level field: '{field}'")
+
+    if "elements" in data:
+        elements = data["elements"]
+        if not isinstance(elements, list) or len(elements) == 0:
+            errors.append("'elements' must be a non-empty list of interactive components.")
+        else:
+            for idx, el in enumerate(elements):
+                if not isinstance(el, dict):
+                    errors.append(f"Element at index {idx} must be a dictionary object.")
+                    continue
+                if "name" not in el or not el["name"]:
+                    errors.append(f"Element at index {idx} missing 'name' identifier.")
+                if "role" not in el or not el["role"]:
+                    errors.append(f"Element at index {idx} missing ARIA 'role' classification.")
+                if "selector" not in el and "target" not in el:
+                    errors.append(f"Element '{el.get('name', f'index_{idx}')}' must provide 'selector' or 'target'.")
+
+                latency = el.get("latency_ms")
+                if latency is not None and isinstance(latency, (int, float)):
+                    if latency > 200:
+                        errors.append(
+                            f"Element '{el.get('name')}' latency ({latency}ms) exceeds the 200ms latency budget."
+                        )
+
+    return len(errors) == 0, errors
+
+
+def validate_contract_file(file_path: str) -> Tuple[bool, List[str]]:
+    """Loads and validates a contract file from disk."""
+    if not os.path.exists(file_path):
+        return False, [f"Contract file does not exist: {file_path}"]
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        return validate_contract_dict(data)
+    except json.JSONDecodeError as err:
+        return False, [f"Malformed JSON syntax: {err}"]
+    except OSError as err:
+        return False, [f"File read error: {err}"]
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Swarm Data Contract Validator")
+    parser.add_argument("contract_path", nargs="?", default=None, help="Path to JSON Data Contract file")
+    parser.add_argument("--schema", action="store_true", help="Print standard JSON schema and exit")
+    args = parser.parse_args()
+
+    if args.schema:
+        print(json.dumps(CONTRACT_SCHEMA, indent=2))
+        return 0
+
+    if not args.contract_path:
+        parser.print_help()
+        return 1
+
+    valid, errors = validate_contract_file(args.contract_path)
+    if valid:
+        print(f"✅ [VALID CONTRACT] '{args.contract_path}' is ready for Clean POM synthesis.")
+        return 0
+    else:
+        print(f"❌ [INVALID CONTRACT] '{args.contract_path}' contains {len(errors)} violation(s):")
+        for err in errors:
+            print(f"   • {err}")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/core/__init__.py

@@ -0,0 +1,52 @@
+"""
+Synapse Hub — Core Execution Engines & Verification Sentinels (tools.core)
+--------------------------------------------------------------------------
+Domain package grouping all CLI routers, Definition-of-Done Quality Gate
+orchestrators, AST scanners, and autonomous subagent execution bridges.
+"""
+
+from tools import (
+    analyze_project,
+    bump_version,
+    check_env,
+    cli,
+    count_tokens,
+    debt_harvester,
+    distill_log,
+    micro_mutator,
+    project_state,
+    repo_map,
+    safety_firewall,
+    senior_code_review,
+    setup_project,
+    skill_vault,
+    sync_agent_rules,
+    test_impact,
+    test_memory_os,
+    universal_ir,
+    update_sentinel,
+    verify_all,
+)
+
+__all__ = [
+    "analyze_project",
+    "bump_version",
+    "check_env",
+    "cli",
+    "count_tokens",
+    "debt_harvester",
+    "distill_log",
+    "micro_mutator",
+    "project_state",
+    "repo_map",
+    "safety_firewall",
+    "senior_code_review",
+    "setup_project",
+    "skill_vault",
+    "sync_agent_rules",
+    "test_impact",
+    "test_memory_os",
+    "universal_ir",
+    "update_sentinel",
+    "verify_all",
+]

package/tools/count_tokens.py

@@ -39,9 +39,9 @@ import hashlib
 import sqlite3
 import argparse
 from datetime import datetime, timezone, timedelta
-from typing import Dict, List, Any, Optional, Tuple
+from typing import Dict, List, Any, Optional
 
-PRICING_TABLE = {
+PRICING_TABLE: Dict[str, Dict[str, Any]] = {
     "gemini-flash": {
         "name": "Google Gemini 2.5/3.x Flash",
         "input_per_m": 0.075,
@@ -140,7 +140,7 @@ def get_budget_config() -> Dict[str, int]:
                     "budget_7d": data.get("budget_7d", DEFAULT_7D_BUDGET),
                 }
         except (OSError, json.JSONDecodeError):
-            custom_budgets = None
+            _ = False
     return {
         "budget_5h": DEFAULT_5H_BUDGET,
         "budget_7d": DEFAULT_7D_BUDGET,
@@ -198,17 +198,19 @@ class AntigravityAdapter:
         if db_path:
             try:
                 conn = sqlite3.connect(db_path)
-                cursor = conn.cursor()
-                cursor.execute("SELECT conversation_id, title, step_count, last_modified_time FROM conversation_summaries")
-                for row in cursor.fetchall():
-                    title_map[row[0]] = {
-                        "title": row[1],
-                        "step_count": row[2],
-                        "last_modified": row[3],
-                    }
-                conn.close()
+                try:
+                    cursor = conn.cursor()
+                    cursor.execute("SELECT conversation_id, title, step_count, last_modified_time FROM conversation_summaries")
+                    for row in cursor.fetchall():
+                        title_map[row[0]] = {
+                            "title": row[1],
+                            "step_count": row[2],
+                            "last_modified": row[3],
+                        }
+                finally:
+                    conn.close()
             except (sqlite3.Error, OSError):
-                conn_closed = True
+                _ = False
 
         conversations = []
         for entry in os.listdir(brain_dir):
@@ -240,7 +242,7 @@ class AntigravityAdapter:
             return {"error": f"Transcript not found at {transcript_path}"}
 
         turns = []
-        current_turn = None
+        current_turn: Optional[Dict[str, Any]] = None
         total_input = 0
         total_cache = 0
         total_output = 0
@@ -388,7 +390,7 @@ class AntigravityAdapter:
                             usage_hours["cache"] += cache_tok
                             usage_hours["output"] += out_tok
             except (OSError, UnicodeDecodeError):
-                transcript_read = False
+                _ = False
 
         budgets = get_budget_config()
         b_5h = budgets["budget_5h"]
@@ -452,7 +454,7 @@ class CursorAdapter:
             return []
 
         pattern = os.path.join(projects_dir, "*", "agent-transcripts", "*", "*.jsonl")
-        sessions = []
+        sessions: List[Dict[str, Any]] = []
         for fpath in glob.glob(pattern):
             try:
                 mtime = os.path.getmtime(fpath)
@@ -493,7 +495,7 @@ class CursorAdapter:
             return {"error": f"Transcript not found at {transcript_path}"}
 
         turns = []
-        current_turn = None
+        current_turn: Optional[Dict[str, Any]] = None
         total_input = 0
         total_output = 0
         total_cache = 0
@@ -608,7 +610,7 @@ class ClaudeCodeAdapter:
 
     @classmethod
     def get_sessions(cls) -> List[Dict[str, Any]]:
-        sessions = []
+        sessions: List[Dict[str, Any]] = []
         home = os.path.expanduser("~")
         # Search candidate directories
         patterns = [
@@ -665,7 +667,7 @@ def detect_platform_from_file(file_path: str) -> str:
                 if "claude" in line.lower():
                     return "claude"
     except (OSError, UnicodeDecodeError):
-        model_detected = None
+        _ = False
     return "antigravity"
 
 
@@ -997,7 +999,7 @@ def export_opentelemetry_genai_spans(parsed: Dict[str, Any], session_id: str = "
     }
     gen_ai_system = system_map.get(platform, "google")
 
-    spans = []
+    spans: List[Dict[str, Any]] = []
     turns = parsed.get("turns", [])
     for idx, turn in enumerate(turns, 1):
         turn_span_id = hashlib.md5(f"{session_id}_turn_{idx}".encode('utf-8'), usedforsecurity=False).hexdigest()[:16]