2 Commits
| Author | SHA1 | Message | Date |
|---|---|---|---|
 Mike Kell
|
63a35eceeb |
feat(stage-16a): error logging, crash capture, and bug reporting
Closes the two findings the release committee review identified as absolute gaps: the platform had no structured logging and no crash reporting, so runtime errors were invisible in every environment and operators had no way to report a defect with evidence attached. Addresses PROJECT_STATE_AUDIT.md findings P3.4 (structured logging infrastructure) and P3.5 (crash reporting integration), plus the "No logging infrastructure" and "No crash reporting" architectural risks in section 3.4. core — new observability layer (packages/core/lib/src/observability/): - KcLogLevel: five ordered severities (debug/info/warning/error/fatal) with numeric severity, label, isAtLeast() threshold comparison, and fromString(). - KcLogRecord: immutable structured record (level, source, message, timestamp, unmodifiable context, error, stackTrace) with format(), toJson(), isFailure. - KcRedactor: credential redaction over 14 sensitive key fragments, recursing through nested maps and lists. Applied to every logged context map and every bug report diagnostics map. - KcLogSink contract plus three implementations: KcConsoleLogSink (silent in release by default), KcInMemoryLogSink (bounded ring buffer supplying bug report evidence), KcMultiLogSink (fan-out that tolerates a failing sink). - KcLogger: the logging facade. Drops sub-threshold records, redacts context, and swallows sink exceptions so observability can never break a business operation. Provides forSource() for subsystem-scoped child loggers. - KcErrorReporter: installs FlutterError.onError and PlatformDispatcher.instance.onError, and provides runGuarded() to wrap runApp. restore() resets global state so tests stay isolated. - KcBugSeverity and KcBugReport: the report model with redacted diagnostics, hasFailureEvidence, toJson() for transmission, and toMarkdown() for export. - KcBugReportSink contract plus KcInMemoryBugReportSink. - KcBugReportService: validates input, attaches the recent log tail as evidence, logs the submission outcome, and returns a failure result rather than throwing when the tracker is unreachable. - KcObservability: assembles logger, evidence buffer, and bug report service together. Building them independently is the most likely way to produce empty bug reports, so this bundle guarantees they share one buffer. design_system: - KcBugReportDialog and KcBugReportDraft: the shared operator reporting form with inline validation, severity selection, optional reporter identity, and an explicit statement that logs are attached and credentials are never included. Kept free of a core dependency so design_system stays dependency-free. Application wiring (kell_web and kell_mobile): - AppServices and MobileAppServices hold a KcObservability; all four factories (fake/wordpress/square/multi) stamp their environment label so reports are attributable to the mode that produced them. - Both main.dart entry points install the global error handlers before the first frame and wrap runApp in a guarded zone, then emit a startup record capturing the effective environment and whether a fake-mode credential fallback occurred. - "Report a problem" action added to the AppShell and MobileShell app bars, capturing the active screen (and tab index on mobile). Documentation: - docs/operations/release-checklist.md (new): per-environment release gates for Development, Test/QA, Staging, and Production. Each environment inherits the prior one's gates and adds its own, with build commands, functional and observability verification, a sign-off record, rollback triggers, and the open blocker register. - master_development_brief.md: Stage 16A manifest, corrected baseline, Stage 16C defined for the deferred scope (retry/rate limiting, remote sink, health dashboard, analytics). Marked the square()/multi() factory and ID conflation debt items resolved (fixed in Stage 10E but still listed as open). - build_execution_tracker.md: Stage 16A slice entry. - PRD.md: milestone table brought current; observability added to infrastructure requirements. Added a scoped markdownlint-disable for MD011 because the PRD's "(text)[cite: n]" citation markers are indistinguishable from reversed links and were silently corrupted by markdownlint --fix during this review. - mkdocs.yml and operations/index.md: register the release checklist. Corrections made during review: - The documented test total of 1,458 omitted feature_policy's 17 tests. The true grand total is 1,475; both figures are now documented with the reason. Validation: - 85 new tests: 56 core, 10 design_system, 10 kell_web, 9 kell_mobile. - 1,475/1,475 passing across all 11 packages and apps. - dart analyze --fatal-infos clean across all 11 packages and apps. - markdownlint clean on all five modified/created documents. Known limitations (tracked as Stage 16C): - Logs and bug reports are held in-process only. There is no remote sink, so diagnostics are lost on restart and are unavailable off-device. - Usage analytics and the per-channel integration health dashboard are not implemented; IntegrationHealthCheck remains a contract with no implementation. |
|
|
Mike Kell
|
079bf8c0f0 |
Updated Agentic Instructions
Publish Docs / publish-docs (push) Successful in 54s
Details
|