refactor: use FileService.ensure_directory() for project directory creation

Replace direct Path.mkdir() calls with FileService.ensure_directory() to enable
future cloud (S3) compatibility. ConfigManager.add_project() is now pure config
management — directory creation is delegated to ProjectService via FileService.

- Make FileService.markdown_processor Optional (not needed for ensure_directory)
- Add file_service: Optional[FileService] to ProjectService.__init__
- ProjectService.add_project() and move_project() use file_service.ensure_directory()
- deps/services.py injects a system-level FileService into ProjectService
- Update tests/conftest.py project_service fixture to include file_service
- Update test_config.py: test that ConfigManager.add_project() never creates dirs

Co-authored-by: Paul Hernandez <phernandez@users.noreply.github.com>

Author: github-actions[bot]

src/basic_memory/config.py

@@ -685,12 +685,8 @@ def add_project(self, name: str, path: str) -> ProjectConfig:
         if project_name:  # pragma: no cover
             raise ValueError(f"Project '{name}' already exists")
 
-        # Ensure the path exists on disk (skip in cloud mode where storage is S3)
-        project_path = Path(path)
-        if not self.config.project_root:
-            project_path.mkdir(parents=True, exist_ok=True)  # pragma: no cover
-
         # Load config, modify it, and save it
+        project_path = Path(path)
         config = self.load_config()
         config.projects[name] = ProjectEntry(path=str(project_path))
         self.save_config(config)

src/basic_memory/deps/services.py

@@ -9,6 +9,7 @@
 
 import asyncio
 import os
+from pathlib import Path
 from typing import Annotated, Any, Callable, Coroutine, Mapping, Protocol
 
 from fastapi import Depends
@@ -549,9 +550,15 @@ async def _reindex_project(**_: Any) -> None:
 
 async def get_project_service(
     project_repository: ProjectRepositoryDep,
+    app_config: AppConfigDep,
 ) -> ProjectService:
-    """Create ProjectService with repository."""
-    return ProjectService(repository=project_repository)
+    """Create ProjectService with repository and a system-level FileService for directory operations."""
+    # A system-level FileService for project directory creation (no project-specific base_path needed).
+    # ensure_directory() accepts absolute paths and ignores base_path for those, so Path.home() is safe.
+    entity_parser = EntityParser(Path.home())
+    markdown_processor = MarkdownProcessor(entity_parser, app_config=app_config)
+    file_service = FileService(Path.home(), markdown_processor, app_config=app_config)
+    return ProjectService(repository=project_repository, file_service=file_service)
 
 
 ProjectServiceDep = Annotated[ProjectService, Depends(get_project_service)]

src/basic_memory/services/file_service.py

@@ -43,7 +43,7 @@ class FileService:
     def __init__(
         self,
         base_path: Path,
-        markdown_processor: MarkdownProcessor,
+        markdown_processor: Optional[MarkdownProcessor] = None,
         max_concurrent_files: int = 10,
         app_config: Optional["BasicMemoryConfig"] = None,
     ):

src/basic_memory/services/project_service.py

@@ -6,7 +6,7 @@
 import shutil
 from datetime import datetime
 from pathlib import Path
-from typing import Dict, Optional, Sequence
+from typing import TYPE_CHECKING, Dict, Optional, Sequence
 
 
 from loguru import logger
@@ -30,16 +30,22 @@
 )
 from basic_memory.utils import generate_permalink
 
+if TYPE_CHECKING:  # pragma: no cover
+    from basic_memory.services.file_service import FileService
+
 
 class ProjectService:
     """Service for managing Basic Memory projects."""
 
     repository: ProjectRepository
 
-    def __init__(self, repository: ProjectRepository):
+    def __init__(
+        self, repository: ProjectRepository, file_service: Optional["FileService"] = None
+    ):
         """Initialize the project service."""
         super().__init__()
         self.repository = repository
+        self.file_service = file_service
 
     @property
     def config_manager(self) -> ConfigManager:
@@ -205,6 +211,16 @@ async def add_project(self, name: str, path: str, set_default: bool = False) ->
                         f"Projects cannot share directory trees."
                     )
 
+        # Ensure the project directory exists on disk.
+        # Trigger: project_root not set means local filesystem mode (not S3/cloud)
+        # Why: FileService (or future S3FileService) provides cloud-compatible directory creation;
+        #      direct Path.mkdir() bypasses this abstraction
+        # Outcome: directory exists before config/DB entries are written
+        if not self.config_manager.config.project_root:
+            if self.file_service is None:
+                raise ValueError("file_service is required for local project directory creation")
+            await self.file_service.ensure_directory(Path(resolved_path))
+
         # First add to config file (this validates project uniqueness and keeps
         # config + database aligned for all backends).
         self.config_manager.add_project(name, resolved_path)
@@ -460,8 +476,13 @@ async def move_project(self, name: str, new_path: str) -> None:
             raise ValueError(f"Project '{name}' not found in configuration")
 
         # Create the new directory if it doesn't exist (skip in cloud mode where storage is S3)
+        # Trigger: project_root not set means local filesystem mode
+        # Why: FileService (or future S3FileService) provides cloud-compatible directory creation
+        # Outcome: destination directory exists before config/DB are updated
         if not self.config_manager.config.project_root:
-            Path(resolved_path).mkdir(parents=True, exist_ok=True)
+            if self.file_service is None:
+                raise ValueError("file_service is required for local project directory creation")
+            await self.file_service.ensure_directory(Path(resolved_path))
 
         # Update in configuration
         config = self.config_manager.load_config()

tests/conftest.py

@@ -466,9 +466,10 @@ async def sample_entity(entity_repository: EntityRepository) -> Entity:
 @pytest_asyncio.fixture
 async def project_service(
     project_repository: ProjectRepository,
+    file_service: FileService,
 ) -> ProjectService:
-    """Create ProjectService with repository."""
-    return ProjectService(repository=project_repository)
+    """Create ProjectService with repository and file service for directory operations."""
+    return ProjectService(repository=project_repository, file_service=file_service)
 
 
 @pytest_asyncio.fixture

tests/test_config.py

@@ -580,23 +580,15 @@ def test_add_project_uses_platform_native_separators(self, monkeypatch):
                 assert "/" in saved_path
                 assert saved_path == str(project_path)
 
-    def test_add_project_skips_mkdir_when_project_root_set(self, monkeypatch):
-        """Test that add_project skips mkdir when project_root is set (cloud mode).
+    def test_add_project_never_creates_directory(self):
+        """Test that ConfigManager.add_project() is pure config management — no mkdir.
 
-        In cloud mode, file storage is S3 — no local directories needed.
-        Without this, add_project crashes on read-only filesystems (e.g. macOS root /).
+        Directory creation is delegated to ProjectService via FileService, which
+        supports both local and cloud (S3) backends.
         """
-        import basic_memory.config
-
         with tempfile.TemporaryDirectory() as temp_dir:
             temp_path = Path(temp_dir)
 
-            # Simulate cloud mode: project_root set, postgres backend
-            monkeypatch.setenv("BASIC_MEMORY_PROJECT_ROOT", "/cloud-root")
-            monkeypatch.setenv("BASIC_MEMORY_DATABASE_BACKEND", "postgres")
-            # Clear module-level cache so env vars are picked up
-            basic_memory.config._CONFIG_CACHE = None
-
             config_manager = ConfigManager()
             config_manager.config_dir = temp_path / "basic-memory"
             config_manager.config_file = config_manager.config_dir / "config.json"
@@ -605,17 +597,15 @@ def test_add_project_skips_mkdir_when_project_root_set(self, monkeypatch):
             initial_config = BasicMemoryConfig(projects={})
             config_manager.save_config(initial_config)
 
-            # Use a path that would fail mkdir on most systems (read-only root)
-            config_manager.add_project("test-project", "/nonexistent/cloud/path")
+            # Use a path that does not exist — ConfigManager should not create it
+            nonexistent_path = str(temp_path / "nonexistent" / "project")
+            config_manager.add_project("test-project", nonexistent_path)
 
             # Verify project was added to config without creating the directory
             config = config_manager.load_config()
             assert "test-project" in config.projects
-            assert config.projects["test-project"].path == "/nonexistent/cloud/path"
-            assert not Path("/nonexistent/cloud/path").exists()
-
-            # Clean up cache for subsequent tests
-            basic_memory.config._CONFIG_CACHE = None
+            assert config.projects["test-project"].path == nonexistent_path
+            assert not Path(nonexistent_path).exists()
 
     def test_model_post_init_uses_platform_native_separators(self, config_home, monkeypatch):
         """Test that model_post_init uses platform-native separators."""