refactor(git-sync): move the PULL->PUSH cycle into the engine as runCycle (PR #119 review, arch #1)

The reconcile choreography (ensureRepo -> merge-check -> ensureBranch ->
checkout('docmost') -> pull -> push) was hand-rolled in the app orchestrator's
driveCycle, duplicating an order the vendored engine owns and could drift from on
upgrade — the failure mode is data clobber. Lift it into @docmost/git-sync as a
single entry point, `runCycle(deps)`. The orchestrator now calls runCycle and
keeps only the lock (its caller) and the gitmost-specific delete-cap POLICY,
injected as the `resolveApplyClient` hook (the engine does the dry-run, hands the
hook the planned delete count — Infinity if planning failed — and uses whatever
client it returns for the apply). driveCycle drops from ~150 lines to ~30.

Tests:
- engine test/cycle.test.ts: composition (merge-in-progress short-circuit;
  ensureRepo->ensureBranch->checkout staging order before the pull; the cap hook
  is consulted with the planned count; no dry-run when no hook).
- engine test/cycle-roundtrip.test.ts: runCycle against a REAL VaultGit in a temp
  repo with a faked Docmost client — a git-originated CREATE flows pull->push and
  the assigned pageId is written back; an unresolved merge short-circuits before
  any client call.
- orchestrator spec rewired to mock runCycle and assert the wiring + the
  resolveApplyClient cap policy (the engine-internal cycle-order/merge tests moved
  to the engine).

Validated end to end on a live stand (real Postgres/Redis + server): a git clone
-> edit -> push over the /git remote round-trips the change into the Docmost page
through the refactored cycle.

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

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

@@ -0,0 +1,169 @@
+import { VaultGit } from "./git";
+import { GitSyncClient } from "./client.types";
+import { Settings } from "./settings";
+import { readExisting, computePullActions, applyPullActions } from "./pull";
+import { runPush } from "./push";
+
+/**
+ * Absolute-path filesystem primitives the cycle needs. Injected (not imported)
+ * so the engine stays IO-free and unit-testable. `mkdir` is recursive; `rm` is
+ * force (a missing file is a no-op).
+ */
+export interface CycleFs {
+  readFile: (absPath: string) => Promise<string>;
+  writeFile: (absPath: string, text: string) => Promise<void>;
+  mkdir: (absDir: string) => Promise<void>;
+  rm: (absPath: string) => Promise<void>;
+}
+
+export interface RunCycleDeps {
+  spaceId: string;
+  /** The Docmost seam (reads for pull, writes for push). */
+  client: GitSyncClient;
+  /** The per-space git vault (a real working repo). */
+  vault: VaultGit;
+  /** Engine settings; `vaultPath` roots the relPath -> absolute-path mapping. */
+  settings: Settings;
+  fs: CycleFs;
+  log: (line: string) => void;
+  /**
+   * Delete-cap hook (the ONLY caller-specific policy). Called with the push
+   * dry-run's planned delete count (`Number.POSITIVE_INFINITY` when the dry-run
+   * itself failed, so the hook can fail safe) and the live client; returns the
+   * client to use for the REAL apply. The default (omitted) applies every op
+   * unmodified. gitmost uses it to neutralize deletes when over its cap.
+   *
+   * When omitted, NO dry-run is performed (one fewer push planning pass).
+   */
+  resolveApplyClient?: (
+    plannedDeletes: number,
+    client: GitSyncClient,
+  ) => GitSyncClient;
+}
+
+export interface RunCycleResult {
+  ran: boolean;
+  /** Set when the cycle short-circuited without running pull/push. */
+  skipped?: "merge-in-progress";
+  pull?: { written: number; deleted: number; conflict: boolean };
+  push?: { mode: string; failures: number };
+}
+
+/**
+ * Run ONE full reconcile cycle for a space: PULL (Docmost -> vault) then PUSH
+ * (vault -> Docmost), under the engine's required branch choreography. This is
+ * the single entry point the app drives — it owns the staging order so it can
+ * never drift from the engine it ships with.
+ *
+ * Staging (the ⭐ data-loss-critical order, SPEC §6/§9):
+ *   1. assertGitAvailable + ensureRepo (the git state store must exist).
+ *   2. refuse on an unresolved merge (a prior conflicting pull); next checkout
+ *      would fail otherwise.
+ *   3. ensureBranch('docmost','main') + checkout('docmost'). Pull writes MUST
+ *      land on `docmost`, not `main`: applyPullActions commits on `docmost`,
+ *      then checks out `main` and merges docmost -> main. Writing Docmost
+ *      content straight onto `main` would clobber local file edits before push
+ *      can diff them.
+ *   4. PULL: readExisting -> listSpaceTree -> computePullActions -> apply.
+ *   5. PUSH: optional dry-run to feed the delete-cap hook, then the real apply.
+ *
+ * Lock + cap POLICY live in the caller; this owns only the mechanics.
+ */
+export async function runCycle(deps: RunCycleDeps): Promise<RunCycleResult> {
+  const { spaceId, client, vault, settings, fs, log, resolveApplyClient } =
+    deps;
+  const vaultRoot = settings.vaultPath;
+  const abs = (relPath: string) => `${vaultRoot}/${relPath}`;
+
+  // 1. The engine state store is git: make sure the repo + branches exist
+  //    before any tracked-file listing or diff.
+  await vault.assertGitAvailable();
+  await vault.ensureRepo();
+
+  // 2. Refuse to run on top of an unresolved merge (SPEC §9): a prior
+  //    conflicting pull leaves the vault mid-merge; the next checkout would fail.
+  if (await vault.isMergeInProgress()) {
+    log(
+      `vault has an unresolved merge — resolve it (or 'git merge --abort') ` +
+        `and re-run (SPEC §9); skipping cycle.`,
+    );
+    return { ran: false, skipped: "merge-in-progress" };
+  }
+
+  // 3. Pull writes happen on `docmost`; be on it BEFORE applying (see docstring).
+  await vault.ensureBranch("docmost", "main");
+  await vault.checkout("docmost");
+
+  // 4. PULL --------------------------------------------------------------------
+  const existing = await readExisting({
+    listTracked: () => vault.listTrackedFiles("*.md"),
+    readFile: (relPath) => fs.readFile(abs(relPath)),
+  });
+
+  const tree = await client.listSpaceTree(spaceId);
+  const pullActions = computePullActions({
+    pages: tree.pages,
+    treeComplete: tree.complete,
+    existing,
+  });
+
+  const pullResult = await applyPullActions(
+    {
+      client,
+      git: vault,
+      writeFile: (absPath, text) => fs.writeFile(absPath, text),
+      mkdir: (absDir) => fs.mkdir(absDir),
+      rm: (absPath) => fs.rm(absPath),
+    },
+    pullActions,
+    vaultRoot,
+  );
+
+  // 5. PUSH --------------------------------------------------------------------
+  const pushDeps = {
+    settings,
+    git: vault,
+    makeClient: () => client,
+    readFile: (relPath: string) => fs.readFile(abs(relPath)),
+    writeFile: (relPath: string, text: string) => fs.writeFile(abs(relPath), text),
+    log,
+  };
+
+  let applyClient = client;
+  if (resolveApplyClient) {
+    // Plan the push as a DRY-RUN first to read the delete count, then let the
+    // caller decide the apply client (e.g. neutralize deletes over a cap). A
+    // failed dry-run yields Infinity so the hook can fail safe.
+    let plannedDeletes: number;
+    try {
+      const dry = await runPush(pushDeps, { dryRun: true });
+      plannedDeletes = dry.planned?.deletes ?? 0;
+    } catch (err) {
+      log(
+        `push dry-run planning failed (${
+          err instanceof Error ? err.message : String(err)
+        }); deferring deletion policy to the cap hook (fail-safe).`,
+      );
+      plannedDeletes = Number.POSITIVE_INFINITY;
+    }
+    applyClient = resolveApplyClient(plannedDeletes, client);
+  }
+
+  const pushResult = await runPush(
+    { ...pushDeps, makeClient: () => applyClient },
+    { dryRun: false },
+  );
+
+  return {
+    ran: true,
+    pull: {
+      written: pullResult.written,
+      deleted: pullResult.deleted,
+      conflict: pullResult.merge.conflict,
+    },
+    push: {
+      mode: pushResult.mode,
+      failures: pushResult.failures?.length ?? 0,
+    },
+  };
+}

packages/git-sync/src/index.ts

@@ -112,3 +112,10 @@ export { parseSettings, envSchema } from "./engine/settings";
 export type { Settings } from "./engine/settings";
 
 export { loadSettingsOrExit } from "./engine/config-errors";
+
+export { runCycle } from "./engine/cycle";
+export type {
+  RunCycleDeps,
+  RunCycleResult,
+  CycleFs,
+} from "./engine/cycle";

packages/git-sync/test/cycle-roundtrip.test.ts

@@ -0,0 +1,169 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { runCycle } from "../src/engine/cycle";
+import type { CycleFs } from "../src/engine/cycle";
+import { VaultGit } from "../src/engine/git";
+import type { Settings } from "../src/engine/settings";
+import { serializeDocmostMarkdownBody } from "../src/lib/index";
+
+const execFileAsync = promisify(execFile);
+
+// runCycle (full PULL -> PUSH choreography) against a REAL VaultGit in a temp
+// repo, with a faked Docmost client. This is the integration guard for the
+// extraction of the cycle out of the app orchestrator: it proves runCycle wires
+// the real engine pull + push together against real git and delivers a
+// git-originated CREATE to the client. (The full two-way data-loss invariant —
+// a local main edit surviving a concurrent Docmost edit — is exercised end to
+// end against a live server in the git-sync e2e stand.)
+
+async function gitAvailable(): Promise<boolean> {
+  try {
+    await execFileAsync("git", ["--version"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function makeSettings(vaultPath: string): Settings {
+  return {
+    docmostApiUrl: "https://docmost.example.com",
+    docmostEmail: "you@example.com",
+    docmostPassword: "secret",
+    docmostSpaceId: "space-1",
+    vaultPath,
+    pollIntervalMs: 15000,
+    debounceMs: 2000,
+    logLevel: "info",
+  } as Settings;
+}
+
+/** Node-fs CycleFs rooted nowhere (absolute paths are passed through). */
+const nodeFs: CycleFs = {
+  readFile: (absPath) => readFile(absPath, "utf8"),
+  writeFile: (absPath, text) => writeFile(absPath, text, "utf8"),
+  mkdir: async (absDir) => {
+    const fs = await import("node:fs/promises");
+    await fs.mkdir(absDir, { recursive: true });
+  },
+  rm: async (absPath) => {
+    const fs = await import("node:fs/promises");
+    await fs.rm(absPath, { force: true });
+  },
+};
+
+/** A minimal recording client; empty Docmost so the pull is a no-op. */
+function makeEmptyClientFake() {
+  return {
+    listSpaceTree: vi.fn(async () => ({ pages: [], complete: true })),
+    getPageJson: vi.fn(),
+    importPageMarkdown: vi.fn(async () => ({ updatedAt: "2026-06-20T00:00:00.000Z" })),
+    createPage: vi.fn(async (title: string) => ({
+      data: { id: "new-id", title },
+      updatedAt: "2026-06-20T00:00:00.000Z",
+    })),
+    deletePage: vi.fn(async () => ({})),
+    movePage: vi.fn(async () => ({})),
+    renamePage: vi.fn(async () => ({})),
+    listRecentSince: vi.fn(async () => []),
+    listTrash: vi.fn(async () => []),
+    restorePage: vi.fn(async () => ({})),
+  };
+}
+
+describe("runCycle against a REAL VaultGit (integration)", () => {
+  let available = false;
+  let dir: string;
+
+  beforeAll(async () => {
+    available = await gitAvailable();
+  });
+
+  afterEach(async () => {
+    if (dir) await rm(dir, { recursive: true, force: true });
+  });
+
+  it("runs the full PULL->PUSH and delivers a git-originated CREATE to the client", async () => {
+    if (!available) return; // skip gracefully when git is unavailable
+
+    dir = await mkdtemp(join(tmpdir(), "docmost-cycle-realgit-"));
+    const git = new VaultGit(dir);
+    await git.ensureRepo();
+    await git.ensureBranch("docmost", "main");
+
+    // A human committed a brand-new file on `main` (meta has title + spaceId but
+    // NO pageId) -> the push side must classify it as a CREATE.
+    const newFile = serializeDocmostMarkdownBody(
+      { version: 1, title: "From Git", spaceId: "space-1" },
+      "a body authored in git",
+    );
+    await writeFile(join(dir, "From Git.md"), newFile, "utf8");
+    await git.stageAll();
+    await git.commit("add From Git.md", {
+      authorName: "Human",
+      authorEmail: "human@local",
+    });
+
+    const client = makeEmptyClientFake();
+    const res = await runCycle({
+      spaceId: "space-1",
+      client: client as any,
+      vault: git,
+      settings: makeSettings(dir),
+      fs: nodeFs,
+      log: () => undefined,
+    });
+
+    expect(res.ran).toBe(true);
+    expect(res.push?.failures).toBe(0);
+    // The CREATE reached Docmost (the push side ran end to end through runCycle).
+    expect(client.createPage).toHaveBeenCalledTimes(1);
+    expect(client.createPage.mock.calls[0][0]).toBe("From Git");
+
+    // The engine wrote the assigned pageId back into the file on disk.
+    const onDisk = await readFile(join(dir, "From Git.md"), "utf8");
+    expect(onDisk).toContain("new-id");
+  });
+
+  it("an unresolved merge short-circuits before any client call", async () => {
+    if (!available) return;
+
+    dir = await mkdtemp(join(tmpdir(), "docmost-cycle-merge-"));
+    const git = new VaultGit(dir);
+    await git.ensureRepo();
+    // Force a conflicting state: create divergent commits on main and docmost
+    // touching the same file, then attempt a merge so the tree is left mid-merge.
+    await writeFile(join(dir, "C.md"), "base\n", "utf8");
+    await git.stageAll();
+    await git.commit("base", { authorName: "h", authorEmail: "h@l" });
+    await git.ensureBranch("docmost", "main");
+    await git.checkout("docmost");
+    await writeFile(join(dir, "C.md"), "docmost-side\n", "utf8");
+    await git.stageAll();
+    await git.commit("docmost edit", { authorName: "h", authorEmail: "h@l" });
+    await git.checkout("main");
+    await writeFile(join(dir, "C.md"), "main-side\n", "utf8");
+    await git.stageAll();
+    await git.commit("main edit", { authorName: "h", authorEmail: "h@l" });
+    // Start a conflicting merge and leave it unresolved.
+    await execFileAsync("git", ["-C", dir, "merge", "docmost"]).catch(() => {});
+
+    const client = makeEmptyClientFake();
+    const res = await runCycle({
+      spaceId: "space-1",
+      client: client as any,
+      vault: git,
+      settings: makeSettings(dir),
+      fs: nodeFs,
+      log: () => undefined,
+    });
+
+    expect(res).toEqual({ ran: false, skipped: "merge-in-progress" });
+    expect(client.listSpaceTree).not.toHaveBeenCalled();
+    expect(client.createPage).not.toHaveBeenCalled();
+  });
+});

packages/git-sync/test/cycle.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect, vi } from "vitest";
+import { runCycle, type RunCycleDeps } from "../src/engine/cycle";
+
+// A fake VaultGit recording the staging calls. An EMPTY vault/tree lets the real
+// readExisting/computePullActions/applyPullActions/runPush run trivially (no
+// files, no pages) so we can assert runCycle's choreography without real git.
+function fakeVault(overrides: Record<string, any> = {}) {
+  const order: string[] = [];
+  const rec =
+    (name: string, ret?: any) =>
+    async (...args: any[]) => {
+      order.push(args.length ? `${name}:${args.join(",")}` : name);
+      return ret;
+    };
+  const vault: any = {
+    order,
+    assertGitAvailable: rec("assertGitAvailable"),
+    ensureRepo: rec("ensureRepo"),
+    isMergeInProgress: vi.fn(async () => false),
+    ensureBranch: rec("ensureBranch"),
+    checkout: rec("checkout"),
+    listTrackedFiles: vi.fn(async () => [] as string[]),
+    // push-side git surface (empty diff -> a clean no-op push)
+    stageAll: rec("stageAll"),
+    commit: rec("commit", { committed: false }),
+    merge: rec("merge", { ok: true, conflict: false, output: "" }),
+    readRef: vi.fn(async () => null),
+    revParse: vi.fn(async () => "0000000000000000000000000000000000000000"),
+    diffNameStatus: vi.fn(async () => [] as any[]),
+    showFileAtRef: vi.fn(async () => ""),
+    updateRef: rec("updateRef"),
+    fastForwardBranch: rec("fastForwardBranch", { ok: true }),
+    ...overrides,
+  };
+  return vault;
+}
+
+function baseDeps(vault: any, over: Partial<RunCycleDeps> = {}): RunCycleDeps {
+  return {
+    spaceId: "space-1",
+    client: {
+      listSpaceTree: vi.fn(async () => ({ pages: [], complete: true })),
+      getPageJson: vi.fn(),
+      importPageMarkdown: vi.fn(),
+      createPage: vi.fn(),
+      deletePage: vi.fn(),
+      movePage: vi.fn(),
+      renamePage: vi.fn(),
+      listRecentSince: vi.fn(),
+      listTrash: vi.fn(),
+      restorePage: vi.fn(),
+    } as any,
+    vault,
+    settings: { vaultPath: "/vault" } as any,
+    fs: {
+      readFile: vi.fn(async () => ""),
+      writeFile: vi.fn(async () => undefined),
+      mkdir: vi.fn(async () => undefined),
+      rm: vi.fn(async () => undefined),
+    },
+    log: vi.fn(),
+    ...over,
+  };
+}
+
+describe("runCycle (composition)", () => {
+  it("short-circuits with skipped:'merge-in-progress' and runs no pull/push", async () => {
+    const vault = fakeVault({ isMergeInProgress: vi.fn(async () => true) });
+    const deps = baseDeps(vault);
+
+    const res = await runCycle(deps);
+
+    expect(res).toEqual({ ran: false, skipped: "merge-in-progress" });
+    // Never advanced to the pull (listSpaceTree) or push.
+    expect(deps.client.listSpaceTree).not.toHaveBeenCalled();
+    expect(vault.order).not.toContain("checkout:docmost");
+  });
+
+  it("stages ensureRepo -> ensureBranch(docmost,main) -> checkout(docmost) BEFORE pulling", async () => {
+    const vault = fakeVault();
+    const deps = baseDeps(vault);
+
+    const res = await runCycle(deps);
+
+    expect(res.ran).toBe(true);
+    const ensureRepoIdx = vault.order.indexOf("ensureRepo");
+    const ensureBranchIdx = vault.order.indexOf("ensureBranch:docmost,main");
+    const checkoutIdx = vault.order.indexOf("checkout:docmost");
+    expect(ensureRepoIdx).toBeGreaterThanOrEqual(0);
+    expect(ensureBranchIdx).toBeGreaterThan(ensureRepoIdx);
+    expect(checkoutIdx).toBeGreaterThan(ensureBranchIdx);
+    expect(deps.client.listSpaceTree).toHaveBeenCalledTimes(1);
+  });
+
+  it("consults the resolveApplyClient hook with the planned delete count", async () => {
+    const vault = fakeVault();
+    const hook = vi.fn((_planned: number, c: any) => c);
+    const deps = baseDeps(vault, { resolveApplyClient: hook });
+
+    await runCycle(deps);
+
+    // An empty vault plans zero deletes; the hook is still consulted so the
+    // caller's policy always sees the count (and a dry-run preceded it).
+    expect(hook).toHaveBeenCalledTimes(1);
+    expect(hook.mock.calls[0][0]).toBe(0);
+  });
+
+  it("skips the dry-run entirely when no resolveApplyClient hook is given", async () => {
+    const vault = fakeVault();
+    const deps = baseDeps(vault); // no resolveApplyClient
+
+    const res = await runCycle(deps);
+    expect(res.ran).toBe(true);
+    // With no cap hook there is a single runPush (the apply) — no dry-run pass.
+    // diffNameStatus is read once per runPush; assert a single planning pass.
+    expect(vault.diffNameStatus).toHaveBeenCalledTimes(1);
+  });
+});