scootcli 0.1.0__py3-none-any.whl

scootcli/config.py

@@ -0,0 +1,241 @@
+"""Configuration: ``.env`` files + environment + defaults with a clear precedence.
+
+Precedence (highest wins):
+  CLI flag → environment variable → project ``.env`` → global ``~/.config/scoot/.env`` → default.
+
+Two optional ``.env`` files are read: the global one in scoot's config home, and the nearest ``.env``
+found walking up from the current directory (so a repo-root file applies from any subdirectory).
+Only scoot's own keys are imported from them: ``SCOOT_*``, the providers' API-key variables
+(``OPENAI_API_KEY``, ...), and the proxy variables. A project's other secrets never enter scoot's
+process through a ``.env`` file.
+
+The CLI-flag layer is applied by the caller (``cli.py``) via :meth:`Config.override`; this module
+handles the lower layers.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+# No proxy by default (set HTTPS_PROXY / --proxy when one is required).
+DEFAULT_PROXY = ""
+
+
+# scoot's own config dir + securely-stored provider API keys (written by ``scoot auth set``).
+SCOOT_CONFIG_DIR = Path.home() / ".config/scoot"
+CREDENTIALS_FILE = SCOOT_CONFIG_DIR / "credentials.json"
+# Persisted user preferences (e.g. the chosen model) — survives across launches.
+PREFERENCES_FILE = SCOOT_CONFIG_DIR / "preferences.json"
+
+# scoot session persistence: auto-saved conversations for --continue / --resume (see PLAN §14).
+STATE_DIR = Path.home() / ".local/state/scoot"
+SESSION_RETENTION = 20  # keep only the most recent N sessions on disk
+
+
+def _config_home() -> Path:
+    """User config dir for scoot (honours XDG_CONFIG_HOME)."""
+    base = os.environ.get("XDG_CONFIG_HOME") or (Path.home() / ".config")
+    return Path(base) / "scoot"
+
+
+ENV_FILE_NAME = ".env"
+_PROXY_KEYS = ("HTTPS_PROXY", "https_proxy", "NO_PROXY", "no_proxy")
+
+
+def global_env_path() -> Path:
+    """``~/.config/scoot/.env`` (honours ``XDG_CONFIG_HOME``): the stable place for keys."""
+    return _config_home() / ENV_FILE_NAME
+
+
+def find_project_env(start: Path) -> Optional[Path]:
+    """The nearest ``.env`` in ``start`` or an ancestor directory, or ``None``."""
+    home = _config_home()
+    for directory in (start, *start.parents):
+        candidate = directory / ENV_FILE_NAME
+        if candidate.is_file() and candidate != home / ENV_FILE_NAME:
+            return candidate
+    return None
+
+
+def env_files(start: Path) -> List[Path]:
+    """Existing env files in *load order*: project first, then global.
+
+    Loading never overrides a variable that is already set, so the project file wins over the global
+    one, and the real environment wins over both.
+    """
+    files: List[Path] = []
+    project = find_project_env(start)
+    if project is not None:
+        files.append(project)
+    glob = global_env_path()
+    if glob.is_file() and glob not in files:
+        files.append(glob)
+    return files
+
+
+def allowed_env_key(key: str) -> bool:
+    """Whether a ``.env`` key is scoot's business: ``SCOOT_*``, provider API keys, proxy settings."""
+    if key.startswith("SCOOT_") or key in _PROXY_KEYS:
+        return True
+    try:
+        from .providers import registry
+
+        return any(key in spec.key_env for spec in registry.all_specs())
+    except Exception:
+        return False
+
+
+def load_dotenv(env_path: Path, allow=allowed_env_key) -> List[str]:
+    """Import allowed ``KEY=VALUE`` lines into ``os.environ`` (never overriding); return imported keys.
+
+    Accepts an optional ``export`` prefix and single or double quotes around the value.
+    """
+    imported: List[str] = []
+    try:
+        lines = env_path.read_text().splitlines()
+    except OSError:
+        return imported
+    for line in lines:
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        if line.startswith("export "):
+            line = line[len("export "):].lstrip()
+        key, _, value = line.partition("=")
+        key = key.strip()
+        if not key or not allow(key):
+            continue
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+            value = value[1:-1]
+        if key not in os.environ:
+            os.environ[key] = value
+            imported.append(key)
+    return imported
+
+
+def _as_bool(value: str) -> bool:
+    return value.strip().lower() not in ("false", "0", "no", "off", "")
+
+
+DEFAULT_MODEL_ALIAS = "default"  # the default provider's preferred model (gpt-5.3-codex on OpenAI)
+AUTO_MODEL_ALIAS = "auto"        # opt-in: pick a model per turn from the live list (routing seed)
+
+
+def is_model_alias(model: Optional[str]) -> bool:
+    return (model or "").strip().lower() in (DEFAULT_MODEL_ALIAS, AUTO_MODEL_ALIAS, "")
+
+
+def _resolve_model_setting(model_env: Optional[str]) -> str:
+    """Model precedence (below the CLI flag, applied later): SCOOT_MODEL → saved pref → default."""
+    if model_env:
+        return model_env
+    try:
+        from .preferences import get_model
+
+        return get_model() or DEFAULT_MODEL_ALIAS
+    except Exception:
+        return DEFAULT_MODEL_ALIAS
+
+
+def _resolve_logo_setting(logo_env: Optional[str]) -> bool:
+    """Mascot on/off precedence (below the --no-logo flag): SCOOT_LOGO env → saved pref → on."""
+    if logo_env is not None and logo_env.strip() != "":
+        return _as_bool(logo_env)
+    try:
+        from .preferences import get_logo
+
+        saved = get_logo()
+        return True if saved is None else saved
+    except Exception:
+        return True
+
+
+@dataclass(frozen=True)
+class Config:
+    """Resolved runtime configuration."""
+
+    proxy: str = DEFAULT_PROXY
+    provider: str = ""  # default provider name; empty → first provider with a key, else ollama
+    model: str = DEFAULT_MODEL_ALIAS  # "default" | "auto" | a model id, ideally provider/model
+    effort: str = "medium"  # reasoning effort for models that take it: low | medium | high | xhigh
+    timeout: int = 120
+    max_steps: int = 50
+    compact_at: int = 100000
+    approval: str = "yolo"
+    root: Path = Path.cwd()
+    verbose: bool = False
+    stream: bool = True  # stream tokens live (SSE) when the UI/terminal supports it
+    panel: bool = True  # show the persistent bottom status bar in the REPL (TTY only)
+    dock: bool = True  # pin the prompt to a fixed bottom row; output scrolls above it (TTY only)
+    resume: str = "auto"  # launch resume policy: hint (show last) | auto (reload last) | off
+    workspace_context: bool = True  # inject a compact repo map (git + tree) into the agent prompt
+    labels: bool = True  # show role labels/gutters (❯ you / ⏺ scoot) in the REPL transcript
+    verbosity: str = "full"  # feed detail: full (tool log) | compact (transient tool line) | quiet (no reasoning)
+    images: bool = True  # detect dropped image paths + describe them with a vision model (M22)
+    vision_model: str = "auto"  # provider/model for image descriptions, or "auto" → pick a capable one
+    image_max_bytes: int = 4 * 1024 * 1024  # per-image cap (no downscale without a 3rd-party lib)
+    env_files: Tuple[str, ...] = ()  # the .env files that were read, in load order (shown by /status)
+    logo: bool = True  # mascot in the launch banner + status-bar face (--no-logo / SCOOT_LOGO / /logo)
+    emoji: bool = True  # 🛴 transcript label; off → ⏺ for terminals without an emoji font (--no-emoji)
+
+    # ── Loading ────────────────────────────────────────────────────────────────
+    @classmethod
+    def load(cls, cwd: Optional[Path] = None) -> "Config":
+        """Load config from the ``.env`` files + environment variables, falling back to defaults."""
+        cwd = (cwd or Path.cwd()).resolve()
+        files = env_files(cwd)
+        for env_file in files:
+            load_dotenv(env_file)
+
+        get = os.environ.get
+        return cls(
+            proxy=get("HTTPS_PROXY") or get("https_proxy") or DEFAULT_PROXY,
+            env_files=tuple(str(f) for f in files),
+            provider=get("SCOOT_PROVIDER", "").strip().lower(),
+            model=_resolve_model_setting(get("SCOOT_MODEL")),
+            effort=get("SCOOT_EFFORT", "medium").strip().lower(),
+            timeout=int(get("SCOOT_TIMEOUT", "120")),
+            max_steps=int(get("SCOOT_MAX_STEPS", "50")),
+            compact_at=int(get("SCOOT_COMPACT_AT", "100000")),
+            approval=get("SCOOT_APPROVAL", "yolo"),
+            root=Path(get("SCOOT_ROOT", str(cwd))).resolve(),
+            verbose=_as_bool(get("SCOOT_VERBOSE", "false")),
+            stream=_as_bool(get("SCOOT_STREAM", "true")),
+            panel=_as_bool(get("SCOOT_PANEL", "true")),
+            dock=_as_bool(get("SCOOT_DOCK", "true")),
+            resume=get("SCOOT_RESUME", "auto").strip().lower(),
+            workspace_context=_as_bool(get("SCOOT_WORKSPACE_CONTEXT", "true")),
+            labels=_as_bool(get("SCOOT_LABELS", "true")),
+            verbosity=get("SCOOT_VERBOSITY", "full").strip().lower(),
+            images=_as_bool(get("SCOOT_IMAGES", "true")),
+            vision_model=get("SCOOT_VISION_MODEL", "auto"),
+            image_max_bytes=int(get("SCOOT_IMAGE_MAX_BYTES", str(4 * 1024 * 1024))),
+            logo=_resolve_logo_setting(get("SCOOT_LOGO")),
+            emoji=_as_bool(get("SCOOT_EMOJI", "true")),
+        )
+
+    def override(self, **kwargs) -> "Config":
+        """Return a copy with the given (non-None) fields overridden — the CLI-flag layer."""
+        clean = {k: v for k, v in kwargs.items() if v is not None}
+        if "root" in clean:
+            clean["root"] = Path(clean["root"]).resolve()
+        return replace(self, **clean)
+
+    def resolve_model(self, task_hint: str = "") -> str:
+        """The qualified ``provider/model`` for the configured preference.
+
+        ``default`` is the default provider's preferred model (``gpt-5.3-codex`` on OpenAI). ``auto`` is
+        the per-turn heuristic over the live model list; before that list exists it resolves the same
+        way as ``default``.
+        """
+        from .providers.base import qualify
+        from .providers.registry import default_provider_name, fallback_model
+
+        if is_model_alias(self.model):
+            return fallback_model(self)
+        return qualify(default_provider_name(self), self.model)
+

scootcli/context.py

@@ -0,0 +1,82 @@
+"""Conversation context management: token estimation + /compact (summarize → clear → reseed).
+
+When the context grows large we ask the model to summarize the conversation, drop the old turns, and
+keep the summary as the new base — freeing tokens without losing the thread (PLAN §6 /compact).
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Optional
+
+_COMPACT_SYSTEM = (
+    "You compress a coding assistant conversation into a compact hand-off note. "
+    "Capture: the user's goal, key decisions, files created/changed, commands run, current plan, and "
+    "any open TODOs. Be terse and factual. Output only the note."
+)
+
+
+def estimate_context_tokens(session) -> int:
+    """Best-effort current context size from the last API ``usage.prompt_tokens``.
+
+    Falls back to a rough char/4 estimate over the live messages when there has been no API call yet
+    (e.g. immediately after resuming a saved session, before the first turn of the new process).
+    """
+    usage = session.last_usage or {}
+    tokens = int(usage.get("prompt_tokens", 0) or 0)
+    if tokens:
+        return tokens
+    return estimate_messages_tokens(getattr(session, "messages", None))
+
+
+def estimate_messages_tokens(messages) -> int:
+    """Rough token estimate (~4 chars/token) over a message list; used before any usage is known."""
+    if not messages:
+        return 0
+    chars = 0
+    for m in messages:
+        content = m.get("content")
+        if isinstance(content, str):
+            chars += len(content)
+    return chars // 4
+
+
+def _render_conversation(messages) -> str:
+    parts = []
+    for m in messages:
+        role = m.get("role", "?")
+        content = m.get("content", "")
+        if not content and m.get("tool_calls"):
+            calls = ", ".join(c.get("function", {}).get("name", "?") for c in m["tool_calls"])
+            content = f"[called tools: {calls}]"
+        parts.append(f"{role}: {content}")
+    return "\n".join(parts)
+
+
+def compact(session, cancel_event: Optional[threading.Event] = None) -> str:
+    """Summarize and replace the session's messages. Returns the summary text (or "" if nothing)."""
+    if not session.messages:
+        return ""
+    conversation = _render_conversation(session.messages)
+    result = session.provider.chat(
+        [
+            {"role": "system", "content": _COMPACT_SYSTEM},
+            {"role": "user", "content": conversation},
+        ],
+        model=session.active_model,
+        max_tokens=900,
+        cancel_event=cancel_event,
+    )
+    summary = (result.content or "").strip()
+    session.account(result.usage)
+    if not summary:
+        return ""
+    session.messages = [
+        {"role": "user", "content": "Summary of earlier conversation (context was compacted):\n" + summary},
+        {"role": "assistant", "content": "Understood — continuing with that context."},
+    ]
+    # Drop the stale usage from the summarization call so the context estimate (bar ``ctx``,
+    # auto-compact check) reflects the new, small message set until the next real turn.
+    session.last_usage = {}
+    return summary
+

scootcli/credentials.py

@@ -0,0 +1,79 @@
+"""Secure-at-rest storage for provider API keys.
+
+Stdlib-only and offline-friendly (no OS-keychain dependency, so the zipapp stays self-contained).
+Keys live in ``~/.config/scoot/credentials.json`` as ``{"keys": {"openai": "sk-..."}}`` with owner-only
+permissions (directory ``0700``, file ``0600``). Keys are never echoed; ``rendering.redact()`` masks them.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Dict, Optional
+
+from . import config as _config
+
+
+def _file() -> Path:
+    override = os.environ.get("SCOOT_CONFIG_DIR")
+    if override:
+        return Path(override).expanduser() / "credentials.json"
+    return _config.CREDENTIALS_FILE
+
+
+def _load() -> Dict[str, str]:
+    try:
+        data = json.loads(_file().read_text())
+    except (OSError, json.JSONDecodeError):
+        return {}
+    keys = data.get("keys") if isinstance(data, dict) else None
+    return {k: v for k, v in keys.items() if isinstance(v, str) and v} if isinstance(keys, dict) else {}
+
+
+def _write(keys: Dict[str, str]) -> Path:
+    directory = _file().parent
+    directory.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(directory, 0o700)
+    except OSError:
+        pass  # best-effort on exotic filesystems
+    # Open with a restrictive mode from the start so a key is never briefly world-readable.
+    fd = os.open(_file(), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as fh:
+        json.dump({"keys": keys}, fh)
+    try:
+        os.chmod(_file(), 0o600)  # tighten in case the file pre-existed
+    except OSError:
+        pass
+    return _file()
+
+
+def load_key(provider: str) -> Optional[str]:
+    """The saved API key for ``provider``, or ``None``."""
+    return _load().get(provider) or None
+
+
+def save_key(provider: str, key: str) -> Path:
+    """Persist ``key`` for ``provider`` (owner-only) and return the file path."""
+    keys = _load()
+    keys[provider] = key.strip()
+    return _write(keys)
+
+
+def delete_key(provider: str) -> bool:
+    """Forget the saved key for ``provider``. Return ``True`` if one was removed."""
+    keys = _load()
+    if provider not in keys:
+        return False
+    del keys[provider]
+    _write(keys)
+    return True
+
+
+def saved_providers() -> list:
+    return sorted(_load())
+
+
+def credentials_path() -> Path:
+    return _file()

scootcli/errors.py

@@ -0,0 +1,87 @@
+"""Typed errors for scoot, so callers can react to specific failure modes.
+
+Each error can carry a short ``hint`` with an actionable remedy for the user (surfaced by the REPL).
+"""
+
+from __future__ import annotations
+
+
+class ScootError(Exception):
+    """Base class for all scoot errors."""
+
+    def __init__(self, message: str, hint: str = ""):
+        super().__init__(message)
+        self.hint = hint
+
+
+class ConfigError(ScootError):
+    """Invalid or missing configuration."""
+
+
+# ── Transport-level ────────────────────────────────────────────────────────────
+class TransportError(ScootError):
+    """Low-level transport failure (connection died, TLS failed, timed out)."""
+
+
+class ProxyError(TransportError):
+    """The HTTPS proxy refused the CONNECT (bad or missing credentials)."""
+
+
+class NetworkError(TransportError):
+    """No connectivity: DNS resolution or TCP connect failed."""
+
+
+class RequestTimeout(TransportError):
+    """The request timed out."""
+
+
+class SSLError(TransportError):
+    """TLS/certificate failure."""
+
+
+# ── Auth ───────────────────────────────────────────────────────────────────────
+class AuthError(ScootError):
+    """Authentication failed: no OAuth token, or token exchange/JWT rejected."""
+
+
+# ── API-level ──────────────────────────────────────────────────────────────────
+class ApiError(ScootError):
+    """The API returned an error response."""
+
+    def __init__(self, message: str, status: int = 0, payload: object = None, hint: str = "", code: str = ""):
+        super().__init__(message, hint=hint)
+        self.status = status
+        self.payload = payload
+        self.code = code
+
+
+class RateLimitError(ApiError):
+    """HTTP 429 — too many requests."""
+
+
+class ServerError(ApiError):
+    """HTTP 5xx — server-side failure."""
+
+
+class QuotaError(ApiError):
+    """HTTP 402/403 or quota exhaustion: billing, quota, or permission problem."""
+
+
+class ContextLengthError(ApiError):
+    """The request exceeded the model's context window."""
+
+
+class ModelUnavailableError(ApiError):
+    """The requested model is not supported/accessible on this endpoint."""
+
+
+# ── Control flow ───────────────────────────────────────────────────────────────
+class Interrupted(ScootError):
+    """The in-flight request/tool was cancelled by the user (ESC)."""
+
+
+# Errors worth retrying with backoff (transient).
+RETRIABLE = (NetworkError, RequestTimeout, RateLimitError, ServerError)
+
+
+

scootcli/images.py

@@ -0,0 +1,169 @@
+"""Detect image file paths dropped into a prompt and encode them as data URIs (PLAN §3 / M22).
+
+Dragging a file into a terminal inserts its *path* as text (plain, backslash-escaped, quoted, or a
+``file://`` URL) — never the bytes. This module is pure text-parsing + file reads: it pulls recognised
+image paths out of a prompt and base64-encodes them for a vision model. No third-party deps.
+"""
+
+from __future__ import annotations
+
+import base64
+import mimetypes
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional, Tuple
+from urllib.parse import unquote, urlparse
+
+IMAGE_EXTENSIONS = {
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".tif", ".heic",
+}
+
+DEFAULT_MAX_BYTES = 4 * 1024 * 1024  # 4 MB — we can't downscale (stdlib only), so cap + warn instead.
+
+# Anchor detection on an image extension, then expand outward to whatever path actually exists on
+# disk. This is robust to spaces in the path (escaped *or* not) and to leading text, which naive
+# whitespace/quote tokenising gets wrong for real drag-and-drop paths (e.g. OneDrive screenshots).
+_IMAGE_EXT_RE = re.compile(r"\.(?:png|jpe?g|gif|webp|bmp|tiff?|heic)\b", re.IGNORECASE)
+
+
+class ImageTooLargeError(ValueError):
+    """Raised when an image exceeds the configured byte cap (we can't resize without a 3rd-party lib)."""
+
+
+@dataclass(frozen=True)
+class EncodedImage:
+    """A base64 data-URI-encoded image ready to attach to a vision request."""
+
+    name: str
+    mime: str
+    data_uri: str
+    size: int
+
+
+def _looks_like_image(path: Path) -> bool:
+    return path.suffix.lower() in IMAGE_EXTENSIONS
+
+
+def _try_path(value: str, root: Optional[Path]) -> Optional[Path]:
+    """Turn a candidate string into an existing image ``Path``, or ``None``."""
+    if not value:
+        return None
+    if value.startswith("file://"):
+        value = unquote(urlparse(value).path)
+    try:
+        p = Path(value).expanduser()
+        if not p.is_absolute() and root is not None:
+            p = Path(root) / p
+        if p.is_file() and _looks_like_image(p):
+            return p.resolve()
+    except OSError:
+        return None
+    return None
+
+
+def _normalize(text: str) -> str:
+    """Make dropped paths detectable: expand ``file://`` URLs and unescape backslash escapes."""
+    text = re.sub(r"file://\S+", lambda m: unquote(urlparse(m.group(0)).path), text)
+    return re.sub(r"\\(.)", r"\1", text)  # "\ " → " ", "\(" → "(", etc.
+
+
+def _find_image_span(text: str, root: Optional[Path]) -> Optional[Tuple[int, int, Path]]:
+    """Find the first ``(start, end, path)`` where ``text[start:end]`` is an existing image file.
+
+    Anchored on an image extension; the start is the left-most ``/``/``~``/beginning such that the
+    spanned substring exists on disk — so paths containing spaces are captured whole.
+    """
+    for m in _IMAGE_EXT_RE.finditer(text):
+        end = m.end()
+        # Candidate starts: string start, each path separator, and each word start (for relative
+        # paths). Ascending order means we try the *longest* (left-most) span first, so a path with
+        # spaces is captured whole rather than truncated at a space.
+        starts = {0}
+        for i, ch in enumerate(text[:end]):
+            if ch in "/~":
+                starts.add(i)
+            elif ch.isspace() and i + 1 < end:
+                starts.add(i + 1)
+        for s in sorted(starts):
+            cand = text[s:end].strip().strip("'\"")
+            p = _try_path(cand, root)
+            if p is not None:
+                # Tighten the removal span: skip leading whitespace but keep a wrapping quote, and
+                # swallow a trailing quote, so `'…path…'` is removed whole (no stray quotes left).
+                while s < end and text[s] in " \t":
+                    s += 1
+                ne = end + 1 if (end < len(text) and text[end] in "'\"") else end
+                return s, ne, p
+    return None
+
+
+def extract_image_paths(text: str, root: Optional[Path] = None) -> Tuple[str, List[Path]]:
+    """Split ``text`` into ``(clean_text, [image_paths])``.
+
+    Only substrings that resolve to an **existing** image file are treated as attachments and removed;
+    everything else is left in place. Handles plain / backslash-escaped / quoted / ``file://`` paths,
+    including filenames with spaces. Relative paths resolve against ``root`` when given.
+    """
+    work = _normalize(text)
+    paths: List[Path] = []
+    while True:
+        span = _find_image_span(work, root)
+        if span is None:
+            break
+        s, e, p = span
+        paths.append(p)
+        work = work[:s] + " " + work[e:]
+    clean = re.sub(r"\s+", " ", work).strip()
+    return clean, paths
+
+
+def badge_text(text: str, root: Optional[Path] = None) -> str:
+    """Return ``text`` with each detected image path replaced by a short ``[Image N]`` badge.
+
+    For display only (e.g. the REPL echo) — the real path is handled separately by
+    :func:`extract_image_paths`. If no image paths are present the original text is returned verbatim.
+    """
+    work = _normalize(text)
+    n = 0
+    while True:
+        span = _find_image_span(work, root)
+        if span is None:
+            break
+        s, e, _ = span
+        n += 1
+        work = work[:s] + f"[Image {n}]" + work[e:]
+    if n == 0:
+        return text  # nothing to badge — keep the prompt exactly as typed
+    return re.sub(r"\s+", " ", work).strip()
+
+
+def _sniff_mime(path: Path, raw: bytes) -> str:
+    """Detect an image MIME type from magic bytes, falling back to the extension."""
+    if raw[:3] == b"\xff\xd8\xff":
+        return "image/jpeg"
+    if raw[:8] == b"\x89PNG\r\n\x1a\n":
+        return "image/png"
+    if raw[:4] == b"RIFF" and raw[8:12] == b"WEBP":
+        return "image/webp"
+    if raw[:6] in (b"GIF87a", b"GIF89a"):
+        return "image/gif"
+    guess = mimetypes.guess_type(str(path))[0]
+    if guess and guess.startswith("image/"):
+        return guess
+    return "image/png"
+
+
+def to_data_uri(path: Path, max_bytes: int = DEFAULT_MAX_BYTES) -> EncodedImage:
+    """Read + base64-encode an image into a ``data:`` URI. Raises :class:`ImageTooLargeError` over cap."""
+    path = Path(path)
+    raw = path.read_bytes()
+    if max_bytes and len(raw) > max_bytes:
+        raise ImageTooLargeError(
+            f"{path.name} is {len(raw) // 1024} KB, over the {max_bytes // 1024} KB limit"
+        )
+    mime = _sniff_mime(path, raw)
+    b64 = base64.b64encode(raw).decode("ascii")
+    return EncodedImage(name=path.name, mime=mime, data_uri=f"data:{mime};base64,{b64}", size=len(raw))
+
+