### Fixed

- Fixed an issue where using fast synchronisation caused a TypeError in some environments (#953).

.github/workflows/cli-docker.yml

@@ -8,8 +8,6 @@ name: Build and Push CLI Docker Image
 
 on:
     push:
-        branches:
-            - main
         tags:
             - "*.*.*-cli"
     workflow_dispatch:
@@ -43,32 +41,14 @@ jobs:
               id: meta
               run: |
                   VERSION=$(jq -r '.version' manifest.json)
-                  SHORT_SHA=$(git rev-parse --short HEAD)
+                  EPOCH=$(date +%s)
+                  TAG="${VERSION}-${EPOCH}-cli"
                   IMAGE="ghcr.io/${{ github.repository_owner }}/livesync-cli"
-                  
-                  # Build tag list based on the event and git ref
-                  TAGS=""
-                  if [[ "${{ github.ref }}" == refs/tags/* ]]; then
-                      # Stable release builds
-                      TAGS="${IMAGE}:${VERSION}-cli,${IMAGE}:latest,${IMAGE}:${VERSION}-sha-${SHORT_SHA}-cli"
-                  elif [[ "${{ github.ref }}" == refs/heads/main ]]; then
-                      # Bleeding-edge / nightly builds
-                      TAGS="${IMAGE}:edge,${IMAGE}:${VERSION}-dev-sha-${SHORT_SHA}-cli"
-                  else
-                      # Other branches / manual run fallback
-                      TAGS="${IMAGE}:${VERSION}-dev-sha-${SHORT_SHA}-cli"
-                  fi
-                  
-                  # Determine if the image should be pushed
-                  PUSH="true"
-                  if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
-                      if [[ "${{ inputs.dry_run }}" == "true" ]]; then
-                          PUSH="false"
-                      fi
-                  fi
-                  
-                  echo "tags=${TAGS}" >> $GITHUB_OUTPUT
-                  echo "push=${PUSH}" >> $GITHUB_OUTPUT
+                  echo "tag=${TAG}"                        >> $GITHUB_OUTPUT
+                  echo "image=${IMAGE}"                    >> $GITHUB_OUTPUT
+                  echo "full=${IMAGE}:${TAG}"              >> $GITHUB_OUTPUT
+                  echo "version=${IMAGE}:${VERSION}-cli"   >> $GITHUB_OUTPUT
+                  echo "latest=${IMAGE}:latest"            >> $GITHUB_OUTPUT
 
             - name: Log in to GitHub Container Registry
               uses: docker/login-action@v3
@@ -112,7 +92,10 @@ jobs:
               with:
                   context: .
                   file: src/apps/cli/Dockerfile
-                  push: ${{ steps.meta.outputs.push }}
-                  tags: ${{ steps.meta.outputs.tags }}
+                  push: ${{ !(github.event_name == 'workflow_dispatch' && inputs.dry_run) }}
+                  tags: |
+                      ${{ steps.meta.outputs.full }}
+                      ${{ steps.meta.outputs.version }}
+                      ${{ steps.meta.outputs.latest }}
                   cache-from: type=gha
                   cache-to: type=gha,mode=max

.github/workflows/unit-ci.yml

@@ -1,68 +1,111 @@
-# Run Unit test without Harnesses
-name: unit-ci
-
-on:
-  workflow_dispatch:
-  push:
-    branches:
-      - main
-      - beta
-    paths:
-      - 'src/**'
-      - 'test/**'
-      - 'package.json'
-      - 'package-lock.json'
-      - 'tsconfig.json'
-      - 'vite.config.ts'
-      - 'vitest.config*.ts'
-      - 'esbuild.config.mjs'
-      - 'eslint.config.mjs'
-      - '.github/workflows/unit-ci.yml'
-  pull_request:
-    paths:
-      - 'src/**'
-      - 'test/**'
-      - 'package.json'
-      - 'package-lock.json'
-      - 'tsconfig.json'
-      - 'vite.config.ts'
-      - 'vitest.config*.ts'
-      - 'esbuild.config.mjs'
-      - 'eslint.config.mjs'
-      - '.github/workflows/unit-ci.yml'
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: recursive
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '24.x'
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci
-
-      # unit tests do not require Playwright, so we can skip installing its dependencies to save time
-      # - name: Install test dependencies (Playwright Chromium)
-      #   run: npm run test:install-dependencies
-
-      - name: Run unit tests suite with coverage
-        run: npm run test:unit:coverage
-
-      - name: Upload coverage report
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-report
-          path: coverage/**
+# Run Unit test without Harnesses
+name: unit-ci
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      - beta
+    paths:
+      - 'src/**'
+      - 'test/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'tsconfig.json'
+      - 'vite.config.ts'
+      - 'vitest.config*.ts'
+      - 'esbuild.config.mjs'
+      - 'eslint.config.mjs'
+      - '.github/workflows/unit-ci.yml'
+  pull_request:
+    paths:
+      - 'src/**'
+      - 'test/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'tsconfig.json'
+      - 'vite.config.ts'
+      - 'vitest.config*.ts'
+      - 'esbuild.config.mjs'
+      - 'eslint.config.mjs'
+      - '.github/workflows/unit-ci.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  unit-test:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run unit tests suite with coverage
+        run: npm run test:unit:coverage
+
+      - name: Upload coverage report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: unit-coverage-report
+          path: coverage/**
+
+  integration-test:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Create environment configuration files
+        run: |
+          cat <<EOF > .env
+          BUILD_MODE=dev
+          PATHS_TEST_INSTALL=
+          EOF
+          cat <<EOF > .test.env
+          hostname=http://127.0.0.1:5989/
+          dbname=livesync-test-db2
+          username=admin
+          password=testpassword
+          minioEndpoint=http://127.0.0.1:9000
+          accessKey=minioadmin
+          secretKey=minioadmin
+          bucketName=livesync-test-bucket
+          EOF
+
+      - name: Start CouchDB container
+        run: npm run test:docker-couchdb:start
+
+      - name: Run integration tests
+        run: npm run test:integration
+
+      - name: Stop CouchDB container
+        if: always()
+        run: npm run test:docker-couchdb:stop || true

AGENTS.md

@@ -32,6 +32,9 @@ Always adhere to the following stylistic and spelling rules:
    - Use **'dialogue'** in documentation, user-facing messages, and general text. Use **'dialog'** only inside source code (e.g. class names, methods).
    - Use the hyphenated form **'plug-in'** in user-facing text. Use **'plugin'** only in codebase files, configuration settings, or technical contexts.
 
+5. **User Communication Language**:
+   - Always reply to the user in the language in which they asked the question.
+
 ---
 
 ## Technical & Architecture Rules

devs.md

@@ -54,8 +54,13 @@ To facilitate development and testing, the build process can automatically copy
 
 - ~~**Deno Tests**: Unit tests for platform-independent code (e.g., `HashManager.test.ts`)~~
     - This is now obsolete, migrated to vitest.
-- **Vitest** (`vitest.config.ts`): E2E test by Browser-based-harness using Playwright, unit tests.
-    - Unit tests should be `*.unit.spec.ts` and placed alongside the implementation file (e.g., `ChunkFetcher.unit.spec.ts`).
+- **Vitest**:
+    - **Unit Tests** (`vitest.config.unit.ts`): Unit tests run in Node.js (excluding harnesses and integration tests). Unit tests should be `*.unit.spec.ts` and placed alongside the implementation file (e.g., `ChunkFetcher.unit.spec.ts`). Executed via `npm run test:unit`.
+    - **Integration Tests** (`vitest.config.integration.ts`): Tests run in Node.js against a real CouchDB instance. Integration tests should be `*.integration.spec.ts` or `*.integration.test.ts` and placed alongside the implementation file (e.g., `StreamingFetch.integration.spec.ts`). Executed via `npm run test:integration`.
+        - If you add a feature that interacts with the remote database (e.g., replication changes, custom changes feed parameters, or custom HTTP queries), you strongly expected to write an integration test to verify the behaviour against a real CouchDB server.
+    - **E2E Tests** (`vitest.config.ts`): End-to-end tests run in a browser-based harness using Playwright/Chromium to test full synchronisation scenarios. Executed via `npm run test`.
+    - **P2P Tests** (`vitest.config.p2p.ts`): Browser-based Peer-to-Peer replication tests. Executed via `npm run test:p2p`.
+    - **RPC Unit Tests** (`vitest.config.rpc-unit.ts`): RPC-specific unit tests with coverage thresholds.
 
 - **Docker Services**: Tests require CouchDB, MinIO (S3), and P2P services:
     ```bash
@@ -63,11 +68,11 @@ To facilitate development and testing, the build process can automatically copy
     npm run test:full              # Run tests with coverage
     npm run test:docker-all:stop   # Stop services
     ```
-    If some services are not needed, start only required ones (e.g., `test:docker-couchdb:start`)
+    If some services are not needed, start only required ones (e.g., `test:docker-couchdb:start`).
     Note that if services are already running, starting script will fail. Please stop them first.
 
 - **Test Structure**:
-    - `test/suite/` - Integration tests for sync operations
+    - `test/suite/` - E2E tests for sync operations (running in browser)
     - `test/unit/` - Unit tests (via vitest, as harness is browser-based)
     - `test/harness/` - Mock implementations (e.g., `obsidian-mock.ts`)
 
@@ -151,7 +156,7 @@ Hence, the new feature should be implemented as follows:
 
 ## Common Patterns
 
-### Module Implementation
+### Module Implementation (Now not recommended for new features, use services instead)
 
 ```typescript
 export class ModuleExample extends AbstractObsidianModule {
@@ -204,6 +209,7 @@ In short, the situation remains unchanged for me, but it means you all become a
 ## Contribution Guidelines
 
 - Follow existing code style and conventions
+- Write integration tests (`*.integration.spec.ts` or `*.integration.test.ts`) when adding or modifying features that interact with the remote database, and ensure that they pass in the CI workflow.
 - Please bump dependencies with care, check artifacts after updates, with diff-tools and only expected changes in the build output (to avoid unexpected vulnerabilities).
 - When adding new features, please consider it has an OSS implementation, and avoid using proprietary services or APIs that may limit usage.
     - For example, any functionality to connect to a new type of server is expected to either have an OSS implementation available for that server, or to be managed under some responsibilities and/or limitations without disrupting existing functionality, and scope for surveillance reduced by some means (e.g., by client-side encryption, auditing the server ourselves).

package.json

@@ -29,6 +29,7 @@
         "unittest": "deno test -A --no-check --coverage=cov_profile  --v8-flags=--expose-gc  --trace-leaks  ./src/",
         "test": "vitest run",
         "test:unit": "vitest run --config vitest.config.unit.ts",
+        "test:integration": "vitest run --config vitest.config.integration.ts",
         "test:unit:coverage": "vitest run --config vitest.config.unit.ts --coverage",
         "test:install-playwright": "npx playwright install chromium",
         "test:install-dependencies": "npm run test:install-playwright",

updates.md

@@ -5,6 +5,14 @@ The head note of 0.25 is now in [updates_old.md](https://github.com/vrtmrz/obsid
 
 ## unreleased
 
+12th June, 2026
+
+### Fixed
+
+- Fixed an issue where using fast synchronisation caused a TypeError in some environments (#953).
+
+## unreleased
+
 ### Fixed (CLI, automated)
 
 - Fixed an issue where the mirror command could fail to apply updates when conflict preservation checks prevented overwriting unsynchronised local changes, even when the `force` parameter or `writeDocumentsIfConflicted` setting was enabled.

vitest.config.common.ts

@@ -1,3 +1,9 @@
+/**
+ * @file vitest.config.common.ts
+ * @description Shared base configuration for all Vitest test environments in the project,
+ * defining common resolve aliases, build defines, and plugins (svelte, inlineWorker).
+ * This configuration is not executed directly, but is imported and merged by other specific configuration files.
+ */
 import { defineConfig } from "vitest/config";
 import { svelte } from "@sveltejs/vite-plugin-svelte";
 import { sveltePreprocess } from "svelte-preprocess";

vitest.config.integration.ts

@@ -0,0 +1,25 @@
+/**
+ * @file vitest.config.integration.ts
+ * @description Configuration for running database integration tests in Node.js against a real CouchDB instance
+ * (e.g. testing streaming changes, database connectivity, and replication status checks).
+ * This is executed via `npm run test:integration` during development and is run in the GitHub Actions `unit-ci` workflow.
+ */
+import { defineConfig, mergeConfig } from "vitest/config";
+import viteConfig from "./vitest.config.common";
+
+export default mergeConfig(
+    viteConfig,
+    defineConfig({
+        resolve: {
+            alias: {
+                obsidian: "", // prevent accidental imports of obsidian types in integration tests
+            },
+        },
+        test: {
+            logHeapUsage: true,
+            name: "integration-tests",
+            include: ["**/*.integration.spec.ts", "**/*.integration.test.ts"],
+            exclude: ["test/**", "src/apps/**/testdeno/**"],
+        },
+    })
+);

vitest.config.p2p.ts

@@ -1,3 +1,9 @@
+/**
+ * @file vitest.config.p2p.ts
+ * @description Configuration for running browser-based Peer-to-Peer (P2P) replication tests
+ * in Playwright (Chromium) using Trystero and Nostr relays.
+ * This is executed via the `npm run test:p2p` command (which runs `test/suitep2p/run-p2p-tests.sh` internally).
+ */
 import { defineConfig, mergeConfig } from "vitest/config";
 import { playwright } from "@vitest/browser-playwright";
 import viteConfig from "./vitest.config.common";

vitest.config.rpc-unit.ts

@@ -1,3 +1,9 @@
+/**
+ * @file vitest.config.rpc-unit.ts
+ * @description Configuration for running RPC-specific unit tests (such as RpcRoom and transport layers) in Node.js,
+ * enforcing coverage thresholds on the RPC sub-module.
+ * This can be run manually to verify RPC-specific coverage, or is matched by the glob patterns in `npm run test:unit`.
+ */
 import { defineConfig, mergeConfig } from "vitest/config";
 import viteConfig from "./vitest.config.common";
 

vitest.config.ts

@@ -1,3 +1,9 @@
+/**
+ * @file vitest.config.ts
+ * @description Configuration for running browser-based end-to-end (E2E) integration tests
+ * using Playwright (Chromium) to test replication and synchronisation scenarios.
+ * This is executed when running the full test suite via `npm run test` or `npm run test:full`.
+ */
 import { defineConfig, mergeConfig } from "vitest/config";
 import { playwright } from "@vitest/browser-playwright";
 import viteConfig from "./vitest.config.common";

vitest.config.unit.ts

@@ -1,3 +1,8 @@
+/**
+ * @file vitest.config.unit.ts
+ * @description Configuration for running unit tests in Node.js (excluding browser harnesses, E2E, and database integration tests).
+ * This is executed during local development via `npm run test:unit` (or with coverage via `npm run test:unit:coverage`), and automatically in the GitHub Actions `unit-ci` workflow.
+ */
 import { defineConfig, mergeConfig } from "vitest/config";
 import viteConfig from "./vitest.config.common";