@acms-subir/core 0.3.15 → 0.3.17

package/cli/sync.mjs

@@ -0,0 +1,876 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { mkdir, open, unlink } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { atomicJson, readJson, fail } from "./common.mjs";
+import {
+  TYPES,
+  PROTOCOL,
+  canonical,
+  hash,
+  differences,
+  classify,
+  matchEntity,
+} from "../src/lib/sync/protocol.mjs";
+
+export const SYNC_HELP = `acms sync — selective environment transfers
+  init --from <site-profile> --to <site-profile>  choose a direction
+  status [--type <category>] [--selected] [--conflicts]
+  list [--type <category>] [--calendar <slug>] [--search <text>]
+  add <ref>... | add --type <category> | add --all
+      add calendar:<slug> --include-events
+  remove <ref>... | remove --type <category>
+  clear                                  clear selection (never content)
+  select                                 interactive numbered selection
+  diff [<ref>] [--selected]                field-level before/after
+  resolve <ref> --use source|destination  resolve this exact pair of versions
+  resolve <ref> --interactive             choose top-level fields
+  plan [--mode draft|live] [--out <file>]  default: draft
+  plan --publish <run-id> | plan --rollback <run-id>
+  show <plan-or-run-id> | history
+  apply --plan <id> | apply --file <plan.json> [--yes]
+  --json --dry-run --cwd <project> --help
+Categories: ${Object.keys(TYPES).join(", ")}
+Both sites must run a sync-capable ACMS version. Use scoped sync keys.
+Plans bind exact payloads to one destination installation and revision.
+--yes never bypasses revisions, conflicts, permissions or dependencies.
+No deletion propagation, account/booking/submission transfer, or code upload.
+Documentation: acms docs sync
+`;
+const configRoot = () =>
+  process.env.ACMS_CONFIG_DIR ?? join(homedir(), ".config/acms");
+const UUID = /^[a-f0-9-]{36}$/i;
+function assertId(id) {
+  if (!UUID.test(id ?? "")) fail("USAGE", "Supply a valid plan or run ID.");
+  return id;
+}
+function endpoint(raw) {
+  const u = new URL(raw);
+  if (
+    u.username ||
+    u.password ||
+    u.search ||
+    u.hash ||
+    !["https:", "http:"].includes(u.protocol) ||
+    (u.protocol === "http:" &&
+      !["localhost", "127.0.0.1", "[::1]"].includes(u.hostname))
+  )
+    fail(
+      "USAGE",
+      "Sync profiles require HTTPS, except loopback development sites.",
+    );
+  return u.origin;
+}
+async function profile(name) {
+  const p = (await readJson(join(configRoot(), "sites.json"))).sites?.[name];
+  if (!p)
+    fail("USAGE", `Unknown site profile ${name}. Run acms site connect first.`);
+  const token = process.env[p.tokenEnv];
+  if (!token) fail("AUTH", `Set ${p.tokenEnv}.`);
+  return { name, url: endpoint(p.url), token };
+}
+async function request(
+  p,
+  path = "/api/sync",
+  body,
+  method = body ? "POST" : "GET",
+) {
+  let response;
+  try {
+    response = await fetch(new URL(path, p.url), {
+      method,
+      headers: {
+        Authorization: `Bearer ${p.token}`,
+        ...(body ? { "Content-Type": "application/json" } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      redirect: "error",
+      signal: AbortSignal.timeout(60000),
+    });
+  } catch {
+    fail(
+      "NETWORK",
+      `Could not reach ${p.url}. Rerun apply with the same plan ID to check an interrupted transfer.`,
+    );
+  }
+  const bytes = await readBounded(response, 10 * 1024 * 1024);
+  let value;
+  try {
+    value = JSON.parse(new TextDecoder().decode(bytes));
+  } catch {
+    fail(
+      "NETWORK",
+      "The site did not return a sync response. Upgrade both sites to a sync-capable ACMS version.",
+    );
+  }
+  if (!response.ok)
+    fail(
+      response.status === 409
+        ? "CONFLICT"
+        : [401, 403].includes(response.status)
+          ? "AUTH"
+          : "NETWORK",
+      value.error ?? `Sync failed (${response.status}).`,
+    );
+  return value;
+}
+async function readBounded(response, limit) {
+  const reader = response.body?.getReader();
+  if (!reader) return new Uint8Array();
+  let size = 0;
+  const chunks = [];
+  try {
+    for (;;) {
+      const r = await reader.read();
+      if (r.done) break;
+      size += r.value.length;
+      if (size > limit) {
+        await reader.cancel();
+        fail("TOO_LARGE", "Sync response exceeds its size limit.");
+      }
+      chunks.push(r.value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const out = new Uint8Array(size);
+  let i = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, i);
+    i += chunk.length;
+  }
+  return out;
+}
+async function snapshots(source, destination) {
+  const results = await Promise.allSettled([
+    request(source, undefined, { op: "snapshot" }),
+    request(destination, undefined, { op: "snapshot" }),
+  ]);
+  for (const result of results)
+    if (result.status === "rejected") throw result.reason;
+  const [from, to] = results.map((r) => r.value);
+  if (from.protocol !== PROTOCOL || to.protocol !== PROTOCOL)
+    fail("USAGE", "Incompatible sync protocol. Upgrade both sites.");
+  if (from.siteId === to.siteId)
+    fail("USAGE", "Both profiles point to the same installation.");
+  return { from, to };
+}
+function rowsFor(from, to, state) {
+  return from.entities.map((entity) => {
+    const match = matchEntity(entity, to.entities),
+      saved = state.resolutions[entity.key];
+    const resolution =
+      saved &&
+      saved.source === entity.hash &&
+      saved.destination === (match.entity?.stateHash ?? null)
+        ? saved
+        : null;
+    const decision = classify(
+      entity,
+      match,
+      state.baselines[entity.key],
+      resolution,
+    );
+    return {
+      entity,
+      target: match.entity,
+      linked: match.linked,
+      resolution,
+      ...decision,
+      selected: state.selected.includes(entity.key),
+      excluded: state.excluded.includes(entity.key),
+    };
+  });
+}
+function kindMatches(kind, type) {
+  return type === "booking-config"
+    ? ["booking", "booking-settings"].includes(kind)
+    : TYPES[type] === kind;
+}
+function filterRows(rows, flags) {
+  if (flags.type && !TYPES[flags.type])
+    fail("USAGE", `Unknown category. Choose ${Object.keys(TYPES).join(", ")}.`);
+  return rows.filter(
+    (r) =>
+      (!flags.type || kindMatches(r.entity.kind, flags.type)) &&
+      (!flags.selected || r.selected) &&
+      (!flags.conflicts || r.action === "conflict") &&
+      (!flags.search ||
+        `${r.entity.ref} ${r.entity.data.title ?? ""}`
+          .toLowerCase()
+          .includes(flags.search.toLowerCase())),
+  );
+}
+function findRow(rows, ref) {
+  const found = rows.filter(
+    (r) =>
+      r.entity.key === ref ||
+      r.entity.ref === ref ||
+      (r.entity.kind === "post" && `post:${r.entity.data.slug}` === ref),
+  );
+  if (found.length !== 1)
+    fail(
+      "USAGE",
+      found.length
+        ? `Ambiguous reference ${ref}; use the full key from sync list.`
+        : `Item ${ref} not found. Run sync list.`,
+    );
+  return found[0];
+}
+function closure(rows, state) {
+  const picked = new Map(),
+    issues = [];
+  function include(key, parent) {
+    if (picked.has(key)) return;
+    const row = rows.find((r) => r.entity.key === key);
+    if (!row) {
+      issues.push(`Missing dependency ${key}`);
+      return;
+    }
+    if (row.excluded) {
+      issues.push(
+        `${parent ?? "Selection"} requires excluded ${row.entity.ref}`,
+      );
+      return;
+    }
+    if (row.action === "preserve") {
+      if (!parent) return;
+      if (!row.target) {
+        issues.push(`Dependency ${row.entity.ref} has no destination item`);
+        return;
+      }
+      // Existing destination is deliberately retained, but its alias must be
+      // linked for references in the parent to resolve.
+      picked.set(key, { ...row, action: "skip", preserved: true });
+      return;
+    }
+    picked.set(key, { ...row, dependency: !!parent });
+    if (row.action === "conflict")
+      issues.push(`${row.entity.ref}: ${row.reason}`);
+    for (const dep of row.entity.dependencies) include(dep, row.entity.ref);
+  }
+  state.selected.forEach((k) => include(k));
+  return { picked: [...picked.values()], issues };
+}
+async function prompt(question) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY)
+    fail(
+      "USAGE",
+      "Interactive sync requires a terminal. Use explicit selection flags or --yes for apply.",
+    );
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+function summary(rows) {
+  return rows.map((r) => ({
+    ref: r.entity.ref,
+    key: r.entity.key,
+    type: r.entity.kind,
+    action: r.action,
+    reason: r.reason,
+    selected: r.selected,
+    dependency: !!r.dependency,
+    hash: r.entity.hash,
+  }));
+}
+
+export async function syncCommand(command, args, flags) {
+  const commands = [
+    "init",
+    "status",
+    "list",
+    "add",
+    "remove",
+    "clear",
+    "select",
+    "diff",
+    "resolve",
+    "plan",
+    "show",
+    "history",
+    "apply",
+  ];
+  if (!commands.includes(command))
+    fail("USAGE", "Unknown sync command. Run acms sync --help.");
+  if (flags.force)
+    fail(
+      "USAGE",
+      "Sync does not support --force. Review and resolve conflicts.",
+    );
+  if (flags.json && (command === "select" || flags.interactive))
+    fail("USAGE", "Interactive selection and --json cannot be combined.");
+  const root = join(configRoot(), "sync", await hash(resolve(process.cwd())));
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  const lockPath = join(root, "lock");
+  let lock;
+  try {
+    lock = await open(lockPath, "wx", 0o600);
+    await lock.writeFile(String(process.pid));
+  } catch (e) {
+    if (e.code === "EEXIST")
+      fail(
+        "CONFLICT",
+        `Another sync command is using this workspace. If it crashed, verify its PID in ${lockPath} before removing that lock.`,
+      );
+    throw e;
+  }
+  try {
+    return await run(command, args, flags, root);
+  } finally {
+    await lock.close();
+    await unlink(lockPath);
+  }
+}
+async function run(command, args, flags, root) {
+  const current = join(root, "current.json");
+  if (command === "init") {
+    if (!flags.from || !flags.to)
+      fail("USAGE", "Use sync init --from <profile> --to <profile>.");
+    const [source, destination] = await Promise.all([
+      profile(flags.from),
+      profile(flags.to),
+    ]);
+    if (source.url === destination.url)
+      fail("USAGE", "Choose two different sites.");
+    const { from, to } = await snapshots(source, destination);
+    const pair = await hash({
+      from: from.siteId,
+      to: to.siteId,
+      source: source.url,
+      destination: destination.url,
+    });
+    const path = join(root, `${pair}.json`);
+    let state;
+    try {
+      state = await readJson(path);
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+      state = {
+        version: 1,
+        source: { name: source.name, url: source.url, siteId: from.siteId },
+        destination: {
+          name: destination.name,
+          url: destination.url,
+          siteId: to.siteId,
+        },
+        selected: [],
+        excluded: [],
+        resolutions: {},
+        baselines: {},
+        plans: {},
+      };
+    }
+    if (!flags["dry-run"]) {
+      await atomicJson(path, state);
+      await atomicJson(current, { pair });
+    }
+    return {
+      direction: `${source.name} → ${destination.name}`,
+      destination: destination.url,
+      selected: state.selected.length,
+      dryRun: !!flags["dry-run"],
+    };
+  }
+  let active;
+  try {
+    active = await readJson(current);
+  } catch {
+    fail("USAGE", "Run sync init --from <profile> --to <profile> first.");
+  }
+  if (!/^[a-f0-9]{64}$/.test(active.pair))
+    fail("USAGE", "Invalid local sync workspace.");
+  const path = join(root, `${active.pair}.json`),
+    state = await readJson(path);
+  const [source, destination] = await Promise.all([
+    profile(state.source.name),
+    profile(state.destination.name),
+  ]);
+  if (
+    source.url !== state.source.url ||
+    destination.url !== state.destination.url
+  )
+    fail("CONFLICT", "A profile URL changed. Run sync init again.");
+  const direction = `${source.name} → ${destination.name}`,
+    base = { direction, destination: destination.url };
+  const save = async () => {
+    if (!flags["dry-run"]) await atomicJson(path, state);
+  };
+  if (command === "history")
+    return {
+      ...base,
+      ...(await request(destination, undefined, { op: "history" })),
+    };
+  if (command === "show")
+    return {
+      ...base,
+      ...(await request(destination, undefined, {
+        op: "show",
+        id: assertId(args[0]),
+      })),
+    };
+  if (command === "clear") {
+    state.selected = [];
+    state.excluded = [];
+    state.resolutions = {};
+    await save();
+    return { ...base, selected: [], dryRun: !!flags["dry-run"] };
+  }
+  if (command === "apply")
+    return apply(source, destination, state, flags, save, base);
+  if (command === "plan" && (flags.publish || flags.rollback)) {
+    if (flags.publish && flags.rollback)
+      fail("USAGE", "Choose publication or rollback.");
+    const op = flags.publish ? "publish" : "rollback",
+      id = assertId(flags.publish ?? flags.rollback);
+    const plan = await request(destination, undefined, {
+      op,
+      id,
+      validateOnly: !!flags["dry-run"],
+    });
+    if (flags["dry-run"]) return { ...base, ...plan, dryRun: true };
+    return persistPlan(plan, state, flags, save, base);
+  }
+  const { from, to } = await snapshots(source, destination);
+  if (
+    from.siteId !== state.source.siteId ||
+    to.siteId !== state.destination.siteId
+  )
+    fail(
+      "CONFLICT",
+      "An installation identity changed. Run sync init to establish a new baseline.",
+    );
+  const rows = rowsFor(from, to, state);
+  let filtered = filterRows(rows, flags);
+  if (flags.calendar) {
+    const cal = findRow(rows, `calendar:${flags.calendar}`);
+    filtered = filtered.filter(
+      (r) =>
+        r.entity.kind === "event" &&
+        r.entity.dependencies.includes(cal.entity.key),
+    );
+  }
+  if (command === "status" || command === "list") {
+    const extra = closure(rows, state);
+    return {
+      ...base,
+      items: summary(filtered.filter((r) => r.entity.kind !== "author")),
+      dependencies: summary(extra.picked.filter((r) => r.dependency)),
+      issues: extra.issues,
+      destinationOnly: to.entities
+        .filter((e) => !from.entities.some((s) => matchEntity(s, [e]).entity))
+        .map((e) => ({ ref: e.ref, action: "preserve" })),
+    };
+  }
+  if (command === "diff") {
+    const picked = args.length
+      ? [findRow(rows, args[0])]
+      : flags.selected
+        ? closure(rows, state).picked
+        : filtered;
+    return {
+      ...base,
+      changes: picked.map((r) => ({
+        ref: r.entity.ref,
+        action: r.action,
+        fields: differences(
+          r.target?.data,
+          r.resolution?.data ?? r.entity.data,
+        ),
+      })),
+    };
+  }
+  if (["add", "remove", "select"].includes(command)) {
+    let picked = args.map((ref) => findRow(rows, ref));
+    if (flags.type || flags.all)
+      picked = filtered.filter(
+        (r) =>
+          r.entity.kind !== "author" &&
+          (command === "remove" || !["skip", "preserve"].includes(r.action)),
+      );
+    if (command === "select") {
+      const options = rows.filter(
+        (r) =>
+          r.entity.kind !== "author" &&
+          !["skip", "preserve"].includes(r.action),
+      );
+      process.stderr.write(
+        `${direction} (${destination.url})\n` +
+          options
+            .map(
+              (r, i) =>
+                `${i + 1}. [${r.selected ? "x" : " "}] ${r.entity.ref} (${r.action})`,
+            )
+            .join("\n") +
+          "\n",
+      );
+      const answer = await prompt(
+        "Select item numbers separated by commas (blank keeps current selection): ",
+      );
+      if (!answer) return { ...base, selected: state.selected };
+      const numbers = answer.split(",").map((n) => Number(n.trim()));
+      if (
+        numbers.some((n) => !Number.isInteger(n) || n < 1 || n > options.length)
+      )
+        fail("USAGE", "Invalid selection.");
+      picked = numbers.map((n) => options[n - 1]);
+      state.selected = [];
+    }
+    if (!picked.length && !flags.all && !flags.type)
+      fail("USAGE", "Select item references, --type, or --all.");
+    if (flags["include-events"])
+      for (const cal of [...picked].filter((r) => r.entity.kind === "calendar"))
+        picked.push(
+          ...rows.filter(
+            (r) =>
+              r.entity.kind === "event" &&
+              r.entity.dependencies.includes(cal.entity.key),
+          ),
+        );
+    for (const row of picked) {
+      const key = row.entity.key;
+      delete state.resolutions[key];
+      if (command === "remove") {
+        state.selected = state.selected.filter((k) => k !== key);
+        state.excluded = [...new Set([...state.excluded, key])];
+      } else {
+        state.selected = [...new Set([...state.selected, key])];
+        state.excluded = state.excluded.filter((k) => k !== key);
+      }
+    }
+    await save();
+    return {
+      ...base,
+      selected: state.selected.map(
+        (k) => rows.find((r) => r.entity.key === k)?.entity.ref ?? k,
+      ),
+      dryRun: !!flags["dry-run"],
+    };
+  }
+  if (command === "resolve") {
+    const row = findRow(rows, args[0]);
+    let use = flags.use,
+      data;
+    if (flags.interactive) {
+      if (!row.target)
+        fail("USAGE", "This item has no destination version to merge.");
+      data = structuredClone(row.entity.data);
+      for (const field of Object.keys({
+        ...row.target.data,
+        ...row.entity.data,
+      }))
+        if (
+          canonical(row.target.data[field] ?? null) !==
+          canonical(row.entity.data[field] ?? null)
+        ) {
+          process.stderr.write(
+            JSON.stringify(
+              {
+                field,
+                source: row.entity.data[field],
+                destination: row.target.data[field],
+              },
+              null,
+              2,
+            ) + "\n",
+          );
+          const choice = await prompt(
+            `${field}: source or destination [destination]? `,
+          );
+          if (choice && choice !== "source" && choice !== "destination")
+            fail("USAGE", "Choose source or destination.");
+          if (choice !== "source") data[field] = row.target.data[field];
+        }
+      use = "fields";
+    }
+    if (!["source", "destination", "fields"].includes(use))
+      fail("USAGE", "Use --use source|destination or --interactive.");
+    state.resolutions[row.entity.key] = {
+      use,
+      ...(data ? { data } : {}),
+      source: row.entity.hash,
+      destination: row.target?.stateHash ?? null,
+    };
+    if (use !== "destination") {
+      state.selected = [...new Set([...state.selected, row.entity.key])];
+      state.excluded = state.excluded.filter((k) => k !== row.entity.key);
+    }
+    await save();
+    return {
+      ...base,
+      ref: row.entity.ref,
+      resolution: use,
+      dryRun: !!flags["dry-run"],
+    };
+  }
+  if (command === "plan") {
+    const { picked, issues } = closure(rows, state);
+    if (issues.length)
+      fail(
+        "CONFLICT",
+        "Resolve selection conflicts and dependencies before planning.",
+        issues,
+      );
+    if (!picked.length)
+      fail("USAGE", "Nothing selected. Use sync add or sync select.");
+    const mode = flags.mode ?? "draft";
+    if (!["draft", "live"].includes(mode))
+      fail("USAGE", "Mode must be draft or live.");
+    const choices = picked.map((r) => ({
+      key: r.entity.key,
+      kind: r.entity.kind,
+      aliases: r.entity.aliases,
+      data: r.preserved ? r.target.data : (r.resolution?.data ?? r.entity.data),
+      targetId: r.target?.id ?? null,
+      expected: r.target?.stateHash ?? null,
+      action: r.action,
+      sourceHash: r.entity.hash,
+    }));
+    const input = {
+      sourceSite: from.siteId,
+      sourceUrl: source.url,
+      destinationSite: to.siteId,
+      revision: to.revision,
+      mode,
+      choices,
+    };
+    const plan = await request(destination, undefined, {
+      op: "plan",
+      input,
+      validateOnly: !!flags["dry-run"],
+    });
+    if (flags["dry-run"]) return { ...base, ...plan, dryRun: true };
+    const files = picked.flatMap((r) => r.entity.files ?? []);
+    state.plans[plan.id] = {
+      files,
+      keys: picked.filter((r) => !r.preserved).map((r) => r.entity.key),
+    };
+    return persistPlan(plan, state, flags, save, base);
+  }
+}
+async function persistPlan(plan, state, flags, save, base) {
+  state.plans[plan.id] = { ...state.plans[plan.id], digest: plan.digest };
+  await save();
+  if (flags.out)
+    await atomicJson(resolve(flags.out), {
+      format: "acms-sync-plan/1",
+      id: plan.id,
+      digest: plan.digest,
+      source: state.source,
+      destination: state.destination,
+      plan,
+      files: state.plans[plan.id].files ?? [],
+    });
+  return {
+    ...base,
+    id: plan.id,
+    digest: plan.digest,
+    mode: plan.mode,
+    purpose: plan.purpose,
+    changes: plan.changes,
+    apply: `acms sync apply --plan ${plan.id}`,
+  };
+}
+async function apply(source, destination, state, flags, save, base) {
+  if (!!flags.plan === !!flags.file)
+    fail("USAGE", "Use exactly one of --plan or --file.");
+  let id = flags.plan,
+    digest,
+    files = [];
+  if (flags.file) {
+    const saved = await readJson(resolve(flags.file));
+    if (
+      saved.format !== "acms-sync-plan/1" ||
+      saved.destination?.url !== destination.url ||
+      saved.destination?.siteId !== state.destination.siteId ||
+      saved.source?.url !== source.url ||
+      saved.source?.siteId !== state.source.siteId
+    )
+      fail("CONFLICT", "This plan belongs to a different environment pair.");
+    id = saved.id;
+    digest = saved.digest;
+    files = saved.files ?? [];
+  } else {
+    digest = state.plans[id]?.digest;
+    files = state.plans[id]?.files ?? [];
+  }
+  assertId(id);
+  const stored = await request(destination, undefined, { op: "show", id });
+  if (digest && stored.digest !== digest)
+    fail("CONFLICT", "Saved plan digest differs from the destination plan.");
+  digest = stored.digest;
+  if (
+    stored.body.destinationSite !== state.destination.siteId ||
+    stored.body.sourceSite !== state.source.siteId
+  )
+    fail(
+      "CONFLICT",
+      "Plan installation identities do not match this workspace.",
+    );
+  if (flags["dry-run"])
+    return { ...base, id, dryRun: true, changes: stored.body.changes };
+  if (!stored.result && !flags.yes) {
+    process.stderr.write(
+      renderSync({
+        ...base,
+        id,
+        mode: stored.body.mode,
+        changes: stored.body.changes,
+      }) + "\n",
+    );
+    if ((await prompt(`Apply to ${destination.url}? Type yes: `)) !== "yes")
+      return { ...base, id, cancelled: true };
+  }
+  if (!stored.result) {
+    const objects = stored.body.operations
+      .filter(
+        (o) => o.kind === "media" && ["create", "update"].includes(o.action),
+      )
+      .flatMap((o) => o.data.objects);
+    for (const object of objects) {
+      const path = `/api/sync/media?key=${encodeURIComponent(object.key)}`;
+      const head = await fetch(new URL(path, destination.url), {
+        method: "HEAD",
+        headers: { Authorization: `Bearer ${destination.token}` },
+        redirect: "error",
+        signal: AbortSignal.timeout(60000),
+      });
+      if (head.ok && head.headers.get("etag") === object.digest) continue;
+      if (head.status !== 404 && !head.ok)
+        fail(
+          head.status === 401 || head.status === 403 ? "AUTH" : "NETWORK",
+          `Could not verify media on ${destination.url}.`,
+        );
+      let file = files.find(
+        (f) => f.key === object.key && f.digest === object.digest,
+      );
+      if (!file) {
+        const snap = await request(source, undefined, { op: "snapshot" });
+        file = snap.entities
+          .flatMap((e) => e.files ?? [])
+          .find((f) => f.key === object.key && f.digest === object.digest);
+      }
+      if (
+        !file ||
+        file.sourceKey.includes("..") ||
+        file.sourceKey.startsWith("/")
+      )
+        fail(
+          "CONFLICT",
+          "The planned source media is no longer available. Generate a new plan.",
+        );
+      const response = await fetch(
+        new URL(
+          `/api/sync/media?key=${encodeURIComponent(file.sourceKey)}`,
+          source.url,
+        ),
+        {
+          headers: { Authorization: `Bearer ${source.token}` },
+          redirect: "error",
+          signal: AbortSignal.timeout(60000),
+        },
+      );
+      if (!response.ok) fail("NETWORK", "Could not read planned source media.");
+      const bytes = await readBounded(response, 16 * 1024 * 1024);
+      if ((await hash(bytes)) !== object.digest)
+        fail(
+          "CONFLICT",
+          "Source media changed after planning. Generate a new plan.",
+        );
+      const upload = await fetch(new URL(path, destination.url), {
+        method: "PUT",
+        headers: {
+          Authorization: `Bearer ${destination.token}`,
+          "Content-Type":
+            response.headers.get("content-type") ?? "application/octet-stream",
+        },
+        body: bytes,
+        redirect: "error",
+        signal: AbortSignal.timeout(60000),
+      });
+      if (!upload.ok)
+        fail(
+          "NETWORK",
+          "Media upload failed. Reapply the same plan to resume.",
+        );
+      await upload.body?.cancel();
+    }
+  }
+  const result = await request(destination, undefined, {
+    op: "apply",
+    id,
+    digest,
+  });
+  // Reconcile from the server even after a lost response / local crash.
+  if (state.plans[id]?.reconciled) return { ...base, ...result };
+  const currentSource = await request(source, undefined, { op: "snapshot" });
+  if (currentSource.siteId !== state.source.siteId)
+    fail(
+      "CONFLICT",
+      "Transfer completed, but the source installation changed before local reconciliation. Reinitialize the workspace.",
+    );
+  for (const item of result.items) {
+    if ((state.baselines[item.key]?.completedAt ?? 0) > result.completedAt)
+      continue;
+    if (item.action === "delete") {
+      delete state.baselines[item.key];
+      continue;
+    }
+    if (item.destinationHash && item.sourceHash)
+      state.baselines[item.key] = {
+        source: item.sourceHash,
+        destination: item.destinationHash,
+        completedAt: result.completedAt,
+      };
+    if (
+      currentSource.entities.find((e) => e.key === item.key)?.hash ===
+      item.sourceHash
+    ) {
+      state.selected = state.selected.filter((k) => k !== item.key);
+      delete state.resolutions[item.key];
+    }
+  }
+  state.plans[id] = { ...state.plans[id], digest, reconciled: true };
+  await save();
+  return { ...base, ...result };
+}
+export function renderSync(data) {
+  const lines = [];
+  if (data.direction) lines.push(`${data.direction} (${data.destination})`);
+  if (data.id)
+    lines.push(
+      `${data.purpose ?? "Plan"} ${data.id}${data.mode ? ` · ${data.mode}` : ""}`,
+    );
+  if (data.dryRun) lines.push("Dry run — no transfer applied.");
+  for (const item of data.items ?? [])
+    lines.push(
+      `${item.selected ? "[x]" : "[ ]"} ${String(item.action).padEnd(9)} ${item.ref ?? item.key}${item.reason ? ` — ${item.reason}` : ""}`,
+    );
+  for (const dep of data.dependencies ?? [])
+    lines.push(`  requires ${dep.ref} (${dep.action})`);
+  for (const issue of data.issues ?? []) lines.push(`Conflict: ${issue}`);
+  for (const change of data.changes ?? []) {
+    lines.push(
+      `${change.action ?? ""} ${change.ref}${change.effect ? ` (${change.effect})` : ""}`,
+    );
+    for (const field of change.fields ?? [])
+      lines.push(
+        `  ${field.field}: ${JSON.stringify(field.before)} → ${JSON.stringify(field.after)}`,
+      );
+  }
+  if (Array.isArray(data.selected))
+    lines.push(`Selected: ${data.selected.join(", ") || "(none)"}`);
+  if (data.apply) lines.push(`Apply: ${data.apply}`);
+  if (data.completedAt) lines.push("Transfer completed.");
+  if (
+    !data.items &&
+    !data.changes &&
+    !Array.isArray(data.selected) &&
+    !data.completedAt
+  )
+    lines.push(JSON.stringify(data, null, 2));
+  return lines.join("\n");
+}