IRC-kosmi-relay/QUICK_REFERENCE.md

# Quick Reference Guide

## Testing the Bridge

### Build and Run Test Program

```bash
cd /Users/erikfredericks/dev-ai/HSO/irc-kosmi-relay
go build -o test-kosmi ./cmd/test-kosmi
./test-kosmi -room "https://app.kosmi.io/room/@hyperspaceout" -debug
```

### Expected Output (Success)

```
INFO Launching headless Chrome for Kosmi connection
INFO Injecting WebSocket interceptor (runs before page load)...
INFO Navigating to Kosmi room: https://app.kosmi.io/room/@hyperspaceout
INFO ✓ WebSocket hook confirmed installed
INFO Status: WebSocket connection intercepted
INFO Successfully connected to Kosmi via Chrome
INFO Listening for messages... Press Ctrl+C to exit
```

### When Messages Arrive

```
INFO Processing 1 messages from queue
INFO Received message: [00:02:51] username: [Kosmi] <username> message text
```

## Key Status Indicators

| Status Message | Meaning | Action |
|---------------|---------|--------|
| `✓ WebSocket hook confirmed installed` | Hook script is active | ✅ Good |
| `Status: WebSocket connection intercepted` | WebSocket is being captured | ✅ Good |
| `Status: No WebSocket connection detected yet` | Hook missed the WebSocket | ❌ Check injection timing |
| `Processing N messages from queue` | Messages are being captured | ✅ Good |

## Common Issues

### Issue: "No WebSocket connection detected yet"

**Cause**: WebSocket hook was injected too late

**Fix**: Verify `injectWebSocketHookBeforeLoad()` uses `page.AddScriptToEvaluateOnNewDocument`

### Issue: "Chrome not found"

**Cause**: Chrome/Chromium not installed or not in PATH

**Fix**: 
```bash
# macOS
brew install --cask google-chrome

# Ubuntu/Debian
sudo apt install chromium-browser

# Verify installation
which google-chrome chromium chromium-browser
```

### Issue: Messages not appearing

**Cause**: Multiple possibilities

**Debug**:
1. Check for "✓ WebSocket hook confirmed installed" ✓
2. Check for "Status: WebSocket connection intercepted" ✓
3. Enable debug logging: `-debug` flag
4. Send a test message in the Kosmi room
5. Look for "Processing N messages from queue"

## Configuration

### Minimal Test Configuration

```toml
[kosmi.test]
RoomURL="https://app.kosmi.io/room/@hyperspaceout"
Debug=true
```

### Full Matterbridge Configuration

```toml
# Kosmi
[kosmi.hyperspaceout]
RoomURL="https://app.kosmi.io/room/@hyperspaceout"

# IRC
[irc.libera]
Server="irc.libera.chat:6667"
Nick="kosmi-relay"
UseTLS=false

# Gateway
[[gateway]]
name="kosmi-irc"
enable=true

[[gateway.inout]]
account="kosmi.hyperspaceout"
channel="main"

[[gateway.inout]]
account="irc.libera"
channel="#your-channel"
```

## Message Format

### Kosmi → IRC

```
[Kosmi] <username> message text
```

### IRC → Kosmi

```
[IRC] <username> message text
```

## File Locations

| File | Purpose |
|------|---------|
| `bridge/kosmi/kosmi.go` | Main bridge implementation |
| `bridge/kosmi/chromedp_client.go` | Headless Chrome client |
| `bridge/kosmi/graphql.go` | GraphQL structures (legacy) |
| `cmd/test-kosmi/main.go` | Standalone test program |
| `matterbridge.toml` | Configuration file |

## Key Implementation Details

### WebSocket Hook Injection

**MUST** use `page.AddScriptToEvaluateOnNewDocument` to inject **before page load**:

```go
chromedp.ActionFunc(func(ctx context.Context) error {
    _, err := page.AddScriptToEvaluateOnNewDocument(script).Do(ctx)
    return err
})
```

### Hook Script

Wraps `window.WebSocket` constructor to intercept all WebSocket connections:

```javascript
window.WebSocket = function(url, protocols) {
    const socket = new OriginalWebSocket(url, protocols);
    // ... interception logic ...
    return socket;
};
```

## Debugging Commands

```bash
# Test Chrome installation
which google-chrome chromium chromium-browser

# Test network connectivity
curl -I https://app.kosmi.io

# Build with verbose output
go build -v -o test-kosmi ./cmd/test-kosmi

# Run with debug logging
./test-kosmi -room "https://app.kosmi.io/room/@hyperspaceout" -debug

# Check for linter errors
go vet ./...
```

## Performance Notes

- **Chrome Startup**: ~1-2 seconds
- **Page Load**: ~1-2 seconds
- **Message Latency**: ~100-500ms
- **Memory Usage**: ~100-200MB (Chrome process)

## Security Considerations

- Bridge runs Chrome in headless mode (no GUI)
- No credentials stored (anonymous access)
- WebSocket traffic is intercepted in memory only
- Messages are not logged to disk (unless debug logging enabled)

## Production Deployment

### systemd Service Example

```ini
[Unit]
Description=Kosmi-IRC Relay
After=network.target

[Service]
Type=simple
User=matterbridge
WorkingDirectory=/opt/matterbridge
ExecStart=/opt/matterbridge/matterbridge -conf /etc/matterbridge/matterbridge.toml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

### Docker Considerations

When running in Docker, ensure:
- Chrome/Chromium is installed in the container
- `--no-sandbox` flag may be needed for Chrome
- Sufficient memory allocation (512MB minimum)

## Resources

- **Documentation**: See `README.md`, `QUICKSTART.md`, `LESSONS_LEARNED.md`
- **Integration Guide**: See `INTEGRATION.md`
- **Implementation Details**: See `IMPLEMENTATION_SUMMARY.md`
- **ChromeDP Guide**: See `CHROMEDP_IMPLEMENTATION.md`

## Support

For issues:
1. Check this quick reference
2. Review `LESSONS_LEARNED.md` for common patterns
3. Enable debug logging for detailed output
4. Check Chrome console logs in debug mode