# Proxym CLI — Przewodnik użytkowania

Kompletny przewodnik po zarządzaniu projektami, ticketami, narzędziami AI i observability
przez CLI `proxym`.

## Spis treści

- [Wymagania](#wymagania)
- [1. Uruchomienie serwera](#1-uruchomienie-serwera)
- [2. Projekty](#2-projekty)
- [3. Tickety i sprinty](#3-tickety-i-sprinty)
- [4. Zlecanie zadań narzędziom AI](#4-zlecanie-zadań-narzędziom-ai)
- [5. `proxym do` — jeden command do wszystkiego](#5-proxym-do--jeden-command-do-wszystkiego)
- [6. Observability](#6-observability)
- [7. Monitorowanie kolejki zadań](#7-monitorowanie-kolejki-zadań)
- [8. Scenariusze end-to-end](#8-scenariusze-end-to-end)
- [9. Testowanie przez Playwright (GUI)](#9-testowanie-przez-playwright-gui)
- [10. Weryfikacja przez CLI shell](#10-weryfikacja-przez-cli-shell)

---

## Wymagania

```bash
# Serwer musi działać w tle
proxym serve &

# Sprawdź status
proxym status
```

Domyślny adres: `http://localhost:4000`. Konfiguracja w `.env` lub `--proxy URL`.

### Persystencja danych

Wszystkie dane dashboardu (tickety, sprinty, projekty, konta, środowiska, użytkownicy) są zapisywane w jednym pliku SQLite:

```
~/.local/share/proxym/proxym.sqlite
```

W Dockerze ustaw `PROXYM_DATA_DIR=/app/data` aby dane trafiały na zamontowany wolumen `proxym-data`.

---

## 1. Uruchomienie serwera

```bash
# Standardowe uruchomienie
proxym serve

# Z hot-reloadem (development)
proxym serve --reload

# Niestandardowy port
proxym serve --port 8080

# Sprawdź że działa
proxym status
proxym providers
proxym models
```

---

## 2. Projekty

### 2.1 Skanowanie katalogu z projektami

Rejestruje wszystkie projekty z podanego katalogu (auto-detekcja stacku, git, itp.):

```bash
# Skanuj ~/github/wronai — znajdzie: proxy, clonebox, code2llm, toonic, stts, devix, heal, goal, clickmd, curllm...
proxym project scan /home/tom/github/wronai

# Wylistuj zarejestrowane projekty
proxym project list
proxym projects          # skrót
```

### 2.2 Dodawanie pojedynczych projektów

```bash
# Projekt lokalny
proxym project add /home/tom/github/wronai/proxy --name proxym --tool aider

# Projekt z git URL
proxym project add --git git@github.com:wronai/clonebox.git

# Projekt zdalny SSH
proxym project add --ssh tom@server:/opt/projects/myapp
```

### 2.3 Szczegóły i usuwanie

```bash
# Pokaż szczegóły projektu
proxym project show proxym

# Usuń projekt z rejestru
proxym project remove <project-id>
```

---

## 3. Tickety i sprinty

### 3.1 Tworzenie ticketów

```bash
# Szybkie tworzenie (preferowana forma)
proxym ticket add "zaktualizuj README.md" -p proxym

# Z przypisaniem narzędzia od razu
proxym ticket add "napraw endpoint /health" -p proxym -t aider --priority high --type bug

# Ticket na projekt z narzędziem claude-code
proxym ticket add "refaktoruj router/strategy.py" -p proxym -t claude-code --type refactor

# Ticket na dokumentację
proxym ticket add "wygeneruj API docs" -p code2llm --type docs

# Ticket na testy
proxym ticket add "dodaj testy dla MCP client" -p proxym --type test -t aider
```

### 3.2 Ticket dla konkretnego projektu (skrót)

```bash
# project task <nazwa-projektu> <opis>
proxym project task proxym "zaktualizuj CHANGELOG.md" --type docs
proxym project task clonebox "dodaj testy integracyjne" --type test -t aider
proxym project task stts "napraw crash w voice pipeline" --type bug
```

### 3.3 Zarządzanie ticketami

```bash
# Listuj tickety
proxym ticket list
proxym ticket list --status todo
proxym ticket list --tool aider
proxym ticket list --priority high

# Pokaż szczegóły
proxym ticket show <ticket-id>

# Aktualizuj status
proxym ticket update <ticket-id> --status in_progress
proxym ticket update <ticket-id> --status done

# Przypisz narzędzie do ticketu
proxym ticket assign <ticket-id> --tool claude-code --mode architect

# Dodaj komentarz
proxym ticket comment <ticket-id> --content "Fix wdrożony, testy przechodzą"

# Kanban board
proxym ticket board
```

### 3.4 Sprinty

```bash
# Utwórz sprint
proxym sprint create --name "Sprint 9 — Observability" --goal "Wdrożyć monitoring i self-healing"

# Listuj sprinty
proxym sprint list

# Szczegóły sprintu
proxym sprint show <sprint-id>

# Zmień status
proxym sprint update <sprint-id> --status active

# Board filtrowany po sprincie
proxym sprint board --sprint <sprint-id>
```

---

## 4. Zlecanie zadań narzędziom AI

### 4.1 Dostępne narzędzia

```bash
# Pokaż zarejestrowane narzędzia
proxym tools list

# Tylko te, które są dostępne na PATH
proxym tools list --available

# Szczegóły narzędzia
proxym tools show aider
```

### 4.2 Ręczny dispatch

```bash
# Wyślij ticket do narzędzia
proxym tools dispatch --ticket <ticket-id> --tool aider

# Z konkretnym trybem i modelem
proxym tools dispatch --ticket <ticket-id> --tool claude-code --mode architect --model balanced
```

### 4.3 Kolejka zadań

```bash
# Status kolejki
proxym tools queue
proxym q                  # skrót

# Lista jobów
proxym tools jobs
proxym tools jobs --status running

# Szczegóły joba
proxym tools job <job-id>

# Anuluj job
proxym tools cancel <job-id>

# Start/stop executora
proxym tools start
proxym tools stop
```

---

## 5. `proxym do` — jeden command do wszystkiego

`proxym do` automatycznie: rozpoznaje typ zadania → dobiera narzędzie → tworzy ticket
→ dispatchuje → śledzi wynik.

### 5.1 Podstawowe użycie

```bash
# Najprostsze — auto-detect projektu, narzędzia, priorytetu
proxym do "napraw crash w endpoincie /health"

# Wskaż projekt
proxym do "zaktualizuj dokumentację API" --on proxym

# Wskaż narzędzie
proxym do "refaktoruj panel.jsx" --on proxym --with claude-code

# Dry-run: pokaż co by się stało
proxym do "dodaj testy dla observability" --dry-run
```

### 5.2 Skróty

```bash
# fix = proxym do "..." --type bug
proxym fix "crash w /health" --on proxym

# refactor = proxym do "..." --type refactor --with claude-code
proxym refactor "wydziel pipeline z completions.py" --on proxym
```

### 5.3 Tryby pracy

```bash
# Utwórz ticket, ale nie uruchamiaj narzędzia
proxym do "nowy feature X" --no-run

# Uruchom, ale nie czekaj na wynik
proxym do "napraw Y" --no-wait

# Z priorytetem i typem
proxym do "security audit middleware" --type refactor --priority critical --on proxym
```

---

## 6. Observability

### 6.1 Logi

```bash
# Ostatnie logi z ring buffera
proxym obs logs
proxym obs logs -n 100
proxym obs logs --level error

# Skrót
proxym log
proxym log -n 50
```

### 6.2 Błędy

```bash
# Podsumowanie błędów
proxym obs errors
```

### 6.3 Health

```bash
# Podsumowanie zdrowia systemu
proxym obs health
```

### 6.4 Self-healing (repair agent)

```bash
# Diagnoza na podstawie tekstu błędu
proxym obs repair --error "ImportError: cannot import name X from Y"

# Auto-diagnoza z ostatnich logów
proxym obs repair --from-logs

# Tryb apply — LLM zaaplikuje patch
proxym obs repair --error "..." --mode apply
```

---

## 7. Monitorowanie kolejki zadań

```bash
# Szybki podgląd kolejki
proxym q

# Pełny status
proxym tools queue

# Filtruj joby po statusie
proxym tools jobs --status done
proxym tools jobs --status failed

# Logi serwera
proxym logs -n 30
proxym logs --level error
```

---

## 8. Scenariusze end-to-end

### Scenariusz A: Aktualizacja dokumentacji wielu projektów

```bash
# 1. Zarejestruj projekty
proxym project scan /home/tom/github/wronai

# 2. Utwórz sprint
proxym sprint create --name "Docs Sprint" --goal "Aktualizacja README we wszystkich projektach"

# 3. Utwórz tickety na dokumentację
proxym project task proxym "zaktualizuj README — dodaj sekcję observability" --type docs
proxym project task clonebox "zaktualizuj README — dodaj przykłady CLI" --type docs
proxym project task code2llm "zaktualizuj README — popraw instrukcję instalacji" --type docs
proxym project task stts "zaktualizuj README — dodaj sekcję voice pipeline" --type docs
proxym project task toonic "zaktualizuj README — dodaj przykłady TOON format" --type docs
proxym project task devix "zaktualizuj README — dodaj diagram architektury" --type docs

# 4. Sprawdź board
proxym ticket list --status todo

# 5. Zlecaj kolejno agentom
proxym do "zaktualizuj README — dodaj sekcję observability" --on proxym --with aider
proxym do "zaktualizuj README — dodaj przykłady CLI" --on clonebox --with aider --no-wait

# 6. Monitoruj
proxym q
proxym tools jobs --status running
```

### Scenariusz B: Bug fixing pipeline

```bash
# 1. Zgłoś buga
proxym fix "endpoint /v1/chat/completions zwraca 500 dla pustych messages" --on proxym

# 2. Sprawdź co się dzieje
proxym q
proxym ticket list --status in_progress

# 3. Po zakończeniu — sprawdź wynik
proxym tools jobs --status done
proxym ticket list --status done

# 4. Obserwuj logi
proxym obs errors
proxym obs health
```

### Scenariusz C: Refactoring z claude-code

```bash
# 1. Zlecenie refaktoryzacji
proxym refactor "wydziel _try_providers i _format_response z completions.py" --on proxym

# 2. Monitorowanie
proxym q
proxym obs logs --level info

# 3. Diagnostyka jeśli coś poszło nie tak
proxym obs errors
proxym obs repair --from-logs
```

### Scenariusz D: Multi-tool workflow na wielu projektach

```bash
# Skanuj projekty
proxym project scan /home/tom/github/wronai

# Zlecaj zadania na różne projekty z różnymi narzędziami
proxym do "dodaj CI/CD pipeline" --on heal --with claude-code --no-wait
proxym do "napraw broken imports" --on clickmd --with aider --no-wait
proxym do "dodaj testy jednostkowe" --on curllm --with aider --no-wait
proxym do "refaktoruj main.py" --on goal --with claude-code --no-wait

# Monitoruj wszystko
proxym q
proxym ticket board
proxym obs health
```

---

## 9. Testowanie przez Playwright (GUI)

Dashboard jest dostępny pod `http://localhost:4000/dashboard-ui`.
Testy GUI znajdują się w `tests/gui/`.

```bash
# Uruchom testy GUI (FastAPI TestClient — bez Playwright)
.venv/bin/python -m pytest tests/gui/ -v

# Testy z Playwright (jeśli zainstalowany)
.venv/bin/python -m pytest tests/e2e/ -v

# Otwórz dashboard w przeglądarce
proxym web
proxym web projects
proxym web tasks
```

**Co można testować w GUI:**
- `/dashboard-ui` — główny panel
- `/dashboard-ui#projects` — lista projektów
- `/dashboard-ui#tasks` — kanban board
- `/observability/health-summary` — JSON health endpoint
- `/observability/errors` — JSON errors endpoint
- `/observability/logs` — JSON logs endpoint

---

## 10. Weryfikacja przez CLI shell

Pełny test end-to-end z poziomu terminala:

```bash
#!/bin/bash
# Minimalna weryfikacja CLI — uruchom z katalogu proxy
set -e

echo "=== 1. Status serwera ==="
proxym status

echo "=== 2. Skanowanie projektów ==="
proxym project scan /home/tom/github/wronai

echo "=== 3. Lista projektów ==="
proxym project list

echo "=== 4. Tworzenie ticketu ==="
proxym ticket add "testowy ticket — weryfikacja CLI" -p proxym --type task

echo "=== 5. Lista ticketów ==="
proxym ticket list

echo "=== 6. Board ==="
proxym ticket board

echo "=== 7. Observability ==="
proxym obs errors
proxym obs health
proxym obs logs -n 5

echo "=== 8. Kolejka ==="
proxym q

echo "=== 9. Dry-run zlecenia ==="
proxym do "testowe zadanie" --on proxym --dry-run

echo "=== DONE ==="
```

Lub użyj gotowego skryptu: `scripts/evaluate_llm_work.sh`

---

## Szybka ściągawka

| Zadanie | Komenda |
|---|---|
| Start serwera | `proxym serve` |
| Status | `proxym status` |
| Skanuj projekty | `proxym project scan ~/github/wronai` |
| Lista projektów | `proxym projects` |
| Nowy ticket | `proxym ticket add "opis" -p projekt` |
| Zlecenie AI | `proxym do "opis" --on projekt` |
| Fix buga | `proxym fix "opis" --on projekt` |
| Refactoring | `proxym refactor "opis" --on projekt` |
| Kolejka | `proxym q` |
| Logi | `proxym log` |
| Błędy | `proxym obs errors` |
| Health | `proxym obs health` |
| Repair | `proxym obs repair --from-logs` |
| Dashboard | `proxym web` |
