refactor(git-sync): internalize the engine — first-class ESM, no vendoring bridge (#119 review)

Closes the architecture item from the #119 review: drop the "vendored from
docmost-sync" framing and the CJS↔ESM `Function('import()')` bridge so the engine
is a normal first-class gitmost package.

Part 1 — vendoring markers removed (prose only, zero behavior change): reworded
"VENDORED into gitmost" / "vendored from docmost-sync" / "Engine LOGIC is
byte-identical" / "it's a port" comments across the engine. Behavior-bearing
strings are untouched: BOT_AUTHOR_NAME/EMAIL and the `Docmost-Sync-Source:`
provenance trailers (changing them would break git authorship + the loop-guard).

Part 2 — the package is now ESM (matching the sibling @docmost/mcp): `type: module`,
tsconfig Node16, `.js` extensions on relative imports, and a static
`import { marked }` replacing the `new Function('return import(...)')` /
`loadMarked` hack — the bridge is GONE from the package. The CommonJS NestJS
server loads the now-ESM engine via a new `git-sync.loader.ts` that mirrors the
existing `docmost-client.loader.ts` mcp loader exactly (Function-indirected
dynamic import + cached promise + retry-on-reject). The 4 server consumers
(orchestrator/datasource/vault-registry/git-http-backend) call `await loadGitSync()`
for value exports; types stay `import type` (erased). The converter-gate spec —
which needs the real converter — loads the package's TS source via a jest
moduleNameMapper + isolatedModules (documented in that spec); the other git-sync
specs mock the loader.

Verified: engine builds pure ESM (no Function/require leftover), vitest 614,
editor-ext build, server + client tsc, full server jest 1397/0. Live stand
smoke-test: server starts clean on the ESM engine (no ERR_REQUIRE_ESM), a real
sync cycle runs through the loader, and the basic e2e suite is 12/12 (clone via
git-http-backend, push, pull, delete, 3-way merge — all through the new loader).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

apps/server/package.json

@@ -189,7 +189,12 @@
           ]
         }
       ],
-      "^.+\\.(t|j)sx?$": "ts-jest"
+      "^.+\\.(t|j)sx?$": [
+        "ts-jest",
+        {
+          "isolatedModules": true
+        }
+      ]
     },
     "transformIgnorePatterns": [
       "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom|lib0)(@|/))"
@@ -206,7 +211,10 @@
       "^@docmost/db/(.*)$": "<rootDir>/database/$1",
       "^@docmost/transactional/(.*)$": "<rootDir>/integrations/transactional/$1",
       "^@docmost/ee/(.*)$": "<rootDir>/ee/$1",
-      "^src/(.*)$": "<rootDir>/$1"
+      "^src/(.*)$": "<rootDir>/$1",
+      "^@docmost/git-sync$": "<rootDir>/../../../packages/git-sync/src/index.ts",
+      "^@docmost/git-sync/(.*)$": "<rootDir>/../../../packages/git-sync/src/$1",
+      "^(\\.{1,2}/.*)\\.js$": "$1"
     }
   }
 }

apps/server/src/collaboration/git-sync-converter-gate.spec.ts

@@ -1,7 +1,17 @@
 /**
+ * JEST CONFIG NOTE (#119 ESM refactor): this is the one spec that needs the REAL
+ * `@docmost/git-sync` converter (not a mock). The package is now ESM, which jest
+ * cannot `require()` nor `import()` without --experimental-vm-modules, so the
+ * server jest config `moduleNameMapper`s `@docmost/git-sync` to its TS SOURCE and
+ * strips the ESM `.js` import suffixes. ts-jest then type-checks that source under
+ * the server's (looser) tsconfig and trips a benign narrowing; the global
+ * `isolatedModules: true` on the ts-jest transform (apps/server/package.json)
+ * makes it transpile-only so this spec loads. Full type-checking of the package
+ * is still enforced by its own `tsc`/vitest gates and the server `tsc --noEmit`.
+ *
  * §13.1 IDEMPOTENCY GATE — the blocking gate for git-sync Phase B.
  *
- * Proves the vendored `@docmost/git-sync` pure converter is schema-compatible
+ * Proves the `@docmost/git-sync` pure converter is schema-compatible
  * with the server's REAL editor-ext document schema: a representative corpus of
  * editor-ext ProseMirror documents must survive a full round trip through the
  * actual server write path without losing any node / mark / attribute.
@@ -19,7 +29,7 @@
  *      validation that runs on a git-sync write (plan §3.3).
  *   4. assert docsCanonicallyEqual(canon(original), canon(normalized)) === true
  *
- * Any node / mark / attr that editor-ext drops (because the vendored
+ * Any node / mark / attr that editor-ext drops (because the git-sync
  * docmost-schema named it differently, or declares a different default) makes
  * the gate FAIL for that document — exactly the schema-divergence plan §3.3 /
  * §13.1 warn about. Genuine, irreducible divergences are isolated into the
@@ -31,9 +41,11 @@
  */
 import { TiptapTransformer } from '@hocuspocus/transformer';
 // Import the server's real schema FIRST so `@docmost/editor-ext` resolves to its
-// built CJS `dist` (its `main`). Importing the ESM `@docmost/git-sync` package
+// built CJS `dist` (its `main`). The ESM-only `@docmost/git-sync` package is
-// first flips jest's resolver to editor-ext's `module` (src) field, which then
+// mapped to its TS SOURCE by the jest `moduleNameMapper` (the built ESM cannot
-// drags in React node views (navigator-less) and breaks the node test env.
+// be `require()`d nor dynamically `import()`ed under jest's node VM), so ts-jest
+// transpiles the real converter to CJS here — exercising the actual converter
+// the server ships, not a stub.
 import { tiptapExtensions } from './collaboration.util';
 import {
   convertProseMirrorToMarkdown,

apps/server/src/integrations/git-sync/git-sync.loader.ts

@@ -0,0 +1,59 @@
+import { pathToFileURL } from 'node:url';
+import type {
+  VaultGit as VaultGitClass,
+  vaultGitEnv as vaultGitEnvFn,
+  runCycle as runCycleFn,
+  parseDocmostMarkdown as parseDocmostMarkdownFn,
+  markdownToProseMirror as markdownToProseMirrorFn,
+} from '@docmost/git-sync';
+
+/**
+ * Runtime value-export surface of the ESM-only `@docmost/git-sync` package that
+ * the server consumes. Types are imported with `import type` (erased at compile,
+ * no runtime require); only the VALUE exports below need the dynamic-load
+ * treatment so a CJS `require()` of the ESM package never happens.
+ */
+interface GitSyncModule {
+  VaultGit: typeof VaultGitClass;
+  vaultGitEnv: typeof vaultGitEnvFn;
+  runCycle: typeof runCycleFn;
+  parseDocmostMarkdown: typeof parseDocmostMarkdownFn;
+  markdownToProseMirror: typeof markdownToProseMirrorFn;
+}
+
+// TS with module:commonjs downlevels a literal `import()` to `require()`, which
+// cannot load the ESM-only `@docmost/git-sync` package. Indirect through
+// Function so the real dynamic `import()` survives compilation and can load ESM
+// from CommonJS at runtime (same trick as
+// apps/server/src/core/ai-chat/tools/docmost-client.loader.ts and
+// integrations/mcp/mcp.service.ts).
+const esmImport = new Function(
+  'specifier',
+  'return import(specifier)',
+) as (specifier: string) => Promise<unknown>;
+
+// Memoize the in-flight/loaded module so the dynamic import runs at most once.
+let modulePromise: Promise<GitSyncModule> | null = null;
+
+/**
+ * Lazily load the ESM-only `@docmost/git-sync` package (cached). Resolves the
+ * package entry to an absolute path, then imports it as a `file://` URL so the
+ * package "exports" map is honoured without bare-specifier resolution-base
+ * fragility.
+ */
+export async function loadGitSync(): Promise<GitSyncModule> {
+  if (!modulePromise) {
+    modulePromise = (async () => {
+      const entry = require.resolve('@docmost/git-sync');
+      const mod = (await esmImport(
+        pathToFileURL(entry).href,
+      )) as GitSyncModule;
+      return mod;
+    })().catch((err) => {
+      // Do not cache a rejected import — allow the next call to retry.
+      modulePromise = null;
+      throw err;
+    });
+  }
+  return modulePromise;
+}

apps/server/src/integrations/git-sync/http/git-http-backend.service.spec.ts

@@ -8,9 +8,13 @@ import { spawn } from 'node:child_process';
 // fake child lets us drive every stdout/stderr/error/close branch by hand.
 jest.mock('node:child_process', () => ({ spawn: jest.fn() }));
 // vaultGitEnv just builds the CGI env overlay; stub it to a passthrough so the
-// service constructs without the real engine.
+// service runs without the real engine. The service loads it at runtime via the
-jest.mock('@docmost/git-sync', () => ({
+// `loadGitSync()` bridge (the ESM `@docmost/git-sync` package cannot be
+// `require()`d under jest), so we mock that loader rather than the package.
+jest.mock('../git-sync.loader', () => ({
+  loadGitSync: jest.fn(async () => ({
     vaultGitEnv: (overlay: Record<string, string>) => overlay,
+  })),
 }));
 
 import {
@@ -81,6 +85,12 @@ function buildService() {
   return new GitHttpBackendService(env as any);
 }
 
+// `run()` now awaits the async `loadGitSync()` bridge before it spawns the
+// child, so the spawn (and its stream-handler wiring) happens one microtask
+// after `run()` is called. These tests drive the fake child synchronously, so
+// flush the microtask queue first to let `run()` reach the spawn.
+const flush = () => new Promise((resolve) => setImmediate(resolve));
+
 describe('GitHttpBackendService.run', () => {
   beforeEach(() => {
     spawnMock.mockReset();
@@ -96,6 +106,7 @@ describe('GitHttpBackendService.run', () => {
     const res = fakeRes();
 
     const p = service.run(baseRequest, fakeReq(), res);
+    await flush();
     // Emit a child 'error' before any stdout -> 500, headers not already sent.
     child.emit('error', new Error('ENOENT spawn git'));
     await p;
@@ -112,6 +123,7 @@ describe('GitHttpBackendService.run', () => {
     const res = fakeRes();
 
     const p = service.run(baseRequest, fakeReq(), res);
+    await flush();
     // stderr diagnostics, then a close with no valid CGI output -> 500.
     child.stderr.emit('data', Buffer.from('fatal: boom'));
     child.emit('close', 128);
@@ -128,6 +140,7 @@ describe('GitHttpBackendService.run', () => {
     const res = fakeRes();
 
     const p = service.run(baseRequest, fakeReq(), res);
+    await flush();
     // A full CGI response: status line + header + blank line + body.
     child.stdout.emit(
       'data',
@@ -157,6 +170,7 @@ describe('GitHttpBackendService.run', () => {
     const warnSpy = jest.spyOn(Logger.prototype, 'warn');
 
     const p = service.run(baseRequest, fakeReq(), res);
+    await flush();
     // The stdout 'error' handler must absorb this — no unhandled throw, no 500.
     expect(() => child.stdout.emit('error', new Error('EPIPE'))).not.toThrow();
     expect(() => child.stderr.emit('error', new Error('EPIPE'))).not.toThrow();

apps/server/src/integrations/git-sync/http/git-http-backend.service.ts

@@ -1,7 +1,7 @@
 import { Injectable, Logger } from '@nestjs/common';
 import { spawn } from 'node:child_process';
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import { vaultGitEnv } from '@docmost/git-sync';
+import { loadGitSync } from '../git-sync.loader';
 import { EnvironmentService } from '../../environment/environment.service';
 
 /** The parsed first part of a CGI response: the HTTP status + header pairs. */
@@ -152,6 +152,7 @@ export class GitHttpBackendService {
     rawReq: IncomingMessage,
     rawRes: ServerResponse,
   ): Promise<void> {
+    const { vaultGitEnv } = await loadGitSync();
     const projectRoot = this.environmentService.getGitSyncDataDir();
     // Build the CGI env from the engine's cwd-isolated base (strips GIT_DIR /
     // GIT_WORK_TREE), then layer the http-backend CGI variables. PATH is

apps/server/src/integrations/git-sync/services/git-sync.orchestrator.spec.ts

@@ -1,4 +1,4 @@
-// Unit tests for the git-sync control plane. The vendored engine's `runCycle`
+// Unit tests for the git-sync control plane. The engine's `runCycle`
 // (which owns the PULL->PUSH branch choreography) is mocked so we exercise ONLY
 // the orchestrator's wiring: gating, the Redis leader lock + in-process mutex
 // (via SpaceLockService), the delete-cap POLICY it injects as `resolveApplyClient`,
@@ -7,13 +7,18 @@
 // mechanics themselves are covered by the engine's own cycle round-trip spec.
 //
 // The engine mock must be declared before importing the orchestrator so the
-// module-graph import binds to the mocked function.
+// runtime `loadGitSync()` bridge resolves to the mocked `runCycle` (the ESM
-jest.mock('@docmost/git-sync', () => ({
+// `@docmost/git-sync` package cannot be `require()`d under jest). The `mock`
-  runCycle: jest.fn(),
+// prefix lets the hoisted factory reference it.
+const mockRunCycle = jest.fn();
+
+jest.mock('../git-sync.loader', () => ({
+  loadGitSync: jest.fn(async () => ({
+    runCycle: mockRunCycle,
+  })),
 }));
 
 import { Logger } from '@nestjs/common';
-import { runCycle } from '@docmost/git-sync';
 import {
   GitSyncOrchestrator,
   GitSyncLockHeldError,
@@ -22,7 +27,7 @@ import { SpaceLockService } from './space-lock.service';
 
 type AnyMock = jest.Mock;
 
-const runCycleMock = runCycle as unknown as AnyMock;
+const runCycleMock = mockRunCycle as unknown as AnyMock;
 
 /** The default happy-path cycle result the engine returns. */
 const OK_CYCLE = {

apps/server/src/integrations/git-sync/services/git-sync.orchestrator.ts

@@ -9,7 +9,8 @@ import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB } from '@docmost/db/types/kysely.types';
 import { sql } from 'kysely';
-import { type Settings, runCycle } from '@docmost/git-sync';
+import type { Settings } from '@docmost/git-sync';
+import { loadGitSync } from '../git-sync.loader';
 import { EnvironmentService } from '../../environment/environment.service';
 import { GitmostDataSourceService } from './gitmost-datasource.service';
 import { VaultRegistryService } from './vault-registry.service';
@@ -246,6 +247,7 @@ export class GitSyncOrchestrator implements OnModuleInit, OnModuleDestroy {
     workspaceId: string,
     serviceUserId: string,
   ): Promise<GitSyncRunStatus> {
+    const { runCycle } = await loadGitSync();
     const settings = this.buildSettings(spaceId);
     const vault = await this.vaultRegistry.getVault(spaceId);
     const client = this.dataSource.bind({ workspaceId, userId: serviceUserId });

apps/server/src/integrations/git-sync/services/gitmost-datasource.service.spec.ts

@@ -30,6 +30,21 @@ jest.mock('@hocuspocus/transformer', () => {
 jest.mock('@docmost/editor-ext', () => ({
   markdownToHtml: jest.fn(),
 }));
+// The service loads `parseDocmostMarkdown` / `markdownToProseMirror` at runtime
+// via the `loadGitSync()` bridge (the ESM `@docmost/git-sync` package cannot be
+// `require()`d under jest). Stub the loader: the real conversion is exercised by
+// the @docmost/git-sync converter tests and the converter gate; here the mocked
+// TiptapTransformer.toYdoc ignores the converted doc anyway, so a passthrough
+// body + a minimal ProseMirror doc is sufficient.
+jest.mock('../git-sync.loader', () => ({
+  loadGitSync: jest.fn(async () => ({
+    parseDocmostMarkdown: (md: string) => ({ meta: {}, body: md }),
+    markdownToProseMirror: async () => ({
+      type: 'doc',
+      content: [{ type: 'paragraph' }],
+    }),
+  })),
+}));
 
 import * as Y from 'yjs';
 import { GitmostDataSourceService } from './gitmost-datasource.service';

apps/server/src/integrations/git-sync/services/gitmost-datasource.service.ts

@@ -1,12 +1,11 @@
 import { Injectable, Logger, NotFoundException } from '@nestjs/common';
 import { TiptapTransformer } from '@hocuspocus/transformer';
 import { generateJitteredKeyBetween } from 'fractional-indexing-jittered';
-import {
+import type {
-  type GitSyncClient,
+  GitSyncClient,
-  type GitSyncPageNodeLite,
+  GitSyncPageNodeLite,
-  parseDocmostMarkdown,
-  markdownToProseMirror,
 } from '@docmost/git-sync';
+import { loadGitSync } from '../git-sync.loader';
 import { PageRepo } from '@docmost/db/repos/page/page.repo';
 import { SpaceRepo } from '@docmost/db/repos/space/space.repo';
 import { InjectKysely } from 'nestjs-kysely';
@@ -177,6 +176,7 @@ export class GitmostDataSourceService {
     fullMarkdown: string,
     baseMarkdown?: string | null,
   ): Promise<{ updatedAt?: string }> {
+    const { parseDocmostMarkdown, markdownToProseMirror } = await loadGitSync();
     const { body } = parseDocmostMarkdown(fullMarkdown);
     const doc = await markdownToProseMirror(body);
 
@@ -213,6 +213,7 @@ export class GitmostDataSourceService {
     );
 
     // The shell is created without body; push the markdown body through collab.
+    const { parseDocmostMarkdown, markdownToProseMirror } = await loadGitSync();
     const { body } = parseDocmostMarkdown(content);
     const doc = await markdownToProseMirror(body);
     await this.writeBody(page.id, doc, ctx.userId);

apps/server/src/integrations/git-sync/services/vault-registry.service.spec.ts

@@ -1,17 +1,30 @@
 // Unit tests for the per-space vault path resolver + lazy VaultGit cache
-// `mkdir` and `VaultGit` are mocked so construction is cheap and
+// `mkdir` and the git-sync loader are mocked so construction is cheap and
 // no real filesystem / git work happens. We assert the path normalization
 // (trailing slash) and the one-VaultGit-per-space caching contract.
+//
+// The service loads `VaultGit` (and `vaultGitEnv`) at runtime via the
+// `loadGitSync()` bridge (the ESM `@docmost/git-sync` package cannot be
+// `require()`d under jest), so we mock that loader rather than the package.
 import { mkdir } from 'node:fs/promises';
-import { VaultGit } from '@docmost/git-sync';
+import { loadGitSync } from '../git-sync.loader';
 
 jest.mock('node:fs/promises', () => ({
   mkdir: jest.fn(async () => undefined),
 }));
 
 // Cheap VaultGit stub: records the path it was constructed with; no shell-out.
-jest.mock('@docmost/git-sync', () => ({
+// Declared with a `mock`-prefixed name so jest allows referencing it inside the
-  VaultGit: jest.fn().mockImplementation((path: string) => ({ path })),
+// hoisted `jest.mock` factory below.
+const mockVaultGit = jest
+  .fn()
+  .mockImplementation((path: string) => ({ path }));
+
+jest.mock('../git-sync.loader', () => ({
+  loadGitSync: jest.fn(async () => ({
+    VaultGit: mockVaultGit,
+    vaultGitEnv: jest.fn(() => ({})),
+  })),
 }));
 
 import { VaultRegistryService } from './vault-registry.service';
@@ -19,7 +32,8 @@ import { VaultRegistryService } from './vault-registry.service';
 type AnyMock = jest.Mock;
 
 const mkdirMock = mkdir as unknown as AnyMock;
-const VaultGitMock = VaultGit as unknown as AnyMock;
+const VaultGitMock = mockVaultGit;
+void loadGitSync;
 
 function build(dataDir: string): { service: VaultRegistryService } {
   const env = {

apps/server/src/integrations/git-sync/services/vault-registry.service.ts

@@ -2,7 +2,8 @@ import { Injectable, Logger } from '@nestjs/common';
 import { mkdir } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { VaultGit, vaultGitEnv } from '@docmost/git-sync';
+import type { VaultGit } from '@docmost/git-sync';
+import { loadGitSync } from '../git-sync.loader';
 import { EnvironmentService } from '../../environment/environment.service';
 
 const execFileAsync = promisify(execFile);
@@ -41,6 +42,7 @@ export class VaultRegistryService {
 
     const path = this.vaultPath(spaceId);
     await mkdir(path, { recursive: true });
+    const { VaultGit } = await loadGitSync();
     const vault = new VaultGit(path);
     this.vaults.set(spaceId, vault);
     return vault;
@@ -66,6 +68,7 @@ export class VaultRegistryService {
    * every request.
    */
   async ensureServable(spaceId: string): Promise<string> {
+    const { vaultGitEnv } = await loadGitSync();
     const vault = await this.getVault(spaceId);
     const path = this.vaultPath(spaceId);
 

packages/git-sync/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@docmost/git-sync",
   "version": "0.1.0",
-  "description": "Vendored pure converter + pure sync engine for the Docmost <-> git Markdown sync (Phase A). See docs/git-sync-plan.md.",
+  "description": "Pure converter + pure sync engine for the Docmost <-> git Markdown sync. See docs/git-sync-plan.md.",
   "private": true,
+  "type": "module",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
   "exports": {

packages/git-sync/src/engine/client.types.ts

@@ -1,24 +1,21 @@
 /**
- * The client seam. Upstream `pull.ts`/`push.ts` reached into the
+ * The client seam. `pull.ts`/`push.ts` depend on a narrow STRUCTURAL interface
- * REST `DocmostClient` from the `docmost-client` package via `Pick<DocmostClient,
+ * rather than any concrete client, because the gitmost server writes NATIVELY —
- * ...>` subsets. That package is NOT vendored here (the gitmost server writes
+ * through repositories + collab `openDirectConnection`.
- * NATIVELY — through repositories + collab `openDirectConnection`),
- * so the engine must depend on a narrow STRUCTURAL interface instead.
  *
- * `GitSyncClient` is that interface: the native datasource (server side, a later
+ * `GitSyncClient` is that interface: the native datasource (server side)
- * step) implements it, and the vendored engine only ever uses `Pick<GitSyncClient,
+ * implements it, and the engine only ever uses `Pick<GitSyncClient, ...>`
- * ...>` subsets of it. The signatures below MIRROR exactly the methods the
+ * subsets of it. The signatures below MIRROR exactly the methods the engine's
- * vendored `pull.ts`/`push.ts` actually call (arg shapes + the fields the engine
+ * `pull.ts`/`push.ts` actually call (arg shapes + the fields the engine reads
- * reads off each result) — verified against the upstream `DocmostClient`
+ * off each result), so a REST-style client is still structurally assignable and
- * (packages/docmost-client/src/client.ts) so a real REST client is still
+ * the native adapter has a precise contract.
- * structurally assignable, and so the native adapter has a precise contract.
  */
 
 /**
  * A page node as returned by `listSpaceTree` (the sidebar/tree walk, no body).
  * The engine layout (`buildVaultLayout`) consumes `PageNode` from `./layout`,
  * which only requires `id` (+ optional `title`/`slugId`/`parentPageId`); this
- * lite shape documents the fields the tree walk surfaces. Upstream nodes also
+ * lite shape documents the fields the tree walk surfaces. Real tree nodes also
  * carry `position`, `icon`, `hasChildren` — kept open via the index signature.
  */
 export interface GitSyncPageNodeLite {
@@ -27,7 +24,7 @@ export interface GitSyncPageNodeLite {
   title?: string;
   parentPageId?: string | null;
   hasChildren?: boolean;
-  /** Upstream `listSpaceTree` nodes carry extra fields (position, icon, …). */
+  /** `listSpaceTree` nodes carry extra fields (position, icon, …). */
   [key: string]: unknown;
 }
 

packages/git-sync/src/engine/cycle.ts

@@ -1,8 +1,8 @@
-import { VaultGit } from "./git";
+import { VaultGit } from "./git.js";
-import { GitSyncClient } from "./client.types";
+import { GitSyncClient } from "./client.types.js";
-import { Settings } from "./settings";
+import { Settings } from "./settings.js";
-import { readExisting, computePullActions, applyPullActions } from "./pull";
+import { readExisting, computePullActions, applyPullActions } from "./pull.js";
-import { runPush } from "./push";
+import { runPush } from "./push.js";
 
 /**
  * Absolute-path filesystem primitives the cycle needs. Injected (not imported)

packages/git-sync/src/engine/git.ts

@@ -3,11 +3,10 @@
  *
  * IMPORTANT — VAULT-SCOPED: every operation here runs with `cwd = vaultPath`,
  * which is the vault's OWN git repository (default `data/vault`), SEPARATE from
- * the docmost-sync source repo. This module MUST NEVER run git against the
+ * the gitmost application repo. This module MUST NEVER run git against the
- * source repo. `data/` is gitignored by the source repo, so a nested repo under
+ * application repo. `data/` is gitignored, so a nested repo under `data/vault`
- * `data/vault` is safe. The pull cycle is READ-ONLY toward Docmost; this module
+ * is safe. The pull cycle is READ-ONLY toward Docmost; this module only touches
- * only touches the local vault git, never a git remote (push is deferred, see
+ * the local vault git, never a git remote (push is deferred, see SPEC §7).
- * SPEC §7).
  *
  * Implementation notes:
  *   - We shell out via `node:child_process` `execFile` (promisified), passing

packages/git-sync/src/engine/layout.ts

@@ -10,7 +10,7 @@
  * lives in each file's meta block (pageId / slugId).
  */
 
-import { sanitizeTitle, disambiguate } from "./sanitize";
+import { sanitizeTitle, disambiguate } from "./sanitize.js";
 
 /** Flat page node as returned by `listAllSpacePages` (no content). */
 export interface PageNode {

packages/git-sync/src/engine/pull.ts

@@ -25,30 +25,29 @@
  * (read-only: listSpaceTree + getPageJson). All git operations run against
  * the vault repo (`cwd = vaultPath`), never the source repo (see ./git.ts).
  *
- * VENDORED into gitmost: the client seam is the native
+ * The client seam is the native `GitSyncClient` (`Pick<GitSyncClient, ...>`);
- * `GitSyncClient` (`Pick<GitSyncClient, ...>`), not the upstream REST
+ * the gitmost server drives the engine in-process (there is no standalone CLI
- * `DocmostClient`; the upstream CLI `main()` entry point is dropped (the gitmost
+ * entry point).
- * server drives the engine in-process). Engine LOGIC is byte-identical.
  */
 import { dirname } from "node:path";
 import { sep } from "node:path";
-import { parsePageFile, serializePageFile } from "../lib/page-file";
+import { parsePageFile, serializePageFile } from "../lib/page-file.js";
-import type { GitSyncClient } from "./client.types";
+import type { GitSyncClient } from "./client.types.js";
-import { buildVaultLayout, type PageNode } from "./layout";
+import { buildVaultLayout, type PageNode } from "./layout.js";
 import {
   VaultGit,
   BOT_AUTHOR_NAME,
   BOT_AUTHOR_EMAIL,
   DEFAULT_BRANCH,
-} from "./git";
+} from "./git.js";
 import {
   planReconciliation,
   decideAbsenceDeletions,
   type LiveEntry,
   type MovedEntry,
   type DeletionDecision,
-} from "./reconcile";
+} from "./reconcile.js";
-import { stabilizePageBody } from "./stabilize";
+import { stabilizePageBody } from "./stabilize.js";
 
 // Engine-only mirror branch (SPEC §5): the engine writes here, humans never do.
 const DOCMOST_BRANCH = "docmost";

packages/git-sync/src/engine/push.ts

@@ -22,21 +22,20 @@
  * then calls `move_page` / `rename_page` (both for a reparent+retitle), or
  * records a NO-OP for a cosmetic local-only file-path rename.
  *
- * VENDORED into gitmost: the client seam is the native
+ * The client seam is the native `GitSyncClient` (`Pick<GitSyncClient, ...>`);
- * `GitSyncClient` (`Pick<GitSyncClient, ...>`), not the upstream REST
+ * the gitmost server drives the engine in-process (there is no standalone CLI
- * `DocmostClient`; the upstream CLI `main()` entry point is dropped (the gitmost
+ * entry point).
- * server drives the engine in-process). Engine LOGIC is byte-identical.
  */
-import { type DocmostMdMeta } from "../lib/index";
+import { type DocmostMdMeta } from "../lib/index.js";
-import { parsePageFile, serializePageFile } from "../lib/page-file";
+import { parsePageFile, serializePageFile } from "../lib/page-file.js";
-import type { GitSyncClient } from "./client.types";
+import type { GitSyncClient } from "./client.types.js";
-import type { DiffEntry } from "./git";
+import type { DiffEntry } from "./git.js";
-import { VaultGit, DEFAULT_BRANCH } from "./git";
+import { VaultGit, DEFAULT_BRANCH } from "./git.js";
-import { bodyHash } from "./loop-guard";
+import { bodyHash } from "./loop-guard.js";
-import { type Settings } from "./settings";
+import { type Settings } from "./settings.js";
 
 // Re-export so callers/tests can import the diff row shape from either module.
-export type { DiffEntry } from "./git";
+export type { DiffEntry } from "./git.js";
 
 /** A page to CREATE in Docmost (new local file, meta has no pageId yet). */
 export interface CreateAction {

packages/git-sync/src/engine/roundtrip-helpers.ts

@@ -1,9 +1,7 @@
 /**
- * Pure helpers extracted from the docmost-sync Phase-0 idempotency harness
+ * Pure, IO-free comparison helpers for the idempotency round-trip checks. The
- * (`src/roundtrip.ts`). Only the IO-free comparison utilities are vendored —
+ * round-trip harness that drives these lives in the package's tests, not in the
- * the CLI scaffold (`--fixture`/`--page`/`--corpus`, `loadSettings`, the
+ * engine.
- * `DocmostClient` live path and `process.exit`) is NOT vendored (the roundtrip
- * harness moves into the package's tests, not the engine).
  */
 
 /**

packages/git-sync/src/engine/settings.ts

@@ -1,16 +1,14 @@
 /**
- * Engine settings (ADAPTED for vendoring).
+ * Engine settings.
  *
- * Upstream this module also loaded `.env` (`dotenv`) and bound `parseSettings`
+ * The engine is driven IN-PROCESS by the NestJS server, which builds the
- * to `process.env` via a `loadSettings()` entry point. In gitmost the engine is
+ * `Settings` object from `EnvironmentService` — so this module must NOT reach
- * driven IN-PROCESS by the NestJS server, which builds the `Settings` object
+ * into `process.env`. It exposes only:
- * from `EnvironmentService` — so the engine must NOT reach into
- * `process.env` here. We therefore vendor ONLY:
  *   - the `Settings` type the engine consumes, and
  *   - `parseSettings(env)` as a PURE function (validate a raw env object -> typed
  *     `Settings`), kept for unit tests and for the server to reuse if it wants
  *     to validate an env-shaped object.
- * The `loadSettings()` / `loadDotenv()` side-effecting entry point is dropped.
+ * There is no `.env`-loading side-effecting entry point.
  */
 import { z } from 'zod';
 

packages/git-sync/src/engine/stabilize.ts

@@ -17,7 +17,7 @@ import {
   markdownToProseMirror,
   serializeDocmostMarkdownBody,
   type DocmostMdMeta,
-} from "../lib/index";
+} from "../lib/index.js";
 
 /**
  * Meta object as `exportPageBody` builds it (SPEC §4). Kept byte-for-byte

packages/git-sync/src/index.ts

@@ -1,9 +1,10 @@
 /**
  * Public surface of `@docmost/git-sync`.
  *
- * Phase A vendors only the PURE converter + pure engine modules
+ * Exposes the pure converter (markdown <-> ProseMirror, file envelope,
- * from docmost-sync. Server integration (GitmostDataSource, orchestrator,
+ * canonicalization) and the sync engine (reconcile planner, vault layout,
- * VaultGit, pull/push) is added in later steps.
+ * pull/push, the git wrapper, and the settings parser) that the gitmost server
+ * drives in-process.
  */
 
 // Pure converter (markdown <-> ProseMirror, file envelope, canonicalization).
@@ -15,8 +16,8 @@ export {
   markdownToProseMirror,
   canonicalizeContent,
   docsCanonicallyEqual,
-} from "./lib/index";
+} from "./lib/index.js";
-export type { DocmostMdMeta } from "./lib/index";
+export type { DocmostMdMeta } from "./lib/index.js";
 
 // Pure engine (no IO): reconcile planner, vault layout, sanitize, stabilize,
 // loop-guard body hash.
@@ -25,7 +26,7 @@ export {
   decideAbsenceDeletions,
   MASS_DELETE_MIN_EXISTING,
   MASS_DELETE_FRACTION,
-} from "./engine/reconcile";
+} from "./engine/reconcile.js";
 export type {
   LiveEntry,
   ExistingEntry,
@@ -33,23 +34,23 @@ export type {
   MovedEntry,
   ReconciliationPlan,
   DeletionDecision,
-} from "./engine/reconcile";
+} from "./engine/reconcile.js";
 
-export { buildVaultLayout } from "./engine/layout";
+export { buildVaultLayout } from "./engine/layout.js";
-export type { PageNode, VaultEntry } from "./engine/layout";
+export type { PageNode, VaultEntry } from "./engine/layout.js";
 
-export { sanitizeTitle, disambiguate } from "./engine/sanitize";
+export { sanitizeTitle, disambiguate } from "./engine/sanitize.js";
 
-export { stabilizePageFile } from "./engine/stabilize";
+export { stabilizePageFile } from "./engine/stabilize.js";
-export type { PageMeta } from "./engine/stabilize";
+export type { PageMeta } from "./engine/stabilize.js";
 
-export { bodyHash } from "./engine/loop-guard";
+export { bodyHash } from "./engine/loop-guard.js";
 
 // IO engine: the client seam, the VaultGit git wrapper, the
 // pull (Docmost->FS) + push (FS->Docmost) planners/appliers, and the (pure)
-// settings parser. The engine consumes the native `GitSyncClient` seam (server
+// settings parser. The engine consumes the native `GitSyncClient` seam (the
-// implements it) — the upstream REST `DocmostClient` is NOT vendored.
+// server implements it) rather than any REST client.
-export type { GitSyncClient, GitSyncPageNodeLite } from "./engine/client.types";
+export type { GitSyncClient, GitSyncPageNodeLite } from "./engine/client.types.js";
 
 export {
   VaultGit,
@@ -58,21 +59,21 @@ export {
   BOT_AUTHOR_NAME,
   BOT_AUTHOR_EMAIL,
   DEFAULT_BRANCH,
-} from "./engine/git";
+} from "./engine/git.js";
-export type { DiffEntry, MergeResult, CommitOptions } from "./engine/git";
+export type { DiffEntry, MergeResult, CommitOptions } from "./engine/git.js";
 
 export {
   readExisting,
   computePullActions,
   applyPullActions,
-} from "./engine/pull";
+} from "./engine/pull.js";
 export type {
   ReadExistingDeps,
   PullActionsInput,
   PullActions,
   ApplyPullActionsDeps,
   ApplyResult,
-} from "./engine/pull";
+} from "./engine/pull.js";
 
 export {
   classifyRenameMoves,
@@ -86,7 +87,7 @@ export {
   LOCAL_AUTHOR_NAME,
   LOCAL_AUTHOR_EMAIL,
   LOCAL_SOURCE_TRAILER,
-} from "./engine/push";
+} from "./engine/push.js";
 export type {
   CreateAction,
   UpdateAction,
@@ -106,18 +107,18 @@ export type {
   PushDeps,
   PushRunResult,
   PushParsedArgs,
-} from "./engine/push";
+} from "./engine/push.js";
 
-export { parseSettings, envSchema } from "./engine/settings";
+export { parseSettings, envSchema } from "./engine/settings.js";
-export type { Settings } from "./engine/settings";
+export type { Settings } from "./engine/settings.js";
 
-export { loadSettingsOrExit } from "./engine/config-errors";
+export { loadSettingsOrExit } from "./engine/config-errors.js";
 
-export { runCycle } from "./engine/cycle";
+export { runCycle } from "./engine/cycle.js";
 export type {
   RunCycleDeps,
   RunCycleResult,
   CycleFs,
-} from "./engine/cycle";
+} from "./engine/cycle.js";
 
-export { parsePageFile, serializePageFile } from "./lib/page-file";
+export { parsePageFile, serializePageFile } from "./lib/page-file.js";

packages/git-sync/src/lib/canonicalize.ts

@@ -1,9 +1,7 @@
 /**
- * docmost-sync ADDITION (not present in docmost-mcp).
+ * Semantic canonicalization of ProseMirror/TipTap documents for the round-trip
- *
+ * idempotency check (SPEC §11, "Задача №0", option (б): compare a CANONICALIZED
- * Semantic canonicalization of ProseMirror/TipTap documents for the Phase-0
+ * form rather than raw bytes).
- * round-trip idempotency check (SPEC §11, "Задача №0", option (б): compare a
- * CANONICALIZED form rather than raw bytes).
  *
  * `markdownToProseMirror` reconstructs schema DEFAULT attributes (e.g.
  * `indent: null` where the source omitted it) and regenerates per-block ids on
@@ -12,8 +10,7 @@
  * normalizes a document so that two semantically-equal docs compare deep-equal
  * regardless of block ids and absent-vs-explicit-default-null attributes.
  *
- * This file is intentionally a NEW, self-contained module so it is trivial to
+ * It is a self-contained module with no external dependencies.
- * backport into docmost-mcp without touching existing code.
  */
 
 /**

packages/git-sync/src/lib/diff.ts

@@ -21,7 +21,7 @@ import { getSchema } from "@tiptap/core";
 import { Node } from "@tiptap/pm/model";
 import { ChangeSet, simplifyChanges } from "@tiptap/pm/changeset";
 import { recreateTransform } from "@fellow/prosemirror-recreate-transform";
-import { docmostExtensions } from "./docmost-schema";
+import { docmostExtensions } from "./docmost-schema.js";
 
 /** A single inserted/deleted change with its containing-block context. */
 export interface DiffChange {

packages/git-sync/src/lib/index.ts

@@ -1,28 +1,26 @@
 /**
- * Public surface of the vendored pure converter (the `lib/` half of the
+ * Public surface of the pure converter (`lib/`). This barrel re-exports the
- * docmost-sync `docmost-client` package). This barrel re-exports only the
  * PURE, IO-free pieces the sync engine needs: the self-contained markdown
  * (de)serializers, the lossless ProseMirror <-> Markdown converter, the
  * markdown -> ProseMirror import path, and semantic canonicalization for the
  * round-trip idempotency check (SPEC §11).
  *
- * The REST client, websocket/collab write-path, auth-utils and page-lock from
+ * There is no REST client, websocket/collab write-path, auth-utils or page-lock
- * the upstream package are deliberately NOT vendored (the gitmost server writes
+ * here — the gitmost server writes natively.
- * natively).
  */
 export {
   serializeDocmostMarkdown,
   parseDocmostMarkdown,
   serializeDocmostMarkdownBody,
-} from "./markdown-document";
+} from "./markdown-document.js";
-export type { DocmostMdMeta } from "./markdown-document";
+export type { DocmostMdMeta } from "./markdown-document.js";
 
-export { convertProseMirrorToMarkdown } from "./markdown-converter";
+export { convertProseMirrorToMarkdown } from "./markdown-converter.js";
 
-export { markdownToProseMirror } from "./markdown-to-prosemirror";
+export { markdownToProseMirror } from "./markdown-to-prosemirror.js";
 
 export {
   canonicalizeContent,
   docsCanonicallyEqual,
-} from "./canonicalize";
+} from "./canonicalize.js";
-export { parsePageFile, serializePageFile } from "./page-file";
+export { parsePageFile, serializePageFile } from "./page-file.js";

packages/git-sync/src/lib/markdown-document.ts

@@ -135,11 +135,9 @@ export function parseDocmostMarkdown(full: string): {
   return { meta, body, comments };
 }
 
-// --- docmost-sync addition (backport target: docmost-mcp/src/lib/markdown-document.ts) ---
-
 /**
  * Serialize a self-contained markdown file with the meta block + body ONLY —
- * NO trailing `docmost:comments` block. The docmost-sync engine never touches
+ * NO trailing `docmost:comments` block. The sync engine never touches
  * `/comments` (SPEC §3): the synced file carries just page identity (meta) and
  * the body, where comment threads survive only as inline `<span
  * data-comment-id>` anchor marks inside the body.

packages/git-sync/src/lib/markdown-to-prosemirror.ts

@@ -1,67 +1,16 @@
 /**
- * Pure markdown -> ProseMirror conversion (extracted from docmost-sync's
+ * Pure markdown -> ProseMirror conversion.
- * `packages/docmost-client/src/lib/collaboration.ts`).
  *
- * Only the PURE converter path is vendored here: `markdownToProseMirror`
+ * The converter path is `markdownToProseMirror` (marked -> HTML ->
- * (marked -> HTML -> generateJSON) plus the two pre/post processors it needs
+ * generateJSON) plus the two pre/post processors it needs (`preprocessCallouts`,
- * (`preprocessCallouts`, `bridgeTaskLists`). The collaboration/websocket
+ * `bridgeTaskLists`). The gitmost server writes the resulting page bodies
- * write-path (Hocuspocus, Yjs, `ws`, `withPageLock`, `sanitizeForYjs`) that
+ * natively through the collab gateway, so no websocket/Yjs write-path lives
- * lives in the same upstream file is intentionally NOT vendored — the gitmost
+ * here.
- * server writes page bodies natively through the collab gateway.
  */
 import { generateJSON } from "@tiptap/html";
 import { JSDOM } from "jsdom";
-import { docmostExtensions } from "./docmost-schema";
+import { marked } from "marked";
-
+import { docmostExtensions } from "./docmost-schema.js";
-/**
- * Structural type for the bits of the `marked` ESM module we use: just the
- * `marked` named export's `parse` method (markdown -> HTML string).
- */
-interface MarkedModule {
-  marked: { parse(markdown: string): string | Promise<string> };
-}
-
-// `marked` is ESM-only. Under this package's CommonJS build TS would otherwise
-// downlevel a literal `import()` to `require()`, which cannot load an ESM-only
-// module. Indirect through `Function` so the real dynamic `import()` survives
-// compilation and loads ESM from CommonJS at runtime in Node (same trick as
-// apps/server/src/core/ai-chat/tools/docmost-client.loader.ts).
-const esmImport = new Function(
-  "specifier",
-  "return import(specifier)",
-) as (specifier: string) => Promise<unknown>;
-
-// Memoize the in-flight/loaded module so the dynamic import runs at most once.
-let markedPromise: Promise<MarkedModule> | null = null;
-
-/**
- * Lazily load the ESM-only `marked` module (cached).
- *
- * In the built CommonJS package (Node, jest with ts-jest) the `esmImport`
- * Function trick performs a real dynamic `import()` of the ESM module. Under
- * vitest, however, the transformed module is evaluated without a dynamic-import
- * callback, so `new Function('return import(...)')` throws "A dynamic import
- * callback was not specified"; there `require('marked')` succeeds because the
- * test runner's loader interops ESM. We therefore try the Function import first
- * and fall back to `require` so BOTH runtimes resolve `marked` transparently.
- */
-async function loadMarked(): Promise<MarkedModule["marked"]> {
-  if (!markedPromise) {
-    markedPromise = (esmImport("marked") as Promise<MarkedModule>)
-      .catch(() => {
-        // Function-trick import is unavailable (e.g. under vitest's evaluator):
-        // fall back to require, which the test runner can interop for ESM.
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        return require("marked") as MarkedModule;
-      })
-      .catch((err) => {
-        // Do not cache a rejected import — allow the next call to retry.
-        markedPromise = null;
-        throw err;
-      });
-  }
-  return (await markedPromise).marked;
-}
 
 // Setup DOM environment for Tiptap HTML parsing in Node.js
 const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>");
@@ -110,8 +59,6 @@ async function preprocessCallouts(markdown: string): Promise<string> {
     return markdown;
   }
 
-  const marked = await loadMarked();
-
   // Recursively transform a slice of lines, converting top-level callouts in
   // that slice into <div> blocks and rendering their inner content (which may
   // itself contain nested callouts) through this same function.
@@ -379,7 +326,6 @@ function stripEmptyParagraphs(node: any): any {
 export async function markdownToProseMirror(
   markdownContent: string,
 ): Promise<any> {
-  const marked = await loadMarked();
   const withCallouts = await preprocessCallouts(markdownContent);
   const html = await marked.parse(withCallouts);
   const bridged = bridgeTaskLists(html);

packages/git-sync/test/git-sync-client.contract.test-d.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, expectTypeOf } from 'vitest';
 import type {
   GitSyncClient,
   GitSyncPageNodeLite,
-} from '../src/engine/client.types';
+} from '../src/engine/client.types.js';
 
 // Contract / type-level guard of the `GitSyncClient` seam (src/engine/client.types.ts).
 //

packages/git-sync/tsconfig.json

@@ -1,8 +1,8 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "module": "CommonJS",
+    "module": "Node16",
-    "moduleResolution": "Node",
+    "moduleResolution": "Node16",
     "outDir": "./build",
     "rootDir": "./src",
     "strict": true,