@narumitw/pi-sync 0.49.15 → 0.50.0

package/src/sync/sync-error-guidance.ts

@@ -0,0 +1,53 @@
+import { errorMessage } from "./sync-errors.js";
+
+/** Add recovery advice without changing backend outcome semantics or printing error causes. */
+export function syncErrorGuidance(error: unknown): string {
+	const detail = errorMessage(error);
+	const message = detail.length > 1200 ? `${detail.slice(0, 1200)}… (details truncated)` : detail;
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	const status = (error as { status?: number } | undefined)?.status;
+	let next: string;
+	if (code === "ENOSPC") {
+		next = "Free disk space for the private pi-sync settings/state directory, then retry.";
+	} else if (code && ["EACCES", "EPERM", "EROFS"].includes(code)) {
+		next = "Check write access to the private pi-sync settings/state directory, then retry.";
+	} else if (code && ["EBUSY", "EIO", "EMFILE", "ENFILE"].includes(code)) {
+		next =
+			"Check local disk availability and other processes using the private settings file, then retry.";
+	} else if (/changed while|type changed|reopen/iu.test(message)) {
+		next = "Reopen the item in /sync and review its current settings before saving again.";
+	} else if (
+		status === 401 ||
+		status === 403 ||
+		/Permission denied|Authentication failed|HTTP (401|403)|failed \((401|403)\)/iu.test(message)
+	) {
+		next =
+			"Check the storage connection's credentials and remote permissions in /sync → More → Storage connections.";
+	} else if (status === 404 || /HTTP 404|failed \(404\)/iu.test(message)) {
+		next =
+			"Verify the connection address and setup's bucket, branch, or path with your provider; this response alone does not prove which resource is missing.";
+	} else if (status !== undefined && status >= 500) {
+		next = "Check your storage provider's service status, then retry Check setup before syncing.";
+	} else if (
+		/timed out|timeout|request failed|resolve host|Could not resolve|ENOTFOUND|ECONNREFUSED/iu.test(
+			message,
+		)
+	) {
+		next =
+			"Check the server address and network connection, then run /sync doctor for the affected setup.";
+	} else if (/strong ETag|If-Match|If-None-Match|precondition|conditional header/iu.test(message)) {
+		next =
+			"Ask your provider to check strong ETags and conditional writes, including proxy behavior, or choose compatible storage. Do not bypass these safety checks.";
+	} else if (/spawn git ENOENT/iu.test(message)) {
+		next = "Install Git 2.30 or newer and make sure Pi can find git on PATH, then retry.";
+	} else if (/response exceeds.*byte limit/iu.test(message)) {
+		next =
+			"Verify the storage endpoint; the server returned an unexpectedly large response. Check your provider's logs before retrying.";
+	} else if (/settings|config|already exists|duplicates|same normalized/iu.test(message)) {
+		next =
+			"Correct the named field or item in /sync. If the settings file is invalid, repair it before retrying; do not replace it with defaults.";
+	} else {
+		next = "Open /sync → More → Check setup and review the reported checks before retrying.";
+	}
+	return `${message}\n${next}`;
+}

package/src/sync/sync-inspection.ts

@@ -0,0 +1,51 @@
+import { createSyncBackend, type SyncBackendFactory } from "../backends/backend-factory.js";
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import { createSnapshot } from "../snapshot/snapshot.js";
+import type { SnapshotOptions } from "../snapshot/snapshot-types.js";
+import { readStateForConfig, syncStateFingerprint } from "../state/sync-state-store.js";
+import { throwIfAborted } from "./signals.js";
+import { inspectRemoteSelection } from "./sync-policy.js";
+import { hasLocalChanges, remoteChangedSinceState } from "./sync-state.js";
+
+/** Advisory baseline-relative observation, never an authorization to transfer files. */
+export async function inspectSync(
+	config: AnySyncConfig,
+	options: SnapshotOptions,
+	signal?: AbortSignal,
+	factory: SyncBackendFactory = createSyncBackend,
+) {
+	throwIfAborted(signal);
+	const backend = await factory(config);
+	throwIfAborted(signal);
+	const local = await createSnapshot(config.snapshotIdentity, { ...options, signal });
+	throwIfAborted(signal);
+	const state = await readStateForConfig(config);
+	throwIfAborted(signal);
+	const head = await backend.readHead(signal);
+	throwIfAborted(signal);
+	return {
+		head,
+		selectionState: head
+			? inspectRemoteSelection(config.include, { selection: head.selection, files: [] })
+			: undefined,
+		localFiles: local.files.length,
+		localChanged: hasLocalChanges(local, state, config),
+		remoteChanged: remoteChangedSinceState(head, state, config, (left, right) =>
+			backend.sameRevision(left, right),
+		),
+		firstSync: !state.lastAppliedSnapshot,
+		emptyInclude: config.include.length === 0,
+		stateIdentity: syncStateFingerprint(state),
+		destination: backend.destination,
+		capability: backend.capability,
+	};
+}
+
+export type SyncInspection = Awaited<ReturnType<typeof inspectSync>>;
+
+export interface StartupObservation {
+	setupName: string;
+	configIdentity: string;
+	checkedAt: string;
+	inspection: SyncInspection;
+}

package/src/sync/sync-loaders.ts

@@ -0,0 +1,54 @@
+type SetupSwitchModule = Pick<typeof import("./setup-switch.js"), "useSyncSetup">;
+type SnapshotModule = Pick<typeof import("../snapshot/snapshot.js"), "createSnapshot">;
+type SyncStateModule = Pick<typeof import("./sync-state.js"), "hasLocalChanges">;
+type SyncOperations = typeof import("./sync-operations.js");
+
+type SyncInspectionModule = Pick<typeof import("./sync-inspection.js"), "inspectSync">;
+
+export interface SyncDependencies {
+	loadSyncInspection(): Promise<SyncInspectionModule>;
+	loadSetupSwitch(): Promise<SetupSwitchModule>;
+	loadSnapshot(): Promise<SnapshotModule>;
+	loadSyncState(): Promise<SyncStateModule>;
+	loadSyncOperations(): Promise<SyncOperations>;
+}
+
+export interface SyncLoaders {
+	inspection(): Promise<SyncInspectionModule>;
+	setupSwitch(): Promise<SetupSwitchModule>;
+	snapshot(): Promise<SnapshotModule>;
+	syncState(): Promise<SyncStateModule>;
+	operations(): Promise<SyncOperations>;
+}
+
+export function createSyncLoaders(dependencies: Partial<SyncDependencies>): SyncLoaders {
+	const loaders: SyncLoaders = {
+		inspection: cachedModuleLoader(
+			dependencies.loadSyncInspection ?? (() => import("./sync-inspection.js")),
+		),
+		setupSwitch: cachedModuleLoader(
+			dependencies.loadSetupSwitch ?? (() => import("./setup-switch.js")),
+		),
+		snapshot: cachedModuleLoader(
+			dependencies.loadSnapshot ?? (() => import("../snapshot/snapshot.js")),
+		),
+		syncState: cachedModuleLoader(dependencies.loadSyncState ?? (() => import("./sync-state.js"))),
+		operations: cachedModuleLoader(
+			dependencies.loadSyncOperations ?? (() => import("./sync-operations.js")),
+		),
+	};
+	return loaders;
+}
+
+function cachedModuleLoader<Module>(load: () => Promise<Module>): () => Promise<Module> {
+	let pending: Promise<Module> | undefined;
+	return () => {
+		if (!pending) {
+			pending = load().catch((error) => {
+				pending = undefined;
+				throw error;
+			});
+		}
+		return pending;
+	};
+}

package/src/{sync-operations.ts → sync/sync-mutations.ts}

@@ -1,22 +1,21 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { createSyncBackend, type SyncBackendFactory } from "./backend-factory.js";
+import { createSyncBackend, type SyncBackendFactory } from "../backends/backend-factory.js";
 import {
-	loadConfig,
-	readStateForConfig,
-	sessionDirForApply,
-	stateDir,
-	syncConfigReviewFingerprint,
-	syncSessionsWarnings,
-	writeStateForConfig,
-} from "./config.js";
-import { inspectLock, isLockGuardHeld, isStaleLock, withLock } from "./lock.js";
+	expectedRemoteHead,
+	type PublishSnapshotResult,
+	type RemoteHead,
+	type SyncBackend,
+} from "../backends/sync-backend.js";
+import type { CommandOptions } from "../commands/command-types.js";
+import { loadConfig } from "../settings/config.js";
+import type { AnySyncConfig } from "../settings/settings-types.js";
 import {
-	formatRemoteSelectionStatus,
-	readSnapshotForHead,
-	requireCompatibleRemoteSelection,
-} from "./remote-snapshot.js";
+	sessionDirForApply,
+	sessionDirFromContext,
+	snapshotOptionsForContext,
+} from "../snapshot/session-paths.js";
 import {
 	createSnapshot,
 	filterSnapshotForConfigPolicy,
@@ -26,28 +25,28 @@ import {
 	sessionSnapshotPathFromAbsolute,
 	snapshotIncludesSessions,
 	snapshotWithoutSessions,
-} from "./snapshot.js";
-import { applySnapshot } from "./snapshot-apply.js";
-import { encodeSnapshot } from "./snapshot-codec.js";
-import {
-	expectedRemoteHead,
-	type PublishSnapshotResult,
-	type RemoteHead,
-	type SyncBackend,
-} from "./sync-backend.js";
-import { createSyncDecision } from "./sync-decision.js";
+} from "../snapshot/snapshot.js";
+import { applySnapshot } from "../snapshot/snapshot-apply.js";
+import { encodeSnapshot } from "../snapshot/snapshot-codec.js";
+import type { Snapshot, SnapshotOptions } from "../snapshot/snapshot-types.js";
+import { stateDir } from "../state/state-directory.js";
+import type { SyncState } from "../state/state-types.js";
+import { readStateForConfig, writeStateForConfig } from "../state/sync-state-store.js";
 import {
 	countPreservedRemoteFiles,
-	errorMessage,
-	formatDiff,
 	formatPullSummary,
 	formatPushSummary,
 	formatRollbackSummary,
-	formatSnapshotOnlyDiff,
-	publicationCapabilityDescription,
-	safeTerminalText,
-} from "./sync-format.js";
-import { inspectRemoteSelection, remoteSelectionMismatch } from "./sync-policy.js";
+} from "../ui/sync-format.js";
+import {
+	readRemoteSnapshot,
+	readSnapshotForHead,
+	requireCompatibleRemoteSelection,
+} from "./remote-snapshot.js";
+import { throwIfAborted } from "./signals.js";
+import { createSyncDecision } from "./sync-decision.js";
+import { errorMessage } from "./sync-errors.js";
+import { inspectRemoteSelection } from "./sync-policy.js";
 import {
 	canPullRemoteSessionsOnFirstSync,
 	canPullRemoteSettingsOnFirstSync,
@@ -61,17 +60,9 @@ import {
 	snapshotsMatch,
 	syncPolicyChanged,
 } from "./sync-state.js";
-import type {
-	AnySyncConfig,
-	CommandOptions,
-	Snapshot,
-	SnapshotOptions,
-	SyncState,
-} from "./types.js";
 
 const STATUS_KEY = "sync";
 const VERSION = 1;
-const DEFAULT_PROFILE = "default";
 const POST_LOCAL_COMMIT_TIMEOUT_MS = 30_000;
 
 export class PublicationStatePersistenceError extends Error {
@@ -109,190 +100,6 @@ interface PushInput {
 	backend?: SyncBackend;
 }
 
-function backendFor(config: AnySyncConfig, factory: SyncBackendFactory) {
-	return factory(config);
-}
-
-export async function status(
-	ctx: ExtensionCommandContext,
-	options: CommandOptions,
-	factory: SyncBackendFactory = createSyncBackend,
-) {
-	const config = await loadConfig(options.setup);
-	throwIfAborted(options.signal);
-	ctx.ui.setStatus(STATUS_KEY, `checking ${config.setupName}`);
-	const backend = await backendFor(config, factory);
-	const local = await createSnapshot(
-		config.snapshotIdentity,
-		snapshotOptionsForContext(ctx, config),
-	);
-	throwIfAborted(options.signal);
-	const state = await readStateForConfig(config);
-	throwIfAborted(options.signal);
-	const head = await backend.readHead(options.signal);
-	throwIfAborted(options.signal);
-	const selectionState = head
-		? inspectRemoteSelection(config.include, { selection: head.selection, files: [] })
-		: undefined;
-	const localChanged = hasLocalChanges(local, state, config);
-
-	const remoteText = head
-		? `remote: ${head.snapshotId} from ${head.machine} at ${head.createdAt}`
-		: "remote: empty";
-	const remoteChanged = remoteChangedSinceState(head, state, config, (left, right) =>
-		backend.sameRevision(left, right),
-	);
-	const warnings = syncSessionsWarnings(config);
-	ctx.ui.setStatus(STATUS_KEY, undefined);
-	ctx.ui.notify(
-		[
-			`sync setup: ${config.setupName}`,
-			`storage connection: ${config.connectionName}`,
-			`storage location: ${safeTerminalText(backend.destination)}`,
-			`publication safety: ${publicationCapabilityDescription(backend.capability)}`,
-			`included content: ${config.include.join(", ") || "none"}`,
-			`sessions: ${config.include.includes("sessions") ? "included" : "excluded"}`,
-			remoteText,
-			formatRemoteSelectionStatus(selectionState),
-			`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 || selectionState?.kind === "different" || warnings.length > 0
-			? "warning"
-			: "info",
-	);
-}
-
-export async function diff(
-	ctx: ExtensionCommandContext,
-	options: CommandOptions,
-	factory: SyncBackendFactory = createSyncBackend,
-) {
-	const config = await loadConfig(options.setup);
-	throwIfAborted(options.signal);
-	ctx.ui.setStatus(STATUS_KEY, `checking ${config.setupName}`);
-	const backend = await backendFor(config, factory);
-	const local = await createSnapshot(
-		config.snapshotIdentity,
-		snapshotOptionsForContext(ctx, config),
-	);
-	throwIfAborted(options.signal);
-	const { snapshot: remote, selectionState } = await readRemoteSnapshot(
-		backend,
-		config,
-		options.signal,
-		{ allowSelectionDifference: true },
-	);
-	throwIfAborted(options.signal);
-	ctx.ui.setStatus(STATUS_KEY, undefined);
-
-	const warnings = syncSessionsWarnings(config);
-	const header = [
-		`sync setup: ${config.setupName}`,
-		`storage connection: ${config.connectionName}`,
-		`storage location: ${safeTerminalText(backend.destination)}`,
-		`included content: ${config.include.join(", ") || "none"}`,
-		`sessions: ${config.include.includes("sessions") ? "included" : "excluded"}`,
-		formatRemoteSelectionStatus(selectionState),
-		...warnings,
-	].join("\n");
-	const level = warnings.length > 0 || selectionState?.kind === "different" ? "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);
-}
-
-export async function doctor(
-	ctx: ExtensionCommandContext,
-	options: CommandOptions,
-	factory: SyncBackendFactory = createSyncBackend,
-) {
-	const messages: string[] = [];
-	let level: "info" | "warning" = "info";
-	let snapshotOptions: SnapshotOptions = {};
-	let profile = DEFAULT_PROFILE;
-	let backend: SyncBackend | undefined;
-	let backendSummary: string[] = [];
-
-	try {
-		const config = await loadConfig(options.setup);
-		throwIfAborted(options.signal);
-		backend = await backendFor(config, factory);
-		profile = config.snapshotIdentity;
-		snapshotOptions = snapshotOptionsForContext(ctx, config);
-		messages.push(
-			`config: ok (sync setup ${config.setupName})`,
-			`included content: ${config.include.join(", ") || "none"}`,
-			`sessions: ${config.include.includes("sessions") ? "included" : "excluded"}`,
-		);
-		backendSummary = [
-			`storage location: ${safeTerminalText(backend.destination)}`,
-			`publication safety: ${publicationCapabilityDescription(backend.capability)}`,
-		];
-		const warnings = syncSessionsWarnings(config);
-		if (warnings.length > 0) {
-			level = "warning";
-			messages.push(...warnings);
-		}
-	} catch (error) {
-		throwIfAborted(options.signal);
-		level = "warning";
-		messages.push(`config: ${errorMessage(error)}`);
-	}
-
-	const local = await createSnapshot(profile, snapshotOptions);
-	throwIfAborted(options.signal);
-	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();
-	throwIfAborted(options.signal);
-	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()) {
-		throwIfAborted(options.signal);
-		level = "warning";
-		messages.push("lock: guard active while metadata is missing or still being initialized");
-	} else {
-		messages.push("lock: free");
-	}
-
-	if (backend) {
-		messages.push(...backendSummary);
-		const diagnostics = await backend.diagnose(options.signal);
-		throwIfAborted(options.signal);
-		for (const diagnostic of diagnostics) {
-			messages.push(diagnostic.message);
-			if (diagnostic.level !== "info") level = "warning";
-		}
-	}
-	ctx.ui.notify(messages.join("\n"), level);
-}
-
 export async function push(
 	ctx: ExtensionCommandContext | ExtensionContext,
 	options: CommandOptions,
@@ -302,7 +109,7 @@ export async function push(
 	const config = input?.config ?? (await loadConfig(options.setup));
 	throwIfAborted(options.signal);
 	ctx.ui.setStatus(STATUS_KEY, `pushing ${config.setupName}`);
-	const backend = input?.backend ?? (await backendFor(config, factory));
+	const backend = input?.backend ?? (await factory(config));
 	const state = input?.state ?? (await readStateForConfig(config));
 	throwIfAborted(options.signal);
 	const local =
@@ -448,7 +255,7 @@ export async function pull(
 	const config = await loadConfig(options.setup);
 	throwIfAborted(options.signal);
 	ctx.ui.setStatus(STATUS_KEY, `pulling ${config.setupName}`);
-	const backend = await backendFor(config, factory);
+	const backend = await factory(config);
 	const state = await readStateForConfig(config);
 	throwIfAborted(options.signal);
 	const local = await createSnapshot(
@@ -553,7 +360,7 @@ export async function syncBoth(
 ) {
 	const config = await loadConfig(options.setup);
 	throwIfAborted(options.signal);
-	const backend = await backendFor(config, factory);
+	const backend = await factory(config);
 	const state = await readStateForConfig(config);
 	throwIfAborted(options.signal);
 	const local = await createSnapshot(
@@ -671,52 +478,6 @@ export async function syncBoth(
 	if (!options.silent) ctx.ui.notify("pi-sync is already up to date.", "info");
 }
 
-export async function history(
-	ctx: ExtensionCommandContext,
-	options: CommandOptions,
-	factory: SyncBackendFactory = createSyncBackend,
-) {
-	const config = await loadConfig(options.setup);
-	throwIfAborted(options.signal);
-	const backend = await backendFor(config, factory);
-	const snapshots = (await backend.listHistory(options.signal)).slice(-20).reverse();
-	throwIfAborted(options.signal);
-	if (snapshots.length === 0) {
-		ctx.ui.notify("No remote pi-sync history found.", "info");
-		return;
-	}
-
-	const currentSnapshot = snapshots[0]?.snapshotId;
-	if (ctx.mode === "tui") {
-		const labels = snapshots.map(
-			(item, index) =>
-				`${index + 1}. ${item.createdAt} · ${safeTerminalText(item.machine)} · ${item.snapshotId}${item.snapshotId === currentSnapshot ? " (current)" : ""}${item.syncSessions ? " · sessions" : ""}`,
-		);
-		const selected = await ctx.ui.select(
-			`History for sync setup “${safeTerminalText(config.setupName)}”\n\nChoose a snapshot to preview rollback.`,
-			[...labels, "Back"],
-		);
-		if (!selected || selected === "Back") return;
-		throwIfAborted(options.signal);
-		const index = labels.indexOf(selected);
-		const snapshot = snapshots[index];
-		if (!snapshot) return;
-		await withLock("rollback", () =>
-			rollback(ctx, { ...options, args: [snapshot.snapshotRef], yes: false }, factory, {
-				backendIdentity: backend.identity,
-				setup: config.setupName,
-			}),
-		);
-		return;
-	}
-	ctx.ui.notify(
-		snapshots
-			.map((item) => `${item.snapshotRef} ${item.createdAt} ${safeTerminalText(item.machine)}`)
-			.join("\n"),
-		"info",
-	);
-}
-
 export async function rollback(
 	ctx: ExtensionCommandContext,
 	options: CommandOptions,
@@ -728,7 +489,7 @@ export async function rollback(
 
 	const config = await loadConfig(options.setup);
 	throwIfAborted(options.signal);
-	const backend = await backendFor(config, factory);
+	const backend = await factory(config);
 	if (
 		expectedSelection &&
 		(backend.identity !== expectedSelection.backendIdentity ||
@@ -837,30 +598,6 @@ function protectedSessionPaths(ctx: ExtensionCommandContext | ExtensionContext)
 	return snapshotPath ? new Set([snapshotPath]) : new Set<string>();
 }
 
-function snapshotOptionsForContext(
-	ctx: ExtensionCommandContext | ExtensionContext,
-	config: AnySyncConfig,
-): SnapshotOptions {
-	return {
-		include: config.include,
-		sessionDir: sessionDirFromContext(ctx),
-	};
-}
-
-function sessionDirFromContext(ctx: ExtensionCommandContext | ExtensionContext) {
-	const manager = ctx.sessionManager as typeof ctx.sessionManager & {
-		usesDefaultSessionDir?: () => boolean;
-	};
-	const usesDefaultSessionDir = manager.usesDefaultSessionDir;
-	if (typeof usesDefaultSessionDir === "function" && usesDefaultSessionDir.call(manager)) {
-		return undefined;
-	}
-	const getSessionDir = manager.getSessionDir;
-	return typeof getSessionDir === "function"
-		? (getSessionDir.call(manager) as string | undefined)
-		: undefined;
-}
-
 async function maybeReload(ctx: ExtensionCommandContext | ExtensionContext, signal?: AbortSignal) {
 	if (signal?.aborted || !("reload" in ctx)) return;
 	if (
@@ -915,27 +652,6 @@ async function snapshotForUpload(
 	return mergeRemotePreservedFiles(local, snapshot, config);
 }
 
-async function readRemoteSnapshot(
-	backend: SyncBackend,
-	config: AnySyncConfig,
-	signal?: AbortSignal,
-	options: { allowSelectionDifference?: boolean } = {},
-) {
-	const head = await backend.readHead(signal);
-	if (!head) return { head: undefined, snapshot: undefined, selectionState: undefined };
-	const snapshot = await readSnapshotForHead(backend, head, signal);
-	const selectionState = inspectRemoteSelection(config.include, snapshot);
-	if (!options.allowSelectionDifference && selectionState.kind === "different") {
-		const configIdentity = syncConfigReviewFingerprint(config);
-		throw remoteSelectionMismatch(config, selectionState.include, configIdentity);
-	}
-	return {
-		head,
-		snapshot: filterSnapshotForConfigPolicy(snapshot, config),
-		selectionState,
-	};
-}
-
 async function confirmPush(
 	ctx: ExtensionCommandContext | ExtensionContext,
 	options: CommandOptions,
@@ -967,13 +683,6 @@ async function confirmPush(
 	return false;
 }
 
-function throwIfAborted(signal?: AbortSignal) {
-	if (!signal?.aborted) return;
-	throw signal.reason instanceof Error
-		? signal.reason
-		: new DOMException("The operation was aborted", "AbortError");
-}
-
 function sameRemoteHead(
 	backend: SyncBackend,
 	left: RemoteHead | undefined,

package/src/sync/sync-operations.ts

@@ -0,0 +1,12 @@
+// First-use operation surface for the cached loader; implementations stay lazy.
+
+export {
+	backupLocal,
+	PublicationStatePersistenceError,
+	pull,
+	push,
+	RollbackPublicationError,
+	rollback,
+	syncBoth,
+} from "./sync-mutations.js";
+export { diff, doctor, history, status } from "./sync-queries.js";

package/src/{sync-policy.ts → sync/sync-policy.ts}

@@ -1,6 +1,6 @@
 import path from "node:path";
-import { isDeniedPath, toPosix } from "./paths.js";
-import type { Snapshot, SnapshotSelection } from "./types.js";
+import { isDeniedPath, toPosix } from "../paths.js";
+import type { Snapshot, SnapshotSelection } from "../snapshot/snapshot-types.js";
 
 export const BUILT_IN_SYNC_ROOTS = [
 	"settings.json",