zetviel/PLAN.md

Zetviel Development Plan

Project Rules

1. Always run zig fmt . after any change to a zig file
2. Before considering a task complete: zig build must have no errors/output
3. Before considering a task complete: all tests must pass with zig build test

Goal

Create a netviel clone with improvements:

• Visual indication that server is working
• URL changes with UI state for deep linking
• Custom frontend (not copying netviel's JavaScript)

Phase 1: Upgrade Zig ✅ COMPLETE

• Update build.zig.zon to Zig 0.15.2
• Update .mise.toml to use Zig 0.15.2
• Fix breaking changes in build.zig (Module API, alignment issues)
• Fix breaking changes in src/main.zig (stdout API)
• Fix JSON API changes in src/root.zig (converted OutOfMemory to WriteFailed)
• Verify all tests pass
• Run zig fmt .

Phase 2: Complete Email Parsing API ✅ COMPLETE

• Finish Email.zig implementation:
  • Extract HTML/plain text content with preference (html > plain)
  • Parse and list attachments (filename, content-type)
  • Extract all standard headers (from, to, cc, bcc, date, subject)
  • Add attachment retrieval by index (getAttachments method)
• Integrate Email parsing into root.zig Thread API
• Add tests for new functionality (existing tests pass)
• Run zig fmt .

Phase 3: HTTP Server & REST API ✅ COMPLETE

• Research and choose HTTP framework (httpz)
• Add HTTP server dependency
• Implement REST endpoints:
  • GET /api/query/<query_string> - search threads
  • GET /api/thread/<thread_id> - get thread messages
  • GET /api/attachment/<message_id>/<num> - download attachment
  • GET /api/message/<message_id> - get message details
• Complete JSON serialization (extend existing in root.zig)
• Add security headers via httpz middleware
• Add tests for API endpoints
• Run zig fmt .

Phase 4: Static File Serving ✅ COMPLETE

• Implement static file serving:
  • Serve index.html at /
  • Serve static assets (placeholder 404 handler)
  • Handle SPA routing (all non-API paths ready)
• Add --port CLI argument
• Run zig fmt .

Phase 5: Frontend Development

• Design minimal UI (list threads, view messages, search)
• Implement frontend features:
  • Thread list view
  • Message detail view
  • Search functionality
  • Visual server status indicator
  • URL-based routing for deep linking
  • Attachment download links
• Ensure API compatibility

Phase 6: Polish

• Add proper error handling throughout
• Add logging
• Update README with usage instructions
• Add configuration options (NOTMUCH_PATH env var)
• Security audit and warnings (local-only usage)
• Run zig fmt .

Notes

• Frontend will be custom-built, not copied from netviel
• HTTP framework choice deferred to Phase 3
• HTML sanitization will use simple allowlist approach (not porting bleach)

Current Status

Ready to begin Phase 1: Zig upgrade to 0.15.2