stem-launcher/README.md

# RV Launcher

Repo `rv-launcher` zawiera narzędzie do pracy z workspace RISC-V. W pierwszej
kolejności służy ono do zarządzania tokenami; pozostałe funkcje obejmują pracę
z kartami pracy i uruchamianie środowiska kontenerowego.

Właściwym skryptem CLI jest wykonywalny plik `rvctl.py`. To on implementuje
zarządzanie tokenami, listowanie serii i kart, przygotowanie repo odpowiedzi i
start kontenera.

Publicznym entrypointem dla użytkownika jest krótki wrapper `rvctl`:

```bash
./rvctl
```

Wrapper uruchamia:

```bash
python3 rvctl.py "$@"
```

`rvctl.py` można też uruchomić bezpośrednio:

```bash
./rvctl.py
```

Ścieżki i domyślne ustawienia są trzymane w `workspace.json`.

## Co robi narzędzie

`rvctl` porządkuje pracę w trzech obszarach.

1. Zarządzanie tokenami

   Narzędzie obsługuje lokalny store `tokens/tokens.json`, porównuje go z git
   remotes i potrafi synchronizować token w obie strony. Szczegóły modelu,
   format pliku i opis komend są w `doc/tokens.md`.

2. Listowanie i pobieranie kart pracy

   `rvctl` czyta serie, karty i zadania z workspace, pomaga wybrać materiał do
   pracy oraz przygotowuje remotes potrzebne do repo odpowiedzi. Docelowy model
   namespace `series`, `cards` i `tasks` jest w `doc/series.md`.

3. Uruchamianie środowiska programistycznego w kontenerach

   Dla wybranej karty `rvctl` uruchamia sesję tmux i kontener z przygotowanym
   środowiskiem developerskim. Docelowy model namespace `containers` jest w
   `doc/containers.md`.

## Model katalogów

Podstawowym miejscem pracy użytkownika jest workspace:

```bash
~/dev/workspace/rv
```

Najpierw utwórz tylko katalog bazowy workspace i wejdź do niego:

```bash
mkdir -p ~/dev/workspace/rv
cd ~/dev/workspace/rv
```

Po tym kroku workspace istnieje, ale nie ma jeszcze katalogów narzędzi,
tokenów ani kart:

```text
~/dev/workspace/rv
```

Potem wybierz jedną z dwóch dróg startu.

### Bez `tokens.json`

Ten wariant jest dla sytuacji, w której token jest podany w URL-u git remota,
a plik `tokens.json` ma powstać dopiero lokalnie.

Etap 1: utwórz katalog launchera i wejdź do niego:

```bash
mkdir -p ~/dev/workspace/rv/tools/rv-launcher
cd ~/dev/workspace/rv/tools/rv-launcher
```

Etap 2: utwórz puste repo, dodaj remote `r1` z tokenem, pobierz branch i
ustaw lokalny `main`:

```bash
git init
git remote add r1 http://u1:TOKEN@77.90.8.171:3001/edu-tools/rv-launcher.git
git fetch r1 main
git switch --track -c main r1/main
```

`r1` jest nazwą remota, z którego startujemy. `--track` ustawia lokalny branch
`main` tak, aby śledził `r1/main`, dzięki czemu późniejsze `git pull` i
`git push` wiedzą, z którym branchem zdalnym pracują.

Po tym kroku w workspace jest już repo launchera:

```text
~/dev/workspace/rv
└── tools
    └── rv-launcher
```

Etap 3: wczytaj token z remota do lokalnego store:

```bash
cd ~/dev/workspace/rv/tools/rv-launcher
./rvctl tokens sync remote r1
./rvctl tokens update r1
```

`tokens sync remote r1` przepisuje token z URL-a remota `r1` do lokalnego
store. `tokens update r1` odpytuje Gitea API i uzupełnia metadane tokena:
ważność, zakresy oraz uprawnienia w organizacji i repo.

`rvctl` sam tworzy katalog `~/dev/workspace/rv/tokens`, jeżeli jeszcze go nie
ma. Plik `tokens.json` dostaje prawa `600`, a katalog store prawa `700`.

Po tym kroku workspace ma już `tokens.json`:

```text
~/dev/workspace/rv
├── tools
│   └── rv-launcher
└── tokens
    └── tokens.json
```

Etap 4: sprawdź, czy git remote i lokalny store widzą ten sam token:

```bash
./rvctl tokens compare
```

Przykładowy wydruk:

```text
tokens
item  server  proto  host                org        repo         user  remote  token_ref  token         valid    scope      org     repo
----  ------  -----  ------------------  ---------  -----------  ----  ------  ---------  ------------  -------  ---------  ------  ------
1     gitea   http   77.90.8.171:3001    edu-tools  rv-launcher  u1    r1      r1      *  e59cc...13be  forever  wwwwwwwww  +++++   ++++
```

Najważniejsze pola:

- `remote` - nazwa git remota, tutaj `r1`
- `token_ref` - lokalna nazwa tokena i marker zgodności po prawej stronie
- `*` - token w remote i w `tokens.json` jest zgodny
- `S` - token jest tylko w `tokens.json`; to jest normalne w trybie store-only
- `R` - token jest tylko w git remote
- `token` - zamaskowany sekret; `rvctl` nie wypisuje całego tokena
- `valid`, `scope`, `org`, `repo` - metadane i uprawnienia pobrane przez
  `tokens update`

Pełny opis tabeli tokenów jest w `doc/tokens.md`.

### Z `tokens.json`

Ten wariant jest dla sytuacji, w której masz już gotowy plik `tokens.json`.

Etap 1: skopiuj token store do workspace:

```bash
mkdir -p ~/dev/workspace/rv/tokens
cd ~/dev/workspace/rv
cp /ścieżka/do/tokens.json tokens/tokens.json
chmod 600 tokens/tokens.json
```

Po tym kroku workspace ma store tokenów, ale nie ma jeszcze launchera:

```text
~/dev/workspace/rv
└── tokens
    └── tokens.json
```

Etap 2: wejdź do katalogu narzędzi i sklonuj `rv-launcher`:

```bash
mkdir -p ~/dev/workspace/rv/tools
cd ~/dev/workspace/rv/tools
git clone http://77.90.8.171:3001/edu-tools/rv-launcher.git
cd rv-launcher
```

Po `git clone` workspace wygląda tak:

```text
~/dev/workspace/rv
├── tools
│   └── rv-launcher
└── tokens
    └── tokens.json
```

Etap 3: sprawdź store i wpisz credentials ze store do remota `r1`:

```bash
./rvctl tokens list store
./rvctl tokens sync store r1
```

`tokens list store` sprawdza, czy skopiowany `tokens.json` zawiera wpis dla
remota `r1`. `tokens sync store r1` bierze token ze store i wpisuje credentials
do git remota `r1`, tak aby kolejne operacje Git mogły używać tego tokena.
Jeżeli po `git clone` repo ma tylko remote `origin` wskazujący to samo repo,
`rvctl` automatycznie przemianuje go na `r1`.

`list store` powinien pokazać token ze store:

```text
tokens
item  source  kind  server  proto  host              org        repo         user  remote  token         valid
----  ------  ----  ------  -----  ----------------  ---------  -----------  ----  ------  ------------  -------
1     store   auth  gitea   http   77.90.8.171:3001  edu-tools  rv-launcher  u1    r1      e59cc...13be  forever
```

`sync store r1` wpisuje credentials do git remota:

```text
repo_root  /home/user/dev/workspace/rv/tools/rv-launcher
remote     r1
renamed_from  origin
server     http://77.90.8.171:3001
user       u1
id         r1
status     updated
url        http://77.90.8.171:3001/edu-tools/rv-launcher.git
```

Etap 4: odśwież metadane tokena i porównaj store z remote:

```bash
./rvctl tokens update r1
./rvctl tokens compare
```

`tokens update r1` odpytuje Gitea API dla tokena ze store i odświeża jego
metadane: ważność, zakresy oraz uprawnienia w organizacji i repo. `tokens
compare` sprawdza potem, czy store i git remote wskazują ten sam token.

`compare` powinien pokazać `*` przy `r1`, jeżeli remote i `tokens.json` są
zgodne:

```text
tokens
item  server  proto  host              org        repo         user  remote  token_ref  token         valid
----  ------  -----  ----------------  ---------  -----------  ----  ------  ---------  ------------  -------
1     gitea   http   77.90.8.171:3001  edu-tools  rv-launcher  u1    r1      r1      *  e59cc...13be  forever
```

Etap 5: po operacjach Git możesz usunąć sekret z `.git/config`, zostawiając
token tylko w store:

```bash
./rvctl tokens rm remote r1
./rvctl tokens compare
```

Po usunięciu remota `compare` pokazuje marker `S`, czyli token jest tylko w
store:

```text
tokens
item  server  proto  host              org        repo         user  remote  token_ref  token         valid
----  ------  -----  ----------------  ---------  -----------  ----  ------  ---------  ------------  -------
1     gitea   http   77.90.8.171:3001  edu-tools  rv-launcher  u1    r1      r1      S  e59cc...13be  forever
```

## Szybki start

Najpierw zobacz konfigurację i dostępne komendy:

```bash
./rvctl
./rvctl show-config
```

Typowy przepływ pracy:

```bash
./rvctl tokens compare
./rvctl list-series
./rvctl list-cards inf
./rvctl tmux-container inf 03 --dry-run
./rvctl tmux-container inf 03 --session rv-inf03 --attach
./rvctl submission inf 03 --class 4i --nick u1
```

`--dry-run` jest przydatny przy sprawdzaniu planu uruchomienia lub konfiguracji
repo, zanim narzędzie coś zmieni.

### Po pobraniu kart pracy

Karty trafiają do `series` w workspace:

```text
~/dev/workspace/rv
├── tools
│   └── rv-launcher
├── tokens
│   └── tokens.json
└── series
    └── inf
        └── 03
```

`rvctl` pracuje na kartach z `series_root`, czyli na katalogu
`~/dev/workspace/rv/series`.

### Po uruchomieniu środowiska kontenerowego

Repo `rv32i-hazard3-env` jest potrzebne dopiero przy uruchamianiu środowiska
kontenerowego. Wtedy pojawia się pod `tools`:

```text
~/dev/workspace/rv
├── tools
│   ├── rv-launcher
│   └── rv32i-hazard3-env
├── tokens
│   └── tokens.json
└── series
    └── inf
        └── 03
```

Repozytoria źródłowe poza workspace, na przykład `~/dev/edu/repos/rv`, są
zapleczem dla autora materiałów albo fallbackiem dla narzędzi. Nie są wymagane
do zwykłej pracy w workspace.

## Dokumentacja

- `doc/rvctl.md` - techniczna dokumentacja CLI: wszystkie komendy, argumenty
  i przełączniki
- `doc/tokens.md` - model tokenów, synchronizacja remote <-> store
- `doc/series.md` - docelowy model komend dla serii i kart pracy
- `doc/containers.md` - docelowy model komend dla środowisk kontenerowych
- `doc/tokens.schema.json` - schemat `tokens/tokens.json`
- `doc/workspace.md` - krótki opis konfiguracji workspace

README jest tylko mapą projektu. Szczegóły operacyjne trzymamy w `doc/`, żeby
nie dublować instrukcji w kilku miejscach.