ipal-kit/docs/dev/gitea-commands.md

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).

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:

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.