stem-launcher/doc/series.md

# Series

Ten dokument opisuje komendy `rvctl` do pracy z seriami, kartami pracy i
zadaniami w kartach.

## Zasada

Komendy kart pracy dzielimy na trzy poziomy:

- `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

`rvctl` tworzy `series_root`, jeżeli katalog jeszcze nie istnieje. Lista serii
i kart pochodzi docelowo z publicznego manifestu
`~/dev/workspace/rv/meta/workspace-info/workspace.json`. Jeżeli manifestu nie
ma, komendy zależne od serii automatycznie klonują repo
`edu-workspace/workspace-info`. Jeżeli klonowanie nie jest możliwe, narzędzie
używa starego fallbacku przez `original_series_root`.

## Szybki przepływ

```bash
./rvctl tokens compare
./rvctl series list
./rvctl series use inf
./rvctl series cards list inf
./rvctl card use bss
./rvctl series cards fetch inf bss
./rvctl tasks list
./rvctl tasks switch 1
```

Dla karty `bss` właściwym repo jest `lab-rv32i-strlen-bss-data-stack`.

## Serie

### `series list`

Listuje dostępne serie z manifestu `workspace-info` oraz liczbę kart już
pobranych do lokalnego workspace. Jeżeli manifestu jeszcze nie ma, komenda
pobiera go automatycznie. Jeżeli `~/dev/workspace/rv/series` nie istnieje,
komenda tworzy ten katalog.

```bash
./rvctl series list
```

Typowy wynik:

```text
fiz  3  0
inf  3  0
```

Kolumny oznaczają: seria, liczba kart w źródłach, liczba kart pobranych do
workspace.

### `series show SERIES`

Pokazuje informacje o serii.

```bash
./rvctl series show inf
```

### `series use SERIES`

Ustawia domyślną serię w `workspace.json`. Po tej komendzie skróty kart i
zadań mogą korzystać z tej serii bez podawania jej za każdym razem.

```bash
./rvctl series use inf
```

## Karty

### `series cards list SERIES`

Listuje karty w wybranej serii.

```bash
./rvctl series cards list inf
```

Przykładowy wynik:

```text
bss  lab-rv32i-strlen-bss-data-stack  source  rv32i-c / bss-data-stack
```

Pierwsza kolumna jest krótką nazwą karty. Pełna nazwa repo zostaje w drugiej
kolumnie.

### `card use CARD`

Ustawia domyślną kartę w aktualnie domyślnej serii. Dla serii `inf`:

```bash
./rvctl card use bss
```

Komenda zapisuje `defaults.card` w `workspace.json`.

### `card use SERIES CARD`

Ustawia jednocześnie domyślną serię i domyślną kartę:

```bash
./rvctl card use inf bss
```

To jest odpowiednik:

```bash
./rvctl series use inf
./rvctl card use bss
```

### `series cards fetch SERIES CARD`

Pobiera albo aktualizuje jedną kartę w workspace. `CARD` może być krótką nazwą
albo unikalnym fragmentem pełnej nazwy repo.

```bash
./rvctl series cards fetch inf bss
```

Karta trafia do:

```text
~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack
```

Po pobraniu `rvctl` przygotowuje remotes:

- `r1` - repo źródłowe karty w `edu-inf`
- `r1a` - repo pracy w `c2025-1a-inf`

Remote `r1a` jest tworzony z tokena `r1` i wskazuje na repo o tej samej nazwie
co karta:

```text
http://77.90.8.171:3001/c2025-1a-inf/lab-rv32i-strlen-bss-data-stack.git
```

### `series cards show SERIES CARD`

Pokazuje informacje o karcie.

```bash
./rvctl series cards show inf bss
```

### `series cards submission SERIES CARD`

Pokazuje albo stosuje konfigurację repo odpowiedzi dla karty.

```bash
./rvctl series cards submission inf bss --class c2025-1a-inf
./rvctl series cards submission inf bss --class c2025-1a-inf --task 4 --apply
```

Bez `--apply` komenda pokazuje plan. Z `--apply` ustawia remotes potrzebne do
pracy z repo odpowiedzi. Jeżeli nie podasz `--branch`, branch jest liczony ze
store tokenów i zadania, na przykład `u1T1a`.

## Zadania w karcie

Zadania są częścią karty, dlatego trzymamy je pod `series cards tasks`.
Do codziennej pracy z domyślną kartą można używać krótszego namespace `tasks`.

### `series cards tasks list SERIES CARD`

Listuje zadania dostępne w konkretnej karcie.
`rvctl` rozpoznaje zadania zapisane jako pliki lub katalogi `task*` w
`src/tasks`, a także katalogi `task*` bezpośrednio w korzeniu karty.

```bash
./rvctl series cards tasks list inf bss
```

Skrót dla domyślnej karty:

```bash
./rvctl tasks list
```

Przykładowy wynik:

```text
inf  bss  task1_bss           ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack/src/tasks/task1_bss.c
inf  bss  task2_data          ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack/src/tasks/task2_data.c
inf  bss  task3_stack_unused  ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack/src/tasks/task3_stack_unused.c
inf  bss  task4_stack_strlen  ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack/src/tasks/task4_stack_strlen.c
```

### `series cards tasks show SERIES CARD TASK`

Pokazuje informacje o konkretnym zadaniu w karcie.

```bash
./rvctl series cards tasks show inf bss task1
```

Skrót dla domyślnej karty:

```bash
./rvctl tasks show 1
```

### `series cards tasks switch SERIES CARD TASK`

Tworzy albo przełącza lokalny branch pracy dla wybranego zadania.

```bash
./rvctl series cards tasks switch inf bss 4
```

Skrót dla domyślnej karty:

```bash
./rvctl tasks switch 4
```

Nazwa brancha jest liczona automatycznie z użytkownika w `tokens.json` i numeru
zadania. Dla użytkownika `u1` i zadania `task4_stack_strlen` powstanie:

```text
u1T4a
```

Jeżeli branch już istnieje, `rvctl` przełącza na niego repo. Jeżeli go nie ma,
tworzy go od aktualnego commita karty. Branch dostaje upstream `r1a/<branch>`,
na przykład `r1a/u1T4a`.

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 zostają jako aliasy kompatybilności:

```text
list-series                         -> series list
list-cards inf                      -> series cards list inf
submission inf bss --class K        -> series cards submission inf bss --class K
```

Dokumentacja i nowe przykłady powinny promować namespace `series`.