feat: initial commit

2026-08-29 13:17:59 +02:00
commit 142f5f5759
91 changed files with 6155 additions and 0 deletions
@@ -0,0 +1,52 @@
+---
+name: sdk-version-upgrade
+description: Podniesienie wersji SDK lub biblioteki wraz z migracją wywołań API - planowanie zmiany, kolejność edycji, obsługa breaking changes i kryteria akceptacji. Użyj gdy zadanie mówi o bumpie wersji, upgradzie SDK, migracji do nowego major release lub usunięciu deprecated API.
+license: Apache-2.0
+allowed-tools:
+  - read_file
+  - search_repo
+  - list_files
+  - write_file
+  - replace_in_file
+  - run_verification
+metadata:
+  owner: pubi-platform
+  version: "1.0.0"
+  references: acme-sdk-2.x-migration.md
+---
+
+# Upgrade wersji SDK
+
+## Zasada nadrzędna
+
+Upgrade to **dwie rozłączne zmiany**: (a) deklaracja wersji w pliku zależności,
+(b) dostosowanie kodu do nowego API. Deklarację wersji ustawia deterministycznie silnik pipeline'u -
+Twoim zadaniem jest wyłącznie (b). Nie edytuj ręcznie plików zależności, chyba że plan mówi inaczej.
+
+## Kolejność pracy
+
+1. Przeczytaj notatkę migracyjną dla docelowej wersji z katalogu `references/` tego skilla.
+   Jeśli brakuje notatki dla danej biblioteki - **zatrzymaj się** i zgłoś `requires_human`.
+   Nie migruj API "z pamięci modelu".
+2. Zbuduj mapę zmian: `stary symbol -> nowy symbol -> plik(i) do zmiany`.
+3. Edytuj plik po pliku, najmniejszą możliwą zmianą (`replace_in_file`, nie przepisywanie pliku).
+4. Po każdym pliku uruchom weryfikację (`run_verification`). Czerwony wynik naprawiaj natychmiast,
+   zanim przejdziesz dalej - kumulowanie błędów uniemożliwia ustalenie przyczyny.
+5. Na koniec sprawdź, czy nie zostały użycia starego API: `search_repo` po każdym symbolu z mapy.
+
+## Breaking changes - reguły decyzyjne
+
+| Sytuacja | Działanie |
+|---|---|
+| Zmiana nazwy klasy/metody, ta sama semantyka | Migruj bezpośrednio |
+| Zmiana nazw parametrów | Migruj, zachowując wartości wywołań 1:1 |
+| Zasób wymaga teraz zamknięcia / context managera | Użyj `with`, nie dodawaj ręcznego `close()` |
+| Nowy wymagany parametr bez sensownej wartości domyślnej | `requires_human` - to decyzja biznesowa |
+| Usunięta funkcjonalność bez zamiennika | `requires_human`, nie obchodź problemu własną implementacją |
+
+## Kryteria akceptacji
+
+- Wszystkie testy repozytorium zielone.
+- Zero wystąpień starych symboli poza plikami changelog/dokumentacji.
+- Diff nie zawiera zmian niezwiązanych z migracją.
+- Deklarowana wersja zależności odpowiada wersji docelowej z zadania.
@@ -0,0 +1,31 @@
+# Maszynowo wykonywalna wersja notatki migracyjnej acme-sdk-2.x-migration.md.
+#
+# Zasada architektoniczna: co da się zmigrować deterministycznie, migrujemy regułą,
+# a nie modelem. LLM jest od reszty - od przypadków, których reguła nie obejmuje,
+# i od oceny, czy wynik ma sens. Reguły są częścią pakietu APM, więc podlegają
+# temu samemu wersjonowaniu i przeglądowi co skill.
+package: acme-sdk
+applies_to: ">=2.0.0,<3.0.0"
+file_glob: "*.py"
+rules:
+  - id: import-client
+    description: "Client -> AcmeClient w imporcie"
+    pattern: '\bfrom acme import Client\b'
+    replacement: 'from acme import AcmeClient'
+  - id: constructor
+    description: "Konstruktor: nowa nazwa klasy, endpoint -> base_url"
+    pattern: '\bClient\(\s*api_key=(?P<key>[^,]+),\s*endpoint=(?P<endpoint>[^)]+)\)'
+    replacement: 'AcmeClient(api_key=\g<key>, base_url=\g<endpoint>)'
+  - id: send-message
+    description: "send() -> messages.create() z nowymi nazwami parametrów"
+    pattern: '\.send\(\s*to=(?P<to>[^,]+),\s*body=(?P<body>[^)]+)\)'
+    replacement: '.messages.create(recipient=\g<to>, content=\g<body>)'
+  - id: drop-close
+    description: "Klient 2.x zwalnia zasoby automatycznie - close() usunięte z API"
+    pattern: '^[ \t]*[A-Za-z_][A-Za-z0-9_]*\.close\(\)[ \t]*\n'
+    replacement: ''
+    multiline: true
+  - id: response-attribute
+    description: "Odpowiedź jest obiektem Message, nie słownikiem"
+    pattern: '(?P<var>\b[a-z_][a-z0-9_]*)\[[''"]id[''"]\]'
+    replacement: '\g<var>.id'
@@ -0,0 +1,27 @@
+# acme-sdk: migracja 1.x -> 2.x
+
+> Przykładowa notatka migracyjna. W realnym wdrożeniu ten katalog zasila pakiet APM
+> utrzymywany przez zespół właściciela SDK (np. `pubi/apm-packages/acme-sdk-migrations`),
+> a `apm install` dostarcza go do joba CI z pinem po tagu.
+
+## Zmiany łamiące kompatybilność
+
+| 1.x | 2.x | Uwagi |
+|---|---|---|
+| `from acme import Client` | `from acme import AcmeClient` | zmiana wyłącznie nazwy |
+| `Client(api_key=..., endpoint=...)` | `AcmeClient(api_key=..., base_url=...)` | `endpoint` -> `base_url` |
+| `client.send(to=..., body=...)` | `client.messages.create(recipient=..., content=...)` | wysyłka przez sub-resource |
+| `client.close()` | `with AcmeClient(...) as client:` | klient jest context managerem |
+| zwracany `dict` z kluczem `id` | obiekt `Message` z atrybutem `.id` | dostęp `msg["id"]` -> `msg.id` |
+
+## Bez zmian
+
+- `AcmeError` pozostaje w `acme.errors`.
+- Format kluczy API i semantyka retry są niezmienione.
+
+## Kolejność migracji
+
+1. Import i konstrukcja klienta.
+2. Wywołania wysyłki.
+3. Zarządzanie cyklem życia (`close()` -> `with`).
+4. Odczyt pól odpowiedzi.
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Znajduje użycia modułu w repozytorium wraz z kontekstem.
+# Użycie: find_usages.sh <katalog-repo> <nazwa-modulu>
+set -euo pipefail
+repo="${1:?podaj katalog repozytorium}"
+module="${2:?podaj nazwę modułu importu}"
+rg --line-number --with-filename \
+   -e "^\s*import\s+${module}\b" \
+   -e "^\s*from\s+${module}\b" \
+   -e "\b${module}\." \
+   --glob '!**/.git/**' --glob '!**/node_modules/**' \
+   "$repo" || echo "brak użyć modułu ${module}"