cli: implement local→CouchDB file watching via chokidar

- Add chokidar ^4.0.0 as dependency (root package.json, runtime-package.json)
- Mark chokidar as external in vite.config.ts (not bundled, loaded at runtime)
- Implement CLIWatchAdapter.beginWatch() with chokidar:
  - ignoreInitial: true (startup files handled by mirror scan)
  - awaitWriteFinish to prevent partial-write events
  - Excludes dotfiles and .livesync/ directory at watcher level
  - Maps add/change/unlink/addDir/unlinkDir to IStorageEventWatchHandlers
  - Fatal error handler: logs clearly and releases watcher resources
- Add close() to CLIWatchAdapter, StorageEventManagerCLI for clean shutdown
- Register onUnload hook in CLIServiceModules to close watcher on shutdown

src/apps/cli/adapters/NodeFileSystemAdapter.ts

@@ -39,12 +39,6 @@ export class NodeFileSystemAdapter implements IFileSystemAdapter<NodeFile, NodeF
 
     async getAbstractFileByPath(p: FilePath | string): Promise<NodeFile | null> {
         const pathStr = this.normalisePath(p);
-
-        const cached = this.fileCache.get(pathStr);
-        if (cached) {
-            return cached;
-        }
-
         return await this.refreshFile(pathStr);
     }
 

src/apps/cli/managers/CLIStorageEventManagerAdapter.ts

@@ -11,8 +11,10 @@ import type {
 } from "@lib/managers/adapters";
 import type { FileEventItemSentinel } from "@lib/managers/StorageEventManager";
 import type { NodeFile, NodeFolder } from "../adapters/NodeTypes";
+import type { Stats } from "fs";
 import * as fs from "fs/promises";
 import * as path from "path";
+import { watch as chokidarWatch, type FSWatcher } from "chokidar";
 
 /**
  * CLI-specific type guard adapter
@@ -56,22 +58,11 @@ class CLIPersistenceAdapter implements IStorageEventPersistenceAdapter {
 }
 
 /**
- * CLI-specific status adapter (console logging)
+ * CLI-specific status adapter (no-op — daemon uses journald for status)
  */
 class CLIStatusAdapter implements IStorageEventStatusAdapter {
-    private lastUpdate = 0;
-    private updateInterval = 5000; // Update every 5 seconds
-
-    updateStatus(status: { batched: number; processing: number; totalQueued: number }): void {
-        const now = Date.now();
-        if (now - this.lastUpdate > this.updateInterval) {
-            if (status.totalQueued > 0 || status.processing > 0) {
-                // console.log(
-                //     `[StorageEventManager] Batched: ${status.batched}, Processing: ${status.processing}, Total Queued: ${status.totalQueued}`
-                // );
-            }
-            this.lastUpdate = now;
-        }
+    updateStatus(_status: { batched: number; processing: number; totalQueued: number }): void {
+        // intentional no-op
     }
 }
 
@@ -100,15 +91,100 @@ class CLIConverterAdapter implements IStorageEventConverterAdapter<NodeFile> {
 }
 
 /**
- * CLI-specific watch adapter (optional file watching with chokidar)
+ * CLI-specific watch adapter using chokidar for real-time filesystem monitoring.
  */
 class CLIWatchAdapter implements IStorageEventWatchAdapter {
-    constructor(private basePath: string) {}
+    private _watcher: FSWatcher | undefined;
+
+    constructor(private basePath: string, private watchEnabled: boolean = false) {}
+
+    private _toNodeFile(filePath: string, stats: Stats | undefined): NodeFile {
+        return {
+            path: path.relative(this.basePath, filePath) as FilePath,
+            stat: {
+                ctime: stats?.ctimeMs ?? Date.now(),
+                mtime: stats?.mtimeMs ?? Date.now(),
+                size: stats?.size ?? 0,
+                type: "file",
+            },
+        };
+    }
+
+    private _toNodeFileStub(filePath: string): NodeFile {
+        return {
+            path: path.relative(this.basePath, filePath) as FilePath,
+            stat: {
+                ctime: Date.now(),
+                mtime: Date.now(),
+                size: 0,
+                type: "file",
+            },
+        };
+    }
+
+    private _toNodeFolder(dirPath: string): NodeFolder {
+        return {
+            path: path.relative(this.basePath, dirPath) as FilePath,
+            isFolder: true,
+        };
+    }
 
     async beginWatch(handlers: IStorageEventWatchHandlers): Promise<void> {
-        // File watching is not activated in the CLI.
-        // Because the CLI is designed for push/pull operations, not real-time sync.
-        // console.error("[CLIWatchAdapter] File watching is not enabled in CLI version");
+        if (!this.watchEnabled) return;
+        const watcher = chokidarWatch(this.basePath, {
+            ignored: [
+                /(^|[/\\])\./,
+            ],
+            ignoreInitial: true,
+            persistent: true,
+            awaitWriteFinish: {
+                stabilityThreshold: 500,
+                pollInterval: 100,
+            },
+        });
+
+        watcher.on("add", (filePath, stats) => {
+            const nodeFile = this._toNodeFile(filePath, stats);
+            handlers.onCreate(nodeFile);
+        });
+
+        watcher.on("change", (filePath, stats) => {
+            const nodeFile = this._toNodeFile(filePath, stats);
+            handlers.onChange(nodeFile);
+        });
+
+        watcher.on("unlink", (filePath) => {
+            const nodeFile = this._toNodeFileStub(filePath);
+            handlers.onDelete(nodeFile);
+        });
+
+        watcher.on("addDir", (dirPath) => {
+            const nodeFolder = this._toNodeFolder(dirPath);
+            handlers.onCreate(nodeFolder);
+        });
+
+        watcher.on("unlinkDir", (dirPath) => {
+            const nodeFolder = this._toNodeFolder(dirPath);
+            handlers.onDelete(nodeFolder);
+        });
+
+        watcher.on("error", (err) => {
+            console.error("[CLIWatchAdapter] Fatal watcher error — file watching stopped:", err);
+            console.error("[CLIWatchAdapter] Exiting for systemd restart.");
+            void watcher.close();
+            this._watcher = undefined;
+            // Use exit(1) rather than SIGTERM so systemd Restart=on-failure engages.
+            process.exit(1);
+        });
+
+        await new Promise<void>((resolve) => watcher.once("ready", resolve));
+        this._watcher = watcher;
+    }
+
+    close(): Promise<void> {
+        if (this._watcher) {
+            return this._watcher.close();
+        }
         return Promise.resolve();
     }
 }
@@ -123,11 +199,15 @@ export class CLIStorageEventManagerAdapter implements IStorageEventManagerAdapte
     readonly status: CLIStatusAdapter;
     readonly converter: CLIConverterAdapter;
 
-    constructor(basePath: string) {
+    constructor(basePath: string, watchEnabled: boolean = false) {
         this.typeGuard = new CLITypeGuardAdapter();
         this.persistence = new CLIPersistenceAdapter(basePath);
-        this.watch = new CLIWatchAdapter(basePath);
+        this.watch = new CLIWatchAdapter(basePath, watchEnabled);
         this.status = new CLIStatusAdapter();
         this.converter = new CLIConverterAdapter();
     }
+
+    close(): Promise<void> {
+        return this.watch.close();
+    }
 }

src/apps/cli/managers/CLIStorageEventManagerAdapter.unit.spec.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import type { IStorageEventWatchHandlers } from "@lib/managers/adapters";
+import type { NodeFile } from "../adapters/NodeTypes";
+
+// ── chokidar mock ──────────────────────────────────────────────────────────────
+// Must be hoisted before imports that pull in chokidar.
+
+const mockWatcher = {
+    on: vi.fn().mockReturnThis(),
+    once: vi.fn((event: string, cb: () => void) => {
+        if (event === "ready") cb();
+        return mockWatcher;
+    }),
+    close: vi.fn(() => Promise.resolve()),
+};
+
+vi.mock("chokidar", () => ({
+    watch: vi.fn(() => mockWatcher),
+}));
+
+import * as chokidar from "chokidar";
+import { CLIStorageEventManagerAdapter } from "./CLIStorageEventManagerAdapter";
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function makeHandlers(): IStorageEventWatchHandlers {
+    return {
+        onCreate: vi.fn(),
+        onChange: vi.fn(),
+        onDelete: vi.fn(),
+        onRename: vi.fn(),
+    } as any;
+}
+
+// ── tests ─────────────────────────────────────────────────────────────────────
+
+describe("CLIStorageEventManagerAdapter", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        // Restore the default once() behaviour (ready fires synchronously).
+        mockWatcher.once.mockImplementation((event: string, cb: () => void) => {
+            if (event === "ready") cb();
+            return mockWatcher;
+        });
+    });
+
+    it("beginWatch is no-op when watchEnabled=false", async () => {
+        const adapter = new CLIStorageEventManagerAdapter("/base", undefined, false);
+        const handlers = makeHandlers();
+
+        await adapter.watch.beginWatch(handlers);
+
+        expect(chokidar.watch).not.toHaveBeenCalled();
+    });
+
+    it("beginWatch calls chokidar.watch when watchEnabled=true", async () => {
+        const adapter = new CLIStorageEventManagerAdapter("/base", undefined, true);
+        const handlers = makeHandlers();
+
+        await adapter.watch.beginWatch(handlers);
+
+        expect(chokidar.watch).toHaveBeenCalledTimes(1);
+        expect(chokidar.watch).toHaveBeenCalledWith(
+            "/base",
+            expect.objectContaining({ ignoreInitial: true })
+        );
+    });
+
+    it("add event produces NodeFile with correct relative path via onCreate", async () => {
+        const basePath = "/vault/base";
+        const adapter = new CLIStorageEventManagerAdapter(basePath, undefined, true);
+        const handlers = makeHandlers();
+
+        await adapter.watch.beginWatch(handlers);
+
+        // Find the callback registered for the "add" event.
+        const addCall = mockWatcher.on.mock.calls.find(([event]) => event === "add");
+        expect(addCall).toBeDefined();
+        const addCallback = addCall![1] as (filePath: string, stats: any) => void;
+
+        const fakeStats = { ctimeMs: 1000, mtimeMs: 2000, size: 42 };
+        addCallback(`${basePath}/subdir/note.md`, fakeStats);
+
+        expect(handlers.onCreate).toHaveBeenCalledTimes(1);
+        const created = (handlers.onCreate as ReturnType<typeof vi.fn>).mock.calls[0][0] as NodeFile;
+        expect(created.path).toBe("subdir/note.md");
+        expect(created.stat?.size).toBe(42);
+    });
+
+    it("close() calls watcher.close()", async () => {
+        const adapter = new CLIStorageEventManagerAdapter("/base", undefined, true);
+        const handlers = makeHandlers();
+
+        await adapter.watch.beginWatch(handlers);
+        await adapter.close();
+
+        expect(mockWatcher.close).toHaveBeenCalledTimes(1);
+    });
+
+    it("close() is safe when no watcher was started", async () => {
+        const adapter = new CLIStorageEventManagerAdapter("/base", undefined, false);
+
+        // Should not throw.
+        await expect(adapter.close()).resolves.toBeUndefined();
+        expect(mockWatcher.close).not.toHaveBeenCalled();
+    });
+
+    it("error event triggers process.exit(1)", async () => {
+        const adapter = new CLIStorageEventManagerAdapter("/base", undefined, true);
+        const handlers = makeHandlers();
+
+        await adapter.watch.beginWatch(handlers);
+
+        const processExitSpy = vi.spyOn(process, "exit").mockImplementation((() => {}) as any);
+
+        const errorCall = mockWatcher.on.mock.calls.find(([event]) => event === "error");
+        expect(errorCall).toBeDefined();
+        const errorCallback = errorCall![1] as (err: Error) => void;
+
+        errorCallback(new Error("disk failure"));
+
+        expect(processExitSpy).toHaveBeenCalledWith(1);
+
+        processExitSpy.mockRestore();
+    });
+});

src/apps/cli/managers/StorageEventManagerCLI.ts

@@ -10,9 +10,10 @@ export class StorageEventManagerCLI extends StorageEventManagerBase<CLIStorageEv
     constructor(
         basePath: string,
         core: LiveSyncBaseCore<ServiceContext, IMinimumLiveSyncCommands>,
-        dependencies: StorageEventManagerBaseDependencies
+        dependencies: StorageEventManagerBaseDependencies,
+        watchEnabled?: boolean
     ) {
-        const adapter = new CLIStorageEventManagerAdapter(basePath);
+        const adapter = new CLIStorageEventManagerAdapter(basePath, watchEnabled);
         super(adapter, dependencies);
         this.core = core;
     }
@@ -25,4 +26,11 @@ export class StorageEventManagerCLI extends StorageEventManagerBase<CLIStorageEv
         // No-op in CLI version
         // Internal file handling is not needed
     }
+
+    /**
+     * Close the file watcher. Call this during graceful shutdown.
+     */
+    close(): Promise<void> {
+        return this.adapter.close();
+    }
 }

src/apps/cli/runtime-package.json

@@ -4,6 +4,7 @@
     "version": "0.0.0",
     "description": "Runtime dependencies for Self-hosted LiveSync CLI Docker image",
     "dependencies": {
+        "chokidar": "^4.0.0",
         "commander": "^14.0.3",
         "werift": "^0.22.9",
         "pouchdb-adapter-http": "^9.0.0",

src/apps/cli/serviceModules/CLIServiceModules.ts

@@ -22,7 +22,8 @@ import type { ServiceModules } from "@lib/interfaces/ServiceModule";
 export function initialiseServiceModulesCLI(
     basePath: string,
     core: LiveSyncBaseCore<ServiceContext, any>,
-    services: InjectableServiceHub<ServiceContext>
+    services: InjectableServiceHub<ServiceContext>,
+    watchEnabled: boolean = false,
 ): ServiceModules {
     const storageAccessManager = new StorageAccessManager();
 
@@ -42,6 +43,12 @@ export function initialiseServiceModulesCLI(
         vaultService: services.vault,
         storageAccessManager: storageAccessManager,
         APIService: services.API,
+    }, false);
+
+    // Close the file watcher during graceful shutdown so the process can exit cleanly.
+    services.appLifecycle.onUnload.addHandler(async () => {
+        await storageEventManager.close();
+        return true;
     });
 
     // Storage access using CLI file system adapter

src/apps/cli/vite.config.ts

@@ -11,11 +11,50 @@ const defaultExternal = [
     "crypto",
     "pouchdb-adapter-leveldb",
     "commander",
+    "chokidar",
     "punycode",
     "werift",
 ];
+// Polyfill FileReader at the very top of the CJS bundle. octagonal-wheels uses
+// FileReader for base64 conversion when Uint8Array.toBase64 (TC39 proposal) is
+// unavailable. Node.js has neither, so we inject a minimal FileReader shim before
+// any module-scope code evaluates.
+const fileReaderPolyfillBanner = `
+if (typeof globalThis.FileReader === "undefined") {
+    globalThis.FileReader = class FileReader {
+        constructor() { this.result = null; this.onload = null; this.onerror = null; }
+        readAsDataURL(blob) {
+            blob.arrayBuffer().then((buf) => {
+                var b64 = require("buffer").Buffer.from(buf).toString("base64");
+                this.result = "data:" + (blob.type || "application/octet-stream") + ";base64," + b64;
+                if (this.onload) this.onload({ target: this });
+            }).catch((err) => { if (this.onerror) this.onerror({ target: this, error: err }); });
+        }
+    };
+}
+`;
+
+function injectBanner(): import("vite").Plugin {
+    return {
+        name: "inject-banner",
+        generateBundle(_options, bundle) {
+            for (const chunk of Object.values(bundle)) {
+                if (chunk.type === "chunk" && chunk.fileName.startsWith("entrypoint")) {
+                    // Insert after the shebang line if present, otherwise at the top.
+                    if (chunk.code.startsWith("#!")) {
+                        const newline = chunk.code.indexOf("\n");
+                        chunk.code = chunk.code.slice(0, newline + 1) + fileReaderPolyfillBanner + chunk.code.slice(newline + 1);
+                    } else {
+                        chunk.code = fileReaderPolyfillBanner + chunk.code;
+                    }
+                }
+            }
+        },
+    };
+}
+
 export default defineConfig({
-    plugins: [svelte()],
+    plugins: [svelte(), injectBanner()],
     resolve: {
         alias: {
             "@lib/worker/bgWorker.ts": "../../lib/src/worker/bgWorker.mock.ts",