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

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

Etap 3: zmień nazwę remota z origin na r1:

git remote rename origin r1

tokens.json jest mapowany na nazwy git remotes, dlatego repo launchera ma używać remota r1.

Po git clone workspace wygląda tak:

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

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

./rvctl tokens list store
./rvctl tokens sync store 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
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 5: odśwież metadane tokena i porównaj store z remote:

./rvctl tokens update r1
./rvctl tokens compare

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

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.

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.

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.