Files

vvzvlad d5cd1bba02 docs: add project spec and VS Code workspace

2026-06-16 18:30:04 +03:00

21 KiB

Raw Blame History

docmost-sync — ТЗ

Двусторонняя синхронизация статей Docmost с локальной папкой Markdown, где state store — git. Поменяли в Docmost → приехало в .md; поменяли .md → уехало в Docmost. История, базлайны и разрешение конфликтов берутся из git.

Статус: спецификация (design fixed). Реализации ещё нет.

1. Цель и границы

Цель: держать в файловой системе живую копию страниц Docmost в Markdown с непрерывной двусторонней синхронизацией тела страниц.
Что синхронизируется двусторонне: тело страницы (контент) + структура дерева (иерархия, перемещения, переименования) + удаления.
Что НЕ синхронизируется: комментарии — ни в какую сторону (см. §3).
Не входит в первую версию: права/ACL, версии истории Docmost как отдельная сущность, вложения как отдельный поток (едут как ссылки внутри контента), realtime-подписка (Фаза 3).

Опора на существующий код

Переиспользуем проект docmost-mcp (Node/TS) как библиотеку, НЕ как обязательный слой:

DocmostClient (логин, REST-вызовы) — основа клиента к Docmost;
lossless-конвертер convertProseMirrorToMarkdown / markdownToProseMirror;
collab-путь записи replacePageContent / mutatePageContent (Hocuspocus/Yjs).

Важно: MCP-инструменты — это тонкая обёртка над HTTP API Docmost. Синк-движок ходит в REST Docmost напрямую и волен использовать любые эндпойнты, которых нет в MCP (в частности — листинг корзины и restore, см. §8).

2. Как Docmost хранит контент (контекст)

Контент страницы — ProseMirror/TipTap JSON в колонке content (jsonb) таблицы pages. Его отдаёт REST POST /pages/info.
Параллельно живёт Yjs/CRDT бинарь (ydoc) — состояние совместного редактирования (Hocuspocus). content — это дебаунс-снимок ydoc.
Запись обратно делаем через collab/Yjs-канал, а не прямой перезаписью jsonb-колонки — чтобы CRDT и снимок оставались согласованными и параллельные правки людей не затирались.
Комментарии-треды лежат в отдельной таблице comments; внутри контента живут только марки-якоря (span[data-comment-id]).

3. Комментарии — не синкаются, только якоря

Синк-движок никогда не обращается к /comments — ни на чтение, ни на запись.
В синхронизируемом файле нет блока тредов. Остаются только инлайновые якоря <span data-comment-id="…">…</span> внутри тела — чтобы подсветки переживали round-trip и не терялись.
Это отличие от export_page_markdown в docmost-mcp (тот кладёт треды): синку нужен режим экспорта «тело + якоря, без comments-блока» (флаг includeCommentThreads: false).
Якоря — обычные марки внутри body. Если комментарий в Docmost удалили/resolved, марка меняется → это легитимное изменение тела, приедет на pull. Наверх такие вещи не пушим никогда (треды на сервере неприкосновенны).

4. Формат файла

Самодостаточный .md с кастомными Docmost-расширениями (как в markdown-document.ts из docmost-mcp, но без comments-блока):

<!-- docmost:meta
{"version":1,"pageId":"…","slugId":"…","title":"…","spaceId":"…","parentPageId":"…"}
-->

# Заголовок
Тело в Markdown с <span data-comment-id="abc">прокомментированным</span> куском,
диаграммами (<div data-type="drawio" …>), таблицами, callout'ами и т.д.

Метаблок — HTML-комментарий (его выкидывает marked, в документ не протекает).
pageId — стабильный якорь связи файл↔страница; по нему различаем move и delete.
Файл без pageId (новый файл от человека) → создать страницу, записать присвоенный pageId обратно в meta.
Опциональные sync-маркеры в meta (lastSyncedHash / lastSyncedUpdatedAt) — НЕ обязательны при git-модели: базлайн держит git (§5). Идентичность (pageId) — единственное, что обязано лежать в файле.

5. State store = git

Локальная папка — git-репозиторий. Базлайн, история, 3-way merge, rename-detection, тумбстоны удалений и перенос между машинами — всё из git.

Модель веток

main — то, что правит человек в ФС и куда вливаются изменения из Docmost.
docmost — зеркало текущего состояния Docmost; пишет только движок, руками не трогают (аналог origin/main).
merge-base(main, docmost) — последняя точка совпадения сторон. Это и есть state store; git ведёт её сам, отдельная БД базлайнов не нужна.
refs/docmost/last-pushed — маркер «что из main уже отражено в Docmost» (для направления ФС→Docmost).

Маппинг страница↔файл

По pageId из meta. Перемещения путей разруливает git rename-detection, сверяясь с pageId.
Дерево Docmost (parentPageId) зеркалится в папки: Space/Родитель/Дочерняя.md. Имя файла — из title (санитизация), но истина связи — pageId, не путь.

6. Циклы синхронизации (в терминах git)

Docmost → ФС (pull)

Изменилась страница (поллинг REST list_pages по updatedAt, позже — websocket) → export (тело + якоря, без комментариев) → запись файла на ветке docmost → commit docmost: update "Title" (pageId).
merge docmost → main: git делает настоящий 3-way merge от реального merge-base. Непересекающиеся правки сливаются сами; настоящее пересечение → конфликт-маркеры в файле (см. §9).
git push в remote.

ФС → Docmost (push)

Человек сохранил файл → (с дебаунсом) commit на main → git push.
diff main против refs/docmost/last-pushed → для каждого added/modified/deleted/renamed транслируем в:
- modified → import_page_markdown (через collab-путь);
- added (нет pageId) → create_page, записать pageId в meta;
- deleted → delete_page (в Trash, обратимо, §8);
- renamed/moved → move_page / rename_page.
Двигаем refs/docmost/last-pushed; фастфорвардим docmost (Docmost это уже содержит), записываем полученный updatedAt (§10).

7. Политика «push в репу после каждого изменения»

Коммит + git push в git-remote сразу после каждого устаканившегося изменения с любой стороны. Обязательные оговорки:

Дебаунс, а не на каждый keystroke. Коалесцировать быстрые правки за окно тишины (N секунд), иначе история и сеть захлёбываются. Docmost и сам отдаёт дебаунс-снимок, так что с его стороны это естественно.
Push = pull-rebase-push с ретраем. Если синкает больше одной машины — пуши в git-remote конкурируют (non-fast-forward); нужен цикл «подтянуть-перебазировать-запушить». Рекомендация: один авторитетный демон на воркспейс Docmost, чтобы не писать в Docmost вдвоём.
Провенанс в коммитах. Разные committer-identity / трейлеры для docmost: и local: — чтобы по истории была видна сторона и чтобы loop-guard отличал свою запись от чужой.

8. Удаления и перемещения

Docmost имеет Trash: delete_page → POST /pages/delete — это soft-delete (ставится deletedAt), страница лежит в корзине, восстанавливается, авто-чистка через ~30 дней. Значит удаления обратимы с обеих сторон.

Файл удалили локально → delete_page (уезжает в Trash, не в небытие).
- Удалять только отслеживаемые файлы (был pageId в meta) — чтобы глюк watcher'а / мусор не трактовался как удаление.
- Порог/подтверждение только на массовое удаление.
Страница в Trash в Docmost → локальный файл удаляется коммитом на main (восстановим из git-истории; опц. зеркалить в локальный .trash/).
Restore в Docmost (сбросился deletedAt) → файл возвращается.
Move vs delete различаем по pageId: страница со сменившимся parentPageId всё ещё присутствует → это move (двигаем файл), а не delete.

Детекция удалений со стороны Docmost

Не ограничиваемся MCP — ходим в REST напрямую к эндпойнту корзины/restore (тому, что дёргает фронт Docmost во вкладке Trash). Точный путь подтвердить из Network-таба UI или из исходников pages-контроллера (TODO §12). Тогда детекция — точный запрос к trash-API (видим deletedAt/restore), а не вывод «pageId пропал из активного дерева».

Симметрия двух корзин (git-история + Docmost Trash) делает синк удалений безопасным.

9. Конфликты: маркеры НИКОГДА не уезжают в Docmost

При merge-конфликте main↔docmost:

коммит с маркерами остаётся в git (бэкап на remote — ок);
push в Docmost для этой страницы блокируется до ручного разрешения;
конфликт показывается локально (git status / нотификация / conflict-копия);
в Docmost разблокируем push только после чистого резолва.

Почему маркеры нельзя пушить в Docmost

Docmost — структурированный, общий и живой источник правды, а не текстовый файл:

ProseMirror, не текст: <<<<<<</=======/>>>>>>> станут литеральными абзацами, видимыми всем читателям.
Дублирование: конфликт-блок несёт обе версии → в живой документ попадают оба противоречащих куска сразу.
Порча структуры: маркеры могут расколоть таблицу/callout/код-блок/ span-якорь комментария → битые ноды, потерянные якоря.
Laundering на round-trip: запушенные маркеры вернутся следующим export как «настоящий контент», другие могли поправить вокруг них — чисто разрешить уже нельзя.
Общий и живой: локальное приватное «я ещё не решил» не должно мгновенно протекать всем; до резолва в вики остаётся последний хороший контент.

Инвариант: в общий источник правды пишем только намеренные, разрешённые состояния — никогда «мы ещё не определились».

10. Предотвращение петель (loop-guard)

Свою же запись файла watcher не должен принимать за правку человека: сравнение хэша тела (не байтов файла) + провенанс коммита.
После push в Docmost записать полученный updatedAt, чтобы следующий поллинг не утянул собственную запись обратно как «удалённое изменение».
Изменение считается «новым», только если отличается от последнего синхронизированного коммита (git как референс).

11. Жёсткий пререквизит: идемпотентность round-trip

git диффает побайтово. Если export недетерминирован, каждый pull рожает ложный дифф → бесконечные коммиты/конфликты. До включения авто-двустороннего режима:

Block id'ы: markdownToProseMirror сейчас их регенерирует. Решить одним из: (а) вшивать block id'ы в md, либо (б) сравнивать нормализованную форму (ProseMirror JSON со снятыми id), а не сырые байты.
Нормализация Markdown: прогнать export → import → export на реальном контенте и добиться пустой разницы (whitespace, экранирование, хвостовые \n в код-блоках и т.п.).
Сравнение состояний синка делать по семантике (канонизированный контент), не по сырым байтам.

Это Задача №0 перед Фазой 2.

12. Безопасность и эксплуатация

git-remote = доступ ко всей вики. Защищать не слабее Docmost; токены Docmost / стейт с креденшелами в репу не коммитить (gitignore + внешний secret store).
Один авторитетный демон на воркспейс (см. §7.2).
Идемпотентность и возобновляемость: операции должны быть идемпотентны, повторный прогон синка — сходиться. При краше посреди push восстанавливаемся сверкой main / docmost / реального состояния Docmost.

Открытые вопросы / TODO

Точный REST-эндпойнт листинга корзины и restore в Docmost (§8).
Модель commit-attribution (отдельные identity vs трейлеры) (§7.3).
Эффективный «changes since T» для больших пространств (пагинация list_pages vs другой механизм).
Стратегия имён файлов при коллизиях title / спецсимволах.
Поведение при >30 днях офлайна (авто-чистка Trash затирает копию).

13. Компоненты (скелет)

git repo (vault): ветки main + docmost, ref refs/docmost/last-pushed.
Docmost→git: детектор изменений/трэша (REST напрямую) → export (тело+якоря) → commit на docmost → merge в main → push.
git→Docmost: FS-watcher (chokidar) + дебаунс → commit на main → push → diff против last-pushed → import/create/delete/move.
Conflict handler: маркеры в git, Docmost-push страницы на паузе, нотификация.
Loop-guard: подавление self-write (хэш тела + провенанс), запись updatedAt после push.
Converter: export_page_markdown(includeCommentThreads:false) / import_page_markdown из docmost-mcp.

Стек: Node/TS, переиспользование docmost-mcp (DocmostClient, конвертер, collab-write), chokidar (watch), прямой REST Docmost для корзины.

14. План по фазам

Фаза 0 — идемпотентность (§11). Стабильный детерминированный round-trip. Блокирует авто-двусторонний режим.
Фаза 1 — зеркало + ручной push (низкий риск). pull всего пространства в файлы по дереву (по pageId), ручной push правленых файлов, конфликт-копии, поллинг. Тело двусторонне в ручном режиме, комментарии read-only.
Фаза 2 — непрерывный двусторонний git-режим. Ветки main/docmost, merge-base как базлайн, FS-watcher + поллинг Docmost, commit+push после каждого устаканившегося изменения, conflict-gating, удаления через Trash + git.
Фаза 3 — realtime и доводка. Подписка на Hocuspocus вместо поллинга, git-история как UX конфликтов, опц. полная реконсиляция комментариев (если когда-нибудь понадобится — сейчас явно вне scope).

15. Зафиксированные решения (резюме)

State store = git: две ветки main/docmost, merge-base как базлайн.
Commit + push в git-remote после каждого устаканившегося изменения с обеих сторон (с дебаунсом, pull-rebase-push, один демон, провенанс).
Комментарии не синкаются ни в какую сторону; в файле — только якоря, без тредов; /comments не дёргается.
Конфликт-маркеры никогда не уезжают в Docmost; push конфликтной страницы блокируется до резолва.
Удаления — через Docmost Trash (soft, обратимо) + git-история; move/delete различаем по pageId; детекция трэша — прямым REST мимо MCP.
Запись в Docmost — через collab/Yjs-путь, не прямой перезаписью jsonb.
Идемпотентный round-trip — пререквизит (Задача №0) до авто-режима.

21 KiB Raw Blame History