174 lines
5.0 KiB
Markdown
174 lines
5.0 KiB
Markdown
# Verstak Repositories
|
||
|
||
## 1. Организация
|
||
|
||
Для GitHub/Gitea лучше использовать organization `verstak` или аналогичную общую группу. Внутри нее живут отдельные репозитории одной продуктовой идеи.
|
||
|
||
Project board можно вести на уровне organization: roadmap, issues, milestones, cross-repo tasks.
|
||
|
||
## 2. Минимальный набор репозиториев
|
||
|
||
### `verstak-desktop`
|
||
|
||
Основное desktop-приложение.
|
||
|
||
Содержит:
|
||
|
||
- Core Platform;
|
||
- UI Shell;
|
||
- plugin loader;
|
||
- capability registry;
|
||
- settings window;
|
||
- plugin manager UI;
|
||
- vault API;
|
||
- storage API;
|
||
- event bus;
|
||
- sync client boundary;
|
||
- dev harness для локальных плагинов.
|
||
|
||
Не содержит:
|
||
|
||
- notes как обязательный модуль;
|
||
- file manager как обязательный модуль;
|
||
- markdown editor как обязательный модуль;
|
||
- browser extension код;
|
||
- sync server код.
|
||
|
||
### `verstak-official-plugins`
|
||
|
||
Монорепозиторий официальных плагинов.
|
||
|
||
Содержит:
|
||
|
||
```text
|
||
plugins/
|
||
files/
|
||
notes/
|
||
markdown-editor/
|
||
markdown-preview/
|
||
file-preview/
|
||
activity/
|
||
journal/
|
||
browser-inbox/
|
||
search/
|
||
secrets/
|
||
templates/
|
||
packages/
|
||
plugin-sdk/
|
||
shared-ui/
|
||
test-harness/
|
||
```
|
||
|
||
Официальные плагины должны устанавливаться и загружаться так же, как сторонние. Нельзя делать для них скрытый privileged path, кроме явно описанных platform permissions.
|
||
|
||
### `verstak-sdk`
|
||
|
||
Общие контракты для разработки плагинов.
|
||
|
||
Содержит:
|
||
|
||
- manifest schema;
|
||
- TypeScript SDK;
|
||
- RPC protocol definitions;
|
||
- capability contracts;
|
||
- event schemas;
|
||
- test helpers;
|
||
- plugin packaging tools;
|
||
- examples.
|
||
|
||
На раннем этапе SDK может жить в `verstak-official-plugins/packages/plugin-sdk`, но должен быть выделен в отдельный репозиторий, когда API начнет стабилизироваться.
|
||
|
||
### `verstak-sync-server`
|
||
|
||
Отдельный сервер синхронизации.
|
||
|
||
Содержит:
|
||
|
||
- HTTP API;
|
||
- auth/pairing;
|
||
- device registry;
|
||
- vault operation log;
|
||
- blob upload/download;
|
||
- conflict handling;
|
||
- retention/deleted file policy;
|
||
- server migrations;
|
||
- deployment docs.
|
||
|
||
Sync server не должен импортировать desktop UI или official plugins.
|
||
|
||
### `verstak-browser-extension`
|
||
|
||
Расширение браузера.
|
||
|
||
Содержит:
|
||
|
||
- Firefox/Chromium extension;
|
||
- local pairing with Verstak;
|
||
- page capture;
|
||
- selected text capture;
|
||
- link sending;
|
||
- pending queue if desktop is offline;
|
||
- domain bindings support;
|
||
- protocol docs for browser inbox plugin.
|
||
|
||
Расширение не должно напрямую знать внутреннюю структуру notes/files/activity. Оно отправляет события в local receiver, а обработка идет через плагин `official.browser-inbox`.
|
||
|
||
## 3. Репозитории позже
|
||
|
||
### `verstak-plugin-registry`
|
||
|
||
Каталог доступных плагинов:
|
||
|
||
- official plugin index;
|
||
- third-party plugin metadata;
|
||
- signatures/checksums;
|
||
- compatibility matrix;
|
||
- install URLs.
|
||
|
||
Не нужен в первый этап, если плагины ставятся вручную из локальной папки или из `verstak-official-plugins`.
|
||
|
||
### `verstak-docs`
|
||
|
||
Публичная документация:
|
||
|
||
- user guide;
|
||
- developer guide;
|
||
- plugin authoring guide;
|
||
- sync setup;
|
||
- security model;
|
||
- migration guides.
|
||
|
||
Может быть отдельным репозиторием позже. Сейчас допустимо держать архитектурные документы рядом с `verstak-desktop`.
|
||
|
||
## 4. Что не дробить слишком рано
|
||
|
||
Не стоит сразу создавать отдельный репозиторий на каждый официальный плагин. Это увеличит накладные расходы и усложнит синхронные изменения SDK/API.
|
||
|
||
Лучше:
|
||
|
||
```text
|
||
verstak-official-plugins - один repo для официальных плагинов
|
||
```
|
||
|
||
А отдельные repo оставить для сторонних плагинов или крупных независимых модулей.
|
||
|
||
## 5. Версионирование
|
||
|
||
Версии должны существовать на трех уровнях:
|
||
|
||
- app version: версия `verstak-desktop`;
|
||
- platform apiVersion: версия API плагинов;
|
||
- plugin version: версия конкретного плагина.
|
||
|
||
Плагин объявляет:
|
||
|
||
```json
|
||
{
|
||
"version": "0.1.0",
|
||
"apiVersion": "1"
|
||
}
|
||
```
|
||
|
||
Core может загрузить плагин только при совместимости `apiVersion`.
|
||
|