@lenne.tech/nest-server 11.31.2 → 11.32.0

package/src/core/modules/hub/services/core-hub-migrations.service.ts

@@ -0,0 +1,112 @@
+import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
+import { InjectConnection } from '@nestjs/mongoose';
+import { readdir } from 'fs/promises';
+import { Connection } from 'mongoose';
+import { resolve } from 'path';
+
+import { ConfigService } from '../../../common/services/config.service';
+import { DEFAULT_MIGRATION_FILE_PATTERN, MigrationRunner } from '../../migrate/migration-runner';
+import { MongoStateStore } from '../../migrate/mongo-state-store';
+import { HubActionMessage } from '../hub-action-messages';
+import { HUB_CONFIG } from '../hub.constants';
+import { HubMigrationsData, HubUnavailable } from '../interfaces/hub-panels.interface';
+import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+
+/**
+ * Reads migration status for the Migrations panel.
+ *
+ * Status is read from the migration-state collection directly (works without a configured runner);
+ * pending migrations are detected by diffing the completed set against the migrations directory
+ * listing. The `up()`/`down()` actions (Phase 7) instantiate a `MigrationRunner` on demand.
+ */
+@Injectable()
+export class CoreHubMigrationsService {
+  protected readonly logger = new Logger(CoreHubMigrationsService.name);
+
+  constructor(
+    @Inject(HUB_CONFIG) protected readonly config: ResolvedHubConfig,
+    protected readonly configService: ConfigService,
+    @Optional() @InjectConnection() protected readonly connection?: Connection,
+  ) {}
+
+  /** Run all pending migrations. Returns the titles that were applied. */
+  async runPending(): Promise<{ ran: string[] }> {
+    const runner = this.buildRunner();
+    const before = new Set(((await this.getStatus()) as HubMigrationsData).completed ?? []);
+    await runner.up();
+    const after = ((await this.getStatus()) as HubMigrationsData).completed ?? [];
+    return { ran: after.filter((title) => !before.has(title)) };
+  }
+
+  /** Roll back the most recently applied migration. Returns the title that was reverted. */
+  async rollbackLast(): Promise<{ rolledBack?: string }> {
+    const before = ((await this.getStatus()) as HubMigrationsData).completed ?? [];
+    const runner = this.buildRunner();
+    await runner.down();
+    const after = new Set(((await this.getStatus()) as HubMigrationsData).completed ?? []);
+    return { rolledBack: before.find((title) => !after.has(title)) };
+  }
+
+  /** Build a MigrationRunner from the hub config + the configured Mongo URI. */
+  protected buildRunner(): MigrationRunner {
+    if (this.config.migrations === false) {
+      throw new Error(HubActionMessage.migrationsDisabled);
+    }
+    const uri = this.configService.getFastButReadOnly<string>('mongoose.uri');
+    if (!uri) {
+      throw new Error(HubActionMessage.mongoUriMissing);
+    }
+    return new MigrationRunner({
+      migrationsDirectory: resolve(process.cwd(), this.config.migrations.dir),
+      stateStore: new MongoStateStore({
+        collectionName: this.config.migrations.collectionName,
+        lockCollectionName: this.config.migrations.lockCollectionName,
+        uri,
+      }),
+    });
+  }
+
+  /** Completed + pending migrations. */
+  async getStatus(): Promise<HubMigrationsData | HubUnavailable> {
+    if (this.config.migrations === false) {
+      return { available: false, hint: 'The migrations panel is disabled.' };
+    }
+    const db = this.connection?.db;
+    if (!db) {
+      return { available: false, hint: 'No MongoDB connection is available.' };
+    }
+
+    const collectionName = this.config.migrations.collectionName;
+    let completed: string[] = [];
+    let lastRun: string | undefined;
+
+    try {
+      const [stateDoc] = await db.collection(collectionName).find({}).limit(1).toArray();
+      completed = (stateDoc?.migrations ?? []).map((m: { title: string }) => m.title);
+      lastRun = stateDoc?.lastRun;
+    } catch (error) {
+      this.logger.warn(`Failed to read migration state: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    const { dirAvailable, files } = await this.listMigrationFiles();
+    const pending = dirAvailable ? files.filter((f) => !completed.includes(f)) : [];
+
+    return { completed, dirAvailable, lastRun, pending, source: 'collection' };
+  }
+
+  /** List migration file titles from the configured directory (empty when the dir is missing). */
+  protected async listMigrationFiles(): Promise<{ dirAvailable: boolean; files: string[] }> {
+    if (this.config.migrations === false) {
+      return { dirAvailable: false, files: [] };
+    }
+    const dir = resolve(process.cwd(), this.config.migrations.dir);
+    try {
+      // A missing or unreadable directory rejects here (ENOENT) → treated as "no dir available".
+      const entries = await readdir(dir);
+      const files = entries.filter((file) => DEFAULT_MIGRATION_FILE_PATTERN.test(file)).sort();
+      return { dirAvailable: true, files };
+    } catch {
+      return { dirAvailable: false, files: [] };
+    }
+  }
+}

package/src/core/modules/hub/services/core-hub-sources.service.ts

@@ -0,0 +1,194 @@
+import { Injectable, Logger, Optional } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { SchedulerRegistry } from '@nestjs/schedule';
+
+import { CoreAiInteractionService } from '../../ai/services/core-ai-interaction.service';
+import { CoreBetterAuthUserMapper } from '../../better-auth/core-better-auth-user.mapper';
+import { CoreErrorCodeService } from '../../error-code/core-error-code.service';
+import { CorePermissionsService } from '../../permissions/core-permissions.service';
+import { HubCronData, HubErrorCodesData, HubUnavailable } from '../interfaces/hub-panels.interface';
+
+/**
+ * Single choke point for the Hub's OPTIONAL data sources.
+ *
+ * Providers that live in non-global modules (error-code, better-auth, ai, permissions) cannot be
+ * `@Optional() @Inject()`-ed — that would always resolve to `undefined` even when the module exists.
+ * Instead they are resolved lazily via `ModuleRef.get(Token, { strict: false })` inside method bodies
+ * (call time — SWC/TDZ-safe), cached after the first hit, and every panel degrades to
+ * `{ available: false }` when its source is absent. `SchedulerRegistry` IS global, so it is injected
+ * normally.
+ */
+@Injectable()
+export class CoreHubSourcesService {
+  protected readonly logger = new Logger(CoreHubSourcesService.name);
+  private readonly resolveCache = new Map<unknown, unknown>();
+
+  constructor(
+    protected readonly moduleRef: ModuleRef,
+    @Optional() protected readonly schedulerRegistry?: SchedulerRegistry,
+  ) {}
+
+  /** AI availability + a light interaction/usage summary. */
+  async getAi(): Promise<HubUnavailable | { available: true; totalInteractions: number }> {
+    const interactionService = this.resolve<CoreAiInteractionService>(CoreAiInteractionService);
+    if (!interactionService) {
+      return { available: false, hint: 'The AI module is not enabled.' };
+    }
+    try {
+      const model = (interactionService as unknown as { mainDbModel?: { estimatedDocumentCount(): Promise<number> } })
+        .mainDbModel;
+      const totalInteractions = model ? await model.estimatedDocumentCount() : 0;
+      return { available: true, totalInteractions };
+    } catch (error) {
+      this.logger.warn(`Failed to read AI interactions: ${error instanceof Error ? error.message : String(error)}`);
+      return { available: true, totalInteractions: 0 };
+    }
+  }
+
+  /** Legacy → IAM auth migration status. */
+  async getAuthMigration(): Promise<HubUnavailable | Record<string, unknown>> {
+    const mapper = this.resolve<CoreBetterAuthUserMapper>(CoreBetterAuthUserMapper);
+    if (!mapper) {
+      return { available: false, hint: 'BetterAuth is not enabled.' };
+    }
+    try {
+      return { available: true, ...(await mapper.getMigrationStatus()) };
+    } catch (error) {
+      this.logger.warn(
+        `Failed to read auth migration status: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return { available: false, hint: 'Failed to read auth migration status.' };
+    }
+  }
+
+  /** Registered cron jobs, intervals and timeouts (via `@nestjs/schedule`). */
+  getCron(): HubCronData | HubUnavailable {
+    if (!this.schedulerRegistry) {
+      return { available: false, hint: 'ScheduleModule.forRoot() is not imported.' };
+    }
+    try {
+      const jobs = [];
+      for (const [name, job] of this.schedulerRegistry.getCronJobs()) {
+        let nextDate: string | undefined;
+        let lastDate: string | undefined;
+        try {
+          nextDate = job.nextDate?.()?.toISO?.() ?? undefined;
+        } catch {
+          /* a job may throw before first run */
+        }
+        try {
+          lastDate = job.lastDate?.()?.toISOString?.() ?? undefined;
+        } catch {
+          /* no last run yet */
+        }
+        jobs.push({ lastDate, name, nextDate, running: Boolean((job as unknown as { running?: boolean }).running) });
+      }
+      return {
+        intervals: [...this.schedulerRegistry.getIntervals()],
+        jobs,
+        timeouts: [...this.schedulerRegistry.getTimeouts()],
+      };
+    } catch (error) {
+      this.logger.warn(`Failed to read scheduler registry: ${error instanceof Error ? error.message : String(error)}`);
+      return { available: false, hint: 'Failed to read scheduled jobs.' };
+    }
+  }
+
+  /** True when BetterAuth (IAM) is actually wired in — used by the dashboard feature matrix. */
+  isBetterAuthActive(): boolean {
+    return !!this.resolve(CoreBetterAuthUserMapper);
+  }
+
+  /**
+   * Whether each optional/degradable panel's backing source is actually present. Fed into the session
+   * payload so the client can grey out and DISABLE nav entries whose module is absent, instead of
+   * letting the user click through to an "unavailable" panel. Panels not listed here are always
+   * available (their data is intrinsic to the Hub).
+   */
+  getPanelAvailability(): Record<string, boolean> {
+    return {
+      ai: !!this.resolve(CoreAiInteractionService),
+      'auth-migration': !!this.resolve(CoreBetterAuthUserMapper),
+      cron: !!this.schedulerRegistry,
+      'error-codes': !!this.resolve(CoreErrorCodeService),
+      routes: !!this.resolve(CorePermissionsService),
+    };
+  }
+
+  /** Control a cron job by name (start | stop | trigger). Throws when scheduling is unavailable. */
+  controlCron(name: string, action: 'start' | 'stop' | 'trigger'): void {
+    if (!this.schedulerRegistry) {
+      throw new Error('ScheduleModule.forRoot() is not imported.');
+    }
+    const job = this.schedulerRegistry.getCronJob(name);
+    if (action === 'start') {
+      job.start();
+    } else if (action === 'stop') {
+      job.stop();
+    } else {
+      // Fire the job's callback once now.
+      const fire = (job as unknown as { fireOnTick?: () => void }).fireOnTick;
+      if (typeof fire === 'function') {
+        fire.call(job);
+      }
+    }
+  }
+
+  /** Error-code catalog with de/en translations. */
+  getErrorCodes(locale = 'en'): HubErrorCodesData | HubUnavailable {
+    const service = this.resolve<CoreErrorCodeService>(CoreErrorCodeService);
+    if (!service) {
+      return { available: false, hint: 'The error-code module is not enabled.' };
+    }
+    try {
+      const codes = service.getErrorCodes();
+      const de = this.safeTranslations(service, 'de');
+      const en = this.safeTranslations(service, 'en');
+      return {
+        codes: codes.map((code) => ({ code, de: de[code], en: en[code] })),
+        locale,
+      };
+    } catch (error) {
+      this.logger.warn(`Failed to read error codes: ${error instanceof Error ? error.message : String(error)}`);
+      return { available: false, hint: 'Failed to read error codes.' };
+    }
+  }
+
+  /** The permissions report (modules + coverage stats), reusing the permissions module's cached scan. */
+  async getRoutes(): Promise<HubUnavailable | { modules: unknown[]; stats: unknown; warnings: unknown[] }> {
+    const service = this.resolve<CorePermissionsService>(CorePermissionsService);
+    if (!service) {
+      return { available: false, hint: 'The permissions module is not enabled — see /permissions.' };
+    }
+    try {
+      const report = service.getReport() ?? (await service.getOrScan());
+      return { modules: report.modules ?? [], stats: report.stats, warnings: report.warnings ?? [] };
+    } catch (error) {
+      this.logger.warn(`Failed to read routes report: ${error instanceof Error ? error.message : String(error)}`);
+      return { available: false, hint: 'Failed to read routes report.' };
+    }
+  }
+
+  /** Resolve an optional provider once, container-wide, and cache the result (including a miss). */
+  protected resolve<T>(token: unknown): T | undefined {
+    if (this.resolveCache.has(token)) {
+      return this.resolveCache.get(token) as T | undefined;
+    }
+    let instance: T | undefined;
+    try {
+      instance = this.moduleRef.get<T>(token as never, { strict: false });
+    } catch {
+      instance = undefined;
+    }
+    this.resolveCache.set(token, instance);
+    return instance;
+  }
+
+  private safeTranslations(service: CoreErrorCodeService, locale: string): Record<string, string> {
+    try {
+      return service.getTranslations(locale as never).errors;
+    } catch {
+      return {};
+    }
+  }
+}

package/src/core/modules/hub/services/hub-log-buffer.service.ts

@@ -0,0 +1,252 @@
+import {
+  ConsoleLogger,
+  Inject,
+  Injectable,
+  Logger,
+  LoggerService,
+  LogLevel,
+  OnModuleDestroy,
+  OnModuleInit,
+} from '@nestjs/common';
+import { inspect } from 'util';
+
+import { redactSensitiveText } from '../../../common/helpers/logging.helper';
+import { HUB_CONFIG } from '../hub.constants';
+import { HubRingBuffer } from '../hub-ring-buffer';
+import { HubLogRecord, HubLogsData } from '../interfaces/hub-panels.interface';
+import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+
+interface BufferedLog extends HubLogRecord {
+  timestamp: number;
+}
+
+/**
+ * A LoggerService that CHAINS to whatever logger was active before it, so nothing is swallowed, and
+ * feeds each record into the Hub's ring buffer. Installed process-globally via `Logger.overrideLogger`.
+ */
+class HubDelegatingLogger implements LoggerService {
+  detached = false;
+
+  constructor(
+    private readonly capture: (level: LogLevel, message: unknown, params: unknown[]) => void,
+    private readonly previous: LoggerService | undefined,
+    private readonly fallback: ConsoleLogger,
+  ) {}
+
+  debug(message: unknown, ...params: unknown[]): void {
+    this.handle('debug', message, params);
+  }
+
+  error(message: unknown, ...params: unknown[]): void {
+    this.handle('error', message, params);
+  }
+
+  fatal(message: unknown, ...params: unknown[]): void {
+    this.handle('fatal', message, params);
+  }
+
+  log(message: unknown, ...params: unknown[]): void {
+    this.handle('log', message, params);
+  }
+
+  setLogLevels(levels: LogLevel[]): void {
+    this.fallback.setLogLevels?.(levels);
+    (this.previous as { setLogLevels?: (l: LogLevel[]) => void } | undefined)?.setLogLevels?.(levels);
+  }
+
+  verbose(message: unknown, ...params: unknown[]): void {
+    this.handle('verbose', message, params);
+  }
+
+  warn(message: unknown, ...params: unknown[]): void {
+    this.handle('warn', message, params);
+  }
+
+  private handle(level: LogLevel, message: unknown, params: unknown[]): void {
+    if (!this.detached) {
+      try {
+        this.capture(level, message, params);
+      } catch {
+        /* the capture path must NEVER throw into the caller's log statement */
+      }
+    }
+    const target = this.previous ?? this.fallback;
+    try {
+      (target as unknown as Record<string, (...a: unknown[]) => void>)[level]?.(message, ...params);
+    } catch {
+      /* chaining must not break either */
+    }
+  }
+}
+
+/**
+ * Captures NestJS `Logger` output into a ring buffer for the Logs panel — WITHOUT requiring the
+ * consumer to touch main.ts.
+ *
+ * `Logger.overrideLogger()` installs a delegating logger process-globally (the same mechanism
+ * `app.useLogger()` uses internally). It chains to the pre-existing logger (never swallows), applies
+ * secret redaction + truncation, and restores the previous logger on shutdown — owner-checked, so a
+ * newer override is never clobbered (the multi-app test-safety concern). Zero cost when disabled.
+ */
+@Injectable()
+export class HubLogBufferService implements OnModuleDestroy, OnModuleInit {
+  private buffer?: HubRingBuffer<BufferedLog>;
+  private cfg?: Exclude<ResolvedHubConfig['collectors']['logs'], false>;
+  private delegating?: HubDelegatingLogger;
+  private excludeContexts = new Set<string>();
+  private previousRef?: LoggerService;
+
+  constructor(@Inject(HUB_CONFIG) protected readonly config: ResolvedHubConfig) {}
+
+  /** Idempotent install of the delegating logger. Public so reads can self-heal after a foreign override. */
+  attach(): void {
+    if (this.config.collectors.logs === false) {
+      return;
+    }
+    if (!this.cfg) {
+      this.cfg = this.config.collectors.logs;
+      this.buffer = new HubRingBuffer<BufferedLog>(this.cfg.capacity);
+      this.excludeContexts = new Set(this.cfg.excludeContexts);
+    }
+    const current = this.staticRef();
+    if (current === this.delegating) {
+      return; // still the owner
+    }
+    // Never chain onto another (foreign/stale) HubDelegatingLogger — that would accumulate a growing
+    // delegate chain across app instances in the same process (parallel tests). Fall back to the
+    // ConsoleLogger instead; a real, non-Hub logger is chained to as the previous target.
+    const previous = current instanceof HubDelegatingLogger ? undefined : current;
+    const fallback = new ConsoleLogger();
+    const levels = (Logger as unknown as { logLevels?: LogLevel[] }).logLevels;
+    if (levels) {
+      fallback.setLogLevels(levels);
+    }
+    this.previousRef = previous;
+    this.delegating = new HubDelegatingLogger(
+      (level, message, params) => this.push(level, message, params),
+      previous,
+      fallback,
+    );
+    Logger.overrideLogger(this.delegating);
+  }
+
+  clear(): void {
+    this.buffer?.clear();
+  }
+
+  detach(): void {
+    if (this.delegating) {
+      this.delegating.detached = true;
+    }
+    // Only restore if we are still the owner — never clobber a newer override.
+    if (this.delegating && this.staticRef() === this.delegating) {
+      Logger.overrideLogger(this.previousRef ?? (undefined as unknown as LoggerService));
+    }
+    this.delegating = undefined;
+  }
+
+  get enabled(): boolean {
+    return this.config.collectors.logs !== false;
+  }
+
+  getData(since?: number): HubLogsData {
+    this.selfHeal();
+    const records = !this.buffer ? [] : since === undefined ? this.buffer.recent() : this.buffer.since(since);
+    return { cursor: this.buffer?.lastSeq ?? -1, dropped: this.buffer?.firstRetainedSeq ?? -1, records };
+  }
+
+  onModuleDestroy(): void {
+    this.detach();
+  }
+
+  onModuleInit(): void {
+    this.attach();
+  }
+
+  /** Extract the trailing string context param (ConsoleLogger convention) + an error stack. */
+  private extract(level: LogLevel, message: unknown, params: unknown[]): BufferedLog | undefined {
+    const parts = [...params];
+    let context: string | undefined;
+    if (parts.length && typeof parts[parts.length - 1] === 'string') {
+      context = parts.pop() as string;
+    }
+    if (context && this.excludeContexts.has(context)) {
+      return undefined;
+    }
+    let stack: string | undefined;
+    // For error(), Nest passes [stack, context]; after popping context a trailing stack-ish string remains.
+    if (
+      level === 'error' &&
+      parts.length &&
+      typeof parts[parts.length - 1] === 'string' &&
+      (parts[parts.length - 1] as string).includes('\n    at ')
+    ) {
+      stack = (parts.pop() as string).slice(0, 2000);
+    }
+    const text = this.stringify(message, parts);
+    const max = this.cfg?.maxMessageLength ?? 2048;
+    // Bound the redaction work: only the first `max` chars are ever shown after truncation, so
+    // redacting an arbitrarily large stringified payload is wasted effort. Cap the input to
+    // `max` + a margin (so a secret straddling the truncation point is still fully redacted).
+    const redactInput = text.length > max + 4096 ? text.slice(0, max + 4096) : text;
+    const redacted = redactSensitiveText(redactInput);
+    return {
+      context,
+      level,
+      message: redacted.length > max ? redacted.slice(0, max) + '… [truncated]' : redacted,
+      seq: 0,
+      stack,
+      timestamp: 0,
+    };
+  }
+
+  private push(level: LogLevel, message: unknown, params: unknown[]): void {
+    if (!this.buffer || !this.cfg) {
+      return;
+    }
+    if (!this.cfg.levels.includes(level)) {
+      return;
+    }
+    const record = this.extract(level, message, params);
+    if (record) {
+      this.buffer.add({
+        context: record.context,
+        level: record.level,
+        message: record.message,
+        stack: record.stack,
+      } as Omit<BufferedLog, 'seq' | 'timestamp'>);
+    }
+  }
+
+  /** Re-attach if a consumer installed their own logger after us (checked on each read; no timers). */
+  private selfHeal(): void {
+    if (!this.enabled) {
+      return;
+    }
+    const current = this.staticRef();
+    if (current !== this.delegating && current !== undefined) {
+      this.attach();
+    }
+  }
+
+  private staticRef(): LoggerService | undefined {
+    return (Logger as unknown as { staticInstanceRef?: LoggerService }).staticInstanceRef;
+  }
+
+  private stringify(message: unknown, params: unknown[]): string {
+    const one = (value: unknown): string => {
+      if (typeof value === 'string') {
+        return value;
+      }
+      if (value instanceof Error) {
+        return `${value.name}: ${value.message}`;
+      }
+      try {
+        return JSON.stringify(value);
+      } catch {
+        return inspect(value, { breakLength: Infinity, depth: 2 });
+      }
+    };
+    return [message, ...params].map(one).join(' | ');
+  }
+}