peeroxide-cli 0.2.0: chat subsystem, init command, dd v2 tree protocol, progress UX

[eshork]

Summary

• Ships three big additions to peeroxide-cli: a peeroxide init bootstrap command, the dd v2 tree-indexed protocol rewrite (with progress UX), and the full chat subsystem (channels, DMs, inbox monitor, interactive TUI).
• Adds public DHT wire-byte counter accessors to peeroxide-dht 1.2.0 → 1.3.0 (additive only — no breaking changes).
• Extends the docs/ mdBook with new init/ and chat/ chapters and rewrites the dd/ chapter to cover both v1 and v2 protocols.

Motivation

The branch grew from three independent threads that share a common substrate (the existing peeroxide DHT primitives):

1. peeroxide init removes the "edit a TOML file by hand before anything works" papercut for new users and gives us a single entry point for both config bootstrap and man-page installation.
2. dd v2 addresses a structural ceiling in v1: the v1 chain was a sequential singly linked list, so a 1 GB payload required ~35,800 sequential mutable_get round trips on the critical path even though every chunk could otherwise be fetched in parallel. v2 turns the index layer into a canonical tree (O(log₃₁ N) round trips) and splits index (mutable) from data (immutable, content-addressed). On the publisher side, the rewrite also lands AIMD concurrency control, a stall watchdog, per-put timeouts, a sticky double-ctrl-c shutdown primitive, and a need-list mechanism that only advertises chunks the receiver actually tried and failed to fetch.
3. chat is a brand-new feature: anonymous, end-to-end-encrypted, verifiable group + DM chat built on the existing DHT primitives, with no protocol changes to peeroxide, no relay code, and no peer cooperation required. It ships with feed rotation, per-feed chain anchoring, ordering + dedup invariants, an inbox-monitor framework, a unified chat::session consumed by both chat join and chat dm, and a full interactive TUI with status bar, slash commands, history replay, and bracketed paste.

The dd progress UX work (bar / log / JSON / off, TTY-aware auto-selection) was added alongside the v2 rewrite so users finally have actionable feedback on large transfers and tools can integrate via JSON-Lines instead of parsing stderr.

Changes

peeroxide-cli

Area	Change
peeroxide init	New command (src/cmd/init.rs, ~489 LOC). Replaces and removes the old peeroxide config init subcommand (src/cmd/config.rs deleted; Commands::Config removed from main.rs). Two mutually-exclusive modes: config bootstrap (default) and man-page installation (--man-pages [PATH]). Config mode supports --force (overwrite), --update (patch network.public / network.bootstrap while preserving comments), and writes a fresh commented TOML. Man-page mode writes generated roff to PATH/man1/ and cleans stale peeroxide*.1 files.
peeroxide chat	New cmd/chat/ module tree (~35 source files). Subcommands: join, dm, inbox, whoami, profiles {list,create,delete}, friends {list,add,remove,refresh}, nexus. Full identity / profile / friend / known-users / nexus system. XSalsa20-Poly1305 + Ed25519 + BLAKE2b crypto. Per-session feed rotation with ±50% wobble, per-feed (id_pubkey, feed_pubkey) chain anchoring, ChainGate strict ordering with 5 s force-release, 1000-entry DedupRing, summary eviction on feed overflow (20→15 + walkback). Inbox monitor with parallel DHT scan (8 lookups + parallel mutable_gets per cycle, ~2-4 s wall-clock vs ~10-20 s in earlier nested-serial design). Shared chat::session consumed by join and dm; DM derives dm_channel_key and per-pair dm_msg_key via Ed25519→X25519 ECDH, sends per-epoch nudges, and best-effort retracts the invite on shutdown.
dd CLI	Renamed deaddrop → dd; leave/pickup → put/get. dd put dispatches on --v1 (default v2); dd get auto-dispatches on the root record's first byte (0x01→v1, 0x02→v2).
dd v2 protocol	Full rewrite as a tree-indexed protocol under wire byte 0x02. New module tree at cmd/deaddrop/v2/ (build, tree, wire, keys, queue, publish, fetch, need, stream). Canonical-shape index tree with 31-slot non-root nodes and a 30-slot root that carries file_size: u64 + crc32c: u32. Data chunks use immutable_put + a reserved per-deaddrop salt byte (currently fixed at 0x00); index nodes use mutable_put with deterministic per-index keypairs. Receiver does BFS fetch with PARALLEL_FETCH_CAP = 64, sliding-window --timeout, and an ephemeral need-feed announcing only attempted-and-failed positions on a 20 s cadence. Soft depth cap of 4 → 27.7M data chunks (~27 GB).
dd progress UX	New cmd/deaddrop/progress/ subsystem (state, format, rate, events, json, bar, log, mode, reporter). TTY-aware mode selection: --json > --no-progress > stderr-TTY → indicatif bar > periodic 2 s stderr log. Bar layouts: 2-bar (v1 put, v2 put) or 4-bar (v2 get) using indicatif::MultiProgress with a wire-rate / amplification line. JSON-Lines schema documented in docs/src/dd/operations.md (events: start, progress, result, ack, done).
dd put robustness	Shared sticky Shutdown primitive (first SIGINT/SIGTERM cancels gracefully; second exits 130). Per-put PUT_TIMEOUT = 30 s enforced in dispatcher. EWMA AIMD controller (α 0.1, decision interval 20, fast-trip threshold 10, shrink 0.75×, grow +2). Stall watchdog kicks concurrency off the floor every 5 s if 30 s pass with no successful put (rate-limited to once / 120 s).
dd put perf	Dedup'd ChunkId work queue with Lane::High priority for need-driven republishes. Interleaved index/data dispatch. Initial sender concurrency 128. Sliding-window get timeout.
Chat subsystem (part 2)	Publisher rewrite: single persistent worker drains a bounded mpsc(64), batches ≤ --batch-size (default 16) over a serial pipeline (join_all(immutable_put) → mutable_put with 200/500/1000 ms retries → announce). Replaces the per-message tokio::spawn race that previously advertised FeedRecords whose referenced immutables had not yet propagated. Stdin EOF triggers a banner-prefixed graceful drain by default; --stay-after-eof preserves the script-then-watch flow.
Chat subsystem (part 3)	Inbox monitor + INBOX status segment + /inbox slash command (shared between chat join and the chat inbox CLI; brief-lock concurrency, lock never held across .await). chat dm becomes a thin consumer of chat::session and gets the TUI / status bar / scroll history / inbox monitor / slash commands / all the same flags for free (join.rs goes from ~666 → ~141 LOC; the bulk of dm's command path now lives in dm_cmd.rs at ~145 LOC, with dm.rs reduced to a small helper shim). NameResolver extracted as canonical pubkey → display-name resolution (friend alias > known screen name > vendor fallback).
Interactive TUI	New cmd/chat/tui/ module (mod, status, commands, input, interactive, line, terminal). Auto-selection between interactive TUI (TTY stdin + stdout) and line mode (everything else). Pinned status bar with activity dot, sticky-width left segments, centered INBOX segment (yellow-on-black when unread > 0), and right-side Feeds / DHT / channel segments. Bounded 500-line in-memory scrollback ring replays through the scroll region on resize / Ctrl-L. Ctrl-C semantics: nonempty buffer clears, empty buffer arms a 2 s force-quit window with a transient overlay. Backpressured publisher sends are wrapped in a select! with ctrl_c so SIGINT stays responsive even mid-batch. RAII TerminalGuard restores raw mode / bracketed paste / cursor / colors / scroll region on every exit path (clean shutdown, Ctrl-C, panic).
DHT counter wiring	dd progress reads live wire-byte counters from HyperDhtHandle::wire_counters() and displays a W ↑ rate ↓ rate (×amp) line.
CLI ergonomics	New global -v / --verbose count flag (warn / info / debug; RUST_LOG overrides). New global --no-public flag. Runtime bootstrap resolution (in cmd/mod.rs::resolve_bootstrap) is two-stage: CLI --bootstrap overrides the config file's network.bootstrap for the base list (not additive), then --public adds default public HyperDHT bootstrap nodes, an empty list auto-fills with the defaults, and --no-public removes the defaults. The legacy --firewalled flag is replaced by --no-public + the auto-public default. Chat-scoped globals: --debug, --probe, --line-mode (env: PEEROXIDE_LINE_MODE=1).
Manpages	peeroxide-init(1) and peeroxide-chat(1) join the existing pages. peeroxide init --man-pages [PATH] replaces the old --generate-man <DIR> flag and cleans stale peeroxide*.1 before writing.
Tests	New tests/chat_integration.rs (~889 LOC). tests/local_commands.rs expanded from ~225 to ~1063 LOC. tests/live_commands.rs updated for the renamed dd put / dd get surface. Unit-test coverage added across chat::ordering, chat::name_resolver, chat::inbox_monitor, chat::tui::status, chat::tui::interactive, chat::tui::commands, chat::tui::input, and dd v2 v2::need::compute_need_entries.

peeroxide-dht

Area	Change
Wire-byte counters	New public WireCounters type in io.rs (atomic bytes_sent / bytes_received handles + new + snapshot). Io gains a pub wire: WireCounters field and a wire_counters() accessor. DhtHandle and HyperDhtHandle gain wire_stats() -> (u64, u64) and wire_counters() -> WireCounters. Drives the dd progress amplification line.
rpc.rs	Threads the shared WireCounters through DhtHandle and the spawn path. No existing signature changes.
hyperdht.rs	Adds public wrapper accessors that delegate to the inner DHT handle. No existing signature changes.

peeroxide

Area	Change
Cargo.toml	Bumps the peeroxide-dht dependency from 1.2.0 to 1.3.0. No source changes.

Documentation (docs/)

Area	Change
New chapters	docs/src/init/overview.md; docs/src/chat/{overview,user-guide,interactive-tui,wire-format,protocol,reference}.md.
Rewritten chapters	docs/src/dd/{overview,architecture,format,operations,future-direction}.md (now cover v1 + v2 side-by-side; future-direction.md collapsed to a one-liner stating v2 is shipped).
Updated chapters	docs/src/SUMMARY.md (adds Setup → init and Commands → chat sections); docs/src/introduction.md (mentions init, chat, dd v1/v2; lists eight primary commands); docs/src/appendices/limits-and-performance.md (new Chat + Dead Drop (v2) constants tables); docs/src/appendices/security-model.md (minor edits); docs/AGENTS.md (small note updates).
Other	docs/ascii_art.txt added (decorative ASCII art asset).
Build	Verified with mdbook build docs/ — clean build, no broken links.

Repository documentation

Path	Change
.github/PULL_REQUEST_TEMPLATE.md	New PR template with PR Checklist, Public API Changes section, and Testing checklist.
peeroxide-cli/README.md	Updated for the new init, chat, dd v2, and progress flag surface; man-pages section now describes the recursive 23-page output (including nested chat subcommands like peeroxide-chat-profiles-create(1) and peeroxide-chat-friends-add(1)); config-path precedence includes $XDG_CONFIG_HOME and platform dirs::config_dir() lookups.
peeroxide-cli/CHANGELOG.md	Adds [Unreleased] entries documenting the dd rename + new progress UX flags + JSON event schema (the chat/init work is implicitly part of the 0.2.0 bump documented in Cargo.toml).
CONTRIBUTING.md	Tiny clarification edit.
AGENTS.md, peeroxide-cli/AGENTS.md, docs/AGENTS.md	Refreshed for the eight-subcommand surface, the cmd/chat/ tree, the deaddrop split into v1.rs + v2/, current v2 constants (DATA_PAYLOAD_MAX=998, NON_ROOT_INDEX_SLOT_CAP=31, ROOT_INDEX_SLOT_CAP=30, SOFT_DEPTH_CAP=4, etc.), the new chat constants (MAX_RECORD_SIZE=1000, HISTORY_CAP=500, GAP_TIMEOUT=5s, …), and the now-shipped state of dd v2 (the previous "v2 not yet implemented" note is gone).

Version bumps

Crate	From	To	Notes
peeroxide-cli	0.1.0	0.2.0	Binary crate; not subject to library SemVer.
peeroxide-dht	1.2.0	1.3.0	MINOR — additive public API only.
peeroxide	1.2.0	1.2.0	Unchanged source; only its dependency on peeroxide-dht bumped.
libudx	1.2.0	1.2.0	Unchanged.

New peeroxide-cli dependencies (binary only)

blake2, ed25519-dalek, curve25519-dalek, sha2, xsalsa20poly1305, chrono, memmap2, crossterm (with event-stream + bracketed-paste), arc-swap, toml_edit, fs2. All required by the chat or dd-v2 work. No new library-crate dependencies.

Public API Changes

All changes below are: [x] Additive only (semver-compatible) / [ ] Breaking (requires maintainer approval)

Crate	Symbol	Change
peeroxide-dht	io::WireCounters	New public struct (bytes_sent: Arc<AtomicU64>, bytes_received: Arc<AtomicU64>).
peeroxide-dht	io::WireCounters::new	New public fn.
peeroxide-dht	io::WireCounters::snapshot	New public fn — returns (sent, received).
peeroxide-dht	io::Io::wire	New public field (additive — Io already had private fields, so adding a new field is non-breaking per Cargo SemVer rules).
peeroxide-dht	io::Io::wire_counters	New public method.
peeroxide-dht	rpc::DhtHandle::wire_stats	New public method — returns (u64, u64).
peeroxide-dht	rpc::DhtHandle::wire_counters	New public method — returns WireCounters.
peeroxide-dht	hyperdht::HyperDhtHandle::wire_stats	New public method — returns (u64, u64).
peeroxide-dht	hyperdht::HyperDhtHandle::wire_counters	New public method — returns WireCounters.

No existing public symbols were removed, renamed, or had their signatures changed. No breaking changes in peeroxide, peeroxide-dht, or libudx. peeroxide-cli's CLI/flag surface changed substantially, but it is a binary and not subject to library SemVer rules.

MSRV: unchanged (workspace rust-version = 1.85).

Testing

• cargo test --workspace — all suites green (unit + integration + Node.js cross-language interop test hyperswarm_cross_language_connect).
• cargo test -p peeroxide-cli --test live_commands -- --ignored — public-network live tests green: test_live_lookup, test_live_announce_then_lookup, test_live_cp_send_recv, test_live_dd_roundtrip.
• cargo clippy --workspace --all-targets -- -D warnings — clean.
• cargo +1.85.0 check --workspace --all-targets — MSRV gate green (let-chain syntax that was failing on the remote Check MSRV workspace job has been rewritten into stable Rust 1.85 control flow in peeroxide-cli/src/cmd/chat/{name_resolver,session,tui/interactive}.rs and peeroxide-cli/tests/chat_integration.rs).
• mdbook build docs/ — clean build, no broken links.

Notes

• This branch was long-lived and several themes were reworked along the way (need-list semantics, progress reporter, ctrl-c handling, chat publisher / receiver, DM → chat::session refactor, status-bar inbox segment, resize replay). The description above reflects the end state, not the commit history.
• The shipped dd v2 wire byte is 0x02. The design was iterated under the internal working name "v3"; the canonical spec at peeroxide-cli/DEADDROP_V2.md and all user-facing surfaces use v2, and in-tree source comments now point at DEADDROP_V2.md and the new docs/src/dd/ chapters (no remaining DEADDROP_V3.md references).
• The per-deaddrop salt byte in v2 data chunk headers is currently forced to 0x00 (the slot is reserved for future per-deaddrop randomization). Documented honestly in docs/src/dd/format.md.
• The chat dm and chat join interactive sessions share the same chat::session orchestration so any future session-level feature (status segment, slash command, shutdown step) lands in one place for both.
• The chat MAX_RECORD_SIZE budget is 1000 B per record; combined with the 180 B envelope overhead this gives ≤ 820 B for screen_name + content. Over-length content surfaces WireError::RecordTooLarge at point-of-attempt with a clear error; multi-frame / continuation messages are out of scope by design.

Working files cleanup

Design notes, implementation prompts, and working spec drafts that lived next to the code during development have been folded into the docs/ mdBook or deleted from the working tree. None of them ship in the published peeroxide-cli crate. Summary of what happened to each:

Path	Lines	Disposition
INIT_COMMAND_PLAN.md (root)	84	Always gitignored via *_PLAN.md; never tracked. Not in this PR. Implementation now documented in docs/src/init/overview.md.
peeroxide-cli/CHAT.md	1457	Deleted. Content folded into docs/src/chat/{wire-format,protocol}.md.
peeroxide-cli/CHAT_CLI.md	448	Deleted. Content folded into docs/src/chat/{user-guide,interactive-tui,reference}.md.
peeroxide-cli/CHAT_IMPL_PROMPT.md	305	Deleted. Implementation prompt; no shipped equivalent needed.
peeroxide-cli/DEBUG_FLAG.md	22	Deleted. The --debug flag is implemented and documented in docs/src/chat/user-guide.md and docs/src/chat/reference.md.
peeroxide-cli/DHT_REF.md	112	Deleted. Generic content folded into docs/src/concepts/dht-primitives.md; chat-specific size math dropped (already covered by docs/src/chat/reference.md).
peeroxide-cli/DEADDROP_V2.md	493	Deleted. dd v2 is now documented across docs/src/dd/{architecture,format,operations}.md.
docs/ascii_art.txt	9	Decorative ASCII-art asset. Pending review: keep as a future logo/banner, or remove if unused.

(The .claude/, .mcp.json, and testfile paths in the workspace root are untracked / gitignored and not in the PR.)