docs: herdr-composer package design and plan

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
FactorandClaude Opus 5.5 committed 2026-11-19 12:51:12 +01:00
1 parent 75025c2406
commit 6beecaac83
1 file changed
+39
@@ -0,0 +1,39 @@
# herdr-composer — instalowalna paczka (projekt + plan)
> Zatwierdzone przez użytkownika 2026-11-19. Wykonawca: Ovis Fast. Review: Ovis Opus.
## Cel
Prywatny mod (repo `http://git.mkali.pl/Factor/herdrMario.git`) instalowany jedną komendą — przez agenta (wzór herdr.dev: „Read ~/.config/herdr-app/AGENTS.md, then add this layout: …”) albo `install.cmd`. Nazwa `herdr-composer` (zamiast `ovis-composer`). Bez publikacji na GitHub/herdr.dev.
## Decyzje
- Format paczki wg `~/.config/herdr-app/AGENTS.md` („Layouts and mods other people made”): folder `herdr/herdr-composer/` = `layouts/herdr-composer.json`, `mods/herdr-composer/*`, `keys.json`, `RECIPE.md`, `preview.png`.
- Instalacja przez **kopię** (nie junction) → Herdr sam przeładowuje mod; aktualizacja = ponowne `install.cmd`.
- Zmiana nazwy bez utraty danych: odczyt `herdr-composer.*`, a gdy brak — `ovis-composer.*` (i zapis pod nową nazwą).
## Zadanie A (Ovis Fast) — restrukturyzacja + zmiana nazwy + migracja
1. `git mv mod/ovis-composer herdr/herdr-composer/mods/herdr-composer`; `git mv layouts/ovis-composer.json herdr/herdr-composer/layouts/herdr-composer.json` (w layoucie `content.mod` → `herdr-composer`). Usuń puste `mod/`, `layouts/`.
2. W kodzie modu wszystkie identyfikatory `ovis-composer` → `herdr-composer`: `CONTEXT`/`key_context`, nazwy akcji `herdr-composer.*` (bind_keys + on_action), klucze `storage.KEYS` (`herdr-composer.history`, `.favorites`, `.usage`, `.userMin`, `.draft:<a>`, `.queue:<a>`), folder obrazów `data/herdr-composer/paste/`, `id()` elementów, komentarze/teksty. `.gitignore`: `herdr/herdr-composer/mods/herdr-composer/gpui-kit.d.ts`.
3. Migracja w `storage.js` (czyste, testowane): każda funkcja `load*` czyta nowy klucz; gdy `null/undefined` — czyta klucz `ovis-composer.*` (ta sama końcówka) i, jeśli coś znalazła, zapisuje to pod nowym kluczem. Stare klucze zostają nietknięte. `cleanupPaste` sprząta oba foldery (`data/ovis-composer/paste` i nowy).
4. `herdr/herdr-composer/keys.json`: `{"global": {"ctrl-shift-space": "herdr-composer.focus"}}`.
5. Testy: importy z `../herdr/herdr-composer/mods/herdr-composer/<m>.js`; nowe testy migracji (nowy klucz wygrywa; fallback ze starego + zapis pod nowym; brak obu → domyślne; śmieci w starym kluczu → ignorowane jak dotąd).
6. `grep -ri "ovis-composer"` w `herdr/` i `tests/` → tylko w kodzie migracji i w RECIPE (zdanie o pochodzeniu).
## Zadanie B (Ovis Fast) — instalator
`install.cmd` w korzeniu repo (wywołuje `powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0scripts\install.ps1" %*`) i przepisany `scripts/install.ps1` (PowerShell 5):
- `install` (domyślnie): jeśli repo jest klonem git i nie ma lokalnych zmian → `git pull --ff-only` (błąd = ostrzeżenie, kontynuacja). Kopiuje `herdr/herdr-composer/mods/herdr-composer` → `%USERPROFILE%\.config\herdr-app\mods\herdr-composer` (mirror: `robocopy /MIR`, kod wyjścia < 8 = OK; pomija `gpui-kit.d.ts`, `jsconfig.json`) i layout → `layouts\herdr-composer.json`. Scalenie `keys.json` paczki do `keys.json` użytkownika (kopia `keys.json.bak-herdr-composer` raz; nie nadpisuje istniejącego klawisza innego niż nasz — ostrzeżenie). Na końcu `herdr-app check …\mods\herdr-composer` i `herdr-app do layout.switch '{"name":"herdr-composer"}'`; brak `herdr-app` w PATH → ostrzeżenie, nie wyjątek.
- **Sprzątanie poprzedniej wersji (`ovis-composer`):** jeśli `mods\ovis-composer` jest junction → `cmd /c rmdir` (tylko link); jeśli zwykły katalog → przenieś do `mods\ovis-composer.bak-<data>`. `layouts\ovis-composer.json` → przenieś do `.bak-<data>`. W `keys.json` usuń wpis wskazujący na `ovis-composer.focus`. Nigdy nie usuwaj plików repo.
- `-Uninstall`: usuwa `mods\herdr-composer`, `layouts\herdr-composer.json`, nasz klawisz z `keys.json`, przełącza na `main`.
- README: sekcja „Instalacja” — (1) przez agenta: `Read ~/.config/herdr-app/AGENTS.md, then add this layout: clone http://git.mkali.pl/Factor/herdrMario.git and use the folder herdr/herdr-composer`; (2) jedna komenda: `git clone http://git.mkali.pl/Factor/herdrMario.git "%USERPROFILE%\herdrMario" && "%USERPROFILE%\herdrMario\install.cmd"`; aktualizacja: ponownie `install.cmd`; odinstalowanie: `install.cmd -Uninstall`.
- Usuń `-Reload` i junction z dokumentacji (nieaktualne).
## Zadanie C (Ovis Fast) — RECIPE.md + preview.png
`herdr/herdr-composer/RECIPE.md` dokładnie wg struktury z AGENTS.md (Name + akapit + `![…](preview.png)`; What you see; How it behaves; Built from; Watch out). W **Built from/Watch out** jawnie: uruchamia `powershell` (`exec`: schowek, wybór pliku, rozmiary plików — ścieżki tylko jako Base64), `hc` (`send`, `put`, `get`, `interrupt`, `keys`), czyta pliki spoza swojego folderu (pliki użytkownika wskazane jako załączniki, `git ls-files` w folderze agenta); „+” i Ctrl+V obrazu tylko Windows; layout jest klonem `main` (wersja z `cloned_from`); UX inspirowany Ovis (devswha/ovis). `preview.png`: zrzut `herdr-app shot` okna z composerem (po instalacji, Zadanie D).
## Zadanie D (Ovis Opus) — instalacja na tej maszynie i weryfikacja
`install.cmd` na tym komputerze → `herdr-app status` bez błędów, layout `herdr-composer`, historia/ulubione/drafty widoczne (migracja), `Ctrl+Shift+Space`, panel, test w GUI. `preview.png` ze zrzutu.
## Kryteria akceptacji
- `npm test` zielone; `herdr-app check` modu OK.
- Po `install.cmd` Herdr pokazuje composer w layoucie `herdr-composer`, historia sprzed zmiany nazwy jest widoczna.
- Zmiana w repo + ponowne `install.cmd` → Herdr przeładowuje mod bez dodatkowych kroków.
- `install.cmd -Uninstall` zostawia `~/.config/herdr-app` bez śladów `herdr-composer` (poza kopiami `.bak`).