JSONdevTools/AGENTS.md

AGENTS.md — JSON DevTools

Statická jednostránková aplikácia (vanilla ES6+, HTML/CSS/JS). Bez frameworkov, bez npm, bez build procesu, bez backendu, bez CDN. Bez CI, package.json ani lint konfigurácie — repozitár je hotový, nič sa nekompiluje.

ZákAZ KONTROL V PREHLIADAČOCH

V prehliadačoch sa nesú overovanie aplikácie – používateľ to robí sám. Neotváraj Chrome/Chromium ani iný prehliadač, neautomatizuj ich, nescreenshotuj cez prehliadač. Trvalé používateľské nariadenie, zapísané aj v globálnej pamäti ~/.config/opencode/AGENTS.md.

Povolené: statická kontrola (node --check), testy logiky v Node.js, curl/python. Nepridávaj do repozitára testy ani nástroje založené na prehliadači.

Štruktúra

src/index.html   src/style.css   src/app.js   # aplikácia – musia zostať v jednej zložke
tests/logic.test.js                # Node testy (bez prehliadača)
docs/                             # screenshoty pre README

• src/index.html načítava style.css a app.js relatívnou cestou → všetky tri súbory musia zostať v src/. Presun do rootu rozbije načítanie aj testy.
• Aplikácia sa otvára ako src/index.html (relatívne cesty), nie cez root.
• Repo hostuje Gitea, nie GitHub — nepridávaj GitHub Actions/Pages šablóny.

Príkazy

node --check src/app.js            # rýchla syntax kontrola
node tests/logic.test.js           # testy logiky – 93 assertov, exit 1 pri chybe
python -m http.server 8080 --directory src   # lokálne spustenie (voliteľné)

Nie je čo npm installovať ani buildovať – po úprave src/*.js|css|html stačí reload stránky.

Ako funguje tests/logic.test.js

• src/app.js sa načíta do vm sandboxu s ručným DOM stubom (žiadne jsdom). Aplikácia sa musí vedieť načítať bez reálneho DOM.
• Stub vracia nový generický element pri každom querySelector() → DOM interakcie (tlačidlá, eventy, fokus) sa v Node testoch neoverujú. Overuj logiku cez window.JSONDevTools, nie cez DOM.
• src/app.js musí na konci exportovať window.JSONDevTools (objekt s modulmi Utils, Toast, Theme, Splitter, Highlighter, Doc, Formatter, FileIO, Tree, Diff, Api, History, App) — bez neho testy skončí chybou.
• Testy čítajú ../src/app.js a ../src/index.html → pri presunu súborov treba upraviť cesty v tests/logic.test.js.
• Pomocníci: ok(name, cond, extra), eq(name, a, b), deepEq(...), section(t).
• Testy obsahujú aj statické kontroly konzistencie: každé $('#id') v app.js musí existovať v index.html, každé <button id> musí mať handler, id v HTML nesmie byť duplicitné. Nové id v HTML pridaj aj do app.js, inak test zfailuje.

Architektúra src/app.js

Jeden IIFE, vnútri moduly: Utils, LS, Toast, Theme, Splitter, Highlighter, Doc, Formatter, FileIO, Tree, Diff, Api, History, App. Bez tried, bez DI – moduly sú plain objekty.

Nároky, ktoré treba rešpektovať:

• Doc je zdieľaný stav medzi Formatter a Tree – oba textareas sú synchro cez Doc.set(text, origin). Nový JSON pohľad pripoj cez Doc.onChange(), nie vlastnou kopírou textu.
• localStorage len cez Utils.store (prefix jsondevtools.*). Wrapper zachytáva prekročenie kvóty a vyhodí toast – nepristupuj k localStorage priamo.
• Bezpečnostná invariant: do historie sa nikdy nesmie uložiť Authorization, Cookie ani X-Api-Key – prechádza to cez sanitizeHeaders() v Api. Tokeny žijú iba v pamäti stránky.
• CSS motívy sú CSS custom properties v html[data-theme="dark"|"light"] – nové farby pridávaj ako premenné, nie ako hardcoded hodnoty.
• UI texty v slovenčine, JSON hodnoty v angličtine.

Ostatné

• Screenshoty v docs/ sú v README vložené relatívnou cestou (docs/...) – pri presúvaní ich treba aktualizovať aj v README.md.
• src/index.html?theme=light|dark prepne motív len pre dané načítanie – uloženú preferenciu v localStorage neprepíše (prepíše ju až prepínač v hlavičke).