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/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();
+  });
+});