9c6283aa8e
First slice of the push direction (SPEC §6), mirroring pull: VaultGit primitives + pure planner + thin injectable apply, exercised via fakes (no live destructive run). - git.ts: diffNameStatus (--name-status -M -z, NUL-parsed, rename-aware), revParse/readRef/updateRef (refs/docmost/last-pushed), showFileAtRef (recover a deleted file's pre-image pageId) - push.ts computePushActions (pure): A/M/D/R -> create/update/delete/renamesMoves; delete only when pageId is recovered from the pre-image, else skipped (§8 guard — no spurious Docmost delete) - push.ts applyPushActions (fakes): update via importPageMarkdown (collab/Yjs path, §2 — never a raw jsonb overwrite); create via createPage then write the assigned pageId back into the file meta (body preserved); delete via deletePage (soft, §8); renamesMoves deferred; advances last-pushed - tests (+26): diffNameStatus A/M/D/rename, ref round-trip, showFileAtRef; pure classification incl. §8 no-pageid skip; apply with fakes (collab-path update, pageid write-back, soft-delete, deferred moves) - 683 -> 709 green; build clean; corpus STABLE Deferred (next increment): move/rename apply, loop-guard (§10), watcher/debounce, remote push, live main wiring, empty-spaceId create guard, per-page error isolation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
docmost-sync
Bidirectional sync between Docmost articles and a local Markdown git vault — the
git repository is the state store. For the full design and the phased
implementation plan, see SPEC.md (the authoritative spec).
Status: Increment 1 — monorepo scaffold + read-only
pull+ Phase-0 round-trip harness. Continuous two-way sync is not implemented yet; see the phased plan inSPEC.md.
It reuses the sibling project docmost-mcp as a library: the DocmostClient
REST client and the lossless ProseMirror ↔ Markdown converter are extracted into
this monorepo (so changes can be backported file-by-file).
Layout
This is an npm-workspaces monorepo:
packages/docmost-client(docmost-client) — the Docmost REST client and itslib/(converter, markdown-document, collaboration, …). Its source layout mirrorsdocmost-mcp/src/1:1 so diffs can be backported by copying files. Sync-specific REST methods are added under clearly markeddocmost-sync additionsbanners.- the repo ROOT — the sync engine app (
src/,test/,build/,data/). It depends ondocmost-clientand holds the config (src/settings.ts), filename sanitization (src/sanitize.ts), the Phase-0 round-trip idempotency harness (src/roundtrip.ts), and the read-onlypull(src/pull.ts).
Install & build
Requires Node >= 20. For local (non-Docker) runs a system git binary must
also be on PATH — the vault state store shells out to it for every operation
(the daemon fails fast at startup if git is missing).
npm install # links the workspace packages
npm run build # builds docmost-client, then compiles the app into build/
docmost-client must build before the app (the app consumes its built output);
the root build script builds the lib first, then runs tsc.
Configuration
Copy .env.example to .env and fill in real values. The
config is read through src/settings.ts.
| Variable | Required | Meaning |
|---|---|---|
DOCMOST_API_URL |
yes | Base URL of our Docmost instance. |
DOCMOST_EMAIL |
yes | Docmost service-user login email. |
DOCMOST_PASSWORD |
yes | Docmost service-user login password. |
DOCMOST_SPACE_ID |
yes | Which Docmost space to mirror. |
VAULT_PATH |
no | Local vault directory (default data/vault). |
GIT_REMOTE |
no | Optional git remote the vault pushes to. |
POLL_INTERVAL_MS |
no | Poll interval in ms (default 15000). |
DEBOUNCE_MS |
no | Debounce window in ms (default 2000). |
LOG_LEVEL |
no | debug | info | warn | error (default info). |
Real secrets go in .env, which is git-ignored — never commit them. The
git remote grants access to the whole vault, so protect it no less than Docmost
itself (SPEC §12).
Running
Round-trip idempotency harness (Phase 0, SPEC §11)
Verifies that export → import → export is byte-stable. Runs offline against a
fixture (the default for CI) — no Docmost credentials needed:
npm run build
node build/roundtrip.js --fixture test/fixtures/sample-doc.json
Or against a live page (needs .env):
node build/roundtrip.js --page <pageId>
Exit code is 0 when the markdown is byte-stable, 1 on a markdown divergence (CI-able). A document-level divergence after stripping block ids is a known SPEC §11 finding and does not fail the run.
Pull (Docmost → filesystem mirror, SPEC §6)
Read-only mirror: walks the configured space's page tree and writes one .md
per page under <VAULT_PATH>/<…ancestors>/<Title>.md. Requires a .env with
real Docmost credentials — it makes live REST calls and does not touch Docmost
state (read-only this increment):
npm run pull