stem-launcher/README.md

RV Launcher

Repo rv-launcher zawiera narzedzie do pracy z workspace RISC-V. W pierwszej kolejnosci sluzy ono do zarzadzania tokenami; pozostale funkcje obejmuja prace z kartami pracy i uruchamianie srodowiska kontenerowego.

Wlasciwym skryptem CLI jest wykonywalny plik rvctl.py. To on implementuje zarzadzanie tokenami, listowanie serii i kart, przygotowanie repo odpowiedzi i start kontenera.

Publicznym entrypointem dla uzytkownika jest krotki wrapper rvctl:

./rvctl

Wrapper uruchamia:

python3 rvctl.py "$@"

rvctl.py mozna tez uruchomic bezposrednio:

./rvctl.py

Sciezki i domyslne ustawienia sa trzymane w workspace.json.

Co robi narzedzie

rvctl porzadkuje prace w trzech obszarach.

1. Zarzadzanie tokenami

   Narzedzie obsluguje lokalny store tokens/tokens.json, porownuje go z git remotes i potrafi synchronizowac token w obie strony. Szczegoly modelu, format pliku i opis komend sa w doc/tokens.md.

2. Listowanie i pobieranie kart pracy

   rvctl czyta serie, karty i zadania z workspace, pomaga wybrac material do pracy oraz przygotowuje remotes potrzebne do repo odpowiedzi. Docelowy model namespace series, cards i tasks jest w doc/series.md.

3. Uruchamianie srodowiska programistycznego w kontenerach

   Dla wybranej karty rvctl uruchamia sesje tmux i kontener z przygotowanym srodowiskiem developerskim. Docelowy model namespace containers jest w doc/containers.md.

Model katalogow

Podstawowym miejscem pracy uzytkownika jest workspace:

~/dev/workspace/rv

Minimalny uklad przed pobraniem launchera zawiera tylko katalogi workspace:

~/dev/workspace/rv
├── tools
├── tokens
└── series

Sa dwie drogi startu.

Bez tokens.json

Jesli nie masz jeszcze pliku z tokenem albo tokenami, zacznij od pustego repo launchera i remota z tokenem:

mkdir -p ~/dev/workspace/rv/tools/rv-launcher
cd ~/dev/workspace/rv/tools/rv-launcher
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

Po tym kroku w workspace jest juz repo launchera:

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

Potem wczytaj token z remota do lokalnego store:

./rvctl tokens sync remote r1
./rvctl tokens update r1

Po tym kroku workspace ma juz lokalny store:

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

Na koniec sprawdz, czy git remote i lokalny store widza ten sam token:

./rvctl tokens compare

Przykladowy 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  +++++   ++++

Najwazniejsze pola:

• remote - nazwa git remota, tutaj r1
• token_ref - lokalna nazwa tokena i marker zgodnosci 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 calego tokena
• valid, scope, org, repo - metadane i uprawnienia pobrane przez tokens update

Pelny opis tabeli tokenow jest w doc/tokens.md.

Z tokens.json

Jesli masz gotowy plik tokens.json, zacznij od lokalnego store tokenow:

mkdir -p ~/dev/workspace/rv/tokens
cp tokens.json ~/dev/workspace/rv/tokens/tokens.json
chmod 600 ~/dev/workspace/rv/tokens/tokens.json

Na tym etapie workspace ma store tokenow, ale nie musi jeszcze miec launchera:

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

Opcja git clone:

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
git remote rename origin r1

Po git clone pojawia sie repo rv-launcher:

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

Po klonie zmieniamy origin na r1, bo tokens.json jest mapowany na nazwy git remotes. Jesli git clone wymaga autoryzacji, uzyj standardowego sposobu Gita dla tego jednego kroku. Plik tokens.json zaczyna obslugiwac Git remotes dopiero wtedy, gdy masz juz lokalnie rvctl.

Po wejsciu do repo launchera sprawdz store i wpisz credentials ze store do remota r1:

./rvctl tokens list store
./rvctl tokens sync store r1

list store powinien pokazac 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

Na koniec odswiez metadane tokena i porownaj store z remote:

./rvctl tokens update r1
./rvctl tokens compare

compare powinien pokazac * przy r1, jezeli remote i tokens.json sa 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

Po operacjach Git mozesz usunac sekret z .git/config, zostawiajac token tylko w store:

./rvctl tokens rm remote r1

Po usunieciu 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 trafiaja 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 srodowiska kontenerowego

Repo rv32i-hazard3-env jest potrzebne dopiero przy uruchamianiu srodowiska kontenerowego. Wtedy pojawia sie pod tools:

~/dev/workspace/rv
├── tools
│   ├── rv-launcher
│   └── rv32i-hazard3-env
├── tokens
│   └── tokens.json
└── series
    └── inf
        └── 03

Repozytoria zrodlowe poza workspace, na przyklad ~/dev/edu/repos/rv, sa zapleczem dla autora materialow albo fallbackiem dla narzedzi. Nie sa wymagane do zwyklej pracy w workspace.

Szybki start

Najpierw zobacz konfiguracje i dostepne komendy:

./rvctl
./rvctl show-config

Typowy przeplyw 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 narzedzie cos zmieni.

Dokumentacja

• doc/rvctl.md - techniczna dokumentacja CLI: wszystkie komendy, argumenty i przelaczniki
• doc/tokens.md - model tokenow, synchronizacja remote <-> store
• doc/series.md - docelowy model komend dla serii i kart pracy
• doc/containers.md - docelowy model komend dla srodowisk kontenerowych
• doc/tokens.schema.json - schemat tokens/tokens.json
• doc/workspace.md - krotki opis konfiguracji workspace

README jest tylko mapa projektu. Szczegoly operacyjne trzymamy w doc/, zeby nie dublowac instrukcji w kilku miejscach.