refactor: extract shared CardStore into internal/store to eliminate duplication

FindCardDirectory, FindOrCreateCardDirectory, GenerateCardID and the
ScanWords helper previously existed in both internal/utils.go (as
standalone functions) and were partially duplicated in
internal/gui/card_service.go (readWordFromDir, ScanExistingWords).

Introduce internal/store.CardStore as the single source of truth for
all on-disk card-directory operations. Both internal/processor and
internal/gui now hold a *store.CardStore field and delegate to it,
removing the last copy of the directory-scanning loop from
card_service.go. internal/utils.go keeps thin forwarding wrappers for
callers that import the root internal package.

Also adds table-driven unit tests for the new package covering
FindCardDirectory (including legacy _word.txt fallback),
FindOrCreateCardDirectory, and CardStore.ScanWords.

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

2 files changed, 311 insertions, 0 deletions

diff --git a/internal/store/store.go b/internal/store/store.go
new file mode 100644
index 0000000..16f50ba
--- /dev/null
+++ b/internal/store/store.go
@@ -0,0 +1,171 @@
+// Package store provides the CardStore type, a single shared repository for
+// locating and creating on-disk card directories. Both the processor and gui
+// packages use CardStore so the directory-scanning logic lives in exactly one
+// place (DRY / SRP).
+//
+// Dependency position: store imports only the standard library, so every other
+// internal package may import it without creating import cycles.
+package store
+
+import (
+	"crypto/md5"
+	"encoding/hex"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+)
+
+// CardStore manages the on-disk layout of word card directories under a single
+// output directory. It is safe to create multiple instances pointing at the
+// same directory; all operations are stateless file-system reads/writes.
+type CardStore struct {
+	outputDir string
+}
+
+// New constructs a CardStore rooted at outputDir.
+func New(outputDir string) *CardStore {
+	return &CardStore{outputDir: outputDir}
+}
+
+// OutputDir returns the root output directory this store operates on.
+func (cs *CardStore) OutputDir() string {
+	return cs.outputDir
+}
+
+// FindCardDirectory searches the output directory for a subdirectory whose
+// word.txt (or legacy _word.txt) matches word. Returns the directory path or
+// an empty string when no matching directory is found.
+func (cs *CardStore) FindCardDirectory(word string) string {
+	return FindCardDirectory(cs.outputDir, word)
+}
+
+// FindOrCreateCardDirectory returns the existing card directory for word, or
+// creates a new one with a generated card ID and writes word.txt so subsequent
+// calls can locate the directory.
+func (cs *CardStore) FindOrCreateCardDirectory(word string) string {
+	return FindOrCreateCardDirectory(cs.outputDir, word)
+}
+
+// ScanWords scans the output directory for subdirectories that contain at
+// least one content file (word.txt or legacy _word.txt) and passes a basic
+// content check provided by the caller. It returns a sorted list of Bulgarian
+// words found. The hasContent predicate receives the full path of each
+// candidate directory; pass nil to accept all directories that have a word
+// file.
+func (cs *CardStore) ScanWords(hasContent func(wordDir string) bool) []string {
+	entries, err := os.ReadDir(cs.outputDir)
+	if err != nil {
+		// Output directory does not exist yet; return empty list silently.
+		return []string{}
+	}
+
+	words := make([]string, 0, len(entries))
+
+	for _, entry := range entries {
+		if !entry.IsDir() || strings.HasPrefix(entry.Name(), ".") {
+			continue
+		}
+
+		wordDir := filepath.Join(cs.outputDir, entry.Name())
+
+		word, ok := readWordFromDir(wordDir)
+		if !ok {
+			continue
+		}
+
+		if hasContent == nil || hasContent(wordDir) {
+			words = append(words, word)
+		}
+	}
+
+	sort.Strings(words)
+	return words
+}
+
+// GenerateCardID creates a unique ID for a card based on the current timestamp
+// and an MD5 hash of the Bulgarian word.
+// Format: epochMillis_md5(word)[:8]
+func GenerateCardID(bulgarianWord string) string {
+	epochMillis := time.Now().UnixNano() / 1_000_000
+	hash := md5.Sum([]byte(bulgarianWord))
+	hashStr := hex.EncodeToString(hash[:])[:8]
+	return fmt.Sprintf("%d_%s", epochMillis, hashStr)
+}
+
+// FindCardDirectory is the package-level (non-method) version of the directory
+// search. It searches outputDir for a subdirectory whose word.txt (or legacy
+// _word.txt) content matches word and returns its path, or "" if not found.
+func FindCardDirectory(outputDir, word string) string {
+	entries, err := os.ReadDir(outputDir)
+	if err != nil {
+		return ""
+	}
+
+	for _, entry := range entries {
+		if !entry.IsDir() || strings.HasPrefix(entry.Name(), ".") {
+			continue
+		}
+
+		dirPath := filepath.Join(outputDir, entry.Name())
+		if found := readWordMatch(dirPath, word); found {
+			return dirPath
+		}
+	}
+
+	return ""
+}
+
+// FindOrCreateCardDirectory returns the existing card directory for word inside
+// outputDir, or creates a new one with a generated card ID. It also writes
+// word.txt so subsequent calls can find the directory.
+func FindOrCreateCardDirectory(outputDir, word string) string {
+	if dir := FindCardDirectory(outputDir, word); dir != "" {
+		return dir
+	}
+
+	cardID := GenerateCardID(word)
+	wordDir := filepath.Join(outputDir, cardID)
+
+	if err := os.MkdirAll(wordDir, 0755); err != nil {
+		fmt.Printf("Warning: failed to create word directory: %v\n", err)
+		return outputDir
+	}
+
+	if err := os.WriteFile(filepath.Join(wordDir, "word.txt"), []byte(word), 0644); err != nil {
+		fmt.Printf("Warning: failed to save word metadata: %v\n", err)
+	}
+
+	return wordDir
+}
+
+// readWordFromDir reads the Bulgarian word stored in word.txt (or the legacy
+// _word.txt) inside a card directory. Returns the word and true on success.
+func readWordFromDir(wordDir string) (string, bool) {
+	wordFile := filepath.Join(wordDir, "word.txt")
+	data, err := os.ReadFile(wordFile)
+	if err != nil {
+		// Backward-compatible fallback: old format used _word.txt.
+		wordFile = filepath.Join(wordDir, "_word.txt")
+		data, err = os.ReadFile(wordFile)
+		if err != nil {
+			return "", false
+		}
+	}
+
+	word := strings.TrimSpace(string(data))
+	if word == "" {
+		return "", false
+	}
+
+	return word, true
+}
+
+// readWordMatch returns true when the card directory at dirPath contains a
+// word file whose trimmed content equals word.
+func readWordMatch(dirPath, word string) bool {
+	found, ok := readWordFromDir(dirPath)
+	return ok && found == word
+}
diff --git a/internal/store/store_test.go b/internal/store/store_test.go
new file mode 100644
index 0000000..6d34d0c
--- /dev/null
+++ b/internal/store/store_test.go
@@ -0,0 +1,140 @@
+package store_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"codeberg.org/snonux/totalrecall/internal/store"
+)
+
+// TestFindCardDirectory verifies that FindCardDirectory locates a directory by
+// its word.txt content and returns an empty string when no match exists.
+func TestFindCardDirectory(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	// Create a card directory with a word file.
+	cardDir := filepath.Join(tmpDir, "someCardID")
+	if err := os.MkdirAll(cardDir, 0755); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(cardDir, "word.txt"), []byte("котка"), 0644); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+
+	tests := []struct {
+		name    string
+		word    string
+		wantDir string // empty means expect ""
+		wantHit bool
+	}{
+		{
+			name:    "existing word found",
+			word:    "котка",
+			wantDir: cardDir,
+			wantHit: true,
+		},
+		{
+			name:    "unknown word returns empty string",
+			word:    "куче",
+			wantDir: "",
+			wantHit: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := store.FindCardDirectory(tmpDir, tt.word)
+			if tt.wantHit && got != tt.wantDir {
+				t.Errorf("FindCardDirectory(%q) = %q; want %q", tt.word, got, tt.wantDir)
+			}
+			if !tt.wantHit && got != "" {
+				t.Errorf("FindCardDirectory(%q) = %q; want empty string", tt.word, got)
+			}
+		})
+	}
+}
+
+// TestFindCardDirectoryLegacyFallback checks that the legacy _word.txt naming
+// convention is still supported for backward compatibility.
+func TestFindCardDirectoryLegacyFallback(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	// Create a card directory with the old _word.txt naming.
+	cardDir := filepath.Join(tmpDir, "legacyCardID")
+	if err := os.MkdirAll(cardDir, 0755); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(cardDir, "_word.txt"), []byte("ябълка"), 0644); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+
+	got := store.FindCardDirectory(tmpDir, "ябълка")
+	if got != cardDir {
+		t.Errorf("FindCardDirectory (legacy) = %q; want %q", got, cardDir)
+	}
+}
+
+// TestFindOrCreateCardDirectory verifies that a new directory is created when
+// no matching one exists, and that the same directory is returned on a second
+// call for the same word.
+func TestFindOrCreateCardDirectory(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	// First call: directory does not exist yet.
+	dir1 := store.FindOrCreateCardDirectory(tmpDir, "хляб")
+	if dir1 == "" || dir1 == tmpDir {
+		t.Fatalf("expected a new card directory, got %q", dir1)
+	}
+
+	// word.txt must have been written.
+	data, err := os.ReadFile(filepath.Join(dir1, "word.txt"))
+	if err != nil {
+		t.Fatalf("word.txt not created: %v", err)
+	}
+	if string(data) != "хляб" {
+		t.Errorf("word.txt content = %q; want %q", string(data), "хляб")
+	}
+
+	// Second call: must return the same directory.
+	dir2 := store.FindOrCreateCardDirectory(tmpDir, "хляб")
+	if dir2 != dir1 {
+		t.Errorf("second call returned %q; want %q", dir2, dir1)
+	}
+}
+
+// TestCardStoreScanWords verifies that ScanWords returns only words from
+// directories that pass the predicate and ignores hidden directories.
+func TestCardStoreScanWords(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	// Helper: create a card directory with word.txt.
+	makeCard := func(id, word string) string {
+		cardDir := filepath.Join(tmpDir, id)
+		_ = os.MkdirAll(cardDir, 0755)
+		_ = os.WriteFile(filepath.Join(cardDir, "word.txt"), []byte(word), 0644)
+		return cardDir
+	}
+
+	dir1 := makeCard("card1", "котка")
+	makeCard("card2", "куче")
+
+	// Hidden directory must be skipped.
+	makeCard(".hidden", "hidden")
+
+	// ScanWords with a predicate that only passes dir1.
+	cs := store.New(tmpDir)
+	words := cs.ScanWords(func(wordDir string) bool {
+		return wordDir == dir1
+	})
+
+	if len(words) != 1 || words[0] != "котка" {
+		t.Errorf("ScanWords = %v; want [котка]", words)
+	}
+
+	// ScanWords with nil predicate must return all non-hidden words.
+	allWords := cs.ScanWords(nil)
+	if len(allWords) != 2 {
+		t.Errorf("ScanWords(nil) = %v; want 2 words", allWords)
+	}
+}