esim-tool-manager 0.1.0__tar.gz

esim_tool_manager-0.1.0/PKG-INFO

@@ -0,0 +1,599 @@
+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.