stem-launcher/doc/rvctl.md

RVCTL CLI

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

Model katalogów

Repo oryginalne trzymamy poza workspace:

~/dev/edu/repos/rv

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

~/dev/workspace/rv

Typowy układ:

~/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, jeśli taki klon roboczy jeszcze nie istnieje.

Karty pracy też są rozdzielone:

• original_series_root wskazuje repo źródłowe kart, na przykład ~/dev/edu/repos/rv/series
• series_root wskazuje klony testowe w workspace, na przykład ~/dev/workspace/rv/series

Komendy launchera pracują na series_root, czyli na klonach testowych.

Pobranie repo i przełączenie gałęzi

Repo treningowe launchera trzymaj pod:

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

Podstawowy bootstrap wygląda tak:

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:

./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:

./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:

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:

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

Minimalny format pliku:

{
  "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:

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:

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

Wariant przez r1:

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:

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

Wariant przez r1:

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

Wywołanie główne

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

Globalne przełączniki:

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

Pomoc tabelaryczna:

./rvctl
./rvctl help
./rvctl tokens
./rvctl help tokens

Szczegółowy help parsera:

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

Komendy:

• show-config
• list-series
• list-cards [series]
• 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:

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

Przykład:

./rvctl show-config

list-series

Listuje katalogi serii znalezione w series_root.

Każda linia ma format:

<series_id><TAB><liczba_kart><TAB><pełna_ścieżka>

Przykład:

./rvctl list-series

list-cards [series]

Listuje karty z wybranej serii.

Argumenty:

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

Format wyjścia:

<card_no><TAB><tytuł_z_README><TAB><pełna_ścieżka>

Jeśli README.md nie ma nagłówka #, skrypt wypisuje:

<card_no><TAB><pełna_ścieżka>

Przykłady:

./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:

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:

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

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:

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:

./rvctl tokens compare
./rvctl tokens compare --repo ~/dev/workspace/rv/series/inf/03

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:

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:

./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:

./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:

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

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:

./rvctl tokens sync store r1 --repo ~/dev/workspace/rv/series/inf/03

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:

./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/03

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:

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:

./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:

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:

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

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:

./rvctl tokens write --repo ~/dev/workspace/rv/series/inf/03 --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:

./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:

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

submission [series] [card]

Wylicza przepływ oddawania rozwiązań:

• r1 jako repo z materiałem z edu-inf
• a1 jako repo odpowiedzi w zsl-inf
• branch ucznia na podstawie jego nicku

Nazwa repo odpowiedzi jest budowana z nazwy repo źródłowego z edu-inf, klasy i daty:

<repo_z_edu-inf>-<klasa>-<data>

Przykład:

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

Argumenty pozycyjne:

• series Id serii albo pełny selector, na przykład inf albo inf/03.
• card Numer karty, na przykład 03.

Przełączniki:

• --class NAME Id klasy, na przykład 4i.
• --nick NAME Nick ucznia. Domyślnie z niego powstaje nazwa brancha.
• --branch NAME Nadpisuje domyślną nazwę brancha.
• --date YYYY-MM-DD Data zajęć używana w nazwie repo odpowiedzi. Domyślnie dzisiejsza.
• --source-url URL Nadpisuje URL repo źródłowego. Bez tego launcher czyta origin z repo karty.
• --apply Dodaje albo aktualizuje remote r1 i a1 w repo karty.

Typowy format wyjścia:

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

Przykłady:

./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 nową sesję tmux i uruchamia kontener w pane 0.

Argumenty pozycyjne:

• series Id serii albo pełny selector, na przykład inf albo inf/03.
• card Numer karty, na przykład 03.

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 03 -> seria inf, karta 03
• tmux-container inf/03 -> pełny selector
• tmux-container 03 -> domyślna seria + karta 03
• tmux-container inf -> seria inf + domyślna karta
• bez argumentów -> domyślna seria i domyślna karta

Przykłady:

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