updated docs

2026-08-12 17:54:40 +02:00
parent 4eedc1f642
commit 195d4169f5
7 changed files with 287 additions and 134 deletions
@@ -0,0 +1,86 @@
+# Jak komendy rozmawiają z git.intecion.net
+
+Ten plik tłumaczy, co robi każda komenda, gdy instalujesz `@intecion/ipal-kit`.
+Rejestr pakietów jest **publiczny do odczytu** — instalacja nie wymaga tokenu.
+Token jest potrzebny tylko przy publikowaniu nowych wersji (patrz
+[publishing.md](./publishing.md)).
+
+## Rejestr scoped — co to znaczy
+
+W `.npmrc` masz jedną linię:
+
+```
+@intecion:registry=https://git.intecion.net/api/packages/IntecionSoftware/npm/
+```
+
+To reguła: „pakiety zaczynające się od `@intecion/` pobieraj z tego adresu".
+**Nie zmienia** domyślnego rejestru — wszystko inne (`react`, `next`,
+`@payloadcms/*`) dalej idzie z publicznego npm. To override dla jednego scope,
+nie przełączenie całego źródła.
+
+Dlatego mieszana instalacja działa bez konfliktu:
+- `@intecion/ipal-kit` → Gitea
+- `react`, `payload`, `lucide-react` → npm
+
+## Komenda po komendzie
+
+### edycja `.npmrc` (linia z registry)
+
+**Co robi:** zapisuje regułę „scope `@intecion` → rejestr Gitea". Nic nie
+pobiera — to plik konfiguracyjny, czytany dopiero przy instalacji.
+
+**Rozmowa z serwerem:** żadna przy samym zapisie.
+
+Ponieważ rejestr jest publiczny, ta linia **nie zawiera tokenu** — plik jest
+bezpieczny do zacommitowania i musi trafić do repo, żeby serwer deploymentu też
+wiedział, skąd brać `@intecion/*`.
+
+### `pnpm add @intecion/ipal-kit`
+
+**Co robi:** to komenda, która faktycznie łączy się z rejestrem.
+
+Krok po kroku:
+1. pnpm widzi scope `@intecion` → sprawdza `.npmrc` → znajduje regułę „→ Gitea".
+2. Łączy się z rejestrem Gitea. Rejestr publiczny, więc **bez tokenu**.
+3. Rejestr odsyła metadane pakietu (wersje, adres `.tgz`).
+4. pnpm pobiera i rozpakowuje do `node_modules/@intecion/ipal-kit` — **czysta
+   ścieżka**, bez hasha commita.
+
+Ta czysta ścieżka jest ważna: komponenty klienta pluginu (baner zgód, analytics,
+Turnstile) rozwiązują się poprawnie tylko z niej. Instalacja z gita dawała
+pokręconą ścieżkę z hashem, która łamała React Client Manifest.
+
+**Gdy to zawiedzie:**
+- `404` — brakuje linii `@intecion:registry` w `.npmrc`, więc pnpm poszedł do
+  publicznego npm, gdzie pakietu nie ma. Sprawdź, czy `.npmrc` istnieje i ma tę
+  linię.
+
+### `pnpm install`
+
+**Co robi:** odtwarza wszystkie zależności z `package.json` / lockfile, w tym
+`@intecion/ipal-kit`. Ta sama rozmowa z Gitea dla części `@intecion`, reszta z
+npm. Różnica względem `add`: `install` odtwarza to, co już zapisane, `add`
+dopisuje nowe.
+
+## Sprawdzenie, czy rejestr odpowiada
+
+Bez tokenu, publiczny endpoint:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}\n" \
+  https://git.intecion.net/api/packages/IntecionSoftware/npm/@intecion%2Fipal-kit
+```
+
+`200` → rejestr działa, pakiet dostępny. `404` → zła ścieżka/nazwa.
+
+## Krótkie podsumowanie
+
+| Komenda | Rozmawia z serwerem? | Token? | Po co |
+|---|---|---|---|
+| edycja `.npmrc` (registry) | nie | nie | reguła scope na później |
+| `pnpm add @intecion/ipal-kit` | tak | nie (publiczny) | pobiera pakiet |
+| `pnpm install` | tak (dla @intecion) | nie | odtwarza zależności |
+| `curl .../npm/@intecion%2F...` | tak | nie | test dostępności |
+
+Publikowanie wersji (osobna rola, **wymaga** tokenu `write:package`):
+[publishing.md](./publishing.md).