feat(devsetup): prepare-developer-machine w bin/, detekcja dystrybucji, uv

Logika przeniesiona z Makefile do bin/prepare-developer-machine/. Skrypt
rozpoznaje wersję macOS, architekturę i dystrybucję Linuksa (rodziny
Debiana, Fedory/RHEL i Archa), a na Linuksie instaluje przypięte uv.

Lista apt dostaje build-essential oraz nagłówki LDAP/SASL/SSL: python-ldap
jest tylko jako sdist, więc bez nich uv sync pada na braku lber.h.

Listy pakietów nie zostały zweryfikowane na prawdziwym Linuksie — testy
w kontenerach przerwało wolne łącze.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mr7s9r131e98ET24qkVaAn

Author: mpasternak

Makefile

@@ -57,122 +57,21 @@ endif
 
 all:	prepare-developer-machine release ## UWAGA: pełna konfiguracja + release (uruchamia release!)
 
-# WeasyPrint (cffi.dlopen / ctypes.util.find_library) musi znalezc
-# libgobject-2.0 / pango / harfbuzz / fontconfig zainstalowane przez brew.
-# Na Apple Silicon te biblioteki siedza w /opt/homebrew/lib, ktorego dyld
-# nie konsultuje domyslnie (default search path to /usr/local/lib + /usr/lib).
-#
-# Probowalismy wczesniej (commit 3531fd2d4) DYLD_FALLBACK_LIBRARY_PATH —
-# nie sprawdza sie w praktyce: macOS SIP strippuje wszystkie zmienne DYLD_*
-# w momencie wywolania chronionej binarki (/usr/bin/*, /bin/sh, itp.), wiec
-# w lancuchach typu  make → sh → uv → python → pytest  zmienna regularnie
-# ginie po drodze. Z perspektywy pytest/uv vs. dlopen — niedeterministyczne.
-#
-# Wracamy do symlinkow w /usr/local/lib: filesystem-level, dyld konsultuje
-# te sciezke z automatu, SIP nic z tym nie zrobi. Wymaga sudo *raz*
-# przy setupie maszyny. Idempotent — recipe nie nadpisuje istniejacych
-# symlinkow wskazujacych na te same cele.
-#
-# UWAGA: To runtime fix dla dlopen. Nie pomaga przy *build-time* bledach
-# (np. wheel buduje sie z zrodla i nie znajduje cairo.h) — wtedy potrzeba
-# PKG_CONFIG_PATH=/opt/homebrew/lib/pkgconfig + LDFLAGS=-L/opt/homebrew/lib
-# + CPPFLAGS=-I/opt/homebrew/include.
-prepare-developer-machine-macos: ## Zainstaluj zależności systemowe na macOS (brew + uv sync + playwright + symlinki)
-	@if ! command -v brew >/dev/null 2>&1; then \
-		echo ""; \
-		echo "BŁĄD: Homebrew (brew) nie jest zainstalowany."; \
-		echo ""; \
-		echo "Homebrew jest wymagany do zainstalowania zależności systemowych"; \
-		echo "(cairo, pango, gdk-pixbuf, libffi, gobject-introspection, gtk+3)."; \
-		echo ""; \
-		echo "Aby zainstalować Homebrew, uruchom w terminalu poniższe polecenie:"; \
-		echo ""; \
-		echo '  /bin/bash -c "$$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'; \
-		echo ""; \
-		echo "Po zakończeniu instalacji wykonaj kroki dodające 'brew' do PATH"; \
-		echo "wypisane przez instalator (zwykle dla Apple Silicon: dopisanie"; \
-		echo "linii 'eval \"\$$(/opt/homebrew/bin/brew shellenv)\"' do ~/.zprofile)."; \
-		echo ""; \
-		echo "Pełna dokumentacja: https://brew.sh"; \
-		echo ""; \
-		echo "Po instalacji Homebrew uruchom ponownie:  make prepare-developer-machine"; \
-		echo ""; \
-		exit 1; \
-	fi
-	brew install cairo pango gdk-pixbuf libffi gobject-introspection gtk+3 node yarn
-	npm install -g grunt-cli
-	uv sync --frozen --no-install-project --all-extras
-	@# Symlinki w /usr/local/lib — dyld konsultuje te sciezke domyslnie,
-	@# wiec niezaleznie od stanu DYLD_* (SIP) WeasyPrint znajdzie libki.
-	@if [ ! -d /usr/local/lib ]; then \
-		echo "Tworze /usr/local/lib (wymagane sudo)..."; \
-		sudo mkdir -p /usr/local/lib; \
-	fi
-	@for pair in \
-		"/opt/homebrew/opt/glib/lib/libgobject-2.0.0.dylib:gobject-2.0" \
-		"/opt/homebrew/opt/pango/lib/libpango-1.0.dylib:pango-1.0" \
-		"/opt/homebrew/opt/harfbuzz/lib/libharfbuzz.dylib:harfbuzz" \
-		"/opt/homebrew/opt/fontconfig/lib/libfontconfig.1.dylib:fontconfig-1" \
-		"/opt/homebrew/opt/pango/lib/libpangoft2-1.0.dylib:pangoft2-1.0"; do \
-		src="$${pair%:*}"; dst="/usr/local/lib/$${pair##*:}"; \
-		if [ -L "$$dst" ] && [ "$$(readlink "$$dst")" = "$$src" ]; then \
-			echo "Symlink $$dst juz wskazuje na $$src — pomijam."; \
-		else \
-			echo "Tworze symlink $$dst -> $$src (wymagane sudo)..."; \
-			sudo ln -sf "$$src" "$$dst"; \
-		fi; \
-	done
-	@# Cleanup po poprzedniej probie z DYLD_FALLBACK_LIBRARY_PATH —
-	@# usun marker + linie export z ~/.zprofile, jesli zostaly.
-	@ZPROFILE="$$HOME/.zprofile"; \
-	MARKER='# bpp: weasyprint dlopen (Homebrew libs on Apple Silicon)'; \
-	if [ -f "$$ZPROFILE" ] && grep -qF "$$MARKER" "$$ZPROFILE"; then \
-		cp "$$ZPROFILE" "$$ZPROFILE.bpp-bak"; \
-		awk -v m="$$MARKER" 'BEGIN{skip=0} \
-			$$0==m {skip=1; next} \
-			skip>0 {skip--; next} \
-			{print}' "$$ZPROFILE.bpp-bak" > "$$ZPROFILE"; \
-		echo "Usunieto stary wpis DYLD_FALLBACK_LIBRARY_PATH z $$ZPROFILE (backup: $$ZPROFILE.bpp-bak)."; \
-	fi
-	$(MAKE) playwright-install
-
-prepare-developer-machine-linux: ## Zainstaluj zależności systemowe na Linuksie (apt + uv sync + playwright)
-	sudo apt update
-	sudo apt install -y yarnpkg nodejs npm python3-dev libpq-dev \
-		libcairo2-dev libpango1.0-dev libgdk-pixbuf-xlib-2.0-dev libffi-dev \
-		libgirepository1.0-dev libgtk-3-dev
-	sudo npm install -g grunt-cli
-	uv sync --frozen --no-install-project --all-extras
-	$(MAKE) playwright-install
-
-prepare-developer-machine: ## Zainstaluj zależności systemowe (auto-detekcja macOS/Linux)
-ifeq ($(OS),Darwin)
-	$(MAKE) prepare-developer-machine-macos
-else ifeq ($(OS),Linux)
-	$(MAKE) prepare-developer-machine-linux
-else
-	@echo "Unsupported platform: $(OS)"
-	@echo "Supported: Darwin (macOS), Linux"
-	@exit 1
-endif
+# Właściwa logika (detekcja systemu i dystrybucji, pakiety, uv, Playwright)
+# siedzi w bin/prepare-developer-machine/.
+PREPARE_DEVELOPER_MACHINE := bin/prepare-developer-machine/prepare.sh
 
-# Pobiera przeglądarki Playwright (chromium itd.) potrzebne do testów E2E.
-# Na Linuksie używa --with-deps, żeby playwright doinstalował systemowe
-# biblioteki (libnss3, libatk, libgtk-3...) przez apt — to wymaga sudo
-# i jest dokładnie tym, co opisuje README sekcja 2 ("uv run playwright
-# install" + "sudo playwright install-deps") tylko sklejone w jednej
-# komendzie. Na macOS install-deps to no-op (browsers są self-contained,
-# a brew już zainstalował systemowe libki w prepare-developer-machine-macos),
-# więc używamy gołego "playwright install".
-#
-# Wymaga, by uv sync --all-extras zostało wcześniej wykonane (playwright
-# CLI siedzi w grupie dev pyproject.toml). Stąd kolejność w prepare-*.
-playwright-install: ## Pobierz przeglądarki Playwright dla testów E2E (na Linuksie z --with-deps, sudo)
-ifeq ($(OS),Darwin)
-	uv run playwright install
-else
-	uv run playwright install --with-deps
-endif
+prepare-developer-machine-macos: ## Zainstaluj zależności systemowe na macOS (brew + uv + uv sync + playwright + symlinki)
+	$(PREPARE_DEVELOPER_MACHINE) macos
+
+prepare-developer-machine-linux: ## Zainstaluj zależności systemowe na Linuksie (apt/dnf/pacman + uv + uv sync + playwright)
+	$(PREPARE_DEVELOPER_MACHINE) linux
+
+prepare-developer-machine: ## Zainstaluj zależności systemowe (auto-detekcja systemu i dystrybucji)
+	$(PREPARE_DEVELOPER_MACHINE)
+
+playwright-install: ## Pobierz przeglądarki Playwright dla testów E2E (na Debianie/Ubuntu z --with-deps, sudo)
+	$(PREPARE_DEVELOPER_MACHINE) playwright
 
 prepare-claude: ## Pokaż instrukcję instalacji wtyczki claude-mem w Claude Code
 	@echo "Setting up Claude Code with claude-mem plugin..."

README.md

@@ -141,32 +141,37 @@ uv run pytest -n auto             # testy równolegle (pytest-xdist)
 ```
 
 Wymagania: **Docker daemon** (do testcontainers), Homebrew (macOS) lub
-`apt` + `sudo` (Linux). Pierwszy bieg pobiera kilkaset MB do paru GB
-(pakiety npm, przeglądarki Playwright, obrazy Dockera dla testów).
-
-Co robi `make prepare-developer-machine`:
-
-- **macOS** (Apple Silicon, Homebrew) — przez `brew`: `cairo`, `pango`,
-  `gdk-pixbuf`, `libffi`, `gobject-introspection`, `gtk+3`, `node`,
-  `yarn`; przez `npm` globalnie `grunt-cli`; tworzy `sudo`-symlinki
-  w `/usr/local/lib` na libki z `/opt/homebrew/lib`
+`sudo` (Linux). `uv` instaluje się samo, jeśli go nie ma. Pierwszy bieg
+pobiera kilkaset MB do paru GB (pakiety npm, przeglądarki Playwright,
+obrazy Dockera dla testów).
+
+Co robi `make prepare-developer-machine` (skrypty:
+`bin/prepare-developer-machine/`; system i dystrybucję wykrywa sam,
+`bin/prepare-developer-machine/prepare.sh detect` pokazuje wynik detekcji):
+
+- **macOS** — przez `brew`: `cairo`, `pango`, `gdk-pixbuf`, `libffi`,
+  `gobject-introspection`, `gtk+3`, `node`, `yarn`; przez `npm` globalnie
+  `grunt-cli`; instaluje `uv`, jeśli go nie ma; na Apple Silicon tworzy
+  `sudo`-symlinki w `/usr/local/lib` na libki z `/opt/homebrew/lib`
   (`dyld` nie konsultuje brew-owej ścieżki domyślnie, a `DYLD_FALLBACK_LIBRARY_PATH`
   jest stripowana przez SIP w podprocesach — patrz
-  [docs/MACOS_WEASYPRINT.md](docs/MACOS_WEASYPRINT.md)); na końcu
-  `uv sync --frozen --no-install-project --all-extras` +
+  [docs/deweloper/weasyprint-macos.md](docs/deweloper/weasyprint-macos.md));
+  na końcu `uv sync --frozen --no-install-project --all-extras` +
   `uv run playwright install`.
-- **Linux** (Debian/Ubuntu, `apt`) — przez `sudo apt`: `yarnpkg`,
-  `nodejs`, `npm`, `python3-dev`, `libpq-dev`, `libcairo2-dev`,
-  `libpango1.0-dev`, `libgdk-pixbuf2.0-dev`, `libffi-dev`,
-  `libgirepository1.0-dev`, `libgtk-3-dev`; przez `sudo npm` globalnie
-  `grunt-cli`; na końcu `uv sync --frozen --no-install-project
-  --all-extras` + `uv run playwright install --with-deps` (z systemowymi
-  libkami chromium — wymaga sudo).
-
-Auto-detekcja systemu jest domyślna; aby wymusić wariant:
-`make prepare-developer-machine-macos` albo
-`make prepare-developer-machine-linux`. Cel **nie woła `make assets`** —
-frontend trzeba zbudować osobno.
+- **Linux** — pakiety systemowe (kompilator, nagłówki LDAP/SASL/SSL dla
+  `python-ldap`, libki WeasyPrint, Node, yarn, gettext) i `grunt-cli`
+  przez menedżer pakietów dystrybucji: `apt` (Debian, Ubuntu i pochodne),
+  `dnf` (Fedora, RHEL i pochodne) albo `pacman` (Arch i pochodne); potem
+  `uv` w wersji przypiętej w projekcie (do `~/.local/bin`, jeśli go nie
+  ma) i `uv sync --frozen --no-install-project --all-extras`. Na końcu
+  `uv run playwright install --with-deps` (Debian/Ubuntu, wymaga sudo)
+  albo samo `uv run playwright install` — poza Debianem/Ubuntu Playwright
+  nie jest oficjalnie wspierany, a jego biblioteki instaluje krok systemowy.
+
+Aby wymusić wariant: `make prepare-developer-machine-macos` albo
+`make prepare-developer-machine-linux` (wariant niepasujący do systemu kończy
+się błędem). Cel **nie woła `make assets`** — frontend trzeba zbudować
+osobno.
 
 `pytest -n auto` (`pytest-xdist`) rozdziela testy między workery; każdy
 worker dostaje **własny** testcontainer PostgreSQL/Redis na losowym

bin/prepare-developer-machine/lib.sh

@@ -0,0 +1,128 @@
+# shellcheck shell=bash disable=SC2034
+#
+# Wspólne funkcje skryptów prepare-developer-machine: logowanie, detekcja
+# systemu, instalacja uv i przeglądarek Playwright.
+#
+# UWAGA: macOS ma bash 3.2 — bez tablic asocjacyjnych, `${x,,}` i `mapfile`.
+
+# Trzymaj w parze z pinem uv w CI (`version:` w setup-uv), Dockerfile
+# (`COPY --from=ghcr.io/astral-sh/uv:…`) i .pre-commit-config.yaml. Inna wersja
+# potrafi uznać ten sam uv.lock za nieaktualny.
+UV_VERSION="0.13.5"
+
+# Node z obrazów Dockera to 24 (NODEJS_VERSION w docker/bpp_base/Dockerfile).
+MIN_NODE_MAJOR=20
+
+log() { printf '\n==> %s\n' "$*"; }
+warn() { printf 'UWAGA: %s\n' "$*" >&2; }
+die() {
+    printf 'BŁĄD: %s\n' "$*" >&2
+    exit 1
+}
+
+# Ustawia DETECTED_OS na `macos` albo `linux`.
+detect_os() {
+    case "$(uname -s)" in
+        Darwin) DETECTED_OS=macos ;;
+        Linux) DETECTED_OS=linux ;;
+        *) die "Nieobsługiwany system: $(uname -s). Obsługiwane: macOS, Linux." ;;
+    esac
+}
+
+# Ustawia MACOS_VERSION, ARCH i BREW_PREFIX (pusty, gdy nie ma Homebrew).
+detect_macos() {
+    MACOS_VERSION="$(sw_vers -productVersion)"
+    ARCH="$(uname -m)"
+    BREW_PREFIX=""
+    if command -v brew >/dev/null 2>&1; then
+        BREW_PREFIX="$(brew --prefix)"
+    fi
+}
+
+# Ustawia LINUX_ID, LINUX_VERSION_ID, LINUX_NAME, ARCH i LINUX_FAMILY
+# (`debian`, `fedora`, `arch` albo pusty, gdy dystrybucja jest nieobsługiwana).
+# ID_LIKE pozwala rozpoznać pochodne: Mint, Pop!_OS, Rocky, Manjaro itd.
+detect_linux() {
+    local os_release="${OS_RELEASE_FILE:-/etc/os-release}"
+    [ -r "$os_release" ] || die "Brak $os_release — nie rozpoznam dystrybucji."
+
+    local ID="" ID_LIKE="" VERSION_ID="" PRETTY_NAME=""
+    # shellcheck disable=SC1090
+    . "$os_release"
+
+    LINUX_ID="$ID"
+    LINUX_VERSION_ID="$VERSION_ID"
+    LINUX_NAME="${PRETTY_NAME:-$ID}"
+    ARCH="$(uname -m)"
+    LINUX_FAMILY=""
+
+    local candidate
+    for candidate in $ID $ID_LIKE; do
+        case "$candidate" in
+            debian | ubuntu) LINUX_FAMILY=debian ;;
+            fedora | rhel | centos) LINUX_FAMILY=fedora ;;
+            arch) LINUX_FAMILY=arch ;;
+        esac
+        [ -z "$LINUX_FAMILY" ] || break
+    done
+}
+
+# Przypina uv, gdy go nie ma; instalator z astral.sh trafia do ~/.local/bin.
+# Na PATH dokładamy ten katalog zawsze, żeby znaleźć uv z poprzedniego
+# uruchomienia, gdy shell nie wczytał jeszcze zmienionego profilu.
+ensure_uv() {
+    export PATH="$HOME/.local/bin:$PATH"
+
+    if command -v uv >/dev/null 2>&1; then
+        local current
+        current="$(uv --version | awk '{print $2}')"
+        if [ "$current" = "$UV_VERSION" ]; then
+            log "uv $current już zainstalowane — pomijam."
+        else
+            warn "uv $current różni się od wersji projektu ($UV_VERSION)."
+            warn "Zaktualizuj: uv self update $UV_VERSION"
+        fi
+        return
+    fi
+
+    command -v curl >/dev/null 2>&1 || die "Do instalacji uv potrzebny jest curl."
+    log "Instaluję uv $UV_VERSION"
+    curl -LsSf "https://astral.sh/uv/${UV_VERSION}/install.sh" | sh
+    command -v uv >/dev/null 2>&1 ||
+        die "uv zainstalowane, ale nie ma go na PATH (sprawdź ~/.local/bin)."
+    warn "uv jest w ~/.local/bin — otwórz nowy shell, żeby było na PATH."
+}
+
+sync_python_deps() {
+    log "Synchronizuję zależności Pythona"
+    uv sync --frozen --no-install-project --all-extras
+}
+
+warn_if_old_node() {
+    local major
+    major="$(node --version | sed -E 's/^v([0-9]+).*/\1/')"
+    if [ "$major" -lt "$MIN_NODE_MAJOR" ]; then
+        warn "Node $major jest stary (obrazy Dockera używają 24)."
+        warn "\`make assets\` może się nie udać — doinstaluj nowszy Node."
+    fi
+}
+
+# Wymaga wcześniejszego `uv sync --all-extras` (playwright CLI siedzi w grupie
+# dev). `--with-deps` doinstalowuje biblioteki systemowe przez apt (sudo),
+# więc działa tylko na rodzinie Debiana. Na macOS przeglądarki są
+# samowystarczalne, a na Fedorze/Archu biblioteki instaluje linux.sh.
+install_playwright_browsers() {
+    export PATH="$HOME/.local/bin:$PATH"
+    detect_os
+
+    log "Instaluję przeglądarki Playwright"
+    if [ "$DETECTED_OS" = linux ]; then
+        detect_linux
+        if [ "$LINUX_FAMILY" = debian ]; then
+            uv run playwright install --with-deps
+            return
+        fi
+        warn "Playwright oficjalnie wspiera tylko Debiana i Ubuntu."
+    fi
+    uv run playwright install
+}