linwin 0.4.0__tar.gz

linwin-0.4.0/.gitignore

@@ -0,0 +1,13 @@
+.idea/
+*.tar
+*.vhdx
+__pycache__/
+*.pyc
+.claude/settings.local.json
+.coverage
+
+# pyship build artifacts
+app/
+dist/
+*.nsi
+*.exe

linwin-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Abel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

linwin-0.4.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: linwin
+Version: 0.4.0
+Summary: Setup WSL2 and make it easily accessible from Windows desktop
+Project-URL: Homepage, https://github.com/jamesabel/linwin
+Project-URL: Repository, https://github.com/jamesabel/linwin
+Project-URL: Issues, https://github.com/jamesabel/linwin/issues
+Author: James Abel
+License: MIT
+License-File: LICENSE
+Keywords: TUI,Ubuntu,WSL,WSL2,WSLg,Windows,setup,xrdp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Installation/Setup
+Classifier: Topic :: System :: Operating System
+Requires-Python: >=3.11
+Requires-Dist: pref>=0.3.1
+Requires-Dist: textual>=0.79.0
+Description-Content-Type: text/markdown
+
+# linwin
+
+Automated TUI (Text User Interface) to install Ubuntu on Windows 11 via WSL2, with the distro stored on a dedicated SSD drive. Includes WSLg for seamless Linux GUI apps on Windows and xrdp for full XFCE4 desktop access via Remote Desktop.
+
+## Prerequisites
+
+- **Windows 11** (or Windows 10 build 19044+)
+- **Hardware virtualization** enabled in BIOS/UEFI (Intel VT-x or AMD-V)
+- **Administrator access** on Windows
+
+## Quick Start
+
+```powershell
+scripts\setup_wsl.bat
+```
+
+This launches an interactive terminal UI that:
+
+- Auto-detects system hardware (RAM, CPUs, drives) and proposes an optimized configuration
+- Scans drives and recommends the best one for WSL storage (NVMe > SSD > HDD)
+- Runs startup verification and shows any issues before setup begins
+- Lets you review and adjust all settings (distro, resources, packages)
+- Enables WSL and Virtual Machine Platform features
+- Installs Ubuntu, exports/imports to your chosen drive
+- Writes `.wslconfig` with your resource limits
+- Runs Linux-side setup (systemd, apt packages, snap packages, xrdp)
+- Configures xrdp with XFCE4 desktop for Remote Desktop access
+- Maintains a WSL keepalive process to prevent VM shutdown between sessions
+- Verifies everything with a PASS/FAIL dashboard
+
+The TUI handles admin elevation, the reboot boundary, and cross-WSL Linux setup automatically. After setup, a launcher screen lets you open apps, launch a terminal, or connect via Remote Desktop.
+
+For quick reruns without dependency installation:
+
+```powershell
+run.bat
+```
+
+### Linux TUI
+
+A standalone Linux TUI is also available for running inside WSL Ubuntu directly:
+
+```bash
+pip3 install textual
+python3 -m linwin.linux
+```
+
+A headless mode is available for non-interactive automation:
+
+```bash
+python3 -m linwin.linux --headless --step enable-systemd
+python3 -m linwin.linux --headless --step install-packages
+```
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| 1-9 | Select numbered actions on any screen |
+| Escape | Quit app / Cancel current screen |
+| Ctrl+Q | Quit app |
+| Click | Select action links and options |
+
+## Configuration
+
+Edit `config.json` before running, or use the built-in Configure Settings screen. On first launch, the TUI auto-detects your system profile and proposes sensible defaults:
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `distroName` | `Ubuntu-22.04` | Distro to install via `wsl --install` |
+| `distroImportName` | `Ubuntu` | Name after export/import |
+| `wslInstallPath` | auto-detected | Where to store the distro VHD |
+| `wslDriveLetter` | auto-detected | Best available drive (NVMe > SSD > HDD) |
+| `wslconfig.memory` | RAM ÷ 4 | RAM limit for WSL2 (min 4 GB) |
+| `wslconfig.processors` | CPUs ÷ 2 | CPU cores for WSL2 (min 1) |
+| `wslconfig.swap` | RAM ÷ 8 | Swap size (min 4 GB) |
+| `wslconfig.defaultVhdSize` | `512GB` | Max VHD size |
+| `snaps` | *(empty)* | Snap packages to install (configure via editor) |
+| `aptPackages` | nautilus, x11-apps, xfce4, xfce4-terminal, xrdp, dbus-x11 | Apt packages to install |
+| `xrdpPort` | `3390` | Port for xrdp (avoids conflict with Windows RDP on 3389) |
+
+## Project Structure
+
+| Path | Description |
+|------|-------------|
+| `run.bat` | Quick launch -- runs the TUI without dependency installation |
+| `scripts/setup_wsl.bat` | Full setup -- installs uv, Python, dependencies, then launches the TUI |
+| `scripts/test.bat` | Run the test suite |
+| `linwin/windows/` | Windows TUI package -- startup verification, auto-config, setup with live progress |
+| `linwin/linux/` | Linux TUI package for WSL-side setup (also supports `--headless`) |
+| `linwin/shared/` | Shared widgets, config, theme, and subprocess utilities |
+| `tests/` | pytest test suite (106 tests) |
+| `config.json` | Default configuration |
+
+## Setup Phases
+
+**Startup:** Auto-detects system hardware, runs verification checks, and presents a setup proposal with recommended configuration for user approval.
+
+**Phase 1 (Windows):** Validates prerequisites, enables WSL and Virtual Machine Platform features, prompts for reboot if needed.
+
+**Phase 2 (Windows + Linux):** Updates WSL, installs Ubuntu, exports/imports distro to target drive, writes `.wslconfig`, enables systemd, installs apt and snap packages, configures xrdp with XFCE4 desktop.
+
+**Verification:** Checks all Windows features, distro registration, WSL version, systemd, packages, WSLg display, xrdp service, and drive mounts.
+
+## Detailed Guide
+
+See [wsl_ubuntu_gnome.md](wsl_ubuntu_gnome.md) for the full manual guide with GUI comparison (WSLg vs. external X servers), troubleshooting, security notes, and decision checklist.
+
+## Launching Apps
+
+After setup, use the launcher screen to open apps directly, or connect via Remote Desktop:
+
+```powershell
+mstsc /v:127.0.0.1:3390
+```
+
+Individual apps can also be launched from an Ubuntu terminal:
+
+```bash
+nautilus &                   # File Manager
+```
+
+Apps appear as native Windows windows via WSLg. A background keepalive process ensures the WSL VM stays running between app launches.

linwin-0.4.0/README.md

@@ -0,0 +1,123 @@
+# linwin
+
+Automated TUI (Text User Interface) to install Ubuntu on Windows 11 via WSL2, with the distro stored on a dedicated SSD drive. Includes WSLg for seamless Linux GUI apps on Windows and xrdp for full XFCE4 desktop access via Remote Desktop.
+
+## Prerequisites
+
+- **Windows 11** (or Windows 10 build 19044+)
+- **Hardware virtualization** enabled in BIOS/UEFI (Intel VT-x or AMD-V)
+- **Administrator access** on Windows
+
+## Quick Start
+
+```powershell
+scripts\setup_wsl.bat
+```
+
+This launches an interactive terminal UI that:
+
+- Auto-detects system hardware (RAM, CPUs, drives) and proposes an optimized configuration
+- Scans drives and recommends the best one for WSL storage (NVMe > SSD > HDD)
+- Runs startup verification and shows any issues before setup begins
+- Lets you review and adjust all settings (distro, resources, packages)
+- Enables WSL and Virtual Machine Platform features
+- Installs Ubuntu, exports/imports to your chosen drive
+- Writes `.wslconfig` with your resource limits
+- Runs Linux-side setup (systemd, apt packages, snap packages, xrdp)
+- Configures xrdp with XFCE4 desktop for Remote Desktop access
+- Maintains a WSL keepalive process to prevent VM shutdown between sessions
+- Verifies everything with a PASS/FAIL dashboard
+
+The TUI handles admin elevation, the reboot boundary, and cross-WSL Linux setup automatically. After setup, a launcher screen lets you open apps, launch a terminal, or connect via Remote Desktop.
+
+For quick reruns without dependency installation:
+
+```powershell
+run.bat
+```
+
+### Linux TUI
+
+A standalone Linux TUI is also available for running inside WSL Ubuntu directly:
+
+```bash
+pip3 install textual
+python3 -m linwin.linux
+```
+
+A headless mode is available for non-interactive automation:
+
+```bash
+python3 -m linwin.linux --headless --step enable-systemd
+python3 -m linwin.linux --headless --step install-packages
+```
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| 1-9 | Select numbered actions on any screen |
+| Escape | Quit app / Cancel current screen |
+| Ctrl+Q | Quit app |
+| Click | Select action links and options |
+
+## Configuration
+
+Edit `config.json` before running, or use the built-in Configure Settings screen. On first launch, the TUI auto-detects your system profile and proposes sensible defaults:
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `distroName` | `Ubuntu-22.04` | Distro to install via `wsl --install` |
+| `distroImportName` | `Ubuntu` | Name after export/import |
+| `wslInstallPath` | auto-detected | Where to store the distro VHD |
+| `wslDriveLetter` | auto-detected | Best available drive (NVMe > SSD > HDD) |
+| `wslconfig.memory` | RAM ÷ 4 | RAM limit for WSL2 (min 4 GB) |
+| `wslconfig.processors` | CPUs ÷ 2 | CPU cores for WSL2 (min 1) |
+| `wslconfig.swap` | RAM ÷ 8 | Swap size (min 4 GB) |
+| `wslconfig.defaultVhdSize` | `512GB` | Max VHD size |
+| `snaps` | *(empty)* | Snap packages to install (configure via editor) |
+| `aptPackages` | nautilus, x11-apps, xfce4, xfce4-terminal, xrdp, dbus-x11 | Apt packages to install |
+| `xrdpPort` | `3390` | Port for xrdp (avoids conflict with Windows RDP on 3389) |
+
+## Project Structure
+
+| Path | Description |
+|------|-------------|
+| `run.bat` | Quick launch -- runs the TUI without dependency installation |
+| `scripts/setup_wsl.bat` | Full setup -- installs uv, Python, dependencies, then launches the TUI |
+| `scripts/test.bat` | Run the test suite |
+| `linwin/windows/` | Windows TUI package -- startup verification, auto-config, setup with live progress |
+| `linwin/linux/` | Linux TUI package for WSL-side setup (also supports `--headless`) |
+| `linwin/shared/` | Shared widgets, config, theme, and subprocess utilities |
+| `tests/` | pytest test suite (106 tests) |
+| `config.json` | Default configuration |
+
+## Setup Phases
+
+**Startup:** Auto-detects system hardware, runs verification checks, and presents a setup proposal with recommended configuration for user approval.
+
+**Phase 1 (Windows):** Validates prerequisites, enables WSL and Virtual Machine Platform features, prompts for reboot if needed.
+
+**Phase 2 (Windows + Linux):** Updates WSL, installs Ubuntu, exports/imports distro to target drive, writes `.wslconfig`, enables systemd, installs apt and snap packages, configures xrdp with XFCE4 desktop.
+
+**Verification:** Checks all Windows features, distro registration, WSL version, systemd, packages, WSLg display, xrdp service, and drive mounts.
+
+## Detailed Guide
+
+See [wsl_ubuntu_gnome.md](wsl_ubuntu_gnome.md) for the full manual guide with GUI comparison (WSLg vs. external X servers), troubleshooting, security notes, and decision checklist.
+
+## Launching Apps
+
+After setup, use the launcher screen to open apps directly, or connect via Remote Desktop:
+
+```powershell
+mstsc /v:127.0.0.1:3390
+```
+
+Individual apps can also be launched from an Ubuntu terminal:
+
+```bash
+nautilus &                   # File Manager
+```
+
+Apps appear as native Windows windows via WSLg. A background keepalive process ensures the WSL VM stays running between app launches.

linwin-0.4.0/config.json

@@ -0,0 +1,50 @@
+{
+    "distroName": "Ubuntu-22.04",
+    "distroImportName": "Ubuntu",
+    "wslInstallPath": "V:\\WSL\\Ubuntu",
+    "wslDriveLetter": "V",
+    "wslconfig": {
+        "memory": "15GB",
+        "processors": 10,
+        "swap": "7GB",
+        "swapFile": "V:\\WSL\\swap.vhdx",
+        "guiApplications": true,
+        "defaultVhdSize": "512GB"
+    },
+    "snaps": [
+        {
+            "name": "pycharm-community",
+            "classic": true
+        },
+        {
+            "name": "firefox",
+            "classic": false
+        }
+    ],
+    "optionalApps": [
+        {
+            "id": "pycharm-community",
+            "display_name": "PyCharm Community",
+            "command": "pycharm-community",
+            "install_method": "snap",
+            "classic": true
+        },
+        {
+            "id": "firefox",
+            "display_name": "Firefox",
+            "command": "firefox",
+            "install_method": "snap",
+            "classic": false
+        }
+    ],
+    "aptPackages": [
+        "nautilus",
+        "x11-apps",
+        "xfce4",
+        "xfce4-terminal",
+        "xrdp",
+        "dbus-x11"
+    ],
+    "enableSystemd": true,
+    "xrdpPort": 3390
+}

linwin-0.4.0/linwin/__init__.py

@@ -0,0 +1 @@
+"""linwin — TUI setup tool for WSL2 Ubuntu with WSLg GUI and xrdp desktop."""

linwin-0.4.0/linwin/__main__.py

@@ -0,0 +1,19 @@
+"""Entry point for ``python -m linwin``.
+
+Delegates to the Windows or Linux TUI based on the current platform.
+"""
+
+import sys
+
+
+def main() -> None:
+    if sys.platform == "win32":
+        from linwin.windows.__main__ import main as win_main
+        win_main()
+    else:
+        from linwin.linux.__main__ import main as linux_main
+        linux_main()
+
+
+if __name__ == "__main__":
+    main()

linwin-0.4.0/linwin/linux/__main__.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""Linux-side TUI entry point for WSL Ubuntu setup.
+
+Usage:
+    python3 -m linwin.linux                                       # Interactive TUI
+    python3 -m linwin.linux --headless --step enable-systemd      # Headless: enable systemd
+    python3 -m linwin.linux --headless --step install-packages    # Headless: install packages
+"""
+
+import argparse
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+from ..shared.headless_protocol import emit_error, emit_log, emit_task
+from ..shared.setup_logging import setup_logging
+
+
+def find_config() -> dict:
+    """Load config from the pref DB, or return defaults if unavailable.
+
+    Inside WSL the ``pref`` package may not be installed, so fall back
+    to defaults.
+    """
+    try:
+        from ..shared.config import load_config
+        return load_config().to_dict()
+    except ImportError:
+        # pref not installed (running inside WSL) — use defaults.
+        from ..shared.config import SetupConfig
+        return SetupConfig().to_dict()
+
+
+def _run_task(task_id: str, coro, success_msg: str = "") -> bool:
+    """Run an async task with structured headless output. Returns True on success."""
+    emit_task(task_id, "running")
+    result = asyncio.run(coro)
+    if hasattr(result, "ok"):
+        if getattr(result, "skipped", False):
+            emit_task(task_id, "done")
+            emit_log(result.message)
+        elif result.ok:
+            emit_task(task_id, "done")
+            emit_log(success_msg or result.message)
+        else:
+            emit_task(task_id, "failed")
+            emit_error(result.message)
+            return False
+    else:
+        # Boolean or other non-TaskResult return value
+        emit_task(task_id, "done")
+    return True
+
+
+def headless_enable_systemd(config: dict) -> int:
+    """Enable systemd in wsl.conf. Delegates to the async implementation in tasks.systemd."""
+    from .tasks.systemd import enable_systemd
+
+    if not _run_task("enable_systemd", enable_systemd()):
+        return 1
+    return 0
+
+
+def headless_install_packages(config: dict) -> int:
+    """Install apt packages, snaps, verify WSLg. Delegates to async task modules."""
+    from .tasks import apt, snaps, wslg
+    from ..shared.config import SnapPackage
+
+    exit_code = 0
+
+    # apt update & upgrade
+    if not _run_task("apt_update", apt.apt_update()):
+        exit_code = 1
+    if not _run_task("apt_upgrade", apt.apt_upgrade()):
+        exit_code = 1
+
+    # apt packages
+    for pkg in config.get("aptPackages", []):
+        if not _run_task(f"apt_{pkg}", apt.install_apt_package(pkg)):
+            exit_code = 1
+
+    # Setup snapd
+    emit_task("setup_snapd", "running")
+    systemd_ok = asyncio.run(snaps.check_systemd_running())
+    if not systemd_ok:
+        emit_task("setup_snapd", "failed")
+        emit_error("systemd not running. Snaps require systemd + WSL restart.")
+        exit_code = 1
+    else:
+        result = asyncio.run(snaps.ensure_snapd())
+        if result.ok:
+            emit_task("setup_snapd", "done")
+            emit_log(result.message)
+        else:
+            emit_task("setup_snapd", "failed")
+            emit_error(result.message)
+            exit_code = 1
+
+        # Install optional apps (snap and apt; custom skipped)
+        for app_info in config.get("optionalApps", config.get("snaps", [])):
+            method = app_info.get("install_method", "snap")
+            app_id = app_info.get("id", app_info.get("name", ""))
+            if method == "snap":
+                snap = SnapPackage(
+                    name=app_id,
+                    classic=app_info.get("classic", True),
+                )
+                if not _run_task(f"snap_{snap.name}", snaps.install_snap(snap)):
+                    exit_code = 1
+            elif method == "apt":
+                if not _run_task(f"apt_opt_{app_id}", apt.install_apt_package(app_id)):
+                    exit_code = 1
+
+    # Verify WSLg
+    emit_task("verify_wslg", "running")
+    wslg_result = asyncio.run(wslg.verify_wslg())
+    emit_log(f"DISPLAY={wslg_result.display_value or '(not set)'}")
+    emit_log(f"/mnt/wslg: {'exists' if wslg_result.wslg_dir_exists else 'not found'}")
+    wslg_ok = wslg_result.display_set and wslg_result.wslg_dir_exists
+    emit_task("verify_wslg", "done" if wslg_ok else "failed")
+
+    return exit_code
+
+
+def headless_configure_xrdp(config: dict) -> int:
+    """Install xrdp + xfce4, configure port/session, enable service.
+
+    Delegates to async task functions in tasks.xrdp. The enable_xrdp_service
+    call internally handles SSL permissions, systemd overrides, colord polkit,
+    logind delay, user linger, and GDM masking.
+    """
+    from .tasks import xrdp
+
+    exit_code = 0
+    port = config.get("xrdpPort", 3390)
+
+    if not _run_task("xrdp_install", xrdp.install_xrdp()):
+        exit_code = 1
+    if not _run_task("xrdp_port", xrdp.configure_xrdp_port(port)):
+        exit_code = 1
+    if not _run_task("xrdp_session", xrdp.configure_xrdp_session()):
+        exit_code = 1
+    if not _run_task("xrdp_service", xrdp.enable_xrdp_service()):
+        exit_code = 1
+
+    return exit_code
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="WSL Ubuntu Setup TUI (Linux)")
+    parser.add_argument("--headless", action="store_true", help="Run without TUI (structured output)")
+    parser.add_argument("--step", choices=["enable-systemd", "install-packages", "configure-xrdp"],
+                        help="Step to run (headless mode)")
+    args = parser.parse_args()
+
+    log = setup_logging()
+
+    config_data = find_config()
+
+    if args.headless:
+        log.info("Headless mode, step=%s", args.step)
+        try:
+            if args.step == "enable-systemd":
+                sys.exit(headless_enable_systemd(config_data))
+            elif args.step == "install-packages":
+                sys.exit(headless_install_packages(config_data))
+            elif args.step == "configure-xrdp":
+                sys.exit(headless_configure_xrdp(config_data))
+            else:
+                print("ERROR:--step required with --headless", flush=True)
+                sys.exit(1)
+        except SystemExit:
+            sys.stdout.flush()
+            raise
+        except Exception:
+            import traceback
+            tb = traceback.format_exc()
+            emit_error(tb)
+            log.error("Unhandled exception in headless mode:\n%s", tb)
+            sys.exit(1)
+    else:
+        # Interactive TUI mode
+        from ..shared.config import SetupConfig
+        from .app import LinuxSetupApp
+
+        log.info("Linux interactive TUI starting")
+        config = SetupConfig.from_dict(config_data)
+        app = LinuxSetupApp(config)
+        app.run()
+        log.info("Linux TUI exited")
+
+
+if __name__ == "__main__":
+    main()

linwin-0.4.0/linwin/linux/app.py

@@ -0,0 +1,15 @@
+"""Linux TUI Application — main Textual app for WSL Ubuntu setup."""
+
+from __future__ import annotations
+
+from ..shared.base_app import BaseSetupApp
+from .screens.welcome import WelcomeScreen
+
+
+class LinuxSetupApp(BaseSetupApp):
+    """Textual TUI for Ubuntu package setup inside WSL."""
+
+    TITLE = "WSL Ubuntu Setup (Linux)"
+
+    def on_mount(self) -> None:
+        self.push_screen(WelcomeScreen(self._config))