@narumitw/pi-sync 0.31.0 → 0.35.0

package/src/command.ts

@@ -7,10 +7,10 @@ const YES_FLAG_COMPLETIONS: readonly CommandArgumentCompletion[] = [
 ];
 export const SYNC_COMMANDS = [
 	{ name: "help", description: "Show command usage" },
-	{ name: "use", description: "Switch the current sync target", usageSuffix: " <target>" },
+	{ name: "use", description: "Switch the current sync setup", usageSuffix: " <setup>" },
 	{ name: "init", description: "Create local config template" },
 	{ name: "config", description: "Show resolved configuration" },
-	{ name: "files", description: "Choose synced files" },
+	{ name: "files", description: "Choose included content" },
 	{ name: "status", description: "Show sync status" },
 	{ name: "diff", description: "Show local/remote diff" },
 	{ name: "doctor", description: "Check config, secrets, and lock state" },
@@ -27,39 +27,39 @@ export type SyncCommandName = (typeof SYNC_COMMANDS)[number]["name"];
 const SYNC_COMMAND_COMPLETIONS: readonly CommandArgumentCompletion[] = SYNC_COMMANDS.map(
 	({ name, description }) => ({ value: name, label: name, description }),
 );
-let targetCompletionNames: string[] = [];
+let setupCompletionNames: string[] = [];
 
-export function setSyncTargetCompletions(names: readonly string[]) {
-	targetCompletionNames = [...new Set(names)].sort((left, right) => left.localeCompare(right));
+export function setSyncSetupCompletions(names: readonly string[]) {
+	setupCompletionNames = [...new Set(names)].sort((left, right) => left.localeCompare(right));
 }
-const TARGET_FLAG_COMPLETION = {
-	value: "--target",
-	label: "--target",
-	description: "Address a target without switching",
+const SETUP_FLAG_COMPLETION = {
+	value: "--setup",
+	label: "--setup",
+	description: "Address a sync setup without switching",
 } as const;
 const SYNC_FLAG_COMPLETIONS: Record<string, readonly CommandArgumentCompletion[]> = {
-	config: [TARGET_FLAG_COMPLETION],
-	files: [TARGET_FLAG_COMPLETION],
-	status: [TARGET_FLAG_COMPLETION],
-	diff: [TARGET_FLAG_COMPLETION],
-	doctor: [TARGET_FLAG_COMPLETION],
+	config: [SETUP_FLAG_COMPLETION],
+	files: [SETUP_FLAG_COMPLETION],
+	status: [SETUP_FLAG_COMPLETION],
+	diff: [SETUP_FLAG_COMPLETION],
+	doctor: [SETUP_FLAG_COMPLETION],
 	push: [
 		...YES_FLAG_COMPLETIONS,
 		{ value: "--force", label: "--force", description: "Overwrite visible remote changes" },
-		TARGET_FLAG_COMPLETION,
+		SETUP_FLAG_COMPLETION,
 	],
 	pull: [
 		...YES_FLAG_COMPLETIONS,
 		{ value: "--force", label: "--force", description: "Overwrite local changes" },
-		TARGET_FLAG_COMPLETION,
+		SETUP_FLAG_COMPLETION,
 	],
 	sync: [
 		...YES_FLAG_COMPLETIONS,
 		{ value: "--force", label: "--force", description: "Resolve conflicts by forcing action" },
-		TARGET_FLAG_COMPLETION,
+		SETUP_FLAG_COMPLETION,
 	],
-	history: [TARGET_FLAG_COMPLETION],
-	rollback: [...YES_FLAG_COMPLETIONS, TARGET_FLAG_COMPLETION],
+	history: [SETUP_FLAG_COMPLETION],
+	rollback: [...YES_FLAG_COMPLETIONS, SETUP_FLAG_COMPLETION],
 	unlock: [{ value: "--stale", label: "--stale", description: "Remove only a stale lock" }],
 };
 
@@ -75,17 +75,17 @@ export function parseOptions(args: string[]): CommandOptions {
 	let yes = false;
 	let force = false;
 	let stale = false;
-	let target: string | undefined;
+	let setup: string | undefined;
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
 		if (arg === "--yes" || arg === "-y") yes = true;
 		else if (arg === "--force") force = true;
 		else if (arg === "--stale") stale = true;
-		else if (arg === "--target") {
+		else if (arg === "--setup") {
 			const name = args[index + 1];
-			if (!name || name.startsWith("-")) throw new Error("--target requires a target name.");
-			if (target !== undefined) throw new Error("--target may be provided only once.");
-			target = name;
+			if (!name || name.startsWith("-")) throw new Error("--setup requires a sync setup name.");
+			if (setup !== undefined) throw new Error("--setup may be provided only once.");
+			setup = name;
 			index += 1;
 		} else if (arg.startsWith("-")) {
 			throw new Error(`Unknown sync option: ${arg}`);
@@ -98,13 +98,13 @@ export function parseOptions(args: string[]): CommandOptions {
 		silent: false,
 		reload: true,
 		auto: false,
-		...(target === undefined ? {} : { target }),
+		...(setup === undefined ? {} : { setup }),
 		args: values,
 	};
 }
 
 export function validateCommandOptions(command: string, options: CommandOptions) {
-	const targetAllowed = new Set([
+	const setupAllowed = new Set([
 		"config",
 		"files",
 		"status",
@@ -116,8 +116,8 @@ export function validateCommandOptions(command: string, options: CommandOptions)
 		"history",
 		"rollback",
 	]);
-	if (options.target && !targetAllowed.has(command)) {
-		throw new Error(`--target is not supported by /sync ${command}.`);
+	if (options.setup && !setupAllowed.has(command)) {
+		throw new Error(`--setup is not supported by /sync ${command}.`);
 	}
 	if ((options.yes || options.force) && !["push", "pull", "sync", "rollback"].includes(command)) {
 		throw new Error(`Confirmation/force options are not supported by /sync ${command}.`);
@@ -128,8 +128,8 @@ export function validateCommandOptions(command: string, options: CommandOptions)
 	const expectedValues = command === "rollback" || command === "use" ? 1 : 0;
 	if (options.args.length !== expectedValues) {
 		if (command === "rollback")
-			throw new Error("Usage: /sync rollback <snapshot-id> [--yes] [--target <name>]");
-		if (command === "use") throw new Error("Usage: /sync use <target>");
+			throw new Error("Usage: /sync rollback <snapshot-id> [--yes] [--setup <name>]");
+		if (command === "use") throw new Error("Usage: /sync use <setup>");
 		throw new Error(`Unexpected argument for /sync ${command}: ${options.args.join(" ")}`);
 	}
 }
@@ -151,12 +151,12 @@ export function completeSyncArguments(argumentPrefix: string): CommandArgumentCo
 	const args = tokens.slice(1);
 	if (command === "use") {
 		if (args.length > 1 || (trailingSpace && args.length > 0)) return null;
-		return completeTargetValue(prefix, trailingSpace ? "" : (args[0] ?? ""));
+		return completeSetupValue(prefix, trailingSpace ? "" : (args[0] ?? ""));
 	}
-	const targetFlagIndex = args.lastIndexOf("--target");
-	if (targetFlagIndex >= 0 && targetFlagIndex === args.length - (trailingSpace ? 1 : 2)) {
-		const currentTarget = trailingSpace ? "" : (args.at(-1) ?? "");
-		if (!currentTarget.startsWith("-")) return completeTargetValue(prefix, currentTarget);
+	const setupFlagIndex = args.lastIndexOf("--setup");
+	if (setupFlagIndex >= 0 && setupFlagIndex === args.length - (trailingSpace ? 1 : 2)) {
+		const currentSetup = trailingSpace ? "" : (args.at(-1) ?? "");
+		if (!currentSetup.startsWith("-")) return completeSetupValue(prefix, currentSetup);
 	}
 
 	const flagCompletions = SYNC_FLAG_COMPLETIONS[command];
@@ -181,15 +181,15 @@ export function completeSyncArguments(argumentPrefix: string): CommandArgumentCo
 		: null;
 }
 
-function completeTargetValue(prefix: string, current: string) {
+function completeSetupValue(prefix: string, current: string) {
 	const currentRaw = current ? (prefix.match(/\S+$/u)?.[0] ?? "") : "";
 	const completionPrefix = currentRaw ? prefix.slice(0, prefix.length - currentRaw.length) : prefix;
-	const matches = targetCompletionNames.filter((name) => name.startsWith(current));
+	const matches = setupCompletionNames.filter((name) => name.startsWith(current));
 	return matches.length > 0
 		? matches.map((name) => ({
 				value: `${completionPrefix}${name}`,
 				label: name,
-				description: "Sync target",
+				description: "Sync setup",
 			}))
 		: null;
 }
@@ -230,6 +230,6 @@ export function usage() {
 	return [
 		"Usage: /sync <command>",
 		`Commands: ${commands}`,
-		"Settings: use /sync init or edit profiles and targets in ~/.pi/agent/pi-sync.json (or $PI_CODING_AGENT_DIR/pi-sync.json). Existing PI_SYNC_* overrides still work but are deprecated for future major-version removal.",
+		"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/config-errors.ts

@@ -0,0 +1,7 @@
+export function isMissingConfigError(error: unknown) {
+	return (
+		error instanceof Error &&
+		(error.message.startsWith("Missing pi-sync settings.") ||
+			error.message === "No sync setups are configured.")
+	);
+}

package/src/config-file.ts

@@ -1,6 +1,5 @@
 import { randomUUID } from "node:crypto";
 import {
-	constants as fsConstants,
 	mkdir,
 	mkdirSync,
 	realpath,
@@ -36,23 +35,51 @@ const LOCKFILE_FS_ADAPTER = {
 	utimesSync,
 };
 
-type LinkFile = (source: string, destination: string) => Promise<void>;
-let linkConfigFile: LinkFile = (source, destination) => fs.link(source, destination);
+type PublishFile = (source: string, destination: string) => Promise<void>;
+let publishConfigFile: PublishFile = publishFileWithoutReplacement;
+let beforeConfigPublicationHook: () => Promise<void> = async () => undefined;
+let afterMissingConfigReadProbeHook: () => Promise<void> = async () => undefined;
 let afterReplacementInstalledHook: () => Promise<void> = async () => undefined;
 let afterConfigQuarantinedHook: () => Promise<void> = async () => undefined;
 
 export type FileIdentity = { dev: number; ino: number };
 
-export async function withConfigFileLinkForTest<T>(
-	link: LinkFile,
+export async function withConfigFilePublicationForTest<T>(
+	publish: PublishFile,
 	run: () => Promise<T>,
 ): Promise<T> {
-	const previous = linkConfigFile;
-	linkConfigFile = link;
+	const previous = publishConfigFile;
+	publishConfigFile = publish;
 	try {
 		return await run();
 	} finally {
-		linkConfigFile = previous;
+		publishConfigFile = previous;
+	}
+}
+
+export async function withConfigPublicationReadyHookForTest<T>(
+	hook: () => Promise<void>,
+	run: () => Promise<T>,
+): Promise<T> {
+	const previous = beforeConfigPublicationHook;
+	beforeConfigPublicationHook = hook;
+	try {
+		return await run();
+	} finally {
+		beforeConfigPublicationHook = previous;
+	}
+}
+
+export async function withMissingConfigReadProbeHookForTest<T>(
+	hook: () => Promise<void>,
+	run: () => Promise<T>,
+): Promise<T> {
+	const previous = afterMissingConfigReadProbeHook;
+	afterMissingConfigReadProbeHook = hook;
+	try {
+		return await run();
+	} finally {
+		afterMissingConfigReadProbeHook = previous;
 	}
 }
 
@@ -99,10 +126,10 @@ export function legacyLocalConfigPath() {
 }
 
 export async function activeLocalConfigPath() {
-	return withLocalConfigFileLock(async () => {
-		const canonicalPath = localConfigPath();
+	const canonicalPath = localConfigPath();
+	const legacyPath = legacyLocalConfigPath();
+	return withLocalConfigReadLockIfNeeded(async () => {
 		if (await pathExists(canonicalPath)) return canonicalPath;
-		const legacyPath = legacyLocalConfigPath();
 		return (await pathExists(legacyPath)) ? legacyPath : canonicalPath;
 	});
 }
@@ -114,16 +141,75 @@ export function consumeLocalConfigMigrationNotice() {
 	return notice;
 }
 
+export async function readActiveLocalConfigDocumentForRepair(): Promise<
+	LocalConfigDocument | undefined
+> {
+	const canonicalPath = localConfigPath();
+	const legacyPath = legacyLocalConfigPath();
+	return withLocalConfigReadLockIfNeeded(async () => {
+		const filePath = (await pathExists(canonicalPath)) ? canonicalPath : legacyPath;
+		const snapshot = await readConfigSnapshotIfExists(filePath);
+		return snapshot ? { path: filePath, ...snapshot } : undefined;
+	});
+}
+
 export async function readMigratingLocalConfigDocument(
 	validateForMigration: (settings: Record<string, unknown>) => void,
 ): Promise<LocalConfigDocument | undefined> {
-	return withLocalConfigFileLock(async () => {
+	return withLocalConfigReadLockIfNeeded(async () => {
 		const configPath = await prepareLocalConfigPath(validateForMigration);
 		const snapshot = await readConfigSnapshotIfExists(configPath);
 		return snapshot ? { path: configPath, ...snapshot } : undefined;
 	});
 }
 
+async function withLocalConfigReadLockIfNeeded<T>(read: () => Promise<T>): Promise<T> {
+	if ((await pathExists(localConfigPath())) || (await pathExists(legacyLocalConfigPath()))) {
+		return withLocalConfigFileLock(read);
+	}
+	await afterMissingConfigReadProbeHook();
+	if (await pathExists(configMutationLockPath())) return withLocalConfigFileLock(read);
+	return read();
+}
+
+export function updateLocalConfigDocument<T extends Record<string, unknown>>(
+	defaultValue: T,
+	update: (current: T) => T,
+	validate: (value: Record<string, unknown>) => void,
+	signal?: AbortSignal,
+): Promise<T> {
+	return withLocalConfigFileLock(async () => {
+		signal?.throwIfAborted();
+		const configPath = await prepareLocalConfigPath(validate);
+		const snapshot = await readConfigSnapshotIfExists(configPath);
+		const document = snapshot ? { path: configPath, ...snapshot } : undefined;
+		const current = document
+			? (structuredClone(document.parsed) as T)
+			: structuredClone(defaultValue);
+		const next = update(current);
+		validate(next);
+		signal?.throwIfAborted();
+		if (document && JSON.stringify(document.parsed) === JSON.stringify(next)) return next;
+		if (document) await replaceLocalConfigDocumentUnlocked(document, next);
+		else await installPrivateConfigExclusively(localConfigPath(), serializedConfig(next));
+		return next;
+	});
+}
+
+export function createLocalConfigDocument(value: Record<string, unknown>) {
+	return withLocalConfigFileLock(async () => {
+		const bytes = serializedConfig(value);
+		try {
+			await installPrivateConfigExclusively(localConfigPath(), bytes);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+				throw new Error("Pi-sync settings were created concurrently; reopen settings and retry.");
+			}
+			throw error;
+		}
+	});
+}
+
 export function replaceLocalConfigDocument(
 	document: LocalConfigDocument,
 	value: Record<string, unknown>,
@@ -135,13 +221,13 @@ async function replaceLocalConfigDocumentUnlocked(
 	document: LocalConfigDocument,
 	value: Record<string, unknown>,
 ) {
-	const nextBytes = Buffer.from(`${JSON.stringify(value, null, "\t")}\n`, "utf8");
+	const nextBytes = serializedConfig(value);
 	const canonicalPath = localConfigPath();
 	if (document.path !== canonicalPath) {
 		if (!(await configDocumentStillMatches(document))) throw settingsChangedError();
 		let installed: FileIdentity;
 		try {
-			installed = await installPrivateConfigExclusively(canonicalPath, nextBytes, true);
+			installed = await installPrivateConfigExclusively(canonicalPath, nextBytes);
 		} catch (error) {
 			if ((error as NodeJS.ErrnoException).code === "EEXIST") {
 				throw new Error("Canonical settings were created concurrently; no settings were replaced.");
@@ -158,7 +244,7 @@ async function replaceLocalConfigDocumentUnlocked(
 	const quarantinePath = await claimCanonicalConfigDocument(document);
 	let installed: FileIdentity;
 	try {
-		installed = await installPrivateConfigExclusively(canonicalPath, nextBytes, true);
+		installed = await installPrivateConfigExclusively(canonicalPath, nextBytes);
 	} catch (error) {
 		await restoreQuarantinedConfig(canonicalPath, quarantinePath);
 		if ((error as NodeJS.ErrnoException).code === "EEXIST") {
@@ -166,13 +252,18 @@ async function replaceLocalConfigDocumentUnlocked(
 		}
 		throw error;
 	}
-	await afterReplacementInstalledHook();
-	if (!(await fileIdentityAndContentsMatch(quarantinePath, document.identity, document.bytes))) {
+	try {
+		await afterReplacementInstalledHook();
+		if (!(await fileIdentityAndContentsMatch(quarantinePath, document.identity, document.bytes))) {
+			throw settingsChangedError();
+		}
+		if (process.platform !== "win32") await fs.chmod(quarantinePath, 0o600);
+	} catch (error) {
 		await quarantineAndRemoveConfigIfMatchesUnlocked(canonicalPath, installed, nextBytes);
 		await restoreQuarantinedConfig(canonicalPath, quarantinePath);
-		throw settingsChangedError();
+		throw error;
 	}
-	if (process.platform !== "win32") await fs.chmod(quarantinePath, 0o600);
+	await fs.rm(quarantinePath).catch(() => undefined);
 	await syncParentDirectory(canonicalPath).catch(() => undefined);
 }
 
@@ -301,6 +392,10 @@ async function readConfigSnapshotIfExists(filePath: string): Promise<ConfigSnaps
 	}
 }
 
+function serializedConfig(value: Record<string, unknown>) {
+	return Buffer.from(`${JSON.stringify(value, null, "\t")}\n`, "utf8");
+}
+
 function parseConfigObject(bytes: Buffer, filePath: string) {
 	let parsed: unknown;
 	try {
@@ -314,11 +409,7 @@ function parseConfigObject(bytes: Buffer, filePath: string) {
 	return parsed as Record<string, unknown>;
 }
 
-async function installPrivateConfigExclusively(
-	filePath: string,
-	bytes: Buffer,
-	allowCopyFallback = false,
-) {
+async function installPrivateConfigExclusively(filePath: string, bytes: Buffer) {
 	await fs.mkdir(path.dirname(filePath), { recursive: true });
 	const temporaryPath = path.join(
 		path.dirname(filePath),
@@ -332,23 +423,34 @@ async function installPrivateConfigExclusively(
 		await handle.sync();
 		await handle.close();
 		handle = undefined;
-		try {
-			await linkConfigFile(temporaryPath, filePath);
-		} catch (error) {
-			if (!allowCopyFallback || !isUnsupportedLinkError(error)) throw error;
-			await fs.copyFile(temporaryPath, filePath, fsConstants.COPYFILE_EXCL);
-		}
+		await publishConfigFile(temporaryPath, filePath);
 		const installed = await fs.lstat(filePath);
+		let publishedHandle: fs.FileHandle | undefined;
+		let publicationError: unknown;
 		try {
-			if (process.platform !== "win32") await fs.chmod(filePath, 0o600);
-			await syncParentDirectory(filePath).catch(() => undefined);
+			if (installed.isSymbolicLink() || !installed.isFile()) {
+				throw new Error(`Published pi-sync settings are not a regular file: ${filePath}`);
+			}
+			publishedHandle = await fs.open(filePath, "r+");
+			const published = await publishedHandle.stat();
+			if (published.dev !== installed.dev || published.ino !== installed.ino) {
+				throw new Error(`Published pi-sync settings changed while opening: ${filePath}`);
+			}
+			if (process.platform !== "win32") await publishedHandle.chmod(0o600);
+			await publishedHandle.sync();
+			await syncParentDirectory(filePath);
 		} catch (error) {
+			publicationError = error;
+		} finally {
+			await publishedHandle?.close().catch(() => undefined);
+		}
+		if (publicationError) {
 			await quarantineAndRemoveConfigIfMatchesUnlocked(
 				filePath,
 				{ dev: installed.dev, ino: installed.ino },
 				bytes,
 			);
-			throw error;
+			throw publicationError;
 		}
 		return { dev: installed.dev, ino: installed.ino };
 	} finally {
@@ -388,11 +490,6 @@ function settingsChangedError() {
 	return new Error("pi-sync settings changed during migration; no settings were replaced.");
 }
 
-function isUnsupportedLinkError(error: unknown) {
-	const code = (error as NodeJS.ErrnoException).code;
-	return code === "ENOTSUP" || code === "EOPNOTSUPP" || code === "EXDEV" || code === "EPERM";
-}
-
 async function configSnapshotStillMatches(filePath: string, snapshot: ConfigSnapshot) {
 	return fileIdentityAndContentsMatch(filePath, snapshot.identity, snapshot.bytes);
 }
@@ -461,47 +558,32 @@ async function fileIdentityAndContentsMatch(
 
 async function restoreQuarantinedConfig(filePath: string, quarantinePath: string) {
 	try {
-		await linkConfigFile(quarantinePath, filePath);
-		await fs.rm(quarantinePath);
+		await renameFileWithoutReplacement(quarantinePath, filePath);
+		if (process.platform !== "win32") await fs.chmod(filePath, 0o600);
 		await syncParentDirectory(filePath);
 		return;
 	} catch (error) {
-		if (isUnsupportedLinkError(error)) {
-			try {
-				await fs.copyFile(quarantinePath, filePath, fsConstants.COPYFILE_EXCL);
-				if (process.platform !== "win32") {
-					await fs.chmod(filePath, 0o600);
-					await fs.chmod(quarantinePath, 0o600);
-				}
-				await syncParentDirectory(filePath);
-				return;
-			} catch (copyError) {
-				if ((copyError as NodeJS.ErrnoException).code !== "EEXIST") return;
-			}
-		} else if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
-			return;
-		}
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") return;
 	}
 	try {
-		const [current, quarantined] = await Promise.all([
-			fs.readFile(filePath),
-			fs.readFile(quarantinePath),
-		]);
-		if (current.equals(quarantined)) await fs.rm(quarantinePath);
-		else if (process.platform !== "win32") await fs.chmod(quarantinePath, 0o600);
+		if (process.platform !== "win32") await fs.chmod(quarantinePath, 0o600);
 		await syncParentDirectory(filePath);
 	} catch {
 		// Preserve the quarantine rather than risk deleting settings that changed concurrently.
 	}
 }
 
+function configMutationLockPath() {
+	return `${localConfigPath()}.mutation-lock`;
+}
+
 export async function withLocalConfigFileLock<T>(run: () => Promise<T>): Promise<T> {
 	const configPath = localConfigPath();
 	await fs.mkdir(path.dirname(configPath), { recursive: true });
 	let compromisedError: Error | undefined;
 	const release = await lockfile.lock(configPath, {
 		fs: LOCKFILE_FS_ADAPTER,
-		lockfilePath: `${configPath}.mutation-lock`,
+		lockfilePath: configMutationLockPath(),
 		realpath: false,
 		stale: CONFIG_LOCK_STALE_MS,
 		update: CONFIG_LOCK_UPDATE_MS,
@@ -530,6 +612,18 @@ async function syncParentDirectory(filePath: string) {
 	}
 }
 
+async function publishFileWithoutReplacement(source: string, destination: string) {
+	await beforeConfigPublicationHook();
+	await renameFileWithoutReplacement(source, destination);
+}
+
+async function renameFileWithoutReplacement(source: string, destination: string) {
+	if (await pathExists(destination)) {
+		throw Object.assign(new Error(`Settings already exist: ${destination}`), { code: "EEXIST" });
+	}
+	await fs.rename(source, destination);
+}
+
 async function pathExists(filePath: string) {
 	try {
 		await fs.lstat(filePath);