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,
+    },
+  };
+}