Files
herdrMario/docs/superpowers/plans/2026-11-19-all-slash-commands.md
2026-11-19 20:32:01 +01:00

150 lines
8.3 KiB
Markdown

# Wszystkie komendy w menu `/` — plan implementacji
**Cel:** po wpisaniu `/` composer pokazuje wszystkie komendy Claude Code, czyli:
- pełną listę wbudowanych,
- komendy i skille projektu,
- globalne komendy i skille użytkownika (`~/.claude`),
- komendy i skille włączonych pluginów.
Menu pokazuje wszystkie trafienia jako przewijaną listę.
**Zaakceptowane przez użytkownika (2026-11-19):**
- pełna statyczna lista wbudowanych;
- globalne `~/.claude/commands` i `~/.claude/skills`;
- pluginy włączone w `~/.claude/settings.json`, nazwy `plugin:nazwa`;
- menu przewijane, bez ucinania do 20;
- katalog globalny czytany raz i odświeżany w tle, nie przy każdym klawiszu.
## Ograniczenia globalne
- Nie zmieniamy Herdr ani jego plików. Pracujemy tylko na gałęzi `feature/composer-dock`. Bez push.
- Testowalna logika jest w `catalog.js` (czysty moduł; `exec` i odczyt pliku wstrzyknięte). GPUI jest tylko w `main.js`.
- Ścieżki w skryptach PowerShell przekazujemy wyłącznie przez `decode()` z `powershell.js` (Base64), jak w `readScript`.
- Błąd odczytu katalogu globalnego nie psuje menu. Wbudowane i projekt dalej się pokazują, a błąd idzie do `onReadError`.
- Opisy wbudowanych komend są po polsku.
## Fakty o środowisku (sprawdzone)
- `herdr` eksportuje:
- `home()`: katalog domowy;
- `readTextFile(path)`: UTF-8 do 1 MiB albo `null`, poza wątkiem UI, bez exec;
- `exec(cmd,args,{cwd,timeout})`.
- `~/.claude/settings.json` zawiera `enabledPlugins`, np. `{ "superpowers@claude-plugins-official": true, ... }`. Nazwa pluginu to część przed `@`.
- `~/.claude/plugins/installed_plugins.json` ma postać `{ "version": 2, "plugins": { "<id>": [ { "installPath": "C:\\...\\superpowers\\7.0.2", ... } ] } }`. Bierzemy pierwszy wpis z `installPath`.
- `<installPath>/.claude-plugin/plugin.json` może mieć pola `skills` i `commands`:
- tablica ścieżek względnych to katalogi skilli (każdy z `SKILL.md`) albo pliki `.md` komend;
- string to katalog do przejrzenia jak domyślny;
- brak pola oznacza domyślne `skills/*/SKILL.md` i `commands/*.md`.
- Przykład: mattpocock-skills ma `"skills": ["./skills/engineering/tdd", ...]`.
- Frontmatter `SKILL.md`:
- `name:` (gdy jest) wygrywa z nazwą katalogu;
- `description:` to opis;
- `user-invocable: false` znaczy: nie pokazywać w menu.
- Grupy w `suggest.js`: `GROUPS = [Wbudowane, Projekt, Użytkownik, Terminal]`. Dodajemy `GROUP_PLUGIN = "Pluginy"` po `Użytkownik`.
## Task 1 — katalog (`catalog.js`, `suggest.js`, testy)
**Interfejsy:**
- `BUILTINS["claude-code"]`: pełna lista (poniżej), alfabetycznie. Komentarz nad listą mówi, że lista jest ręczna i że przy nowej wersji Claude Code trzeba ją uzupełnić.
- `export const GROUP_PLUGIN = "Pluginy"` w `suggest.js`, dopisana do `GROUPS` po `GROUP_USER`.
- `export async function globalCommands(home, exec, readText, options = {})` zwraca `Promise<Item[]>`:
1. Odczytuje `settings.json` oraz `installed_plugins.json`, a dla każdego włączonego pluginu jego `plugin.json` (przez `readText`; brak pliku albo zły JSON to pusta lista z tego źródła, bez wyjątku).
2. Zbiera katalogi i pliki do przejrzenia:
- użytkownik: `~/.claude/commands/*.md`, `~/.claude/skills/*/SKILL.md`;
- pluginy według reguł `plugin.json` wyżej.
3. Jednym wywołaniem `exec` (PowerShell, a `sh` jako zapas, wzór `listProjectFiles`) wypisuje istniejące pliki. Wszystkie wzorce trafiają do skryptu przez Base64.
4. Każdy plik czyta przez `readText`. Pomija `user-invocable: false`.
5. Item:
- użytkownik: `{key, desc, group: GROUP_USER, insert: "/key "}`;
- plugin: `key = "<plugin>:<name>"`, `group: GROUP_PLUGIN`.
6. Błąd listowania to wyjątek, chyba że jest `options.onReadError`: wtedy go wywołuje i zwraca to, co się da.
- `commands(cwd, exec, options)` przyjmuje `options.global` (Item[], gotowe z cache). Kolejność: builtins, project, global, snippets. Duplikaty `key` usuwa: pierwszy wygrywa.
**Lista wbudowanych `claude-code`:** zostaw obecne 6 i dodaj resztę. `key`, potem polski opis:
- `add-dir`: Dodaje katalog roboczy.
- `agents`: Zarządza subagentami.
- `bashes`: Pokazuje zadania w tle.
- `bug`: Zgłasza błąd Claude Code.
- `clear`: Czyści historię rozmowy.
- `code-review`: Przegląd zmian pod kątem błędów.
- `compact`: Zwija historię do podsumowania.
- `config`: Otwiera ustawienia.
- `context`: Pokazuje zużycie kontekstu.
- `cost`: Pokazuje koszt i zużycie tokenów.
- `doctor`: Sprawdza instalację Claude Code.
- `exit`: Kończy sesję.
- `export`: Eksportuje rozmowę.
- `fast`: Przełącza tryb szybki.
- `feedback`: Wysyła opinię o Claude Code.
- `fewer-permission-prompts`: Dodaje bezpieczne komendy do listy dozwolonych.
- `help`: Pomoc.
- `hooks`: Zarządza hookami.
- `ide`: Łączy z IDE.
- `init`: Tworzy CLAUDE.md dla projektu.
- `install-github-app`: Instaluje aplikację GitHub.
- `keybindings`: Ustawia skróty klawiszowe.
- `login`: Logowanie.
- `logout`: Wylogowanie.
- `loop`: Uruchamia polecenie cyklicznie.
- `mcp`: Zarządza serwerami MCP.
- `memory`: Edytuje pliki pamięci.
- `model`: Wybiera model.
- `output-style`: Ustawia styl odpowiedzi.
- `permissions`: Ustawia uprawnienia narzędzi.
- `plugin`: Zarządza pluginami.
- `pr-comments`: Pokazuje komentarze PR.
- `privacy-settings`: Ustawienia prywatności.
- `release-notes`: Pokazuje informacje o wydaniu.
- `resume`: Wznawia wcześniejszą sesję.
- `review`: Przegląd pull requesta.
- `rewind`: Cofa rozmowę lub kod.
- `schedule`: Planuje zadania w chmurze.
- `security-review`: Przegląd bezpieczeństwa zmian.
- `simplify`: Upraszcza zmieniony kod.
- `status`: Pokazuje stan sesji.
- `statusline`: Ustawia linię statusu.
- `terminal-setup`: Konfiguruje terminal.
- `todos`: Pokazuje listę zadań.
- `upgrade`: Zmienia plan.
- `usage`: Pokazuje limity użycia.
- `vim`: Przełącza tryb vim.
- `workflows`: Pokazuje przebieg workflow.
**Testy** (`tests/catalog*.test.mjs` albo istniejący plik testów katalogu; fałszywe `exec` i `readText`):
- `GROUPS` zawiera `"Pluginy"` po `"Użytkownik"`.
- Builtiny `claude-code` zawierają co najmniej `context`, `help`, `mcp`, `rewind` i `clear`; klucze są unikalne.
- `globalCommands`:
- plugin włączony daje `superpowers:brainstorming`;
- plugin wyłączony (`false`) albo nieobecny w `enabledPlugins` nic nie daje;
- `plugin.json` z tablicą `skills` bierze tylko wymienione katalogi;
- `user-invocable: false` jest pominięty;
- `name:` z frontmattera wygrywa z nazwą katalogu;
- komenda użytkownika `~/.claude/commands/handoff.md` daje `handoff` w grupie `Użytkownik`;
- brak `settings.json` daje tylko pozycje użytkownika, bez wyjątku;
- błąd listowania z `onReadError` wywołuje handler i zwraca resztę.
- `commands` z `options.global` usuwa duplikat `key` (pierwszy wygrywa).
Commit: `feat: the / menu offers user, plugin and all built-in commands`.
## Task 2 — menu i cache (`main.js`)
- Cache katalogu globalnego:
- `this.globalCommands = null`, `this.globalLoadedAt = 0`, `this.globalLoading = false`;
- przy otwarciu menu `/`: brak cache albo cache starszy niż 60 s uruchamia `refreshGlobal(cx)` (jedno naraz, w tle);
- `loadSuggestions` używa tego, co już jest (`options.global: this.globalCommands ?? []`);
- po zakończeniu odświeżenia, gdy menu `/` jest otwarte, przelicz je (`loadSuggestions` dla bieżącego tokenu);
- w `checking()` nie odpalaj.
- Menu:
- usuń ucinanie do `MENU_LIMIT` i wiersz „…i jeszcze N”; renderuj wszystkie trafienia;
- `ScrollHandle.new()` z `gpui-kit` w `init()`, `.track_scroll(handle)` na `composer-menu-list`;
- przy zmianie `menu.index` (strzałki) wołaj `handle.scroll_to_item(index)` (licz z wierszem błędu/pustki, jeśli jest dzieckiem przed pozycjami);
- wysokość menu bez zmian.
- Nagłówki grup / kolejność: `merge(groupItems(...))` z nową grupą działa bez zmian (sprawdź).
Commit: `feat: the / menu scrolls through every match and caches the global catalog`.
## Review Focus
1. Brak `~/.claude/settings.json` albo `installed_plugins.json`, uszkodzony JSON: menu dalej działa.
2. Ścieżki ze spacjami i polskimi znakami (`D:\Development\workspace - Mariusz`) w listowaniu.
3. Szybkie pisanie po `/`: żadnego exec na każdy klawisz dla katalogu globalnego.
4. Strzałka w dół za widoczny obszar: zaznaczenie widoczne (scroll).
5. Plugin z `skills` jako tablicą (mattpocock-skills) i jako brak pola (superpowers).