feat(exec): add streaming, pagination, and serialization for query execution

[joewiz]

Summary

Overhauls the exec command with three new execution capabilities and rich serialization control.

Execution modes

• Cursor-based pagination (new default) — uses lsp:eval/lsp:fetch via REST API; interactive TTY sessions prompt between pages, piped output fetches all pages automatically. Falls back to XML-RPC if the lsp module is unavailable.
• WebSocket streaming (--stream) — connects to /exist/ws/eval, prints results as they arrive, Ctrl+C sends cancel.
• XML-RPC (fallback) — used when --bind variables are provided or cursor API is unavailable.

New flags

Flag	Description
--stream / -s	Stream results via WebSocket
--timing / -t	Show execution timing breakdown
--page-size <n>	Results per page in cursor mode (default: 20)
--output / -o	Output format: text (default) or json
--method	Serialization method: xml, json, text, html, adaptive
--indent / --no-indent	Enable or suppress indented output
--highlight	Wrap full-text matches in highlight elements

Sample commands

# Default: paginated output (cursor-based, 20 results/page)
xst exec "for $i in 1 to 100 return $i"

# Explicit page size
xst exec --page-size 50 "for $i in 1 to 1000 return $i"

# Stream all results via WebSocket
xst exec --stream "for $i in 1 to 100000 return $i"

# Show timing breakdown
xst exec --timing "1 + 1"
# 2
# Parse: 1ms | Compile: 2ms | Eval: 0ms | Total: 3ms

# JSON output format (collects all pages)
xst exec --output json "map { 'key': 'value' }"

# Serialization: JSON method
xst exec --method json "map { 'key': 'value' }"

# Serialization: XML without indentation
xst exec --method xml --no-indent "doc('/db/data.xml')"

# Serialization: raw text values
xst exec --method text "string-join(1 to 5, ',')"

# Serialization: full-text highlights
xst exec --highlight "collection('/db/shakespeare')//SPEECH[ft:query(., 'love')]"

# Compact output (no indent)
xst exec --no-indent "for $i in 1 to 5 return <item>{$i}</item>"

# Stream with timing
xst exec --stream --timing "for $i in 1 to 10 return $i"

# Variable bindings (uses XML-RPC fallback)
xst exec -b '{"a":1}' '$a+$a'

Dependencies

Requires the server-side WebSocket eval endpoint from eXist-db/exist#6145 for --stream to function. Cursor-based pagination requires the lsp XQuery module; falls back to XML-RPC automatically if unavailable. --timing without --stream works against any existing eXist-db instance.

Note: CI is expected to fail until eXist-db/exist#6145 is merged into develop.

Test plan

• xst exec "1+1" — uses cursor API, falls back to XML-RPC
• xst exec --timing "1+1" — prints result + timing to stderr
• xst exec --stream "for $i in 1 to 10 return $i" — streams items via WebSocket
• xst exec --stream --timing "1+1" — streams + shows granular timing
• xst exec --page-size 50 "for $i in 1 to 1000 return $i" — paginated output with custom page size
• xst exec --output json "map { 'key': 'value' }" — JSON-formatted output
• xst exec --method text 'string-join(("a","b","c"), ",")' — text serialization
• xst exec --no-indent "<root><child/></root>" — suppressed indentation
• xst exec -b '{"a":1}' '$a+$a' — variable bindings use XML-RPC path
• Ctrl+C during --stream — sends cancel, prints summary
• Piped output (xst exec --page-size 5 "..." | cat) fetches all pages without prompting

🤖 Generated with Claude Code