# Jak kontrybuować

## Architektura

Toolbox dzieli się na dwie kategorie poleceń z różnymi kontraktami.

### Polecenia (commands)

Operacje na zewnętrznych systemach, zaprojektowane do łączenia w potoki.

- Dane wyjściowe trafiają na **stdout** jako **NDJSON**
- Wyłącznie do użycia w potokach: `logintegra youtrack issues "..." | jq .`
- Nie wyświetlają interaktywnych elementów UI
- Nie pytają użytkownika o potwierdzenie

```
from logintegra_toolbox_cli.console import emit

for record in results:
    emit(record)
```

### Workflow

Gotowe scenariusze domenowe orkiestrujące wiele kroków. Działają jak TUI.

- Dane wyjściowe trafiają na **stdout** jako czytelny dla człowieka teskt (Rich, tabele, kolory)
- Mogą pytać użytkownika o potwierdzenie (`click.confirm`, `click.prompt`)
- Mogą wyświetlać paski postępu, spinnery itp.
- Nie są przeznaczone do pipowania

```
from rich.console import Console

console = Console()
console.print(f"[bold green]Release {version} created[/bold green]")
confirmed = click.confirm("Assign issues to release?")
```

## Logi

Niezależnie od kategorii, logi diagnostyczne zawsze trafiają na **stderr** - nigdy na stdout. Dzięki temu nie zakłócają strumienia danych przy pipowaniu.

```
import logging

logger = logging.getLogger(__name__)

logger.info("Found %d issues", len(results))    # widoczne domyślnie
logger.debug("Query: %s", query)                # widoczne tylko z --verbose
logger.error("Something went wrong: %s", e)    # zawsze widoczne
```

```

```

## Dodawanie nowego polecenia (command)

1. Stwórz moduł w odpowiednim pakiecie, np. `youtrack/commands.py`
2. Zdefiniuj grupę Click lub dodaj do istniejącej
3. Używaj `emit()` do wypisywania danych
4. Używaj `logger` do komunikatów
5. Dodaj polecenie do `main.py`

## Dodawanie nowego workflow

1. Stwórz logikę domenową w `workflows/<projekt>.py`
2. Dodaj polecenie Click w `workflows/commands.py`
3. Używaj Rich do prezentacji wyników
4. Używaj `click.confirm` / `click.prompt` do interakcji z użytkownikiem
5. Logikę domenową trzymaj oddzielnie od warstwy CLI (jak `apollo.py` vs `commands.py`)

## Styl kodu

```
uv run ruff format .
uv run ruff check .
uv run mypy src
uv run pytest
```

Kod piszemy po angielsku (nazwy zmiennych, komentarze, help stringi, komunikaty błędów).
