# RVCTL CLI

Plik opisuje przełączniki i listę komend skryptu `rvctl`.

## Model katalogów

Repo oryginalne trzymamy poza workspace:

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

Workspace służy do klonów roboczych i ćwiczeń:

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

Typowy układ:

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

`rvctl` czyta publiczny opis serii i kart z `workspace-info`, a pobrane karty
trzyma w `series_root` w workspace. Tool repo `rv32i-hazard3-env` wybiera
najpierw z workspace, a potem z fallbacku `~/dev/edu/repos/rv`, jeśli taki klon
roboczy jeszcze nie istnieje.

Karty pracy są rozdzielone:

- `workspace_info_path` wskazuje manifest, na przykład `~/dev/workspace/rv/meta/workspace-info/workspace.json`
- `series_root` wskazuje klony robocze w workspace, na przykład `~/dev/workspace/rv/series`
- `original_series_root` zostaje fallbackiem dla lokalnych repo źródłowych

Komendy launchera pracują na `series_root`, czyli na klonach roboczych.

## Pobranie repo i przełączenie gałęzi

Repo treningowe launchera trzymaj pod:

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

Podstawowy bootstrap wygląda 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
```

Główne pliki CLI:

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

`rvctl` jest jedynym publicznym entrypointem. `rvctl.py` jest implementacją
uruchamianą przez wrapper i nie wymaga osobnego wywoływania przez ucznia.

Uruchomienie bez argumentów pokazuje tabelaryczny skrót komend:

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

### Autoryzacja

Masz dwie drogi.

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

To jest wariant dydaktyczny, jeśli uczeń ma ćwiczyć ręczne dodawanie remota z
tokenem do zdalnego endpointu. Jeśli launcher zobaczy URL w formacie
`http://LOGIN:TOKEN@...`, zapisze ten token lokalnie do `tokens/tokens.json`.

Przykład:

```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 wymagającymi autoryzacji dodaj lokalny token do:

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

Minimalny format pliku:

```json
{
  "version": 3,
  "tokens": [
    {
      "id": "r1",
      "value": "TU_WSTAW_TOKEN",
      "server": {
        "type": "gitea",
        "endpoint": "http://77.90.8.171:3001",
        "scheme": "http",
        "host": "77.90.8.171",
        "port": 3001
      },
      "user": "u1",
      "org": "edu-tools",
      "repo": "rv-launcher"
    }
  ]
}
```

Ten plik powinien być lokalny, niewersjonowany i mieć prawa `600`.

Przykład:

```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 wykonywać `clone`, `fetch` i `push`, albo gdy użytkownik po zajęciach chce
pracować z wieloma repo na swoim koncie bez wpisywania tokena do każdego
remota.

### Fetch i switch

Domyślna gałąź 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
```

Jeśli chcesz wejść na inną gałąź, na przykład `feat/x`, użyj:

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

## Wywołanie główne

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

Globalne przełączniki:

- `--config PATH`
  Używa innego pliku `workspace.json`.

Pomoc tabelaryczna:

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

Szczegółowy help parsera:

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

Komendy:

- `show-config`
- `workspace show`
- `workspace sync`
- `list-series`
- `list-cards [series]`
- `series list`
- `series use SERIES`
- `series show SERIES`
- `series fetch SERIES [--dry-run]`
- `card use CARD`
- `card use SERIES CARD`
- `series cards list SERIES`
- `series cards show SERIES CARD`
- `series cards fetch SERIES CARD`
- `series cards submission SERIES CARD --class NAME`
- `series cards tasks list SERIES CARD`
- `series cards tasks show SERIES CARD TASK`
- `series cards tasks switch SERIES CARD TASK`
- `env list`
- `env sync`
- `env build rv32i|host`
- `debug rv32i|host [TASK|CARD TASK|SERIES CARD TASK]`
- `run host [TASK|CARD TASK|SERIES CARD TASK]`
- `shell rv32i|host [CARD|SERIES CARD]`
- `tasks list [CARD|SERIES CARD]`
- `tasks show TASK|CARD TASK|SERIES CARD TASK`
- `tasks switch TASK|CARD TASK|SERIES CARD TASK`
- `tokens scan`
- `tokens compare`
- `tokens read`
- `tokens stats`
- `tokens write`
- `tokens update`
- `submission [series] [card]`
- `tmux-container [series] [card]`

## `show-config`

Wypisuje rozwiązane ścieżki z konfiguracji.

Typowy format:

```text
config_path<TAB>...
original_root<TAB>...
original_series_root<TAB>...
workspace_root<TAB>...
workspace_info_path<TAB>...
workspace_info_url<TAB>...
workspace_info_status<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
  ...
```

Przykład:

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

## `workspace show`

Pokazuje lokalizację i stan publicznego manifestu wspólnego workspace.

```bash
./rvctl workspace show
```

## `workspace sync`

Klonuje albo aktualizuje repo `edu-workspace/workspace-info` do katalogu
`~/dev/workspace/rv/meta/workspace-info`.

```bash
./rvctl workspace sync
./rvctl workspace sync --dry-run
```

Jeżeli lokalnej kopii manifestu jeszcze nie ma, komendy zależne od manifestu
same wykonują bootstrap przez `git clone`. Istniejącego manifestu nie
aktualizują automatycznie; do tego służy jawne `workspace sync`.

## `series list`

Listuje serie dostępne w `workspace-info` i workspace. Jeżeli `workspace-info`
jeszcze nie istnieje lokalnie, komenda pobiera je automatycznie. Komenda tworzy
`series_root`, jeżeli katalog jeszcze nie istnieje.

Format wyjścia:

```text
<series_id><TAB><karty_w_źródłach><TAB><karty_w_workspace><TAB><workspace_path>
```

Przykład:

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

## `series use SERIES`

Ustawia `defaults.series` w `workspace.json`.

Argumenty:

- `SERIES`
  Id serii, na przykład `inf`.

Przykład:

```bash
./rvctl series use inf
```

Typowy wynik:

```text
old_series<TAB>...
series<TAB>inf
status<TAB>updated|unchanged
config<TAB>...
```

## `series show SERIES`

Pokazuje szczegóły jednej serii.

Argumenty:

- `SERIES`
  Id serii, na przykład `inf`.

Format wyjścia:

```text
series<TAB>...
source_path<TAB>...
workspace_path<TAB>...
cards_count<TAB>...
cards<TAB>...
```

## `series fetch SERIES`

Pobiera albo aktualizuje wszystkie karty z serii.

Argumenty:

- `SERIES`
  Id serii, na przykład `inf`.

Przełączniki:

- `--dry-run`
  Pokazuje plan bez klonowania repo i bez zmian w token store.

Przykład:

```bash
./rvctl series fetch inf --dry-run
```

## `series cards list SERIES`

Listuje karty w wybranej serii.

Argumenty:

- `SERIES`
  Id serii, na przykład `inf`.

Format wyjścia:

```text
<card><TAB><repo><TAB><source|workspace><TAB><tytuł_z_README>
```

Przykład:

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

## `card use CARD`

Ustawia `defaults.card` w `workspace.json` dla aktualnie domyślnej serii.

Argumenty:

- `CARD`
  Pełna nazwa repo albo unikalny fragment, na przykład `bss`.

Przykład:

```bash
./rvctl card use bss
```

## `card use SERIES CARD`

Ustawia jednocześnie `defaults.series` i `defaults.card` w `workspace.json`.

Argumenty:

- `SERIES`
  Id serii, na przykład `inf`.
- `CARD`
  Pełna nazwa repo albo unikalny fragment, na przykład `bss`.

Przykład:

```bash
./rvctl card use inf bss
```

## `series cards show SERIES CARD`

Pokazuje szczegóły jednej karty.

Argumenty:

- `SERIES`
  Id serii, na przykład `inf`.
- `CARD`
  Pełna nazwa repo albo unikalny fragment, na przykład `bss`.

Format wyjścia:

```text
series<TAB>...
card<TAB>...
repo<TAB>...
source_path<TAB>...
workspace_path<TAB>...
source_remote<TAB>...
source_url<TAB>...
answer_remote<TAB>...
answer_url<TAB>...
tasks<TAB>...
```

## `series cards fetch SERIES CARD`

Pobiera kartę z repo źródłowego do `series_root`. `CARD` może być pełną nazwą
repo albo unikalnym fragmentem, na przykład `bss`.

Argumenty:

- `SERIES`
  Id serii, na przykład `inf`.
- `CARD`
  Pełna nazwa repo albo unikalny fragment, na przykład `bss`.

Przełączniki:

- `--dry-run`
  Pokazuje plan bez klonowania repo, bez zapisu tokena `r1a` i bez ustawiania
  remota odpowiedzi.

```bash
./rvctl series cards fetch inf bss
```

Po pobraniu komenda ustawia:

- `r1` na repo źródłowe w `edu-inf`
- `r1a` na repo pracy w `c2025-1a-inf`

`r1a` jest tworzony z tokena `r1` i wskazuje na repo o tej samej nazwie co
karta.

## `series cards submission SERIES CARD`

Alias funkcjonalny dla `submission`, ale z jawnym namespace kart.

Argumenty:

- `SERIES`
  Id serii, na przykład `inf`.
- `CARD`
  Pełna nazwa repo albo unikalny fragment, na przykład `bss`.

Przełączniki:

- `--class NAME`
  Id klasy albo grupy.
- `--nick NAME`
  Nick ucznia. Jeżeli go nie podasz, `rvctl` bierze użytkownika ze store
  tokenów.
- `--task TASK`
  Zadanie używane do zbudowania domyślnej nazwy brancha. Domyślnie
  `defaults.task` z `workspace.json`.
- `--branch NAME`
  Nadpisuje nazwę brancha odpowiedzi. Bez tego branch ma format
  `<login>T<numer_zadania>a`, na przykład `u1T1a`.
- `--date YYYY-MM-DD`
  Data zajęć widoczna w planie.
- `--source-url URL`
  Nadpisuje URL repo źródłowego.
- `--apply`
  Zapisuje remotes `r1` i `r1a` w repo karty.

Przykład:

```bash
./rvctl series cards submission inf bss --class c2025-1a-inf --apply
```

## `series cards tasks list SERIES CARD`

Listuje zadania pobranej karty. `rvctl` rozpoznaje pliki lub katalogi `task*`
w `src/tasks`, a także katalogi `task*` bezpośrednio w korzeniu karty.

Argumenty:

- `SERIES`
  Id serii, na przykład `inf`.
- `CARD`
  Pełna nazwa repo albo unikalny fragment, na przykład `bss`.

```bash
./rvctl series cards tasks list inf bss
```

## `series cards tasks show SERIES CARD TASK`

Pokazuje szczegóły jednego zadania.

Argumenty:

- `SERIES`
  Id serii, na przykład `inf`.
- `CARD`
  Pełna nazwa repo albo unikalny fragment, na przykład `bss`.
- `TASK`
  Pełna nazwa zadania albo unikalny fragment, na przykład `task1`.

```bash
./rvctl series cards tasks show inf bss task1
```

## `series cards tasks switch SERIES CARD TASK`

Tworzy albo przełącza lokalny branch pracy dla zadania.

Argumenty:

- `SERIES`
  Id serii, na przykład `inf`.
- `CARD`
  Pełna nazwa repo albo unikalny fragment, na przykład `bss`.
- `TASK`
  Pełna nazwa zadania albo unikalny fragment, na przykład `task4` albo `4`.

Przełączniki:

- `--branch NAME`
  Nadpisuje automatyczną nazwę brancha.
- `--dry-run`
  Pokazuje plan bez przełączania brancha.

Domyślna nazwa brancha powstaje z użytkownika w `tokens.json`, numeru zadania i
końcówki `a`. Dla użytkownika `u1` i zadania `task4_stack_strlen` będzie to
`u1T4a`. Komenda ustawia też upstream brancha na `r1a/u1T4a`.

```bash
./rvctl series cards tasks switch inf bss 4
```

## `tasks list`

Skrót do listowania zadań z domyślnej karty z `workspace.json`.

```bash
./rvctl tasks list
```

Opcjonalnie można wskazać kartę albo serię i kartę:

```bash
./rvctl tasks list bss
./rvctl tasks list inf bss
```

## `tasks show TASK`

Skrót do podglądu zadania z domyślnej karty.

```bash
./rvctl tasks show 4
./rvctl tasks show bss 4
./rvctl tasks show inf bss 4
```

## `tasks switch TASK`

Skrót do przełączenia na branch odpowiedzi dla zadania z domyślnej karty.

```bash
./rvctl tasks switch 4
```

Ta komenda działa tak samo jak pełna forma:

```bash
./rvctl series cards tasks switch inf bss 4
```

## `env list`

Pokazuje profile środowiska kontenerowego obsługiwane przez `rvctl`.

```bash
./rvctl env list
```

Profile:

- `rv32i` - RISC-V/Hazard3, `nvim`, `tmux`, `gdb-multiarch`
- `host` - natywny kontener z `clang`, `gcc`, `gdb`, opcjonalnie `lldb`

## `env sync`

Klonuje albo aktualizuje repo `rv32i-hazard3-student-env` do katalogu
`~/dev/workspace/rv/tools/rv32i-hazard3-student-env`.

```bash
./rvctl env sync
./rvctl env sync --dry-run
```

## `env build rv32i|host`

Buduje wybrany profil `docker compose`.

```bash
./rvctl env build rv32i
./rvctl env build host
./rvctl env build host --dry-run
```

## `debug rv32i|host`

Uruchamia debugowanie zadania w kontenerze. Selektor może być pełny albo krótki.

```bash
./rvctl debug rv32i inf bss 1
./rvctl debug host inf bss 1
./rvctl debug rv32i 4
./rvctl debug host 4
./rvctl debug rv32i 4 --pane 0
./rvctl debug rv32i 4 pane node:0
```

`rv32i` uruchamia symulator Hazard3, `gdb-multiarch` i `nvim`. `host` kompiluje
zadanie natywnie i otwiera `gdb` obok `nvim`. Profil `host` jest przeznaczony
dla tasków C z funkcją `main`; taski czysto asemblerowe debugujemy w profilu
`rv32i`.

Przełączniki:

- `--task TASK` - nadpisuje zadanie z selektora albo z `workspace.json`
- `--instance NAME` - ustawia nazwę instancji kontenera/tmuxa
- `--editor nvim|vim` - wybiera edytor w kontenerze
- `--pane TARGET` - wysyła wygenerowaną komendę do istniejącego panelu tmuxa
  na hoście
- `--dry-run` - pokazuje komendę bez uruchamiania Dockera

`--pane 0` oznacza panel `0` w bieżącym oknie tmuxa. `pane node:0` oznacza
okno `node`, panel `0`. Natywne targety tmuxa, na przykład `%3` albo
`:node.0`, też są obsługiwane.

## `run host`

Buduje i uruchamia wybrane zadanie natywnie w kontenerze `host`.

```bash
./rvctl run host inf bss 1
./rvctl run host 4
./rvctl run host 4 --pane node:0
```

Profil `rv32i` pracuje obecnie przez `debug rv32i`, bo wymaga symulatora
Hazard3 i połączenia GDB.

## `shell rv32i|host`

Otwiera shell w wybranym profilu kontenera z podmontowaną kartą.

```bash
./rvctl shell rv32i inf bss
./rvctl shell host inf bss
./rvctl shell host --dry-run
./rvctl shell rv32i --pane 0
```

## `list-series`

Alias kompatybilności dla `series list`.

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

## `list-cards [series]`

Alias kompatybilności dla `series cards list SERIES`.

Argumenty:

- `series`
  Opcjonalne id serii, na przykład `inf`.
  Jeśli go brak, brana jest domyślna seria z `workspace.json`.

Przykłady:

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

## `tokens scan`

Czyta remote URL-e w repo i pokazuje diagnostyczną tabelę git remotes:
`auth`, `plain` i `unsupported`. Nie porównuje ich z `tokens.json`. Komenda
jest read-only.

Przełączniki:

- `--repo PATH`
  Ścieżka wewnątrz docelowego repo. Domyślnie repo zawierające `rvctl`.
- `--server ENDPOINT`
  Pokazuje tylko wpisy z danego endpointu.

Typowy wynik:

```text
remotes
item  remote  kind         server  proto  host                org        repo         user  token         result          url
----  ------  -----------  ------  -----  ------------------  ---------  -----------  ----  ------------  --------------  --------------------------------------
1     r1      auth         gitea   http   77.90.8.171:3001    edu-tools  rv-launcher  u1    e59cc...13be  found           http://77.90.8.171:3001/edu-tools/...
```

Przykład:

```bash
./rvctl tokens scan
./rvctl tokens scan --repo ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack
```

## `tokens compare`

Czyta remote URL-e w repo oraz lokalny `tokens.json`, łączy wpisy w pary po
endpoincie, nazwie remota, token id, wartości tokena, org i repo, a potem
pokazuje jeden logiczny wiersz na token. Komenda jest read-only.

Przełączniki:

- `--repo PATH`
  Ścieżka wewnątrz docelowego repo. Domyślnie repo zawierające `rvctl`.

Typowy wynik:

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

`token_ref` jest komórką stałej szerokości: nazwa tokena jest po lewej, a marker
po prawej. Nazwa tokena jest taka sama jak nazwa git remote, np. `r1`. Marker
`*` oznacza, że remote i `tokens.json` są zgodne. Marker `R` oznacza token tylko
w remote, a `S` token tylko w `tokens.json`.

Maski uprawnień:

- `scope` ma pozycje `aAimnopru`: activitypub, admin, issue, misc, notification, organization, package, repository, user
- w `scope`: `w` oznacza read/write, `r` read, `-` brak dostępu
- `org` ma pozycje `oawrc`: owner, admin, write, read, create repo
- `repo` ma pozycje `oawr`: owner, admin, write, read
- `+` oznacza włączone, `-` wyłączone, `?` nie wczytano, `!` błąd wczytania
- `valid` pokazuje `forever`, lokalne `expires_at`, `invalid`, `?` albo `!`

Przykład:

```bash
./rvctl tokens compare
./rvctl tokens compare --repo ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack
```

## `tokens list store|remote|both`

Wypisuje jedno źródło bez porównywania go z drugim. `list` jest read-only:
pokazuje co jest w `tokens.json`, co jest w git remote albo oba źródła jako
osobne wiersze. `compare` służy do porównania zgodności.

Przełączniki:

- `--repo PATH`
  Repo, z którego listowane są git remotes. Domyślnie repo zawierające `rvctl`.
- `--server ENDPOINT`
  Ogranicza wynik do jednego endpointu.

Typowy wynik:

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

Przykłady:

```bash
./rvctl tokens list store
./rvctl tokens list remote
./rvctl tokens list both
```

## `tokens add REMOTE_ID`

Dodaje pusty szkielet tokena do `tokens.json`. `REMOTE_ID` musi być taki sam
jak nazwa git remote, np. `r1`. Pole `value` jest puste i trzeba je uzupełnić
ręcznie przed użyciem tokena.

Przełączniki:

- `--server ENDPOINT`
  Endpoint serwera. Domyślnie `git.base_url` z `workspace.json`.
- `--value TOKEN`
  Opcjonalna wartość tokena. Domyślnie pusta.
- `--user NAME`
  Login używany w URL-u auth, np. `u1`.
- `--remote NAME`
  Alias zgodności. Jeśli podany, musi być taki sam jak `REMOTE_ID`.
- `--org NAME`
  Opcjonalna organizacja dla remota.
- `--repo NAME`
  Opcjonalne repo dla remota.
- `--dry-run`
  Pokazuje plan bez zapisu.

Przykłady:

```bash
./rvctl tokens add r1
./rvctl tokens add r1 --user u1 --org edu-tools --repo rv-launcher
```

## `tokens sync remote REMOTE_ID`

Czyta dane auth z git remote `REMOTE_ID` i zapisuje je do `tokens.json`. Nie
pobiera metadanych z API.

Przełączniki:

- `--repo PATH`
  Ścieżka wewnątrz docelowego repo. Domyślnie repo zawierające `rvctl`.
- `--dry-run`
  Pokazuje plan bez zapisu.

Przykład:

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

## `tokens sync store REMOTE_ID`

Zapisuje dane auth z rekordu `REMOTE_ID` w `tokens.json` do git remote o tej
samej nazwie. Jeśli remote jeszcze nie istnieje, URL jest budowany z pól
`server.endpoint`, `org` i `repo` w `tokens.json`.

Jeżeli repo ma tylko remote `origin` wskazujący ten sam URL, `sync store`
automatycznie przemianuje `origin` na `REMOTE_ID` przed wpisaniem credentials.

Przełączniki:

- `--repo PATH`
  Ścieżka wewnątrz docelowego repo. Domyślnie bieżący katalog.
- `--url URL`
  Opcjonalny URL remota. Nadpisuje URL zbudowany z `tokens.json`.
- `--server ENDPOINT`
  Endpoint serwera z `tokens.json`.
- `--replace`
  Nadpisuje inne dane auth już wpisane w remote URL.
- `--dry-run`
  Pokazuje plan bez zapisu.

Przykład:

```bash
./rvctl tokens sync store r1 --repo ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack
```

## `tokens remove store|remote|both REMOTE_ID`

Usuwa rekord z `tokens.json`, git remote albo oba miejsca.
Domyślnym repo dla `remote` i `both` jest repo, w którym leży `rvctl`. Inne
repo można wskazać przez `--repo PATH`.

Przełączniki:

- `--repo PATH`
  Repo, z którego ma być usunięty git remote. Domyślnie repo zawierające
  `rvctl`.
- `--server ENDPOINT`
  Endpoint serwera, jeśli `tokens.json` ma kilka rekordów o tym samym `id`.
- `--dry-run`
  Pokazuje plan bez usuwania.

Przykłady:

```bash
./rvctl tokens remove store r1
./rvctl tokens remove remote r1
./rvctl tokens remove both r1
./rvctl tokens remove remote r1 --repo ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack
```

## `tokens read`

Pokazuje zawartość `tokens/tokens.json` w podziale na endpointy serwerów.

Przełączniki:

- `--server ENDPOINT`
  Ogranicza wynik do jednego endpointu.
- `--show-secrets`
  Pokazuje pełne wartości tokenów 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
tokens<TAB>1
id<TAB>r1<TAB>SE****23
user<TAB>r1<TAB>u1
```

Przykład:

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

## `tokens stats`

Pokazuje statystyki endpointów z repo i `tokens.json`, a także ich zgodność
względem siebie.

Przełączniki:

- `--repo PATH`
  Ścieżka wewnątrz repo, z którego mają być odczytane remote URL-e.
- `--server ENDPOINT`
  Ogranicza wynik do jednego endpointu.

Typowy wynik:

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

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

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

Przykład:

```bash
./rvctl tokens stats --repo ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack
```

## `tokens write`

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

Przełączniki:

- `--repo PATH`
  Ścieżka wewnątrz docelowego repo. Domyślnie bieżący katalog.
- `--remote NAME`
  Nazwa remota do aktualizacji lub utworzenia.
- `--url URL`
  Opcjonalny URL remota. Nadpisuje URL zbudowany z `tokens.json`.
- `--server ENDPOINT`
  Endpoint serwera z `tokens.json`.
- `--user NAME`
  Użytkownik z wybranego endpointu.
- `--token-name NAME`
  Remote id w `tokens.json`, na przykład `r1`. Domyślnie wartość `--remote`.
- `--replace`
  Nadpisuje inne dane auth już wpisane w remote URL.
- `--dry-run`
  Pokazuje plan bez zapisu.

Przykład:

```bash
./rvctl tokens write --repo ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack --remote r1 --server http://77.90.8.171:3001
```

## `tokens update REMOTE_ID`

Pobiera z API metadane dla rekordu `REMOTE_ID` zapisanego w `tokens.json`.
Nie synchronizuje sekretu z git remote.

Przełączniki:

- `--server ENDPOINT`
  Opcjonalny wybór endpointu, jeśli ten sam `REMOTE_ID` istnieje dla wielu serwerów.
- `--dry-run`
  Pokazuje plan bez zapisu.

Przykład:

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

## `tokens update --from ...`

Komendy zgodności dla starego modelu kierunkowego.

Przełączniki:

- `--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`
  Ścieżka wewnątrz repo.
- `--remote NAME`
  Wymagane dla `--from store`.
- `--url URL`
  Opcjonalny URL dla `--from store`.
- `--server ENDPOINT`
  Opcjonalny wybór endpointu dla `--from store`.
- `--user NAME`
  Opcjonalny wybór usera dla `--from store`.
- `--token-name NAME`
  Opcjonalny wybór remote id dla `--from store`.
- `--replace`
  Nadpisuje inne auth przy `--from store`.
- `--dry-run`
  Pokazuje plan bez zapisu.

Przykłady:

```bash
./rvctl tokens update --from remotes --repo ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack
./rvctl tokens update --from store --repo ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack --remote r1 --server http://77.90.8.171:3001
```

## `submission [series] [card]`

Wylicza przepływ oddawania rozwiązań:

- `r1` jako repo z materiałem z `edu-inf`
- `r1a` jako repo odpowiedzi w `c2025-1a-inf`
- branch ucznia liczony ze store tokenów i zadania

Nazwa repo odpowiedzi jest taka sama jak nazwa repo źródłowego karty:

```text
<repo_z_edu-inf>
```

Przykład:

```text
lab-rv32i-strlen-bss-data-stack
```

Argumenty pozycyjne:

- `series`
  Id serii albo pełny selector, na przykład `inf` albo `inf/bss`.
- `card`
  Karta albo unikalny fragment nazwy repo, na przykład `bss`.

Przełączniki:

- `--class NAME`
  Id klasy albo grupy, na przykład `c2025-1a-inf`.
- `--nick NAME`
  Nick ucznia. Jeżeli go nie podasz, `rvctl` bierze użytkownika ze store
  tokenów.
- `--task TASK`
  Zadanie używane do zbudowania domyślnej nazwy brancha. Domyślnie
  `defaults.task` z `workspace.json`.
- `--branch NAME`
  Nadpisuje domyślną nazwę brancha. Bez tego branch ma format
  `<login>T<numer_zadania>a`, na przykład `u1T1a`.
- `--date YYYY-MM-DD`
  Data zajęć. Zostaje w raporcie, ale nie zmienia nazwy repo odpowiedzi.
- `--source-url URL`
  Nadpisuje URL repo źródłowego. Bez tego launcher czyta `r1` albo `origin` z
  repo karty.
- `--apply`
  Dodaje albo aktualizuje remote `r1` i `r1a` w repo karty.

Typowy format wyjścia:

```text
selector<TAB>inf/bss
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>r1a
answer_repo<TAB>c2025-1a-inf/lab-rv32i-strlen-bss-data-stack
answer_url<TAB>http://77.90.8.171:3001/c2025-1a-inf/lab-rv32i-strlen-bss-data-stack.git
student_user<TAB>u1
student_branch<TAB>u1T1a
```

Przykłady:

```bash
./rvctl submission inf bss --class c2025-1a-inf
./rvctl submission inf bss --class c2025-1a-inf --task 4 --apply
./rvctl series cards submission inf bss --class c2025-1a-inf --branch u1T4a
```

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

Tworzy nową sesję `tmux` i uruchamia kontener w `pane 0`.

Argumenty pozycyjne:

- `series`
  Id serii albo pełny selector, na przykład `inf` albo `inf/bss`.
- `card`
  Karta albo unikalny fragment nazwy repo, na przykład `bss`.

Przełączniki:

- `--session NAME`
  Nadpisuje nazwę sesji `tmux`.
- `--window NAME`
  Nadpisuje nazwę okna `tmux`.
- `--instance NAME`
  Ustawia `RV_INSTANCE` dla wrappera `rv`.
- `--attach`
  Po utworzeniu sesji robi `tmux attach`.
- `--dry-run`
  Nie uruchamia `tmux`; wypisuje selector, ścieżki i końcową komendę.

Reguły wyboru karty:

- `tmux-container inf bss` -> seria `inf`, karta `bss`
- `tmux-container inf/bss` -> pełny selector
- `tmux-container bss` -> domyślna seria + karta `bss`
- `tmux-container inf` -> seria `inf` + domyślna karta
- bez argumentów -> domyślna seria i domyślna karta

Przykłady:

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