feat(data): add TTL-based document cache eviction and review fixes

Add configurable cache eviction that removes extracted document files
older than cache_ttl_days (default 30) on startup. Controlled via
config file or MICASA_CACHE_TTL_DAYS env var; set to 0 to disable.

Also addresses review feedback on the audit fix commit:
- Remove unreachable WarrantyExpiry nil guard in dashExpiringRows
  (filtered by SQL WHERE IS NOT NULL + loadDashboardAt nil check)
- Add compile-time test ensuring form data structs have no reference
  fields (cloneFormData shallow-copy safety)
- Strengthen openFileCmd trust-boundary comment
- Fix gosec G204 nolint placement in main_test.go so directives are
  on the exec.Command line, not a detached comment
- Fix EvictStaleCache to accept dir param for proper test isolation
  (xdg.CacheHome is set at init, not affected by t.Setenv)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cpcloud

cmd/micasa/main.go

@@ -66,6 +66,13 @@ func main() {
 	if err := store.SetMaxDocumentSize(cfg.Documents.MaxFileSize); err != nil {
 		fail("configure document size limit", err)
 	}
+	cacheDir, err := data.DocumentCacheDir()
+	if err != nil {
+		fail("resolve document cache directory", err)
+	}
+	if _, err := data.EvictStaleCache(cacheDir, cfg.Documents.CacheTTLDays); err != nil {
+		fail("evict stale cache", err)
+	}
 
 	opts := app.Options{
 		DBPath:     dbPath,

cmd/micasa/main_test.go

@@ -82,7 +82,13 @@ func buildTestBinary(t *testing.T) string {
 		ext = ".exe"
 	}
 	bin := filepath.Join(t.TempDir(), "micasa"+ext)
-	cmd := exec.Command("go", "build", "-o", bin, ".")
+	cmd := exec.Command( //nolint:gosec // test helper with constant args
+		"go",
+		"build",
+		"-o",
+		bin,
+		".",
+	)
 	cmd.Env = append(os.Environ(), "CGO_ENABLED=0")
 	out, err := cmd.CombinedOutput()
 	require.NoError(t, err, "build failed:\n%s", out)
@@ -96,7 +102,8 @@ func TestVersion_DevShowsCommitHash(t *testing.T) {
 		t.Skip("no .git directory; VCS info unavailable (e.g. Nix sandbox)")
 	}
 	bin := buildTestBinary(t)
-	out, err := exec.Command(bin, "--version").Output()
+	verCmd := exec.Command(bin, "--version") //nolint:gosec // test binary path from buildTestBinary
+	out, err := verCmd.Output()
 	require.NoError(t, err, "--version failed")
 	got := strings.TrimSpace(string(out))
 	// Built inside a git repo: expect a hex hash, possibly with -dirty.
@@ -110,13 +117,14 @@ func TestVersion_Injected(t *testing.T) {
 		ext = ".exe"
 	}
 	bin := filepath.Join(t.TempDir(), "micasa"+ext)
-	cmd := exec.Command("go", "build",
+	cmd := exec.Command("go", "build", //nolint:gosec // test with constant args
 		"-ldflags", "-X main.version=1.2.3",
 		"-o", bin, ".")
 	cmd.Env = append(os.Environ(), "CGO_ENABLED=0")
 	out, err := cmd.CombinedOutput()
 	require.NoError(t, err, "build failed:\n%s", out)
-	verOut, err := exec.Command(bin, "--version").Output()
+	verCmd := exec.Command(bin, "--version") //nolint:gosec // test binary path from above
+	verOut, err := verCmd.Output()
 	require.NoError(t, err, "--version failed")
 	assert.Equal(t, "1.2.3", strings.TrimSpace(string(verOut)))
 }

internal/app/dashboard.go

@@ -671,10 +671,10 @@ func (m *Model) dashProjectRows() []dashRow {
 func (m *Model) dashExpiringRows() []dashRow {
 	d := m.dashboard
 	var rows []dashRow
+	// WarrantyExpiry is guaranteed non-nil here: ListExpiringWarranties uses
+	// WHERE warranty_expiry IS NOT NULL, and loadDashboardAt skips nil entries
+	// before populating ExpiringWarranties.
 	for _, w := range d.ExpiringWarranties {
-		if w.Appliance.WarrantyExpiry == nil {
-			continue
-		}
 		overdue := w.DaysFromNow < 0
 		nameStyle := m.styles.DashUpcoming
 		if overdue {

internal/app/dashboard_load_test.go

@@ -193,3 +193,23 @@ func TestLoadDashboardAtBuildsNav(t *testing.T) {
 	assert.NotEmpty(t, m.dashNav)
 	assert.Equal(t, tabMaintenance, m.dashNav[0].Tab)
 }
+
+func TestLoadDashboardExcludesAppliancesWithoutWarranty(t *testing.T) {
+	m := newTestModelWithStore(t)
+
+	// One appliance with warranty in range, one without any warranty.
+	expiry := time.Date(2026, 3, 15, 0, 0, 0, 0, time.UTC)
+	require.NoError(t, m.store.CreateAppliance(data.Appliance{
+		Name:           "Fridge",
+		WarrantyExpiry: &expiry,
+	}))
+	require.NoError(t, m.store.CreateAppliance(data.Appliance{
+		Name: "Toaster",
+	}))
+
+	now := time.Date(2026, 2, 1, 0, 0, 0, 0, time.UTC)
+	require.NoError(t, m.loadDashboardAt(now))
+
+	require.Len(t, m.dashboard.ExpiringWarranties, 1)
+	assert.Equal(t, "Fridge", m.dashboard.ExpiringWarranties[0].Appliance.Name)
+}

internal/app/docopen.go

@@ -41,6 +41,9 @@ func (m *Model) openSelectedDocument() tea.Cmd {
 // openFileCmd returns a tea.Cmd that opens the given path with the OS viewer.
 // The command runs to completion so exit-status errors (e.g. no handler for
 // the MIME type) are captured and returned as an openFileResultMsg.
+//
+// Only called from openSelectedDocument with a path returned by
+// Store.ExtractDocument (always under the XDG cache directory).
 func openFileCmd(path string) tea.Cmd {
 	return func() tea.Msg {
 		var cmd *exec.Cmd

internal/app/form_validators_test.go

@@ -4,6 +4,7 @@
 package app
 
 import (
+	"reflect"
 	"testing"
 	"time"
 
@@ -214,3 +215,63 @@ func TestServiceLogFormValuesNoVendor(t *testing.T) {
 	assert.Zero(t, got.VendorID)
 	assert.Empty(t, got.Cost)
 }
+
+func TestFormDirtyDetectionUserFlow(t *testing.T) {
+	m := newTestModel()
+
+	// Simulate: user opens an appliance edit form with pre-filled values.
+	values := &applianceFormData{
+		Name:  "Fridge",
+		Brand: "Samsung",
+		Cost:  "$899.00",
+	}
+	m.formData = values
+	m.snapshotForm()
+
+	// User hasn't changed anything yet — form should not be dirty.
+	m.checkFormDirty()
+	assert.False(t, m.formDirty, "form should not be dirty before any edits")
+
+	// User edits the brand field.
+	values.Brand = "LG"
+	m.checkFormDirty()
+	assert.True(t, m.formDirty, "form should be dirty after editing a field")
+
+	// User reverts the edit back to the original value.
+	values.Brand = "Samsung"
+	m.checkFormDirty()
+	assert.False(t, m.formDirty, "form should not be dirty after reverting")
+}
+
+// TestFormDataStructsHaveNoReferenceFields ensures cloneFormData's shallow
+// copy is safe. If any form data struct gains a pointer, slice, or map
+// field, this test will catch it -- the snapshot would share that reference
+// and dirty-detection via reflect.DeepEqual would silently break.
+func TestFormDataStructsHaveNoReferenceFields(t *testing.T) {
+	structs := []any{
+		projectFormData{},
+		applianceFormData{},
+		maintenanceFormData{},
+		vendorFormData{},
+		quoteFormData{},
+		serviceLogFormData{},
+		documentFormData{},
+		houseFormData{},
+	}
+	for _, s := range structs {
+		rt := reflect.TypeOf(s)
+		t.Run(rt.Name(), func(t *testing.T) {
+			for i := range rt.NumField() {
+				f := rt.Field(i)
+				switch f.Type.Kind() { //nolint:exhaustive // only reference kinds matter here
+				case reflect.Ptr, reflect.Slice, reflect.Map,
+					reflect.Chan, reflect.Func, reflect.Interface:
+					t.Errorf(
+						"field %s.%s is %s -- cloneFormData requires value-only fields",
+						rt.Name(), f.Name, f.Type.Kind(),
+					)
+				}
+			}
+		})
+	}
+}

internal/config/config.go

@@ -44,12 +44,18 @@ type Documents struct {
 	// MaxFileSize is the largest file (in bytes) that can be imported as a
 	// document attachment. Default: 50 MiB.
 	MaxFileSize int64 `toml:"max_file_size"`
+
+	// CacheTTLDays is the number of days an extracted document cache entry
+	// is kept before being evicted on the next startup. Set to 0 to disable
+	// eviction. Default: 30.
+	CacheTTLDays int `toml:"cache_ttl_days"`
 }
 
 const (
-	DefaultBaseURL = "http://localhost:11434/v1"
-	DefaultModel   = "qwen3"
-	configRelPath  = "micasa/config.toml"
+	DefaultBaseURL      = "http://localhost:11434/v1"
+	DefaultModel        = "qwen3"
+	DefaultCacheTTLDays = 30
+	configRelPath       = "micasa/config.toml"
 )
 
 // defaults returns a Config with all default values populated.
@@ -60,7 +66,8 @@ func defaults() Config {
 			Model:   DefaultModel,
 		},
 		Documents: Documents{
-			MaxFileSize: data.MaxDocumentSize,
+			MaxFileSize:  data.MaxDocumentSize,
+			CacheTTLDays: DefaultCacheTTLDays,
 		},
 	}
 }
@@ -101,6 +108,13 @@ func LoadFromPath(path string) (Config, error) {
 		)
 	}
 
+	if cfg.Documents.CacheTTLDays < 0 {
+		return cfg, fmt.Errorf(
+			"documents.cache_ttl_days must be non-negative, got %d",
+			cfg.Documents.CacheTTLDays,
+		)
+	}
+
 	return cfg, nil
 }
 
@@ -123,6 +137,11 @@ func applyEnvOverrides(cfg *Config) {
 			cfg.Documents.MaxFileSize = n
 		}
 	}
+	if ttl := os.Getenv("MICASA_CACHE_TTL_DAYS"); ttl != "" {
+		if n, err := strconv.Atoi(ttl); err == nil {
+			cfg.Documents.CacheTTLDays = n
+		}
+	}
 }
 
 // ExampleTOML returns a commented config file suitable for writing as a
@@ -148,5 +167,9 @@ model = "` + DefaultModel + `"
 [documents]
 # Maximum file size (in bytes) for document imports. Default: 50 MiB.
 # max_file_size = 52428800
+
+# Days to keep extracted document cache entries before evicting on startup.
+# Set to 0 to disable eviction. Default: 30.
+# cache_ttl_days = 30
 `
 }

internal/config/config_test.go

@@ -137,3 +137,37 @@ func TestMaxDocumentSizeRejectsInvalid(t *testing.T) {
 		})
 	}
 }
+
+func TestDefaultCacheTTLDays(t *testing.T) {
+	cfg, err := LoadFromPath(filepath.Join(t.TempDir(), "nope.toml"))
+	require.NoError(t, err)
+	assert.Equal(t, DefaultCacheTTLDays, cfg.Documents.CacheTTLDays)
+}
+
+func TestCacheTTLDaysFromFile(t *testing.T) {
+	path := writeConfig(t, "[documents]\ncache_ttl_days = 7\n")
+	cfg, err := LoadFromPath(path)
+	require.NoError(t, err)
+	assert.Equal(t, 7, cfg.Documents.CacheTTLDays)
+}
+
+func TestCacheTTLDaysZeroDisables(t *testing.T) {
+	path := writeConfig(t, "[documents]\ncache_ttl_days = 0\n")
+	cfg, err := LoadFromPath(path)
+	require.NoError(t, err)
+	assert.Equal(t, 0, cfg.Documents.CacheTTLDays)
+}
+
+func TestCacheTTLDaysEnvOverride(t *testing.T) {
+	t.Setenv("MICASA_CACHE_TTL_DAYS", "14")
+	cfg, err := LoadFromPath(filepath.Join(t.TempDir(), "nope.toml"))
+	require.NoError(t, err)
+	assert.Equal(t, 14, cfg.Documents.CacheTTLDays)
+}
+
+func TestCacheTTLDaysRejectsNegative(t *testing.T) {
+	path := writeConfig(t, "[documents]\ncache_ttl_days = -1\n")
+	_, err := LoadFromPath(path)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "must be non-negative")
+}

internal/data/doccache.go

@@ -4,9 +4,11 @@
 package data
 
 import (
+	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
+	"time"
 )
 
 // ExtractDocument writes the document's BLOB content to the XDG cache
@@ -31,8 +33,15 @@ func (s *Store) ExtractDocument(id uint) (string, error) {
 	name := doc.ChecksumSHA256 + "-" + filepath.Base(doc.FileName)
 	cachePath := filepath.Join(cacheDir, name)
 
-	// Cache hit: file exists with correct size.
+	// Cache hit: file exists with correct size. Touch the ModTime so the
+	// TTL-based eviction in EvictStaleCache treats it as recently used.
 	if info, statErr := os.Stat(cachePath); statErr == nil && info.Size() == doc.SizeBytes {
+		now := time.Now()
+		_ = os.Chtimes(
+			cachePath,
+			now,
+			now,
+		) // best-effort; stale ModTime just means earlier re-extraction
 		return cachePath, nil
 	}
 
@@ -41,3 +50,39 @@ func (s *Store) ExtractDocument(id uint) (string, error) {
 	}
 	return cachePath, nil
 }
+
+// EvictStaleCache removes cached document files from dir that haven't been
+// modified in the given number of days. A ttlDays of 0 disables eviction.
+// Returns the number of files removed and any error encountered while listing
+// the directory (individual file removal errors are skipped).
+func EvictStaleCache(dir string, ttlDays int) (int, error) {
+	if ttlDays <= 0 || dir == "" {
+		return 0, nil
+	}
+
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return 0, nil // cache dir doesn't exist yet; nothing to evict
+		}
+		return 0, fmt.Errorf("list cache dir: %w", err)
+	}
+
+	cutoff := time.Now().AddDate(0, 0, -ttlDays)
+	removed := 0
+	for _, entry := range entries {
+		if entry.IsDir() {
+			continue
+		}
+		info, err := entry.Info()
+		if err != nil {
+			continue
+		}
+		if info.ModTime().Before(cutoff) {
+			if os.Remove(filepath.Join(dir, entry.Name())) == nil {
+				removed++
+			}
+		}
+	}
+	return removed, nil
+}