zen-fs-config 0.5.32 → 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;
@@ -57,11 +57,78 @@ 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.
+ * because sidecars live next to their data file as `<name>.mtime` files.
  * 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,30 @@ 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).
+     *
+     * Older builds stored version sidecars as hidden dotfiles (`.db.json.version`).
+     * They are now `<name>.version`. This one-time sweep renames existing legacy
+     * sidecars (preserving version history) and removes the old copy from every
+     * replica so sync does not pull it back.
+     *
+     * Default: `true`. Pass `false` to skip the startup sweep.
+     */
+    migrateVersionSidecars?: boolean;
 }
 /** Type of sync group. */
 type SyncGroupType = 'config-sync' | 'data-sync';
@@ -421,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
@@ -585,6 +687,71 @@ declare function getAccountFields(type: string): string[];
 declare function mergeAccountFields(targetType: string, sourceOptions: Record<string, unknown>, targetOptions: Record<string, unknown>): Record<string, unknown>;
 declare function wrapZenFSFileSystem(config: any): Promise<BackendInstance>;
 
+/**
+ * zen-fs-config — Legacy Version Sidecar Migration
+ *
+ * Version sidecars used to be stored as hidden dotfiles:
+ *
+ *   config file:  /app-a/db.json
+ *   version file: /app-a/.db.json.version        (OLD — starts with `.`)
+ *
+ * They are now stored as `<name>.version` (no leading dot):
+ *
+ *   version file: /app-a/db.json.version         (NEW)
+ *
+ * This module migrates existing legacy sidecars to the new naming at startup,
+ * preserving version history (the file content is byte-identical after rename).
+ *
+ * Ambiguity safety: a legacy path `.x.version` could in theory belong to either
+ * a dotfile config `.x` (whose version is unchanged by the rename) or a
+ * non-dot config `x` (old naming). We resolve it by probing the directory:
+ *   - `.x` exists  → it's the dotfile config's version → NEW path == legacy → skip
+ *   - `x`  exists  → rename legacy `.x.version` → `x.version`
+ *   - neither      → orphan (config gone) → delete
+ *
+ * We also delete the remote residual legacy path from every replica so the
+ * sync engine does not pull the old sidecar back (zen-fs-sync syncs `.version`
+ * files on both ends).
+ */
+/** Minimal async FS surface needed to read/rename/delete on the local primary. */
+interface MigrateLocalFS {
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<{
+        mode?: number;
+    }>;
+    readFile(path: string, encoding?: string): Promise<Uint8Array | string>;
+    writeFile(path: string, data: Uint8Array): Promise<void>;
+    unlink(path: string): Promise<void>;
+}
+/** Minimal async FS surface needed to delete remote residual legacy sidecars. */
+interface MigrateReplicaFS {
+    unlink(path: string): Promise<void>;
+}
+interface VersionMigrationOptions {
+    /** Root to scan. Default: `/` (the whole local primary). */
+    root?: string;
+    /** Report what would change without touching anything. */
+    dryRun?: boolean;
+    /** Replica backends whose legacy sidecars should be deleted. */
+    replicas?: MigrateReplicaFS[];
+}
+interface VersionMigrationResult {
+    /** Local legacy sidecars renamed to the new naming. */
+    renamed: string[];
+    /** Local orphan legacy sidecars deleted (no owning config). */
+    deleted: string[];
+    /** Remote residual legacy sidecars deleted (best-effort). */
+    remoteDeleted: string[];
+    /** Paths that failed to migrate. */
+    failed: string[];
+}
+/**
+ * Walk `fs` from `options.root` and migrate every legacy `.x.version` /
+ * `.x.version.mtime` sidecar to the new `<name>.version` / `<name>.version.mtime`
+ * naming. Best-effort: failures are collected in `failed`, never thrown.
+ */
+declare function migrateVersionSidecars(fs: MigrateLocalFS, options?: VersionMigrationOptions): Promise<VersionMigrationResult>;
+
 /**
  * zen-fs-config — ConfigRepo Implementation
  *
@@ -690,6 +857,28 @@ 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)
+     * and deletes the residual legacy copy from every replica backend so sync
+     * does not pull it back. Best-effort: failures are logged, never thrown.
+     *
+     * Runs once at startup (see createConfigRepo). Safe to call again.
+     */
+    migrateLegacyVersionSidecars(): Promise<VersionMigrationResult>;
     /**
      * Perform a full sync + dedup cycle without the watch snapshot cache.
      * Used by createConfigRepo to pull remote-only files (like duplicate
@@ -876,24 +1065,35 @@ declare function connect(appId: string, options?: ConnectOptions): Promise<Conne
 /**
  * zen-fs-config — Sidecar Version File Management
  *
- * Each config file has a companion .version file for version-based change
- * detection and conflict resolution.
+ * Each config file has a companion `.version` sidecar file for version-based
+ * change detection and conflict resolution. The sidecar is named `<name>.version`
+ * (NOT `.name.version`) so it is not a hidden dotfile.
  *
  * Config file:  /app-a/db.json
- * Version file: /app-a/.db.json.version
+ * Version file: /app-a/db.json.version
  */
 
 /**
  * Compute the sidecar version file path from a config file path.
  *
- * /app-a/db.json        → /app-a/.db.json.version
- * /shared/flags.json    → /shared/.flags.json.version
- * /nodes/s1/env.json    → /nodes/s1/.env.json.version
+ * /app-a/db.json        → /app-a/db.json.version
+ * /shared/flags.json    → /shared/flags.json.version
+ * /nodes/s1/env.json    → /nodes/s1/env.json.version
  *
  * Returns null for files that are already version sidecars (.version files),
- * to prevent creating version-of-version files (e.g. ..db.json.version.version).
+ * to prevent creating version-of-version files (e.g. db.json.version.version).
  */
 declare function versionPathFor(configFilePath: string): string | null;
+/**
+ * Compute the *legacy* (pre-dotfile-removal) version sidecar path for a config
+ * file. Returns the old `.${name}.version` form for non-dot configs, or `null`
+ * for dotfile configs (whose version path is unchanged) and for version files
+ * themselves.
+ *
+ * Used as a read fallback so existing history in `.db.json.version` is still
+ * found after the naming scheme changed to `db.json.version`.
+ */
+declare function legacyVersionPathFor(configFilePath: string): string | null;
 /**
  * Compute SHA-256 hash of a Uint8Array.
  * Returns "sha256:" prefix + hex digest.
@@ -923,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 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 };
+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;
@@ -57,11 +57,78 @@ 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.
+ * because sidecars live next to their data file as `<name>.mtime` files.
  * 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,30 @@ 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).
+     *
+     * Older builds stored version sidecars as hidden dotfiles (`.db.json.version`).
+     * They are now `<name>.version`. This one-time sweep renames existing legacy
+     * sidecars (preserving version history) and removes the old copy from every
+     * replica so sync does not pull it back.
+     *
+     * Default: `true`. Pass `false` to skip the startup sweep.
+     */
+    migrateVersionSidecars?: boolean;
 }
 /** Type of sync group. */
 type SyncGroupType = 'config-sync' | 'data-sync';
@@ -421,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
@@ -585,6 +687,71 @@ declare function getAccountFields(type: string): string[];
 declare function mergeAccountFields(targetType: string, sourceOptions: Record<string, unknown>, targetOptions: Record<string, unknown>): Record<string, unknown>;
 declare function wrapZenFSFileSystem(config: any): Promise<BackendInstance>;
 
+/**
+ * zen-fs-config — Legacy Version Sidecar Migration
+ *
+ * Version sidecars used to be stored as hidden dotfiles:
+ *
+ *   config file:  /app-a/db.json
+ *   version file: /app-a/.db.json.version        (OLD — starts with `.`)
+ *
+ * They are now stored as `<name>.version` (no leading dot):
+ *
+ *   version file: /app-a/db.json.version         (NEW)
+ *
+ * This module migrates existing legacy sidecars to the new naming at startup,
+ * preserving version history (the file content is byte-identical after rename).
+ *
+ * Ambiguity safety: a legacy path `.x.version` could in theory belong to either
+ * a dotfile config `.x` (whose version is unchanged by the rename) or a
+ * non-dot config `x` (old naming). We resolve it by probing the directory:
+ *   - `.x` exists  → it's the dotfile config's version → NEW path == legacy → skip
+ *   - `x`  exists  → rename legacy `.x.version` → `x.version`
+ *   - neither      → orphan (config gone) → delete
+ *
+ * We also delete the remote residual legacy path from every replica so the
+ * sync engine does not pull the old sidecar back (zen-fs-sync syncs `.version`
+ * files on both ends).
+ */
+/** Minimal async FS surface needed to read/rename/delete on the local primary. */
+interface MigrateLocalFS {
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<{
+        mode?: number;
+    }>;
+    readFile(path: string, encoding?: string): Promise<Uint8Array | string>;
+    writeFile(path: string, data: Uint8Array): Promise<void>;
+    unlink(path: string): Promise<void>;
+}
+/** Minimal async FS surface needed to delete remote residual legacy sidecars. */
+interface MigrateReplicaFS {
+    unlink(path: string): Promise<void>;
+}
+interface VersionMigrationOptions {
+    /** Root to scan. Default: `/` (the whole local primary). */
+    root?: string;
+    /** Report what would change without touching anything. */
+    dryRun?: boolean;
+    /** Replica backends whose legacy sidecars should be deleted. */
+    replicas?: MigrateReplicaFS[];
+}
+interface VersionMigrationResult {
+    /** Local legacy sidecars renamed to the new naming. */
+    renamed: string[];
+    /** Local orphan legacy sidecars deleted (no owning config). */
+    deleted: string[];
+    /** Remote residual legacy sidecars deleted (best-effort). */
+    remoteDeleted: string[];
+    /** Paths that failed to migrate. */
+    failed: string[];
+}
+/**
+ * Walk `fs` from `options.root` and migrate every legacy `.x.version` /
+ * `.x.version.mtime` sidecar to the new `<name>.version` / `<name>.version.mtime`
+ * naming. Best-effort: failures are collected in `failed`, never thrown.
+ */
+declare function migrateVersionSidecars(fs: MigrateLocalFS, options?: VersionMigrationOptions): Promise<VersionMigrationResult>;
+
 /**
  * zen-fs-config — ConfigRepo Implementation
  *
@@ -690,6 +857,28 @@ 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)
+     * and deletes the residual legacy copy from every replica backend so sync
+     * does not pull it back. Best-effort: failures are logged, never thrown.
+     *
+     * Runs once at startup (see createConfigRepo). Safe to call again.
+     */
+    migrateLegacyVersionSidecars(): Promise<VersionMigrationResult>;
     /**
      * Perform a full sync + dedup cycle without the watch snapshot cache.
      * Used by createConfigRepo to pull remote-only files (like duplicate
@@ -876,24 +1065,35 @@ declare function connect(appId: string, options?: ConnectOptions): Promise<Conne
 /**
  * zen-fs-config — Sidecar Version File Management
  *
- * Each config file has a companion .version file for version-based change
- * detection and conflict resolution.
+ * Each config file has a companion `.version` sidecar file for version-based
+ * change detection and conflict resolution. The sidecar is named `<name>.version`
+ * (NOT `.name.version`) so it is not a hidden dotfile.
  *
  * Config file:  /app-a/db.json
- * Version file: /app-a/.db.json.version
+ * Version file: /app-a/db.json.version
  */
 
 /**
  * Compute the sidecar version file path from a config file path.
  *
- * /app-a/db.json        → /app-a/.db.json.version
- * /shared/flags.json    → /shared/.flags.json.version
- * /nodes/s1/env.json    → /nodes/s1/.env.json.version
+ * /app-a/db.json        → /app-a/db.json.version
+ * /shared/flags.json    → /shared/flags.json.version
+ * /nodes/s1/env.json    → /nodes/s1/env.json.version
  *
  * Returns null for files that are already version sidecars (.version files),
- * to prevent creating version-of-version files (e.g. ..db.json.version.version).
+ * to prevent creating version-of-version files (e.g. db.json.version.version).
  */
 declare function versionPathFor(configFilePath: string): string | null;
+/**
+ * Compute the *legacy* (pre-dotfile-removal) version sidecar path for a config
+ * file. Returns the old `.${name}.version` form for non-dot configs, or `null`
+ * for dotfile configs (whose version path is unchanged) and for version files
+ * themselves.
+ *
+ * Used as a read fallback so existing history in `.db.json.version` is still
+ * found after the naming scheme changed to `db.json.version`.
+ */
+declare function legacyVersionPathFor(configFilePath: string): string | null;
 /**
  * Compute SHA-256 hash of a Uint8Array.
  * Returns "sha256:" prefix + hex digest.
@@ -923,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 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 };
+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 };