zen-fs-config 0.5.33 → 0.5.34

package/dist/index.d.mts

@@ -25,7 +25,7 @@ import { SyncMapStore, SyncMapTransaction } from '@zenfs/core';
  * deleting them would cost network calls and lose mtime precision.
  */
 /** Minimal async FS surface needed for the purge. */
-interface PurgeableFS {
+interface PurgeableFS$1 {
     readdir(path: string): Promise<string[]>;
     stat(path: string): Promise<{
         mode?: number;
@@ -61,7 +61,74 @@ declare function isMtimeSidecar(fileName: string): boolean;
  * 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>;
+declare function purgeMtimeSidecars(fs: PurgeableFS$1, options?: PurgeMtimeOptions): Promise<MtimePurgeResult>;
+
+/**
+ * zen-fs-config — `.keep` placeholder cleanup (local primary only)
+ *
+ * Backends that cannot store empty directories (Git, RemoteStorage…) keep a
+ * directory alive with an internal `.keep` placeholder — exactly like the
+ * `.mtime` sidecar, this is backend-internal metadata that MUST be hidden from
+ * callers (see zen-fs-sync/docs/SyncableFS.md §1/§2).
+ *
+ * Older builds leaked `.keep` files into the local primary (IndexedDB on
+ * browser, Folder on Node), where they linger forever: the sync engine now
+ * skips `.keep` paths on both sides, so nothing ever removes them, and every
+ * walk re-creates confusion about which directories are "real".
+ *
+ * This module walks the local primary and deletes those leaked `.keep` files.
+ * It never touches replica (remote) backends: their placeholders are live
+ * metadata that keep real (empty) directories alive, and deleting them would
+ * lose directory structure.
+ *
+ * The intentional `.keep` under `/.meta/` (used to keep the backends directory
+ * alive) is protected and never deleted — see `protectedDirs`.
+ */
+/** 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 PurgeKeepOptions {
+    /** Root to scan. Default: `/` (the whole local primary). */
+    root?: string;
+    /** Report what would be deleted without unlinking anything. */
+    dryRun?: boolean;
+    /**
+     * Directories (and their subtrees) whose `.keep` files are NEVER deleted.
+     * Defaults to `['/.meta']` to protect the intentional backends placeholder
+     * that keeps `/.meta/backends` alive.
+     */
+    protectedDirs?: string[];
+}
+interface KeepPurgeResult {
+    /** Files visited during the walk (`.keep` included). */
+    scanned: number;
+    /** Placeholders deleted — or, in dryRun, that would be deleted. */
+    removed: string[];
+    /** Placeholders that could not be deleted (unlink failed). */
+    failed: string[];
+}
+/**
+ * True when a file name is the internal `.keep` directory placeholder.
+ *
+ * Matches exactly `.keep` (the file name), which is the only form produced by
+ * the backends — never a suffix match, so `foo.keep` is left untouched.
+ */
+declare function isKeepFile(fileName: string): boolean;
+/**
+ * Delete every leaked `.keep` placeholder stored in a local primary backend.
+ *
+ * Walks the whole tree from `options.root` — including dotfiles and `/.meta/`
+ * entries — but skips any directory listed in `protectedDirs` (default
+ * `/.meta`) so the intentional backends placeholder survives. Unreadable
+ * entries are skipped; failures on individual files are collected in `failed`
+ * instead of aborting the walk.
+ */
+declare function purgeKeepFiles(fs: PurgeableFS, options?: PurgeKeepOptions): Promise<KeepPurgeResult>;
 
 /** A single backend in the topology. */
 interface BackendDescriptor {
@@ -229,6 +296,18 @@ interface ConfigRepoOptions {
      * Default: `true`. Pass `false` to skip the (local-only) startup sweep.
      */
     purgeMtimeSidecars?: boolean;
+    /**
+     * Delete leaked `.keep` placeholders from the local primary on startup.
+     *
+     * Backends that cannot store empty directories (Gitee, RemoteStorage…) keep a
+     * directory alive with an internal `.keep` placeholder. Older builds copied
+     * those backend-internal files into the local primary, where sync ignores
+     * them — so they linger forever. The intentional `/.meta/backends/.keep` is
+     * always protected.
+     *
+     * Default: `true`. Pass `false` to skip the (local-only) startup sweep.
+     */
+    purgeKeepFiles?: boolean;
     /**
      * Migrate legacy `.x.version` sidecars to the new `<name>.version` naming on
      * startup (rename locally, delete the remote residual).
@@ -433,6 +512,17 @@ interface IConfigRepo {
         root?: string;
         dryRun?: boolean;
     }): Promise<MtimePurgeResult>;
+    /**
+     * Delete leaked `.keep` placeholders from the local primary backend.
+     *
+     * Runs automatically on `createConfigRepo()` unless
+     * `options.purgeKeepFiles === false`. Call it manually to clean a
+     * long-lived store, or with `{ dryRun: true }` to only list them.
+     */
+    purgeKeepFiles(options?: {
+        root?: string;
+        dryRun?: boolean;
+    }): Promise<KeepPurgeResult>;
     /**
      * Create a data-sync group for this app.
      * Each backend can optionally reference a config-sync backend's account
@@ -767,6 +857,19 @@ declare class ConfigRepo implements IConfigRepo {
      * @param options.dryRun List the sidecars without deleting them.
      */
     purgeMtimeSidecars(options?: PurgeMtimeOptions): Promise<MtimePurgeResult>;
+    /**
+     * Delete leaked `.keep` placeholders from the local primary backend.
+     *
+     * Backends that cannot store empty directories (Gitee, RemoteStorage…) keep a
+     * directory alive with an internal `.keep` placeholder. Older builds copied
+     * those backend-internal files into the local primary, where sync ignores
+     * them — so they linger forever. `/.meta/backends/.keep` (intentional) is
+     * protected and never removed.
+     *
+     * @param options.root Scan only this subtree (default `/`).
+     * @param options.dryRun List the placeholders without deleting them.
+     */
+    purgeKeepFiles(options?: PurgeKeepOptions): Promise<KeepPurgeResult>;
     /**
      * Migrate legacy `.x.version` sidecars (old dotfile naming) to the new
      * `<name>.version` naming. Renames local sidecars (preserving content/history)
@@ -1020,4 +1123,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 MigrateLocalFS, type MigrateReplicaFS, type MtimePurgeResult, type PurgeMtimeOptions, type PurgeableFS, type SyncGroupType, type TombstoneMeta, type VersionMeta, type VersionMigrationOptions, type VersionMigrationResult, configKeyToFilePath, connect, createBackend, createConfigRepo, createSerializerChain, getAccountFields, getBackendMetadata, getExtension, hasBackend, incrementVersion, isBrowserEnv, isMtimeSidecar, legacyVersionPathFor, listBackendMetadata, listBackends, localPrimaryType, mergeAccountFields, migrateVersionSidecars, purgeMtimeSidecars, 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, type KeepPurgeResult, LOCAL_IDB_BACKEND_ID, type MigrateLocalFS, type MigrateReplicaFS, type MtimePurgeResult, type PurgeKeepOptions, type PurgeMtimeOptions, type PurgeableFS$1 as PurgeableFS, type SyncGroupType, type TombstoneMeta, type VersionMeta, type VersionMigrationOptions, type VersionMigrationResult, configKeyToFilePath, connect, createBackend, createConfigRepo, createSerializerChain, getAccountFields, getBackendMetadata, getExtension, hasBackend, incrementVersion, isBrowserEnv, isKeepFile, isMtimeSidecar, legacyVersionPathFor, listBackendMetadata, listBackends, localPrimaryType, mergeAccountFields, migrateVersionSidecars, purgeKeepFiles, purgeMtimeSidecars, readVersion, registerBackend, registerFolderBackend, resolveLocalPrimary, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };

package/dist/index.d.ts

@@ -25,7 +25,7 @@ import { SyncMapStore, SyncMapTransaction } from '@zenfs/core';
  * deleting them would cost network calls and lose mtime precision.
  */
 /** Minimal async FS surface needed for the purge. */
-interface PurgeableFS {
+interface PurgeableFS$1 {
     readdir(path: string): Promise<string[]>;
     stat(path: string): Promise<{
         mode?: number;
@@ -61,7 +61,74 @@ declare function isMtimeSidecar(fileName: string): boolean;
  * 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>;
+declare function purgeMtimeSidecars(fs: PurgeableFS$1, options?: PurgeMtimeOptions): Promise<MtimePurgeResult>;
+
+/**
+ * zen-fs-config — `.keep` placeholder cleanup (local primary only)
+ *
+ * Backends that cannot store empty directories (Git, RemoteStorage…) keep a
+ * directory alive with an internal `.keep` placeholder — exactly like the
+ * `.mtime` sidecar, this is backend-internal metadata that MUST be hidden from
+ * callers (see zen-fs-sync/docs/SyncableFS.md §1/§2).
+ *
+ * Older builds leaked `.keep` files into the local primary (IndexedDB on
+ * browser, Folder on Node), where they linger forever: the sync engine now
+ * skips `.keep` paths on both sides, so nothing ever removes them, and every
+ * walk re-creates confusion about which directories are "real".
+ *
+ * This module walks the local primary and deletes those leaked `.keep` files.
+ * It never touches replica (remote) backends: their placeholders are live
+ * metadata that keep real (empty) directories alive, and deleting them would
+ * lose directory structure.
+ *
+ * The intentional `.keep` under `/.meta/` (used to keep the backends directory
+ * alive) is protected and never deleted — see `protectedDirs`.
+ */
+/** 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 PurgeKeepOptions {
+    /** Root to scan. Default: `/` (the whole local primary). */
+    root?: string;
+    /** Report what would be deleted without unlinking anything. */
+    dryRun?: boolean;
+    /**
+     * Directories (and their subtrees) whose `.keep` files are NEVER deleted.
+     * Defaults to `['/.meta']` to protect the intentional backends placeholder
+     * that keeps `/.meta/backends` alive.
+     */
+    protectedDirs?: string[];
+}
+interface KeepPurgeResult {
+    /** Files visited during the walk (`.keep` included). */
+    scanned: number;
+    /** Placeholders deleted — or, in dryRun, that would be deleted. */
+    removed: string[];
+    /** Placeholders that could not be deleted (unlink failed). */
+    failed: string[];
+}
+/**
+ * True when a file name is the internal `.keep` directory placeholder.
+ *
+ * Matches exactly `.keep` (the file name), which is the only form produced by
+ * the backends — never a suffix match, so `foo.keep` is left untouched.
+ */
+declare function isKeepFile(fileName: string): boolean;
+/**
+ * Delete every leaked `.keep` placeholder stored in a local primary backend.
+ *
+ * Walks the whole tree from `options.root` — including dotfiles and `/.meta/`
+ * entries — but skips any directory listed in `protectedDirs` (default
+ * `/.meta`) so the intentional backends placeholder survives. Unreadable
+ * entries are skipped; failures on individual files are collected in `failed`
+ * instead of aborting the walk.
+ */
+declare function purgeKeepFiles(fs: PurgeableFS, options?: PurgeKeepOptions): Promise<KeepPurgeResult>;
 
 /** A single backend in the topology. */
 interface BackendDescriptor {
@@ -229,6 +296,18 @@ interface ConfigRepoOptions {
      * Default: `true`. Pass `false` to skip the (local-only) startup sweep.
      */
     purgeMtimeSidecars?: boolean;
+    /**
+     * Delete leaked `.keep` placeholders from the local primary on startup.
+     *
+     * Backends that cannot store empty directories (Gitee, RemoteStorage…) keep a
+     * directory alive with an internal `.keep` placeholder. Older builds copied
+     * those backend-internal files into the local primary, where sync ignores
+     * them — so they linger forever. The intentional `/.meta/backends/.keep` is
+     * always protected.
+     *
+     * Default: `true`. Pass `false` to skip the (local-only) startup sweep.
+     */
+    purgeKeepFiles?: boolean;
     /**
      * Migrate legacy `.x.version` sidecars to the new `<name>.version` naming on
      * startup (rename locally, delete the remote residual).
@@ -433,6 +512,17 @@ interface IConfigRepo {
         root?: string;
         dryRun?: boolean;
     }): Promise<MtimePurgeResult>;
+    /**
+     * Delete leaked `.keep` placeholders from the local primary backend.
+     *
+     * Runs automatically on `createConfigRepo()` unless
+     * `options.purgeKeepFiles === false`. Call it manually to clean a
+     * long-lived store, or with `{ dryRun: true }` to only list them.
+     */
+    purgeKeepFiles(options?: {
+        root?: string;
+        dryRun?: boolean;
+    }): Promise<KeepPurgeResult>;
     /**
      * Create a data-sync group for this app.
      * Each backend can optionally reference a config-sync backend's account
@@ -767,6 +857,19 @@ declare class ConfigRepo implements IConfigRepo {
      * @param options.dryRun List the sidecars without deleting them.
      */
     purgeMtimeSidecars(options?: PurgeMtimeOptions): Promise<MtimePurgeResult>;
+    /**
+     * Delete leaked `.keep` placeholders from the local primary backend.
+     *
+     * Backends that cannot store empty directories (Gitee, RemoteStorage…) keep a
+     * directory alive with an internal `.keep` placeholder. Older builds copied
+     * those backend-internal files into the local primary, where sync ignores
+     * them — so they linger forever. `/.meta/backends/.keep` (intentional) is
+     * protected and never removed.
+     *
+     * @param options.root Scan only this subtree (default `/`).
+     * @param options.dryRun List the placeholders without deleting them.
+     */
+    purgeKeepFiles(options?: PurgeKeepOptions): Promise<KeepPurgeResult>;
     /**
      * Migrate legacy `.x.version` sidecars (old dotfile naming) to the new
      * `<name>.version` naming. Renames local sidecars (preserving content/history)
@@ -1020,4 +1123,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 MigrateLocalFS, type MigrateReplicaFS, type MtimePurgeResult, type PurgeMtimeOptions, type PurgeableFS, type SyncGroupType, type TombstoneMeta, type VersionMeta, type VersionMigrationOptions, type VersionMigrationResult, configKeyToFilePath, connect, createBackend, createConfigRepo, createSerializerChain, getAccountFields, getBackendMetadata, getExtension, hasBackend, incrementVersion, isBrowserEnv, isMtimeSidecar, legacyVersionPathFor, listBackendMetadata, listBackends, localPrimaryType, mergeAccountFields, migrateVersionSidecars, purgeMtimeSidecars, 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, type KeepPurgeResult, LOCAL_IDB_BACKEND_ID, type MigrateLocalFS, type MigrateReplicaFS, type MtimePurgeResult, type PurgeKeepOptions, type PurgeMtimeOptions, type PurgeableFS$1 as PurgeableFS, type SyncGroupType, type TombstoneMeta, type VersionMeta, type VersionMigrationOptions, type VersionMigrationResult, configKeyToFilePath, connect, createBackend, createConfigRepo, createSerializerChain, getAccountFields, getBackendMetadata, getExtension, hasBackend, incrementVersion, isBrowserEnv, isKeepFile, isMtimeSidecar, legacyVersionPathFor, listBackendMetadata, listBackends, localPrimaryType, mergeAccountFields, migrateVersionSidecars, purgeKeepFiles, purgeMtimeSidecars, readVersion, registerBackend, registerFolderBackend, resolveLocalPrimary, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };

package/dist/index.js

@@ -418,6 +418,7 @@ __export(index_exports, {
   hasBackend: () => hasBackend,
   incrementVersion: () => incrementVersion,
   isBrowserEnv: () => isBrowserEnv,
+  isKeepFile: () => isKeepFile,
   isMtimeSidecar: () => isMtimeSidecar,
   legacyVersionPathFor: () => legacyVersionPathFor,
   listBackendMetadata: () => listBackendMetadata,
@@ -425,6 +426,7 @@ __export(index_exports, {
   localPrimaryType: () => localPrimaryType,
   mergeAccountFields: () => mergeAccountFields,
   migrateVersionSidecars: () => migrateVersionSidecars,
+  purgeKeepFiles: () => purgeKeepFiles,
   purgeMtimeSidecars: () => purgeMtimeSidecars,
   readVersion: () => readVersion,
   registerBackend: () => registerBackend,
@@ -1117,15 +1119,79 @@ async function purgeMtimeSidecars(fs, options = {}) {
   return result;
 }
 
-// src/version-migration.ts
+// src/keep-cleanup.ts
+function isKeepFile(fileName) {
+  return fileName === ".keep";
+}
 var S_IFDIR2 = 16384;
-function isDir(stat) {
+var DEFAULT_PROTECTED_DIRS = ["/.meta"];
+function isDirectory2(stat) {
   return typeof stat.mode === "number" && (stat.mode & S_IFDIR2) === S_IFDIR2;
 }
 function joinPath2(dir, entry) {
   if (dir === "/" || dir === "") return `/${entry}`;
   return `${dir.replace(/\/+$/, "")}/${entry}`;
 }
+function isProtected(fullPath, protectedDirs) {
+  return protectedDirs.some((d) => {
+    const dir = d.endsWith("/") ? d.slice(0, -1) : d;
+    return fullPath === dir || fullPath.startsWith(dir + "/");
+  });
+}
+async function purgeKeepFiles(fs, options = {}) {
+  const root = options.root && options.root !== "" ? options.root : "/";
+  const dryRun = options.dryRun ?? false;
+  const protectedDirs = options.protectedDirs ?? DEFAULT_PROTECTED_DIRS;
+  const result = { scanned: 0, removed: [], failed: [] };
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    if (isProtected(dir, protectedDirs)) continue;
+    let entries;
+    try {
+      entries = await fs.readdir(dir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const fullPath = joinPath2(dir, entry);
+      if (isProtected(fullPath, protectedDirs)) continue;
+      let stat;
+      try {
+        stat = await fs.stat(fullPath);
+      } catch {
+        continue;
+      }
+      if (isDirectory2(stat)) {
+        stack.push(fullPath);
+        continue;
+      }
+      result.scanned++;
+      if (!isKeepFile(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/version-migration.ts
+var S_IFDIR3 = 16384;
+function isDir(stat) {
+  return typeof stat.mode === "number" && (stat.mode & S_IFDIR3) === S_IFDIR3;
+}
+function joinPath3(dir, entry) {
+  if (dir === "/" || dir === "") return `/${entry}`;
+  return `${dir.replace(/\/+$/, "")}/${entry}`;
+}
 async function existsPath(fs, p) {
   try {
     await fs.stat(p);
@@ -1140,8 +1206,8 @@ function configNameFromLegacy(entry) {
 }
 async function resolveTarget(fs, dir, entry) {
   const configName = configNameFromLegacy(entry);
-  const configPath = joinPath2(dir, configName);
-  const dotConfigPath = joinPath2(dir, `.${configName}`);
+  const configPath = joinPath3(dir, configName);
+  const dotConfigPath = joinPath3(dir, `.${configName}`);
   if (await existsPath(fs, dotConfigPath)) {
     return { action: "skip" };
   }
@@ -1170,7 +1236,7 @@ async function migrateVersionSidecars(fs, options = {}) {
       continue;
     }
     for (const entry of entries) {
-      const full = joinPath2(dir, entry);
+      const full = joinPath3(dir, entry);
       let stat;
       try {
         stat = await fs.stat(full);
@@ -1724,6 +1790,32 @@ var ConfigRepo = class {
     }
     return result;
   }
+  /**
+   * Delete leaked `.keep` placeholders from the local primary backend.
+   *
+   * Backends that cannot store empty directories (Gitee, RemoteStorage…) keep a
+   * directory alive with an internal `.keep` placeholder. Older builds copied
+   * those backend-internal files into the local primary, where sync ignores
+   * them — so they linger forever. `/.meta/backends/.keep` (intentional) is
+   * protected and never removed.
+   *
+   * @param options.root Scan only this subtree (default `/`).
+   * @param options.dryRun List the placeholders without deleting them.
+   */
+  async purgeKeepFiles(options) {
+    this.assertNotDisposed();
+    const result = await purgeKeepFiles(this.cachedFS, options);
+    if (result.removed.length > 0) {
+      log2.log(
+        `[ConfigRepo] purged ${result.removed.length} .keep placeholder(s) from local primary` + (options?.dryRun ? " (dry run)" : ""),
+        result.removed
+      );
+    }
+    if (result.failed.length > 0) {
+      log2.warn(`[ConfigRepo] failed to purge ${result.failed.length} .keep placeholder(s):`, result.failed);
+    }
+    return result;
+  }
   /**
    * Migrate legacy `.x.version` sidecars (old dotfile naming) to the new
    * `<name>.version` naming. Renames local sidecars (preserving content/history)
@@ -2694,6 +2786,17 @@ var AppDataGroupImpl = class {
     } catch (err) {
       log2.warn(`[AppDataGroup:${this.groupId}] .mtime purge failed:`, err?.message ?? err);
     }
+    try {
+      const purgedKeep = await purgeKeepFiles(this.localFS);
+      if (purgedKeep.removed.length > 0) {
+        log2.warn(
+          `[AppDataGroup:${this.groupId}] purged ${purgedKeep.removed.length} leaked .keep placeholder(s):`,
+          purgedKeep.removed
+        );
+      }
+    } catch (err) {
+      log2.warn(`[AppDataGroup:${this.groupId}] .keep purge failed:`, err?.message ?? err);
+    }
     const localSyncable = backendToSyncableFS(this.localFS, `local(${this.groupId})`);
     this.fs = createChrootFS(this.localFS, "/");
     const { kept, removed } = dedupeAppDataBackends(this._backends);
@@ -2833,6 +2936,19 @@ async function createConfigRepo(appId, options = {}) {
       log2.warn(`[createConfigRepo] .mtime purge failed:`, err?.message ?? err);
     }
   }
+  if (options.purgeKeepFiles !== false) {
+    try {
+      const purged = await purgeKeepFiles(cachedFS);
+      if (purged.removed.length > 0) {
+        log2.warn(
+          `[createConfigRepo] purged ${purged.removed.length} leaked .keep placeholder(s) from local primary:`,
+          purged.removed
+        );
+      }
+    } catch (err) {
+      log2.warn(`[createConfigRepo] .keep purge failed:`, err?.message ?? err);
+    }
+  }
   const cacheOptions = options.cache === false ? void 0 : options.cache ?? {};
   try {
     await primaryInstance.mkdir(META_DIR);
@@ -3077,6 +3193,7 @@ init_backend_registry();
   hasBackend,
   incrementVersion,
   isBrowserEnv,
+  isKeepFile,
   isMtimeSidecar,
   legacyVersionPathFor,
   listBackendMetadata,
@@ -3084,6 +3201,7 @@ init_backend_registry();
   localPrimaryType,
   mergeAccountFields,
   migrateVersionSidecars,
+  purgeKeepFiles,
   purgeMtimeSidecars,
   readVersion,
   registerBackend,

package/dist/index.mjs

@@ -688,15 +688,79 @@ async function purgeMtimeSidecars(fs, options = {}) {
   return result;
 }
 
-// src/version-migration.ts
+// src/keep-cleanup.ts
+function isKeepFile(fileName) {
+  return fileName === ".keep";
+}
 var S_IFDIR2 = 16384;
-function isDir(stat) {
+var DEFAULT_PROTECTED_DIRS = ["/.meta"];
+function isDirectory2(stat) {
   return typeof stat.mode === "number" && (stat.mode & S_IFDIR2) === S_IFDIR2;
 }
 function joinPath2(dir, entry) {
   if (dir === "/" || dir === "") return `/${entry}`;
   return `${dir.replace(/\/+$/, "")}/${entry}`;
 }
+function isProtected(fullPath, protectedDirs) {
+  return protectedDirs.some((d) => {
+    const dir = d.endsWith("/") ? d.slice(0, -1) : d;
+    return fullPath === dir || fullPath.startsWith(dir + "/");
+  });
+}
+async function purgeKeepFiles(fs, options = {}) {
+  const root = options.root && options.root !== "" ? options.root : "/";
+  const dryRun = options.dryRun ?? false;
+  const protectedDirs = options.protectedDirs ?? DEFAULT_PROTECTED_DIRS;
+  const result = { scanned: 0, removed: [], failed: [] };
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    if (isProtected(dir, protectedDirs)) continue;
+    let entries;
+    try {
+      entries = await fs.readdir(dir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const fullPath = joinPath2(dir, entry);
+      if (isProtected(fullPath, protectedDirs)) continue;
+      let stat;
+      try {
+        stat = await fs.stat(fullPath);
+      } catch {
+        continue;
+      }
+      if (isDirectory2(stat)) {
+        stack.push(fullPath);
+        continue;
+      }
+      result.scanned++;
+      if (!isKeepFile(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/version-migration.ts
+var S_IFDIR3 = 16384;
+function isDir(stat) {
+  return typeof stat.mode === "number" && (stat.mode & S_IFDIR3) === S_IFDIR3;
+}
+function joinPath3(dir, entry) {
+  if (dir === "/" || dir === "") return `/${entry}`;
+  return `${dir.replace(/\/+$/, "")}/${entry}`;
+}
 async function existsPath(fs, p) {
   try {
     await fs.stat(p);
@@ -711,8 +775,8 @@ function configNameFromLegacy(entry) {
 }
 async function resolveTarget(fs, dir, entry) {
   const configName = configNameFromLegacy(entry);
-  const configPath = joinPath2(dir, configName);
-  const dotConfigPath = joinPath2(dir, `.${configName}`);
+  const configPath = joinPath3(dir, configName);
+  const dotConfigPath = joinPath3(dir, `.${configName}`);
   if (await existsPath(fs, dotConfigPath)) {
     return { action: "skip" };
   }
@@ -741,7 +805,7 @@ async function migrateVersionSidecars(fs, options = {}) {
       continue;
     }
     for (const entry of entries) {
-      const full = joinPath2(dir, entry);
+      const full = joinPath3(dir, entry);
       let stat;
       try {
         stat = await fs.stat(full);
@@ -1295,6 +1359,32 @@ var ConfigRepo = class {
     }
     return result;
   }
+  /**
+   * Delete leaked `.keep` placeholders from the local primary backend.
+   *
+   * Backends that cannot store empty directories (Gitee, RemoteStorage…) keep a
+   * directory alive with an internal `.keep` placeholder. Older builds copied
+   * those backend-internal files into the local primary, where sync ignores
+   * them — so they linger forever. `/.meta/backends/.keep` (intentional) is
+   * protected and never removed.
+   *
+   * @param options.root Scan only this subtree (default `/`).
+   * @param options.dryRun List the placeholders without deleting them.
+   */
+  async purgeKeepFiles(options) {
+    this.assertNotDisposed();
+    const result = await purgeKeepFiles(this.cachedFS, options);
+    if (result.removed.length > 0) {
+      log2.log(
+        `[ConfigRepo] purged ${result.removed.length} .keep placeholder(s) from local primary` + (options?.dryRun ? " (dry run)" : ""),
+        result.removed
+      );
+    }
+    if (result.failed.length > 0) {
+      log2.warn(`[ConfigRepo] failed to purge ${result.failed.length} .keep placeholder(s):`, result.failed);
+    }
+    return result;
+  }
   /**
    * Migrate legacy `.x.version` sidecars (old dotfile naming) to the new
    * `<name>.version` naming. Renames local sidecars (preserving content/history)
@@ -2265,6 +2355,17 @@ var AppDataGroupImpl = class {
     } catch (err) {
       log2.warn(`[AppDataGroup:${this.groupId}] .mtime purge failed:`, err?.message ?? err);
     }
+    try {
+      const purgedKeep = await purgeKeepFiles(this.localFS);
+      if (purgedKeep.removed.length > 0) {
+        log2.warn(
+          `[AppDataGroup:${this.groupId}] purged ${purgedKeep.removed.length} leaked .keep placeholder(s):`,
+          purgedKeep.removed
+        );
+      }
+    } catch (err) {
+      log2.warn(`[AppDataGroup:${this.groupId}] .keep purge failed:`, err?.message ?? err);
+    }
     const localSyncable = backendToSyncableFS(this.localFS, `local(${this.groupId})`);
     this.fs = createChrootFS(this.localFS, "/");
     const { kept, removed } = dedupeAppDataBackends(this._backends);
@@ -2404,6 +2505,19 @@ async function createConfigRepo(appId, options = {}) {
       log2.warn(`[createConfigRepo] .mtime purge failed:`, err?.message ?? err);
     }
   }
+  if (options.purgeKeepFiles !== false) {
+    try {
+      const purged = await purgeKeepFiles(cachedFS);
+      if (purged.removed.length > 0) {
+        log2.warn(
+          `[createConfigRepo] purged ${purged.removed.length} leaked .keep placeholder(s) from local primary:`,
+          purged.removed
+        );
+      }
+    } catch (err) {
+      log2.warn(`[createConfigRepo] .keep purge failed:`, err?.message ?? err);
+    }
+  }
   const cacheOptions = options.cache === false ? void 0 : options.cache ?? {};
   try {
     await primaryInstance.mkdir(META_DIR);
@@ -2643,6 +2757,7 @@ export {
   hasBackend,
   incrementVersion,
   isBrowserEnv,
+  isKeepFile,
   isMtimeSidecar,
   legacyVersionPathFor,
   listBackendMetadata,
@@ -2650,6 +2765,7 @@ export {
   localPrimaryType,
   mergeAccountFields,
   migrateVersionSidecars,
+  purgeKeepFiles,
   purgeMtimeSidecars,
   readVersion,
   registerBackend,

package/dist/zen-fs-config.js

@@ -25111,6 +25111,7 @@ var ZenFSConfig = (() => {
     hasBackend: () => hasBackend,
     incrementVersion: () => incrementVersion,
     isBrowserEnv: () => isBrowserEnv,
+    isKeepFile: () => isKeepFile,
     isMtimeSidecar: () => isMtimeSidecar,
     legacyVersionPathFor: () => legacyVersionPathFor,
     listBackendMetadata: () => listBackendMetadata,
@@ -25118,6 +25119,7 @@ var ZenFSConfig = (() => {
     localPrimaryType: () => localPrimaryType,
     mergeAccountFields: () => mergeAccountFields,
     migrateVersionSidecars: () => migrateVersionSidecars,
+    purgeKeepFiles: () => purgeKeepFiles,
     purgeMtimeSidecars: () => purgeMtimeSidecars,
     readVersion: () => readVersion,
     registerBackend: () => registerBackend,
@@ -26994,15 +26996,79 @@ var ZenFSConfig = (() => {
     return result;
   }
 
-  // src/version-migration.ts
+  // src/keep-cleanup.ts
+  function isKeepFile(fileName) {
+    return fileName === ".keep";
+  }
   var S_IFDIR3 = 16384;
-  function isDir(stat5) {
+  var DEFAULT_PROTECTED_DIRS = ["/.meta"];
+  function isDirectory4(stat5) {
     return typeof stat5.mode === "number" && (stat5.mode & S_IFDIR3) === S_IFDIR3;
   }
   function joinPath2(dir, entry) {
     if (dir === "/" || dir === "") return `/${entry}`;
     return `${dir.replace(/\/+$/, "")}/${entry}`;
   }
+  function isProtected(fullPath, protectedDirs) {
+    return protectedDirs.some((d) => {
+      const dir = d.endsWith("/") ? d.slice(0, -1) : d;
+      return fullPath === dir || fullPath.startsWith(dir + "/");
+    });
+  }
+  async function purgeKeepFiles(fs, options = {}) {
+    const root = options.root && options.root !== "" ? options.root : "/";
+    const dryRun = options.dryRun ?? false;
+    const protectedDirs = options.protectedDirs ?? DEFAULT_PROTECTED_DIRS;
+    const result = { scanned: 0, removed: [], failed: [] };
+    const stack = [root];
+    while (stack.length > 0) {
+      const dir = stack.pop();
+      if (isProtected(dir, protectedDirs)) continue;
+      let entries2;
+      try {
+        entries2 = await fs.readdir(dir);
+      } catch {
+        continue;
+      }
+      for (const entry of entries2) {
+        const fullPath = joinPath2(dir, entry);
+        if (isProtected(fullPath, protectedDirs)) continue;
+        let stat5;
+        try {
+          stat5 = await fs.stat(fullPath);
+        } catch {
+          continue;
+        }
+        if (isDirectory4(stat5)) {
+          stack.push(fullPath);
+          continue;
+        }
+        result.scanned++;
+        if (!isKeepFile(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/version-migration.ts
+  var S_IFDIR4 = 16384;
+  function isDir(stat5) {
+    return typeof stat5.mode === "number" && (stat5.mode & S_IFDIR4) === S_IFDIR4;
+  }
+  function joinPath3(dir, entry) {
+    if (dir === "/" || dir === "") return `/${entry}`;
+    return `${dir.replace(/\/+$/, "")}/${entry}`;
+  }
   async function existsPath(fs, p) {
     try {
       await fs.stat(p);
@@ -27017,8 +27083,8 @@ var ZenFSConfig = (() => {
   }
   async function resolveTarget(fs, dir, entry) {
     const configName = configNameFromLegacy(entry);
-    const configPath = joinPath2(dir, configName);
-    const dotConfigPath = joinPath2(dir, `.${configName}`);
+    const configPath = joinPath3(dir, configName);
+    const dotConfigPath = joinPath3(dir, `.${configName}`);
     if (await existsPath(fs, dotConfigPath)) {
       return { action: "skip" };
     }
@@ -27047,7 +27113,7 @@ var ZenFSConfig = (() => {
         continue;
       }
       for (const entry of entries2) {
-        const full = joinPath2(dir, entry);
+        const full = joinPath3(dir, entry);
         let stat5;
         try {
           stat5 = await fs.stat(full);
@@ -27601,6 +27667,32 @@ var ZenFSConfig = (() => {
       }
       return result;
     }
+    /**
+     * Delete leaked `.keep` placeholders from the local primary backend.
+     *
+     * Backends that cannot store empty directories (Gitee, RemoteStorage…) keep a
+     * directory alive with an internal `.keep` placeholder. Older builds copied
+     * those backend-internal files into the local primary, where sync ignores
+     * them — so they linger forever. `/.meta/backends/.keep` (intentional) is
+     * protected and never removed.
+     *
+     * @param options.root Scan only this subtree (default `/`).
+     * @param options.dryRun List the placeholders without deleting them.
+     */
+    async purgeKeepFiles(options) {
+      this.assertNotDisposed();
+      const result = await purgeKeepFiles(this.cachedFS, options);
+      if (result.removed.length > 0) {
+        log6.log(
+          `[ConfigRepo] purged ${result.removed.length} .keep placeholder(s) from local primary` + (options?.dryRun ? " (dry run)" : ""),
+          result.removed
+        );
+      }
+      if (result.failed.length > 0) {
+        log6.warn(`[ConfigRepo] failed to purge ${result.failed.length} .keep placeholder(s):`, result.failed);
+      }
+      return result;
+    }
     /**
      * Migrate legacy `.x.version` sidecars (old dotfile naming) to the new
      * `<name>.version` naming. Renames local sidecars (preserving content/history)
@@ -28571,6 +28663,17 @@ var ZenFSConfig = (() => {
       } catch (err2) {
         log6.warn(`[AppDataGroup:${this.groupId}] .mtime purge failed:`, err2?.message ?? err2);
       }
+      try {
+        const purgedKeep = await purgeKeepFiles(this.localFS);
+        if (purgedKeep.removed.length > 0) {
+          log6.warn(
+            `[AppDataGroup:${this.groupId}] purged ${purgedKeep.removed.length} leaked .keep placeholder(s):`,
+            purgedKeep.removed
+          );
+        }
+      } catch (err2) {
+        log6.warn(`[AppDataGroup:${this.groupId}] .keep purge failed:`, err2?.message ?? err2);
+      }
       const localSyncable = backendToSyncableFS(this.localFS, `local(${this.groupId})`);
       this.fs = createChrootFS(this.localFS, "/");
       const { kept, removed } = dedupeAppDataBackends(this._backends);
@@ -28710,6 +28813,19 @@ var ZenFSConfig = (() => {
         log6.warn(`[createConfigRepo] .mtime purge failed:`, err2?.message ?? err2);
       }
     }
+    if (options.purgeKeepFiles !== false) {
+      try {
+        const purged = await purgeKeepFiles(cachedFS);
+        if (purged.removed.length > 0) {
+          log6.warn(
+            `[createConfigRepo] purged ${purged.removed.length} leaked .keep placeholder(s) from local primary:`,
+            purged.removed
+          );
+        }
+      } catch (err2) {
+        log6.warn(`[createConfigRepo] .keep 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.33",
+  "version": "0.5.34",
   "description": "Distributed config management library built on ZenFS, zen-fs-cache, and zen-fs-sync",
   "main": "dist/index.js",
   "module": "dist/index.mjs",