Merge branch 'master' into android-safe-area-insets

.cursor/rules/development/logging_standards.mdc

@@ -0,0 +1,176 @@
+# Agent Contract — TimeSafari Logging (Unified, MANDATORY)
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-19
+**Status**: 🎯 **ACTIVE** - Mandatory logging standards
+
+## Overview
+
+This document defines unified logging standards for the TimeSafari project,
+ensuring consistent, rest-parameter logging style using the project logger.
+No `console.*` methods are allowed in production code.
+
+## Scope and Goals
+
+**Scope**: Applies to all diffs and generated code in this workspace unless
+explicitly exempted below.
+
+**Goal**: One consistent, rest-parameter logging style using the project
+logger; no `console.*` in production code.
+
+## Non‑Negotiables (DO THIS)
+
+- You **MUST** use the project logger; **DO NOT** use any `console.*`
+
+  methods.
+
+- Import exactly as:
+
+  - `import { logger } from '@/utils/logger'`
+
+  - If `@` alias is unavailable, compute the correct relative path (do not
+
+    fail).
+
+- Call signatures use **rest parameters**: `logger.info(message, ...args)`
+
+- Prefer primitives/IDs and small objects in `...args`; **never build a
+
+  throwaway object** just to "wrap context".
+
+- Production defaults: Web = `warn+`, Electron = `error`, Dev/Capacitor =
+
+  `info+` (override via `VITE_LOG_LEVEL`).
+
+- **Database persistence**: `info|warn|error` are persisted; `debug` is not.
+
+  Use `logger.toDb(msg, level?)` for DB-only.
+
+## Available Logger API (Authoritative)
+
+- `logger.debug(message, ...args)` — verbose internals, timings, input/output
+
+  shapes
+
+- `logger.log(message, ...args)` — synonym of `info` for general info
+
+- `logger.info(message, ...args)` — lifecycle, state changes, success paths
+
+- `logger.warn(message, ...args)` — recoverable issues, retries, degraded mode
+
+- `logger.error(message, ...args)` — failures, thrown exceptions, aborts
+
+- `logger.toDb(message, level?)` — DB-only entry (default level = `info`)
+
+- `logger.toConsoleAndDb(message, isError)` — console + DB (use sparingly)
+
+- `logger.withContext(componentName)` — returns a scoped logger
+
+## Level Guidelines (Use These Heuristics)
+
+### DEBUG
+
+Use for method entry/exit, computed values, filters, loops, retries, and
+external call payload sizes.
+
+### INFO
+
+Use for user-visible lifecycle and completed operations.
+
+### WARN
+
+Use for recoverable issues, fallbacks, unexpected-but-handled conditions.
+
+### ERROR
+
+Use for unrecoverable failures, data integrity issues, and thrown
+exceptions.
+
+## Context Hygiene (Consistent, Minimal, Helpful)
+
+- **Component context**: Prefer scoped logger.
+
+- **Emojis**: Optional and minimal for visual scanning.
+
+- **Sensitive data**: Never log secrets (tokens, keys, passwords) or
+  payloads >10KB. Prefer IDs over objects; redact/hash when needed.
+
+## DB Logging Rules
+
+- `debug` **never** persists automatically.
+
+- `info|warn|error` persist automatically.
+
+- For DB-only events (no console), call `logger.toDb('Message',
+  'info'|'warn'|'error')`.
+
+## Exceptions (Tightly Scoped)
+
+Allowed paths (still prefer logger):
+
+- `**/*.test.*`, `**/*.spec.*`
+
+- `scripts/dev/**`, `scripts/migrate/**`
+
+To intentionally keep `console.*`, add a pragma on the previous line:
+
+```typescript
+
+// cursor:allow-console reason="short justification"
+console.log('temporary output');
+
+```
+
+## CI & Diff Enforcement
+
+- Do not introduce `console.*` anywhere outside allowed, pragma'd spots.
+
+- If an import is missing, insert it and resolve alias/relative path
+  correctly.
+
+- Enforce rest-parameter call shape in reviews; replace object-wrapped
+  context.
+
+- Ensure environment log level rules remain intact (`VITE_LOG_LEVEL`
+  respected).
+
+---
+
+**See also**:
+  `.cursor/rules/development/logging_migration.mdc` for migration patterns and examples.
+
+**Status**: Active and enforced
+**Priority**: Critical
+**Estimated Effort**: Ongoing reference
+**Dependencies**: TimeSafari logger utility
+**Stakeholders**: Development team, Code review team
+
+## Model Implementation Checklist
+
+### Before Adding Logging
+
+- [ ] **Logger Import**: Import logger as `import { logger } from
+  '@/utils/logger'`
+- [ ] **Log Level Selection**: Determine appropriate log level
+  (debug/info/warn/error)
+- [ ] **Context Planning**: Plan what context information to include
+- [ ] **Sensitive Data Review**: Identify any sensitive data that needs redaction
+
+### During Logging Implementation
+
+- [ ] **Rest Parameters**: Use `logger.info(message, ...args)` format, not object
+  wrapping
+- [ ] **Context Addition**: Include relevant IDs, primitives, or small objects in
+  args
+- [ ] **Level Appropriateness**: Use correct log level for the situation
+- [ ] **Scoped Logger**: Use `logger.withContext(componentName)` for
+  component-specific logging
+
+### After Logging Implementation
+
+- [ ] **Console Check**: Ensure no `console.*` methods are used (unless in
+  allowed paths)
+- [ ] **Performance Review**: Verify logging doesn't impact performance
+- [ ] **DB Persistence**: Use `logger.toDb()` for database-only logging if needed
+- [ ] **Environment Compliance**: Respect `VITE_LOG_LEVEL` environment
+  variable