prismcast 1.8.0 → 1.10.0

package/dist/utils/m3u.js

@@ -8,15 +8,32 @@
  */
 // Maximum length for generated channel keys.
 const MAX_KEY_LENGTH = 50;
+/**
+ * Escapes a string for safe inclusion as an M3U quoted attribute value (the `value` portion of `attribute="value"`). RFC 8216 section 4.2 forbids the
+ * double-quote character (the attribute terminator) and bare line feed / carriage return inside a quoted-string and defines no escape sequence; the de-facto
+ * extended-M3U convention used by VLC, IPTV-Org tooling, and downstream consumers is backslash-escaping. We backslash-escape the structural characters and
+ * replace literal CR/LF with a single space - there is no portable escape sequence for line breaks inside a quoted-string, and dropping the line break entirely
+ * would silently glue adjacent words together while leaving the attribute syntactically valid. Apply this helper at every M3U attribute write site that flows
+ * user-controlled content; structurally server-controlled values (validated channel keys, numeric fields, fixed literals) do not need it but pass through
+ * unchanged when wrapped, so prefer wrapping for uniformity.
+ *
+ * Order matters: the backslash replacement runs first so the backslashes we introduce when escaping double-quote do not get re-escaped by a second pass.
+ *
+ * @param value - The raw string to escape.
+ * @returns A string safe to embed between the surrounding double-quotes of an M3U attribute value.
+ */
+export function escapeM3uAttribute(value) {
+    return value.replace(/[\r\n]+/g, " ").replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+}
 /**
  * Generates a URL-safe channel key from a display name. The key is used as the channel identifier in URLs and configuration.
  * @param name - The display name to convert.
  * @returns A lowercase, hyphen-separated key suitable for URLs.
  *
  * Examples:
- * - "CNN Live!" → "cnn-live"
- * - "BBC News 24/7" → "bbc-news-247"
- * - "  Spaces  Everywhere  " → "spaces-everywhere"
+ * - "CNN Live!" -> "cnn-live"
+ * - "BBC News 24/7" -> "bbc-news-247"
+ * - "  Spaces  Everywhere  " -> "spaces-everywhere"
  */
 export function generateChannelKey(name) {
     return name.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, MAX_KEY_LENGTH);
@@ -30,17 +47,14 @@ export function generateChannelKey(name) {
 function extractAttribute(line, attribute) {
     // Match attribute="value" (quoted).
     const quotedPattern = new RegExp(attribute + "=\"([^\"]*)\"", "i");
-    const quotedMatch = line.match(quotedPattern);
-    if (quotedMatch) {
-        return quotedMatch[1];
+    const quotedValue = line.match(quotedPattern)?.[1];
+    if (quotedValue !== undefined) {
+        return quotedValue;
     }
     // Match attribute=value (unquoted, ends at space or comma).
     const unquotedPattern = new RegExp(attribute + "=([^\\s,\"]+)", "i");
-    const unquotedMatch = line.match(unquotedPattern);
-    if (unquotedMatch) {
-        return unquotedMatch[1];
-    }
-    return null;
+    const unquotedValue = line.match(unquotedPattern)?.[1];
+    return unquotedValue ?? null;
 }
 /**
  * Extracts the display name from an #EXTINF line. First tries tvg-name attribute, then falls back to the comma-separated suffix.
@@ -53,7 +67,7 @@ function extractName(line) {
     if (tvgName && (tvgName.trim().length > 0)) {
         return tvgName.trim();
     }
-    // Fall back to comma suffix (the part after the last comma in #EXTINF line). Format: #EXTINF:-1 attributes,Display Name
+    // Fall back to comma suffix (the part after the last comma in #EXTINF line). Format: "#EXTINF:-1 attributes,Display Name".
     const commaIndex = line.lastIndexOf(",");
     if (commaIndex !== -1) {
         const suffix = line.slice(commaIndex + 1).trim();
@@ -91,9 +105,9 @@ export function parseM3U(content) {
     const errors = [];
     const lines = content.split(/\r?\n/);
     let pendingExtinf = null;
-    for (let i = 0; i < lines.length; i++) {
+    for (const [i, rawLine] of lines.entries()) {
         const lineNumber = i + 1;
-        const line = lines[i].trim();
+        const line = rawLine.trim();
         // Skip empty lines and comments (except #EXTINF).
         if ((line.length === 0) || ((line.startsWith("#")) && !line.startsWith("#EXTINF"))) {
             continue;

package/dist/utils/m3u.js.map

@@ -1 +1 @@
-{"version":3,"file":"m3u.js","sourceRoot":"","sources":["../../src/utils/m3u.ts"],"names":[],"mappings":"AAMA;;;;;;;GAOG;AAEH,6CAA6C;AAC7C,MAAM,cAAc,GAAG,EAAE,CAAC;AA6B1B;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAE7C,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;AACjJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,IAAY,EAAE,SAAiB;IAEvD,oCAAoC;IACpC,MAAM,aAAa,GAAG,IAAI,MAAM,CAAC,SAAS,GAAG,eAAe,EAAE,GAAG,CAAC,CAAC;IACnE,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAE9C,IAAG,WAAW,EAAE,CAAC;QAEf,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC;IAED,4DAA4D;IAC5D,MAAM,eAAe,GAAG,IAAI,MAAM,CAAC,SAAS,GAAG,eAAe,EAAE,GAAG,CAAC,CAAC;IACrE,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAElD,IAAG,aAAa,EAAE,CAAC;QAEjB,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,IAAY;IAE/B,gCAAgC;IAChC,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAEnD,IAAG,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QAE1C,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;IACxB,CAAC;IAED,wHAAwH;IACxH,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAEzC,IAAG,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;QAErB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAEjD,IAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAErB,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,IAAY;IAEpC,iEAAiE;IACjE,MAAM,YAAY,GAAG,gBAAgB,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC;IAEnE,IAAG,YAAY,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QAEpD,OAAO,YAAY,CAAC,IAAI,EAAE,CAAC;IAC7B,CAAC;IAED,uBAAuB;IACvB,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAE/C,IAAG,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QAEtC,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;IACtB,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAe;IAEtC,MAAM,QAAQ,GAAiB,EAAE,CAAC;IAClC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAErC,IAAI,aAAa,GAAuE,IAAI,CAAC;IAE7F,KAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAErC,MAAM,UAAU,GAAG,CAAC,GAAG,CAAC,CAAC;QACzB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAE7B,kDAAkD;QAClD,IAAG,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;YAElF,SAAS;QACX,CAAC;QAED,sBAAsB;QACtB,IAAG,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAE/B,+DAA+D;YAC/D,IAAG,aAAa,EAAE,CAAC;gBAEjB,MAAM,CAAC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,GAAG,8BAA8B,CAAC,CAAC;YAC3F,CAAC;YAED,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;YAE/B,IAAG,CAAC,IAAI,EAAE,CAAC;gBAET,MAAM,CAAC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,gDAAgD,CAAC,CAAC;gBAC7F,aAAa,GAAG,IAAI,CAAC;gBAErB,SAAS;YACX,CAAC;YAED,aAAa,GAAG;gBAEd,UAAU;gBACV,IAAI;gBACJ,SAAS,EAAE,gBAAgB,CAAC,IAAI,CAAC;aAClC,CAAC;YAEF,SAAS;QACX,CAAC;QAED,2CAA2C;QAC3C,IAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAE7D,IAAG,CAAC,aAAa,EAAE,CAAC;gBAElB,qEAAqE;gBACrE,SAAS;YACX,CAAC;YAED,QAAQ,CAAC,IAAI,CAAC;gBAEZ,IAAI,EAAE,aAAa,CAAC,IAAI;gBACxB,SAAS,EAAE,aAAa,CAAC,SAAS;gBAClC,GAAG,EAAE,IAAI;aACV,CAAC,CAAC;YAEH,aAAa,GAAG,IAAI,CAAC;YAErB,SAAS;QACX,CAAC;QAED,uCAAuC;IACzC,CAAC;IAED,0CAA0C;IAC1C,IAAG,aAAa,EAAE,CAAC;QAEjB,MAAM,CAAC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,GAAG,8BAA8B,CAAC,CAAC;IAC3F,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"m3u.js","sourceRoot":"","sources":["../../src/utils/m3u.ts"],"names":[],"mappings":"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"}

package/dist/utils/memo.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Wraps an async probe in a one-shot memoization closure. The returned function:
+ *
+ * - On first call: invokes probe(), caches the resolved value, returns it.
+ * - On concurrent first-calls (multiple callers arriving before the first probe resolves): all callers share the single in-flight promise, so probe is
+ *   invoked exactly once regardless of arrival order.
+ * - On subsequent calls after first success: returns the cached value directly without invoking probe.
+ * - On probe rejection: the rejection is sticky. Every subsequent call returns the same rejected promise without re-probing. This is by design - retrying
+ *   a probe that has demonstrated it can fail risks a retry storm; if the caller wants retry semantics, they should compose memoizeAsync with a retry helper
+ *   rather than have memoizeAsync silently retry. (Production-cached resolveFFmpegPath has no rejection path - probeFFmpegPath returns undefined for "not
+ *   found" rather than throwing - so this branch never fires in the ffmpeg use case.)
+ *
+ * The cache and pending state are closure-scoped: there is no test seam, no reset method, and no way for callers to invalidate the cache. Callers that need
+ * invalidation are doing a different thing (TTL cache, refresh-on-event cache) and should not use this primitive.
+ *
+ * @param probe - The async function to memoize. Invoked at most once on success, or once per process on rejection.
+ * @returns A function that returns the same Promise<T> on every call.
+ */
+export declare function memoizeAsync<T>(probe: () => Promise<T>): () => Promise<T>;

package/dist/utils/memo.js

@@ -0,0 +1,53 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * memo.ts: Async memoization primitives. The single primitive here is memoizeAsync - a one-shot async cache that runs its probe at most once across the
+ * lifetime of the returned function and shares the in-flight promise across concurrent first-callers. Used to lazily compute values that are expensive on
+ * first call and cheap-to-cached on subsequent calls (e.g., resolveFFmpegPath probing the filesystem).
+ */
+/**
+ * Wraps an async probe in a one-shot memoization closure. The returned function:
+ *
+ * - On first call: invokes probe(), caches the resolved value, returns it.
+ * - On concurrent first-calls (multiple callers arriving before the first probe resolves): all callers share the single in-flight promise, so probe is
+ *   invoked exactly once regardless of arrival order.
+ * - On subsequent calls after first success: returns the cached value directly without invoking probe.
+ * - On probe rejection: the rejection is sticky. Every subsequent call returns the same rejected promise without re-probing. This is by design - retrying
+ *   a probe that has demonstrated it can fail risks a retry storm; if the caller wants retry semantics, they should compose memoizeAsync with a retry helper
+ *   rather than have memoizeAsync silently retry. (Production-cached resolveFFmpegPath has no rejection path - probeFFmpegPath returns undefined for "not
+ *   found" rather than throwing - so this branch never fires in the ffmpeg use case.)
+ *
+ * The cache and pending state are closure-scoped: there is no test seam, no reset method, and no way for callers to invalidate the cache. Callers that need
+ * invalidation are doing a different thing (TTL cache, refresh-on-event cache) and should not use this primitive.
+ *
+ * @param probe - The async function to memoize. Invoked at most once on success, or once per process on rejection.
+ * @returns A function that returns the same Promise<T> on every call.
+ */
+export function memoizeAsync(probe) {
+    let state = { kind: "unset" };
+    return async () => {
+        switch (state.kind) {
+            case "resolved": {
+                // Fast path: return the cached value directly. TypeScript narrows state.value to T on this branch.
+                return state.value;
+            }
+            case "pending": {
+                // Concurrent caller (or a follow-up caller during a sticky-rejection state). Share the single in-flight promise.
+                return state.promise;
+            }
+            case "unset": {
+                /* First call. Kick off the probe and chain a success handler that flips state to "resolved". The chained promise is what callers receive: when probe
+                 * succeeds, the .then() callback runs, state becomes "resolved", and the chained promise resolves with the value. When probe rejects, the .then()
+                 * callback never runs (no onRejected handler) and the chained promise rejects, so state stays "pending" carrying the rejected promise - all future
+                 * callers receive the same rejection.
+                 */
+                const promise = probe().then((value) => {
+                    state = { kind: "resolved", value };
+                    return value;
+                });
+                state = { kind: "pending", promise };
+                return promise;
+            }
+        }
+    };
+}
+//# sourceMappingURL=memo.js.map

package/dist/utils/memo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memo.js","sourceRoot":"","sources":["../../src/utils/memo.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAeH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAAI,KAAuB;IAErD,IAAI,KAAK,GAAiB,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAE5C,OAAO,KAAK,IAAgB,EAAE;QAE5B,QAAO,KAAK,CAAC,IAAI,EAAE,CAAC;YAElB,KAAK,UAAU,CAAC,CAAC,CAAC;gBAEhB,mGAAmG;gBACnG,OAAO,KAAK,CAAC,KAAK,CAAC;YACrB,CAAC;YAED,KAAK,SAAS,CAAC,CAAC,CAAC;gBAEf,iHAAiH;gBACjH,OAAO,KAAK,CAAC,OAAO,CAAC;YACvB,CAAC;YAED,KAAK,OAAO,CAAC,CAAC,CAAC;gBAEb;;;;mBAIG;gBACH,MAAM,OAAO,GAAG,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;oBAErC,KAAK,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;oBAEpC,OAAO,KAAK,CAAC;gBACf,CAAC,CAAC,CAAC;gBAEH,KAAK,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;gBAErC,OAAO,OAAO,CAAC;YACjB,CAAC;QACH,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/utils/morganStream.js

@@ -1,4 +1,4 @@
-import df from "dateformat";
+import { formatTimestamp } from "./format.js";
 import { isConsoleLogging } from "./logger.js";
 import { writeLogEntry } from "./fileLogger.js";
 /* Morgan HTTP request logger needs a writable stream to output log entries. By default, Morgan writes to stdout. This adapter routes Morgan output to either the
@@ -19,13 +19,13 @@ export function createMorganStream() {
             const trimmedMessage = message.trim();
             if (isConsoleLogging()) {
                 // Console logging mode - add timestamp prefix and write to stdout.
-                const timestamp = df(new Date(), "yyyy/mm/dd HH:MM:ss.l");
+                const timestamp = formatTimestamp();
                 // eslint-disable-next-line no-console
                 console.log(["[", timestamp, "] ", trimmedMessage].join(""));
             }
             else {
-                // File logging mode - route through the file logger which adds its own timestamp.
-                writeLogEntry("info", trimmedMessage);
+                // File logging mode - route through the file logger which adds its own timestamp. HTTP request logs use the default terminal color, matching info-level output.
+                writeLogEntry("info", trimmedMessage, null);
             }
         }
     };

package/dist/utils/morganStream.js.map

@@ -1 +1 @@
-{"version":3,"file":"morganStream.js","sourceRoot":"","sources":["../../src/utils/morganStream.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,UAAU,kBAAkB;IAEhC,OAAO;QAEL,KAAK,EAAE,CAAC,OAAe,EAAQ,EAAE;YAE/B,8EAA8E;YAC9E,MAAM,cAAc,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;YAEtC,IAAG,gBAAgB,EAAE,EAAE,CAAC;gBAEtB,mEAAmE;gBACnE,MAAM,SAAS,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,EAAE,uBAAuB,CAAC,CAAC;gBAE1D,sCAAsC;gBACtC,OAAO,CAAC,GAAG,CAAC,CAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,cAAc,CAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YACjE,CAAC;iBAAM,CAAC;gBAEN,kFAAkF;gBAClF,aAAa,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"morganStream.js","sourceRoot":"","sources":["../../src/utils/morganStream.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,UAAU,kBAAkB;IAEhC,OAAO;QAEL,KAAK,EAAE,CAAC,OAAe,EAAQ,EAAE;YAE/B,8EAA8E;YAC9E,MAAM,cAAc,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;YAEtC,IAAG,gBAAgB,EAAE,EAAE,CAAC;gBAEtB,mEAAmE;gBACnE,MAAM,SAAS,GAAG,eAAe,EAAE,CAAC;gBAEpC,sCAAsC;gBACtC,OAAO,CAAC,GAAG,CAAC,CAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,cAAc,CAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YACjE,CAAC;iBAAM,CAAC;gBAEN,gKAAgK;gBAChK,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/utils/pid.d.ts

@@ -1,7 +1,7 @@
-import type { Nullable } from "../types/index.js";
+import type { Nullable } from "../types/index.ts";
 /**
  * Checks whether a process with the given PID is still running. Uses the signal 0 technique: process.kill(pid, 0) throws ESRCH if the process does not exist,
- * returns successfully if it does. EPERM (permission denied) means the process exists but belongs to another user — treated as "still running" since we cannot
+ * returns successfully if it does. EPERM (permission denied) means the process exists but belongs to another user - treated as "still running" since we cannot
  * kill it anyway. This is cross-platform and works on macOS, Linux, and Windows without external tools.
  * @param pid - The process ID to check.
  * @returns True if the process is running, false if it has exited.

package/dist/utils/pid.js

@@ -1,14 +1,14 @@
 import fs from "node:fs";
 /* PID files provide a lightweight mechanism for tracking running processes across restarts and crashes. Each PID file stores a single process ID as a plain text
  * integer. On startup, the stored PID is checked via signal 0 to determine whether the process is still alive. Stale PID files from crashed or terminated processes
- * are handled gracefully — ENOENT on read and ESRCH on signal check are both expected and silently ignored.
+ * are handled gracefully - ENOENT on read and ESRCH on signal check are both expected and silently ignored.
  *
  * This module is intentionally synchronous. PID file operations run in contexts where the event loop may not be available (process.on("exit") handlers), so all
  * I/O uses the synchronous fs API and process.kill() for signaling.
  */
 /**
  * Checks whether a process with the given PID is still running. Uses the signal 0 technique: process.kill(pid, 0) throws ESRCH if the process does not exist,
- * returns successfully if it does. EPERM (permission denied) means the process exists but belongs to another user — treated as "still running" since we cannot
+ * returns successfully if it does. EPERM (permission denied) means the process exists but belongs to another user - treated as "still running" since we cannot
  * kill it anyway. This is cross-platform and works on macOS, Linux, and Windows without external tools.
  * @param pid - The process ID to check.
  * @returns True if the process is running, false if it has exited.

package/dist/utils/platform.d.ts

@@ -1,4 +1,4 @@
-import type { Nullable } from "../types/index.js";
+import type { Nullable } from "../types/index.ts";
 export type Platform = "darwin" | "linux" | "windows";
 export type ServiceManager = "launchd" | "systemd" | "windows-scheduler";
 export declare const SERVICE_ID = "com.github.hjdhjd.prismcast";

package/dist/utils/platform.js

@@ -88,8 +88,9 @@ export function getServiceFilePath() {
             return path.join(homeDir, ".config", "systemd", "user", "prismcast.service");
         }
         case "windows": {
-            // Windows Task Scheduler doesn't use a file path in the same way. We return a marker path inside the data directory for consistency.
-            return path.join(getDataDir(), "service-installed.marker");
+            // The PowerShell launcher script is the primary service file on Windows. It contains the runtime configuration (working directory, environment variables,
+            // node and entry point paths) and serves as the single source of truth for stale path detection. Task Scheduler invokes this launcher at user logon.
+            return path.join(getDataDir(), "prismcast-service.ps1");
         }
         default: {
             return "";

package/dist/utils/platform.js.map

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

package/dist/utils/retry.d.ts

@@ -1,8 +1,10 @@
+import { type Clock } from "./clock.ts";
 /**
  * Options for retryOperation. Groups all parameters into a single object to avoid positional parameter sprawl and make the function extensible.
  */
 export interface RetryOptions<T> {
     backoffJitter?: number;
+    clock?: Clock;
     description: string;
     earlySuccessCheck?: () => Promise<boolean>;
     maxAttempts: number;

package/dist/utils/retry.js

@@ -1,8 +1,10 @@
 /* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
  *
- * retry.ts: Retry logic with exponential backoff for PrismCast.
+ * retry.ts: Retry logic with exponential backoff for PrismCast. Time-dependent operations route through a Clock (see clock.ts) so tests can deterministically
+ * control sleeps and timeout races without depending on real-time delays - the function's nested raceWithTimeout/Promise.race/finally/await delay chain is
+ * exactly the shape Node's synchronous mock.timers.tick cannot drain.
  */
-import { delay, raceWithTimeout } from "./delay.js";
+import { realClock } from "./clock.js";
 import { formatError, isSessionClosedError } from "./errors.js";
 import { LOG } from "./logger.js";
 /**
@@ -13,7 +15,7 @@ import { LOG } from "./logger.js";
  * @throws The last error encountered if all attempts fail.
  */
 export async function retryOperation(options) {
-    const { backoffJitter = 1000, description, earlySuccessCheck, maxAttempts, maxBackoffDelay = 3000, operation, shouldAbort, timeoutMs } = options;
+    const { backoffJitter = 1000, clock = realClock, description, earlySuccessCheck, maxAttempts, maxBackoffDelay = 3000, operation, shouldAbort, timeoutMs } = options;
     let lastError = null;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         // Check if we should abort before starting this attempt. This catches cases where the page was closed during the backoff delay between retries.
@@ -25,7 +27,7 @@ export async function retryOperation(options) {
         }
         try {
             // eslint-disable-next-line no-await-in-loop
-            return await raceWithTimeout(operation(), timeoutMs);
+            return await clock.raceWithTimeout(operation(), timeoutMs);
         }
         catch (error) {
             lastError = error;
@@ -49,13 +51,13 @@ export async function retryOperation(options) {
                 }
             }
             // If we reach here, we're going to retry (or fail after max attempts). Now log the warning since there's an actual issue to report.
-            LOG.warn("Attempt %s failed for %s: %s", attempt, description, formatError(error));
+            LOG.warn("Attempt %s failed for %s: %s.", attempt, description, formatError(error));
             // Between retry attempts, wait with exponential backoff plus random jitter.
             if (attempt < maxAttempts) {
-                const baseDelay = Math.min(1000 * Math.pow(2, attempt - 1), maxBackoffDelay);
+                const baseDelay = Math.min(1000 * (2 ** (attempt - 1)), maxBackoffDelay);
                 const jitter = Math.random() * backoffJitter;
                 // eslint-disable-next-line no-await-in-loop
-                await delay(baseDelay + jitter);
+                await clock.sleep(baseDelay + jitter);
             }
         }
     }

package/dist/utils/retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAuClC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAI,OAAwB;IAE9D,MAAM,EAAE,aAAa,GAAG,IAAI,EAAE,WAAW,EAAE,iBAAiB,EAAE,WAAW,EAAE,eAAe,GAAG,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAEjJ,IAAI,SAAS,GAAY,IAAI,CAAC;IAE9B,KAAI,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QAEvD,gJAAgJ;QAChJ,IAAG,WAAW,EAAE,EAAE,EAAE,CAAC;YAEnB,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,CAAC;QAED,IAAG,OAAO,GAAG,CAAC,EAAE,CAAC;YAEf,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,iCAAiC,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;QAC3F,CAAC;QAED,IAAI,CAAC;YAEH,4CAA4C;YAC5C,OAAO,MAAM,eAAe,CAAC,SAAS,EAAE,EAAE,SAAS,CAAC,CAAC;QACvD,CAAC;QAAC,OAAM,KAAK,EAAE,CAAC;YAEd,SAAS,GAAG,KAAK,CAAC;YAElB,8HAA8H;YAC9H,IAAG,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAE/B,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,2CAA2C,EAAE,WAAW,CAAC,CAAC;gBAE7E,MAAM,KAAK,CAAC;YACd,CAAC;YAED,6JAA6J;YAC7J,gKAAgK;YAChK,IAAG,iBAAiB,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;gBAEjE,IAAI,CAAC;oBAEH,4CAA4C;oBAC5C,MAAM,aAAa,GAAG,MAAM,iBAAiB,EAAE,CAAC;oBAEhD,IAAG,aAAa,EAAE,CAAC;wBAEjB,OAAO;oBACT,CAAC;gBACH,CAAC;gBAAC,OAAM,WAAW,EAAE,CAAC;oBAEpB,yDAAyD;gBAC3D,CAAC;YACH,CAAC;YAED,oIAAoI;YACpI,GAAG,CAAC,IAAI,CAAC,8BAA8B,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;YAEnF,4EAA4E;YAC5E,IAAG,OAAO,GAAG,WAAW,EAAE,CAAC;gBAEzB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;gBAC7E,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,aAAa,CAAC;gBAE7C,4CAA4C;gBAC5C,MAAM,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,SAAS,CAAC;AAClB,CAAC"}
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAc,SAAS,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AA4ClC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAI,OAAwB;IAE9D,MAAM,EAAE,aAAa,GAAG,IAAI,EAAE,KAAK,GAAG,SAAS,EAAE,WAAW,EAAE,iBAAiB,EAAE,WAAW,EAAE,eAAe,GAAG,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAEpK,IAAI,SAAS,GAAY,IAAI,CAAC;IAE9B,KAAI,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QAEvD,gJAAgJ;QAChJ,IAAG,WAAW,EAAE,EAAE,EAAE,CAAC;YAEnB,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,CAAC;QAED,IAAG,OAAO,GAAG,CAAC,EAAE,CAAC;YAEf,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,iCAAiC,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;QAC3F,CAAC;QAED,IAAI,CAAC;YAEH,4CAA4C;YAC5C,OAAO,MAAM,KAAK,CAAC,eAAe,CAAC,SAAS,EAAE,EAAE,SAAS,CAAC,CAAC;QAC7D,CAAC;QAAC,OAAM,KAAK,EAAE,CAAC;YAEd,SAAS,GAAG,KAAK,CAAC;YAElB,8HAA8H;YAC9H,IAAG,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAE/B,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,2CAA2C,EAAE,WAAW,CAAC,CAAC;gBAE7E,MAAM,KAAK,CAAC;YACd,CAAC;YAED,6JAA6J;YAC7J,gKAAgK;YAChK,IAAG,iBAAiB,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;gBAEjE,IAAI,CAAC;oBAEH,4CAA4C;oBAC5C,MAAM,aAAa,GAAG,MAAM,iBAAiB,EAAE,CAAC;oBAEhD,IAAG,aAAa,EAAE,CAAC;wBAEjB,OAAO;oBACT,CAAC;gBACH,CAAC;gBAAC,OAAM,WAAW,EAAE,CAAC;oBAEpB,yDAAyD;gBAC3D,CAAC;YACH,CAAC;YAED,oIAAoI;YACpI,GAAG,CAAC,IAAI,CAAC,+BAA+B,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;YAEpF,4EAA4E;YAC5E,IAAG,OAAO,GAAG,WAAW,EAAE,CAAC;gBAEzB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;gBACzE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,aAAa,CAAC;gBAE7C,4CAA4C;gBAC5C,MAAM,KAAK,CAAC,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,SAAS,CAAC;AAClB,CAAC"}

package/dist/utils/sanitize.d.ts

@@ -1,12 +1,12 @@
 /**
  * Strips non-printable characters from a string and trims whitespace. Replaces `.trim()` at data-collection points to ensure string values contain only visible
- * content. Safe to call on already-clean strings — the regex replacement is a no-op when no non-printable characters are present.
+ * content. Safe to call on already-clean strings - the regex replacement is a no-op when no non-printable characters are present.
  * @param value - The string to sanitize.
  * @returns The sanitized string with non-printable characters removed and whitespace trimmed.
  */
 export declare function sanitizeString(value: string): string;
 /**
- * Tests whether a string contains any non-printable characters. Used for startup warnings when loading persisted data — the warning alerts users to corruption
+ * Tests whether a string contains any non-printable characters. Used for startup warnings when loading persisted data - the warning alerts users to corruption
  * without modifying the loaded values.
  * @param value - The string to test.
  * @returns True if the string contains at least one non-printable character.

package/dist/utils/sanitize.js

@@ -10,12 +10,12 @@
  * spaces, and Unicode line/paragraph separators. TAB (\x09), LF (\x0A), and CR (\x0D) are preserved because they appear legitimately in multi-line text fields.
  */
 // Pattern matching non-printable characters. Covers: C0 controls except TAB/LF/CR, DEL, BOM, zero-width spaces, directional markers, and line/paragraph separators.
-// The no-control-regex rule is suppressed because this regex genuinely needs to match control characters — that is its entire purpose.
+// The no-control-regex rule is suppressed because this regex genuinely needs to match control characters - that is its entire purpose.
 // eslint-disable-next-line no-control-regex
 const NON_PRINTABLE_PATTERN = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F\uFEFF\u200B-\u200F\u2028-\u2029]/g;
 /**
  * Strips non-printable characters from a string and trims whitespace. Replaces `.trim()` at data-collection points to ensure string values contain only visible
- * content. Safe to call on already-clean strings — the regex replacement is a no-op when no non-printable characters are present.
+ * content. Safe to call on already-clean strings - the regex replacement is a no-op when no non-printable characters are present.
  * @param value - The string to sanitize.
  * @returns The sanitized string with non-printable characters removed and whitespace trimmed.
  */
@@ -23,13 +23,13 @@ export function sanitizeString(value) {
     return value.replace(NON_PRINTABLE_PATTERN, "").trim();
 }
 /**
- * Tests whether a string contains any non-printable characters. Used for startup warnings when loading persisted data — the warning alerts users to corruption
+ * Tests whether a string contains any non-printable characters. Used for startup warnings when loading persisted data - the warning alerts users to corruption
  * without modifying the loaded values.
  * @param value - The string to test.
  * @returns True if the string contains at least one non-printable character.
  */
 export function containsNonPrintable(value) {
-    // Reset lastIndex before testing — the global flag on NON_PRINTABLE_PATTERN causes .test() to advance lastIndex on each call, which would produce alternating
+    // Reset lastIndex before testing - the global flag on NON_PRINTABLE_PATTERN causes .test() to advance lastIndex on each call, which would produce alternating
     // true/false results without this reset.
     NON_PRINTABLE_PATTERN.lastIndex = 0;
     return NON_PRINTABLE_PATTERN.test(value);

package/dist/utils/streamContext.d.ts

@@ -4,6 +4,7 @@
  */
 export interface StreamContext {
     channelName?: string;
+    showNameResolver?: () => string;
     streamId: string;
     url?: string;
 }
@@ -26,3 +27,9 @@ export declare function getStreamContext(): StreamContext | undefined;
  * @returns The stream ID, or undefined if not running within a stream context.
  */
 export declare function getStreamId(): string | undefined;
+/**
+ * Resolves the current show name from the stream context's lazy resolver. Returns an empty string if no resolver is set or no show name is available. Named
+ * distinctly from the stream-ID-based show name lookup in the streaming module to avoid ambiguity via the barrel export in utils/index.ts.
+ * @returns The current show name, or an empty string.
+ */
+export declare function resolveContextShowName(): string;

package/dist/utils/streamContext.js

@@ -2,7 +2,7 @@
  *
  * streamContext.ts: AsyncLocalStorage-based stream context for automatic log correlation.
  */
-import { AsyncLocalStorage } from "async_hooks";
+import { AsyncLocalStorage } from "node:async_hooks";
 // AsyncLocalStorage instance for stream context. This is the core mechanism that allows context to propagate through async calls.
 const streamContextStorage = new AsyncLocalStorage();
 /**
@@ -30,4 +30,13 @@ export function getStreamContext() {
 export function getStreamId() {
     return streamContextStorage.getStore()?.streamId;
 }
+/**
+ * Resolves the current show name from the stream context's lazy resolver. Returns an empty string if no resolver is set or no show name is available. Named
+ * distinctly from the stream-ID-based show name lookup in the streaming module to avoid ambiguity via the barrel export in utils/index.ts.
+ * @returns The current show name, or an empty string.
+ */
+export function resolveContextShowName() {
+    const resolver = streamContextStorage.getStore()?.showNameResolver;
+    return resolver ? resolver() : "";
+}
 //# sourceMappingURL=streamContext.js.map

package/dist/utils/streamContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"streamContext.js","sourceRoot":"","sources":["../../src/utils/streamContext.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AA4BhD,kIAAkI;AAClI,MAAM,oBAAoB,GAAG,IAAI,iBAAiB,EAAiB,CAAC;AAEpE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAI,OAAsB,EAAE,EAAoB;IAExF,OAAO,oBAAoB,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAE9B,OAAO,oBAAoB,CAAC,QAAQ,EAAE,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW;IAEzB,OAAO,oBAAoB,CAAC,QAAQ,EAAE,EAAE,QAAQ,CAAC;AACnD,CAAC"}
+{"version":3,"file":"streamContext.js","sourceRoot":"","sources":["../../src/utils/streamContext.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAgCrD,kIAAkI;AAClI,MAAM,oBAAoB,GAAG,IAAI,iBAAiB,EAAiB,CAAC;AAEpE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAI,OAAsB,EAAE,EAAoB;IAExF,OAAO,oBAAoB,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAE9B,OAAO,oBAAoB,CAAC,QAAQ,EAAE,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW;IAEzB,OAAO,oBAAoB,CAAC,QAAQ,EAAE,EAAE,QAAQ,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB;IAEpC,MAAM,QAAQ,GAAG,oBAAoB,CAAC,QAAQ,EAAE,EAAE,gBAAgB,CAAC;IAEnE,OAAO,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACpC,CAAC"}

package/dist/utils/timing.d.ts

@@ -1,5 +1,8 @@
+import { type Clock } from "./clock.ts";
 /**
- * Creates a lightweight elapsed-time closure using performance.now(). Call the returned function to get the elapsed milliseconds since creation.
- * @returns A closure that returns elapsed milliseconds as a number.
+ * Creates a lightweight elapsed-time closure. Captures the clock's current reading at creation and rounds the elapsed delta on each call. Production callers
+ * pass no argument and consume the realClock default; tests inject a fake clock for deterministic time control.
+ * @param clock - The clock to read time from. Defaults to realClock (which wraps performance.now()).
+ * @returns A closure that returns elapsed milliseconds as a rounded integer.
  */
-export declare function startTimer(): () => number;
+export declare function startTimer(clock?: Clock): () => number;

package/dist/utils/timing.js

@@ -1,13 +1,17 @@
 /* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
  *
- * timing.ts: Timing measurement utilities for PrismCast.
+ * timing.ts: Timing measurement utilities for PrismCast. Reads the clock through the Clock port (see clock.ts) so tests can inject a deterministic time source;
+ * production callers omit the argument and the default-argument wires through to realClock which delegates to performance.now().
  */
+import { realClock } from "./clock.js";
 /**
- * Creates a lightweight elapsed-time closure using performance.now(). Call the returned function to get the elapsed milliseconds since creation.
- * @returns A closure that returns elapsed milliseconds as a number.
+ * Creates a lightweight elapsed-time closure. Captures the clock's current reading at creation and rounds the elapsed delta on each call. Production callers
+ * pass no argument and consume the realClock default; tests inject a fake clock for deterministic time control.
+ * @param clock - The clock to read time from. Defaults to realClock (which wraps performance.now()).
+ * @returns A closure that returns elapsed milliseconds as a rounded integer.
  */
-export function startTimer() {
-    const start = performance.now();
-    return () => Math.round(performance.now() - start);
+export function startTimer(clock = realClock) {
+    const start = clock.now();
+    return () => Math.round(clock.now() - start);
 }
 //# sourceMappingURL=timing.js.map

package/dist/utils/timing.js.map

@@ -1 +1 @@
-{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../src/utils/timing.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,UAAU,UAAU;IAExB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAEhC,OAAO,GAAW,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;AAC7D,CAAC"}
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../src/utils/timing.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAc,SAAS,EAAE,MAAM,YAAY,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,QAAe,SAAS;IAEjD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;IAE1B,OAAO,GAAW,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;AACvD,CAAC"}

package/dist/utils/version.d.ts

@@ -1,6 +1,7 @@
-import type { Nullable } from "../types/index.js";
+import type { Nullable } from "../types/index.ts";
 /**
- * Gets the current package version from package.json.
+ * Gets the current package version from package.json. Resolved at module load via the JSON import attribute, so the value is structurally guaranteed and the
+ * lookup is a constant-time field read.
  * @returns The current version string (e.g., "1.0.7").
  */
 export declare function getPackageVersion(): string;

package/dist/utils/version.js

@@ -3,38 +3,25 @@
  * version.ts: Version checking and update notification utilities.
  */
 import { LOG } from "./logger.js";
-import { fileURLToPath } from "url";
 import { formatError } from "./errors.js";
-import { readFileSync } from "fs";
-import { resolve } from "path";
+import packageJson from "../../package.json" with { type: "json" };
 // Package name for npm registry lookups.
 const NPM_PACKAGE_NAME = "prismcast";
-// Cached package version.
-let cachedPackageVersion = null;
 /**
- * Gets the current package version from package.json.
+ * Gets the current package version from package.json. Resolved at module load via the JSON import attribute, so the value is structurally guaranteed and the
+ * lookup is a constant-time field read.
  * @returns The current version string (e.g., "1.0.7").
  */
 export function getPackageVersion() {
-    if (cachedPackageVersion) {
-        return cachedPackageVersion;
-    }
-    try {
-        // Resolve the path to package.json relative to this file. This file is in src/utils/ or dist/utils/, and package.json is in the project root.
-        const currentDir = fileURLToPath(new URL(".", import.meta.url));
-        const packagePath = resolve(currentDir, "../../package.json");
-        const packageJson = JSON.parse(readFileSync(packagePath, "utf-8"));
-        cachedPackageVersion = packageJson.version;
-        return cachedPackageVersion;
-    }
-    catch {
-        return "0.0.0";
-    }
+    return packageJson.version;
 }
 // GitHub raw URL for fetching changelog.
 const CHANGELOG_URL = "https://raw.githubusercontent.com/hjdhjd/prismcast/main/Changelog.md";
 // How often to check for updates (2 hours in milliseconds).
 const UPDATE_CHECK_INTERVAL = 2 * 60 * 60 * 1000;
+// Minimum interval between consecutive checkForUpdates() calls. Multiple invocations within this window collapse into a single check, preventing duplicate
+// network traffic when both the startup notification path and the periodic interval timer fire close together. Bypassed when the caller passes force=true.
+const UPDATE_CHECK_DEBOUNCE = 60 * 1000;
 // Cached version information.
 let cachedLatestVersion = null;
 let cachedChangelog = null;
@@ -75,7 +62,7 @@ export function isVersionLessThan(a, b) {
  */
 export async function fetchLatestVersion() {
     try {
-        const response = await fetch("https://registry.npmjs.org/" + NPM_PACKAGE_NAME);
+        const response = await fetch("https://registry.npmjs.org/" + NPM_PACKAGE_NAME, { signal: AbortSignal.timeout(5000) });
         if (!response.ok) {
             return null;
         }
@@ -94,7 +81,7 @@ export async function fetchLatestVersion() {
  */
 async function fetchChangelogContent() {
     try {
-        const response = await fetch(CHANGELOG_URL);
+        const response = await fetch(CHANGELOG_URL, { signal: AbortSignal.timeout(5000) });
         if (!response.ok) {
             return null;
         }
@@ -112,15 +99,15 @@ async function fetchChangelogContent() {
  * @returns The changelog entry for the version, or null if not found.
  */
 function extractVersionChangelog(changelog, version) {
-    // Match the version header and capture everything until the next version header or end of file. The changelog format is: ## 1.0.8 (date)
-    // Note: We use (?![^]) instead of $ for end-of-string because the m flag makes $ match end-of-line, which would stop the non-greedy *? at the first line.
-    const pattern = new RegExp("^## " + version.replace(/\./g, "\\.") + "\\s+\\([^)]+\\)\\s*\\n([\\s\\S]*?)(?=^## \\d|(?![^]))", "m");
+    // Match the version header and capture everything until the next version header or end of file. The changelog format is "## 1.0.8 (date)". The end-of-string
+    // sentinel uses (?![^]) instead of $ because the m flag makes $ match end-of-line, which would stop the non-greedy *? at the first line.
+    const pattern = new RegExp("^## " + version.replaceAll(".", "\\.") + "\\s+\\([^)]+\\)\\s*\\n([\\s\\S]*?)(?=^## \\d|(?![^]))", "m");
     const match = changelog.match(pattern);
     if (!match) {
         return null;
     }
     // Clean up the entry: trim whitespace and remove leading/trailing blank lines.
-    return match[1].trim();
+    return match[1]?.trim() ?? null;
 }
 /**
  * Checks for updates and caches the results.
@@ -129,8 +116,8 @@ function extractVersionChangelog(changelog, version) {
  */
 export async function checkForUpdates(currentVersion, force = false) {
     const now = Date.now();
-    // Skip if we checked recently (within 1 minute) to avoid duplicate checks on startup, unless forced.
-    if (!force && ((now - lastCheckTime) < 60000)) {
+    // Skip when a check fired within the debounce window so duplicate startup paths collapse to one network request, unless force=true bypasses the guard.
+    if (!force && ((now - lastCheckTime) < UPDATE_CHECK_DEBOUNCE)) {
         return;
     }
     lastCheckTime = now;