note-connector 0.2.5 → 0.2.7

package/py/src/note_mcp/auth/file_session.py

@@ -0,0 +1,145 @@
+"""File-based session management for Docker/headless environments.
+
+Provides session storage using JSON files when keyring is not available.
+This is a fallback mechanism for environments where system keyring
+cannot be accessed (Docker containers, headless servers, etc.).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from note_mcp.models import Session
+
+logger = logging.getLogger(__name__)
+
+# Default session filename
+SESSION_FILENAME = "session.json"
+
+
+def _get_default_data_dir() -> Path:
+    """Get the default data directory for session storage.
+
+    Returns:
+        Path to data directory. Priority:
+        1. NOTE_MCP_DATA_DIR environment variable
+        2. /app/data (Docker)
+        3. ~/.note-mcp (local)
+    """
+    # Check for environment variable first (Important #4)
+    env_dir = os.environ.get("NOTE_MCP_DATA_DIR")
+    if env_dir:
+        return Path(env_dir)
+
+    # Check for Docker environment
+    if Path("/app/data").exists() and os.access("/app/data", os.W_OK):
+        return Path("/app/data")
+
+    # Fall back to home directory
+    home = Path.home()
+    return home / ".note-mcp"
+
+
+class FileBasedSessionManager:
+    """File-based session management for Docker/headless environments.
+
+    Stores session data in a JSON file instead of system keyring.
+    Suitable for environments where keyring is not available.
+
+    Attributes:
+        data_dir: Directory where session file is stored
+        session_file: Full path to the session JSON file
+    """
+
+    def __init__(self, data_dir: Path | None = None) -> None:
+        """Initialize FileBasedSessionManager.
+
+        Args:
+            data_dir: Session file storage directory.
+                      Default: /app/data (Docker) or ~/.note-mcp (local)
+        """
+        self.data_dir = data_dir or _get_default_data_dir()
+        self.session_file = self.data_dir / SESSION_FILENAME
+
+    def save(self, session: Session) -> None:
+        """Save session to JSON file.
+
+        Args:
+            session: Session object to save
+
+        Raises:
+            OSError: If file cannot be written
+        """
+        # Ensure directory exists
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+
+        # Write session data to file
+        session_data = session.model_dump()
+        with open(self.session_file, "w", encoding="utf-8") as f:
+            json.dump(session_data, f, ensure_ascii=False, indent=2)
+
+        logger.debug(f"Session saved to {self.session_file}")
+
+    def load(self) -> Session | None:
+        """Load session from JSON file.
+
+        Returns:
+            Session object if found and valid, None otherwise
+        """
+        if not self.session_file.exists():
+            logger.debug("No session file found")
+            return None
+
+        try:
+            with open(self.session_file, encoding="utf-8") as f:
+                session_data = json.load(f)
+
+            # Import here to avoid circular imports
+            from note_mcp.models import Session
+
+            return Session(**session_data)
+        except json.JSONDecodeError as e:
+            # File is corrupted - distinct from "no session"
+            logger.error(f"Session file corrupted (invalid JSON): {e}")
+            logger.info(f"Consider deleting corrupted file: {self.session_file}")
+            return None
+        except (TypeError, ValueError) as e:
+            # Invalid data structure
+            logger.error(f"Session file has invalid data structure: {e}")
+            logger.info(f"Consider deleting invalid file: {self.session_file}")
+            return None
+        except OSError as e:
+            logger.warning(f"Failed to read session file: {e}")
+            return None
+
+    def clear(self) -> bool:
+        """Clear session by deleting the session file.
+
+        Returns:
+            True if session was cleared successfully, False if deletion failed.
+            Returns True if no session file exists (nothing to clear).
+        """
+        if not self.session_file.exists():
+            logger.debug("No session file to clear")
+            return True
+
+        try:
+            self.session_file.unlink()
+            logger.debug(f"Session file deleted: {self.session_file}")
+            return True
+        except OSError as e:
+            logger.error(f"Failed to delete session file (security concern): {e}")
+            return False
+
+    def has_session(self) -> bool:
+        """Check if a session file exists.
+
+        Returns:
+            True if session file exists, False otherwise
+        """
+        return self.session_file.exists()

package/py/src/note_mcp/auth/session.py

@@ -0,0 +1,240 @@
+"""Session management with keyring storage.
+
+Provides secure session storage using the system keyring.
+Includes diagnostic information when keyring is not available.
+
+For Docker/headless environments where keyring is not available,
+set USE_FILE_SESSION=1 to use file-based session storage.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+from typing import TYPE_CHECKING
+
+import keyring
+from keyring.errors import PasswordDeleteError
+
+from note_mcp.auth.file_session import FileBasedSessionManager
+from note_mcp.models import Session
+
+if TYPE_CHECKING:
+    pass
+
+
+class KeyringError(Exception):
+    """Exception raised when keyring operations fail.
+
+    Includes diagnostic information to help users troubleshoot
+    keyring configuration issues.
+
+    Attributes:
+        message: Human-readable error message
+        os_info: Operating system information
+        backend_info: Keyring backend information
+        setup_instructions: Steps to configure keyring
+    """
+
+    def __init__(
+        self,
+        message: str,
+        os_info: str,
+        backend_info: str | None = None,
+        setup_instructions: list[str] | None = None,
+    ) -> None:
+        """Initialize KeyringError with diagnostic information.
+
+        Args:
+            message: Human-readable error message
+            os_info: Operating system information
+            backend_info: Keyring backend information (if available)
+            setup_instructions: Steps to configure keyring
+        """
+        self.message = message
+        self.os_info = os_info
+        self.backend_info = backend_info
+        self.setup_instructions = setup_instructions or []
+        super().__init__(self._format_message())
+
+    def _format_message(self) -> str:
+        """Format the error message with diagnostic information."""
+        parts = [self.message]
+        parts.append(f"\nOS: {self.os_info}")
+        if self.backend_info:
+            parts.append(f"Backend: {self.backend_info}")
+        if self.setup_instructions:
+            parts.append("\nSetup instructions:")
+            for instruction in self.setup_instructions:
+                parts.append(f"  - {instruction}")
+        return "\n".join(parts)
+
+
+def _get_os_info() -> str:
+    """Get operating system information for diagnostics."""
+    return f"{platform.system()} {platform.release()}"
+
+
+def _get_backend_info() -> str | None:
+    """Get keyring backend information for diagnostics."""
+    try:
+        backend = keyring.get_keyring()
+        return type(backend).__name__
+    except Exception:
+        return None
+
+
+def _get_setup_instructions() -> list[str]:
+    """Get setup instructions based on the current platform."""
+    system = platform.system()
+    instructions: list[str] = []
+
+    if system == "Linux":
+        instructions = [
+            "Install a keyring backend: sudo apt-get install gnome-keyring",
+            "Or install libsecret: sudo apt-get install libsecret-1-0",
+            "For headless servers, consider using keyrings.alt: pip install keyrings.alt",
+            "Then configure with: python -c 'import keyring; print(keyring.get_keyring())'",
+        ]
+    elif system == "Darwin":
+        instructions = [
+            "macOS should use Keychain automatically",
+            "If issues persist, try: security unlock-keychain",
+            "Check Keychain Access app for any locked keychains",
+        ]
+    elif system == "Windows":
+        instructions = [
+            "Windows should use Windows Credential Locker automatically",
+            "If issues persist, check Windows Credential Manager",
+            "Try running as administrator if access is denied",
+        ]
+    else:
+        instructions = [
+            "Install a compatible keyring backend",
+            "See: https://pypi.org/project/keyring/",
+        ]
+
+    return instructions
+
+
+class SessionManager:
+    """Manages session storage using keyring or file-based backend.
+
+    Provides secure storage of session data in the system keyring.
+    When keyring is not available, provides clear diagnostic information.
+
+    For Docker/headless environments, set USE_FILE_SESSION=1 to use
+    file-based session storage instead of keyring.
+
+    Attributes:
+        service_name: The keyring service name used for storage
+    """
+
+    DEFAULT_SERVICE_NAME = "note-mcp"
+    SESSION_KEY = "session"
+
+    def __init__(self, service_name: str | None = None) -> None:
+        """Initialize SessionManager.
+
+        Args:
+            service_name: Keyring service name (default: "note-mcp")
+        """
+        self.service_name = service_name or self.DEFAULT_SERVICE_NAME
+
+        # Use file-based backend when USE_FILE_SESSION=1
+        if os.environ.get("USE_FILE_SESSION") == "1":
+            self._backend: FileBasedSessionManager | None = FileBasedSessionManager()
+        else:
+            self._backend = None  # Use keyring directly
+
+    def save(self, session: Session) -> None:
+        """Save session to keyring or file backend.
+
+        Args:
+            session: Session object to save
+
+        Raises:
+            KeyringError: If keyring operation fails (when using keyring)
+            OSError: If file operation fails (when using file backend)
+        """
+        if self._backend:
+            self._backend.save(session)
+            return
+
+        try:
+            session_data = session.model_dump()
+            session_json = json.dumps(session_data)
+            keyring.set_password(self.service_name, self.SESSION_KEY, session_json)
+        except Exception as e:
+            raise KeyringError(
+                message=f"Failed to save session to keyring: {e}",
+                os_info=_get_os_info(),
+                backend_info=_get_backend_info(),
+                setup_instructions=_get_setup_instructions(),
+            ) from e
+
+    def load(self) -> Session | None:
+        """Load session from keyring or file backend.
+
+        Returns:
+            Session object if found and valid, None otherwise
+
+        Raises:
+            KeyringError: If keyring operation fails (when using keyring)
+        """
+        if self._backend:
+            return self._backend.load()
+
+        try:
+            session_json = keyring.get_password(self.service_name, self.SESSION_KEY)
+        except Exception as e:
+            raise KeyringError(
+                message=f"Failed to load session from keyring: {e}",
+                os_info=_get_os_info(),
+                backend_info=_get_backend_info(),
+                setup_instructions=_get_setup_instructions(),
+            ) from e
+
+        if session_json is None:
+            return None
+
+        try:
+            session_data = json.loads(session_json)
+            return Session(**session_data)
+        except (json.JSONDecodeError, TypeError, ValueError):
+            # Invalid JSON or invalid session data
+            return None
+
+    def clear(self) -> None:
+        """Clear session from keyring or file backend.
+
+        Does not raise an error if no session exists.
+        """
+        if self._backend:
+            self._backend.clear()
+            return
+
+        try:
+            keyring.delete_password(self.service_name, self.SESSION_KEY)
+        except PasswordDeleteError:
+            # Session didn't exist, which is fine
+            pass
+        except Exception:
+            # Silently ignore other errors on clear
+            pass
+
+    def has_session(self) -> bool:
+        """Check if a session exists in keyring or file backend.
+
+        Returns:
+            True if a valid session exists, False otherwise
+        """
+        if self._backend:
+            return self._backend.has_session()
+
+        try:
+            session_json = keyring.get_password(self.service_name, self.SESSION_KEY)
+            return session_json is not None
+        except Exception:
+            return False

package/py/src/note_mcp/browser/__init__.py

@@ -0,0 +1,10 @@
+"""Browser module for note-mcp.
+
+Provides Playwright-based browser automation for login and preview.
+"""
+
+from note_mcp.browser.config import HEADLESS_ENV_VAR, get_headless_mode
+from note_mcp.browser.manager import BrowserManager
+from note_mcp.browser.preview import show_preview
+
+__all__ = ["BrowserManager", "show_preview", "get_headless_mode", "HEADLESS_ENV_VAR"]

package/py/src/note_mcp/browser/config.py

@@ -0,0 +1,21 @@
+"""Browser configuration utilities.
+
+Provides configuration functions for browser automation.
+"""
+
+import os
+
+# Environment variable name for headless mode configuration
+HEADLESS_ENV_VAR = "NOTE_MCP_TEST_HEADLESS"
+
+
+def get_headless_mode() -> bool:
+    """Get headless mode from NOTE_MCP_TEST_HEADLESS environment variable.
+
+    Default: True (headless mode for CI/CD stability)
+    Set NOTE_MCP_TEST_HEADLESS=false to show browser window for debugging.
+
+    Returns:
+        True if headless mode is enabled (default)
+    """
+    return os.environ.get(HEADLESS_ENV_VAR, "true").lower() != "false"

package/py/src/note_mcp/browser/manager.py

@@ -0,0 +1,182 @@
+"""Browser manager for Playwright automation.
+
+Provides singleton browser instance management with page reuse.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import atexit
+import logging
+from typing import TYPE_CHECKING, ClassVar
+
+from playwright.async_api import Page, async_playwright
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from playwright.async_api import Browser, BrowserContext, Playwright
+
+
+class BrowserManager:
+    """Manages Playwright browser instance as singleton.
+
+    Provides page reuse and proper cleanup on exit.
+    Uses asyncio.Lock for thread-safe access.
+
+    Class Attributes:
+        _instance: Singleton instance
+        _browser: Playwright Browser instance
+        _context: Browser context
+        _page: Reusable page instance
+        _lock: Async lock for thread-safe access
+    """
+
+    _instance: ClassVar[BrowserManager | None] = None
+    _playwright: Playwright | None = None
+    _browser: Browser | None = None
+    _context: BrowserContext | None = None
+    _page: Page | None = None
+    _lock: asyncio.Lock | None = None
+
+    def __init__(self) -> None:
+        """Initialize browser manager.
+
+        Should not be called directly. Use get_instance() instead.
+        """
+        pass
+
+    @classmethod
+    def get_instance(cls) -> BrowserManager:
+        """Get singleton instance of BrowserManager.
+
+        Returns:
+            BrowserManager singleton instance
+        """
+        if cls._instance is None:
+            cls._instance = cls()
+            cls._lock = asyncio.Lock()
+            # Register cleanup on exit
+            atexit.register(cls._sync_cleanup)
+        return cls._instance
+
+    @classmethod
+    def _sync_cleanup(cls) -> None:
+        """Synchronous cleanup for atexit hook."""
+        if cls._browser is not None:
+            try:
+                loop = asyncio.get_event_loop()
+                if loop.is_running():
+                    # Schedule cleanup if loop is running
+                    loop.create_task(cls._async_cleanup())
+                else:
+                    # Run cleanup directly if loop is not running
+                    loop.run_until_complete(cls._async_cleanup())
+            except RuntimeError as e:
+                # Only handle "no event loop" errors, re-raise others
+                error_msg = str(e).lower()
+                if "no running event loop" in error_msg or "no current event loop" in error_msg:
+                    asyncio.run(cls._async_cleanup())
+                else:
+                    raise
+
+    @classmethod
+    async def _async_cleanup(cls) -> None:
+        """Async cleanup for browser resources."""
+        if cls._browser is not None:
+            await cls._safe_close_browser()
+            cls._browser = None
+        if cls._playwright is not None:
+            await cls._safe_stop_playwright()
+            cls._playwright = None
+        cls._context = None
+        cls._page = None
+
+    @classmethod
+    async def _safe_close_browser(cls) -> None:
+        """Safely close browser, logging errors at debug level."""
+        try:
+            if cls._browser is not None:
+                await cls._browser.close()
+        except Exception as e:  # noqa: BLE001 - intentionally broad for cleanup
+            logger.debug("Browser cleanup error (non-fatal): %s", e, exc_info=True)
+
+    @classmethod
+    async def _safe_stop_playwright(cls) -> None:
+        """Safely stop playwright, logging errors at debug level."""
+        try:
+            if cls._playwright is not None:
+                await cls._playwright.stop()
+        except Exception as e:  # noqa: BLE001 - intentionally broad for cleanup
+            logger.debug("Playwright cleanup error (non-fatal): %s", e, exc_info=True)
+
+    async def _ensure_browser(self, headless: bool | None = None) -> None:
+        """Ensure browser is started.
+
+        Args:
+            headless: If True, run in headless mode. If False, show browser window.
+                     If None, use the default from config (NOTE_MCP_TEST_HEADLESS env var).
+        """
+        if self._playwright is None:
+            self.__class__._playwright = await async_playwright().start()
+        playwright = self._playwright
+        assert playwright is not None
+
+        if self._browser is None:
+            if headless is None:
+                from note_mcp.browser.config import get_headless_mode
+
+                headless = get_headless_mode()
+            self.__class__._browser = await playwright.chromium.launch(headless=headless)
+        browser = self._browser
+        assert browser is not None
+
+        if self._context is None:
+            self.__class__._context = await browser.new_context()
+        context = self._context
+        assert context is not None
+
+        if self._page is None or self._page.is_closed():
+            self.__class__._page = await context.new_page()
+
+    async def get_page(self, headless: bool | None = None) -> Page:
+        """Get a browser page, creating if necessary.
+
+        Reuses existing page if available and not closed.
+        Uses lock for thread-safe access.
+
+        Args:
+            headless: If True, run in headless mode. If False, show browser window.
+                     If None, use the default from config (NOTE_MCP_TEST_HEADLESS env var).
+
+                     IMPORTANT: This parameter is only used when launching a NEW browser.
+                     If a browser already exists, this parameter is SILENTLY IGNORED.
+                     Call close() first if you need to change the headless mode.
+
+        Returns:
+            Playwright Page instance
+        """
+        if self._lock is None:
+            self.__class__._lock = asyncio.Lock()
+        lock = self._lock
+        assert lock is not None
+
+        async with lock:
+            # Check if existing page is still valid
+            if self._page is not None and not self._page.is_closed():
+                return self._page
+
+            # Create new browser/page if needed
+            await self._ensure_browser(headless=headless)
+            assert self._page is not None
+            return self._page
+
+    async def close(self) -> None:
+        """Close browser and cleanup resources."""
+        if self._lock is None:
+            self.__class__._lock = asyncio.Lock()
+        lock = self._lock
+        assert lock is not None
+
+        async with lock:
+            await self._async_cleanup()

package/py/src/note_mcp/browser/preview.py

@@ -0,0 +1,68 @@
+"""Browser-based article preview using API access token.
+
+Provides functionality to show article preview in browser via API.
+This approach is faster and more stable than the editor-based approach.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from playwright.async_api import Error as PlaywrightError
+from playwright.async_api import TimeoutError as PlaywrightTimeoutError
+
+from note_mcp.api.articles import build_preview_url, get_preview_access_token
+from note_mcp.browser.manager import BrowserManager
+
+if TYPE_CHECKING:
+    from note_mcp.models import Session
+
+
+async def show_preview(
+    session: Session,
+    article_key: str,
+) -> None:
+    """Show article preview in browser via API.
+
+    Gets preview access token via API and navigates directly
+    to preview URL. Faster and more stable than editor-based approach.
+
+    Args:
+        session: Authenticated session with username
+        article_key: Article key (e.g., "n1234567890ab")
+
+    Raises:
+        NoteAPIError: If token fetch fails
+        RuntimeError: If browser navigation fails
+    """
+    # Get preview access token via API
+    access_token = await get_preview_access_token(session, article_key)
+
+    # Build preview URL
+    preview_url = build_preview_url(article_key, access_token)
+
+    # Get browser page
+    manager = BrowserManager.get_instance()
+    page = await manager.get_page()
+
+    # Inject session cookies into browser context
+    playwright_cookies: list[dict[str, Any]] = []
+    for name, value in session.cookies.items():
+        playwright_cookies.append(
+            {
+                "name": name,
+                "value": value,
+                "domain": ".note.com",
+                "path": "/",
+            }
+        )
+    await page.context.add_cookies(playwright_cookies)  # type: ignore[arg-type]
+
+    # Navigate directly to preview URL (no editor involved)
+    try:
+        await page.goto(preview_url, wait_until="domcontentloaded")
+        await page.wait_for_load_state("networkidle")
+    except PlaywrightTimeoutError as e:
+        raise RuntimeError(f"Preview page load timed out: {preview_url}") from e
+    except PlaywrightError as e:
+        raise RuntimeError(f"Browser navigation failed: {e}") from e

package/py/src/note_mcp/browser/url_helpers.py

@@ -0,0 +1,18 @@
+"""URL helper utilities for browser automation.
+
+Provides common URL validation and manipulation functions.
+"""
+
+
+def validate_article_edit_url(current_url: str, article_key: str) -> bool:
+    """Validate that the current URL is a valid article edit page.
+
+    Args:
+        current_url: The current browser URL
+        article_key: The expected article key (e.g., "n1234567890ab")
+
+    Returns:
+        True if the URL is a valid article edit page, False otherwise
+    """
+    valid_patterns = [f"/notes/{article_key}", f"/n/{article_key}", "editor.note.com"]
+    return any(pattern in current_url for pattern in valid_patterns)

package/py/src/note_mcp/chatgpt/__init__.py

@@ -0,0 +1 @@
+"""ChatGPT Apps SDK connector layer for note-connector."""