Files
herdrMario/docs/superpowers/plans/2026-11-20-agent-profiles.md
2026-11-20 08:49:14 +01:00

185 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Profile agentów dla menu `/` — plan implementacji
> **Dla wykonawcy (Ovis Fast):** zadania wykonuj po kolei, każde osobnym commitem. Kroki mają checkboxy (`- [ ]`).
**Cel:** menu `/` podpowiada komendy dowolnego agenta. Wiedza o agencie pochodzi z profilu: domyślnego w kodzie albo z pliku `composer-agents.json` użytkownika. Do tego dochodzą komendy wysłane wcześniej do tego agenta, wzięte z historii.
**Architektura:**
- Nowy czysty moduł `profiles.js`: domyślne profile, parsowanie i walidacja pliku, wybór profilu dla `agentName`.
- `catalog.js` przestaje znać Claude Code: czyta źródła, które daje profil, a komendy z historii buduje osobną funkcją.
- `main.js` w tle trzyma plik profili i cache źródeł `home` per `id` profilu, a pod pozycjami menu pokazuje wiersze informacyjne.
**Stack:** JS (ESM), GPUI z `gpui-kit`, testy `node --test` (`npm test`).
**Spec:** `docs/superpowers/specs/2026-11-20-agent-profiles-design.md`. Przeczytaj cały plik przed startem.
## Ograniczenia globalne
- Nie zmieniamy Herdr ani jego plików. Pracujemy tylko na gałęzi `feature/composer-dock`. Bez push.
- Logika testowalna siedzi w czystych modułach (`profiles.js`, `catalog.js`; `exec` i `readText` wstrzyknięte). GPUI jest tylko w `main.js`.
- Ścieżki do skryptów PowerShell trafiają wyłącznie przez `decode()` z `powershell.js` (Base64).
- Menu `/` dla Claude Code (bez historii) daje **identyczną** listę jak przed zmianą: te same `key`, `group`, `insert`, `desc` i kolejność.
- Plik: `[appHome(), "composer-agents.json"].join("\\")`. Brak pliku jest normalny i nie jest błędem.
- TTL odświeżania pliku i źródeł `home`: 60 s (obecne `GLOBAL_TTL_MS`).
- Teksty dla użytkownika dosłownie:
- `GROUP_HISTORY = "Z historii"`;
- nieznany agent: ``Nieznany agent `<nazwa>` – dodaj profil w ~/.config/herdr-app/composer-agents.json`` (gdzie `<nazwa>` to `agentName`);
- problem z plikiem: `` `composer-agents.json`: <powód> ``.
## Review Focus
1. `agentName` w innej wielkości liter niż `match` (np. `Kiro-CLI`): profil ma pasować. Test w Task 1.
2. Plik z BOM, CRLF albo komentarzem-śmieciem: BOM jest usuwany, zły JSON daje domyślne profile i powód. Test w Task 1.
3. Wpis historii zaczynający się ścieżką (`/c/Users/x`), samym `/` albo `/ cos` nie jest komendą. Test w Task 2.
4. Dwa panele z różnymi agentami: menu codex nie pokazuje komend `~/.claude`, bo cache jest per `id`. Test cache w Task 3 (czysta funkcja).
5. Profil z pliku nadpisujący `claude-code` bez `claude-plugins` nie pokazuje pluginów, a ścieżka `..` lub bezwzględna jest odrzucana. Test w Task 1.
---
### Task 1: `profiles.js`, czyli domyślne profile, parsowanie i wybór
**Pliki:**
- Utwórz: `herdr/herdr-composer/mods/herdr-composer/profiles.js`
- Zmień: `herdr/herdr-composer/mods/herdr-composer/catalog.js` (przenieś `BUILTINS` i `AGENT_ALIASES` do `profiles.js`, w `catalog.js` zostaw `export { BUILTINS } from "./profiles.js"`)
- Test: `tests/profiles.test.mjs`
**Interfejsy (produkuje):**
- Typy (JSDoc):
- `Source = {scope:"project"|"home", path:string, pattern:"*.md"|"*/SKILL.md", prefix:string}`, albo `{scope:"home", kind:"claude-plugins"}`;
- `Profile = {id:string, match:string[], builtins:{key:string, desc:string}[], sources:Source[]}` (wszystko znormalizowane: `desc` domyślnie `""`, `prefix` domyślnie `"/"`).
- `export const PROFILES_FILE = "composer-agents.json"`
- `export const BUILTINS`: bez zmian treści.
- `export const DEFAULT_PROFILES: Profile[]`:
- `claude-code`: `match ["claude-code","claude"]`, builtins = `BUILTINS["claude-code"]`, sources w tej kolejności:
1. project `.claude/commands` `*.md`;
2. project `.claude/skills` `*/SKILL.md`;
3. home `.claude/commands` `*.md`;
4. home `.claude/skills` `*/SKILL.md`;
5. `{scope:"home", kind:"claude-plugins"}`.
- `codex`: `match ["codex"]`, builtins = `BUILTINS.codex`, `sources []`.
- `export function parseProfiles(text: string|null|undefined): {profiles: Profile[], problem: string|null}`
- `null`/`undefined` (brak pliku) daje `{profiles: [], problem: null}`.
- Usuwa BOM. Zły JSON daje `{profiles: [], problem: "nieczytelny JSON"}`.
- Brak `agents` albo `agents` nie jest tablicą: `problem: "brak listy agents"`.
- Profil bez `id` (string) albo bez niepustego `match` (lista stringów) jest pomijany. Źródło z `path` bezwzględnym (`/x`, `C:/x`, `C:\x`, `\\x`) lub z segmentem `..`, nieznanym `scope` albo nieznanym `pattern` jest pomijane. Builtin bez `key` (string) jest pomijany.
- Coś pominięto, a reszta działa: `problem: "pominięto <n> wpisów"`, gdzie `n` to liczba pominiętych profili, źródeł i builtinów razem.
- `export function resolveProfile(userProfiles: Profile[], agent: string): Profile|null`: najpierw `userProfiles`, potem `DEFAULT_PROFILES`; pierwszy, którego `match` zawiera `agent` (bez rozróżniania wielkości liter, po `trim()`). `""` i `"default"` dają `null`, chyba że ktoś jawnie wpisał je w `match`.
- [ ] **Krok 1: testy (RED)** w `tests/profiles.test.mjs`:
- `resolveProfile([], "claude")` i `resolveProfile([], "Claude-Code")` → `id === "claude-code"`; `resolveProfile([], "codex").id === "codex"`; `resolveProfile([], "kiro-cli") === null`; `resolveProfile([], "default") === null`.
- Profil z pliku `{id:"claude-code", match:["claude-code"], builtins:[{key:"x"}]}` wygrywa z domyślnym: `builtins` to tylko `x`, a `sources` jest puste (brak `claude-plugins`).
- `parseProfiles(null)` → `{profiles:[], problem:null}`.
- `parseProfiles("\uFEFF{\"agents\":[{\"id\":\"kiro\",\"match\":[\"kiro-cli\"],\"sources\":[{\"scope\":\"home\",\"path\":\".kiro/prompts\",\"pattern\":\"*.md\",\"prefix\":\"@\"}]}]}\r\n")` → jeden profil, źródło z `prefix:"@"`, `problem:null`.
- `parseProfiles("{nope")` → `problem:"nieczytelny JSON"`, `profiles:[]`.
- `parseProfiles('{"agents":{}}')` → `problem:"brak listy agents"`.
- Profil z dwoma źródłami `{path:"../x"}` i `{path:"C:/x"}` oraz jednym dobrym → zostaje 1 źródło, `problem:"pominięto 2 wpisów"`.
- Profil bez `match` jest pominięty, drugi dobry zostaje.
- `pattern:"**/*.md"` jest odrzucony.
- `DEFAULT_PROFILES[0].builtins` ma te same klucze co `BUILTINS["claude-code"]`.
- [ ] **Krok 2:** `npm test` daje FAIL (brak modułu).
- [ ] **Krok 3:** zaimplementuj `profiles.js` i przenieś `BUILTINS` z re-eksportem w `catalog.js`.
- [ ] **Krok 4:** `npm test` daje PASS, łącznie z dzisiejszymi 190 testami.
- [ ] **Krok 5: commit** `feat: agent profiles describe each agent's commands`
---
### Task 2: `catalog.js` czyta źródła profilu i komendy z historii
**Pliki:**
- Zmień: `herdr/herdr-composer/mods/herdr-composer/catalog.js`, `herdr/herdr-composer/mods/herdr-composer/suggest.js`
- Test: `tests/catalog.test.mjs`
**Interfejsy:**
- Konsumuje z Task 1: `Profile`, `Source`, `DEFAULT_PROFILES`, `resolveProfile`.
- Produkuje:
- `suggest.js`: `export const GROUP_HISTORY = "Z historii"`, w `GROUPS` po `GROUP_PLUGIN`, przed `GROUP_TERMINAL`.
- `commands(cwd, exec, options)` z `options = {profile?: Profile|null, snippets?, global?: Item[], history?: Item[], onReadError?}`:
- `profile` null lub brak: tylko `snippets` i `history`, bez `exec`;
- w przeciwnym razie kolejność: builtins profilu, źródła `project` profilu (czytane przez `exec` w `cwd`), `global`, `snippets`, `history`;
- deduplikacja po `key`: pierwszy wygrywa;
- `insert` = `source.prefix + key + " "`.
- Źródła `project` listuje **jedno** `exec` (sh, a PowerShell jako zapas, jak dziś `listProjectFiles`). Ścieżki i wzorce idą jako argumenty (sh) lub przez `decode()` (PS), nie są sklejane w skrypt. Nazwa skilla projektu: zawsze nazwa folderu, bez filtra `user-invocable` (jak dziś).
- `globalCommands(home, exec, readText, options)` z `options = {sources: Source[], onReadError?}`:
- czyta tylko źródła `scope:"home"` z `sources`; `kind:"claude-plugins"` daje dzisiejszą logikę pluginów (`~/.claude/settings.json` itd.);
- źródło `home` `{path, pattern}` daje dzisiejszy spec `md` / `skills` dla `${home}/${path}`;
- nazwy i filtr `user-invocable` jak dziś; `insert` z `prefix` źródła (plugin: `"/"`);
- brak `sources` lub pusta lista: `[]` bez `exec`.
- `export function historyCommands(history: HistoryEntry[], agent: string): Item[]`:
- wpisy z `agentName` równym `agent` (bez wielkości liter, `trim`), od najnowszego `sentAt`;
- pierwszy token `text.trimStart()` pasujący do `/^\/[A-Za-z0-9][\w:.-]*$/`;
- `key` bez `/`, `desc: ""`, `group: GROUP_HISTORY`, `insert: "/"+key+" "`;
- bez duplikatów.
- `export function unknownAgentMessage(agent: string): string` oraz `export function profileProblemMessage(problem: string): string`: teksty z Ograniczeń globalnych.
- Usuń `isClaudeCode` i `LIST_SH`/`LIST_PS` na sztywno. Test `isClaudeCode` zastępują testy `resolveProfile` z Task 1, więc usuwasz go.
- [ ] **Krok 1: test „CC bez zmian” PRZED zmianą kodu.** Na obecnym kodzie, na fałszywej maszynie z testów (`machine(...)`) z plikami:
- projekt `.claude/commands/a.md`, `.claude/skills/s/SKILL.md` (z `name: inna`);
- home `~/.claude/commands/handoff.md`;
- jeden plugin.
Wywołaj `commands(cwd, exec, {agent:"claude-code", global: await globalCommands(...)})` i wpisz wynik (lista `{key, group, insert, desc}`) jako literał `EXPECTED_CC` w teście. Commit tylko testu: `test: pin the / menu of Claude Code before profiles`. `npm test` daje PASS.
- [ ] **Krok 2: przepisz ten test na nowe API** (`profile: resolveProfile([], "claude-code")`, `globalCommands(..., {sources: profile.sources})`) z tym samym `EXPECTED_CC`. Dodaj testy (RED):
- `commands` z `profile: null`, `history: [h]` daje `[h]` i `exec` nie zostaje wywołane;
- profil `kiro` ze źródłem project `.kiro/prompts` `*.md` `prefix:"@"` daje `{key:"review", insert:"@review ", group:"Projekt"}`;
- `globalCommands` z `sources: []` daje `[]`, bez `exec`;
- `globalCommands` ze źródłem home `.kiro/prompts` daje grupę `Użytkownik`;
- `historyCommands`: wpisy `"/clear"`, `" /superpowers:brainstorming x"`, `"/c/Users/x"`, `"/ cos"`, `"/"`, `"hej /clear"` oraz wpis innego agenta dają dokładnie `["superpowers:brainstorming","clear"]` (gdy `brainstorming` jest nowszy), w grupie `Z historii`;
- `commands` z builtin `clear` i historią `clear` daje jedno `clear` z grupy `Wbudowane`;
- `GROUPS` zawiera `"Z historii"` zaraz po `"Pluginy"`;
- istniejące testy `globalCommands` dostają mechanicznie `{sources: DEFAULT_PROFILES[0].sources}`.
- [ ] **Krok 3:** `npm test` daje FAIL na nowych testach.
- [ ] **Krok 4:** zaimplementuj.
- [ ] **Krok 5:** `npm test` daje PASS, z `EXPECTED_CC` bez zmian.
- [ ] **Krok 6: commit** `feat: the / menu reads the sources of the agent's profile and its history`
---
### Task 3: `main.js`, czyli plik profili, cache per profil, wiersze informacyjne i README
**Pliki:**
- Zmień: `herdr/herdr-composer/mods/herdr-composer/main.js` (`updateSuggestions` ~2213, `refreshGlobal` ~2228, `loadSuggestions` ~2275, `renderMenu` ~2824, stan w `init` ~199), `herdr/herdr-composer/mods/herdr-composer/catalog.js` (jedna czysta funkcja niżej), README moda (sekcja „Inni agenci”)
- Test: `tests/catalog.test.mjs`
**Interfejsy:**
- Konsumuje: `parseProfiles`, `resolveProfile`, `PROFILES_FILE` (Task 1); `commands`, `globalCommands`, `historyCommands`, `unknownAgentMessage`, `profileProblemMessage` (Task 2).
- Produkuje w `catalog.js`: `export function menuNotes({profile, agent, profilesLoaded, problem}): string[]`:
- `[profileProblemMessage(problem)]`, gdy `problem`;
- plus `unknownAgentMessage(agent)`, gdy `!profile && profilesLoaded`;
- kolejność: najpierw nieznany agent, potem problem.
- Stan w `main.js`:
- `this.userProfiles = []`, `this.profileProblem = null`, `this.profilesLoaded = false`;
- `this.globalCommands = new Map()` (klucz `profile.id`, wartość `Item[]`) i `this.globalLoadedAt = new Map()`, zamiast dzisiejszych pojedynczych pól;
- flaga `this.globalLoading` jak dziś.
- `refreshGlobal(cx)`:
1. gdy minęło 60 s od ostatniego odczytu pliku: `readTextFile([appHome(), PROFILES_FILE].join("\\"))`, potem `parseProfiles` i ustawienie trzech pól oraz `profilesLoaded = true`;
2. `profile = resolveProfile(this.userProfiles, agentName(target))`; gdy profil ma źródła `home` i cache dla `profile.id` jest pusty lub starszy niż 60 s, `globalCommands(home(), exec, readTextFile, {sources: profile.sources, onReadError})` zapisuje wynik pod `profile.id`;
3. po zakończeniu, gdy menu `/` jest otwarte, przeładuj menu tak jak dziś.
W `updateSuggestions` wołaj `refreshGlobal` dla **każdego** agenta przy `/` (usuń warunek `isClaudeCode`). `checking()` blokuje jak dziś.
- `loadSuggestions`, gałąź `/`:
- `profile = resolveProfile(this.userProfiles, agentName(agent))`;
- `commands(cwd, exec, {profile, snippets: [], global: this.globalCommands.get(profile?.id) ?? [], history: catalog.historyCommands(storage.loadHistory(this.store), agentName(agent)), onReadError})`;
- `this.menu.notes = catalog.menuNotes({...})`.
- `renderMenu`: `notes` jako szare (`t.dim`, `text_size(11.5)`) wiersze **pod** pozycjami, w tej samej przewijanej liście. Nie da się ich wybrać, a indeksy pozycji i `scroll_to_item` się nie zmieniają. Komunikat „Żadna komenda nie pasuje” nie pojawia się, gdy pozycji nie ma, a są `notes` z nieznanym agentem.
- README: sekcja „Inni agenci”:
- klucz bierzesz z wiersza „Nieznany agent …”;
- ścieżka pliku i format (pola z tabeli w specu);
- że plik nadpisuje profil o tym samym `id` w całości;
- przykład dla kiro z nagłówkiem „przykład niesprawdzony”.
- [ ] **Krok 1: testy (RED)** `menuNotes`:
- `{profile:null, agent:"kiro-cli", profilesLoaded:true}` daje 1 wiersz zawierający `` `kiro-cli` ``;
- to samo przy `profilesLoaded:false` daje `[]`;
- profil plus `problem:"nieczytelny JSON"` daje `["`composer-agents.json`: nieczytelny JSON"]`;
- `profile:null`, `problem` i `profilesLoaded:true` dają 2 wiersze, najpierw nieznany agent.
- [ ] **Krok 2:** `npm test` daje FAIL.
- [ ] **Krok 3:** zaimplementuj `menuNotes`, zmiany w `main.js` i README.
- [ ] **Krok 4:** `npm test` daje PASS. `grep -n isClaudeCode herdr/herdr-composer/mods/herdr-composer/*.js` nic nie znajduje.
- [ ] **Krok 5: commit** `feat: the composer reads agent profiles from composer-agents.json`
---
## Po wykonaniu (Ovis Opus, nie wykonawca)
- Instalacja: `powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1`, potem `herdr-app status` musi dać `"errors": []`.
- GUI: menu `/` w CC wygląda tak jak przed zmianą.
- Plik testowy `composer-agents.json` z profilem `codex` ze źródłem home `.claude/commands` daje `handoff` w menu codex w ciągu 60 s.
- Uszkodzony plik daje wiersz z powodem. Po teście usuń plik.