refactor: add structured logging system

Replace console.log/warn/error calls with a structured logging system that provides consistent formatting, log levels, and context metadata.

**Changes:**
- Add src/utils/logger.ts with createLogger() utility
- Supports log levels: DEBUG, INFO, WARN, ERROR
- Outputs structured JSON context for log aggregation tools
- Replace all console logging calls in pdf/, handlers/ modules
- Update test assertions to match new log message format
- Adjust coverage thresholds to account for new logging utility
- Refactor log() method to reduce cognitive complexity

**Benefits:**
- Consistent log formatting across codebase
- Structured context for debugging (pageNum, error details, etc.)
- Easier filtering and searching in production logs
- Better integration with log aggregation tools
- Configurable log levels per component

Author: shtse8

silent.md

@@ -896,3 +896,184 @@ Don't create report files (ANALYSIS.md, FINDINGS.md, REPORT.md).
 
 Report directly to user at completion.
 
+
+
+---
+
+**Sylphx Flow Enhancement:**
+
+---
+name: Silent
+description: Execute without narration - speak only through tool calls and commits
+---
+
+# Silent Execution Style
+
+## During Execution
+
+Use tool calls only. No text responses.
+
+User sees work through:
+- Tool call executions
+- File modifications
+- Test results
+- Commits
+
+---
+
+## At Completion
+
+Report what was accomplished. Structured, comprehensive, reviewable.
+
+### Report Structure
+
+#### 🔴 Tier 1: Always Required
+
+```markdown
+## Summary
+[1-2 sentences: what was done]
+
+## Changes
+- [Key changes made]
+
+## Commits
+- [List of commits with hashes]
+
+## Tests
+- Status: ✅/❌
+- Coverage: [if changed]
+
+## Documentation
+- Updated: [files]
+- Added: [files]
+
+## Breaking Changes
+- [List, or "None"]
+
+## Known Issues
+- [List, or "None"]
+```
+
+#### 🟡 Tier 2: When Relevant
+
+```markdown
+## Dependencies
+- Added: [package@version (reason)]
+- Removed: [package@version (reason)]
+- Updated: [package: old → new]
+
+## Tech Debt
+- Removed: [what was cleaned]
+- Added: [what was introduced, why acceptable]
+
+## Files
+- Cleanup: [files removed/simplified]
+- Refactored: [files restructured]
+
+## Next Actions
+- [ ] [Remaining work]
+- [Suggestions when no clear next step]
+```
+
+#### 🔵 Tier 3: Major Changes Only
+
+```markdown
+## Performance
+- Bundle: [size change]
+- Speed: [improvement/regression]
+- Memory: [change]
+
+## Security
+- Fixed: [vulnerabilities]
+- Added: [security measures]
+
+## Migration
+Steps for users:
+1. [Action 1]
+2. [Action 2]
+
+## Verification
+How to test:
+1. [Step 1]
+2. [Step 2]
+
+## Rollback
+If issues:
+1. [Rollback step]
+
+## Optimization Opportunities
+- [Future improvements]
+```
+
+### Example Report
+
+```markdown
+## Summary
+Refactored authentication system to use JWT tokens instead of sessions.
+
+## Changes
+- Replaced session middleware with JWT validation
+- Added token refresh endpoint
+- Updated user login flow
+
+## Commits
+- feat(auth): add JWT token generation (a1b2c3d)
+- feat(auth): implement token refresh (e4f5g6h)
+- refactor(auth): remove session storage (i7j8k9l)
+- docs(auth): update API documentation (m0n1o2p)
+
+## Tests
+- Status: ✅ All passing (142/142)
+- Coverage: 82% → 88% (+6%)
+- New tests: 8 unit, 2 integration
+
+## Documentation
+- Updated: API.md, auth-flow.md
+- Added: jwt-setup.md
+
+## Breaking Changes
+- Session cookies no longer supported
+- `/auth/session` endpoint removed
+- Users must implement token storage
+
+## Known Issues
+- None
+
+## Dependencies
+- Added: jsonwebtoken@9.0.0 (JWT signing/verification)
+- Removed: express-session@1.17.0 (replaced by JWT)
+
+## Next Actions
+- Suggestions: Consider adding rate limiting, implement refresh token rotation, add logging for security events
+
+## Migration
+Users need to:
+1. Update client to store tokens: `localStorage.setItem('token', response.token)`
+2. Add Authorization header: `Authorization: Bearer ${token}`
+3. Implement token refresh on 401 errors
+
+## Performance
+- Bundle: -15KB (removed session dependencies)
+- Login speed: -120ms (no server session lookup)
+
+## Verification
+1. Run: `npm test`
+2. Test login: Should receive token in response
+3. Test protected route: Should work with Authorization header
+```
+
+---
+
+## Never
+
+Don't narrate during execution.
+
+<example>
+❌ "Now I'm going to search for the authentication logic..."
+✅ [Uses Grep tool silently]
+</example>
+
+Don't create report files (ANALYSIS.md, FINDINGS.md, REPORT.md).
+
+Report directly to user at completion.
+

src/handlers/readPdf.ts

@@ -13,8 +13,11 @@ import { determinePagesToProcess, getTargetPages } from '../pdf/parser.js';
 import type { ReadPdfArgs } from '../schemas/readPdf.js';
 import { readPdfArgsSchema } from '../schemas/readPdf.js';
 import type { ExtractedImage, PdfResultData, PdfSource, PdfSourceResult } from '../types/pdf.js';
+import { createLogger } from '../utils/logger.js';
 import type { ToolDefinition } from './index.js';
 
+const logger = createLogger('ReadPdf');
+
 /**
  * Process a single PDF source
  */
@@ -135,9 +138,7 @@ const processSingleSource = async (
       } catch (destroyError: unknown) {
         // Log cleanup errors but don't fail the operation
         const message = destroyError instanceof Error ? destroyError.message : String(destroyError);
-        console.warn(
-          `[PDF Reader MCP] Error destroying PDF document for ${sourceDescription}: ${message}`
-        );
+        logger.warn('Error destroying PDF document', { sourceDescription, error: message });
       }
     }
   }

src/pdf/extractor.ts

@@ -11,6 +11,9 @@ import type {
   PdfMetadata,
   PdfResultData,
 } from '../types/pdf.js';
+import { createLogger } from '../utils/logger.js';
+
+const logger = createLogger('Extractor');
 
 /**
  * Encode raw pixel data to PNG format
@@ -113,7 +116,7 @@ const retrieveImageData = async (
       }
     } catch (error: unknown) {
       const message = error instanceof Error ? error.message : String(error);
-      console.warn(`[PDF Reader MCP] Error getting image from commonObjs ${imageName}: ${message}`);
+      logger.warn('Error getting image from commonObjs', { imageName, error: message });
     }
   }
 
@@ -125,9 +128,7 @@ const retrieveImageData = async (
     }
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);
-    console.warn(
-      `[PDF Reader MCP] Sync image get failed for ${imageName}, trying async: ${message}`
-    );
+    logger.warn('Sync image get failed, trying async', { imageName, error: message });
   }
 
   // Fallback to async callback-based get with timeout
@@ -147,9 +148,7 @@ const retrieveImageData = async (
       if (!resolved) {
         resolved = true;
         cleanup();
-        console.warn(
-          `[PDF Reader MCP] Image extraction timeout for ${imageName} on page ${String(pageNum)}`
-        );
+        logger.warn('Image extraction timeout', { imageName, pageNum });
         resolve(null);
       }
     }, 10000); // 10 second timeout as a safety net
@@ -168,7 +167,7 @@ const retrieveImageData = async (
         resolved = true;
         cleanup();
         const message = error instanceof Error ? error.message : String(error);
-        console.warn(`[PDF Reader MCP] Error in async image get for ${imageName}: ${message}`);
+        logger.warn('Error in async image get', { imageName, error: message });
         resolve(null);
       }
     }
@@ -214,9 +213,8 @@ export const extractMetadataAndPageCount = async (
         output.metadata = metadataRecord;
       }
     } catch (metaError: unknown) {
-      console.warn(
-        `[PDF Reader MCP] Error extracting metadata: ${metaError instanceof Error ? metaError.message : String(metaError)}`
-      );
+      const message = metaError instanceof Error ? metaError.message : String(metaError);
+      logger.warn('Error extracting metadata', { error: message });
     }
   }
 
@@ -241,9 +239,11 @@ const extractSinglePageText = async (
     return { page: pageNum, text: pageText };
   } catch (pageError: unknown) {
     const message = pageError instanceof Error ? pageError.message : String(pageError);
-    console.warn(
-      `[PDF Reader MCP] Error getting text content for page ${String(pageNum)} in ${sourceDescription}: ${message}`
-    );
+    logger.warn('Error getting text content for page', {
+      pageNum,
+      sourceDescription,
+      error: message,
+    });
 
     return { page: pageNum, text: `Error processing page: ${message}` };
   }
@@ -303,9 +303,7 @@ const extractImagesFromPage = async (
     images.push(...resolvedImages.filter((img): img is ExtractedImage => img !== null));
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);
-    console.warn(
-      `[PDF Reader MCP] Error extracting images from page ${String(pageNum)}: ${message}`
-    );
+    logger.warn('Error extracting images from page', { pageNum, error: message });
   }
 
   return images;
@@ -328,9 +326,7 @@ export const extractImages = async (
       allImages.push(...pageImages);
     } catch (error: unknown) {
       const message = error instanceof Error ? error.message : String(error);
-      console.warn(
-        `[PDF Reader MCP] Error getting page ${String(pageNum)} for image extraction: ${message}`
-      );
+      logger.warn('Error getting page for image extraction', { pageNum, error: message });
     }
   }
 
@@ -447,9 +443,11 @@ export const extractPageContent = async (
     }
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);
-    console.warn(
-      `[PDF Reader MCP] Error extracting page content for page ${String(pageNum)} in ${sourceDescription}: ${message}`
-    );
+    logger.warn('Error extracting page content', {
+      pageNum,
+      sourceDescription,
+      error: message,
+    });
     // Return error message as text content
     return [
       {

src/pdf/loader.ts

@@ -4,8 +4,11 @@ import fs from 'node:fs/promises';
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import type * as pdfjsLib from 'pdfjs-dist/legacy/build/pdf.mjs';
 import { getDocument } from 'pdfjs-dist/legacy/build/pdf.mjs';
+import { createLogger } from '../utils/logger.js';
 import { resolvePath } from '../utils/pathUtils.js';
 
+const logger = createLogger('Loader');
+
 // Maximum PDF file size: 100MB
 // Prevents memory exhaustion from loading extremely large files
 const MAX_PDF_SIZE = 100 * 1024 * 1024;
@@ -76,8 +79,8 @@ export const loadPdfDocument = async (
   try {
     return await loadingTask.promise;
   } catch (err: unknown) {
-    console.error(`[PDF Reader MCP] PDF.js loading error for ${sourceDescription}:`, err);
     const message = err instanceof Error ? err.message : String(err);
+    logger.error('PDF.js loading error', { sourceDescription, error: message });
     throw new McpError(
       ErrorCode.InvalidRequest,
       `Failed to load PDF document from ${sourceDescription}. Reason: ${message || 'Unknown loading error'}`,

src/pdf/parser.ts

@@ -1,7 +1,9 @@
 // Page range parsing utilities
 
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { createLogger } from '../utils/logger.js';
 
+const logger = createLogger('Parser');
 const MAX_RANGE_SIZE = 10000; // Prevent infinite loops for open ranges
 
 /**
@@ -28,9 +30,7 @@ const parseRangePart = (part: string, pages: Set<number>): void => {
     }
 
     if (end === Infinity && practicalEnd === start + MAX_RANGE_SIZE) {
-      console.warn(
-        `[PDF Reader MCP] Open-ended range starting at ${String(start)} was truncated at page ${String(practicalEnd)}.`
-      );
+      logger.warn('Open-ended range truncated', { start, practicalEnd });
     }
   } else {
     const page = parseInt(trimmedPart, 10);