edu/stem-launcher
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ffd12c99055a26708d22df49c205d3910e9e0c10
stem-launcher/doc/rvctl.md
T

719 lines
16 KiB
Markdown
Raw Blame History

# 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": 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 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`
Czyta remote URL-e w repo oraz lokalny `tokens.json`, laczy wpisy w pary po
endpoincie, nazwie remota, token id, wartosci tokena, org i repo, a potem
pokazuje jeden logiczny wiersz na token. Komenda jest read-only.
Przelaczniki:
- `--repo PATH`
Sciezka wewnatrz docelowego repo. Domyslnie repo zawierajace `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 -----w--- +++++ ++++
```
`token_ref` jest komorka stalej szerokosci: nazwa tokena jest po lewej, a marker
po prawej. Nazwa tokena jest taka sama jak nazwa git remote, np. `r1`. Marker
`*` oznacza, ze remote i `tokens.json` sa zgodne. Marker `R` oznacza token tylko
w remote, a `S` token tylko w `tokens.json`.
Maski uprawnien:
- `scope` ma pozycje `aAimnopru`: activitypub, admin, issue, misc, notification, organization, package, repository, user
- w `scope`: `w` oznacza read/write, `r` read, `-` brak dostepu
- `org` ma pozycje `oawrc`: owner, admin, write, read, create repo
- `repo` ma pozycje `oawr`: owner, admin, write, read
- `+` oznacza wlaczone, `-` wylaczone, `?` nie wczytano, `!` blad wczytania
- `valid` pokazuje `forever`, lokalne `expires_at`, `invalid`, `?` albo `!`
Przyklad:
```bash
./rvctl tokens scan
./rvctl tokens scan --repo ~/dev/workspace/rv/series/inf/03
```
## `tokens list store|remote|both`
Wypisuje jedno zrodlo bez porownywania go z drugim. `list` jest read-only:
pokazuje co jest w `tokens.json`, co jest w git remote albo oba zrodla jako
osobne wiersze. `scan` sluzy do porownania zgodnosci.
Przelaczniki:
- `--repo PATH`
Repo, z ktorego listowane sa git remotes. Domyslnie repo zawierajace `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
```
Przyklady:
```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 byc taki sam
jak nazwa git remote, np. `r1`. Pole `value` jest puste i trzeba je uzupelnic
recznie przed uzyciem tokena.
Przelaczniki:
- `--server ENDPOINT`
Endpoint serwera. Domyslnie `git.base_url` z `workspace.json`.
- `--value TOKEN`
Opcjonalna wartosc tokena. Domyslnie pusta.
- `--user NAME`
Login uzywany w URL-u auth, np. `u1`.
- `--remote NAME`
Alias zgodnosci. Jesli podany, musi byc taki sam jak `REMOTE_ID`.
- `--org NAME`
Opcjonalna organizacja dla remota.
- `--repo NAME`
Opcjonalne repo dla remota.
- `--dry-run`
Pokazuje plan bez zapisu.
Przyklady:
```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.
Przelaczniki:
- `--repo PATH`
Sciezka wewnatrz docelowego repo. Domyslnie repo zawierajace `rvctl`.
- `--dry-run`
Pokazuje plan bez zapisu.
Przyklad:
```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.
Przelaczniki:
- `--repo PATH`
Sciezka wewnatrz docelowego repo. Domyslnie biezacy katalog.
- `--url URL`
URL remota, jesli remote jeszcze nie istnieje.
- `--server ENDPOINT`
Endpoint serwera z `tokens.json`.
- `--replace`
Nadpisuje inne dane auth juz wpisane w remote URL.
- `--dry-run`
Pokazuje plan bez zapisu.
Przyklad:
```bash
./rvctl tokens sync store r1 --repo ~/dev/workspace/rv/series/inf/03
```
## `tokens remove store|remote|both REMOTE_ID`
Usuwa rekord z `tokens.json`, poswiadczenia z URL-a git remota albo oba
miejsca. `tokens remove remote` zostawia sam git remote, ale zapisuje jego URL
bez `LOGIN:TOKEN@`.
Domyslnym repo dla `remote` i `both` jest repo, w ktorym lezy `rvctl`. Inne
repo mozna wskazac przez `--repo PATH`.
Przelaczniki:
- `--repo PATH`
Repo, w ktorym ma byc wyczyszczony URL git remota. Domyslnie repo
zawierajace `rvctl`.
- `--server ENDPOINT`
Endpoint serwera, jesli `tokens.json` ma kilka rekordow o tym samym `id`.
- `--dry-run`
Pokazuje plan bez usuwania.
Przyklady:
```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/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:
```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
```
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>...
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
```
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`
Remote id w `tokens.json`, na przyklad `r1`. Domyslnie wartosc `--remote`.
- `--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
```
## `tokens update REMOTE_ID`
Pobiera z API metadane dla rekordu `REMOTE_ID` zapisanego w `tokens.json`.
Nie synchronizuje sekretu z git remote.
Przelaczniki:
- `--server ENDPOINT`
Opcjonalny wybor endpointu, jesli ten sam `REMOTE_ID` istnieje dla wielu serwerow.
- `--dry-run`
Pokazuje plan bez zapisu.
Przyklad:
```bash
./rvctl tokens update r1
```
## `tokens update --from ...`
Komendy zgodnosci dla starego modelu kierunkowego.
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 remote id dla `--from store`.
- `--replace`
Nadpisuje inne auth przy `--from store`.
- `--dry-run`
Pokazuje plan bez zapisu.
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
```
## `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
```
Reference in New Issue View Git Blame Copy Permalink