---
alwaysApply: false
---

# Logging Migration — Patterns and Examples

> **Agent role**: Reference this file for specific migration patterns and
  examples when converting console.* calls to logger usage.

## 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)`

## Level Guidelines with Examples

### DEBUG Examples

```typescript

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 Examples

```typescript

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 Examples

```typescript

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 Examples

```typescript

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 Examples

### Component Context

```typescript

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]`.

### Emoji Guidelines

Recommended set for visual scanning:

- Start/finish: 🚀 / ✅

- Retry/loop: 🔄

- External call: 📡

- Data/metrics: 📊

- Inspection: 🔍

## Quick Before/After

### **Before**

```typescript

console.log('User signed in', user.id, meta);
console.error('Failed to update profile', err);
console.info('Filter toggled', this.hasVisibleDid);

```

### **After**

```typescript

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)

**See also**:
  `.cursor/rules/development/logging_standards.mdc` for the core standards and rules.

# Logging Migration — Patterns and Examples

> **Agent role**: Reference this file for specific migration patterns and
  examples when converting console.* calls to logger usage.

## 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)`

## Level Guidelines with Examples

### DEBUG Examples

```typescript

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 Examples

```typescript

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 Examples

```typescript

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 Examples

```typescript

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 Examples

### Component Context

```typescript

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]`.

### Emoji Guidelines

Recommended set for visual scanning:

- Start/finish: 🚀 / ✅

- Retry/loop: 🔄

- External call: 📡

- Data/metrics: 📊

- Inspection: 🔍

## Quick Before/After

### **Before**

```typescript

console.log('User signed in', user.id, meta);
console.error('Failed to update profile', err);
console.info('Filter toggled', this.hasVisibleDid);

```

### **After**

```typescript

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)

**See also**:
  `.cursor/rules/development/logging_standards.mdc` for the core standards and rules.

## Model Implementation Checklist

### Before Logging Migration

- [ ] **Code Review**: Identify all `console.*` calls in the codebase
- [ ] **Logger Import**: Verify logger utility is available and accessible
- [ ] **Context Planning**: Plan component context for each logging call
- [ ] **Level Assessment**: Determine appropriate log levels for each call

### During Logging Migration

- [ ] **Import Replacement**: Replace `console.*` with `logger.*` calls
- [ ] **Context Addition**: Add component context using scoped logger or prefix
- [ ] **Level Selection**: Choose appropriate log level (debug/info/warn/error)
- [ ] **Parameter Format**: Use rest-parameter call shape (`message, ...args`)

### After Logging Migration

- [ ] **Console Check**: Ensure no `console.*` methods remain (unless pragma'd)
- [ ] **Context Validation**: Verify all logging calls have proper context
- [ ] **Level Review**: Confirm log levels are appropriate for each situation
- [ ] **Testing**: Test logging functionality across all platforms