stem-launcher/doc/rvctl.md

# RVCTL CLI

Plik opisuje przelaczniki i liste komend skryptu `rvctl`.

## Model katalogow

Repo oryginalne trzymamy poza workspace:

```bash
~/dev/edu/repos/rv
```

Workspace sluzy do klonow roboczych i cwiczen:

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

Typowy uklad:

```text
~/dev/edu/repos/rv/rv-launcher
~/dev/edu/repos/rv/rv32i-hazard3-env
~/dev/edu/repos/rv/series/<seria>/<karta>
~/dev/workspace/rv/tools/rv-launcher
~/dev/workspace/rv/tools/rv32i-hazard3-env
~/dev/workspace/rv/series/<seria>/<karta>
```

`rvctl` czyta karty z `series_root` w workspace. Tool repo
`rv32i-hazard3-env` wybiera najpierw z workspace, a potem z fallbacku
`~/dev/edu/repos/rv`, jesli taki klon roboczy jeszcze nie istnieje.

Karty pracy tez sa rozdzielone:

- `original_series_root` wskazuje repo zrodlowe kart, na przyklad `~/dev/edu/repos/rv/series`
- `series_root` wskazuje klony testowe w workspace, na przyklad `~/dev/workspace/rv/series`

Komendy launchera pracuja na `series_root`, czyli na klonach testowych.

## Pobranie repo i przelaczenie galezi

Repo treningowe launchera trzymaj pod:

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

Podstawowy bootstrap wyglada tak:

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

Glowne pliki CLI:

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

`rvctl` jest jedynym publicznym entrypointem. `rvctl.py` jest implementacja
uruchamiana przez wrapper i nie wymaga osobnego wywolywania przez ucznia.

Uruchomienie bez argumentow pokazuje tabelaryczny skrot komend:

```bash
./rvctl
./rvctl tokens
./rvctl help tokens
```

### Autoryzacja

Masz dwie drogi.

#### Droga 1: remote `r1` z tokenem w URL

To jest wariant dydaktyczny, jesli uczen ma cwiczyc reczne dodawanie remota z
tokenem do zdalnego endpointu. Jesli launcher zobaczy URL w formacie
`http://LOGIN:TOKEN@...`, zapisze ten token lokalnie do `tokens/tokens.json`.

Przyklad:

```bash
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
```

#### Droga 2: lokalny `tokens/tokens.json`

Przed operacjami wymagajacymi autoryzacji dodaj lokalny token do:

```bash
~/dev/workspace/rv/tokens/tokens.json
```

Minimalny format pliku:

```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": "TU_WSTAW_TOKEN"
          }
        }
      }
    }
  }
}
```

Ten plik powinien byc lokalny, niewersjonowany i miec prawa `600`.

Przyklad:

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

Wariant z `tokens/tokens.json` jest wygodniejszy wtedy, gdy launcher ma
sam wykonywac `clone`, `fetch` i `push`, albo gdy uzytkownik po zajeciach chce
pracowac z wieloma repo na swoim koncie bez wpisywania tokena do kazdego
remota.

### Fetch i switch

Domyslna galaz launchera to `main`.

Po sklonowaniu:

```bash
git fetch origin main
git switch main
git pull --ff-only
```

Wariant przez `r1`:

```bash
git fetch r1 main
git switch --track -c main r1/main
git pull --ff-only r1 main
```

Jesli chcesz wejsc na inna galaz, na przyklad `feat/x`, uzyj:

```bash
git fetch origin feat/x
git switch --track -c feat/x origin/feat/x
```

Wariant przez `r1`:

```bash
git fetch r1 feat/x
git switch --track -c feat/x r1/feat/x
```

## Wywolanie glowne

```bash
./rvctl [--config PATH] <komenda> [opcje]
```

Globalne przelaczniki:

- `--config PATH`
  Uzywa innego pliku `workspace.json`.

Pomoc tabelaryczna:

```bash
./rvctl
./rvctl help
./rvctl tokens
./rvctl help tokens
```

Szczegolowy help parsera:

```bash
./rvctl --help
./rvctl <komenda> --help
./rvctl tokens <komenda> --help
```

Komendy:

- `show-config`
- `list-series`
- `list-cards [series]`
- `tokens scan`
- `tokens read`
- `tokens stats`
- `tokens write`
- `tokens update`
- `submission [series] [card]`
- `tmux-container [series] [card]`

## `show-config`

Wypisuje rozwiazane sciezki z konfiguracji.

Typowy format:

```text
config_path<TAB>...
original_root<TAB>...
original_series_root<TAB>...
workspace_root<TAB>...
series_root<TAB>...
socket_root<TAB>...
token_path<TAB>...
tools_root<TAB>...
git_base_url<TAB>...
git_source_org<TAB>...
git_answer_org<TAB>...
git_source_remote<TAB>...
git_answer_remote<TAB>...
git_origin_remote<TAB>...
git_fallback_branch<TAB>...
tools_root_candidates
  ...
```

Przyklad:

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

## `list-series`

Listuje katalogi serii znalezione w `series_root`.

Kazda linia ma format:

```text
<series_id><TAB><liczba_kart><TAB><pelna_sciezka>
```

Przyklad:

```bash
./rvctl list-series
```

## `list-cards [series]`

Listuje karty z wybranej serii.

Argumenty:

- `series`
  Opcjonalne id serii, na przyklad `inf`.
  Jesli go brak, brana jest domyslna seria z `workspace.json`.

Format wyjscia:

```text
<card_no><TAB><tytul_z_README><TAB><pelna_sciezka>
```

Jesli `README.md` nie ma naglowka `#`, skrypt wypisuje:

```text
<card_no><TAB><pelna_sciezka>
```

Przyklady:

```bash
./rvctl list-cards
./rvctl list-cards inf
```

## `tokens scan`

Skanuje remote URL-e w repo i zapisuje znalezione dane do `tokens/tokens.json`.

Przelaczniki:

- `--repo PATH`
  Sciezka wewnatrz docelowego repo. Domyslnie biezacy katalog.
- `--verbose`
  Pokazuje dodatkowo sekcje `context` i `scan`.

Typowy wynik:

```text
items
item<TAB>source<TAB>remote<TAB>kind<TAB>user<TAB>token<TAB>result<TAB>status<TAB>url
1<TAB>repo<TAB>r1<TAB>auth<TAB>u1<TAB>remote<TAB>existing<TAB>in_sync<TAB>http://77.90.8.171:3001
1<TAB>tokens.json<TAB><TAB>store<TAB>u1<TAB>t1<TAB>present<TAB>in_sync<TAB>http://77.90.8.171:3001
```

Jesli remote istnieje, ale ma URL bez `LOGIN:TOKEN@`, wynik bedzie mial
w wierszu `repo` wartosci `kind=plain` i `result=no_credentials`. Jezeli
ten sam endpoint istnieje w `tokens.json`, drugi wiersz tego samego `item`
pokaze `source=tokens.json`, `token=t1` i `result=present`.

Przyklad:

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

## `tokens read`

Pokazuje zawartosc `tokens/tokens.json` w podziale na endpointy serwerow.

Przelaczniki:

- `--server ENDPOINT`
  Ogranicza wynik do jednego endpointu.
- `--show-secrets`
  Pokazuje pelne wartosci tokenow zamiast maskowania.

Typowy wynik:

```text
token_path<TAB>...
endpoint<TAB>http://77.90.8.171:3001
type<TAB>gitea
scheme<TAB>http
host<TAB>77.90.8.171
port<TAB>3001
users<TAB>1
tokens<TAB>1
user<TAB>u1
token<TAB>t1<TAB>SE****23
```

Przyklad:

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

## `tokens stats`

Pokazuje statystyki endpointow z repo i `tokens.json`, a takze ich zgodnosc
wzgledem siebie.

Przelaczniki:

- `--repo PATH`
  Sciezka wewnatrz repo, z ktorego maja byc odczytane remote URL-e.
- `--server ENDPOINT`
  Ogranicza wynik do jednego endpointu.

Typowy wynik:

```text
context
item<TAB>value
repo_root<TAB>...
token_path<TAB>...

items
item<TAB>source<TAB>remote<TAB>kind<TAB>user<TAB>token<TAB>result<TAB>status<TAB>url
1<TAB>repo<TAB>r1<TAB>plain<TAB><TAB><TAB>no_credentials<TAB>store_ahead<TAB>http://77.90.8.171:3001
1<TAB>tokens.json<TAB><TAB>store<TAB>u1<TAB>t1<TAB>present<TAB>store_ahead<TAB>http://77.90.8.171:3001

status
item<TAB>value
store_ahead<TAB>1
```

Przyklad:

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

## `tokens write`

Wpisuje dane z `tokens/tokens.json` do wybranego remota repo.

Przelaczniki:

- `--repo PATH`
  Sciezka wewnatrz docelowego repo. Domyslnie biezacy katalog.
- `--remote NAME`
  Nazwa remota do aktualizacji lub utworzenia.
- `--url URL`
  URL remota, jesli remote jeszcze nie istnieje.
- `--server ENDPOINT`
  Endpoint serwera z `tokens.json`.
- `--user NAME`
  Uzytkownik z wybranego endpointu.
- `--token-name NAME`
  Nazwa tokena, na przyklad `t1`.
- `--replace`
  Nadpisuje inne dane auth juz wpisane w remote URL.
- `--dry-run`
  Pokazuje plan bez zapisu.

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.

Przelaczniki:

- `--from remotes`
  Skanuje remote URL-e i zapisuje wynik do `tokens.json`.
- `--from store`
  Bierze dane z `tokens.json` i wpisuje je do remota repo.
- `--repo PATH`
  Sciezka wewnatrz repo.
- `--remote NAME`
  Wymagane dla `--from store`.
- `--url URL`
  Opcjonalny URL dla `--from store`.
- `--server ENDPOINT`
  Opcjonalny wybor endpointu dla `--from store`.
- `--user NAME`
  Opcjonalny wybor usera dla `--from store`.
- `--token-name NAME`
  Opcjonalny wybor tokena dla `--from store`.
- `--replace`
  Nadpisuje inne auth przy `--from store`.
- `--dry-run`
  Pokazuje plan bez zapisu przy `--from store`.

Przyklady:

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

## `submission [series] [card]`

Wylicza flow oddawania rozwiazan:

- `r1` jako repo z materialem z `edu-inf`
- `a1` jako repo odpowiedzi w `zsl-inf`
- branch ucznia na podstawie jego nicku

Nazwa repo odpowiedzi jest budowana z nazwy repo zrodlowego z `edu-inf`, klasy
i daty:

```text
<repo_z_edu-inf>-<klasa>-<data>
```

Przyklad:

```text
lab-rv32i-strlen-bss-data-stack-4i-2026-04-26
```

Argumenty pozycyjne:

- `series`
  Id serii albo pelny selector, na przyklad `inf` albo `inf/03`.
- `card`
  Numer karty, na przyklad `03`.

Przelaczniki:

- `--class NAME`
  Id klasy, na przyklad `4i`.
- `--nick NAME`
  Nick ucznia. Domyslnie z niego powstaje nazwa brancha.
- `--branch NAME`
  Nadpisuje domyslna nazwe brancha.
- `--date YYYY-MM-DD`
  Data zajec uzywana w nazwie repo odpowiedzi. Domyslnie dzisiejsza.
- `--source-url URL`
  Nadpisuje URL repo zrodlowego. Bez tego launcher czyta `origin` z repo karty.
- `--apply`
  Dodaje albo aktualizuje remote `r1` i `a1` w repo karty.

Typowy format wyjscia:

```text
selector<TAB>inf/03
card_path<TAB>...
source_repo<TAB>edu-inf/lab-rv32i-strlen-bss-data-stack
source_remote<TAB>r1
source_url<TAB>http://77.90.8.171:3001/edu-inf/lab-rv32i-strlen-bss-data-stack.git
source_branch<TAB>deploy
answer_remote<TAB>a1
answer_repo<TAB>zsl-inf/lab-rv32i-strlen-bss-data-stack-4i-2026-04-26
answer_url<TAB>http://77.90.8.171:3001/zsl-inf/lab-rv32i-strlen-bss-data-stack-4i-2026-04-26.git
student_branch<TAB>u1
```

Przyklady:

```bash
./rvctl submission inf 03 --class 4i --nick u1
./rvctl submission inf 03 --class 4i --nick u1 --apply
./rvctl submission inf/03 --class 4i --nick u2 --date 2026-04-26
```

## `tmux-container [series] [card]`

Tworzy nowa sesje `tmux` i uruchamia kontener w `pane 0`.

Argumenty pozycyjne:

- `series`
  Id serii albo pelny selector, na przyklad `inf` albo `inf/03`.
- `card`
  Numer karty, na przyklad `03`.

Przelaczniki:

- `--session NAME`
  Nadpisuje nazwe sesji `tmux`.
- `--window NAME`
  Nadpisuje nazwe okna `tmux`.
- `--instance NAME`
  Ustawia `RV_INSTANCE` dla wrappera `rv`.
- `--attach`
  Po utworzeniu sesji robi `tmux attach`.
- `--dry-run`
  Nie uruchamia `tmux`; wypisuje selector, sciezki i koncowa komende.

Reguly wyboru karty:

- `tmux-container inf 03` -> seria `inf`, karta `03`
- `tmux-container inf/03` -> pelny selector
- `tmux-container 03` -> domyslna seria + karta `03`
- `tmux-container inf` -> seria `inf` + domyslna karta
- bez argumentow -> domyslna seria i domyslna karta

Przyklady:

```bash
./rvctl tmux-container 03 --dry-run
./rvctl tmux-container inf 03 --session rv-inf03
./rvctl tmux-container inf/03 --attach
```