# TODO — Proxym: Audit & Improvement Plan

> Wygenerowano na podstawie analizy `run.sh`, `verify.sh`, `prompts.md`,
> danych TOON (validation, analysis, duplication, flow, map) oraz kodu źródłowego.
>
> Data: 2026-03-24

---

## 1. Problemy w `run.sh` (examples/todo-app-ts)

### 1.1 Złożoność cyklomatyczna i długość funkcji

| Funkcja | CC | Linie | Limit |
|---|---|---|---|
| `_create_project_scaffold` | 17 | 205 | CC ≤ 15, L ≤ 100 |
| `_verify_project` | 19 | 104 | CC ≤ 15, L ≤ 100 |
| `_create_sprint_and_tickets` | — | 129 | L ≤ 100 |

**Do zrobienia:**
- [ ] Wydzielić `_create_project_scaffold` na mniejsze funkcje: `_write_package_json`, `_write_tsconfig`, `_write_source_stubs`, `_write_test_stubs`, `_init_git`
- [ ] Wydzielić `_verify_project` na: `_verify_npm_install`, `_verify_typecheck`, `_verify_build`, `_verify_tests`, `_verify_smoke` (wzorem verify.sh, który robi to poprawnie)
- [ ] Podzielić `_create_sprint_and_tickets` — ticket definitions do osobnego pliku YAML/JSON, pętla tworząca tickety w jednej funkcji

### 1.2 Hardkodowane dane w skrypcie

- [ ] **Ticket definitions inline** — 7 bloków `_create_ticket` z wieloliniowymi opisami są zahardkodowane w bashu. Przenieść do `tickets.yaml` lub `tickets.json` i iterować w pętli
- [ ] **Scaffold heredocs** — cały `package.json`, `tsconfig.json`, stuby źródłowe są inline. Przenieść do `templates/` i kopiować z szablonów
- [ ] **Stałe ścieżki API** — `/dashboard/environments`, `/dashboard/projects`, `/dashboard/tickets` powtarzają się. Wydzielić do zmiennych

### 1.3 Kruche parsowanie odpowiedzi

- [ ] `_jq()` Python fallback nie obsługuje filtrów typu `.[] | .id` ani `select()`. Dla użytkowników bez `jq` parsowanie jest ograniczone
- [ ] `grep -oP 'SPR-[A-F0-9]+'` — zakłada konkretny format ID sprintu. Jeśli API zmieni format, skrypt się psuje
- [ ] Brak weryfikacji HTTP status code przy `_api()` (używa `-sf`, ale nie loguje statusu). Przy 4xx/5xx od API, zmienna jest pusta i skrypt kontynuuje

**Do zrobienia:**
- [ ] Dodać `_api_with_status()` która zwraca zarówno body jak i kod HTTP
- [ ] Ujednolicić parsowanie ID — używać `_jq .id` zamiast `grep -oP`
- [ ] Dodać walidację odpowiedzi API po każdym kroku (czy zawiera wymagane pola)

### 1.4 Obsługa błędów i idempotentność

- [ ] Skrypt nie jest idempotentny — drugie uruchomienie tworzy duplikaty ticketów i sprintów
- [ ] Brak `--clean` / `--force` flagi do usunięcia istniejącego projektu i zaczęcia od nowa
- [ ] `_register_project` fallback szuka projektu po nazwie, ale nie aktualizuje istniejącego
- [ ] Brak `trap` do cleanup przy `Ctrl+C` — przerwany skrypt zostawia częściowy stan

**Do zrobienia:**
- [ ] Dodać `--clean` flagę (usuwa katalog i dane z proxym)
- [ ] Sprawdzić czy sprint/tickety istnieją przed tworzeniem (dedup)
- [ ] Dodać `trap` do graceful shutdown z logowaniem stanu

### 1.5 Zależność od Python3 do budowania JSON

- [ ] 12 wywołań `python3 -c "import json..."` do budowania ciał HTTP — to jest poprawne podejście, ale ciężkie
- [ ] Rozważyć użycie `jq` do budowania JSON tam, gdzie jest dostępne, z Python fallback

---

## 2. Problemy w `verify.sh`

### 2.1 Złożoność cyklomatyczna

| Funkcja | CC | Limit |
|---|---|---|
| `_verify_smoke_test` | 27 | CC ≤ 15 |

**Do zrobienia:**
- [ ] Podzielić `_verify_smoke_test` na: `_smoke_test_add`, `_smoke_test_list`, `_smoke_test_done`, `_smoke_test_remove`, `_smoke_test_error_handling`

### 2.2 Brakujące testy

- [ ] Brak testu `edit` command w smoke test
- [ ] Brak testu `clear --yes` command
- [ ] Brak testu `undone` command
- [ ] Brak testu `--filter` i `--priority` opcji w `list`
- [ ] Brak testu shebang w `dist/index.js` (`#!/usr/bin/env node`)

### 2.3 Krucha ekstrakcja danych

- [ ] `python3 -c "... open('${PROJECT_DIR}/package.json') ..."` — podatne na injection przez nazwy katalogów ze spacjami
- [ ] Ekstrakcja `task_id` z pliku JSON bezpośrednio (zakłada strukturę `[{id: ...}]` lub `{todos: [{id: ...}]}`). Niespójna z formatem, który `store.ts` może wygenerować
- [ ] `grep -caE "(✓|✗|PASS|FAIL|passed)"` do zliczania testów jest niedokładne

---

## 3. Problemy CLI / UX proxym

### 3.1 Niespójny interfejs CLI

- [ ] `proxym --proxy URL` wymagany w każdej komendzie — dodać zapis do `~/.proxymrc` lub `PROXYM_URL` env var (już częściowo jest, ale skrypt zawsze wymaga `--proxy`)
- [ ] `proxym ticket add` vs `proxym ticket create` — niespójna nomenklatura (w prompts.md używane zamiennie)
- [ ] `proxym projects` vs `proxym project list` — dwa sposoby listowania
- [ ] `proxym q` to skrót do `proxym tools queue` — brak `proxym jobs` jako aliasu do `proxym tools jobs`
- [ ] `proxym do` vs `proxym fix` vs `proxym refactor` — trzy osobne komendy, które różnią się tylko `type`. Ujednolicić z `--type` flagą

**Do zrobienia:**
- [ ] Dodać `proxym config set proxy_url http://localhost:4000` — persistent config
- [ ] Aliasy: `proxym jobs` → `proxym tools jobs`, `proxym board` → `proxym ticket board`
- [ ] Ujednolicić `add`/`create` terminologię w całym CLI

### 3.2 Brak feedback loop w web CLI (dashboard)

- [ ] Dashboard (`/dashboard-ui`) nie pokazuje live output z narzędzi AI (aider, claude-code)
- [ ] SSE stream (`_events_sse.py`) istnieje, ale brak integracji z job execution progress
- [ ] Brak progress bar / live log w konsoli webowej podczas dispatch
- [ ] Brak websocket do real-time log streaming z narzędzia

**Do zrobienia:**
- [ ] Dodać SSE/WebSocket endpoint `/dashboard/tools/jobs/{id}/stream` z live output
- [ ] Dashboard: komponent `<JobLiveLog>` pokazujący stdout/stderr w real-time
- [ ] CLI: `proxym tools follow <job-id>` — tail live output

### 3.3 Brak walidacji przed dispatch

- [ ] `proxym do "opis" --on projekt` nie sprawdza czy projekt istnieje zanim wyśle
- [ ] Brak walidacji czy wybrany tool jest zainstalowany i zdrowy przed dispatch
- [ ] Brak `--dry-run` w `proxym do` z pełnym planem (tool, model, project_dir, ticket preview)

**Do zrobienia:**
- [ ] Pre-flight check: projekt → środowisko → tool health → dispatch
- [ ] Dodać `proxym do --dry-run` z outputem w formacie tabeli

---

## 4. Duplikacje kodu (z duplication.toon)

| Priorytet | Gdzie | Co | Oszczędność |
|---|---|---|---|
| 1 | `mcp/_tools_vallm.py` | `tool_validate_syntax` / `tool_validate_imports` — identyczna struktura 22L | 22 linii |
| 2 | `cli/utils/cmd_sessions_list.py` | `cmd_sessions_list` / `cmd_mcp_servers` — identyczna struktura 10L | 10 linii |
| 3 | `dashboard/_users_api.py` + `_tickets_api.py` | `_emit_event` — identyczna implementacja 7L | 7 linii |
| 4 | `dashboard/_shared.py` + `domain/setup.py` | `shared_accounts` / `get_event_store` — identyczna 6L | 6 linii |

**Do zrobienia:**
- [ ] Wydzielić `_validate_tool_generic()` w `mcp/utils/`
- [ ] Wydzielić `_emit_event()` do `dashboard/utils/_emit_event.py`
- [ ] Ujednolicić `shared_accounts` pattern do jednego modułu

---

## 5. Wysoka złożoność komponentów Dashboard (JSX)

| Komponent | CC | Problem |
|---|---|---|
| `tickets.jsx` (główny) | 89 | Monolityczny, 1347 linii |
| `tools.jsx` (główny) | 73 | Monolityczny, 1435 linii |
| `ToolsJobQueue.jsx` | 48 | Zbyt dużo logiki w jednym komponencie |
| `TasksPanelRefactored.jsx` | 45 | "Refactored" ale nadal za złożony |
| `TasksRecentJobs.jsx` | 37 | Zbyt dużo warunków |
| `HumanJobsList.jsx` | 37 | Identyczny pattern jak `TasksRecentJobs` |
| `logs.jsx` | 34 | Brak wydzielenia |
| `TicketsPanelRefactored.jsx` | 31 | Nadal powyżej limitu |
| `ToolHealthPanelRefactored.jsx` | 31 | j.w. |
| `DiagConfig.jsx` | 29 | Konfiguracja inline |
| `EditableTicketTable.jsx` | 29 | Zbyt dużo inline logic |

**Do zrobienia:**
- [ ] `tickets.jsx` (1347L) — rozbić na max 5 komponentów, każdy ≤ 200L
- [ ] `tools.jsx` (1435L) — j.w., wydzielić dispatch table, job queue, health panel
- [ ] Wyciągnąć shared patterns `TasksRecentJobs` / `HumanJobsList` do generycznego `<RecentJobsList>`
- [ ] Dodać parser JSX do toonic validation (aktualnie `Language 'jsx' not available` — ~25 plików z oceną "review")

---

## 6. Problemy architektoniczne (z flow.toon i analysis.toon)

### 6.1 Mutacje w pipeline'ach

Pipeline `update_ticket → _maybe_auto_dispatch_ticket → _enqueue_ticket_job` zawiera mutujące kroki (`_get_registry`, `_seed_workspace_project`, `get_settings`). Utrudnia testowanie i powoduje side-effecty.

- [ ] Wydzielić `_get_registry()` jako singleton z explicit initialization (zamiast lazy global mutation)
- [ ] `_seed_workspace_project` powinien być wywołany raz przy starcie, nie w pipeline
- [ ] `get_settings()` — lazy singleton OK, ale oznaczyć jako pure w flow (nie mutuje stanu business)

### 6.2 Fan-out hotspoty

| Funkcja | Fan-out | Problem |
|---|---|---|
| `run_all_tests` | 28 | Zbyt dużo zależności |
| `chat_completions` | 27 | God-function |
| `QuickTaskCreator` | 27 | UI god-component |
| `ToolHealthPanel` | 26 | UI god-component |
| `dispatch_job` | 23 | Zbyt dużo odpowiedzialności |

- [ ] `chat_completions` — wydzielić `_resolve_and_route()`, `_execute_completion()`, `_format_and_return()`
- [ ] `dispatch_job` — wydzielić pre-validation, queueing, execution do osobnych modułów

### 6.3 Wysokie CC w backendzie Python

| Moduł | CC | Problem |
|---|---|---|
| `startup.py` | 18 | Za dużo warunków startu |
| `_diag_providers.py` | 19 | Każdy provider to osobny if |
| `_health.py` | 28 | Monolityczny health check |
| `completions.py (chat_completions)` | — | Wielu providerów, fallback chain |

- [ ] `_health.py` — pattern Strategy: każdy check jako osobna klasa (częściowo zrobione w `HealthCheckerRefactored`, dokończyć)
- [ ] `startup.py` — wydzielić initialization steps do osobnych funkcji z dependency injection

---

## 7. Transparentność generowania kodu

### 7.1 Brak kontekstu dla narzędzi AI

- [ ] Ticket descriptions w `run.sh` nie zawierają **pełnego kontekstu pliku** — AI tool dostaje opis, ale nie widzi istniejącego kodu stubs
- [ ] Brak mechanizmu automatycznego dołączania `spec.md` do kontekstu narzędzia
- [ ] Brak `--context-files` w dispatch API do przekazywania dodatkowych plików

**Do zrobienia:**
- [ ] Dodać pole `context_files: [spec.md, src/types.ts]` do ticket body
- [ ] Dispatch API: automatycznie czytać `context_files` i dołączać do promptu
- [ ] Ticket description template z sekcjami: `## Goal`, `## Files to modify`, `## Context files`, `## Acceptance criteria`

### 7.2 Brak weryfikacji po każdym tickecie

- [ ] `run.sh` dispatchuje wszystkie tickety sekwencyjnie, ale nie weryfikuje wyników pośrednich
- [ ] Ticket 3 (commands.ts) zależy od Ticket 1 (store.ts) — jeśli store jest źle wygenerowany, commands też będzie zły
- [ ] Brak dependency graph między ticketami

**Do zrobienia:**
- [ ] Dodać `depends_on: [TKT-xxx]` w ticket model
- [ ] Po każdym tickecie: szybki typecheck (`tsc --noEmit`) zanim dispatch kolejnego
- [ ] Retry z feedback: jeśli typecheck fail → re-dispatch z kontekstem błędu

### 7.3 Brak diff review

- [ ] Po zakończeniu joba, brak automatycznego `git diff` z podglądem zmian
- [ ] Dashboard nie pokazuje co konkretnie AI zmieniło w plikach
- [ ] Brak mechanizmu accept/reject zmian przed merge

**Do zrobienia:**
- [ ] Po job done: automatyczny `git add -A && git diff --cached` → zapisać w job result
- [ ] Dashboard: `<DiffViewer>` komponent z kolorowym diff
- [ ] CLI: `proxym tools diff <job-id>` — pokaż co AI zmieniło

---

## 8. Usprawnienia Web Dashboard

- [ ] Brak ciemnego motywu (dark mode) — tylko jasny
- [ ] Brak keyboard shortcuts (np. `k` → kanban, `t` → tickets, `q` → queue)
- [ ] Brak search/filter w ticket list po nazwie projektu
- [ ] Panel `proxym web` otwiera przeglądarkę, ale nie sprawdza czy serwer jest uruchomiony
- [ ] Brak export board do markdown / CSV (jest CSV w `TicketList.jsx`, ale brak markdown)
- [ ] Brak mobile-responsive layout

---

## 9. Brakująca dokumentacja

- [ ] Brak `CONTRIBUTING.md` z opisem jak dodać nowy tool adapter
- [ ] Brak diagramu sekwencji dispatch flow (mermaid)
- [ ] Brak dokumentacji API endpointów `/dashboard/*` (OpenAPI/Swagger?)
- [ ] `docs/CLI_USAGE.md` i `docs/API.md` istnieją, ale mogą być nieaktualne
- [ ] Brak przykładu end-to-end dla `claude-code` tool (run.sh domyślnie używa `aider`)

---

## 10. Quick wins (łatwe do naprawienia)

- [ ] `verify.sh` linia 79: `grep -qaE` — `-a` jest niepotrzebne na non-binary files
- [ ] `run.sh`: `SPRINT_ID=$(echo "$sprint_resp" | grep -oP ...)` — `-P` (PCRE) niedostępne na macOS. Użyć `grep -oE` z POSIX regex
- [ ] `run.sh`: `date -Iseconds` — nie działa na macOS (BSD date). Dodać fallback: `date -u +"%Y-%m-%dT%H:%M:%S%z"`
- [ ] Brak `shellcheck` w CI — oba skrypty mają potencjalne problemy z quoting
- [ ] Brak `set -o errexit` w verify.sh (celowe `set +e`, ale brak komentarza wyjaśniającego dlaczego)
- [ ] `_check_file` w verify.sh: próg 50 bajtów na "nie-stub" jest za niski — plik z samym importem to ~80 bajtów

---

## Podsumowanie priorytetów

| Priorytet | Obszar | Wpływ |
|---|---|---|
| **P0 — Krytyczne** | Idempotentność `run.sh`, brak pre-flight validation w dispatch | Blokuje niezawodne użycie |
| **P1 — Wysokie** | Kontekst dla AI tools, dependency graph ticketów, live job output | Kluczowe dla skuteczności generowania kodu |
| **P2 — Średnie** | Duplikacje kodu, refaktor dashboard JSX, CLI aliases | Utrzymanie i DX |
| **P3 — Niskie** | Portability (macOS), dark mode, keyboard shortcuts, docs | Quality of life |