skrift 0.1.0a15__py3-none-any.whl → 0.1.0a17__py3-none-any.whl

skrift/asgi.py

@@ -22,6 +22,8 @@ from advanced_alchemy.extensions.litestar import (
     SQLAlchemyAsyncConfig,
     SQLAlchemyPlugin,
 )
+
+from skrift.db.session import SafeSQLAlchemyAsyncConfig
 from litestar import Litestar
 from litestar.config.compression import CompressionConfig
 from litestar.contrib.jinja import JinjaTemplateEngine
@@ -398,10 +400,11 @@ def create_app() -> Litestar:
             pool_size=settings.db.pool_size,
             max_overflow=settings.db.pool_overflow,
             pool_timeout=settings.db.pool_timeout,
+            pool_pre_ping=settings.db.pool_pre_ping,
             echo=settings.db.echo,
         )
 
-    db_config = SQLAlchemyAsyncConfig(
+    db_config = SafeSQLAlchemyAsyncConfig(
         connection_string=settings.db.url,
         metadata=Base.metadata,
         create_all=False,
@@ -564,10 +567,11 @@ def create_setup_app() -> Litestar:
                 pool_size=5,
                 max_overflow=10,
                 pool_timeout=30,
+                pool_pre_ping=True,
                 echo=False,
             )
 
-        db_config = SQLAlchemyAsyncConfig(
+        db_config = SafeSQLAlchemyAsyncConfig(
             connection_string=db_url,
             metadata=Base.metadata,
             create_all=False,

skrift/claude_skill/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: skrift
+description: "Help working with Skrift CMS codebases - a Python async CMS built on Litestar with WordPress-style conventions. Use for creating controllers, models, hooks, pages, and templates."
+---
+
+# Skrift CMS Development Guide
+
+Skrift is a lightweight async Python CMS built on Litestar, featuring WordPress-style template resolution, a hook/filter extensibility system, and SQLAlchemy async database access.
+
+## Current Project State
+
+**Configuration:**
+!`cat app.yaml 2>/dev/null || echo "No app.yaml found"`
+
+**Controllers:**
+!`ls skrift/controllers/*.py 2>/dev/null | head -10`
+
+**Models:**
+!`ls skrift/db/models/*.py 2>/dev/null | head -10`
+
+**Services:**
+!`ls skrift/db/services/*.py 2>/dev/null | head -10`
+
+**Templates:**
+!`ls templates/*.html 2>/dev/null | head -10 || echo "No custom templates"`
+
+## Quick Reference
+
+### Core Architecture
+
+- **Framework**: Litestar (async Python web framework)
+- **Database**: SQLAlchemy async with Advanced Alchemy
+- **Templates**: Jinja2 with WordPress-style template hierarchy
+- **Config**: YAML (app.yaml) + environment variables (.env)
+- **Auth**: OAuth providers + role-based permissions
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `skrift/asgi.py` | AppDispatcher, app creation, middleware loading |
+| `skrift/config.py` | Settings management, YAML config loading |
+| `skrift/cli.py` | CLI commands (serve, secret, db) |
+| `skrift/lib/hooks.py` | WordPress-like hook/filter system |
+| `skrift/lib/template.py` | Template resolution with fallbacks |
+| `skrift/db/base.py` | SQLAlchemy Base class (UUIDAuditBase) |
+| `skrift/auth/` | Guards, roles, permissions |
+
+### CLI Commands
+
+```bash
+# Run development server
+skrift serve --reload --port 8080
+
+# Generate secret key
+skrift secret                    # Print to stdout
+skrift secret --write .env       # Write to .env file
+
+# Database migrations (wraps Alembic)
+skrift db upgrade head           # Apply all migrations
+skrift db downgrade -1           # Rollback one migration
+skrift db current                # Show current revision
+skrift db revision -m "desc" --autogenerate  # Create migration
+```
+
+## Task-Specific Guidance
+
+### Creating a Controller
+
+Controllers are Litestar Controller classes registered in `app.yaml`:
+
+```python
+from litestar import Controller, get, post
+from litestar.response import Template as TemplateResponse
+from sqlalchemy.ext.asyncio import AsyncSession
+
+class MyController(Controller):
+    path = "/my-path"
+
+    @get("/")
+    async def list_items(self, db_session: AsyncSession) -> TemplateResponse:
+        # db_session is injected automatically
+        return TemplateResponse("my-template.html", context={"items": []})
+```
+
+Register in `app.yaml`:
+```yaml
+controllers:
+  - myapp.controllers:MyController
+```
+
+### Creating a Database Model
+
+Models inherit from `skrift.db.base.Base` (provides id, created_at, updated_at):
+
+```python
+from sqlalchemy import String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+from skrift.db.base import Base
+
+class MyModel(Base):
+    __tablename__ = "my_models"
+
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+```
+
+### Creating a Service
+
+Services are async functions that handle database operations:
+
+```python
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from skrift.db.models import MyModel
+
+async def get_item_by_id(db_session: AsyncSession, item_id: UUID) -> MyModel | None:
+    result = await db_session.execute(select(MyModel).where(MyModel.id == item_id))
+    return result.scalar_one_or_none()
+
+async def create_item(db_session: AsyncSession, name: str) -> MyModel:
+    item = MyModel(name=name)
+    db_session.add(item)
+    await db_session.commit()
+    await db_session.refresh(item)
+    return item
+```
+
+### Using Hooks
+
+The hook system provides WordPress-like extensibility:
+
+```python
+from skrift.lib.hooks import hooks, action, filter
+
+# Action: Side effects (no return value needed)
+@action("after_page_save", priority=10)
+async def notify_on_save(page, is_new: bool):
+    print(f"Page saved: {page.title}")
+
+# Filter: Transform values (must return value)
+@filter("page_seo_meta", priority=10)
+async def customize_meta(meta: dict, page) -> dict:
+    meta["author"] = "Custom Author"
+    return meta
+
+# Trigger hooks programmatically
+await hooks.do_action("my_action", arg1, arg2)
+result = await hooks.apply_filters("my_filter", initial_value, arg1)
+```
+
+Built-in hooks:
+- Actions: `before_page_save`, `after_page_save`, `before_page_delete`, `after_page_delete`
+- Filters: `page_seo_meta`, `page_og_meta`, `sitemap_urls`, `sitemap_page`, `robots_txt`, `template_context`
+
+### Using Guards (Authorization)
+
+Protect routes with permission or role guards:
+
+```python
+from skrift.auth import auth_guard, Permission, Role
+
+class AdminController(Controller):
+    path = "/admin"
+    guards = [auth_guard, Permission("manage-pages")]
+
+    @get("/")
+    async def admin_dashboard(self) -> TemplateResponse:
+        return TemplateResponse("admin/dashboard.html")
+```
+
+Combine requirements:
+```python
+# AND: Both required
+guards = [auth_guard, Permission("edit") & Permission("publish")]
+
+# OR: Either sufficient
+guards = [auth_guard, Role("admin") | Role("editor")]
+```
+
+### Template Resolution
+
+WordPress-style template hierarchy with fallbacks:
+
+```python
+from skrift.lib.template import Template
+
+# Tries: page-about.html -> page.html
+template = Template("page", "about")
+
+# Tries: post-news-2024.html -> post-news.html -> post.html
+template = Template("post", "news", "2024")
+
+return template.render(TEMPLATE_DIR, page=page, extra="context")
+```
+
+Templates searched in order:
+1. `./templates/` (project directory - user overrides)
+2. `skrift/templates/` (package directory - defaults)
+
+## Reference Documentation
+
+For detailed documentation, see:
+- [Architecture Details](architecture.md)
+- [Code Patterns](patterns.md)

skrift/claude_skill/architecture.md

@@ -0,0 +1,328 @@
+# Skrift Architecture
+
+## Application Lifecycle
+
+### AppDispatcher Pattern
+
+Skrift uses a dispatcher architecture that routes between setup and main applications:
+
+```
+                    ┌─────────────────────────────┐
+                    │      AppDispatcher          │
+                    │  (skrift/asgi.py)           │
+                    └─────────────┬───────────────┘
+                                  │
+              ┌───────────────────┼───────────────────┐
+              │                   │                   │
+              ▼                   ▼                   ▼
+     ┌────────────────┐   ┌────────────┐   ┌────────────────┐
+     │   Setup App    │   │  /static   │   │   Main App     │
+     │  (/setup/*)    │   │   Files    │   │  (everything)  │
+     └────────────────┘   └────────────┘   └────────────────┘
+```
+
+**Key behaviors:**
+- `setup_locked=False`: /setup/* routes active, checks DB for setup completion
+- `setup_locked=True`: All traffic goes to main app, /setup/* returns 404
+- Main app is lazily created after setup completes (no restart needed)
+
+**Entry point:** `skrift.asgi:app` (created by `create_dispatcher()`)
+
+### Startup Flow
+
+1. `create_dispatcher()` called at module load
+2. Checks if setup complete in database
+3. If complete + config valid: returns `create_app()` directly
+4. Otherwise: returns `AppDispatcher` with lazy main app creation
+
+### Request Flow
+
+```
+Request → AppDispatcher → Route Decision:
+  │
+  ├─ /setup/* or /static/* → Setup App
+  │
+  ├─ Setup not complete → Check DB:
+  │   ├─ Complete → Create main app, lock setup, route to main
+  │   └─ Not complete → Redirect to /setup
+  │
+  └─ Setup locked → Main App (handles everything including 404 for /setup/*)
+```
+
+## Configuration System
+
+### Configuration Flow
+
+```
+.env (loaded early) → app.yaml (with $VAR interpolation) → Settings (Pydantic)
+```
+
+### Environment-Specific Config
+
+| Environment | Config File |
+|-------------|-------------|
+| production (default) | `app.yaml` |
+| development | `app.dev.yaml` |
+| testing | `app.test.yaml` |
+
+Set via `SKRIFT_ENV` environment variable.
+
+### app.yaml Structure
+
+```yaml
+# Database connection
+db:
+  url: $DATABASE_URL  # Interpolates from .env
+  pool_size: 5
+  pool_overflow: 10
+  pool_timeout: 30
+  echo: false  # SQL logging
+
+# Authentication
+auth:
+  redirect_base_url: "https://example.com"
+  allowed_redirect_domains: []
+  providers:
+    google:
+      client_id: $GOOGLE_CLIENT_ID
+      client_secret: $GOOGLE_CLIENT_SECRET
+      scopes: ["openid", "email", "profile"]
+
+# Session cookies
+session:
+  cookie_domain: null  # null = exact host only
+
+# Controllers to load
+controllers:
+  - skrift.controllers.auth:AuthController
+  - skrift.controllers.web:WebController
+  - myapp.controllers:CustomController
+
+# Middleware (optional)
+middleware:
+  - myapp.middleware:create_logging_middleware
+  - factory: myapp.middleware:create_rate_limit
+    kwargs:
+      requests_per_minute: 100
+```
+
+### Settings Class (`skrift/config.py`)
+
+```python
+class Settings(BaseSettings):
+    debug: bool = False
+    secret_key: str  # Required - from .env
+
+    db: DatabaseConfig
+    auth: AuthConfig
+    session: SessionConfig
+```
+
+Access settings: `from skrift.config import get_settings`
+
+## Database Layer
+
+### Base Model
+
+All models inherit from `skrift.db.base.Base`:
+
+```python
+from advanced_alchemy.base import UUIDAuditBase
+
+class Base(UUIDAuditBase):
+    __abstract__ = True
+    # Provides: id (UUID), created_at, updated_at
+```
+
+### Session Access
+
+Sessions injected via Litestar's SQLAlchemy plugin:
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession
+
+@get("/")
+async def handler(self, db_session: AsyncSession) -> dict:
+    # db_session is auto-injected
+    ...
+```
+
+### Core Models
+
+| Model | Table | Purpose |
+|-------|-------|---------|
+| `User` | `users` | User accounts |
+| `OAuthAccount` | `oauth_accounts` | Linked OAuth providers |
+| `Role` | `roles` | Permission roles |
+| `Page` | `pages` | Content pages |
+| `PageRevision` | `page_revisions` | Content history |
+| `Setting` | `settings` | Key-value site settings |
+
+### Migrations
+
+Uses Alembic via CLI wrapper:
+
+```bash
+skrift db upgrade head                    # Apply all
+skrift db downgrade -1                    # Rollback one
+skrift db revision -m "add table" --autogenerate  # Generate
+```
+
+Migration files in: `skrift/migrations/versions/`
+
+## Authentication & Authorization
+
+### OAuth Flow
+
+```
+/auth/{provider}/login → Provider → /auth/{provider}/callback → Session created
+```
+
+Providers configured in `app.yaml` under `auth.providers`.
+
+### Session Management
+
+Client-side encrypted cookies (Litestar's CookieBackendConfig):
+- 7-day expiry
+- HttpOnly, Secure (in production), SameSite=Lax
+
+### Role-Based Authorization
+
+**Built-in Roles:**
+- `admin`: Full access (`administrator` permission bypasses all checks)
+- `editor`: Can manage pages
+- `author`: Can view drafts
+- `moderator`: Can moderate content
+
+**Guard System:**
+
+```python
+from skrift.auth import auth_guard, Permission, Role
+
+# Basic auth required
+guards = [auth_guard]
+
+# With permission
+guards = [auth_guard, Permission("manage-pages")]
+
+# With role
+guards = [auth_guard, Role("editor")]
+
+# Combinations
+guards = [auth_guard, Permission("edit") & Permission("publish")]  # AND
+guards = [auth_guard, Role("admin") | Role("editor")]              # OR
+```
+
+**Custom Roles:**
+
+```python
+from skrift.auth import register_role
+
+register_role(
+    "support",
+    "view-tickets",
+    "respond-tickets",
+    display_name="Support Agent",
+)
+```
+
+## Template System
+
+### Resolution Order
+
+The `Template` class resolves templates from most to least specific:
+
+```python
+Template("page", "services", "web")
+# Tries: page-services-web.html → page-services.html → page.html
+```
+
+### Search Directories
+
+1. `./templates/` (project root - user overrides)
+2. `skrift/templates/` (package - defaults)
+
+### Template Globals
+
+Available in all templates:
+- `now()` - Current datetime
+- `site_name()` - From settings
+- `site_tagline()` - From settings
+- `site_copyright_holder()` - From settings
+- `site_copyright_start_year()` - From settings
+
+### Template Filters
+
+- `markdown` - Render markdown to HTML
+
+## Hook/Filter System
+
+### Concept
+
+WordPress-inspired extensibility:
+- **Actions**: Side effects, no return value
+- **Filters**: Transform and return values
+
+### Registration Methods
+
+```python
+# Decorator (auto-registers on import)
+@action("hook_name", priority=10)
+async def my_action(arg1, arg2):
+    ...
+
+@filter("hook_name", priority=10)
+async def my_filter(value, arg1) -> Any:
+    return modified_value
+
+# Direct registration
+hooks.add_action("hook_name", callback, priority=10)
+hooks.add_filter("hook_name", callback, priority=10)
+```
+
+### Triggering
+
+```python
+# Actions (fire and forget)
+await hooks.do_action("hook_name", arg1, arg2)
+
+# Filters (chain transforms)
+result = await hooks.apply_filters("hook_name", initial_value, arg1)
+```
+
+### Priority
+
+Lower numbers execute first. Default is 10.
+
+### Built-in Hook Points
+
+**Actions:**
+- `before_page_save(page, is_new)` - Before saving
+- `after_page_save(page, is_new)` - After saving
+- `before_page_delete(page)` - Before deletion
+- `after_page_delete(page)` - After deletion
+
+**Filters:**
+- `page_seo_meta(meta, page)` - Modify SEO metadata
+- `page_og_meta(meta, page)` - Modify OpenGraph metadata
+- `sitemap_urls(urls)` - Modify sitemap URLs
+- `sitemap_page(page_data, page)` - Modify sitemap entry
+- `robots_txt(content)` - Modify robots.txt
+- `template_context(context)` - Modify template context
+
+## Static Files
+
+Served from `/static/` with same priority as templates:
+1. `./static/` (project root - user overrides)
+2. `skrift/static/` (package - defaults)
+
+## Error Handling
+
+Custom exception handlers in `skrift/lib/exceptions.py`:
+- `HTTPException` → `http_exception_handler`
+- `Exception` → `internal_server_error_handler`
+
+Error templates:
+- `error.html` - Generic error
+- `error-404.html` - Not found
+- `error-500.html` - Server error

skrift/claude_skill/patterns.md

@@ -0,0 +1,552 @@
+# Skrift Code Patterns
+
+## Controller Patterns
+
+### Basic Controller
+
+```python
+from pathlib import Path
+from litestar import Controller, get, post
+from litestar.response import Template as TemplateResponse
+from sqlalchemy.ext.asyncio import AsyncSession
+
+TEMPLATE_DIR = Path(__file__).parent.parent / "templates"
+
+class ItemController(Controller):
+    path = "/items"
+
+    @get("/")
+    async def list_items(self, db_session: AsyncSession) -> TemplateResponse:
+        items = await item_service.list_items(db_session)
+        return TemplateResponse("items/list.html", context={"items": items})
+
+    @get("/{item_id:uuid}")
+    async def get_item(
+        self, db_session: AsyncSession, item_id: UUID
+    ) -> TemplateResponse:
+        item = await item_service.get_by_id(db_session, item_id)
+        if not item:
+            raise NotFoundException(f"Item {item_id} not found")
+        return TemplateResponse("items/detail.html", context={"item": item})
+```
+
+### Protected Controller with Guards
+
+```python
+from skrift.auth import auth_guard, Permission, Role
+
+class AdminController(Controller):
+    path = "/admin"
+    guards = [auth_guard, Role("admin")]
+
+    @get("/")
+    async def dashboard(self) -> TemplateResponse:
+        return TemplateResponse("admin/dashboard.html")
+
+    @get("/users")
+    async def list_users(self, db_session: AsyncSession) -> TemplateResponse:
+        # Additional permission check beyond role
+        ...
+```
+
+### Controller with Request/Session Access
+
+```python
+from litestar import Request
+
+class AuthController(Controller):
+    path = "/auth"
+
+    @get("/profile")
+    async def profile(
+        self, request: Request, db_session: AsyncSession
+    ) -> TemplateResponse:
+        user_id = request.session.get("user_id")
+        if not user_id:
+            raise NotAuthorizedException()
+
+        user = await user_service.get_by_id(db_session, UUID(user_id))
+        return TemplateResponse("auth/profile.html", context={"user": user})
+
+    @post("/logout")
+    async def logout(self, request: Request) -> Redirect:
+        request.session.clear()
+        return Redirect("/")
+```
+
+### Controller with Flash Messages
+
+```python
+@post("/items")
+async def create_item(
+    self, request: Request, db_session: AsyncSession, data: ItemCreate
+) -> Redirect:
+    await item_service.create(db_session, data)
+    request.session["flash"] = {"type": "success", "message": "Item created!"}
+    return Redirect("/items")
+
+@get("/items")
+async def list_items(self, request: Request, db_session: AsyncSession):
+    flash = request.session.pop("flash", None)  # Get and remove
+    items = await item_service.list_items(db_session)
+    return TemplateResponse("items/list.html", context={"items": items, "flash": flash})
+```
+
+## Database Model Patterns
+
+### Basic Model
+
+```python
+from sqlalchemy import String, Text, Boolean
+from sqlalchemy.orm import Mapped, mapped_column
+from skrift.db.base import Base
+
+class Article(Base):
+    __tablename__ = "articles"
+
+    title: Mapped[str] = mapped_column(String(255), nullable=False)
+    content: Mapped[str] = mapped_column(Text, nullable=False, default="")
+    is_published: Mapped[bool] = mapped_column(Boolean, default=False)
+```
+
+### Model with Relationships
+
+```python
+from sqlalchemy import ForeignKey
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from uuid import UUID
+
+class Comment(Base):
+    __tablename__ = "comments"
+
+    # Foreign key
+    article_id: Mapped[UUID] = mapped_column(
+        ForeignKey("articles.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+
+    # Relationship
+    article: Mapped["Article"] = relationship("Article", back_populates="comments")
+
+    content: Mapped[str] = mapped_column(Text, nullable=False)
+
+# In Article model:
+class Article(Base):
+    # ...
+    comments: Mapped[list["Comment"]] = relationship(
+        "Comment",
+        back_populates="article",
+        cascade="all, delete-orphan",
+        order_by="desc(Comment.created_at)",
+    )
+```
+
+### Model with Optional Fields
+
+```python
+from datetime import datetime
+
+class Event(Base):
+    __tablename__ = "events"
+
+    title: Mapped[str] = mapped_column(String(255), nullable=False)
+    # Optional fields use | None
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    starts_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+```
+
+### Model with Indexes
+
+```python
+class LogEntry(Base):
+    __tablename__ = "log_entries"
+
+    level: Mapped[str] = mapped_column(String(20), nullable=False, index=True)
+    message: Mapped[str] = mapped_column(Text, nullable=False)
+    # Composite index
+    __table_args__ = (
+        Index("ix_log_entries_level_created", "level", "created_at"),
+    )
+```
+
+## Service Layer Patterns
+
+### Basic CRUD Service
+
+```python
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from uuid import UUID
+
+async def list_items(
+    db_session: AsyncSession,
+    limit: int | None = None,
+    offset: int = 0,
+) -> list[Item]:
+    query = select(Item).order_by(Item.created_at.desc())
+    if offset:
+        query = query.offset(offset)
+    if limit:
+        query = query.limit(limit)
+    result = await db_session.execute(query)
+    return list(result.scalars().all())
+
+async def get_by_id(db_session: AsyncSession, item_id: UUID) -> Item | None:
+    result = await db_session.execute(select(Item).where(Item.id == item_id))
+    return result.scalar_one_or_none()
+
+async def create(db_session: AsyncSession, name: str, **kwargs) -> Item:
+    item = Item(name=name, **kwargs)
+    db_session.add(item)
+    await db_session.commit()
+    await db_session.refresh(item)
+    return item
+
+async def update(
+    db_session: AsyncSession,
+    item_id: UUID,
+    **updates,
+) -> Item | None:
+    item = await get_by_id(db_session, item_id)
+    if not item:
+        return None
+
+    for key, value in updates.items():
+        if value is not None:
+            setattr(item, key, value)
+
+    await db_session.commit()
+    await db_session.refresh(item)
+    return item
+
+async def delete(db_session: AsyncSession, item_id: UUID) -> bool:
+    item = await get_by_id(db_session, item_id)
+    if not item:
+        return False
+    await db_session.delete(item)
+    await db_session.commit()
+    return True
+```
+
+### Service with Filtering
+
+```python
+from sqlalchemy import select, and_, or_
+from datetime import datetime, UTC
+
+async def list_published_articles(
+    db_session: AsyncSession,
+    category: str | None = None,
+    search: str | None = None,
+) -> list[Article]:
+    query = select(Article).where(Article.is_published == True)
+
+    filters = []
+    if category:
+        filters.append(Article.category == category)
+    if search:
+        filters.append(
+            or_(
+                Article.title.ilike(f"%{search}%"),
+                Article.content.ilike(f"%{search}%"),
+            )
+        )
+
+    if filters:
+        query = query.where(and_(*filters))
+
+    query = query.order_by(Article.published_at.desc())
+    result = await db_session.execute(query)
+    return list(result.scalars().all())
+```
+
+### Service with Hooks
+
+```python
+from skrift.lib.hooks import hooks
+
+BEFORE_ITEM_SAVE = "before_item_save"
+AFTER_ITEM_SAVE = "after_item_save"
+
+async def create(db_session: AsyncSession, name: str) -> Item:
+    item = Item(name=name)
+
+    await hooks.do_action(BEFORE_ITEM_SAVE, item, is_new=True)
+
+    db_session.add(item)
+    await db_session.commit()
+    await db_session.refresh(item)
+
+    await hooks.do_action(AFTER_ITEM_SAVE, item, is_new=True)
+
+    return item
+```
+
+## Hook/Filter Patterns
+
+### Action Hook
+
+```python
+from skrift.lib.hooks import action
+
+@action("after_page_save", priority=10)
+async def invalidate_cache(page, is_new: bool):
+    """Clear cache when page is saved."""
+    cache.delete(f"page:{page.slug}")
+
+@action("after_user_register", priority=5)
+async def send_welcome_email(user):
+    """Send welcome email to new users."""
+    await email_service.send_welcome(user.email)
+```
+
+### Filter Hook
+
+```python
+from skrift.lib.hooks import filter
+
+@filter("page_seo_meta", priority=10)
+async def add_default_author(meta: dict, page) -> dict:
+    """Add default author to SEO meta."""
+    if "author" not in meta:
+        meta["author"] = "Site Author"
+    return meta
+
+@filter("template_context", priority=20)
+async def add_global_vars(context: dict) -> dict:
+    """Add global variables to all templates."""
+    context["current_year"] = datetime.now().year
+    context["version"] = "1.0.0"
+    return context
+```
+
+### Custom Hook Points
+
+```python
+# Define hook constants
+MY_BEFORE_SAVE = "my_before_save"
+MY_AFTER_SAVE = "my_after_save"
+MY_DATA_FILTER = "my_data_filter"
+
+# Trigger in service
+async def save_thing(db_session: AsyncSession, data: dict) -> Thing:
+    # Apply filters to data
+    data = await hooks.apply_filters(MY_DATA_FILTER, data)
+
+    thing = Thing(**data)
+    await hooks.do_action(MY_BEFORE_SAVE, thing)
+
+    db_session.add(thing)
+    await db_session.commit()
+
+    await hooks.do_action(MY_AFTER_SAVE, thing)
+    return thing
+```
+
+## Template Patterns
+
+### Using Template Class
+
+```python
+from skrift.lib.template import Template
+from pathlib import Path
+
+TEMPLATE_DIR = Path(__file__).parent.parent / "templates"
+
+@get("/{slug:str}")
+async def view_item(self, db_session: AsyncSession, slug: str) -> TemplateResponse:
+    item = await item_service.get_by_slug(db_session, slug)
+
+    # Tries: item-{slug}.html -> item.html
+    template = Template("item", slug, context={"item": item})
+    return template.render(TEMPLATE_DIR)
+```
+
+### Template with SEO Context
+
+```python
+from skrift.lib.seo import get_page_seo_meta, get_page_og_meta
+
+@get("/{slug:path}")
+async def view_page(self, request: Request, db_session: AsyncSession, slug: str):
+    page = await page_service.get_by_slug(db_session, slug)
+
+    site_name = get_cached_site_name()
+    base_url = str(request.base_url).rstrip("/")
+
+    seo_meta = await get_page_seo_meta(page, site_name, base_url)
+    og_meta = await get_page_og_meta(page, site_name, base_url)
+
+    return TemplateResponse("page.html", context={
+        "page": page,
+        "seo_meta": seo_meta,
+        "og_meta": og_meta,
+    })
+```
+
+## Middleware Patterns
+
+### Simple Middleware
+
+```python
+# myapp/middleware.py
+from litestar.middleware import AbstractMiddleware
+from litestar.types import ASGIApp, Receive, Scope, Send
+
+class LoggingMiddleware(AbstractMiddleware):
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] == "http":
+            print(f"Request: {scope['method']} {scope['path']}")
+        await self.app(scope, receive, send)
+
+def create_logging_middleware(app: ASGIApp) -> ASGIApp:
+    return LoggingMiddleware(app=app)
+```
+
+Register in app.yaml:
+```yaml
+middleware:
+  - myapp.middleware:create_logging_middleware
+```
+
+### Middleware with Configuration
+
+```python
+from litestar.middleware import DefineMiddleware
+
+class RateLimitMiddleware(AbstractMiddleware):
+    def __init__(self, app: ASGIApp, requests_per_minute: int = 60):
+        super().__init__(app)
+        self.limit = requests_per_minute
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        # Rate limiting logic...
+        await self.app(scope, receive, send)
+
+def create_rate_limit_middleware(app: ASGIApp, requests_per_minute: int = 60) -> ASGIApp:
+    return RateLimitMiddleware(app, requests_per_minute)
+```
+
+Register with kwargs:
+```yaml
+middleware:
+  - factory: myapp.middleware:create_rate_limit_middleware
+    kwargs:
+      requests_per_minute: 100
+```
+
+## Authorization Patterns
+
+### Permission-Based Access
+
+```python
+from skrift.auth import auth_guard, Permission
+
+class ArticleController(Controller):
+    path = "/articles"
+    guards = [auth_guard]  # All routes require auth
+
+    @get("/")
+    async def list_articles(self, db_session: AsyncSession):
+        # Anyone authenticated can list
+        ...
+
+    @post("/", guards=[Permission("create-articles")])
+    async def create_article(self, db_session: AsyncSession, data: ArticleCreate):
+        # Only users with create-articles permission
+        ...
+
+    @delete("/{id:uuid}", guards=[Permission("delete-articles")])
+    async def delete_article(self, db_session: AsyncSession, id: UUID):
+        # Only users with delete-articles permission
+        ...
+```
+
+### Custom Role Registration
+
+```python
+# In your app's __init__.py or startup module
+from skrift.auth import register_role
+
+# Register before database sync (app startup)
+register_role(
+    "contributor",
+    "create-articles",
+    "edit-own-articles",
+    display_name="Contributor",
+    description="Can create and edit their own articles",
+)
+
+register_role(
+    "reviewer",
+    "view-drafts",
+    "approve-articles",
+    display_name="Reviewer",
+    description="Can review and approve articles",
+)
+```
+
+## Testing Patterns
+
+### Controller Test
+
+```python
+import pytest
+from litestar.testing import TestClient
+
+@pytest.fixture
+def client(app):
+    return TestClient(app)
+
+async def test_list_items(client, db_session):
+    # Create test data
+    item = await item_service.create(db_session, name="Test")
+
+    response = client.get("/items")
+    assert response.status_code == 200
+    assert "Test" in response.text
+```
+
+### Service Test
+
+```python
+import pytest
+
+async def test_create_item(db_session):
+    item = await item_service.create(db_session, name="Test Item")
+
+    assert item.id is not None
+    assert item.name == "Test Item"
+
+async def test_list_items_filters(db_session):
+    await item_service.create(db_session, name="Item A", published=True)
+    await item_service.create(db_session, name="Item B", published=False)
+
+    published = await item_service.list_items(db_session, published_only=True)
+
+    assert len(published) == 1
+    assert published[0].name == "Item A"
+```
+
+### Hook Test
+
+```python
+from skrift.lib.hooks import hooks
+
+async def test_hook_called(db_session):
+    called_with = []
+
+    async def track_save(page, is_new):
+        called_with.append((page.title, is_new))
+
+    hooks.add_action("after_page_save", track_save)
+
+    try:
+        await page_service.create(db_session, slug="test", title="Test")
+
+        assert len(called_with) == 1
+        assert called_with[0] == ("Test", True)
+    finally:
+        hooks.remove_action("after_page_save", track_save)
+```

skrift/cli.py

@@ -139,5 +139,52 @@ def db(ctx):
     sys.exit(alembic_main(alembic_argv))
 
 
+@cli.command("init-claude")
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Overwrite existing skill files",
+)
+def init_claude(force):
+    """Set up Claude Code skill for Skrift development.
+
+    Copies the Skrift skill files to .claude/skills/skrift/ in the current
+    directory, enabling Claude Code to understand Skrift conventions.
+
+    \b
+    Creates:
+        .claude/skills/skrift/SKILL.md      - Main skill with dynamic context
+        .claude/skills/skrift/architecture.md - System architecture docs
+        .claude/skills/skrift/patterns.md   - Code patterns and examples
+    """
+    import importlib.resources
+
+    skill_dir = Path.cwd() / ".claude" / "skills" / "skrift"
+
+    # Check if skill already exists
+    if skill_dir.exists() and not force:
+        click.echo(f"Skill directory already exists: {skill_dir}", err=True)
+        click.echo("Use --force to overwrite existing files.", err=True)
+        sys.exit(1)
+
+    # Create directory
+    skill_dir.mkdir(parents=True, exist_ok=True)
+
+    # Copy skill files from package
+    skill_files = ["SKILL.md", "architecture.md", "patterns.md"]
+    package_files = importlib.resources.files("skrift.claude_skill")
+
+    for filename in skill_files:
+        source = package_files.joinpath(filename)
+        dest = skill_dir / filename
+
+        content = source.read_text()
+        dest.write_text(content)
+        click.echo(f"Created {dest.relative_to(Path.cwd())}")
+
+    click.echo()
+    click.echo("Claude Code skill installed. Use /skrift to activate.")
+
+
 if __name__ == "__main__":
     cli()

skrift/config.py

@@ -110,6 +110,7 @@ class DatabaseConfig(BaseModel):
     pool_size: int = 5
     pool_overflow: int = 10
     pool_timeout: int = 30
+    pool_pre_ping: bool = True  # Validate connections before use
     echo: bool = False
 
 

skrift/db/session.py

@@ -0,0 +1,90 @@
+"""Safe SQLAlchemy async session provider with CancelledError handling.
+
+This module provides a custom session configuration that properly handles
+connection cleanup when HTTP requests are cancelled (client disconnect, timeout).
+Without this, CancelledError can prevent session cleanup, leading to connection
+pool leaks.
+"""
+
+import asyncio
+from collections.abc import AsyncGenerator
+from typing import TYPE_CHECKING, Callable, cast
+
+from advanced_alchemy._listeners import set_async_context
+from advanced_alchemy.extensions.litestar import SQLAlchemyAsyncConfig
+from advanced_alchemy.extensions.litestar._utils import (
+    delete_aa_scope_state,
+    get_aa_scope_state,
+    set_aa_scope_state,
+)
+from sqlalchemy.ext.asyncio import AsyncSession
+
+if TYPE_CHECKING:
+    from litestar.datastructures import State
+    from litestar.types import Scope
+
+
+class SafeSQLAlchemyAsyncConfig(SQLAlchemyAsyncConfig):
+    """SQLAlchemy async config with safe session cleanup on request cancellation.
+
+    This subclass overrides `provide_session` to use an async generator that
+    catches CancelledError and ensures sessions are properly closed, preventing
+    connection pool leaks when HTTP requests are cancelled.
+
+    The standard advanced_alchemy session management relies on ASGI events
+    (http.response.body, http.disconnect) to trigger cleanup via before_send_handler.
+    However, CancelledError can prevent these events from firing, leaving sessions
+    in an unclosed state.
+
+    By using an async generator, Litestar's dependency injection system ensures
+    cleanup runs even when CancelledError is raised.
+    """
+
+    async def provide_session(
+        self,
+        state: "State",
+        scope: "Scope",
+    ) -> AsyncGenerator[AsyncSession, None]:
+        """Provide a database session with proper cleanup on cancellation.
+
+        This async generator wraps session creation to ensure that
+        CancelledError (raised when an HTTP request is cancelled) doesn't
+        prevent session cleanup, which would leak connections.
+
+        Args:
+            state: The application state
+            scope: The ASGI scope
+
+        Yields:
+            AsyncSession: The database session
+        """
+        # Check if we already have a session in scope
+        session = cast(
+            "AsyncSession | None",
+            get_aa_scope_state(scope, self.session_scope_key),
+        )
+
+        if session is None:
+            # Create a new session
+            session_maker = cast(
+                "Callable[[], AsyncSession]",
+                state[self.session_maker_app_state_key],
+            )
+            session = session_maker()
+            # Store in scope for reuse within this request
+            set_aa_scope_state(scope, self.session_scope_key, session)
+
+        set_async_context(True)
+
+        try:
+            yield session
+        except asyncio.CancelledError:
+            # Request was cancelled - ensure we clean up the session
+            # This prevents connection pool leaks
+            await session.close()
+            # Remove the session from scope state to prevent double-close
+            delete_aa_scope_state(scope, self.session_scope_key)
+            raise
+
+
+__all__ = ["SafeSQLAlchemyAsyncConfig"]

skrift/setup/config_writer.py

@@ -21,6 +21,7 @@ DEFAULT_CONFIG = {
         "pool_size": 5,
         "pool_overflow": 10,
         "pool_timeout": 30,
+        "pool_pre_ping": True,
         "echo": False,
     },
     "auth": {

skrift/setup/state.py

@@ -172,9 +172,9 @@ def run_migrations_if_needed() -> tuple[bool, str | None]:
         return True, None
 
     try:
-        # Try skrift-db first
+        # Try skrift db first (the correct command)
         result = subprocess.run(
-            ["skrift-db", "upgrade", "head"],
+            ["skrift", "db", "upgrade", "head"],
             capture_output=True,
             text=True,
             cwd=Path.cwd(),
@@ -183,7 +183,7 @@ def run_migrations_if_needed() -> tuple[bool, str | None]:
         if result.returncode == 0:
             _migrations_run = True
             return True, None
-        # If skrift-db fails, try alembic directly
+        # If skrift db fails, try alembic directly
     except (subprocess.TimeoutExpired, FileNotFoundError):
         pass
 
@@ -202,7 +202,7 @@ def run_migrations_if_needed() -> tuple[bool, str | None]:
     except subprocess.TimeoutExpired:
         return False, "Migration timed out"
     except FileNotFoundError:
-        return False, "Neither skrift-db nor alembic found"
+        return False, "skrift db command not found"
     except Exception as e:
         return False, str(e)
 

{skrift-0.1.0a15.dist-info → skrift-0.1.0a17.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skrift
-Version: 0.1.0a15
+Version: 0.1.0a17
 Summary: A lightweight async Python CMS for crafting modern websites
 Requires-Python: >=3.13
 Requires-Dist: advanced-alchemy>=0.26.0

{skrift-0.1.0a15.dist-info → skrift-0.1.0a17.dist-info}/RECORD

@@ -1,9 +1,9 @@
 skrift/__init__.py,sha256=eXE5PFVkJpH5XsV_ZlrTIeFPUPrmcHYAj4GpRS3R5PY,29
 skrift/__main__.py,sha256=wt6JZL9nBhKU36vdyurhOEtWy7w3C9zohyy24PLcKho,164
 skrift/alembic.ini,sha256=mYguI6CbMCTyfHctsGiTyf9Z5gv21FdeI3qtfgOHO3A,1815
-skrift/asgi.py,sha256=7uPvgsGMpZJyPOjIGxL9QlXTRLWh9uRAhcg-RdBS1c8,23355
-skrift/cli.py,sha256=aT-7pXvOuuZC-Eypx1h-xCiqaBKhIFjSqd5Ky_dHna0,4214
-skrift/config.py,sha256=ZDOrYgp6gC6fE1nEZgrAOouoykhRo2NZo5U1-WLdDSc,7862
+skrift/asgi.py,sha256=re_DzFiLzFdSiY3TAj_UGuVedkZTIs8jx1rHb6vPvkM,23509
+skrift/cli.py,sha256=-K-uO1r8y5r8wsRGygZFyaH1DsY1s9L0XViScPBnt9s,5744
+skrift/config.py,sha256=9qDy9GhGbUZWinsagfPPkeAWsapHoZmqmeYFR3CEdxQ,7928
 skrift/admin/__init__.py,sha256=x81Cj_ilVmv6slaMl16HHyT_AgrnLxKEWkS0RPa4V9s,289
 skrift/admin/controller.py,sha256=gSprerjhxqxaH2lHm8vbLuz-jslN553FpbKF7jwEm9Y,19607
 skrift/admin/navigation.py,sha256=VwttFoIUIJy5rONKIkJd5w4CNkUpeK22_OfLGHecN34,3382
@@ -24,12 +24,17 @@ skrift/auth/__init__.py,sha256=uHMqty3dgDSYlReVT96WhygzH6qNAWSVDWoxumzxmsA,1155
 skrift/auth/guards.py,sha256=QePajHsGnJ4R_hlhzblr5IoAgZcY5jzeZ64bJwDL9hM,4451
 skrift/auth/roles.py,sha256=Cvwv8v7Li6CJHhucTuzxRjaNmS530F9sbbQlCPRqhm4,3291
 skrift/auth/services.py,sha256=h6GTXdN5UMRYglnaFz4asMoutVkSSAyL3_Vt56N26pA,5441
+skrift/claude_skill/SKILL.md,sha256=cOEBAsUSw224op9XagsRGpv1rMBswD23ZhfsPgETLOs,5972
+skrift/claude_skill/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+skrift/claude_skill/architecture.md,sha256=jKtegv3FsWmeWsW0bmRr6tQMVlbFt-y_wSTRVn90qtc,8508
+skrift/claude_skill/patterns.md,sha256=YjbBgozeUpDYx44PazDXY8r6bTWddvUiZ7ub6Ol7qtc,14415
 skrift/controllers/__init__.py,sha256=bVr0tsSGz7jBi002Lqd1AA1FQd7ZA_IagsqTKpiHiK0,147
 skrift/controllers/auth.py,sha256=ohYjBJiRa5RDQKUQjL3nR6lzm4uUZcfIgnF2G-QY5o8,21905
 skrift/controllers/sitemap.py,sha256=Yfz2ElHrkZVMhAN5ixriU5RwEFJ713rS0Uezj90Bfts,3814
 skrift/controllers/web.py,sha256=J-kbmzwJcKfiBvNbF8yR7GHGo0jhvWzY77YstJi_pcI,2968
 skrift/db/__init__.py,sha256=uSghyDFT2K4SFiEqUzdjCGzWpS-Oy6Sd1FUappau-v0,52
 skrift/db/base.py,sha256=QJplFj9235kZdScASEpvyNHln6YW2hqbHwJEYZ3OSsc,173
+skrift/db/session.py,sha256=b2E4VeSIscPTEDBWQrketJbmUqLdWqdhqhUv7cojUkY,3237
 skrift/db/models/__init__.py,sha256=DtgYPLs8rTLNFmZ0-HzD_8uhvaGRtayZCrxpMhAo88U,413
 skrift/db/models/oauth_account.py,sha256=fzmApdtrRYeEWLl35Y7H0YtF7CWjzrpG-lknBOuYRc8,1840
 skrift/db/models/page.py,sha256=pYMWBmQ7FfDiFcyBU3xV4kbpWboimZw5TZtVDOcr73o,2068
@@ -50,11 +55,11 @@ skrift/lib/markdown.py,sha256=fPLUIAsmFXC64Os2RngQG7P2xRKBd1RO8fh7b5_gV1U,950
 skrift/lib/seo.py,sha256=3fAfXn_7Jpq_OhINpcbQznixLcJTbaD-I86_Je2SFoo,2512
 skrift/lib/template.py,sha256=4_urkRfvth75yNeQ5TyGTHvkvs3vVef7TcwZx0k285k,4226
 skrift/setup/__init__.py,sha256=3VjFPMES5y0M5cQ9R4C1xazqiEPEDqTPjX9-3rBMXnA,478
-skrift/setup/config_writer.py,sha256=YFH3FVjXN7Rum2fzGVPAQRkjdc9b0bHECDqMKYiEkhg,6347
+skrift/setup/config_writer.py,sha256=2yXwJ5TRcRnQAiRL2i0cyJ3KYnJJ-QUNUsCuSOCR7M0,6378
 skrift/setup/controller.py,sha256=v0Ey8T7ptJ5A3vOqQ1TUAXH1bQwA0288J5uyUWMihsw,34250
 skrift/setup/middleware.py,sha256=Nai8ZG2vHldngmAhq7kWzAwKRNcP5tHKhJHa5dCh404,2941
 skrift/setup/providers.py,sha256=0BFKB6168NcmtXxFF6ofHgEDMQD2FbXkexsqrARVtDI,7967
-skrift/setup/state.py,sha256=RMe9LtIjzDoOm9u-Nk5-KAnr_JBiQIjWDpTP9E30ezc,9304
+skrift/setup/state.py,sha256=3RJzdtRY-ZtTWsb9aLTw43lEvgnanXMAEhK7QQmaAU0,9321
 skrift/static/css/style.css,sha256=6in8KjmwythfQV9pGt-uSCJCoHG1OijrdDOOad7oYBk,22978
 skrift/templates/base.html,sha256=s6gylukPyBvb9StgNz8MRZr4h3QT3C8GTMiwOu23nC0,4421
 skrift/templates/error-404.html,sha256=sJrDaF3Or3Nyki8mxo3wBxLLzgy4wkB9p9wdS8pRA6k,409
@@ -80,7 +85,7 @@ skrift/templates/setup/configuring.html,sha256=2KHW9h2BrJgL_kO5IizbAYs4pnFLyRf76
 skrift/templates/setup/database.html,sha256=gU4-315-QraHa2Eq4Fh3b55QpOM2CkJzh27_Yz13frA,5495
 skrift/templates/setup/restart.html,sha256=GHg31F_e2uLFhWUzJoalk0Y0oYLqsFWyZXWKX3mblbY,1355
 skrift/templates/setup/site.html,sha256=PSOH-q1-ZBl47iSW9-Ad6lEfJn_fzdGD3Pk4vb3xgK4,1680
-skrift-0.1.0a15.dist-info/METADATA,sha256=6_eCcfYQ2K5uH_acqd3Q3FmEby0a1Yx710xIiEBa3rs,7267
-skrift-0.1.0a15.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-skrift-0.1.0a15.dist-info/entry_points.txt,sha256=uquZ5Mumqr0xwYTpTcNiJtFSITGfF6_QCCy2DZJSZig,42
-skrift-0.1.0a15.dist-info/RECORD,,
+skrift-0.1.0a17.dist-info/METADATA,sha256=TElTCDYHVD_CoTOzfB9htMyL2UfBHX2qYs28IIp3zt4,7267
+skrift-0.1.0a17.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+skrift-0.1.0a17.dist-info/entry_points.txt,sha256=uquZ5Mumqr0xwYTpTcNiJtFSITGfF6_QCCy2DZJSZig,42
+skrift-0.1.0a17.dist-info/RECORD,,