@narumitw/pi-sync 0.30.0 → 0.34.0

package/src/sync.ts

@@ -1,7 +1,3 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { promisify } from "node:util";
-import { gunzip, gzip } from "node:zlib";
 import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
@@ -11,107 +7,47 @@ import {
 	completeSyncArguments,
 	parseOptions,
 	resolveSyncCommand,
-	setSyncTargetCompletions,
+	setSyncSetupCompletions,
 	usage,
 	validateCommandOptions,
 } from "./command.js";
 import {
 	activeLocalConfigPath,
-	configuredTargetNames,
+	configuredSyncSetupNames,
 	consumeLocalConfigMigrationNotice,
-	deprecatedPiSyncEnvironmentWarnings,
+	createLocalConfigDocument,
 	ensureStateDir,
-	isEnabled,
-	isExplicitlyEnabled,
 	isMissingConfigError,
 	loadConfig,
 	loadPartialConfig,
 	localConfigPath,
 	localConfigTemplate,
-	normalizeExtraFiles,
-	normalizeSyncFiles,
 	readLocalConfigObject,
 	readStateForConfig,
-	sessionDirForApply,
 	sessionTokenWarnings,
-	stateDir,
 	syncSessionsWarnings,
-	writeLocalConfigObject,
-	writeStateForConfig,
 } from "./config.js";
 import { showFileSelection } from "./file-selection.js";
-import { inspectLock, isLockGuardHeld, isStaleLock, unlock, withLock } from "./lock.js";
+import { unlock, withLock } from "./lock.js";
 import { showSetupWizard, showSyncManager } from "./manager-ui.js";
-import {
-	historyKey,
-	latestKey,
-	pointerFor,
-	profilePrefix,
-	S3Client,
-	snapshotKey,
-} from "./s3-client.js";
-import {
-	createSnapshot,
-	filterSnapshotForConfigPolicy,
-	mergeRemotePreservedFiles,
-	scanSnapshot,
-	sessionSnapshotPathFromAbsolute,
-	snapshotIncludesSessions,
-	snapshotWithoutSessions,
-} from "./snapshot.js";
-import { applySnapshot } from "./snapshot-apply.js";
+import { SetupPullRequiresUiError, useSyncSetup } from "./setup-switch.js";
+import { createSnapshot } from "./snapshot.js";
 import { recoverSnapshotTransactionsOnStartup } from "./snapshot-transaction.js";
+import { errorMessage } from "./sync-format.js";
 import {
-	countPreservedRemoteFiles,
-	errorMessage,
-	formatDestination,
-	formatDiff,
-	formatPullSummary,
-	formatPushSummary,
-	formatRollbackSummary,
-	formatSnapshotOnlyDiff,
-	redact,
-	remoteIdentity,
-	safeTerminalText,
-	sha256,
-} from "./sync-format.js";
-import {
-	canPullRemoteSessionsOnFirstSync,
-	canPullRemoteSettingsOnFirstSync,
-	fileHashMap,
-	hasLocalChanges,
-	hasRemoteChanges,
-	remoteChangedSinceState,
-	sameHashes,
-	shouldRefreshSyncedState,
-	snapshotHashesMatchState,
-	snapshotsMatch,
-	syncPolicyChanged,
-} from "./sync-state.js";
-import { TargetPullRequiresUiError, useSyncTarget } from "./target-switch.js";
-import type {
-	CommandOptions,
-	LatestPointer,
-	RemoteObject,
-	Snapshot,
-	SnapshotOptions,
-	SyncConfig,
-	SyncState,
-} from "./types.js";
+	diff,
+	doctor,
+	history,
+	pull,
+	push,
+	rollback,
+	status,
+	syncBoth,
+} from "./sync-operations.js";
+import { hasLocalChanges } from "./sync-state.js";
+import type { AnySyncConfig, CommandOptions, SnapshotOptions } from "./types.js";
 
-const [gzipAsync, gunzipAsync] = [promisify(gzip), promisify(gunzip)];
 const STATUS_KEY = "sync";
-const VERSION = 1;
-const DEFAULT_PROFILE = "default";
-const DEFAULT_PREFIX = "pi-sync";
-const DEFAULT_REGION = "auto";
-
-interface PushInput {
-	config: SyncConfig;
-	state: SyncState;
-	local: Snapshot;
-	client?: S3Client;
-}
 
 const AUTO_SYNC_OPTIONS: CommandOptions = {
 	yes: true,
@@ -123,55 +59,89 @@ const AUTO_SYNC_OPTIONS: CommandOptions = {
 	args: [],
 };
 export default function sync(pi: ExtensionAPI) {
+	let sessionAbort = new AbortController();
+	let shutdownAbort: AbortController | undefined;
+
 	pi.registerCommand("sync", {
-		description: "Sync Pi settings through Cloudflare R2 or S3-compatible storage",
+		description: "Sync Pi settings through Git, WebDAV, R2, or S3-compatible storage",
 		getArgumentCompletions: completeSyncArguments,
 		handler: async (args, ctx) => {
-			await handleCommand(args, ctx);
+			if (!ctx.hasUI) {
+				throw new Error(
+					"/sync requires TUI or RPC mode so results and safety prompts are observable.",
+				);
+			}
+			await handleCommand(args, ctx, sessionAbort.signal);
 		},
 	});
 
 	pi.on("session_start", async (_event, ctx) => {
+		shutdownAbort?.abort(new DOMException("Session replaced", "AbortError"));
+		shutdownAbort = undefined;
+		sessionAbort.abort(new DOMException("Session replaced", "AbortError"));
+		sessionAbort = new AbortController();
+		const signal = sessionAbort.signal;
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 		try {
 			await recoverSnapshotTransactionsOnStartup();
+			if (signal.aborted) return;
 		} catch (error) {
+			if (signal.aborted) return;
 			ctx.ui.notify(`pi-sync recovery required: ${errorMessage(error)}`, "error");
 			return;
 		}
 		try {
-			setSyncTargetCompletions(await configuredTargetNames());
+			setSyncSetupCompletions(await configuredSyncSetupNames());
+			if (signal.aborted) return;
 		} catch {
-			setSyncTargetCompletions([]);
+			if (signal.aborted) return;
+			setSyncSetupCompletions([]);
 		}
 		const migrationNotice = consumeLocalConfigMigrationNotice();
 		if (migrationNotice) ctx.ui.notify(migrationNotice, "warning");
-		const warnings = deprecatedPiSyncEnvironmentWarnings();
-		if (warnings.length > 0) ctx.ui.notify(warnings.join("\n"), "warning");
-		await autoSync(ctx);
+		if (signal.aborted) return;
+		await autoSync(ctx, signal);
 	});
 
 	pi.on("session_shutdown", async (event, ctx) => {
+		sessionAbort.abort(new DOMException("Session shut down", "AbortError"));
+		shutdownAbort?.abort(new DOMException("Session shut down again", "AbortError"));
+		const controller = new AbortController();
+		shutdownAbort = controller;
+		const signal = combineSignals(controller.signal, AbortSignal.timeout(30_000));
 		const reason =
 			typeof event === "object" && event ? (event as { reason?: string }).reason : undefined;
-		if (reason !== "reload") await autoPushSessions(ctx);
+		try {
+			if (reason !== "reload") await autoPushSessions(ctx, signal);
+		} finally {
+			if (shutdownAbort === controller) shutdownAbort = undefined;
+		}
+		if (signal.aborted) return;
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 	});
 }
 
-async function handleCommand(rawArgs: string, ctx: ExtensionCommandContext) {
+async function handleCommand(
+	rawArgs: string,
+	ctx: ExtensionCommandContext,
+	sessionSignal: AbortSignal,
+) {
 	if (!rawArgs.trim()) {
 		try {
-			await showSyncManager(ctx, (route, signal, onCommit, target) =>
-				executeCommand(route, ctx, signal, onCommit, target),
+			await showSyncManager(
+				ctx,
+				(route, signal, onCommit, target) =>
+					executeCommand(route, ctx, combineSignals(sessionSignal, signal), onCommit, target),
+				sessionSignal,
 			);
 		} catch (error) {
+			if (sessionSignal.aborted) return;
 			ctx.ui.setStatus(STATUS_KEY, undefined);
 			ctx.ui.notify(errorMessage(error), "error");
 		}
 		return;
 	}
-	await executeCommand(rawArgs, ctx);
+	await executeCommand(rawArgs, ctx, sessionSignal);
 }
 
 async function executeCommand(
@@ -179,14 +149,14 @@ async function executeCommand(
 	ctx: ExtensionCommandContext,
 	signal?: AbortSignal,
 	onCommit?: () => void,
-	target?: string,
+	setup?: string,
 ) {
 	try {
 		const command = await resolveSyncCommand(rawArgs, ctx);
-		if (!command) return;
+		if (signal?.aborted || !command) return;
 		const { subcommand, rest } = command;
 		const options = parseOptions(rest);
-		if (target !== undefined) options.target = target;
+		if (setup !== undefined) options.setup = setup;
 		if (signal) options.signal = signal;
 		if (onCommit) options.onCommit = onCommit;
 		validateCommandOptions(subcommand, options);
@@ -196,18 +166,23 @@ async function executeCommand(
 				ctx.ui.notify(usage(), "info");
 				return;
 			case "use":
-				await useSyncTarget(ctx, options.args[0] ?? "", (selectedTarget) =>
-					withLock("pull", () => pull(ctx, { ...options, target: selectedTarget })),
+				await useSyncSetup(
+					ctx,
+					options.args[0] ?? "",
+					(selectedSetup) =>
+						withLock("pull", () => pull(ctx, { ...options, setup: selectedSetup })),
+					undefined,
+					options.signal,
 				);
 				return;
 			case "init":
-				await initConfig(ctx);
+				await initConfig(ctx, signal);
 				return;
 			case "config":
 				await showConfig(ctx, options);
 				return;
 			case "files":
-				await showFileSelection(ctx, options.target);
+				await showFileSelection(ctx, options.setup, options.signal);
 				return;
 			case "status":
 				await status(ctx, options);
@@ -239,49 +214,64 @@ async function executeCommand(
 				ctx.ui.notify(`Unknown /sync command: ${subcommand}\n\n${usage()}`, "warning");
 		}
 	} catch (error) {
+		if (signal?.aborted) return;
 		ctx.ui.setStatus(STATUS_KEY, undefined);
-		if (signal?.aborted && error instanceof Error && error.name === "AbortError") return;
-		if (error instanceof TargetPullRequiresUiError) throw error;
+		if (error instanceof SetupPullRequiresUiError) throw error;
 		ctx.ui.notify(errorMessage(error), "error");
 	}
 }
 
-async function autoSync(ctx: ExtensionContext) {
+async function autoSync(ctx: ExtensionContext, signal: AbortSignal) {
 	try {
 		const partial = await loadPartialConfig();
-		if (!isEnabled(partial.autoSync ?? process.env.PI_SYNC_AUTO_SYNC, true)) return;
+		throwIfAborted(signal);
+		if (!partial.automatic) return;
 		await ensureStateDir();
+		throwIfAborted(signal);
 		await loadConfig();
-		await withLock("auto-sync", () => syncBoth(ctx, AUTO_SYNC_OPTIONS));
+		throwIfAborted(signal);
+		await withLock("auto-sync", () => {
+			throwIfAborted(signal);
+			return syncBoth(ctx, { ...AUTO_SYNC_OPTIONS, signal });
+		});
 	} catch (error) {
-		if (isMissingConfigError(error)) return;
+		if (signal.aborted || isMissingConfigError(error)) return;
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 		ctx.ui.notify(`pi-sync auto sync skipped: ${errorMessage(error)}`, "warning");
 	}
 }
 
-async function autoPushSessions(ctx: ExtensionContext) {
+async function autoPushSessions(ctx: ExtensionContext, signal: AbortSignal) {
 	try {
 		const partial = await loadPartialConfig();
-		if (!isEnabled(partial.autoSync ?? process.env.PI_SYNC_AUTO_SYNC, true)) return;
-		if (!isExplicitlyEnabled(partial.syncSessions)) return;
+		throwIfAborted(signal);
+		if (!partial.automatic) return;
+		if (!partial.include.includes("sessions")) return;
 		await ensureStateDir();
+		throwIfAborted(signal);
 		const config = await loadConfig();
-		if (!config.syncSessions) return;
+		throwIfAborted(signal);
+		if (!config.include.includes("sessions")) return;
 		await withLock("auto-session-push", async () => {
+			throwIfAborted(signal);
 			const state = await readStateForConfig(config);
-			const local = await createSnapshot(config.profile, snapshotOptionsForContext(ctx, config));
+			throwIfAborted(signal);
+			const local = await createSnapshot(
+				config.snapshotIdentity,
+				snapshotOptionsForContext(ctx, config),
+			);
+			throwIfAborted(signal);
 			if (!hasLocalChanges(local, state, config)) return;
-			await push(ctx, AUTO_SYNC_OPTIONS, { config, state, local });
+			await push(ctx, { ...AUTO_SYNC_OPTIONS, signal }, { config, state, local });
 		});
 	} catch (error) {
-		if (isMissingConfigError(error)) return;
+		if (signal.aborted || isMissingConfigError(error)) return;
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 		ctx.ui.notify(`pi-sync session push skipped: ${errorMessage(error)}`, "warning");
 	}
 }
 
-async function initConfig(ctx: ExtensionCommandContext) {
+async function initConfig(ctx: ExtensionCommandContext, signal?: AbortSignal) {
 	const configPath = localConfigPath();
 	if (await readLocalConfigObject()) {
 		ctx.ui.notify(`Config already exists: ${await activeLocalConfigPath()}`, "info");
@@ -289,533 +279,115 @@ async function initConfig(ctx: ExtensionCommandContext) {
 	}
 
 	if (ctx.mode === "tui") {
-		await showSetupWizard(ctx);
+		await showSetupWizard(ctx, signal);
 		return;
 	}
-	await writeLocalConfigObject(localConfigTemplate());
-	ctx.ui.notify(`Created ${configPath}. Fill in R2 credentials, then run /sync doctor.`, "info");
+	await createLocalConfigDocument(localConfigTemplate());
+	ctx.ui.notify(
+		`Created ${configPath}. Add a storage connection and sync setup before syncing.`,
+		"info",
+	);
 }
 
 async function showConfig(ctx: ExtensionCommandContext, options: CommandOptions) {
-	const partial = await loadPartialConfig(options.target);
-	const syncSessions = isExplicitlyEnabled(partial.syncSessions);
+	const config = await loadConfig(options.setup);
 	const warnings = [
-		...deprecatedPiSyncEnvironmentWarnings(),
-		...sessionTokenWarnings(partial),
-		...syncSessionsWarnings({ syncSessions }),
+		...(config.backend.type === "s3" ? sessionTokenWarnings(config.backend.profile) : []),
+		...syncSessionsWarnings(config),
 	];
+	const storageLines = configStorageLines(config);
 	ctx.ui.notify(
 		[
 			"pi-sync config:",
-			`target: ${partial.target ?? "default"}`,
-			`storage profile: ${partial.storageProfile ?? "default"}`,
-			`endpoint: ${partial.endpoint ?? "missing"}`,
-			`bucket: ${partial.bucket ?? "missing"}`,
-			`region: ${partial.region ?? DEFAULT_REGION}`,
-			`accessKeyId: ${partial.accessKeyId ? redact(partial.accessKeyId) : "missing"}`,
-			`secretAccessKey: ${partial.secretAccessKey ? "configured" : "missing"}`,
-			`sessionToken: ${partial.sessionToken ? "configured" : "not configured"}`,
-			`profile: ${partial.profile ?? DEFAULT_PROFILE}`,
-			`prefix: ${partial.prefix ?? DEFAULT_PREFIX}`,
-			`autoSync: ${isEnabled(partial.autoSync ?? process.env.PI_SYNC_AUTO_SYNC, true) ? "enabled" : "disabled"}`,
-			`syncFiles: ${normalizeSyncFiles(partial.syncFiles).join(", ") || "none"}`,
-			`syncSessions: ${syncSessions ? "enabled" : "disabled"}`,
-			`extraFiles: ${normalizeExtraFiles(partial.extraFiles).join(", ") || "none"}`,
-			`local config: ${localConfigPath()}`,
+			`sync setup: ${config.setupName}`,
+			`storage connection: ${config.connectionName}`,
+			...storageLines,
+			`storage path: ${config.storagePath}`,
+			`automatic sync: ${config.automatic ? "enabled" : "disabled"}`,
+			`included content: ${config.include.join(", ") || "none"}`,
+			`sessions: ${config.include.includes("sessions") ? "included" : "not included"}`,
+			`settings file: ${localConfigPath()}`,
 			...warnings,
 		].join("\n"),
 		warnings.length > 0 ? "warning" : "info",
 	);
 }
 
-async function status(ctx: ExtensionCommandContext, options: CommandOptions) {
-	const config = await loadConfig(options.target);
-	ctx.ui.setStatus(STATUS_KEY, `checking ${config.target ?? "default"}`);
-	const client = new S3Client(config, options.signal);
-	const local = await createSnapshot(config.profile, snapshotOptionsForContext(ctx, config));
-	const state = await readStateForConfig(config);
-	const latest = await client.getJson<LatestPointer>(latestKey(config));
-	const localChanged = hasLocalChanges(local, state, config);
-
-	let remoteText = "remote: empty";
-	const remoteChanged = remoteChangedSinceState(latest, state, config);
-	if (!latest.missing && latest.value) {
-		remoteText = `remote: ${latest.value.snapshot} from ${latest.value.machine} at ${latest.value.createdAt}`;
+function configStorageLines(config: AnySyncConfig) {
+	switch (config.backend.type) {
+		case "git":
+			return [
+				"kind: git",
+				`remote: ${displayGitRemote(config.backend.profile.remote)}`,
+				"authentication: existing Git/SSH credentials (not stored)",
+				`branch: ${config.backend.destination.branch}`,
+			];
+		case "webdav":
+			return [
+				"kind: webdav",
+				`url: ${displayWebDavUrl(config.backend.profile.url, config.backend.profile.username)}`,
+				"username: configured (value hidden)",
+				"password: configured",
+			];
+		case "s3":
+			return [
+				"kind: s3",
+				`endpoint: ${config.backend.profile.endpoint}`,
+				`bucket: ${config.backend.destination.bucket}`,
+				`region: ${config.backend.profile.region}`,
+				"access key id: configured",
+				"secret access key: configured",
+				`session token: ${config.backend.profile.sessionToken ? "configured" : "not configured"}`,
+			];
 	}
-
-	const warnings = [...deprecatedPiSyncEnvironmentWarnings(), ...syncSessionsWarnings(config)];
-	ctx.ui.setStatus(STATUS_KEY, undefined);
-	ctx.ui.notify(
-		[
-			`target: ${config.target ?? "default"}`,
-			`storage profile: ${config.storageProfile ?? "default"}`,
-			`destination: ${formatDestination(config)}`,
-			`remote namespace: ${config.profile}`,
-			`sync files: ${normalizeSyncFiles(config.syncFiles).join(", ") || "none"}`,
-			`extra files: ${config.extraFiles.join(", ") || "none"}`,
-			`sessions: ${config.syncSessions ? "included" : "excluded"}`,
-			remoteText,
-			`local files: ${local.files.length}`,
-			`local changed since last sync: ${localChanged ? "yes" : "no"}`,
-			`remote changed since last sync: ${remoteChanged ? "yes" : "no"}`,
-			...warnings,
-		].join("\n"),
-		localChanged || remoteChanged || warnings.length > 0 ? "warning" : "info",
-	);
 }
 
-async function diff(ctx: ExtensionCommandContext, options: CommandOptions) {
-	const config = await loadConfig(options.target);
-	ctx.ui.setStatus(STATUS_KEY, `checking ${config.target ?? "default"}`);
-	const client = new S3Client(config, options.signal);
-	const local = await createSnapshot(config.profile, snapshotOptionsForContext(ctx, config));
-	const remote = await readRemoteSnapshot(client, config);
-	ctx.ui.setStatus(STATUS_KEY, undefined);
-
-	const warnings = [...deprecatedPiSyncEnvironmentWarnings(), ...syncSessionsWarnings(config)];
-	const header = [
-		`target: ${config.target ?? "default"}`,
-		`storage profile: ${config.storageProfile ?? "default"}`,
-		`destination: ${formatDestination(config)}`,
-		`sync files: ${normalizeSyncFiles(config.syncFiles).join(", ") || "none"}`,
-		`extra files: ${config.extraFiles.join(", ") || "none"}`,
-		`sessions: ${config.syncSessions ? "included" : "excluded"}`,
-		...warnings,
-	].join("\n");
-	const level = warnings.length > 0 ? "warning" : "info";
-	if (!remote) {
-		ctx.ui.notify(
-			`${header}\n\n${formatSnapshotOnlyDiff("Remote is empty. Local push would upload", local)}`,
-			level,
-		);
-		return;
-	}
-
-	ctx.ui.notify(`${header}\n\n${formatDiff(local, remote)}`, level);
-}
-
-async function doctor(ctx: ExtensionCommandContext, options: CommandOptions) {
-	const messages: string[] = [];
-	let level: "info" | "warning" = "info";
-	let snapshotOptions: SnapshotOptions = {};
-	let profile = DEFAULT_PROFILE;
-
+function displayGitRemote(value: string | undefined) {
+	if (!value) return "missing";
 	try {
-		const config = await loadConfig(options.target);
-		profile = config.profile;
-		snapshotOptions = snapshotOptionsForContext(ctx, config);
-		messages.push(
-			`config: ok (target ${config.target ?? "default"}; ${config.bucket}/${profilePrefix(config)})`,
-		);
-		messages.push(`sync files: ${normalizeSyncFiles(config.syncFiles).join(", ") || "none"}`);
-		messages.push(`extra files: ${config.extraFiles.join(", ") || "none"}`);
-		messages.push(`sessions: ${config.syncSessions ? "included" : "excluded"}`);
-		const warnings = [
-			...deprecatedPiSyncEnvironmentWarnings(),
-			...sessionTokenWarnings(config),
-			...syncSessionsWarnings(config),
-		];
-		if (warnings.length > 0) {
-			level = "warning";
-			messages.push(...warnings);
-		}
-	} catch (error) {
-		level = "warning";
-		messages.push(`config: ${errorMessage(error)}`);
-	}
-
-	const local = await createSnapshot(profile, snapshotOptions);
-	const secrets = scanSnapshot(local);
-	if (secrets.length > 0) {
-		level = "warning";
-		messages.push("secret scan: possible secrets found:");
-		messages.push(...secrets.map((secret) => `- ${secret}`));
-	} else {
-		messages.push(`secret scan: ok (${local.files.length} files checked)`);
-	}
-
-	const lock = await inspectLock();
-	if (lock.status === "valid" && isStaleLock(lock.lock)) {
-		level = "warning";
-		messages.push(
-			`lock: stale (pid ${lock.lock.pid}); run /sync unlock after verifying no sync is running`,
-		);
-	} else if (lock.status === "valid") {
-		messages.push(`lock: held by pid ${lock.lock.pid} since ${lock.lock.startedAt}`);
-	} else if (lock.status === "unreadable") {
-		level = "warning";
-		messages.push(
-			"lock: unreadable; use /sync unlock --stale only after verifying no sync is running",
-		);
-	} else if (await isLockGuardHeld()) {
-		level = "warning";
-		messages.push("lock: guard active while metadata is missing or still being initialized");
-	} else {
-		messages.push("lock: free");
-	}
-	ctx.ui.notify(messages.join("\n"), level);
-}
-
-async function push(
-	ctx: ExtensionCommandContext | ExtensionContext,
-	options: CommandOptions,
-	input?: PushInput,
-) {
-	const config = input?.config ?? (await loadConfig(options.target));
-	ctx.ui.setStatus(STATUS_KEY, `pushing ${config.target ?? "default"}`);
-	const client = input?.client ?? new S3Client(config, options.signal);
-	const state = input?.state ?? (await readStateForConfig(config));
-	const local =
-		input?.local ?? (await createSnapshot(config.profile, snapshotOptionsForContext(ctx, config)));
-
-	const latest = await client.getJson<LatestPointer>(latestKey(config));
-	const remoteForUpload = await readRemoteSnapshotForUpload(client, config, latest, state);
-	if (remoteChangedSinceState(latest, state, config) && !options.force) {
-		const remoteForConflict = remoteForUpload
-			? filterSnapshotForConfigPolicy(remoteForUpload, config)
-			: undefined;
-		if (!remoteForConflict || !snapshotHashesMatchState(remoteForConflict, state, config)) {
-			throw new Error(
-				"Remote or sync policy changed since last sync. Run /sync pull first or /sync push --force.",
-			);
-		}
-	}
-
-	const upload = await snapshotForUpload(client, config, local, latest, remoteForUpload);
-	const secrets = scanSnapshot(local);
-	if (secrets.length > 0) {
-		throw new Error(
-			`Refusing to push possible secrets:\n${secrets.map((s) => `- ${s}`).join("\n")}`,
-		);
-	}
-
-	const preservedRemoteFileCount = countPreservedRemoteFiles(local, upload);
-	if (
-		!options.yes &&
-		!(await ctx.ui.confirm(
-			snapshotIncludesSessions(upload) ? "Push pi settings and sessions?" : "Push pi settings?",
-			formatPushSummary(config, upload, latest, preservedRemoteFileCount, remoteForUpload),
-		))
-	) {
-		ctx.ui.setStatus(STATUS_KEY, undefined);
-		ctx.ui.notify("Push cancelled.", "info");
-		return;
-	}
-
-	options.onCommit?.();
-	const publicationClient = options.onCommit ? new S3Client(config) : client;
-	const pointer = await uploadSnapshot(publicationClient, config, upload, latest, options.force);
-	const historyWarning = await updateHistorySafely(publicationClient, config, pointer);
-	await writeStateForConfig(config, {
-		version: VERSION,
-		profile: config.profile,
-		lastAppliedSnapshot: pointer.snapshot,
-		lastRemoteEtag: undefined,
-		lastFileHashes: fileHashMap(local),
-		syncFiles: config.syncFiles,
-		syncSessions: config.syncSessions,
-		extraFiles: config.extraFiles,
-	});
-	ctx.ui.setStatus(STATUS_KEY, undefined);
-	if (!options.silent) {
-		ctx.ui.notify(
-			[
-				`Pushed ${upload.files.length} files from target “${config.target ?? "default"}” as ${pointer.snapshot}.`,
-				historyWarning,
-			]
-				.filter(Boolean)
-				.join("\n"),
-			historyWarning ? "warning" : "info",
-		);
+		const url = new URL(value);
+		url.username = "";
+		url.password = "";
+		url.search = "";
+		url.hash = "";
+		return url.toString();
+	} catch {
+		return value.replace(/^(?:[^@\s]+@)?(?<host>[^:]+):.+$/u, "$<host>:…");
 	}
 }
 
-async function pull(ctx: ExtensionCommandContext | ExtensionContext, options: CommandOptions) {
-	const config = await loadConfig(options.target);
-	ctx.ui.setStatus(STATUS_KEY, `pulling ${config.target ?? "default"}`);
-	const client = new S3Client(config, options.signal);
-	const state = await readStateForConfig(config);
-	const local = await createSnapshot(config.profile, snapshotOptionsForContext(ctx, config));
-	const remote = await readRemoteSnapshot(client, config);
-	if (!remote) throw new Error("Remote is empty. Run /sync push from a configured machine first.");
-
-	const localChanged = hasLocalChanges(local, state, config);
-	const remoteChanged = hasRemoteChanges(remote, state, config, protectedSessionPaths(ctx));
-	if (localChanged && remoteChanged && state.lastAppliedSnapshot && !options.force) {
-		throw new Error(
-			"Both local and remote changed since last sync. Run /sync diff, then choose /sync pull --force or /sync push --force.",
-		);
-	}
-
-	if (
-		!options.yes &&
-		!(await ctx.ui.confirm(
-			snapshotIncludesSessions(remote) ? "Pull pi settings and sessions?" : "Pull pi settings?",
-			formatPullSummary(config, local, remote, protectedSessionPaths(ctx).size),
-		))
-	) {
-		ctx.ui.setStatus(STATUS_KEY, undefined);
-		ctx.ui.notify("Pull cancelled.", "info");
-		return "cancelled" as const;
-	}
-
-	options.onCommit?.();
-	const backup = await backupLocal(config.profile, snapshotOptionsForContext(ctx, config));
-	const applySessionDir = await sessionDirForApply(ctx, remote);
-	const lastFileHashes = await applySnapshot(remote, protectedSessionPaths(ctx), {
-		syncFiles: config.syncFiles,
-		sessionDir: applySessionDir,
-		extraFiles: config.extraFiles,
-	});
-	await writeStateForConfig(config, {
-		version: VERSION,
-		profile: config.profile,
-		lastAppliedSnapshot: remote.id,
-		lastRemoteEtag: undefined,
-		lastFileHashes,
-		syncFiles: config.syncFiles,
-		syncSessions: config.syncSessions,
-		extraFiles: config.extraFiles,
-	});
-	ctx.ui.setStatus(STATUS_KEY, undefined);
-	if (!options.silent) {
-		ctx.ui.notify(
-			`Pulled ${remote.files.length} files from ${remote.id}. Backup: ${backup}`,
-			"info",
-		);
-	} else if (options.auto && config.syncSessions && snapshotIncludesSessions(remote)) {
-		ctx.ui.notify(
-			"Pulled Pi sessions after startup selected the current session. Restart Pi or resume a pulled session to use newly synced conversations.",
-			"warning",
-		);
-	}
-	if (options.reload) await maybeReload(ctx);
-	return "applied" as const;
-}
-
-async function syncBoth(ctx: ExtensionCommandContext | ExtensionContext, options: CommandOptions) {
-	const config = await loadConfig(options.target);
-	const client = new S3Client(config, options.signal);
-	const state = await readStateForConfig(config);
-	const local = await createSnapshot(config.profile, snapshotOptionsForContext(ctx, config));
-	if (
-		normalizeSyncFiles(config.syncFiles).length === 0 &&
-		config.extraFiles.length === 0 &&
-		!config.syncSessions
-	) {
-		if (!options.silent) {
-			ctx.ui.notify(
-				`Target “${config.target ?? "default"}” manages no files. Choose synced content in /sync Settings before syncing.`,
-				"warning",
-			);
-		}
-		return;
-	}
-	const remote = await readRemoteSnapshot(client, config);
-	const localChanged = hasLocalChanges(local, state, config);
-	const remoteChanged = remote
-		? hasRemoteChanges(remote, state, config, protectedSessionPaths(ctx))
-		: false;
-	const firstSync = !state.lastAppliedSnapshot;
-
-	if (firstSync && remote && remote.files.length > 0 && local.files.length > 0) {
-		if (!canPullRemoteSettingsOnFirstSync(local, remote)) {
-			throw new Error(
-				"Remote settings exist and this machine has different local Pi settings. Run /sync diff, then manually choose /sync pull or /sync push.",
-			);
-		}
-		if (!sameHashes(fileHashMap(local), fileHashMap(remote))) {
-			if (!canPullRemoteSessionsOnFirstSync(local, remote)) {
-				throw new Error(
-					"Remote settings match, but local and remote Pi sessions differ. Run /sync diff, then manually choose /sync pull or /sync push.",
-				);
-			}
-			await pull(ctx, options);
-			return;
-		}
-		await writeStateForConfig(config, {
-			version: VERSION,
-			profile: config.profile,
-			lastAppliedSnapshot: remote.id,
-			lastRemoteEtag: undefined,
-			lastFileHashes: fileHashMap(remote),
-			syncFiles: config.syncFiles,
-			syncSessions: config.syncSessions,
-			extraFiles: config.extraFiles,
-		});
-		if (!options.silent)
-			ctx.ui.notify("pi-sync state initialized; local settings already match remote.", "info");
-		return;
-	}
-	if (localChanged && remoteChanged && remote && snapshotsMatch(local, remote)) {
-		await writeStateForConfig(config, {
-			version: VERSION,
-			profile: config.profile,
-			lastAppliedSnapshot: remote.id,
-			lastRemoteEtag: undefined,
-			lastFileHashes: fileHashMap(remote),
-			syncFiles: config.syncFiles,
-			syncSessions: config.syncSessions,
-			extraFiles: config.extraFiles,
-		});
-		if (!options.silent) ctx.ui.notify("pi-sync is already up to date.", "info");
-		return;
-	}
-	if (localChanged && remoteChanged && state.lastAppliedSnapshot) {
-		throw new Error(
-			"Both local and remote changed. Run /sync diff and resolve with push --force or pull --force.",
-		);
-	}
-	if (remoteChanged) {
-		await pull(ctx, options);
-		return;
-	}
-	if (localChanged || !remote) {
-		await push(ctx, options);
-		return;
-	}
-	if (shouldRefreshSyncedState(remote, state, config)) {
-		await writeStateForConfig(config, {
-			version: VERSION,
-			profile: config.profile,
-			lastAppliedSnapshot: remote.id,
-			lastRemoteEtag: undefined,
-			lastFileHashes: fileHashMap(remote),
-			syncFiles: config.syncFiles,
-			syncSessions: config.syncSessions,
-			extraFiles: config.extraFiles,
-		});
-	}
-	if (!options.silent) ctx.ui.notify("pi-sync is already up to date.", "info");
-}
-
-async function history(ctx: ExtensionCommandContext, options: CommandOptions) {
-	const config = await loadConfig(options.target);
-	const client = new S3Client(config, options.signal);
-	const remote = await client.getJson<{ snapshots?: LatestPointer[] }>(historyKey(config));
-	if (remote.missing || !remote.value?.snapshots?.length) {
-		ctx.ui.notify("No remote pi-sync history found.", "info");
-		return;
-	}
-
-	const snapshots = remote.value.snapshots.slice(-20).reverse();
-	const currentSnapshot = snapshots[0]?.snapshot;
-	if (ctx.mode === "tui") {
-		const labels = snapshots.map(
-			(item, index) =>
-				`${index + 1}. ${item.createdAt} · ${safeTerminalText(item.machine)} · ${item.snapshot}${item.snapshot === currentSnapshot ? " (current)" : ""}${item.syncSessions ? " · sessions" : ""}`,
-		);
-		const selected = await ctx.ui.select(
-			`History for target “${safeTerminalText(config.target ?? "default")}”\n\nChoose a snapshot to preview rollback.`,
-			[...labels, "Back"],
-		);
-		if (!selected || selected === "Back") return;
-		const index = labels.indexOf(selected);
-		const snapshot = snapshots[index];
-		if (!snapshot) return;
-		await withLock("rollback", () =>
-			rollback(ctx, { ...options, args: [snapshot.snapshot], yes: false }),
-		);
-		return;
+function displayWebDavUrl(value: string | undefined, username: string | undefined) {
+	if (!value) return "missing";
+	try {
+		const url = new URL(value);
+		url.username = "";
+		url.password = "";
+		url.search = "";
+		url.hash = "";
+		return username ? `${url.origin}/…` : `${url.origin}${url.pathname}`;
+	} catch {
+		return "invalid (value hidden)";
 	}
-	ctx.ui.notify(
-		snapshots
-			.map((item) => `${item.snapshot} ${item.createdAt} ${safeTerminalText(item.machine)}`)
-			.join("\n"),
-		"info",
-	);
 }
 
-async function rollback(ctx: ExtensionCommandContext, options: CommandOptions) {
-	const target = options.args[0];
-	if (!target) throw new Error("Usage: /sync rollback <snapshot-id> [--yes]");
-
-	const config = await loadConfig(options.target);
-	const client = new S3Client(config, options.signal);
-	const snapshot = await client.getBuffer(snapshotKey(config, target));
-	if (!snapshot.value) throw new Error(`Snapshot not found: ${target}`);
-	const decoded = await decodeSnapshot(snapshot.value);
-	const remote = filterSnapshotForConfigPolicy(
-		config.syncSessions ? decoded : snapshotWithoutSessions(decoded),
-		config,
-		{ regenerateId: true },
-	);
-	const local = await createSnapshot(config.profile, snapshotOptionsForContext(ctx, config));
-
-	if (
-		!options.yes &&
-		!(await ctx.ui.confirm(
-			snapshotIncludesSessions(remote)
-				? "Rollback pi settings and sessions?"
-				: "Rollback pi settings?",
-			formatRollbackSummary(config, local, remote, target, protectedSessionPaths(ctx).size),
-		))
-	) {
-		ctx.ui.notify("Rollback cancelled.", "info");
-		return;
-	}
-
-	options.onCommit?.();
-	const backup = await backupLocal(config.profile, snapshotOptionsForContext(ctx, config));
-	const applySessionDir = await sessionDirForApply(ctx, remote);
-	const lastFileHashes = await applySnapshot(remote, protectedSessionPaths(ctx), {
-		syncFiles: config.syncFiles,
-		sessionDir: applySessionDir,
-		extraFiles: config.extraFiles,
-	});
-	const publicationClient = options.onCommit ? new S3Client(config) : client;
-	const latest = await publicationClient.getJson<LatestPointer>(latestKey(config));
-	const upload = await snapshotForUpload(publicationClient, config, remote, latest, undefined, {
-		ignoreUnreadableRemote: true,
-	});
-	const encoded = upload.id === decoded.id ? snapshot.value : await encodeSnapshot(upload);
-	if (upload.id !== decoded.id) {
-		await publicationClient.putBuffer(snapshotKey(config, upload.id), encoded, "application/gzip");
-	}
-	const pointer = pointerFor(config, upload, sha256(encoded));
-	await publicationClient.putJson(latestKey(config), pointer);
-	const historyWarning = await updateHistorySafely(publicationClient, config, pointer);
-	await writeStateForConfig(config, {
-		version: VERSION,
-		profile: config.profile,
-		lastAppliedSnapshot: pointer.snapshot,
-		lastRemoteEtag: undefined,
-		lastFileHashes,
-		syncFiles: config.syncFiles,
-		syncSessions: config.syncSessions,
-		extraFiles: config.extraFiles,
-	});
-	ctx.ui.notify(
-		[
-			`Rolled back target “${config.target ?? "default"}” to ${target}; latest: ${pointer.snapshot}. Backup: ${backup}`,
-			historyWarning,
-		]
-			.filter(Boolean)
-			.join("\n"),
-		historyWarning ? "warning" : "info",
-	);
-	await maybeReload(ctx);
+function throwIfAborted(signal: AbortSignal) {
+	if (!signal.aborted) return;
+	throw signal.reason instanceof Error
+		? signal.reason
+		: new DOMException("The operation was aborted", "AbortError");
 }
 
-function protectedSessionPaths(ctx: ExtensionCommandContext | ExtensionContext) {
-	const getSessionFile = ctx.sessionManager.getSessionFile;
-	if (typeof getSessionFile !== "function") return new Set<string>();
-	const sessionFile = getSessionFile.call(ctx.sessionManager) as string | undefined;
-	const snapshotPath = sessionFile
-		? sessionSnapshotPathFromAbsolute(sessionFile, sessionDirFromContext(ctx))
-		: undefined;
-	return snapshotPath ? new Set([snapshotPath]) : new Set<string>();
+function combineSignals(primary: AbortSignal, secondary?: AbortSignal) {
+	return secondary ? AbortSignal.any([primary, secondary]) : primary;
 }
 
 function snapshotOptionsForContext(
 	ctx: ExtensionCommandContext | ExtensionContext,
-	config: SyncConfig,
+	config: AnySyncConfig,
 ): SnapshotOptions {
 	return {
-		syncFiles: config.syncFiles,
-		syncSessions: config.syncSessions,
+		include: config.include,
 		sessionDir: sessionDirFromContext(ctx),
-		extraFiles: config.extraFiles,
 	};
 }
 
@@ -833,138 +405,6 @@ function sessionDirFromContext(ctx: ExtensionCommandContext | ExtensionContext)
 		: undefined;
 }
 
-async function maybeReload(ctx: ExtensionCommandContext | ExtensionContext) {
-	if (!("reload" in ctx)) return;
-	if (
-		ctx.hasUI &&
-		(await ctx.ui.confirm(
-			"Reload Pi resources now?",
-			"This reloads extensions, skills, prompts, themes, and context files.",
-		))
-	) {
-		await ctx.reload();
-	}
-}
-
-async function readRemoteSnapshotForUpload(
-	client: S3Client,
-	config: SyncConfig,
-	latest: RemoteObject<LatestPointer>,
-	state: SyncState,
-) {
-	if (
-		latest.missing ||
-		!latest.value ||
-		(latest.value.snapshot === state.lastAppliedSnapshot && !syncPolicyChanged(state, config))
-	) {
-		return undefined;
-	}
-	return readRemoteSnapshotRaw(client, config);
-}
-
-async function snapshotForUpload(
-	client: S3Client,
-	config: SyncConfig,
-	local: Snapshot,
-	latest: RemoteObject<LatestPointer>,
-	remote?: Snapshot,
-	options: { ignoreUnreadableRemote?: boolean } = {},
-) {
-	if (latest.missing || !latest.value) return local;
-	let snapshot = remote;
-	if (!snapshot) {
-		try {
-			snapshot = await readRemoteSnapshotRaw(client, config);
-		} catch (error) {
-			if (options.ignoreUnreadableRemote) return local;
-			throw error;
-		}
-	}
-	return snapshot ? mergeRemotePreservedFiles(local, snapshot, config) : local;
-}
-
-async function uploadSnapshot(
-	client: S3Client,
-	config: SyncConfig,
-	snapshot: Snapshot,
-	latest: RemoteObject<LatestPointer>,
-	force: boolean,
-) {
-	const encoded = await encodeSnapshot(snapshot);
-	const pointer = pointerFor(config, snapshot, sha256(encoded));
-	await client.putBuffer(snapshotKey(config, snapshot.id), encoded, "application/gzip");
-	const current = await client.getJson<LatestPointer>(latestKey(config));
-	if (!force && remoteIdentity(current) !== remoteIdentity(latest)) {
-		throw new Error("Remote changed while pushing. Run /sync pull first, then retry.");
-	}
-	await client.putJson(latestKey(config), pointer);
-	const verified = await client.getJson<LatestPointer>(latestKey(config));
-	if (verified.value?.snapshot !== pointer.snapshot) {
-		throw new Error(
-			"Remote latest changed immediately after push. Run /sync status before continuing.",
-		);
-	}
-	return pointer;
-}
-
-async function readRemoteSnapshot(client: S3Client, config: SyncConfig) {
-	const snapshot = await readRemoteSnapshotRaw(client, config);
-	return snapshot ? filterSnapshotForConfigPolicy(snapshot, config) : undefined;
-}
-
-async function readRemoteSnapshotRaw(client: S3Client, config: SyncConfig) {
-	const latest = await client.getJson<LatestPointer>(latestKey(config));
-	if (latest.missing || !latest.value) return undefined;
-	const object = await client.getBuffer(snapshotKey(config, latest.value.snapshot));
-	if (!object.value)
-		throw new Error(`Remote latest points to missing snapshot: ${latest.value.snapshot}`);
-	if (sha256(object.value) !== latest.value.sha256)
-		throw new Error("Remote snapshot checksum mismatch.");
-	return decodeSnapshot(object.value);
-}
-
-async function encodeSnapshot(snapshot: Snapshot) {
-	return gzipAsync(Buffer.from(JSON.stringify(snapshot), "utf8"));
-}
-
-async function decodeSnapshot(buffer: Buffer): Promise<Snapshot> {
-	const decoded = await gunzipAsync(buffer);
-	const parsed = JSON.parse(decoded.toString("utf8")) as Snapshot;
-	if (parsed.version !== VERSION || !Array.isArray(parsed.files))
-		throw new Error("Unsupported snapshot format.");
-	return parsed;
-}
-
-export async function backupLocal(profile: string, options: SnapshotOptions = {}) {
-	const snapshot = await createSnapshot(profile, options);
-	const backupDirectory = path.join(stateDir(), "backups");
-	await fs.mkdir(backupDirectory, { recursive: true });
-	const backupPath = path.join(backupDirectory, `${snapshot.id}.json.gz`);
-	await fs.writeFile(backupPath, await encodeSnapshot(snapshot));
-	return backupPath;
-}
-
-async function updateHistorySafely(client: S3Client, config: SyncConfig, pointer: LatestPointer) {
-	try {
-		await updateHistory(client, config, pointer);
-		return undefined;
-	} catch (error) {
-		return `Remote snapshot is active, but history could not be updated: ${errorMessage(error)}. Run /sync doctor before relying on history.`;
-	}
-}
-
-async function updateHistory(client: S3Client, config: SyncConfig, pointer: LatestPointer) {
-	const object = await client.getJson<{ version: number; snapshots: LatestPointer[] }>(
-		historyKey(config),
-	);
-	const snapshots = object.value?.snapshots ?? [];
-	const next = [
-		...snapshots.filter((snapshot) => snapshot.snapshot !== pointer.snapshot),
-		pointer,
-	].slice(-100);
-	await client.putJson(historyKey(config), { version: VERSION, snapshots: next });
-}
-
 export { completeSyncArguments, parseOptions, splitArgs } from "./command.js";
 export {
 	isCloudflareR2Endpoint,
@@ -993,6 +433,7 @@ export {
 	preflightSnapshotApply,
 	protectSnapshotApplyPlan,
 } from "./snapshot-apply.js";
+export { backupLocal } from "./sync-operations.js";
 export {
 	canPullRemoteSessionsOnFirstSync,
 	canPullRemoteSettingsOnFirstSync,