Metadata-Version: 2.4
Name: esim-tool-manager
Version: 0.2.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-19%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)
- [Anonymous Usage Statistics](#anonymous-usage-statistics)
- [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
│       ├── stats.py
│       └── version.py
│
├── tests/
│   ├── test_config.py
│   ├── test_detector.py
│   ├── test_locator.py
│   ├── test_path_manager.py
│   ├── test_stats.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 | ✅ |
| Anonymous usage statistics | ✅ |

```text
collected 19 items

19 passed
```

### Verifying a Change

After making a change (e.g. the telemetry addition above), confirm it two ways:

**1. Run the complete test suite**

```powershell
python -m pytest
```

Expected result:

```text
19 passed
```

**2. Check Git status**

```powershell
git status
```

Expected to see intentional changes, for example:

```text
modified:   README.md
modified:   src/esim_manager/cli.py
modified:   src/esim_manager/stats.py

new file:   tests/test_stats.py
```

---

## 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`.

---

## Anonymous Usage Statistics

eSim Tool Manager collects limited anonymous installation statistics to help understand project adoption and software version distribution.

| Data collected | Purpose |
|---|---|
| Randomly generated installation ID | Distinguishes unique installs without identifying the user |
| eSim Tool Manager version | Tracks version adoption |
| First-seen timestamp | Tracks when an install first appeared |
| Last-seen timestamp | Tracks whether an install is still active |

**What is *not* collected:** names, email addresses, computer names, files, or any other intentionally identifying information.

Statistics are used only for aggregate project usage information.

| Command | Effect |
|---|---|
| `esim-tool-manager telemetry false` | Disable telemetry |
| `esim-tool-manager telemetry true` | Re-enable telemetry |
| `esim-tool-manager telemetry` | Check the current telemetry setting |

---

## 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 | 19 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" : 14
    "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, anonymous usage statistics, configuration-driven tool definitions, a command-line interface, and automated testing.

```text
19 passed
```

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