# RV Launcher Repo `rv-launcher` zawiera narzędzie do pracy z workspace RISC-V. W pierwszej kolejności służy ono do zarządzania tokenami; pozostałe funkcje obejmują pracę z kartami pracy i uruchamianie środowiska kontenerowego. Właściwym skryptem CLI jest wykonywalny plik `rvctl.py`. To on implementuje zarządzanie tokenami, listowanie serii i kart, przygotowanie repo odpowiedzi i start kontenera. Publicznym entrypointem dla użytkownika jest krótki wrapper `rvctl`: ```bash ./rvctl ``` Wrapper uruchamia: ```bash python3 rvctl.py "$@" ``` `rvctl.py` można też uruchomić bezpośrednio: ```bash ./rvctl.py ``` Ścieżki i domyślne ustawienia są trzymane w `workspace.json`. ## Co robi narzędzie `rvctl` porządkuje pracę w trzech obszarach. 1. Zarządzanie tokenami Narzędzie obsługuje lokalny store `tokens/tokens.json`, porównuje go z git remotes i potrafi synchronizować token w obie strony. Szczegóły modelu, format pliku i opis komend są w `doc/tokens.md`. 2. Listowanie i pobieranie kart pracy `rvctl` czyta serie, karty i zadania z workspace, pomaga wybrać materiał do pracy oraz przygotowuje remotes potrzebne do repo odpowiedzi. Docelowy model namespace `series`, `cards` i `tasks` jest w `doc/series.md`. 3. Uruchamianie środowiska programistycznego w kontenerach Dla wybranej karty `rvctl` uruchamia sesję tmux i kontener z przygotowanym środowiskiem developerskim. Docelowy model namespace `containers` jest w `doc/containers.md`. ## Model katalogów Podstawowym miejscem pracy użytkownika jest workspace: ```bash ~/dev/workspace/rv ``` Najpierw utwórz tylko katalog bazowy workspace i wejdź do niego: ```bash mkdir -p ~/dev/workspace/rv cd ~/dev/workspace/rv ``` Po tym kroku workspace istnieje, ale nie ma jeszcze katalogów narzędzi, tokenów ani kart: ```text ~/dev/workspace/rv ``` Potem wybierz jedną z dwóch dróg startu. ### Bez `tokens.json` Ten wariant jest dla sytuacji, w której token jest podany w URL-u git remota, a plik `tokens.json` ma powstać dopiero lokalnie. Etap 1: utwórz katalog launchera i wejdź do niego: ```bash mkdir -p ~/dev/workspace/rv/tools/rv-launcher cd ~/dev/workspace/rv/tools/rv-launcher ``` Etap 2: utwórz puste repo, dodaj remote `r1` z tokenem, pobierz branch i ustaw lokalny `main`: ```bash git init 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 ``` `r1` jest nazwą remota, z którego startujemy. `--track` ustawia lokalny branch `main` tak, aby śledził `r1/main`, dzięki czemu późniejsze `git pull` i `git push` wiedzą, z którym branchem zdalnym pracują. Po tym kroku w workspace jest już repo launchera: ```text ~/dev/workspace/rv └── tools └── rv-launcher ``` Etap 3: wczytaj token z remota do lokalnego store: ```bash cd ~/dev/workspace/rv/tools/rv-launcher ./rvctl tokens sync remote r1 ./rvctl tokens update r1 ``` `tokens sync remote r1` przepisuje token z URL-a remota `r1` do lokalnego store. `tokens update r1` odpytuje Gitea API i uzupełnia metadane tokena: ważność, zakresy oraz uprawnienia w organizacji i repo. `rvctl` sam tworzy katalog `~/dev/workspace/rv/tokens`, jeżeli jeszcze go nie ma. Plik `tokens.json` dostaje prawa `600`, a katalog store prawa `700`. Po tym kroku workspace ma już `tokens.json`: ```text ~/dev/workspace/rv ├── tools │ └── rv-launcher └── tokens └── tokens.json ``` Etap 4: sprawdź, czy git remote i lokalny store widzą ten sam token: ```bash ./rvctl tokens compare ``` Przykładowy wydruk: ```text tokens item server proto host org repo user remote token_ref token valid scope org repo ---- ------ ----- ------------------ --------- ----------- ---- ------ --------- ------------ ------- --------- ------ ------ 1 gitea http 77.90.8.171:3001 edu-tools rv-launcher u1 r1 r1 * e59cc...13be forever wwwwwwwww +++++ ++++ ``` Najważniejsze pola: - `remote` - nazwa git remota, tutaj `r1` - `token_ref` - lokalna nazwa tokena i marker zgodności po prawej stronie - `*` - token w remote i w `tokens.json` jest zgodny - `S` - token jest tylko w `tokens.json`; to jest normalne w trybie store-only - `R` - token jest tylko w git remote - `token` - zamaskowany sekret; `rvctl` nie wypisuje całego tokena - `valid`, `scope`, `org`, `repo` - metadane i uprawnienia pobrane przez `tokens update` Pełny opis tabeli tokenów jest w `doc/tokens.md`. ### Z `tokens.json` Ten wariant jest dla sytuacji, w której masz już gotowy plik `tokens.json`. Etap 1: skopiuj token store do workspace: ```bash mkdir -p ~/dev/workspace/rv/tokens cd ~/dev/workspace/rv cp /ścieżka/do/tokens.json tokens/tokens.json chmod 600 tokens/tokens.json ``` Po tym kroku workspace ma store tokenów, ale nie ma jeszcze launchera: ```text ~/dev/workspace/rv └── tokens └── tokens.json ``` Etap 2: wejdź do katalogu narzędzi i sklonuj `rv-launcher`: ```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 ``` Po `git clone` workspace wygląda tak: ```text ~/dev/workspace/rv ├── tools │ └── rv-launcher └── tokens └── tokens.json ``` Etap 3: sprawdź store i wpisz credentials ze store do remota `r1`: ```bash ./rvctl tokens list store ./rvctl tokens sync store r1 ``` `tokens list store` sprawdza, czy skopiowany `tokens.json` zawiera wpis dla remota `r1`. `tokens sync store r1` bierze token ze store i wpisuje credentials do git remota `r1`, tak aby kolejne operacje Git mogły używać tego tokena. Jeżeli po `git clone` repo ma tylko remote `origin` wskazujący to samo repo, `rvctl` automatycznie przemianuje go na `r1`. `list store` powinien pokazać token ze store: ```text tokens item source kind server proto host org repo user remote token valid ---- ------ ---- ------ ----- ---------------- --------- ----------- ---- ------ ------------ ------- 1 store auth gitea http 77.90.8.171:3001 edu-tools rv-launcher u1 r1 e59cc...13be forever ``` `sync store r1` wpisuje credentials do git remota: ```text repo_root /home/user/dev/workspace/rv/tools/rv-launcher remote r1 renamed_from origin server http://77.90.8.171:3001 user u1 id r1 status updated url http://77.90.8.171:3001/edu-tools/rv-launcher.git ``` Etap 4: odśwież metadane tokena i porównaj store z remote: ```bash ./rvctl tokens update r1 ./rvctl tokens compare ``` `tokens update r1` odpytuje Gitea API dla tokena ze store i odświeża jego metadane: ważność, zakresy oraz uprawnienia w organizacji i repo. `tokens compare` sprawdza potem, czy store i git remote wskazują ten sam token. `compare` powinien pokazać `*` przy `r1`, jeżeli remote i `tokens.json` są zgodne: ```text tokens item server proto host org repo user remote token_ref token valid ---- ------ ----- ---------------- --------- ----------- ---- ------ --------- ------------ ------- 1 gitea http 77.90.8.171:3001 edu-tools rv-launcher u1 r1 r1 * e59cc...13be forever ``` Etap 5: po operacjach Git możesz usunąć sekret z `.git/config`, zostawiając token tylko w store: ```bash ./rvctl tokens rm remote r1 ./rvctl tokens compare ``` Po usunięciu remota `compare` pokazuje marker `S`, czyli token jest tylko w store: ```text tokens item server proto host org repo user remote token_ref token valid ---- ------ ----- ---------------- --------- ----------- ---- ------ --------- ------------ ------- 1 gitea http 77.90.8.171:3001 edu-tools rv-launcher u1 r1 r1 S e59cc...13be forever ``` ## Szybki start Najpierw zobacz konfigurację i dostępne komendy: ```bash ./rvctl ./rvctl show-config ``` Typowy przepływ pracy: ```bash ./rvctl tokens compare ./rvctl list-series ./rvctl list-cards inf ./rvctl tmux-container inf 03 --dry-run ./rvctl tmux-container inf 03 --session rv-inf03 --attach ./rvctl submission inf 03 --class 4i --nick u1 ``` `--dry-run` jest przydatny przy sprawdzaniu planu uruchomienia lub konfiguracji repo, zanim narzędzie coś zmieni. ### Po pobraniu kart pracy Karty trafiają do `series` w workspace: ```text ~/dev/workspace/rv ├── tools │ └── rv-launcher ├── tokens │ └── tokens.json └── series └── inf └── 03 ``` `rvctl` pracuje na kartach z `series_root`, czyli na katalogu `~/dev/workspace/rv/series`. ### Po uruchomieniu środowiska kontenerowego Repo `rv32i-hazard3-env` jest potrzebne dopiero przy uruchamianiu środowiska kontenerowego. Wtedy pojawia się pod `tools`: ```text ~/dev/workspace/rv ├── tools │ ├── rv-launcher │ └── rv32i-hazard3-env ├── tokens │ └── tokens.json └── series └── inf └── 03 ``` Repozytoria źródłowe poza workspace, na przykład `~/dev/edu/repos/rv`, są zapleczem dla autora materiałów albo fallbackiem dla narzędzi. Nie są wymagane do zwykłej pracy w workspace. ## Dokumentacja - `doc/rvctl.md` - techniczna dokumentacja CLI: wszystkie komendy, argumenty i przełączniki - `doc/tokens.md` - model tokenów, synchronizacja remote <-> store - `doc/series.md` - docelowy model komend dla serii i kart pracy - `doc/containers.md` - docelowy model komend dla środowisk kontenerowych - `doc/tokens.schema.json` - schemat `tokens/tokens.json` - `doc/workspace.md` - krótki opis konfiguracji workspace README jest tylko mapą projektu. Szczegóły operacyjne trzymamy w `doc/`, żeby nie dublować instrukcji w kilku miejscach.