@narumitw/pi-sync 0.49.3 → 0.49.5

package/src/state-directory.ts

@@ -0,0 +1,184 @@
+import { lstatSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import lockfile from "proper-lockfile";
+import { LOCK_GUARD_STALE_MS } from "./lock-policy.js";
+import { LOCKFILE_FS_ADAPTER } from "./lockfile-fs.js";
+
+const CANONICAL_DIRECTORY_NAME = "pi-sync";
+const LEGACY_DIRECTORY_NAME = ".pisync";
+const MIGRATION_LOCK_NAME = ".pi-sync-state-migration.lock";
+const MIGRATION_LOCK_STALE_MS = 30_000;
+const MIGRATION_LOCK_UPDATE_MS = 10_000;
+
+export type StateDirectoryPreparation =
+	| { status: "ready" }
+	| { status: "migrated"; message: string }
+	| { status: "deferred"; message: string };
+
+interface StateDirectoryGuard {
+	release: () => Promise<void>;
+	throwIfCompromised: () => void;
+}
+
+export function stateDir() {
+	const roots = inspectStateRoots();
+	if (roots.canonical) return canonicalStateDir();
+	if (roots.legacy) return legacyStateDir();
+	return canonicalStateDir();
+}
+
+export function legacyStateDir() {
+	return path.join(getAgentDir(), LEGACY_DIRECTORY_NAME);
+}
+
+export function stateDirectoryMigrationNotice() {
+	const roots = inspectStateRoots();
+	if (!roots.legacy) return undefined;
+	return "Legacy pi-sync state is still stored in .pisync. Close other Pi sessions, then run /sync migrate-state to move it to pi-sync/.";
+}
+
+export async function withStateDirectoryAccess<T>(fn: () => Promise<T>): Promise<T> {
+	return runWithStateDirectoryGuard(await acquireStateDirectoryGuard(), fn);
+}
+
+export async function migrateLegacyStateDirectory(): Promise<StateDirectoryPreparation> {
+	const initial = inspectStateRoots();
+	if (initial.canonical || !initial.legacy) return { status: "ready" };
+
+	let guard: StateDirectoryGuard;
+	try {
+		guard = await acquireStateDirectoryGuard();
+	} catch (error) {
+		if (!isLockHeldError(error)) throw error;
+		return {
+			status: "deferred",
+			message:
+				"pi-sync state migration was deferred because another state user is active. Close other Pi sessions and retry.",
+		};
+	}
+	return runWithStateDirectoryGuard(guard, async () => {
+		const roots = inspectStateRoots();
+		if (roots.canonical || !roots.legacy) return { status: "ready" };
+
+		const legacyLock = path.join(legacyStateDir(), "lock");
+		const legacyGuardHeld = await lockfile.check(legacyLock, {
+			fs: LOCKFILE_FS_ADAPTER,
+			lockfilePath: `${legacyLock}.guard`,
+			realpath: false,
+			stale: LOCK_GUARD_STALE_MS,
+		});
+		if (legacyGuardHeld || (await pathExists(legacyLock))) {
+			return {
+				status: "deferred",
+				message:
+					"pi-sync state migration was deferred because the legacy directory is busy. Close other Pi sessions, clear any confirmed stale sync lock, and retry.",
+			};
+		}
+		guard.throwIfCompromised();
+		await fs.rename(legacyStateDir(), canonicalStateDir());
+		guard.throwIfCompromised();
+		inspectStateRoots();
+		return {
+			status: "migrated",
+			message: `Migrated pi-sync state from ${legacyStateDir()} to ${canonicalStateDir()}.`,
+		};
+	});
+}
+
+async function acquireStateDirectoryGuard(): Promise<StateDirectoryGuard> {
+	let compromisedError: Error | undefined;
+	const release = await lockfile.lock(getAgentDir(), {
+		fs: LOCKFILE_FS_ADAPTER,
+		lockfilePath: migrationLockPath(),
+		realpath: false,
+		stale: MIGRATION_LOCK_STALE_MS,
+		update: MIGRATION_LOCK_UPDATE_MS,
+		retries: { retries: 20, minTimeout: 10, maxTimeout: 50 },
+		onCompromised: (error) => {
+			compromisedError = error;
+		},
+	});
+	return {
+		release,
+		throwIfCompromised: () => {
+			if (compromisedError) throw compromisedError;
+		},
+	};
+}
+
+async function runWithStateDirectoryGuard<T>(guard: StateDirectoryGuard, fn: () => Promise<T>) {
+	let result: T | undefined;
+	let failed = false;
+	let failure: unknown;
+	try {
+		guard.throwIfCompromised();
+		result = await fn();
+		guard.throwIfCompromised();
+	} catch (error) {
+		failed = true;
+		failure = error;
+	}
+	try {
+		await guard.release();
+	} catch (error) {
+		if (!failed) {
+			failed = true;
+			failure = error;
+		}
+	}
+	if (failed) throw failure;
+	return result as T;
+}
+
+function isLockHeldError(error: unknown) {
+	return (error as NodeJS.ErrnoException).code === "ELOCKED";
+}
+
+function canonicalStateDir() {
+	return path.join(getAgentDir(), CANONICAL_DIRECTORY_NAME);
+}
+
+function migrationLockPath() {
+	return path.join(getAgentDir(), MIGRATION_LOCK_NAME);
+}
+
+function inspectStateRoots() {
+	const canonical = isDirectoryRoot(canonicalStateDir(), "canonical");
+	const legacy = isDirectoryRoot(legacyStateDir(), "legacy");
+	if (canonical && legacy) {
+		throw new Error(
+			`Both legacy ${legacyStateDir()} and canonical ${canonicalStateDir()} pi-sync state directories exist. Close all Pi sessions and reconcile the directories manually; pi-sync will not merge or delete either directory.`,
+		);
+	}
+	return { canonical, legacy };
+}
+
+function isDirectoryRoot(directory: string, label: string) {
+	try {
+		const entry = lstatSync(directory);
+		if (entry.isSymbolicLink()) {
+			throw new Error(
+				`Refusing to use ${label} pi-sync state directory symbolic link: ${directory}`,
+			);
+		}
+		if (!entry.isDirectory()) {
+			throw new Error(`${label} pi-sync state path is not a directory: ${directory}`);
+		}
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+async function pathExists(filePath: string) {
+	try {
+		await fs.lstat(filePath);
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+		throw error;
+	}
+}

package/src/sync-backend.ts

@@ -1,4 +1,4 @@
-import type { Snapshot } from "./types.js";
+import type { Snapshot, SnapshotSelection } from "./types.js";
 
 export type PublicationCapability =
 	| "read-check-write-verify"
@@ -15,6 +15,8 @@ export interface RemoteHead {
 	createdAt: string;
 	machine: string;
 	syncSessions: boolean;
+	/** Validated lightweight projection; revalidate it against the immutable snapshot before adoption. */
+	selection?: SnapshotSelection;
 }
 
 export interface RemoteHistoryEntry {

package/src/sync-format.ts

@@ -1,5 +1,6 @@
 import { agentDir } from "./config.js";
 import type { PublicationCapability, RemoteHead } from "./sync-backend.js";
+import { inspectRemoteSelection } from "./sync-policy.js";
 import { fileHashMap } from "./sync-state.js";
 import type { CommonSyncConfig, Snapshot } from "./types.js";
 
@@ -50,6 +51,11 @@ export function formatPushSummary(
 		`Sessions: ${upload.syncSessions ? "included — may contain private conversations" : "not included"}`,
 		head ? `Remote latest: ${head.snapshotId}` : "Remote latest: empty",
 		"Publication effect: the backend's active head will reference the new immutable snapshot.",
+		...(remote && inspectRemoteSelection(config.include, remote).kind === "different"
+			? [
+					"Included-content policy effect: replace the differing remote selection with this setup's local selection.",
+				]
+			: []),
 		formatPublicationPreview(remote, upload),
 		preservedRemoteFileCount > 0
 			? `Possible secrets in locally managed files were scanned before this prompt; ${preservedRemoteFileCount} preserved remote file(s) were not rescanned.`

package/src/sync-operations.ts

@@ -11,6 +11,11 @@ import {
 	writeStateForConfig,
 } from "./config.js";
 import { inspectLock, isLockGuardHeld, isStaleLock, withLock } from "./lock.js";
+import {
+	formatRemoteSelectionStatus,
+	readSnapshotForHead,
+	requireCompatibleRemoteSelection,
+} from "./remote-snapshot.js";
 import {
 	createSnapshot,
 	filterSnapshotForConfigPolicy,
@@ -41,6 +46,7 @@ import {
 	publicationCapabilityDescription,
 	safeTerminalText,
 } from "./sync-format.js";
+import { inspectRemoteSelection, RemoteSelectionMismatchError } from "./sync-policy.js";
 import {
 	canPullRemoteSessionsOnFirstSync,
 	canPullRemoteSettingsOnFirstSync,
@@ -124,6 +130,9 @@ export async function status(
 	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
@@ -143,12 +152,15 @@ export async function status(
 			`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 || warnings.length > 0 ? "warning" : "info",
+		localChanged || remoteChanged || selectionState?.kind === "different" || warnings.length > 0
+			? "warning"
+			: "info",
 	);
 }
 
@@ -166,7 +178,12 @@ export async function diff(
 		snapshotOptionsForContext(ctx, config),
 	);
 	throwIfAborted(options.signal);
-	const { snapshot: remote } = await readRemoteSnapshot(backend, config, options.signal);
+	const { snapshot: remote, selectionState } = await readRemoteSnapshot(
+		backend,
+		config,
+		options.signal,
+		{ allowSelectionDifference: true },
+	);
 	throwIfAborted(options.signal);
 	ctx.ui.setStatus(STATUS_KEY, undefined);
 
@@ -177,9 +194,10 @@ export async function diff(
 		`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 ? "warning" : "info";
+	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)}`,
@@ -299,6 +317,18 @@ export async function push(
 		state,
 		options.signal,
 	);
+	if (
+		!options.force &&
+		!remoteForUpload &&
+		head?.selection &&
+		inspectRemoteSelection(config.include, { selection: head.selection, files: [] }).kind ===
+			"different"
+	) {
+		remoteForUpload = await readSnapshotForHead(backend, head, options.signal);
+	}
+	if (remoteForUpload && !options.force) {
+		requireCompatibleRemoteSelection(config, remoteForUpload);
+	}
 	if (
 		remoteChangedSinceState(head, state, config, (left, right) =>
 			backend.sameRevision(left, right),
@@ -886,16 +916,20 @@ 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 };
-	const snapshot = await backend.readSnapshot(head.snapshotRef, signal);
-	if (snapshot.id !== head.snapshotId) {
-		throw new Error(
-			`Remote head ${head.snapshotId} resolved to unexpected snapshot ${snapshot.id}.`,
-		);
+	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") {
+		throw new RemoteSelectionMismatchError(config.include, selectionState.include);
 	}
-	return { head, snapshot: filterSnapshotForConfigPolicy(snapshot, config) };
+	return {
+		head,
+		snapshot: filterSnapshotForConfigPolicy(snapshot, config),
+		selectionState,
+	};
 }
 
 async function confirmPush(

package/src/sync-policy.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { isDeniedPath, toPosix } from "./paths.js";
+import type { Snapshot, SnapshotSelection } from "./types.js";
 
 export const BUILT_IN_SYNC_ROOTS = [
 	"settings.json",
@@ -15,6 +16,15 @@ export const BUILT_IN_SYNC_ROOTS = [
 
 export const DEFAULT_SYNC_INCLUDE = [...BUILT_IN_SYNC_ROOTS] as const;
 export type BuiltInSyncFile = (typeof BUILT_IN_SYNC_ROOTS)[number];
+const SNAPSHOT_SELECTION_VERSION = 1;
+const MAX_SYNC_INCLUDE_ITEMS = 1_024;
+const MAX_SYNC_INCLUDE_PATH_BYTES = 4_096;
+const MAX_SYNC_INCLUDE_TOTAL_BYTES = 256 * 1_024;
+
+interface IncludePathNode {
+	selected?: string;
+	children: Map<string, IncludePathNode>;
+}
 
 const BUILT_IN_BY_LOWER = new Map<string, BuiltInSyncFile>(
 	BUILT_IN_SYNC_ROOTS.map((fileName) => [fileName.toLowerCase(), fileName]),
@@ -34,12 +44,31 @@ export function normalizeSyncInclude(value: unknown): string[] {
 	if (!Array.isArray(value)) {
 		throw new Error("Invalid pi-sync settings: sync.include must be an array.");
 	}
+	if (value.length > MAX_SYNC_INCLUDE_ITEMS) {
+		throw new Error(
+			`Invalid pi-sync settings: sync.include has too many items; limit: ${MAX_SYNC_INCLUDE_ITEMS}.`,
+		);
+	}
 	const result: string[] = [];
 	const seen = new Set<string>();
+	const pathRoot: IncludePathNode = { children: new Map() };
+	let totalBytes = 0;
 	for (const item of value) {
 		if (typeof item !== "string") {
 			throw new Error("Invalid pi-sync settings: sync.include items must be strings.");
 		}
+		const itemBytes = Buffer.byteLength(item, "utf8");
+		if (itemBytes > MAX_SYNC_INCLUDE_PATH_BYTES) {
+			throw new Error(
+				`Invalid pi-sync settings: sync.include item is too long; limit: ${MAX_SYNC_INCLUDE_PATH_BYTES} bytes.`,
+			);
+		}
+		totalBytes += itemBytes;
+		if (totalBytes > MAX_SYNC_INCLUDE_TOTAL_BYTES) {
+			throw new Error(
+				`Invalid pi-sync settings: sync.include is too large; limit: ${MAX_SYNC_INCLUDE_TOTAL_BYTES} bytes.`,
+			);
+		}
 		const trimmed = item.trim();
 		const builtIn = BUILT_IN_BY_LOWER.get(trimmed.toLowerCase());
 		const normalized = builtIn ?? (trimmed.toLowerCase() === "sessions" ? "sessions" : trimmed);
@@ -48,19 +77,34 @@ export function normalizeSyncInclude(value: unknown): string[] {
 		if (seen.has(identity)) {
 			throw new Error(`Invalid pi-sync settings: duplicate sync.include item: ${item}`);
 		}
-		for (const previous of seen) {
-			if (identity.startsWith(`${previous}/`) || previous.startsWith(`${identity}/`)) {
-				throw new Error(
-					`Invalid pi-sync settings: overlapping sync.include items are ambiguous: ${item}`,
-				);
-			}
-		}
+		addIncludePath(pathRoot, identity, item);
 		seen.add(identity);
 		result.push(normalized);
 	}
 	return result;
 }
 
+function addIncludePath(root: IncludePathNode, identity: string, source: string) {
+	let node = root;
+	for (const segment of identity.split("/")) {
+		if (node.selected !== undefined) throwOverlappingInclude(source);
+		let child = node.children.get(segment);
+		if (!child) {
+			child = { children: new Map() };
+			node.children.set(segment, child);
+		}
+		node = child;
+	}
+	if (node.children.size > 0) throwOverlappingInclude(source);
+	node.selected = identity;
+}
+
+function throwOverlappingInclude(item: string): never {
+	throw new Error(
+		`Invalid pi-sync settings: overlapping sync.include items are ambiguous: ${item}`,
+	);
+}
+
 function validateAgentRelativeInclude(value: string) {
 	const normalized = toPosix(value);
 	const topLevel = normalized.split("/")[0]?.toLowerCase();
@@ -89,6 +133,138 @@ function validateAgentRelativeInclude(value: string) {
 	}
 }
 
+export function portableSnapshotSelection(value: unknown): SnapshotSelection {
+	const selection = value as Partial<SnapshotSelection> | null;
+	if (
+		!selection ||
+		typeof selection !== "object" ||
+		Array.isArray(selection) ||
+		selection.version !== SNAPSHOT_SELECTION_VERSION ||
+		!Object.hasOwn(selection, "include") ||
+		Object.keys(selection).some((key) => key !== "version" && key !== "include")
+	) {
+		throw new Error("Invalid snapshot selection policy.");
+	}
+	return {
+		version: SNAPSHOT_SELECTION_VERSION,
+		include: normalizeSyncInclude(selection.include),
+	};
+}
+
+export function snapshotSelectionInclude(snapshot: Pick<Snapshot, "selection">) {
+	return snapshot.selection === undefined
+		? undefined
+		: portableSnapshotSelection(snapshot.selection).include;
+}
+
+export function selectionForSnapshot(include: unknown): SnapshotSelection {
+	return { version: SNAPSHOT_SELECTION_VERSION, include: normalizeSyncInclude(include) };
+}
+
+export function sameSyncInclude(left: unknown, right: unknown) {
+	const normalizedLeft = normalizeSyncInclude(left);
+	const normalizedRight = normalizeSyncInclude(right);
+	return (
+		normalizedLeft.length === normalizedRight.length &&
+		normalizedLeft.every((item, index) => item === normalizedRight[index])
+	);
+}
+
+export function compareSyncInclude(local: unknown, remote: unknown) {
+	const localInclude = normalizeSyncInclude(local);
+	const remoteInclude = normalizeSyncInclude(remote);
+	const localSet = new Set(localInclude);
+	const remoteSet = new Set(remoteInclude);
+	return {
+		same: sameSyncInclude(localInclude, remoteInclude),
+		remoteOnly: remoteInclude.filter((item) => !localSet.has(item)),
+		localOnly: localInclude.filter((item) => !remoteSet.has(item)),
+	};
+}
+
+export type RemoteSelectionState =
+	| { kind: "legacy"; discovered: string[] }
+	| { kind: "same"; include: string[] }
+	| {
+			kind: "different";
+			include: string[];
+			remoteOnly: string[];
+			localOnly: string[];
+	  };
+
+export function inspectRemoteSelection(
+	localInclude: unknown,
+	snapshot: Pick<Snapshot, "selection" | "files">,
+): RemoteSelectionState {
+	const remoteInclude = snapshotSelectionInclude(snapshot);
+	if (!remoteInclude) {
+		return { kind: "legacy", discovered: discoverLegacySnapshotInclude(snapshot) };
+	}
+	const comparison = compareSyncInclude(localInclude, remoteInclude);
+	return comparison.same
+		? { kind: "same", include: remoteInclude }
+		: { kind: "different", include: remoteInclude, ...comparison };
+}
+
+export class RemoteSelectionMismatchError extends Error {
+	readonly localInclude: string[];
+	readonly remoteInclude: string[];
+
+	constructor(localInclude: unknown, remoteInclude: unknown) {
+		const local = normalizeSyncInclude(localInclude);
+		const remote = normalizeSyncInclude(remoteInclude);
+		super(
+			"Remote included content differs from this sync setup. Review Remote included content in /sync Settings, or use a reviewed force push to keep local selection.",
+		);
+		this.name = "RemoteSelectionMismatchError";
+		this.localInclude = local;
+		this.remoteInclude = remote;
+	}
+}
+
+export function discoverLegacySnapshotInclude(snapshot: Pick<Snapshot, "files">) {
+	const builtIns = new Set<BuiltInSyncFile>();
+	const custom = new Set<string>();
+	let sessions = false;
+	for (const file of snapshot.files) {
+		const normalized = toPosix(file.path);
+		if (
+			!normalized ||
+			file.path.includes("\\") ||
+			normalized.length > 4096 ||
+			normalized.startsWith("../") ||
+			path.posix.isAbsolute(normalized) ||
+			path.posix.normalize(normalized) !== normalized ||
+			// biome-ignore lint/suspicious/noControlCharactersInRegex: Ignore unsafe legacy paths.
+			/[\u0000-\u001f\u007f-\u009f]/u.test(normalized) ||
+			isDeniedPath(normalized)
+		) {
+			continue;
+		}
+		const [topLevel, ...rest] = normalized.split("/");
+		if (!topLevel) continue;
+		if (topLevel === "sessions" && rest.length > 0) {
+			sessions = true;
+			continue;
+		}
+		const builtIn = BUILT_IN_BY_LOWER.get(topLevel.toLowerCase());
+		if (
+			builtIn &&
+			((TOP_LEVEL_DIRS.has(builtIn) && rest.length > 0) ||
+				(!TOP_LEVEL_DIRS.has(builtIn) && rest.length === 0))
+		) {
+			builtIns.add(builtIn);
+			continue;
+		}
+		if (isSafeCustomIncludePath(topLevel)) custom.add(topLevel);
+	}
+	return [
+		...BUILT_IN_SYNC_ROOTS.filter((item) => builtIns.has(item)),
+		...[...custom].sort((left, right) => left.localeCompare(right)),
+		...(sessions ? ["sessions"] : []),
+	];
+}
+
 export function syncIncludeSelection(value: unknown) {
 	const include = normalizeSyncInclude(value);
 	const builtIns = include.filter((item): item is BuiltInSyncFile =>