skrift 0.1.0a14__py3-none-any.whl → 0.1.0a16__py3-none-any.whl

skrift/admin/controller.py

@@ -26,8 +26,9 @@ from skrift.auth.roles import ROLE_DEFINITIONS
 from skrift.admin.navigation import build_admin_nav, ADMIN_NAV_TAG
 from skrift.db.models.user import User
 from skrift.db.models import Page
-from skrift.db.services import page_service
+from skrift.db.services import page_service, revision_service
 from skrift.db.services import setting_service
+from skrift.lib.flash import flash_success, flash_error, flash_info, get_flash_messages
 
 
 class AdminController(Controller):
@@ -74,10 +75,10 @@ class AdminController(Controller):
         if not ctx["admin_nav"]:
             raise NotAuthorizedException("No admin pages accessible")
 
-        flash = request.session.pop("flash", None)
+        flash_messages = get_flash_messages(request)
         return TemplateResponse(
             "admin/admin.html",
-            context={"flash": flash, **ctx},
+            context={"flash_messages": flash_messages, **ctx},
         )
 
     @get(
@@ -100,10 +101,10 @@ class AdminController(Controller):
         )
         users = list(result.scalars().all())
 
-        flash = request.session.pop("flash", None)
+        flash_messages = get_flash_messages(request)
         return TemplateResponse(
             "admin/users/list.html",
-            context={"flash": flash, "users": users, **ctx},
+            context={"flash_messages": flash_messages, "users": users, **ctx},
         )
 
     @get(
@@ -129,11 +130,11 @@ class AdminController(Controller):
         # Get user's current role names
         current_roles = {role.name for role in target_user.roles}
 
-        flash = request.session.pop("flash", None)
+        flash_messages = get_flash_messages(request)
         return TemplateResponse(
             "admin/users/roles.html",
             context={
-                "flash": flash,
+                "flash_messages": flash_messages,
                 "target_user": target_user,
                 "current_roles": current_roles,
                 "available_roles": ROLE_DEFINITIONS,
@@ -200,18 +201,18 @@ class AdminController(Controller):
         """List all pages with management actions."""
         ctx = await self._get_admin_context(request, db_session)
 
-        # Get all pages with their authors
+        # Get all pages with their authors, ordered by display order then created
         result = await db_session.execute(
             select(Page)
             .options(selectinload(Page.user))
-            .order_by(Page.created_at.desc())
+            .order_by(Page.order.asc(), Page.created_at.desc())
         )
         pages = list(result.scalars().all())
 
-        flash = request.session.pop("flash", None)
+        flash_messages = get_flash_messages(request)
         return TemplateResponse(
             "admin/pages/list.html",
-            context={"flash": flash, "pages": pages, **ctx},
+            context={"flash_messages": flash_messages, "pages": pages, **ctx},
         )
 
     @get(
@@ -223,10 +224,10 @@ class AdminController(Controller):
     ) -> TemplateResponse:
         """Show new page form."""
         ctx = await self._get_admin_context(request, db_session)
-        flash = request.session.pop("flash", None)
+        flash_messages = get_flash_messages(request)
         return TemplateResponse(
             "admin/pages/edit.html",
-            context={"flash": flash, "page": None, **ctx},
+            context={"flash_messages": flash_messages, "page": None, **ctx},
         )
 
     @post(
@@ -245,8 +246,20 @@ class AdminController(Controller):
         content = data.get("content", "").strip()
         is_published = data.get("is_published") == "on"
 
+        # New fields
+        order = int(data.get("order", 0) or 0)
+        publish_at_str = data.get("publish_at", "").strip()
+        publish_at = datetime.fromisoformat(publish_at_str) if publish_at_str else None
+
+        # SEO fields
+        meta_description = data.get("meta_description", "").strip() or None
+        og_title = data.get("og_title", "").strip() or None
+        og_description = data.get("og_description", "").strip() or None
+        og_image = data.get("og_image", "").strip() or None
+        meta_robots = data.get("meta_robots", "").strip() or None
+
         if not title or not slug:
-            request.session["flash"] = "Title and slug are required"
+            flash_error(request, "Title and slug are required")
             return Redirect(path="/admin/pages/new")
 
         published_at = datetime.now(UTC) if is_published else None
@@ -259,11 +272,18 @@ class AdminController(Controller):
                 content=content,
                 is_published=is_published,
                 published_at=published_at,
+                order=order,
+                publish_at=publish_at,
+                meta_description=meta_description,
+                og_title=og_title,
+                og_description=og_description,
+                og_image=og_image,
+                meta_robots=meta_robots,
             )
-            request.session["flash"] = f"Page '{title}' created successfully!"
+            flash_success(request, f"Page '{title}' created successfully!")
             return Redirect(path="/admin/pages")
         except Exception as e:
-            request.session["flash"] = f"Error creating page: {str(e)}"
+            flash_error(request, f"Error creating page: {str(e)}")
             return Redirect(path="/admin/pages/new")
 
     @get(
@@ -278,13 +298,13 @@ class AdminController(Controller):
 
         page = await page_service.get_page_by_id(db_session, page_id)
         if not page:
-            request.session["flash"] = "Page not found"
+            flash_error(request, "Page not found")
             return Redirect(path="/admin/pages")
 
-        flash = request.session.pop("flash", None)
+        flash_messages = get_flash_messages(request)
         return TemplateResponse(
             "admin/pages/edit.html",
-            context={"flash": flash, "page": page, **ctx},
+            context={"flash_messages": flash_messages, "page": page, **ctx},
         )
 
     @post(
@@ -304,13 +324,25 @@ class AdminController(Controller):
         content = data.get("content", "").strip()
         is_published = data.get("is_published") == "on"
 
+        # New fields
+        order = int(data.get("order", 0) or 0)
+        publish_at_str = data.get("publish_at", "").strip()
+        publish_at = datetime.fromisoformat(publish_at_str) if publish_at_str else None
+
+        # SEO fields
+        meta_description = data.get("meta_description", "").strip() or None
+        og_title = data.get("og_title", "").strip() or None
+        og_description = data.get("og_description", "").strip() or None
+        og_image = data.get("og_image", "").strip() or None
+        meta_robots = data.get("meta_robots", "").strip() or None
+
         if not title or not slug:
-            request.session["flash"] = "Title and slug are required"
+            flash_error(request, "Title and slug are required")
             return Redirect(path=f"/admin/pages/{page_id}/edit")
 
         page = await page_service.get_page_by_id(db_session, page_id)
         if not page:
-            request.session["flash"] = "Page not found"
+            flash_error(request, "Page not found")
             return Redirect(path="/admin/pages")
 
         published_at = page.published_at
@@ -326,11 +358,18 @@ class AdminController(Controller):
                 content=content,
                 is_published=is_published,
                 published_at=published_at,
+                order=order,
+                publish_at=publish_at,
+                meta_description=meta_description,
+                og_title=og_title,
+                og_description=og_description,
+                og_image=og_image,
+                meta_robots=meta_robots,
             )
-            request.session["flash"] = f"Page '{title}' updated successfully!"
+            flash_success(request, f"Page '{title}' updated successfully!")
             return Redirect(path="/admin/pages")
         except Exception as e:
-            request.session["flash"] = f"Error updating page: {str(e)}"
+            flash_error(request, f"Error updating page: {str(e)}")
             return Redirect(path=f"/admin/pages/{page_id}/edit")
 
     @post(
@@ -397,6 +436,55 @@ class AdminController(Controller):
         request.session["flash"] = f"'{page_title}' has been deleted"
         return Redirect(path="/admin/pages")
 
+    @get(
+        "/pages/{page_id:uuid}/revisions",
+        guards=[auth_guard, Permission("manage-pages")],
+    )
+    async def list_revisions(
+        self, request: Request, db_session: AsyncSession, page_id: UUID
+    ) -> TemplateResponse:
+        """List revisions for a page."""
+        ctx = await self._get_admin_context(request, db_session)
+
+        page = await page_service.get_page_by_id(db_session, page_id)
+        if not page:
+            flash_error(request, "Page not found")
+            return Redirect(path="/admin/pages")
+
+        revisions = await revision_service.list_revisions(db_session, page_id)
+
+        flash_messages = get_flash_messages(request)
+        return TemplateResponse(
+            "admin/pages/revisions.html",
+            context={"flash_messages": flash_messages, "page": page, "revisions": revisions, **ctx},
+        )
+
+    @post(
+        "/pages/{page_id:uuid}/revisions/{revision_id:uuid}/restore",
+        guards=[auth_guard, Permission("manage-pages")],
+    )
+    async def restore_revision(
+        self, request: Request, db_session: AsyncSession, page_id: UUID, revision_id: UUID
+    ) -> Redirect:
+        """Restore a page to a previous revision."""
+        page = await page_service.get_page_by_id(db_session, page_id)
+        if not page:
+            flash_error(request, "Page not found")
+            return Redirect(path="/admin/pages")
+
+        revision = await revision_service.get_revision(db_session, revision_id)
+        if not revision or revision.page_id != page_id:
+            flash_error(request, "Revision not found")
+            return Redirect(path=f"/admin/pages/{page_id}/revisions")
+
+        user_id = request.session.get("user_id")
+        await revision_service.restore_revision(
+            db_session, page, revision, UUID(user_id) if user_id else None
+        )
+
+        flash_success(request, f"Page restored to revision #{revision.revision_number}")
+        return Redirect(path=f"/admin/pages/{page_id}/edit")
+
     @get(
         "/settings",
         tags=[ADMIN_NAV_TAG],
@@ -410,10 +498,10 @@ class AdminController(Controller):
         ctx = await self._get_admin_context(request, db_session)
         site_settings = await setting_service.get_site_settings(db_session)
 
-        flash = request.session.pop("flash", None)
+        flash_messages = get_flash_messages(request)
         return TemplateResponse(
             "admin/settings/site.html",
-            context={"flash": flash, "settings": site_settings, **ctx},
+            context={"flash_messages": flash_messages, "settings": site_settings, **ctx},
         )
 
     @post(
@@ -448,5 +536,5 @@ class AdminController(Controller):
         # Refresh the site settings cache
         await setting_service.load_site_settings_cache(db_session)
 
-        request.session["flash"] = "Site settings saved successfully"
+        flash_success(request, "Site settings saved successfully")
         return Redirect(path="/admin/settings")

skrift/alembic/versions/20260202_add_content_scheduling.py

@@ -0,0 +1,35 @@
+"""add content scheduling
+
+Revision ID: 5e6f7g8h9i0j
+Revises: 4d5e6f7g8h9i
+Create Date: 2026-02-02 10:02:00.000000
+
+This migration adds the publish_at column for scheduled publishing.
+When set, pages with is_published=True will only be visible after this datetime.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import advanced_alchemy.types
+
+
+# revision identifiers, used by Alembic.
+revision: str = '5e6f7g8h9i0j'
+down_revision: Union[str, None] = '4d5e6f7g8h9i'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table('pages') as batch_op:
+        batch_op.add_column(
+            sa.Column('publish_at', advanced_alchemy.types.datetime.DateTimeUTC(timezone=True), nullable=True)
+        )
+        batch_op.create_index('ix_pages_publish_at', ['publish_at'])
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('pages') as batch_op:
+        batch_op.drop_index('ix_pages_publish_at')
+        batch_op.drop_column('publish_at')

skrift/alembic/versions/20260202_add_page_ordering.py

@@ -0,0 +1,32 @@
+"""add page ordering
+
+Revision ID: 4d5e6f7g8h9i
+Revises: 3c4d5e6f7g8h
+Create Date: 2026-02-02 10:01:00.000000
+
+This migration adds an order column to the pages table for custom ordering.
+Lower numbers appear first, default is 0.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '4d5e6f7g8h9i'
+down_revision: Union[str, None] = '3c4d5e6f7g8h'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table('pages') as batch_op:
+        batch_op.add_column(sa.Column('order', sa.Integer(), nullable=False, server_default='0'))
+        batch_op.create_index('ix_pages_order', ['order'])
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('pages') as batch_op:
+        batch_op.drop_index('ix_pages_order')
+        batch_op.drop_column('order')

skrift/alembic/versions/20260202_add_page_revisions.py

@@ -0,0 +1,46 @@
+"""add page revisions table
+
+Revision ID: 6f7g8h9i0j1k
+Revises: 5e6f7g8h9i0j
+Create Date: 2026-02-02 10:03:00.000000
+
+This migration creates the page_revisions table for tracking content history.
+Revisions are created when page content is modified, allowing restoration.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import advanced_alchemy.types
+
+
+# revision identifiers, used by Alembic.
+revision: str = '6f7g8h9i0j1k'
+down_revision: Union[str, None] = '5e6f7g8h9i0j'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table('page_revisions',
+        sa.Column('id', advanced_alchemy.types.guid.GUID(length=16), nullable=False),
+        sa.Column('page_id', advanced_alchemy.types.guid.GUID(length=16), nullable=False),
+        sa.Column('user_id', advanced_alchemy.types.guid.GUID(length=16), nullable=True),
+        sa.Column('revision_number', sa.Integer(), nullable=False),
+        sa.Column('title', sa.String(length=500), nullable=False),
+        sa.Column('content', sa.Text(), nullable=False),
+        sa.Column('created_at', advanced_alchemy.types.datetime.DateTimeUTC(timezone=True), nullable=False),
+        sa.Column('sa_orm_sentinel', sa.Integer(), nullable=True),
+        sa.Column('updated_at', advanced_alchemy.types.datetime.DateTimeUTC(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(['page_id'], ['pages.id'], name=op.f('fk_page_revisions_page_id_pages'), ondelete='CASCADE'),
+        sa.ForeignKeyConstraint(['user_id'], ['users.id'], name=op.f('fk_page_revisions_user_id_users'), ondelete='SET NULL'),
+        sa.PrimaryKeyConstraint('id', name=op.f('pk_page_revisions'))
+    )
+    op.create_index(op.f('ix_page_revisions_page_id'), 'page_revisions', ['page_id'], unique=False)
+    op.create_index(op.f('ix_page_revisions_user_id'), 'page_revisions', ['user_id'], unique=False)
+
+
+def downgrade() -> None:
+    op.drop_index(op.f('ix_page_revisions_user_id'), table_name='page_revisions')
+    op.drop_index(op.f('ix_page_revisions_page_id'), table_name='page_revisions')
+    op.drop_table('page_revisions')

skrift/alembic/versions/20260202_add_seo_fields.py

@@ -0,0 +1,42 @@
+"""add SEO fields to pages
+
+Revision ID: 3c4d5e6f7g8h
+Revises: 2b3c4d5e6f7g
+Create Date: 2026-02-02 10:00:00.000000
+
+This migration adds SEO metadata fields to the pages table:
+- meta_description: Meta description for search engines
+- og_title: OpenGraph title override
+- og_description: OpenGraph description override
+- og_image: OpenGraph image URL
+- meta_robots: Meta robots directive (noindex, nofollow, etc.)
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '3c4d5e6f7g8h'
+down_revision: Union[str, None] = '2b3c4d5e6f7g'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table('pages') as batch_op:
+        batch_op.add_column(sa.Column('meta_description', sa.Text(), nullable=True))
+        batch_op.add_column(sa.Column('og_title', sa.String(length=500), nullable=True))
+        batch_op.add_column(sa.Column('og_description', sa.Text(), nullable=True))
+        batch_op.add_column(sa.Column('og_image', sa.String(length=1024), nullable=True))
+        batch_op.add_column(sa.Column('meta_robots', sa.String(length=100), nullable=True))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('pages') as batch_op:
+        batch_op.drop_column('meta_robots')
+        batch_op.drop_column('og_image')
+        batch_op.drop_column('og_description')
+        batch_op.drop_column('og_title')
+        batch_op.drop_column('meta_description')

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)