zen-fs-config 0.5.44 → 0.5.46

package/dist/index.d.mts

@@ -345,8 +345,30 @@ interface AppDataBackendDescriptor {
 interface AppDataGroupDescriptor {
     id: string;
     groupType: 'data-sync';
+    /** User-editable display name. `id` is the stable identifier. */
+    name?: string;
     backends: AppDataBackendDescriptor[];
 }
+/** Descriptor for the config-sync group itself (display metadata only). */
+interface ConfigSyncGroupDescriptor {
+    groupType: 'config-sync';
+    /** User-editable display name. The group has no separate id. */
+    name?: string;
+}
+/** Per-backend sync state of a data group. */
+interface BackendSyncState {
+    backendId: string;
+    /** Pair id when the backend instance was created and paired successfully. */
+    pairId?: string;
+    /**
+     * Present when this descriptor could not be connected (e.g. a required
+     * option is missing), so no sync pair exists for it.
+     */
+    error?: {
+        message: string;
+        timestamp: number;
+    };
+}
 /** Handle to a data-sync group, providing direct fs access. */
 interface AppDataGroup {
     readonly groupId: string;
@@ -355,6 +377,11 @@ interface AppDataGroup {
     readonly fs: typeof node_fs;
     /** Get sync status for this data group's sync pairs. */
     getSyncStatuses(): Map<string, SyncPairStatus>;
+    /**
+     * Per-backend sync state, including descriptors that failed to connect and
+     * therefore have no pair (they do not appear in getSyncStatuses()).
+     */
+    getBackendSyncStates(): Map<string, BackendSyncState>;
     /** Manually flush pending sync. */
     flush(): Promise<SyncResult[]>;
     /** Stop sync and release resources. */
@@ -536,6 +563,20 @@ interface IConfigRepo {
     getAppDataGroup(id: string): Promise<AppDataGroup>;
     /** List all data-sync group descriptors for this app. */
     listAppDataGroups(): Promise<AppDataGroupDescriptor[]>;
+    /**
+     * Update a data-sync group's display name (descriptor-only; id, backends,
+     * local and remote data are untouched). Empty/oversized names are rejected.
+     */
+    updateAppDataGroupName(id: string, name: string): Promise<void>;
+    /** Read the config-sync group's display descriptor (may be absent). */
+    getConfigSyncGroupDescriptor(): Promise<ConfigSyncGroupDescriptor | null>;
+    /**
+     * Update the config-sync group's display name (descriptor-only; backends,
+     * local store and remote data are untouched).
+     */
+    updateConfigSyncGroupDescriptor(patch: {
+        name: string;
+    }): Promise<ConfigSyncGroupDescriptor>;
     /** Remove a data-sync group (stops sync, removes descriptor). */
     removeAppDataGroup(id: string): Promise<void>;
     /**
@@ -986,6 +1027,20 @@ declare class ConfigRepo implements IConfigRepo {
      * authoritative source of the data group's backend topology (FR2.3).
      */
     updateAppDataGroupDescriptor(id: string, backends: AppDataBackendDescriptor[]): Promise<void>;
+    /**
+     * Change a data-sync group's display name only. `id`, backends, local stores
+     * and remote data are untouched, so existing sync pairs keep working.
+     */
+    updateAppDataGroupName(id: string, name: string): Promise<void>;
+    getConfigSyncGroupDescriptor(): Promise<ConfigSyncGroupDescriptor | null>;
+    /**
+     * Change the config-sync group's display name only. Backends, the local
+     * store and remote data are untouched.
+     */
+    updateConfigSyncGroupDescriptor(patch: {
+        name: string;
+    }): Promise<ConfigSyncGroupDescriptor>;
+    private readAppDataGroupDescriptor;
     getAppDataGroup(id: string): Promise<AppDataGroup>;
     listAppDataGroups(): Promise<AppDataGroupDescriptor[]>;
     removeAppDataGroup(id: string): Promise<void>;
@@ -1141,4 +1196,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, 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 };
+export { type AppDataBackendDescriptor, type AppDataGroup, type AppDataGroupDescriptor, type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendMetadata, type BackendParamDef, type BackendSyncState, type BackendsMeta, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConfigSyncGroupDescriptor, 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

@@ -345,8 +345,30 @@ interface AppDataBackendDescriptor {
 interface AppDataGroupDescriptor {
     id: string;
     groupType: 'data-sync';
+    /** User-editable display name. `id` is the stable identifier. */
+    name?: string;
     backends: AppDataBackendDescriptor[];
 }
+/** Descriptor for the config-sync group itself (display metadata only). */
+interface ConfigSyncGroupDescriptor {
+    groupType: 'config-sync';
+    /** User-editable display name. The group has no separate id. */
+    name?: string;
+}
+/** Per-backend sync state of a data group. */
+interface BackendSyncState {
+    backendId: string;
+    /** Pair id when the backend instance was created and paired successfully. */
+    pairId?: string;
+    /**
+     * Present when this descriptor could not be connected (e.g. a required
+     * option is missing), so no sync pair exists for it.
+     */
+    error?: {
+        message: string;
+        timestamp: number;
+    };
+}
 /** Handle to a data-sync group, providing direct fs access. */
 interface AppDataGroup {
     readonly groupId: string;
@@ -355,6 +377,11 @@ interface AppDataGroup {
     readonly fs: typeof node_fs;
     /** Get sync status for this data group's sync pairs. */
     getSyncStatuses(): Map<string, SyncPairStatus>;
+    /**
+     * Per-backend sync state, including descriptors that failed to connect and
+     * therefore have no pair (they do not appear in getSyncStatuses()).
+     */
+    getBackendSyncStates(): Map<string, BackendSyncState>;
     /** Manually flush pending sync. */
     flush(): Promise<SyncResult[]>;
     /** Stop sync and release resources. */
@@ -536,6 +563,20 @@ interface IConfigRepo {
     getAppDataGroup(id: string): Promise<AppDataGroup>;
     /** List all data-sync group descriptors for this app. */
     listAppDataGroups(): Promise<AppDataGroupDescriptor[]>;
+    /**
+     * Update a data-sync group's display name (descriptor-only; id, backends,
+     * local and remote data are untouched). Empty/oversized names are rejected.
+     */
+    updateAppDataGroupName(id: string, name: string): Promise<void>;
+    /** Read the config-sync group's display descriptor (may be absent). */
+    getConfigSyncGroupDescriptor(): Promise<ConfigSyncGroupDescriptor | null>;
+    /**
+     * Update the config-sync group's display name (descriptor-only; backends,
+     * local store and remote data are untouched).
+     */
+    updateConfigSyncGroupDescriptor(patch: {
+        name: string;
+    }): Promise<ConfigSyncGroupDescriptor>;
     /** Remove a data-sync group (stops sync, removes descriptor). */
     removeAppDataGroup(id: string): Promise<void>;
     /**
@@ -986,6 +1027,20 @@ declare class ConfigRepo implements IConfigRepo {
      * authoritative source of the data group's backend topology (FR2.3).
      */
     updateAppDataGroupDescriptor(id: string, backends: AppDataBackendDescriptor[]): Promise<void>;
+    /**
+     * Change a data-sync group's display name only. `id`, backends, local stores
+     * and remote data are untouched, so existing sync pairs keep working.
+     */
+    updateAppDataGroupName(id: string, name: string): Promise<void>;
+    getConfigSyncGroupDescriptor(): Promise<ConfigSyncGroupDescriptor | null>;
+    /**
+     * Change the config-sync group's display name only. Backends, the local
+     * store and remote data are untouched.
+     */
+    updateConfigSyncGroupDescriptor(patch: {
+        name: string;
+    }): Promise<ConfigSyncGroupDescriptor>;
+    private readAppDataGroupDescriptor;
     getAppDataGroup(id: string): Promise<AppDataGroup>;
     listAppDataGroups(): Promise<AppDataGroupDescriptor[]>;
     removeAppDataGroup(id: string): Promise<void>;
@@ -1141,4 +1196,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, 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 };
+export { type AppDataBackendDescriptor, type AppDataGroup, type AppDataGroupDescriptor, type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendMetadata, type BackendParamDef, type BackendSyncState, type BackendsMeta, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConfigSyncGroupDescriptor, 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

@@ -1424,10 +1424,25 @@ var GROUP_TYPE_FILE = `${META_DIR}/group-type`;
 var BACKENDS_FILE = `${META_DIR}/backends.json`;
 var BACKENDS_DIR = `${META_DIR}/backends`;
 var APP_DATA_GROUPS_DIR = `${META_DIR}/app-data-groups`;
+var CONFIG_SYNC_GROUP_FILE = `${META_DIR}/config-sync-group.json`;
+var GROUP_NAME_MAX_LENGTH = 40;
 var CONFLICTS_DIR = `${META_DIR}/.conflicts`;
 var DELETIONS_DIR = `${META_DIR}/.deleted`;
 var NODES_DIR = "/nodes";
 var SHARED_DIR = "/shared";
+function normalizeGroupName(value) {
+  if (typeof value !== "string") {
+    throw new Error("Group name must be a string");
+  }
+  const name = value.trim();
+  if (!name) {
+    throw new Error("Group name must not be empty");
+  }
+  if (name.length > GROUP_NAME_MAX_LENGTH) {
+    throw new Error(`Group name must be at most ${GROUP_NAME_MAX_LENGTH} characters`);
+  }
+  return name;
+}
 var CONFIG_ONLY_PREFIXES = [META_DIR, NODES_DIR, SHARED_DIR];
 var LOCAL_IDB_BACKEND_ID = "local-idb";
 function tombstoneFileName(filePath) {
@@ -2783,9 +2798,11 @@ var ConfigRepo = class {
    */
   async updateAppDataGroupDescriptor(id, backends) {
     this.assertNotDisposed();
+    const existing = await this.readAppDataGroupDescriptor(id);
     const descriptor = {
       id,
       groupType: "data-sync",
+      ...existing?.name ? { name: existing.name } : {},
       backends
     };
     const descPath = this.appDataGroupFilePath(id);
@@ -2796,6 +2813,73 @@ var ConfigRepo = class {
     const version = await incrementVersion(this.fullFS, descPath, bytes, author);
     await this.writeVersionSidecar(descPath, version);
   }
+  /**
+   * Change a data-sync group's display name only. `id`, backends, local stores
+   * and remote data are untouched, so existing sync pairs keep working.
+   */
+  async updateAppDataGroupName(id, name) {
+    this.assertNotDisposed();
+    const normalized = normalizeGroupName(name);
+    const existing = await this.readAppDataGroupDescriptor(id);
+    if (!existing) {
+      throw new Error(`App data group "${id}" not found`);
+    }
+    const descriptor = {
+      ...existing,
+      id,
+      groupType: "data-sync",
+      name: normalized
+    };
+    const descPath = this.appDataGroupFilePath(id);
+    await this.ensureDir(descPath);
+    const bytes = new TextEncoder().encode(JSON.stringify(descriptor, null, 2));
+    await this.cachedFS.writeFile(descPath, bytes);
+    const author = `${this.appId}/${this.nodeId}`;
+    const version = await incrementVersion(this.fullFS, descPath, bytes, author);
+    await this.writeVersionSidecar(descPath, version);
+  }
+  async getConfigSyncGroupDescriptor() {
+    this.assertNotDisposed();
+    try {
+      const raw = await this.cachedFS.readFile(CONFIG_SYNC_GROUP_FILE);
+      const parsed = JSON.parse(new TextDecoder().decode(toUint8Array2(raw)));
+      if (parsed && parsed.groupType === "config-sync") {
+        return parsed;
+      }
+    } catch {
+    }
+    return null;
+  }
+  /**
+   * Change the config-sync group's display name only. Backends, the local
+   * store and remote data are untouched.
+   */
+  async updateConfigSyncGroupDescriptor(patch) {
+    this.assertNotDisposed();
+    const normalized = normalizeGroupName(patch?.name);
+    const descriptor = {
+      groupType: "config-sync",
+      name: normalized
+    };
+    await this.ensureDir(CONFIG_SYNC_GROUP_FILE);
+    const bytes = new TextEncoder().encode(JSON.stringify(descriptor, null, 2));
+    await this.cachedFS.writeFile(CONFIG_SYNC_GROUP_FILE, bytes);
+    const author = `${this.appId}/${this.nodeId}`;
+    const version = await incrementVersion(this.fullFS, CONFIG_SYNC_GROUP_FILE, bytes, author);
+    await this.writeVersionSidecar(CONFIG_SYNC_GROUP_FILE, version);
+    return descriptor;
+  }
+  async readAppDataGroupDescriptor(id) {
+    try {
+      const raw = await this.cachedFS.readFile(this.appDataGroupFilePath(id));
+      const parsed = JSON.parse(new TextDecoder().decode(toUint8Array2(raw)));
+      if (parsed && parsed.id === id && parsed.groupType === "data-sync") {
+        return parsed;
+      }
+    } catch {
+    }
+    return null;
+  }
   async getAppDataGroup(id) {
     this.assertNotDisposed();
     const cached = this.appDataGroups.get(id);
@@ -2885,6 +2969,7 @@ var AppDataGroupImpl = class {
   syncEngine;
   localFS;
   dataBackends = /* @__PURE__ */ new Map();
+  backendStates = /* @__PURE__ */ new Map();
   disposed = false;
   constructor(groupId, appId, backends, pollIntervalMs, parent) {
     this.groupId = groupId;
@@ -2957,8 +3042,14 @@ var AppDataGroupImpl = class {
           "/"
         );
         this.dataBackends.set(desc.id, { instance, syncable, pairId: pair.pairId, desc });
+        this.backendStates.set(desc.id, { backendId: desc.id, pairId: pair.pairId });
         log2.log(`[AppDataGroup:${this.groupId}] backend ${desc.id} (${desc.type}) connected, pair=${pair.pairId}`);
       } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        this.backendStates.set(desc.id, {
+          backendId: desc.id,
+          error: { message, timestamp: Date.now() }
+        });
         log2.error(`[AppDataGroup:${this.groupId}] Failed to create backend ${desc.id} (${desc.type}):`, err);
       }
     }
@@ -2983,6 +3074,9 @@ var AppDataGroupImpl = class {
     const results = await this.syncEngine.syncAll();
     return Array.from(results.values());
   }
+  getBackendSyncStates() {
+    return new Map(this.backendStates);
+  }
   async addBackend(id, type, options, description) {
     if (this.disposed) throw new Error("DataSyncGroup has been disposed");
     if (this.dataBackends.has(id)) {
@@ -3005,6 +3099,8 @@ var AppDataGroupImpl = class {
     );
     const desc = { id, type, options, description, createdAt: Date.now() };
     this.dataBackends.set(id, { instance, syncable, pairId: pair.pairId, desc });
+    this.backendStates.set(id, { backendId: id, pairId: pair.pairId });
+    this._backends = [...this._backends.filter((b) => b.id !== id), desc];
     log2.log(`[AppDataGroup:${this.groupId}] addBackend: ${id} (${type}) connected, pair=${pair.pairId}`);
     try {
       await this.syncEngine.sync(pair.pairId);
@@ -3012,18 +3108,23 @@ var AppDataGroupImpl = class {
       log2.warn(`[AppDataGroup:${this.groupId}] addBackend: initial sync failed for ${id}:`, err);
     }
     this.syncEngine.watch(pair.pairId);
-    await this.parent.updateAppDataGroupDescriptor(this.groupId, this.listBackends());
+    await this.parent.updateAppDataGroupDescriptor(this.groupId, this._backends);
   }
   async removeBackend(id) {
     if (this.disposed) throw new Error("DataSyncGroup has been disposed");
     const backend = this.dataBackends.get(id);
-    if (!backend) {
+    const desc = this._backends.find((b) => b.id === id);
+    if (!backend && !desc) {
       throw new Error(`Backend "${id}" not found in data group "${this.groupId}"`);
     }
-    this.syncEngine.removePair(backend.pairId);
-    this.dataBackends.delete(id);
-    await this.parent.updateAppDataGroupDescriptor(this.groupId, this.listBackends());
-    if (backend.instance?.dispose) {
+    if (backend) {
+      this.syncEngine.removePair(backend.pairId);
+      this.dataBackends.delete(id);
+    }
+    this.backendStates.delete(id);
+    this._backends = this._backends.filter((b) => b.id !== id);
+    await this.parent.updateAppDataGroupDescriptor(this.groupId, this._backends);
+    if (backend?.instance?.dispose) {
       await backend.instance.dispose();
     }
     log2.log(`[AppDataGroup:${this.groupId}] removeBackend: ${id} removed`);

package/dist/index.mjs

@@ -884,10 +884,25 @@ var GROUP_TYPE_FILE = `${META_DIR}/group-type`;
 var BACKENDS_FILE = `${META_DIR}/backends.json`;
 var BACKENDS_DIR = `${META_DIR}/backends`;
 var APP_DATA_GROUPS_DIR = `${META_DIR}/app-data-groups`;
+var CONFIG_SYNC_GROUP_FILE = `${META_DIR}/config-sync-group.json`;
+var GROUP_NAME_MAX_LENGTH = 40;
 var CONFLICTS_DIR = `${META_DIR}/.conflicts`;
 var DELETIONS_DIR = `${META_DIR}/.deleted`;
 var NODES_DIR = "/nodes";
 var SHARED_DIR = "/shared";
+function normalizeGroupName(value) {
+  if (typeof value !== "string") {
+    throw new Error("Group name must be a string");
+  }
+  const name = value.trim();
+  if (!name) {
+    throw new Error("Group name must not be empty");
+  }
+  if (name.length > GROUP_NAME_MAX_LENGTH) {
+    throw new Error(`Group name must be at most ${GROUP_NAME_MAX_LENGTH} characters`);
+  }
+  return name;
+}
 var CONFIG_ONLY_PREFIXES = [META_DIR, NODES_DIR, SHARED_DIR];
 var LOCAL_IDB_BACKEND_ID = "local-idb";
 function tombstoneFileName(filePath) {
@@ -2243,9 +2258,11 @@ var ConfigRepo = class {
    */
   async updateAppDataGroupDescriptor(id, backends) {
     this.assertNotDisposed();
+    const existing = await this.readAppDataGroupDescriptor(id);
     const descriptor = {
       id,
       groupType: "data-sync",
+      ...existing?.name ? { name: existing.name } : {},
       backends
     };
     const descPath = this.appDataGroupFilePath(id);
@@ -2256,6 +2273,73 @@ var ConfigRepo = class {
     const version = await incrementVersion(this.fullFS, descPath, bytes, author);
     await this.writeVersionSidecar(descPath, version);
   }
+  /**
+   * Change a data-sync group's display name only. `id`, backends, local stores
+   * and remote data are untouched, so existing sync pairs keep working.
+   */
+  async updateAppDataGroupName(id, name) {
+    this.assertNotDisposed();
+    const normalized = normalizeGroupName(name);
+    const existing = await this.readAppDataGroupDescriptor(id);
+    if (!existing) {
+      throw new Error(`App data group "${id}" not found`);
+    }
+    const descriptor = {
+      ...existing,
+      id,
+      groupType: "data-sync",
+      name: normalized
+    };
+    const descPath = this.appDataGroupFilePath(id);
+    await this.ensureDir(descPath);
+    const bytes = new TextEncoder().encode(JSON.stringify(descriptor, null, 2));
+    await this.cachedFS.writeFile(descPath, bytes);
+    const author = `${this.appId}/${this.nodeId}`;
+    const version = await incrementVersion(this.fullFS, descPath, bytes, author);
+    await this.writeVersionSidecar(descPath, version);
+  }
+  async getConfigSyncGroupDescriptor() {
+    this.assertNotDisposed();
+    try {
+      const raw = await this.cachedFS.readFile(CONFIG_SYNC_GROUP_FILE);
+      const parsed = JSON.parse(new TextDecoder().decode(toUint8Array2(raw)));
+      if (parsed && parsed.groupType === "config-sync") {
+        return parsed;
+      }
+    } catch {
+    }
+    return null;
+  }
+  /**
+   * Change the config-sync group's display name only. Backends, the local
+   * store and remote data are untouched.
+   */
+  async updateConfigSyncGroupDescriptor(patch) {
+    this.assertNotDisposed();
+    const normalized = normalizeGroupName(patch?.name);
+    const descriptor = {
+      groupType: "config-sync",
+      name: normalized
+    };
+    await this.ensureDir(CONFIG_SYNC_GROUP_FILE);
+    const bytes = new TextEncoder().encode(JSON.stringify(descriptor, null, 2));
+    await this.cachedFS.writeFile(CONFIG_SYNC_GROUP_FILE, bytes);
+    const author = `${this.appId}/${this.nodeId}`;
+    const version = await incrementVersion(this.fullFS, CONFIG_SYNC_GROUP_FILE, bytes, author);
+    await this.writeVersionSidecar(CONFIG_SYNC_GROUP_FILE, version);
+    return descriptor;
+  }
+  async readAppDataGroupDescriptor(id) {
+    try {
+      const raw = await this.cachedFS.readFile(this.appDataGroupFilePath(id));
+      const parsed = JSON.parse(new TextDecoder().decode(toUint8Array2(raw)));
+      if (parsed && parsed.id === id && parsed.groupType === "data-sync") {
+        return parsed;
+      }
+    } catch {
+    }
+    return null;
+  }
   async getAppDataGroup(id) {
     this.assertNotDisposed();
     const cached = this.appDataGroups.get(id);
@@ -2345,6 +2429,7 @@ var AppDataGroupImpl = class {
   syncEngine;
   localFS;
   dataBackends = /* @__PURE__ */ new Map();
+  backendStates = /* @__PURE__ */ new Map();
   disposed = false;
   constructor(groupId, appId, backends, pollIntervalMs, parent) {
     this.groupId = groupId;
@@ -2417,8 +2502,14 @@ var AppDataGroupImpl = class {
           "/"
         );
         this.dataBackends.set(desc.id, { instance, syncable, pairId: pair.pairId, desc });
+        this.backendStates.set(desc.id, { backendId: desc.id, pairId: pair.pairId });
         log2.log(`[AppDataGroup:${this.groupId}] backend ${desc.id} (${desc.type}) connected, pair=${pair.pairId}`);
       } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        this.backendStates.set(desc.id, {
+          backendId: desc.id,
+          error: { message, timestamp: Date.now() }
+        });
         log2.error(`[AppDataGroup:${this.groupId}] Failed to create backend ${desc.id} (${desc.type}):`, err);
       }
     }
@@ -2443,6 +2534,9 @@ var AppDataGroupImpl = class {
     const results = await this.syncEngine.syncAll();
     return Array.from(results.values());
   }
+  getBackendSyncStates() {
+    return new Map(this.backendStates);
+  }
   async addBackend(id, type, options, description) {
     if (this.disposed) throw new Error("DataSyncGroup has been disposed");
     if (this.dataBackends.has(id)) {
@@ -2465,6 +2559,8 @@ var AppDataGroupImpl = class {
     );
     const desc = { id, type, options, description, createdAt: Date.now() };
     this.dataBackends.set(id, { instance, syncable, pairId: pair.pairId, desc });
+    this.backendStates.set(id, { backendId: id, pairId: pair.pairId });
+    this._backends = [...this._backends.filter((b) => b.id !== id), desc];
     log2.log(`[AppDataGroup:${this.groupId}] addBackend: ${id} (${type}) connected, pair=${pair.pairId}`);
     try {
       await this.syncEngine.sync(pair.pairId);
@@ -2472,18 +2568,23 @@ var AppDataGroupImpl = class {
       log2.warn(`[AppDataGroup:${this.groupId}] addBackend: initial sync failed for ${id}:`, err);
     }
     this.syncEngine.watch(pair.pairId);
-    await this.parent.updateAppDataGroupDescriptor(this.groupId, this.listBackends());
+    await this.parent.updateAppDataGroupDescriptor(this.groupId, this._backends);
   }
   async removeBackend(id) {
     if (this.disposed) throw new Error("DataSyncGroup has been disposed");
     const backend = this.dataBackends.get(id);
-    if (!backend) {
+    const desc = this._backends.find((b) => b.id === id);
+    if (!backend && !desc) {
       throw new Error(`Backend "${id}" not found in data group "${this.groupId}"`);
     }
-    this.syncEngine.removePair(backend.pairId);
-    this.dataBackends.delete(id);
-    await this.parent.updateAppDataGroupDescriptor(this.groupId, this.listBackends());
-    if (backend.instance?.dispose) {
+    if (backend) {
+      this.syncEngine.removePair(backend.pairId);
+      this.dataBackends.delete(id);
+    }
+    this.backendStates.delete(id);
+    this._backends = this._backends.filter((b) => b.id !== id);
+    await this.parent.updateAppDataGroupDescriptor(this.groupId, this._backends);
+    if (backend?.instance?.dispose) {
       await backend.instance.dispose();
     }
     log2.log(`[AppDataGroup:${this.groupId}] removeBackend: ${id} removed`);

package/dist/zen-fs-config.js

@@ -27449,10 +27449,25 @@ var ZenFSConfig = (() => {
   var BACKENDS_FILE = `${META_DIR}/backends.json`;
   var BACKENDS_DIR = `${META_DIR}/backends`;
   var APP_DATA_GROUPS_DIR = `${META_DIR}/app-data-groups`;
+  var CONFIG_SYNC_GROUP_FILE = `${META_DIR}/config-sync-group.json`;
+  var GROUP_NAME_MAX_LENGTH = 40;
   var CONFLICTS_DIR = `${META_DIR}/.conflicts`;
   var DELETIONS_DIR = `${META_DIR}/.deleted`;
   var NODES_DIR = "/nodes";
   var SHARED_DIR = "/shared";
+  function normalizeGroupName(value) {
+    if (typeof value !== "string") {
+      throw new Error("Group name must be a string");
+    }
+    const name = value.trim();
+    if (!name) {
+      throw new Error("Group name must not be empty");
+    }
+    if (name.length > GROUP_NAME_MAX_LENGTH) {
+      throw new Error(`Group name must be at most ${GROUP_NAME_MAX_LENGTH} characters`);
+    }
+    return name;
+  }
   var CONFIG_ONLY_PREFIXES = [META_DIR, NODES_DIR, SHARED_DIR];
   var LOCAL_IDB_BACKEND_ID = "local-idb";
   function tombstoneFileName(filePath) {
@@ -28808,9 +28823,11 @@ var ZenFSConfig = (() => {
      */
     async updateAppDataGroupDescriptor(id, backends) {
       this.assertNotDisposed();
+      const existing = await this.readAppDataGroupDescriptor(id);
       const descriptor = {
         id,
         groupType: "data-sync",
+        ...existing?.name ? { name: existing.name } : {},
         backends
       };
       const descPath = this.appDataGroupFilePath(id);
@@ -28821,6 +28838,73 @@ var ZenFSConfig = (() => {
       const version2 = await incrementVersion(this.fullFS, descPath, bytes, author);
       await this.writeVersionSidecar(descPath, version2);
     }
+    /**
+     * Change a data-sync group's display name only. `id`, backends, local stores
+     * and remote data are untouched, so existing sync pairs keep working.
+     */
+    async updateAppDataGroupName(id, name) {
+      this.assertNotDisposed();
+      const normalized = normalizeGroupName(name);
+      const existing = await this.readAppDataGroupDescriptor(id);
+      if (!existing) {
+        throw new Error(`App data group "${id}" not found`);
+      }
+      const descriptor = {
+        ...existing,
+        id,
+        groupType: "data-sync",
+        name: normalized
+      };
+      const descPath = this.appDataGroupFilePath(id);
+      await this.ensureDir(descPath);
+      const bytes = new TextEncoder().encode(JSON.stringify(descriptor, null, 2));
+      await this.cachedFS.writeFile(descPath, bytes);
+      const author = `${this.appId}/${this.nodeId}`;
+      const version2 = await incrementVersion(this.fullFS, descPath, bytes, author);
+      await this.writeVersionSidecar(descPath, version2);
+    }
+    async getConfigSyncGroupDescriptor() {
+      this.assertNotDisposed();
+      try {
+        const raw = await this.cachedFS.readFile(CONFIG_SYNC_GROUP_FILE);
+        const parsed = JSON.parse(new TextDecoder().decode(toUint8Array2(raw)));
+        if (parsed && parsed.groupType === "config-sync") {
+          return parsed;
+        }
+      } catch {
+      }
+      return null;
+    }
+    /**
+     * Change the config-sync group's display name only. Backends, the local
+     * store and remote data are untouched.
+     */
+    async updateConfigSyncGroupDescriptor(patch) {
+      this.assertNotDisposed();
+      const normalized = normalizeGroupName(patch?.name);
+      const descriptor = {
+        groupType: "config-sync",
+        name: normalized
+      };
+      await this.ensureDir(CONFIG_SYNC_GROUP_FILE);
+      const bytes = new TextEncoder().encode(JSON.stringify(descriptor, null, 2));
+      await this.cachedFS.writeFile(CONFIG_SYNC_GROUP_FILE, bytes);
+      const author = `${this.appId}/${this.nodeId}`;
+      const version2 = await incrementVersion(this.fullFS, CONFIG_SYNC_GROUP_FILE, bytes, author);
+      await this.writeVersionSidecar(CONFIG_SYNC_GROUP_FILE, version2);
+      return descriptor;
+    }
+    async readAppDataGroupDescriptor(id) {
+      try {
+        const raw = await this.cachedFS.readFile(this.appDataGroupFilePath(id));
+        const parsed = JSON.parse(new TextDecoder().decode(toUint8Array2(raw)));
+        if (parsed && parsed.id === id && parsed.groupType === "data-sync") {
+          return parsed;
+        }
+      } catch {
+      }
+      return null;
+    }
     async getAppDataGroup(id) {
       this.assertNotDisposed();
       const cached = this.appDataGroups.get(id);
@@ -28911,6 +28995,7 @@ var ZenFSConfig = (() => {
       __publicField(this, "syncEngine");
       __publicField(this, "localFS");
       __publicField(this, "dataBackends", /* @__PURE__ */ new Map());
+      __publicField(this, "backendStates", /* @__PURE__ */ new Map());
       __publicField(this, "disposed", false);
       __publicField(this, "parent");
       __publicField(this, "_backends");
@@ -28982,8 +29067,14 @@ var ZenFSConfig = (() => {
             "/"
           );
           this.dataBackends.set(desc.id, { instance, syncable, pairId: pair.pairId, desc });
+          this.backendStates.set(desc.id, { backendId: desc.id, pairId: pair.pairId });
           log6.log(`[AppDataGroup:${this.groupId}] backend ${desc.id} (${desc.type}) connected, pair=${pair.pairId}`);
         } catch (err2) {
+          const message = err2 instanceof Error ? err2.message : String(err2);
+          this.backendStates.set(desc.id, {
+            backendId: desc.id,
+            error: { message, timestamp: Date.now() }
+          });
           log6.error(`[AppDataGroup:${this.groupId}] Failed to create backend ${desc.id} (${desc.type}):`, err2);
         }
       }
@@ -29008,6 +29099,9 @@ var ZenFSConfig = (() => {
       const results = await this.syncEngine.syncAll();
       return Array.from(results.values());
     }
+    getBackendSyncStates() {
+      return new Map(this.backendStates);
+    }
     async addBackend(id, type, options, description) {
       if (this.disposed) throw new Error("DataSyncGroup has been disposed");
       if (this.dataBackends.has(id)) {
@@ -29030,6 +29124,8 @@ var ZenFSConfig = (() => {
       );
       const desc = { id, type, options, description, createdAt: Date.now() };
       this.dataBackends.set(id, { instance, syncable, pairId: pair.pairId, desc });
+      this.backendStates.set(id, { backendId: id, pairId: pair.pairId });
+      this._backends = [...this._backends.filter((b) => b.id !== id), desc];
       log6.log(`[AppDataGroup:${this.groupId}] addBackend: ${id} (${type}) connected, pair=${pair.pairId}`);
       try {
         await this.syncEngine.sync(pair.pairId);
@@ -29037,18 +29133,23 @@ var ZenFSConfig = (() => {
         log6.warn(`[AppDataGroup:${this.groupId}] addBackend: initial sync failed for ${id}:`, err2);
       }
       this.syncEngine.watch(pair.pairId);
-      await this.parent.updateAppDataGroupDescriptor(this.groupId, this.listBackends());
+      await this.parent.updateAppDataGroupDescriptor(this.groupId, this._backends);
     }
     async removeBackend(id) {
       if (this.disposed) throw new Error("DataSyncGroup has been disposed");
       const backend = this.dataBackends.get(id);
-      if (!backend) {
+      const desc = this._backends.find((b) => b.id === id);
+      if (!backend && !desc) {
         throw new Error(`Backend "${id}" not found in data group "${this.groupId}"`);
       }
-      this.syncEngine.removePair(backend.pairId);
-      this.dataBackends.delete(id);
-      await this.parent.updateAppDataGroupDescriptor(this.groupId, this.listBackends());
-      if (backend.instance?.dispose) {
+      if (backend) {
+        this.syncEngine.removePair(backend.pairId);
+        this.dataBackends.delete(id);
+      }
+      this.backendStates.delete(id);
+      this._backends = this._backends.filter((b) => b.id !== id);
+      await this.parent.updateAppDataGroupDescriptor(this.groupId, this._backends);
+      if (backend?.instance?.dispose) {
         await backend.instance.dispose();
       }
       log6.log(`[AppDataGroup:${this.groupId}] removeBackend: ${id} removed`);

package/package.json

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