12 KiB

Raw Blame History

Phase 5: Headless Node, Integration Testing & Release

Status: Pending Phase 4 Completion

Phase Goal: Complete the chronogrid_daemon headless binary with all background services, perform comprehensive multi-device integration testing, finalize cross-platform build pipelines, and produce release artifacts for Windows (.msi), Linux (.AppImage/.deb), and Android (.apk).

Prerequisites: Phase 4 complete ✅
Estimated Complexity: High
Blocking: None — this is the final phase

Task 5.1 — Complete chronogrid_daemon Headless Binary

Task 5.1: Complete the chronogrid_daemon headless binary with all background services:
- Implement full daemon startup sequence in apps/chronogrid_daemon/src/main.rs:
  1. Parse CLI args and load TOML config
  2. Initialize tracing structured logging (JSON format for production, pretty for dev)
  3. Load or generate NodeIdentity from config path
  4. Retrieve master key from keychain (or encrypted keyfile for headless)
  5. Initialize chronogrid_core::Database
  6. Start chronogrid_net::SwarmManager (P2P mesh)
  7. Start IMAP polling tasks for all configured accounts
  8. Start filesystem watchers for all configured watch paths
  9. Start CalDAV embedded server on 127.0.0.1:4242
  10. Start Eisenhower score recomputation timer (every 15 minutes)
  11. Start automation rules engine event loop
  12. Block on shutdown signal (SIGTERM/SIGINT/SIGHUP)
  13. Graceful shutdown: stop all background tasks, flush database, close P2P swarm
- Implement apps/chronogrid_daemon/src/config.rs:
  - DaemonConfig struct with full TOML deserialization
  - Sections: [node], [database], [network], [imap] (array), [watchers] (array), [caldav], [logging]
- Implement apps/chronogrid_daemon/src/web_gui.rs:
  - Lightweight HTTPS web interface on 127.0.0.1:8443 using axum
  - Self-signed TLS certificate generated on first run
  - REST API endpoints: GET /api/tasks, GET /api/notes, POST /api/tasks, GET /api/sync/status
  - Minimal HTML/JS dashboard for browser-based task management
- Create apps/chronogrid_daemon/config.example.toml with all options documented
- Run cargo build --release --package chronogrid_daemon

Task 5.2 — Headless Keyfile Credential Store

Task 5.2: Implement encrypted keyfile credential storage for headless/server deployments:
- Create crates/chronogrid_crypto/src/keyfile.rs:
  - KeyFile struct: stores encrypted master key + salt in a file
  - Encryption: AES-256-GCM with a key derived from a server-specific secret (environment variable or systemd credential)
  - KeyFile::create(path: &Path, master_key: &[u8], server_secret: &[u8]) -> Result<()>
  - KeyFile::load(path: &Path, server_secret: &[u8]) -> Result<Vec<u8>>
- Implement chronogrid_crypto::resolve_key(config: &KeyConfig) -> Result<Vec<u8>>:
  - Tries OS keychain first (desktop mode)
  - Falls back to keyfile (headless mode)
  - Falls back to environment variable CHRONOGRID_MASTER_KEY (CI/container mode)
- Update chronogrid_daemon to use resolve_key for flexible credential resolution
- Unit tests: keyfile create/load round-trip, wrong server secret rejection, env var fallback
- Run cargo test --package chronogrid_crypto

Task 5.3 — Multi-Device Integration Test Suite

Task 5.3: Create a comprehensive multi-device integration test suite:
- Create tests/integration/ directory at workspace root
- Add integration_tests as a workspace member with [[test]] targets
- Implement tests/integration/sync_convergence.rs:
  - Spawn two in-process SwarmManager instances on loopback
  - Create a task on Node A while Node B is offline
  - Reconnect nodes and verify task appears on Node B within 5 seconds
  - Verify CRDT merge: concurrent title edits on both nodes converge to a single value
- Implement tests/integration/crypto_pipeline.rs:
  - Full pipeline: passphrase → Argon2id → SQLCipher open → CRDT write → read back
  - Verify wrong passphrase cannot open database
  - Verify keychain store/retrieve round-trip
- Implement tests/integration/ingestion_pipeline.rs:
  - Mock IMAP server → IMAP poller → AI processing → task created in DB
  - File watcher → Markdown file drop → note + tasks created in DB
  - Jot text → NLP pipeline → task with correct namespace, due date, duration
- Implement tests/integration/caldav_sync.rs:
  - CalDAV server starts → curl PROPFIND → verify calendar collection response
  - Create time block → verify iCalendar VEVENT in REPORT response
- Run cargo test --test sync_convergence --test crypto_pipeline --test ingestion_pipeline --test caldav_sync

Task 5.4 — Performance & Stress Testing

Task 5.4: Perform performance and stress testing:
- Implement tests/perf/crdt_merge_stress.rs:
  - Generate 10,000 concurrent task mutations across 3 simulated peers
  - Verify all peers converge to identical state within 30 seconds
  - Measure merge throughput: target > 1,000 merges/second
- Implement tests/perf/db_query_perf.rs:
  - Insert 50,000 tasks across 10 namespaces
  - Measure query time for: list by namespace, filter by quadrant, filter by due date range
  - Target: all queries < 50ms on standard hardware
- Implement tests/perf/p2p_latency.rs:
  - Measure round-trip sync latency between two local peers
  - Target: < 500ms for a single task delta sync on LAN
- Document performance results in docs/ARCHITECTURE/06-performance-benchmarks.md
- Run cargo test --test crdt_merge_stress --test db_query_perf --test p2p_latency -- --nocapture

Task 5.5 — Android Platform Integration

Task 5.5: Complete Android platform integration:
- Configure Android NDK cross-compilation in scripts/build_android_libs.sh:
  - Targets: aarch64-linux-android (ARM64), armv7-linux-androideabi (ARM32), x86_64-linux-android (emulator)
  - Set ANDROID_NDK_HOME and CARGO_TARGET_*_LINKER environment variables
  - Build chronogrid_ffi for all three targets
  - Copy .so files to correct jniLibs subdirectories
- Implement Android KeyStore bridge in Flutter:
  - lib/src/core/android_keystore.dart — uses flutter_secure_storage for Android KeyStore-backed key storage
  - Override store_credential / retrieve_credential FFI calls on Android with Dart-side KeyStore implementation
- Implement Android-specific features:
  - QuickJotWidget — home screen widget using home_widget package
  - Share Intent receiver — AndroidManifest.xml intent filter for ACTION_SEND text/URL sharing
  - Background sync service — WorkManager periodic task for P2P sync when app is backgrounded
- Test on Android emulator: flutter run -d emulator-5554
- Test on physical Android device: flutter run -d <device_id>
- Run flutter test — all tests pass on Android target

Task 5.6 — Linux Platform Integration & AppImage Build

Task 5.6: Complete Linux platform integration and AppImage packaging:
- Configure GTK3 dependencies in apps/chronogrid_flutter/linux/CMakeLists.txt
- Link libchronogrid_ffi.so in Linux CMake build
- Implement Linux-specific features:
  - SecretService D-Bus integration (already in chronogrid_crypto via keyring crate)
  - Global hotkey via global-hotkey crate on Linux (X11/Wayland)
  - System tray icon using tray_manager Flutter package
- Create scripts/package_linux.sh:
  - Build Flutter Linux release: flutter build linux --release
  - Package as AppImage using appimagetool
  - Package as .deb using dpkg-deb
- Create docs/DEPLOYMENT/02-linux-installation.md
- Cross-compile from Windows using WSL2 or Docker: docker run --rm -v $(pwd):/workspace rust:latest cargo build --release --target x86_64-unknown-linux-gnu --package chronogrid_ffi

Task 5.7 — Windows MSI Installer

Task 5.7: Create the Windows MSI installer:
- Add wix toolset configuration: apps/chronogrid_flutter/windows/installer/
- Create Product.wxs WiX source file:
  - Application name, version, manufacturer metadata
  - Install chronogrid_flutter.exe and chronogrid_ffi.dll to Program Files\ChronoGrid\
  - Install chronogrid-daemon.exe as an optional Windows Service component
  - Desktop shortcut and Start Menu entry
  - Uninstaller registration
- Create scripts/build_windows_installer.ps1:
  - flutter build windows --release
  - cargo build --release --package chronogrid_daemon
  - Run WiX toolset: candle.exe Product.wxs && light.exe Product.wixobj -o ChronoGrid-Setup.msi
- Create docs/DEPLOYMENT/03-windows-installation.md
- Test installer on clean Windows VM

Task 5.8 — Systemd Service & Server Deployment Guide

Task 5.8: Finalize systemd service configuration and server deployment documentation:
- Create apps/chronogrid_daemon/deploy/chronogrid.service (systemd unit file):
```
[Unit]
Description=ChronoGrid Headless Peer Node
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=chronogrid
Group=chronogrid
WorkingDirectory=/var/lib/chronogrid
ExecStart=/usr/local/bin/chronogrid-daemon --config /etc/chronogrid/config.toml
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=chronogrid
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/var/lib/chronogrid

[Install]
WantedBy=multi-user.target
```
- Create apps/chronogrid_daemon/deploy/install.sh — automated server installation script
- Update docs/DEPLOYMENT/01-headless-daemon-setup.md with complete setup guide:
  - Prerequisites, binary installation, config file setup, keyfile credential setup, systemd enable/start, firewall rules, log monitoring
- Create docs/DEPLOYMENT/04-multi-device-pairing.md — guide for pairing desktop + mobile + headless nodes using Swarm Key

Task 5.9 — Final Verification & Release Checklist

Task 5.9: Execute final verification and prepare release:
- Run full test suite: cargo test --workspace — zero failures
- Run scripts/verify_agent_work.ps1 — exits with code 0
- Run integration tests: all convergence, crypto, ingestion, and CalDAV tests pass
- Run performance tests: all targets met (< 50ms queries, > 1,000 merges/sec, < 500ms P2P latency)
- Manual acceptance testing against all criteria in docs/ARCHITECTURE/04-master-user-story.md:
  - IMAP polling creates tasks within 2 seconds of receipt
  - Database is unreadable without master key
  - Offline edits on two devices converge after reconnection without data loss
  - All four UI views render from same CRDT state store
  - Headless daemon builds for Linux/systemd and maintains CRDT state
- Update docs/ARCHITECTURE/01-OSAD-system-architecture.md Section 8 roadmap to mark all phases complete
- Create CHANGELOG.md with v1.0.0 release notes
- Tag release: git tag -a v1.0.0 -m "ChronoGrid P2P v1.0.0 — Initial Release"
- Push tag: git push origin v1.0.0

Phase 5 Completion Criteria

All 9 tasks above marked [x]
cargo test --workspace passes with zero failures
All integration tests pass
All performance targets met
All 5 acceptance criteria from master user story verified manually
Windows .msi installer produced and tested
Linux .AppImage and .deb packages produced
Android .apk produced and tested on physical device
chronogrid-daemon binary deployed and running on headless Linux server
v1.0.0 git tag pushed to git.kellsupport.com
DECISION_LOG.md updated with Phase 5 decisions
All ADRs up to date

12 KiB Raw Blame History