dsh-desktop-kit 2.2.1 → 2.7.3

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

@@ -0,0 +1,473 @@
+/**
+ * dsh-memory-bridge — GitHub transport primitives.
+ *
+ * The exchange repository holds the merged dossier itself (not per-machine
+ * snapshots). A machine keeps local dossiers as its working copy and a local
+ * snapshot of the last successfully synchronised content ("base"). A sync cycle
+ * is: fetch origin → reset the derived clone → three-way merge every file
+ * (local / base / origin) → commit → push with retry. A rejected push is never
+ * forced: the cycle re-fetches and merges again, so another machine's work
+ * cannot be overwritten by "whoever pushed last".
+ */
+
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  BridgeError,
+  DEFAULT_LIMITS,
+  JOURNAL_FILE,
+  SECTION_FILES,
+  canonicalizePaths,
+  ensureDir,
+  exists,
+  extractAutoScanBlocks,
+  isTemplateContent,
+  localizePaths,
+  normalizeLf,
+  readTextIfExists,
+  redactSecrets,
+  sha256,
+  stripAutoScan,
+  writeFileAtomic,
+} from "./bridge.js";
+import { splitJournal } from "./merge.js";
+
+const GIT_TIMEOUT_MS = 120_000;
+const MAX_GIT_OUTPUT = 64 * 1024;
+
+/* ------------------------------------------------------------------ */
+/* git process                                                         */
+/* ------------------------------------------------------------------ */
+
+function lastLine(value, max = 300) {
+  const text = String(value ?? "").trim().split(/\r?\n/u).filter(Boolean).at(-1) ?? "";
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+export function runProcess(command, args, { cwd, env = {}, timeoutMs = GIT_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, args, {
+        cwd,
+        windowsHide: true,
+        env: {
+          ...process.env,
+          GIT_TERMINAL_PROMPT: "0",
+          GCM_INTERACTIVE: "Never",
+          GIT_MERGE_AUTOEDIT: "no",
+          ...env,
+        },
+      });
+    } catch (error) {
+      resolve({ ok: false, code: -1, stdout: "", stderr: `${command} spawn failed: ${String(error)}` });
+      return;
+    }
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      try {
+        child.kill();
+      } catch {
+        /* already gone */
+      }
+      settled = true;
+      resolve({ ok: false, code: -1, stdout, stderr: `${stderr}\nтаймаут ${command} ${timeoutMs} мс`.trim() });
+    }, timeoutMs);
+    timer.unref?.();
+    child.stdout?.on("data", (chunk) => {
+      stdout = `${stdout}${chunk.toString()}`.slice(-MAX_GIT_OUTPUT);
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr = `${stderr}${chunk.toString()}`.slice(-MAX_GIT_OUTPUT);
+    });
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ ok: false, code: -1, stdout, stderr: `${stderr}\n${String(error)}`.trim() });
+    });
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ ok: code === 0, code: Number(code), stdout, stderr });
+    });
+  });
+}
+
+export function runGit(args, options = {}) {
+  return runProcess("git", args, options);
+}
+
+export function runGh(args, options = {}) {
+  return runProcess("gh", args, { timeoutMs: 60_000, ...options });
+}
+
+export async function gitVersion() {
+  const result = await runGit(["--version"], { timeoutMs: 15_000 });
+  return result.ok ? result.stdout.trim() : undefined;
+}
+
+export async function ghVersion() {
+  const result = await runGh(["--version"], { timeoutMs: 15_000 });
+  return result.ok ? result.stdout.trim().split(/\r?\n/u)[0] : undefined;
+}
+
+/** Login of the GitHub account authenticated in the `gh` CLI, if any. */
+export async function ghLogin() {
+  const result = await runGh(["api", "user", "--jq", ".login"], { timeoutMs: 20_000 });
+  if (!result.ok) return undefined;
+  const login = result.stdout.trim();
+  return /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/u.test(login) ? login : undefined;
+}
+
+/** `private`, `public`, `missing` or `unknown` (no gh / no access). */
+export async function repoVisibility(repo) {
+  if (!isRepoSlug(repo)) return "unknown";
+  const result = await runGh(["repo", "view", repo, "--json", "visibility", "--jq", ".visibility"], { timeoutMs: 25_000 });
+  if (result.ok) {
+    const visibility = result.stdout.trim().toLowerCase();
+    return visibility === "private" || visibility === "public" ? visibility : "unknown";
+  }
+  if (/not found|could not resolve/i.test(result.stderr)) return "missing";
+  return "unknown";
+}
+
+export async function createPrivateRepo(repo, description = "Private exchange repository for DSH project-memory dossiers") {
+  if (!isRepoSlug(repo)) throw new BridgeError("github/bad-repo", "укажите репозиторий в виде owner/name");
+  const result = await runGh(["repo", "create", repo, "--private", "--add-readme", "--description", description], {
+    timeoutMs: 90_000,
+  });
+  if (!result.ok) {
+    if (/already exists|name already exists/i.test(result.stderr)) {
+      throw new BridgeError("github/repo-exists", `репозиторий ${repo} уже существует — нажмите «Подключить существующий»`);
+    }
+    throw new BridgeError("github/create-failed", gitError(result, `не удалось создать приватный репозиторий ${repo}`));
+  }
+  return { repo };
+}
+
+/* ------------------------------------------------------------------ */
+/* repository URLs and local directories                               */
+/* ------------------------------------------------------------------ */
+
+const REPO_SLUG = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u;
+
+export function isRepoSlug(value) {
+  return typeof value === "string" && REPO_SLUG.test(value.trim());
+}
+
+/** Default exchange repository name for one GitHub account. */
+export function suggestedExchangeRepo(login) {
+  return typeof login === "string" && login.length > 0 ? `${login}/dsh-memory-exchange` : null;
+}
+
+/** Accept `owner/name` (GitHub), an HTTPS/SSH URL, or a local path (tests). */
+export function repoRemoteUrl(repo) {
+  const value = String(repo ?? "").trim();
+  if (value.length === 0) throw new BridgeError("github/no-repo", "репозиторий не задан");
+  if (isRepoSlug(value)) return `https://github.com/${value}.git`;
+  if (/^https?:\/\//iu.test(value) || /^git@/iu.test(value)) return value;
+  if (path.isAbsolute(value) || /^[A-Za-z]:[\\/]/u.test(value)) return value;
+  throw new BridgeError("github/bad-repo", "укажите репозиторий в виде owner/name");
+}
+
+export function repoFolderName(repo) {
+  return String(repo ?? "")
+    .trim()
+    .replace(/^https?:\/\/github\.com\//iu, "")
+    .replace(/\.git$/iu, "")
+    .replace(/[^A-Za-z0-9._-]+/gu, "-")
+    .slice(0, 80) || "exchange";
+}
+
+export function repoWebUrl(repo) {
+  const value = String(repo ?? "").trim();
+  return isRepoSlug(value) ? `https://github.com/${value}` : value;
+}
+
+function gitError(result, fallback) {
+  const detail = lastLine(result?.stderr) || lastLine(result?.stdout);
+  return detail.length > 0 ? `${fallback}: ${detail}` : fallback;
+}
+
+/* ------------------------------------------------------------------ */
+/* clone / fetch / commit / push                                       */
+/* ------------------------------------------------------------------ */
+
+export async function cloneRepo({ directory, repo }) {
+  const url = repoRemoteUrl(repo);
+  await ensureDir(path.dirname(directory));
+  if (await exists(path.join(directory, ".git"))) return { ok: true, cloned: false, url };
+  if (await exists(directory)) {
+    // A derived clone without .git is disposable: rebuild it from the remote.
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+  const result = await runGit(["clone", "--origin", "origin", url, directory]);
+  if (!result.ok) throw new BridgeError("github/clone-failed", gitError(result, `не удалось клонировать ${url}`));
+  return { ok: true, cloned: true, url };
+}
+
+export async function verifyRemote(repo) {
+  const url = repoRemoteUrl(repo);
+  const result = await runGit(["ls-remote", "--heads", url], { timeoutMs: 45_000 });
+  if (!result.ok) throw new BridgeError("github/no-access", gitError(result, `нет доступа к ${url}`));
+  const branches = result.stdout
+    .split(/\r?\n/u)
+    .map((line) => line.split(/\s+/u).at(-1) ?? "")
+    .map((line) => line.replace(/^refs\/heads\//u, ""))
+    .filter(Boolean);
+  return { url, branches };
+}
+
+export async function fetchOrigin(directory, branch) {
+  return runGit(["fetch", "--prune", "origin", branch], { cwd: directory });
+}
+
+export async function remoteHeadExists(directory, branch) {
+  const result = await runGit(["rev-parse", "--verify", "--quiet", `origin/${branch}`], { cwd: directory });
+  return result.ok;
+}
+
+export async function resetToRemote(directory, branch) {
+  const result = await runGit(["reset", "--hard", `origin/${branch}`], { cwd: directory });
+  if (!result.ok) throw new BridgeError("github/reset-failed", gitError(result, "не удалось обновить локальный клон репозитория"));
+  const clean = await runGit(["clean", "-fd", "projects"], { cwd: directory });
+  if (!clean.ok) throw new BridgeError("github/clean-failed", gitError(clean, "не удалось очистить клон репозитория"));
+}
+
+export async function ensureRepoIdentity(directory, machine) {
+  const name = await runGit(["config", "user.name"], { cwd: directory });
+  if (!name.ok || name.stdout.trim().length === 0) {
+    await runGit(["config", "user.name", `DSH Memory Bridge (${machine?.label ?? "machine"})`], { cwd: directory });
+  }
+  const email = await runGit(["config", "user.email"], { cwd: directory });
+  if (!email.ok || email.stdout.trim().length === 0) {
+    const safe = String(machine?.machineId ?? "machine").replace(/[^A-Za-z0-9._-]+/gu, "");
+    await runGit(["config", "user.email", `${safe}@dsh-memory-bridge.local`], { cwd: directory });
+  }
+}
+
+export async function commitRepo(directory, message) {
+  const add = await runGit(["add", "-A"], { cwd: directory });
+  if (!add.ok) throw new BridgeError("github/add-failed", gitError(add, "не удалось подготовить изменения"));
+  const staged = await runGit(["diff", "--cached", "--quiet"], { cwd: directory });
+  if (staged.ok) return { committed: false };
+  const commit = await runGit(["commit", "-m", message], { cwd: directory });
+  if (!commit.ok) throw new BridgeError("github/commit-failed", gitError(commit, "не удалось создать commit"));
+  return { committed: true };
+}
+
+export async function pushRepo(directory, branch) {
+  return runGit(["push", "origin", `HEAD:${branch}`], { cwd: directory });
+}
+
+/** Create the first commit when the remote repository is completely empty. */
+export async function seedEmptyRepo(directory, branch, machine) {
+  await ensureRepoIdentity(directory, machine);
+  await ensureDir(path.join(directory, "projects"));
+  const readme = path.join(directory, "README.md");
+  if (!(await exists(readme))) {
+    const created = new Date().toISOString().slice(0, 10);
+    await writeFileAtomic(
+      readme,
+      `# dsh-memory-exchange\n\n![dsh-memory-bridge](https://cdn.jsdelivr.net/npm/dsh-memory-bridge@latest/docs/images/hero.png)\n\n**Приватный репозиторий обмена памятью проектов DeepSeek Harness.**\n\nСоздан плагином [\`dsh-memory-bridge\`](https://www.npmjs.com/package/dsh-memory-bridge)\nна машине «${machine?.label ?? "machine"}» ${created}.\n\nСюда плагин складывает **объединённые досье проектов**; вручную редактировать\nфайлы не нужно — плагин сам сливает изменения с разных АРМ.\n\n## Что внутри\n\n| Путь | Назначение |\n|---|---|\n| \`projects/<проект>--<key8>/\` | досье проекта: 6 разделов + журнал |\n| \`projects/<проект>--<key8>/project.json\` | fingerprint, имя, последний автор записи |\n| \`JOURNAL/YYYY-MM.md\` | журнал сессий проекта |\n\n## Как это работает\n\n1. Каждая машина перед синхронизацией получает свежую версию из этого репозитория.\n2. Досье сливается «моё / прошлая общая версия / версия из GitHub» (трёхстороннее слияние).\n3. Если одна и та же строка изменена по-разному — плагин показывает конфликт и не перезаписывает файл молча.\n\n## Безопасность\n\n- Репозиторий **приватный**: доступ только у владельца GitHub-аккаунта.\n- Плагин вырезает секреты и PII, домашние пути заменяет токеном \`%DSH_HOME%\`.\n- Не добавляйте сюда ключи, пароли, дампы и другие секреты вручную.\n\n## Управление\n\nВ DSH: **Настройки → «Память проектов»**. Останавливать синхронизацию удалением\nрепозитория не нужно — выключите её переключателем на странице.\n`,
+    );
+  }
+  await runGit(["add", "-A"], { cwd: directory });
+  const commit = await runGit(["commit", "-m", `init: exchange repository (${machine?.label ?? "machine"})`], { cwd: directory });
+  if (!commit.ok) throw new BridgeError("github/init-failed", gitError(commit, "не удалось создать первый commit"));
+  const push = await pushRepo(directory, branch);
+  if (!push.ok) throw new BridgeError("github/push-failed", gitError(push, "не удалось отправить первый commit"));
+}
+
+/* ------------------------------------------------------------------ */
+/* content canonicalisation and three-way merge                        */
+/* ------------------------------------------------------------------ */
+
+/** Text that participates in comparison/merge: canonical, redacted, no AUTO-SCAN. */
+export function syncText(relativePath, rawText) {
+  const redacted = normalizeLf(redactSecrets(rawText ?? ""));
+  const manual = SECTION_FILES.includes(relativePath) ? stripAutoScan(redacted) : redacted;
+  return canonicalizePaths(manual).trimEnd();
+}
+
+/** Local file content from merged canonical text: local home + its own AUTO-SCAN blocks. */
+export function localFileText(relativePath, mergedText, localRawText) {
+  const localized = localizePaths(mergedText).trimEnd();
+  if (!SECTION_FILES.includes(relativePath)) return `${localized}\n`;
+  const blocks = extractAutoScanBlocks(localRawText ?? "");
+  const parts = [localized];
+  for (const block of blocks) parts.push(block.trim());
+  return `${parts.filter((part) => part.length > 0).join("\n\n")}\n`;
+}
+
+export async function readTreeFiles(directory) {
+  const files = new Map();
+  const add = async (relativePath) => {
+    const text = await readTextIfExists(path.join(directory, ...relativePath.split("/")));
+    if (text !== undefined) files.set(relativePath, text);
+  };
+  for (const name of SECTION_FILES) await add(name);
+  try {
+    const entries = (await fs.readdir(path.join(directory, "JOURNAL"), { withFileTypes: true }))
+      .filter((entry) => entry.isFile() && /^\d{4}-\d{2}\.md$/u.test(entry.name))
+      .map((entry) => entry.name)
+      .sort();
+    for (const name of entries) await add(`JOURNAL/${name}`);
+  } catch {
+    /* no journal */
+  }
+  return files;
+}
+
+export async function writeTreeFile(directory, relativePath, text) {
+  const target = path.join(directory, ...relativePath.split("/"));
+  await writeFileAtomic(target, text);
+}
+
+async function writeTemp(file, text) {
+  await ensureDir(path.dirname(file));
+  await writeFileAtomic(file, text, { mode: 0o600 });
+}
+
+function resolveAdditiveHunk(hunk) {
+  const all = [...hunk.local, ...hunk.remote];
+  const meaningful = all.map((line) => line.trim()).filter((line) => line.length > 0);
+  if (meaningful.length === 0) return { ok: true, lines: [] };
+  const additive = meaningful.every(
+    (line) => /^[-*]\s+/u.test(line) || /^#{2,4}\s+/u.test(line) || /^\d+\.\s+/u.test(line),
+  );
+  if (!additive) return { ok: false };
+  const seen = new Set();
+  const lines = [];
+  for (const line of all) {
+    const key = line.trim();
+    if (key.length === 0) {
+      lines.push(line);
+      continue;
+    }
+    if (seen.has(key)) continue;
+    seen.add(key);
+    lines.push(line);
+  }
+  return { ok: true, lines };
+}
+
+/**
+ * Three-way merge via `git merge-file`; additive hunks are resolved to a union,
+ * everything else is returned as an unresolved conflict (the caller keeps the
+ * local file and asks the user).
+ * @returns {Promise<{ok:boolean, text:string, unresolved:number, hunks:number}>}
+ */
+export async function mergeThreeWay({ localText, baseText, remoteText, tmpDir }) {
+  const stamp = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2, 8)}`;
+  const localPath = path.join(tmpDir, `${stamp}.local.md`);
+  const basePath = path.join(tmpDir, `${stamp}.base.md`);
+  const remotePath = path.join(tmpDir, `${stamp}.remote.md`);
+  await writeTemp(localPath, `${normalizeLf(localText).trimEnd()}\n`);
+  await writeTemp(basePath, `${normalizeLf(baseText ?? "").trimEnd()}\n`);
+  await writeTemp(remotePath, `${normalizeLf(remoteText).trimEnd()}\n`);
+  try {
+    const result = await runGit(
+      ["merge-file", "-p", "--diff3", "-L", "local", "-L", "base", "-L", "github", localPath, basePath, remotePath],
+      { timeoutMs: 30_000 },
+    );
+    const merged = result.stdout.replace(/\r\n/gu, "\n");
+    if (result.ok && result.code === 0) {
+      return { ok: true, text: merged.trimEnd(), unresolved: 0, hunks: 0 };
+    }
+    if (result.code > 0) {
+      const lines = merged.split("\n");
+      const resolvedLines = [];
+      let unresolved = 0;
+      let hunks = 0;
+      let mode = "normal";
+      let current;
+      for (const line of lines) {
+        if (line.startsWith("<<<<<<<")) {
+          current = { local: [], remote: [] };
+          mode = "local";
+          hunks += 1;
+          continue;
+        }
+        if (line.startsWith("|||||||")) {
+          mode = "base";
+          continue;
+        }
+        if (line.startsWith("=======") && current !== undefined) {
+          mode = "remote";
+          continue;
+        }
+        if (line.startsWith(">>>>>>>") && current !== undefined) {
+          const resolved = resolveAdditiveHunk(current);
+          if (resolved.ok) resolvedLines.push(...resolved.lines);
+          else {
+            unresolved += 1;
+            resolvedLines.push(...current.local);
+          }
+          current = undefined;
+          mode = "normal";
+          continue;
+        }
+        if (current !== undefined) {
+          if (mode === "local") current.local.push(line);
+          else if (mode === "remote") current.remote.push(line);
+          continue;
+        }
+        resolvedLines.push(line);
+      }
+      return {
+        ok: unresolved === 0,
+        text: resolvedLines.join("\n").trimEnd(),
+        unresolved,
+        hunks,
+      };
+    }
+    throw new BridgeError("github/merge-failed", gitError(result, "git merge-file завершился ошибкой"));
+  } finally {
+    for (const file of [localPath, basePath, remotePath]) {
+      try {
+        await fs.rm(file, { force: true });
+      } catch {
+        /* temp cleanup best effort */
+      }
+    }
+  }
+}
+
+/** Journal-specific fallback: union entries, keep both sides when headers collide differently. */
+export function mergeJournalAdditive(localText, remoteText) {
+  const local = splitJournal(localText);
+  const remote = splitJournal(remoteText);
+  const localKeys = new Set(local.entries.map((entry) => entry.key));
+  const headers = new Map(local.entries.map((entry) => [entry.header, entry]));
+  const conflicts = [];
+  const additions = [];
+  for (const entry of remote.entries) {
+    const twin = headers.get(entry.header);
+    if (twin !== undefined && twin.key !== entry.key) {
+      conflicts.push(entry);
+      continue;
+    }
+    if (localKeys.has(entry.key)) continue;
+    localKeys.add(entry.key);
+    additions.push(entry);
+  }
+  if (additions.length === 0) {
+    return { text: localText.trimEnd(), added: 0, conflicts };
+  }
+  const head = local.head.length > 0 ? local.head : remote.head;
+  const entries = [...local.entries, ...additions].sort((left, right) => (left.time ?? 0) - (right.time ?? 0));
+  const pieces = head.length > 0 ? [head, ...entries.map((entry) => entry.raw)] : entries.map((entry) => entry.raw);
+  return { text: `${pieces.join("\n\n").trimEnd()}\n`, added: additions.length, conflicts };
+}
+
+export function hashText(text) {
+  return sha256(text);
+}

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

@@ -0,0 +1,205 @@
+/**
+ * dsh-memory-bridge — safe merge decisions.
+ *
+ * Rules (v1), deliberately conservative:
+ *  - a remote version is accepted wholesale only when the local file did not
+ *    change since the last synchronised state (`sha256(local) === base[path]`),
+ *    when the local file is still a fresh project template, or when it is missing;
+ *  - journals are merged additively: remote entries never overwrite local ones;
+ *  - any other concurrent change is a conflict: local stays, remote goes to
+ *    `incoming/` and the conflict report — never guessed.
+ */
+
+import { SECTION_FILES, JOURNAL_FILE, sha256, stripAutoScan, isTemplateContent } from "./bridge.js";
+
+const JOURNAL_HEADER = /^#{2,3}\s+(\d{4})-(\d{2})-(\d{2})(?:\s+(\d{2}):(\d{2}))?/u;
+
+function normaliseHeader(header) {
+  return String(header ?? "").replace(/\s+/gu, " ").trim();
+}
+
+function normaliseBody(body) {
+  return String(body ?? "")
+    .replace(/\r\n/gu, "\n")
+    .replace(/[ \t]+$/gmu, "")
+    .trim();
+}
+
+function entryTime(header) {
+  const match = JOURNAL_HEADER.exec(String(header ?? ""));
+  if (!match) return 0;
+  return Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]), Number(match[4] ?? 0), Number(match[5] ?? 0));
+}
+
+/**
+ * Split a journal file into a leading head and entries.
+ * Supports both formats used by the kit:
+ *   `## YYYY-MM-DD — title`      (manual records from the skill template)
+ *   `### YYYY-MM-DD HH:MM · ...` (automatic records written by project-memory)
+ * @returns {{head:string, entries:Array<{header:string, body:string, raw:string, key:string, time:number}>}}
+ */
+export function splitJournal(text) {
+  const value = String(text ?? "");
+  if (value.trim().length === 0) return { head: "", entries: [] };
+  const headLines = [];
+  const entries = [];
+  let current;
+  for (const line of value.split(/\r?\n/u)) {
+    if (JOURNAL_HEADER.test(line)) {
+      if (current) entries.push(current);
+      current = { header: line.trimEnd(), body: [] };
+      continue;
+    }
+    if (current) current.body.push(line);
+    else headLines.push(line);
+  }
+  if (current) entries.push(current);
+  return {
+    head: normaliseBody(headLines.join("\n")),
+    entries: entries.map(({ header, body }) => {
+      const bodyText = normaliseBody(body.join("\n"));
+      const raw = `${normaliseHeader(header)}\n${bodyText}`.trimEnd();
+      return {
+        header: normaliseHeader(header),
+        body: bodyText,
+        raw,
+        key: sha256(`${normaliseHeader(header)}\n${bodyText}`),
+        time: entryTime(header),
+      };
+    }),
+  };
+}
+
+/**
+ * Additive journal merge: local entries win, remote-only entries are inserted.
+ * @returns {{text:string, added:number, conflicts:Array<{header:string, remote:string}>}}
+ */
+export function mergeJournal(localText, remoteText) {
+  const local = splitJournal(localText);
+  const remote = splitJournal(remoteText);
+  const known = new Set(local.entries.map((entry) => entry.key));
+  const added = [];
+  const conflicts = [];
+  const byHeader = new Map(local.entries.map((entry) => [entry.header, entry]));
+  for (const entry of remote.entries) {
+    const twin = byHeader.get(entry.header);
+    if (twin !== undefined && twin.key !== entry.key) {
+      conflicts.push({ header: entry.header, remote: entry.raw });
+      continue;
+    }
+    if (known.has(entry.key)) continue;
+    known.add(entry.key);
+    added.push(entry);
+  }
+  const merged = [...local.entries, ...added].sort((left, right) => {
+    if (left.time !== right.time) return left.time - right.time;
+    return left.header.localeCompare(right.header, "ru");
+  });
+  const pieces = [];
+  if (local.head.length > 0) pieces.push(local.head);
+  else if (remote.head.length > 0) pieces.push(remote.head);
+  for (const entry of merged) pieces.push(entry.raw);
+  return {
+    text: `${pieces.join("\n\n").trimEnd()}\n`,
+    added: added.length,
+    conflicts,
+  };
+}
+
+/**
+ * Decide what to do with every file present on either side.
+ *
+ * A remote version is accepted wholesale only when the remote bundle says it
+ * changed from the same base the local machine last synchronised with
+ * (`remote.files[].base === localBase[path]`). This blocks a stale machine from
+ * rolling a newer local file back while still allowing fast-forward.
+ *
+ * @param {{localContent:Map<string,string>, remoteContent:Map<string,string>,
+ *          baseHashes:Record<string,string>|Map<string,string>,
+ *          remoteBases?:Record<string,string|null>|Map<string,string|null>,
+ *          force?:boolean}} input
+ * @returns {Array<{path:string, action:'none'|'take-remote'|'journal'|'conflict',
+ *                  local?:string, remote?:string, reason:string, force?:boolean}>}
+ */
+export function decideSync({ localContent, remoteContent, baseHashes, remoteBases, force = false }) {
+  const base = baseHashes instanceof Map ? baseHashes : new Map(Object.entries(baseHashes ?? {}));
+  const remoteBaseMap = remoteBases instanceof Map ? remoteBases : new Map(Object.entries(remoteBases ?? {}));
+  const paths = new Set([...localContent.keys(), ...remoteContent.keys()]);
+  const decisions = [];
+  for (const relativePath of [...paths].sort()) {
+    const remote = remoteContent.get(relativePath);
+    if (remote === undefined) {
+      // A remote bundle without this file is not a deletion request: keep local.
+      decisions.push({ path: relativePath, action: "none", reason: "только локальный файл" });
+      continue;
+    }
+    const local = localContent.get(relativePath);
+    if (local === undefined) {
+      decisions.push({ path: relativePath, action: "take-remote", remote, reason: "локального файла нет" });
+      continue;
+    }
+    if (local === remote) {
+      decisions.push({ path: relativePath, action: "none", reason: "совпадает" });
+      continue;
+    }
+    const isJournal = JOURNAL_FILE.test(relativePath);
+    if (isJournal) {
+      decisions.push({ path: relativePath, action: "journal", local, remote, reason: "аддитивное слияние журнала" });
+      continue;
+    }
+    const knownHash = base.get(relativePath);
+    const remoteBase = remoteBaseMap.get(relativePath) ?? null;
+    const localHash = sha256(local);
+    if (force) {
+      decisions.push({ path: relativePath, action: "take-remote", local, remote, force: true, reason: "принудительный импорт (--force)" });
+      continue;
+    }
+    if (isTemplateContent(local) && (knownHash === undefined || knownHash === localHash)) {
+      decisions.push({ path: relativePath, action: "take-remote", local, remote, reason: "локальный файл — шаблон проекта" });
+      continue;
+    }
+    const remoteHash = sha256(remote);
+    if (knownHash !== undefined && remoteBase !== null && remoteBase === knownHash) {
+      if (localHash === knownHash) {
+        decisions.push({ path: relativePath, action: "take-remote", local, remote, reason: "локально не менялось, чужая версия из той же базы" });
+        continue;
+      }
+      if (remoteHash === knownHash) {
+        decisions.push({ path: relativePath, action: "none", reason: "чужая версия не менялась" });
+        continue;
+      }
+      decisions.push({ path: relativePath, action: "conflict", local, remote, reason: "обе стороны менялись от одной базы" });
+      continue;
+    }
+    if (knownHash === undefined) {
+      decisions.push({ path: relativePath, action: "conflict", local, remote, reason: "нет общей базы для безопасного слияния" });
+      continue;
+    }
+    if (remoteBase !== null && remoteBase !== knownHash) {
+      decisions.push({ path: relativePath, action: "conflict", local, remote, reason: "чужая версия происходит из другой базы" });
+      continue;
+    }
+    decisions.push({ path: relativePath, action: "conflict", local, remote, reason: "обе стороны менялись" });
+  }
+  return decisions;
+}
+
+/**
+ * Compose the local file text after accepting a remote version of a section:
+ * the remote manual content plus the local AUTO-SCAN blocks (local scanner
+ * results are machine-specific and never travel between machines).
+ */
+export function composeSectionFromRemote(remoteText, localRawText) {
+  const manual = stripAutoScan(remoteText);
+  const blockMatch = String(localRawText ?? "").match(/<!--\s*AUTO-SCAN:START[^>]*-->[\s\S]*?<!--\s*AUTO-SCAN:END\s*-->/gu) ?? [];
+  const blocks = blockMatch.slice(0, 4);
+  const parts = [manual.trim()];
+  for (const block of blocks) parts.push(block.trim());
+  return `${parts.filter((part) => part.length > 0).join("\n\n")}\n`;
+}
+
+/** Content that actually travels: sections lose AUTO-SCAN blocks, journals keep everything. */
+export function syncableText(relativePath, rawText) {
+  const redacted = String(rawText ?? "");
+  return SECTION_FILES.includes(relativePath) ? stripAutoScan(redacted) : redacted;
+}