stem-launcher/doc/tokens.md

# Tokens

Plik opisuje aktualny model pracy z tokenami w launcherze.

## Zrodlo prawdy

Sa dwa miejsca, w ktorych moga byc zapisane tokeny:

- remote URL-e w repo, na przyklad `http://LOGIN:TOKEN@host/org/repo.git`
- lokalny plik `~/dev/workspace/rv/tokens/tokens.json`

Jesli remote URL zawiera `LOGIN:TOKEN@...`, to remote jest zrodlem prawdy.
Launcher moze wtedy zeskanowac repo i zapisac ten token do `tokens.json`.

Jesli remote nie ma tokena, `tokens.json` moze byc uzyty jako lokalny store
przy operacjach `tokens write` i `tokens update --from store`.

## Format `tokens.json`

Tokeny sa trzymane per endpoint serwera, a dopiero pod nim per user i token:

```json
{
  "version": 2,
  "servers": {
    "http://77.90.8.171:3001": {
      "type": "gitea",
      "scheme": "http",
      "host": "77.90.8.171",
      "port": 3001,
      "users": {
        "u1": {
          "tokens": {
            "t1": "SECRET"
          }
        }
      }
    }
  }
}
```

To pozwala odroznic:

- typ serwera, na przyklad `gitea`, `github`, `gitlab`, `unknown`
- endpoint, czyli `scheme + host + port`
- uzytkownikow na danym serwerze
- wiele tokenow dla jednego usera

## Skanowanie remota

Przy `tokens scan` launcher:

- czyta wszystkie remote URL-e w repo
- czyta `tokens.json`
- laczy remote i store w pary po endpoincie serwera
- wybiera tylko `http` i `https`
- jesli URL ma `LOGIN:TOKEN@...`, wyciaga login i token
- zapisuje je pod odpowiednim endpointem w `tokens.json`

Endpoint jest liczony z:

- scheme
- host
- port

Przy skanowaniu launcher zapisuje tez metadane serwera:

- `type`
- `scheme`
- `host`
- `port`

## Komendy

### `tokens scan`

Zrodla:

```text
repo + tokens.json
```

Dzialanie:

- skanuje remote URL-e w repo
- czyta wpisy z `tokens.json`
- laczy oba zrodla po endpoincie serwera
- zapisuje znalezione tokeny do `tokens.json`
- zapisuje je per endpoint serwera
- wypisuje domyslnie tylko waska tabele `items`
- z `--verbose` dopisuje diagnostyczne sekcje `context` oraz `scan`

Tabela `items` porownuje dwa zrodla dla tego samego endpointu. Ten sam `item`
moze miec dwa wiersze:

- `source=repo` - stan remote URL-i w repo
- `source=tokens.json` - stan lokalnego store tokenow

Dzieki temu widac, dla ktorego endpointu token jest w remote, a dla ktorego
jest tylko w `tokens.json`.

Kolumny w tabeli `items`:

- `item` - numer porownywanego endpointu
- `source` - `repo` albo `tokens.json`
- `remote` - nazwa remote, na przyklad `r1`; tylko dla `source=repo`
- `kind` - `auth`, `plain`, `store` albo `missing`
- `user` - login odczytany z URL albo ze store
- `token_ref` - referencja bez sekretu: `remote` dla tokenu w URL albo nazwa tokenu ze store, na przyklad `t1`
- `result` - `added`, `existing`, `present`, `no_credentials` albo `missing`
- `status` - relacja repo do `tokens.json`, na przyklad `in_sync` albo `store_ahead`
- `url` - endpoint serwera bez sekretu, trzymany jako ostatnia kolumna i przycinany do szerokosci tabeli

Przyklad:

```bash
./rvctl tokens scan
./rvctl tokens scan --repo ~/dev/workspace/rv/series/inf/03
./rvctl tokens scan --verbose
```

### `tokens read`

Pokazuje szczegolowa zawartosc `tokens.json`.

Wynik zawiera:

- endpoint
- type
- scheme
- host
- port
- users
- tokens

Oraz liste userow i nazw tokenow dla kazdego endpointu.

Przyklad:

```bash
./rvctl tokens read
./rvctl tokens read --server http://77.90.8.171:3001
./rvctl tokens read --show-secrets
```

### `tokens stats`

Pokazuje statystyki per endpoint serwera i porownuje dwa zrodla:

- endpointy znalezione w remote URL-ach repo
- endpointy zapisane w `tokens.json`

Wynik ma ten sam model porownania co `tokens scan`, ale nie zapisuje zmian:

- liczbe endpointow w repo
- liczbe endpointow w store
- laczna unie endpointow
- statusy zgodnosci, na przyklad `in_sync`, `store_ahead`, `repo_ahead`
- tabele `items`, w ktorej repo i `tokens.json` sa osobnymi wierszami tego samego itemu

Przyklad:

```bash
./rvctl tokens stats --repo ~/dev/workspace/rv/series/inf/03
```

### `tokens write`

Kierunek:

```text
tokens.json -> repo
```

Dzialanie:

- bierze token z `tokens.json`
- wybiera endpoint, usera i token
- wpisuje dane auth do wybranego remota repo

Przyklad:

```bash
./rvctl tokens write \
  --repo ~/dev/workspace/rv/series/inf/03 \
  --remote r1 \
  --server http://77.90.8.171:3001 \
  --user u1 \
  --token-name t1
```

### `tokens update`

Uruchamia synchronizacje w zadanym kierunku.

Dozwolone kierunki:

- `tokens update --from remotes`
- `tokens update --from store`

Przyklad:

```bash
./rvctl tokens update --from remotes --repo ~/dev/workspace/rv/series/inf/03
./rvctl tokens update --from store --repo ~/dev/workspace/rv/series/inf/03 --remote r1 --server http://77.90.8.171:3001 --user u1 --token-name t1
```

## Konflikty

Domyslnie launcher nie zgaduje przy konflikcie.

Jesli:

- token jest w repo, ale nie ma go w `tokens.json`
  uzyj `tokens scan`
- token jest w `tokens.json`, ale nie ma go w repo
  uzyj `tokens write`
- token jest i tu, i tu, ale wartosci sa rozne
  wybierz kierunek jawnie przez `tokens update --from ...`

Przy `tokens write` i `tokens update --from store` mozna uzyc:

- `--replace`
- `--dry-run`

## Rekomendacja

Najbezpieczniejszy model pracy:

- `tokens scan` do zczytywania danych z remote'ow
- `tokens read` do podgladu store
- `tokens stats` do zbiorczego przegladu per endpoint
- `tokens write` do jawnego wpisania auth do remota
- `tokens update --from ...` tylko z jawnym kierunkiem