# 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
./rvctl tokens compare
```

Po tym kroku workspace ma juz lokalny store:

```text
~/dev/workspace/rv
|-- tools
|   `-- rv-launcher
|-- tokens
|   `-- tokens.json
`-- series
```

### 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 compare
./rvctl tokens update r1
```

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