@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

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

@@ -1 +1 @@
-{"version":3,"file":"local.cjs","sources":["../../../src/sync/scanners/local.ts"],"sourcesContent":["import { readdir, stat } from 'node:fs/promises'\nimport { join, relative, sep } from 'node:path'\nimport type { LocalSyncPath, SyncFolder } from '../types.ts'\n\n/**\n * Scans a local directory tree and yields {@link LocalSyncPath} entries\n * sorted by relative path. Unreadable files and directories are silently skipped.\n */\nexport class LocalFolder implements SyncFolder {\n  readonly type = 'local' as const\n  /** 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 path to the local directory to scan.\n   */\n  constructor(root: string) {\n    this.root = root\n  }\n\n  /** Recursively walks the directory and yields files sorted by relative path. */\n  async *scan(): AsyncGenerator<LocalSyncPath> {\n    const collected: LocalSyncPath[] = []\n    await this.walk(this.root, collected)\n    collected.sort((a, b) => a.relativePath.localeCompare(b.relativePath))\n    for (const entry of collected) {\n      yield entry\n    }\n  }\n\n  /**\n   * Recursively collects files from {@link dir} into {@link out}.\n   * @param dir - Absolute path of the directory to scan.\n   * @param out - Accumulator array that receives discovered file entries.\n   */\n  private async walk(dir: string, out: LocalSyncPath[]): Promise<void> {\n    let entries: import('node:fs').Dirent[]\n    try {\n      entries = await readdir(dir, { withFileTypes: true })\n    } catch {\n      return\n    }\n\n    for (const entry of entries) {\n      const fullPath = join(dir, entry.name)\n      if (entry.isDirectory()) {\n        await this.walk(fullPath, out)\n      } else if (entry.isFile()) {\n        try {\n          const s = await stat(fullPath)\n          const rel = relative(this.root, fullPath).split(sep).join('/')\n          out.push({\n            relativePath: rel,\n            absolutePath: fullPath,\n            modTimeMillis: Math.floor(s.mtimeMs),\n            size: s.size,\n          })\n        } catch {\n          // skip unreadable files\n        }\n      }\n    }\n  }\n}\n"],"names":["readdir","join","stat","relative","sep"],"mappings":";;;;AAQO,MAAM,YAAkC;AAAA,EACpC,OAAO;AAAA;AAAA,EAEP;AAAA;AAAA;AAAA;AAAA;AAAA,EAMT,YAAY,MAAc;AACxB,SAAK,OAAO;AAAA,EACd;AAAA;AAAA,EAGA,OAAO,OAAsC;AAC3C,UAAM,YAA6B,CAAA;AACnC,UAAM,KAAK,KAAK,KAAK,MAAM,SAAS;AACpC,cAAU,KAAK,CAAC,GAAG,MAAM,EAAE,aAAa,cAAc,EAAE,YAAY,CAAC;AACrE,eAAW,SAAS,WAAW;AAC7B,YAAM;AAAA,IACR;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAc,KAAK,KAAa,KAAqC;AACnE,QAAI;AACJ,QAAI;AACF,gBAAU,MAAMA,SAAAA,QAAQ,KAAK,EAAE,eAAe,MAAM;AAAA,IACtD,QAAQ;AACN;AAAA,IACF;AAEA,eAAW,SAAS,SAAS;AAC3B,YAAM,WAAWC,UAAAA,KAAK,KAAK,MAAM,IAAI;AACrC,UAAI,MAAM,eAAe;AACvB,cAAM,KAAK,KAAK,UAAU,GAAG;AAAA,MAC/B,WAAW,MAAM,UAAU;AACzB,YAAI;AACF,gBAAM,IAAI,MAAMC,SAAAA,KAAK,QAAQ;AAC7B,gBAAM,MAAMC,UAAAA,SAAS,KAAK,MAAM,QAAQ,EAAE,MAAMC,UAAAA,GAAG,EAAE,KAAK,GAAG;AAC7D,cAAI,KAAK;AAAA,YACP,cAAc;AAAA,YACd,cAAc;AAAA,YACd,eAAe,KAAK,MAAM,EAAE,OAAO;AAAA,YACnC,MAAM,EAAE;AAAA,UAAA,CACT;AAAA,QACH,QAAQ;AAAA,QAER;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;;"}
+{"version":3,"file":"local.cjs","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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"}

package/dist/sync/scanners/local.d.cts

@@ -1,24 +1,39 @@
-import { LocalSyncPath, SyncFolder } from '../types.js';
+import { LocalSyncPath, SyncFolder, SyncScanOptions } from '../types.js';
 /**
- * Scans a local directory tree and yields {@link LocalSyncPath} entries
- * sorted by relative path. Unreadable files and directories are silently skipped.
+ * Scans a local directory tree and yields {@link LocalSyncPath} entries sorted by relative path.
+ * A root directory read failure aborts the scan with an error diagnostic. Per-entry file or
+ * directory failures are reported through `onError` and the scan continues over readable siblings.
+ * SDK-managed partial download file names are skipped so unfinished internal
+ * temp files are not synchronized.
+ * The current implementation collects matching entries before sorting, so memory usage is
+ * proportional to the number of matched files.
  */
 export declare class LocalFolder implements SyncFolder {
     readonly type: "local";
-    /** Absolute path to the local root directory. */
+    readonly appliesScanFilters: true;
+    readonly appliesScanSorting: true;
+    /** Resolved absolute path to the local root directory. */
     readonly root: string;
     /**
      * Creates a new LocalFolder for the given root directory.
-     * @param root - Absolute path to the local directory to scan.
+     * @param root - Absolute or relative path to the local directory to scan.
      */
     constructor(root: string);
-    /** Recursively walks the directory and yields files sorted by relative path. */
-    scan(): AsyncGenerator<LocalSyncPath>;
+    /**
+     * Recursively walks the directory and yields files in sync path order.
+     * @param options - Optional scan controls.
+     */
+    scan(options?: SyncScanOptions): AsyncGenerator<LocalSyncPath>;
     /**
      * 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 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.
      */
     private walk;
+    private emitScanError;
 }
 //# sourceMappingURL=local.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../src/sync/scanners/local.js"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE5D;;;GAGG;AACH,qBAAa,WAAY,YAAW,UAAU;IAC5C,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAS;IAChC,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;OAGG;gBACS,IAAI,EAAE,MAAM;IAIxB,gFAAgF;IACzE,IAAI,IAAI,cAAc,CAAC,aAAa,CAAC;IAS5C;;;;OAIG;YACW,IAAI;CA4BnB"}
+{"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"}

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

@@ -1,24 +1,39 @@
-import { LocalSyncPath, SyncFolder } from '../types.js';
+import { LocalSyncPath, SyncFolder, SyncScanOptions } from '../types.js';
 /**
- * Scans a local directory tree and yields {@link LocalSyncPath} entries
- * sorted by relative path. Unreadable files and directories are silently skipped.
+ * Scans a local directory tree and yields {@link LocalSyncPath} entries sorted by relative path.
+ * A root directory read failure aborts the scan with an error diagnostic. Per-entry file or
+ * directory failures are reported through `onError` and the scan continues over readable siblings.
+ * SDK-managed partial download file names are skipped so unfinished internal
+ * temp files are not synchronized.
+ * The current implementation collects matching entries before sorting, so memory usage is
+ * proportional to the number of matched files.
  */
 export declare class LocalFolder implements SyncFolder {
     readonly type: "local";
-    /** Absolute path to the local root directory. */
+    readonly appliesScanFilters: true;
+    readonly appliesScanSorting: true;
+    /** Resolved absolute path to the local root directory. */
     readonly root: string;
     /**
      * Creates a new LocalFolder for the given root directory.
-     * @param root - Absolute path to the local directory to scan.
+     * @param root - Absolute or relative path to the local directory to scan.
      */
     constructor(root: string);
-    /** Recursively walks the directory and yields files sorted by relative path. */
-    scan(): AsyncGenerator<LocalSyncPath>;
+    /**
+     * Recursively walks the directory and yields files in sync path order.
+     * @param options - Optional scan controls.
+     */
+    scan(options?: SyncScanOptions): AsyncGenerator<LocalSyncPath>;
     /**
      * 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 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.
      */
     private walk;
+    private emitScanError;
 }
 //# sourceMappingURL=local.d.ts.map

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":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE5D;;;GAGG;AACH,qBAAa,WAAY,YAAW,UAAU;IAC5C,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAS;IAChC,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;OAGG;gBACS,IAAI,EAAE,MAAM;IAIxB,gFAAgF;IACzE,IAAI,IAAI,cAAc,CAAC,aAAa,CAAC;IAS5C;;;;OAIG;YACW,IAAI;CA4BnB"}
+{"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"}

package/dist/sync/scanners/local.js

@@ -1,58 +1,217 @@
-import { readdir, stat } from "node:fs/promises";
-import { join, relative, sep } from "node:path";
-class LocalFolder {
-  type = "local";
-  /** Absolute path to the local root directory. */
-  root;
-  /**
-   * Creates a new LocalFolder for the given root directory.
-   * @param root - Absolute path to the local directory to scan.
-   */
-  constructor(root) {
-    this.root = root;
-  }
-  /** Recursively walks the directory and yields files sorted by relative path. */
-  async *scan() {
-    const collected = [];
-    await this.walk(this.root, collected);
-    collected.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
-    for (const entry of collected) {
-      yield entry;
-    }
-  }
-  /**
-   * Recursively collects files from {@link dir} into {@link out}.
-   * @param dir - Absolute path of the directory to scan.
-   * @param out - Accumulator array that receives discovered file entries.
-   */
-  async walk(dir, out) {
-    let entries;
-    try {
-      entries = await readdir(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const fullPath = join(dir, entry.name);
-      if (entry.isDirectory()) {
-        await this.walk(fullPath, out);
-      } else if (entry.isFile()) {
-        try {
-          const s = await stat(fullPath);
-          const rel = relative(this.root, fullPath).split(sep).join("/");
-          out.push({
-            relativePath: rel,
-            absolutePath: fullPath,
-            modTimeMillis: Math.floor(s.mtimeMs),
-            size: s.size
-          });
-        } catch {
-        }
-      }
-    }
-  }
-}
-export {
-  LocalFolder
+import { validateSyncFilters } from "../regexp-safety.js";
+import { emitScannerSkip, regexpInputTooLongSkip } from "../scan-events.js";
+import { directoryMayContainSyncPaths, pathPassesSyncFilters, pathSkippedByRegExpInputLimit } from "../filters.js";
+import { compareSyncRelativePaths } from "../path-order.js";
+import { assertScanEntryLimit, scanEntryLimit } from "../scan-limit.js";
+import { localFileIdentityFromStats } from "../local-file-identity.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
+/**
+* Scans a local directory tree and yields {@link LocalSyncPath} entries sorted by relative path.
+* A root directory read failure aborts the scan with an error diagnostic. Per-entry file or
+* directory failures are reported through `onError` and the scan continues over readable siblings.
+* SDK-managed partial download file names are skipped so unfinished internal
+* temp files are not synchronized.
+* The current implementation collects matching entries before sorting, so memory usage is
+* proportional to the number of matched files.
+*/
+var LocalFolder = class {
+	type = "local";
+	appliesScanFilters = true;
+	appliesScanSorting = true;
+	/** Resolved absolute path to the local root directory. */
+	root;
+	/**
+	* Creates a new LocalFolder for the given root directory.
+	* @param root - Absolute or relative path to the local directory to scan.
+	*/
+	constructor(root) {
+		this.root = resolvePathAtConstruction(root);
+		registerLocalFilesystemRoot(this);
+	}
+	/**
+	* Recursively walks the directory and yields files in sync path order.
+	* @param options - Optional scan controls.
+	*/
+	async *scan(options = {}) {
+		validateSyncFilters(options);
+		const nodeDeps = await loadLocalNodeDeps();
+		const root = nodeDeps.resolve(this.root);
+		const collected = [];
+		await this.walk(root, root, collected, options, scanEntryLimit(options), nodeDeps);
+		collected.sort((a, b) => compareSyncRelativePaths(a.relativePath, b.relativePath));
+		for (const entry of collected) {
+			throwIfScanAborted(options);
+			yield entry;
+		}
+	}
+	/**
+	* 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 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.
+	*/
+	async walk(root, dir, out, options, maxScanEntries, nodeDeps) {
+		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);
+			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);
+			if (isDownloadStagingDirectorySegment(rel) && entry.isDirectory() && isDownloadStagingDirectorySegment(entry.name) && await isManagedDownloadStagingRoot(fullPath)) continue;
+			if (rel.includes("\\")) {
+				emitScannerSkip(options, {
+					type: "skip",
+					path: rel,
+					size: 0,
+					reason: "unsafe-name",
+					message: `Skipped local path ${JSON.stringify(rel)}: backslashes are not safe sync path characters`
+				});
+				continue;
+			}
+			if (isReservedSyncTempFileName(entry.name)) {
+				emitScannerSkip(options, {
+					type: "skip",
+					path: rel,
+					size: 0,
+					reason: "stale-download-partial",
+					message: `Skipped local path ${JSON.stringify(rel)}: reserved SDK partial download file`
+				});
+				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;
+				}
+				assertScanEntryLimit(out.length + 1, maxScanEntries);
+				out.push({
+					relativePath: rel,
+					absolutePath: fullPath,
+					modTimeMillis: Math.floor(s.mtimeMs),
+					size: s.size,
+					fileIdentity: localFileIdentityFromStats(s)
+				});
+			}
+		}
+	}
+	emitScanError(options, path, kind, err) {
+		const event = {
+			type: "error",
+			path,
+			size: 0,
+			message: `failed to scan local ${kind}: ${localFilesystemErrorReason(err)}`
+		};
+		options.onError?.(event);
+		return new Error(event.message);
+	}
 };
-//# sourceMappingURL=local.js.map
+async function loadLocalNodeDeps() {
+	const [fsPromises, path] = await Promise.all([import("node:fs/promises"), import("node:path")]);
+	return {
+		readdir: fsPromises.readdir,
+		lstat: fsPromises.lstat,
+		join: path.join,
+		relative: path.relative,
+		resolve: path.resolve,
+		sep: path.sep
+	};
+}
+function resolvePathAtConstruction(root) {
+	const processLike = globalThis.process;
+	if (typeof processLike?.cwd !== "function") return root;
+	const cwd = processLike.cwd();
+	if (processLike.platform === "win32") return resolveWindowsPath(cwd, root);
+	return resolvePosixPath(cwd, root);
+}
+function resolvePosixPath(cwd, root) {
+	const resolved = normalizePathSegments((root.startsWith("/") ? root : `${cwd}/${root}`).split("/"), "/");
+	return resolved === "" ? "/" : `/${resolved}`;
+}
+function resolveWindowsPath(cwd, root) {
+	const normalizedRoot = root.replaceAll("/", "\\");
+	const normalizedCwd = cwd.replaceAll("/", "\\");
+	const drive = /^[A-Za-z]:/.exec(normalizedCwd)?.[0] ?? "";
+	const cwdUnc = splitUncPath(normalizedCwd);
+	if (/^\\\\/.test(normalizedRoot)) return normalizeUncPath(normalizedRoot);
+	if (/^[A-Za-z]:\\/.test(normalizedRoot)) return joinWindowsRoot(normalizedRoot.slice(0, 2), normalizePathSegments(normalizedRoot.slice(3).split("\\"), "\\"));
+	if (/^[A-Za-z]:/.test(normalizedRoot)) throw new Error("LocalFolder root must not be a drive-relative Windows path");
+	if (normalizedRoot.startsWith("\\")) {
+		const rest = normalizePathSegments(normalizedRoot.slice(1).split("\\"), "\\");
+		return joinWindowsRoot(cwdUnc?.prefix ?? drive, rest);
+	}
+	if (cwdUnc !== void 0) {
+		const resolved = normalizePathSegments([...cwdUnc.rest, ...normalizedRoot.split("\\")], "\\");
+		return joinWindowsRoot(cwdUnc.prefix, resolved);
+	}
+	const base = /^[A-Za-z]:\\/.test(normalizedCwd) ? normalizedCwd : `${drive}\\`;
+	const prefix = /^[A-Za-z]:/.exec(base)?.[0] ?? drive;
+	return joinWindowsRoot(prefix, normalizePathSegments([...base.slice(prefix.length).replace(/^\\/, "").split("\\"), ...normalizedRoot.split("\\")], "\\"));
+}
+function normalizeUncPath(path) {
+	const unc = splitUncPath(path);
+	if (unc === void 0) return path;
+	return joinWindowsRoot(unc.prefix, normalizePathSegments(unc.rest, "\\"));
+}
+function splitUncPath(path) {
+	if (!path.startsWith("\\\\")) return void 0;
+	const [server, share, ...rest] = path.split("\\").filter((part) => part !== "");
+	if (server === void 0 || share === void 0) return void 0;
+	return {
+		prefix: `\\\\${server}\\${share}`,
+		rest
+	};
+}
+function joinWindowsRoot(prefix, rest) {
+	return rest === "" ? `${prefix}\\` : `${prefix}\\${rest}`;
+}
+function normalizePathSegments(segments, separator) {
+	const out = [];
+	for (const segment of segments) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			out.pop();
+			continue;
+		}
+		out.push(segment);
+	}
+	return out.join(separator);
+}
+function relativePathFromRoot(root, path, nodeDeps) {
+	return nodeDeps.relative(root, path).split(nodeDeps.sep).join("/");
+}
+function throwIfScanAborted(options) {
+	if (options.signal?.aborted === true) throw options.signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+//#endregion
+export { LocalFolder };
+
+//# sourceMappingURL=local.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"local.js","sources":["../../../src/sync/scanners/local.ts"],"sourcesContent":["import { readdir, stat } from 'node:fs/promises'\nimport { join, relative, sep } from 'node:path'\nimport type { LocalSyncPath, SyncFolder } from '../types.ts'\n\n/**\n * Scans a local directory tree and yields {@link LocalSyncPath} entries\n * sorted by relative path. Unreadable files and directories are silently skipped.\n */\nexport class LocalFolder implements SyncFolder {\n  readonly type = 'local' as const\n  /** 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 path to the local directory to scan.\n   */\n  constructor(root: string) {\n    this.root = root\n  }\n\n  /** Recursively walks the directory and yields files sorted by relative path. */\n  async *scan(): AsyncGenerator<LocalSyncPath> {\n    const collected: LocalSyncPath[] = []\n    await this.walk(this.root, collected)\n    collected.sort((a, b) => a.relativePath.localeCompare(b.relativePath))\n    for (const entry of collected) {\n      yield entry\n    }\n  }\n\n  /**\n   * Recursively collects files from {@link dir} into {@link out}.\n   * @param dir - Absolute path of the directory to scan.\n   * @param out - Accumulator array that receives discovered file entries.\n   */\n  private async walk(dir: string, out: LocalSyncPath[]): Promise<void> {\n    let entries: import('node:fs').Dirent[]\n    try {\n      entries = await readdir(dir, { withFileTypes: true })\n    } catch {\n      return\n    }\n\n    for (const entry of entries) {\n      const fullPath = join(dir, entry.name)\n      if (entry.isDirectory()) {\n        await this.walk(fullPath, out)\n      } else if (entry.isFile()) {\n        try {\n          const s = await stat(fullPath)\n          const rel = relative(this.root, fullPath).split(sep).join('/')\n          out.push({\n            relativePath: rel,\n            absolutePath: fullPath,\n            modTimeMillis: Math.floor(s.mtimeMs),\n            size: s.size,\n          })\n        } catch {\n          // skip unreadable files\n        }\n      }\n    }\n  }\n}\n"],"names":[],"mappings":";;AAQO,MAAM,YAAkC;AAAA,EACpC,OAAO;AAAA;AAAA,EAEP;AAAA;AAAA;AAAA;AAAA;AAAA,EAMT,YAAY,MAAc;AACxB,SAAK,OAAO;AAAA,EACd;AAAA;AAAA,EAGA,OAAO,OAAsC;AAC3C,UAAM,YAA6B,CAAA;AACnC,UAAM,KAAK,KAAK,KAAK,MAAM,SAAS;AACpC,cAAU,KAAK,CAAC,GAAG,MAAM,EAAE,aAAa,cAAc,EAAE,YAAY,CAAC;AACrE,eAAW,SAAS,WAAW;AAC7B,YAAM;AAAA,IACR;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAc,KAAK,KAAa,KAAqC;AACnE,QAAI;AACJ,QAAI;AACF,gBAAU,MAAM,QAAQ,KAAK,EAAE,eAAe,MAAM;AAAA,IACtD,QAAQ;AACN;AAAA,IACF;AAEA,eAAW,SAAS,SAAS;AAC3B,YAAM,WAAW,KAAK,KAAK,MAAM,IAAI;AACrC,UAAI,MAAM,eAAe;AACvB,cAAM,KAAK,KAAK,UAAU,GAAG;AAAA,MAC/B,WAAW,MAAM,UAAU;AACzB,YAAI;AACF,gBAAM,IAAI,MAAM,KAAK,QAAQ;AAC7B,gBAAM,MAAM,SAAS,KAAK,MAAM,QAAQ,EAAE,MAAM,GAAG,EAAE,KAAK,GAAG;AAC7D,cAAI,KAAK;AAAA,YACP,cAAc;AAAA,YACd,cAAc;AAAA,YACd,eAAe,KAAK,MAAM,EAAE,OAAO;AAAA,YACnC,MAAM,EAAE;AAAA,UAAA,CACT;AAAA,QACH,QAAQ;AAAA,QAER;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;"}
+{"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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"}

package/dist/sync/sha1-metadata.cjs

@@ -0,0 +1,94 @@
+const require_sha1 = require("../util/sha1.cjs");
+//#region src/sync/sha1-metadata.ts
+/** Prefix used to mark SHA-1 metadata that must not prove equality without byte verification. */
+var untrustedSha1Prefix = "unverified:";
+/**
+* Marks a verifiable SHA-1 digest as untrusted provider metadata.
+*
+* @param sha1 - Verifiable 40-character hexadecimal SHA-1 digest.
+*
+* @returns The untrusted SHA-1 sentinel value.
+*
+* @throws When the supplied value is not a verifiable SHA-1 digest.
+*/
+function untrustedSha1(sha1) {
+	const normalized = require_sha1.normalizeVerifiableSha1(sha1);
+	if (normalized === null) throw new Error("untrusted SHA-1 metadata must be verifiable");
+	return `${untrustedSha1Prefix}${normalized}`;
+}
+/**
+* Extracts the best comparable SHA-1 value from a B2 file version.
+*
+* B2's primary `contentSha1` is authoritative for single-part uploads when it is a verifiable
+* digest. Large/multipart B2 files report `contentSha1: null`; `fileInfo.large_file_sha1` is
+* caller-provided metadata, so it is returned as an untrusted hint that cannot prove equality
+* until the high-level synchronizer hashes the selected version's bytes.
+*
+* @param version - B2 file version metadata.
+*
+* @returns A lowercase comparable SHA-1, an untrusted sentinel, or null when unavailable.
+*/
+function selectB2ComparableSha1(version) {
+	const originalContentSha1 = version.contentSha1;
+	if (typeof originalContentSha1 === "string") {
+		if (isUntrustedSha1(originalContentSha1)) return originalContentSha1.toLowerCase();
+		return require_sha1.normalizeVerifiableSha1(originalContentSha1) ?? originalContentSha1.toLowerCase();
+	}
+	const largeFileSha1 = require_sha1.normalizeVerifiableSha1(version.fileInfo["large_file_sha1"]);
+	return largeFileSha1 === null ? null : untrustedSha1(largeFileSha1);
+}
+/**
+* Returns whether a SHA-1 value is marked as untrusted metadata.
+*
+* @param sha1 - Candidate SHA-1 metadata.
+*
+* @returns True when the value carries B2's unverified sentinel prefix.
+*/
+function isUntrustedSha1(sha1) {
+	return sha1?.toLowerCase().startsWith("unverified:") ?? false;
+}
+/**
+* Parses the public `SyncPath.contentSha1` value into an explicit trust/availability state.
+*
+* @param sha1 - The raw `contentSha1` field from a sync path.
+*
+* @returns A discriminated state so custom scanners do not need to decode sentinels directly.
+*/
+function parseSyncContentSha1(sha1) {
+	if (sha1 === void 0) return { kind: "pending" };
+	if (sha1 === null) return { kind: "unavailable" };
+	if (isUntrustedSha1(sha1)) return {
+		kind: "untrusted",
+		raw: sha1,
+		value: require_sha1.normalizeVerifiableSha1(sha1.slice(11))
+	};
+	const normalized = require_sha1.normalizeVerifiableSha1(sha1);
+	if (normalized === null) return {
+		kind: "untrusted",
+		raw: sha1,
+		value: null
+	};
+	return {
+		kind: "verified",
+		value: normalized
+	};
+}
+/**
+* Reads an explicit SHA-1 state when present, otherwise parses the compatibility field.
+*
+* @param path - Object carrying SHA-1 metadata.
+*
+* @returns The explicit or parsed SHA-1 state.
+*/
+function syncSha1StateOf(path) {
+	return path.contentSha1State ?? parseSyncContentSha1(path.contentSha1);
+}
+//#endregion
+exports.isUntrustedSha1 = isUntrustedSha1;
+exports.parseSyncContentSha1 = parseSyncContentSha1;
+exports.selectB2ComparableSha1 = selectB2ComparableSha1;
+exports.syncSha1StateOf = syncSha1StateOf;
+exports.untrustedSha1 = untrustedSha1;
+exports.untrustedSha1Prefix = untrustedSha1Prefix;
+
+//# sourceMappingURL=sha1-metadata.cjs.map

package/dist/sync/sha1-metadata.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sha1-metadata.cjs","names":[],"sources":["../../src/sync/sha1-metadata.ts"],"sourcesContent":["import type { FileVersion } from '../types/file.ts'\nimport { normalizeVerifiableSha1 } from '../util/sha1.ts'\n\n/** Prefix used to mark SHA-1 metadata that must not prove equality without byte verification. */\nexport const untrustedSha1Prefix = 'unverified:'\n\n/** SHA-1 has not been computed or populated yet. */\nexport interface SyncSha1PendingState {\n  /** State discriminator. */\n  readonly kind: 'pending'\n}\n\n/** SHA-1 is known to be unavailable for this path. */\nexport interface SyncSha1UnavailableState {\n  /** State discriminator. */\n  readonly kind: 'unavailable'\n}\n\n/** SHA-1 is a normalized 40-character digest that may prove equality. */\nexport interface SyncSha1VerifiedState {\n  /** State discriminator. */\n  readonly kind: 'verified'\n  /** Normalized lowercase 40-character SHA-1 digest. */\n  readonly value: string\n}\n\n/** SHA-1 metadata is present but cannot prove equality without verification. */\nexport interface SyncSha1UntrustedState {\n  /** State discriminator. */\n  readonly kind: 'untrusted'\n  /** Normalized digest when one can be extracted from the raw metadata. */\n  readonly value: string | null\n  /** Original metadata string supplied by the scanner or B2 file version. */\n  readonly raw: string\n}\n\n/** Public SHA-1 state used by sync scanners and low-level compare helpers. */\nexport type SyncSha1State =\n  | SyncSha1PendingState\n  | SyncSha1UnavailableState\n  | SyncSha1VerifiedState\n  | SyncSha1UntrustedState\n\n/**\n * Marks a verifiable SHA-1 digest as untrusted provider metadata.\n *\n * @param sha1 - Verifiable 40-character hexadecimal SHA-1 digest.\n *\n * @returns The untrusted SHA-1 sentinel value.\n *\n * @throws When the supplied value is not a verifiable SHA-1 digest.\n */\nexport function untrustedSha1(sha1: string): string {\n  const normalized = normalizeVerifiableSha1(sha1)\n  if (normalized === null) throw new Error('untrusted SHA-1 metadata must be verifiable')\n  return `${untrustedSha1Prefix}${normalized}`\n}\n\n/**\n * Extracts the best comparable SHA-1 value from a B2 file version.\n *\n * B2's primary `contentSha1` is authoritative for single-part uploads when it is a verifiable\n * digest. Large/multipart B2 files report `contentSha1: null`; `fileInfo.large_file_sha1` is\n * caller-provided metadata, so it is returned as an untrusted hint that cannot prove equality\n * until the high-level synchronizer hashes the selected version's bytes.\n *\n * @param version - B2 file version metadata.\n *\n * @returns A lowercase comparable SHA-1, an untrusted sentinel, or null when unavailable.\n */\nexport function selectB2ComparableSha1(version: FileVersion): string | null {\n  const originalContentSha1 = version.contentSha1\n  if (typeof originalContentSha1 === 'string') {\n    if (isUntrustedSha1(originalContentSha1)) return originalContentSha1.toLowerCase()\n    const contentSha1 = normalizeVerifiableSha1(originalContentSha1)\n    return contentSha1 ?? originalContentSha1.toLowerCase()\n  }\n\n  const largeFileSha1 = normalizeVerifiableSha1(version.fileInfo['large_file_sha1'])\n  return largeFileSha1 === null ? null : untrustedSha1(largeFileSha1)\n}\n\n/**\n * Returns whether a SHA-1 value is marked as untrusted metadata.\n *\n * @param sha1 - Candidate SHA-1 metadata.\n *\n * @returns True when the value carries B2's unverified sentinel prefix.\n */\nexport function isUntrustedSha1(sha1: string | null | undefined): boolean {\n  return sha1?.toLowerCase().startsWith(untrustedSha1Prefix) ?? false\n}\n\n/**\n * Parses the public `SyncPath.contentSha1` value into an explicit trust/availability state.\n *\n * @param sha1 - The raw `contentSha1` field from a sync path.\n *\n * @returns A discriminated state so custom scanners do not need to decode sentinels directly.\n */\nexport function parseSyncContentSha1(sha1: string | null | undefined): SyncSha1State {\n  if (sha1 === undefined) return { kind: 'pending' }\n  if (sha1 === null) return { kind: 'unavailable' }\n  if (isUntrustedSha1(sha1)) {\n    return {\n      kind: 'untrusted',\n      raw: sha1,\n      value: normalizeVerifiableSha1(sha1.slice(untrustedSha1Prefix.length)),\n    }\n  }\n  const normalized = normalizeVerifiableSha1(sha1)\n  if (normalized === null) return { kind: 'untrusted', raw: sha1, value: null }\n  return { kind: 'verified', value: normalized }\n}\n\n/**\n * Reads an explicit SHA-1 state when present, otherwise parses the compatibility field.\n *\n * @param path - Object carrying SHA-1 metadata.\n *\n * @returns The explicit or parsed SHA-1 state.\n */\nexport function syncSha1StateOf(path: {\n  readonly contentSha1?: string | null\n  readonly contentSha1State?: SyncSha1State\n}): SyncSha1State {\n  return path.contentSha1State ?? parseSyncContentSha1(path.contentSha1)\n}\n"],"mappings":";;;AAIA,IAAa,sBAAsB;;;;;;;;;;AAgDnC,SAAgB,cAAc,MAAsB;CAClD,MAAM,aAAa,aAAA,wBAAwB,IAAI;CAC/C,IAAI,eAAe,MAAM,MAAM,IAAI,MAAM,6CAA6C;CACtF,OAAO,GAAG,sBAAsB;AAClC;;;;;;;;;;;;;AAcA,SAAgB,uBAAuB,SAAqC;CAC1E,MAAM,sBAAsB,QAAQ;CACpC,IAAI,OAAO,wBAAwB,UAAU;EAC3C,IAAI,gBAAgB,mBAAmB,GAAG,OAAO,oBAAoB,YAAY;EAEjF,OADoB,aAAA,wBAAwB,mBACrC,KAAe,oBAAoB,YAAY;CACxD;CAEA,MAAM,gBAAgB,aAAA,wBAAwB,QAAQ,SAAS,kBAAkB;CACjF,OAAO,kBAAkB,OAAO,OAAO,cAAc,aAAa;AACpE;;;;;;;;AASA,SAAgB,gBAAgB,MAA0C;CACxE,OAAO,MAAM,YAAY,CAAC,CAAC,WAAA,aAA8B,KAAK;AAChE;;;;;;;;AASA,SAAgB,qBAAqB,MAAgD;CACnF,IAAI,SAAS,KAAA,GAAW,OAAO,EAAE,MAAM,UAAU;CACjD,IAAI,SAAS,MAAM,OAAO,EAAE,MAAM,cAAc;CAChD,IAAI,gBAAgB,IAAI,GACtB,OAAO;EACL,MAAM;EACN,KAAK;EACL,OAAO,aAAA,wBAAwB,KAAK,MAAM,EAA0B,CAAC;CACvE;CAEF,MAAM,aAAa,aAAA,wBAAwB,IAAI;CAC/C,IAAI,eAAe,MAAM,OAAO;EAAE,MAAM;EAAa,KAAK;EAAM,OAAO;CAAK;CAC5E,OAAO;EAAE,MAAM;EAAY,OAAO;CAAW;AAC/C;;;;;;;;AASA,SAAgB,gBAAgB,MAGd;CAChB,OAAO,KAAK,oBAAoB,qBAAqB,KAAK,WAAW;AACvE"}