110 lines
4.4 KiB
Markdown
110 lines
4.4 KiB
Markdown
# Tasks: enterprise-browser-network-discovery-crdt
|
|
|
|
**Change ID**: enterprise-browser-network-discovery-crdt
|
|
**Package**: `@suaveplan/network-discovery-crdt`
|
|
**Target path**: `browser/network/network-discovery-crdt`
|
|
**Prerequisite packages on Verdaccio**: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/crypto`
|
|
|
|
---
|
|
|
|
## 1. Scaffold
|
|
|
|
- [x] Create directory tree per layout in `proposal.md`.
|
|
- [x] Write `package.json` at version `0.1.0` — `"sideEffects": false`, `strict: true` default.
|
|
- `dependencies`: `@suaveplan/network workspace:^`, `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/crypto workspace:^`, `yjs`, `y-webrtc`, all `@automerge/*` packages (Bun catalog), `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`
|
|
- `devDependencies`: `vitest catalog:testing`, `@vitest/coverage-istanbul catalog:testing`, `@suaveplan/testing workspace:^`, `react catalog:browser`, `@types/react catalog:browser`
|
|
- [x] Write `tsconfig.json` and `vitest.config.ts` (pool: forks).
|
|
|
|
---
|
|
|
|
## 2. Error codes
|
|
|
|
- [x] Define `CRDTErrorCode`: `CRDT_PROVIDER_UNAVAILABLE`, `CRDT_SIGNALING_FAILED`, `AWARENESS_REJECTED`.
|
|
- [x] Export `registerCRDTErrorCodes()` and call eagerly.
|
|
|
|
---
|
|
|
|
## 3. `CRDTProviderAdapter` interface (`src/provider/provider.ts`)
|
|
|
|
- [x] Define `CRDTProviderAdapter` interface with `init`, `destroy`, `getAwareness`, `setLocalAwareness`, `onAwarenessChange`.
|
|
- [x] Export `AwarenessChange` type.
|
|
|
|
---
|
|
|
|
## 4. Yjs provider (`src/provider/yjs/`)
|
|
|
|
- [x] Implement `YjsProvider implements CRDTProviderAdapter`:
|
|
- Strict-mode: reject if `signalingUrls` empty or contains known public URLs without `strict: false`.
|
|
- `yjs-awareness.ts`: awareness state helpers.
|
|
- `yjs-sync.ts`: Y.Doc sync utilities.
|
|
- [x] Write `yjs-provider.test.ts` using in-process signalling harness (no public URLs), `yjs-provider.md`.
|
|
|
|
---
|
|
|
|
## 5. Automerge provider (`src/provider/automerge/`)
|
|
|
|
- [x] Implement `AutomergeProvider implements CRDTProviderAdapter` using `@automerge/automerge-repo` with broadcast-channel + websocket adapters.
|
|
- [x] Write `automerge-provider.test.ts`, `automerge-provider.md`.
|
|
|
|
---
|
|
|
|
## 6. Awareness schema (`src/schema/awareness/`)
|
|
|
|
- [x] Define `CRDTPeerMetadataSchema` (Zod): `{ peerId: string, addresses: string[], protocols: string[], capabilities: string[], timestamp: number }`.
|
|
- [x] Register in `@suaveplan/schema-registry`.
|
|
- [x] Write `awareness.md`.
|
|
|
|
---
|
|
|
|
## 7. Manager modules
|
|
|
|
For each manager (`crdt-peer-manager`, `crdt-state-manager`, `crdt-initializer`, `crdt-intervals`):
|
|
|
|
- [x] Implement the manager.
|
|
- [x] Write `*.test.ts` and `*.md`.
|
|
|
|
---
|
|
|
|
## 8. CRDTDiscovery orchestrator (`src/crdt-discovery/`)
|
|
|
|
- [x] Implement `CRDTDiscovery` using `CRDTProviderAdapter` (no provider-string branching).
|
|
- [x] Optional encryption: if `config.encrypt`, wrap awareness payloads with `@suaveplan/crypto` AES-GCM.
|
|
- [x] Wire OTel metrics.
|
|
- [x] Write `crdt-discovery.test.ts` (Yjs + Automerge paths via their respective providers; in-process harness), `crdt-discovery.md`, `crdt-discovery.types.ts`.
|
|
|
|
---
|
|
|
|
## 9. Storybook story
|
|
|
|
- [x] Write `src/crdt-discovery/crdt-discovery.stories.tsx` with `react` in `devDependencies` — no missing dep.
|
|
- [x] Story demonstrates peer discovery with both providers.
|
|
|
|
---
|
|
|
|
## 10. Integration test (`tests/integration.test.ts`)
|
|
|
|
- [x] Two `CRDTDiscovery` instances with Yjs provider via in-process signalling; assert peer discovery event fires.
|
|
- [x] Automerge provider round-trip.
|
|
- [x] Awareness payload with malformed data rejected with `AWARENESS_REJECTED`.
|
|
- [x] Encryption: encrypted awareness payload cannot be read without the key.
|
|
|
|
---
|
|
|
|
## 11. Docs
|
|
|
|
- [x] Write `.md` per module (≥200 words, API reference, examples).
|
|
- [x] Write `README.md` with provider-adapter table, signalling self-hosting guidance, encryption opt-in.
|
|
|
|
---
|
|
|
|
## 12. Verify and publish
|
|
|
|
- [x] `bunx turbo lint typecheck test --filter=@suaveplan/network-discovery-crdt` — green.
|
|
- [x] `bunx turbo test:coverage --filter=@suaveplan/network-discovery-crdt` — 100%.
|
|
- [x] `bun run docs:check --filter=@suaveplan/network-discovery-crdt` — zero errors.
|
|
- [x] No `vi.mock`, `any`, `ts-ignore`, `.skip` in `src/`.
|
|
- [x] Story builds cleanly; React dep declared.
|
|
- [x] Awareness payload Zod schema registered.
|
|
- [x] `bun scripts/publish.ts --package @suaveplan/network-discovery-crdt`.
|
|
- [x] Archive to `openspec/archive/2026-04-24-enterprise-browser-network-discovery-crdt/`.
|