180 lines
5.8 KiB
Markdown
180 lines
5.8 KiB
Markdown
# AGENTS.md — Verstak Desktop
|
||
|
||
## Назначение
|
||
|
||
`verstak-desktop` — Core Platform + UI Shell. Это минимальное ядро, которое запускает приложение, управляет плагинами и предоставляет общий интерфейс. **Core не содержит бизнес-функций пользователя.**
|
||
|
||
## Главные инварианты
|
||
|
||
- Core не импортирует official plugins как обязательные модули.
|
||
- Core не содержит notes/files/editor/activity/journal как внутренние фичи.
|
||
- Все пользовательские функции приходят через динамические плагины.
|
||
- Plugin Manager UI — обязательный компонент core с первого этапа.
|
||
- Capability registry и contribution registry — механизмы связи, а не жёсткие импорты.
|
||
- Плагины не могут обращаться к Wails backend методам напрямую — только через VerstakPluginAPI.
|
||
|
||
## Технологии
|
||
|
||
- **Backend:** Go (Wails v2)
|
||
- **Frontend:** Svelte (plain JS, без `lang="ts"`)
|
||
- **UI Shell:** окно, навигация, command palette, settings, plugin manager, dialogs/toasts
|
||
|
||
## Что НЕ входит в core
|
||
|
||
- Markdown editor (это плагин)
|
||
- File manager (это плагин)
|
||
- Notes workflow (это плагин)
|
||
- Activity / journal (это плагины)
|
||
- Browser inbox (это плагин)
|
||
- Search (это плагин)
|
||
- Secrets (это плагин)
|
||
- Templates (это плагин)
|
||
|
||
## Plugin Runtime
|
||
|
||
1. Discovery — сканирование plugin directories, чтение plugin.json
|
||
2. Validation — проверка schemaVersion, apiVersion, обязательных полей
|
||
3. State check — enabled/disabled
|
||
4. Capability resolution — проверка requires/optionalRequires
|
||
5. Permissions — запрос, отображение пользователю
|
||
6. Backend sidecar — launch, если нужен
|
||
7. Frontend bundle — загрузка, если есть
|
||
8. Registration — capabilities и contributions в registry
|
||
9. Status — loaded / degraded / failed / incompatible / missing-required-capability
|
||
|
||
## Структура репозитория
|
||
|
||
```
|
||
verstak-desktop/
|
||
AGENTS.md
|
||
go.mod
|
||
main.go
|
||
cmd/
|
||
internal/
|
||
core/
|
||
plugin/
|
||
discovery.go
|
||
manifest.go
|
||
state.go
|
||
lifecycle.go
|
||
capability/
|
||
registry.go
|
||
contribution/
|
||
registry.go
|
||
permissions/
|
||
registry.go
|
||
events/
|
||
bus.go
|
||
settings/
|
||
registry.go
|
||
vault/
|
||
api.go
|
||
storage/
|
||
api.go
|
||
diagnostics/
|
||
api.go
|
||
sync/
|
||
boundary.go
|
||
shell/
|
||
app/
|
||
navigation/
|
||
window/
|
||
command-palette/
|
||
plugin-manager/
|
||
ui/
|
||
settings/
|
||
dialogs/
|
||
api/
|
||
plugin.go
|
||
frontend/
|
||
src/
|
||
wails.json
|
||
...
|
||
```
|
||
|
||
## Verification language policy
|
||
|
||
**Do not say "checked", "verified", "works", or "all good" unless a concrete
|
||
verification command or user scenario was executed.**
|
||
|
||
Use exact labels:
|
||
- Build checked
|
||
- Unit tests checked
|
||
- Backend behavior checked
|
||
- Frontend E2E checked
|
||
- Real desktop GUI checked
|
||
- Not checked / requires manual verification
|
||
|
||
If GUI behavior was not clicked and asserted, report:
|
||
"GUI behavior was not verified."
|
||
|
||
### GUI testing
|
||
|
||
Frontend E2E tests are in `frontend/e2e/`. Run with `npm run test:e2e`.
|
||
These tests use Playwright + mocked Wails bindings. They test Svelte component
|
||
logic and user interactions in a real Chromium browser.
|
||
|
||
**Limitations:** Playwright tests do NOT test the real WebKitGTK/Wails native
|
||
shell. For real desktop GUI verification, a separate AT-SPI/xdotool layer is
|
||
needed (not yet implemented).
|
||
|
||
See `docs/GUI_TESTING.md` for details.
|
||
|
||
## Debug logging
|
||
|
||
**Always use debug logging when investigating issues. Never rely on "it should work" — look at the logs.**
|
||
|
||
### Backend debug
|
||
|
||
Enable with `--debug` flag:
|
||
```bash
|
||
./verstak-desktop --debug
|
||
```
|
||
|
||
Logs go to: `~/.local/share/verstak/debug/verstak-YYYY-MM-DD-HHMMSS.log`
|
||
|
||
View in real-time:
|
||
```bash
|
||
tail -f ~/.local/share/verstak/debug/verstak-*.log
|
||
```
|
||
|
||
What's logged (when `--debug` is active):
|
||
- Plugin discovery: dirs scanned, each plugin found (id, name, version, source, root)
|
||
- Plugin lifecycle: capability registration, contribution registration, status transitions
|
||
- API calls: GetPlugins, GetContributions, GetCapabilities, ReloadPlugins, EnablePlugin, DisablePlugin
|
||
- Vault operations: open/close/status
|
||
|
||
### Frontend debug
|
||
|
||
Enable via **either**:
|
||
1. URL query param: `?debug` (not practical in Wails, use #2)
|
||
2. In browser console: `localStorage.setItem('verstak-debug', 'true')` then reload
|
||
|
||
Logs go to:
|
||
- Browser console (with `[debug]` prefix)
|
||
- localStorage buffer: `localStorage.getItem('verstak-debug-log')` (last 1000 entries)
|
||
|
||
Export frontend log from console:
|
||
```javascript
|
||
copy(JSON.parse(localStorage.getItem('verstak-debug-log')))
|
||
// or
|
||
window.__verstakDebug.exportLog()
|
||
```
|
||
|
||
What's logged:
|
||
- App startup: checkVault, GetAppSettings, GetVaultStatus
|
||
- Navigation: onNav, onOpenView, onOpenSettings, onCloseSettings
|
||
- PluginManager: loadAll (start/end, plugin count, each plugin status), reload, enable/disable
|
||
- Sidebar: onMount (plugins loaded, sidebar items count), handleNav, handleSidebarItem
|
||
|
||
### Debug workflow
|
||
|
||
1. User reports issue
|
||
2. Restart app with `--debug` and reproduce
|
||
3. Run `tail -f ~/.local/share/verstak/debug/verstak-*.log` and share output
|
||
4. For frontend issues: enable frontend debug view `exportLog()` output
|
||
5. Analyze logs, identify root cause, fix
|
||
6. Verify fix by asking user to reproduce again with debug on
|
||
|
||
**Never skip step 2-4. Always look at real logs before proposing fixes.**
|