@bnhf/prismcast 1.3.4-2026.2.19

package/dist/utils/ffmpeg.js

@@ -0,0 +1,317 @@
+import { LOG } from "./logger.js";
+import { existsSync } from "node:fs";
+import ffmpegForHomebridge from "ffmpeg-for-homebridge";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+// The ffmpeg-for-homebridge package has incorrect type definitions (declares named export but JS uses default export). Cast to the correct type.
+const ffmpegPath = ffmpegForHomebridge;
+/* When using WebM capture mode, Chrome's MediaRecorder outputs WebM container with H264 video and Opus audio. For HLS compatibility, we need fMP4 container with
+ * H264 video and AAC audio. FFmpeg handles this conversion:
+ *
+ * - Video: Passed through unchanged (copy codec) - no quality loss, minimal CPU
+ * - Audio: Transcoded from Opus to AAC - lightweight operation
+ * - Container: Converted from WebM to fragmented MP4 with streaming-friendly flags
+ *
+ * The FFmpeg process runs for the lifetime of the stream, reading WebM from stdin and writing fMP4 to stdout. This output feeds directly into the existing fMP4
+ * segmenter.
+ */
+/* FFmpeg can be located in several places depending on how it was installed. We check in order of preference:
+ * 1. Channels DVR bundled FFmpeg:
+ *    - macOS: ~/Library/Application Support/ChannelsDVR/latest/ffmpeg
+ *    - Windows: C:\ProgramData\channelsdvr\latest\ffmpeg.exe
+ *    - Linux: ~/channels-dvr/latest/ffmpeg, /usr/local/channels-dvr/latest/ffmpeg, /opt/channels-dvr/latest/ffmpeg
+ * 2. Bundled FFmpeg from ffmpeg-for-homebridge package
+ * 3. System PATH (standard installation via package manager or manual install)
+ *
+ * The resolved path is cached after the first successful lookup to avoid repeated filesystem checks.
+ */
+// Cached FFmpeg path after resolution. Null means not yet resolved, undefined means not found.
+let cachedFFmpegPath = null;
+/**
+ * Checks if FFmpeg exists at a specific path by attempting to run it.
+ * @param pathToCheck - Full path to the FFmpeg executable.
+ * @returns Promise resolving to true if FFmpeg runs successfully at this path.
+ */
+async function checkFFmpegAtPath(pathToCheck) {
+    return new Promise((resolve) => {
+        const ffmpeg = spawn(pathToCheck, ["-version"], {
+            stdio: ["ignore", "ignore", "ignore"]
+        });
+        ffmpeg.on("error", () => {
+            resolve(false);
+        });
+        ffmpeg.on("exit", (code) => {
+            resolve(code === 0);
+        });
+    });
+}
+/**
+ * Resolves the FFmpeg executable path. Checks Channels DVR (macOS, Windows, Linux), then the bundled ffmpeg-for-homebridge, then system PATH. The resolved path is
+ * cached for subsequent calls.
+ * @returns Promise resolving to the FFmpeg path if found, or undefined if not available.
+ */
+export async function resolveFFmpegPath() {
+    // Return cached result if already resolved.
+    if (cachedFFmpegPath !== null) {
+        return cachedFFmpegPath;
+    }
+    // On macOS, check Channels DVR bundled FFmpeg first. Users of PrismCast with Channels DVR likely have this available.
+    if (process.platform === "darwin") {
+        const channelsDvrPath = join(homedir(), "Library", "Application Support", "ChannelsDVR", "latest", "ffmpeg");
+        if (existsSync(channelsDvrPath) && (await checkFFmpegAtPath(channelsDvrPath))) {
+            cachedFFmpegPath = channelsDvrPath;
+            return cachedFFmpegPath;
+        }
+    }
+    // On Windows, check Channels DVR bundled FFmpeg. Users of PrismCast with Channels DVR likely have this available.
+    if (process.platform === "win32") {
+        const channelsDvrPath = join("C:", "ProgramData", "channelsdvr", "latest", "ffmpeg.exe");
+        if (existsSync(channelsDvrPath) && (await checkFFmpegAtPath(channelsDvrPath))) {
+            cachedFFmpegPath = channelsDvrPath;
+            return cachedFFmpegPath;
+        }
+    }
+    // On Linux, check common Channels DVR installation paths. The Channels DVR setup script creates a channels-dvr directory in the current working directory when
+    // run. The official recommendation is ~/channels-dvr, but users also install to /usr/local/channels-dvr and /opt/channels-dvr.
+    if (process.platform === "linux") {
+        const linuxChannelsDvrPaths = [
+            join(homedir(), "channels-dvr", "latest", "ffmpeg"),
+            join("/usr", "local", "channels-dvr", "latest", "ffmpeg"),
+            join("/opt", "channels-dvr", "latest", "ffmpeg")
+        ];
+        for (const channelsDvrPath of linuxChannelsDvrPaths) {
+            // eslint-disable-next-line no-await-in-loop
+            if (existsSync(channelsDvrPath) && (await checkFFmpegAtPath(channelsDvrPath))) {
+                cachedFFmpegPath = channelsDvrPath;
+                return cachedFFmpegPath;
+            }
+        }
+    }
+    // Check ffmpeg-for-homebridge bundled FFmpeg. This provides a reliable fallback without requiring manual FFmpeg installation.
+    if (ffmpegPath && existsSync(ffmpegPath) && (await checkFFmpegAtPath(ffmpegPath))) {
+        cachedFFmpegPath = ffmpegPath;
+        return cachedFFmpegPath;
+    }
+    // Finally, check if ffmpeg is available in the system PATH.
+    if (await checkFFmpegAtPath("ffmpeg")) {
+        cachedFFmpegPath = "ffmpeg";
+        return cachedFFmpegPath;
+    }
+    // FFmpeg not found anywhere.
+    cachedFFmpegPath = undefined;
+    return undefined;
+}
+/**
+ * Spawns an FFmpeg process configured to transcode WebM (H264+Opus) to fMP4 (H264+AAC). The process reads from stdin and writes to stdout, allowing it to be
+ * integrated into a Node.js stream pipeline. Video is passed through unchanged; audio is transcoded from Opus to AAC for HLS compatibility.
+ *
+ * FFmpeg arguments:
+ * - `-hide_banner -loglevel warning`: Reduce noise, only show warnings/errors
+ * - `-probesize 16384`: Limit input probing to 16KB (Chrome's WebM header fits well under this) to minimize startup delay
+ * - `-i pipe:0`: Read input from stdin
+ * - `-c:v copy`: Copy video stream without re-encoding (H264 passthrough)
+ * - `-c:a aac -b:a <bitrate>`: Transcode audio to AAC at specified bitrate
+ * - `-f mp4`: Output MP4 container format
+ * - `-movflags frag_keyframe+empty_moov+default_base_moof`: Streaming-friendly fMP4 flags
+ * - `-flush_packets 1`: Flush output immediately after each packet to minimize latency
+ * - `pipe:1`: Write output to stdout
+ * @param audioBitrate - Audio bitrate in bits per second (e.g., 256000 for 256 kbps).
+ * @param onError - Callback invoked when FFmpeg exits unexpectedly or encounters an error.
+ * @param streamId - Stream identifier for logging.
+ * @param comment - Optional comment metadata (channel name or domain) to embed in the output.
+ * @returns FFmpeg process wrapper with stdin, stdout, and kill function.
+ */
+export function spawnFFmpeg(audioBitrate, onError, streamId, comment) {
+    // Use the cached FFmpeg path from resolveFFmpegPath(). This should always be set because isFFmpegAvailable() is called during startup, which populates the cache.
+    // If somehow not set, fall back to "ffmpeg" and let spawn handle the error.
+    const ffmpegPath = cachedFFmpegPath ?? "ffmpeg";
+    // Use Apple's AudioToolbox AAC encoder on macOS for better quality and performance. Fall back to FFmpeg's built-in AAC encoder on other platforms.
+    const aacEncoder = process.platform === "darwin" ? "aac_at" : "aac";
+    const ffmpegArgs = [
+        "-hide_banner",
+        "-loglevel", "warning",
+        "-probesize", "16384",
+        "-i", "pipe:0",
+        "-c:v", "copy",
+        "-c:a", aacEncoder,
+        "-b:a", String(audioBitrate),
+        "-f", "mp4",
+        "-movflags", "frag_keyframe+empty_moov+default_base_moof+skip_sidx+skip_trailer",
+        "-flush_packets", "1"
+    ];
+    // Add metadata comment if provided. This embeds "PrismCast - <channel>" in the output for identification.
+    if (comment) {
+        ffmpegArgs.push("-metadata", "comment=PrismCast - " + comment);
+    }
+    ffmpegArgs.push("pipe:1");
+    const ffmpeg = spawn(ffmpegPath, ffmpegArgs, {
+        stdio: ["pipe", "pipe", "pipe"]
+    });
+    const logPrefix = streamId ? "[" + streamId + "] " : "";
+    // Track whether graceful shutdown has been initiated. When true, we suppress error callbacks because any exit (whether from SIGTERM or stdin close) is expected.
+    let shuttingDown = false;
+    // Log FFmpeg stderr output (warnings and errors). stderr is guaranteed to be a Readable since we set stdio: ["pipe", "pipe", "pipe"].
+    ffmpeg.stderr.on("data", (data) => {
+        // Suppress warnings during shutdown - truncated input warnings are expected when the capture stream closes.
+        if (shuttingDown) {
+            return;
+        }
+        const message = data.toString().trim();
+        // Filter out common noise that isn't actionable.
+        const noisePatterns = ["Press [q] to stop", "frame=", "size=", "time=", "bitrate=", "speed="];
+        if (noisePatterns.some((pattern) => message.includes(pattern))) {
+            return;
+        }
+        if (message.length > 0) {
+            LOG.debug("streaming:ffmpeg", "%sFFmpeg: %s", logPrefix, message);
+        }
+    });
+    // Handle FFmpeg process exit.
+    ffmpeg.on("exit", (code, signal) => {
+        // During graceful shutdown, any exit is expected (whether from SIGTERM or stdin closing).
+        if (shuttingDown) {
+            return;
+        }
+        if (signal === "SIGTERM") {
+            // Normal termination via kill() - don't treat as error.
+            return;
+        }
+        if ((code !== null) && (code !== 0)) {
+            onError(new Error("FFmpeg exited with code " + String(code) + "."));
+        }
+        else if (signal) {
+            onError(new Error("FFmpeg killed by signal " + signal + "."));
+        }
+    });
+    // Handle spawn errors (e.g., FFmpeg not found).
+    ffmpeg.on("error", (error) => {
+        // During graceful shutdown, suppress errors from stdin pipe closing.
+        if (shuttingDown) {
+            return;
+        }
+        onError(error);
+    });
+    // Kill function for graceful shutdown. Sets the shuttingDown flag before sending SIGTERM so that any exit (whether from SIGTERM or stdin closing due to capture
+    // stream ending) is treated as normal termination.
+    const kill = () => {
+        shuttingDown = true;
+        if (!ffmpeg.killed) {
+            ffmpeg.kill("SIGTERM");
+        }
+    };
+    return {
+        kill,
+        process: ffmpeg,
+        stdin: ffmpeg.stdin,
+        stdout: ffmpeg.stdout
+    };
+}
+/**
+ * Spawns an FFmpeg process configured to remux fMP4 input to MPEG-TS output with codec copy. The process reads a continuous fMP4 stream (init segment followed by
+ * media segments) from stdin and writes MPEG-TS to stdout. No transcoding occurs — both video (H264) and audio (AAC) are copied unchanged — so CPU usage is minimal.
+ *
+ * FFmpeg arguments:
+ * - `-hide_banner -loglevel warning`: Reduce noise, only show warnings/errors
+ * - `-probesize 16384`: Limit input probing to 16KB (fMP4 init segment is ~1.3KB) to minimize startup delay
+ * - `-f mp4 -i pipe:0`: Read fragmented MP4 from stdin
+ * - `-c copy`: Copy both video and audio codecs without transcoding
+ * - `-f mpegts`: Output MPEG-TS container format
+ * - `-mpegts_pmt_start_pid 0x0020`: Use ATSC-conventional PMT PID range instead of FFmpeg's default (0x1000). Minimum allowed value is 0x0020 (32).
+ * - `-mpegts_start_pid 0x0031`: Use ATSC-conventional elementary stream PIDs instead of FFmpeg's defaults (0x100+)
+ * - `-mpegts_service_type digital_tv`: Label the service as digital TV in the PMT service descriptor
+ * - `-pat_period 0.1`: Repeat PAT/PMT tables every 100ms, matching ATSC broadcast frequency
+ * - `-pcr_period 40`: Insert PCR timestamps every 40ms, matching ATSC broadcast convention
+ * - `-flush_packets 1`: Flush output immediately after each packet to minimize latency
+ * - `pipe:1`: Write output to stdout
+ * @param onError - Callback invoked when FFmpeg exits unexpectedly or encounters an error.
+ * @param streamId - Optional stream identifier for logging.
+ * @returns FFmpeg process wrapper with stdin, stdout, and kill function.
+ */
+export function spawnMpegTsRemuxer(onError, streamId) {
+    const ffmpegBin = cachedFFmpegPath ?? "ffmpeg";
+    // MPEG-TS muxer flags are tuned to produce output resembling a real HDHomeRun CONNECT DUO (HDTC-2US) ATSC transport stream. Plex's transcoder may make
+    // assumptions about stream structure based on the reported device model (PID assignments, PAT/PMT frequency). Using ATSC-conventional values avoids "Invalid
+    // argument" failures when Plex tries to transcode the live session for remote clients. These are pure container metadata changes — the actual A/V data is
+    // untouched by -c copy.
+    const ffmpegArgs = [
+        "-hide_banner",
+        "-loglevel", "warning",
+        "-probesize", "16384",
+        "-f", "mp4",
+        "-i", "pipe:0",
+        "-c", "copy",
+        "-f", "mpegts",
+        "-mpegts_pmt_start_pid", "0x0020",
+        "-mpegts_start_pid", "0x0031",
+        "-mpegts_service_type", "digital_tv",
+        "-pat_period", "0.1",
+        "-pcr_period", "40",
+        "-flush_packets", "1",
+        "pipe:1"
+    ];
+    const ffmpeg = spawn(ffmpegBin, ffmpegArgs, {
+        stdio: ["pipe", "pipe", "pipe"]
+    });
+    const logPrefix = streamId ? "[" + streamId + "] " : "";
+    // Track whether graceful shutdown has been initiated. When true, we suppress error callbacks because any exit is expected.
+    let shuttingDown = false;
+    // Log FFmpeg stderr output (warnings and errors).
+    ffmpeg.stderr.on("data", (data) => {
+        if (shuttingDown) {
+            return;
+        }
+        const message = data.toString().trim();
+        const noisePatterns = ["Press [q] to stop", "frame=", "size=", "time=", "bitrate=", "speed="];
+        if (noisePatterns.some((pattern) => message.includes(pattern))) {
+            return;
+        }
+        if (message.length > 0) {
+            LOG.debug("streaming:ffmpeg", "%sMPEG-TS remuxer: %s", logPrefix, message);
+        }
+    });
+    // Handle FFmpeg process exit.
+    ffmpeg.on("exit", (code, signal) => {
+        if (shuttingDown) {
+            return;
+        }
+        if (signal === "SIGTERM") {
+            return;
+        }
+        if ((code !== null) && (code !== 0)) {
+            onError(new Error("MPEG-TS remuxer exited with code " + String(code) + "."));
+        }
+        else if (signal) {
+            onError(new Error("MPEG-TS remuxer killed by signal " + signal + "."));
+        }
+    });
+    // Handle spawn errors (e.g., FFmpeg not found).
+    ffmpeg.on("error", (error) => {
+        if (shuttingDown) {
+            return;
+        }
+        onError(error);
+    });
+    // Kill function for graceful shutdown.
+    const kill = () => {
+        shuttingDown = true;
+        if (!ffmpeg.killed) {
+            ffmpeg.kill("SIGTERM");
+        }
+    };
+    return {
+        kill,
+        process: ffmpeg,
+        stdin: ffmpeg.stdin,
+        stdout: ffmpeg.stdout
+    };
+}
+/**
+ * Checks if FFmpeg is available on the system. This resolves the FFmpeg path and caches it for use by spawnFFmpeg().
+ * @returns Promise resolving to true if FFmpeg is available, false otherwise.
+ */
+export async function isFFmpegAvailable() {
+    const ffmpegPath = await resolveFFmpegPath();
+    return ffmpegPath !== undefined;
+}
+//# sourceMappingURL=ffmpeg.js.map

package/dist/utils/ffmpeg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffmpeg.js","sourceRoot":"","sources":["../../src/utils/ffmpeg.ts"],"names":[],"mappings":"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"}

package/dist/utils/fileLogger.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Initializes the file logger. Creates the log file if it does not exist. Must be called after the data directory is ensured to exist.
+ * @param maxSize - Maximum log file size in bytes from CONFIG.logging.maxSize.
+ */
+export declare function initializeFileLogger(maxSize: number): Promise<void>;
+/**
+ * Writes a log entry to the buffer. Entries are flushed to disk periodically.
+ * @param level - Log level ("info", "warn", "error", "debug").
+ * @param message - The formatted log message.
+ * @param color - Optional ANSI color code to apply to the level prefix and message.
+ * @param categoryTag - Optional debug category tag (e.g., "recovery:tab"). Appended to the level prefix as [DEBUG:category].
+ */
+export declare function writeLogEntry(level: string, message: string, color?: string, categoryTag?: string): void;
+/**
+ * Flushes the write buffer to disk asynchronously. Called periodically by the flush timer.
+ */
+export declare function flushLogBuffer(): Promise<void>;
+/**
+ * Flushes the write buffer to disk synchronously. Used during shutdown to ensure final logs are written.
+ */
+export declare function flushLogBufferSync(): void;
+/**
+ * Shuts down the file logger, flushing any remaining buffer synchronously.
+ */
+export declare function shutdownFileLogger(): void;

package/dist/utils/fileLogger.js

@@ -0,0 +1,248 @@
+import df from "dateformat";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const { promises: fsPromises } = fs;
+/* The file logger provides persistent logging to ~/.prismcast/prismcast.log with automatic size-based trimming. When the log file exceeds the configured maximum
+ * size, it is trimmed to half the maximum size, keeping only complete lines (the most recent logs are preserved). This approach prevents unbounded log growth while
+ * maintaining recent history for troubleshooting.
+ *
+ * Design decisions:
+ *
+ * 1. Asynchronous buffered writes - Logs are collected in a buffer and flushed periodically to avoid blocking the event loop during high-frequency logging.
+ * 2. Periodic size checking - File size is checked every N writes rather than on each write to minimize syscall overhead.
+ * 3. Atomic trim operations - Trimming writes to a temp file then renames, preventing data loss if the process crashes during trim.
+ * 4. Timestamps - Uses the same format as console-stamp for consistency: yyyy/mm/dd HH:MM:ss.l
+ */
+/* The file logger maintains state for the log file path, write buffer, and size tracking. State is initialized when initializeFileLogger() is called during server
+ * startup.
+ */
+// Path to the log file, set during initialization.
+let logFilePath = null;
+// Buffer for collecting log entries before flushing to disk.
+let writeBuffer = [];
+// Approximate file size tracked in memory between actual file size checks.
+let approximateSize = 0;
+// Counter for tracking writes since last file size check.
+let writeCount = 0;
+// Timer for periodic buffer flushing.
+let flushTimer = null;
+// Flag indicating whether the file logger is initialized and operational.
+let isInitialized = false;
+// Flag to temporarily disable logging on write errors, preventing error cascades.
+let isDisabled = false;
+// Timestamp when logging was disabled due to error, for retry timing.
+let disabledAt = 0;
+// Maximum log file size, set during initialization.
+let maxLogSize = 1048576;
+// Configuration Constants.
+// Interval in milliseconds between buffer flushes.
+const FLUSH_INTERVAL_MS = 1000;
+// Number of writes between file size checks.
+const SIZE_CHECK_FREQUENCY = 100;
+// Duration in milliseconds to disable logging after a write error before retrying.
+const ERROR_RETRY_DELAY_MS = 60000;
+/* Terminal color codes for log file output. These match the colors used in console mode so that viewing the log file with terminal commands (tail -f, less -R, cat)
+ * shows the same color scheme as console output.
+ */
+const ANSI_RESET = "\x1b[0m";
+// Initialization.
+/**
+ * Initializes the file logger. Creates the log file if it does not exist. Must be called after the data directory is ensured to exist.
+ * @param maxSize - Maximum log file size in bytes from CONFIG.logging.maxSize.
+ */
+export async function initializeFileLogger(maxSize) {
+    const dataDir = path.join(os.homedir(), ".prismcast");
+    logFilePath = path.join(dataDir, "prismcast.log");
+    maxLogSize = maxSize;
+    try {
+        // Ensure the data directory exists.
+        await fsPromises.mkdir(dataDir, { recursive: true });
+        // Check if log file exists and get its size.
+        try {
+            const stats = await fsPromises.stat(logFilePath);
+            approximateSize = stats.size;
+        }
+        catch (error) {
+            // File does not exist, create it.
+            if (error.code === "ENOENT") {
+                await fsPromises.writeFile(logFilePath, "", "utf-8");
+                approximateSize = 0;
+            }
+            else {
+                throw error;
+            }
+        }
+        // Start the periodic flush timer.
+        flushTimer = setInterval(() => {
+            void flushLogBuffer();
+        }, FLUSH_INTERVAL_MS);
+        isInitialized = true;
+    }
+    catch (error) {
+        // Log to console since file logging failed, but do not throw - file logging is a best-effort feature.
+        // eslint-disable-next-line no-console
+        console.error("Failed to initialize file logger: %s. File logging disabled.", (error instanceof Error) ? error.message : String(error));
+    }
+}
+// Log Entry Writing.
+/**
+ * Writes a log entry to the buffer. Entries are flushed to disk periodically.
+ * @param level - Log level ("info", "warn", "error", "debug").
+ * @param message - The formatted log message.
+ * @param color - Optional ANSI color code to apply to the level prefix and message.
+ * @param categoryTag - Optional debug category tag (e.g., "recovery:tab"). Appended to the level prefix as [DEBUG:category].
+ */
+export function writeLogEntry(level, message, color, categoryTag) {
+    if (!isInitialized || !logFilePath) {
+        return;
+    }
+    // Check if logging is disabled due to previous error and whether retry delay has passed.
+    if (isDisabled) {
+        if ((Date.now() - disabledAt) < ERROR_RETRY_DELAY_MS) {
+            return;
+        }
+        // Re-enable logging and try again.
+        isDisabled = false;
+    }
+    // Format the log entry with timestamp and level. Apply ANSI color if provided.
+    const timestamp = df(new Date(), "yyyy/mm/dd HH:MM:ss.l");
+    const levelTag = categoryTag ? [level.toUpperCase(), ":", categoryTag].join("") : level.toUpperCase();
+    const levelPrefix = (level === "info") ? "" : ["[", levelTag, "] "].join("");
+    const colorStart = color ?? "";
+    const colorEnd = color ? ANSI_RESET : "";
+    const entry = ["[", timestamp, "] ", colorStart, levelPrefix, message, colorEnd, "\n"].join("");
+    // Add to buffer.
+    writeBuffer.push(entry);
+    approximateSize += entry.length;
+    writeCount++;
+    // Check if we should verify actual file size.
+    if ((writeCount % SIZE_CHECK_FREQUENCY) === 0) {
+        void checkAndTrimFile();
+    }
+}
+// Buffer Flushing.
+/**
+ * Flushes the write buffer to disk asynchronously. Called periodically by the flush timer.
+ */
+export async function flushLogBuffer() {
+    if (!isInitialized || !logFilePath || (writeBuffer.length === 0)) {
+        return;
+    }
+    // Take the current buffer and reset.
+    const entries = writeBuffer;
+    writeBuffer = [];
+    const content = entries.join("");
+    try {
+        await fsPromises.appendFile(logFilePath, content, "utf-8");
+    }
+    catch (error) {
+        // Disable logging temporarily to prevent error cascade.
+        isDisabled = true;
+        disabledAt = Date.now();
+        // Log to console as fallback.
+        // eslint-disable-next-line no-console
+        console.error("Failed to write to log file: %s. File logging disabled for %s seconds.", (error instanceof Error) ? error.message : String(error), ERROR_RETRY_DELAY_MS / 1000);
+    }
+}
+/**
+ * Flushes the write buffer to disk synchronously. Used during shutdown to ensure final logs are written.
+ */
+export function flushLogBufferSync() {
+    if (!isInitialized || !logFilePath || (writeBuffer.length === 0)) {
+        return;
+    }
+    const content = writeBuffer.join("");
+    writeBuffer = [];
+    try {
+        fs.appendFileSync(logFilePath, content, "utf-8");
+    }
+    catch (error) {
+        // Log to console as fallback.
+        // eslint-disable-next-line no-console
+        console.error("Failed to write final log entries: %s.", (error instanceof Error) ? error.message : String(error));
+    }
+}
+// Size Management.
+/**
+ * Checks the actual file size and trims if it exceeds the maximum.
+ */
+async function checkAndTrimFile() {
+    if (!logFilePath) {
+        return;
+    }
+    try {
+        const stats = await fsPromises.stat(logFilePath);
+        approximateSize = stats.size;
+        if (approximateSize > maxLogSize) {
+            await trimLogFile();
+        }
+    }
+    catch (error) {
+        // File might have been deleted externally - reset size tracking.
+        if (error.code === "ENOENT") {
+            approximateSize = 0;
+        }
+        // Log to console but continue operating.
+        // eslint-disable-next-line no-console
+        console.warn("Error checking log file size: %s.", (error instanceof Error) ? error.message : String(error));
+    }
+}
+/**
+ * Trims the log file to half the maximum size, keeping only complete lines. The most recent logs are preserved.
+ */
+async function trimLogFile() {
+    if (!logFilePath) {
+        return;
+    }
+    try {
+        const content = await fsPromises.readFile(logFilePath, "utf-8");
+        // Calculate target size (half of max).
+        const targetSize = Math.floor(maxLogSize / 2);
+        // We want to keep the END of the file (most recent logs). Find where to cut.
+        const cutPosition = content.length - targetSize;
+        if (cutPosition <= 0) {
+            // File is smaller than target, no trimming needed.
+            return;
+        }
+        // Find the next newline after the cut position to keep complete lines.
+        let lineStart = content.indexOf("\n", cutPosition);
+        if (lineStart === -1) {
+            // No newline found after cut position, keep from cut position.
+            lineStart = cutPosition;
+        }
+        else {
+            // Start after the newline.
+            lineStart += 1;
+        }
+        const trimmedContent = content.substring(lineStart);
+        // Write to temp file, then rename (atomic replace).
+        const tempPath = logFilePath + ".tmp";
+        await fsPromises.writeFile(tempPath, trimmedContent, "utf-8");
+        await fsPromises.rename(tempPath, logFilePath);
+        approximateSize = trimmedContent.length;
+    }
+    catch (error) {
+        // Log to console but continue operating - trim will be retried on next check.
+        // eslint-disable-next-line no-console
+        console.warn("Error trimming log file: %s.", (error instanceof Error) ? error.message : String(error));
+    }
+}
+// Shutdown.
+/**
+ * Shuts down the file logger, flushing any remaining buffer synchronously.
+ */
+export function shutdownFileLogger() {
+    if (!isInitialized) {
+        return;
+    }
+    // Stop the flush timer.
+    if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+    }
+    // Flush remaining buffer synchronously.
+    flushLogBufferSync();
+    isInitialized = false;
+}
+//# sourceMappingURL=fileLogger.js.map

package/dist/utils/fileLogger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileLogger.js","sourceRoot":"","sources":["../../src/utils/fileLogger.ts"],"names":[],"mappings":"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"}

package/dist/utils/format.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Formats a duration in milliseconds as a human-readable string. The format varies based on duration length:
+ * - Less than 60 seconds: "17s"
+ * - Less than 1 hour: "6m 39s"
+ * - 1 hour or more: "1h 23m"
+ * @param ms - Duration in milliseconds.
+ * @returns Formatted duration string.
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Extracts a concise domain from a URL by keeping only the last two portions of the hostname (e.g., "watch.foodnetwork.com" becomes "foodnetwork.com",
+ * "www.hulu.com" becomes "hulu.com"). Used as a standard domain key for DOMAIN_CONFIG lookups and as a display fallback when no provider name is configured.
+ * @param url - The URL to extract the domain from.
+ * @returns The concise domain, or the original URL if parsing fails.
+ */
+export declare function extractDomain(url: string): string;