Add CLI tool for River to enable easier testing and debugging

[sanity]

Overview

Create a command-line interface for River that enables rapid testing of core functionality, particularly room creation and invitation flows that are currently failing on the live network.

Motivation

Currently, debugging River issues requires using the browser UI, which makes it difficult to:

• Reproduce bugs quickly
• Create automated tests
• See detailed debug information about contract operations
• Test specific scenarios in isolation

A CLI tool would provide:

1. Direct access to River functionality without UI dependencies
2. Better visibility into Freenet contract operations (PUT/GET)
3. Scriptable interface for automated testing
4. Alternative interface that some power users might prefer

Proposed Design

Core Commands

Room Management

river room create --name "Test Room" --description "Debug room"
river room list
river room join <room-id>
river room leave <room-id>
river room info <room-id>

Messaging

river message send <room-id> "Hello world"
river message list <room-id> [--last N]
river message stream <room-id>  # Real-time updates

Member Management

river invite create <room-id> --note "Join our test"
river invite accept <invitation-code>
river member list <room-id>
river member add <room-id> <member-id>

Debugging Commands

river debug contract-put <room-id>  # Test PUT operation
river debug contract-get <room-id>  # Test GET operation
river debug websocket               # Show WebSocket traffic
river debug sync-state             # Show synchronization state

Technical Requirements

1. Shared Core Logic: Reuse River's existing data structures and Freenet integration from the UI codebase
2. Configuration Support:
   • Custom Freenet node URLs
   • WebSocket timeout settings
   • Log level configuration
3. Output Formats:
   • Human-readable (default)
   • JSON (for scripting with tools like jq)
   • Debug mode with full contract data
4. Error Handling: Clear error messages with debugging suggestions

Example Usage

# Create a room and capture the ID
ROOM_ID=$(river room create --name "Test" --json  < /dev/null |  jq -r .room_id)

# Create an invitation
INVITE=$(river invite create $ROOM_ID --json | jq -r .invitation_code)

# Try to accept the invitation (currently failing on live network)
river --debug invite accept $INVITE

Implementation Priority

Start with the minimal set needed to reproduce current bugs:

1. room create - Test PUT operations
2. invite create / invite accept - Test GET operations
3. --debug flag for verbose contract operation logging

Success Criteria

1. Can reproduce the room invitation bug without browser UI
2. Provides clear visibility into PUT/GET contract operations
3. Shows exact timeout points and error messages
4. Enables rapid iteration when testing fixes

Future Enhancements

• Import/export room state for debugging
• Performance testing commands
• Batch operations for stress testing
• Contract state diffs between operations
• Network topology visualization

Related Issues

• This would help debug the ongoing invitation bug where PUT/GET operations timeout on the live network
• Would enable creation of automated integration tests for River

Technical Notes

• Use tokio for async runtime (consistent with River UI)
• Share contract types and serialization logic with UI
• Consider using clap for command parsing
• Structured logging with tracing crate

[sanity]

Data Storage Design

The CLI tool needs to store user data including private keys, room memberships, and local state. Here's the proposed approach:

Default Storage Locations

Following platform conventions:

• Linux/Unix: ~/.config/river-cli/
• macOS: ~/Library/Application Support/river-cli/
• Windows: %APPDATA%/river-cli/

Storage Structure

• config.toml - Default Freenet node URL, log level, etc.
• identity/ - User's River private/public keys
• rooms/ - Room memberships and cached data
• state/ - Synchronization state

CLI Override Options

To support testing with multiple instances:

Use custom data directory

river --data-dir /tmp/river-test-1 room create --name "Test"

Or set via environment variable

export RIVER_DATA_DIR=/tmp/river-test-2
river room list

Completely ephemeral mode (nothing persisted)

river --ephemeral room create --name "Temp Room"

Testing Considerations

For automated testing:

• Deterministic key generation with seed: river --seed "test-seed-123" identity new
• Temporary directories that auto-cleanup: river --temp-dir room create
• Export/import of complete state for test fixtures

This design ensures the CLI tool can be used both as a daily driver and for testing without conflicts between instances.

[sanity]

Important Clarification: Subscribe/Update Operations

The primary issue is actually with subscribe/update operations, not just PUT/GET. The current bug manifests as:

The Real Problem

• Room updates fail to propagate between two River UI instances
• This happens even when both browsers are connected to the same Freenet peer
• Updates (new messages, member joins) made in one window don't appear in the other
• The subscription mechanism appears to be failing to notify clients of state changes

Testing Scenarios for CLI Tool

The CLI tool should prioritize testing these subscription/update flows:

# Terminal 1: Subscribe to room updates
river room subscribe <room-id> --follow

# Terminal 2: Send a message
river message send <room-id> "Test message"

# Terminal 1 should immediately show the new message

Key Operations to Test

1. Subscribe to room state changes

   • CLI should maintain WebSocket connection for real-time updates
   • Show when subscription is established vs when it times out

2. Update notifications

   • When room state changes, all subscribers should be notified
   • Test with multiple CLI instances subscribing to same room

3. State synchronization

   • After an update, all clients should have identical room state
   • CLI should show contract version/hash for debugging

Debugging Commands Should Include

# Subscribe to a room and show all contract updates
river debug subscribe <room-id> --verbose

# Monitor update propagation across clients
river debug monitor-updates <room-id>

# Test update notification system
river debug test-subscription <room-id>

This will help us debug why updates aren't propagating between clients, which is the core issue preventing River from being usable on the network.

Implementation Note: Using freenet-stdlib

The CLI tool should use the freenet-stdlib crate for Freenet communication. This library can be used both from WASM and native applications depending on feature flags:

For Native CLI Tool

[dependencies]
freenet-stdlib = { version = "0.1.9", default-features = false, features = ["std"] }

Key APIs to Use

• Review the freenet-stdlib documentation on crates.io for the current API
• The library provides WebSocket client functionality for native applications
• Use the same contract interfaces that the River UI uses, but from native code
• This ensures consistency between CLI and UI implementations

The freenet-stdlib source is available for reference, but always check the published version on crates.io for the stable API.

[kustomzone]

Seems the default WS port is in an excluded range on Win 10.
We can change it, but it could catch people unawares.

Freenet node WebSocket URL default: ws://127.0.0.1:50509

 netsh interface ipv4 show excludedportrange protocol=tcp

Protocol tcp Port Exclusion Ranges

 (Start Port) (End Port), ...

│    49677  49776, 49877  49976, 50000  50059, 50060  50159, 50260  50359, 50460  50559,    │  <---
│    50560  50659, 50660  50759, 50760  50859, 50974  51073, 51074  51173, 51514  51613,    │
│    51614  51713, 51714  51813, 51814  51913, 51914  52013                                 │

.

[sanity]

Seems the default WS port is in an excluded range on Win 10

Good catch, will file a bug.

[sanity]

@kustomzone Thanks for pointing out the Windows port issue! I've created a tracking issue in freenet-core for this: freenet/freenet-core#1751

The default WebSocket port 50509 indeed falls within Windows' excluded range (50000-50059). We'll need to change the default to something outside the reserved ranges.