databricks-tellr-app 0.4.2.dev9__tar.gz → 0.4.2.dev11__tar.gz

{databricks_tellr_app-0.4.2.dev9 → databricks_tellr_app-0.4.2.dev11}/PKG-INFO

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

{databricks_tellr_app-0.4.2.dev9 → databricks_tellr_app-0.4.2.dev11}/databricks_tellr_app.egg-info/PKG-INFO

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

{databricks_tellr_app-0.4.2.dev9 → databricks_tellr_app-0.4.2.dev11}/pyproject.toml

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

{databricks_tellr_app-0.4.2.dev9 → databricks_tellr_app-0.4.2.dev11}/src/api/routes/settings/design_systems.py

@@ -172,6 +172,28 @@ class DesignSystemDetail(DesignSystemSummary):
     assets: List[AssetOut]
 
 
+class ImportWarningOut(BaseModel):
+    """One bundle entry the import ignored, and why."""
+    path: str
+    reason: str
+
+
+class DesignSystemImportResult(DesignSystemDetail):
+    """The /import response: the imported detail PLUS anything that was ignored.
+
+    Additive by design. Some entries are individually unusable without making the
+    bundle unusable (an unsniffable template screenshot, a non-UTF-8 token source);
+    those are dropped so one junk file cannot cost the whole upload. Reporting them
+    only to the server log told the user the import had succeeded and left them to
+    discover a missing thumbnail themselves.
+
+    A NON-FATAL list on a 201, and its own model rather than a field on
+    :class:`DesignSystemDetail`, so the GET/create/update responses are byte-for-byte
+    unchanged and an existing /import client simply ignores a field it does not read.
+    """
+    warnings: List[ImportWarningOut] = []
+
+
 class DesignSystemCreate(BaseModel):
     """Structured (in-app) create — thin. Assets arrive via /import."""
     # UNCAPPED, matching the unbounded ``design_system.name`` column; ``min_length``
@@ -496,7 +518,11 @@ def list_design_systems(
         )
 
 
-@router.post("/import", response_model=DesignSystemDetail, status_code=status.HTTP_201_CREATED)
+@router.post(
+    "/import",
+    response_model=DesignSystemImportResult,
+    status_code=status.HTTP_201_CREATED,
+)
 async def import_design_system(
     file: UploadFile = File(...),
     name: Optional[str] = Form(None),
@@ -517,14 +543,23 @@ async def import_design_system(
             detail=f"Upload exceeds the maximum bundle size of {MAX_BUNDLE_SIZE_BYTES} bytes",
         )
     try:
+        # Filled with the entries the import dropped without failing, so the caller
+        # learns about them instead of only the server log doing so.
+        dropped: list[design_system_service.BundleImportWarning] = []
         ds = design_system_service.import_bundle(
             db,
             zip_bytes=content,
             user=_current_user(),
             name_override=name,
             source_filename=file.filename,
+            warnings=dropped,
+        )
+        return DesignSystemImportResult(
+            **_detail(ds).model_dump(),
+            warnings=[
+                ImportWarningOut(path=w.path, reason=w.reason) for w in dropped
+            ],
         )
-        return _detail(ds)
     except DesignSystemNameConflictError as e:
         db.rollback()
         raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(e))

{databricks_tellr_app-0.4.2.dev9 → databricks_tellr_app-0.4.2.dev11}/src/services/design_system_service.py

@@ -11,9 +11,13 @@ Lakebase rows:
   custom properties are parsed as an ADDITIONAL token source.
 - ``fonts/**`` and ``assets/**`` — binary files stored as ``design_system_asset``
   rows (bytes in-DB, following the ``image_assets`` pattern). ``preview*`` files
-  under ``assets/`` are reference-only and skipped; a template folder's
-  ``templates/<folder>/preview.*`` screenshot IS stored (kind ``template_shot``,
-  v1 Phase 4) so the template picker can serve thumbnails.
+  under ``assets/`` are reference-only and skipped; a template folder's screenshot
+  IS stored (kind ``template_shot``, v1 Phase 4) so the template picker can serve
+  thumbnails. Both shipped shapes count: ``templates/<folder>/preview.<ext>`` and
+  the DOT-PREFIXED, EXTENSION-LESS ``templates/<folder>/.thumbnail`` a real export
+  writes — the latter is allowlisted past the general dotfile skip and has its
+  media type SNIFFED from its magic bytes (unknown content is refused, never
+  stored under a guessed type).
 
 v1 Phase 1 ("import foundation") extends the importer WITHOUT changing the
 generation seam:
@@ -55,7 +59,7 @@ import logging
 import mimetypes
 import re
 import zipfile
-from typing import Any, Optional
+from typing import Any, NamedTuple, Optional
 
 from sqlalchemy.orm import Session, defer
 
@@ -74,6 +78,22 @@ logger = logging.getLogger(__name__)
 MANIFEST_FILENAME = "_ds_manifest.json"
 DEFAULT_CSS_TOKEN_SOURCE = "colors_and_type.css"
 
+
+class BundleImportWarning(NamedTuple):
+    """A bundle entry the import DROPPED without failing the upload.
+
+    Some entries are individually unusable without making the bundle unusable — an
+    unsniffable template screenshot, a CSS token source that is not UTF-8. Dropping
+    just that entry is right (one junk file must not cost the whole upload), but the
+    caller was then told the import succeeded with nothing to say a file had been
+    ignored, so the only record was a server-side log the user cannot see. These ride
+    back on the import response instead.
+    """
+
+    path: str
+    reason: str
+
+
 # Color sub-groups the compiler renders as :root vars. A token name whose first
 # segment is one of these carries its group in the name (e.g. --brand-accents-lava).
 _COLOR_SUBGROUPS = frozenset(("core", "accents", "ink", "tints"))
@@ -276,21 +296,89 @@ def _infer_asset_kind(rel_path: str) -> str:
 # raster-image extension) — stored as a ``template_shot`` asset so the Phase 4
 # template picker can serve thumbnails. Checked BEFORE ``_should_skip`` (which
 # excludes ``templates/**`` from generic asset storage).
+#
+# Anchored with ``\Z``, NOT ``$``: in Python ``$`` matches at the end of the string
+# OR immediately before a single trailing newline, so a ``$``-anchored allowlist on
+# a PATH accepts ``<allowed shape>\n`` — ``templates/x/preview.png\n`` was matched,
+# stored, and served. ``\Z`` is the true end of string. Applies to every allowlist
+# regex in this module that judges a path or a filename.
 _TEMPLATE_PREVIEW_RE = re.compile(
-    r"^templates/[^/]+/preview[^/]*\.(png|jpe?g|gif|webp)$", re.IGNORECASE
+    r"^templates/[^/]+/preview[^/]*\.(png|jpe?g|gif|webp)\Z", re.IGNORECASE
 )
 
+# The SAME screenshot as it actually ships in a real export: DOT-PREFIXED, named
+# ``thumbnail`` rather than ``preview``, and carrying NO file extension —
+# ``templates/<folder>/.thumbnail``. Every one of those was discarded, so a real
+# bundle imported with no thumbnail at all and a NULL ``thumbnail_url``.
+#
+# Deliberately the NARROWEST path shape that describes them: exactly one folder
+# segment under ``templates/``, an optional single leading dot, one of the two
+# known basenames, and NOTHING else — no extension, no suffix. It is this
+# tightness that makes it safe for :func:`_iter_safe_entries` to exempt a match
+# from the general dotfile skip; a dotfile anywhere else stays skipped. Because
+# a match carries no extension, its media type is NOT guessable from the name and
+# is sniffed from the content instead (:func:`_sniff_raster_mime`).
+# ``\Z`` for the same reason as _TEMPLATE_PREVIEW_RE: with ``$`` this accepted
+# ``templates/x/.thumbnail\n``, which was then stored AND linked as a template's
+# thumbnail_url.
+_TEMPLATE_THUMBNAIL_RE = re.compile(
+    r"^templates/[^/]+/\.?(thumbnail|preview)\Z", re.IGNORECASE
+)
+
+# Magic-byte signatures for the raster formats a template thumbnail may be. An
+# extension-less file is stored ONLY if its bytes match one of these; unknown
+# content is refused rather than persisted under a guessed content type. SVG is
+# absent on purpose (it can carry inline script and has no magic number).
+_PNG_MAGIC = b"\x89PNG\r\n\x1a\n"
+_JPEG_MAGIC = b"\xff\xd8\xff"
+_GIF_MAGICS = (b"GIF87a", b"GIF89a")
+
+
+def _sniff_raster_mime(data: bytes) -> Optional[str]:
+    """MIME type from an image's MAGIC BYTES, or ``None`` if not a known raster.
+
+    Content-based detection for files whose name carries no extension. WebP is a
+    RIFF container, so ``RIFF`` alone is not enough — the form type at bytes 8:12
+    must spell ``WEBP``, otherwise a RIFF/WAVE file would be stored as an image.
+    """
+    if data.startswith(_PNG_MAGIC):
+        return "image/png"
+    if data.startswith(_JPEG_MAGIC):
+        return "image/jpeg"
+    if data.startswith(_GIF_MAGICS):
+        return "image/gif"
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "image/webp"
+    return None
+
+
+def _is_template_thumbnail(rel_path: str) -> bool:
+    """True for an EXTENSION-LESS template screenshot (``templates/x/.thumbnail``).
+
+    Distinguished from :func:`_is_template_preview` because the absence of an
+    extension is what forces content sniffing.
+    """
+    return bool(_TEMPLATE_THUMBNAIL_RE.match(rel_path.lower()))
+
 
 def _is_template_preview(rel_path: str) -> bool:
-    return bool(_TEMPLATE_PREVIEW_RE.match(rel_path.lower()))
+    """True for a template folder's screenshot in EITHER shipped shape."""
+    low = rel_path.lower()
+    return bool(_TEMPLATE_PREVIEW_RE.match(low)) or bool(
+        _TEMPLATE_THUMBNAIL_RE.match(low)
+    )
 
 
 def _should_skip(rel_path: str) -> bool:
     """Only ``assets/**`` and ``fonts/**`` files are stored; skip everything else.
 
     Directories, OS junk, dotfiles, template screenshots and ``preview*`` files
-    (reference-only material) are excluded. Template-folder preview thumbnails
-    are the exception — the caller checks :func:`_is_template_preview` first.
+    (reference-only material) are excluded. Template-folder screenshots are the
+    exception — the caller checks :func:`_is_template_preview` first.
+
+    NOTE: this is not the FIRST gate an entry passes. ``_iter_safe_entries`` runs
+    upstream and applies its own dotfile skip, so a dot-prefixed screenshot has to
+    be allowlisted THERE as well or it never reaches this function at all.
     """
     low = rel_path.lower()
     base = _basename(low)
@@ -500,12 +588,20 @@ def import_bundle(
     user: Optional[str],
     name_override: Optional[str] = None,
     source_filename: Optional[str] = None,
+    warnings: Optional[list[BundleImportWarning]] = None,
 ) -> DesignSystem:
     """Import a ``.zip`` design-system bundle into Lakebase and compile it.
 
     Returns the persisted :class:`DesignSystem` (committed, with tokens + assets +
     ``compiled_style_content``).
 
+    Args:
+        warnings: optional collector. Pass a list to receive an
+            :class:`BundleImportWarning` for every entry the import DROPPED without
+            failing — the caller can then tell the user which files were ignored and
+            why. Omitting it keeps the previous signature working for the many
+            callers that only want the design system.
+
     Raises:
         DesignSystemImportError: bundle is not a zip, missing/invalid manifest, or
             violates a size limit (HTTP 400).
@@ -563,8 +659,10 @@ def import_bundle(
         # Read the DECLARED CSS token sources ONCE (budgeted); the same bytes are
         # reused for both token parsing and source-file retention (no double-charge).
         css_sources = _read_css_sources(zf, root_prefix, manifest, budget)
-        tokens = _collect_tokens(manifest, _decode_css_texts(css_sources))
-        assets, files = _collect_assets_and_files(zf, root_prefix, budget, css_sources)
+        tokens = _collect_tokens(manifest, _decode_css_texts(css_sources, warnings))
+        assets, files = _collect_assets_and_files(
+            zf, root_prefix, budget, css_sources, warnings
+        )
 
     # Stored VERBATIM; the strip decides only whether the brand wrote a description
     # at all (a whitespace-only one describes nothing, so it stays NULL). Same split
@@ -913,7 +1011,10 @@ def _read_css_sources(
     return result
 
 
-def _decode_css_texts(css_sources: "dict[str, bytes]") -> list[str]:
+def _decode_css_texts(
+    css_sources: "dict[str, bytes]",
+    warnings: "Optional[list[BundleImportWarning]]" = None,
+) -> list[str]:
     """Decode the pre-read CSS source bytes to UTF-8 text (skip undecodable)."""
     texts: list[str] = []
     for path, raw in css_sources.items():
@@ -921,31 +1022,98 @@ def _decode_css_texts(css_sources: "dict[str, bytes]") -> list[str]:
             texts.append(raw.decode("utf-8"))
         except UnicodeDecodeError:
             logger.warning("Skipping non-UTF-8 CSS token source: %s", path)
+            if warnings is not None:
+                warnings.append(
+                    BundleImportWarning(
+                        path,
+                        "not valid UTF-8; its design tokens were not read.",
+                    )
+                )
     return texts
 
 
 def _safe_relpath(rel_path: str) -> Optional[str]:
-    """Normalize a bundle-relative path; return ``None`` if it is unsafe (zip-slip).
-
-    Rejects absolute paths (POSIX ``/`` or a Windows drive) and any path that
-    escapes the bundle root via a ``..`` segment. Backslashes are normalized to
-    ``/`` and ``.``/empty segments are collapsed. Assets are stored as DB bytes
-    (never written to disk), so this is defence-in-depth — and it keeps the
-    persisted ``design_system_file.path`` values safe for the later file browser.
+    """The CANONICAL form of a bundle-relative FILE path, or ``None`` to REFUSE it.
+
+    VALIDATION, not laundering: a path is already canonical or it is refused. It is
+    never rewritten into an acceptable form, because rewriting changes the very
+    thing later rules are about to judge. ``assets/innocent/.`` used to normalize to
+    ``assets/innocent`` — losing the ``.`` basename that made it junk — and the
+    entry was stored under a path that was not its own name. Two entries could also
+    collapse onto ONE identity (``assets/./x``, ``assets//x`` and ``assets/x`` all
+    became ``assets/x``), leaving which bytes win to zip ordering.
+
+    Refused: an empty name, a C0/DEL control character (``\\n`` and NUL among them,
+    so no rule downstream has to cope with one), an absolute path (POSIX ``/`` or a
+    Windows drive), and any ``.``, ``..`` or EMPTY segment. Backslashes are still
+    folded to ``/`` first, which is the one tolerance kept deliberately: zips written
+    on Windows use them as separators, and folding cannot erase a segment or change a
+    basename's junk-ness the way the collapses above did.
+
+    A trailing-slash DIRECTORY marker is not a file path and is refused here; callers
+    reach the directory case through :func:`_classify_bundle_entry`, which strips the
+    marker and validates the path it names.
+
+    This is the contract the file browser already relies on: stored
+    ``design_system_file.path`` values are canonical by construction, so
+    ``_validated_file_path`` can reject a non-canonical REQUEST instead of
+    normalizing it into an accepted one.
     """
     if not rel_path:
         return None
     normalized = rel_path.replace("\\", "/")
+    if any(ord(ch) < 0x20 or ord(ch) == 0x7F for ch in normalized):
+        return None
     if normalized.startswith("/") or re.match(r"^[A-Za-z]:", normalized):
         return None
-    parts: list[str] = []
-    for segment in normalized.split("/"):
-        if segment in ("", "."):
-            continue
-        if segment == "..":
-            return None
-        parts.append(segment)
-    return "/".join(parts) if parts else None
+    if any(segment in ("", ".", "..") for segment in normalized.split("/")):
+        return None
+    return normalized
+
+
+# The verdict :func:`_classify_bundle_entry` reaches for one zip entry.
+_ENTRY_REFUSE = "refuse"  # unsafe — reject the whole bundle
+_ENTRY_SKIP = "skip"      # legitimate but never stored (directory, OS junk, dotfile)
+_ENTRY_FILE = "file"      # store it, under the canonical path returned alongside
+
+
+def _classify_bundle_entry(rel_path: str) -> tuple[str, Optional[str]]:
+    """THE decision for one bundle entry: refuse it, skip it, or store it.
+
+    ONE place that canonicalizes and then applies EVERY rule. Both gates that judge
+    bundle paths call this — the up-front whole-bundle scan
+    (:func:`_assert_bundle_paths_safe`) and the per-entry iterator
+    (:func:`_iter_safe_entries`) — so they cannot disagree about a path shape, and a
+    new rule cannot be added to one and forgotten in the other. They used to decide
+    separately and DID disagree: the scan refused ``assets/innocent/.`` on its raw
+    basename while the iterator accepted the same entry on its normalized one, and
+    the permissive gate was the one that reached storage.
+
+    Returns ``(verdict, canonical_path)``; the path is set only for ``_ENTRY_FILE``.
+    """
+    if rel_path.endswith("/"):
+        # A directory marker. It is never stored, but the path it NAMES still has to
+        # be canonical, so '../evil/' is refused rather than skipped.
+        return (
+            (_ENTRY_SKIP, None)
+            if _safe_relpath(rel_path[:-1]) is not None
+            else (_ENTRY_REFUSE, None)
+        )
+    canonical = _safe_relpath(rel_path)
+    if canonical is None:
+        return _ENTRY_REFUSE, None
+    low = canonical.lower()
+    if low.startswith("__macosx/") or "/__macosx/" in low:
+        return _ENTRY_SKIP, None
+    base = _basename(low)
+    # The ONE dot-prefixed shape the importer stores is a template folder's
+    # screenshot; every other dotfile stays skipped. Tested against the CANONICAL
+    # path — the same string the recognizer sees downstream.
+    if (base == ".ds_store" or base.startswith(".")) and not _is_template_preview(
+        canonical
+    ):
+        return _ENTRY_SKIP, None
+    return _ENTRY_FILE, canonical
 
 
 def _is_symlink(info: zipfile.ZipInfo) -> bool:
@@ -966,8 +1134,11 @@ def _assert_bundle_paths_safe(zf: zipfile.ZipFile) -> None:
     root-prefix scoping — so a malicious entry that falls OUTSIDE the bundle root
     (e.g. ``../evil.png`` when the manifest sits under ``safe/``) is REJECTED, not
     silently skipped. EVERY entry is checked (no exemption for empty or ``.``-only
-    names): absolute paths, ``..`` traversal, and empty/invalid names are refused,
-    and symlink entries are refused before any bytes are read.
+    names): absolute paths, ``..`` traversal, control characters, and empty/invalid
+    names are refused, and symlink entries are refused before any bytes are read.
+
+    The path verdict comes from :func:`_classify_bundle_entry`, the SAME classifier
+    :func:`_iter_safe_entries` uses, so the two gates cannot disagree about a shape.
     """
     for info in zf.infolist():
         name = info.filename
@@ -975,12 +1146,12 @@ def _assert_bundle_paths_safe(zf: zipfile.ZipFile) -> None:
             raise DesignSystemImportError(
                 f"Bundle entry '{name}' is a symlink; refusing to import."
             )
-        # No ``if name`` guard: an empty (or ``.``-only) name also fails
-        # ``_safe_relpath`` and must be rejected, not skipped.
-        if _safe_relpath(name) is None:
+        # No ``if name`` guard: an empty (or ``.``-only) name is also refused, not
+        # skipped.
+        if _classify_bundle_entry(name)[0] == _ENTRY_REFUSE:
             raise DesignSystemImportError(
-                f"Bundle contains an unsafe path '{name}' (empty, absolute, or "
-                "parent-directory traversal); refusing to import."
+                f"Bundle contains an unsafe path '{name}' (empty, absolute, "
+                "non-canonical, or parent-directory traversal); refusing to import."
             )
 
 
@@ -990,26 +1161,34 @@ def _iter_safe_entries(zf: zipfile.ZipFile, root_prefix: str):
     Skips directories, OS junk (``__MACOSX``, ``.DS_Store``) and dotfiles. Raises
     :class:`DesignSystemImportError` on a zip-slip path (absolute or ``..``) so a
     malicious bundle is rejected rather than silently stored.
+
+    This is the ACTUAL first gate every entry passes, so the ONE dot-prefixed shape
+    the importer stores — a template folder's ``.thumbnail`` screenshot
+    (:func:`_is_template_preview`) — is allowlisted HERE too. Without that a fix to
+    the recognizer alone reads as working in a unit test and still drops every real
+    thumbnail, because the entry never reaches the recognizer.
+
+    Every path rule lives in :func:`_classify_bundle_entry` — the same classifier the
+    up-front scan uses — so an entry is judged on its CANONICAL path and neither gate
+    can be patched into disagreeing with the other. Stripping ``root_prefix`` is the
+    only work done here, and it is bookkeeping rather than a path rule.
     """
     for info in zf.infolist():
         name = info.filename
         if not name.startswith(root_prefix):
             continue
         rel_raw = name[len(root_prefix):]
-        if not rel_raw or rel_raw.endswith("/"):
-            continue  # directory entry
-        low = rel_raw.lower()
-        if low.startswith("__macosx/") or "/__macosx/" in low:
-            continue
-        base = _basename(low)
-        if base == ".ds_store" or base.startswith("."):
-            continue
-        safe = _safe_relpath(rel_raw)
-        if safe is None:
+        if not rel_raw:
+            continue  # the root-prefix directory entry itself
+        verdict, safe = _classify_bundle_entry(rel_raw)
+        if verdict == _ENTRY_REFUSE:
             raise DesignSystemImportError(
-                f"Bundle contains an unsafe path '{rel_raw}' (absolute path or "
-                "parent-directory traversal); refusing to import."
+                f"Bundle contains an unsafe path '{rel_raw}' (absolute path, "
+                "non-canonical path, or parent-directory traversal); refusing to "
+                "import."
             )
+        if safe is None:  # _ENTRY_SKIP
+            continue
         yield info, safe
 
 
@@ -1128,6 +1307,7 @@ def _collect_assets_and_files(
     root_prefix: str,
     budget: "_SizeBudget",
     css_sources: "dict[str, bytes]",
+    warnings: "Optional[list[BundleImportWarning]]" = None,
 ) -> tuple[list[DesignSystemAsset], list[DesignSystemFile]]:
     """Read a bundle into asset rows + file rows in one safety-checked pass.
 
@@ -1176,8 +1356,37 @@ def _collect_assets_and_files(
             # Size-checked read: the declared size is validated BEFORE
             # materialisation (bomb guard).
             data = budget.read_info(zf, info)
-            mime = _guess_mime(rel)
             kind = "template_shot" if _is_template_preview(rel) else _infer_asset_kind(rel)
+            if _is_template_thumbnail(rel):
+                # No extension to guess from, so the type comes from the CONTENT.
+                # Unrecognized bytes are REFUSED rather than stored as
+                # application/octet-stream: a thumbnail is served back to the
+                # browser, so its declared type has to be one we actually verified.
+                # Only THIS entry is dropped — a bundle import is one request, and
+                # one junk screenshot must not cost the whole upload.
+                sniffed = _sniff_raster_mime(data)
+                if sniffed is None:
+                    logger.warning(
+                        "Bundle entry '%s' is not a PNG/JPEG/GIF/WebP image "
+                        "(%d bytes); not stored as a template thumbnail",
+                        rel,
+                        len(data),
+                    )
+                    # A server-side log alone left the user believing the import was
+                    # complete; the same fact rides back on the response.
+                    if warnings is not None:
+                        warnings.append(
+                            BundleImportWarning(
+                                rel,
+                                "not a PNG, JPEG, GIF or WebP image "
+                                f"({len(data)} bytes); this template's thumbnail "
+                                "was not stored.",
+                            )
+                        )
+                    continue
+                mime = sniffed
+            else:
+                mime = _guess_mime(rel)
             width, height = _image_dimensions(data, mime)
             asset = DesignSystemAsset(
                 kind=kind,

{databricks_tellr_app-0.4.2.dev9 → databricks_tellr_app-0.4.2.dev11}/src/services/design_system_templates.py

@@ -606,9 +606,37 @@ def _entry_path_candidates(entry: dict) -> list[str]:
     return out
 
 
+#: Basenames a template folder's screenshot ships under, with or without a leading
+#: dot and with or without an extension: the documented ``preview.png`` and the
+#: ``.thumbnail`` a real export actually writes. Matching only ``preview*`` left
+#: every real bundle's ``thumbnail_url`` NULL even once the importer stored the
+#: bytes — the importer and this lookup are two separate gates on the same file.
+_THUMBNAIL_BASENAME_PREFIXES = ("preview", "thumbnail")
+
+
+def _is_thumbnail_basename(basename: str) -> bool:
+    """True for a screenshot basename, with or without a leading dot.
+
+    A PREFIX match on purpose, matching the breadth of the importer's
+    ``preview[^/]*\\.<ext>`` shape. A C0/DEL control character is refused outright:
+    the prefix test alone says nothing about what TRAILS the basename, and this is
+    the third gate on the same file — the importer now refuses such a path, so this
+    is defence in depth that no longer depends on the importer for the property.
+    """
+    if any(ord(ch) < 0x20 or ord(ch) == 0x7F for ch in basename):
+        return False
+    return basename.lstrip(".").startswith(_THUMBNAIL_BASENAME_PREFIXES)
+
+
 def _find_thumbnail_asset_id(files: list[Any], template_dir: str) -> Optional[int]:
-    """The template folder's ``preview*`` screenshot: the smallest-path image
-    reference row under ``template_dir`` whose basename starts with ``preview``."""
+    """The template folder's screenshot: the smallest-path image reference row
+    under ``template_dir`` whose basename names a preview or a thumbnail.
+
+    Smallest path is the tie-break when a folder ships more than one, so the choice
+    is deterministic. The ``image/*`` requirement is what keeps a non-image file
+    named ``thumbnail`` out: the importer only records a verified, sniffed media
+    type on these rows.
+    """
     previews: list[tuple[str, int]] = []
     for ds_file in files:
         asset_id = getattr(ds_file, "asset_id", None)
@@ -619,7 +647,7 @@ def _find_thumbnail_asset_id(files: list[Any], template_dir: str) -> Optional[in
             continue
         basename = path.rsplit("/", 1)[-1].lower()
         mime = (getattr(ds_file, "mime", "") or "").lower()
-        if basename.startswith("preview") and mime.startswith("image/"):
+        if _is_thumbnail_basename(basename) and mime.startswith("image/"):
             previews.append((path, asset_id))
     return min(previews)[1] if previews else None