feat: configurable bufo exclude/include patterns via env vars (#491)

adds BUFO_EXCLUDE_PATTERNS and BUFO_INCLUDE_PATTERNS env vars to control
which bufo images appear in the easter egg animation.

- exclude: regex patterns to filter out (default: ^bigbufo_)
- include: allowlist that overrides exclude (default: bigbufo_0_0, bigbufo_2_1)

adds CommaSeparatedStringSet type for parsing comma-delimited env vars.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <[e-mail]>

backend/src/backend/config.py

···
 
 from __future__ import annotations
 
+from functools import partial
 from pathlib import Path
+from typing import Annotated, Any, TypeVar
 from urllib.parse import urlparse
 
-from pydantic import Field, computed_field
+from pydantic import BeforeValidator, Field, TypeAdapter, computed_field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 BASE_DIR = Path(__file__).resolve().parents[2]
+
+T = TypeVar("T")
+
+
+def validate_set_T_from_delim_string(
+    value: str | T | set[T] | None, type_: Any, delim: str | None = None
+) -> set[T]:
+    """Parse comma-delimited string into a set.
+
+    e.g. `BUFO_EXCLUDE_PATTERNS=bigbufo*,other*` -> `{"bigbufo*", "other*"}`
+    """
+    if not value:
+        return set()
+
+    adapter = TypeAdapter(type_)
+    delim = delim or ","
+    if isinstance(value, str):
+        return {adapter.validate_strings(s.strip()) for s in value.split(delim)}
+    try:
+        return {adapter.validate_python(value)}
+    except Exception:
+        pass
+    try:
+        return TypeAdapter(set[type_]).validate_python(value)
+    except Exception:
+        pass
+    raise ValueError(f"invalid set[{type_}]: {value}")
+
+
+CommaSeparatedStringSet = Annotated[
+    str | set[str],
+    BeforeValidator(partial(validate_set_T_from_delim_string, type_=str)),
+]
 
 
 class AppSettingsSection(BaseSettings):
···
     )
 
 
+class BufoSettings(AppSettingsSection):
+    """Bufo easter egg configuration."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="BUFO_",
+        env_file=".env",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    exclude_patterns: CommaSeparatedStringSet = Field(
+        default={"^bigbufo_"},
+        description="Regex patterns for bufo names to exclude from the easter egg animation",
+    )
+    include_patterns: CommaSeparatedStringSet = Field(
+        default={"bigbufo_0_0", "bigbufo_2_1"},
+        description="Regex patterns to override exclusions (allowlist)",
+    )
+
+
 class ObservabilitySettings(AppSettingsSection):
     """Observability configuration."""
 
···
     teal: TealSettings = Field(
         default_factory=TealSettings,
         description="teal.fm scrobbling integration settings",
+    )
+    bufo: BufoSettings = Field(
+        default_factory=BufoSettings,
+        description="bufo easter egg settings",
     )
 
 

backend/src/backend/main.py

···
         "max_upload_size_mb": settings.storage.max_upload_size_mb,
         "max_image_size_mb": 20,  # hardcoded limit for cover art
         "default_hidden_tags": DEFAULT_HIDDEN_TAGS,
+        "bufo_exclude_patterns": list(settings.bufo.exclude_patterns),
+        "bufo_include_patterns": list(settings.bufo.include_patterns),
     }
 
 

frontend/src/lib/components/BufoEasterEgg.svelte

···
 <script lang="ts">
 	import { onMount } from 'svelte';
+	import { getServerConfig } from '$lib/config';
 
 	interface Props {
 		query: string;
+		excludePatterns?: string[];
+		includePatterns?: string[];
 	}
 
 	interface Bufo {
···
 		animationClass: string;
 	}
 
-	let { query }: Props = $props();
+	let { query, excludePatterns = [], includePatterns = [] }: Props = $props();
 
 	let bufos = $state<Bufo[]>([]);
 	let spawnedBufos = $state<SpawnedBufo[]>([]);
···
 		}
 
 		try {
+			// get patterns from props or config
+			let exclude = excludePatterns;
+			let include = includePatterns;
+			if (exclude.length === 0 && include.length === 0) {
+				const config = await getServerConfig();
+				exclude = config.bufo_exclude_patterns ?? [];
+				include = config.bufo_include_patterns ?? [];
+			}
+
 			const params = new URLSearchParams({
 				query,
 				top_k: '10',
 				family_friendly: 'true'
 			});
+			if (exclude.length > 0) {
+				params.set('exclude', exclude.join(','));
+			}
+			if (include.length > 0) {
+				params.set('include', include.join(','));
+			}
 			const response = await fetch(`https://find-bufo.fly.dev/api/search?${params}`);
 			if (response.ok) {
 				const data = await response.json();

frontend/src/lib/config.ts

···
 	max_upload_size_mb: number;
 	max_image_size_mb: number;
 	default_hidden_tags: string[];
+	bufo_exclude_patterns: string[];
+	bufo_include_patterns: string[];
 }
 
 let serverConfig: ServerConfig | null = null;