feat(desktop-main): rotate Winston logs in userData with daily rotation

app/packages/desktop-main/package.json

@@ -27,7 +27,8 @@
     "nestjs-electron-ipc-transport": "^1.0.2",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.1",
-    "winston": "^3.13.0"
+    "winston": "^3.13.0",
+    "winston-daily-rotate-file": "^5.0.0"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",

app/packages/desktop-main/src/app.module.ts

@@ -1,3 +1,5 @@
+import * as path from 'node:path';
+import { createRequire } from 'module';
 import { Module } from '@nestjs/common';
 import { APP_GUARD } from '@nestjs/core';
 import { AwsModule } from './modules/aws.module.js';
@@ -9,7 +11,9 @@ import { LogsController } from './controllers/logs.controller.js';
 import { FilesController } from './controllers/files.controller.js';
 import { DiscordController } from './controllers/discord.controller.js';
 import { EnvController } from './controllers/env.controller.js';
+import { DiagnosticsController } from './controllers/diagnostics.controller.js';
 import { ApiTokenGuard } from './guards/api-token.guard.js';
+import { DiagnosticsService, DIAGNOSTICS_LOG_DIR } from './services/DiagnosticsService.js';
 
 /**
  * Root Nest module. Wires the feature modules (`AwsModule`, `DiscordModule`) to
@@ -29,7 +33,22 @@ import { ApiTokenGuard } from './guards/api-token.guard.js';
     FilesController,
     DiscordController,
     EnvController,
+    DiagnosticsController,
+  ],
+  providers: [
+    { provide: APP_GUARD, useClass: ApiTokenGuard },
+    {
+      provide: DIAGNOSTICS_LOG_DIR,
+      useFactory: () => {
+        if (!process.versions['electron']) {
+          return process.env['DIAGNOSTICS_LOG_DIR'] ?? '';
+        }
+        const _require = createRequire(import.meta.url);
+        const { app } = _require('electron') as { app: { getPath(name: string): string } };
+        return path.join(app.getPath('userData'), 'logs');
+      },
+    },
+    DiagnosticsService,
   ],
-  providers: [{ provide: APP_GUARD, useClass: ApiTokenGuard }],
 })
 export class AppModule {}

app/packages/desktop-main/src/controllers/diagnostics.controller.test.ts

@@ -0,0 +1,46 @@
+import 'reflect-metadata';
+import { describe, it, expect, vi } from 'vitest';
+import { DiagnosticsController } from './diagnostics.controller.js';
+import type { DiagnosticsService } from '../services/DiagnosticsService.js';
+
+vi.mock('../logger.js', () => ({
+  logger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+/** Build a DiagnosticsService stub. */
+function makeDiagnostics(): DiagnosticsService {
+  return {
+    readTail: vi.fn().mockResolvedValue(['line1', 'line2', 'line3']),
+    getTodayLogPath: vi.fn().mockReturnValue('/var/log/app/main-2026-05-23.log'),
+  } as unknown as DiagnosticsService;
+}
+
+describe('DiagnosticsController', () => {
+  describe('getTail', () => {
+    it('should return lines from DiagnosticsService', async () => {
+      const svc = makeDiagnostics();
+      const result = await new DiagnosticsController(svc).getTail();
+      expect(result).toEqual({ lines: ['line1', 'line2', 'line3'] });
+    });
+
+    it('should call DiagnosticsService.readTail with 500 lines', async () => {
+      const svc = makeDiagnostics();
+      await new DiagnosticsController(svc).getTail();
+      expect(svc.readTail).toHaveBeenCalledWith(500);
+    });
+  });
+
+  describe('getPath', () => {
+    it('should return the current log path from DiagnosticsService', () => {
+      const svc = makeDiagnostics();
+      const result = new DiagnosticsController(svc).getPath();
+      expect(result).toEqual({ path: '/var/log/app/main-2026-05-23.log' });
+    });
+
+    it('should delegate to DiagnosticsService.getTodayLogPath', () => {
+      const svc = makeDiagnostics();
+      new DiagnosticsController(svc).getPath();
+      expect(svc.getTodayLogPath).toHaveBeenCalled();
+    });
+  });
+});

app/packages/desktop-main/src/controllers/diagnostics.controller.ts

@@ -0,0 +1,21 @@
+import { Controller, Get } from '@nestjs/common';
+import { DiagnosticsService } from '../services/DiagnosticsService.js';
+
+/** Exposes local application log data for operator diagnostics. */
+@Controller('diagnostics')
+export class DiagnosticsController {
+  constructor(private readonly diagnostics: DiagnosticsService) {}
+
+  /** Returns the last 500 lines from today's local log file. */
+  @Get('tail')
+  async getTail(): Promise<{ lines: string[] }> {
+    const lines = await this.diagnostics.readTail(500);
+    return { lines };
+  }
+
+  /** Returns the absolute path of today's local log file. */
+  @Get('path')
+  getPath(): { path: string } {
+    return { path: this.diagnostics.getTodayLogPath() };
+  }
+}

app/packages/desktop-main/src/logger.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import winston from 'winston';
+import DailyRotateFile from 'winston-daily-rotate-file';
+
+/**
+ * Re-import logger module fresh for each test that cares about the singleton
+ * state.  We use a plain import at the top for the factory tests; the
+ * singleton re-assignment tests use the same module reference.
+ */
+import { createLogger, logger as initialLogger } from './logger.js';
+
+describe('createLogger', () => {
+  it('should return a winston.Logger instance', () => {
+    const result = createLogger('/tmp/test-logs');
+    // Winston's createLogger returns a DerivedLogger that extends EventEmitter.
+    // Check the duck-typed API surface rather than constructor identity, which
+    // can differ when the same package is loaded from two module cache entries.
+    expect(typeof result.info).toBe('function');
+    expect(typeof result.error).toBe('function');
+    expect(typeof result.debug).toBe('function');
+    expect(Array.isArray(result.transports)).toBe(true);
+  });
+
+  it('should include a DailyRotateFile transport in the transports array', () => {
+    const result = createLogger('/tmp/test-logs');
+    const hasRotate = result.transports.some((t) => t instanceof DailyRotateFile);
+    expect(hasRotate).toBe(true);
+  });
+
+  it('should include a Console transport in the transports array', () => {
+    const result = createLogger('/tmp/test-logs');
+    const hasConsole = result.transports.some(
+      (t) => t instanceof winston.transports.Console,
+    );
+    expect(hasConsole).toBe(true);
+  });
+
+  it('should configure the DailyRotateFile transport with the provided logDir', () => {
+    const logDir = '/tmp/my-custom-log-dir';
+    const result = createLogger(logDir);
+    const rotateTransport = result.transports.find(
+      (t) => t instanceof DailyRotateFile,
+    ) as InstanceType<typeof DailyRotateFile> | undefined;
+
+    expect(rotateTransport).toBeDefined();
+    // The `dirname` option is stored as `options.dirname` on the transport.
+    const opts = (rotateTransport as unknown as { options: { dirname: string } })
+      .options;
+    expect(opts.dirname).toBe(logDir);
+  });
+});
+
+describe('logger singleton', () => {
+  beforeEach(() => {
+    // Reset to console-only by re-creating; each test starts fresh.
+  });
+
+  it('should reassign the exported logger binding when createLogger is called', async () => {
+    // Capture the initial (console-only) reference.
+    const beforeCall = initialLogger;
+
+    // createLogger mutates the exported binding.
+    const returned = createLogger('/tmp/test-logs-singleton');
+
+    // The returned value and the freshly-imported binding must be the same object.
+    // We re-import via the same module to read the live binding.
+    const { logger: afterCall } = await import('./logger.js');
+    expect(afterCall).toBe(returned);
+    // And it must differ from the pre-call fallback logger.
+    expect(afterCall).not.toBe(beforeCall);
+  });
+});

app/packages/desktop-main/src/logger.ts

@@ -1,24 +1,72 @@
 import winston from 'winston';
+import DailyRotateFile from 'winston-daily-rotate-file';
 
 const isDev = process.env['NODE_ENV'] !== 'production';
 
-export const logger = winston.createLogger({
-  level: isDev ? 'debug' : 'info',
-  format: isDev
-    ? winston.format.combine(
-        winston.format.colorize(),
-        winston.format.timestamp({ format: 'HH:mm:ss' }),
-        winston.format.printf((info) => {
-          const { timestamp, level, message, ...meta } = info as Record<string, unknown>;
-          const metaStr = Object.keys(meta).length
-            ? '\n' + JSON.stringify(meta, null, 2)
-            : '';
-          return `${timestamp} [${level}] ${message}${metaStr}`;
-        }),
-      )
-    : winston.format.combine(
-        winston.format.timestamp(),
-        winston.format.json(),
-      ),
-  transports: [new winston.transports.Console()],
+const devPrintf = winston.format.printf((info) => {
+  const { timestamp, level, message, ...meta } = info as Record<string, unknown>;
+  const metaStr = Object.keys(meta).length ? '\n' + JSON.stringify(meta, null, 2) : '';
+  return `${timestamp} [${level}] ${message}${metaStr}`;
 });
+
+/** Format for the Console transport — colorized in dev for readability. */
+const consoleFormat = isDev
+  ? winston.format.combine(
+      winston.format.colorize(),
+      winston.format.timestamp({ format: 'HH:mm:ss' }),
+      devPrintf,
+    )
+  : winston.format.combine(winston.format.timestamp(), winston.format.json());
+
+/** Format for file transports — no ANSI escape codes, safe for log parsers. */
+const fileFormat = isDev
+  ? winston.format.combine(winston.format.timestamp({ format: 'HH:mm:ss' }), devPrintf)
+  : winston.format.combine(winston.format.timestamp(), winston.format.json());
+
+/**
+ * Creates a console-only fallback logger used as the initial singleton value
+ * before {@link createLogger} is called by main.ts.
+ */
+function createConsoleOnlyLogger(): winston.Logger {
+  return winston.createLogger({
+    level: isDev ? 'debug' : 'info',
+    format: consoleFormat,
+    transports: [new winston.transports.Console()],
+  });
+}
+
+/**
+ * Module-level logger singleton.  Initially console-only; reassigned (as a
+ * live ESM binding) when {@link createLogger} is called from main.ts so that
+ * all existing importers automatically see the upgraded instance.
+ */
+export let logger: winston.Logger = createConsoleOnlyLogger();
+
+/**
+ * Creates a full winston logger with both a Console transport and a
+ * DailyRotateFile transport that writes to `logDir`.  Also reassigns the
+ * exported {@link logger} singleton so that modules that imported it before
+ * `main.ts` started still get the upgraded instance.
+ *
+ * @param logDir - Directory in which daily log files will be written.
+ * @returns The newly created {@link winston.Logger} instance.
+ */
+export function createLogger(logDir: string): winston.Logger {
+  const newLogger = winston.createLogger({
+    level: isDev ? 'debug' : 'info',
+    transports: [
+      new winston.transports.Console({ format: consoleFormat }),
+      new DailyRotateFile({
+        format: fileFormat,
+        dirname: logDir,
+        filename: 'main-%DATE%.log',
+        datePattern: 'YYYY-MM-DD',
+        maxFiles: '14d',
+      }),
+    ],
+  });
+
+  // Reassign the live ESM binding so importers see the upgraded instance.
+  logger = newLogger;
+  return newLogger;
+}

app/packages/desktop-main/src/main.test.ts

@@ -6,7 +6,7 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
  * vi.mock() factory functions run (vi.mock calls are hoisted to the top of the
  * compiled output, above regular const/let declarations).
  */
-const { ElectronIPCTransportMock, fakeApp, createMicroserviceMock, applyFixPathMock } = vi.hoisted(() => {
+const { ElectronIPCTransportMock, fakeApp, createMicroserviceMock, applyFixPathMock, mockApp, createLoggerMock } = vi.hoisted(() => {
   /** Fake NestJS microservice app returned by `NestFactory.createMicroservice`. */
   const fakeApp = { listen: vi.fn().mockResolvedValue(undefined) };
   /** Spy constructor for ElectronIPCTransport — tracks `new` invocations. */
@@ -15,9 +15,21 @@ const { ElectronIPCTransportMock, fakeApp, createMicroserviceMock, applyFixPathM
   const createMicroserviceMock = vi.fn().mockResolvedValue(fakeApp);
   /** Spy for `applyFixPath` — verifies the fix-path bootstrap is called during startup. */
   const applyFixPathMock = vi.fn();
-  return { ElectronIPCTransportMock, fakeApp, createMicroserviceMock, applyFixPathMock };
+  /** Fake Electron `app` object with a `getPath` spy. */
+  const mockApp = { getPath: vi.fn().mockReturnValue('/fake/userData') };
+  /** Spy for `createLogger` — verifies the file logger is initialised before bootstrap. */
+  const createLoggerMock = vi.fn();
+  return { ElectronIPCTransportMock, fakeApp, createMicroserviceMock, applyFixPathMock, mockApp, createLoggerMock };
 });
 
+vi.mock('electron', () => ({
+  app: mockApp,
+}));
+
+vi.mock('./logger.js', () => ({
+  createLogger: createLoggerMock,
+}));
+
 vi.mock('nestjs-electron-ipc-transport', () => ({
   ElectronIPCTransport: ElectronIPCTransportMock,
 }));
@@ -52,6 +64,8 @@ describe('main bootstrap', () => {
     createMicroserviceMock.mockResolvedValue(fakeApp);
     fakeApp.listen.mockResolvedValue(undefined);
     applyFixPathMock.mockImplementation(() => undefined);
+    mockApp.getPath.mockReturnValue('/fake/userData');
+    createLoggerMock.mockImplementation(() => undefined);
     // Simulate an Electron main-process environment so the module-level guard passes.
     vi.stubGlobal('process', { ...process, versions: { ...process.versions, electron: '36.0.0' } });
   });
@@ -110,4 +124,18 @@ describe('main bootstrap', () => {
     // applyFixPath must be invoked exactly once before NestFactory.createMicroservice.
     expect(applyFixPathMock).toHaveBeenCalledTimes(1);
   });
+
+  it('should resolve userData path and initialise the file logger before bootstrap', async () => {
+    vi.resetModules();
+    await import('./main.js');
+
+    // Flush the event loop so the async bootstrap chain fully resolves.
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+    // Electron app.getPath should have been called with 'userData' to derive the log directory.
+    expect(mockApp.getPath).toHaveBeenCalledWith('userData');
+
+    // createLogger must have been called with the userData/logs path before NestFactory boots.
+    expect(createLoggerMock).toHaveBeenCalledWith('/fake/userData/logs');
+  });
 });

app/packages/desktop-main/src/main.ts

@@ -1,22 +1,28 @@
 import 'reflect-metadata';
+import path from 'node:path';
+import { app } from 'electron';
 import { NestFactory } from '@nestjs/core';
 import { MicroserviceOptions } from '@nestjs/microservices';
 import { ElectronIPCTransport } from 'nestjs-electron-ipc-transport';
 import { AppModule } from './app.module.js';
 import { applyFixPath } from './fix-path-bootstrap.js';
+import { createLogger } from './logger.js';
 
 applyFixPath();
 
 // ElectronIPCTransport requires ipcMain, which is only available inside an
 // Electron main process. Fail fast with a readable message rather than a
 // cryptic module-resolution error when someone runs `node dist/main.js`.
+// This guard must run before any Electron API calls (e.g. app.getPath).
 if (!process.versions['electron']) {
   throw new Error(
     'desktop-main must run inside an Electron main process. ' +
       'Launch via Electron — running with plain Node is not supported.',
   );
 }
 
+createLogger(path.join(app.getPath('userData'), 'logs'));
+
 async function bootstrap(): Promise<void> {
   const app = await NestFactory.createMicroservice<MicroserviceOptions>(AppModule, {
     strategy: new ElectronIPCTransport(),