Removed dirty OS check. And support Legacy WSL2 distributions (#15)

* Removed dirty OS check. And support Legacy WSL2 distributions

* finishing v0.5.0

Author: LeeShan87

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2025-12-01
+
 ### Fixed
 - Distribution names now persist across Vagrant commands (fixes #8)
 - `vagrant ssh` and other commands now remember auto-generated distribution names
@@ -23,6 +25,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Silent distribution startup for SSH commands to prevent output pollution
 - `EnsureRunning` action for transparent VM wake-up on SSH access
+- Export existing WSL2 distributions to cache for modern distributions (supporting `--name` flag)
+- Removed dirty OS check before vagrant up
+- Automatic handling for legacy distributions (Ubuntu 20.04/22.04, OracleLinux, etc.) via install -> terminate -> export flow
+- Future-proof blocklist approach: only 7 legacy distributions listed, new distributions automatically get modern treatment
+- User's original distributions are preserved (not unregistered) when exporting to cache
 
 ## [0.4.0] - 2025-11-24
 
@@ -216,7 +223,8 @@ end
 - Some SUSE Enterprise distributions have guest detection issues
 - AlmaLinux-10 and archlinux have provisioning limitations
 
-[unreleased]: https://github.com/LeeShan87/vagrant-wsl2-provider/compare/v0.4.0...HEAD
+[unreleased]: https://github.com/LeeShan87/vagrant-wsl2-provider/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/LeeShan87/vagrant-wsl2-provider/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/LeeShan87/vagrant-wsl2-provider/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/LeeShan87/vagrant-wsl2-provider/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/LeeShan87/vagrant-wsl2-provider/compare/v0.1.0...v0.2.0

Rakefile

@@ -92,4 +92,14 @@ end
 desc "Run all distributions compatibility test - full (Pester, all distros)"
 task :test_all_distributions_full => :ensure_pester do
   sh "powershell -File test/integration/Invoke-PesterTests.ps1 -TestFile AllDistributions -Full"
-end
+end
+
+desc "Run export existing distribution integration test"
+task :test_export_existing => :ensure_pester do
+  sh "powershell -File test/integration/Invoke-PesterTests.ps1 -TestFile ExportExisting"
+end
+
+desc "Run legacy distribution integration test (slow - only with -Full)"
+task :test_legacy_distro_full => :ensure_pester do
+  sh "powershell -File test/integration/Invoke-PesterTests.ps1 -TestFile LegacyDistro -Full"
+end

docs/custom-base-images.md

@@ -0,0 +1,245 @@
+# Custom Base Images
+
+This guide explains how to create custom base images for the Vagrant WSL2 provider.
+
+## Overview
+
+The Vagrant WSL2 provider uses a caching system to speed up VM creation. When you first run `vagrant up`, the provider:
+
+1. Downloads/installs a clean WSL2 distribution (e.g., Ubuntu-24.04)
+2. Exports it to a cache directory: `~/.vagrant.d/wsl2-cache/`
+3. Creates project-specific VMs from this cached image
+
+This ensures every `vagrant up` starts with a clean, reproducible environment.
+
+## Why Create Custom Base Images?
+
+You might want to create a custom base image if you:
+
+- Need pre-installed packages in all your VMs (e.g., Docker, specific tools)
+- Want to apply custom configurations before VM creation
+- Need a specific distribution version not available via `wsl --install`
+- Want to optimize VM startup time by pre-installing common dependencies
+
+## Creating a Custom Base Image
+
+### Method 1: Manual Creation (Recommended)
+
+**Step 1: Create and customize a WSL distribution**
+
+```powershell
+# Install a fresh distribution
+wsl --install Ubuntu-24.04 --no-launch
+
+# Launch it and install your custom packages
+wsl -d Ubuntu-24.04
+
+# Inside the distribution:
+sudo apt update
+sudo apt install -y build-essential git curl
+# ... install whatever you need ...
+
+# Exit the distribution
+exit
+```
+
+**Step 2: Export to cache directory**
+
+```powershell
+# Create cache directory if it doesn't exist
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.vagrant.d\wsl2-cache"
+
+# Export your customized distribution
+wsl --export Ubuntu-24.04 "$env:USERPROFILE\.vagrant.d\wsl2-cache\Ubuntu-24.04-vagrant-base.tar"
+```
+
+**Step 3: Clean up the original (optional)**
+
+```powershell
+# Remove the original distribution to save space
+wsl --unregister Ubuntu-24.04
+```
+
+**Step 4: Use in Vagrantfile**
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.box = "Ubuntu-24.04"
+
+  config.vm.provider "wsl2" do |wsl|
+    # Vagrant will use your custom cached image!
+  end
+end
+```
+
+### Method 2: Using an Existing Distribution
+
+If you already have a WSL distribution that you've customized and want to use as a base:
+
+```powershell
+# Export your existing distribution to the cache
+wsl --export MyCustomDistro "$env:USERPROFILE\.vagrant.d\wsl2-cache\MyCustomDistro-vagrant-base.tar"
+```
+
+Then in your Vagrantfile:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.box = "MyCustomDistro"
+
+  config.vm.provider "wsl2" do |wsl|
+    # Will use your custom cached image
+  end
+end
+```
+
+## Important Considerations
+
+### Cache Naming Convention
+
+The cache file **must** follow this naming pattern:
+
+```
+<distribution-name>-vagrant-base.tar
+```
+
+For example:
+- `Ubuntu-24.04-vagrant-base.tar` for box name `Ubuntu-24.04`
+- `Debian-vagrant-base.tar` for box name `Debian`
+- `MyCustomDistro-vagrant-base.tar` for box name `MyCustomDistro`
+
+### Keeping Images Clean
+
+**Best Practice**: Don't include user-specific data or temporary files in your base image.
+
+**What to avoid**:
+- User home directory modifications
+- Running services or daemons
+- Temporary files in `/tmp`
+- User-specific SSH keys or credentials
+- Project-specific code or data
+
+**What's okay**:
+- System-wide package installations
+- System configuration files
+- Pre-compiled tools or binaries
+- System-wide environment variables
+
+### Automatic Backup for Legacy Distributions
+
+If you have a legacy distribution (e.g., Ubuntu-20.04) already installed locally, the provider will automatically:
+
+1. Backup your existing distribution
+2. Install a fresh clean version
+3. Export it to cache
+4. Restore your original distribution
+
+This ensures you don't lose your existing work while still getting a clean cache.
+
+## Cache Location
+
+All cached base images are stored in:
+
+```
+Windows: C:\Users\<username>\.vagrant.d\wsl2-cache\
+```
+
+You can manually manage these files:
+
+```powershell
+# List cached images
+Get-ChildItem "$env:USERPROFILE\.vagrant.d\wsl2-cache"
+
+# Remove a specific cache
+Remove-Item "$env:USERPROFILE\.vagrant.d\wsl2-cache\Ubuntu-24.04-vagrant-base.tar"
+
+# Remove all caches
+Remove-Item "$env:USERPROFILE\.vagrant.d\wsl2-cache\*"
+```
+
+## Updating Cache
+
+To update a cached image with new packages or configurations:
+
+1. Delete the existing cache file
+2. Run `vagrant up` - the provider will recreate it
+
+OR manually:
+
+```powershell
+# Delete old cache
+Remove-Item "$env:USERPROFILE\.vagrant.d\wsl2-cache\Ubuntu-24.04-vagrant-base.tar"
+
+# Create new custom image using Method 1 above
+# ...
+```
+
+## Examples
+
+### Example 1: Docker Pre-installed
+
+```powershell
+# Install Ubuntu
+wsl --install Ubuntu-24.04 --no-launch
+wsl -d Ubuntu-24.04
+
+# Inside Ubuntu, install Docker
+curl -fsSL https://get.docker.com -o get-docker.sh
+sudo sh get-docker.sh
+exit
+
+# Export to cache
+wsl --export Ubuntu-24.04 "$env:USERPROFILE\.vagrant.d\wsl2-cache\Ubuntu-24.04-vagrant-base.tar"
+
+# Clean up
+wsl --unregister Ubuntu-24.04
+```
+
+### Example 2: Development Tools Pre-installed
+
+```powershell
+wsl --install Debian --no-launch
+wsl -d Debian
+
+# Install development tools
+sudo apt update
+sudo apt install -y build-essential cmake ninja-build git
+exit
+
+# Export to cache
+wsl --export Debian "$env:USERPROFILE\.vagrant.d\wsl2-cache\Debian-vagrant-base.tar"
+wsl --unregister Debian
+```
+
+## Troubleshooting
+
+### Cache Not Being Used
+
+If Vagrant isn't using your custom cache:
+
+1. **Check the filename**: Must be `<box-name>-vagrant-base.tar`
+2. **Check the location**: Must be in `~/.vagrant.d/wsl2-cache/`
+3. **Check the box name**: In Vagrantfile, `config.vm.box` must match the cache filename
+
+### Large Cache Files
+
+If your cache files are very large:
+
+- Avoid including package caches: `sudo apt clean`
+- Remove temporary files before export
+- Consider using VHDX compression (future feature)
+
+### Permission Issues
+
+If you get permission errors when exporting:
+
+```powershell
+# Run PowerShell as Administrator
+wsl --export DistroName "path\to\cache.tar"
+```
+
+## See Also
+
+- [WSL2 Command Cheat Sheet](wsl2-command-cheat-sheet.md)
+- [Vagrant Documentation](https://www.vagrantup.com/docs)
+- [WSL Documentation](https://learn.microsoft.com/en-us/windows/wsl/)

examples/export-existing/Vagrantfile

@@ -0,0 +1,22 @@
+# Export Existing Distribution Example
+#
+# This example demonstrates exporting an existing WSL2 distribution to cache
+# when it supports the --name flag
+#
+# Prerequisites:
+#   - Ubuntu-24.04 must be installed locally: wsl --install Ubuntu-24.04
+#
+# What happens:
+#   1. Vagrant detects Ubuntu-24.04 is installed locally
+#   2. Vagrant checks that Ubuntu-24.04 supports --name flag
+#   3. Vagrant exports Ubuntu-24.04 to cache
+#   4. Vagrant creates a new VM from the cached tar
+#   5. Original Ubuntu-24.04 installation remains untouched
+
+Vagrant.configure("2") do |config|
+  config.vm.box = "Ubuntu-24.04"
+
+  config.vm.provider "wsl2" do |wsl|
+    # Provider will automatically export existing Ubuntu-24.04 to cache
+  end
+end

examples/legacy-distro/Vagrantfile

@@ -0,0 +1,20 @@
+# Legacy Distribution Example
+#
+# This example demonstrates installing legacy WSL2 distributions
+# that don't support the --no-launch flag (Ubuntu-20.04, Ubuntu-22.04, OracleLinux, etc.)
+#
+# What happens:
+#   1. Vagrant installs the distribution interactively (launches automatically)
+#   2. Vagrant terminates it before user setup completes
+#   3. Vagrant exports it to cache
+#   4. Vagrant unregisters the base distribution
+#   5. Vagrant creates project VM from cached tar
+
+Vagrant.configure("2") do |config|
+  # Use a legacy distribution that doesn't support --no-launch
+  config.vm.box = "Ubuntu-20.04"
+
+  config.vm.provider "wsl2" do |wsl|
+    # Legacy distributions are automatically detected and handled differently
+  end
+end