databricks-tellr-app 0.3.11.dev5__tar.gz → 0.3.11.dev7__tar.gz

{databricks_tellr_app-0.3.11.dev5 → databricks_tellr_app-0.3.11.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databricks-tellr-app
-Version: 0.3.11.dev5
+Version: 0.3.11.dev7
 Summary: Tellr application package for Databricks Apps
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{databricks_tellr_app-0.3.11.dev5 → databricks_tellr_app-0.3.11.dev7}/databricks_tellr_app.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databricks-tellr-app
-Version: 0.3.11.dev5
+Version: 0.3.11.dev7
 Summary: Tellr application package for Databricks Apps
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{databricks_tellr_app-0.3.11.dev5 → databricks_tellr_app-0.3.11.dev7}/databricks_tellr_app.egg-info/SOURCES.txt

@@ -99,6 +99,7 @@ setup.py
 ./src/services/config_validator.py
 ./src/services/design_system_compiler.py
 ./src/services/design_system_service.py
+./src/services/design_system_templates.py
 ./src/services/drive_uploader.py
 ./src/services/genie_service.py
 ./src/services/google_slides_auth.py
@@ -123,6 +124,7 @@ setup.py
 ./src/services/identity_providers/workspace_provider.py
 ./src/services/tools/__init__.py
 ./src/services/tools/agent_bricks_tool.py
+./src/services/tools/ds_asset_tool.py
 ./src/services/tools/genie_tool.py
 ./src/services/tools/mcp_tool.py
 ./src/services/tools/model_endpoint_tool.py
@@ -243,6 +245,7 @@ src/services/config_service.py
 src/services/config_validator.py
 src/services/design_system_compiler.py
 src/services/design_system_service.py
+src/services/design_system_templates.py
 src/services/drive_uploader.py
 src/services/genie_service.py
 src/services/google_slides_auth.py
@@ -267,6 +270,7 @@ src/services/identity_providers/local_provider.py
 src/services/identity_providers/workspace_provider.py
 src/services/tools/__init__.py
 src/services/tools/agent_bricks_tool.py
+src/services/tools/ds_asset_tool.py
 src/services/tools/genie_tool.py
 src/services/tools/mcp_tool.py
 src/services/tools/model_endpoint_tool.py

{databricks_tellr_app-0.3.11.dev5 → databricks_tellr_app-0.3.11.dev7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "databricks-tellr-app"
-version = "0.3.11.dev5"
+version = "0.3.11.dev7"
 description = "Tellr application package for Databricks Apps"
 readme = "README.md"
 requires-python = ">=3.10"

{databricks_tellr_app-0.3.11.dev5 → databricks_tellr_app-0.3.11.dev7}/src/api/routes/agent_config.py

@@ -21,9 +21,25 @@ router = APIRouter(prefix="/api/sessions/{session_id}/agent-config", tags=["agen
 
 
 def _validate_references(config: AgentConfig) -> None:
-    """Validate that design_system_id, slide_style_id and deck_prompt_id reference
-    existing (active) library entries."""
-    from src.database.models import DesignSystem, SlideDeckPromptLibrary, SlideStyleLibrary
+    """Validate the library references and SANITIZE the template pin, in place.
+
+    ``design_system_id``, ``slide_style_id`` and ``deck_prompt_id`` stay STRICT
+    (422 on a missing/inactive entry — the existing convention). The template
+    pin is SELF-HEALING instead: template ids are re-minted by the sanctioned
+    delete+re-upload workflow, so a persisted config can legitimately hold a
+    stale pin — rejecting it would wedge EVERY later config update. When
+    ``template_id`` does not resolve to a template belonging to the selected
+    design system (pin with no design system, another system's template, or a
+    missing/re-materialized template), it is cleared in place with a warning;
+    the caller persists and returns the sanitized config so the frontend state
+    syncs. This mirrors the deliberately lenient generation path.
+    """
+    from src.database.models import (
+        DesignSystem,
+        DesignSystemTemplate,
+        SlideDeckPromptLibrary,
+        SlideStyleLibrary,
+    )
 
     with get_db_session() as db:
         if config.design_system_id is not None:
@@ -40,6 +56,26 @@ def _validate_references(config: AgentConfig) -> None:
                     status_code=422,
                     detail=f"design_system_id {config.design_system_id} not found",
                 )
+        if config.template_id is not None:
+            template = None
+            if config.design_system_id is not None:
+                template = (
+                    db.query(DesignSystemTemplate)
+                    .filter(
+                        DesignSystemTemplate.id == config.template_id,
+                        DesignSystemTemplate.design_system_id == config.design_system_id,
+                    )
+                    .first()
+                )
+            if template is None:
+                logger.warning(
+                    "Clearing stale template pin %s (design_system_id=%s): the "
+                    "template does not exist or does not belong to the selected "
+                    "design system; saving the config without it",
+                    config.template_id,
+                    config.design_system_id,
+                )
+                config.template_id = None
         if config.slide_style_id is not None:
             style = (
                 db.query(SlideStyleLibrary)
@@ -115,7 +151,9 @@ async def get_agent_config(session_id: str):
 async def put_agent_config(session_id: str, config: AgentConfig):
     """Replace the full agent config for a session."""
     # Pydantic already validated duplicates via model_validator.
-    # Now validate foreign-key references.
+    # Now validate foreign-key references; a stale template pin is sanitized
+    # (cleared in place) rather than rejected, so what is persisted and
+    # returned below is the effective config.
     _validate_references(config)
 
     try:

{databricks_tellr_app-0.3.11.dev5 → databricks_tellr_app-0.3.11.dev7}/src/api/routes/settings/design_systems.py

@@ -15,6 +15,7 @@ silently overwritten; the caller supplies a different name (import accepts a
 """
 import logging
 import os
+import re
 from typing import List, Optional
 
 from fastapi import APIRouter, Depends, File, Form, HTTPException, Response, UploadFile, status
@@ -27,6 +28,8 @@ from src.database.models.design_system import (
     MAX_BUNDLE_SIZE_BYTES,
     DesignSystem,
     DesignSystemAsset,
+    DesignSystemFile,
+    DesignSystemTemplate,
     DesignSystemToken,
 )
 from src.services import design_system_service
@@ -65,6 +68,34 @@ class AssetOut(BaseModel):
     url: str  # served-asset endpoint (bytes are never inlined in listings)
 
 
+class TemplateOut(BaseModel):
+    """Picker view of one addressable template (Phase 4). The layout HTML is
+    deliberately NOT exposed here — source viewing is a later phase."""
+    id: int
+    name: str
+    description: Optional[str]
+    entry_path: str
+    thumbnail_url: Optional[str]  # template-scoped thumbnail endpoint, or None
+
+
+class DesignSystemTemplateListResponse(BaseModel):
+    templates: List[TemplateOut]
+    total: int
+
+
+class FileEntryOut(BaseModel):
+    """One node of the source-file tree (Phase 6) — metadata only, never bytes."""
+    path: str
+    kind: str
+    mime: str
+    size_bytes: int
+
+
+class DesignSystemFileListResponse(BaseModel):
+    files: List[FileEntryOut]
+    total: int
+
+
 class DesignSystemSummary(BaseModel):
     """List/picker view — counts only, no binary payloads."""
     id: int
@@ -473,12 +504,123 @@ def set_default_design_system(ds_id: int, db: Session = Depends(get_db)):
         )
 
 
+def _template_thumbnail_url(ds_id: int, template_id: int) -> str:
+    return f"/api/settings/design-systems/{ds_id}/templates/{template_id}/thumbnail"
+
+
+@router.get("/{ds_id}/templates", response_model=DesignSystemTemplateListResponse)
+def list_design_system_templates(ds_id: int, db: Session = Depends(get_db)):
+    """List a design system's addressable templates for the picker.
+
+    Rows are materialized lazily (from the manifest + retained bundle files) for
+    systems imported before templates were addressable entities, then persisted;
+    a system without retained template files simply lists zero templates.
+    """
+    try:
+        ds = db.query(DesignSystem).filter(DesignSystem.id == ds_id).first()
+        if not ds:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Design system {ds_id} not found",
+            )
+        from src.services.design_system_templates import materialize_templates
+
+        if materialize_templates(ds):
+            db.commit()  # persist lazily-derived rows (and assign their ids)
+
+        templates = sorted(ds.templates, key=lambda t: t.id)
+        return DesignSystemTemplateListResponse(
+            templates=[
+                TemplateOut(
+                    id=t.id,
+                    name=t.name,
+                    description=t.description,
+                    entry_path=t.entry_path,
+                    thumbnail_url=(
+                        _template_thumbnail_url(ds_id, t.id)
+                        if t.thumbnail_asset_id is not None
+                        else None
+                    ),
+                )
+                for t in templates
+            ],
+            total=len(templates),
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        db.rollback()
+        logger.error(f"Error listing templates for design system {ds_id}: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to list design system templates",
+        )
+
+
 # Raster image types that are safe to render inline. Anything else (notably
 # image/svg+xml, which can carry inline <script>) is served as a download so a
 # directly-navigated asset cannot execute script in the app origin (stored XSS).
 _INLINE_SAFE_MIMES = frozenset({"image/png", "image/jpeg", "image/gif", "image/webp"})
 
 
+@router.get("/{ds_id}/templates/{template_id}/thumbnail")
+def serve_design_system_template_thumbnail(
+    ds_id: int, template_id: int, db: Session = Depends(get_db)
+):
+    """Serve a template's preview-screenshot bytes for the picker.
+
+    Ownership-validated end to end: the template must belong to the design
+    system in the path AND its thumbnail asset must belong to the same system —
+    404 otherwise. Served with ``X-Content-Type-Options: nosniff`` (and forced
+    to download for non-raster types), mirroring the asset endpoint.
+    """
+    try:
+        template = (
+            db.query(DesignSystemTemplate)
+            .filter(
+                DesignSystemTemplate.id == template_id,
+                DesignSystemTemplate.design_system_id == ds_id,
+            )
+            .first()
+        )
+        if not template or template.thumbnail_asset_id is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Thumbnail not found for template {template_id} "
+                f"of design system {ds_id}",
+            )
+        asset = (
+            db.query(DesignSystemAsset)
+            .filter(
+                DesignSystemAsset.id == template.thumbnail_asset_id,
+                DesignSystemAsset.design_system_id == ds_id,
+            )
+            .first()
+        )
+        if not asset:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Thumbnail not found for template {template_id} "
+                f"of design system {ds_id}",
+            )
+        mime = str(asset.mime)
+        headers = {"X-Content-Type-Options": "nosniff"}
+        if mime not in _INLINE_SAFE_MIMES:
+            # Static value (no attacker-controlled filename) to avoid header injection.
+            headers["Content-Disposition"] = "attachment"
+        return Response(content=asset.data, media_type=mime, headers=headers)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            f"Error serving thumbnail for template {template_id}: {e}", exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to serve design system template thumbnail",
+        )
+
+
 @router.get("/{ds_id}/assets/{asset_id}")
 def serve_design_system_asset(ds_id: int, asset_id: int, db: Session = Depends(get_db)):
     """Serve a design-system asset's raw bytes (for preview + generation).
@@ -515,3 +657,191 @@ def serve_design_system_asset(ds_id: int, asset_id: int, db: Session = Depends(g
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail="Failed to serve design system asset",
         )
+
+
+# --- Source-file browser (v1 Phase 6) ----------------------------------------
+
+# Extensions/MIMEs that are TEXT SOURCE material in the file browser. Anything
+# matched here is served as ``text/plain`` so user-uploaded markup (HTML, SVG,
+# JS, …) can never render or execute in the app origin — the browser is a SOURCE
+# viewer, never a preview surface (template previews go through the thumbnail
+# endpoint instead). The extension fallback covers rows whose stored MIME was
+# unguessable at import time.
+_TEXT_SOURCE_EXTENSIONS = frozenset(
+    ("md", "markdown", "css", "json", "html", "htm", "js", "mjs", "svg", "txt", "xml")
+)
+_TEXT_SOURCE_MIMES = frozenset(
+    (
+        "application/json",
+        "application/javascript",
+        "application/ecmascript",
+        "application/xml",
+    )
+)
+
+# Percent-encoded '.', '/' or '\' still present AFTER the framework's one decode
+# pass — only ever seen in double-encoding smuggling attempts, so reject outright.
+_ENCODED_TRAVERSAL_RE = re.compile(r"%(2e|2f|5c)", re.IGNORECASE)
+
+
+def _validated_file_path(raw: str) -> Optional[str]:
+    """Return ``raw`` when it is a canonical bundle-relative path, else ``None``.
+
+    Stored ``design_system_file.path`` values are canonical by construction (the
+    importer normalizes them via ``_safe_relpath``), so the browser REJECTS any
+    non-canonical request instead of normalizing it into an accepted form:
+    backslashes, absolute/drive paths, empty/``.``/``..`` segments, and lingering
+    percent-encoded traversal bytes all fail. Lookups are DB-exact within one
+    design system (no filesystem involved), so this is defence-in-depth.
+    """
+    if not raw or "\\" in raw:
+        return None
+    # NUL / C0 control characters never appear in a legitimate stored path, and
+    # NUL in particular must be rejected BEFORE the DB lookup: psycopg2 refuses
+    # NUL in a bound parameter (ValueError), which would surface as a 500
+    # instead of the uniform opaque 404 (SQLite masks this as a no-match 404).
+    if any(ord(ch) < 0x20 for ch in raw):
+        return None
+    if _ENCODED_TRAVERSAL_RE.search(raw):
+        return None
+    if raw.startswith("/") or re.match(r"^[A-Za-z]:", raw):
+        return None
+    if any(segment in ("", ".", "..") for segment in raw.split("/")):
+        return None
+    return raw
+
+
+def _is_text_source(path: str, mime: str) -> bool:
+    """True when a stored file is text source material (served as text/plain)."""
+    mime_l = (mime or "").lower()
+    if mime_l.startswith("text/"):
+        return True
+    if mime_l in _TEXT_SOURCE_MIMES or mime_l.endswith("+json") or mime_l.endswith("+xml"):
+        return True
+    base = path.rsplit("/", 1)[-1]
+    ext = base.rsplit(".", 1)[-1].lower() if "." in base else ""
+    return ext in _TEXT_SOURCE_EXTENSIONS
+
+
+@router.get("/{ds_id}/files", response_model=DesignSystemFileListResponse)
+def list_design_system_files(ds_id: int, db: Session = Depends(get_db)):
+    """List a design system's retained bundle file tree — metadata only.
+
+    ``design_system_file`` carries the COMPLETE tree for any system imported
+    since source retention (v1 Phase 1): SOURCE rows (readme/skill/css/template
+    HTML) plus path-only REFERENCE rows for every asset/font (their bytes live in
+    ``design_system_asset``). The listing is a column projection — byte payloads
+    are never loaded, mirroring the blob-free list conventions above.
+    """
+    try:
+        exists = db.query(DesignSystem.id).filter(DesignSystem.id == ds_id).first()
+        if not exists:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Design system {ds_id} not found",
+            )
+        rows = (
+            db.query(
+                DesignSystemFile.path,
+                DesignSystemFile.kind,
+                DesignSystemFile.mime,
+                DesignSystemFile.size_bytes,
+            )
+            .filter(DesignSystemFile.design_system_id == ds_id)
+            .all()
+        )
+        # Sort in Python: deterministic byte order on every backend (SQL ORDER BY
+        # is collation-dependent on PostgreSQL).
+        rows = sorted(rows, key=lambda r: str(r[0]))
+        return DesignSystemFileListResponse(
+            files=[
+                FileEntryOut(path=path, kind=kind, mime=mime, size_bytes=size_bytes)
+                for path, kind, mime, size_bytes in rows
+            ],
+            total=len(rows),
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error listing files for design system {ds_id}: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to list design system files",
+        )
+
+
+@router.get("/{ds_id}/files/{file_path:path}")
+def serve_design_system_file(ds_id: int, file_path: str, db: Session = Depends(get_db)):
+    """Serve ONE stored bundle file's content — the "Open source file" endpoint.
+
+    Security posture for user-uploaded content (mirrors the thumbnail/asset
+    endpoints, hardened further because this endpoint serves markup sources):
+
+    - The requested path must be canonical (:func:`_validated_file_path` rejects
+      traversal, absolute, backslash and percent-encoded forms) and is looked up
+      by EXACT match scoped to this design system; reference rows resolve their
+      bytes through an ownership-checked ``design_system_asset`` lookup. Every
+      failure is the same opaque 404.
+    - Text sources (md/css/html/js/json/svg/…) are served as
+      ``text/plain; charset=utf-8`` — uploaded markup never gets a renderable or
+      executable content type.
+    - EVERY response is ``Content-Disposition: attachment`` (static value — no
+      attacker-controlled filename, no header injection) with
+      ``X-Content-Type-Options: nosniff``; nothing is served inline.
+    """
+    not_found = HTTPException(
+        status_code=status.HTTP_404_NOT_FOUND,
+        detail=f"File not found for design system {ds_id}",
+    )
+    try:
+        validated = _validated_file_path(file_path)
+        if validated is None:
+            raise not_found
+        row = (
+            db.query(DesignSystemFile)
+            .filter(
+                DesignSystemFile.design_system_id == ds_id,
+                DesignSystemFile.path == validated,
+            )
+            .first()
+        )
+        if not row:
+            raise not_found
+        content = row.data
+        if content is None:
+            # Asset/font reference row: bytes live in design_system_asset. The
+            # asset must belong to the SAME design system — 404 otherwise.
+            if row.asset_id is None:
+                raise not_found
+            asset = (
+                db.query(DesignSystemAsset)
+                .filter(
+                    DesignSystemAsset.id == row.asset_id,
+                    DesignSystemAsset.design_system_id == ds_id,
+                )
+                .first()
+            )
+            if not asset:
+                raise not_found
+            content = asset.data
+        media_type = (
+            "text/plain; charset=utf-8"
+            if _is_text_source(str(row.path), str(row.mime))
+            else str(row.mime)
+        )
+        return Response(
+            content=content,
+            media_type=media_type,
+            headers={
+                "X-Content-Type-Options": "nosniff",
+                "Content-Disposition": "attachment",
+            },
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error serving file for design system {ds_id}: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to serve design system file",
+        )

{databricks_tellr_app-0.3.11.dev5 → databricks_tellr_app-0.3.11.dev7}/src/api/schemas/agent_config.py

@@ -62,6 +62,11 @@ class AgentConfig(BaseModel):
     # A selected design system compiles to prompt text and, when set, takes
     # precedence over slide_style_id (see agent_factory._get_prompt_content).
     design_system_id: Optional[int] = None
+    # Optionally pins ONE of the selected design system's templates
+    # (design_system_template.id). Meaningful only alongside design_system_id;
+    # generation IGNORES it (with a log) unless the template exists and belongs
+    # to that design system, so a stale pin can never fail a request.
+    template_id: Optional[int] = None
     deck_prompt_id: Optional[int] = None
     system_prompt: Optional[str] = None
     slide_editing_instructions: Optional[str] = None

{databricks_tellr_app-0.3.11.dev5 → databricks_tellr_app-0.3.11.dev7}/src/core/database.py

@@ -530,6 +530,9 @@ def _run_migrations(engine, schema: str | None = None):
         # --- design system: add is_active (soft-delete) to pre-existing tables ---
         _migrate_design_system_soft_delete(conn, inspector, schema, _qual, is_sqlite)
 
+        # --- design system (v1): add font_mapping_json to pre-existing tables ---
+        _migrate_design_system_font_mapping(conn, inspector, schema, _qual, is_sqlite)
+
         # --- keep newly created objects owned by the shared role (prod forks) ---
         _reassign_new_objects_to_shared_owner(conn, is_sqlite)
 
@@ -537,10 +540,14 @@ def _run_migrations(engine, schema: str | None = None):
 def _migrate_design_system_tables(conn, schema: str | None = None) -> None:
     """Create the additive design-system tables (idempotent, dialect-safe).
 
-    Phase 1 of the Design System Library. Adds three NEW tables — ``design_system``,
-    ``design_system_asset``, ``design_system_token`` — without touching
-    ``slide_style_library`` or any existing table, so the current slide-style
-    prompt path is unaffected.
+    Design System Library. Adds five NEW tables — ``design_system``,
+    ``design_system_asset``, ``design_system_token``, ``design_system_file``,
+    ``design_system_template`` — without touching ``slide_style_library`` or any
+    existing table, so the current slide-style prompt path is unaffected.
+    ``design_system_file`` (v1 Phase 1) retains bundle source files + path
+    references, and ``design_system_template`` (v1 Phase 4) makes templates
+    individually addressable; both are created AFTER their parents so their
+    foreign keys to ``design_system`` and ``design_system_asset`` resolve.
 
     ``Base.metadata.create_all()`` (run first in ``init_db``) already creates these
     on fresh installs; this hand-rolled step guarantees they also exist on
@@ -548,16 +555,24 @@ def _migrate_design_system_tables(conn, schema: str | None = None) -> None:
     exercised on its own. Creation is driven from the ORM metadata via
     ``Table.create(checkfirst=True)`` — a single source of truth for the schema,
     idempotent (a no-op when the table exists) and correctly compiled for both
-    PostgreSQL/Lakebase and the SQLite used in tests. Parent table is created
+    PostgreSQL/Lakebase and the SQLite used in tests. Parent tables are created
     first so the child foreign keys resolve.
     """
     from src.database.models.design_system import (
         DesignSystem,
         DesignSystemAsset,
+        DesignSystemFile,
+        DesignSystemTemplate,
         DesignSystemToken,
     )
 
-    for model in (DesignSystem, DesignSystemAsset, DesignSystemToken):
+    for model in (
+        DesignSystem,
+        DesignSystemAsset,
+        DesignSystemToken,
+        DesignSystemFile,
+        DesignSystemTemplate,
+    ):
         table = model.__table__
         # Match init_db()'s schema handling so a qualified deployment creates the
         # tables in the Lakebase schema; guarded so it stays a no-op on repeat.
@@ -599,6 +614,37 @@ def _migrate_design_system_soft_delete(conn, inspector, schema, _qual, is_sqlite
     ))
 
 
+def _migrate_design_system_font_mapping(conn, inspector, schema, _qual, is_sqlite) -> None:
+    """Add ``font_mapping_json`` to ``design_system`` (v1 Phase 1, idempotent).
+
+    v1 Phase 1 stores a normalized font mapping (manifest ``fonts[]`` /
+    ``brandFonts[]`` -> family/weight/style + token linkage) on the parent record.
+    ``Base.metadata.create_all()`` adds the column on fresh installs, but does NOT
+    alter a ``design_system`` table provisioned by an earlier deploy; this
+    hand-rolled ALTER backfills it. The column is nullable (a bundle may declare
+    no fonts) so no default/backfill value is required. Column existence is probed
+    with the inspector passed from ``_run_migrations`` (or a fresh one when called
+    standalone). Dialect-safe: ``JSONB`` on PostgreSQL/Lakebase, ``JSON`` (TEXT
+    affinity) on the SQLite used in tests — matching the model's ``with_variant``
+    column and the existing ``agent_config JSON`` migration.
+    """
+    from sqlalchemy import inspect, text
+
+    insp = inspector or inspect(conn)
+    try:
+        cols = {c["name"] for c in insp.get_columns("design_system", schema=schema)}
+    except Exception:
+        return
+    if not cols or "font_mapping_json" in cols:
+        return
+
+    col_type = "JSON" if is_sqlite else "JSONB"
+    logger.info("Migration: adding font_mapping_json column to design_system")
+    conn.execute(text(
+        f"ALTER TABLE {_qual('design_system')} ADD COLUMN font_mapping_json {col_type} NULL"
+    ))
+
+
 def _reassign_new_objects_to_shared_owner(
     conn, is_sqlite: bool, owning_role: str = "tellr_app_owners"
 ) -> None: