stem-launcher/doc/usage.md

RV Launcher CLI

Authors

Mateusz Pabiszczak, 2026

Status

Draft

Plik opisuje przelaczniki i liste komend skryptu workspace.py.

Pobranie repo i przelaczenie galezi

Jesli trzymasz tool repo pod:

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

to podstawowy bootstrap wyglada 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

Jesli w Twoim workspace narzedzia sa poza rv/, analogiczny katalog to:

~/dev/workspace/tools/rv-launcher

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:

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:

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

Minimalny format pliku:

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

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.

Launcher umie tez przemigrowac stary plik tokens/gitea_tokens.json do nowego tokens/tokens.json.

Fetch i switch

Domyslna galaz 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

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

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

Wywolanie glowne

python3 workspace.py [--config PATH] <komenda> [opcje]

Globalne przelaczniki:

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

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:

config_path<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:

python3 workspace.py show-config

list-series

Listuje katalogi serii znalezione w series_root.

Kazda linia ma format:

<series_id><TAB><liczba_kart><TAB><pelna_sciezka>

Przyklad:

python3 workspace.py 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:

<card_no><TAB><tytul_z_README><TAB><pelna_sciezka>

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

<card_no><TAB><pelna_sciezka>

Przyklady:

python3 workspace.py list-cards
python3 workspace.py 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.

Typowy wynik:

repo_root<TAB>...
scanned<TAB>1
added<TAB>1
servers<TAB>1
token_path<TAB>...

Przyklad:

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

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:

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:

python3 workspace.py tokens read
python3 workspace.py tokens read --server http://77.90.8.171:3001

tokens stats

Pokazuje statystyki tokenow per endpoint serwera.

Przelaczniki:

• --server ENDPOINT Ogranicza wynik do jednego endpointu.

Typowy wynik:

endpoint<TAB>type<TAB>scheme<TAB>host<TAB>port<TAB>users<TAB>tokens
http://77.90.8.171:3001<TAB>gitea<TAB>http<TAB>77.90.8.171<TAB>3001<TAB>1<TAB>1

Przyklad:

python3 workspace.py tokens stats

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:

python3 workspace.py 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:

python3 workspace.py tokens update --from remotes --repo ~/dev/workspace/rv/series/inf/03
python3 workspace.py 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:

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

Przyklad:

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:

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:

python3 workspace.py submission inf 03 --class 4i --nick u1
python3 workspace.py submission inf 03 --class 4i --nick u1 --apply
python3 workspace.py 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:

python3 workspace.py tmux-container 03 --dry-run
python3 workspace.py tmux-container inf 03 --session rv-inf03
python3 workspace.py tmux-container inf/03 --attach