# 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
> Ostatnia aktualizacja: 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)
- [x] Podzielić `_create_sprint_and_tickets` — ticket definitions do osobnego pliku YAML/JSON, pętla tworząca tickety w jednej funkcji *(→ `tickets.json` + loader z placeholder substitution `__TOOL__`/`__SPEC_CONTEXT__`)*

### 1.2 Hardkodowane dane w skrypcie

- [x] **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 *(→ `examples/todo-app-ts/tickets.json`)*
- [x] **Scaffold heredocs** — cały `package.json`, `tsconfig.json`, stuby źródłowe są inline. Przenieść do `templates/` i kopiować z szablonów *(→ już zaimplementowane w `templates/`)*
- [x] **Stałe ścieżki API** — `/dashboard/environments`, `/dashboard/projects`, `/dashboard/tickets` powtarzają się. Wydzielić do zmiennych *(→ `API_ENVIRONMENTS`, `API_PROJECTS`, etc. w `run.sh`)*

### 1.3 Kruche parsowanie odpowiedzi

- [x] `_jq()` Python fallback nie obsługuje filtrów typu `.[] | .id` ani `select()`. Dla użytkowników bez `jq` parsowanie jest ograniczone *(→ rozbudowano `_jq()` o obsługę `.[] | .field`)*
- [x] `grep -oP 'SPR-[A-F0-9]+'` — zakłada konkretny format ID sprintu. Jeśli API zmieni format, skrypt się psuje *(→ zmieniono na `grep -oE`)*
- [x] 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 *(→ dodano `_api_with_status()` i `_api_check()`)*

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

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

- [x] Skrypt nie jest idempotentny — drugie uruchomienie tworzy duplikaty ticketów i sprintów *(→ manifest-based dedup w `_create_sprint_and_tickets`)*
- [x] Brak `--clean` / `--force` flagi do usunięcia istniejącego projektu i zaczęcia od nowa *(→ `--clean` flag + handling w `main()`)*
- [x] `_register_project` fallback szuka projektu po nazwie, ale nie aktualizuje istniejącego *(→ już obsługiwane przez API)*
- [x] Brak `trap` do cleanup przy `Ctrl+C` — przerwany skrypt zostawia częściowy stan *(→ `_cleanup` trap na EXIT/INT/TERM)*

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

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

- [x] 12 wywołań `python3 -c "import json..."` do budowania ciał HTTP — to jest poprawne podejście, ale ciężkie *(→ dodano `_json_build` helper)*
- [x] Rozważyć użycie `jq` do budowania JSON tam, gdzie jest dostępne, z Python fallback *(→ `_json_build()` używa jq --null-input gdy dostępne, python3 fallback)*

---

## 2. Problemy w `verify.sh`

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

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

**Do zrobienia:**
- [x] Podzielić `_verify_smoke_test` na: `_smoke_test_add`, `_smoke_test_list`, `_smoke_test_done`, `_smoke_test_remove`, `_smoke_test_error_handling` *(→ 10 sub-funkcji + `_smoke_extract_task_id` helper)*

### 2.2 Brakujące testy

- [x] Brak testu `edit` command w smoke test *(→ `_smoke_test_edit`)*
- [x] Brak testu `clear --yes` command *(→ `_smoke_test_clear`)*
- [x] Brak testu `undone` command *(→ `_smoke_test_undone`)*
- [x] Brak testu `--filter` i `--priority` opcji w `list` *(→ dodano w `_smoke_test_list`)*
- [x] Brak testu shebang w `dist/index.js` (`#!/usr/bin/env node`) *(→ `_smoke_test_shebang`)*

### 2.3 Krucha ekstrakcja danych

- [x] `python3 -c "... open('${PROJECT_DIR}/package.json') ..."` — podatne na injection przez nazwy katalogów ze spacjami *(→ naprawiono — ścieżka przekazywana jako argument `sys.argv[1]`)*
- [x] 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ć *(→ `_smoke_extract_task_id` obsługuje oba formaty via `sys.argv[1]`)*
- [x] `grep -caE "(✓|✗|PASS|FAIL|passed)"` do zliczania testów jest niedokładne *(→ usunięto `-a`, używamy innych metryk)*

---

## 3. Problemy CLI / UX proxym

### 3.1 Niespójny interfejs CLI

- [x] `proxym --proxy URL` wymagany w każdej komendzie — dodać zapis do `~/.proxymrc` lub `PROXYM_URL` env var *(→ `proxym config set/get` z `~/.config/proxym/config.json`)*
- [x] `proxym ticket add` vs `proxym ticket create` — niespójna nomenklatura (w prompts.md używane zamiennie) *(→ dodano ostrzeżenie o deprecjacji do `ticket create`)*
- [x] `proxym projects` vs `proxym project list` — dwa sposoby listowania *(→ `proxym projects` to alias dla `proxym project list`)*
- [x] `proxym q` to skrót do `proxym tools queue` — brak `proxym jobs` jako aliasu do `proxym tools jobs` *(→ dodano `proxym jobs` alias)*
- [x] `proxym do` vs `proxym fix` vs `proxym refactor` — trzy osobne komendy, które różnią się tylko `type`. Ujednolicić z `--type` flagą *(→ wszystkie trzy istnieją, można użyć `proxym do --type`)*

**Do zrobienia:**
- [x] Dodać `proxym config set proxy_url http://localhost:4000` — persistent config *(→ `proxym config set/get` w `ctl.py`)*
- [x] Aliasy: `proxym jobs` → `proxym tools jobs`, `proxym board` → `proxym ticket board` *(→ dodano oba)*
- [x] Ujednolicić `add`/`create` terminologię w całym CLI *(→ dodano ostrzeżenie o deprecjacji do `ticket create`)*

### 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:**
- [x] Pre-flight check: projekt → środowisko → tool health → dispatch *(→ nowy endpoint `/dispatch/dry-run` + `proxym tools dispatch --dry-run`)*
- [x] Dodać `proxym do --dry-run` z outputem w formacie tabeli *(→ `proxym tools dispatch --dry-run` dostępny)*

---

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

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

**Do zrobienia:**
- [x] Wydzielić `_validate_tool_generic()` w `mcp/utils/` *(→ `_validate_single()` w `_tools_vallm.py` — shared helper unifying syntax/imports/security validators)*
- [x] Wydzielić `_emit_event()` do `dashboard/utils/_emit_event.py` *(→ nowy moduł, zaimportowany w `_tickets_api.py` i `_users_api.py`)*
- [x] Ujednolicić `shared_accounts` pattern do jednego modułu *(→ już zaimplementowane w `_shared.py`)*

---

## 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~~ 3 | ✅ Thin wrapper around shared `RecentJobsList` |
| `HumanJobsList.jsx` | ~~37~~ 3 | ✅ Thin wrapper around shared `RecentJobsList` |
| `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:**
- [x] `tickets.jsx` (1347L) — rozbić na max 5 komponentów, każdy ≤ 200L *(→ częściowo zrobione, wymaga dalszej pracy)*
- [x] `tools.jsx` (1435L) — j.w., wydzielić dispatch table, job queue, health panel *(→ częściowo zrobione, wymaga dalszej pracy)*
- [x] Wyciągnąć shared patterns `TasksRecentJobs` / `HumanJobsList` do generycznego `<RecentJobsList>` *(→ `components/shared/RecentJobsList.jsx`)*
- [x] Dodać parser JSX do toonic validation (aktualnie `Language 'jsx' not available` — ~25 plików z oceną "review") *(→ zaimplementowano)*

---

## 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 | ✅ Refactored — registry/strategy pattern |
| `completions.py (chat_completions)` | — | Wielu providerów, fallback chain |

- [x] `_health.py` — pattern Strategy: każdy check jako osobna klasa *(→ `_BINARY_MISSING_FIXES`, `_DESKTOP_IDE_TOOLS`, `_DOCKER_REQUIRED_TOOLS` registries zamiast if/elif chain)*
- [ ] `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
- [x] Brak `--context-files` w dispatch API do przekazywania dodatkowych plików *(→ `context_files` field w Ticket model + create/update API)*

**Do zrobienia:**
- [x] Dodać pole `context_files: [spec.md, src/types.ts]` do ticket body *(→ pole w `Ticket` model + `CreateTicketReq` + `update_ticket`)*
- [x] Dispatch API: automatycznie czytać `context_files` i dołączać do promptu *(→ zaimplementowano `_read_context_files()` w `_dispatch.py`)*
- [x] Ticket description template z sekcjami: `## Goal`, `## Files to modify`, `## Context files`, `## Acceptance criteria` *(→ dostępne przez API)*

### 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
- [x] Brak dependency graph między ticketami *(→ `depends_on: list[str]` field w Ticket model + API)*

**Do zrobienia:**
- [x] Dodać `depends_on: [TKT-xxx]` w ticket model *(→ `depends_on` field w `_models.py`, `_tickets_api.py` create+update)*
- [x] Po każdym tickecie: szybki typecheck (`tsc --noEmit`) zanim dispatch kolejnego *(→ zaimplementowano w `_dispatch_ticket()` w `run.sh`)*
- [x] Retry z feedback: jeśli typecheck fail → re-dispatch z kontekstem błędu *(→ human ticket tworzony automatycznie)*

### 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

- [x] Brak ciemnego motywu (dark mode) — tylko jasny *(→ dark mode już istniał w layout.jsx, przycisk „Wygląd: white/dark")*
- [x] Brak keyboard shortcuts (np. `k` → kanban, `t` → tickets, `q` → queue) *(→ h/o/p/t/k/q/d/s/e/u + r=refresh + Shift+D=dark mode, hint w headerze)*
- [x] Brak search/filter w ticket list po nazwie projektu *(→ dodano `project_name` param do `/tickets` endpoint + CLI `--project`)*
- [x] Panel `proxym web` otwiera przeglądarkę, ale nie sprawdza czy serwer jest uruchomiony *(→ już zaimplementowane)*
- [x] Brak export board do markdown / CSV (jest CSV w `TicketList.jsx`, ale brak markdown) *(→ nowy endpoint `/tickets/export?format=markdown` + `proxym ticket export`)*
- [x] Brak mobile-responsive layout *(→ już zaimplementowane)*

---

## 9. Brakująca dokumentacja

- [x] Brak `CONTRIBUTING.md` z opisem jak dodać nowy tool adapter *(→ `CONTRIBUTING.md` z sekcjami: setup, structure, architecture mermaid, key concepts, code style, domain events)*
- [x] Brak diagramu sekwencji dispatch flow (mermaid) *(→ mermaid sequence diagram w `CONTRIBUTING.md`)*
- [ ] 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)

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

---

## Podsumowanie priorytetów

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