solstone 0.1.1__py3-none-any.whl

solstone/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (c) 2026 sol pbc
+
+"""solstone namespace package."""

solstone/apps/__init__.py

@@ -0,0 +1,350 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (c) 2026 sol pbc
+
+"""App plugin system for solstone.
+
+Convention-based app discovery with minimal configuration:
+
+Directory Structure:
+    apps/my_app/           # Use underscores, not hyphens!
+      workspace.html       # Required: Main template
+      routes.py            # Optional: Flask blueprint (for custom routes beyond index)
+      background.html      # Optional: Background service
+      app.json             # Optional: Metadata overrides
+      agents/              # Optional: Custom agents
+      tests/               # Optional: App-specific tests
+
+Naming Rules:
+    - App directory names must use underscores (my_app), not hyphens (my-app)
+    - App name = directory name (e.g., "my_app")
+    - Blueprint variable must be named {app_name}_bp (e.g., my_app_bp)
+    - Blueprint name must use "app:{name}" pattern for consistency
+      (e.g., Blueprint("app:home", ...), use url_for('app:home.index'))
+    - URL prefix convention: /app/{app_name}
+
+app.json fields (all optional):
+    {
+      "icon": "🏠",           # Emoji icon for menu bar (default: "📦")
+      "label": "Custom Label", # Display label (default: title-cased app name)
+      "facets": {},            # Facet options: {"disabled": true} to hide facet bar
+      "date_nav": true,        # Show date navigation bar (default: false)
+      "app_bar": false,        # Hide the universal chat bar on this app (default: true)
+      "allow_future_dates": true  # Allow future dates in month picker (default: false)
+    }
+
+    See the App dataclass below for the complete field list with types and defaults.
+
+Apps are automatically discovered and registered.
+All apps are served at /app/{name} via shared handler.
+Apps with routes.py can define custom routes beyond the index route.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+from flask import Blueprint
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class App:
+    """Convention-based app configuration."""
+
+    name: str
+    icon: str
+    label: str
+    blueprint: Optional[Blueprint] = None
+
+    # Template paths (relative to Flask template root)
+    workspace_template: str = ""
+    background_template: Optional[str] = None
+
+    # Facet configuration (optional, default {})
+    # Options:
+    #   - disabled: If true, facets bar is hidden for this app
+    facets_config: dict = field(default_factory=dict)
+
+    # Date navigation (renders date nav below facet bar)
+    date_nav: bool = False
+
+    # Hide the universal chat bar on this app
+    app_bar: bool = True
+
+    # Allow clicking future dates in month picker (for todos)
+    allow_future_dates: bool = False
+
+    def facets_enabled(self) -> bool:
+        """Check if facets are enabled for this app."""
+        return not self.facets_config.get("disabled", False)
+
+    def date_nav_enabled(self) -> bool:
+        """Check if date nav is enabled for this app."""
+        return self.date_nav
+
+    def get_blueprint(self) -> Optional[Blueprint]:
+        """Return Flask Blueprint with app routes, or None if app has no custom routes."""
+        return self.blueprint
+
+    def get_workspace_template(self) -> str:
+        """Return path to workspace template."""
+        return self.workspace_template
+
+    def get_background_template(self) -> Optional[str]:
+        """Return path to background service template, or None."""
+        return self.background_template
+
+
+class AppRegistry:
+    """Registry for discovering and managing solstone apps."""
+
+    def __init__(self):
+        self.apps: dict[str, App] = {}
+
+    def discover(self) -> None:
+        """Auto-discover apps using convention over configuration.
+
+        For each directory in apps/:
+        1. Check for workspace.html (required)
+        2. Load app.json if present (for icon, label overrides)
+        3. Import routes.py and get blueprint (optional - for custom routes)
+        4. Check for background.html (optional)
+        """
+        apps_dir = Path(__file__).parent
+
+        for app_path in sorted(apps_dir.iterdir()):
+            # Skip non-directories and private/internal directories
+            if not app_path.is_dir() or app_path.name.startswith("_"):
+                continue
+
+            app_name = app_path.name
+
+            # Skip if workspace.html doesn't exist (required)
+            if not (app_path / "workspace.html").exists():
+                logger.debug(f"Skipping {app_name}/ - no workspace.html found")
+                continue
+
+            try:
+                app = self._load_app(app_name, app_path)
+                self.apps[app_name] = app
+                logger.info(f"Discovered app: {app_name}")
+            except Exception as e:
+                logger.error(f"Failed to load app {app_name}: {e}", exc_info=True)
+
+    def _load_app(self, app_name: str, app_path: Path) -> App:
+        """Load a single app from its directory.
+
+        Args:
+            app_name: Name of the app (directory name)
+            app_path: Path to app directory
+
+        Returns:
+            App instance
+
+        Raises:
+            Exception: If app cannot be loaded
+        """
+        # Validate app name
+        if "-" in app_name:
+            logger.warning(
+                f"App '{app_name}' uses hyphens. Use underscores instead (e.g., 'my_app')"
+            )
+
+        # Load metadata from app.json (optional)
+        metadata = self._load_metadata(app_path)
+
+        # Get icon and label (with defaults)
+        icon = metadata.get("icon", "📦")
+        label = metadata.get("label", app_name.replace("_", " "))
+
+        # Parse facets config
+        facets_config = metadata.get("facets", {})
+        if not isinstance(facets_config, dict):
+            facets_config = {}
+
+        # Date navigation
+        date_nav = metadata.get("date_nav", False)
+
+        # Universal app bar
+        app_bar = metadata.get("app_bar", True)
+
+        # Allow future dates in month picker
+        allow_future_dates = metadata.get("allow_future_dates", False)
+
+        # Import routes module and get blueprint (optional)
+        blueprint = None
+        routes_module = None
+        routes_file = app_path / "routes.py"
+
+        if routes_file.exists():
+            routes_module = importlib.import_module(f"solstone.apps.{app_name}.routes")
+
+            # Find blueprint - look for *_bp attribute
+            expected_bp_var = f"{app_name}_bp"
+
+            for attr_name in dir(routes_module):
+                if attr_name.endswith("_bp"):
+                    bp = getattr(routes_module, attr_name)
+                    if isinstance(bp, Blueprint):
+                        blueprint = bp
+
+                        # Warn if variable name doesn't match convention
+                        if attr_name != expected_bp_var:
+                            logger.warning(
+                                f"App '{app_name}': Blueprint variable '{attr_name}' should be '{expected_bp_var}'"
+                            )
+
+                        break
+
+            if not blueprint:
+                raise ValueError(
+                    f"No blueprint found in apps.{app_name}.routes - "
+                    f"expected variable named '{expected_bp_var}'"
+                )
+
+            # Verify blueprint name uses "app:{name}" pattern for consistency
+            expected_name = f"app:{app_name}"
+            if blueprint.name != expected_name:
+                raise ValueError(
+                    f"App '{app_name}': Blueprint name must be '{expected_name}', "
+                    f"got '{blueprint.name}'. Update Blueprint() declaration in routes.py"
+                )
+        else:
+            # No routes.py - create a minimal blueprint
+            blueprint = self._create_minimal_blueprint(app_name)
+            logger.debug(
+                f"Created minimal blueprint for app '{app_name}' (no routes.py)"
+            )
+
+        # Inject default index route if app doesn't define one
+        self._inject_index_if_needed(blueprint, routes_module, app_name)
+
+        # Resolve template paths (relative to apps/ directory since that's in the loader)
+        workspace_template = f"{app_name}/workspace.html"
+
+        background_template = None
+        if (app_path / "background.html").exists():
+            background_template = f"{app_name}/background.html"
+
+        return App(
+            name=app_name,
+            icon=icon,
+            label=label,
+            blueprint=blueprint,
+            workspace_template=workspace_template,
+            background_template=background_template,
+            facets_config=facets_config,
+            date_nav=date_nav,
+            app_bar=app_bar,
+            allow_future_dates=allow_future_dates,
+        )
+
+    def _load_metadata(self, app_path: Path) -> dict[str, Any]:
+        """Load app.json metadata file if it exists.
+
+        Args:
+            app_path: Path to app directory
+
+        Returns:
+            Dict with metadata, or empty dict if no app.json
+        """
+        metadata_file = app_path / "app.json"
+        if metadata_file.exists():
+            try:
+                with open(metadata_file) as f:
+                    return json.load(f)
+            except Exception as e:
+                logger.warning(f"Failed to load {metadata_file}: {e}")
+        return {}
+
+    def _create_minimal_blueprint(self, app_name: str) -> Blueprint:
+        """Create a minimal blueprint for apps without routes.py.
+
+        Args:
+            app_name: Name of the app
+
+        Returns:
+            Blueprint with proper naming and URL prefix
+        """
+        blueprint = Blueprint(
+            f"app:{app_name}",
+            __name__,
+            url_prefix=f"/app/{app_name}",
+        )
+        return blueprint
+
+    def _inject_index_if_needed(
+        self, blueprint: Blueprint, routes_module: Any, app_name: str
+    ) -> None:
+        """Inject default index route if app doesn't define one.
+
+        Checks if routes module has an 'index' function. If not, adds a
+        default index route that renders app.html using blueprint.record()
+        to support multiple app registrations.
+
+        Args:
+            blueprint: The Flask blueprint to inject into
+            routes_module: The imported routes module (or None if no routes.py)
+            app_name: Name of the app
+        """
+        import inspect
+
+        has_index = False
+
+        if routes_module:
+            # Get functions defined in this module (not imported)
+            module_functions = [
+                name
+                for name, obj in inspect.getmembers(routes_module)
+                if inspect.isfunction(obj) and obj.__module__ == routes_module.__name__
+            ]
+            has_index = "index" in module_functions
+
+        if not has_index:
+            # No index function, inject default one using record() for deferred setup
+            # Only inject if blueprint hasn't been registered yet
+            if not blueprint._got_registered_once:
+
+                def index():
+                    from flask import render_template
+
+                    return render_template("app.html")
+
+                def setup_index(state):
+                    """Deferred setup function called when blueprint is registered."""
+                    state.app.add_url_rule(
+                        f"{blueprint.url_prefix}/",
+                        endpoint=f"{blueprint.name}.index",
+                        view_func=index,
+                    )
+
+                blueprint.record(setup_index)
+                logger.debug(f"Injected default index route for app '{app_name}'")
+
+    def register_blueprints(self, flask_app) -> None:
+        """Register all app blueprints with Flask.
+
+        Args:
+            flask_app: Flask application instance
+        """
+        for app in self.apps.values():
+            if not app.blueprint:
+                logger.error(
+                    f"App '{app.name}' has no blueprint - this should not happen"
+                )
+                continue
+
+            try:
+                flask_app.register_blueprint(app.blueprint)
+                logger.info(f"Registered blueprint: {app.blueprint.name}")
+            except Exception as e:
+                logger.error(
+                    f"Failed to register blueprint for app {app.name}: {e}",
+                    exc_info=True,
+                )