zen-fs-config 0.5.31 → 0.5.32

package/dist/index.d.mts

@@ -4,6 +4,65 @@ import * as node_fs from 'node:fs';
 import * as node_path from 'node:path';
 import { SyncMapStore, SyncMapTransaction } from '@zenfs/core';
 
+/**
+ * zen-fs-config — mtime sidecar cleanup
+ *
+ * Backends that cannot store a precise mtime natively (RemoteStorage, Gitee,
+ * …) persist it in a `.mtime` sidecar next to each file
+ * (`data.json` → `.data.json.mtime`). A sidecar is backend-internal metadata:
+ * it belongs to the backend that produced it and must never be handed out by
+ * `readdir()`/`createSnapshot()`.
+ *
+ * Older builds did leak them, and once a sidecar lands in the local primary
+ * (IndexedDB on browser, Folder on Node) it stays there forever — zen-fs-sync
+ * deliberately skips `.mtime` paths on both sides, so nothing ever removes
+ * them, and every walk logs:
+ *
+ *   [zen-fs-sync] mtime sidecar leaked from backend "local-idb" …
+ *
+ * This module walks the local primary and deletes those leaked files. It never
+ * touches replica (remote) backends: their sidecars are live metadata, and
+ * deleting them would cost network calls and lose mtime precision.
+ */
+/** Minimal async FS surface needed for the purge. */
+interface PurgeableFS {
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<{
+        mode?: number;
+    }>;
+    unlink(path: string): Promise<void>;
+}
+interface PurgeMtimeOptions {
+    /** Root to scan. Default: `/` (the whole local primary). */
+    root?: string;
+    /** Report what would be deleted without unlinking anything. */
+    dryRun?: boolean;
+}
+interface MtimePurgeResult {
+    /** Files visited during the walk (sidecars included). */
+    scanned: number;
+    /** Sidecars deleted — or, in dryRun, that would be deleted. */
+    removed: string[];
+    /** Sidecars that could not be deleted (unlink failed). */
+    failed: string[];
+}
+/**
+ * True when a file name is an mtime sidecar.
+ *
+ * Uses the same rule as zen-fs-sync's walker (`path.endsWith('.mtime')`), so
+ * the pathological nested form (`.foo.mtime.mtime`) is covered too.
+ */
+declare function isMtimeSidecar(fileName: string): boolean;
+/**
+ * Delete every `.mtime` sidecar stored in a local primary backend.
+ *
+ * Walks the whole tree from `options.root` — including dotfiles and `/.meta/`,
+ * because sidecars live next to their data file and are themselves dotfiles.
+ * Unreadable entries are skipped; failures on individual files are collected
+ * in `failed` instead of aborting the walk.
+ */
+declare function purgeMtimeSidecars(fs: PurgeableFS, options?: PurgeMtimeOptions): Promise<MtimePurgeResult>;
+
 /** A single backend in the topology. */
 interface BackendDescriptor {
     /** Unique identifier within this config repo (e.g., "local-idb"). */
@@ -159,6 +218,17 @@ interface ConfigRepoOptions {
      * Default: 1800000 (30 minutes).
      */
     syncPollIntervalMs?: number;
+    /**
+     * Delete leaked `.mtime` sidecars from the local primary on startup.
+     *
+     * Backends that keep a precise mtime out-of-band (RemoteStorage, Gitee…)
+     * write a `.mtime` file next to each data file. Older builds copied those
+     * backend-internal files into the local primary, where sync ignores them —
+     * so they linger forever and warn on every walk.
+     *
+     * Default: `true`. Pass `false` to skip the (local-only) startup sweep.
+     */
+    purgeMtimeSidecars?: boolean;
 }
 /** Type of sync group. */
 type SyncGroupType = 'config-sync' | 'data-sync';
@@ -340,6 +410,17 @@ interface IConfigRepo {
      * Called automatically by createConfigRepo() after setupSync().
      */
     syncMetaToReplicas(): Promise<void>;
+    /**
+     * Delete leaked `.mtime` sidecars from the local primary backend.
+     *
+     * Runs automatically on `createConfigRepo()` unless
+     * `options.purgeMtimeSidecars === false`. Call it manually to clean a
+     * long-lived store, or with `{ dryRun: true }` to only list them.
+     */
+    purgeMtimeSidecars(options?: {
+        root?: string;
+        dryRun?: boolean;
+    }): Promise<MtimePurgeResult>;
     /**
      * Create a data-sync group for this app.
      * Each backend can optionally reference a config-sync backend's account
@@ -593,6 +674,22 @@ declare class ConfigRepo implements IConfigRepo {
     private safeExists;
     /** Public wrapper for processTombstones — used by createConfigRepo. */
     processTombstonesPublic(): Promise<void>;
+    /**
+     * Delete leaked `.mtime` sidecar files from the local primary backend
+     * (IndexedDB on browser, Folder on Node).
+     *
+     * Sidecars are produced by backends that keep a precise mtime out-of-band
+     * (RemoteStorage, Gitee…). Once one is copied into the local primary it is
+     * never removed: zen-fs-sync skips `.mtime` paths on both sides, so it is
+     * invisible to sync, and every walk warns about the leak.
+     *
+     * Only the local primary is scanned — replica sidecars are live metadata of
+     * the backend that owns them and must be left alone.
+     *
+     * @param options.root Scan only this subtree (default `/`).
+     * @param options.dryRun List the sidecars without deleting them.
+     */
+    purgeMtimeSidecars(options?: PurgeMtimeOptions): Promise<MtimePurgeResult>;
     /**
      * Perform a full sync + dedup cycle without the watch snapshot cache.
      * Used by createConfigRepo to pull remote-only files (like duplicate
@@ -826,4 +923,4 @@ declare function incrementVersion(fs: SyncableFS, configFilePath: string, newCon
  */
 declare function verifyOrRepairVersion(fs: SyncableFS, configFilePath: string, author: string): Promise<VersionMeta | null>;
 
-export { type AppDataBackendDescriptor, type AppDataGroup, type AppDataGroupDescriptor, type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendMetadata, type BackendParamDef, type BackendsMeta, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type ConnectOptions, type ConnectResult, FolderStore, type IConfigRepo, LOCAL_IDB_BACKEND_ID, type SyncGroupType, type TombstoneMeta, type VersionMeta, configKeyToFilePath, connect, createBackend, createConfigRepo, createSerializerChain, getAccountFields, getBackendMetadata, getExtension, hasBackend, incrementVersion, isBrowserEnv, listBackendMetadata, listBackends, localPrimaryType, mergeAccountFields, readVersion, registerBackend, registerFolderBackend, resolveLocalPrimary, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };
+export { type AppDataBackendDescriptor, type AppDataGroup, type AppDataGroupDescriptor, type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendMetadata, type BackendParamDef, type BackendsMeta, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type ConnectOptions, type ConnectResult, FolderStore, type IConfigRepo, LOCAL_IDB_BACKEND_ID, type MtimePurgeResult, type PurgeMtimeOptions, type PurgeableFS, type SyncGroupType, type TombstoneMeta, type VersionMeta, configKeyToFilePath, connect, createBackend, createConfigRepo, createSerializerChain, getAccountFields, getBackendMetadata, getExtension, hasBackend, incrementVersion, isBrowserEnv, isMtimeSidecar, listBackendMetadata, listBackends, localPrimaryType, mergeAccountFields, purgeMtimeSidecars, readVersion, registerBackend, registerFolderBackend, resolveLocalPrimary, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };

package/dist/index.d.ts

@@ -4,6 +4,65 @@ import * as node_fs from 'node:fs';
 import * as node_path from 'node:path';
 import { SyncMapStore, SyncMapTransaction } from '@zenfs/core';
 
+/**
+ * zen-fs-config — mtime sidecar cleanup
+ *
+ * Backends that cannot store a precise mtime natively (RemoteStorage, Gitee,
+ * …) persist it in a `.mtime` sidecar next to each file
+ * (`data.json` → `.data.json.mtime`). A sidecar is backend-internal metadata:
+ * it belongs to the backend that produced it and must never be handed out by
+ * `readdir()`/`createSnapshot()`.
+ *
+ * Older builds did leak them, and once a sidecar lands in the local primary
+ * (IndexedDB on browser, Folder on Node) it stays there forever — zen-fs-sync
+ * deliberately skips `.mtime` paths on both sides, so nothing ever removes
+ * them, and every walk logs:
+ *
+ *   [zen-fs-sync] mtime sidecar leaked from backend "local-idb" …
+ *
+ * This module walks the local primary and deletes those leaked files. It never
+ * touches replica (remote) backends: their sidecars are live metadata, and
+ * deleting them would cost network calls and lose mtime precision.
+ */
+/** Minimal async FS surface needed for the purge. */
+interface PurgeableFS {
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<{
+        mode?: number;
+    }>;
+    unlink(path: string): Promise<void>;
+}
+interface PurgeMtimeOptions {
+    /** Root to scan. Default: `/` (the whole local primary). */
+    root?: string;
+    /** Report what would be deleted without unlinking anything. */
+    dryRun?: boolean;
+}
+interface MtimePurgeResult {
+    /** Files visited during the walk (sidecars included). */
+    scanned: number;
+    /** Sidecars deleted — or, in dryRun, that would be deleted. */
+    removed: string[];
+    /** Sidecars that could not be deleted (unlink failed). */
+    failed: string[];
+}
+/**
+ * True when a file name is an mtime sidecar.
+ *
+ * Uses the same rule as zen-fs-sync's walker (`path.endsWith('.mtime')`), so
+ * the pathological nested form (`.foo.mtime.mtime`) is covered too.
+ */
+declare function isMtimeSidecar(fileName: string): boolean;
+/**
+ * Delete every `.mtime` sidecar stored in a local primary backend.
+ *
+ * Walks the whole tree from `options.root` — including dotfiles and `/.meta/`,
+ * because sidecars live next to their data file and are themselves dotfiles.
+ * Unreadable entries are skipped; failures on individual files are collected
+ * in `failed` instead of aborting the walk.
+ */
+declare function purgeMtimeSidecars(fs: PurgeableFS, options?: PurgeMtimeOptions): Promise<MtimePurgeResult>;
+
 /** A single backend in the topology. */
 interface BackendDescriptor {
     /** Unique identifier within this config repo (e.g., "local-idb"). */
@@ -159,6 +218,17 @@ interface ConfigRepoOptions {
      * Default: 1800000 (30 minutes).
      */
     syncPollIntervalMs?: number;
+    /**
+     * Delete leaked `.mtime` sidecars from the local primary on startup.
+     *
+     * Backends that keep a precise mtime out-of-band (RemoteStorage, Gitee…)
+     * write a `.mtime` file next to each data file. Older builds copied those
+     * backend-internal files into the local primary, where sync ignores them —
+     * so they linger forever and warn on every walk.
+     *
+     * Default: `true`. Pass `false` to skip the (local-only) startup sweep.
+     */
+    purgeMtimeSidecars?: boolean;
 }
 /** Type of sync group. */
 type SyncGroupType = 'config-sync' | 'data-sync';
@@ -340,6 +410,17 @@ interface IConfigRepo {
      * Called automatically by createConfigRepo() after setupSync().
      */
     syncMetaToReplicas(): Promise<void>;
+    /**
+     * Delete leaked `.mtime` sidecars from the local primary backend.
+     *
+     * Runs automatically on `createConfigRepo()` unless
+     * `options.purgeMtimeSidecars === false`. Call it manually to clean a
+     * long-lived store, or with `{ dryRun: true }` to only list them.
+     */
+    purgeMtimeSidecars(options?: {
+        root?: string;
+        dryRun?: boolean;
+    }): Promise<MtimePurgeResult>;
     /**
      * Create a data-sync group for this app.
      * Each backend can optionally reference a config-sync backend's account
@@ -593,6 +674,22 @@ declare class ConfigRepo implements IConfigRepo {
     private safeExists;
     /** Public wrapper for processTombstones — used by createConfigRepo. */
     processTombstonesPublic(): Promise<void>;
+    /**
+     * Delete leaked `.mtime` sidecar files from the local primary backend
+     * (IndexedDB on browser, Folder on Node).
+     *
+     * Sidecars are produced by backends that keep a precise mtime out-of-band
+     * (RemoteStorage, Gitee…). Once one is copied into the local primary it is
+     * never removed: zen-fs-sync skips `.mtime` paths on both sides, so it is
+     * invisible to sync, and every walk warns about the leak.
+     *
+     * Only the local primary is scanned — replica sidecars are live metadata of
+     * the backend that owns them and must be left alone.
+     *
+     * @param options.root Scan only this subtree (default `/`).
+     * @param options.dryRun List the sidecars without deleting them.
+     */
+    purgeMtimeSidecars(options?: PurgeMtimeOptions): Promise<MtimePurgeResult>;
     /**
      * Perform a full sync + dedup cycle without the watch snapshot cache.
      * Used by createConfigRepo to pull remote-only files (like duplicate
@@ -826,4 +923,4 @@ declare function incrementVersion(fs: SyncableFS, configFilePath: string, newCon
  */
 declare function verifyOrRepairVersion(fs: SyncableFS, configFilePath: string, author: string): Promise<VersionMeta | null>;
 
-export { type AppDataBackendDescriptor, type AppDataGroup, type AppDataGroupDescriptor, type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendMetadata, type BackendParamDef, type BackendsMeta, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type ConnectOptions, type ConnectResult, FolderStore, type IConfigRepo, LOCAL_IDB_BACKEND_ID, type SyncGroupType, type TombstoneMeta, type VersionMeta, configKeyToFilePath, connect, createBackend, createConfigRepo, createSerializerChain, getAccountFields, getBackendMetadata, getExtension, hasBackend, incrementVersion, isBrowserEnv, listBackendMetadata, listBackends, localPrimaryType, mergeAccountFields, readVersion, registerBackend, registerFolderBackend, resolveLocalPrimary, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };
+export { type AppDataBackendDescriptor, type AppDataGroup, type AppDataGroupDescriptor, type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendMetadata, type BackendParamDef, type BackendsMeta, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type ConnectOptions, type ConnectResult, FolderStore, type IConfigRepo, LOCAL_IDB_BACKEND_ID, type MtimePurgeResult, type PurgeMtimeOptions, type PurgeableFS, type SyncGroupType, type TombstoneMeta, type VersionMeta, configKeyToFilePath, connect, createBackend, createConfigRepo, createSerializerChain, getAccountFields, getBackendMetadata, getExtension, hasBackend, incrementVersion, isBrowserEnv, isMtimeSidecar, listBackendMetadata, listBackends, localPrimaryType, mergeAccountFields, purgeMtimeSidecars, readVersion, registerBackend, registerFolderBackend, resolveLocalPrimary, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };

package/dist/index.js

@@ -418,10 +418,12 @@ __export(index_exports, {
   hasBackend: () => hasBackend,
   incrementVersion: () => incrementVersion,
   isBrowserEnv: () => isBrowserEnv,
+  isMtimeSidecar: () => isMtimeSidecar,
   listBackendMetadata: () => listBackendMetadata,
   listBackends: () => listBackends,
   localPrimaryType: () => localPrimaryType,
   mergeAccountFields: () => mergeAccountFields,
+  purgeMtimeSidecars: () => purgeMtimeSidecars,
   readVersion: () => readVersion,
   registerBackend: () => registerBackend,
   registerFolderBackend: () => registerFolderBackend,
@@ -1038,6 +1040,60 @@ async function verifyOrRepairVersion(fs, configFilePath, author) {
   }
 }
 
+// src/mtime-cleanup.ts
+function isMtimeSidecar(fileName) {
+  return fileName.endsWith(".mtime");
+}
+var S_IFDIR = 16384;
+function isDirectory(stat) {
+  return typeof stat.mode === "number" && (stat.mode & S_IFDIR) === S_IFDIR;
+}
+function joinPath(dir, entry) {
+  if (dir === "/" || dir === "") return `/${entry}`;
+  return `${dir.replace(/\/+$/, "")}/${entry}`;
+}
+async function purgeMtimeSidecars(fs, options = {}) {
+  const root = options.root && options.root !== "" ? options.root : "/";
+  const dryRun = options.dryRun ?? false;
+  const result = { scanned: 0, removed: [], failed: [] };
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = await fs.readdir(dir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const fullPath = joinPath(dir, entry);
+      let stat;
+      try {
+        stat = await fs.stat(fullPath);
+      } catch {
+        continue;
+      }
+      if (isDirectory(stat)) {
+        stack.push(fullPath);
+        continue;
+      }
+      result.scanned++;
+      if (!isMtimeSidecar(entry)) continue;
+      if (dryRun) {
+        result.removed.push(fullPath);
+        continue;
+      }
+      try {
+        await fs.unlink(fullPath);
+        result.removed.push(fullPath);
+      } catch {
+        result.failed.push(fullPath);
+      }
+    }
+  }
+  return result;
+}
+
 // src/config-repo.ts
 var log2 = (0, import_localstorage_logger2.createLogger)("zen-fs-config:config-repo");
 var META_DIR = "/.meta";
@@ -1491,6 +1547,35 @@ var ConfigRepo = class {
   async processTombstonesPublic() {
     await this.processTombstones();
   }
+  /**
+   * Delete leaked `.mtime` sidecar files from the local primary backend
+   * (IndexedDB on browser, Folder on Node).
+   *
+   * Sidecars are produced by backends that keep a precise mtime out-of-band
+   * (RemoteStorage, Gitee…). Once one is copied into the local primary it is
+   * never removed: zen-fs-sync skips `.mtime` paths on both sides, so it is
+   * invisible to sync, and every walk warns about the leak.
+   *
+   * Only the local primary is scanned — replica sidecars are live metadata of
+   * the backend that owns them and must be left alone.
+   *
+   * @param options.root Scan only this subtree (default `/`).
+   * @param options.dryRun List the sidecars without deleting them.
+   */
+  async purgeMtimeSidecars(options) {
+    this.assertNotDisposed();
+    const result = await purgeMtimeSidecars(this.cachedFS, options);
+    if (result.removed.length > 0) {
+      log2.log(
+        `[ConfigRepo] purged ${result.removed.length} .mtime sidecar(s) from local primary` + (options?.dryRun ? " (dry run)" : ""),
+        result.removed
+      );
+    }
+    if (result.failed.length > 0) {
+      log2.warn(`[ConfigRepo] failed to purge ${result.failed.length} .mtime sidecar(s):`, result.failed);
+    }
+    return result;
+  }
   /**
    * Perform a full sync + dedup cycle without the watch snapshot cache.
    * Used by createConfigRepo to pull remote-only files (like duplicate
@@ -2412,6 +2497,17 @@ var AppDataGroupImpl = class {
     } catch {
       throw new Error(`Failed to create local primary for data group "${this.groupId}"`);
     }
+    try {
+      const purged = await purgeMtimeSidecars(this.localFS);
+      if (purged.removed.length > 0) {
+        log2.warn(
+          `[AppDataGroup:${this.groupId}] purged ${purged.removed.length} leaked .mtime sidecar(s):`,
+          purged.removed
+        );
+      }
+    } catch (err) {
+      log2.warn(`[AppDataGroup:${this.groupId}] .mtime purge failed:`, err?.message ?? err);
+    }
     const localSyncable = backendToSyncableFS(this.localFS, `local(${this.groupId})`);
     this.fs = createChrootFS(this.localFS, "/");
     const { kept, removed } = dedupeAppDataBackends(this._backends);
@@ -2538,6 +2634,19 @@ async function createConfigRepo(appId, options = {}) {
   log2.log(`[createConfigRepo] Creating local primary (type: ${localPrimary.type})...`);
   const primaryInstance = await createBackend(localPrimary);
   const cachedFS = primaryInstance;
+  if (options.purgeMtimeSidecars !== false) {
+    try {
+      const purged = await purgeMtimeSidecars(cachedFS);
+      if (purged.removed.length > 0) {
+        log2.warn(
+          `[createConfigRepo] purged ${purged.removed.length} leaked .mtime sidecar(s) from local primary:`,
+          purged.removed
+        );
+      }
+    } catch (err) {
+      log2.warn(`[createConfigRepo] .mtime purge failed:`, err?.message ?? err);
+    }
+  }
   const cacheOptions = options.cache === false ? void 0 : options.cache ?? {};
   try {
     await primaryInstance.mkdir(META_DIR);
@@ -2772,10 +2881,12 @@ init_backend_registry();
   hasBackend,
   incrementVersion,
   isBrowserEnv,
+  isMtimeSidecar,
   listBackendMetadata,
   listBackends,
   localPrimaryType,
   mergeAccountFields,
+  purgeMtimeSidecars,
   readVersion,
   registerBackend,
   registerFolderBackend,

package/dist/index.mjs

@@ -613,6 +613,60 @@ async function verifyOrRepairVersion(fs, configFilePath, author) {
   }
 }
 
+// src/mtime-cleanup.ts
+function isMtimeSidecar(fileName) {
+  return fileName.endsWith(".mtime");
+}
+var S_IFDIR = 16384;
+function isDirectory(stat) {
+  return typeof stat.mode === "number" && (stat.mode & S_IFDIR) === S_IFDIR;
+}
+function joinPath(dir, entry) {
+  if (dir === "/" || dir === "") return `/${entry}`;
+  return `${dir.replace(/\/+$/, "")}/${entry}`;
+}
+async function purgeMtimeSidecars(fs, options = {}) {
+  const root = options.root && options.root !== "" ? options.root : "/";
+  const dryRun = options.dryRun ?? false;
+  const result = { scanned: 0, removed: [], failed: [] };
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = await fs.readdir(dir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const fullPath = joinPath(dir, entry);
+      let stat;
+      try {
+        stat = await fs.stat(fullPath);
+      } catch {
+        continue;
+      }
+      if (isDirectory(stat)) {
+        stack.push(fullPath);
+        continue;
+      }
+      result.scanned++;
+      if (!isMtimeSidecar(entry)) continue;
+      if (dryRun) {
+        result.removed.push(fullPath);
+        continue;
+      }
+      try {
+        await fs.unlink(fullPath);
+        result.removed.push(fullPath);
+      } catch {
+        result.failed.push(fullPath);
+      }
+    }
+  }
+  return result;
+}
+
 // src/config-repo.ts
 var log2 = createLogger2("zen-fs-config:config-repo");
 var META_DIR = "/.meta";
@@ -1066,6 +1120,35 @@ var ConfigRepo = class {
   async processTombstonesPublic() {
     await this.processTombstones();
   }
+  /**
+   * Delete leaked `.mtime` sidecar files from the local primary backend
+   * (IndexedDB on browser, Folder on Node).
+   *
+   * Sidecars are produced by backends that keep a precise mtime out-of-band
+   * (RemoteStorage, Gitee…). Once one is copied into the local primary it is
+   * never removed: zen-fs-sync skips `.mtime` paths on both sides, so it is
+   * invisible to sync, and every walk warns about the leak.
+   *
+   * Only the local primary is scanned — replica sidecars are live metadata of
+   * the backend that owns them and must be left alone.
+   *
+   * @param options.root Scan only this subtree (default `/`).
+   * @param options.dryRun List the sidecars without deleting them.
+   */
+  async purgeMtimeSidecars(options) {
+    this.assertNotDisposed();
+    const result = await purgeMtimeSidecars(this.cachedFS, options);
+    if (result.removed.length > 0) {
+      log2.log(
+        `[ConfigRepo] purged ${result.removed.length} .mtime sidecar(s) from local primary` + (options?.dryRun ? " (dry run)" : ""),
+        result.removed
+      );
+    }
+    if (result.failed.length > 0) {
+      log2.warn(`[ConfigRepo] failed to purge ${result.failed.length} .mtime sidecar(s):`, result.failed);
+    }
+    return result;
+  }
   /**
    * Perform a full sync + dedup cycle without the watch snapshot cache.
    * Used by createConfigRepo to pull remote-only files (like duplicate
@@ -1987,6 +2070,17 @@ var AppDataGroupImpl = class {
     } catch {
       throw new Error(`Failed to create local primary for data group "${this.groupId}"`);
     }
+    try {
+      const purged = await purgeMtimeSidecars(this.localFS);
+      if (purged.removed.length > 0) {
+        log2.warn(
+          `[AppDataGroup:${this.groupId}] purged ${purged.removed.length} leaked .mtime sidecar(s):`,
+          purged.removed
+        );
+      }
+    } catch (err) {
+      log2.warn(`[AppDataGroup:${this.groupId}] .mtime purge failed:`, err?.message ?? err);
+    }
     const localSyncable = backendToSyncableFS(this.localFS, `local(${this.groupId})`);
     this.fs = createChrootFS(this.localFS, "/");
     const { kept, removed } = dedupeAppDataBackends(this._backends);
@@ -2113,6 +2207,19 @@ async function createConfigRepo(appId, options = {}) {
   log2.log(`[createConfigRepo] Creating local primary (type: ${localPrimary.type})...`);
   const primaryInstance = await createBackend(localPrimary);
   const cachedFS = primaryInstance;
+  if (options.purgeMtimeSidecars !== false) {
+    try {
+      const purged = await purgeMtimeSidecars(cachedFS);
+      if (purged.removed.length > 0) {
+        log2.warn(
+          `[createConfigRepo] purged ${purged.removed.length} leaked .mtime sidecar(s) from local primary:`,
+          purged.removed
+        );
+      }
+    } catch (err) {
+      log2.warn(`[createConfigRepo] .mtime purge failed:`, err?.message ?? err);
+    }
+  }
   const cacheOptions = options.cache === false ? void 0 : options.cache ?? {};
   try {
     await primaryInstance.mkdir(META_DIR);
@@ -2342,10 +2449,12 @@ export {
   hasBackend,
   incrementVersion,
   isBrowserEnv,
+  isMtimeSidecar,
   listBackendMetadata,
   listBackends,
   localPrimaryType,
   mergeAccountFields,
+  purgeMtimeSidecars,
   readVersion,
   registerBackend,
   registerFolderBackend,

package/dist/zen-fs-config.js

@@ -25111,10 +25111,12 @@ var ZenFSConfig = (() => {
     hasBackend: () => hasBackend,
     incrementVersion: () => incrementVersion,
     isBrowserEnv: () => isBrowserEnv,
+    isMtimeSidecar: () => isMtimeSidecar,
     listBackendMetadata: () => listBackendMetadata,
     listBackends: () => listBackends,
     localPrimaryType: () => localPrimaryType,
     mergeAccountFields: () => mergeAccountFields,
+    purgeMtimeSidecars: () => purgeMtimeSidecars,
     readVersion: () => readVersion,
     registerBackend: () => registerBackend,
     registerFolderBackend: () => registerFolderBackend,
@@ -26915,6 +26917,60 @@ var ZenFSConfig = (() => {
     }
   }
 
+  // src/mtime-cleanup.ts
+  function isMtimeSidecar(fileName) {
+    return fileName.endsWith(".mtime");
+  }
+  var S_IFDIR2 = 16384;
+  function isDirectory3(stat5) {
+    return typeof stat5.mode === "number" && (stat5.mode & S_IFDIR2) === S_IFDIR2;
+  }
+  function joinPath(dir, entry) {
+    if (dir === "/" || dir === "") return `/${entry}`;
+    return `${dir.replace(/\/+$/, "")}/${entry}`;
+  }
+  async function purgeMtimeSidecars(fs, options = {}) {
+    const root = options.root && options.root !== "" ? options.root : "/";
+    const dryRun = options.dryRun ?? false;
+    const result = { scanned: 0, removed: [], failed: [] };
+    const stack = [root];
+    while (stack.length > 0) {
+      const dir = stack.pop();
+      let entries2;
+      try {
+        entries2 = await fs.readdir(dir);
+      } catch {
+        continue;
+      }
+      for (const entry of entries2) {
+        const fullPath = joinPath(dir, entry);
+        let stat5;
+        try {
+          stat5 = await fs.stat(fullPath);
+        } catch {
+          continue;
+        }
+        if (isDirectory3(stat5)) {
+          stack.push(fullPath);
+          continue;
+        }
+        result.scanned++;
+        if (!isMtimeSidecar(entry)) continue;
+        if (dryRun) {
+          result.removed.push(fullPath);
+          continue;
+        }
+        try {
+          await fs.unlink(fullPath);
+          result.removed.push(fullPath);
+        } catch {
+          result.failed.push(fullPath);
+        }
+      }
+    }
+    return result;
+  }
+
   // src/config-repo.ts
   var log6 = createLogger2("zen-fs-config:config-repo");
   var META_DIR = "/.meta";
@@ -27368,6 +27424,35 @@ var ZenFSConfig = (() => {
     async processTombstonesPublic() {
       await this.processTombstones();
     }
+    /**
+     * Delete leaked `.mtime` sidecar files from the local primary backend
+     * (IndexedDB on browser, Folder on Node).
+     *
+     * Sidecars are produced by backends that keep a precise mtime out-of-band
+     * (RemoteStorage, Gitee…). Once one is copied into the local primary it is
+     * never removed: zen-fs-sync skips `.mtime` paths on both sides, so it is
+     * invisible to sync, and every walk warns about the leak.
+     *
+     * Only the local primary is scanned — replica sidecars are live metadata of
+     * the backend that owns them and must be left alone.
+     *
+     * @param options.root Scan only this subtree (default `/`).
+     * @param options.dryRun List the sidecars without deleting them.
+     */
+    async purgeMtimeSidecars(options) {
+      this.assertNotDisposed();
+      const result = await purgeMtimeSidecars(this.cachedFS, options);
+      if (result.removed.length > 0) {
+        log6.log(
+          `[ConfigRepo] purged ${result.removed.length} .mtime sidecar(s) from local primary` + (options?.dryRun ? " (dry run)" : ""),
+          result.removed
+        );
+      }
+      if (result.failed.length > 0) {
+        log6.warn(`[ConfigRepo] failed to purge ${result.failed.length} .mtime sidecar(s):`, result.failed);
+      }
+      return result;
+    }
     /**
      * Perform a full sync + dedup cycle without the watch snapshot cache.
      * Used by createConfigRepo to pull remote-only files (like duplicate
@@ -28289,6 +28374,17 @@ var ZenFSConfig = (() => {
       } catch {
         throw new Error(`Failed to create local primary for data group "${this.groupId}"`);
       }
+      try {
+        const purged = await purgeMtimeSidecars(this.localFS);
+        if (purged.removed.length > 0) {
+          log6.warn(
+            `[AppDataGroup:${this.groupId}] purged ${purged.removed.length} leaked .mtime sidecar(s):`,
+            purged.removed
+          );
+        }
+      } catch (err2) {
+        log6.warn(`[AppDataGroup:${this.groupId}] .mtime purge failed:`, err2?.message ?? err2);
+      }
       const localSyncable = backendToSyncableFS(this.localFS, `local(${this.groupId})`);
       this.fs = createChrootFS(this.localFS, "/");
       const { kept, removed } = dedupeAppDataBackends(this._backends);
@@ -28415,6 +28511,19 @@ var ZenFSConfig = (() => {
     log6.log(`[createConfigRepo] Creating local primary (type: ${localPrimary.type})...`);
     const primaryInstance = await createBackend(localPrimary);
     const cachedFS = primaryInstance;
+    if (options.purgeMtimeSidecars !== false) {
+      try {
+        const purged = await purgeMtimeSidecars(cachedFS);
+        if (purged.removed.length > 0) {
+          log6.warn(
+            `[createConfigRepo] purged ${purged.removed.length} leaked .mtime sidecar(s) from local primary:`,
+            purged.removed
+          );
+        }
+      } catch (err2) {
+        log6.warn(`[createConfigRepo] .mtime purge failed:`, err2?.message ?? err2);
+      }
+    }
     const cacheOptions = options.cache === false ? void 0 : options.cache ?? {};
     try {
       await primaryInstance.mkdir(META_DIR);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zen-fs-config",
-  "version": "0.5.31",
+  "version": "0.5.32",
   "description": "Distributed config management library built on ZenFS, zen-fs-cache, and zen-fs-sync",
   "main": "dist/index.js",
   "module": "dist/index.mjs",