stem-launcher/README.md

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:

./rvctl

Wrapper uruchamia:

python3 rvctl.py "$@"

rvctl.py można też uruchomić bezpośrednio:

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

~/dev/workspace/rv

Najpierw utwórz tylko katalog bazowy workspace i wejdź do niego:

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:

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

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:

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:

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

Etap 3: wczytaj token z remota do lokalnego store:

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:

~/dev/workspace/rv
├── tools
│   └── rv-launcher
└── tokens
    └── tokens.json

Etap 4: sprawdź, czy git remote i lokalny store widzą ten sam token:

./rvctl tokens compare

Przykładowy wydruk:

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:

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:

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

Etap 2: wejdź do katalogu narzędzi i sklonuj rv-launcher:

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:

~/dev/workspace/rv
├── tools
│   └── rv-launcher
└── tokens
    └── tokens.json

Etap 3: sprawdź store i wpisz credentials ze store do remota r1:

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

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:

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:

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

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:

./rvctl tokens rm remote r1
./rvctl tokens compare

Po usunięciu remota compare pokazuje marker S, czyli token jest tylko w store:

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:

./rvctl
./rvctl show-config

Typowy przepływ pracy:

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

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

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