Retire legacy sources and verify managed iOS deployment
This commit is contained in:
@@ -1,115 +1,54 @@
|
||||
# AGENTS.md — working method
|
||||
# VoiceCat working method
|
||||
|
||||
This file is the **working method** for a developer or AI agent picking up VoiceCat. Companion
|
||||
files:
|
||||
Start with `CLAUDE.md` for commands and architecture and `PROGRESS.md` for the current handoff.
|
||||
The supported product is the .NET 10 implementation. Old C++ and Swift application code is
|
||||
retirement material, not a source of truth.
|
||||
|
||||
- [`CLAUDE.md`](CLAUDE.md) — the hub: build/test commands, architecture at a glance, doc map.
|
||||
- [`PROGRESS.md`](PROGRESS.md) — living tracker: what's done, what's next. **Update it as you work.**
|
||||
- [`docs/`](docs/) — the **source of truth** for all design.
|
||||
## Definition of done
|
||||
|
||||
Read those, then use the method below.
|
||||
A clean compile is the floor. Changes are done when their observable behavior is covered by a
|
||||
test or, for hardware/accessibility/release behavior, by a clearly recorded manual gate.
|
||||
|
||||
## What this repo is right now
|
||||
For implementation work:
|
||||
|
||||
A complete **design** ([`docs/`](docs/)) plus a working implementation through M5: real TLS
|
||||
control plane, encrypted UDP voice (Opus), multi-stream, TOFU identity pinning, channel tree,
|
||||
permissions, moderation, disconnect/keepalive/reaper. The Windows WinForms C# client is
|
||||
shipped (M4). The macOS/iOS Swift client is next. The `skeleton` preset still links a
|
||||
no-deps stub path (`VC_ERR_NOT_IMPLEMENTED`) for smoke-check builds.
|
||||
1. Read the relevant code and current contract document.
|
||||
2. Add or adjust the smallest behavior test that demonstrates the requested result.
|
||||
3. Implement the change without weakening encryption, real-time safety, or accessibility.
|
||||
4. Build and run the affected tests, then the full managed test suite when practical.
|
||||
5. Update concise current documentation and `PROGRESS.md` if the handoff changed.
|
||||
|
||||
## The working method (important)
|
||||
## Supported layout
|
||||
|
||||
**A clean compile is the floor, not the goal.** Do not treat "make the compiler errors go
|
||||
away" as done. Each milestone in [`docs/roadmap.md`](docs/roadmap.md) has an **exit
|
||||
criterion stated as observable behavior** — that is what "done" means. Examples:
|
||||
| Path | Purpose |
|
||||
|---|---|
|
||||
| `proto/voicecat.proto` | Control-plane wire schema |
|
||||
| `dotnet/src/` | Managed server, core, protocol, crypto, audio, codec/DSP, and CLI |
|
||||
| `dotnet/tests/VoiceCat.Tests/` | Managed behavior tests |
|
||||
| `clients/windows/` | Supported WinForms client |
|
||||
| `clients/apple/dotnet/` | Supported AppKit and UIKit clients |
|
||||
| `native/media/` | Required narrow Opus/RNNoise C ABI |
|
||||
| `native/rnnoise/` | Vendored RNNoise source/model |
|
||||
| `native/apple/broadcast/` | Required ReplayKit extension and shared-memory producer |
|
||||
|
||||
- M1 done = *two `vccli` instances actually chat through a real server over TLS*, not "it builds".
|
||||
- M2 done = *you can talk between two clients in a channel and hear loss concealment work*.
|
||||
|
||||
So the loop is:
|
||||
|
||||
1. Pick the current milestone in `docs/roadmap.md`. Read the relevant design doc section.
|
||||
2. Write the smallest test (CTest, or a `vccli` interaction) that encodes the exit behavior.
|
||||
3. Implement the subsystem until that test passes — not just until it compiles.
|
||||
4. Keep the build green and the existing tests passing on every commit.
|
||||
|
||||
Every commit must compile and pass `ctest`. Behavior tests are how you know you're actually
|
||||
making progress.
|
||||
|
||||
## Build
|
||||
|
||||
Default development preset (real deps via vcpkg — works on Windows/Linux/macOS). vcpkg is
|
||||
bundled as a git submodule at `vcpkg/`, pinned to `vcpkg.json`'s `builtin-baseline`:
|
||||
## Core verification
|
||||
|
||||
```bash
|
||||
git submodule update --init vcpkg # one-time, after cloning
|
||||
./vcpkg/bootstrap-vcpkg.sh # .bat on Windows
|
||||
cmake --preset dev
|
||||
cmake --build --preset dev
|
||||
ctest --preset dev
|
||||
./dotnet/build-native.ps1
|
||||
dotnet restore dotnet/VoiceCat.slnx --locked-mode
|
||||
dotnet build dotnet/VoiceCat.slnx -c Release --no-restore
|
||||
dotnet test dotnet/VoiceCat.slnx -c Release --no-build
|
||||
./dotnet/check-licenses.ps1
|
||||
```
|
||||
|
||||
To use an external vcpkg checkout instead, `export VCPKG_ROOT=/path/to/vcpkg` — it always
|
||||
takes priority over the bundled submodule.
|
||||
Apple builds additionally use `./dotnet/build-native-ios.sh` and
|
||||
`clients/apple/dotnet/VoiceCat.Apple.slnx` on macOS.
|
||||
|
||||
Skeleton (no third-party deps — works immediately, no vcpkg needed):
|
||||
## Hard rules
|
||||
|
||||
```bash
|
||||
cmake --preset skeleton
|
||||
cmake --build --preset skeleton
|
||||
ctest --preset skeleton
|
||||
```
|
||||
|
||||
> **Windows gotcha — always run `ctest` and built binaries via PowerShell, not Git Bash.**
|
||||
> MinGW-built executables fail in Git Bash with exit code `0xc0000139`
|
||||
> (STATUS_ENTRYPOINT_NOT_FOUND) even though the file exists and is marked executable.
|
||||
> PowerShell runs them correctly. Use the PowerShell tool (not Bash) for any `ctest`,
|
||||
> `voicecat-server.exe`, or `vccli.exe` invocation on Windows.
|
||||
|
||||
Other presets: `release` (optimized + tests), `server-release` (optimized + stripped,
|
||||
deployment-shaped), `windows-client` (DLL for C# app), `apple-dev`/`apple-ios`/
|
||||
`apple-ios-sim` (Apple platform scaffolding). See [`docs/building.md`](docs/building.md)
|
||||
for the full matrix.
|
||||
|
||||
`vcpkg.json` pins all deps to a fixed vcpkg baseline — `cmake --preset dev` resolves them
|
||||
automatically on first configure. The vcpkg triplet is auto-resolved from the host platform
|
||||
by [`cmake/voicecat-toolchain.cmake`](cmake/voicecat-toolchain.cmake), which also resolves
|
||||
`VCPKG_ROOT` (env var override, else the bundled `vcpkg/` submodule).
|
||||
|
||||
## Where each subsystem lives (and its doc)
|
||||
|
||||
| Path | Subsystem | Design |
|
||||
|------|-----------|--------|
|
||||
| `core/include/voicecat.h` | The C ABI every client/server calls | docs/architecture.md §4 |
|
||||
| `core/proto/voicecat.proto` | Control-plane wire format | docs/protocol.md |
|
||||
| `core/src/net/` | Asio TCP/UDP transport, framing | docs/architecture.md, docs/protocol.md §1 |
|
||||
| `core/src/crypto/` | TLS 1.3 (mbedTLS), media AEAD (libsodium), anti-replay | docs/security.md |
|
||||
| `core/src/codec/` | Opus encode/decode, FEC/DTX | docs/voice.md §3–4 |
|
||||
| `core/src/protocol/` | Envelope (de)serialize, state machine, routing | docs/protocol.md |
|
||||
| `core/src/session/` | Channels, users, streams, permissions, text | docs/protocol.md §5 |
|
||||
| `core/src/audio/` | Capture/playback (miniaudio), APM DSP, jitter buffer, mixer | docs/voice.md §8–11 |
|
||||
| `server/` | Connection mgr, session registry, SFU relay, SQLite | docs/architecture.md §5 |
|
||||
| `tools/vccli/` | Headless client to drive/verify the protocol | — |
|
||||
|
||||
## Suggested first steps (M1 spine)
|
||||
|
||||
1. **Wire protobuf + framing** (`net/` + `protocol/`): build, then generate C++ from
|
||||
`voicecat.proto`, implement the `[u32 length][Envelope]` framing over a plain TCP socket
|
||||
(TLS can come right after). Test: round-trip an `Envelope` through the framer.
|
||||
2. **TLS 1.3 via mbedTLS** (`crypto/`): wrap the TCP channel. Test: `vccli` completes a TLS
|
||||
handshake against `voicecat-server` and exchanges a `ClientHello`/`ServerHello`.
|
||||
3. **Auth + state** (`session/`): guest + admin-provisioned accounts (Argon2id/SQLite),
|
||||
channel tree snapshot/deltas, ephemeral text relay. Test: two `vccli` chat.
|
||||
|
||||
Then proceed to M2 (UDP media) per the roadmap.
|
||||
|
||||
## House rules
|
||||
|
||||
- **No GPL/LGPL dependencies, ever** (closed-source redistribution is a goal). See
|
||||
docs/tech-stack.md §5. CI should fail on a copyleft transitive dep.
|
||||
- **Encryption is mandatory** — never add a plaintext transport path. docs/security.md.
|
||||
- **Real-time audio threads** never allocate, lock, or block. docs/architecture.md §3.
|
||||
- Keep `docs/` and code in sync. If you change a wire format or the C ABI, update the doc in
|
||||
the same commit.
|
||||
- The C ABI is the contract for the Swift/C# clients — treat changes to `voicecat.h` and
|
||||
`voicecat.proto` as deliberate, versioned events (docs/protocol.md §8).
|
||||
- Encryption is mandatory: TLS control plus authenticated encrypted UDP media.
|
||||
- Never introduce GPL/LGPL dependencies.
|
||||
- Real-time audio callbacks never allocate, lock, block, or perform I/O.
|
||||
- Preserve accessible names, keyboard operation, and curated screen-reader announcements.
|
||||
- Wire, database, and shared-ring changes are deliberate versioned changes.
|
||||
- Do not restore compatibility tests for retired implementations unless explicitly requested.
|
||||
- Keep `PROGRESS.md` short. Use Git history rather than accumulating completed-work prose.
|
||||
|
||||
Reference in New Issue
Block a user