2 files changed, 120 insertions, 0 deletions
diff --git a/internal/liturgy/clean_test.go b/internal/liturgy/clean_test.go
new file mode 100644
index 0000000..4dbe0d9
--- /dev/null
+++ b/internal/liturgy/clean_test.go
@@ -0,0 +1,72 @@
+package liturgy
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+// TestCleanCache exercises CleanCache's file-selection rules: only
+// "<YYYY-MM-DD>.html"/".json" pairs older than the cutoff are removed; a
+// recent pair and a non-matching file are left untouched. The cutoff is a
+// fixed literal (not time.Now-derived) so the test is deterministic; only
+// the "recent" fixture is anchored to today, and only to make sure it lands
+// safely on the "keep" side of that fixed cutoff.
+func TestCleanCache(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("XDG_CACHE_HOME", dir)
+	cacheDir := filepath.Join(dir, "lectio")
+	if err := os.MkdirAll(cacheDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	recent := time.Now().Format("2006-01-02")
+	files := map[string]string{
+		"2020-01-01.html": "<html>old</html>",
+		"2020-01-01.json": `[{"Heading":"old"}]`,
+		recent + ".html":  "<html>recent</html>",
+		"notes.txt":       "not a cache file",
+	}
+	for name, content := range files {
+		if err := os.WriteFile(filepath.Join(cacheDir, name), []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	cutoff := time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)
+	removed, freed, err := CleanCache(cutoff)
+	if err != nil {
+		t.Fatalf("CleanCache: %v", err)
+	}
+	if removed != 2 {
+		t.Errorf("removed = %d, want 2", removed)
+	}
+	if freed <= 0 {
+		t.Errorf("freed = %d, want > 0", freed)
+	}
+
+	for _, gone := range []string{"2020-01-01.html", "2020-01-01.json"} {
+		if _, err := os.Stat(filepath.Join(cacheDir, gone)); !os.IsNotExist(err) {
+			t.Errorf("%s still exists after CleanCache, want removed", gone)
+		}
+	}
+	for _, kept := range []string{recent + ".html", "notes.txt"} {
+		if _, err := os.Stat(filepath.Join(cacheDir, kept)); err != nil {
+			t.Errorf("%s missing after CleanCache, want kept: %v", kept, err)
+		}
+	}
+}
+
+// TestCleanCacheMissingDir checks the documented no-op: a cache dir that
+// does not exist yet is not an error.
+func TestCleanCacheMissingDir(t *testing.T) {
+	t.Setenv("XDG_CACHE_HOME", t.TempDir())
+	removed, freed, err := CleanCache(time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC))
+	if err != nil {
+		t.Fatalf("CleanCache on missing dir: %v", err)
+	}
+	if removed != 0 || freed != 0 {
+		t.Errorf("CleanCache on missing dir = (%d, %d), want (0, 0)", removed, freed)
+	}
+}
diff --git a/internal/liturgy/fetch.go b/internal/liturgy/fetch.go
index 32eaaad..f4f6992 100644
--- a/internal/liturgy/fetch.go
+++ b/internal/liturgy/fetch.go
@@ -41,6 +41,12 @@ var publishedRe = regexp.MustCompile(`id="\w*0all"`)
 // validate its own input first.
 var dateRe = regexp.MustCompile(`^\d{4}-\d{2}-\d{2}$`)
 
+// cacheFileRe matches the cache file names Load/Harvest write into
+// cacheDir(): "<YYYY-MM-DD>.html" or "<YYYY-MM-DD>.json". CleanCache uses it
+// to tell cache entries apart from anything else that might be sitting in
+// the directory.
+var cacheFileRe = regexp.MustCompile(`^(\d{4}-\d{2}-\d{2})\.(html|json)$`)
+
 // Options controls how Load resolves a day's readings.
 type Options struct {
 	// Date is the day to load, formatted YYYY-MM-DD.
@@ -135,6 +141,48 @@ func Load(opts Options) ([]Section, error) {
 	return secs, nil
 }
 
+// CleanCache removes cached readings whose date is before `before` from
+// cacheDir(). It matches only files named "<YYYY-MM-DD>.html"/".json";
+// anything else in the directory (e.g. a stray notes.txt, or the sigla
+// store, which lives elsewhere entirely) is left alone. A missing cache dir
+// is not an error -- it just means there is nothing to clean yet.
+func CleanCache(before time.Time) (removed int, freed int64, err error) {
+	dir := cacheDir()
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return 0, 0, nil
+		}
+		return 0, 0, err
+	}
+
+	for _, entry := range entries {
+		if entry.IsDir() {
+			continue
+		}
+		m := cacheFileRe.FindStringSubmatch(entry.Name())
+		if m == nil {
+			continue
+		}
+		date, perr := time.Parse("2006-01-02", m[1])
+		if perr != nil || !date.Before(before) {
+			continue
+		}
+
+		path := filepath.Join(dir, entry.Name())
+		info, serr := os.Stat(path)
+		if serr != nil {
+			return removed, freed, serr
+		}
+		if rerr := os.Remove(path); rerr != nil {
+			return removed, freed, rerr
+		}
+		removed++
+		freed += info.Size()
+	}
+	return removed, freed, nil
+}
+
 // loadJSONCache reads and unmarshals the parsed-sections cache file.
 func loadJSONCache(path string) ([]Section, error) {
 	data, err := os.ReadFile(path)