stem-launcher/README.md

# RV Launcher

Repo `rv-launcher` zawiera narzedzie do pracy z workspace RISC-V. W pierwszej
kolejnosci sluzy ono do zarzadzania tokenami; pozostale funkcje obejmuja prace
z kartami pracy i uruchamianie srodowiska kontenerowego.

Wlasciwym skryptem CLI jest wykonywalny plik `rvctl.py`. To on implementuje
zarzadzanie tokenami, listowanie serii i kart, przygotowanie repo odpowiedzi i
start kontenera.

Publicznym entrypointem dla uzytkownika jest krotki wrapper `rvctl`:

```bash
./rvctl
```

Wrapper uruchamia:

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

`rvctl.py` mozna tez uruchomic bezposrednio:

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

Sciezki i domyslne ustawienia sa trzymane w `workspace.json`.

## Co robi narzedzie

`rvctl` porzadkuje prace w trzech obszarach.

1. Zarzadzanie tokenami

   Narzedzie obsluguje lokalny store `tokens/tokens.json`, porownuje go z git
   remotes i potrafi synchronizowac token w obie strony. Szczegoly modelu,
   format pliku i opis komend sa w `doc/tokens.md`.

2. Listowanie i pobieranie kart pracy

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

3. Uruchamianie srodowiska programistycznego w kontenerach

   Dla wybranej karty `rvctl` uruchamia sesje tmux i kontener z przygotowanym
   srodowiskiem developerskim. Docelowy model namespace `containers` jest w
   `doc/containers.md`.

## Model katalogow

Podstawowym miejscem pracy uzytkownika jest workspace:

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

Minimalny uklad po starcie zawiera launcher, katalog tokenow i katalog na karty:

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

Sa dwie drogi startu.

### Bez `tokens.json`

Jesli nie masz jeszcze pliku z tokenem albo tokenami, zacznij od pustego repo
launchera i remota z tokenem:

```bash
mkdir -p ~/dev/workspace/rv/tools/rv-launcher
cd ~/dev/workspace/rv/tools/rv-launcher
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
```

Potem wczytaj token z remota do lokalnego store:

```bash
./rvctl tokens sync remote r1
./rvctl tokens update r1
```

Po tym kroku workspace ma juz lokalny store:

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

Na koniec sprawdz, czy git remote i lokalny store widza ten sam token:

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

Przykladowy 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  +++++   ++++
```

Najwazniejsze pola:

- `remote` - nazwa git remota, tutaj `r1`
- `token_ref` - lokalna nazwa tokena i marker zgodnosci 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 calego tokena
- `valid`, `scope`, `org`, `repo` - metadane i uprawnienia pobrane przez
  `tokens update`

Pelny opis tabeli tokenow jest w `doc/tokens.md`.

### Z `tokens.json`

Jesli masz gotowy plik `tokens.json`, zacznij od skopiowania go do workspace:

```bash
mkdir -p ~/dev/workspace/rv/tokens
cp tokens.json ~/dev/workspace/rv/tokens/tokens.json
chmod 600 ~/dev/workspace/rv/tokens/tokens.json
```

Nastepnie pobierz albo przygotuj `rv-launcher` w:

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

Po wejsciu do repo launchera sprawdz store tokenow:

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

### Po pobraniu kart pracy

Karty trafiaja 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 srodowiska kontenerowego

Repo `rv32i-hazard3-env` jest potrzebne dopiero przy uruchamianiu srodowiska
kontenerowego. Wtedy pojawia sie pod `tools`:

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

Repozytoria zrodlowe poza workspace, na przyklad `~/dev/edu/repos/rv`, sa
zapleczem dla autora materialow albo fallbackiem dla narzedzi. Nie sa wymagane
do zwyklej pracy w workspace.

## Szybki start

Najpierw zobacz konfiguracje i dostepne komendy:

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

Typowy przeplyw 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 narzedzie cos zmieni.

## Dokumentacja

- `doc/rvctl.md` - techniczna dokumentacja CLI: wszystkie komendy, argumenty
  i przelaczniki
- `doc/tokens.md` - model tokenow, synchronizacja remote <-> store
- `doc/series.md` - docelowy model komend dla serii i kart pracy
- `doc/containers.md` - docelowy model komend dla srodowisk kontenerowych
- `doc/tokens.schema.json` - schemat `tokens/tokens.json`
- `doc/workspace.md` - krotki opis konfiguracji workspace

README jest tylko mapa projektu. Szczegoly operacyjne trzymamy w `doc/`, zeby
nie dublowac instrukcji w kilku miejscach.