mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/attachments/routes.py

@@ -0,0 +1,326 @@
+"""The files track's HTTP routes (seam S3; documented in docs/files.mdx)."""
+
+import tempfile
+import uuid
+from pathlib import Path
+
+from ..api_errors import APIError
+from ..api_routes import Response, Route
+from ..phone_io import PhoneIOError
+from . import service
+from .store import FILE_MAX, ID, StoreError
+
+DESTINATION_APP = "app:"
+
+
+class _Copied(Exception):
+    def __init__(self, result):
+        self.result = result
+
+
+def _store(request):
+    store = service.store_for(request.runtime)
+    if store is None:
+        raise APIError("Attaching files needs Mobster's data folder. Run Mobster with its task history on.", 503,
+                       "files_unavailable")
+    return store
+
+
+def _found(store, attachment_id):
+    found = store.get(attachment_id)
+    if found is None:
+        raise APIError("That file isn't here any more. Attach it again.", 404, "attachment_not_found")
+    return found
+
+
+def _refuse(error):
+    if isinstance(error, StoreError):
+        return Response.error(str(error), error.status, error.code)
+    raise error
+
+
+def _query(request, name):
+    values = request.query.get(name) or []
+    if len(values) > 1:
+        raise ValueError(f"Supply {name} once")
+    return values[0] if values else None
+
+
+def upload(request):
+    store = _store(request)
+    name = (_query(request, "name") or "").strip()
+    if len(name) > 1024:
+        raise ValueError("That file name is too long")
+    thread = _query(request, "thread")
+    if thread is not None and not ID.fullmatch(thread):
+        raise ValueError("thread must be a conversation id")
+    try:
+        attachment = store.create(request.body or b"", name or "file", thread_id=thread)
+    except StoreError as error:
+        return _refuse(error)
+    return Response.json({"attachment": attachment.public()}, 201)
+
+
+def metadata(request):
+    store = _store(request)
+    return Response.json({"attachment": _found(store, request.params["id"]).public()})
+
+
+def content(request):
+    store = _store(request)
+    attachment = _found(store, request.params["id"])
+    path = store.path(attachment, "original")
+    if path is None:
+        raise APIError("That file's content is gone. Attach it again.", 404, "attachment_not_found")
+    mime = attachment.data.get("mime") or "application/octet-stream"
+    if attachment.kind in ("text", "csv"):
+        mime = "text/plain; charset=utf-8"  # never served as HTML, JSON or a script
+    return Response.bytes(path.read_bytes(), mime)
+
+
+def thumb(request):
+    store = _store(request)
+    attachment = _found(store, request.params["id"])
+    path = store.path(attachment, "thumb")
+    if path is None:
+        raise APIError("This file has no thumbnail.", 404, "no_thumbnail")
+    return Response.bytes(path.read_bytes(), "image/jpeg")
+
+
+def delete(request):
+    store = _store(request)
+    if not store.delete(request.params["id"]):
+        raise APIError("That file isn't here any more.", 404, "attachment_not_found")
+    return Response.json({"deleted": True})
+
+
+def _phone(request, device):
+    """(fleet phone record, PhoneFiles) for ``device`` (None: the default device)."""
+    if device is not None and (not isinstance(device, str) or not 0 < len(device) <= 128):
+        raise ValueError("device must be a device id or name")
+    record = service.device_record(request.runtime, device)
+    try:
+        return record, service.phone_files(record)
+    except PhoneIOError as error:
+        raise _phone_error(error) from None
+
+
+def _phone_error(error):
+    status = {"needs_cable": 409, "no_file_sharing": 409, "no_device": 409, "locked": 409, "not_found": 404,
+              "tools": 503, "usage": 400}.get(error.code, 502)
+    message = str(error) + (f" {error.fix}" if error.fix else "")
+    return APIError(message, status, error.code)
+
+
+def phone_list(request):
+    from .agent import file_sharing_apps
+    record, phone = _phone(request, _query(request, "device"))
+    app = _query(request, "app")
+    try:
+        out = {"device": {"id": record["id"], "name": record["name"], "kind": record["kind"]},
+               "apps": file_sharing_apps(phone)}
+        if app:
+            out["files"] = phone.ls(app)
+    except PhoneIOError as error:
+        raise _phone_error(error) from None
+    return Response.json(out)
+
+
+def phone_put(request):
+    # The user's own click in the Mac app: api_http.APP_ONLY_ROUTES needs its session, so a process holding only the
+    # token file can't put files on the phone.
+    body = request.body or {}
+    unknown = set(body) - {"device", "attachmentId", "destination"}
+    if unknown:
+        raise ValueError("Unsupported field: " + ", ".join(sorted(unknown)))
+    key = request.headers.get("Idempotency-Key")
+    if key is not None and not 0 < len(key) <= 200:
+        raise ValueError("Idempotency-Key is 1 to 200 characters")
+    store = _store(request)
+    attachment = _found(store, body.get("attachmentId") if isinstance(body.get("attachmentId"), str) else "")
+    destination = body.get("destination")
+    if not isinstance(destination, str) or not (destination in ("clipboard", "photos")
+                                                or destination.startswith(DESTINATION_APP)):
+        raise ValueError("destination is clipboard, photos or app:<bundle id>")
+    device = body.get("device")
+    if device is not None and (not isinstance(device, str) or not 0 < len(device) <= 128):
+        raise ValueError("device must be a device id or name")
+    runtime = request.runtime
+    phone = runtime.resolve_device(device)
+    key = key or uuid.uuid4().hex
+    fingerprint = {"device": phone.id, "attachmentId": attachment.id, "destination": destination}
+    earlier = store.copy_result(key, fingerprint)
+    if earlier is not None:
+        return Response.json(earlier)
+    reserved = False
+    def before_copy():
+        nonlocal reserved
+        if reserved:
+            return
+        previous = store.reserve_copy(key, fingerprint)
+        if previous is not None:
+            raise _Copied(previous)
+        reserved = True
+
+    from ..journal import JournalError, Lease
+    with runtime.lock:
+        if getattr(runtime, "closing", False):
+            raise APIError("The service is shutting down", 503, "shutting_down")
+        if runtime.run_on(phone) is not None:
+            raise APIError(f"{phone.name or 'The iPhone'} is busy with a task. Try again when it ends.", 409,
+                           "device_busy")
+        url = (runtime.config.wda_url if getattr(phone, "primary", False) else phone.wda_url) or ""
+        if not url:
+            raise APIError(f"{phone.name or 'The device'} isn't set up yet.", 409, "no_device")
+        try:
+            lease = Lease.device(url.rstrip("/"))
+        except JournalError:
+            raise APIError("Your iPhone is busy. Wait for it to finish, then try again.", 409, "device_busy") from None
+    try:
+        earlier = store.copy_result(key, fingerprint)
+        if earlier is not None:
+            return Response.json(earlier)
+        if destination == "clipboard":
+            result = _put_clipboard(request, store, attachment, phone.id, before_copy)
+        elif destination == "photos":
+            result = _put_photos(request, store, attachment, phone.id, before_copy)
+        else:
+            bundle = destination[len(DESTINATION_APP):]
+            record, files = _phone(request, phone.id)
+            original = store.path(attachment, "original")
+            if original is None:
+                raise APIError("That file's content is gone. Attach it again.", 404, "attachment_not_found")
+            try:
+                copied = files.put(bundle, original, name=attachment.name, before_copy=before_copy)
+            except PhoneIOError as error:
+                raise _phone_error(error) from None
+            result = {"status": "copied", "name": copied["name"], "path": copied["path"], "destination": destination,
+                      "device": record["id"]}
+        store.finish_copy(key, result)
+        return Response.json(result)
+    except _Copied as previous:
+        return Response.json(previous.result)
+    finally:
+        lease.close()
+
+
+def _wda(request, device):
+    """(fleet phone, call(method, path, body, timeout)) for a device's WebDriverAgent session, refused while a task runs
+    on it."""
+    import json
+    import urllib.request
+
+    from ..phone_io import checked_request
+    runtime = request.runtime
+    phone = runtime.resolve_device(device)
+    if runtime.device_busy(phone.id):
+        raise APIError(f"{phone.name or 'The iPhone'} is busy with a task. Try again when it ends.", 409,
+                       "device_busy")
+    url = (phone.wda_url or "").rstrip("/")
+    if not url:
+        raise APIError(f"{phone.name or 'The device'} isn't set up yet.", 409, "no_device")
+
+    def send(method, path, body, timeout):
+        session = phone.wda_session()
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(f"{url}/session/{session}{path}", data=data, method=method,
+                                     headers={"Content-Type": "application/json"})
+        with urllib.request.urlopen(req, timeout=timeout) as response:
+            return json.load(response)
+    return phone, checked_request(send)
+
+
+def _put_clipboard(request, store, attachment, device, before_copy):
+    """A text file onto the phone's clipboard through WebDriverAgent (any device), never while a task runs on it."""
+    from ..phone_io.clipboard import set_text
+    if attachment.kind not in ("text", "csv"):
+        raise APIError("Only a text file goes on the clipboard.", 400, "not_text")
+    phone, call = _wda(request, device)
+    text = store.whole_text(attachment)  # the file itself, never the excerpt the agent reads
+    if text is None:
+        raise APIError("That file's content is gone. Attach it again.", 404, "attachment_not_found")
+    try:
+        set_text(_copy_call(call, before_copy), text)
+    except PhoneIOError as error:
+        raise _phone_error(error) from None
+    except OSError:
+        raise APIError(f"{phone.name or 'The iPhone'} didn't answer. Keep it unlocked and connected, then try again.",
+                       502, "phone_unreachable") from None
+    return {"status": "copied", "name": attachment.name, "path": None, "destination": "clipboard",
+            "device": phone.id}
+
+
+def _put_photos(request, store, attachment, device, before_copy):
+    """A picture or video into the phone's Photos library (phone_io.photos.send: Mobster's runner saves it), never while
+    a task runs on the phone."""
+    from ..phone_io.photos import send
+    if attachment.kind != "image":
+        raise APIError("Only a photo or a video goes into Photos.", 400, "not_media")
+    original = store.path(attachment, "original")
+    if original is None:
+        raise APIError("That file's content is gone. Attach it again.", 404, "attachment_not_found")
+    phone, call = _wda(request, device)
+    try:
+        added = send(call, original, name=phone.name or "the iPhone",
+                     activate=lambda bundle: call("POST", "/wda/apps/activate", {"bundleId": bundle}, 15),
+                     before_send=before_copy)
+    except PhoneIOError as error:
+        status = {"needs_rebuild": 409, "photos_denied": 409, "photos_restricted": 409,
+                  "photos_not_determined": 409, "usage": 400}.get(error.code, 502)
+        raise APIError(str(error) + (f" {error.fix}" if error.fix else ""), status, error.code) from None
+    except OSError:
+        raise APIError(f"{phone.name or 'The iPhone'} didn't answer. Keep it unlocked and connected, then try again.",
+                       502, "phone_unreachable") from None
+    return {"status": "copied", "name": attachment.name, "path": None, "destination": "photos", "device": phone.id,
+            "kind": added["kind"]}
+
+
+def _copy_call(call, before_copy):
+    """Journal intent after local validation and read-only preflight, before the first WDA mutation."""
+    def dispatch(method, path, body=None, timeout=15):
+        if method != "GET":
+            before_copy()
+        return call(method, path, body, timeout)
+    return dispatch
+
+
+def phone_get(request):
+    from ..harness_api import post_thread_item
+    body = request.body or {}
+    unknown = set(body) - {"device", "app", "name", "threadId"}
+    if unknown:
+        raise ValueError("Unsupported field: " + ", ".join(sorted(unknown)))
+    app, name, thread = body.get("app"), body.get("name"), body.get("threadId")
+    if not isinstance(app, str) or not isinstance(name, str) or not name:
+        raise ValueError("Name the app (its bundle ID) and the file")
+    if thread is not None and (not isinstance(thread, str) or not ID.fullmatch(thread)):
+        raise ValueError("threadId must be a conversation id")
+    store = _store(request)
+    record, phone = _phone(request, body.get("device"))
+    with tempfile.TemporaryDirectory(prefix="mobster-phone-file-") as folder:
+        try:
+            saved = phone.get(app, name, Path(folder))
+        except PhoneIOError as error:
+            raise _phone_error(error) from None
+        if saved.stat().st_size > FILE_MAX:
+            raise APIError("Mobster attaches files of 25 MB or less.", 413, "too_large")
+        try:
+            attachment = store.create(saved.read_bytes(), saved.name, thread_id=thread, origin="phone")
+        except StoreError as error:
+            return _refuse(error)
+    if thread:
+        post_thread_item(thread, {"kind": "file_saved", "attachment": attachment.ref(), "app": app,
+                                  "device": record["name"]})
+    return Response.json({"attachment": attachment.public()}, 201)
+
+
+ROUTES = (
+    Route("files", "POST", "/api/attachments", upload, body="raw", max_bytes=FILE_MAX),
+    Route("files", "GET", "/api/attachments/{id}", metadata, body="none"),
+    Route("files", "GET", "/api/attachments/{id}/content", content, body="none"),
+    Route("files", "GET", "/api/attachments/{id}/thumb", thumb, body="none"),
+    Route("files", "DELETE", "/api/attachments/{id}", delete, body="none"),
+    Route("files", "GET", "/api/phone/files", phone_list, body="none"),
+    Route("files", "POST", "/api/phone/files/put", phone_put, idempotency=True),
+    Route("files", "POST", "/api/phone/files/get", phone_get),
+)

mobile_agent/attachments/service.py

@@ -0,0 +1,170 @@
+"""The attachments service per Runtime: its store, the run listener that records which task used which file, and the
+clean-up thread."""
+
+import logging
+import threading
+import weakref
+from pathlib import Path
+
+log = logging.getLogger("mobster.attachments")
+
+GC_FIRST, GC_EVERY, BUS_WAIT = 60.0, 1800.0, 5.0
+_stores = weakref.WeakKeyDictionary()
+_lock = threading.Lock()
+
+
+def store_for(runtime):
+    """The runtime's AttachmentStore, or None when it keeps no journal on disk."""
+    from .store import AttachmentStore
+    with _lock:
+        if getattr(runtime, "closing", False):
+            return None
+        found = _stores.get(runtime)
+        if found is not None:
+            return found
+        state_db = getattr(getattr(runtime, "config", None), "state_db", None)
+        journal = getattr(runtime, "journal", None)
+        if not state_db or journal is None:
+            return None
+
+        def publish(event):
+            post = getattr(runtime, "publish", None)
+            if callable(post):
+                post("attachments", event)
+
+        store = AttachmentStore(journal, Path(state_db).parent / "attachments", publish=publish,
+                                referenced=lambda: referenced(runtime))
+        try:
+            # Called under the runtime's lock (delete_run, create's retention): only note the ids here; the
+            # clean-up thread deletes what they leave unused.
+            journal.add_expiry_listener(lambda run_ids: expire_later(runtime, run_ids))
+        except Exception:  # noqa: BLE001
+            log.exception("could not listen for expired tasks")
+        _stores[runtime] = store
+        return store
+
+
+def device_record(runtime, device=None):
+    """A devices.py-shaped record of the device ``device`` names (an id, UDID or name; None: the default device), for
+    phone_io.files."""
+    phone = runtime.resolve_device(device)
+    return {"id": phone.id, "kind": phone.kind, "udid": phone.udid, "name": phone.name or phone.id,
+            "transport": getattr(phone, "transport", None), "wdaUrl": phone.wda_url}
+
+
+def phone_files(record):
+    """phone_io.files.PhoneFiles for ``record`` (tests replace this)."""
+    from ..phone_io.files import PhoneFiles
+    return PhoneFiles(record)
+
+
+def referenced(runtime):
+    """{attachment id: [run ids]} the tasks in memory name in their ``attachmentIds``."""
+    out = {}
+    lock = getattr(runtime, "lock", None)
+    if lock is None:
+        return out
+    with lock:
+        runs = list(getattr(runtime, "runs", {}).values())
+    for run in runs:
+        for identifier in (getattr(run, "extras", None) or {}).get("attachmentIds") or ():
+            out.setdefault(identifier, []).append(run.id)
+    return out
+
+
+def expire_later(runtime, run_ids):
+    """The journal's expiry listener: hand the removed tasks to the clean-up thread (there is one whenever this runtime
+    keeps any file)."""
+    cleaner = _cleaners.get(runtime)
+    if cleaner is not None and run_ids:
+        with cleaner.lock:
+            cleaner.expired.update(run_ids)
+
+
+class Cleaner:
+    def __init__(self, runtime):
+        self.runtime = runtime
+        self.stop = threading.Event()
+        self.lock = threading.Lock()
+        self.expired = set()
+        self.thread = threading.Thread(target=self._loop, name="mobster-attachments", daemon=True)
+
+    def take_expired(self):
+        with self.lock:
+            ids, self.expired = self.expired, set()
+        return ids
+
+    def _loop(self):
+        import time
+
+        from ..eventbus import bus as default_bus
+        bus = getattr(self.runtime, "bus", None) or default_bus
+        cursor = bus.position()
+        due = time.monotonic() + GC_FIRST
+        while not self.stop.is_set():
+            try:
+                events = bus.wait({"threads"}, cursor, BUS_WAIT)
+            except Exception:  # noqa: BLE001
+                events = []
+                self.stop.wait(BUS_WAIT)
+            if events and isinstance(events[-1].get("id"), str):
+                cursor = events[-1]["id"]
+            store = store_for(self.runtime) if not self.stop.is_set() else None
+            if store is None:
+                continue
+            expired = self.take_expired()
+            if expired:
+                try:
+                    store.expired(sorted(expired))
+                except Exception:  # noqa: BLE001
+                    log.exception("could not clean up the files of tasks that left history")
+            for event in events:
+                thread = event.get("thread") if isinstance(event.get("thread"), dict) else {}
+                if event.get("event") == "thread_deleted" and thread.get("id"):
+                    try:
+                        store.delete_thread(thread["id"])
+                    except Exception:  # noqa: BLE001
+                        log.exception("could not delete a conversation's files")
+            if time.monotonic() >= due:
+                due = time.monotonic() + GC_EVERY
+                try:
+                    store.gc()
+                except Exception:  # noqa: BLE001
+                    log.exception("attachment clean-up failed")
+
+
+_cleaners = weakref.WeakKeyDictionary()
+
+
+def start(runtime):
+    """register_service start: the store, and its clean-up thread once there is anything to clean (now, or at the first
+    upload)."""
+    store = store_for(runtime)
+    if store is None:
+        return
+    store.on_first_write = lambda: ensure_cleaner(runtime)
+    try:
+        kept = store.count()
+    except Exception:  # noqa: BLE001 -- a journal that can't answer starts no thread; the first upload will
+        kept = 0
+    if kept:
+        ensure_cleaner(runtime)
+
+
+def ensure_cleaner(runtime):
+    with _lock:
+        if runtime in _cleaners or getattr(runtime, "closing", False):
+            return
+        cleaner = Cleaner(runtime)
+        _cleaners[runtime] = cleaner
+    cleaner.thread.start()
+
+
+def close(runtime):
+    with _lock:
+        store = _stores.pop(runtime, None)
+        cleaner = _cleaners.pop(runtime, None)
+    if store is not None:
+        store.on_first_write = None
+    if cleaner is not None:
+        cleaner.stop.set()

mobile_agent/attachments/sniff.py

@@ -0,0 +1,152 @@
+"""What a file is, from its first bytes, never from its name: the attachment allowlist."""
+
+import json
+import os
+import re
+import unicodedata
+from dataclasses import dataclass
+
+KINDS = ("image", "pdf", "text", "csv")
+NAME_LIMIT = 120
+# Characters a name never keeps: C0/C1 controls, and the invisible marks that make a name read differently.
+_UNSAFE = re.compile(r"[\x00-\x1f\x7f-\x9f\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]")
+_HEIF_BRANDS = {b"heic", b"heix", b"hevc", b"hevx", b"heim", b"heis", b"hevm", b"hevs", b"mif1", b"msf1", b"avif"}
+
+
+class Unsupported(ValueError):
+    """The file isn't one Mobster reads. ``code``: unsupported_type."""
+
+    code = "unsupported_type"
+
+
+@dataclass(frozen=True)
+class FileType:
+    mime: str
+    kind: str        # image | pdf | text | csv
+    ext: str         # the extension Mobster stores it under (no dot)
+    label: str       # a word for people: "PDF", "PNG image", "CSV"
+
+
+IMAGE_TYPES = {
+    "image/png": FileType("image/png", "image", "png", "PNG image"),
+    "image/jpeg": FileType("image/jpeg", "image", "jpg", "JPEG image"),
+    "image/gif": FileType("image/gif", "image", "gif", "GIF image"),
+    "image/webp": FileType("image/webp", "image", "webp", "WebP image"),
+    "image/heic": FileType("image/heic", "image", "heic", "HEIC photo"),
+}
+PDF = FileType("application/pdf", "pdf", "pdf", "PDF")
+PLAIN = FileType("text/plain", "text", "txt", "Text")
+MARKDOWN = FileType("text/markdown", "text", "md", "Markdown")
+JSON_TYPE = FileType("application/json", "text", "json", "JSON")
+CSV = FileType("text/csv", "csv", "csv", "CSV")
+TSV = FileType("text/tab-separated-values", "csv", "tsv", "TSV")
+
+UNSUPPORTED = "Mobster reads images, PDFs, text and CSV files. This file is none of those."
+
+
+def image_type(head):
+    """The image type ``head`` (a file's first bytes) starts with, or None."""
+    if head.startswith(b"\x89PNG\r\n\x1a\n"):
+        return IMAGE_TYPES["image/png"]
+    if head.startswith(b"\xff\xd8\xff"):
+        return IMAGE_TYPES["image/jpeg"]
+    if head.startswith((b"GIF87a", b"GIF89a")):
+        return IMAGE_TYPES["image/gif"]
+    if head[:4] == b"RIFF" and head[8:12] == b"WEBP":
+        return IMAGE_TYPES["image/webp"]
+    if head[4:8] == b"ftyp" and head[8:12] in _HEIF_BRANDS:
+        return IMAGE_TYPES["image/heic"]
+    return None
+
+
+def is_pdf(head):
+    """A PDF's header ``%PDF-`` within its first 1 KB (some writers put junk before it, as readers allow)."""
+    return b"%PDF-" in head[:1024]
+
+
+def decode_text(data):
+    """``data`` as text, or None when it isn't UTF-8 text: it must decode, hold no NUL, and at most 1 in 1,000 of its
+    characters may be a control character other than tab, newline, carriage return or form feed."""
+    if b"\x00" in data:
+        return None
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError:
+        return None
+    if text.startswith("\ufeff"):
+        text = text[1:]
+    controls = sum(1 for ch in text if (ord(ch) < 32 and ch not in "\t\n\r\f") or ord(ch) == 127)
+    if controls > max(1, len(text) // 1000):
+        return None
+    return text
+
+
+def sniff(data, name=""):
+    """The FileType of ``data`` (the whole file), or Unsupported. The name only says which text a text file is."""
+    head = bytes(data[:4096])
+    found = image_type(head)
+    if found is not None:
+        return found
+    if is_pdf(head):
+        return PDF
+    text = decode_text(bytes(data))
+    if text is None:
+        raise Unsupported(UNSUPPORTED)
+    ext = os.path.splitext(str(name or "").lower())[1]
+    if ext == ".csv":
+        return CSV
+    if ext == ".tsv":
+        return TSV
+    if ext == ".json":
+        try:
+            json.loads(text)
+            return JSON_TYPE
+        except ValueError:
+            return PLAIN
+    if ext in (".md", ".markdown"):
+        return MARKDOWN
+    return PLAIN
+
+
+def clean_name(name, fallback="file"):
+    """A file name that is safe to show and to write anywhere: the last path part only, Unicode NFC, without control or
+    direction-override characters, spaces collapsed, never "", "." or "..", never starting with "-" or ".", at most
+    NAME_LIMIT characters with its extension kept."""
+    text = unicodedata.normalize("NFC", str(name or ""))
+    text = text.replace("\\", "/").rsplit("/", 1)[-1]
+    text = _UNSAFE.sub("", text)
+    text = " ".join(text.split()).strip(" .")
+    text = text.lstrip("-").strip()
+    if not text or text in (".", ".."):
+        text = fallback
+    if len(text) > NAME_LIMIT:
+        stem, ext = os.path.splitext(text)
+        ext = ext if len(ext) <= 12 else ""
+        text = stem[:NAME_LIMIT - len(ext)].rstrip(" .") + ext
+    return text
+
+
+def with_extension(name, file_type):
+    """``name`` ending in an extension that matches ``file_type`` (``scan`` + PDF -> ``scan.pdf``); a name that already
+    has a fitting one keeps it (``photo.jpeg`` stays)."""
+    stem, ext = os.path.splitext(name)
+    ext = ext.lower().lstrip(".")
+    fitting = {"jpg": {"jpg", "jpeg"}, "heic": {"heic", "heif"}, "txt": {"txt", "text", "log", ""},
+               "md": {"md", "markdown"}, "csv": {"csv"}, "tsv": {"tsv"}, "json": {"json"}}
+    if ext == file_type.ext or ext in fitting.get(file_type.ext, set()):
+        return name if ext or file_type.kind not in ("image", "pdf") else f"{name}.{file_type.ext}"
+    if file_type.kind == "text" and file_type.ext == "txt":
+        return name  # a .log or .yaml file keeps its name; it is read as plain text
+    return clean_name(f"{name}.{file_type.ext}")
+
+
+def size_words(count):
+    """``412 KB``, ``3.4 MB``: a file's size for people (1 KB = 1,000 bytes, as Finder counts)."""
+    count = int(count or 0)
+    if count < 1000:
+        return f"{count} byte" + ("" if count == 1 else "s")
+    for unit, step in (("KB", 1e3), ("MB", 1e6), ("GB", 1e9)):
+        value = count / step
+        if value < 999.5 or unit == "GB":
+            return f"{value:.0f} {unit}" if value >= 10 or unit == "KB" else f"{value:.1f} {unit}"
+    return f"{count} bytes"