When a project directory is moved or deleted, its corresponding wp-env cache directory (under $WP_ENV_HOME, defaulting to ~/.wp-env) is left behind with no built-in way to detect or clean it up. The same goes for the Docker containers and their images.

To make matters worse, there is no metadata connecting an environment's cache directory to its project directory (e.g. connecting ~/.wp-env/0123456789abcdef to ~/Repos/gutenberg) nor to the Docker artefacts.

N.B.: there is a connection in the opposite direction, but it's specific to the Docker runtime, so we still need a proper solution in wp-env itself. For the record, I'm referring to:

$ docker compose ls -a
NAME           STATUS              CONFIG FILES
00cabcdef...   exited(4)           /../.wp-env/00cabcdef.../docker-compose.yml
00c123456...   exited(4)           /../.wp-env/00c123456.../docker-compose.yml

Proposal

1. Start tracking the aforementioned metadata in each environment's wp-env-cache.json, which currently looks like:

{
  "latestWordPressVersion":"6.9.4",
  "config_checksum":"0123456789abcdef",
  "runtime":"docker"
}

… and could grow to accommodate:

{
  "configPath": "/.../.../Repos/gutenberg",
  "runtimeOptions": {
     "dockerImageNamespace": "0123456789abcdef"
  }
}

This tracking should work retroactively, i.e. existing environments should see their wp-env-cache.json automatically updated to include the new metadata.

2. Add a wp-env prune command that:

   • Scans all subdirectories in the cache directory.
   • Identifies entries whose original config path and/or runtime-specific resources no longer exist. In the case of the Docker runtime, this means compose projects, images, containers, and possibly networks and volumes.
   • Tears down all associated resources.
   • Removes the orphaned cache directories.
   • Reports what was removed.

The command should require confirmation (with a --force flag to skip it), consistent with the existing destroy and cleanup commands.