Files
herdrMario/docs/superpowers/plans/2026-11-19-composer-dock.md
T
2026-11-19 15:56:20 +01:00

12 KiB
Raw Blame History

Composer Dock Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Konfigurowalny dock przycisków w belce herdr-composer: klik wysyła lub wstawia zapisany tekst, a zarządzanie odbywa się z menu pod prawym klikiem.

Architecture: Czysta logika docka i menu w nowym dock.js, zapis w storage.js (herdr-composer.dock). main.js rysuje dock i menu, a wysyłanie przekazuje do istniejącego finish() (kolejka, --force, strażnik agenta), z pominięciem pola tekstowego.

Tech Stack: mod Herdr (ES modules, gpui-kit), node --test.

Spec: docs/superpowers/specs/2026-11-19-composer-dock-design.md · makieta docs/superpowers/mockups/herdr-composer-dock.html

Global Constraints

  • Bez rekompilacji Herdr i bez zmian w plikach dostarczanych z Herdr. Zmiany tylko w herdr/herdr-composer/, tests/, README.md i docs/.
  • Kod modu: herdr/herdr-composer/mods/herdr-composer/. Moduły czyste (dock.js, storage.js) nie importują gpui-kit, gpui-base ani herdr.
  • Klucz zapisu herdr-composer.dock, bez odczytu ovis-composer.* (nowa funkcja, brak migracji).
  • Limit 30 przycisków. Nazwa domyślna ma najwyżej 16 znaków (15 + …), białe znaki są zwinięte do jednej spacji.
  • Teksty UI po polsku, dosłownie: „Przypnij do docka”, „Odepnij z docka”, „Przypnij bieżący tekst do docka”, „Odepnij bieżący tekst z docka”, „Zmień nazwę”, „Tylko wstawiaj”, „Wysyłaj od razu”, „Przesuń w lewo”, „Przesuń w prawo”, „Usuń z docka”, „Wstaw”, „Dodaj do ulubionych”, „Usuń z ulubionych”, „Prawy klik w Ulubionych → Przypnij do docka”.
  • Dock ma wysokość 28 px i nie może zwiększać wysokości bloku composera (auto-fit).
  • Skróty klawiszowe modu zostają w kontekście herdr-composer > Input. Nie dodajemy nowych globalnych.
  • Testy: npm test (dziś 155 pass) musi być zielone po każdym zadaniu.
  • Po zmianie modu: install.cmd (kopia do ~/.config/herdr-app/mods/herdr-composer), herdr-app status → "errors": [].

Review Focus

  • Klik przycisku send, gdy w polu jest niewysłany szkic: szkic i załączniki zostają nietknięte, a wysyła się tylko tekst przycisku.
  • Klik send, gdy agent working albo kolejka niepusta: wiadomość trafia do kolejki, a nie wychodzi od razu. Agent blocked dostaje ją od razu z --force.
  • Klik tuż po przełączeniu agenta (okno 500 ms): syncOk blokuje wysyłkę i pokazuje komunikat, bez wysłania do złego agenta.
  • Uszkodzony albo ręcznie zmieniony herdr-composer.dock w shared.json (nie-tablica, brak pól, duplikaty, ponad 30): dock ładuje to, co poprawne, i nie wywraca modu.
  • Edycja nazwy w miejscu: Esc anuluje tylko edycję i nie przerywa agenta. Enter zapisuje i niczego nie wysyła.

Task 1: dock.js + zapis w storage.js

Files:

  • Create: herdr/herdr-composer/mods/herdr-composer/dock.js
  • Modify: herdr/herdr-composer/mods/herdr-composer/storage.js (KEYS, nowe loadDock/saveDock)
  • Test: tests/dock.test.mjs, tests/storage.test.mjs

Interfaces — Produces:

  • DockButton = { id: string, label: string, text: string, mode: "send" | "insert" }

  • MenuItem = { command: string, label: string, disabled?: boolean, danger?: boolean }

  • DOCK_LIMIT = 30, LABEL_MAX = 16

  • defaultLabel(text: string): string

  • normalize(raw: unknown): DockButton[]: przepuszcza tylko poprawne wpisy (id i text niepuste, mode z listy). Pusty label zamienia na defaultLabel(text). Odrzuca duplikaty text (porównanie po trim(), pierwszy wygrywa) i obcina do 30.

  • isPinned(dock, text): boolean (porównanie po trim()).

  • pin(dock, text, id): DockButton[]: dodaje na końcu {id, label: defaultLabel(text), text: text.trim(), mode: "send"}. Zwraca ten sam dock, gdy tekst jest pusty, już przypięty albo osiągnięto limit.

  • unpin(dock, text), remove(dock, id), move(dock, id, step: -1 | 1) (na krawędzi bez zmian), rename(dock, id, label) (pusty po trim() → defaultLabel(text)), toggleMode(dock, id): każda zwraca nową tablicę i nie mutuje wejścia.

  • dockAction(button, { hasAgent: boolean }): "send" | "insert" | "none"

  • dockMenu(dock, id): MenuItem[]: komendy po kolei: rename, mode (etykieta „Tylko wstawiaj” przy send, „Wysyłaj od razu” przy insert), left (disabled na pierwszym), right (disabled na ostatnim), remove (danger: true).

  • rowMenu({ tab: "history" | "favorites", favorite: boolean, pinned: boolean }): MenuItem[]: insert „Wstaw”. Potem w zakładce favorites pin („Przypnij do docka” / „Odepnij z docka”). Na końcu favorite („Dodaj do ulubionych” / „Usuń z ulubionych”, danger przy usuwaniu).

  • starMenu({ text: string, pinned: boolean }): MenuItem[]: jedna pozycja pin („Przypnij bieżący tekst do docka” / „Odepnij bieżący tekst z docka”), disabled, gdy text.trim() jest pusty.

  • storage.js: KEYS.dock = "herdr-composer.dock", loadDock(store): DockButton[] (przez normalize, bez fallbacku ovis-composer.), saveDock(store, items): void (zapisuje normalize(items)).

  • Step 1: Napisz testy, które padają w tests/dock.test.mjs. Przypadki z wartościami:

    • defaultLabel("/handoff") === "/handoff"
    • defaultLabel("npm test i raport po polsku") === "npm test i rapo…" (15 + …)
    • defaultLabel(" a\n b ") === "a b"
    • normalize("x") daje []
    • normalize([{id:"1",text:"a",mode:"send",label:""}, {id:"2",text:" a ",mode:"send",label:"x"}, {id:"3",text:"b",mode:"zly"}]) → jeden wpis {id:"1",label:"a",text:"a",mode:"send"}
    • normalize z 35 poprawnymi wpisami → długość 30
    • pin([], " /clear ", "9") → [{id:"9",label:"/clear",text:"/clear",mode:"send"}]; pin tego samego tekstu drugi raz → bez zmian; pin(d, " ", "x") → bez zmian; pin przy 30 → bez zmian
    • move(d, firstId, -1) → bez zmian; move(d, firstId, 1) zamienia pierwszy z drugim; wejście nie jest zmutowane (Object.isFrozen-owa kopia albo porównanie z kopią)
    • rename(d, id, " ") → label === defaultLabel(text); toggleMode dwa razy → "send"
    • dockAction({mode:"insert"}, {hasAgent:true}) === "insert"; dockAction({mode:"send"}, {hasAgent:false}) === "none"
    • dockMenu: komendy ["rename","mode","left","right","remove"]; dla pierwszego left.disabled === true; etykiety trybu jak wyżej
    • rowMenu({tab:"history",favorite:false,pinned:false}) → komendy ["insert","favorite"]; rowMenu({tab:"favorites",favorite:true,pinned:true}) → ["insert","pin","favorite"] z etykietą „Odepnij z docka”
    • starMenu({text:"",pinned:false})[0].disabled === true

    W tests/storage.test.mjs: saveDock → loadDock daje to samo; loadDock przy wartości pod ovis-composer.dock i braku nowej → []; śmieci pod kluczem → [].

  • Step 2: npm test: nowe testy padają (brak modułu lub funkcji).

  • Step 3: Zaimplementuj dock.js i zmiany w storage.js (dla odczytu wzoruj się na readList, ale bez loadMigrating).

  • Step 4: npm test: wszystko zielone.

  • Step 5: Commit feat: dock model and storage (herdr-composer.dock)

Task 2: Dock w belce: rysowanie i klik

Files:

  • Modify: herdr/herdr-composer/mods/herdr-composer/main.js (init: this.dock = loadDock(store); renderCard; nowe renderDock, dockPress)

Interfaces — Consumes: Task 1 (loadDock, saveDock, dockAction, DockButton), istniejące syncOk, target, finish(agent, message, cx, mode), overLimit, textarea.replace, syncFieldAfterReplace, notice.

  • Step 1: W renderCard wstaw za ☆ separator (1×18 px, t.border). Zamiast div().flex_1() wstaw renderDock(t, active): h_flex().flex_1().min_w(0).h(28).gap(6).overflow_x_scroll() (id("composer-dock")). Pusty dock pokazuje podpowiedź w kolorze t.dim, rozmiar 12.
  • Step 2: Przycisk id("dock-"+b.id), wysokość 28, px(11), rounded(8), tekst 12, flex_none, maks. szerokość 150 z ucięciem. send: bg(t.chrome), text_color(t.foreground). insert: brak tła, ramka 1 px t.border (przerywana, jeśli API pozwala; jeśli nie, pełna) i prefiks ✎ w t.dim. Gdy !active: text_color(t.dim), bez cursor_pointer i bez akcji. Tooltip z pełnym text, jeśli gpui-kit ma tooltip; jeśli nie, pomiń.
  • Step 3: dockPress(button, cx):
    • insert: this.textarea.replace(button.text), syncFieldAfterReplace(), notice „Wstawiono w miejscu kursora — nic nie zostało wysłane.”
    • send: syncOk (przy błędzie ten sam komunikat co w submit, bez „Zostaje w szkicu”), potem target(), overLimit(button.text), a na końcu this.finish(agent, button.text.trim(), cx). Nie wolno wołać clearField, submit ani ruszać załączników.
  • Step 4: npm test zielone, install.cmd, herdr-app check i herdr-app status bez błędów. Testu w GUI wykonawca nie robi (Task 4, Opus).
  • Step 5: Commit feat: composer dock in the bar (send / insert)

Task 3: Menu pod prawym klikiem (dock, ☆, wiersze panelu)

Files:

  • Modify: main.js (menu i obsługa komend), panel.js (secondary click woła on.rowMenu(key, event, cx) zamiast on.toggle)

Interfaces — Consumes: dockMenu, rowMenu, starMenu, pin, unpin, remove, move, rename, toggleMode, isPinned, saveDock, istniejące toggleFavoriteText, panelPickKey, isFavorite, newId.

  • Step 1: Jeden renderer menu renderContextMenu(t, items, onCommand): v_flex, min. szerokość 210, bg(t.raised), ramka t.border, rounded(8), p(4). Pozycja danger w kolorze błędu z motywu, disabled przygaszona i bez akcji. Stan this.contextMenu = { kind: "dock" | "row" | "star", id | key, items } | null. Esc z fokusem w polu zamyka najpierw menu (dopisz w runAction("escape") przed panelem i przerwaniem agenta). Klik poza menu zamyka (on_mouse_down_out).
  • Step 2: Kotwiczenie. Przycisk docka i ☆: Popover z .mouse_button("right"), kontrolowany (open(this.contextMenu?.kind===... && id===...), on_open_change). Wiersz panelu (lista wirtualna, on_item_secondary_click): menu jako Popup zakotwiczony do kontenera panelu (anchor("top_right")). Ruling: jeśli Popover nie zadziała z prawym przyciskiem w GUI, użyj Popup zakotwiczonego do całego docka, z tym samym rendererem.
  • Step 3: Komendy.
    • dock: rename ustawia this.renaming = id i rysuje przycisk jako mały Input (osobny stan input, szer. 110, wstępnie pełna nazwa). Enter wywołuje rename + saveDock. Esc i blur anulują. Kontekst herdr-composer > Input obejmuje też ten input, więc w runAction przy this.renaming klawisze escape, up, down i tab są obsługiwane jako edycja nazwy, a nie composera.
    • dock: mode wywołuje toggleMode, left/right wywołują move, remove wywołuje remove. Każda kończy się saveDock i cx.notify().
    • wiersz: insert woła panelPickKey, favorite woła toggleFavoriteText, pin woła pin(dock, text, this.newId()) albo unpin.
    • ☆: pin/unpin bieżącego this.value.
    • Lewy klik ☆ bez zmian.
  • Step 4: Ctrl+D w panelu dalej przełącza ulubione od razu (sprawdź, że panelKey tego nie zmienia).
  • Step 5: npm test, install.cmd, herdr-app check i status bez błędów.
  • Step 6: Commit feat: right-click menus for dock, star and panel rows

Task 4 (Opus): weryfikacja w GUI, dokumentacja

  • Test GUI (SendKeys i herdr-app shot, wykonuje Opus):
    • przypięcie z Ulubionych oraz z ☆;
    • klik send przy idle: dociera do agenta, a szkic zostaje;
    • klik przy working: trafia do kolejki;
    • tryb insert: tekst w miejscu kursora;
    • zmiana nazwy Enter/Esc;
    • przesuwanie i usuwanie;
    • przepełnienie (ponad 8 przycisków), przewijanie;
    • brak agenta: wyszarzone;
    • restart modu (install.cmd): dock przetrwał.
  • README: wiersz w tabeli Użycie („dock”) i akapit w „Dane” (herdr-composer.dock). RECIPE.md: punkt w „How it behaves”. preview.png: nowy zrzut z dockiem.
  • Commit docs: composer dock in README, RECIPE and preview