ndev-stack 0.1.0__py3-none-any.whl

ndev/linux/commands/db.py

@@ -0,0 +1,319 @@
+import os
+import sys
+import shutil
+import subprocess
+import typer
+from typing import Optional
+from rich.console import Console
+from ndev.common.logger import logger
+
+console = Console()
+
+db_app = typer.Typer(help="Manage MySQL databases and users", invoke_without_command=True)
+
+# Shared options for commands
+def execute_sql_mysql(host: str, port: int, user: str, password: Optional[str], sql: str) -> subprocess.CompletedProcess:
+    cmd = ["mysql", "-h", host, "-P", str(port), "-u", user, "--batch", "--skip-column-names"]
+    if password:
+        cmd.append(f"--password={password}")
+    return subprocess.run(cmd, input=sql, capture_output=True, text=True)
+
+def confirm_destructive(force: bool, database: str, message: str):
+    if force:
+        return
+    console.print(f"\n[bold yellow]WARNING: {message}[/bold yellow]")
+    confirm = typer.prompt("Type the database/username to confirm")
+    if confirm != database:
+        logger.error("Confirmation failed. Aborting.")
+        raise typer.Exit(code=1)
+
+def run_wizard():
+    console.print("\n========================================")
+    console.print("      NDev MySQL Database Manager Wizard")
+    console.print("========================================")
+    
+    # 1. Connection Details
+    host = typer.prompt("Host", default="localhost")
+    port = typer.prompt("Port", default=3306, type=int)
+    
+    admin_user = typer.prompt("Admin username", default="root")
+    admin_password = typer.prompt("Admin password", default="", hide_input=True)
+    
+    # 2. Action
+    console.print("\nOperation:")
+    console.print("  1) Create Database")
+    console.print("  2) Drop Database")
+    console.print("  3) Export Database (mysqldump)")
+    console.print("  4) Create User")
+    console.print("  5) Drop User")
+    op_choice = typer.prompt("Choice [1-5]", default=1, type=int)
+    
+    action_map = {1: "create-db", 2: "drop-db", 3: "export-db", 4: "create-user", 5: "drop-user"}
+    action = action_map.get(op_choice, "create-db")
+    
+    target_name = typer.prompt("Database/Username")
+    if not target_name:
+        logger.error("Target name is required.")
+        raise typer.Exit(code=1)
+        
+    # Execute actions
+    if action == "create-db":
+        owner = typer.prompt("User to grant privileges to (optional)", default="")
+        user_host = typer.prompt("Host for mysql user (optional)", default="%") if owner else "%"
+        execute_create_db(host, port, admin_user, admin_password, target_name, owner, user_host, "utf8mb4", "utf8mb4_unicode_ci")
+    elif action == "drop-db":
+        confirm_destructive(False, target_name, f"You are about to DROP database '{target_name}' permanently.")
+        execute_drop_db(host, port, admin_user, admin_password, target_name)
+    elif action == "export-db":
+        output_path = typer.prompt("Output SQL file path (optional, press Enter for default stdout/filename)", default=f"{target_name}.sql")
+        execute_export_db(host, port, admin_user, admin_password, target_name, output_path)
+    elif action == "create-user":
+        new_password = typer.prompt("New password for user", hide_input=True)
+        grant_db = typer.prompt("Database to grant privileges to", default=target_name)
+        user_host = typer.prompt("Host for mysql user (optional)", default="%")
+        execute_create_user(host, port, admin_user, admin_password, target_name, new_password, grant_db, user_host)
+    elif action == "drop-user":
+        confirm_destructive(False, target_name, f"You are about to DROP user '{target_name}' permanently.")
+        execute_drop_user(host, port, admin_user, admin_password, target_name, "%")
+
+def execute_create_db(host: str, port: int, user: str, password: Optional[str], database: str, owner: str, user_host: str, charset: str, collation: str):
+    logger.info(f"Creating MySQL database '{database}'...")
+    if not shutil.which("mysql"):
+        logger.error("mysql CLI tool not found.")
+        raise typer.Exit(code=1)
+    sql = f"CREATE DATABASE IF NOT EXISTS `{database}` CHARACTER SET {charset} COLLATE {collation};"
+    res = execute_sql_mysql(host, port, user, password, sql)
+    if res.returncode != 0:
+        logger.error(f"MySQL Error:\n{res.stderr}")
+        raise typer.Exit(code=1)
+        
+    if owner:
+        logger.info(f"Granting all privileges on {database} to {owner}...")
+        grant_sql = f"GRANT ALL PRIVILEGES ON `{database}`.* TO '{owner}'@'{user_host}'; FLUSH PRIVILEGES;"
+        res = execute_sql_mysql(host, port, user, password, grant_sql)
+        if res.returncode != 0:
+            logger.error(f"MySQL Error:\n{res.stderr}")
+            raise typer.Exit(code=1)
+    console.print(f"[bold green]Database '{database}' created successfully.[/bold green]")
+
+def execute_drop_db(host: str, port: int, user: str, password: Optional[str], database: str):
+    logger.info(f"Dropping MySQL database '{database}'...")
+    if not shutil.which("mysql"):
+        logger.error("mysql CLI tool not found.")
+        raise typer.Exit(code=1)
+    sql = f"DROP DATABASE IF EXISTS `{database}`;"
+    res = execute_sql_mysql(host, port, user, password, sql)
+    if res.returncode != 0:
+        logger.error(f"MySQL Error:\n{res.stderr}")
+        raise typer.Exit(code=1)
+    console.print(f"[bold green]Database '{database}' dropped successfully.[/bold green]")
+
+def execute_export_db(
+    host: str,
+    port: int,
+    user: str,
+    password: Optional[str],
+    database: str,
+    output: Optional[str] = None,
+    quick: bool = True,
+    single_transaction: bool = True,
+    routines: bool = True,
+    triggers: bool = True
+):
+    logger.info(f"Exporting MySQL database '{database}'...")
+    if not shutil.which("mysqldump"):
+        logger.error("mysqldump CLI tool not found.")
+        raise typer.Exit(code=1)
+
+    cmd = ["mysqldump", "-h", host, "-P", str(port), "-u", user]
+    if password:
+        cmd.append(f"--password={password}")
+    if quick:
+        cmd.append("--quick")
+    if single_transaction:
+        cmd.append("--single-transaction")
+    if routines:
+        cmd.append("--routines")
+    if triggers:
+        cmd.append("--triggers")
+    cmd.append(database)
+
+    if output:
+        out_path = os.path.abspath(output)
+        out_dir = os.path.dirname(out_path)
+        if out_dir and not os.path.exists(out_dir):
+            os.makedirs(out_dir, exist_ok=True)
+        try:
+            with open(out_path, "w", encoding="utf-8") as f:
+                res = subprocess.run(cmd, stdout=f, stderr=subprocess.PIPE, text=True)
+        except Exception as e:
+            logger.error(f"Failed to open output file '{out_path}': {e}")
+            raise typer.Exit(code=1)
+        if res.returncode != 0:
+            logger.error(f"mysqldump Error:\n{res.stderr}")
+            raise typer.Exit(code=1)
+        console.print(f"[bold green]Database '{database}' exported successfully to '{out_path}'.[/bold green]")
+    else:
+        res = subprocess.run(cmd, capture_output=True, text=True)
+        if res.returncode != 0:
+            logger.error(f"mysqldump Error:\n{res.stderr}")
+            raise typer.Exit(code=1)
+        sys.stdout.write(res.stdout)
+
+def execute_create_user(host: str, port: int, user: str, password: Optional[str], new_user: str, new_pass: str, grant_db: Optional[str], user_host: str):
+    logger.info(f"Creating user '{new_user}' on MySQL...")
+    if not shutil.which("mysql"):
+        logger.error("mysql CLI tool not found.")
+        raise typer.Exit(code=1)
+    sql = f"CREATE USER IF NOT EXISTS '{new_user}'@'{user_host}' IDENTIFIED BY '{new_pass}';"
+    res = execute_sql_mysql(host, port, user, password, sql)
+    if res.returncode != 0:
+        logger.error(f"MySQL Error:\n{res.stderr}")
+        raise typer.Exit(code=1)
+        
+    if grant_db:
+        logger.info(f"Granting all privileges on {grant_db}.* to {new_user}...")
+        grant_sql = f"GRANT ALL PRIVILEGES ON `{grant_db}`.* TO '{new_user}'@'{user_host}'; FLUSH PRIVILEGES;"
+        res = execute_sql_mysql(host, port, user, password, grant_sql)
+        if res.returncode != 0:
+            logger.error(f"MySQL Error:\n{res.stderr}")
+            raise typer.Exit(code=1)
+    console.print(f"[bold green]User '{new_user}' created successfully.[/bold green]")
+
+def execute_drop_user(host: str, port: int, user: str, password: Optional[str], drop_user: str, user_host: str):
+    logger.info(f"Dropping user '{drop_user}' on MySQL...")
+    if not shutil.which("mysql"):
+        logger.error("mysql CLI tool not found.")
+        raise typer.Exit(code=1)
+    sql = f"DROP USER IF EXISTS '{drop_user}'@'{user_host}'; FLUSH PRIVILEGES;"
+    res = execute_sql_mysql(host, port, user, password, sql)
+    if res.returncode != 0:
+        logger.error(f"MySQL Error:\n{res.stderr}")
+        raise typer.Exit(code=1)
+    console.print(f"[bold green]User '{drop_user}' dropped successfully.[/bold green]")
+
+# CLI command entry points
+@db_app.callback(invoke_without_command=True)
+def db_callback(ctx: typer.Context):
+    """Wizard to manage databases & users if run without subcommands."""
+    if ctx.invoked_subcommand is None:
+        run_wizard()
+
+@db_app.command("create")
+@db_app.command("create-db")
+def create_db_cmd(
+    name: str = typer.Argument(None, help="Database name"),
+    host: str = typer.Option("localhost", "--host", "-h", help="Database host"),
+    port: int = typer.Option(3306, "--port", "-P", help="Database port"),
+    user: str = typer.Option("root", "--user", "-u", help="Admin username"),
+    password: Optional[str] = typer.Option(None, "--password", "-p", help="Admin password"),
+    owner: Optional[str] = typer.Option(None, "--owner", help="MySQL user to grant privileges on"),
+    user_host: str = typer.Option("%", "--user-host", help="MySQL user host (default: %)"),
+    charset: str = typer.Option("utf8mb4", "--charset", help="MySQL charset"),
+    collation: str = typer.Option("utf8mb4_unicode_ci", "--collation", help="MySQL collation")
+):
+    """Create a MySQL database."""
+    if not name:
+        name = typer.prompt("Database name").strip()
+    if not name:
+        logger.error("Database name is required.")
+        raise typer.Exit(code=1)
+    execute_create_db(host, port, user, password, name, owner or "", user_host, charset, collation)
+
+@db_app.command("drop")
+@db_app.command("drop-db")
+def drop_db_cmd(
+    name: str = typer.Argument(None, help="Database name"),
+    host: str = typer.Option("localhost", "--host", "-h", help="Database host"),
+    port: int = typer.Option(3306, "--port", "-P", help="Database port"),
+    user: str = typer.Option("root", "--user", "-u", help="Admin username"),
+    password: Optional[str] = typer.Option(None, "--password", "-p", help="Admin password"),
+    force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation prompt")
+):
+    """Drop a MySQL database."""
+    if not name:
+        name = typer.prompt("Database name").strip()
+    if not name:
+        logger.error("Database name is required.")
+        raise typer.Exit(code=1)
+    confirm_destructive(force, name, f"You are about to DROP database '{name}' permanently.")
+    execute_drop_db(host, port, user, password, name)
+
+@db_app.command("export")
+@db_app.command("export-db")
+@db_app.command("dump")
+def export_db_cmd(
+    name: str = typer.Argument(None, help="Database name"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="Output SQL file path (prints to stdout if omitted)"),
+    host: str = typer.Option("localhost", "--host", "-h", help="Database host"),
+    port: int = typer.Option(3306, "--port", "-P", help="Database port"),
+    user: str = typer.Option("root", "--user", "-u", help="Admin username"),
+    password: Optional[str] = typer.Option(None, "--password", "-p", help="Admin password"),
+    quick: bool = typer.Option(True, "--quick/--no-quick", help="Retrieve rows for a table from the server a row at a time"),
+    single_transaction: bool = typer.Option(True, "--single-transaction/--no-single-transaction", help="Dump transactional tables in consistent state"),
+    routines: bool = typer.Option(True, "--routines/--no-routines", help="Dump stored routines (procedures and functions)"),
+    triggers: bool = typer.Option(True, "--triggers/--no-triggers", help="Dump triggers")
+):
+    """Export/dump a MySQL database using mysqldump."""
+    if not name:
+        name = typer.prompt("Database name").strip()
+    if not name:
+        logger.error("Database name is required.")
+        raise typer.Exit(code=1)
+    execute_export_db(
+        host=host,
+        port=port,
+        user=user,
+        password=password,
+        database=name,
+        output=output,
+        quick=quick,
+        single_transaction=single_transaction,
+        routines=routines,
+        triggers=triggers
+    )
+
+@db_app.command("create-user")
+def create_user_cmd(
+    username: str = typer.Argument(None, help="Username"),
+    new_password: str = typer.Option(None, "--new-password", help="Password for the user"),
+    host: str = typer.Option("localhost", "--host", "-h", help="Database host"),
+    port: int = typer.Option(3306, "--port", "-P", help="Database port"),
+    user: str = typer.Option("root", "--user", "-u", help="Admin username"),
+    password: Optional[str] = typer.Option(None, "--password", "-p", help="Admin password"),
+    grant_db: Optional[str] = typer.Option(None, "--grant-db", help="Database to grant privileges to"),
+    user_host: str = typer.Option("%", "--user-host", help="MySQL user host (default: %)")
+):
+    """Create a database user."""
+    if not username:
+        username = typer.prompt("Username").strip()
+    if not username:
+        logger.error("Username is required.")
+        raise typer.Exit(code=1)
+    if not new_password:
+        new_password = typer.prompt("Password for the user", hide_input=True).strip()
+    if not new_password:
+        logger.error("Password is required.")
+        raise typer.Exit(code=1)
+    db_to_grant = grant_db if grant_db else username
+    execute_create_user(host, port, user, password, username, new_password, db_to_grant, user_host)
+
+@db_app.command("drop-user")
+def drop_user_cmd(
+    username: str = typer.Argument(None, help="Username"),
+    host: str = typer.Option("localhost", "--host", "-h", help="Database host"),
+    port: int = typer.Option(3306, "--port", "-P", help="Database port"),
+    user: str = typer.Option("root", "--user", "-u", help="Admin username"),
+    password: Optional[str] = typer.Option(None, "--password", "-p", help="Admin password"),
+    user_host: str = typer.Option("%", "--user-host", help="MySQL user host (default: %)"),
+    force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation prompt")
+):
+    """Drop a database user."""
+    if not username:
+        username = typer.prompt("Username").strip()
+    if not username:
+        logger.error("Username is required.")
+        raise typer.Exit(code=1)
+    confirm_destructive(force, username, f"You are about to DROP user '{username}' permanently.")
+    execute_drop_user(host, port, user, password, username, user_host)
+

ndev/linux/commands/doctor.py

@@ -0,0 +1,56 @@
+import shutil
+import subprocess
+import typer
+from rich.console import Console
+from rich.table import Table
+from ndev.common.constants import NDEV_DIR, CONFIG_FILE
+from ndev.common.logger import logger
+
+console = Console()
+
+def doctor_cmd():
+    """Run diagnostic checks on the host and sandbox environments."""
+    table = Table(title="ndev Doctor Diagnostic Report")
+    table.add_column("Check", style="bold cyan")
+    table.add_column("Status")
+    table.add_column("Details")
+    
+    bwrap_path = shutil.which("bwrap")
+    if bwrap_path:
+        try:
+            res = subprocess.run(["bwrap", "--version"], capture_output=True, text=True)
+            table.add_row("Bubblewrap (bwrap)", "[green]OK[/green]", f"Found at {bwrap_path} ({res.stdout.strip()})")
+        except Exception as e:
+            table.add_row("Bubblewrap (bwrap)", "[red]FAILED[/red]", f"Found at {bwrap_path} but failed to run: {e}")
+    else:
+        table.add_row("Bubblewrap (bwrap)", "[red]MISSING[/red]", "bubblewrap is required to build PHP in a sandbox.")
+        
+    gcc_path = shutil.which("gcc")
+    if gcc_path:
+        table.add_row("GCC Compiler", "[green]OK[/green]", f"Found at {gcc_path}")
+    else:
+        table.add_row("GCC Compiler", "[red]MISSING[/red]", "gcc is required to compile PHP.")
+        
+    make_path = shutil.which("make")
+    if make_path:
+        table.add_row("Make Utility", "[green]OK[/green]", f"Found at {make_path}")
+    else:
+        table.add_row("Make Utility", "[red]MISSING[/red]", "make is required to build PHP.")
+        
+    pkgconfig_path = shutil.which("pkg-config")
+    if pkgconfig_path:
+        table.add_row("Pkg-Config Utility", "[green]OK[/green]", f"Found at {pkgconfig_path}")
+    else:
+        table.add_row("Pkg-Config Utility", "[red]MISSING[/red]", "pkg-config is required to find libraries during compilation.")
+        
+    if NDEV_DIR.exists():
+        table.add_row("Layout Directory (~/.ndev)", "[green]OK[/green]", f"Exists at {NDEV_DIR}")
+    else:
+        table.add_row("Layout Directory (~/.ndev)", "[yellow]WARNING[/yellow]", "Not initialized yet.")
+        
+    if CONFIG_FILE.exists():
+        table.add_row("Configuration File", "[green]OK[/green]", f"Found at {CONFIG_FILE}")
+    else:
+        table.add_row("Configuration File", "[yellow]WARNING[/yellow]", "Not initialized yet.")
+        
+    console.print(table)

ndev/linux/commands/grok.py

@@ -0,0 +1,75 @@
+import re
+import tempfile
+import subprocess
+import shutil
+import typer
+from pathlib import Path
+from rich.console import Console
+from ndev.common.logger import logger
+
+console = Console()
+
+def get_vhosts() -> list[str]:
+    nginx_dir = Path("/etc/nginx/sites-enabled")
+    domains = []
+    if not nginx_dir.exists():
+        return domains
+        
+    for file in nginx_dir.glob("*.conf"):
+        try:
+            content = file.read_text()
+            for line in content.splitlines():
+                line = line.strip()
+                if line.startswith("server_name"):
+                    parts = line.split()
+                    for p in parts[1:]:
+                        p = p.rstrip(";").strip()
+                        if p and p != "_":
+                            domains.append(p)
+                            break
+        except Exception:
+            pass
+    return domains
+
+def grok_cmd():
+    """Proxy local Nginx vhosts over public internet using Ngrok."""
+    if not shutil.which("ngrok"):
+        logger.error("ngrok is not installed or not in PATH.")
+        raise typer.Exit(code=1)
+        
+    domains = get_vhosts()
+    if not domains:
+        logger.error("No vhosts found in /etc/nginx/sites-enabled.")
+        raise typer.Exit(code=1)
+        
+    console.print("\n[bold]Available VHosts[/bold]")
+    console.print("----------------")
+    for i, d in enumerate(domains):
+        console.print(f" {i + 1}) {d}")
+        
+    console.print("")
+    choice = typer.prompt("Select vhost index", type=int)
+    if choice < 1 or choice > len(domains):
+        logger.error("Invalid selection.")
+        raise typer.Exit(code=1)
+        
+    domain = domains[choice - 1]
+    
+    policy_content = f"""on_http_request:
+  - actions:
+      - type: add-headers
+        config:
+          headers:
+            Host: {domain}
+"""
+    
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as tmp:
+        tmp.write(policy_content)
+        policy_file = tmp.name
+        
+    logger.info(f"Selected domain: {domain}")
+    logger.info("Starting ngrok...")
+    try:
+        subprocess.run(["ngrok", "http", "80", "--traffic-policy-file", policy_file])
+    finally:
+        Path(policy_file).unlink(missing_ok=True)

ndev/linux/commands/install.py

@@ -0,0 +1,39 @@
+import typer
+from ndev.linux.php.installer import install_version
+from ndev.common.logger import logger
+
+from typing import Optional
+
+def install_cmd(
+    version: str = typer.Argument(None, help="PHP version to install (e.g. 8.4, 8.3.12)"),
+    show_logs: Optional[bool] = typer.Option(
+        None,
+        "--show-logs/--no-show-logs",
+        "-s",
+        help="Show verbose compilation and installation logs"
+    )
+):
+    """Compile and install a PHP version from source."""
+    if not version:
+        version = typer.prompt("PHP version to install (e.g. 8.4, 8.3.12)").strip()
+    if not version:
+        logger.error("PHP version is required.")
+        raise typer.Exit(code=1)
+        
+    if show_logs is None:
+        show_logs = typer.confirm("Show verbose compilation and installation logs?", default=False)
+        
+    try:
+        resolved_version = install_version(version, show_logs=show_logs)
+        
+        # Auto-activate the version if no active version is set
+        from ndev.common.constants import CURRENT_LINK
+        if not CURRENT_LINK.exists() and not CURRENT_LINK.is_symlink():
+            logger.info(f"No active PHP version set. Setting PHP {resolved_version} as active...")
+            from ndev.linux.commands.use import use_cmd
+            use_cmd(resolved_version)
+            
+    except Exception as e:
+        logger.error(f"Installation failed: {e}")
+        raise typer.Exit(code=1)
+

ndev/linux/commands/list.py

@@ -0,0 +1,47 @@
+import typer
+from pathlib import Path
+from rich.console import Console
+from rich.table import Table
+from ndev.common.constants import PHP_DIR, CURRENT_LINK
+from ndev.linux.runtime.fpm import get_fpm_status
+from ndev.common.logger import logger
+
+console = Console()
+
+def list_cmd():
+    """List all locally installed PHP versions."""
+    if not PHP_DIR.exists():
+        logger.info("No PHP versions installed yet. Install one with 'ndev install <version>'.")
+        return
+        
+    installed_versions = []
+    for path in PHP_DIR.iterdir():
+        if path.is_dir():
+            installed_versions.append(path.name)
+            
+    if not installed_versions:
+        logger.info("No PHP versions installed yet. Install one with 'ndev install <version>'.")
+        return
+        
+    from packaging.version import parse as parse_version
+    installed_versions = sorted(installed_versions, key=parse_version)
+    
+    active_version = None
+    if CURRENT_LINK.exists() and CURRENT_LINK.is_symlink():
+        active_version = CURRENT_LINK.resolve().name
+        
+    table = Table(title="Installed PHP Versions")
+    table.add_column("Version", style="bold cyan")
+    table.add_column("Status")
+    table.add_column("Active", justify="center")
+    
+    for v in installed_versions:
+        status = get_fpm_status(v)
+        status_text = "[green]Running[/green]" if status["running"] else "Stopped"
+        
+        is_active = v == active_version
+        active_text = "[bold green]* (active)[/bold green]" if is_active else ""
+        
+        table.add_row(v, status_text, active_text)
+        
+    console.print(table)

ndev/linux/commands/logs.py

@@ -0,0 +1,36 @@
+import typer
+from ndev.common.constants import LOGS_DIR, CURRENT_LINK
+from ndev.common.logger import logger
+
+def logs_cmd(
+    version: str = typer.Argument(None, help="PHP version to view logs for (defaults to current active version)"),
+    lines: int = typer.Option(50, "--lines", "-n", help="Number of lines to display")
+):
+    """View PHP-FPM logs for a version."""
+    from ndev.common.utils import get_version_or_prompt
+    if not version:
+        version = get_version_or_prompt(version, "PHP version to view logs")
+        if not version:
+            logger.error("No version specified.")
+            raise typer.Exit(code=1)
+
+            
+    parts = version.split(".")
+    major_minor = f"{parts[0]}{parts[1]}"
+    log_file = LOGS_DIR / f"php-fpm-{major_minor}.log"
+    
+    if not log_file.exists():
+        logger.error(f"No log file found at {log_file} for version {version}.")
+        raise typer.Exit(code=1)
+        
+    try:
+        with open(log_file, "r") as f:
+            content = f.readlines()
+        
+        last_lines = content[-lines:]
+        logger.info(f"Showing last {len(last_lines)} lines of {log_file}:")
+        for line in last_lines:
+            print(line, end="")
+    except Exception as e:
+        logger.error(f"Failed to read log file: {e}")
+        raise typer.Exit(code=1)

ndev/linux/commands/mailpit.py

@@ -0,0 +1,82 @@
+"""
+Mailpit CLI commands for ndev (Linux).
+"""
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from ndev.linux.runtime.mailpit import (
+    DEFAULT_SMTP_PORT,
+    DEFAULT_WEB_PORT,
+    get_mailpit_status,
+    launch_mailpit,
+    restart_mailpit,
+    setup_mailpit,
+    start_mailpit,
+    stop_mailpit,
+)
+
+console = Console()
+mailpit_app = typer.Typer(
+    help="Manage Mailpit local email sandbox & SMTP catcher.",
+    no_args_is_help=True,
+)
+
+
+@mailpit_app.command("install")
+def mailpit_install():
+    """Download and install the prebuilt Mailpit Linux binary."""
+    setup_mailpit()
+
+
+@mailpit_app.command("start")
+def mailpit_start(
+    smtp_port: int = typer.Option(DEFAULT_SMTP_PORT, "--smtp-port", help="SMTP listening port"),
+    web_port: int = typer.Option(DEFAULT_WEB_PORT, "--web-port", help="Web UI listening port"),
+):
+    """Start Mailpit background service."""
+    start_mailpit(smtp_port=smtp_port, web_port=web_port)
+
+
+@mailpit_app.command("stop")
+def mailpit_stop():
+    """Stop Mailpit background service."""
+    stop_mailpit()
+
+
+@mailpit_app.command("restart")
+def mailpit_restart(
+    smtp_port: int = typer.Option(DEFAULT_SMTP_PORT, "--smtp-port", help="SMTP listening port"),
+    web_port: int = typer.Option(DEFAULT_WEB_PORT, "--web-port", help="Web UI listening port"),
+):
+    """Restart Mailpit background service."""
+    restart_mailpit(smtp_port=smtp_port, web_port=web_port)
+
+
+@mailpit_app.command("status")
+def mailpit_status():
+    """Show status of Mailpit service."""
+    st = get_mailpit_status()
+    table = Table(title="Mailpit Service Status")
+    table.add_column("Property", style="bold cyan")
+    table.add_column("Value")
+
+    status_text = "[bold green]Running[/bold green]" if st["running"] else "[bold red]Stopped[/bold red]"
+    table.add_row("Service", "Mailpit")
+    table.add_row("Status", status_text)
+    table.add_row("PID", str(st["pid"]) if st["pid"] else "N/A")
+    table.add_row("SMTP Server", f"127.0.0.1:{st['smtp_port']}")
+    table.add_row("Web UI URL", st["url"] if st["url"] else f"http://127.0.0.1:{st['web_port']} (Stopped)")
+    console.print(table)
+
+
+@mailpit_app.command("launch")
+def mailpit_launch_cmd():
+    """Open Mailpit web UI in default browser (starts service if stopped)."""
+    launch_mailpit()
+
+
+@mailpit_app.command("open", hidden=True)
+def mailpit_open_alias():
+    """Alias for launch."""
+    launch_mailpit()