From 34f5bcb6b75567ab7c155374bb5cab9d1a6336dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A5vard=20Kittelsen?= Date: Wed, 19 Aug 2026 08:00:20 +0000 Subject: [PATCH] docs: correct the integration test path, note two things easy to get wrong --- CLAUDE.md | 18 ++++++++++++++++-- docs/transport.md | 8 +++++++- 2 files changed, 23 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 91033cc..28679ee 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,8 +21,12 @@ This codebase communicates over a live relay with timing-sensitive handshakes an **Integration tests** (`npm run test:integration` in a package): - Hit the real relays at `wss://relay.riften.net:443` and `wss://relay.cauldron.quest:443` - Test the full protocol handshake end-to-end -- Located in `src/__tests__/*.integration.test.ts` -- Run with generous timeouts (60s per test) via `vitest.integration.config.ts` +- Located in `src/integration/*.test.ts` (wallet is the only package with them today) +- Run with generous timeouts (60s per test) via `vitest.integration.config.ts`, serially + (`singleFork`) to avoid relay contention, and with `retry: 2` — these hit third-party + relays, so a dropped connection is an environment failure rather than a regression +- A failure that reproduces locally is real; one that does not is usually the relay. + Check whether the same test passed on an earlier pipeline before assuming a regression - Must pass before any release ### Running tests @@ -87,3 +91,13 @@ npm run build # builds all packages in dependency order ``` Packages must be built before integration tests run (tests import from `dist/`). + +## Releases + +The `publish` CI job runs on `master` only, via `contrib/auto-publish.js`. + +**The `version` in each `package.json` is a floor, not the shipped version** — all declare +`0.2.0` while npm carries higher patches. Use `npm view @wizardconnect/ version`. + +The lockfile is not published, so clearing a dependency advisory means bumping the declared +range in `package.json`, not just `package-lock.json`. diff --git a/docs/transport.md b/docs/transport.md index d4e110e..01e23da 100644 --- a/docs/transport.md +++ b/docs/transport.md @@ -50,10 +50,12 @@ connect(): Promise // NDK connect, subscribe to GiftWrap events, start waiting for relays. disconnect(): Promise - // Stop subscription, mark queue not-ready, update lastProcessedTimestamp. + // Stop subscription, close the relay pool, mark queue not-ready, update + // lastProcessedTimestamp. Kills any in-flight publish — see below. relay(message: ProtocolMessage): Promise // Send a message. Enqueues if relays not ready. Throws if paired key not set. + // Resolves only once the publish has settled against every configured relay. setPairedPublicKey(key: Uint8Array): void // Called after key exchange. Enables outbound messages and incoming peer filtering. @@ -78,6 +80,10 @@ regardless (avoiding silent message loss on slow connections). On `disconnect()`, the queue is marked not-ready so messages sent during a reconnect gap are held rather than dropped. +Because `disconnect()` closes the pool, it kills any publish still in flight — so anything +sending a final message before tearing down must await the `relay()` first. See +[wallet.md § Sending disconnect](wallet.md#sending-disconnect). + ### Replay protection `lastProcessedTimestamp` is set to `now - 2` on the first connection. On reconnect it is updated