# logintegra-toolbox-cli

Toolbox Logintegra

## Wymagania

- Python 3.14+
- [uv](<https://docs.astral.sh/uv/>)

## Instalacja

```
uv sync
```

## Konfiguracja

Skopiuj przykładowy plik konfiguracyjny do `~/.config/logintegra-toolbox/config.toml`:

```
cp config.example.toml ~/.config/logintegra-toolbox/config.toml
```

```
[youtrack]
url = "https://youtrack.example.com"

[bitbucket]
url = "https://api.bitbucket.org/2.0"
username = "your-atlassian-account@example.com"

[slack]
url = "https://slack.com/api"
```

## Dane uwierzytelniające

Skopiuj przykładowy plik credentials do `~/.config/logintegra-toolbox/.credentials.toml`:

```
cp .credentials.example.toml ~/.config/logintegra-toolbox/.credentials.toml
```

```
[youtrack]
token = "perm:your-youtrack-token"

[bitbucket]
token = "your-bitbucket-access-token"
```

Alternatywnie można użyć zmiennych środowiskowych:

```
export YOUTRACK_TOKEN=perm:your-youtrack-token
export BITBUCKET_TOKEN=your-bitbucket-access-token
```

## Użycie

```
uv run logintegra [OPCJE] KOMENDA
```

### YouTrack

```
# Sprawdź połączenie
logintegra youtrack ping

# Wylistuj issues pasujące do zapytania
logintegra youtrack issues "Sprint is wombaty-49"
```

### Bitbucket

```
# Sprawdź połączenie
logintegra bitbucket ping

# Wylistuj pull requesty (domyślnie OPEN)
logintegra bitbucket prs apollo
logintegra bitbucket prs apollo --state MERGED --target develop --limit 50

# Wylistuj branche pasujące do wzorca
logintegra bitbucket branches apollo --filter release-

# Wyciągnij klucze zadań YouTrack z pull requesta (tytuł, branch, opis, commity)
logintegra bitbucket pr-issues apollo 42 --project A
# {"key":"A-18301","pr_id":42,"repo":"apollo","sources":["title","branch","commit"]}
```

Workspace pobierany jest z `bitbucket.workspace` w konfiguracji; można go nadpisać opcją `--workspace`.

Pole `sources` mówi, **skąd** pochodzi dany klucz. Klucz znaleziony wyłącznie w nazwie brancha jest słabszą przesłanką niż klucz z commita - dlatego narzędzie nie zgaduje, tylko raportuje pochodzenie.

### YouTrack - zmiany na zadaniach

Polecenia zmieniające dane przyjmują listę zadań z argumentów **lub ze stdin** (klucze albo NDJSON) i wspierają `--dry-run`.

```
# Ustaw Release na wskazanych zadaniach
logintegra youtrack set-release release-4.159.0 A-18301 A-18302

# Tagi (needs-update, needs:manual-config)
logintegra youtrack tag needs-update A-18301
logintegra youtrack tag needs-update A-18301 --remove

# Dowolne polecenie YouTracka
logintegra youtrack command "State Fixed" A-18301 --comment "Wydane w 4.159.0"

# Komentarz (tekst z argumentu albo z pipe'a)
logintegra youtrack comment A-18301 "Uwagi do procesu"
```

**Najpierw `--dry-run`.** Pokazuje dokładnie, co i na jakich zadaniach zostałoby zmienione, i nie wywołuje API (nie wymaga nawet tokenu):

```
logintegra youtrack set-release release-4.159.0 A-18301 --dry-run
# {"key":"A-18301","command":"Release release-4.159.0","applied":false,"dry_run":true}
```

Pusty strumień na wejściu nie robi nic i wypisuje ostrzeżenie - nie jest traktowany jako sukces.

### Release - weryfikacja odcięcia

Porównuje **zadania wynikające z kodu** (commity, które są na branchu release, a nie były w poprzednim wydaniu) z **zadaniami oznaczonymi `Release`** w YouTracku.

```
logintegra release verify 4.159.0 \
  --repo apollo --repo apollo-frontend --repo msc \
  --previous release-4.158.0 --project A
```

Odcięcie obejmuje kilka repozytoriów (backend, frontend, mikroserwisy) - `--repo` powtarza się dla każdego z nich. Wszystkie repozytoria trzymają tę samą konwencję branchy, więc `--branch` i `--previous` są wspólne.

Repozytoria są uzgadniane **razem**, w jednym przebiegu, a nie osobno. To jest istotne: zadanie zrobione wyłącznie na froncie ma kod w odcięciu, więc jest `ok`. Trzy osobne uruchomienia `verify` (po jednym na repo) pokazałyby je jako `no_code` w backendzie i `ok` na froncie - sklejenie takich raportów daje fałszywe problemy.

Repo, które nie ma brancha release (np. mikroserwis nieodcinany w tym wydaniu), zwraca z Bitbucketa 404 - takie repo jest pomijane i nie przerywa weryfikacji. Pomięcie trafia na stderr jako ostrzeżenie, bo **literówka w `--repo` wygląda identycznie** jak repo bez zmian: w obu przypadkach repo nie wnosi kodu, a jego zadania mogą przez to wyjść jako `no_code`. Warto zerknąć na ostrzeżenia, zanim uzna się raport za wiarygodny.

Każdy rekord ma status:

| status | znaczenie |
| --- | --- |
| `ok` | zadanie jest i w kodzie (w dowolnym repo odcięcia), i oznaczone `Release: release-4.159.0` |
| `missing_release` | kod jest w odcięciu, ale zadanie nie ma ustawionego `Release` |
| `no_code` | zadanie ma ustawiony `Release`, ale nie ma commitów w żadnym repo odcięcia |
| `unknown_issue` | klucz z commita nie istnieje w YouTracku (literówka) |

Pole `repos` mówi, w których repozytoriach znaleziono kod, a `commits` to suma commitów ze wszystkich repozytoriów:

```
# gdzie szukać kodu zadań bez ustawionego Release
logintegra release verify 4.159.0 \
  --repo apollo-backend --repo apollo-frontend --repo microservice-courier --repo infokiosk \
  --previous release-4.158.0 \
  | jq -r 'select(.status == "missing_release") | [.key, (.repos | join(",")), .summary] | @tsv'
```

```
# tylko problemy
logintegra release verify 4.159.0 \
  --repo apollo --repo apollo-frontend --repo msc \
  --previous release-4.158.0 \
  | jq 'select(.status != "ok")'
```

Polecenie jest wyłącznie do odczytu i można je uruchamiać wielokrotnie.

Wynik można podać wprost do poprawki - to zastępuje ręczne wklejanie opisu PR do komentarza i ustawianie `Release` klikaniem:

```
logintegra release verify 4.159.0 \
  --repo apollo --repo apollo-frontend --repo msc \
  --previous release-4.158.0 --project A \
  | jq -r 'select(.status == "missing_release").key' \
  | logintegra youtrack set-release release-4.159.0 --dry-run
```

### Raport na Slacku

Wynik `release verify` to NDJSON, więc raport dla ludzi składa się filtrem jq [`contrib/slack-verify.jq`](<https://bitbucket.org/logintegraspzoo/logintegra-toolbox-cli/src/master/contrib/slack-verify.jq>) i wysyła przez `logintegra slack send`:

```
uv run logintegra release verify 4.163.0 \
    --repo apollo-backend --repo apollo-frontend \
    --repo microservice-courier --repo infokiosk \
    --workspace logintegraspzoo --previous release-4.162.0 \
  | jq -sr --arg version "4.163.0" -f contrib/slack-verify.jq \
  | uv run logintegra slack send 'apollo-cut'
```

Efekt:

```
*Weryfikacja wydania 4.163.0* – 42 ok, 4 problemy

:red_circle: *Nieznane zgłoszenia* (1)
• `A-18999` _bez tytułu_ _(infokiosk)_

:large_orange_circle: *Brak wersji w YouTrack* (2)
• `A-18301` Poprawka NPE w wyszukiwaniu przewoźnika _(apollo-backend, apollo-frontend)_
• `A-18302` Ponawianie wysyłki w kliencie SMTP _(microservice-courier)_

:large_blue_circle: *Brak kodu w cutcie* (1)
• `A-18310` Aktualizacja dokumentacji
```

Uwagi:

- `jq -s` scala rekordy w jedną tablicę (potrzebne do grupowania i zliczania), a `-r` wypisuje czysty tekst zamiast stringa JSON - tego oczekuje `slack send` na stdin.
- `--arg version` służy tylko do nagłówka; podaj tę samą wersję co w `verify`.
- Zadania `ok` są **zliczane, ale nie wypisywane** - to większość wydania i nic nie wnoszą do przeglądu. Gdy nie ma żadnych problemów, wiadomość to `:white_check_mark: Wszystko się zgadza.`, więc pipeline jest bezpieczny do uruchamiania cyklicznie.
- W nawiasie na końcu linii są repozytoria, w których znaleziono kod zadania - przy czterech repo to pierwsza rzecz, o którą pyta osoba poprawiająca. `no_code` nie ma kodu nigdzie, więc tam nawias się nie pojawia.
- Nie dokładaj tu `--strict`: kod wyjścia 1 przerwałby pipeline, zanim wiadomość trafi na Slacka.
- Kolejność statusów jest ta sama co w `STATUS_ORDER` (`release/reconcile.py`) - najpierw to, co wymaga człowieka.

## Output i pipowanie

CLI jest zaprojektowane wokół kompozycji w stylu Unix. Każde polecenie produkujące dane zapisuje **NDJSON** (newline-delimited JSON) na stdout.

Dzięki temu każde polecenie można wpiąć w inny program lub inne polecenie `logintegra`:

```
# Ładne wyświetlenie przez jq
logintegra youtrack issues "Sprint: wombaty-49" | jq .

# Wyciągnięcie konkretnego pola
logintegra youtrack issues "Sprint: wombaty-49" | jq -r '.idReadable'

# Filtrowanie w locie
logintegra youtrack issues "Sprint: wombaty-49" | jq 'select(.summary | test("login"))'

# Pipe do innego polecenia logintegra
logintegra youtrack issues "Sprint: wombaty-49" | logintegra slack notify channel-1
```

## TeamCity

Narzędzie dobrze nadaje się do kroków buildowych w TeamCity.

**Przykładowy krok - cut**

```
uv run logintegra workflows apollo cut %release.version% --sprint %sprint.name%
```

**Przykładowy krok - weryfikacja przed deployem:**

```
COUNT=$(uv run logintegra youtrack issues "Sprint: %sprint.name% #Unresolved" | jq -s 'length')
if [ "$COUNT" -gt 0 ]; then
  echo "##teamcity[buildProblem description='Są nierozwiązane issues: '"$COUNT"']"
  exit 1
fi
```

**Przykładowy krok - weryfikacja odcięcia (`--strict` przerywa build):**

```
uv run logintegra release verify %release.version% \
  --repo apollo --repo apollo-frontend --repo msc --previous release-%previous.version% --project A --strict
```

**Wymagania na agencie:** Python 3.14+ oraz [uv](<https://docs.astral.sh/uv/>) muszą być zainstalowane.

### Docker

Zamiast instalować Pythona i uv na agencie, można uruchamiać CLI z obrazu. Obraz zawiera też `jq` oraz filtr [`contrib/slack-verify.jq`](<https://bitbucket.org/logintegraspzoo/logintegra-toolbox-cli/src/master/contrib/slack-verify.jq>) (pod `/opt/logintegra/contrib`), więc całe pipeline'y z tego README działają w środku bez dokładania czegokolwiek.

```
docker build -t logintegra-toolbox:latest .
```

Obraz nie zawiera żadnej konfiguracji ani sekretów:

- **`config.toml`** montuje się do `/config` (obraz ustawia `LOGINTEGRA_CONFIG_DIR=/config`). Plik nie ma sekretów - są w nim tylko adresy URL, workspace i login.
- **Tokeny** przekazuje się zmiennymi środowiskowymi: `YOUTRACK_TOKEN`, `BITBUCKET_TOKEN`, `SLACK_TOKEN`. W TeamCity trzymaj je jako parametry typu `password`.

```
docker run --rm \
  -v /opt/teamcity/logintegra:/config:ro \
  -e YOUTRACK_TOKEN -e BITBUCKET_TOKEN -e SLACK_TOKEN \
  logintegra-toolbox:latest youtrack issues "Sprint: wombaty-49"
```

`ENTRYPOINT` to samo `logintegra`, więc argumenty podaje się wprost, bez powtarzania nazwy polecenia. Gdy potrzebny jest pełny pipeline z `jq`, uruchom powłokę:

```
docker run --rm -v /opt/teamcity/logintegra:/config:ro \
  -e BITBUCKET_TOKEN -e YOUTRACK_TOKEN -e SLACK_TOKEN \
  --entrypoint sh logintegra-toolbox:latest -c '
    logintegra release verify %release.version% \
        --repo apollo-backend --repo apollo-frontend \
        --repo microservice-courier --repo infokiosk \
        --workspace logintegraspzoo --previous release-%previous.version% \
      | jq -sr --arg version "%release.version%" -f /opt/logintegra/contrib/slack-verify.jq \
      | logintegra slack send apollo-cut'
```

W kroku **Docker** w TeamCity wystarczy podać obraz i argumenty - TeamCity sam montuje katalog roboczy i potrafi uruchomić kontener pod UID agenta. Obraz to obsługuje: konfiguracja jest szukana w `LOGINTEGRA_CONFIG_DIR`, a nie w `$HOME`, więc działa pod dowolnym użytkownikiem.

Sekcja `[slack]` (jak każda inna) jest opcjonalna - krok, który jej nie używa, nie potrzebuje jej w `config.toml` ani tokenu.

## Inne

### Formatowanie i linting

```
uv run ruff format .
uv run ruff check .
```

### Sprawdzanie typów

```
uv run mypy src
```

### Testy

```
uv run pytest
```

### Dodawanie zależności

Zależność produkcyjna:

```
uv add <nazwa-pakietu>
```

Zależność dev:

```
uv add --group dev <nazwa-pakietu>
```
