Metadata-Version: 2.4
Name: blasttrace
Version: 1.2.1
Summary: Pre-Edit Full-Stack Breaking-Change & Contract Blast-Radius Engine
Home-page: https://blasttrace.dev
Author: Moin Hasan
Author-email: Moin Hasan <moin_hasan@live.com>
License: Proprietary
Project-URL: Homepage, https://blasttrace.dev
Project-URL: Documentation, https://blasttrace.dev
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=0.1.0
Requires-Dist: requests>=2.28.0
Dynamic: author
Dynamic: home-page

# BlastTrace

> **Pre-Edit Full-Stack Breaking-Change & Contract Blast-Radius Engine**  
> `Database Schema` $\longleftrightarrow$ `Backend ORM & Go Services` $\longleftrightarrow$ `API Contracts` $\longleftrightarrow$ `Web (React/Vue)` $\longleftrightarrow$ `Mobile (Flutter/iOS/Android)` $\longleftrightarrow$ `Tests`

[![PyPI Version](https://img.shields.io/badge/pypi-v1.2.1-blue.svg)](https://pypi.org/project/blasttrace/)
[![Engine](https://img.shields.io/badge/engine-BlastTrace%20Native%20Core-brightgreen.svg)](https://blasttrace.dev)
[![License](https://img.shields.io/badge/license-Commercial%20%2F%20Community-green.svg)](https://blasttrace.dev)
[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey.svg)](https://blasttrace.dev)

---

## ⚡ What is BlastTrace?

**BlastTrace** is a high-performance **Model Context Protocol (FastMCP)** server and standalone developer CLI that prevents AI coding agents (and engineering teams) from silently breaking full-stack web and mobile applications.

Existing linters and AST tools only trace single-language file imports (`File A -> File B`). They go **100% blind** when a schema edit cascades across architectural boundaries:

```text
[Database Column: users.billing_balance]
         ↓
[Backend ORM / Go Microservice: User.billing_balance]
         ↓
[API Endpoint: GET /api/v1/user/summary]
         ↓
[Web & Mobile Clients]:
  ├─ React Storefront (CheckoutModal.tsx)
  ├─ Vue / Nuxt 3 Storefront (UserProfile.vue)
  ├─ Flutter POS Client (product_model.dart)
  ├─ Native iOS App (UserProfileDto.swift)
  └─ Native Android App (UserProfileResponse.kt)
         ↓
[Targeted Test Suites: pytest, vitest, flutter test]
```

Powered by the **BlastTrace Native Core**, BlastTrace deterministically connects schema, code, network contracts, and client consumers into an actionable topology **before** files are saved, before `git commit`, and before pull requests merge.

---

## 🚀 Quick Start

### 1. Installation
```bash
pip install --upgrade blasttrace
```
*Supports Windows, macOS, and Linux out-of-the-box.*

---

### 2. Universal 1-Click AI Agent Setup
Automatically connect BlastTrace's 10 pre-edit safety tools to your AI coding agents in **1 single command**:

```bash
blasttrace install-agent
```

BlastTrace automatically scans your machine and configures:
- **Cursor IDE** (workspace `.cursor/mcp.json` and global settings)
- **Claude Desktop** (`claude_desktop_config.json`)
- **Claude Code CLI** (`~/.claude.json`)
- **VS Code Extensions** (Cline & Roo Code)
- **Windsurf** (`mcp_config.json`)
- **Zed Editor** (`settings.json`)
- **Custom Frameworks** (prints standard universal MCP snippet for LangChain, LlamaIndex, Aider)

---

### 3. Standalone Developer CLI (Zero AI Required)

Run pre-edit contract reachability checks directly from your terminal:

```bash
# Check full-stack blast radius of any symbol or file
blasttrace check User.balance

# Or inspect blast radius across a specific repository
blasttrace check User.balance /path/to/repo

# Output raw JSON for custom CI/CD pipelines
blasttrace check User.balance --json
```

#### Clean Executive Terminal Output:
```text
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  BlastTrace Contract Reachability Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Target Symbol       : User.balance
  License Tier        : PRO
  Total Blast Radius  : 28 downstream node(s)

  Downstream Breakdown by Layer:
    • Backend                 : 3 impacted
    • API                     : 5 impacted
    • Web Storefront (React)  : 7 impacted
    • Vue / Nuxt Storefront   : 2 impacted
    • Flutter POS / Client    : 3 impacted
    • iOS Client (Swift)      : 3 impacted
    • Android Client (Kotlin) : 2 impacted
    • Tests                   : 3 impacted

  Immediate Downstream Paths (Top 5):
    -> sample_backend.py (User.balance)
    -> sample_backend.py (User.balance) -> sample_backend.py (process_user_checkout)
    -> sample_backend.py (User.balance) -> sample_backend.py (get_user_profile)
    -> sample_backend.py (User.balance) -> sample_go_service.go (GET /api/v1/user)
    -> sample_backend.py (User.balance) -> sample_backend.py (GET /api/v1/user [balance])
    ... and 23 more path(s) (pass --json for full trace)

  Targeted Test Command:
    pytest sample_test.py:test_user_checkout_and_balance
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

### 4. Git Pre-Commit Breaking-Change Gate

Install the automatic pre-commit safety gate across your repository:
```bash
blasttrace pre-commit --install
```

Whenever you or an AI agent attempts to stage breaking contract edits without updating client consumers, BlastTrace halts the commit and outputs the exact impacted consumers.

---

## 🛡️ Supported Technology Stacks

| Architectural Layer | Supported Technologies & Frameworks |
| :--- | :--- |
| **Database & Migrations** | PostgreSQL, MySQL, SQLite, SQL DDL migrations (`.sql`), SQLAlchemy, Alembic, Prisma (`schema.prisma`), GORM. |
| **Backend & Microservices** | Python (FastAPI, Flask, Django REST, Pydantic, SQLAlchemy), **Go / Golang** (Gin, Fiber, Chi, standard `net/http`, GORM). |
| **API Contract Layer** | REST endpoints, JSON request/response payloads, OpenAPI / Swagger specifications. |
| **Web Frontends** | **React & Next.js** (TypeScript AST, prop-chains, property destructuring), **Vue.js & Nuxt 3** (`.vue` templates, `<script setup>`, Pinia stores, `$fetch`, `useFetch`, Axios). |
| **Mobile Client Suite** | **Flutter / Dart** (Dio, HTTP client, `fromJson`/`toJson` models), **Native iOS** (Swift `Codable` structs, `CodingKeys`, `URLSession`, Alamofire), **Native Android** (Kotlin `data class`, `@SerializedName`, Retrofit `@GET`/`@POST`, Ktor). |
| **Test Suites** | Pytest, Unittest, Jest, Vitest, Flutter test (change-aware test selection). |

---

## 🔑 Licensing & Tiers

| Tier | Price | Access | Capabilities |
| :--- | :---: | :--- | :--- |
| **Community** | **$0** (Free Forever) | Zero key needed | Read-only repository topology indexing (`index_repository_topology`) and basic symbol reachability (`analyze_symbol_reachability`). |
| **Console Tester** | Internal Testing | Signed tester key (`BT-TEST-...`) | Full Pro access for verified QA and pilot developers. Generated via `blasttrace gen-test-key <LABEL>`. |
| **Pro License** | **$19/mo** (or $180/yr) | Lemon Squeezy Store Key | All 10 FastMCP safety tools, automated Pre-Edit Breaking-Change Gate (PASS/WARN/BLOCK), surgical sync patch generation, and circular dependency interceptor. |

Activate your Pro or Tester key:
```bash
blasttrace activate YOUR-LICENSE-KEY
```

Check current license status:
```bash
blasttrace status
```

---

## 🔒 100% Local & Privacy-Preserving

BlastTrace executes entirely on your local machine:
- **Zero telemetry:** No metrics or usage sent to external servers.
- **Air-gapped operation:** Deterministic Dependency Reachability Engine runs locally.
- **Zero cloud code uploads:** Your intellectual property never leaves your workstation.

---

## 🌐 Official Links
- **Website & Documentation:** [https://blasttrace.dev](https://blasttrace.dev)
- **PyPI Package:** [https://pypi.org/project/blasttrace/](https://pypi.org/project/blasttrace/)
