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

Najpierw utworz komplet katalogow startowych:

mkdir -p ~/dev/workspace/rv/tools
mkdir -p ~/dev/workspace/rv/tokens
mkdir -p ~/dev/workspace/rv/series
cd ~/dev/workspace/rv

Po tym kroku workspace ma tylko puste katalogi robocze:

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

Potem wybierz jedna z dwoch drog startu.

Bez tokens.json

Ten wariant jest dla sytuacji, w ktorej token jest podany w URL-u git remota, a plik tokens.json ma powstac dopiero lokalnie.

Etap 1: wejdz do katalogu narzedzi i utworz puste repo rv-launcher:

cd ~/dev/workspace/rv/tools
mkdir -p rv-launcher
cd rv-launcher
git init

Etap 2: dodaj remote r1 z tokenem, pobierz branch i ustaw lokalny main:

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 nazwa remota, z ktorego startujemy. --track ustawia lokalny branch main tak, aby sledzil r1/main, dzieki czemu pozniejsze git pull i git push wiedza, z ktorym branchem zdalnym pracuja.

Po tym kroku w workspace jest juz repo launchera:

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

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

Po tym kroku workspace ma juz tokens.json:

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

Etap 4: 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

Ten wariant jest dla sytuacji, w ktorej masz juz gotowy plik tokens.json.

Etap 1: skopiuj token store do workspace:

cd ~/dev/workspace/rv
cp /sciezka/do/tokens.json tokens/tokens.json
chmod 600 tokens/tokens.json

Po tym kroku workspace ma store tokenow, ale nie ma jeszcze launchera:

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

Etap 2: wejdz do katalogu narzedzi i sklonuj rv-launcher:

cd ~/dev/workspace/rv/tools
git clone http://77.90.8.171:3001/edu-tools/rv-launcher.git
cd rv-launcher

Etap 3: zmien nazwe remota z origin na r1:

git remote rename origin r1

tokens.json jest mapowany na nazwy git remotes, dlatego repo launchera ma uzywac remota r1.

Po git clone workspace wyglada tak:

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

Etap 4: 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

Etap 5: 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

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

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

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.