Browse Source
- Remove conditional activeDid checks around $updateSettings calls in FeedFilters.vue - Call $updateSettings unconditionally, letting implementation handle missing activeDid - Maintain functional behavior while simplifying code structurepull/162/head
1 changed files with 138 additions and 0 deletions
@ -0,0 +1,138 @@ |
|||
# Agent Contract — TimeSafari Logging (Unified, MANDATORY) |
|||
|
|||
**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. |
|||
```ts |
|||
logger.debug('[HomeView] reloadFeedOnChange() called'); |
|||
logger.debug('[HomeView] Current filter settings', settings.filterFeedByVisible, settings.filterFeedByNearby, settings.searchBoxes?.length ?? 0); |
|||
logger.debug('[FeedFilters] Toggling nearby filter', this.isNearby, this.settingChanged, this.activeDid); |
|||
``` |
|||
**Avoid:** Vague messages (`'Processing data'`). |
|||
|
|||
### INFO |
|||
Use for user-visible lifecycle and completed operations. |
|||
```ts |
|||
logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM); |
|||
logger.info('[StartView] User selected new seed generation'); |
|||
logger.info('[SearchAreaView] Search box stored', searchBox.name, searchBox.bbox); |
|||
logger.info('[ContactQRScanShowView] Contact registration OK', contact.did); |
|||
``` |
|||
**Avoid:** Diagnostic details that belong in `debug`. |
|||
|
|||
### WARN |
|||
Use for recoverable issues, fallbacks, unexpected-but-handled conditions. |
|||
```ts |
|||
logger.warn('[ContactQRScanShowView] Invalid scan result – no value', resultType); |
|||
logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL'); |
|||
logger.warn('[ContactQRScanShowView] JWT missing "own" field'); |
|||
``` |
|||
**Avoid:** Hard failures (those are `error`). |
|||
|
|||
### ERROR |
|||
Use for unrecoverable failures, data integrity issues, and thrown exceptions. |
|||
```ts |
|||
logger.error('[HomeView Settings] initializeIdentity() failed', err); |
|||
logger.error('[StartView] Failed to load initialization data', error); |
|||
logger.error('[ContactQRScanShowView] Error processing contact QR', error, rawValue); |
|||
``` |
|||
**Avoid:** Expected user cancels (use `info`/`debug`). |
|||
|
|||
## Context Hygiene (Consistent, Minimal, Helpful) |
|||
- **Component context:** Prefer scoped logger. |
|||
```ts |
|||
const log = logger.withContext('UserService'); |
|||
log.info('User created', userId); |
|||
log.error('Failed to create user', error); |
|||
``` |
|||
If not using `withContext`, prefix message with `[ComponentName]`. |
|||
- **Emojis:** Optional and minimal for visual scanning. Recommended set: |
|||
- Start/finish: 🚀 / ✅ • Retry/loop: 🔄 • External call: 📡 • Data/metrics: 📊 • Inspection: 🔍 |
|||
- **Sensitive data:** Never log secrets (tokens, keys, passwords) or payloads >10KB. Prefer IDs over objects; redact/hash when needed. |
|||
|
|||
## Migration — Auto‑Rewrites (Apply Every Time) |
|||
- Exact transforms: |
|||
- `console.debug(...)` → `logger.debug(...)` |
|||
- `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when clearly stateful) |
|||
- `console.info(...)` → `logger.info(...)` |
|||
- `console.warn(...)` → `logger.warn(...)` |
|||
- `console.error(...)` → `logger.error(...)` |
|||
- Multi-arg handling: |
|||
- First arg becomes `message` (stringify safely if non-string). |
|||
- Remaining args map 1:1 to `...args`: |
|||
`console.info(msg, a, b)` → `logger.info(String(msg), a, b)` |
|||
- Sole `Error`: |
|||
- `console.error(err)` → `logger.error(err.message, err)` |
|||
- **Object-wrapping cleanup:** Replace `{{ userId, meta }}` wrappers with separate args: |
|||
`logger.info('User signed in', userId, meta)` |
|||
|
|||
## 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: |
|||
```ts |
|||
// cursor:allow-console reason="short justification" |
|||
console.log('temporary output'); |
|||
``` |
|||
Without the pragma, rewrite to `logger.*`. |
|||
|
|||
## 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). |
|||
|
|||
## Quick Before/After |
|||
**Before** |
|||
```ts |
|||
console.log('User signed in', user.id, meta); |
|||
console.error('Failed to update profile', err); |
|||
console.info('Filter toggled', this.hasVisibleDid); |
|||
``` |
|||
**After** |
|||
```ts |
|||
import {{ logger }} from '@/utils/logger'; |
|||
|
|||
logger.info('User signed in', user.id, meta); |
|||
logger.error('Failed to update profile', err); |
|||
logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid); |
|||
``` |
|||
|
|||
## Checklist (for every PR) |
|||
- [ ] No `console.*` (or properly pragma’d in the allowed locations) |
|||
- [ ] Correct import path for `logger` |
|||
- [ ] Rest-parameter call shape (`message, ...args`) |
|||
- [ ] Right level chosen (debug/info/warn/error) |
|||
- [ ] No secrets / oversized payloads / throwaway context objects |
|||
- [ ] Component context provided (scoped logger or `[Component]` prefix) |
|||
|
|||
_Unified on: 2025-08-15 08:11:46Z_ |
Loading…
Reference in new issue