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