Metadata-Version: 2.4
Name: esim-tool-manager
Version: 0.1.0
Summary: Automated external tool manager for eSim
Author: Sachin Kharote
Keywords: esim,tool-manager,kicad,ngspice,electronics,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: typer
Requires-Dist: rich
Requires-Dist: packaging

# eSim Tool Manager

<p align="center">
  <img src="https://img.shields.io/badge/platform-Windows-0078D6?style=flat-square&logo=windows" alt="platform" />
  <img src="https://img.shields.io/badge/python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="python" />
  <img src="https://img.shields.io/badge/tests-17%20passed-brightgreen?style=flat-square&logo=pytest&logoColor=white" alt="tests" />
  <img src="https://img.shields.io/badge/status-functional%20prototype-yellow?style=flat-square" alt="status" />
  <img src="https://img.shields.io/badge/license-unspecified-lightgrey?style=flat-square" alt="license" />
</p>

<p align="center">
  Automated external tool manager for <strong>eSim</strong> on Windows — detect, install, configure, and verify the tools an eSim development environment needs, from one CLI.
</p>

---

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Supported Tools](#supported-tools)
- [Requirements](#requirements)
- [Installation](#installation)
- [Command-Line Interface](#command-line-interface)
  - [Status](#check-tool-status)
  - [Install](#install-tools)
  - [Configure](#configure-kicad)
  - [Dependencies](#check-dependencies)
  - [Update](#update-checking)
- [Configuration](#configuration)
- [Architecture](#architecture)
- [Project Structure](#project-structure)
- [Testing](#testing)
- [Logging](#logging)
- [Error Handling](#error-handling)
- [Design Approach](#design-approach)
- [Current Limitations](#current-limitations)
- [Future Improvements](#future-improvements)
- [Development](#development)
- [Example Verified Environment](#example-verified-environment)
- [License](#license)
- [Project Status](#project-status)

---

## Overview

eSim relies on a handful of external tools — KiCad, Ngspice, Python, Git — that each need to be detected, version-checked, installed, and (in KiCad's case) wired into the system `PATH` before eSim can use them. **eSim Tool Manager** wraps all of that into a single configuration-driven CLI so a new eSim setup goes from "nothing installed" to "verified and ready" in a few commands.

```mermaid
flowchart LR
    A["New Windows machine"] --> B["esim-tool-manager status"]
    B --> C{"Tools missing or\noutdated?"}
    C -- Yes --> D["esim-tool-manager install <tool>"]
    D --> E["esim-tool-manager configure kicad"]
    E --> F["esim-tool-manager check-dependencies"]
    C -- No --> F
    F --> G["Ready for eSim development"]
```

---

## Features

| Category | Capability |
|---|---|
| 🔍 Detection | Detect installed external tools and report their versions |
| ✅ Compatibility | Check installed versions against configured minimums |
| 📦 Installation | Install supported tools automatically (`winget`, direct download) |
| 🧩 KiCad | Install via Windows Package Manager, locate `kicad-cli.exe`, configure PATH |
| ⚡ Ngspice | Install via a configured direct-download archive using 7-Zip |
| 🔗 Dependencies | Check required system dependencies (WinGet, 7-Zip, Python, Git) |
| 🔄 Updates | Check for available tool updates |
| 🗒️ Logging | Maintain application logs for diagnostics |
| ⚙️ Configuration | Tool definitions driven entirely by `config/tools.json` |
| 🧪 Testing | Automated test suite using `pytest` |

---

## Supported Tools

| Tool | Detection | Installation | Version Check | Configuration | Min. Version |
|------|:---------:|:-------------|:--------------:|:--------------:|:-------------:|
| **Ngspice** | ✅ | Direct download | ✅ | ✅ | `47` |
| **KiCad** | ✅ | `winget` | ✅ | ✅ | `8` |
| **Python** | ✅ | `winget` | ✅ | — | `3.10` |
| **Git** | ✅ | `winget` | ✅ | — | `2.0` |

---

## Requirements

### System Requirements

- Windows 10/11
- Python 3.10 or newer
- Git
- Windows Package Manager (`winget`)
- 7-Zip for Ngspice installation

Python dependencies are defined in `requirements.txt`.

---

## Installation

```mermaid
flowchart TD
    A["git clone repository-url"] --> B["python -m venv .venv"]
    B --> C[".\\.venv\\Scripts\\Activate.ps1"]
    C --> D["pip install -r requirements.txt"]
    D --> E["pip install -e ."]
    E --> F["esim-tool-manager --help"]
```

### 1. Clone the repository

```powershell
git clone <repository-url>
cd esim-tool-manager
```

### 2. Create a virtual environment

```powershell
python -m venv .venv
```

### 3. Activate the virtual environment

```powershell
.\.venv\Scripts\Activate.ps1
```

If PowerShell blocks script execution, run:

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
```

Then activate the environment again:

```powershell
.\.venv\Scripts\Activate.ps1
```

### 4. Install Python dependencies

```powershell
pip install -r requirements.txt
```

### 5. Install the project

```powershell
pip install -e .
```

### 6. Verify the CLI

```powershell
esim-tool-manager --help
```

---

## Command-Line Interface

| Command | Purpose |
|---|---|
| `status` | Report installed tools, versions, and compatibility |
| `install` | Install a configured tool automatically |
| `configure` | Locate and configure a tool (e.g., KiCad CLI on PATH) |
| `update` | Check configured tools for available updates |
| `check-dependencies` | Verify system and development dependencies |

```powershell
esim-tool-manager --help
```

### Check Tool Status

```powershell
esim-tool-manager status
```

```text
eSim Tool Manager
=================

✓ Ngspice: Installed

✓ KiCad: Installed
  Version: 10.0.5
  Required: >= 8
  Compatibility: ✓ Compatible

✓ Python: Installed
  Version: 3.11.0
  Required: >= 3.10
  Compatibility: ✓ Compatible

✓ Git: Installed
  Version: 2.55.0
  Required: >= 2.0
  Compatibility: ✓ Compatible
```

### Install Tools

```powershell
esim-tool-manager install <tool_name>
```

```powershell
esim-tool-manager install kicad
esim-tool-manager install ngspice
```

The installation method is determined by the tool configuration.

#### KiCad

Installed through Windows Package Manager using the configured package ID `KiCad.KiCad`.

#### Ngspice

```mermaid
flowchart TD
    A["Check 7-Zip availability"] --> B["Create installation directory"]
    B --> C["Download configured Ngspice archive"]
    C --> D["Extract archive with 7-Zip"]
    D --> E["Search for ngspice executable"]
    E --> F["Report discovered executable"]
```

### Configure KiCad

```powershell
esim-tool-manager configure kicad
```

```mermaid
flowchart TD
    A["Start configure kicad"] --> B{"kicad-cli.exe\non system PATH?"}
    B -- Yes --> E["Already configured"]
    B -- No --> C["Search %LOCALAPPDATA%\\Programs\\KiCad"]
    C --> D{"Found?"}
    D -- Yes --> F["Add containing directory to user PATH"]
    D -- No --> G["Report not found"]
```

```text
eSim Tool Manager - Configuration
=================================

Searching for KiCad...

✓ Found: C:\Users\<user>\AppData\Local\Programs\KiCad\10.0\bin\kicad-cli.exe

Configuring PATH...

✓ PATH configured successfully.
```

### Check Dependencies

```powershell
esim-tool-manager check-dependencies
```

```text
Dependency Check
================

System Dependencies
-------------------
✓ WinGet: Available
✓ 7-Zip: Available

Development Tools
-----------------
✓ Python: Python 3.11.0
✓ Git: git version 2.55.0.windows.3

eSim External Tools
-------------------
✓ KiCad: 10.0.5
✓ Ngspice: Available

========================
✓ All required dependencies are available.
```

### Update Checking

```powershell
esim-tool-manager update
esim-tool-manager update kicad
```

```text
eSim Tool Manager - Update
==========================

Checking updates for KiCad...

No available upgrade found.
No newer package versions are available from the configured sources.
```

---

## Configuration

Tool definitions live in `config/tools.json`, keeping tool-specific information separate from application logic.

Each tool can define:

| Field | Description |
|---|---|
| `name` | Internal tool identifier |
| `display_name` | Human-readable name |
| `command` | Executable command |
| `version_command` | Command used to query the installed version |
| `required_version` | Minimum compatible version |
| `install_method` | e.g. `winget`, direct download |
| `package_id` | Package identifier for the install method |
| download info | Direct-download source details |
| install dependencies | Prerequisites needed before install |

Example KiCad configuration:

```json
{
    "name": "kicad",
    "display_name": "KiCad",
    "command": "kicad-cli",
    "version_command": [
        "kicad-cli",
        "--version"
    ],
    "required_version": "8",
    "install_method": "winget",
    "package_id": "KiCad.KiCad"
}
```

---

## Architecture

```mermaid
flowchart TD
    CLI["CLI — cli.py"]

    CLI --> Detector["Detector — detector.py"]
    CLI --> Installer["Installer — installer.py"]
    CLI --> Dependency["Dependency — dependency.py"]

    Detector --> Version["Version — version.py"]
    Installer --> Locator["Locator — locator.py"]
    Dependency --> PathMgr["PATH Manager — path_manager.py"]

    CLI --> Config["Config — config.py"]
    CLI --> Logger["Logger — logger.py"]

    style CLI fill:#4C6EF5,color:#fff
    style Config fill:#495057,color:#fff
    style Logger fill:#495057,color:#fff
```

| Module | File | Responsibility |
|---|---|---|
| CLI | `cli.py` | User-facing commands: `status`, `install`, `configure`, `update`, `check-dependencies` |
| Configuration | `config.py` | Loads tool definitions from `config/tools.json` |
| Detection | `detector.py` | Determines whether external commands are available and retrieves reported versions |
| Version Management | `version.py` | Extracts version numbers and checks against configured minimums |
| Installation | `installer.py` | Handles `winget` and direct-archive installation |
| KiCad Locator | `locator.py` | Locates `kicad-cli.exe`, including the standard per-user install directory |
| PATH Management | `path_manager.py` | Adds tool directories to the current user's Windows PATH |
| Dependency Checking | `dependency.py` | Checks system and development dependencies |
| Logging | `logger.py` | Application logging for operations and diagnostics |

---

## Project Structure

```text
esim-tool-manager/
│
├── config/
│   └── tools.json
│
├── docs/
│
├── logs/
│
├── src/
│   └── esim_manager/
│       ├── __init__.py
│       ├── cli.py
│       ├── config.py
│       ├── dependency.py
│       ├── detector.py
│       ├── installer.py
│       ├── locator.py
│       ├── logger.py
│       ├── main.py
│       ├── path_manager.py
│       └── version.py
│
├── tests/
│   ├── test_config.py
│   ├── test_detector.py
│   ├── test_locator.py
│   ├── test_path_manager.py
│   └── test_version.py
│
├── .gitignore
├── pyproject.toml
├── README.md
└── requirements.txt
```

---

## Testing

```powershell
python -m pytest
```

| Area covered | Status |
|---|:---:|
| Configuration loading | ✅ |
| Tool detection | ✅ |
| Installed tool checks | ✅ |
| Version extraction | ✅ |
| Version compatibility | ✅ |
| PATH management | ✅ |
| KiCad executable location | ✅ |

```text
collected 17 items

17 passed
```

---

## Logging

Application logs are stored in `logs/`, with the main log file at `logs/esim_manager.log`. Logging records important operations such as status checks and dependency checks. Log files are excluded from Git via `.gitignore`.

---

## Error Handling

The application handles common failures such as:

- Tool not installed
- Unknown tool name
- Missing package configuration
- Missing WinGet
- Missing 7-Zip
- Failed downloads
- Failed archive extraction
- Missing executables after installation
- PATH configuration failures
- Unsupported installation methods
- Unsupported operating systems

The CLI returns a non-zero exit code when an operation fails.

---

## Design Approach

The project follows a modular, configuration-driven design: instead of hard-coding every tool into the CLI, tool information lives in `tools.json`. This gives:

- Easier addition of new tools
- Centralized version requirements
- Centralized installation configuration
- Separation between configuration and application logic
- Easier testing and maintenance

Detection, installation, version handling, PATH management, dependency checking, and logging are each isolated into individual modules.

---

## Current Limitations

- Installation methods are tool-specific.
- Linux and macOS support are not currently implemented.
- Some update mechanisms depend on the capabilities of the configured package source.
- PATH changes may require a new terminal/process before all applications recognize them.
- The current test suite focuses primarily on deterministic modules rather than performing real software installations.

---

## Future Improvements

| Priority area | Improvement |
|---|---|
| Platform support | Linux support, macOS support |
| Installation | Additional package-manager backends, more installation methods, installation rollback support |
| Reliability | Better recovery from failed installations, automatic PATH refresh across existing processes |
| Updates | Improved update support for direct-download tools |
| Testing | More comprehensive integration testing, continuous integration testing |
| Reporting | More detailed installation reports |
| Tooling | Additional eSim-specific external tools |
| Usability | GUI interface for users who do not want to use the CLI |

---

## Development

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
pip install -e .
esim-tool-manager --help
esim-tool-manager status
esim-tool-manager check-dependencies
python -m pytest
```

---

## Example Verified Environment

| Component | Version |
|---|---|
| Operating System | Windows |
| Python | 3.11.0 |
| Git | 2.55.0 |
| KiCad | 10.0.5 |
| Ngspice | 47 |
| Pytest | 9.1.1 |
| Automated Tests | 17 passed |

```text
✓ WinGet: Available
✓ 7-Zip: Available
✓ Python: Available
✓ Git: Available
✓ KiCad: Available
✓ Ngspice: Available

✓ All required dependencies are available.
```

---

## License

This project currently does not specify a separate open-source license.

---

## Project Status

**Current status: Functional prototype**

```mermaid
pie showData
    title Feature Coverage
    "Implemented" : 13
    "Planned / Future" : 8
```

The core implementation currently provides tool detection, version checking, version compatibility checking, KiCad installation through WinGet, Ngspice direct installation, KiCad CLI discovery, PATH configuration, dependency checking, update checking, logging, configuration-driven tool definitions, a command-line interface, and automated testing.

```text
17 passed
```

The project is ready for further refinement, documentation, integration testing, and expansion of supported installation methods.
