prismcast 1.12.0 → 1.13.0

package/dist/utils/fileLogger.js

@@ -1,8 +1,11 @@
+import { assertNever } from "./never.js";
+import { boundedWait } from "./delay.js";
 import { formatTimestamp } from "./format.js";
 import fs from "node:fs";
 import { isAnyDebugEnabled } from "./debugFilter.js";
 import path from "node:path";
 import { styleText } from "node:util";
+import { systemClock } from "homebridge-plugin-utils";
 const { promises: fsPromises } = fs;
 /* The file logger provides persistent logging to a configurable log file 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
@@ -18,76 +21,129 @@ const { promises: fsPromises } = fs;
  * 5. Terminal coloring - SGR escape codes are baked into the file output via styleText so that viewing the log with terminal commands (tail -f, less -R, cat)
  *    shows the same color scheme as console output. styleText emits both the opening color code and the trailing reset in one call, with validateStream disabled
  *    because the log file is not a TTY but we still want the codes preserved for downstream terminal viewers.
+ * 6. Startup window - The logger cannot open its file until the configuration that names the path and the size cap has been read, and reading it is itself
+ *    worth logging. Entries emitted in the window state, before the one initialization, are held in the write buffer and appended by the first flush after it,
+ *    so the log file opens with the boot messages that preceded it. The window is bounded, and the initialization leaves it whether it succeeds or fails.
  */
-/* 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.
+/* The file logger's module state: the lifecycle state that says where a line goes, plus the bookkeeping of the file it is open on. Every one of them is set up
+ * by the initializeFileLogger() call during server startup.
+ */
+// Where the logger is in its lifecycle. Only transition() assigns it, which is what gives the flush timer a single owner.
+let state = { kind: "window" };
+/* Buffer collecting log entries between flushes. It is the open file's bookkeeping rather than a member of the open state: the write path pushes to it once per
+ * line, and rebuilding a state object per line would allocate on every log call.
  */
-// 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.
+// Writes since the last file size check, beside the state for the same reason the buffer is - the write path bumps it once per line.
 let writeCount = 0;
-// Timer for periodic buffer flushing.
-let flushTimer = null;
-// Flag indicating whether the file logger is initialized and operational.
-let isInitialized = false;
-/* Tail of the write-ordering chain. Every asynchronous mutation of the log file (buffer flushes and trims) is appended to this promise so that the operations run
- * strictly one after another. Without this serialization a flush's appendFile could land between a trim's readFile and its rename, and the rename would then
- * overwrite the just-appended lines with stale trimmed content - silently dropping log entries. Routing both paths through a single ordering primitive makes
- * "read-modify-rename" and "append" mutually exclusive without an explicit lock. The tail never rejects: the helper that enqueues work swallows the settled
- * outcome before chaining the next operation, so one failing operation cannot poison the chain for subsequent writes.
+/* Tail of the write-ordering chain, the open file's bookkeeping rather than a member of its state. Every asynchronous mutation of the log file (buffer flushes
+ * and trims) is appended to this promise so that the operations run strictly one after another. Without this serialization a flush's appendFile could land
+ * between a trim's readFile and its rename, and the rename would then overwrite the just-appended lines with stale trimmed content - silently dropping log
+ * entries. Routing both paths through a single ordering primitive makes "read-modify-rename" and "append" mutually exclusive without an explicit lock. The tail
+ * never rejects: the helper that enqueues work swallows the settled outcome before chaining the next operation, so one failing operation cannot poison the chain
+ * for subsequent writes.
  */
 let writeChain = Promise.resolve();
-// 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.
+// How long shutdown waits for the outstanding write chain to drain. Generous enough for a trim's read, write, and rename on a busy disk, and short enough that a
+// wedged filesystem operation cannot hold the process open through its own shutdown.
+const SHUTDOWN_DRAIN_BOUND_MS = 5000;
+// Maximum log file size, set during initialization. It is configuration the trim reads rather than lifecycle, so it stays beside the state.
 let maxLogSize = 1048576;
+/* The clock the flush interval arms on and the pause stamps read, set during initialization. It is per-run configuration the way the size cap is, so it stays
+ * beside the state rather than inside it: a member of the open variant would put the clock's lifetime where the file keeps lifecycle, and the closing and closed
+ * states read it too.
+ */
+let loggerClock = systemClock;
 // 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.
+// Duration in milliseconds a paused file drops entries for before the next write retries it.
 const ERROR_RETRY_DELAY_MS = 60000;
+// The most entries the startup window holds. A push past the limit drops the oldest entry, because the newest lines are the ones that explain an exit.
+const STARTUP_BUFFER_LIMIT = 1000;
+// Lifecycle State.
+/**
+ * Moves the logger to its next state. Every transition goes through here, and this is where the flush timer's lifetime is decided: a timer belongs to the
+ * states that carry one, so leaving them for a state that does not carry the same timer stops it, whichever transition is leaving.
+ * @param next - The state the logger enters.
+ */
+function transition(next) {
+    if (("timer" in state) && (!("timer" in next) || (next.timer !== state.timer))) {
+        state.timer[Symbol.dispose]();
+    }
+    state = next;
+}
+/**
+ * The path of the file the logger writes through its buffer, while it has one: the open and closing states. The window has no file yet, the off state has
+ * none, and the closed state keeps its path for the synchronous append in writeLogEntry rather than for the buffered paths this reader serves.
+ * @returns The path, or null when no file is open.
+ */
+function openFilePath() {
+    switch (state.kind) {
+        case "open":
+        case "closing": {
+            return state.path;
+        }
+        case "window":
+        case "closed":
+        case "off": {
+            return null;
+        }
+        default: {
+            return assertNever(state);
+        }
+    }
+}
 // 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.
+ * Initializes the file logger. Creates the log file if it does not exist. Must be called after the data directory is ensured to exist. A call is the one
+ * initialization of the process: it enters open, leaving the window's entries in the buffer for the first flush to append, or off, discarding them. Either
+ * outcome leaves the startup window behind.
  * @param logPath - Absolute path to the log file, resolved by the caller via getLogFilePath().
  * @param maxSize - Maximum log file size in bytes from CONFIG.logging.maxSize.
+ * @param clock - The clock the flush interval arms on and the pause stamps read; defaults to the system clock.
  */
-export async function initializeFileLogger(logPath, maxSize) {
-    logFilePath = logPath;
+export async function initializeFileLogger(logPath, maxSize, clock = systemClock) {
+    /* This runs before the first await below, because the states it leaves must not survive into that gap. A later initialization supersedes the file the last
+     * run closed, so a line landing inside these awaits is dropped rather than appended to a file this run has moved on from; a timer a still-open logger carried
+     * is stopped by the chokepoint on the way through; and the window is the one state left alone, because the lines it holds are the boot messages the first
+     * flush appends.
+     */
+    if (state.kind !== "window") {
+        transition({ kind: "off" });
+    }
+    loggerClock = clock;
     maxLogSize = maxSize;
     try {
         // Ensure the parent directory of the log file exists.
-        await fsPromises.mkdir(path.dirname(logFilePath), { recursive: true });
-        // Check if log file exists and get its size.
+        await fsPromises.mkdir(path.dirname(logPath), { recursive: true });
+        // The stat asks one question - does the file exist - and its result is not needed beyond that, because an existing file is appended to as it stands and
+        // the periodic check reads the size from the disk when it needs one.
         try {
-            const stats = await fsPromises.stat(logFilePath);
-            approximateSize = stats.size;
+            await fsPromises.stat(logPath);
         }
         catch (error) {
             // File does not exist, create it.
             if (error.code === "ENOENT") {
-                await fsPromises.writeFile(logFilePath, "", "utf-8");
-                approximateSize = 0;
+                await fsPromises.writeFile(logPath, "", "utf-8");
             }
             else {
                 throw error;
             }
         }
-        // Start the periodic flush timer.
-        flushTimer = setInterval(() => {
+        // The timer belongs to the state that holds the file, so it is created with that state and disposed by the chokepoint when the logger leaves it.
+        const timer = clock.schedule(() => {
             void flushLogBuffer();
-        }, FLUSH_INTERVAL_MS);
-        isInitialized = true;
+        }, FLUSH_INTERVAL_MS, { repeat: true });
+        transition({ kind: "open", path: logPath, pausedSince: null, timer });
     }
     catch (error) {
+        // A failed initialization discards what the window held and leaves the logger where no state takes a line: no file will ever take those entries, and
+        // holding them would grow the buffer for the life of the process.
+        writeBuffer = [];
+        transition({ kind: "off" });
         // 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));
@@ -95,38 +151,84 @@ export async function initializeFileLogger(logPath, maxSize) {
 }
 // Log Entry Writing.
 /**
- * Writes a log entry to the buffer. Entries are flushed to disk periodically.
+ * Formats one log entry as it appears in the file: the timestamp, the level tag (carrying the debug category when one is supplied), and the message, colored
+ * and newline-terminated. The buffered path and the post-shutdown append both call it, so the shape of a line is stated in one place. See the file's design
+ * block for the rationale behind baking SGR codes into the file output.
  * @param level - Log level ("info", "warn", "error", "debug").
  * @param message - The formatted log message.
  * @param color - Color name accepted by node:util.styleText, or null for the default terminal color.
  * @param categoryTag - Optional debug category tag (e.g., "recovery:tab"). Appended to the level prefix as [DEBUG:category].
+ * @returns The entry text, terminated by a newline.
  */
-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. See the file's design block for the rationale behind baking SGR codes into the file output.
-    const timestamp = formatTimestamp();
+function formatLogEntry(level, message, color, categoryTag) {
+    const timestamp = formatTimestamp(loggerClock.now());
     const levelTag = categoryTag ? level.toUpperCase() + ":" + categoryTag : level.toUpperCase();
     const levelPrefix = (level === "info") ? "" : "[" + levelTag + "] ";
     const body = levelPrefix + message;
     const coloredBody = color ? styleText(color, body, { validateStream: false }) : body;
-    const entry = "[" + timestamp + "] " + coloredBody + "\n";
-    // 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();
+    return "[" + timestamp + "] " + coloredBody + "\n";
+}
+/**
+ * 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 - Color name accepted by node:util.styleText, or null for the default terminal color.
+ * @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) {
+    switch (state.kind) {
+        case "window": {
+            writeBuffer.push(formatLogEntry(level, message, color, categoryTag));
+            /* The window has no open file, so it bounds itself where the open state runs a periodic size check instead. The bound is tested on every push, so the
+             * oldest entry makes room as soon as one entry too many arrives.
+             */
+            if (writeBuffer.length > STARTUP_BUFFER_LIMIT) {
+                writeBuffer.shift();
+            }
+            return;
+        }
+        case "open":
+        case "closing": {
+            if ((state.kind === "open") && (state.pausedSince !== null)) {
+                if ((loggerClock.now() - state.pausedSince) < ERROR_RETRY_DELAY_MS) {
+                    return;
+                }
+                /* The first write past the retry delay re-opens the file, and the next failure on it sets a fresh pause. Clearing the field here is what keeps it
+                 * describing the file's standing rather than a moment that has passed, and it has no observable of its own, because every failure on the file the
+                 * logger holds open refreshes the timestamp.
+                 */
+                transition({ ...state, pausedSince: null });
+            }
+            writeBuffer.push(formatLogEntry(level, message, color, categoryTag));
+            writeCount++;
+            // Check if we should verify actual file size.
+            if ((writeCount % SIZE_CHECK_FREQUENCY) === 0) {
+                void checkAndTrimFile();
+            }
+            return;
+        }
+        case "closed": {
+            /* The logger has shut down and this line still belongs to the run that just ended, so it goes to that run's file. The append is synchronous because
+             * nothing asynchronous is left to carry it: the flush timer is stopped, the write chain has drained, and the process may exit on the next tick.
+             */
+            try {
+                fs.appendFileSync(state.path, formatLogEntry(level, message, color, categoryTag), "utf-8");
+            }
+            catch (error) {
+                // eslint-disable-next-line no-console
+                console.error("Failed to write a log entry after shutdown: %s.", (error instanceof Error) ? error.message : String(error));
+                // A closed file that cannot be written is where the logger goes off, so the path is reported once rather than once per line.
+                transition({ kind: "off" });
+            }
+            return;
+        }
+        case "off": {
+            // Nothing takes the entry: no file is open, no closed file is waiting for it, and the startup window is behind us.
+            return;
+        }
+        default: {
+            assertNever(state);
+        }
     }
 }
 // Write Ordering.
@@ -134,7 +236,7 @@ export function writeLogEntry(level, message, color, categoryTag) {
  * Serializes an asynchronous log-file mutation against every other such mutation. The supplied operation is appended to the module-scoped write chain so that
  * flushes and trims execute one at a time, never interleaving their read/append/rename steps. The returned promise resolves when this specific operation has
  * settled. The chain itself is advanced with the settled (caught) result so a rejecting operation cannot poison subsequent writes - each operation is responsible
- * for its own error handling, exactly as the inline try/catch blocks did before serialization.
+ * for its own error handling.
  * @param operation - The async mutation to run after all previously enqueued mutations have completed.
  */
 async function serializeWrite(operation) {
@@ -150,12 +252,13 @@ async function serializeWrite(operation) {
  * interleave with an in-flight trim, which would otherwise discard the appended lines when the trim renames its stale snapshot over the file.
  */
 export async function flushLogBuffer() {
-    if (!isInitialized || !logFilePath || (writeBuffer.length === 0)) {
+    // The path is read once here so the serialized operation below writes to the file the logger held when the flush was issued, whatever the state does next.
+    const targetPath = openFilePath();
+    if ((targetPath === null) || (writeBuffer.length === 0)) {
         return;
     }
-    // Take the current buffer and reset. We snapshot the path as well so the serialized operation is not affected by a concurrent shutdown clearing logFilePath.
+    // Take the current buffer and reset.
     const entries = writeBuffer;
-    const targetPath = logFilePath;
     writeBuffer = [];
     const content = entries.join("");
     return serializeWrite(async () => {
@@ -163,26 +266,51 @@ export async function flushLogBuffer() {
             await fsPromises.appendFile(targetPath, 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);
+            /* Every failure on the file the logger still holds open sets or refreshes the pause, so the delay before the next attempt runs from the latest failure
+             * rather than the first. A failure that settles while the logger is closing that file, or has already left it, touches no state: the final flush is the
+             * run's one attempt either way, and the drain bound lets a shutdown complete with an append still in flight, so a run that has since opened its own file
+             * must not inherit a pause the run before it earned.
+             */
+            if ((state.kind === "open") && (state.path === targetPath)) {
+                transition({ ...state, pausedSince: loggerClock.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);
+            }
+            else {
+                // Log to console as fallback.
+                // eslint-disable-next-line no-console
+                console.error("Failed to write to the log file: %s.", (error instanceof Error) ? error.message : String(error));
+            }
         }
     });
 }
 /**
- * Flushes the write buffer to disk synchronously. Used during shutdown to ensure final logs are written.
+ * Flushes the write buffer to disk synchronously. Shutdown reaches it while the logger is closing and writes to the configured log file, and the process exit
+ * handler reaches it on either side of initialization. The fallback path serves that second position - an exit in the startup window, where the buffer holds
+ * the window's entries and no log file was ever opened - and a logger holding a file of its own ignores it in favor of that file.
+ * @param fallbackPath - Absolute path to write to when the logger never initialized. Shutdown omits it, and so does console mode, whose lines never enter the buffer.
  */
-export function flushLogBufferSync() {
-    if (!isInitialized || !logFilePath || (writeBuffer.length === 0)) {
+export function flushLogBufferSync(fallbackPath) {
+    if (writeBuffer.length === 0) {
+        return;
+    }
+    // With no file of its own, the fallback path is the only thing that says where these entries should land, and without one there is nowhere to put them.
+    const openPath = openFilePath();
+    const targetPath = openPath ?? fallbackPath;
+    if (!targetPath) {
         return;
     }
     const content = writeBuffer.join("");
     writeBuffer = [];
     try {
-        fs.appendFileSync(logFilePath, content, "utf-8");
+        /* Only the fallback needs its parent directory created, and it shares the catch below so a read-only data directory yields the same console message a
+         * failed append does. A logger holding its own file created that directory at initialization, so repeating the syscall here would buy nothing.
+         */
+        if (openPath === null) {
+            fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+        }
+        fs.appendFileSync(targetPath, content, "utf-8");
     }
     catch (error) {
         // Log to console as fallback.
@@ -195,24 +323,21 @@ export function flushLogBufferSync() {
  * Checks the actual file size and trims if it exceeds the maximum.
  */
 async function checkAndTrimFile() {
-    if (!logFilePath) {
+    const targetPath = openFilePath();
+    if (targetPath === null) {
         return;
     }
     try {
-        const stats = await fsPromises.stat(logFilePath);
-        approximateSize = stats.size;
+        const stats = await fsPromises.stat(targetPath);
         // Skip trimming when debug logging is active. Debug sessions generate high-volume output that is valuable for diagnosis - trimming mid-session would discard
         // the very data we are trying to capture.
-        if ((approximateSize > maxLogSize) && !isAnyDebugEnabled()) {
+        if ((stats.size > maxLogSize) && !isAnyDebugEnabled()) {
             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.
+        // A file removed externally arrives here as the stat's ENOENT, and the warning is the whole response: the next append recreates the file, so logging
+        // continues into an empty one rather than stopping.
         // eslint-disable-next-line no-console
         console.warn("Error checking log file size: %s.", (error instanceof Error) ? error.message : String(error));
     }
@@ -259,11 +384,12 @@ export function computeTrimmedLogContent(content, maxSize) {
  * an appendFile cannot land between this function's readFile and its rename, so the rename never overwrites freshly appended lines with a stale snapshot.
  */
 async function trimLogFile() {
-    if (!logFilePath) {
+    // The path is read once here because a shutdown can move the state under the serialized operation below, and the rename has to land on the file the read
+    // came from rather than on wherever the logger has since gone.
+    const targetPath = openFilePath();
+    if (targetPath === null) {
         return;
     }
-    // Snapshot the path so a concurrent shutdown clearing logFilePath cannot redirect the rename target mid-operation.
-    const targetPath = logFilePath;
     return serializeWrite(async () => {
         try {
             const content = await fsPromises.readFile(targetPath, "utf-8");
@@ -275,7 +401,6 @@ async function trimLogFile() {
             const tempPath = targetPath + ".tmp";
             await fsPromises.writeFile(tempPath, trimmedContent, "utf-8");
             await fsPromises.rename(tempPath, targetPath);
-            approximateSize = trimmedContent.length;
         }
         catch (error) {
             // Log to console but continue operating - trim will be retried on next check.
@@ -286,28 +411,42 @@ async function trimLogFile() {
 }
 // Shutdown.
 /**
- * Shuts down the file logger, flushing any remaining buffer synchronously.
+ * Shuts down the file logger: enters the closing state, waits for the write chain to drain, then flushes any remaining buffer synchronously and enters closed.
+ *
+ * The flush timer stops the moment the logger enters closing, because the chokepoint disposes a timer the next state does not carry, so no periodic flush can
+ * fire into the drain.
+ *
+ * The drain is what keeps shutdown from racing the writes it is meant to finish. A trim holds the log file across a read, a temp write, and a rename; a synchronous
+ * final flush issued while that rename is still pending appends to the file the rename is about to replace, so the last entries of the run are discarded along with
+ * the stale snapshot. Awaiting the chain first puts the final flush strictly after every mutation already in flight.
+ *
+ * The wait is bounded because a wedged filesystem operation must not hold the process open through its own shutdown. When the bound lapses the flush and the move
+ * to closed proceed anyway, which is the same outcome an unbounded wait would eventually reach minus the hang.
+ *
+ * The closed state keeps the path of the file it closed, so a line logged after this point - the exit handler's Chrome cleanup, a late process-level handler - is
+ * appended to that file synchronously instead of falling into the gap between the shutdown and the process exit.
  */
-export function shutdownFileLogger() {
-    if (!isInitialized) {
+export async function shutdownFileLogger() {
+    // The window, closed, and off states have no file to shut down, and returning here is what leaves a window's buffered entries for the exit handler's fallback.
+    if ((state.kind !== "open") && (state.kind !== "closing")) {
         return;
     }
-    // Stop the flush timer.
-    if (flushTimer) {
-        clearInterval(flushTimer);
-        flushTimer = null;
-    }
+    const targetPath = state.path;
+    /* Entering closing stops the flush timer through the chokepoint, so no periodic flush fires into the drain, and it lifts any pause the open file carried: the
+     * drain buffers every line logged under it and the final flush is the run's one last attempt at them, which a pause - a bound on a cascade of periodic
+     * retries - has no reason to prevent.
+     */
+    transition({ kind: "closing", path: targetPath });
+    // Drain the outstanding write chain so the synchronous flush below lands after every mutation already in flight rather than into a file a pending rename is
+    // about to replace. The chain never rejects - serializeWrite swallows each operation's outcome - so this only ever resolves or lapses.
+    await boundedWait(writeChain, SHUTDOWN_DRAIN_BOUND_MS, { clock: loggerClock });
     // Flush remaining buffer synchronously.
     flushLogBufferSync();
-    // Reset all module state so a subsequent initializeFileLogger() starts from a clean slate. The disabled-on-write-error flag in particular must not survive
-    // shutdown - if a prior run hit a write failure and entered the 60-second retry window, that window should not silently drop writes from the next run.
-    isInitialized = false;
-    isDisabled = false;
-    disabledAt = 0;
-    writeBuffer = [];
-    approximateSize = 0;
     writeCount = 0;
-    logFilePath = null;
+    writeBuffer = [];
+    // The closed state keeps the file this run wrote to, so a line logged from here on still reaches it rather than falling into the gap between the shutdown and
+    // the process exit.
+    transition({ kind: "closed", path: targetPath });
     // Reset the write-ordering chain so the next run starts from a fresh, already-resolved tail rather than chaining onto the previous run's last operation.
     writeChain = Promise.resolve();
 }

package/dist/utils/fileLogger.js.map

@@ -1 +1 @@
-{"version":3,"file":"fileLogger.js","sourceRoot":"","sources":["../../src/utils/fileLogger.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;AAOpC;;;;;;;;;;;;;;GAcG;AAEH;;GAEG;AAEH,mDAAmD;AACnD,IAAI,WAAW,GAAqB,IAAI,CAAC;AAEzC,6DAA6D;AAC7D,IAAI,WAAW,GAAa,EAAE,CAAC;AAE/B,2EAA2E;AAC3E,IAAI,eAAe,GAAG,CAAC,CAAC;AAExB,0DAA0D;AAC1D,IAAI,UAAU,GAAG,CAAC,CAAC;AAEnB,sCAAsC;AACtC,IAAI,UAAU,GAA6C,IAAI,CAAC;AAEhE,0EAA0E;AAC1E,IAAI,aAAa,GAAG,KAAK,CAAC;AAE1B;;;;;GAKG;AACH,IAAI,UAAU,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;AAElD,kFAAkF;AAClF,IAAI,UAAU,GAAG,KAAK,CAAC;AAEvB,sEAAsE;AACtE,IAAI,UAAU,GAAG,CAAC,CAAC;AAEnB,oDAAoD;AACpD,IAAI,UAAU,GAAG,OAAO,CAAC;AAEzB,2BAA2B;AAE3B,mDAAmD;AACnD,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAE/B,6CAA6C;AAC7C,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAEjC,mFAAmF;AACnF,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAEnC,kBAAkB;AAElB;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,OAAe,EAAE,OAAe;IAEzE,WAAW,GAAG,OAAO,CAAC;IACtB,UAAU,GAAG,OAAO,CAAC;IAErB,IAAI,CAAC;QAEH,sDAAsD;QACtD,MAAM,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAEvE,6CAA6C;QAC7C,IAAI,CAAC;YAEH,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAEjD,eAAe,GAAG,KAAK,CAAC,IAAI,CAAC;QAC/B,CAAC;QAAC,OAAM,KAAK,EAAE,CAAC;YAEd,kCAAkC;YAClC,IAAI,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAEtD,MAAM,UAAU,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;gBACrD,eAAe,GAAG,CAAC,CAAC;YACtB,CAAC;iBAAM,CAAC;gBAEN,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;QAED,kCAAkC;QAClC,UAAU,GAAG,WAAW,CAAC,GAAS,EAAE;YAElC,KAAK,cAAc,EAAE,CAAC;QACxB,CAAC,EAAE,iBAAiB,CAAC,CAAC;QAEtB,aAAa,GAAG,IAAI,CAAC;IACvB,CAAC;IAAC,OAAM,KAAK,EAAE,CAAC;QAEd,sGAAsG;QACtG,sCAAsC;QACtC,OAAO,CAAC,KAAK,CAAC,8DAA8D,EAAE,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1I,CAAC;AACH,CAAC;AAED,qBAAqB;AAErB;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,OAAe,EAAE,KAAe,EAAE,WAAoB;IAEjG,IAAG,CAAC,aAAa,IAAI,CAAC,WAAW,EAAE,CAAC;QAElC,OAAO;IACT,CAAC;IAED,yFAAyF;IACzF,IAAG,UAAU,EAAE,CAAC;QAEd,IAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,CAAC,GAAG,oBAAoB,EAAE,CAAC;YAEpD,OAAO;QACT,CAAC;QAED,mCAAmC;QACnC,UAAU,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,6IAA6I;IAC7I,MAAM,SAAS,GAAG,eAAe,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,GAAG,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;IAC7F,MAAM,WAAW,GAAG,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,QAAQ,GAAG,IAAI,CAAC;IACpE,MAAM,IAAI,GAAG,WAAW,GAAG,OAAO,CAAC;IACnC,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACrF,MAAM,KAAK,GAAG,GAAG,GAAG,SAAS,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI,CAAC;IAE1D,iBAAiB;IACjB,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxB,eAAe,IAAI,KAAK,CAAC,MAAM,CAAC;IAChC,UAAU,EAAE,CAAC;IAEb,8CAA8C;IAC9C,IAAG,CAAC,UAAU,GAAG,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;QAE7C,KAAK,gBAAgB,EAAE,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,kBAAkB;AAElB;;;;;;GAMG;AACH,KAAK,UAAU,cAAc,CAAC,SAA8B;IAE1D,gKAAgK;IAChK,sGAAsG;IACtG,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAEvC,UAAU,GAAG,GAAG,CAAC,IAAI,CAAC,GAAS,EAAE,CAAC,SAAS,EAAE,GAAS,EAAE,CAAC,SAAS,CAAC,CAAC;IAEpE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,mBAAmB;AAEnB;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc;IAElC,IAAG,CAAC,aAAa,IAAI,CAAC,WAAW,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;QAEhE,OAAO;IACT,CAAC;IAED,6JAA6J;IAC7J,MAAM,OAAO,GAAG,WAAW,CAAC;IAC5B,MAAM,UAAU,GAAG,WAAW,CAAC;IAE/B,WAAW,GAAG,EAAE,CAAC;IAEjB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEjC,OAAO,cAAc,CAAC,KAAK,IAAmB,EAAE;QAE9C,IAAI,CAAC;YAEH,MAAM,UAAU,CAAC,UAAU,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC5D,CAAC;QAAC,OAAM,KAAK,EAAE,CAAC;YAEd,wDAAwD;YACxD,UAAU,GAAG,IAAI,CAAC;YAClB,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAExB,8BAA8B;YAC9B,sCAAsC;YACtC,OAAO,CAAC,KAAK,CAAC,wEAAwE,EACpF,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC,CAAC;QAC3F,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAEhC,IAAG,CAAC,aAAa,IAAI,CAAC,WAAW,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;QAEhE,OAAO;IACT,CAAC;IAED,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAErC,WAAW,GAAG,EAAE,CAAC;IAEjB,IAAI,CAAC;QAEH,EAAE,CAAC,cAAc,CAAC,WAAW,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IAAC,OAAM,KAAK,EAAE,CAAC;QAEd,8BAA8B;QAC9B,sCAAsC;QACtC,OAAO,CAAC,KAAK,CAAC,wCAAwC,EAAE,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACpH,CAAC;AACH,CAAC;AAED,mBAAmB;AAEnB;;GAEG;AACH,KAAK,UAAU,gBAAgB;IAE7B,IAAG,CAAC,WAAW,EAAE,CAAC;QAEhB,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QAEH,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAEjD,eAAe,GAAG,KAAK,CAAC,IAAI,CAAC;QAE7B,6JAA6J;QAC7J,0CAA0C;QAC1C,IAAG,CAAC,eAAe,GAAG,UAAU,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,CAAC;YAE1D,MAAM,WAAW,EAAE,CAAC;QACtB,CAAC;IACH,CAAC;IAAC,OAAM,KAAK,EAAE,CAAC;QAEd,iEAAiE;QACjE,IAAI,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAEtD,eAAe,GAAG,CAAC,CAAC;QACtB,CAAC;QAED,yCAAyC;QACzC,sCAAsC;QACtC,OAAO,CAAC,IAAI,CAAC,mCAAmC,EAAE,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9G,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAe,EAAE,OAAe;IAEvE,uCAAuC;IACvC,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;IAE3C,6EAA6E;IAC7E,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,UAAU,CAAC;IAEhD,IAAG,WAAW,IAAI,CAAC,EAAE,CAAC;QAEpB,mDAAmD;QACnD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,uEAAuE;IACvE,IAAI,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAEnD,IAAG,SAAS,KAAK,CAAC,CAAC,EAAE,CAAC;QAEpB,+DAA+D;QAC/D,SAAS,GAAG,WAAW,CAAC;IAC1B,CAAC;SAAM,CAAC;QAEN,2BAA2B;QAC3B,SAAS,IAAI,CAAC,CAAC;IACjB,CAAC;IAED,OAAO,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,WAAW;IAExB,IAAG,CAAC,WAAW,EAAE,CAAC;QAEhB,OAAO;IACT,CAAC;IAED,mHAAmH;IACnH,MAAM,UAAU,GAAG,WAAW,CAAC;IAE/B,OAAO,cAAc,CAAC,KAAK,IAAmB,EAAE;QAE9C,IAAI,CAAC;YAEH,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;YAC/D,MAAM,cAAc,GAAG,wBAAwB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YAErE,IAAG,cAAc,KAAK,IAAI,EAAE,CAAC;gBAE3B,OAAO;YACT,CAAC;YAED,oDAAoD;YACpD,MAAM,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;YAErC,MAAM,UAAU,CAAC,SAAS,CAAC,QAAQ,EAAE,cAAc,EAAE,OAAO,CAAC,CAAC;YAC9D,MAAM,UAAU,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YAE9C,eAAe,GAAG,cAAc,CAAC,MAAM,CAAC;QAC1C,CAAC;QAAC,OAAM,KAAK,EAAE,CAAC;YAEd,8EAA8E;YAC9E,sCAAsC;YACtC,OAAO,CAAC,IAAI,CAAC,8BAA8B,EAAE,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACzG,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,YAAY;AAEZ;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAEhC,IAAG,CAAC,aAAa,EAAE,CAAC;QAElB,OAAO;IACT,CAAC;IAED,wBAAwB;IACxB,IAAG,UAAU,EAAE,CAAC;QAEd,aAAa,CAAC,UAAU,CAAC,CAAC;QAC1B,UAAU,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,wCAAwC;IACxC,kBAAkB,EAAE,CAAC;IAErB,2JAA2J;IAC3J,uJAAuJ;IACvJ,aAAa,GAAG,KAAK,CAAC;IACtB,UAAU,GAAG,KAAK,CAAC;IACnB,UAAU,GAAG,CAAC,CAAC;IACf,WAAW,GAAG,EAAE,CAAC;IACjB,eAAe,GAAG,CAAC,CAAC;IACpB,UAAU,GAAG,CAAC,CAAC;IACf,WAAW,GAAG,IAAI,CAAC;IAEnB,yJAAyJ;IACzJ,UAAU,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;AACjC,CAAC"}
+{"version":3,"file":"fileLogger.js","sourceRoot":"","sources":["../../src/utils/fileLogger.ts"],"names":[],"mappings":"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"}

package/dist/utils/format.d.ts

@@ -3,9 +3,10 @@ import type { Nullable } from "../types/index.ts";
  * Formats the current date and time as a log timestamp string: `yyyy/mm/dd hh:mm:ss.mmm AM/PM`. Uses 12-hour time with decimalized seconds and AM/PM.
  * Single source of truth for all log timestamp formatting - used by the console wrapper in app.ts, the file logger, the Morgan HTTP request logger, and the SSE log
  * emitter.
+ * @param now - The instant to format, as epoch milliseconds; defaults to the system clock's reading.
  * @returns Formatted timestamp string.
  */
-export declare function formatTimestamp(): string;
+export declare function formatTimestamp(now?: number): string;
 /**
  * Formats a duration as a human-readable string. The format varies based on duration length:
  * - Less than 60 seconds: "17s"
@@ -22,12 +23,36 @@ export declare function formatDuration(value: number, unit?: "ms" | "s"): string
  * Formats a Unix millisecond timestamp as a human-readable relative time string (e.g., "2 minutes ago", "3 hours ago", "5 days ago"). Used for health indicator
  * tooltips where absolute timestamps would be harder to interpret at a glance.
  * @param timestamp - Unix millisecond timestamp.
+ * @param now - The instant the distance is measured from, as epoch milliseconds; defaults to the system clock's reading.
  * @returns Relative time string.
  */
-export declare function formatTimeAgo(timestamp: number): string;
+export declare function formatTimeAgo(timestamp: number, now?: number): string;
+/**
+ * Display labels for the standard vertical resolutions, keyed by the height in pixels. This is the single source of truth for the label a resolution is shown
+ * under: the native HLS quality suffix in the log, the stream detail's codec line in the web UI, and anything else that renders a resolution to a person all
+ * read it from here. A height with no entry has no standard label, and its caller falls back to the raw resolution string.
+ */
+export declare const RESOLUTION_LABELS: Record<string, string>;
+/**
+ * Formats a pixel size as the "WIDTHxHEIGHT" string the codebase carries resolutions in. This is the one producer of that form, and it matches the shape the
+ * native probe reads verbatim out of a manifest's RESOLUTION attribute, so a resolution that came off the wire and one this function built are the same string
+ * to every consumer downstream - the label lookup below included.
+ * @param width - The width in pixels.
+ * @param height - The height in pixels.
+ * @returns The size as "WIDTHxHEIGHT".
+ */
+export declare function formatResolution(width: number, height: number): string;
+/**
+ * Formats a "WIDTHxHEIGHT" resolution string as its standard display label, falling back to the resolution string itself when the height carries no standard
+ * label. The fallback is what keeps a non-standard rendition visible rather than dropped: a 1234x999 variant renders as "1234x999" instead of disappearing.
+ * @param resolution - The resolution as "WIDTHxHEIGHT".
+ * @returns The display label, or the resolution string when the height has no label.
+ */
+export declare function formatResolutionLabel(resolution: string): 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 service name is configured.
+ * "www.hulu.com" becomes "hulu.com"). An IP-literal host is returned whole, because an address has no registrable domain to shorten. Used as a standard domain key
+ * for DOMAIN_CONFIG lookups and as a display fallback when no service name is configured.
  * @param url - The URL to extract the domain from.
  * @returns The concise domain, or the original URL if parsing fails.
  */
@@ -42,6 +67,14 @@ export declare function extractDomain(url: string): string;
  * @returns The pathname, or null when parsing fails.
  */
 export declare function extractPathname(url: string): Nullable<string>;
+/**
+ * Resolves a potentially relative URL against a base URL. Handles both absolute and relative URLs.
+ *
+ * @param url - The URL to resolve (may be relative or absolute).
+ * @param baseUrl - The base URL for resolving relative references.
+ * @returns The resolved absolute URL.
+ */
+export declare function resolveUrl(url: string, baseUrl: string): string;
 /**
  * Capitalizes the first letter of a string.
  * @param str - The string to capitalize.
@@ -56,4 +89,3 @@ export declare function capitalize(str: string): string;
  * @returns The JSON string.
  */
 export declare function stringifySorted(data: unknown, indent?: number): string;
-//# sourceMappingURL=format.d.ts.map