edu/stem-launcher
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Use Polish diacritics in docs

Browse Source
This commit is contained in:
mpabi
2026-04-29 02:09:30 +02:00
parent dedde573f7
commit b67c5b5204
6 changed files with 326 additions and 321 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+72 -70
View File
@@ -1,14 +1,14 @@
# 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.
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.
Wlasciwym skryptem CLI jest wykonywalny plik `rvctl.py`. To on implementuje
zarzadzanie tokenami, listowanie serii i kart, przygotowanie repo odpowiedzi i
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 uzytkownika jest krotki wrapper `rvctl`:
Publicznym entrypointem dla użytkownika jest krótki wrapper `rvctl`:
```bash
./rvctl
@@ -20,73 +20,73 @@ Wrapper uruchamia:
python3 rvctl.py "$@"
```
`rvctl.py` mozna tez uruchomic bezposrednio:
`rvctl.py` można też uruchomić bezpośrednio:
```bash
./rvctl.py
```
Sciezki i domyslne ustawienia sa trzymane w `workspace.json`.
Ścieżki i domyślne ustawienia są trzymane w `workspace.json`.
## Co robi narzedzie
## Co robi narzędzie
`rvctl` porzadkuje prace w trzech obszarach.
`rvctl` porządkuje pracę w trzech obszarach.
1. Zarzadzanie tokenami
1. Zarządzanie 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`.
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 wybrac material do
`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 srodowiska programistycznego w kontenerach
3. Uruchamianie środowiska programistycznego w kontenerach
Dla wybranej karty `rvctl` uruchamia sesje tmux i kontener z przygotowanym
srodowiskiem developerskim. Docelowy model namespace `containers` jest w
Dla wybranej karty `rvctl` uruchamia sesję tmux i kontener z przygotowanym
środowiskiem developerskim. Docelowy model namespace `containers` jest w
`doc/containers.md`.
## Model katalogow
## Model katalogów
Podstawowym miejscem pracy uzytkownika jest workspace:
Podstawowym miejscem pracy użytkownika jest workspace:
```bash
~/dev/workspace/rv
```
Najpierw utworz tylko katalog bazowy workspace i wejdz do niego:
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 katalogow narzedzi,
tokenow ani kart:
Po tym kroku workspace istnieje, ale nie ma jeszcze katalogów narzędzi,
tokenów ani kart:
```text
~/dev/workspace/rv
```
Potem wybierz jedna z dwoch drog startu.
Potem wybierz jedną z dwóch dróg 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.
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: utworz katalog launchera i wejdz do niego:
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: utworz puste repo, dodaj remote `r1` z tokenem, pobierz branch i
Etap 2: utwórz puste repo, dodaj remote `r1` z tokenem, pobierz branch i
ustaw lokalny `main`:
```bash
@@ -96,11 +96,11 @@ 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.
`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 juz repo launchera:
Po tym kroku w workspace jest już repo launchera:
```text
~/dev/workspace/rv
@@ -108,16 +108,18 @@ Po tym kroku w workspace jest juz repo launchera:
└── rv-launcher
```
Etap 3: utworz katalog store i wczytaj token z remota do lokalnego store:
Etap 3: wczytaj token z remota do lokalnego store:
```bash
cd ~/dev/workspace/rv/tools/rv-launcher
mkdir -p ~/dev/workspace/rv/tokens
./rvctl tokens sync remote r1
./rvctl tokens update r1
```
Po tym kroku workspace ma juz `tokens.json`:
`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
@@ -127,13 +129,13 @@ Po tym kroku workspace ma juz `tokens.json`:
└── tokens.json
```
Etap 4: sprawdz, czy git remote i lokalny store widza ten sam token:
Etap 4: sprawdź, czy git remote i lokalny store widzą ten sam token:
```bash
./rvctl tokens compare
```
Przykladowy wydruk:
Przykładowy wydruk:
```text
tokens
@@ -142,33 +144,33 @@ item server proto host org repo user remote t
1 gitea http 77.90.8.171:3001 edu-tools rv-launcher u1 r1 r1 * e59cc...13be forever wwwwwwwww +++++ ++++
```
Najwazniejsze pola:
Najważniejsze pola:
- `remote` - nazwa git remota, tutaj `r1`
- `token_ref` - lokalna nazwa tokena i marker zgodnosci po prawej stronie
- `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 calego tokena
- `token` - zamaskowany sekret; `rvctl` nie wypisuje całego tokena
- `valid`, `scope`, `org`, `repo` - metadane i uprawnienia pobrane przez
`tokens update`
Pelny opis tabeli tokenow jest w `doc/tokens.md`.
Pełny opis tabeli tokenów jest w `doc/tokens.md`.
### Z `tokens.json`
Ten wariant jest dla sytuacji, w ktorej masz juz gotowy plik `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 /sciezka/do/tokens.json tokens/tokens.json
cp /ścieżka/do/tokens.json tokens/tokens.json
chmod 600 tokens/tokens.json
```
Po tym kroku workspace ma store tokenow, ale nie ma jeszcze launchera:
Po tym kroku workspace ma store tokenów, ale nie ma jeszcze launchera:
```text
~/dev/workspace/rv
@@ -176,7 +178,7 @@ Po tym kroku workspace ma store tokenow, ale nie ma jeszcze launchera:
└── tokens.json
```
Etap 2: wejdz do katalogu narzedzi i sklonuj `rv-launcher`:
Etap 2: wejdź do katalogu narzędzi i sklonuj `rv-launcher`:
```bash
mkdir -p ~/dev/workspace/rv/tools
@@ -185,16 +187,16 @@ 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`:
Etap 3: zmień nazwę remota z `origin` na `r1`:
```bash
git remote rename origin r1
```
`tokens.json` jest mapowany na nazwy git remotes, dlatego repo launchera ma
uzywac remota `r1`.
używać remota `r1`.
Po `git clone` workspace wyglada tak:
Po `git clone` workspace wygląda tak:
```text
~/dev/workspace/rv
@@ -204,14 +206,14 @@ Po `git clone` workspace wyglada tak:
└── tokens.json
```
Etap 4: sprawdz store i wpisz credentials ze store do remota `r1`:
Etap 4: sprawdź store i wpisz credentials ze store do remota `r1`:
```bash
./rvctl tokens list store
./rvctl tokens sync store r1
```
`list store` powinien pokazac token ze store:
`list store` powinien pokazać token ze store:
```text
tokens
@@ -232,14 +234,14 @@ status updated
url http://77.90.8.171:3001/edu-tools/rv-launcher.git
```
Etap 5: odswiez metadane tokena i porownaj store z remote:
Etap 5: odśwież metadane tokena i porównaj store z remote:
```bash
./rvctl tokens update r1
./rvctl tokens compare
```
`compare` powinien pokazac `*` przy `r1`, jezeli remote i `tokens.json` sa
`compare` powinien pokazać `*` przy `r1`, jeżeli remote i `tokens.json` są
zgodne:
```text
@@ -249,7 +251,7 @@ item server proto host org repo user remote tok
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
Etap 6: po operacjach Git możesz usunąć sekret z `.git/config`, zostawiając
token tylko w store:
```bash
@@ -257,7 +259,7 @@ token tylko w store:
./rvctl tokens compare
```
Po usunieciu remota `compare` pokazuje marker `S`, czyli token jest tylko w
Po usunięciu remota `compare` pokazuje marker `S`, czyli token jest tylko w
store:
```text
@@ -269,7 +271,7 @@ item server proto host org repo user remote tok
### Po pobraniu kart pracy
Karty trafiaja do `series` w workspace:
Karty trafiają do `series` w workspace:
```text
~/dev/workspace/rv
@@ -285,10 +287,10 @@ Karty trafiaja do `series` w workspace:
`rvctl` pracuje na kartach z `series_root`, czyli na katalogu
`~/dev/workspace/rv/series`.
### Po uruchomieniu srodowiska kontenerowego
### Po uruchomieniu środowiska kontenerowego
Repo `rv32i-hazard3-env` jest potrzebne dopiero przy uruchamianiu srodowiska
kontenerowego. Wtedy pojawia sie pod `tools`:
Repo `rv32i-hazard3-env` jest potrzebne dopiero przy uruchamianiu środowiska
kontenerowego. Wtedy pojawia się pod `tools`:
```text
~/dev/workspace/rv
@@ -302,20 +304,20 @@ kontenerowego. Wtedy pojawia sie pod `tools`:
└── 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.
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 konfiguracje i dostepne komendy:
Najpierw zobacz konfigurację i dostępne komendy:
```bash
./rvctl
./rvctl show-config
```
Typowy przeplyw pracy:
Typowy przepływ pracy:
```bash
./rvctl tokens compare
@@ -327,17 +329,17 @@ Typowy przeplyw pracy:
```
`--dry-run` jest przydatny przy sprawdzaniu planu uruchomienia lub konfiguracji
repo, zanim narzedzie cos zmieni.
repo, zanim narzędzie coś zmieni.
## Dokumentacja
- `doc/rvctl.md` - techniczna dokumentacja CLI: wszystkie komendy, argumenty
i przelaczniki
- `doc/tokens.md` - model tokenow, synchronizacja remote <-> store
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 srodowisk kontenerowych
- `doc/containers.md` - docelowy model komend dla środowisk kontenerowych
- `doc/tokens.schema.json` - schemat `tokens/tokens.json`
- `doc/workspace.md` - krotki opis konfiguracji workspace
- `doc/workspace.md` - krótki opis konfiguracji workspace
README jest tylko mapa projektu. Szczegoly operacyjne trzymamy w `doc/`, zeby
nie dublowac instrukcji w kilku miejscach.
README jest tylko mapą projektu. Szczegóły operacyjne trzymamy w `doc/`, żeby
nie dublować instrukcji w kilku miejscach.
doc/containers.md
+24 -24
View File
@@ -1,20 +1,20 @@
# Containers
Ten dokument opisuje docelowy model komend `rvctl` do uruchamiania
srodowiska programistycznego w kontenerach.
środowiska programistycznego w kontenerach.
## Zasada
Kontener jest srodowiskiem pracy dla wybranej karty, opcjonalnie zawezonym do
konkretnego zadania. `rvctl` uruchamia je przez sesje `tmux`, tak aby terminal
z kontenerem byl latwy do ponownego podlaczenia.
Kontener jest środowiskiem pracy dla wybranej karty, opcjonalnie zawężonym do
konkretnego zadania. `rvctl` uruchamia je przez sesję `tmux`, tak aby terminal
z kontenerem był łatwy do ponownego podłączenia.
Uzywamy namespace `containers`, a nie `container`, bo jest spojny z pluralnymi
Używamy namespace `containers`, a nie `container`, bo jest spójny z pluralnymi
namespace'ami `tokens`, `cards` i `tasks`.
## Szybki Flow
## Szybki przepływ
Typowy przeplyw pracy:
Typowy przepływ pracy:
```bash
./rvctl tokens compare
@@ -28,13 +28,13 @@ Typowy przeplyw pracy:
## Model
Docelowo komendy `containers` pracuja na trzech warstwach:
Docelowo komendy `containers` pracują na trzech warstwach:
- karta pracy, np. `inf 03`
- opcjonalne zadanie, np. `--task task1`
- instancja srodowiska, np. `--instance shell`
- instancja środowiska, np. `--instance shell`
Domyslne wartosci pochodza z `workspace.json`:
Domyślne wartości pochodzą z `workspace.json`:
```text
defaults.series
@@ -49,7 +49,7 @@ defaults.tmux_window
### `containers show [SERIES] [CARD]`
Pokazuje plan uruchomienia srodowiska bez tworzenia sesji `tmux`.
Pokazuje plan uruchomienia środowiska bez tworzenia sesji `tmux`.
```bash
./rvctl containers show inf 03
@@ -77,7 +77,7 @@ Ta komenda jest odpowiednikiem obecnego trybu:
### `containers start [SERIES] [CARD]`
Uruchamia sesje `tmux` i kontener dla wybranej karty.
Uruchamia sesję `tmux` i kontener dla wybranej karty.
```bash
./rvctl containers start inf 03
@@ -85,29 +85,29 @@ Uruchamia sesje `tmux` i kontener dla wybranej karty.
./rvctl containers start inf 03 --task task1 --instance shell --attach
```
Przelaczniki:
Przełączniki:
- `--task TASK`
Wybiera zadanie w karcie. Bez tego `rvctl` uzywa domyslnego zadania z
Wybiera zadanie w karcie. Bez tego `rvctl` używa domyślnego zadania z
`workspace.json` albo pracuje na katalogu karty.
- `--session NAME`
Nadpisuje nazwe sesji `tmux`.
Nadpisuje nazwę sesji `tmux`.
- `--window NAME`
Nadpisuje nazwe okna `tmux`.
Nadpisuje nazwę okna `tmux`.
- `--instance NAME`
Ustawia wariant srodowiska, np. `shell`.
Ustawia wariant środowiska, np. `shell`.
- `--attach`
Po uruchomieniu od razu podlacza terminal do sesji.
Po uruchomieniu od razu podłącza terminal do sesji.
### `containers list`
Listuje aktywne srodowiska uruchomione przez `rvctl`.
Listuje aktywne środowiska uruchomione przez `rvctl`.
```bash
./rvctl containers list
```
Przykladowy wynik:
Przykładowy wynik:
```text
session selector task instance window
@@ -117,7 +117,7 @@ rv-inf03 inf/03 task1 shell rv
### `containers attach SESSION`
Podlacza terminal do istniejacej sesji.
Podłącza terminal do istniejącej sesji.
```bash
./rvctl containers attach rv-inf03
@@ -131,7 +131,7 @@ tmux attach -t rv-inf03
### `containers stop SESSION`
Zamyka sesje `tmux`, a razem z nia uruchomiony w niej proces kontenera.
Zamyka sesję `tmux`, a razem z nią uruchomiony w niej proces kontenera.
```bash
./rvctl containers stop rv-inf03
@@ -145,7 +145,7 @@ tmux kill-session -t rv-inf03
## Aliasowanie Starej Komendy
Stara komenda moze zostac jako alias kompatybilnosci:
Stara komenda może zostać jako alias kompatybilności:
```text
tmux-container inf 03 --dry-run -> containers show inf 03
@@ -153,4 +153,4 @@ tmux-container inf 03 --session NAME -> containers start inf 03 --session NAME
tmux-container inf/03 --attach -> containers start inf/03 --attach
```
Dokumentacja i nowe przyklady powinny promowac namespace `containers`.
Dokumentacja i nowe przykłady powinny promować namespace `containers`.
doc/rvctl.md
+137 -137
View File
@@ -1,8 +1,8 @@
# RVCTL CLI
Plik opisuje przelaczniki i liste komend skryptu `rvctl`.
Plik opisuje przełączniki i listę komend skryptu `rvctl`.
## Model katalogow
## Model katalogów
Repo oryginalne trzymamy poza workspace:
@@ -10,13 +10,13 @@ Repo oryginalne trzymamy poza workspace:
~/dev/edu/repos/rv
```
Workspace sluzy do klonow roboczych i cwiczen:
Workspace służy do klonów roboczych i ćwiczeń:
```bash
~/dev/workspace/rv
```
Typowy uklad:
Typowy układ:
```text
~/dev/edu/repos/rv/rv-launcher
@@ -29,16 +29,16 @@ Typowy uklad:
`rvctl` czyta karty z `series_root` w workspace. Tool repo
`rv32i-hazard3-env` wybiera najpierw z workspace, a potem z fallbacku
`~/dev/edu/repos/rv`, jesli taki klon roboczy jeszcze nie istnieje.
`~/dev/edu/repos/rv`, jeśli taki klon roboczy jeszcze nie istnieje.
Karty pracy tez sa rozdzielone:
Karty pracy też są rozdzielone:
- `original_series_root` wskazuje repo zrodlowe kart, na przyklad `~/dev/edu/repos/rv/series`
- `series_root` wskazuje klony testowe w workspace, na przyklad `~/dev/workspace/rv/series`
- `original_series_root` wskazuje repo źródłowe kart, na przykład `~/dev/edu/repos/rv/series`
- `series_root` wskazuje klony testowe w workspace, na przykład `~/dev/workspace/rv/series`
Komendy launchera pracuja na `series_root`, czyli na klonach testowych.
Komendy launchera pracują na `series_root`, czyli na klonach testowych.
## Pobranie repo i przelaczenie galezi
## Pobranie repo i przełączenie gałęzi
Repo treningowe launchera trzymaj pod:
@@ -46,7 +46,7 @@ Repo treningowe launchera trzymaj pod:
~/dev/workspace/rv/tools/rv-launcher
```
Podstawowy bootstrap wyglada tak:
Podstawowy bootstrap wygląda tak:
```bash
mkdir -p ~/dev/workspace/rv/tools
@@ -55,17 +55,17 @@ git clone http://77.90.8.171:3001/edu-tools/rv-launcher.git
cd rv-launcher
```
Glowne pliki CLI:
Główne pliki CLI:
```bash
./rvctl
rvctl.py
```
`rvctl` jest jedynym publicznym entrypointem. `rvctl.py` jest implementacja
uruchamiana przez wrapper i nie wymaga osobnego wywolywania przez ucznia.
`rvctl` jest jedynym publicznym entrypointem. `rvctl.py` jest implementacją
uruchamianą przez wrapper i nie wymaga osobnego wywoływania przez ucznia.
Uruchomienie bez argumentow pokazuje tabelaryczny skrot komend:
Uruchomienie bez argumentów pokazuje tabelaryczny skrót komend:
```bash
./rvctl
@@ -79,11 +79,11 @@ Masz dwie drogi.
#### Droga 1: remote `r1` z tokenem w URL
To jest wariant dydaktyczny, jesli uczen ma cwiczyc reczne dodawanie remota z
tokenem do zdalnego endpointu. Jesli launcher zobaczy URL w formacie
To jest wariant dydaktyczny, jeśli uczeń ma ćwiczyć ręczne dodawanie remota z
tokenem do zdalnego endpointu. Jeśli launcher zobaczy URL w formacie
`http://LOGIN:TOKEN@...`, zapisze ten token lokalnie do `tokens/tokens.json`.
Przyklad:
Przykład:
```bash
git remote add r1 http://u1:TOKEN@77.90.8.171:3001/edu-tools/rv-launcher.git
@@ -93,7 +93,7 @@ git switch --track -c main r1/main
#### Droga 2: lokalny `tokens/tokens.json`
Przed operacjami wymagajacymi autoryzacji dodaj lokalny token do:
Przed operacjami wymagającymi autoryzacji dodaj lokalny token do:
```bash
~/dev/workspace/rv/tokens/tokens.json
@@ -123,9 +123,9 @@ Minimalny format pliku:
}
```
Ten plik powinien byc lokalny, niewersjonowany i miec prawa `600`.
Ten plik powinien być lokalny, niewersjonowany i mieć prawa `600`.
Przyklad:
Przykład:
```bash
mkdir -p ~/dev/workspace/rv/tokens
@@ -134,13 +134,13 @@ chmod 600 ~/dev/workspace/rv/tokens/tokens.json
```
Wariant z `tokens/tokens.json` jest wygodniejszy wtedy, gdy launcher ma
sam wykonywac `clone`, `fetch` i `push`, albo gdy uzytkownik po zajeciach chce
pracowac z wieloma repo na swoim koncie bez wpisywania tokena do kazdego
sam wykonywać `clone`, `fetch` i `push`, albo gdy użytkownik po zajęciach chce
pracować z wieloma repo na swoim koncie bez wpisywania tokena do każdego
remota.
### Fetch i switch
Domyslna galaz launchera to `main`.
Domyślna gałąź launchera to `main`.
Po sklonowaniu:
@@ -158,7 +158,7 @@ git switch --track -c main r1/main
git pull --ff-only r1 main
```
Jesli chcesz wejsc na inna galaz, na przyklad `feat/x`, uzyj:
Jeśli chcesz wejść na inną gałąź, na przykład `feat/x`, użyj:
```bash
git fetch origin feat/x
@@ -172,16 +172,16 @@ git fetch r1 feat/x
git switch --track -c feat/x r1/feat/x
```
## Wywolanie glowne
## Wywołanie główne
```bash
./rvctl [--config PATH] <komenda> [opcje]
```
Globalne przelaczniki:
Globalne przełączniki:
- `--config PATH`
Uzywa innego pliku `workspace.json`.
Używa innego pliku `workspace.json`.
Pomoc tabelaryczna:
@@ -192,7 +192,7 @@ Pomoc tabelaryczna:
./rvctl help tokens
```
Szczegolowy help parsera:
Szczegółowy help parsera:
```bash
./rvctl --help
@@ -216,7 +216,7 @@ Komendy:
## `show-config`
Wypisuje rozwiazane sciezki z konfiguracji.
Wypisuje rozwiązane ścieżki z konfiguracji.
Typowy format:
@@ -240,7 +240,7 @@ tools_root_candidates
...
```
Przyklad:
Przykład:
```bash
./rvctl show-config
@@ -250,13 +250,13 @@ Przyklad:
Listuje katalogi serii znalezione w `series_root`.
Kazda linia ma format:
Każda linia ma format:
```text
<series_id><TAB><liczba_kart><TAB><pelna_sciezka>
<series_id><TAB><liczba_kart><TAB><pełna_ścieżka>
```
Przyklad:
Przykład:
```bash
./rvctl list-series
@@ -269,22 +269,22 @@ Listuje karty z wybranej serii.
Argumenty:
- `series`
Opcjonalne id serii, na przyklad `inf`.
Jesli go brak, brana jest domyslna seria z `workspace.json`.
Opcjonalne id serii, na przykład `inf`.
Jeśli go brak, brana jest domyślna seria z `workspace.json`.
Format wyjscia:
Format wyjścia:
```text
<card_no><TAB><tytul_z_README><TAB><pelna_sciezka>
<card_no><TAB><tytuł_z_README><TAB><pełna_ścieżka>
```
Jesli `README.md` nie ma naglowka `#`, skrypt wypisuje:
Jeśli `README.md` nie ma nagłówka `#`, skrypt wypisuje:
```text
<card_no><TAB><pelna_sciezka>
<card_no><TAB><pełna_ścieżka>
```
Przyklady:
Przykłady:
```bash
./rvctl list-cards
@@ -293,14 +293,14 @@ Przyklady:
## `tokens scan`
Czyta remote URL-e w repo i pokazuje diagnostyczna tabele git remotes:
`auth`, `plain` i `unsupported`. Nie porownuje ich z `tokens.json`. Komenda
Czyta remote URL-e w repo i pokazuje diagnostyczną tabelę git remotes:
`auth`, `plain` i `unsupported`. Nie porównuje ich z `tokens.json`. Komenda
jest read-only.
Przelaczniki:
Przełączniki:
- `--repo PATH`
Sciezka wewnatrz docelowego repo. Domyslnie repo zawierajace `rvctl`.
Ścieżka wewnątrz docelowego repo. Domyślnie repo zawierające `rvctl`.
- `--server ENDPOINT`
Pokazuje tylko wpisy z danego endpointu.
@@ -313,7 +313,7 @@ item remote kind server proto host org repo
1 r1 auth gitea http 77.90.8.171:3001 edu-tools rv-launcher u1 e59cc...13be found http://77.90.8.171:3001/edu-tools/...
```
Przyklad:
Przykład:
```bash
./rvctl tokens scan
@@ -322,14 +322,14 @@ Przyklad:
## `tokens compare`
Czyta remote URL-e w repo oraz lokalny `tokens.json`, laczy wpisy w pary po
endpoincie, nazwie remota, token id, wartosci tokena, org i repo, a potem
Czyta remote URL-e w repo oraz lokalny `tokens.json`, łączy wpisy w pary po
endpoincie, nazwie remota, token id, wartości tokena, org i repo, a potem
pokazuje jeden logiczny wiersz na token. Komenda jest read-only.
Przelaczniki:
Przełączniki:
- `--repo PATH`
Sciezka wewnatrz docelowego repo. Domyslnie repo zawierajace `rvctl`.
Ścieżka wewnątrz docelowego repo. Domyślnie repo zawierające `rvctl`.
Typowy wynik:
@@ -340,21 +340,21 @@ item server proto host org repo user remote t
1 gitea http 77.90.8.171:3001 edu-tools rv-launcher u1 r1 r1 * e59cc...13be forever wwwwwwwww +++++ ++++
```
`token_ref` jest komorka stalej szerokosci: nazwa tokena jest po lewej, a marker
`token_ref` jest komórką stałej szerokości: nazwa tokena jest po lewej, a marker
po prawej. Nazwa tokena jest taka sama jak nazwa git remote, np. `r1`. Marker
`*` oznacza, ze remote i `tokens.json` sa zgodne. Marker `R` oznacza token tylko
`*` oznacza, że remote i `tokens.json` są zgodne. Marker `R` oznacza token tylko
w remote, a `S` token tylko w `tokens.json`.
Maski uprawnien:
Maski uprawnień:
- `scope` ma pozycje `aAimnopru`: activitypub, admin, issue, misc, notification, organization, package, repository, user
- w `scope`: `w` oznacza read/write, `r` read, `-` brak dostepu
- w `scope`: `w` oznacza read/write, `r` read, `-` brak dostępu
- `org` ma pozycje `oawrc`: owner, admin, write, read, create repo
- `repo` ma pozycje `oawr`: owner, admin, write, read
- `+` oznacza wlaczone, `-` wylaczone, `?` nie wczytano, `!` blad wczytania
- `+` oznacza włączone, `-` wyłączone, `?` nie wczytano, `!` błąd wczytania
- `valid` pokazuje `forever`, lokalne `expires_at`, `invalid`, `?` albo `!`
Przyklad:
Przykład:
```bash
./rvctl tokens compare
@@ -363,14 +363,14 @@ Przyklad:
## `tokens list store|remote|both`
Wypisuje jedno zrodlo bez porownywania go z drugim. `list` jest read-only:
pokazuje co jest w `tokens.json`, co jest w git remote albo oba zrodla jako
osobne wiersze. `compare` sluzy do porownania zgodnosci.
Wypisuje jedno źródło bez porównywania go z drugim. `list` jest read-only:
pokazuje co jest w `tokens.json`, co jest w git remote albo oba źródła jako
osobne wiersze. `compare` służy do porównania zgodności.
Przelaczniki:
Przełączniki:
- `--repo PATH`
Repo, z ktorego listowane sa git remotes. Domyslnie repo zawierajace `rvctl`.
Repo, z którego listowane są git remotes. Domyślnie repo zawierające `rvctl`.
- `--server ENDPOINT`
Ogranicza wynik do jednego endpointu.
@@ -384,7 +384,7 @@ item source kind server proto host org repo
2 remote auth gitea http 77.90.8.171:3001 edu-tools rv-launcher u1 r1 e59cc...13be
```
Przyklady:
Przykłady:
```bash
./rvctl tokens list store
@@ -394,20 +394,20 @@ Przyklady:
## `tokens add REMOTE_ID`
Dodaje pusty szkielet tokena do `tokens.json`. `REMOTE_ID` musi byc taki sam
jak nazwa git remote, np. `r1`. Pole `value` jest puste i trzeba je uzupelnic
recznie przed uzyciem tokena.
Dodaje pusty szkielet tokena do `tokens.json`. `REMOTE_ID` musi być taki sam
jak nazwa git remote, np. `r1`. Pole `value` jest puste i trzeba je uzupełnić
ręcznie przed użyciem tokena.
Przelaczniki:
Przełączniki:
- `--server ENDPOINT`
Endpoint serwera. Domyslnie `git.base_url` z `workspace.json`.
Endpoint serwera. Domyślnie `git.base_url` z `workspace.json`.
- `--value TOKEN`
Opcjonalna wartosc tokena. Domyslnie pusta.
Opcjonalna wartość tokena. Domyślnie pusta.
- `--user NAME`
Login uzywany w URL-u auth, np. `u1`.
Login używany w URL-u auth, np. `u1`.
- `--remote NAME`
Alias zgodnosci. Jesli podany, musi byc taki sam jak `REMOTE_ID`.
Alias zgodności. Jeśli podany, musi być taki sam jak `REMOTE_ID`.
- `--org NAME`
Opcjonalna organizacja dla remota.
- `--repo NAME`
@@ -415,7 +415,7 @@ Przelaczniki:
- `--dry-run`
Pokazuje plan bez zapisu.
Przyklady:
Przykłady:
```bash
./rvctl tokens add r1
@@ -427,14 +427,14 @@ Przyklady:
Czyta dane auth z git remote `REMOTE_ID` i zapisuje je do `tokens.json`. Nie
pobiera metadanych z API.
Przelaczniki:
Przełączniki:
- `--repo PATH`
Sciezka wewnatrz docelowego repo. Domyslnie repo zawierajace `rvctl`.
Ścieżka wewnątrz docelowego repo. Domyślnie repo zawierające `rvctl`.
- `--dry-run`
Pokazuje plan bez zapisu.
Przyklad:
Przykład:
```bash
./rvctl tokens sync remote r1
@@ -444,23 +444,23 @@ Przyklad:
## `tokens sync store REMOTE_ID`
Zapisuje dane auth z rekordu `REMOTE_ID` w `tokens.json` do git remote o tej
samej nazwie. Jesli remote jeszcze nie istnieje, URL jest budowany z pol
samej nazwie. Jeśli remote jeszcze nie istnieje, URL jest budowany z pól
`server.endpoint`, `org` i `repo` w `tokens.json`.
Przelaczniki:
Przełączniki:
- `--repo PATH`
Sciezka wewnatrz docelowego repo. Domyslnie biezacy katalog.
Ścieżka wewnątrz docelowego repo. Domyślnie bieżący katalog.
- `--url URL`
Opcjonalny URL remota. Nadpisuje URL zbudowany z `tokens.json`.
- `--server ENDPOINT`
Endpoint serwera z `tokens.json`.
- `--replace`
Nadpisuje inne dane auth juz wpisane w remote URL.
Nadpisuje inne dane auth już wpisane w remote URL.
- `--dry-run`
Pokazuje plan bez zapisu.
Przyklad:
Przykład:
```bash
./rvctl tokens sync store r1 --repo ~/dev/workspace/rv/series/inf/03
@@ -469,20 +469,20 @@ Przyklad:
## `tokens remove store|remote|both REMOTE_ID`
Usuwa rekord z `tokens.json`, git remote albo oba miejsca.
Domyslnym repo dla `remote` i `both` jest repo, w ktorym lezy `rvctl`. Inne
repo mozna wskazac przez `--repo PATH`.
Domyślnym repo dla `remote` i `both` jest repo, w którym leży `rvctl`. Inne
repo można wskazać przez `--repo PATH`.
Przelaczniki:
Przełączniki:
- `--repo PATH`
Repo, z ktorego ma byc usuniety git remote. Domyslnie repo zawierajace
Repo, z którego ma być usunięty git remote. Domyślnie repo zawierające
`rvctl`.
- `--server ENDPOINT`
Endpoint serwera, jesli `tokens.json` ma kilka rekordow o tym samym `id`.
Endpoint serwera, jeśli `tokens.json` ma kilka rekordów o tym samym `id`.
- `--dry-run`
Pokazuje plan bez usuwania.
Przyklady:
Przykłady:
```bash
./rvctl tokens remove store r1
@@ -493,14 +493,14 @@ Przyklady:
## `tokens read`
Pokazuje zawartosc `tokens/tokens.json` w podziale na endpointy serwerow.
Pokazuje zawartość `tokens/tokens.json` w podziale na endpointy serwerów.
Przelaczniki:
Przełączniki:
- `--server ENDPOINT`
Ogranicza wynik do jednego endpointu.
- `--show-secrets`
Pokazuje pelne wartosci tokenow zamiast maskowania.
Pokazuje pełne wartości tokenów zamiast maskowania.
Typowy wynik:
@@ -516,7 +516,7 @@ id<TAB>r1<TAB>SE****23
user<TAB>r1<TAB>u1
```
Przyklad:
Przykład:
```bash
./rvctl tokens read
@@ -525,13 +525,13 @@ Przyklad:
## `tokens stats`
Pokazuje statystyki endpointow z repo i `tokens.json`, a takze ich zgodnosc
wzgledem siebie.
Pokazuje statystyki endpointów z repo i `tokens.json`, a także ich zgodność
względem siebie.
Przelaczniki:
Przełączniki:
- `--repo PATH`
Sciezka wewnatrz repo, z ktorego maja byc odczytane remote URL-e.
Ścieżka wewnątrz repo, z którego mają być odczytane remote URL-e.
- `--server ENDPOINT`
Ogranicza wynik do jednego endpointu.
@@ -553,7 +553,7 @@ item<TAB>value
in_sync<TAB>1
```
Przyklad:
Przykład:
```bash
./rvctl tokens stats --repo ~/dev/workspace/rv/series/inf/03
@@ -563,10 +563,10 @@ Przyklad:
Wpisuje dane z `tokens/tokens.json` do wybranego remota repo.
Przelaczniki:
Przełączniki:
- `--repo PATH`
Sciezka wewnatrz docelowego repo. Domyslnie biezacy katalog.
Ścieżka wewnątrz docelowego repo. Domyślnie bieżący katalog.
- `--remote NAME`
Nazwa remota do aktualizacji lub utworzenia.
- `--url URL`
@@ -574,15 +574,15 @@ Przelaczniki:
- `--server ENDPOINT`
Endpoint serwera z `tokens.json`.
- `--user NAME`
Uzytkownik z wybranego endpointu.
Użytkownik z wybranego endpointu.
- `--token-name NAME`
Remote id w `tokens.json`, na przyklad `r1`. Domyslnie wartosc `--remote`.
Remote id w `tokens.json`, na przykład `r1`. Domyślnie wartość `--remote`.
- `--replace`
Nadpisuje inne dane auth juz wpisane w remote URL.
Nadpisuje inne dane auth już wpisane w remote URL.
- `--dry-run`
Pokazuje plan bez zapisu.
Przyklad:
Przykład:
```bash
./rvctl tokens write --repo ~/dev/workspace/rv/series/inf/03 --remote r1 --server http://77.90.8.171:3001
@@ -593,14 +593,14 @@ Przyklad:
Pobiera z API metadane dla rekordu `REMOTE_ID` zapisanego w `tokens.json`.
Nie synchronizuje sekretu z git remote.
Przelaczniki:
Przełączniki:
- `--server ENDPOINT`
Opcjonalny wybor endpointu, jesli ten sam `REMOTE_ID` istnieje dla wielu serwerow.
Opcjonalny wybór endpointu, jeśli ten sam `REMOTE_ID` istnieje dla wielu serwerów.
- `--dry-run`
Pokazuje plan bez zapisu.
Przyklad:
Przykład:
```bash
./rvctl tokens update r1
@@ -608,32 +608,32 @@ Przyklad:
## `tokens update --from ...`
Komendy zgodnosci dla starego modelu kierunkowego.
Komendy zgodności dla starego modelu kierunkowego.
Przelaczniki:
Przełączniki:
- `--from remotes`
Skanuje remote URL-e i zapisuje wynik do `tokens.json`.
- `--from store`
Bierze dane z `tokens.json` i wpisuje je do remota repo.
- `--repo PATH`
Sciezka wewnatrz repo.
Ścieżka wewnątrz repo.
- `--remote NAME`
Wymagane dla `--from store`.
- `--url URL`
Opcjonalny URL dla `--from store`.
- `--server ENDPOINT`
Opcjonalny wybor endpointu dla `--from store`.
Opcjonalny wybór endpointu dla `--from store`.
- `--user NAME`
Opcjonalny wybor usera dla `--from store`.
Opcjonalny wybór usera dla `--from store`.
- `--token-name NAME`
Opcjonalny wybor remote id dla `--from store`.
Opcjonalny wybór remote id dla `--from store`.
- `--replace`
Nadpisuje inne auth przy `--from store`.
- `--dry-run`
Pokazuje plan bez zapisu.
Przyklady:
Przykłady:
```bash
./rvctl tokens update --from remotes --repo ~/dev/workspace/rv/series/inf/03
@@ -642,20 +642,20 @@ Przyklady:
## `submission [series] [card]`
Wylicza flow oddawania rozwiazan:
Wylicza przepływ oddawania rozwiązań:
- `r1` jako repo z materialem z `edu-inf`
- `r1` jako repo z materiałem z `edu-inf`
- `a1` jako repo odpowiedzi w `zsl-inf`
- branch ucznia na podstawie jego nicku
Nazwa repo odpowiedzi jest budowana z nazwy repo zrodlowego z `edu-inf`, klasy
Nazwa repo odpowiedzi jest budowana z nazwy repo źródłowego z `edu-inf`, klasy
i daty:
```text
<repo_z_edu-inf>-<klasa>-<data>
```
Przyklad:
Przykład:
```text
lab-rv32i-strlen-bss-data-stack-4i-2026-04-26
@@ -664,26 +664,26 @@ lab-rv32i-strlen-bss-data-stack-4i-2026-04-26
Argumenty pozycyjne:
- `series`
Id serii albo pelny selector, na przyklad `inf` albo `inf/03`.
Id serii albo pełny selector, na przykład `inf` albo `inf/03`.
- `card`
Numer karty, na przyklad `03`.
Numer karty, na przykład `03`.
Przelaczniki:
Przełączniki:
- `--class NAME`
Id klasy, na przyklad `4i`.
Id klasy, na przykład `4i`.
- `--nick NAME`
Nick ucznia. Domyslnie z niego powstaje nazwa brancha.
Nick ucznia. Domyślnie z niego powstaje nazwa brancha.
- `--branch NAME`
Nadpisuje domyslna nazwe brancha.
Nadpisuje domyślną nazwę brancha.
- `--date YYYY-MM-DD`
Data zajec uzywana w nazwie repo odpowiedzi. Domyslnie dzisiejsza.
Data zajęć używana w nazwie repo odpowiedzi. Domyślnie dzisiejsza.
- `--source-url URL`
Nadpisuje URL repo zrodlowego. Bez tego launcher czyta `origin` z repo karty.
Nadpisuje URL repo źródłowego. Bez tego launcher czyta `origin` z repo karty.
- `--apply`
Dodaje albo aktualizuje remote `r1` i `a1` w repo karty.
Typowy format wyjscia:
Typowy format wyjścia:
```text
selector<TAB>inf/03
@@ -698,7 +698,7 @@ answer_url<TAB>http://77.90.8.171:3001/zsl-inf/lab-rv32i-strlen-bss-data-stack-4
student_branch<TAB>u1
```
Przyklady:
Przykłady:
```bash
./rvctl submission inf 03 --class 4i --nick u1
@@ -708,37 +708,37 @@ Przyklady:
## `tmux-container [series] [card]`
Tworzy nowa sesje `tmux` i uruchamia kontener w `pane 0`.
Tworzy nową sesję `tmux` i uruchamia kontener w `pane 0`.
Argumenty pozycyjne:
- `series`
Id serii albo pelny selector, na przyklad `inf` albo `inf/03`.
Id serii albo pełny selector, na przykład `inf` albo `inf/03`.
- `card`
Numer karty, na przyklad `03`.
Numer karty, na przykład `03`.
Przelaczniki:
Przełączniki:
- `--session NAME`
Nadpisuje nazwe sesji `tmux`.
Nadpisuje nazwę sesji `tmux`.
- `--window NAME`
Nadpisuje nazwe okna `tmux`.
Nadpisuje nazwę okna `tmux`.
- `--instance NAME`
Ustawia `RV_INSTANCE` dla wrappera `rv`.
- `--attach`
Po utworzeniu sesji robi `tmux attach`.
- `--dry-run`
Nie uruchamia `tmux`; wypisuje selector, sciezki i koncowa komende.
Nie uruchamia `tmux`; wypisuje selector, ścieżki i końcową komendę.
Reguly wyboru karty:
Reguły wyboru karty:
- `tmux-container inf 03` -> seria `inf`, karta `03`
- `tmux-container inf/03` -> pelny selector
- `tmux-container 03` -> domyslna seria + karta `03`
- `tmux-container inf` -> seria `inf` + domyslna karta
- bez argumentow -> domyslna seria i domyslna karta
- `tmux-container inf/03` -> pełny selector
- `tmux-container 03` -> domyślna seria + karta `03`
- `tmux-container inf` -> seria `inf` + domyślna karta
- bez argumentów -> domyślna seria i domyślna karta
Przyklady:
Przykłady:
```bash
./rvctl tmux-container 03 --dry-run
doc/series.md
+21 -21
View File
@@ -7,16 +7,16 @@ pracy i zadaniami w kartach.
Komendy kart pracy dzielimy na trzy poziomy:
- `series` - operacje na serii jako calosci
- `series` - operacje na serii jako całości
- `series cards` - operacje na kartach w ramach serii
- `series cards tasks` - operacje na zadaniach w ramach karty
Uzywamy pluralnych namespace'ow `cards` i `tasks`, bo opisuja kolekcje zasobow
i sa spojne z pluralnym `tokens`.
Używamy pluralnych namespace'ów `cards` i `tasks`, bo opisują kolekcje zasobów
i są spójne z pluralnym `tokens`.
## Szybki Flow
## Szybki przepływ
Typowy przeplyw pracy:
Typowy przepływ pracy:
```bash
./rvctl tokens compare
@@ -35,13 +35,13 @@ Typowy przeplyw pracy:
### `series list`
Listuje dostepne serie w workspace.
Listuje dostępne serie w workspace.
```bash
./rvctl series list
```
Przykladowy wynik:
Przykładowy wynik:
```text
series cards workspace
@@ -51,7 +51,7 @@ inf 12 ~/dev/workspace/rv/series/inf
### `series show SERIES`
Pokazuje informacje o serii jako calosci.
Pokazuje informacje o serii jako całości.
```bash
./rvctl series show inf
@@ -69,14 +69,14 @@ cards 01 02 03 ...
### `series fetch SERIES`
Pobiera albo aktualizuje cala serie w workspace.
Pobiera albo aktualizuje całą serię w workspace.
```bash
./rvctl series fetch inf
```
Ta komenda pracuje na wszystkich kartach w serii. Do pobrania jednej karty
sluzy `series cards fetch`.
służy `series cards fetch`.
## Karty
@@ -88,7 +88,7 @@ Listuje karty w wybranej serii.
./rvctl series cards list inf
```
Przykladowy wynik:
Przykładowy wynik:
```text
series card repo
@@ -119,7 +119,7 @@ tasks task1 task2 ...
### `series cards fetch SERIES CARD`
Pobiera albo aktualizuje jedna karte w workspace.
Pobiera albo aktualizuje jedną kartę w workspace.
```bash
./rvctl series cards fetch inf 03
@@ -127,7 +127,7 @@ Pobiera albo aktualizuje jedna karte w workspace.
### `series cards submission SERIES CARD`
Pokazuje albo stosuje konfiguracje repo odpowiedzi dla karty.
Pokazuje albo stosuje konfigurację repo odpowiedzi dla karty.
```bash
./rvctl series cards submission inf 03 --class 4i --nick u1
@@ -139,17 +139,17 @@ do pracy z repo odpowiedzi.
## Zadania W Karcie
Zadania sa czescia karty, dlatego trzymamy je pod `series cards tasks`.
Zadania są częścią karty, dlatego trzymamy je pod `series cards tasks`.
### `series cards tasks list SERIES CARD`
Listuje zadania dostepne w konkretnej karcie.
Listuje zadania dostępne w konkretnej karcie.
```bash
./rvctl series cards tasks list inf 03
```
Przykladowy wynik:
Przykładowy wynik:
```text
series card task path
@@ -176,12 +176,12 @@ workspace_path ~/dev/workspace/rv/series/inf/03/task1
card_path ~/dev/workspace/rv/series/inf/03
```
Na tym poziomie nie wprowadzamy osobnego `fetch`: zadania sa pobierane razem z
karta przez `series cards fetch` albo razem z cala seria przez `series fetch`.
Na tym poziomie nie wprowadzamy osobnego `fetch`: zadania są pobierane razem z
kartą przez `series cards fetch` albo razem z całą serią przez `series fetch`.
## Aliasowanie Starych Komend
Stare komendy mozna zostawic jako aliasy kompatybilnosci:
Stare komendy można zostawić jako aliasy kompatybilności:
```text
list-series -> series list
@@ -189,7 +189,7 @@ list-cards inf -> series cards list inf
submission inf 03 --class K --nick N -> series cards submission inf 03 --class K --nick N
```
Komendy `series cards tasks ...` nie maja starego odpowiednika i powinny byc
Komendy `series cards tasks ...` nie mają starego odpowiednika i powinny być
wprowadzane tylko w nowym namespace.
Dokumentacja i nowe przyklady powinny promowac namespace `series`.
Dokumentacja i nowe przykłady powinny promować namespace `series`.
doc/tokens.md
+69 -66
View File
@@ -1,18 +1,18 @@
# Tokens
`rvctl` obsluguje tokeny Gitea w dwoch miejscach:
`rvctl` obsługuje tokeny Gitea w dwóch miejscach:
- `tokens.json` - lokalny store sekretow i metadanych tokenow
- `tokens.json` - lokalny store sekretów i metadanych tokenów
- `.git/config` - git remotes w konkretnym repo
Rekord w `tokens.json` zawiera token, endpoint serwera, login oraz docelowe
`org/repo`. Git remote sluzy tylko do operacji Git (`fetch`, `push`) albo do
`org/repo`. Git remote służy tylko do operacji Git (`fetch`, `push`) albo do
pierwszego wczytania tokena do store.
Bez `--repo` komendy tokenow dzialaja na repo `rv-launcher`. Dla kart pracy albo
Bez `--repo` komendy tokenów działają na repo `rv-launcher`. Dla kart pracy albo
innych repo podaj `--repo PATH`.
## Szybki Flow
## Szybki przepływ
Startujemy od git remota z tokenem w URL-u:
@@ -40,15 +40,15 @@ Pobieramy z API metadane tokena:
./rvctl tokens update r1
```
Sprawdzamy zgodnosc remote i store:
Sprawdzamy zgodność remote i store:
```bash
./rvctl tokens cmp
```
Po poprawnej synchronizacji `compare`/`cmp` powinien pokazac `*` przy `r1`.
Po poprawnej synchronizacji `compare`/`cmp` powinien pokazać `*` przy `r1`.
Jesli chcesz sprawdzic, czy store da sie odtworzyc z remota, usun tylko rekord
Jeśli chcesz sprawdzić, czy store da się odtworzyć z remota, usuń tylko rekord
ze store i wczytaj go ponownie z git remota:
```bash
@@ -58,27 +58,30 @@ ze store i wczytaj go ponownie z git remota:
./rvctl tokens cmp
```
Po `sync remote` metadane API sa ustawiane na `?`, dlatego `update` jest zawsze
Po `sync remote` metadane API są ustawiane na `?`, dlatego `update` jest zawsze
kolejnym krokiem.
## Dwa Zrodla
## Dwa Źródła
`rvctl` rozroznia dwa miejsca:
`rvctl` rozróżnia dwa miejsca:
- git remote w repo, np. `http://u1:SECRET@host/org/repo.git`
- lokalny store `~/dev/workspace/rv/tokens/tokens.json`
Kierunki sa jawne:
Komendy zapisujące store same tworzą katalog nadrzędny, jeżeli go nie ma.
Katalog `tokens` dostaje prawa `700`, a plik `tokens.json` prawa `600`.
Kierunki są jawne:
- `sync remote r1` czyta git remote i zapisuje rekord do `tokens.json`
- `sync store r1` czyta `tokens.json` i zapisuje auth do git remota
- `update r1` nie synchronizuje sekretu, tylko odswieza metadane z API
- `update r1` nie synchronizuje sekretu, tylko odświeża metadane z API
- `remove remote r1` albo `rm remote r1` usuwa git remote
- `remove store r1` albo `rm store r1` usuwa rekord z `tokens.json`
## Listowanie
`list` pokazuje zrodla bez porownywania:
`list` pokazuje źródła bez porównywania:
```bash
./rvctl tokens list store
@@ -90,7 +93,7 @@ Znaczenie:
- `store` - rekordy zapisane w `tokens.json`
- `remote` - git remotes zapisane w `.git/config`
- `both` - oba zrodla jako osobne wiersze
- `both` - oba źródła jako osobne wiersze
Dla innego repo podaj `--repo`:
@@ -102,14 +105,14 @@ Dla innego repo podaj `--repo`:
### Remote -> Store
Uzyj, gdy token jest w git remote i chcesz go zapisac w store:
Użyj, gdy token jest w git remote i chcesz go zapisać w store:
```bash
./rvctl tokens sync remote r1
```
Ta komenda kopiuje sekret, usera, endpoint, org i repo z URL-a remota do
`tokens.json`. Nie pyta API o uprawnienia, wiec zawsze zeruje metadane API:
`tokens.json`. Nie pyta API o uprawnienia, więc zawsze zeruje metadane API:
`valid` ustawia na `?`, maski `scope`, `org_perm` i `repo_perm` ustawia na `?`,
a `expires_at` usuwa. Realne uprawnienia wpisuje dopiero:
@@ -119,27 +122,27 @@ a `expires_at` usuwa. Realne uprawnienia wpisuje dopiero:
### Store -> Remote
Uzyj, gdy token jest juz w `tokens.json`, a chcesz utworzyc albo odswiezyc git
Użyj, gdy token jest już w `tokens.json`, a chcesz utworzyć albo odświeżyć git
remote:
```bash
./rvctl tokens sync store r1
```
Jesli remote `r1` nie istnieje, `rvctl` buduje URL z pol `server.endpoint`,
`org` i `repo` w `tokens.json`, na przyklad:
Jeśli remote `r1` nie istnieje, `rvctl` buduje URL z pól `server.endpoint`,
`org` i `repo` w `tokens.json`, na przykład:
```text
http://77.90.8.171:3001/edu-tools/rv-launcher.git
```
Opcjonalnie mozna podac URL recznie:
Opcjonalnie można podać URL ręcznie:
```bash
./rvctl tokens sync store r1 --url http://77.90.8.171:3001/edu-tools/rv-launcher.git
```
Jesli remote ma juz inne credentials, uzyj:
Jeśli remote ma już inne credentials, użyj:
```bash
./rvctl tokens sync store r1 --replace
@@ -147,7 +150,7 @@ Jesli remote ma juz inne credentials, uzyj:
## Aktualizacja Metadanych
Po zapisaniu tokena w store odswiez jego metadane z API:
Po zapisaniu tokena w store odśwież jego metadane z API:
```bash
./rvctl tokens update r1
@@ -162,9 +165,9 @@ Po zapisaniu tokena w store odswiez jego metadane z API:
Ta komenda nie zmienia git remota i nie kopiuje sekretu.
## Porownanie
## Porównanie
`compare` sprawdza zgodnosc store i remote. Skrot: `cmp`.
`compare` sprawdza zgodność store i remote. Skrót: `cmp`.
```bash
./rvctl tokens compare
@@ -173,13 +176,13 @@ Ta komenda nie zmienia git remota i nie kopiuje sekretu.
Marker w kolumnie `token_ref`:
- `*` - store i remote sa zgodne
- `*` - store i remote są zgodne
- `S` - token jest tylko w store
- `R` - token jest tylko w remote
- `!` - wpis jest sparowany, ale token jest `invalid` albo wystapil blad API
- `!` - wpis jest sparowany, ale token jest `invalid` albo wystąpił błąd API
Gdy marker to `S`, token nie jest bledny. To znaczy tylko, ze nie ma
odpowiadajacego git remota.
Gdy marker to `S`, token nie jest błędny. To znaczy tylko, że nie ma
odpowiadającego git remota.
## Store-only
@@ -193,13 +196,13 @@ Po pierwszej konfiguracji wygodny tryb pracy to trzymanie tokena tylko w
```
Wtedy `compare`/`cmp` pokazuje `S`, a `list store` nadal pokazuje znane metadane
tokenu. Gdy trzeba wykonac operacje git przez remote, odtworz remote:
tokenu. Gdy trzeba wykonać operacje git przez remote, odtwórz remote:
```bash
./rvctl tokens sync store r1
```
Po operacji mozna go znowu usunac:
Po operacji można go znowu usunąć:
```bash
./rvctl tokens rm remote r1
@@ -207,7 +210,7 @@ Po operacji mozna go znowu usunac:
## Usuwanie
Usuwaj tylko to miejsce, ktore naprawde chcesz wyczyscic:
Usuwaj tylko to miejsce, które naprawdę chcesz wyczyścić:
```bash
./rvctl tokens rm remote r1
@@ -223,7 +226,7 @@ Znaczenie:
## Inne Repo
Domyslnie komendy tokenow pracuja na repo zawierajacym `rvctl`. Dla kart pracy
Domyślnie komendy tokenów pracują na repo zawierającym `rvctl`. Dla kart pracy
albo innych repo podaj `--repo`.
```bash
@@ -232,17 +235,17 @@ albo innych repo podaj `--repo`.
./rvctl tokens sync store r1 --repo ~/dev/workspace/rv/series/inf/03
```
Store tokenow nadal pozostaje jeden:
Store tokenów nadal pozostaje jeden:
```text
~/dev/workspace/rv/tokens/tokens.json
```
## Pozostale Komendy
## Pozostałe Komendy
### `tokens read`
Pokazuje zawartosc `tokens.json`.
Pokazuje zawartość `tokens.json`.
```bash
./rvctl tokens read
@@ -252,24 +255,24 @@ Pokazuje zawartosc `tokens.json`.
### `tokens add`
Dodaje szkielet rekordu do `tokens.json`. `REMOTE_ID` musi odpowiadac nazwie
git remote. Przelaczniki sa opcjonalne; jesli ich nie podasz, `rvctl` zapisuje
puste wartosci do pozniejszego uzupelnienia. Wyjatkiem jest `server`, ktory
domyslnie pochodzi z `workspace.json`.
Dodaje szkielet rekordu do `tokens.json`. `REMOTE_ID` musi odpowiadać nazwie
git remote. Przełączniki są opcjonalne; jeśli ich nie podasz, `rvctl` zapisuje
puste wartości do późniejszego uzupełnienia. Wyjątkiem jest `server`, który
domyślnie pochodzi z `workspace.json`.
```bash
./rvctl tokens add r1
./rvctl tokens add r1 --server http://77.90.8.171:3001 --user u1 --org edu-tools --repo rv-launcher
```
Najczesciej pusty szkielet ma sens wtedy, gdy chcesz recznie wpisac token w
`tokens.json`. `sync store r1` nie uzyje pustego tokena. Najpierw trzeba
uzupelnic co najmniej `value` i `user`. Jesli remote ma byc tworzony bez `--url`,
potrzebne sa tez `org` i `repo`.
Najczęściej pusty szkielet ma sens wtedy, gdy chcesz ręcznie wpisać token w
`tokens.json`. `sync store r1` nie użyje pustego tokena. Najpierw trzeba
uzupełnić co najmniej `value` i `user`. Jeśli remote ma być tworzony bez `--url`,
potrzebne są też `org` i `repo`.
### `tokens stats`
Pokazuje kontekst, tabele `tokens` i podsumowanie statusow endpointow.
Pokazuje kontekst, tabelę `tokens` i podsumowanie statusów endpointów.
```bash
./rvctl tokens stats
@@ -278,10 +281,10 @@ Pokazuje kontekst, tabele `tokens` i podsumowanie statusow endpointow.
## Uprawnienia
W `tokens.json` uprawnienia sa zapisane jako mapy klucz-wartosc. W tabelach CLI
sa pokazywane jako zwarte maski.
W `tokens.json` uprawnienia są zapisane jako mapy klucz-wartość. W tabelach CLI
są pokazywane jako zwarte maski.
Naglowki masek:
Nagłówki masek:
- `scope`: `aAimnopru`
- `org`: `oawrc-`
@@ -299,17 +302,17 @@ Kategorie `scope`:
- `r` - repository
- `u` - user
Wartosci w `scope`:
Wartości w `scope`:
- `w` - read/write
- `r` - read
- `-` - no access
- `?` - nie wczytano
- `!` - blad wczytania
- `!` - błąd wczytania
Gitea moze zwrocic globalny scope `all` zamiast listy `write:*`. Launcher
rozwija wtedy `all` do pelnej maski `wwwwwwwww`. Scope `public-only` jest
flaga ograniczenia widocznosci API i nie zmienia kategorii w tej masce.
Gitea może zwrócić globalny scope `all` zamiast listy `write:*`. Launcher
rozwija wtedy `all` do pełnej maski `wwwwwwwww`. Scope `public-only` jest
flagą ograniczenia widoczności API i nie zmienia kategorii w tej masce.
Kategorie `org_perm`:
@@ -326,17 +329,17 @@ Kategorie `repo_perm`:
- `w` - write
- `r` - read
Wartosci w `org_perm` i `repo_perm`:
Wartości w `org_perm` i `repo_perm`:
- `+` - flaga wlaczona
- `-` - flaga wylaczona
- `+` - flaga włączona
- `-` - flaga wyłączona
- `?` - nie wczytano
- `!` - blad wczytania
- `!` - błąd wczytania
## Model Danych
`tokens.json` ma format `version: 3`. Glownym rekordem jest jeden remote-token.
Pole `id` jest obowiazkowe i musi byc takie samo jak nazwa git remote, np.
`tokens.json` ma format `version: 3`. Głównym rekordem jest jeden remote-token.
Pole `id` jest obowiązkowe i musi być takie samo jak nazwa git remote, np.
`r1` albo `r1a`.
Pola synchronizowane z git remote:
@@ -351,16 +354,16 @@ Pola synchronizowane z git remote:
Pola pobierane z API przez `tokens update r1`:
- `valid` - `forever`, data wygasniecia, `invalid`, `?` albo `!`
- `valid` - `forever`, data wygaśnięcia, `invalid`, `?` albo `!`
- `scope` - mapa scope tokena
- `org_perm` - mapa praw uzytkownika w organizacji
- `repo_perm` - mapa praw uzytkownika w repo
- `org_perm` - mapa praw użytkownika w organizacji
- `repo_perm` - mapa praw użytkownika w repo
`tokens sync remote r1` nadpisuje pola z git remota i oznacza te metadane jako
nieznane. To celowe: po zmianie sekretu, usera albo repo stare metadane API nie
sa juz wiarygodne.
są już wiarygodne.
Minimalny przyklad:
Minimalny przykład:
```json
{
@@ -384,7 +387,7 @@ Minimalny przyklad:
}
```
Przyklad po `tokens update r1` moze dodatkowo zawierac:
Przykład po `tokens update r1` może dodatkowo zawierać:
```json
{
@@ -416,4 +419,4 @@ Przyklad po `tokens update r1` moze dodatkowo zawierac:
}
```
Pelny schemat pliku jest w `doc/tokens.schema.json`.
Pełny schemat pliku jest w `doc/tokens.schema.json`.
doc/workspace.md
+3 -3
View File
@@ -1,6 +1,6 @@
# Workspace
Ten plik opisuje tylko kontekst workspace. Szczegolowy opis CLI jest w
Ten plik opisuje tylko kontekst workspace. Szczegółowy opis CLI jest w
`doc/rvctl.md`.
Publiczny entrypoint launchera:
@@ -9,5 +9,5 @@ Publiczny entrypoint launchera:
./rvctl
```
Implementacja CLI znajduje sie w `rvctl.py`. Plik `workspace.json` przechowuje
sciezki workspace, series, socketow, tokenow i fallback do repo zrodlowych.
Implementacja CLI znajduje się w `rvctl.py`. Plik `workspace.json` przechowuje
ścieżki workspace, series, socketów, tokenów i fallback do repo źródłowych.