Metadata-Version: 2.4
Name: ndev-stack
Version: 0.3.0
Summary: Cross-platform developer stack manager for PHP, FastCGI/PHP-FPM, MariaDB, Redis, PostgreSQL, MongoDB, Nginx, SSL, and Mailpit on Linux and Windows
Author-email: Ankit Karan <ankit.karan99@gmail.com>
Project-URL: Homepage, https://github.com/ankitkaran99/ndev
Project-URL: Repository, https://github.com/ankitkaran99/ndev
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1.0
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=0.40.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: filelock>=3.12.0
Requires-Dist: packaging>=23.0
Requires-Dist: jinja2>=3.1.0

# ndev

<p align="center">
  <h1 align="center">ndev</h1>
  <p align="center"><strong>Universal, Zero-Config Local PHP & Web Development Stack for Windows and Linux.</strong></p>
</p>

<p align="center">
  <a href="https://pypi.org/project/ndev-stack/"><img src="https://img.shields.io/pypi/v/ndev-stack.svg?color=blue" alt="PyPI Version"></a>
  <a href="https://pypi.org/project/ndev-stack/"><img src="https://img.shields.io/pypi/pyversions/ndev-stack.svg" alt="Python Versions"></a>
  <a href="https://github.com/ankitkaran99/ndev/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
</p>

<p align="center">
  <img src="ui.PNG" alt="ndev Interactive Terminal UI Dashboard" width="90%">
</p>

---

`ndev` is an all-in-one developer environment manager that isolates, orchestrates, and runs multi-version **PHP** runtimes, **Nginx** web server, **MariaDB / MySQL**, **Redis** in-memory store, **phpMyAdmin**, **Mailpit** email sandbox, local **SSL** certificates (`mkcert`), and public HTTP tunnels (`ngrok`) on **Windows 10/11** and **Linux** (Debian/Ubuntu).

---

## Key Features

- **Multi-Version PHP Environment**:
  - **Windows**: Zero-compilation prebuilt official binaries from `windows.php.net` (PHP 5.6 – 8.5, Thread-Safe & Non-Thread-Safe, x64/x86).
  - **Linux**: Sandboxed, unprivileged source compilation with `bubblewrap` and self-healing multiarch library paths.
- **Process Orchestration & FastCGI / FPM**:
  - **Windows**: Multi-process `php-cgi.exe` FastCGI worker pools load-balanced through Nginx `upstream` blocks.
  - **Linux**: Native `php-fpm` worker daemons over isolated Unix sockets (`~/.ndev/run/php<ver>.sock`).
- **Interactive Asynchronous TUI Dashboard (`ndev ui`)**:
  - Full-screen real-time terminal UI built with Textual for live monitoring, batch start/stop/restart, on-the-fly CLI PHP version switching, folder-picker virtual host creator, and live log tailing.
- **Automated Nginx Virtual Hosts (`ndev vhost`)**:
  - Generates Nginx server blocks with custom FastCGI upstreams, HTTP $\rightarrow$ HTTPS redirects, trusted local SSL certificates, and hosts file mappings.
- **In-Memory Store (`ndev redis`)**:
  - Native background Redis server management (`6379`) with interactive `redis-cli` terminal integration.
- **Local Email Sandbox (`ndev mailpit`)**:
  - Embedded zero-dependency SMTP email catcher (`127.0.0.1:1025`) and web inbox (`http://127.0.0.1:8025`).
- **Database & Web Administration (`ndev db` & `ndev pma`)**:
  - Portable MariaDB server (`3306`) with user/database management CLI tools and local phpMyAdmin (`http://127.0.0.1:8080`).
- **Single-Command Stack Upgrader (`ndev upgrade`)**:
  - Automated version scanning and non-destructive upgrading for Nginx, MariaDB, Redis, Mailpit, phpMyAdmin, mkcert, and Composer.

---

## Architecture & Platform Mapping

```text
ndev/
├── main.py                 # Cross-platform dispatcher & runtime detector
├── common/                 # Shared utilities, configs, logger, GitHub API
├── win/                    # Windows native subsystem (FastCGI, Shims, Click CLI, TUI)
│   ├── core/               # php, services, fcgi, vhost, db, redis_core, mailpit, pma, upgrade
│   └── templates/          # Nginx virtual host configuration templates
└── linux/                  # Linux native subsystem (PHP-FPM, Typer CLI, TUI, Chroot)
    ├── php/                # Source resolver, downloader, extensions, builder
    ├── chroot/             # Bubblewrap sandbox manager
    └── runtime/            # FPM, PMA, Mailpit, and systemd daemons
```

| Subsystem | Windows 10/11 (`ndev-win`) | Linux Debian/Ubuntu (`ndev-linux`) |
| :--- | :--- | :--- |
| **PHP Distribution** | Precompiled binaries from `windows.php.net` | Compiles from official source via `bubblewrap` sandbox |
| **Process Model** | Multi-worker `php-cgi.exe` pools via Nginx `upstream` | Native `php-fpm` daemons over Unix domain sockets |
| **CLI & PATH** | Global batch shims in `%USERPROFILE%\.ndev\shims\` | Symlinks in `~/.local/bin/` |
| **Privilege Elevation**| Win32 `ShellExecuteExW` (`runas`) only for `hosts` | `sudo` for Nginx and `/etc/hosts` |
| **Web Server** | Portable Nginx in `%USERPROFILE%\.ndev\nginx\` | System Nginx via `apt install nginx` |
| **Database** | Portable MariaDB in `%USERPROFILE%\.ndev\mariadb\` | System MariaDB via `apt install mariadb-server` |
| **In-Memory Cache** | Portable Redis in `%USERPROFILE%\.ndev\redis\` | System Redis via `apt install redis-server` |
| **Email Sandbox** | Standalone prebuilt Mailpit binary | Standalone prebuilt Mailpit binary |
| **phpMyAdmin** | Served via PHP CLI server (`http://127.0.0.1:8080`) | Served via PHP CLI server (`http://127.0.0.1:8080`) |
| **Local SSL** | Standalone `mkcert.exe` in `shims\` | System `mkcert` package via `apt` |
| **TUI Dashboard** | Asynchronous Textual TUI (`ndev ui`) | Asynchronous Textual TUI (`ndev ui`) |

---

## Directory Structure & Layout

### Windows Layout (`%USERPROFILE%\.ndev`)
```text
%USERPROFILE%\.ndev\
├── certs\                  # Local SSL certificates and cacert.pem CA bundle
├── downloads\              # Cached zip downloads
├── mariadb\                # Portable MariaDB installation & data directory
│   ├── bin\                # mysqld.exe, mysql.exe, mysqldump.exe
│   └── data\               # Database storage
├── nginx\                  # Portable Nginx installation
│   ├── conf\
│   │   ├── nginx.conf      # Main Nginx config (includes ndev-vhosts/*.conf)
│   │   └── ndev-vhosts\    # Virtual host configurations (*.conf)
│   ├── logs\               # Nginx access/error logs per virtual host
│   └── temp\               # FastCGI and proxy client temporary body storage
├── php\
│   └── <version>\          # Extracted PHP binaries (php.exe, php-cgi.exe, php.ini, ext/)
├── pma\                    # Standalone phpMyAdmin installation & config.inc.php
├── redis\                  # Portable Redis server and redis-cli binaries
├── run\                    # Active PID and FastCGI worker state files (JSON)
├── shims\                  # Global batch shims for PATH (php, composer, mysql, redis-cli, mailpit, ndev, etc.)
├── mailpit.db              # Persistent message database for Mailpit
└── config.json             # Global configuration (ports, worker counts)
```

### Linux Layout (`~/.ndev`)
```text
~/.ndev/
├── bin/                    # Standalone binaries (mailpit)
├── builds/                 # Source tarballs and compilation build directories
├── cache/                  # Download and build cache
├── certs/                  # Local SSL certificates and mkcert root CA
├── chroot/                 # Sandboxed development packages and build root
├── downloads/              # Downloaded source archives
├── logs/                   # Service and daemon logs (pma.log, mailpit.log, etc.)
├── php/
│   └── <version>/          # Compiled PHP installations (bin/, sbin/, etc/php.ini, etc/php-fpm.d/)
├── phpmyadmin/             # Standalone phpMyAdmin installation & config.inc.php
├── run/                    # Active PID and Unix domain socket files (*.sock, *.pid)
├── current                 # Symlink pointing to the currently active PHP version directory
├── mailpit.db              # Persistent message database for Mailpit
└── config.toml             # Global build and runtime configuration
```

---

## Installation

### Standard Installation via PyPI

Install `ndev-stack` using `pip` or `pipx`:

```bash
# Using pip
pip install ndev-stack

# Or using pipx (isolated application environment)
pipx install ndev-stack
```

> **Note**: The package is published on PyPI as `ndev-stack`, which provides the global commands `ndev`, `ndev-win`, and `ndev-linux`.

### Development / Source Installation

```bash
git clone https://github.com/ankitkaran99/ndev.git
cd ndev
pip install -e .
```

---

## Quick Start Guide

### Windows 10 / 11

```powershell
# 1. Install ndev-stack
pip install ndev-stack

# 2. Download and configure portable stack (Nginx, MariaDB, Redis, mkcert, Mailpit, Composer)
ndev setup

# 3. Add shims to user PATH (one-time setup for global CLI access)
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\.ndev\shims", "User")
$env:Path += ";$env:USERPROFILE\.ndev\shims"

# 4. Verify installation & launch interactive dashboard
ndev doctor
ndev ui
```

### Linux (Debian / Ubuntu)

```bash
# 1. Install system build dependencies
sudo apt update
sudo apt install -y bubblewrap build-essential pkg-config nginx mkcert redis-server default-mysql-client
mkcert -install

# 2. Install ndev-stack
pip install ndev-stack

# 3. Bootstrap runtime environment and shims
ndev setup
export PATH="$HOME/.local/bin:$PATH"

# 4. Verify installation & launch interactive dashboard
ndev doctor
ndev ui
```

---

## Quick Command Reference

| Command | Action |
|---|---|
| `ndev ui` | Launch real-time Textual TUI dashboard (*aliases: `tui`, `dashboard`*) |
| `ndev available` | List available PHP releases (`--archives` for legacy versions) |
| `ndev install <ver>` | Install / compile a PHP version (`8.4`, `8.3`, `7.4`, etc.) |
| `ndev use <ver>` | Switch active CLI PHP version on PATH |
| `ndev current` | Show active CLI PHP version |
| `ndev list` | List installed PHP versions and daemon / worker pool status |
| `ndev start <target>` | Start service or pool (`all`, `nginx`, `mariadb`, `redis`, `pma`, `mailpit`, `<ver>`) |
| `ndev stop <target>` | Stop service or pool (`all`, `nginx`, `mariadb`, `redis`, `pma`, `mailpit`, `<ver>`) |
| `ndev restart <target>`| Restart service or pool (`all`, `nginx`, `mariadb`, `redis`, `pma`, `mailpit`, `<ver>`) |
| `ndev reload nginx` | Reload Nginx configuration without downtime |
| `ndev status` | View real-time service status dashboard |
| `ndev ctl` | Interactive terminal service control menu |
| `ndev vhost` | Interactive virtual host creation wizard with local SSL |
| `ndev vhost-list` | List all configured virtual hosts |
| `ndev vhost-remove` | Remove virtual host and clean up hosts file |
| `ndev db` | Interactive SQL database management wizard |
| `ndev redis` | Manage Redis server or launch interactive `redis-cli` |
| `ndev mailpit` | Manage local email sandbox (`install`, `start`, `stop`, `launch`, `open`) |
| `ndev pma` | Manage phpMyAdmin background service (`http://127.0.0.1:8080`) |
| `ndev ext` | Manage PECL extensions (`list`, `install`, `enable`, `disable`) |
| `ndev grok` | Public HTTP tunneling for local virtual hosts via ngrok |
| `ndev postgres` | Manage PostgreSQL server (`install`, `start`, `stop`, `restart`, `status`) |
| `ndev mongodb` | Manage MongoDB server (`install`, `start`, `stop`, `restart`, `status`) |
| `ndev module list` | List all dynamic modules and status in `<userdir>/.ndev/modules/` |
| `ndev module <action>`| Manage dynamic module lifecycle (`install`, `start`, `stop`, `restart`, `status`, `open`) |
| `ndev module create` | Scaffold a new dynamic module with manifest and template code |
| `ndev upgrade` | Check for and upgrade stack components (Nginx, MariaDB, Redis, PMA, Mailpit, mkcert, Composer) |
| `ndev upgrade --check` | Check component versions against upstream releases without upgrading |
| `ndev shell` | Interactive developer subshell pre-loaded with PHP/Composer/MySQL/Redis on PATH |
| `ndev doctor` | Run environment diagnostics and health checks |
| `ndev logs` | View and tail service and virtual host logs |
| `ndev clean` | Clean up downloads cache and stale runtime state |

---

## Detailed Usage Guide

### 1. Interactive Terminal UI Dashboard (`ndev ui`)

Launch the modern, responsive Textual TUI dashboard for real-time monitoring and process control:

```bash
ndev ui
# Aliases: ndev tui, ndev dashboard
```

- **Live Status Grid**: Monitor real-time status, PIDs, and active ports for Nginx, MariaDB, Redis, PMA, Mailpit, and PHP worker pools.
- **One-Click Component Setup & Upgrades**: Install uninstalled services (**Redis**, **PMA**, **Mailpit**, **Nginx**, **MariaDB**, **mkcert**, **Composer**) or upgrade existing components with single-click UI actions.
- **Interactive Virtual Host Manager**: Create new virtual hosts (`＋ Create VHost`) with automatic local SSL (`mkcert`) and an integrated folder-picker dialog.
- **PHP Runtime Management**: Install any PHP version (`＋ Install PHP`), uninstall versions (`✖ Uninstall Selected`), or change the active CLI PHP version via dropdown.
- **Batch Actions**: One-click **Start All**, **Stop All**, **Restart All**, and **Reload Nginx** from the persistent sidebar.
- **Integrated Log Tail Viewer**: Select and inspect live logs for Nginx, MariaDB, Redis, PHP, and Virtual Hosts.

---

### 2. PHP Version Management

```bash
# List available PHP releases (from php.net / windows.php.net)
ndev available
ndev available --archives    # include legacy releases (5.6 - 7.3)

# Install a PHP version (prebuilt on Windows, source-compiled on Linux)
ndev install 8.4

# List locally installed PHP versions and daemon/pool status
ndev list

# Switch globally active CLI PHP version
ndev use 8.4

# Show current active CLI PHP version
ndev current

# Uninstall a PHP version
ndev uninstall 7.4
```

---

### 3. Service & Process Management

```bash
# Start / Stop / Restart a PHP pool or individual service
ndev start 8.4
ndev stop 8.4
ndev restart 8.4

# Control core services
ndev start nginx
ndev start mariadb
ndev start redis
ndev start pma
ndev start mailpit

# Batch operations
ndev start all
ndev stop all
ndev restart all

# Reload Nginx configuration without downtime
ndev reload nginx

# View service status
ndev status
```

---

### 4. Virtual Host Management (`vhost`)

Create and manage local Nginx sites mapped to `127.0.0.1`:

```bash
# Interactive wizard (auto-prompts for domain, document root, PHP version, and SSL)
ndev vhost

# Create a standard HTTP virtual host
ndev vhost --domain project.local --root /path/to/project --php 8.4

# Create an HTTPS virtual host with trusted local SSL certificates (mkcert)
ndev vhost --domain project.local --root /path/to/project --php 8.4 --ssl

# List all configured virtual hosts
ndev vhost-list

# Remove a virtual host (removes Nginx conf and cleans hosts file)
ndev vhost-remove --domain project.local
```

---

### 5. Redis In-Memory Store (`redis`)

Manage the local Redis server and launch the interactive `redis-cli`:

> [!TIP]
> **Redis Connection Defaults**:
> * **Host**: `127.0.0.1` or `localhost`
> * **Port**: `6379`
> * **Password**: None (default)

```bash
# Start Redis server
ndev redis start
ndev start redis

# Check Redis status
ndev redis status
ndev status redis

# Open interactive redis-cli terminal
ndev redis cli

# Stop or restart Redis server
ndev redis stop
ndev redis restart
```

#### Laravel / Symfony / WordPress Configuration:
```env
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
```

---

### 6. SQL Database Manager (`db`) & phpMyAdmin (`pma`)

Manage MySQL/MariaDB databases, users, and web administration:

> [!TIP]
> **Default MariaDB / MySQL Credentials**:
> * **Host**: `127.0.0.1` or `localhost`
> * **Port**: `3306`
> * **Username**: `root`
> * **Password**: `root` (Windows) / system auth (Linux)
> * **phpMyAdmin URL**: [http://127.0.0.1:8080](http://127.0.0.1:8080)

```bash
# Launch interactive database management wizard
ndev db

# Create database and user
ndev db create-db mydb --owner myuser
ndev db create-user myuser --new-password secret --grant-db mydb

# Export & import database dumps
ndev db export-db mydb -o backup.sql
ndev db import-db mydb backup.sql

# Start phpMyAdmin web UI
ndev start pma
ndev pma
```

---

### 7. Local Email Sandbox (`mailpit`)

Catch every outgoing e-mail your local applications send using [Mailpit](https://github.com/axllent/mailpit):

> [!TIP]
> **SMTP & Web UI Defaults**:
> * **SMTP Server**: `127.0.0.1:1025`
> * **Web Inbox**: [http://127.0.0.1:8025](http://127.0.0.1:8025)
> * No authentication required — all emails are safely intercepted locally.

```bash
# Start Mailpit (auto-installs if not present)
ndev mailpit start
ndev start mailpit

# Open Web UI in default browser
ndev mailpit launch
ndev mailpit open

# Stop or restart Mailpit
ndev mailpit stop
ndev mailpit restart
```

#### Configuring Mailpit in your Project:

**Laravel (`.env`):**
```env
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
```

**PHP (`php.ini`):**
```ini
[mail function]
SMTP = 127.0.0.1
smtp_port = 1025
```

---

### 8. Stack Upgrade Engine (`upgrade`)

Scan for and upgrade stack components (Nginx, MariaDB, Redis, PMA, Mailpit, mkcert, Composer) safely against latest upstream releases:

```bash
# Check for available updates across all stack components
ndev upgrade --check

# Upgrade all components to latest stable releases
ndev upgrade

# Upgrade a specific component
ndev upgrade redis
ndev upgrade mailpit
ndev upgrade pma
```

---

### 9. Diagnostics & Developer Tools

```bash
# Run full environment health check
ndev doctor

# Launch pre-configured developer subshell
ndev shell

# Tail live logs for services or virtual hosts
ndev logs
ndev logs 8.4
ndev logs nginx

# Tunnel local virtual host to public web via ngrok
ndev grok

# Clean download cache and temporary files
ndev clean
```

---

### 10. Extensible Dynamic Modules (`ndev module`)

`ndev` features a modular architecture where core services (`nginx`, `mariadb`, `php`, `phpmyadmin`, `ngrok`) are augmented with dynamic modules (`mailpit`, `redis`, `postgres`, `mongodb`, and custom community modules) located in `<userdir>/.ndev/modules/<module_name>/`.

#### Module Commands:
```bash
# List all discovered modules and running status
ndev module list

# Manage module lifecycle
ndev module install mailpit
ndev module start redis
ndev module status postgres
ndev module status mongodb
ndev module open mailpit     # Opens web UI if available
ndev module restart redis
ndev module stop redis

# Direct convenience commands also work seamlessly:
ndev start mailpit
ndev stop redis
ndev postgres start
ndev postgres status
ndev mongodb start
ndev mongodb status

# Scaffold a new custom module
ndev module create my-service --display-name "My Custom Service" --category queue --port 9000
```

#### Module Structure (`~/.ndev/modules/<name>/`):
```text
~/.ndev/modules/my-service/
├── manifest.json   # Module metadata, ports, categories, and web UI definitions
└── module.py       # Python lifecycle handler (is_installed, install, start, stop, restart, status, open_ui)
```

**Sample `manifest.json`:**
```json
{
  "name": "my-service",
  "display_name": "My Custom Service",
  "version": "1.0.0",
  "description": "Custom queue worker service",
  "category": "queue",
  "ports": [9000],
  "web_ui": "http://127.0.0.1:9000",
  "platforms": ["windows", "linux"],
  "entrypoint": "module.py"
}
```

Dynamic modules appear automatically inside the **TUI Dashboard (`ndev ui`)**, where you can start, stop, restart, and open web interfaces with a single click.

> 📖 **Looking to build your own module?** See the full [**ndev Module Developer Guide (MODULE_DEV_GUIDE.md)**](MODULE_DEV_GUIDE.md) for step-by-step instructions, manifest schema, and boilerplate templates.

---

## Configuration Files

### Windows
* **Global Settings**: `%USERPROFILE%\.ndev\config.json`
* **PHP Configuration**: `%USERPROFILE%\.ndev\php\<version>\php.ini`
* **Nginx Main Config**: `%USERPROFILE%\.ndev\nginx\conf\nginx.conf`
* **Virtual Host Configs**: `%USERPROFILE%\.ndev\nginx\conf\ndev-vhosts\*.conf`
* **FastCGI Worker Pools**: Base port `13000` with 4 workers per PHP version (customizable in `config.json`).

### Linux
* **Global Settings**: `~/.ndev/config.toml`
* **PHP Configuration**: `~/.ndev/php/<version>/etc/php.ini`
* **PHP Extensions**: `~/.ndev/php/<version>/etc/conf.d/<ext>.ini`
* **PHP-FPM Pool Config**: `~/.ndev/php/<version>/etc/php-fpm.d/www.conf`

---

## License

MIT License. See [LICENSE](LICENSE) for more details.
