feat(tests): add Deno-based tests for checking CLI functionality in the same-codebase between platforms.

src/apps/cli/testdeno/helpers/backgroundCli.ts

@@ -0,0 +1,112 @@
+import { CLI_DIR } from "./cli.ts";
+import { join } from "@std/path";
+
+const CLI_DIST = join(CLI_DIR, "dist", "index.cjs");
+const VERBOSE_ENABLED = Deno.env.get("LIVESYNC_CLI_VERBOSE") === "1";
+const DEBUG_ENABLED = Deno.env.get("LIVESYNC_CLI_DEBUG") === "1";
+
+function decorateArgs(args: string[]): string[] {
+    return DEBUG_ENABLED ? ["-d", ...args] : VERBOSE_ENABLED ? ["-v", ...args] : args;
+}
+
+async function pump(
+    stream: ReadableStream<Uint8Array>,
+    sink: (text: string) => void,
+    teeTarget: WritableStream<Uint8Array> | null
+): Promise<void> {
+    const reader = stream.getReader();
+    const writer = teeTarget?.getWriter();
+    const dec = new TextDecoder();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            if (!value) continue;
+            sink(dec.decode(value, { stream: true }));
+            if (writer) {
+                await writer.write(value);
+            }
+        }
+    } finally {
+        if (writer) writer.releaseLock();
+        reader.releaseLock();
+    }
+}
+
+export class BackgroundCliProcess {
+    #stdout = "";
+    #stderr = "";
+    #stdoutDone: Promise<void>;
+    #stderrDone: Promise<void>;
+
+    constructor(
+        readonly child: Deno.ChildProcess,
+        readonly args: string[]
+    ) {
+        this.#stdoutDone = pump(
+            child.stdout,
+            (text) => {
+                this.#stdout += text;
+            },
+            null
+        );
+        this.#stderrDone = pump(
+            child.stderr,
+            (text) => {
+                this.#stderr += text;
+            },
+            null
+        );
+    }
+
+    get stdout(): string {
+        return this.#stdout;
+    }
+
+    get stderr(): string {
+        return this.#stderr;
+    }
+
+    get combined(): string {
+        return this.#stdout + this.#stderr;
+    }
+
+    async waitUntilContains(needle: string, timeoutMs = 15000): Promise<void> {
+        const started = Date.now();
+        while (Date.now() - started < timeoutMs) {
+            if (this.combined.includes(needle)) return;
+            const status = await Promise.race([
+                this.child.status.then((s) => ({ type: "status" as const, status: s })),
+                new Promise<{ type: "tick" }>((resolve) => setTimeout(() => resolve({ type: "tick" }), 100)),
+            ]);
+            if (status.type === "status") {
+                throw new Error(
+                    `Background CLI exited before '${needle}' appeared (code ${status.status.code})\n${this.combined}`
+                );
+            }
+        }
+        throw new Error(`Timed out waiting for '${needle}'\n${this.combined}`);
+    }
+
+    async stop(): Promise<number> {
+        try {
+            this.child.kill("SIGTERM");
+        } catch {
+            // ignore already-exited processes
+        }
+        const status = await this.child.status;
+        await Promise.all([this.#stdoutDone, this.#stderrDone]);
+        return status.code;
+    }
+}
+
+export function startCliInBackground(...args: string[]): BackgroundCliProcess {
+    const child = new Deno.Command("node", {
+        args: [CLI_DIST, ...decorateArgs(args)],
+        cwd: CLI_DIR,
+        stdin: "null",
+        stdout: "piped",
+        stderr: "piped",
+    }).spawn();
+    return new BackgroundCliProcess(child, args);
+}

src/apps/cli/testdeno/helpers/cli.ts

@@ -0,0 +1,231 @@
+import { join } from "@std/path";
+
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+// This file lives at: src/apps/cli/testdeno/helpers/cli.ts
+// CLI root (src/apps/cli/) is two levels up.
+// import.meta.dirname is available in Deno 1.40+ as an OS-native path string.
+export const CLI_DIR: string = join(import.meta.dirname!, "..", "..");
+const CLI_DIST = join(CLI_DIR, "dist", "index.cjs");
+
+// ---------------------------------------------------------------------------
+// Result type
+// ---------------------------------------------------------------------------
+export interface CliResult {
+    stdout: string;
+    stderr: string;
+    /** stdout + stderr concatenated — useful for assertion messages. */
+    combined: string;
+    code: number;
+}
+
+const TEE_ENABLED = Deno.env.get("LIVESYNC_TEST_TEE") === "1";
+const VERBOSE_ENABLED = Deno.env.get("LIVESYNC_CLI_VERBOSE") === "1";
+const DEBUG_ENABLED = Deno.env.get("LIVESYNC_CLI_DEBUG") === "1";
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function concatChunks(chunks: Uint8Array[]): Uint8Array {
+    const total = chunks.reduce((n, c) => n + c.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) {
+        out.set(c, offset);
+        offset += c.length;
+    }
+    return out;
+}
+
+async function collectStream(
+    stream: ReadableStream<Uint8Array>,
+    teeTarget: WritableStream<Uint8Array> | null
+): Promise<Uint8Array> {
+    const reader = stream.getReader();
+    const chunks: Uint8Array[] = [];
+    const writer = teeTarget?.getWriter();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            if (value) {
+                chunks.push(value);
+                if (writer) {
+                    await writer.write(value);
+                }
+            }
+        }
+    } finally {
+        if (writer) {
+            writer.releaseLock();
+        }
+        reader.releaseLock();
+    }
+    return concatChunks(chunks);
+}
+
+async function runNodeCommand(args: string[], stdinData?: Uint8Array): Promise<CliResult> {
+    const cliArgs = DEBUG_ENABLED ? ["-d", ...args] : VERBOSE_ENABLED ? ["-v", ...args] : args;
+    const child = new Deno.Command("node", {
+        args: [CLI_DIST, ...cliArgs],
+        cwd: CLI_DIR,
+        stdin: stdinData ? "piped" : "null",
+        stdout: "piped",
+        stderr: "piped",
+    }).spawn();
+
+    const stdoutPromise = collectStream(child.stdout, TEE_ENABLED ? Deno.stdout.writable : null);
+    const stderrPromise = collectStream(child.stderr, TEE_ENABLED ? Deno.stderr.writable : null);
+
+    if (stdinData) {
+        const w = child.stdin.getWriter();
+        await w.write(stdinData);
+        await w.close();
+    }
+
+    const [status, stdout, stderr] = await Promise.all([child.status, stdoutPromise, stderrPromise]);
+
+    const dec = new TextDecoder();
+    const out = dec.decode(stdout);
+    const err = dec.decode(stderr);
+    return { stdout: out, stderr: err, combined: out + err, code: status.code };
+}
+
+function isTransientNetworkError(message: string): boolean {
+    const m = message.toLowerCase();
+    return (
+        m.includes("fetch failed") ||
+        m.includes("econnreset") ||
+        m.includes("econnrefused") ||
+        m.includes("und_err_socket") ||
+        m.includes("other side closed")
+    );
+}
+
+// ---------------------------------------------------------------------------
+// Core runners
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the CLI (node dist/index.cjs) with the supplied arguments.
+ * Pass the vault / DB path as the first argument, exactly as the bash helpers
+ * do.  Does NOT throw on non-zero exit — check `.code` yourself.
+ */
+export async function runCli(...args: string[]): Promise<CliResult> {
+    const retries = Number(Deno.env.get("LIVESYNC_CLI_RETRY") ?? "0");
+    for (let attempt = 0; ; attempt++) {
+        const result = await runNodeCommand(args);
+        if (result.code === 0) return result;
+
+        if (attempt >= retries || !isTransientNetworkError(result.combined)) {
+            return result;
+        }
+        const waitMs = 400 * (attempt + 1);
+        console.warn(`[WARN] transient CLI failure, retrying (${attempt + 1}/${retries}) in ${waitMs}ms`);
+        await sleep(waitMs);
+    }
+}
+
+/**
+ * Run the CLI and throw if it exits non-zero.  Returns stdout.
+ */
+export async function runCliOrFail(...args: string[]): Promise<string> {
+    const r = await runCli(...args);
+    if (r.code !== 0) {
+        throw new Error(`CLI exited with code ${r.code}\nstdout: ${r.stdout}\nstderr: ${r.stderr}`);
+    }
+    return r.stdout;
+}
+
+/**
+ * Run the CLI with data piped to stdin (equivalent to `echo … | run_cli …`
+ * or `cat file | run_cli …`).
+ */
+export async function runCliWithInput(input: string | Uint8Array, ...args: string[]): Promise<CliResult> {
+    const data = typeof input === "string" ? new TextEncoder().encode(input) : input;
+
+    const retries = Number(Deno.env.get("LIVESYNC_CLI_RETRY") ?? "0");
+    for (let attempt = 0; ; attempt++) {
+        const result = await runNodeCommand(args, data);
+        if (result.code === 0) return result;
+
+        if (attempt >= retries || !isTransientNetworkError(result.combined)) {
+            return result;
+        }
+        const waitMs = 400 * (attempt + 1);
+        console.warn(`[WARN] transient CLI(stdin) failure, retrying (${attempt + 1}/${retries}) in ${waitMs}ms`);
+        await sleep(waitMs);
+    }
+}
+
+/**
+ * runCliWithInput — throws on non-zero exit, returns stdout.
+ */
+export async function runCliWithInputOrFail(input: string | Uint8Array, ...args: string[]): Promise<string> {
+    const r = await runCliWithInput(input, ...args);
+    if (r.code !== 0) {
+        throw new Error(`CLI (with stdin) exited with code ${r.code}\nstdout: ${r.stdout}\nstderr: ${r.stderr}`);
+    }
+    return r.stdout;
+}
+
+// ---------------------------------------------------------------------------
+// Output helpers
+// ---------------------------------------------------------------------------
+
+/** Strip the CLIWatchAdapter banner line that `cat` emits. */
+export function sanitiseCatStdout(raw: string): string {
+    return raw
+        .split("\n")
+        .filter((l) => l !== "[CLIWatchAdapter] File watching is not enabled in CLI version")
+        .join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Assertions (parity with test-helpers.sh)
+// ---------------------------------------------------------------------------
+
+export function assertContains(haystack: string, needle: string, message: string): void {
+    if (!haystack.includes(needle)) {
+        throw new Error(`[FAIL] ${message}\nExpected to find: ${JSON.stringify(needle)}\nActual output:\n${haystack}`);
+    }
+}
+
+export function assertNotContains(haystack: string, needle: string, message: string): void {
+    if (haystack.includes(needle)) {
+        throw new Error(`[FAIL] ${message}\nDid NOT expect: ${JSON.stringify(needle)}\nActual output:\n${haystack}`);
+    }
+}
+
+export async function assertFilesEqual(expectedPath: string, actualPath: string, message: string): Promise<void> {
+    const [expected, actual] = await Promise.all([Deno.readFile(expectedPath), Deno.readFile(actualPath)]);
+    if (expected.length !== actual.length || expected.some((b, i) => b !== actual[i])) {
+        const hex = async (d: Uint8Array<ArrayBuffer>) => {
+            const h = await crypto.subtle.digest("SHA-256", d);
+            return [...new Uint8Array(h)].map((b) => b.toString(16).padStart(2, "0")).join("");
+        };
+        throw new Error(
+            `[FAIL] ${message}\nexpected SHA-256: ${await hex(expected)}\nactual   SHA-256: ${await hex(actual)}`
+        );
+    }
+}
+
+// ---------------------------------------------------------------------------
+// JSON helpers
+// ---------------------------------------------------------------------------
+
+export async function readJsonFile<T = Record<string, unknown>>(filePath: string): Promise<T> {
+    return JSON.parse(await Deno.readTextFile(filePath)) as T;
+}
+
+export function jsonStringField(jsonText: string, field: string): string {
+    const data = JSON.parse(jsonText) as Record<string, unknown>;
+    const value = data[field];
+    return typeof value === "string" ? value : "";
+}
+
+export function jsonFieldIsNa(data: Record<string, unknown>, field: string): boolean {
+    return data[field] === "N/A";
+}

src/apps/cli/testdeno/helpers/docker.ts

@@ -0,0 +1,530 @@
+/**
+ * Docker service management for tests.
+ *
+ * CouchDB start/stop/init is implemented directly using `docker` CLI commands
+ * and the Fetch API, so it works on any platform where Docker (Desktop) is
+ * available — including Windows — without needing bash.
+ */
+
+type DockerInvoker = {
+    bin: string;
+    prefix: string[];
+    label: string;
+};
+
+let dockerInvokerPromise: Promise<DockerInvoker> | null = null;
+const DOCKER_TEE = Deno.env.get("LIVESYNC_DOCKER_TEE") === "1" || Deno.env.get("LIVESYNC_TEST_TEE") === "1";
+
+// ---------------------------------------------------------------------------
+// Low-level docker wrapper
+// ---------------------------------------------------------------------------
+
+function parseCommand(command: string): { bin: string; prefix: string[] } {
+    const parts = command.trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0) {
+        throw new Error("LIVESYNC_DOCKER_COMMAND is empty");
+    }
+    return { bin: parts[0], prefix: parts.slice(1) };
+}
+
+async function runCommand(bin: string, args: string[]): Promise<{ code: number; stdout: string; stderr: string }> {
+    const cmd = new Deno.Command(bin, {
+        args,
+        stdin: "null",
+        stdout: "piped",
+        stderr: "piped",
+    });
+    try {
+        const { code, stdout, stderr } = await cmd.output();
+        const dec = new TextDecoder();
+        const result = {
+            code,
+            stdout: dec.decode(stdout),
+            stderr: dec.decode(stderr),
+        };
+        if (DOCKER_TEE) {
+            if (result.stdout.trim().length > 0) {
+                console.log(`[docker:${bin}] ${result.stdout.trimEnd()}`);
+            }
+            if (result.stderr.trim().length > 0) {
+                console.error(`[docker:${bin}] ${result.stderr.trimEnd()}`);
+            }
+        }
+        return result;
+    } catch (err) {
+        if (err instanceof Deno.errors.NotFound) {
+            return {
+                code: 127,
+                stdout: "",
+                stderr: `Command not found: ${bin}`,
+            };
+        }
+        throw err;
+    }
+}
+
+async function resolveDockerInvoker(): Promise<DockerInvoker> {
+    const custom = Deno.env.get("LIVESYNC_DOCKER_COMMAND")?.trim();
+    if (custom) {
+        const parsed = parseCommand(custom);
+        const runner: DockerInvoker = {
+            ...parsed,
+            label: `custom(${custom})`,
+        };
+
+        // Validate custom command eagerly so misconfiguration fails fast.
+        const checkArgs = runner.prefix.length === 0 ? ["--version"] : [...runner.prefix, "docker", "--version"];
+        const check = await runCommand(runner.bin, checkArgs);
+        if (check.code !== 0) {
+            throw new Error(`LIVESYNC_DOCKER_COMMAND is not usable: ${custom}\n${check.stderr || check.stdout}`);
+        }
+        return runner;
+    }
+
+    const mode = (Deno.env.get("LIVESYNC_DOCKER_MODE") ?? "auto").toLowerCase();
+    const onWindows = Deno.build.os === "windows";
+
+    const native: DockerInvoker = { bin: "docker", prefix: [], label: "docker" };
+    const wsl: DockerInvoker = { bin: "wsl", prefix: [], label: "wsl docker" };
+
+    if (mode === "native") {
+        return native;
+    }
+    if (mode === "wsl") {
+        return wsl;
+    }
+    if (mode !== "auto") {
+        throw new Error(`Unsupported LIVESYNC_DOCKER_MODE='${mode}'. Use auto, native, or wsl.`);
+    }
+
+    // On Windows we prefer `wsl docker` first, then native docker.
+    // This typically works better in setups where Docker is installed only in
+    // WSL and not exposed as docker.exe on PATH.
+    const candidates = onWindows ? [wsl, native] : [native, wsl];
+    for (const c of candidates) {
+        if (c.bin === "docker") {
+            const r = await runCommand("docker", ["--version"]);
+            if (r.code === 0) return c;
+            continue;
+        }
+        const r = await runCommand("wsl", ["docker", "--version"]);
+        if (r.code === 0) return c;
+    }
+
+    throw new Error(
+        [
+            "Docker command is not available.",
+            "Set one of:",
+            "- LIVESYNC_DOCKER_MODE=native",
+            "- LIVESYNC_DOCKER_MODE=wsl",
+            "- LIVESYNC_DOCKER_COMMAND='docker'",
+            "- LIVESYNC_DOCKER_COMMAND='wsl docker'",
+        ].join("\n")
+    );
+}
+
+async function getDockerInvoker(): Promise<DockerInvoker> {
+    if (!dockerInvokerPromise) {
+        dockerInvokerPromise = resolveDockerInvoker().then((r) => {
+            console.log(`[INFO] docker runner: ${r.label}`);
+            return r;
+        });
+    }
+    return await dockerInvokerPromise;
+}
+
+async function docker(...args: string[]): Promise<{ code: number; stdout: string; stderr: string }> {
+    const invoker = await getDockerInvoker();
+
+    // Either:
+    //   docker <args>
+    // Or:
+    //   wsl docker <args>
+    const finalArgs =
+        invoker.prefix.length === 0
+            ? invoker.bin === "wsl"
+                ? ["docker", ...args]
+                : args
+            : [...invoker.prefix, ...args];
+
+    const r = await runCommand(invoker.bin, finalArgs);
+    return { code: r.code, stdout: r.stdout, stderr: r.stderr };
+}
+
+async function dockerOrFail(...args: string[]): Promise<string> {
+    const r = await docker(...args);
+    if (r.code !== 0) {
+        throw new Error(`docker ${args[0]} failed (code ${r.code}): ${r.stderr.trim()}`);
+    }
+    return r.stdout;
+}
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForCouchdbStable(hostname: string, user: string, password: string): Promise<void> {
+    const h = hostname.replace(/\/$/, "").replace("localhost", "127.0.0.1");
+    const auth = btoa(`${user}:${password}`);
+    const headers = { Authorization: `Basic ${auth}` };
+    let consecutive = 0;
+    for (let i = 0; i < 30; i++) {
+        try {
+            const r = await fetch(`${h}/_up`, {
+                headers,
+                signal: AbortSignal.timeout(3000),
+            });
+            if (r.ok) {
+                consecutive++;
+                if (consecutive >= 3) return;
+            } else {
+                consecutive = 0;
+            }
+        } catch {
+            consecutive = 0;
+        }
+        await sleep(500);
+    }
+    throw new Error("CouchDB did not become stable in time");
+}
+
+// ---------------------------------------------------------------------------
+// Fetch with retry (mirrors cli_test_curl_json() retry loop)
+// ---------------------------------------------------------------------------
+
+async function fetchRetry(
+    url: string,
+    init: RequestInit,
+    retries = 30,
+    delayMs = 2000,
+    allowStatus: number[] = []
+): Promise<void> {
+    let lastError: unknown;
+    let lastStatus: number | undefined;
+    for (let i = 0; i < retries; i++) {
+        try {
+            const r = await fetch(url, {
+                signal: AbortSignal.timeout(5000),
+                ...init,
+            });
+            lastStatus = r.status;
+            await r.body?.cancel().catch(() => {});
+            if (r.ok || allowStatus.includes(r.status)) return;
+            lastError = `HTTP ${r.status}`;
+        } catch (e) {
+            lastError = e;
+        }
+        await sleep(delayMs);
+    }
+    throw new Error(
+        `Could not reach ${url} after ${retries} retries: ${lastError} (last status: ${lastStatus ?? "N/A"})`
+    );
+}
+
+// ---------------------------------------------------------------------------
+// CouchDB
+// ---------------------------------------------------------------------------
+//
+// TODO: these values could be configurable via environment variables.
+//
+const COUCHDB_CONTAINER = "couchdb-test";
+const COUCHDB_IMAGE = "couchdb:3.5.0";
+
+const MINIO_CONTAINER = "minio-test";
+const MINIO_IMAGE = "minio/minio";
+const MINIO_MC_IMAGE = "minio/mc";
+
+export async function stopCouchdb(): Promise<void> {
+    await docker("stop", COUCHDB_CONTAINER);
+    await docker("rm", COUCHDB_CONTAINER);
+}
+
+/**
+ * Start a CouchDB test container, initialise it, and create the test DB.
+ * Mirrors cli_test_start_couchdb() from test-helpers.sh, using direct
+ * docker / fetch calls instead of the bash util scripts.
+ */
+export async function startCouchdb(couchdbUri: string, user: string, password: string, dbname: string): Promise<void> {
+    console.log("[INFO] stopping leftover CouchDB container if present");
+    await stopCouchdb().catch(() => {});
+
+    console.log("[INFO] starting CouchDB test container");
+    await dockerOrFail(
+        "run",
+        "-d",
+        "--name",
+        COUCHDB_CONTAINER,
+        "-p",
+        // TODO: port mapping should be configurable.
+        "5989:5984",
+        "-e",
+        `COUCHDB_USER=${user}`,
+        "-e",
+        `COUCHDB_PASSWORD=${password}`,
+        "-e",
+        "COUCHDB_SINGLE_NODE=y",
+        COUCHDB_IMAGE
+    );
+
+    console.log("[INFO] initialising CouchDB");
+    await initCouchdb(couchdbUri, user, password);
+
+    console.log("[INFO] waiting for CouchDB to become stable");
+    await waitForCouchdbStable(couchdbUri, user, password);
+
+    console.log(`[INFO] creating test database: ${dbname}`);
+    await createCouchdbDatabase(couchdbUri, user, password, dbname);
+}
+
+/**
+ * Mirror couchdb-init.sh: configure single-node CouchDB via its REST API.
+ */
+async function initCouchdb(hostname: string, user: string, password: string, node = "_local"): Promise<void> {
+    // Podman environments often resolve localhost to ::1; use 127.0.0.1 like
+    // the bash script does.
+    const h = hostname.replace(/\/$/, "").replace("localhost", "127.0.0.1");
+    const auth = btoa(`${user}:${password}`);
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Basic ${auth}`,
+    };
+
+    const calls: Array<[string, string, string]> = [
+        [
+            "POST",
+            `${h}/_cluster_setup`,
+            JSON.stringify({
+                action: "enable_single_node",
+                username: user,
+                password,
+                bind_address: "0.0.0.0",
+                port: 5984,
+                singlenode: true,
+            }),
+        ],
+        ["PUT", `${h}/_node/${node}/_config/chttpd/require_valid_user`, '"true"'],
+        ["PUT", `${h}/_node/${node}/_config/chttpd_auth/require_valid_user`, '"true"'],
+        ["PUT", `${h}/_node/${node}/_config/httpd/WWW-Authenticate`, '"Basic realm=\\"couchdb\\""'],
+        ["PUT", `${h}/_node/${node}/_config/httpd/enable_cors`, '"true"'],
+        ["PUT", `${h}/_node/${node}/_config/chttpd/enable_cors`, '"true"'],
+        ["PUT", `${h}/_node/${node}/_config/chttpd/max_http_request_size`, '"4294967296"'],
+        ["PUT", `${h}/_node/${node}/_config/couchdb/max_document_size`, '"50000000"'],
+        ["PUT", `${h}/_node/${node}/_config/cors/credentials`, '"true"'],
+        ["PUT", `${h}/_node/${node}/_config/cors/origins`, '"*"'],
+    ];
+
+    for (const [method, url, body] of calls) {
+        await fetchRetry(url, { method, headers, body });
+    }
+}
+
+export async function createCouchdbDatabase(
+    hostname: string,
+    user: string,
+    password: string,
+    dbname: string
+): Promise<void> {
+    const h = hostname.replace(/\/$/, "").replace("localhost", "127.0.0.1");
+    const auth = btoa(`${user}:${password}`);
+    await fetchRetry(`${h}/${dbname}`, {
+        method: "PUT",
+        headers: { Authorization: `Basic ${auth}` },
+    });
+}
+
+/** Update a CouchDB document via PUT. Returns the updated document. */
+export async function updateCouchdbDoc(
+    hostname: string,
+    user: string,
+    password: string,
+    docUrl: string,
+    updater: (doc: Record<string, unknown>) => Record<string, unknown>
+): Promise<void> {
+    const h = hostname.replace(/\/$/, "").replace("localhost", "127.0.0.1");
+    const auth = btoa(`${user}:${password}`);
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Basic ${auth}`,
+    };
+    const getRes = await fetch(`${h}/${docUrl}`, { headers });
+    const current = (await getRes.json()) as Record<string, unknown>;
+    const updated = updater(current);
+    await fetchRetry(`${h}/${docUrl}`, {
+        method: "PUT",
+        headers,
+        body: JSON.stringify(updated),
+    });
+}
+
+// ---------------------------------------------------------------------------
+// MinIO
+// ---------------------------------------------------------------------------
+
+function shQuote(value: string): string {
+    return `'${value.split("'").join(`'"'"'`)}'`;
+}
+
+export async function stopMinio(): Promise<void> {
+    await docker("stop", MINIO_CONTAINER);
+    await docker("rm", MINIO_CONTAINER);
+}
+
+async function initMinioBucket(
+    minioEndpoint: string,
+    accessKey: string,
+    secretKey: string,
+    bucket: string
+): Promise<boolean> {
+    const cmd =
+        `mc alias set myminio ${shQuote(minioEndpoint)} ${shQuote(accessKey)} ${shQuote(secretKey)} >/dev/null 2>&1 && ` +
+        `mc mb --ignore-existing myminio/${shQuote(bucket)} >/dev/null 2>&1`;
+    const r = await docker("run", "--rm", "--network", "host", "--entrypoint", "/bin/sh", MINIO_MC_IMAGE, "-c", cmd);
+    return r.code === 0;
+}
+
+async function waitForMinioBucket(
+    minioEndpoint: string,
+    accessKey: string,
+    secretKey: string,
+    bucket: string
+): Promise<void> {
+    for (let i = 0; i < 30; i++) {
+        const checkCmd =
+            `mc alias set myminio ${shQuote(minioEndpoint)} ${shQuote(accessKey)} ${shQuote(secretKey)} >/dev/null 2>&1 && ` +
+            `mc ls myminio/${shQuote(bucket)} >/dev/null 2>&1`;
+        const check = await docker(
+            "run",
+            "--rm",
+            "--network",
+            // Now I used host networking to access the container via localhost for some environments (Docker Desktop on Windows).
+            // We need something good idea to work across all environments.
+            "host",
+            "--entrypoint",
+            "/bin/sh",
+            MINIO_MC_IMAGE,
+            "-c",
+            checkCmd
+        );
+        if (check.code === 0) {
+            return;
+        }
+        await initMinioBucket(minioEndpoint, accessKey, secretKey, bucket);
+        await sleep(2000);
+    }
+    throw new Error(`MinIO bucket not ready: ${bucket}`);
+}
+
+export async function startMinio(
+    minioEndpoint: string,
+    accessKey: string,
+    secretKey: string,
+    bucket: string
+): Promise<void> {
+    console.log("[INFO] stopping leftover MinIO container if present");
+    await stopMinio().catch(() => {});
+
+    console.log("[INFO] starting MinIO test container");
+    await dockerOrFail(
+        "run",
+        "-d",
+        "--name",
+        MINIO_CONTAINER,
+        // TODO: Ports should be configurable.
+        "-p",
+        "9000:9000",
+        "-p",
+        "9001:9001",
+        "-e",
+        `MINIO_ROOT_USER=${accessKey}`,
+        "-e",
+        `MINIO_ROOT_PASSWORD=${secretKey}`,
+        "-e",
+        `MINIO_SERVER_URL=${minioEndpoint}`,
+        MINIO_IMAGE,
+        "server",
+        "/data",
+        "--console-address",
+        ":9001"
+    );
+
+    console.log(`[INFO] initialising MinIO test bucket: ${bucket}`);
+    let initialised = false;
+    for (let i = 0; i < 5; i++) {
+        if (await initMinioBucket(minioEndpoint, accessKey, secretKey, bucket)) {
+            initialised = true;
+            break;
+        }
+        await sleep(2000);
+    }
+    if (!initialised) {
+        throw new Error(`Could not initialise MinIO bucket after retries: ${bucket}`);
+    }
+
+    await waitForMinioBucket(minioEndpoint, accessKey, secretKey, bucket);
+}
+
+// ---------------------------------------------------------------------------
+// P2P relay (strfry)
+// ---------------------------------------------------------------------------
+// TODO: these values could be configurable via environment variables.
+const P2P_RELAY_CONTAINER = "relay-test";
+const P2P_RELAY_IMAGE = "ghcr.io/hoytech/strfry:latest";
+const STRFRY_BOOTSTRAP_SH = String.raw`cat > /tmp/strfry.conf <<"EOF"
+db = "./strfry-db/"
+
+relay {
+  bind = "0.0.0.0"
+  port = 7777
+  nofiles = 100000
+
+  info {
+    name = "livesync test relay"
+    description = "local relay for livesync p2p tests"
+  }
+
+  maxWebsocketPayloadSize = 131072
+  autoPingSeconds = 55
+
+  writePolicy {
+    plugin = ""
+  }
+}
+EOF
+exec /app/strfry --config /tmp/strfry.conf relay`;
+
+export async function stopP2pRelay(): Promise<void> {
+    await docker("stop", P2P_RELAY_CONTAINER);
+    await docker("rm", P2P_RELAY_CONTAINER);
+}
+
+/**
+ * Start the local P2P relay container through the same docker runner used
+ * by CouchDB helpers. This keeps process ownership consistent across
+ * start/stop on Windows, WSL, and native Linux/macOS.
+ */
+export async function startP2pRelay(): Promise<void> {
+    console.log("[INFO] stopping leftover P2P relay container if present");
+    await stopP2pRelay().catch(() => {});
+
+    console.log("[INFO] starting local P2P relay container");
+    await dockerOrFail(
+        "run",
+        "-d",
+        "--name",
+        P2P_RELAY_CONTAINER,
+        "-p",
+        //TODO: port mapping should be configurable.
+        "4000:7777",
+        "--tmpfs",
+        "/app/strfry-db:rw,size=256m",
+        "--entrypoint",
+        "sh",
+        P2P_RELAY_IMAGE,
+        "-lc",
+        STRFRY_BOOTSTRAP_SH
+    );
+}
+
+export function isLocalP2pRelay(relayUrl: string): boolean {
+    return relayUrl === "ws://localhost:4000" || relayUrl === "ws://localhost:4000/";
+}

src/apps/cli/testdeno/helpers/env.ts

@@ -0,0 +1,26 @@
+/**
+ * Load a .env-style file (KEY=value per line) into a plain object.
+ * Equivalent to `source $TEST_ENV_FILE; set -a` in bash.
+ * Maybe we should use some library... now it is just the minimal implementation that covers our use cases.
+ *
+ * Supported value formats:
+ *   KEY=value
+ *   KEY='single quoted'
+ *   KEY="double quoted"
+ *   # comment lines are ignored
+  */
+export async function loadEnvFile(filePath: string): Promise<Record<string, string>> {
+    const text = await Deno.readTextFile(filePath);
+    const result: Record<string, string> = {};
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) continue;
+        const idx = trimmed.indexOf("=");
+        if (idx < 0) continue;
+        const key = trimmed.slice(0, idx).trim();
+        const raw = trimmed.slice(idx + 1).trim();
+        // Strip surrounding single or double quotes
+        result[key] = raw.replace(/^(['"])(.*)\1$/, "$2");
+    }
+    return result;
+}

src/apps/cli/testdeno/helpers/p2p.ts

@@ -0,0 +1,52 @@
+import { runCli } from "./cli.ts";
+import { isLocalP2pRelay, startP2pRelay, stopP2pRelay } from "./docker.ts";
+
+export type PeerEntry = {
+    id: string;
+    name: string;
+};
+
+export function parsePeerLines(output: string): PeerEntry[] {
+    return output
+        .split(/\r?\n/)
+        .map((line) => line.split("\t"))
+        .filter((parts) => parts.length >= 3 && parts[0] === "[peer]")
+        .map((parts) => ({ id: parts[1], name: parts[2] }));
+}
+
+export async function discoverPeer(
+    vaultDir: string,
+    settingsFile: string,
+    timeoutSeconds: number,
+    targetPeer?: string
+): Promise<PeerEntry> {
+    const result = await runCli(vaultDir, "--settings", settingsFile, "p2p-peers", String(timeoutSeconds));
+    if (result.code !== 0) {
+        throw new Error(`p2p-peers failed\n${result.combined}`);
+    }
+    const peers = parsePeerLines(result.stdout);
+    if (targetPeer) {
+        const matched = peers.find((peer) => peer.id === targetPeer || peer.name === targetPeer);
+        if (matched) return matched;
+    }
+    if (peers.length === 0) {
+        const fallback = result.combined.match(/Advertisement from\s+([^\s]+)/);
+        if (fallback?.[1]) {
+            return { id: fallback[1], name: fallback[1] };
+        }
+        throw new Error(`No peers discovered\n${result.combined}`);
+    }
+    return peers[0];
+}
+
+export async function maybeStartLocalRelay(relay: string): Promise<boolean> {
+    if (!isLocalP2pRelay(relay)) return false;
+    await startP2pRelay();
+    return true;
+}
+
+export async function stopLocalRelayIfStarted(started: boolean): Promise<void> {
+    if (started) {
+        await stopP2pRelay().catch(() => {});
+    }
+}

src/apps/cli/testdeno/helpers/settings.ts

@@ -0,0 +1,205 @@
+import { join } from "@std/path";
+import { CLI_DIR, runCliOrFail } from "./cli.ts";
+
+// ---------------------------------------------------------------------------
+// Settings file initialisation
+// ---------------------------------------------------------------------------
+
+/** Generate a default settings file using the CLI's init-settings command. */
+export async function initSettingsFile(settingsFile: string): Promise<void> {
+    await runCliOrFail("init-settings", "--force", settingsFile);
+}
+
+/**
+ * Generate a full setup URI from a settings file via src/lib API.
+ * Mirrors the bash flow in test-setup-put-cat-linux.sh.
+ */
+export async function generateSetupUriFromSettings(settingsFile: string, setupPassphrase: string): Promise<string> {
+    const repoRoot = join(CLI_DIR, "..", "..", "..");
+    const script = [
+        "import fs from 'node:fs';",
+        "import { pathToFileURL } from 'node:url';",
+        "(async () => {",
+        "  const modulePath = process.env.REPO_ROOT + '/src/lib/src/API/processSetting.ts';",
+        "  const moduleUrl = pathToFileURL(modulePath).href;",
+        "  const { encodeSettingsToSetupURI } = await import(moduleUrl);",
+        "  const settingsPath = process.env.SETTINGS_FILE;",
+        "  const passphrase = process.env.SETUP_PASSPHRASE;",
+        "  const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));",
+        "  settings.couchDB_DBNAME = 'setup-put-cat-db';",
+        "  settings.couchDB_URI = 'http://127.0.0.1:5999';",
+        "  settings.couchDB_USER = 'dummy';",
+        "  settings.couchDB_PASSWORD = 'dummy';",
+        "  settings.liveSync = false;",
+        "  settings.syncOnStart = false;",
+        "  settings.syncOnSave = false;",
+        "  const uri = await encodeSettingsToSetupURI(settings, passphrase);",
+        "  process.stdout.write(uri.trim());",
+        "})();",
+    ].join("\n");
+
+    const scriptPath = await Deno.makeTempFile({
+        prefix: "livesync-setup-uri-",
+        suffix: ".mts",
+    });
+    await Deno.writeTextFile(scriptPath, script);
+
+    try {
+        const cmd = new Deno.Command("npx", {
+            args: ["tsx", scriptPath],
+            cwd: CLI_DIR,
+            env: {
+                REPO_ROOT: repoRoot,
+                SETTINGS_FILE: settingsFile,
+                SETUP_PASSPHRASE: setupPassphrase,
+            },
+            stdin: "null",
+            stdout: "piped",
+            stderr: "piped",
+        });
+
+        const { code, stdout, stderr } = await cmd.output();
+        const dec = new TextDecoder();
+        if (code !== 0) {
+            throw new Error(
+                `Failed to generate setup URI (code ${code})\nstdout: ${dec.decode(stdout)}\nstderr: ${dec.decode(stderr)}`
+            );
+        }
+
+        const uri = dec.decode(stdout).trim();
+        if (!uri) {
+            throw new Error("Failed to generate setup URI: output is empty");
+        }
+        return uri;
+    } finally {
+        await Deno.remove(scriptPath).catch(() => {});
+    }
+}
+
+/** Set isConfigured=true in a settings file (required for mirror / scan). */
+export async function markSettingsConfigured(settingsFile: string): Promise<void> {
+    const data = JSON.parse(await Deno.readTextFile(settingsFile));
+    data.isConfigured = true;
+    await Deno.writeTextFile(settingsFile, JSON.stringify(data, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// CouchDB remote settings
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply CouchDB connection details to a settings file.
+ * Mirrors cli_test_apply_couchdb_settings() from test-helpers.sh.
+ */
+export async function applyCouchdbSettings(
+    settingsFile: string,
+    couchdbUri: string,
+    couchdbUser: string,
+    couchdbPassword: string,
+    couchdbDbname: string,
+    liveSync = false
+): Promise<void> {
+    const data = JSON.parse(await Deno.readTextFile(settingsFile));
+    data.couchDB_URI = couchdbUri;
+    data.couchDB_USER = couchdbUser;
+    data.couchDB_PASSWORD = couchdbPassword;
+    data.couchDB_DBNAME = couchdbDbname;
+    if (liveSync) {
+        data.liveSync = true;
+        data.syncOnStart = false;
+        data.syncOnSave = false;
+        data.usePluginSync = false;
+    }
+    data.isConfigured = true;
+    await Deno.writeTextFile(settingsFile, JSON.stringify(data, null, 2));
+}
+
+export async function applyRemoteSyncSettings(
+    settingsFile: string,
+    options: {
+        remoteType: "COUCHDB" | "MINIO";
+        couchdbUri?: string;
+        couchdbUser?: string;
+        couchdbPassword?: string;
+        couchdbDbname?: string;
+        minioBucket?: string;
+        minioEndpoint?: string;
+        minioAccessKey?: string;
+        minioSecretKey?: string;
+        encrypt?: boolean;
+        passphrase?: string;
+    }
+): Promise<void> {
+    const data = JSON.parse(await Deno.readTextFile(settingsFile));
+
+    if (options.remoteType === "COUCHDB") {
+        data.remoteType = "";
+        data.couchDB_URI = options.couchdbUri;
+        data.couchDB_USER = options.couchdbUser;
+        data.couchDB_PASSWORD = options.couchdbPassword;
+        data.couchDB_DBNAME = options.couchdbDbname;
+    } else {
+        data.remoteType = "MINIO";
+        data.bucket = options.minioBucket;
+        data.endpoint = options.minioEndpoint;
+        data.accessKey = options.minioAccessKey;
+        data.secretKey = options.minioSecretKey;
+        data.region = "auto";
+        data.forcePathStyle = true;
+    }
+
+    data.liveSync = true;
+    data.syncOnStart = false;
+    data.syncOnSave = false;
+    data.usePluginSync = false;
+    data.encrypt = options.encrypt === true;
+    data.passphrase = options.encrypt ? (options.passphrase ?? "") : "";
+    data.isConfigured = true;
+    await Deno.writeTextFile(settingsFile, JSON.stringify(data, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// P2P settings
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply P2P connection details to a settings file.
+ * Mirrors cli_test_apply_p2p_settings() from test-helpers.sh.
+ */
+export async function applyP2pSettings(
+    settingsFile: string,
+    roomId: string,
+    passphrase: string,
+    appId = "self-hosted-livesync-cli-tests",
+    relays = "ws://localhost:4000/",
+    autoAccept = "~.*"
+): Promise<void> {
+    const data = JSON.parse(await Deno.readTextFile(settingsFile));
+    data.P2P_Enabled = true;
+    data.P2P_AutoStart = false;
+    data.P2P_AutoBroadcast = false;
+    data.P2P_AppID = appId;
+    data.P2P_roomID = roomId;
+    data.P2P_passphrase = passphrase;
+    data.P2P_relays = relays;
+    data.P2P_AutoAcceptingPeers = autoAccept;
+    data.P2P_AutoDenyingPeers = "";
+    data.P2P_IsHeadless = true;
+    data.isConfigured = true;
+    await Deno.writeTextFile(settingsFile, JSON.stringify(data, null, 2));
+}
+
+export async function applyP2pTestTweaks(settingsFile: string, deviceName: string, passphrase: string): Promise<void> {
+    const data = JSON.parse(await Deno.readTextFile(settingsFile));
+    data.remoteType = "ONLY_P2P";
+    data.encrypt = true;
+    data.passphrase = passphrase;
+    data.usePathObfuscation = true;
+    data.handleFilenameCaseSensitive = false;
+    data.customChunkSize = 50;
+    data.usePluginSyncV2 = true;
+    data.doNotUseFixedRevisionForChunks = false;
+    data.P2P_DevicePeerName = deviceName;
+    data.isConfigured = true;
+    await Deno.writeTextFile(settingsFile, JSON.stringify(data, null, 2));
+}

src/apps/cli/testdeno/helpers/temp.ts

@@ -0,0 +1,33 @@
+import { join } from "@std/path";
+
+/**
+ * A temporary directory that cleans itself up via `await using`.
+ * Requires TypeScript 5.2+ / Deno 1.40+ for the AsyncDisposable protocol.
+ *
+ * @example
+ * ```ts
+ * await using tmp = await TempDir.create();
+ * const file = tmp.join("data.json");
+ * ```
+ */
+export class TempDir implements AsyncDisposable {
+    readonly path: string;
+
+    private constructor(path: string) {
+        this.path = path;
+    }
+
+    static async create(prefix = "livesync-deno-test"): Promise<TempDir> {
+        const path = await Deno.makeTempDir({ prefix: `${prefix}.` });
+        return new TempDir(path);
+    }
+
+    /** Return an OS path joined to the temp directory root. */
+    join(...parts: string[]): string {
+        return join(this.path, ...parts);
+    }
+
+    async [Symbol.asyncDispose](): Promise<void> {
+        await Deno.remove(this.path, { recursive: true }).catch(() => {});
+    }
+}