86 lines
4.1 KiB
Markdown
86 lines
4.1 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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 install`ovať 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).
|