obsidian-livesync/src/apps/cli/testdeno/test_dev_deno.md

# CLI Deno Test Development Notes

This document provides an overview of the Deno-based compatibility tests under `src/apps/cli/testdeno/`.
The existing bash tests under `src/apps/cli/test/` are preserved, while a Windows-friendly suite is maintained in parallel.

---

## Goals

- Keep existing bash tests intact.
- Provide direct execution from Windows PowerShell.
- Establish a TypeScript (Deno) foundation for core end-to-end and integration scenarios.

---

## Directory structure

```
src/apps/cli/testdeno/
  deno.json
  CONTRIBUTING_TESTS.md
  helpers/
    backgroundCli.ts
    cli.ts
    docker.ts
    env.ts
    p2p.ts
    settings.ts
    temp.ts
  test-e2e-two-vaults-couchdb.ts
  test-push-pull.ts
  test-p2p-host.ts
  test-p2p-peers-local-relay.ts
  test-p2p-sync.ts
  test-p2p-three-nodes-conflict.ts
  test-p2p-upload-download-repro.ts
  test-e2e-two-vaults-matrix.ts
  test-setup-put-cat.ts
  test-mirror.ts
  test-sync-two-local-databases.ts
  test-sync-locked-remote.ts
  test-daemon.ts
  test-decoupled-vault.ts
  test-remote-commands.ts
```

---

## Key files

### `deno.json`

- Defines Deno tasks.
- Defines import maps for `@std/assert` and `@std/path`.

Main tasks:

- `deno task test`
- `deno task test:local`
- `deno task test:daemon`
- `deno task test:decoupled-vault`
- `deno task test:remote-commands`
- `deno task test:push-pull`
- `deno task test:setup-put-cat`
- `deno task test:mirror`
- `deno task test:sync-two-local`
- `deno task test:sync-locked-remote`
- `deno task test:p2p-host`
- `deno task test:p2p-peers`
- `deno task test:p2p-sync`
- `deno task test:p2p-three-nodes`
- `deno task test:p2p-upload-download`
- `deno task test:e2e-couchdb`
- `deno task test:e2e-matrix`

### `helpers/cli.ts`

- CLI execution wrappers.
- `runCli`, `runCliOrFail`, `runCliWithInput`.
- Output normalisation via `sanitiseCatStdout`.
- Comparison utilities, including `assertFilesEqual`.

This file corresponds to `run_cli` and common assertions in `test-helpers.sh`.

### `helpers/settings.ts`

- Executes `init-settings --force`.
- Marks `isConfigured = true`.
- Applies CouchDB and P2P settings.
- Applies remote synchronisation settings and P2P test tweaks.

This file corresponds to settings helpers in `test-helpers.sh`.

### `helpers/docker.ts`

- Starts, stops, and initialises CouchDB directly from Deno.
- Configures CouchDB via `fetch + retry`.
- Starts and stops the P2P relay through the same Docker runner.

Both CouchDB and P2P relay flows are bash-independent.

### `helpers/backgroundCli.ts`

- Starts long-running commands such as `p2p-host` in the background.
- Waits for readiness logs and handles termination.

### `helpers/p2p.ts`

- Determines whether a local relay should be started.
- Parses `p2p-peers` output.
- Discovers peer IDs with a fallback based on advertisement logs.

### `helpers/env.ts`

- Loads `.test.env`.
- Supports `KEY=value`, single-quoted values, and double-quoted values.

### `helpers/temp.ts`

- Provides `TempDir`.
- Uses `await using` to auto-clean temporary directories.

---

## Implemented tests

### `test-push-pull.ts`

- Verifies push and pull round trips.
- Uses environment variables or `.test.env` for CouchDB values.

### `test-setup-put-cat.ts`

- Verifies `setup` with full setup URI generation via `encodeSettingsToSetupURI`.
- Verifies `push`, `cat`, `ls`, `info`, `rm`, `resolve`, `cat-rev`, and `pull-rev`.
- Does not require an external remote.

### `test-mirror.ts`

- Verifies six core mirror scenarios.
- Does not require an external remote.

### `test-sync-two-local-databases.ts`

- Verifies sync between two vaults and CouchDB.
- Verifies conflict detection and resolve propagation.
- Starts Docker CouchDB by default when `LIVESYNC_START_DOCKER != 0`.

### `test-sync-locked-remote.ts`

- Updates the CouchDB milestone `locked` flag.
- Verifies sync success when unlocked.
- Verifies actionable CLI error when locked.

### `test-p2p-host.ts`

- Verifies that `p2p-host` starts and emits readiness output.

### `test-p2p-peers-local-relay.ts`

- Verifies peer discovery through a local relay.

### `test-p2p-sync.ts`

- Verifies that `p2p-sync` completes after peer discovery.

### `test-p2p-three-nodes-conflict.ts`

- Uses one host and two clients.
- Verifies conflict creation, detection via `info`, and resolution via `resolve`.

### `test-p2p-upload-download-repro.ts`

- Uses host, upload, and download nodes.
- Verifies transfer of text files and binary files, including larger files.

### `test-e2e-two-vaults-couchdb.ts`

- Verifies two-vault end-to-end scenarios on CouchDB.
- Runs both encryption-off and encryption-on cases.
- Includes conflict marker checks in `ls` and resolve propagation checks.

### `test-e2e-two-vaults-matrix.ts`

- Verifies the matrix equivalent of the bash script.
- Runs four combinations:
  - `COUCHDB-enc0`
  - `COUCHDB-enc1`
  - `MINIO-enc0`
  - `MINIO-enc1`

### `test-daemon.ts`

- Verifies daemon-related ignore rules behaviour.
- Exercises scenarios with `.livesync/ignore` wildcard rules, missing ignore rules, and imported `.gitignore` rules.

### `test-decoupled-vault.ts`

- Verifies push, pull, and mirror command behaviour when the vault directory is decoupled from the database directory.

### `test-remote-commands.ts`

- Verifies remote database management commands: `remote-status`, `lock-remote`, `unlock-remote`, and `mark-resolved`.

---

## Running tests (PowerShell)

From `src/apps/cli/testdeno`:

```powershell
cd src/apps/cli/testdeno

# Local-only set
deno task test:local

# Individual tests
deno task test:setup-put-cat
deno task test:mirror
deno task test:daemon
deno task test:push-pull
deno task test:sync-locked-remote

# CouchDB-based tests
deno task test:sync-two-local
deno task test:decoupled-vault
deno task test:remote-commands
deno task test:e2e-couchdb

# P2P-based tests
deno task test:p2p-host
deno task test:p2p-peers
deno task test:p2p-sync
deno task test:p2p-three-nodes
deno task test:p2p-upload-download
deno task test:e2e-matrix
```

---

## Environment variables

### CouchDB

- `COUCHDB_URI`
- `COUCHDB_USER`
- `COUCHDB_PASSWORD`
- `COUCHDB_DBNAME`

Equivalent keys in `src/apps/cli/.test.env`:

- `hostname`
- `username`
- `password`
- `dbname`

### Behaviour switches

- `LIVESYNC_START_DOCKER=0`: use existing CouchDB.
- `REMOTE_PATH`: override target path for selected tests.
- `LIVESYNC_TEST_TEE=1`: stream CLI stdout and stderr during execution.
- `LIVESYNC_DOCKER_TEE=1`: stream Docker stdout and stderr.
- `LIVESYNC_CLI_RETRY=<n>`: retry transient network failures.
- `LIVESYNC_DEBUG_KEEP_DOCKER=1`: keep `couchdb-test` after test completion.

### Docker command selection

`helpers/docker.ts` supports command selection via environment variables.

- `LIVESYNC_DOCKER_MODE=auto` (default)
  - Windows: tries `wsl docker` first, then `docker`.
  - Non-Windows: tries `docker` first, then `wsl docker`.
- `LIVESYNC_DOCKER_MODE=native`: always uses `docker`.
- `LIVESYNC_DOCKER_MODE=wsl`: always uses `wsl docker`.
- `LIVESYNC_DOCKER_COMMAND="..."`: custom command, for example `wsl docker`.

`LIVESYNC_DOCKER_COMMAND` has priority over `LIVESYNC_DOCKER_MODE`.

PowerShell examples:

```powershell
# Use Docker in WSL explicitly
$env:LIVESYNC_DOCKER_MODE = "wsl"
deno task test:sync-two-local

# Full custom command
$env:LIVESYNC_DOCKER_COMMAND = "wsl docker"
deno task test:sync-two-local
```

### P2P

- `RELAY`
- `ROOM_ID`
- `PASSPHRASE`
- `APP_ID`
- `PEERS_TIMEOUT`
- `SYNC_TIMEOUT`
- `USE_INTERNAL_RELAY=0|1`
- `TIMEOUT_SECONDS`

---

## Continuous Integration

The GitHub Actions workflow `.github/workflows/cli-deno-tests.yml` runs automatically on pushes and pull requests affecting the CLI, executing the non-P2P test suite (`test:ci`). P2P tests (`test:p2p`) are excluded from automatic execution and must be run via manual dispatch (`workflow_dispatch`). You can optionally check the "Enable verbose and debug logging" checkbox during a manual dispatch to produce detailed trace logs for troubleshooting.

---

## Current limitations

- MinIO startup and matrix coverage are ported. Current limits are elsewhere, not setup URI generation.

---

## Maintenance policy

- Existing bash tests remain available.
- Deno tests are expanded in parallel for cross-platform usage.
- New scenarios should be added through reusable helpers in `helpers/`.