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>

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

@@ -1,24 +1,21 @@
 /**
- * The client seam. Upstream `pull.ts`/`push.ts` reached into the
- * REST `DocmostClient` from the `docmost-client` package via `Pick<DocmostClient,
- * ...>` subsets. That package is NOT vendored here (the gitmost server writes
- * NATIVELY — through repositories + collab `openDirectConnection`),
- * so the engine must depend on a narrow STRUCTURAL interface instead.
+ * The client seam. `pull.ts`/`push.ts` depend on a narrow STRUCTURAL interface
+ * rather than any concrete client, because the gitmost server writes NATIVELY —
+ * through repositories + collab `openDirectConnection`.
  *
- * `GitSyncClient` is that interface: the native datasource (server side, a later
- * step) implements it, and the vendored engine only ever uses `Pick<GitSyncClient,
- * ...>` subsets of it. The signatures below MIRROR exactly the methods the
- * vendored `pull.ts`/`push.ts` actually call (arg shapes + the fields the engine
- * reads off each result) — verified against the upstream `DocmostClient`
- * (packages/docmost-client/src/client.ts) so a real REST client is still
- * structurally assignable, and so the native adapter has a precise contract.
+ * `GitSyncClient` is that interface: the native datasource (server side)
+ * implements it, and the engine only ever uses `Pick<GitSyncClient, ...>`
+ * subsets of it. The signatures below MIRROR exactly the methods the engine's
+ * `pull.ts`/`push.ts` actually call (arg shapes + the fields the engine reads
+ * off each result), so a REST-style client is still structurally assignable and
+ * 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 { GitSyncClient } from "./client.types";
-import { Settings } from "./settings";
-import { readExisting, computePullActions, applyPullActions } from "./pull";
-import { runPush } from "./push";
+import { VaultGit } from "./git.js";
+import { GitSyncClient } from "./client.types.js";
+import { Settings } from "./settings.js";
+import { readExisting, computePullActions, applyPullActions } from "./pull.js";
+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
- * source repo. `data/` is gitignored by the source repo, so a nested repo under
- * `data/vault` is safe. The pull cycle is READ-ONLY toward Docmost; this module
- * only touches the local vault git, never a git remote (push is deferred, see
- * SPEC §7).
+ * the gitmost application repo. This module MUST NEVER run git against the
+ * application repo. `data/` is gitignored, so a nested repo under `data/vault`
+ * is safe. The pull cycle is READ-ONLY toward Docmost; this module only touches
+ * the local vault git, never a git remote (push is deferred, see 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
- * `GitSyncClient` (`Pick<GitSyncClient, ...>`), not the upstream REST
- * `DocmostClient`; the upstream CLI `main()` entry point is dropped (the gitmost
- * server drives the engine in-process). Engine LOGIC is byte-identical.
+ * The client seam is the native `GitSyncClient` (`Pick<GitSyncClient, ...>`);
+ * the gitmost server drives the engine in-process (there is no standalone CLI
+ * entry point).
  */
 import { dirname } from "node:path";
 import { sep } from "node:path";
-import { parsePageFile, serializePageFile } from "../lib/page-file";
-import type { GitSyncClient } from "./client.types";
-import { buildVaultLayout, type PageNode } from "./layout";
+import { parsePageFile, serializePageFile } from "../lib/page-file.js";
+import type { GitSyncClient } from "./client.types.js";
+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";
-import { stabilizePageBody } from "./stabilize";
+} from "./reconcile.js";
+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
- * `GitSyncClient` (`Pick<GitSyncClient, ...>`), not the upstream REST
- * `DocmostClient`; the upstream CLI `main()` entry point is dropped (the gitmost
- * server drives the engine in-process). Engine LOGIC is byte-identical.
+ * The client seam is the native `GitSyncClient` (`Pick<GitSyncClient, ...>`);
+ * the gitmost server drives the engine in-process (there is no standalone CLI
+ * entry point).
  */
-import { type DocmostMdMeta } from "../lib/index";
-import { parsePageFile, serializePageFile } from "../lib/page-file";
-import type { GitSyncClient } from "./client.types";
-import type { DiffEntry } from "./git";
-import { VaultGit, DEFAULT_BRANCH } from "./git";
-import { bodyHash } from "./loop-guard";
-import { type Settings } from "./settings";
+import { type DocmostMdMeta } from "../lib/index.js";
+import { parsePageFile, serializePageFile } from "../lib/page-file.js";
+import type { GitSyncClient } from "./client.types.js";
+import type { DiffEntry } from "./git.js";
+import { VaultGit, DEFAULT_BRANCH } from "./git.js";
+import { bodyHash } from "./loop-guard.js";
+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
- * (`src/roundtrip.ts`). Only the IO-free comparison utilities are vendored —
- * the CLI scaffold (`--fixture`/`--page`/`--corpus`, `loadSettings`, the
- * `DocmostClient` live path and `process.exit`) is NOT vendored (the roundtrip
- * harness moves into the package's tests, not the engine).
+ * Pure, IO-free comparison helpers for the idempotency round-trip checks. The
+ * round-trip harness that drives these lives in the package's tests, not in 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`
- * to `process.env` via a `loadSettings()` entry point. In gitmost the engine is
- * driven IN-PROCESS by the NestJS server, which builds the `Settings` object
- * from `EnvironmentService` — so the engine must NOT reach into
- * `process.env` here. We therefore vendor ONLY:
+ * The engine is driven IN-PROCESS by the NestJS server, which builds the
+ * `Settings` object from `EnvironmentService` — so this module must NOT reach
+ * into `process.env`. It exposes 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