sardine-cms-admin 0.1.0__tar.gz

sardine_cms_admin-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+
+# Node (admin panel UI, if applicable)
+node_modules/
+*.tsbuildinfo
+
+# Environment and secrets
+.env
+.env.*
+!.env.example
+
+# Local databases
+*.sqlite3
+*.db
+
+# Static build output
+_site/
+out/
+export/
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/
+!.vscode/settings.json

sardine_cms_admin-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: sardine-cms-admin
+Version: 0.1.0
+Summary: Sardine CMS admin panel: FastAPI API + server-rendered UI
+License-Expression: Apache-2.0
+Requires-Python: >=3.12
+Requires-Dist: argon2-cffi>=23.1
+Requires-Dist: fastapi>=0.115
+Requires-Dist: jinja2>=3.1
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: sardine-cms-build
+Requires-Dist: sardine-cms-cli
+Requires-Dist: sardine-cms-core
+Requires-Dist: sardine-cms-validation
+Requires-Dist: uvicorn>=0.30
+Description-Content-Type: text/markdown
+
+# cms-admin
+
+The Sardine CMS admin panel: an authenticated FastAPI application serving both
+the admin API and the server-rendered UI (ADR-0013). It drives `cms-core`,
+`cms-validation` and `cms-build` through their public APIs — storage comes
+from `create_storage(url)`, so every supported engine works unchanged.
+
+```bash
+pip install -e apps/admin
+SARDINE_STORAGE_URL="sqlite:///content.db" uvicorn --factory cms_admin.app:create_app
+```
+
+There are no default credentials — create the first account with the CLI,
+then sign in at `/login`:
+
+```bash
+cms admin create-user editor-in-chief -p my-project --role admin
+```
+
+The UI is built on AdminLTE 4 (MIT, vendored verbatim with its license —
+ADR-0017), used CSS-only: the admin ships zero JavaScript and serves
+everything itself, no CDN. A small overlay adds the brand (local
+Inter/Newsreader) and accessibility fixes. The dashboard shows
+content by workflow status, the translation coverage matrix and a live
+validation report. Articles and pages are edited in the browser: EN source
+plus a side-by-side editor per translation, with state indicators from the
+checksum model and a preview rendered by the builder's own Markdown
+renderer (raw HTML disabled). The media library uploads with server-side
+validation (MIME sniffed from bytes, size limit, parsed image dimensions),
+manages mandatory EN + translatable alt text, and refuses to delete assets
+that articles or sections still reference. The workflow moves content through
+draft → review → published → archived with each transition owned by a rung
+of the role ladder; publishing runs the validation gate. The Publishing
+panel previews into `/preview/` and builds/exports the project output with
+target extras, with every run recorded on the dashboard.
+
+Configuration is environment-only (no config files with secrets):
+
+| Variable                        | Meaning                                     | Default                |
+| ------------------------------- | ------------------------------------------- | ---------------------- |
+| `SARDINE_STORAGE_URL`         | Storage URL for `create_storage`            | `sqlite:///content.db` |
+| `SARDINE_ADMIN_SESSION_HOURS` | Session lifetime in hours                   | `12`                   |
+| `SARDINE_ADMIN_COOKIE_SECURE` | Set `0` only for plain-http local dev       | `1`                    |
+| `SARDINE_MEDIA_DIR`             | Media upload directory (the project's)      | `media`                |
+| `SARDINE_ADMIN_UPLOAD_MAX_MB`   | Upload size limit in MB                     | `10`                   |
+| `SARDINE_PROJECT_DIR`           | Project directory (`sardine.toml`)          | `.`                    |
+| `SARDINE_ADMIN_PUBLISH_GATE`    | Set `0` to publish despite validation errors | `1`                   |
+
+The full admin guide — configuration, roles, workflow, publishing,
+security model — is [docs/ADMIN_GUIDE.md](../../docs/ADMIN_GUIDE.md)
+(anti-drift-checked). Milestone 3 status and the phased plan live in
+[docs/PLAN.md](../../docs/PLAN.md).

sardine_cms_admin-0.1.0/README.md

@@ -0,0 +1,52 @@
+# cms-admin
+
+The Sardine CMS admin panel: an authenticated FastAPI application serving both
+the admin API and the server-rendered UI (ADR-0013). It drives `cms-core`,
+`cms-validation` and `cms-build` through their public APIs — storage comes
+from `create_storage(url)`, so every supported engine works unchanged.
+
+```bash
+pip install -e apps/admin
+SARDINE_STORAGE_URL="sqlite:///content.db" uvicorn --factory cms_admin.app:create_app
+```
+
+There are no default credentials — create the first account with the CLI,
+then sign in at `/login`:
+
+```bash
+cms admin create-user editor-in-chief -p my-project --role admin
+```
+
+The UI is built on AdminLTE 4 (MIT, vendored verbatim with its license —
+ADR-0017), used CSS-only: the admin ships zero JavaScript and serves
+everything itself, no CDN. A small overlay adds the brand (local
+Inter/Newsreader) and accessibility fixes. The dashboard shows
+content by workflow status, the translation coverage matrix and a live
+validation report. Articles and pages are edited in the browser: EN source
+plus a side-by-side editor per translation, with state indicators from the
+checksum model and a preview rendered by the builder's own Markdown
+renderer (raw HTML disabled). The media library uploads with server-side
+validation (MIME sniffed from bytes, size limit, parsed image dimensions),
+manages mandatory EN + translatable alt text, and refuses to delete assets
+that articles or sections still reference. The workflow moves content through
+draft → review → published → archived with each transition owned by a rung
+of the role ladder; publishing runs the validation gate. The Publishing
+panel previews into `/preview/` and builds/exports the project output with
+target extras, with every run recorded on the dashboard.
+
+Configuration is environment-only (no config files with secrets):
+
+| Variable                        | Meaning                                     | Default                |
+| ------------------------------- | ------------------------------------------- | ---------------------- |
+| `SARDINE_STORAGE_URL`         | Storage URL for `create_storage`            | `sqlite:///content.db` |
+| `SARDINE_ADMIN_SESSION_HOURS` | Session lifetime in hours                   | `12`                   |
+| `SARDINE_ADMIN_COOKIE_SECURE` | Set `0` only for plain-http local dev       | `1`                    |
+| `SARDINE_MEDIA_DIR`             | Media upload directory (the project's)      | `media`                |
+| `SARDINE_ADMIN_UPLOAD_MAX_MB`   | Upload size limit in MB                     | `10`                   |
+| `SARDINE_PROJECT_DIR`           | Project directory (`sardine.toml`)          | `.`                    |
+| `SARDINE_ADMIN_PUBLISH_GATE`    | Set `0` to publish despite validation errors | `1`                   |
+
+The full admin guide — configuration, roles, workflow, publishing,
+security model — is [docs/ADMIN_GUIDE.md](../../docs/ADMIN_GUIDE.md)
+(anti-drift-checked). Milestone 3 status and the phased plan live in
+[docs/PLAN.md](../../docs/PLAN.md).

sardine_cms_admin-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "sardine-cms-admin"
+version = "0.1.0"
+description = "Sardine CMS admin panel: FastAPI API + server-rendered UI"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+dependencies = [
+    "sardine-cms-core",
+    "sardine-cms-validation",
+    "sardine-cms-build",
+    "sardine-cms-cli",
+    "fastapi>=0.115",
+    "jinja2>=3.1",
+    "uvicorn>=0.30",
+    "argon2-cffi>=23.1",
+    "python-multipart>=0.0.9",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cms_admin"]

sardine_cms_admin-0.1.0/src/cms_admin/__init__.py

@@ -0,0 +1,6 @@
+"""Sardine CMS admin panel (ADR-0013): FastAPI API + server-rendered UI."""
+
+from cms_admin.app import create_app
+from cms_admin.settings import AdminSettings
+
+__all__ = ["AdminSettings", "create_app"]

sardine_cms_admin-0.1.0/src/cms_admin/app.py

@@ -0,0 +1,102 @@
+"""Application factory.
+
+One FastAPI process serves the API and the server-rendered UI (ADR-0013).
+Storage is opened once per process (any supported engine, via the
+thread-affine ``StorageExecutor``) and closed on shutdown; handlers reach it
+through ``get_db``.
+"""
+
+import tempfile
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from cms_admin.articles import router as articles_router
+from cms_admin.auth import get_db
+from cms_admin.auth import router as auth_router
+from cms_admin.dashboard import router as dashboard_router
+from cms_admin.db import StorageExecutor
+from cms_admin.media import router as media_router
+from cms_admin.pages import router as pages_router
+from cms_admin.publishing import router as publishing_router
+from cms_admin.settings import AdminSettings
+
+
+@asynccontextmanager
+async def _lifespan(app: FastAPI) -> AsyncIterator[None]:
+    settings: AdminSettings = app.state.settings
+    app.state.db = StorageExecutor(settings.storage_url)
+    try:
+        yield
+    finally:
+        app.state.db.close()
+
+
+# Hardening (SECURITY_STRATEGY, M3 phase 9): the admin ships zero JavaScript,
+# so the CSP allows no script source at all; styles, fonts and images come
+# only from the app itself; nothing may frame it.
+SECURITY_HEADERS = {
+    "Content-Security-Policy": (
+        "default-src 'none'; style-src 'self'; font-src 'self'; "
+        "img-src 'self' data:; form-action 'self'; base-uri 'none'; "
+        "frame-ancestors 'none'"
+    ),
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "DENY",
+    "Referrer-Policy": "strict-origin-when-cross-origin",
+    "Permissions-Policy": "geolocation=(), microphone=(), camera=()",
+}
+
+
+def create_app(settings: AdminSettings | None = None) -> FastAPI:
+    from cms_admin.auth import LoginRateLimiter
+
+    app = FastAPI(title="Sardine CMS admin", lifespan=_lifespan, docs_url=None, redoc_url=None)
+
+    @app.middleware("http")
+    async def _security_headers(request: Request, call_next):  # type: ignore[no-untyped-def]
+        response = await call_next(request)
+        for name, value in SECURITY_HEADERS.items():
+            response.headers.setdefault(name, value)
+        return response
+
+    app.state.settings = settings if settings is not None else AdminSettings.from_env()
+    # autoescape must be forced on: the stock select_autoescape does not
+    # recognize the .html.j2 extension and would render templates unescaped.
+    app.state.templates = Jinja2Templates(
+        env=Environment(
+            loader=FileSystemLoader(Path(__file__).parent / "templates"),
+            autoescape=select_autoescape(default=True, default_for_string=True),
+        )
+    )
+    app.state.login_limiter = LoginRateLimiter()
+    app.include_router(auth_router)
+    app.include_router(dashboard_router)
+    app.include_router(articles_router)
+    app.include_router(pages_router)
+    app.include_router(media_router)
+    app.include_router(publishing_router)
+    app.state.preview_dir = tempfile.mkdtemp(prefix="sardine-preview-")
+    app.mount("/static", StaticFiles(directory=Path(__file__).parent / "static"), name="static")
+    app.mount(
+        "/preview",
+        StaticFiles(directory=app.state.preview_dir, html=True, check_dir=False),
+        name="preview",
+    )
+    app.mount(
+        "/media-files",
+        StaticFiles(directory=app.state.settings.media_dir, check_dir=False),
+        name="media-files",
+    )
+
+    @app.get("/healthz")
+    async def healthz(request: Request) -> dict[str, str | int]:
+        version = await get_db(request).run(lambda storage: storage.schema_version())
+        return {"status": "ok", "schema_version": version}
+
+    return app

sardine_cms_admin-0.1.0/src/cms_admin/articles.py

@@ -0,0 +1,393 @@
+"""Articles: list, create, and the side-by-side translation editor.
+
+The EN source is edited on the article page; each translation is edited next
+to a read-only view of the source it translates (the checksum model marks it
+outdated automatically when the source changes afterwards). The preview uses
+the builder's own Markdown renderer, so what an editor sees is exactly what
+the published site will render — raw HTML stays disabled.
+"""
+
+from datetime import UTC, datetime
+
+from cms_build import render_markdown
+from cms_core import (
+    AdminSession,
+    Article,
+    ArticleContent,
+    ContentStatus,
+    Language,
+    Role,
+    User,
+    new_article,
+)
+from cms_core.languages import SOURCE_LANGUAGE, TARGET_LANGUAGES
+from cms_validation import SiteContent
+from fastapi import APIRouter, Depends, Form, HTTPException, Request, status
+from fastapi.responses import RedirectResponse
+from pydantic import ValidationError
+
+from cms_admin.auth import current_session, enforce_csrf, get_db
+from cms_admin.workflow import (
+    allowed,
+    available_transitions,
+    publish_blockers,
+    transition_minimum,
+)
+
+router = APIRouter(prefix="/articles")
+
+HTTP_422 = status.HTTP_422_UNPROCESSABLE_CONTENT
+
+
+def form_errors(error: ValidationError) -> list[str]:
+    return [
+        f"{'.'.join(str(part) for part in item['loc']) or 'form'}: {item['msg']}"
+        for item in error.errors()
+    ]
+
+
+def parse_tags(raw: str) -> tuple[str, ...]:
+    return tuple(part.strip() for part in raw.split(",") if part.strip())
+
+
+def content_form(content: ArticleContent | None) -> dict[str, str]:
+    if content is None:
+        return {"title": "", "summary": "", "body_markdown": "", "slug": ""}
+    return {
+        "title": content.title,
+        "summary": content.summary,
+        "body_markdown": content.body_markdown,
+        "slug": content.slug or "",
+    }
+
+
+def _target_language(code: str) -> Language:
+    try:
+        language = Language(code)
+    except ValueError:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="unknown language"
+        ) from None
+    if language is SOURCE_LANGUAGE:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="the source language is edited on the article page",
+        )
+    return language
+
+
+async def _load_article(request: Request, article_id: str) -> Article:
+    article = await get_db(request).run(lambda storage: storage.load_article(article_id))
+    if article is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="unknown article")
+    return article
+
+
+def _page(
+    request: Request, template: str, context: dict[str, object], status_code: int = 200
+) -> object:
+    return request.app.state.templates.TemplateResponse(
+        request, template, {"active_section": "articles", **context}, status_code=status_code
+    )
+
+
+@router.get("")
+async def articles_list(
+    request: Request,
+    user_session: tuple[User, AdminSession] = Depends(current_session),
+) -> object:
+    user, session = user_session
+    articles = await get_db(request).run(lambda storage: storage.load_all_articles())
+    return _page(
+        request,
+        "articles_list.html.j2",
+        {
+            "user": user,
+            "csrf_token": session.csrf_token,
+            "articles": articles,
+            "target_languages": TARGET_LANGUAGES,
+        },
+    )
+
+
+@router.get("/new")
+async def article_new_form(
+    request: Request,
+    user_session: tuple[User, AdminSession] = Depends(current_session),
+) -> object:
+    user, session = user_session
+    form = {"id": "", "category": "", "tags": "", "cover": "", **content_form(None)}
+    return _page(
+        request,
+        "article_new.html.j2",
+        {"user": user, "csrf_token": session.csrf_token, "errors": [], "form": form},
+    )
+
+
+def _validated_article(base: Article, form: dict[str, str]) -> Article:
+    """Rebuild the article from the form and run every model validator once."""
+    payload = base.model_dump()
+    payload.update(
+        source=ArticleContent(
+            title=form["title"],
+            summary=form["summary"],
+            body_markdown=form["body_markdown"],
+            slug=form["slug"] or None,
+        ).model_dump(),
+        category=form["category"] or None,
+        cover=form["cover"] or None,
+        tags=parse_tags(form["tags"]),
+        updated_at=datetime.now(UTC),
+    )
+    return Article.model_validate(payload)
+
+
+@router.post("")
+async def article_create(
+    request: Request,
+    user_session: tuple[User, AdminSession] = Depends(enforce_csrf),
+    article_id: str = Form(alias="id"),
+    title: str = Form(""),
+    summary: str = Form(""),
+    body_markdown: str = Form(""),
+    slug: str = Form(""),
+    category: str = Form(""),
+    tags: str = Form(""),
+    cover: str = Form(""),
+) -> object:
+    user, session = user_session
+    db = get_db(request)
+    form = {
+        "id": article_id,
+        "title": title,
+        "summary": summary,
+        "body_markdown": body_markdown,
+        "slug": slug,
+        "category": category,
+        "tags": tags,
+        "cover": cover,
+    }
+    try:
+        base = new_article(article_id, ArticleContent(title=title or "-"))
+        article = _validated_article(base, form)
+    except ValidationError as error:
+        errors = form_errors(error)
+    else:
+        existing = await db.run(lambda storage: storage.load_article(article_id))
+        if existing is None:
+            await db.run(lambda storage: storage.save_article(article))
+            return RedirectResponse(
+                f"/articles/{article.id}", status_code=status.HTTP_303_SEE_OTHER
+            )
+        errors = [f"id: an article with id {article_id!r} already exists"]
+    return _page(
+        request,
+        "article_new.html.j2",
+        {"user": user, "csrf_token": session.csrf_token, "errors": errors, "form": form},
+        status_code=HTTP_422,
+    )
+
+
+def _editor_context(
+    article: Article, form: dict[str, str] | None = None, role: Role | None = None
+) -> dict[str, object]:
+    return {
+        "article": article,
+        "transitions": available_transitions(article.status, role) if role else [],
+        "states": article.translation_states(),
+        "target_languages": TARGET_LANGUAGES,
+        "preview_html": render_markdown(article.source.body_markdown),
+        "form": form
+        or {
+            **content_form(article.source),
+            "category": article.category or "",
+            "tags": ", ".join(article.tags),
+            "cover": article.cover or "",
+        },
+    }
+
+
+@router.get("/{article_id}")
+async def article_edit_form(
+    request: Request,
+    article_id: str,
+    user_session: tuple[User, AdminSession] = Depends(current_session),
+) -> object:
+    user, session = user_session
+    article = await _load_article(request, article_id)
+    return _page(
+        request,
+        "article_edit.html.j2",
+        {
+            "user": user,
+            "csrf_token": session.csrf_token,
+            "errors": [],
+            **_editor_context(article, role=user.role),
+        },
+    )
+
+
+@router.post("/{article_id}")
+async def article_edit_save(
+    request: Request,
+    article_id: str,
+    user_session: tuple[User, AdminSession] = Depends(enforce_csrf),
+    title: str = Form(""),
+    summary: str = Form(""),
+    body_markdown: str = Form(""),
+    slug: str = Form(""),
+    category: str = Form(""),
+    tags: str = Form(""),
+    cover: str = Form(""),
+) -> object:
+    user, session = user_session
+    article = await _load_article(request, article_id)
+    form = {
+        "title": title,
+        "summary": summary,
+        "body_markdown": body_markdown,
+        "slug": slug,
+        "category": category,
+        "tags": tags,
+        "cover": cover,
+    }
+    try:
+        article = _validated_article(article, form)
+    except ValidationError as error:
+        return _page(
+            request,
+            "article_edit.html.j2",
+            {
+                "user": user,
+                "csrf_token": session.csrf_token,
+                "errors": form_errors(error),
+                **_editor_context(article, form, role=user.role),
+            },
+            status_code=HTTP_422,
+        )
+    await get_db(request).run(lambda storage: storage.save_article(article))
+    return RedirectResponse(f"/articles/{article.id}", status_code=status.HTTP_303_SEE_OTHER)
+
+
+def _translation_context(
+    article: Article, language: Language, form: dict[str, str] | None = None
+) -> dict[str, object]:
+    translation = article.translations.get(language)
+    content = translation.content if translation else None
+    return {
+        "article": article,
+        "language": language,
+        "state": article.translation_state(language),
+        "source_preview_html": render_markdown(article.source.body_markdown),
+        "preview_html": render_markdown(content.body_markdown) if content else "",
+        "form": form or content_form(content),
+    }
+
+
+@router.get("/{article_id}/translations/{language_code}")
+async def translation_form(
+    request: Request,
+    article_id: str,
+    language_code: str,
+    user_session: tuple[User, AdminSession] = Depends(current_session),
+) -> object:
+    user, session = user_session
+    language = _target_language(language_code)
+    article = await _load_article(request, article_id)
+    return _page(
+        request,
+        "article_translation.html.j2",
+        {
+            "user": user,
+            "csrf_token": session.csrf_token,
+            "errors": [],
+            **_translation_context(article, language),
+        },
+    )
+
+
+@router.post("/{article_id}/translations/{language_code}")
+async def translation_save(
+    request: Request,
+    article_id: str,
+    language_code: str,
+    user_session: tuple[User, AdminSession] = Depends(enforce_csrf),
+    title: str = Form(""),
+    summary: str = Form(""),
+    body_markdown: str = Form(""),
+    slug: str = Form(""),
+) -> object:
+    user, session = user_session
+    language = _target_language(language_code)
+    article = await _load_article(request, article_id)
+    form = {"title": title, "summary": summary, "body_markdown": body_markdown, "slug": slug}
+    try:
+        content = ArticleContent(
+            title=title, summary=summary, body_markdown=body_markdown, slug=slug or None
+        )
+    except ValidationError as error:
+        return _page(
+            request,
+            "article_translation.html.j2",
+            {
+                "user": user,
+                "csrf_token": session.csrf_token,
+                "errors": form_errors(error),
+                **_translation_context(article, language, form),
+            },
+            status_code=HTTP_422,
+        )
+    article.set_translation(language, content)
+    article.updated_at = datetime.now(UTC)
+    await get_db(request).run(lambda storage: storage.save_article(article))
+    return RedirectResponse(
+        f"/articles/{article.id}/translations/{language.value}",
+        status_code=status.HTTP_303_SEE_OTHER,
+    )
+
+
+@router.post("/{article_id}/status")
+async def article_status(
+    request: Request,
+    article_id: str,
+    user_session: tuple[User, AdminSession] = Depends(enforce_csrf),
+    to: str = Form(...),
+) -> object:
+    user, session = user_session
+    article = await _load_article(request, article_id)
+    try:
+        target = ContentStatus(to)
+    except ValueError:
+        raise HTTPException(status_code=400, detail="unknown status") from None
+    minimum = transition_minimum(article.status, target)
+    if minimum is None:
+        raise HTTPException(status_code=400, detail="invalid transition")
+    if not allowed(user.role, minimum):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"requires the {minimum.value} role",
+        )
+    if target is ContentStatus.PUBLISHED and request.app.state.settings.publish_gate:
+        db = get_db(request)
+        content = SiteContent(
+            articles=await db.run(lambda storage: storage.load_all_articles()),
+            pages=await db.run(lambda storage: storage.load_all_pages()),
+            media=await db.run(lambda storage: storage.load_all_media_assets()),
+        )
+        blockers = publish_blockers(article, content)
+        if blockers:
+            return _page(
+                request,
+                "article_edit.html.j2",
+                {
+                    "user": user,
+                    "csrf_token": session.csrf_token,
+                    "errors": blockers,
+                    **_editor_context(article, role=user.role),
+                },
+                status_code=HTTP_422,
+            )
+    article.status = target
+    article.updated_at = datetime.now(UTC)
+    await get_db(request).run(lambda storage: storage.save_article(article))
+    return RedirectResponse(f"/articles/{article.id}", status_code=status.HTTP_303_SEE_OTHER)