5.8 KiB

Raw Permalink Blame History

Verstak Plugin SDK

TypeScript API, JSON-схемы и контрактные тесты для плагинов Верстака.

English · Русский

Контракт alpha-версии. Держите SDK, Desktop и официальные плагины в одной релизной линейке, пока API развиваются.

TypeScript API, JSON-схемы и контрактные тесты для плагинов в Verstak Desktop. SDK версионируется независимо, чтобы авторы плагинов могли валидировать свои manifest и компилироваться против публичного host API.

Установка и проверка

npm ci
npm run lint
npm test
npm run build

Сборка создаёт dist/. Упакованный npm-артефакт можно сделать локально:

./scripts/release.sh v0.1.0

Скрипт проверяет версию на соответствие package.json, затем записывает npm-тарбол и SHA256SUMS в release/.

Публикация GitHub Release

./scripts/publish-github-release.sh v0.1.0

Выполняет локальную упаковку, затем требует чистый актуальный main и авторизованный gh CLI. Создаёт и отправляет аннотированный тег, затем загружает npm-тарбол и SHA256SUMS в GitHub Releases. Запрошенная версия должна совпадать с package.json.

Контракты, актуальные для alpha

Дела имеют постоянные UUID-идентификаторы; пути — это адреса, а не идентификаторы.
Активность может быть привязана к workspaceId или к явной области unassigned.
hostname-normalization-v1.json определяет общее каноническое представление доменов браузера, используемое Desktop и расширением.
Пакеты активности браузера содержат только нормализованный домен и ограниченную длительность. Ручные захваты используют отдельный протокол Inbox.

Контракт синхронизации

schemas/sync.json описывает формат журнала операций, используемый Desktop core и sync-сервером. Сервер упорядочивает операции по server_sequence, не сливает содержимое файлов и не становится источником истины.

Операции с файлами и папками: create, update, delete, move. Небольшой UTF-8 текст может быть встроенным; бинарные и большие файлы содержат ссылку blob {sha256,size}.
Операции с делами (Deal) — это сущности workspace, принадлежащие core: create, rename, trash, restore с постоянным workspaceId.
Pull использует since_sequence и page_limit; клиент сохраняет курсор только после успешного применения каждой операции и останавливается на первой неудачной.
Файл, превышающий лимит blob или иначе неподдерживаемый, не помечается синхронизированным и повторяется при следующих сканированиях.

Контракт Frontend API

Verstak Desktop создаёт реальный API через createPluginAPI(pluginId) и передаёт его компонентам плагинов при монтировании. SDK экспортирует TypeScript-типы для этого объекта:

settings.read/write/writeAll
capabilities.list/get/has
commands.register/execute/executeFor
contributions.list
events.publish/subscribe
files.list/metadata/readText/readBytes/writeText/createFolder/move/trash/listTrash/restoreTrash/deleteTrash
workbench.openResource/editResource
опциональный dispose

Пути к файлам — канонические vault-относительные слеш-пути. Обратные слеши, абсолютные пути Windows/UNC, переходы по директориям, нулевые байты, варианты .verstak и операции через symlink отклоняются. Чтение/запись текста — только UTF-8; readText ограничен 2 МБ, readBytes возвращает base64 для обычных файлов до 8 МБ.

Bundled frontend-плагины являются доверенными и выполняются в контексте JS рабочего стола. Текущие проверки прав — это контрактные проверки, а не граница безопасности; настоящая изоляция — в будущем milestone sidecar/sandbox.

5.8 KiB Raw Permalink Blame History Unescape Escape