@backblaze-labs/b2-sdk 0.3.0 → 0.4.0

package/dist/sync/scanners/local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../src/sync/scanners/local.js"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,aAAa,EAAkB,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AA0B7F;;;;;;;;GAQG;AACH,qBAAa,WAAY,YAAW,UAAU;IAC5C,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAS;IAChC,QAAQ,CAAC,kBAAkB,EAAG,IAAI,CAAS;IAC3C,QAAQ,CAAC,kBAAkB,EAAG,IAAI,CAAS;IAC3C,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;OAGG;gBACS,IAAI,EAAE,MAAM;IAKxB;;;OAGG;IACI,IAAI,CAAC,OAAO,GAAE,eAAoB,GAAG,cAAc,CAAC,aAAa,CAAC;IAazE;;;;;;;;OAQG;YACW,IAAI;IA8FlB,OAAO,CAAC,aAAa;CAetB"}
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../src/sync/scanners/local.js"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,aAAa,EAAkB,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AA+B7F;;;;;;;;GAQG;AACH,qBAAa,WAAY,YAAW,UAAU;IAC5C,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAS;IAChC,QAAQ,CAAC,kBAAkB,EAAG,IAAI,CAAS;IAC3C,QAAQ,CAAC,kBAAkB,EAAG,IAAI,CAAS;IAC3C,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;OAGG;gBACS,IAAI,EAAE,MAAM;IAKxB;;;OAGG;IACI,IAAI,CAAC,OAAO,GAAE,eAAoB,GAAG,cAAc,CAAC,aAAa,CAAC;IAqCzE;;;;;;;;;;;OAWG;YACW,IAAI;YAuFJ,aAAa;YA4Db,WAAW;YA4CX,aAAa;IAuF3B,OAAO,CAAC,aAAa;CAetB"}

package/dist/sync/scanners/local.js

@@ -4,9 +4,9 @@ import { directoryMayContainSyncPaths, pathPassesSyncFilters, pathSkippedByRegEx
 import { compareSyncRelativePaths } from "../path-order.js";
 import { assertScanEntryLimit, scanEntryLimit } from "../scan-limit.js";
 import { localFileIdentityFromStats } from "../local-file-identity.js";
+import { localFilesystemErrorReason } from "../filesystem-errors.js";
 import { isReservedSyncTempFileName } from "../path-safety.js";
 import { isDownloadStagingDirectorySegment, isManagedDownloadStagingRoot } from "../download-staging.js";
-import { localFilesystemErrorReason } from "../filesystem-errors.js";
 import { registerLocalFilesystemRoot } from "../local-filesystem-root.js";
 //#region src/sync/scanners/local.ts
 /**
@@ -40,8 +40,17 @@ var LocalFolder = class {
 		validateSyncFilters(options);
 		const nodeDeps = await loadLocalNodeDeps();
 		const root = nodeDeps.resolve(this.root);
+		const followSymlinks = options.localSymlinks === "follow" && options.requireLocalSafePaths !== true;
+		let scanRoot = root;
 		const collected = [];
-		await this.walk(root, root, collected, options, scanEntryLimit(options), nodeDeps);
+		const activeDirectoryIds = /* @__PURE__ */ new Set();
+		const followedDirectoryIds = /* @__PURE__ */ new Set();
+		if (followSymlinks) try {
+			scanRoot = await nodeDeps.realpath(root);
+			const rootStats = await nodeDeps.stat(scanRoot);
+			if (rootStats.isDirectory()) activeDirectoryIds.add(localNodeIdentity(rootStats));
+		} catch {}
+		await this.walk(scanRoot, scanRoot, "", collected, options, scanEntryLimit(options), nodeDeps, activeDirectoryIds, followedDirectoryIds);
 		collected.sort((a, b) => compareSyncRelativePaths(a.relativePath, b.relativePath));
 		for (const entry of collected) {
 			throwIfScanAborted(options);
@@ -52,25 +61,28 @@ var LocalFolder = class {
 	* Recursively collects files from {@link dir} into {@link out}.
 	* @param root - Resolved scan root used for relative path calculation.
 	* @param dir - Absolute path of the directory to scan.
+	* @param dirRel - Sync-relative path represented by {@link dir}.
 	* @param out - Accumulator array that receives discovered file entries.
 	* @param options - Optional scan controls.
 	* @param maxScanEntries - Maximum number of entries to retain before failing.
 	* @param nodeDeps - Lazy-loaded Node filesystem and path helpers.
+	* @param activeDirectoryIds - Directory identities in the current recursion stack.
+	* @param followedDirectoryIds - Followed symlink directory identities already traversed.
 	*/
-	async walk(root, dir, out, options, maxScanEntries, nodeDeps) {
+	async walk(root, dir, dirRel, out, options, maxScanEntries, nodeDeps, activeDirectoryIds, followedDirectoryIds) {
 		throwIfScanAborted(options);
 		let entries;
 		try {
 			entries = await nodeDeps.readdir(dir, { withFileTypes: true });
 		} catch (err) {
-			const error = this.emitScanError(options, relativePathFromRoot(root, dir, nodeDeps), "directory", err);
+			const error = this.emitScanError(options, dirRel, "directory", err);
 			if (dir === root) throw error;
 			return;
 		}
 		for (const entry of entries) {
 			throwIfScanAborted(options);
 			const fullPath = nodeDeps.join(dir, entry.name);
-			const rel = relativePathFromRoot(root, fullPath, nodeDeps);
+			const rel = joinSyncRelativePath(dirRel, entry.name);
 			if (isDownloadStagingDirectorySegment(rel) && entry.isDirectory() && isDownloadStagingDirectorySegment(entry.name) && await isManagedDownloadStagingRoot(fullPath)) continue;
 			if (rel.includes("\\")) {
 				emitScannerSkip(options, {
@@ -93,35 +105,130 @@ var LocalFolder = class {
 				continue;
 			}
 			if (entry.isDirectory()) {
-				if (directoryMayContainSyncPaths(rel, options)) await this.walk(root, fullPath, out, options, maxScanEntries, nodeDeps);
-			} else if (entry.isFile()) {
-				if (!pathPassesSyncFilters(rel, options)) {
-					if (pathSkippedByRegExpInputLimit(rel, options)) emitScannerSkip(options, regexpInputTooLongSkip(rel));
-					continue;
-				}
-				let s;
-				try {
-					s = await nodeDeps.lstat(fullPath);
-					/* v8 ignore start -- lstat race after a Dirent file result is not deterministic */
-					if (!s.isFile()) {
-						this.emitScanError(options, rel, "file", /* @__PURE__ */ new Error("not a regular file"));
-						continue;
-					}
-				} catch (err) {
-					/* v8 ignore next -- stat TOCTOU failures are not deterministic to trigger */
-					this.emitScanError(options, relativePathFromRoot(root, fullPath, nodeDeps), "file", err);
-					continue;
+				if (directoryMayContainSyncPaths(rel, options)) await this.walkDirectory(root, fullPath, rel, out, options, maxScanEntries, nodeDeps, activeDirectoryIds, followedDirectoryIds);
+			} else if (entry.isFile()) await this.collectFile(fullPath, rel, out, options, maxScanEntries, nodeDeps);
+			else if (entry.isSymbolicLink()) await this.handleSymlink(root, fullPath, rel, out, options, maxScanEntries, nodeDeps, activeDirectoryIds, followedDirectoryIds);
+		}
+	}
+	async walkDirectory(root, dir, rel, out, options, maxScanEntries, nodeDeps, activeDirectoryIds, followedDirectoryIds, knownStats) {
+		let stats = knownStats;
+		if (stats === void 0) try {
+			stats = await nodeDeps.stat(dir);
+		} catch (err) {
+			/* v8 ignore start -- stat TOCTOU failures after a Dirent directory result are not deterministic */
+			this.emitScanError(options, rel, "directory", err);
+			return;
+		}
+		/* v8 ignore start -- stat TOCTOU races after a Dirent directory result are not deterministic */
+		if (!stats.isDirectory()) {
+			this.emitScanError(options, rel, "directory", /* @__PURE__ */ new Error("not a directory"));
+			return;
+		}
+		/* v8 ignore stop */
+		const identity = localNodeIdentity(stats);
+		if (activeDirectoryIds.has(identity)) {
+			emitScannerSkip(options, {
+				type: "skip",
+				path: rel,
+				size: 0,
+				reason: "local-symlink-loop",
+				message: `Skipped local path ${JSON.stringify(rel)}: symlink would revisit an ancestor directory`
+			});
+			return;
+		}
+		activeDirectoryIds.add(identity);
+		try {
+			await this.walk(root, dir, rel, out, options, maxScanEntries, nodeDeps, activeDirectoryIds, followedDirectoryIds);
+		} finally {
+			activeDirectoryIds.delete(identity);
+		}
+	}
+	async collectFile(fullPath, rel, out, options, maxScanEntries, nodeDeps, knownStats) {
+		if (!pathPassesSyncFilters(rel, options)) {
+			if (pathSkippedByRegExpInputLimit(rel, options)) emitScannerSkip(options, regexpInputTooLongSkip(rel));
+			return;
+		}
+		let s = knownStats;
+		if (s === void 0) try {
+			s = await nodeDeps.lstat(fullPath);
+			/* v8 ignore start -- lstat race after a Dirent file result is not deterministic */
+			if (!s.isFile()) {
+				this.emitScanError(options, rel, "file", /* @__PURE__ */ new Error("not a regular file"));
+				return;
+			}
+		} catch (err) {
+			/* v8 ignore start -- stat TOCTOU failures are not deterministic to trigger */
+			this.emitScanError(options, rel, "file", err);
+			return;
+		}
+		assertScanEntryLimit(out.length + 1, maxScanEntries);
+		out.push({
+			relativePath: rel,
+			absolutePath: fullPath,
+			modTimeMillis: Math.floor(s.mtimeMs),
+			size: s.size,
+			fileIdentity: localFileIdentityFromStats(s)
+		});
+	}
+	async handleSymlink(root, fullPath, rel, out, options, maxScanEntries, nodeDeps, activeDirectoryIds, followedDirectoryIds) {
+		if ((options.localSymlinks ?? "skip") === "skip" || options.requireLocalSafePaths === true) {
+			emitScannerSkip(options, {
+				type: "skip",
+				path: rel,
+				size: 0,
+				reason: "local-symlink",
+				message: `Skipped local path ${JSON.stringify(rel)}: local symlinks are disabled`
+			});
+			return;
+		}
+		let targetPath;
+		let targetStats;
+		try {
+			targetPath = await nodeDeps.realpath(fullPath);
+			targetStats = await nodeDeps.stat(targetPath);
+		} catch (err) {
+			this.emitScanError(options, rel, "symlink", err);
+			return;
+		}
+		if (!isPathInsideRoot(root, targetPath, nodeDeps)) {
+			emitScannerSkip(options, {
+				type: "skip",
+				path: rel,
+				size: 0,
+				reason: "local-symlink",
+				message: `Skipped local path ${JSON.stringify(rel)}: symlink target is outside the sync root`
+			});
+			return;
+		}
+		if (targetStats.isDirectory()) {
+			if (directoryMayContainSyncPaths(rel, options)) {
+				const identity = localNodeIdentity(targetStats);
+				if (followedDirectoryIds.has(identity)) {
+					emitScannerSkip(options, {
+						type: "skip",
+						path: rel,
+						size: 0,
+						reason: "local-symlink-loop",
+						message: `Skipped local path ${JSON.stringify(rel)}: symlink target was already visited`
+					});
+					return;
 				}
-				assertScanEntryLimit(out.length + 1, maxScanEntries);
-				out.push({
-					relativePath: rel,
-					absolutePath: fullPath,
-					modTimeMillis: Math.floor(s.mtimeMs),
-					size: s.size,
-					fileIdentity: localFileIdentityFromStats(s)
-				});
+				followedDirectoryIds.add(identity);
+				await this.walkDirectory(root, targetPath, rel, out, options, maxScanEntries, nodeDeps, activeDirectoryIds, followedDirectoryIds, targetStats);
 			}
+			return;
 		}
+		if (targetStats.isFile()) {
+			await this.collectFile(targetPath, rel, out, options, maxScanEntries, nodeDeps, targetStats);
+			return;
+		}
+		emitScannerSkip(options, {
+			type: "skip",
+			path: rel,
+			size: 0,
+			reason: "local-symlink",
+			message: `Skipped local path ${JSON.stringify(rel)}: symlink target is not a regular file or directory`
+		});
 	}
 	emitScanError(options, path, kind, err) {
 		const event = {
@@ -139,9 +246,12 @@ async function loadLocalNodeDeps() {
 	return {
 		readdir: fsPromises.readdir,
 		lstat: fsPromises.lstat,
+		stat: fsPromises.stat,
 		join: path.join,
 		relative: path.relative,
+		realpath: fsPromises.realpath,
 		resolve: path.resolve,
+		isAbsolute: path.isAbsolute,
 		sep: path.sep
 	};
 }
@@ -205,8 +315,15 @@ function normalizePathSegments(segments, separator) {
 	}
 	return out.join(separator);
 }
-function relativePathFromRoot(root, path, nodeDeps) {
-	return nodeDeps.relative(root, path).split(nodeDeps.sep).join("/");
+function joinSyncRelativePath(parent, child) {
+	return parent === "" ? child : `${parent}/${child}`;
+}
+function isPathInsideRoot(root, path, nodeDeps) {
+	const rel = nodeDeps.relative(root, path);
+	return rel === "" || !rel.startsWith(`..${nodeDeps.sep}`) && rel !== ".." && !nodeDeps.isAbsolute(rel);
+}
+function localNodeIdentity(stats) {
+	return `${stats.dev}:${stats.ino}`;
 }
 function throwIfScanAborted(options) {
 	if (options.signal?.aborted === true) throw options.signal.reason ?? new DOMException("Aborted", "AbortError");

package/dist/sync/scanners/local.js.map

@@ -1 +1 @@
-{"version":3,"file":"local.js","names":[],"sources":["../../../src/sync/scanners/local.ts"],"sourcesContent":["import {\n  isDownloadStagingDirectorySegment,\n  isManagedDownloadStagingRoot,\n} from '../download-staging.ts'\nimport { localFilesystemErrorReason } from '../filesystem-errors.ts'\nimport {\n  directoryMayContainSyncPaths,\n  pathPassesSyncFilters,\n  pathSkippedByRegExpInputLimit,\n} from '../filters.ts'\nimport { localFileIdentityFromStats } from '../local-file-identity.ts'\nimport { registerLocalFilesystemRoot } from '../local-filesystem-root.ts'\nimport { compareSyncRelativePaths } from '../path-order.ts'\nimport { isReservedSyncTempFileName } from '../path-safety.ts'\nimport { validateSyncFilters } from '../regexp-safety.ts'\nimport { emitScannerSkip, regexpInputTooLongSkip } from '../scan-events.ts'\nimport { assertScanEntryLimit, scanEntryLimit } from '../scan-limit.ts'\nimport type { LocalSyncPath, SyncErrorEvent, SyncFolder, SyncScanOptions } from '../types.ts'\n\ntype LocalDirent = {\n  readonly name: string\n  isDirectory(): boolean\n  isFile(): boolean\n}\n\ntype LocalStats = {\n  readonly dev: number\n  readonly ino: number\n  readonly mtimeMs: number\n  readonly ctimeMs: number\n  readonly size: number\n  isFile(): boolean\n}\n\ntype LocalNodeDeps = {\n  readdir(path: string, options: { readonly withFileTypes: true }): Promise<LocalDirent[]>\n  lstat(path: string): Promise<LocalStats>\n  join(...paths: string[]): string\n  relative(from: string, to: string): string\n  resolve(...paths: string[]): string\n  sep: string\n}\n\n/**\n * Scans a local directory tree and yields {@link LocalSyncPath} entries sorted by relative path.\n * A root directory read failure aborts the scan with an error diagnostic. Per-entry file or\n * directory failures are reported through `onError` and the scan continues over readable siblings.\n * SDK-managed partial download file names are skipped so unfinished internal\n * temp files are not synchronized.\n * The current implementation collects matching entries before sorting, so memory usage is\n * proportional to the number of matched files.\n */\nexport class LocalFolder implements SyncFolder {\n  readonly type = 'local' as const\n  readonly appliesScanFilters = true as const\n  readonly appliesScanSorting = true as const\n  /** Resolved absolute path to the local root directory. */\n  readonly root: string\n\n  /**\n   * Creates a new LocalFolder for the given root directory.\n   * @param root - Absolute or relative path to the local directory to scan.\n   */\n  constructor(root: string) {\n    this.root = resolvePathAtConstruction(root)\n    registerLocalFilesystemRoot(this)\n  }\n\n  /**\n   * Recursively walks the directory and yields files in sync path order.\n   * @param options - Optional scan controls.\n   */\n  async *scan(options: SyncScanOptions = {}): AsyncGenerator<LocalSyncPath> {\n    validateSyncFilters(options)\n    const nodeDeps = await loadLocalNodeDeps()\n    const root = nodeDeps.resolve(this.root)\n    const collected: LocalSyncPath[] = []\n    await this.walk(root, root, collected, options, scanEntryLimit(options), nodeDeps)\n    collected.sort((a, b) => compareSyncRelativePaths(a.relativePath, b.relativePath))\n    for (const entry of collected) {\n      throwIfScanAborted(options)\n      yield entry\n    }\n  }\n\n  /**\n   * Recursively collects files from {@link dir} into {@link out}.\n   * @param root - Resolved scan root used for relative path calculation.\n   * @param dir - Absolute path of the directory to scan.\n   * @param out - Accumulator array that receives discovered file entries.\n   * @param options - Optional scan controls.\n   * @param maxScanEntries - Maximum number of entries to retain before failing.\n   * @param nodeDeps - Lazy-loaded Node filesystem and path helpers.\n   */\n  private async walk(\n    root: string,\n    dir: string,\n    out: LocalSyncPath[],\n    options: SyncScanOptions,\n    maxScanEntries: number,\n    nodeDeps: LocalNodeDeps,\n  ): Promise<void> {\n    throwIfScanAborted(options)\n    let entries: LocalDirent[]\n    try {\n      entries = await nodeDeps.readdir(dir, { withFileTypes: true })\n    } catch (err) {\n      const error = this.emitScanError(\n        options,\n        relativePathFromRoot(root, dir, nodeDeps),\n        'directory',\n        err,\n      )\n      if (dir === root) throw error\n      return\n    }\n\n    for (const entry of entries) {\n      throwIfScanAborted(options)\n      const fullPath = nodeDeps.join(dir, entry.name)\n      const rel = relativePathFromRoot(root, fullPath, nodeDeps)\n      if (\n        isDownloadStagingDirectorySegment(rel) &&\n        entry.isDirectory() &&\n        isDownloadStagingDirectorySegment(entry.name) &&\n        (await isManagedDownloadStagingRoot(fullPath))\n      ) {\n        continue\n      }\n      if (rel.includes('\\\\')) {\n        emitScannerSkip(options, {\n          type: 'skip',\n          path: rel,\n          size: 0,\n          reason: 'unsafe-name',\n          message: `Skipped local path ${JSON.stringify(rel)}: backslashes are not safe sync path characters`,\n        })\n        continue\n      }\n      if (isReservedSyncTempFileName(entry.name)) {\n        emitScannerSkip(options, {\n          type: 'skip',\n          path: rel,\n          size: 0,\n          reason: 'stale-download-partial',\n          message: `Skipped local path ${JSON.stringify(rel)}: reserved SDK partial download file`,\n        })\n        continue\n      }\n      // Symlinks, FIFOs, sockets, and device nodes are not syncable files.\n      // Ignore them without poisoning delete-mode orphan handling for unrelated paths.\n      if (entry.isDirectory()) {\n        if (directoryMayContainSyncPaths(rel, options)) {\n          await this.walk(root, fullPath, out, options, maxScanEntries, nodeDeps)\n        }\n      } else if (entry.isFile()) {\n        if (!pathPassesSyncFilters(rel, options)) {\n          if (pathSkippedByRegExpInputLimit(rel, options)) {\n            emitScannerSkip(options, regexpInputTooLongSkip(rel))\n          }\n          continue\n        }\n        let s: LocalStats\n        try {\n          s = await nodeDeps.lstat(fullPath)\n          /* v8 ignore start -- lstat race after a Dirent file result is not deterministic */\n          if (!s.isFile()) {\n            this.emitScanError(options, rel, 'file', new Error('not a regular file'))\n            continue\n          }\n          /* v8 ignore stop */\n        } catch (err) {\n          /* v8 ignore next -- stat TOCTOU failures are not deterministic to trigger */\n          this.emitScanError(options, relativePathFromRoot(root, fullPath, nodeDeps), 'file', err)\n          continue\n        }\n        assertScanEntryLimit(out.length + 1, maxScanEntries)\n        out.push({\n          relativePath: rel,\n          absolutePath: fullPath,\n          modTimeMillis: Math.floor(s.mtimeMs),\n          size: s.size,\n          fileIdentity: localFileIdentityFromStats(s),\n        })\n      }\n    }\n  }\n\n  private emitScanError(\n    options: SyncScanOptions,\n    path: string,\n    kind: 'directory' | 'file',\n    err: unknown,\n  ): Error {\n    const event: SyncErrorEvent = {\n      type: 'error',\n      path,\n      size: 0,\n      message: `failed to scan local ${kind}: ${localFilesystemErrorReason(err)}`,\n    }\n    options.onError?.(event)\n    return new Error(event.message)\n  }\n}\n\nasync function loadLocalNodeDeps(): Promise<LocalNodeDeps> {\n  const [fsPromises, path] = await Promise.all([import('node:fs/promises'), import('node:path')])\n  return {\n    readdir: fsPromises.readdir as LocalNodeDeps['readdir'],\n    lstat: fsPromises.lstat as LocalNodeDeps['lstat'],\n    join: path.join,\n    relative: path.relative,\n    resolve: path.resolve,\n    sep: path.sep,\n  }\n}\n\nfunction resolvePathAtConstruction(root: string): string {\n  const processLike = (\n    globalThis as {\n      process?: { cwd?: () => string; platform?: string }\n    }\n  ).process\n  if (typeof processLike?.cwd !== 'function') return root\n\n  const cwd = processLike.cwd()\n  if (processLike.platform === 'win32') return resolveWindowsPath(cwd, root)\n  return resolvePosixPath(cwd, root)\n}\n\nfunction resolvePosixPath(cwd: string, root: string): string {\n  const joined = root.startsWith('/') ? root : `${cwd}/${root}`\n  const resolved = normalizePathSegments(joined.split('/'), '/')\n  return resolved === '' ? '/' : `/${resolved}`\n}\n\nfunction resolveWindowsPath(cwd: string, root: string): string {\n  const normalizedRoot = root.replaceAll('/', '\\\\')\n  const normalizedCwd = cwd.replaceAll('/', '\\\\')\n  const drive = /^[A-Za-z]:/.exec(normalizedCwd)?.[0] ?? ''\n  const cwdUnc = splitUncPath(normalizedCwd)\n  if (/^\\\\\\\\/.test(normalizedRoot)) return normalizeUncPath(normalizedRoot)\n  if (/^[A-Za-z]:\\\\/.test(normalizedRoot)) {\n    const prefix = normalizedRoot.slice(0, 2)\n    const rest = normalizedRoot.slice(3).split('\\\\')\n    return joinWindowsRoot(prefix, normalizePathSegments(rest, '\\\\'))\n  }\n  if (/^[A-Za-z]:/.test(normalizedRoot)) {\n    throw new Error('LocalFolder root must not be a drive-relative Windows path')\n  }\n  if (normalizedRoot.startsWith('\\\\')) {\n    const rest = normalizePathSegments(normalizedRoot.slice(1).split('\\\\'), '\\\\')\n    return joinWindowsRoot(cwdUnc?.prefix ?? drive, rest)\n  }\n  if (cwdUnc !== undefined) {\n    const resolved = normalizePathSegments([...cwdUnc.rest, ...normalizedRoot.split('\\\\')], '\\\\')\n    return joinWindowsRoot(cwdUnc.prefix, resolved)\n  }\n  const base = /^[A-Za-z]:\\\\/.test(normalizedCwd) ? normalizedCwd : `${drive}\\\\`\n  const prefix = /^[A-Za-z]:/.exec(base)?.[0] ?? drive\n  const baseRest = base.slice(prefix.length).replace(/^\\\\/, '').split('\\\\')\n  const resolved = normalizePathSegments([...baseRest, ...normalizedRoot.split('\\\\')], '\\\\')\n  return joinWindowsRoot(prefix, resolved)\n}\n\nfunction normalizeUncPath(path: string): string {\n  const unc = splitUncPath(path)\n  if (unc === undefined) return path\n  return joinWindowsRoot(unc.prefix, normalizePathSegments(unc.rest, '\\\\'))\n}\n\nfunction splitUncPath(\n  path: string,\n): { readonly prefix: string; readonly rest: string[] } | undefined {\n  if (!path.startsWith('\\\\\\\\')) return undefined\n  const parts = path.split('\\\\').filter((part) => part !== '')\n  const [server, share, ...rest] = parts\n  if (server === undefined || share === undefined) return undefined\n  return { prefix: `\\\\\\\\${server}\\\\${share}`, rest }\n}\n\nfunction joinWindowsRoot(prefix: string, rest: string): string {\n  return rest === '' ? `${prefix}\\\\` : `${prefix}\\\\${rest}`\n}\n\nfunction normalizePathSegments(segments: readonly string[], separator: '/' | '\\\\'): string {\n  const out: string[] = []\n  for (const segment of segments) {\n    if (segment === '' || segment === '.') continue\n    if (segment === '..') {\n      out.pop()\n      continue\n    }\n    out.push(segment)\n  }\n  return out.join(separator)\n}\n\nfunction relativePathFromRoot(root: string, path: string, nodeDeps: LocalNodeDeps): string {\n  return nodeDeps.relative(root, path).split(nodeDeps.sep).join('/')\n}\n\nfunction throwIfScanAborted(options: SyncScanOptions): void {\n  if (options.signal?.aborted === true) {\n    throw options.signal.reason ?? new DOMException('Aborted', 'AbortError')\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"local.js","names":[],"sources":["../../../src/sync/scanners/local.ts"],"sourcesContent":["import {\n  isDownloadStagingDirectorySegment,\n  isManagedDownloadStagingRoot,\n} from '../download-staging.ts'\nimport { localFilesystemErrorReason } from '../filesystem-errors.ts'\nimport {\n  directoryMayContainSyncPaths,\n  pathPassesSyncFilters,\n  pathSkippedByRegExpInputLimit,\n} from '../filters.ts'\nimport { localFileIdentityFromStats } from '../local-file-identity.ts'\nimport { registerLocalFilesystemRoot } from '../local-filesystem-root.ts'\nimport { compareSyncRelativePaths } from '../path-order.ts'\nimport { isReservedSyncTempFileName } from '../path-safety.ts'\nimport { validateSyncFilters } from '../regexp-safety.ts'\nimport { emitScannerSkip, regexpInputTooLongSkip } from '../scan-events.ts'\nimport { assertScanEntryLimit, scanEntryLimit } from '../scan-limit.ts'\nimport type { LocalSyncPath, SyncErrorEvent, SyncFolder, SyncScanOptions } from '../types.ts'\n\ntype LocalDirent = {\n  readonly name: string\n  isDirectory(): boolean\n  isFile(): boolean\n  isSymbolicLink(): boolean\n}\n\ntype LocalStats = {\n  readonly dev: number\n  readonly ino: number\n  readonly mtimeMs: number\n  readonly ctimeMs: number\n  readonly size: number\n  isDirectory(): boolean\n  isFile(): boolean\n}\n\ntype LocalNodeDeps = {\n  readdir(path: string, options: { readonly withFileTypes: true }): Promise<LocalDirent[]>\n  lstat(path: string): Promise<LocalStats>\n  stat(path: string): Promise<LocalStats>\n  join(...paths: string[]): string\n  relative(from: string, to: string): string\n  realpath(path: string): Promise<string>\n  resolve(...paths: string[]): string\n  isAbsolute(path: string): boolean\n  sep: string\n}\n\n/**\n * Scans a local directory tree and yields {@link LocalSyncPath} entries sorted by relative path.\n * A root directory read failure aborts the scan with an error diagnostic. Per-entry file or\n * directory failures are reported through `onError` and the scan continues over readable siblings.\n * SDK-managed partial download file names are skipped so unfinished internal\n * temp files are not synchronized.\n * The current implementation collects matching entries before sorting, so memory usage is\n * proportional to the number of matched files.\n */\nexport class LocalFolder implements SyncFolder {\n  readonly type = 'local' as const\n  readonly appliesScanFilters = true as const\n  readonly appliesScanSorting = true as const\n  /** Resolved absolute path to the local root directory. */\n  readonly root: string\n\n  /**\n   * Creates a new LocalFolder for the given root directory.\n   * @param root - Absolute or relative path to the local directory to scan.\n   */\n  constructor(root: string) {\n    this.root = resolvePathAtConstruction(root)\n    registerLocalFilesystemRoot(this)\n  }\n\n  /**\n   * Recursively walks the directory and yields files in sync path order.\n   * @param options - Optional scan controls.\n   */\n  async *scan(options: SyncScanOptions = {}): AsyncGenerator<LocalSyncPath> {\n    validateSyncFilters(options)\n    const nodeDeps = await loadLocalNodeDeps()\n    const root = nodeDeps.resolve(this.root)\n    const followSymlinks =\n      options.localSymlinks === 'follow' && options.requireLocalSafePaths !== true\n    let scanRoot = root\n    const collected: LocalSyncPath[] = []\n    const activeDirectoryIds = new Set<string>()\n    const followedDirectoryIds = new Set<string>()\n    if (followSymlinks) {\n      try {\n        scanRoot = await nodeDeps.realpath(root)\n        const rootStats = await nodeDeps.stat(scanRoot)\n        if (rootStats.isDirectory()) activeDirectoryIds.add(localNodeIdentity(rootStats))\n      } catch {\n        // Root read errors are reported by walk(), preserving the existing diagnostic shape.\n      }\n    }\n    await this.walk(\n      scanRoot,\n      scanRoot,\n      '',\n      collected,\n      options,\n      scanEntryLimit(options),\n      nodeDeps,\n      activeDirectoryIds,\n      followedDirectoryIds,\n    )\n    collected.sort((a, b) => compareSyncRelativePaths(a.relativePath, b.relativePath))\n    for (const entry of collected) {\n      throwIfScanAborted(options)\n      yield entry\n    }\n  }\n\n  /**\n   * Recursively collects files from {@link dir} into {@link out}.\n   * @param root - Resolved scan root used for relative path calculation.\n   * @param dir - Absolute path of the directory to scan.\n   * @param dirRel - Sync-relative path represented by {@link dir}.\n   * @param out - Accumulator array that receives discovered file entries.\n   * @param options - Optional scan controls.\n   * @param maxScanEntries - Maximum number of entries to retain before failing.\n   * @param nodeDeps - Lazy-loaded Node filesystem and path helpers.\n   * @param activeDirectoryIds - Directory identities in the current recursion stack.\n   * @param followedDirectoryIds - Followed symlink directory identities already traversed.\n   */\n  private async walk(\n    root: string,\n    dir: string,\n    dirRel: string,\n    out: LocalSyncPath[],\n    options: SyncScanOptions,\n    maxScanEntries: number,\n    nodeDeps: LocalNodeDeps,\n    activeDirectoryIds: Set<string>,\n    followedDirectoryIds: Set<string>,\n  ): Promise<void> {\n    throwIfScanAborted(options)\n    let entries: LocalDirent[]\n    try {\n      entries = await nodeDeps.readdir(dir, { withFileTypes: true })\n    } catch (err) {\n      const error = this.emitScanError(options, dirRel, 'directory', err)\n      if (dir === root) throw error\n      return\n    }\n\n    for (const entry of entries) {\n      throwIfScanAborted(options)\n      const fullPath = nodeDeps.join(dir, entry.name)\n      const rel = joinSyncRelativePath(dirRel, entry.name)\n      if (\n        isDownloadStagingDirectorySegment(rel) &&\n        entry.isDirectory() &&\n        isDownloadStagingDirectorySegment(entry.name) &&\n        (await isManagedDownloadStagingRoot(fullPath))\n      ) {\n        continue\n      }\n      if (rel.includes('\\\\')) {\n        emitScannerSkip(options, {\n          type: 'skip',\n          path: rel,\n          size: 0,\n          reason: 'unsafe-name',\n          message: `Skipped local path ${JSON.stringify(rel)}: backslashes are not safe sync path characters`,\n        })\n        continue\n      }\n      if (isReservedSyncTempFileName(entry.name)) {\n        emitScannerSkip(options, {\n          type: 'skip',\n          path: rel,\n          size: 0,\n          reason: 'stale-download-partial',\n          message: `Skipped local path ${JSON.stringify(rel)}: reserved SDK partial download file`,\n        })\n        continue\n      }\n      // Symlinks, FIFOs, sockets, and device nodes are not syncable files.\n      // Ignore them without poisoning delete-mode orphan handling for unrelated paths.\n      if (entry.isDirectory()) {\n        if (directoryMayContainSyncPaths(rel, options)) {\n          await this.walkDirectory(\n            root,\n            fullPath,\n            rel,\n            out,\n            options,\n            maxScanEntries,\n            nodeDeps,\n            activeDirectoryIds,\n            followedDirectoryIds,\n          )\n        }\n      } else if (entry.isFile()) {\n        await this.collectFile(fullPath, rel, out, options, maxScanEntries, nodeDeps)\n      } else if (entry.isSymbolicLink()) {\n        await this.handleSymlink(\n          root,\n          fullPath,\n          rel,\n          out,\n          options,\n          maxScanEntries,\n          nodeDeps,\n          activeDirectoryIds,\n          followedDirectoryIds,\n        )\n      }\n    }\n  }\n\n  private async walkDirectory(\n    root: string,\n    dir: string,\n    rel: string,\n    out: LocalSyncPath[],\n    options: SyncScanOptions,\n    maxScanEntries: number,\n    nodeDeps: LocalNodeDeps,\n    activeDirectoryIds: Set<string>,\n    followedDirectoryIds: Set<string>,\n    knownStats?: LocalStats,\n  ): Promise<void> {\n    let stats = knownStats\n    if (stats === undefined) {\n      try {\n        stats = await nodeDeps.stat(dir)\n      } catch (err) {\n        /* v8 ignore start -- stat TOCTOU failures after a Dirent directory result are not deterministic */\n        this.emitScanError(options, rel, 'directory', err)\n        return\n        /* v8 ignore stop */\n      }\n    }\n    /* v8 ignore start -- stat TOCTOU races after a Dirent directory result are not deterministic */\n    if (!stats.isDirectory()) {\n      this.emitScanError(options, rel, 'directory', new Error('not a directory'))\n      return\n    }\n    /* v8 ignore stop */\n\n    const identity = localNodeIdentity(stats)\n    if (activeDirectoryIds.has(identity)) {\n      emitScannerSkip(options, {\n        type: 'skip',\n        path: rel,\n        size: 0,\n        reason: 'local-symlink-loop',\n        message: `Skipped local path ${JSON.stringify(rel)}: symlink would revisit an ancestor directory`,\n      })\n      return\n    }\n\n    activeDirectoryIds.add(identity)\n    try {\n      await this.walk(\n        root,\n        dir,\n        rel,\n        out,\n        options,\n        maxScanEntries,\n        nodeDeps,\n        activeDirectoryIds,\n        followedDirectoryIds,\n      )\n    } finally {\n      activeDirectoryIds.delete(identity)\n    }\n  }\n\n  private async collectFile(\n    fullPath: string,\n    rel: string,\n    out: LocalSyncPath[],\n    options: SyncScanOptions,\n    maxScanEntries: number,\n    nodeDeps: LocalNodeDeps,\n    knownStats?: LocalStats,\n  ): Promise<void> {\n    if (!pathPassesSyncFilters(rel, options)) {\n      if (pathSkippedByRegExpInputLimit(rel, options)) {\n        emitScannerSkip(options, regexpInputTooLongSkip(rel))\n      }\n      return\n    }\n\n    let s = knownStats\n    if (s === undefined) {\n      try {\n        s = await nodeDeps.lstat(fullPath)\n        /* v8 ignore start -- lstat race after a Dirent file result is not deterministic */\n        if (!s.isFile()) {\n          this.emitScanError(options, rel, 'file', new Error('not a regular file'))\n          return\n        }\n        /* v8 ignore stop */\n      } catch (err) {\n        /* v8 ignore start -- stat TOCTOU failures are not deterministic to trigger */\n        this.emitScanError(options, rel, 'file', err)\n        return\n        /* v8 ignore stop */\n      }\n    }\n\n    assertScanEntryLimit(out.length + 1, maxScanEntries)\n    out.push({\n      relativePath: rel,\n      absolutePath: fullPath,\n      modTimeMillis: Math.floor(s.mtimeMs),\n      size: s.size,\n      fileIdentity: localFileIdentityFromStats(s),\n    })\n  }\n\n  private async handleSymlink(\n    root: string,\n    fullPath: string,\n    rel: string,\n    out: LocalSyncPath[],\n    options: SyncScanOptions,\n    maxScanEntries: number,\n    nodeDeps: LocalNodeDeps,\n    activeDirectoryIds: Set<string>,\n    followedDirectoryIds: Set<string>,\n  ): Promise<void> {\n    if ((options.localSymlinks ?? 'skip') === 'skip' || options.requireLocalSafePaths === true) {\n      emitScannerSkip(options, {\n        type: 'skip',\n        path: rel,\n        size: 0,\n        reason: 'local-symlink',\n        message: `Skipped local path ${JSON.stringify(rel)}: local symlinks are disabled`,\n      })\n      return\n    }\n\n    let targetPath: string\n    let targetStats: LocalStats\n    try {\n      targetPath = await nodeDeps.realpath(fullPath)\n      targetStats = await nodeDeps.stat(targetPath)\n    } catch (err) {\n      this.emitScanError(options, rel, 'symlink', err)\n      return\n    }\n\n    if (!isPathInsideRoot(root, targetPath, nodeDeps)) {\n      emitScannerSkip(options, {\n        type: 'skip',\n        path: rel,\n        size: 0,\n        reason: 'local-symlink',\n        message: `Skipped local path ${JSON.stringify(rel)}: symlink target is outside the sync root`,\n      })\n      return\n    }\n\n    if (targetStats.isDirectory()) {\n      if (directoryMayContainSyncPaths(rel, options)) {\n        const identity = localNodeIdentity(targetStats)\n        if (followedDirectoryIds.has(identity)) {\n          emitScannerSkip(options, {\n            type: 'skip',\n            path: rel,\n            size: 0,\n            reason: 'local-symlink-loop',\n            message: `Skipped local path ${JSON.stringify(rel)}: symlink target was already visited`,\n          })\n          return\n        }\n        followedDirectoryIds.add(identity)\n        await this.walkDirectory(\n          root,\n          targetPath,\n          rel,\n          out,\n          options,\n          maxScanEntries,\n          nodeDeps,\n          activeDirectoryIds,\n          followedDirectoryIds,\n          targetStats,\n        )\n      }\n      return\n    }\n\n    if (targetStats.isFile()) {\n      await this.collectFile(targetPath, rel, out, options, maxScanEntries, nodeDeps, targetStats)\n      return\n    }\n\n    emitScannerSkip(options, {\n      type: 'skip',\n      path: rel,\n      size: 0,\n      reason: 'local-symlink',\n      message: `Skipped local path ${JSON.stringify(rel)}: symlink target is not a regular file or directory`,\n    })\n  }\n\n  private emitScanError(\n    options: SyncScanOptions,\n    path: string,\n    kind: 'directory' | 'file' | 'symlink',\n    err: unknown,\n  ): Error {\n    const event: SyncErrorEvent = {\n      type: 'error',\n      path,\n      size: 0,\n      message: `failed to scan local ${kind}: ${localFilesystemErrorReason(err)}`,\n    }\n    options.onError?.(event)\n    return new Error(event.message)\n  }\n}\n\nasync function loadLocalNodeDeps(): Promise<LocalNodeDeps> {\n  const [fsPromises, path] = await Promise.all([import('node:fs/promises'), import('node:path')])\n  return {\n    readdir: fsPromises.readdir as LocalNodeDeps['readdir'],\n    lstat: fsPromises.lstat as LocalNodeDeps['lstat'],\n    stat: fsPromises.stat as LocalNodeDeps['stat'],\n    join: path.join,\n    relative: path.relative,\n    realpath: fsPromises.realpath,\n    resolve: path.resolve,\n    isAbsolute: path.isAbsolute,\n    sep: path.sep,\n  }\n}\n\nfunction resolvePathAtConstruction(root: string): string {\n  const processLike = (\n    globalThis as {\n      process?: { cwd?: () => string; platform?: string }\n    }\n  ).process\n  if (typeof processLike?.cwd !== 'function') return root\n\n  const cwd = processLike.cwd()\n  if (processLike.platform === 'win32') return resolveWindowsPath(cwd, root)\n  return resolvePosixPath(cwd, root)\n}\n\nfunction resolvePosixPath(cwd: string, root: string): string {\n  const joined = root.startsWith('/') ? root : `${cwd}/${root}`\n  const resolved = normalizePathSegments(joined.split('/'), '/')\n  return resolved === '' ? '/' : `/${resolved}`\n}\n\nfunction resolveWindowsPath(cwd: string, root: string): string {\n  const normalizedRoot = root.replaceAll('/', '\\\\')\n  const normalizedCwd = cwd.replaceAll('/', '\\\\')\n  const drive = /^[A-Za-z]:/.exec(normalizedCwd)?.[0] ?? ''\n  const cwdUnc = splitUncPath(normalizedCwd)\n  if (/^\\\\\\\\/.test(normalizedRoot)) return normalizeUncPath(normalizedRoot)\n  if (/^[A-Za-z]:\\\\/.test(normalizedRoot)) {\n    const prefix = normalizedRoot.slice(0, 2)\n    const rest = normalizedRoot.slice(3).split('\\\\')\n    return joinWindowsRoot(prefix, normalizePathSegments(rest, '\\\\'))\n  }\n  if (/^[A-Za-z]:/.test(normalizedRoot)) {\n    throw new Error('LocalFolder root must not be a drive-relative Windows path')\n  }\n  if (normalizedRoot.startsWith('\\\\')) {\n    const rest = normalizePathSegments(normalizedRoot.slice(1).split('\\\\'), '\\\\')\n    return joinWindowsRoot(cwdUnc?.prefix ?? drive, rest)\n  }\n  if (cwdUnc !== undefined) {\n    const resolved = normalizePathSegments([...cwdUnc.rest, ...normalizedRoot.split('\\\\')], '\\\\')\n    return joinWindowsRoot(cwdUnc.prefix, resolved)\n  }\n  const base = /^[A-Za-z]:\\\\/.test(normalizedCwd) ? normalizedCwd : `${drive}\\\\`\n  const prefix = /^[A-Za-z]:/.exec(base)?.[0] ?? drive\n  const baseRest = base.slice(prefix.length).replace(/^\\\\/, '').split('\\\\')\n  const resolved = normalizePathSegments([...baseRest, ...normalizedRoot.split('\\\\')], '\\\\')\n  return joinWindowsRoot(prefix, resolved)\n}\n\nfunction normalizeUncPath(path: string): string {\n  const unc = splitUncPath(path)\n  if (unc === undefined) return path\n  return joinWindowsRoot(unc.prefix, normalizePathSegments(unc.rest, '\\\\'))\n}\n\nfunction splitUncPath(\n  path: string,\n): { readonly prefix: string; readonly rest: string[] } | undefined {\n  if (!path.startsWith('\\\\\\\\')) return undefined\n  const parts = path.split('\\\\').filter((part) => part !== '')\n  const [server, share, ...rest] = parts\n  if (server === undefined || share === undefined) return undefined\n  return { prefix: `\\\\\\\\${server}\\\\${share}`, rest }\n}\n\nfunction joinWindowsRoot(prefix: string, rest: string): string {\n  return rest === '' ? `${prefix}\\\\` : `${prefix}\\\\${rest}`\n}\n\nfunction normalizePathSegments(segments: readonly string[], separator: '/' | '\\\\'): string {\n  const out: string[] = []\n  for (const segment of segments) {\n    if (segment === '' || segment === '.') continue\n    if (segment === '..') {\n      out.pop()\n      continue\n    }\n    out.push(segment)\n  }\n  return out.join(separator)\n}\n\nfunction joinSyncRelativePath(parent: string, child: string): string {\n  return parent === '' ? child : `${parent}/${child}`\n}\n\nfunction isPathInsideRoot(root: string, path: string, nodeDeps: LocalNodeDeps): boolean {\n  const rel = nodeDeps.relative(root, path)\n  return (\n    rel === '' ||\n    (!rel.startsWith(`..${nodeDeps.sep}`) && rel !== '..' && !nodeDeps.isAbsolute(rel))\n  )\n}\n\nfunction localNodeIdentity(stats: LocalStats): string {\n  return `${stats.dev}:${stats.ino}`\n}\n\nfunction throwIfScanAborted(options: SyncScanOptions): void {\n  if (options.signal?.aborted === true) {\n    throw options.signal.reason ?? new DOMException('Aborted', 'AbortError')\n  }\n}\n"],"mappings":"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"}

package/dist/sync/synchronizer.cjs

@@ -7,9 +7,10 @@ const require_sha1_options = require("./sha1-options.cjs");
 const require_local_sha1 = require("./local-sha1.cjs");
 const require_compare = require("./policies/compare.cjs");
 const require_index$1 = require("./policies/index.cjs");
+const require_filesystem_errors = require("./filesystem-errors.cjs");
 const require_path_safety = require("./path-safety.cjs");
+const require_download_staging = require("./download-staging.cjs");
 const require_prefix = require("./prefix.cjs");
-const require_filesystem_errors = require("./filesystem-errors.cjs");
 const require_local_filesystem_root = require("./local-filesystem-root.cjs");
 const require_b2_sha1_reader = require("./b2-sha1-reader.cjs");
 const require_local_file_io = require("./local-file-io.cjs");
@@ -64,6 +65,7 @@ async function* synchronize(config) {
 		...options.exclude !== void 0 ? { exclude: options.exclude } : {},
 		...options.signal !== void 0 ? { signal: options.signal } : {},
 		...options.maxScanEntries !== void 0 ? { maxScanEntries: options.maxScanEntries } : {},
+		...options.localSymlinks !== void 0 ? { localSymlinks: options.localSymlinks } : {},
 		...direction === "b2-to-local" ? { requireLocalSafePaths: true } : {},
 		onError: (event) => {
 			scanHadError = true;
@@ -71,7 +73,10 @@ async function* synchronize(config) {
 			queueEvent(event);
 		}
 	};
-	const factory = createActionFactory(config, localRootContexts);
+	const downloadStagingRoots = await downloadStagingRootCleanupTargets(direction, localRootContexts);
+	const factory = createActionFactory(config, localRootContexts, { onDownloadStagingRoot(target) {
+		downloadStagingRoots.set(target.managedDirectory, target);
+	} });
 	const readB2Sha1 = dryRun ? void 0 : createB2Sha1Reader(config);
 	const actionAbortController = new AbortController();
 	const removeAbortForwarder = forwardAbortSignal(options.signal, actionAbortController);
@@ -127,6 +132,7 @@ async function* synchronize(config) {
 		if (!completed) abortActionController(actionAbortController, new DOMException("Sync iterator closed", "AbortError"));
 		removeAbortForwarder();
 		await drainActions();
+		await removeDownloadStagingRootMarkersAndDirectoriesAfterSync(downloadStagingRoots);
 	}
 	async function collectPairs() {
 		const pairs = [];
@@ -145,6 +151,7 @@ async function* synchronize(config) {
 		return pairs;
 	}
 	async function* emitSha1Batch(batch) {
+		/* v8 ignore next -- SHA-1 batches are sliced only while index is within pairs.length */
 		if (batch.length === 0) return false;
 		await drainActions();
 		yield* emitQueuedEvents();
@@ -174,6 +181,7 @@ async function* synchronize(config) {
 		return false;
 	}
 	async function processPreparedBatch(batch) {
+		/* v8 ignore next -- callers guard empty SHA-1 batches before preparing pairs */
 		if (batch.length === 0) return {
 			items: [],
 			aborted: false
@@ -201,6 +209,7 @@ async function* synchronize(config) {
 	function planPreparedPair(pair, prepared) {
 		const event = {
 			type: "compare",
+			/* v8 ignore next -- zipFolders never emits a pair with both sides absent */
 			path: (pair[0] ?? pair[1])?.relativePath ?? "",
 			size: 0,
 			bytesHashed: prepared.bytesHashed,
@@ -224,9 +233,9 @@ async function* synchronize(config) {
 			event,
 			actions: [new require_index.SkipAction(prepared.pair[1].relativePath, "not removed because scan errors occurred")]
 		};
-		if (sourceInventoryIncomplete(scanEvents) && prepared.pair[0] === null && prepared.pair[1] !== null) return {
+		if (scanEvents.sourceInventoryIncompleteMessage !== void 0 && prepared.pair[0] === null && prepared.pair[1] !== null) return {
 			event,
-			actions: [new require_index.SkipAction(prepared.pair[1].relativePath, scanEvents.sourceInventoryIncompleteMessage ?? "not removed because the source scan skipped unsafe B2 names")]
+			actions: [new require_index.SkipAction(prepared.pair[1].relativePath, scanEvents.sourceInventoryIncompleteMessage)]
 		};
 		return {
 			event,
@@ -288,6 +297,24 @@ async function* synchronize(config) {
 		while (runningActions.size > 0) await Promise.race(runningActions);
 	}
 }
+async function downloadStagingRootCleanupTargets(direction, localRootContexts) {
+	const targets = /* @__PURE__ */ new Map();
+	if (direction !== "b2-to-local" || localRootContexts.dest === void 0) return targets;
+	const target = {
+		managedDirectory: (await import("node:path")).join(localRootContexts.dest.realPath, require_download_staging.DOWNLOAD_STAGING_DIRECTORY_NAME),
+		rootRealPath: localRootContexts.dest.realPath
+	};
+	targets.set(target.managedDirectory, target);
+	return targets;
+}
+async function removeDownloadStagingRootMarkersAndDirectoriesAfterSync(targets) {
+	if (targets.size === 0) return;
+	const path = await import("node:path");
+	for (const target of targets.values()) {
+		await synchronizerTestHooks.beforeDownloadStagingRootCleanup?.(target.managedDirectory);
+		await require_download_staging.removeDownloadStagingRootMarkerAndDirectory(target.rootRealPath, target.managedDirectory, path);
+	}
+}
 /**
 * Normalizes user-provided sync concurrency before it controls compare batches and transfers.
 *
@@ -463,10 +490,11 @@ function toSseCDownloadKey(setting) {
 *
 * @param config - Synchronizer configuration containing source, destination, and options.
 * @param localRootContexts - Resolved filesystem roots captured before action creation.
+* @param lifecycleHooks - Hooks used to report action-scoped cleanup state.
 *
 * @returns An action factory bound to the provided configuration.
 */
-function createActionFactory(config, localRootContexts) {
+function createActionFactory(config, localRootContexts, lifecycleHooks = {}) {
 	const upConfig = config;
 	const downConfig = config;
 	const uploadPrefix = require_prefix.asRawB2KeyPrefix(upConfig.prefix ?? b2FolderRawPrefix(config.dest) ?? "");
@@ -481,16 +509,16 @@ function createActionFactory(config, localRootContexts) {
 				const root = rootContext?.root ?? upConfig.source.root ?? "";
 				const fileName = dest !== void 0 ? validateB2SyncPathInPrefix(uploadPrefix, dest) : `${uploadPrefix}${relPath}`;
 				if (rootContext !== void 0) await assertLocalRootContextCurrent(rootContext, relPath, { allowSymlinkRoot: true });
-				const targetPath = rootContext === void 0 ? await resolveContainedLocalPath(root, source.relativePath, absPath) : await resolveContainedLocalPath(rootContext.realPath, source.relativePath);
-				throwIfAborted(signal);
+				const targetPath = rootContext === void 0 ? await resolveContainedLocalPath(root, source.relativePath, absPath) : config.options.localSymlinks === "follow" ? await resolveContainedLocalPath(rootContext.realPath, source.relativePath, absPath) : await resolveContainedLocalPath(rootContext.realPath, source.relativePath);
+				throwIfAborted(actionSignal(signal));
 				const fileSource = await createValidatedUploadFileSource(source, targetPath);
-				throwIfAborted(signal);
+				throwIfAborted(actionSignal(signal));
 				const serverSideEncryption = config.options.encryptionProvider?.getSettingForUpload(fileName, fileSource.size);
 				await bucket.upload({
 					fileName,
 					source: fileSource,
 					...serverSideEncryption !== void 0 ? { serverSideEncryption } : {},
-					...signal !== void 0 ? { signal } : {}
+					signal: actionSignal(signal)
 				});
 			});
 		},
@@ -509,14 +537,22 @@ function createActionFactory(config, localRootContexts) {
 				const serverSideEncryption = toSseCDownloadKey(config.options.encryptionProvider?.getSettingForDownload(source.selectedVersion));
 				const result = await bucket.file(b2FileName).downloadById(source.selectedVersion.fileId, {
 					...serverSideEncryption !== void 0 ? { serverSideEncryption } : {},
-					...signal !== void 0 ? { signal } : {}
+					signal: actionSignal(signal)
 				});
 				try {
 					await require_local_file_io.writeLocalStreamInsideRoot(root, relPath, result.body, {
 						expectedBytes,
 						...scannedDest !== void 0 ? { expectedDestination: scannedDest } : {},
 						idleTimeoutMillis,
-						...signal !== void 0 ? { signal } : {}
+						...lifecycleHooks.onDownloadStagingRoot !== void 0 ? { onDownloadStagingRoot: (managedDirectory) => {
+							const rootRealPath = localRootContexts.dest?.realPath;
+							if (rootRealPath === void 0) return;
+							lifecycleHooks.onDownloadStagingRoot?.({
+								managedDirectory,
+								rootRealPath
+							});
+						} } : {},
+						signal: actionSignal(signal)
 					});
 				} catch (err) {
 					await cancelReadableStreamBody(result.body, err);
@@ -534,7 +570,7 @@ function createActionFactory(config, localRootContexts) {
 			const bucket = upConfig.bucket ?? downConfig.bucket;
 			assertBucket(bucket, "hide");
 			return new require_index.HideAction(path, async (_relPath, signal) => {
-				await bucket.hideFile(`${uploadPrefix}${path}`, signal === void 0 ? void 0 : { signal });
+				await bucket.hideFile(`${uploadPrefix}${path}`, { signal: actionSignal(signal) });
 			});
 		},
 		hideB2Path(path) {
@@ -542,7 +578,7 @@ function createActionFactory(config, localRootContexts) {
 			assertBucket(bucket, "hide");
 			const b2FileName = validateB2SyncPathInPrefix(uploadPrefix, path);
 			return new require_index.HideAction(path.relativePath, async (_relPath, signal) => {
-				await bucket.hideFile(b2FileName, signal === void 0 ? void 0 : { signal });
+				await bucket.hideFile(b2FileName, { signal: actionSignal(signal) });
 			});
 		},
 		deleteRemote(path) {
@@ -550,16 +586,16 @@ function createActionFactory(config, localRootContexts) {
 			assertBucket(bucket, "delete");
 			const b2FileName = validateB2SyncPathInPrefix(uploadPrefix, path);
 			return new require_index.DeleteRemoteAction(path.relativePath, path.selectedVersion.fileId, async (fileId$1, _fileName, signal) => {
-				await bucket.deleteFileVersion(b2FileName, require_ids.fileId(fileId$1), signal === void 0 ? void 0 : { signal });
+				await bucket.deleteFileVersion(b2FileName, require_ids.fileId(fileId$1), { signal: actionSignal(signal) });
 			});
 		},
 		deleteLocal(path) {
 			const rootContext = localRootContexts.dest;
 			const root = rootContext?.root ?? localSyncRoot(downConfig.dest);
 			return new require_index.DeleteLocalAction(path.relativePath, path.absolutePath, async (absPath, signal) => {
-				signal?.throwIfAborted();
+				actionSignal(signal).throwIfAborted();
 				if (absPath !== path.absolutePath) throw new Error(`Refusing to delete outside sync root: ${path.relativePath}`);
-				signal?.throwIfAborted();
+				actionSignal(signal).throwIfAborted();
 				try {
 					if (rootContext !== void 0) await assertLocalRootContextCurrent(rootContext, path.relativePath, { allowSymlinkRoot: false });
 					await require_local_file_io.deleteLocalFileInsideRoot(root, path);
@@ -585,7 +621,7 @@ function createActionFactory(config, localRootContexts) {
 				fileName: targetPath,
 				...destinationServerSideEncryption !== void 0 ? { destinationServerSideEncryption } : {},
 				...sourceServerSideEncryption !== void 0 ? { sourceServerSideEncryption } : {},
-				...signal !== void 0 ? { signal } : {}
+				signal: actionSignal(signal)
 			});
 		});
 	}
@@ -651,10 +687,15 @@ function validateB2SyncPathInPrefix(prefix, path, operation = "mutate") {
 function isB2SyncPath(path) {
 	return "selectedVersion" in path;
 }
+var defaultActionSignal = new AbortController().signal;
+function actionSignal(signal) {
+	return signal ?? defaultActionSignal;
+}
 function throwIfAborted(signal) {
-	if (signal?.aborted === true) throw signal.reason ?? new DOMException("Aborted", "AbortError");
+	if (signal.aborted) throw signal.reason ?? new DOMException("Aborted", "AbortError");
 }
 async function cancelReadableStreamBody(body, reason) {
+	/* v8 ignore next -- writeLocalStreamInsideRoot releases the body reader before throwing */
 	if (body.locked) return;
 	try {
 		await body.cancel(reason);
@@ -704,10 +745,7 @@ function bufferScanEvent(buffer, event, direction, scanSide) {
 	else buffer.dropped++;
 }
 function* drainScanEvents(buffer) {
-	while (buffer.events.length > 0) {
-		const event = buffer.events.shift();
-		if (event) yield event;
-	}
+	while (buffer.events.length > 0) yield buffer.events.shift();
 	if (buffer.dropped > 0) {
 		yield {
 			type: "skip",
@@ -722,9 +760,6 @@ function* drainScanEvents(buffer) {
 function scanHadFilesystemError(scanEvents) {
 	return scanEvents.fatalFilesystemErrorMessage !== void 0;
 }
-function sourceInventoryIncomplete(scanEvents) {
-	return scanEvents.sourceInventoryIncompleteMessage !== void 0;
-}
 function scanFilesystemError(scanEvents) {
 	return scanEvents.fatalFilesystemErrorMessage === void 0 ? void 0 : new Error(scanEvents.fatalFilesystemErrorMessage);
 }
@@ -743,14 +778,26 @@ function isLocalDeleteSafetyError(err) {
 }
 async function resolveContainedLocalPath(root, relativePath, absolutePath) {
 	if (root === "") throw new Error("Local sync root required for filesystem mutation");
+	const { realpath } = await import("node:fs/promises");
 	const { isAbsolute, relative, resolve, sep } = await import("node:path");
 	const safeRoot = resolve(root);
 	const target = absolutePath === void 0 ? resolve(safeRoot, relativePath) : resolve(absolutePath);
-	const pathFromRoot = relative(safeRoot, target);
+	let containmentRoot = safeRoot;
+	let pathFromRoot = relative(containmentRoot, target);
+	let escapesRoot = pathFromRoot === ".." || pathFromRoot.startsWith(`..${sep}`) || isAbsolute(pathFromRoot);
+	if (escapesRoot && absolutePath !== void 0) {
+		const realRoot = await realpath(safeRoot).catch(() => safeRoot);
+		const realPathFromRoot = relative(realRoot, target);
+		if (!(realPathFromRoot === ".." || realPathFromRoot.startsWith(`..${sep}`) || isAbsolute(realPathFromRoot))) {
+			containmentRoot = realRoot;
+			pathFromRoot = realPathFromRoot;
+			escapesRoot = false;
+		}
+	}
 	/* v8 ignore next -- defense-in-depth after prior no-follow and symlink checks. */
-	if (pathFromRoot === ".." || pathFromRoot.startsWith(`..${sep}`) || isAbsolute(pathFromRoot)) throw new Error(`Refusing to access path outside sync root: ${relativePath}`);
-	await assertLocalRootHasNoSymlink(safeRoot, relativePath);
-	await assertPathHasNoSymlinkComponents(safeRoot, pathFromRoot, relativePath);
+	if (escapesRoot) throw new Error(`Refusing to access path outside sync root: ${relativePath}`);
+	await assertLocalRootHasNoSymlink(containmentRoot, relativePath);
+	await assertPathHasNoSymlinkComponents(containmentRoot, pathFromRoot, relativePath);
 	return target;
 }
 async function assertLocalRootHasNoSymlink(safeRoot, relativePath) {