Wave Client for Emacs - Project Documentation

gmake test-api

Output:

Testing Wave Server API...
=== Health Check ===
{"status":"healthy","timestamp":"2026-01-10T21:12:13.817809"}

=== Inbox ===
[{"id":"indexwave!indexwave","digest":"Wave Server Index","unread":0,"creator":"system@localhost"},...]

=== Root ===
{"message":"Wave Server API","status":"running","version":"0.2.0"}

gmake elisp-version

Output:

Emacs version: GNU Emacs 30.1 (build 1, aarch64-unknown-freebsd14.3)

Tests that all elisp modules load without errors:

gmake elisp-load-test

Output:

Testing elisp module loading...
Loading wave-client.el... done
Loading wave-mode.el... done
Loading wave-list.el... done
Loading wave-edit.el... done
All modules loaded successfully!

# Start server first
gmake server &
sleep 3

# Fetch inbox via Emacs batch mode
gmake elisp-http-inbox

Output:

Fetching inbox via HTTP from localhost:9898...
=== INBOX (5 waves) ===
  indexwave!indexwave: Wave Server Index
  localhost!conv+root: Discussion: Wave protocol features
  localhost!conv+root: Emacs client testing
  localhost!conv+root: Architecture discussion with diagram
  localhost!b+reply1: Charlie: Don't forget about the conflict resolution algorithms!

The elisp-http-inbox target runs this code:

(require 'url)
(require 'json)

(defun fetch-inbox ()
  (with-current-buffer
    (url-retrieve-synchronously "http://localhost:9898/api/inbox" t)
    (goto-char (point-min))
    (re-search-forward "^$" nil t)
    (let* ((json-object-type 'plist)
           (inbox (json-read)))
      (message "=== INBOX (%d waves) ===" (length inbox))
      (dolist (wave (append inbox nil))
        (message "  %s: %s"
          (plist-get wave :id)
          (plist-get wave :digest))))))

(fetch-inbox)

gmake ws-test

Uses scripts/ws-test.py to verify WebSocket connectivity:

Connecting to ws://localhost:9898/ws...
Connected!
Sending ProtocolOpenRequest for indexwave!indexwave
Received: {"version":0,"sequenceNumber":1,"messageType":"ProtocolWaveletUpdate",...}
All tests passed!

gmake ws-test-interactive

Opens an interactive session for manual WebSocket testing.

Problem: The waves endpoint had two issues:

1. Missing /health endpoint
2. doc_data was sometimes a list instead of dict

Solution: Added type checking in get_wave endpoint:

if isinstance(doc_data, dict):
    docs_dict[doc_id] = Document(
        doc_id=doc_id,
        contributors=doc_data.get("contributors", []),
        ...
    )
else:
    # doc_data is a primitive or list, wrap it as content
    docs_dict[doc_id] = Document(
        doc_id=doc_id,
        contributors=[],
        content=[doc_data] if not isinstance(doc_data, list) else doc_data
    )

Problem: The websockets library 15.0+ removed the .open attribute.

Solution: Use .state instead:

from websockets.protocol import State

def is_connected(ws) -> bool:
    return ws.state == State.OPEN

WebSocket operations in batch mode hit recursion limits due to accept-process-output loop depth. Use synchronous HTTP for batch testing.

uv rebuilds C extensions on FreeBSD. Workaround: use polecat worktree venv which has pre-built packages.