feat(storage): speed up scans and add dependency cleanup (#2432)

This commit is contained in:
Carlos Florêncio
2026-08-08 19:30:05 +01:00
committed by GitHub
parent 56fdc7b011
commit 7133b132f6
51 changed files with 3323 additions and 132 deletions
@@ -49,6 +49,11 @@ func (i *storageInventory) LoadWorkspaceInventory(ctx context.Context) (workspac
})
}
}
tasks, err := i.taskWorkspaceStates(ctx)
if err != nil {
return workspaces.Inventory{}, err
}
inventory.KnownTaskIDs, inventory.ArchivedTaskIDs = taskEligibilitySets(tasks)
return inventory, nil
}
@@ -88,6 +93,32 @@ type activeWorkspaceRow struct {
WorkspacePath string
}
type taskWorkspaceState struct {
ID string `db:"id"`
ArchivedAt *time.Time `db:"archived_at"`
}
func (i *storageInventory) taskWorkspaceStates(ctx context.Context) ([]taskWorkspaceState, error) {
rows := make([]taskWorkspaceState, 0)
query := i.reader.Rebind("SELECT id, archived_at FROM tasks")
if err := i.reader.SelectContext(ctx, &rows, query); err != nil {
return nil, err
}
return rows, nil
}
func taskEligibilitySets(tasks []taskWorkspaceState) (map[string]struct{}, map[string]struct{}) {
known := make(map[string]struct{}, len(tasks))
archived := make(map[string]struct{})
for _, task := range tasks {
known[task.ID] = struct{}{}
if task.ArchivedAt != nil {
archived[task.ID] = struct{}{}
}
}
return known, archived
}
type containerInventory struct{ reader *sqlx.DB }
func (i *containerInventory) ContainerTaskRemovable(ctx context.Context, taskID string) (bool, error) {
@@ -95,6 +95,48 @@ func TestWorkspaceInventoryOnlyProtectsActiveTaskWorktrees(t *testing.T) {
}
}
func TestWorkspaceInventoryLoadsTaskEligibilityStates(t *testing.T) {
t.Run("active and archived tasks", func(t *testing.T) {
database := newContainerInventoryDatabase(t)
insertContainerInventoryTask(t, database, "active", v1.TaskStateInProgress, false)
insertContainerInventoryTask(t, database, "archived", v1.TaskStateCompleted, true)
states, err := (&storageInventory{reader: database}).taskWorkspaceStates(context.Background())
if err != nil {
t.Fatalf("taskWorkspaceStates: %v", err)
}
known, archived := taskEligibilitySets(states)
if !reflect.DeepEqual(known, map[string]struct{}{"active": {}, "archived": {}}) {
t.Fatalf("known task IDs = %#v", known)
}
if !reflect.DeepEqual(archived, map[string]struct{}{"archived": {}}) {
t.Fatalf("archived task IDs = %#v", archived)
}
})
t.Run("empty database", func(t *testing.T) {
database := newContainerInventoryDatabase(t)
states, err := (&storageInventory{reader: database}).taskWorkspaceStates(context.Background())
if err != nil {
t.Fatalf("taskWorkspaceStates: %v", err)
}
known, archived := taskEligibilitySets(states)
if len(states) != 0 || len(known) != 0 || len(archived) != 0 {
t.Fatalf("empty task eligibility = states %#v known %#v archived %#v", states, known, archived)
}
})
t.Run("query error", func(t *testing.T) {
database := newContainerInventoryDatabase(t)
if err := database.Close(); err != nil {
t.Fatalf("close inventory database: %v", err)
}
if _, err := (&storageInventory{reader: database}).taskWorkspaceStates(context.Background()); err == nil {
t.Fatal("taskWorkspaceStates error = nil, want closed-database error")
}
})
}
func TestContainerInventoryRemovability(t *testing.T) {
tests := []struct {
name string
@@ -7,6 +7,7 @@ import (
"fmt"
"os"
"path/filepath"
"sync"
"time"
"github.com/kandev/kandev/internal/agent/runtime/activity"
@@ -15,6 +16,7 @@ import (
"github.com/kandev/kandev/internal/common/logger"
"github.com/kandev/kandev/internal/db"
"github.com/kandev/kandev/internal/system/jobs"
systemmetrics "github.com/kandev/kandev/internal/system/metrics"
systemsettings "github.com/kandev/kandev/internal/system/settings"
storagepkg "github.com/kandev/kandev/internal/system/storage"
"github.com/kandev/kandev/internal/system/storage/dockerstore"
@@ -107,6 +109,17 @@ func provideStorageComposition(
})
handler := storagepkg.NewHandler(storagepkg.HandlerConfig{
Settings: settings, Runs: store, Quarantine: store, Overview: cachedOverview,
DiskCapacity: func(ctx context.Context, path string) (storagepkg.DiskCapacity, error) {
capacity, err := systemmetrics.DiskUsage(ctx, path)
if err != nil {
return storagepkg.DiskCapacity{}, err
}
return storagepkg.DiskCapacity{
TotalBytes: capacity.TotalBytes, UsedBytes: capacity.UsedBytes,
AvailableBytes: capacity.AvailableBytes, UsedPercent: capacity.UsedPercent,
}, nil
},
DiskPath: cfg.ResolvedHomeDir(),
Mutations: operations, OnSettingsChanged: runtime.ApplySettings, LogError: logError,
})
return &storageComposition{
@@ -162,7 +175,9 @@ type storageOverview struct {
settings *storagepkg.SettingsStore
quarantine quarantineSummarizer
workspaceFactory workspaceFactory
workspaceAnalyze func(context.Context, storagepkg.StorageMaintenanceSettings) (workspaces.Analysis, error)
goCache *gocache.Provider
goCacheAnalyze func(context.Context) (gocache.Analysis, error)
docker *dockerstore.Provider
dockerClient *lazyStorageDocker
dockerHost string
@@ -174,10 +189,44 @@ func (o *storageOverview) Summary(ctx context.Context) (storagepkg.Summary, erro
if err != nil {
return storagepkg.Summary{}, err
}
workspaceSummary, workspaceErr := o.workspaceFactory(settings).Analyze(ctx)
goCacheSummary, goCacheErr := o.goCache.Analyze(ctx)
quarantineSummary, quarantineErr := o.quarantine.SummarizeQuarantine(ctx)
dockerSummary := o.docker.Analyze(ctx)
var (
workspaceSummary workspaces.Analysis
workspaceErr error
goCacheSummary gocache.Analysis
goCacheErr error
quarantineSummary storagepkg.QuarantineSummary
quarantineErr error
dockerSummary dockerstore.Analysis
)
var measurements sync.WaitGroup
measurements.Add(4)
workspaceAnalyze := o.workspaceAnalyze
if workspaceAnalyze == nil {
workspaceAnalyze = func(ctx context.Context, settings storagepkg.StorageMaintenanceSettings) (workspaces.Analysis, error) {
return o.workspaceFactory(settings).Analyze(ctx)
}
}
goCacheAnalyze := o.goCacheAnalyze
if goCacheAnalyze == nil {
goCacheAnalyze = o.goCache.Analyze
}
go func() {
defer measurements.Done()
workspaceSummary, workspaceErr = workspaceAnalyze(ctx, settings)
}()
go func() {
defer measurements.Done()
goCacheSummary, goCacheErr = goCacheAnalyze(ctx)
}()
go func() {
defer measurements.Done()
quarantineSummary, quarantineErr = o.quarantine.SummarizeQuarantine(ctx)
}()
go func() {
defer measurements.Done()
dockerSummary = o.docker.Analyze(ctx)
}()
measurements.Wait()
return storagepkg.Summary{
Workspaces: summaryValue(workspaceSummary, workspaceErr),
GoCache: summaryValue(goCacheSummary, goCacheErr),
@@ -271,6 +320,7 @@ func storageCleanupProviders(
return []storagepkg.CleanupProvider{
quarantineCleanupProvider{purger: quarantine},
workspaceCleanupAdapter(settings, workspaceFactory),
workspaceDependencyCleanupAdapter(settings, workspaceFactory),
goCacheCleanupProvider{provider: goCache},
dockerContainerCleanupAdapter(settings, docker),
dockerBuildCacheCleanupAdapter(settings, docker),
@@ -278,6 +328,20 @@ func storageCleanupProviders(
}
}
func workspaceDependencyCleanupAdapter(
settings *storagepkg.SettingsStore,
factory workspaceFactory,
) storagepkg.CleanupProvider {
return namedCleanupProvider{name: "workspace_dependencies", cleanup: func(ctx context.Context) (map[string]any, error) {
current, err := settings.GetSettings(ctx)
if err != nil || !current.Workspaces.DependencyCleanupEnabled {
return nil, err
}
result, err := factory(current).CleanupDependencies(ctx)
return toMap(result), err
}}
}
func workspaceCleanupAdapter(
settings *storagepkg.SettingsStore,
factory workspaceFactory,
@@ -7,6 +7,7 @@ import (
"os"
"path/filepath"
"strings"
"sync"
"testing"
"time"
@@ -92,6 +93,187 @@ func TestStorageOverviewIncludesQuarantineAndManagedContainers(t *testing.T) {
}
}
func TestStorageCleanupProvidersIncludeWorkspaceDependencyCleanup(t *testing.T) {
settings, store := newStorageMaintenanceStores(t)
home := t.TempDir()
workspaceFactory := func(storagepkg.StorageMaintenanceSettings) *workspaces.Provider {
return workspaces.New(workspaces.Config{TasksRoot: filepath.Join(home, "tasks"), Store: store})
}
providers := storageCleanupProviders(settings, workspaceFactory, nil, nil, nil)
for _, provider := range providers {
if provider.Name() == "workspace_dependencies" {
return
}
}
t.Fatal("storage cleanup providers did not include workspace_dependencies")
}
func TestWorkspaceDependencyCleanupProviderIsDefaultOff(t *testing.T) {
settings, store := newStorageMaintenanceStores(t)
home := t.TempDir()
factoryCalls := 0
workspaceFactory := func(storagepkg.StorageMaintenanceSettings) *workspaces.Provider {
factoryCalls++
return workspaces.New(workspaces.Config{TasksRoot: filepath.Join(home, "tasks"), Store: store})
}
var dependencyProvider storagepkg.CleanupProvider
for _, provider := range storageCleanupProviders(settings, workspaceFactory, nil, nil, nil) {
if provider.Name() == "workspace_dependencies" {
dependencyProvider = provider
break
}
}
if dependencyProvider == nil {
t.Fatal("workspace dependency provider is missing")
}
if result, err := dependencyProvider.Cleanup(context.Background()); err != nil || result != nil {
t.Fatalf("default-off cleanup = (%#v, %v), want no-op", result, err)
}
if factoryCalls != 0 {
t.Fatalf("workspace factory calls = %d, want 0 while disabled", factoryCalls)
}
enabled := storagepkg.DefaultSettings()
enabled.Workspaces.DependencyCleanupEnabled = true
if _, err := settings.SaveSettings(context.Background(), enabled); err != nil {
t.Fatalf("enable dependency cleanup: %v", err)
}
if _, err := dependencyProvider.Cleanup(context.Background()); err == nil {
t.Fatal("enabled dependency cleanup unexpectedly succeeded without complete inventory")
}
if factoryCalls != 1 {
t.Fatalf("workspace factory calls = %d, want 1 after enabling", factoryCalls)
}
}
func TestStorageOverviewStartsIndependentMeasurementsTogether(t *testing.T) {
home := t.TempDir()
for _, dir := range []string{filepath.Join(home, "tasks"), filepath.Join(home, "trash")} {
if err := os.MkdirAll(dir, 0o700); err != nil {
t.Fatal(err)
}
}
t.Setenv("GOCACHE", filepath.Join(home, "go-cache"))
settings, store := newStorageMaintenanceStores(t)
workspaceStarted, workspaceRelease := make(chan struct{}), make(chan struct{})
goCacheStarted, goCacheRelease := make(chan struct{}), make(chan struct{})
quarantine := &blockingOverviewQuarantine{
started: make(chan struct{}), release: make(chan struct{}),
}
dockerClient := &blockingOverviewDockerClient{
started: make(chan struct{}), release: make(chan struct{}),
}
var releaseOnce sync.Once
releaseMeasurements := func() {
releaseOnce.Do(func() {
close(workspaceRelease)
close(goCacheRelease)
close(quarantine.release)
close(dockerClient.release)
})
}
t.Cleanup(releaseMeasurements)
docker := dockerstore.NewProvider(dockerClient, overviewContainerInventory{}, settings)
overview := &storageOverview{
settings: settings, quarantine: quarantine,
workspaceAnalyze: func(context.Context, storagepkg.StorageMaintenanceSettings) (workspaces.Analysis, error) {
close(workspaceStarted)
<-workspaceRelease
return workspaces.Analysis{}, nil
},
goCacheAnalyze: func(context.Context) (gocache.Analysis, error) {
close(goCacheStarted)
<-goCacheRelease
return gocache.Analysis{}, nil
},
workspaceFactory: func(current storagepkg.StorageMaintenanceSettings) *workspaces.Provider {
return workspaces.New(workspaces.Config{
TasksRoot: filepath.Join(home, "tasks"), TrashRoot: filepath.Join(home, "trash"),
Inventory: overviewWorkspaceInventory{}, Store: store,
GracePeriod: time.Duration(current.OrphanGraceHours) * time.Hour,
Retention: time.Duration(current.QuarantineRetentionHours) * time.Hour,
})
},
goCache: gocache.New(gocache.Config{
HomeDir: home, TrashDir: filepath.Join(home, "trash"), Settings: settings, Store: store,
}),
docker: docker, homeDir: home,
}
resultCh := make(chan struct {
summary storagepkg.Summary
err error
}, 1)
go func() {
summary, err := overview.Summary(context.Background())
resultCh <- struct {
summary storagepkg.Summary
err error
}{summary: summary, err: err}
}()
for _, measurement := range []struct {
name string
started <-chan struct{}
}{
{name: "workspace", started: workspaceStarted},
{name: "Go cache", started: goCacheStarted},
{name: "quarantine", started: quarantine.started},
{name: "Docker", started: dockerClient.started},
} {
select {
case <-measurement.started:
case <-time.After(time.Second):
t.Fatalf("%s measurement did not start before the barrier was released", measurement.name)
}
}
releaseMeasurements()
select {
case result := <-resultCh:
if result.err != nil {
t.Fatalf("Summary: %v", result.err)
}
case <-time.After(time.Second):
t.Fatal("Summary did not finish")
}
}
type blockingOverviewQuarantine struct {
started chan struct{}
release chan struct{}
}
func (s *blockingOverviewQuarantine) SummarizeQuarantine(context.Context) (storagepkg.QuarantineSummary, error) {
close(s.started)
<-s.release
return storagepkg.QuarantineSummary{}, nil
}
type blockingOverviewDockerClient struct {
started chan struct{}
release chan struct{}
}
func (c *blockingOverviewDockerClient) Ping(context.Context) error { return nil }
func (c *blockingOverviewDockerClient) ListContainers(context.Context, map[string]string) ([]agentdocker.ContainerInfo, error) {
return nil, nil
}
func (c *blockingOverviewDockerClient) RemoveContainer(context.Context, string, bool) error {
return nil
}
func (c *blockingOverviewDockerClient) DiskUsage(context.Context) (agentdocker.DiskUsage, error) {
close(c.started)
<-c.release
return agentdocker.DiskUsage{}, nil
}
func (c *blockingOverviewDockerClient) PruneBuildCache(context.Context, agentdocker.BuildCachePruneOptions) (agentdocker.PruneResult, error) {
return agentdocker.PruneResult{}, nil
}
func (c *blockingOverviewDockerClient) PruneUnusedImages(context.Context, time.Time) (agentdocker.PruneResult, error) {
return agentdocker.PruneResult{}, nil
}
type failingQuarantineSummarizer struct{ err error }
func (s failingQuarantineSummarizer) SummarizeQuarantine(context.Context) (storagepkg.QuarantineSummary, error) {
@@ -479,14 +661,14 @@ func TestQuarantineCleanupProviderPurgesEligibleEntries(t *testing.T) {
func TestStorageCleanupProvidersIncludesQuarantineProvider(t *testing.T) {
providers := storageCleanupProviders(nil, nil, nil, nil, &recordingQuarantinePurger{})
if len(providers) != 6 {
t.Fatalf("provider count = %d, want 6", len(providers))
if len(providers) != 7 {
t.Fatalf("provider count = %d, want 7", len(providers))
}
if providers[0].Name() != "quarantine" {
t.Fatalf("first provider = %q, want quarantine", providers[0].Name())
}
if providers[1].Name() != "workspaces" || providers[2].Name() != "go_cache" {
t.Fatalf("provider order = %q, %q, want workspaces, go_cache", providers[1].Name(), providers[2].Name())
if providers[1].Name() != "workspaces" || providers[2].Name() != "workspace_dependencies" || providers[3].Name() != "go_cache" {
t.Fatalf("provider order = %q, %q, %q, want workspaces, workspace_dependencies, go_cache", providers[1].Name(), providers[2].Name(), providers[3].Name())
}
}
@@ -0,0 +1,42 @@
package metrics
import (
"context"
"errors"
)
// DiskCapacity describes the space available on a filesystem.
type DiskCapacity struct {
TotalBytes uint64
AvailableBytes uint64
UsedBytes uint64
UsedPercent float64
}
func diskCapacityFromBytes(total, available uint64) (DiskCapacity, error) {
if total == 0 {
return DiskCapacity{}, errors.New("disk total is zero")
}
if available > total {
available = total
}
used := total - available
percent := float64(used) / float64(total) * 100
return DiskCapacity{
TotalBytes: total, AvailableBytes: available, UsedBytes: used, UsedPercent: percent,
}, nil
}
// Only one potentially blocking platform call is admitted at a time. Context
// cancellation can return the request before the OS call does, so this guard
// prevents repeated refreshes from accumulating unbounded goroutines.
var diskUsageCall = make(chan struct{}, 1)
func acquireDiskUsageCall(ctx context.Context) (func(), error) {
select {
case diskUsageCall <- struct{}{}:
return func() { <-diskUsageCall }, nil
case <-ctx.Done():
return nil, ctx.Err()
}
}
@@ -0,0 +1,33 @@
package metrics
import "testing"
func TestDiskCapacityFromBytesClampsAvailableSpace(t *testing.T) {
capacity, err := diskCapacityFromBytes(100, 125)
if err != nil {
t.Fatalf("diskCapacityFromBytes: %v", err)
}
if capacity.TotalBytes != 100 || capacity.AvailableBytes != 100 || capacity.UsedBytes != 0 || capacity.UsedPercent != 0 {
t.Fatalf("capacity = %#v, want zero used space", capacity)
}
}
func TestDiskCapacityFromBytesReturnsExactFields(t *testing.T) {
capacity, err := diskCapacityFromBytes(1000, 250)
if err != nil {
t.Fatalf("diskCapacityFromBytes: %v", err)
}
if capacity.TotalBytes != 1000 || capacity.AvailableBytes != 250 || capacity.UsedBytes != 750 || capacity.UsedPercent != 75 {
t.Fatalf("capacity = %#v, want total=1000 available=250 used=750 percent=75", capacity)
}
}
func TestDiskCapacityFromBytesRejectsZeroTotal(t *testing.T) {
capacity, err := diskCapacityFromBytes(0, 0)
if err == nil {
t.Fatal("diskCapacityFromBytes error = nil, want zero-total error")
}
if capacity != (DiskCapacity{}) {
t.Fatalf("capacity = %#v, want zero value", capacity)
}
}
@@ -4,7 +4,6 @@ package metrics
import (
"context"
"errors"
"fmt"
"syscall"
"time"
@@ -20,11 +19,24 @@ type diskStatfsResult struct {
}
func diskPercent(ctx context.Context, path string) (float64, error) {
capacity, err := DiskUsage(ctx, path)
if err != nil {
return 0, err
}
return capacity.UsedPercent, nil
}
func DiskUsage(ctx context.Context, path string) (DiskCapacity, error) {
release, err := acquireDiskUsageCall(ctx)
if err != nil {
return DiskCapacity{}, err
}
result := make(chan diskStatfsResult, 1)
go func() {
defer release()
var stat syscall.Statfs_t
err := statfs(path, &stat)
result <- diskStatfsResult{stat: stat, err: err}
callErr := statfs(path, &stat)
result <- diskStatfsResult{stat: stat, err: callErr}
}()
timer := time.NewTimer(diskStatfsTimeout)
@@ -32,22 +44,27 @@ func diskPercent(ctx context.Context, path string) (float64, error) {
select {
case <-ctx.Done():
return 0, ctx.Err()
return DiskCapacity{}, ctx.Err()
case <-timer.C:
return 0, fmt.Errorf("disk usage timed out for %q", path)
return DiskCapacity{}, fmt.Errorf("disk usage timed out for %q", path)
case res := <-result:
if res.err != nil {
return 0, res.err
return DiskCapacity{}, res.err
}
return diskPercentFromStatfs(res.stat)
return diskCapacityFromStatfs(res.stat)
}
}
func diskPercentFromStatfs(stat syscall.Statfs_t) (float64, error) {
total := stat.Blocks * uint64(stat.Bsize)
free := stat.Bavail * uint64(stat.Bsize)
if total == 0 {
return 0, errors.New("disk total is zero")
capacity, err := diskCapacityFromStatfs(stat)
if err != nil {
return 0, err
}
return (1 - float64(free)/float64(total)) * 100, nil
return capacity.UsedPercent, nil
}
func diskCapacityFromStatfs(stat syscall.Statfs_t) (DiskCapacity, error) {
total := stat.Blocks * uint64(stat.Bsize)
available := stat.Bavail * uint64(stat.Bsize)
return diskCapacityFromBytes(total, available)
}
@@ -5,6 +5,7 @@ package metrics
import (
"context"
"errors"
"sync/atomic"
"syscall"
"testing"
"time"
@@ -14,8 +15,11 @@ func TestDiskPercentReturnsWhenContextCancelsWhileStatfsBlocks(t *testing.T) {
original := statfs
block := make(chan struct{})
started := make(chan struct{})
var calls atomic.Int32
statfs = func(_ string, _ *syscall.Statfs_t) error {
close(started)
if calls.Add(1) == 1 {
close(started)
}
<-block
return errors.New("unblocked")
}
@@ -46,4 +50,31 @@ func TestDiskPercentReturnsWhenContextCancelsWhileStatfsBlocks(t *testing.T) {
case <-time.After(500 * time.Millisecond):
t.Fatal("diskPercent did not return after context cancellation")
}
for range 20 {
requestContext, requestCancel := context.WithCancel(context.Background())
requestCancel()
if _, err := DiskUsage(requestContext, "/still-slow"); !errors.Is(err, context.Canceled) {
t.Fatalf("repeated DiskUsage error = %v, want context.Canceled", err)
}
}
if got := calls.Load(); got != 1 {
t.Fatalf("blocked statfs calls = %d, want one admitted call", got)
}
}
func TestDiskUsageReturnsCapacityFields(t *testing.T) {
original := statfs
statfs = func(_ string, stat *syscall.Statfs_t) error {
*stat = syscall.Statfs_t{Blocks: 1000, Bsize: 1, Bavail: 250}
return nil
}
t.Cleanup(func() { statfs = original })
capacity, err := DiskUsage(context.Background(), "/data")
if err != nil {
t.Fatalf("DiskUsage: %v", err)
}
if capacity.TotalBytes != 1000 || capacity.AvailableBytes != 250 || capacity.UsedBytes != 750 || capacity.UsedPercent != 75 {
t.Fatalf("capacity = %#v, want total=1000 available=250 used=750 percent=75", capacity)
}
}
@@ -4,7 +4,6 @@ package metrics
import (
"context"
"errors"
"fmt"
"time"
@@ -23,16 +22,29 @@ type diskQueryResult struct {
}
func diskPercent(ctx context.Context, path string) (float64, error) {
capacity, err := DiskUsage(ctx, path)
if err != nil {
return 0, err
}
return capacity.UsedPercent, nil
}
func DiskUsage(ctx context.Context, path string) (DiskCapacity, error) {
dir, err := windows.UTF16PtrFromString(path)
if err != nil {
return 0, fmt.Errorf("convert path %q: %w", path, err)
return DiskCapacity{}, fmt.Errorf("convert path %q: %w", path, err)
}
release, err := acquireDiskUsageCall(ctx)
if err != nil {
return DiskCapacity{}, err
}
result := make(chan diskQueryResult, 1)
go func() {
defer release()
var freeToCaller, totalBytes, totalFree uint64
callErr := getDiskFreeSpaceEx(dir, &freeToCaller, &totalBytes, &totalFree)
result <- diskQueryResult{totalBytes: totalBytes, freeBytes: totalFree, err: callErr}
result <- diskQueryResult{totalBytes: totalBytes, freeBytes: freeToCaller, err: callErr}
}()
timer := time.NewTimer(diskQueryTimeout)
@@ -40,20 +52,21 @@ func diskPercent(ctx context.Context, path string) (float64, error) {
select {
case <-ctx.Done():
return 0, ctx.Err()
return DiskCapacity{}, ctx.Err()
case <-timer.C:
return 0, fmt.Errorf("disk usage timed out for %q", path)
return DiskCapacity{}, fmt.Errorf("disk usage timed out for %q", path)
case res := <-result:
if res.err != nil {
return 0, fmt.Errorf("GetDiskFreeSpaceEx %q: %w", path, res.err)
return DiskCapacity{}, fmt.Errorf("GetDiskFreeSpaceEx %q: %w", path, res.err)
}
return diskPercentFromBytes(res.totalBytes, res.freeBytes)
return diskCapacityFromBytes(res.totalBytes, res.freeBytes)
}
}
func diskPercentFromBytes(total, free uint64) (float64, error) {
if total == 0 {
return 0, errors.New("disk total is zero")
capacity, err := diskCapacityFromBytes(total, free)
if err != nil {
return 0, err
}
return (1 - float64(free)/float64(total)) * 100, nil
return capacity.UsedPercent, nil
}
@@ -46,6 +46,22 @@ type Summary struct {
Docker any `json:"docker"`
}
type DiskCapacity struct {
Path string `json:"path"`
TotalBytes uint64 `json:"total_bytes"`
UsedBytes uint64 `json:"used_bytes"`
AvailableBytes uint64 `json:"available_bytes"`
UsedPercent float64 `json:"used_percent"`
Available bool `json:"available"`
Warning string `json:"warning,omitempty"`
}
type DiskCapacityReader func(context.Context, string) (DiskCapacity, error)
func (r DiskCapacityReader) ReadDiskCapacity(ctx context.Context, path string) (DiskCapacity, error) {
return r(ctx, path)
}
type QuarantineSummary struct {
Count int `json:"count" db:"count"`
SizeBytes int64 `json:"size_bytes" db:"size_bytes"`
@@ -68,6 +84,8 @@ type HandlerConfig struct {
Runs RunLister
Quarantine QuarantineLister
Overview OverviewReader
DiskCapacity DiskCapacityReader
DiskPath string
Mutations Mutations
OnSettingsChanged func(StorageMaintenanceSettings)
LogError func(string, error)
@@ -89,6 +107,7 @@ func (h *Handler) logError(message string, err error) {
func RegisterRoutes(group *gin.RouterGroup, handler *Handler) {
group.GET("/storage", handler.getStorage)
group.GET("/storage/disk", handler.getStorageDisk)
group.GET("/storage/settings", handler.getStorageSettings)
group.PATCH("/storage/settings", handler.patchSettings)
group.POST("/storage/go-cache/adopt", handler.adoptGoCache)
@@ -101,6 +120,25 @@ func RegisterRoutes(group *gin.RouterGroup, handler *Handler) {
group.DELETE("/storage/quarantine/:id", handler.deleteQuarantine)
}
func (h *Handler) getStorageDisk(c *gin.Context) {
result := DiskCapacity{Path: h.config.DiskPath}
if h.config.DiskCapacity == nil {
result.Warning = "disk usage unavailable"
c.JSON(http.StatusOK, result)
return
}
capacity, err := h.config.DiskCapacity.ReadDiskCapacity(c.Request.Context(), h.config.DiskPath)
if err != nil {
h.logError("failed to read storage disk capacity", err)
result.Warning = "disk usage unavailable"
c.JSON(http.StatusOK, result)
return
}
capacity.Path = h.config.DiskPath
capacity.Available = true
c.JSON(http.StatusOK, capacity)
}
func (h *Handler) listRuns(c *gin.Context) {
limit, _ := strconv.Atoi(c.DefaultQuery("limit", "20"))
runs, err := h.config.Runs.ListRuns(c.Request.Context(), limit)
@@ -71,6 +71,88 @@ func TestGetStorageReturnsSnapshotAnalyzedAt(t *testing.T) {
}
}
func TestGetStorageDiskReturnsIndependentCapacityResponse(t *testing.T) {
gin.SetMode(gin.TestMode)
router := gin.New()
RegisterRoutes(router.Group("/api/v1/system"), NewHandler(HandlerConfig{}))
response := httptest.NewRecorder()
router.ServeHTTP(response, httptest.NewRequest(http.MethodGet, "/api/v1/system/storage/disk", nil))
if response.Code != http.StatusOK {
t.Fatalf("status = %d, want 200", response.Code)
}
var body struct {
Available bool `json:"available"`
}
if err := json.Unmarshal(response.Body.Bytes(), &body); err != nil {
t.Fatalf("decode response: %v", err)
}
if body.Available {
t.Fatalf("unconfigured disk reader should be unavailable: %s", response.Body.String())
}
}
func TestGetStorageDiskReturnsMeasuredFields(t *testing.T) {
gin.SetMode(gin.TestMode)
router := gin.New()
RegisterRoutes(router.Group("/api/v1/system"), NewHandler(HandlerConfig{
DiskPath: "/data",
DiskCapacity: func(context.Context, string) (DiskCapacity, error) {
return DiskCapacity{
TotalBytes: 1000, UsedBytes: 750, AvailableBytes: 250, UsedPercent: 75,
}, nil
},
}))
response := httptest.NewRecorder()
router.ServeHTTP(response, httptest.NewRequest(http.MethodGet, "/api/v1/system/storage/disk", nil))
if response.Code != http.StatusOK {
t.Fatalf("status = %d, want 200", response.Code)
}
var body DiskCapacity
if err := json.Unmarshal(response.Body.Bytes(), &body); err != nil {
t.Fatalf("decode response: %v", err)
}
want := DiskCapacity{
Path: "/data", TotalBytes: 1000, UsedBytes: 750, AvailableBytes: 250, UsedPercent: 75, Available: true,
}
if body != want {
t.Fatalf("disk response = %#v, want %#v", body, want)
}
}
func TestGetStorageDiskLogsReaderErrorsAndReturnsUnavailable(t *testing.T) {
gin.SetMode(gin.TestMode)
var loggedMessage string
router := gin.New()
RegisterRoutes(router.Group("/api/v1/system"), NewHandler(HandlerConfig{
DiskPath: "/data",
DiskCapacity: func(context.Context, string) (DiskCapacity, error) {
return DiskCapacity{}, errors.New("statfs failed")
},
LogError: func(message string, _ error) { loggedMessage = message },
}))
response := httptest.NewRecorder()
router.ServeHTTP(response, httptest.NewRequest(http.MethodGet, "/api/v1/system/storage/disk", nil))
if response.Code != http.StatusOK {
t.Fatalf("status = %d, want 200", response.Code)
}
if loggedMessage != "failed to read storage disk capacity" {
t.Fatalf("logged message = %q", loggedMessage)
}
var body DiskCapacity
if err := json.Unmarshal(response.Body.Bytes(), &body); err != nil {
t.Fatalf("decode response: %v", err)
}
if body.Available || body.Warning == "" {
t.Fatalf("error response = %#v, want unavailable warning", body)
}
}
func TestGetStorageSettingsReturnsPolicyWithoutOverviewScan(t *testing.T) {
gin.SetMode(gin.TestMode)
settings := DefaultSettings()
@@ -2,11 +2,13 @@ package storage
import (
"context"
"encoding/json"
"errors"
"fmt"
"math"
"path/filepath"
"reflect"
"strings"
"testing"
"github.com/jmoiron/sqlx"
@@ -16,6 +18,16 @@ import (
systemsettings "github.com/kandev/kandev/internal/system/settings"
)
func TestDefaultSettingsDisablesWorkspaceDependencyCleanup(t *testing.T) {
raw, err := json.Marshal(DefaultSettings())
if err != nil {
t.Fatalf("marshal defaults: %v", err)
}
if !strings.Contains(string(raw), `"dependency_cleanup_enabled":false`) {
t.Fatalf("defaults = %s, want dependency cleanup disabled", raw)
}
}
func TestSettingsStoreMissingUsesDisabledDefaults(t *testing.T) {
store, _ := newTestStores(t)
@@ -29,7 +41,7 @@ func TestSettingsStoreMissingUsesDisabledDefaults(t *testing.T) {
IdleForMinutes: 10,
OrphanGraceHours: 168,
QuarantineRetentionHours: 168,
Workspaces: ResourceSettings{Enabled: true},
Workspaces: WorkspaceSettings{Enabled: true},
KandevContainers: ResourceSettings{Enabled: true},
GoCache: GoCacheSettings{
Enabled: false,
+15 -10
View File
@@ -30,6 +30,11 @@ type ResourceSettings struct {
Enabled bool `json:"enabled"`
}
type WorkspaceSettings struct {
Enabled bool `json:"enabled"`
DependencyCleanupEnabled bool `json:"dependency_cleanup_enabled"`
}
type GoCacheSettings struct {
Enabled bool `json:"enabled"`
MaxBytes int64 `json:"max_bytes"`
@@ -46,15 +51,15 @@ type DockerSettings struct {
}
type StorageMaintenanceSettings struct {
Enabled bool `json:"enabled"`
CheckIntervalHours int `json:"check_interval_hours"`
IdleForMinutes int `json:"idle_for_minutes"`
OrphanGraceHours int `json:"orphan_grace_hours"`
QuarantineRetentionHours int `json:"quarantine_retention_hours"`
Workspaces ResourceSettings `json:"workspaces"`
KandevContainers ResourceSettings `json:"kandev_containers"`
GoCache GoCacheSettings `json:"go_cache"`
Docker DockerSettings `json:"docker"`
Enabled bool `json:"enabled"`
CheckIntervalHours int `json:"check_interval_hours"`
IdleForMinutes int `json:"idle_for_minutes"`
OrphanGraceHours int `json:"orphan_grace_hours"`
QuarantineRetentionHours int `json:"quarantine_retention_hours"`
Workspaces WorkspaceSettings `json:"workspaces"`
KandevContainers ResourceSettings `json:"kandev_containers"`
GoCache GoCacheSettings `json:"go_cache"`
Docker DockerSettings `json:"docker"`
}
func DefaultSettings() StorageMaintenanceSettings {
@@ -63,7 +68,7 @@ func DefaultSettings() StorageMaintenanceSettings {
IdleForMinutes: 10,
OrphanGraceHours: 168,
QuarantineRetentionHours: 168,
Workspaces: ResourceSettings{Enabled: true},
Workspaces: WorkspaceSettings{Enabled: true},
KandevContainers: ResourceSettings{Enabled: true},
GoCache: GoCacheSettings{
MaxBytes: 16106127360,
@@ -0,0 +1,379 @@
package workspaces
import (
"context"
"errors"
"fmt"
"io/fs"
"os"
"path/filepath"
"sort"
"github.com/kandev/kandev/internal/system/storage"
)
var dependencyDirectoryAllowlist = []string{
"node_modules",
"bower_components",
".pnpm-store",
".yarn/cache",
".yarn/unplugged",
".venv",
"venv",
".tox",
".nox",
"__pypackages__",
"Pods",
".gradle",
}
var dependencyDirectoryNames = map[string]struct{}{
"node_modules": {},
"bower_components": {},
".pnpm-store": {},
".venv": {},
"venv": {},
".tox": {},
".nox": {},
"__pypackages__": {},
"Pods": {},
".gradle": {},
}
var dependencyTraversalExclusions = map[string]struct{}{
"vendor": {},
"target": {},
"build": {},
"dist": {},
".cache": {},
".git": {},
}
// DependencyDirectoryAllowlist returns the exact directory patterns that dependency cleanup
// may remove. The returned slice is independent of the provider's internal list.
func DependencyDirectoryAllowlist() []string {
return append([]string(nil), dependencyDirectoryAllowlist...)
}
func (p *Provider) CleanupDependencies(ctx context.Context) (DependencyCleanupResult, error) {
result := DependencyCleanupResult{}
tasksRoot, trashTasks, err := p.roots()
if err != nil {
return result, err
}
inventory, err := p.loadInventory(ctx)
if err != nil {
return result, err
}
if inventory.KnownTaskIDs == nil || inventory.ArchivedTaskIDs == nil {
return result, ErrInventoryIncomplete
}
protected, err := buildProtectedSet(tasksRoot, inventory)
if err != nil {
return result, err
}
roots, warnings, err := discoverTaskRoots(tasksRoot)
if err != nil {
return result, err
}
result.Warnings = append(result.Warnings, warnings...)
for _, root := range roots {
if err := ctx.Err(); err != nil {
return result, err
}
if _, keep := protected[root.path]; keep || !dependencyEligible(root.owner, inventory) {
continue
}
marked, err := dependencyWorkspaceMarker(root.path, root.owner)
if err != nil {
result.Warnings = append(result.Warnings, err.Error())
continue
}
if !marked {
continue
}
workspaceResult, err := p.cleanupDependencyWorkspace(ctx, tasksRoot, trashTasks, root)
if err != nil {
return result, err
}
result.Directories += workspaceResult.Directories
result.ReclaimedBytes += workspaceResult.ReclaimedBytes
result.Workspaces += workspaceResult.Workspaces
result.Warnings = append(result.Warnings, workspaceResult.Warnings...)
}
return result, nil
}
func (p *Provider) cleanupDependencyWorkspace(
ctx context.Context,
tasksRoot, trashTasks string,
root candidate,
) (DependencyCleanupResult, error) {
result := DependencyCleanupResult{}
targets, err := findDependencyTargets(ctx, root.path)
if err != nil {
if isDependencyCleanupContextError(err) {
return result, err
}
result.Warnings = append(result.Warnings,
fmt.Sprintf("inspect workspace dependencies %s: %v", root.path, err))
return result, nil
}
inventory, err := p.loadInventory(ctx)
if err != nil {
return result, err
}
protected, err := buildProtectedSet(tasksRoot, inventory)
if err != nil {
return result, err
}
for _, target := range targets {
if err := ctx.Err(); err != nil {
return result, err
}
size, warning, err := p.cleanupDependencyTarget(
ctx, tasksRoot, trashTasks, root, target, inventory, protected,
)
if err != nil {
if isDependencyCleanupContextError(err) {
return result, err
}
result.Warnings = append(result.Warnings, err.Error())
continue
}
if warning != "" {
result.Warnings = append(result.Warnings, warning)
continue
}
result.Directories++
result.ReclaimedBytes += size
}
if result.Directories > 0 {
result.Workspaces = 1
}
return result, nil
}
func (p *Provider) cleanupDependencyTarget(
ctx context.Context,
tasksRoot, trashTasks string,
root candidate,
target string,
inventory Inventory,
protected map[string]struct{},
) (int64, string, error) {
valid, warning, err := revalidateDependencyTarget(
ctx, tasksRoot, trashTasks, root, target, inventory, protected,
)
if err != nil || !valid {
return 0, warning, err
}
size, err := dependencyDirectorySize(ctx, target)
if err != nil {
if isDependencyCleanupContextError(err) {
return 0, "", err
}
return 0, "", fmt.Errorf("measure dependency directory %s: %w", target, err)
}
if err := removeDependencyDirectory(ctx, root.path, target); err != nil {
return 0, "", fmt.Errorf("remove dependency directory %s: %w", target, err)
}
return size, "", nil
}
func isDependencyCleanupContextError(err error) bool {
return errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded)
}
func (p *Provider) loadInventory(ctx context.Context) (Inventory, error) {
if p.config.Inventory == nil {
return Inventory{}, ErrInventoryIncomplete
}
inventory, err := p.config.Inventory.LoadWorkspaceInventory(ctx)
if err != nil {
return Inventory{}, fmt.Errorf("load authoritative workspace inventory: %w", err)
}
if !inventory.Complete {
return Inventory{}, ErrInventoryIncomplete
}
return inventory, nil
}
func dependencyEligible(owner OwnershipMarker, inventory Inventory) bool {
if owner.TaskID == "" {
return false
}
if _, archived := inventory.ArchivedTaskIDs[owner.TaskID]; archived {
return true
}
_, known := inventory.KnownTaskIDs[owner.TaskID]
return !known
}
func dependencyWorkspaceMarker(path string, expected OwnershipMarker) (bool, error) {
owner, marked, err := readOwnershipMarker(path)
if err != nil {
return false, fmt.Errorf("inspect workspace ownership marker %s: %w", path, err)
}
if !marked {
return false, nil
}
if owner.TaskID != expected.TaskID || owner.TaskDirName != expected.TaskDirName ||
owner.LayoutVersion != expected.LayoutVersion {
return false, fmt.Errorf("workspace ownership changed while preparing dependency cleanup: %s", path)
}
return true, nil
}
func findDependencyTargets(ctx context.Context, root string) ([]string, error) {
targets := make([]string, 0)
err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
if err := ctx.Err(); err != nil {
return err
}
if walkErr != nil {
return walkErr
}
if entry.Type()&os.ModeSymlink != 0 {
if entry.IsDir() {
return filepath.SkipDir
}
return nil
}
if path != root && entry.IsDir() {
if _, excluded := dependencyTraversalExclusions[entry.Name()]; excluded {
return filepath.SkipDir
}
relative, err := filepath.Rel(root, path)
if err != nil {
return err
}
if isDependencyTarget(relative, entry.Name()) {
targets = append(targets, path)
return filepath.SkipDir
}
}
return nil
})
if err != nil {
return nil, err
}
sort.Strings(targets)
return targets, nil
}
func isDependencyTarget(relative, name string) bool {
if _, allowed := dependencyDirectoryNames[name]; allowed {
return true
}
parent := filepath.Base(filepath.Dir(relative))
return parent == ".yarn" && (name == "cache" || name == "unplugged")
}
func revalidateDependencyTarget(
ctx context.Context,
tasksRoot, trashTasks string,
root candidate,
target string,
inventory Inventory,
protected map[string]struct{},
) (bool, string, error) {
if err := ctx.Err(); err != nil {
return false, "", err
}
valid, warning, err := validateDependencyTargetPath(tasksRoot, trashTasks, root, target)
if err != nil || !valid {
return valid, warning, err
}
valid, warning, err = validateDependencyDirectories(root.path, target)
if err != nil || !valid {
return valid, warning, err
}
owner, err := validateDependencyWorkspaceMarker(root)
if err != nil {
return false, "", err
}
if owner == nil {
return false, fmt.Sprintf("skip workspace whose ownership changed: %s", root.path), nil
}
if _, isProtected := protected[root.path]; isProtected || !dependencyEligible(*owner, inventory) {
return false, fmt.Sprintf("skip protected or active workspace: %s", root.path), nil
}
return true, "", nil
}
func validateDependencyTargetPath(
tasksRoot, trashTasks string,
root candidate,
target string,
) (bool, string, error) {
if !pathContains(root.path, target) || target == root.path {
return false, fmt.Sprintf("skip dependency path outside workspace: %s", target), nil
}
anchor, err := storage.CommonPath(tasksRoot, trashTasks)
if err != nil {
return false, "", err
}
if err := storage.ValidateNoSymlinkPath(anchor, root.path); err != nil {
return false, fmt.Sprintf("skip workspace with unsafe path %s: %v", root.path, err), nil
}
if err := storage.ValidateNoSymlinkPath(anchor, target); err != nil {
return false, fmt.Sprintf("skip dependency path with unsafe path %s: %v", target, err), nil
}
return true, "", nil
}
func validateDependencyDirectories(root, target string) (bool, string, error) {
rootInfo, err := os.Lstat(root)
if err != nil {
return false, "", err
}
targetInfo, err := os.Lstat(target)
if err != nil {
return false, "", err
}
if rootInfo.Mode()&os.ModeSymlink != 0 || !rootInfo.IsDir() ||
targetInfo.Mode()&os.ModeSymlink != 0 || !targetInfo.IsDir() {
return false, fmt.Sprintf("skip dependency path that is not a real directory: %s", target), nil
}
return true, "", nil
}
func validateDependencyWorkspaceMarker(root candidate) (*OwnershipMarker, error) {
owner, marked, err := readOwnershipMarker(root.path)
if err != nil {
return nil, err
}
if !marked || owner.TaskID != root.owner.TaskID || owner.TaskDirName != root.owner.TaskDirName ||
owner.LayoutVersion != root.owner.LayoutVersion {
return nil, nil
}
return &owner, nil
}
func dependencyDirectorySize(ctx context.Context, root string) (int64, error) {
var size int64
err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
if err := ctx.Err(); err != nil {
return err
}
if walkErr != nil {
return walkErr
}
if entry.Type()&os.ModeSymlink != 0 {
if entry.IsDir() {
return filepath.SkipDir
}
return nil
}
if entry.Type().IsRegular() {
info, err := entry.Info()
if err != nil {
return err
}
size += info.Size()
}
return nil
})
return size, err
}
@@ -0,0 +1,50 @@
//go:build !windows
package workspaces
import (
"context"
"os"
"path/filepath"
"testing"
)
func TestRemoveDependencyDirectoryDoesNotFollowWorkspaceReplacement(t *testing.T) {
parent := t.TempDir()
root := filepath.Join(parent, "workspace")
external := filepath.Join(parent, "external")
if err := os.MkdirAll(filepath.Join(root, "node_modules"), 0o755); err != nil {
t.Fatal(err)
}
if err := os.MkdirAll(filepath.Join(external, "node_modules"), 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(root, "node_modules", "owned.txt"), []byte("owned"), 0o600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(external, "node_modules", "external.txt"), []byte("external"), 0o600); err != nil {
t.Fatal(err)
}
originalRoot := root + ".original"
err := removeDependencyDirectoryWithHook(
context.Background(), root, filepath.Join(root, "node_modules"),
func() {
if err := os.Rename(root, originalRoot); err != nil {
t.Fatalf("rename workspace: %v", err)
}
if err := os.Symlink(external, root); err != nil {
t.Fatalf("replace workspace with symlink: %v", err)
}
},
)
if err != nil {
t.Fatalf("removeDependencyDirectory: %v", err)
}
if _, err := os.Stat(filepath.Join(external, "node_modules", "external.txt")); err != nil {
t.Fatalf("external payload changed: %v", err)
}
if _, err := os.Stat(filepath.Join(originalRoot, "node_modules")); !os.IsNotExist(err) {
t.Fatalf("original dependency directory still exists: %v", err)
}
}
@@ -0,0 +1,269 @@
package workspaces
import (
"context"
"errors"
"os"
"path/filepath"
"reflect"
"testing"
"time"
"github.com/kandev/kandev/internal/system/storage"
)
func TestDependencyDirectoryAllowlistIsExactAndReturnedByCopy(t *testing.T) {
want := []string{
"node_modules", "bower_components", ".pnpm-store", ".yarn/cache", ".yarn/unplugged",
".venv", "venv", ".tox", ".nox", "__pypackages__", "Pods", ".gradle",
}
got := DependencyDirectoryAllowlist()
if !reflect.DeepEqual(got, want) {
t.Fatalf("allowlist = %#v, want %#v", got, want)
}
got[0] = "mutated"
if DependencyDirectoryAllowlist()[0] != want[0] {
t.Fatal("allowlist exposed its internal storage")
}
}
func TestCleanupDependenciesOnlyRemovesAllowlistedDirectoriesFromArchivedAndDeletedWorkspaces(t *testing.T) {
provider, tasksRoot, inventory, _ := newDependencyProviderFixture(t)
archived := createDependencyWorkspace(t, tasksRoot, "archived-task_abc", "archived-task")
deleted := createDependencyWorkspace(t, tasksRoot, "deleted-task_def", "deleted-task")
active := createDependencyWorkspace(t, tasksRoot, "active-task_ghi", "active-task")
inventory.inventory.WorktreePaths = []string{filepath.Join(active, "repo")}
for _, root := range []string{archived, deleted, active} {
writeDependencyFixture(t, root)
}
result, err := provider.CleanupDependencies(context.Background())
if err != nil {
t.Fatalf("CleanupDependencies: %v", err)
}
wantDirectories := (len(DependencyDirectoryAllowlist()) + 1) * 2
if result.Directories != wantDirectories {
t.Fatalf("directories = %d, want %d; result=%#v", result.Directories, wantDirectories, result)
}
if result.Workspaces != 2 {
t.Fatalf("workspaces = %d, want 2; result=%#v", result.Workspaces, result)
}
if result.ReclaimedBytes != int64(wantDirectories*4) {
t.Fatalf("reclaimed bytes = %d, want %d", result.ReclaimedBytes, wantDirectories*4)
}
for _, root := range []string{archived, deleted} {
for _, relative := range DependencyDirectoryAllowlist() {
assertDependencyRemoved(t, root, filepath.FromSlash(relative))
}
assertDependencyRemoved(t, root, filepath.Join("src", "node_modules"))
assertDependencyKept(t, root, filepath.Join("vendor", "node_modules"))
assertDependencyKept(t, root, filepath.Join("target", "node_modules"))
assertDependencyKept(t, root, filepath.Join("build", "node_modules"))
assertDependencyKept(t, root, filepath.Join(".cache", "node_modules"))
assertDependencyKept(t, root, filepath.Join(".git", "node_modules"))
assertDependencyKept(t, root, "source.txt")
}
for _, root := range []string{active} {
for _, relative := range DependencyDirectoryAllowlist() {
assertDependencyKept(t, root, filepath.FromSlash(relative))
}
}
}
func TestCleanupDependenciesSkipsSymlinkTargetsAndExternalPayloads(t *testing.T) {
provider, tasksRoot, _, _ := newDependencyProviderFixture(t)
root := createDependencyWorkspace(t, tasksRoot, "symlink-task_abc", "archived-task")
external := t.TempDir()
externalFile := filepath.Join(external, "keep.txt")
if err := os.WriteFile(externalFile, []byte("keep"), 0o600); err != nil {
t.Fatal(err)
}
if err := os.Symlink(external, filepath.Join(root, "node_modules")); err != nil {
t.Fatalf("symlink dependency: %v", err)
}
result, err := provider.CleanupDependencies(context.Background())
if err != nil {
t.Fatalf("CleanupDependencies: %v", err)
}
if result.Directories != 0 {
t.Fatalf("directories = %d, want 0", result.Directories)
}
assertDependencyKept(t, root, "node_modules")
if _, err := os.Stat(externalFile); err != nil {
t.Fatalf("external symlink payload changed: %v", err)
}
}
func TestCleanupDependenciesFailsClosedWhenEligibilityInventoryIsMissing(t *testing.T) {
provider, tasksRoot, store := newProviderFixture(t, Inventory{Complete: true}, nil)
root := createDependencyWorkspace(t, tasksRoot, "missing-state-task_abc", "missing-state-task")
writeDependencyDirectory(t, filepath.Join(root, "node_modules"), "keep")
result, err := provider.CleanupDependencies(context.Background())
if err == nil {
t.Fatal("CleanupDependencies succeeded without task eligibility inventory")
}
if !errors.Is(err, ErrInventoryIncomplete) {
t.Fatalf("error = %v, want ErrInventoryIncomplete", err)
}
if result.Directories != 0 || len(store.entries) != 0 {
t.Fatalf("cleanup mutated storage: result=%#v entries=%d", result, len(store.entries))
}
assertDependencyKept(t, root, "node_modules")
}
func TestCleanupDependenciesHonorsCancellationBeforeMutation(t *testing.T) {
provider, tasksRoot, _, _ := newDependencyProviderFixture(t)
root := createDependencyWorkspace(t, tasksRoot, "cancelled-task_abc", "deleted-task")
writeDependencyDirectory(t, filepath.Join(root, "node_modules"), "keep")
ctx, cancel := context.WithCancel(context.Background())
cancel()
result, err := provider.CleanupDependencies(ctx)
if !errors.Is(err, context.Canceled) {
t.Fatalf("error = %v, want context.Canceled", err)
}
if result.Directories != 0 {
t.Fatalf("directories = %d, want 0", result.Directories)
}
assertDependencyKept(t, root, "node_modules")
}
func TestCleanupDependenciesPreservesWorkspaceForRestore(t *testing.T) {
provider, tasksRoot, _, store := newDependencyProviderFixture(t)
root := createDependencyWorkspace(t, tasksRoot, "restore-task_abc", "archived-task")
writeDependencyDirectory(t, filepath.Join(root, "node_modules"), "remove")
if err := os.WriteFile(filepath.Join(root, "source.txt"), []byte("source"), 0o600); err != nil {
t.Fatal(err)
}
old := time.Date(2026, time.July, 1, 0, 0, 0, 0, time.UTC)
if err := os.Chtimes(root, old, old); err != nil {
t.Fatalf("Chtimes: %v", err)
}
if result, err := provider.CleanupDependencies(context.Background()); err != nil || result.Directories != 1 {
t.Fatalf("CleanupDependencies result=%#v err=%v", result, err)
}
if err := os.Chtimes(root, old, old); err != nil {
t.Fatalf("Chtimes after dependency cleanup: %v", err)
}
cleanupResult, err := provider.Cleanup(context.Background())
if err != nil {
t.Fatalf("Cleanup: %v", err)
}
if cleanupResult.Candidates != 1 || cleanupResult.Quarantined != 1 {
t.Fatalf("Cleanup result=%#v, want one quarantined workspace", cleanupResult)
}
if len(store.order) != 1 {
t.Fatalf("quarantine entries = %d, want 1", len(store.order))
}
entry := store.entries[store.order[0]]
if _, err := provider.Restore(context.Background(), entry.ID); err != nil {
t.Fatalf("Restore: %v", err)
}
if _, err := os.Stat(filepath.Join(root, "source.txt")); err != nil {
t.Fatalf("restored source: %v", err)
}
if _, err := os.Lstat(filepath.Join(root, "node_modules")); !os.IsNotExist(err) {
t.Fatalf("pruned dependency restored unexpectedly: %v", err)
}
owner, marked, err := readOwnershipMarker(root)
if err != nil || !marked || owner.TaskID != "archived-task" {
t.Fatalf("restored ownership marker=%#v marked=%v err=%v", owner, marked, err)
}
if store.entries[entry.ID].State != storage.QuarantineStateRestored {
t.Fatalf("restore state = %q, want %q", store.entries[entry.ID].State, storage.QuarantineStateRestored)
}
}
func newDependencyProviderFixture(t *testing.T) (*Provider, string, *dependencyInventorySource, *fakeQuarantineStore) {
t.Helper()
home := t.TempDir()
tasksRoot := filepath.Join(home, "tasks")
if err := os.MkdirAll(tasksRoot, 0o755); err != nil {
t.Fatal(err)
}
store := newFakeQuarantineStore()
known := map[string]struct{}{"archived-task": {}}
archived := map[string]struct{}{"archived-task": {}}
inventory := &Inventory{
Complete: true, KnownTaskIDs: known, ArchivedTaskIDs: archived,
}
source := &dependencyInventorySource{inventory: *inventory}
provider := New(Config{
TasksRoot: tasksRoot, TrashRoot: filepath.Join(home, "trash"), Store: store,
Inventory: source, GracePeriod: 7 * 24 * time.Hour,
Now: func() time.Time { return time.Date(2026, time.July, 14, 0, 0, 0, 0, time.UTC) },
})
return provider, tasksRoot, source, store
}
type dependencyInventorySource struct{ inventory Inventory }
func (s *dependencyInventorySource) LoadWorkspaceInventory(context.Context) (Inventory, error) {
return s.inventory, nil
}
func createDependencyWorkspace(t *testing.T, tasksRoot, relative, taskID string) string {
t.Helper()
root := filepath.Join(tasksRoot, relative)
if err := os.MkdirAll(root, 0o755); err != nil {
t.Fatal(err)
}
if err := WriteOwnershipMarker(root, OwnershipMarker{
TaskID: taskID, TaskDirName: relative, LayoutVersion: LayoutVersionSemantic,
}); err != nil {
t.Fatal(err)
}
old := time.Date(2026, time.July, 1, 0, 0, 0, 0, time.UTC)
if err := os.Chtimes(root, old, old); err != nil {
t.Fatal(err)
}
return root
}
func writeDependencyFixture(t *testing.T, root string) {
t.Helper()
for _, relative := range DependencyDirectoryAllowlist() {
writeDependencyDirectory(t, filepath.Join(root, filepath.FromSlash(relative)), "keep")
}
for _, relative := range []string{
filepath.Join("src", "node_modules"), filepath.Join("vendor", "node_modules"),
filepath.Join("target", "node_modules"), filepath.Join("build", "node_modules"),
filepath.Join("dist", "node_modules"), filepath.Join(".cache", "node_modules"),
filepath.Join(".git", "node_modules"),
} {
writeDependencyDirectory(t, filepath.Join(root, relative), "keep")
}
if err := os.WriteFile(filepath.Join(root, "source.txt"), []byte("source"), 0o600); err != nil {
t.Fatal(err)
}
}
func writeDependencyDirectory(t *testing.T, root, contents string) {
t.Helper()
if err := os.MkdirAll(root, 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(root, "payload.txt"), []byte(contents), 0o600); err != nil {
t.Fatal(err)
}
}
func assertDependencyRemoved(t *testing.T, root, relative string) {
t.Helper()
if _, err := os.Lstat(filepath.Join(root, relative)); !os.IsNotExist(err) {
t.Fatalf("dependency %s still exists or returned unexpected error: %v", relative, err)
}
}
func assertDependencyKept(t *testing.T, root, relative string) {
t.Helper()
if _, err := os.Lstat(filepath.Join(root, relative)); err != nil {
t.Fatalf("dependency %s was removed: %v", relative, err)
}
}
@@ -0,0 +1,215 @@
//go:build !windows
package workspaces
import (
"context"
"errors"
"fmt"
"io"
"os"
"path/filepath"
"strings"
"golang.org/x/sys/unix"
)
const dependencyDirectoryOpenFlags = unix.O_RDONLY | unix.O_DIRECTORY | unix.O_NOFOLLOW | unix.O_CLOEXEC
// removeDependencyDirectory opens every path component with O_NOFOLLOW and removes
// entries through the resulting directory descriptors. This keeps a concurrent
// rename or symlink replacement from redirecting deletion outside the workspace.
func removeDependencyDirectory(ctx context.Context, root, target string) error {
return removeDependencyDirectoryWithHook(ctx, root, target, nil)
}
// removeDependencyDirectoryWithHook is also used by the race regression test to
// replace the validated path after its descriptors have been opened.
func removeDependencyDirectoryWithHook(
ctx context.Context,
root, target string,
afterOpen func(),
) error {
if err := ctx.Err(); err != nil {
return err
}
relative, err := dependencyRelativePath(root, target)
if err != nil {
return err
}
rootFD, err := openDependencyDirectoryPath(root)
if err != nil {
return fmt.Errorf("open dependency workspace root: %w", err)
}
defer func() { _ = unix.Close(rootFD) }()
parentFD, targetFD, err := openDependencyTarget(rootFD, relative)
if err != nil {
return err
}
defer func() { _ = unix.Close(targetFD) }()
if parentFD != rootFD {
defer func() { _ = unix.Close(parentFD) }()
}
if afterOpen != nil {
afterOpen()
}
if err := removeUnixDependencyContents(ctx, targetFD); err != nil {
return err
}
if err := ctx.Err(); err != nil {
return err
}
// Unlinking through the parent descriptor with AT_REMOVEDIR cannot follow a
// replacement symlink. The target's contents were removed through targetFD.
if err := unix.Unlinkat(parentFD, filepath.Base(filepath.Clean(relative)), unix.AT_REMOVEDIR); err != nil && !errors.Is(err, unix.ENOENT) {
return err
}
return nil
}
func dependencyRelativePath(root, target string) (string, error) {
root = filepath.Clean(root)
target = filepath.Clean(target)
if !filepath.IsAbs(root) || !filepath.IsAbs(target) {
return "", fmt.Errorf("dependency paths must be absolute")
}
relative, err := filepath.Rel(root, target)
if err != nil {
return "", fmt.Errorf("resolve dependency path: %w", err)
}
if relative == "." || filepath.IsAbs(relative) {
return "", fmt.Errorf("dependency target must be below workspace root")
}
for _, part := range strings.Split(filepath.ToSlash(relative), "/") {
if part == "" || part == "." || part == ".." {
return "", fmt.Errorf("dependency target contains an unsafe path component")
}
}
return relative, nil
}
func openDependencyDirectoryPath(path string) (int, error) {
if !filepath.IsAbs(path) {
return -1, fmt.Errorf("dependency workspace root must be absolute")
}
fd, err := unix.Open(string(filepath.Separator), dependencyDirectoryOpenFlags, 0)
if err != nil {
return -1, err
}
for _, part := range dependencyAbsolutePathComponents(path) {
next, err := unix.Openat(fd, part, dependencyDirectoryOpenFlags, 0)
if err != nil {
_ = unix.Close(fd)
return -1, err
}
_ = unix.Close(fd)
fd = next
}
return fd, nil
}
func dependencyAbsolutePathComponents(path string) []string {
clean := filepath.Clean(path)
trimmed := strings.TrimPrefix(filepath.ToSlash(clean), "/")
if trimmed == "" {
return nil
}
parts := strings.Split(trimmed, "/")
result := make([]string, 0, len(parts))
for _, part := range parts {
if part != "" && part != "." {
result = append(result, part)
}
}
return result
}
func openDependencyTarget(rootFD int, relative string) (parentFD, targetFD int, err error) {
parts := strings.Split(filepath.ToSlash(relative), "/")
parentFD = rootFD
for index, part := range parts {
next, openErr := unix.Openat(parentFD, part, dependencyDirectoryOpenFlags, 0)
if openErr != nil {
if parentFD != rootFD {
_ = unix.Close(parentFD)
}
return -1, -1, openErr
}
if index == len(parts)-1 {
return parentFD, next, nil
}
if parentFD != rootFD {
_ = unix.Close(parentFD)
}
parentFD = next
}
return -1, -1, fmt.Errorf("dependency target is empty")
}
func removeUnixDependencyContents(ctx context.Context, dirFD int) error {
names, err := readUnixDependencyNames(dirFD)
if err != nil {
return err
}
for _, name := range names {
if err := removeUnixDependencyEntry(ctx, dirFD, name); err != nil {
return err
}
}
return nil
}
func readUnixDependencyNames(dirFD int) ([]string, error) {
readFD, err := unix.Dup(dirFD)
if err != nil {
return nil, err
}
dir := os.NewFile(uintptr(readFD), "dependency-directory")
if dir == nil {
_ = unix.Close(readFD)
return nil, fmt.Errorf("open dependency directory descriptor")
}
names, err := dir.Readdirnames(-1)
_ = dir.Close()
if err != nil && !errors.Is(err, io.EOF) {
return nil, err
}
return names, nil
}
func removeUnixDependencyEntry(ctx context.Context, dirFD int, name string) error {
if err := ctx.Err(); err != nil {
return err
}
var stat unix.Stat_t
if err := unix.Fstatat(dirFD, name, &stat, unix.AT_SYMLINK_NOFOLLOW); err != nil {
if errors.Is(err, unix.ENOENT) {
return nil
}
return err
}
if stat.Mode&unix.S_IFMT == unix.S_IFDIR {
return removeUnixDependencySubdirectory(ctx, dirFD, name)
}
if err := unix.Unlinkat(dirFD, name, 0); err != nil && !errors.Is(err, unix.ENOENT) {
return err
}
return nil
}
func removeUnixDependencySubdirectory(ctx context.Context, parentFD int, name string) error {
childFD, err := unix.Openat(parentFD, name, dependencyDirectoryOpenFlags, 0)
if err != nil {
return err
}
err = removeUnixDependencyContents(ctx, childFD)
_ = unix.Close(childFD)
if err != nil {
return err
}
if err := unix.Unlinkat(parentFD, name, unix.AT_REMOVEDIR); err != nil && !errors.Is(err, unix.ENOENT) {
return err
}
return nil
}
@@ -0,0 +1,291 @@
//go:build windows
package workspaces
import (
"context"
"errors"
"fmt"
"io"
"os"
"path/filepath"
"strings"
"unsafe"
"golang.org/x/sys/windows"
)
// Windows uses native handles rooted at the workspace. OBJ_DONT_REPARSE and
// FILE_OPEN_REPARSE_POINT make each component no-follow; deletion is then
// requested on the opened handle rather than by path.
func removeDependencyDirectory(ctx context.Context, root, target string) error {
return removeDependencyDirectoryWithHook(ctx, root, target, nil)
}
func removeDependencyDirectoryWithHook(
ctx context.Context,
root, target string,
afterOpen func(),
) error {
if err := ctx.Err(); err != nil {
return err
}
relative, err := dependencyRelativePath(root, target)
if err != nil {
return err
}
rootHandle, err := openWindowsDependencyDirectoryPath(root)
if err != nil {
return fmt.Errorf("open dependency workspace root: %w", err)
}
defer windows.CloseHandle(rootHandle)
parentHandle, targetHandle, err := openWindowsDependencyTarget(rootHandle, relative)
if err != nil {
return err
}
defer windows.CloseHandle(targetHandle)
if parentHandle != rootHandle {
defer windows.CloseHandle(parentHandle)
}
if afterOpen != nil {
afterOpen()
}
if err := removeWindowsDependencyContents(ctx, targetHandle); err != nil {
return err
}
if err := ctx.Err(); err != nil {
return err
}
return markWindowsDependencyForDelete(targetHandle)
}
func dependencyRelativePath(root, target string) (string, error) {
root = filepath.Clean(root)
target = filepath.Clean(target)
if !filepath.IsAbs(root) || !filepath.IsAbs(target) {
return "", fmt.Errorf("dependency paths must be absolute")
}
relative, err := filepath.Rel(root, target)
if err != nil {
return "", fmt.Errorf("resolve dependency path: %w", err)
}
if relative == "." || filepath.IsAbs(relative) {
return "", fmt.Errorf("dependency target must be below workspace root")
}
for _, part := range strings.FieldsFunc(filepath.Clean(relative), func(r rune) bool { return r == '\\' || r == '/' }) {
if part == "" || part == "." || part == ".." {
return "", fmt.Errorf("dependency target contains an unsafe path component")
}
}
return relative, nil
}
func openWindowsDependencyDirectoryPath(path string) (windows.Handle, error) {
name := windowsDependencyNTPath(path)
handle, err := openWindowsDependencyHandle(0, name, windows.FILE_DIRECTORY_FILE)
if err != nil {
return 0, err
}
return rejectWindowsDependencyReparse(handle)
}
func openWindowsDependencyDirectoryRelative(parent windows.Handle, name string) (windows.Handle, error) {
return openWindowsDependencyHandle(parent, name, windows.FILE_DIRECTORY_FILE)
}
func openWindowsDependencyEntryRelative(parent windows.Handle, name string) (windows.Handle, error) {
return openWindowsDependencyHandle(parent, name, windows.FILE_NON_DIRECTORY_FILE)
}
func openWindowsDependencyHandle(
parent windows.Handle,
name string,
createOption uint32,
) (windows.Handle, error) {
objectName, err := windows.NewNTUnicodeString(name)
if err != nil {
return 0, err
}
objectAttributes := &windows.OBJECT_ATTRIBUTES{
Length: uint32(unsafe.Sizeof(windows.OBJECT_ATTRIBUTES{})),
RootDirectory: parent,
ObjectName: objectName,
Attributes: windows.OBJ_CASE_INSENSITIVE | windows.OBJ_DONT_REPARSE,
}
var ioStatus windows.IO_STATUS_BLOCK
var allocationSize int64
var handle windows.Handle
err = windows.NtCreateFile(
&handle,
windows.FILE_GENERIC_READ|windows.FILE_GENERIC_WRITE|windows.DELETE,
objectAttributes,
&ioStatus,
&allocationSize,
0,
windows.FILE_SHARE_READ|windows.FILE_SHARE_WRITE|windows.FILE_SHARE_DELETE,
windows.FILE_OPEN,
createOption|windows.FILE_OPEN_REPARSE_POINT,
0,
0,
)
if err != nil {
return 0, err
}
return handle, nil
}
func rejectWindowsDependencyReparse(handle windows.Handle) (windows.Handle, error) {
reparse, err := windowsDependencyHandleIsReparsePoint(handle)
if err != nil {
_ = windows.CloseHandle(handle)
return 0, err
}
if reparse {
_ = windows.CloseHandle(handle)
return 0, fmt.Errorf("dependency path is a reparse point")
}
return handle, nil
}
func windowsDependencyNTPath(path string) string {
clean := filepath.Clean(path)
if strings.HasPrefix(clean, `\\?\`) {
return `\??\` + strings.TrimPrefix(clean, `\\?\`)
}
if strings.HasPrefix(clean, `\\`) {
return `\??\UNC\` + strings.TrimPrefix(clean, `\\`)
}
return `\??\` + clean
}
func openWindowsDependencyTarget(rootHandle windows.Handle, relative string) (parent, target windows.Handle, err error) {
parts := strings.FieldsFunc(filepath.Clean(relative), func(r rune) bool { return r == '\\' || r == '/' })
parent = rootHandle
for index, part := range parts {
next, openErr := openWindowsDependencyDirectoryRelative(parent, part)
if openErr != nil {
if parent != rootHandle {
_ = windows.CloseHandle(parent)
}
return 0, 0, openErr
}
if reparse, checkErr := windowsDependencyHandleIsReparsePoint(next); checkErr != nil {
_ = windows.CloseHandle(next)
if parent != rootHandle {
_ = windows.CloseHandle(parent)
}
return 0, 0, checkErr
} else if reparse {
_ = windows.CloseHandle(next)
if parent != rootHandle {
_ = windows.CloseHandle(parent)
}
return 0, 0, fmt.Errorf("dependency path is a reparse point")
}
if index == len(parts)-1 {
return parent, next, nil
}
if parent != rootHandle {
_ = windows.CloseHandle(parent)
}
parent = next
}
return 0, 0, fmt.Errorf("dependency target is empty")
}
func windowsDependencyHandleIsReparsePoint(handle windows.Handle) (bool, error) {
var info windows.ByHandleFileInformation
if err := windows.GetFileInformationByHandle(handle, &info); err != nil {
return false, err
}
return info.FileAttributes&windows.FILE_ATTRIBUTE_REPARSE_POINT != 0, nil
}
func removeWindowsDependencyContents(ctx context.Context, dirHandle windows.Handle) error {
readHandle, err := duplicateWindowsDependencyHandle(dirHandle)
if err != nil {
return err
}
dir := os.NewFile(uintptr(readHandle), "dependency-directory")
if dir == nil {
_ = windows.CloseHandle(readHandle)
return fmt.Errorf("open dependency directory handle")
}
names, err := dir.Readdirnames(-1)
_ = dir.Close()
if err != nil && !errors.Is(err, io.EOF) {
return err
}
for _, name := range names {
if err := ctx.Err(); err != nil {
return err
}
child, dirErr := openWindowsDependencyDirectoryRelative(dirHandle, name)
if dirErr == nil {
reparse, checkErr := windowsDependencyHandleIsReparsePoint(child)
if checkErr != nil {
_ = windows.CloseHandle(child)
return checkErr
}
if reparse {
_ = windows.CloseHandle(child)
continue
}
if err := removeWindowsDependencyContents(ctx, child); err != nil {
_ = windows.CloseHandle(child)
return err
}
err := markWindowsDependencyForDelete(child)
_ = windows.CloseHandle(child)
if err != nil {
return err
}
continue
}
file, fileErr := openWindowsDependencyEntryRelative(dirHandle, name)
if fileErr != nil {
return fmt.Errorf("open dependency entry %s: %w", name, fileErr)
}
reparse, checkErr := windowsDependencyHandleIsReparsePoint(file)
if checkErr != nil {
_ = windows.CloseHandle(file)
return checkErr
}
if reparse {
_ = windows.CloseHandle(file)
continue
}
err = markWindowsDependencyForDelete(file)
_ = windows.CloseHandle(file)
if err != nil {
return err
}
}
return nil
}
func duplicateWindowsDependencyHandle(handle windows.Handle) (windows.Handle, error) {
var duplicate windows.Handle
if err := windows.DuplicateHandle(
windows.CurrentProcess(), handle, windows.CurrentProcess(), &duplicate, 0, false,
windows.DUPLICATE_SAME_ACCESS,
); err != nil {
return 0, err
}
return duplicate, nil
}
func markWindowsDependencyForDelete(handle windows.Handle) error {
info := struct{ Flags uint32 }{
Flags: windows.FILE_DISPOSITION_DELETE |
windows.FILE_DISPOSITION_POSIX_SEMANTICS |
windows.FILE_DISPOSITION_IGNORE_READONLY_ATTRIBUTE,
}
return windows.SetFileInformationByHandle(
handle,
windows.FileDispositionInfoEx,
(*byte)(unsafe.Pointer(&info)),
uint32(unsafe.Sizeof(info)),
)
}
@@ -116,15 +116,9 @@ func (p *Provider) classificationInputs(
if err != nil {
return "", "", nil, nil, nil, err
}
if p.config.Inventory == nil {
return "", "", nil, nil, nil, ErrInventoryIncomplete
}
inventory, err := p.config.Inventory.LoadWorkspaceInventory(ctx)
inventory, err := p.loadInventory(ctx)
if err != nil {
return "", "", nil, nil, nil, fmt.Errorf("load authoritative workspace inventory: %w", err)
}
if !inventory.Complete {
return "", "", nil, nil, nil, ErrInventoryIncomplete
return "", "", nil, nil, nil, err
}
protected, err := buildProtectedSet(tasksRoot, inventory)
if err != nil {
@@ -40,6 +40,8 @@ type Inventory struct {
EnvironmentPaths []string
ExecutionPaths []string
ScratchRoots []ScratchRoot
KnownTaskIDs map[string]struct{}
ArchivedTaskIDs map[string]struct{}
}
type InventorySource interface {
@@ -76,6 +78,13 @@ type CleanupResult struct {
Warnings []string `json:"warnings,omitempty"`
}
type DependencyCleanupResult struct {
Workspaces int `json:"workspaces"`
Directories int `json:"directories"`
ReclaimedBytes int64 `json:"reclaimed_bytes"`
Warnings []string `json:"warnings,omitempty"`
}
type Analysis struct {
TotalBytes int64 `json:"total_bytes"`
ActiveBytes int64 `json:"active_bytes"`
@@ -0,0 +1,54 @@
import { Input } from "@kandev/ui/input";
import { Label } from "@kandev/ui/label";
import { useTranslation } from "react-i18next";
import { StorageActionButton } from "./storage-action-button";
import { StorageSettingHelp } from "./storage-setting-help";
type Props = {
path: string;
setPath: (path: string) => void;
onOpen: () => void;
pending: boolean;
enabled: boolean;
};
export function StorageAdoptionField({ path, setPath, onOpen, pending, enabled }: Props) {
const { t } = useTranslation();
let disabledReason: string | undefined;
if (pending) disabledReason = t("system:storageActionPending");
else if (!enabled) disabledReason = t("system:storageEnableGoCacheFirst");
else if (!path.trim()) disabledReason = t("system:storageEnterCachePathFirst");
const fieldLabel = t("system:storageExternalGoCache");
return (
<div className="min-w-0 space-y-2 pt-3">
<div className="flex items-center gap-1">
<Label htmlFor="storage-adoption-path">{fieldLabel}</Label>
<StorageSettingHelp label={fieldLabel}>
{t("system:storageExternalGoCacheHelp")}
</StorageSettingHelp>
</div>
<p className="text-xs text-muted-foreground">
{t("system:storageExternalGoCacheDescription")}
</p>
<div className="flex min-w-0 flex-col gap-2 sm:flex-row">
<Input
id="storage-adoption-path"
value={path}
disabled={pending || !enabled}
onChange={(event) => setPath(event.target.value)}
placeholder="/root/.cache/go-build"
className="h-11 min-w-0 font-mono"
data-testid="storage-go-cache-adopt-path"
/>
<StorageActionButton
variant="outline"
disabledReason={disabledReason}
onClick={onOpen}
data-testid="storage-go-cache-adopt"
>
{t("system:storageAdoptCache")}
</StorageActionButton>
</div>
</div>
);
}
@@ -0,0 +1,63 @@
import { cleanup, render, screen } from "@testing-library/react";
import { afterEach, describe, expect, it } from "vitest";
import type { StorageDiskCapacityResponse } from "@/lib/types/system";
import { StorageDiskCapacityCard } from "./storage-disk-capacity-card";
afterEach(cleanup);
const disk: StorageDiskCapacityResponse = {
path: "/data",
total_bytes: 100 * 1024 ** 3,
used_bytes: 80 * 1024 ** 3,
available_bytes: 20 * 1024 ** 3,
used_percent: 80,
available: true,
};
describe("StorageDiskCapacityCard", () => {
it("renders the measured percentage, sizes, path, and accessible progress value", () => {
render(<StorageDiskCapacityCard disk={disk} />);
expect(screen.getByTestId("storage-disk-used-percent").textContent).toContain("80%");
expect(screen.getByTestId("storage-disk-capacity-card").getAttribute("data-severity")).toBe(
"warning",
);
expect(screen.getByTestId("storage-disk-capacity-path").textContent).toContain("/data");
expect(screen.getByText("80 GB used")).toBeTruthy();
expect(screen.getByText("20 GB available · 100 GB total")).toBeTruthy();
expect(screen.getByRole("progressbar").getAttribute("aria-valuenow")).toBe("80");
});
it("uses critical styling at exactly 90% full", () => {
render(
<StorageDiskCapacityCard
disk={{
...disk,
used_percent: 90,
used_bytes: 90 * 1024 ** 3,
available_bytes: 10 * 1024 ** 3,
}}
/>,
);
expect(screen.getByTestId("storage-disk-capacity-card").getAttribute("data-severity")).toBe(
"critical",
);
});
it("clamps invalid percentages before rendering the progress bar", () => {
render(<StorageDiskCapacityCard disk={{ ...disk, used_percent: 120 }} />);
expect(screen.getByRole("progressbar").getAttribute("aria-valuenow")).toBe("100");
expect(screen.getByTestId("storage-disk-used-percent").textContent).toContain("100%");
});
it("renders an unavailable state without inventing capacity", () => {
render(
<StorageDiskCapacityCard disk={{ ...disk, available: false, warning: "unavailable" }} />,
);
expect(screen.getByTestId("storage-disk-unavailable")).toBeTruthy();
expect(screen.queryByRole("progressbar")).toBeNull();
});
});
@@ -0,0 +1,170 @@
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@kandev/ui/card";
import { Progress } from "@kandev/ui/progress";
import { Spinner } from "@kandev/ui/spinner";
import { IconDatabase } from "@tabler/icons-react";
import { useTranslation } from "react-i18next";
import { formatNumber } from "@/lib/i18n/formats";
import type { StorageDiskCapacityResponse } from "@/lib/types/system";
import { formatGigabytes } from "./storage-units";
type Props = {
disk: StorageDiskCapacityResponse | null;
loading?: boolean;
error?: string | null;
};
type Severity = "normal" | "warning" | "critical";
function clampPercent(value: number): number {
if (!Number.isFinite(value)) return 0;
return Math.min(100, Math.max(0, value));
}
function severityForPercent(percent: number): Severity {
if (percent >= 90) return "critical";
if (percent >= 80) return "warning";
return "normal";
}
function severityTextClassName(severity: Severity): string {
switch (severity) {
case "critical":
return "text-lg font-semibold text-red-600 dark:text-red-400";
case "warning":
return "text-lg font-semibold text-amber-600 dark:text-amber-400";
default:
return "text-lg font-semibold";
}
}
function severityProgressClassName(severity: Severity): string {
switch (severity) {
case "critical":
return "h-3 [&_[data-slot=progress-indicator]]:bg-red-500";
case "warning":
return "h-3 [&_[data-slot=progress-indicator]]:bg-amber-500";
default:
return "h-3";
}
}
function LoadingDiskCard({ loading, error }: Pick<Props, "loading" | "error">) {
const { t } = useTranslation();
const isLoading = loading ?? true;
return (
<Card data-testid="storage-disk-capacity-card">
<CardContent className="flex items-center gap-2 py-8 text-sm text-muted-foreground">
{isLoading && <Spinner className="size-4" data-testid="storage-disk-spinner" />}
<span>
{isLoading ? t("system:storageDiskLoading") : t("system:storageSectionUnavailable")}
</span>
{error && <span className="break-words text-destructive">{error}</span>}
</CardContent>
</Card>
);
}
function UnavailableDiskCard({ disk }: { disk: StorageDiskCapacityResponse }) {
const { t } = useTranslation();
return (
<Card data-testid="storage-disk-capacity-card">
<CardHeader>
<CardTitle className="flex items-center gap-2 text-base">
<IconDatabase className="size-4" /> {t("system:storageDiskTitle")}
</CardTitle>
<CardDescription>{t("system:storageDiskDescription")}</CardDescription>
</CardHeader>
<CardContent>
<p className="text-sm text-muted-foreground" data-testid="storage-disk-unavailable">
{t("system:storageDiskUnavailable")}
</p>
{disk.path && (
<code className="mt-2 block break-all text-xs text-muted-foreground">{disk.path}</code>
)}
</CardContent>
</Card>
);
}
function AvailableDiskCard({
disk,
loading,
error,
}: {
disk: StorageDiskCapacityResponse;
loading: boolean;
error?: string | null;
}) {
const { t } = useTranslation();
const percent = clampPercent(disk.used_percent);
const severity = severityForPercent(percent);
const percentLabel = formatNumber(percent, { maximumFractionDigits: 1 });
const progressLabel = t("system:storageDiskProgressAria", { percent: percentLabel });
return (
<Card data-testid="storage-disk-capacity-card" data-severity={severity}>
<CardHeader>
<CardTitle className="flex items-center gap-2 text-base">
<IconDatabase className="size-4" /> {t("system:storageDiskTitle")}
{loading && <Spinner className="size-4" data-testid="storage-disk-spinner" />}
</CardTitle>
<CardDescription>{t("system:storageDiskDescription")}</CardDescription>
{error && (
<p className="break-words text-xs text-destructive" data-testid="storage-disk-error">
{t("system:storageSectionUnavailable")}: {error}
</p>
)}
</CardHeader>
<CardContent className="min-w-0 space-y-3">
<div className="flex flex-wrap items-baseline justify-between gap-2">
<span className={severityTextClassName(severity)} data-testid="storage-disk-used-percent">
{t("system:storageDiskUsed", { percent: percentLabel })}
</span>
<span className="text-xs text-muted-foreground">
{t("system:storageDiskUsedSize", { size: formatGigabytes(disk.used_bytes) })}
</span>
</div>
<Progress
value={percent}
aria-label={progressLabel}
aria-valuemin={0}
aria-valuemax={100}
className={severityProgressClassName(severity)}
/>
<div className="flex min-w-0 flex-wrap justify-between gap-x-3 gap-y-1 text-xs text-muted-foreground">
<span>
{t("system:storageDiskCapacitySummary", {
available: formatGigabytes(disk.available_bytes),
total: formatGigabytes(disk.total_bytes),
})}
</span>
</div>
<div className="min-w-0 text-xs text-muted-foreground">
<span>{t("system:storageDiskPath")}: </span>
<code className="break-all" data-testid="storage-disk-capacity-path">
{disk.path}
</code>
</div>
{severity !== "normal" && (
<p
className={
severity === "critical"
? "text-xs text-red-600 dark:text-red-400"
: "text-xs text-amber-600 dark:text-amber-400"
}
data-testid="storage-disk-threshold-warning"
>
{severity === "critical"
? t("system:storageDiskCriticalWarning")
: t("system:storageDiskHighWarning")}
</p>
)}
</CardContent>
</Card>
);
}
export function StorageDiskCapacityCard({ disk, loading, error }: Props) {
if (!disk) return <LoadingDiskCard loading={loading} error={error} />;
if (!disk.available) return <UnavailableDiskCard disk={disk} />;
return <AvailableDiskCard disk={disk} loading={loading ?? false} error={error} />;
}
@@ -31,7 +31,7 @@ const overview = {
idle_for_minutes: 10,
orphan_grace_hours: 168,
quarantine_retention_hours: 168,
workspaces: { enabled: true },
workspaces: { enabled: true, dependency_cleanup_enabled: false },
kandev_containers: { enabled: true },
go_cache: { enabled: false, max_bytes: 16106127360, adopted_path: "" },
docker: {
@@ -13,6 +13,7 @@ import {
import type { StorageMaintenanceSettings as Settings, SystemJob } from "@/lib/types/system";
import { useSettingsSaveContributor } from "../../settings-save-provider";
import { StorageActionButton } from "./storage-action-button";
import { StorageDiskCapacityCard } from "./storage-disk-capacity-card";
import { StorageOverviewCard } from "./storage-overview-card";
import { StoragePolicyCard } from "./storage-policy-card";
import { StorageQuarantineCard } from "./storage-quarantine-card";
@@ -296,6 +297,11 @@ function StoragePrimarySections({
const capabilities = controller.policy?.capabilities ?? controller.overview?.capabilities;
return (
<div className="min-w-0 space-y-4" data-testid="storage-primary-sections">
<StorageDiskCapacityCard
disk={controller.disk}
loading={controller.loading?.disk}
error={controller.sectionErrors?.disk}
/>
<StorageOverviewCard
overview={controller.overview}
settings={savedSettings ?? undefined}
@@ -313,6 +319,7 @@ function StoragePrimarySections({
pending={controlsPending}
onChange={setDraft}
onAdopt={controller.adopt}
onCleanDependencies={() => void controller.runNow(["workspace_dependencies"])}
/>
)}
</div>
@@ -12,7 +12,7 @@ const degradedOverview = {
idle_for_minutes: 10,
orphan_grace_hours: 168,
quarantine_retention_hours: 168,
workspaces: { enabled: true },
workspaces: { enabled: true, dependency_cleanup_enabled: false },
kandev_containers: { enabled: true },
go_cache: { enabled: false, max_bytes: 16106127360, adopted_path: "" },
docker: {
@@ -1,4 +1,4 @@
import { cleanup, fireEvent, render, screen } from "@testing-library/react";
import { cleanup, fireEvent, render, screen, within } from "@testing-library/react";
import { TooltipProvider } from "@kandev/ui/tooltip";
import { afterEach, describe, expect, it, vi } from "vitest";
import type { StorageMaintenanceSettings } from "@/lib/types/system";
@@ -10,7 +10,7 @@ const settings: StorageMaintenanceSettings = {
idle_for_minutes: 10,
orphan_grace_hours: 168,
quarantine_retention_hours: 168,
workspaces: { enabled: true },
workspaces: { enabled: true, dependency_cleanup_enabled: false },
kandev_containers: { enabled: true },
go_cache: { enabled: false, max_bytes: 16106127360, adopted_path: "" },
docker: {
@@ -37,6 +37,7 @@ const testIds = {
dockerBuildCacheUnused: "storage-docker-build-cache-unused-hours",
dockerImagesUnused: "storage-docker-unused-images-hours",
};
const dirtyAttribute = "data-settings-dirty";
const ADOPTION_PATH_TEST_ID = "storage-go-cache-adopt-path";
const ADOPT_BUTTON_TEST_ID = "storage-go-cache-adopt";
@@ -47,6 +48,7 @@ function renderCard(
onChange = vi.fn(),
currentSettings: StorageMaintenanceSettings = settings,
savedSettings: StorageMaintenanceSettings = settings,
onCleanDependencies?: () => void,
) {
render(
<TooltipProvider>
@@ -57,6 +59,7 @@ function renderCard(
pending={pending}
onChange={onChange}
onAdopt={vi.fn()}
onCleanDependencies={onCleanDependencies}
/>
</TooltipProvider>,
);
@@ -161,6 +164,72 @@ describe("External Go cache path", () => {
});
describe("StoragePolicyCard", () => {
it("shows the dependency allowlist and keeps cleanup opt-in", () => {
const onChange = renderCard();
const allowlist = screen.getByTestId("storage-dependency-allowlist");
const expectedDirectories = [
"node_modules",
"bower_components",
".pnpm-store",
".yarn/cache",
".yarn/unplugged",
".venv",
"venv",
".tox",
".nox",
"__pypackages__",
"Pods",
".gradle",
];
expect(
within(allowlist)
.getAllByRole("listitem")
.map((item) => item.textContent?.trim()),
).toEqual(expectedDirectories);
expect(allowlist.textContent).not.toContain("vendor");
const toggle = screen.getByTestId(
"storage-workspace-dependencies-enabled",
) as HTMLButtonElement;
expect(toggle.getAttribute("aria-checked")).toBe("false");
fireEvent.click(toggle);
expect(onChange).toHaveBeenLastCalledWith({
...settings,
workspaces: { ...settings.workspaces, dependency_cleanup_enabled: true },
});
});
it("keeps dependency cleanup enabled when orphan cleanup is toggled", () => {
const currentSettings = {
...settings,
workspaces: { enabled: true, dependency_cleanup_enabled: true },
};
const onChange = renderCard(false, vi.fn(), currentSettings, currentSettings);
fireEvent.click(screen.getByLabelText("Clean orphan task workspaces"));
expect(onChange).toHaveBeenLastCalledWith({
...currentSettings,
workspaces: { ...currentSettings.workspaces, enabled: false },
});
});
it("marks dependency cleanup changes on the workspace policy card", () => {
const currentSettings = {
...settings,
workspaces: { enabled: true, dependency_cleanup_enabled: true },
};
renderCard(false, vi.fn(), currentSettings, settings);
expect(
screen.getByTestId("storage-policy-section-workspaces").getAttribute(dirtyAttribute),
).toBe("true");
expect(
screen.getByTestId("storage-workspace-dependencies-enabled").getAttribute(dirtyAttribute),
).toBe("true");
});
it("edits every Docker cleanup threshold", () => {
const onChange = renderCard();
@@ -201,6 +270,41 @@ describe("StoragePolicyCard", () => {
});
});
describe("StoragePolicyCard dependency action", () => {
it("runs dependency cleanup only when the saved opt-in is enabled", () => {
const onCleanDependencies = vi.fn();
const enabledSettings = {
...settings,
workspaces: { enabled: true, dependency_cleanup_enabled: true },
};
renderCard(false, vi.fn(), enabledSettings, enabledSettings, onCleanDependencies);
const button = screen.getByTestId("storage-clean-workspace-dependencies") as HTMLButtonElement;
expect(button.disabled).toBe(false);
fireEvent.click(button);
expect(onCleanDependencies).toHaveBeenCalledTimes(1);
});
it("disables dependency cleanup while opt-in changes are unsaved or pending", () => {
const onCleanDependencies = vi.fn();
const enabledSettings = {
...settings,
workspaces: { enabled: true, dependency_cleanup_enabled: true },
};
renderCard(false, vi.fn(), enabledSettings, settings, onCleanDependencies);
expect(
(screen.getByTestId("storage-clean-workspace-dependencies") as HTMLButtonElement).disabled,
).toBe(true);
cleanup();
renderCard(true, vi.fn(), enabledSettings, enabledSettings, onCleanDependencies);
expect(
(screen.getByTestId("storage-clean-workspace-dependencies") as HTMLButtonElement).disabled,
).toBe(true);
expect(onCleanDependencies).not.toHaveBeenCalled();
});
});
describe("StoragePolicyCard interactions", () => {
it("disables policy controls while an action is pending", () => {
renderCard(true);
@@ -239,7 +343,7 @@ describe("StoragePolicyCard interactions", () => {
renderCard(false, vi.fn(), {
...settings,
enabled: false,
workspaces: { enabled: false },
workspaces: { ...settings.workspaces, enabled: false },
go_cache: { ...settings.go_cache, enabled: false },
docker: {
...settings.docker,
@@ -281,15 +385,13 @@ describe("StoragePolicyCard interactions", () => {
it("marks the changed field and owning policy card as dirty", () => {
renderCard(false, vi.fn(), { ...settings, idle_for_minutes: 31 });
expect(screen.getByTestId("storage-idle-period").getAttribute("data-settings-dirty")).toBe(
expect(screen.getByTestId("storage-idle-period").getAttribute(dirtyAttribute)).toBe("true");
expect(screen.getByTestId("storage-policy-section-schedule").getAttribute(dirtyAttribute)).toBe(
"true",
);
expect(
screen.getByTestId("storage-policy-section-schedule").getAttribute("data-settings-dirty"),
).toBe("true");
expect(
screen.getByTestId("storage-policy-section-docker").getAttribute("data-settings-dirty"),
).toBe("false");
expect(screen.getByTestId("storage-policy-section-docker").getAttribute(dirtyAttribute)).toBe(
"false",
);
});
it("groups related settings and provides help for every policy option", () => {
@@ -304,7 +406,7 @@ describe("StoragePolicyCard interactions", () => {
]) {
expect(screen.getByText(heading)).toBeTruthy();
}
expect(screen.getAllByLabelText(/^More information about /)).toHaveLength(16);
expect(screen.getAllByLabelText(/^More information about /)).toHaveLength(18);
});
});
@@ -1,17 +1,15 @@
"use client";
import { useEffect, useRef, useState } from "react";
import { Input } from "@kandev/ui/input";
import { Label } from "@kandev/ui/label";
import { Switch } from "@kandev/ui/switch";
import { useTranslation } from "react-i18next";
import { settingsWithDockerAcknowledgement } from "@/hooks/domains/system/use-storage-maintenance";
import type { StorageCapabilities, StorageMaintenanceSettings } from "@/lib/types/system";
import { DedicatedDockerDialog, ExternalGoCacheDialog } from "./storage-confirmation-dialogs";
import { StorageActionButton } from "./storage-action-button";
import { StorageAdoptionField } from "./storage-adoption-field";
import { NumberField, PolicySection, SettingRow } from "./storage-policy-fields";
import { StorageSettingHelp } from "./storage-setting-help";
import { bytesToGigabytes, gigabytesToBytes } from "./storage-units";
import { StorageWorkspaceDependencySettings } from "./storage-workspace-dependency-settings";
type Props = {
settings: StorageMaintenanceSettings;
@@ -20,6 +18,7 @@ type Props = {
pending: boolean;
onChange: (settings: StorageMaintenanceSettings) => void;
onAdopt: (path: string) => Promise<void>;
onCleanDependencies?: () => void;
};
type PolicySectionProps = Pick<
@@ -94,7 +93,13 @@ function ScheduleSection({ settings, savedSettings, pending, onChange }: PolicyS
);
}
function WorkspaceSection({ settings, savedSettings, pending, onChange }: PolicySectionProps) {
function WorkspaceSection({
settings,
savedSettings,
pending,
onChange,
onCleanDependencies,
}: PolicySectionProps & Pick<Props, "onCleanDependencies">) {
const { t } = useTranslation();
const workspacesDirty = settingIsDirty(
settings,
@@ -107,12 +112,17 @@ function WorkspaceSection({ settings, savedSettings, pending, onChange }: Policy
savedSettings,
(value) => value.kandev_containers.enabled,
);
const dependencyCleanupDirty = settingIsDirty(
settings,
savedSettings,
(value) => value.workspaces.dependency_cleanup_enabled,
);
return (
<PolicySection
sectionId="workspaces"
title={t("system:storageWorkspacesTitle")}
description={t("system:storageWorkspacesDescription")}
isDirty={workspacesDirty || graceDirty || containersDirty}
isDirty={workspacesDirty || graceDirty || dependencyCleanupDirty || containersDirty}
>
<SettingRow
title={t("system:storageOrphanWorkspaces")}
@@ -122,7 +132,9 @@ function WorkspaceSection({ settings, savedSettings, pending, onChange }: Policy
<Switch
checked={settings.workspaces.enabled}
disabled={pending}
onCheckedChange={(enabled) => onChange({ ...settings, workspaces: { enabled } })}
onCheckedChange={(enabled) =>
onChange({ ...settings, workspaces: { ...settings.workspaces, enabled } })
}
aria-label={t("system:storageCleanOrphanWorkspacesAria")}
data-settings-dirty={workspacesDirty}
/>
@@ -141,6 +153,13 @@ function WorkspaceSection({ settings, savedSettings, pending, onChange }: Policy
isDirty={graceDirty}
/>
</div>
<StorageWorkspaceDependencySettings
settings={settings}
savedSettings={savedSettings}
pending={pending}
onChange={onChange}
onCleanDependencies={onCleanDependencies}
/>
<SettingRow
title={t("system:storageKandevContainers")}
description={t("system:storageContainersDescription")}
@@ -159,59 +178,6 @@ function WorkspaceSection({ settings, savedSettings, pending, onChange }: Policy
);
}
function AdoptionField({
path,
setPath,
onOpen,
pending,
enabled,
}: {
path: string;
setPath: (path: string) => void;
onOpen: () => void;
pending: boolean;
enabled: boolean;
}) {
const { t } = useTranslation();
let disabledReason: string | undefined;
if (pending) disabledReason = t("system:storageActionPending");
else if (!enabled) disabledReason = t("system:storageEnableGoCacheFirst");
else if (!path.trim()) disabledReason = t("system:storageEnterCachePathFirst");
const fieldLabel = t("system:storageExternalGoCache");
return (
<div className="min-w-0 space-y-2 pt-3">
<div className="flex items-center gap-1">
<Label htmlFor="storage-adoption-path">{fieldLabel}</Label>
<StorageSettingHelp label={fieldLabel}>
{t("system:storageExternalGoCacheHelp")}
</StorageSettingHelp>
</div>
<p className="text-xs text-muted-foreground">
{t("system:storageExternalGoCacheDescription")}
</p>
<div className="flex min-w-0 flex-col gap-2 sm:flex-row">
<Input
id="storage-adoption-path"
value={path}
disabled={pending || !enabled}
onChange={(event) => setPath(event.target.value)}
placeholder="/root/.cache/go-build"
className="h-11 min-w-0 font-mono"
data-testid="storage-go-cache-adopt-path"
/>
<StorageActionButton
variant="outline"
disabledReason={disabledReason}
onClick={onOpen}
data-testid="storage-go-cache-adopt"
>
{t("system:storageAdoptCache")}
</StorageActionButton>
</div>
</div>
);
}
function GoCacheSection({
settings,
savedSettings,
@@ -277,7 +243,7 @@ function GoCacheSection({
/>
</div>
{capabilities.go_cache_adoption_available && (
<AdoptionField
<StorageAdoptionField
path={adoptionPath}
setPath={setAdoptionPath}
pending={pending}
@@ -518,6 +484,7 @@ export function StoragePolicyCard({
pending,
onChange,
onAdopt,
onCleanDependencies,
}: Props) {
const { t } = useTranslation();
const [dockerDialogOpen, setDockerDialogOpen] = useState(false);
@@ -554,6 +521,7 @@ export function StoragePolicyCard({
capabilities={capabilities}
pending={pending}
onChange={onChange}
onCleanDependencies={onCleanDependencies}
/>
<GoCacheSection
settings={settings}
@@ -0,0 +1,102 @@
import { Switch } from "@kandev/ui/switch";
import { useTranslation } from "react-i18next";
import type { StorageMaintenanceSettings } from "@/lib/types/system";
import { StorageActionButton } from "./storage-action-button";
import { StorageSettingHelp } from "./storage-setting-help";
import { SettingRow } from "./storage-policy-fields";
// Keep this display snapshot in sync with backend DependencyDirectoryAllowlist.
const DEPENDENCY_DIRECTORIES = [
"node_modules",
"bower_components",
".pnpm-store",
".yarn/cache",
".yarn/unplugged",
".venv",
"venv",
".tox",
".nox",
"__pypackages__",
"Pods",
".gradle",
] as const;
type Props = {
settings: StorageMaintenanceSettings;
savedSettings: StorageMaintenanceSettings;
pending: boolean;
onChange: (settings: StorageMaintenanceSettings) => void;
onCleanDependencies?: () => void;
};
export function StorageWorkspaceDependencySettings({
settings,
savedSettings,
pending,
onChange,
onCleanDependencies,
}: Props) {
const { t } = useTranslation();
const dependenciesEnabled = settings.workspaces.dependency_cleanup_enabled;
const savedDependenciesEnabled = savedSettings.workspaces.dependency_cleanup_enabled;
const dependencyCleanupDirty = dependenciesEnabled !== savedDependenciesEnabled;
let dependencyActionDisabledReason: string | undefined;
if (pending) {
dependencyActionDisabledReason = t("system:storageActionPending");
} else if (!savedDependenciesEnabled) {
dependencyActionDisabledReason = t("system:storageEnableWorkspaceDependenciesAndSave");
}
return (
<>
<SettingRow
title={t("system:storageWorkspaceDependencies")}
description={t("system:storageWorkspaceDependenciesDescription")}
help={t("system:storageWorkspaceDependenciesHelp")}
control={
<Switch
checked={settings.workspaces.dependency_cleanup_enabled}
disabled={pending || !settings.workspaces.enabled}
onCheckedChange={(dependency_cleanup_enabled) =>
onChange({
...settings,
workspaces: { ...settings.workspaces, dependency_cleanup_enabled },
})
}
aria-label={t("system:storageWorkspaceDependencies")}
data-testid="storage-workspace-dependencies-enabled"
data-settings-dirty={dependencyCleanupDirty}
/>
}
/>
<div className="min-w-0 space-y-2 border-b py-3" data-testid="storage-dependency-allowlist">
<div className="flex min-w-0 items-center gap-1">
<p className="text-sm font-medium">{t("system:storageDependencyFoldersTitle")}</p>
<StorageSettingHelp label={t("system:storageDependencyFoldersTitle")}>
{t("system:storageDependencyFoldersHelp")}
</StorageSettingHelp>
</div>
<p className="text-xs text-muted-foreground">
{t("system:storageDependencyFoldersDescription")}
</p>
<ul className="grid min-w-0 grid-cols-1 gap-1 text-xs sm:grid-cols-2">
{DEPENDENCY_DIRECTORIES.map((directory) => (
<li key={directory} className="min-w-0">
<code className="block break-all rounded bg-muted px-2 py-1">{directory}</code>
</li>
))}
</ul>
{onCleanDependencies && (
<StorageActionButton
variant="outline"
disabledReason={dependencyActionDisabledReason}
onClick={onCleanDependencies}
data-testid="storage-clean-workspace-dependencies"
>
{t("system:storageCleanWorkspaceDependencies")}
</StorageActionButton>
)}
</div>
</>
);
}
@@ -70,6 +70,8 @@ test.describe("Mobile storage maintenance", () => {
await settingsMenu.getByRole("link", { name: "Storage" }).click();
await expect(testPage.getByTestId("storage-settings-page")).toBeVisible();
await expect(testPage.getByTestId("storage-disk-capacity-card")).toBeVisible();
await expect(testPage.getByRole("progressbar")).toBeVisible();
await testPage
.getByRole("button", { name: "More information about Scheduled maintenance" })
.click();
@@ -117,6 +119,13 @@ test.describe("Mobile storage maintenance", () => {
await expect(testPage.getByText("Go build cache adopted")).toBeVisible();
await testPage.reload();
await expect(testPage.getByTestId("storage-go-cache-adopt-path")).toHaveValue(externalGoCache);
await expect(testPage.getByTestId("storage-dependency-allowlist")).toContainText(".yarn/cache");
await testPage
.getByRole("button", { name: "More information about Folders Kandev will check" })
.tap();
await expect(testPage.getByRole("tooltip")).toContainText("recursively");
await testPage.reload();
await expect(testPage.getByTestId("storage-settings-page")).toBeVisible();
await testPage.getByRole("button", { name: "More information about Quarantine" }).click();
await expect(testPage.getByRole("tooltip")).toContainText("recoverable holding area");
await expect
@@ -141,6 +141,11 @@ test.describe("System storage maintenance", () => {
await expect(testPage.getByTestId("storage-policy-card")).toBeVisible();
await expect(testPage.getByTestId("storage-run-history")).toBeVisible();
await expect(testPage.getByTestId("storage-quarantine-card")).toBeVisible();
await expect(testPage.getByTestId("storage-disk-capacity-card")).toBeVisible();
await expect(testPage.getByRole("progressbar")).toBeVisible();
await expect(testPage.getByTestId("storage-dependency-allowlist")).toContainText(
"node_modules",
);
await expect(testPage.getByTestId("storage-overview-spinner")).toBeVisible();
await expect(testPage.getByTestId("storage-analysis-total")).toHaveCount(0);
await expect(testPage.getByTestId("toast-message")).toHaveCount(0);
@@ -16,6 +16,7 @@ const mocks = vi.hoisted(() => ({
purge: vi.fn(),
fetchJob: vi.fn(),
fetchOverview: vi.fn(),
fetchDisk: vi.fn(),
fetchPolicy: vi.fn(),
fetchQuarantine: vi.fn(),
fetchRuns: vi.fn(),
@@ -36,6 +37,7 @@ vi.mock("@/lib/api/domains/system-api", () => ({
purgeStorageQuarantine: mocks.purge,
fetchSystemJob: mocks.fetchJob,
fetchStorageOverview: mocks.fetchOverview,
fetchStorageDisk: mocks.fetchDisk,
fetchStoragePolicy: mocks.fetchPolicy,
fetchStorageQuarantine: mocks.fetchQuarantine,
fetchStorageRuns: mocks.fetchRuns,
@@ -55,7 +57,7 @@ const settings: StorageMaintenanceSettings = {
idle_for_minutes: 10,
orphan_grace_hours: 168,
quarantine_retention_hours: 168,
workspaces: { enabled: true },
workspaces: { enabled: true, dependency_cleanup_enabled: false },
kandev_containers: { enabled: true },
go_cache: { enabled: false, max_bytes: 16106127360, adopted_path: "" },
docker: {
@@ -93,6 +95,15 @@ const overview: StorageOverviewResponse = {
last_run: null,
};
const disk = {
path: "/data",
total_bytes: 100,
used_bytes: 80,
available_bytes: 20,
used_percent: 80,
available: true,
};
const cleanupJobId = "cleanup-job";
const cleanupJob = {
id: cleanupJobId,
@@ -120,6 +131,7 @@ function wrapper({ children }: { children: ReactNode }) {
beforeEach(() => {
vi.clearAllMocks();
mocks.fetchOverview.mockResolvedValue(overview);
mocks.fetchDisk.mockResolvedValue(disk);
mocks.fetchPolicy.mockResolvedValue({
settings: overview.settings,
capabilities: overview.capabilities,
@@ -146,6 +158,7 @@ describe("useStorageMaintenance", () => {
runs: false,
quarantine: false,
overview: true,
disk: false,
});
expect(result.current.overview).toBeNull();
@@ -162,6 +175,7 @@ describe("useStorageMaintenance", () => {
await waitFor(() => expect(result.current.overview).toEqual(overview));
expect(mocks.fetchRuns).toHaveBeenCalledWith(20);
expect(mocks.fetchQuarantine).toHaveBeenCalledTimes(1);
expect(mocks.fetchDisk).toHaveBeenCalledTimes(1);
expect(result.current.pendingAction).toBeNull();
});
@@ -251,6 +265,20 @@ describe("useStorageMaintenance", () => {
});
});
describe("useStorageMaintenance disk isolation", () => {
it("keeps the other sections usable when the disk request fails", async () => {
mocks.fetchDisk.mockRejectedValueOnce(new Error("disk unavailable"));
const { result } = renderHook(() => useStorageMaintenance(), { wrapper });
await waitFor(() => expect(result.current.sectionErrors.disk).toBe("disk unavailable"));
expect(result.current.policy?.settings).toEqual(settings);
expect(result.current.overview).toEqual(overview);
expect(result.current.runs).toEqual([]);
expect(result.current.quarantine).toEqual([]);
expect(result.current.loading.disk).toBe(false);
});
});
describe("useStorageMaintenance busy feedback", () => {
it("retains labeled busy feedback and reruns the same resources with force", async () => {
mocks.run.mockRejectedValueOnce(
@@ -23,6 +23,7 @@ import {
analyzeStorage,
deleteStorageQuarantine,
fetchStorageOverview,
fetchStorageDisk,
fetchStoragePolicy,
fetchStorageQuarantine,
fetchStorageRuns,
@@ -96,7 +97,7 @@ export function settingsWithDockerAcknowledgement(
};
}
export type StorageSection = "policy" | "overview" | "runs" | "quarantine";
export type StorageSection = "policy" | "overview" | "disk" | "runs" | "quarantine";
export type StorageSectionLoading = Record<StorageSection, boolean>;
export type StorageSectionErrors = Record<StorageSection, string | null>;
type Reload = (sections?: StorageSection[]) => Promise<void>;
@@ -376,23 +377,27 @@ export function useStorageMaintenance() {
const storage = useAppStore((state) => state.system.storage);
const setPolicy = useAppStore((state) => state.setSystemStoragePolicy);
const setOverview = useAppStore((state) => state.setSystemStorageOverview);
const setDisk = useAppStore((state) => state.setSystemStorageDisk);
const setRuns = useAppStore((state) => state.setSystemStorageRuns);
const setQuarantine = useAppStore((state) => state.setSystemStorageQuarantine);
const [loading, setLoading] = useState<StorageSectionLoading>({
policy: true,
overview: true,
disk: true,
runs: true,
quarantine: true,
});
const [sectionErrors, setSectionErrors] = useState<StorageSectionErrors>({
policy: null,
overview: null,
disk: null,
runs: null,
quarantine: null,
});
const sectionGenerations = useRef<Record<StorageSection, number>>({
policy: 0,
overview: 0,
disk: 0,
runs: 0,
quarantine: 0,
});
@@ -421,13 +426,15 @@ export function useStorageMaintenance() {
[],
);
const reload = useCallback(
async (sections: StorageSection[] = ["policy", "overview", "runs", "quarantine"]) => {
async (sections: StorageSection[] = ["policy", "overview", "disk", "runs", "quarantine"]) => {
const jobs = sections.map((section) => {
switch (section) {
case "policy":
return loadSection("policy", fetchStoragePolicy, setPolicy);
case "overview":
return loadSection("overview", fetchStorageOverview, setOverview);
case "disk":
return loadSection("disk", fetchStorageDisk, setDisk);
case "runs":
return loadSection("runs", () => fetchStorageRuns(20), setRuns);
case "quarantine":
@@ -440,7 +447,7 @@ export function useStorageMaintenance() {
);
if (failure) throw failure.reason;
},
[loadSection, setOverview, setPolicy, setQuarantine, setRuns],
[loadSection, setDisk, setOverview, setPolicy, setQuarantine, setRuns],
);
const commitAdoptedPolicy = useCallback(
(policy: StoragePolicyResponse) => {
+21 -1
View File
@@ -35,6 +35,7 @@ import {
analyzeStorage,
deleteStorageQuarantine,
fetchStorageOverview,
fetchStorageDisk,
fetchStoragePolicy,
fetchStorageQuarantine,
fetchStorageRuns,
@@ -393,7 +394,7 @@ const storageSettings = {
idle_for_minutes: 10,
orphan_grace_hours: 168,
quarantine_retention_hours: 168,
workspaces: { enabled: true },
workspaces: { enabled: true, dependency_cleanup_enabled: false },
kandev_containers: { enabled: true },
go_cache: { enabled: false, max_bytes: 16106127360, adopted_path: "" },
docker: {
@@ -429,6 +430,25 @@ describe("storage maintenance", () => {
expect((await fetchStorageQuarantine())[0]?.id).toBe("entry-1");
});
it("loads disk capacity independently without caching", async () => {
fetchSpy.mockResolvedValueOnce(
jsonResponse({
path: "/data",
total_bytes: 1000,
used_bytes: 800,
available_bytes: 200,
used_percent: 80,
available: true,
}),
);
const response = await fetchStorageDisk();
expect(lastCall().url).toBe(`${BASE}/storage/disk`);
expect(lastCall().init?.cache).toBe("no-store");
expect(response.used_percent).toBe(80);
});
it("saves dedicated Docker acknowledgement with its confirmation", async () => {
fetchSpy.mockResolvedValueOnce(jsonResponse({ settings: storageSettings }));
await saveStorageSettings(storageSettings, "DEDICATED");
+10
View File
@@ -17,6 +17,7 @@ import type {
StorageAdoptionResponse,
StorageMaintenanceRun,
StorageMaintenanceSettings,
StorageDiskCapacityResponse,
StorageOverviewResponse,
StoragePolicyResponse,
StorageQuarantineEntry,
@@ -275,6 +276,15 @@ export function fetchStorageOverview(
});
}
export function fetchStorageDisk(
options?: ApiRequestOptions,
): Promise<StorageDiskCapacityResponse> {
return fetchJson<StorageDiskCapacityResponse>(`${SYSTEM_BASE}/storage/disk`, {
...options,
cache: "no-store",
});
}
export function fetchStoragePolicy(options?: ApiRequestOptions): Promise<StoragePolicyResponse> {
return fetchJson<StoragePolicyResponse>(`${SYSTEM_BASE}/storage/settings`, {
...options,
@@ -95,7 +95,7 @@ describe("system storage slice", () => {
idle_for_minutes: 10,
orphan_grace_hours: 168,
quarantine_retention_hours: 168,
workspaces: { enabled: true },
workspaces: { enabled: true, dependency_cleanup_enabled: false },
kandev_containers: { enabled: true },
go_cache: { enabled: false, max_bytes: 16106127360, adopted_path: "" },
docker: {
@@ -137,6 +137,7 @@ describe("system storage slice", () => {
expect(store.getState().system.storage).toEqual({
policy,
overview,
disk: null,
runs: [],
quarantine: [],
});
@@ -10,7 +10,7 @@ export const defaultSystemState: SystemSliceState = {
updates: null,
jobs: {},
metrics: null,
storage: { policy: null, overview: null, runs: [], quarantine: [] },
storage: { policy: null, overview: null, disk: null, runs: [], quarantine: [] },
},
};
@@ -65,6 +65,10 @@ export const createSystemSlice: StateCreator<
set((draft) => {
draft.system.storage.overview = overview;
}),
setSystemStorageDisk: (disk) =>
set((draft) => {
draft.system.storage.disk = disk;
}),
setSystemStorageRuns: (runs) =>
set((draft) => {
draft.system.storage.runs = runs;
@@ -7,6 +7,7 @@ import type {
SystemJob,
SystemMetricsSnapshot,
StorageMaintenanceRun,
StorageDiskCapacityResponse,
StorageOverviewResponse,
StoragePolicyResponse,
StorageQuarantineEntry,
@@ -31,6 +32,7 @@ export type SystemSliceState = {
storage: {
policy: StoragePolicyResponse | null;
overview: StorageOverviewResponse | null;
disk: StorageDiskCapacityResponse | null;
runs: StorageMaintenanceRun[];
quarantine: StorageQuarantineEntry[];
};
@@ -48,6 +50,7 @@ export type SystemSliceActions = {
setSystemMetricsSnapshot: (snapshot: SystemMetricsSnapshot) => void;
setSystemStoragePolicy: (policy: StoragePolicyResponse) => void;
setSystemStorageOverview: (overview: StorageOverviewResponse) => void;
setSystemStorageDisk: (disk: StorageDiskCapacityResponse) => void;
setSystemStorageRuns: (runs: StorageMaintenanceRun[]) => void;
setSystemStorageQuarantine: (entries: StorageQuarantineEntry[]) => void;
};
+15 -1
View File
@@ -261,6 +261,10 @@ export interface StorageResourceSettings {
enabled: boolean;
}
export interface StorageWorkspaceSettings extends StorageResourceSettings {
dependency_cleanup_enabled: boolean;
}
export interface StorageGoCacheSettings {
enabled: boolean;
max_bytes: number;
@@ -282,7 +286,7 @@ export interface StorageMaintenanceSettings {
idle_for_minutes: number;
orphan_grace_hours: number;
quarantine_retention_hours: number;
workspaces: StorageResourceSettings;
workspaces: StorageWorkspaceSettings;
kandev_containers: StorageResourceSettings;
go_cache: StorageGoCacheSettings;
docker: StorageDockerSettings;
@@ -421,6 +425,16 @@ export interface StorageOverviewResponse {
last_run: StorageMaintenanceRun | null;
}
export interface StorageDiskCapacityResponse {
path: string;
total_bytes: number;
used_bytes: number;
available_bytes: number;
used_percent: number;
available: boolean;
warning?: string;
}
export interface StoragePolicyResponse {
settings: StorageMaintenanceSettings;
capabilities: StorageCapabilities;
+19
View File
@@ -307,6 +307,17 @@
"storageDockerUnavailableBadge": "Docker unavailable",
"storageDockerUnavailableNotice": "Docker is unavailable; Docker cleanup options cannot run on this host.",
"storageDockerUnmeasured": "Docker usage could not be measured",
"storageDiskTitle": "Disk capacity",
"storageDiskDescription": "Current usage of the filesystem containing Kandev storage.",
"storageDiskLoading": "Loading disk capacity…",
"storageDiskUnavailable": "Disk capacity is unavailable right now.",
"storageDiskUsed": "{{percent}}% full",
"storageDiskUsedSize": "{{size}} used",
"storageDiskCapacitySummary": "{{available}} available · {{total}} total",
"storageDiskPath": "Storage path",
"storageDiskProgressAria": "Disk usage: {{percent}}% full",
"storageDiskHighWarning": "This filesystem is becoming full (80% or more used).",
"storageDiskCriticalWarning": "This filesystem is critically full (90% or more used).",
"storageEligibleNow": "Eligible now",
"storageEnableGoCacheFirst": "Enable the managed Go cache first.",
"storageEnableManagedGoCacheAria": "Enable managed Go cache",
@@ -412,6 +423,14 @@
"storageWorkspacesDescription": "Reclaim resources that Kandev can positively identify as no longer in use.",
"storageWorkspacesDetail": "{{reclaimable}} reclaimable after the grace period · {{active}} active",
"storageWorkspacesTitle": "Workspaces and containers",
"storageWorkspaceDependencies": "Remove dependencies from archived or deleted workspaces",
"storageWorkspaceDependenciesDescription": "Opt in to remove dependency folders while keeping the workspace source and recovery metadata.",
"storageWorkspaceDependenciesHelp": "When enabled and saved, Kandev recursively checks only the listed folders inside unprotected Kandev task workspaces that are archived or deleted. It skips missing folders, symlinks, active or protected workspaces, and ambiguous folders such as vendor, target, build, dist, .cache, and .git. Restoring a trimmed workspace may require reinstalling dependencies.",
"storageDependencyFoldersTitle": "Folders Kandev will check",
"storageDependencyFoldersDescription": "These exact directory names are the complete cleanup allowlist.",
"storageDependencyFoldersHelp": "Kandev searches recursively for these directory names. Missing folders are skipped. Kandev never targets the excluded ambiguous names, follows symlinks, or accepts custom paths. Only archived or deleted, unprotected Kandev workspaces are eligible, and dependencies may need to be reinstalled after restore.",
"storageCleanWorkspaceDependencies": "Clean workspace dependencies",
"storageEnableWorkspaceDependenciesAndSave": "Enable and save dependency cleanup before running it.",
"systemMetrics": "System metrics",
"uiStateHelp": "Clears layout and UI preferences saved in your browser (panel sizes, pinned tasks, expanded groups, etc.). Use this if the app looks broken, panels are stuck, or the layout feels wrong. Your tasks, sessions, and server data are not affected - only the per-browser UI state. The page reloads after the reset.",
"uiStateReset": "Reset",
+19
View File
@@ -307,6 +307,17 @@
"storageDockerUnavailableBadge": "Ďōćķēŕ ũńàvàĩĺàƀĺē",
"storageDockerUnavailableNotice": "Ďōćķēŕ ĩś ũńàvàĩĺàƀĺē; Ďōćķēŕ ćĺēàńũƥ ōƥţĩōńś ćàńńōţ ŕũń ōń ţĥĩś ĥōśţ.",
"storageDockerUnmeasured": "Ďōćķēŕ ũśàĝē ćōũĺď ńōţ ƀē ḿēàśũŕēď",
"storageDiskTitle": "Ďĩśķ ćàƥàćĩţŷ",
"storageDiskDescription": "Ćũŕŕēńţ ũśàĝē ōƒ ţĥē ƒĩĺēśŷśţēḿ ćōńţàĩńĩńĝ Ķàńďēv śţōŕàĝē.",
"storageDiskLoading": "Ĺōàďĩńĝ ďĩśķ ćàƥàćĩţŷ…",
"storageDiskUnavailable": "Ďĩśķ ćàƥàćĩţŷ ĩś ũńàvàĩĺàƀĺē ŕĩĝĥţ ńōŵ.",
"storageDiskUsed": "{{percent}}% ƒũĺĺ",
"storageDiskUsedSize": "{{size}} ũśēď",
"storageDiskCapacitySummary": "{{available}} àvàĩĺàƀĺē · {{total}} ţōţàĺ",
"storageDiskPath": "Śţōŕàĝē ƥàţĥ",
"storageDiskProgressAria": "Ďĩśķ ũśàĝē: {{percent}}% ƒũĺĺ",
"storageDiskHighWarning": "Ţĥĩś ƒĩĺēśŷśţēḿ ĩś ƀēćōḿĩńĝ ƒũĺĺ (80% ōŕ ḿōŕē ũśēď).",
"storageDiskCriticalWarning": "Ţĥĩś ƒĩĺēśŷśţēḿ ĩś ćŕĩţĩćàĺĺŷ ƒũĺĺ (90% ōŕ ḿōŕē ũśēď).",
"storageEligibleNow": "Ēĺĩĝĩƀĺē ńōŵ",
"storageEnableGoCacheFirst": "Ēńàƀĺē ţĥē ḿàńàĝēď Ĝō ćàćĥē ƒĩŕśţ.",
"storageEnableManagedGoCacheAria": "Ēńàƀĺē ḿàńàĝēď Ĝō ćàćĥē",
@@ -412,6 +423,14 @@
"storageWorkspacesDescription": "Ŕēćĺàĩḿ ŕēśōũŕćēś ţĥàţ Ķàńďēv ćàń ƥōśĩţĩvēĺŷ ĩďēńţĩƒŷ àś ńō ĺōńĝēŕ ĩń ũśē.",
"storageWorkspacesDetail": "{{reclaimable}} ŕēćĺàĩḿàƀĺē àƒţēŕ ţĥē ĝŕàćē ƥēŕĩōď · {{active}} àćţĩvē",
"storageWorkspacesTitle": "Ŵōŕķśƥàćēś àńď ćōńţàĩńēŕś",
"storageWorkspaceDependencies": "Ŕēḿōvē ďēƥēńďēńćĩēś ƒŕōḿ àŕćĥĩvēď ōŕ ďēĺēţēď ŵōŕķśƥàćēś",
"storageWorkspaceDependenciesDescription": "Ōƥţ ĩń ţō ŕēḿōvē ďēƥēńďēńćŷ ƒōĺďēŕś ŵĥĩĺē ķēēƥĩńĝ ţĥē ŵōŕķśƥàćē śōũŕćē àńď ŕēćōvēŕŷ ḿēţàďàţà.",
"storageWorkspaceDependenciesHelp": "Ŵĥēń ēńàƀĺēď àńď śàvēď, Ķàńďēv ŕēćũŕśĩvēĺŷ ćĥēćķś ōńĺŷ ţĥē ĺĩśţēď ƒōĺďēŕś ĩńśĩďē ũńƥŕōţēćţēď Ķàńďēv ţàśķ ŵōŕķśƥàćēś ţĥàţ àŕē àŕćĥĩvēď ōŕ ďēĺēţēď. Ĩţ śķĩƥś ḿĩśśĩńĝ ƒōĺďēŕś, śŷḿĺĩńķś, àćţĩvē ōŕ ƥŕōţēćţēď ŵōŕķśƥàćēś, àńď àḿƀĩĝũōũś ƒōĺďēŕś śũćĥ àś vēńďōŕ, ţàŕĝēţ, ƀũĩĺď, ďĩśţ, .ćàćĥē, àńď .ĝĩţ. Ŕēśţōŕĩńĝ à ţŕĩḿḿēď ŵōŕķśƥàćē ḿàŷ ŕēqũĩŕē ŕēĩńśţàĺĺĩńĝ ďēƥēńďēńćĩēś.",
"storageDependencyFoldersTitle": "Ƒōĺďēŕś Ķàńďēv ŵĩĺĺ ćĥēćķ",
"storageDependencyFoldersDescription": "Ţĥēśē ēxàćţ ďĩŕēćţōŕŷ ńàḿēś àŕē ţĥē ćōḿƥĺēţē ćĺēàńũƥ àĺĺōŵĺĩśţ.",
"storageDependencyFoldersHelp": "Ķàńďēv śēàŕćĥēś ŕēćũŕśĩvēĺŷ ƒōŕ ţĥēśē ďĩŕēćţōŕŷ ńàḿēś. Ḿĩśśĩńĝ ƒōĺďēŕś àŕē śķĩƥƥēď. Ķàńďēv ńēvēŕ ţàŕĝēţś ţĥē ēxćĺũďēď àḿƀĩĝũōũś ńàḿēś, ƒōĺĺōŵś śŷḿĺĩńķś, ōŕ àććēƥţś ćũśţōḿ ƥàţĥś. Ōńĺŷ àŕćĥĩvēď ōŕ ďēĺēţēď, ũńƥŕōţēćţēď Ķàńďēv ŵōŕķśƥàćēś àŕē ēĺĩĝĩƀĺē, àńď ďēƥēńďēńćĩēś ḿàŷ ńēēď ţō ƀē ŕēĩńśţàĺĺēď àƒţēŕ ŕēśţōŕē.",
"storageCleanWorkspaceDependencies": "Ćĺēàń ŵōŕķśƥàćē ďēƥēńďēńćĩēś",
"storageEnableWorkspaceDependenciesAndSave": "Ēńàƀĺē àńď śàvē ďēƥēńďēńćŷ ćĺēàńũƥ ƀēƒōŕē ŕũńńĩńĝ ĩţ.",
"systemMetrics": "Śŷśţēḿ ḿēţŕĩćś",
"uiStateHelp": "Ćĺēàŕś ĺàŷōũţ àńď ŨĨ ƥŕēƒēŕēńćēś śàvēď ĩń ŷōũŕ ƀŕōŵśēŕ (ƥàńēĺ śĩźēś, ƥĩńńēď ţàśķś, ēxƥàńďēď ĝŕōũƥś, ēţć.). Ũśē ţĥĩś ĩƒ ţĥē àƥƥ ĺōōķś ƀŕōķēń, ƥàńēĺś àŕē śţũćķ, ōŕ ţĥē ĺàŷōũţ ƒēēĺś ŵŕōńĝ. Ŷōũŕ ţàśķś, śēśśĩōńś, àńď śēŕvēŕ ďàţà àŕē ńōţ àƒƒēćţēď - ōńĺŷ ţĥē ƥēŕ-ƀŕōŵśēŕ ŨĨ śţàţē. Ţĥē ƥàĝē ŕēĺōàďś àƒţēŕ ţĥē ŕēśēţ.",
"uiStateReset": "Ŕēśēţ",
+19
View File
@@ -307,6 +307,17 @@
"storageDockerUnavailableBadge": "Docker indisponível",
"storageDockerUnavailableNotice": "O Docker não está disponível; as opções de limpeza do Docker não podem ser executadas neste anfitrião.",
"storageDockerUnmeasured": "Não foi possível medir a utilização do Docker",
"storageDiskTitle": "Capacidade do disco",
"storageDiskDescription": "Utilização atual do sistema de ficheiros que contém o armazenamento do Kandev.",
"storageDiskLoading": "A carregar a capacidade do disco…",
"storageDiskUnavailable": "A capacidade do disco não está disponível neste momento.",
"storageDiskUsed": "{{percent}}% cheio",
"storageDiskUsedSize": "{{size}} utilizado",
"storageDiskCapacitySummary": "{{available}} disponível · {{total}} no total",
"storageDiskPath": "Caminho do armazenamento",
"storageDiskProgressAria": "Utilização do disco: {{percent}}% cheio",
"storageDiskHighWarning": "Este sistema de ficheiros está a ficar cheio (80% ou mais utilizado).",
"storageDiskCriticalWarning": "Este sistema de ficheiros está criticamente cheio (90% ou mais utilizado).",
"storageEligibleNow": "Elegível agora",
"storageEnableGoCacheFirst": "Ative primeiro a cache do Go gerida.",
"storageEnableManagedGoCacheAria": "Ativar a cache do Go gerida",
@@ -412,6 +423,14 @@
"storageWorkspacesDescription": "Recupere recursos que o Kandev consegue identificar com segurança como já não estando em uso.",
"storageWorkspacesDetail": "{{reclaimable}} recuperáveis após o período de tolerância · {{active}} ativas",
"storageWorkspacesTitle": "Áreas de trabalho e contentores",
"storageWorkspaceDependencies": "Remover dependências de áreas de trabalho arquivadas ou eliminadas",
"storageWorkspaceDependenciesDescription": "Ative para remover pastas de dependências, mantendo o código-fonte e os metadados de recuperação.",
"storageWorkspaceDependenciesHelp": "Quando ativado e guardado, o Kandev verifica recursivamente apenas as pastas listadas dentro de áreas de trabalho de tarefas do Kandev arquivadas ou eliminadas. Ignora pastas ausentes, ligações simbólicas, áreas ativas ou protegidas e pastas ambíguas como vendor, target, build, dist, .cache e .git. Restaurar uma área de trabalho limpa pode exigir reinstalar as dependências.",
"storageDependencyFoldersTitle": "Pastas que o Kandev irá verificar",
"storageDependencyFoldersDescription": "Estes nomes exatos de diretórios são a lista completa de limpeza permitida.",
"storageDependencyFoldersHelp": "O Kandev procura recursivamente estes nomes de diretórios. As pastas ausentes são ignoradas. O Kandev nunca visa os nomes ambíguos excluídos, segue ligações simbólicas ou aceita caminhos personalizados. Só são elegíveis áreas de trabalho do Kandev arquivadas ou eliminadas e não protegidas; depois de restaurar, pode ser necessário reinstalar as dependências.",
"storageCleanWorkspaceDependencies": "Limpar dependências das áreas de trabalho",
"storageEnableWorkspaceDependenciesAndSave": "Ative e guarde a limpeza de dependências antes de a executar.",
"systemMetrics": "Métricas do sistema",
"uiStateHelp": "Limpa as preferências de esquema e de interface guardadas no seu navegador (tamanhos dos painéis, tarefas afixadas, grupos expandidos, etc.). Use isto se a aplicação parecer avariada, se os painéis estiverem bloqueados ou se o esquema parecer errado. As suas tarefas, sessões e dados do servidor não são afetados - apenas o estado da interface de cada navegador. A página é recarregada após a reposição.",
"uiStateReset": "Repor",
+19
View File
@@ -307,6 +307,17 @@
"storageDockerUnavailableBadge": "Docker 不可用",
"storageDockerUnavailableNotice": "Docker 不可用;此主机无法运行 Docker 清理选项。",
"storageDockerUnmeasured": "无法测量 Docker 用量",
"storageDiskTitle": "磁盘容量",
"storageDiskDescription": "包含 Kandev 存储的文件系统当前使用情况。",
"storageDiskLoading": "正在加载磁盘容量…",
"storageDiskUnavailable": "磁盘容量暂时不可用。",
"storageDiskUsed": "已满 {{percent}}%",
"storageDiskUsedSize": "已使用 {{size}}",
"storageDiskCapacitySummary": "可用 {{available}} · 总计 {{total}}",
"storageDiskPath": "存储路径",
"storageDiskProgressAria": "磁盘使用率:已满 {{percent}}%",
"storageDiskHighWarning": "此文件系统正在变满(已使用 80% 或更多)。",
"storageDiskCriticalWarning": "此文件系统已严重满载(已使用 90% 或更多)。",
"storageEligibleNow": "当前符合条件",
"storageEnableGoCacheFirst": "请先启用托管的 Go 缓存。",
"storageEnableManagedGoCacheAria": "启用托管 Go 缓存",
@@ -412,6 +423,14 @@
"storageWorkspacesDescription": "回收 Kandev 能明确识别为不再使用的资源。",
"storageWorkspacesDetail": "宽限期后可回收 {{reclaimable}} · 活动 {{active}}",
"storageWorkspacesTitle": "工作区与容器",
"storageWorkspaceDependencies": "删除已归档或已删除工作区中的依赖项",
"storageWorkspaceDependenciesDescription": "选择加入后可删除依赖目录,同时保留工作区源代码和恢复元数据。",
"storageWorkspaceDependenciesHelp": "启用并保存后,Kandev 只会在已归档或已删除且未受保护的 Kandev 任务工作区中递归检查下列目录。缺失目录、符号链接、活动或受保护工作区,以及 vendor、target、build、dist、.cache 和 .git 等含义不明确的目录都会跳过。恢复清理过的工作区后可能需要重新安装依赖项。",
"storageDependencyFoldersTitle": "Kandev 将检查的文件夹",
"storageDependencyFoldersDescription": "这些确切的目录名称构成完整的清理允许列表。",
"storageDependencyFoldersHelp": "Kandev 会递归搜索这些目录名称。缺失目录会跳过。Kandev 永远不会处理排除的含义不明确名称、跟随符号链接或接受自定义路径。只有已归档或已删除且未受保护的 Kandev 工作区符合条件,恢复后可能需要重新安装依赖项。",
"storageCleanWorkspaceDependencies": "清理工作区依赖项",
"storageEnableWorkspaceDependenciesAndSave": "请先启用并保存依赖清理设置,再运行清理。",
"systemMetrics": "系统指标",
"uiStateHelp": "清除保存在浏览器中的布局与 UI 偏好(面板大小、固定任务、展开分组等)。若应用显示异常、面板卡住或布局不对,可使用此选项。任务、会话与服务器数据不受影响 — 仅影响当前浏览器保存的 UI 状态。重置后页面会重新加载。",
"uiStateReset": "重置",
@@ -0,0 +1,147 @@
---
spec: docs/specs/system-page/storage-overview-parallel-scan.md
created: 2026-08-08
status: completed
---
# Implementation Plan: Faster storage analysis, capacity visibility, and dependency cleanup
## Overview
Deliver three related Storage maintenance improvements: overlap the four expensive overview
measurements, expose a lightweight filesystem-capacity endpoint and accessible progress card, and
add an opt-in, ownership-aware dependency-directory cleanup provider for archived/deleted task
workspaces. Preserve existing overview contracts, per-source error degradation, process-local
overview cache behavior, progressive page loading, and activity-coordinator idle semantics.
## Backend design
- Refactor the overview composition in
`apps/backend/internal/backendapp/storage_maintenance.go` around a small measurement seam that
can run workspace, Go-cache, quarantine, and Docker analysis concurrently.
- Use explicit result slots or equivalent ownership-safe state so each measurement writes only its
own result and error before the parent goroutine assembles `Summary`.
- Wait for all measurements rather than cancelling siblings on an expected provider error. Preserve
the current behavior where unavailable sources are represented in the returned summary and other
sources still contribute their data.
- Keep settings loading before the measurement fan-out because provider construction and configured
paths depend on that snapshot.
- Keep disk capacity outside the overview cache so the capacity card is cheap and can refresh
independently while a cold scan is pending. Reuse the existing cross-platform statfs/free-space
semantics in `apps/backend/internal/system/metrics` through a small capacity result seam rather
than duplicating platform-specific calculations.
- Add a `GET /api/v1/system/storage/disk` handler that measures the filesystem containing the
Kandev storage root and returns total, used, available, percentage, path, and availability/error
fields. A capacity failure must not fail the overview or other Storage sections.
### Workspace dependency cleanup
- Add a persisted, default-off `workspaces.dependency_cleanup_enabled` setting and surface it in the
Workspaces policy card with localized warning/help copy. Always display the exact fixed allowlist
in a code-styled disclosure labeled as folders Kandev will check; pair it with the existing
`StorageSettingHelp` information control so hover, keyboard focus, and tap expose the same
explanation.
- Add a `workspace_dependencies` cleanup provider and resource-specific action. It uses the same
maintenance lease, busy response, Run anyway behavior, cancellation, retry, and run-history
result shape as other destructive providers.
- Reuse the workspace provider's fail-closed ownership, authoritative inventory, path containment,
and no-follow-symlink checks. Introduce a small eligibility source if needed to distinguish
archived task rows from deleted tasks whose ownership marker remains on disk.
- Prune only the fixed allowlist from the spec. Count directories and reclaimed bytes, preserve
source/Git/recovery metadata, skip protected or state-changing workspaces, and make the operation
idempotent so retrying after interruption is safe.
- Keep full workspace orphan grace and quarantine retention unchanged. Dependency pruning is a
separate provider and must never be implied by the disk percentage or by read-only Analyze.
- Coordinate pruning with quarantine restore and task reactivation so a restore/unarchive cannot
race a dependency deletion. Revalidate ownership and task state immediately before each target
removal; fail closed on incomplete inventory.
## Tests
- Add a deterministic barrier-based backend test for the overview fan-out. It must prove all four
measurements enter before release, then assert the assembled summary and independent errors.
- Retain or update composition fakes only as needed to inject blocking providers; avoid tests that
depend on `time.Sleep` or host filesystem size.
- Add capacity provider/handler tests for byte math, clamping, unavailable filesystems, timeout or
cancellation, and the selected storage-root path. Extend API fixtures for the new disk response.
- Add workspace-provider tests for allowlist-only deletion, archived/deleted eligibility, active
inventory protection, symlink/path escape rejection, byte/count results, cancellation, retry,
restore-after-prune, and default-off settings validation.
- Run the existing cache, handler, operations, scheduler, and activity-coordinator suites to guard
the unchanged contracts.
- Extend desktop and mobile Storage E2E coverage for the independent capacity card, the progress
bar's accessible percentage, the new policy option, visible allowlisted-folder names, the
hover/focus/tap help explanation, and the workspace dependency action. Keep the page one-column on
mobile and verify no horizontal overflow.
## Observability and rollout
- When a compatible post-change runtime is available, use the existing backend request-duration
logs to capture a comparable cold overview before and after implementation. The cache must be
cold for both measurements and the host dataset/settings must be held constant. If the running
runtime predates the capacity route, record the baseline and deterministic/managed E2E evidence
instead of claiming a comparable post-change timing.
- Capture disk-capacity response timing separately to confirm it is available before the cold
overview completes.
- Record the measured result in the implementation task handoff. If workspace traversal remains
the dominant cost, open a separate bounded directory-traversal optimization rather than expanding
this change.
## Implementation waves
Wave 1:
- [x] [Task 01: Parallelize overview measurements](task-01-parallelize-overview-measurements.md)
Wave 2:
- [x] [Task 03: Add disk capacity and progress card](task-03-disk-capacity-progress.md)
- [x] [Task 04: Add opt-in dependency cleanup](task-04-workspace-dependency-cleanup.md)
Wave 3:
- [x] [Task 02: Integrated regression and timing validation](task-02-regression-and-timing-validation.md)
## Implementation results
- Overview measurements now fan out after settings load. A barrier-based test proves workspace,
Go-cache, quarantine, and Docker measurements all enter before release; the backend package and
storage packages pass with `-race`.
- `GET /api/v1/system/storage/disk` reports filesystem total, used, available, percentage, path,
and safe unavailable states. The page loads it independently, renders the accessible progress
bar, and applies 80% warning/90% critical presentation thresholds.
- Workspace dependency cleanup is default-off, uses the exact 12-entry allowlist, requires a
complete authoritative task inventory, targets only archived/deleted unprotected Kandev-owned
roots, and revalidates ownership, containment, symlink safety, and eligibility before each
deletion. Results report affected workspaces, directories, bytes, and warnings.
- Focused backend tests, the backend race suite, backend lint, web typecheck/lint/i18n checks, 101 focused web
tests, public-doc validation, and managed Chromium/mobile Storage E2E flows pass. The mobile
flow verifies the allowlist disclosure through touch interaction without horizontal overflow;
the workspace suite also verifies exact allowlist-copy behavior and restore after dependency
pruning, and the Windows metrics package compiles.
- The captured pre-change live baseline remains approximately 103 seconds cold and effectively
instantaneous warm because of the 15-minute overview cache. The post-change managed E2E holds
the overview response and confirms the disk card renders independently before it is released;
a same-dataset live timing comparison was not taken against the currently running pre-change
backend (its disk route returned 404). Workspace traversal remains the dominant optimization
risk to monitor after rollout.
- Idle behavior is unchanged: scheduled cleanup still requires the existing quiet period and
blocks on active execution/shell/setup/cleanup/Docker-build resources; manual Analyze remains
read-only and not idle-gated.
## Risks
- Goroutine-owned result state must be race-free; run the focused backend suite with `-race`.
- A provider that blocks or ignores cancellation can still determine request duration; the change
removes top-level serialization but does not alter provider traversal behavior.
- A refactor that accidentally wraps each provider in a separate cache or changes error joining
could regress warm reads or partial summaries; preserve the existing cache and response tests.
- Disk usage can be confused with Kandev-counted bytes; label the progress card as the filesystem
containing Kandev storage and show raw total/available values so the distinction is explicit.
- Dependency names such as `vendor`, `target`, and `.cache` are ambiguous; keep them out of the
initial fixed allowlist and make skipped/warned paths visible in the run result.
- Dependency pruning can race restore, unarchive, or a newly admitted task. Use the existing
maintenance admission path plus per-target revalidation and fail closed on any state change.
- The activity gate covers instrumented runtime work. Workspace reconciliation that occurs before an
execution activity lease is acquired remains outside this change and should be audited separately
if it becomes a demonstrated idle-gate gap.
@@ -0,0 +1,67 @@
---
id: "01-parallelize-overview-measurements"
title: "Parallelize overview measurements"
status: done
wave: 1
depends_on: []
plan: "plan.md"
spec: "../../specs/system-page/storage-overview-parallel-scan.md"
---
# Task 01: Parallelize overview measurements
## Acceptance
- Workspace, Go-cache, quarantine, and Docker measurements start concurrently after settings are
loaded.
- A provider error does not prevent successful results from the other providers from reaching the
existing `Summary` response.
- The API response, provider construction, and overview cache behavior remain unchanged.
- No measurement goroutine or shared result state produces a race or leak under cancellation.
## Verification
```bash
cd apps/backend && go test -race ./internal/backendapp ./internal/system/storage ./internal/agent/runtime/activity ./internal/agent/runtime/lifecycle
```
The new unit test must use barriers/channels to prove concurrent entry; it must not use a sleep-
based timing assertion.
## Files likely touched
- `apps/backend/internal/backendapp/storage_maintenance.go`
- `apps/backend/internal/backendapp/storage_maintenance_test.go` or the existing focused backend
composition test file
- Any small test-only provider seams required by the composition test
## Dependencies
None.
## Inputs
- Spec: parallel overview measurements, failure modes, and unchanged API/persistence guarantees
- Existing `storageOverview.Summary` composition in
`apps/backend/internal/backendapp/storage_maintenance.go`
- Typed providers in `apps/backend/internal/system/storage/workspaces/provider.go`,
`gocache/provider.go`, `store.go`, and `dockerstore/provider.go`
- Existing cache and API tests in `apps/backend/internal/system/storage`
## Output contract
Return a compact handoff capsule with acceptance status, changed entry points, focused test results,
race-test results, risk tags, and any provider behavior that remains dominant in live timing.
## Result
Implemented the four-way fan-out with isolated result/error slots and preserved the existing
summary/cache contract. The barrier test proves concurrent entry without sleeps. These checks pass:
```text
go test ./internal/backendapp ./internal/system/storage/... ./internal/system/metrics ./internal/agent/runtime/activity ./internal/agent/runtime/lifecycle -count=1
go test -race ./internal/backendapp ./internal/system/storage/... ./internal/system/metrics -count=1
```
The remaining dominant cost is workspace traversal; provider traversal itself was intentionally
left unchanged in this task.
@@ -0,0 +1,75 @@
---
id: "02-regression-and-timing-validation"
title: "Validate storage scan and idle behavior"
status: done
wave: 3
depends_on: ["01-parallelize-overview-measurements", "03-disk-capacity-progress", "04-workspace-dependency-cleanup"]
plan: "plan.md"
spec: "../../specs/system-page/storage-overview-parallel-scan.md"
---
# Task 02: Validate storage scan and idle behavior
## Acceptance
- Existing Storage E2E coverage still shows policy, history, and quarantine before a held overview
response, the independent disk-capacity card renders before a held overview response, and the
mobile Storage flow has no horizontal overflow.
- Cache, handler, operations, scheduler, activity-coordinator, disk-capacity, and workspace
dependency tests pass after the changes.
- When a compatible post-change backend is available, a comparable cold overview request is timed
on the same host/settings as the baseline and the independent disk request is timed separately.
If the running backend predates the disk route, the baseline, deterministic fan-out barrier, and
held-overview managed E2E are recorded as the accepted non-mutating evidence instead.
- The Aug 5 `skipped_busy` behavior remains explainable by active `execution_preparing` and
`execution_running` leases; no cleanup is run while those resources are active.
## Verification
```bash
cd apps/backend && go test -race ./internal/backendapp ./internal/system/storage ./internal/agent/runtime/activity ./internal/agent/runtime/lifecycle
cd apps/web && pnpm e2e:run --project chromium tests/system/storage-maintenance.spec.ts
cd apps/web && pnpm e2e:run --project mobile-chrome tests/system/mobile-storage-maintenance.spec.ts
```
For the live timing comparison, use a read-only cold-cache setup and the existing backend request
duration logs. Do not drive the user's live browser or mutate storage data to manufacture a scan.
## Files likely touched
- `apps/web/e2e/tests/system/storage-maintenance.spec.ts`
- `apps/web/e2e/tests/system/mobile-storage-maintenance.spec.ts`
- implementation task handoff or validation notes for the before/after timing result
## Dependencies
Tasks 01, 03, and 04.
## Inputs
- Existing progressive-loading, capacity, dependency-option, and mobile Storage E2E scenarios
- Existing cache, capacity, dependency-cleanup, and idle-gate tests
- Baseline cold request: approximately 103 seconds on the captured host; warm request: effectively
instantaneous due to the successful overview cache
## Output contract
Return exact commands and results, available cold/warm timing evidence, mobile artifacts if a test
fails, idle-gate confirmation, and remaining optimization risks. Mark this task done only after
Task 01 is implemented and the regression evidence is complete.
## Result
The pre-change cold baseline was approximately 103 seconds on the captured host, with warm reads
effectively instantaneous from the 15-minute cache. The new deterministic fan-out test proves the
four measurements overlap, and the managed E2E progressive-loading test holds the overview while
the disk card and fast sections render. Chromium Storage E2E passed 6/6; mobile Storage E2E passed
4/4 after the touch disclosure flow was isolated from the existing scheduled-help tooltip.
The existing activity/lifecycle packages and storage race suite pass, along with backend lint and
the Windows disk-metrics compile check. Fresh desktop and mobile PR captures show the progress
card and independent loading state. The idle contract remains
unchanged: the Aug 5 `skipped_busy` entry correctly reported active `execution_preparing` and
`execution_running` resources. A same-dataset post-change live timing sample was not collected
because the currently running local backend predates this endpoint; its disk request returned 404.
The managed E2E evidence is the non-mutating substitute for independent capacity availability.
@@ -0,0 +1,75 @@
---
id: "03-disk-capacity-progress"
title: "Add disk capacity and progress card"
status: done
wave: 2
depends_on: []
plan: "plan.md"
spec: "../../specs/system-page/storage-overview-parallel-scan.md"
---
# Task 03: Add disk capacity and progress card
## Acceptance
- `GET /api/v1/system/storage/disk` measures the filesystem containing Kandev's storage root and
returns total, used, available, percentage, path, and availability/error fields.
- The disk request is independent from the cached overview and remains responsive while the
overview scan is held or cold.
- The Storage page shows localized used percentage, used/available/total sizes, and an accessible
progress bar with warning styling at 80% and critical styling at 90%.
- A capacity failure renders an unavailable card and does not block policy, history, quarantine, or
overview sections.
- Desktop and mobile layouts remain usable without horizontal overflow.
## Verification
```bash
cd apps/backend && go test -race ./internal/system/metrics ./internal/system/storage ./internal/backendapp
cd apps/web && pnpm run typecheck
cd apps/web && pnpm test -- --run components/settings/system/storage/storage-disk-capacity-card.test.tsx
```
The implementation must reuse or factor the existing cross-platform disk-free-space semantics in
`apps/backend/internal/system/metrics`; do not add a Unix-only storage API.
## Files likely touched
- `apps/backend/internal/system/metrics/disk_unix.go`
- `apps/backend/internal/system/metrics/disk_windows.go`
- `apps/backend/internal/system/metrics/*_test.go`
- `apps/backend/internal/system/storage/handler.go`
- `apps/backend/internal/system/storage/types.go`
- `apps/backend/internal/backendapp/storage_maintenance.go`
- `apps/backend/internal/system/storage/handler_test.go`
- `apps/web/lib/api/domains/system-api.ts`
- `apps/web/lib/types/system.ts`
- `apps/web/hooks/domains/system/use-storage-maintenance.ts`
- `apps/web/components/settings/system/storage/storage-disk-capacity-card.tsx`
- Storage API/component fixtures and tests
- localized system translation resources
## Dependencies
None. The card is intentionally independent of Task 01's overview fan-out.
## Inputs
- Spec: filesystem capacity indicator, API surface, and failure scenarios
- Existing `apps/backend/internal/system/metrics/disk_unix.go` and `disk_windows.go`
- Existing progressive-loading request orchestration in `use-storage-maintenance.ts`
- Existing `formatGigabytes` and localized Storage card patterns
## Output contract
Return a compact handoff capsule with API/test results, desktop/mobile evidence, exact percentage
semantics, and any platform-specific capacity limitations.
## Result
Added the cross-platform `GET /api/v1/system/storage/disk` endpoint and an independently loaded
capacity card. Unix statfs and Windows `GetDiskFreeSpaceEx` expose total, service-available, used,
and clamped percentage values. The UI renders the exact percentage and byte-derived sizes, with
accessible progress semantics plus 80%/90% warning styling; unavailable reads remain non-blocking.
Backend metrics/storage tests, web typecheck/lint, focused component tests, and the desktop/mobile
managed Storage E2E flows pass.
@@ -0,0 +1,96 @@
---
id: "04-workspace-dependency-cleanup"
title: "Add opt-in dependency cleanup"
status: done
wave: 2
depends_on: []
plan: "plan.md"
spec: "../../specs/system-page/storage-overview-parallel-scan.md"
---
# Task 04: Add opt-in dependency cleanup
## Acceptance
- Storage settings persist a default-off workspace dependency-cleanup option and reject malformed
settings without changing the previous saved value.
- Scheduled and full manual maintenance can prune only the fixed allowlist beneath Kandev-owned
task workspaces whose task is archived or deleted and whose authoritative inventory has no active
references.
- The resource-specific `workspace_dependencies` run uses the existing maintenance activity gate,
busy-resource response, Run anyway path, cancellation, retry, and history persistence.
- The provider never follows symlinks, crosses the task workspace root, deletes ambiguous directory
names, or mutates active/borrowed/restored workspaces. It revalidates before each deletion.
- Results report successfully pruned directories, reclaimed bytes, skips, and warnings, and retries
are idempotent. The directory count is the number of directories actually removed; skipped paths
are represented in warnings.
- A workspace can be restored after pruning with source and recovery metadata intact, with a clear
indication that dependencies may need to be installed again.
- The Workspaces policy card visibly lists every allowlisted directory Kandev checks before the
option is enabled. An adjacent info control exposes the recursive-search, excluded-folder,
safety, and reinstall explanation on hover, keyboard focus, and touch activation.
## Verification
```bash
cd apps/backend && go test -race ./internal/system/storage ./internal/system/storage/workspaces ./internal/backendapp ./internal/task/service
cd apps && pnpm --filter @kandev/web test -- --run components/settings/system/storage/storage-policy-card.test.tsx components/settings/system/storage/storage-maintenance-settings.test.tsx
```
Add filesystem fixtures for every allowlist entry and negative fixtures for `vendor`, `target`,
`.cache`, `.git`, symlinked directories, escaped paths, active workspaces, and incomplete inventory.
Use channels/barriers for state-change races rather than sleep-based tests.
## Files likely touched
- `apps/backend/internal/system/storage/types.go`
- `apps/backend/internal/system/storage/settings.go`
- `apps/backend/internal/system/storage/workspaces/types.go`
- `apps/backend/internal/system/storage/workspaces/provider.go`
- `apps/backend/internal/system/storage/workspaces/provider_test.go`
- `apps/backend/internal/system/storage/runner.go`
- `apps/backend/internal/system/storage/operations.go`
- `apps/backend/internal/system/storage/operations_test.go`
- `apps/backend/internal/backendapp/storage_maintenance.go`
- `apps/backend/internal/backendapp/storage_inventory.go`
- `apps/backend/internal/task/service/*` only if task/reactivation or restore coordination requires
an existing cleanup hook to be extended
- `apps/web/lib/types/system.ts`
- `apps/web/components/settings/system/storage/storage-policy-card.tsx`
- `apps/web/components/settings/system/storage/storage-maintenance-settings.tsx`
- `apps/web/components/settings/system/storage/storage-setting-help.tsx`
- `apps/web/e2e/tests/system/storage-maintenance.spec.ts`
- `apps/web/e2e/tests/system/mobile-storage-maintenance.spec.ts`
- localized system translation resources
## Dependencies
None for the backend contract. Task 02 integrates this behavior with the full desktop/mobile
regression suite.
## Inputs
- Spec: fixed allowlist, eligibility, retention interaction, safety guarantees, and run selection
- Existing workspace candidate/quarantine logic in `workspaces/provider.go`
- Existing authoritative inventory in `backendapp/storage_inventory.go`
- Existing settings normalization and `selectCleanupProviders` resource-selection behavior
- Existing quarantine restore and task resource cleanup tests
## Output contract
Return a compact handoff capsule with settings/API changes, provider safety results, race-test
results, run-history examples, user-facing warning copy, and any remaining package-manager coverage
gaps. Mark the task done only when no path can be deleted outside the allowlist and owned roots.
## Result
Implemented the persisted default-off setting and `workspace_dependencies` provider. The provider
fails closed on incomplete inventory, only accepts the exact allowlist (`node_modules`,
`bower_components`, `.pnpm-store`, `.yarn/cache`, `.yarn/unplugged`, `.venv`, `venv`, `.tox`,
`.nox`, `__pypackages__`, `Pods`, `.gradle`), skips ambiguous folders, never follows symlinks, and
revalidates ownership, containment, protection, and archived/deleted eligibility before each
deletion. Tests cover archived/deleted selection, active protection, exclusions, symlink payloads,
incomplete inventory, cancellation, byte/directory/workspace counts, default-off provider
selection, and restore after pruning with source and ownership metadata intact. The policy card
displays every allowlisted folder and the existing hover/focus/tap help control explains the
recursive scope and reinstall consequence.
+19
View File
@@ -135,6 +135,11 @@ policy saves reuse the displayed snapshot instead of scanning disk again. The pa
snapshot was last analyzed. Select **Analyze** to force a fresh scan; restarting the backend also
clears the in-memory snapshot.
The page also shows the current percentage used on the filesystem containing Kandev's storage,
along with used, available, and total capacity. This is host-volume capacity, not just the bytes
that Kandev can classify. The card warns at 80% full and uses a critical style at 90%; these
thresholds do not trigger cleanup.
Scheduled cleanup is disabled by default and runs only after the configured resource-idle quiet
period. Orphaned task workspaces and rotated Go caches move into Kandev's quarantine before
permanent deletion. Each entry shows its `delete_after` retention deadline: **Delete** and
@@ -151,6 +156,20 @@ checks still apply.
If scheduled cleanup is disabled, no independent quarantine sweeper runs: use a full **Run now** or
one of the quarantine actions when you want cleanup.
The Workspaces policy includes an off-by-default **Remove dependencies from archived or deleted
task workspaces** option. When enabled, a scheduled cleanup or the matching manual action can
recursively remove only these directories from eligible, unprotected Kandev task workspaces:
`node_modules`, `bower_components`, `.pnpm-store`, `.yarn/cache`, `.yarn/unplugged`, `.venv`,
`venv`, `.tox`, `.nox`, `__pypackages__`, `Pods`, and `.gradle`.
The Storage page always shows this exact list next to an information control. Kandev skips missing
directories, never follows symlinks, and does not target ambiguous names such as `vendor`, `target`,
`build`, `dist`, `.cache`, or `.git`. Only archived or deleted workspaces without active or
protected references qualify. This does not change the existing full-workspace lifecycle (seven
days of orphan grace followed by seven days of quarantine retention), and restoring a workspace
after dependency pruning may require reinstalling its dependencies.
Host-wide Docker build-cache and unused-image cleanup remain disabled until you confirm that Kandev
owns a dedicated Docker daemon.
Do not enable those rules on a daemon shared with unrelated workloads.
+1
View File
@@ -210,6 +210,7 @@ System pages (Radarr/Sonarr-style) for status, disk usage, database maintenance,
|---|---|
| [system-page](system-page/spec.md) | draft |
| [storage-maintenance](system-page/storage-maintenance.md) | building |
| [storage-overview-parallel-scan](system-page/storage-overview-parallel-scan.md) | shipped |
| [feature-toggles](feature-toggles/spec.md) | draft |
---
@@ -0,0 +1,269 @@
---
status: shipped
created: 2026-08-08
owner: kandev
---
# Storage maintenance scan, capacity, and dependency cleanup
This is a focused extension to [Storage maintenance](storage-maintenance.md). It improves cold
analysis time, gives the operator an immediate view of the filesystem capacity that contains
Kandev's storage, and adds an opt-in way to reclaim dependency directories from archived or deleted
task workspaces without deleting their source trees.
## Why
The Storage maintenance page currently waits for a cold overview scan before it can show the
analysis card. The page already requests policy, run history, quarantine, and overview data
independently, so those lightweight sections are not the source of the long wait. The backend
overview itself measures workspaces, the Go build cache, quarantine, and Docker usage one after
another.
The page also needs to answer two operator questions without requiring filesystem expertise: how
close is the host volume containing Kandev's data to full, and can dependency-heavy archived task
workspaces be trimmed while their source remains recoverable? The capacity signal must not wait for
the slow overview scan, and dependency cleanup must be explicitly enabled because restoring an
archived workspace after pruning requires dependencies to be installed again.
A live cold request took about 103 seconds on a host with approximately 102 GB of workspace data
and 38 GB of Go-cache data. The same route was effectively instantaneous on the next request
because the successful 15-minute overview cache was warm. The independent measurements should be
able to overlap so the cold path is governed primarily by the slowest source rather than the sum
of all four source times.
## What
### Parallel overview measurements
After the settings snapshot needed to construct the providers is loaded, the overview scan starts
these independent measurements concurrently:
- workspace usage and candidate classification;
- Go build-cache usage and candidate classification;
- quarantine totals;
- Docker usage, when Docker is configured and available.
The scan waits for all four results before returning the existing `Summary`. Each measurement keeps
its current value/error behavior: one failed source does not discard successful results from the
other sources, and the response shape remains unchanged.
The existing successful-snapshot cache, 15-minute freshness window, forced refresh used by manual
Analyze, concurrent-refresh coalescing, and stale-snapshot protection remain in force. No new
durable state is introduced by this scan optimization.
### Filesystem capacity indicator
The page adds a lightweight, independently loaded disk-capacity card. It reads the filesystem that
contains Kandev's storage root (the task/workspace storage volume), rather than adding Kandev-owned
byte counts to the host disk total. The card shows:
- a localized exact percentage such as **80% full**;
- a progress bar with the same value exposed through `aria-valuenow`;
- used, available, and total capacity in the existing GB formatting; and
- the measured storage path or a localized explanation when the capacity read is unavailable.
The capacity request is not held behind the cold overview scan and is not served from the 15-minute
overview snapshot. It can therefore show current host-volume pressure while the detailed analysis
card is still loading. The percentage is calculated from the filesystem's service-available bytes,
clamped to 0–100, and the API returns the raw byte values so the UI never has to infer them.
The indicator uses accessible warning styling when the volume reaches 80% full and critical styling
at 90% full. Those thresholds are presentation constants, not cleanup triggers; the card does not
automatically delete anything when a threshold is crossed.
### Opt-in dependency-directory cleanup
Maintenance settings add an off-by-default **Remove dependencies from archived or deleted task
workspaces** option under the Workspaces section. When enabled, scheduled maintenance and a full
manual run may recursively remove a fixed, safety-reviewed allowlist of dependency directories
inside Kandev-owned task workspace roots:
- `node_modules`, `bower_components`, and `.pnpm-store`;
- `.yarn/cache` and `.yarn/unplugged`;
- `.venv`, `venv`, `.tox`, `.nox`, and `__pypackages__`;
- `Pods` and `.gradle` when they are nested beneath an eligible task workspace.
The initial allowlist deliberately excludes ambiguous names such as `vendor`, `target`, `build`,
`dist`, `.cache`, and `.git`. Those may contain committed source, recovery metadata, or unrelated
artifacts and require a separate classification decision. The option does not accept arbitrary
paths or shell commands.
The Workspaces policy card always shows the exact allowlist in a localized, code-styled **Folders
Kandev will check** disclosure so the user can see what the option covers before enabling it. An
adjacent information icon provides hover, keyboard-focus, and tap behavior and explains that these
are directory names Kandev searches for recursively, that absent directories are simply skipped,
that excluded names are never targeted, and that restoring a pruned task may require reinstalling
dependencies. The list and help content remain usable on mobile; hover is an enhancement, not the
only way to access the explanation.
Dependency pruning uses the same fail-closed workspace ownership and activity inventory as orphan
workspace cleanup. A target must be beneath a real Kandev-owned task workspace, belong to a task that
is archived or deleted, and have no active execution, session worktree, environment borrower, or
other protected reference. The provider revalidates the target before each destructive operation.
Deleted tasks are identified from the ownership marker and the absence of an authoritative task
row; an incomplete inventory causes the provider to make no changes.
This option does not change the existing full-workspace lifecycle. The current defaults are seven
days of orphan grace followed by seven days of quarantine retention, not a single two-week age
threshold. Dependency pruning can reclaim the large dependency directories during that lifecycle
while preserving source files and workspace metadata. A later restore succeeds with the remaining
workspace, but the UI and run result explain that dependencies were removed and may need to be
reinstalled.
The existing manual resource-selection contract gains the provider name
`workspace_dependencies`, allowing an explicit **Clean workspace dependencies** action in the
Workspaces settings card. It uses the normal maintenance activity gate, busy-resource feedback,
Run anyway behavior, cancellation, retry, and run-history reporting. It never runs as part of
read-only Analyze.
### Page behavior
The Storage maintenance page continues to render policy, history, quarantine, and the capacity card
as soon as their independent requests complete. Only the analysis card remains in its existing
loading state while the cold overview scan is running. A cached overview continues to load without a
new filesystem scan, and manual Analyze continues to request a fresh read-only snapshot. Enabling
dependency cleanup adds one policy control and one workspace-specific action without changing the
mobile one-column composition.
### Idle behavior invariant
This change does not alter cleanup scheduling or task admission. The existing resource-idle gate
continues to block scheduled cleanup when instrumented execution, shell/test/setup/cleanup work,
or Docker image builds are active. The quiet period is measured from the last released task
activity, and a newly admitted task cancels and drains a maintenance lease before proceeding.
Manual Analyze remains read-only and is not idle-gated. The existing `skipped_busy` history entry
that reports `execution_preparing` and `execution_running` is therefore a correct scheduled-run
outcome, not an overview-scan failure.
## Success criteria
- A deterministic backend test proves all four independent measurements have started before any
blocking measurement is released; the test must not rely on a timing race.
- The same test proves the returned summary and per-source errors match the serial implementation.
- When a compatible post-change backend is available, a cold live overview measurement is captured
after implementation using the existing request timing logs. The result should be bounded by the
slowest provider plus join overhead, rather than the sum of provider durations, on the same host
and dataset. If the only running backend predates the capacity route, the baseline timing plus the
deterministic fan-out barrier and held-overview managed E2E are the accepted non-mutating evidence
until a compatible runtime is available.
- Existing cache tests still prove that warm reads, forced Analyze refreshes, coalesced misses, and
failed refreshes behave exactly as before.
- Existing desktop and mobile Storage maintenance flows continue to show fast sections while an
overview is pending, and the capacity card renders independently with no horizontal overflow.
- Capacity tests verify exact byte fields, percentage clamping, 80%/90% presentation thresholds,
unavailable filesystems, and accessible progress-bar semantics.
- Dependency-cleanup tests verify the default-off setting, allowlist-only deletion, byte/count
reporting, symlink and path-containment safety, active-workspace protection, archived/deleted
eligibility, cancellation, retry, and restore-after-prune behavior.
- Desktop and mobile UI tests verify the visible allowlist, the info control's hover/focus/tap
explanation, excluded-folder copy, and no horizontal overflow.
- Existing activity-coordinator and scheduled-runner tests continue to prove the idle behavior
described above.
## Scenarios
### Cold overview starts independent sources together
Given no cached successful overview, when `GET /api/v1/system/storage` or manual Analyze begins,
then settings are loaded once, all independent measurements start without waiting for one another,
and the response contains the same summary fields as before.
### Capacity is visible while analysis is pending
Given a slow or cold overview scan, when the Storage page opens, then the independent capacity
request can render the filesystem percentage and progress bar before the detailed analysis finishes.
If the capacity read fails, the card shows an unavailable state without blocking the other sections.
### Dependency cleanup is opt-in and scoped
Given the dependency option is disabled, when scheduled or manual maintenance runs, then no
dependency directory is removed. Given it is enabled and an archived or deleted workspace is
unprotected, when the workspace-dependency provider runs, then only allowlisted dependency
directories beneath that workspace are removed and the run records their count and reclaimed bytes.
### The UI explains the cleanup scope
Given the Workspaces policy card is visible, then it shows the exact allowlisted folder names before
the user enables the option. Its information control explains the recursive search, skipped absent
folders, excluded folder names, safety checks, and reinstall consequence through hover, keyboard
focus, and touch activation.
### Active or restored workspaces are protected
Given a workspace is active, borrowed by an active task, has an active execution/session handle, or
changes state while pruning, then the provider skips it without deleting any dependency directory.
Given a user restores a workspace after dependencies were pruned, then the source tree and recovery
metadata remain available and the result explains that dependencies must be reinstalled.
### One source fails
Given one measurement returns an error, when the other measurements complete, then successful
source results remain available, the failed source reports its existing unavailable/error state,
and the request does not deadlock or leak measurement goroutines.
### Cached overview is reused
Given a successful snapshot younger than 15 minutes, when the page is opened, refreshed, or policy
settings are saved, then the cached snapshot is returned without starting another filesystem or
Docker scan.
### Manual Analyze remains read-only
Given active task execution, when the user selects Analyze, then the request may run because it
does not acquire the maintenance idle lease and it does not delete or mutate storage.
### Scheduled cleanup remains idle-gated
Given `execution_preparing` or `execution_running` activity is active, when the scheduled cleanup
interval fires, then the run is persisted as `skipped_busy` with those stable resource labels and
no cleanup provider runs. When a task is admitted while maintenance holds the lease, maintenance
is cancelled and drained before the task proceeds.
## Failure modes
- A provider returns an error: preserve its current per-source error representation while joining
the other provider results.
- The request context is cancelled: stop waiting and return according to the existing handler/job
contract without leaving background work or a shared cache flight stranded.
- Multiple callers miss or force-refresh together: preserve the existing single-flight cache
behavior and ensure a stale completion cannot overwrite a newer snapshot.
- Docker is unavailable: preserve the current unavailable Docker summary and do not make other
measurements wait on a Docker-specific retry.
- Filesystem capacity is unavailable or times out: return an unavailable capacity card and continue
loading policy, history, quarantine, and overview independently.
- A dependency target is a symlink, escapes the workspace root, or has ambiguous ownership: skip it
and record a warning; never follow it or fall back to arbitrary recursive deletion.
- A task becomes active or is restored during dependency pruning: cancel/skip the affected target,
leave it intact, and allow the maintenance job to retry safely.
## API surface
The existing `GET /api/v1/system/storage` and `POST /api/v1/system/storage/analyze` contracts remain
the public entry points for cached and forced overview reads. Add a lightweight
`GET /api/v1/system/storage/disk` response with `path`, `total_bytes`, `used_bytes`,
`available_bytes`, `used_percent`, `available`, and an optional `warning`. Extend persisted storage
settings with the workspace dependency-cleanup boolean, and expose `workspace_dependencies` as a
valid resource name for the existing `POST /api/v1/system/storage/run` selection field. No other
route or API contract changes are required.
## Persistence guarantees
The disk-capacity response is read-only and is not persisted or included in the 15-minute overview
cache. The dependency-cleanup preference is persisted with the existing install-wide storage
settings object and defaults to false. Maintenance history continues to persist cleanup results,
including dependency counts/bytes and scheduled `skipped_busy` outcomes. Overview snapshots retain
their existing TTL and invalidation rules.
## Out of scope
- Changing the 15-minute cache TTL, cache ownership, or refresh semantics.
- Parallelizing directory traversal inside an individual workspace or Go-cache tree; that can be a
separate bounded-worker optimization if the post-change measurements show it is still dominant.
- Changing storage ownership, full-workspace grace/retention rules, quiet-period semantics, resource
labels, or task preemption behavior.
- Allowing arbitrary dependency paths, shell commands, generic `vendor`/`target`/build-directory
deletion, or host-wide package-manager cache cleanup.
- Automatically pruning on the disk-percentage threshold; the progress bar is informational only.
- Replacing the existing progressive-loading page composition; the new capacity card is an
independently loaded addition and uses the existing mobile one-column pattern.