# Containers

Ten dokument opisuje docelowy model komend `rvctl` do uruchamiania
środowiska programistycznego w kontenerach.

## Zasada

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.

Używamy namespace `containers`, a nie `container`, bo jest spójny z pluralnymi
namespace'ami `tokens`, `cards` i `tasks`.

## Szybki przepływ

Typowy przepływ 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` pracują na trzech warstwach:

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

Domyślne wartości pochodzą 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 środowiska 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 sesję `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
```

Przełączniki:

- `--task TASK`
  Wybiera zadanie w karcie. Bez tego `rvctl` używa domyślnego zadania z
  `workspace.json` albo pracuje na katalogu karty.
- `--session NAME`
  Nadpisuje nazwę sesji `tmux`.
- `--window NAME`
  Nadpisuje nazwę okna `tmux`.
- `--instance NAME`
  Ustawia wariant środowiska, np. `shell`.
- `--attach`
  Po uruchomieniu od razu podłącza terminal do sesji.

### `containers list`

Listuje aktywne środowiska uruchomione przez `rvctl`.

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

Przykładowy wynik:

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

### `containers attach SESSION`

Podłącza terminal do istniejącej sesji.

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

Technicznie odpowiada to:

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

### `containers stop SESSION`

Zamyka sesję `tmux`, a razem z nią 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 może zostać jako alias kompatybilności:

```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 przykłady powinny promować namespace `containers`.