# Containers

Ten dokument opisuje docelowy model komend `rvctl` do uruchamiania
srodowiska 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.

Uzywamy namespace `containers`, a nie `container`, bo jest spojny z pluralnymi
namespace'ami `tokens`, `cards` i `tasks`.

## Szybki Flow

Typowy przeplyw pracy:

```bash
./rvctl tokens compare
./rvctl series cards show inf 03
./rvctl series cards tasks list inf 03
./rvctl containers show inf 03
./rvctl containers start inf 03 --session rv-inf03 --attach
./rvctl containers list
./rvctl containers stop rv-inf03
```

## Model

Docelowo komendy `containers` pracuja na trzech warstwach:

- karta pracy, np. `inf 03`
- opcjonalne zadanie, np. `--task task1`
- instancja srodowiska, np. `--instance shell`

Domyslne wartosci pochodza z `workspace.json`:

```text
defaults.series
defaults.card
defaults.task
defaults.instance
defaults.tmux_session
defaults.tmux_window
```

## Komendy

### `containers show [SERIES] [CARD]`

Pokazuje plan uruchomienia srodowiska bez tworzenia sesji `tmux`.

```bash
./rvctl containers show inf 03
./rvctl containers show inf/03 --task task1
```

Typowe pola:

```text
selector        inf/03
task            task1
card_path       ~/dev/workspace/rv/series/inf/03
task_path       ~/dev/workspace/rv/series/inf/03/task1
tools_root      ~/dev/workspace/rv/tools/rv32i-hazard3-env
session         rv-inf03
window          rv
instance        shell
```

Ta komenda jest odpowiednikiem obecnego trybu:

```bash
./rvctl tmux-container inf 03 --dry-run
```

### `containers start [SERIES] [CARD]`

Uruchamia sesje `tmux` i kontener dla wybranej karty.

```bash
./rvctl containers start inf 03
./rvctl containers start inf/03 --session rv-inf03
./rvctl containers start inf 03 --task task1 --instance shell --attach
```

Przelaczniki:

- `--task TASK`
  Wybiera zadanie w karcie. Bez tego `rvctl` uzywa domyslnego zadania z
  `workspace.json` albo pracuje na katalogu karty.
- `--session NAME`
  Nadpisuje nazwe sesji `tmux`.
- `--window NAME`
  Nadpisuje nazwe okna `tmux`.
- `--instance NAME`
  Ustawia wariant srodowiska, np. `shell`.
- `--attach`
  Po uruchomieniu od razu podlacza terminal do sesji.

### `containers list`

Listuje aktywne srodowiska uruchomione przez `rvctl`.

```bash
./rvctl containers list
```

Przykladowy wynik:

```text
session   selector  task   instance  window
--------  --------  -----  --------  ------
rv-inf03  inf/03    task1  shell     rv
```

### `containers attach SESSION`

Podlacza terminal do istniejacej sesji.

```bash
./rvctl containers attach rv-inf03
```

Technicznie odpowiada to:

```bash
tmux attach -t rv-inf03
```

### `containers stop SESSION`

Zamyka sesje `tmux`, a razem z nia uruchomiony w niej proces kontenera.

```bash
./rvctl containers stop rv-inf03
```

Technicznie odpowiada to:

```bash
tmux kill-session -t rv-inf03
```

## Aliasowanie Starej Komendy

Stara komenda moze zostac jako alias kompatybilnosci:

```text
tmux-container inf 03 --dry-run      -> containers show inf 03
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`.