gitmost/docs/backlog/git-sync-thin-meta.md

git-sync: native-Obsidian vault format

Статус: дизайн (согласован с владельцем 2026-06-24), к реализации.

Цель

Волт спейса должен быть настоящим Obsidian-волтом: владелец открывает папку в Obsidian (с плагином Folder Notes) и получает ровно ту же структуру страниц, не замечая разницы. Никаких служебных артефактов, которые бы выглядели чужеродно. Сторонние редакторы кладут «голые» файлы/папки — движок их адоптирует в страницы Docmost.

Сейчас каждый .md несёт жирный <!-- docmost:meta {…} --> блок — это уезжает.

Формат

<Space-vault>/
  Заметка.md              # лист: чистый markdown + frontmatter id
  Проект/                 # страница-родитель = ПАПКА
    Проект.md             # folder-note: ТЕЛО самой страницы «Проект»
    Задача.md             # ребёнок
    Подпроект/
      Подпроект.md        # тело «Подпроект»
      ...
  .obsidian/              # конфиг Obsidian — движок НЕ ТРОГАЕТ

Каждый файл страницы:

---
gitmost_id: 019ef6fc-2638-7ce1-9ce3-2756ce038480
---
<чистый markdown — тело страницы (wiki-ссылки, всё как в Obsidian)>

• Лист (нет детей) → <title>.md.
• Родитель (есть дети) → папка <title>/, его тело в <title>/<title>.md (folder-note по конвенции плагина LostPaul Folder Notes — заметка с именем папки внутри неё). Лист, у которого появился первый ребёнок, превращается из <title>.md в <title>/<title>.md (безопасный move по id).
• title = имя файла (для папки — имя папки). parentPageId = ближайшая родительская папка (её folder-note). spaceId = эта репа. Всё выводимо.
• Идентичность — gitmost_id (= Docmost pageId) во frontmatter. Невыводима, едет ВМЕСТЕ с файлом → переживает любой move, даже не распознанный git как rename. (Ключ namespaced gitmost_id, не голый id, чтобы не конфликтовать с пользовательскими frontmatter-полями. Имя ключа — последнее на подтверждении.)
• Коллизии имён (2+ сиблинга с одним title): как делает сам Obsidian — добавляем натуральный суффикс 2, 3. id во frontmatter, так что имя файла чисто косметическое; смена суффикса — безопасный rename (идентичность по id).

Никакого .gitmost/index.json (сайдкар отвергнут: path-keyed индекс хрупок к rename; id во frontmatter самодостаточен). Никаких docmost:meta/docmost:comments блоков (комменты и так живут инлайн-марками <span data-comment-id> в теле).

Ссылки между заметками ([[wikilinks]])

Obsidian резолвит [[Заметка]] по basename (не по полному пути), нормализуя пробелы/-/_, с приоритетом короткого пути при неоднозначности.

• В Docmost ссылки — по pageId (mention/reference node), rename переживают.
• В волте — обсидиановские [[basename]].
• Следствие: reparent (смена папки) ссылку НЕ ломает (basename тот же), ломает только retitle. Значит переписывать [[…]] надо только при смене имени страницы — узкий случай. (Obsidian сам умеет «update links on rename».)
• Конвертер Docmost-mention ↔ [[wikilink]] (обе стороны) + переписывание при retitle — отдельная фаза (см. план), не блокирует формат.

PULL (Docmost → vault)

1. Прочитать дерево спейса.
2. Layout: лист→<t>.md, родитель→<t>/<t>.md, коллизии→ 2/ 3.
3. Записать ---\ngitmost_id: …\n---\n<тело> (чистый markdown).
4. Переехавшие файлы — move (по id), не delete.
5. Коммит на docmost, merge в main.

PUSH (vault → Docmost)

1. Дифф last-pushed..main.
2. Идентичность файла — из frontmatter gitmost_id. Родитель — из пути (folder-note родительской папки).
3. Классификация:
   • есть gitmost_id в дереве → update/move/rename по id (страховка 5133bb34).
   • нет id (новый голый файл от Obsidian) → adopt: create page (title=имя, parent=папка), дописать gitmost_id во frontmatter.
   • голая папка с детьми без folder-note → создать страницу-родитель, завести <folder>/<folder>.md.
   • файл пропал, а id ещё в дереве под другим путём → move. Реально пропал → delete (под delete-cap).

Адопция (третья-сторона → Docmost)

• голый .md без frontmatter id → create page.
• голая папка с .md внутри без folder-note → create страницу-родитель + folder-note.
• .obsidian/, аттачменты, dot-файлы, любые не-.md → игнор (не страницы), лежат в гите как есть, Obsidian ими владеет. Без .gitignore.

Миграция со старого формата

Существующие волты несут docmost:meta в файлах.

• На первом цикле нового движка: если у файла нет frontmatter, но есть docmost:meta → читаем pageId оттуда, переписываем файл в native-формат (frontmatter id + чистое тело + folder-note layout), разовый «normalize» коммит.
• Фолбэк навсегда: docmost:meta всё ещё парсится как источник id, если frontmatter нет (файл со старой системы). (Реализовано в parsePageFile.)

Краевые случаи

• Git не хранит пустые папки → «родитель без своего файла» невозможен: тело родителя — это folder-note <t>/<t>.md, он и держит папку (плюс дети). Childless пустая страница → просто <t>.md.
• Конфликт folder-note Папка/Папка.md с ребёнком title «Папка» → ребёнку суффикс.
• Переименование папки (= rename родителя) → move всего поддерева по id, без delete+create; ссылки [[…]] на сам родитель переписать (basename сменился).

План фаз (каждая — юниты движка + браузерный e2e + изолированные shell-e2e)

1. ✅ Формат файла: parsePageFile/serializePageFile (frontmatter id + тело, фолбэк на legacy docmost:meta). Юниты. Без смены поведения. (готово)
2. PULL пишет native-формат (frontmatter + folder-note layout) + миграция.
3. PUSH берёт идентичность из frontmatter, родителя из пути.
4. Адопция голых файлов/папок.
5. Чистка: убрать docmost:meta из генерации (оставить фолбэк-парсер).
6. Ссылки: конвертер Docmost-mention ↔ [[wikilink]] + переписывание при retitle.

Риски

Смена ФОРМАТА волта на data-loss-чувствительном движке (сегодня ловили тяжёлый баг с трашем живых страниц). Каждая фаза — за инкрементом, с юнит-тестами движка И браузерным e2e (git-sync-browser-e2e.cjs) + изолированными shell-e2e на одноразовом спейсе. Без in-place миграций без бэкапа волта.