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

Closes #149

## Summary

- Installs `winston-daily-rotate-file ^5.0.0` in `@hyveon/desktop-main`
and refactors `logger.ts` to a `createLogger(logDir)` factory that adds
a `DailyRotateFile` transport writing `main-YYYY-MM-DD.log` under a
caller-supplied directory (14-day retention, daily rotation at midnight)
- `main.ts` resolves `app.getPath('userData')` from Electron and calls
`createLogger(path.join(userData, 'logs'))` before `bootstrap()`,
ensuring log files land in the correct OS-specific user data directory
on every platform
- Adds `DiagnosticsService` (reads last N lines from today's log file,
ENOENT-safe) and `DiagnosticsController` (`GET /api/diagnostics/tail`,
`GET /api/diagnostics/path`) wired into `AppModule` with a
`DIAGNOSTICS_LOG_DIR` injection token
- Adds `DiagnosticsPanel` React component that fetches
`api.diagnosticsTail()` on mount, polls every 5 seconds, autoscrolls to
the bottom, and surfaces loading/error states; mounted in a new
"Diagnostics" section on `SettingsPage`

## Implementation notes

- The `logger.ts` singleton is exported as `export let logger` (ESM live
binding) so existing import sites (`LogsService`, etc.) receive the
updated instance after `main.ts` calls `createLogger` — no refactor of
call sites needed
- `winston-daily-rotate-file` v5.0.0 is CJS but importable from ESM
hosts in Node.js; v5 also ships bundled TypeScript declarations, so no
`@types/` package is required
- The `DIAGNOSTICS_LOG_DIR` AppModule provider uses `useFactory: () =>
path.join(electronApp.getPath('userData'), 'logs')` — this call is safe
because the factory only runs during Nest bootstrap, which `main.ts`
defers until after `createLogger` has already resolved the path
- The preload extension (`window.gsd.diagnostics`) was intentionally
omitted — the web layer uses the same HTTP `GET /api/*` pattern as every
other feature; no IPC bridge is needed
- `diagnosticsLogPath` is fetched once on mount only (stable across the
component lifetime); `diagnosticsTail` is re-fetched every 5 seconds

## Test plan

- [ ] `npm run app:test` — 525 tests pass (50 test files, 0 failures)
- [ ] `npm run app:lint` — 0 errors
- [ ] On macOS/Linux: packaged app writes `~/Library/Application
Support/<app>/logs/main-YYYY-MM-DD.log` (macOS) or
`~/.config/<app>/logs/...` (Linux)
- [ ] Settings → Diagnostics page shows last log lines and
auto-refreshes every 5 seconds

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: CoderCoco

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,6 @@
+import * as os from 'node:os';
+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 +12,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 +34,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'] ?? os.tmpdir();
+        }
+        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,68 @@
+import { describe, it, expect } 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', () => {
+  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 { 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.',
   );
 }
 
+const { app } = await import('electron') as unknown as { app: { getPath(name: string): string } };
+createLogger(path.join(app.getPath('userData'), 'logs'));
+
 async function bootstrap(): Promise<void> {
   const app = await NestFactory.createMicroservice<MicroserviceOptions>(AppModule, {
     strategy: new ElectronIPCTransport(),