fix(#29 review r1): stack-delete leak, rollback/retention/version tests, UX trap

F3: deleting a file-based stack now removes the stack ROOT (compose/{id}) via a
new removeStackProjectDir helper, not stack.ProjectPath (which the PR repointed to
compose/{id}/v{N}) — old version dirs + parent no longer leak. Git stacks unchanged.
F1: tests for validateRollbackTarget (rejects 0/neg/>current/hole) and the rollback
snapshot (client content ignored, target read from disk, monotonic new version, note).
F2: tests for pruneStackFileVersionDirs (deletes given dirs, swallows errors) + the
post-commit gate contract + a monotonic-version regression guard.
F4: handler tests for ?version= (negative/out-of-range -> 400, valid version served,
legacy fallback).
F5: swagger @param version on GET file; @version 2.44.0 (handler.go) + package.json
2.44.0, matching APIVersion.
F6: the version selector no longer sets rollbackTo for the current/top version and
clears it on a manual buffer edit (so edits are honored, not silently discarded);
returning to the current version restores the current content. Distinguishes real
user edits from the programmatic version-load (CodeMirror ExternalChange).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

api/http/handler/handler.go

@@ -79,7 +79,7 @@ type Handler struct {
 }
 
 // @title PortainerCE API
-// @version 2.43.0
+// @version 2.44.0
 // @description.markdown
 // @x-tagGroups [{"name":"Access Control","tags":["auth","roles","team_memberships","teams","users"]},{"name":"Administration","tags":["backup","ldap","motd","settings","status","system","ssl","upload"]},{"name":"Docker","tags":["templates","custom_templates","docker","registries","resource_controls","stacks","webhooks","websocket"]},{"name":"Edge Compute","tags":["edge_agent","edge_groups","edge_jobs","edge","edge_stacks"]},{"name":"Environment Management","tags":["endpoint_groups","endpoints","tags"]},{"name":"GitOps","tags":["gitops"]},{"name":"Kubernetes","tags":["helm","kubernetes"]}]
 // @termsOfService

api/http/handler/stacks/stack_delete.go

@@ -139,13 +139,25 @@ func (handler *Handler) stackDelete(w http.ResponseWriter, r *http.Request) *htt
 		}
 	}
 
-	if err := handler.FileService.RemoveDirectory(stack.ProjectPath); err != nil {
+	if err := handler.removeStackProjectDir(stack); err != nil {
 		log.Warn().Err(err).Msg("Unable to remove stack files from disk")
 	}
 
 	return response.Empty(w)
 }
 
+// removeStackProjectDir deletes a stack's files from disk. For file-based (non-git) stacks the
+// whole stack root (compose/{id}) is removed so every versioned subfolder (v1..vN) is cleaned up,
+// because stack.ProjectPath only points at the current version directory (compose/{id}/v{N}).
+// Git stacks keep a ProjectPath of compose/{id}, so removing it directly preserves their behavior.
+func (handler *Handler) removeStackProjectDir(stack *portainer.Stack) error {
+	if stack.WorkflowID == 0 {
+		return handler.FileService.RemoveDirectory(handler.FileService.GetStackProjectPath(strconv.Itoa(int(stack.ID))))
+	}
+
+	return handler.FileService.RemoveDirectory(stack.ProjectPath)
+}
+
 func (handler *Handler) deleteExternalStack(r *http.Request, w http.ResponseWriter, stackName string, securityContext *security.RestrictedRequestContext) *httperror.HandlerError {
 	endpointID, err := request.RetrieveNumericQueryParameter(r, "endpointId", false)
 	if err != nil {
@@ -355,7 +367,7 @@ func (handler *Handler) stackDeleteKubernetesByName(w http.ResponseWriter, r *ht
 			continue
 		}
 
-		if err := handler.FileService.RemoveDirectory(stack.ProjectPath); err != nil {
+		if err := handler.removeStackProjectDir(&stack); err != nil {
 			errs = errors.Join(errs, err)
 			log.Warn().Err(err).Msg("Unable to remove stack files from disk")
 		}

api/http/handler/stacks/stack_file.go

@@ -30,6 +30,7 @@ type stackFileResponse struct {
 // @security jwt
 // @produce json
 // @param id path int true "Stack identifier"
+// @param version query int false "return this file version (file-based stacks)"
 // @success 200 {object} stackFileResponse "Success"
 // @failure 400 "Invalid request"
 // @failure 403 "Permission denied"

api/http/handler/stacks/stack_file_test.go

@@ -76,6 +76,130 @@ func TestStackFile_GitPendingRedeploy_Returns409(t *testing.T) {
 	require.Equal(t, http.StatusConflict, rr.Code)
 }
 
+// setupFileVersionStackTest wires a handler over a real datastore + filesystem and creates a
+// file-based (non-git) stack together with the given on-disk file versions. It returns the handler
+// and the created stack so version-selection cases can be exercised through the HTTP handler.
+func setupFileVersionStackTest(t *testing.T, stack *portainer.Stack, versionContent map[int]string) *Handler {
+	t.Helper()
+
+	_, store := datastore.MustNewTestStore(t, false, true)
+
+	_, err := mockCreateUser(store)
+	require.NoError(t, err)
+
+	endpoint, err := mockCreateEndpoint(store)
+	require.NoError(t, err)
+
+	fileService, err := filesystem.NewService(t.TempDir(), "")
+	require.NoError(t, err)
+
+	handler := NewHandler(testhelpers.NewTestRequestBouncer())
+	handler.FileService = fileService
+	handler.DataStore = store
+
+	stackFolder := strconv.Itoa(int(stack.ID))
+	for v, content := range versionContent {
+		_, err := fileService.StoreStackFileFromBytesByVersion(stackFolder, stack.EntryPoint, v, []byte(content))
+		require.NoError(t, err)
+	}
+
+	stack.EndpointID = endpoint.ID
+	require.NoError(t, store.Stack().Create(stack))
+
+	return handler
+}
+
+// requestStackFile performs a GET /stacks/{id}/file request (optionally with a raw query string).
+func requestStackFile(t *testing.T, handler *Handler, stackID portainer.StackID, rawQuery string) *httptest.ResponseRecorder {
+	t.Helper()
+
+	target := "/stacks/" + strconv.Itoa(int(stackID)) + "/file"
+	if rawQuery != "" {
+		target += "?" + rawQuery
+	}
+
+	req := mockCreateStackRequestWithSecurityContext(http.MethodGet, target, nil)
+	rr := httptest.NewRecorder()
+	handler.ServeHTTP(rr, req)
+
+	return rr
+}
+
+// TestStackFile_VersionParam exercises the ?version= selector on a file-based stack: rejects a
+// negative version, rejects an out-of-range version, and returns the selected version's content.
+func TestStackFile_VersionParam(t *testing.T) {
+	t.Parallel()
+
+	newHandlerAndStack := func(t *testing.T) (*Handler, portainer.StackID) {
+		stack := &portainer.Stack{
+			ID:               10,
+			Type:             portainer.DockerComposeStack,
+			EntryPoint:       "docker-compose.yml",
+			StackFileVersion: 3,
+			Versions: []portainer.StackFileVersionInfo{
+				{Version: 1}, {Version: 2}, {Version: 3},
+			},
+		}
+		handler := setupFileVersionStackTest(t, stack, map[int]string{
+			1: "V1-CONTENT", 2: "V2-CONTENT", 3: "V3-CONTENT",
+		})
+		// Point ProjectPath at the current version directory (as the versioning code does).
+		stack.ProjectPath = handler.FileService.GetStackProjectPathByVersion("10", 3, "")
+		require.NoError(t, handler.DataStore.Stack().Update(stack.ID, stack))
+
+		return handler, stack.ID
+	}
+
+	t.Run("negative version returns 400", func(t *testing.T) {
+		handler, id := newHandlerAndStack(t)
+		rr := requestStackFile(t, handler, id, "version=-1")
+		require.Equal(t, http.StatusBadRequest, rr.Code)
+	})
+
+	t.Run("out-of-range version returns 400", func(t *testing.T) {
+		handler, id := newHandlerAndStack(t)
+		rr := requestStackFile(t, handler, id, "version=99")
+		require.Equal(t, http.StatusBadRequest, rr.Code)
+	})
+
+	t.Run("valid version returns that version content", func(t *testing.T) {
+		handler, id := newHandlerAndStack(t)
+		rr := requestStackFile(t, handler, id, "version=2")
+		require.Equal(t, http.StatusOK, rr.Code)
+
+		var resp stackFileResponse
+		require.NoError(t, json.Unmarshal(rr.Body.Bytes(), &resp))
+		require.Equal(t, "V2-CONTENT", resp.StackFileContent)
+	})
+}
+
+// TestStackFile_VersionParam_LegacyFallback covers the fallback branch for stacks predating the
+// version history seed: when Versions[] is empty, an in-range version (1..StackFileVersion) is
+// accepted and served from its v{N} directory.
+func TestStackFile_VersionParam_LegacyFallback(t *testing.T) {
+	t.Parallel()
+
+	stack := &portainer.Stack{
+		ID:               11,
+		Type:             portainer.DockerComposeStack,
+		EntryPoint:       "docker-compose.yml",
+		StackFileVersion: 2,
+		// Versions intentionally empty: legacy stack without a recorded history.
+	}
+	handler := setupFileVersionStackTest(t, stack, map[int]string{
+		1: "LEGACY-V1", 2: "LEGACY-V2",
+	})
+	stack.ProjectPath = handler.FileService.GetStackProjectPathByVersion("11", 2, "")
+	require.NoError(t, handler.DataStore.Stack().Update(stack.ID, stack))
+
+	rr := requestStackFile(t, handler, stack.ID, "version=1")
+	require.Equal(t, http.StatusOK, rr.Code)
+
+	var resp stackFileResponse
+	require.NoError(t, json.Unmarshal(rr.Body.Bytes(), &resp))
+	require.Equal(t, "LEGACY-V1", resp.StackFileContent)
+}
+
 func TestStackFile_MatchingGitSettings_ReturnsFileContent(t *testing.T) {
 	t.Parallel()
 	_, store := datastore.MustNewTestStore(t, false, true)

api/http/handler/stacks/stack_versioning_test.go

@@ -1,11 +1,16 @@
 package stacks
 
 import (
+	"errors"
 	"strconv"
 	"testing"
 
 	portainer "github.com/portainer/portainer/api"
+	"github.com/portainer/portainer/api/dataservices"
+	"github.com/portainer/portainer/api/datastore"
 	"github.com/portainer/portainer/api/filesystem"
+	"github.com/portainer/portainer/api/internal/testhelpers"
+	httperror "github.com/portainer/portainer/pkg/libhttp/error"
 
 	"github.com/stretchr/testify/require"
 )
@@ -92,6 +97,250 @@ func versionNumbers(versions []portainer.StackFileVersionInfo) []int {
 	return out
 }
 
+// TestValidateRollbackTarget checks the rollback-version guard: it rejects non-positive versions,
+// versions above the current file version, and versions that are not present in the append-only
+// history (a "hole"), while accepting an in-range version that exists in Versions[].
+func TestValidateRollbackTarget(t *testing.T) {
+	t.Parallel()
+
+	// StackFileVersion is 5, but v4 was never recorded (a hole in the history).
+	stack := &portainer.Stack{
+		StackFileVersion: 5,
+		Versions: []portainer.StackFileVersionInfo{
+			{Version: 1}, {Version: 2}, {Version: 3}, {Version: 5},
+		},
+	}
+
+	require.Error(t, validateRollbackTarget(stack, 0), "zero is not a valid version")
+	require.Error(t, validateRollbackTarget(stack, -1), "negative is not a valid version")
+	require.Error(t, validateRollbackTarget(stack, 6), "version above StackFileVersion is out of range")
+	require.Error(t, validateRollbackTarget(stack, 4), "a version missing from history (hole) is rejected")
+
+	require.NoError(t, validateRollbackTarget(stack, 3), "in-range version present in history is accepted")
+	require.NoError(t, validateRollbackTarget(stack, 5), "current version present in history is accepted")
+}
+
+// newVersioningTestHandler builds a Handler wired with a real filesystem service and datastore,
+// plus a test user, for exercising the version snapshot/prune helpers.
+func newVersioningTestHandler(t *testing.T) (*Handler, *datastore.Store, portainer.FileService, *portainer.User) {
+	t.Helper()
+
+	_, store := datastore.MustNewTestStore(t, false, true)
+
+	fs, err := filesystem.NewService(t.TempDir(), "")
+	require.NoError(t, err)
+
+	user, err := mockCreateUser(store)
+	require.NoError(t, err)
+
+	handler := NewHandler(testhelpers.NewTestRequestBouncer())
+	handler.DataStore = store
+	handler.FileService = fs
+
+	return handler, store, fs, user
+}
+
+// TestSnapshotFileBasedStackVersion_Rollback verifies the rollback branch: it reads the TARGET
+// version's content from disk (ignoring the client-supplied content), writes a NEW monotonic
+// version whose note is "rollback from v{N}", and repoints ProjectPath to the new version dir.
+func TestSnapshotFileBasedStackVersion_Rollback(t *testing.T) {
+	t.Parallel()
+
+	handler, store, fs, user := newVersioningTestHandler(t)
+
+	stackFolder := "1"
+	entryPoint := "docker-compose.yml"
+
+	// Seed three on-disk versions with distinct content.
+	for v, content := range map[int]string{1: "V1-CONTENT", 2: "V2-CONTENT", 3: "V3-CONTENT"} {
+		_, err := fs.StoreStackFileFromBytesByVersion(stackFolder, entryPoint, v, []byte(content))
+		require.NoError(t, err)
+	}
+
+	stack := &portainer.Stack{
+		ID:               1,
+		EntryPoint:       entryPoint,
+		StackFileVersion: 3,
+		ProjectPath:      fs.GetStackProjectPathByVersion(stackFolder, 3, ""),
+		Versions: []portainer.StackFileVersionInfo{
+			{Version: 1}, {Version: 2}, {Version: 3},
+		},
+	}
+
+	target := 1
+	var (
+		pruned  []int
+		httpErr *httperror.HandlerError
+	)
+	err := store.UpdateTx(func(tx dataservices.DataStoreTx) error {
+		// Client content is deliberately non-empty to prove it is IGNORED for a rollback.
+		pruned, httpErr = handler.snapshotFileBasedStackVersion(tx, stack, []byte("CLIENT-CONTENT-IGNORED"), &target, user.ID)
+		return nil
+	})
+	require.NoError(t, err)
+	require.Nil(t, httpErr)
+	require.Empty(t, pruned, "no retention pruning expected below the cap")
+
+	// A new monotonic version (v4) was created.
+	require.Equal(t, 4, stack.StackFileVersion)
+	require.Equal(t, fs.GetStackProjectPathByVersion(stackFolder, 4, ""), stack.ProjectPath)
+
+	last := stack.Versions[len(stack.Versions)-1]
+	require.Equal(t, 4, last.Version)
+	require.Equal(t, "rollback from v1", last.Note)
+
+	// The new version's content is the TARGET (v1) content read from disk, not the client payload.
+	got, err := fs.GetFileContent(stack.ProjectPath, entryPoint)
+	require.NoError(t, err)
+	require.Equal(t, "V1-CONTENT", string(got))
+}
+
+// TestSnapshotFileBasedStackVersion_MonotonicVersion guards against a len-based next-version bug:
+// the new version must be StackFileVersion+1, strictly greater than any previously trimmed version,
+// even when the history slice is shorter than StackFileVersion (older entries already pruned).
+func TestSnapshotFileBasedStackVersion_MonotonicVersion(t *testing.T) {
+	t.Parallel()
+
+	handler, store, fs, user := newVersioningTestHandler(t)
+
+	stackFolder := "1"
+	entryPoint := "docker-compose.yml"
+
+	// StackFileVersion is 24 but only two history entries remain (older ones were pruned):
+	// a len-based scheme would wrongly compute the next version as len+1 = 3.
+	stack := &portainer.Stack{
+		ID:               1,
+		EntryPoint:       entryPoint,
+		StackFileVersion: 24,
+		ProjectPath:      fs.GetStackProjectPathByVersion(stackFolder, 24, ""),
+		Versions: []portainer.StackFileVersionInfo{
+			{Version: 23}, {Version: 24},
+		},
+	}
+
+	var httpErr *httperror.HandlerError
+	err := store.UpdateTx(func(tx dataservices.DataStoreTx) error {
+		_, httpErr = handler.snapshotFileBasedStackVersion(tx, stack, []byte("NEW-CONTENT"), nil, user.ID)
+		return nil
+	})
+	require.NoError(t, err)
+	require.Nil(t, httpErr)
+
+	require.Equal(t, 25, stack.StackFileVersion, "next version must be StackFileVersion+1, not len-based")
+	last := stack.Versions[len(stack.Versions)-1]
+	require.Equal(t, 25, last.Version)
+	require.Greater(t, last.Version, 24, "new version must be strictly greater than any prior version")
+
+	got, err := fs.GetFileContent(stack.ProjectPath, entryPoint)
+	require.NoError(t, err)
+	require.Equal(t, "NEW-CONTENT", string(got))
+}
+
+// countingFileService wraps a FileService to count and optionally fail RemoveDirectory calls,
+// so tests can assert prune ordering and error-swallowing without touching real disk.
+type countingFileService struct {
+	portainer.FileService
+	removeDirErr   error
+	removeDirCalls int
+	removedDirs    []string
+}
+
+func (s *countingFileService) GetStackProjectPathByVersion(stackID string, version int, commitHash string) string {
+	return "compose/" + stackID + "/v" + strconv.Itoa(version)
+}
+
+func (s *countingFileService) RemoveDirectory(dir string) error {
+	s.removeDirCalls++
+	s.removedDirs = append(s.removedDirs, dir)
+	return s.removeDirErr
+}
+
+// TestPruneStackFileVersionDirs_RemovesGivenDirs verifies the prune helper physically deletes
+// exactly the requested version directories and leaves the others untouched.
+func TestPruneStackFileVersionDirs_RemovesGivenDirs(t *testing.T) {
+	t.Parallel()
+
+	fs, err := filesystem.NewService(t.TempDir(), "")
+	require.NoError(t, err)
+
+	handler := NewHandler(testhelpers.NewTestRequestBouncer())
+	handler.FileService = fs
+
+	const stackID = portainer.StackID(9)
+	stackFolder := strconv.Itoa(int(stackID))
+
+	for v := 1; v <= 3; v++ {
+		_, err := fs.StoreStackFileFromBytesByVersion(stackFolder, "docker-compose.yml", v, []byte("v"+strconv.Itoa(v)))
+		require.NoError(t, err)
+	}
+
+	handler.pruneStackFileVersionDirs(stackID, []int{1, 3})
+
+	for v, wantExists := range map[int]bool{1: false, 2: true, 3: false} {
+		exists, err := fs.FileExists(fs.GetStackProjectPathByVersion(stackFolder, v, ""))
+		require.NoError(t, err)
+		require.Equal(t, wantExists, exists, "version %d directory existence mismatch", v)
+	}
+}
+
+// TestPruneStackFileVersionDirs_SwallowsRemoveError verifies a RemoveDirectory failure is
+// best-effort: it is logged and swallowed (no panic), and every requested version is attempted.
+func TestPruneStackFileVersionDirs_SwallowsRemoveError(t *testing.T) {
+	t.Parallel()
+
+	fs := &countingFileService{removeDirErr: errors.New("disk error")}
+	handler := NewHandler(testhelpers.NewTestRequestBouncer())
+	handler.FileService = fs
+
+	require.NotPanics(t, func() {
+		handler.pruneStackFileVersionDirs(7, []int{1, 2})
+	})
+	require.Equal(t, 2, fs.removeDirCalls, "every requested version directory must be attempted")
+}
+
+// TestPruneGateContract_Illustrative documents the post-commit gate shape used by stackUpdate:
+// the pruned version directories are physically removed only when the transaction committed
+// (err == nil); on a failed transaction the trimmed Versions[] was never persisted, so the
+// directories must be kept on disk to stay consistent with the database.
+//
+// NOTE: this reproduces the gate condition inline — it illustrates the intended contract rather
+// than exercising the real handler wiring (forcing a mid-commit UpdateTx failure while
+// pruneVersions is already populated is not injectable in a unit test). The actual gate lives in
+// stackUpdate (`if err == nil && len(pruneVersions) > 0`); pruneStackFileVersionDirs's real
+// behaviour (deletes the given dirs, swallows RemoveDirectory errors) is covered non-vacuously by
+// TestPruneStackFileVersionDirs_RemovesGivenDirs and _SwallowsRemoveError.
+func TestPruneGateContract_Illustrative(t *testing.T) {
+	t.Parallel()
+
+	pruneVersions := []int{1, 2}
+
+	t.Run("transaction failed - prune skipped", func(t *testing.T) {
+		fs := &countingFileService{}
+		handler := NewHandler(testhelpers.NewTestRequestBouncer())
+		handler.FileService = fs
+
+		var err error = errors.New("commit failed")
+		if err == nil && len(pruneVersions) > 0 {
+			handler.pruneStackFileVersionDirs(7, pruneVersions)
+		}
+
+		require.Zero(t, fs.removeDirCalls, "no directory may be deleted when the transaction failed")
+	})
+
+	t.Run("transaction committed - prune runs", func(t *testing.T) {
+		fs := &countingFileService{}
+		handler := NewHandler(testhelpers.NewTestRequestBouncer())
+		handler.FileService = fs
+
+		var err error
+		if err == nil && len(pruneVersions) > 0 {
+			handler.pruneStackFileVersionDirs(7, pruneVersions)
+		}
+
+		require.Equal(t, len(pruneVersions), fs.removeDirCalls, "all pruned directories deleted after commit")
+	})
+}
+
 // TestSnapshotStackFilesToVersion verifies a multi-file snapshot writes every file into the
 // v{N} folder and returns the version project path (not the base path).
 func TestSnapshotStackFilesToVersion(t *testing.T) {