# Migracja `rv-launcher` do `stem-launcher`

Status: M1–M4 wdrożone; M5 pozostaje okresem zgodności
Data: 2026-07-14

## Dlaczego zmieniamy nazwę

Launcher obsługuje już kod natywny AMD64 i Hazard3, a plan obejmuje RP2350
RISC-V, RP2350 ARM, fizykę i kolejne serie STEM. Nazwy `rv-launcher`, `rvctl`,
`RV_*` i `~/dev/workspace/rv` błędnie sugerują narzędzie ograniczone do RISC-V.

Docelowy słownik:

| Obecnie | Docelowo |
| --- | --- |
| `rv-launcher` | `stem-launcher` |
| `rvctl` | `stemctl` |
| `rvctl.py` | wewnętrzny moduł launchera; nazwa nie jest publicznym API |
| `RV_*` | `STEM_*` |
| `.rv/` | `.stem/` |
| `~/dev/workspace/rv` | `~/dev/workspace/stem` |
| profil `host` | `native-amd64` |
| profil `rv32i` | `hazard3-sim` |

## Zasada migracji

Najpierw dostarczamy zgodność w kodzie, a dopiero później zmieniamy nazwę repo
na serwerze. Odwrotna kolejność zepsułaby bootstrap, token records, remotes,
ścieżki dokumentacji i istniejące workspace uczniów.

## Etapy

### M1 — alias CLI (wdrożone)

- dodać wykonywalny `stemctl` wskazujący tę samą implementację;
- pozostawić `rvctl` jako cichy wrapper;
- pomoc i nowe materiały pokazują wyłącznie `stemctl`;
- `rvctl` nie dopisuje ostrzeżeń do stderr i zachowuje format stdout/stderr
  potrzebny istniejącym skryptom.

### M2 — konfiguracja i ścieżki (wdrożone)

- dodać wersjonowaną migrację `workspace.json`;
- nowe zmienne `STEM_*` mają pierwszeństwo, stare `RV_*` są fallbackiem;
- jeśli istnieje `/workspace/.stem`, użyć go;
- jeśli istnieje tylko `/workspace/.rv`, użyć go i zaproponować migrację;
- komenda `stemctl workspace doctor` pokazuje użyte ścieżki i runtime;
- komenda `stemctl workspace migrate --dry-run` nie zmienia danych, tylko
  pokazuje plan.

Migracja katalogu stanu musi być atomowa na pojedynczym filesystemie i nigdy
nie usuwa starego katalogu przed zweryfikowaniem nowego.

### M3 — profile i kontenery (wdrożone)

- wprowadzić `native-amd64`, `hazard3-sim`, `rp2350`;
- zachować aliasy `host -> native-amd64` oraz `rv32i -> hazard3-sim`;
- kontenery otrzymują labels z nazwą kanoniczną, nie aliasem;
- wyniki zapisują nazwę kanoniczną oraz opcjonalne `requested_alias`.

### M4 — repo Gitea (wdrożone 2026-07-14)

Po wydaniu kompatybilnego launchera wykonano:

1. zmianę nazwy na `edu-tools/stem-launcher` przez API Gitea;
2. aktualizację lokalnego `origin`, bootstrapu, dokumentacji i przykładów
   token records;
3. weryfikację clone/fetch/push przez nowy URL;
4. weryfikację przekierowania starej nazwy przez Gitea;
5. zachowanie wrappera `rvctl` i pozostałych aliasów na okres zgodności.

Operację administracyjną wykonano po SSH do VPS i przez ograniczony token API;
sekret nie znajduje się w repo ani w konfiguracji launchera.

### M5 — wycofanie kompatybilności

Stare nazwy można usunąć dopiero, gdy:

- wszystkie serie w `workspace-info` wskazują nowe CLI i repo;
- CI nie używa `rvctl`, `RV_*`, `.rv` ani profili `host`/`rv32i`;
- obraz pracowni został odświeżony;
- co najmniej jeden pełny cykl zajęć przeszedł na `stemctl`;
- dostępna jest instrukcja ręcznego odzyskania starego workspace.

## Testy migracji

1. Nowa instalacja bez istniejącego workspace.
2. Istniejący workspace `/rv` z kartami i bez aktywnych kontenerów.
3. Workspace z `.rv/<instance>` i zatrzymanym kontenerem.
4. Store tokenów wskazujący repo `rv-launcher`.
5. Remotes bez sekretu oraz remotes z historycznym tokenem w URL.
6. Równoległe instancje profili `host` i `rv32i`.
7. Ponowne wykonanie migracji — wynik musi być idempotentny.
8. Rollback konfiguracji bez utraty repo, branchy, artefaktów i logów.

## Kryterium zakończenia

Uczeń po migracji wykonuje:

```bash
stemctl series cards fetch inf bss
stemctl test native-amd64 inf bss 1
stemctl debug hazard3-sim inf bss 1
stemctl deploy rp2350 inf bss 1 --target rp2350-rv --device /dev/bus/usb/001/006
```

Istniejący skrypt używający `rvctl debug rv32i` nadal działa w zadeklarowanym
okresie kompatybilności i trafia do tego samego kanonicznego profilu.