@vrtmrz/livesync-commonlib 0.1.0-rc.5 → 0.1.0-rc.6

package/README.md

@@ -1,6 +1,6 @@
 # Self-hosted LiveSync Commonlib
 
-Commonlib is the ESM package which provides shared data, storage, replication, host-context, and RPC primitives for Self-hosted LiveSync, its CLI, Webapp, and WebPeer.
+Commonlib is the ESM package which provides shared data, storage, replication, and host-context primitives for Self-hosted LiveSync, its CLI, Webapp, and WebPeer.
 
 This package is primarily for maintainers of those clients and for integrations which deliberately reuse a reviewed Commonlib contract. It is not yet a general-purpose LiveSync SDK: the package does not provide a stable end-to-end client factory or own host UI, permissions, credentials, process lifecycle, or application persistence.
 
@@ -24,8 +24,8 @@ The package is ESM-only and declares Node 20 or later. Browser entry points are
 | `@vrtmrz/livesync-commonlib`                       | `DirectFileManipulator` for integrations which access CouchDB directly            | Deliberately small, but its high-level lifecycle and file-operation semantics are not final |
 | `@vrtmrz/livesync-commonlib/context`               | Instance-owned events, translation injection, and host-neutral standard-I/O types | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/browser`               | Rooted File System Access API storage                                             | Focused, package-tested pre-1.0 contract                                                    |
-| `@vrtmrz/livesync-commonlib/node`                  | Rooted Node storage, Node standard I/O, and selected Node capabilities            | Focused platform entry; some convenience exports still require 1.0 classification           |
-| `@vrtmrz/livesync-commonlib/rpc`                   | Transport-neutral RPC rooms, sessions, errors, and the PouchDB RPC bridge         | Deliberate export, but its 1.0 stability status is not yet accepted                         |
+| `@vrtmrz/livesync-commonlib/node`                  | Rooted Node storage, Node standard I/O, and selected Node capabilities            | Supported platform façade; keeps Node-only dependencies behind an explicit boundary         |
+| `@vrtmrz/livesync-commonlib/rpc`                   | Existing LiveSync RPC and PouchDB bridge migration                                | Transitional only; not part of the stable Commonlib 1.0 contract                            |
 | `@vrtmrz/livesync-commonlib/remote-configurations` | Multiple-remote profile creation, naming, and selection                           | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/settings`              | New-Vault defaults, stored-setting fallbacks, and settings migration results      | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/compat/*`              | Exact legacy imports still required by existing clients                           | Migration-only; paths may be removed as consumers migrate                                   |
@@ -33,13 +33,13 @@ The package is ESM-only and declares Node 20 or later. Browser entry points are
 
 Import only the entry point required by the current runtime. Browser code must not import the Node entry.
 
-TODO: decide whether the Node entry's `fs`, `fsPromises`, `path`, `os`, `readline`, URL, and built-in-module convenience exports belong in the 1.0 public contract or should move behind compatibility paths.
+The Node and browser entries are platform façades. They keep platform-specific adapters and capabilities behind package-owned boundaries, so a consumer does not have to reproduce those imports or their build and review exceptions. The Node entry's selected built-in-module exports are deliberate parts of that façade. Package checks ensure that the root, context, and browser entries do not load the Node implementation.
 
-TODO: decide whether the draft RPC protocol and PouchDB bridge are stable 1.0 contracts, remain explicitly experimental, or move to a separately versioned package. Until that decision, pin the exact package version when consuming the RPC entry.
+The RPC entry exists only while the maintained LiveSync P2P composition depends on the current implementation. Its draft wire protocol and PouchDB bridge are not stable Commonlib 1.0 contracts. RPC is planned to move to Fancy Kit as an independently owned rewrite; new Commonlib consumers should not adopt the transitional entry.
 
 ## Host context and initialisation
 
-One service context belongs to one independently composed Commonlib client. It owns that client's event hub and translator. Creating a context without options creates a fresh event hub and uses a translator which returns message keys unchanged:
+One service context belongs to one independently composed Commonlib client. It owns that client's event hub and translator. Creating a context without options creates a fresh event hub and renders Commonlib's typed canonical English messages. A host may inject a translator to provide another language:
 
 ```ts
 import {
@@ -61,7 +61,9 @@ The host may instead extend `ServiceContext` with platform-specific capabilities
 
 Context construction does not select storage, connect to a database, start replication, acquire browser permission, or install process-wide state. The host separately owns platform-resource acquisition, adapter construction, and the lifecycle order of its particular service composition.
 
-TODO: define a reviewed high-level composition factory and its initialisation, readiness, error, and disposal contract. Until that exists, service implementations exposed under `compat/*` retain their owning client's lifecycle rather than becoming a general public composition API.
+After the Self-hosted LiveSync 1.0 work, the planned high-level composition is a narrow `createLiveSyncFileClient` factory for direct database integrations, not a general factory which exposes Commonlib's internal Service Hub. It will resolve only after its private context, services, database, and protocol settings are ready, and its returned file client will own its watches, reconnect work, and orderly disposal. Obsidian, CLI, Webapp, and other full hosts retain their host-specific compositions.
+
+The factory is not implemented yet. Until it is available, service implementations exposed under `compat/*` retain their owning client's lifecycle rather than becoming a general public composition API.
 
 ## Rooted storage
 
@@ -114,9 +116,9 @@ See [the remote configuration profile guide](docs/remote-configurations.md) for
 
 The package is currently an infrastructure and compatibility boundary. The context, rooted-storage, and standard-I/O result contracts have focused cross-platform or instance-isolation tests. Platform details which cannot be shared, such as file timestamp fidelity and browser permission handling, remain host concerns and are documented separately.
 
-`DirectFileManipulator` is useful for existing integrations, but its enumeration, watch ownership, failure, conflict, concurrency, readiness, and disposal semantics are not yet a stable high-level SDK contract.
+`DirectFileManipulator` is useful for existing integrations, but its enumeration, watch ownership, failure, conflict, concurrency, readiness, and disposal semantics are not a stable high-level SDK contract. It is the migration source for the planned file client, not the shape to preserve as the new API.
 
-TODO: define and document the first high-level client façade before declaring list, get, put, delete, watch, and close behaviour stable.
+The accepted replacement direction is an asynchronously created file client with stable `list`, `get`, `put`, `delete`, `watch`, and `close` operations. The operation result, conflict, concurrency, watch checkpoint, retry, and error contracts still require focused decisions and tests before that client can be published.
 
 Package developers should read [the developer guide](docs/development.md). The focused contracts are described in [the storage guide](docs/platform-storage.md), [the standard-I/O guide](docs/platform-standard-io.md), [the settings lifecycle guide](docs/settings-lifecycle.md), and [the remote configuration profile guide](docs/remote-configurations.md).
 

package/dist/common/configForDoc.js

@@ -1,7 +1,12 @@
 import { isCloudantURI } from "../pouchdb/utils_couchdb.js";
 import { LOG_LEVEL_INFO, LOG_LEVEL_NOTICE, LOG_LEVEL_VERBOSE, Logger } from "./logger.js";
 import { getConfName } from "./settingConstants.js";
-import { ChunkAlgorithmNames, E2EEAlgorithmNames, E2EEAlgorithms } from "./types.js";
+import {
+  ChunkAlgorithmNames,
+  E2EEAlgorithmNames,
+  E2EEAlgorithms,
+  REMOTE_COUCHDB
+} from "./types.js";
 var ConditionType = /* @__PURE__ */ ((ConditionType2) => {
   ConditionType2["PLATFORM_CASE_INSENSITIVE"] = "platform-case-insensitive";
   ConditionType2["PLATFORM_CASE_SENSITIVE"] = "platform-case-sensitive";
@@ -90,7 +95,7 @@ const DoctorRegulationV0_24_30 = {
       value: 60,
       valueDisplay: "60 (detected on if less than 55)",
       level: 2 /* Recommended */,
-      detectionFunc: (settings) => settings?.chunkSplitterVersion === "v3-rabin-karp" && !isCloudantURI(settings?.couchDB_URI || ""),
+      detectionFunc: (settings) => settings?.remoteType === REMOTE_COUCHDB && settings?.chunkSplitterVersion === "v3-rabin-karp" && !isCloudantURI(settings?.couchDB_URI || ""),
       reason: "With the V3 Rabin-Karp chunk splitter and Self-hosted CouchDB, the chunk size is set to 60 (means around 6MB) by default. This is in effect the maximum chunk size, which in practice is divided more finely."
     }
   }

package/dist/common/models/setting.type.d.ts

@@ -1,7 +1,8 @@
 import type { ChunkAlgorithms, E2EEAlgorithms, HashAlgorithms, MODE_AUTOMATIC, MODE_PAUSED, MODE_SELECTIVE, MODE_SHINY, RemoteTypes } from "./setting.const.js";
-import type { I18N_LANGS } from "../rosetta.js";
 import type { CustomRegExpSourceList } from "./shared.type.util.js";
 import type { JWTAlgorithm } from "./auth.type.js";
+/** Display languages recognised by the current LiveSync settings schema. */
+export type I18N_LANGS = "" | "def" | "de" | "es" | "fr" | "he" | "ja" | "ko" | "ru" | "zh" | "zh-tw";
 /**
  * Represents the connection details required to connect to a CouchDB instance.
  */

package/dist/common/models/tweak.definition.d.ts

@@ -34,7 +34,7 @@ export declare const TweakValuesTemplate: {
     showOnlyIconsOnEditor?: boolean;
     hideFileWarningNotice?: boolean;
     networkWarningStyle?: "" | "icon" | "hidden";
-    displayLanguage?: import("../rosetta.js").I18N_LANGS;
+    displayLanguage?: import("./setting.type.js").I18N_LANGS;
     trashInsteadDelete?: boolean;
     doNotDeleteFolder?: boolean;
     batchSave?: boolean;

package/dist/common/settingConstants.d.ts

@@ -1,3 +1,4 @@
+import { type MessageTranslator } from "../services/base/MessageTranslator.js";
 import { type ConfigurationItem, type ObsidianLiveSyncSettings } from "./types.js";
 type ExtractPropertiesByType<T, U> = {
     [K in keyof T as T[K] extends U ? K : never]: T[K] extends U ? K : never;
@@ -43,7 +44,7 @@ export declare const AllSettingDefault: {
     showOnlyIconsOnEditor: boolean;
     hideFileWarningNotice: boolean;
     networkWarningStyle: "" | "icon" | "hidden";
-    displayLanguage: import("./rosetta.js").I18N_LANGS;
+    displayLanguage: import("./models/setting.type.js").I18N_LANGS;
     trashInsteadDelete: boolean;
     doNotDeleteFolder: boolean;
     batchSave: boolean;
@@ -202,7 +203,7 @@ export type AllBooleanItemKey = FilterBooleanKeys<AllSettings>;
 export type AllSettingItemKey = AllStringItemKey | AllNumericItemKey | AllBooleanItemKey;
 export type ValueOf<T extends AllSettingItemKey> = T extends AllStringItemKey ? string : T extends AllNumericItemKey ? number : T extends AllBooleanItemKey ? boolean : AllSettings[T];
 export declare const SettingInformation: Partial<Record<keyof AllSettings, ConfigurationItem>>;
-type SettingLabelTranslator = (message: string) => string;
+type SettingLabelTranslator = MessageTranslator;
 export declare function getConfig(key: AllSettingItemKey, translate?: SettingLabelTranslator): false | {
     name: string;
     desc?: string;

package/dist/common/settingConstants.js

@@ -1,4 +1,4 @@
-import { $t } from "./i18n.js";
+import { englishMessageTranslator } from "../services/base/MessageTranslator.js";
 import {
   DEFAULT_SETTINGS,
   configurationNames
@@ -399,7 +399,7 @@ const SettingInformation = {
     desc: "Files with modification times greater than this value (in seconds since the Unix epoch) will not have their events reflected. Set to 0 to disable this limit."
   }
 };
-function translateInfo(infoSrc, translate = (message) => $t(message)) {
+function translateInfo(infoSrc, translate = englishMessageTranslator) {
   if (!infoSrc) return false;
   const info = { ...infoSrc };
   info.name = translate(info.name);

package/dist/context.d.ts

@@ -5,5 +5,6 @@
  */
 export { ServiceContext, createServiceContext, type ServiceContextContract, type ServiceContextOptions, } from "./services/base/ServiceBase.js";
 export { createLiveSyncEventHub, type LiveSyncEventHub } from "./hub/hub.js";
-export { passthroughMessageTranslator, type MessageTranslator, type TranslationParameters, } from "./services/base/MessageTranslator.js";
+export { englishMessageTranslator, passthroughMessageTranslator, type MessageTranslator, type TranslationParameters, } from "./services/base/MessageTranslator.js";
+export { commonlibEnglishMessages, type CommonlibMessageKey } from "./services/base/CommonlibMessages.js";
 export type { StandardIo, StandardIoChunk } from "./platform/standardIo.js";

package/dist/context.js

@@ -4,11 +4,15 @@ import {
 } from "./services/base/ServiceBase.js";
 import { createLiveSyncEventHub } from "./hub/hub.js";
 import {
+  englishMessageTranslator,
   passthroughMessageTranslator
 } from "./services/base/MessageTranslator.js";
+import { commonlibEnglishMessages } from "./services/base/CommonlibMessages.js";
 export {
   ServiceContext,
+  commonlibEnglishMessages,
   createLiveSyncEventHub,
   createServiceContext,
+  englishMessageTranslator,
   passthroughMessageTranslator
 };

package/dist/replication/LiveSyncAbstractReplicator.d.ts

@@ -1,6 +1,7 @@
 import { type EntryDoc, type DatabaseConnectingStatus, type RemoteDBSettings, type EntryLeaf, type TweakValues, type NodeData } from "../common/types.js";
 import type { RequiredServices } from "../interfaces/ServiceModule.js";
 import type { TranslationParameters } from "../services/base/MessageTranslator.js";
+import type { CommonlibMessageKey } from "../services/base/CommonlibMessages.js";
 export type ReplicationCallback = (e: PouchDB.Core.ExistingDocument<EntryDoc>[]) => Promise<boolean> | boolean;
 export type ReplicationStat = {
     sent: number;
@@ -37,7 +38,7 @@ export declare abstract class LiveSyncAbstractReplicator {
     get database(): import("../pouchdb/LiveSyncLocalDB.js").LiveSyncLocalDB;
     get rawDatabase(): PouchDB.Database<EntryDoc>;
     get currentSettings(): import("../common/types.js").ObsidianLiveSyncSettings;
-    protected translate<TKey extends string>(key: TKey, params?: TranslationParameters): string;
+    protected translate(key: CommonlibMessageKey, params?: TranslationParameters): string;
     sendChunks(setting: RemoteDBSettings, remoteDB: PouchDB.Database<EntryDoc> | undefined, showResult: boolean, fromSeq?: number | string): Promise<boolean>;
     abstract getReplicationPBKDF2Salt(setting: RemoteDBSettings, refresh?: boolean): Promise<Uint8Array<ArrayBuffer>>;
     ensurePBKDF2Salt(setting: RemoteDBSettings, showMessage?: boolean, useCache?: boolean): Promise<boolean>;

package/dist/serviceModules/Rebuilder.js

@@ -1,5 +1,5 @@
 import { FlagFilesHumanReadable } from "../common/models/redflag.const.js";
-import { REMOTE_COUCHDB, REMOTE_MINIO } from "../common/models/setting.const.js";
+import { REMOTE_COUCHDB, REMOTE_MINIO, REMOTE_P2P } from "../common/models/setting.const.js";
 import { DEFAULT_SETTINGS } from "../common/models/setting.const.defaults.js";
 import { LOG_LEVEL_NOTICE, LOG_LEVEL_VERBOSE } from "octagonal-wheels/common/logger";
 import { delay } from "octagonal-wheels/promises";
@@ -108,6 +108,9 @@ Please enable them from the settings screen after setup is complete.`,
     await this.resetLocalDatabase();
     await delay(1e3);
     await this.databaseEvents.initialiseDatabase(true, true, true);
+    if (this.setting.currentSettings().remoteType === REMOTE_P2P) {
+      return;
+    }
     await this.replication.markLocked();
     await this._tryResetRemoteDatabase();
     await this.replication.markLocked();
@@ -273,8 +276,10 @@ Are you sure you wish to proceed?`;
     await this.replication.markResolved();
     await delay(500);
     await this.replication.replicateAllFromRemote(true);
-    await delay(1e3);
-    await this.replication.replicateAllFromRemote(true);
+    if (this.setting.currentSettings().remoteType !== REMOTE_P2P) {
+      await delay(1e3);
+      await this.replication.replicateAllFromRemote(true);
+    }
     if (autoResume) {
       await this.finishRebuild();
     }

package/dist/services/BrowserServices.d.ts

@@ -8,6 +8,7 @@ import type { ReplicatorService } from "./base/ReplicatorService.js";
 import type { UIService } from "./implements/base/UIService.js";
 import type { InjectableAPIService } from "./implements/injectable/InjectableAPIService.js";
 import type { KeyValueDatabaseFactory } from "../interfaces/KeyValueDatabase.js";
+import type { ObsidianLiveSyncSettings } from "../common/types.js";
 export type BrowserServiceHostDependencies<T extends ServiceContext> = {
     API: InjectableAPIService<T>;
     appLifecycle: AppLifecycleService<T>;
@@ -29,6 +30,7 @@ export type BrowserServiceHubOptions<T extends ServiceContext> = {
     context?: T;
     host: BrowserServiceHost<T>;
     openKeyValueDatabase?: KeyValueDatabaseFactory;
+    onDisplayLanguageChanged?: (language: ObsidianLiveSyncSettings["displayLanguage"]) => void;
 };
 export declare class BrowserServiceHub<T extends ServiceContext> extends InjectableServiceHub<T> {
     get vault(): InjectableVaultServiceCompat<T>;

package/dist/services/BrowserServices.js

@@ -32,7 +32,10 @@ class BrowserServiceHub extends InjectableServiceHub {
     const API = options.host.createAPI(context);
     const conflict = new InjectableConflictService(context);
     const fileProcessing = new InjectableFileProcessingService(context);
-    const setting = new InjectableSettingService(context, { APIService: API });
+    const setting = new InjectableSettingService(context, {
+      APIService: API,
+      onDisplayLanguageChanged: options.onDisplayLanguageChanged
+    });
     const appLifecycle = new BrowserAppLifecycleService(context, { settingService: setting });
     const remote = new InjectableRemoteService(context, {
       pouchDB: PouchDB,

package/dist/services/HeadlessServices.d.ts

@@ -4,11 +4,13 @@ import type { DatabaseService } from "./base/DatabaseService.js";
 import type { Constructor } from "../common/utils.type.js";
 import type { KeyValueDatabaseFactory } from "../interfaces/KeyValueDatabase.js";
 import type { PouchDBConstructor } from "../pouchdb/PouchDBConstructor.js";
+import type { ObsidianLiveSyncSettings } from "../common/types.js";
 export declare class HeadlessServiceHub<T extends ServiceContext> extends InjectableServiceHub<T> {
     constructor(_context: T | undefined, overrideServiceConstructor: {
         /** PouchDB with the adapters required by this headless runtime. */
         pouchDB: PouchDBConstructor;
         database?: Constructor<DatabaseService<T>>;
         openKeyValueDatabase?: KeyValueDatabaseFactory;
+        onDisplayLanguageChanged?: (language: ObsidianLiveSyncSettings["displayLanguage"]) => void;
     });
 }

package/dist/services/HeadlessServices.js

@@ -54,7 +54,8 @@ class HeadlessServiceHub extends InjectableServiceHub {
     const conflict = new InjectableConflictService(context);
     const fileProcessing = new InjectableFileProcessingService(context);
     const setting = new InjectableSettingService(context, {
-      APIService: API
+      APIService: API,
+      onDisplayLanguageChanged: overrideServiceConstructor.onDisplayLanguageChanged
     });
     const appLifecycle = new HeadlessAppLifecycleService(context, {
       settingService: setting