Metadata-Version: 2.4
Name: ndev-stack
Version: 0.1.0
Summary: Cross-platform developer stack manager for PHP, FastCGI/PHP-FPM, MariaDB, 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

`ndev` is a powerful, non-root / non-admin developer tool suite to manage, run, and isolate PHP runtimes (PHP-FPM on Linux, FastCGI worker pools on Windows), PECL extensions, MySQL/MariaDB databases, Nginx virtual hosts, trusted local SSL certificates, Mailpit email sandbox, and public HTTP tunneling natively on **Linux** (Debian/Ubuntu) and **Windows 10/11**.

A single unified repository and package with automatic OS detection that uses native operating system primitives for each platform.

<p align="center">
  <img src="ui.PNG" alt="ndev Interactive TUI Dashboard" width="850">
</p>

---

## Key Features

- **Multi-Version PHP Management**:
  - **Linux**: Sandboxed source compilation (`5.6` – `8.5`) inside an unprivileged `bubblewrap` environment with custom, self-healing multiarch paths.
  - **Windows**: Instant zero-compilation prebuilt official binaries from `windows.php.net` (NTS & TS, x64 & x86).
- **Process & Daemon Model**:
  - **Linux**: Isolated native `php-fpm` worker pools communicating over Unix domain sockets (`~/.ndev/run/php<ver>.sock`).
  - **Windows**: Deterministic multi-process `php-cgi.exe` FastCGI worker pools load-balanced by Nginx `upstream` blocks.
- **Interactive Terminal UI Dashboard (`ui` / `tui` / `dashboard`)**: Modern, asynchronous Textual TUI dashboard for real-time stack monitoring, live auto-refresh, quick batch actions (Start/Stop/Restart All), active CLI PHP switching, integrated log tailing, and virtual host launching.
- **Interactive Control Menu (`ctl`)**: Unified terminal service selector to monitor and control Nginx, MariaDB, phpMyAdmin, and PHP instances.
- **Nginx Virtual Host Manager (`vhost`)**: Automated Nginx server blocks with custom upstreams, canonical HTTP $\rightarrow$ HTTPS redirects, trusted local SSL certificate generation (`mkcert`), and `/etc/hosts` / Windows `hosts` mapping.
- **SQL Database Manager (`db`)**: Interactive wizard and CLI suite to create/drop databases, manage users, grant permissions, and export SQL dumps (`mysqldump`).
- **PECL Extension Manager (`ext`)**: Compiles or downloads precompiled PECL `.dll` / `.so` binaries (Redis, Xdebug, etc.) and enables/disables them per PHP version.
- **Local Email Sandbox (`mailpit`)**: Zero-dependency local SMTP email catcher & modern web UI (`http://127.0.0.1:8025`) using prebuilt binaries.
- **phpMyAdmin Background Service (`pma`)**: One-command background phpMyAdmin service management served locally over `http://127.0.0.1:8080`.
- **Public HTTP Tunneling (`grok`)**: Interactive ngrok tunnel launcher to proxy local virtual hosts over the web with automatic Host header rewriting.
- **Automated Stack Setup (`setup`)**:
  - **Linux**: Installs MariaDB, Nginx, Composer, and creates symlinks in `~/.local/bin/`.
  - **Windows**: Portable zero-installer extraction of Nginx, MariaDB, mkcert, ngrok, Mailpit, Composer, and CA bundles under `%USERPROFILE%\.ndev\` with global batch shims on `PATH`.

---

## Platform Differences: Linux (`ndev`) vs. Windows (`ndev`)

| Subsystem | Linux (`ndev`) | Windows (`ndev`) |
| :--- | :--- | :--- |
| **PHP Distribution** | Compiles PHP from official source using `bubblewrap` sandbox and `gcc`/`make` | Downloads official precompiled Windows builds from `windows.php.net` (NTS & TS, x64 & x86) |
| **Process Model** | Native `php-fpm` daemon with Unix domain sockets (`~/.ndev/run/php<ver>.sock`) | Multi-process worker pool of `php-cgi.exe` instances over deterministic TCP ports (`13000+`), balanced via Nginx `upstream` |
| **CLI & PATH Switching** | Linux symlinks in `~/.local/bin/` (`php`, `composer`, `ndev`) pointing to `~/.ndev/current/` | Windows batch shims in `%USERPROFILE%\.ndev\shims\` (`php.bat`, `composer.bat`, `ndev.bat`) |
| **Privilege Elevation** | `sudo` for Nginx and `/etc/hosts` changes | Scoped Windows UAC elevation via Win32 `ShellExecuteExW` (`runas`) only when updating `hosts` file |
| **Web Server** | Host system package installed via `apt install nginx` (`/etc/nginx/`) | Portable standalone Nginx zip extracted to `%USERPROFILE%\.ndev\nginx\` |
| **Database** | Host system package installed via `apt install mariadb-server` | Portable MariaDB zip extracted to `%USERPROFILE%\.ndev\mariadb\` initialized via `mariadb-install-db.exe` |
| **PECL Extensions** | Source compilation (`phpize`, `./configure`, `make`) within build sandbox | Precompiled official PECL `.dll` downloads matching PHP version, VS compiler (`vs16`, `vs17`), and thread safety |
| **Email Sandbox** | Prebuilt Linux Mailpit binary in `~/.ndev/bin/mailpit` | Prebuilt Windows Mailpit binary in `%USERPROFILE%\.ndev\shims\mailpit.exe` |
| **phpMyAdmin** | Served via PHP's built-in web server (`php -S 127.0.0.1:8080`) | Served via PHP's built-in web server (`php.exe -S 127.0.0.1:8080`) |
| **Local SSL** | `mkcert` package via `apt` (`~/.ndev/certs/`) | Portable `mkcert.exe` downloaded into `%USERPROFILE%\.ndev\shims\` |
| **TUI Dashboard** | Asynchronous Textual TUI (`ndev ui`) with live auto-refresh | Asynchronous Textual TUI (`ndev ui`) with live auto-refresh |

---

## Codebase Architecture

```text
ndev/
├── main.py                 # Main entrypoint & automatic OS dispatcher
├── cli.py                  # CLI redirect to ndev.main
├── tui.py                  # TUI redirect to ndev.win.tui or ndev.linux.tui
├── common/                 # Cross-platform shared utilities
│   ├── constants.py        # Shared directory constants and defaults
│   ├── logger.py           # Rich logging engine
│   ├── config.py           # Configuration schema and loader
│   ├── github.py           # GitHub release query APIs
│   ├── manifest.py         # Build manifest and package index
│   └── utils.py            # Shared system & network helper functions
├── win/                    # Windows native subsystem
│   ├── cli.py              # Windows Click CLI command suite
│   ├── tui.py              # Windows Textual TUI Dashboard & Modals
│   ├── core/               # Windows core modules (paths, php, fcgi, services, vhost, mkcert, db, pma, mailpit, setup, upgrade)
│   └── templates/          # Nginx virtual host configuration templates
└── linux/                  # Linux native subsystem
    ├── cli.py              # Linux Typer CLI command suite
    ├── tui.py              # Linux Textual TUI Dashboard & Modals
    ├── commands/           # Linux CLI sub-commands (start, stop, vhost, ctl, etc.)
    ├── runtime/            # Linux daemon runners (fpm, pma, mailpit, process, upgrade)
    ├── php/                # Linux PHP source compilation & resolver
    └── chroot/             # Unprivileged bubblewrap sandbox manager
```

---

## Directory Structure & Layout

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

### 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 (patches include 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
├── run\                    # Active PID and FastCGI worker state files (JSON)
├── shims\                  # Global batch shims for PATH (php, composer, mysql, mailpit, ndev, etc.)
├── mailpit.db              # Persistent message database for Mailpit
└── config.json             # Global configuration (ports, worker counts)
```

---

## Installation

### Standard Installation via PyPI

Install `ndev-stack` directly using `pip` or `pipx` (recommended for standalone CLI tools):

```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`, but installs the global commands `ndev`, `ndev-win`, and `ndev-linux`.

---

## Quick Start Guide

### Windows 10 / 11

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

# 2. Download and configure portable stack (Nginx, MariaDB, 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 default-mysql-client
mkcert -install

# 2. Install ndev
pip install ndev

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

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

### Development / Source Installation

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

---

## 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`) |
| `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`, `pma`, `mailpit`, `<ver>`) |
| `ndev stop <target>` | Stop service or pool (`all`, `nginx`, `mariadb`, `pma`, `mailpit`, `<ver>`) |
| `ndev restart <target>`| Restart service or pool (`all`, `nginx`, `mariadb`, `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 ext` | Manage PECL extensions (`list`, `install`, `enable`, `disable`) |
| `ndev mailpit` | Manage local email sandbox (`install`, `start`, `stop`, `launch`, `open`) |
| `ndev pma` | Manage phpMyAdmin background service (`http://127.0.0.1:8080`) |
| `ndev grok` | Public HTTP tunneling for local virtual hosts via ngrok |
| `ndev upgrade` | Check for and upgrade stack components (Nginx, Mailpit, MariaDB, PMA, mkcert, Composer) |
| `ndev upgrade --check` | Check component versions against upstream releases without upgrading |
| `ndev shell` | Interactive developer subshell pre-loaded with PHP/Composer/MySQL 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 |

---

## Usage Guide

### PHP Version Management

```bash
# List available PHP versions from php.net / windows.php.net
ndev available
ndev available --archives    # include legacy releases

# Install a PHP version (compiled on Linux, downloaded on Windows)
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

# Check for newer minor/patch releases
ndev update

# Uninstall a PHP version
ndev uninstall 7.4
```

---

### Process & Service Management

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

# Control Nginx, MariaDB, phpMyAdmin, or Mailpit
ndev start nginx
ndev start mariadb
ndev start pma
ndev start mailpit
ndev start all

# Stop or restart all services
ndev stop all
ndev restart all

# Reload Nginx configuration without downtime
ndev reload nginx

# View service status dashboard
ndev status
ndev status 8.4
ndev status pma
ndev status mailpit
```

---

### Interactive Terminal UI Dashboard (`ui` / `dashboard`)

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

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

* **Live Status Dashboard**: Real-time health, PIDs, sockets/ports for Nginx, MariaDB, PMA (phpMyAdmin), Mailpit, and all PHP instances.
* **One-Click Component Setup & Upgrades**: Install uninstalled services (**PMA**, **Mailpit**, **Nginx**, **MariaDB**, **mkcert**, **Composer**) or check/upgrade stack releases with single-click UI actions.
* **Interactive Virtual Host Manager**: Create new virtual hosts (`＋ Create VHost`) with automatic mkcert SSL and docroot binding via modal dialog, or delete existing vhosts with full cleanup.
* **PHP Runtime Lifecycle**: Install new PHP runtimes (`＋ Install PHP`) from upstream releases, uninstall versions (`✖ Uninstall Selected`), switch active CLI version, or start/stop individual FastCGI pools.
* **Quick Batch Actions**: One-click **Start All**, **Stop All**, **Restart All**, and **Reload Nginx** from the persistent sidebar.
* **On-the-fly CLI PHP Switcher**: Change globally active CLI PHP version instantly via dropdown.
* **Integrated Log Tail Viewer**: Select and inspect live tails for Nginx, MariaDB, PHP, and Virtual Host logs.
* **Asynchronous & Non-Blocking**: Built with Textual workers — all background actions and I/O polling run smoothly without freezing the UI.

---

### Interactive CLI Control Menu (`ctl`)

Launch the interactive terminal service selector:
```bash
ndev ctl
```

---

### Virtual Host Management (`vhost`)

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

```bash
# Interactive wizard
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
ndev vhost-remove --domain project.local
```

---

### SQL Database Manager (`db`)

Manage MySQL/MariaDB databases and users:

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

```bash
# Launch interactive database wizard
ndev db

# Create a database
ndev db create-db mydb --owner myuser

# Create a database user with privileges
ndev db create-user myuser --new-password secret --grant-db mydb

# Export database dump
ndev db export-db mydb -o backup.sql

# Import database dump
ndev db import-db mydb backup.sql

# Drop a database
ndev db drop-db mydb
```

---

### PECL Extension Manager (`ext`)

Manage PECL extensions for any installed PHP version:

```bash
# List loaded extensions for a PHP version
ndev ext list 8.4

# Install a PECL extension (e.g. redis, xdebug)
ndev ext install redis 8.4

# Enable or disable an extension
ndev ext enable redis 8.4
ndev ext disable redis 8.4
```

---

### phpMyAdmin Management (`pma`)

Manage the phpMyAdmin database administration web UI served locally in the background:

> [!TIP]
> **phpMyAdmin Access & Credentials**:
> * **URL**: [http://127.0.0.1:8080](http://127.0.0.1:8080)
> * **Default Username**: `root`

```bash
# Start phpMyAdmin on port 8080 (auto-installs on first run)
ndev start pma

# Check status
ndev status pma

# Stop or restart phpMyAdmin
ndev stop pma
ndev restart pma
```

---

### Local Email Sandbox (`mailpit`)

Catch every outgoing e-mail your local project sends without hitting real inboxes, using [Mailpit](https://github.com/axllent/mailpit) — a fast, zero-dependency prebuilt binary with a modern web UI.

> [!TIP]
> **SMTP & Web UI Defaults**:
> * **SMTP server** → `127.0.0.1:1025` ← point your PHP / Laravel / WordPress app here
> * **Web inbox**   → [http://127.0.0.1:8025](http://127.0.0.1:8025)
> * No authentication required — every sent email is safely captured locally.

```bash
# Install prebuilt binary from GitHub releases
ndev mailpit install

# Start the sandbox (auto-downloads if not present)
ndev mailpit start
ndev start mailpit

# Launch / open Web UI in your default browser
ndev mailpit launch
ndev mailpit open

# View status
ndev mailpit status
ndev status mailpit

# Stop or restart
ndev mailpit stop
ndev stop mailpit
ndev mailpit restart
ndev restart mailpit

# Custom ports
ndev mailpit start --smtp-port 2525 --web-port 8085
```

#### Configuring your PHP project to use Mailpit

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

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

**WordPress (`wp-config.php` / SMTP Plugin):**
* **Host**: `127.0.0.1`
* **Port**: `1025`
* **Encryption**: None / Plain
* **Authentication**: None / No

Or via Symfony Mailer / PHPMailer / Python / Node.js — just send SMTP traffic to `127.0.0.1:1025`.

---

### Interactive Developer Shell (`shell`)

Open an interactive shell pre-configured with active PHP, Composer, MySQL, and Nginx on your `PATH`:

```bash
ndev shell
```

---

### Public HTTP Tunneling (`grok`)

Tunnel any configured local virtual host to the public web via `ngrok`:

```bash
ndev grok
```

---

### Diagnostics & Log Viewing

```bash
# Run environment diagnostics
ndev doctor

# View / tail logs
ndev logs
ndev logs 8.4

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

---

## Configuration

### Linux
* **Global Configuration**: `~/.ndev/config.toml`
* **PHP Configuration (`php.ini`)**: `~/.ndev/php/<version>/etc/php.ini`
* **Extension Configurations (`conf.d/`)**: `~/.ndev/php/<version>/etc/conf.d/<ext>.ini`
* **PHP-FPM Server Configuration**: `~/.ndev/php/<version>/etc/php-fpm.conf`
* **PHP-FPM Pool Configuration**: `~/.ndev/php/<version>/etc/php-fpm.d/www.conf`

### Windows
* **Global Configuration**: `%USERPROFILE%\.ndev\config.json`
* **PHP Configuration (`php.ini`)**: `%USERPROFILE%\.ndev\php\<version>\php.ini`
* **Nginx Configuration**: `%USERPROFILE%\.ndev\nginx\conf\nginx.conf`
* **Virtual Host Configs**: `%USERPROFILE%\.ndev\nginx\conf\ndev-vhosts\*.conf`
* **FastCGI Worker Pools**: Configurable base port (default: `13000`) and workers per version (default: `4`) in `config.json`.
