fix(directory-watcher): ensure unique metadata paths per discovered database

- Add meta path expansion to support home directory tilde notation (~)
- Derive unique metadata directories for each discovered database
- Prevent databases from clobbering each other's replication state
- Add tests for meta path expansion and directory-specific paths

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: corylanou

cmd/litestream/main.go

@@ -527,7 +527,12 @@ func NewDBFromConfig(dbc *DBConfig) (*litestream.DB, error) {
 
 	// Override default database settings if specified in configuration.
 	if dbc.MetaPath != nil {
-		db.SetMetaPath(*dbc.MetaPath)
+		expandedMetaPath, err := expand(*dbc.MetaPath)
+		if err != nil {
+			return nil, fmt.Errorf("failed to expand meta path: %w", err)
+		}
+		dbc.MetaPath = &expandedMetaPath
+		db.SetMetaPath(expandedMetaPath)
 	}
 	if dbc.MonitorInterval != nil {
 		db.MonitorInterval = *dbc.MonitorInterval
@@ -627,6 +632,18 @@ func newDBFromDirectoryEntry(dbc *DBConfig, dirPath, dbPath string) (*litestream
 	dbConfigCopy.Recursive = false // Clear recursive flag
 	dbConfigCopy.Watch = false     // Individual DBs do not watch directories
 
+	// Ensure every database discovered beneath a directory receives a unique
+	// metadata path. Without this, all databases share the same meta-path and
+	// clobber each other's replication state.
+	if dbc.MetaPath != nil {
+		baseMetaPath, err := expand(*dbc.MetaPath)
+		if err != nil {
+			return nil, fmt.Errorf("failed to expand meta path for %s: %w", dbPath, err)
+		}
+		metaPathCopy := deriveMetaPathForDirectoryEntry(baseMetaPath, relPath)
+		dbConfigCopy.MetaPath = &metaPathCopy
+	}
+
 	// Deep copy replica config and make path unique per database.
 	// This prevents all databases from writing to the same replica path.
 	if dbc.Replica != nil {
@@ -697,6 +714,24 @@ func cloneReplicaConfigWithRelativePath(base *ReplicaConfig, relPath string) (*R
 	return &replicaCopy, nil
 }
 
+// deriveMetaPathForDirectoryEntry returns a unique metadata directory for a
+// database discovered through directory replication by appending the database's
+// relative path and the standard Litestream suffix to the configured base path.
+func deriveMetaPathForDirectoryEntry(basePath, relPath string) string {
+	relPath = filepath.Clean(relPath)
+	if relPath == "." || relPath == "" {
+		return basePath
+	}
+
+	relDir, relFile := filepath.Split(relPath)
+	if relFile == "" || relFile == "." {
+		return filepath.Join(basePath, relPath)
+	}
+
+	metaDirName := "." + relFile + litestream.MetaDirSuffix
+	return filepath.Join(basePath, relDir, metaDirName)
+}
+
 // appendRelativePathToURL appends relPath to the URL's path component, ensuring
 // the result remains rooted and uses forward slashes.
 func appendRelativePathToURL(u *url.URL, relPath string) {

cmd/litestream/main_test.go

@@ -5,6 +5,7 @@ import (
 	"context"
 	"errors"
 	"os"
+	"os/user"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -137,6 +138,46 @@ dbs:
 	})
 }
 
+func TestNewDBFromConfig_MetaPathExpansion(t *testing.T) {
+	u, err := user.Current()
+	if err != nil {
+		t.Skipf("user.Current failed: %v", err)
+	}
+	if u.HomeDir == "" {
+		t.Skip("no home directory available for expansion test")
+	}
+
+	tmpDir := t.TempDir()
+	dbPath := filepath.Join(tmpDir, "db.sqlite")
+	replicaPath := filepath.Join(tmpDir, "replica")
+	if err := os.MkdirAll(replicaPath, 0o755); err != nil {
+		t.Fatalf("failed to create replica directory: %v", err)
+	}
+
+	metaPath := filepath.Join("~", "litestream-meta")
+	config := &main.DBConfig{
+		Path:     dbPath,
+		MetaPath: &metaPath,
+		Replica: &main.ReplicaConfig{
+			Type: "file",
+			Path: replicaPath,
+		},
+	}
+
+	db, err := main.NewDBFromConfig(config)
+	if err != nil {
+		t.Fatalf("NewDBFromConfig failed: %v", err)
+	}
+
+	expectedMetaPath := filepath.Join(u.HomeDir, "litestream-meta")
+	if got := db.MetaPath(); got != expectedMetaPath {
+		t.Fatalf("MetaPath not expanded: got %s, want %s", got, expectedMetaPath)
+	}
+	if config.MetaPath == nil || *config.MetaPath != expectedMetaPath {
+		t.Fatalf("config MetaPath not updated: got %v, want %s", config.MetaPath, expectedMetaPath)
+	}
+}
+
 func TestNewFileReplicaFromConfig(t *testing.T) {
 	r, err := main.NewReplicaFromConfig(&main.ReplicaConfig{Path: "/foo"}, nil)
 	if err != nil {
@@ -1614,6 +1655,74 @@ func TestNewDBsFromDirectoryConfig_UniquePaths(t *testing.T) {
 	}
 }
 
+// TestNewDBsFromDirectoryConfig_MetaPathPerDatabase ensures that each database
+// discovered via a directory config receives a unique metadata directory when a
+// base meta-path is provided.
+func TestNewDBsFromDirectoryConfig_MetaPathPerDatabase(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	rootDB := filepath.Join(tmpDir, "primary.db")
+	createSQLiteDB(t, rootDB)
+
+	nestedDir := filepath.Join(tmpDir, "team", "nested")
+	if err := os.MkdirAll(nestedDir, 0o755); err != nil {
+		t.Fatalf("failed to create nested directory: %v", err)
+	}
+	nestedDB := filepath.Join(nestedDir, "analytics.db")
+	createSQLiteDB(t, nestedDB)
+
+	u, err := user.Current()
+	if err != nil {
+		t.Skipf("user.Current failed: %v", err)
+	}
+	if u.HomeDir == "" {
+		t.Skip("no home directory available for expansion test")
+	}
+
+	metaRoot := filepath.Join("~", "meta-root")
+	expandedMetaRoot := filepath.Join(u.HomeDir, "meta-root")
+	replicaDir := filepath.Join(t.TempDir(), "replica")
+	config := &main.DBConfig{
+		Dir:       tmpDir,
+		Pattern:   "*.db",
+		Recursive: true,
+		MetaPath:  &metaRoot,
+		Replica: &main.ReplicaConfig{
+			Type: "file",
+			Path: replicaDir,
+		},
+	}
+
+	dbs, err := main.NewDBsFromDirectoryConfig(config)
+	if err != nil {
+		t.Fatalf("NewDBsFromDirectoryConfig failed: %v", err)
+	}
+	if len(dbs) != 2 {
+		t.Fatalf("expected 2 databases, got %d", len(dbs))
+	}
+
+	expectedMetaPaths := map[string]string{
+		rootDB:   filepath.Join(expandedMetaRoot, ".primary.db"+litestream.MetaDirSuffix),
+		nestedDB: filepath.Join(expandedMetaRoot, "team", "nested", ".analytics.db"+litestream.MetaDirSuffix),
+	}
+
+	metaSeen := make(map[string]struct{})
+	for _, db := range dbs {
+		metaPath := db.MetaPath()
+		want, ok := expectedMetaPaths[db.Path()]
+		if !ok {
+			t.Fatalf("unexpected database path returned: %s", db.Path())
+		}
+		if metaPath != want {
+			t.Fatalf("database %s meta path mismatch: got %s, want %s", db.Path(), metaPath, want)
+		}
+		if _, dup := metaSeen[metaPath]; dup {
+			t.Fatalf("duplicate meta path detected: %s", metaPath)
+		}
+		metaSeen[metaPath] = struct{}{}
+	}
+}
+
 // TestNewDBsFromDirectoryConfig_SubdirectoryPaths verifies that the relative
 // directory structure is preserved in replica paths when using recursive scanning.
 func TestNewDBsFromDirectoryConfig_SubdirectoryPaths(t *testing.T) {