GMW/docs/superpowers/specs/2026-05-19-winston-logging-refactor-design.md

Winston Logging Refactor Design

Goal

Refactor project logging from Pino to Winston and clean up logging-related dependencies without changing application behavior.

Scope

• Replace pino and pino-pretty with winston.
• Remove pino-http if no code still uses it.
• Keep logging access centralized in src/logger.ts.
• Preserve current exported logger API shape where practical: logger and createChildLogger(context).
• Normalize log output and levels across the codebase.
• Avoid unrelated feature work or broad refactors.

Logging Architecture

src/logger.ts remains the only logging entry point. It will create one Winston logger with npm levels:

• error
• warn
• info
• http
• verbose
• debug
• silly

LOG_LEVEL validation will be updated to accept these Winston standard levels. Default behavior stays environment-aware: development can log more detail, production stays concise.

Outputs

Winston will write to:

1. Console
   • Pretty, colorized, timestamped output.
   • Includes logger context, message, and metadata.
2. logs/app.log
   • JSON format.
   • Includes all logs at configured level and above.
3. logs/error.log
   • JSON format.
   • Includes error-level logs only.

The logger should create the logs/ directory at runtime if needed. logs/ should be ignored by git.

Metadata and Error Handling

Existing log calls mostly remain valid. src/logger.ts will format metadata centrally so individual call sites do not need custom serialization.

Handled metadata shapes:

• { error: err }
• { err }
• { reason }
• extra plain objects used by existing log calls

Errors should serialize with message, stack, name, code, statusCode, and any relevant enumerable fields. Non-error metadata should pass through without lossy conversion.

Code Changes

Expected files:

• package.json and lockfile: add winston, remove Pino packages that become unused.
• src/logger.ts: rewrite from Pino to Winston.
• src/config.ts: expand LOG_LEVEL schema.
• .gitignore: ignore logs/ if missing.
• Logger call sites: update only if TypeScript or Winston format compatibility requires it.

Known logger consumers include:

• src/index.ts
• src/webserver.ts
• src/middleware.ts
• src/voiceController.ts
• src/media/mediaController.ts
• src/media/screenShareController.ts
• src/moderation/broadcaster.ts
• src/moderation/messageCapture.ts
• src/streaming/transcoder.ts

Additional consumers should be found by grep during implementation.

Dependency Cleanup

Remove packages only after confirming no imports remain:

• pino
• pino-pretty
• pino-http

Do not remove unrelated dependencies in this pass.

Testing and Verification

Run:

• pnpm install or equivalent lockfile update after dependency changes.
• pnpm run typecheck
• pnpm run test
• pnpm run lint

Also verify log behavior with a short runtime command or startup check:

• console output is readable and includes context.
• logs/app.log is created.
• logs/error.log is created when an error log occurs.

Success Criteria

• No Pino imports remain.
• Winston is the only logging backend.
• Existing application logging calls compile.
• Log levels are consistent and configurable via LOG_LEVEL.
• Console and file logging both work.
• Tests, typecheck, and lint pass.