vibetuner 2.26.6__py3-none-any.whl

vibetuner/models/types.py

@@ -0,0 +1,16 @@
+"""Common type definitions for models.
+
+WARNING: This is a scaffolding-managed file. DO NOT MODIFY directly.
+Provides type aliases and re-exports for consistent typing across models.
+"""
+
+from typing import TYPE_CHECKING, TypeAlias, TypeVar
+
+from beanie import Document, Link as BeanieLink
+
+
+if TYPE_CHECKING:
+    _T = TypeVar("_T", bound=Document)
+    Link: TypeAlias = _T
+else:
+    Link = BeanieLink

vibetuner/models/user.py

@@ -0,0 +1,91 @@
+"""Core user model for authentication and user management.
+
+WARNING: This is a scaffolding-managed file. DO NOT MODIFY directly.
+Extend functionality by creating custom models that reference or extend these models.
+"""
+
+from functools import cached_property
+from typing import Any, List, Self
+
+from beanie import Document
+from beanie.operators import Eq
+from pydantic import BaseModel, Field
+from pydantic_extra_types.language_code import LanguageAlpha2
+
+from vibetuner.models.registry import register_model
+
+from .mixins import TimeStampMixin
+from .oauth import OAuthAccountModel
+from .types import Link
+
+
+class UserSettings(BaseModel):
+    """User settings for the application.
+
+    This class holds the default settings for the user, such as language and theme.
+    It can be extended to include more user-specific settings in the future.
+    """
+
+    language: LanguageAlpha2 | None = Field(
+        default=None,
+        description="Preferred language for the user",
+    )
+
+    @cached_property
+    def session_dict(self) -> dict[str, Any]:
+        """Return a dictionary representation of the user settings for session storage.
+
+        Make sure to only include fields that are necessary for the session.
+        """
+        return self.model_dump(
+            exclude_none=True,
+            exclude_unset=True,
+            include={
+                "language",
+            },
+        )
+
+
+@register_model
+class UserModel(Document, TimeStampMixin):
+    email: str | None = Field(
+        default=None,
+        description="Primary email address for authentication",
+    )
+    name: str | None = Field(
+        default=None,
+        description="User's full display name",
+    )
+    picture: str | None = Field(
+        default=None,
+        description="URL to user's profile picture or avatar",
+    )
+    oauth_accounts: List[Link[OAuthAccountModel]] = Field(
+        default_factory=list,
+        description="Connected OAuth provider accounts (Google, GitHub, etc.)",
+    )
+
+    user_settings: UserSettings = Field(
+        default_factory=UserSettings,
+        description="User-specific settings for the application",
+    )
+
+    class Settings:
+        name = "users"
+        keep_nulls = False
+
+    @cached_property
+    def session_dict(self) -> dict[str, Any]:
+        return {
+            "id": str(self.id),
+            **self.model_dump(
+                exclude_none=True,
+                exclude_unset=True,
+                include={"name", "email", "picture"},
+            ),
+            "settings": self.user_settings.session_dict,
+        }
+
+    @classmethod
+    async def get_by_email(cls, email: str) -> Self | None:
+        return await cls.find_one(Eq(cls.email, email))

vibetuner/mongo.py

@@ -0,0 +1,33 @@
+from importlib import import_module
+
+from beanie import init_beanie
+from pymongo import AsyncMongoClient
+
+from vibetuner.config import settings
+from vibetuner.logging import logger
+from vibetuner.models.registry import get_all_models
+
+
+async def init_models() -> None:
+    """Initialize MongoDB connection and register all Beanie models."""
+
+    # Try to import user models to trigger their registration
+    try:
+        import_module("app.models")
+    except ModuleNotFoundError:
+        # Silent pass for missing app.models module (expected in some projects)
+        pass
+    except ImportError as e:
+        # Log warning for any import error (including syntax errors, missing dependencies, etc.)
+        logger.warning(
+            f"Failed to import app.models: {e}. User models will not be registered."
+        )
+
+    client: AsyncMongoClient = AsyncMongoClient(
+        host=str(settings.mongodb_url),
+        compressors=["zstd"],
+    )
+
+    await init_beanie(
+        database=client[settings.mongo_dbname], document_models=get_all_models()
+    )

vibetuner/paths.py

@@ -0,0 +1,250 @@
+from importlib.resources import files
+from pathlib import Path
+from typing import Self
+
+from pydantic import computed_field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from vibetuner.logging import logger
+
+
+# Package-relative paths (for bundled templates in the vibetuner package)
+_package_files = files("vibetuner")
+_package_templates_traversable = _package_files / "templates"
+
+
+def _get_package_templates_path() -> Path:
+    """Get package templates path, works for both installed and editable installs."""
+    try:
+        return Path(str(_package_templates_traversable))
+    except (TypeError, ValueError):
+        raise RuntimeError(
+            "Package templates are in a non-filesystem location. "
+            "This is not yet supported."
+        ) from None
+
+
+def create_core_templates_symlink(target: Path) -> None:
+    """Create or update a 'core' symlink pointing to the package templates directory."""
+
+    try:
+        source = _get_package_templates_path().resolve()
+    except RuntimeError as e:
+        logger.error(f"Cannot create symlink: {e}")
+        return
+
+    # Case 1: target does not exist → create symlink
+    if not target.exists():
+        target.symlink_to(source, target_is_directory=True)
+        logger.info(f"Created symlink '{target}' → '{source}'")
+        return
+
+    # Case 2: exists but is not a symlink → error
+    if not target.is_symlink():
+        logger.error(f"Cannot create symlink: '{target}' exists and is not a symlink.")
+        raise FileExistsError(
+            f"Cannot create symlink: '{target}' exists and is not a symlink."
+        )
+
+    # Case 3: is a symlink but points somewhere else → update it
+    if target.resolve() != source:
+        target.unlink()
+        target.symlink_to(source, target_is_directory=True)
+        logger.info(f"Updated symlink '{target}' → '{source}'")
+
+
+# Package templates always available
+package_templates = _get_package_templates_path()
+core_templates = package_templates  # Alias for backwards compatibility
+
+
+class PathSettings(BaseSettings):
+    """Path settings with lazy auto-detection of project root."""
+
+    model_config = SettingsConfigDict(
+        case_sensitive=False,
+        extra="ignore",
+        validate_default=True,
+    )
+
+    root: Path | None = None
+    fallback_path: str = "defaults"
+
+    @model_validator(mode="after")
+    def detect_project_root(self) -> Self:
+        """Auto-detect project root if not explicitly set."""
+        if self.root is None:
+            detected = self._find_project_root()
+            if detected is not None:
+                self.root = detected
+        return self
+
+    @staticmethod
+    def _find_project_root() -> Path | None:
+        """Find project root by searching for marker files."""
+        markers = [".copier-answers.yml", "pyproject.toml", ".git"]
+        current = Path.cwd()
+
+        for parent in [current, *current.parents]:
+            if any((parent / marker).exists() for marker in markers):
+                return parent
+
+        return None
+
+    # Project-specific paths (only available if root is set)
+    @computed_field
+    @property
+    def templates(self) -> Path | None:
+        """Project templates directory."""
+        return self.root / "templates" if self.root else None
+
+    @computed_field
+    @property
+    def app_templates(self) -> Path | None:
+        """Deprecated: use templates instead."""
+        return self.templates
+
+    @computed_field
+    @property
+    def locales(self) -> Path | None:
+        """Project locales directory."""
+        return self.root / "locales" if self.root else None
+
+    @computed_field
+    @property
+    def config_vars(self) -> Path | None:
+        """Copier answers file."""
+        return self.root / ".copier-answers.yml" if self.root else None
+
+    @computed_field
+    @property
+    def assets(self) -> Path | None:
+        """Project assets directory."""
+        return self.root / "assets" if self.root else None
+
+    @computed_field
+    @property
+    def statics(self) -> Path | None:
+        """Project static assets directory."""
+        return self.root / "assets" / "statics" if self.root else None
+
+    @computed_field
+    @property
+    def css(self) -> Path | None:
+        """Project CSS directory."""
+        return self.root / "assets" / "statics" / "css" if self.root else None
+
+    @computed_field
+    @property
+    def js(self) -> Path | None:
+        """Project JavaScript directory."""
+        return self.root / "assets" / "statics" / "js" if self.root else None
+
+    @computed_field
+    @property
+    def favicons(self) -> Path | None:
+        """Project favicons directory."""
+        return self.root / "assets" / "statics" / "favicons" if self.root else None
+
+    @computed_field
+    @property
+    def img(self) -> Path | None:
+        """Project images directory."""
+        return self.root / "assets" / "statics" / "img" if self.root else None
+
+    # Template paths (always return a list, project + package)
+    @computed_field
+    @property
+    def frontend_templates(self) -> list[Path]:
+        """Frontend template search paths (project overrides, then package)."""
+        paths = []
+        if self.root:
+            project_path = self.root / "templates" / "frontend"
+            if project_path.exists():
+                paths.append(project_path)
+        paths.append(package_templates / "frontend")
+        return paths
+
+    @computed_field
+    @property
+    def email_templates(self) -> list[Path]:
+        """Email template search paths (project overrides, then package)."""
+        paths = []
+        if self.root:
+            project_path = self.root / "templates" / "email"
+            if project_path.exists():
+                paths.append(project_path)
+        paths.append(package_templates / "email")
+        return paths
+
+    @computed_field
+    @property
+    def markdown_templates(self) -> list[Path]:
+        """Markdown template search paths (project overrides, then package)."""
+        paths = []
+        if self.root:
+            project_path = self.root / "templates" / "markdown"
+            if project_path.exists():
+                paths.append(project_path)
+        paths.append(package_templates / "markdown")
+        return paths
+
+    def to_template_path_list(self, path: Path) -> list[Path]:
+        """Convert path to list with fallback."""
+        return [path, path / self.fallback_path]
+
+    def fallback_static_default(self, static_type: str, file_name: str) -> Path:
+        """Return a fallback path for a static file."""
+        if self.statics is None:
+            raise RuntimeError(
+                "Project root not detected. Cannot access static assets."
+            )
+
+        paths_to_check = [
+            self.statics / static_type / file_name,
+            self.statics / self.fallback_path / static_type / file_name,
+        ]
+
+        for path in paths_to_check:
+            if path.exists():
+                return path
+
+        raise FileNotFoundError(
+            f"Could not find {file_name} in any of the fallback paths: {paths_to_check}"
+        )
+
+
+# Global settings instance with lazy auto-detection
+_settings = PathSettings()
+
+
+def to_template_path_list(path: Path) -> list[Path]:
+    """Convert path to list with fallback."""
+    return _settings.to_template_path_list(path)
+
+
+def fallback_static_default(static_type: str, file_name: str) -> Path:
+    """Return a fallback path for a static file."""
+    return _settings.fallback_static_default(static_type, file_name)
+
+
+# Expose settings instance for direct access
+paths = _settings
+
+# Module-level variables that delegate to settings (backwards compatibility)
+# Access like: from vibetuner.paths import frontend_templates
+# Or better: from vibetuner.paths import paths; paths.frontend_templates
+root = _settings.root
+templates = _settings.templates
+app_templates = _settings.app_templates
+locales = _settings.locales
+config_vars = _settings.config_vars
+assets = _settings.assets
+statics = _settings.statics
+css = _settings.css
+js = _settings.js
+favicons = _settings.favicons
+img = _settings.img
+frontend_templates = _settings.frontend_templates
+email_templates = _settings.email_templates
+markdown_templates = _settings.markdown_templates

vibetuner/services/blob.py

@@ -0,0 +1,175 @@
+"""Blob storage service for file uploads to S3 or R2.
+
+WARNING: This is a scaffolding-managed file. DO NOT MODIFY directly.
+To extend blob functionality, create wrapper services in the parent services directory.
+"""
+
+import mimetypes
+from pathlib import Path
+from typing import Literal
+
+import aioboto3
+from aiobotocore.config import AioConfig
+
+from vibetuner.config import settings
+from vibetuner.models import BlobModel
+from vibetuner.models.blob import BlobStatus
+
+
+S3_SERVICE_NAME: Literal["s3"] = "s3"
+DEFAULT_CONTENT_TYPE: str = "application/octet-stream"
+
+
+class BlobService:
+    def __init__(
+        self,
+        session: aioboto3.Session | None = None,
+        default_bucket: str | None = None,
+    ) -> None:
+        if (
+            settings.r2_bucket_endpoint_url is None
+            or settings.r2_access_key is None
+            or settings.r2_secret_key is None
+        ):
+            raise ValueError(
+                "R2 bucket endpoint URL, access key, and secret key must be set in settings."
+            )
+        self.session = session or aioboto3.Session(
+            aws_access_key_id=settings.r2_access_key.get_secret_value(),
+            aws_secret_access_key=settings.r2_secret_key.get_secret_value(),
+            region_name=settings.r2_default_region,
+        )
+        self.endpoint_url = str(settings.r2_bucket_endpoint_url)
+        self.config = AioConfig(
+            request_checksum_calculation="when_required",
+            response_checksum_validation="when_required",
+        )
+
+        if not default_bucket:
+            if settings.r2_default_bucket_name is None:
+                raise ValueError(
+                    "Default bucket name must be provided either in settings or as an argument."
+                )
+            self.default_bucket = settings.r2_default_bucket_name
+        else:
+            self.default_bucket = default_bucket
+
+    async def put_object(
+        self,
+        body: bytes,
+        content_type: str = DEFAULT_CONTENT_TYPE,
+        bucket: str | None = None,
+        namespace: str | None = None,
+        original_filename: str | None = None,
+    ) -> BlobModel:
+        """Put an object into the R2 bucket and return the blob model"""
+
+        bucket = bucket or self.default_bucket
+
+        blob = BlobModel.from_bytes(
+            body=body,
+            content_type=content_type,
+            bucket=bucket,
+            namespace=namespace,
+            original_filename=original_filename,
+        )
+
+        await blob.insert()
+
+        if not blob.id:
+            raise ValueError("Blob ID must be set before uploading to R2.")
+
+        try:
+            async with self.session.client(
+                service_name=S3_SERVICE_NAME,
+                endpoint_url=self.endpoint_url,
+                config=self.config,
+            ) as s3_client:
+                await s3_client.put_object(
+                    Bucket=bucket,
+                    Key=blob.full_path,
+                    Body=body,
+                    ContentType=content_type,
+                )
+            blob.status = BlobStatus.UPLOADED
+        except Exception:
+            blob.status = BlobStatus.ERROR
+        finally:
+            await blob.save()
+
+        return blob
+
+    async def put_object_with_extension(
+        self,
+        body: bytes,
+        extension: str,
+        bucket: str | None = None,
+        namespace: str | None = None,
+    ) -> BlobModel:
+        """Put an object into the R2 bucket with content type guessed from extension"""
+        content_type, _ = mimetypes.guess_type(f"file.{extension.lstrip('.')}")
+        content_type = content_type or DEFAULT_CONTENT_TYPE
+
+        return await self.put_object(body, content_type, bucket, namespace)
+
+    async def put_file(
+        self,
+        file_path: Path | str,
+        content_type: str | None = None,
+        bucket: str | None = None,
+        namespace: str | None = None,
+    ) -> BlobModel:
+        """Put a file from filesystem into the R2 bucket"""
+        file_path = Path(file_path)
+
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        # Auto-detect content type if not provided
+        if content_type is None:
+            content_type, _ = mimetypes.guess_type(str(file_path))
+            content_type = content_type or DEFAULT_CONTENT_TYPE
+
+        return await self.put_object(
+            file_path.read_bytes(),
+            content_type,
+            bucket,
+            namespace,
+            original_filename=file_path.name,
+        )
+
+    async def get_object(self, key: str) -> bytes:
+        """Retrieve an object from the R2 bucket"""
+        blob = await BlobModel.get(key)
+        if not blob:
+            raise ValueError(f"Blob not found: {key}")
+
+        async with self.session.client(
+            service_name=S3_SERVICE_NAME,
+            endpoint_url=self.endpoint_url,
+            config=self.config,
+        ) as s3_client:
+            response = await s3_client.get_object(
+                Bucket=blob.bucket,
+                Key=blob.full_path,
+            )
+            return await response["Body"].read()
+
+    async def delete_object(self, key: str) -> None:
+        """Delete an object from the R2 bucket"""
+        blob = await BlobModel.get(key)
+        if not blob:
+            raise ValueError(f"Blob not found: {key}")
+
+        blob.status = BlobStatus.DELETED
+
+        await blob.save()
+
+    async def object_exists(self, key: str, check_bucket: bool = False) -> bool:
+        """Check if an object exists in the R2 bucket"""
+
+        blob = await BlobModel.get(key)
+        if not blob:
+            return False
+
+        return True

vibetuner/services/email.py

@@ -0,0 +1,50 @@
+"""Email service for sending transactional emails via AWS SES.
+
+WARNING: This is a scaffolding-managed file. DO NOT MODIFY directly.
+To extend email functionality, create wrapper services in the parent services directory.
+"""
+
+from typing import Literal
+
+import boto3
+
+from vibetuner.config import settings
+
+
+SES_SERVICE_NAME: Literal["ses"] = "ses"
+
+
+class SESEmailService:
+    def __init__(
+        self,
+        ses_client=None,
+        from_email: str | None = None,
+    ) -> None:
+        self.ses_client = ses_client or boto3.client(
+            service_name=SES_SERVICE_NAME,
+            region_name=settings.project.aws_default_region,
+            aws_access_key_id=settings.aws_access_key_id.get_secret_value()
+            if settings.aws_access_key_id
+            else None,
+            aws_secret_access_key=settings.aws_secret_access_key.get_secret_value()
+            if settings.aws_secret_access_key
+            else None,
+        )
+        self.from_email = from_email or settings.project.from_email
+
+    async def send_email(
+        self, to_address: str, subject: str, html_body: str, text_body: str
+    ):
+        """Send email using Amazon SES"""
+        response = self.ses_client.send_email(
+            Source=self.from_email,
+            Destination={"ToAddresses": [to_address]},
+            Message={
+                "Subject": {"Data": subject, "Charset": "UTF-8"},
+                "Body": {
+                    "Html": {"Data": html_body, "Charset": "UTF-8"},
+                    "Text": {"Data": text_body, "Charset": "UTF-8"},
+                },
+            },
+        )
+        return response

vibetuner/tasks/lifespan.py

@@ -0,0 +1,28 @@
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+
+from vibetuner.context import Context, ctx
+from vibetuner.logging import logger
+from vibetuner.mongo import init_models
+
+
+@asynccontextmanager
+async def base_lifespan() -> AsyncGenerator[Context, None]:
+    logger.info("Vibetuner task worker starting")
+
+    await init_models()
+
+    yield ctx
+
+    logger.info("Vibetuner task worker stopping")
+
+
+try:
+    from app.tasks.lifespan import lifespan  # ty: ignore
+except ModuleNotFoundError:
+    # Silent pass for missing app.tasks.lifespan module (expected in some projects)
+    lifespan = base_lifespan
+except ImportError as e:
+    # Log warning for any import error (including syntax errors, missing dependencies, etc.)
+    logger.warning(f"Failed to import app.tasks.lifespan: {e}. Using base lifespan.")
+    lifespan = base_lifespan

vibetuner/tasks/worker.py

@@ -0,0 +1,15 @@
+from streaq import Worker
+
+from vibetuner.config import settings
+from vibetuner.tasks.lifespan import lifespan
+
+
+worker = Worker(
+    redis_url=str(settings.redis_url),
+    queue_name=(
+        settings.project.project_slug
+        if not settings.debug
+        else f"debug-{settings.project.project_slug}"
+    ),
+    lifespan=lifespan,
+)

vibetuner/templates/email/magic_link.html.jinja

@@ -0,0 +1,17 @@
+{# djlint:off #}
+<html>
+    <body>
+        <p>Click the link below to sign in to your account:</p>
+        <p>
+            <a href="{{ login_url }}"
+               style="background-color: #007bff;
+                      color: white;
+                      padding: 12px 24px;
+                      text-decoration: none;
+                      border-radius: 4px">Sign In</a>
+        </p>
+        <p>This link will expire in 15 minutes.</p>
+        <p>If you didn't request this, you can safely ignore this email.</p>
+    </body>
+</html>
+{# djlint:on #}

vibetuner/templates/email/magic_link.txt.jinja

@@ -0,0 +1,5 @@
+Sign in to {{ project_name }}
+Copy and paste this link into your browser to sign in:
+{{ login_url }}
+This link will expire in 15 minutes.
+If you didn't request this, you can safely ignore this email.

vibetuner/templates/frontend/base/favicons.html.jinja

@@ -0,0 +1 @@
+<link rel="manifest" href="{{ url_for('site_webmanifest').path }}" />