Metadata-Version: 2.4
Name: converge-cli
Version: 0.1.4
Summary: A Python-first repository intelligence and environment convergence platform.
Author-email: Converge Authors <authors@example.com>
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: networkx>=3.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sqlmodel>=0.0.16
Requires-Dist: typer>=0.12.0
Requires-Dist: uv>=0.1.0
Provides-Extra: dev
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Requires-Dist: types-networkx>=3.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">
  <img src="https://raw.githubusercontent.com/desenyon/converge/main/docs/assets/logo.png" alt="Converge Logo" width="200" onerror="this.style.display='none'"/>
  
  <h1 align="center">Converge</h1>
  
  <p align="center">
    <strong>The Python-First Repository Intelligence and Environment Convergence Platform</strong>
  </p>

  <p align="center">
    <a href="https://pypi.org/project/converge-cli/"><img src="https://img.shields.io/pypi/v/converge-cli.svg?style=for-the-badge&color=2563ea&labelColor=1e293b" alt="PyPI Version"></a>
    <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.12+-blue.svg?style=for-the-badge&logo=python&logoColor=white&color=3b82f6&labelColor=1e293b" alt="Python Version"></a>
    <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/badge/Powered%20By-uv-white.svg?style=for-the-badge&logo=uv&logoColor=black&color=f8fafc&labelColor=1e293b" alt="Powered By UV"></a>
    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-purple.svg?style=for-the-badge&color=8b5cf6&labelColor=1e293b" alt="License"></a>
  </p>
</div>

<br />

---

## 1. Overview

Converge is an advanced intelligence platform for Python repositories. It constructs a topographical map of your entire codebase's explicit and implicit dependencies. By analyzing the raw Abstract Syntax Trees (AST) against your manifests, it definitively detects missing constraints, flags unused packages for garbage collection, and creates perfectly optimized virtual environments instantaneously.

It eliminates environment debugging entirely.

---

## 2. Installation

Converge uses `uv` underneath to create its ultra-fast sandbox validation environments. It is highly recommended to install Converge globally to keep it isolated from the projects you are trying to repair.

Using `uv` (Recommended):
```bash
uv tool install converge-cli
uv tool upgrade converge-cli
```

Using `pipx`:
```bash
pipx install converge-cli
```

---

## 3. Core Capabilities

Converge exposes a rich, high-performance CLI interface designed for serious engineering workflows.

### 3.1 Initializing the Graph (`scan`)
Before you can analyze a project, you must scan it. Converge maps your files, configuration, and dependencies into a serialized local SQLite network.

```bash
cd your-project
converge scan .
```

### 3.2 Automated Provisioning (`create`)
Instantly create a virtual environment explicitly tailored to the repository's scanned constraints. Converge supports both `uv` and `pip` providers.

```bash
converge create . --provider uv 
```

### 3.3 Diagnostic Sweeps (`doctor`)
Execute a structural integrity check across the codebase. Converge will alert you to:
- **Unresolved Imports**: Modules you import in Python that are fundamentally missing from `pyproject.toml`.
- **Unused Dependencies**: Packages present in your manifest that no file in the repository actually imports.
- **Version Clashes**: Constraint violations detected mathematically.

```bash
converge doctor
```
*Output instances generate unique `conflict_id`s for deeper tracing.*

### 3.4 Deep Traceability (`explain`)
Pass an entity ID or a specific `conflict_id` generated by the doctor to visualize why the constraint anomaly exists within your repository geometry.

```bash
# Debug a specific anomaly
converge explain conflict:unresolved_mod:auth.py_pkg:requests

# Visualize the topographical dependency tree of an entity
converge explain pkg:fastapi
```

### 3.5 Automated Repair Generators (`fix`)
Converge can automatically synthesize and test repair strategies in hidden `uv` sandboxes in the background. It tests matrix permutations of your environment within milliseconds, guaranteeing the recommended fix won't break your build.

```bash
# Simulate fixes
converge fix .

# Apply the validated fix matrix
converge fix . --apply
```

---

## 4. Continuous Integration Integration

Converge should act as the ultimate gatekeeper in your CI/CD pipelines, preventing structural anomalies from ever reaching production.

### GitHub Actions

```yaml
name: Converge Analysis
on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v2
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          
      - run: uv tool install converge-cli
      - run: converge scan .
      - run: converge doctor
```

---

## 5. Extensibility

Converge is designed to be imported programmatically to build internal developer tools or feed advanced agentic architectures. 

```python
from pathlib import Path
from converge.scanner.scanner import Scanner
from converge.graph.store import GraphStore
from converge.solver.conflict import ConflictDetector

# Introspect Graph Programmatically
store = GraphStore("sqlite:///converge_graph.db")
scanner = Scanner(root_dir=Path("."), store=store)

entities, relationships = scanner.scan_all()
store.add_entities(entities)
store.add_relationships(relationships)

# Detect structural integrity
G = store.load_networkx()
detector = ConflictDetector(G)
conflicts = detector.detect_all()

if conflicts:
    print(f"Danger! Detected {len(conflicts)} architectural anomalies.")
```

---

## 6. License

This project is licensed under the MIT License. See the `LICENSE` file for full details.
