@narumitw/pi-sync 0.49.14 → 0.50.0

package/src/backends/backend-types.ts

@@ -0,0 +1,81 @@
+import type { SnapshotSelection } from "../snapshot/snapshot-types.js";
+/** Backend-only resolved S3 connection fields. */
+export interface ResolvedS3StorageProfile {
+	kind: "r2" | "s3-compatible";
+	endpoint: string;
+	region: string;
+	accessKeyId: string;
+	secretAccessKey: string;
+	sessionToken?: string;
+}
+
+/** Backend-only coordinates. `prefix` is the complete reviewed v3 storage path. */
+export interface ResolvedS3Destination {
+	bucket: string;
+	prefix: string;
+	/** Snapshot/wire identity; never derived from the local setup name. */
+	namespace: string;
+}
+
+export interface ResolvedS3Backend {
+	type: "s3";
+	profile: ResolvedS3StorageProfile;
+	destination: ResolvedS3Destination;
+}
+
+export interface ResolvedWebDavStorageProfile {
+	kind: "webdav";
+	url: string;
+	username: string;
+	password: string;
+}
+
+/** Backend-only coordinates. `path` is the complete reviewed v3 storage path. */
+export interface ResolvedWebDavDestination {
+	path: string;
+	namespace: string;
+}
+
+export interface ResolvedWebDavBackend {
+	type: "webdav";
+	profile: ResolvedWebDavStorageProfile;
+	destination: ResolvedWebDavDestination;
+}
+
+export interface ResolvedGitStorageProfile {
+	kind: "git";
+	remote: string;
+}
+
+/** Backend-only coordinates. `directory` is the complete reviewed v3 storage path. */
+export interface ResolvedGitDestination {
+	branch: string;
+	directory: string;
+	namespace: string;
+}
+
+export interface ResolvedGitBackend {
+	type: "git";
+	profile: ResolvedGitStorageProfile;
+	destination: ResolvedGitDestination;
+}
+
+export type ResolvedSyncBackend = ResolvedS3Backend | ResolvedWebDavBackend | ResolvedGitBackend;
+
+export interface LatestPointer {
+	version: number;
+	profile: string;
+	snapshot: string;
+	sha256: string;
+	createdAt: string;
+	machine: string;
+	syncSessions?: boolean;
+	/** Lightweight projection; the immutable snapshot remains authoritative. */
+	selection?: SnapshotSelection;
+}
+
+export interface RemoteObject<T> {
+	value?: T;
+	etag?: string;
+	missing: boolean;
+}

package/src/{git-backend.ts → backends/git/git-backend.ts}

@@ -1,6 +1,22 @@
 import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { posixJoin } from "../../paths.js";
+import type { Snapshot, SnapshotFile } from "../../snapshot/snapshot-types.js";
+import { stateDir } from "../../state/state-directory.js";
+import { syncErrorGuidance } from "../../sync/sync-error-guidance.js";
+import type { ResolvedGitBackend } from "../backend-types.js";
+import {
+	type BackendDiagnostic,
+	type ExpectedRemoteHead,
+	type PublishSnapshotOptions,
+	type PublishSnapshotResult,
+	type RemoteHead,
+	type RemoteHistoryEntry,
+	type SyncBackend,
+	SyncBackendConflictError,
+	SyncBackendPublicationOutcomeUnknownError,
+} from "../sync-backend.js";
 import {
 	normalizeGitBranch,
 	normalizeGitDirectory,
@@ -21,20 +37,6 @@ import {
 	validateGitPublicationTree,
 	validateGitSnapshot,
 } from "./git-storage.js";
-import { posixJoin } from "./paths.js";
-import { stateDir } from "./state-directory.js";
-import {
-	type BackendDiagnostic,
-	type ExpectedRemoteHead,
-	type PublishSnapshotOptions,
-	type PublishSnapshotResult,
-	type RemoteHead,
-	type RemoteHistoryEntry,
-	type SyncBackend,
-	SyncBackendConflictError,
-	SyncBackendPublicationOutcomeUnknownError,
-} from "./sync-backend.js";
-import type { ResolvedGitBackend, Snapshot, SnapshotFile } from "./types.js";
 
 const COMMAND_TIMEOUT_MS = 30_000;
 const POST_COMMIT_TIMEOUT_MS = 45_000;
@@ -74,7 +76,7 @@ export class GitSyncBackend implements SyncBackend {
 		if (!this.allowLocalRemotes) assertProductionRemote(config.profile.remote);
 		this.identity = gitBackendIdentity(config);
 		this.destination = gitDestination(config);
-		this.cacheRoot = options.cacheRoot ?? path.join(stateDir(), "git");
+		this.cacheRoot = path.resolve(options.cacheRoot ?? path.join(stateDir(), "git"));
 		this.cacheDir = path.join(this.cacheRoot, this.identity.slice("git:".length), "repository.git");
 		this.commandTimeoutMs = options.commandTimeoutMs ?? COMMAND_TIMEOUT_MS;
 		this.postCommitTimeoutMs = options.postCommitTimeoutMs ?? POST_COMMIT_TIMEOUT_MS;
@@ -268,7 +270,14 @@ export class GitSyncBackend implements SyncBackend {
 	}
 
 	async diagnose(signal?: AbortSignal): Promise<BackendDiagnostic[]> {
-		const diagnostics: BackendDiagnostic[] = [];
+		const diagnostics: BackendDiagnostic[] = [
+			{
+				key: "git-scope",
+				level: "info",
+				message:
+					"git check scope: read remote snapshots and inspect the local cache. Write access is not tested.",
+			},
+		];
 		try {
 			const version = await runGit(["--version"], {
 				signal,
@@ -284,7 +293,13 @@ export class GitSyncBackend implements SyncBackend {
 					: `${versionText || "unknown Git version"}; pi-sync requires Git 2.30 or newer`,
 			});
 		} catch (error) {
-			return [{ key: "git-version", level: "error", message: this.safeError(error) }];
+			return [
+				{
+					key: "git-version",
+					level: "error",
+					message: syncErrorGuidance(new Error(this.safeError(error))),
+				},
+			];
 		}
 		try {
 			const head = await this.readHead(signal);
@@ -305,7 +320,7 @@ export class GitSyncBackend implements SyncBackend {
 			diagnostics.push({
 				key: "git-remote",
 				level: "error",
-				message: `git remote: ${this.safeError(error)}`,
+				message: `git remote: ${syncErrorGuidance(new Error(this.safeError(error)))}`,
 			});
 		}
 		return diagnostics;
@@ -547,12 +562,14 @@ export class GitSyncBackend implements SyncBackend {
 				try {
 					recreate = !(await this.cacheUsesSha1(signal));
 				} catch {
+					throwIfAborted(signal);
 					recreate = true;
 				}
 			}
 		} catch (error) {
 			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
 		}
+		throwIfAborted(signal);
 		if (recreate) await fs.rm(this.cacheDir, { recursive: true, force: true });
 		try {
 			await fs.access(this.cacheDir);
@@ -604,7 +621,7 @@ export class GitSyncBackend implements SyncBackend {
 	}
 
 	private publicationPath() {
-		return this.config.destination.directory;
+		return this.config.destination.directory === "./" ? "" : this.config.destination.directory;
 	}
 
 	private manifestPath() {
@@ -766,10 +783,12 @@ async function withGitCacheMutation<T>(
 	signal?: AbortSignal,
 ): Promise<T> {
 	const previous = gitCacheMutationQueues.get(cacheDir) ?? Promise.resolve();
+	let started = false;
 	const operation = previous
 		.catch(() => undefined)
 		.then(() => {
 			throwIfAborted(signal);
+			started = true;
 			return run();
 		});
 	const tail = operation.then(
@@ -791,6 +810,11 @@ async function withGitCacheMutation<T>(
 	if (signal.aborted) onAbort();
 	try {
 		return await Promise.race([operation, aborted]);
+	} catch (error) {
+		// A queued job can cancel immediately, but a running job owns a child/cache
+		// mutation. Drain its bounded cleanup before releasing outer sync guards.
+		if (started) await tail;
+		throw error;
 	} finally {
 		signal.removeEventListener("abort", onAbort);
 	}

package/src/{git-config.ts → backends/git/git-config.ts}

@@ -88,6 +88,7 @@ export function normalizeGitBranch(value: string | undefined) {
 }
 
 export function normalizeGitDirectory(value: string | undefined) {
+	if (value?.trim() === "." || value?.trim() === "./") return "./";
 	const directory = trimSlashes(normalizeOptionalString(value) ?? DEFAULT_GIT_DIRECTORY);
 	if (
 		!directory ||

package/src/{git-storage.ts → backends/git/git-storage.ts}

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
-import { portableSnapshotSelection, snapshotSelectionInclude } from "./sync-policy.js";
-import type { Snapshot, SnapshotSelection } from "./types.js";
+import type { Snapshot, SnapshotSelection } from "../../snapshot/snapshot-types.js";
+import { portableSnapshotSelection, snapshotSelectionInclude } from "../../sync/sync-policy.js";
 
 export const GIT_MANIFEST_VERSION = 2;
 export const MAX_GIT_MANIFEST_BYTES = 1024 * 1024;

package/src/{s3-backend.ts → backends/s3/s3-backend.ts}

@@ -1,8 +1,11 @@
 import { createHash } from "node:crypto";
-import { sessionTokenWarnings } from "./config.js";
-import { encodeKey, posixJoin } from "./paths.js";
-import { S3Client, S3ObjectAlreadyExistsError } from "./s3-client.js";
-import { decodeSnapshot, encodeSnapshot } from "./snapshot-codec.js";
+import { encodeKey, posixJoin } from "../../paths.js";
+import { sessionTokenWarnings } from "../../settings/config.js";
+import { decodeSnapshot, encodeSnapshot } from "../../snapshot/snapshot-codec.js";
+import type { Snapshot } from "../../snapshot/snapshot-types.js";
+import { syncErrorGuidance } from "../../sync/sync-error-guidance.js";
+import { portableSnapshotSelection } from "../../sync/sync-policy.js";
+import type { LatestPointer, RemoteObject, ResolvedS3Backend } from "../backend-types.js";
 import {
 	type BackendDiagnostic,
 	type ExpectedRemoteHead,
@@ -13,9 +16,8 @@ import {
 	type SyncBackend,
 	SyncBackendConflictError,
 	SyncBackendPublicationOutcomeUnknownError,
-} from "./sync-backend.js";
-import { portableSnapshotSelection } from "./sync-policy.js";
-import type { LatestPointer, RemoteObject, ResolvedS3Backend, Snapshot } from "./types.js";
+} from "../sync-backend.js";
+import { S3Client, S3ObjectAlreadyExistsError } from "./s3-client.js";
 
 const VERSION = 1;
 const POST_COMMIT_TIMEOUT_MS = 30_000;
@@ -189,7 +191,7 @@ export class S3SyncBackend implements SyncBackend {
 
 	async diagnose(signal?: AbortSignal): Promise<BackendDiagnostic[]> {
 		throwIfAborted(signal);
-		return [
+		const diagnostics: BackendDiagnostic[] = [
 			{
 				key: "s3-config",
 				level: "info",
@@ -201,6 +203,39 @@ export class S3SyncBackend implements SyncBackend {
 				message,
 			})),
 		];
+		const deadline = AbortSignal.timeout(10_000);
+		const probeSignal = signal ? AbortSignal.any([signal, deadline]) : deadline;
+		try {
+			const result = await new S3Client(this.config, probeSignal).diagnoseRead(
+				latestKey(this.config),
+			);
+			throwIfAborted(probeSignal);
+			const messages = {
+				readable:
+					"s3 remote read: HTTP success. Snapshot contents and write access are not tested.",
+				"missing-key":
+					"s3 remote read: no snapshot at this path (NoSuchKey). Write access is not tested; verify the bucket and path before first sync.",
+				"missing-bucket":
+					"s3 remote read: bucket not found (NoSuchBucket). Create the bucket with your provider or edit the setup's bucket name.",
+				"unknown-404":
+					"s3 remote read: HTTP 404; cannot confirm whether the bucket or snapshot is missing. Verify the endpoint, bucket, and path with your provider. Write access is not tested.",
+			};
+			diagnostics.push({
+				key: "s3-read",
+				level: result === "readable" ? "info" : "warning",
+				message: messages[result],
+			});
+		} catch (error) {
+			throwIfAborted(signal);
+			diagnostics.push({
+				key: "s3-read",
+				level: "warning",
+				message: syncErrorGuidance(
+					deadline.aborted ? new Error("S3 diagnostic request timed out.") : error,
+				),
+			});
+		}
+		return diagnostics;
 	}
 
 	private async resolveChecksum(reference: string, signal?: AbortSignal) {
@@ -257,7 +292,7 @@ export function snapshotKey(config: ResolvedS3Backend, id: string) {
 }
 
 export function storageRoot(config: ResolvedS3Backend) {
-	return config.destination.prefix;
+	return config.destination.prefix === "./" ? "" : config.destination.prefix;
 }
 
 export function pointerFor(
@@ -444,6 +479,7 @@ function assertSafeDestination(config: ResolvedS3Backend) {
 		["prefix", config.destination.prefix, true],
 		["namespace", config.destination.namespace, false],
 	] as const) {
+		if (label === "prefix" && value === "./") continue;
 		if (
 			(!allowEmpty && value.length === 0) ||
 			value.includes("\\") ||

package/src/{s3-client.ts → backends/s3/s3-client.ts}

@@ -1,7 +1,7 @@
 import { createHash, createHmac } from "node:crypto";
 import { setTimeout as sleep } from "node:timers/promises";
-import { encodeKey, posixJoin } from "./paths.js";
-import type { RemoteObject, ResolvedS3Backend } from "./types.js";
+import { encodeKey, posixJoin } from "../../paths.js";
+import type { RemoteObject, ResolvedS3Backend } from "../backend-types.js";
 
 const MAX_JSON_RESPONSE_BYTES = 1024 * 1024;
 const MAX_SNAPSHOT_RESPONSE_BYTES = 256 * 1024 * 1024;
@@ -32,6 +32,16 @@ export class S3ObjectAlreadyExistsError extends Error {
 	}
 }
 
+export class S3HttpError extends Error {
+	constructor(
+		message: string,
+		readonly status: number,
+	) {
+		super(message);
+		this.name = "S3HttpError";
+	}
+}
+
 export class S3Client {
 	private config: ResolvedS3Backend;
 	private endpoint: URL;
@@ -50,6 +60,28 @@ export class S3Client {
 		this.requestTimeoutMs = requestTimeoutMs;
 	}
 
+	/** Read-only access probe. A bare 404 cannot distinguish a missing key from a missing bucket. */
+	async diagnoseRead(
+		key: string,
+	): Promise<"readable" | "missing-key" | "missing-bucket" | "unknown-404"> {
+		this.signal?.throwIfAborted();
+		const response = await this.request("GET", key);
+		if (response.ok) {
+			await response.body?.cancel();
+			this.signal?.throwIfAborted();
+			return "readable";
+		}
+		const detail = await this.readErrorText(response);
+		this.signal?.throwIfAborted();
+		if (response.status === 404) {
+			const code = /<Code>\s*([A-Za-z]+)\s*<\/Code>/u.exec(detail)?.[1];
+			if (code === "NoSuchBucket") return "missing-bucket";
+			if (code === "NoSuchKey") return "missing-key";
+			return "unknown-404";
+		}
+		throw new S3HttpError(`S3 remote read failed (HTTP ${response.status}).`, response.status);
+	}
+
 	async getJson<T>(key: string): Promise<RemoteObject<T>> {
 		const maxAttempts = 3;
 		let lastError: unknown;
@@ -57,7 +89,10 @@ export class S3Client {
 			const object = await this.request("GET", key);
 			if (object.status === 404) return { missing: true };
 			if (!object.ok) {
-				throw new Error(`S3 GET failed (${object.status}): ${await this.readErrorText(object)}`);
+				throw new S3HttpError(
+					`S3 GET failed (${object.status}): ${await this.readErrorText(object)}`,
+					object.status,
+				);
 			}
 			const body = await readBoundedText(object, MAX_JSON_RESPONSE_BYTES, "S3 JSON response");
 			// R2 can intermittently return an empty 200 body (read-after-write
@@ -87,7 +122,10 @@ export class S3Client {
 			const object = await this.request("GET", key);
 			if (object.status === 404) return { missing: true };
 			if (!object.ok) {
-				throw new Error(`S3 GET failed (${object.status}): ${await this.readErrorText(object)}`);
+				throw new S3HttpError(
+					`S3 GET failed (${object.status}): ${await this.readErrorText(object)}`,
+					object.status,
+				);
 			}
 			const buffer = await readBoundedBuffer(
 				object,
@@ -130,7 +168,10 @@ export class S3Client {
 			throw new S3ObjectAlreadyExistsError(key);
 		}
 		if (!response.ok) {
-			throw new Error(`S3 PUT failed (${response.status}): ${await this.readErrorText(response)}`);
+			throw new S3HttpError(
+				`S3 PUT failed (${response.status}): ${await this.readErrorText(response)}`,
+				response.status,
+			);
 		}
 	}
 
@@ -173,8 +214,13 @@ export class S3Client {
 			? undefined
 			: this.config.profile.sessionToken;
 		const response = await send(sessionToken);
-		if (!(await this.shouldRetryWithoutSessionToken(response, sessionToken))) return response;
-
+		try {
+			if (!(await this.shouldRetryWithoutSessionToken(response, sessionToken))) return response;
+		} catch (error) {
+			await response.body?.cancel().catch(() => undefined);
+			throw error;
+		}
+		await response.body?.cancel();
 		const retry = await send(undefined);
 		if (retry.ok || retry.status === 404) this.omitSessionTokenAfterRejection = true;
 		return retry;
@@ -246,6 +292,8 @@ async function readBoundedText(response: Response, limit: number, label: string)
 async function readBoundedBuffer(response: Response, limit: number, label: string) {
 	const contentLength = Number(response.headers.get("content-length"));
 	if (Number.isFinite(contentLength) && contentLength > limit) {
+		// Do not await cancellation of a cloned stream before its sibling can be released.
+		void response.body?.cancel().catch(() => undefined);
 		throw new Error(`${label} exceeds the ${limit}-byte limit.`);
 	}
 	if (!response.body) return Buffer.alloc(0);
@@ -258,7 +306,7 @@ async function readBoundedBuffer(response: Response, limit: number, label: strin
 			if (done) break;
 			total += value.byteLength;
 			if (total > limit) {
-				await reader.cancel().catch(() => undefined);
+				void reader.cancel().catch(() => undefined);
 				throw new Error(`${label} exceeds the ${limit}-byte limit.`);
 			}
 			chunks.push(Buffer.from(value));

package/src/{sync-backend.ts → backends/sync-backend.ts}

@@ -1,4 +1,4 @@
-import type { Snapshot, SnapshotSelection } from "./types.js";
+import type { Snapshot, SnapshotSelection } from "../snapshot/snapshot-types.js";
 
 export type PublicationCapability =
 	| "read-check-write-verify"

package/src/{webdav-backend.ts → backends/webdav/webdav-backend.ts}

@@ -1,5 +1,9 @@
 import { createHash, randomUUID } from "node:crypto";
-import { decodeSnapshot, encodeSnapshot } from "./snapshot-codec.js";
+import { decodeSnapshot, encodeSnapshot } from "../../snapshot/snapshot-codec.js";
+import type { Snapshot } from "../../snapshot/snapshot-types.js";
+import { syncErrorGuidance } from "../../sync/sync-error-guidance.js";
+import { portableSnapshotSelection } from "../../sync/sync-policy.js";
+import type { LatestPointer, RemoteObject, ResolvedWebDavBackend } from "../backend-types.js";
 import {
 	type BackendDiagnostic,
 	type ExpectedRemoteHead,
@@ -10,9 +14,7 @@ import {
 	type SyncBackend,
 	SyncBackendConflictError,
 	SyncBackendPublicationOutcomeUnknownError,
-} from "./sync-backend.js";
-import { portableSnapshotSelection } from "./sync-policy.js";
-import type { LatestPointer, RemoteObject, ResolvedWebDavBackend, Snapshot } from "./types.js";
+} from "../sync-backend.js";
 import { WebDavClient, WebDavHttpError, WebDavPreconditionError } from "./webdav-client.js";
 
 const VERSION = 1;
@@ -198,6 +200,12 @@ export class WebDavSyncBackend implements SyncBackend {
 				level: "info",
 				message: `webdav URL/TLS/auth: configured (${webDavStorageLocation(this.config)})`,
 			},
+			{
+				key: "webdav-scope",
+				level: "info",
+				message:
+					"webdav check scope: temporary write/delete probe; repair the active snapshot's history entry if missing. No local content is applied.",
+			},
 		];
 		try {
 			await this.runCapabilityProbe(signal);
@@ -217,7 +225,7 @@ export class WebDavSyncBackend implements SyncBackend {
 			diagnostics.push({
 				key: "webdav-probe",
 				level: "error",
-				message: `webdav publication is read-only until diagnostics pass: ${errorMessage(error)}`,
+				message: `webdav publication is read-only until diagnostics pass: ${syncErrorGuidance(error)}`,
 			});
 			return diagnostics;
 		}
@@ -232,7 +240,7 @@ export class WebDavSyncBackend implements SyncBackend {
 			diagnostics.push({
 				key: "webdav-history",
 				level: "error",
-				message: `webdav history repair failed: ${errorMessage(error)}`,
+				message: `webdav history repair failed: ${syncErrorGuidance(error)}`,
 			});
 		}
 		return diagnostics;
@@ -250,7 +258,7 @@ export class WebDavSyncBackend implements SyncBackend {
 
 	private async runCapabilityProbe(signal?: AbortSignal) {
 		throwIfAborted(signal);
-		const probeCollection = `${rootPath(this.config)}/.pi-sync-probes/${randomUUID()}`;
+		const probeCollection = joinRemote(rootPath(this.config), ".pi-sync-probes", randomUUID());
 		const probe = `${probeCollection}/conditional.txt`;
 		const client = new WebDavClient(this.config, signal);
 		let created = false;
@@ -382,7 +390,7 @@ export class WebDavSyncBackend implements SyncBackend {
 }
 
 export function rootPath(config: ResolvedWebDavBackend) {
-	return config.destination.path;
+	return config.destination.path === "./" ? "" : config.destination.path;
 }
 
 export function latestPath(config: ResolvedWebDavBackend) {
@@ -410,7 +418,7 @@ export function webDavBackendIdentity(config: ResolvedWebDavBackend) {
 
 function webDavStorageLocation(config: ResolvedWebDavBackend) {
 	const url = new URL(secretFreeUrl(config.profile.url));
-	return `${url.host} · ${rootPath(config)}`;
+	return `${url.host} · ${config.destination.path}`;
 }
 
 function pointerFor(
@@ -586,7 +594,11 @@ function assertSafeDestination(config: ResolvedWebDavBackend) {
 	const url = new URL(config.profile.url);
 	if (url.username || url.password || url.search || url.hash)
 		throw new Error("Invalid WebDAV URL.");
-	for (const value of [config.destination.path, config.destination.namespace]) {
+	for (const [label, value] of [
+		["path", config.destination.path],
+		["namespace", config.destination.namespace],
+	]) {
+		if (label === "path" && value === "./") continue;
 		if (
 			!value ||
 			value.includes("\\") ||

package/src/{webdav-client.ts → backends/webdav/webdav-client.ts}

@@ -1,5 +1,5 @@
 import { XMLParser } from "fast-xml-parser";
-import type { RemoteObject, ResolvedWebDavBackend } from "./types.js";
+import type { RemoteObject, ResolvedWebDavBackend } from "../backend-types.js";
 
 const JSON_LIMIT = 1024 * 1024;
 const ERROR_LIMIT = 64 * 1024;

package/src/{webdav-config.ts → backends/webdav/webdav-config.ts}

@@ -41,6 +41,7 @@ export function normalizeWebDavUrl(value: string | undefined) {
 }
 
 export function normalizeWebDavPath(value: string | undefined) {
+	if (value?.trim() === "." || value?.trim() === "./") return "./";
 	const normalized = trimSlashes(normalizeOptionalString(value) ?? DEFAULT_PATH);
 	if (
 		!normalized ||