dsh-desktop-kit 2.2.1 → 2.7.2

package/plugins/dsh-memory-bridge/lib/sync.js

@@ -0,0 +1,984 @@
+/**
+ * dsh-memory-bridge — GitHub-only sync service (v2).
+ *
+ * Transport: one private GitHub repository holds the merged dossier of every
+ * project. Every machine keeps its local dossier as a working copy plus a base
+ * snapshot of the last successful sync. A cycle:
+ *
+ *   fetch → reset derived clone to origin → three-way merge each file
+ *   (local / base / origin) → write merged local + repo files → commit → push
+ *
+ * A failed push is never forced: the cycle fetches again and merges again, so
+ * asynchronous work of several machines is combined instead of overwritten.
+ */
+
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+
+import {
+  BridgeError,
+  DEFAULT_LIMITS,
+  JOURNAL_FILE,
+  SECTION_FILES,
+  ensureDir,
+  exists,
+  isAllowedSyncPath,
+  isTemplateContent,
+  readTextIfExists,
+  sha256,
+  writeFileAtomic,
+  writeJsonAtomic,
+} from "./bridge.js";
+import {
+  cloneRepo,
+  commitRepo,
+  createPrivateRepo,
+  fetchOrigin,
+  ghLogin,
+  ghVersion,
+  gitVersion,
+  isRepoSlug,
+  localFileText,
+  mergeJournalAdditive,
+  mergeThreeWay,
+  pushRepo,
+  readTreeFiles,
+  remoteHeadExists,
+  repoFolderName,
+  repoRemoteUrl,
+  repoVisibility,
+  repoWebUrl,
+  resetToRemote,
+  runGit,
+  seedEmptyRepo,
+  suggestedExchangeRepo,
+  syncText,
+  verifyRemote,
+  writeTreeFile,
+  ensureRepoIdentity,
+} from "./github.js";
+import { splitJournal } from "./merge.js";
+import { exportPortable, importPortable, scanPortable } from "./portable.js";
+import * as st from "./state.js";
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function formatTime(value) {
+  if (typeof value !== "string") return "—";
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? value : date.toLocaleString("ru-RU", { hour12: false });
+}
+
+function folderSlug(slug) {
+  return String(slug ?? "project").replace(/[^A-Za-z0-9._-]+/gu, "-").slice(0, 40) || "project";
+}
+
+function projectFolder(target) {
+  return `${folderSlug(target.slug)}--${target.projectKey.slice(0, 8)}`;
+}
+
+function mapDiffers(local, base) {
+  const keys = new Set([...local.keys(), ...base.keys()]);
+  for (const key of keys) {
+    if ((local.get(key) ?? "") !== (base.get(key) ?? "")) return true;
+  }
+  return false;
+}
+
+function unionText(localText, remoteText) {
+  const localLines = String(localText ?? "").split("\n");
+  const seen = new Set(localLines.map((line) => line.trim()).filter(Boolean));
+  const extra = String(remoteText ?? "")
+    .split("\n")
+    .filter((line) => line.trim().length > 0 && !seen.has(line.trim()));
+  if (extra.length === 0) return localText;
+  return `${localText.trimEnd()}\n${extra.join("\n")}\n`;
+}
+
+export function createSyncService({ home = process.env.DSH_HOME || path.join(os.homedir(), ".dsh"), logger = null, ghAdapter = {} } = {}) {
+  const paths = st.pathsFor(home);
+  const ghApi = {
+    version: ghVersion,
+    login: ghLogin,
+    visibility: repoVisibility,
+    createRepo: createPrivateRepo,
+    ...ghAdapter,
+  };
+  let running = null;
+  let machine;
+  let runtime = { lastAutoAt: 0, lastError: null };
+  let githubCache = { at: 0, info: null };
+  const visibilityCache = new Map();
+
+  async function init() {
+    for (const directory of [paths.root, paths.githubRoot, paths.baseDir, paths.conflictsDir, paths.tmpDir, paths.backupsDir]) {
+      await ensureDir(directory);
+    }
+    machine = await st.loadMachine(home);
+    await st.logLine(home, `github service started machine=${machine.machineId} host=${machine.label}`);
+    return machine;
+  }
+
+  async function currentConfig() {
+    return st.loadConfig(home);
+  }
+
+  async function currentMachine() {
+    if (!machine) machine = await st.loadMachine(home);
+    return machine;
+  }
+
+  /** gh CLI availability + the authenticated GitHub account (cached for a minute). */
+  async function githubSnapshot({ force = false } = {}) {
+    if (!force && githubCache.info !== null && Date.now() - githubCache.at < 60_000) return githubCache.info;
+    let available = false;
+    let login;
+    try {
+      available = Boolean(await ghApi.version());
+      if (available) login = await ghApi.login();
+    } catch {
+      available = false;
+      login = undefined;
+    }
+    const info = {
+      available,
+      authenticated: Boolean(login),
+      login: login ?? null,
+      suggestedRepo: suggestedExchangeRepo(login),
+    };
+    githubCache = { at: Date.now(), info };
+    return info;
+  }
+
+  async function visibilityOf(repo, { force = false } = {}) {
+    if (!isRepoSlug(repo)) return "unknown";
+    const cached = visibilityCache.get(repo);
+    if (!force && cached !== undefined && Date.now() - cached.at < 60_000) return cached.value;
+    let value = "unknown";
+    try {
+      value = (await ghApi.visibility(repo)) ?? "unknown";
+    } catch {
+      value = "unknown";
+    }
+    visibilityCache.set(repo, { at: Date.now(), value });
+    return value;
+  }
+
+  function repoDirectory(config) {
+    if (typeof config.localDir === "string" && config.localDir.trim().length > 0) return path.resolve(config.localDir.trim());
+    return path.join(paths.githubRoot, repoFolderName(config.repo));
+  }
+
+  function baseDirectory(folder) {
+    return path.join(paths.baseDir, folder);
+  }
+
+  async function readBaseMap(folder) {
+    const map = await readTreeFiles(baseDirectory(folder));
+    const result = new Map();
+    for (const [key, value] of map) result.set(key, String(value).replace(/\r\n/gu, "\n").trimEnd());
+    return result;
+  }
+
+  async function writeBaseMap(folder, content) {
+    const directory = baseDirectory(folder);
+    for (const [key, value] of content) await writeTreeFile(directory, key, `${String(value).trimEnd()}\n`);
+  }
+
+  async function localTargets(config) {
+    const { targets, skipped } = await st.syncTargets(home, config);
+    const registry = await st.readRegistry(home);
+    const resolved = targets.map((target) => ({ ...target, folder: projectFolder(target) }));
+    // A project may have been registered before it became a git repository.
+    // Re-detect the remote at sync time instead of asking the user to re-register.
+    for (const item of [...skipped]) {
+      const project = registry.projects.find((entry) => entry.slug === item.slug);
+      if (!project) continue;
+      const roots = Array.isArray(project.roots) ? project.roots.filter((root) => typeof root === "string") : [];
+      for (const root of roots) {
+        const remoteResult = await runGit(["config", "--get", "remote.origin.url"], { cwd: root });
+        let remote = remoteResult.ok ? remoteResult.stdout.trim() : "";
+        if (remote.length === 0) {
+          const fallback = await runGit(["remote", "get-url", "origin"], { cwd: root });
+          remote = fallback.ok ? fallback.stdout.trim() : "";
+        }
+        if (remote.length === 0) continue;
+        remote = remote.replace(/\/\/[^@/]+@/u, "//[REDACTED]@").slice(0, 200);
+        const fingerprint = `git:${remote}`;
+        const projectKey = st.projectKeyFor(fingerprint);
+        const target = {
+          slug: item.slug,
+          name: typeof project.name === "string" ? project.name : item.slug,
+          fingerprint,
+          projectKey,
+          directory: path.join(paths.projectsMemory, item.slug),
+          roots,
+        };
+        resolved.push({ ...target, folder: projectFolder(target) });
+        skipped.splice(skipped.indexOf(item), 1);
+        break;
+      }
+    }
+    return { targets: resolved, skipped };
+  }
+
+  async function localSyncMap(target) {
+    const raw = await st.readLocalDossier(target.directory, {
+      maxFileBytes: DEFAULT_LIMITS.maxFileBytes,
+      maxBundleBytes: DEFAULT_LIMITS.maxBundleBytes,
+      maxFiles: DEFAULT_LIMITS.maxFiles,
+    });
+    const map = new Map();
+    for (const [key, value] of raw.raw) map.set(key, syncText(key, value));
+    return { map, raw: raw.raw, skipped: raw.skipped };
+  }
+
+  async function remoteSyncMap(repoProjectDir) {
+    const tree = await readTreeFiles(repoProjectDir);
+    const map = new Map();
+    for (const [key, value] of tree) map.set(key, String(value).replace(/\r\n/gu, "\n").trimEnd());
+    return map;
+  }
+
+  /* ---------------------------------------------------------------- */
+  /* conflicts                                                         */
+  /* ---------------------------------------------------------------- */
+
+  async function listConflicts() {
+    const conflicts = [];
+    let entries = [];
+    try {
+      entries = await fsp.readdir(paths.conflictsDir, { withFileTypes: true });
+    } catch {
+      return conflicts;
+    }
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+      try {
+        const parsed = JSON.parse(await fsp.readFile(path.join(paths.conflictsDir, entry.name), "utf8"));
+        if (parsed && typeof parsed === "object") conflicts.push(parsed);
+      } catch {
+        /* corrupted conflict file: ignore, it stays on disk */
+      }
+    }
+    return conflicts.sort((left, right) => String(left.createdAt).localeCompare(String(right.createdAt)));
+  }
+
+  function conflictId(conflict) {
+    return sha256(`conflict\u0000${conflict.folder}\u0000${conflict.path}`).slice(0, 16);
+  }
+
+  async function saveConflict(conflict) {
+    const id = conflictId(conflict);
+    const file = path.join(paths.conflictsDir, `${id}.json`);
+    const existed = await exists(file);
+    await writeJsonAtomic(file, { ...conflict, id, createdAt: nowIso() });
+    if (!existed) await st.logLine(home, `conflict project=${conflict.projectSlug} file=${conflict.path}`);
+    return { id, file, added: !existed };
+  }
+
+  /**
+   * While a conflict is unresolved, keep its local/remote previews up to date,
+   * so resolving later never overwrites a newer change from GitHub.
+   */
+  async function refreshStoredConflicts(dir, targets, storedConflicts) {
+    for (const conflict of storedConflicts) {
+      const target = targets.find((item) => item.folder === conflict.folder);
+      if (!target) continue;
+      const localFile = path.join(target.directory, ...conflict.path.split("/"));
+      const localRaw = await readTextIfExists(localFile);
+      const remoteRaw = await readTextIfExists(path.join(dir, "projects", conflict.folder, ...conflict.path.split("/")));
+      if (localRaw === undefined || remoteRaw === undefined) continue;
+      const localText = syncText(conflict.path, localRaw);
+      const remoteText = String(remoteRaw).replace(/\r\n/gu, "\n").trimEnd();
+      if (localText !== conflict.localText || remoteText !== conflict.remoteText) {
+        await saveConflict({ ...conflict, localText, remoteText });
+      }
+    }
+  }
+
+  async function readConflict(id) {
+    const file = path.join(paths.conflictsDir, `${String(id).replace(/[^a-f0-9]/giu, "")}.json`);
+    const raw = await readTextIfExists(file);
+    if (raw === undefined) return undefined;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return undefined;
+    }
+  }
+
+  async function removeConflict(id) {
+    await fsp.rm(path.join(paths.conflictsDir, `${String(id).replace(/[^a-f0-9]/giu, "")}.json`), { force: true });
+  }
+
+  /* ---------------------------------------------------------------- */
+  /* merge one project into the derived clone                          */
+  /* ---------------------------------------------------------------- */
+
+  async function mergeProject({ target, repoDir, conflicts, existingConflictPaths, report }) {
+    const repoProjectDir = path.join(repoDir, "projects", target.folder);
+    const metaFile = path.join(repoProjectDir, "project.json");
+    let meta;
+    try {
+      meta = JSON.parse(await fsp.readFile(metaFile, "utf8"));
+    } catch {
+      meta = undefined;
+    }
+    const me = await currentMachine();
+    if (meta && typeof meta.fingerprint === "string" && meta.fingerprint.length > 0 && meta.fingerprint !== target.fingerprint) {
+      report.warnings.push(`${target.slug}: в репозитории проект с другим fingerprint (${meta.fingerprint}) — пропущен`);
+      return;
+    }
+    const local = await localSyncMap(target);
+    const base = await readBaseMap(target.folder);
+    const remote = await remoteSyncMap(repoProjectDir);
+    const pathsToMerge = new Set([...local.map.keys(), ...base.keys(), ...remote.keys()]);
+    let wroteLocal = false;
+    let wroteRepo = false;
+    for (const relativePath of [...pathsToMerge].sort()) {
+      if (existingConflictPaths.has(relativePath)) continue; // wait for the user's choice
+      const localText = local.map.get(relativePath);
+      const baseText = base.get(relativePath);
+      const remoteText = remote.get(relativePath);
+      let merged;
+      let conflict = false;
+      if (localText === undefined && remoteText === undefined) continue;
+      if (remoteText === undefined) {
+        if (baseText === undefined) {
+          merged = localText; // brand new local file
+        } else {
+          conflict = true; // another machine deleted it; never delete silently
+        }
+      } else if (localText === undefined) {
+        merged = remoteText; // import into a local project that does not have this file
+      } else if (localText === remoteText) {
+        continue;
+      } else if (baseText !== undefined && localText === baseText) {
+        merged = remoteText; // fast-forward
+      } else if (baseText !== undefined && remoteText === baseText) {
+        merged = localText; // publish local change
+      } else if (baseText === undefined) {
+        const localTemplate = SECTION_FILES.includes(relativePath) && isTemplateContent(localText);
+        const remoteTemplate = SECTION_FILES.includes(relativePath) && isTemplateContent(remoteText);
+        if (localTemplate && !remoteTemplate) merged = remoteText;
+        else if (!localTemplate && remoteTemplate) merged = localText;
+        else conflict = true;
+      } else {
+        const three = await mergeThreeWay({
+          localText,
+          baseText,
+          remoteText,
+          tmpDir: paths.tmpDir,
+        });
+        if (three.ok) {
+          merged = three.text;
+        } else if (JOURNAL_FILE.test(relativePath)) {
+          const union = mergeJournalAdditive(localText, remoteText);
+          if (union.conflicts.length === 0) merged = union.text;
+          else conflict = true;
+        } else {
+          conflict = true;
+        }
+      }
+      if (conflict) {
+        conflicts.push({
+          folder: target.folder,
+          projectSlug: target.slug,
+          projectName: target.name,
+          path: relativePath,
+          localText: localText ?? "",
+          remoteText: remoteText ?? "",
+          baseText: baseText ?? "",
+        });
+        continue;
+      }
+      if (merged === undefined) continue;
+      const canonical = String(merged).replace(/\r\n/gu, "\n").trimEnd();
+      const currentLocal = local.map.get(relativePath);
+      if (currentLocal !== canonical) {
+        const localRaw = local.raw.get(relativePath) ?? "";
+        const nextLocal = localFileText(relativePath, canonical, localRaw);
+        await writeFileAtomic(path.join(target.directory, ...relativePath.split("/")), nextLocal);
+        local.map.set(relativePath, canonical);
+        wroteLocal = true;
+      }
+      if (remoteText !== canonical) {
+        await writeTreeFile(repoProjectDir, relativePath, `${canonical}\n`);
+        wroteRepo = true;
+      }
+    }
+    // project metadata is part of the exchange
+    const nextMeta = {
+      key: target.projectKey,
+      fingerprint: target.fingerprint,
+      slug: target.slug,
+      name: target.name,
+      updatedAt: nowIso(),
+      lastWriter: me.machineId,
+      lastWriterLabel: me.label,
+    };
+    const metaText = `${JSON.stringify(nextMeta, null, 2)}\n`;
+    const previousMeta = await readTextIfExists(metaFile);
+    if (previousMeta !== metaText) {
+      await ensureDir(repoProjectDir);
+      await writeFileAtomic(metaFile, metaText);
+      wroteRepo = true;
+    }
+    if (wroteLocal) report.files += 1;
+    if (wroteRepo) report.projects += 1;
+    report.entries.push({ folder: target.folder, files: local.map.size, changed: wroteLocal || wroteRepo });
+  }
+
+  /* ---------------------------------------------------------------- */
+  /* one sync attempt: fetch → reset → merge → commit → push           */
+  /* ---------------------------------------------------------------- */
+
+  async function attemptSync(config, conflicts, report) {
+    const dir = repoDirectory(config);
+    await cloneRepo({ directory: dir, repo: config.repo });
+    await ensureRepoIdentity(dir, await currentMachine());
+    const remote = await verifyRemote(config.repo);
+    if (remote.branches.length === 0) {
+      await seedEmptyRepo(dir, config.branch, await currentMachine());
+    }
+    const fetch = await fetchOrigin(dir, config.branch);
+    if (!fetch.ok) throw new BridgeError("github/fetch-failed", `не удалось получить изменения из GitHub: ${short(fetch.stderr)}`);
+    if (!(await remoteHeadExists(dir, config.branch))) {
+      throw new BridgeError("github/no-branch", `в репозитории нет ветки ${config.branch}`);
+    }
+    await resetToRemote(dir, config.branch);
+    const { targets, skipped } = await localTargets(config);
+    report.skipped.push(...skipped);
+    const storedConflicts = await listConflicts();
+    await refreshStoredConflicts(dir, targets, storedConflicts);
+    const freshStored = await listConflicts();
+    for (const target of targets) {
+      const existingConflictPaths = new Set(
+        freshStored.filter((conflict) => conflict.projectSlug === target.slug).map((conflict) => conflict.path),
+      );
+      try {
+        await mergeProject({ target, repoDir: dir, conflicts, existingConflictPaths, report });
+      } catch (error) {
+        report.warnings.push(`${target.slug}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    const message = `sync: ${(await currentMachine()).label} · ${nowIso()}${conflicts.length > 0 ? ` · conflicts: ${conflicts.length}` : ""}`;
+    const commit = await commitRepo(dir, message);
+    report.committed = commit.committed;
+    const push = await pushRepo(dir, config.branch);
+    if (!push.ok) {
+      return { ok: false, error: `push отклонён: ${short(push.stderr)}` };
+    }
+    return { ok: true, dir, targets };
+  }
+
+  function short(value, max = 240) {
+    const text = String(value ?? "").replace(/\s+/gu, " ").trim();
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+  }
+
+  async function doSync({ manual = false, reason = "manual" } = {}) {
+    const config = await currentConfig();
+    if (typeof config.repo !== "string" || config.repo.trim().length === 0) {
+      throw new BridgeError("github/not-configured", "подключите приватный GitHub-репозиторий в настройках");
+    }
+    if (!(await gitVersion())) throw new BridgeError("github/no-git", "git не найден в системе");
+    // Safety gate: never push dossiers into a repository that became public or whose
+    // visibility can no longer be confirmed. The UI shows it, the Host enforces it.
+    if (isRepoSlug(config.repo)) {
+      const visibility = await visibilityOf(config.repo);
+      if (visibility === "public") {
+        throw new BridgeError(
+          "github/repo-public",
+          `репозиторий ${config.repo} публичный. Синхронизация остановлена: сделайте репозиторий приватным и повторите`,
+        );
+      }
+      if (visibility !== "private") {
+        throw new BridgeError(
+          "github/repo-unverified",
+          `не удалось подтвердить, что ${config.repo} приватный. Синхронизация остановлена; проверьте gh auth login и доступ`,
+        );
+      }
+    }
+    const conflicts = [];
+    const report = { projects: 0, files: 0, skipped: [], warnings: [], entries: [], committed: false, conflicts: 0, pushed: false };
+    let lastError;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      try {
+        const result = await attemptSync(config, conflicts, report);
+        if (!result.ok) {
+          lastError = result.error;
+          continue;
+        }
+        report.pushed = true;
+        // successful push: refresh base snapshots from the repository
+        for (const target of result.targets) {
+          const repoProjectDir = path.join(result.dir, "projects", target.folder);
+          const canonical = await remoteSyncMap(repoProjectDir);
+          await writeBaseMap(target.folder, canonical);
+        }
+        lastError = undefined;
+        break;
+      } catch (error) {
+        lastError = error instanceof Error ? error.message : String(error);
+        if (attempt === 0 && !(await exists(path.join(repoDirectory(config), ".git")))) {
+          // clone/verify errors are not retryable
+          break;
+        }
+      }
+    }
+    for (const conflict of conflicts) {
+      await saveConflict(conflict);
+    }
+    report.conflicts = conflicts.length;
+    const next = await currentConfig();
+    if (lastError === undefined) {
+      next.lastSyncAt = nowIso();
+      next.lastError = null;
+      runtime.lastError = null;
+    } else {
+      next.lastError = lastError;
+      runtime.lastError = lastError;
+      await st.logLine(home, `sync failed (${reason}): ${lastError}`);
+    }
+    await st.saveConfig(home, next);
+    report.warnings = [...new Set(report.warnings)];
+    if (lastError !== undefined && report.pushed !== true) {
+      const error = new BridgeError("github/sync-failed", lastError);
+      error.report = report;
+      throw error;
+    }
+    return report;
+  }
+
+  async function syncNow(options = {}) {
+    if (running !== null) throw new BridgeError("sync/busy", "Синхронизация уже выполняется — подождите");
+    running = (async () => doSync({ manual: true, reason: options.reason ?? "manual" }))().finally(() => {
+      running = null;
+    });
+    return running;
+  }
+
+  /* ---------------------------------------------------------------- */
+  /* conflicts resolution                                              */
+  /* ---------------------------------------------------------------- */
+
+  async function resolveConflict(id, choice) {
+    const validChoice = choice === "remote" || choice === "both" ? choice : "local";
+    const conflict = await readConflict(id);
+    if (conflict === undefined) throw new BridgeError("github/conflict-not-found", "конфликт не найден (возможно, уже разрешён)");
+    const config = await currentConfig();
+    const { targets } = await localTargets(config);
+    const target = targets.find((item) => item.slug === conflict.projectSlug);
+    if (!target) throw new BridgeError("github/project-not-found", `проект не найден локально: ${conflict.projectSlug}`);
+    let merged = conflict.localText ?? "";
+    if (validChoice === "remote") merged = conflict.remoteText ?? "";
+    if (validChoice === "both") {
+      if (JOURNAL_FILE.test(conflict.path)) {
+        const union = mergeJournalAdditive(conflict.localText ?? "", conflict.remoteText ?? "");
+        merged = union.text;
+      } else {
+        const three = await mergeThreeWay({
+          localText: conflict.localText ?? "",
+          baseText: conflict.baseText ?? "",
+          remoteText: conflict.remoteText ?? "",
+          tmpDir: paths.tmpDir,
+        });
+        merged = three.ok ? three.text : unionText(conflict.localText ?? "", conflict.remoteText ?? "");
+      }
+    }
+    const dir = repoDirectory(config);
+    await cloneRepo({ directory: dir, repo: config.repo });
+    await ensureRepoIdentity(dir, await currentMachine());
+    const fetch = await fetchOrigin(dir, config.branch);
+    if (!fetch.ok) throw new BridgeError("github/fetch-failed", `не удалось получить изменения: ${short(fetch.stderr)}`);
+    await resetToRemote(dir, config.branch);
+    const repoProjectDir = path.join(dir, "projects", target.folder);
+    const canonical = String(merged).replace(/\r\n/gu, "\n").trimEnd();
+    const localRaw = await st.readLocalDossier(target.directory, {
+      maxFileBytes: DEFAULT_LIMITS.maxFileBytes,
+      maxBundleBytes: DEFAULT_LIMITS.maxBundleBytes,
+      maxFiles: DEFAULT_LIMITS.maxFiles,
+    });
+    const nextLocal = localFileText(conflict.path, canonical, localRaw.raw.get(conflict.path) ?? "");
+    await writeFileAtomic(path.join(target.directory, ...conflict.path.split("/")), nextLocal);
+    await writeTreeFile(repoProjectDir, conflict.path, `${canonical}\n`);
+    await commitRepo(dir, `resolve: ${conflict.projectSlug}/${conflict.path} (${validChoice}) · ${(await currentMachine()).label}`);
+    const push = await pushRepo(dir, config.branch);
+    if (!push.ok) {
+      throw new BridgeError("github/push-failed", `не удалось отправить разрешение конфликта: ${short(push.stderr)}`);
+    }
+    await removeConflict(id);
+    const canonicalMap = await remoteSyncMap(repoProjectDir);
+    await writeBaseMap(target.folder, canonicalMap);
+    const next = await currentConfig();
+    next.lastSyncAt = nowIso();
+    next.lastError = null;
+    await st.saveConfig(home, next);
+    return { ok: true, conflict: { ...conflict, resolved: validChoice } };
+  }
+
+  /* ---------------------------------------------------------------- */
+  /* history and restore                                               */
+  /* ---------------------------------------------------------------- */
+
+  async function projectHistory(slug, options = {}) {
+    const config = await currentConfig();
+    if (config.repo.length === 0) throw new BridgeError("github/not-configured", "репозиторий не подключён");
+    if (!(await gitVersion())) throw new BridgeError("github/no-git", "git не найден в системе");
+    const { targets } = await localTargets(config);
+    const target = targets.find((item) => item.slug === slug);
+    if (!target) throw new BridgeError("github/project-not-found", `проект не найден локально: ${slug}`);
+    const dir = repoDirectory(config);
+    await cloneRepo({ directory: dir, repo: config.repo });
+    try {
+      await fetchOrigin(dir, config.branch);
+    } catch {
+      /* offline: show the history we already have */
+    }
+    const reference = (await remoteHeadExists(dir, config.branch)) ? `origin/${config.branch}` : "HEAD";
+    const limit = Math.max(1, Math.min(50, Number(options.limit) || 20));
+    const log = await runGit(
+      ["log", `-${limit}`, "--format=%H%x09%aI%x09%an%x09%s", reference, "--", `projects/${target.folder}`],
+      { cwd: dir },
+    );
+    if (!log.ok) throw new BridgeError("github/log-failed", `не удалось прочитать историю: ${short(log.stderr)}`);
+    const commits = log.stdout
+      .split(/\r?\n/u)
+      .filter((line) => line.trim().length > 0)
+      .map((line) => {
+        const [sha, date, author, subject] = line.split("\t");
+        return {
+          sha: String(sha ?? ""),
+          date: String(date ?? ""),
+          author: String(author ?? ""),
+          subject: String(subject ?? ""),
+        };
+      })
+      .filter((commit) => /^[0-9a-f]{7,40}$/u.test(commit.sha));
+    return { project: { slug: target.slug, name: target.name }, commits };
+  }
+
+  async function restoreVersion(slug, commitRaw) {
+    const commit = String(commitRaw ?? "").trim();
+    if (!/^[0-9a-f]{7,40}$/u.test(commit)) throw new BridgeError("github/bad-commit", "некорректный идентификатор версии");
+    const config = await currentConfig();
+    if (config.repo.length === 0) throw new BridgeError("github/not-configured", "репозиторий не подключён");
+    if (!(await gitVersion())) throw new BridgeError("github/no-git", "git не найден в системе");
+    const { targets } = await localTargets(config);
+    const target = targets.find((item) => item.slug === slug);
+    if (!target) throw new BridgeError("github/project-not-found", `проект не найден локально: ${slug}`);
+    const dir = repoDirectory(config);
+    await cloneRepo({ directory: dir, repo: config.repo });
+    await ensureRepoIdentity(dir, await currentMachine());
+    const fetch = await fetchOrigin(dir, config.branch);
+    if (!fetch.ok) throw new BridgeError("github/fetch-failed", `не удалось получить изменения: ${short(fetch.stderr)}`);
+    await resetToRemote(dir, config.branch);
+    const check = await runGit(["cat-file", "-e", `${commit}^{commit}`], { cwd: dir });
+    if (!check.ok) throw new BridgeError("github/commit-not-found", `версия ${commit.slice(0, 8)} не найдена в репозитории`);
+    const tree = await runGit(["ls-tree", "-r", "--name-only", commit, "--", `projects/${target.folder}`], { cwd: dir });
+    if (!tree.ok) throw new BridgeError("github/log-failed", `не удалось прочитать версию: ${short(tree.stderr)}`);
+    const prefix = `projects/${target.folder}/`;
+    const files = tree.stdout
+      .split(/\r?\n/u)
+      .filter((line) => line.startsWith(prefix))
+      .map((line) => line.slice(prefix.length).replaceAll("\\", "/"))
+      .filter((relativePath) => isAllowedSyncPath(relativePath));
+    if (files.length === 0) throw new BridgeError("github/empty-version", "в этой версии нет файлов досье проекта");
+    await st.backupDossier(home, target.slug, target.directory, { maxFileBytes: DEFAULT_LIMITS.maxFileBytes });
+    const current = await st.readLocalDossier(target.directory, {
+      maxFileBytes: DEFAULT_LIMITS.maxFileBytes,
+      maxBundleBytes: DEFAULT_LIMITS.maxBundleBytes,
+      maxFiles: DEFAULT_LIMITS.maxFiles,
+    });
+    const repoProjectDir = path.join(dir, "projects", target.folder);
+    let restored = 0;
+    for (const relativePath of files) {
+      const show = await runGit(["show", `${commit}:${prefix}${relativePath}`], { cwd: dir });
+      if (!show.ok) continue;
+      const canonical = String(show.stdout).replace(/\r\n/gu, "\n").trimEnd();
+      const nextLocal = localFileText(relativePath, canonical, current.raw.get(relativePath) ?? "");
+      await writeFileAtomic(path.join(target.directory, ...relativePath.split("/")), nextLocal);
+      await writeTreeFile(repoProjectDir, relativePath, `${canonical}\n`);
+      restored += 1;
+    }
+    if (restored === 0) throw new BridgeError("github/empty-version", "нечего восстанавливать: файлы версии не прочитаны");
+    await commitRepo(dir, `restore: ${target.slug} @ ${commit.slice(0, 8)} · ${(await currentMachine()).label}`);
+    const push = await pushRepo(dir, config.branch);
+    if (!push.ok) throw new BridgeError("github/push-failed", `не удалось отправить восстановление: ${short(push.stderr)}`);
+    const canonicalMap = await remoteSyncMap(repoProjectDir);
+    await writeBaseMap(target.folder, canonicalMap);
+    const next = await currentConfig();
+    next.lastSyncAt = nowIso();
+    next.lastError = null;
+    await st.saveConfig(home, next);
+    return { restored, commit, project: { slug: target.slug, name: target.name } };
+  }
+
+  /* ---------------------------------------------------------------- */
+  /* portable USB transfer                                            */
+  /* ---------------------------------------------------------------- */
+
+  async function portableTargets() {
+    const config = await currentConfig();
+    return (await localTargets(config)).targets;
+  }
+
+  async function portableExport(destination) {
+    return exportPortable({
+      home,
+      destination,
+      targets: await portableTargets(),
+      machine: await currentMachine(),
+    });
+  }
+
+  async function portableScan(source) {
+    return scanPortable({ home, source, targets: await portableTargets() });
+  }
+
+  async function portableImport(source, options = {}) {
+    return importPortable({
+      home,
+      source,
+      targets: await portableTargets(),
+      projectSlugs: options.projectSlugs,
+      strategy: options.strategy,
+    });
+  }
+
+  /* ---------------------------------------------------------------- */
+  /* configuration and status                                          */
+  /* ---------------------------------------------------------------- */
+
+  async function configure(repoRaw, branchRaw) {
+    const repo = String(repoRaw ?? "").trim();
+    if (repo.length === 0) throw new BridgeError("github/bad-repo", "укажите репозиторий owner/name");
+    const branch = typeof branchRaw === "string" && branchRaw.trim().length > 0 ? branchRaw.trim() : "main";
+    repoRemoteUrl(repo); // validates shape
+    if (!(await gitVersion())) throw new BridgeError("github/no-git", "git не найден в системе — установите Git for Windows");
+    if (isRepoSlug(repo)) {
+      const visibility = await visibilityOf(repo, { force: true });
+      if (visibility === "public") {
+        throw new BridgeError(
+          "github/repo-public",
+          `репозиторий ${repo} публичный. Плагин работает только с приватным репозиторием — создайте приватный и подключите его`,
+        );
+      }
+      if (visibility !== "private") {
+        throw new BridgeError(
+          "github/repo-unverified",
+          `не удалось подтвердить, что ${repo} приватный. Проверьте, что GitHub CLI авторизован (gh auth login) и у вас есть доступ к репозиторию`,
+        );
+      }
+    }
+    const remote = await verifyRemote(repo);
+    if (remote.branches.length > 0 && !remote.branches.includes(branch)) {
+      throw new BridgeError("github/bad-branch", `в репозитории нет ветки ${branch}; доступны: ${remote.branches.join(", ")}`);
+    }
+    const config = await currentConfig();
+    config.repo = repo;
+    config.branch = branch;
+    await st.saveConfig(home, config);
+    try {
+      await cloneRepo({ directory: repoDirectory(config), repo });
+    } catch (error) {
+      config.lastError = error instanceof Error ? error.message : String(error);
+      await st.saveConfig(home, config);
+      throw error;
+    }
+    return { repo, branch, branches: remote.branches };
+  }
+
+  /**
+   * Create a private exchange repository under the authenticated GitHub account
+   * and connect it. Never defaults to somebody else's account: the owner is the
+   * login of the current machine's `gh` session.
+   */
+  async function createRepo(repoRaw) {
+    const github = await githubSnapshot({ force: true });
+    if (!github.available) {
+      throw new BridgeError("github/no-gh", "GitHub CLI (gh) не найден. Установите gh и выполните вход: gh auth login");
+    }
+    if (!github.authenticated) {
+      throw new BridgeError("github/no-auth", "Вы не вошли в GitHub. Выполните в терминале: gh auth login");
+    }
+    const repo = typeof repoRaw === "string" && repoRaw.trim().length > 0 ? repoRaw.trim() : suggestedExchangeRepo(github.login);
+    if (!isRepoSlug(repo)) throw new BridgeError("github/bad-repo", "укажите репозиторий в виде owner/name");
+    const visibility = await visibilityOf(repo, { force: true });
+    if (visibility === "public") {
+      throw new BridgeError("github/repo-public", `репозиторий ${repo} уже существует и он публичный — плагин работает только с приватными`);
+    }
+    let created = false;
+    if (visibility !== "private") {
+      try {
+        await ghApi.createRepo(repo);
+        created = true;
+      } catch (error) {
+        if (!(error instanceof BridgeError) || error.code !== "github/repo-exists") throw error;
+      }
+    }
+    await configure(repo, "main");
+    return { created, repo, owner: github.login, status: await status() };
+  }
+
+  async function setEnabled(enabled) {
+    const config = await currentConfig();
+    if (enabled === true && config.repo.length === 0) {
+      throw new BridgeError("github/not-configured", "сначала подключите приватный репозиторий");
+    }
+    config.enabled = enabled === true;
+    await st.saveConfig(home, config);
+    return { enabled: config.enabled };
+  }
+
+  async function setOptions(options = {}) {
+    const config = await currentConfig();
+    if (Number.isFinite(Number(options.intervalSeconds))) {
+      config.intervalSeconds = Math.max(60, Math.min(3600, Math.trunc(Number(options.intervalSeconds))));
+    }
+    if (typeof options.autoSync === "boolean") config.autoSync = options.autoSync;
+    if (Array.isArray(options.excludeProjects)) {
+      config.excludeProjects = options.excludeProjects.filter((item) => typeof item === "string").slice(0, 200);
+    }
+    await st.saveConfig(home, config);
+    return { intervalSeconds: config.intervalSeconds, autoSync: config.autoSync, excludeProjects: config.excludeProjects };
+  }
+
+  async function status() {
+    const config = await currentConfig();
+    const me = await currentMachine();
+    const gitAvailable = Boolean(await gitVersion());
+    const github = await githubSnapshot();
+    const configured = config.repo.length > 0;
+    const repoVisibilityValue = configured ? await visibilityOf(config.repo) : null;
+    const dir = configured ? repoDirectory(config) : "";
+    const repoCloned = configured ? await exists(path.join(dir, ".git")) : false;
+    const conflicts = await listConflicts();
+    const resolved = await localTargets(config);
+    const targets = resolved.targets;
+    const skipped = resolved.skipped;
+    const repoProjects = [];
+    if (configured && repoCloned) {
+      try {
+        for (const entry of await fsp.readdir(path.join(dir, "projects"), { withFileTypes: true })) {
+          if (!entry.isDirectory()) continue;
+          try {
+            const meta = JSON.parse(await fsp.readFile(path.join(dir, "projects", entry.name, "project.json"), "utf8"));
+            repoProjects.push({ folder: entry.name, slug: meta.slug ?? entry.name, name: meta.name ?? meta.slug ?? entry.name, fingerprint: meta.fingerprint });
+          } catch {
+            repoProjects.push({ folder: entry.name, slug: entry.name, name: entry.name });
+          }
+        }
+      } catch {
+        /* empty repository */
+      }
+    }
+    const projects = [];
+    let localChanges = 0;
+    for (const target of targets) {
+      const local = await localSyncMap(target);
+      const base = await readBaseMap(target.folder);
+      const hasConflict = conflicts.some((conflict) => conflict.projectSlug === target.slug);
+      let state = "synced";
+      if (hasConflict) state = "conflict";
+      else if (mapDiffers(local.map, base)) {
+        state = "local-changes";
+        localChanges += 1;
+      }
+      projects.push({ slug: target.slug, name: target.name, status: state, lastSyncAt: config.lastSyncAt ?? null });
+    }
+    const localSlugs = new Set(targets.map((target) => target.slug));
+    for (const repoProject of repoProjects) {
+      if (localSlugs.has(repoProject.slug)) continue;
+      projects.push({ slug: repoProject.slug, name: repoProject.name, status: "not-opened", lastSyncAt: null });
+    }
+    const conflictPreviews = conflicts.map((conflict) => ({
+      id: conflict.id,
+      projectSlug: conflict.projectSlug,
+      projectName: conflict.projectName,
+      path: conflict.path,
+      localPreview: preview(conflict.localText),
+      remotePreview: preview(conflict.remoteText),
+      createdAt: conflict.createdAt,
+    }));
+    return {
+      ok: true,
+      configured,
+      enabled: config.enabled,
+      repo: config.repo,
+      branch: config.branch,
+      repoUrl: configured ? repoWebUrl(config.repo) : "",
+      repoVisibility: repoVisibilityValue,
+      localDir: dir,
+      gitAvailable,
+      github: { ...github, repoVisibility: repoVisibilityValue },
+      suggestedRepo: github.suggestedRepo,
+      repoCloned,
+      lastSyncAt: config.lastSyncAt ?? null,
+      lastError: config.lastError ?? null,
+      machine: { id: me.machineId, label: me.label },
+      pending: { localChanges, unpushed: false },
+      conflicts: conflictPreviews,
+      projects,
+      skipped,
+      options: {
+        intervalSeconds: config.intervalSeconds,
+        autoSync: config.autoSync,
+        excludeProjects: config.excludeProjects,
+      },
+    };
+  }
+
+    function preview(text, max = 900) {
+      const value = String(text ?? "");
+      return value.length > max ? `${value.slice(0, max - 1)}…` : value;
+    }
+
+  async function autoSync({ reason = "timer" } = {}) {
+    if (running !== null) return { skipped: true, reason: "busy" };
+    const config = await currentConfig();
+    if (!config.enabled || !config.autoSync || config.repo.length === 0) return { skipped: true, reason: "disabled" };
+    if (!(await gitVersion())) return { skipped: true, reason: "no-git" };
+    const interval = Math.max(60, Math.min(3600, config.intervalSeconds)) * 1000;
+    if (Date.now() - runtime.lastAutoAt < interval) return { skipped: true, reason: "interval" };
+    runtime.lastAutoAt = Date.now();
+    try {
+      return await syncNow({ reason });
+    } catch (error) {
+      runtime.lastError = error instanceof Error ? error.message : String(error);
+      await st.logLine(home, `auto sync failed (${reason}): ${runtime.lastError}`);
+      return { ok: false, error: runtime.lastError };
+    }
+  }
+
+  function isBusy() {
+    return running !== null;
+  }
+
+  return {
+    init,
+    status,
+    configure,
+    createRepo,
+    setEnabled,
+    history: projectHistory,
+    restoreVersion,
+    portableExport,
+    portableScan,
+    portableImport,
+    setOptions,
+    syncNow,
+    resolveConflict,
+    autoSync,
+    config: currentConfig,
+    machine: currentMachine,
+    paths,
+    isBusy,
+  };
+}