skrift 0.1.0a15__tar.gz → 0.1.0a17__tar.gz

{skrift-0.1.0a15 → skrift-0.1.0a17}/PKG-INFO

@@ -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 → skrift-0.1.0a17}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "skrift"
-version = "0.1.0a15"
+version = "0.1.0a17"
 description = "A lightweight async Python CMS for crafting modern websites"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -47,6 +47,7 @@ include = [
     "skrift/static/**/*",
     "skrift/alembic/**/*",
     "skrift/alembic.ini",
+    "skrift/claude_skill/*.md",
 ]
 exclude = [
     "**/__pycache__",

{skrift-0.1.0a15 → skrift-0.1.0a17}/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-0.1.0a17/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-0.1.0a17/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