# Protocol Probe Tool Design

**Date:** 2026-06-11
**Status:** Design proposal
**TODO:** TODO-047
**Requirements:** SysRS-128, SRS-123
**Effort:** L

## Purpose

Connect to a TeamSpeak 3-compatible server and enumerate its capabilities. Validates server compatibility, reports supported features, permissions, and protocol behavior for verification and compatibility tracking.

## Inputs

- Server address (host:port)
- Optional: nickname, identity, server password

## Outputs

- Server info: version, platform, name, welcome message
- Supported features: text messaging, voice, file transfer, channel permissions
- Client permissions: talk power, poke power, channel join capabilities
- Protocol compatibility report: pass/fail/warning per feature
- Error codes encountered during probing

## Architecture

```text
┌──────────┐     ┌───────────────┐     ┌──────────────────┐
│ CLI      │────>│ Probe Session │────>│ tsclientlib      │
│ (host,   │     │ (chanora_     │     │ Protocol Adapter │
│  port)   │     │  protocol)    │     │                  │
└──────────┘     └───────┬───────┘     └──────────────────┘
                         │
              ┌──────────v──────────┐
              │ Probe Commands:     │
              │  1. connect         │
              │  2. server info     │
              │  3. channel list    │
              │  4. client list     │
              │  5. send test msg   │
              │  6. voice capability│
              │  7. permissions     │
              └──────────┬──────────┘
                         │
              ┌──────────v──────────┐
              │ Compatibility      │
              │ Report (JSON/text) │
              └────────────────────┘
```

1. **Connect:** Establish session via `chanora_protocol` adapter
2. **Query:** Execute probe commands sequentially with timeout
3. **Collect:** Gather responses, errors, and timing for each probe
4. **Report:** Output structured compatibility report

## Implementation Plan

- New Rust binary crate: `tools/protocol-probe/`
- Reuse `chanora_protocol::adapter` for tsclientlib connection
- Probe sequence: connect → server info → channels → clients → text test → voice check → permissions
- Each probe step has independent timeout (5s default)
- CLI interface: `protocol-probe <host[:port]> [--nick probe-bot] [--password <pw>] [--output json|text]`
- JSON output for CI integration; text output for human readability

## Dependencies

- `chanora_protocol` (adapter, tsclientlib wrapper)
- `chanora_core` (connection manager, event types)
- `serde_json` (report output)
- `clap` (CLI argument parsing)

## Verification

- Unit test: mock protocol responses, verify report generation
- Integration test: probe local test server, verify all features detected
- Demo: probe public TeamSpeak server, show compatibility report
- CI: run against test server in CI environment, assert pass on required features