@narumitw/pi-sync 0.49.15 → 0.50.1

package/src/commands/command-handler.ts

@@ -0,0 +1,201 @@
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../settings/config.js";
+import { readStateForConfig, syncStateFingerprint } from "../state/sync-state-store.js";
+import { combineSignals } from "../sync/signals.js";
+import { errorMessage } from "../sync/sync-errors.js";
+import type { SyncLoaders } from "../sync/sync-loaders.js";
+import { formatRemoteSelectionMismatch } from "../sync/sync-policy.js";
+import type { RunRouteResult } from "../ui/cancellable-operation.js";
+import {
+	observationMatchesConfig,
+	type SyncAttentionController,
+	type SyncAttentionOrigin,
+	syncAttentionMatchesConfig,
+} from "../ui/sync-attention.js";
+import { parseOptions, splitArgs } from "./command.js";
+import { executeCommand, executeRecoveryCommand } from "./command-execution.js";
+
+const STATUS_KEY = "sync";
+
+export async function handleCommand(
+	rawArgs: string,
+	ctx: ExtensionCommandContext,
+	sessionSignal: AbortSignal,
+	loaders: SyncLoaders,
+	attention: SyncAttentionController,
+) {
+	await reconcileObservation(attention, sessionSignal);
+	if (sessionSignal.aborted) return;
+	const run = (route: string, signal?: AbortSignal, onCommit?: () => void, target?: string) =>
+		executeCommand(
+			route,
+			ctx,
+			combineSignals(sessionSignal, signal),
+			loaders,
+			observationCommitCallback(attention, sessionSignal, onCommit),
+			target,
+		);
+	if (!rawArgs.trim()) {
+		try {
+			const { showSyncManager } = await import("../ui/manager-ui.js");
+			if (sessionSignal.aborted) return;
+			await showSyncManager(ctx, run, sessionSignal, {
+				getAttention: () => attention.current(),
+				getObservation: () => attention.observation(),
+				onObservationInvalidated: () => attention.clearObservation(),
+				onSelectionResolved: (expected) => {
+					if (attention.current() === expected) attention.clear(ctx);
+				},
+			});
+		} catch (error) {
+			if (sessionSignal.aborted) return;
+			ctx.ui.setStatus(STATUS_KEY, undefined);
+			ctx.ui.notify(errorMessage(error), "error");
+		}
+		await reconcileObservation(attention, sessionSignal);
+		if (!sessionSignal.aborted) await attention.publish(ctx, sessionSignal);
+		return;
+	}
+	const result = await run(rawArgs);
+	if (result.kind === "decision-required") {
+		ctx.ui.notify(result.decision.directMessage, "error");
+	} else if (result.kind === "remote-selection-required") {
+		const origin = directSelectionOrigin(rawArgs);
+		if (origin) attention.set(result.decision, origin);
+		const deterministic = splitArgs(rawArgs).some((arg) => arg === "--yes" || arg === "-y");
+		if (origin && ctx.mode === "tui" && !deterministic) {
+			await resolveSelectionAttention(ctx, attention, sessionSignal, loaders);
+		} else {
+			ctx.ui.notify(
+				formatRemoteSelectionMismatch(
+					result.decision.setupName,
+					result.decision.localInclude,
+					result.decision.remoteInclude,
+				),
+				"error",
+			);
+		}
+	}
+	await clearAttentionAfterCompletedOperation(rawArgs, result, ctx, attention, sessionSignal);
+	await reconcileSelectionAttention(ctx, attention, sessionSignal);
+	await reconcileObservation(attention, sessionSignal);
+	if (!sessionSignal.aborted) await attention.publish(ctx, sessionSignal);
+}
+
+function observationCommitCallback(
+	attention: SyncAttentionController,
+	sessionSignal: AbortSignal,
+	onCommit?: () => void,
+) {
+	const observed = attention.observation();
+	return () => {
+		// Opening or cancelling a review changes nothing. A commit may change data
+		// even if later publication/baseline cleanup fails; never restore old hints.
+		if (!sessionSignal.aborted && attention.observation() === observed)
+			attention.clearObservation();
+		onCommit?.();
+	};
+}
+
+async function reconcileObservation(attention: SyncAttentionController, signal: AbortSignal) {
+	const observed = attention.observation();
+	if (!observed || signal.aborted) return;
+	try {
+		const config = await loadConfig();
+		if (signal.aborted || attention.observation() !== observed) return;
+		if (!observationMatchesConfig(observed, config)) {
+			attention.clearObservation();
+			return;
+		}
+		const state = await readStateForConfig(config);
+		if (signal.aborted || attention.observation() !== observed) return;
+		if (syncStateFingerprint(state) !== observed.inspection.stateIdentity)
+			attention.clearObservation();
+	} catch {
+		if (!signal.aborted && attention.observation() === observed) attention.clearObservation();
+	}
+}
+
+async function clearAttentionAfterCompletedOperation(
+	rawArgs: string,
+	result: RunRouteResult,
+	ctx: ExtensionContext,
+	attention: SyncAttentionController,
+	signal: AbortSignal,
+) {
+	if (result.kind !== "completed" || result.outcome === "cancelled" || signal.aborted) return;
+	const [command, ...rest] = splitArgs(rawArgs);
+	if (command !== "sync" && command !== "pull" && command !== "push") return;
+	const current = attention.current();
+	if (!current) return;
+	try {
+		const options = parseOptions(rest);
+		const setupName = options.setup ?? (await loadConfig()).setupName;
+		if (signal.aborted || attention.current() !== current) return;
+		if (current.decision.setupName === setupName) attention.clear(ctx);
+	} catch {
+		// Attention reconciliation below owns malformed or concurrently changed settings.
+	}
+}
+
+async function reconcileSelectionAttention(
+	ctx: ExtensionContext,
+	attention: SyncAttentionController,
+	signal: AbortSignal,
+) {
+	const current = attention.current();
+	if (!current || signal.aborted) return;
+	try {
+		const config = await loadConfig(current.decision.setupName);
+		if (signal.aborted || attention.current() !== current) return;
+		if (!syncAttentionMatchesConfig(current, config)) attention.clear(ctx);
+	} catch {
+		if (!signal.aborted && attention.current() === current) attention.clear(ctx);
+	}
+}
+
+function directSelectionOrigin(rawArgs: string): SyncAttentionOrigin | undefined {
+	const command = splitArgs(rawArgs)[0];
+	return command === "sync" || command === "pull" || command === "push" ? command : undefined;
+}
+
+export async function resolveSelectionAttention(
+	ctx: ExtensionContext,
+	attention: SyncAttentionController,
+	signal: AbortSignal,
+	loaders: SyncLoaders,
+	options: {
+		cancelLabel?: string;
+		withStateAccess?: <T>(task: () => Promise<T>) => Promise<T>;
+	} = {},
+) {
+	const current = attention.current();
+	if (!current || signal.aborted) return;
+	const { dispatchManagerResult } = await import("../ui/manager-result-dispatcher.js");
+	if (signal.aborted || attention.current() !== current) return;
+	await dispatchManagerResult(
+		ctx,
+		{ kind: "remote-selection-required", decision: current.decision },
+		current.origin,
+		(route, actionSignal, onCommit, target) => {
+			const execute = () =>
+				executeRecoveryCommand(
+					route,
+					ctx,
+					combineSignals(signal, actionSignal),
+					loaders,
+					observationCommitCallback(attention, signal, onCommit),
+					target,
+				);
+			return options.withStateAccess ? options.withStateAccess(execute) : execute();
+		},
+		signal,
+		{
+			cancelLabel: options.cancelLabel,
+			withStateAccess: options.withStateAccess,
+			onSelectionResolved: () => {
+				if (attention.current() === current) attention.clear(ctx);
+			},
+		},
+	);
+}

package/src/commands/command-types.ts

@@ -0,0 +1,18 @@
+export interface CommandOptions {
+	yes: boolean;
+	force: boolean;
+	stale: boolean;
+	silent: boolean;
+	reload: boolean;
+	auto: boolean;
+	setup?: string;
+	signal?: AbortSignal;
+	onCommit?: () => void;
+	args: string[];
+}
+
+export interface CommandArgumentCompletion {
+	value: string;
+	label: string;
+	description?: string;
+}

package/src/{command.ts → commands/command.ts}

@@ -1,5 +1,5 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import type { CommandArgumentCompletion, CommandOptions } from "./types.js";
+import type { CommandArgumentCompletion, CommandOptions } from "./command-types.js";
 
 const YES_FLAG_COMPLETIONS: readonly CommandArgumentCompletion[] = [
 	{ value: "--yes", label: "--yes", description: "Skip confirmation prompts" },
@@ -235,6 +235,7 @@ export function usage() {
 	return [
 		"Usage: /sync <command>",
 		`Commands: ${commands}`,
+		"Automatic sync: background startup checks only; use /sync to review and transfer. At shutdown, selected content is pushed automatically only when sessions are included. Startup checks run in TUI/RPC, not print/JSON.",
 		"Settings: use /sync init or edit storage connections and sync setups in ~/.pi/agent/pi-sync.json (or the configured Pi agent directory). Version 1 and version 2 settings are unsupported and are never rewritten.",
 	].join("\n");
 }

package/src/commands/setup-completions.ts

@@ -0,0 +1,6 @@
+import { configuredSyncSetupNames } from "../settings/settings-store.js";
+import { setSyncSetupCompletions } from "./command.js";
+
+export async function refreshTargetCompletions() {
+	setSyncSetupCompletions(await configuredSyncSetupNames());
+}

package/src/settings/config.ts

@@ -0,0 +1,238 @@
+import { createHash } from "node:crypto";
+import { backendIdentityCoordinates } from "../backends/backend-identity.js";
+import {
+	normalizeGitBranch,
+	normalizeGitDirectory,
+	normalizeGitRemote,
+} from "../backends/git/git-config.js";
+import { normalizeWebDavPath, normalizeWebDavUrl } from "../backends/webdav/webdav-config.js";
+import { normalizeSyncInclude } from "../sync/sync-policy.js";
+import { localConfigPath, readActiveLocalConfigDocumentForRepair } from "./config-file.js";
+import { requireSettings } from "./settings-store.js";
+import type {
+	AnySyncConfig,
+	OnSwitchAction,
+	PartialConfig,
+	PiSyncSettingsV3,
+	StorageConnectionSettings,
+	SyncSetupSettings,
+} from "./settings-types.js";
+import {
+	DEFAULT_ON_SWITCH,
+	isCloudflareR2Endpoint,
+	normalizeS3Bucket,
+	normalizeS3Endpoint,
+	normalizeStoragePath,
+	optionalString,
+	ownObject,
+	requiredString,
+	validateConfigName,
+	validateSettingsDocument,
+} from "./settings-validation.js";
+
+export async function loadConfig(setupName?: string): Promise<AnySyncConfig> {
+	return configFromSettings(await requireSettings(), setupName);
+}
+
+/** A background freshness read must never trigger legacy-file publication. */
+export async function loadConfigForCheck(): Promise<AnySyncConfig> {
+	const document = await readActiveLocalConfigDocumentForRepair();
+	if (!document) throw new Error(`Missing pi-sync settings: ${localConfigPath()}`);
+	validateSettingsDocument(document.parsed);
+	return configFromSettings(document.parsed as PiSyncSettingsV3);
+}
+
+function configFromSettings(settings: PiSyncSettingsV3, setupName?: string): AnySyncConfig {
+	const selectedName = setupName ?? settings.activeSyncSetup;
+	if (!selectedName) throw new Error("No sync setups are configured.");
+	validateConfigName(selectedName, "sync setup");
+	const setup = ownObject<SyncSetupSettings>(settings.syncSetups, selectedName);
+	if (!setup)
+		throw new Error(`Invalid pi-sync settings: sync setup “${selectedName}” was not found.`);
+	const connectionName = setup.storage.connection;
+	const connection = ownObject<StorageConnectionSettings>(
+		settings.storageConnections,
+		connectionName,
+	);
+	if (!connection) {
+		throw new Error(
+			`Invalid pi-sync settings: sync setup “${selectedName}” references missing storage connection “${connectionName}”.`,
+		);
+	}
+	return resolveSyncConfig(
+		selectedName,
+		setup,
+		connectionName,
+		connection,
+		settings.onSwitch,
+		settings.skipSecretScan ?? false,
+	);
+}
+
+export type SyncSetupStorageReview = Pick<
+	PartialConfig,
+	"connectionName" | "storageKind" | "storagePath" | "bucket" | "branch"
+>;
+
+/** A validated setup-facing projection used by manager and settings UI. */
+export async function loadPartialConfig(setupName?: string): Promise<PartialConfig> {
+	const config = await loadConfig(setupName);
+	return {
+		setupName: config.setupName,
+		...storageReviewFromConfig(config),
+		include: [...config.include],
+		automatic: config.automatic,
+		onSwitch: config.onSwitch,
+	};
+}
+
+export function syncSetupStorageReview(
+	setupName: string,
+	setup: SyncSetupSettings,
+	connectionName: string,
+	connection: StorageConnectionSettings,
+): SyncSetupStorageReview {
+	return storageReviewFromConfig(
+		resolveSyncConfig(setupName, setup, connectionName, connection, DEFAULT_ON_SWITCH, false),
+	);
+}
+
+export function syncSetupReviewIdentity(
+	setupName: string,
+	setup: SyncSetupSettings,
+	connectionName: string,
+	connection: StorageConnectionSettings,
+) {
+	return syncConfigReviewIdentity(
+		resolveSyncConfig(setupName, setup, connectionName, connection, DEFAULT_ON_SWITCH, false),
+	);
+}
+
+export function syncConfigReviewIdentity(config: AnySyncConfig) {
+	return JSON.stringify([
+		config.setupName,
+		config.connectionName,
+		backendIdentityCoordinates(config),
+		config.include,
+		config.automatic,
+	]);
+}
+
+export function syncConfigReviewFingerprint(config: AnySyncConfig) {
+	return createHash("sha256").update(syncConfigReviewIdentity(config)).digest("hex");
+}
+
+/** Internal freshness token, including credentials; never display or persist it. */
+export function syncCheckConfigFingerprint(config: AnySyncConfig) {
+	return createHash("sha256").update(JSON.stringify(config)).digest("hex");
+}
+
+function storageReviewFromConfig(config: AnySyncConfig): SyncSetupStorageReview {
+	return {
+		connectionName: config.connectionName,
+		storageKind: config.backend.type,
+		storagePath: config.storagePath,
+		...(config.backend.type === "s3"
+			? { bucket: config.backend.destination.bucket }
+			: config.backend.type === "git"
+				? { branch: config.backend.destination.branch }
+				: {}),
+	};
+}
+
+function resolveSyncConfig(
+	setupName: string,
+	setup: SyncSetupSettings,
+	connectionName: string,
+	connection: StorageConnectionSettings,
+	onSwitch: OnSwitchAction,
+	skipSecretScan: boolean,
+): AnySyncConfig {
+	const storagePath = normalizeStoragePath(setup.storage.path);
+	const namespace =
+		storagePath === "./" ? "root" : storagePath.slice(storagePath.lastIndexOf("/") + 1);
+	const include = normalizeSyncInclude(setup.sync.include);
+	const common = {
+		setupName,
+		connectionName,
+		storagePath,
+		snapshotIdentity: namespace,
+		include,
+		automatic: setup.sync.automatic,
+		onSwitch,
+		skipSecretScan,
+	};
+	if (connection.type === "git") {
+		return {
+			...common,
+			backend: {
+				type: "git",
+				profile: { kind: "git", remote: normalizeGitRemote(connection.remote) as string },
+				destination: {
+					branch: normalizeGitBranch(setup.storage.branch),
+					directory: normalizeGitDirectory(storagePath),
+					namespace,
+				},
+			},
+		};
+	}
+	if (connection.type === "webdav") {
+		return {
+			...common,
+			backend: {
+				type: "webdav",
+				profile: {
+					kind: "webdav",
+					url: normalizeWebDavUrl(connection.url) as string,
+					username: connection.credentials.username,
+					password: connection.credentials.password,
+				},
+				destination: { path: normalizeWebDavPath(storagePath), namespace },
+			},
+		};
+	}
+	return {
+		...common,
+		backend: {
+			type: "s3",
+			profile: {
+				kind: isCloudflareR2Endpoint(connection.endpoint) ? "r2" : "s3-compatible",
+				endpoint: normalizeS3Endpoint(connection.endpoint),
+				region: requiredString(connection.region, "S3 region"),
+				accessKeyId: connection.credentials.accessKeyId,
+				secretAccessKey: connection.credentials.secretAccessKey,
+				sessionToken: optionalString(connection.credentials.sessionToken, "S3 session token"),
+			},
+			destination: {
+				bucket: normalizeS3Bucket(setup.storage.bucket),
+				prefix: storagePath,
+				namespace,
+			},
+		},
+	};
+}
+
+export function sessionTokenWarnings(config: { endpoint?: string; sessionToken?: string }) {
+	if (!isCloudflareR2Endpoint(config.endpoint) || !config.sessionToken) return [];
+	return [
+		"session token: configured for Cloudflare R2; if R2 rejects X-Amz-Security-Token, pi-sync retries once without it. R2 static access keys usually do not need a session token.",
+	];
+}
+
+export function syncSessionsWarnings(config: { include: readonly string[] }) {
+	if (!config.include.includes("sessions")) return [];
+	return [
+		"sessions: included; Pi session JSONL can contain prompts, tool output, file paths, images, and secrets. Sync sessions only to storage you trust.",
+	];
+}
+
+export function isEnabled(value: boolean | string | undefined, defaultValue: boolean) {
+	if (value === undefined) return defaultValue;
+	if (typeof value === "boolean") return value;
+	return !["0", "false", "no", "off"].includes(value.trim().toLowerCase());
+}
+
+export function isExplicitlyEnabled(value: boolean | string | undefined) {
+	if (typeof value === "boolean") return value;
+	return ["1", "true", "yes", "on"].includes(value?.trim().toLowerCase() ?? "");
+}

package/src/{settings-management.ts → settings/settings-management.ts}

@@ -1,13 +1,14 @@
-import {
-	effectiveSyncSetupRemoteIdentity,
-	localConfigPath,
-	normalizeSyncInclude,
-	type SyncSetupStorageReview,
-	syncSetupStorageReview,
-	updateLocalConfig,
-	validateConfigName,
-} from "./config.js";
-import type { PiSyncSettingsV3, StorageConnectionSettings, SyncSetupSettings } from "./types.js";
+import { isDeepStrictEqual } from "node:util";
+import { normalizeSyncInclude } from "../sync/sync-policy.js";
+import { type SyncSetupStorageReview, syncSetupStorageReview } from "./config.js";
+import { localConfigPath } from "./config-file.js";
+import { updateLocalConfig } from "./settings-store.js";
+import type {
+	PiSyncSettingsV3,
+	StorageConnectionSettings,
+	SyncSetupSettings,
+} from "./settings-types.js";
+import { effectiveSyncSetupRemoteIdentity, validateConfigName } from "./settings-validation.js";
 
 export class SyncSetupReviewChangedError extends Error {
 	constructor(message: string) {
@@ -40,13 +41,12 @@ export async function saveNewV3Settings(
 			},
 		},
 	};
-	await updateLocalConfig((current) => {
+	return updateLocalConfig((current) => {
 		if (Object.keys(current.storageConnections).length || Object.keys(current.syncSetups).length) {
 			throw new Error(`Settings already exist: ${localConfigPath()}`);
 		}
-		return settings;
+		return { ...current, ...settings };
 	}, signal);
-	return settings;
 }
 
 export async function addStorageConnection(
@@ -92,7 +92,12 @@ export async function updateStorageConnection(
 	}, signal);
 }
 
-export async function addSyncSetup(name: string, setup: SyncSetupSettings, signal?: AbortSignal) {
+export async function addSyncSetup(
+	name: string,
+	setup: SyncSetupSettings,
+	signal?: AbortSignal,
+	expectedConnection?: StorageConnectionSettings,
+) {
 	validateConfigName(name, "sync setup");
 	await updateSettings((settings) => {
 		if (Object.hasOwn(settings.syncSetups, name))
@@ -100,6 +105,14 @@ export async function addSyncSetup(name: string, setup: SyncSetupSettings, signa
 		if (!Object.hasOwn(settings.storageConnections, setup.storage.connection)) {
 			throw new Error(`Storage connection not found: ${setup.storage.connection}`);
 		}
+		if (
+			expectedConnection &&
+			!isDeepStrictEqual(settings.storageConnections[setup.storage.connection], expectedConnection)
+		) {
+			throw new SyncSetupReviewChangedError(
+				"Storage connection changed while the setup review was open; reopen it.",
+			);
+		}
 		const nextSetups = { ...settings.syncSetups, [name]: structuredClone(setup) };
 		assertUniqueLocations(nextSetups, settings.storageConnections);
 		return {
@@ -116,6 +129,7 @@ export async function updateSyncSetup(
 	options: {
 		expectedStorage?: SyncSetupStorageReview;
 		expectedInclude?: readonly string[];
+		expectedConnection?: StorageConnectionSettings;
 		signal?: AbortSignal;
 	} = {},
 ) {
@@ -146,6 +160,17 @@ export async function updateSyncSetup(
 				);
 			}
 		}
+		if (
+			options.expectedConnection &&
+			!isDeepStrictEqual(
+				settings.storageConnections[setup.storage.connection],
+				options.expectedConnection,
+			)
+		) {
+			throw new SyncSetupReviewChangedError(
+				"Storage connection changed while the setup review was open; reopen it.",
+			);
+		}
 		const nextSetup = update(structuredClone(setup));
 		if (!Object.hasOwn(settings.storageConnections, nextSetup.storage.connection)) {
 			throw new Error(`Storage connection not found: ${nextSetup.storage.connection}`);

package/src/settings/settings-store.ts

@@ -0,0 +1,109 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+	localConfigPath,
+	readMigratingLocalConfigDocument,
+	updateLocalConfigDocument,
+} from "./config-file.js";
+import type { OnSwitchAction, PiSyncSettingsV3 } from "./settings-types.js";
+import { DEFAULT_ON_SWITCH, validateSettingsDocument } from "./settings-validation.js";
+
+let configUpdateQueue: Promise<void> = Promise.resolve();
+
+export async function requireSettings() {
+	const settings = await readLocalConfigObject();
+	if (!settings) {
+		throw new Error(
+			`Missing pi-sync settings. Open /sync and choose Set up sync, or create ${localConfigPath()}.`,
+		);
+	}
+	return settings;
+}
+
+export async function configuredSyncSetupNames() {
+	const settings = await readLocalConfigObject();
+	return settings
+		? Object.keys(settings.syncSetups).sort((left, right) => left.localeCompare(right))
+		: [];
+}
+
+export async function loadOnSwitch(): Promise<OnSwitchAction> {
+	return (await requireSettings()).onSwitch;
+}
+
+export function localConfigTemplate(): PiSyncSettingsV3 {
+	return {
+		version: 3,
+		onSwitch: DEFAULT_ON_SWITCH,
+		skipSecretScan: false,
+		storageConnections: {},
+		syncSetups: {},
+	};
+}
+
+export async function readLocalConfigDocument() {
+	const document = await readMigratingLocalConfigDocument((settings) => {
+		validateSettingsDocument(settings);
+	});
+	if (document) validateSettingsDocument(document.parsed);
+	return document;
+}
+
+export async function readLocalConfigObject(): Promise<PiSyncSettingsV3 | undefined> {
+	return (await readLocalConfigDocument())?.parsed as PiSyncSettingsV3 | undefined;
+}
+
+export function updateLocalConfig(
+	update: (current: PiSyncSettingsV3) => PiSyncSettingsV3,
+	signal?: AbortSignal,
+) {
+	const operation = configUpdateQueue.then(() => {
+		signal?.throwIfAborted();
+		return performLocalConfigUpdate(update, signal);
+	});
+	configUpdateQueue = operation.then(
+		() => undefined,
+		() => undefined,
+	);
+	return operation;
+}
+
+async function performLocalConfigUpdate(
+	update: (current: PiSyncSettingsV3) => PiSyncSettingsV3,
+	signal?: AbortSignal,
+) {
+	return updateLocalConfigDocument(localConfigTemplate(), update, validateSettingsDocument, signal);
+}
+
+export async function writeLocalConfigObject(value: PiSyncSettingsV3 | Record<string, unknown>) {
+	validateSettingsDocument(value as Record<string, unknown>);
+	const configPath = localConfigPath();
+	await fs.mkdir(path.dirname(configPath), { recursive: true });
+	try {
+		const stat = await fs.lstat(configPath);
+		if (stat.isSymbolicLink())
+			throw new Error(`Refusing to overwrite symlinked pi-sync settings: ${configPath}`);
+		if (!stat.isFile()) throw new Error(`pi-sync settings are not a regular file: ${configPath}`);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+	const temporaryPath = path.join(
+		path.dirname(configPath),
+		`.${path.basename(configPath)}.${process.pid}.${randomUUID()}.tmp`,
+	);
+	let handle: fs.FileHandle | undefined;
+	try {
+		handle = await fs.open(temporaryPath, "wx", 0o600);
+		await handle.writeFile(`${JSON.stringify(value, null, "\t")}\n`, "utf8");
+		if (process.platform !== "win32") await handle.chmod(0o600);
+		await handle.sync();
+		await handle.close();
+		handle = undefined;
+		await fs.rename(temporaryPath, configPath);
+	} catch (error) {
+		await handle?.close().catch(() => undefined);
+		await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+		throw error;
+	}
+}