Cleaning all or specific playground sessions (#258)

```sh
$ builder-playground clean
# or specific session
$ builder-playground clean major-hornet
```
The session list command is delivered from PR #257.

Author: canercidam

README.md

@@ -16,18 +16,18 @@ Quick start:
 
 ```bash
 # L1 environment with mev-boost relay
-builder-playground cook l1
+builder-playground start l1
 
 # L2 OpStack with external builder support
-builder-playground cook opstack --external-builder http://localhost:4444
+builder-playground start opstack --external-builder http://localhost:4444
 ```
 
 ## Getting started
 
-Clone the repository and use the `cook` command to deploy a specific recipe:
+Clone the repository and use the `start` command to deploy a specific recipe:
 
 ```bash
-$ builder-playground cook <recipe>
+$ builder-playground start <recipe>
 ```
 
 Currently available recipes:
@@ -41,7 +41,7 @@ Deploys a complete L1 environment with:
 - An in-memory [mev-boost-relay](https://github.com/flashbots/mev-boost-relay).
 
 ```bash
-$ builder-playground cook l1 [flags]
+$ builder-playground start l1 [flags]
 ```
 
 Flags:
@@ -61,7 +61,7 @@ Deploys an L2 environment with:
 - A complete sequencer with op-node, op-geth and op-batcher
 
 ```bash
-$ builder-playground cook opstack [flags]
+$ builder-playground start opstack [flags]
 ```
 
 Flags:
@@ -74,15 +74,15 @@ Flags:
 Here's a complete example showing how to run the L1 recipe with the latest fork enabled and custom output directory:
 
 ```bash
-$ builder-playground cook l1 --latest-fork --output ~/my-builder-testnet --genesis-delay 15 --log-level debug
+$ builder-playground start l1 --latest-fork --output ~/my-builder-testnet --genesis-delay 15 --log-level debug
 ```
 
 ### Generate transaction flow with contender
 
 builder-playground can generate transaction flow to its nodes with [contender](https://github.com/flashbots/contender). Just pass the `--contender` flag to send spam transactions that fill each block:
 
 ```bash
-go run main.go cook l1 --contender
+go run main.go start l1 --contender
 ```
 
 The default contender flags are as follows:
@@ -95,7 +95,7 @@ To add or modify contender flags, use `--contender.arg`:
 
 ```bash
 # run the builtin erc20 scenario instead of the default "fill block" scenario, at 100 TPS
-go run main.go cook l1 --contender \
+go run main.go start l1 --contender \
   --contender.arg "--tps 100" \
   --contender.arg "erc20"
 ```
@@ -137,18 +137,30 @@ $ builder-playground inspect <service> <port>
 Example:
 
 ```bash
-$ builder-playground cook opstack
+$ builder-playground start opstack
 $ builder-playground inspect op-geth authrpc
 ```
 
 This command starts a `tcpflow` container in the same network interface as the service and captures the traffic to the specified port.
 
 ## Clean
 
-Removes a recipe running in the background
+Remove local playground sessions:
 
 ```bash
-$ builder-playground clean [--output ./output]
+$ builder-playground stop all
+```
+
+You can also stop specific session:
+
+```bash
+$ builder-playground list
+honest-opossum
+major-hornet
+sacred-giraffe
+$ builder-playground stop honest-opossum sacred-giraffe
+Cleaning session: honest-opossum
+Cleaning session: sacred-giraffe
 ```
 
 ## Telemetry
@@ -167,8 +179,8 @@ By default, Prometheus scrapes the `/metrics` path, but services can override th
 Enable Prometheus for any recipe:
 
 ```bash
-$ builder-playground cook l1 --with-prometheus
-$ builder-playground cook opstack --with-prometheus
+$ builder-playground start l1 --with-prometheus
+$ builder-playground start opstack --with-prometheus
 ```
 
 ## Internals

main.go

@@ -47,9 +47,10 @@ var rootCmd = &cobra.Command{
 	},
 }
 
-var cookCmd = &cobra.Command{
-	Use:   "cook",
-	Short: "Cook a recipe",
+var startCmd = &cobra.Command{
+	Use:     "start",
+	Short:   "Start a recipe",
+	Aliases: []string{"cook"},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		recipeNames := []string{}
 		for _, recipe := range recipes {
@@ -59,18 +60,27 @@ var cookCmd = &cobra.Command{
 	},
 }
 
-var cleanCmd = &cobra.Command{
-	Use:   "clean",
-	Short: "Clean a recipe",
+var stopCmd = &cobra.Command{
+	Use:   "stop",
+	Short: "Stop a playground session",
 	RunE: func(cmd *cobra.Command, args []string) error {
-		manifest, err := playground.ReadManifest(outputFlag)
-		if err != nil {
-			return err
+		sessions := args
+		if len(sessions) == 0 {
+			return fmt.Errorf("please specify at least one session name or 'all' to stop all sessions")
 		}
-		if err := playground.StopContainersBySessionID(manifest.ID); err != nil {
-			return err
+		if len(sessions) == 1 && sessions[0] == "all" {
+			var err error
+			sessions, err = playground.GetLocalSessions()
+			if err != nil {
+				return err
+			}
+		}
+		for _, session := range sessions {
+			if err := playground.StopSession(session); err != nil {
+				return err
+			}
+			fmt.Println("Stopping session:", session)
 		}
-		fmt.Println("The recipe has been stopped and cleaned.")
 		return nil
 	},
 }
@@ -143,15 +153,15 @@ func main() {
 		recipeCmd.Flags().StringVar(&contenderTarget, "contender.target", "", "override the node that contender spams -- accepts names like \"el\"")
 		recipeCmd.Flags().BoolVar(&detached, "detached", false, "Detached mode: Run the recipes in the background")
 
-		cookCmd.AddCommand(recipeCmd)
+		startCmd.AddCommand(recipeCmd)
 	}
 
-	rootCmd.AddCommand(cookCmd)
+	rootCmd.AddCommand(startCmd)
 	rootCmd.AddCommand(inspectCmd)
 	rootCmd.AddCommand(versionCmd)
 
-	rootCmd.AddCommand(cleanCmd)
-	cleanCmd.Flags().StringVar(&outputFlag, "output", "", "Output folder for the artifacts")
+	rootCmd.AddCommand(stopCmd)
+	stopCmd.Flags().StringVar(&outputFlag, "output", "", "Output folder for the artifacts")
 
 	if err := rootCmd.Execute(); err != nil {
 		fmt.Println(err)

playground/local_runner.go

@@ -5,13 +5,15 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"log/slog"
 	"maps"
 	"net"
 	"net/url"
 	"os"
 	"os/exec"
 	"path/filepath"
 	"runtime"
+	"slices"
 	"strings"
 	"sync"
 	"text/template"
@@ -228,11 +230,14 @@ func (d *LocalRunner) Stop() error {
 	for _, handle := range d.handles {
 		handle.Process.Kill()
 	}
+	return StopSession(d.manifest.ID)
+}
 
+func StopSession(id string) error {
 	// stop the docker-compose
 	cmd := exec.CommandContext(
 		context.Background(), "docker", "compose",
-		"-p", d.manifest.ID,
+		"-p", id,
 		"down",
 		"-v", // removes containers and volumes
 	)
@@ -247,6 +252,28 @@ func (d *LocalRunner) Stop() error {
 	return nil
 }
 
+func GetLocalSessions() ([]string, error) {
+	var sessions []string
+	client, err := newDockerClient()
+	if err != nil {
+		return nil, err
+	}
+	containers, err := client.ContainerList(context.Background(), container.ListOptions{
+		All: true,
+	})
+	if err != nil {
+		return nil, err
+	}
+	for _, container := range containers {
+		if container.Labels["playground"] == "true" {
+			sessions = append(sessions, container.Labels["playground.session"])
+		}
+	}
+	// Return sorted unique occurences
+	slices.Sort(sessions)
+	return slices.Compact(sessions), nil
+}
+
 // reservePort finds the first available port from the startPort and reserves it
 // Note that we have to keep track of the port in 'reservedPorts' because
 // the port allocation happens before the services uses it and binds to it.
@@ -839,6 +866,7 @@ func (d *LocalRunner) ensureImage(ctx context.Context, imageName string) error {
 	// Image not found locally, pull it
 	d.config.Callback(imageName, TaskStatusPulling)
 
+	slog.Info("pulling image", "image", imageName)
 	reader, err := d.client.ImagePull(ctx, imageName, image.PullOptions{})
 	if err != nil {
 		return fmt.Errorf("failed to pull image %s: %w", imageName, err)
@@ -925,40 +953,3 @@ func (d *LocalRunner) Run(ctx context.Context) error {
 
 	return g.Wait()
 }
-
-// StopContainersBySessionID removes all Docker containers associated with a specific playground session ID.
-// This is a standalone utility function used by the clean command to stop containers without requiring
-// a LocalRunner instance or manifest reference.
-//
-// TODO: Refactor to reduce code duplication with LocalRunner.Stop()
-// Consider creating a shared dockerClient wrapper with helper methods for container management
-// that both LocalRunner and this function can use.
-func StopContainersBySessionID(id string) error {
-	client, err := newDockerClient()
-	if err != nil {
-		return err
-	}
-
-	containers, err := client.ContainerList(context.Background(), container.ListOptions{
-		Filters: filters.NewArgs(filters.Arg("label", fmt.Sprintf("playground.session=%s", id))),
-	})
-	if err != nil {
-		return fmt.Errorf("error getting container list: %w", err)
-	}
-
-	g := new(errgroup.Group)
-	for _, cont := range containers {
-		g.Go(func() error {
-			if err := client.ContainerRemove(context.Background(), cont.ID, container.RemoveOptions{
-				RemoveVolumes: true,
-				RemoveLinks:   false,
-				Force:         true,
-			}); err != nil {
-				return fmt.Errorf("error removing container: %w", err)
-			}
-			return nil
-		})
-	}
-
-	return g.Wait()
-}

playground/releases.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"io"
 	"log"
+	"log/slog"
 	"net/http"
 	"os"
 	"os/exec"
@@ -67,6 +68,7 @@ func DownloadRelease(outputFolder string, artifact *release) (string, error) {
 }
 
 func downloadArtifact(url, expectedFile, outPath string) error {
+	slog.Info("downloading artifact", "url", url, "expectedFile", expectedFile, "outPath", outPath)
 	// Download the file
 	resp, err := http.Get(url)
 	if err != nil {