Phase 14b: serve backend — meta watcher, watcher errors, new routes, defensive Zod

[ABB65]

Summary

• Watchers — .contentrain/meta/ now surfaced via new meta:changed WS event; chokidar 'error' no longer silently swallowed (new file-watch:error WS event with message + timestamp).
• New routes — GET /api/describe-format (wraps contentrain_describe_format); GET /api/preview/merge?branch=cr/... (side-effect-free FF / conflict / already-merged preview before approve).
• Defensive Zod — /api/normalize/plan/reject validates an optional { reason? } body; whole serve write surface now parses through one parseOrThrow() gate.

Details

meta:changed

Covers both real layouts agents produce:

• meta/<model>/<locale>.json → { type: 'meta:changed', modelId, locale }
• meta/<model>/<entry>/<locale>.json → { type: 'meta:changed', modelId, entryId, locale }

Previously editing any .contentrain/meta/*.json file left the Serve UI rendering stale metadata until a full refresh.

file-watch:error

chokidar's error event was unhandled. Now broadcasts { type: 'file-watch:error', message, timestamp }. The UI can render a "watcher down, live updates paused" banner instead of silently degrading (e.g. hitting the OS inotify limit on Linux).

/api/preview/merge

Returns { alreadyMerged, canFastForward, conflicts, filesChanged, stat }. Three signals:

• alreadyMerged — merge-base --is-ancestor <branch> <CONTENTRAIN_BRANCH> succeeds (approve would be a no-op)
• canFastForward — merge-base --is-ancestor <CONTENTRAIN_BRANCH> <branch> succeeds (FF possible)
• conflicts — best-effort list from git merge-tree. [] when clean; null when the check couldn't run (older git, missing refs)

Does NOT run the real merge. Complements the approve route, which continues to surface runtime conflicts by throwing.

Out of scope (explicit)

• /api/doctor — no contentrain_doctor MCP tool exists; only the CLI's 540-line command. Rather than duplicate CLI logic into serve, we defer until doctor is extracted into a reusable MCP tool.
• sdk:regenerated WS event — contentrain generate runs outside serve's process so the watcher can't observe it cleanly. Needs a different hook; defer until the design is concrete.

Test plan

• oxlint across cli src + tests → 0 warnings on 209 files
• contentrain typecheck → 0 errors
• contentrain vitest → 137/137 (was 130 on next-mcp); 7 new tests covering:
  • meta:changed with and without entryId
  • file-watch:error payload shape (message + ISO timestamp)
  • /api/describe-format invokes the correct MCP tool
  • /api/preview/merge rejects non-cr branches with 400
  • /api/preview/merge happy path: FF-possible, no conflicts, correct filesChanged
  • plan/reject accepts { reason? } body AND empty body AND rejects malformed

No MCP or tool surface changes

Pure serve-backend pass on existing tools.

🤖 Generated with Claude Code