basic-memory 0.16.1__py3-none-any.whl → 0.17.4__py3-none-any.whl

basic_memory/cli/auth.py

@@ -7,6 +7,9 @@ import os
 import secrets
 import time
 import webbrowser
+from contextlib import asynccontextmanager
+from collections.abc import AsyncIterator, Callable
+from typing import AsyncContextManager
 
 import httpx
 from rich.console import Console
@@ -19,7 +22,12 @@ console = Console()
 class CLIAuth:
     """Handles WorkOS OAuth Device Authorization for CLI tools."""
 
-    def __init__(self, client_id: str, authkit_domain: str):
+    def __init__(
+        self,
+        client_id: str,
+        authkit_domain: str,
+        http_client_factory: Callable[[], AsyncContextManager[httpx.AsyncClient]] | None = None,
+    ):
         self.client_id = client_id
         self.authkit_domain = authkit_domain
         app_config = ConfigManager().config
@@ -28,6 +36,21 @@ class CLIAuth:
         # PKCE parameters
         self.code_verifier = None
         self.code_challenge = None
+        self._http_client_factory = http_client_factory
+
+    @asynccontextmanager
+    async def _get_http_client(self) -> AsyncIterator[httpx.AsyncClient]:
+        """Create an AsyncClient, optionally via injected factory.
+
+        Why: enables reliable tests without monkeypatching httpx internals while
+        still using real httpx request/response objects.
+        """
+        if self._http_client_factory:
+            async with self._http_client_factory() as client:
+                yield client
+        else:
+            async with httpx.AsyncClient() as client:
+                yield client
 
     def generate_pkce_pair(self) -> tuple[str, str]:
         """Generate PKCE code verifier and challenge."""
@@ -57,7 +80,7 @@ class CLIAuth:
         }
 
         try:
-            async with httpx.AsyncClient() as client:
+            async with self._get_http_client() as client:
                 response = await client.post(device_auth_url, data=data)
 
                 if response.status_code == 200:
@@ -111,7 +134,7 @@ class CLIAuth:
 
         for _attempt in range(max_attempts):
             try:
-                async with httpx.AsyncClient() as client:
+                async with self._get_http_client() as client:
                     response = await client.post(token_url, data=data)
 
                     if response.status_code == 200:
@@ -201,7 +224,7 @@ class CLIAuth:
         }
 
         try:
-            async with httpx.AsyncClient() as client:
+            async with self._get_http_client() as client:
                 response = await client.post(token_url, data=data)
 
                 if response.status_code == 200:

basic_memory/cli/commands/__init__.py

@@ -1,7 +1,7 @@
 """CLI commands for basic-memory."""
 
 from . import status, db, import_memory_json, mcp, import_claude_conversations
-from . import import_claude_projects, import_chatgpt, tool, project
+from . import import_claude_projects, import_chatgpt, tool, project, format, telemetry
 
 __all__ = [
     "status",
@@ -13,4 +13,6 @@ __all__ = [
     "import_chatgpt",
     "tool",
     "project",
+    "format",
+    "telemetry",
 ]

basic_memory/cli/commands/cloud/api_client.py

@@ -1,6 +1,9 @@
 """Cloud API client utilities."""
 
+from collections.abc import AsyncIterator
 from typing import Optional
+from contextlib import asynccontextmanager
+from typing import AsyncContextManager, Callable
 
 import httpx
 import typer
@@ -11,6 +14,8 @@ from basic_memory.config import ConfigManager
 
 console = Console()
 
+HttpClientFactory = Callable[[], AsyncContextManager[httpx.AsyncClient]]
+
 
 class CloudAPIError(Exception):
     """Exception raised for cloud API errors."""
@@ -38,14 +43,14 @@ def get_cloud_config() -> tuple[str, str, str]:
     return config.cloud_client_id, config.cloud_domain, config.cloud_host
 
 
-async def get_authenticated_headers() -> dict[str, str]:
+async def get_authenticated_headers(auth: CLIAuth | None = None) -> dict[str, str]:
     """
     Get authentication headers with JWT token.
     handles jwt refresh if needed.
     """
     client_id, domain, _ = get_cloud_config()
-    auth = CLIAuth(client_id=client_id, authkit_domain=domain)
-    token = await auth.get_valid_token()
+    auth_obj = auth or CLIAuth(client_id=client_id, authkit_domain=domain)
+    token = await auth_obj.get_valid_token()
     if not token:
         console.print("[red]Not authenticated. Please run 'basic-memory cloud login' first.[/red]")
         raise typer.Exit(1)
@@ -53,21 +58,31 @@ async def get_authenticated_headers() -> dict[str, str]:
     return {"Authorization": f"Bearer {token}"}
 
 
+@asynccontextmanager
+async def _default_http_client(timeout: float) -> AsyncIterator[httpx.AsyncClient]:
+    async with httpx.AsyncClient(timeout=timeout) as client:
+        yield client
+
+
 async def make_api_request(
     method: str,
     url: str,
     headers: Optional[dict] = None,
     json_data: Optional[dict] = None,
     timeout: float = 30.0,
+    *,
+    auth: CLIAuth | None = None,
+    http_client_factory: HttpClientFactory | None = None,
 ) -> httpx.Response:
     """Make an API request to the cloud service."""
     headers = headers or {}
-    auth_headers = await get_authenticated_headers()
+    auth_headers = await get_authenticated_headers(auth=auth)
     headers.update(auth_headers)
     # Add debug headers to help with compression issues
     headers.setdefault("Accept-Encoding", "identity")  # Disable compression for debugging
 
-    async with httpx.AsyncClient(timeout=timeout) as client:
+    client_factory = http_client_factory or (lambda: _default_http_client(timeout))
+    async with client_factory() as client:
         try:
             response = await client.request(method=method, url=url, headers=headers, json=json_data)
             response.raise_for_status()

basic_memory/cli/commands/cloud/cloud_utils.py

@@ -16,7 +16,10 @@ class CloudUtilsError(Exception):
     pass
 
 
-async def fetch_cloud_projects() -> CloudProjectList:
+async def fetch_cloud_projects(
+    *,
+    api_request=make_api_request,
+) -> CloudProjectList:
     """Fetch list of projects from cloud API.
 
     Returns:
@@ -27,14 +30,18 @@ async def fetch_cloud_projects() -> CloudProjectList:
         config = config_manager.config
         host_url = config.cloud_host.rstrip("/")
 
-        response = await make_api_request(method="GET", url=f"{host_url}/proxy/projects/projects")
+        response = await api_request(method="GET", url=f"{host_url}/proxy/projects/projects")
 
         return CloudProjectList.model_validate(response.json())
     except Exception as e:
         raise CloudUtilsError(f"Failed to fetch cloud projects: {e}") from e
 
 
-async def create_cloud_project(project_name: str) -> CloudProjectCreateResponse:
+async def create_cloud_project(
+    project_name: str,
+    *,
+    api_request=make_api_request,
+) -> CloudProjectCreateResponse:
     """Create a new project on cloud.
 
     Args:
@@ -57,7 +64,7 @@ async def create_cloud_project(project_name: str) -> CloudProjectCreateResponse:
             set_default=False,
         )
 
-        response = await make_api_request(
+        response = await api_request(
             method="POST",
             url=f"{host_url}/proxy/projects/projects",
             headers={"Content-Type": "application/json"},
@@ -84,7 +91,7 @@ async def sync_project(project_name: str, force_full: bool = False) -> None:
         raise CloudUtilsError(f"Failed to sync project '{project_name}': {e}") from e
 
 
-async def project_exists(project_name: str) -> bool:
+async def project_exists(project_name: str, *, api_request=make_api_request) -> bool:
     """Check if a project exists on cloud.
 
     Args:
@@ -94,7 +101,7 @@ async def project_exists(project_name: str) -> bool:
         True if project exists, False otherwise
     """
     try:
-        projects = await fetch_cloud_projects()
+        projects = await fetch_cloud_projects(api_request=api_request)
         project_names = {p.name for p in projects.projects}
         return project_name in project_names
     except Exception:

basic_memory/cli/commands/cloud/rclone_commands.py

@@ -9,17 +9,32 @@ This module provides simplified, project-scoped rclone operations:
 Replaces tenant-wide sync with project-scoped workflows.
 """
 
+import re
 import subprocess
 from dataclasses import dataclass
+from functools import lru_cache
 from pathlib import Path
-from typing import Optional
+from typing import Callable, Optional, Protocol
 
+from loguru import logger
 from rich.console import Console
 
+from basic_memory.cli.commands.cloud.rclone_installer import is_rclone_installed
 from basic_memory.utils import normalize_project_path
 
 console = Console()
 
+# Minimum rclone version for --create-empty-src-dirs support
+MIN_RCLONE_VERSION_EMPTY_DIRS = (1, 64, 0)
+
+class RunResult(Protocol):
+    returncode: int
+    stdout: str
+
+
+RunFunc = Callable[..., RunResult]
+IsInstalledFunc = Callable[[], bool]
+
 
 class RcloneError(Exception):
     """Exception raised for rclone command errors."""
@@ -27,6 +42,56 @@ class RcloneError(Exception):
     pass
 
 
+def check_rclone_installed(is_installed: IsInstalledFunc = is_rclone_installed) -> None:
+    """Check if rclone is installed and raise helpful error if not.
+
+    Raises:
+        RcloneError: If rclone is not installed with installation instructions
+    """
+    if not is_installed():
+        raise RcloneError(
+            "rclone is not installed.\n\n"
+            "Install rclone by running: bm cloud setup\n"
+            "Or install manually from: https://rclone.org/downloads/\n\n"
+            "Windows users: Ensure you have a package manager installed (winget, chocolatey, or scoop)"
+        )
+
+
+@lru_cache(maxsize=1)
+def get_rclone_version(run: RunFunc = subprocess.run) -> tuple[int, int, int] | None:
+    """Get rclone version as (major, minor, patch) tuple.
+
+    Returns:
+        Version tuple like (1, 64, 2), or None if version cannot be determined.
+
+    Note:
+        Result is cached since rclone version won't change during runtime.
+    """
+    try:
+        result = run(["rclone", "version"], capture_output=True, text=True, timeout=10)
+        # Parse "rclone v1.64.2" or "rclone v1.60.1-DEV"
+        match = re.search(r"v(\d+)\.(\d+)\.(\d+)", result.stdout)
+        if match:
+            version = (int(match.group(1)), int(match.group(2)), int(match.group(3)))
+            logger.debug(f"Detected rclone version: {version}")
+            return version
+    except Exception as e:
+        logger.warning(f"Could not determine rclone version: {e}")
+    return None
+
+
+def supports_create_empty_src_dirs(version: tuple[int, int, int] | None) -> bool:
+    """Check if installed rclone supports --create-empty-src-dirs flag.
+
+    Returns:
+        True if rclone version >= 1.64.0, False otherwise.
+    """
+    if version is None:
+        # If we can't determine version, assume older and skip the flag
+        return False
+    return version >= MIN_RCLONE_VERSION_EMPTY_DIRS
+
+
 @dataclass
 class SyncProject:
     """Project configured for cloud sync.
@@ -109,6 +174,10 @@ def project_sync(
     bucket_name: str,
     dry_run: bool = False,
     verbose: bool = False,
+    *,
+    run: RunFunc = subprocess.run,
+    is_installed: IsInstalledFunc = is_rclone_installed,
+    filter_path: Path | None = None,
 ) -> bool:
     """One-way sync: local → cloud.
 
@@ -124,14 +193,16 @@ def project_sync(
         True if sync succeeded, False otherwise
 
     Raises:
-        RcloneError: If project has no local_sync_path configured
+        RcloneError: If project has no local_sync_path configured or rclone not installed
     """
+    check_rclone_installed(is_installed=is_installed)
+
     if not project.local_sync_path:
         raise RcloneError(f"Project {project.name} has no local_sync_path configured")
 
     local_path = Path(project.local_sync_path).expanduser()
     remote_path = get_project_remote(project, bucket_name)
-    filter_path = get_bmignore_filter_path()
+    filter_path = filter_path or get_bmignore_filter_path()
 
     cmd = [
         "rclone",
@@ -150,7 +221,7 @@ def project_sync(
     if dry_run:
         cmd.append("--dry-run")
 
-    result = subprocess.run(cmd, text=True)
+    result = run(cmd, text=True)
     return result.returncode == 0
 
 
@@ -160,6 +231,13 @@ def project_bisync(
     dry_run: bool = False,
     resync: bool = False,
     verbose: bool = False,
+    *,
+    run: RunFunc = subprocess.run,
+    is_installed: IsInstalledFunc = is_rclone_installed,
+    version: tuple[int, int, int] | None = None,
+    filter_path: Path | None = None,
+    state_path: Path | None = None,
+    is_initialized: Callable[[str], bool] = bisync_initialized,
 ) -> bool:
     """Two-way sync: local ↔ cloud.
 
@@ -180,15 +258,17 @@ def project_bisync(
         True if bisync succeeded, False otherwise
 
     Raises:
-        RcloneError: If project has no local_sync_path or needs --resync
+        RcloneError: If project has no local_sync_path, needs --resync, or rclone not installed
     """
+    check_rclone_installed(is_installed=is_installed)
+
     if not project.local_sync_path:
         raise RcloneError(f"Project {project.name} has no local_sync_path configured")
 
     local_path = Path(project.local_sync_path).expanduser()
     remote_path = get_project_remote(project, bucket_name)
-    filter_path = get_bmignore_filter_path()
-    state_path = get_project_bisync_state(project.name)
+    filter_path = filter_path or get_bmignore_filter_path()
+    state_path = state_path or get_project_bisync_state(project.name)
 
     # Ensure state directory exists
     state_path.mkdir(parents=True, exist_ok=True)
@@ -198,7 +278,6 @@ def project_bisync(
         "bisync",
         str(local_path),
         remote_path,
-        "--create-empty-src-dirs",
         "--resilient",
         "--conflict-resolve=newer",
         "--max-delete=25",
@@ -209,6 +288,11 @@ def project_bisync(
         str(state_path),
     ]
 
+    # Add --create-empty-src-dirs if rclone version supports it (v1.64+)
+    version = version if version is not None else get_rclone_version(run=run)
+    if supports_create_empty_src_dirs(version):
+        cmd.append("--create-empty-src-dirs")
+
     if verbose:
         cmd.append("--verbose")
     else:
@@ -221,13 +305,13 @@ def project_bisync(
         cmd.append("--resync")
 
     # Check if first run requires resync
-    if not resync and not bisync_initialized(project.name) and not dry_run:
+    if not resync and not is_initialized(project.name) and not dry_run:
         raise RcloneError(
             f"First bisync for {project.name} requires --resync to establish baseline.\n"
             f"Run: bm project bisync --name {project.name} --resync"
         )
 
-    result = subprocess.run(cmd, text=True)
+    result = run(cmd, text=True)
     return result.returncode == 0
 
 
@@ -235,6 +319,10 @@ def project_check(
     project: SyncProject,
     bucket_name: str,
     one_way: bool = False,
+    *,
+    run: RunFunc = subprocess.run,
+    is_installed: IsInstalledFunc = is_rclone_installed,
+    filter_path: Path | None = None,
 ) -> bool:
     """Check integrity between local and cloud.
 
@@ -249,14 +337,16 @@ def project_check(
         True if files match, False if differences found
 
     Raises:
-        RcloneError: If project has no local_sync_path configured
+        RcloneError: If project has no local_sync_path configured or rclone not installed
     """
+    check_rclone_installed(is_installed=is_installed)
+
     if not project.local_sync_path:
         raise RcloneError(f"Project {project.name} has no local_sync_path configured")
 
     local_path = Path(project.local_sync_path).expanduser()
     remote_path = get_project_remote(project, bucket_name)
-    filter_path = get_bmignore_filter_path()
+    filter_path = filter_path or get_bmignore_filter_path()
 
     cmd = [
         "rclone",
@@ -270,7 +360,7 @@ def project_check(
     if one_way:
         cmd.append("--one-way")
 
-    result = subprocess.run(cmd, capture_output=True, text=True)
+    result = run(cmd, capture_output=True, text=True)
     return result.returncode == 0
 
 
@@ -278,6 +368,9 @@ def project_ls(
     project: SyncProject,
     bucket_name: str,
     path: Optional[str] = None,
+    *,
+    run: RunFunc = subprocess.run,
+    is_installed: IsInstalledFunc = is_rclone_installed,
 ) -> list[str]:
     """List files in remote project.
 
@@ -291,11 +384,14 @@ def project_ls(
 
     Raises:
         subprocess.CalledProcessError: If rclone command fails
+        RcloneError: If rclone is not installed
     """
+    check_rclone_installed(is_installed=is_installed)
+
     remote_path = get_project_remote(project, bucket_name)
     if path:
         remote_path = f"{remote_path}/{path}"
 
     cmd = ["rclone", "ls", remote_path]
-    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+    result = run(cmd, capture_output=True, text=True, check=True)
     return result.stdout.splitlines()

basic_memory/cli/commands/cloud/rclone_installer.py

@@ -151,11 +151,25 @@ def install_rclone_windows() -> None:
         except RcloneInstallError:
             console.print("[yellow]scoop installation failed[/yellow]")
 
-    # No package manager available
-    raise RcloneInstallError(
-        "Could not install rclone automatically. Please install a package manager "
-        "(winget, chocolatey, or scoop) or install rclone manually from https://rclone.org/downloads/"
+    # No package manager available - provide detailed instructions
+    error_msg = (
+        "Could not install rclone automatically.\n\n"
+        "Windows requires a package manager to install rclone. Options:\n\n"
+        "1. Install winget (recommended, built into Windows 11):\n"
+        "   - Windows 11: Already installed\n"
+        "   - Windows 10: Install 'App Installer' from Microsoft Store\n"
+        "   - Then run: bm cloud setup\n\n"
+        "2. Install chocolatey:\n"
+        "   - Visit: https://chocolatey.org/install\n"
+        "   - Then run: bm cloud setup\n\n"
+        "3. Install scoop:\n"
+        "   - Visit: https://scoop.sh\n"
+        "   - Then run: bm cloud setup\n\n"
+        "4. Manual installation:\n"
+        "   - Download from: https://rclone.org/downloads/\n"
+        "   - Extract and add to PATH\n"
     )
+    raise RcloneInstallError(error_msg)
 
 
 def install_rclone(platform_override: Optional[str] = None) -> None:

basic_memory/cli/commands/cloud/upload.py

@@ -2,6 +2,8 @@
 
 import os
 from pathlib import Path
+from contextlib import AbstractAsyncContextManager
+from typing import Callable
 
 import aiofiles
 import httpx
@@ -20,6 +22,9 @@ async def upload_path(
     verbose: bool = False,
     use_gitignore: bool = True,
     dry_run: bool = False,
+    *,
+    client_cm_factory: Callable[[], AbstractAsyncContextManager[httpx.AsyncClient]] | None = None,
+    put_func=call_put,
 ) -> bool:
     """
     Upload a file or directory to cloud project via WebDAV.
@@ -85,8 +90,10 @@ async def upload_path(
                     size_str = f"{size / (1024 * 1024):.1f} MB"
                 print(f"  {relative_path} ({size_str})")
         else:
-            # Upload files using httpx
-            async with get_client() as client:
+            # Upload files using httpx.
+            # Allow injection for tests (MockTransport) while keeping production default.
+            cm_factory = client_cm_factory or get_client
+            async with cm_factory() as client:
                 for i, (file_path, relative_path) in enumerate(files_to_upload, 1):
                     # Skip archive files (zip, tar, gz, etc.)
                     if _is_archive_file(file_path):
@@ -110,7 +117,7 @@ async def upload_path(
 
                     # Upload via HTTP PUT to WebDAV endpoint with mtime header
                     # Using X-OC-Mtime (ownCloud/Nextcloud standard)
-                    response = await call_put(
+                    response = await put_func(
                         client, remote_path, content=content, headers={"X-OC-Mtime": str(mtime)}
                     )
                     response.raise_for_status()

basic_memory/cli/commands/command_utils.py

@@ -1,12 +1,14 @@
 """utility functions for commands"""
 
-from typing import Optional
+import asyncio
+from typing import Optional, TypeVar, Coroutine, Any
 
 from mcp.server.fastmcp.exceptions import ToolError
 import typer
 
 from rich.console import Console
 
+from basic_memory import db
 from basic_memory.mcp.async_client import get_client
 
 from basic_memory.mcp.tools.utils import call_post, call_get
@@ -15,24 +17,70 @@ from basic_memory.schemas import ProjectInfoResponse
 
 console = Console()
 
+T = TypeVar("T")
 
-async def run_sync(project: Optional[str] = None, force_full: bool = False):
+
+def run_with_cleanup(coro: Coroutine[Any, Any, T]) -> T:
+    """Run an async coroutine with proper database cleanup.
+
+    This helper ensures database connections are cleaned up before the event
+    loop closes, preventing process hangs in CLI commands.
+
+    Args:
+        coro: The coroutine to run
+
+    Returns:
+        The result of the coroutine
+    """
+
+    async def _with_cleanup() -> T:
+        try:
+            return await coro
+        finally:
+            await db.shutdown_db()
+
+    return asyncio.run(_with_cleanup())
+
+
+async def run_sync(
+    project: Optional[str] = None,
+    force_full: bool = False,
+    run_in_background: bool = True,
+):
     """Run sync operation via API endpoint.
 
     Args:
         project: Optional project name
         force_full: If True, force a full scan bypassing watermark optimization
+        run_in_background: If True, return immediately; if False, wait for completion
     """
 
     try:
         async with get_client() as client:
             project_item = await get_active_project(client, project, None)
             url = f"{project_item.project_url}/project/sync"
+            params = []
             if force_full:
-                url += "?force_full=true"
+                params.append("force_full=true")
+            if not run_in_background:
+                params.append("run_in_background=false")
+            if params:
+                url += "?" + "&".join(params)
             response = await call_post(client, url)
             data = response.json()
-            console.print(f"[green]{data['message']}[/green]")
+            # Background mode returns {"message": "..."}, foreground returns SyncReportResponse
+            if "message" in data:
+                console.print(f"[green]{data['message']}[/green]")
+            else:
+                # Foreground mode - show summary of sync results
+                total = data.get("total", 0)
+                new_count = len(data.get("new", []))
+                modified_count = len(data.get("modified", []))
+                deleted_count = len(data.get("deleted", []))
+                console.print(
+                    f"[green]Synced {total} files[/green] "
+                    f"(new: {new_count}, modified: {modified_count}, deleted: {deleted_count})"
+                )
     except (ToolError, ValueError) as e:
         console.print(f"[red]Sync failed: {e}[/red]")
         raise typer.Exit(1)