Fixed: Replication progress is now correctly saved and restored in the CLI.

src/apps/cli/Dockerfile

@@ -108,4 +108,4 @@ RUN chmod +x /usr/local/bin/livesync-cli
 # Mount your vault / local database directory here
 VOLUME ["/data"]
 
-ENTRYPOINT ["livesync-cli"]
+ENTRYPOINT ["/usr/local/bin/livesync-cli"]

src/apps/cli/README.md

@@ -45,6 +45,10 @@ CLI Main
     - Settings management (JSON file)
     - Graceful shutdown handling
 
+## Something I realised later that could lead to misunderstandings
+
+The term `vault` in this README refers to the directory containing your local database and settings file. Not the actual files you want to sync. I will fix this later, but please be mind this for now.
+
 ## Docker
 
 A Docker image is provided for headless / server deployments. Build from the repository root:

src/apps/cli/main.ts

@@ -3,25 +3,10 @@
  * Command-line version of Self-hosted LiveSync plugin for syncing vaults without Obsidian
  */
 
-if (!("localStorage" in globalThis) || typeof (globalThis as any).localStorage?.getItem !== "function") {
-    const store = new Map<string, string>();
-    (globalThis as any).localStorage = {
-        getItem: (key: string) => (store.has(key) ? store.get(key)! : null),
-        setItem: (key: string, value: string) => {
-            store.set(key, value);
-        },
-        removeItem: (key: string) => {
-            store.delete(key);
-        },
-        clear: () => {
-            store.clear();
-        },
-    };
-}
-
 import * as fs from "fs/promises";
 import * as path from "path";
 import { NodeServiceContext, NodeServiceHub } from "./services/NodeServiceHub";
+import { configureNodeLocalStorage, ensureGlobalNodeLocalStorage } from "./services/NodeLocalStorage";
 import { LiveSyncBaseCore } from "../../LiveSyncBaseCore";
 import { ModuleReplicatorP2P } from "../../modules/core/ModuleReplicatorP2P";
 import { initialiseServiceModulesCLI } from "./serviceModules/CLIServiceModules";
@@ -43,6 +28,7 @@ import { getPathFromUXFileInfo } from "@lib/common/typeUtils";
 import { stripAllPrefixes } from "@lib/string_and_binary/path";
 
 const SETTINGS_FILE = ".livesync/settings.json";
+ensureGlobalNodeLocalStorage();
 defaultLoggerEnv.minLogLevel = LOG_LEVEL_DEBUG;
 
 function printHelp(): void {
@@ -252,6 +238,7 @@ export async function main() {
     const settingsPath = options.settingsPath
         ? path.resolve(options.settingsPath)
         : path.join(vaultPath, SETTINGS_FILE);
+    configureNodeLocalStorage(path.join(vaultPath, ".livesync", "runtime", "local-storage.json"));
 
     infoLog(`Self-hosted LiveSync CLI`);
     infoLog(`Vault: ${vaultPath}`);

src/apps/cli/services/NodeLocalStorage.ts

@@ -0,0 +1,111 @@
+import * as nodeFs from "node:fs";
+import * as nodePath from "node:path";
+
+type LocalStorageShape = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+};
+
+class PersistentNodeLocalStorage {
+    private storagePath: string | undefined;
+    private localStore: Record<string, string> = {};
+
+    configure(storagePath: string) {
+        if (this.storagePath === storagePath) {
+            return;
+        }
+        this.storagePath = storagePath;
+        this.loadFromFile();
+    }
+
+    private loadFromFile() {
+        if (!this.storagePath) {
+            this.localStore = {};
+            return;
+        }
+        try {
+            const loaded = JSON.parse(nodeFs.readFileSync(this.storagePath, "utf-8")) as Record<string, string>;
+            this.localStore = { ...loaded };
+        } catch {
+            this.localStore = {};
+        }
+    }
+
+    private flushToFile() {
+        if (!this.storagePath) {
+            return;
+        }
+        nodeFs.mkdirSync(nodePath.dirname(this.storagePath), { recursive: true });
+        nodeFs.writeFileSync(this.storagePath, JSON.stringify(this.localStore, null, 2), "utf-8");
+    }
+
+    getItem(key: string): string | null {
+        return this.localStore[key] ?? null;
+    }
+
+    setItem(key: string, value: string) {
+        this.localStore[key] = value;
+        this.flushToFile();
+    }
+
+    removeItem(key: string) {
+        if (!(key in this.localStore)) {
+            return;
+        }
+        delete this.localStore[key];
+        this.flushToFile();
+    }
+
+    clear() {
+        this.localStore = {};
+        this.flushToFile();
+    }
+}
+
+const persistentNodeLocalStorage = new PersistentNodeLocalStorage();
+
+function createNodeLocalStorageShim(): LocalStorageShape {
+    return {
+        getItem(key: string) {
+            return persistentNodeLocalStorage.getItem(key);
+        },
+        setItem(key: string, value: string) {
+            persistentNodeLocalStorage.setItem(key, value);
+        },
+        removeItem(key: string) {
+            persistentNodeLocalStorage.removeItem(key);
+        },
+        clear() {
+            persistentNodeLocalStorage.clear();
+        },
+    };
+}
+
+export function ensureGlobalNodeLocalStorage() {
+    if (!("localStorage" in globalThis) || typeof (globalThis as any).localStorage?.getItem !== "function") {
+        (globalThis as any).localStorage = createNodeLocalStorageShim();
+    }
+}
+
+export function configureNodeLocalStorage(storagePath: string) {
+    persistentNodeLocalStorage.configure(storagePath);
+    ensureGlobalNodeLocalStorage();
+}
+
+export function getNodeLocalStorageItem(key: string): string {
+    return persistentNodeLocalStorage.getItem(key) ?? "";
+}
+
+export function setNodeLocalStorageItem(key: string, value: string) {
+    persistentNodeLocalStorage.setItem(key, value);
+}
+
+export function deleteNodeLocalStorageItem(key: string) {
+    persistentNodeLocalStorage.removeItem(key);
+}
+
+export function clearNodeLocalStorage() {
+    persistentNodeLocalStorage.clear();
+}

src/apps/cli/services/NodeLocalStorage.unit.spec.ts

@@ -0,0 +1,60 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+    clearNodeLocalStorage,
+    configureNodeLocalStorage,
+    ensureGlobalNodeLocalStorage,
+    getNodeLocalStorageItem,
+    setNodeLocalStorageItem,
+} from "./NodeLocalStorage";
+
+describe("NodeLocalStorage", () => {
+    const tempDirs: string[] = [];
+
+    afterEach(() => {
+        clearNodeLocalStorage();
+        for (const tempDir of tempDirs.splice(0)) {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+    });
+
+    it("persists values to the configured file", () => {
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "livesync-node-local-storage-"));
+        tempDirs.push(tempDir);
+        const storagePath = path.join(tempDir, "runtime", "local-storage.json");
+
+        configureNodeLocalStorage(storagePath);
+        setNodeLocalStorageItem("checkpoint", "42");
+
+        const saved = JSON.parse(fs.readFileSync(storagePath, "utf-8")) as Record<string, string>;
+        expect(saved.checkpoint).toBe("42");
+    });
+
+    it("reloads persisted values when configured again", () => {
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "livesync-node-local-storage-"));
+        tempDirs.push(tempDir);
+        const storagePath = path.join(tempDir, "runtime", "local-storage.json");
+
+        fs.mkdirSync(path.dirname(storagePath), { recursive: true });
+        fs.writeFileSync(storagePath, JSON.stringify({ persisted: "value" }, null, 2), "utf-8");
+
+        configureNodeLocalStorage(storagePath);
+
+        expect(getNodeLocalStorageItem("persisted")).toBe("value");
+    });
+
+    it("installs a global localStorage shim backed by the same store", () => {
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "livesync-node-local-storage-"));
+        tempDirs.push(tempDir);
+        const storagePath = path.join(tempDir, "runtime", "local-storage.json");
+
+        configureNodeLocalStorage(storagePath);
+        ensureGlobalNodeLocalStorage();
+
+        globalThis.localStorage.setItem("shared", "state");
+
+        expect(getNodeLocalStorageItem("shared")).toBe("state");
+    });
+});

src/apps/cli/services/NodeSettingService.ts

@@ -5,17 +5,17 @@ import { handlers } from "@lib/services/lib/HandlerUtils";
 import type { ObsidianLiveSyncSettings } from "@lib/common/types";
 import type { ServiceContext } from "@lib/services/base/ServiceBase";
 import { SettingService, type SettingServiceDependencies } from "@lib/services/base/SettingService";
-import * as nodeFs from "node:fs";
-import * as nodePath from "node:path";
+import {
+    configureNodeLocalStorage,
+    deleteNodeLocalStorageItem,
+    getNodeLocalStorageItem,
+    setNodeLocalStorageItem,
+} from "./NodeLocalStorage";
 
 export class NodeSettingService<T extends ServiceContext> extends SettingService<T> {
-    private storagePath: string;
-    private localStore: Record<string, string> = {};
-
     constructor(context: T, dependencies: SettingServiceDependencies, storagePath: string) {
         super(context, dependencies);
-        this.storagePath = storagePath;
-        this.loadLocalStoreFromFile();
+        configureNodeLocalStorage(storagePath);
         this.onSettingSaved.addHandler((settings) => {
             eventHub.emitEvent(EVENT_SETTING_SAVED, settings);
             return Promise.resolve(true);
@@ -26,34 +26,16 @@ export class NodeSettingService<T extends ServiceContext> extends SettingService
         });
     }
 
-    private loadLocalStoreFromFile() {
-        try {
-            const loaded = JSON.parse(nodeFs.readFileSync(this.storagePath, "utf-8")) as Record<string, string>;
-            this.localStore = { ...loaded };
-        } catch {
-            this.localStore = {};
-        }
-    }
-
-    private flushLocalStoreToFile() {
-        nodeFs.mkdirSync(nodePath.dirname(this.storagePath), { recursive: true });
-        nodeFs.writeFileSync(this.storagePath, JSON.stringify(this.localStore, null, 2), "utf-8");
-    }
-
     protected setItem(key: string, value: string) {
-        this.localStore[key] = value;
-        this.flushLocalStoreToFile();
+        setNodeLocalStorageItem(key, value);
     }
 
     protected getItem(key: string): string {
-        return this.localStore[key] ?? "";
+        return getNodeLocalStorageItem(key);
     }
 
     protected deleteItem(key: string): void {
-        if (key in this.localStore) {
-            delete this.localStore[key];
-            this.flushLocalStoreToFile();
-        }
+        deleteNodeLocalStorageItem(key);
     }
 
     public saveData = handlers<{ saveData: (data: ObsidianLiveSyncSettings) => Promise<void> }>().binder("saveData");