@narumitw/pi-sync 0.49.14 → 0.50.0

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) {
@@ -31,6 +32,7 @@ export async function saveNewV3Settings(
 		version: 3,
 		activeSyncSetup: input.setupName,
 		onSwitch: "ask-before-pull",
+		skipSecretScan: false,
 		storageConnections: { [input.connectionName]: structuredClone(input.connection) },
 		syncSetups: {
 			[input.setupName]: {
@@ -39,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(
@@ -91,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))
@@ -99,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 {
@@ -115,6 +129,7 @@ export async function updateSyncSetup(
 	options: {
 		expectedStorage?: SyncSetupStorageReview;
 		expectedInclude?: readonly string[];
+		expectedConnection?: StorageConnectionSettings;
 		signal?: AbortSignal;
 	} = {},
 ) {
@@ -145,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;
+	}
+}

package/src/settings/settings-types.ts

@@ -0,0 +1,128 @@
+import type { ResolvedS3Backend, ResolvedSyncBackend } from "../backends/backend-types.js";
+export type StorageConnectionType = "s3" | "git" | "webdav";
+export type OnSwitchAction = "ask-before-pull" | "pull-after-switch" | "switch-only";
+
+export interface S3CredentialsSettings {
+	accessKeyId: string;
+	secretAccessKey: string;
+	sessionToken?: string;
+	[key: string]: unknown;
+}
+
+export interface WebDavCredentialsSettings {
+	username: string;
+	password: string;
+	[key: string]: unknown;
+}
+
+export interface S3StorageConnectionSettings {
+	type: "s3";
+	endpoint: string;
+	region: string;
+	credentials: S3CredentialsSettings;
+	remote?: never;
+	url?: never;
+	[key: string]: unknown;
+}
+
+export interface GitStorageConnectionSettings {
+	type: "git";
+	remote: string;
+	endpoint?: never;
+	region?: never;
+	credentials?: never;
+	url?: never;
+	[key: string]: unknown;
+}
+
+export interface WebDavStorageConnectionSettings {
+	type: "webdav";
+	url: string;
+	credentials: WebDavCredentialsSettings;
+	endpoint?: never;
+	region?: never;
+	remote?: never;
+	[key: string]: unknown;
+}
+
+export type StorageConnectionSettings =
+	| S3StorageConnectionSettings
+	| GitStorageConnectionSettings
+	| WebDavStorageConnectionSettings;
+
+export interface CommonSyncSetupStorageSettings {
+	connection: string;
+	path: string;
+	[key: string]: unknown;
+}
+
+export interface S3SyncSetupStorageSettings extends CommonSyncSetupStorageSettings {
+	bucket: string;
+	branch?: never;
+}
+
+export interface GitSyncSetupStorageSettings extends CommonSyncSetupStorageSettings {
+	branch: string;
+	bucket?: never;
+}
+
+export interface WebDavSyncSetupStorageSettings extends CommonSyncSetupStorageSettings {
+	bucket?: never;
+	branch?: never;
+}
+
+export type SyncSetupStorageSettings =
+	| S3SyncSetupStorageSettings
+	| GitSyncSetupStorageSettings
+	| WebDavSyncSetupStorageSettings;
+
+export interface SyncPolicySettings {
+	include: string[];
+	automatic: boolean;
+	[key: string]: unknown;
+}
+
+export interface SyncSetupSettings {
+	storage: SyncSetupStorageSettings;
+	sync: SyncPolicySettings;
+	[key: string]: unknown;
+}
+
+export interface PiSyncSettingsV3 {
+	version: 3;
+	activeSyncSetup?: string;
+	onSwitch: OnSwitchAction;
+	skipSecretScan?: boolean;
+	storageConnections: Record<string, StorageConnectionSettings>;
+	syncSetups: Record<string, SyncSetupSettings>;
+	[key: string]: unknown;
+}
+
+export interface SyncConfig<Backend extends ResolvedSyncBackend = ResolvedS3Backend> {
+	setupName: string;
+	connectionName: string;
+	storagePath: string;
+	/** Snapshot/wire identity retained behind the settings normalization boundary. */
+	snapshotIdentity: string;
+	include: string[];
+	automatic: boolean;
+	onSwitch: OnSwitchAction;
+	skipSecretScan: boolean;
+	backend: Backend;
+}
+
+export type AnySyncConfig = SyncConfig<ResolvedSyncBackend>;
+export type CommonSyncConfig = Omit<AnySyncConfig, "backend">;
+
+/** UI projection over a fully validated v3 setup; it is never persisted directly. */
+export interface PartialConfig {
+	setupName: string;
+	connectionName: string;
+	storageKind: StorageConnectionType;
+	storagePath: string;
+	include: string[];
+	automatic: boolean;
+	onSwitch: OnSwitchAction;
+	bucket?: string;
+	branch?: string;
+}