233 lines
12 KiB
Markdown
233 lines
12 KiB
Markdown
# 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):
|
|
```ini
|
|
[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
|