106 lines
5.8 KiB
Markdown
106 lines
5.8 KiB
Markdown
<div align="center">
|
||
|
||
# Verstak Plugin SDK
|
||
|
||
### TypeScript API, JSON-схемы и контрактные тесты для плагинов Верстака.
|
||
|
||
[English](README.md) · **Русский**
|
||
|
||
[](https://github.com/mirivlad/verstak-sdk/releases)
|
||
|
||
[](LICENSE)
|
||
|
||
</div>
|
||
|
||
> **Контракт alpha-версии.** Держите SDK, Desktop и официальные плагины
|
||
> в одной релизной линейке, пока API развиваются.
|
||
|
||
TypeScript API, JSON-схемы и контрактные тесты для плагинов в Verstak Desktop.
|
||
SDK версионируется независимо, чтобы авторы плагинов могли валидировать
|
||
свои manifest и компилироваться против публичного host API.
|
||
|
||
## Установка и проверка
|
||
|
||
```bash
|
||
npm ci
|
||
npm run lint
|
||
npm test
|
||
npm run build
|
||
```
|
||
|
||
Сборка создаёт `dist/`. Упакованный npm-артефакт можно сделать локально:
|
||
|
||
```bash
|
||
./scripts/release.sh v0.1.0
|
||
```
|
||
|
||
Скрипт проверяет версию на соответствие `package.json`, затем записывает
|
||
npm-тарбол и `SHA256SUMS` в `release/`.
|
||
|
||
## Публикация GitHub Release
|
||
|
||
```bash
|
||
./scripts/publish-github-release.sh v0.1.0
|
||
```
|
||
|
||
Выполняет локальную упаковку, затем требует чистый актуальный `main` и
|
||
авторизованный [`gh`](https://cli.github.com/) 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.
|
||
|
||
## Лицензия
|
||
|
||
Copyright © 2026 Verstak contributors. Распространяется на условиях
|
||
[GNU AGPLv3 или новее](LICENSE).
|