/** * @file packages/core/src/cliHistory.ts * @description This file contains the CLI history page generator. * @author Luca Liguori * @created 2025-10-09 * @version 1.0.1 * @license Apache-2.0 * * Copyright 2025, 2026, 2027 Luca Liguori. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ import { writeFileSync } from 'node:fs'; import os from 'node:os'; import path from 'node:path'; import { logModuleLoaded } from '@matterbridge/utils/loader'; // @matterbridge import { Tracker, type TrackerSnapshot } from '@matterbridge/utils/tracker'; logModuleLoaded('CliHistory'); export type GenerateHistoryPageOptions = { /** * Full path (file name included) for the generated HTML file. * Defaults to `/history.html`. */ outputPath?: string; /** * Title shown in the generated page and browser tab. * Defaults to `Matterbridge CPU & Memory History`. */ pageTitle?: string; /** * Hostname shown in the generated page and browser tab. */ hostname?: string; }; /** * Generates a static HTML dashboard displaying CPU and memory history. * * @param {GenerateHistoryPageOptions} [options] - Optional configuration for output path, page title, and refresh interval. * * @returns {string | undefined} The absolute path to the generated HTML file, or undefined if no samples exist. */ // oxlint-disable-next-line max-lines-per-function export function generateHistoryPage(options: GenerateHistoryPageOptions = {}): string | undefined { const pageTitle = options.pageTitle ?? 'Matterbridge CPU & Memory History'; const hostname = options.hostname ?? os.hostname(); const outputPath = path.resolve(options.outputPath ?? path.join(process.cwd(), 'history.html')); const normalizedHistory: TrackerSnapshot[] = []; for (let offset = 0; offset < Tracker.historySize; offset += 1) { const index = (Tracker.historyIndex + offset) % Tracker.historySize; const entry = Tracker.history[index]; if (!entry || entry.timestamp === 0) continue; normalizedHistory.push(entry); } if (normalizedHistory.length === 0) { return undefined; } const peakOsCpu = Math.max(...normalizedHistory.map((entry) => entry.peakOsCpu ?? entry.osCpu)); const peakProcessCpu = Math.max(...normalizedHistory.map((entry) => entry.peakProcessCpu ?? entry.processCpu)); const peakRss = Math.max(...normalizedHistory.map((entry) => entry.peakRss ?? entry.rss)); const peakHeapUsed = Math.max(...normalizedHistory.map((entry) => entry.peakHeapUsed ?? entry.heapUsed)); const peakHeapTotal = Math.max(...normalizedHistory.map((entry) => entry.peakHeapTotal ?? entry.heapTotal)); const peakExternal = Math.max(...normalizedHistory.map((entry) => entry.peakExternal ?? entry.external)); const peakArrayBuffers = Math.max(...normalizedHistory.map((entry) => entry.peakArrayBuffers ?? entry.arrayBuffers)); const firstTimestamp = normalizedHistory[0]?.timestamp ?? Date.now(); const lastTimestamp = normalizedHistory[normalizedHistory.length - 1]?.timestamp ?? Date.now(); const summary = { entries: normalizedHistory.length, timeRange: `${new Date(firstTimestamp).toLocaleString()} → ${new Date(lastTimestamp).toLocaleString()}`, peakOsCpu, peakProcessCpu, peakRss, peakHeapUsed, peakHeapTotal, peakExternal, peakArrayBuffers, }; const html = ` ${escapeHtml(pageTitle)}

${escapeHtml(pageTitle)}

Hostname: ${escapeHtml(hostname)}

Generated: ${new Date().toLocaleString()}

Host CPU Usage (%)

Process CPU Usage (%)

Memory Usage (MB)

External and Array Buffers (MB)

Samples

Timestamp Host CPU % Peak % Process CPU % Peak % RSS (MB) Peak MB Heap Used (MB) Peak MB Heap Total (MB) Peak MB
`; writeFileSync(outputPath, html, { encoding: 'utf-8' }); return outputPath; } /** * Escapes HTML special characters to prevent breaking embedded markup. * * @param {string} input - The string to escape. * @returns {string} The escaped string safe for HTML contexts. */ function escapeHtml(input: string): string { return input.replace(/&/g, '&').replace(//g, '>').replace(/"/g, '"').replace(/'/g, '''); }