sardine-cms-core 0.1.0__tar.gz

sardine_cms_core-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_core-0.1.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: sardine-cms-core
+Version: 0.1.0
+Summary: Content model, versioned schemas and translation states for Sardine CMS
+License-Expression: Apache-2.0
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.9
+Provides-Extra: mssql
+Requires-Dist: pymssql>=2.3; extra == 'mssql'
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.1; extra == 'mysql'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# cms-core
+
+Content model, versioned schemas and translation states (EN source;
+`missing / outdated / complete`) for Sardine CMS. See the repository
+root README and docs for the full architecture.

sardine_cms_core-0.1.0/README.md

@@ -0,0 +1,5 @@
+# cms-core
+
+Content model, versioned schemas and translation states (EN source;
+`missing / outdated / complete`) for Sardine CMS. See the repository
+root README and docs for the full architecture.

sardine_cms_core-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "sardine-cms-core"
+version = "0.1.0"
+description = "Content model, versioned schemas and translation states for Sardine CMS"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+dependencies = ["pydantic>=2.9"]
+
+[project.optional-dependencies]
+postgres = ["psycopg[binary]>=3.2"]
+mysql = ["PyMySQL>=1.1"]
+mssql = ["pymssql>=2.3"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cms_core"]

sardine_cms_core-0.1.0/src/cms_core/__init__.py

@@ -0,0 +1,49 @@
+"""Content model, versioned schemas and translation states."""
+
+from cms_core.accounts import AdminSession, Role, User
+from cms_core.languages import SOURCE_LANGUAGE, TARGET_LANGUAGES, Language
+from cms_core.media import MediaAsset
+from cms_core.models import (
+    SCHEMA_VERSION,
+    Article,
+    ArticleContent,
+    new_article,
+)
+from cms_core.pages import Page, PageContent, Section, SectionContent, new_page
+from cms_core.states import ContentStatus, TranslationState
+from cms_core.storage import StorageBackend, create_storage
+from cms_core.translatable import (
+    ChecksummedContent,
+    TranslatableModel,
+    Translation,
+    worst_state,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "SOURCE_LANGUAGE",
+    "TARGET_LANGUAGES",
+    "AdminSession",
+    "Article",
+    "ArticleContent",
+    "ChecksummedContent",
+    "ContentStatus",
+    "Language",
+    "MediaAsset",
+    "Page",
+    "PageContent",
+    "Role",
+    "Section",
+    "SectionContent",
+    "StorageBackend",
+    "TranslatableModel",
+    "Translation",
+    "TranslationState",
+    "User",
+    "create_storage",
+    "new_article",
+    "new_page",
+    "worst_state",
+]

sardine_cms_core-0.1.0/src/cms_core/accounts.py

@@ -0,0 +1,48 @@
+"""Admin accounts and sessions (Milestone 3).
+
+Accounts are an operational concern of the admin panel: they live in the
+storage database (shared migration history) but are **never** part of the
+JSON/Markdown export — the portable source of truth stays content-only.
+The domain layer only defines the shapes; hashing and session issuance are
+the admin application's job.
+"""
+
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+USERNAME_PATTERN = r"^[a-z0-9][a-z0-9._-]{0,63}$"
+
+
+class Role(StrEnum):
+    """Least-privilege ladder; each step includes the previous one's intent.
+
+    editor: create and edit drafts · reviewer: move drafts through review ·
+    publisher: publish and archive · admin: manage accounts and settings.
+    """
+
+    EDITOR = "editor"
+    REVIEWER = "reviewer"
+    PUBLISHER = "publisher"
+    ADMIN = "admin"
+
+
+class User(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    username: str = Field(pattern=USERNAME_PATTERN)
+    password_hash: str = Field(min_length=1)
+    role: Role
+    created_at: datetime
+
+
+class AdminSession(BaseModel):
+    """A server-side session row. Only the token's hash is stored."""
+
+    model_config = ConfigDict(frozen=True)
+
+    token_hash: str = Field(min_length=1)
+    username: str = Field(pattern=USERNAME_PATTERN)
+    csrf_token: str = Field(min_length=1)
+    expires_at: datetime

sardine_cms_core-0.1.0/src/cms_core/export.py

@@ -0,0 +1,142 @@
+"""Deterministic portable export: a JSON index plus per-language Markdown files.
+
+Same input always produces byte-identical output — articles are sorted by id,
+JSON keys are sorted, and no timestamps are generated at export time.
+"""
+
+import json
+from collections.abc import Iterable
+
+from cms_core.languages import SOURCE_LANGUAGE, Language
+from cms_core.media import MediaAsset
+from cms_core.models import SCHEMA_VERSION, Article, ArticleContent
+from cms_core.pages import Page, Section
+
+
+def article_to_portable(article: Article) -> dict[str, object]:
+    languages: dict[str, dict[str, str]] = {
+        SOURCE_LANGUAGE.value: {
+            "state": "complete",
+            "title": article.source.title,
+            "summary": article.source.summary,
+        }
+    }
+    for language, translation in sorted(
+        article.translations.items(), key=lambda item: item[0].value
+    ):
+        languages[language.value] = {
+            "state": article.translation_state(language).value,
+            "title": translation.content.title,
+            "summary": translation.content.summary,
+            "source_checksum": translation.source_checksum,
+        }
+    return {
+        "id": article.id,
+        "status": article.status.value,
+        "created_at": article.created_at.isoformat(),
+        "updated_at": article.updated_at.isoformat(),
+        "languages": languages,
+    }
+
+
+def section_to_portable(section: Section) -> dict[str, object]:
+    languages: dict[str, dict[str, object]] = {
+        SOURCE_LANGUAGE.value: {
+            "state": "complete",
+            "fields": dict(sorted(section.source.fields.items())),
+            "media": list(section.source.media),
+        }
+    }
+    for language, translation in sorted(
+        section.translations.items(), key=lambda item: item[0].value
+    ):
+        languages[language.value] = {
+            "state": section.translation_state(language).value,
+            "fields": dict(sorted(translation.content.fields.items())),
+            "media": list(translation.content.media),
+            "source_checksum": translation.source_checksum,
+        }
+    return {"key": section.key, "kind": section.kind, "languages": languages}
+
+
+def page_to_portable(page: Page) -> dict[str, object]:
+    languages: dict[str, dict[str, str]] = {
+        SOURCE_LANGUAGE.value: {
+            "state": "complete",
+            "title": page.source.title,
+            "description": page.source.description,
+            "slug": page.source.slug,
+        }
+    }
+    for language, translation in sorted(page.translations.items(), key=lambda item: item[0].value):
+        languages[language.value] = {
+            "state": page.translation_state(language).value,
+            "title": translation.content.title,
+            "description": translation.content.description,
+            "slug": translation.content.slug,
+            "source_checksum": translation.source_checksum,
+        }
+    return {
+        "id": page.id,
+        "status": page.status.value,
+        "created_at": page.created_at.isoformat(),
+        "updated_at": page.updated_at.isoformat(),
+        "languages": languages,
+        "sections": [section_to_portable(section) for section in page.sections],
+    }
+
+
+def media_to_portable(asset: MediaAsset) -> dict[str, object]:
+    return {
+        "id": asset.id,
+        "path": asset.path,
+        "mime_type": asset.mime_type,
+        "width": asset.width,
+        "height": asset.height,
+        "alt": {
+            language.value: text
+            for language, text in sorted(asset.alt.items(), key=lambda item: item[0].value)
+        },
+    }
+
+
+def export_content_json(
+    articles: Iterable[Article],
+    pages: Iterable[Page] = (),
+    media: Iterable[MediaAsset] = (),
+) -> str:
+    payload = {
+        "schema_version": SCHEMA_VERSION,
+        "articles": [
+            article_to_portable(article)
+            for article in sorted(articles, key=lambda article: article.id)
+        ],
+        "pages": [page_to_portable(page) for page in sorted(pages, key=lambda page: page.id)],
+        "media": [media_to_portable(asset) for asset in sorted(media, key=lambda asset: asset.id)],
+    }
+    return json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+
+
+def export_markdown_files(articles: Iterable[Article]) -> dict[str, str]:
+    """Map of relative file path -> Markdown content, one file per language."""
+    files: dict[str, str] = {}
+    for article in sorted(articles, key=lambda article: article.id):
+        files[f"{article.id}/{SOURCE_LANGUAGE.value}.md"] = _render_markdown(article.source)
+        for language, translation in sorted(
+            article.translations.items(), key=lambda item: item[0].value
+        ):
+            files[f"{article.id}/{language.value}.md"] = _render_markdown(translation.content)
+    return files
+
+
+def _render_markdown(content: ArticleContent) -> str:
+    lines = [f"# {content.title}", ""]
+    if content.summary:
+        lines.extend([f"> {content.summary}", ""])
+    lines.append(content.body_markdown)
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def languages_in_export(files: dict[str, str]) -> set[Language]:
+    """Languages present in a Markdown export (used by parity checks)."""
+    return {Language(path.rsplit("/", 1)[1].removesuffix(".md")) for path in files}

sardine_cms_core-0.1.0/src/cms_core/languages.py

@@ -0,0 +1,17 @@
+"""Supported languages. English is the canonical source language."""
+
+from enum import StrEnum
+
+
+class Language(StrEnum):
+    EN = "en"
+    PT_PT = "pt-pt"
+    ES = "es"
+    FR = "fr"
+    DE = "de"
+
+
+SOURCE_LANGUAGE = Language.EN
+TARGET_LANGUAGES: tuple[Language, ...] = tuple(
+    language for language in Language if language is not SOURCE_LANGUAGE
+)

sardine_cms_core-0.1.0/src/cms_core/media.py

@@ -0,0 +1,38 @@
+"""Media assets with mandatory, translatable alt text.
+
+Editorial rules from the brief are enforced at the model level: images must
+declare their dimensions, and alt text in the source language is mandatory.
+"""
+
+from pydantic import BaseModel, Field, model_validator
+
+from cms_core.languages import SOURCE_LANGUAGE, TARGET_LANGUAGES, Language
+from cms_core.models import SLUG_PATTERN
+
+
+class MediaAsset(BaseModel):
+    id: str = Field(pattern=SLUG_PATTERN)
+    path: str = Field(min_length=1)
+    mime_type: str = Field(min_length=1)
+    width: int | None = Field(default=None, gt=0)
+    height: int | None = Field(default=None, gt=0)
+    alt: dict[Language, str]
+
+    @property
+    def is_image(self) -> bool:
+        return self.mime_type.startswith("image/")
+
+    @model_validator(mode="after")
+    def _enforce_editorial_rules(self) -> "MediaAsset":
+        if self.path.startswith("/") or ".." in self.path.split("/"):
+            raise ValueError("media path must be relative and must not traverse upwards")
+        if self.is_image and (self.width is None or self.height is None):
+            raise ValueError("images must declare width and height")
+        if not self.alt.get(SOURCE_LANGUAGE, "").strip():
+            raise ValueError(f"alt text in the source language ({SOURCE_LANGUAGE}) is mandatory")
+        return self
+
+    def missing_alt_languages(self) -> tuple[Language, ...]:
+        return tuple(
+            language for language in TARGET_LANGUAGES if not self.alt.get(language, "").strip()
+        )

sardine_cms_core-0.1.0/src/cms_core/models.py

@@ -0,0 +1,51 @@
+"""Article content model with per-language translations.
+
+Translation freshness is tracked by checksum (see :mod:`cms_core.translatable`):
+every translation records the checksum of the source (EN) content it was
+translated from, so a source edit automatically marks translations outdated.
+"""
+
+import re
+from datetime import UTC, datetime
+
+from pydantic import Field, field_validator
+
+from cms_core.states import ContentStatus
+from cms_core.translatable import ChecksummedContent, TranslatableModel
+
+SCHEMA_VERSION = 2
+
+SLUG_PATTERN = r"^[a-z0-9]+(?:-[a-z0-9]+)*$"
+
+
+class ArticleContent(ChecksummedContent):
+    title: str = Field(min_length=1)
+    summary: str = ""
+    body_markdown: str = ""
+    slug: str | None = Field(default=None, pattern=SLUG_PATTERN)
+
+    def checksum_payload(self) -> tuple[str, ...]:
+        return (self.title, self.summary, self.body_markdown, self.slug or "")
+
+
+class Article(TranslatableModel[ArticleContent]):
+    id: str = Field(pattern=SLUG_PATTERN)
+    status: ContentStatus = ContentStatus.DRAFT
+    created_at: datetime
+    updated_at: datetime
+    category: str | None = Field(default=None, pattern=SLUG_PATTERN)
+    cover: str | None = Field(default=None, pattern=SLUG_PATTERN)
+    tags: tuple[str, ...] = ()
+
+    @field_validator("tags")
+    @classmethod
+    def _tags_are_slugs(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        for tag in value:
+            if not re.fullmatch(SLUG_PATTERN, tag):
+                raise ValueError(f"tag {tag!r} is not a valid slug")
+        return tuple(sorted(set(value)))
+
+
+def new_article(article_id: str, source: ArticleContent, *, now: datetime | None = None) -> Article:
+    timestamp = now or datetime.now(tz=UTC)
+    return Article(id=article_id, created_at=timestamp, updated_at=timestamp, source=source)

sardine_cms_core-0.1.0/src/cms_core/pages.py

@@ -0,0 +1,65 @@
+"""Pages composed of typed sections; both are independently translatable.
+
+A section's ``kind`` names the theme template that renders it — cms-build
+never hardcodes HTML, per the extensibility contracts in docs/PLAN.md. A
+page's translation state aggregates its own content and every section: the
+least-complete state wins, so one missing section translation blocks the
+whole page from publishing.
+"""
+
+from datetime import UTC, datetime
+
+from pydantic import Field
+
+from cms_core.languages import Language
+from cms_core.models import SLUG_PATTERN
+from cms_core.states import ContentStatus, TranslationState
+from cms_core.translatable import ChecksummedContent, TranslatableModel, worst_state
+
+
+class PageContent(ChecksummedContent):
+    title: str = Field(min_length=1)
+    description: str = ""
+    slug: str = Field(pattern=SLUG_PATTERN)
+
+    def checksum_payload(self) -> tuple[str, ...]:
+        return (self.title, self.description, self.slug)
+
+
+class SectionContent(ChecksummedContent):
+    fields: dict[str, str] = Field(default_factory=dict)
+    media: list[str] = Field(default_factory=list)
+
+    def checksum_payload(self) -> tuple[str, ...]:
+        field_parts = tuple(f"{name}\x1e{self.fields[name]}" for name in sorted(self.fields))
+        return (*field_parts, "\x1d", *self.media)
+
+
+class Section(TranslatableModel[SectionContent]):
+    key: str = Field(pattern=SLUG_PATTERN)
+    kind: str = Field(pattern=SLUG_PATTERN)
+
+
+class Page(TranslatableModel[PageContent]):
+    id: str = Field(pattern=SLUG_PATTERN)
+    status: ContentStatus = ContentStatus.DRAFT
+    created_at: datetime
+    updated_at: datetime
+    sections: list[Section] = Field(default_factory=list)
+
+    def translation_state(self, language: Language) -> TranslationState:
+        own = super().translation_state(language)
+        return worst_state(
+            (own, *(section.translation_state(language) for section in self.sections))
+        )
+
+    def section(self, key: str) -> Section | None:
+        for section in self.sections:
+            if section.key == key:
+                return section
+        return None
+
+
+def new_page(page_id: str, source: PageContent, *, now: datetime | None = None) -> Page:
+    timestamp = now or datetime.now(tz=UTC)
+    return Page(id=page_id, created_at=timestamp, updated_at=timestamp, source=source)

sardine_cms_core-0.1.0/src/cms_core/states.py

@@ -0,0 +1,16 @@
+"""Translation states and the editorial content workflow."""
+
+from enum import StrEnum
+
+
+class TranslationState(StrEnum):
+    MISSING = "missing"
+    OUTDATED = "outdated"
+    COMPLETE = "complete"
+
+
+class ContentStatus(StrEnum):
+    DRAFT = "draft"
+    REVIEW = "review"
+    PUBLISHED = "published"
+    ARCHIVED = "archived"

sardine_cms_core-0.1.0/src/cms_core/storage/__init__.py

@@ -0,0 +1,23 @@
+"""Multi-backend persistence behind one interface.
+
+Backends register per URL scheme (``create_storage("sqlite:///content.db")``).
+SQLite ships built in; PostgreSQL, SQL Server and MySQL/MariaDB are planned
+and third parties can register custom engines via :func:`register_backend`.
+"""
+
+from cms_core.storage.base import StorageBackend
+from cms_core.storage.factory import (
+    available_schemes,
+    create_storage,
+    register_backend,
+)
+from cms_core.storage.sqlite import MIGRATIONS, SQLiteBackend
+
+__all__ = [
+    "MIGRATIONS",
+    "SQLiteBackend",
+    "StorageBackend",
+    "available_schemes",
+    "create_storage",
+    "register_backend",
+]

sardine_cms_core-0.1.0/src/cms_core/storage/base.py

@@ -0,0 +1,126 @@
+"""Backend-agnostic storage interface.
+
+Every storage engine (SQLite today; PostgreSQL and SQL Server planned)
+implements this one interface, so nothing above the storage layer knows which
+database is in use. The database is always a working store — the portable
+source of truth is the JSON/Markdown export (:mod:`cms_core.export`).
+"""
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from types import TracebackType
+
+from cms_core.accounts import AdminSession, User
+from cms_core.media import MediaAsset
+from cms_core.models import Article
+from cms_core.pages import Page
+
+
+class StorageBackend(ABC):
+    @abstractmethod
+    def schema_version(self) -> int: ...
+
+    @abstractmethod
+    def migrate(self) -> int: ...
+
+    @abstractmethod
+    def close(self) -> None: ...
+
+    # Articles
+
+    @abstractmethod
+    def save_article(self, article: Article) -> None: ...
+
+    @abstractmethod
+    def load_article(self, article_id: str) -> Article | None: ...
+
+    @abstractmethod
+    def delete_article(self, article_id: str) -> bool: ...
+
+    @abstractmethod
+    def list_article_ids(self) -> list[str]: ...
+
+    def load_all_articles(self) -> list[Article]:
+        articles = (self.load_article(article_id) for article_id in self.list_article_ids())
+        return [article for article in articles if article is not None]
+
+    # Pages
+
+    @abstractmethod
+    def save_page(self, page: Page) -> None: ...
+
+    @abstractmethod
+    def load_page(self, page_id: str) -> Page | None: ...
+
+    @abstractmethod
+    def delete_page(self, page_id: str) -> bool: ...
+
+    @abstractmethod
+    def list_page_ids(self) -> list[str]: ...
+
+    def load_all_pages(self) -> list[Page]:
+        pages = (self.load_page(page_id) for page_id in self.list_page_ids())
+        return [page for page in pages if page is not None]
+
+    # Media
+
+    @abstractmethod
+    def save_media_asset(self, asset: MediaAsset) -> None: ...
+
+    @abstractmethod
+    def load_media_asset(self, asset_id: str) -> MediaAsset | None: ...
+
+    @abstractmethod
+    def delete_media_asset(self, asset_id: str) -> bool: ...
+
+    @abstractmethod
+    def list_media_ids(self) -> list[str]: ...
+
+    def load_all_media_assets(self) -> list[MediaAsset]:
+        assets = (self.load_media_asset(asset_id) for asset_id in self.list_media_ids())
+        return [asset for asset in assets if asset is not None]
+
+    def has_content(self) -> bool:
+        """True when any article, page or media asset exists."""
+        return bool(self.list_article_ids() or self.list_page_ids() or self.list_media_ids())
+
+    # Admin accounts (never exported — see cms_core.accounts)
+
+    @abstractmethod
+    def save_user(self, user: User) -> None: ...
+
+    @abstractmethod
+    def load_user(self, username: str) -> User | None: ...
+
+    @abstractmethod
+    def delete_user(self, username: str) -> bool: ...
+
+    @abstractmethod
+    def list_usernames(self) -> list[str]: ...
+
+    # Admin sessions
+
+    @abstractmethod
+    def save_session(self, session: AdminSession) -> None: ...
+
+    @abstractmethod
+    def load_session(self, token_hash: str) -> AdminSession | None: ...
+
+    @abstractmethod
+    def delete_session(self, token_hash: str) -> bool: ...
+
+    @abstractmethod
+    def delete_expired_sessions(self, now: datetime) -> int: ...
+
+    # Context manager
+
+    def __enter__(self) -> "StorageBackend":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()