feat(monitoring): add logger service with log level filtering

.cursor/rules/ai-assistant-workflow.mdc

@@ -13,6 +13,7 @@ Guidelines for effective collaboration between developers and AI assistants on K
 ## Task Planning & Management
 
 ### Always Use Todo Lists
+
 For any non-trivial task (3+ steps), AI assistants should create and maintain a todo list:
 
 ```markdown
@@ -24,18 +25,21 @@ For any non-trivial task (3+ steps), AI assistants should create and maintain a
 ```
 
 ### Task Breakdown Patterns
+
 - **Feature Addition**: Research → Design → Implement → Test → Lint/Typecheck
 - **Bug Fix**: Reproduce → Identify → Fix → Test → Verify
 - **Refactoring**: Analyze → Plan → Execute → Test → Validate
 
 ## Code Understanding Workflow
 
 ### Before Making Changes
+
 1. **Search and understand** - Use search tools to understand existing patterns
 2. **Read related files** - Check imports, types, and similar components
 3. **Follow project conventions** - Match existing code style and architecture
 
 ### Research Commands
+
 ```bash
 # Find component patterns
 find src/components -name "*.tsx" | head -10
@@ -50,42 +54,65 @@ find . -name "*.spec.tsx" -path "*/components/*"
 ## Development Best Practices
 
 ### Component Development
+
 - **Check existing patterns** first (see `project-structure.mdc` for directory organization)
 - **Follow project conventions** and existing code style
 
 ### Testing Requirements
+
 - **Create unit tests** using patterns from `testing.mdc`
 - **Test both success and error scenarios**
 
+### Logger Usage
+
+- **Never use `console.*` directly** — use the `logger` service from `src/monitoring/logger` instead.
+  ```ts
+  import { logger } from '~/monitoring/logger';
+  logger.debug('message', { context }); // instead of console.log
+  logger.info('message', { context }); // instead of console.info
+  logger.warn('message', { context }); // instead of console.warn
+  logger.error('message', error, { context }); // instead of console.error
+  ```
+- When **modifying existing files** that contain `console.*` statements, replace them with the appropriate `logger` method.
+- When **creating new files**, always use `logger` for any logging needs.
+- **Do not** proactively search the codebase for `console.*` to replace — only update files you are already modifying as part of the current task.
+
 ### Code Quality Checks
+
 Always run lint and typecheck commands after code changes (see `package-management.mdc` for yarn commands).
 
 ## File Navigation & References
 
 ### Provide Line References
+
 When discussing code, always include file paths with line numbers:
+
 ```
 The error handling is in src/hooks/useApplications.ts:45
 ```
 
 ## Communication Patterns
 
 ### Progress Updates
+
 - Mark todos as `in_progress` when starting work
 - Mark todos as `completed` immediately after finishing
 - Update user on significant discoveries or blockers
 
 ### Code Explanations
+
 - Focus on **why** rather than **what**
 - Explain architectural decisions and trade-offs
 - Reference existing patterns and conventions
 
 ### Error Handling
+
 - Reproduce errors when possible
 - Check common issues: imports, types, missing dependencies
 - Provide specific file paths and line numbers for fixes
 
 ## Pull Request Checklist
+
 See [CONTRIBUTING.md#pull-request-checklist](../../CONTRIBUTING.md) for the full, up-to-date list.
 
 ## Common Commands

.gitignore

@@ -41,3 +41,6 @@ tsconfig.tsbuildinfo
 # Personal local claude settings
 .claude/*
 CLAUDE.local.md
+
+# Snyk Security Extension - AI Rules (auto-generated)
+.cursor/rules/snyk_rules.mdc

src/consts/log-levels.ts

@@ -0,0 +1,9 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/** Numeric severity values for each log level, used for level-based filtering */
+export const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};

src/monitoring/__tests__/logger.spec.ts

@@ -0,0 +1,237 @@
+import { mockConsole, MockConsole } from '~/unit-test-utils';
+
+const mockCaptureException = jest.fn();
+
+jest.mock('../index', () => ({
+  monitoringService: {
+    captureException: (...args: unknown[]) => mockCaptureException(...args),
+  },
+}));
+
+describe('logger', () => {
+  let consoleMock: MockConsole;
+
+  beforeEach(() => {
+    consoleMock = mockConsole();
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    consoleMock.restore();
+  });
+
+  describe('with default log level (debug in non-production)', () => {
+    // Default NODE_ENV in jest is 'test', so currentLevel = 'debug'
+    // Re-import logger for each describe block to capture env at module scope
+    let logger: typeof import('../logger').logger;
+
+    beforeEach(() => {
+      jest.isolateModules(() => {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        logger = require('../logger').logger;
+      });
+    });
+
+    describe('debug', () => {
+      it('should log with [DEBUG] prefix and context', () => {
+        const context = { key: 'value' };
+        logger.debug('test message', context);
+
+        expect(consoleMock.log).toHaveBeenCalledWith('[DEBUG] test message', context);
+      });
+
+      it('should log with empty string when context is not provided', () => {
+        logger.debug('test message');
+
+        expect(consoleMock.log).toHaveBeenCalledWith('[DEBUG] test message', '');
+      });
+    });
+
+    describe('info', () => {
+      it('should log with [INFO] prefix and context', () => {
+        const context = { user: 'admin' };
+        logger.info('info message', context);
+
+        expect(consoleMock.info).toHaveBeenCalledWith('[INFO] info message', context);
+      });
+
+      it('should log with empty string when context is not provided', () => {
+        logger.info('info message');
+
+        expect(consoleMock.info).toHaveBeenCalledWith('[INFO] info message', '');
+      });
+    });
+
+    describe('warn', () => {
+      it('should log with [WARN] prefix and context', () => {
+        const context = { severity: 'high' };
+        logger.warn('warning message', context);
+
+        expect(consoleMock.warn).toHaveBeenCalledWith('[WARN] warning message', context);
+      });
+
+      it('should log with empty string when context is not provided', () => {
+        logger.warn('warning message');
+
+        expect(consoleMock.warn).toHaveBeenCalledWith('[WARN] warning message', '');
+      });
+    });
+
+    describe('error', () => {
+      it('should log with [ERROR] prefix and call monitoringService.captureException', () => {
+        const error = new Error('boom');
+        const context = { action: 'submit' };
+        logger.error('error occurred', error, context);
+
+        expect(consoleMock.error).toHaveBeenCalledWith('[ERROR] error occurred', error, context);
+        expect(mockCaptureException).toHaveBeenCalledWith(error, context);
+      });
+
+      it('should handle missing error and context parameters', () => {
+        logger.error('error occurred');
+
+        expect(consoleMock.error).toHaveBeenCalledWith('[ERROR] error occurred', undefined, '');
+        expect(mockCaptureException).toHaveBeenCalledWith(undefined, undefined);
+      });
+
+      it('should handle error without context', () => {
+        const error = new Error('test');
+        logger.error('error occurred', error);
+
+        expect(consoleMock.error).toHaveBeenCalledWith('[ERROR] error occurred', error, '');
+        expect(mockCaptureException).toHaveBeenCalledWith(error, undefined);
+      });
+    });
+  });
+
+  describe('log level filtering', () => {
+    it('should not log debug messages in production environment', () => {
+      jest.isolateModules(() => {
+        process.env.NODE_ENV = 'production';
+        process.env.LOG_LEVEL = 'debug';
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const prodLogger = require('../logger').logger;
+        prodLogger.debug('should not appear');
+
+        expect(consoleMock.log).not.toHaveBeenCalled();
+        process.env.NODE_ENV = 'test';
+        delete process.env.LOG_LEVEL;
+      });
+    });
+
+    it('should suppress debug and info when LOG_LEVEL is warn', () => {
+      jest.isolateModules(() => {
+        process.env.LOG_LEVEL = 'warn';
+        delete process.env.NODE_ENV;
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const filteredLogger = require('../logger').logger;
+
+        filteredLogger.debug('should not appear');
+        filteredLogger.info('should not appear');
+        filteredLogger.warn('should appear');
+
+        expect(consoleMock.log).not.toHaveBeenCalled();
+        expect(consoleMock.info).not.toHaveBeenCalled();
+        expect(consoleMock.warn).toHaveBeenCalledWith('[WARN] should appear', '');
+
+        process.env.NODE_ENV = 'test';
+        delete process.env.LOG_LEVEL;
+      });
+    });
+
+    it('should only allow error when LOG_LEVEL is error', () => {
+      jest.isolateModules(() => {
+        process.env.LOG_LEVEL = 'error';
+        delete process.env.NODE_ENV;
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const filteredLogger = require('../logger').logger;
+
+        filteredLogger.debug('no');
+        filteredLogger.info('no');
+        filteredLogger.warn('no');
+        filteredLogger.error('yes');
+
+        expect(consoleMock.log).not.toHaveBeenCalled();
+        expect(consoleMock.info).not.toHaveBeenCalled();
+        expect(consoleMock.warn).not.toHaveBeenCalled();
+        expect(consoleMock.error).toHaveBeenCalledWith('[ERROR] yes', undefined, '');
+
+        process.env.NODE_ENV = 'test';
+        delete process.env.LOG_LEVEL;
+      });
+    });
+
+    it('should default to warn level in production when LOG_LEVEL is not set', () => {
+      jest.isolateModules(() => {
+        delete process.env.LOG_LEVEL;
+        process.env.NODE_ENV = 'production';
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const prodLogger = require('../logger').logger;
+
+        prodLogger.debug('no');
+        prodLogger.info('no');
+        prodLogger.warn('yes');
+
+        expect(consoleMock.log).not.toHaveBeenCalled();
+        expect(consoleMock.info).not.toHaveBeenCalled();
+        expect(consoleMock.warn).toHaveBeenCalledWith('[WARN] yes', '');
+
+        process.env.NODE_ENV = 'test';
+      });
+    });
+
+    it('should allow all levels when LOG_LEVEL is debug', () => {
+      jest.isolateModules(() => {
+        process.env.LOG_LEVEL = 'debug';
+        process.env.NODE_ENV = 'test';
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const debugLogger = require('../logger').logger;
+
+        debugLogger.debug('d');
+        debugLogger.info('i');
+        debugLogger.warn('w');
+        debugLogger.error('e');
+
+        expect(consoleMock.log).toHaveBeenCalledTimes(1);
+        expect(consoleMock.info).toHaveBeenCalledTimes(1);
+        expect(consoleMock.warn).toHaveBeenCalledTimes(1);
+        expect(consoleMock.error).toHaveBeenCalledTimes(1);
+
+        delete process.env.LOG_LEVEL;
+      });
+    });
+  });
+
+  describe('LOG_LEVELS export', () => {
+    it('should export correct numeric values for each log level', () => {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const { LOG_LEVELS } = require('../../consts/log-levels');
+
+      expect(LOG_LEVELS).toEqual({
+        debug: 0,
+        info: 1,
+        warn: 2,
+        error: 3,
+      });
+    });
+  });
+
+  describe('monitoringService integration', () => {
+    it('should not call monitoringService when error level is suppressed', () => {
+      jest.isolateModules(() => {
+        // There's no level higher than error that would suppress it,
+        // but we can verify it IS called when error level is active
+        process.env.LOG_LEVEL = 'error';
+        process.env.NODE_ENV = 'test';
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const errorLogger = require('../logger').logger;
+
+        errorLogger.error('critical', new Error('fail'));
+
+        expect(mockCaptureException).toHaveBeenCalledWith(new Error('fail'), undefined);
+
+        delete process.env.LOG_LEVEL;
+      });
+    });
+  });
+});

src/monitoring/logger.ts

@@ -0,0 +1,38 @@
+import { LOG_LEVELS, type LogLevel } from '../consts/log-levels';
+import { monitoringService } from './index';
+
+const currentLevel: LogLevel =
+  (process.env.LOG_LEVEL as LogLevel) || (process.env.NODE_ENV === 'production' ? 'warn' : 'debug');
+
+function shouldLog(level: LogLevel): boolean {
+  return LOG_LEVELS[level] >= LOG_LEVELS[currentLevel];
+}
+
+export const logger = {
+  debug(message: string, context?: Record<string, unknown>) {
+    if (!shouldLog('debug')) return;
+    if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line no-console
+      console.log(`[DEBUG] ${message}`, context ?? '');
+    }
+  },
+
+  info(message: string, context?: Record<string, unknown>) {
+    if (!shouldLog('info')) return;
+    // eslint-disable-next-line no-console
+    console.info(`[INFO] ${message}`, context ?? '');
+  },
+
+  warn(message: string, context?: Record<string, unknown>) {
+    if (!shouldLog('warn')) return;
+    // eslint-disable-next-line no-console
+    console.warn(`[WARN] ${message}`, context ?? '');
+  },
+
+  error(message: string, error?: Error, context?: Record<string, unknown>) {
+    if (!shouldLog('error')) return;
+    // eslint-disable-next-line no-console
+    console.error(`[ERROR] ${message}`, error, context ?? '');
+    monitoringService?.captureException(error, context);
+  },
+};