verstak-desktop/AGENTS.md

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:

./verstak-desktop --debug

Logs go to: ~/.local/share/verstak/debug/verstak-YYYY-MM-DD-HHMMSS.log

View in real-time:

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:

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.