@narumitw/pi-sync 0.25.0 → 0.29.0

package/src/snapshot-transaction.ts

@@ -0,0 +1,201 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { agentDir, stateDir } from "./config.js";
+import { assertWithinRoot, isPathInside } from "./paths.js";
+import { sessionStorageRoot } from "./snapshot.js";
+import type { SnapshotApplyPlan } from "./types.js";
+
+const JOURNAL_VERSION = 1;
+
+interface TransactionEntry {
+	target: string;
+	backupName: string;
+	kind: "missing" | "file" | "directory" | "symlink";
+	linkTarget?: string;
+}
+
+interface TransactionJournal {
+	version: number;
+	root: string;
+	sessionRoot?: string;
+	entries: TransactionEntry[];
+}
+
+export async function applySnapshotTransaction(
+	plan: SnapshotApplyPlan,
+	options: { sessionDir?: string } = {},
+) {
+	await recoverPendingSnapshotTransactions();
+	const transaction = await prepareTransaction(plan, options.sessionDir);
+	try {
+		for (const target of plan.deletes) {
+			await fs.rm(target, { force: true, recursive: true });
+		}
+		for (const item of plan.writes) {
+			await fs.writeFile(item.target, item.content);
+		}
+		await fs.rm(transaction.directory, { recursive: true, force: true });
+	} catch (error) {
+		try {
+			await restoreTransaction(transaction.directory, transaction.journal);
+		} catch (recoveryError) {
+			throw new AggregateError(
+				[error, recoveryError],
+				`Snapshot apply failed and automatic recovery also failed. Transaction retained at ${transaction.directory}.`,
+			);
+		}
+		throw error;
+	}
+}
+
+export async function recoverPendingSnapshotTransactions() {
+	const directory = transactionRoot();
+	let entries: import("node:fs").Dirent[];
+	try {
+		entries = await fs.readdir(directory, { withFileTypes: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+		throw error;
+	}
+	for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+		if (!entry.isDirectory()) continue;
+		const transactionDirectory = path.join(directory, entry.name);
+		const journalPath = path.join(transactionDirectory, "journal.json");
+		let journal: TransactionJournal;
+		try {
+			journal = JSON.parse(await fs.readFile(journalPath, "utf8")) as TransactionJournal;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+				await fs.rm(transactionDirectory, { recursive: true, force: true });
+				continue;
+			}
+			throw new Error(`Cannot recover malformed pi-sync transaction: ${journalPath}`, {
+				cause: error,
+			});
+		}
+		await restoreTransaction(transactionDirectory, journal);
+	}
+}
+
+async function prepareTransaction(plan: SnapshotApplyPlan, sessionDir?: string) {
+	const root = path.resolve(agentDir());
+	const sessionRoot = sessionDir ? path.resolve(sessionStorageRoot(root, sessionDir)) : undefined;
+	const directory = path.join(transactionRoot(), randomUUID());
+	const backupDirectory = path.join(directory, "before");
+	await fs.mkdir(backupDirectory, { recursive: true, mode: 0o700 });
+	const targets = [...new Set([...plan.deletes, ...plan.writes.map((item) => item.target)])].sort();
+	const entries: TransactionEntry[] = [];
+	for (let index = 0; index < targets.length; index += 1) {
+		const target = targets[index];
+		if (!target) continue;
+		assertAllowedTarget(root, sessionRoot, target);
+		const backupName = `${index}`;
+		const backupPath = path.join(backupDirectory, backupName);
+		try {
+			const stat = await fs.lstat(target);
+			if (stat.isSymbolicLink()) {
+				entries.push({
+					target,
+					backupName,
+					kind: "symlink",
+					linkTarget: await fs.readlink(target),
+				});
+			} else if (stat.isDirectory()) {
+				await fs.cp(target, backupPath, {
+					recursive: true,
+					dereference: false,
+					preserveTimestamps: true,
+				});
+				entries.push({ target, backupName, kind: "directory" });
+			} else if (stat.isFile()) {
+				await fs.copyFile(target, backupPath);
+				await fs.chmod(backupPath, stat.mode);
+				entries.push({ target, backupName, kind: "file" });
+			} else {
+				throw new Error(`Unsupported existing snapshot target: ${target}`);
+			}
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			entries.push({ target, backupName, kind: "missing" });
+		}
+	}
+	const journal: TransactionJournal = {
+		version: JOURNAL_VERSION,
+		root,
+		sessionRoot,
+		entries,
+	};
+	await fs.writeFile(
+		path.join(directory, "journal.json"),
+		`${JSON.stringify(journal, null, "\t")}\n`,
+		{
+			mode: 0o600,
+		},
+	);
+	return { directory, journal };
+}
+
+async function restoreTransaction(directory: string, journal: TransactionJournal) {
+	validateJournal(directory, journal);
+	for (const entry of [...journal.entries].sort(
+		(left, right) => right.target.length - left.target.length,
+	)) {
+		await fs.rm(entry.target, { recursive: true, force: true });
+	}
+	for (const entry of journal.entries) {
+		if (entry.kind === "missing") continue;
+		await fs.mkdir(path.dirname(entry.target), { recursive: true });
+		const backupPath = path.join(directory, "before", entry.backupName);
+		assertWithinRoot(directory, backupPath);
+		if (entry.kind === "file") await fs.copyFile(backupPath, entry.target);
+		else if (entry.kind === "directory") {
+			await fs.cp(backupPath, entry.target, {
+				recursive: true,
+				dereference: false,
+				preserveTimestamps: true,
+			});
+		} else if (entry.kind === "symlink" && entry.linkTarget !== undefined) {
+			await fs.symlink(entry.linkTarget, entry.target);
+		}
+	}
+	await fs.rm(directory, { recursive: true, force: true });
+}
+
+function validateJournal(directory: string, journal: TransactionJournal) {
+	if (journal.version !== JOURNAL_VERSION || !Array.isArray(journal.entries)) {
+		throw new Error(`Unsupported pi-sync transaction journal: ${directory}`);
+	}
+	const expectedRoot = path.resolve(agentDir());
+	if (path.resolve(journal.root) !== expectedRoot) {
+		throw new Error(`Transaction root no longer matches the Pi agent directory: ${directory}`);
+	}
+	for (const entry of journal.entries) {
+		if (
+			!entry ||
+			typeof entry.target !== "string" ||
+			typeof entry.backupName !== "string" ||
+			!/^\d+$/u.test(entry.backupName)
+		) {
+			throw new Error(`Invalid pi-sync transaction entry: ${directory}`);
+		}
+		assertAllowedTarget(journal.root, journal.sessionRoot, entry.target);
+	}
+}
+
+function assertAllowedTarget(root: string, sessionRoot: string | undefined, target: string) {
+	const resolved = path.resolve(target);
+	if (isPathInside(root, resolved)) {
+		assertWithinRoot(root, resolved);
+		return;
+	}
+	if (sessionRoot && isPathInside(sessionRoot, resolved)) {
+		assertWithinRoot(sessionRoot, resolved);
+		return;
+	}
+	throw new Error(`Transaction target is outside configured roots: ${target}`);
+}
+
+function transactionRoot() {
+	return path.join(stateDir(), "transactions");
+}

package/src/snapshot.ts

@@ -5,20 +5,25 @@ import os from "node:os";
 import path from "node:path";
 import { agentDir, configuredSessionDir } from "./config.js";
 import { isDeniedPath, posixJoin, safeJoin, toPosix } from "./paths.js";
+
 export { isDeniedPath } from "./paths.js";
-import type {
-	Snapshot,
-	SnapshotFile,
-	SnapshotOptions,
-	SyncConfig,
-} from "./types.js";
+
+import {
+	canonicalSnapshotPathForConfig,
+	DEFAULT_SYNC_FILES,
+	extraFilePathsByLower,
+	isConfiguredSnapshotPath,
+	isPreservableUnmanagedSnapshotPath,
+	normalizeExtraFiles,
+	normalizeSyncFiles,
+} from "./sync-policy.js";
+import type { Snapshot, SnapshotFile, SnapshotOptions, SyncConfig } from "./types.js";
+
+export { canonicalSnapshotPathForConfig, isConfiguredSnapshotPath } from "./sync-policy.js";
 
 const VERSION = 1;
-const TOP_LEVEL_FILES = new Set(["settings.json", "keybindings.json", "models.json", "AGENTS.md", "APPEND_SYSTEM.md"]);
-const TOP_LEVEL_DIRS = new Set(["skills", "prompts", "themes", "extensions"]);
-const TOP_LEVEL_FILE_PATHS = new Map([...TOP_LEVEL_FILES].map((name) => [name.toLowerCase(), name]));
-const TOP_LEVEL_FILE_NAMES = new Set(TOP_LEVEL_FILE_PATHS.keys());
-const RESERVED_TOP_LEVEL_NAMES = new Set([...TOP_LEVEL_DIRS, "sessions"]);
+const TOP_LEVEL_FILES: readonly string[] = DEFAULT_SYNC_FILES.filter((name) => name.includes("."));
+const TOP_LEVEL_DIRS = new Set<string>(DEFAULT_SYNC_FILES.filter((name) => !name.includes(".")));
 const SECRET_PATTERNS = [
 	/AWS_SECRET_ACCESS_KEY\s*[=:]\s*['"]?[A-Za-z0-9/+]{35,}/i,
 	/(ANTHROPIC|OPENAI|GEMINI|GOOGLE|FIRECRAWL|GITHUB|CLOUDFLARE|R2|S3)_[A-Z0-9_]*(KEY|TOKEN|SECRET)\s*[=:]\s*['"]?[^\s'"]{12,}/i,
@@ -33,27 +38,6 @@ function expandHome(value: string) {
 	return value;
 }
 
-export function normalizeExtraFiles(value: unknown) {
-	if (!Array.isArray(value)) return [];
-	const seen = new Set<string>();
-	return value
-		.filter((item): item is string => typeof item === "string")
-		.map((item) => item.trim())
-		.filter((item) => {
-			const lower = item.toLowerCase();
-			if (
-				item === "" || item === "." || item === ".." || item.includes("/") || item.includes("\\") ||
-				TOP_LEVEL_FILE_NAMES.has(lower) || isDeniedPath(item) || RESERVED_TOP_LEVEL_NAMES.has(lower) || seen.has(lower)
-			) return false;
-			seen.add(lower);
-			return true;
-		});
-}
-
-export function extraFilePathsByLower(value: unknown) {
-	return new Map(normalizeExtraFiles(value).map((fileName) => [fileName.toLowerCase(), fileName]));
-}
-
 function selectTopLevelFileEntry(entries: Dirent[], fileName: string) {
 	const exact = entries.find((entry) => entry.isFile() && entry.name === fileName);
 	if (exact) return exact;
@@ -70,15 +54,24 @@ function sha256(value: Buffer) {
 function isSafeSnapshotPath(relativePath: string) {
 	if (relativePath.includes("\\")) return false;
 	const normalized = toPosix(relativePath);
-	return Boolean(normalized) && normalized !== "." && normalized !== ".." && !normalized.startsWith("../") &&
-		!path.posix.isAbsolute(normalized) && path.posix.normalize(normalized) === normalized && !isDeniedPath(normalized);
+	return (
+		Boolean(normalized) &&
+		normalized !== "." &&
+		normalized !== ".." &&
+		!normalized.startsWith("../") &&
+		!path.posix.isAbsolute(normalized) &&
+		path.posix.normalize(normalized) === normalized &&
+		!isDeniedPath(normalized)
+	);
 }
 
 function snapshotsMatch(left: Snapshot, right: Snapshot) {
 	const leftHashes = new Map(left.files.map((file) => [file.path, file.sha256]));
 	const rightHashes = new Map(right.files.map((file) => [file.path, file.sha256]));
-	return leftHashes.size === rightHashes.size &&
-		[...leftHashes].every(([filePath, hash]) => rightHashes.get(filePath) === hash);
+	return (
+		leftHashes.size === rightHashes.size &&
+		[...leftHashes].every(([filePath, hash]) => rightHashes.get(filePath) === hash)
+	);
 }
 
 function snapshotId() {
@@ -91,6 +84,7 @@ export async function createSnapshot(
 ): Promise<Snapshot> {
 	const syncSessions = Boolean(options.syncSessions);
 	const files = await collectFiles(agentDir(), {
+		syncFiles: options.syncFiles,
 		syncSessions,
 		sessionDir: options.sessionDir ?? (await configuredSessionDir()),
 		extraFiles: options.extraFiles,
@@ -112,12 +106,14 @@ export async function collectFiles(
 ): Promise<SnapshotFile[]> {
 	const results: SnapshotFile[] = [];
 	const entries = await fs.readdir(root, { withFileTypes: true });
+	const selectedFiles = new Set<string>(normalizeSyncFiles(options.syncFiles));
 	for (const entry of entries) {
-		if (entry.isDirectory() && TOP_LEVEL_DIRS.has(entry.name)) {
+		if (entry.isDirectory() && TOP_LEVEL_DIRS.has(entry.name) && selectedFiles.has(entry.name)) {
 			await collectDirectory(results, root, entry.name);
 		}
 	}
 	for (const fileName of TOP_LEVEL_FILES) {
+		if (!selectedFiles.has(fileName)) continue;
 		const entry = selectTopLevelFileEntry(entries, fileName);
 		if (entry) await addFile(results, root, entry.name, fileName);
 	}
@@ -168,7 +164,11 @@ async function addFile(
 	if (!isSafeSnapshotPath(snapshotPath)) return;
 	const absolutePath = safeJoin(root, relativePath);
 	const content = await fs.readFile(absolutePath);
-	results.push({ path: snapshotPath, contentBase64: content.toString("base64"), sha256: sha256(content) });
+	results.push({
+		path: snapshotPath,
+		contentBase64: content.toString("base64"),
+		sha256: sha256(content),
+	});
 }
 
 export function isSessionPath(relativePath: string) {
@@ -181,11 +181,18 @@ export function isSessionFilePath(relativePath: string) {
 }
 
 export function sessionStorageRoot(root: string, configuredSessionDir?: string) {
-	return configuredSessionDir ? path.resolve(expandHome(configuredSessionDir)) : path.resolve(root, "sessions");
+	return configuredSessionDir
+		? path.resolve(expandHome(configuredSessionDir))
+		: path.resolve(root, "sessions");
 }
 
-export function sessionSnapshotPathFromAbsolute(sessionFile: string, configuredSessionDir?: string) {
-	const relativePath = toPosix(path.relative(sessionStorageRoot(agentDir(), configuredSessionDir), sessionFile));
+export function sessionSnapshotPathFromAbsolute(
+	sessionFile: string,
+	configuredSessionDir?: string,
+) {
+	const relativePath = toPosix(
+		path.relative(sessionStorageRoot(agentDir(), configuredSessionDir), sessionFile),
+	);
 	if (!relativePath || relativePath.startsWith("../") || path.posix.isAbsolute(relativePath)) {
 		return undefined;
 	}
@@ -195,23 +202,21 @@ export function sessionSnapshotPathFromAbsolute(sessionFile: string, configuredS
 
 export function snapshotTarget(root: string, relativePath: string, configuredSessionDir?: string) {
 	if (isSessionPath(relativePath)) {
-		return safeJoin(sessionStorageRoot(root, configuredSessionDir), relativePath.slice("sessions/".length));
+		return safeJoin(
+			sessionStorageRoot(root, configuredSessionDir),
+			relativePath.slice("sessions/".length),
+		);
 	}
 	return safeJoin(root, relativePath);
 }
 
-function isPathInside(parent: string, child: string) {
-	const relativePath = path.relative(parent, child);
-	return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));
-}
-
 export function snapshotIncludesSessions(snapshot: Snapshot) {
 	return snapshot.syncSessions === true || snapshot.files.some((file) => isSessionPath(file.path));
 }
 
 export function filterSnapshotForConfigPolicy(
 	snapshot: Snapshot,
-	config: Pick<SyncConfig, "syncSessions" | "extraFiles">,
+	config: Pick<SyncConfig, "syncFiles" | "syncSessions" | "extraFiles">,
 	options: { regenerateId?: boolean } = {},
 ) {
 	const extraFilePaths = extraFilePathsByLower(config.extraFiles);
@@ -230,23 +235,9 @@ export function filterSnapshotForConfigPolicy(
 	};
 }
 
-export function isConfiguredSnapshotPath(
-	relativePath: string,
-	config: Pick<SyncConfig, "syncSessions">,
-	extraFiles: Set<string>,
-) {
-	const normalized = toPosix(relativePath);
-	if (isSessionPath(normalized)) return config.syncSessions;
-	if (!normalized.includes("/")) {
-		const lower = normalized.toLowerCase();
-		return TOP_LEVEL_FILE_NAMES.has(lower) || extraFiles.has(lower);
-	}
-	return TOP_LEVEL_DIRS.has(normalized.slice(0, normalized.indexOf("/")));
-}
-
 function canonicalizeSnapshotFilesForConfig(
 	files: SnapshotFile[],
-	config: Pick<SyncConfig, "syncSessions">,
+	config: Pick<SyncConfig, "syncFiles" | "syncSessions">,
 	extraFiles: Set<string>,
 	extraFilePaths: Map<string, string>,
 ) {
@@ -257,14 +248,17 @@ function canonicalizeSnapshotFilesForConfig(
 	>();
 	for (const file of files) {
 		const normalized = toPosix(file.path);
-		if (!isSafeSnapshotPath(file.path) || !isConfiguredSnapshotPath(normalized, config, extraFiles)) {
+		if (
+			!isSafeSnapshotPath(file.path) ||
+			!isConfiguredSnapshotPath(normalized, config, extraFiles)
+		) {
 			continue;
 		}
-		const topLevelPath = canonicalTopLevelFilePath(normalized, extraFilePaths);
-		if (!topLevelPath) {
+		if (normalized.includes("/")) {
 			configuredFiles.push(normalized === file.path ? file : { ...file, path: normalized });
 			continue;
 		}
+		const topLevelPath = canonicalSnapshotPathForConfig(normalized, extraFilePaths);
 		const candidate = {
 			exact: normalized === topLevelPath,
 			file: { ...file, path: topLevelPath },
@@ -281,17 +275,6 @@ function canonicalizeSnapshotFilesForConfig(
 	].sort((left, right) => left.path.localeCompare(right.path));
 }
 
-function canonicalTopLevelFilePath(relativePath: string, extraFilePaths: Map<string, string>) {
-	const normalized = toPosix(relativePath);
-	if (normalized.includes("/")) return undefined;
-	const lower = normalized.toLowerCase();
-	return TOP_LEVEL_FILE_PATHS.get(lower) ?? extraFilePaths.get(lower);
-}
-
-export function canonicalSnapshotPathForConfig(relativePath: string, extraFilePaths: Map<string, string>) {
-	return canonicalTopLevelFilePath(relativePath, extraFilePaths) ?? toPosix(relativePath);
-}
-
 function isPreferredExtraCandidate(
 	left: { exact: boolean; originalPath: string },
 	right: { exact: boolean; originalPath: string },
@@ -332,38 +315,36 @@ export function scanSnapshot(snapshot: Snapshot) {
 export function mergeRemotePreservedFiles(
 	local: Snapshot,
 	remote: Snapshot,
-	config: Pick<SyncConfig, "syncSessions" | "extraFiles">,
+	config: Pick<SyncConfig, "syncFiles" | "syncSessions" | "extraFiles">,
 ) {
-	const withSessions = config.syncSessions ? local : mergeRemoteSessionFiles(local, remote);
-	const paths = new Set(withSessions.files.map((file) => file.path));
-	const pathNames = new Set(withSessions.files.map((file) => file.path.toLowerCase()));
-	const extraFileNames = new Set(normalizeExtraFiles(config.extraFiles).map((file) => file.toLowerCase()));
-	const seenRemoteExtraNames = new Set<string>();
-	const remoteExtras = remote.files.filter((file) => {
+	const localPathNames = new Set(local.files.map((file) => file.path.toLowerCase()));
+	const configuredExtraFiles = new Set(
+		normalizeExtraFiles(config.extraFiles).map((file) => file.toLowerCase()),
+	);
+	const preservedPathNames = new Set<string>();
+	const preserved = remote.files.filter((file) => {
 		const normalized = toPosix(file.path);
 		const lower = normalized.toLowerCase();
 		if (
-			paths.has(normalized) ||
-			pathNames.has(lower) ||
+			localPathNames.has(lower) ||
+			preservedPathNames.has(lower) ||
 			!isSafeSnapshotPath(file.path) ||
-			normalized.includes("/") ||
-			TOP_LEVEL_FILE_NAMES.has(lower) ||
-			RESERVED_TOP_LEVEL_NAMES.has(lower) ||
-			extraFileNames.has(lower) ||
-			seenRemoteExtraNames.has(lower)
+			isConfiguredSnapshotPath(normalized, config, configuredExtraFiles) ||
+			!isPreservableUnmanagedSnapshotPath(normalized)
 		) {
 			return false;
 		}
-		seenRemoteExtraNames.add(lower);
+		preservedPathNames.add(lower);
 		return true;
 	});
-	if (remoteExtras.length === 0) return withSessions;
+	if (preserved.length === 0) return local;
 	return {
-		...withSessions,
+		...local,
 		id: snapshotId(),
 		createdAt: new Date().toISOString(),
 		machine: os.hostname(),
-		files: [...withSessions.files, ...remoteExtras].sort((left, right) =>
+		syncSessions: snapshotIncludesSessions(local) || snapshotIncludesSessions(remote),
+		files: [...local.files, ...preserved].sort((left, right) =>
 			left.path.localeCompare(right.path),
 		),
 	};

package/src/sync-format.ts

@@ -0,0 +1,168 @@
+import { createHash } from "node:crypto";
+import { agentDir } from "./config.js";
+import { fileHashMap } from "./sync-state.js";
+import type { LatestPointer, RemoteObject, Snapshot, SyncConfig } from "./types.js";
+
+export function formatDiff(local: Snapshot, remote: Snapshot) {
+	const localMap = fileHashMap(local);
+	const remoteMap = fileHashMap(remote);
+	const allPaths = [...new Set([...Object.keys(localMap), ...Object.keys(remoteMap)])].sort();
+	const lines = [
+		`local: ${local.files.length} files`,
+		`remote: ${remote.id} (${remote.files.length} files)`,
+		"",
+	];
+	let changed = 0;
+	for (const filePath of allPaths) {
+		if (!localMap[filePath]) {
+			lines.push(`Remote only: ${filePath}`);
+			changed += 1;
+		} else if (!remoteMap[filePath]) {
+			lines.push(`Local only: ${filePath}`);
+			changed += 1;
+		} else if (localMap[filePath] !== remoteMap[filePath]) {
+			lines.push(`Different: ${filePath}`);
+			changed += 1;
+		}
+	}
+	if (changed === 0) lines.push("No file differences.");
+	return lines.join("\n");
+}
+
+export function formatSnapshotOnlyDiff(title: string, snapshot: Snapshot) {
+	return [`${title}: ${snapshot.id}`, ...snapshot.files.map((file) => `Add: ${file.path}`)].join(
+		"\n",
+	);
+}
+
+export function formatPushSummary(
+	config: SyncConfig,
+	upload: Snapshot,
+	latest: RemoteObject<LatestPointer>,
+	preservedRemoteFileCount = 0,
+	remote?: Snapshot,
+) {
+	return [
+		`Target: ${safeTerminalText(config.target ?? "default")}`,
+		`Destination: ${formatDestination(config)}`,
+		`Upload ${upload.files.length} files from ${safeTerminalText(agentDir())}.`,
+		`Sessions: ${upload.syncSessions ? "included — may contain private conversations" : "not included"}`,
+		latest.value ? `Remote latest: ${latest.value.snapshot}` : "Remote latest: empty",
+		"Publication effect: latest.json will point to the new immutable snapshot.",
+		formatPublicationPreview(remote, upload),
+		preservedRemoteFileCount > 0
+			? `Possible secrets in locally managed files were scanned before this prompt; ${preservedRemoteFileCount} preserved remote file(s) were not rescanned.`
+			: "Possible secrets were scanned before this prompt.",
+	].join("\n");
+}
+
+export function formatApplyPreview(local: Snapshot, remote: Snapshot) {
+	return formatDirectionalChanges(local, remote, {
+		add: "Add locally",
+		update: "Update locally",
+		remove: "Remove locally",
+	});
+}
+
+export function formatPullSummary(
+	config: SyncConfig,
+	local: Snapshot,
+	remote: Snapshot,
+	protectedSessionCount: number,
+) {
+	return [
+		`Target: ${safeTerminalText(config.target ?? "default")}`,
+		`Destination: ${formatDestination(config)}`,
+		`Snapshot: ${safeTerminalText(remote.id)}`,
+		`Sessions: ${remote.syncSessions ? "included — may contain private conversations" : "not included"}`,
+		`Protected live sessions: ${protectedSessionCount || "none"}`,
+		formatApplyPreview(local, remote),
+		"A local backup is created before these writes/deletes. The remote active snapshot is unchanged.",
+	].join("\n");
+}
+
+export function formatRollbackSummary(
+	config: SyncConfig,
+	local: Snapshot,
+	remote: Snapshot,
+	requestedSnapshot: string,
+	protectedSessionCount: number,
+) {
+	return [
+		`Target: ${safeTerminalText(config.target ?? "default")}`,
+		`Destination: ${formatDestination(config)}`,
+		`Snapshot: ${safeTerminalText(requestedSnapshot)}`,
+		`Sessions: ${remote.syncSessions ? "included — may contain private conversations" : "not included"}`,
+		`Protected live sessions: ${protectedSessionCount || "none"}`,
+		formatApplyPreview(local, remote),
+		"A local backup is created before applying; the remote latest pointer will change.",
+	].join("\n");
+}
+
+function formatPublicationPreview(remote: Snapshot | undefined, upload: Snapshot) {
+	if (!remote) {
+		return ["Remote is empty.", ...upload.files.map((file) => `Add remotely: ${file.path}`)].join(
+			"\n",
+		);
+	}
+	return formatDirectionalChanges(remote, upload, {
+		add: "Add remotely",
+		update: "Update remotely",
+		remove: "Remove remotely",
+	});
+}
+
+function formatDirectionalChanges(
+	before: Snapshot,
+	after: Snapshot,
+	labels: { add: string; update: string; remove: string },
+) {
+	const beforeMap = fileHashMap(before);
+	const afterMap = fileHashMap(after);
+	const paths = [...new Set([...Object.keys(beforeMap), ...Object.keys(afterMap)])].sort();
+	const lines: string[] = [];
+	for (const filePath of paths) {
+		if (!beforeMap[filePath]) lines.push(`${labels.add}: ${filePath}`);
+		else if (!afterMap[filePath]) lines.push(`${labels.remove}: ${filePath}`);
+		else if (beforeMap[filePath] !== afterMap[filePath])
+			lines.push(`${labels.update}: ${filePath}`);
+	}
+	if (lines.length === 0) lines.push("No file changes.");
+	return lines.join("\n");
+}
+
+export function formatDestination(config: SyncConfig) {
+	let host = config.endpoint;
+	try {
+		host = new URL(config.endpoint).hostname;
+	} catch {
+		// Preserve a sanitized invalid endpoint for actionable repair output.
+	}
+	return safeTerminalText(`${host} · ${config.bucket}/${config.prefix}/profiles/${config.profile}`);
+}
+
+export function countPreservedRemoteFiles(local: Snapshot, upload: Snapshot) {
+	const localPaths = new Set(local.files.map((file) => file.path));
+	return upload.files.filter((file) => !localPaths.has(file.path)).length;
+}
+
+export function safeTerminalText(value: string) {
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: Escape untrusted terminal controls.
+	return value.replace(/[\u0000-\u001f\u007f-\u009f]/gu, "?");
+}
+
+export function redact(value: string) {
+	return value.length <= 8 ? "configured" : `${value.slice(0, 4)}…${value.slice(-4)}`;
+}
+
+export function remoteIdentity(remote: RemoteObject<LatestPointer>) {
+	return remote.missing ? "missing" : (remote.value?.snapshot ?? "unknown");
+}
+
+export function sha256(value: Buffer) {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+export function errorMessage(error: unknown) {
+	return safeTerminalText(error instanceof Error ? error.message : String(error));
+}