feat: add --events flag for machine-readable NDJSON lifecycle events on stderr

[nextbysam]

Problem

wacli has --json for structured stdout output, but the auth/sync lifecycle — the most important part for programmatic consumers — only emits human-readable strings to stderr:

Starting authentication…
Connected.
Processing history sync (42 conversations)...
Synced 75 messages...
Idle for 30s, exiting.

Anyone building an application on top of wacli is forced to regex-parse English sentences to track what's happening. This is fragile: one wording change upstream silently breaks the consumer, and useful structured data (the Progress float from whatsmeow, conversation counts) gets thrown away in the string formatting.

This is a blind spot in an otherwise well-designed scripting interface — --json clearly signals intent for programmatic use, and issue #83 (JSON-RPC daemon) and issue #65 (Unix socket IPC) reinforce that vision.

Solution

Add a --events persistent flag that emits newline-delimited JSON to stderr during auth and sync, one event per line:

{"event":"auth_starting","ts":1709042400000}
{"event":"qr_code","data":{"code":"2@abc123..."},"ts":1709042400001}
{"event":"connected","ts":1709042400002}
{"event":"history_sync","data":{"conversations":42},"ts":1709042400003}
{"event":"progress","data":{"messages_synced":75},"ts":1709042400004}
{"event":"idle_exit","data":{"idle_duration":"30s","messages_synced":150},"ts":1709042400005}

Without --events, behavior is byte-for-byte identical to before. This is purely additive.

Events emitted

Event	When	Data fields
auth_starting	wacli auth begins	—
qr_code	QR ready to scan	code (raw QR string, not terminal art)
connected	whatsmeow events.Connected	—
disconnected	whatsmeow events.Disconnected	—
history_sync	whatsmeow events.HistorySync	conversations (count)
progress	every 25 messages stored	messages_synced (count)
reconnecting	backoff reconnect starts	—
stopping	graceful shutdown (SIGINT/SIGTERM)	messages_synced
idle_exit	idle timer fires	idle_duration, messages_synced

The qr_code event is particularly useful: instead of detecting Unicode block characters in a stream, consumers get the raw QR payload string and can render it however they want (web canvas, mobile SDK, PNG file).

Changes

• internal/out/events.go — EventWriter: thread-safe NDJSON emitter, no-op when disabled
• cmd/wacli/root.go — --events persistent flag wired to App.events
• internal/app/app.go — Events *out.EventWriter in Options; App.Events() accessor
• internal/app/sync.go — every fmt.Fprintf(os.Stderr, ...) dual-pathed: JSON event or existing text
• cmd/wacli/auth.go — auth_starting and qr_code events
• internal/out/events_test.go — unit tests for EventWriter
• internal/app/sync_events_test.go — integration tests using the existing fakeWA harness

Usage

# Machine-readable (new)
wacli auth --json --events --idle-exit 5s 2>events.ndjson

# Human-readable (unchanged)
wacli auth --json --idle-exit 5s

Combine with jq for easy scripting:

wacli sync --events 2>&1 | grep '^{' | jq 'select(.event == "progress") | .data.messages_synced'

🤖 Generated with Claude Code