feat: implement devcontainer stop and down commands

[monotykamary]

Description

This PR implements the devcontainer stop and devcontainer down commands as requested in #386.

Changes

• Added devcontainer stop command to stop running dev containers without removing them
• Added devcontainer down command to stop and remove dev containers
• Both commands support:
  • --workspace-folder to target containers in a specific workspace
  • --all flag to target all dev containers
  • --id-label for filtering by custom labels
  • --remove-volumes flag (down command only) to also remove associated volumes
• Updated README.md to mark both commands as implemented
• Handles both single container and Docker Compose configurations

Testing

Tested locally with the devcontainer-cli project itself:

Starting a dev container:

$ node devcontainer.js up --workspace-folder .
[2 ms] @devcontainers/cli 0.78.0. Node.js v23.11.0. darwin 24.5.0 arm64.
[56101 ms] Resolving Feature dependencies for 'ghcr.io/devcontainers/features/docker-in-docker:2'...
[58100 ms] Soft-dependency 'ghcr.io/devcontainers/features/common-utils' is not required.  Removing from installation order...
[58919 ms] Files to omit: ''
[58943 ms] Start: Run: docker buildx build --load --build-arg BUILDKIT_INLINE_CACHE=1 -f /var/folders/hc/3k4lvfw90yv7kghsnynghcvm0000gn/T/devcontainercli/container-features/0.78.0-1751290815562/Dockerfile-with-features -t vsc-devcontainer-cli-6f385ddc776962fbc66433725cf2935d233cb13fc75495e7d8b39668ffb80f7e --target dev_containers_target_stage --build-arg VARIANT=18-bookworm --build-context dev_containers_feature_content_source=/var/folders/hc/3k4lvfw90yv7kghsnynghcvm0000gn/T/devcontainercli/container-features/0.78.0-1751290815562 --build-arg _DEV_CONTAINERS_BASE_IMAGE=dev_container_auto_added_stage_label --build-arg _DEV_CONTAINERS_IMAGE_USER=node --build-arg _DEV_CONTAINERS_FEATURE_CONTENT_SOURCE=dev_container_feature_content_temp /Users/monotykamary/VCS/working-remote/open-source/devcontainer-cli/.devcontainer
[+] Building 39.4s (18/18) FINISHED                             docker:orbstack
...
{"outcome":"success","containerId":"29a48fbce0680d222eeb2de247e0ec2d3636801f857ade596e8579c883742973","remoteUser":"node","remoteWorkspaceFolder":"/workspaces/devcontainer-cli"}

Stopping the container:

$ node devcontainer.js stop --workspace-folder .
{"outcome":"success","stoppedContainers":["29a48fbce068"],"containersFound":1}
[2025-06-30T13:49:11.771Z] @devcontainers/cli 0.78.0. Node.js v23.11.0. darwin 24.5.0 arm64.

Verifying container is stopped but not removed:

$ docker ps -a --filter "id=29a48fbce068" --format "table {{.ID}}\t{{.Status}}"
CONTAINER ID   STATUS
29a48fbce068   Exited (0) 14 seconds ago

Removing the container:

$ node devcontainer.js down --workspace-folder .
{"outcome":"success","removedContainers":["29a48fbce068"],"removedVolumes":[],"containersFound":1}
[2025-06-30T13:49:35.845Z] @devcontainers/cli 0.78.0. Node.js v23.11.0. darwin 24.5.0 arm64.

Verifying container is completely removed:

$ docker ps -a --filter "id=29a48fbce068" --format "table {{.ID}}\t{{.Status}}"
CONTAINER ID   STATUS

Fixes

Fixes #386

[monotykamary]

@microsoft-github-policy-service agree

[frkhol]

poke @bamurtaugh :-)

[monotykamary]

Fixed observability for docker-compose projects

The issue where devcontainer down wasn't reporting removed containers for docker-compose setups has been fixed and added.

Changes:

• Added container listing before running docker-compose stop/down commands
• Returns actual container IDs in the response
• Properly reports the containersFound count

Example output after fix:

$ devcontainer down --workspace-folder .
[0 ms] @devcontainers/cli 0.78.0. Node.js v23.11.0. darwin 24.5.0 arm64.
[302 ms] Start: Run: docker compose -f /path/to/project/.devcontainer/docker-compose.yml --profile * config
{"outcome":"success","removedContainers":["4ece8ec99542","0caeaa724c07","9901a507f38d"],"containersFound":3,"dockerComposeProject":"project_devcontainer"}

The removedContainers array now correctly shows the container IDs that were removed, and containersFound shows the actual count.

[chrmarti]

Thanks for the PR! Left a few comments.

[monotykamary]

Sincerest thanks for the thorough review! I've made all the requested changes:

✅ Fixed issues:

1. Logging - Fixed getDockerComposeCLI to use proper logging output instead of dropping messages
2. Docker path support - Added dockerPath parameter to support alternative container runtimes like Podman
3. Safer --all flag - Changed from devcontainer.local_folder to devcontainer.metadata label for more reliable filtering
4. Error logging - Added logging for:
   • Container inspection failures
   • Volume removal failures

[AkeemMcLennon]

This looks great! Thanks for the fix!

@chrmarti / @monotykamary Is there anything left in this MR that I can help with?

[fictiontoreality]

@ MS: Please merge! This PR is over six months old now and sorely needed.

[monotykamary]

@ MS: Please merge! This PR is over six months old now and sorely needed.

you'd figure a 2-3 year issue that motivated the creation of a new OSS project (devpod) would have been solved by someone else at some point 🎅