blasttrace 1.2.0__py2.py3-none-any.whl

blasttrace/server.py

@@ -0,0 +1,935 @@
+"""
+BlastTrace FastMCP Server & Standalone CLI
+Pre-Edit Full-Stack Breaking-Change & Contract Blast-Radius Engine.
+"""
+
+import json
+import os
+import subprocess
+import sys
+from typing import List, Dict, Any, Optional
+
+# Ensure project root and build directories are on sys.path
+PACKAGE_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT_DIR = os.path.dirname(PACKAGE_DIR)
+for candidate in (ROOT_DIR, os.path.join(ROOT_DIR, "build")):
+    if candidate not in sys.path:
+        sys.path.insert(0, candidate)
+
+from blasttrace.license import (
+    activate_license,
+    deactivate_license,
+    verify_license,
+    get_license_status,
+    get_runtime_token,
+    generate_tester_license_key,
+)
+from blasttrace.parsers.contract_linker import (
+    build_fullstack_topology,
+    resolve_entity_id,
+)
+from blasttrace.parsers.sql_schema_parser import parse_schema_file
+from blasttrace.parsers.python_ast_parser import parse_python_file
+from blasttrace.parsers.ts_react_parser import parse_ts_react_file
+from blasttrace.parsers.api_route_parser import parse_api_file
+from blasttrace.classifier import (
+    classify_proposed_edit,
+    format_evidence_chains,
+)
+from blasttrace.visualizer import (
+    generate_mermaid_blast_radius,
+    generate_mermaid_contract_chain,
+    generate_mermaid_cycles,
+)
+from blasttrace.remediation import (
+    generate_surgical_sync_plan,
+    generate_cycle_refactoring_plan,
+)
+
+from collections import deque
+
+class _DeterministicReachabilityEngine:
+    """
+    BlastTrace Native Core — Pure-environment deterministic dependency reachability engine.
+    Ensures seamless cross-platform execution on Windows, macOS, and Linux without external build tools.
+    """
+    def __init__(self):
+        self._topology_links: Dict[str, List[str]] = {}
+
+    def add_edge(self, u: str, v: str) -> None:
+        if u not in self._topology_links:
+            self._topology_links[u] = []
+        if v not in self._topology_links[u]:
+            self._topology_links[u].append(v)
+        if v not in self._topology_links:
+            self._topology_links[v] = []
+
+    def find_shortest_path(self, start: str, target: str) -> List[str]:
+        if start not in self._topology_links or target not in self._topology_links:
+            return []
+        origin_hop: Dict[str, str] = {}
+        seen = {start}
+        horizon = deque([start])
+        reached = False
+        while horizon:
+            curr = horizon.popleft()
+            if curr == target:
+                reached = True
+                break
+            for nxt in self._topology_links.get(curr, []):
+                if nxt not in seen:
+                    seen.add(nxt)
+                    origin_hop[nxt] = curr
+                    horizon.append(nxt)
+        if not reached:
+            return []
+        trace_seq = []
+        curr = target
+        while curr != start:
+            trace_seq.append(curr)
+            curr = origin_hop[curr]
+        trace_seq.append(start)
+        trace_seq.reverse()
+        return trace_seq
+
+    def trace_blast_radius_paths(self, start: str, max_hops: int = 4) -> List[List[str]]:
+        all_chains: List[List[str]] = []
+        if start not in self._topology_links or max_hops <= 0:
+            return all_chains
+        origin_hop: Dict[str, str] = {}
+        hop_depth: Dict[str, int] = {start: 0}
+        horizon = deque([start])
+        while horizon:
+            curr = horizon.popleft()
+            d = hop_depth[curr]
+            if d >= max_hops:
+                continue
+            for nxt in self._topology_links.get(curr, []):
+                if nxt not in hop_depth:
+                    hop_depth[nxt] = d + 1
+                    origin_hop[nxt] = curr
+                    horizon.append(nxt)
+                    chain = []
+                    walk = nxt
+                    while walk != start:
+                        chain.append(walk)
+                        walk = origin_hop[walk]
+                    chain.append(start)
+                    chain.reverse()
+                    all_chains.append(chain)
+        return all_chains
+
+    def detect_circular_dependencies(self, runtime_token: str = "") -> List[List[str]]:
+        idx_map: Dict[str, int] = {}
+        boundary_map: Dict[str, int] = {}
+        active_frame: Dict[str, bool] = {}
+        frame_st: List[str] = []
+        seq_counter = [0]
+        detected_rings: List[List[str]] = []
+
+        def _eval_recursive_ring(u: str):
+            seq_counter[0] += 1
+            idx_map[u] = boundary_map[u] = seq_counter[0]
+            frame_st.append(u)
+            active_frame[u] = True
+
+            for v in self._topology_links.get(u, []):
+                if v not in idx_map:
+                    _eval_recursive_ring(v)
+                    boundary_map[u] = min(boundary_map[u], boundary_map[v])
+                elif active_frame.get(v, False):
+                    boundary_map[u] = min(boundary_map[u], idx_map[v])
+
+            if boundary_map[u] == idx_map[u]:
+                ring_group = []
+                while True:
+                    v = frame_st.pop()
+                    active_frame[v] = False
+                    ring_group.append(v)
+                    if u == v:
+                        break
+                if len(ring_group) > 1 or (u in self._topology_links.get(u, [])):
+                    detected_rings.append(ring_group)
+
+        for node in list(self._topology_links.keys()):
+            if node not in idx_map:
+                _eval_recursive_ring(node)
+
+        return detected_rings
+
+
+try:
+    import blasttrace_cpp_core
+    CppBlastEngine = blasttrace_cpp_core.CppBlastEngine
+except ImportError:
+    CppBlastEngine = _DeterministicReachabilityEngine
+
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="BlastTrace")
+IS_PRO_TIER = False
+
+
+def _populate_cpp_engine(topology: Dict[str, Any]) -> Any:
+    """Instantiates and populates the BlastTrace Native Core from parsed full-stack topology."""
+    engine = CppBlastEngine()
+    for edge in topology.get("edges", []):
+        engine.add_edge(edge["source"], edge["target"])
+    return engine
+
+
+def _pro_gate_error(tool_label: str) -> str:
+    return json.dumps(
+        {
+            "error": "Pro License Required",
+            "engine": "BlastTrace Native Core",
+            "tier": "COMMUNITY",
+            "message": f"{tool_label} requires an active BlastTrace Pro license. Run 'blasttrace activate <KEY>' to unlock.",
+        },
+        indent=2,
+    )
+
+
+# ============================================================================
+# FREE COMMUNITY TIER TOOLS (2 Tools)
+# ============================================================================
+
+
+@mcp.tool()
+def index_repository_topology(repo_path: str) -> str:
+    """
+    Scans the repository across Database, Backend, API, Frontend, and Tests,
+    populates the BlastTrace Native Core, and returns structural summary counts.
+    """
+    topology = build_fullstack_topology(repo_path)
+    if "error" in topology:
+        return json.dumps({"engine": "BlastTrace Native Core", "error": topology["error"]}, indent=2)
+
+    _populate_cpp_engine(topology)
+    layer_counts: Dict[str, int] = {"database": 0, "backend": 0, "api": 0, "frontend": 0, "tests": 0}
+    for n in topology["nodes"]:
+        layer = n.get("layer", "backend")
+        layer_counts[layer] = layer_counts.get(layer, 0) + 1
+
+    return json.dumps(
+        {
+            "status": "Indexed",
+            "engine": "BlastTrace Native Core",
+            "tier": "PRO" if verify_license() else "COMMUNITY",
+            "repo_root": topology["repo_root"],
+            "node_count": len(topology["nodes"]),
+            "edge_count": len(topology["edges"]),
+            "layer_breakdown": layer_counts,
+            "tables_indexed": list(topology["db_tables"].keys()),
+            "api_routes_indexed": [f"{r['method']} {r['path']}" for r in topology["api_routes"]],
+            "test_suites_indexed": list(topology["test_suites"].keys()),
+        },
+        indent=2,
+    )
+
+
+@mcp.tool()
+def analyze_symbol_reachability(repo_path: str, target_symbol: str, max_hops: int = 4) -> str:
+    """
+    Traces direct and transitive downstream callers/importers of a function, class, or file
+    within the repository using the Deterministic Dependency Reachability Engine.
+    """
+    topology = build_fullstack_topology(repo_path)
+    if "error" in topology:
+        return json.dumps({"engine": "BlastTrace Native Core", "error": topology["error"]}, indent=2)
+
+    engine = _populate_cpp_engine(topology)
+    matched_ids = resolve_entity_id(topology, target_symbol)
+
+    all_chains: List[List[str]] = []
+    impacted_symbols: List[str] = []
+    for start_id in matched_ids:
+        chains = engine.trace_blast_radius_paths(start_id, max_hops)
+        for ch in chains:
+            all_chains.append(ch)
+            for nid in ch[1:]:
+                if nid not in impacted_symbols:
+                    impacted_symbols.append(nid)
+
+    return json.dumps(
+        {
+            "status": "Reachability Evaluated",
+            "engine": "BlastTrace Native Core",
+            "tier": "PRO" if verify_license() else "COMMUNITY",
+            "target_symbol": target_symbol,
+            "resolved_node_ids": matched_ids,
+            "max_hops": max_hops,
+            "impacted_count": len(impacted_symbols),
+            "impacted_nodes": impacted_symbols,
+            "reachability_chains": format_evidence_chains(topology, all_chains),
+        },
+        indent=2,
+    )
+
+
+# ============================================================================
+# PRO TIER TOOLS (8 Tools — Gated by verify_license() + Native C++ Seal)
+# ============================================================================
+
+
+@mcp.tool()
+def verify_pre_edit_safety_gate(
+    repo_path: str,
+    file_path: str,
+    symbol_name: str,
+    proposed_signature_or_diff: str,
+) -> str:
+    """
+    [PRO TIER] Flagship Pre-Edit Breaking-Change Gate: Compares existing symbol/schema/route
+    contract against the proposed edit, classifies severity (PASS / WARN / BLOCK), traces
+    all downstream consumers across DB/Backend/API/Frontend/Tests, and returns a Mermaid
+    blast-radius diagram and surgical multi-file synchronization plan.
+    """
+    if not verify_license():
+        return _pro_gate_error("Pre-Edit Breaking-Change Safety Gate")
+
+    topology = build_fullstack_topology(repo_path)
+    if "error" in topology:
+        return json.dumps({"engine": "BlastTrace Native Core", "error": topology["error"]}, indent=2)
+
+    engine = _populate_cpp_engine(topology)
+    matched_ids = resolve_entity_id(topology, symbol_name)
+    if not matched_ids and file_path:
+        matched_ids = resolve_entity_id(topology, f"{os.path.basename(file_path)}:{symbol_name}")
+
+    downstream_chains: List[List[str]] = []
+    for start_id in matched_ids:
+        chains = engine.trace_blast_radius_paths(start_id, 6)
+        downstream_chains.extend(chains)
+
+    classification_res = classify_proposed_edit(
+        topology,
+        file_path,
+        symbol_name,
+        proposed_signature_or_diff,
+        downstream_chains,
+    )
+    gate_status = classification_res["gate_status"]
+    sync_plan = generate_surgical_sync_plan(topology, classification_res, downstream_chains)
+    mermaid_diag = generate_mermaid_blast_radius(
+        downstream_chains,
+        title=f"Pre-Edit Blast Radius: {symbol_name}",
+        gate_status=gate_status,
+        topology=topology,
+    )
+
+    return json.dumps(
+        {
+            "engine": "BlastTrace Native Core",
+            "tier": "PRO",
+            "gate_status": gate_status,
+            "classification": classification_res["classification"],
+            "target_file": classification_res["target_file"],
+            "target_symbol": symbol_name,
+            "reasons": classification_res["reasons"],
+            "evidence_chains": classification_res["evidence_chains"],
+            "mermaid_diagram": mermaid_diag,
+            "surgical_sync_plan": sync_plan,
+        },
+        indent=2,
+    )
+
+
+@mcp.tool()
+def trace_fullstack_contract_chain(repo_path: str, start_entity: str, target_entity: str = "") -> str:
+    """
+    [PRO TIER] Traces end-to-end contract paths from a Database Column/Table -> ORM Model ->
+    Backend Function -> API Route -> Frontend UI Component -> Covering Test Suite.
+    """
+    if not verify_license():
+        return _pro_gate_error("Full-Stack Cross-Boundary Contract Tracing")
+
+    topology = build_fullstack_topology(repo_path)
+    if "error" in topology:
+        return json.dumps({"engine": "BlastTrace Native Core", "error": topology["error"]}, indent=2)
+
+    engine = _populate_cpp_engine(topology)
+    start_ids = resolve_entity_id(topology, start_entity)
+    target_ids = resolve_entity_id(topology, target_entity) if target_entity else []
+
+    chosen_path: List[str] = []
+    all_chains: List[List[str]] = []
+
+    if start_ids and target_ids:
+        for s_id in start_ids:
+            for t_id in target_ids:
+                path = engine.find_shortest_path(s_id, t_id)
+                if path:
+                    all_chains.append(path)
+                    if not chosen_path or len(path) > len(chosen_path):
+                        chosen_path = path
+    elif start_ids:
+        for s_id in start_ids:
+            chains = engine.trace_blast_radius_paths(s_id, 6)
+            for ch in chains:
+                all_chains.append(ch)
+                if len(ch) > len(chosen_path):
+                    chosen_path = ch
+
+    evidence = format_evidence_chains(topology, [chosen_path] if chosen_path else all_chains)
+    return json.dumps(
+        {
+            "status": "Contract Chain Identified" if (chosen_path or all_chains) else "No Contract Link Found",
+            "engine": "BlastTrace Native Core",
+            "tier": "PRO",
+            "start_entity": start_entity,
+            "target_entity": target_entity or "all_downstream_consumers",
+            "path_sequence": chosen_path,
+            "hop_count": max(0, len(chosen_path) - 1),
+            "evidence_chains": evidence,
+            "mermaid_diagram": generate_mermaid_contract_chain(
+                chosen_path if chosen_path else (all_chains[0] if all_chains else []),
+                title=f"Full-Stack Contract Chain: {start_entity}",
+                topology=topology,
+            ),
+        },
+        indent=2,
+    )
+
+
+@mcp.tool()
+def analyze_db_schema_blast_radius(repo_path: str, schema_or_migration_file: str, table_or_column: str) -> str:
+    """
+    [PRO TIER] Parses SQL/Prisma/ORM changes and identifies every backend query, ORM model,
+    API endpoint, frontend UI component, and test suite that will break if the column or table
+    is modified or dropped.
+    """
+    if not verify_license():
+        return _pro_gate_error("Database Schema & Migration Blast-Radius Analyzer")
+
+    topology = build_fullstack_topology(repo_path)
+    if "error" in topology:
+        return json.dumps({"engine": "BlastTrace Native Core", "error": topology["error"]}, indent=2)
+
+    engine = _populate_cpp_engine(topology)
+    matched_ids = resolve_entity_id(topology, f"db:{table_or_column.lower()}")
+    if not matched_ids:
+        matched_ids = resolve_entity_id(topology, table_or_column)
+
+    chains: List[List[str]] = []
+    for sid in matched_ids:
+        chains.extend(engine.trace_blast_radius_paths(sid, 6))
+
+    impacted_by_layer: Dict[str, List[str]] = {
+        "backend_orm_and_functions": [],
+        "api_endpoints": [],
+        "frontend_components": [],
+        "tests": [],
+    }
+    nodes_by_id = topology["nodes_by_id"]
+    for ch in chains:
+        for nid in ch[1:]:
+            nmeta = nodes_by_id.get(nid, {})
+            layer = nmeta.get("layer", "")
+            label = f"{nmeta.get('file', '')}:{nmeta.get('name', nid)}" if nmeta.get("file") else nid
+            if layer == "backend" and label not in impacted_by_layer["backend_orm_and_functions"]:
+                impacted_by_layer["backend_orm_and_functions"].append(label)
+            elif layer == "api" and label not in impacted_by_layer["api_endpoints"]:
+                impacted_by_layer["api_endpoints"].append(label)
+            elif layer == "frontend" and label not in impacted_by_layer["frontend_components"]:
+                impacted_by_layer["frontend_components"].append(label)
+            elif layer == "tests" and label not in impacted_by_layer["tests"]:
+                impacted_by_layer["tests"].append(label)
+
+    cls_res = classify_proposed_edit(
+        topology,
+        schema_or_migration_file,
+        table_or_column,
+        f"DROP COLUMN {table_or_column}",
+        chains,
+    )
+    sync_plan = generate_surgical_sync_plan(topology, cls_res, chains)
+
+    return json.dumps(
+        {
+            "status": "Schema Blast Radius Computed",
+            "engine": "BlastTrace Native Core",
+            "tier": "PRO",
+            "schema_file": schema_or_migration_file,
+            "target_table_or_column": table_or_column,
+            "gate_status": cls_res["gate_status"],
+            "classification": cls_res["classification"],
+            "impacted_layers": impacted_by_layer,
+            "evidence_chains": format_evidence_chains(topology, chains),
+            "mermaid_diagram": generate_mermaid_blast_radius(
+                chains,
+                title=f"DB Schema Blast Radius: {table_or_column}",
+                gate_status=cls_res["gate_status"],
+                topology=topology,
+            ),
+            "surgical_sync_plan": sync_plan,
+        },
+        indent=2,
+    )
+
+
+@mcp.tool()
+def analyze_api_contract_impact(repo_path: str, route_path_or_file: str, changed_field: str = "") -> str:
+    """
+    [PRO TIER] Traces an API endpoint (/api/v1/...) to all backend handlers and all frontend
+    fetch/axios/useQuery consumers, flagging broken payload fields.
+    """
+    if not verify_license():
+        return _pro_gate_error("API Contract Breaking-Change Scanner")
+
+    topology = build_fullstack_topology(repo_path)
+    if "error" in topology:
+        return json.dumps({"engine": "BlastTrace Native Core", "error": topology["error"]}, indent=2)
+
+    engine = _populate_cpp_engine(topology)
+    query_ids = resolve_entity_id(topology, route_path_or_file)
+    if changed_field:
+        field_ids = resolve_entity_id(topology, f"{route_path_or_file}.{changed_field}")
+        if field_ids:
+            query_ids = field_ids + [qid for qid in query_ids if qid not in field_ids]
+
+    chains: List[List[str]] = []
+    for qid in query_ids:
+        chains.extend(engine.trace_blast_radius_paths(qid, 5))
+
+    frontend_consumers: List[str] = []
+    covering_tests: List[str] = []
+    nodes_by_id = topology["nodes_by_id"]
+    for ch in chains:
+        for nid in ch[1:]:
+            nmeta = nodes_by_id.get(nid, {})
+            if nmeta.get("layer") == "frontend":
+                entry = f"{nmeta.get('file', '')} ({nmeta.get('name', nid)})"
+                if entry not in frontend_consumers:
+                    frontend_consumers.append(entry)
+            elif nmeta.get("layer") == "tests":
+                entry = f"{nmeta.get('file', '')} ({nmeta.get('name', nid)})"
+                if entry not in covering_tests:
+                    covering_tests.append(entry)
+
+    cls_res = classify_proposed_edit(
+        topology,
+        route_path_or_file,
+        route_path_or_file,
+        f"removed {changed_field}" if changed_field else "breaking route modification",
+        chains,
+    )
+
+    return json.dumps(
+        {
+            "status": "API Contract Impact Evaluated",
+            "engine": "BlastTrace Native Core",
+            "tier": "PRO",
+            "route_or_file": route_path_or_file,
+            "changed_field": changed_field,
+            "gate_status": cls_res["gate_status"],
+            "classification": "BREAKING_API_CONTRACT" if chains else cls_res["classification"],
+            "frontend_consumers": frontend_consumers,
+            "covering_tests": covering_tests,
+            "evidence_chains": format_evidence_chains(topology, chains),
+            "mermaid_diagram": generate_mermaid_blast_radius(
+                chains,
+                title=f"API Contract Impact: {route_path_or_file}" + (f" [{changed_field}]" if changed_field else ""),
+                gate_status=cls_res["gate_status"],
+                topology=topology,
+            ),
+            "surgical_sync_plan": generate_surgical_sync_plan(topology, cls_res, chains),
+        },
+        indent=2,
+    )
+
+
+@mcp.tool()
+def analyze_python_module_impact(repo_path: str, file_path: str, target_symbol: str) -> str:
+    """
+    [PRO TIER] Deep Python AST signature, type-hint, decorator, and cross-module call-chain
+    impact analysis.
+    """
+    if not verify_license():
+        return _pro_gate_error("Python AST Module & Signature Impact Analyzer")
+
+    topology = build_fullstack_topology(repo_path)
+    if "error" in topology:
+        return json.dumps({"engine": "BlastTrace Native Core", "error": topology["error"]}, indent=2)
+
+    abs_target = file_path if os.path.isabs(file_path) else os.path.join(topology["repo_root"], file_path)
+    parsed_py = parse_python_file(abs_target, topology["repo_root"])
+
+    engine = _populate_cpp_engine(topology)
+    matched_ids = resolve_entity_id(topology, target_symbol)
+    chains: List[List[str]] = []
+    for mid in matched_ids:
+        chains.extend(engine.trace_blast_radius_paths(mid, 5))
+
+    sym_details = parsed_py.get("functions", {}).get(target_symbol) or parsed_py.get("classes", {}).get(target_symbol)
+
+    return json.dumps(
+        {
+            "status": "Python AST Impact Analyzed",
+            "engine": "BlastTrace Native Core",
+            "tier": "PRO",
+            "file": parsed_py.get("file", file_path),
+            "target_symbol": target_symbol,
+            "symbol_metadata": sym_details,
+            "downstream_chains": format_evidence_chains(topology, chains),
+            "mermaid_diagram": generate_mermaid_blast_radius(
+                chains,
+                title=f"Python Symbol Impact: {target_symbol}",
+                gate_status="WARN" if chains else "PASS",
+                topology=topology,
+            ),
+        },
+        indent=2,
+    )
+
+
+@mcp.tool()
+def analyze_typescript_frontend_impact(repo_path: str, file_path: str, target_symbol: str) -> str:
+    """
+    [PRO TIER] Deep TypeScript/React component prop, interface, hook, and API consumer
+    blast-radius analysis.
+    """
+    if not verify_license():
+        return _pro_gate_error("TypeScript & React Frontend Impact Analyzer")
+
+    topology = build_fullstack_topology(repo_path)
+    if "error" in topology:
+        return json.dumps({"engine": "BlastTrace Native Core", "error": topology["error"]}, indent=2)
+
+    abs_target = file_path if os.path.isabs(file_path) else os.path.join(topology["repo_root"], file_path)
+    parsed_fe = parse_ts_react_file(abs_target, topology["repo_root"])
+
+    engine = _populate_cpp_engine(topology)
+    matched_ids = resolve_entity_id(topology, target_symbol)
+    chains: List[List[str]] = []
+    for mid in matched_ids:
+        chains.extend(engine.trace_blast_radius_paths(mid, 5))
+
+    sym_details = parsed_fe.get("symbols", {}).get(target_symbol) or parsed_fe.get("interfaces", {}).get(target_symbol)
+
+    return json.dumps(
+        {
+            "status": "Frontend Component Impact Analyzed",
+            "engine": "BlastTrace Native Core",
+            "tier": "PRO",
+            "file": parsed_fe.get("file", file_path),
+            "target_symbol": target_symbol,
+            "component_or_interface": sym_details,
+            "api_dependencies": parsed_fe.get("api_calls", []),
+            "accessed_response_fields": parsed_fe.get("property_accesses", []),
+            "downstream_chains": format_evidence_chains(topology, chains),
+            "mermaid_diagram": generate_mermaid_blast_radius(
+                chains,
+                title=f"Frontend Blast Radius: {target_symbol}",
+                gate_status="WARN" if chains else "PASS",
+                topology=topology,
+            ),
+        },
+        indent=2,
+    )
+
+
+@mcp.tool()
+def select_impacted_tests(repo_path: str, changed_files_or_symbols: List[str]) -> str:
+    """
+    [PRO TIER] Deterministically selects the exact unit, integration, and E2E test files
+    and test cases that cover the modified symbols, schema columns, or API endpoints.
+    """
+    if not verify_license():
+        return _pro_gate_error("Change-Aware Test Selector")
+
+    topology = build_fullstack_topology(repo_path)
+    if "error" in topology:
+        return json.dumps({"engine": "BlastTrace Native Core", "error": topology["error"]}, indent=2)
+
+    engine = _populate_cpp_engine(topology)
+    nodes_by_id = topology["nodes_by_id"]
+
+    selected_test_files: List[str] = []
+    selected_test_cases: List[str] = []
+    evidence_chains: List[List[str]] = []
+
+    for item in changed_files_or_symbols:
+        matched_ids = resolve_entity_id(topology, item)
+        for mid in matched_ids:
+            chains = engine.trace_blast_radius_paths(mid, 6)
+            for ch in chains:
+                for nid in ch:
+                    nmeta = nodes_by_id.get(nid, {})
+                    if nmeta.get("layer") == "tests":
+                        evidence_chains.append(ch)
+                        tfile = nmeta.get("file", "")
+                        if tfile and tfile not in selected_test_files:
+                            selected_test_files.append(tfile)
+                        if nmeta.get("type") == "test_case":
+                            tc_name = nmeta.get("name", nid)
+                            if tc_name not in selected_test_cases:
+                                selected_test_cases.append(tc_name)
+
+    return json.dumps(
+        {
+            "status": "Impacted Tests Selected",
+            "engine": "BlastTrace Native Core",
+            "tier": "PRO",
+            "changed_inputs": changed_files_or_symbols,
+            "selected_test_files": selected_test_files,
+            "selected_test_cases": selected_test_cases,
+            "pytest_command": f"pytest {' '.join(selected_test_files)}" if selected_test_files else "pytest",
+            "evidence_chains": format_evidence_chains(topology, evidence_chains),
+        },
+        indent=2,
+    )
+
+
+@mcp.tool()
+def detect_circular_code_dependencies(repo_path: str) -> str:
+    """
+    [PRO TIER] Uses the BlastTrace Native Core Recursive Loop Analysis engine to detect
+    circular import and call loops across modules/packages, outputting a Mermaid cycle graph
+    and surgical refactoring patch.
+    """
+    if not verify_license():
+        return _pro_gate_error("Circular Dependency Interceptor")
+
+    topology = build_fullstack_topology(repo_path)
+    if "error" in topology:
+        return json.dumps({"engine": "BlastTrace Native Core", "error": topology["error"]}, indent=2)
+
+    engine = CppBlastEngine()
+    for mod_edge in topology.get("module_import_edges", []):
+        engine.add_edge(mod_edge["source"], mod_edge["target"])
+
+    runtime_token = get_runtime_token()
+    cycles = engine.detect_circular_dependencies(runtime_token)
+
+    return json.dumps(
+        {
+            "status": "Circular Dependencies Detected" if cycles else "Clean",
+            "engine": "BlastTrace Native Core",
+            "tier": "PRO",
+            "cycles_detected": len(cycles),
+            "dependency_loops": cycles,
+            "mermaid_diagram": generate_mermaid_cycles(cycles),
+            "surgical_refactoring": generate_cycle_refactoring_plan(cycles),
+        },
+        indent=2,
+    )
+
+
+# ============================================================================
+# STANDALONE TERMINAL CLI & GIT PRE-COMMIT GATE
+# ============================================================================
+
+
+def _format_terminal_reachability(data: dict) -> str:
+    impacted_count = data.get("impacted_count", 0)
+    target = data.get("target_symbol", "")
+    tier = data.get("tier", "COMMUNITY")
+    chains = data.get("reachability_chains", [])
+
+    layer_counts = {
+        "Database": 0,
+        "Backend": 0,
+        "Go Microservice": 0,
+        "API": 0,
+        "Web Storefront (React)": 0,
+        "Vue / Nuxt Storefront": 0,
+        "Flutter POS / Client": 0,
+        "iOS Client (Swift)": 0,
+        "Android Client (Kotlin)": 0,
+        "Tests": 0,
+    }
+    test_files = set()
+    for nid in data.get("impacted_nodes", []):
+        if nid.startswith("db:"):
+            layer_counts["Database"] += 1
+        elif nid.startswith("py:"):
+            layer_counts["Backend"] += 1
+        elif nid.startswith("go:"):
+            layer_counts["Go Microservice"] += 1
+        elif nid.startswith("api:") or nid.startswith("api_field:"):
+            layer_counts["API"] += 1
+        elif nid.startswith("fe:"):
+            layer_counts["Web Storefront (React)"] += 1
+        elif nid.startswith("vue:"):
+            layer_counts["Vue / Nuxt Storefront"] += 1
+        elif nid.startswith("dart:"):
+            layer_counts["Flutter POS / Client"] += 1
+        elif nid.startswith("swift:"):
+            layer_counts["iOS Client (Swift)"] += 1
+        elif nid.startswith("kotlin:"):
+            layer_counts["Android Client (Kotlin)"] += 1
+        elif nid.startswith("test:"):
+            layer_counts["Tests"] += 1
+            test_files.add(nid.replace("test:", "").split("::")[0])
+
+    lines = [
+        "━" * 60,
+        "  BlastTrace Contract Reachability Summary",
+        "━" * 60,
+        f"  Target Symbol       : {target}",
+        f"  License Tier        : {tier}",
+        f"  Total Blast Radius  : {impacted_count} downstream node(s)",
+        "",
+        "  Downstream Breakdown by Layer:"
+    ]
+    for layer, count in layer_counts.items():
+        if count > 0:
+            lines.append(f"    • {layer:<22} : {count} impacted")
+
+    if chains:
+        lines.append("")
+        lines.append("  Immediate Downstream Paths (Top 5):")
+        for ch in chains[:5]:
+            lines.append(f"    -> {ch}")
+        if len(chains) > 5:
+            lines.append(f"    ... and {len(chains) - 5} more path(s) (pass --json for full trace)")
+
+    if test_files:
+        lines.append("")
+        lines.append("  Targeted Test Command:")
+        lines.append(f"    pytest {' '.join(sorted(test_files)[:4])}")
+
+    lines.append("━" * 60)
+    return "\n".join(lines)
+
+
+def _run_git_diff_gate(repo_path: str, is_pre_commit: bool = False) -> int:
+    """Inspects modified files in git working tree / staged index and evaluates blast radius."""
+    cmd = ["git", "diff", "--cached", "--name-only"] if is_pre_commit else ["git", "diff", "--name-only"]
+    try:
+        out = subprocess.check_output(cmd, cwd=repo_path, stderr=subprocess.DEVNULL, text=True)
+        changed_files = [line.strip() for line in out.splitlines() if line.strip()]
+    except Exception:
+        changed_files = []
+
+    topology = build_fullstack_topology(repo_path)
+    if "error" in topology:
+        print(json.dumps({"engine": "BlastTrace Native Core", "error": topology["error"]}, indent=2))
+        return 1
+
+    engine = _populate_cpp_engine(topology)
+    impacts: List[str] = []
+    for fpath in changed_files:
+        for mid in resolve_entity_id(topology, fpath):
+            chains = engine.trace_blast_radius_paths(mid, 5)
+            impacts.extend(format_evidence_chains(topology, chains))
+
+    gate = "BLOCK" if impacts else "PASS"
+    report = {
+        "engine": "BlastTrace Native Core",
+        "mode": "pre-commit" if is_pre_commit else "diff",
+        "gate_status": gate,
+        "changed_files": changed_files,
+        "downstream_evidence_chains": list(dict.fromkeys(impacts)),
+    }
+    print(json.dumps(report, indent=2))
+    return 1 if (gate == "BLOCK" and is_pre_commit) else 0
+
+
+def main() -> None:
+    global IS_PRO_TIER
+    if len(sys.argv) > 1:
+        cmd = sys.argv[1].lower()
+        if cmd == "activate":
+            if len(sys.argv) < 3:
+                print("Usage: blasttrace activate <LICENSE_KEY>")
+                sys.exit(1)
+            key = sys.argv[2]
+            success = activate_license(key)
+            sys.exit(0 if success else 1)
+        elif cmd == "deactivate":
+            success = deactivate_license()
+            sys.exit(0 if success else 1)
+        elif cmd == "status":
+            status_info = get_license_status()
+            print(json.dumps(status_info, indent=2))
+            sys.exit(0)
+        elif cmd in ("gen-test-key", "create-test-key"):
+            label = sys.argv[2] if len(sys.argv) > 2 else "TESTER"
+            key = generate_tester_license_key(label)
+            print(f"[+] Generated Authorized Tester Key ({label.upper()}):")
+            print(key)
+            print(f"\nShare with your tester to run:")
+            print(f"blasttrace activate {key}")
+            sys.exit(0)
+        elif cmd in ("install-agent", "setup-agent", "configure-agent"):
+            from blasttrace.install_agent import install_all_agents, format_universal_mcp_snippet
+            target = sys.argv[2] if len(sys.argv) > 2 else "all"
+            print("━" * 60)
+            print("  BlastTrace Universal AI Agent MCP Configurator")
+            print("━" * 60)
+            results = install_all_agents(target=target)
+            if results:
+                print(f"[+] Detected & configured {len(results)} AI environment(s):")
+                for name, ok in results:
+                    mark = "✔" if ok else "✘"
+                    print(f"  [{mark}] {name}")
+                print("\n[+] Success: Restart your IDE or AI agent to activate BlastTrace!")
+            else:
+                print("[!] No active AI environment configs automatically detected in default paths.")
+            print("\nUniversal MCP Configuration Snippet (for any agent/tool):")
+            print(format_universal_mcp_snippet())
+            sys.exit(0)
+        elif cmd == "check":
+            if len(sys.argv) < 3:
+                print("Usage: blasttrace check <file_or_symbol> [repo_path] [--json]")
+                sys.exit(1)
+            raw_args = [a for a in sys.argv[2:] if a != "--json"]
+            is_json = "--json" in sys.argv
+            target = raw_args[0]
+            repo = raw_args[1] if len(raw_args) > 1 else os.getcwd()
+            raw_res = analyze_symbol_reachability(repo, target)
+            if is_json:
+                print(raw_res)
+            else:
+                try:
+                    res_dict = json.loads(raw_res)
+                    print(_format_terminal_reachability(res_dict))
+                except Exception:
+                    print(raw_res)
+            sys.exit(0)
+        elif cmd == "diff":
+            repo = sys.argv[2] if len(sys.argv) > 2 else os.getcwd()
+            sys.exit(_run_git_diff_gate(repo, is_pre_commit=False))
+        elif cmd == "pre-commit":
+            if len(sys.argv) > 2 and sys.argv[2] == "--install":
+                repo = sys.argv[3] if len(sys.argv) > 3 else os.getcwd()
+                hook_dir = os.path.join(repo, ".git", "hooks")
+                os.makedirs(hook_dir, exist_ok=True)
+                hook_path = os.path.join(hook_dir, "pre-commit")
+                with open(hook_path, "w") as f:
+                    f.write("#!/bin/sh\n# BlastTrace Pre-Commit Breaking-Change Gate\nblasttrace pre-commit\n")
+                try:
+                    os.chmod(hook_path, 0o755)
+                except Exception:
+                    pass
+                print(f"[+] Success: Hook installed successfully at {hook_path}")
+                sys.exit(0)
+            repo = sys.argv[2] if len(sys.argv) > 2 else os.getcwd()
+            sys.exit(_run_git_diff_gate(repo, is_pre_commit=True))
+        elif cmd in ("-h", "--help", "help"):
+            print("BlastTrace CLI - Pre-Edit Full-Stack Breaking-Change & Contract Blast-Radius Engine")
+            print("Commands:")
+            print("  blasttrace check <symbol> [repo] [--json]  Check full-stack blast radius (summary or raw JSON)")
+            print("  blasttrace install-agent [agent]  Auto-configure in Cursor, Claude, Windsurf, VS Code, Zed")
+            print("  blasttrace diff [repo]            Analyze blast radius of uncommitted git changes")
+            print("  blasttrace pre-commit [repo]      Run pre-commit breaking-change gate on staged changes")
+            print("  blasttrace activate <KEY>         Activate Pro license on this machine")
+            print("  blasttrace deactivate             Deactivate Pro license and release hardware seat")
+            print("  blasttrace status                 Show current license and machine status")
+            print("  blasttrace                        Start FastMCP stdio server")
+            sys.exit(0)
+
+    IS_PRO_TIER = verify_license()
+    if IS_PRO_TIER:
+        print("[*] BlastTrace running in PRO Tier (BlastTrace Native Core Unlocked)", file=sys.stderr)
+    else:
+        print("[*] BlastTrace running in COMMUNITY Tier (Free Edition)", file=sys.stderr)
+
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()
+