Docker: new stacks and containers, stack down/delete, container remove, image pull/remove/prune

A new stack is a folder in a home (where stacks are already kept: Dockhand's group here,
~/stacks elsewhere) with compose.yaml and an optional root-only .env, validated by compose
before it is kept and deployed the way its neighbours were — inside dockhand, or to a node
over tcp from the hub. New container is the same dialog on a form that writes the compose.
Homes are scanned, so undeployed stacks stay listed. Delete moves a stack's files to
.hamlab-trash; nothing is forced, and volumes and data are never touched.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

internal/api/docker.go

@@ -11,6 +11,8 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
+	"log"
 	"net/http"
 	"os"
 	"os/exec"
@@ -143,19 +145,78 @@ var dockerRef = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$`)
 
 func (s *Server) dockerAction(w http.ResponseWriter, r *http.Request) {
 	id, action := r.PathValue("id"), r.PathValue("action")
-	if !dockerRef.MatchString(id) || (action != "start" && action != "stop" && action != "restart") {
-		jsonErr(w, 400, "start, stop or restart a container by name or ID")
+	if !dockerRef.MatchString(id) || (action != "start" && action != "stop" && action != "restart" && action != "remove") {
+		jsonErr(w, 400, "start, stop, restart or remove a container by name or ID")
 		return
 	}
 	ctx, cancel := context.WithTimeout(r.Context(), 90*time.Second)
 	defer cancel()
-	if _, err := dockerRun(ctx, action, id); err != nil {
+	verb := action
+	if action == "remove" { // never forced: a running container has to be stopped first, on purpose
+		verb = "rm"
+	}
+	if _, err := dockerRun(ctx, verb, id); err != nil {
+		code := 500
+		if action == "remove" {
+			code = 409
+		}
+		jsonErr(w, code, err.Error())
+		return
+	}
+	log.Printf("docker: %s %s (from %s)", action, id, clientIP(r))
+	w.WriteHeader(204)
+}
+
+var imageRef = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9._/:@-]{0,254}$`)
+
+// imagePull runs `docker pull` as a task the page follows.
+func (s *Server) imagePull(w http.ResponseWriter, r *http.Request) {
+	var body struct{ Image string }
+	if err := json.NewDecoder(io.LimitReader(r.Body, 4096)).Decode(&body); err != nil || !imageRef.MatchString(strings.TrimSpace(body.Image)) {
+		jsonErr(w, 400, "an image looks like nginx:alpine or ghcr.io/owner/name:tag")
+		return
+	}
+	ref := strings.TrimSpace(body.Image)
+	t, err := s.tasks.Start("docker:pull", "pull "+ref, exec.Command(dockerTool(), "pull", ref))
+	if err != nil {
 		jsonErr(w, 500, err.Error())
 		return
 	}
+	log.Printf("docker: pull %s as task %s (from %s)", ref, t.ID, clientIP(r))
+	jsonOK(w, 202, t.Snapshot(false))
+}
+
+// imageRemove is `docker rmi`, unforced: an image something still uses is refused by Docker, and that is the answer.
+func (s *Server) imageRemove(w http.ResponseWriter, r *http.Request) {
+	var body struct{ Image string }
+	if err := json.NewDecoder(io.LimitReader(r.Body, 4096)).Decode(&body); err != nil || !imageRef.MatchString(strings.TrimSpace(body.Image)) {
+		jsonErr(w, 400, "which image?")
+		return
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), 90*time.Second)
+	defer cancel()
+	if _, err := dockerRun(ctx, "rmi", strings.TrimSpace(body.Image)); err != nil {
+		jsonErr(w, 409, err.Error())
+		return
+	}
+	log.Printf("docker: rmi %s (from %s)", body.Image, clientIP(r))
 	w.WriteHeader(204)
 }
 
+// imagePrune removes dangling images only — layers no tag points at any more, left behind by pulls.
+func (s *Server) imagePrune(w http.ResponseWriter, r *http.Request) {
+	ctx, cancel := context.WithTimeout(r.Context(), 3*time.Minute)
+	defer cancel()
+	out, err := dockerRun(ctx, "image", "prune", "-f")
+	if err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	lines := strings.Split(strings.TrimSpace(string(out)), "\n")
+	log.Printf("docker: image prune (from %s)", clientIP(r))
+	jsonOK(w, 200, map[string]string{"result": lines[len(lines)-1]})
+}
+
 // dockerLogs is the tail of a container's log; ?since=<RFC3339> asks only for what is new,
 // which is how the page follows a log without holding a connection open.
 func (s *Server) dockerLogs(w http.ResponseWriter, r *http.Request) {