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

basic_memory/telemetry.py

@@ -0,0 +1,249 @@
+"""Anonymous telemetry for Basic Memory (Homebrew-style opt-out).
+
+This module implements privacy-respecting usage analytics following the Homebrew model:
+- Telemetry is ON by default
+- Users can easily opt out: `bm telemetry disable`
+- First run shows a one-time notice (not a prompt)
+- Only anonymous data is collected (random UUID, no personal info)
+
+What we collect:
+- App version, Python version, OS, architecture
+- Feature usage (which MCP tools and CLI commands are used)
+- Error types (sanitized, no file paths or personal data)
+
+What we NEVER collect:
+- Note content, file names, or paths
+- Personal information
+- IP addresses (OpenPanel doesn't store these)
+
+Documentation: https://basicmemory.com/telemetry
+"""
+
+import platform
+import re
+import uuid
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+from openpanel import OpenPanel
+
+from basic_memory import __version__
+
+# --- Configuration ---
+
+# OpenPanel credentials (write-only, safe to embed in client code)
+# These can only send events to our dashboard, not read any data
+OPENPANEL_CLIENT_ID = "2e7b036d-c6e5-40aa-91eb-5c70a8ef21a3"
+OPENPANEL_CLIENT_SECRET = "sec_92f7f8328bd0368ff4c2"
+
+TELEMETRY_DOCS_URL = "https://basicmemory.com/telemetry"
+
+TELEMETRY_NOTICE = f"""
+Basic Memory collects anonymous usage statistics to help improve the software.
+This includes: version, OS, feature usage, and errors. No personal data or note content.
+
+To opt out: bm telemetry disable
+Details: {TELEMETRY_DOCS_URL}
+"""
+
+# --- Module State ---
+
+_client: OpenPanel | None = None
+_initialized: bool = False
+
+
+# --- Installation ID ---
+
+
+def get_install_id() -> str:
+    """Get or create anonymous installation ID.
+
+    Creates a random UUID on first run and stores it locally.
+    User can delete ~/.basic-memory/.install_id to reset.
+    """
+    id_file = Path.home() / ".basic-memory" / ".install_id"
+
+    if id_file.exists():
+        return id_file.read_text().strip()
+
+    install_id = str(uuid.uuid4())
+    id_file.parent.mkdir(parents=True, exist_ok=True)
+    id_file.write_text(install_id)
+    return install_id
+
+
+# --- Client Management ---
+
+
+def _get_client() -> OpenPanel:
+    """Get or create the OpenPanel client (singleton).
+
+    Lazily initializes the client with global properties.
+    """
+    global _client, _initialized
+
+    if _client is None:
+        from basic_memory.config import ConfigManager
+
+        config = ConfigManager().config
+
+        # Trigger: first call to track an event
+        # Why: lazy init avoids work if telemetry never used; disabled flag
+        #      tells OpenPanel to skip network calls when user opts out or during tests
+        # Outcome: client ready to queue events (or silently discard if disabled)
+        is_disabled = not config.telemetry_enabled or config.is_test_env
+        _client = OpenPanel(
+            client_id=OPENPANEL_CLIENT_ID,
+            client_secret=OPENPANEL_CLIENT_SECRET,
+            disabled=is_disabled,
+        )
+
+        if config.telemetry_enabled and not config.is_test_env and not _initialized:
+            # Set global properties that go with every event
+            _client.set_global_properties(
+                {
+                    "app_version": __version__,
+                    "python_version": platform.python_version(),
+                    "os": platform.system().lower(),
+                    "arch": platform.machine(),
+                    "install_id": get_install_id(),
+                    "source": "foss",
+                }
+            )
+            _initialized = True
+
+    return _client
+
+
+def reset_client() -> None:
+    """Reset the telemetry client (for testing or after config changes)."""
+    global _client, _initialized
+    _client = None
+    _initialized = False
+
+
+# --- Event Tracking ---
+
+
+def track(event: str, properties: dict[str, Any] | None = None) -> None:
+    """Track an event. Fire-and-forget, never raises.
+
+    Args:
+        event: Event name (e.g., "app_started", "mcp_tool_called")
+        properties: Optional event properties
+    """
+    # Constraint: telemetry must never break the application
+    # Even if OpenPanel API is down or config is corrupt, user's command must succeed
+    try:
+        _get_client().track(event, properties or {})
+    except Exception as e:
+        logger.opt(exception=False).debug(f"Telemetry failed: {e}")
+
+
+# --- First-Run Notice ---
+
+
+def show_notice_if_needed() -> None:
+    """Show one-time telemetry notice (Homebrew style).
+
+    Only shows if:
+    - Telemetry is enabled
+    - Notice hasn't been shown before
+
+    After showing, marks the notice as shown in config.
+    """
+    from basic_memory.config import ConfigManager
+
+    config_manager = ConfigManager()
+    config = config_manager.config
+
+    if config.telemetry_enabled and not config.telemetry_notice_shown:
+        from rich.console import Console
+        from rich.panel import Panel
+
+        # Print to stderr so it doesn't interfere with command output
+        console = Console(stderr=True)
+        console.print(
+            Panel(
+                TELEMETRY_NOTICE.strip(),
+                title="[dim]Telemetry Notice[/dim]",
+                border_style="dim",
+                expand=False,
+            )
+        )
+
+        # Mark as shown so we don't show again
+        config.telemetry_notice_shown = True
+        config_manager.save_config(config)
+
+
+# --- Convenience Functions ---
+
+
+def track_app_started(mode: str) -> None:
+    """Track app startup.
+
+    Args:
+        mode: "cli" or "mcp"
+    """
+    track("app_started", {"mode": mode})
+
+
+def track_mcp_tool(tool_name: str) -> None:
+    """Track MCP tool usage.
+
+    Args:
+        tool_name: Name of the tool (e.g., "write_note", "search_notes")
+    """
+    track("mcp_tool_called", {"tool": tool_name})
+
+
+def track_cli_command(command: str) -> None:
+    """Track CLI command usage.
+
+    Args:
+        command: Command name (e.g., "sync", "import claude")
+    """
+    track("cli_command", {"command": command})
+
+
+def track_sync_completed(entity_count: int, duration_ms: int) -> None:
+    """Track sync completion.
+
+    Args:
+        entity_count: Number of entities synced
+        duration_ms: Duration in milliseconds
+    """
+    track("sync_completed", {"entity_count": entity_count, "duration_ms": duration_ms})
+
+
+def track_import_completed(source: str, count: int) -> None:
+    """Track import completion.
+
+    Args:
+        source: Import source (e.g., "claude", "chatgpt")
+        count: Number of items imported
+    """
+    track("import_completed", {"source": source, "count": count})
+
+
+def track_error(error_type: str, message: str) -> None:
+    """Track an error (sanitized).
+
+    Args:
+        error_type: Exception class name
+        message: Error message (will be sanitized to remove file paths)
+    """
+    if not message:
+        track("error", {"type": error_type, "message": ""})
+        return
+
+    # Sanitize file paths to prevent leaking user directory structure
+    # Unix paths: /Users/name/file.py, /home/user/notes/doc.md
+    sanitized = re.sub(r"/[\w/.+-]+\.\w+", "[FILE]", message)
+    # Windows paths: C:\Users\name\file.py, D:\projects\doc.md
+    sanitized = re.sub(r"[A-Z]:\\[\w\\.+-]+\.\w+", "[FILE]", sanitized, flags=re.IGNORECASE)
+
+    # Truncate to avoid sending too much data
+    track("error", {"type": error_type, "message": sanitized[:200]})

basic_memory/utils.py

@@ -5,9 +5,9 @@ import os
 import logging
 import re
 import sys
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
-from typing import Optional, Protocol, Union, runtime_checkable, List
+from typing import Protocol, Union, runtime_checkable, List
 
 from loguru import logger
 from unidecode import unidecode
@@ -42,7 +42,7 @@ def normalize_project_path(path: str) -> str:
     # Windows paths have a drive letter followed by a colon
     if len(path) >= 2 and path[1] == ":":
         # Windows absolute path - return unchanged
-        return path
+        return path  # pragma: no cover
 
     # Handle both absolute and relative Unix paths
     normalized = path.lstrip("/")
@@ -67,19 +67,20 @@ class PathLike(Protocol):
 # This preserves compatibility with existing code while we migrate
 FilePath = Union[Path, str]
 
-# Disable the "Queue is full" warning
-logging.getLogger("opentelemetry.sdk.metrics._internal.instrument").setLevel(logging.ERROR)
-
 
 def generate_permalink(file_path: Union[Path, str, PathLike], split_extension: bool = True) -> str:
     """Generate a stable permalink from a file path.
 
     Args:
         file_path: Original file path (str, Path, or PathLike)
+        split_extension: Whether to split off and discard file extensions.
+                        When True, uses mimetypes to detect real extensions.
+                        When False, preserves all content including periods.
 
     Returns:
         Normalized permalink that matches validation rules. Converts spaces and underscores
         to hyphens for consistency. Preserves non-ASCII characters like Chinese.
+        Preserves periods in version numbers (e.g., "2.0.0") when they're not real file extensions.
 
     Examples:
         >>> generate_permalink("docs/My Feature.md")
@@ -90,12 +91,26 @@ def generate_permalink(file_path: Union[Path, str, PathLike], split_extension: b
         'design/unified-model-refactor'
         >>> generate_permalink("中文/测试文档.md")
         '中文/测试文档'
+        >>> generate_permalink("Version 2.0.0")
+        'version-2.0.0'
     """
     # Convert Path to string if needed
     path_str = Path(str(file_path)).as_posix()
 
-    # Remove extension (for now, possibly)
-    (base, extension) = os.path.splitext(path_str)
+    # Only split extension if there's a real file extension
+    # Use mimetypes to detect real extensions, avoiding misinterpreting periods in version numbers
+    import mimetypes
+
+    mime_type, _ = mimetypes.guess_type(path_str)
+    has_real_extension = mime_type is not None
+
+    if has_real_extension and split_extension:
+        # Real file extension detected - split it off
+        (base, extension) = os.path.splitext(path_str)
+    else:
+        # No real extension or split_extension=False - process the whole string
+        base = path_str
+        extension = ""
 
     # Check if we have CJK characters that should be preserved
     # CJK ranges: \u4e00-\u9fff (CJK Unified Ideographs), \u3000-\u303f (CJK symbols),
@@ -147,9 +162,9 @@ def generate_permalink(file_path: Union[Path, str, PathLike], split_extension: b
         # Remove apostrophes entirely (don't replace with hyphens)
         text_no_apostrophes = text_with_hyphens.replace("'", "")
 
-        # Replace unsafe chars with hyphens, but preserve CJK characters
+        # Replace unsafe chars with hyphens, but preserve CJK characters and periods
         clean_text = re.sub(
-            r"[^a-z0-9\u4e00-\u9fff\u3000-\u303f\u3400-\u4dbf/\-]", "-", text_no_apostrophes
+            r"[^a-z0-9\u4e00-\u9fff\u3000-\u303f\u3400-\u4dbf/\-\.]", "-", text_no_apostrophes
         )
     else:
         # Original ASCII-only processing for backward compatibility
@@ -168,8 +183,8 @@ def generate_permalink(file_path: Union[Path, str, PathLike], split_extension: b
         # Remove apostrophes entirely (don't replace with hyphens)
         text_no_apostrophes = text_with_hyphens.replace("'", "")
 
-        # Replace remaining invalid chars with hyphens
-        clean_text = re.sub(r"[^a-z0-9/\-]", "-", text_no_apostrophes)
+        # Replace remaining invalid chars with hyphens, preserving periods
+        clean_text = re.sub(r"[^a-z0-9/\-\.]", "-", text_no_apostrophes)
 
     # Collapse multiple hyphens
     clean_text = re.sub(r"-+", "-", clean_text)
@@ -181,36 +196,44 @@ def generate_permalink(file_path: Union[Path, str, PathLike], split_extension: b
     return_val = "/".join(clean_segments)
 
     # Append file extension back, if necessary
-    if not split_extension and extension:
-        return_val += extension
+    if not split_extension and extension:  # pragma: no cover
+        return_val += extension  # pragma: no cover
 
     return return_val
 
 
 def setup_logging(
-    env: str,
-    home_dir: Path,
-    log_file: Optional[str] = None,
     log_level: str = "INFO",
-    console: bool = True,
+    log_to_file: bool = False,
+    log_to_stdout: bool = False,
+    structured_context: bool = False,
 ) -> None:  # pragma: no cover
-    """
-    Configure logging for the application.
+    """Configure logging with explicit settings.
+
+    This function provides a simple, explicit interface for configuring logging.
+    Each entry point (CLI, MCP, API) should call this with appropriate settings.
 
     Args:
-        env: The environment name (dev, test, prod)
-        home_dir: The root directory for the application
-        log_file: The name of the log file to write to
-        log_level: The logging level to use
-        console: Whether to log to the console
+        log_level: DEBUG, INFO, WARNING, ERROR
+        log_to_file: Write to ~/.basic-memory/basic-memory.log with rotation
+        log_to_stdout: Write to stderr (for Docker/cloud deployments)
+        structured_context: Bind tenant_id, fly_region, etc. for cloud observability
     """
     # Remove default handler and any existing handlers
     logger.remove()
 
-    # Add file handler if we are not running tests and a log file is specified
-    if log_file and env != "test":
-        # Setup file logger
-        log_path = home_dir / log_file
+    # In test mode, only log to stdout regardless of settings
+    env = os.getenv("BASIC_MEMORY_ENV", "dev")
+    if env == "test":
+        logger.add(sys.stderr, level=log_level, backtrace=True, diagnose=True, colorize=True)
+        return
+
+    # Add file handler with rotation
+    if log_to_file:
+        log_path = Path.home() / ".basic-memory" / "basic-memory.log"
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        # Keep logging synchronous (enqueue=False) to avoid background logging threads.
+        # Background threads are a common source of "hang on exit" issues in CLI/test runs.
         logger.add(
             str(log_path),
             level=log_level,
@@ -218,42 +241,28 @@ def setup_logging(
             retention="10 days",
             backtrace=True,
             diagnose=True,
-            enqueue=True,
+            enqueue=False,
             colorize=False,
         )
 
-    # Add console logger if requested or in test mode
-    if env == "test" or console:
+    # Add stdout handler (for Docker/cloud)
+    if log_to_stdout:
         logger.add(sys.stderr, level=log_level, backtrace=True, diagnose=True, colorize=True)
 
-    logger.info(f"ENV: '{env}' Log level: '{log_level}' Logging to {log_file}")
-
-    # Bind environment context for structured logging (works in both local and cloud)
-    tenant_id = os.getenv("BASIC_MEMORY_TENANT_ID", "local")
-    fly_app_name = os.getenv("FLY_APP_NAME", "local")
-    fly_machine_id = os.getenv("FLY_MACHINE_ID", "local")
-    fly_region = os.getenv("FLY_REGION", "local")
-
-    logger.configure(
-        extra={
-            "tenant_id": tenant_id,
-            "fly_app_name": fly_app_name,
-            "fly_machine_id": fly_machine_id,
-            "fly_region": fly_region,
-        }
-    )
+    # Bind structured context for cloud observability
+    if structured_context:
+        logger.configure(
+            extra={
+                "tenant_id": os.getenv("BASIC_MEMORY_TENANT_ID", "local"),
+                "fly_app_name": os.getenv("FLY_APP_NAME", "local"),
+                "fly_machine_id": os.getenv("FLY_MACHINE_ID", "local"),
+                "fly_region": os.getenv("FLY_REGION", "local"),
+            }
+        )
 
     # Reduce noise from third-party libraries
-    noisy_loggers = {
-        # HTTP client logs
-        "httpx": logging.WARNING,
-        # File watching logs
-        "watchfiles.main": logging.WARNING,
-    }
-
-    # Set log levels for noisy loggers
-    for logger_name, level in noisy_loggers.items():
-        logging.getLogger(logger_name).setLevel(level)
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("watchfiles.main").setLevel(logging.WARNING)
 
 
 def parse_tags(tags: Union[List[str], str, None]) -> List[str]:
@@ -322,7 +331,7 @@ def normalize_file_path_for_comparison(file_path: str) -> str:
     This function normalizes file paths to help detect potential conflicts:
     - Converts to lowercase for case-insensitive comparison
     - Normalizes Unicode characters
-    - Handles path separators consistently
+    - Converts backslashes to forward slashes for cross-platform consistency
 
     Args:
         file_path: The file path to normalize
@@ -331,19 +340,15 @@ def normalize_file_path_for_comparison(file_path: str) -> str:
         Normalized file path for comparison purposes
     """
     import unicodedata
+    from pathlib import PureWindowsPath
 
-    # Convert to lowercase for case-insensitive comparison
-    normalized = file_path.lower()
+    # Use PureWindowsPath to ensure backslashes are treated as separators
+    # regardless of current platform, then convert to POSIX-style
+    normalized = PureWindowsPath(file_path).as_posix().lower()
 
     # Normalize Unicode characters (NFD normalization)
     normalized = unicodedata.normalize("NFD", normalized)
 
-    # Replace path separators with forward slashes
-    normalized = normalized.replace("\\", "/")
-
-    # Remove multiple slashes
-    normalized = re.sub(r"/+", "/", normalized)
-
     return normalized
 
 
@@ -423,25 +428,41 @@ def validate_project_path(path: str, project_path: Path) -> bool:
     try:
         resolved = (project_path / path).resolve()
         return resolved.is_relative_to(project_path.resolve())
-    except (ValueError, OSError):
-        return False
+    except (ValueError, OSError):  # pragma: no cover
+        return False  # pragma: no cover
+
 
+def ensure_timezone_aware(dt: datetime, cloud_mode: bool | None = None) -> datetime:
+    """Ensure a datetime is timezone-aware.
 
-def ensure_timezone_aware(dt: datetime) -> datetime:
-    """Ensure a datetime is timezone-aware using system timezone.
+    If the datetime is naive, convert it to timezone-aware. The interpretation
+    depends on cloud_mode:
+    - In cloud mode (PostgreSQL/asyncpg): naive datetimes are interpreted as UTC
+    - In local mode (SQLite): naive datetimes are interpreted as local time
 
-    If the datetime is naive, convert it to timezone-aware using the system's local timezone.
-    If it's already timezone-aware, return it unchanged.
+    asyncpg uses binary protocol which returns timestamps in UTC but as naive
+    datetimes. In cloud deployments, cloud_mode=True handles this correctly.
 
     Args:
         dt: The datetime to ensure is timezone-aware
+        cloud_mode: Optional explicit cloud_mode setting. If None, loads from config.
 
     Returns:
         A timezone-aware datetime
     """
     if dt.tzinfo is None:
-        # Naive datetime - assume it's in local time and add timezone
-        return dt.astimezone()
+        # Determine cloud_mode: use explicit parameter if provided, otherwise load from config
+        if cloud_mode is None:
+            from basic_memory.config import ConfigManager
+
+            cloud_mode = ConfigManager().config.cloud_mode_enabled
+
+        if cloud_mode:
+            # Cloud/PostgreSQL mode: naive datetimes from asyncpg are already UTC
+            return dt.replace(tzinfo=timezone.utc)
+        else:
+            # Local/SQLite mode: naive datetimes are in local time
+            return dt.astimezone()
     else:
         # Already timezone-aware
         return dt